skill-provenance

Skill：skill-provenance

为每个 skill 建立来源与完整性台账。orca-sec-scans 会扫描内容中的漏洞/密钥；此 skill 回答供应链中的另外两个问题：skill 来自哪里，以及安装后是否遭到篡改。存储文件为 fdk/skills.provenance.json（来源 + 记录日期 + skills/<name>/ 中所有文件的 sha256）。通过重新计算校验和并与台账比对来验证——不一致 = MODIFIED，磁盘上存在但尚未记入台账的 skill = UNTRACKED。

WHAT

用途和背景

• 用途： 通过台账 fdk/skills.provenance.json（来源 + 记录日期 + 所有文件的 sha256）以及重新计算校验和的 verify 命令，回答每个 skill 的两个供应链问题：来自哪里，以及安装后是否遭到篡改。
• 触发条件（何时使用）：
  • 刚从外部来源（市场、其他仓库、其他项目会话中的提炼）安装 / 提炼了 skill → 使用 record 固定来源 + 校验和。
  • 怀疑 / 想检查 skill 是否被绕过流程修改 → 使用 check。
  • 询问“这个 skill 来自哪里”、“审计 skill 来源”、“skill 校验和”、“skill 供应链”。
  • CI 想拦截陌生 skill，或被修改但尚未更新台账的 skill。
• 非目标： 不扫描 skill 内容中的漏洞/密钥（由 orca-sec-scans 负责）；不自行猜测 skill 来源。

心智模型

skills/<name>/（磁盘上的文件）→ 每个文件的 sha256 → 与台账 fdk/skills.provenance.json 比对 → OK | MODIFIED（不一致）| UNTRACKED（磁盘上存在但尚未记入台账）| MISSING（台账中存在，但磁盘上已不存在）。record = 写入/覆盖台账条目；check = 读取并比对。

输入和输出约定

	Field	Required?	含义
In	<name> 或 --all	record 必填	要记入台账的 skill
In	--source	record 必填	URL、真实的 repo#ref，或 local-authored
In	--ci	否	有 MODIFIED/UNTRACKED 时，check 返回退出码 1
Out	fdk/skills.provenance.json 中的台账条目	record 后	来源 + 记录日期 + sha256
Out	每个 skill 的状态	check 后	OK / MODIFIED / UNTRACKED / MISSING + 退出码

规则和能力

• RULE-01（MUST）：不得捏造来源。--source 必须是真实的 URL/ref 或 local-authored；错误的 provenance 比没有 provenance 更糟。
• RULE-02（MUST）：每次合法安装/修改后都必须执行 record——台账是真实信息的唯一来源；修改 skill 后不重新记录，会被 CI 作为异常修改拦截（这是预期行为）。
• RULE-03（MUST）：不得替代 orca-sec-scans——此 skill 负责来源/完整性，不扫描内容中的漏洞/密钥；两者都要使用。
• RULE-04（MUST）：check --ci 将 MISSING（skill 已移除）视为非错误；只有 MODIFIED/UNTRACKED 才会拦截。
• RULE-05（MUST）：存储文件 fdk/skills.provenance.json 是经整理维护的文件——与 skill 变更一同提交，避免内容偏离。
• 能力：读取 skill 文件并计算哈希；写入本地 provenance 台账。不联网。

失败边界

• 不知道 skill 的真实来源 → 向用户澄清，不得猜测并填写 --source。
• check --ci 发现 MODIFIED/UNTRACKED → 失败（退出码 1）；有意修改 → 重新记录，异常修改 → 调查。
• MISSING → 报告，但不拦截。

HOW

主要工作流

步骤	类型	输入	操作	输出/退出	失败/后续
W01	effect	空台账	一次性回填 record --all --source local-authored	完整台账	台账已有内容 → 跳过
W02	effect	新技能 + 真实来源	record <name> --source …	台账条目	来源不明确 → 澄清
W03	deterministic	台账 + 磁盘	check（检查全部或一个技能）	OK/MODIFIED/UNTRACKED/MISSING	—
W04	deterministic	台账 + 磁盘	CI 门禁 check --ci	退出码 0/1	MODIFIED/UNTRACKED → 退出码 1
W05	effect	有意修改过的技能	使用旧来源重新记录	新校验和	未重新记录 → W04 报错

各步骤详情（W01–W05 的事实来源）：

1. 一次性回填（如果台账为空）——将所有现有技能记录为自编：

   python3 fdk/tools/skill-provenance.py record --all --source local-authored
   

2. 安装/添加新技能时——记录真实来源（URL、repo#ref 或 local-authored）：

   python3 fdk/tools/skill-provenance.py record <name> --source "https://github.com/<owner>/<repo>#<ref>"
   

3. 随时检查完整性（输出 OK/MODIFIED/UNTRACKED/MISSING）：

   python3 fdk/tools/skill-provenance.py check          # xem tất cả
   python3 fdk/tools/skill-provenance.py check <name>   # một skill
   

4. CI 门禁——如果存在 MODIFIED 或 UNTRACKED，则退出码为 1（已接入 .github/workflows/skills-sync.yml）：

   python3 fdk/tools/skill-provenance.py check --ci
   

5. 有意修改技能后，运行 record <name> --source <旧来源> 来更新校验和——否则，check --ci 会报告 MODIFIED（这是正确的：所有更改都必须经过台账）。

分支

ID	类型	条件	行为	跳过/失败	重新汇合
B01	conditional_required	台账为空	回填 W01	台账已有内容 → 跳过	W03
B02	recovery	check 报告 MODIFIED	有意修改 → W05 重新记录；不清楚是谁修改的 → 按意外修改调查	—	W03
B03	recovery	check 报告 UNTRACKED	新技能有效 → W02 使用真实来源记录	来源不明确 → 澄清	W03

验证与停止条件

完全确定：skill-provenance.py 的校验和 + 退出码。需要人工判断的部分：--source 来源是否真实。check 全部输出 OK 时停止（MISSING 可以接受）。

示例

• **正向示例：**刚从 https://github.com/acme/skills#v1.2 拉取技能 → python3 fdk/tools/skill-provenance.py record foo --source "https://github.com/acme/skills#v1.2" → check foo 输出 OK。
• **边界/失败示例：**修改 skills/foo/SKILL.md 后未重新记录 → check --ci 输出 MODIFIED foo，退出码为 1；用户问“foo 来自哪里”，但没人知道 → 不要猜测并填写 --source，应询问确认。