前言¶

在 DeepSeek Harness（DSH）里跑 Agent 时，模型会不会先说明再动手、拿不准时会不会问你、执行过程中你改主意它会不会立刻停下，往往取决于当次推理，而不是固定策略。对日常开发来说，这会带来三类具体问题：重要写盘或跑命令前缺少一句可读的意图说明；不可逆操作在未确认时被直接执行；你中途发一条新消息，当前 turn 仍可能跑完原计划。

dsh-narrator（旁白）是社区维护者 Chasterccj 发布的工作流类 DSH 插件，在宿主侧用提示词与 tools/pre-execute 把上述行为收成可配置的政策层。下面介绍它做什么、如何安装，以及配置与 /narrator 命令的用法。插件目录页见 SkillHub，源码与说明见 GitHub。

这是什么¶

dsh-narrator 是 host-only 的 DSH bundle（当前 package 版本 0.1.0，MIT 许可证），不依赖网络、无运行时额外依赖、无需构建步骤。它面向 DSH >= 0.2.1-rc.2 且 < 0.3.0 的环境，通过 cordis.patch.yml 注入三项默认开启的能力：重要动作旁白、不确定先问（硬门禁）、插话即停。

与「完全交给模型自行决定是否解释、是否提问」相比，该插件把这三件事写成固定策略（旁白段设计为 cache-safe，尽量不破坏前缀缓存），并在不可逆工具调用前由 tools/pre-execute 拦截，直到同 turn 内已通过 ask_user_question 问过用户。

核心功能¶

重要动作旁白¶

在写文件、执行命令、安装或变更插件、改定时任务、派发子代理等动作前后，Agent 会用一句白话说明「要做什么、为什么」，完成后再简要说明结果。

默认视为重要动作的工具包括：write、edit、bash/shell/terminal/run_command、plugin_manager、subagent、subagent_fork、workflow、spawn_teammate、schedule_create/schedule_update/schedule_delete。未在已知列表中的工具默认也按重要动作处理（多解释一句）；read、grep、glob、web_search、todo_write、job_*、list_* 等只读与协调类工具默认不旁白。可通过配置扩展或静音特定工具名（支持 * 通配）。

不确定先问（硬门禁）¶

命中不可逆规则时，模型不能直接执行，须先调用 ask_user_question 向你确认；同一 turn 内问过一次即可复用，确认后重试才放行。

默认不可逆情形包括（节选，完整列表以 README 为准）：

• 写文件：write/edit 解析后的目标路径落在工作区根之外（根目录由 workspaceRoot 或会话 cwd 决定）
• 插件：plugin_manager 的 install_bundle / remove_bundle / set_bundle
• 工具名含 publish / deploy / release
• Shell：如 rm、mv、git push、git reset --hard、npm|pnpm|yarn|bun publish 与包管理 install/remove 等；Windows 下另有 del、Remove-Item 等匹配项

可通过 irreversibleBash 追加正则（不区分大小写）。

插话即停¶

监听你本人发送的新消息时，会取消当前正在执行的 turn，以下一回合按你的最新指示继续，并简短说明已中止的内容。

子代理与 Agent Teams¶

子代理无法直接向用户提问（DSH 限制）。默认 children: report 时，子代理命中不可逆动作会被挡下，并把需用户确认的决策写入结果交回父代理；父代理收到带 NARRATOR-CHILD-GATE 标记的结果时，会收到上下文提示：先向用户确认再重试或调整计划。children 还可设为 soft（只放行）或 off（关闭子代理侧相关策略）。

安装与启用¶

DSH 生态里插件通过 profile 与 Web 的 Plugins 页管理；社区目录 SkillHub 与 DeepSeek / 幻方无官方从属关系，安装前建议自行查看源码与许可证。

Web 界面（推荐）¶

1. 打开 DSH Web，进入左侧 Plugins（插件） 页
2. 选择 Add plugin（添加插件），填写 dsh-narrator，或 GitHub 源 github:Chasterccj/dsh-narrator
3. 确认 bundle 已启用；若未立即生效，可重启一次 DSH

命令行¶

dsh plugin 只负责把包装进 profile，装完后仍需在 Web Plugins 页确认 bundle 已选中（首次可能需要重启）：

dsh plugin --profile web add dsh-narrator
# 或从 GitHub 装：
dsh plugin --profile web add github:Chasterccj/dsh-narrator

卸载：

dsh plugin --profile web remove dsh-narrator

然后在 Web Plugins 页确认 bundle 已移除；可选删除状态文件 $DSH_HOME/narrator/state.json（Windows 一般为 %USERPROFILE%\.dsh\narrator\state.json）。

配置¶

在 profile 的 cordis.patch.yml 里为 narrator 条目增加 config（也可直接编辑 profile 的 patch 文件）：

- id: narrator
  name: dsh-narrator
  config:
    narration: true          # 重要动作旁白
    gate: true               # 不确定先问（硬门禁）
    interrupt: true          # 插话即停
    children: report         # 子代理策略：report | soft | off
    importantTools: []       # 额外重要动作，工具名支持 * 通配
    quietTools: []           # 强制不旁白（优先于 importantTools）
    irreversibleBash: []     # 额外不可逆命令正则（字符串）
    workspaceRoot: ""        # 空 = 用会话 cwd

典型用法：/narrator 命令¶

会话内可用 slash 命令查看或临时覆盖三项开关与子代理策略；覆盖值持久化到 $DSH_HOME/narrator/state.json，重启后保留，/narrator reset 清除并回到配置默认值：

/narrator status                      # 查看三个开关、子代理策略与来源
/narrator on | off                    # 三个行为一起开关
/narrator narration on|off
/narrator gate on|off
/narrator interrupt on|off
/narrator children report|soft|off
/narrator reset                       # 清除命令覆盖，回到配置默认值

先做安装并启用 bundle，再在需要时调低旁白或门禁（例如临时 /narrator gate off），做完敏感任务后用 reset 恢复，是 README 中可直接复现的操作路径。

适用场景与注意¶

适合谁：希望 Agent 在改仓库、跑 shell、动插件与子代理前可读地说明意图，并对删改、发布、越界写盘等操作强制先问；同时需要在长 turn 执行中随时用新消息改向的 DSH 用户。

务必注意：插件以当前 DSH 进程权限运行，门禁与旁白不能替代你自己对命令与 patch 内容的审查。安装前请阅读 仓库源码 与 MIT 许可证；引擎版本需落在 >= 0.2.1-rc.2 < 0.3.0。子代理场景下用户确认仍须由父代理完成，这是 DSH 架构下的设计取舍，而非插件单独能绕过的限制。

结尾¶

经过上面的步骤，dsh-narrator 把「说明、确认、随用户最新消息转向」从模型偶发行为变成可开关、可持久化覆盖的配置与命令。若要在工作流里统一 Agent 交互纪律，可从 Web 或 CLI 安装并在 cordis.patch.yml 与 /narrator 上微调。

• 目录页：https://www.skillhub.cn/plugins/Chasterccj/dsh-narrator
• GitHub：https://github.com/Chasterccj/dsh-narrator