项目类图架构师是做什么的？

将一个仓库转化为可交互的UML类图，让开发者可以探索而无需阅读数百个文件。分析是基于证据的：图中的每个类、属性、方法和关系都指向其来源的文件和行号。没有凭空捏造的内容；启发式发现的结果会标注为推断。

此文件中所有路径都相对于技能目录（包含此SKILL.md的文件夹）。

要求

Node.js 18+ (node --version)。这些脚本没有依赖：不要为此技能运行 npm install。
对仓库的读取权限。分析过程绝不会修改源文件；它只写入自己的输出文件夹。
如果Node.js不可用，请使用末尾描述的备用方案。

工作流程

1. 识别仓库

使用用户所讨论项目的绝对路径（通常是当前工作空间）。以下命令从技能目录运行，因此像 . 这样的相对路径会指向技能本身。

2. 生成图表

node scripts/class-architect.js generate "/absolute/path/to/repo"

有用的选项（完整列表请参阅CLI参考）：

需求	选项
在页脚中标注作者	`--author "名称" --author-role "软件工程师"`
图表标题	`--title "计费服务"`
仅分析大型仓库的一部分	`--include "src/main/java/com/acme/billing/**"` （可重复）
跳过文件夹	`--exclude "legacy/**"` （可重复）
限制语言	`--languages java,sql`
同时分析测试代码	`--include-tests`
初始视图/布局	`--view classes
自定义输出文件夹	`--out "/path/to/output"` （默认 `<repo>/.class-architect`）
从HTML中隐藏本地路径	`--hide-root` （禁用“在编辑器中打开”链接）

命令在标准输出上打印JSON摘要（进度信息发送到标准错误）。退出码：0 成功，1 用法错误，2 无可分析的源文件，3 模型验证失败（无任何输出写入），4 内部错误。

3. 检查结果

阅读JSON摘要（status, outputs, summary.counts, summary.insights, summary.edits, validation）。输出文件夹中写入的内容：

diagram.html - 交互式图表（在浏览器中打开；可离线工作）。
report.md / report.json - 扫描的文件、类、接口、枚举、关系、推断关系、未解析的引用、被排除的文件及其原因、警告、洞察。
model.json - UML模型（单一事实来源）；overlay.json - 用户编辑（如果存在）。

如果退出码为 2，请调整 --include / --languages 并说明哪些文件夹被排除及其原因（来自JSON details）。如果退出码为 3，请报告验证错误；不要手动编辑模型来隐藏它们。

对于拥有数百个类的仓库，图表将在概览（模块）视图打开，并允许用户深入模块和包；你也可以使用 --include 为一个限界上下文生成聚焦的图表。

4. 向用户展示图表

给出 diagram.html 的路径（以及从 outputs.diagramUrl 获取的 file:// URL）。除非用户要求且你的环境允许，否则不要尝试启动浏览器。
仅总结报告所说的内容：类/接口/枚举/关系的数量、检测到的框架、依赖循环、架构发现、未解析的引用和警告。准确引用类名。
提及标记为推断的关系（命名约定、Go结构类型化）应进行验证，并且派生表/列名已标记为衍生。
指出主要交互方式：点击类或行以检查它（包含源文件和行号）、搜索（/）、筛选、视图（概览、包、类、数据库ER）、放大镜（L）、编辑模式（E）、洞察、导出。详情：交互式图表指南。

5. 代码变更后刷新

再次运行相同的命令。它会：

只重新分析更改过的文件（增量缓存），
保留每个用户编辑（来自 overlay.json 以及用户通过保存按钮保存到 diagram.html 的编辑），
将目标从代码中消失的编辑报告为孤立（保留，绝不会静默丢失），以及与源更改冲突的编辑，
高亮显示与上次运行相比添加/删除/修改的类，
保留前一个图表的备份（diagram.prev.html）。

如果用户将图表副本下载到了其他地方，请使用 --edits "/path/to/saved-diagram.html" 传递该文件。

6. 可选：文档章节

图表可以在其下方显示额外的文档（表格、流程图、步骤、枚举网格、横幅注释），使用原始模板的组件。只添加你在代码中验证过的事实，并引用源文件。按照配置指南编写一个JSON文件，并使用 --notes notes.json 传递。

规则

切勿作为此技能的一部分修改、格式化或“修复”被分析的源代码。
切勿发明类、成员或关系，也不要把推断的关系当作确定无疑的来呈现。
切勿删除或覆盖 overlay.json 或用户保存的 diagram.html：CLI会自动合并它们。
输出文件夹 .class-architect/ 是生成的；建议将其添加到 .gitignore，除非用户想提交图表。
不要将图表或模型上传到任何地方：它们可能包含专有代码结构。

脚本无法运行时的后备方案

如果Node.js 18+不可用或不允许执行命令：

阅读相关的源文件，并按照UML模型参考手动编写一个模型JSON。只包含你在代码中看到的元素，并带有 source.file 和 source.line；对于非显式的内容，设置 confidence: "inferred"。
将 templates/viewer.html 复制到用户希望放置图表的位置（例如 class-diagram.html）。
在副本中，将 <script type="application/json" id="pca-data">null</script> 内的文本 null 替换为 {"model": <你的模型>, "overlay": null, "meta": {"title": "<项目名称>"}}，在JSON内部将 < 写为 \u003C。
或者，告诉用户打开 templates/viewer.html 并将 model.json 拖放到页面上。

然后，浏览器中的布局、交互和导出功能与生成的图表完全相同；只是缺少自动提取、变更检测和验证报告。要明确说明模型是手动编写的。

其他命令

node scripts/class-architect.js analyze "/abs/repo"                       # 模型 + 报告，无HTML
node scripts/class-architect.js render --model model.json --out diagram.html
node scripts/class-architect.js validate --model model.json --html diagram.html
node scripts/class-architect.js diff --base old-model.json --head model.json
node scripts/class-architect.js edits --from saved-diagram.html --out overlay.json
node scripts/class-architect.js viewer --out viewer.html
node scripts/class-architect.js doctor

参考文件（仅在需要时阅读）

references/CLI.md - 每个命令、选项、输出和退出码。
references/INTERACTIVE-DIAGRAM.md - 用户在图表中可以做什么，键盘快捷键。
references/RELATIONSHIPS.md - 每种关系类型和多重性如何确定，证据和置信度。
references/LANGUAGES.md - 支持的语言、框架和ORM，以及提取的内容。
references/CONFIGURATION.md - class-architect.config.json、外部实体、阈值、文档注释。
references/UML-MODEL.md - 模型格式（用于后备方案或其他工具）。
references/LIMITATIONS.md - 已知的限制，在相关时提及。

项目类图架构师