@ultime/codecraft 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 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

@@ -62,23 +62,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`，避免维护多份正文。
 
 ## 第一次使用
 
@@ -134,6 +127,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 +143,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 遇到第一个失败即停止 |
@@ -168,26 +166,30 @@ codecraft init --root . --name demo --apply      # 写盘
 ### 输出
 
 - 默认 Markdown：头部元信息 + Findings 表 + Gates 表。
-- `--format json`：包含 `version` / `mode` / `pack` / `rules` / `findings` / `plan` / `gates` / `summary`，用于 CI、趋势和两次运行 diff。
+- `--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 +209,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 +229,15 @@ A4（单一收口）属于结构判断，由 review 与项目门禁负责，不
 ## 目录
 
 ```text
-SKILL.md      标准 agent skill 入口（skills-npm / install 使用）
-docs/         宪法、族卡、AI 契约、风格总图、模式、架构、AI 提示词、门禁
+SKILL.md      标准 agent skill 入口（skills add / skills-npm 使用）
+docs/         宪法、族卡、AI 契约、审计契约、风格总图、模式、架构、AI 提示词、门禁
 scenarios/    新项目 / 旧项目审计 / 只出报告 / 重构评审
-adapters/     generic / Trae / Claude 手动指针
+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    后续版本计划与交接说明
+evals/        CLI eval fixtures + golden tasks（人工回归）
 ```
 
 ## 版本与稳定承诺
@@ -243,7 +249,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 +258,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

@@ -22,7 +22,7 @@ description: 面向 JS/TS 的代码规范与架构设计（Codecraft）。默认
 
 | 任务 | 先读 | 产出 |
 |---|---|---|
-| 审计 / 评审现有代码 | 宪法 + 相关族卡 | 报告（只读） |
+| 审计 / 评审现有代码 | 宪法 + `docs/08-audit-contract.md` + 相关族卡 | 报告（只读） |
 | 设计架构 / 拆边界 | `docs/06-architecture.md` + 宪法 | 计划 / ADR（只读） |
 | 新项目 / 脚手架 | `06` + `scenarios/new-project.md` | 骨架计划；必要时 `init` |
 | 选型（模式 / 库） | `docs/05-patterns.md` | 选型与代价 |
@@ -36,7 +36,7 @@ description: 面向 JS/TS 的代码规范与架构设计（Codecraft）。默认
 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`
 

package/VERSION

@@ -1 +1 @@
-1.4.0
+1.5.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

@@ -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/02-ai-contract.md

@@ -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/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. 最小开场
 

package/docs/08-audit-contract.md

@@ -0,0 +1,141 @@
+# 审计输出契约 v1
+
+> 2026-10-27 · v1
+> 用途：约束 Audit 模式的判定、证据、局限与一致性，防止把“静态检查 0 findings”写成“全部通过”。
+> 范围：JS/TS 项目，默认前端；Node 后端只复用结构与安全类判定。
+> 关系：流程见 `docs/02-ai-contract.md`；格式见 `prompts/output.md`；规则正文见 `docs/00-constitution.md` 与 `docs/01-family-cards.md`。
+
+## 1. 必填结构
+
+Audit 报告必须包含：
+
+1. **范围与方法**：仓库 / 分支 / 目录、只读声明、执行的命令、未执行项与原因。
+2. **逐条判定**：A1–A21 全覆盖；不适用写 `na` 并说明原因。
+3. **差距 / 风险**：按优先级分组，每条带证据。
+4. **计划**：阶段、内容、可回滚、验收。
+5. **验证**：命令 + 结果；不能跑要写原因。
+6. **局限**：静态检查覆盖不到的部分，尤其是 A17 / A21。
+
+逐条判定表固定为：
+
+```md
+| ID | 判定 | 证据 | 局限 |
+|---|---|---|---|
+| A4 | warn | `useList.ts` 6 处、页面 20+ 处 `code === 200` | 未覆盖运行时错误分支 |
+```
+
+## 2. 判定口径
+
+| 判定 | 含义 |
+|---|---|
+| `pass` | 有证据覆盖该规则，且没有相反证据 |
+| `pass（静态）` | 只有静态检查通过；必须写清检查范围，不能替代人工抽样 |
+| `warn` | 存在相反证据、覆盖不完整，或只有部分满足 |
+| `fail` | 明确违反，且会造成安全、数据或契约风险；按 P0 处理 |
+| `na` | 该规则不适用；必须写原因 |
+
+证据要求：
+
+- 文件级：`path/to/file.ts:line`；不要只写目录。
+- 命令级：写出命令与结果；计数必须带可复现的检索式。
+- 禁止「看起来一致」「整体规范」这类无证据结论。
+- 一个规则有多个子项时，逐项给证据；不能用一个子项代表全部。
+
+## 3. 静态检查边界
+
+内置检查是**抽样工具**，不是审计结论：
+
+- **A17**：按三条线索识别生成类型：路径含 `external/` / `generated/`、文件头有只读声明（`本文件由…生成` / `勿手改` / `@generated`）、`boundaries.external` / `boundaries.generated` 配置。只解析相对路径与 `@/` `~/` `#/` 别名；解析不到或头部无标记时仍是盲区，必须人工检查。
+  - 生成的数据 / 资源模块（如图标表）不算类型契约，不触发 A17。
+  - 约定：生成 / 外部类型放在 `external/` 或 `generated/` 下；迁移前按人工检查，不能因 0 findings 判 `pass`。
+- **A2 / A11**：只覆盖包结构、生成物标记等文本模式；没有类型图、没有运行时验证。
+- **A21**：高置信 token 模式（私钥 / AWS / 阿里云 `LTAI` / GitHub / Slack / API key）+ 配置与 Java / Kotlin 源码中的明文强口令 / 密钥字段；跳过环境变量、占位符与测试目录。没有命中不等于不存在，必须写明扫描范围。
+- **A4 / A5 / A8 / A12 / A13 / A19**：靠人工阅读，不做静态扫描。A4 需要语义判断；A5 需要状态可达性、A8 需要数据流分析，文本级扫描实测误报高；不能因为 CLI 0 findings 就给 `pass`。
+
+因此：
+
+- 报告必须写「`codecraft check` 的结果与覆盖范围」。
+- 用了 `--exclude` 时必须列出排除路径；否则计数不可复现。
+- `0 findings` 只能写成「静态检查未命中」，不能写成「规则通过」。
+- 审计结论的置信度分为 High / Medium / Low：
+  - High：静态 + 人工抽样 + 关键路径验证
+  - Medium：静态 + 人工抽样
+  - Low：仅静态检查
+
+## 4. A1–A21 判定矩阵
+
+| ID | 判定方式 | `pass` 条件 | 常见误判 |
+|---|---|---|---|
+| A1 | 人工抽样（结构检索辅助） | 同族实例使用同一模板 / 插槽；抽样覆盖主要分支 | 只看到统一 Wrapper，忽略内部结构分叉 |
+| A2 | 静态依赖 + 人工 | 无反向依赖、无跨层 import | 只看 core 的 import，漏掉传输层 import 状态 |
+| A3 | 人工 | 传输层不解释业务 code、不承担 UI 反馈 | 401 收口一处就判通过 |
+| A4 | 人工 + 计数 | 每种关注点只有一个收口；无散落的同类判断 | 认证 / 提示各一处，但业务码判断散落 30+ 处 |
+| A5 | 静态 + 人工 | 非法状态不可表示；联合类型 / 穷尽分支 | 有类型但大量 `any` / 多布尔并存 |
+| A6 | 人工 + 静态（空 catch） | 错误是值；无静默失败；调用方必须处理 | 成功元组里 err 恒为 `undefined`，业务失败仍走成功分支 |
+| A7 | 人工 | 可枚举变化用表；加 case 只加一行 | 有表但仍有并行 if / switch |
+| A8 | 人工 | 派生状态不落库 / 不重复存储 | 有 computed，同时把结果再存一份 |
+| A9 | 人工 | 注释只写意图 / 契约 / 边界 / 反例 | 注释复述代码，或规范文档本身漂移 |
+| A10 | 人工 + 配置 | 例外有理由 / 主人 / 到期；安全不可豁免 | 只写“历史原因”，没有到期 |
+| A11 | 静态（标记）+ CI 比对 | 生成物有只读标记，且再生成 diff 为空 | 只有“勿手改”头，没有再生成比对 |
+| A12 | 人工 | 复制有母版、版本、分叉点、升级路径 | 多处副本，未指明母版 |
+| A13 | 人工 | 每一层都能一眼定位源头 | `utils/` 成为域名 / 传输 / 海报的混合桶 |
+| A14 | 人工 | 抽象有真实消费方与触发条件 | 以“以后可能用”为由提前抽象 |
+| A15 | 流程 / 输出检查 | 变更说明含改了什么 / 为什么 / 怎么验 / 风险 | 用 A15 去评价代码结构 |
+| A16 | 人工 + 搜索 | 命名标层、可搜索、组合可读 | 单项目内一致，但跨端 / 跨团队歧义 |
+| A17 | 静态（路径 / 文件头 / 配置）+ 人工 | 内部不 import 外部类型；外部契约在包装层转换 | 别名解析不到或头部无标记就判通过；把生成数据模块当成类型契约 |
+| A18 | 人工 | 有档位；默认 L0；按触发升级 | 所有能力默认开启 |
+| A19 | 人工 + 契约测试 | public contract 固定；有可替换性验证 | 边界口头清楚，但没有契约测试 |
+| A20 | 人工 | 记录环节 / 职责 / 契约，不把库当层 | 用框架名代替架构层 |
+| A21 | 静态扫描 + 人工 | 无密钥 / 内部路径外泄；交付白名单一致 | 模式扫描 0 命中就判全局通过；把运行时变量名当明文密钥 |
+
+## 5. 一致性检查
+
+出结论前，必须做一次交叉检查；发现矛盾就降级：
+
+| 场景 | 要求 |
+|---|---|
+| A4 判 `pass`，但存在多处 `code === 200` / 重复错误处理 | 改为 `warn`；单一收口未成立 |
+| A11 判 `pass`，但没有再生成比对 / CI diff | 最多 `warn`；只能写“生成物有只读标记” |
+| A8 判 `pass`，但派生状态被落库 / 重复存储 | 改为 `warn`，或写明可接受理由与主人 |
+| A21 判 `pass`，但只做了模式扫描 | 写 `pass（有限）` 或 `warn`；列扫描范围 |
+| A17 判 `pass`，但存在生成类型直用 | 改为 `warn`；路径不在 `external/` 也算 |
+| A12 判 `pass`，但同族存在多份副本 | 改为 `warn`；必须指明母版 |
+| A3 判 `pass`，但传输层直接弹 Toast / 跳转 | 改为 `warn`；传输层不应承担 UI 反馈 |
+
+## 6. 优先级
+
+| 级别 | 定义 | 例子 |
+|---|---|---|
+| P0 | 安全、数据丢失、不可回滚 | 密钥泄漏、越权、破坏性迁移 |
+| P1 | 架构 / 契约 / 文档真源错误 | 分层失效、规范写错事实、门禁缺失 |
+| P2 | 可维护性 / 重复实现 | 业务错误码散落、上传目录三份真源 |
+| P3 | 测试、清理、体验 | 纯函数无单测、命名不统一 |
+
+同一份报告里，P1 不能多于结论总数的一半而不说明取舍；否则先合并根因。
+
+## 7. 计划表
+
+```md
+| 阶段 | 内容 | 可回滚 | 验收 |
+|---|---|---|---|
+| 0 | 文档纠偏 | 纯文档，单 commit 可回退 | 描述与检索结果一致 |
+| 1 | 门禁补齐 | 移除 config / hook 即恢复 | 故意引入类型错误会被拦 |
+```
+
+要求：
+
+- 每阶段可独立回滚，不用“重来一遍”。
+- 验收必须是可执行命令或可检索结果，不写“感觉完成”。
+- 不写时间估算；写依赖与顺序。
+- 重构阶段先补基线（typecheck / 单测 / 契约测试），再改行为。
+
+## 8. 交付前自检
+
+- [ ] A1–A21 全部出现，或写明 `na`
+- [ ] 每条 `pass` / `warn` 都有文件行号或命令
+- [ ] 所有计数都能用文中命令复现
+- [ ] 已做一致性检查，A4 / A8 / A11 / A17 / A21 没有被高估
+- [ ] 已写明静态检查覆盖不到的部分
+- [ ] 没有密钥、内部路径、客户隐私
+- [ ] Audit 只读；未改代码、未起服务
+- [ ] 计划每阶段可回滚、有验收

package/evals/cases.json

@@ -0,0 +1,110 @@
+[
+  {
+    "name": "a17-default",
+    "root": "a17-default",
+    "args": ["--pack", "app", "--format", "json"],
+    "expect": { "exit": 0, "findings": { "A17": 1 } }
+  },
+  {
+    "name": "a17-boundaries",
+    "root": "a17-boundaries",
+    "args": ["--pack", "app", "--format", "json"],
+    "expect": { "exit": 0, "findings": { "A17": 1 } }
+  },
+  {
+    "name": "a6-empty-catch",
+    "root": "a6-empty-catch",
+    "args": ["--pack", "app", "--format", "json"],
+    "expect": { "exit": 0, "findings": { "A6": 1 } }
+  },
+  {
+    "name": "ignore-active",
+    "root": "ignore-active",
+    "args": ["--pack", "app", "--format", "json"],
+    "expect": { "exit": 0, "findings": {}, "ignored": 1 }
+  },
+  {
+    "name": "ignore-expired",
+    "root": "ignore-expired",
+    "args": ["--pack", "app", "--format", "json", "--ci"],
+    "expect": { "exit": 1, "findings": { "A17": 1 }, "expired": 1 }
+  },
+  {
+    "name": "library-a11",
+    "root": "library-a11",
+    "args": ["--pack", "library", "--format", "json"],
+    "expect": { "exit": 0, "findings": { "A11": 1 } }
+  },
+  {
+    "name": "zero-files",
+    "root": "zero-files",
+    "args": ["--pack", "library", "--format", "json"],
+    "expect": { "exit": 2, "findings": {}, "warnings": 1 }
+  },
+  {
+    "name": "a17-generated-header",
+    "root": "a17-generated-header",
+    "args": ["--pack", "app", "--format", "json"],
+    "expect": { "exit": 0, "findings": { "A17": 1 } }
+  },
+  {
+    "name": "a21-plaintext",
+    "root": "a21-plaintext",
+    "args": ["--pack", "app", "--format", "json"],
+    "expect": { "exit": 0, "findings": { "A21": 2 } }
+  },
+  {
+    "name": "a2-workspace",
+    "root": "a2-workspace",
+    "args": ["--pack", "library", "--format", "json"],
+    "expect": { "exit": 0, "findings": { "A2": 1 } }
+  },
+  {
+    "name": "a2-declared",
+    "root": "a2-declared",
+    "args": ["--pack", "library", "--format", "json"],
+    "expect": { "exit": 0, "findings": {} }
+  },
+  {
+    "name": "a6-clean",
+    "root": "a6-clean",
+    "args": ["--pack", "app", "--format", "json"],
+    "expect": { "exit": 0, "findings": {} }
+  },
+  {
+    "name": "a11-marker",
+    "root": "a11-marker",
+    "args": ["--pack", "library", "--format", "json"],
+    "expect": { "exit": 0, "findings": {} }
+  },
+  {
+    "name": "a17-local",
+    "root": "a17-local",
+    "args": ["--pack", "app", "--format", "json"],
+    "expect": { "exit": 0, "findings": {} }
+  },
+  {
+    "name": "a17-generated-data",
+    "root": "a17-generated-data",
+    "args": ["--pack", "app", "--format", "json"],
+    "expect": { "exit": 0, "findings": {} }
+  },
+  {
+    "name": "a21-placeholders",
+    "root": "a21-placeholders",
+    "args": ["--pack", "app", "--format", "json"],
+    "expect": { "exit": 0, "findings": {} }
+  },
+  {
+    "name": "a21-doc-paths",
+    "root": "a21-doc-paths",
+    "args": ["--pack", "design-system", "--format", "json"],
+    "expect": { "exit": 0, "findings": { "A21": 2 } }
+  },
+  {
+    "name": "sarif",
+    "root": "a17-default",
+    "args": ["--pack", "app", "--format", "sarif"],
+    "expect": { "exit": 0, "sarif": { "version": "2.1.0", "rule": "A17" } }
+  }
+]

package/evals/fixtures/a11-marker/packages/core/dist/tokens.css

@@ -0,0 +1,4 @@
+/* 生成物 · 勿手改：由 core build 产出 */
+:root {
+  --color-fg: #111;
+}

package/evals/fixtures/a11-marker/packages/core/package.json

@@ -0,0 +1 @@
+{ "name": "@x/core" }

package/evals/fixtures/a11-marker/packages/core/src/index.ts

@@ -0,0 +1 @@
+export const version = '1.0.0'