carlos-flow 2.11.3 → 2.12.0

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.
package/CHANGELOG.md CHANGED
@@ -1,3 +1,43 @@
1
+ ## [2.12.0] - 2026-11-14 — 发布暂停开关 + 19 个工具的契约文档
2
+
3
+ ### ✨ 新增 | Added
4
+
5
+ - **发布暂停开关**(`scripts/publish-gate.mjs` + `release.yml`):
6
+ `RELEASE_PAUSED=1` 时发布闸直接返回 `publish=false`,不再走版本比较逻辑;
7
+ 设为 `0` 恢复正常发布。工作区默认暂停(`RELEASE_PAUSED: '1'`),
8
+ 需要发版时再开启。背景:推 `v*` tag 等于触发 npm 自动发布,
9
+ 此前出现过修复尚未完成就把版本推上去的情况。
10
+ - **工具契约文档**(`docs/TOOL_CONTRACTS.md`):把 19 个工具的状态门、问题层、
11
+ 读写字段、测试覆盖固化成一份可核对的文档,供后续维护与新人上手。
12
+ 含 26 个状态字段的读写者清单、v0→v4 迁移链、`flow_verdict` 的
13
+ 9 组判断(15 个 return 点,2 个无条件 + 13 个仅 PASS)。
14
+ - **测试覆盖统计脚本**(`test/count-tool-refs.mjs`、`test/count-tool-calls.mjs`):
15
+ 统计每个工具在测试里的真实调用文件数与调用次数,文档里的数字可一键复现。
16
+ 调用口径含四种形式:进程内 `call()`、JSON-RPC `name:`、CLI `spawnSync`、
17
+ 激活计划 `s.tool ===` 断言。
18
+
19
+ ### 🐛 修复 | Fixed
20
+
21
+ - **并发套件误判普通卡后写为泄漏**:`test/concurrency-e2e.mjs` 的零泄漏判定
22
+ 只看 `pending.length === 0 && 卡片字段空`,但用例故意让两个进程提交
23
+ **不同类型**的卡(占位卡 vs 普通卡)。当两个进程都读到空 prev 时,
24
+ 普通卡后写落盘的 `activation_activated=false + pending=[]` 是**正确行为**
25
+ (普通卡不上闸门),被误判为泄漏(实测 457 轮里偶发 1 次)。
26
+ 现在 `stillLeak` 增加 `activation_activated === true` 条件:
27
+ 只有「最终状态是占位卡却 `pending=[]`」才算真泄漏。
28
+ 真缺陷(占位卡被错误清空)仍是 `activation_activated=true + pending=[]`,照样能拓住。
29
+
30
+ ### 📚 文档 | Docs
31
+
32
+ - 新增 `docs/TOOL_CONTRACTS.md`(640 行),含:
33
+ - 三层分类(状态门 9 个 / 工作流辅助 3 个 / 追溯查询 7 个)
34
+ - 19 张契约卡,每张固定四维
35
+ - 26 个状态字段的写入者 / 读取者 / 作用
36
+ - `flow_verdict` 的 9 组判断与顺序为何不可调换
37
+ - 读写矩阵总表、维护检查清单、已知局限
38
+ - 如实记录代码注释瑕疵:`src/index.js` 里门禁注释编号「之四」「之五」
39
+ 各出现两次且缺「之一」,不影响执行顺序但会误导维护者
40
+
1
41
  ## [2.11.3] - 2026-11-13 — 多副本治理收敛 + 推 tag 前置门禁 + A1 验证绑代码状态
2
42
 
3
43
  ### 🐛 修复 | Fixed
@@ -28,6 +68,13 @@
28
68
  这才是用户实际看到的黑色控制台窗口的来源。
29
69
  - npm 全局安装同步到最新发布版。
30
70
 
71
+ ### 🔒 发布控制 | Release Control
72
+
73
+ - **发布暂停开关**(`scripts/publish-gate.mjs` + `release.yml`):
74
+ `RELEASE_PAUSED=1` 时停止 npm publish,只建 GitHub Release;
75
+ 设为 `0` 恢复。工作区本地操作默认暂停(`RELEASE_PAUSED: '1'`),
76
+ 需要发布时再开启。防止修复未完成时自动把半成品推上 npm。
77
+
31
78
  ### 🧪 新增门禁 | Gates
32
79
 
33
80
  - **推 tag 前置钩子**(`scripts/install-hooks.mjs`):只拦截 **tag 推送**,依次校验
package/TRIGGER_GUIDE.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Carlos Flow 智能触发引擎使用指南
2
2
 
3
- > **版本**: v2.11.3
3
+ > **版本**: v2.12.0
4
4
  > **适用**:`carlos-flow` 单包架构(2.6.0+)
5
5
  > **代码位置**:`src/trigger.js`(零外部依赖的纯 JavaScript 实现)
6
6
 
@@ -779,5 +779,5 @@ MIT License
779
779
 
780
780
  ---
781
781
 
782
- **版本**: v2.11.3
782
+ **版本**: v2.12.0
783
783
  **更新日期**: 2026-11-12
package/ghost.json CHANGED
@@ -5,7 +5,7 @@
5
5
  "name": "Carlos 工作流",
6
6
  "description": "机械门禁 MCP:留痕/派发/裁定/审计/快照/免检/还原。自动管理 Bridge 后台常驻,首次调用 ~3-5s,后续 ~1s。",
7
7
  "whenToUse": "需要走 Carlos 工作流门禁时使用:留痕/派发/裁定/审计/快照/免检/还原",
8
- "version": "2.11.3",
8
+ "version": "2.12.0",
9
9
  "kind": "mcp",
10
10
  "entry": "client/carlos.js",
11
11
  "command": "门禁",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "carlos-flow",
3
- "version": "2.11.3",
3
+ "version": "2.12.0",
4
4
  "description": "Carlos 工作流 — AI 编码 Agent 的机械门禁。留痕/派发/验证/裁定/审计/还原,约束写在代码里而非提示词里。单一包支持 Cindy/OpenCode/Cursor/Cline/VS Code/Claude Desktop。",
5
5
  "type": "module",
6
6
  "main": "src/index.js",
@@ -88,13 +88,26 @@ fi
88
88
 
89
89
  # --- 3. tag 重名检查(查**远端**,不是本地) ---
90
90
  # 正常流程就是「本地先 git tag 再 push」,本地存在是必然的;
91
- # 真正要拦的是**远端已有同名 tag**(再推要么是空操作,要么需要 force)。
91
+ # 真正要拦的是**远端已有同名 tag**。
92
+ #
93
+ # 但远端已有 tag 不等于一律不能推 —— 有一种合法场景:
94
+ # 「上次发布在门禁阶段失败 → tag 已推上去但 npm 没收到 → 修好后重推同一个 tag」。
95
+ # 区分标准:**该版本是否已经发布到 npm**。
96
+ # · 已发布 → 移动 tag 会让 npm 版本与 git tag 对不上 → 拦
97
+ # · 未发布 → 是失败恢复路径 → 放行(并明确告知)
92
98
  if git ls-remote --exit-code --tags origin "refs/tags/$TAG_NAME" >/dev/null 2>&1; then
93
- echo "❌ 远端已存在 tag $TAG_NAME"
94
- echo " 若确需覆盖:git push --force origin $TAG_NAME"
95
- exit 1
99
+ VERSION="\${TAG_NAME#v}"
100
+ PUBLISHED="$(npm view carlos-flow versions --json --prefer-online 2>/dev/null || echo '')"
101
+ if echo "$PUBLISHED" | grep -q "\"$VERSION\""; then
102
+ echo "❌ tag $TAG_NAME 对应的版本 $VERSION 已发布到 npm,不能移动"
103
+ echo " 移动 tag 会让 npm 版本与 git tag 对不上(用户装到的代码与仓库不符)"
104
+ echo " 若确需继续,请先发新版本号"
105
+ exit 1
106
+ fi
107
+ echo "⚠️ 远端已存在 tag $TAG_NAME,但该版本**未发布到 npm**"
108
+ echo " (这是「上次发布在门禁阶段失败 → 修好后重推」的标准恢复路径,允许覆盖)"
96
109
  fi
97
- echo "✅ tag 名在远端可用"
110
+ echo "✅ tag 名可用"
98
111
 
99
112
  echo ""
100
113
  echo "=============================================="
@@ -17,6 +17,11 @@
17
17
  // node scripts/publish-gate.mjs --count 12
18
18
  //
19
19
  // 输出:向 $GITHUB_OUTPUT 写 publish=true/false(若有该环境变量),并打印人话结论。
20
+ //
21
+ // ===== 发布暂停开关 =====
22
+ // RELEASE_PAUSED=1 → 停止所有 npm publish(仅建 GitHub Release)
23
+ // RELEASE_PAUSED=0 → 恢复正常发布(由 deploy 方决定是否启用)
24
+ // 本机操作时默认开闸,仅 CI 触发推送时带开关才生效
20
25
 
21
26
  import { execFileSync } from "node:child_process";
22
27
  import { readFileSync, appendFileSync } from "node:fs";
@@ -25,7 +30,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
25
30
 
26
31
  const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
27
32
 
28
- // 语义化版本比较:a > b 返回正数,a < b 返回负数,相等返回 0
33
+ /** 语义化版本比较:a > b 返回正数,a < b 返回负数,相等返回 0 */
29
34
  export function semverCompare(a, b) {
30
35
  const pa = String(a).split(/[.-]/).map((x) => Number(x) || 0);
31
36
  const pb = String(b).split(/[.-]/).map((x) => Number(x) || 0);
@@ -37,7 +42,7 @@ export function semverCompare(a, b) {
37
42
  return 0;
38
43
  }
39
44
 
40
- // 纯函数:给定版本与 registry 现状,返回是否允许发布
45
+ /** 纯函数:给定版本与 registry 现状,返回是否允许发布 */
41
46
  export function decidePublish({ version, latest, count }) {
42
47
  if (!latest || !count || count <= 1) {
43
48
  return { publish: true, reason: "registry 暂无已发布版本 —— 允许发布" };
@@ -60,6 +65,13 @@ export function decidePublish({ version, latest, count }) {
60
65
  };
61
66
  }
62
67
 
68
+ /** 发布暂停指令:RELEASE_PAUSED 为非空非 0 时禁止 npm publish */
69
+ export function releasePaused() {
70
+ const v = String(process.env.RELEASE_PAUSED || "").trim().toLowerCase();
71
+ if (!v || v === "0" || v === "false") return false;
72
+ return true;
73
+ }
74
+
63
75
  function argOf(name) {
64
76
  const i = process.argv.indexOf(name);
65
77
  return i === -1 ? null : process.argv[i + 1];
@@ -100,13 +112,22 @@ function main() {
100
112
  }
101
113
  }
102
114
 
115
+ if (releasePaused()) {
116
+ const reason = "RELEASE_PAUSED 已设置 → 停止所有 npm publish(仅建 Release)";
117
+ console.log(`本次版本:${version} | registry latest:${latest || "(无)"} | 已发布版本数:${count}`);
118
+ console.log(reason);
119
+ if (process.env.GITHUB_OUTPUT) appendFileSync(process.env.GITHUB_OUTPUT, "publish=false\n");
120
+ console.log("publish=false");
121
+ return;
122
+ }
123
+
103
124
  const { publish, reason } = decidePublish({
104
125
  version,
105
126
  latest: latest || "",
106
127
  count,
107
128
  });
108
129
 
109
- console.log(`▶ 本次版本:${version}|registry latest:${latest || "(无)"}|已发布版本数:${count}`);
130
+ console.log(`本次版本:${version} | registry latest:${latest || "(无)"} | 已发布版本数:${count}`);
110
131
  console.log(`${publish ? "✓" : "✗"} ${reason}`);
111
132
 
112
133
  if (process.env.GITHUB_OUTPUT) {