Back to Details

skill-provenance

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Skill: skill-provenance

Skill: skill-provenance

Sổ nguồn gốc + toàn vẹn cho từng skill. 
orca-sec-scans
quét vuln/secret trong NỘI DUNG; skill này trả lời hai câu hỏi khác của chuỗi cung ứng (supply-chain): skill từ đâu tới và có bị sửa lén sau khi cài không. Store là 
fdk/skills.provenance.json
(nguồn + ngày ghi + sha256 mọi file trong 
skills/<name>/
). Verify bằng cách tính lại checksum và so với sổ — lệch = MODIFIED, có skill trên đĩa mà chưa ghi sổ = UNTRACKED.
用于记录每个 skill 的来源与完整性的账本。
orca-sec-scans
会扫描内容中的 vuln/secret；本 skill 回答 supply-chain 中另外两个问题：skill 从哪里来，以及安装后是否被暗中修改。存储文件为 
fdk/skills.provenance.json
（来源 + 记录日期 + 
skills/<name>/
中每个文件的 sha256）。校验方式是重新计算 checksum 并与账本比较——不一致 = MODIFIED，磁盘上存在但未记入账本的 skill = UNTRACKED。

WHAT

WHAT

Purpose và context

目的与上下文

  • Purpose: trả lời hai câu hỏi supply-chain cho từng skill — từ đâu tới và có bị sửa lén sau khi cài không — bằng sổ 
    fdk/skills.provenance.json
    (nguồn + ngày ghi + sha256 mọi file) và lệnh verify tính lại checksum.
  • Trigger (when to use):
    • Vừa cài / chưng cất một skill từ nguồn ngoài (marketplace, repo khác, distill trong phiên dự án khác) → 
      record
      để chốt nguồn + checksum.
    • Nghi ngờ / muốn kiểm skill có bị sửa ngoài luồng không → 
      check
      .
    • Hỏi "skill này từ đâu ra", "audit nguồn skill", "checksum skill", "supply-chain skill".
    • CI muốn chặn skill lạ hoặc skill bị sửa mà chưa cập nhật sổ.
  • Non-goals: không quét vuln/secret trong nội dung skill (việc của 
    orca-sec-scans
    ); không tự đoán nguồn skill.
  • 目的： 通过 
    fdk/skills.provenance.json
    账本（来源 + 记录日期 + 每个文件的 sha256）以及重新计算 checksum 的 verify 命令，回答每个 skill 的两个 supply-chain 问题——从哪里来以及安装后是否被暗中修改。
  • 触发条件（何时使用）：
    • 刚安装/存放来自外部来源的 skill（marketplace、其他 repo、在其他项目会话中 distill）→ 使用 
      record
      固定来源 + checksum。
    • 怀疑或需要检查 skill 是否被意外修改 → 
      check
      。
    • 询问“这个 skill 从哪里来”、“审计 skill 来源”、“skill checksum”、“skill supply-chain”。
    • CI 需要阻止未知 skill 或已修改但尚未更新账本的 skill。
  • 非目标： 不扫描 skill 内容中的 vuln/secret（这是 
    orca-sec-scans
    的职责）；不自行推测 skill 的来源。

Mental model

心智模型

skills/<name>/ (file trên đĩa) → sha256 mỗi file → so với sổ fdk/skills.provenance.json → OK | MODIFIED (lệch) | UNTRACKED (trên đĩa chưa ghi sổ) | MISSING (trong sổ, không còn trên đĩa)
. 
record
= ghi/ghi đè mục sổ; 
check
= đọc so.
skills/<name>/
（磁盘上的文件）→ 计算每个文件的 sha256 → 与 
fdk/skills.provenance.json
账本比较 → OK | MODIFIED（不一致） | UNTRACKED（磁盘上存在但未记入账本） | MISSING（账本中存在但磁盘上已不存在）。
record
= 写入/覆盖账本条目；
check
= 读取并比较。

Input và output contract

输入与输出约定

FieldRequired?Ý nghĩa
In
<name>
hoặc 
--all
có với 
record
skill cần ghi sổ
In
--source
có với 
record
URL, 
repo#ref
thật, hoặc 
local-authored
In
--ci
không
check
trả exit 1 khi có MODIFIED/UNTRACKED
Outmục sổ trong 
fdk/skills.provenance.json
sau 
record
nguồn + ngày ghi + sha256
Outtrạng thái từng skillsau 
check
OK / MODIFIED / UNTRACKED / MISSING + exit code
字段是否必填含义
输入
<name>
或 
--all
record
时必填		需要记入账本的 skill
输入
--source
record
时必填		URL、真实的 
repo#ref
或 
local-authored
输入
--ci
否
check
在出现 MODIFIED/UNTRACKED 时返回 exit 1
输出
fdk/skills.provenance.json
中的账本条目
record
后		来源 + 记录日期 + sha256
输出每个 skill 的状态
check
后		OK / MODIFIED / UNTRACKED / MISSING + exit code

Rules và capabilities

规则与能力

  • RULE-01 (MUST): Không tự bịa nguồn. 
    --source
    phải là URL/ref thật hoặc 
    local-authored
    ; provenance sai còn tệ hơn không có.
  • RULE-02 (MUST): record sau MỌI lần cài/sửa hợp lệ — sổ là nguồn chân lý; skill sửa mà không re-record sẽ bị CI chặn như sửa đổi lạ (đúng ý đồ).
  • RULE-03 (MUST): Không thay 
    orca-sec-scans
     — skill này lo provenance/toàn vẹn, không quét vuln/secret nội dung; dùng cả hai.
  • RULE-04 (MUST): 
    check --ci
    coi MISSING (skill đã gỡ) là không-phải-lỗi; chỉ MODIFIED/UNTRACKED mới chặn.
  • RULE-05 (MUST): Store 
    fdk/skills.provenance.json
    là file curated — commit cùng thay đổi skill, đừng để drift.
  • Capabilities: đọc file skill + tính hash; ghi sổ provenance cục bộ. Không mạng.
  • RULE-01（必须）：不得自行编造来源。 
    --source
    必须是真实的 URL/ref 或 
    local-authored
    ；错误的 provenance 比没有 provenance 更糟。
  • RULE-02（必须）：每次合法安装/修改后都必须执行 
    record
    ——账本是事实来源；修改 skill 后若未 re-record，CI 会将其作为可疑修改拦截（符合预期）。
  • RULE-03（必须）：不得替代 
    orca-sec-scans
    ——本 skill 负责 provenance/完整性，不扫描内容中的 vuln/secret；两者应结合使用。
  • RULE-04（必须）：
    check --ci
    必须将 MISSING（已卸载的 skill）视为非错误    ；只有 MODIFIED/UNTRACKED 才触发拦截。
  • RULE-05（必须）：Store 
    fdk/skills.provenance.json
    是 curated（人工维护）文件    ——应与 skill 变更一同 commit，避免 drift（漂移）。
  • 能力：读取 skill 文件并计算 hash；写入本地 provenance 账本。不访问网络。

Failure boundaries

失败边界

  • Không biết nguồn thật của skill → clarify với user, không ghi 
    --source
    đoán.
  • check --ci
    thấy MODIFIED/UNTRACKED → failed (exit 1); sửa có chủ đích → re-record, sửa lạ → điều tra.
  • MISSING → báo, không chặn.
  • 不知道 skill 的真实来源 → 向用户澄清（clarify），不要猜测 
    --source
    。
  • check --ci
    检测到 MODIFIED/UNTRACKED → failed（exit 1）；有意修改 → re-record；可疑修改 → 调查。
  • MISSING → 报告但不拦截。

HOW

HOW

Main workflow

主要工作流

StepTypeInputsActionOutputs/exitFailure/next
W01effectsổ trốngBackfill một lần 
record --all --source local-authored
sổ đầy đủsổ đã có → skip
W02effectskill mới + nguồn thật
record <name> --source …
mục sổnguồn không rõ → clarify
W03deterministicsổ + đĩa
check
(tất cả hoặc một skill)		OK/MODIFIED/UNTRACKED/MISSING—
W04deterministicsổ + đĩaGate CI 
check --ci
exit 0/1MODIFIED/UNTRACKED → exit 1
W05effectskill đã cố ý sửare-record với nguồn cũchecksum mớikhông re-record → W04 đỏ
Chi tiết từng bước (nguồn chân lý cho W01–W05):
  1. Backfill một lần (nếu sổ trống) — ghi mọi skill hiện có là tự viết:
    bash
    python3 fdk/tools/skill-provenance.py record --all --source local-authored
  2. Khi cài / thêm skill mới — ghi nguồn thật (URL, 
    repo#ref
    , hoặc 
    local-authored
    ):
    bash
    python3 fdk/tools/skill-provenance.py record <name> --source "https://github.com/<owner>/<repo>#<ref>"
  3. Kiểm toàn vẹn bất cứ lúc nào (in OK / MODIFIED / UNTRACKED / MISSING):
    bash
    python3 fdk/tools/skill-provenance.py check          # xem tất cả
python3 fdk/tools/skill-provenance.py check <name>   # một skill
  4. Gate CI — exit 1 nếu có MODIFIED hoặc UNTRACKED (đã gắn trong 
    .github/workflows/skills-sync.yml
    ):
    bash
    python3 fdk/tools/skill-provenance.py check --ci
  5. Sau khi cố ý sửa một skill, chạy lại 
    record <name> --source <nguồn cũ>
    để cập nhật checksum — nếu không, 
    check --ci
    sẽ báo MODIFIED (đúng: mọi thay đổi phải qua sổ).
步骤类型输入操作输出/退出码失败/下一步
W01effect账本为空一次性 Backfill：
record --all --source local-authored
完整账本账本已存在 → 跳过
W02effect新 skill + 真实来源
record <name> --source …
账本条目来源不明确 → clarify
W03deterministic账本 + 磁盘
check
（全部或单个 skill）		OK/MODIFIED/UNTRACKED/MISSING—
W04deterministic账本 + 磁盘CI Gate：
check --ci
exit 0/1MODIFIED/UNTRACKED → exit 1
W05effect已有意修改的 skill使用原来源 re-record新 checksum未 re-record → W04 失败
各步骤详情（W01–W05 的事实来源）：
  1. 一次性回填（如果账本为空）——将所有现有 skill 记录为自行编写：
    bash
    python3 fdk/tools/skill-provenance.py record --all --source local-authored
  2. 安装/添加新 skill 时——记录真实来源（URL、
    repo#ref
    或 
    local-authored
    ）：
    bash
    python3 fdk/tools/skill-provenance.py record <name> --source "https://github.com/<owner>/<repo>#<ref>"
  3. 随时校验完整性（输出 OK / MODIFIED / UNTRACKED / MISSING）：
    bash
    python3 fdk/tools/skill-provenance.py check          # xem tất cả
python3 fdk/tools/skill-provenance.py check <name>   # một skill
  4. CI Gate——如出现 MODIFIED 或 UNTRACKED，则 exit 1（已挂载到 
    .github/workflows/skills-sync.yml
    ）：
    bash
    python3 fdk/tools/skill-provenance.py check --ci
  5. 在有意修改某个 skill 后，使用原来源再次运行 
    record <name> --source <旧来源>
    更新 checksum——否则 
    check --ci
    会报告 MODIFIED（这是正确行为：所有修改都必须经过账本）。

Branches

分支

IDKindGuardHành viSkip / failureRejoin
B01conditional_requiredsổ trốngbackfill W01sổ đã có → skipW03
B02recovery
check
báo MODIFIED		sửa có chủ đích → W05 re-record; không rõ ai sửa → điều tra như sửa lạ—W03
B03recovery
check
báo UNTRACKED		skill mới hợp lệ → W02 record với nguồn thậtnguồn không rõ → clarifyW03
ID类型条件行为跳过/失败汇合
B01conditional_required账本为空回填 W01账本已存在 → 跳过W03
B02recovery
check
报告 MODIFIED		有意修改 → W05 re-record；无法确定修改者 → 按可疑修改调查—W03
B03recovery
check
报告 UNTRACKED		合法的新 skill → W02，使用真实来源 record来源不明确 → clarifyW03

Validation và stopping

校验与停止条件

Hoàn toàn tất định: checksum + exit code của 
skill-provenance.py
. Phần cần người: nguồn 
--source
có thật không. Dừng khi 
check
in toàn OK (MISSING chấp nhận).
完全确定性：依赖 
skill-provenance.py
的 checksum + exit code。需要人工判断的部分：
--source
是否真实。
check
输出全部 OK 时停止（MISSING 可接受）。

Examples

示例

  • Positive: vừa kéo skill từ 
    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
    in OK.
  • Boundary/failure: sửa 
    skills/foo/SKILL.md
    mà không re-record → 
    check --ci
    in MODIFIED foo, exit 1; user hỏi "foo từ đâu" nhưng không ai biết → không ghi 
    --source
    đoán, hỏi lại.
  • 正向示例： 刚从 
    https://github.com/acme/skills#v1.2
    拉取 skill → 
    python3 fdk/tools/skill-provenance.py record foo --source "https://github.com/acme/skills#v1.2"
    → 
    check foo
    输出 OK。
  • 边界/失败： 修改 
    skills/foo/SKILL.md
    后未 re-record → 
    check --ci
    输出 MODIFIED foo，exit 1；用户询问“foo 从哪里来”，但无人知道 → 不写入猜测的 
    --source
    ，再次询问。