archview

/archview

给指定工作区的代码节点写语义摘要，让 ArchView 面板从「一堆文件名」变成「能看懂的架构」。

这份提示词的结构参照 Understand-Anything 的 skills/understand/SKILL.md （MIT，见仓库 NOTICE），流程换成 ArchView 的。

和 UA 最根本的一处不同：UA 让 LLM 同时挖结构又写语义，所以它需要一堆修补脚本 擦屁股（规范化 ID、丢悬空边、翻转方向搞反的边）。ArchView 里结构是 CodeGraph 给的 确定性事实，你只写语义。因此本流程里没有任何一步让你产出节点或边 —— 如果你发现自己在写 JSON 里的 source/target/type，你已经跑偏了。

选项

$ARGUMENTS 可以包含：

• 一个目录路径 —— 目标工作区根（默认当前工作目录）
• --module <key> —— 只处理这一个模块（模块 key 见 AGENT-GUIDE.md 的模块表）
• --stale-only —— 只重写 hash 失配的过期摘要，不碰缺失项
• --limit <n> —— 本轮最多写 n 条（大工作区分批推进用）
• --dry-run —— 只报告要写哪些节点，不落盘

---

铁律（读完再动手）

铁律 1 —— 你永远不写拓扑

节点和边只能由 CodeGraph 的 tree-sitter 输出派生。你能提供的字段只有两个： summary 与 tags。

具体禁止：

• 绝不允许手写、修改、"修正" <workspace>/.archview/graph.json。它是派生物， 重建会整份重写。你的编辑不但会消失，在消失之前还会让面板显示假架构。
• 不要动 .archview/meta.json、.archview/briefs/ —— 同样是派生物。
• 不要在摘要里把推断出来的 import / 调用 / 继承当事实写。这些关系简报里已经有了 （importsFrom / importedBy / renders / renderedBy），直接引用。
• 发现拓扑不对（缺边、方向反、模块归属错），报告它，不要动手改图。 那是 builder 或 deriver 的 bug，改图只会掩盖它。

铁律 2 —— 每个节点的 summary 必须非空

没有 LLM 摘要时系统会填确定性兜底句（<名字> —— <路径> 中的 <kind>）。 那不是摘要，它只是为了不让校验器报警。简报里 summarySource 不是 "llm" 的每一条都是你的活（真实取值见阶段 2 那张表）。

铁律 3 —— 摘要的 key 必须是简报里的 nodeId 原文

节点 ID 方案是冻结的，摘要文件用它做 key。拼错的 key 不会报错，只会静默变成 孤儿摘要，在重建时被丢掉。复制，不要重新拼装。

---

进度汇报

每个阶段开始时打一行状态，写完一批报一次。工作区大的时候这一步不是礼貌，是让人知道 你还在动。

[阶段 N/6] <阶段名>…

例：[阶段 3/6] 写 entry 模块的摘要（83 个文件节点，缺 12 条）…

---

阶段 0 —— 摸清现场

1. 确定 WORKSPACE：$ARGUMENTS 里第一个不以 -- 开头的参数就是它；没有就用当前 工作目录。确认 <WORKSPACE>/.archview/ 存在。

2. 读 <WORKSPACE>/.archview/AGENT-GUIDE.md。这是唯一的必读文件。

   它是生成物，装着这个工作区此刻的实况：项目名与描述、模块清单（各自文件数）、 检测到的语言、摘要覆盖率、具体缺哪些节点、简报文件的确切路径、该读哪几份语言/ 框架指导、输出格式、MCP 配置片段、自检清单。

   • 文件不存在时，在 ArchView 仓库目录里跑 pnpm exec archview-skill guide --workspace <WORKSPACE> --write （或 node <仓库>/archview/packages/skill/dist/bin/skill.js guide --workspace <WORKSPACE> --write）生成。 不要用 npx archview-skill —— 这个包还没发布到 npm，npx 会去 registry 找它然后失败； 裸命令 archview-skill 也不在 PATH 里。跑不了就退回读 <WORKSPACE>/.archview/briefs/ 自己判断（信息少一些，但够干活）。
   • 文件在，但里面的数字看着与 .archview/ 的现状矛盾（比如它说缺 40 条、而 summaries 里已经有了），说明它是旧的：重新生成一次，别拿旧数字干活。