前言¶

在 DSH 里做智能体，常见需求是多轮对话、按 schema 调工具、把结果回填再继续推理。有人直接接 Codex 一类 CLI，有人自己写循环。前者往往绑在特定范式（AGENTS.md、工具协议、会话格式）上；后者容易在 LLM 通道和工具调度上重复造轮子。

@snow-the/dsh-busyloop（社区目录：snow-The/dsh-busyloop）提供的是 agent-loop 能力层：用宿主官方的 ctx.llm 做多轮 + 工具调度，不单独起一个运行时。README 里写得很直白——装上 busyloop，DSH 侧可以有与「完整 agent 循环」等价的能力，但不保证行为与 Codex 一致；Codex 风格属于可选的上层（如 dsh-busyloop-codex、dsh-busyloop-codexstyle 规划中）。

下面按定位、能力、安装、用法和注意点说明，事实均来自 GitHub 仓库 README 与包元数据。

这是什么¶

• 名称：@snow-the/dsh-busyloop（npm 包名；目录页插件线索为 snow-the/dsh-busyloop）
• 维护者：snow-The
• 分类：工作流（社区目录）
• 当前版本（package.json）：0.1.26
• 许可证：MIT
• 兼容声明：dshReleases 含 0.2.0-rc.1、0.2.0-rc.2、0.2.1-rc.2，verifiedAgainst 为 0.2.1-rc.2

一句话：DSH agent-loop 引擎——宿主 LLM 通道（官方 ctx.llm）+ 轻量 loop 骨架 + 工具表注入；并注册宿主工具 busyloop_run（README 描述中用于 ark/direct 通道的一次性任务，主模型 token 不被占用）。

生态上，DSH 强调「一切皆插件」；skillhub.cn 是社区插件目录，与 DeepSeek / 幻方无官方从属关系。

架构与设计原则¶

README 用「三件套」概括：

dsh-busyloop ──────────── 引擎(能力:LLM 适配器 + loop + 宿主工具调度)
├── dsh-busyloop-codex ──── 范式①:桥接 codex CLI(外包)
└── dsh-busyloop-codexstyle ─ 范式②:自研 codex 风格(规划中)

本文介绍的 busyloop 是中间这一层引擎；Codex 相关包是不同范式，需按需另装。

设计原则（摘自 README）：

1. LLM 适配器：不手刻、不外接独立服务；直接消费宿主 ctx.llm（@deepseek-ai/dsh-llm 的 LlmRuntime），类型来自官方包，运行时由宿主提供。
2. 不造独立运行时：逻辑全部在 DSH 宿主内；发布物在「纯 dsh + 官方包」环境可跑（bundle 自包含，构建时官方包 external）。
3. 工具表注入：宿主 ctx.tools 只读、不可枚举；loop 使用的工具由调用方传入（schema + execute）。

核心功能¶

编程接口¶

插件内典型用法：

import { createBusyLoop, hostLlm } from '@snow-the/dsh-busyloop'

// 插件内:
const engine = createBusyLoop(ctx)           // ctx.llm 宿主服务
const result = await engine.run({
  provider: 'deepseek',
  model: 'deepseek-chat',
  prompt: '东京天气如何?用 get_weather 工具查询后一句话回答',
  tools: [weatherTool],
  onEvent: (ev) => console.log(ev),          // turn / tool / done
})
// { output, turns, toolCalls, usage, finish }

纯库方式：hostLlm(ctx.llm) → runBusyLoop(llm, options)。

run 的返回结构包含 output、turns、toolCalls、usage、finish；onEvent 可观察 turn / tool / done 等事件。

HTTP 端点（经 ctx.webServer）¶

宿主提供 webServer（例如 dsh-web-app）时，通过 ctx.inject(['webServer'], …) 注册下列端点（README 说明已纠正早期误写的 ctx.http.mount 方案）：

安全行为（README 强调）：

• 不能用 ctx.get('webServer') 做一次性快照注册，否则 webServer 后挂载会漏注册且不报错。
• 各端点经 Host/Origin + 浏览器鉴权围栏（connection.requestRejection）；伪造请求 403、匿名 401；围栏读不到时失败关闭（503），不静默放行。

测试与质量¶

README 列出 14 个测试，分三层：单元/集成（npm test，fake chunks）、宿主解析链验证、真机 E2E（node e2e/e2e-host.mjs，需真 API key，手动运行）。

安装与启用¶

已抓取资料未给出 dsh plugin add github:... 一类一键命令；按 README「安装(重要)」在 profile 里接入包即可。

1. dependencies 与 bundles 都要加
   只在 dependencies 里声明会被 pnpm 装进 node_modules，但不会被 DSH loader 挂载（loader 只应用 bundles 里声明包的 bundle patch）。必须同时把 @snow-the/dsh-busyloop 写入 dsh.profile.bundles，cordis.patch.yml 才会生效，busyloop_run 工具才会注册。

2. 不要把 @deepseek-ai/dsh-tools 写成运行时 dependencies
   它是宿主提供的包（经 dsh-base bundle 装入）；本插件仅 peerDependency。误放进 dependencies 可能在「安装后立即重启」窗口期拉入第二个 dsh-tools 实例，导致首次工具调用崩溃（README 记录 0.1.6 教训，0.1.7 起改为 peer）。

3. 重启时序
   pnpm install 必须完整结束（等到 Done）再重启 dsh web；安装进行中不要重启。

peer 依赖（package.json）：@deepseek-ai/dsh、@deepseek-ai/dsh-llm、@deepseek-ai/dsh-llm-deepseek、@deepseek-ai/dsh-tools，版本均 >=0.2.0-rc.1。

包内还带 web client 注入：@deepseek-ai/dsh-client-locale、@deepseek-ai/dsh-client-ui-conversation（dsh.client 元数据）。

适用场景与注意¶

适合谁

• 要在 DSH 插件或 bundle 里实现「LLM 多轮 + 自定义工具表」，且希望走官方 ctx.llm 通道的开发者。
• 需要 HTTP 管理 LLM 通道/凭据/连通性测试，且宿主已提供 webServer 的部署形态。
• 只要循环能力、不强制 Codex 会话范式；Codex 桥接或 codexstyle 另选上层包。

务必注意

• 插件代码在当前 DSH 进程权限下运行；安装前请自行阅读 源码 与 MIT 许可证，评估凭据与网络暴露面（尤其 /api/busyloop/* 与凭据写入接口）。
• busyloop 是能力层，不保证与 Codex CLI 相同的工作方式；若产品依赖 AGENTS.md 或固定工具协议，应评估 dsh-busyloop-codex / 未来的 codexstyle。
• 社区目录星标为 0（线索数据），不代表质量结论，仅作目录元信息。

结尾¶

dsh-busyloop 把 agent 循环收进 DSH 宿主：官方 LLM、可注入工具表、可选 HTTP 运维面，并避免把 dsh-tools 重复装进依赖图。若你在 profile 里同时维护 dependencies 与 bundles，并按 README 完成安装时序，即可在插件内 createBusyLoop(ctx) 或库模式 runBusyLoop 落地多轮工具调用。

• 社区目录：https://www.skillhub.cn/plugins/snow-The/dsh-busyloop
• GitHub：https://github.com/snow-The/dsh-busyloop