第 20 卷

能力域官方包作用

工具（tools）fs/tool-fs、fs/tool-fs-文件/终端/网页/技能/待 search、fs/tool-str-办等可调用工具

replace-editor、shell/ tool-bash、web、skill、

todo

上下文（context）context/、compaction/请求上下文组装、长对话压缩

服务器）

策略分散在多个包组）

模型（llm）llm/、llm-deepseek、模型接入、重试 llm-retry

conversation、uitool…）

> **完整清单与包数口径**：官方仓库 `packages/README.md` 是包清单权威表（47 组）；

`@deepseek-ai/dsh` CLI 的 0.1.0-rc.6 声明 **53 个 `@deepseek-ai/dsh-*` 直接依赖**（+CLI 自身 = 54），家族发布总量约 **221 个**（含 devDeps 与历史 0.0.1-rc.1 列车，官方构建

commit 提及）。白皮书/官方所称"60+"指 `packages/` 下全部子目录。**npm 包名写法** （`@deepseek-ai/dsh-*`）与**仓库路径写法**（`fs/tool-fs`）的对应关系，以及每个包的实测

描述，见 [附录 B：官方包速查大全](./appendix-packages.md)。

> > 📚 **想深入架构**：官方 `docs/subsystems/`（session / system-prompt / tools / agent /

agent-loop / scope / llm-streaming / subagent）是各子系统的设计文档，比本节的"能力域分组"更系统化；自动生成的权威清单见官方 `docs/tool-catalog.md`、`docs/config-

catalog.md`、`docs/module-graph.md`。

8.2 内置工具（实测观察）

模型实际可调用的工具名是**简短动词**（实测记录，来自 dsh web 会话与 agent/request 日志）：

（用于产物追踪）

**工具结果与产物追踪**（重要概念）：工具的返回里带有 `locations`（文件路径），dsh 用它们做"产物文件行"（对话结尾的产物 chips 就是从这里来的）——**模型改了什么文件，

UI 能直接看到并可打开**。

8.3 上下文是怎么喂给模型的

一次模型请求的上下文 = 系统提示 + 技能目录 + 对话历史 + 工具结果。实测在会话日志中可见：

<!-- [style] 示意图代码块统一补 text 语言标签 -->

上下文注入 @deepseek-ai/dsh-system-prompt← 官方系统提示上下文注入 skill-catalog

• 技能目录

dsh 的上下文机制：

• **系统提示分层**：官方插件通过 `systemPrompt.section()` 注册提示片段（如 ui-

deliverables 注册"产物文件引用"指导）

• **技能目录注入**：可用技能列表进入上下文，模型按需调用
• **工具 schema**：每步请求携带工具定义

8.3.1 PTC 模式（Code mode）：一段代码编排多轮工具调用

**PTC = Programmatic Tool Calling（程序化工具调用）**——官方中文站称「PTC 模式」，官方英文页面对应 **Code mode**

（[#1052](https://github.com/deepseek-ai/deepseek-harness/discussions/1052) 评论区社区详解；官方站点原文："PTC 模式通过模型生成的一段代码组合多轮工具调用"）。

**与传统方式的区别**：标准模式下模型**每步发一次工具调用**（一步一往返）；PTC 模式下模型**生成一段 TypeScript 程序**，在单次程序内编排多轮工具调用（循环、分支、

`Promise.all` 并行），整段程序一次往返执行完毕：

维度标准模式PTC 模式（Code mode）

灌

典型场景日常对话、单步任务长链路自动化、确定性执行

**执行机制**：程序交给 `@deepseek-ai/dsh-code-runtime-worker-thread` 在**全新 Node worker 线程**里执行（类型剥离后可擦除 TS；空环境 + 堆/耗时/输出预算 + 硬终

止）；程序内每个子工具调用仍走完整工具流水线（权限、沙箱、审计照常生效）。

**收益**：多步调用一次往返 + 中间结果不再全部塞回上下文 → **token 开销大幅下降** （#1052 评论区实测经验：PTC 模式是长任务降本手段之一）。

> 注意：PTC 模式仍有社区反馈的已知坑——`run_code`/`bash` 的 description required 死循环（见 8.8 坑 1）；且长会话中多轮工具调用的中间产物仍会留在上下文（#1052 原帖实测

70M→100M token 暴涨即发生在 PTC 模式下，见 8.4 节自动压缩需求）。

8.4 长对话：compaction（压缩）

长对话会撑爆上下文。dsh 的 `compaction` 插件（如 `compaction-basic`）负责：

• 检测上下文溢出（`agent/request-error` 的 `CONTEXT_WINDOW_EXCEEDED`）
• 压缩历史（模型无关的修剪 + 可选摘要）
• 失败时路由到"溢出代理"（overflow agent）

> **自动压缩是社区高频需求**（[#1052](https://github.com/deepseek-ai/deepseekharness/discussions/1052)）：用户反馈长会话 token 暴涨后"要开新会话"很痛苦，希望**自动

压缩而非手动新会话**——社区回复确认"现在内置应该是没有自动压缩"（需装 compaction 插件 /手动 compact）。想低成本延续长会话的临时做法：换新会话 + 按需注入记忆（记忆分层方案见

第 7 章 7.3 节与第 14 章 14.7 节生态工具）。

> 对新手：**知道"长对话会自动压缩"即可**，细节是进阶话题。生产环境注意：压缩会丢细节，重要上下文建议手动写进提示词。

8.5 权限与安全模型（了解即可）

• **访问模式**：UI 里可见「Workspace Write」等模式（权限预设）
• **交互审批**：`interaction/*` 提供权限/审批能力（危险操作可要求确认）
• **沙箱**：`sandbox/*` 隔离命令执行（如 pwsh 沙箱有 ACL 约束——实测中遇到过

temp 目录权限问题）

• **工具超时**：`guard/*` 提供 loop 卫生与工具超时