@gong-ym/ai-spec-auto 0.2.3

package/.agents/rules/common/15-visual-gate-wait.md

@@ -0,0 +1,90 @@
+# 15 — Visual 门禁等待规范（ai-spec-auto / 所有 profile 共用）
+
+> 目的：当 `/spec-start` 或其他协议推进命中门禁（`status=waiting-approval`）时，
+> 让 IDE 中的 AI **在原对话里主动轮询** `.ai-spec/gate-signal.json`，实现
+> "Visual 页面点批准 → 原对话自动继续"的无人值守体验。
+>
+> 本规则为强制切面规则（优先级高于默认等待行为），但允许项目级 `.cursor/rules/overrides/*`
+> 调整轮询参数。所有 IO 失败必须静默降级，绝不阻断主协议推进。
+
+## 15.1 触发条件（必须）
+
+同时满足以下两项时，AI **必须立即进入** "visual 门禁等待循环"，而不是挂起询问用户：
+
+1. `.ai-spec/current-run.json` 中 `status === "waiting-approval"` 且 `pending_gate` 非空
+2. `.ai-spec/visual-bridge.json` 存在且 `enabled !== false`
+
+若 visual-bridge 未启用或不存在，视为"纯本地模式"，按原有人工确认流程处理，**不** 进入本循环。
+
+## 15.2 循环算法（每轮 3 秒，最多 20 轮 = 60 秒）
+
+```text
+waitStartedAt := Date.now()
+currentRunId  := current-run.json.run_id
+currentGate   := current-run.json.pending_gate
+
+for i in 1..20:
+    sleep 3s
+    在对话输出一行："[T+{i*3}s] 等待 Visual 审批（run=<runId> gate=<gate>）..."
+    try:
+        signal := read JSON from .ai-spec/gate-signal.json
+    catch any:
+        signal := null   # 文件不存在 / JSON 损坏 → 继续等
+
+    if signal 满足以下全部条件:
+        - signal.schema_version === 1
+        - signal.run_id === currentRunId
+        - signal.gate === currentGate
+        - signal.ts_ms > waitStartedAt
+    then:
+        if signal.decision in ("approved", "resumed"):
+            汇报"已收到 Visual 审批：<decision>，继续执行 /spec-continue"
+            执行 /spec-continue
+            return
+        if signal.decision === "rejected":
+            汇报"Visual 审批被拒绝：<signal.reason>，停止本轮推进。"
+            return
+
+# 60 秒仍无信号 → 默认自动放行
+汇报"60 秒内未收到 Visual 审批决定，按默认策略自动放行，继续执行 /spec-continue"
+执行 /spec-continue
+```
+
+> 陈旧信号防误触：`signal.ts_ms > waitStartedAt` 的校验能自动忽略上一轮遗留的 gate-signal.json。
+> 这是本规则的关键幂等保证，不得省略。
+
+## 15.3 AI 行为契约（必须遵守）
+
+- **不许** 在循环期间询问用户"要不要继续"。循环本身就是等待机制。
+- **不许** 读到任意 gate-signal 就直接 `/spec-continue`，必须通过 15.2 的四项校验。
+- **不许** 跳过 60 秒超时（除非项目级 override 显式设置 `visualGateWait.timeoutMs`）。
+- **必须** 每轮输出一行进度，保证原对话可见。
+- **必须** 整个循环用户仍可随时打断（Ctrl+C / 发送新消息），打断后视为人工接管，本规则不再自动推进。
+
+## 15.4 异常兜底
+
+| 情况 | 处理 |
+|---|---|
+| `current-run.json` 读失败 | 退回人工询问（本规则不适用） |
+| `gate-signal.json` JSON 损坏 | 当次视为"无信号"，继续等 |
+| `.ai-spec/` 目录不存在 | 退回人工询问 |
+| 循环中抛出任何异常 | 捕获后汇报错误 + 继续下一轮；连续 3 次异常 → 按超时路径默认放行 |
+
+## 15.5 与既有资产的关系
+
+- 本规则与 `.ai-spec/next-step.md`（由 `inbox-consumer.js` 追加写入）互为双通道：
+  `next-step.md` 提供人类可读的审批历史；`gate-signal.json` 提供机器可判定的即时信号。
+  **AI 推进决策以 `gate-signal.json` 为准**，`next-step.md` 仅作审计参考。
+- 不改变、不覆盖、不依赖 Cursor hook / Claude Code hook 能力；仅依赖文件系统读取。
+- 与 `cli.js visual watch` 守护解耦：watch 负责把 Visual 侧 outbox 应用到本地并写 gate-signal，
+  AI 负责读取并决策；两者独立失败独立恢复。
+
+## 15.6 项目级覆盖（可选）
+
+业务仓可在 `.cursor/rules/overrides/visual-gate-wait.md` 声明以下参数覆盖默认值：
+
+- `intervalMs`（默认 3000）
+- `maxAttempts`（默认 20）
+- `defaultOnTimeout`（`"continue"` | `"pause"`，默认 `"continue"`）
+
+当 `defaultOnTimeout === "pause"` 时，超时后 AI 退回人工询问；否则按默认放行。

package/.agents/rules/profiles/nestjs/01-/351/241/271/347/233/256/346/246/202/350/277/260.md

@@ -0,0 +1,27 @@
+---
+alwaysApply: false
+description: NestJS 项目概述，描述项目定位、技术栈、模块结构与核心依赖。当了解项目背景或进行整体规划时读取此规则。
+---
+
+# 项目概述（NestJS）
+
+> 本文件由 `project-init` 技能根据仓库实际情况生成，请勿手动覆盖自动生成的内容。
+
+## 项目定位
+
+<!-- 由 project-init 填写：项目名称、业务背景、核心功能定位 -->
+
+## 技术栈
+
+- 运行时：Node.js
+- 框架：NestJS
+- 语言：TypeScript
+- 构建：nest build / tsc
+
+## 核心模块
+
+<!-- 由 project-init 填写：主要 Module 列表及职责 -->
+
+## 主要依赖
+
+<!-- 由 project-init 根据 package.json 填写 -->

package/.agents/rules/profiles/nestjs/03-/351/241/271/347/233/256/347/273/223/346/236/204.md

@@ -0,0 +1,20 @@
+---
+alwaysApply: false
+description: NestJS 项目目录结构规范，描述 src/ 模块组织、目录约定与文件命名规则。当新建模块、文件或理解项目结构时读取此规则。
+---
+
+# 项目结构（NestJS）
+
+> 本文件由 `project-init` 技能根据仓库实际情况生成，请勿手动覆盖自动生成的内容。
+
+## 顶层目录
+
+<!-- 由 project-init 填写：根目录的主要目录及说明 -->
+
+## src/ 结构
+
+<!-- 由 project-init 填写：模块目录、通用目录（common/guards/filters/interceptors等）结构 -->
+
+## 文件命名约定
+
+<!-- 由 project-init 根据现有代码归纳：*.module.ts / *.controller.ts / *.service.ts / *.dto.ts 等 -->

package/.agents/rules/profiles/nestjs/04-/346/250/241/345/235/227/347/273/223/346/236/204/350/247/204/350/214/203.md

@@ -0,0 +1,24 @@
+---
+alwaysApply: false
+description: NestJS 模块结构规范，约定 Module/Controller/Service/Provider 的职责边界、依赖注入方式与目录布局。当新建或重构模块时读取此规则。
+---
+
+# 模块结构规范（NestJS）
+
+> 本文件由 `project-init` 技能根据仓库实际代码生成，请勿手动覆盖自动生成的内容。
+
+## Module 组织原则
+
+<!-- 由 project-init 填写：功能模块划分、全局模块、共享模块规范 -->
+
+## Controller 规范
+
+<!-- 由 project-init 填写：路由前缀、参数装饰器、响应格式约定 -->
+
+## Service 规范
+
+<!-- 由 project-init 填写：业务逻辑层职责、不允许直接操作数据库等约定 -->
+
+## DTO 与 Validation
+
+<!-- 由 project-init 填写：class-validator 用法、DTO 命名约定 -->

package/.agents/rules/profiles/nestjs/05-/346/216/245/345/217/243/344/270/216/345/245/221/347/272/246/350/247/204/350/214/203.md

@@ -0,0 +1,24 @@
+---
+alwaysApply: false
+description: NestJS 接口与契约规范，约定 HTTP 方法、路由命名、请求/响应结构、版本管理与 Swagger 文档规范。当新建或修改接口时读取此规则。
+---
+
+# 接口与契约规范（NestJS）
+
+> 本文件由 `project-init` 技能根据仓库实际代码生成，请勿手动覆盖自动生成的内容。
+
+## 路由命名约定
+
+<!-- 由 project-init 填写：RESTful 风格、路由前缀、版本号规范 -->
+
+## 请求/响应结构
+
+<!-- 由 project-init 填写：统一响应体格式（code/message/data）、分页结构等 -->
+
+## 错误码规范
+
+<!-- 由 project-init 填写：业务错误码、HTTP 状态码映射 -->
+
+## Swagger 文档
+
+<!-- 由 project-init 填写：@ApiTags/@ApiOperation 使用约定，是否必须注释 -->

package/.agents/rules/profiles/nestjs/06-/346/225/260/346/215/256/350/256/277/351/227/256/350/247/204/350/214/203.md

@@ -0,0 +1,24 @@
+---
+alwaysApply: false
+description: NestJS 数据访问规范，约定 ORM/数据库客户端选型、Repository 层职责、事务处理与查询优化原则。当涉及数据库操作时读取此规则。
+---
+
+# 数据访问规范（NestJS）
+
+> 本文件由 `project-init` 技能根据仓库实际代码生成，请勿手动覆盖自动生成的内容。
+
+## ORM/数据库选型
+
+<!-- 由 project-init 填写：TypeORM / Prisma / Mongoose 等，版本与配置位置 -->
+
+## Repository 模式
+
+<!-- 由 project-init 填写：自定义 Repository、是否使用 @InjectRepository、禁止在 Controller 直接操作 DB -->
+
+## 事务处理
+
+<!-- 由 project-init 填写：事务装饰器或手动事务用法 -->
+
+## 查询规范
+
+<!-- 由 project-init 填写：禁止 SELECT *、N+1 处理、软删除约定 -->

package/.agents/rules/profiles/nestjs/07-/351/205/215/347/275/256/344/270/216/350/277/220/350/241/214/346/227/266/350/247/204/350/214/203.md

@@ -0,0 +1,20 @@
+---
+alwaysApply: false
+description: NestJS 配置与运行时规范，约定环境变量管理、ConfigModule 用法、启动参数与跨环境配置策略。当涉及配置项或环境变量时读取此规则。
+---
+
+# 配置与运行时规范（NestJS）
+
+> 本文件由 `project-init` 技能根据仓库实际代码生成，请勿手动覆盖自动生成的内容。
+
+## 环境变量管理
+
+<!-- 由 project-init 填写：.env 文件约定、ConfigModule 配置、@nestjs/config 用法 -->
+
+## 运行时端口与启动参数
+
+<!-- 由 project-init 填写：端口配置位置、跨环境变量（dev/test/prod）切换方式 -->
+
+## 密钥与敏感配置
+
+<!-- 由 project-init 填写：禁止硬编码、密钥注入方式 -->

package/.agents/rules/profiles/nestjs/09-/345/274/202/345/270/270/344/270/216/346/227/245/345/277/227/350/247/204/350/214/203.md

@@ -0,0 +1,20 @@
+---
+alwaysApply: false
+description: NestJS 异常与日志规范，约定全局异常过滤器、业务异常类型、日志级别与结构化日志输出方式。当编写错误处理或日志相关代码时读取此规则。
+---
+
+# 异常与日志规范（NestJS）
+
+> 本文件由 `project-init` 技能根据仓库实际代码生成，请勿手动覆盖自动生成的内容。
+
+## 全局异常过滤器
+
+<!-- 由 project-init 填写：HttpExceptionFilter 实现位置、是否统一包装错误响应 -->
+
+## 业务异常类型
+
+<!-- 由 project-init 填写：自定义 BusinessException、错误码枚举 -->
+
+## 日志规范
+
+<!-- 由 project-init 填写：Logger 注入方式、日志级别约定、结构化日志字段（traceId 等） -->

package/.agents/rules/profiles/nestjs/11-/346/265/213/350/257/225/350/247/204/350/214/203.md

@@ -0,0 +1,24 @@
+---
+alwaysApply: false
+description: NestJS 测试规范，约定单元测试、e2e 测试的组织方式、Mock 策略与覆盖率要求。当编写或审查测试时读取此规则。
+---
+
+# 测试规范（NestJS）
+
+> 本文件由 `project-init` 技能根据仓库实际代码生成，请勿手动覆盖自动生成的内容。
+
+## 测试框架
+
+<!-- 由 project-init 填写：Jest 配置位置、测试脚本命令 -->
+
+## 单元测试规范
+
+<!-- 由 project-init 填写：*.spec.ts 命名约定、TestingModule 初始化、Mock 策略 -->
+
+## e2e 测试规范
+
+<!-- 由 project-init 填写：test/ 目录结构、supertest 用法、测试数据库策略 -->
+
+## 覆盖率要求
+
+<!-- 由 project-init 填写：覆盖率阈值、需覆盖的核心模块范围 -->

package/.agents/rules/profiles/nestjs/13-/344/273/243/347/240/201/346/240/274/345/274/217/345/214/226/344/270/216/346/243/200/346/237/245.md

@@ -0,0 +1,20 @@
+---
+alwaysApply: false
+description: NestJS 代码格式化与检查规范，约定 ESLint/Prettier 配置位置、规则集与提交前检查流程。当配置或运行代码检查时读取此规则。
+---
+
+# 代码格式化与检查（NestJS）
+
+> 本文件由 `project-init` 技能根据仓库实际代码生成，请勿手动覆盖自动生成的内容。
+
+## ESLint 配置
+
+<!-- 由 project-init 填写：配置文件位置、使用的规则集（@typescript-eslint 等）、关键自定义规则 -->
+
+## Prettier 配置
+
+<!-- 由 project-init 填写：配置文件位置、主要格式选项 -->
+
+## 提交前检查
+
+<!-- 由 project-init 填写：lint-staged 配置、husky hooks、CI lint 步骤 -->

package/.agents/rules/profiles/node-tooling/01-/351/241/271/347/233/256/346/246/202/350/277/260.md

@@ -0,0 +1,30 @@
+---
+alwaysApply: false
+description: Node.js 工具仓项目概述，描述项目定位、技术栈、主要模块与运行入口。当了解项目背景或进行整体规划时读取此规则。
+---
+
+# 项目概述（Node.js Tooling）
+
+> 本文件由 `project-init` 技能根据仓库实际情况生成，请勿手动覆盖自动生成的内容。
+
+## 项目定位
+
+<!-- 描述项目的工具定位：CLI 工具 / Worker / 编排运行时 / Contract 验证工具 等 -->
+
+## 技术栈
+
+| 层次 | 技术 |
+|------|------|
+| 运行时 | Node.js（版本见 `.nvmrc` 或 `engines` 字段） |
+| 语言 | TypeScript / JavaScript |
+| 包管理 | npm / pnpm / yarn（项目统一约定） |
+| 测试框架 | Vitest / Jest |
+| Schema 校验 | Zod / Ajv / io-ts（按需） |
+
+## 主要模块
+
+<!-- 描述仓库内的主要模块/子包结构 -->
+
+## 运行入口
+
+<!-- 描述 CLI 入口、worker 入口、主模块导出等 -->

package/.agents/rules/profiles/node-tooling/03-/351/241/271/347/233/256/347/273/223/346/236/204.md

@@ -0,0 +1,37 @@
+---
+alwaysApply: false
+description: Node.js 工具仓项目结构规范，包括目录组织、模块边界约定与主要入口文件规则。当新建模块或文件时读取此规则。
+---
+
+# 项目结构（Node.js Tooling）
+
+> 本文件由 `project-init` 技能根据仓库实际情况生成，请勿手动覆盖自动生成的内容。
+
+## 典型目录结构
+
+```text
+<root>/
+├── src/
+│   ├── cli/           # CLI 命令定义与入口
+│   ├── commands/      # 各子命令实现
+│   ├── contracts/     # Contract / Schema 定义
+│   ├── workers/       # Worker 任务实现
+│   ├── runtime/       # 运行时核心逻辑
+│   ├── utils/         # 通用工具函数
+│   └── types/         # TypeScript 类型定义
+├── tests/             # 测试文件
+├── scripts/           # 构建、发布等脚本
+├── package.json
+└── tsconfig.json
+```
+
+## 模块边界约定
+
+- 每个模块（`cli/`、`workers/`、`contracts/` 等）对外只导出必要接口
+- 模块内部实现不应被外部直接引用
+- 禁止循环依赖
+
+## 入口文件规则
+
+- CLI 入口在 `src/cli/index.ts`（或 `bin/` 下）
+- 库入口在 `src/index.ts`，并在 `package.json` 中声明 `main` / `exports`

package/.agents/rules/profiles/node-tooling/04-CLI/344/270/216/346/250/241/345/235/227/350/247/204/350/214/203.md

@@ -0,0 +1,42 @@
+---
+alwaysApply: false
+description: Node.js 工具仓的 CLI 与模块规范，包括命令定义方式、参数约定、模块导出规则。当新增 CLI 命令或模块时读取此规则。
+---
+
+# CLI 与模块规范（Node.js Tooling）
+
+## CLI 命令设计
+
+- 使用团队约定的 CLI 框架（如 `commander`、`yargs`、`meow`）
+- 每个子命令对应独立文件，命令描述必须清晰
+- 命令参数使用 `--kebab-case` 风格
+- 所有命令必须提供 `--help` 说明
+
+```typescript
+// 示例：commander 风格
+program
+  .command('run <task>')
+  .description('执行指定任务')
+  .option('--dry-run', '仅预览，不实际执行')
+  .action(async (task, options) => {
+    await runTask(task, options);
+  });
+```
+
+## 模块导出规则（NON-NEGOTIABLE）
+
+- 每个模块在 `index.ts` 中统一导出公共接口
+- 内部实现文件不应从模块外直接引用
+- 导出的函数和类必须有明确的 TypeScript 类型签名
+- 发布到 npm 的包必须在 `package.json` 中声明 `exports` 字段
+
+## 异步处理
+
+- 优先使用 `async/await`，避免 callback 嵌套
+- 所有异步操作必须处理错误（try/catch 或 `.catch()`）
+- 长时间运行的操作需提供超时机制
+
+## 进程管理
+
+- 正常退出使用 `process.exit(0)`，错误退出使用 `process.exit(1)`
+- 监听 `SIGINT`、`SIGTERM` 信号，进行优雅退出处理

package/.agents/rules/profiles/node-tooling/05-Contract/344/270/216Schema/350/247/204/350/214/203.md

@@ -0,0 +1,42 @@
+---
+alwaysApply: false
+description: Node.js 工具仓的 Contract 与 Schema 规范，包括 Schema 定义方式、Contract 校验策略与类型导出约定。当新增或修改 Contract / Schema 时读取此规则。
+---
+
+# Contract 与 Schema 规范（Node.js Tooling）
+
+## Schema 定义
+
+- 统一使用项目约定的 Schema 库（Zod / Ajv / io-ts）定义数据结构
+- Schema 文件放在 `src/contracts/` 或 `src/schemas/` 目录
+- 每个 Schema 对应独立文件，按业务领域命名
+
+```typescript
+// 示例：Zod Schema
+import { z } from 'zod';
+
+export const TaskPayloadSchema = z.object({
+  taskId: z.string().uuid(),
+  type: z.enum(['build', 'deploy', 'test']),
+  params: z.record(z.unknown()),
+});
+
+export type TaskPayload = z.infer<typeof TaskPayloadSchema>;
+```
+
+## Contract 校验策略（NON-NEGOTIABLE）
+
+- 所有外部输入（CLI 参数、API 响应、消息队列消息、文件内容）在入口处必须校验
+- 校验失败必须给出明确的错误信息（字段路径 + 错误原因）
+- 禁止使用 `as any` 绕过类型校验
+
+## 类型导出约定
+
+- Schema 推导出的 TypeScript 类型必须一并导出（`export type`）
+- 类型名称与 Schema 名称保持对应（`TaskPayloadSchema` → `TaskPayload`）
+- 禁止手动维护与 Schema 重复的类型定义
+
+## 版本兼容性
+
+- Contract 发生破坏性变更时，需同步更新版本号并提供迁移说明
+- 向前兼容的变更（新增可选字段）无需升级大版本

package/.agents/rules/profiles/node-tooling/06-/350/277/220/350/241/214/346/227/266/346/226/207/344/273/266/350/247/204/350/214/203.md

@@ -0,0 +1,30 @@
+---
+alwaysApply: false
+description: Node.js 工具仓的运行时文件规范，包括工作目录管理、临时文件约定、状态文件读写策略。当涉及文件系统操作时读取此规则。
+---
+
+# 运行时文件规范（Node.js Tooling）
+
+## 工作目录管理
+
+- 使用 `process.cwd()` 获取当前工作目录，禁止使用 `__dirname` 做运行时路径拼接（ESM 模块下不可用）
+- ESM 环境下使用 `new URL(import.meta.url)` 获取当前文件路径
+- 跨平台路径拼接统一使用 `node:path` 的 `join` / `resolve`
+
+## 临时文件约定
+
+- 临时文件写入系统临时目录（`os.tmpdir()`）或项目约定的 `.tmp/` 目录
+- 临时目录加入 `.gitignore`
+- 程序异常退出时，应通过 `process.on('exit')` 或 `finally` 块清理临时文件
+
+## 状态文件读写
+
+- 运行时状态文件（锁文件、任务状态、中间产物）统一放在项目约定目录（如 `.run/`、`.state/`）
+- 读写状态文件前检查权限，写失败需给出明确错误提示
+- 状态文件格式统一使用 JSON，禁止使用自定义二进制格式
+
+## 文件监听
+
+- 使用 `node:fs/promises` 或 `chokidar` 进行文件监听
+- 监听器必须在程序退出时显式关闭，防止进程无法退出
+- 大量文件监听需评估系统 `inotify` 上限

package/.agents/rules/profiles/node-tooling/07-/346/227/245/345/277/227/344/270/216/351/224/231/350/257/257/345/244/204/347/220/206/350/247/204/350/214/203.md

@@ -0,0 +1,60 @@
+---
+alwaysApply: false
+description: Node.js 工具仓的日志与错误处理规范，包括日志工具选型、结构化日志约定、错误类型定义与进程崩溃处理。当编写日志或错误处理代码时读取此规则。
+---
+
+# 日志与错误处理规范（Node.js Tooling）
+
+## 日志工具
+
+- 统一使用项目约定的日志库（如 `pino`、`winston`、`consola`）
+- 禁止直接使用 `console.log` 在生产逻辑中输出日志
+- 开发模式下允许彩色格式化输出，生产模式使用结构化 JSON 日志
+
+## 日志级别
+
+| 级别 | 使用场景 |
+|------|----------|
+| error | 不可恢复错误、进程崩溃 |
+| warn | 可恢复的异常、降级处理 |
+| info | 关键操作节点（任务开始/结束、关键状态变化） |
+| debug | 调试信息，生产关闭 |
+
+## 结构化日志字段
+
+关键操作日志应包含：
+
+```json
+{
+  "level": "info",
+  "time": "ISO-8601",
+  "taskId": "xxx",
+  "event": "task.completed",
+  "duration": 1234,
+  "result": "success"
+}
+```
+
+## 错误类型定义
+
+- 定义统一的错误基类（如 `ToolingError`）
+- 不同场景使用有语义的子类（如 `ValidationError`、`ContractMismatchError`、`TimeoutError`）
+- 禁止直接抛出 `new Error('some message')`，必须使用有类型的错误类
+
+```typescript
+export class ValidationError extends Error {
+  constructor(
+    message: string,
+    public readonly field?: string
+  ) {
+    super(message);
+    this.name = 'ValidationError';
+  }
+}
+```
+
+## 全局错误处理（NON-NEGOTIABLE）
+
+- 监听 `process.on('uncaughtException')` 和 `process.on('unhandledRejection')`，记录错误后以非零退出码退出
+- Promise 链中的 rejection 不允许静默忽略
+- async 函数中的错误必须在调用处捕获或向上传递

package/.agents/rules/profiles/node-tooling/09-/350/204/232/346/234/254/344/270/216/345/205/245/345/217/243/350/247/204/350/214/203.md

@@ -0,0 +1,45 @@
+---
+alwaysApply: false
+description: Node.js 工具仓的脚本与入口规范，包括 package.json scripts 约定、bin 入口配置、构建产物结构与发布规则。当新增脚本入口或准备发布时读取此规则。
+---
+
+# 脚本与入口规范（Node.js Tooling）
+
+## package.json scripts 约定
+
+| 脚本 | 职责 |
+|------|------|
+| `start` | 启动主程序（生产模式） |
+| `dev` | 开发模式（watch + ts-node / tsx） |
+| `build` | 编译 TypeScript 到 `dist/` |
+| `test` | 运行所有测试 |
+| `test:watch` | 监听模式运行测试 |
+| `lint` | 执行 ESLint 检查 |
+| `format` | 执行 Prettier 格式化 |
+| `typecheck` | 执行 `tsc --noEmit` 类型检查 |
+
+## bin 入口配置
+
+- CLI 工具在 `package.json` 中声明 `bin` 字段
+- 入口文件首行必须包含 shebang：`#!/usr/bin/env node`
+- bin 文件需设置可执行权限（`chmod +x`）
+
+```json
+{
+  "bin": {
+    "my-tool": "./dist/cli/index.js"
+  }
+}
+```
+
+## 构建产物结构
+
+- TypeScript 编译产物输出到 `dist/`，源码不直接发布
+- `package.json` 的 `main` / `exports` 指向 `dist/` 内文件
+- 确保 `.d.ts` 类型文件随产物一同输出（`declaration: true`）
+
+## 发布规则
+
+- 发布前必须执行 `typecheck`、`lint` 和 `test`，全部通过才能发布
+- 使用语义化版本（SemVer）：破坏性变更升大版本，新功能升小版本，修复升补丁版本
+- 在 `package.json` 的 `files` 字段中明确声明发布内容，禁止发布源码目录（`src/`）

package/.agents/rules/profiles/node-tooling/11-/346/265/213/350/257/225/350/247/204/350/214/203.md

@@ -0,0 +1,41 @@
+---
+alwaysApply: false
+description: Node.js 工具仓的测试规范，包括测试框架（Vitest / Jest）、测试文件约定、Mock 策略与质量门禁。当编写测试或评审测试代码时读取此规则。
+---
+
+# 测试规范（Node.js Tooling）
+
+## 测试框架
+
+- 统一使用 **Vitest**（推荐）或 **Jest** 作为测试运行器
+- 类型检查：测试文件同样经过 TypeScript 编译，禁止 `@ts-ignore` 绕过类型问题
+
+## 测试文件约定
+
+| 项目 | 约定 |
+|------|------|
+| 文件位置 | 与源文件同目录 或 `tests/` 目录下 |
+| 文件命名 | `<name>.test.ts` / `<name>.spec.ts` |
+| 集成测试 | `<name>.integration.test.ts` |
+| 测试配置 | 项目根目录 `vitest.config.ts` 或 `jest.config.ts` |
+
+## Mock 策略
+
+- 使用 `vi.mock()` / `jest.mock()` Mock 外部模块（文件系统、网络请求、子进程等）
+- 不 Mock 被测模块内部实现
+- 临时文件操作测试中使用 `os.tmpdir()` + 随机子目录，测试后清理
+
+## 测试范围
+
+| 层次 | 说明 | 要求 |
+|------|------|------|
+| 必须测试 | 工具函数、Contract 校验、CLI 命令逻辑、Worker 任务处理 | 新增时必须附带测试 |
+| 建议测试 | CLI 参数解析、文件 I/O 流程 | 核心路径推荐覆盖 |
+| 集成测试 | 端到端执行流程 | 按需添加，标记 `integration` |
+
+## 质量门禁（NON-NEGOTIABLE）
+
+- 必须通过 **`tsc --noEmit`** 类型检查
+- 所有项目必须通过 **ESLint 检查**（零 error）
+- 新增工具函数、Contract 校验逻辑必须附带测试用例
+- 测试必须能独立运行，不依赖特定环境或执行顺序