7.1 CLI 模式

本节目标

认识 dsh 的命令行玩法：一次运行、自定义配置、插件管理，脱离图形界面也能用。

图形界面之外，还有命令行

整本书都在讲 Web UI，但 dsh 不只有图形界面。dsh 命令本身是一个多模式启动器，除了 dsh web，还有几个有意思的模式。

四种入口模式

命令	干什么	适合
`dsh web`	启动图形界面（整本书的主角）	日常交互
`dsh --profile headless "任务"`	跑一次任务，打印结果后退出	自动化、脚本、CI
`dsh --profile <名字>`	启动指定配置档案	自定义场景
`dsh plugin --profile <名字> <参数>`	管理该档案的插件	插件安装维护

0.1.6-alpha.2 起，profile 名还能当命令用：dsh 后面紧跟的第一个参数如果不是选项、也不是 plugin，就展开成 --profile <名字>。dsh headless "任务" 和 dsh --profile headless "任务" 完全等价，自定义 profile 也一样（dsh myprofile）；plugin 保留为命令优先，想启动同名 profile 就写显式的 dsh --profile plugin。

headless：一句话跑完一个任务

最有意思的是 headless 模式。它不需要界面，一条命令把任务干完就退出：

dsh --profile headless "总结当前目录下这个项目的结构"

跑完后终端里直接打印 agent 的回答，适合写进脚本、定时任务、CI 流水线。可以把它理解成 dsh 的"命令行版"。

profile：你的专属配置档案

dsh 用 profile 管理不同的运行配置。每个 profile 是一套独立的插件组合和配置：

web 和 headless 是内置的，首次使用自动初始化
其他 profile 通过 dsh plugin 命令创建
每个 profile 有自己的插件、补丁和配置，互不干扰

运行 headless 需要什么

和图形界面一样需要模型密钥。headless 模式通过环境变量读取：

export DEEPSEEK_API_KEY="你的密钥"
dsh --profile headless "任务"

机器可读输出：给脚本和监督进程用

0.1.6-alpha.1 起，headless 新增了一组给程序消费的开关，默认用法完全不变：

dsh --profile headless [--json] [--session-id <id>] ["任务" | -]

--json：stdout 从「最终一条回答」换成逐行 JSON 事件流，依次输出 session（会话 ID）、status（轮次/步骤边界与用量）、text（助手文本块）、thinking（推理块）、tool_call / tool_result（工具调用与结果）、final（最后回答）。推理过程变成一条事件，不再刷 stderr。脚本可以按行解析，精确掌握 agent 每一步干了什么
--session-id <id>：指定要续接的会话。它只采用已存在的持久化会话，ID 写错或不存在会直接报错，不会悄悄开出一段空历史；不带该参数时照旧新建随机会话，会话 ID 在第一条 session 事件里告诉你。外部监督进程把第一轮拿到的 ID 存下来，后续每轮传回去，就实现了多轮连续自动化
stdin 传任务：位置参数写成 - 或者干脆不传任务，任务文本就从标准输入读取。长提示词（超出命令行参数长度的那种）走管道最稳妥

最小示例

跑一轮拿会话 ID，第二轮续上：

out=$(dsh --profile headless --json "整理这个仓库的 TODO")
sid=$(echo "$out" | head -1 | jq -r .sessionId)
dsh --profile headless --json --session-id "$sid" - <<'EOF'
继续刚才的任务，把 TODO 按优先级排序
EOF

每行事件都有固定结构，jq、Python、Node 都能直接消费。

启动失败时看哪里

0.1.6-alpha.2 起，CLI 的启动诊断更完整：启动失败时，完整的诊断信息会保存到 $DSH_HOME 下的日志目录，终端上把失败按「出错的服务」和「还在等待的服务」分组展示，不用再从一屏滚动日志里扒线索。报障或排查时，把日志目录里最新的诊断文件带上，一眼就能定位是哪个插件或服务没起来。

常见问题

问：图形界面和 CLI 能同时用吗？

能。它们共用同一套 dsh 安装，只是入口不同。

问：CLI 适合新手吗？

日常干活用图形界面更直观。CLI 是给自动化和进阶场景的，先知道有这些模式就行，用到再学。

小结

dsh 是四模式启动器：web、headless、自定义 profile、插件管理
0.1.6-alpha.2 起 profile 名可直接当命令用（dsh headless "任务" 等价 dsh --profile headless "任务"）
headless 一条命令跑完任务打印结果，适合自动化
0.1.6-alpha.1 起headless 支持 --json 事件流、--session-id 会话续接和 stdin 任务，监督进程可以精确接管多轮运行
启动失败时完整诊断落盘 $DSH_HOME 日志目录，终端按服务分组报错
profile 是一套独立的配置档案，web 和 headless 是内置的

CLI 了解了，下一节把权限和沙箱的底层讲透。

7.1 CLI 模式 ​

图形界面之外，还有命令行 ​

四种入口模式 ​

headless：一句话跑完一个任务 ​

profile：你的专属配置档案 ​

运行 headless 需要什么 ​

机器可读输出：给脚本和监督进程用 ​

启动失败时看哪里 ​

常见问题 ​

小结 ​