第 19 卷

动手练习（检验你是否真懂了）

1. **理解题**：不看原文，说出 dsh 生态的 3 个官方入口（仓库/API 文档/社区）各自

的用途 > 自查：参考本章 7.1 节官方入口表格

1. **理解题**：官方当前"不接受外部 PR"，但鼓励哪三种参与方式？为什么"做 dsh-

plugin 生态项目"是官方点名认可的方式？

> 自查：参考本章 7.1 节"但鼓励"段落

1. **动手题**：在 GitHub 搜索 `topic:dsh-plugin`，列出你找到的 3 个社区插件，说

出每个插件的定位 > 自查：参考本章 7.3 节"发现插件"段落 + 7.7 节搜索渠道表格

1. **动手题**：按本章 7.6 节的步骤，完整挂载 `DSH-better-sidebar` 或按第 4 章示例

自己写一个提速插件，记录 `pnpm install` 的输出和验证结果 > 自查：参考本章 7.6 节两处改动的完整代码片段

1. **动手题**：给 `DSH-better-sidebar` 或自己写的提速插件的 README 提一个改进

PR（比如加一个安装步骤、修一个 typo），体验社区 PR 流程 > 自查：参考本章 7.4 节第 2 步 + 第 5 章案例的 PR 范式

1. **思考题**：本章 7.9 节时间线显示"60+ 官方包同步放出"和"社区插件爆发"发生在

同一天。这对开源项目的生态策略有什么启示？

> 自查：参考本章 7.9 节时间线表格 + 7.10 节联动模式

常见疑问 FAQ

**Q1：官方说"不接受外部 PR"，那我的插件代码放哪？**

放在你自己的 GitHub 仓库，作为独立的 dsh-plugin 生态项目。官方鼓励这种方式——通过插件扩展能力，无需改 dsh 核心。给仓库加 `dsh-plugin` topic，npm 发布即可。

**Q2：Discord 和 Discussions 有什么区别？**

Discord 适合实时讨论；Discussions 适合正式提案、功能建议、求助（有记录可查）。官方当前建议的贡献入口是 Discussions。

**Q3：我想写中文教程/博客，有格式要求吗？**

没有官方格式要求。建议包含安装步骤、代码示例、实机截图/日志。可参考本白皮书结构（TL;DR + 分步讲解 + 练习）。

**Q4：生态零日是什么意思？为什么说是"先发优势"？**

生态零日 = 生态刚起步，内容/插件/教程几乎为零。先发优势 = 早期入场者容易成为"某个方向的标杆"。类比：2015 年写 React 教程的人、2018 年做 VS Code 插件的人。

**Q5：rc 阶段迭代快，我的插件会不会刚写完就过时？**

有可能。降低风险：① 依赖用 `^0.1.0-rc.6` 线；② 关注官方 changelog；③ 逻辑用纯函数隔离，接入层薄一点，升级时只改接入层。

**Q6：我想做 dsh 生态项目，但从哪开始？**

从"自己的痛点"开始。比如：① 想要 TUI → 做 tui profile 插件；② 想要 token 追踪 → 做 cost-tracker 插件；③ 想要 diff 视图 → 做 diff 插件。参考本章 7.5 节阅读路径。

**Q7：7.6 节的 `link:` 路径在 Windows 和 macOS 下写法一样吗？**

不一样。Windows 用双反斜杠转义（`link:C:\\path\\to\\plugin`），macOS/Linux 用正斜杠（`link:/path/to/plugin`）。建议社区插件最终走 npm 发布，消除路径差异。

**Q8：官方讨论区发帖有什么技巧，能让官方更快响应？**

参考 7.10 节 3 个原则：带环境信息、带复现步骤、先搜索避免重复。功能建议说明"解决什么问题"比"怎么实现"更重要。

第 8 章：工具与上下文系统

> 本章目标：理解 dsh 的"能力引擎"——模型能调用哪些工具、上下文是怎么喂给模型的、以及长对话怎么处理。**这是从"能跑"到"跑得明白"的关键一章。**

TL;DR（本章核心，30 秒版）

1. **60+ 官方能力包**：工具（fs/shell/web/skill/todo）、上下文

（context/compaction）、会话、子代理、MCP、工作流、安全、模型、界面——一切皆插件

1. **内置工具名是简短动词**：`read`/`write`/`grep`/`glob`/`edit`/`bash`/`todo`/`skill`

——写提示词直接说"读文件""搜索"即可

1. **工具返回 locations → 产物追踪**：模型改了什么文件，UI 能直接看到并可打开

（对话末尾的产物 chips）

1. **上下文 = 系统提示 + 技能目录 + 对话历史 + 工具结果**：分层注入，每步请求携

带工具 schema

1. **长对话自动压缩（compaction）**：检测溢出 → 修剪历史 → 可选摘要 → 失败路

由到溢出代理。重要信息建议写进提示词

1. **插件行为可零成本验证**：mock llm + headless + 审计 dump（#462）——没有

API key 也能验证 waterfall 透传与工具注入

1. **工具链有三个已知坑**：code 模式 run_code/bash 的 description required 死循

环（#558/#581/#689）；流式下工具名被抹空（#725 同族，见 FAQ）；run_code 内交互式工具异步结果被丢弃（#1476）

<details><summary>本章导航</summary>

• [8.1 官方能力包地图（60+ 包一览）](#81-官方能力包地图60-包一览)
• [8.2 内置工具（实测观察）](#82-内置工具实测观察)
• [8.3 上下文是怎么喂给模型的](#83-上下文是怎么喂给模型的)
• [8.3.1 PTC 模式（Code mode）：一段代码编排多轮工具调用](#831-ptc-模式code-

mode一段代码编排多轮工具调用)

• [8.4 长对话：compaction（压缩）](#84-长对话compaction压缩)
• [8.5 权限与安全模型（了解即可）](#85-权限与安全模型了解即可)
• [8.6 新手最该记住的三件事](#86-新手最该记住的三件事)
• [8.7 插件运行时验证方法论（零成本）](#87-插件运行时验证方法论零成本)
• [8.8 工具链踩坑](#88-工具链踩坑)

</details>

8.1 官方能力包地图（60+ 包一览）

dsh 的能力全部以包形式提供（`packages/<group>/<name>`）。新手最需要认识的：