GitLink 智能体执行证据回执 Skill

本项目是面向 GitLink AI Agent 工作流的执行证据回执工具。它通过 Agent Skill 和 Python CLI，把 GitLink Issue、PR、PR Files、CI/CD 等工作流元数据归一化为 evidence.json，生成可篡改感知的 hash_chain.json，并渲染可供人工复核的 review_report.md。

本项目不是代码正确性验证器。它是执行证据回执生成器。

参赛定位

目标赛题：第八届 CCF 开源创新大赛「GitLink 智能化服务开源项目贡献赛」。

匹配子赛题：子赛题二「编写和丰富 GitLink Skills」。

本项目交付的是一个可复用的 GitLink Agent Evidence Receipt Skill，并提供离线可复现演示、真实 gitlink-cli 只读模式、JSON Schema、测试和提交前审计文档。

核心价值

AI Agent 可以操作 GitLink workflow，但如果缺少轻量、可复核的 operation receipt，Issue、PR、CI/CD 的状态容易停留在口头描述。本项目把观察到的 GitLink 元数据转成稳定 JSON，并用哈希链绑定证据对象，使后续评审、引用、复核和审计更容易。

架构

flowchart LR
  A[Issue / PR / CI] --> B[gitlink-cli or fixtures]
  B --> C[normalizer]
  C --> D[evidence.json]
  D --> E[hash_chain.json]
  E --> F[review_report.md]
  F --> G[optional GitLink comment]

离线演示

python -m pip install -e ".[dev]"
make test
make demo-offline

离线演示使用 examples/fixtures，不需要 GitLink 登录，不访问网络，不读取凭据。

真实 GitLink 只读模式

gitlink-evidence collect \
  --source-mode gitlink-cli \
  --owner OWNER \
  --repo REPO \
  --issue ISSUE_ID \
  --pr PR_ID \
  --out dist/evidence

真实模式只调用 gitlink-cli 读命令。v0.1.0 中 CI 采集保持保守实现，因为不同版本 gitlink-cli 的 CI 命令细节可能存在差异。

输出文件

evidence.json：归一化后的 Issue、PR、PR Files、CI 元数据。
hash_chain.json：基于 canonical JSON 的 SHA-256 哈希链。
review_report.md：人工可读的执行证据回执报告。
comment.md：由 render-comment 生成的可选评论摘要。

验证命令

gitlink-evidence verify \
  --evidence dist/evidence/evidence.json \
  --hash-chain dist/evidence/hash_chain.json

期望输出：

OK: hash chain verified

Agent Skill

Skill 入口：

skills/gitlink-agent-evidence/SKILL.md

Skill 说明了何时使用、如何离线演示、如何进入真实 GitLink 只读模式、如何验证哈希链，以及为什么默认不做 GitLink 写回。

参赛材料索引

docs/demo-workflow.md：演示流程。
docs/contest-submission.md：比赛提交说明。
docs/submission-readiness.md：评分标准对照和 Agent 验证记录。
docs/threat-model.md：威胁模型。
schemas/：evidence.json 与 hash_chain.json 的 JSON Schema。
examples/expected/：固定时间戳生成的期望输出。

安全与隐私

默认使用 offline fixture mode。
测试不发起真实网络请求。
token、cookie、password、authorization、secret、private_key、session 等敏感字段会被脱敏。
默认不向 GitLink 写评论。
--write-comment 在 v0.1.0 中只是保留选项，不执行真实写回。

当前限制

只记录观察到的工作流元数据，不证明代码语义正确。
不实现完整 POP、ARO、MCP Server、Web UI、数据库、云服务或自动合并 PR。
gitlink-cli CI 采集为 best-effort。
尚未提交到 gitlink-cli 官方主仓库收录；当前版本作为独立 GitLink 开源仓库提交。

Roadmap

增加显式 --ci-command 支持。
增加可选 JSON Schema 校验。
在人工确认后支持 GitLink 评论写回。
准备向 gitlink-cli 主仓库提交 Skill 收录申请。