@ultime/codecraft 1.0.3 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 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` 后可被自动发现。
+- 新增 `codecraft install`：自动检测 Claude / Trae / Cursor，写入 `.agents/skills` 与对应目录；支持 `--agent` / `--global` / `--dest` / `--force` / `--dry-run`。
+- README 增加三种安装方式：`skills-npm`、内置安装器、手动指针。
+- `docs/07-ai-prompts.md` 与 adapters 补充安装入口。
+
 ## 1.0.3 - 2026-10-27
 
 - 文档从 v0 草稿固化为 v1 稳定版。

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)
@@ -19,29 +19,67 @@
 
 规则正文只在 [`docs/`](./docs/)；其它位置只放入口与指针，避免第二份真源。
 
-> 第一次用：直接看 [5 分钟上手](#5-分钟上手)。
+> 第一次用：直接看 [安装](#安装) 和 [第一次使用](#第一次使用)。
 
-## 5 分钟上手
+## 范围与分层
 
-Codecraft 有两种用法：**让 AI 按规范工作**（skill）和**在本地跑检查**（CLI）。先完成第 1、2 步就能用起来。
+| 项 | 内容 |
+|---|---|
+| 覆盖 | 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（推荐，多项目 / 团队）
+
+```bash
+npm i -D @ultime/codecraft skills-npm
+npx skills-npm setup
+```
+
+之后每次 `npm install` 都会把 `node_modules/@ultime/codecraft` 里的 skill 同步到 agent 目录：`.agents/skills/codecraft`，以及检测到的 Claude / Trae / Cursor 目录。需要 Node.js >= 22.20（`skills-npm` 的要求）。
+
+### 方式 B：Codecraft 自带安装器（单次，无额外依赖）
+
+```bash
+npx @ultime/codecraft install
+```
 
-### 第 1 步：把入口接到 agent
+自动检测当前项目的 agent，把 `SKILL.md`、`docs/`、`scenarios/`、`prompts/` 复制到 `.agents/skills/codecraft` 和对应 agent 目录（`.claude/skills`、`.trae/skills`、`.cursor/skills`）。
 
-Codecraft 不是装完 npm 包就自动出现在 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                 # 覆盖已有目录
+```
 
-**方式 A：指针式（推荐）**
+### 方式 C：手动指针
 
-在项目规则里留一行，让 agent 做代码任务时来读：
+不复制文件，只在项目规则里留一行：
 
-- Trae：项目 `.trae/rules/codecraft.md`
-- Claude：项目 `CLAUDE.md` 或 `~/.claude/CLAUDE.md`
-- 其他 agent：项目 `AGENTS.md`
+- Trae：`.trae/rules/codecraft.md`
+- Claude：`CLAUDE.md` 或 `~/.claude/CLAUDE.md`
+- 其他：`AGENTS.md`
 
 ```md
 代码任务先读 <Codecraft 路径>/codecraft/adapters/trae/SKILL.md
 ```
 
-平台对应的入口文件：
+平台入口：
 
 | 平台 | 入口文件 |
 |---|---|
@@ -49,11 +87,7 @@ Codecraft 不是装完 npm 包就自动出现在 agent 里。选一种方式接
 | Trae | [`adapters/trae/SKILL.md`](./adapters/trae/SKILL.md) |
 | Claude | [`adapters/claude/SKILL.md`](./adapters/claude/SKILL.md) |
 
-**方式 B：复制到 skills 目录**
-
-把对应平台的入口文件放进 agent 的 skills 目录。必须让 `docs/`、`scenarios/`、`prompts/` 与该文件保持 `../../` 的相对位置（符号链接即可），否则入口里的路径会失效。
-
-### 第 2 步：对 AI 说第一句话
+## 第一次使用
 
 ```text
 用 Codecraft 审计本项目，只读，不改文件。
@@ -63,18 +97,11 @@ Codecraft 不是装完 npm 包就自动出现在 agent 里。选一种方式接
 
 更多场景（只出报告、新项目、重构评审、架构设计、模式选型、脚手架、Design System）见 [docs/07-ai-prompts.md](./docs/07-ai-prompts.md)。
 
-### 第 3 步：需要本地检查时再装 CLI
+需要本地检查时再装 CLI：
 
 ```bash
 npx @ultime/codecraft check --root .
-npx @ultime/codecraft@latest check --root .
-```
-
-安装为项目依赖：
-
-```bash
-npm i -D @ultime/codecraft
-npx codecraft check --root .
+npx codecraft check --root .        # 已安装为项目依赖时
 ```
 
 本地开发 / 未发布时用 tarball：
@@ -85,8 +112,6 @@ npm i -D /path/to/ultime-codecraft-<version>.tgz
 npx codecraft check --root .
 ```
 
-也可以 `pnpm link --global /path/to/codecraft`，之后在任意目录使用 `codecraft`。
-
 ## 模式
 
 | 模式 | 是否改文件 | 对应命令 |
@@ -107,6 +132,7 @@ codecraft <command> [options]
 | `audit` | 内置规则 + `codecraft.config.json` 里的 gates，出只读报告 |
 | `plan` | 把 findings 转成只读升级计划；默认不跑 gates |
 | `init` | 生成 app / library 骨架；默认 dry-run |
+| `install` | 把 skill 安装到 agent skills 目录；默认写入，`--dry-run` 只看计划 |
 | `version` | 输出版本号 |
 
 ### 常用
@@ -121,6 +147,9 @@ codecraft audit --config codecraft.config.json --fail-fast
 codecraft plan --root . --with-gates
 codecraft init --root . --name demo              # dry-run
 codecraft init --root . --name demo --apply      # 写盘
+codecraft install                                # 自动检测并安装
+codecraft install --agent trae,claude --force
+codecraft install --dry-run
 ```
 
 ### 参数
@@ -138,13 +167,18 @@ codecraft init --root . --name demo --apply      # 写盘
 | `--with-gates` | — | 关 | `plan` 执行 gates |
 | `--name <name>` | 字符串 | — | `init` 的 app / package 名称；`--apply` 时必填 |
 | `--apply` | — | 关 | `init` 写盘；已存在路径跳过，不覆盖 |
+| `--agent <list>` | `auto` / `claude` / `trae` / `cursor` / `generic` | `auto` | `install` 目标，可逗号分隔 |
+| `--global` | — | 关 | `install` 写入用户目录 |
+| `--dest <path>` | 目录 | — | `install` 的显式目标 |
+| `--force` | — | 关 | `install` 覆盖已有 codecraft 目录 |
+| `--dry-run` | — | 关 | `install` 只输出计划，不写盘 |
 
 ### 退出码
 
 | 码 | 含义 |
 |---|---|
 | `0` | 通过；warning 不阻断 |
-| `1` | 有 error findings，或有 gate 失败 |
+| `1` | 有 error findings、install 失败，或有 gate 失败 |
 | `2` | 用法错误、root 不存在、配置非法 |
 
 ### 输出
@@ -161,7 +195,7 @@ codecraft init --root . --name demo --apply      # 写盘
 | `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`
@@ -181,12 +215,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)。
@@ -194,25 +238,41 @@ A4（单一收口）属于结构判断，由 review 与项目门禁负责，不
 ## 目录
 
 ```text
+SKILL.md      标准 agent skill 入口（skills-npm / install 使用）
 docs/         宪法、族卡、AI 契约、风格总图、模式、架构、AI 提示词、门禁
 scenarios/    新项目 / 旧项目审计 / 只出报告 / 重构评审
-adapters/     generic / Trae / Claude 入口
+adapters/     generic / Trae / Claude 手动指针
 prompts/      输出格式
-src/ + bin/   CLI
+src/ + bin/   CLI（含 install）
 tests/        node:test 用例
 templates/    init --apply 的 app / library 骨架
 evals/        golden tasks（人工回归）
+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`；不要直接删规则。
+- **`check` / `audit` / `plan` 有什么区别？** `check` 只跑内置规则；`audit` 额外跑 config 里的 gates；`plan` 只读，把 findings 转成计划，默认不跑 gates。
+- **为什么不自动跑 typecheck / test？** 门禁由项目提供，Codecraft 只编排，避免第二套实现。
+- **monorepo 为什么被判成 library？** 有 `packages/` 或根 `package.json` 即按 library；可用 `--pack` 显式覆盖。
+- **支持哪些文件？** 只扫 JS/TS 相关扩展名与 `package.json`；其它语言不覆盖。
 
 ## 边界
 
 - 静态检查是文本级：能覆盖高置信模式，可能漏报或误报；最终以项目门禁与 review 为准。
+- 机检只扫描 JS/TS 相关文件（`.ts` / `.tsx` / `.js` / `.jsx` / `.mjs` / `.cjs` / `.vue` / `.svelte`）与 `package.json`，其它语言不覆盖。
 - 不内置任何业务规则、框架约定或公司内部门禁。
 - 不读取、不上传代码；所有检查在本地完成。
 

package/SKILL.md

@@ -0,0 +1,67 @@
+---
+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).
+---
+
+# 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/06-architecture.md`
+4. 只读相关族卡：`docs/01-family-cards.md`（前端项目才读 Page / Component）
+5. 需要选型时：`docs/05-patterns.md`
+6. 选一个场景：`scenarios/`
+7. 按 `docs/02-ai-contract.md` 执行
+8. 按 `prompts/output.md` 输出
+9. 不知道怎么说时：`docs/07-ai-prompts.md`
+
+## 模式
+
+- **Audit（审计）**：只读，出报告。
+- **Plan（计划）**：只读，出架构 / 升级计划。
+- **Apply（执行）**：改代码 + 跑门禁。
+
+## 工作流
+
+1. 判定任务属于哪个场景。
+2. 只读相关族卡，不要一次加载全部。
+3. 先出计划；Apply 前确认范围。
+4. 跑项目验证命令；不能跑要说明原因。
+5. 按 `prompts/output.md` 输出。
+
+## 禁止
+
+- Audit / Plan 模式改文件。
+- 把业务逻辑放进 Transport 或 Page。
+- 内部代码 import `external/` 或生成类型。
+- 手改生成物。
+- 把前端族规则套到 Node 后端（Page / Component / UI 不适用）。
+- 写敏感信息；发现即停止、脱敏、提示轮换。
+- 安全红线登记例外。
+
+规则正文只在 `docs/`；本文件只做入口。

package/VERSION

@@ -1 +1 @@
-1.0.3
+1.2.0

package/adapters/README.md

@@ -9,4 +9,6 @@ Core 是 `docs/` + `scenarios/` + `scripts/`；adapters 只做入口，不复制
 
 规则：adapter 只写“读什么、按什么流程、输出什么”，规则正文留在 `docs/`。
 
+包根的 [`SKILL.md`](../SKILL.md) 是标准 agent skill 入口（`skills-npm` / `codecraft install` 使用）；本目录的平台文件用于手动指针接入。两者二选一，不要同时维护两套正文。
+
 使用者提示词（怎么对 AI 说）：[`../docs/07-ai-prompts.md`](../docs/07-ai-prompts.md)。

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 节「变的」，其余是判据与代价。
 
 ## 一句话