前言¶
在 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 界面（推薦）¶
- 打開 DSH Web，進入左側 Plugins（插件） 頁
- 選擇 Add plugin（添加插件），填寫
dsh-narrator，或 GitHub 源github:Chasterccj/dsh-narrator - 確認 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
| 字段 | 默認 | 說明 |
|---|---|---|
narration |
true |
重要動作前/後各一句白話說明 |
gate |
true |
不可逆動作先問用戶才放行 |
interrupt |
true |
用戶在執行中發消息 → 取消當前 turn |
children |
report |
子代理不可逆時的處理方式 |
importantTools |
[] |
追加重要動作工具名 |
quietTools |
[] |
強制靜音（同時關閉該工具的硬門禁） |
irreversibleBash |
[] |
追加不可逆 shell 正則 |
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
