Back to Details

ai-sdlc-host-adapter

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

ai-sdlc-host-adapter: Portable Host Negotiation

ai-sdlc-host-adapter: 可移植主机协商

Internal AI SDLC skill, not client-facing by default. Negotiation describes host behavior; it never invokes the host.
内部AI SDLC技能，默认不面向客户。 协商仅描述主机行为；绝不会调用主机。

0. Skill Card

0. 技能卡片

  • Skill name: 
    ai-sdlc-host-adapter
  • Primary audience: Dev, Delivery, Architecture
  • Supporting audience: Security, QA
  • Audience tags: Dev, Delivery, Architecture, Security
  • SDLC stage: Portable execution handoff
  • Purpose: Preserve workflow semantics across hosts with explicit mappings and safe fallbacks.
  • Output: 
    _ai_sdlc/adapters/<adapter-id>/negotiation.{toon,json,md}
  • 技能名称：
    ai-sdlc-host-adapter
  • 主要受众：开发人员、交付人员、架构师
  • 支持受众：安全人员、QA人员
  • 受众标签：开发、交付、架构、安全
  • SDLC阶段：可移植执行交接
  • 用途：通过显式映射和安全降级方案，在不同主机间保留工作流语义。
  • 输出：
    _ai_sdlc/adapters/<adapter-id>/negotiation.{toon,json,md}

0.1 Required Inputs

0.1 必需输入

  • Versioned adapter manifest and capability request.
  • Exact portable operations, required capabilities, isolation need, and desired concurrency.
  • 带版本的适配器清单和能力请求。
  • 明确的可移植操作、必需能力、隔离需求及期望并发量。

0.2 Clarification Rules

0.2 澄清规则

  • Ask when required semantics or host operation identity is ambiguous.
  • Reject unknown fields, duplicate operations, invalid API ranges, undeclared capabilities, or non-equivalent native mappings.
  • Never infer shell, filesystem, network, isolation, concurrency, or approval support.
  • 当必需语义或主机操作身份不明确时发起询问。
  • 拒绝未知字段、重复操作、无效API范围、未声明能力或非等效原生映射。
  • 绝不推断Shell、文件系统、网络、隔离、并发或审批支持情况。

0.2.1 Flow Mode Flags

0.2.1 流程模式标志

  • Support 
    --quick-flow
    and 
    --full-flow
    ; full flow takes precedence.
  • Both modes use identical compatibility and fallback rules.
  • Full flow reviews every mapping, limit, fallback, and unsupported requirement.
  • 支持
    --quick-flow
    和
    --full-flow
    ；全流程模式优先。
  • 两种模式使用完全相同的兼容性和降级规则。
  • 全流程模式会检查每一项映射、限制、降级方案及不支持的需求。

0.3 Output Rules

0.3 输出规则

  • Default to complete TOON with mappings, missing requirements, fallbacks, effective limits, compatibility, source fingerprint, and result fingerprint.
  • Return summaries directly in the Codex response.
  • Emit 
    ai-sdlc-handoff/v1
    with 
    result
    , 
    blockers
    , 
    next_required
    , and 
    next_optional
    ; actions include 
    reason
    , 
    command
    , and 
    expected_artifact
    .
  • Do not create 
    summary.txt
    , 
    *-summary.txt
    , or another standalone summary file.
  • 默认生成完整的TOON文件，包含映射、缺失需求、降级方案、有效限制、兼容性、源指纹及结果指纹。
  • 直接在Codex响应中返回摘要。
  • 输出
    ai-sdlc-handoff/v1
    格式，包含
    result
    、
    blockers
    、
    next_required
    和
    next_optional
    ；操作信息包含
    reason
    、
    command
    和
    expected_artifact
    。
  • 不要创建
    summary.txt
    、
    *-summary.txt
    或其他独立的摘要文件。

0.4 Artifact Routing

0.4 工件路由

  • Write negotiations only below 
    _ai_sdlc/adapters/<adapter-id>/
    .
  • Keep manifests in repository-owned visible paths or skill conformance fixtures.
  • Never mutate a manifest during negotiation.
  • 仅在
    _ai_sdlc/adapters/<adapter-id>/
    路径下写入协商结果。
  • 将清单保存在仓库所属的可见路径或技能一致性测试夹具中。
  • 协商过程中绝不修改清单。

0.5 Feature State Machine

0.5 特性状态机

  • Read owning feature 
    _ai_sdlc/state.toon
    before execution handoff.
  • Negotiation does not advance feature or runtime state.
  • 在执行交接前读取所属特性的
    _ai_sdlc/state.toon
    文件。
  • 协商不会推进特性或运行时状态。

0.6 Artifact Metadata And Metatags

0.6 工件元数据与元标签

  • Related Markdown uses canonical 
    artifact_metadata
    and 
    metatags
    .
  • Machine records use versioned adapter, request, and negotiation schemas.
  • 相关Markdown文件使用标准的
    artifact_metadata
    和
    metatags
    。
  • 机器记录使用带版本的适配器、请求和协商模式。

0.7 Specs Index

0.7 规范索引

  • Read 
    _ai_sdlc/specs-index.toon
    first and use 
    specs-index.md
    for human review.
  • Negotiation does not refresh either index.
  • 首先读取
    _ai_sdlc/specs-index.toon
    ，并使用
    specs-index.md
    供人工审核。
  • 协商不会刷新任何一个索引。

References

参考资料

  • Read 
    references/adapter-contract.md
    before adding a mapping or fallback.
  • Validate manifests and requests with the JSON schemas in 
    references/
    .
  • Use 
    scripts/adapter.py
    for validation and negotiation.
  • Use 
    references/fixtures/
    only as contract conformance hosts, not claims about products.
  • 在添加映射或降级方案前，先阅读
    references/adapter-contract.md
    。
  • 使用
    references/
    目录下的JSON模式验证清单和请求。
  • 使用
    scripts/adapter.py
    进行验证和协商。
  • 仅将
    references/fixtures/
    用作合同一致性测试主机，而非产品声明。

Script Usage

脚本使用

bash
python3 skills/ai-sdlc-host-adapter/scripts/adapter.py . --adapter adapter.json --validate
python3 skills/ai-sdlc-host-adapter/scripts/adapter.py . --adapter adapter.json --negotiate --request request.json --write
bash
python3 skills/ai-sdlc-host-adapter/scripts/adapter.py . --adapter adapter.json --validate
python3 skills/ai-sdlc-host-adapter/scripts/adapter.py . --adapter adapter.json --negotiate --request request.json --write

Purpose

用途

Keep workflow meaning portable while making host limitations and fallbacks explicit.
在明确主机限制和降级方案的同时，保持工作流含义的可移植性。

Steps

步骤

  1. Validate manifest identity, API range, unique capabilities, mappings, and limits.
  2. Validate the exact capability request.
  3. Prefer equivalent native mappings.
  4. Use only registered deterministic fallbacks whose prerequisites are supported.
  5. Reduce concurrency or isolation to sequential execution with exact reasons.
  6. Fail incompatible when a required operation or capability has no safe mapping.
  7. Emit a complete TOON-first negotiation without invoking host operations.
  1. 验证清单标识、API范围、唯一能力、映射及限制。
  2. 验证明确的能力请求。
  3. 优先选择等效的原生映射。
  4. 仅使用已注册且满足前提条件的确定性降级方案。
  5. 降低并发量或隔离级别至顺序执行，并给出明确原因。
  6. 当必需操作或能力无安全映射时，判定为不兼容并终止。
  7. 生成完整的TOON优先协商结果，且不调用主机操作。

Output Spec

输出规范

The negotiation records native and fallback mappings, unsupported operations, missing capabilities, requested and effective limits, compatibility, reasons, and deterministic fingerprints.
Quality gate:
  • Pass only when every required operation and capability has an equivalent mapping or registered semantic-preserving fallback.
  • Fail closed when host behavior would change workflow semantics.
协商记录包含原生和降级映射、不支持的操作、缺失的能力、请求及有效限制、兼容性、原因及确定性指纹。
质量门：
  • 仅当所有必需操作和能力都有等效映射或已注册的语义保留降级方案时，判定为通过。
  • 当主机行为会改变工作流语义时，判定为失败并终止。

Scope Boundary

范围边界

  • Do not execute host operations, commands, hooks, or approvals.
  • Do not claim capabilities not declared by the adapter.
  • Do not silently drop workflow steps or required gates.
  • 不执行主机操作、命令、钩子或审批流程。
  • 不声明适配器未定义的能力。
  • 不静默丢弃工作流步骤或必需关卡。