visual-recap
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseSystem recap
系统回顾
When a change is non-trivial (a plan, a PR create or update, or a request for a
visual recap), put one marker-delimited block in the PR description. GitHub
renders it. It does not replace reading the diff.
当变更并非简单修改时(无论是制定计划、创建或更新 PR,还是收到可视化回顾请求),都要在 PR 描述中放入一个由标记界定的区块。GitHub 会渲染该区块,但它不能代替阅读 diff。
When
使用时机
Recap mode reads the diff, not memory. Claims about what changed must be
checkable against (plus ). Session context may
explain intent only.
git diff <base>...HEAD--statRun the classifier. Roll up to the highest of , then , then
. You still choose vs from the diff. is a
new map entry.
addsextendscomposescomposesextendsadds| Rollup | Risk | Also |
|---|---|---|
| low | Wiring and call sites only. |
| medium | Verify locally with the project's control CLI as the seeded user; a PR preview only when local cannot |
| high | Update |
Update when this PR adds, removes, or materially reshapes a
primitive (new , renamed meaning, or ownership roots that must change). Do
not edit for ordinary feature work. Call out a touched invariant from
that map at every risk.
primitives.yamlidsummaryKeep each entry's in sync: list the current decision records that shape
the primitive ( if none), and when this PR adds or supersedes a
record, add it to (or swap it into) the matching entries. The classifier prints
each touched primitive's ; read them before you change that primitive. The
check script fails on missing or superseded paths.
adrsadrs: []adrsPlan mode uses before a PR exists. Recap mode replaces that
block from . In plan mode, say explicitly when the plan
requires no change to any primitive; that is the lowest-risk outcome.
**Mode:** plangit diff <base>...HEADThe block shape is one example:
references/block-format.md.
recap 模式以 diff 为依据,而不是依赖记忆。 关于变更内容的陈述必须能够通过 (以及 )进行核验。会话上下文只能用于解释意图。
git diff <base>...HEAD--stat运行分类器。按 、、 的顺序向上汇总,并取其中最高等级。 与 之间仍需根据 diff 进行选择。 表示新增一个 map 条目。
addsextendscomposescomposesextendsadds| 汇总级别 | 风险 | 附加要求 |
|---|---|---|
| 低 | 仅涉及连接与调用点。 |
| 中 | 在本地以已预置用户的身份使用项目的 control CLI 进行验证;仅当本地无法完成验证时,才使用 PR 预览。 |
| 高 | 更新 |
当此 PR 新增、移除或实质性重构某个 primitive(使用新的 、含义被重新定义,或必须变更 ownership roots)时,请更新 。对于普通功能开发,不要修改 。无论风险等级如何,都要明确指出该 map 中被触及的 invariant。
idprimitives.yamlsummary保持每个条目的 同步:列出当前塑造该 primitive 的决策记录(如果没有,则为 );当此 PR 新增或取代某条记录时,将其添加到匹配的条目中,或替换其中的旧记录。分类器会打印每个受影响 primitive 的 ;修改该 primitive 前必须先阅读这些记录。检查脚本会在路径缺失或已被取代时失败。
adrsadrs: []adrs在 PR 尚未创建时,plan 模式使用 。recap 模式根据 替换该区块。在 plan 模式下,如果计划无需更改任何 primitive,请明确说明;这是风险最低的结果。
**Mode:** plangit diff <base>...HEAD以下是一个区块格式示例:
references/block-format.md。
Command
命令
bash
node .agents/skills/visual-recap/scripts/classify-primitives.mjs --base <base> --head HEAD --json
node .agents/skills/visual-recap/scripts/upsert-recap-block.mjs <pr-number> <block-file>
node .agents/skills/visual-recap/scripts/check-primitives-map.mjsThe upsert script checks mermaid, then replaces the marker block or appends it.
It does not edit text outside the markers. Re-run both commands after a
significant push.
bash
node .agents/skills/visual-recap/scripts/classify-primitives.mjs --base <base> --head HEAD --json
node .agents/skills/visual-recap/scripts/upsert-recap-block.mjs <pr-number> <block-file>
node .agents/skills/visual-recap/scripts/check-primitives-map.mjsupsert 脚本会先检查 Mermaid,然后替换标记区块;若区块不存在,则进行追加。它不会修改标记范围之外的文本。完成重大 push 后,重新运行这两个命令。
Failure
失败处理
- The mermaid check exits non-zero. Fix the diagram. Keep out of sequence notes and messages.
; - The block file must start with and end with
<!-- system-recap:start -->.<!-- system-recap:end --> - fails with
gh pr edit. The script still prints the merged body. Apply that body with Cursor ManagePullRequest. Do not have Kody edit the PR.Resource not accessible by integration (updatePullRequest) - A health check or login smoke is not medium or high verification. Prefer local control CLI proof; use a preview only when local cannot exercise the change. Do not cat the session cookie into curl or Python.
- Mermaid 检查以非零状态退出。修复图表。序列图的 note 和 message 中不要使用 。
; - 区块文件必须以 开头,并以
<!-- system-recap:start -->结尾。<!-- system-recap:end --> - 失败并返回
gh pr edit。脚本仍会打印合并后的正文。使用 Cursor ManagePullRequest 应用该正文。不要让 Kody 编辑 PR。Resource not accessible by integration (updatePullRequest) - health check 或 login smoke test 并不构成中、高风险级别的验证。优先提供本地 control CLI 验证证据;仅当本地无法验证变更时才使用预览。不要将 session cookie 通过 管道传给 curl 或 Python。
cat