架构定位

能力扩展

通过能力包、外部证据、持久状态和标准协议扩展 Agent 能做的事情。

如何为 Agent 增加 Skill、检索、记忆和外部协议能力？

概念校准

Skill

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

工具

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

Skill、Prompt 与 Agent 能力包

把需求抽取器封装成有 Manifest、资源边界和兼容元数据的 Skill。

本章只做一件事交付可安装、可审查、覆盖三个场景的 Forge Skill。

开始前，Forge 已经具备已完成 Module 05 的“Prompt、上下文工程与结构化输出”，其通过验收的 solution 是本章起点。

完成后，Forge 将能够把 Forge 的需求抽取能力封装为可安装 Skill。

卡住时的最小恢复点只打包 Markdown、Schema 和测试夹具，不附带自动执行脚本。

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

阶段能力链

01验证能力包必须包含入口说明、资源目录和可审查的相对路径02区分可读取资源与可执行脚本，并默认禁止安装或运行脚本03用声明变量渲染 Prompt，并拒绝缺失或未声明变量以避免平台隐式依赖04解析包含 ID、版本、入口、文件哈希和权限声明的严格 Manifest05解析 SemVer 并根据主版本判断升级是否需要迁移06根据平台能力、所需功能和最低客户端版本给出兼容或缺口报告07为三场景生成排序稳定、哈希可复核且不自动执行脚本的发布清单

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

概念校准\n\n在开始操作代码前，先把本章涉及的概念放回正确的工程边界。\n\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

验证能力包必须包含入口说明、资源目录和可审查的相对路径

先看一个具体问题

创建 forge/skill_layout.py 并让结构验证测试通过

当前 forge/skill_layout.py 不存在，tests/test_stage.py 在导入 validate_layout 时直接触发 ModuleNotFoundError，因此学习者需要从空文件开始创建该模块。

本阶段要实现的 validate_layout 接收路径字符串列表，返回错误字符串列表；它必须拒绝缺少 SKILL.md 的目录，并拒绝绝对路径或包含 .. 的父目录遍历路径。

测试 test_skill_requires_entry_instructions 和 test_parent_traversal_is_rejected 分别锁定这两个结构约束，学习者需要让这两个测试从失败变为通过。

先做判断

如果 validate_layout([“references/guide.md”]) 的实现只是 return []，运行 test_skill_requires_entry_instructions 会发生什么？

测试通过，因为 references/guide.md 是合法路径
测试失败，因为断言期望错误列表包含 missing SKILL.md
测试失败，因为路径包含父目录遍历
测试通过，因为 references 是允许的根目录

判断依据: 正确选项是第二个：测试断言 “missing SKILL.md” in validate_layout(…)，空列表不包含该错误，因此失败。这暴露了入口文件合同没有被执行。

它是什么

Skill 结构验证器是一个纯函数合同检查器

validate_layout 接收路径字符串列表，返回错误字符串列表；它不读取文件内容，只根据路径集合判断是否满足 SKILL.md 入口、允许根目录和相对路径安全。

该函数使用 PurePosixPath 把每个路径字符串规范化为可检查的路径对象，然后通过集合成员关系和 parts 属性执行静态判断。

它不是什么

它不是文件系统扫描器或安装器

validate_layout 不会检查文件是否真实存在，也不会创建目录、复制资源或执行脚本；它只对传入的路径字符串做结构合同验证。

它也不负责平台权限策略或工具调用隔离，这些边界由后续的 Harness 和适配器处理，本阶段只验证 Skill 包的结构元素。

它与相邻概念的关系

入口集合、根目录集合与路径对象之间的关系

REQUIRED 集合定义必须存在的入口文件名 SKILL.md，ALLOWED_ROOTS 集合定义允许的第一级目录，如 references、templates、scripts、tests。

PurePosixPath 的 parts 属性把路径拆成组件，使代码能检查第一级根目录和 .. 组件；先检查入口缺失，再检查路径安全，最后检查根目录，形成分层验证顺序。

本阶段的边界决定: 当路径列表缺少 SKILL.md 时返回 missing SKILL.md；当路径为绝对路径或包含 .. 时返回 unsafe path；当第一级目录不在 ALLOWED_ROOTS 时返回 unknown root。

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

教师示范

目标: 演示 validate_layout 如何拒绝缺少 SKILL.md 的路径列表，并返回包含 missing SKILL.md 的错误。

先创建 forge/skill_layout.py，定义 REQUIRED = {“SKILL.md”}，这是 Skill 包必须包含的入口文件集合。

validate_layout 把每个路径字符串转换为 PurePosixPath，然后用集合推导得到路径字符串集合；如果 REQUIRED 不是该集合的子集，就向 errors 添加 “missing SKILL.md”。

这样 test_skill_requires_entry_instructions 传入 [“references/guide.md”] 时，函数会返回 [“missing SKILL.md”]，满足断言。

实施步骤

创建 forge/skill_layout.py 文件。
从 pathlib 导入 PurePosixPath。
定义 REQUIRED = {“SKILL.md”}。
在 validate_layout 中规范化路径并检查 REQUIRED <= {str(item) for item in normalized}，否则添加 missing SKILL.md。
运行单测 test_skill_requires_entry_instructions 验证入口检查。

真实 solution 代码: forge/skill_layout.py

from pathlib import PurePosixPath

REQUIRED={"SKILL.md"}
ALLOWED_ROOTS={"SKILL.md","references","templates","scripts","tests"}

def validate_layout(paths: list[str]) -> list[str]:
    normalized=[PurePosixPath(item) for item in paths]; errors=[]
    if not REQUIRED <= {str(item) for item in normalized}: errors.append("missing SKILL.md")
    for item in normalized:
        if item.is_absolute() or ".." in item.parts: errors.append(f"unsafe path: {item}")
        elif item.parts and item.parts[0] not in ALLOWED_ROOTS: errors.append(f"unknown root: {item.parts[0]}")
    return errors

python -m pytest -q tests/test_stage.py

运行真实测试

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

为什么这样实现

子集检查 REQUIRED <= {str(item) for item in normalized} 只有在路径集合包含 SKILL.md 时才为真，因此缺少入口时必然添加错误。

这个检查只验证入口文件名是否存在，不验证文件内容或真实文件系统状态，所以它是结构合同的第一层。

带提示练习

补全 validate_layout 中检查父目录遍历的逻辑，使包含 templates/../../secret.txt 的路径列表被标记为不安全。

在 validate_layout 中遍历已经规范化的 PurePosixPath 对象。
对每个路径检查 item.is_absolute() or “..” in item.parts。
如果条件为真，向 errors 添加 f“unsafe path: {item}”。
运行 test_parent_traversal_is_rejected 验证该路径被拒绝。

逐级提示

PurePosixPath 的 parts 属性会把 templates/../../secret.txt 拆成 (‘templates’, ‘..’, ‘..’, ‘secret.txt’)，其中包含 ..。
先检查绝对路径或 ..，再检查第一级根目录，避免把不安全路径误判为 unknown root。

完成标准

validate_layout([“SKILL.md”,“templates/../../secret.txt”]) 返回的列表中至少有一项包含 unsafe path。
test_parent_traversal_is_rejected 通过。

故障注入与排查

故障夹具 fixtures/failure.json 描述了一个缺少入口文件的场景：一个没有 SKILL.md 的目录被当作可安装的 Skill 接受。故障实现 validate_layout 直接返回空列表，不执行任何结构合同检查。运行 python -m pytest -q ../tests/test_stage.py::test_skill_requires_entry_instructions 时，捕获到的失败输出显示测试断言失败，因为函数返回空列表，而断言期望错误字符串 “missing SKILL.md” 存在。

本阶段正在建立 Skill 结构验证器，validate_layout 的职责就是检查 SKILL.md 入口、允许根目录和路径安全。故障实现直接返回空列表，导致入口检查测试断言失败。学习者需要观察失败输出，定位到 forge/skill_layout.py 中直接返回空列表这一行，然后诊断并修复这个已注入的缺陷，添加缺失的 SKILL.md 入口检查，使函数在缺少 SKILL.md 时返回“缺少 SKILL.md”的错误，从而让测试通过。

已验证的故障合同

目标测试: test_skill_requires_entry_instructions
故障文件: forge/skill_layout.py

诊断顺序

运行 python -m pytest -q ../tests/test_stage.py::test_skill_requires_entry_instructions，观察断言失败，确认函数返回空列表。
打开 forge/skill_layout.py，看到 validate_layout 直接返回空列表，没有执行任何结构合同检查。
在实现中先规范化路径，再检查 REQUIRED <= {str(item) for item in normalized}，否则添加 “missing SKILL.md” 的错误。

修复原则: 修复 forge/skill_layout.py 中的 validate_layout：定义 REQUIRED={“SKILL.md”}，将路径规范化为 PurePosixPath 后检查入口是否存在，缺少 SKILL.md 时添加 “missing SKILL.md” 的错误。这样 test_skill_requires_entry_instructions 会通过，并且入口合同得到执行。

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

迁移挑战

办公研究场景：一个 Skill 目录需要包含 SKILL.md、references/brief-template.md 和 templates/decision.md，用于从文档和表格生成带引用的决策简报。该场景仅改变输入路径列表的数据内容，不改变验证逻辑或能力边界。

改变的条件: 输入路径列表从缺少 SKILL.md 的列表变为包含 SKILL.md、references/brief-template.md 和 templates/decision.md 的完整列表，验证结果从返回错误变为返回空列表。

调用 validate_layout([“SKILL.md”, “references/brief-template.md”, “templates/decision.md”])，确认返回空列表，并解释为什么这些路径都通过入口、根目录和遍历检查。

完成标准

validate_layout([“SKILL.md”, “references/brief-template.md”, “templates/decision.md”]) 返回空列表，证明没有 missing SKILL.md、unsafe path 或 unknown root 错误。
该列表满足 SKILL.md 入口、references 和 templates 根目录以及无父目录遍历。
解释为什么 references 和 templates 作为第一级目录都在 ALLOWED_ROOTS 中，且路径中没有绝对路径或 .. 组件。

运行真实测试

python -m pytest -q tests/test_stage.py

运行真实测试

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

设计解释题: 为什么先检查 item.is_absolute() or “..” in item.parts，再检查 item.parts[0] not in ALLOWED_ROOTS，这个顺序对安全判断有什么因果影响？

一个有力回答应包含

如果先检查根目录，templates/../../secret.txt 的第一级是 templates，会被误判为合法根目录，从而漏掉父目录遍历。
先检查绝对路径和 .. 能保证任何逃逸出允许根目录的路径先被标记为 unsafe path，避免后续根目录检查掩盖安全问题。

掌握证据

test_skill_requires_entry_instructions 通过：validate_layout([“references/guide.md”]) 返回包含 missing SKILL.md 的错误。
test_parent_traversal_is_rejected 通过：validate_layout([“SKILL.md”,“templates/../../secret.txt”]) 返回包含 unsafe path 的错误。
forge/skill_layout.py 中 REQUIRED 和 ALLOWED_ROOTS 集合定义了入口与允许根目录，PurePosixPath 用于规范化路径并检查 ..。

STAGE 02

区分可读取资源与可执行脚本，并默认禁止安装或运行脚本

先看一个具体问题

Skill 包中的脚本为什么不能像资源一样被自动安装

在 Skill 包的安装过程中，学习者面对的核心决策是区分可读取的静态资源与可能产生副作用的可执行脚本。当前的 forge/package_policy.py 文件尚未创建，测试在收集阶段就会因为 ModuleNotFoundError 而中断。

故障夹具中的 decide_file 函数将所有路径一视同仁地标记为可安装，并且将 scripts/ 目录下的文件标记为可执行。这导致 scripts/setup.ps1 在未经用户显式批准的情况下被直接接受并赋予执行权限，违反了安全策略。

学习者需要创建 forge/package_policy.py，实现 decide_file 函数，使得脚本在默认情况下被拒绝安装，且即使经过批准也必须以不可执行的状态存储，而普通资源文件则可以安全安装。

先做判断

当 decide_file("scripts/setup.ps1") 被调用且未传入 allow_scripts=True 时，函数应该返回什么样的决策结果？

install=True, executable=True，因为脚本也是包的一部分
install=False, executable=False，因为脚本需要显式批准
install=True, executable=False，因为脚本可以安装但不能执行
install=False, executable=True，因为脚本需要批准但可以执行

判断依据: 正确答案是 install=False 且 executable=False。脚本具有执行副作用的风险，默认策略必须拒绝其安装，并在 reason 中说明需要显式批准。即使后续获得批准，脚本也必须以不可执行的状态存储，执行权限由 Harness 和权限策略另行控制。

它是什么

资源与脚本的本质区别

资源是可读取的静态内容，例如 Markdown 文档、JSON 配置或图片，它们在被安装和读取时不会产生系统副作用。脚本则是包含可执行代码的文件，例如 .ps1 或 .py，一旦被执行就可能修改文件系统、发起网络请求或访问敏感数据。

decide_file 函数的职责是根据路径前缀和调用参数，为每个文件输出一个包含 install、executable 和 reason 的 FileDecision。这个决策模型将安全策略从运行时提前到安装时，确保平台不会无意中引入可执行副作用。

它不是什么

策略边界的常见误解

策略不是仅仅检查文件扩展名，因为 .py 文件既可能是可执行脚本也可能是只读文档片段，因此本阶段使用目录前缀 scripts/ 作为脚本标识。

批准脚本安装并不意味着赋予执行权限，allow_scripts=True 只允许脚本文件被复制到安装目录，但 executable 字段必须始终为 False，实际执行由 Harness 在独立的权限检查中决定。

它与相邻概念的关系

决策与平台执行的依赖关系

decide_file 返回的 FileDecision 是安装器决定是否将文件写入磁盘的依据，而 executable 字段则指导安装器在写入时剥离或保留文件的可执行位。

Harness 负责在安装完成后根据平台策略和用户权限决定是否真正运行某个脚本，因此 package_policy 模块只需关注安装边界的静态属性，不需要也不应该尝试预测运行时上下文。

本阶段的边界决定: 当路径以 scripts/ 开头且 allow_scripts 为 False 时，必须返回 install=False；当路径包含绝对路径或 .. 时，必须因不安全而拒绝；所有通过检查的文件，其 executable 字段必须为 False。

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

教师示范

目标: 演示 decide_file 对 scripts/setup.ps1 返回 install=False 和 executable=False，且 reason 包含 approval。

首先创建 forge/package_policy.py 文件，定义 FileDecision 数据类和 decide_file 函数。函数需要使用 PurePosixPath 解析路径，检查路径安全性，并识别脚本目录。

对于 scripts/setup.ps1，由于它位于 scripts/ 目录下且默认 allow_scripts=False，函数必须返回拒绝安装的决策，并在 reason 中明确指出需要显式批准。

实施步骤

使用 @dataclass(frozen=True) 定义 FileDecision，包含 path、install、executable 和 reason 四个字段。
在 decide_file 中使用 PurePosixPath(path) 解析路径，并检查 item.is_absolute() 或 ".." in item.parts 以拒绝不安全路径。
判断 item.parts[0]=="scripts"，若为真且 allow_scripts 为 False，则返回 FileDecision(path, False, False, "scripts require explicit approval")。

真实 solution 代码: forge/package_policy.py

from dataclasses import dataclass
from pathlib import PurePosixPath

@dataclass(frozen=True)
class FileDecision:
    path: str; install: bool; executable: bool; reason: str

def decide_file(path: str, allow_scripts: bool=False) -> FileDecision:
    item=PurePosixPath(path)
    if item.is_absolute() or ".." in item.parts: return FileDecision(path,False,False,"unsafe path")
    is_script=item.parts and item.parts[0]=="scripts"
    if is_script and not allow_scripts: return FileDecision(path,False,False,"scripts require explicit approval")
    return FileDecision(path,True,False,"resource" if not is_script else "approved script stored non-executable")

python -m pytest -q tests/test_stage.py

运行真实测试

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

为什么这样实现

这一步建立了脚本拒绝策略的核心逻辑：通过目录前缀识别脚本，并在未获得显式批准时拒绝安装。reason 字段中的 approval 关键字为用户提供了明确的反馈。

executable 被硬编码为 False，因为安装策略与执行策略是分离的，即使脚本被批准安装，它也只作为静态内容存在，执行必须经过 Harness 的独立授权。

带提示练习

补全 decide_file 中对 references/api.md 的处理，使其 install=True 且 executable=False。

在 decide_file 函数中，确保不安全路径和脚本拒绝分支之后，存在一个处理普通资源文件的默认返回分支。
对于 references/api.md，它不匹配 scripts/ 前缀，因此不应被脚本拒绝分支拦截。
确保默认返回分支的 install 参数为 True，executable 参数为 False，并在 reason 中说明这是一个资源文件。

逐级提示

检查 is_script 变量在路径为 references/api.md 时的值是什么。
考虑当路径不是脚本且路径安全时，函数应该执行到哪一条 return 语句。
最终的 return 语句应该返回 FileDecision(path, True, False, ...)，其中 reason 可以是 resource。

完成标准

decide_file("references/api.md") 返回的 install 为 True。
decide_file("references/api.md") 返回的 executable 为 False。

故障注入与排查

故障夹具中的 forge/package_policy.py 实现了一个有缺陷的 decide_file 函数，它对所有路径都返回 install=True，并且当路径以 scripts/ 开头时返回 executable=True。这导致 test_script_is_denied_without_explicit_approval 测试失败，因为 scripts/setup.ps1 被错误地接受并标记为可执行。

本阶段要求学习者理解资源与脚本的边界，并通过路径前缀和 allow_scripts 参数实现默认拒绝策略。修复后的 decide_file 函数能够正确识别 scripts/ 前缀，在未获批准时拒绝安装，并确保所有文件的 executable 字段为 False，从而满足测试断言。

已验证的故障合同

目标测试: test_script_is_denied_without_explicit_approval
故障文件: forge/package_policy.py

诊断顺序

运行 python -m pytest -q ../tests/test_stage.py::test_script_is_denied_without_explicit_approval，观察失败信息显示 decision.install 为 True 而非预期的 False。
检查故障源码中的 decide_file 函数，发现它无条件返回 FileDecision(path, True, path.startswith("scripts/"), "accepted")。
识别出该实现没有检查 allow_scripts 参数，也没有区分资源与脚本的安全策略，导致脚本被自动接受并标记为可执行。

修复原则: 修复方案是重写 decide_file 函数，首先使用 PurePosixPath 检查路径安全性，然后判断路径是否属于 scripts/ 目录。如果是脚本且 allow_scripts 为 False，则返回拒绝决策；否则返回 install=True 但 executable=False 的资源决策。这确保了脚本默认被拒绝，且资源永远不会被标记为可执行。

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

迁移挑战

音乐创作场景：Skill 包中包含一个用于导出 MP3 文件的脚本 scripts/export_mp3.py，需要验证该脚本在默认策略下被拒绝安装。

改变的条件: 将测试输入路径从软件交付场景的 scripts/setup.ps1 更改为音乐创作场景的 scripts/export_mp3.py

调用 decide_file("scripts/export_mp3.py")，验证返回的 FileDecision 对象中 install 为 False，executable 为 False，且 reason 字符串中包含 approval。

完成标准

decide_file("scripts/export_mp3.py").install 必须为 False，确认脚本在默认策略下被拒绝安装
decide_file("scripts/export_mp3.py").reason 必须包含 approval，确认拒绝原因指向缺少显式批准

运行真实测试

python -m pytest -q tests/test_stage.py

运行真实测试

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

设计解释题: 为什么即使 allow_scripts=True 使得脚本可以被安装，executable 字段仍然必须为 False？请从安装策略与运行时权限分离的角度解释这一设计决策的因果权衡。

一个有力回答应包含

安装策略只决定文件是否被写入磁盘，不决定文件是否可以被运行
将 executable 固定为 False 确保即使脚本被安装，也不会自动获得执行位
运行时执行由 Harness 根据平台权限策略和用户授权独立控制
这种分离防止了安装阶段的策略失误直接导致代码执行

掌握证据

test_script_is_denied_without_explicit_approval 通过，证明 decide_file 对 scripts/setup.ps1 返回 install=False 且 reason 包含 approval
test_reference_is_installable_but_not_executable 通过，证明 decide_file 对 references/api.md 返回 install=True 且 executable=False
forge/package_policy.py 被正确创建，使用 PurePosixPath 解析路径并区分 scripts/ 前缀与普通资源

STAGE 03

用声明变量渲染 Prompt，并拒绝缺失或未声明变量以避免平台隐式依赖

先看一个具体问题

缺失变量被静默替换为空字符串

在当前起点状态下，forge/prompt_template.py 文件尚不存在，测试文件 tests/test_stage.py 在导入 from forge.prompt_template import render 时会直接抛出 ModuleNotFoundError，导致收集阶段就中断。

本阶段需要新建 forge/prompt_template.py 并实现 render 函数，使其能够从模板中提取变量、校验声明集合与提供的值字典，最终安全地完成字符串替换。

故障树中的 faultySource 展示了一个存在缺陷的初始实现：它在替换时使用 values.get(match.group(1), "")，当模板声明了 goal 变量但值字典中没有提供对应键时，goal 会被静默替换为空字符串，导致渲染后的指令丢失关键信息。

test_missing_declared_value_is_not_silently_blank 测试用例期望在这种情况下抛出包含 missing variables 的 ValueError，而不是静默返回残缺的字符串。

先做判断

当模板为 Review {{workspace}} for {{goal}}，声明集合为 {workspace, goal}，但值字典只提供 {workspace: 'repo'} 时，使用 values.get(name, "") 的实现会产生什么结果？

抛出 ValueError，因为 goal 缺失
返回 ’Review repo for ’，goal 变成空字符串
返回 ‘Review repo for {{goal}}’，原样保留占位符
抛出 KeyError，因为字典中没有 goal 键

判断依据: values.get(name, "") 会在键不存在时返回默认值空字符串，因此不会抛出异常，而是把 goal 替换为空，返回 ’Review repo for ’。这正是需要避免的静默丢失行为。

它是什么

声明式模板渲染的三集合校验模型

render 函数围绕三个集合运作：模板中实际使用的变量集合 used、外部声明的合法变量集合 declared、以及调用方提供的值字典键集合。

渲染前必须依次检查：used 是否为 declared 的子集以拒绝未声明变量，used 是否被 values 完全覆盖以拒绝缺失值，以及 values 是否包含 declared 之外的额外键以拒绝未知值。

只有这三层校验全部通过后，才执行 VARIABLE.sub 替换，且替换时使用 values[match.group(1)] 直接索引而非 .get，确保不会回退到默认值。

它不是什么

模板渲染不是简单的字符串替换

模板渲染不等同于无条件的 str.replace 或带默认值的 dict.get，因为这两种方式都会在变量缺失时静默产生不完整结果而非报错。

声明集合不是可选的装饰性参数，它是平台间可移植性的合同：如果模板使用了未在 declared 中声明的变量，说明该模板依赖了目标平台可能不支持的隐式上下文。

extra 检查不是多余的严格性，它防止调用方误以为某些值会被模板使用但实际上从未出现在模板中，这种不匹配往往意味着调用方与模板版本不一致。

它与相邻概念的关系

render 与 Skill 可移植性的关系

render 函数是 Skill 包中 Prompt 模板跨平台渲染的基础设施：不同平台加载同一个 Skill 时，只要值字典满足声明合同，渲染结果就一致。

forge/package_policy.py 中的 decide_file 决定了文件层面的策略，而 render 在内容层面保证了 Prompt 变量的完整性，两者共同构成 Skill 包的可靠性边界。

VARIABLE 正则表达式 r"{{\s*([a-zA-Z_][a-zA-Z0-9_]*)\s*}}" 定义了模板语法，它允许变量名两侧有空白字符如 {{ workspace }}，这与 test_declared_template_renders_portably 中测试的带空格模板一致。

本阶段的边界决定: 当 used - declared 非空时必须抛出 ValueError 而非忽略未声明变量，因为未声明变量意味着模板依赖了平台合同之外的隐式上下文，静默接受会破坏跨平台可移植性。

实验 ID: skill-agent-packages-03-portable-prompt-template
输入: 软件交付：为前端仓库增加功能、修改代码并补测试。
证据目录: evidence/skill-agent-packages/03-portable-prompt-template/
验收: 待验收

教师示范

目标: 演示 render 在缺少已声明变量值时抛出包含 ‘missing variables’ 的 ValueError，而不是用空字符串静默替换。

测试 test_missing_declared_value_is_not_silently_blank 调用 render('Review {{workspace}} for {{goal}}', {'workspace', 'goal'}, {'workspace': 'repo'})，其中 goal 在声明集合中但值字典缺失。

正确的实现先用 VARIABLE.findall(template) 提取出 {'workspace', 'goal'} 作为 used 集合，然后计算 missing = used - set(values) 得到 {'goal'}，发现非空后抛出 ValueError('missing variables: goal')。

这样测试中的 pytest.raises(ValueError, match='missing variables') 就能匹配到异常消息并通过。

实施步骤

用 VARIABLE.findall(template) 从模板字符串中提取所有变量名，存入 used 集合
计算 missing = used - set(values)，如果 missing 非空则 raise ValueError('missing variables: ' + ','.join(sorted(missing)))
通过校验后用 VARIABLE.sub(lambda match: values[match.group(1)], template) 执行替换，直接用键索引而非 .get

真实 solution 代码: forge/prompt_template.py

import re
VARIABLE=re.compile(r"{{\s*([a-zA-Z_][a-zA-Z0-9_]*)\s*}}")

def render(template: str, declared: set[str], values: dict[str,str]) -> str:
    used=set(VARIABLE.findall(template))
    if used-declared: raise ValueError("undeclared variables: "+",".join(sorted(used-declared)))
    missing=used-set(values)
    if missing: raise ValueError("missing variables: "+",".join(sorted(missing)))
    extra=set(values)-declared
    if extra: raise ValueError("unknown values: "+",".join(sorted(extra)))
    return VARIABLE.sub(lambda match: values[match.group(1)],template)

python -m pytest -q tests/test_stage.py

运行真实测试

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

为什么这样实现

used - set(values) 这个集合差集运算精确地找出了模板需要但调用方未提供的变量名，goal 会被识别为缺失。

抛出异常而非返回空字符串的原因是：如果 goal 被静默替换为空，渲染结果 ’Review repo for ’ 看起来仍然是一个合法字符串，下游消费者无法察觉关键信息丢失，这在 Agent 指令场景中会导致模型收到不完整的任务描述。

带提示练习

补全 render 中对未声明变量的检查，使模板包含 declared 中不存在的变量时抛出包含 ‘undeclared variables’ 的 ValueError。

在 render 函数中，在计算 missing 之前，先用 used - declared 计算未声明变量集合
如果该集合非空，抛出 ValueError，消息以 ’undeclared variables: ’ 开头并附上排序后的变量名列表
确认 extra = set(values) - declared 的检查也存在于函数中，以拒绝提供了但未声明的值

逐级提示

集合差集 used - declared 会返回在模板中使用但未在 declared 集合中声明的变量名
异常消息需要以 ’undeclared variables: ’ 开头，后接用逗号连接的排序变量名
参考 missing 的检查模式：if used-declared: raise ValueError(...)

完成标准

当模板包含 declared 中不存在的变量时，render 抛出 ValueError 且消息包含 ‘undeclared variables’
当模板只使用 declared 中的变量且值字典完整时，render 正常返回渲染后的字符串

故障注入与排查

故障树中的 faultySource 实现了 render 函数，但它在替换时使用 values.get(match.group(1), "")，当 test_missing_declared_value_is_not_silently_blank 传入缺少 goal 值的字典时，goal 被静默替换为空字符串，测试期望的 ValueError 未被抛出。可执行故障夹具修改 forge/prompt_template.py，并由 test_missing_declared_value_is_not_silently_blank 稳定复现。已验证机制标识为 values.get。

本阶段实现的 render 在执行替换前会比较 used、declared 和 set(values) 三个集合，missing = used - set(values) 会发现 goal 缺失并抛出包含 ‘missing variables’ 的 ValueError，从而满足测试的 pytest.raises 断言。

已验证的故障合同

目标测试: test_missing_declared_value_is_not_silently_blank
故障文件: forge/prompt_template.py

诊断顺序

运行 python -m pytest -q ../tests/test_stage.py::test_missing_declared_value_is_not_silently_blank，观察到测试失败，错误信息为 Failed: DID NOT RAISE ValueError
检查 faultySource 中的 render 函数，发现它直接调用 VARIABLE.sub(lambda match: values.get(match.group(1), ""), template)，没有任何前置校验
确认 values.get(match.group(1), "") 在键不存在时返回空字符串而非抛出异常，这就是 goal 消失的直接原因

修复原则: 将 values.get(match.group(1), "") 替换为三集合校验后使用 values[match.group(1)] 直接索引：先计算 used = set(VARIABLE.findall(template))，检查 used - declared 和 missing = used - set(values)，校验通过后用 values[match.group(1)] 替换，这样缺失的 goal 会在 missing 检查中被捕获并抛出 ValueError。

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

迁移挑战

办公研究场景：需要为高管生成一份文档摘要简报，模板为 ‘Summarize {{document}} for {{audience}}’。

改变的条件: 将场景数据从软件交付的 workspace/goal 变量替换为办公研究的 document/audience 变量，模板内容和值字典相应改变但集合大小和结构不变。

调用 render('Summarize {{document}} for {{audience}}', {'document', 'audience'}, {'document': 'Q3-report.pdf', 'audience': 'executives'})，验证返回值为 ‘Summarize Q3-report.pdf for executives’。

完成标准

传入模板 ‘Summarize {{document}} for {{audience}}’，声明集合 {‘document’, ‘audience’}，值字典 {‘document’: ‘Q3-report.pdf’, ‘audience’: ‘executives’} 时，render 返回 ‘Summarize Q3-report.pdf for executives’
当值字典缺少 ‘audience’ 键时，render 抛出 ValueError 且消息包含 ‘missing variables’，保持缺失变量拒绝的不变式

运行真实测试

python -m pytest -q tests/test_stage.py

运行真实测试

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

设计解释题: 为什么未声明的变量会导致错误而不是被静默忽略？请从跨平台可移植性和隐式依赖的角度解释这一设计决策的因果权衡。

一个有力回答应包含

未声明变量意味着模板依赖了目标平台可能不提供的隐式上下文，静默忽略会导致不同平台渲染结果不一致
声明集合是 Skill 包与平台之间的合同，使用未声明变量等于违反合同，应该尽早报错而非产生不可预测的输出
如果允许未声明变量被静默替换为空字符串，下游消费者无法区分’变量值为空’和’变量缺失’两种情况，这会导致调试困难

掌握证据

test_missing_declared_value_is_not_silently_blank 通过，证明 render 在值字典缺少已声明变量时会抛出包含 ‘missing variables’ 的 ValueError 而非静默替换为空字符串
test_declared_template_renders_portably 通过，证明 render 能正确处理模板中变量名两侧的空白字符如 {{ workspace }} 并返回 ‘Review repo’
forge/prompt_template.py 中 render 函数实现了 used - declared、missing = used - set(values) 和 extra = set(values) - declared 三层集合校验，确保模板使用的变量是声明的子集且值字典完整覆盖

STAGE 04

解析包含 ID、版本、入口、文件哈希和权限声明的严格 Manifest

先看一个具体问题

Manifest 不是字典，而是信任边界

在 Stage 04 中，forge/manifest.py 尚不存在，测试文件 tests/test_stage.py 在导入时直接抛出 ModuleNotFoundError: No module named 'forge.manifest'，导致收集阶段就失败。

本阶段的起点代码为空，学习者需要从零创建 forge/manifest.py，实现 Manifest.parse 方法，使其在入口文件不在 files 哈希映射中时抛出包含 entrypoint 的 ValueError。

核心决策在于：Manifest 绝不能被当作宽松的元数据字典来解析，它必须作为 Skill 包的信任边界，拒绝任何未经验证的入口或文件哈希。

先做判断

当 Manifest.parse 收到一个 entrypoint 为 missing.md 但 files 中只有 SKILL.md 的字典时，正确的严格解析器应该做什么？

直接接受并返回 Manifest 对象，因为字段都存在
抛出 ValueError 且消息中包含 entrypoint
自动将 entrypoint 改为 files 中的第一个文件
忽略 entrypoint 字段，使用默认值 SKILL.md

判断依据: 正确答案是抛出 ValueError 且消息中包含 entrypoint。信任边界要求入口必须存在于文件哈希映射中，否则该入口未被内容寻址验证，不能被信任。

它是什么

Manifest 是内容寻址的信任契约

Manifest 是一个不可变数据契约，通过 Manifest.parse 类方法将外部字典转化为受信任的 Manifest 对象，其核心在于解析过程本身就是一次完整的验证。

它要求字段集合精确匹配 id、version、entrypoint、files、permissions 五个键，不多不少，ID 必须匹配小写连字符模式，文件哈希必须是 64 位十六进制字符串。

入口文件必须存在于 files 映射中，这意味着入口本身也是内容寻址的，攻击者无法注入一个未被哈希验证的入口文件。

它不是什么

Manifest 不是宽松的元数据容器

Manifest 不是简单的字典包装器，不能使用 payload.get 提供默认值来跳过缺失字段，否则攻击者可以省略关键字段并让解析器静默填充。

它也不是一个通用的配置解析器，不会容忍多余字段或格式不规范的哈希值，任何偏差都应导致 ValueError 而非静默修正。

Manifest 的验证不依赖于外部工具链的后续步骤，解析本身必须是原子性的信任决策点。

它与相邻概念的关系

字段验证与入口存在性检查的因果关系

字段集合检查是第一道防线，确保没有多余或缺失的键，这防止了攻击者通过注入未知字段来绕过后续验证逻辑。

哈希格式验证与入口存在性检查形成因果链：只有当 files 中的每个值都是合法的 64 位十六进制哈希时，入口存在性检查才有意义，因为内容寻址依赖于哈希的完整性。

entrypoint 必须是 files 映射的键，这建立了入口文件与其内容哈希之间的强绑定，使得 Harness 在安装时可以验证入口文件内容是否与声明的哈希匹配。

本阶段的边界决定: 当 payload 的键集合不等于 {'id','version','entrypoint','files','permissions'} 时，必须立即抛出 ValueError，绝不能使用默认值填充缺失字段或忽略多余字段。

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

教师示范

目标: 演示 Manifest.parse 在入口文件不在 files 映射中时抛出 ValueError，且消息包含 entrypoint。

测试 test_entrypoint_must_be_content_addressed 构造了一个合法的 manifest 字典，然后将 entrypoint 改为 missing.md，这个键不存在于 files 映射中。

解析器必须在此时抛出 ValueError，因为 missing.md 没有对应的内容哈希，这意味着入口文件未被内容寻址，不能被信任为包的入口。

这一行为将 Manifest 从元数据字典提升为信任边界：入口的存在性检查是防止未验证文件被安装的关键机制。

实施步骤

检查 payload 的键集合是否精确等于 {'id','version','entrypoint','files','permissions'}，不匹配则抛出 ValueError。
验证 id 是否匹配 ^[a-z0-9]+(?:-[a-z0-9]+)*$ 模式，验证 files 中每个值是否匹配 ^[0-9a-f]{64}$ 模式。
检查 payload['entrypoint'] 是否是 files 映射的键，不是则抛出包含 entrypoint 的 ValueError。
构造并返回冻结的 Manifest 数据类实例。

真实 solution 代码: forge/manifest.py

from dataclasses import dataclass
import re
ID=re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$"); SHA=re.compile(r"^[0-9a-f]{64}$")
@dataclass(frozen=True)
class Manifest:
    id: str; version: str; entrypoint: str; files: dict[str,str]; permissions: tuple[str,...]
    @classmethod
    def parse(cls,payload: dict[str,object]) -> "Manifest":
        required={"id","version","entrypoint","files","permissions"}
        if set(payload)!=required: raise ValueError("manifest fields do not match contract")
        if not ID.fullmatch(str(payload["id"])): raise ValueError("invalid id")
        files=dict(payload["files"])
        if not files or any(not SHA.fullmatch(str(value)) for value in files.values()): raise ValueError("invalid file hash")
        if payload["entrypoint"] not in files: raise ValueError("entrypoint missing from files")
        return cls(str(payload["id"]),str(payload["version"]),str(payload["entrypoint"]),files,tuple(payload["permissions"]))

python -m pytest -q tests/test_stage.py

运行真实测试

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

为什么这样实现

入口存在性检查发生在字段集合和哈希格式验证之后，这确保了当检查到入口时，files 映射本身已经是一个经过验证的、只包含合法 64 位哈希的字典。

如果入口检查失败，说明攻击者试图让包使用一个未被内容寻址的文件作为入口，抛出 ValueError 阻断了这种攻击路径，使 Manifest 成为真正的信任边界。

带提示练习

补全 Manifest.parse 中对文件哈希格式的验证，使 files 中存在非 64 位十六进制哈希时被拒绝。

在 forge/manifest.py 中定义 SHA 正则表达式 re.compile(r"^[0-9a-f]{64}$")。
在字段集合检查和 ID 模式验证通过之后、入口存在性检查之前，使用 any(not SHA.fullmatch(str(value)) for value in files.values()) 验证所有文件哈希格式。
如果存在不匹配 64 位十六进制模式的哈希值，抛出 ValueError("invalid file hash")。
运行 python -m pytest -q tests/test_stage.py::test_valid_manifest_is_parsed 确认合法 manifest（files 中 SKILL.md 的哈希为 64 位 a）仍能通过。

逐级提示

提示：ID 必须匹配 ^[a-z0-9]+(?:-[a-z0-9]+)*$ 模式，即小写字母、数字和连字符段，不允许大写字母或特殊字符。
提示：ID 验证应在字段集合检查之后执行，确保 payload["id"] 存在后再进行模式匹配。
提示：合法的 forge-requirements 符合该模式，而 Forge_Requirements 或 forge.requirements 应被拒绝。

完成标准

test_valid_manifest_is_parsed 通过，因为合法 manifest 的 files 中 SKILL.md 的哈希为 64 位 a，匹配 SHA 正则模式。
如果传入的 files 中存在非 64 位十六进制哈希（如 "short"），Manifest.parse 会抛出 ValueError 而非静默接受。

故障注入与排查

故障实验室提供的 faulty/forge/manifest.py 完全没有字段或哈希验证，parse 方法仅用 payload.get 做字典强制转换。当运行 test_entrypoint_must_be_content_addressed 时，测试期望抛出包含 entrypoint 的 ValueError，但 faulty 代码直接接受了 missing.md 作为入口，导致 pytest.raises 断言 DID NOT RAISE ValueError 而失败。

本阶段教授的严格 Manifest 契约要求 entrypoint 必须存在于 files 映射中，这正是 faulty 代码缺失的机制。通过在 Manifest.parse 中添加 if payload["entrypoint"] not in files: raise ValueError("entrypoint missing from files")，可以确保未验证的入口被拒绝，使 test_entrypoint_must_be_content_addressed 通过。

已验证的故障合同

目标测试: test_entrypoint_must_be_content_addressed
故障文件: forge/manifest.py

诊断顺序

运行 python -m pytest -q ../tests/test_stage.py::test_entrypoint_must_be_content_addressed，观察输出 DID NOT RAISE ValueError。
检查 faulty/forge/manifest.py 的 parse 方法，发现它直接用 payload.get("entrypoint","SKILL.md") 取值并构造对象，没有任何存在性检查。
对比测试期望：测试将 entrypoint 设为 missing.md，期望解析器检测到它不在 files 中并抛出异常，但 faulty 代码跳过了这一检查。

修复原则: 修复方法是在 Manifest.parse 中添加入口存在性检查：在完成字段集合验证和哈希格式验证后，添加 if payload["entrypoint"] not in files: raise ValueError("entrypoint missing from files")。这确保了入口必须是 files 映射的键，从而将入口绑定到内容哈希上，阻止未验证的入口被接受。

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

迁移挑战

音乐创作场景：一个 Skill 包用于整理曲目信息和发行计划，其 manifest 的 id 为 music-release，version 为 1.0.0，entrypoint 为 SKILL.md，files 包含 SKILL.md 的 64 位哈希，permissions 为空列表。但有人误在 manifest 字典中添加了一个多余字段 author，需要验证 Manifest.parse 拒绝该不精确字段集合。

改变的条件: 在 manifest 字典中添加多余字段 author，验证 Manifest.parse 的精确字段集合检查分支拒绝多余键，这与合法 manifest 的五键精确匹配路径不同。

构造一个 manifest 字典，id 为 music-release，version 为 1.0.0，entrypoint 为 SKILL.md，files 为 {"SKILL.md": "b"*64}，permissions 为 []，并额外添加一个多余字段 author: "producer"，调用 Manifest.parse 并确认抛出 ValueError。

完成标准

构造的 manifest 字典包含多余字段 author，使其键集合不等于 {'id','version','entrypoint','files','permissions'}，触发精确字段集合检查分支
Manifest.parse 抛出 ValueError，拒绝包含多余字段的 manifest，证明字段集合检查是信任边界的第一道防线

运行真实测试

python -m pytest -q tests/test_stage.py

运行真实测试

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

设计解释题: 为什么入口文件必须存在于 files 哈希映射中，而不是仅仅存在于包目录中？请从内容寻址和信任边界的角度解释这一设计决策的因果权衡。

一个有力回答应包含

入口存在于 files 映射中意味着入口文件有对应的声明哈希，Harness 可以在安装时验证文件内容是否与哈希匹配，防止篡改。
如果仅检查文件存在于目录中，攻击者可以在打包后替换入口文件内容，而 Manifest 无法检测这种篡改，因为缺少内容绑定。

掌握证据

test_entrypoint_must_be_content_addressed 通过，证明 Manifest.parse 在 entrypoint 不在 files 中时抛出包含 entrypoint 的 ValueError。
test_valid_manifest_is_parsed 通过，证明合法 manifest 字典（id 为 forge-requirements，哈希为 64 位 a）被正确解析为 Manifest 对象。
forge/manifest.py 中的 ID 和 SHA 正则表达式确保了 ID 模式和哈希格式的严格验证，使 Manifest 成为内容寻址的信任边界。

STAGE 05

解析 SemVer 并根据主版本判断升级是否需要迁移

先看一个具体问题

Skill 升级时主版本变化未被识别为需要迁移

在当前的 forge/versioning.py 故障实现中，upgrade_kind 函数无条件返回 compatible-upgrade，导致从 1.4.2 升级到 2.0.0 时未触发迁移要求。

测试用例 test_major_upgrade_requires_migration 期望主版本号变化时返回 migration-required，但实际返回了 compatible-upgrade，断言失败。

根本原因在于版本元数据虽然被解析并存储在 Version 数据类中，但并未与兼容性语义建立因果联系，主版本号的变化没有驱动分类逻辑。

先做判断

当 upgrade_kind("1.4.2", "2.0.0") 被调用时，故障代码返回 compatible-upgrade。你认为要修复此问题，核心逻辑应基于哪个版本号分量的比较？

仅比较补丁号是否变化
比较主版本号是否不同
比较次版本号是否递增
比较完整版本字符串的字典序

判断依据: 正确思路是比较主版本号。根据 SemVer 规范，主版本号变化代表不兼容的 API 变更，必须返回 migration-required，而次版本号和补丁号变化属于兼容升级。

它是什么

语义版本号（SemVer）的兼容性判定模型

语义版本号由主版本、次版本和补丁三个数字分量组成，主版本号变化表示不兼容的 API 修改，次版本号变化表示向后兼容的新功能，补丁号变化表示向后兼容的缺陷修复。

upgrade_kind 函数通过 parse_version 将版本字符串解析为 Version 数据类对象，然后比较左右两端的主版本号来判定升级类型，主版本号不同则返回 migration-required，否则返回 compatible-upgrade。

它不是什么

SemVer 判定模型的边界

版本兼容性判定不是简单的字符串比较或字典序比较，因为 2.0.0 在字典序上大于 1.9.9 但这并不直接表达 API 兼容性语义。

upgrade_kind 不是对任意版本格式生效的通用解析器，它严格依赖正则表达式 PATTERN 匹配标准 SemVer 格式，无法处理非数字前缀或缺失分量的字符串。

它与相邻概念的关系

版本解析与升级分类的因果链

parse_version 函数使用正则表达式 PATTERN 提取数字分量并构造 Version 对象，Version 使用 @dataclass(frozen=True, order=True) 装饰器从而支持基于元组的自然大小比较。

upgrade_kind 依赖 parse_version 的输出，先通过 right <= left 拦截非递增目标版本，再通过 right.major != left.major 将主版本差异映射为 migration-required，形成从字符串到分类结果的完整因果链。

本阶段的边界决定: 当目标版本的主版本号与当前版本不同时，无论次版本或补丁号如何变化，都必须判定为需要迁移，因为主版本号变化在 SemVer 中是破坏性 API 变更的唯一标志。

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

教师示范

目标: 演示 upgrade_kind('1.4.2', '2.0.0') 返回 'migration-required'，验证主版本号变化触发迁移判定。

首先调用 parse_version('1.4.2') 和 parse_version('2.0.0')，正则表达式 PATTERN 匹配成功并分别返回 Version(major=1, minor=4, patch=2) 和 Version(major=2, minor=0, patch=0)。

随后 upgrade_kind 检查 right <= left，由于 2.0.0 大于 1.4.2，条件不成立，继续比较 right.major != left.major，即 2 != 1 为真，函数返回 migration-required。

实施步骤

调用 parse_version 将字符串 1.4.2 和 2.0.0 解析为 Version 对象
比较 right.major 和 left.major，发现 2 != 1
返回 migration-required 表示主版本变化需要迁移

真实 solution 代码: forge/versioning.py

from dataclasses import dataclass
import re
PATTERN=re.compile(r"^(0|[1-9]d*).(0|[1-9]d*).(0|[1-9]d*)(?:-([0-9A-Za-z.-]+))?$")
@dataclass(frozen=True,order=True)
class Version:
    major: int; minor: int; patch: int; prerelease: str=""

def parse_version(text: str) -> Version:
    match=PATTERN.fullmatch(text)
    if not match: raise ValueError("invalid semantic version")
    return Version(int(match[1]),int(match[2]),int(match[3]),match[4] or "")

def upgrade_kind(current: str, target: str) -> str:
    left=parse_version(current); right=parse_version(target)
    if right<=left: raise ValueError("target version must be newer")
    return "migration-required" if right.major!=left.major else "compatible-upgrade"

python -m pytest -q tests/test_stage.py

运行真实测试

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

为什么这样实现

主版本号从 1 变为 2，根据 SemVer 规范这意味着存在不兼容的 API 变更，因此 right.major != left.major 条件为真，函数返回 migration-required。

Version 数据类使用 order=True，使得 right <= left 的比较基于 (major, minor, patch) 元组自然排序，确保只有目标版本严格大于当前版本时才继续分类逻辑。

带提示练习

补全 upgrade_kind 中对目标版本必须严格大于当前版本的检查，使相同或更低版本抛出 ValueError。

在 upgrade_kind 函数中调用 parse_version 获取 left 和 right 两个 Version 对象
添加条件判断：如果 right <= left 则抛出 ValueError 并附带描述性消息
确保该检查在主版本号比较逻辑之前执行，防止无效升级路径进入分类逻辑

逐级提示

利用 Version 数据类 order=True 特性，直接使用 <= 运算符比较两个 Version 对象
抛出异常时使用 raise ValueError("target version must be newer") 提供清晰的错误信息
将版本有效性检查放在兼容性分类逻辑之前，遵循前置校验原则

完成标准

当调用 upgrade_kind("1.4.2", "1.4.2") 时抛出 ValueError
当调用 upgrade_kind("2.0.0", "1.4.2") 时抛出 ValueError

故障注入与排查

在 fixtures/failure.json 定义的故障实现中，forge/versioning.py 的 upgrade_kind 函数无条件返回 compatible-upgrade。运行 test_major_upgrade_requires_migration 测试时，断言 upgrade_kind("1.4.2", "2.0.0") == "migration-required" 失败，实际得到 compatible-upgrade。

本阶段通过在 upgrade_kind 中引入 parse_version 解析和 right.major != left.major 比较，将版本元数据与兼容性语义直接关联。该机制精确覆盖了故障代码中缺失的主版本号判定逻辑，使 test_major_upgrade_requires_migration 测试通过。

已验证的故障合同

目标测试: test_major_upgrade_requires_migration
故障文件: forge/versioning.py

诊断顺序

查看 faultySource 中 upgrade_kind 的实现，发现函数体仅包含 return "compatible-upgrade"，没有任何版本比较逻辑
运行 python -m pytest -q ../tests/test_stage.py::test_major_upgrade_requires_migration，确认测试失败并输出 AssertionError: assert 'compatible-upgrade' == 'migration-required'
检查 parse_version 函数确认其能正确解析版本字符串，但 upgrade_kind 未调用其结果进行主版本号比较

修复原则: 修复方案是在 upgrade_kind 中调用 parse_version 解析 current 和 target 字符串，先检查 right <= left 抛出 ValueError，再通过 right.major != left.major 判定是否返回 migration-required。该修复将版本元数据与兼容性语义直接关联，使主版本号变化正确触发迁移要求。

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

迁移挑战

软件交付场景中，前端仓库的 Skill 包当前版本为 2.3.1，计划升级到 2.4.0。

改变的条件: 将输入版本数据从主版本变化场景替换为次版本变化场景，从 1.4.2 到 2.0.0 改为 2.3.1 到 2.4.0

调用 upgrade_kind("2.3.1", "2.4.0")，验证主版本号相同且目标版本更高时返回 compatible-upgrade，确认次版本升级不需要迁移。

完成标准

upgrade_kind("2.3.1", "2.4.0") 返回 compatible-upgrade 而非 migration-required
目标版本 2.4.0 的主版本号 2 与当前版本 2.3.1 的主版本号 2 相同，保持兼容性不变量

运行真实测试

python -m pytest -q tests/test_stage.py

运行真实测试

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

设计解释题: 为什么在 upgrade_kind 中先执行 right <= left 的前置校验，再比较主版本号？如果调换这两个检查的顺序会导致什么边界问题？

一个有力回答应包含

前置校验防止目标版本低于或等于当前版本时进入分类逻辑，避免产生无意义的升级判定
如果先比较主版本号，当目标版本低于当前版本但主版本号不同时，会错误返回 migration-required 而非抛出 ValueError
Version 的 order=True 基于元组比较，确保版本大小判定与 SemVer 语义一致

掌握证据

test_major_upgrade_requires_migration 通过，验证 upgrade_kind("1.4.2", "2.0.0") 返回 migration-required
test_minor_upgrade_is_compatible 通过，验证 upgrade_kind("1.4.2", "1.5.0") 返回 compatible-upgrade
parse_version 使用正则表达式 PATTERN 严格校验 SemVer 格式，无效字符串抛出 ValueError
upgrade_kind 中 right <= left 检查确保目标版本必须严格大于当前版本

STAGE 06

根据平台能力、所需功能和最低客户端版本给出兼容或缺口报告

先看一个具体问题

Skill 在目标平台上总是被误判为兼容

在当前代码变更之前，项目中不存在 forge/compatibility.py 文件，因此测试在收集阶段就会因为 ModuleNotFoundError: No module named 'forge.compatibility' 而中断。

为了通过测试，我们需要创建该文件并实现 compatibility 函数。然而，如果仅仅让该函数无条件返回 True, []，就会产生一个更隐蔽的工程缺陷：平台即使缺少所需功能，也会被错误地标记为兼容。

test_missing_platform_feature_is_reported 测试用例明确要求，当平台 Platform("codex", "1.2.0", frozenset({"prompts"})) 缺少 resources 功能时，函数必须返回 ok=False 且 gaps 包含 "missing feature: resources"。

本阶段的核心任务是建立一种机制，通过比较平台实际拥有的功能集与所需功能集，以及比较客户端版本与最低版本要求，来产生精确的缺口报告。

先做判断

当 compatibility 函数接收到一个客户端版本满足要求但功能集不完整的平台时，如果函数内部完全没有执行任何集合比较逻辑，测试断言 ok is False and gaps == ["missing feature: resources"] 会发生什么？

断言成功，因为版本满足要求就默认功能兼容
断言失败，因为 ok 的实际值是 True 而不是 False
抛出 KeyError，因为 resources 不在平台功能集中
抛出 TypeError，因为无法对 frozenset 和 set 进行减法运算

判断依据: 正确答案是断言失败。如果函数无条件返回 True, []，那么 ok 的值就是 True，而断言期望它是 False，因此 assert (True is False) 会触发 AssertionError。这说明兼容性不能仅凭存在性判断，必须进行实质性的集合差异比较。

它是什么

兼容性评估模型

兼容性评估是一个基于集合差异和版本比较的确定性计算过程。它接收目标平台的当前状态（包括功能集和客户端版本号）以及 Skill 的硬性需求（所需功能和最低版本），输出一个布尔值和一个缺口列表。

在这个模型中，required_features - platform.features 的差集直接暴露了平台缺失的功能，而 parse_version 函数将版本字符串转换为可比较的元组，从而确定客户端版本是否低于最低要求。

它不是什么

兼容性评估的边界

兼容性评估不是简单地检查平台名称是否存在，也不是一种基于启发式的模糊猜测。它不负责自动安装缺失的功能或升级客户端版本。

该机制不涉及对平台运行时性能的评估，也不检查 Skill 中附带脚本是否被平台信任执行；这些属于 Harness 和权限策略的范畴，超出了本阶段纯数据比较的边界。

它与相邻概念的关系

组件间的依赖关系

compatibility 函数依赖于 forge.versioning 模块中的 parse_version 函数来将版本字符串（如 “1.2.0”）解析为可比较的数值结构。

Platform 数据类作为输入数据的载体，其 features 字段必须是 frozenset 类型，以便进行高效的集合运算，而 required_features 作为 set 传入，两者相减产生缺失功能的迭代器。

缺口列表的生成顺序由 sorted() 函数保证，这使得测试断言可以精确匹配列表内容，避免了集合无序性导致的测试不稳定问题。

本阶段的边界决定: 当平台功能集是 required_features 的真子集时，必须立即判定为不兼容并报告缺失的具体功能项，即使客户端版本满足要求也不能改变这一结论。

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

教师示范

目标: 演示当平台缺少 resources 功能时，compatibility 函数如何计算集合差集并返回包含 "missing feature: resources" 的缺口列表。

我们首先关注 test_missing_platform_feature_is_reported 测试用例。该测试传入了一个只包含 "prompts" 功能的平台，但所需功能是 {"prompts", "resources"}。

为了使函数正确报告缺口，我们需要计算 required_features - platform.features，即 {"prompts", "resources"} - {"prompts"}，结果为 {"resources"}。

然后我们将这个差集中的每个元素格式化为 "missing feature: {item}" 字符串，并追加到 gaps 列表中。由于 gaps 列表非空，函数最终返回 not gaps（即 False）和 gaps 列表。

实施步骤

定义 Platform 数据类，包含 id、client_version 和 features 字段。
初始化 gaps 为空列表，用于收集所有不满足条件的缺口。
计算 required_features - platform.features 并对结果排序，将每个缺失功能格式化为字符串追加到 gaps 中。
返回 (not gaps, gaps)，其中 not gaps 在有缺口时为 False。

真实 solution 代码: forge/compatibility.py

from dataclasses import dataclass
from forge.versioning import parse_version
@dataclass(frozen=True)
class Platform:
    id: str; client_version: str; features: frozenset[str]

def compatibility(platform: Platform, required_features: set[str], min_version: str) -> tuple[bool,list[str]]:
    gaps=[]
    if parse_version(platform.client_version)<parse_version(min_version): gaps.append(f"requires client {min_version}")
    gaps.extend(f"missing feature: {item}" for item in sorted(required_features-platform.features))
    return not gaps,gaps

python -m pytest -q tests/test_stage.py

运行真实测试

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

为什么这样实现

在这个例子中，集合差集运算是核心机制。sorted() 函数确保了当有多个缺失功能时，它们在列表中的顺序是确定的，这使得 gaps == ["missing feature: resources"] 这样的精确断言能够稳定通过。

注意 return not gaps 的逻辑：当 gaps 列表为空时，not gaps 为 True，表示完全兼容；当 gaps 中有任何元素时，not gaps 为 False，表示存在不兼容的缺口。

带提示练习

在已实现功能缺口检查的基础上，补全 compatibility 函数中对客户端版本低于最低要求的检查，使 gaps 包含 "requires client 1.0.0"。

查看 test_old_client_is_reported_separately 测试用例，注意它传入的客户端版本是 "0.9.0"，最低要求是 "1.0.0"。
在函数开头，使用 forge.versioning 中的 parse_version 函数比较 platform.client_version 和 min_version。
如果客户端版本低于最低版本，将 f"requires client {min_version}" 追加到 gaps 列表中。

逐级提示

parse_version 函数将版本字符串转换为可比较的元组，可以直接使用 < 运算符进行比较。
注意缺口追加的顺序：版本检查应该在功能检查之前执行，这样 gaps 列表的顺序才能与测试期望一致。
使用 gaps.append(f"requires client {min_version}") 来添加版本缺口。

完成标准

test_old_client_is_reported_separately 测试通过，且 gaps 中包含 "requires client 1.0.0"。
当版本不足且功能缺失同时存在时，版本缺口应排在功能缺口之前。

故障注入与排查

在 fixtures/failure.json 指定的故障场景中，forge/compatibility.py 的 compatibility 函数被注入了 Return true with no gaps 缺陷。这导致 test_missing_platform_feature_is_reported 测试失败，因为一个缺少 resources 功能的平台被错误地报告为完全兼容。

本阶段建立的集合比较机制能够直接解决该问题。通过执行 required_features - platform.features 运算，我们可以精确识别出平台缺失的功能，并将其作为缺口报告。当 gaps 列表非空时，not gaps 会返回 False，从而正确地将平台标记为不兼容。

已验证的故障合同

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

诊断顺序

运行 python -m pytest -q ../tests/test_stage.py::test_missing_platform_feature_is_reported，观察失败输出 assert (True is False)。
检查 forge/compatibility.py 中的 compatibility 函数，发现它直接返回 True, []，没有执行任何比较逻辑。
确认测试输入的平台功能集为 frozenset({"prompts"})，而所需功能为 {"prompts", "resources"}，两者存在差异。

修复原则: 修复方法是移除 return True, []，替换为实际的比较逻辑。首先使用 parse_version 检查版本，然后计算 required_features - platform.features 的差集，将缺失功能格式化后追加到 gaps 列表，最后返回 not gaps, gaps。这样当平台缺少 resources 时，gaps 将包含 "missing feature: resources"，且 ok 为 False。

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

迁移挑战

办公研究场景：使用 compatibility 评估平台 Platform('office-agent', '1.5.0', frozenset({'prompts', 'resources'})) 对所需功能 {'prompts', 'resources', 'tools'} 和最低版本 '1.0.0' 的兼容性。

改变的条件: 将测试输入的平台功能集从仅缺少 ‘resources’ 改变为缺少 ‘tools’ 功能，同时保持客户端版本满足要求。

调用 compatibility(Platform('office-agent', '1.5.0', frozenset({'prompts', 'resources'})), {'prompts', 'resources', 'tools'}, '1.0.0')，验证返回的 gaps 列表中包含 "missing feature: tools" 且 ok 为 False。

完成标准

传入参数中平台功能集为 frozenset({'prompts', 'resources'})，所需功能集包含 tools
返回结果中 ok 必须为 False，且 gaps 必须等于 ["missing feature: tools"]

运行真实测试

python -m pytest -q tests/test_stage.py

运行真实测试

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

设计解释题: 为什么在 compatibility 函数中需要同时检查功能集差集和客户端版本，而不是只检查其中一项就返回结果？请结合缺口列表的累积机制说明这种设计的因果权衡。

一个有力回答应包含

只检查功能集会导致版本过低的客户端被误判为兼容，只检查版本会导致功能缺失被忽略。
累积缺口到同一个列表中可以一次性报告所有不兼容原因，避免调用方需要多次试探。
sorted() 保证了功能缺口报告的顺序确定性，而版本检查在前保证了多缺口时的列表顺序稳定。

掌握证据

test_missing_platform_feature_is_reported 测试通过，证明 compatibility 函数能正确识别 required_features - platform.features 的差集并报告 "missing feature: resources"。
test_old_client_is_reported_separately 测试通过，证明 parse_version 比较逻辑能正确识别低于 min_version 的客户端并报告 "requires client 1.0.0"。
forge/compatibility.py 中的 return not gaps, gaps 逻辑确保了只要 gaps 列表非空，ok 就为 False，从而避免了兼容性元数据成为装饰性判断。

STAGE 07

为三场景生成排序稳定、哈希可复核且不自动执行脚本的发布清单

先看一个具体问题

发布清单缺失场景完整性校验导致部分场景被接受

在当前的代码起点中，forge/packaging.py 文件尚未创建，测试在收集阶段就会因为 ModuleNotFoundError: No module named 'forge.packaging' 而中断。作为开发者，你需要从零创建该模块，并实现 build_inventory 函数以生成确定性的发布清单。

在构建故障实验室的缺陷代码时，build_inventory 函数完全忽略了传入的 scenarios 参数，直接对文件字典进行遍历并返回清单。这导致当调用者仅传入 {'software', 'office'} 时，系统仍然会生成发布清单，从而接受了不完整的场景包。

根据本模块的里程碑要求，发布清单必须强制覆盖 software、office 和 music 这三个场景。如果场景集合与要求不符，函数必须抛出包含特定错误信息的 ValueError 异常，以阻止不完整包的发布。

先做判断

当 build_inventory 函数接收到 {'software', 'office'} 作为场景参数时，为了保证发布清单的完整性，该函数应当采取什么行为？

直接返回空列表以跳过不完整的场景
抛出包含 ‘software, office, and music’ 的 ValueError 异常
自动补全缺失的 music 场景并继续生成清单
仅打印警告信息并正常返回清单

判断依据: 正确的做法是立即中断执行并抛出 ValueError 异常，因为发布清单的契约要求恰好包含三个场景，任何缺失都意味着包不完整，不能通过校验。

它是什么

确定性发布清单的构建契约

确定性发布清单是 Skill 包中所有文件的有序记录，每个条目包含文件路径、基于文件内容计算的 SHA-256 哈希值以及可执行标志。它通过固定的排序规则和哈希校验，确保相同的输入文件集合在任何时间、任何环境下都能生成完全相同的清单输出。

在本阶段中，确定性还体现在场景完整性约束上：build_inventory 必须要求传入的 scenarios 参数恰好等于 {'software', 'office', 'music'}，并在生成清单前进行严格校验，从而在打包阶段拦截不完整的场景配置。

它不是什么

发布清单不是简单的文件列表拷贝

发布清单不是对输入文件字典的直接遍历输出，因为字典的插入顺序在不同运行中可能不同，这会破坏确定性。同时，它也不是一个可以自动执行附带脚本的机制，所有文件的 executable 标志必须被硬编码为 False。

此外，场景校验不是一种软性建议或可忽略的警告，而是强制性的前置条件。函数不能在场景不匹配时静默补全或返回降级结果，必须通过抛出异常来明确拒绝不符合契约的输入。

它与相邻概念的关系

场景校验、路径排序与哈希计算的协同

场景校验是生成清单的第一道防线，它决定了函数是否继续执行；路径排序是确定性的核心机制，通过对文件名进行字典序排序，保证了输出列表的顺序稳定；哈希计算则为每个文件提供了内容级别的可复核性。

这三者协同工作：场景校验拦截不完整的包，路径排序保证输出顺序的确定性，而哈希值和 executable 标志则确保了文件内容的可追溯性和安全性。如果缺少场景校验，即使排序和哈希正确，也会产生不完整的清单。

本阶段的边界决定: 当 scenarios 参数不等于 {'software', 'office', 'music'} 时，函数必须立即抛出 ValueError 异常，绝不能进入文件遍历和清单生成阶段。

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

教师示范

目标: 演示 build_inventory 在场景集缺少 music 时抛出包含 ‘software, office, and music’ 的 ValueError 异常。

为了实现场景完整性校验，我们需要在 build_inventory 函数的入口处设置一道关卡。当传入的 scenarios 集合与模块级常量 REQUIRED_SCENARIOS 不匹配时，函数必须立即中断执行。

这通过 if scenarios != REQUIRED_SCENARIOS: raise ValueError(...) 实现，该条件判断确保了只有覆盖全部三个场景的包才能进入后续的清单生成流程，从而在源头阻止部分场景包的发布。

实施步骤

在 forge/packaging.py 顶部定义常量 REQUIRED_SCENARIOS = {'software', 'office', 'music'}。
在 build_inventory 函数体第一行添加 if scenarios != REQUIRED_SCENARIOS: raise ValueError('package must cover software, office, and music')。
确保异常信息中包含 ‘software, office, and music’ 字符串，以满足测试断言要求。

真实 solution 代码: forge/packaging.py

from hashlib import sha256
from pathlib import PurePosixPath

REQUIRED_SCENARIOS={"software","office","music"}

def build_inventory(files: dict[str,bytes], scenarios: set[str]) -> list[dict[str,object]]:
    if scenarios!=REQUIRED_SCENARIOS: raise ValueError("package must cover software, office, and music")
    inventory=[]
    for name in sorted(files):
        item=PurePosixPath(name)
        if item.is_absolute() or ".." in item.parts: raise ValueError("unsafe package path")
        inventory.append({"path":name,"sha256":sha256(files[name]).hexdigest(),"executable":False})
    if "SKILL.md" not in files: raise ValueError("missing SKILL.md")
    return inventory

python -m pytest -q tests/test_stage.py

运行真实测试

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

为什么这样实现

通过在函数入口处设置场景集合的严格匹配判断，我们确保了任何缺少场景的调用都会被拦截。这直接满足了 test_package_requires_all_three_scenarios 测试中 except ValueError as error: assert 'software, office, and music' in str(error) 的断言要求。

这种前置校验模式将失败快速暴露在调用边界，避免了后续无效的文件遍历和哈希计算，符合防御式编程的设计原则。

带提示练习

补全 build_inventory 中对文件路径排序和 executable 标志的设置，使输出按路径排序且所有 executable 为 False。

使用 sorted(files) 获取排序后的文件名列表，并遍历该列表构建清单。
对于每个文件，使用 sha256(files[name]).hexdigest() 计算其哈希值。
在构建每个条目的字典时，将 executable 键的值硬编码为 False，而不是基于文件路径进行推断。

逐级提示

Python 字典的 items() 或 keys() 方法不保证顺序，考虑使用内置的 sorted() 函数。
回顾故障代码中 executable 标志是如何被错误设置的：name.startswith('scripts/')，你需要将其改为固定值。
确保最终返回的列表中，每个字典的 path 键对应排序后的文件名。

完成标准

调用 build_inventory 返回的列表中，item['path'] 的顺序必须与 sorted(files.keys()) 完全一致。
返回列表中所有 item['executable'] 的值必须全等于 False，无论文件路径是否以 scripts/ 开头。

故障注入与排查

在故障实验室中，forge/packaging.py 的 build_inventory 函数完全忽略了传入的 scenarios 参数。当测试调用 build_inventory({'SKILL.md': b'x'}, {'software', 'office'}) 时，函数没有抛出异常，而是直接生成了发布清单，导致 test_package_requires_all_three_scenarios 测试失败。

本阶段要求在函数入口处添加场景集合的严格匹配校验。通过引入 REQUIRED_SCENARIOS 常量并进行比较，可以确保当传入的场景集合不等于 {'software', 'office', 'music'} 时，函数抛出 ValueError 异常，从而修复该缺陷。

已验证的故障合同

目标测试: test_package_requires_all_three_scenarios
故障文件: forge/packaging.py

诊断顺序

运行 python -m pytest -q ../tests/test_stage.py::test_package_requires_all_three_scenarios，观察测试失败信息。
查看失败信息中的 AssertionError: partial scenario package accepted，这表明函数在场景不完整时没有抛出异常。
检查 forge/packaging.py 源码，发现 build_inventory 函数中没有任何对 scenarios 参数的校验逻辑。

修复原则: 在 build_inventory 函数的第一行添加场景校验逻辑：定义常量 REQUIRED_SCENARIOS = {'software', 'office', 'music'}，并在函数入口处添加 if scenarios != REQUIRED_SCENARIOS: raise ValueError('package must cover software, office, and music')。这样当传入 {'software', 'office'} 时，函数会立即抛出包含正确信息的异常，阻止不完整清单的生成。

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

迁移挑战

使用 build_inventory 为音乐创作场景生成清单，文件包含 SKILL.md、references/chords.md 和 scripts/export.py，场景集为 {'software','office','music'}。

改变的条件: 将输入文件集合替换为音乐创作场景的三个文件，验证排序和可执行标志在新的文件路径下仍然正确。

调用 build_inventory({'SKILL.md': b'skill', 'references/chords.md': b'chords', 'scripts/export.py': b'export'}, {'software', 'office', 'music'})，并验证返回列表的路径顺序和可执行标志。

完成标准

返回列表的 path 顺序必须为 ['SKILL.md', 'references/chords.md', 'scripts/export.py']，验证了字典序排序在新文件集上仍然有效。
返回列表中 scripts/export.py 条目的 executable 值必须为 False，验证了所有脚本均不可执行的安全约束。

运行真实测试

python -m pytest -q tests/test_stage.py

运行真实测试

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

设计解释题: 为什么 build_inventory 必须在入口处强制校验场景集合，而不是在清单生成后通过检查清单内容来补全缺失的场景？

一个有力回答应包含

前置校验避免了无效的文件遍历和哈希计算，符合快速失败原则。
场景集合是打包契约的一部分，缺失场景意味着包本身不完整，无法通过事后补全来修复。
在入口处抛出异常能更精确地定位错误来源，避免下游产生难以追踪的不一致状态。

掌握证据

test_package_requires_all_three_scenarios 测试通过，证明 build_inventory 在场景集合不等于 {'software', 'office', 'music'} 时正确抛出包含 ‘software, office, and music’ 的 ValueError。
test_inventory_is_sorted_and_never_marks_scripts_executable 测试通过，证明返回清单按 path 字典序排序且所有 executable 标志为 False。
forge/packaging.py 中定义了 REQUIRED_SCENARIOS 常量，并在 build_inventory 函数入口处进行了严格匹配校验。

完成本章

把 Forge 的需求抽取能力封装为可安装 Skill。

FORGE / LOCAL CHECK

本地实验自检

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

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

选择 verification.json

主要层

依赖能力

为后续提供

受这些层约束

概念校准

Skill

工具

Skill、Prompt 与 Agent 能力包

先看一个具体问题

创建 forge/skill_layout.py 并让结构验证测试通过

先做判断

它是什么

Skill 结构验证器是一个纯函数合同检查器

它不是什么

它不是文件系统扫描器或安装器

它与相邻概念的关系

入口集合、根目录集合与路径对象之间的关系

先看一个具体问题

Skill 包中的脚本为什么不能像资源一样被自动安装

先做判断

它是什么

资源与脚本的本质区别

它不是什么

策略边界的常见误解

它与相邻概念的关系

决策与平台执行的依赖关系

先看一个具体问题

缺失变量被静默替换为空字符串

先做判断

它是什么

声明式模板渲染的三集合校验模型

它不是什么

模板渲染不是简单的字符串替换

它与相邻概念的关系

render 与 Skill 可移植性的关系

先看一个具体问题

Manifest 不是字典，而是信任边界

先做判断

它是什么

Manifest 是内容寻址的信任契约

它不是什么

Manifest 不是宽松的元数据容器

它与相邻概念的关系

字段验证与入口存在性检查的因果关系

先看一个具体问题

Skill 升级时主版本变化未被识别为需要迁移

先做判断

它是什么

语义版本号（SemVer）的兼容性判定模型

它不是什么

SemVer 判定模型的边界

它与相邻概念的关系

版本解析与升级分类的因果链

先看一个具体问题

Skill 在目标平台上总是被误判为兼容

先做判断

它是什么

兼容性评估模型

它不是什么

兼容性评估的边界

它与相邻概念的关系

组件间的依赖关系

先看一个具体问题

发布清单缺失场景完整性校验导致部分场景被接受

先做判断

它是什么

确定性发布清单的构建契约

它不是什么

发布清单不是简单的文件列表拷贝

它与相邻概念的关系

场景校验、路径排序与哈希计算的协同