@ultime/codecraft 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 1.6.0 - 2026-10-27
+
+- 新增代码架构分析报告场景与模板：`scenarios/architecture-report.md`、`templates/architecture-report.md`。
+- README 增加「适用场景」与不适用清单；明确 Codecraft 只做代码架构，不含业务架构。
+- `docs/06-architecture.md` 收口为「代码架构设计方法」；`prompts/output.md` 增加架构报告输出指引。
+- 统一术语写法：AI 面向文档英文裸写，`README` / 对外报告首次出现标注中文，名字类不附中文；新增 `docs/09-glossary.md` 与 `tests/docs.test.mjs`。
+
 ## 1.5.0 - 2026-10-27
 
 - 新增 `--exclude <glob>`（可重复）：扫描级排除，用于 fixture / 第三方目录；报告头与 JSON 记录 exclude 模式。

package/README.md

@@ -1,6 +1,6 @@
-# Codecraft（代码手艺）
+# Codecraft
 
-> 面向 JS/TS 的代码规范与架构设计，作为可安装的 skill 包。
+> 面向 JS/TS 的代码规范与代码架构设计（不含业务架构），作为可安装的 skill 包。
 > 默认 Web 前端；示例原生优先（TS / 原生 Web API），框架只给 Vue 3 / React；Node 后端只复用结构规则；其它语言不在范围。
 
 - 版本：见 [VERSION](./VERSION)
@@ -16,18 +16,41 @@
 | 一套可执行的代码宪法（A1–A21）与代码族卡 | 业务组件库 |
 | 面向 AI 的固定入口与输出格式 | 某个框架的编码风格指南 |
 | 通用规则的静态检查 + 项目门禁编排 | 替代 typecheck / 单测 / e2e |
+| 代码架构分析与报告 | 业务架构 / 角色 / 流程 / 领域建模 |
 
 规则正文只在 [`docs/`](./docs/)；其它位置只放入口与指针，避免第二份真源。
 
 > 第一次用：直接看 [安装](#安装) 和 [第一次使用](#第一次使用)。
 
+## 适用场景
+
+按「新建 / 接手 / 演进 / 日常」分组，选一个入口即可：
+
+| 分组 | 场景 | 典型任务 | 产出 | 模式 |
+|---|---|---|---|---|
+| 新建 | 架构设计 | 定档位、边界、依赖规则 | 目标架构 / ADR（架构决策记录） | Plan（计划） |
+| 新建 | 脚手架 | app / library 骨架 | 目录、配置、门禁 | Apply（执行） |
+| 接手 | 代码架构报告 | 把现有结构讲清楚 | 架构分析文档 | Audit（审计） |
+| 接手 | 老项目审计 | A1–A21 体检 | 报告、差距、升级计划 | Audit |
+| 接手 | 重构 / 迁移评审 | 现状 → 目标、回退点 | 迁移计划 | Plan |
+| 演进 | 包 / monorepo（单仓多包）边界 | 拆包、依赖方向修正 | 边界计划 | Plan |
+| 演进 | 生成物 / 契约链 | 单一生成链、diff 门禁 | 治理方案 | Plan |
+| 演进 | 错误 / 状态模型 | Result、状态穷尽、失败可见 | 重构方案 | Plan |
+| 日常 | PR / 增量审计 | 只看变更范围 | findings | Audit |
+| 日常 | 规范落地 | 宪法 → 项目 `rules/` + 门禁 | 规则与门禁映射 | Apply |
+| 日常 | Design System（设计系统） / 组件库 | 包边界、公共 API、文档自包含 | 审计报告 | Audit |
+| 日常 | 只出报告 | 只读汇报 | 报告 | Audit |
+
+不适用：业务能力地图、角色与业务流程、领域建模、UI / 交互设计、运行时性能、渗透测试、数据库调优。
+
 ## 范围与分层
 
 | 项 | 内容 |
 |---|---|
 | 覆盖 | JS/TS 项目；Web 前端为默认场景（示例原生优先，框架仅 Vue 3 / React） |
+| 代码架构 | 系统 / 容器 / 模块 / 组件边界、依赖方向、关键链路、生成物、演进 |
 | 可复用 | Node 后端：模块边界、依赖方向、内外分离、生成物、门禁与文档规则 |
-| 不适用 | Page / Component 等前端族；数据库、缓存、并发、事务等后端专项 |
+| 不适用 | 业务架构、角色 / 流程 / 领域建模；Page / Component 等前端族；数据库、缓存、并发、事务等后端专项 |
 | 不在范围 | Java / Go / Python 等其它语言；后端专项另立体系 |
 
 内容分三层，按需取用：
@@ -79,9 +102,16 @@ npx skills-npm setup
 用 Codecraft 审计本项目，只读，不改文件。
 ```
 
+需要一份能读的代码架构文档：
+
+```text
+用 Codecraft 按 scenarios/architecture-report.md 出一份代码架构分析报告。
+只读，不改文件；不做业务架构，先不画图。
+```
+
 只启用 skill、不说 Codecraft 时，agent 可能按普通项目分析处理，不保证走 Audit 模式。带上名字最稳。
 
-更多场景（只出报告、新项目、重构评审、架构设计、模式选型、脚手架、Design System）见 [docs/07-ai-prompts.md](./docs/07-ai-prompts.md)。
+更多场景（代码架构报告、只出报告、新项目、重构评审、架构设计、模式选型、脚手架、Design System）见 [docs/07-ai-prompts.md](./docs/07-ai-prompts.md)。
 
 需要本地检查时再装 CLI：
 
@@ -165,7 +195,7 @@ codecraft init --root . --name demo --apply      # 写盘
 
 ### 输出
 
-- 默认 Markdown：头部元信息 + Findings 表 + Gates 表。
+- 默认 Markdown：头部元信息 + Findings 表 + Gates（门禁）表。
 - `--format json`：包含 `version` / `mode` / `pack` / `rules` / `exclude` / `findings` / `plan` / `gates` / `summary`，用于 CI、趋势和两次运行 diff。
 - `--format sarif`：SARIF 2.1.0，可直接上传 GitHub Code Scanning。
 - `--changed` / `--since` 只过滤 findings，底层仍做全量扫描；JSON 的 `scope` 为 `changed`，`changed` 为变更文件数。
@@ -230,13 +260,13 @@ A4（单一收口）、A5（互斥布尔 / 非法状态）、A8（派生状态
 
 ```text
 SKILL.md      标准 agent skill 入口（skills add / skills-npm 使用）
-docs/         宪法、族卡、AI 契约、审计契约、风格总图、模式、架构、AI 提示词、门禁
-scenarios/    新项目 / 旧项目审计 / 只出报告 / 重构评审
+docs/         宪法、族卡、AI 契约、审计契约、风格总图、模式、架构、AI 提示词、门禁、术语表
+scenarios/    新项目 / 旧项目审计 / 代码架构报告 / 只出报告 / 重构评审
 adapters/     generic 手动指针（其它 agent 统一指向 SKILL.md）
 prompts/      输出格式
 src/ + bin/   CLI（check / audit / plan / init）
 tests/        node:test 用例
-templates/    init --apply 的 app / library 骨架
+templates/    init --apply 的 app / library 骨架 + 架构报告模板
 evals/        CLI eval fixtures + golden tasks（人工回归）
 ```
 

package/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: codecraft
-description: 面向 JS/TS 的代码规范与架构设计（Codecraft）。默认 Web 前端，Node 后端可复用结构规则；用于审计、架构设计、重构评审、规范检查与脚手架。Code standard and architecture design for JS/TS projects (frontend-first; structural rules reusable for Node backends).
+description: 面向 JS/TS 的代码规范与代码架构设计（Codecraft）。默认 Web 前端，Node 后端可复用结构规则；用于审计、代码架构分析、架构设计、重构评审、规范检查与脚手架。不含业务架构。Code standard and code architecture for JS/TS projects (frontend-first; structural rules reusable for Node backends).
 ---
 
-# Codecraft（代码手艺）
+# Codecraft
 
 > 方向：JS/TS。默认场景是 Web 前端；示例原生优先（TS / 原生 Web API），框架只给 Vue 3 / React；Node 后端只复用结构规则；其它语言不在范围。
 
@@ -12,8 +12,9 @@ description: 面向 JS/TS 的代码规范与架构设计（Codecraft）。默认
 | 项 | 内容 |
 |---|---|
 | 覆盖 | JS/TS 项目；页面、组件、行为、状态、传输、类型、包、脚本、测试 |
+| 代码架构 | 系统 / 容器 / 模块 / 组件边界、依赖方向、关键链路、生成物、演进 |
 | 可复用 | Node 后端：模块边界、依赖方向、内外分离、生成物、门禁与文档规则 |
-| 不适用 | 前端专属族（Page / Component）；后端数据库、缓存、并发、事务等专项规范 |
+| 不适用 | 业务架构、角色 / 流程 / 领域建模；前端专属族（Page / Component）；后端数据库、缓存、并发、事务等专项规范 |
 | 不在范围 | Java / Go / Python 等其它语言；后端专项另立体系，本 skill 不承诺覆盖 |
 
 > 示例顺序：原生 → Vue 3 / React；其它框架不预建，先在 `docs/01-family-cards.md` §12 登记。
@@ -23,6 +24,7 @@ description: 面向 JS/TS 的代码规范与架构设计（Codecraft）。默认
 | 任务 | 先读 | 产出 |
 |---|---|---|
 | 审计 / 评审现有代码 | 宪法 + `docs/08-audit-contract.md` + 相关族卡 | 报告（只读） |
+| 代码架构分析 / 出报告 | `docs/06-architecture.md` + `docs/08-audit-contract.md` + `scenarios/architecture-report.md` | 架构报告（只读） |
 | 设计架构 / 拆边界 | `docs/06-architecture.md` + 宪法 | 计划 / ADR（只读） |
 | 新项目 / 脚手架 | `06` + `scenarios/new-project.md` | 骨架计划；必要时 `init` |
 | 选型（模式 / 库） | `docs/05-patterns.md` | 选型与代价 |
@@ -32,19 +34,20 @@ description: 面向 JS/TS 的代码规范与架构设计（Codecraft）。默认
 
 1. 项目 `AGENTS.md` / `rules/`
 2. `docs/00-constitution.md`
-3. 设计架构时：`docs/06-architecture.md`
+3. 设计架构 / 出架构报告时：`docs/06-architecture.md`
 4. 只读相关族卡：`docs/01-family-cards.md`（前端项目才读 Page / Component）
 5. 需要选型时：`docs/05-patterns.md`
 6. 选一个场景：`scenarios/`
 7. 按 `docs/02-ai-contract.md` 执行；审计还必须读 `docs/08-audit-contract.md`
 8. 按 `prompts/output.md` 输出
 9. 不知道怎么说时：`docs/07-ai-prompts.md`
+10. 术语写法：`docs/09-glossary.md`（AI 文档英文裸写；`README` / 对外报告首次出现标注中文；名字类不附中文）
 
 ## 模式
 
-- **Audit（审计）**：只读，出报告。
-- **Plan（计划）**：只读，出架构 / 升级计划。
-- **Apply（执行）**：改代码 + 跑门禁。
+- **Audit**：只读，出报告。
+- **Plan**：只读，出架构 / 升级计划。
+- **Apply**：改代码 + 跑门禁。
 
 ## 工作流
 
@@ -57,6 +60,7 @@ description: 面向 JS/TS 的代码规范与架构设计（Codecraft）。默认
 ## 禁止
 
 - Audit / Plan 模式改文件。
+- 把业务架构 / 业务流程 / 领域规则写进代码架构报告；这些不在本 skill 范围。
 - 把业务逻辑放进 Transport 或 Page。
 - 内部代码 import `external/` 或生成类型。
 - 手改生成物。

package/VERSION

@@ -1 +1 @@
-1.5.0
+1.6.0

package/docs/00-constitution.md

@@ -96,7 +96,7 @@
 | 内部查询 | `UserQuery` | `UserSearchModel` |
 | 内部输入 | `UserInput` | `UserSetModel` |
 | 内部视图模型 | `UserView` | 无 |
-| 外部类型（后端 / 第三方） | 只存在于 `external/` 或 Wrapper（包装层）；不参与内部命名 | 生成物原名 |
+| 外部类型（后端 / 第三方） | 只存在于 `external/` 或 Wrapper；不参与内部命名 | 生成物原名 |
 | UI 原语 | `app-` | 同左 |
 | 页面类 | `page-*` | 同左 |
 | 表 | `statusMap` / `apiMap` | 同左 |
@@ -160,7 +160,7 @@
 ### 3.2 内外边界（Inside/Outside Boundary）
 
 - 前端规范只管**内部代码**；后端 API、第三方 API 的契约风格不在规范内。
-- 外部内容只在 **Wrapper（包装层）** 出现；Wrapper 负责把外部类型 / 字段 / code 转成内部类型 / 错误。
+- 外部内容只在 **Wrapper** 出现；Wrapper 负责把外部类型 / 字段 / code 转成内部类型 / 错误。
 - 内部代码不 import 外部类型；Wrapper 是唯一入口。
 - Wrapper 可自由适配，但必须：类型安全、错误归一、不泄漏外部字段、可插拔。
 - 换后端 / 第三方 = 换 Wrapper，不改内部。
@@ -298,7 +298,7 @@ repo/
 
 ## 5. 使用方式
 
-- **人**：review 时按 A1–A21 检查；新规则先写 ADR（Architecture Decision Record，架构决策记录）。
+- **人**：review 时按 A1–A21 检查；新规则先写 ADR。
 - **AI**：先读本宪法 + 相关《代码族卡》+ 项目覆盖；输出按 A15，安全按 A21。
 - **修改**：一次变更一个状态；契约类改动全仓原子提交。
 

package/docs/01-family-cards.md

@@ -57,7 +57,7 @@
 
 ## 3. Transport（传输层）
 
-- **职责**：网络、HTTP、取消；原样透传；不解释业务 code。401 / 日志是可选环节；外部契约转换在 Wrapper（包装层）。
+- **职责**：网络、HTTP、取消；原样透传；不解释业务 code。401 / 日志是可选环节；外部契约转换在 Wrapper。
 - **形状**：`api/` 或 `request/`；`adapter/` / `interceptors/` / `modules/`；默认用原生 `fetch` + `AbortController`，框架封装只作可选实现；`pending/` / `console/` 是可选环节，不是必须目录。
 - **命名**：API 文件 snake_case 且与 URL 同名；一 URL 一文件。新代码推荐 `api/<domain>/<action>.ts` + `fetchXxx` / `getXxx`；旧项目可保留 `api_` 前缀（防重名、可搜索、标层）；同族不要混用。
 - **契约**：返回 raw response 或传输层结果；不产出域类型；错误只做传输层归一。
@@ -69,7 +69,7 @@
 - **反例**：传输层把业务 code 解析成域变体；transport import store / UI；全局单例藏副作用。
 - **验收**：lint「transport 不 import UI / store」；401 / pending 测试；契约测试。
 
-## 4. Wrapper（包装层）
+## 4. Wrapper
 
 - **职责**：外部契约适配；把后端 / 第三方的类型、字段、code 转成内部类型 / 错误；不放业务规则、不放 UI。
 - **形状**：`adapters/<source>/` 或 `api/<domain>/<source>.ts`；一个外部来源一个适配器。

package/docs/02-ai-contract.md

@@ -9,7 +9,7 @@
 
 1. 项目覆盖：`AGENTS.md` / `rules/` / `README`
 2. 《代码宪法 v1》
-3. 设计或评审架构：`06-architecture.md`（档位 / 七步法 / 边界 / ADR）
+3. 设计或评审架构：`06-architecture.md`（档位 / 七步法 / 边界）；决策用 ADR
 4. 只读相关《代码族卡 v1》（前端项目才读 Page / Component）
 5. 需要选型时：`05-patterns.md`（按力选，不按名字选）
 6. 相关契约 / 类型 / 测试 / 示例
@@ -37,7 +37,7 @@
 - 内部文档标 `Internal`；不进入交付目录。
 - 生成示例值用占位符（`<TOKEN>` / `<PASSWORD>`），不得复制真实配置。
 - 发现疑似密钥 / 隐私，停止生成、脱敏、提示轮换。
-- 术语格式：英文首次出现用 `English（中文）`；代码标识符保持英文。
+- 术语写法：AI 面向文档（`docs/` / `scenarios/` / `prompts/` / `templates/`）英文裸写；`README`、对外报告首次出现用 `English（中文）`；名字类（产品 / 文件 / 命令 / 语言 / 框架 / 标准名 / 代码标识）不附中文。术语表见 `09-glossary.md`，`tests/docs.test.mjs` 检查术语表与 README 首次出现。
 
 ## 4. 必须
 

package/docs/06-architecture.md

@@ -1,6 +1,8 @@
-# 架构设计方法（可选）
+# 代码架构设计方法（可选）
 
-> 用途：系统级 / 模块级 / 演进级的决策方法；代码级模式见 `05-patterns.md`。
+> 用途：系统级 / 模块级 / 演进级的代码架构决策方法；代码级模式见 `05-patterns.md`。
+> 边界：只讨论代码架构；业务能力、角色、业务流程、领域规则不在本 skill 范围。
+> 产出：只出文档时用 `scenarios/architecture-report.md` + `templates/architecture-report.md`。
 > 原则：**方法先于模式；约束先于图；边界先于抽象。**
 > 范围：方法本身与语言无关，可用于 JS/TS 前端与 Node 后端；文中目录与框架取舍以 JS/TS 为准。
 > 术语：English（中文）。
@@ -202,7 +204,7 @@ src/
 | 状态 | 局部 / 全局 store / server state / 状态机 | 生命周期、共享范围、异步复杂度 |
 | UI 组合 | 单应用 / 微前端 / 设计系统分层 | 团队规模、复用范围、品牌数量 |
 
-## 7. ADR（架构决策记录）
+## 7. ADR
 
 ```md
 # ADR-0001: 采用模块化单体而非微服务

package/docs/07-ai-prompts.md

@@ -89,7 +89,7 @@ npx skills-npm setup
 
 ```text
 使用 Codecraft（<路径>/codecraft）。
-模式：Review（只评审）或 Apply（执行）。
+模式：Review（只评审）或 Apply。
 范围：<diff / 文件 / 模块>。
 任务：按 scenarios/refactor-review.md 评审。
 要求：先列问题（边界 / 状态 / 错误 / 命名 / 注释 / 生成物），再给最小改动计划；能不改就不改；Apply 后跑门禁。
@@ -148,6 +148,16 @@ npx @ultime/codecraft check --pack design-system --root .
 要求：不要改文件；按 A2 / A11 / A21 归类；给最小修复计划。
 ```
 
+### 3.9 代码架构分析报告
+
+```text
+使用 Codecraft（<路径>/codecraft）。
+模式：Audit（老项目）/ Plan（新项目），只读。
+范围：<仓库 / 目录 / 包>。
+任务：按 scenarios/architecture-report.md 出一份代码架构分析报告。
+要求：按 templates/architecture-report.md 的结构；只做代码架构，不做业务架构；先不画图，用表格 / 列表；每条结论给文件:行号或命令；A17 / A21 写明盲区；0 findings 只写“静态未命中”；未知项单列。
+```
+
 ## 4. 说法上的要点
 
 - 先说模式，不要让 AI 猜。

package/docs/09-glossary.md

@@ -0,0 +1,22 @@
+# Glossary（术语表）
+
+> 写法：正文首次出现用 `English（中文）`；名字类不附中文。
+> 名字类 = 产品 / 文件 / 命令 / 语言 / 框架 / 标准名 / 代码标识（如 Codecraft、README.md、npm、JS/TS、JSON、A1–A21）。
+> 本表是术语写法的单一真源；`tests/docs.test.mjs` 检查正文首次出现。
+
+| English | 中文 |
+|---|---|
+| Audit | 审计 |
+| Plan | 计划 |
+| Apply | 执行 |
+| Wrapper | 包装层 |
+| Gate | 门禁 |
+| Gates | 门禁 |
+| Drift | 漂移 |
+| ADR | 架构决策记录 |
+| Canonical Link | 规范链接 |
+| canonical link | 规范链接 |
+| Context Engineering | 上下文工程 |
+| Progressive Disclosure | 渐进披露 |
+| Single Source of Truth | 单一真源 |
+| Design System | 设计系统 |

package/evals/golden-tasks.md

@@ -85,7 +85,7 @@
 
 - 输入：一个单团队、单产品的多页应用，后端契约未知。
 - 模式：Plan（只读）。
-- 期望：先定档位 L0/L1；列变化轴；切边界并给依赖规则；两张图（Context / Container）；ADR 只记难逆转项；不改文件。
+- 期望：先定档位 L0/L1；列变化轴；切边界并给依赖规则；Context / Container 用表格描述（本阶段不要求画图）；ADR 只记难逆转项；不改文件。
 - 失败信号：直接上微服务 / 微前端；只画图不给依赖规则；没有退出条件。
 
 ## 13. 架构评审
@@ -120,6 +120,13 @@
 - 期望：A4 判 `warn`；A11 判 `warn`；报告写明 `0 findings` 只是静态未命中；计数带检索命令。
 - 失败信号：A4 / A11 判 `pass`；把静态检查当全通过；结论没有文件行号或命令。
 
+## 18. 代码架构分析报告
+
+- 输入：一个三端项目（client / admin / server），已有 README 与部分 `rules/`。
+- 模式：Audit（只读）。
+- 期望：按 `templates/architecture-report.md` 出文档；结构 / 依赖 / 关键链路 / A1–A21 / 风险 / 演进 / 未知项齐全；每条有证据；明确写「不含业务架构」「本阶段不画图」；不改文件。
+- 失败信号：写成业务能力 / 角色 / 业务流程；没有证据；只给结论；用图代替结构表；改文件。
+
 ## 评分
 
 - 每条任务：pass / fail。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultime/codecraft",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "面向 JS/TS 的代码规范与架构设计（前端默认，Node 后端可复用结构规则），作为可安装的 skill 包。",
   "keywords": [
     "ai",

package/prompts/output.md

@@ -24,6 +24,10 @@
 ## 下一步
 ```
 
+## 架构报告
+
+代码架构分析报告按 [`../templates/architecture-report.md`](../templates/architecture-report.md) 输出；默认不画图，用表格 / 列表表达结构；证据、局限与 `0 findings` 口径同 Audit。
+
 ## 规则
 
 - A1–A21 全部出现；不适用写 `na` 并说明原因。

package/scenarios/architecture-report.md

@@ -0,0 +1,88 @@
+# Architecture Report（代码架构分析报告）
+
+> 定位：把代码架构讲清楚，形成一份人能读、能评审、能执行的 Markdown 文档。
+> 范围：只做代码架构；业务能力、角色、业务流程、领域规则不在本 skill 范围。
+> 关系：方法见 `docs/06-architecture.md`；证据门槛见 `docs/08-audit-contract.md`；模板见 `templates/architecture-report.md`。
+
+## 何时用
+
+- 接手老项目，需要一份能读的代码架构说明。
+- 重构 / 迁移 / 拆包前，先固定现状与约束。
+- 新项目立项，需要目标架构、边界与阶段计划。
+- 向人 / 客户汇报代码架构（不含业务架构）。
+
+不适用：业务能力地图、角色与流程、领域建模、UI 设计、运行时性能、渗透测试。
+
+## 输入
+
+- 仓库路径 / 分支 / 目录范围。
+- 模式：老项目 `Audit`；新项目 `Plan`；只出报告 `Audit`。
+- 目标：体检 / 重构 / 迁移 / 新建立 / 汇报。
+- 约束：能否跑命令、时间范围、必须保留的边界。
+- 已知业务背景（可选）：只作为上下文，不写成业务架构结论。
+
+## 先读
+
+1. 项目 `AGENTS.md` / `rules/`
+2. `docs/00-constitution.md`
+3. `docs/06-architecture.md`
+4. 只读相关族卡：`docs/01-family-cards.md`
+5. 审计模式：`docs/08-audit-contract.md`
+6. 输出：`prompts/output.md` + `templates/architecture-report.md`
+
+## 步骤
+
+1. **确认范围**：仓库 / 目录 / 包、只读声明、能否跑命令、本次不覆盖什么。
+2. **盘点**：技术栈、入口、页面 / 路由、模块、包、请求层、状态、类型、生成物、测试与门禁。
+3. **结构**（用表格 / 列表，不画图）：
+   - 系统上下文：外部系统、运行时、部署单元。
+   - 容器 / 模块：职责、边界、依赖方向。
+   - 公共 API：哪些是契约，哪些是内部实现。
+4. **关键链路**：请求链、状态链、错误模型、数据流、生成链；每段给 `file:line`。
+5. **跑静态检查**：`codecraft check / audit`，记录 `files / findings / 覆盖范围`；写明 A17 / A21 盲区。
+6. **逐条判定**：A1–A21，标 `pass` / `pass（静态）` / `warn` / `fail` / `na`，每条带证据与局限。
+7. **风险与技术债**：按 P0–P3 排；区分「已发生」与「可能发生」。
+8. **演进计划**：
+   - 老项目：现状 → 目标 → 分阶段迁移，每阶段可回滚、有验收命令。
+   - 新项目：目标架构 → 边界 → 目录 / 契约 → 阶段计划。
+9. **未知项**：没有证据的角色、规则、运行时行为单列，不猜。
+
+## 输出
+
+- 一份 Markdown 报告，按 `templates/architecture-report.md`。
+- 默认不画图；用表格、列表、缩进表达结构。
+- 如果后续需要图，图只作为视图，源仍写在 Markdown 里，不把图片当唯一真源。
+- 报告落在项目 `docs/` 下；文件名建议 `<主题>-代码架构分析报告.md`，并纳入项目文档索引。
+
+## 证据
+
+- 每条结论给 `path/to/file:line`，或可复现命令。
+- 计数写检索式与统计口径（行 / 处 / 文件）。
+- `0 findings` 只能写「静态检查未命中」，不能写成「架构通过」。
+- 不写密钥、客户名、本机绝对路径；发现即停止并提示轮换。
+
+## 停止条件
+
+- 无法只读访问仓库。
+- 需要改动生产配置或运行服务才能判断。
+- 发现凭证 / 隐私。
+- 业务结论超出代码证据，必须由人确认。
+
+## 验收
+
+- 报告结构与模板一致，结论 / 证据 / 风险 / 计划 / 未知项齐全。
+- A1–A21 全覆盖或写 `na`；每条有证据。
+- 明确写了「只做代码架构，不含业务架构」。
+- Audit / Plan 模式未改任何文件。
+- 计数与命令可复现。
+
+## 与其他场景的区别
+
+| 场景 | 侧重 | 产出 |
+|---|---|---|
+| `audit-existing.md` | A1–A21 体检 | findings、差距、升级计划 |
+| `new-project.md` | 新项目设计 | 目标架构、骨架、阶段计划 |
+| `report-only.md` | 只要 findings | 只读问题清单 |
+| 本场景 | 结构叙事 + 演进 | 一份完整代码架构分析报告 |
+
+本场景可以复用 `audit-existing` 的 findings，但不重复做业务架构。

package/scenarios/new-project.md

@@ -17,7 +17,7 @@
 2. `../docs/00-constitution.md`
 3. `../docs/01-family-cards.md`（只读相关族）
 4. `../docs/03-style-map.md`
-5. `../docs/06-architecture.md`（档位 / 七步法 / 边界 / ADR）
+5. `../docs/06-architecture.md`（档位 / 七步法 / 边界）；决策用 ADR
 6. 需要选型时：`../docs/05-patterns.md`
 
 ## 步骤

package/scenarios/refactor-review.md

@@ -6,7 +6,7 @@
 
 ## 模式
 
-Apply（执行）或 Review（只评审）。
+Apply 或 Review（只评审）。
 
 ## 步骤
 

package/templates/README.md

@@ -6,6 +6,8 @@
 |---|---|
 | `app/` | 应用骨架：`README.md` + `package.json` |
 | `library/` | 包骨架：`README.md` + `CHANGELOG.md` + `compat.md` + `package.json` |
+| `architecture-report.md` | 代码架构分析报告模板（Agent 输出用，不是 init 骨架） |
 
 - 目录结构由 `src/init.mjs` 定义，模板只提供文件内容。
-- 页面 / 组件 / Wrapper 的单文件形态见 `docs/01-family-cards.md`，不单独出模板：不同框架的写法差异大于共性。
+- `architecture-report.md` 只被 `scenarios/architecture-report.md` 引用，不参与 `init`。
+- 页面 / 组件 / Wrapper的单文件形态见 `docs/01-family-cards.md`，不单独出模板：不同框架的写法差异大于共性。

package/templates/architecture-report.md

@@ -0,0 +1,97 @@
+# <项目 / 模块> 代码架构分析报告（Codecraft）
+
+> 模式：Audit / Plan，只读 · 日期：YYYY-MM-DD · 仓库：`<repo>` · 分支：`<branch>` · HEAD：`<sha>`
+> 范围：`<目录 / 包>` · 规则版本：Codecraft `<version>`
+> 只读声明：未改代码、未起服务。未执行：`<typecheck / build / 单测>`。
+> 边界：本文只讨论代码架构；业务能力、角色、业务流程、领域规则不在范围。
+
+## 1. 结论与置信度
+
+- 一句话结论：
+- 置信度：High / Medium / Low（依据：静态 + 人工抽样 + 关键路径）
+- 最高风险：
+- 最需要先做的决定：
+
+## 2. 范围与方法
+
+| 项 | 内容 |
+|---|---|
+| 范围 | |
+| 已执行 | |
+| 未执行 | |
+| 覆盖边界 | |
+| 判定口径 | |
+
+## 3. 架构现状
+
+### 3.1 系统与容器
+
+| 单元 | 职责 | 运行时 / 部署 | 外部依赖 |
+|---|---|---|---|
+| | | | |
+
+### 3.2 模块与依赖
+
+| 模块 / 包 | 职责 | 允许依赖 | 禁止依赖 | 证据 |
+|---|---|---|---|---|
+| | | | | |
+
+- 依赖方向：
+- 边界与内外分离：
+- 公共 API / 内部实现：
+
+### 3.3 关键链路
+
+| 链路 | 入口 | 关键节点 | 失败模式 | 证据 |
+|---|---|---|---|---|
+| 请求 | | | | |
+| 状态 | | | | |
+| 错误 | | | | |
+| 数据 | | | | |
+| 生成 | | | | |
+
+## 4. A1–A21 判定
+
+| ID | 判定 | 证据 | 局限 |
+|---|---|---|---|
+| A1 | pass / pass（静态）/ warn / fail / na | `path:line` 或命令 | |
+| … | | | |
+
+- 一致性检查：
+- `codecraft check` 结果：`files / findings / 覆盖范围`
+- A17 / A21 盲区：
+
+## 5. 风险与技术债
+
+| 优先级 | 问题 | 证据 | 影响 | 建议 |
+|---|---|---|---|---|
+| P0 | | | | |
+| P1 | | | | |
+| P2 | | | | |
+| P3 | | | | |
+
+## 6. 演进计划
+
+| 阶段 | 内容 | 可回滚 | 验收 |
+|---|---|---|---|
+| 0 | | | |
+| 1 | | | |
+| 2 | | | |
+
+- 不写时间估算。
+- 每阶段一个可验收的垂直切片。
+
+## 7. 未知项与待确认
+
+| # | 问题 | 为什么无法确认 | 需要谁 / 什么证据 |
+|---|---|---|---|
+| 1 | | | |
+
+## 8. 附录：证据与命令
+
+```bash
+# 本次执行的检查
+```
+
+- 相关文件：
+- 相关文档：