前言¶

在 DSH 里跑智能体时，很多团队会把规范、笔记、规格说明放在工作区外的固定目录——例如个人笔记盘、跨项目共用的 spec。原生 @deepseek-ai/dsh-agent-instructions 会沿当前工作目录的祖先链发现 AGENTS.md 一类文件；换工作区或 cwd 不在那条链上时，锚点就失效。下面介绍的 dsh-live-docs（维护者 abluefan，分类：工作流）把锚点改成你在配置里显式列出的绝对路径（可含 glob），文件改动后按尾部追加方式进入模型上下文，且不绑当前工作区。

这是什么¶

dsh-live-docs 是 DeepSeek Harness 社区插件，仓库 abluefan/dsh-live-docs，目录页见 skillhub.cn。一句话：让若干绝对路径文件的变更，在 agent 每步执行前自动以尾部追加形式到达模型，机制对齐原生 agent-instructions（四态、预算、<system-reminder> 框架），只把「cwd 祖先链」换成「绝对路径清单 + preset 过滤」。

与原生 AGENTS.md 的差异¶

0.2.1 起配置不再走 settings.yaml，写在 profile patch 对应插件 entry 下。

核心机制（摘要）¶

插件挂在 agent/pre-step：decision.messages 会被 append 成 user/message，内容持久、留痕，尾部追加有利于不砍前缀缓存。

• 四态：没变 / 变了 / 删了 / 读不到（读不到时保留上一版，不当成删除）
• 状态写入消息 source.changes，重启后扫 surface 恢复
• 自行拼装 <system-reminder> 并转义内容中的闭合标签
• 措辞类型：baseline / additional / updated / removed / notice
• 一次多个变化合并为一个块；按字节预算、UTF-8 安全截断，并用 marker 报告
• files[].mode：inline 全文注入；notice 仅提示存在，需要时再读；超大文件会按 maxInlineBytes 降级为 notice；整批超过 maxBatchBytes 时按顺序丢弃后续并报告

presets[].name 必须等于 session.header.agentPreset，只有匹配的 preset 才会生效。

安装与启用¶

DSH 版本要求：≥ 0.2.1-rc.2（见仓库 package.json 的 engines.dsh）。插件以当前 dsh 进程权限读盘，安装前请自行查看源码与 MIT 许可证。

通过插件市场（推荐）¶

在 awesome-dsh-plugin 目录查找，或在 dsh 插件 → 发现 中搜索 dsh-live-docs 安装。

手动安装（二选一，不要同时使用）¶

A. 复制目录 + 手写 insert（本地开发）

1. 将插件目录复制到 $DSH_HOME/profiles/web/node_modules/dsh-live-docs/
2. 在 $DSH_HOME/profiles/web/cordis.patch.yml 增加：

- insert:
    - id: live-docs
      name: 'dsh-live-docs'

3. 重启 dsh，或让 Loader 重载配置。

B. npm 包已发布时使用

dsh plugin --profile web add dsh-live-docs

使用 B 后包名会进入 dsh.profile.bundles，bundles 层会读本包自带的 cordis.patch.yml；不要再做 A 的第 2 步，同一 id 插两次会导致 DSH 启动失败。

典型配置¶

在 cordis.patch.yml 本 entry 的 config 中写入 preset 与文件列表，例如：

- insert:
    - id: live-docs
      name: 'dsh-live-docs'
      config:
        presets:
          - name: my-preset
            files:
              - { path: 'D:\notes\*.md', label: notes, mode: inline }
              - { path: 'D:\docs\spec.md',                mode: notice }
        maxInlineBytes: 262144
        maxBatchBytes: 524288

path 为绝对路径；含 * 时按 glob 展开（Node 22+ 内建 fs.glob）。label 供 UI 显示。

同一份文件清单可在多个 preset 中引用，减少重复配置漂移：

sharedFiles:
  - name: core
    files:
      - { path: 'D:\notes\*', mode: inline }

presets:
  - name: preset-a
    include: [core]
  - name: preset-b
    include: [core]

下列三个顶层配置字段标了 .volatile()：只改它们时 Loader 不 remount，直接提交到运行中的 fiber.config；每次 agent/pre-step 用 current() 读最新值，改配置立刻生效、不必拆会话。只有改插件代码才需要重启 DSH。

适用场景与注意¶

适合：会话 preset 固定、但希望模型始终跟上工作区外某几份活文档（笔记、规格、团队 wiki 导出等）；需要与原生 instructions 类似的变更感知与预算控制，又不想依赖 cwd 祖先链。

注意：

• 路径必须是本机绝对路径，glob 依赖 Node 22+ 运行环境。
• session.header.agentPreset 与 presets[].name 不一致时，该 preset 不会加载任何文件。
• 插件读文件权限等于 dsh 进程；勿把无权限或敏感路径 blindly 加入清单。
• 社区目录与 DeepSeek / 幻方无官方从属关系，安装来源以你信任的 market 或 GitHub 为准。

结尾¶

dsh-live-docs 把「活文档进上下文」从工作区锚点解耦到绝对路径 + preset，改动以尾部追加进模型，并支持 inline/notice 与字节预算。进一步细节见 GitHub README 与 插件目录页。