前言¶
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设置了一个优雅退出的超时时间，超时后进程会被强制杀死，这可能导致非常慢的刷新被截断。
