信息层级：【有据可查】= 附官方文档或可信来源链接；【社区共识】= 社区用户普遍经验，未经官方确认；【待考察/推测】= 推测或暂未能核实，请谨慎对待。
📌 与安装入门的分工：下载、首次配置、沙箱模式、插件挑选已在DSH 安装、首次配置与社区插件中讲过，本篇专注"装好之后每天怎么用、怎么玩得更深"。
1. 定位速览
| 项目 | 内容 | 层级 |
|---|---|---|
| 出品方 | DeepSeek（开源，MIT） | 有据可查：GitHub |
| 核心理念 | "一切皆插件"，基于 Cordis | 有据可查：官网 |
| 状态 | developer preview，会有破坏兼容的变更 | 有据可查：README |
| 形态 | Web UI、headless、SDK、ACP、桌面 | 有据可查：CLI README |
| 订阅方案 | dsh 本身免费开源；费用来自你接入的模型 API（如 DeepSeek 开放平台按量计费） | 有据可查：MIT 协议；模型计费见 DeepSeek 定价 |
2. 四种模式怎么选？【有据可查】
| 模式 | 一句话 | 建议使用场景【待考察/推测】 |
|---|---|---|
| Standard | 完整工具集 | 90% 的日常任务 |
| Code | 用 Code Mode SDK 让模型"写程序调工具" | 批量改名、多文件同类修改、数据处理 |
| Minimal | 仅持久 bash + str_replace_editor |
对比不同模型"裸能力"（呼应 模型能力实测：固定条件、题库与评分表 实测篇） |
| Creator | 运行时检查 + 插件实验 + 预设编写指导 | 进阶用户定制自己的工作流 |
3. 一天的典型工作流
3.1 早上：开工三件事
- 从项目目录启动：
dsh以"调用目录"为默认工作区根目录。【有据可查】 - 选择工作区：Web UI 未选工作区时输入框不可用。【有据可查：Web UI 指南】
- 先让它"读"再让它"写"：先查看当前会话沙箱与审批策略；只读阶段确认有效文件策略为
read-only，再做摘要与计划，阅读并确认计划后，才按任务需要选择workspace-write。【社区共识；默认值辨析见下方官方依据】
3.2 会话与模型的小知识【有据可查】
来源：模型配置指南
- 选中某模型会成为新会话的默认模型；已发出请求的会话会保留它日志里记录的模型。
- 模型配置修改在下一次请求生效，无需重启。
- Effort（推理强度）菜单：DeepSeek 自家路由提供
off/low/high/max；默认值可用llm-deepseek.reasoningEffort设置。
# $DSH_HOME/profiles/web/cordis.patch.yml
- id: llm-deepseek
config:
reasoningEffort: high # 日常建议 high；简单任务可 off 省钱（实践建议，待考察）
3.3 提示词习惯（经验判断）【社区共识/待考察】
| 不好的写法 | 更好的写法 |
|---|---|
| "帮我优化一下代码" | "把 src/api/*.ts 里重复的错误处理抽成一个函数，不改对外接口，改完跑 pnpm test" |
| "修 bug" | "复现步骤：…；期望：…；实际：…；先定位原因再改" |
| 一次塞 10 个需求 | 拆成多个会话，每个会话一个目标 |
4. 进阶一：headless 进 CI / 脚本【有据可查】
dsh --profile headless "run the tests and summarize failures"
echo "exit code: $?" # 0 = 完成, 1 = 中止或出错
- 一次调用 = 一个任务，打印最终答案后退出；不开端口、不留后台进程。
- 推理过程流式输出到 stderr（
dsh: reasoning:标题下），最终答案在 stdout。 - 适合：定时巡检、PR 检查脚本、批处理。
- ⚠️ 在 CI 中运行时，API Key 用 CI 平台的密钥管理注入，不要写进仓库。【社区共识】
5. 进阶二：ACP 与 SDK——把 dsh 嵌进别的工具
| 方式 | 命令 | 用途 | 层级 |
|---|---|---|---|
| ACP | dsh --profile acp |
通过 ACP（Agent Client Protocol）over stdio 供自动化客户端/编辑器调用 | 有据可查 |
| SDK | dsh --profile sdk |
JSON-RPC over stdio；TypeScript SDK 与 Python SDK | 有据可查：Python SDK 指南 |
| SDK 最小版 | dsh --profile sdk-minimal |
独立的最小 Agent 树（不套用 dsh-base） | 有据可查 |
【待考察/推测】哪些编辑器/客户端已经可以直接以 ACP 方式接入 dsh，需以各编辑器文档为准，本文未逐一验证。
6. 进阶三：自定义 profile——为不同项目准备不同"人格"
# 基于 web 模板创建一个专用 profile
dsh --profile frontend --from-default-profile web
【有据可查】profile 是"有序的插件补丁层 + 你的覆盖配置"；配置文件位于 $DSH_HOME/profiles/<profile名>/cordis.patch.yml。
分 profile 的经验方案【待考察/推测】：
| profile | 用途 | 模型/设置倾向 |
|---|---|---|
web（默认） |
日常 | 主力模型、high effort |
review |
只读审查 | 沙箱保持 read-only |
bench |
模型对比 | Minimal 模式 + 多个 provider |
trial |
试插件 | 与日常隔离 |
7. 进阶四：实验性功能（谨慎使用）【有据可查】
官网将以下功能标注为 Experimental：Agent teams（多 Agent 协作）、Auto approval review（自动审批审查）、Scheduled tasks（定时任务）、Voice input（语音输入）。来源：https://www.deepseek.com/en/harness/
- 【社区共识】实验性功能可能随版本变更甚至移除，不建议把关键流程建在其上。
- 定时任务意味着"无人值守执行"，务必配合保守沙箱。
8. 进阶五：把 Web UI 发布到服务器（团队/远程使用）
- 【有据可查】官方有《Publish the Web UI behind a reverse proxy》指南：public-deployments.md
- 【有据可查】SSH 远程启动时 dsh 只打印主机地址，由 SSH 客户端/编辑器负责端口转发。
- 【社区共识】优先用 SSH 端口转发访问，而不是直接把 3080 端口暴露到公网；确需公网访问请加认证与 HTTPS（见 VPS 入门：连接、账号、防火墙与日常维护 VPS 入门）。
9. 接入自定义模型（速查）
详细原理见DSH 添加模型：协议、地址、密钥与模型 ID。dsh 支持三种协议：openai-completions、openai-responses、anthropic-messages；内置目录含 anthropic、openai、moonshotai、zai 等；OAuth 登录类（如 Codex 订阅）暂不支持直接添加。【有据可查】
10. 常见报错（日常使用向）
| 现象 | 可能原因 | 处理 | 层级 |
|---|---|---|---|
| 输入框灰色 | 未选工作区，或默认模型被删除显示 "Select model" | 选工作区/重新选模型 | 有据可查 |
MISSING_CREDENTIAL |
Key 未保存/环境变量缺失 | Models 页保存 | 有据可查 |
UNKNOWN_MODEL |
模型 ID 不在配置 | 添加模型 | 有据可查 |
UNSUPPORTED_REASONING_EFFORT |
模型不支持所选 effort | 换 effort 或模型 | 有据可查 |
SANDBOX_UNAVAILABLE |
无可用沙箱后端 | 安装系统依赖，不要直接关沙箱 | 有据可查 |
| 升级后配置不生效 | 预览版破坏性变更 | 查 release notes，重建 profile | 社区共识 |
11. 适合人群
- ✅ 愿意折腾、喜欢开源、重视安全默认值的开发者
- ✅ 想把 Agent 嵌入脚本/CI/自研产品的人（headless、SDK、ACP）
- ⚠️ 追求"开箱即用、永不变化"的用户：预览期可能不太适合【待考察/推测】
12. 本篇无法核实/需谨慎的点
- 哪些编辑器已原生支持以 ACP 接入 dsh。
- Code 模式、Creator 模式的具体性能/成本差异：无官方数据。
- 实验性功能的稳定性与后续去留。
- 分 profile 方案与 effort 建议为经验判断。
小白练习：把本文流程逐项走通
练习目标：完成一次先读、计划、修改、测试和复核的任务。
上文已介绍概念、配置和操作示例。下面侧重第一次实际操作时的顺序、检查点和结果核对；需要查具体参数时回到对应小节。命令逐条输入，看到上一条的结果后再继续。
-
先保存当前项目的一份可恢复副本，再从项目目录启动 DSH。确认浏览器中选中的工作区与终端目录一致。
-
先让它列出结构和测试入口，不修改文件；阅读计划后再给出一个范围明确的改动。
-
为该会话选择适当权限，保留模型名称和 effort 记录。权限策略与模型强弱是两组独立设置。
-
完成改动后查看修改文件列表，逐条运行项目测试，再打开最终文件检查实际效果。
-
把日常开发、只读审查和插件试验放进不同 profile。修改覆盖配置前备份文件，并查看合成后的配置。
-
headless 示例只在练习项目运行。先核对退出码，再分别查看最终输出和错误输出，最后才接入自动任务。
profile 名称不能代替权限检查
【有据可查】review 只是示例 profile 名称；名字本身不会限制写入。dsh-sandbox-policy 的缺省值、组合后的默认配置和会话保存的权限是不同层次。官方预设包含 workspace-write + ask、danger-full-access + never，实际会话以有效策略为准。
【操作补充】分别进入日常、审查和插件试验 profile，检查合成配置，再查看实际会话的 Permissions；审查 profile 要验证文件策略确实只读。恢复旧会话或改变配置后，再核对一次，不把新 profile 的默认值自动套给旧会话。