deepseek-harness/apps/cli/reference/README.zh.md

dsh CLI（命令行界面）行为参考

English | 中文

本参考定义原始配置、Web 和无头命令模式。参数由 src/args.ts 统一解析，src/bin.ts 只动态导入选中的运行器。

原始配置

原始 dsh 必须提供显式 patch 列表配置：

dsh --config ./app.cordis.yml

指定文件通过 Include 插件的 patch 算法直接应用到 config/base.cordis.yml 之上。它不是完整替代树，也不会添加任何 surface overlay。基础配置刻意不包含启动 agent（智能体）或交互前端入口；必填 overlay 负责选择这些部署细节。相对配置路径从调用目录解析。配置解析、schema 校验、模块解析或插件启动失败会得到报告并以非零状态退出。收到 SIGINT 或 SIGTERM 时，挂载的根节点会先 dispose（资源释放）再退出。

patch 通过 id 定位基础配置行，并替换该行完整的 config 值，而不是深度合并各键。patch 列表也可插入新行，只要随附 Loader 能解析其插件模块：

- id: agent-loop
  config:
    agents:
      - id: main
        provider: deepseek-official
        model: deepseek-v4-flash

可在不启动的情况下检查生效的配置树：

dsh --dump-default-config
dsh --config ./app.cordis.yml --dump-config

--dump-default-config 只打印随附基础配置。--dump-config 必须与 --config 同时使用，并打印基础配置和带来源注释的 overlay。组合使用 @cordisjs/plugin-include 的 applyEntryPatches 与 entryListSchema；!!js 表达式保持未求值，找不到目标的 patch 会报告到 stderr。

Web 与无头模式

dsh web 启动 base.cordis.yml 加 config/web.cordis.yml，随后在给出 dsh web --config <path> 时应用该显式 patch 列表。磁盘上不会自动发现任何东西：overlay 只有被点名才会抵达一次启动。--host、--port、--workspace-root 和可重复的 --trusted-host 值会成为 Web 宿主 patch；负责这些值的插件 schema 会在启动时验证它们。--dev 挂载客户端插件 HMR（热模块替换）接收器；若要无刷新更新客户端 bundle，还需单独运行 pnpm run dev:web watcher。

dsh web
dsh web --config ./web-profile.cordis.yml
dsh web --dump-default-config
dsh web --dump-config

生产 Web 运行器需要已构建的包和前端产物（pnpm run build）。默认服务地址是 http://127.0.0.1:3080。绑定所有接口时，还会信任机器自动发现的 LAN IP 字面量；--trusted-host 可添加 /api 浏览器信任围栏接受的具名 authority。

dsh -p "task" 使用同一基础配置和 Web 组合，在 OS 分配的端口上启动 Web 宿主，运行一个新的持久化会话，打印最终答案并退出。它像其他每个界面一样接受 --config <path>——自动化运行应当点名自己的组合，而不是依赖机器状态——并拒绝原始配置 dump flag。

Web 和无头进程关闭时会给插件树最多 5 秒完成 dispose。第一次 SIGINT/SIGTERM 启动该优雅排空；第二次信号强制立即退出。如果无头模式正常结束时已经卡在 dispose 中，第一次 Ctrl+C 就会升格并立即退出，而不会被吞掉。

两种模式都将调用目录作为默认 workspace 根目录，以 65,536 字节渲染预算加载适用的 AGENTS.md 或 CLAUDE.md 指令，并使用内存 SQLite 会话内容索引。两者都只在启动时读取各自的 overlay 一次。app-boot 的 Harness home 契约负责环境分层和 $DSH_HOME 解析；凭据 provider负责凭据存储。

新会话默认使用 workspace-write 权限预设。Bash 和文件系统修改仅限于会话 workspace 与平台临时根目录；读取、网络访问和进程可见性不受限制。DSH_PERMISSION_MODE 更改进程后备值。General settings 中存储的权限影响后续 Web 会话，不改变已打开的会话。

DSH_TOOLS_MODE 为 Web／无头进程选择 native、code 或 both；其他值会导致启动失败。config/core-web.cordis.yml 是可选 Web overlay：它在保留随附宿主、浏览器、workspace、持久化和权限组合的同时，把原生模型 surface 缩减为持久 bash 和 str_replace_editor。

共享部署行为

基础配置挂载原生 DeepSeek 适配器、settings 与凭据提供方、稳定的 web_search、repository Plugin 支持和会话遥测。提供方凭据存放在 $DSH_HOME/.credentials.yaml 或环境中；启动器从不把该文档提升到 process.env，因此凭据可以轮换。$DSH_HOME/.env 是用户的普通环境层，位于调用目录的 .env 与继承环境之下。搜索使用 DEEPSEEK_API_KEY 并接受 DEEPSEEK_SEARCH_BASE_URL；只有 overlay 插入提供方并启用 web_fetch 后，该工具才可用。

会话事件默认作为 OTLP/HTTP 日志流式发送。DSH_TELEMETRY_OTLP_URL 选择其他 collector。任何非空 DSH_TELEMETRY_DISABLED 都会在启动前禁用遥测配置行。随附基础配置没有遥测脱敏规则，因此导出的记录可能包含消息文本、工具参数与结果以及 workspace 路径；该部署决策由遥测 Agent Note负责。

空 repository-plugins 行让任何被点名的 overlay 挂载已准备的不可变 repository Plugin generation。参见 repository Plugin 契约。CLI 还随附 @deepseek-ai/dsh-mcp-client 作为 overlay 的依赖，但默认不启用 MCP 服务器，因为每条服务器命令都是 agent 沙箱之外的受信任可执行代码。

源码启动器

把源码运行启动器链接到 PATH：

ln -sf "$(pwd)/bin/dsh" ~/.local/bin/dsh

它通过 real path 解析 checkout，并使用 node --import tsx/esm 启动 apps/cli/src/bin.ts。TSX_TSCONFIG_PATH 固定到 checkout 根目录，因此 workspace 包解析不依赖调用目录。pnpm run dsh 使用同一入口并转发参数。运行 pnpm run build 后，构建形式为 apps/cli/lib/bin.js。