@ultime/codecraft 1.4.0 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # 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 模式。
+- 新增 `npm run self-check`，CI 同步执行；仓库自检以 `--exclude 'evals/fixtures/**'` 达到 0 findings。
+- 修正 README 与 FAQ 的扫描范围描述：A21 额外扫描配置与后端源码扩展名，结构规则仍只扫 JS/TS。
+- pack 自动判定补齐 Vue CLI（`vue.config.*`）与单页 Web 入口（html + 框架依赖 + `src/main.*`），避免把 Vue / React 应用判成 `library`。
+- 结构规则跳过压缩 / 构建产物（A21 不受影响），减少与源码重复的 A6 / A17 findings。
+- A21 修正误报：`MYSQL_PWD="$VAR" cmd` 这类 shell 环境变量前缀不再算明文口令；引号值只取引号内内容。
+- 扫描跳过 `.agents` / `.trae` / `.claude` / `.cursor` 等 agent 安装目录，避免把已安装 skill 的 fixture 当项目代码。
+- 修复 A6 行号漂移：剥离注释时保留换行，空 catch 的行号与源码一致。
+- A17 支持按文件头识别生成类型（`本文件由…生成` / `勿手改` / `@generated`），并解析相对路径与 `@/` `~/` `#/` 别名；生成的数据 / 资源模块不触发。
+- A21 扩充：新增阿里云 `LTAI`、明文 `password` / `secret` / `apiKey` / `accessKey` 赋值扫描，覆盖 `.java` / `.kt` / `.properties` / `.xml` / `.env`；跳过环境变量、占位符与测试目录。
+- 新增单元测试与 CLI eval（`a17-generated-header` / `a21-plaintext`）。
+- 移除 `adapters/claude` / `adapters/trae` 等单 agent 入口；手动指针统一指向 `SKILL.md`，文档改用通用 `.agents` 表述。
+- 新增 `docs/08-audit-contract.md`：逐条判定、证据门槛、静态边界、A1–A21 判定矩阵、一致性检查、P0–P3 与计划表。
+- `prompts/output.md` 增加 A1–A21 全覆盖、证据 / 局限列、0 findings 声明与计数可复现要求。
+- `docs/02-ai-contract.md` 与 `scenarios/audit-existing.md` 接入审计证据门槛。
+- `SKILL.md` 路由与读法把审计指向 `08`；`README` 目录说明同步。
+- 新增 A6 空 catch 静态检查（app / library）。
+- A17 支持 `boundaries.external` / `boundaries.generated` 配置，覆盖约定外的生成类型路径。
+- 新增 `--format sarif`（SARIF 2.1.0），可直接接 GitHub Code Scanning。
+- 新增 `--changed` / `--since <ref>`：只报告变更 / 未跟踪文件中的 findings；底层仍全量扫描。
+- 新增 GitHub Actions CI：`npm test` + `npm run eval` + `npm pack --dry-run`。
+- 新增 `evals/run.mjs` + fixtures：覆盖 A6 / A17（含 boundaries）/ ignore / A11 / 0 文件 / SARIF。
+
 ## 1.4.0 - 2026-10-27
 
 - 仓库改为 `skills/codecraft` 标准集合布局，可被 `skills` CLI 直接发现。

package/CONTRIBUTING.md

@@ -20,6 +20,8 @@
 
 ```bash
 npm test
+npm run eval
+npm run self-check
 npm pack --dry-run
 node bin/codecraft.mjs check --root <项目>
 ```
@@ -35,4 +37,5 @@ node bin/codecraft.mjs check --root <项目>
 - **minor**：新能力——CLI 选项、检查规则、适配器、模板、向后兼容的配置字段。
 - **patch**：修复、文档、提示词、测试、CI，或无行为变化的内部调整。
 - `2.0` 不设时间表；没有破坏性变更就不进 major。
+- v1 内容收口未完成前不发版；内容变更先累积在 `CHANGELOG.md` 的 Unreleased。
 - 发布前同时改 `VERSION`、`package.json`、`CHANGELOG.md`，并跑 `npm test` 与 `npm pack --dry-run`。

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 等其它语言；后端专项另立体系 |
 
 内容分三层，按需取用：
@@ -62,23 +85,16 @@ npx skills-npm setup
 
 ### 方式 C：手动指针
 
-不复制文件，只在项目规则里留一行：
+不复制文件，只在通用入口里留一行：
 
-- 通用：`AGENTS.md`
-- Claude：`CLAUDE.md` 或 `~/.claude/CLAUDE.md`
-- Trae：`.trae/rules/codecraft.md`
+- 通用：`AGENTS.md`（推荐）
+- 其它 agent：使用该 agent 自己的入口文件，内容相同
 
 ```md
-代码任务先读 <Codecraft 仓库路径>/skills/codecraft/adapters/trae/SKILL.md
+代码任务先读 <Codecraft 路径>/skills/codecraft/SKILL.md
 ```
 
-平台入口：
-
-| 平台 | 入口文件 |
-|---|---|
-| 通用（读 `AGENTS.md`） | [`adapters/generic/AGENTS.md`](./adapters/generic/AGENTS.md) |
-| Claude | [`adapters/claude/SKILL.md`](./adapters/claude/SKILL.md) |
-| Trae | [`adapters/trae/SKILL.md`](./adapters/trae/SKILL.md) |
+入口示例：[`adapters/generic/AGENTS.md`](./adapters/generic/AGENTS.md)。其它 agent 不需要单独适配文件，统一指向 `SKILL.md`，避免维护多份正文。
 
 ## 第一次使用
 
@@ -86,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：
 
@@ -134,6 +157,8 @@ codecraft check --root .
 codecraft check --pack library --root ../../packages/core
 codecraft check --pack design-system
 codecraft check --format json --ci
+codecraft check --changed --ci                    # 只看变更 / 未跟踪文件
+codecraft check --since origin/main --ci          # PR 内变更
 codecraft audit --severity error
 codecraft audit --config codecraft.config.json --fail-fast
 codecraft plan --root . --with-gates
@@ -148,7 +173,10 @@ codecraft init --root . --name demo --apply      # 写盘
 | `--root <path>` | 目录 | `.` | 被检查的项目根 |
 | `--pack <name>` | `app` / `library` / `design-system` / `auto` | `auto` | 规则包；CLI 优先于 config |
 | `--config <path>` | 文件 | `codecraft.config.json` | 相对 `--root` |
-| `--format <fmt>` | `md` / `json` | `md` | 输出格式 |
+| `--changed` | — | 关 | 只报告变更 / 未跟踪文件中的 findings |
+| `--since <ref>` | git ref | — | 只报告自该 ref 以来变动文件中的 findings |
+| `--exclude <glob>` | 路径 / glob | — | 扫描时跳过；可重复。用于 fixture、第三方目录等不应参与检查的路径 |
+| `--format <fmt>` | `md` / `json` / `sarif` | `md` | 输出格式 |
 | `--severity <level>` | `warn` / `error` | `warn` | findings 的严重级别 |
 | `--ci` | — | 关 | 等价于 `--severity error` |
 | `--fail-fast` | — | 关 | gates 遇到第一个失败即停止 |
@@ -167,27 +195,31 @@ codecraft init --root . --name demo --apply      # 写盘
 
 ### 输出
 
-- 默认 Markdown：头部元信息 + Findings 表 + Gates 表。
-- `--format json`：包含 `version` / `mode` / `pack` / `rules` / `findings` / `plan` / `gates` / `summary`，用于 CI、趋势和两次运行 diff。
+- 默认 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` 为变更文件数。
 - 报告始终带版本号与规则 ID；`plan` 明确声明「No files were changed by this command.」。
 
 ## Rule Packs
 
 | Pack | 内置规则 | 检查范围 |
 |---|---|---|
-| `app` | A17 / A21 | `pages / components / behavior` 不 import `external/` / `generated/`；密钥扫描 |
-| `library` | A2 / A11 / A21 | 包不 import app、相对路径不逃逸、workspace 依赖必须声明；生成物必须有“勿手改 / 派生”标记；密钥扫描 |
-| `design-system` | A2 / A11 / A21 | library 规则 + 包内公开文档不得引用内部 `docs/` |
+| `app` | A6 / A17 / A21 | 空 catch；`pages / components / behavior` 不 import `external/` / `generated/`（含生成文件头与 `boundaries` 配置）；密钥扫描 |
+| `library` | A2 / A6 / A11 / A21 | 包不 import app、相对路径不逃逸、workspace 依赖必须声明；空 catch；生成物必须有“勿手改 / 派生”标记；密钥扫描 |
+| `design-system` | A2 / A6 / A11 / A21 | library 规则 + 包内公开文档不得引用内部 `docs/` |
 
 `--pack auto` 的判定顺序（基于 JS/TS 生态的目录与 `package.json`）：
 
-1. 有 `apps/` 或 `src/pages` → `app`
-2. 有 `packages/` 或根 `package.json` → `library`
-3. 其余 → `app`
+1. 有 `apps/`、`src/pages` / `pages` / `app` / `src/app`，或 Nuxt / Taro / uni-app / Vue CLI（`vue.config.*`）标记 → `app`
+2. 单页 Web 入口三件套：`index.html`（根或 `public/`）+ 框架依赖（`vue` / `react` / `svelte` 等）+ `src/main.*` / `src/index.*` → `app`
+3. 一级子目录命中上述任一标记（workspace 内嵌应用）→ `app`
+4. 有 `packages/`、`src/` 或根 `package.json` → `library`
+5. 其余 → `app`
 
-`design-system` 不参与自动判定，必须显式指定。
+`design-system` 不参与自动判定，必须显式指定。带 demo 页的库若被误判为 `app`，用 `--pack library` 覆盖。
 
-A4（单一收口）属于结构判断，由 review 与项目门禁负责，不由静态扫描替代。
+A4（单一收口）、A5（互斥布尔 / 非法状态）、A8（派生状态）属于结构或状态判断，由 review 与项目门禁负责，不由静态扫描替代。
 
 ## 配置
 
@@ -207,13 +239,18 @@ A4（单一收口）属于结构判断，由 review 与项目门禁负责，不
       "reason": "legacy page; migrate in 2026-Q4",
       "expires": "2026-12-31"
     }
-  ]
+  ],
+  "boundaries": {
+    "external": ["@/types/external"],
+    "generated": ["@/types/project"]
+  }
 }
 ```
 
 - `pack`：`app` / `library` / `design-system` / `auto`。
 - `gates`：数组；每项必须有一个非空的 `run` 字符串，可选 `name`、`timeoutMs`（默认 `120000`）。
 - `ignore`：例外登记（A12）。每项必须有 `rule` / `file` / `reason`，`expires` 可选（`YYYY-MM-DD`）；`file` 支持 `*` / `**` / `?`。安全规则 `A21` 不可豁免。
+- `boundaries`：A17 的补充路径。生成类型优先按文件头自动识别；`external` / `generated` 填 import 前缀或 glob，用于头部没有标记、或路径不在约定内的项目。
 - 命中的 findings 不参与退出码，但仍出现在报告的 `Ignored` 表与 JSON 的 `ignored`；过期的条目不生效，列在 `Expired Exceptions`。
 - gate 在 `--root` 下通过 shell 执行，注入 `CI=1`；失败时报告尾部 40 行 / 4000 字符。
 - `check` 不跑 gates；`audit` 默认跑；`plan` 只在 `--with-gates` 时跑。
@@ -222,16 +259,15 @@ A4（单一收口）属于结构判断，由 review 与项目门禁负责，不
 ## 目录
 
 ```text
-SKILL.md      标准 agent skill 入口（skills-npm / install 使用）
-docs/         宪法、族卡、AI 契约、风格总图、模式、架构、AI 提示词、门禁
-scenarios/    新项目 / 旧项目审计 / 只出报告 / 重构评审
-adapters/     generic / Trae / Claude 手动指针
+SKILL.md      标准 agent skill 入口（skills add / skills-npm 使用）
+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 骨架
-evals/        golden tasks（人工回归）
-ROADMAP.md    后续版本计划与交接说明
+templates/    init --apply 的 app / library 骨架 + 架构报告模板
+evals/        CLI eval fixtures + golden tasks（人工回归）
 ```
 
 ## 版本与稳定承诺
@@ -243,7 +279,7 @@ ROADMAP.md    后续版本计划与交接说明
 - 不按「感觉重要」升 major；`2.0` 不设时间表。
 - 规则 ID `A1–A21` 稳定；增删规则属于 minor 以上的变更。
 - 报告始终携带版本号；跨版本对比以 JSON 为准。
-- 后续计划：[ROADMAP.md](https://github.com/ultime-space/skills/blob/main/skills/codecraft/ROADMAP.md)。
+- 版本历史见 [CHANGELOG.md](./CHANGELOG.md)；计划不在仓库内维护。
 
 ## FAQ
 
@@ -252,13 +288,16 @@ ROADMAP.md    后续版本计划与交接说明
 - **怎么装到指定 agent？** `npx skills add ultime-space/skills --skill codecraft`；交互选 agent，或用 `-a <agent>` 非交互。安装路径由 `skills` CLI 维护，本 skill 不枚举。
 - **`check` / `audit` / `plan` 有什么区别？** `check` 只跑内置规则；`audit` 额外跑 config 里的 gates；`plan` 只读，把 findings 转成计划，默认不跑 gates。
 - **为什么不自动跑 typecheck / test？** 门禁由项目提供，Codecraft 只编排，避免第二套实现。
-- **monorepo 为什么被判成 app / library？** 有 `pages/`、`app/`、`manifest.json + pages.json`、Taro / uni-app 依赖或嵌套应用时按 `app`；有 `packages/` 或 `src/` 时按 `library`；仍不确定就显式传 `--pack`。
-- **支持哪些文件？** 只扫 JS/TS 相关扩展名与 `package.json`；其它语言不覆盖。
+- **monorepo 为什么被判成 app / library？** 有 `pages/`、`app/`、`manifest.json + pages.json`、Taro / uni-app / Vue CLI 标记、单页 Web 入口或嵌套应用时按 `app`；有 `packages/` 或 `src/` 时按 `library`；仍不确定就显式传 `--pack`。
+- **支持哪些文件？** A2 / A6 / A11 / A17 扫描 JS/TS 相关扩展名与 `package.json`；A21 额外扫描配置与后端源码（`.yml` / `.yaml` / `.env` / `.properties` / `.xml` / `.java` / `.kt` 等）里的明文密钥。其它语言仍不在检查范围。
 
 ## 边界
 
 - 静态检查是文本级：能覆盖高置信模式，可能漏报或误报；最终以项目门禁与 review 为准。
-- 机检只扫描 JS/TS 相关文件（`.ts` / `.tsx` / `.js` / `.jsx` / `.mjs` / `.cjs` / `.vue` / `.svelte`）与 `package.json`，其它语言不覆盖。
+- 结构规则（A2 / A6 / A11 / A17）只扫描 JS/TS 相关文件（`.ts` / `.tsx` / `.js` / `.jsx` / `.mjs` / `.cjs` / `.vue` / `.svelte`）与 `package.json`；A21 额外扫描配置与后端源码扩展名（见上），但只做密钥 / 内部路径模式匹配，不做语言级分析。
+- 压缩 / 构建产物（≤3 行且存在 >1000 字符的单行）不参与 A2 / A6 / A11 / A17，避免与源码重复报同一问题；A21 仍会扫描它们。
+- `.agents` / `.trae` / `.claude` / `.cursor` 等 agent 安装目录不扫描，避免把已安装 skill 的 fixture 当项目代码。
+- `--exclude` 是扫描级排除，不产生 findings；它不能替代 `ignore`（后者用于登记已发现问题的例外，且 A21 不可豁免）。
 - 不内置任何业务规则、框架约定或公司内部门禁。
 - 不读取、不上传代码；所有检查在本地完成。
 

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 登记。
@@ -22,7 +23,8 @@ 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` 执行
+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.4.0
+1.6.0

package/adapters/README.md

@@ -3,12 +3,11 @@
 Core 是 `docs/` + `scenarios/` + `scripts/`；adapters 只做入口，不复制规则。
 
 - `generic/AGENTS.md`：任何读 `AGENTS.md` 的 agent
-- `trae/SKILL.md`：Trae skill
-- `claude/SKILL.md`：Claude skill
-- 未来：Cursor / Copilot / Gemini 等
+
+其它 agent 使用自己的入口文件，统一指向包根 [`SKILL.md`](../SKILL.md)；不为单一 agent 维护专属文件。
 
 规则：adapter 只写“读什么、按什么流程、输出什么”，规则正文留在 `docs/`。
 
-包根的 [`SKILL.md`](../SKILL.md) 是标准 agent skill 入口（`skills add` / `skills-npm` 使用）；本目录的平台文件用于手动指针接入。两者二选一，不要同时维护两套正文。
+包根的 [`SKILL.md`](../SKILL.md) 是标准 agent skill 入口（`skills add` / `skills-npm` 使用）；本目录只保留通用手动指针。
 
 使用者提示词（怎么对 AI 说）：[`../docs/07-ai-prompts.md`](../docs/07-ai-prompts.md)。

package/codecraft.config.example.json

@@ -19,5 +19,9 @@
       "reason": "legacy page; migrate in 2026-Q4",
       "expires": "2026-12-31"
     }
-  ]
+  ],
+  "boundaries": {
+    "external": ["@/types/external"],
+    "generated": ["@/types/project"]
+  }
 }

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。
 - **修改**：一次变更一个状态；契约类改动全仓原子提交。
 
@@ -312,8 +312,8 @@ repo/
 
 ## 6. 机检现状
 
-- 已内置（`codecraft check`）：A2 / A11 / A17 / A21（静态、文本级）。
-- 需要项目门禁或人工评审：A3 / A4（收口判断）/ A5–A9（类型与结构）/ A12–A20。
+- 已内置（`codecraft check`）：A2 / A6（空 catch）/ A11 / A17 / A21（静态、文本级）。
+- 需要项目门禁或人工评审：A3 / A4（收口判断）/ A5 / A7–A9（类型与结构）/ A12–A20。
 - 静态扫描只覆盖高置信模式；漏报由项目门禁补，误报按 A12 登记例外。
 
 ## 7. 待定

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. 必须
 
@@ -56,7 +56,18 @@
 4. **风险 / 不确定**
 5. **后续**：owner + 到期
 
-## 6. Review Checklist（评审清单）
+Audit 报告还必须满足 `docs/08-audit-contract.md`。
+
+## 6. 审计证据门槛
+
+- A1–A21 全覆盖；不适用写 `na`。
+- 每条 `pass` 必须给文件行号或可复现命令；只有静态检查通过时写 `pass（静态）`。
+- `0 findings` 只能写成「静态检查未命中」，不能写成规则通过；必须写明 A17 / A21 等覆盖盲区。
+- 计数必须带检索式；不能复现的数字不写。
+- 出结论前做一致性检查：A4 / A8 / A11 / A17 / A21 与证据矛盾时降级。
+- 优先级按 P0–P3；计划每阶段可回滚、有验收。
+
+## 7. Review Checklist（评审清单）
 
 - [ ] 族形正确（Page / Behavior / Transport；Node 后端跳过 Page / Component）
 - [ ] 依赖向内

package/docs/04-gates.md

@@ -34,22 +34,27 @@
   ],
   "ignore": [
     { "rule": "A17", "file": "src/pages/legacy/**", "reason": "legacy page", "expires": "2026-12-31" }
-  ]
+  ],
+  "boundaries": {
+    "external": ["@/types/external"],
+    "generated": ["@/types/project"]
+  }
 }
 ```
 
 - `pack`：`app` / `library` / `design-system` / `auto`；CLI `--pack` 优先。
 - `gates`：数组；每项必须有 `run`，可选 `name` / `timeoutMs`。
 - `ignore`：例外登记（A12）；`rule` / `file` / `reason` 必填，`expires` 可选。过期条目不生效，报告中单列；安全规则 `A21` 不可豁免。
+- `boundaries`：A17 的补充路径；生成类型优先按文件头识别，`external` / `generated` 填 import 前缀或 glob，覆盖头部无标记或路径不在约定内的项目。
 - 配置文件默认 `codecraft.config.json`；可用 `--config` 指定。
 
 ## 4. 按项目类型选门禁
 
 | 项目类型 | 通用 | 业务 |
 |---|---|---|
-| **App** | A17 / A21（A4 人工评审） | typecheck、单测、e2e、视觉回归 |
-| **Library** | A2 / A11 / A21 | build、单测、exports 检查、依赖对账 |
-| **Design System** | A2 / A11 / A21 | 构建、契约快照、视觉回归、a11y |
+| **App** | A6 / A17 / A21（A4 人工评审） | typecheck、单测、e2e、视觉回归 |
+| **Library** | A2 / A6 / A11 / A21 | build、单测、exports 检查、依赖对账 |
+| **Design System** | A2 / A6 / A11 / A21 | 构建、契约快照、视觉回归、a11y |
 | **Docs** | A21 | 死链、三线头、交付白名单 |
 
 ### 4.1 内置规则
@@ -57,13 +62,23 @@
 | Rule | Pack | 检查 |
 |---|---|---|
 | A2 | library / design-system | 包不 import apps；相对路径不逃逸；workspace 依赖必须声明 |
+| A6 | all | 空 catch / 静默失败 |
 | A11 | library / design-system | 生成物必须有“勿手改 / 派生”标记 |
-| A17 | app | `pages / components / behavior` 不 import `external/` / `generated/` |
-| A21 | all | 高置信密钥模式（私钥 / AWS / GitHub / Slack / API key） |
+| A17 | app | `pages / components / behavior` 不 import `external/` / `generated/`；生成类型按文件头（`本文件由…生成` / `勿手改` / `@generated`）自动识别；自定义路径用 `boundaries` 补充 |
+| A21 | all | 高置信密钥模式（私钥 / AWS / 阿里云 `LTAI` / GitHub / Slack / API key）；配置与后端源码中的明文 `password` / `secret` / `apiKey` / `accessKey` 赋值；环境变量引用与占位符不报 |
 | A21 | design-system | 包内公开文档（README / USAGE / CHANGELOG / contract）不引用内部 `docs/` |
 
 A4（单一收口）是结构判断，仍由 review / 项目门禁负责，不由静态扫描替代。
 
+### 4.2 CI 用法
+
+```bash
+codecraft check --changed --ci                  # PR 只拦变更文件
+codecraft check --changed --format sarif > codecraft.sarif
+```
+
+`--changed` / `--since` 只过滤 findings；底层仍做全量扫描。SARIF 可直接上传 GitHub Code Scanning。
+
 ## 5. 执行顺序
 
 1. 快速静态（内置规则、lint）；

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

@@ -24,17 +24,16 @@ npx skills-npm setup
 
 装好后项目里会有 `.agents/skills/codecraft/SKILL.md`（以及检测到的 agent 目录）。
 
-也可以手动在 agent 入口里留一条指针，不要复制规则：
+也可以手动在通用入口里留一条指针，不要复制规则：
 
-- 通用：`AGENTS.md`
-- Claude：`CLAUDE.md`
-- Trae：项目 `.trae/rules/codecraft.md`
+- 通用：`AGENTS.md`（推荐）
+- 其它 agent：使用该 agent 自己的入口文件，内容相同
 
 ```md
-代码任务先读 <Codecraft 仓库路径>/skills/codecraft/adapters/<平台>/...
+代码任务先读 <Codecraft 路径>/skills/codecraft/SKILL.md
 ```
 
-平台对应：Trae → `adapters/trae/SKILL.md`，Claude → `adapters/claude/SKILL.md`，其他 → `adapters/generic/AGENTS.md`。
+入口示例：`adapters/generic/AGENTS.md`。其它 agent 不需要单独适配文件，统一指向 `SKILL.md`。
 
 ## 2. 最小开场
 
@@ -90,7 +89,7 @@ npx skills-npm setup
 
 ```text
 使用 Codecraft（<路径>/codecraft）。
-模式：Review（只评审）或 Apply（执行）。
+模式：Review（只评审）或 Apply。
 范围：<diff / 文件 / 模块>。
 任务：按 scenarios/refactor-review.md 评审。
 要求：先列问题（边界 / 状态 / 错误 / 命名 / 注释 / 生成物），再给最小改动计划；能不改就不改；Apply 后跑门禁。
@@ -149,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 猜。