harness-reflex 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/CHANGELOG.md +20 -0
- package/README.md +266 -2
- package/USER_GUIDE.md +639 -0
- package/dist/adapters/agy.d.ts +8 -0
- package/dist/adapters/agy.js +80 -0
- package/dist/adapters/agy.js.map +1 -0
- package/dist/adapters/claude.d.ts +13 -0
- package/dist/adapters/claude.js +46 -0
- package/dist/adapters/claude.js.map +1 -0
- package/dist/adapters/codex.d.ts +139 -0
- package/dist/adapters/codex.js +368 -0
- package/dist/adapters/codex.js.map +1 -0
- package/dist/backend/defaults.d.ts +31 -0
- package/dist/backend/defaults.js +32 -0
- package/dist/backend/defaults.js.map +1 -0
- package/dist/backend/factory.d.ts +11 -0
- package/dist/backend/factory.js +40 -0
- package/dist/backend/factory.js.map +1 -0
- package/dist/backend/jev.d.ts +524 -0
- package/dist/backend/jev.js +1486 -0
- package/dist/backend/jev.js.map +1 -0
- package/dist/backend/mock.d.ts +26 -0
- package/dist/backend/mock.js +320 -0
- package/dist/backend/mock.js.map +1 -0
- package/dist/backend/route-prompt.d.ts +37 -0
- package/dist/backend/route-prompt.js +42 -0
- package/dist/backend/route-prompt.js.map +1 -0
- package/dist/backend/simple-jev.d.ts +35 -0
- package/dist/backend/simple-jev.js +273 -0
- package/dist/backend/simple-jev.js.map +1 -0
- package/dist/backend/types.d.ts +270 -0
- package/dist/backend/types.js +5 -0
- package/dist/backend/types.js.map +1 -0
- package/dist/cli/index.d.ts +2 -0
- package/dist/cli/index.js +278 -0
- package/dist/cli/index.js.map +1 -0
- package/dist/core/calibrate.d.ts +56 -0
- package/dist/core/calibrate.js +144 -0
- package/dist/core/calibrate.js.map +1 -0
- package/dist/core/closing.d.ts +90 -0
- package/dist/core/closing.js +111 -0
- package/dist/core/closing.js.map +1 -0
- package/dist/core/evidence.d.ts +119 -0
- package/dist/core/evidence.js +209 -0
- package/dist/core/evidence.js.map +1 -0
- package/dist/core/gate.d.ts +25 -0
- package/dist/core/gate.js +114 -0
- package/dist/core/gate.js.map +1 -0
- package/dist/core/judge.d.ts +221 -0
- package/dist/core/judge.js +251 -0
- package/dist/core/judge.js.map +1 -0
- package/dist/core/ledger.d.ts +67 -0
- package/dist/core/ledger.js +173 -0
- package/dist/core/ledger.js.map +1 -0
- package/dist/core/orchestrate-closing.d.ts +237 -0
- package/dist/core/orchestrate-closing.js +250 -0
- package/dist/core/orchestrate-closing.js.map +1 -0
- package/dist/core/orchestrate-correction.d.ts +209 -0
- package/dist/core/orchestrate-correction.js +141 -0
- package/dist/core/orchestrate-correction.js.map +1 -0
- package/dist/core/orchestrate-host.d.ts +225 -0
- package/dist/core/orchestrate-host.js +80 -0
- package/dist/core/orchestrate-host.js.map +1 -0
- package/dist/core/orchestrate-stagnation.d.ts +259 -0
- package/dist/core/orchestrate-stagnation.js +270 -0
- package/dist/core/orchestrate-stagnation.js.map +1 -0
- package/dist/core/orchestrate.d.ts +357 -0
- package/dist/core/orchestrate.js +418 -0
- package/dist/core/orchestrate.js.map +1 -0
- package/dist/core/policy.d.ts +122 -0
- package/dist/core/policy.js +102 -0
- package/dist/core/policy.js.map +1 -0
- package/dist/core/prune-plan.d.ts +141 -0
- package/dist/core/prune-plan.js +390 -0
- package/dist/core/prune-plan.js.map +1 -0
- package/dist/core/prune.d.ts +30 -0
- package/dist/core/prune.js +73 -0
- package/dist/core/prune.js.map +1 -0
- package/dist/core/route.d.ts +35 -0
- package/dist/core/route.js +39 -0
- package/dist/core/route.js.map +1 -0
- package/dist/core/score.d.ts +40 -0
- package/dist/core/score.js +49 -0
- package/dist/core/score.js.map +1 -0
- package/dist/core/screen.d.ts +22 -0
- package/dist/core/screen.js +117 -0
- package/dist/core/screen.js.map +1 -0
- package/dist/core/stagnation.d.ts +23 -0
- package/dist/core/stagnation.js +93 -0
- package/dist/core/stagnation.js.map +1 -0
- package/dist/core/text.d.ts +36 -0
- package/dist/core/text.js +66 -0
- package/dist/core/text.js.map +1 -0
- package/dist/hook/cli.d.ts +9 -0
- package/dist/hook/cli.js +52 -0
- package/dist/hook/cli.js.map +1 -0
- package/dist/hook/contract.d.ts +125 -0
- package/dist/hook/contract.js +159 -0
- package/dist/hook/contract.js.map +1 -0
- package/dist/hook/decision.d.ts +97 -0
- package/dist/hook/decision.js +955 -0
- package/dist/hook/decision.js.map +1 -0
- package/dist/hook/memory-store.d.ts +81 -0
- package/dist/hook/memory-store.js +157 -0
- package/dist/hook/memory-store.js.map +1 -0
- package/dist/hook/payload.d.ts +55 -0
- package/dist/hook/payload.js +129 -0
- package/dist/hook/payload.js.map +1 -0
- package/dist/hook/run.d.ts +48 -0
- package/dist/hook/run.js +218 -0
- package/dist/hook/run.js.map +1 -0
- package/dist/hook/store-port.d.ts +72 -0
- package/dist/hook/store-port.js +2 -0
- package/dist/hook/store-port.js.map +1 -0
- package/dist/index.d.ts +18 -0
- package/dist/index.js +19 -0
- package/dist/index.js.map +1 -0
- package/dist/mcp/server.d.ts +12 -0
- package/dist/mcp/server.js +368 -0
- package/dist/mcp/server.js.map +1 -0
- package/dist/ports/audit.d.ts +18 -0
- package/dist/ports/audit.js +11 -0
- package/dist/ports/audit.js.map +1 -0
- package/dist/ports/clock.d.ts +14 -0
- package/dist/ports/clock.js +11 -0
- package/dist/ports/clock.js.map +1 -0
- package/dist/ports/decision.d.ts +75 -0
- package/dist/ports/decision.js +2 -0
- package/dist/ports/decision.js.map +1 -0
- package/dist/ports/index.d.ts +14 -0
- package/dist/ports/index.js +2 -0
- package/dist/ports/index.js.map +1 -0
- package/dist/ports/log.d.ts +22 -0
- package/dist/ports/log.js +12 -0
- package/dist/ports/log.js.map +1 -0
- package/dist/ports/state.d.ts +46 -0
- package/dist/ports/state.js +13 -0
- package/dist/ports/state.js.map +1 -0
- package/dist/state/clock.d.ts +40 -0
- package/dist/state/clock.js +43 -0
- package/dist/state/clock.js.map +1 -0
- package/dist/state/file-store.d.ts +340 -0
- package/dist/state/file-store.js +849 -0
- package/dist/state/file-store.js.map +1 -0
- package/dist/state/paths.d.ts +41 -0
- package/dist/state/paths.js +73 -0
- package/dist/state/paths.js.map +1 -0
- package/docs/USER_GUIDE.en.md +721 -0
- package/docs/claude-code.md +281 -0
- package/docs/design/v0.2.0-harness-plugins.md +381 -0
- package/docs/design/v0.3.0-orchestration-unification.md +580 -0
- package/docs/dsh-plugin.md +578 -0
- package/docs/reflex-ui-regression-2026-10-20.md +34 -0
- package/docs/release-checklist-v0.1.0.md +315 -0
- package/docs/release-handbook-porting-notes.md +106 -0
- package/docs/release-handbook.md +393 -0
- package/docs/release-notes-v0.1.0.md +63 -0
- package/docs/release-notes-v0.3.0.md +152 -0
- package/docs/research/claude-code-harness.md +607 -0
- package/docs/research/pi-harness.md +621 -0
- package/experiments/data/calibration_sample.json +14 -0
- package/experiments/index.ts +29 -0
- package/experiments/runner.ts +156 -0
- package/package.json +82 -4
package/USER_GUIDE.md
ADDED
|
@@ -0,0 +1,639 @@
|
|
|
1
|
+
# Harness Reflex 使用说明(v0.3.0)
|
|
2
|
+
|
|
3
|
+
> 本文档是 **`dsh-harness-reflex` 插件** 与 **`harness-reflex` 核心包** 的完整使用手册。
|
|
4
|
+
> 同一份内容会内嵌进 `packages/dsh-harness-reflex/client.js`,可在 DSH 设置面板的
|
|
5
|
+
> **「使用说明 / Guide」** 标签页内直接阅读(跟随 DSH 界面语言中英切换)。
|
|
6
|
+
> 因此修改本文档后必须重新执行 `npm run build:all`,否则面板里仍是上一次构建的副本
|
|
7
|
+
> (`npm run test:plugin` 会用文档摘要做漂移校验)。
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## 1. Harness Reflex 是什么
|
|
12
|
+
|
|
13
|
+
Harness Reflex 是一个 **System One(快思考)决策运行时**:它在不调用昂贵
|
|
14
|
+
System Two 生成式推理的前提下,用毫秒级的概率判定完成门禁校验、上下文剪枝、
|
|
15
|
+
死循环拦截、模型路由与推理强度决策,并把每一次决策写进可审计的决策账本。
|
|
16
|
+
|
|
17
|
+
它有两种交付形态,共享同一套判定引擎,但**对外工具面不同**(见第 9 节):
|
|
18
|
+
|
|
19
|
+
| 形态 | 包 | 适用 Harness | 通信方式 |
|
|
20
|
+
| --- | --- | --- | --- |
|
|
21
|
+
| stdio MCP 服务器 | `harness-reflex` | Claude Code、Codex CLI、AGY | MCP JSON-RPC 子进程 |
|
|
22
|
+
| DSH Host 插件 | `dsh-harness-reflex` | DeepSeek Harness (`dsh`) | 进程内 `ctx.tools` / Cordis 钩子 |
|
|
23
|
+
|
|
24
|
+
MCP 面暴露 8 个工具;DSH 面只注册 5 个可开关工具(默认 4 个),剪枝/停滞/账本由自动干预与
|
|
25
|
+
`/reflex-ledger` 命令承载。参数及校验边界以第 9 节和各表面实际工具定义为准。
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
## 2. 插件架构
|
|
30
|
+
|
|
31
|
+
```text
|
|
32
|
+
┌──────────────────────────────────────────────────────────────────────┐
|
|
33
|
+
│ Harness Layer │
|
|
34
|
+
│ Claude Code (.mcp.json) · Codex (.codex/config.json) · AGY 插件包 │
|
|
35
|
+
└───────────────┬──────────────────────────────────┬───────────────────┘
|
|
36
|
+
│ stdio MCP │ DSH Cordis 进程内
|
|
37
|
+
┌───────────────▼──────────────────┐ ┌────────────▼───────────────────┐
|
|
38
|
+
│ harness-reflex 核心(dist/) │ │ dsh-harness-reflex 插件 │
|
|
39
|
+
│ gate · prune · stagnation │◄─┤ src/bridge.ts ReflexRuntime │
|
|
40
|
+
│ route · screen · score │ │ src/tools.ts 5 个可开关工具 │
|
|
41
|
+
│ ledger · calibrate │ │ src/router.ts 虚拟 Provider │
|
|
42
|
+
└───────────────┬──────────────────┘ │ src/effort.ts 推理强度拦截 │
|
|
43
|
+
│ DecisionBackend │ src/panel-* 设置面板 + API │
|
|
44
|
+
┌───────────────▼──────────────────┐ └────────────┬───────────────────┘
|
|
45
|
+
│ mock · simple-jev/vLLM · 官方 Jev │ │ settings.section
|
|
46
|
+
└──────────────────────────────────┘ ┌────────────▼───────────────────┐
|
|
47
|
+
│ client.js 浏览器面板(React) │
|
|
48
|
+
│ 概览/虚拟 Provider/推理强度/ │
|
|
49
|
+
│ System 1 后端/自动干预/工具开关/ │
|
|
50
|
+
│ 决策账本/使用说明 │
|
|
51
|
+
└────────────────────────────────┘
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
关键模块一览(插件侧):
|
|
55
|
+
|
|
56
|
+
| 文件 | 职责 |
|
|
57
|
+
| --- | --- |
|
|
58
|
+
| `src/index.ts` | Cordis 插件入口 `apply(ctx, config)`,注册与拆除都在一个 `ctx.effect` 内 |
|
|
59
|
+
| `src/bridge.ts` | `ReflexRuntime`:一次激活的 backend / ledger / 校准器 / 决策服务集合 |
|
|
60
|
+
| `src/tools.ts` | 5 个可开关 `reflex_*` 工具,默认注册 4 个(Host `defineTool` 严格校验 + 顶层未声明参数拦截) |
|
|
61
|
+
| `src/router.ts` | `VirtualModelRouter`:候选池 → System 1 决策 → 降级 / Fail-Closed → 审计 |
|
|
62
|
+
| `src/virtual-adapter.ts` | 虚拟 provider 的 `LlmAdapter` 表面与派发层兜底 |
|
|
63
|
+
| `src/routing.ts` | `installModelRouting`:注册虚拟 provider,挂 `agent/pre-step`、`agent/request` |
|
|
64
|
+
| `src/effort.ts` | `EffortInterceptor`:每轮推理强度判定、投影与状态上报 |
|
|
65
|
+
| `src/session-audit.ts` | 写/读 `plugin:dsh-reflex/effort` 会话记录(不污染模型上下文) |
|
|
66
|
+
| `src/panel-api.ts` | 设置面板只读投影 + `/dsh-reflex/api/*` 路由(仅 loopback) |
|
|
67
|
+
| `src/client/*` | 浏览器半边:槽位注册、中英文案、Markdown 渲染、面板视图 |
|
|
68
|
+
|
|
69
|
+
启动顺序:DSH 载入插件 → `apply` 解析配置 → 建立 `ReflexRuntime` → 注册虚拟
|
|
70
|
+
provider 与请求钩子 → 注册默认 4 个工具(`route` 打开后 5 个)→ 注册
|
|
71
|
+
`/reflex-ledger` 命令 → 挂载面板路由。卸载时逆序注销,完全可逆。
|
|
72
|
+
|
|
73
|
+
---
|
|
74
|
+
|
|
75
|
+
## 3. 安装与构建
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
# 1) 安装依赖并构建(根包 → 链接本机 DSH 依赖 → 插件 → 浏览器 bundle)
|
|
79
|
+
npm install
|
|
80
|
+
npm run build:all
|
|
81
|
+
|
|
82
|
+
# 2) 配置目标 Harness(生成 .mcp.json / .codex/config.json / AGY 插件包)
|
|
83
|
+
node dist/cli/index.js setup all # 或 claude | codex | agy
|
|
84
|
+
|
|
85
|
+
# 3) 以 DSH 插件方式安装(进程内集成,推荐)
|
|
86
|
+
# 发布 tarball:同版本重装必须 --force;开发期也可直接装目录
|
|
87
|
+
dsh plugin --profile web add --force ./release/dsh-harness-reflex-0.3.0.tgz
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
`npm run build:all` 的每一步都是必需的:
|
|
91
|
+
|
|
92
|
+
1. `tsc`:根包 `src/` → `dist/`;
|
|
93
|
+
2. `node scripts/link-dsh-deps.mjs`:把本机 DSH 的 `@deepseek-ai/*` 软链进
|
|
94
|
+
`packages/dsh-harness-reflex/node_modules/`(完全离线,不访问 registry);
|
|
95
|
+
3. `tsc -p packages/dsh-harness-reflex/tsconfig.json`:插件 Host 半边 → `packages/dsh-harness-reflex/dist/`;
|
|
96
|
+
4. `node scripts/embed-user-guide.mjs` + `tsc -p tsconfig.client.json` +
|
|
97
|
+
`node packages/dsh-harness-reflex/dist/client-bundle.js packages/dsh-harness-reflex`:
|
|
98
|
+
把本文档内嵌进浏览器半边并产出单文件 `client.js`。
|
|
99
|
+
|
|
100
|
+
> 构建顺序不可交换:`client.js` 必须晚于本文档的修改,否则面板显示的说明与仓库文档不一致。
|
|
101
|
+
|
|
102
|
+
---
|
|
103
|
+
|
|
104
|
+
## 4. System 1 后端接入配置
|
|
105
|
+
|
|
106
|
+
三种后端共用一套 `SYSTEM_ONE_*` 环境变量与插件配置项,选择顺序为
|
|
107
|
+
「插件配置 > 环境变量 > 默认 mock」。
|
|
108
|
+
|
|
109
|
+
| 后端 | 取值 | 说明 |
|
|
110
|
+
| --- | --- | --- |
|
|
111
|
+
| 本地启发式(默认) | `mock` | 确定性、零网络、亚毫秒级;用于离线开发与测试 |
|
|
112
|
+
| 通用 logits 读出 | `simple-jev` | vLLM / OpenAI 兼容接口的 `max_tokens: 1` + `next-token logprobs` |
|
|
113
|
+
| 官方 Jev / System One API | `jev` | `POST {BASE_URL}/v1/...`,需 API Key |
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
# 官方 Jev:只有 key 是必填
|
|
117
|
+
export SYSTEM_ONE_API_KEY="your-api-key"
|
|
118
|
+
|
|
119
|
+
# 自托管 vLLM(OpenAI 兼容):只有地址是必填
|
|
120
|
+
export SYSTEM_ONE_BASE_URL="http://localhost:8000"
|
|
121
|
+
export SYSTEM_ONE_BACKEND=simple-jev # 省略也能判定:检测到 VLLM_BASE_URL/OPENAI_BASE_URL 即为 simple-jev
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
不显式设 `SYSTEM_ONE_BACKEND` 时的判定顺序:有 `SYSTEM_ONE_API_KEY`/`JEV_API_KEY` → `jev`;
|
|
125
|
+
有 `VLLM_BASE_URL`/`OPENAI_BASE_URL` → `simple-jev`;都没有 → `mock`。
|
|
126
|
+
|
|
127
|
+
三份默认值都取决于后端,不要凭「默认 mock」推断另外两个:
|
|
128
|
+
|
|
129
|
+
| 变量 | `jev` | `simple-jev` |
|
|
130
|
+
| --- | --- | --- |
|
|
131
|
+
| `SYSTEM_ONE_BASE_URL` | `https://api.typesafe.ai/v1/systemone` | `http://localhost:8000` |
|
|
132
|
+
| `SYSTEM_ONE_MODEL` | `jev-latest` | `Qwen/Qwen2.5-7B-Instruct` |
|
|
133
|
+
| `SYSTEM_ONE_API_KEY` | **无**(空串,请求会被服务端拒绝) | `dummy`(本地服务通常不校验) |
|
|
134
|
+
|
|
135
|
+
**连接只来自「当前激活的连接配置」**(面板「System 1 后端」页的「连接配置(可多套)」)。
|
|
136
|
+
没有激活项时插件就是**未配置**状态:面板明确显示未配置,插件不发任何外部请求,
|
|
137
|
+
判定改走本地确定性启发式。激活名写错时也不会被悄悄换成别的连接。
|
|
138
|
+
|
|
139
|
+
每一套连接配置的字段(写进 DSH 插件配置时位于 `systemOne.profiles.<名字>`):
|
|
140
|
+
|
|
141
|
+
| 配置 | 默认 | 说明 |
|
|
142
|
+
| --- | --- | --- |
|
|
143
|
+
| `baseUrl` | 省略 | System 1 服务地址;省略时由后端按环境变量/默认值决定 |
|
|
144
|
+
| `modelIds` | 省略 | 这套连接可用的**模型 ID 列表**(可多个)。`model` 是单模型写法,等同于只含一项的列表 |
|
|
145
|
+
| `selectedModel` | 列表第一项 | **唯一选定的模型**:运行时发送它,「测试」按钮探活也用它。必须是 `modelIds` 里的一项:保存时就会拒绝不在列表里的选择;手改文件绕过校验时,运行时不建立任何连接(面板显示未配置),不会改发默认模型 |
|
|
146
|
+
| `apiKey` | 省略 | 密钥本身;**只写不读**——保存后不回显,页面只显示「已保存」。**改名不会带着它走**:改名后需要重新填写(见下) |
|
|
147
|
+
| `apiKeyEnv` | 省略 | **只记录环境变量名**;省略时不点名,由后端按 `SYSTEM_ONE_API_KEY` → `JEV_API_KEY` → `VLLM_API_KEY` → `OPENAI_API_KEY` 兜底;点名即锁定,不回落 |
|
|
148
|
+
| `timeoutMs` | 省略 | 单次判定超时;省略时用**后端默认值 `jev` 10000 ms / `simple-jev` 8000 ms**,不是统一值 |
|
|
149
|
+
| `backend` | 省略 | 这套连接使用的后端实现;省略时用顶层 `backend` |
|
|
150
|
+
|
|
151
|
+
顶层的 `backend` 只是「连接未指定实现时用哪个」(`auto` 按环境变量判定,也可强制
|
|
152
|
+
`mock` / `vllm` / `jev`),它本身不构成连接。显式 `backend: mock` 仍然有效:那是
|
|
153
|
+
主动选择本地实现,不需要连接配置。
|
|
154
|
+
|
|
155
|
+
**改名与只写密钥.** 连接的「名字」就是它在设置文档里的路径,所以改名等于换一个
|
|
156
|
+
保存路径,Host 无法把已保存的密钥搬到新名字下。面板因此会**阻止保存**并点名该行,
|
|
157
|
+
要求重新填写 API Key(来源是环境变量的连接不受影响,改名照常保存)。同时改两个
|
|
158
|
+
名字互换、或改到一个已被别的已保存配置占用的名字,也会被拦下并说明原因。
|
|
159
|
+
|
|
160
|
+
`systemOne` 顶层同名的 `baseUrl` / `model` / `apiKeyEnv` / `timeoutMs` 不参与连接:
|
|
161
|
+
它们不构成一套连接配置。文件里若还留着这些字段,面板既不读取也不改写它们。
|
|
162
|
+
|
|
163
|
+
校准曲线(可选):用 `calibrate` 引擎基于历史标注集拟合 ECE/PAVA 曲线,再用
|
|
164
|
+
`calibrationPath` 指向该 JSON,运行时会自动修正过度自信的原始概率。
|
|
165
|
+
|
|
166
|
+
---
|
|
167
|
+
|
|
168
|
+
## 5. 虚拟 Provider 与模型池
|
|
169
|
+
|
|
170
|
+
**概念.** 插件注册一个虚拟 provider(默认 id `reflex`),它自己不产生任何
|
|
171
|
+
token:当请求落到 `reflex/reflex-auto` 这类虚拟模型上时,`agent/request` 钩子会
|
|
172
|
+
用 System 1 从该虚拟模型配置的**物理候选池**里选出一个真实 `provider/model`,
|
|
173
|
+
改写请求配置后继续派发,并写一条 `type: model-route` 台账。
|
|
174
|
+
|
|
175
|
+
配置结构(对应 YAML):
|
|
176
|
+
|
|
177
|
+
```yaml
|
|
178
|
+
routing:
|
|
179
|
+
enabled: true
|
|
180
|
+
virtualProvider: reflex
|
|
181
|
+
maxTaskChars: 400 # 每个 agent 参与打分的任务文本上限
|
|
182
|
+
fallback: deepseek:deepseek-chat # 池无法回答时的降级目标
|
|
183
|
+
models:
|
|
184
|
+
reflex-auto: # 虚拟模型 ID
|
|
185
|
+
- provider: deepseek
|
|
186
|
+
model: deepseek-reasoner
|
|
187
|
+
description: 长链路推理与代码重构
|
|
188
|
+
tags: [reasoning, expensive]
|
|
189
|
+
- provider: deepseek
|
|
190
|
+
model: deepseek-chat
|
|
191
|
+
description: 日常问答与快速编辑
|
|
192
|
+
tags: [fast, cheap]
|
|
193
|
+
reflex-fast:
|
|
194
|
+
- provider: deepseek
|
|
195
|
+
model: deepseek-chat
|
|
196
|
+
description: 低延迟场景
|
|
197
|
+
tags: [fast]
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
**规则与边界.**
|
|
201
|
+
|
|
202
|
+
- `enabled: false` 或 `models` 为空 ⇒ 不注册虚拟 provider,行为与未安装插件一致。
|
|
203
|
+
- 候选池为空且未配置 `fallback` ⇒ **Fail-Closed**:报错而不是乱派发。
|
|
204
|
+
- `virtualProvider` 不能包含 `:`;候选的 `provider` 与 `model` 都不能为空。
|
|
205
|
+
- 主代理与 subagent 都走同一条拦截链路,抗循环标识(loop identity)在改写后保持不变。
|
|
206
|
+
- 每次路由的候选、选择、置信度与耗时都会进账本,可在「决策账本」页回看。
|
|
207
|
+
- **每次调用的来源(g-068)**:每条决策账目与工具输出都带 `systemOneConnection`
|
|
208
|
+
(调用时生效的 System 1 连接名)、`systemOneModel`(本次**请求**的模型 ID)与
|
|
209
|
+
`systemOneSource` 之一 —— `remote`(由该连接作答)、`local`(该连接不发请求)、
|
|
210
|
+
`local-fallback`(远端尝试失败后本地作答)、`rejected`(远端失败且没有产出决策)
|
|
211
|
+
或 `unknown`(没有任何证据能证明来源)。`systemOneModel` 只是**请求**的模型:上游是否
|
|
212
|
+
接受或改写它,插件结构上看不到,因此任何地方都不把它当作「实际应答模型」。
|
|
213
|
+
切换连接不会改写历史条目;账本 JSONL 只追加、不重写。`/reflex-ledger` 与面板
|
|
214
|
+
「决策账本」页都显示这三项。
|
|
215
|
+
|
|
216
|
+
**上下文感知与会话粘性(省缓存、非必要不切换).** 换模型会让服务端的提示词前缀
|
|
217
|
+
缓存整体失效,因此路由不是「每轮重新选一次」,而是**默认守住这台会话已经在用的物理
|
|
218
|
+
模型**:
|
|
219
|
+
|
|
220
|
+
- 插件按 agent 累计本会话已观测到的上下文规模(`agent/pre-step` 送进来的输入字符数,
|
|
221
|
+
按 4 字符 ≈ 1 token 折算),每次决策都把它和**当前物理模型**一起交给 System 1
|
|
222
|
+
(请求里的 `state.currentModel` / `state.contextTokens` / `state.contextChars`)。
|
|
223
|
+
- 决策提示词里会同时给出这条策略:保留当前模型能保住提示词缓存,只有另一个候选
|
|
224
|
+
**明显更合适**时才切走;候选清单里当前模型还带
|
|
225
|
+
`[current model — keeping it preserves the prompt cache]` 标记与 `current: true` 标志,
|
|
226
|
+
文本型后端和结构化后端都能读到同一个信号。
|
|
227
|
+
- 后端排出名次后还有一道**粘性闸门**:挑战者必须分数更高、且高出当前模型
|
|
228
|
+
`stickyMargin`(默认 15%)的相对幅度,才会真的切换;并列或只是略优都保持不动。
|
|
229
|
+
- 账本的每条 `model-route` 都记下 `currentModel`、`switched` 与 `contextTokens`,
|
|
230
|
+
于是「这轮为什么没换模型」是可回看的,而不是靠猜。
|
|
231
|
+
- 粘性只在**同一个候选池**内生效:当前模型不在本轮候选里(例如换到另一个虚拟模型)
|
|
232
|
+
时,决策照常按 System 1 的名次走,`switched` 记为 `true`。
|
|
233
|
+
|
|
234
|
+
**在设置面板里配置.** 打开 DSH 设置 →「Reflex 决策运行时」→ **虚拟 Provider**:
|
|
235
|
+
顶部开关启用路由;填写虚拟 Provider 名称、兜底目标、任务文本预算;在「模型池」
|
|
236
|
+
里新增虚拟模型与候选(上移/下移调整顺序),点 **保存** 整体写回。面板的写入
|
|
237
|
+
会先过一遍 Host 侧同一个 `resolveConfig` 校验器,非法配置(空 ID、重复模型、
|
|
238
|
+
跨组错误)会被直接拒绝并给出对应错误文案。
|
|
239
|
+
|
|
240
|
+
---
|
|
241
|
+
|
|
242
|
+
## 6. 自适应思考等级(`reflex` / `auto`)
|
|
243
|
+
|
|
244
|
+
把推理强度策略设为 `reflex`(`auto` 与它同义)后,插件会在每轮真正发起 API 请求前
|
|
245
|
+
拦截输入意图与上下文,用 System 1 判定本轮需要的 `reasoningEffort`,再改写实际
|
|
246
|
+
下发的参数。
|
|
247
|
+
|
|
248
|
+
| 配置 | 默认 | 说明 |
|
|
249
|
+
| --- | --- | --- |
|
|
250
|
+
| `effort.reasoningEffort` | 省略 | `reflex` / `auto` = 每轮自适应;省略 = 不干预,插件完全不碰 `reasoningEffort`;具体档位请在模型选择器里选择,可选项取决于目标模型声明的档位集合 |
|
|
251
|
+
| `effort.fallback` | `medium` | System 1 不可用或置信度低于下限时,确定性线索投票的兜底档 |
|
|
252
|
+
| `effort.minConfidence` | `0.3` | 低于该置信度的判定不直接采用,改走兜底 |
|
|
253
|
+
| `effort.enabled` | `true` | 设为 `false` = 整层关闭:不判定、不审计、不注入 `reflex` 档位 |
|
|
254
|
+
|
|
255
|
+
配置只回答一个问题:**要不要启用自适应**。
|
|
256
|
+
|
|
257
|
+
- **留空(默认)= 不干预**:插件完全不改写 `reasoningEffort`,不产生判定与审计记录,行为与未安装该功能一致;
|
|
258
|
+
- **`reflex`(`auto` 同义)= 自适应**:每轮按 System 1 判定本轮档位;
|
|
259
|
+
- **想固定思考深度**:请在模型选择器里选择具体档位,可选项取决于目标模型声明的
|
|
260
|
+
档位集合;配置只接受留空或 `reflex`(`auto` 同义),写入其它值会在启动时被拒绝,
|
|
261
|
+
并提示把档位改到模型选择器里选择。
|
|
262
|
+
|
|
263
|
+
**行为约定.**
|
|
264
|
+
|
|
265
|
+
- 调用方在请求里显式选择的具体档位永远保持透明,插件不会覆盖;
|
|
266
|
+
- 目标模型不支持思考等级时安全降级,不会把参数原样塞给非思考模型;
|
|
267
|
+
- 每一轮都会向会话写入一条审计记录(`plugin:dsh-reflex/effort`),其中只包含
|
|
268
|
+
判定档位、置信度与截断后的任务摘录,**不进入后续模型上下文**;
|
|
269
|
+
- 判定结果同时投影到状态栏,可在「概览」页看到最近一次决策
|
|
270
|
+
(形如 `reflex: high (confidence 0.82, system-one, 12.4 ms)`)。
|
|
271
|
+
|
|
272
|
+
**关掉整层(`effort.enabled: false`).**
|
|
273
|
+
|
|
274
|
+
`effort.enabled` 是**能力开关**,与「策略是什么」相互独立:`reasoningEffort: reflex`
|
|
275
|
+
加上 `enabled: false` 是合法组合,语义等于完全不装这一段拦截(区别只在于配置仍
|
|
276
|
+
写着策略)。关闭后:
|
|
277
|
+
|
|
278
|
+
- **不判定**:不发起 System 1 调用、不做线索投票、不写判定缓存,也不发布
|
|
279
|
+
`reflex/effort` 状态——「概览」页不会出现本插件的最近决策;
|
|
280
|
+
- **不审计**:账本里没有 `effort-decision` 记录,会话日志里也没有
|
|
281
|
+
`plugin:dsh-reflex/effort` 记录;
|
|
282
|
+
- **不注入档位**:本插件注入的那一档(`reflex` / `auto`)从模型选择器里撤销,
|
|
283
|
+
只保留适配器自己声明的档位与其默认档;
|
|
284
|
+
- **具体档位原样下发**:调用方在请求里显式选择的 `high`、`medium` 等连「对齐到目标
|
|
285
|
+
模型词表」的改写都不做,逐字节保持原样;
|
|
286
|
+
- **标记安全兜底**:已有会话或手工构造的调用里若仍带着本插件的标记,标记在**物理
|
|
287
|
+
适配器边界被删除**,而不是被翻译成一个档位——最终生效的是 provider 自己的默认
|
|
288
|
+
档,插件标记永远不会泄漏给真实 provider。
|
|
289
|
+
|
|
290
|
+
默认 `true`(省略即 `true`),因此不写这一项时行为与显式写 `true` 逐字节一致。
|
|
291
|
+
|
|
292
|
+
---
|
|
293
|
+
|
|
294
|
+
## 7. 自动干预门禁(`off` / `observe` / `active`)
|
|
295
|
+
|
|
296
|
+
插件可以在**模型没有调用任何 `reflex_*` 工具**的情况下,用宿主原生钩子自行干预。
|
|
297
|
+
开关只有一处:`interventions.mode`,取值 `off` / `observe` / `active`,默认 `observe`:
|
|
298
|
+
|
|
299
|
+
```yaml
|
|
300
|
+
interventions:
|
|
301
|
+
mode: observe # off | observe | active
|
|
302
|
+
capabilities: # 可选:四大能力分别覆盖,inherit 表示跟随 mode
|
|
303
|
+
stagnation: inherit
|
|
304
|
+
prune: inherit
|
|
305
|
+
gate: inherit
|
|
306
|
+
closing: inherit
|
|
307
|
+
maxInterventionsPerTurn: 3
|
|
308
|
+
maxJudgmentsPerTurn: 3
|
|
309
|
+
maxJudgmentsPerSession: 20
|
|
310
|
+
```
|
|
311
|
+
|
|
312
|
+
四大能力各自是**四态**:`off` / `observe` / `active` 显式覆盖 `mode`,`inherit`
|
|
313
|
+
(或省略)跟随 `mode`。因此可以整体保持 `active`,只把 `prune` 单独降为
|
|
314
|
+
`observe`(只记账不剪枝),或反过来把整体设为 `off` 而只放开 `gate`。
|
|
315
|
+
|
|
316
|
+
| 模式 | 行为 |
|
|
317
|
+
| --- | --- |
|
|
318
|
+
| `off` | 不注册任何钩子监听器;工具执行与不装插件逐字节一致 |
|
|
319
|
+
| `observe`(默认) | 完整检测与判定,只记账不执行:不改写 content、不注入消息、不拒绝工具、不 steer |
|
|
320
|
+
| `active` | 完整链路:重复调用在执行前拒绝、超长结果在进入上下文前剪枝、重复失败改写为纠正反馈、回合收尾对有证据冲突的结论提出异议 |
|
|
321
|
+
|
|
322
|
+
| 能力 | 钩子 | `active` 时的动作 |
|
|
323
|
+
| --- | --- | --- |
|
|
324
|
+
| `stagnation` | `tools/pre-execute`、`agent/pre-step` | 判定重复/振荡后拒绝该次调用,或在下一次 step 注入纠正上下文 |
|
|
325
|
+
| `prune` | `tools/post-execute` | 结果超阈值时先保留原件再改写:原文写入会话日志并给出定位符,改写文本保留首尾并在中间标注定位符 |
|
|
326
|
+
| `gate` | `tools/post-execute` | 同一调用连续失败达阈值时,把结果改写为纠正反馈;失败与否只看工具源保证的结构化退出码或宿主退出标记 |
|
|
327
|
+
| `closing` | `agent/turn-stopping` | 用 `reflex_gate` 复核本回合的结论与证据,矛盾时 steer 一次 |
|
|
328
|
+
|
|
329
|
+
### 合法等待为什么不会被当成停滞(豁免默认值)
|
|
330
|
+
|
|
331
|
+
等待后台作业是合法行为,因此 `stagnation` 对**可结构识别的等待型调用**做了豁免。
|
|
332
|
+
判定只看两个结构化事实,**不读工具描述、也不读任何输出文本**:
|
|
333
|
+
|
|
334
|
+
1. **工具身份**:调用的是宿主自己的后台作业查询工具 `job_output`、`job_list`
|
|
335
|
+
(由 `@deepseek-ai/dsh-tool-jobs` 注册,shell 工具的后台作业也统一走 `job_output`);
|
|
336
|
+
2. **调用形态**:参数是宿主自己声明的作业句柄字段(`job_output` 的 `job_id` 非空字符串;
|
|
337
|
+
`job_list` 本身无参数,故以空参数对象为其形态)。
|
|
338
|
+
|
|
339
|
+
命中豁免的调用:不产生拒绝、不注入纠正上下文、不消耗 turn 的干预与判定额度,
|
|
340
|
+
`observe` 与 `active` 的计划完全一致;它仍会记录进检测窗口,只是不计入「无进展重复」
|
|
341
|
+
(重复、失败重试、振荡三类触发都跳过它),因此**真正的循环并不会因为中间等了一次作业而消失**。
|
|
342
|
+
`job_kill` 刻意不在豁免内——它是终止动作,不是等待查询。
|
|
343
|
+
输出文本里出现 `wait` / `sleep` / `poll` 等字样不构成任何豁免。
|
|
344
|
+
范围即上表所列的两个工具名;这是文档化的默认值,无需额外配置。
|
|
345
|
+
|
|
346
|
+
### 被剪掉的原文如何取回
|
|
347
|
+
|
|
348
|
+
`active` 剪枝的次序是「先保留、后替换」,这一步不能只有措辞:
|
|
349
|
+
|
|
350
|
+
1. 判定通过、且**保留成功**之后,才生成改写文本;
|
|
351
|
+
2. 原文以 `plugin:dsh-reflex/pruned-original` 记录写进会话日志(宿主 `appendPluginRecord`),
|
|
352
|
+
不进入模型可见面,`fork` / `resume` 会随日志一起带走;
|
|
353
|
+
3. 改写文本中间带上定位符 `plugin:dsh-reflex/pruned-original#<digest>`,模型因此随时可以
|
|
354
|
+
要求取回被省略的部分;
|
|
355
|
+
4. 保留失败(没有会话、日志缺失、写回校验不过)时**不替换**,也不计 `actualSavedTokens`,
|
|
356
|
+
结果逐字节保持原样(记为 `retention-failed`;这次判定已经付出,仍照实记账)。
|
|
357
|
+
|
|
358
|
+
取回就是拿同一条定位符读会话事件:
|
|
359
|
+
|
|
360
|
+
```ts
|
|
361
|
+
import { readPrunedOriginal } from 'dsh-harness-reflex';
|
|
362
|
+
|
|
363
|
+
const record = readPrunedOriginal(session.ownEvents(), locator);
|
|
364
|
+
record?.text; // 逐字节原文
|
|
365
|
+
record?.chars; // 保留时的字符数
|
|
366
|
+
record?.digest; // 与决策记录里的 digest 一致
|
|
367
|
+
```
|
|
368
|
+
|
|
369
|
+
下限 `pruneFloorRatio`(默认 0.5)是**安装文本占原文的最小比例**:判定给出的候选若低于它,
|
|
370
|
+
就用首尾上下文补足到该比例;判定选中的中间诊断整体保留,不会被下限挤掉。
|
|
371
|
+
可保留的载荷有边界:换行少于 4 个(不足 5 行)或超过 100 000 字符时不做剪枝
|
|
372
|
+
(分别记为 `unsupported-payload` / `retention-too-large`),单行输出与超大日志原样通过;
|
|
373
|
+
同一载荷重复出现时复用第一次保留的原件,不重复写日志。
|
|
374
|
+
|
|
375
|
+
### 成本与可追溯
|
|
376
|
+
|
|
377
|
+
- 账本按 `mode` 与 `capability` 分列:`plans`(计划了几次)、`applied`(真正执行了几次)、
|
|
378
|
+
`judgments` / `memoHits`(判定与判定缓存命中)、`judgeTokens`(判定消耗的 token)、
|
|
379
|
+
`originalTokens` / `candidateTokens` / `potentialSavedTokens`(本可节省)/ `actualSavedTokens`(真正少带进上下文的量);
|
|
380
|
+
- `observe` 的 `actualSavedTokens` 恒为 0,`potentialSavedTokens` 与同输入的 `active` 逐项一致;
|
|
381
|
+
- 判定成本单独计:`localLatencyMs`(本机仲裁)与 `remoteLatencyMs`(后端判定)分开统计;
|
|
382
|
+
- 每条剪枝记录都带被替换原文的 `digest`、`turn`/`step` 与定位符 `originalLocator`;用定位符即可读回逐字节原文(见上「被剪掉的原文如何取回」);
|
|
383
|
+
- 保留是替换的前提:保留不成功就不替换、不计 `actualSavedTokens`,`plans` 也不谎报一次没发生的缩减;
|
|
384
|
+
- `off` 严格零行为:不注册任何监听器、不采样、不判定,与不装插件逐字节一致;
|
|
385
|
+
- 判定缓存以「回合 + 尾部窗口」为键:同一个问题一个回合只付一次;`maxJudgmentsPerTurn`、
|
|
386
|
+
`maxJudgmentsPerSession`、`maxInterventionsPerTurn` 分别是每回合判定、每会话判定、每回合干预的次数上限;
|
|
387
|
+
- 同一 `(agent, 调用签名)` 的干预在一个回合内去重;被本插件拒绝的那次调用的返回值不参与二次判定;
|
|
388
|
+
- 本插件自己注册的工具永不进入判定(它们的结果已经是优化产物;默认 4 个,打开
|
|
389
|
+
`route` 后 5 个),这些 `reflex_*` 载荷不受干预影响。
|
|
390
|
+
|
|
391
|
+
### 安全与回退
|
|
392
|
+
|
|
393
|
+
- **fail-open**:任一判定环节抛错都直接放行下游结果(记为 `planning-error`),不会让工具调用失败;
|
|
394
|
+
- **判失败不靠措辞**:以结果的结构化 `exitCode`/`signal` 为准,其次才是宿主追加在末行的退出标记;正文里出现 “failed” 不算失败,也不会因此拦下一次合法重试;
|
|
395
|
+
- **权限单调**:`tools/pre-execute` 只在下游给 `allow` 时追加一条 `deny`;下游给 `ask`/`deny`/`cancel` 时按原对象原样返回(含 `info`),既不放宽也不覆盖;
|
|
396
|
+
- **会话隔离**:检测窗口、判定缓存与次数上限都按 agent 记账,多 agent 互不共享;
|
|
397
|
+
- **卸载无残留**:插件卸载时解除全部监听器并清空引擎状态;账本默认只在内存(未设 `ledgerPath` 时不落盘)。
|
|
398
|
+
|
|
399
|
+
---
|
|
400
|
+
|
|
401
|
+
## 8. 设置面板(DSH Settings UI)
|
|
402
|
+
|
|
403
|
+
插件通过 `dsh.client` 声明浏览器半边,注册到设置面板的 `settings.section` 槽位:
|
|
404
|
+
|
|
405
|
+
| 标签页 | 内容 |
|
|
406
|
+
| --- | --- |
|
|
407
|
+
| 概览 | 决策计数、节省 token、平均时延、门禁通过/失败、最近一次自适应决策 |
|
|
408
|
+
| 虚拟 Provider | 路由开关、虚拟 Provider 名称、模型池增删与排序、兜底目标 |
|
|
409
|
+
| 推理强度 | 策略(不干预 / Reflex 自适应)、兜底档、最小置信度、**自适应推理强度开关** |
|
|
410
|
+
| 自动干预 | 三态模式(`off`/`observe`/`active`)、四大能力覆盖、每回合干预次数上限、每回合判定上限、每会话判定上限、重复阈值、失败阈值、最小置信度、判定窗口大小、剪枝下限比例;并列出当前生效的模式与能力(只读) |
|
|
411
|
+
| 工具开关 | 5 个能力逐项启停(默认 4 开、`route` 关);每项写明**做什么 / agent 何时该调用 / 是否建议暴露**,并有「应用推荐组合」按钮;页尾列出当前已注册的工具名(只读,跟随 `toolPrefix`),并提示账本改用 `/reflex-ledger` |
|
|
412
|
+
| System 1 后端 | 连接配置(可多套:Base URL、模型列表与单选、API Key 只写、环境变量名、超时)、后端实现;以及工具名前缀、裁剪阈值、账本 JSONL 路径、校准曲线路径 |
|
|
413
|
+
| 决策账本 | 实时指标、最近决策表、落盘路径、清空(需二次确认) |
|
|
414
|
+
| **使用说明** | **本手册的只读视图,跟随 DSH 界面语言中英切换** |
|
|
415
|
+
|
|
416
|
+
- 页面保存前会过一次 Host 校验:改一个字段只写该字段所在的路径(整组写回的组除外,
|
|
417
|
+
见下);System 1 后端页覆盖连接配置行、`systemOne.active`、`backend` 与四个运行时
|
|
418
|
+
字段,保存时按路径只写改动项;
|
|
419
|
+
- Host 文档只读时页面自动进入只读模式,写操作按钮禁用;
|
|
420
|
+
- 面板路由 `/dsh-reflex/api/*`(`panel` / `health` / `ledger/clear`)只接受 loopback 客户端,清除账本必须显式确认。
|
|
421
|
+
|
|
422
|
+
### 各组的写回范围
|
|
423
|
+
|
|
424
|
+
面板永远显示**当前生效值**,且保存走的是 Host 设置文档的唯一写入通道(按组
|
|
425
|
+
`set` + 修订号校验),不存在第二条写入路径。各组写回粒度不同:
|
|
426
|
+
|
|
427
|
+
- **自动干预:整组写回**。保存该组时,面板把该组当前的**模式与全部预算值一次性
|
|
428
|
+
完整写入**(与虚拟 Provider、推理强度等组一致),所以配置里留下的是你在面板上
|
|
429
|
+
看到的那一份完整取值,而不是只有被改过的那一个字段;其中能力覆盖只写「不等于
|
|
430
|
+
`inherit`」的项,其余保持省略(省略 = 跟随模式)。
|
|
431
|
+
- **工具开关:只写与默认不同的项**。只有偏离该后缀默认值的开关会写进
|
|
432
|
+
`tools.enabled`:默认开启的工具被关掉写 `false`,默认关闭的 `route` 被打开写
|
|
433
|
+
`true`;把任何一项改回默认值都会**删除**该键。因此「推荐组合」与「整组省略」
|
|
434
|
+
逐字节一致,默认配置下配置内容零变化(默认已经是 4 开 1 关)。
|
|
435
|
+
- **推理强度开关:总是显式写入**。`effort.enabled` 随该组写下当前值,避免出现
|
|
436
|
+
「面板显示已启用、配置里其实是省略」的歧义。
|
|
437
|
+
- **System 1 后端:逐条路径只写改动项**。Host 的设置文档按**配置路径**寻址,而该页
|
|
438
|
+
覆盖的是 `backend`(标量)、连接配置行(`systemOne.profiles.<名字>.<字段>`)、
|
|
439
|
+
`systemOne.active` 以及 `toolPrefix`、`ledgerPath`、`pruneThreshold`、
|
|
440
|
+
`calibrationPath` 四个顶层字段:保存时只写**取值真的变了**的路径,没动过的行与
|
|
441
|
+
字段一个字都不写(改名/删除的行另按 g-065 的规则整棵子树 `unset`)。**页面名不会
|
|
442
|
+
被当成配置键**——`runtime` 并不是 `Config` 的字段,按页面名写入会被 Host 直接拒绝,
|
|
443
|
+
整次保存随之失败。留空的 `ledgerPath`/`calibrationPath` 以「取消设置」写入,效果
|
|
444
|
+
等于沿用下层配置而不是写空串。
|
|
445
|
+
|
|
446
|
+
非法值(未知工具后缀、非布尔值、越界预算、非法三态取值)由 Host 侧同一个
|
|
447
|
+
`resolveConfig` 校验器拒绝并给出字段级错误文案,面板不会部分生效——要么整组通过,
|
|
448
|
+
要么一个字都不写。
|
|
449
|
+
|
|
450
|
+
### 工具开关:两类建议与推荐组合
|
|
451
|
+
|
|
452
|
+
工具开关页的每一项都写清三件事:**这个能力做什么**、**agent 在什么情况下应该调用
|
|
453
|
+
它**、以及一条**是否建议暴露给 agent** 的标签:
|
|
454
|
+
|
|
455
|
+
| 建议标签 | 含义 | 能力 |
|
|
456
|
+
| --- | --- | --- |
|
|
457
|
+
| 建议暴露 | agent 日常确实会用 | `choice`、`score`、`screen`、`gate` |
|
|
458
|
+
| 按需开启 | 候选很多时先缩小范围才有用,默认关闭 | `route` |
|
|
459
|
+
|
|
460
|
+
页首的「**应用推荐组合**」按钮按上表预填这 5 个开关,并把 `route` 关掉。**这个
|
|
461
|
+
推荐组合就是默认值**:`tools.enabled` 省略时,`choice`、`score`、`screen`、`gate`
|
|
462
|
+
开、`route` 关,DSH 插件侧默认暴露 4 个工具。按钮只预填草稿、不落盘:仍需点
|
|
463
|
+
「保存」;草稿若已经等于默认值,保存**不写任何内容**(没有需要记录的差异)。
|
|
464
|
+
|
|
465
|
+
`route` 是可选增强:打开它(面板开关,或配置里写 `tools: { enabled: { route: true } }`)
|
|
466
|
+
才会注册 `reflex_route`;不开也不影响主流程。
|
|
467
|
+
|
|
468
|
+
还有三项能力**已经不是工具**,因此这里没有它们的开关:`prune`(结果剪枝)与
|
|
469
|
+
`detect_stagnation`(停滞检测)由自动干预层直接驱动,随 `observe`/`active` 生效;
|
|
470
|
+
账本汇总改由 `/reflex-ledger` 命令读取。页尾有一行提示指出这两条去路;stdio MCP
|
|
471
|
+
侧仍保留同名的 8 个工具,见下一节。
|
|
472
|
+
|
|
473
|
+
---
|
|
474
|
+
|
|
475
|
+
## 9. MCP 工具 ↔ DSH 原生能力对照
|
|
476
|
+
|
|
477
|
+
两种形态**各自使用不同的工具集**:stdio MCP 侧仍然暴露自 v0.1.0 起冻结的 **8 个工具**,
|
|
478
|
+
DSH 插件侧只注册 **6 个可开关的能力(默认 5 个)**——另外三项能力改由自动干预与一条
|
|
479
|
+
命令承载,不占用模型的工具清单。`reflex_delegate` 是插件侧专属的包装工具:它把任务转交给
|
|
480
|
+
宿主的 `subagent` 工具,由 System One 决定子树该用多深的思考档位;它**刻意没有**思考档位
|
|
481
|
+
参数(想精确指定档位就直接调用 `subagent`),并且只在宿主委派工具声明了
|
|
482
|
+
`reasoning_effort`(即部署开启了 `modelSelection: true`)时才注册——否则不注册并在日志里
|
|
483
|
+
说明原因,不会出现「注册了却传不进档位」的静默降级。
|
|
484
|
+
|
|
485
|
+
| 能力 | MCP 工具名(`harness-reflex mcp`) | DSH 插件侧(`dsh-harness-reflex`) | 主要参数 | 建议 |
|
|
486
|
+
| --- | --- | --- | --- | --- |
|
|
487
|
+
| 多选一分类 | `reflex_choice` | 工具 `reflex_choice` | `question`, `options[]`, 可选 `context` | 建议暴露 |
|
|
488
|
+
| 连续评分 | `reflex_score` | 工具 `reflex_score` | `statement`, 可选 `criteria`, `context` | 建议暴露 |
|
|
489
|
+
| 提示注入筛查 | `reflex_screen` | 工具 `reflex_screen` | `content`, 可选 `source`, `strict` | 建议暴露 |
|
|
490
|
+
| 声明-证据门禁 | `reflex_gate` | 工具 `reflex_gate` | `assertions[{statement}]`, `evidence`, 可选 `strictness` | 建议暴露 |
|
|
491
|
+
| 候选排序 | `reflex_route` | 工具 `reflex_route`(**默认不注册**) | `goal`, `candidates[]`, 可选 `topK` | 按需开启 |
|
|
492
|
+
| 委派子代理 | `reflex_delegate` | 工具 `reflex_delegate`(**需先在设置面板勾选「子代理委派」,且宿主委派工具随后开放思考档位时才注册**) | `prompt`, `description`, 可选 `provider`, `model`, `cwd` | 建议暴露 |
|
|
493
|
+
| 长输出剪枝 | `reflex_prune` | 无工具:结果剪枝由 `tools/pre-execute` 等钩子按干预模式自动执行 | `rawOutput`, 可选 `intent`, `shadowMode` | — |
|
|
494
|
+
| 停滞检测 | `reflex_detect_stagnation` | 无工具:停滞检测是自动干预的一部分 | 可选 `recentAction`, `goal`, `history[]` | — |
|
|
495
|
+
| 账本审计 | `reflex_status_ledger` | 无工具:改用 `/reflex-ledger` 命令(无参数) | 可选 `includeEntries`(返回 `summary`,可附 `recentEntries`) | 人读 |
|
|
496
|
+
|
|
497
|
+
勾选 **子代理委派** 是一次带副作用的明确同意:插件会把 `tool-subagent: { modelSelection: true }` **合并**进你的
|
|
498
|
+
profile patch(`~/.dsh/profiles/<profile>/cordis.patch.yml`),其余内容逐字节保留,写入前先备份。宿主在启动时
|
|
499
|
+
读取该开关,因此面板明说 **「已保存,重启 DSH 后生效」**,不假装即时生效。运行期该能力消失时,插件只告警、
|
|
500
|
+
摘掉 `reflex_delegate` 并在面板显示原因——**绝不自动把你的配置改回去**。
|
|
501
|
+
|
|
502
|
+
差异点:
|
|
503
|
+
|
|
504
|
+
- 工具名前缀可配置(`toolPrefix`,默认 `reflex_`),例如改成 `rv_` 后是 `rv_gate`;
|
|
505
|
+
- DSH 侧参数校验由 Host 的 `defineTool` 完成(必填/类型/枚举/嵌套),工具层再拦
|
|
506
|
+
截顶层未声明参数。MCP 侧发布 `inputSchema` 供客户端使用,但分派器不执行通用
|
|
507
|
+
JSON Schema 校验;错传 `claims` 而非 `assertions` 会进入空断言门禁,返回
|
|
508
|
+
`passed: false`、`needsEscalation: true`、`results: []`,不是 JSON Schema 错误。
|
|
509
|
+
执行异常返回工具结果 `isError: true`。DSH 另支持断言内可选 `criteria`,MCP 未声明此嵌套字段;
|
|
510
|
+
- DSH 侧的账本读取**不经过模型**:`/reflex-ledger` 由 Host 直接渲染为文本(汇总 +
|
|
511
|
+
最近 5 条),也没有工具参数;账本是否落盘取决于 `ledgerPath`(省略时只留内存,
|
|
512
|
+
不写用户项目)。MCP 侧仍是 `reflex_status_ledger` 工具,参数与返回见上表;
|
|
513
|
+
- DSH 侧的能力可用 `tools.enabled` **逐项开关**,键名是**后缀**,只接受当前 5 个后缀:
|
|
514
|
+
|
|
515
|
+
```yaml
|
|
516
|
+
tools:
|
|
517
|
+
enabled:
|
|
518
|
+
route: true # 打开默认关闭的候选排序
|
|
519
|
+
gate: false # 关掉默认开启的门禁,其余照常
|
|
520
|
+
```
|
|
521
|
+
|
|
522
|
+
后缀与 `toolPrefix` 无关:前缀改成 `rv_` 之后 `{ gate: false }` 关掉的仍是
|
|
523
|
+
`rv_gate`。被关闭的能力**不会被注册**到 `ctx.tools`,因此模型可见的工具清单里
|
|
524
|
+
没有它,`reflexToolNames()` 与前缀推导的结果里也没有它——没有「占位工具」这种
|
|
525
|
+
东西,模型不会看到一个调用即报错的空壳。`tools.enabled` 省略时按后缀默认值
|
|
526
|
+
(`choice`/`score`/`screen`/`gate` 开、`route` 关)生效;写成不存在的后缀
|
|
527
|
+
(例如 `teleport`,或已改为命令的 `prune`/`detect_stagnation`/`status_ledger`)
|
|
528
|
+
或非布尔值会在安装时被校验器拒绝,而不是被静默忽略。把 5 项全部写 `false` 后本
|
|
529
|
+
插件不注册任何工具(路由、推理强度与干预钩子不受影响)。
|
|
530
|
+
|
|
531
|
+
### 9.1 五个 Harness 的能力差异
|
|
532
|
+
|
|
533
|
+
同一套决策引擎接进了五个宿主,但**能力并不对等**:宿主没给出对应钩子时,该能力就是做不到。
|
|
534
|
+
选宿主之前先看这张表(「是否在模型侧真实生效」才是关键,不是「有没有接线」):
|
|
535
|
+
|
|
536
|
+
| 能力 | Claude Code | DSH | Codex CLI | pi | Kimi Code | OpenCode |
|
|
537
|
+
|---|---|---|---|---|---|---|
|
|
538
|
+
| 剪枝(改写工具输出) | ✅ | ✅ 自动 | ⚠️ 仅 MCP 工具输出,**shell 输出改不了** | ✅ | ❌ 只记账不生效 | ✅ |
|
|
539
|
+
| 停滞拦截 | ✅ | ✅ 自动 | ✅ | ✅ | ✅ | ✅ |
|
|
540
|
+
| 收尾阻断 | ✅ 真阻断 | ✅ 真阻断 | ✅ | ⚠️ 只续跑一次,记 `closing-degraded-pass` | ⚠️ 需 exit-2 shim | ❌ 无法拦截 |
|
|
541
|
+
| 接入形态 | hooks + MCP | 进程内插件 | hooks.json + config.toml | 进程内 TS 扩展 | hooks.toml + shim | JS 插件 |
|
|
542
|
+
|
|
543
|
+
四条例外必须记住:
|
|
544
|
+
|
|
545
|
+
1. **Codex**:`PostToolUse` 只接受 `updatedMCPToolOutput`,且只对 MCP 工具生效,**shell 工具输出无法改写**。
|
|
546
|
+
本机无可用模型端点,MCP 工具从未进入回合内工具清单,这一路径未真机验证。
|
|
547
|
+
2. **Kimi**:`PostToolUse` / `PostToolUseFailure` / `SubagentStop` 是 observation-only,判定只进账本、
|
|
548
|
+
改变不了模型看到的内容;**剪枝只记账不生效**。`Stop` 要靠 `hooks/reflex-stop-exit2.sh` 转成 exit 2 才拦得住。
|
|
549
|
+
3. **OpenCode**:宿主没有 shell 钩子机制,扩展点是 JS 插件;剪枝与停滞**生效**,但 **Stop 无法拦截**
|
|
550
|
+
(`session.idle` 不带助手文本,也无插件级否决权,只写 warn 日志)。
|
|
551
|
+
4. **pi**:没有任何 API 能拒绝结束回合,`agent_before_settle` 只能请求一次续跑;矛盾未被纠正时放行并记
|
|
552
|
+
`closing-degraded-pass`,**pi 永不写 `closing-block`**。
|
|
553
|
+
|
|
554
|
+
**Claude Code 与 DSH 是完整能力**。Kimi / OpenCode 的整机安装与钩子触发、Codex 的回合内 MCP 工具均未真机验证,
|
|
555
|
+
复现方法见各包 README 的「Verification status」。
|
|
556
|
+
|
|
557
|
+
---
|
|
558
|
+
|
|
559
|
+
## 10. 决策账本与审计
|
|
560
|
+
|
|
561
|
+
每次判定都会追加一条 JSONL 记录(`type` 取值:`gate`、`prune`、`stagnation`、
|
|
562
|
+
`route`、`model-route`、`effort`、`choice`),字段包含后端、耗时、置信度、
|
|
563
|
+
节省 token 估算与截断后的详情。查看方式:
|
|
564
|
+
|
|
565
|
+
```bash
|
|
566
|
+
node dist/cli/index.js ledger # 终端查看汇总
|
|
567
|
+
```
|
|
568
|
+
|
|
569
|
+
- **`/reflex-ledger`(DSH 内)**:在会话里直接输入该命令,Host 会把**本次激活**的
|
|
570
|
+
账本汇总渲染成文本(总调用数、按类型分布、平均时延、节省 token 与估算成本、
|
|
571
|
+
门禁通过/失败、停滞告警,以及最近 5 条决策)——这是命令,不是工具:**不占用模型
|
|
572
|
+
上下文、不发起模型回合**,账本为空时返回一句「暂无记录」而不是一排 0;
|
|
573
|
+
- `ledgerPath` 省略 ⇒ 仅内存,关掉进程即消失(默认,用户项目零污染);
|
|
574
|
+
- 配置了路径 ⇒ 追加写 JSONL 并支持回放,面板「决策账本」页显示落盘路径;
|
|
575
|
+
- 面板清空账本需要连续两次点击确认,第二次才真正删除记录与 JSONL 文件。
|
|
576
|
+
|
|
577
|
+
---
|
|
578
|
+
|
|
579
|
+
## 11. 测试与发布
|
|
580
|
+
|
|
581
|
+
```bash
|
|
582
|
+
npm test # 根包:ledger / score / MCP 表面 / 打包清单
|
|
583
|
+
npm run test:plugin # DSH 插件:注册、严格校验、工具面与 /reflex-ledger、路由、推理强度、面板、使用说明
|
|
584
|
+
npm run test:mutation # 负向对照:注入故障,要求测试套件(或编译器)全部抓住
|
|
585
|
+
npm run test:all # build:all + 两套测试
|
|
586
|
+
npm run release # 全套测试 + 打包并校验 release/ 下的 tarball
|
|
587
|
+
npm run release:pack # 只打包并校验(不跑测试;注意需先 build:all)
|
|
588
|
+
```
|
|
589
|
+
|
|
590
|
+
发布产物(`release/`):
|
|
591
|
+
|
|
592
|
+
| 产物 | 内容 |
|
|
593
|
+
| --- | --- |
|
|
594
|
+
| `harness-reflex-<version>.tgz` | 根包:`dist/`、`README.md`、`docs/`、`USER_GUIDE.md`、`experiments/` |
|
|
595
|
+
| `dsh-harness-reflex-<version>.tgz` | 插件 `dsh-harness-reflex`(npm pack 命名):`dist/`、`client.js`(内含本手册)、`cordis.patch.yml`、`locale/` |
|
|
596
|
+
| `harness-reflex-claude-code-<version>.tgz` | Claude Code 插件:`.claude-plugin/`、`hooks/`、`.mcp.json` |
|
|
597
|
+
| `harness-reflex-codex-<version>.tgz` | Codex 配置包:`hooks.json`、`config.toml` |
|
|
598
|
+
| `pi-reflex-<version>.tgz` | pi 扩展:`src/`(发布会直接跑源码)、`scripts/`、`dist/` 声明 |
|
|
599
|
+
| `harness-reflex-kimi-code-<version>.tgz` | Kimi Code 配置包:`hooks.toml`、`hooks/reflex-stop-exit2.sh`、`mcp.json` |
|
|
600
|
+
| `harness-reflex-opencode-<version>.tgz` | OpenCode 插件:`plugin/reflex.js`、`opencode.json` |
|
|
601
|
+
| `SHA256SUMS` | 全部 tarball 的 SHA-256 校验和 |
|
|
602
|
+
| `release-report.json` | 逐项打包核验记录(文件清单、死链、依赖声明、安装冒烟) |
|
|
603
|
+
| `RELEASE-<version>.md` | 由脚本生成的发布说明(机器产物;当前版本的会在每次打包时重写,**更早版本的会被保留**) |
|
|
604
|
+
|
|
605
|
+
校验脚本 `scripts/release-pack.mjs` 会解压 tarball 逐个断言:必需文件齐全、
|
|
606
|
+
无测试构建与临时目录、`exports`/`bin`/`dsh.bundle.patch` 目标真实存在、每个相
|
|
607
|
+
对引用与 sourcemap 都能在包内解析(零死链),并在临时目录里真装一次根包、
|
|
608
|
+
跑通 `import` 与 stdio MCP `tools/list`。
|
|
609
|
+
|
|
610
|
+
---
|
|
611
|
+
|
|
612
|
+
## 12. 常见问题排查
|
|
613
|
+
|
|
614
|
+
| 现象 | 原因与处理 |
|
|
615
|
+
| --- | --- |
|
|
616
|
+
| 设置里找不到「Reflex 决策运行时」 | Host 半边未加载或未注册配置命名空间;确认 `dsh plugin --profile web add` 成功并重启/重载 `dsh` |
|
|
617
|
+
| 面板显示只读 | 当前 DSH 设置文档不可写;只读模式下所有写操作被禁用属预期行为 |
|
|
618
|
+
| 虚拟模型报错而不是派发 | 候选池为空且没有 `routing.fallback`;补候选或配置兜底目标 |
|
|
619
|
+
| 文本没有按预期被路由 | 检查 `routing.enabled`、虚拟模型 ID 拼写,以及 Agent 是否真的请求了该虚拟模型 |
|
|
620
|
+
| 推理强度没变化 | 策略设置为省略 = 不干预;或者调用方在请求里显式选择了具体档位 |
|
|
621
|
+
| System 1 判定总是走兜底 | `timeoutMs` 过小、`baseUrl` 不可达,或 `minConfidence` 过高;先看「概览」页的最近决策与后端状态。注意超时**没有统一默认值**:省略时 `jev` 用 10000 ms、`simple-jev` 用 8000 ms |
|
|
622
|
+
| 面板里的使用说明是过时副本 | 修改 `USER_GUIDE.md` 后未重新构建;执行 `npm run build:all` |
|
|
623
|
+
| 关掉某个工具后模型仍在调用它 | 注册表在下一次加载时生效;重载插件后再看,并确认键名写的是**后缀**(`gate`,不是 `reflex_gate`)。`prune`/`detect_stagnation`/`status_ledger` 已不是工具,写进 `tools.enabled` 会被校验器拒绝 |
|
|
624
|
+
| 默认工具清单里没有 `reflex_route` | 属预期:`route` 默认关闭,需要在工具开关页打开(或写 `tools: { enabled: { route: true } }`) |
|
|
625
|
+
| 想查账本但找不到 `reflex_status_ledger` 工具 | 账本已是命令:输入 `/reflex-ledger`(stdio MCP 侧仍有同名工具) |
|
|
626
|
+
| 关掉自适应推理强度后模型选择器仍有 `reflex` 档位 | 该档位是上一次加载注入的;确认配置已生效并重载插件,注入即被撤销 |
|
|
627
|
+
| 保存配置时报错「只支持留空或 reflex」 | 配置里仍写着具体档位;删掉该值(或改成 `reflex`)。需要固定深度请在模型选择器里选择具体档位 |
|
|
628
|
+
| 保存「自动干预」后配置里多出默认值 | 属预期:该组是整组写回,模式与全部预算按面板当前值完整写入 |
|
|
629
|
+
|
|
630
|
+
---
|
|
631
|
+
|
|
632
|
+
## 13. 版本与兼容性
|
|
633
|
+
|
|
634
|
+
- 版本:`harness-reflex` 与 `dsh-harness-reflex` 同步发布,v0.3.0;五个宿主插件包同版本;
|
|
635
|
+
- Node:`>= 18`(根包 `engines`;`pi-reflex` 为 `>= 22.19.0`);DSH Host 依赖 `@deepseek-ai/*@0.2.1-alpha.4`;
|
|
636
|
+
- 插件以 `peerDependencies` 声明 Host 契约,运行时不重复打包 Host 模块;
|
|
637
|
+
- stdio MCP 的 8 工具表面自 v0.1.0 起冻结,Host 侧变更不得静默改动其载荷;
|
|
638
|
+
- DSH 插件侧的工具表面自 v0.1.0 起是 **5 个可开关能力、默认注册 4 个**
|
|
639
|
+
(`route` 默认关闭),账本为 `/reflex-ledger` 命令——这一侧不承诺与 MCP 侧逐项对齐。
|