dsh-cot-anchor 0.0.0-stage → 0.3.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/LICENSE +21 -0
- package/README.md +142 -2
- package/cordis.patch.yml +10 -0
- package/docs/softcut-kernel-port.md +257 -0
- package/lib/client.js +677 -0
- package/lib/index.js +4536 -0
- package/package.json +51 -4
- package/tools/apply-softcut-port.mjs +1390 -0
- package/tools/trace-softcut.mjs +159 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 dsh-cot-anchor contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,143 @@
|
|
|
1
|
-
#
|
|
1
|
+
# dsh-cot-anchor
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
DeepSeek Harness(DSH)插件:治一类特定的模型毛病——**思考着思考,但没在推进**。表现为反复重新推导已经得出的结论、把工具调用写成纯文本、原地重复同一段话、输出无意义的递增数字流。
|
|
4
|
+
|
|
5
|
+
插件做两件事:
|
|
6
|
+
|
|
7
|
+
1. **结论回流**:每次工具结果返回后,从最新思考中摘出已成立的结论(最多 3 条、每条 ≤ 220 字)插回上下文,下一步起手就能看到,不必重推一遍。**装上默认生效。**
|
|
8
|
+
2. **生成中途打断(软切)**:生成过程中每 32 个字符检查一次,发现打转 / 原地重复 / 伪工具调用 / 数字流就立即切断本次请求,把已生成部分作为正常消息落盘、排好结论锚点,让回合从断点续跑——不会因为一次误判丢掉整轮工作。
|
|
9
|
+
|
|
10
|
+
它不解决一切长任务问题,只解决「单流内思考链极度冗余、结论反复重新发现」。跨步骤的折返跑(同一结论在十几步里重推)不在能力范围内,那是姊妹插件 [dsh-step-governor](https://github.com/JiewiW/dsh-step-governor) 的职责。
|
|
11
|
+
|
|
12
|
+
## 快速开始
|
|
13
|
+
|
|
14
|
+
```sh
|
|
15
|
+
dsh plugin --profile <你的profile> add github:JiewiW/dsh-cot-anchor#v0.3.0
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
重启实例后设置页出现「COT 锚点」标签即生效。结论注入无需任何配置;软切需要内核支持(见[兼容性](#兼容性与软切内核))。
|
|
19
|
+
|
|
20
|
+
## 工作方式
|
|
21
|
+
|
|
22
|
+
```
|
|
23
|
+
模型思考 → 工具执行 → [插件] 摘出已成立的结论插回上下文 → 下一步思考
|
|
24
|
+
↑
|
|
25
|
+
只在工具边界注入
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
注入消息以 `user` 角色追加在工具结果之后、下一次请求之前,尾部追加写入会话日志,不改写已有内容,因此不会打穿前缀缓存。
|
|
29
|
+
|
|
30
|
+
## 成本
|
|
31
|
+
|
|
32
|
+
| 场景 | 额外成本 |
|
|
33
|
+
| --- | --- |
|
|
34
|
+
| 默认(结论注入开启,其余关闭) | 每个工具结果后一条短消息,上界 660 字符(3 条 × 220 字);无额外模型调用 |
|
|
35
|
+
| 命令执行纪律提醒 | 每轮一次、随运行时上下文快照("Current runtime context…")注入,位于记忆规则之后;单条全文固定约 380 token(字符估算),作为稳定前缀段参与上下文,不再随工具调用堆叠 |
|
|
36
|
+
| 开启 LLM 提炼结论(默认关) | 每个助手回合**多一次**小模型调用 |
|
|
37
|
+
| 开启打转 / 重复等判定 | 纯本地字符串计算,零 token 成本;可能增加少量回合数 |
|
|
38
|
+
| 开启 CoT 静默采集 | 每个助手回合留一条本地样本;默认关闭 |
|
|
39
|
+
|
|
40
|
+
注入消息会随之后续请求的上下文一同发送,因此持续占用少量上下文窗口。按中英混排估算,660 字符约合 200–500 token 量级——相对于一次工具往返的上下文可以忽略,但它在**每一步**都会累积。注入以尾部追加方式写入会话日志,不改写已有内容,因此不会打穿前缀缓存:除新追加的一块外,此前内容始终是稳定前缀。新追加块在其首次出现的那次请求上按未命中计费一次,此后转为缓存命中——这一点与文本是否固定无关。推理锚点每次不同,其排列顺序仅为内容组织上的一致性,不影响缓存行为(自 411cb74/v0.2.2 起命令执行纪律已改走运行时上下文快照的固定段,不再参与本次工具注入)。
|
|
41
|
+
|
|
42
|
+
在一个约 924 万 token 的真实长会话上实测:插件注入总量约占全会话 0.23%(每个注入块只在首现那一次请求按未命中计费,此后转为缓存命中)。具体分项口径见下文「实测成本占比」。
|
|
43
|
+
|
|
44
|
+
## 能力边界(请先读)
|
|
45
|
+
|
|
46
|
+
- 两类机制都是**单步边界内**的:软切只看当前一次生成流,进入下一步计数归零。治得了单流内退化,治不了跨步骤折返跑。
|
|
47
|
+
- 软切不减少回合步数。长任务账单的大头是「步数 × 每步膨胀的上下文重读」,步数治理请用 step-governor。
|
|
48
|
+
- 模型可能**知道自己在空转却停不下来**——实测出现过思考中自述「I'm burning turns, let me stop」之后继续生成下一条探索路线。注入的前提是模型会读且照做,自知不构成刹车。
|
|
49
|
+
- 软切每回合按判定类别分桶计预算 **6/20/3**(启发式判定 6 次、字节级确证重复 20 次、伪工具调用 3 次),总闸 **29**(6+20+3)。打满后启发式判定升级为终止本回合,高置信重复仍照常拦截;预算事件(`agent/soft-cut-suppressed` / `phase.abortTurn`)在会话日志可观测。这些常量由内核定义、不由插件持有。
|
|
50
|
+
|
|
51
|
+
> 以下统计数据自 **v0.2.1 之前的机制**采集:当时命令执行纪律是随每次工具执行后剥出的独立 `user` 消息(`source.summary = cot-anchor: exec-discipline`)与推理锚点同车注入。**自 v0.2.1 起(并入 411cb74 迁移后)**,纪律不再随工具注入,而是注册为运行时上下文快照的一个固定段(每轮出现一次、位于记忆规则之后、用户唠叨之前),不再按工具条数线性堆叠;下述注入量只是旧机制的上限参照。
|
|
52
|
+
|
|
53
|
+
在一个 95 次助手请求、累计约 924 万 token 的真实长会话上按消息级口径统计(字符→token 为启发式估算,非 tokenizer 实测;任何人可在自己的 DSH 会话日志上按同口径复算:逐条统计 `user/message` 中 `source.summary` 为 `cot-anchor: exec-discipline`(固定纪律)与其他 `cot-anchor:*`(动态锚点)的文本,并对照各次助手请求 `usage` 的 `inputTokens` / `cacheReadTokens`):
|
|
54
|
+
|
|
55
|
+
> 结论:插件带来的新增输入在全会话 token 总量的 0.3% 以内。每个注入块在首现时按未命中计费一次,此后随上下文增长参与后续每一次请求。纪律块体积约占注入量五分之四,但"文本固定"不带来额外缓存收益——该占比只反映体积,不反映命中。(该占比为 v0.2.1 之前旧机制的历史数据;新版纪律块已移入运行时上下文快照固定段,不再按工具条数累计。)
|
|
56
|
+
|
|
57
|
+
## 兼容性与软切内核
|
|
58
|
+
|
|
59
|
+
| 能力 | 支持的 DSH 版本 |
|
|
60
|
+
| --- | --- |
|
|
61
|
+
| --- | --- |
|
|
62
|
+
| 结论注入、设置页 | 0.1.5 起全部版本 |
|
|
63
|
+
| 生成中途打断(软切) | 仅 0.1.5-rc.1 / rc.2 开箱可用 |
|
|
64
|
+
|
|
65
|
+
0.1.5-rc.3 起内核移除了软切所需的 `agent/soft-cut` 钩子,该能力会静默失效;插件在启动日志和设置页顶部明确提示当前内核是否支持——**以设置页显示为准**,不要凭开关是开的就认为在生效。
|
|
66
|
+
|
|
67
|
+
新版内核可用随包工具把软切机构移植回去(带版本与哈希自检,幂等、可回滚,不符自动还原):
|
|
68
|
+
|
|
69
|
+
```sh
|
|
70
|
+
node node_modules/dsh-cot-anchor/tools/apply-softcut-port.mjs --check # 查看状态
|
|
71
|
+
node node_modules/dsh-cot-anchor/tools/apply-softcut-port.mjs # 应用
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
移植后重启实例。完整步骤与风险见 [docs/softcut-kernel-port.md](docs/softcut-kernel-port.md)。
|
|
75
|
+
|
|
76
|
+
## 设置
|
|
77
|
+
|
|
78
|
+
设置页「COT 锚点」共 61 项、分组展示,多数场景用默认值即可。下面只列常用项与容易误判的项;其余阈值在设置页内均有内联说明。
|
|
79
|
+
|
|
80
|
+
### 总开关
|
|
81
|
+
|
|
82
|
+
| 键 | 默认 | 说明 |
|
|
83
|
+
| --- | --- | --- |
|
|
84
|
+
| `enableToolInject` | 开 | 工具结果后注入结论锚点,本插件的主要价值,建议保持开启 |
|
|
85
|
+
| `enableSoftCut` | 开 | 允许生成中途打断;内核不支持时自动无效 |
|
|
86
|
+
| `enableExecDisciplineBlock` | 开 | 随锚点同车注入命令执行纪律提醒;与锚点注入共用去重节奏,关闭后锚点注入行为不变 |
|
|
87
|
+
|
|
88
|
+
### 五项软切判定
|
|
89
|
+
|
|
90
|
+
全部关闭时插件只做结论注入。
|
|
91
|
+
|
|
92
|
+
| 键 | 识别什么 | 注意 |
|
|
93
|
+
| --- | --- | --- |
|
|
94
|
+
| `enablePseudoTool` | 把工具调用写成普通文本(如 `<seed:tool_call>...`) | 只能识别已知文本形态 |
|
|
95
|
+
| `enableRepeat` | 逐字节相同的内容反复吐出 | 换措辞的重复抓不到 |
|
|
96
|
+
| `enableChurn` | 措辞不同但反复「重新分析」 | 启发式判定,遇到未闭合代码块自动让路 |
|
|
97
|
+
| `enableTransition` | 「接下来我要……」类转折句 | **最容易误判**:正常分阶段思考也有转折句;若频繁在正常思考中切断,先关它(v0.3.0 起已要求转折词后跟随执行动词、并剥离已注入锚点后再判定,误判面已显著收窄) |
|
|
98
|
+
| `enableNumberRunaway` | 无意义递增数字流 | 要求数字流足够长(≥ 500 字符跨度等阈值) |
|
|
99
|
+
|
|
100
|
+
打断太频繁时:先关 `enableTransition`,其次调高判定阈值(`churnMinHits` 默认 18 等)。
|
|
101
|
+
|
|
102
|
+
自 v0.2.4 起,转折句判定自带「结论-转折间距」守卫(`softCutGapThreshold`,默认 80):当尾部扫描窗口内最后一个结论开启词(如「所以」)与最后一个转折宣告(如「接下来」)间距超过阈值时,判定为「子阶段小结论 + 后续分析 + 转折宣告」而非阶段边界,拒绝软切——避免「所以 X 是根因」这类中途小结论与后续转折词各自命中检测器、把一次正常分析拦腰切断。
|
|
103
|
+
|
|
104
|
+
自 v0.3.0 起,转折句判定叠加三层加固(详见[发行说明](RELEASE-NOTES.md)):① 已注入锚点按会话去重,同内容不再重复注入,命中时记录去重事件而非切断;② 「结论-转折间距」守卫在结论开启词缺失时由放行改为拒绝(fail-closed);③ 切句与转折识别改为引号感知——报告正文中引用的推理原文、正则文本不再被切成以「所以/现在」开头的伪句;同时转折宣告词后必须跟随执行动词(「现在写报告」命中、「Now I have the full chain.」这类状态陈述不命中),已注入锚点文本也先剥离再参与判定,阻断「锚点自我触发」的自反馈环。
|
|
105
|
+
|
|
106
|
+
### 锚点内容
|
|
107
|
+
|
|
108
|
+
| 键 | 默认 | 说明 |
|
|
109
|
+
| --- | --- | --- |
|
|
110
|
+
| `minReasoningChars` | 250 | 思考短于此长度不提取结论 |
|
|
111
|
+
| `maxPoints` | 3 | 最多保留几条结论 |
|
|
112
|
+
| `maxPointChars` | 220 | 单条结论字数上限 |
|
|
113
|
+
|
|
114
|
+
结论由规则从思考文本中摘句得到,不理解句子的语义角色,因此入池前会剔除两类无命题内容:纯话语标记句(剥掉 Actually / wait / Hmm / 其实 / 等等 等标记后实词不足 6 字符,如「Actually, wait.」「其实,等等。」)与路线意图宣告句(「the decisive route: ask the user…」)。标记词**领起但带事实命题**的句子(「Wait, the kernel never marks in verbose mode.」)照常保留。
|
|
115
|
+
|
|
116
|
+
注意:Wait / Actually / Hmm 等转折词在推理链中承担结构控制作用,插件**不从模型输出里删除它们**,只阻止它们被当成结论回灌。
|
|
117
|
+
|
|
118
|
+
### LLM 提炼与 CoT 采集(默认全关)
|
|
119
|
+
|
|
120
|
+
- `enableLlmRefine`:用一次小模型调用把整段思考压成摘要式结论,通常比规则摘句更准;provider/model 留空则跟随当前会话。
|
|
121
|
+
- `enableHarvest` / `enableAutoAnalyze` / `enableLearnedPatterns`:静默采集思考样本、自动归纳检测器看不见的打转形态、把学习成果用于判定。开启会在本地留存思考文本,启用前请自行评估隐私;学习模式默认有 20 轮影子期(`learnedShadowRounds`)防止一次误学永久改变判定。
|
|
122
|
+
|
|
123
|
+
## 隐私
|
|
124
|
+
|
|
125
|
+
- 结论注入与全部软切判定都在本地完成,不向任何外部服务发送数据。
|
|
126
|
+
- LLM 提炼开启时,思考文本会发给你指定的 provider(留空则跟随当前会话)。
|
|
127
|
+
- CoT 采集开启时,思考文本与工具轨迹只留存本地。
|
|
128
|
+
|
|
129
|
+
## 常见问题
|
|
130
|
+
|
|
131
|
+
**设置页显示「当前内核没有掐断能力」**
|
|
132
|
+
内核不提供软切钩子,结论注入不受影响。需要软切可停留在 0.1.5-rc.1/rc.2,或按上文移植。
|
|
133
|
+
|
|
134
|
+
**模型好像没收到提醒**
|
|
135
|
+
确认 `enableToolInject` 已开、且思考长度超过 `minReasoningChars`——思考过短本来就不提取。
|
|
136
|
+
|
|
137
|
+
## 开发
|
|
138
|
+
|
|
139
|
+
仓库根目录所有 `test-*.mjs` 都是独立可执行脚本(无测试框架、无 `npm test`),逐个 `node test-*.mjs` 运行,退出码 0 即通过。
|
|
140
|
+
|
|
141
|
+
## 许可
|
|
142
|
+
|
|
143
|
+
MIT
|
package/cordis.patch.yml
ADDED
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
# dsh-cot-anchor bundle patch: mount the dsh-cot-anchor plugin.
|
|
2
|
+
#
|
|
3
|
+
# Applied when this bundle appears in a profile's dsh.profile.bundles list.
|
|
4
|
+
# Host half only: listens to tools/post-execute, extracts conclusion sentences
|
|
5
|
+
# from the latest assistant reasoning block, and injects a brief "COT anchor"
|
|
6
|
+
# summary after each tool result so the model does not re-derive
|
|
7
|
+
# already-established conclusions in the next reasoning pass.
|
|
8
|
+
- insert:
|
|
9
|
+
- id: dsh-cot-anchor
|
|
10
|
+
name: dsh-cot-anchor
|
|
@@ -0,0 +1,257 @@
|
|
|
1
|
+
# 在 0.1.5-rc.3 及以上版本恢复生成中途软切
|
|
2
|
+
|
|
3
|
+
> 本文档面向已在使用本插件、且希望在新版 DSH 上保留"打转打断"能力的用户。
|
|
4
|
+
> 不需要打断能力的用户**无需阅读**——结论注入在所有版本都正常工作。
|
|
5
|
+
|
|
6
|
+
## 目录
|
|
7
|
+
|
|
8
|
+
1. [为什么需要这个补丁](#一为什么需要这个补丁)
|
|
9
|
+
2. [能力现状速查](#二能力现状速查)
|
|
10
|
+
3. [使用步骤](#三使用步骤)
|
|
11
|
+
4. [移植原理](#四移植原理)
|
|
12
|
+
5. [风险与回滚](#五风险与回滚)
|
|
13
|
+
6. [排障](#六排障)
|
|
14
|
+
7. [已知限制](#七已知限制)
|
|
15
|
+
|
|
16
|
+
## 一、为什么需要这个补丁
|
|
17
|
+
|
|
18
|
+
### 现象
|
|
19
|
+
|
|
20
|
+
模型在生成过程中出现下列情况时,插件**不会打断**,只能靠你手动中断:
|
|
21
|
+
|
|
22
|
+
- 把工具调用写成普通文本(例如输出 `<seed:tool_call>…`)而非真正发起调用;
|
|
23
|
+
- 原地重复同一段内容,重复几百次也不停;
|
|
24
|
+
- 措辞不同但反复"重新分析"同一件事(语义空转);
|
|
25
|
+
- 输出无意义的递增数字流。
|
|
26
|
+
|
|
27
|
+
这些情况都会让一次回合白烧 token 却毫无进展。
|
|
28
|
+
|
|
29
|
+
### 原因
|
|
30
|
+
|
|
31
|
+
打断能力依赖 DSH 宿主提供的钩子 `agent/soft-cut`。该钩子自 **0.1.5-rc.3 起被上游移除**:
|
|
32
|
+
|
|
33
|
+
| DSH 版本 | 具备该钩子 |
|
|
34
|
+
| --- | --- |
|
|
35
|
+
| 0.1.5-rc.1 | 是 |
|
|
36
|
+
| 0.1.5-rc.2 | 是 |
|
|
37
|
+
| 0.1.5-rc.3 及更高(含 0.1.6 / 0.1.7 / 0.2.x) | 否 |
|
|
38
|
+
|
|
39
|
+
钩子不存在时,插件注册在其上的回调**永远不会触发**。此时插件表现如下:
|
|
40
|
+
|
|
41
|
+
- 加载无报错、启动日志干净;
|
|
42
|
+
- 结论注入照常工作(这是插件的主要功能,不受影响);
|
|
43
|
+
- 设置页的"打断判定"开关虽然是打开的,但**不起任何作用**。
|
|
44
|
+
|
|
45
|
+
**静默失效**是这里最麻烦的地方:开关状态与实际行为不一致,��能靠观察故障反推。
|
|
46
|
+
|
|
47
|
+
### 本补丁做什么
|
|
48
|
+
|
|
49
|
+
把 0.1.5-rc.2 中的软切机构移植回新版内核,恢复"切断当前生成、插入锚点、从断点继续"的语义。
|
|
50
|
+
|
|
51
|
+
插件代码**不需要任何改动**。
|
|
52
|
+
|
|
53
|
+
## 二、能力现状速查
|
|
54
|
+
|
|
55
|
+
| 能力 | 不打补丁 | 打补丁后 |
|
|
56
|
+
| --- | --- | --- |
|
|
57
|
+
| 结论注入(插件主功能) | ✅ 正常 | ✅ 正常 |
|
|
58
|
+
| 设置页显示 | ✅ 正常 | ✅ 正常 |
|
|
59
|
+
| 打转判定(伪调用 / 重复 / 空转 / 数字流) | ❌ 静默失效 | ✅ 正常 |
|
|
60
|
+
| 生成中途打断 | ❌ 静默失效 | ✅ 正常 |
|
|
61
|
+
|
|
62
|
+
不打补丁时,插件会在启动日志和设置页顶部明确提示"当前内核没有掐断能力"——请以该提示为准,不要凭"开关是开的"判断功能是否生效。
|
|
63
|
+
|
|
64
|
+
## 三、使用步骤
|
|
65
|
+
|
|
66
|
+
### 前提
|
|
67
|
+
|
|
68
|
+
- Node.js 18 或更高(脚本需要 `node:zlib` 的 zstd 支持与标准 ESM)
|
|
69
|
+
- 能修改 DSH 安装目录下的 `node_modules`(即有写权限)
|
|
70
|
+
- 改动的是宿主内核文件,**属于超出插件边界的修改**,请先理解本文第五节的风险
|
|
71
|
+
|
|
72
|
+
### 步骤 1:定位内核文件
|
|
73
|
+
|
|
74
|
+
```sh
|
|
75
|
+
node tools/apply-softcut-port.mjs --check
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
预期输出之一:
|
|
79
|
+
|
|
80
|
+
```
|
|
81
|
+
内核文件:<你的路径>/node_modules/@deepseek-ai/dsh-agent-loop/lib/index.js
|
|
82
|
+
移植状态:未应用 ✗
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
脚本会自动定位。若提示未找到,说明 DSH 不在当前工作目录下,请用环境变量指定:
|
|
86
|
+
|
|
87
|
+
```sh
|
|
88
|
+
# PowerShell
|
|
89
|
+
$env:SOFTCUT_TARGET = '<内核 lib/index.js 的绝对路径>'
|
|
90
|
+
|
|
91
|
+
# bash / zsh
|
|
92
|
+
SOFTCUT_TARGET='<绝对路径>' node tools/apply-softcut-port.mjs --check
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
查找方法:在 DSH 安装目录的 `node_modules` 下找 `@deepseek-ai/dsh-agent-loop/lib/index.js`。
|
|
96
|
+
|
|
97
|
+
> **注意**:pnpm 的内容寻址目录名(形如 `@deepseek-ai+dsh-agent-loop_<哈希>`)**每次 DSH 升级都会变**,所以不要把路径写进任何脚本或配置——脚本每次运行都会重新解析。
|
|
98
|
+
|
|
99
|
+
### 步骤 2:先在副本上试跑(可选但推荐)
|
|
100
|
+
|
|
101
|
+
```sh
|
|
102
|
+
# 复制一份到临时目录预演,确认替换锚点能匹配
|
|
103
|
+
cp <内核文件> /tmp/agent-loop-test.js
|
|
104
|
+
SOFTCUT_TARGET=/tmp/agent-loop-test.js node tools/apply-softcut-port.mjs
|
|
105
|
+
node --check /tmp/agent-loop-test.js
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
若报「锚点校验失败」,说明当前内核版本的代码排版与移植脚本的假设不一致。**请不要放宽匹配条件**——那会导致改坏内核。脚本会打印具体是哪一处锚点没匹配上,请对照排查。
|
|
109
|
+
|
|
110
|
+
### 步骤 3:应用到真实内核
|
|
111
|
+
|
|
112
|
+
```sh
|
|
113
|
+
node tools/apply-softcut-port.mjs
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
预期输出:
|
|
117
|
+
|
|
118
|
+
```
|
|
119
|
+
内核文件:<路径>
|
|
120
|
+
已备份 → <路径>.bak-pre-softcut-port
|
|
121
|
+
✓ A. 新增 soft-cut 常量与分类预算纯函数
|
|
122
|
+
✓ B. phase 初始化加 softCutBudget 分类计数
|
|
123
|
+
✓ C1. buildRequest 改用 requestSignal
|
|
124
|
+
✓ C2. 流循环内按间隔调用 agent/soft-cut 并按分类预算裁决
|
|
125
|
+
✓ D1. catch 分支区分自切与真错
|
|
126
|
+
✓ D2. catch 收尾 + 软切边界落盘续跑
|
|
127
|
+
✓ 移植完成。
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
脚本是**幂等**的:已应用时再次运行会直接跳过,不会重复改写。
|
|
131
|
+
|
|
132
|
+
### 步骤 4:重启 DSH
|
|
133
|
+
|
|
134
|
+
**必须重启**,否则改动不会生效。运行中的进程已经把代码载入内存,磁盘上的变更对它无影响。
|
|
135
|
+
|
|
136
|
+
### 步骤 5:验证
|
|
137
|
+
|
|
138
|
+
打开设置 → 「COT 锚点」,确认顶部提示条变为**绿色「掐断能力正常」**。
|
|
139
|
+
|
|
140
|
+
如需进一步确认软切行为真的发生,可发一条容易触发打断的消息,再用取证脚本查看会话事件:
|
|
141
|
+
|
|
142
|
+
```sh
|
|
143
|
+
node tools/trace-softcut.mjs <解包后的 session.jsonl>
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
符合软切的输出特征:
|
|
147
|
+
|
|
148
|
+
```
|
|
149
|
+
1] ASSISTANT turn=1 step=1 interrupted=false textLen=… ← 前缀按正常消息落盘
|
|
150
|
+
2] INBOX/SPLICED target=next-step inserted=1
|
|
151
|
+
3] == step/start == turn=1 step=2 ← 切开了
|
|
152
|
+
4] USER source=plugin:dsh-cot-anchor ← 插件注入
|
|
153
|
+
5] ASSISTANT turn=1 step=2 interrupted=false textLen=… ← 从断点继续
|
|
154
|
+
6] == turn/end == turn=1 {"kind":"completed"} ← 完整跑通,不是 aborted
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
会话日志是 zstd 压缩的(`session.v3.jsonl.zstd` / `session.v4.jsonl.zstd`),需先解包为明文 JSONL。
|
|
158
|
+
|
|
159
|
+
#### 移植后的一次实测确认
|
|
160
|
+
|
|
161
|
+
在一台 0.2.0 系列、已应用本移植(内核源码中可见 `DSH-SOFT-CUT-PORT` 标记)的环境上,一个真实长任务会话中软切**实际触发 4 次**(打转判定 2 次、转折句判定 2 次),取证特征与上文一致:每次被切都留下一条没有 `usage` 字段的助手消息(共 4 条)、紧随一条 `target: next-step` 的 `agent/inbox/spliced`,回合以 `{"kind":"completed"}` 正常结束而非 aborted。注意同一条注入会先以 `agent/inbox/spliced`(inserted)出现、再以 `user/message`(claimed)落盘,计数时按消息 id 去重,不要把两处重复各计一次。即移植恢复的不仅是钩子注册,"切断—落盘—续跑"整条链路在真实任务中确实工作。
|
|
162
|
+
|
|
163
|
+
需要区分的是:**软切真实开火 ≠ 成功约束住模型**。同一会话里模型在被切、被注入"停止重新分析"后仍于后续步骤再次打转。移植解决的是"能力静默失效",不保证跨步骤空转被根治——该边界见 README「能力边界」一节。
|
|
164
|
+
|
|
165
|
+
## 四、移植原理
|
|
166
|
+
|
|
167
|
+
0.1.5-rc.2 的软切机构全部位于内核 `dsh-agent-loop` 内,插件仅提供"要不要切"的判定。两者的分工是:
|
|
168
|
+
|
|
169
|
+
- **插件(裁判)**:判断是否该切断,返回 `{ kind: "cut", budgetClass, contexts: [...] }`(`budgetClass` 声明请求哪类预算,见下文「分类软切预算」);
|
|
170
|
+
- **内核(剪刀)**:中断本次上游请求、把已生成部分按正常消息落盘、把上下文排入 next-step、继续本回合。
|
|
171
|
+
|
|
172
|
+
所以必须把"剪刀"补回内核,插件侧无需改动。移植共 4 处,均为**纯增量**(不改动原有逻辑,只插入缺失的代码路径):
|
|
173
|
+
|
|
174
|
+
| 处 | 位置(按代码语义定位,勿按行号) | 内容 |
|
|
175
|
+
| --- | --- | --- |
|
|
176
|
+
| **A** | 最后一条 `import` 之后 | 检查间隔(32 字符)与尾部窗口常量;三类有界预算 `HEURISTIC_CUT_MAX=6` / `CONFIRMED_REPEAT_CUT_MAX=20` / `CONFIRMED_PSEUDO_CUT_MAX=3` 与汇总对象 `SOFT_CUT_LIMITS`;hard-abort 固定错误串 `SOFT_CUT_PSEUDO_ABORT_MESSAGE`;两个自包含纯函数 `createSoftCutBudget()` / `decideSoftCut()` |
|
|
177
|
+
| **B** | `wakeDriver()` 内 `this.setPhase({ kind: "running", … })` | 新增 `softCutBudget: createSoftCutBudget()` 分类计数(每次 turn 开始归零,防跨 turn 泄漏) |
|
|
178
|
+
| **C1** | `step()` 中 `firstAttempt = false;` 之后 | 声明独立的 `softCutAbort` 控制器与 `requestSignal`;`buildRequest()` 的最后一个 `signal` 实参改用 `requestSignal` |
|
|
179
|
+
| **C2** | `for await (const chunk of stream)` 循环内 | 累积 `text-delta` / `reasoning-delta`;每满 32 字符调用 `agent/soft-cut` waterfall(payload 附 `budgets` 三类快照,**无前置总闸**——每个检查点必达插件);返回 cut 后经 `decideSoftCut` 三分支:`cut` 中止上游请求并跳出,`reject` 继续生成,`hard-abort` 发出 `agent/error` 后中止当前 turn |
|
|
180
|
+
| **D1** | `step()` 内 `catch` 开头 | 区分"自己切的"与"真出错",避免软切被当成错误 |
|
|
181
|
+
| **D2** | 紧随其后的 `try { const finish = …` 之前 | 软切边界:前缀按**正常** `assistant/message` 落盘(不带 `interrupted` 标记)、按 `trimTo` 裁掉重复尾巴、把上下文排入 next-step 让回合续跑 |
|
|
182
|
+
|
|
183
|
+
C1 是最关键的一处:它让中断**只作用于当前这一次上游请求**,而不是整个 turn——这正是"切一刀后继续"与"整轮急停"的区别。
|
|
184
|
+
|
|
185
|
+
### 分类软切预算(0.2.0 起)
|
|
186
|
+
|
|
187
|
+
每 turn 三类独立计数、互不挤占,全部有界:
|
|
188
|
+
|
|
189
|
+
| 类别(wire 枚举) | 预算键(驼峰) | 上限/turn | 覆盖触发 |
|
|
190
|
+
| --- | --- | --- | --- |
|
|
191
|
+
| `heuristic` | `heuristic` | 6 | churn(语义空转)、transition(转折句)等启发式判定 |
|
|
192
|
+
| `confirmed-repeat` | `confirmedRepeat` | 20 | repeat(字节级复读)、numberRunaway(递增数字流) |
|
|
193
|
+
| `confirmed-pseudo` | `confirmedPseudo` | 3 | pseudoTool(文本化伪工具调用) |
|
|
194
|
+
|
|
195
|
+
裁决规则(内核侧纯函数 `decideSoftCut`,输入 `budgetClass` 与该类余量):
|
|
196
|
+
|
|
197
|
+
- 该类计数未达上限 → `cut`:正常软切,计数 +1;
|
|
198
|
+
- 该类已达上限 → `reject`:该类后续决策被**静默忽略**(流继续、不裁尾、不注入);
|
|
199
|
+
- `confirmed-pseudo` 已达上限 → **`hard-abort`**:内核向会话发出 `agent/error`(错误消息固定为 `cot-anchor-budget-pseudo-abort`)并中止当前 turn。理由:伪调用误报的"cut→新 step→再误报"自我循环会让 turn 永不可完成,与其无限软切不如硬停让用户介入。
|
|
200
|
+
|
|
201
|
+
兼容口径:插件决策**缺少** `budgetClass` 字段(0.1.5 及更早版本的插件)或取值未知时,一律按 `heuristic` 归类。waterfall payload 的 `budgets` 字段仅作观测快照,不参与裁决。
|
|
202
|
+
|
|
203
|
+
移植依赖的 6 项内核能力在新版中均已存在,属纯增量,不需要额外安装依赖:`interruptedBlocks()`、`inbox.splice()`、`AssistantStreamAttempt`、`live.settle()`、`createAssistantMessage`、`AbortSignal.any`。
|
|
204
|
+
|
|
205
|
+
## 五、风险与回滚
|
|
206
|
+
|
|
207
|
+
### 风险
|
|
208
|
+
|
|
209
|
+
- **补丁与内核版本耦合**:上游若改动了 `step()` 的代码排版,移植脚本的锚点将无法匹配(此时脚本会安全中止、不改动文件,但软切不会生效)。
|
|
210
|
+
- **内核升级会覆盖补丁**:`pnpm install` / `pnpm update` 会重新写入 `dsh-agent-loop`,补丁随之消失,且**不会报错**。升级后请重跑本补丁。
|
|
211
|
+
- **内核补丁可能与上游未来版本冲突**,极端情况下导致 DSH 启动失败。
|
|
212
|
+
|
|
213
|
+
### 建议
|
|
214
|
+
|
|
215
|
+
1. 先在测试用 profile 上验证,再用于日常环境。
|
|
216
|
+
2. 升级 DSH 前后各跑一次 `--check`,确认状态。
|
|
217
|
+
3. 养成看设置页能力提示的习惯——它比任何日志都可靠。
|
|
218
|
+
|
|
219
|
+
### 回滚
|
|
220
|
+
|
|
221
|
+
```sh
|
|
222
|
+
node tools/apply-softcut-port.mjs --revert
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
脚本会读取首次改写时创建的 `<文件>.bak-pre-softcut-port` 还原。**回滚后同样需要重启 DSH。**
|
|
226
|
+
|
|
227
|
+
若备份不存在(说明从未在本机应用过移植),无需回滚。
|
|
228
|
+
|
|
229
|
+
### 从旧版移植升级(0.1.6 及更早应用过单闸版移植)
|
|
230
|
+
|
|
231
|
+
旧版移植(`softCuts` 单计数、`MAX_SOFT_CUTS_PER_TURN` 总闸)的改写产物与新锚点不兼容,直接应用会因锚点失配**零写入退出**。升级路径:
|
|
232
|
+
|
|
233
|
+
```sh
|
|
234
|
+
node tools/apply-softcut-port.mjs --revert # 还原旧移植(读 .bak-pre-softcut-port 备份)
|
|
235
|
+
node tools/apply-softcut-port.mjs # 应用新版移植(重新备份后写入)
|
|
236
|
+
node tools/apply-softcut-port.mjs --check # 确认「已应用」
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
若 `--revert` 报备份不存在而内核源码里仍有旧移植痕迹,说明备份曾被覆盖——此时先重装 DSH(恢复 pristine 内核)再执行新版移植。
|
|
240
|
+
|
|
241
|
+
## 六、排障
|
|
242
|
+
|
|
243
|
+
| 现象 | 原因与处理 |
|
|
244
|
+
| --- | --- |
|
|
245
|
+
| 脚本提示「未找到 dsh-agent-loop 内核文件」 | DSH 不在当前工作目录。用 `SOFTCUT_TARGET` 指定绝对路径。 |
|
|
246
|
+
| 脚本提示「锚点校验失败」 | 当前内核排版与脚本假设不一致。**不要放宽匹配**。脚本会指明具体是哪一处,据此人工比对。 |
|
|
247
|
+
| 运行后设置页仍显示「没有掐断能力」 | 未重启 DSH,或重启的不是你改动的那个安装实例。 |
|
|
248
|
+
| `node --check` 报语法错 | 移植被部分写入。执行 `--revert` 还原后重新排查。 |
|
|
249
|
+
| Windows 计划任务里执行脚本报 `2147942402` | 计划任务解析不到 `node`。在任务里写 `node.exe` 的**绝对路径**。 |
|
|
250
|
+
|
|
251
|
+
## 七、已知限制
|
|
252
|
+
|
|
253
|
+
- 软切是**尽力而为**的启发式机制,判定基于字符串特征,不理解语义。正常思考中出现转折句也可能被切断(代价较低:模型从断点继续,不会丢失工作)。
|
|
254
|
+
- 单个回合每类软切各有上限且全部有界:启发式 6 次、确证复读 20 次、伪工具 3 次;启发式与确证复读超限后该类被静默忽略,伪工具超限升级为硬中止(见「分类软切预算」)。
|
|
255
|
+
- 本插件**不会中止进行中的回合**。它只在模型自己写坏输出时切断当前这一次生成请求,随后继续。若你看到回合被整体取消,那不是本插件的行为。
|
|
256
|
+
- 补丁不修复其它因内核升级而失效的能力。本插件的结论注入与设置页在所有版本均可用。
|
|
257
|
+
- 移植脚本按 DSH 0.1.5-rc.2 的实现写就,面向 0.1.5-rc.3 至 0.2.x。更新到更高版本后可能需要按新排版调整锚点。
|