@ultime/codecraft 1.1.0 → 1.2.1

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 1.2.1 - 2026-10-27
+
+- 修复 pack 自动判定：识别 Nuxt 2 的 `pages/`、Nuxt 3 的 `app/`、uni-app 的 `manifest.json + pages.json`、Taro / uni-app 依赖，以及 workspace 内的嵌套应用。
+- 新增 `trae-cn` 安装目标（`~/.trae-cn/skills`）；`--agent` 顺序改为 generic / claude / cursor / trae / trae-cn，不再默认优先 Trae。
+- 扫描 0 个源文件时输出警告并以 2 退出，避免把空扫描当成通过。
+- README 补充 agent 列表、`--dest`、`Files: 0` 与 Trae CN 的说明。
+
+## 1.2.0 - 2026-10-27
+
+- 新增 `ignore` 例外配置（A12）：`rule` / `file` / `reason` 必填，`expires` 可选；支持 `*` / `**` / `?` 路径匹配；安全规则 `A21` 不可豁免。
+- 命中例外的 findings 不再影响退出码，但仍在报告的 `Ignored` 表和 JSON 的 `ignored` / `exceptions` 中可见；过期例外汇总到 `Expired Exceptions`。
+- 错误信息补充下一步：root 不存在、config 非法、pack 不匹配、未知命令。
+- README 增加 FAQ 与版本口径；`docs/04` 与配置示例补充 `ignore`。
+- 文档明确范围：JS/TS、默认前端、示例原生优先、Node 后端只复用结构规则；框架示例只保留 Vue 3 / React，其它框架留扩展位。
+
 ## 1.1.0 - 2026-10-27
 
 - 新增根 `SKILL.md`，兼容 Agent Skills / `skills-npm`；安装 `@ultime/codecraft` 后可被自动发现。

package/CONTRIBUTING.md

@@ -19,9 +19,20 @@
 ## 验证
 
 ```bash
-node --test tests/*.test.mjs
+npm test
+npm pack --dry-run
 node bin/codecraft.mjs check --root <项目>
 ```
 
 - 新增 / 修改规则必须补测试；没有反例的规则降级为「参考」。
 - 不提交密钥、客户名、内部路径；发现疑似凭据立即停止并提示轮换。
+
+## 版本号
+
+只按 semver，不按「感觉重要」升 major：
+
+- **major**：破坏性变更——规则 ID 语义变更、配置格式不兼容、JSON 输出结构变化。
+- **minor**：新能力——CLI 选项、检查规则、适配器、模板、向后兼容的配置字段。
+- **patch**：修复、文档、提示词、测试、CI，或无行为变化的内部调整。
+- `2.0` 不设时间表；没有破坏性变更就不进 major。
+- 发布前同时改 `VERSION`、`package.json`、`CHANGELOG.md`，并跑 `npm test` 与 `npm pack --dry-run`。

package/README.md

@@ -1,7 +1,7 @@
 # Codecraft（代码手艺）
 
-> 语言无关的代码规范，作为可安装的 skill 包。
-> 让 AI 和人在新项目、旧项目、评审中按同一套约束工作，并能按版本引入。
+> 面向 JS/TS 的代码规范与架构设计，作为可安装的 skill 包。
+> 默认 Web 前端；示例原生优先（TS / 原生 Web API），框架只给 Vue 3 / React；Node 后端只复用结构规则；其它语言不在范围。
 
 - 版本：见 [VERSION](./VERSION)
 - npm：[@ultime/codecraft](https://www.npmjs.com/package/@ultime/codecraft)
@@ -21,6 +21,26 @@
 
 > 第一次用：直接看 [安装](#安装) 和 [第一次使用](#第一次使用)。
 
+## 范围与分层
+
+| 项 | 内容 |
+|---|---|
+| 覆盖 | JS/TS 项目；Web 前端为默认场景（示例原生优先，框架仅 Vue 3 / React） |
+| 可复用 | Node 后端：模块边界、依赖方向、内外分离、生成物、门禁与文档规则 |
+| 不适用 | Page / Component 等前端族；数据库、缓存、并发、事务等后端专项 |
+| 不在范围 | Java / Go / Python 等其它语言；后端专项另立体系 |
+
+内容分三层，按需取用：
+
+| 层 | 回答什么 | 位置 |
+|---|---|---|
+| **规则** | 什么不能变 | [`docs/00-constitution.md`](./docs/00-constitution.md) |
+| **形状** | 边界与结构长什么样 | [`docs/06-architecture.md`](./docs/06-architecture.md)、[`docs/01-family-cards.md`](./docs/01-family-cards.md) |
+| **示例** | 原生怎么落，框架怎么对应 | 族卡的形状、[`templates/`](./templates/)、[`docs/05-patterns.md`](./docs/05-patterns.md) |
+
+> 族卡的形状默认原生（HTML + TS）；框架示例只给 Vue 3 / React，其它框架在族卡 §12 登记，不预建。
+
+
 ## 安装
 
 ### 方式 A：npm + skills-npm（推荐，多项目 / 团队）
@@ -38,15 +58,19 @@ npx skills-npm setup
 npx @ultime/codecraft install
 ```
 
-自动检测当前项目的 agent，把 `SKILL.md`、`docs/`、`scenarios/`、`prompts/` 复制到 `.agents/skills/codecraft` 和对应 agent 目录（`.claude/skills`、`.trae/skills`、`.cursor/skills`）。
+自动检测当前项目的 agent，把 `SKILL.md`、`docs/`、`scenarios/`、`prompts/` 复制到 `.agents/skills/codecraft` 和对应 agent 目录（`.claude/skills`、`.cursor/skills`、`.trae/skills`、`.trae-cn/skills`）。不传 `--agent` 时只按检测结果安装，不优先任何一家。
 
 ```bash
-npx @ultime/codecraft install --agent claude          # 指定 agent，可逗号分隔
-npx @ultime/codecraft install --global --agent claude # 装到用户目录
-npx @ultime/codecraft install --dry-run               # 只看计划
-npx @ultime/codecraft install --force                 # 覆盖已有目录
+npx @ultime/codecraft install --agent generic          # 指定 agent，可逗号分隔
+npx @ultime/codecraft install --global --agent claude  # 装到用户目录
+npx @ultime/codecraft install --global --agent trae-cn # Trae CN 的全局目录
+npx @ultime/codecraft install --global --dest .trae-cn/skills  # 自定义目录
+npx @ultime/codecraft install --dry-run                # 只看计划
+npx @ultime/codecraft install --force                  # 覆盖已有目录
 ```
 
+可选 agent：`generic` / `claude` / `cursor` / `trae` / `trae-cn`；未知目录用 `--dest`。
+
 ### 方式 C：手动指针
 
 不复制文件，只在项目规则里留一行：
@@ -175,7 +199,7 @@ codecraft install --dry-run
 | `library` | A2 / A11 / A21 | 包不 import app、相对路径不逃逸、workspace 依赖必须声明；生成物必须有“勿手改 / 派生”标记；密钥扫描 |
 | `design-system` | A2 / A11 / A21 | library 规则 + 包内公开文档不得引用内部 `docs/` |
 
-`--pack auto` 的判定顺序：
+`--pack auto` 的判定顺序（基于 JS/TS 生态的目录与 `package.json`）：
 
 1. 有 `apps/` 或 `src/pages` → `app`
 2. 有 `packages/` 或根 `package.json` → `library`
@@ -195,12 +219,22 @@ A4（单一收口）属于结构判断，由 review 与项目门禁负责，不
   "gates": [
     { "name": "typecheck", "run": "pnpm typecheck", "timeoutMs": 120000 },
     { "name": "test", "run": "pnpm test", "timeoutMs": 120000 }
+  ],
+  "ignore": [
+    {
+      "rule": "A17",
+      "file": "src/pages/legacy/**",
+      "reason": "legacy page; migrate in 2026-Q4",
+      "expires": "2026-12-31"
+    }
   ]
 }
 ```
 
 - `pack`：`app` / `library` / `design-system` / `auto`。
 - `gates`：数组；每项必须有一个非空的 `run` 字符串，可选 `name`、`timeoutMs`（默认 `120000`）。
+- `ignore`：例外登记（A12）。每项必须有 `rule` / `file` / `reason`，`expires` 可选（`YYYY-MM-DD`）；`file` 支持 `*` / `**` / `?`。安全规则 `A21` 不可豁免。
+- 命中的 findings 不参与退出码，但仍出现在报告的 `Ignored` 表与 JSON 的 `ignored`；过期的条目不生效，列在 `Expired Exceptions`。
 - gate 在 `--root` 下通过 shell 执行，注入 `CI=1`；失败时报告尾部 40 行 / 4000 字符。
 - `check` 不跑 gates；`audit` 默认跑；`plan` 只在 `--with-gates` 时跑。
 - 通用规则内置，业务门禁只编排、不复制。构建指引见 [`docs/04-gates.md`](./docs/04-gates.md)。
@@ -223,13 +257,28 @@ ROADMAP.md    后续版本计划与交接说明
 ## 版本与稳定承诺
 
 - semver；当前版本见 [VERSION](./VERSION)。
+- **major**：只用于破坏性变更——规则 ID 语义变更、配置格式不兼容、JSON 输出结构变化。
+- **minor**：新能力——CLI 选项、检查规则、适配器、模板、向后兼容的配置字段。
+- **patch**：修复、文档、提示词、测试、CI，或无行为变化的内部调整。
+- 不按「感觉重要」升 major；`2.0` 不设时间表。
 - 规则 ID `A1–A21` 稳定；增删规则属于 minor 以上的变更。
 - 报告始终携带版本号；跨版本对比以 JSON 为准。
 - 后续计划：[ROADMAP.md](https://github.com/ultime-space/skills/blob/main/codecraft/ROADMAP.md)。
 
+## FAQ
+
+- **静态检查误报怎么办？** 在 `codecraft.config.json` 的 `ignore` 里登记 `rule` + `file` + `reason`，必要时加 `expires`；不要直接删规则。
+- **`Files: 0` 是什么意思？** 没有扫到源文件，命令会输出警告并以 2 退出；用 `--pack app|library` 指定正确类型，或检查 `--root`。
+- **Trae CN 装到哪？** 用 `--agent trae-cn`（`~/.trae-cn/skills`）；未知目录用 `--dest`。
+- **`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`；其它语言不覆盖。
+
 ## 边界
 
 - 静态检查是文本级：能覆盖高置信模式，可能漏报或误报；最终以项目门禁与 review 为准。
+- 机检只扫描 JS/TS 相关文件（`.ts` / `.tsx` / `.js` / `.jsx` / `.mjs` / `.cjs` / `.vue` / `.svelte`）与 `package.json`，其它语言不覆盖。
 - 不内置任何业务规则、框架约定或公司内部门禁。
 - 不读取、不上传代码；所有检查在本地完成。
 

package/SKILL.md

@@ -1,16 +1,39 @@
 ---
 name: codecraft
-description: 语言无关的代码规范（Codecraft）。用于项目代码审计与分析、架构设计、重构评审、代码规范检查和脚手架。Language-agnostic code standard for auditing, reviewing, designing, and scaffolding code.
+description: 面向 JS/TS 的代码规范与架构设计（Codecraft）。默认 Web 前端，Node 后端可复用结构规则；用于审计、架构设计、重构评审、规范检查与脚手架。Code standard and architecture design for JS/TS projects (frontend-first; structural rules reusable for Node backends).
 ---
 
 # Codecraft（代码手艺）
 
+> 方向：JS/TS。默认场景是 Web 前端；示例原生优先（TS / 原生 Web API），框架只给 Vue 3 / React；Node 后端只复用结构规则；其它语言不在范围。
+
+## 范围
+
+| 项 | 内容 |
+|---|---|
+| 覆盖 | JS/TS 项目；页面、组件、行为、状态、传输、类型、包、脚本、测试 |
+| 可复用 | Node 后端：模块边界、依赖方向、内外分离、生成物、门禁与文档规则 |
+| 不适用 | 前端专属族（Page / Component）；后端数据库、缓存、并发、事务等专项规范 |
+| 不在范围 | Java / Go / Python 等其它语言；后端专项另立体系，本 skill 不承诺覆盖 |
+
+> 示例顺序：原生 → Vue 3 / React；其它框架不预建，先在 `docs/01-family-cards.md` §12 登记。
+
+## 读法（按任务路由）
+
+| 任务 | 先读 | 产出 |
+|---|---|---|
+| 审计 / 评审现有代码 | 宪法 + 相关族卡 | 报告（只读） |
+| 设计架构 / 拆边界 | `docs/06-architecture.md` + 宪法 | 计划 / ADR（只读） |
+| 新项目 / 脚手架 | `06` + `scenarios/new-project.md` | 骨架计划；必要时 `init` |
+| 选型（模式 / 库） | `docs/05-patterns.md` | 选型与代价 |
+| 改代码 | 宪法 + 相关族卡 + 项目门禁 | 变更 + 验证 |
+
 ## 先读
 
 1. 项目 `AGENTS.md` / `rules/`
 2. `docs/00-constitution.md`
-3. 只读相关族卡：`docs/01-family-cards.md`
-4. 设计架构时：`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` 执行
@@ -37,6 +60,7 @@ description: 语言无关的代码规范（Codecraft）。用于项目代码审
 - 把业务逻辑放进 Transport 或 Page。
 - 内部代码 import `external/` 或生成类型。
 - 手改生成物。
+- 把前端族规则套到 Node 后端（Page / Component / UI 不适用）。
 - 写敏感信息；发现即停止、脱敏、提示轮换。
 - 安全红线登记例外。
 

package/VERSION

@@ -1 +1 @@
-1.1.0
+1.2.1

package/adapters/claude/SKILL.md

@@ -1,10 +1,12 @@
 ---
 name: codecraft
-description: 语言无关的代码规范（Codecraft）。用于项目代码审计与分析、架构设计、重构评审、代码规范检查和脚手架。Language-agnostic code standard for auditing, reviewing, designing, and scaffolding code.
+description: 面向 JS/TS 的代码规范与架构设计（Codecraft）。默认 Web 前端，Node 后端可复用结构规则；用于审计、架构设计、重构评审、规范检查与脚手架。
 ---
 
 # Codecraft（代码手艺）
 
+> 方向：JS/TS（默认前端）。后端只复用结构规则；Page / Component 等前端族不套用到后端。
+
 ## 先读
 
 1. 项目 `AGENTS.md` / `rules/`

package/adapters/generic/AGENTS.md

@@ -1,5 +1,7 @@
 # Codecraft Adapter（通用）
 
+> 方向：JS/TS（默认前端）。Node 后端只复用模块边界与依赖规则；Page / Component 不适用。
+
 当任务涉及写代码、重构、评审、审计或脚手架时：
 
 1. 读项目 `AGENTS.md` / `rules/`。

package/adapters/trae/SKILL.md

@@ -1,10 +1,12 @@
 ---
 name: codecraft
-description: 语言无关的代码规范（Codecraft）。用于项目代码审计与分析、架构设计、重构评审、代码规范检查和脚手架。Language-agnostic code standard for auditing, reviewing, designing, and scaffolding code.
+description: 面向 JS/TS 的代码规范与架构设计（Codecraft）。默认 Web 前端，Node 后端可复用结构规则；用于审计、架构设计、重构评审、规范检查与脚手架。
 ---
 
 # Codecraft（代码手艺）
 
+> 方向：JS/TS（默认前端）。后端只复用结构规则；Page / Component 等前端族不套用到后端。
+
 ## 先读
 
 1. 项目 `AGENTS.md` / `rules/`

package/codecraft.config.example.json

@@ -11,5 +11,13 @@
       "run": "pnpm test",
       "timeoutMs": 120000
     }
+  ],
+  "ignore": [
+    {
+      "rule": "A17",
+      "file": "src/pages/legacy/**",
+      "reason": "legacy page; migrate in 2026-Q4",
+      "expires": "2026-12-31"
+    }
   ]
 }

package/docs/00-constitution.md

@@ -1,11 +1,23 @@
-# 代码宪法 v1（语言无关）
+# 代码宪法 v1（JS/TS）
 
 > 2026-10-27 · v1 稳定版。
-> 用途：给人和 AI 的共同约束；语言无关，具体语法见《代码族卡 v1》。
+> 用途：给人和 AI 的共同约束；适用于 JS/TS 项目，默认前端场景。
 > 读者：团队 / AI（Design Specification）。
 > 术语：English（中文）。
 
-## 0. 第一性
+## 0. 范围与读法
+
+| 项 | 内容 |
+|---|---|
+| 覆盖 | JS/TS；Web 前端为默认场景 |
+| 可复用 | Node 后端：M1–M5 与 A1–A21 中的结构、边界与安全规则 |
+| 部分适用 | A5 / A6 / A8 的验收列是 TS / 前端写法（`assertNever` / `satisfies` / `computed`）；其它实现只要证明同一不变量即可 |
+| 示例顺序 | 原生（TS / Web API）→ Vue 3 / React → 其它框架（不预建，族卡 §12 登记） |
+| 不在范围 | Page / Component 等前端族；数据库、缓存、并发、事务；其它语言 |
+
+> 读法：§1 元判据 → §2 不变量 → 按主题查 §3 → 族形查《代码族卡 v1》。
+
+## 0.1 第一性
 
 **可预测性（Predictability）**：同一类东西长得一样；同一类改动只动一处；错误看得见；文档不会撒谎。
 
@@ -237,7 +249,7 @@ repo/
 |---|---|---|---|
 | **Transport（传输）** | 网络 / HTTP / 取消 | 有远程调用时 | 自研 / 第三方 |
 | **Wrapper（包装）** | 外部 → 内部转换 | 有外部契约时 | 自研 / 生成 |
-| **Behavior（行为）** | 页面无关行为 | 有复用 / 复杂逻辑时 | composable / hook / service |
+| **Behavior（行为）** | 页面无关行为 | 有复用 / 复杂逻辑时 | 纯函数 / 状态机；需要时再加 composable / hook / service |
 | **State（状态）** | 状态建模与转移 | 有异步 / 多态时 | 联合类型 / 状态机 |
 | **Concurrency（并发控制）** | 去重 / 共享 in-flight / 取消 | 有并发请求时 | 自研 / 第三方 / 不做 |
 | **Observability（可观测性）** | 日志 / 追踪 / 请求序 | 需要排障时 | console / APM / 不做 |
@@ -306,5 +318,5 @@ repo/
 
 ## 7. 待定
 
-- 第一个语言方言是 TS/JS，还是同时写 Java/Go？
 - 每条规则的 owner 和到期日。
+- 后端（Node）专项是否独立成体系；当前只复用本宪法的结构与安全规则。

package/docs/01-family-cards.md

@@ -1,7 +1,10 @@
-# 代码族卡 v1（11 个环节）
+# 代码族卡 v1（11 个环节 · JS/TS）
 
 > 2026-10-27 · v1 稳定版。
 > 用途：把《代码宪法 v1》落到每个代码族（环节）；不同族可以不同形状，族内必须同形。
+> 形状与示例原生优先：TS + 原生 Web API（DOM / fetch / CustomEvent）为默认；框架示例只给 Vue 3 / React。
+> 其它框架不预建，先在 §12 扩展位登记。
+> 前端专用族：Page / Component；Node 后端只复用结构与边界类族。
 > 术语：English（中文）。
 
 ## 0. 卡模板
@@ -10,11 +13,29 @@
 
 > 族是「环节」，不是必须模块；项目没有这个职责时，这一族可以不存在。
 
-## 1. Page（页面）
+## 0.1 适用范围
+
+| 族 | 前端 | Node 后端 | 备注 |
+|---|---|---|---|
+| Page | ✅ | ❌ | 后端无对应物，不要硬造 |
+| Component | ✅ | ❌ | 同上 |
+| Behavior | ✅ | ⚠️ | 对应 domain service；core 不依赖框架仍成立 |
+| Transport | ✅ | ✅ | 后端是 client / adapter |
+| Wrapper | ✅ | ✅ | 防腐层，规则一致 |
+| Type | ✅ | ✅ | 联合类型等验收项按语言替换 |
+| Package | ✅ | ✅ | 包边界、版本、public API 规则通用 |
+| State | ✅ | ⚠️ | 状态机 / 领域状态可用；computed 换成同义派生 |
+| Util | ✅ | ✅ | 纯函数，规则一致 |
+| Script | ✅ | ✅ | 脚本通用 |
+| Test | ✅ | ✅ | 分层测试策略通用 |
+
+> ✅ 直接用；⚠️ 思路可用、形状要按项目重写；❌ 不适用。
+
+## 1. Page（页面）· 前端专用
 
 - **职责**：组合根；路由入口；只做编排、布局、状态展示；不承载业务规则。
-- **形状**：`pages/<domain>/index.vue` + `index.config.ts`；页面级类 `page-*`；页面骨架固定为顶栏 / 内容 / 底栏 / 弹层四插槽（组件名按项目命名）。
-- **命名**：目录 kebab-case；组件 PascalCase；页面级类 `page-*`（标作用域，不做装饰）。
+- **形状**：`pages/<domain>/index.html` + `index.ts`（原生）；`index.vue`（Vue）；`index.tsx`（React）。页面级类 `page-*`；页面骨架固定为顶栏 / 内容 / 底栏 / 弹层四插槽（组件名按项目命名）。
+- **命名**：目录 kebab-case；页面级类 `page-*`（标作用域，不做装饰）；组件名原生用 kebab-case 自定义元素，Vue / React 用 PascalCase。
 - **契约**：接收路由参数；调用 Behavior Layer（行为层）；渲染 loading / empty / error / success；不直接 import api。
 - **状态与错误**：页面状态由 Behavior Layer 提供；页面只持有纯 UI 状态（弹窗、tab）；错误必须可见。
 - **测试**：集成 / 视觉回归；纯 UI 不写单元测试。
@@ -22,22 +43,22 @@
 - **反例**：页面直接 import api；页面里写请求与转换；多个互斥布尔。
 - **验收**：lint「pages 不 import `@/api`」；路由 / 页面清单；视觉回归。
 
-## 2. Behavior Layer（行为层）
+## 2. Behavior Layer（行为层）· 前端为主
 
 - **职责**：页面无关的行为；状态转移、校验、编排；不放 UI、不放平台细节。
-- **形状**：Vue3 `composables/<domain>/<verb>.ts`；React `hooks/<domain>/<verb>.ts`；需要跨框架时拆 `behavior/<domain>/core.ts` + `useXxx.ts`。
-- **命名**：`useXxx` 适配器；`xxxCore` / `xxxBehavior` 核心；一个文件一个动词；同族一种前缀。
+- **形状**：默认 `behavior/<domain>/<verb>.ts`（纯 TS，不依赖框架）；需要框架绑定时再加薄适配 `useXxx.ts`（Vue composable / React hook）。
+- **命名**：`xxxCore` / `xxxBehavior` 核心；`useXxx` 适配器；一个文件一个动词；同族一种前缀。
 - **契约**：入参 / 选项明确；返回状态 + 动作；不藏模块级单例；core 不 import 框架。
-- **状态与错误**：状态用联合类型；派生用 computed / selector；预期失败用 Result / 域变体。
+- **状态与错误**：状态用联合类型；派生用纯函数（Vue `computed` / React selector）；预期失败用 Result / 域变体。
 - **测试**：core 属性测试；适配器集成测试。
-- **正例**：`useList` / `refreshList(state, fetchPage)` / `useFilterList`。
-- **反例**：composable 直接 toast / 跳转；模块级可变状态；为一次性页面逻辑硬抽 composable。
-- **验收**：依赖规则「behavior core 不 import vue / react / uni / taro」；状态转移测试；`any` lint。
+- **正例**：`listBehavior` + `useList`（适配层）；`refreshList(state, fetchPage)`。
+- **反例**：适配层直接 toast / 跳转；模块级可变状态；为一次性页面逻辑硬抽 composable。
+- **验收**：依赖规则「behavior core 不 import vue / react 或其它框架运行时」；状态转移测试；`any` lint。
 
 ## 3. Transport（传输层）
 
 - **职责**：网络、HTTP、取消；原样透传；不解释业务 code。401 / 日志是可选环节；外部契约转换在 Wrapper（包装层）。
-- **形状**：`api/` 或 `request/`；`adapter/` / `interceptors/` / `modules/`；`pending/` / `console/` 是可选环节，不是必须目录。
+- **形状**：`api/` 或 `request/`；`adapter/` / `interceptors/` / `modules/`；默认用原生 `fetch` + `AbortController`，框架封装只作可选实现；`pending/` / `console/` 是可选环节，不是必须目录。
 - **命名**：API 文件 snake_case 且与 URL 同名；一 URL 一文件。新代码推荐 `api/<domain>/<action>.ts` + `fetchXxx` / `getXxx`；旧项目可保留 `api_` 前缀（防重名、可搜索、标层）；同族不要混用。
 - **契约**：返回 raw response 或传输层结果；不产出域类型；错误只做传输层归一。
 - **状态与错误**：无 UI 状态；401 单一收口；超时 / 取消 / 网络错误；不弹业务 toast。
@@ -99,12 +120,12 @@
 - **反例**：`utils` 包；工具包 import 应用；包内混入业务页面。
 - **验收**：`boundaries`；包 build / test；`exports` 检查；兼容矩阵。
 
-## 7. Component（组件）
+## 7. Component（组件）· 前端专用
 
 - **职责**：UI 展示与交互；只消费 props / emit；不取数、不放业务规则；可复用、可组合。
-- **形状**：目录式 `components/<Name>/index.vue` + `index.scss`；全局原语放 `app-ui/`；页面私有组件放页面目录。
-- **命名**：PascalCase 目录 / 组件；`app-` 用于全局原语；角色后缀 `XxxCard / XxxList / XxxForm / XxxModal / XxxPage`；类型 `XxxProps / XxxEmits`。
-- **契约**：props 下行、emit 上行；不 import api / behavior；不读业务 store（仅全局身份 / 权限例外）；样式 scoped / BEM；可访问性（键盘 / ARIA / 对比度）。
+- **形状**：`components/<Name>/index.html` + `index.css`（+ 可选 `index.ts`）；Vue `index.vue`；React `index.tsx`；全局原语放 `app-ui/`；页面私有组件放页面目录。
+- **命名**：原生自定义元素 kebab-case；Vue / React 组件 PascalCase；`app-` 用于全局原语；角色后缀 `XxxCard / XxxList / XxxForm / XxxModal / XxxPage`；类型 `XxxProps / XxxEmits`（Vue / React）。
+- **契约**：attributes / properties 下行、`CustomEvent` 上行（Vue / React 对应 props / emit）；不 import api / behavior；不读业务 store（仅全局身份 / 权限例外）；样式 scoped / BEM；可访问性（键盘 / ARIA / 对比度）。
 - **状态与错误**：只持有纯 UI 状态（open / hover / focus）；loading / empty / error 由 props 传入；不吞错。
 - **测试**：示例页 / Storybook；交互测试；视觉回归；a11y。
 - **正例**：页面骨架组件、`XxxCard`、`XxxGrid`。
@@ -114,12 +135,12 @@
 ## 8. State（状态）
 
 - **职责**：领域状态建模；状态是数据，不是布尔堆；转移通过事件 / 动作。
-- **形状**：`types/<domain>` 的联合类型；`behavior/<domain>/core.ts` 的 reducer / state machine；store 只存数据 + setter。
+- **形状**：默认纯 TS：`types/<domain>` 的联合类型 + `behavior/<domain>/core.ts` 的 reducer / state machine；store 只存数据 + setter，框架只做订阅与派生。
 - **命名**：`XxxState` / `XxxStatus` / `XxxEvent` / `XxxAction`；通用 `AsyncState / ListState` 放 `types/common`。
-- **契约**：状态用联合类型；非法状态不可表示；`success` 有 data，`error` 有 error；派生用 selector / computed。
+- **契约**：状态用联合类型；非法状态不可表示；`success` 有 data，`error` 有 error；派生用纯函数（Vue `computed` / React selector）。
 - **错误**：错误分类；预期失败用 Result / 域变体；空 catch 为零。
 - **测试**：状态转移表 / 属性测试；关键流程。
-- **正例**：`useList` 的 status；auth machine；form state。
+- **正例**：`listBehavior` 的 status；auth machine；form state。
 - **反例**：`loading / error / data` 三个布尔；store 放请求逻辑；派生状态另存一份。
 - **验收**：`assertNever`；`satisfies Record<Union, T>`；状态转移测试。
 
@@ -150,7 +171,7 @@
 ## 11. Test（测试）
 
 - **职责**：保护契约与关键路径；不是追覆盖率。
-- **形状**：`tests/` 或 `__tests__/`；fixture 单独；命名 `<unit>.test.ts`。
+- **形状**：`tests/` 或 `__tests__/`；fixture 单独；命名 `<unit>.test.ts`；默认 `node:test`，组件交互 / 视觉测试再按项目选工具。
 - **命名**：`describe('<unit> · <behavior>')`、`it('does X when Y')`；中英文随项目，保持一致。
 - **契约**：
   - Pure core → 属性测试 / 单元测试；
@@ -166,4 +187,6 @@
 
 ## 12. 扩展位
 
-新的族先在这里登记，不预建结构。
+当前收录的框架示例：Vue 3、React；其它框架不预建目录与示例，先在这里登记。
+
+登记时补四项：入口形状、状态派生方式、组件契约（props / events）、测试工具。

package/docs/02-ai-contract.md

@@ -2,15 +2,16 @@
 
 > 2026-10-27 · v1 稳定版。
 > 用途：所有模型 / agent 生成或修改代码前先读；与《代码宪法 v1》《代码族卡 v1》配套。
+> 范围：JS/TS 项目，默认前端。示例原生优先（TS / Web API），框架只给 Vue 3 / React；Node 后端只套用结构与安全规则，Page / Component 等前端族不适用。
 > 术语：English（中文）。
 
 ## 1. 先读
 
-1. 《代码宪法 v1》
-2. 相关《代码族卡 v1》
-3. 设计架构时：`06-architecture.md`（档位 / 七步法 / 边界 / ADR）
-4. 需要选型时：`05-patterns.md`（按力选，不按名字选）
-5. 项目覆盖：`AGENTS.md` / `rules/` / `README`
+1. 项目覆盖：`AGENTS.md` / `rules/` / `README`
+2. 《代码宪法 v1》
+3. 设计或评审架构：`06-architecture.md`（档位 / 七步法 / 边界 / ADR）
+4. 只读相关《代码族卡 v1》（前端项目才读 Page / Component）
+5. 需要选型时：`05-patterns.md`（按力选，不按名字选）
 6. 相关契约 / 类型 / 测试 / 示例
 
 ## 2. 禁止
@@ -57,7 +58,7 @@
 
 ## 6. Review Checklist（评审清单）
 
-- [ ] 族形正确（Page / Behavior / Transport）
+- [ ] 族形正确（Page / Behavior / Transport；Node 后端跳过 Page / Component）
 - [ ] 依赖向内
 - [ ] 状态穷尽
 - [ ] 错误可见

package/docs/03-style-map.md

@@ -1,6 +1,7 @@
 # 风格总图（一页）
 
 > 一页看完全套约束的形状；细则见 `00-constitution.md`，字段见 `01-family-cards.md`。
+> 范围：默认 JS/TS 前端项目；结构与判据可迁移，页面 / 组件相关条目只适用于前端。
 > 读法：先看第 1 节「不变的」和第 2 节「变的」，其余是判据与代价。
 
 ## 一句话

package/docs/04-gates.md

@@ -1,6 +1,7 @@
 # Gates（两层门禁）
 
 > Codecraft 只内置“规范性通用门禁”；业务门禁由项目实现，Codecraft 负责编排与汇总。
+> 示例命令按 JS/TS 生态（`pnpm`）书写；gate 契约本身与语言无关，Node 项目同样适用。
 
 ## 1. 两层模型
 
@@ -30,12 +31,16 @@
   "gates": [
     { "name": "typecheck", "run": "pnpm typecheck", "timeoutMs": 120000 },
     { "name": "test", "run": "pnpm test", "timeoutMs": 120000 }
+  ],
+  "ignore": [
+    { "rule": "A17", "file": "src/pages/legacy/**", "reason": "legacy page", "expires": "2026-12-31" }
   ]
 }
 ```
 
 - `pack`：`app` / `library` / `design-system` / `auto`；CLI `--pack` 优先。
 - `gates`：数组；每项必须有 `run`，可选 `name` / `timeoutMs`。
+- `ignore`：例外登记（A12）；`rule` / `file` / `reason` 必填，`expires` 可选。过期条目不生效，报告中单列；安全规则 `A21` 不可豁免。
 - 配置文件默认 `codecraft.config.json`；可用 `--config` 指定。
 
 ## 4. 按项目类型选门禁

package/docs/05-patterns.md

@@ -1,6 +1,7 @@
 # 设计模式工具箱（可选）
 
 > 用途：AI 与人的「可选工具」，不是必背清单；按力（forces）选，不按名字选。
+> 范围：模式本身与语言无关；第 4 / 5 节分别是 JS/TS 惯用与前端 / UI 专用。
 > 术语：English（中文）。
 > 原则：**先有痛点，再选模式；没有代价说明的模式，不许用。**
 

package/docs/06-architecture.md

@@ -2,6 +2,7 @@
 
 > 用途：系统级 / 模块级 / 演进级的决策方法；代码级模式见 `05-patterns.md`。
 > 原则：**方法先于模式；约束先于图；边界先于抽象。**
+> 范围：方法本身与语言无关，可用于 JS/TS 前端与 Node 后端；文中目录与框架取舍以 JS/TS 为准。
 > 术语：English（中文）。
 
 ## 0. 先分开六个词
@@ -104,6 +105,7 @@ src/
 ```
 
 - 依赖只能向下；同层不互相 import；跨模块只走 public API。
+- 结构默认与框架无关：原生能表达的先写原生，Vue / React 只作页面与组件的落点。
 - `shared/api` + adapter + interceptors 是承重墙，不塞进 feature。
 - server state 与 client state 分开：server state 用 query 层；client state 用 store / 状态机。
 - 测试分层：纯 core 单测 → feature 行为测试 → 页面 smoke → API 契约测试。

package/docs/07-ai-prompts.md

@@ -1,6 +1,7 @@
 # AI 使用提示词（Prompts）
 
 > 用途：给使用者一份可以直接复制的说法，让 AI 按 Codecraft 的模式工作。
+> 范围：提示词按 JS/TS 项目写；Node 后端只复用审计 / 架构 / 评审类提示词。
 > 读法：先看「最小开场」，再按场景复制；提示词不替代规则，规则正文仍在 `docs/`。
 > 关系：入口见 `adapters/`；输出格式见 `prompts/output.md`；约束见 `02-ai-contract.md`。
 

package/evals/golden-tasks.md

@@ -1,5 +1,7 @@
 # Golden Tasks（评估任务）
 
+> 任务默认按 JS/TS 前端项目设计；Node 后端只复用审计 / 架构 / 评审类任务，数据库、缓存、并发不在本批评估内。
+
 用于验证 skill 是否真的按规范工作。每条任务记录：结果、版本、误报 / 漏报。
 
 ## 1. 新项目架构计划

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ultime/codecraft",
-  "version": "1.1.0",
-  "description": "Language-agnostic code standard as an installable skill package.",
+  "version": "1.2.1",
+  "description": "面向 JS/TS 的代码规范与架构设计（前端默认，Node 后端可复用结构规则），作为可安装的 skill 包。",
   "keywords": [
     "ai",
     "code-standard",

package/src/cli.mjs

@@ -4,6 +4,7 @@ import { check } from './check.mjs'
 import { loadConfig, runGates } from './gates.mjs'
 import { buildPlan, summarizePlan } from './plan.mjs'
 import { applyInitPlan, buildInitPlan } from './init.mjs'
+import { applyIgnores } from './ignore.mjs'
 import { applyInstallPlan, buildInstallPlan, parseAgents } from './install.mjs'
 
 const PACKAGE = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
@@ -23,9 +24,9 @@ Options:
   --root <path>            Project root (default: cwd)
   --pack app|library|design-system|auto  Rule pack (default: auto)
   --config <path>          Config file (default: codecraft.config.json)
-  --agent auto|claude|trae|cursor|generic  Install target, comma-separated (default: auto)
+  --agent auto|generic|claude|cursor|trae|trae-cn  Install target, comma-separated (default: auto)
   --global                 Install into the home directory
-  --dest <path>            Explicit destination (relative to root / home)
+  --dest <path>            Explicit destination (relative to root / home), e.g. .trae-cn/skills
   --force                  Replace an existing codecraft skill directory
   --dry-run                Show the install plan without writing
   --no-gates               Skip gates in audit / plan
@@ -59,13 +60,13 @@ export function main(argv) {
 
   const command = args.command || 'check'
   if (!['check', 'audit', 'plan', 'init', 'install'].includes(command)) {
-    console.error(`codecraft: unknown command "${command}"`)
+    console.error(`codecraft: unknown command "${command}"\n  next: run codecraft --help`)
     return 2
   }
 
   const root = path.resolve(process.cwd(), args.root)
   if (!fs.existsSync(root)) {
-    console.error(`codecraft: root not found: ${root}`)
+    console.error(`codecraft: root not found: ${root}\n  next: pass --root <project> or run from the project directory`)
     return 2
   }
 
@@ -115,13 +116,15 @@ export function main(argv) {
 
   const pack = resolvePack(args.pack, config.config.pack, root)
   if (!pack) {
-    console.error('codecraft: invalid config pack; expected app, library or auto')
+    console.error(
+      `codecraft: invalid config pack "${config.config.pack}"\n  next: use app, library, design-system or auto`,
+    )
     return 2
   }
 
   if (command === 'init') {
     if (args.apply && !args.name) {
-      console.error('codecraft: init --apply requires --name <name>')
+      console.error('codecraft: init --apply requires --name <name>\n  next: add --name <demo>')
       return 2
     }
     const plan = buildInitPlan(root, pack === 'design-system' ? 'library' : pack, args.name)
@@ -149,10 +152,17 @@ export function main(argv) {
   const result = check(root, { pack })
   const severity = args.ci ? 'error' : args.severity
   const findings = result.findings.map((finding) => ({ ...finding, severity }))
+  const filtered = applyIgnores(findings, config.config.ignore ?? [])
+  const activeFindings = filtered.findings
+  const warnings = []
+  if (result.files === 0 && result.findings.length === 0) {
+    warnings.push(`0 source files scanned under ${root}; pass --pack app|library or check --root`)
+    console.error(`codecraft: warning: ${warnings[0]}`)
+  }
   const gates = shouldRunGates(command, args)
     ? runGates(root, config.config.gates ?? [], { failFast: args.failFast })
     : []
-  const plan = command === 'plan' ? buildPlan(findings) : []
+  const plan = command === 'plan' ? buildPlan(activeFindings) : []
   const meta = {
     version: VERSION,
     mode: command,
@@ -162,7 +172,10 @@ export function main(argv) {
     severity,
     rules: pack === 'app' ? ['A17', 'A21'] : ['A2', 'A11', 'A21'],
     files: result.files,
-    findings: findings.length,
+    findings: activeFindings.length,
+    ignored: filtered.ignored.length,
+    expired: filtered.expired.length,
+    warnings,
     plan: plan.length,
     gates: gates.length,
   }
@@ -172,12 +185,16 @@ export function main(argv) {
       JSON.stringify(
         {
           ...meta,
-          findings,
+          findings: activeFindings,
+          ignored: filtered.ignored,
+          exceptions: filtered.exceptions,
           plan,
           gates,
           summary: {
             files: result.files,
-            findings: findings.length,
+            findings: activeFindings.length,
+            ignored: filtered.ignored.length,
+            expired: filtered.expired.length,
             plan: plan.length,
             gates: gates.length,
             gateFailures: gates.filter((gate) => gate.exitCode !== 0).length,
@@ -188,12 +205,15 @@ export function main(argv) {
       ),
     )
   } else if (command === 'plan') {
-    console.log(formatPlan(meta, findings, plan, gates))
+    console.log(formatPlan(meta, activeFindings, plan, gates))
   } else {
-    console.log(formatReport(meta, findings, gates))
+    console.log(formatReport(meta, activeFindings, filtered.ignored, filtered.expired, gates))
   }
 
-  const failed = findings.some((finding) => finding.severity === 'error') || gates.some((gate) => gate.exitCode !== 0)
+  const failed =
+    activeFindings.some((finding) => finding.severity === 'error') ||
+    gates.some((gate) => gate.exitCode !== 0)
+  if (warnings.length) return 2
   return failed ? 1 : 0
 }
 
@@ -268,19 +288,89 @@ function parseArgs(argv) {
   return args
 }
 
-function detectPack(root) {
-  if (isDir(path.join(root, 'apps')) || isDir(path.join(root, 'src', 'pages'))) return 'app'
+export function detectPack(root) {
+  if (isDir(path.join(root, 'apps'))) return 'app'
+  if (hasAppMarkers(root)) return 'app'
   if (isDir(path.join(root, 'packages'))) return 'library'
+  if (hasNestedApp(root)) return 'app'
+  if (isDir(path.join(root, 'src'))) return 'library'
   if (fs.existsSync(path.join(root, 'package.json'))) return 'library'
   return 'app'
 }
 
+const APP_DIR_MARKERS = ['src/pages', 'pages', 'app', 'src/app']
+const APP_FILE_MARKERS = [
+  'nuxt.config.js',
+  'nuxt.config.ts',
+  'nuxt.config.mjs',
+  'app.config.js',
+  'app.config.ts',
+  'src/app.config.js',
+  'src/app.config.ts',
+  'taro.config.js',
+  'taro.config.ts',
+]
+const APP_DEPS = ['nuxt', '@tarojs/taro', '@dcloudio/uni-app', 'uni-app', 'next']
+
+function hasAppMarkers(root) {
+  if (APP_DIR_MARKERS.some((dir) => isDir(path.join(root, dir)))) return true
+  if (APP_FILE_MARKERS.some((file) => isFile(path.join(root, file)))) return true
+  if (hasUniAppFiles(root)) return true
+  return hasAppDependency(root)
+}
+
+function hasNestedApp(root) {
+  let entries
+  try {
+    entries = fs.readdirSync(root, { withFileTypes: true })
+  } catch {
+    return false
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue
+    if (['node_modules', 'dist', 'build', 'target', '.git', '.nuxt', '.output', 'coverage'].includes(entry.name)) {
+      continue
+    }
+    const child = path.join(root, entry.name)
+    if (APP_DIR_MARKERS.some((dir) => isDir(path.join(child, dir)))) return true
+    if (APP_FILE_MARKERS.some((file) => isFile(path.join(child, file)))) return true
+    if (hasUniAppFiles(child)) return true
+    if (hasAppDependency(child)) return true
+  }
+  return false
+}
+
+function hasUniAppFiles(root) {
+  const atRoot = isFile(path.join(root, 'manifest.json')) && isFile(path.join(root, 'pages.json'))
+  const atSrc = isFile(path.join(root, 'src', 'manifest.json')) && isFile(path.join(root, 'src', 'pages.json'))
+  return atRoot || atSrc
+}
+
+function hasAppDependency(root) {
+  let manifest
+  try {
+    manifest = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'))
+  } catch {
+    return false
+  }
+  const deps = { ...(manifest.dependencies ?? {}), ...(manifest.devDependencies ?? {}) }
+  return APP_DEPS.some((dep) => dep in deps)
+}
+
+function isFile(target) {
+  try {
+    return fs.statSync(target).isFile()
+  } catch {
+    return false
+  }
+}
+
 function fail(message) {
   console.error(`codecraft: ${message}\n\n${HELP}`)
   process.exit(2)
 }
 
-function formatReport(meta, findings, gates) {
+function formatReport(meta, findings, ignored, expired, gates) {
   const lines = header(meta)
 
   if (!findings.length) {
@@ -292,6 +382,35 @@ function formatReport(meta, findings, gates) {
     }
   }
 
+  if (ignored.length) {
+    lines.push(
+      '',
+      '## Ignored',
+      '',
+      '| Rule | File | Line | Reason | Expires |',
+      '|---|---|---|---|---|',
+    )
+    for (const finding of ignored) {
+      lines.push(
+        `| ${finding.rule} | ${finding.file} | ${finding.line} | ${escapeCell(finding.reason)} | ${finding.expires ?? '—'} |`,
+      )
+    }
+  }
+
+  if (expired.length) {
+    lines.push(
+      '',
+      '## Expired Exceptions',
+      '',
+      '| Rule | File | Expires | Reason |',
+      '|---|---|---|---|',
+    )
+    for (const exception of expired) {
+      lines.push(`| ${exception.rule} | ${exception.file} | ${exception.expires} | ${escapeCell(exception.reason)} |`)
+    }
+    lines.push('', '- Expired exceptions no longer suppress findings; renew the date or remove the entry.')
+  }
+
   lines.push(...gateLines(gates))
   return lines.join('\n')
 }
@@ -438,6 +557,9 @@ function header(meta) {
     `- Severity: ${meta.severity}`,
     `- Files: ${meta.files}`,
     `- Findings: ${meta.findings}`,
+    `- Ignored: ${meta.ignored ?? 0}`,
+    `- Expired exceptions: ${meta.expired ?? 0}`,
+    `- Warnings: ${meta.warnings?.length ?? 0}`,
     `- Gates: ${meta.gates}`,
     '',
   ]

package/src/gates.mjs

@@ -1,30 +1,33 @@
 import fs from 'node:fs'
 import path from 'node:path'
 import { spawnSync } from 'node:child_process'
+import { validateIgnore } from './ignore.mjs'
 
 export function loadConfig(root, configPath) {
   const file = configPath ? path.resolve(root, configPath) : path.join(root, 'codecraft.config.json')
 
-  if (!fs.existsSync(file)) return { file: null, config: {} }
+  if (!fs.existsSync(file)) return { file: null, config: { ignore: [] } }
 
   let config
   try {
     config = JSON.parse(fs.readFileSync(file, 'utf8'))
   } catch (error) {
-    throw new Error(`invalid config ${file}: ${error.message}`)
+    throw new Error(
+      `invalid config ${file}: ${error.message} (fix the JSON syntax, or remove the file to use defaults)`,
+    )
   }
 
   if (config.gates != null && !Array.isArray(config.gates)) {
-    throw new Error(`invalid config ${file}: "gates" must be an array`)
+    throw new Error(`invalid config ${file}: "gates" must be an array (each item: { name?, run, timeoutMs? })`)
   }
 
   for (const gate of config.gates ?? []) {
     if (!gate || typeof gate.run !== 'string' || !gate.run.trim()) {
-      throw new Error(`invalid config ${file}: each gate needs a "run" string`)
+      throw new Error(`invalid config ${file}: each gate needs a "run" string (e.g. "pnpm test")`)
     }
   }
 
-  return { file, config }
+  return { file, config: { ...config, ignore: validateIgnore(config.ignore, file) } }
 }
 
 export function runGates(root, gates, options = {}) {

package/src/ignore.mjs

@@ -0,0 +1,145 @@
+const DATE = /^\d{4}-\d{2}-\d{2}$/
+
+/**
+ * 校验并规范化 ignore 条目。
+ * 每条必须有 rule / file / reason；expires 可选（YYYY-MM-DD）。
+ */
+export function validateIgnore(entries, configFile = 'config') {
+  if (entries == null) return []
+  if (!Array.isArray(entries)) {
+    throw new Error(
+      `invalid config ${configFile}: "ignore" must be an array (each item: { rule, file, reason, expires? })`,
+    )
+  }
+
+  return entries.map((entry, index) => {
+    const at = `ignore[${index}]`
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+      throw new Error(`invalid config ${configFile}: ${at} must be an object`)
+    }
+
+    const rule = typeof entry.rule === 'string' ? entry.rule.trim() : ''
+    if (!/^A\d+$/.test(rule)) {
+      throw new Error(`invalid config ${configFile}: ${at}.rule must be a rule id like "A17"`)
+    }
+    if (rule === 'A21') {
+      throw new Error(
+        `invalid config ${configFile}: ${at}.rule A21 is a security rule and cannot be ignored (safety red line)`,
+      )
+    }
+
+    const file = typeof entry.file === 'string' ? entry.file.trim() : ''
+    if (!file) {
+      throw new Error(`invalid config ${configFile}: ${at}.file is required (path or glob, e.g. "src/pages/legacy/**")`)
+    }
+
+    const reason = typeof entry.reason === 'string' ? entry.reason.trim() : ''
+    if (!reason) {
+      throw new Error(`invalid config ${configFile}: ${at}.reason is required (A12: every exception needs a reason)`)
+    }
+
+    const expires = entry.expires == null || entry.expires === '' ? null : String(entry.expires).trim()
+    if (expires && !isDate(expires)) {
+      throw new Error(`invalid config ${configFile}: ${at}.expires must be YYYY-MM-DD`)
+    }
+
+    return { rule, file, reason, expires }
+  })
+}
+
+/**
+ * 把 ignore 应用到 findings 上。
+ * 过期条目不生效，单独返回，供报告提示续期或删除。
+ */
+export function applyIgnores(findings, exceptions, options = {}) {
+  const today = options.today ?? localDate()
+  const active = []
+  const expired = []
+
+  for (const exception of exceptions) {
+    if (exception.expires && exception.expires < today) expired.push(exception)
+    else active.push(exception)
+  }
+
+  const kept = []
+  const ignored = []
+
+  for (const finding of findings) {
+    const matched = active.find(
+      (exception) => exception.rule === finding.rule && matchPath(exception.file, finding.file),
+    )
+    if (matched) ignored.push({ ...finding, reason: matched.reason, expires: matched.expires })
+    else kept.push(finding)
+  }
+
+  return {
+    findings: kept,
+    ignored,
+    exceptions: [
+      ...active.map((exception) => ({ ...exception, status: 'active' })),
+      ...expired.map((exception) => ({ ...exception, status: 'expired' })),
+    ],
+    expired,
+  }
+}
+
+/** 支持 * / ** / ? 的路径匹配；不含通配符时按精确路径或目录前缀匹配。 */
+export function matchPath(pattern, file) {
+  const normalizedPattern = normalize(pattern)
+  const normalizedFile = normalize(file)
+
+  if (!/[*?]/.test(normalizedPattern)) {
+    return (
+      normalizedFile === normalizedPattern ||
+      (normalizedPattern.endsWith('/') && normalizedFile.startsWith(normalizedPattern))
+    )
+  }
+
+  return globToRegExp(normalizedPattern).test(normalizedFile)
+}
+
+function normalize(value) {
+  return String(value)
+    .replace(/\\/g, '/')
+    .replace(/^\.\//, '')
+}
+
+function globToRegExp(pattern) {
+  let source = '^'
+  for (let index = 0; index < pattern.length; index += 1) {
+    const char = pattern[index]
+    if (char === '*') {
+      if (pattern[index + 1] === '*') {
+        index += 1
+        if (pattern[index + 1] === '/') {
+          source += '(?:.*/)?'
+          index += 1
+        } else {
+          source += '.*'
+        }
+      } else {
+        source += '[^/]*'
+      }
+    } else if (char === '?') {
+      source += '[^/]'
+    } else if ('\\^$+?.()|{}[]'.includes(char)) {
+      source += `\\${char}`
+    } else {
+      source += char
+    }
+  }
+  return new RegExp(`${source}$`)
+}
+
+function isDate(value) {
+  if (!DATE.test(value)) return false
+  const parsed = new Date(`${value}T00:00:00Z`)
+  return !Number.isNaN(parsed.getTime()) && parsed.toISOString().slice(0, 10) === value
+}
+
+function localDate() {
+  const now = new Date()
+  const month = String(now.getMonth() + 1).padStart(2, '0')
+  const day = String(now.getDate()).padStart(2, '0')
+  return `${now.getFullYear()}-${month}-${day}`
+}

package/src/install.mjs

@@ -8,17 +8,19 @@ const SKILL_FILES = ['SKILL.md']
 const SKILL_DIRS = ['docs', 'scenarios', 'prompts']
 
 const AGENT_DIRS = {
+  generic: '.agents/skills',
   claude: '.claude/skills',
-  trae: '.trae/skills',
   cursor: '.cursor/skills',
-  generic: '.agents/skills',
+  trae: '.trae/skills',
+  'trae-cn': '.trae-cn/skills',
 }
 
 const AGENT_MARKERS = {
+  generic: ['.agents'],
   claude: ['.claude', 'CLAUDE.md'],
-  trae: ['.trae'],
   cursor: ['.cursor'],
-  generic: ['.agents'],
+  trae: ['.trae'],
+  'trae-cn': ['.trae-cn'],
 }
 
 export const AGENTS = Object.keys(AGENT_DIRS)

package/templates/app/README.md

@@ -8,7 +8,7 @@
 |---|---|
 | `src/pages` | 页面：一个页面一个编排入口，只编排 |
 | `src/components` | 展示与交互组件；原语薄、业务组件按域 |
-| `src/behavior` | 页面无关行为（hooks / composables） |
+| `src/behavior` | 页面无关行为：默认纯 TS core，框架绑定作薄适配（hooks / composables） |
 | `src/api` | 请求收口；唯一可接触 `external/` 的层 |
 | `src/adapters` | 平台适配（请求 / 存储 / 路由 / 导出） |
 | `src/types` | 内部类型：通用层与业务层 |
@@ -17,6 +17,7 @@
 ## 规则
 
 - `pages / components / behavior` 不 import `external/` 或 `generated/`。
+- 原生能表达的先写原生；Vue / React 只作页面与组件的落点。
 - 外部类型只在 `api` / `adapters` 内转成内部类型。
 - 鉴权失效、错误提示、分页各一处收口。
 - 状态用联合类型；非法状态不可表示。