第一次打开一个陌生仓库，你可能想让 Agent 找到启动入口、说明测试怎么跑，再解释几个主要模块。真正需要的并不只是一次模型回答：它得能读取文件、执行命令、记住前面读过什么，并在需要授权时停下来。
DeepSeek Harness 把这些能力组合成一个可运行的 Agent 环境，命令叫 dsh。模型负责推理，Harness 负责让它接触工作区、调用工具和持续执行。这个系列从一次具体任务出发，再讨论什么时候值得改它的配置。
版本说明：本轮更新以 CLI 与 TypeScript SDK 的 0.2.0-rc.2 为准，对应上游 dsh-v0.2.0-rc.2。安装与调用示例固定版本。0.1.5-rc.1 的历史排错结果仅在相关章节作为历史记录保留。本轮重新核对发布包与声明，模型任务示例的验收标准会单独说明，不把源码核对写成模型实跑结果。
先让它完成一件小事
第一项任务可以很小：
阅读当前仓库的 README 和包配置，告诉我怎么启动、怎么运行测试，并列出你实际查看过的文件。先不要修改文件。
这个任务能同时检查三件事：工作区选对了吗，模型能正常回答吗，文件工具真的被调用了吗。只收到一段流畅的介绍还不够；要在会话里确认它读取了对应文件，再把启动命令与仓库本身核对。
安装与首次运行会把这条路径走完整：安装固定版本、打开带认证信息的地址、配置模型、选择工作区，最后检查一次文件阅读任务的结果。
三种入口，按任务选择
| 你要做什么 | 从哪里进入 | 主要关注什么 |
|---|---|---|
| 边看过程边交互，让 Agent 读代码或修改项目 | Web UI | 工作区、模型设置、授权与工具记录 |
| 从脚本发起一个任务，收集输出 | headless |
stdout、结构化事件、超时与独立验收 |
| 在自己的应用里管理会话和中间事件 | TypeScript SDK | 子进程生命周期、sessionId、错误处理 |
先选择一种入口即可。能用 Web UI 完成工作的场景，没有必要为了“更完整”先研究 JSON-RPC；需要稳定程序接口时，再读 SDK 的会话和结果语义。
本版本还包含 acp 和 sdk-minimal 等 profile。它们的存在可以在profile 模板声明中核对，本系列不把未走通的集成写成开箱即用的教程。
为什么迟早会碰到 profile
假设你已经能正常运行任务，接下来可能想做两件事：给脚本任务装一个插件，或者关闭不需要的会话标题模型请求。这时才需要理解 profile。
一个 profile 可以看成一份独立的运行方案：它选择哪些 bundle，按什么顺序加载，并保存你自己的覆盖配置。默认数据目录是 ~/.dsh，profile 位于 $DSH_HOME/profiles/<name>/。本系列会把练习数据放进单独的 DSH_HOME，方便试验和回退。
DeepSeek Harness 的特点是很多能力通过插件组合，包括模型接入、会话管理和界面。对使用者最直接的影响是：先找对运行方案，再改对应的配置。给 web 安装的插件，不会因为你改用 headless 就自动出现在另一个 profile 中。
不用猜当前加载了什么。安装后，在练习项目目录运行：
npx --no-install dsh --profile headless --dump-config
它输出组合后的配置，适合回答“这项能力到底有没有启用”。配置怎样合成、为什么一个覆盖可能让其他字段消失，留到配置覆盖篇具体说明。
按你的目标选一条阅读路线
第一次使用，按 导论 → 安装与首次运行 阅读。完成第一个任务后，有疑问再进入下面的主题。
| 文章 | 读完应当能做什么 |
|---|---|
| 安装与首次运行 | 配置模型与工作区，检查首个任务是否真正读取了文件 |
| headless 与 CI | 从脚本运行任务，并让测试命令独立决定流水线结果 |
| TypeScript SDK | 管理运行实例、保持多轮会话并处理空结果 |
| profile 与插件管理 | 判断插件装到了哪里，以及是否进入运行配置 |
| 写一个配置覆盖层 | 用可回退的 patch 调整行为，并核对实际效果 |
| 选择和验证社区插件 | 区分包已安装、插件已加载和工具已被调用 |
| Web 认证与远程访问排错 | 区分认证失败与请求信任检查失败，理解端口转发的边界 |
自动化方向可以按 headless → CI → SDK 阅读；定制方向可以按 profile → patch → 社区插件阅读。它们共享同一套概念，不要求顺序读完八篇。
开始前，判断它是否适合这次工作
如果你希望检查 Agent 的工具行为、把运行环境接入自己的脚本，或者按工作方式组合插件，这个项目值得试。代价是你需要关心运行版本、profile 和模型配置；插件生态中的兼容性也要自己验证。
如果当前目标只是尽快完成一个已有工具就能解决的任务，先把任务完成。为了使用 Harness 而改造整条工作流，收益往往没有想象中大。
上游仍将项目定位为开发预览，版本升级应先在单独的数据目录和工作副本里试。0.2.0-rc.2 的 Web 启动参数仍明确拒绝 --host 0.0.0.0；需要远程访问时先读鉴权篇，不把本地 Agent 当作已经具备团队权限隔离的共享服务。
从安装与首次运行开始。先得到一次能核对的结果，再决定需要改哪一层。