carlos-flow 2.5.9 → 2.6.1
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 +184 -90
- package/MIGRATION.md +245 -0
- package/README.en.md +461 -476
- package/README.md +388 -138
- package/README.zh.md +388 -138
- package/TRIGGER_GUIDE.md +745 -554
- package/bridge/mcp-bridge.js +7 -1
- package/client/carlos.js +9 -2
- package/ghost.json +1 -1
- package/package.json +4 -2
- package/scripts/check-repo-parity.mjs +198 -253
- package/src/index.js +12 -2
package/TRIGGER_GUIDE.md
CHANGED
|
@@ -1,71 +1,93 @@
|
|
|
1
|
-
# Carlos Flow 智能触发引擎使用指南
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
1
|
+
# Carlos Flow 智能触发引擎使用指南
|
|
2
|
+
|
|
3
|
+
> **版本**:v2.6.0
|
|
4
|
+
> **适用**:`carlos-flow` 单包架构(2.6.0+)
|
|
5
|
+
> **代码位置**:`src/trigger.js`(零外部依赖的纯 JavaScript 实现)
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 📋 概述
|
|
10
|
+
|
|
11
|
+
Carlos Flow 智能触发引擎是一个三层智能系统,能够自动感知用户意图并在合适的时机触发工作流。它具备以下特点:
|
|
12
|
+
|
|
13
|
+
### 核心特性
|
|
14
|
+
|
|
15
|
+
1. **动态上限控制** - 基于会话时长、任务复杂度和触发历史动态调整触发上限
|
|
16
|
+
2. **评分系统** - 对每个用户输入评分:关键词 50 + 上下文 30 + 意图 20,加权后满分 **38**
|
|
17
|
+
3. **决策引擎** - 基于评分和动态上限决定是否触发工作流(四档:`trigger` / `review` / `ignore` / `throttled`)
|
|
18
|
+
4. **激活机制** - 把判定转成**可执行的 MCP 动作序列**:留痕 → 占位卡 → 闸门 → 放行
|
|
19
|
+
5. **会话隔离** - 触发历史与限流状态按 session 分文件存放,多会话互不干扰
|
|
20
|
+
6. **用户反馈学习** - 记录用户接受/拒绝,持续优化触发
|
|
21
|
+
7. **零外部依赖** - 纯 JavaScript 实现,无需 npm 包
|
|
22
|
+
8. **可解释性** - 每次决策都返回完整 `breakdown`(命中词 / 语境词 / 意图类型 + 各维度得分)
|
|
23
|
+
|
|
24
|
+
### 三层架构总览
|
|
25
|
+
|
|
26
|
+
```mermaid
|
|
27
|
+
flowchart LR
|
|
28
|
+
U["用户输入"] --> L1{"L1 DynamicTriggerManager<br/>还能触发吗?"}
|
|
29
|
+
L1 -->|"间隔不足 / 超上限"| T["throttled<br/>如实返回评分<br/>不动作"]
|
|
30
|
+
L1 -->|"可以"| L2{"L2 TriggerScorer<br/>三维评分"}
|
|
31
|
+
L2 --> L3{"L3 DecisionEngine<br/>四档决策"}
|
|
32
|
+
L3 -->|trigger| A["✅ 激活"]
|
|
33
|
+
L3 -->|review| R["给出建议<br/>不自动执行"]
|
|
34
|
+
L3 -->|ignore| I["静默忽略"]
|
|
35
|
+
A --> G["activation_pending<br/>闸门:claim/dispatch/verdict 全拦"]
|
|
36
|
+
G -->|"补齐后"| OK["放行"]
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
### 系统架构
|
|
40
|
+
|
|
41
|
+
```
|
|
42
|
+
┌─────────────────────────────────────────────────────────────┐
|
|
43
|
+
│ 用户输入 │
|
|
44
|
+
└─────────────────────────────────────────────────────────────┘
|
|
45
|
+
↓
|
|
46
|
+
┌─────────────────────────────────────────────────────────────┐
|
|
47
|
+
│ L1: DynamicTriggerManager (动态上限) │
|
|
48
|
+
│ - 计算当前触发上限 │
|
|
49
|
+
│ - 管理历史触发记录 │
|
|
50
|
+
│ - 确保最少触发间隔 │
|
|
51
|
+
└─────────────────────────────────────────────────────────────┘
|
|
52
|
+
↓
|
|
53
|
+
┌─────────────────────────────────────────────────────────────┐
|
|
54
|
+
│ L2: TriggerScorer (评分系统) │
|
|
55
|
+
│ - 关键词匹配 (0-50 分) │
|
|
56
|
+
│ - 上下文相关性 (0-30 分) │
|
|
57
|
+
│ - 用户意图识别 (0-20 分) │
|
|
58
|
+
└─────────────────────────────────────────────────────────────┘
|
|
59
|
+
↓
|
|
60
|
+
┌─────────────────────────────────────────────────────────────┐
|
|
61
|
+
│ L3: TriggerDecisionEngine (决策引擎) │
|
|
62
|
+
│ - 综合评分计算 │
|
|
63
|
+
│ - 触发决策 (trigger/ignore/review) │
|
|
64
|
+
│ - 用户反馈记录 │
|
|
65
|
+
└─────────────────────────────────────────────────────────────┘
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
## ⚙️ 配置说明
|
|
69
|
+
|
|
70
|
+
### 配置文件位置
|
|
71
|
+
|
|
72
|
+
| 文件 | 位置 | 说明 |
|
|
73
|
+
|------|------|------|
|
|
74
|
+
| `trigger-config.json` | `$CARLOS_FLOW_HOME/trigger-config.json` | 自定义阈值与权重;不存在则用默认值 |
|
|
75
|
+
| `trigger-state.json` | `$CARLOS_FLOW_HOME/trigger-state.json` | 触发历史与学习数据 |
|
|
76
|
+
|
|
77
|
+
`CARLOS_FLOW_HOME` 未设置时,默认落在 `~/.carlos-flow`(与 `src/state.js` 的 `FLOW_HOME` 同一约定)。
|
|
78
|
+
配置与状态**不会**写入仓库目录,也**不会**污染 npm 包。
|
|
79
|
+
|
|
80
|
+
### 默认配置参数
|
|
81
|
+
|
|
82
|
+
```json
|
|
83
|
+
{
|
|
84
|
+
"baseTriggerLimit": 5,
|
|
85
|
+
"maxTriggerLimit": 15,
|
|
86
|
+
"sessionLengthCoeff": 0.5,
|
|
87
|
+
"complexityCoeff": 2,
|
|
88
|
+
"historyCoeff": 0.3,
|
|
89
|
+
"decayRate": 0.98,
|
|
90
|
+
|
|
69
91
|
"keywordWeights": {
|
|
70
92
|
"work": 3,
|
|
71
93
|
"flow": 3,
|
|
@@ -89,106 +111,273 @@ Carlos Flow 智能触发引擎是一个三层智能系统,能够自动感知
|
|
|
89
111
|
"留痕": 2,
|
|
90
112
|
"裁定": 2
|
|
91
113
|
},
|
|
92
|
-
|
|
93
|
-
"contextRelevanceWeight": 0.3,
|
|
94
|
-
"userIntentWeight": 0.2,
|
|
95
|
-
|
|
96
|
-
"triggerThreshold": 15,
|
|
97
|
-
"autoTriggerThreshold": 25,
|
|
98
|
-
"lowConfidenceThreshold": 10,
|
|
99
|
-
|
|
100
|
-
"feedbackLearningRate": 0.1,
|
|
101
|
-
"positiveFeedbackWeight": 1.5,
|
|
102
|
-
"negativeFeedbackWeight": 0.7,
|
|
103
|
-
|
|
104
|
-
"triggerWindowMinutes": 60,
|
|
105
|
-
"minTriggerIntervalSeconds": 300
|
|
106
|
-
}
|
|
107
|
-
```
|
|
108
|
-
|
|
109
|
-
### 参数说明
|
|
110
|
-
|
|
111
|
-
#### 动态上限参数
|
|
112
|
-
- `baseTriggerLimit`: 基础触发上限(0 会话时)
|
|
113
|
-
- `maxTriggerLimit`: 最大触发上限(防止过度触发)
|
|
114
|
-
- `sessionLengthCoeff`: 会话时长系数(每小时增加量)
|
|
115
|
-
- `complexityCoeff`: 任务复杂度系数(基于参数)
|
|
116
|
-
- `historyCoeff`: 历史触发频率系数
|
|
117
|
-
- `decayRate`: 历史触发衰减率(随时间减弱)
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
- `
|
|
126
|
-
- `
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
114
|
+
|
|
115
|
+
"contextRelevanceWeight": 0.3,
|
|
116
|
+
"userIntentWeight": 0.2,
|
|
117
|
+
|
|
118
|
+
"triggerThreshold": 15,
|
|
119
|
+
"autoTriggerThreshold": 25,
|
|
120
|
+
"lowConfidenceThreshold": 10,
|
|
121
|
+
|
|
122
|
+
"feedbackLearningRate": 0.1,
|
|
123
|
+
"positiveFeedbackWeight": 1.5,
|
|
124
|
+
"negativeFeedbackWeight": 0.7,
|
|
125
|
+
|
|
126
|
+
"triggerWindowMinutes": 60,
|
|
127
|
+
"minTriggerIntervalSeconds": 300
|
|
128
|
+
}
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
### 参数说明
|
|
132
|
+
|
|
133
|
+
#### 动态上限参数
|
|
134
|
+
- `baseTriggerLimit`: 基础触发上限(0 会话时)
|
|
135
|
+
- `maxTriggerLimit`: 最大触发上限(防止过度触发)
|
|
136
|
+
- `sessionLengthCoeff`: 会话时长系数(每小时增加量)
|
|
137
|
+
- `complexityCoeff`: 任务复杂度系数(基于参数)
|
|
138
|
+
- `historyCoeff`: 历史触发频率系数
|
|
139
|
+
- `decayRate`: 历史触发衰减率(随时间减弱)
|
|
140
|
+
|
|
141
|
+
> ⚠️ **公式里 `historyCoeff` 是减项(惩罚),不是加项。**
|
|
142
|
+
> 早期实现误写成加法 —— 触发越多上限反而越高,封顶逻辑自我抵消,
|
|
143
|
+
> 于是「窗口内次数达上限」分支永远不可达。已修正并有回归用例守护。
|
|
144
|
+
|
|
145
|
+
#### 评分参数
|
|
146
|
+
- `keywordWeights`: 关键词权重配置
|
|
147
|
+
- `contextRelevanceWeight`: 上下文相关性权重
|
|
148
|
+
- `userIntentWeight`: 用户意图识别权重
|
|
149
|
+
|
|
150
|
+
#### 决策阈值
|
|
151
|
+
- `triggerThreshold`: 最低触发阈值(15 分以上触发)
|
|
152
|
+
- `autoTriggerThreshold`: 自动触发阈值(25 分以上自动)
|
|
153
|
+
- `lowConfidenceThreshold`: 低置信度阈值(低于此忽略)
|
|
154
|
+
|
|
155
|
+
---
|
|
156
|
+
|
|
157
|
+
## 🧮 评分公式(完整推导)
|
|
158
|
+
|
|
159
|
+
### 动态上限
|
|
160
|
+
|
|
161
|
+
```
|
|
162
|
+
rawLimit = baseTriggerLimit
|
|
163
|
+
+ (sessionAgeHours × sessionLengthCoeff)
|
|
164
|
+
+ (sessionComplexity × complexityCoeff)
|
|
165
|
+
- (triggersInWindow × historyCoeff)
|
|
166
|
+
|
|
167
|
+
dynamicLimit = clamp(floor(rawLimit), 1, maxTriggerLimit)
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
**示例**(会话 2 小时、复杂度 1.5、窗口内已触发 3 次):
|
|
171
|
+
|
|
172
|
+
```
|
|
173
|
+
rawLimit = 5 + (2 × 0.5) + (1.5 × 2) - (3 × 0.3)
|
|
174
|
+
= 5 + 1 + 3 - 0.9
|
|
175
|
+
= 8.1 → floor = 8
|
|
176
|
+
dynamicLimit = min(8, 15) = 8
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
### 三维评分
|
|
180
|
+
|
|
181
|
+
```
|
|
182
|
+
keywordScore = min(Σ(命中词权重) × 5, 50) // 关键词维度,满分 50
|
|
183
|
+
contextScore = min(Σ(命中语境词) × 3 × complexity, 30) // 上下文维度,满分 30
|
|
184
|
+
intentScore = min(Σ(命中意图类型) × 20, 20) // 意图维度,满分 20
|
|
185
|
+
|
|
186
|
+
totalScore = round(
|
|
187
|
+
keywordScore × (1 - contextRelevanceWeight - userIntentWeight)
|
|
188
|
+
+ contextScore × contextRelevanceWeight
|
|
189
|
+
+ intentScore × userIntentWeight
|
|
190
|
+
)
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
默认权重(`contextRelevanceWeight=0.3`, `userIntentWeight=0.2`)下:
|
|
194
|
+
|
|
195
|
+
```
|
|
196
|
+
totalScore = keywordScore × 0.5 + contextScore × 0.3 + intentScore × 0.2
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
**理论满分**:`(50 × 0.5) + (30 × 0.3) + (20 × 0.2) = 25 + 9 + 4 = 38`
|
|
200
|
+
|
|
201
|
+
> 这就是 README 里说的「加权后满分 **38**」—— 它不是拍脑袋的常数,而是三个维度的加权上限。
|
|
202
|
+
|
|
203
|
+
### 置信度
|
|
204
|
+
|
|
205
|
+
| 命中总数(关键词 + 语境 + 意图类型) | 置信度 |
|
|
206
|
+
|-----------------------------------|-------|
|
|
207
|
+
| 0 | 0.3 |
|
|
208
|
+
| 1 ~ 2 | 0.6 |
|
|
209
|
+
| ≥ 3 | 0.9 |
|
|
210
|
+
|
|
211
|
+
### 决策
|
|
212
|
+
|
|
213
|
+
```
|
|
214
|
+
effectiveThreshold = max(1, threshold + feedbackAdjustment)
|
|
215
|
+
|
|
216
|
+
threshold = (score ≥ autoTriggerThreshold && confidence ≥ 0.8)
|
|
217
|
+
? autoTriggerThreshold // 25
|
|
218
|
+
: triggerThreshold // 15
|
|
219
|
+
|
|
220
|
+
decision:
|
|
221
|
+
限流(间隔不足 / 窗口内超上限) → throttled
|
|
222
|
+
score ≥ effectiveThreshold → trigger
|
|
223
|
+
score < lowConfidenceThreshold(10) → ignore
|
|
224
|
+
否则 → review
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
---
|
|
228
|
+
|
|
229
|
+
## 🔀 配置合并语义(重要)
|
|
230
|
+
|
|
231
|
+
配置加载**不是**简单的 `{ ...DEFAULT, ...loaded }`。字段分三类处理:
|
|
232
|
+
|
|
233
|
+
| 字段类型 | 语义 | 例子 |
|
|
234
|
+
|---------|------|------|
|
|
235
|
+
| **对象** | **合并**(用户覆盖同名默认项,其余默认项保留) | `keywordWeights` |
|
|
236
|
+
| **数组** | **追加去重**(扩展,不是替换) | `readOnlyIntentWords` / `mutatingActionWords` |
|
|
237
|
+
| **标量** | 覆盖 | 阈值、权重、系数 |
|
|
238
|
+
|
|
239
|
+
### 为什么必须这样
|
|
240
|
+
|
|
241
|
+
早期实现是**浅合并**。后果:
|
|
242
|
+
|
|
243
|
+
```json
|
|
244
|
+
{ "keywordWeights": { "评审": 5 } }
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
用户只想加一个词,结果**整个默认词表被丢掉** —— 包括内置的中文流程词。
|
|
248
|
+
于是「我只是加一个自定义词」反而让所有默认词失效,中文场景重新变回 0 分。
|
|
249
|
+
|
|
250
|
+
### 类型不合法时的兜底
|
|
251
|
+
|
|
252
|
+
若用户写 `"keywordWeights": null` 或 `"keywordWeights": [1,2]`:
|
|
253
|
+
|
|
254
|
+
- 浅合并会把非法值带进 `config.keywordWeights`
|
|
255
|
+
- `buildKeywordIndex()` 的 `Object.entries(null)` 抛 TypeError
|
|
256
|
+
- 触发引擎在该进程内**每次调用都失败**(客户端 catch 掉 → **静默失去自动触发**)
|
|
257
|
+
|
|
258
|
+
现在:类型不对就**丢弃用户值 + 回退默认表 + 打印警告**,
|
|
259
|
+
并且在合并后再兜一次底。
|
|
260
|
+
|
|
261
|
+
```json
|
|
262
|
+
{ "readOnlyIntentWords": "not-array" }
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
→ 警告 + 回退默认词表,引擎正常工作。
|
|
266
|
+
|
|
267
|
+
### 非法 JSON
|
|
268
|
+
|
|
269
|
+
配置文件损坏时 → 警告 + 全量回退默认配置,**引擎不崩**。
|
|
270
|
+
|
|
271
|
+
---
|
|
272
|
+
|
|
273
|
+
## 🔁 激活闸门时序(防假闭环)
|
|
274
|
+
|
|
275
|
+
自动触发**不等于**直接放行。完整时序:
|
|
276
|
+
|
|
277
|
+
```mermaid
|
|
278
|
+
sequenceDiagram
|
|
279
|
+
participant U as 用户
|
|
280
|
+
participant T as 触发引擎
|
|
281
|
+
participant S as MCP Server
|
|
282
|
+
|
|
283
|
+
U->>T: 用户消息
|
|
284
|
+
T->>T: L1 上限 → L2 评分 → L3 决策
|
|
285
|
+
alt decision = trigger
|
|
286
|
+
T->>S: flow_add_user_msg(写用户原话)
|
|
287
|
+
Note over S: quote 锚点的唯一数据源
|
|
288
|
+
T->>S: flow_submit_requirement (activation: true)
|
|
289
|
+
Note over S: 提交 read_only 占位卡<br/>会话进入已留痕门禁态
|
|
290
|
+
S->>S: activation_pending = [scope, acceptance, verify.cmd]
|
|
291
|
+
T-->>U: 提示补齐字段
|
|
292
|
+
U->>S: flow_submit_requirement(完整卡)
|
|
293
|
+
S->>S: activation_pending = [](闸门放行)
|
|
294
|
+
else decision = review / ignore / throttled
|
|
295
|
+
T-->>U: 如实返回评分与决策,不动作
|
|
296
|
+
end
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
### 闸门期间被拒绝的操作
|
|
300
|
+
|
|
301
|
+
| 操作 | 拒绝原因 |
|
|
302
|
+
|------|---------|
|
|
303
|
+
| `flow_claim` | 激活占位卡尚未补齐(待补:scope、acceptance、verify.cmd) |
|
|
304
|
+
| `flow_dispatch` | 同上 |
|
|
305
|
+
| `flow_verdict` | 同上 —— **防未执行就记 PASS 的假闭环** |
|
|
306
|
+
|
|
307
|
+
### 关键安全约束
|
|
308
|
+
|
|
309
|
+
1. **会话已有任务卡时自动激活会跳过开卡** —— 不覆盖用户已有任务
|
|
310
|
+
2. **自动激活只负责「留痕 + 进入门禁」** —— 绝不代替 Agent 决定改哪些文件
|
|
311
|
+
3. **普通卡不上闸门** —— 未标 `activation` 且该会话从未被激活过的普通卡片,
|
|
312
|
+
`activation_pending` 保持为空(`read_only` 档只需 `goal` + `quote`,
|
|
313
|
+
否则会误伤 T1 只读调研场景)
|
|
314
|
+
4. **待补项由服务端从卡片内容派生** —— 不是硬编码三项,而是根据当前卡片实际缺什么计算
|
|
315
|
+
|
|
316
|
+
---
|
|
317
|
+
|
|
318
|
+
## 🚀 使用方式
|
|
319
|
+
|
|
320
|
+
### 1. 在 `carlos.js` 中使用
|
|
321
|
+
|
|
322
|
+
智能触发引擎已集成到 `carlos.js` 客户端中。调用时自动执行触发检查:
|
|
323
|
+
|
|
324
|
+
```bash
|
|
325
|
+
node carlos.js flow_dispatch {"sessionId":"default"}
|
|
326
|
+
```
|
|
327
|
+
|
|
328
|
+
在调用 MCP 工具之前,引擎会检查用户意图并可能自动触发工作流。
|
|
329
|
+
|
|
330
|
+
### 2. 独立使用触发引擎
|
|
331
|
+
|
|
332
|
+
在 Node.js 项目中直接使用:
|
|
333
|
+
|
|
334
|
+
```javascript
|
|
335
|
+
import TriggerEngine from './src/trigger.js';
|
|
336
|
+
|
|
337
|
+
// 创建引擎实例
|
|
338
|
+
const engine = TriggerEngine.create('session-123');
|
|
339
|
+
|
|
340
|
+
// 检查是否触发
|
|
341
|
+
const result = engine.shouldTrigger('运行 dispatch 工作流', {
|
|
342
|
+
sessionId: 'session-123',
|
|
343
|
+
complexity: 1.2
|
|
344
|
+
});
|
|
345
|
+
|
|
346
|
+
if (result.shouldTrigger) {
|
|
347
|
+
console.log('✅ 触发工作流!');
|
|
348
|
+
// 执行后续流程...
|
|
349
|
+
} else {
|
|
350
|
+
console.log('❌ 暂不触发');
|
|
351
|
+
}
|
|
352
|
+
|
|
353
|
+
// 记录用户反馈
|
|
354
|
+
engine.recordFeedback('positive'); // 用户接受
|
|
355
|
+
engine.recordFeedback('negative'); // 用户拒绝
|
|
356
|
+
```
|
|
357
|
+
|
|
358
|
+
### 3. 通过 CLI 客户端集成
|
|
359
|
+
|
|
360
|
+
触发引擎已集成到 `client/carlos.js`:每次调用 MCP 工具前先做一次触发检查。
|
|
361
|
+
命中后**不只是打印日志**——它会执行[激活流程](#🔁-激活机制判断--动作),真正把会话推进门禁态。
|
|
362
|
+
|
|
363
|
+
```bash
|
|
364
|
+
# triggerMessage 传入真实用户原话(也可用环境变量 CARLOS_TRIGGER_MESSAGE)
|
|
365
|
+
node client/carlos.js flow_status '{"sessionId":"my-task","triggerMessage":"run dispatch workflow"}'
|
|
366
|
+
```
|
|
367
|
+
|
|
368
|
+
stderr 输出:
|
|
369
|
+
```
|
|
370
|
+
[Carlos Trigger] 判定触发:评分 37 · 置信度 0.9
|
|
371
|
+
[Carlos Trigger] 已执行激活步骤:flow_add_user_msg(写入用户原话,作为任务卡 quote 锚点校验的数据源)
|
|
372
|
+
[Carlos Trigger] 已执行激活步骤:flow_submit_requirement(开卡:将会话置为已留痕状态,审计链记录 activation 事件)
|
|
373
|
+
|
|
374
|
+
【Carlos 触发引擎已激活工作流】
|
|
375
|
+
…
|
|
376
|
+
```
|
|
377
|
+
|
|
378
|
+
> ⚠️ **`triggerMessage` 必须显式传入,否则完全不启用自动触发。**
|
|
379
|
+
>
|
|
380
|
+
> - `triggerMessage` 是**客户端专用字段**,不会被透传给 MCP 工具(`complexity` 同样剥离);
|
|
192
381
|
> - 默认词表**中英文都有**:英文 `work` / `flow` / `carlos` / `dispatch` / `trigger` / `start` / `run` / `execute`,
|
|
193
382
|
> 中文 `工作流` / `门禁` / `任务卡` / `派发` / `子代理` / `流程` / `触发` / `执行` / `调度` / `审计` / `复核` / `留痕` / `裁定`
|
|
194
383
|
> (上下文表另有 `executor` / `auditor`;意图表另有 `auto` / `process` / `monitor` 等)。
|
|
@@ -196,10 +385,10 @@ stderr 输出:
|
|
|
196
385
|
> 所以「走门禁流程」会触发,而「给接口加个参数校验」不会误触发。
|
|
197
386
|
> - 需要自定义时用 `CARLOS_FLOW_HOME/trigger-config.json`:里面的 `keywordWeights` 是
|
|
198
387
|
> **追加/覆盖同名项**(默认词表保留),`readOnlyIntentWords` / `mutatingActionWords` 是**追加去重**;
|
|
199
|
-
> - 早先版本的兜底项是「工具名 + 参数 JSON」,会造成**自伤**(参数含触发词 → 自己开占位卡 →
|
|
200
|
-
> 同一次调用的 `flow_dispatch` 反被闸门拒绝)与**锚点污染**(写入的「用户原话」是命令行文本 →
|
|
201
|
-
> Agent 用真实原话重提卡时 quote 锚点校验失败 → 补齐流程卡死)。现已改为**不传即不触发**。
|
|
202
|
-
|
|
388
|
+
> - 早先版本的兜底项是「工具名 + 参数 JSON」,会造成**自伤**(参数含触发词 → 自己开占位卡 →
|
|
389
|
+
> 同一次调用的 `flow_dispatch` 反被闸门拒绝)与**锚点污染**(写入的「用户原话」是命令行文本 →
|
|
390
|
+
> Agent 用真实原话重提卡时 quote 锚点校验失败 → 补齐流程卡死)。现已改为**不传即不触发**。
|
|
391
|
+
|
|
203
392
|
> **当前定位**:触发引擎是**库级能力**(`src/trigger.js`),但它**已经**作为第 15 个 MCP 工具
|
|
204
393
|
> **`flow_trigger_check`** 暴露给宿主 Agent —— 调用它即可获得与命令行客户端完全一致的评分与激活行为:
|
|
205
394
|
> 达标时**实际完成激活**(写入用户原话 + 开占位卡 → 会话进入门禁态),未达标只如实返回评分。
|
|
@@ -208,385 +397,387 @@ stderr 输出:
|
|
|
208
397
|
> 1. **MCP 工具** —— 调 `flow_trigger_check`(任何 MCP 宿主均可)
|
|
209
398
|
> 2. **OpenCode 插件** —— `plugins/carlos-flow-trigger.js` 监听 `chat.message` 自动调用(opencode 版专有)
|
|
210
399
|
> 3. **命令行客户端** —— `node client/carlos.js ... --triggerMessage "..."`
|
|
211
|
-
|
|
212
|
-
## 📊 评分计算详解
|
|
213
|
-
|
|
214
|
-
### 总分计算公式
|
|
215
|
-
|
|
216
|
-
```
|
|
217
|
-
总分 = 关键词分 × 0.5 + 上下文分 × 0.3 + 意图分 × 0.2
|
|
218
|
-
```
|
|
219
|
-
|
|
220
|
-
### 各维度分数范围
|
|
221
|
-
|
|
222
|
-
| 维度 | 基础分数 | 权重 | 贡献上限 |
|
|
223
|
-
|------|----------|------|----------|
|
|
224
|
-
| 关键词匹配 | 0-50 | 0.5 | 25 |
|
|
225
|
-
| 上下文相关性 | 0-30 | 0.3 | 9 |
|
|
226
|
-
| 用户意图识别 | 0-20 | 0.2 | 4 |
|
|
227
|
-
| **总计** | - | - | **38** |
|
|
228
|
-
|
|
229
|
-
### 决策逻辑(与 `src/trigger.js` 实现逐行对应)
|
|
230
|
-
|
|
231
|
-
```javascript
|
|
232
|
-
// 1) 先算评分(即使随后被限流,评分与置信度也要如实返回)
|
|
233
|
-
const score = scorer.calculateImpulseScore(message, context, historyCount).score;
|
|
234
|
-
|
|
235
|
-
// 2) 动态上限 / 最短间隔检查
|
|
236
|
-
if (!canTrigger().can) {
|
|
237
|
-
return { decision: 'throttled', score, confidence, breakdown }; // 限流
|
|
238
|
-
}
|
|
239
|
-
|
|
240
|
-
// 3) 阈值选择:高置信度时用自动阈值,否则用普通阈值
|
|
241
|
-
const threshold = (score >= autoTriggerThreshold && confidence >= 0.8)
|
|
242
|
-
? autoTriggerThreshold
|
|
243
|
-
: triggerThreshold;
|
|
244
|
-
|
|
245
|
-
// 4) 叠加反馈学习偏移(负反馈多 → 更保守)
|
|
246
|
-
const effectiveThreshold = Math.max(1, threshold + feedbackAdjustment);
|
|
247
|
-
|
|
248
|
-
// 5) 判定
|
|
249
|
-
if (score >= effectiveThreshold) decision = 'trigger'; // ✅ 达标,进入激活流程
|
|
250
|
-
else if (score < lowConfidenceThreshold) decision = 'ignore'; // ❌ 低于 10 分,忽略
|
|
251
|
-
else decision = 'review'; // ⚠️ 临界,建议手动启动
|
|
252
|
-
```
|
|
253
|
-
|
|
254
|
-
| 决策 | 含义 | 是否动作 |
|
|
255
|
-
|------|------|---------|
|
|
256
|
-
| `trigger` | 评分达标 | **进入激活流程**(自动档:评分 ≥ 25 且置信度 ≥ 0.8) |
|
|
257
|
-
| `review` | 临界区间 | 只输出建议与补全指引,**不执行任何 MCP 动作** |
|
|
258
|
-
| `ignore` | 低于 `lowConfidenceThreshold` | 无动作 |
|
|
259
|
-
| `throttled` | 被动态上限或最短间隔拦下 | 无动作,但**如实返回真实评分与置信度** |
|
|
260
|
-
|
|
261
|
-
> ⚠️ 限流时依然返回真实的 `score` / `confidence` / `breakdown`,不会丢成 0,也不会假装“未评分”。
|
|
262
|
-
|
|
263
|
-
### 置信度口径
|
|
264
|
-
|
|
265
|
-
`confidence` 由**命中项数量**决定(`calculateConfidence()`):
|
|
266
|
-
|
|
267
|
-
| 命中项数 | confidence | 含义 |
|
|
268
|
-
|---------|-----------|------|
|
|
269
|
-
| 0 | **0.3** | 没命中任何词/意图 —— 低置信度 |
|
|
270
|
-
| 1 ~ 2 | **0.6** | 中等置信度 |
|
|
271
|
-
| ≥ 3 | **0.9** | 高置信度(可走自动档) |
|
|
272
|
-
|
|
273
|
-
命中项 = 命中的关键词数 + 命中的上下文词数 + 意图类型是否非 `generic`。
|
|
274
|
-
|
|
275
|
-
> 📌 已知口径特性:关键词表与上下文表有重叠(`work` / `flow` / `dispatch` 同时出现在两张表里),
|
|
276
|
-
> 同一个词会被计入两次,因此 `confidence` 偏乐观。这是**已知并接受的现状**,
|
|
277
|
-
> 真正决定是否触发的是**加权总分**,不是 confidence。
|
|
278
|
-
|
|
279
|
-
---
|
|
280
|
-
|
|
281
|
-
## 🔁 激活机制(判断 → 动作)
|
|
282
|
-
|
|
283
|
-
决策本身只是判断。**激活机制**负责把判断变成**真实执行的门禁动作**。
|
|
284
|
-
|
|
285
|
-
### 三个阶段
|
|
286
|
-
|
|
287
|
-
| 阶段 | 组件 | 产物 |
|
|
288
|
-
|------|------|------|
|
|
289
|
-
| **判断** | `TriggerDecisionEngine.shouldTrigger()` | `decision` + `score` + `confidence` + `breakdown` |
|
|
290
|
-
| **翻译** | `TriggerDecisionEngine.buildActivationPlan()` | 可执行的 MCP 动作序列(每步带 `auto` 标记) |
|
|
291
|
-
| **激活** | `client/carlos.js` 逐步执行 | 会话进入“已留痕”门禁态 |
|
|
292
|
-
|
|
293
|
-
### 激活计划长什么样
|
|
294
|
-
|
|
295
|
-
```javascript
|
|
296
|
-
const result = engine.shouldTrigger('run dispatch workflow', { sessionId: 'my-task' });
|
|
297
|
-
|
|
298
|
-
result.activationPlan = {
|
|
299
|
-
activated: true,
|
|
300
|
-
decision: 'trigger',
|
|
301
|
-
score: 38,
|
|
302
|
-
confidence: 0.9,
|
|
303
|
-
matchedKeywords: ['work', 'flow', 'dispatch', 'run'],
|
|
304
|
-
goal: '执行 Carlos 工作流任务:run dispatch workflow(命中:work, flow, dispatch, run)',
|
|
305
|
-
steps: [
|
|
306
|
-
{ tool: 'flow_add_user_msg', auto: true }, // 自动:留痕用户原话
|
|
307
|
-
{ tool: 'flow_submit_requirement', auto: true }, // 自动:提交 read_only 占位卡
|
|
308
|
-
{ tool: 'flow_submit_requirement', auto: false }, // 引导:补齐字段后重新提交
|
|
309
|
-
// needsFill 不是固定三项:待补字段由**服务端从当前卡片内容派生**
|
|
310
|
-
// (scope / acceptance / verify.cmd 缺哪个就锁哪个,都齐了才解闸)。
|
|
311
|
-
needsFill: '<由服务端派生:scope / acceptance / verify.cmd 中当前缺失的项>' },
|
|
312
|
-
],
|
|
313
|
-
pendingFields: '<由服务端从卡片内容派生,非固定三项>',
|
|
314
|
-
prompt: '【Carlos 触发引擎已激活工作流】…',
|
|
315
|
-
};
|
|
316
|
-
```
|
|
317
|
-
|
|
318
|
-
### 激活的四个实际动作
|
|
319
|
-
|
|
320
|
-
1. **留痕用户原话** — `flow_add_user_msg`
|
|
321
|
-
把用户原话写进会话消息文件。它是任务卡 `quote` 锚点校验的**唯一数据源**,必须先于开卡。
|
|
322
|
-
|
|
323
|
-
2. **提交占位卡** — `flow_submit_requirement`(`activation: true`)
|
|
324
|
-
以 `read_only` 档提交(只要求 `goal` + `quote`),**会话进入已留痕门禁态**,审计链记录激活事件。
|
|
325
|
-
|
|
326
|
-
3. **闸门生效** — `activation_pending`
|
|
327
|
-
状态里记下待补齐字段 `scope` / `acceptance` / `verify.cmd`。
|
|
328
|
-
在补齐之前,以下三个工具 **一律拒绝**:
|
|
329
|
-
|
|
330
|
-
| 工具 | 拒绝原因 |
|
|
331
|
-
|------|---------|
|
|
332
|
-
| `flow_claim` | 不能拿一张没补齐的卡去领派发名额 |
|
|
333
|
-
| `flow_dispatch` | 不能拿一张没补齐的卡去派发执行 |
|
|
334
|
-
| `flow_verdict` | **防假闭环**——未经派发**且未验证通过**,不能直接记 PASS(`DIRECTION` / `LOCAL` 不受此限) |
|
|
335
|
-
|
|
336
|
-
```
|
|
337
|
-
ERROR: 激活占位卡尚未补齐(待补:scope、acceptance、verify.cmd)。
|
|
338
|
-
请先补齐后重新调用 flow_submit_requirement,再来领取派发名额。
|
|
339
|
-
```
|
|
340
|
-
|
|
341
|
-
4. **补齐后放行** — 重新提交完整卡
|
|
342
|
-
Agent 补齐字段后重新调用 `flow_submit_requirement`(**不带** `activation`),
|
|
343
|
-
`activation_pending` 被清空,门禁解除,可以正常 `flow_claim` / `flow_dispatch`。
|
|
344
|
-
|
|
345
|
-
### 安全约束
|
|
346
|
-
|
|
347
|
-
| 约束 | 行为 |
|
|
348
|
-
|------|------|
|
|
349
|
-
| 会话**已有任务卡** | 跳过自动开卡,**不覆盖用户已有任务** |
|
|
350
|
-
| 占位卡**不许记 PASS** | `flow_verdict` 在字段未补齐时拒绝,堵住「未执行、未验证、却直接完成」的假闭环 |
|
|
351
|
-
| 自动激活**不决定改哪些文件** | 只负责“留痕 + 进入门禁”,`scope` 必须由 Agent 确认 |
|
|
352
|
-
| 目标描述是**推断值** | `goal` 由关键词推导,**标记为占位**,需与用户确认后改写 |
|
|
353
|
-
| `manual` 档 | 只输出建议与补全指引,**不执行任何 MCP 动作** |
|
|
354
|
-
|
|
355
|
-
### 手动使用激活计划
|
|
356
|
-
|
|
357
|
-
```javascript
|
|
358
|
-
const plan = result.activationPlan;
|
|
359
|
-
for (const step of plan.steps) {
|
|
360
|
-
if (!step.auto) continue; // 只执行参数完整的步骤
|
|
361
|
-
await callMCP('tools/call', { name: step.tool, arguments: step.args });
|
|
362
|
-
}
|
|
363
|
-
// 然后把 plan.prompt 交给 Agent,让它补齐字段
|
|
364
|
-
```
|
|
365
|
-
|
|
366
|
-
---
|
|
367
|
-
|
|
368
|
-
## 🔄 动态上限计算
|
|
369
|
-
|
|
370
|
-
### 公式
|
|
371
|
-
|
|
372
|
-
```
|
|
373
|
-
动态上限 = clamp(
|
|
374
|
-
baseTriggerLimit +
|
|
375
|
-
(会话时长小时数 × sessionLengthCoeff) +
|
|
376
|
-
(任务复杂度 × complexityCoeff) -
|
|
377
|
-
(窗口内触发次数 × historyCoeff),
|
|
378
|
-
1, maxTriggerLimit
|
|
379
|
-
)
|
|
380
|
-
```
|
|
381
|
-
|
|
382
|
-
> **设计要点**:会话越长、任务越复杂 → 上限越高(允许更多触发);
|
|
383
|
-
> 近期触发越频繁 → 上限越低(收敛打扰)。
|
|
384
|
-
> 历史项是**惩罚项**而非增益项 —— 若为增益,触发次数会把上限反向抬高,封顶逻辑将自我抵消而永不生效。
|
|
385
|
-
|
|
386
|
-
### 示例
|
|
387
|
-
|
|
388
|
-
- 新会话(0 小时),复杂度 1.0,无历史 → 上限 = 5 + 0 + 2 - 0 = **7**
|
|
389
|
-
- 2 小时会话,复杂度 1.2,窗口内 3 次触发 → 上限 = 5 + 1 + 2.4 - 0.9 = **7**
|
|
390
|
-
- 5 小时会话,复杂度 1.5,窗口内 0 次触发 → 上限 = 5 + 2.5 + 3 = **10**
|
|
391
|
-
|
|
392
|
-
### 上限判定
|
|
393
|
-
|
|
394
|
-
```
|
|
395
|
-
窗口内触发次数 = countTriggersInWindow() // 原始计数
|
|
396
|
-
if (窗口内触发次数 >= 动态上限) → 拒绝触发
|
|
397
|
-
```
|
|
398
|
-
|
|
399
|
-
> 注:判定用的是**原始次数**(`countTriggersInWindow()`),不是衰减加权均值。
|
|
400
|
-
> 上限公式里的历史项同样用原始次数×`historyCoeff`(惩罚项,触发越多上限越低)。
|
|
401
|
-
|
|
402
|
-
> ⚠️ **窗口长度必须与最短间隔匹配**:`minTriggerIntervalSeconds = 300`(5 分钟)时,
|
|
403
|
-
> 若 `triggerWindowMinutes` 只有 15 分钟,窗口内最多只能触发 3 次,
|
|
404
|
-
> 而上限至少是 5+1=6 → 「次数达上限」分支**永远不可达**,实际只有 5 分钟冷却在起作用。
|
|
405
|
-
> 因此默认 `triggerWindowMinutes` 已改为 **60 分钟**(1 小时内最多 12 次,上限 6~15 才有意义)。
|
|
406
|
-
|
|
407
|
-
## 📈 用户反馈学习
|
|
408
|
-
|
|
409
|
-
系统**持久化**记录用户反馈(存在会话状态文件里,进程退出也不丢),
|
|
410
|
-
并让反馈**真正影响触发阈值**:
|
|
411
|
-
|
|
412
|
-
```javascript
|
|
413
|
-
// 用户接受触发
|
|
414
|
-
engine.recordFeedback('positive');
|
|
415
|
-
|
|
416
|
-
// 用户拒绝触发
|
|
417
|
-
engine.recordFeedback('negative');
|
|
418
|
-
// → { ok: true, feedback: { positive: 0, negative: 1 }, thresholdAdjustment: 1 }
|
|
419
|
-
```
|
|
420
|
-
|
|
421
|
-
| 机制 | 说明 |
|
|
422
|
-
|------|------|
|
|
423
|
-
| **即时调整** | `getFeedbackThresholdAdjustment()` 按当前会话正/负反馈比例算出阈值偏移,负反馈越多偏移越大(更保守) |
|
|
424
|
-
| **持久学习** | 每累积 `feedbackLearningCycle`(默认 10)条反馈自动调用 `updateFeedbackWeights()`,把学习结果写入 `trigger-config.json` 的 `feedbackThresholdOffset` |
|
|
425
|
-
| **生效位置** | 偏移量加在决策阈值上:`effectiveThreshold = threshold + 即时偏移 + 持久偏移`,最低为 1 |
|
|
426
|
-
|
|
427
|
-
```javascript
|
|
428
|
-
// 手动触发一次学习(可选,recordFeedback 已会自动按周期触发)
|
|
429
|
-
engine.updateFeedbackWeights();
|
|
430
|
-
// → { ok: true, thresholdOffset: 1, positive: 0, negative: 10 }
|
|
431
|
-
```
|
|
432
|
-
|
|
433
|
-
> ⚠️ 早期版本的反馈只写在**进程内 Map** 里、`updateFeedbackWeights()` 也**没有任何调用点**,
|
|
434
|
-
> 属于「文档写了但功能不存在」。现在已改为持久化 + 自动触发 + 真正影响阈值。
|
|
435
|
-
|
|
436
|
-
## 🎯 最佳实践
|
|
437
|
-
|
|
438
|
-
### 1. 响应式设计
|
|
439
|
-
|
|
440
|
-
- 高频触发场景:调高 `maxTriggerLimit`
|
|
441
|
-
- 低频场景:降低 `triggerThreshold` 优化灵敏度
|
|
442
|
-
- 生产环境:设置 `minTriggerIntervalSeconds >= 300`
|
|
443
|
-
|
|
444
|
-
### 2. 关键词优化
|
|
445
|
-
|
|
446
|
-
根据实际业务调整 `keywordWeights`:
|
|
447
|
-
|
|
448
|
-
```json
|
|
449
|
-
"keywordWeights": {
|
|
450
|
-
"deploy": 4,
|
|
451
|
-
"test": 3,
|
|
452
|
-
"check": 2,
|
|
453
|
-
"run": 1
|
|
454
|
-
}
|
|
455
|
-
```
|
|
456
|
-
|
|
457
|
-
### 3. 上下文感知
|
|
458
|
-
|
|
459
|
-
为不同任务类型设置不同复杂度参数:
|
|
460
|
-
|
|
461
|
-
```bash
|
|
462
|
-
# 高风险任务
|
|
463
|
-
node carlos.js flow_dispatch --complexity 1.5
|
|
464
|
-
|
|
465
|
-
# 常规任务
|
|
466
|
-
node carlos.js flow_dispatch --complexity 1.0
|
|
467
|
-
```
|
|
468
|
-
|
|
469
|
-
## 🔧 高级功能
|
|
470
|
-
|
|
471
|
-
### 自定义评分算法
|
|
472
|
-
|
|
473
|
-
```javascript
|
|
474
|
-
class CustomScorer extends TriggerScorer {
|
|
475
|
-
calculateKeywordScore(message) {
|
|
476
|
-
// 覆盖关键词匹配逻辑
|
|
477
|
-
// ...
|
|
478
|
-
}
|
|
479
|
-
}
|
|
480
|
-
|
|
481
|
-
// 使用自定义打分器
|
|
482
|
-
const customEngine = new TriggerDecisionEngine(
|
|
483
|
-
new DynamicTriggerManager(),
|
|
484
|
-
new CustomScorer()
|
|
485
|
-
);
|
|
486
|
-
```
|
|
487
|
-
|
|
488
|
-
### 持久化状态
|
|
489
|
-
|
|
490
|
-
```javascript
|
|
491
|
-
const state = TriggerState.load('session-id');
|
|
492
|
-
// 修改状态
|
|
493
|
-
state.triggerHistory = [...];
|
|
494
|
-
state.save(); // 持久化到 disk
|
|
495
|
-
```
|
|
496
|
-
|
|
497
|
-
## 🐛 故障排查
|
|
498
|
-
|
|
499
|
-
### 问题 1: 触发不灵敏
|
|
500
|
-
|
|
501
|
-
**症状**: 明显意图但评分低于阈值
|
|
502
|
-
|
|
503
|
-
**解决**:
|
|
504
|
-
1. 检查关键词权重配置
|
|
505
|
-
2. 降低 `triggerThreshold`
|
|
506
|
-
3. 增加 `contextRelevanceWeight`
|
|
507
|
-
|
|
508
|
-
### 问题 2: 触发过于频繁
|
|
509
|
-
|
|
510
|
-
**症状**: 短时间内多次触发
|
|
511
|
-
|
|
512
|
-
**解决**:
|
|
513
|
-
1. 调高 `minTriggerIntervalSeconds`
|
|
514
|
-
2. 调低 `sessionLengthCoeff`
|
|
515
|
-
3. 调高 `historyCoeff`(它是**惩罚项**,调高会更快收紧上限)
|
|
516
|
-
4. 调低 `baseTriggerLimit`
|
|
517
|
-
|
|
518
|
-
### 问题 3: 评分总是 0
|
|
519
|
-
|
|
520
|
-
**症状**: 所有消息都匹配不到关键词
|
|
521
|
-
|
|
522
|
-
**解决**:
|
|
523
|
-
1. 检查消息是否包含配置关键词
|
|
524
|
-
2. 验证 `keywordWeights` 是否生效
|
|
525
|
-
3. 查看日志调试匹配过程
|
|
526
|
-
|
|
527
|
-
### 问题 4: 触发引擎没生效(客户端无任何提示)
|
|
528
|
-
|
|
529
|
-
**症状**: 调用 `client/carlos.js` 时看不到 `[Carlos Trigger]` 日志
|
|
530
|
-
|
|
531
|
-
**解决**:
|
|
532
|
-
1. 确认 `src/trigger.js` 存在且与 `client/carlos.js` 同版本
|
|
533
|
-
2. 确认客户端用的是**动态 import**(ESM 下 `require()` 不存在,会被 try/catch 静默吞掉)
|
|
534
|
-
3. 直接运行 `node src/trigger.js "你的消息"` 验证引擎本体
|
|
535
|
-
|
|
536
|
-
### 问题 5: 激活后 `flow_claim` / `flow_dispatch` 被拒
|
|
537
|
-
|
|
538
|
-
**症状**: `ERROR: 激活占位卡尚未补齐(待补:scope、acceptance、verify.cmd)`
|
|
539
|
-
|
|
540
|
-
**这不是 bug,是激活闸门在起作用**。自动激活只负责“留痕 + 进入门禁”,
|
|
541
|
-
不知道该改哪些文件,所以必须先补齐字段:
|
|
542
|
-
|
|
543
|
-
1. 确认目标描述(激活时自动推断的 `goal` 可能不准,需与用户确认后改写)
|
|
544
|
-
2. 补齐 `scope`(只准改动的文件)、`acceptance`(可判定的验收标准)、`verify.cmd`(验证命令)
|
|
545
|
-
3. **重新调用 `flow_submit_requirement`**(不要带 `activation` 参数)——这一步会清空 `activation_pending`
|
|
546
|
-
4. 再调用 `flow_claim` / `flow_dispatch`
|
|
547
|
-
|
|
548
|
-
查看当前待补字段:
|
|
549
|
-
|
|
550
|
-
```bash
|
|
551
|
-
node client/carlos.js flow_status '{"sessionId":"my-task"}'
|
|
552
|
-
# → "activation_pending": ["scope", "acceptance", "verify.cmd"]
|
|
553
|
-
```
|
|
554
|
-
|
|
555
|
-
### 问题 6: 激活了但派发一直被拒,且提示「待补:scope、acceptance、verify.cmd」
|
|
556
|
-
|
|
557
|
-
**症状**: `ERROR: 激活占位卡尚未补齐(待补:scope、acceptance、verify.cmd)`
|
|
558
|
-
|
|
559
|
-
**这是闸门在正常工作**,不是故障。必须**三项都补齐**才能解闸:
|
|
560
|
-
|
|
561
|
-
- `scope` —— 只准改动的文件(非空)
|
|
562
|
-
- `acceptance` —— 可判定的验收标准(非空)
|
|
563
|
-
- `verify.cmd` —— 验证命令(非空)
|
|
564
|
-
|
|
565
|
-
只补其中一项**不解闸**(`activation_pending` 会精确告诉你还缺哪几项)。
|
|
566
|
-
补齐后**重新调用 `flow_submit_requirement`**(不带 `activation` 参数)即解除。
|
|
567
|
-
|
|
568
|
-
### 问题 7: 一个会话的触发影响了另一个会话
|
|
569
|
-
|
|
570
|
-
**症状**: 明明是新会话,却提示“时间间隔不足”
|
|
571
|
-
|
|
572
|
-
**原因**: 早期版本所有会话共用一个触发状态文件(`trigger-state.json`),跨会话互相限流。
|
|
573
|
-
|
|
574
|
-
**现状**: 已修复——状态按 session 分文件存放在 `CARLOS_FLOW_HOME/trigger-state/<sessionId>.json`。
|
|
575
|
-
若仍遇到,请确认客户端与 `src/trigger.js` 版本一致(见问题 4)。
|
|
576
|
-
|
|
577
|
-
## 📚 相关资源
|
|
578
|
-
|
|
579
|
-
- [测试脚本](test/trigger-e2e.mjs) - E2E 测试套件(
|
|
580
|
-
- [变异测试](scripts/mutation-check.mjs) - 注入退化验证测试套件真的能抓住(13 类变异)
|
|
581
|
-
- [核心代码](src/trigger.js) - 触发引擎实现
|
|
582
|
-
- [集成示例](client/carlos.js) - 客户端集成代码
|
|
583
|
-
- [
|
|
584
|
-
|
|
585
|
-
|
|
586
|
-
|
|
587
|
-
|
|
588
|
-
|
|
589
|
-
|
|
590
|
-
|
|
591
|
-
|
|
592
|
-
|
|
400
|
+
|
|
401
|
+
## 📊 评分计算详解
|
|
402
|
+
|
|
403
|
+
### 总分计算公式
|
|
404
|
+
|
|
405
|
+
```
|
|
406
|
+
总分 = 关键词分 × 0.5 + 上下文分 × 0.3 + 意图分 × 0.2
|
|
407
|
+
```
|
|
408
|
+
|
|
409
|
+
### 各维度分数范围
|
|
410
|
+
|
|
411
|
+
| 维度 | 基础分数 | 权重 | 贡献上限 |
|
|
412
|
+
|------|----------|------|----------|
|
|
413
|
+
| 关键词匹配 | 0-50 | 0.5 | 25 |
|
|
414
|
+
| 上下文相关性 | 0-30 | 0.3 | 9 |
|
|
415
|
+
| 用户意图识别 | 0-20 | 0.2 | 4 |
|
|
416
|
+
| **总计** | - | - | **38** |
|
|
417
|
+
|
|
418
|
+
### 决策逻辑(与 `src/trigger.js` 实现逐行对应)
|
|
419
|
+
|
|
420
|
+
```javascript
|
|
421
|
+
// 1) 先算评分(即使随后被限流,评分与置信度也要如实返回)
|
|
422
|
+
const score = scorer.calculateImpulseScore(message, context, historyCount).score;
|
|
423
|
+
|
|
424
|
+
// 2) 动态上限 / 最短间隔检查
|
|
425
|
+
if (!canTrigger().can) {
|
|
426
|
+
return { decision: 'throttled', score, confidence, breakdown }; // 限流
|
|
427
|
+
}
|
|
428
|
+
|
|
429
|
+
// 3) 阈值选择:高置信度时用自动阈值,否则用普通阈值
|
|
430
|
+
const threshold = (score >= autoTriggerThreshold && confidence >= 0.8)
|
|
431
|
+
? autoTriggerThreshold
|
|
432
|
+
: triggerThreshold;
|
|
433
|
+
|
|
434
|
+
// 4) 叠加反馈学习偏移(负反馈多 → 更保守)
|
|
435
|
+
const effectiveThreshold = Math.max(1, threshold + feedbackAdjustment);
|
|
436
|
+
|
|
437
|
+
// 5) 判定
|
|
438
|
+
if (score >= effectiveThreshold) decision = 'trigger'; // ✅ 达标,进入激活流程
|
|
439
|
+
else if (score < lowConfidenceThreshold) decision = 'ignore'; // ❌ 低于 10 分,忽略
|
|
440
|
+
else decision = 'review'; // ⚠️ 临界,建议手动启动
|
|
441
|
+
```
|
|
442
|
+
|
|
443
|
+
| 决策 | 含义 | 是否动作 |
|
|
444
|
+
|------|------|---------|
|
|
445
|
+
| `trigger` | 评分达标 | **进入激活流程**(自动档:评分 ≥ 25 且置信度 ≥ 0.8) |
|
|
446
|
+
| `review` | 临界区间 | 只输出建议与补全指引,**不执行任何 MCP 动作** |
|
|
447
|
+
| `ignore` | 低于 `lowConfidenceThreshold` | 无动作 |
|
|
448
|
+
| `throttled` | 被动态上限或最短间隔拦下 | 无动作,但**如实返回真实评分与置信度** |
|
|
449
|
+
|
|
450
|
+
> ⚠️ 限流时依然返回真实的 `score` / `confidence` / `breakdown`,不会丢成 0,也不会假装“未评分”。
|
|
451
|
+
|
|
452
|
+
### 置信度口径
|
|
453
|
+
|
|
454
|
+
`confidence` 由**命中项数量**决定(`calculateConfidence()`):
|
|
455
|
+
|
|
456
|
+
| 命中项数 | confidence | 含义 |
|
|
457
|
+
|---------|-----------|------|
|
|
458
|
+
| 0 | **0.3** | 没命中任何词/意图 —— 低置信度 |
|
|
459
|
+
| 1 ~ 2 | **0.6** | 中等置信度 |
|
|
460
|
+
| ≥ 3 | **0.9** | 高置信度(可走自动档) |
|
|
461
|
+
|
|
462
|
+
命中项 = 命中的关键词数 + 命中的上下文词数 + 意图类型是否非 `generic`。
|
|
463
|
+
|
|
464
|
+
> 📌 已知口径特性:关键词表与上下文表有重叠(`work` / `flow` / `dispatch` 同时出现在两张表里),
|
|
465
|
+
> 同一个词会被计入两次,因此 `confidence` 偏乐观。这是**已知并接受的现状**,
|
|
466
|
+
> 真正决定是否触发的是**加权总分**,不是 confidence。
|
|
467
|
+
|
|
468
|
+
---
|
|
469
|
+
|
|
470
|
+
## 🔁 激活机制(判断 → 动作)
|
|
471
|
+
|
|
472
|
+
决策本身只是判断。**激活机制**负责把判断变成**真实执行的门禁动作**。
|
|
473
|
+
|
|
474
|
+
### 三个阶段
|
|
475
|
+
|
|
476
|
+
| 阶段 | 组件 | 产物 |
|
|
477
|
+
|------|------|------|
|
|
478
|
+
| **判断** | `TriggerDecisionEngine.shouldTrigger()` | `decision` + `score` + `confidence` + `breakdown` |
|
|
479
|
+
| **翻译** | `TriggerDecisionEngine.buildActivationPlan()` | 可执行的 MCP 动作序列(每步带 `auto` 标记) |
|
|
480
|
+
| **激活** | `client/carlos.js` 逐步执行 | 会话进入“已留痕”门禁态 |
|
|
481
|
+
|
|
482
|
+
### 激活计划长什么样
|
|
483
|
+
|
|
484
|
+
```javascript
|
|
485
|
+
const result = engine.shouldTrigger('run dispatch workflow', { sessionId: 'my-task' });
|
|
486
|
+
|
|
487
|
+
result.activationPlan = {
|
|
488
|
+
activated: true,
|
|
489
|
+
decision: 'trigger',
|
|
490
|
+
score: 38,
|
|
491
|
+
confidence: 0.9,
|
|
492
|
+
matchedKeywords: ['work', 'flow', 'dispatch', 'run'],
|
|
493
|
+
goal: '执行 Carlos 工作流任务:run dispatch workflow(命中:work, flow, dispatch, run)',
|
|
494
|
+
steps: [
|
|
495
|
+
{ tool: 'flow_add_user_msg', auto: true }, // 自动:留痕用户原话
|
|
496
|
+
{ tool: 'flow_submit_requirement', auto: true }, // 自动:提交 read_only 占位卡
|
|
497
|
+
{ tool: 'flow_submit_requirement', auto: false }, // 引导:补齐字段后重新提交
|
|
498
|
+
// needsFill 不是固定三项:待补字段由**服务端从当前卡片内容派生**
|
|
499
|
+
// (scope / acceptance / verify.cmd 缺哪个就锁哪个,都齐了才解闸)。
|
|
500
|
+
needsFill: '<由服务端派生:scope / acceptance / verify.cmd 中当前缺失的项>' },
|
|
501
|
+
],
|
|
502
|
+
pendingFields: '<由服务端从卡片内容派生,非固定三项>',
|
|
503
|
+
prompt: '【Carlos 触发引擎已激活工作流】…',
|
|
504
|
+
};
|
|
505
|
+
```
|
|
506
|
+
|
|
507
|
+
### 激活的四个实际动作
|
|
508
|
+
|
|
509
|
+
1. **留痕用户原话** — `flow_add_user_msg`
|
|
510
|
+
把用户原话写进会话消息文件。它是任务卡 `quote` 锚点校验的**唯一数据源**,必须先于开卡。
|
|
511
|
+
|
|
512
|
+
2. **提交占位卡** — `flow_submit_requirement`(`activation: true`)
|
|
513
|
+
以 `read_only` 档提交(只要求 `goal` + `quote`),**会话进入已留痕门禁态**,审计链记录激活事件。
|
|
514
|
+
|
|
515
|
+
3. **闸门生效** — `activation_pending`
|
|
516
|
+
状态里记下待补齐字段 `scope` / `acceptance` / `verify.cmd`。
|
|
517
|
+
在补齐之前,以下三个工具 **一律拒绝**:
|
|
518
|
+
|
|
519
|
+
| 工具 | 拒绝原因 |
|
|
520
|
+
|------|---------|
|
|
521
|
+
| `flow_claim` | 不能拿一张没补齐的卡去领派发名额 |
|
|
522
|
+
| `flow_dispatch` | 不能拿一张没补齐的卡去派发执行 |
|
|
523
|
+
| `flow_verdict` | **防假闭环**——未经派发**且未验证通过**,不能直接记 PASS(`DIRECTION` / `LOCAL` 不受此限) |
|
|
524
|
+
|
|
525
|
+
```
|
|
526
|
+
ERROR: 激活占位卡尚未补齐(待补:scope、acceptance、verify.cmd)。
|
|
527
|
+
请先补齐后重新调用 flow_submit_requirement,再来领取派发名额。
|
|
528
|
+
```
|
|
529
|
+
|
|
530
|
+
4. **补齐后放行** — 重新提交完整卡
|
|
531
|
+
Agent 补齐字段后重新调用 `flow_submit_requirement`(**不带** `activation`),
|
|
532
|
+
`activation_pending` 被清空,门禁解除,可以正常 `flow_claim` / `flow_dispatch`。
|
|
533
|
+
|
|
534
|
+
### 安全约束
|
|
535
|
+
|
|
536
|
+
| 约束 | 行为 |
|
|
537
|
+
|------|------|
|
|
538
|
+
| 会话**已有任务卡** | 跳过自动开卡,**不覆盖用户已有任务** |
|
|
539
|
+
| 占位卡**不许记 PASS** | `flow_verdict` 在字段未补齐时拒绝,堵住「未执行、未验证、却直接完成」的假闭环 |
|
|
540
|
+
| 自动激活**不决定改哪些文件** | 只负责“留痕 + 进入门禁”,`scope` 必须由 Agent 确认 |
|
|
541
|
+
| 目标描述是**推断值** | `goal` 由关键词推导,**标记为占位**,需与用户确认后改写 |
|
|
542
|
+
| `manual` 档 | 只输出建议与补全指引,**不执行任何 MCP 动作** |
|
|
543
|
+
|
|
544
|
+
### 手动使用激活计划
|
|
545
|
+
|
|
546
|
+
```javascript
|
|
547
|
+
const plan = result.activationPlan;
|
|
548
|
+
for (const step of plan.steps) {
|
|
549
|
+
if (!step.auto) continue; // 只执行参数完整的步骤
|
|
550
|
+
await callMCP('tools/call', { name: step.tool, arguments: step.args });
|
|
551
|
+
}
|
|
552
|
+
// 然后把 plan.prompt 交给 Agent,让它补齐字段
|
|
553
|
+
```
|
|
554
|
+
|
|
555
|
+
---
|
|
556
|
+
|
|
557
|
+
## 🔄 动态上限计算
|
|
558
|
+
|
|
559
|
+
### 公式
|
|
560
|
+
|
|
561
|
+
```
|
|
562
|
+
动态上限 = clamp(
|
|
563
|
+
baseTriggerLimit +
|
|
564
|
+
(会话时长小时数 × sessionLengthCoeff) +
|
|
565
|
+
(任务复杂度 × complexityCoeff) -
|
|
566
|
+
(窗口内触发次数 × historyCoeff),
|
|
567
|
+
1, maxTriggerLimit
|
|
568
|
+
)
|
|
569
|
+
```
|
|
570
|
+
|
|
571
|
+
> **设计要点**:会话越长、任务越复杂 → 上限越高(允许更多触发);
|
|
572
|
+
> 近期触发越频繁 → 上限越低(收敛打扰)。
|
|
573
|
+
> 历史项是**惩罚项**而非增益项 —— 若为增益,触发次数会把上限反向抬高,封顶逻辑将自我抵消而永不生效。
|
|
574
|
+
|
|
575
|
+
### 示例
|
|
576
|
+
|
|
577
|
+
- 新会话(0 小时),复杂度 1.0,无历史 → 上限 = 5 + 0 + 2 - 0 = **7**
|
|
578
|
+
- 2 小时会话,复杂度 1.2,窗口内 3 次触发 → 上限 = 5 + 1 + 2.4 - 0.9 = **7**
|
|
579
|
+
- 5 小时会话,复杂度 1.5,窗口内 0 次触发 → 上限 = 5 + 2.5 + 3 = **10**
|
|
580
|
+
|
|
581
|
+
### 上限判定
|
|
582
|
+
|
|
583
|
+
```
|
|
584
|
+
窗口内触发次数 = countTriggersInWindow() // 原始计数
|
|
585
|
+
if (窗口内触发次数 >= 动态上限) → 拒绝触发
|
|
586
|
+
```
|
|
587
|
+
|
|
588
|
+
> 注:判定用的是**原始次数**(`countTriggersInWindow()`),不是衰减加权均值。
|
|
589
|
+
> 上限公式里的历史项同样用原始次数×`historyCoeff`(惩罚项,触发越多上限越低)。
|
|
590
|
+
|
|
591
|
+
> ⚠️ **窗口长度必须与最短间隔匹配**:`minTriggerIntervalSeconds = 300`(5 分钟)时,
|
|
592
|
+
> 若 `triggerWindowMinutes` 只有 15 分钟,窗口内最多只能触发 3 次,
|
|
593
|
+
> 而上限至少是 5+1=6 → 「次数达上限」分支**永远不可达**,实际只有 5 分钟冷却在起作用。
|
|
594
|
+
> 因此默认 `triggerWindowMinutes` 已改为 **60 分钟**(1 小时内最多 12 次,上限 6~15 才有意义)。
|
|
595
|
+
|
|
596
|
+
## 📈 用户反馈学习
|
|
597
|
+
|
|
598
|
+
系统**持久化**记录用户反馈(存在会话状态文件里,进程退出也不丢),
|
|
599
|
+
并让反馈**真正影响触发阈值**:
|
|
600
|
+
|
|
601
|
+
```javascript
|
|
602
|
+
// 用户接受触发
|
|
603
|
+
engine.recordFeedback('positive');
|
|
604
|
+
|
|
605
|
+
// 用户拒绝触发
|
|
606
|
+
engine.recordFeedback('negative');
|
|
607
|
+
// → { ok: true, feedback: { positive: 0, negative: 1 }, thresholdAdjustment: 1 }
|
|
608
|
+
```
|
|
609
|
+
|
|
610
|
+
| 机制 | 说明 |
|
|
611
|
+
|------|------|
|
|
612
|
+
| **即时调整** | `getFeedbackThresholdAdjustment()` 按当前会话正/负反馈比例算出阈值偏移,负反馈越多偏移越大(更保守) |
|
|
613
|
+
| **持久学习** | 每累积 `feedbackLearningCycle`(默认 10)条反馈自动调用 `updateFeedbackWeights()`,把学习结果写入 `trigger-config.json` 的 `feedbackThresholdOffset` |
|
|
614
|
+
| **生效位置** | 偏移量加在决策阈值上:`effectiveThreshold = threshold + 即时偏移 + 持久偏移`,最低为 1 |
|
|
615
|
+
|
|
616
|
+
```javascript
|
|
617
|
+
// 手动触发一次学习(可选,recordFeedback 已会自动按周期触发)
|
|
618
|
+
engine.updateFeedbackWeights();
|
|
619
|
+
// → { ok: true, thresholdOffset: 1, positive: 0, negative: 10 }
|
|
620
|
+
```
|
|
621
|
+
|
|
622
|
+
> ⚠️ 早期版本的反馈只写在**进程内 Map** 里、`updateFeedbackWeights()` 也**没有任何调用点**,
|
|
623
|
+
> 属于「文档写了但功能不存在」。现在已改为持久化 + 自动触发 + 真正影响阈值。
|
|
624
|
+
|
|
625
|
+
## 🎯 最佳实践
|
|
626
|
+
|
|
627
|
+
### 1. 响应式设计
|
|
628
|
+
|
|
629
|
+
- 高频触发场景:调高 `maxTriggerLimit`
|
|
630
|
+
- 低频场景:降低 `triggerThreshold` 优化灵敏度
|
|
631
|
+
- 生产环境:设置 `minTriggerIntervalSeconds >= 300`
|
|
632
|
+
|
|
633
|
+
### 2. 关键词优化
|
|
634
|
+
|
|
635
|
+
根据实际业务调整 `keywordWeights`:
|
|
636
|
+
|
|
637
|
+
```json
|
|
638
|
+
"keywordWeights": {
|
|
639
|
+
"deploy": 4,
|
|
640
|
+
"test": 3,
|
|
641
|
+
"check": 2,
|
|
642
|
+
"run": 1
|
|
643
|
+
}
|
|
644
|
+
```
|
|
645
|
+
|
|
646
|
+
### 3. 上下文感知
|
|
647
|
+
|
|
648
|
+
为不同任务类型设置不同复杂度参数:
|
|
649
|
+
|
|
650
|
+
```bash
|
|
651
|
+
# 高风险任务
|
|
652
|
+
node carlos.js flow_dispatch --complexity 1.5
|
|
653
|
+
|
|
654
|
+
# 常规任务
|
|
655
|
+
node carlos.js flow_dispatch --complexity 1.0
|
|
656
|
+
```
|
|
657
|
+
|
|
658
|
+
## 🔧 高级功能
|
|
659
|
+
|
|
660
|
+
### 自定义评分算法
|
|
661
|
+
|
|
662
|
+
```javascript
|
|
663
|
+
class CustomScorer extends TriggerScorer {
|
|
664
|
+
calculateKeywordScore(message) {
|
|
665
|
+
// 覆盖关键词匹配逻辑
|
|
666
|
+
// ...
|
|
667
|
+
}
|
|
668
|
+
}
|
|
669
|
+
|
|
670
|
+
// 使用自定义打分器
|
|
671
|
+
const customEngine = new TriggerDecisionEngine(
|
|
672
|
+
new DynamicTriggerManager(),
|
|
673
|
+
new CustomScorer()
|
|
674
|
+
);
|
|
675
|
+
```
|
|
676
|
+
|
|
677
|
+
### 持久化状态
|
|
678
|
+
|
|
679
|
+
```javascript
|
|
680
|
+
const state = TriggerState.load('session-id');
|
|
681
|
+
// 修改状态
|
|
682
|
+
state.triggerHistory = [...];
|
|
683
|
+
state.save(); // 持久化到 disk
|
|
684
|
+
```
|
|
685
|
+
|
|
686
|
+
## 🐛 故障排查
|
|
687
|
+
|
|
688
|
+
### 问题 1: 触发不灵敏
|
|
689
|
+
|
|
690
|
+
**症状**: 明显意图但评分低于阈值
|
|
691
|
+
|
|
692
|
+
**解决**:
|
|
693
|
+
1. 检查关键词权重配置
|
|
694
|
+
2. 降低 `triggerThreshold`
|
|
695
|
+
3. 增加 `contextRelevanceWeight`
|
|
696
|
+
|
|
697
|
+
### 问题 2: 触发过于频繁
|
|
698
|
+
|
|
699
|
+
**症状**: 短时间内多次触发
|
|
700
|
+
|
|
701
|
+
**解决**:
|
|
702
|
+
1. 调高 `minTriggerIntervalSeconds`
|
|
703
|
+
2. 调低 `sessionLengthCoeff`
|
|
704
|
+
3. 调高 `historyCoeff`(它是**惩罚项**,调高会更快收紧上限)
|
|
705
|
+
4. 调低 `baseTriggerLimit`
|
|
706
|
+
|
|
707
|
+
### 问题 3: 评分总是 0
|
|
708
|
+
|
|
709
|
+
**症状**: 所有消息都匹配不到关键词
|
|
710
|
+
|
|
711
|
+
**解决**:
|
|
712
|
+
1. 检查消息是否包含配置关键词
|
|
713
|
+
2. 验证 `keywordWeights` 是否生效
|
|
714
|
+
3. 查看日志调试匹配过程
|
|
715
|
+
|
|
716
|
+
### 问题 4: 触发引擎没生效(客户端无任何提示)
|
|
717
|
+
|
|
718
|
+
**症状**: 调用 `client/carlos.js` 时看不到 `[Carlos Trigger]` 日志
|
|
719
|
+
|
|
720
|
+
**解决**:
|
|
721
|
+
1. 确认 `src/trigger.js` 存在且与 `client/carlos.js` 同版本
|
|
722
|
+
2. 确认客户端用的是**动态 import**(ESM 下 `require()` 不存在,会被 try/catch 静默吞掉)
|
|
723
|
+
3. 直接运行 `node src/trigger.js "你的消息"` 验证引擎本体
|
|
724
|
+
|
|
725
|
+
### 问题 5: 激活后 `flow_claim` / `flow_dispatch` 被拒
|
|
726
|
+
|
|
727
|
+
**症状**: `ERROR: 激活占位卡尚未补齐(待补:scope、acceptance、verify.cmd)`
|
|
728
|
+
|
|
729
|
+
**这不是 bug,是激活闸门在起作用**。自动激活只负责“留痕 + 进入门禁”,
|
|
730
|
+
不知道该改哪些文件,所以必须先补齐字段:
|
|
731
|
+
|
|
732
|
+
1. 确认目标描述(激活时自动推断的 `goal` 可能不准,需与用户确认后改写)
|
|
733
|
+
2. 补齐 `scope`(只准改动的文件)、`acceptance`(可判定的验收标准)、`verify.cmd`(验证命令)
|
|
734
|
+
3. **重新调用 `flow_submit_requirement`**(不要带 `activation` 参数)——这一步会清空 `activation_pending`
|
|
735
|
+
4. 再调用 `flow_claim` / `flow_dispatch`
|
|
736
|
+
|
|
737
|
+
查看当前待补字段:
|
|
738
|
+
|
|
739
|
+
```bash
|
|
740
|
+
node client/carlos.js flow_status '{"sessionId":"my-task"}'
|
|
741
|
+
# → "activation_pending": ["scope", "acceptance", "verify.cmd"]
|
|
742
|
+
```
|
|
743
|
+
|
|
744
|
+
### 问题 6: 激活了但派发一直被拒,且提示「待补:scope、acceptance、verify.cmd」
|
|
745
|
+
|
|
746
|
+
**症状**: `ERROR: 激活占位卡尚未补齐(待补:scope、acceptance、verify.cmd)`
|
|
747
|
+
|
|
748
|
+
**这是闸门在正常工作**,不是故障。必须**三项都补齐**才能解闸:
|
|
749
|
+
|
|
750
|
+
- `scope` —— 只准改动的文件(非空)
|
|
751
|
+
- `acceptance` —— 可判定的验收标准(非空)
|
|
752
|
+
- `verify.cmd` —— 验证命令(非空)
|
|
753
|
+
|
|
754
|
+
只补其中一项**不解闸**(`activation_pending` 会精确告诉你还缺哪几项)。
|
|
755
|
+
补齐后**重新调用 `flow_submit_requirement`**(不带 `activation` 参数)即解除。
|
|
756
|
+
|
|
757
|
+
### 问题 7: 一个会话的触发影响了另一个会话
|
|
758
|
+
|
|
759
|
+
**症状**: 明明是新会话,却提示“时间间隔不足”
|
|
760
|
+
|
|
761
|
+
**原因**: 早期版本所有会话共用一个触发状态文件(`trigger-state.json`),跨会话互相限流。
|
|
762
|
+
|
|
763
|
+
**现状**: 已修复——状态按 session 分文件存放在 `CARLOS_FLOW_HOME/trigger-state/<sessionId>.json`。
|
|
764
|
+
若仍遇到,请确认客户端与 `src/trigger.js` 版本一致(见问题 4)。
|
|
765
|
+
|
|
766
|
+
## 📚 相关资源
|
|
767
|
+
|
|
768
|
+
- [测试脚本](test/trigger-e2e.mjs) - E2E 测试套件(29 项,含 10 项回归用例)
|
|
769
|
+
- [变异测试](scripts/mutation-check.mjs) - 注入退化验证测试套件真的能抓住(13 类变异)
|
|
770
|
+
- [核心代码](src/trigger.js) - 触发引擎实现
|
|
771
|
+
- [集成示例](client/carlos.js) - 客户端集成代码
|
|
772
|
+
- [完整 README](../README.md) - 项目总览与能力矩阵
|
|
773
|
+
- [迁移指南](../MIGRATION.md) - 从旧包升级
|
|
774
|
+
- [更新日志](../CHANGELOG.md) - 版本历史
|
|
775
|
+
|
|
776
|
+
## 📄 许可证
|
|
777
|
+
|
|
778
|
+
MIT License
|
|
779
|
+
|
|
780
|
+
---
|
|
781
|
+
|
|
782
|
+
**版本**: v2.6.1
|
|
783
|
+
**更新日期**: 2026-11-07
|