架构定位

Harness 与治理

用运行环境控制工具、权限、副作用、预算、人工确认、恢复和平台差异。

谁控制权限、运行环境、副作用、平台适配和恢复？

概念校准

Harness

它是什么: 承载模型、工具、状态、权限、日志、预算、人工确认和恢复的运行控制环境。
它不是什么: 它能限制风险并保留证据，但不能直接阻止模型产生幻觉。

Skill

它是什么: 包含指令、资源、适用边界、版本和兼容信息的可复用能力包。
它不是什么: 不等于一段 Prompt，也不意味着其中脚本可以被无条件执行。

工具

它是什么: Agent 可通过明确参数、权限和结果合同调用的受约束能力。
它不是什么: 工具不等于 MCP；本地函数、命令或 HTTP 客户端也可以是工具。

多平台适配与迁移

建立 Codex、Claude Code、WorkBuddy 的能力模型、目录和权限适配器。

本章只做一件事同一 Forge Skill 在三个平台通过兼容测试。

开始前，Forge 已经具备已完成 Module 14 的“身份、权限、安全与供应链”，其通过验收的 solution 是本章起点。

完成后，Forge 将能够让同一个 Forge Skill 通过适配器部署到三个平台。

卡住时的最小恢复点先输出平台差异报告，不执行安装或写入。

下载本章实验仓库Python 3.12 · pytest · Pydantic · SQLite · deterministic Mock

阶段能力链

01用平台无关合同描述 Skill 需要的工具、资源和确认能力02把规范 Skill 合同映射为 Codex 目录、工具声明和确认策略03生成 Claude Code 命令白名单，并拒绝无法表达的必需能力04将能力映射到 WorkBuddy 工作区权限，并保留只读与写入的差异05把三个平台的安装计划规范化为可比较、可审计的配置记录06区分阻塞缺失和可接受降级，并生成可解释的平台兼容报告07用统一合同检查安装路径、权限不升级和能力覆盖，阻止不安全适配器发布

每一步只增加一种可验证能力；后一步建立在前一步已经通过的代码和测试上。

概念校准\n\n在开始操作代码前，先把本章涉及的概念放回正确的工程边界。\n\n
\n\n### Harness harness\n\n- 它是什么: 承载模型、工具、状态、权限、日志、预算、人工确认、隔离和恢复的运行控制环境。\n- 它不是什么: 它可以缩小风险、拒绝动作并保留证据，但不能保证模型输出永远正确，也不能代替领域验收。\n- 与相邻概念的关系: Agent Loop 在 Harness 中运行；Tool、Memory 和 MCP 连接受其策略约束；Observability 记录过程，Evaluation 判断行为。\n- 在 HeatStack Forge 中的位置: Forge Harness 管理工作目录、工具、确认队列、预算、Checkpoint、审计日志和回滚，把模型建议与真实副作用分开。\n- 典型误用与修正: 误用是把系统提示词当成安全边界。修正方法是把权限、路径、网络、密钥、预算和回滚落实在模型之外的控制中。\n\n### Skill skill\n\n- 它是什么: 包含指令、资源、适用边界、版本和兼容元数据的可复用能力包，可被 Agent 平台发现、安装或引用。\n- 它不是什么: 它不等于一段 Prompt，也不代表附带脚本可以自动执行；实际执行仍受平台、工具合同和权限策略约束。\n- 与相邻概念的关系: Prompt 可以是 Skill 的一部分，Tool 可以被 Skill 引用，Harness 决定安装与运行边界，适配器处理平台差异。\n- 在 HeatStack Forge 中的位置: Forge 将需求抽取能力打包为带 Manifest、测试、资源清单和风险说明的 Skill，并适配三个目标平台。\n- 典型误用与修正: 误用是复制一个 Prompt 文件就宣称跨平台兼容。修正方法是声明依赖、入口、资源、版本、权限与验收测试。\n\n### 工具 tool\n\n- 它是什么: Agent 可通过明确参数、权限、执行边界和结果合同调用的受约束能力，例如函数、命令、数据库查询或 HTTP 客户端。\n- 它不是什么: 工具不等于 MCP，也不等于任意脚本。协议可以暴露能力，但 Harness 仍决定是否允许调用及如何处理副作用。\n- 与相邻概念的关系: Agent Loop 选择工具，Schema 约束参数，Harness 执行权限检查和隔离，Verification 检查结果是否推进目标。\n- 在 HeatStack Forge 中的位置: Forge 的 tool registry 保存合同与风险等级；执行前生成变更计划，高风险写操作等待确认，执行后记录结果与恢复信息。\n- 典型误用与修正: 误用是让模型根据工具名称自由拼参数。修正方法是严格 Schema、确定性校验、超时、幂等键和拒绝分支测试。\n\n

STAGE 01

用平台无关合同描述 Skill 需要的工具、资源和确认能力

先看一个具体问题

如何声明 Skill 需要哪些能力，并区分必需与可选？

你正在为 Forge 平台构建跨平台适配层，需要让同一个 Skill 在不同平台上安装时能够判断该平台是否满足其能力需求。

当前代码库中还没有 forge/adapters 包，也没有任何能力模型，因此测试 test_required_capabilities_are_reported 和 test_optional_capability_is_not_a_blocker 在导入阶段就失败了。

你需要创建一个平台无关的合同模型，用 CapabilityRequirement 表示单个能力需求（包含名称和是否必需），用 SkillContract 表示一个 Skill 的全部能力需求，并实现 missing_capabilities 函数来计算缺失的必需能力。

关键决策是：当某个能力被标记为可选时，即使平台没有提供该能力，也不应该阻止安装。

先做判断

在实现 required_names 方法时，以下哪种做法能正确区分必需与可选能力？

返回所有能力名称，不管 required 标志。
只返回 required=True 的能力名称。
只返回 required=False 的能力名称。
返回能力名称和 required 标志的元组。

判断依据: 正确做法是只返回 required=True 的能力名称，因为 missing_capabilities 只应报告缺失的必需能力，可选能力缺失不应成为安装障碍。

它是什么

平台无关能力合同是什么

平台无关能力合同是一组数据结构，用于声明一个 Skill 在运行时需要哪些外部能力，而不关心这些能力在具体平台上如何实现。

CapabilityRequirement 封装了能力名称和一个布尔标志 required，默认值为 True，表示该能力是必需的。

SkillContract 聚合了一个 Skill 的所有能力需求，并提供 required_names 方法来提取所有必需能力的名称集合。

missing_capabilities 函数接收一个合同和一个可用能力集合，返回所有缺失的必需能力。

它不是什么

平台无关能力合同不是什么

它不是平台映射表，不负责将能力名称转换为具体平台的 API 或配置。

它也不是安装器，不会执行任何安装逻辑或检查平台是否真的具备这些能力。

它不包含任何平台特定的实现细节，只描述需求本身。

它与相邻概念的关系

合同内部各组件的关系

SkillContract 包含多个 CapabilityRequirement，每个需求都有名称和必需标志。

required_names 方法遍历所有需求，过滤出 required=True 的项，并返回它们的名称集合。

missing_capabilities 调用 required_names 得到必需能力集合，然后与可用能力集合做差集，得到缺失的必需能力。

本阶段的边界决定: 合同模型只负责描述需求，不负责平台映射或安装；判断平台是否满足需求由 missing_capabilities 完成，但实际安装决策由上层 Harness 根据缺失能力集合做出。

实验 ID: platform-adapters-01-canonical-capability-model
输入: 软件交付：为前端仓库增加功能、修改代码并补测试。
证据目录: evidence/platform-adapters/01-canonical-capability-model/
验收: 待验收

教师示范

目标: 演示如何定义 CapabilityRequirement 和 SkillContract，并实现 missing_capabilities 以正确区分必需与可选能力。

假设我们有一个代码审查 Skill，它需要 read_files 能力来读取代码，而 git 能力是可选的，用于直接操作版本控制。

我们首先定义 CapabilityRequirement 数据类，包含 name 和 required 字段，其中 required 默认为 True。

然后定义 SkillContract 数据类，包含 skill_id 和 capabilities 元组，并实现 required_names 方法，只返回 required=True 的能力名称。

最后实现 missing_capabilities 函数，它接收合同和可用能力集合，返回必需能力集合与可用能力集合的差集。

实施步骤

创建 forge/adapters/__init__.py 文件，内容为 """Cross-platform adapter contracts."""。
创建 forge/adapters/capabilities.py 文件，导入 dataclass。
定义 CapabilityRequirement 数据类，使用 @dataclass(frozen=True) 装饰，包含 name: str 和 required: bool = True。
定义 SkillContract 数据类，包含 skill_id: str 和 capabilities: tuple[CapabilityRequirement, ...]。
在 SkillContract 中实现 required_names 方法，返回 frozenset(item.name for item in self.capabilities if item.required)。
定义 missing_capabilities 函数，返回 contract.required_names() - available。

真实 solution 代码: forge/adapters/__init__.py

"""Cross-platform adapter contracts."""

真实 solution 代码: forge/adapters/capabilities.py

from dataclasses import dataclass

@dataclass(frozen=True)
class CapabilityRequirement:
    name: str
    required: bool = True

@dataclass(frozen=True)
class SkillContract:
    skill_id: str
    capabilities: tuple[CapabilityRequirement, ...]

    def required_names(self) -> frozenset[str]:
        return frozenset(item.name for item in self.capabilities if item.required)

def missing_capabilities(contract: SkillContract, available: set[str]) -> frozenset[str]:
    return contract.required_names() - available

python -m pytest -q tests/test_stage.py

运行真实测试

..                                                                       [100%]
2 passed in <duration>s

为什么这样实现

required_names 方法中的 if item.required 条件确保只有必需能力被包含，可选能力被忽略。

missing_capabilities 使用集合差集操作，从必需能力集合中减去可用能力集合，得到缺失的必需能力。

当可用能力集合包含所有必需能力时，差集为空集，表示没有缺失的必需能力。

带提示练习

补全 required_names 方法，使其只返回标记为 required 的能力名称。

打开 forge/adapters/capabilities.py 文件。
找到 SkillContract 类中的 required_names 方法。
修改方法体，在生成器表达式中添加 if item.required 条件。
保存文件并运行测试命令。

逐级提示

提示1：生成器表达式目前是 item.name for item in self.capabilities，需要添加过滤条件。
提示2：过滤条件应该检查 item.required 是否为真。
提示3：修改后应为 item.name for item in self.capabilities if item.required。

完成标准

required_names 方法返回的集合只包含 required=True 的能力名称。
运行 python -m pytest -q tests/test_stage.py 后两个测试均通过。

故障注入与排查

在故障实验室中，我们提供了一个有缺陷的 forge/adapters/capabilities.py 实现，其中 required_names 方法忽略了 required 标志，返回所有能力名称。运行测试 test_optional_capability_is_not_a_blocker 时，由于可选能力 git 被错误地视为必需，导致断言失败。你需要诊断并修复这个缺陷。

本阶段已经建立了能力合同模型，并明确了必需与可选能力的区别。通过检查 required_names 方法的实现，可以定位到缺陷在于没有过滤 required 标志。修复方法是在生成器表达式中添加 if item.required 条件，使方法只返回必需能力。

已验证的故障合同

目标测试: test_optional_capability_is_not_a_blocker
故障文件: forge/adapters/capabilities.py

诊断顺序

运行故障命令 python -m pytest -q ../tests/test_stage.py::test_optional_capability_is_not_a_blocker，观察测试失败。
查看失败输出，发现 missing_capabilities 返回了 frozenset({'git'})，而预期是空集。
检查 forge/adapters/capabilities.py 中的 required_names 方法，发现它返回所有能力名称，没有检查 required 标志。
确认缺陷：required_names 方法中的生成器表达式缺少 if item.required 条件。

修复原则: 修改 required_names 方法，在生成器表达式中添加 if item.required 条件，使其只返回必需能力名称。修改后的代码为：return frozenset(item.name for item in self.capabilities if item.required)。

python -m pytest -q ../tests/test_stage.py::test_optional_capability_is_not_a_blocker

迁移挑战

办公研究场景中，你需要为一个“文档审阅”技能建模。该技能需要 read_files 能力来读取文档，而 git 能力是可选的，用于版本控制集成。

改变的条件: 将场景从软件交付的代码审查技能改为办公研究的文档审阅技能，并调整能力需求：read_files 必需，git 可选。

使用 CapabilityRequirement 和 SkillContract 为“文档审阅”技能创建合同，其中 read_files 必需，git 可选。然后调用 missing_capabilities 函数，传入可用能力集合 {"read_files"}，验证返回空集。

完成标准

创建的 SkillContract 包含两个 CapabilityRequirement：read_files 的 required=True，git 的 required=False。
调用 missing_capabilities(contract, {"read_files"}) 返回 frozenset()，表示没有缺失的必需能力。

运行真实测试

python -m pytest -q tests/test_stage.py

运行真实测试

..                                                                       [100%]
2 passed in <duration>s

设计解释题: 为什么 required_names 方法需要检查 required 标志？如果它返回所有能力名称，会对平台兼容性判断产生什么影响？

一个有力回答应包含

required_names 方法检查 required 标志是为了区分必需能力和可选能力，确保只有必需能力被用于缺失计算。
如果返回所有能力名称，可选能力缺失也会被报告为缺失，导致平台被错误地判定为不兼容，阻止安装。

掌握证据

通过 test_required_capabilities_are_reported 和 test_optional_capability_is_not_a_blocker 两个测试。
能够解释 required_names 方法中 if item.required 条件的作用，以及为什么可选能力缺失不应阻止安装。
在办公场景中成功创建合同并验证 missing_capabilities 返回空集。

STAGE 02

把规范 Skill 合同映射为 Codex 目录、工具声明和确认策略

先看一个具体问题

从规范合同到 Codex 安装计划

你需要在 forge/adapters/codex.py 中实现 plan_codex 函数，把 SkillContract 转换为 CodexInstallPlan。

当前测试 test_codex_path_and_tools_are_mapped 和 test_codex_write_approval_is_preserved 都失败，因为模块尚未创建。

关键决策是：目标路径必须符合 Codex 的 skills/<skill_id>/SKILL.md 结构，工具列表必须来自合同要求，审批模式必须固定为 ask-before-writes。

如果审批模式被错误地设为 full-access，就会绕过写操作前的确认，导致权限提升。

先做判断

在实现 plan_codex 时，审批模式应该如何处理？

根据可用能力动态决定
始终设为 ask-before-writes
设为 full-access 以简化安装
由调用者传入参数

判断依据: 正确选项是“始终设为 ask-before-writes”。适配器必须保留安全语义，不能因为平台差异而提升权限。

它是什么

适配器是安全语义的翻译器

适配器把规范合同中的能力要求映射为平台特定的安装计划，同时保持权限边界不变。

对于 Codex，这意味着生成正确的目录路径、工具声明和审批模式。

审批模式 ask-before-writes 确保任何写操作前都需要用户确认，这是合同隐含的安全要求。

它不是什么

适配器不是权限决策者

适配器不能随意更改权限模式，即使安装成功也不能提升权限。

它不负责执行安装，也不验证平台是否真正遵守审批模式。

适配器只是生成计划，实际执行由 Harness 控制。

它与相邻概念的关系

合同、适配器与 Harness 的关系

SkillContract 定义能力要求，适配器将其转换为平台计划，Harness 负责执行并强制权限。

missing_capabilities 函数用于检查可用能力是否满足合同，不满足时应抛出异常。

目标路径由 home 和 skill_id 拼接，工具列表来自合同的 required_names()。

本阶段的边界决定: 适配器必须保持安全语义，不能提升权限；审批模式固定为 ask-before-writes，即使平台支持更宽松的模式。

实验 ID: platform-adapters-02-codex-adapter
输入: 软件交付：为前端仓库增加功能、修改代码并补测试。
证据目录: evidence/platform-adapters/02-codex-adapter/
验收: 待验收

教师示范

目标: 演示如何实现 plan_codex 生成正确的目标路径、工具列表和审批模式。

首先创建 forge/adapters/codex.py 文件，定义 CodexInstallPlan 数据类和 plan_codex 函数。

在函数中，调用 missing_capabilities 检查合同要求的能力是否都可用，如果有缺失则抛出 ValueError。

然后构造 CodexInstallPlan，目标路径为 {home}/skills/{skill_id}/SKILL.md，工具列表为排序后的合同要求名称，审批模式为 ask-before-writes。

实施步骤

创建文件 forge/adapters/codex.py。
导入 dataclass 和 SkillContract, missing_capabilities。
定义 CodexInstallPlan 数据类，包含 target_path、tools、approval_mode 字段。
实现 plan_codex 函数，检查缺失能力并返回计划。

真实 solution 代码: forge/adapters/codex.py

from dataclasses import dataclass
from forge.adapters.capabilities import SkillContract, missing_capabilities

@dataclass(frozen=True)
class CodexInstallPlan:
    target_path: str
    tools: tuple[str, ...]
    approval_mode: str

def plan_codex(contract: SkillContract, available: set[str], home: str) -> CodexInstallPlan:
    missing = missing_capabilities(contract, available)
    if missing:
        raise ValueError("Codex missing capabilities: " + ", ".join(sorted(missing)))
    if not home or ".." in home.replace("\\", "/").split("/"):
        raise ValueError("unsafe Codex home")
    return CodexInstallPlan(f"{home.rstrip('/')}/skills/{contract.skill_id}/SKILL.md", tuple(sorted(contract.required_names())), "ask-before-writes")

python -m pytest -q tests/test_stage.py

运行真实测试

..                                                                       [100%]
2 passed in <duration>s

为什么这样实现

目标路径使用 home 和 skill_id 拼接，确保符合 Codex 的目录结构。

工具列表来自 contract.required_names()，排序后保持确定性。

审批模式硬编码为 ask-before-writes，保留安全语义。

带提示练习

修正 plan_codex 中的审批模式，使其始终为 ask-before-writes。

打开 forge/adapters/codex.py。
找到返回 CodexInstallPlan 的语句。
将 approval_mode 参数从 full-access 改为 ask-before-writes。
运行测试确认通过。

逐级提示

审批模式是 CodexInstallPlan 的第三个字段。
安全边界要求写操作前必须确认。
不要根据可用能力动态改变审批模式。

完成标准

test_codex_write_approval_is_preserved 通过。
plan_codex 返回的 approval_mode 为 ask-before-writes。

故障注入与排查

在故障夹具 fixtures/failure.json 中，forge/adapters/codex.py 的 plan_codex 函数将审批模式硬编码为 full-access，导致测试 test_codex_write_approval_is_preserved 失败。你需要诊断并修复这个权限提升缺陷。

本阶段已经学习了适配器必须保留安全语义，不能提升权限。通过检查 plan_codex 的返回值，可以发现审批模式被错误地设置为 full-access，而正确值应为 ask-before-writes。修复该缺陷需要将硬编码的字符串改为正确的审批模式。

已验证的故障合同

目标测试: test_codex_write_approval_is_preserved
故障文件: forge/adapters/codex.py

诊断顺序

运行故障命令 python -m pytest -q ../tests/test_stage.py::test_codex_write_approval_is_preserved，观察断言失败。
查看 forge/adapters/codex.py 中 plan_codex 的返回语句，发现 approval_mode 被设为 full-access。
对比规范合同的安全要求，确认审批模式应为 ask-before-writes。
修改代码，将 full-access 改为 ask-before-writes。

修复原则: 在 forge/adapters/codex.py 的 plan_codex 函数中，将返回的 CodexInstallPlan 的 approval_mode 字段从 full-access 改为 ask-before-writes。这样生成的安装计划会要求写操作前确认，保留安全语义。

python -m pytest -q ../tests/test_stage.py::test_codex_write_approval_is_preserved

迁移挑战

音乐场景中，你需要为“发布计划”技能生成 Codex 安装计划。该技能要求 write_files 能力，可用能力集合包含 write_files 和 read_files。

改变的条件: 将技能从安全审查场景改为音乐发布计划场景，并改变能力要求为 write_files。

使用 plan_codex 函数，为技能 ID release-planning 生成 Codex 安装计划。传入可用能力集合 {"write_files", "read_files"} 和 home 路径 C:/Users/dev/.codex。验证生成的计划中目标路径以 /skills/release-planning/SKILL.md 结尾，工具列表包含 write_files，且审批模式为 ask-before-writes。

完成标准

计划的目标路径以 /skills/release-planning/SKILL.md 结尾。
计划的工具列表包含 write_files。
计划的审批模式为 ask-before-writes。

运行真实测试

python -m pytest -q tests/test_stage.py

运行真实测试

..                                                                       [100%]
2 passed in <duration>s

设计解释题: 为什么 Codex 适配器必须保留 ask-before-writes 审批模式，而不能根据平台能力动态调整？

一个有力回答应包含

审批模式是安全语义的一部分，适配器不能提升权限。
动态调整可能导致写操作未经确认，增加风险。
保留固定审批模式确保跨平台行为一致。

掌握证据

通过 test_codex_path_and_tools_are_mapped 和 test_codex_write_approval_is_preserved 两个测试。
能够解释为什么适配器必须保留 ask-before-writes 审批模式，不能提升权限。
在音乐场景的转移挑战中，正确生成包含 write_files 工具且审批模式为 ask-before-writes 的 Codex 安装计划。

STAGE 03

生成 Claude Code 命令白名单，并拒绝无法表达的必需能力

先看一个具体问题

为 Claude Code 平台生成命令白名单，并拒绝无法表达的必需能力

当前仓库中只有 Codex 适配器，还没有 Claude 适配器，因此测试在导入 forge.adapters.claude 时直接失败。

你需要新建 forge/adapters/claude.py，实现 plan_claude 函数，将技能契约中的能力需求映射为 Claude Code 允许的工具列表。

如果某个必需能力无法在 Claude Code 中表达，适配器必须抛出 ValueError，而不是默认映射到通用 shell 访问。

本阶段的目标是让两个测试通过：test_known_capabilities_map_to_tools 和 test_unknown_required_capability_is_rejected。

先做判断

当适配器遇到一个无法映射到 Claude Code 工具的必需能力时，最安全的做法是什么？

默认映射到 Bash，因为 Bash 可以执行任何命令
抛出异常，拒绝生成计划
忽略该能力，继续生成计划
记录警告并映射到只读工具

判断依据: 正确选项是“抛出异常，拒绝生成计划”。因为默认映射到 Bash 会扩大权限，可能让模型执行未预期的操作；忽略能力会导致技能无法正常工作；映射到只读工具同样不准确。适配器必须明确拒绝无法表达的必需能力，以保证安全性和语义正确性。

它是什么

显式能力映射表

显式能力映射表是一个从能力名称到平台工具名称的字典，例如 {"read_files": "Read", "write_files": "Edit", "shell": "Bash"}。

适配器只允许映射表中列出的能力，任何不在表中的能力都被视为无法表达，必须拒绝。

这种设计让能力边界清晰可见，避免意外扩大权限，也便于审计和测试。

它不是什么

不是通用 shell 访问的别名

显式映射表不是把未知能力默认映射到 Bash 的机制，那样会失去能力约束。

它也不是一个可以随意扩展的开放集合；添加新映射需要同时考虑平台是否真正支持该能力。

映射表只负责名称转换，不负责权限检查或执行隔离，这些由 Harness 层处理。

它与相邻概念的关系

与技能契约和平台计划的关系

技能契约（SkillContract）定义了技能需要哪些能力，适配器读取这些能力并转换为平台允许的工具列表。

plan_claude 返回的 ClaudePlan 包含技能文件路径和允许的工具元组，供后续部署使用。

如果契约中的能力不在映射表中，适配器通过 missing_capabilities 函数检测缺失并抛出 ValueError。

本阶段的边界决定: 适配器必须拒绝无法表达的必需能力，而不是扩大权限；这保证了平台计划的安全性和语义正确性。

实验 ID: platform-adapters-03-claude-code-adapter
输入: 软件交付：为前端仓库增加功能、修改代码并补测试。
证据目录: evidence/platform-adapters/03-claude-code-adapter/
验收: 待验收

教师示范

目标: 演示如何实现 plan_claude，使用显式映射表并拒绝未知必需能力。

我们首先定义映射表 CAPABILITY_TO_TOOL，将 read_files 映射到 Read，write_files 映射到 Edit，shell 映射到 Bash。

然后实现 plan_claude：先计算可表示的能力集合，再用 missing_capabilities 找出契约中缺失的能力。

如果有缺失，抛出包含缺失能力名称的 ValueError；否则生成排序后的工具元组并返回 ClaudePlan。

实施步骤

创建 forge/adapters/claude.py 文件。
定义 CAPABILITY_TO_TOOL 字典。
定义 ClaudePlan 数据类，包含 skill_path 和 allowed_tools。
实现 plan_claude 函数，检查缺失能力并抛出异常。
运行测试验证。

真实 solution 代码: forge/adapters/claude.py

from dataclasses import dataclass
from forge.adapters.capabilities import SkillContract, missing_capabilities

CAPABILITY_TO_TOOL = {"read_files":"Read", "write_files":"Edit", "shell":"Bash"}

@dataclass(frozen=True)
class ClaudePlan:
    skill_path: str
    allowed_tools: tuple[str, ...]

def plan_claude(contract: SkillContract, root: str) -> ClaudePlan:
    representable = set(CAPABILITY_TO_TOOL)
    missing = missing_capabilities(contract, representable)
    if missing:
        raise ValueError("Claude adapter cannot represent: " + ", ".join(sorted(missing)))
    tools = tuple(sorted(CAPABILITY_TO_TOOL[name] for name in contract.required_names()))
    return ClaudePlan(f"{root.rstrip('/')}/.claude/skills/{contract.skill_id}/SKILL.md", tools)

python -m pytest -q tests/test_stage.py

运行真实测试

..                                                                       [100%]
2 passed in <duration>s

为什么这样实现

映射表是显式的，只有列出的能力才会被接受，这避免了未知能力被意外映射到危险工具。

missing_capabilities 函数来自 capabilities.py，它比较契约需求和可表示集合，返回缺失的能力名称。

抛出 ValueError 而不是静默忽略，确保调用者能立即发现不兼容问题。

带提示练习

补全 CAPABILITY_TO_TOOL 映射，并添加对未知必需能力的拒绝逻辑。

在 forge/adapters/claude.py 中定义 CAPABILITY_TO_TOOL 字典，包含 read_files、write_files 和 shell 三个映射。
导入 missing_capabilities 函数。
在 plan_claude 中计算 representable 集合和 missing 集合。
如果 missing 非空，抛出 ValueError，消息包含 “cannot represent” 和缺失能力名称。
否则生成排序后的工具元组并返回 ClaudePlan。

逐级提示

提示1：missing_capabilities(contract, representable) 返回一个集合，包含契约中不在 representable 中的能力名称。
提示2：异常消息格式应为 "Claude adapter cannot represent: " + ", ".join(sorted(missing))。
提示3：工具元组需要排序，使用 sorted(CAPABILITY_TO_TOOL[name] for name in contract.required_names())。

完成标准

test_known_capabilities_map_to_tools 通过：对于只要求 read_files 的契约，allowed_tools 等于 ("Read",)。
test_unknown_required_capability_is_rejected 通过：对于要求 database_admin 的契约，抛出 ValueError 且消息包含 “cannot represent”。

故障注入与排查

当前 forge/adapters/claude.py 存在一个缺陷：未知能力被默认映射到 Bash，导致 test_unknown_required_capability_is_rejected 失败。测试期望适配器拒绝无法表达的能力，但实际却接受了 database_admin 并返回 Bash 工具。

本阶段已经介绍了显式映射表和拒绝未知能力的机制，因此你可以通过检查 plan_claude 中的映射逻辑来定位问题。故障夹具 fixtures/failure.json 明确指出缺陷是“使用 Bash 作为未知能力的默认映射”，修复方法就是改为拒绝缺失的能力。

已验证的故障合同

目标测试: test_unknown_required_capability_is_rejected
故障文件: forge/adapters/claude.py

诊断顺序

运行故障命令 python -m pytest -q ../tests/test_stage.py::test_unknown_required_capability_is_rejected，观察断言失败信息。
查看 forge/adapters/claude.py 中的 plan_claude 实现，发现 CAPABILITY_TO_TOOL.get(name, "Bash") 将未知能力默认映射为 Bash。
对比预期行为：未知能力应该导致 ValueError，而不是被映射。
修改代码，使用 missing_capabilities 检测缺失能力并抛出异常。

修复原则: 在 plan_claude 中，先计算 representable = set(CAPABILITY_TO_TOOL)，然后调用 missing_capabilities(contract, representable) 得到缺失能力集合。如果集合非空，抛出 ValueError("Claude adapter cannot represent: " + ", ".join(sorted(missing)))。否则，正常生成工具元组。

python -m pytest -q ../tests/test_stage.py::test_unknown_required_capability_is_rejected

迁移挑战

办公场景中有一个“文档审阅”技能，需要 read_files 和 write_files 能力。使用 plan_claude 为该技能生成计划，并验证 allowed_tools 包含 Read 和 Edit。

改变的条件: 将技能契约的能力需求从单一 read_files 改为同时要求 read_files 和 write_files，并验证生成的工具列表包含两个对应工具。

编写一个测试或脚本，创建 SkillContract("doc_review", (CapabilityRequirement("read_files"), CapabilityRequirement("write_files")))，调用 plan_claude(contract, "/work")，然后断言返回的 allowed_tools 等于 ("Edit", "Read")（注意排序）。

完成标准

生成的 allowed_tools 元组包含 Read 和 Edit，且顺序为 ("Edit", "Read")。
调用 plan_claude 时不会抛出异常，且返回的 ClaudePlan 实例的 skill_path 属性以 /work/.claude/skills/doc_review/SKILL.md 结尾。

运行真实测试

python -m pytest -q tests/test_stage.py

运行真实测试

..                                                                       [100%]
2 passed in <duration>s

设计解释题: 为什么不能将未知能力默认映射到 Bash？请从权限最小化和语义正确性的角度解释。

一个有力回答应包含

默认映射到 Bash 会授予模型执行任意命令的能力，违反权限最小化原则。
未知能力可能具有特定语义，映射到 Bash 会导致行为不符合预期，破坏技能契约。
显式拒绝可以让调用者尽早发现不兼容问题，避免在运行时出现意外。

掌握证据

通过 test_known_capabilities_map_to_tools 和 test_unknown_required_capability_is_rejected 两个测试。
能够解释显式能力映射的重要性：它防止未知能力被意外映射到危险工具，保证适配器的安全性和语义正确性。
在办公场景的转移挑战中，成功为同时要求 read_files 和 write_files 的技能生成包含 Read 和 Edit 的计划。

STAGE 04

将能力映射到 WorkBuddy 工作区权限，并保留只读与写入的差异

先看一个具体问题

从能力需求推导 WorkBuddy 工作区访问级别

当前仓库中还没有 forge/adapters/workbuddy.py，因此测试在导入 plan_workbuddy 时直接失败，错误为 ModuleNotFoundError: No module named 'forge.adapters.workbuddy'。

本阶段需要创建该文件，实现 plan_workbuddy 函数，根据 Skill 的能力需求决定 WorkBuddy 工作区访问级别。

如果 Skill 需要 write_files 能力，则工作区访问级别应为 write；否则应保持 read，不能默认提升权限。

测试 test_write_skill_receives_write_access 和 test_read_only_skill_stays_read_only 分别验证写入和只读两种场景。

先做判断

在实现 plan_workbuddy 之前，请预测：如果适配器总是请求写入权限，会发生什么？

所有 Skill 都能正常工作，因为写入权限更强大。
只读 Skill 会意外获得写入权限，违反最小权限原则。
测试会全部通过，因为测试不检查权限级别。
适配器会抛出异常，因为无法处理只读 Skill。

判断依据: 正确答案是第二个选项。如果适配器总是请求写入权限，只读 Skill 会意外获得写入权限，这违反了最小权限原则，并且测试 test_read_only_skill_stays_read_only 会失败。

它是什么

WorkBuddy 适配器是什么

WorkBuddy 适配器是一个将 Skill 的能力需求映射到 WorkBuddy 工作区访问级别的组件。

它接收 SkillContract 对象，检查其中是否包含 write_files 能力，然后生成一个 WorkBuddyPlan，其中包含配置路径和访问级别。

适配器必须根据能力需求推导访问级别，而不是硬编码为 write 或 read。

它不是什么

WorkBuddy 适配器不是什么

它不是一个通用的权限管理系统，也不负责执行实际的写入操作。

它不会自动提升权限，也不会忽略 Skill 的能力需求。

它不处理 shell 能力，如果检测到 shell 能力，会抛出 ValueError，因为 WorkBuddy 配置文件不暴露 shell。

它与相邻概念的关系

与其他组件的关系

plan_workbuddy 依赖于 SkillContract 的 required_names() 方法来获取能力名称集合。

WorkBuddyPlan 是一个冻结的数据类，包含 config_path 和 workspace_access 两个字段。

测试文件 tests/test_stage.py 导入 plan_workbuddy 并验证其行为，因此适配器必须与测试期望一致。

本阶段的边界决定: 适配器必须根据 write_files 能力是否存在来决定访问级别，不能默认提升权限；同时要拒绝 shell 能力，因为 WorkBuddy 不支持 shell。

实验 ID: platform-adapters-04-workbuddy-adapter
输入: 软件交付：为前端仓库增加功能、修改代码并补测试。
证据目录: evidence/platform-adapters/04-workbuddy-adapter/
验收: 待验收

教师示范

目标: 演示如何实现 plan_workbuddy，根据 write_files 能力决定访问级别。

首先，我们需要创建 forge/adapters/workbuddy.py 文件，并定义 WorkBuddyPlan 数据类和 plan_workbuddy 函数。

在函数内部，我们调用 contract.required_names() 获取能力名称集合，然后检查是否包含 write_files。

如果包含，则访问级别为 write，否则为 read。同时，如果检测到 shell 能力，则抛出 ValueError。

最后，返回一个 WorkBuddyPlan 实例，其中配置路径为 {workspace}/.workbuddy/{skill_id}.json，注意去除工作区路径末尾的斜杠。

实施步骤

创建 forge/adapters/workbuddy.py 文件。
导入 dataclass 和 SkillContract。
定义 WorkBuddyPlan 数据类，包含 config_path 和 workspace_access 字段。
实现 plan_workbuddy 函数，获取能力名称集合，检查 shell 和 write_files，返回相应的计划。

真实 solution 代码: forge/adapters/workbuddy.py

from dataclasses import dataclass
from forge.adapters.capabilities import SkillContract

@dataclass(frozen=True)
class WorkBuddyPlan:
    config_path: str
    workspace_access: str

def plan_workbuddy(contract: SkillContract, workspace: str) -> WorkBuddyPlan:
    required = contract.required_names()
    if "shell" in required:
        raise ValueError("WorkBuddy profile does not expose shell")
    access = "write" if "write_files" in required else "read"
    return WorkBuddyPlan(f"{workspace.rstrip('/')}/.workbuddy/{contract.skill_id}.json", access)

python -m pytest -q tests/test_stage.py

运行真实测试

..                                                                       [100%]
2 passed in <duration>s

为什么这样实现

contract.required_names() 返回一个集合，包含 Skill 所需的所有能力名称。

通过检查 "write_files" in required，我们可以判断 Skill 是否需要写入权限。

如果检测到 shell 能力，我们抛出 ValueError，因为 WorkBuddy 配置文件不支持 shell。

配置路径使用 workspace.rstrip('/') 确保路径末尾没有多余的斜杠。

带提示练习

修正 plan_workbuddy，使其在缺少 write_files 时返回 read 访问。

打开 forge/adapters/workbuddy.py 文件。
检查 plan_workbuddy 函数中访问级别的赋值逻辑。
确保当 write_files 不在能力集合中时，访问级别为 read。
运行测试 python -m pytest -q tests/test_stage.py 验证修复。

逐级提示

提示1：使用条件表达式 access = "write" if "write_files" in required else "read"。
提示2：不要忘记检查 shell 能力并抛出异常。
提示3：确保配置路径正确拼接，使用 workspace.rstrip('/')。

完成标准

测试 test_write_skill_receives_write_access 通过。
测试 test_read_only_skill_stays_read_only 通过。

故障注入与排查

在故障夹具 fixtures/failure.json 中，forge/adapters/workbuddy.py 被注入了一个缺陷：plan_workbuddy 总是返回 workspace_access="write"，忽略了 Skill 的实际能力需求。运行测试 test_read_only_skill_stays_read_only 时，断言失败，因为只读 Skill 得到了写入权限。

本阶段已经学习了如何根据能力需求推导访问级别，因此可以识别出适配器忽略了能力集合，并修复为根据 write_files 是否存在来决定访问级别。本阶段的 forge/adapters/workbuddy.py 实现直接受 test_read_only_skill_stays_read_only 约束，因此可以用已验证的边界机制定位这个故障。

已验证的故障合同

目标测试: test_read_only_skill_stays_read_only
故障文件: forge/adapters/workbuddy.py

诊断顺序

运行故障测试命令 python -m pytest -q ../tests/test_stage.py::test_read_only_skill_stays_read_only，观察断言失败。
查看 forge/adapters/workbuddy.py 中的 plan_workbuddy 函数，发现它硬编码返回 "write"。
对比预期行为：应该检查 contract.required_names() 中是否包含 write_files。
修复函数，根据能力集合动态决定访问级别。

修复原则: 修改 plan_workbuddy 函数，使用 required = contract.required_names() 获取能力集合，然后设置 access = "write" if "write_files" in required else "read"，并保留对 shell 能力的检查。

python -m pytest -q ../tests/test_stage.py::test_read_only_skill_stays_read_only

迁移挑战

办公场景中有一个“只读报告”技能，它只需要 read_files 能力。请使用 plan_workbuddy 为该技能生成计划，并验证工作区访问级别为 read。

改变的条件: 将技能的能力需求从引导练习中的 write_files 能力改为只读文件能力，即仅包含 read_files，因此访问级别应为 read。

编写一个测试或脚本，创建一个 SkillContract，其能力需求仅包含 read_files，然后调用 plan_workbuddy，断言返回的 workspace_access 为 read。

完成标准

创建的 SkillContract 必须仅包含 read_files 能力。
调用 plan_workbuddy 后，返回的 workspace_access 必须为 read。
返回的 config_path 必须正确拼接工作区路径和技能 ID，且不包含末尾斜杠。

运行真实测试

python -m pytest -q tests/test_stage.py

运行真实测试

..                                                                       [100%]
2 passed in <duration>s

设计解释题: 为什么只读 Skill 不应该获得写入权限？如果适配器总是请求写入权限，会有什么后果？

一个有力回答应包含

只读 Skill 只需要读取文件，不需要修改文件，因此授予写入权限会扩大攻击面。
如果适配器总是请求写入权限，那么即使 Skill 不需要写入，它也可能意外修改文件，导致数据损坏或安全漏洞。
遵循最小权限原则，只授予完成任务所必需的最小权限。

掌握证据

通过测试 test_write_skill_receives_write_access 和 test_read_only_skill_stays_read_only。
能够解释为什么只读 Skill 不应该获得写入权限，以及最小权限原则的重要性。
在故障实验室中成功修复了适配器，使其根据能力需求动态决定访问级别。

STAGE 05

把三个平台的安装计划规范化为可比较、可审计的配置记录

先看一个具体问题

如何将不同平台的安装计划统一为可比较的配置记录？

当前 forge/adapters/config.py 文件尚未创建，因此 normalize_plan 函数不存在，导致测试在导入阶段就失败。

我们需要实现一个规范化函数，它接收平台标识符和安装计划数据类，返回包含 schemaVersion 和 configuration 的字典。

关键决策在于：规范化过程中必须验证平台标识符是否受支持，否则未知平台会混入发布配置，造成后续审计和部署风险。

先做判断

在实现 normalize_plan 时，如果传入一个未知平台标识符（如 "mystery-agent"），函数应该如何处理？

直接序列化并返回配置记录，因为规范化只负责格式转换
抛出 ValueError，因为规范化必须验证平台标识符
返回一个带有默认平台字段的配置记录
忽略平台字段，只序列化计划数据类

判断依据: 正确选项是抛出 ValueError。规范化不是简单的格式转换，它必须确保平台标识符属于受支持的适配器注册表，否则未知平台会进入发布配置，破坏后续的可审计性和部署安全性。

它是什么

规范化平台配置是什么

规范化平台配置是将不同平台的安装计划转换为统一结构的过程，该结构包含平台标识符、模式版本和配置数据。

它必须验证平台标识符是否在受支持的适配器注册表中，并检查计划是否为数据类且包含安装路径。

规范化后的配置记录是可比较、可审计的，能够被下游部署流程安全地消费。

它不是什么

规范化平台配置不是什么

规范化不等于简单的序列化，它不能接受任意平台名称而不加验证。

规范化不负责执行安装或修改计划内容，它只负责将计划转换为标准格式并确保其符合基本约束。

规范化不是平台适配器本身，它不处理平台特定的通信协议或认证逻辑。

它与相邻概念的关系

与其他组件的关系

规范化函数 normalize_plan 被测试文件 tests/test_stage.py 直接调用，测试期望它验证平台并返回正确的 schemaVersion。

它依赖于 Python 的 dataclasses 模块来序列化计划数据类，并检查计划是否包含安装路径字段。

规范化后的配置记录将被后续的部署流程使用，因此必须保证平台标识符的有效性。

本阶段的边界决定: 规范化必须验证平台标识符，拒绝未知平台；同时检查计划是否为数据类且包含安装路径，否则抛出相应异常。

实验 ID: platform-adapters-05-normalized-platform-config
输入: 软件交付：为前端仓库增加功能、修改代码并补测试。
证据目录: evidence/platform-adapters/05-normalized-platform-config/
验收: 待验收

教师示范

目标: 演示如何实现 normalize_plan 的基础版本，包括平台验证和序列化数据类。

首先，我们创建 forge/adapters/config.py 文件，并导入 dataclasses 模块中的 asdict 和 is_dataclass。

然后，我们定义 normalize_plan 函数，它接收平台标识符和计划对象，返回规范化后的字典。

在函数内部，我们首先检查平台标识符是否在受支持的集合中，如果不是则抛出 ValueError。

接着，我们检查计划对象是否为数据类，如果不是则抛出 TypeError。

最后，我们使用 asdict 将数据类转换为字典，并检查是否包含以 path 结尾的键，然后返回包含平台、模式版本和配置的字典。

实施步骤

创建 forge/adapters/config.py 文件。
导入 asdict 和 is_dataclass。
定义 normalize_plan 函数。
添加平台验证逻辑。
添加数据类检查和路径检查。
返回规范化字典。

真实 solution 代码: forge/adapters/config.py

from dataclasses import asdict, is_dataclass

def normalize_plan(platform: str, plan: object) -> dict[str, object]:
    if platform not in {"codex", "claude-code", "workbuddy"}:
        raise ValueError("unknown platform")
    if not is_dataclass(plan):
        raise TypeError("adapter plan must be a dataclass")
    values = asdict(plan)
    if not any(key.endswith("path") for key in values):
        raise ValueError("adapter plan lacks install path")
    return {"platform": platform, "schemaVersion": 1, "configuration": values}

python -m pytest -q tests/test_stage.py

运行真实测试

..                                                                       [100%]
2 passed in <duration>s

为什么这样实现

平台验证确保只有受支持的平台（codex、claude-code、workbuddy）能够通过规范化，未知平台会立即被拒绝。

数据类检查防止传入非数据类对象导致序列化错误，路径检查确保计划包含安装路径，这是部署所必需的信息。

最终返回的字典包含 platform、schemaVersion 和 configuration 字段，满足测试对 schemaVersion 为 1 的断言。

带提示练习

在现有基础上添加平台注册表检查，使未知平台抛出 ValueError。

打开 forge/adapters/config.py 文件。
在 normalize_plan 函数开头添加平台验证代码。
使用 if platform not in {"codex", "claude-code", "workbuddy"}: 判断平台是否受支持。
如果平台不受支持，抛出 ValueError("unknown platform")。
运行测试确认 test_unknown_platform_is_rejected 通过。

逐级提示

提示：平台集合应该包含所有已实现的适配器平台名称。
提示：异常消息必须包含 “unknown” 子串，以满足测试断言。
提示：验证应该放在函数的最前面，避免后续处理无效平台。

完成标准

test_unknown_platform_is_rejected 测试通过。
test_known_platform_is_normalized 测试仍然通过。

故障注入与排查

在故障夹具 fixtures/failure.json 中，forge/adapters/config.py 的 normalize_plan 函数缺少平台注册表验证，导致未知平台 mystery-agent 被序列化为看似有效的配置记录。测试 test_unknown_platform_is_rejected 因此失败，因为函数没有抛出预期的 ValueError。

本阶段的核心机制是在规范化过程中验证平台标识符。通过检查平台是否在受支持的适配器注册表中，我们可以拒绝未知平台，从而修复故障。学习者已经掌握了平台验证的必要性，并能够实现相应的检查逻辑。

已验证的故障合同

目标测试: test_unknown_platform_is_rejected
故障文件: forge/adapters/config.py

诊断顺序

运行故障命令 python -m pytest -q ../tests/test_stage.py::test_unknown_platform_is_rejected，观察测试失败。
查看 forge/adapters/config.py 中的 normalize_plan 函数，发现它直接序列化平台名称而没有验证。
确认测试期望未知平台抛出 ValueError，但当前函数没有抛出异常。
定位根因：规范化被误认为等同于验证，缺少平台注册表检查。

修复原则: 在 normalize_plan 函数开头添加平台验证：if platform not in {"codex", "claude-code", "workbuddy"}: raise ValueError("unknown platform")。这样未知平台会被立即拒绝，测试通过。

python -m pytest -q ../tests/test_stage.py::test_unknown_platform_is_rejected

迁移挑战

音乐创作场景中，你需要使用 normalize_plan 规范化一个 Codex 平台的安装计划。计划数据类为 Plan，包含 target_path 字段。

改变的条件: 将计划的目标路径从默认的 /skills/a 改为 /skills/music-release，平台保持为 codex。

编写一个测试或脚本，调用 normalize_plan("codex", Plan("/skills/music-release"))，并验证返回的 schemaVersion 为 1 且 configuration 中的 target_path 正确。

完成标准

调用 normalize_plan 时传入平台 codex 和计划 Plan("/skills/music-release")。
断言返回字典的 platform 字段等于 codex。
断言返回字典的 schemaVersion 等于 1。
断言返回字典的 configuration 字段包含 target_path 且值为 /skills/music-release。

运行真实测试

python -m pytest -q tests/test_stage.py

运行真实测试

..                                                                       [100%]
2 passed in <duration>s

设计解释题: 为什么规范化必须包含平台验证？如果接受未知平台，会有什么风险？

一个有力回答应包含

平台验证确保只有受支持的平台能够进入配置记录，避免未知平台导致部署失败或安全漏洞。
接受未知平台会破坏配置的可审计性，因为下游流程无法识别平台，可能导致错误操作或数据损坏。
规范化与验证分离会导致配置记录看似有效但实际不可用，增加调试成本。

掌握证据

通过 test_known_platform_is_normalized 和 test_unknown_platform_is_rejected 两个测试。
能够解释规范化与验证的区别：规范化负责格式转换，验证负责平台标识符的合法性。
在转移挑战中成功使用 normalize_plan 处理不同平台和路径，并验证返回结果。

STAGE 06

区分阻塞缺失和可接受降级，并生成可解释的平台兼容报告

先看一个具体问题

平台缺少可选能力时被错误判为不兼容

在上一阶段，你已经把不同平台的原始配置规范化为统一的 SkillContract，其中每个能力都带有 required 标志。

现在需要实现 evaluate 函数，根据平台实际可用的能力集合生成 CompatibilityReport，报告必须区分阻塞缺失和可接受降级。

当前 forge/adapters/compatibility.py 文件尚不存在，运行测试会直接报 ModuleNotFoundError，因为测试文件 tests/test_stage.py 试图导入 evaluate。

如果简单地把所有缺失能力都放进 blockers，那么缺少可选能力 git 的平台也会被标记为不兼容，这违背了合同语义。

先做判断

在实现 evaluate 之前，请预测：如果平台缺少一个标记为可选的能力（例如 git），CompatibilityReport.compatible 应该是什么？

False，因为任何缺失都意味着平台不完整
True，因为可选能力缺失不应阻塞兼容性
False，但把缺失项放入 degradations
True，但把缺失项放入 blockers

判断依据: 正确答案是 True，可选能力缺失只应记录为降级，不影响整体兼容性。只有必需能力缺失才会导致 compatible=False。

它是什么

兼容性报告是合同与平台能力的差异分析

CompatibilityReport 是一个不可变数据类，包含 compatible 布尔值、blockers 元组和 degradations 元组。

evaluate 函数遍历 SkillContract 中的每个 CapabilityRequirement，检查其名称是否在 available 集合中。

对于缺失的能力，根据其 required 标志决定放入 blockers 还是 degradations。

最终 compatible 仅由 blockers 是否为空决定，与 degradations 无关。

它不是什么

兼容性报告不是简单的缺失列表

它不把所有缺失能力混为一谈，而是保留每个能力的必需/可选语义。

它不负责修改平台配置或自动安装缺失能力，只做静态评估。

它不保证平台在运行时一定成功，只反映合同层面的静态兼容性。

它与相邻概念的关系

与已有组件的关系

SkillContract 和 CapabilityRequirement 来自 forge/adapters/capabilities.py，本阶段不修改它们。

evaluate 函数被测试文件 tests/test_stage.py 直接调用，测试期望返回的 CompatibilityReport 字段精确匹配。

后续阶段可能会使用该报告来决定是否允许部署或触发迁移流程。

本阶段的边界决定: 只有当缺失的能力的 required 属性为 True 时，才将其加入 blockers；否则加入 degradations，并且 compatible 只取决于 blockers 是否为空。

实验 ID: platform-adapters-06-compatibility-loss-report
输入: 软件交付：为前端仓库增加功能、修改代码并补测试。
证据目录: evidence/platform-adapters/06-compatibility-loss-report/
验收: 待验收

教师示范

目标: 演示如何实现 evaluate，生成包含 blockers 和 degradations 的 CompatibilityReport。

假设一个技能合同要求 read_files（必需）和 git（可选），而平台只提供了 read_files。

正确的评估结果应该是 compatible=True，blockers=()，degradations=('git',)。

实现时，先分别收集缺失的必需能力和可选能力，然后构造报告。

实施步骤

创建 forge/adapters/compatibility.py 文件。
定义 CompatibilityReport 数据类，包含 compatible、blockers、degradations 三个字段。
实现 evaluate 函数，遍历 contract.capabilities，对每个缺失项根据 required 标志分类。
对分类结果排序以保证确定性，然后返回 CompatibilityReport(not blockers, blockers, degradations)。

真实 solution 代码: forge/adapters/compatibility.py

from dataclasses import dataclass
from forge.adapters.capabilities import SkillContract

@dataclass(frozen=True)
class CompatibilityReport:
    compatible: bool
    blockers: tuple[str, ...]
    degradations: tuple[str, ...]

def evaluate(contract: SkillContract, available: set[str]) -> CompatibilityReport:
    blockers = tuple(sorted(item.name for item in contract.capabilities if item.required and item.name not in available))
    degradations = tuple(sorted(item.name for item in contract.capabilities if not item.required and item.name not in available))
    return CompatibilityReport(not blockers, blockers, degradations)

python -m pytest -q tests/test_stage.py

运行真实测试

..                                                                       [100%]
2 passed in <duration>s

为什么这样实现

测试 test_required_gap_blocks_compatibility 验证缺少必需能力时 compatible 为 False。

测试 test_optional_gap_is_reported_as_degradation 验证缺少可选能力时 compatible 为 True 且 degradations 包含该能力。

带提示练习

修正 evaluate，使可选缺失进入 degradations 而不是 blockers。

打开 forge/adapters/compatibility.py，检查当前实现是否把所有缺失能力都放进了 blockers。
修改列表推导式，增加条件 if item.required 来筛选必需能力。
为可选能力创建另一个列表推导式，条件为 if not item.required。
确保两个元组都经过 sorted 排序，然后重新运行测试。

逐级提示

注意 CapabilityRequirement 的 required 字段默认值为 True。
blockers 和 degradations 都应该是元组，且元素顺序稳定。
compatible 的值是 not blockers，而不是 not missing。

完成标准

test_required_gap_blocks_compatibility 通过。
test_optional_gap_is_reported_as_degradation 通过。

故障注入与排查

当前 forge/adapters/compatibility.py 的实现把所有缺失能力都放进了 blockers，导致缺少可选能力 git 的平台被错误标记为不兼容。运行测试 test_optional_gap_is_reported_as_degradation 会失败，断言 report.compatible is True 不成立。

本阶段的核心就是区分必需和可选能力，而故障正是丢失了这个区分。通过检查 evaluate 函数中列表推导式的条件，可以定位到缺少 if item.required 过滤的问题。修复后，测试将通过。

已验证的故障合同

目标测试: test_optional_gap_is_reported_as_degradation
故障文件: forge/adapters/compatibility.py

诊断顺序

运行 python -m pytest -q ../tests/test_stage.py::test_optional_gap_is_reported_as_degradation，观察失败输出。
查看失败信息中的 CompatibilityReport(compatible=False, blockers=('git',), degradations=())，发现 git 被放进了 blockers。
打开 forge/adapters/compatibility.py，检查 evaluate 函数中的列表推导式，确认没有根据 required 标志进行区分。
修复代码，将缺失的必需能力放入 blockers，缺失的可选能力放入 degradations。

修复原则: 修改 evaluate 函数，分别使用 if item.required 和 if not item.required 两个条件来生成 blockers 和 degradations，然后返回 CompatibilityReport(not blockers, blockers, degradations)。

python -m pytest -q ../tests/test_stage.py::test_optional_gap_is_reported_as_degradation

迁移挑战

音乐创作场景中，你需要评估一个“曲目管理”技能在某个平台上的兼容性。该技能合同要求 read_files 为必需，git 为可选，而平台只提供了 read_files。

改变的条件: 将技能合同的能力集合从默认示例改为音乐场景的“曲目管理”技能，并保持必需/可选标志不变。

使用 evaluate 函数评估该技能合同与平台可用能力集合的兼容性，并验证结果。

完成标准

调用 evaluate 后返回的 CompatibilityReport.compatible 为 True。
返回的 CompatibilityReport.degradations 包含 git，且 blockers 为空。

运行真实测试

python -m pytest -q tests/test_stage.py

运行真实测试

..                                                                       [100%]
2 passed in <duration>s

设计解释题: 为什么可选能力缺失不应阻塞兼容性？请结合 CompatibilityReport 中 blockers 和 degradations 的语义，说明这种设计对平台适配决策的影响。

一个有力回答应包含

可选能力缺失只影响部分功能，平台仍能完成核心任务，因此不应阻塞整体兼容性。
将缺失项放入 degradations 可以让调用方了解潜在限制，同时允许部署继续进行。
如果所有缺失都视为阻塞，会导致过度保守，错失可用的平台。

掌握证据

通过 test_required_gap_blocks_compatibility 和 test_optional_gap_is_reported_as_degradation 两个测试。
能够解释 blockers 与 degradations 的区别，并说明为什么可选缺失不阻塞兼容性。
在音乐场景的转移挑战中，正确使用 evaluate 得到 compatible=True 且 degradations 包含 git。

STAGE 07

用统一合同检查安装路径、权限不升级和能力覆盖，阻止不安全适配器发布

先看一个具体问题

如何自动检查适配器计划是否符合安全与能力要求？

在上一阶段，我们生成了兼容性报告，但报告只描述差异，并不会阻止不安全的适配器发布。

现在需要实现一个一致性检查函数 check_plan，它接收平台名、配置字典和所需能力集合，返回 ConformanceResult。

如果配置缺少安装路径、未覆盖所需能力，或者审批模式为 full-access 但所需能力中不包含 unattended_write，则必须判定为不通过并给出具体错误。

当前代码库中还没有 forge/adapters/conformance.py 文件，因此测试在导入阶段就会失败。

先做判断

在实现 check_plan 之前，请预测：如果只检查配置是否非空，能否通过 test_permission_escalation_fails_conformance 测试？

能通过，因为配置非空且包含 capabilities。
不能通过，因为 full-access 审批模式会授予超出所需能力的权限。
能通过，因为测试只检查 passed 是否为 False。
不能通过，因为配置缺少 target_path。

判断依据: 正确答案是“不能通过，因为 full-access 审批模式会授予超出所需能力的权限”。该测试传入 approval_mode 为 full-access，但所需能力只有 read_files，这属于权限升级，必须被拒绝。仅检查非空无法发现这种语义违规。

它是什么

一致性检查是什么

一致性检查是对适配器生成的配置计划进行语义验证，确保其满足安全与能力合同。

它检查三个关键维度：安装路径是否存在且非空、所需能力是否被配置声明、审批模式是否导致权限升级。

检查结果通过 ConformanceResult 数据类返回，包含平台名、是否通过以及错误元组。

它不是什么

一致性检查不是什么

它不只是检查配置字典是否非空或字段是否存在，因为形状正确不代表语义安全。

它不负责实际执行安装或修改系统状态，只对计划进行静态分析。

它不能替代领域验收，也不能保证模型输出永远正确，只验证适配器计划是否符合预定义规则。

它与相邻概念的关系

与其他组件的关系

check_plan 使用配置字典和所需能力集合作为输入，这些数据来自 Skill 的元数据和适配器生成的计划。

ConformanceResult 的 errors 元组会被测试断言，例如 test_permission_escalation_fails_conformance 检查 errors 中包含 “permission escalation”。

该检查位于 forge/adapters/conformance.py，与 capabilities.py、compatibility.py 等模块共同构成适配器层。

本阶段的边界决定: 一致性检查必须验证语义，包括权限不升级和能力覆盖，而不仅仅是配置形状。如果只检查非空，就会批准授予未声明 full-access 的适配器，导致安全风险。

实验 ID: platform-adapters-07-adapter-conformance-suite
输入: 软件交付：为前端仓库增加功能、修改代码并补测试。
证据目录: evidence/platform-adapters/07-adapter-conformance-suite/
验收: 待验收

教师示范

目标: 演示如何实现 check_plan 的基础部分：检查安装路径和能力覆盖。

我们从零开始创建 forge/adapters/conformance.py 文件，并定义 ConformanceResult 数据类。

首先实现安装路径检查：从配置字典中查找键名以 ‘path’ 结尾的项，如果值不是非空字符串，则添加错误 “install path missing”。

然后实现能力覆盖检查：获取配置中的 capabilities 列表，如果所需能力集合不是其子集，则添加错误 “required capability missing”。

实施步骤

创建文件 forge/adapters/conformance.py。
导入 dataclass 并定义 ConformanceResult 数据类，包含 platform、passed、errors 字段。
定义 check_plan 函数，初始化 errors 列表。
使用 next 和生成器表达式查找键名以 ‘path’ 结尾的项，检查其值是否为非空字符串。
获取配置中的 capabilities 集合，检查 required_capabilities 是否为其子集。
返回 ConformanceResult(platform, not errors, tuple(errors))。

真实 solution 代码: forge/adapters/conformance.py

from dataclasses import dataclass

@dataclass(frozen=True)
class ConformanceResult:
    platform: str
    passed: bool
    errors: tuple[str, ...]

def check_plan(platform: str, configuration: dict[str, object], required_capabilities: set[str]) -> ConformanceResult:
    errors: list[str] = []
    path_value = next((value for key, value in configuration.items() if key.endswith("path")), "")
    if not isinstance(path_value, str) or not path_value:
        errors.append("install path missing")
    declared = set(configuration.get("capabilities", ()))
    if declared and not required_capabilities.issubset(declared):
        errors.append("required capability missing")
    if configuration.get("approval_mode") == "full-access" and "unattended_write" not in required_capabilities:
        errors.append("permission escalation")
    return ConformanceResult(platform, not errors, tuple(errors))

python -m pytest -q tests/test_stage.py

运行真实测试

..                                                                       [100%]
2 passed in <duration>s

为什么这样实现

安装路径检查确保适配器计划指定了有效的目标路径，避免安装到未知位置。

能力覆盖检查确保适配器声明的能力至少包含 Skill 所需的能力，否则运行时可能因缺少权限而失败。

这两个检查是语义验证的基础，但尚未处理权限升级问题。

带提示练习

添加权限升级检查，使 full-access 在未要求 unattended_write 时失败。

在 check_plan 函数中，在能力覆盖检查之后添加权限升级检查。
检查 configuration.get(“approval_mode”) 是否等于 “full-access”。
同时检查 “unattended_write” 是否不在 required_capabilities 中。
如果两个条件都满足，向 errors 列表添加 “permission escalation”。
运行测试 test_permission_escalation_fails_conformance 验证结果。

逐级提示

使用 configuration.get(“approval_mode”) 获取审批模式。
使用 not in 检查 “unattended_write” 是否不在 required_capabilities 中。
错误消息必须与测试断言一致，即 “permission escalation”。

完成标准

test_permission_escalation_fails_conformance 测试通过。
test_safe_plan_conforms 测试仍然通过。

故障注入与排查

当前 faulty 版本的 conformance.py 只检查配置是否非空，因此会错误地批准一个 full-access 计划。运行测试 test_permission_escalation_fails_conformance 会失败，因为该计划授予了超出所需能力的权限。你需要诊断并修复这个缺陷。可执行故障夹具修改 forge/adapters/conformance.py，并由 test_permission_escalation_fails_conformance 稳定复现。

本阶段已经实现了安装路径和能力覆盖检查，但缺少权限升级检查。faulty 版本正是缺少这一关键语义验证，导致 full-access 计划被错误通过。通过添加权限升级检查，可以阻止不安全适配器发布。

已验证的故障合同

目标测试: test_permission_escalation_fails_conformance
故障文件: forge/adapters/conformance.py

诊断顺序

运行命令 python -m pytest -q ../tests/test_stage.py::test_permission_escalation_fails_conformance，观察测试失败。
查看测试代码，发现传入 approval_mode 为 full-access，但所需能力只有 read_files。
检查 faulty 版本的 check_plan 实现，发现它只检查配置是否非空，没有检查审批模式与所需能力的关系。
确认缺陷：缺少权限升级检查，导致 full-access 计划被错误通过。

修复原则: 在 check_plan 函数中添加权限升级检查：如果 configuration.get(“approval_mode”) == “full-access” 且 “unattended_write” 不在 required_capabilities 中，则向 errors 列表添加 “permission escalation”。这样 full-access 计划在未要求 unattended_write 时会被拒绝。

python -m pytest -q ../tests/test_stage.py::test_permission_escalation_fails_conformance

迁移挑战

办公研究场景中，一个 WorkBuddy 适配器计划配置为只读访问，所需能力为 read_files。请使用 check_plan 检查该计划，并验证 passed 为 True。

改变的条件: 将场景从软件交付的 Codex 平台改为办公研究的 WorkBuddy 平台，并调整配置为只读访问。

编写一个 Python 脚本或交互式调用，使用 check_plan 函数检查以下计划：platform 为 “workbuddy”，configuration 为 {“target_path”:“/skills/office”, “capabilities”:[“read_files”], “approval_mode”:“ask-before-writes”}，required_capabilities 为 {“read_files”}。验证返回的 ConformanceResult 的 passed 属性为 True。

完成标准

调用 check_plan 后返回的 ConformanceResult 对象中 passed 属性为 True。
errors 元组为空，表示没有一致性错误。

运行真实测试

python -m pytest -q tests/test_stage.py

运行真实测试

..                                                                       [100%]
2 passed in <duration>s

设计解释题: 为什么一致性检查必须检查权限升级？如果只验证配置形状，会带来什么风险？

一个有力回答应包含

权限升级意味着适配器授予的权限超过了 Skill 实际所需，例如 full-access 审批模式允许自动写入，而 Skill 只需要读取文件。
如果只验证配置形状，攻击者或错误配置可能授予过多权限，导致未授权操作或数据泄露。
检查权限升级可以确保最小权限原则，降低安全风险。

掌握证据

通过 test_safe_plan_conforms 和 test_permission_escalation_fails_conformance 两个测试。
能够解释为什么一致性检查必须包含权限升级检查，而不仅仅是配置形状验证。
在 transferChallenge 中成功使用 check_plan 验证办公场景下的 WorkBuddy 计划通过检查。

完成本章

让同一个 Forge Skill 通过适配器部署到三个平台。

FORGE / LOCAL CHECK

本地实验自检

未开始
2阅读中
3实验已下载
4测试结果已读取
5本地自检通过

verification.json 只在当前浏览器中解析，不会上传。这里验证的是实验合同，不是服务器认证或第三方背书。

选择 verification.json

主要层

依赖能力

为后续提供

受这些层约束

概念校准

Harness

Skill

工具

多平台适配与迁移

先看一个具体问题

如何声明 Skill 需要哪些能力，并区分必需与可选？

先做判断

它是什么

平台无关能力合同是什么

它不是什么

平台无关能力合同不是什么

它与相邻概念的关系

合同内部各组件的关系

先看一个具体问题

从规范合同到 Codex 安装计划

先做判断

它是什么

适配器是安全语义的翻译器

它不是什么

适配器不是权限决策者

它与相邻概念的关系

合同、适配器与 Harness 的关系

先看一个具体问题

为 Claude Code 平台生成命令白名单，并拒绝无法表达的必需能力

先做判断

它是什么

显式能力映射表

它不是什么

不是通用 shell 访问的别名

它与相邻概念的关系

与技能契约和平台计划的关系

先看一个具体问题

从能力需求推导 WorkBuddy 工作区访问级别

先做判断

它是什么

WorkBuddy 适配器是什么

它不是什么

WorkBuddy 适配器不是什么

它与相邻概念的关系

与其他组件的关系

先看一个具体问题

如何将不同平台的安装计划统一为可比较的配置记录？

先做判断

它是什么

规范化平台配置是什么

它不是什么

规范化平台配置不是什么

它与相邻概念的关系

与其他组件的关系

先看一个具体问题

平台缺少可选能力时被错误判为不兼容

先做判断

它是什么

兼容性报告是合同与平台能力的差异分析

它不是什么

兼容性报告不是简单的缺失列表

它与相邻概念的关系

与已有组件的关系

先看一个具体问题

如何自动检查适配器计划是否符合安全与能力要求？

先做判断

它是什么

一致性检查是什么

它不是什么

一致性检查不是什么

它与相邻概念的关系

与其他组件的关系