add-coder 0.3.16 → 0.3.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "add-coder",
-  "version": "0.3.16",
+  "version": "0.3.19",
   "private": false,
   "description": "[codein2027](https://github.com/xiaomingming92/codein2027) - A complete scaffolding for building the ADD programming paradigm, the implementation layer for AI code governance. Core principle: Audit as Infrastructure. Breaks the black-box programming process and cross-session amnesia, evolving programming paradigms into an auditable, traceable, and convergent new era. npx-ready.\n\n[codein2027](https://github.com/xiaomingming92/codein2027) 快速构建 ADD 编程范式的完整脚手架——AI 代码治理的落地方案。以「审计即基础设施」为核心，彻底打破编程过程黑盒与跨轮失忆，让编程范式进化为可审计、可追溯、可收敛的新时代。npx 即用，人人可体验。",
   "repository": {

package/templates/.add-coder-src-hash.json

@@ -1,5 +1,5 @@
 {
-  "_version": "0.3.16",
+  "_version": "0.3.19",
   "adapters/claude/hooks/doc-format-guard.sh": "ec59ad3f",
   "adapters/claude/hooks/lib/common.sh": "4f3e64ad",
   "adapters/claude/hooks/lib/context-inject.sh": "cfc8c65e",
@@ -15,7 +15,7 @@
   "adapters/claude/hooks/post-tool-failure.sh": "669b1b65",
   "adapters/claude/hooks/post-tool-use.sh": "f54dd009",
   "adapters/claude/hooks/pre-compact.sh": "4248f84f",
-  "adapters/claude/hooks/pre-tool-use.sh": "e186abc8",
+  "adapters/claude/hooks/pre-tool-use.sh": "080f8979",
   "adapters/claude/hooks/prompt-submit.sh": "2fe9e42c",
   "adapters/claude/hooks/review-checklist.sh": "b383a983",
   "adapters/claude/hooks/session-end.sh": "777ae808",
@@ -40,7 +40,7 @@
   "adapters/codex/hooks/post-tool-failure.sh": "669b1b65",
   "adapters/codex/hooks/post-tool-use.sh": "27123aee",
   "adapters/codex/hooks/pre-compact.sh": "6164c007",
-  "adapters/codex/hooks/pre-tool-use.sh": "8f6b77a0",
+  "adapters/codex/hooks/pre-tool-use.sh": "797664b8",
   "adapters/codex/hooks/prompt-submit.sh": "a41371ea",
   "adapters/codex/hooks/review-checklist.sh": "b383a983",
   "adapters/codex/hooks/session-end.sh": "3cc8c346",
@@ -64,7 +64,7 @@
   "adapters/qoder/hooks/post-tool-failure.sh": "8bc7a0e4",
   "adapters/qoder/hooks/post-tool-use.sh": "051cb6ed",
   "adapters/qoder/hooks/pre-compact.sh": "092fa6cf",
-  "adapters/qoder/hooks/pre-tool-use.sh": "ade1adf0",
+  "adapters/qoder/hooks/pre-tool-use.sh": "565cff92",
   "adapters/qoder/hooks/prompt-submit.sh": "336f262e",
   "adapters/qoder/hooks/review-checklist.sh": "666831c8",
   "adapters/qoder/hooks/session-end.sh": "c50339df",
@@ -89,7 +89,7 @@
   "adapters/trae/hooks/post-tool-failure.sh": "669b1b65",
   "adapters/trae/hooks/post-tool-use.sh": "27123aee",
   "adapters/trae/hooks/pre-compact.sh": "6164c007",
-  "adapters/trae/hooks/pre-tool-use.sh": "63151fb0",
+  "adapters/trae/hooks/pre-tool-use.sh": "2d7fc7a7",
   "adapters/trae/hooks/prompt-submit.sh": "a41371ea",
   "adapters/trae/hooks/review-checklist.sh": "b383a983",
   "adapters/trae/hooks/session-end.sh": "3cc8c346",
@@ -124,7 +124,7 @@
   "adapters/vscode/hooks/post-tool-failure.sh": "355cfab1",
   "adapters/vscode/hooks/post-tool-use.sh": "5f188718",
   "adapters/vscode/hooks/pre-compact.sh": "a0908f0e",
-  "adapters/vscode/hooks/pre-tool-use.sh": "705953bf",
+  "adapters/vscode/hooks/pre-tool-use.sh": "4bf878e7",
   "adapters/vscode/hooks/prompt-submit.sh": "3e56d1a9",
   "adapters/vscode/hooks/review-checklist.sh": "b383a983",
   "adapters/vscode/hooks/session-end.sh": "7b407b9f",
@@ -155,7 +155,7 @@
   "core/hooks/post-tool-failure.sh": "669b1b65",
   "core/hooks/post-tool-use.sh": "27123aee",
   "core/hooks/pre-compact.sh": "6164c007",
-  "core/hooks/pre-tool-use.sh": "60bcf63a",
+  "core/hooks/pre-tool-use.sh": "f967ab24",
   "core/hooks/prompt-submit.sh": "a41371ea",
   "core/hooks/review-checklist.sh": "b383a983",
   "core/hooks/session-end.sh": "3cc8c346",
@@ -166,7 +166,7 @@
   "core/plans/2026-07/08/add-coder-npm-package-add-route-v1.md": "b05fce99",
   "core/plans/2026-07/08/add-coder-npm-package-handoff-v1.md": "1bd40a4a",
   "core/plans/2026-07/08/add-coder-npm-package-plan-v1.md": "a678d98e",
-  "core/prisma/add.prisma": "fa818acf",
+  "core/prisma/add.prisma": "037bd7e9",
   "core/reports/REPORT-WORKFLOW.md": "03d39b21",
   "core/reports/boundary-runtime-report.md": "6fd8053f",
   "core/reports/code-review-combined-report.md": "195d52aa",
@@ -175,7 +175,10 @@
   "core/reports/index.md": "6348c374",
   "core/reports/runtime-report/gateway.md": "a5751665",
   "core/reviews/.gitkeep": "e3b0c442",
-  "core/rules/project_rules.md": "fea8bfaa",
+  "core/rules/profiles/index.toml": "b83332d4",
+  "core/rules/profiles/machineserver-profile.md": "8a36cf39",
+  "core/rules/profiles/webapp-profile.md": "e493ae7b",
+  "core/rules/project_rules.md": "82b25e08",
   "core/rules/theory-practice-map.toml": "b1db99fd",
   "core/scripts/db-ensure.sh": "faeb6b92",
   "core/scripts/gen-plan-index.sh": "bfc6ad3e",
@@ -203,23 +206,25 @@
   "core/scripts/mcp-server/tasks/index.ts": "c040eb75",
   "core/scripts/mcp-server/tasks/runner.ts": "d84bd35d",
   "core/scripts/mcp-server/tasks/store.ts": "2fce1a92",
-  "core/scripts/mcp-server/tools/audit.ts": "3c23458b",
-  "core/scripts/mcp-server/tools/context.ts": "5a00457b",
-  "core/scripts/mcp-server/tools/docs.ts": "a3937aec",
-  "core/scripts/mcp-server/tools/gateway/check_add_route_completeness.ts": "c205989d",
-  "core/scripts/mcp-server/tools/gateway/check_add_route_status.ts": "3662b6dc",
-  "core/scripts/mcp-server/tools/gateway/check_dps.ts": "cea4cb8b",
-  "core/scripts/mcp-server/tools/gateway/check_rahs.ts": "c37f6810",
-  "core/scripts/mcp-server/tools/gateway/check_spec_sync.ts": "a683697f",
+  "core/scripts/mcp-server/tools/audit.ts": "71a38969",
+  "core/scripts/mcp-server/tools/context.ts": "9ce21255",
+  "core/scripts/mcp-server/tools/contract.ts": "c894e64a",
+  "core/scripts/mcp-server/tools/docs.ts": "034e473c",
+  "core/scripts/mcp-server/tools/gateway/check_add_route_completeness.ts": "b58e76ee",
+  "core/scripts/mcp-server/tools/gateway/check_add_route_status.ts": "23fbbb6b",
+  "core/scripts/mcp-server/tools/gateway/check_dps.ts": "0f0bedd8",
+  "core/scripts/mcp-server/tools/gateway/check_rahs.ts": "fe210727",
+  "core/scripts/mcp-server/tools/gateway/check_spec_sync.ts": "89c2338b",
   "core/scripts/mcp-server/tools/gateway/helpers.ts": "690d7891",
-  "core/scripts/mcp-server/tools/gateway/index.ts": "5a9fd5ed",
+  "core/scripts/mcp-server/tools/gateway/index.ts": "559acb75",
   "core/scripts/mcp-server/tools/gateway.backup": "65eae393",
-  "core/scripts/mcp-server/tools/hitl.ts": "80093743",
-  "core/scripts/mcp-server/tools/hook-event-report.ts": "3926005b",
-  "core/scripts/mcp-server/tools/index.ts": "b15c6753",
-  "core/scripts/mcp-server/tools/plan.ts": "2f83b56f",
-  "core/scripts/mcp-server/tools/quality.ts": "26ddf75d",
-  "core/scripts/mcp-server/tools/review.ts": "c2d464ed",
+  "core/scripts/mcp-server/tools/hitl.ts": "f447345f",
+  "core/scripts/mcp-server/tools/hook-event-report.ts": "3f21836e",
+  "core/scripts/mcp-server/tools/index.ts": "884172ba",
+  "core/scripts/mcp-server/tools/plan.ts": "477fd80d",
+  "core/scripts/mcp-server/tools/quality.ts": "c4634453",
+  "core/scripts/mcp-server/tools/registrar.ts": "efd81b3a",
+  "core/scripts/mcp-server/tools/review.ts": "4d72ca19",
   "core/scripts/mcp-server/types.ts": "6c5e60bc",
   "core/scripts/mcp-server.ts": "99cc6833",
   "core/skills/add-paradigm/SKILL.md": "5d4fa389",
@@ -234,6 +239,8 @@
   "core/templates/add-route-template.schema.json": "867a45c1",
   "core/templates/checklist-template.md": "d6b73a5c",
   "core/templates/checklist-template.schema.json": "fb3a73e8",
+  "core/templates/collab-contract-template.md": "bccba0fd",
+  "core/templates/collab-contract-template.schema.json": "ae0f482c",
   "core/templates/fix-verification-template.md": "9c9ed175",
   "core/templates/fix-verification-template.schema.json": "a18bc6a5",
   "core/templates/handoff-multi-round-template.md": "d3a2375d",

package/templates/adapters/claude/hooks/pre-tool-use.sh

@@ -103,8 +103,13 @@ if [ "$tool_name" = "Write" ] || [ "$tool_name" = "Edit" ] || [ "$tool_name" = "
 
   # §C: HITL tongyi 检查 — plans/ + PLAN_REVIEW reviews/ 写入前必须有 .hitl-tongyi-{planName} 哨兵
   # implementation/runtime review 不需要 HITL，走 §B 活跃 Plan 检查
+  # handoff 是 Step 8 收敛产物（多轮交接手册），不经 HITL 审批，同样豁免
   if echo "$file_path" | grep -qE '\.(qoder|claude|add|vscode|trae)/(plans)/'; then
-    _do_hitl=true
+    if echo "$file_path" | grep -qE '\-handoff'; then
+      _do_hitl=false  # handoff 不被 HITL 拦截（Step 8 产物，无独立审批）
+    else
+      _do_hitl=true
+    fi
   elif echo "$file_path" | grep -qE '\.(qoder|claude|add|vscode|trae)/(reviews)/'; then
     if echo "$file_path" | grep -qE '-(implementation|runtime)'; then
       _do_hitl=false  # implementation/runtime review 不被 HITL 拦截

package/templates/adapters/codex/hooks/pre-tool-use.sh

@@ -175,8 +175,14 @@ if [ "$tool_name" = "Write" ] || [ "$tool_name" = "Edit" ] || [ "$tool_name" = "
 
   # §C: HITL tongyi 检查 — plans/ + PLAN_REVIEW reviews/ 写入前必须有 .hitl-tongyi-{planName} 哨兵
   # implementation/runtime review 不需要 HITL，走 §B 活跃 Plan 检查
+  # handoff 是 Step 8 收敛产物（多轮交接手册），不经 HITL 审批，同样豁免
+  # TODO 应该caijuehub管理
   if echo "$file_path" | grep -qE '\.(qoder|claude|add|vscode|trae)/(plans)/'; then
-    _do_hitl=true
+    if echo "$file_path" | grep -qE '\-handoff'; then
+      _do_hitl=false  # handoff 不被 HITL 拦截（Step 8 产物，无独立审批）
+    else
+      _do_hitl=true
+    fi
   elif echo "$file_path" | grep -qE '\.(qoder|claude|add|vscode|trae)/(reviews)/'; then
     if echo "$file_path" | grep -qE '-(implementation|runtime)'; then
       _do_hitl=false  # implementation/runtime review 不被 HITL 拦截

package/templates/adapters/qoder/hooks/pre-tool-use.sh

@@ -104,8 +104,13 @@ if [ "$tool_name" = "Write" ] || [ "$tool_name" = "Edit" ] || [ "$tool_name" = "
 
   # §C: HITL tongyi 检查 — plans/ + PLAN_REVIEW reviews/ 写入前必须有 .hitl-tongyi-{planName} 哨兵
   # implementation/runtime review 不需要 HITL，走 §B 活跃 Plan 检查
+  # handoff 是 Step 8 收敛产物（多轮交接手册），不经 HITL 审批，同样豁免
   if echo "$file_path" | grep -qE '\.(qoder|claude|add|vscode|trae)/(plans)/'; then
-    _do_hitl=true
+    if echo "$file_path" | grep -qE '\-handoff'; then
+      _do_hitl=false  # handoff 不被 HITL 拦截（Step 8 产物，无独立审批）
+    else
+      _do_hitl=true
+    fi
   elif echo "$file_path" | grep -qE '\.(qoder|claude|add|vscode|trae)/(reviews)/'; then
     if echo "$file_path" | grep -qE '-(implementation|runtime)'; then
       _do_hitl=false  # implementation/runtime review 不被 HITL 拦截

package/templates/adapters/trae/hooks/pre-tool-use.sh

@@ -175,8 +175,14 @@ if [ "$tool_name" = "Write" ] || [ "$tool_name" = "Edit" ] || [ "$tool_name" = "
 
   # §C: HITL tongyi 检查 — plans/ + PLAN_REVIEW reviews/ 写入前必须有 .hitl-tongyi-{planName} 哨兵
   # implementation/runtime review 不需要 HITL，走 §B 活跃 Plan 检查
+  # handoff 是 Step 8 收敛产物（多轮交接手册），不经 HITL 审批，同样豁免
+  # TODO 应该caijuehub管理
   if echo "$file_path" | grep -qE '\.(qoder|claude|add|vscode|trae)/(plans)/'; then
-    _do_hitl=true
+    if echo "$file_path" | grep -qE '\-handoff'; then
+      _do_hitl=false  # handoff 不被 HITL 拦截（Step 8 产物，无独立审批）
+    else
+      _do_hitl=true
+    fi
   elif echo "$file_path" | grep -qE '\.(qoder|claude|add|vscode|trae)/(reviews)/'; then
     if echo "$file_path" | grep -qE '-(implementation|runtime)'; then
       _do_hitl=false  # implementation/runtime review 不被 HITL 拦截

package/templates/adapters/vscode/hooks/pre-tool-use.sh

@@ -103,8 +103,13 @@ if [ "$tool_name" = "Write" ] || [ "$tool_name" = "Edit" ] || [ "$tool_name" = "
 
   # §C: HITL tongyi 检查 — plans/ + PLAN_REVIEW reviews/ 写入前必须有 .hitl-tongyi-{planName} 哨兵
   # implementation/runtime review 不需要 HITL，走 §B 活跃 Plan 检查
+  # handoff 是 Step 8 收敛产物（多轮交接手册），不经 HITL 审批，同样豁免
   if echo "$file_path" | grep -qE '\.(qoder|claude|add|vscode|trae)/(plans)/'; then
-    _do_hitl=true
+    if echo "$file_path" | grep -qE '\-handoff'; then
+      _do_hitl=false  # handoff 不被 HITL 拦截（Step 8 产物，无独立审批）
+    else
+      _do_hitl=true
+    fi
   elif echo "$file_path" | grep -qE '\.(qoder|claude|add|vscode|trae)/(reviews)/'; then
     if echo "$file_path" | grep -qE '-(implementation|runtime)'; then
       _do_hitl=false  # implementation/runtime review 不被 HITL 拦截

package/templates/core/hooks/pre-tool-use.sh

@@ -175,8 +175,14 @@ if [ "$tool_name" = "Write" ] || [ "$tool_name" = "Edit" ] || [ "$tool_name" = "
 
   # §C: HITL tongyi 检查 — plans/ + PLAN_REVIEW reviews/ 写入前必须有 .hitl-tongyi-{planName} 哨兵
   # implementation/runtime review 不需要 HITL，走 §B 活跃 Plan 检查
+  # handoff 是 Step 8 收敛产物（多轮交接手册），不经 HITL 审批，同样豁免
+  # TODO 应该caijuehub管理
   if echo "$file_path" | grep -qE '\.(qoder|claude|add|vscode|trae)/(plans)/'; then
-    _do_hitl=true
+    if echo "$file_path" | grep -qE '\-handoff'; then
+      _do_hitl=false  # handoff 不被 HITL 拦截（Step 8 产物，无独立审批）
+    else
+      _do_hitl=true
+    fi
   elif echo "$file_path" | grep -qE '\.(qoder|claude|add|vscode|trae)/(reviews)/'; then
     if echo "$file_path" | grep -qE '-(implementation|runtime)'; then
       _do_hitl=false  # implementation/runtime review 不被 HITL 拦截

package/templates/core/prisma/add.prisma

@@ -45,6 +45,7 @@ model AuditLog {
 enum HitlType {
   PLAN
   PLAN_REVIEW
+  COLLAB_CONTRACT
 }
 
 enum HitlStatus {
@@ -94,6 +95,12 @@ model PlanRecord {
   checklistTDone Int           @default(0)
   checklistR     Int           @default(0)
   planKeyword    String?
+  // 并发协作契约：该 Plan 在契约中的角色（MASTER=总控 / SUB=子 Plan）
+  contractRole   ContractRole?
+  // 所属契约名（与 CollabContract.contractName 对应，反查用）
+  contractName   String?
+  // 作为总控 Plan 持有的契约（masterPlanName 外键方向）
+  masterContract CollabContract?
   // DPS 四维评分历史（check_dps 调用后回写，供 FFT 自适应权重消费）
   dpsSemScore    Int?          // 语义相关性 0-100
   dpsEntropyScore Int?         // 信息熵匹配 0-100
@@ -106,6 +113,7 @@ model PlanRecord {
   updatedAt      DateTime      @updatedAt
 
   @@index([planKeyword])
+  @@index([contractName])
 }
 
 model ReviewRecord {
@@ -123,3 +131,30 @@ model ReviewRecord {
   @@index([planName])
   @@index([type])
 }
+
+enum ContractRole {
+  MASTER  // 总控 Plan（契约持有者）
+  SUB     // 子 Plan（契约实施单元）
+}
+
+// 并发协作契约（多智能体并行实施规则集，对应 collab-contract 文档）
+model CollabContract {
+  id                 String   @id @default(cuid())
+  contractName       String   @unique
+  contractPath       String
+  // 外键：总控 Plan（契约持有者，ContractRole=MASTER，一对一）
+  masterPlanName     String   @unique
+  masterPlan         PlanRecord @relation(fields: [masterPlanName], references: [planName], onDelete: Restrict)
+  participants       Json     // [{role, platformEntity, boundPlan, planKeyword, description}]
+  abilityMatrix      Json?    // {能力: {专家: boolean}}
+  stages             Json     // [{stage, expert, trigger, parallelism}]
+  dependencyGraph    String?  // ASCII 图 + 机器可读声明
+  fileBoundaries     Json     // [{expert, exclusiveDomain, forbidden, isolationMode}]  isolationMode: file/worktree
+  completionCriteria Json?    // {专家: 完成标志}
+  status             String   @default("ACTIVE") // ACTIVE / SUPERSEDED
+  version            Int      @default(1)
+  createdAt          DateTime @default(now())
+  updatedAt          DateTime @updatedAt
+
+  @@index([masterPlanName])
+}

package/templates/core/rules/profiles/index.toml

@@ -0,0 +1,12 @@
+# add-coder 技术栈 profile 注册表（内置）
+# 用户自定义: 在 {magicDir}/rules/profiles/ 下放置任意 *.md 即可被 `add-coder stack list` 识别
+
+[[profile]]
+name = "webapp"
+description = "Web 应用（前端/全栈）: LangGraph/Next.js/Prisma/TypeScript 案例栈"
+file = "webapp-profile.md"
+
+[[profile]]
+name = "machineserver"
+description = "后端服务（机器人→中间件→平台链路）: Kestra/HTTP API/事件驱动"
+file = "machineserver-profile.md"

package/templates/core/rules/profiles/machineserver-profile.md

@@ -0,0 +1,22 @@
+# machineserver-profile — 后端服务技术栈约束
+
+> 由 add-coder 分发，可通过 `add-coder stack set machineserver` 启用/切换。
+> 本 profile 描述「机器人 → 中间件 → 平台」后端链路的通用约束，不绑定具体框架实现。
+> 启用后，AI 必须遵守本文件中全部约束；未启用时本文件不构成约束。
+
+## 技术栈事实（不是约束，仅供 AI 参考）
+
+- 典型链路: 机器人/Agent → Kestra 工作流编排 → HTTP API → 平台
+- 典型形态: 事件驱动 + 任务编排 + 服务间 HTTP 集成
+
+## 代码质量
+
+- 服务边界: 编排(工作流)与业务(API)分层,禁止在编排层写业务逻辑
+- 幂等: 任务/接口消费必须幂等,失败可重放
+- 契约: 跨服务 API 必须有显式契约(OpenAPI/JSON Schema),禁止隐式字段约定
+- 可观测: 每个任务/请求链路必须有 traceId 贯穿
+
+## 错误处理
+
+- 失败路径与成功路径信息密度等价
+- 编排失败必须有重试/补偿策略,禁止静默失败

package/templates/core/rules/profiles/webapp-profile.md

@@ -0,0 +1,61 @@
+# webapp-profile — Web 应用技术栈约束
+
+> 由 add-coder 分发，可通过 `add-coder stack set webapp` 启用/切换。
+> 本 profile 为 ADD 案例研究（前端/全栈 Web 应用）沉淀的技术栈约束，从 project_rules.md 迁移而来。
+> 启用后，AI 必须遵守本文件中全部约束；未启用时本文件不构成约束。
+
+## 数据库 Schema
+
+Prisma schema 修改时：
+- 新增模型必须有审计数据字段（Json 类型）
+- 关联关系必须定义 `onDelete: Cascade`
+- 使用 `@id @default(cuid())` 生成 ID
+- 使用 `@updatedAt` 自动更新时间戳
+
+## Agent 节点
+
+LangGraph 节点实现时：
+- 必须通过 `wrapNodeWithAudit` 包装
+- `inputSnapshot` 不能为空对象 `{}`
+- 路由决策必须调用 `agentAuditRoute()`
+- 检索节点必须记录证据链 diff
+
+## 代码质量
+
+- TypeScript 编译必须通过（`npx tsc --noEmit`）
+- ESLint 零 error（`npx eslint src/` 不得出现 error 级别问题，warning 逐步降低）
+- 禁止 `any` 类型（必须显式定义）
+- 禁止简化代码实现，一切以代码高质量为衡量标准
+- 新增文件必须在项目已有目录结构内，遵循现有命名规范
+
+## 附录 A
+
+### A. {{projectName}} ADD-0.3 实现（AuditCallback）
+
+{{projectName}} 通过 **LangChain `BaseCallbackHandler` 继承模式** 实现自动审计：
+
+- `AuditCallback extends BaseCallbackHandler` — 继承 LangChain 标准回调接口
+- `handleChainStart()` / `handleChainEnd()` / `handleChainError()` — 节点进入/退出/异常自动记录
+- `handleLLMEnd()` — LLM 调用完成时记录 token 用量
+- `handleToolStart()` / `handleToolEnd()` — Tool 调用完成时记录输入/输出
+
+注入方式（`src/agents/index.ts`）：
+```typescript
+const callback = new AuditCallback(traceId, userId)
+agent.invoke(input, { callbacks: [callback] })
+```
+
+**与 Layer 1 dev-logger 的关系**：
+- Layer 1（`wrapNodeWithAudit`）：console + file，仅开发环境，AI 助手消费
+- Layer 2（`AuditCallback`）：AuditLog 表，所有环境始终开启，最终用户消费
+- 两者共存互补，互不干扰
+
+**设计目标达成情况**：
+
+| 目标 | 状态 |
+|------|:----:|
+| 自动记录 | ✅ |
+| 不阻塞响应 | ✅ |
+| 成功/失败等价 | ✅ |
+| 节点过滤 | ✅ |
+| traceId 全链追踪 | ✅ |

package/templates/core/rules/project_rules.md

@@ -846,6 +846,10 @@ ADD-17 定义 HITL 如何在 guard 约束下运作（temporary.md 绕过 guard
 
 ## 项目技术约束
 
+### 技术栈约束（profile 引用）
+
+{{stackReferenceLine}}
+
 ### 审计日志器模式
 
 每个业务域的审计日志器必须遵循 `audit-logger.ts` 的完整模式：
@@ -856,30 +860,6 @@ ADD-17 定义 HITL 如何在 guard 约束下运作（temporary.md 绕过 guard
 - `readRecentLogs()` / `clearLogs()` 读写函数
 - `ENABLE_FILE_LOG` 环境变量控制，开发环境默认启用
 
-### 数据库 Schema
-
-Prisma schema 修改时：
-- 新增模型必须有审计数据字段（Json 类型）
-- 关联关系必须定义 `onDelete: Cascade`
-- 使用 `@id @default(cuid())` 生成 ID
-- 使用 `@updatedAt` 自动更新时间戳
-
-### Agent 节点
-
-LangGraph 节点实现时：
-- 必须通过 `wrapNodeWithAudit` 包装
-- `inputSnapshot` 不能为空对象 `{}`
-- 路由决策必须调用 `agentAuditRoute()`
-- 检索节点必须记录证据链 diff
-
-### 代码质量
-
-- TypeScript 编译必须通过（`npx tsc --noEmit`）
-- ESLint 零 error（`npx eslint src/` 不得出现 error 级别问题，warning 逐步降低）
-- 禁止 `any` 类型（必须显式定义）
-- 禁止简化代码实现，一切以代码高质量为衡量标准
-- 新增文件必须在项目已有目录结构内，遵循现有命名规范
-
 ---
 
 ## MCP 工具约束
@@ -890,7 +870,7 @@ LangGraph 节点实现时：
 
 AI 助手在生成任何代码前，必须先调用以下工具获取真实信息，不得凭记忆假设：
 - `get_project_context` — 获取项目结构、技术栈、可用脚本
-- `get_db_schema` — 获取 Prisma Schema 模型定义
+- `get_db_schema` — 获取项目数据模型定义（如 Prisma Schema / ORM 模型）
 - `get_audit_logger_pattern` — 获取现有审计日志器模式
 - `find_related_docs` — 查找与变更相关的项目文档（ADD-0.1 文档先行）
 
@@ -961,34 +941,6 @@ Trae IDE 加载项目时自动连接 MCP 服务器。
 
 ### 附录
 
-#### A. {{projectName}} ADD-0.3 实现（AuditCallback）
-
-{{projectName}} 通过 **LangChain `BaseCallbackHandler` 继承模式** 实现自动审计：
-
-- `AuditCallback extends BaseCallbackHandler` — 继承 LangChain 标准回调接口
-- `handleChainStart()` / `handleChainEnd()` / `handleChainError()` — 节点进入/退出/异常自动记录
-- `handleLLMEnd()` — LLM 调用完成时记录 token 用量
-- `handleToolStart()` / `handleToolEnd()` — Tool 调用完成时记录输入/输出
-
-注入方式（`src/agents/index.ts`）：
-```typescript
-const callback = new AuditCallback(traceId, userId)
-agent.invoke(input, { callbacks: [callback] })
-```
-
-**与 Layer 1 dev-logger 的关系**：
-- Layer 1（`wrapNodeWithAudit`）：console + file，仅开发环境，AI 助手消费
-- Layer 2（`AuditCallback`）：AuditLog 表，所有环境始终开启，最终用户消费
-- 两者共存互补，互不干扰
-
-**设计目标达成情况**：
-
-| 目标 | 状态 |
-|------|:----:|
-| 自动记录 | ✅ |
-| 不阻塞响应 | ✅ |
-| 成功/失败等价 | ✅ |
-| 节点过滤 | ✅ |
-| traceId 全链追踪 | ✅ |
+> 附录 A（{{projectName}} ADD-0.3 AuditCallback 实现，含 LangChain `BaseCallbackHandler` 模式）已移至技术栈 profile：`{{magicDir}}/rules/profiles/webapp-profile.md` §附录 A。未设置 webapp 技术栈时，该附录内容不构成约束。
 
 #### B. 历史参考（milktea 项目）

package/templates/core/scripts/mcp-server/tools/audit.ts

@@ -1,9 +1,13 @@
 import * as z from "zod/v4"
-import type { McpServer } from "@modelcontextprotocol/server"
+import type { ToolRegistrar } from "./registrar.js"
 import { textResponse, errorResponse } from "../shared/response.js"
 import { prisma } from "../shared/prisma.js"
+import { PROJECT_ID, PROJECT_ROOT } from "../shared/env.js"
 
-export function registerAuditTools(server: McpServer) {
+export function registerAuditTools(server: ToolRegistrar) {
+
+  // args 窄化辅助：MCP 工具参数可能是 string | number | undefined，统一转 string
+  const s = (v: string | number | undefined): string => (typeof v === "number" ? String(v) : (v ?? ""))
 
   // ===== query_audit_logs (L992-1109) =====
   server.registerTool("query_audit_logs", {
@@ -21,16 +25,18 @@ export function registerAuditTools(server: McpServer) {
     try {
       const { targetType, action, targetId, planKeyword, keyword, sinceMinutes, limit = 20 } = args
       const where: Record<string, unknown> = {}
-      if (sinceMinutes !== undefined) where.createdAt = { gte: new Date(Date.now() - sinceMinutes * 60 * 1000) }
-      if (targetType) where.targetType = targetType; if (action) where.action = action; if (targetId) where.targetId = targetId; if (planKeyword) where.planKeyword = planKeyword
-      if (keyword) where.OR = [{ action: { contains: keyword, mode: "insensitive" } },{ targetType: { contains: keyword, mode: "insensitive" } },{ targetId: { contains: keyword, mode: "insensitive" } },{ reason: { contains: keyword, mode: "insensitive" } },{ planKeyword: { contains: keyword, mode: "insensitive" } }]
-      const logs = await prisma.devOperation.findMany({ where, orderBy: { createdAt: "desc" }, take: Math.min(limit, 100), include: { user: { select: { username: true } } } })
+      if (sinceMinutes !== undefined) where.createdAt = { gte: new Date(Date.now() - Number(sinceMinutes) * 60 * 1000) }
+      if (targetType) where.targetType = s(targetType); if (action) where.action = s(action); if (targetId) where.targetId = s(targetId); if (planKeyword) where.planKeyword = s(planKeyword)
+      const kw = s(keyword)
+      if (kw) where.OR = [{ action: { contains: kw, mode: "insensitive" } },{ targetType: { contains: kw, mode: "insensitive" } },{ targetId: { contains: kw, mode: "insensitive" } },{ reason: { contains: kw, mode: "insensitive" } },{ planKeyword: { contains: kw, mode: "insensitive" } }]
+      type AuditLogRow = { createdAt: Date; action: string; targetType: string; targetId: string | null; reason: string | null; planKeyword: string | null }
+      const logs = await (prisma.devOperation as Record<string, (...a: unknown[]) => unknown>).findMany({ where, orderBy: { createdAt: "desc" }, take: Math.min(Number(limit) || 20, 100), include: { user: { select: { username: true } } } }) as unknown as AuditLogRow[]
       if (logs.length === 0) {
         const f: string[] = []; if (targetType) f.push(`targetType=${targetType}`); if (action) f.push(`action=${action}`); if (targetId) f.push(`targetId=${targetId}`); if (planKeyword) f.push(`planKeyword=${planKeyword}`); if (keyword) f.push(`keyword="${keyword}"`); if (sinceMinutes !== undefined) f.push(`sinceMinutes=${sinceMinutes}`)
         return textResponse(`=== 开发操作审计日志 ===\n\n未找到匹配的审计记录（条件: ${f.length > 0 ? f.join(", ") : "无条件"}）。\n\n可能原因: 数据库未运行、尚无相关开发操作记录、或 filter 过于严格。`)
       }
       const fl: string[] = []; if (targetType) fl.push(`targetType=${targetType}`); if (action) fl.push(`action=${action}`); if (targetId) fl.push(`targetId=${targetId}`); if (planKeyword) fl.push(`planKeyword=${planKeyword}`); if (keyword) fl.push(`keyword="${keyword}"`); if (sinceMinutes !== undefined) fl.push(`最近${sinceMinutes}分钟`)
-      const lines = [`=== 开发操作审计日志 (条件: ${fl.length > 0 ? fl.join(", ") : "无过滤条件（最近全部）"}) ===`, `共 ${logs.length} 条记录`]
+      const lines = [`=== 开发操作审计日志 (条件: ${fl.length > 0 ? fl.join(", ") : "无过滤条件（最近全部）"}) ===`, `服务项目: ${PROJECT_ID} (${PROJECT_ROOT})`, `共 ${logs.length} 条记录`]
       for (let i = 0; i < logs.length; i++) {
         const l = logs[i]; lines.push(`[${i+1}] ${l.createdAt.toISOString()}`, `    action: ${l.action} | targetType: ${l.targetType} | targetId: ${l.targetId || "(无)"}`)
         if (l.reason) lines.push(`    reason: ${l.reason}`); if (l.planKeyword) lines.push(`    planKeyword: ${l.planKeyword}`)
@@ -56,16 +62,19 @@ export function registerAuditTools(server: McpServer) {
   }, async (args: Record<string, string | number | undefined>, _ctx: unknown) => {
     try {
       const { action, targetType, targetId, planKeyword, beforeState, afterState, reason } = args
+      const tId = s(targetId)
       const pathWarnings: string[] = []
-      if (targetId && (targetId.startsWith("/") || /^[A-Z]:\\/.test(targetId))) pathWarnings.push(`⚠️ targetId 使用了绝对路径: "${targetId}"。请使用相对路径。`)
+      if (tId && (tId.startsWith("/") || /^[A-Z]:\\/.test(tId))) pathWarnings.push(`⚠️ targetId 使用了绝对路径: "${tId}"。请使用相对路径。`)
       let parsedBefore: unknown, parsedAfter: unknown
-      try { if (beforeState) parsedBefore = JSON.parse(beforeState); if (afterState) parsedAfter = JSON.parse(afterState) } catch { return errorResponse("beforeState/afterState 必须是有效的 JSON 字符串。") }
-      let systemUser = await (prisma.addUser as Record<string, (...a: unknown[]) => unknown>).findUnique({ where: { username: "ai-assistant" }, select: { id: true } })
-      if (!systemUser) systemUser = await (prisma.addUser as Record<string, (...a: unknown[]) => unknown>).create({ data: { id: "ai-assistant", username: "ai-assistant", email: "ai-assistant@internal" }, select: { id: true } })
-      const log = await (prisma.devOperation as Record<string, (...a: unknown[]) => unknown>).create({ data: { userId: systemUser.id, planKeyword: planKeyword || "unknown", action, targetType, targetId: targetId || "unknown", beforeState: parsedBefore ?? null, afterState: parsedAfter ?? null, reason: reason || null } })
-      const lines = [`✅ 开发操作已记录`, `  ID: ${log.id}`, `  action: ${action}`, `  targetType: ${targetType}`, `  targetId: ${targetId || "unknown"}`, `  planKeyword: ${planKeyword || "unknown"}`, `  createdAt: ${log.createdAt.toISOString()}`]
+      try { if (beforeState) parsedBefore = JSON.parse(s(beforeState)); if (afterState) parsedAfter = JSON.parse(s(afterState)) } catch { return errorResponse("beforeState/afterState 必须是有效的 JSON 字符串。") }
+      type AddUserRow = { id: string }
+      let systemUser = await (prisma.addUser as Record<string, (...a: unknown[]) => unknown>).findUnique({ where: { username: "ai-assistant" }, select: { id: true } }) as unknown as AddUserRow | null
+      if (!systemUser) systemUser = await (prisma.addUser as Record<string, (...a: unknown[]) => unknown>).create({ data: { id: "ai-assistant", username: "ai-assistant", email: "ai-assistant@internal" }, select: { id: true } }) as unknown as AddUserRow
+      type DevLogRow = { id: string; createdAt: Date }
+      const log = await (prisma.devOperation as Record<string, (...a: unknown[]) => unknown>).create({ data: { userId: systemUser.id, planKeyword: s(planKeyword) || "unknown", action: s(action), targetType: s(targetType), targetId: tId || "unknown", beforeState: parsedBefore ?? null, afterState: parsedAfter ?? null, reason: s(reason) || null } }) as unknown as DevLogRow
+      const lines = [`✅ 开发操作已记录`, `  落库项目: ${PROJECT_ID} (${PROJECT_ROOT})`, `  ID: ${log.id}`, `  action: ${s(action)}`, `  targetType: ${s(targetType)}`, `  targetId: ${tId || "unknown"}`, `  planKeyword: ${s(planKeyword) || "unknown"}`, `  createdAt: ${log.createdAt.toISOString()}`]
       if (pathWarnings.length > 0) { lines.push(""); lines.push(...pathWarnings) }
-      lines.push("", `📋 落库回查（必须执行）:`, targetId ? `  query_audit_logs({ targetId: "${targetId}" }) — 确认本条记录已写入` : "")
+      lines.push("", `📋 落库回查（必须执行）:`, tId ? `  query_audit_logs({ targetId: "${tId}" }) — 确认本条记录已写入` : "")
       return textResponse(lines.join("\n"))
     } catch (error) { return errorResponse(`记录开发操作失败: ${error instanceof Error ? error.message : String(error)}`) }
   })

package/templates/core/scripts/mcp-server/tools/context.ts

@@ -1,5 +1,5 @@
 import * as z from "zod/v4"
-import type { McpServer } from "@modelcontextprotocol/server"
+import type { ToolRegistrar } from "./registrar.js"
 import { readFile } from "fs/promises"
 import { readdir } from "fs/promises"
 import { stat } from "fs/promises"
@@ -9,7 +9,7 @@ import { textResponse, errorResponse } from "../shared/response.js"
 import { readFileSafe, readdirRecursive } from "../shared/fs.js"
 import { PROJECT_ROOT, MAGIC_DIR } from "../shared/fs.js"
 
-export function registerContextTools(server: McpServer) {
+export function registerContextTools(server: ToolRegistrar) {
 
   // ===== get_project_context (L166-430) =====
   server.registerTool(
@@ -66,6 +66,24 @@ export function registerContextTools(server: McpServer) {
             }
             parts.push("")
           }
+          // 技术栈 profile 追加（D8）：stack.json → profiles/{stack}-profile.md 存在 → 追加全文
+          const stackRaw = await readFileSafe(join(PROJECT_ROOT, MAGIC_DIR, "stack.json"))
+          if (stackRaw) {
+            try {
+              const stackDoc = JSON.parse(stackRaw) as { stack?: unknown }
+              if (typeof stackDoc.stack === "string" && stackDoc.stack) {
+                const profileContent = await readFileSafe(join(PROJECT_ROOT, MAGIC_DIR, "rules", "profiles", `${stackDoc.stack}-profile.md`))
+                if (profileContent) {
+                  parts.push(`=== 技术栈约束 (${stackDoc.stack}-profile) ===`)
+                  parts.push(profileContent)
+                  parts.push("")
+                } else {
+                  parts.push(`⚠️ profile 文件缺失: ${MAGIC_DIR}/rules/profiles/${stackDoc.stack}-profile.md（技术栈约束未生效）`)
+                  parts.push("")
+                }
+              }
+            } catch { /* stack.json 损坏 → 中性处理，仅返回 project_rules.md */ }
+          }
         }
 
         if (scope === "all" || scope === "structure" || scope === "add-state") {