@kangyishuai/dsh-btw 0.0.0-stage → 0.1.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/LICENSE +21 -0
- package/README.md +90 -2
- package/README.zh-CN.md +93 -0
- package/cordis.patch.yml +3 -0
- package/lib/badge.js +45 -0
- package/lib/client.js +884 -0
- package/lib/config.js +22 -0
- package/lib/history.js +77 -0
- package/lib/index.js +8 -0
- package/lib/limits.js +36 -0
- package/lib/messages.js +41 -0
- package/lib/paths.js +40 -0
- package/lib/prompts.js +80 -0
- package/lib/service.js +365 -0
- package/lib/settings.js +89 -0
- package/lib/subagent.js +200 -0
- package/lib/threads.js +240 -0
- package/locale/en.json +28 -0
- package/locale/zh.json +28 -0
- package/package.json +50 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 kangyishuai
|
|
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,91 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @kangyishuai/dsh-btw
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
> **Read-only side questions that do not interrupt the main task.**
|
|
4
|
+
|
|
5
|
+
[中文](./README.zh-CN.md)
|
|
6
|
+
|
|
7
|
+
Unofficial plugin for [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness). Not affiliated with DeepSeek.
|
|
8
|
+
|
|
9
|
+
## What it does
|
|
10
|
+
|
|
11
|
+
`/btw <question>` asks a side question about the current work **without interrupting the main task and without adding to the conversation history**.
|
|
12
|
+
|
|
13
|
+
- **Available while the agent is working.** The command dispatches immediately instead of queueing behind the running turn (measured: 215 ms, no user message created).
|
|
14
|
+
- **Read-only.** The side question runs in a forked child agent with **no tools**; a runtime guard denies any tool call that slips through, and `send_message` is always denied.
|
|
15
|
+
- **Cheap.** The fork reuses the parent conversation's prompt prefix, so the provider serves most of it from cache (measured: 57% on the first fork, 94% on a repeat). Cache writes are not billed.
|
|
16
|
+
- **Kept.** Answers are written to a per-session JSONL history so you can reopen the last one with a bare `/btw`.
|
|
17
|
+
- **Threads.** Follow up on a side question without losing the earlier exchange; the thread's history is replayed to the model each turn.
|
|
18
|
+
- **Promote to draft.** Turn the latest side question into a four-section draft (question / conclusion / key details / still unresolved) and **insert it into the composer — never send it**. You decide whether to send.
|
|
19
|
+
- **Honest scope badge.** The overlay states how many side questions exist and reminds you that **the model can see the whole conversation**; a scope choice only narrows the instruction, it does not cut context.
|
|
20
|
+
|
|
21
|
+
## How it works
|
|
22
|
+
|
|
23
|
+
A third-party DSH plugin cannot reach a provider adapter through `ctx.llm` (every access path resolves to an instance without adapters). The supported path is a **forked subagent**:
|
|
24
|
+
|
|
25
|
+
1. `ctx.subagents.startActivation({ provider: 'fork', parent: agent, … })` — the parent `Agent` comes from the command invocation.
|
|
26
|
+
2. A `ctx.tools.guard(...)` is armed on the child so the side question stays read-only.
|
|
27
|
+
3. The child's answer is read from the activation result, the child session is archived so it does not clutter the session list, and the Q&A is appended to history.
|
|
28
|
+
|
|
29
|
+
Follow-ups re-fork each turn and replay the thread's own Q&A into the prompt — a fork is single-turn, so keeping one child alive would degenerate into a full side session with its own lifecycle.
|
|
30
|
+
|
|
31
|
+
Promote only **returns text** from the host and inserts it with the composer's `setDraft`; `submit` is never called. If the composer already has content the action is refused instead of overwriting what you were typing.
|
|
32
|
+
|
|
33
|
+
Scope is deliberately **advisory**: a fork inherits every completed turn of the parent, and a plugin cannot inherit a subset. The badge says so instead of pretending the context was trimmed.
|
|
34
|
+
|
|
35
|
+
## Install
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
dsh plugin --profile desktop add @kangyishuai/dsh-btw
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
Restart the DSH desktop app afterwards.
|
|
42
|
+
|
|
43
|
+
## Usage
|
|
44
|
+
|
|
45
|
+
```
|
|
46
|
+
/btw what was the name of that config file again?
|
|
47
|
+
/btw # reopen the last answer
|
|
48
|
+
/btw --thread <threadId> # continue an existing thread
|
|
49
|
+
/btw --scope recent <q> # hint the answer to focus (session | recent | selection)
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
The overlay (button left of the composer) lists threads with cost badges, lets you follow up or
|
|
53
|
+
promote one to a draft, and shows the scope badge.
|
|
54
|
+
|
|
55
|
+
## Configuration
|
|
56
|
+
|
|
57
|
+
Plugin config (set when adding the plugin to a profile):
|
|
58
|
+
|
|
59
|
+
| Key | Default | Meaning |
|
|
60
|
+
| -------------- | ---------------------- | --------------------------------------------------------------------------------------------------- |
|
|
61
|
+
| `allowedTools` | `[]` | Tool names the side question may use. Empty means fully read-only. `send_message` is never allowed. |
|
|
62
|
+
| `language` | `auto` | `en` / `zh`; `auto` follows the system locale. |
|
|
63
|
+
| `dataRoot` | `$DSH_HOME` → `~/.dsh` | Where history and settings live (`<dataRoot>/btw/`). |
|
|
64
|
+
|
|
65
|
+
Runtime settings (editable in **Settings → Side questions**, stored in `<dataRoot>/btw/settings.json`):
|
|
66
|
+
|
|
67
|
+
| Key | Default | Meaning |
|
|
68
|
+
| -------------- | ------- | ------------------------------------------------- |
|
|
69
|
+
| `allowedTools` | `[]` | Overrides the plugin config above when non-empty. |
|
|
70
|
+
| `historyLimit` | `50` | Records kept per session (1–200). |
|
|
71
|
+
|
|
72
|
+
The settings file is re-read on every use, so edits take effect without restarting the host.
|
|
73
|
+
|
|
74
|
+
## Side effects & risks
|
|
75
|
+
|
|
76
|
+
- **Spends one model call** per side question (a fork of the current conversation).
|
|
77
|
+
- **Creates a child session**, then archives it. If archiving is unavailable the child stays visible in the session list — the answer itself is unaffected.
|
|
78
|
+
- **Writes** `<dataRoot>/btw/<parentSessionId>.jsonl` (up to 50 records per session, atomically replaced). It never copies the main conversation to disk.
|
|
79
|
+
- **Read-only is enforced at runtime**, not by prompt text: a tool call from the side question is denied with a model-facing reason.
|
|
80
|
+
|
|
81
|
+
## Compatibility
|
|
82
|
+
|
|
83
|
+
| Plugin | Verified on DSH |
|
|
84
|
+
| ------ | --------------- |
|
|
85
|
+
| 0.1.0 | 0.2.2-rc.3 |
|
|
86
|
+
|
|
87
|
+
The underlying host seams (command dispatch while busy, fork cache reuse, `tools.guard`, `workspaceRegistry.archiveSession`) were verified on DSH 0.2.2-rc.3. **The plugin itself has not yet been installed into a live profile** — that end-to-end check is still pending.
|
|
88
|
+
|
|
89
|
+
## License
|
|
90
|
+
|
|
91
|
+
MIT
|
package/README.zh-CN.md
ADDED
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
# @kangyishuai/dsh-btw
|
|
2
|
+
|
|
3
|
+
> **不打断主任务的只读旁问。**
|
|
4
|
+
|
|
5
|
+
[English](./README.md)
|
|
6
|
+
|
|
7
|
+
[DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness) 的非官方插件,与 DeepSeek 官方无关。
|
|
8
|
+
|
|
9
|
+
## 做什么
|
|
10
|
+
|
|
11
|
+
`/btw <问题>` 就当前工作提一个旁问,**不打断主任务、也不进入对话历史**。
|
|
12
|
+
|
|
13
|
+
- **回合进行中可用**:命令立即派发,不排到当前回合之后(实测 215 ms,且不产生用户消息)。
|
|
14
|
+
- **只读**:旁问在 fork 出来的子代理里执行,**不给任何工具**;运行期 guard 会拒绝漏网的工具调用,`send_message` 永远拒绝。
|
|
15
|
+
- **便宜**:fork 复用主会话的提示前缀,服务端大部分走缓存(实测首次 fork 命中 57%,重复请求 94%),且不产生写缓存费用。
|
|
16
|
+
- **可留存**:答案写入按会话切分的 JSONL 历史,裸 `/btw` 可重新打开上一条。
|
|
17
|
+
- **可追问**:同一条旁问可以继续追问,线程内的问答每轮都会回放给模型。
|
|
18
|
+
- **一键转正**:把最近一条旁问整理成四节草稿(问题 / 结论 / 关键细节 / 仍未解决),**只插进输入框、绝不发送**,发不发由你决定。
|
|
19
|
+
- **诚实的范围徽章**:浮层会说明有多少条旁问,并提示**模型能看到完整会话**;范围档位只缩窄指令,不裁剪上下文。
|
|
20
|
+
|
|
21
|
+
## 怎么实现的
|
|
22
|
+
|
|
23
|
+
第三方 DSH 插件**拿不到带 provider adapter 的 `ctx.llm` 实例**(所有取法都返回无 adapter 的实例)。受支持的路径是 **fork 子代理**:
|
|
24
|
+
|
|
25
|
+
1. `ctx.subagents.startActivation({ provider: 'fork', parent: agent, … })` —— 父 `Agent` 来自命令调用上下文;
|
|
26
|
+
2. 在子代理上挂 `ctx.tools.guard(...)`,保证只读;
|
|
27
|
+
3. 从 activation 结果里取答案,归档子会话避免污染会话列表,并把问答追加进历史。
|
|
28
|
+
|
|
29
|
+
追问每轮**重新 fork** 并把线程内的问答回放进提示词 —— fork 是单轮语义,让一个子会话活着续聊会退化成
|
|
30
|
+
完整的 side session(更重、要管会话生命周期)。
|
|
31
|
+
|
|
32
|
+
转正只由 host **返回文本**,客户端用 composer 的 `setDraft` 插入,**从不调用 `submit`**;
|
|
33
|
+
输入框已有内容时直接拒绝,不覆盖你正在写的东西。
|
|
34
|
+
|
|
35
|
+
范围是刻意做成**建议性**的:fork 会继承父会话全部已完成轮次,插件无法只继承一部分。
|
|
36
|
+
徽章如实说明这点,而不是假装上下文被裁剪过。
|
|
37
|
+
|
|
38
|
+
## 安装
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
dsh plugin --profile desktop add @kangyishuai/dsh-btw
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
装完重启 DSH 桌面版。
|
|
45
|
+
|
|
46
|
+
## 用法
|
|
47
|
+
|
|
48
|
+
```
|
|
49
|
+
/btw 刚才那个配置文件叫什么来着?
|
|
50
|
+
/btw # 重新打开上一条答案
|
|
51
|
+
/btw --thread <线程id> # 在已有线程里继续追问
|
|
52
|
+
/btw --scope recent <问题> # 提示回答聚焦的范围(session | recent | selection)
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
浮层(输入框左侧按钮)列出各线程与成本徽章,可追问、可转正,并显示范围徽章。
|
|
56
|
+
|
|
57
|
+
## 配置
|
|
58
|
+
|
|
59
|
+
插件配置(把插件加进 profile 时设置):
|
|
60
|
+
|
|
61
|
+
| 键 | 默认 | 含义 |
|
|
62
|
+
| -------------- | ---------------------- | -------------------------------------------------------------- |
|
|
63
|
+
| `allowedTools` | `[]` | 允许旁问使用的工具名。空 = 完全只读。`send_message` 永不放行。 |
|
|
64
|
+
| `language` | `auto` | `en` / `zh`;`auto` 跟随系统语言。 |
|
|
65
|
+
| `dataRoot` | `$DSH_HOME` → `~/.dsh` | 历史与设置文件的位置(`<dataRoot>/btw/`)。 |
|
|
66
|
+
|
|
67
|
+
运行期设置(在**设置 → 旁问**里改,落在 `<dataRoot>/btw/settings.json`):
|
|
68
|
+
|
|
69
|
+
| 键 | 默认 | 含义 |
|
|
70
|
+
| -------------- | ---- | ------------------------------- |
|
|
71
|
+
| `allowedTools` | `[]` | 非空时覆盖上面的插件配置。 |
|
|
72
|
+
| `historyLimit` | `50` | 每会话保留的旁问条数(1–200)。 |
|
|
73
|
+
|
|
74
|
+
设置文件每次使用前重读,改完不需要重启宿主。
|
|
75
|
+
|
|
76
|
+
## 副作用与风险
|
|
77
|
+
|
|
78
|
+
- 每次旁问**多花一次模型调用**(fork 当前对话)。
|
|
79
|
+
- **会创建一个子会话**并随后归档。若归档不可用,子会话会留在会话列表里 —— 答案本身不受影响。
|
|
80
|
+
- **会写** `<dataRoot>/btw/<父会话id>.jsonl`(每会话最多 50 条,原子替换)。**绝不**把主对话内容复制到磁盘。
|
|
81
|
+
- **只读是运行期强制的**,不靠提示词:旁问发起的工具调用会带着面向模型的原因被拒绝。
|
|
82
|
+
|
|
83
|
+
## 兼容性
|
|
84
|
+
|
|
85
|
+
| 插件 | 已在 DSH 上验证 |
|
|
86
|
+
| ----- | --------------- |
|
|
87
|
+
| 0.1.0 | 0.2.2-rc.3 |
|
|
88
|
+
|
|
89
|
+
底层宿主 seam(busy 时命令派发、fork 缓存复用、`tools.guard`、`workspaceRegistry.archiveSession`)已在 DSH 0.2.2-rc.3 上实测。**插件本身尚未安装进真实 profile 跑过** —— 这一步端到端验证仍待完成。
|
|
90
|
+
|
|
91
|
+
## 许可证
|
|
92
|
+
|
|
93
|
+
MIT
|
package/cordis.patch.yml
ADDED
package/lib/badge.js
ADDED
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
// @ts-check
|
|
2
|
+
// 上下文徽章的**纯文本生成**(不 import 宿主包,便于单测)。
|
|
3
|
+
//
|
|
4
|
+
// 诚实原则(v0.3 设计的硬要求):
|
|
5
|
+
// fork 子代理继承的是父会话**全部已完成轮次**,第三方插件无法只继承其中一部分
|
|
6
|
+
// (`ctx.llm` 拿不到 adapter,见 ADR 0016)。所以「上下文范围」只能在提示词里声明
|
|
7
|
+
// 「请只看这些」,徽章必须如实写明「模型可见完整会话」,**不能**声称限制了上下文。
|
|
8
|
+
|
|
9
|
+
/**
|
|
10
|
+
* 生成徽章文本。
|
|
11
|
+
* @param {{ records?: number, scope?: string, lang?: string }} [input]
|
|
12
|
+
* @returns {string}
|
|
13
|
+
*/
|
|
14
|
+
export function renderBadge(input = {}) {
|
|
15
|
+
const lang = input.lang === "en" ? "en" : "zh";
|
|
16
|
+
const records = Math.max(0, Math.trunc(Number(input.records) || 0));
|
|
17
|
+
const scope = String(input.scope ?? "").trim();
|
|
18
|
+
if (lang === "en") {
|
|
19
|
+
const base =
|
|
20
|
+
records === 0
|
|
21
|
+
? "No side question yet"
|
|
22
|
+
: `Based on ${records} side-question record${records === 1 ? "" : "s"}`;
|
|
23
|
+
const caveat =
|
|
24
|
+
"the model can see the whole conversation; only the instruction scopes the answer";
|
|
25
|
+
return scope === "" ? `${base} · ${caveat}` : `${base} · ${caveat} · asked to focus: ${scope}`;
|
|
26
|
+
}
|
|
27
|
+
const base = records === 0 ? "本会话还没有旁问" : `基于 ${records} 条旁问记录`;
|
|
28
|
+
const caveat = "模型可见完整会话,范围只约束回答";
|
|
29
|
+
return scope === "" ? `${base} · ${caveat}` : `${base} · ${caveat} · 已要求只看:${scope}`;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* 把「范围」要求渲染成提示词片段(真正生效的只有这段指令,不是上下文裁剪)。
|
|
34
|
+
* @param {string} scope
|
|
35
|
+
* @returns {string}
|
|
36
|
+
*/
|
|
37
|
+
export function renderScopeInstruction(scope) {
|
|
38
|
+
const text = String(scope ?? "").trim();
|
|
39
|
+
if (text === "") return "";
|
|
40
|
+
return [
|
|
41
|
+
"Scope requested by the user for this side question (advisory only — you can see the whole session):",
|
|
42
|
+
text,
|
|
43
|
+
"Prefer information inside that scope; if the answer is outside it, say so explicitly.",
|
|
44
|
+
].join("\n");
|
|
45
|
+
}
|