SnowRikka/dsh-llama-responses

dsh-llama-responses

DeepSeek Harness(dsh)的本地大模型适配器插件:OpenAI Responses 协议(/v1/responses),对接本地 llama.cpp llama-server。

用途:dsh 主代理继续用 DeepSeek 官方 API,子代理(spawn/fork)路由到本地模型,省 API 成本。

隔离设计(重要):所有子代理不继承父对话——subagent_fork 已通过 patch 重定向到 spawn 提供方
(provider: spawn),两个委派工具的子代理都只看到父代理下发的指令文本,父会话任何内容
(含已完成轮次)都不会进入子代理上下文,避免上下文膨胀与信息泄漏。父代理要传递背景,
必须显式写进委派指令。(已实测:父对话中的信息子代理明确回答"看不到"。)

重要提示(子代理走本地模型的前置操作)

已知坑:每次启动必须先在 DeepSeek Harness 中手动选择一次本地的 qwen3.8-27b 并提问一次,然后把主代理
换回 DeepSeek V4 模型——之后子代理才会正常走本地的 qwen3.8-27b。不做这一次"本地提问再切回",
子代理不会正常路由到本地模型。

安装(生态方式)

方式一:dsh 官方插件命令(推荐)
dsh plugin --profile web add git+https://github.com/SnowRikka/dsh-llama-responses.git

方式二:手动软链(便于改源码)
git clone https://github.com/SnowRikka/dsh-llama-responses.git ~/dsh-llama-responses
ln -sfn ~/dsh-llama-responses ~/.dsh/profiles/web/node_modules/dsh-llama-responses

包内自带 cordis.patch.yml(bundle 层,注册默认适配器)与 skill/(委派规范 skill,
package.json 的 dsh.skills 声明)。装好后按下文 patch 把子代理路由到
provider: llama-responses 即可。npm 未发布前,以上两种方式等效。

文件

| 文件 | 说明 |
|---|---|
| index.js | 插件入口:Config schema + ctx.llm.registerAdapter(['llama-responses'], ...) |
| adapter.js | 适配器本体:GenerateOptions → Responses 请求、Responses SSE → dsh StreamChunk(文本/工具调用流式/用量/finish) |
| test_adapter.mjs | 单元测试(不经 dsh 直连 llama-server:多轮、工具调用、工具结果回传) |
| node_modules/ | 指向 dsh 自带依赖的符号链接(dsh-llm、schemastery) |

已验证(2026-08-23,Qwen3.8-27B)

- 单元测试:多轮记忆、function_call 流式、function_call_output 回传,全部通过
- 端到端(DeepSeek 主代理 + 本地子代理):
- subagent(spawn/可继续后台)✅
- subagent_fork(one-shot 前台,已重定向 spawn=完全不继承父对话)✅ 隔离已实测
- send_message(追问排队下一回合)✅
- list_agents(显示 running/ready 状态)✅
- interrupt_agent(中断成功,子代理转 ready)✅
- report/结算通知(运行时通知链路)✅

如何启用 DeepSeek Harness 自带的子代理功能(前置条件)

本插件挂载在 dsh 的子代理体系上,先把 dsh 自带的子代理功能启用(这是必要前置):

现状:哪些默认开、哪些默认关

| Profile | 子代理引擎(spawn/fork 提供方、继续执行管理器) | 模型侧工具(subagent 等) |
|---|---|---|
| headless | 默认启用 | 默认启用 |
| web | 默认启用 | 默认禁用(web-app 组合包有意禁用,需 patch 开启) |

确认方法:

dsh --profile web --dump-config | grep -B1 -A4 "id: tool-subagent"   # 看 disabled 字段

web profile 启用 patch

在 ~/.dsh/profiles/web/cordis.patch.yml 加入(不带 config 的覆盖型条目):

- id: tool-subagent-control        # send_message / interrupt_agent
disabled: false

- id: tool-subagent-list-agents    # list_agents
disabled: false

- id: tool-subagent                # 委派工具(可继续后台子代理)
disabled: false

- id: tool-subagent-fork           # 委派工具(one-shot,已重定向 spawn=无父对话)
disabled: false

启用后模型会看到 5 个工具:subagent、subagent_fork、send_message、interrupt_agent、list_agents
(子代理内部另有 report 回报通道,自动生效)。

验证子代理功能本身(未挂本插件也能测,子代理会走默认 DeepSeek 模型)

dsh --profile headless "用 subagent 工具委派一个子代理回答:1+1等于几?转述它的答案"

如何启用本插件(本地模型路由)

前置:本地模型服务已运行(例:~/qwen/start_server.sh,监听 127.0.0.1:8080),
且建议加 --reasoning off 避免思考占用子代理输出预算。

1. 放置插件(软链到 profile)

对每个要用它的 profile 执行(web / headless)
ln -sfn /home/lmj/zi-dai-deep ~/.dsh/profiles/web/node_modules/dsh-llama-responses
ln -sfn /home/lmj/zi-dai-deep ~/.dsh/profiles/headless/node_modules/dsh-llama-responses

(依赖符号链接 node_modules/@deepseek-ai/{dsh-llm,schemastery} 已就位,一般无需动)

2. 配置 patch(~/.dsh/profiles//cordis.patch.yml)

注册适配器
- insert:
- id: llm-responses-local
name: dsh-llama-responses
config:
baseURL: http://127.0.0.1:8080/v1
providerName: llama-responses
apiKeyEnv: DSH_LOCAL_LLM_KEY
models:
- id: qwen3.8-27b            # 与 llama-server 加载的模型对应
name: Qwen3.8-27B IQ4_XS (local)
contextWindow: 163840
defaultContextWindow: 163840
defaultMaxTokens: 8192

子代理固定本地模型(已含完整示例见两个 profile 里的现成 patch)
- id: tool-subagent
config:
provider: spawn
toolName: subagent
backgroundMode: continuable
agentOptions:
provider: llama-responses       # 关键:路由到本地
model: qwen3.8-27b
maxTokens: 8192

web profile 还需要 - id: tool-subagent(-control/-list-agents/-fork)  disabled: false(web-app 默认禁用这些工具,headless 默认启用)。

3. 环境变量

~/.bashrc 已有;本地服务不校验鉴权,占位即可
export DSH_LOCAL_LLM_KEY=local-no-auth

4. 验证

dsh --profile web --dump-config | grep -A3 llm-responses-local   # 应看到插件条目
dsh --profile headless "用 subagent 工具委派子代理回答:1+1等于几?"  # 子代理答案应回传

协议细节(踩过的坑)

- 历史消息条目必须带顶层 type:'message',assistant 内容用 output_text
(裸 role 条目会报 "Cannot determine type of 'item'")
- 工具:{type:'function', name, description, parameters} 扁平格式;
结果回传用 {type:'function_call_output', call_id, output}
- SSE 事件:response.output_text.delta / response.function_call_arguments.delta /
response.output_item.done / response.completed(usage 在 completed 里)
- Node fetch 不走系统代理,本地 127.0.0.1 直连无碍

配置项参考

| 字段 | 默认 | 说明 |
|---|---|---|
| baseURL | http://127.0.0.1:8080/v1 | 适配器自动拼接 /responses |
| providerName | llama-responses | 注册到 ctx.llm 的路由名 |
| apiKeyEnv | DSH_LOCAL_LLM_KEY | 读该环境变量作 Bearer |
| models | qwen3.8-27b/160K | 模型目录(id 须与服务端一致) |
| defaultContextWindow | 163840 | 上下文窗口(与服务端 llama-server 的 --ctx-size 一致) |
| defaultMaxTokens | 8192 | 单请求输出上限 |

附带 SKILL:local-subagent-delegation

skill/local-subagent-delegation/SKILL.md — 面向主代理的子代理委派规范:

- 子代理 = 160K 上下文本地代码模型(身份自称不可信,忽略之)
- 指令必须自包含且详尽(六要素自查:目标/输入/约束/输出格式/验收标准/输出规模(由主代理判断,无固定上限))
- 硬性红线:同一时刻最多 1 个子代理(委派前 list_agents 检查)
- 默认一次性使用;仅同任务紧邻小追问且上下文 /.dsh/skills//SKILL.md |
| 200 | 项目级 | /.agents/skills/ |
| 300 | 自定义 | Config.customSkillDirs |
| 400 | 用户级 | ~/.dsh/skills//SKILL.md(本 skill 装在这里) |
| 500 | 用户级 | ~/.agents/skills/ |

同名 skill 低 rank 值优先;仅目录包 /SKILL.md 与扁平 .md 两种形式,
不支持嵌套递归发现。