架构定位

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 适配器不是什么#

它与相邻概念的关系#

与其他组件的关系#

先看一个具体问题#

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

先做判断#

它是什么#

规范化平台配置是什么#

它不是什么#

规范化平台配置不是什么#

它与相邻概念的关系#

与其他组件的关系#

先看一个具体问题#

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

先做判断#

它是什么#

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

它不是什么#

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

它与相邻概念的关系#

与已有组件的关系#

先看一个具体问题#

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

先做判断#

它是什么#

一致性检查是什么#

它不是什么#

一致性检查不是什么#

它与相邻概念的关系#

与其他组件的关系#