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 +47 -0
- package/TRIGGER_GUIDE.md +2 -2
- package/ghost.json +1 -1
- package/package.json +1 -1
- package/scripts/install-hooks.mjs +18 -5
- package/scripts/publish-gate.mjs +24 -3
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.
|
|
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.
|
|
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.
|
|
8
|
+
"version": "2.12.0",
|
|
9
9
|
"kind": "mcp",
|
|
10
10
|
"entry": "client/carlos.js",
|
|
11
11
|
"command": "门禁",
|
package/package.json
CHANGED
|
@@ -88,13 +88,26 @@ fi
|
|
|
88
88
|
|
|
89
89
|
# --- 3. tag 重名检查(查**远端**,不是本地) ---
|
|
90
90
|
# 正常流程就是「本地先 git tag 再 push」,本地存在是必然的;
|
|
91
|
-
# 真正要拦的是**远端已有同名 tag
|
|
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
|
-
|
|
94
|
-
|
|
95
|
-
|
|
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 "=============================================="
|
package/scripts/publish-gate.mjs
CHANGED
|
@@ -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
|
-
|
|
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
|
-
|
|
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(
|
|
130
|
+
console.log(`本次版本:${version} | registry latest:${latest || "(无)"} | 已发布版本数:${count}`);
|
|
110
131
|
console.log(`${publish ? "✓" : "✗"} ${reason}`);
|
|
111
132
|
|
|
112
133
|
if (process.env.GITHUB_OUTPUT) {
|