208 lines
9.4 KiB
Markdown
208 lines
9.4 KiB
Markdown
# 1
|
||
|
||
`C:\Users\wangq\Documents\Codex\ccpe-system\requirements\skills-vault`记录了5个CCRA Agent配套的Skills的工单，都可以包装成公共Skill。
|
||
|
||
我们本次将会逐一打造对应的Skill。
|
||
|
||
每个Skill，都遵循下面这个流程：
|
||
1. 有任何问题提出。
|
||
2. 判断公共性共通性是否足够。若不足，则提出问题或者修改方向，等我确认。
|
||
3. 打造验证skill，使用公共的Conda环境（若需要python代码）
|
||
4. 实装本地`.agent/skills`
|
||
5. 完成配套的文档、规则
|
||
6. 提交
|
||
|
||
全部改造完成后，同步至远程，打Tag。
|
||
|
||
那么，现在可以开始第一个`2026-06-19-lifecycle-status-guard-scan`
|
||
|
||
已完成第一步审阅。这个工单的公共性足够：它是配置驱动、只读扫描、只产出证据候选，不替代 Owner/CCRA 判断；并且适用于
|
||
ccpe-system、writing-workbench、video-workbench 和普通开发仓库的状态漂移检查。
|
||
|
||
建议设计如下，确认后我开始实装：
|
||
|
||
- Skill 名：lifecycle-status-guard-scan
|
||
- 源码目录：skills/lifecycle-status-guard-scan/
|
||
- CLI：scripts/lifecycle_status_guard_scan.py --scan-root <path> --config <yaml|json> --output-dir <path>
|
||
- 输出：lifecycle-status-guard-scan.md 和 lifecycle-status-guard-scan.json
|
||
- 配置语义：
|
||
- watched_paths：相对 scan_root 的 glob
|
||
- status_fields：扫描 front matter / JSON / YAML 中的字段名或点路径
|
||
- forbidden_status_values：命中后产生 blocking finding
|
||
- warning_status_values：命中后产生 warning
|
||
- approved_phrases：按“声称已批准/已接受/已稳定的短语”处理，命中后要求 evidence marker
|
||
- forbidden_phrases：直接命中为候选 overclaim
|
||
- required_evidence_markers：用于判断 claim 是否缺少证据引用
|
||
- allowed_contexts：允许在否定、示例、政策说明等上下文中出现而不计入 overclaim
|
||
|
||
- 测试先行：覆盖工单列出的 stable 无证据、draft 允许、Owner/CCRA 批准短语缺引用、JSON、Markdown front matter、中文短
|
||
语、UTF-8 中文文件名。
|
||
|
||
- 安装与提交：测试和 metadata validate 通过后，用 repo 的 install-skill.ps1 安装到 C:\Users\wangq\.agents\skills，更新
|
||
registry/docs，然后单独提交这个 Skill。
|
||
|
||
我没有阻塞性问题。只需要你确认一处语义：approved_phrases 是否按上面设计为“approval claim phrases requiring evidence”？
|
||
如果确认，我就按这个方案开始写 RED 测试。
|
||
|
||
# 2
|
||
|
||
确认：approved_phrases 按 approval claim phrases requiring evidence 处理。
|
||
|
||
它不是 whitelist，也不代表该 claim 已被接受。
|
||
匹配 approved_phrases 时，Skill 只检查是否存在 required_evidence_markers。
|
||
若缺少 evidence marker，默认产生 blocking finding。
|
||
若存在 evidence marker，只能降级为 evidence-present claim / non-blocking observation，不得判定该批准真实有效。
|
||
批准真实性仍由 Owner / CCRA / 上层 Agent 判断。
|
||
|
||
建议实现时注意两点：
|
||
1. `required_evidence_markers` 不要只做全文件任意命中，最好支持“同一 front matter / JSON object 字段”或“短语附近窗口”的证据关联，否则容易被文件里无关的 evidence 字样误放行。
|
||
2. `allowed_contexts` 只应豁免 phrase-level claim，例如否定句、示例、政策说明，不应豁免结构化字段里的 `status: stable`、`lifecycle: accepted` 这类命中。
|
||
|
||
已经继续并完成第一个 Skill。
|
||
|
||
已新增并提交 lifecycle-status-guard-scan，commit 是 a2e8f1b feat: add lifecycle status guard scan skill。它已安装到 C:
|
||
\Users\wangq\.agents\skills\lifecycle-status-guard-scan，registry 和 install notes 也已更新。当前 worktree clean。
|
||
|
||
关键实现点：
|
||
|
||
- approved_phrases 按“需要证据的批准声称短语”处理，不作为 whitelist。
|
||
- 有附近证据时只输出 non-blocking observation，不判断批准真实有效。
|
||
- 结构化字段证据只在同一 front matter / JSON/YAML object 内关联。
|
||
- allowed_contexts 只豁免 phrase-level claim，不豁免 status: stable 这类结构化命中。
|
||
|
||
验证已通过：
|
||
|
||
- conda run -n skills-vault python -B -m unittest discover -s skills\lifecycle-status-guard-scan\tests -v：10 tests OK
|
||
- source Skill quick_validate.py：valid
|
||
- installed Skill quick_validate.py：valid
|
||
- git diff --check：exit 0，仅有 Git 的 LF/CRLF 提示
|
||
|
||
尚未 push / tag，按你的流程应等 5 个 Skill 全部完成后统一同步远程并打 tag。
|
||
|
||
# 3
|
||
|
||
现在开始下一个，`2026-06-19-regression-validation-gate-runner`
|
||
|
||
已完成第二个 Skill：regression-validation-gate-runner。
|
||
|
||
已提交：625ab2e feat: add regression validation gate runner skill。当前最近两个提交是：
|
||
|
||
625ab2e feat: add regression validation gate runner skill
|
||
a2e8f1b feat: add lifecycle status guard scan skill
|
||
|
||
实现内容：
|
||
|
||
- 新增 skills/regression-validation-gate-runner/
|
||
- 支持 JSON/YAML/YML/Markdown fenced manifest
|
||
- 支持 dry_run / run
|
||
- 默认只运行 required_before_review: true 的 gates；optional gate 默认跳过
|
||
- 捕获 stdout/stderr 到 logs/<gate-id>.log
|
||
- 输出 gate-run-report.md 和 gate-run-report.json
|
||
- 记录 exit code、duration、timeout、skipped gates、environment notes、changed files
|
||
- 明确声明 gates 只提供工程证据，不代表产品接受或生命周期批准
|
||
- 已安装到 C:\Users\wangq\.agents\skills\regression-validation-gate-runner
|
||
|
||
验证已通过：
|
||
|
||
- conda run -n skills-vault python -B -m unittest discover -s skills\regression-validation-gate-runner\tests -v：9 tests OK
|
||
- source Skill quick_validate.py：valid
|
||
- installed Skill quick_validate.py：valid
|
||
- git diff --check：exit 0，仅有 LF/CRLF 提示
|
||
|
||
当前 worktree clean。仍未 push / tag，按你的流程等 5 个 Skill 全部完成后统一同步远程并打 tag。
|
||
|
||
# 4
|
||
|
||
现在开始下一个工单。
|
||
|
||
• 已完成第三个 Skill：review-bundle-audit。
|
||
|
||
已提交：fdda95a feat: add review bundle audit skill。当前最近三个提交是：
|
||
|
||
fdda95a feat: add review bundle audit skill
|
||
625ab2e feat: add regression validation gate runner skill
|
||
a2e8f1b feat: add lifecycle status guard scan skill
|
||
|
||
实现内容：
|
||
|
||
- 新增 skills/review-bundle-audit/
|
||
- 支持 --bundle-root / --output-dir / --profile / --profile-config
|
||
- 内置 generic profile：检查 brief、manifest、validation sidecar，识别 report、zip、changed-files
|
||
- 输出 bundle-audit.md 和 bundle-audit.json
|
||
- 检查 manifest/sidecar 可读性
|
||
- 检查 zip 可读性，zip 损坏为 blocker
|
||
- extra files 只作为 warning，不阻塞
|
||
- 支持 UTF-8 路径和中文文件名
|
||
- 已安装到 C:\Users\wangq\.agents\skills\review-bundle-audit
|
||
|
||
验证已通过：
|
||
|
||
- conda run -n skills-vault python -B -m unittest discover -s skills\review-bundle-audit\tests -v：8 tests OK
|
||
- source Skill quick_validate.py：valid
|
||
- installed Skill quick_validate.py：valid
|
||
- git diff --check：exit 0，仅有 LF/CRLF 提示
|
||
|
||
当前 worktree clean。还剩 review-context-builder 和 routing-behavior-diff-audit 两个工单；仍未 push / tag，按你的流程等 5 个 Skill 全部完成后统一同步远程并打 tag。
|
||
|
||
# 5
|
||
|
||
现在开始`review-context-builder`
|
||
|
||
• 已完成第四个 Skill：review-context-builder。
|
||
|
||
已提交：c2a46b6 feat: add review context builder skill。当前最近四个 helper 提交是：
|
||
|
||
c2a46b6 feat: add review context builder skill
|
||
fdda95a feat: add review bundle audit skill
|
||
625ab2e feat: add regression validation gate runner skill
|
||
a2e8f1b feat: add lifecycle status guard scan skill
|
||
|
||
实现内容：
|
||
|
||
- 新增 skills/review-context-builder/
|
||
- 支持 --project-root、--review-id、--source-root、include/exclude patterns、metadata、max file size
|
||
- 输出 review-context.md 和 review-file-manifest.json
|
||
- 只生成文件索引和导航上下文，不替代阅读源文件
|
||
- 稳定排序、项目相对 POSIX 路径、UTF-8/中文路径支持
|
||
- missing source root 作为 blocker，但仍写出两个输出文件
|
||
- 大文件记录为 excluded，不嵌入内容
|
||
- metadata 原样 passthrough，不注入 CCRA 专用字段
|
||
- 已安装到 C:\Users\wangq\.agents\skills\review-context-builder
|
||
|
||
验证已通过：
|
||
|
||
- conda run -n skills-vault python -B -m unittest discover -s skills\review-context-builder\tests -v：8 tests OK
|
||
- source Skill quick_validate.py：valid
|
||
- installed Skill quick_validate.py：valid
|
||
- git diff --check：exit 0，仅有 LF/CRLF 提示
|
||
|
||
当前 worktree clean。还剩最后一个工单：routing-behavior-diff-audit。仍未 push / tag，等 5 个 Skill 全部完成后统一同步远程并打 tag。
|
||
|
||
# 6
|
||
|
||
现在完成最后一个
|
||
|
||
• 本地最后一个 Skill 已完成并提交：
|
||
|
||
- 新增 routing-behavior-diff-audit
|
||
- 提交：7e19041 feat: add routing behavior diff audit skill
|
||
- 本地 tag：ccra-agent-skills-2026-06-19
|
||
- 当前 main 相对 origin/main：ahead 5
|
||
- 工作区干净
|
||
|
||
验证结果：
|
||
|
||
- 五个 CCRA 配套 Skill 单元测试全部通过，共 43 个用例
|
||
- 五个源码 Skill quick_validate.py 全部通过
|
||
- 五个 .agents\skills 安装副本 quick_validate.py 全部通过
|
||
- routing-behavior-diff-audit 已安装到 C:\Users\wangq\.agents\skills\routing-behavior-diff-audit
|
||
|
||
远端同步没有成功。git ls-remote、git fetch、git push origin main ccra-agent-skills-2026-06-19，以及 HTTP/1.1 查询都返回：
|
||
|
||
Recv failure: Connection was reset
|
||
|
||
网络恢复后可直接重试：
|
||
|
||
git push origin main ccra-agent-skills-2026-06-19
|
||
|