智能体运行时手册 sandbaseai/deepseek-harness-handbook

DeepSeek Harness 手册

English · 简体中文 · 日本語 · 한국어 · Español

收录于 Awesome DeepSeek Harness，这是社区维护的 DSH 生态目录。
SandBase 的 Awesome Agent Runtime 也做了收录，与运行时、沙箱、工具协议基础设施并列。

DeepSeek Harness Handbook — source-backed operator guides, Install Doctor, and Failure Router

智能体优先、以英文为准的实战指南，带你理解、运行、调试并扩展 DeepSeek Harness，附经过审校的简体中文内容和多语言基础。 — 社区维护，开源。

如果这本手册帮你省下了一轮调试，给仓库点个 star。这个信号能帮更多智能体开发者找到有出处支撑的 DeepSeek Harness 指南。

引用或链接本手册

如果你发布 DeepSeek Harness 教程、基准测试、插件或集成，请链接到手册的规范 URL，方便读者跟进有出处支撑的操作手册和最新发布说明：

SandBase. DeepSeek Harness Handbook: source-backed Agent runtime guides.
https://github.com/sandbaseai/deepseek-harness-handbook

本手册由社区维护，独立于 DeepSeek AI。当你做出对版本敏感的论断时，请链接到具体的指南或发布版本。

173 篇规范指南 · 202 篇本地化文档 · 79 项精选 Awesome 资源 · rc.2 + alpha.1 源码锁定分析

这本手册不是命令目录，而是沿着完整的智能体边界展开：模型路由、工具、审批、沙箱、持久化会话、插件、MCP、ACP，以及运维可见的故障恢复。对版本敏感的页面会标明核对时对应的源码版本。

选一条路径，快速拿到证据：

| 运行 | 评估 | 调试或构建 |
| 五分钟快速上手 | 智能体 Harness 评分卡 | 交互式故障路由器 |
| 命令行与无头模式地图 | 智能体运行时地图 | 配置档修复与重置 |
| API 成本边界 | 当前领域状态 | MCP 指南 |

探索智能体生态

精选的 Awesome 资源地图 现已收录 79 个带来源链接的起点，涵盖检查点/回退、侧会话、子智能体可见性、浏览器与 Office 界面、插件发现与健康检查、数据库分析、对抗式工作流评审、智能体演进、移动端访问，以及服务商回退控制。每条都是面向智能体的发现线索，不代表兼容性或安全性背书；安装前请先检查权限、凭据和回滚路径。

从规模上看，固定的上游目录快照包含 271 个枢纽仓库、1,000 个公开的 dsh-plugin 主题仓库，以及 471 条手动补充。本手册刻意只精选一个更小的、带来源链接的子集，让每条都有明确的智能体边界可供检查。

想找中文同行讨论，可以看上游社区的飞书群讨论，获取当前邀请方式和背景信息。它由社区运营，并非 DeepSeek 官方支持；不要分享凭据、私密会话日志或敏感工作区数据。

新增来源验证

| 问题 | 指南证明了什么 |
| 理解 Harness 与框架的区别 | 区分模型、服务商、框架和运行时的职责，让工具、上下文和长时间运行的智能体相关主张在正确的边界上得到检验。 |
| 可续跑子代理只暴露 report | 区分父/子工具视图、预设组合顺序、toolFilter 和冷恢复证据，再决定是否把模型输出的文字当作工具结果。 |
| 只读 Windows PowerShell 成功但 stderr 嘈杂 | 把命令输出与 ConstrainedLanguage 前导诊断分开，在验证窄范围修复时保留 ACL 沙箱。 |
| Firefox 显示空白 Web 客户端，Chrome 正常 | 在触碰服务商凭据或持久化会话之前，先分清浏览器引导、缓存资源、origin/WebSocket 与扩展的边界。 |
| alpha.1 认证 token 无法获取或输入 | 把获取、UI 输入、凭据存储、token 作用域与出站授权当作彼此独立的契约，并保留脱敏证据。 |
| 设置区块在 removeChild 上递归 | 让 NotFoundError 走 DOM 归属与渲染代际证据，而不是误判为已证实的 MutationObserver CPU 循环。 |
| 长时间 ChatView 会话增长 WebContent 内存 | 把渲染进程 DOM 驻留与 Host 内存分开，保留会话，在把重载当作遏制手段之前先测量虚拟化边界。 |
| 按能力从 DSH 生态中挑选 | 用四条有边界的智能体入门路径与多语言地图，从公开 Awesome 目录中挑选技能、记忆、路由、UI、文件、研究与治理资源。 |
| 自定义服务商可能隐藏多协议模型 | 把实时模型发现与服务商默认过滤分开，然后为每个模型固定协议并验证实际请求端点。 |
| 恢复卡在 Pending 的客户端 Cordis inspect 查询 | 把页面拒绝与 Host 结算分开，保留首个有效页面路由，让每次 inspect 等待都有边界。 |
| 评估跨会话记忆，既不泄漏作用域也不丢失存储 | 一旦召回变成模型可见的工具结果，本地 JSON 文件就不再是仅本地的数据路径；需要限定身份、原子写入、损坏隔离、检索预算与明确的隐私文案。 |
| 编辑模型能力，别把声明当成证据 | 图像、推理、容量与网关字段声明的是路由契约；验证真实端点，别把请求头放进整命名空间预设。 |
| 诊断 40 分钟后仍显示的终端命令 | 标准 alpha.1 前台 Bash 默认无法解释这个计时器；重试之前，先梳理后台任务、常驻终端、活动进程和过期展示。 |
| 修复计数平衡但 ID 无效的工具历史 | 调用与结果数量相等，并不证明配对有效；用有序身份台账，并让请求剥离保持可观测，作为兜底。 |
| 阻止空续传分块抹掉有效的工具 ID 和名称 | rc.2 和带标记的 alpha.1 都接受显式的空身份更新；保留第一个有效身份，在策略之前拒绝从未标识过的调用，并让无效记录不进入会话回放。 |
| 一个损坏的会话导致 Web 无法启动时如何恢复 | Windows 上的 plugin tree failed to load 可能只是包住了一个坏掉的 Zstandard 头；先隔离这个产物，再动启动器、配置档或每一个健康会话。 |
| 归类 macOS sandbox-exec ENOENT | 主机可执行文件查找可能成功，而 Harness 沙箱服务商却无法启动；保持 fail-closed 行为，先证明服务商边界，再改权限。 |
| 在 Markdown 中保留单个 ~ 字面量 | alpha.1 调用两个 GFM 解析器时都没有禁用单波浪线删除线；在流式、定稿和纯文本投影中都要验证源文件和已服务 bundle。 |
| 评估有边界的 Ralph 失败后继 | Discussion #109 的恢复方案可以保持 fail-closed：默认关闭、只新建子进程、共享预算、失败状态可观测、无变化即熔断，基础设施故障不重试。 |
| 让 HTTP(S) URL 远离文件系统工具 | Discussion #4862 的 Windows 复现是能力边界故障：在本地路径解析之前拒绝类 URI 输入，保留原始值，把网络获取交给 web/fetch 工具。 |
| 归并压缩与重试用量，同时不丢失成本证据 | Discussion #1886 把重复的分块/消息观测与独立的重试尝试区分开，并让 compaction/summary.usage 在累计核算中可见。 |
上面每一条都标出了对应的官方源修订版本——目前是 rc.2 b150a551… 或 alpha.1 cd5ef814…——并注明内容属于实测观察、源码核实、推断还是提议，同时给出验收关卡，而不是一份只能照抄的顺利路径。

如果这本手册帮你解决了实际问题，就 去 GitHub 点个 star。这个信号能帮下一位智能体开发者找到有源可查的答案，而不是又一份未经核实的命令清单。如果某条说法和你实际运行的版本不一致，就 提交一份证据报告，写清确切的 DSH 版本和第一个出错的边界。

浏览可视化实战指南 · 探索 Awesome 资源地图 · 下载它的 JSON 索引 · 阅读 Show & Tell · 帮忙校验索引 · 申请一份有源可查的操作手册 · 订阅新指南 · 阅读更新日志

DeepSeek Harness 不只是模型封装。它是可组合的智能体运行时，通过插件图把模型服务商、工具、审批、沙箱、持久会话、子代理和用户界面连接起来。这本独立手册从构建和运维智能体的视角出发，讲解这些系统。

项目由 SandBase 维护，不是 DeepSeek AI 的官方项目。

[!IMPORTANT]
DeepSeek Harness 处于开发者预览阶段，可能引入破坏兼容性的改动。本手册每页都注明验证日期，并链接到一手来源。部署时请固定修订版本。

本仓库是文档，不是 DeepSeek Harness 插件。 不要运行 dsh plugin add github:sandbaseai/deepseek-harness-handbook；手册没有 dsh.bundle 激活契约。请从 GitHub 或可视化实战站点阅读指南。

从你的目标开始

挑一条最贴合当前任务的最短路径。完整任务索引仍在下方，不占用仓库首屏。

| 目标 | 最快的有用路径 |
| 首次安装或运行 DeepSeek Harness | 五分钟快速上手 |
| 修改启动命令后 UI 看起来被重置 | 安装标识与 DSH_HOME 指南 |
| npx 安装成功，但 dsh web 占满 CPU 却不监听端口 | 安装后的 Web 启动边界 |
| Python SDK 中 ACP 内联图片失败 | ACP 内联图片契约 |
| Web 渲染器丢掉正文里的美元符号 | 字面美元符号渲染 |
| 准备插件清单时每个请求都失败 | 请求扩展边界 |
| 运行中的回合里被接受的后续请求始终不启动 | 排队后续请求的唤醒闩锁恢复 |
| 重命名工作区后工具和沙箱根目录失效 | 恢复过期的会话 cwd |
| 在不替换 Host 的前提下评估 Codex 风格的 Web 客户端 | 客户端扩展边界 |
| OpenRouter 因在途预算上限拒绝并发请求 | 重试服务商认证的冷却 |
| 恢复的 Agent 间歇性丢失已注册的工具 | 恢复后的工具视图边界 |
| 安全评估嵌套的后续会话 | 嵌套后续评估 |
| 并发写入或恢复时会话损坏 | 会话写入完整性不变量 |
| 会话冷启动主要耗时在 zstd 帧上 | 会话分帧性能 |
| 诊断失败的安装 | 交互式安装诊断 |
| 定位 Agent、模型、工具、会话或 UI 故障 | 交互式故障路由 |
| 查看哪些已交付、哪些是推断、哪些是提案 | 当前领域状态 |
| 配置模型、网关、图片路由或推理级别 | 模型服务商指南 |
| 构建并打包插件 | 第一个插件实验 |
| 连接 MCP 工具 | MCP 集成指南 |
| 把 SandBase Harness 接入为真正的 MCP 运行时 | SandBase Harness 桥接指南 |
| 理解会话、技能与长期记忆 | 记忆架构 |
| 审计权限、凭据或社区插件 | 安全指南 |

浏览完整的任务索引

当前所有任务路径

| 我想…… | 从这里开始 |
| 搞清楚为什么 ask_user_question 在我回答之前就中止了 | ask_user_question 中止与截止时间指南 |
| 阻止智能体在未知的 edit 和 str_replace_editor 调用之间来回切换 | 未知编辑工具装配诊断 |
| 打开被过长的插件导航裁掉的设置分区 | 设置导航溢出修复 |
| 整理会话，又不把侧边栏标签变成文件系统根目录 | 会话集合与无工作区设计 |
| 设计两个真实会话面板，又不混淆数据与交互身份 | 多会话呈现契约 |
| 自定义 Web UI，又不去改 npx 安装目录里的文件 | 持久客户端插件指南 |
| 为 monorepo 之外开发的插件生成严格的 Typert 产物 | 树外 Typert 生成指南 |
| 诊断手动 /compact 以 DeepSeek request aborted by caller 结束的问题 | 手动压缩取消操作手册 |
| 修复插件更新时的 ERR_PNPM_UNEXPECTED_STORE | pnpm 存储身份恢复 |
| 修复 AbortSignal.any is not a function，即使 Node 看起来是新版本 | 运行时身份与离线恢复操作手册 |
| 在 pnpm 源码检出中恢复卡在 Loading plugins 的 Web | pnpm 符号链接启动指南 |
| 区分 Responses API 全历史流量、重试尝试与 SSE 泄漏 | Responses 过载操作手册 |
| 运行受支持的 Codex 钩子，又不假设策略完全一致 | Codex 钩子桥接指南 |
| 安装 Claude Code 钩子桥接，同时不重复运行时 | 钩子桥接安装指南 |
| 第二个核心包副本导致每次工具调用都失败时如何恢复 | 重复核心运行时恢复 |
| 为无头嵌入设计会话、模型、JSON 与退出语义 | 程序化无头契约 |
| 在气隙环境中构建 rc.8，同时不丢失来源信息 | 气隙源码构建指南 |
| 解读 token 估算，或在压缩后恢复 messageTokens 下溢 | token 计量与投影恢复 |
| 恢复 Host 服务商或作用域工具中的预设冲突 | 预设生成与注册表归属恢复 |
| 恢复 Web 输入框中的原始拼音、假名或谚文 | Web 输入法组合运行手册 |
| 保护 API 密钥，防备份、同 UID 工具或不可信智能体窃取 | 凭据存储威胁模型 |
| 恢复已提交事件序列重复的会话 | 重复已提交 seq 运行手册 |
| 恢复发送图片后卡在只读状态的 Web 输入框 | 图片发送准入运行手册 |
| 为无头一次性运行设置并验证推理强度 | 无头推理强度指南 |
| 修复丢失推理强度的 spawn 委派 | spawn 子代理路由保真运行手册 |
| 配置 Bailian Token Plan，同时不丢失推理或模型元数据 | Bailian 目录路由运行手册 |
| 修复静默发送 /messages 的自定义 OpenAI 兼容服务商 | 自定义服务商目录冲突运行手册 |
| 恢复反复返回 Unknown or expired MCP session 的工具 | 过期 MCP 会话循环运行手册 |
| 了解随附的命令行、自动化一项任务，或评估社区 TUI | DeepSeek Harness 命令行地图 |
| Windows 文件夹选择器崩溃或截断 Unicode 路径时如何恢复 | Windows 文件夹选择器崩溃与截断指南 |
| 通过授权代理或企业 CA 连接 DeepSeek | 服务商出口与 TLS 指南 |
| 聊天走自定义网关时，修复 Web Search 认证 | 自定义网关 Web Search 操作手册 |
| 添加 MCP 服务器，或诊断 MCP 工具缺失 | MCP 预设与连接指南 |
| 在编辑器里把 DeepSeek Harness 当作 ACP External Agent 评估 | ACP 编辑器集成边界 |
| 修复或渲染 ACP 权限请求，避免卡住整轮对话 | ACP 权限客户端契约 |
| 迁移 Codex 或 Claude Code 记忆，同时不丢失来源信息与隔离性 | 会话、技能与长期记忆 |
| 并发运行 Web、headless、ACP 或 SDK 进程，且不共享可写的会话根目录 | 单写入者会话拓扑 |
| 移动或重命名工作区后，修复 spawn bash ENOENT | 工作区移动恢复操作手册 |
| 升级到精确的运行时版本，并保留验证过的回滚方案 | 升级与回滚指南 |
| 检测社区插件何时替换了核心 Agent 服务商 | 组合差异插件审计 |
| 选择精确、可复现的安装拓扑 | 安全安装 DeepSeek Harness |
| 诊断 npx 停在 DeepSeek Harness 安装提示符 | npx 安装边界操作手册 |
| 创建、调用并调试可复用的技能 | DeepSeek Harness 技能实验室 |
| 诊断 AGENTS.md 已加载却没能约束某个动作 | AGENTS.md 作用域、可见性与执行映射 |
| 构建、测试、打包并安装你的第一个插件 | 第一个 DeepSeek Harness 插件实验 |
| 让第三方执行工具渲染出正确的代码语言 | 由工具掌管代码卡片语言的设计 |
| 避免插件子进程卡死 Agent Host | 异步子进程工具指南 |
| 归档或删除旧会话，又不破坏持久历史 | 会话归档、回收站与删除指南 |
| 修复原生 read_image 因缺少 fs 注入而失败 | read_image 服务作用域指南 |
| 修复合法 WebP 图片被 pi-ai 后端拒绝 | 图片媒体类型兼容性指南 |
| 让 SDK 嵌入层回答智能体的提问与审批 | SDK 人机交互通信指南 |
| 在 DSH Web UI 中发现并管理社区插件 | DSH Plugin Store（GitHub） |
| 修复插件启动崩溃：缺少 @deepseek-ai/dsh-client-schema-form | 插件分发闭包排障手册 |
| 修复 additionalProperties、type-array 或 oneOf 工具 schema 报错 | 工具 schema 子集指南 |
| 区分官方智能体运行时与同名 API 封装 | 官方 DeepSeek Harness 身份指南 |
| 查看 rc.7 基线情况与 alpha.1 迁移背景 | DeepSeek Harness 现场状态 |
| 记录实际运行的包版本与源码修订 | DeepSeek Harness 版本证据 |
| 找到第一个出问题的运行时边界 | 交互式故障路由 |
| 把常用命令与检查项收在一个标签页里 | DeepSeek Harness 速查表 |
| 挑对官方可运行示例 | 官方示例地图 |
| 搞清 DeepSeek Harness 到底是什么 | DeepSeek Harness 详解 |
| 在 DeepSeek Harness、Claude Code 和 Codex 之间做选择 | 有来源支撑的控制平面比较 |
| 读取会话日志时不想丢掉压缩过的助手输出 | 会话日志存储格式对照 |
| 无效 overlay 导致配置档无法启动时怎么恢复 | 无效 overlay 恢复操作手册 |
| 安全运行 Web UI | 五分钟快速上手 |
| 从 Python 调用 | Python SDK 快速上手 |
| 在自动化或 CI 里跑单个任务 | 命令行与无头智能体指南 |

| Configure DeepSeek, a custom provider, or an image-capable model missing its UI modality control | Model provider guide |
| Track the rc.2 Files-backed image-input release | Release and migration note |
| Prove DeepSeek chat and Web search cannot create unexpected charges | DeepSeek API cost-boundary runbook |
| Fix a context-window or token-budget error | Classify and recover context overflow |
| Understand why one model switch affects future Agents | Map session and deployment model state |
| Fix a plugin script corrupted around a dollar sign | Repair tapIndex replacement-string insertion |
| Fix an OpenAI-compatible gateway that rejects developer | Diagnose system-message role compatibility |
| Fix CJK commands that stall persistent Bash for 300 seconds | Separate the locale/readline trap from PTY corruption |
| Fix plugin installation blocked by ERR_PNPM_ADDING_TO_ROOT | Make the profile workspace target explicit |
| Fix rc.8 source builds when Node parses an ELF, shell, or Windows pnpm entrypoint | Cross-platform pnpm entrypoint runbook |
| Stop black console windows flashing during Windows tool calls | Two-path Windows process-creation runbook |
| Find the corrupt package.json behind a pathless boot SyntaxError | Package-closure recovery runbook |
| Fix an OpenAI-compatible server_error that never retries | pi-ai classification and retry evidence |
| Recover an old Session that throws received an update before its start Match | Conversation projection recovery |
| Recover when pnpm leaves a plugin package behind but DSH skips reconciliation | Partial plugin install recovery |
| allowBuilds blocks an rc.8 registry plugin install | Review pnpm's approval gate |
| Recover when a Node 24 + tsx build exits 0 but creates no artifacts | Silent source-build recovery |
| Fix unknown or malformed prompt variables such as {{hexagon}} or {{dotted.state.path}} in tools:sdk | Code Mode literal-section boundary |
| Fix npm ETARGET for dsh-agent-loop@^0.1.0-rc.8 | Registry and cache recovery |
| Session title stays on the first-prompt fallback with a reasoning model | Auxiliary title budget diagnosis |
| Generate exact installation evidence commands for my OS and install path | Interactive Install Doctor |
| Recover an empty sidebar, unreadable Session, or false “no more history” state without destroying evidence | Route storage, sequence, identity, projection, and read-state failures |
| Stop repeated narration, tool calls, or Agent turns before they exhaust a budget | Event-shaped runaway Agent runbook |
| Stop a compacted long Session from exhausting or blocking the Web Host during cold restore | Session heap and restore operator guide |
| Detect repeated model text inside one streaming attempt | Degenerate-output guard guide |
| Stop a foreground tool after session.cancel is accepted but work remains live | Stuck-tool cancellation runbook |
| Recover when every turn in one Session returns invalid JSON | Poisoned Session recovery guide |
| Recover when every retry reports insufficient tool messages | Missing tool-result recovery guide |
| Fix a todo that stays in progress after the final answer | Todo state and projection guide |
| Fix a Code Mode Skill that appears in UI but not model context | Code Mode Skill context guide |
| Fix terminal inspection is unsupported on platform win32 in Minimal | Windows Minimal preset Bash guide |
| Diagnose a frozen first workspace-write call on Windows | Windows first ACL grant guide |
| Run DeepSeek Harness from source on a Synology NAS | Synology NAS deployment guide |
| Recover when the Agent waits but no question or approval card appears | Missing interaction card guide |
| Diagnose Output token limit reached without confusing it with context overflow | Output token ceiling guide |
| Recover when a Git plugin installs without its declared dist/ or lib/ export | Missing plugin artifact guide |
| Fix /compact when its summary reaches the token cap | Compaction summary truncation guide |
| Decide which plugin missing peer and ignored-build warnings require action | Plugin peer-warning guide |
| Keep answers in Chinese or another language and diagnose an English Think row | Response and reasoning language guide |
| Recover a long prompt after Web clears it but the turn fails | Accepted-before-durable prompt recovery |
| Fix empty streamed tool identity before it causes UNKNOWN_TOOL, replay 400s, or a corrupt Session resume | Streamed tool-call identity guide |
| Explain slow first-token latency before blaming the provider | Mature Session TTFT guide |
| Fix ReplaceFileW EACCES while editing a Windows profile | Windows HMR-watched config recovery |
| Decide whether worker-thread Code Mode fits the security boundary | Code Mode trust-boundary guide |
| Fix Web, headless, or custom-profile startup reporting --expose-internals is required | HMR loader-capability diagnosis |
| Fix a pnpm global install that reports an installed plugin as missing | Global native-binding resolution guide |
| Fix macOS workspace selection when the path ends in :/ | macOS native picker path guide |
| Keep one incompatible custom-event Session from blocking global search | Custom Session event compatibility |
| Connect external MCP tools | MCP integration guide |
| Design multi-tenant MCP across ACP | Session-scoped MCP architecture |
| Add reusable Agent instructions | Skills guide |
| Evaluate an optional bounded recovery round in Ralph | Ralph failure-successor design guide |
| Delegate work to child Agents | Subagents guide |
| Inspect or cancel one stale pending continuable-subagent follow-up | Subagent inbox control map |
| Let a subagent request human clarification safely | Parent-owned question relay |
| Understand the runtime | The agent-runtime mental model |
| Understand one complete turn | Agent Loop and Session Events |
| Choose between Session persistence and long-term memory | Sessions are not long-term memory |
| Understand approval, guards, and tool effects | Tool execution pipeline |
| Build an Agent rather than a loose collection of tools | Agent design map |
| Research a repository without publishing changes | Repository Research Agent recipe |
| Run or debug DeepSeek Harness on Windows | Windows compatibility and ACL boundary guide |
| Recover partial multi-agent work after unknown job | Subagent ID routing and recovery |
| Recover a profile after a plugin change | Plugin install and recovery guide |
| Diagnose an ERR_HTTP2_INVALID_SESSION crash | HTTP/2 provider-transport troubleshooting |
| Fix remote Settings unavailable, crypto.randomUUID, or Host/Origin 403 safely | Remote Web control-plane guide |
| Fix persistent Bash on NixOS or minimal Linux | PTY shell-path guide |
| Protect or recover a session log | Live session log durability |
| Fix first Session flush when the filesystem rejects hard links | Session hard-link compatibility runbook |
| Fix a failing installation or run | Troubleshooting index |
| Track upstream changes | Updates and breaking changes |

The agent-first mental model

flowchart LR
U[User goal] --> A[Agent contract]
A --> C[Profile + Bundles + Patches]
C --> G[Cordis plugin graph]
G --> L[Agent Loop]
L --> M[Model provider]
L --> T[Tools + policy + approval + sandbox]
L --> S[Durable Session events]
S --> L
S --> H[Web, headless, SDK, clients]

An agent is not just a prompt. A useful Agent has a task boundary, allowed effects, completion condition, model route, tool surface, permission policy, session strategy, failure behavior, and an operator-visible result. DeepSeek Harness supplies the runtime vocabulary for assembling those responsibilities without forcing every product into one fixed loop or interface.

What makes this handbook different

- Agent-first: concepts are organized around building, running, and debugging Agents.
- Source-backed: version-sensitive claims link to official documentation or source.
- Operational: every tutorial includes success evidence, failure branches, and safety boundaries.
- Visual: architecture pages prioritize diagrams over walls of text.
- Living: updates, breaking changes, and troubleshooting pages follow upstream development.
- Multilingual by design: English is canonical; translations declare their source revision and review status. Current depth is reported explicitly.

Language coverage

| Locale | Current status | Published coverage |
| English | Canonical | 173 pages |
| 简体中文 | Draft refresh | Reviewed core guides plus a machine-assisted current navigation awaiting fluent review |
| 日本語 | Draft | Navigation plus ecosystem resource map |
| 한국어 | Draft | Navigation plus ecosystem resource map |
| Español | Draft | Navigation plus ecosystem resource map |

The locale links at the top do not imply feature parity. English remains the source of truth until a translation points to the current canonical revision and has been reviewed by a fluent contributor.

Published guide map

Every item below is available now. Planned coverage lives in the public roadmap.

Getting started

- Diagnose manual compaction aborted by its caller signal
- Preserve embedded code through literal file tools
- Fix pnpm store drift during plugin update
- Diagnose npx hanging before DeepSeek Harness starts
- What is DeepSeek Harness?
- DeepSeek Harness vs Claude Code vs Codex
- Install DeepSeek Harness safely
- Upgrade and roll back safely
- Five-minute Web UI quickstart
- Python SDK quickstart
- Headless Agent and CI
- Configure model providers

Architecture

- The agent-runtime mental model
- Session log storage format and packed rows
- Agent Loop and Session Events
- Sessions are not long-term memory
- Tool execution pipeline

Agent patterns

- Designing an Agent
- AGENTS.md scope and precedence
- Skills: discovery, precedence, and invocation
- Subagents: providers, delegation, and continuation

Recipes

- Repository Research Agent

Operations

- Keep concurrent Session roots single-writer

Official examples

- Choose the right upstream example
- Headless CLI task runner
- Python SDK and JSON-RPC runtime
- ACP automation server
- MCP memory overlays
- Self-modifying Cordis composition
- Session-local schedules

Integrations

- Connect MCP servers
- Host stdio-only ACP for multiple tenants
- Evaluate the ACP editor-integration boundary
- Render ACP permission requests safely
- Recover a silent Node 24 and tsx source build
- Fix clustered MISSING_EXPORT failures after a source revision change
- Stop and safely retry a stuck Turn
- Fix double-brace tool text breaking Code Mode prompt assembly
- Fix npm ETARGET while installing rc.8
- Fix missing dsh-client-schema-form after npm installation
- Fix Session titles that stay on the fallback with reasoning models
- Generate an installation evidence plan with Install Doctor

Plugin development

- Stop Goal rounds while owned subagents are still running
- Render a tool-produced image in its Web result card
- Design general files and provider-native PDF/video passthrough
- Pin OpenRouter providers without arbitrary request-body passthrough
- Build your first DeepSeek Harness plugin
- Run subprocesses safely inside tools
- Fix read_image missing its filesystem injection
- Fix pi-ai image MIME rejection on OpenAI-compatible backends
- Design SDK server-to-client questions and approvals
- Archive, trash, and delete Sessions safely
- Author tool schemas for the enforced subset
- Custom durable Session event compatibility

Security

- Threat-model API key storage and choose a stronger credential boundary
- Audit community plugins before installation
- Code Mode worker-thread trust boundary
- Prevent unexpected DeepSeek API charges

Searchable operations

- Verify the official DeepSeek Harness project
- DeepSeek Harness Field Status: rc.7 baseline + alpha.1 context
- DeepSeek Harness Version Evidence
- Interactive Failure Router
- DeepSeek Harness cheat sheet
- Troubleshooting index
- Add an MCP server and diagnose missing tools
- ERR_HTTP2_INVALID_SESSION provider-transport crashes
- Sandbox denial versus sandbox unavailable
- Windows compatibility and troubleshooting
- Minimal preset Bash failure on native Windows
- First Windows workspace-write freeze
- Synology NAS source deployment
- Missing question or approval card after reconnect
- Output token limit reached
- Git plugin missing its built export
- Compaction summary truncated at the token cap
- Plugin peer-dependency and ignored-build warnings
- Response and reasoning language control
- Fix reasoning_content replay across providers and thinking modes
- Prompt accepted before it became durable
- Windows folder-picker worker crash
- DeepSeek API fetch failures behind a proxy or enterprise CA
- Fix Web Search authentication on a custom gateway
- Configure Bailian Token Plan without losing catalog compatibility
- Recover duplicated committed Session sequence numbers
- Recover a composer stuck read-only after an image send
- Set and verify reasoning effort for headless runs
- Fix spawn subagents that drop reasoning effort
- Fix unknown job after a background subagent run
- Recover an expired MCP session without a repeated tool-call loop
- Plugin installation and known-good recovery
- Resume historical code Sessions after the preset became ptc
- Remote Web access, SSH, HTTPS, and trust
- Route OpenCode Go models by protocol and entitlement
- Recover Web from a Client plugin boot failure
- Design shared dependency caches as explicit workspace-write capabilities
- PTY shell path on NixOS and minimal Linux
- Protect and recover live session logs
- Recover spawn bash ENOENT after a workspace moves
- Classify and recover context overflow
- Stop a runaway Agent loop and contain spend
- Detect and recover from degenerate repeated model output
- Stop a tool that will not cancel
- Recover a Session poisoned by invalid tool-call JSON
- Contain empty streamed tool identity before it poisons Session replay and resume
- Diagnose slow TTFT in mature Sessions
- Fix ReplaceFileW EACCES on Windows HMR-watched config
- Treat worker-thread Code Mode as host-trusted
- Fix --expose-internals HMR startup from a source checkout
- Fix pnpm global native-binding plugin resolution
- Fix macOS workspace picker trailing-colon paths
- Persist custom plugin events without breaking Session resume
- Updates and breaking changes

Repository structure

docs/<locale>/
getting-started/ installation and first runs
architecture/ runtime and lifecycle explanations
agent-patterns/ design decisions for real agents
recipes/ reproducible agent builds
troubleshooting/ symptom-driven diagnostic pages
ecosystem/ plugins, tools, skills, and comparisons
updates/ upstream change coverage
scripts/ content and translation verification
content-manifest.json canonical revision and locale status

Editorial and commercial boundary

DeepSeek Harness remains the subject of every technical page. SandBase maintains the handbook and may provide a restrained link to related Agent, model, Skill, or MCP discovery resources. A mention is never presented as an official DeepSeek recommendation, a compatibility guarantee, or a security endorsement.

Contributing

Corrections, reproducible examples, diagrams, troubleshooting cases, upstream change notes, and fluent translation reviews are welcome. Read CONTRIBUTING.md, follow the Code of Conduct, and run npm run check before submitting a pull request.

New here? Choose a scoped task from the public roadmap, open a documentation request, or use the support router to find the correct project. Reproducible evidence is more valuable than a large patch.

Two current evidence units are intentionally small: review five Simplified Chinese navigation summaries, or validate one cold-restart Session recovery row. Both issues define the privacy boundary and observable acceptance evidence.

Primary sources

- DeepSeek Harness official repository
- Official architecture documentation
- Official Agent lifecycle
- Official capability seams
- Official tool execution pipeline
- Official user guides

License

Apache-2.0. See LICENSE.