前言¶
DeepSeek Harness (DSH) 默認的 Headless 運行器通常是一次性的，難以處理需要多輪交互的複雜場景，也不方便獲取結構化輸出。dsh-plugin-cli-session 插件解決了這個問題。它是一個支持恢復的 Headless CLI 會話運行器，由用戶 ghbhiee 維護。它將原有的對話型運行器與 claude -p 風格的運行器合併，統一了會話解析、驅動循環和摘要處理邏輯，同時支持多目錄隔離和標籤管理。
核心功能¶
該插件主要提供以下能力：
1. 會話恢復：支持繼續最新的會話或通過 ID 指定會話。
2. 多目錄隔離：通過 --workdir 指定工作目錄，不同目錄下的會話互不干擾。
3. 機器可讀輸出：支持 JSON 格式輸出，便於腳本處理。
4. 會話管理：支持通過標籤和列表功能管理會話。
安裝¶
插件通過命令行安裝，無需構建步驟。
dsh plugin --profile chat add github:ghbhiee/dsh-plugin-cli-session
也可以從本地克隆安裝，以便進行本地重建和調試。
git clone https://github.com/ghbhiee/dsh-plugin-cli-session.git
dsh plugin --profile chat add ./dsh-plugin-cli-session
配置¶
插件通過配置文件管理會話配置。通常需要修改 ~/.dsh/profiles/chat/cordis.patch.yml 或 ~/.dsh/profiles/api/cordis.patch.yml。
需要重置 config 字段，並指定 request 爲 !!js ctx.cliStartup。以下是兩個典型的配置示例：
對話模式：
- id: cli-runner
config:
request: !!js ctx.cliStartup
sessionTag: chat-cli
announceSessionId: true
機器可讀模式：
- id: cli-runner
config:
request: !!js ctx.cliStartup
sessionTag: api
announceSessionId: false
配置項說明：
* sessionTag：默認爲 cli。寫入會話的 agentPreset 中，也是 --list 和 --resume 的作用域，確保同一目錄下不同配置的會話互不干擾。
* announceSessionId：默認爲 false。決定是否將會話 ID 寫入標準錯誤流（stderr），stdout 保持純淨。
* exitGraceMs：默認爲 1500。優雅退出前的等待時間。
典型用法¶
插件提供了多種命令行參數來控制行爲。
- 新建會話
在默認目錄啓動新會話：
dsh --profile chat "explain this file"
- 恢復會話
繼續當前目錄下最新的會話：
dsh --profile chat -r "follow-up"
繼續指定 ID 的會話：
dsh --profile chat -s <id> "follow-up"
- 多目錄會話
在指定目錄下啓動新會話：
dsh --profile chat -w ./scratch "start here"
- 列出會話
列出當前配置的所有會話並退出：
dsh --profile chat -l
- 機器可讀輸出
以 JSON 格式輸出結果，不包含對話文本：
dsh --profile api -o json "summarize this"
以流式 JSON 輸出：
dsh --profile api -o stream-json "summarize"
重要注意¶
使用時需注意以下幾點：
--json-schema的含義：該參數傳入的是提示文本，要求模型按照該 Schema 輸出 JSON，而不是開啓 provider 的結構化輸出模式。模型仍可能返回代碼塊或註釋，解析時應做防禦性處理。- 輸出內容：CLI 模式僅返回最後一條助手消息，中間的對話輪次記錄在會話日誌中。
is_error的覆蓋範圍：只要會話狀態不是completed，is_error字段就會爲true，包括未開始的輪次。sessionTag的存儲：該字段存儲在agentPreset中，是一個借用字段，並非官方文檔的擴展點。- 硬退出機制：
exitGraceMs設置了一個優雅退出的超時時間，超時後進程會被強制殺死，這可能導致非常慢的刷新被截斷。
