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),两个委派工具的子代理都只看到父代理下发的指令文本,父会话任何内容 (含已完成轮次)都不会进入子代理上下文,避免上下文膨胀与信息泄漏。父代理要传递背景, 必须显式写进委派指令。(已实测:父对话中的信息子代理明确回答"看不到"。)

安装(生态方式)

# 方式一: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/<profile>/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: 65536
        defaultContextWindow: 65536
        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/64K	模型目录(id 须与服务端一致)
defaultContextWindow	65536	上下文窗口
defaultMaxTokens	8192	单请求输出上限

附带 SKILL:local-subagent-delegation

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

• 子代理 = 64K 上下文本地代码模型(身份自称不可信,忽略之)
• 指令必须自包含且详尽(六要素自查:目标/输入/约束/输出格式/验收标准/输出规模(由主代理判断,无固定上限))
• 硬性红线:同一时刻最多 1 个子代理(委派前 list_agents 检查)
• 默认一次性使用;仅同任务紧邻小追问且上下文 <32K 时允许 send_message 复用
• 何时不该委派(直接做/密集上下文交互/超长输出)

安装方式(已完成):软链到 ~/.dsh/skills/local-subagent-delegation; web profile 需 patch 启用 tool-skill(disabled: false),headless 默认启用。 已实测:模型能发现并加载该 skill,委派行为完全符合规范(六要素齐备、先查单实例、声明一次性)。

如何启用 skill 功能(tool-skill,前置条件)

skill 的发现与加载由 @deepseek-ai/dsh-tool-skill 插件提供,各 profile 默认状态不同:

Profile	tool-skill 默认状态
headless	默认启用
web	默认禁用(web-app 组合包禁用),需 patch 开启

web profile 启用方法

在 ~/.dsh/profiles/web/cordis.patch.yml 加入:

# 启用 skill 工具(模型发现/加载 SKILL.md)
- id: tool-skill
  disabled: false

(本机已配置;生效需要重启 dsh web,patch 热更新对工具启停不总是即时。)

验证

# 1. 配置树确认条目已启用(应显示 disabled: false)
dsh --profile web --dump-config | grep -A2 "id: tool-skill"

# 2. 运行时确认模型能发现 skill(应列出 local-subagent-delegation)
dsh --profile headless "你现在有哪些可用的 skill?只列名称和描述"

skill 的安装位置(发现优先级,供排错参考)

优先级	来源	目录
100	项目级	<项目根>/.dsh/skills/<name>/SKILL.md
200	项目级	<项目根>/.agents/skills/
300	自定义	Config.customSkillDirs
400	用户级	~/.dsh/skills/<name>/SKILL.md(本 skill 装在这里)
500	用户级	~/.agents/skills/

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