前言¶
在 DSH 里开新会话时，模型通常只能看到规则、工具说明和工作目录路径，对仓库里已有 README、CHANGELOG 或设计笔记往往一无所知。常见做法是上来就 glob / grep，多占轮次，也容易漏读该先看的文档。下面介绍社区插件 dsh-workspace-docs（维护者 YumenoSayuri，GitHub：YumenoSayuri/dsh-workspace-docs），它把当前工作区的顶层文件夹名与各处的文档文件名清单注入模型可见的运行时上下文，只列名、不读内容，让 agent 接任务时先按清单打开文档，再决定是否搜索代码。
这是什么¶
dsh-workspace-docs 是 DeepSeek Harness（DSH）下的「记忆」类插件（社区目录：SkillHub 插件页）。当前版本 0.3.1（MIT 许可证，Node.js >= 20）。它不替模型判断哪份文档重要，只回答「工作区里文档大致在哪、叫什么」；读什么仍由模型用 read 自行决定。
核心功能¶
运行时上下文注入¶
插件通过 ctx.systemPrompt.context() 注册为运行时上下文快照，与官方 working-directory 走同一条通道：模型会当作上下文读取，界面上不显示为聊天气泡。默认排序 order 为 130，排在官方 WORKING_DIRECTORY（100）之后。
注入文本形如 README 中的示例（占位路径，实际以会话工作目录为准）：
当前工作区文件概览（由 dsh-workspace-docs 自动生成，只列文件名，未读内容）：
工作目录：<工作区路径>
顶层文件夹（3 个）：
- app/
- packages/
- scripts/
顶层文档（优先读）：
- CHANGELOG.md
- CONTRIBUTING.md
各文件夹内的文档文件（优先读）：
- packages/api/：README.md、CHANGELOG.md
- packages/web/：README.md
- app/legacy/：README.md、ARCHITECTURE.md
接项目任务时，先按上面的文档清单读 README、更新日志与工程记录，再决定是否搜索代码；
清单没覆盖到目标时再用 glob/grep 定位。
扫描规则（两层、只列文件名）¶
- 顶层列一层；若某目录内部还有子目录（容器布局），再下探第二层找文档，最深两层，不递归。
- 文档识别：扩展名
.md/.txt/.markdown/.rst/.adoc，或文件名含readme、changelog、changes、history、notes、todo、license、contributing。 - 排序：README 优先，其次 CHANGELOG，再次 ARCHITECTURE / DESIGN，最后其余
.md。 - 噪音排除：固定名单（如
node_modules、.git、dist、build、coverage等），以及_开头与.开头的目录；可通过配置ignored追加（不区分大小写），前缀规则始终生效。 - 上限与提示：顶层超过
maxTopLevel时输出「还有 N 项未列出」；渲染后总文本超过maxBytes时按 UTF-8 边界截断。
按请求变更检测与缓存¶
每次请求会检测已列目录的 mtime：未变则复用缓存（README 称约 0.5ms），有增删或改名才重扫（约 8–10ms）。仅修改某文档内容不会改变目录条目，因此不会触发重扫。拿不到会话工作目录时不注入，避免把无关目录清单塞进其他 agent 的 prompt；读取失败也不阻断会话。
依赖与实现约束¶
零外部依赖，仅使用 Node 内置模块（node:fs、node:path、node:os）。插件不 import 任何 @deepseek-ai/* 包，由 bundle patch 以相对路径加载。声明的服务：systemPrompt、workingDirectory。
安装与启用¶
DSH 生态里插件常以 profile 依赖 + bundle 方式启用；本仓库 README 未提供 dsh plugin add github:... 一类命令，请按下列步骤操作。
- 把插件目录放到 profile 能解析到的位置，例如
~/.dsh/plugins/dsh-workspace-docs。 - 在 profile 的
package.json中加入 link 依赖，并把包名写入dsh.profile.bundles：
{
"dependencies": {
"dsh-workspace-docs": "link:<插件目录绝对路径>"
},
"dsh": {
"profile": {
"bundles": ["...", "dsh-workspace-docs"]
}
}
}
- 不需要手改 profile 的
cordis.patch.yml：插件自带dsh.bundle.patch，加载器会读取其中的cordis.patch.yml并插入插件行。 - 重启 DSH，新会话生效。
可选配置示例（与 README 一致）：
- id: workspace-docs
name: dsh-workspace-docs
config:
maxTopLevel: 50
maxDocsPerDir: 12
maxBytes: 4000
order: 130
| 字段 | 默认值 | 含义 |
|---|---|---|
maxTopLevel |
50 |
顶层最多列出多少条（目录优先占名额，剩余给文件） |
maxDocsPerDir |
12 |
每个子目录最多列多少份文档；同时限制容器下最多扫多少个子目录 |
maxBytes |
4000 |
注入文本字节上限 |
order |
130 |
运行时上下文排序位置 |
ignored |
见源码 DEFAULT_IGNORED |
额外排除的目录名 |
典型用法¶
启用后无需单独命令：每个新请求在上下文组装阶段自动带上「工作区文件概览」。模型侧建议流程与插件注入文案一致：
- 接项目任务时，先按清单用
read打开 README、CHANGELOG、CONTRIBUTING 等。 - 清单未覆盖目标路径时，再用
glob/grep定位代码或更深层的文档（插件只扫两层，例如packages/a/src/docs不会自动列出）。
适用场景与注意¶
适合： monorepo 或「工作区顶层多个项目文件夹」布局；希望减少首轮盲搜、优先读既有工程文档的 DSH 会话。
限制（来自 README）：
- 只扫两层；容器下子目录数量受
maxDocsPerDir限制，极多项目时可能截断，需依赖「未列出」提示自行补看。 - 注入快照在会话 compaction 后是否保留，取决于 DSH 上下文保留策略。
安全：插件以当前 DSH 进程权限读取工作目录；安装前请阅读 GitHub 源码 与 MIT 许可证，确认路径与 bundle 配置符合你的 profile 习惯。社区目录 SkillHub 为独立站点，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-workspace-docs 用轻量目录扫描把「文档在哪」写进运行时上下文，配合变更检测避免会话中途清单变旧。需要详情、版本历史（如 0.3.0 改为运行时上下文通道、0.3.1 文档校准）时，见 GitHub 仓库 与 SkillHub 目录页。
