add-coder 0.3.21 → 0.3.23

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +30 -3
  2. package/package.json +1 -1
  3. package/templates/.add-coder-src-hash.json +2 -3
  4. package/templates/core/scripts/mcp-server/tools/review.ts +3 -1
  5. package/templates/core/DEPENDENCIES.md +0 -91
package/README.md CHANGED
@@ -4,7 +4,7 @@ Make 0.75 into one.
4
4
 
5
5
  > 🀄中文 | 🔤[English](#-english-readme)
6
6
 
7
- 💡 [什么叫做酷，怎么让软件变酷？](https://github.com/xiaomingming92/add-coder/blob/main/docs/what-makes-software-cool.md) —— add范式的设计哲学
7
+ 💡 [酷 = 标准符合度 × 熵值管控 —— 我把"酷"从形容词算成了可验证的工程属性](https://github.com/xiaomingming92/add-coder/blob/main/docs/what-makes-software-cool.md)（ADD 范式设计哲学，附 benchmark 实证）
8
8
 
9
9
  > [![NPM downloads](https://img.shields.io/npm/dt/add-coder)](https://www.npmjs.com/package/add-coder) [![NPM version](https://img.shields.io/npm/v/add-coder)](https://www.npmjs.com/package/add-coder) [![GitHub stars](https://img.shields.io/github/stars/xiaomingming92/add-coder)](https://github.com/xiaomingming92/add-coder) <br/>
10
10
  > [📈 趋势](https://www.npmcharts.com/compare/add-coder?interval=30)<br/>
@@ -220,7 +220,20 @@ Plan 里的 Task 不应该停留在文档里。add-coder 将 tasks.md 末尾的
220
220
  tasks.md §IDE JSON → TodoWrite → IDE 面板
221
221
  ```
222
222
 
223
+ ### ⑩ 并发协作契约：多智能体协作即契约
223
224
 
225
+ 多个 Agent 同时改一个仓库，没有契约必然冲突——改同一批文件、审计归因混乱。add-coder 把并行协作变成一份**经 HITL 审批的契约**：
226
+
227
+ | 机制 | 实现 |
228
+ |------|------|
229
+ | **总控 Plan + N 个子 Plan** | Lead Agent 调度，专家按 description 触发条件委派，满足即拉起 |
230
+ | **文件边界** | 默认软隔离（git diff 交叉检查），大改升级 git worktree 硬隔离 |
231
+ | **仲裁链路** | 跨边界修改走 BOUNDARY_REQUEST → Lead 裁决 → 落库可查 |
232
+ | **审计分桶** | 每个专家独立 planKeyword，query_audit_logs 各域各查 |
233
+
234
+ > 契约模板：`templates/core/templates/collab-contract-template.md`（init 后同步到项目 `.add/templates/`），契约新建/重大变更走 `COLLAB_CONTRACT` 审批。
235
+ >
236
+ > 📜 溯源：并发契约原创时间戳 → [CHANGELOG v0.3.18「并发协作契约」](https://github.com/xiaomingming92/add-coder/blob/main/CHANGELOG.md#0318---2026-08-05)；"酷"的工程学定义 → [what-makes-software-cool.md](https://github.com/xiaomingming92/add-coder/blob/main/docs/what-makes-software-cool.md)——契约的审计分桶与完成判定（DPS ≥ 80）正长在"熵值管控"四维上。
224
237
 
225
238
  ---
226
239
 
@@ -411,8 +424,7 @@ Tasks (实验性) 双向 ✅ 已实现 长任务持久化
411
424
 
412
425
  Make 0.75 into one.
413
426
 
414
- 💡[What is cool, and how do you make software cool?](https://github.com/xiaomingming92/add-coder/blob/main/docs/what-makes-software-cool.md)
415
- —— The design philosophy of the ADD paradigm.
427
+ 💡 [Cool = Standard Conformance × Entropy Control — I turned "cool" from an adjective into a verifiable engineering property](https://github.com/xiaomingming92/add-coder/blob/main/docs/what-makes-software-cool.md) (design philosophy of the ADD paradigm, with benchmark evidence)
416
428
  > [![NPM downloads](https://img.shields.io/npm/dt/add-coder)](https://www.npmjs.com/package/add-coder) [![NPM version](https://img.shields.io/npm/v/add-coder)](https://www.npmjs.com/package/add-coder) [![GitHub stars](https://img.shields.io/github/stars/xiaomingming92/add-coder)](https://github.com/xiaomingming92/add-coder) <br/>
417
429
  > [📈 trend](https://www.npmcharts.com/compare/add-coder?interval=30)<br/>
418
430
  > 👍 Please star it if you hope more people will know about [add-coder](https://github.com/xiaomingming92/add-coder)
@@ -551,6 +563,21 @@ Tasks in Plan docs shouldn't stay in docs. add-coder loads the JSON task list fr
551
563
  tasks.md §IDE JSON → TodoWrite → IDE panel
552
564
  ```
553
565
 
566
+ ### ⑩ Concurrency Contract: Multi-Agent Collaboration, Contractualized
567
+
568
+ Multiple agents working one repository without a contract is a guaranteed conflict storm — overlapping file edits, tangled audit attribution. add-coder turns parallel collaboration into a **HITL-approved contract**:
569
+
570
+ | Mechanism | Implementation |
571
+ |------|------|
572
+ | **Master Plan + N sub-Plans** | A Lead Agent orchestrates; experts are delegated by description-matched trigger conditions |
573
+ | **File boundaries** | Soft isolation by default (git diff cross-check), upgrading to git worktree hard isolation for large changes |
574
+ | **Arbitration chain** | Cross-boundary edits go through BOUNDARY_REQUEST → Lead's ruling → recorded to DB |
575
+ | **Audit bucketing** | Each expert holds its own planKeyword; query_audit_logs retrieves per domain |
576
+
577
+ > Contract template: `templates/core/templates/collab-contract-template.md` (synced into the project's `.add/templates/` after init); contract creation/major changes go through `COLLAB_CONTRACT` approval.
578
+ >
579
+ > 📜 Provenance: concurrency-contract original timestamp → [CHANGELOG v0.3.18 "collab-contract"](https://github.com/xiaomingming92/add-coder/blob/main/CHANGELOG.md#0318---2026-08-05); the engineering definition of "cool" → [what-makes-software-cool.md](https://github.com/xiaomingming92/add-coder/blob/main/docs/what-makes-software-cool.md) — the contract's audit bucketing and completion criteria (DPS ≥ 80) are built directly on the four dimensions of "entropy control".
580
+
554
581
  ---
555
582
 
556
583
  ## 📖 Case Study: Breathing Life Back into Old Android Devices
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "add-coder",
3
- "version": "0.3.21",
3
+ "version": "0.3.23",
4
4
  "private": false,
5
5
  "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 即用，人人可体验。",
6
6
  "repository": {
package/templates/.add-coder-src-hash.json CHANGED
@@ -1,5 +1,5 @@
1
1
  {
2
- "_version": "0.3.21",
2
+ "_version": "0.3.23",
3
3
  "adapters/claude/hooks/doc-format-guard.sh": "ec59ad3f",
4
4
  "adapters/claude/hooks/lib/common.sh": "4f3e64ad",
5
5
  "adapters/claude/hooks/lib/context-inject.sh": "cfc8c65e",
@@ -135,7 +135,6 @@
135
135
  "adapters/vscode/launch.json": "f2b79855",
136
136
  "adapters/vscode/settings.json": "7cabd00e",
137
137
  "adapters/vscode/tasks.json": "654d7fbd",
138
- "core/DEPENDENCIES.md": "88d01954",
139
138
  "core/agents/add-flow-guardian.md": "c3e650d2",
140
139
  "core/docs/ADD-governance-claude-code.md": "0f582a7e",
141
140
  "core/docs/ADD-governance-codex.md": "289e8b71",
@@ -226,7 +225,7 @@
226
225
  "core/scripts/mcp-server/tools/plan.ts": "477fd80d",
227
226
  "core/scripts/mcp-server/tools/quality.ts": "c4634453",
228
227
  "core/scripts/mcp-server/tools/registrar.ts": "efd81b3a",
229
- "core/scripts/mcp-server/tools/review.ts": "4d72ca19",
228
+ "core/scripts/mcp-server/tools/review.ts": "370f84f2",
230
229
  "core/scripts/mcp-server/types.ts": "6c5e60bc",
231
230
  "core/scripts/mcp-server.ts": "99cc6833",
232
231
  "core/skills/add-paradigm/SKILL.md": "5d4fa389",
package/templates/core/scripts/mcp-server/tools/review.ts CHANGED
@@ -58,7 +58,9 @@ export function registerReviewTools(server: ToolRegistrar) {
58
58
  .replace(/-review-.*$/, "")
59
59
  .replace(/-implementation.*$/, "")
60
60
  .replace(/-runtime.*$/, "")
61
- if (pn && !derivedPlan.includes(pn)) continue
61
+ // [2026-08-09 修复] 过滤方向颠倒：derivedPlan 是前缀，pn 是完整 planName（{prefix}-plan-v{n}），
62
+ // 应为 pn.includes(derivedPlan)；原实现 derivedPlan.includes(pn) 永远 false → 传入 planName 时全部跳过
63
+ if (pn && !pn.includes(derivedPlan)) continue
62
64
 
63
65
  // 查找匹配的 PlanRecord：PlanRecord.planName 格式为 {planPrefix}-plan-v{n}
64
66
  // 而 derivedPlan 为 {planPrefix}（从 review 文件名中去掉了 -review-v{n}）
package/templates/core/DEPENDENCIES.md DELETED
@@ -1,91 +0,0 @@
1
- # 模板运行时依赖清单（Template Runtime Dependencies）
2
-
3
- > 本文件随 `sync` 同步到项目的 `.add/`（或对应 magic 目录）。**基建依赖必须在安装期解决，不要等到运行时（如 DPS 评分）才发现缺失。**
4
- >
5
- > 两类资源的责任边界：
6
- >
7
- > | 类别 | 解决时机 | 负责方 |
8
- > |------|---------|--------|
9
- > | **基建依赖（npm 包）** | 项目安装期 `npm i` | 本清单（DEPENDENCIES.md） |
10
- > | **运行时资源（模型权重）** | 首次 DPS 调用或 `model:download` 预下载 | `check_dps` 降级提示 + CLI 下载命令 |
11
-
12
- ---
13
-
14
- ## 一、基建依赖（必须随项目安装）
15
-
16
- 以下 npm 包是模板脚本（`.add/scripts/mcp-server/` 等）的运行时基建，缺失时对应功能**静默降级或直接报错**：
17
-
18
- | 依赖 | 版本 | 用途 | 缺失后果 |
19
- |------|------|------|---------|
20
- | `@huggingface/transformers` | `^3.8.1` | DPS `check_dps` 语义延续性 embedding（`getEmbeddings` 动态 import） | **check_dps 延续性静默降级为 0**（语义分 ×0.6 丢失，不易察觉） |
21
- | `vector-cosine-similarity` | `^1.8.0` | DPS 余弦相似度计算 | check_dps 直接报错 |
22
- | `@modelcontextprotocol/server` | `2.0.0` | MCP 服务器运行 | MCP 工具全部不可用 |
23
- | `zod` | `^4.4.3` | MCP 工具输入 schema（`zod/v4`） | MCP 注册失败 |
24
- | `dotenv` | `*` | 环境变量加载 | 配置缺失、连接失败 |
25
- | `@prisma/client` | `^7.0.0` | ADD-7 审计落库（`shared/prisma.ts`） | 审计不可用 |
26
- | `prisma` | `^7.0.0` | Prisma CLI（generate） | 客户端生成失败 |
27
- | `smol-toml` | `^1.7.0` | caijuehub TOML 转录（`npm run generate`） | 策略转录失败 |
28
- | `tsx` | `>=4` | TS 脚本直接执行（sync/转录/benchmark） | 脚本不可运行 |
29
-
30
- > 以上依赖与 add-coder 包本体 `dependencies` 对齐——**安装 add-coder 包即默认获得全部基建**（`npm i add-coder` 自动安装）。本清单服务于**未安装 add-coder 包、仅同步模板脚本**的消费项目。
31
-
32
- ### 安装命令
33
-
34
- ```bash
35
- # 消费项目（未安装 add-coder 包本体）：
36
- npm i @huggingface/transformers@^3.8.1 vector-cosine-similarity@^1.8.0 \
37
- @modelcontextprotocol/server@2.0.0 zod@^4.4.3 dotenv \
38
- @prisma/client@^7.0.0 prisma@^7.0.0 smol-toml@^1.7.0 tsx@>=4
39
- ```
40
-
41
- ---
42
-
43
- ## 二、已知版本冲突：onnxruntime 解析错位（pnpm overrides）
44
-
45
- **场景**：升级到新版 `@huggingface/transformers`（^3.8.x，依赖 `onnxruntime-node@1.21.0`）后，若项目同时存在 langchain 生态的 optional 依赖（其声明 `onnxruntime-node/web@1.14.0`），pnpm 会同时解析出 `onnxruntime-common@1.14.0` 与 `1.21.0` 两套——transformers 加载时拿到错位的 `common@1.14.0`，导致 embedding 初始化异常。
46
-
47
- **症状**：`check_dps` 延续性降级为 0（embedding pipeline 初始化抛错进 catch，现象与模型未下载相同，不易区分）。
48
-
49
- **解决**：用 pnpm overrides 将 1.14.0 强制替换为 1.21.0。
50
-
51
- ```json
52
- // package.json
53
- {
54
- "pnpm": {
55
- "overrides": {
56
- "onnxruntime-node@1.14.0": "1.21.0",
57
- "onnxruntime-web@1.14.0": "1.21.0",
58
- "onnxruntime-common@1.14.0": "1.21.0"
59
- }
60
- }
61
- }
62
- ```
63
-
64
- ```yaml
65
- # pnpm-workspace.yaml（等效，pnpm 9+ 推荐）
66
- packages:
67
- - .
68
- overrides:
69
- onnxruntime-node@1.14.0: 1.21.0
70
- onnxruntime-web@1.14.0: 1.21.0
71
- onnxruntime-common@1.14.0: 1.21.0
72
- ```
73
-
74
- 验证：`pnpm install` 后 `pnpm list onnxruntime-node onnxruntime-common` 应只见 1.21.x，无 1.14.0。
75
-
76
- ---
77
-
78
- ## 三、运行时资源（非基建，可延迟）
79
-
80
- | 资源 | 获取方式 | 缺失时的行为 |
81
- |------|---------|-------------|
82
- | embedding 模型权重（约 90MB） | `add-coder model:download` 预下载；或首次 DPS 调用自动补下载 | check_dps 降级为纯结构分并提示下载入口（**不阻断**） |
83
-
84
- > 基建依赖缺失 ≠ 运行时资源缺失：前者应通过安装解决（本清单），后者通过 `model:download` 解决。check_dps 的降级提示只针对后者。
85
-
86
- ---
87
-
88
- ## 四、新增依赖的维护规则
89
-
90
- - 模板脚本引入新的 npm 包时，**必须同步更新本清单**（依赖 / 版本 / 用途 / 缺失后果四列）
91
- - 版本号与 add-coder 根 `package.json` 保持一致（`dependencies` 是权威来源，本清单是消费项目视图）