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

DeepSeek Harness 手册

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

GitHub stars Latest release Content check License: Apache-2.0

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

DeepSeek Harness 手册 — 基于源码的操作指南、安装诊断和故障路由器

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

如果本手册帮你省下了一轮调试，请为仓库加星。这一信号能帮助更多智能体构建者找到基于源码的 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，以及操作者可见的故障恢复。对版本敏感的页面会标明其所校验的源码修订版本。

选择一条路径，快速获取证据：

| 运行 | 评估 | 调试或构建 |
|---|---|---|
| 五分钟快速入门 | Agent Harness 评分卡 | 交互式故障路由器 |
| CLI 与无头模式地图 | Agent 运行时地图 | 配置修复与重置 |
| API 成本边界 | 当前领域状态 | MCP 指南 |

探索 Agent 生态系统

精选的 Awesome 资源地图 现已涵盖 79 个附有来源链接的起点，包括检查点/回退、侧边 Session、子 Agent 可见性、浏览器与 Office 界面、插件发现与健康检查、数据库分析、对抗性工作流审查、Agent 演化、移动端访问以及提供商回退控制。每个条目都是面向 Agent 的发现线索，而非兼容性或安全性背书；安装前请检查权限、凭据和回滚路径。

关于规模背景，置顶的 上游目录快照 包含 271 个枢纽仓库、1,000 个公开的 dsh-plugin 主题仓库以及 471 个手动添加项。本手册刻意精选了一个更小、附有来源链接的子集，以便每个条目都有明确的 Agent 边界可供检查。

关于中文同行讨论，请参阅上游社区的 飞书群讨论 以获取当前邀请和背景信息。该讨论由社区运营，并非 DeepSeek 官方支持；请勿分享凭据、私人 Session 日志或敏感工作区数据。

新近来源验证

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

如果本手册解决了一个真实问题，请在 GitHub 上为其加星。这一信号能帮助下一位 Agent 构建者找到有源可依的答案，而不是又一份未经核实的命令清单。如果某项说法与你实际运行的运行时不同，请提交证据报告，并附上确切的 DSH 版本和首个失败边界。

浏览可视化现场指南 · 探索 Awesome 资源地图 · 下载其 JSON 索引 · 阅读 Show & Tell · 帮助验证索引 · 请求有源可依的运行手册 · 订阅新指南 · 阅读变更日志

DeepSeek Harness 不仅仅是模型封装。它是一个可组合的 agent 运行时，通过插件图将模型提供方、工具、审批、沙箱、持久会话、子 agent 和用户界面连接起来。这本独立手册从构建和运营 agent 的人员视角解释这些系统。

本项目由 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 启动边界 |
| ACP 内联图片在 Python SDK 中失败 | ACP 内联图片契约 |
| Web 渲染器从正文中丢弃美元符号 | 字面美元符号渲染 |
| 在插件清单准备期间每个请求都失败 | 请求扩展边界 |
| 在运行中的回合内被接受的后续请求永远不会启动 | 排队后续请求唤醒锁存恢复 |
| 重命名工作区会破坏工具和沙箱根目录 | 恢复过期的会话 cwd |
| 在不替换 Host 的情况下评估 Codex 风格的 Web 客户端 | 客户端扩展边界 |
| OpenRouter 因在途预算上限而拒绝并发请求 | 重试提供商证实的冷却 |
| 恢复的 Agent 间歇性丢失已注册的工具 | 恢复的工具视图边界 |
| 安全地评估嵌套后续 Session | 嵌套后续评估 |
| 在并发写入者或恢复下 Session 损坏 | 会话写入完整性不变量 |
| 会话冷打开主要受 zstd 帧影响 | 会话帧性能 |
| 诊断失败的安装 | 交互式安装诊断器 |
| 路由 Agent、模型、工具、Session 或 UI 故障 | 交互式故障路由器 |
| 查看哪些已发布、推断或提议 | 当前字段状态 |
| 配置模型、网关、图片路由或推理级别 | 模型提供商指南 |
| 构建并打包插件 | 第一个插件实验 |
| 连接 MCP 工具 | MCP 集成指南 |
| 将 SandBase Harness 连接为真实的 MCP 运行时 | SandBase Harness 桥接指南 |
| 理解会话、技能与长期记忆 | 记忆架构 |
| 审计权限、凭据或社区插件 | 安全指南 |

浏览完整的任务专属索引

所有当前任务路径

| 我想要… | 从这里开始 |
|---|---|
| 解释为什么 ask_user_question 在我回答之前就中止了 | ask_user_question 中止与截止时间指南 |
| 阻止 Agent 在未知的 edit 和 str_replace_editor 调用之间来回切换 | 未知编辑工具装配诊断 |
| 在冗长的插件导航下方访问被裁剪的设置分区 | 设置导航溢出修复 |
| 在不把侧边栏标签变成文件系统根目录的情况下组织会话 | 会话集合与无工作区设计 |
| 在不混淆数据或交互身份的情况下设计两个真实的会话窗格 | 多会话呈现契约 |
| 在不修改 npx 安装内部文件的情况下自定义 Web UI | 持久化客户端插件指南 |
| 为在 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 hooks 桥接 | Hooks 桥接安装指南 |
| 当第二个核心包副本破坏所有工具调用时进行恢复 | 重复核心运行时恢复 |
| 为无头嵌入设计会话、模型、JSON 和退出语义 | 编程式无头契约 |
| 在气隙环境中构建 rc.8 而不丢失来源信息 | 气隙源码构建指南 |
| 解读 token 估算或在压缩后恢复 messageTokens 下溢 | Token 核算与投影恢复 |
| 恢复 Host 提供程序或作用域工具中的预设冲突 | 预设生成与注册表所有权恢复 |
| 在 Web 编辑器中恢复原始拼音、假名或谚文 | Web IME 组合输入运行手册 |
| 保护 API 密钥免受备份、同 UID 工具或不受信任的 Agent 侵害 | 凭据存储威胁模型 |
| 恢复已提交事件序列重复的 Session | 重复已提交 seq 运行手册 |
| 恢复发送图片后卡在只读状态的 Web 编辑器 | 图片发送准入运行手册 |
| 为无头一次性运行设置并验证推理强度 | 无头推理强度指南 |
| 修复丢失推理强度的 spawn 委托 | Spawn 子代理路由保真运行手册 |
| 配置百炼 Token Plan 而不丢失推理或模型元数据 | 百炼目录路由运行手册 |
| 修复静默发送 /messages 的自定义 OpenAI 兼容提供程序 | 自定义提供程序目录冲突运行手册 |
| 恢复反复返回 Unknown or expired MCP session 的工具 | 过期 MCP 会话循环运行手册 |
| 了解已发布的 CLI、自动化一项任务，或评估一个社区 TUI | DeepSeek Harness CLI 地图 |
| 当 Windows 文件夹选择器崩溃或截断 Unicode 路径时进行恢复 | Windows 文件夹选择器崩溃与截断指南 |
| 通过授权代理或企业 CA 连接到 DeepSeek | 提供商出口与 TLS 指南 |
| 当聊天使用自定义网关时修复 Web Search 身份验证 | 自定义网关 Web Search 运行手册 |
| 添加 MCP 服务器或诊断缺失的 MCP 工具 | MCP 预设与连接指南 |
| 在编辑器中评估 DeepSeek Harness 作为 ACP 外部代理 | ACP 编辑器集成边界 |
| 修复或渲染 ACP 权限请求而不挂起该轮次 | ACP 权限客户端契约 |
| 迁移 Codex 或 Claude Code 记忆而不丢失来源或隔离性 | 会话、技能与长期记忆 |
| 并发运行 Web、无头、ACP 或 SDK 进程而不共享可写 Session 根目录 | 单写入者 Session 拓扑 |
| 在移动或重命名工作区后修复 spawn bash ENOENT | 已移动工作区恢复运行手册 |
| 升级精确运行时并保留经过验证的回滚 | 升级与回滚指南 |
| 检测社区插件何时替换核心 Agent 提供商 | 组合差异插件审计 |
| 选择精确、可复现的安装拓扑 | 安全安装 DeepSeek Harness |
| 诊断 npx 在 DeepSeek Harness 安装提示处等待 | npx 安装边界运行手册 |
| 创建、调用并调试可复用的 Skill | DeepSeek Harness Skills 实验室 |
| 诊断为什么 AGENTS.md 已加载但未能约束某个操作 | AGENTS.md 作用域、可见性与强制执行映射 |
| 构建、测试、打包并安装我的第一个插件 | 第一个 DeepSeek Harness 插件实验 |
| 让第三方执行工具渲染正确的代码语言 | 工具自有的代码卡片语言设计 |
| 防止插件子进程冻结 Agent Host | 异步子进程工具指南 |
| 归档或删除旧 Session 而不破坏持久历史记录 | Session 归档、回收站与删除指南 |
| 修复原生 read_image 因缺少 fs 注入而失败的问题 | read_image 服务作用域指南 |
| 修复有效的 WebP 图像被 pi-ai 后端拒绝的问题 | 图像媒体类型兼容性指南 |
| 让 SDK 嵌入方回答 Agent 问题和审批 | SDK 人机交互通信指南 |
| 从 DSH Web UI 发现并管理社区插件 | DSH Plugin Store（GitHub） |
| 修复因缺少 @deepseek-ai/dsh-client-schema-form 导致的插件启动崩溃 | 插件分发闭包运行手册 |
| 修复 additionalProperties、类型数组或 oneOf 工具 schema 错误 | 工具 schema 子集指南 |
| 区分官方 Agent 运行时与同名 API 封装 | 官方 DeepSeek Harness 身份指南 |
| 检查 rc.7 基线与 alpha.1 迁移背景 | DeepSeek Harness 现场状态 |
| 捕获实际运行的包和源码修订版本 | DeepSeek Harness 版本证据 |
| 找到第一个损坏的运行时边界 | 交互式故障路由器 |
| 将必要命令和检查集中在一个标签页中 | DeepSeek Harness 速查表 |
| 选择正确的官方可运行示例 | 官方示例地图 |
| 了解 DeepSeek Harness 究竟是什么 | DeepSeek Harness 详解 |
| 在 DeepSeek Harness、Claude Code 和 Codex 之间做选择 | 有来源支撑的控制平面比较 |
| 在不丢失打包的助手输出的情况下读取 Session 日志 | Session 日志存储格式对照 |
| 当无效 overlay 导致 profile 无法启动时进行恢复 | 无效 overlay 恢复操作手册 |
| 安全地运行 Web UI | 五分钟快速上手 |
| 从 Python 中使用它 | Python SDK 快速上手 |
| 在自动化或 CI 中运行单个任务 | CLI 与 Headless Agent 指南 |
| 配置 DeepSeek、自定义 provider，或缺少 UI 模态控制的图像能力模型 | 模型 provider 指南 |
| 跟踪 rc.2 基于 Files 的图像输入版本 | 发布与迁移说明 |
| 证明 DeepSeek 聊天和 Web 搜索不会产生意外费用 | DeepSeek API 成本边界操作手册 |
| 修复上下文窗口或 token 预算错误 | 对上下文溢出进行分类与恢复 |
| 理解为什么一次模型切换会影响未来的 Agent | 梳理 session 与部署模型状态 |
| 修复因美元符号而损坏的插件脚本 | 修复 tapIndex 替换字符串插入问题 |
| 修复拒绝 developer 的 OpenAI 兼容网关 | 诊断 system 消息角色兼容性 |
| 修复导致持久 Bash 停滞 300 秒的 CJK 命令 | 将 locale/readline 陷阱与 PTY 损坏区分开 |
| 修复被 ERR_PNPM_ADDING_TO_ROOT 阻止的插件安装 | 明确 profile 工作区目标 |
| 修复 rc.8 源码构建中 Node 解析 ELF、shell 或 Windows pnpm 入口点的问题 | 跨平台 pnpm 入口点操作手册 |
| 在 Windows 工具调用期间阻止黑色控制台窗口闪现 | 双路径 Windows 进程创建操作手册 |
| 找出无路径启动 SyntaxError 背后损坏的 package.json | 包闭包恢复操作手册 |
| 修复一个从不重试的 OpenAI 兼容 server_error | pi-ai 分类与重试证据 |
| 恢复一个抛出 received an update before its start Match 的旧 Session | 对话投影恢复 |
| 当 pnpm 遗留一个插件包但 DSH 跳过协调时进行恢复 | 部分插件安装恢复 |
| allowBuilds 阻止 rc.8 注册表插件安装 | 审查 pnpm 的批准门禁 |
| 当 Node 24 + tsx 构建以 0 退出但未创建任何产物时进行恢复 | 静默源码构建恢复 |
| 修复 tools:sdk 中未知或格式错误的提示变量，例如 {{hexagon}} 或 {{dotted.state.path}} | Code Mode 字面量区段边界 |
| 修复 dsh-agent-loop@^0.1.0-rc.8 的 npm ETARGET | 注册表与缓存恢复 |
| 使用推理模型时，Session 标题停留在首个提示词回退值 | 辅助标题预算诊断 |
| 为我的操作系统和安装路径生成精确的安装证据命令 | 交互式安装诊断 |
| 在不破坏证据的情况下恢复空白侧边栏、无法读取的 Session 或虚假的“没有更多历史记录”状态 | 路由存储、序列、身份、投影和读取状态故障 |
| 在重复叙述、工具调用或 Agent 轮次耗尽预算之前将其停止 | 事件形态的失控 Agent 操作手册 |
| 阻止已压缩的长 Session 在冷恢复期间耗尽或阻塞 Web Host | Session 堆内存与恢复操作员指南 |
| 检测单次流式尝试中重复的模型文本 | 退化输出防护指南 |
| 在 session.cancel 被接受但工作仍在进行后停止前台工具 | 卡住工具取消操作手册 |
| 当一个 Session 中的每一轮都返回无效 JSON 时进行恢复 | 中毒 Session 恢复指南 |
| 当每次重试都报告工具消息不足时进行恢复 | 缺失工具结果恢复指南 |
| 修复在最终答案后仍保持进行中的 todo | Todo 状态与投影指南 |
| 修复出现在 UI 中但不在模型上下文中的 Code Mode Skill | Code Mode Skill 上下文指南 |
| 修复 Minimal 中的 terminal inspection is unsupported on platform win32 | Windows Minimal 预设 Bash 指南 |
| 诊断 Windows 上首次 workspace-write 调用冻结的问题 | Windows 首次 ACL 授权指南 |
| 在 Synology NAS 上从源码运行 DeepSeek Harness | Synology NAS 部署指南 |
| 当 Agent 在等待但没有出现提问或审批卡片时进行恢复 | 缺失交互卡片指南 |
| 诊断 Output token limit reached，不要将其与上下文溢出混淆 | 输出 token 上限指南 |
| 当 Git 插件安装后缺少其声明的 dist/ 或 lib/ 导出时进行恢复 | 缺失插件产物指南 |
| 修复 /compact 在其摘要达到 token 上限时的问题 | 压缩摘要截断指南 |
| 判断哪些插件 missing peer 和忽略构建警告需要处理 | 插件 peer 警告指南 |
| 保持用中文或其他语言回答，并诊断英文 Think 行 | 响应与推理语言指南 |
| Web 清除长提示词后轮次失败时恢复它 | 持久化前已接受的提示词恢复 |
| 在空流式工具身份导致 UNKNOWN_TOOL、重放 400 错误或 Session 恢复损坏之前修复它 | 流式工具调用身份指南 |
| 在归咎于提供商之前解释首 token 延迟缓慢的原因 | 成熟 Session TTFT 指南 |
| 在编辑 Windows 配置文件时修复 ReplaceFileW EACCES | Windows HMR 监视配置恢复 |
| 判断 worker 线程 Code Mode 是否符合安全边界 | Code Mode 信任边界指南 |
| 修复 Web、无头或自定义配置文件启动时报告需要 --expose-internals 的问题 | HMR 加载器能力诊断 |
| 修复 pnpm 全局安装将已安装插件报告为缺失的问题 | 全局原生绑定解析指南 |
| 修复路径以 :/ 结尾时的 macOS 工作区选择问题 | macOS 原生选择器路径指南 |
| 避免一个不兼容的自定义事件 Session 阻塞全局搜索 | 自定义 Session 事件兼容性 |
| 连接外部 MCP 工具 | MCP 集成指南 |
| 跨 ACP 设计多租户 MCP | Session 作用域 MCP 架构 |
| 添加可复用的 Agent 指令 | Skills 指南 |
| 评估 Ralph 中可选的有界恢复轮次 | Ralph 失败后继设计指南 |
| 将工作委派给子 Agent | 子 Agent 指南 |
| 检查或取消一个陈旧的待处理可继续子 Agent 后续任务 | 子 Agent 收件箱控制图 |
| 让子 Agent 安全地请求人工澄清 | 父级拥有的问题中继 |
| 理解运行时 | Agent 运行时心智模型 |
| 理解一个完整的轮次 | Agent Loop 与 Session 事件 |
| 在 Session 持久化与长期记忆之间做选择 | Session 不是长期记忆 |
| 理解审批、防护与工具效果 | 工具执行流水线 |
| 构建一个 Agent，而不是一堆松散的工具 | Agent 设计地图 |
| 在不发布更改的情况下研究仓库 | 仓库研究 Agent 配方 |
| 在 Windows 上运行或调试 DeepSeek Harness | Windows 兼容性与 ACL 边界指南 |
| 在 unknown job 之后恢复部分多 Agent 工作 | 子 Agent ID 路由与恢复 |
| 在插件变更后恢复 profile | 插件安装与恢复指南 |
| 诊断 ERR_HTTP2_INVALID_SESSION 崩溃 | HTTP/2 提供商传输故障排查 |
| 安全修复远程 Settings 不可用、crypto.randomUUID 或 Host/Origin 403 | 远程 Web 控制平面指南 |
| 修复 NixOS 或最小化 Linux 上的持久 Bash | PTY shell 路径指南 |
| 保护或恢复会话日志 | 实时会话日志持久性 |
| 修复文件系统拒绝硬链接时的首次 Session 刷新 | 会话硬链接兼容性运行手册 |
| 修复安装或运行失败 | 故障排查索引 |
| 跟踪上游变更 | 更新与破坏性变更 |

Agent 优先的心智模型

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]

Agent 不仅仅是一个提示词。一个有用的 Agent 具有任务边界、允许的效果、完成条件、模型路由、工具表面、权限策略、会话策略、失败行为以及操作员可见的结果。DeepSeek Harness 提供了运行时词汇来组装这些职责，而不会强制每个产品进入一个固定的循环或接口。

本手册的独特之处

- Agent 优先： 概念围绕构建、运行和调试 Agent 来组织。
- 来源支撑： 对版本敏感的声明会链接到官方文档或源代码。
- 可操作： 每个教程都包含成功证据、失败分支和安全边界。
- 可视化： 架构页面优先使用图表而非大段文字。
- 持续更新： 更新、破坏性变更和故障排查页面跟随上游开发。
- 多语言设计： 英文为权威版本；译文需声明其源修订版本和审阅状态。当前深度已明确说明。

语言覆盖

| 语言区域 | 当前状态 | 已发布覆盖范围 |
|---|---|---|
| 英语 | 权威版本 | 173 页 |
| 简体中文 | 草稿刷新 | 已审阅的核心指南，加上机器辅助的当前导航，等待流利审阅 |
| 日本語 | 草稿 | 导航及生态系统资源地图 |
| 한국어 | 草稿 | 导航及生态系统资源地图 |
| Español | 草稿 | 导航及生态系统资源地图 |

顶部的语言区域链接并不意味着功能对等。在译文指向当前权威修订版本并由流利贡献者审阅之前，英文仍是唯一事实来源。

已发布指南地图

以下每一项现已可用。计划覆盖范围见公开路线图。

入门

- 诊断因调用方信号而中止的手动压缩
- 通过字面文件工具保留嵌入代码
- 修复插件更新期间的 pnpm store 漂移
- 诊断 DeepSeek Harness 启动前 npx 挂起
- 什么是 DeepSeek Harness？
- DeepSeek Harness vs Claude Code vs Codex
- 安全安装 DeepSeek Harness
- 安全升级和回滚
- 五分钟 Web UI 快速入门
- Python SDK 快速入门
- 无头 Agent 与 CI
- 配置模型提供商

架构

- Agent 运行时心智模型
- 会话日志存储格式与打包行
- Agent 循环与会话事件
- 会话不是长期记忆
- 工具执行流水线

Agent 模式

- 设计 Agent
- AGENTS.md 范围与优先级
- Skills：发现、优先级与调用
- Subagents：提供商、委托与延续

配方

- 仓库研究 Agent

运维

- 保持并发 Session 根目录单写入者

官方示例
- 选择正确的上游示例
- 无头 CLI 任务运行器
- Python SDK 与 JSON-RPC 运行时
- ACP 自动化服务器
- MCP 记忆叠加层
- 自修改的 Cordis 组合
- 会话本地调度

集成

- 连接 MCP 服务器
- 为多租户托管仅 stdio 的 ACP
- 评估 ACP 编辑器集成边界
- 安全地渲染 ACP 权限请求
- 恢复静默的 Node 24 与 tsx 源码构建
- 修复源码修订变更后集群化的 MISSING_EXPORT 失败
- 停止并安全地重试卡住的 Turn
- 修复双花括号工具文本破坏 Code Mode 提示词组装的问题
- 修复安装 rc.8 时的 npm ETARGET
- 修复 npm 安装后缺失的 dsh-client-schema-form
- 修复推理模型下 Session 标题停留在回退值的问题
- 使用 Install Doctor 生成安装证据计划

插件开发

- 在自有子代理仍在运行时停止 Goal 轮次
- 在其 Web 结果卡片中渲染工具生成的图像
- 设计通用文件与提供商原生 PDF/视频透传
- 固定 OpenRouter 提供商而不透传任意请求体
- 构建你的第一个 DeepSeek Harness 插件
- 在工具内安全地运行子进程
- 修复 read_image 缺失其文件系统注入的问题
- 修复 OpenAI 兼容后端上的 pi-ai 图像 MIME 拒绝问题
- 设计 SDK 服务器到客户端的问题与审批
- 安全地归档、移入回收站和删除 Session
- 为强制子集编写工具 schema
- 自定义持久化 Session 事件兼容性

安全

- 对 API 密钥存储进行威胁建模并选择更强的凭据边界
- 安装前审计社区插件
- Code Mode 工作线程信任边界
- 防止意外的 DeepSeek API 费用

可搜索的操作

- 验证官方 DeepSeek Harness 项目
- DeepSeek Harness 现场状态：rc.7 基线 + alpha.1 上下文
- DeepSeek Harness 版本证据
- 交互式故障路由器
- DeepSeek Harness 速查表
- 故障排查索引
- 添加 MCP 服务器并诊断缺失的工具
- ERR_HTTP2_INVALID_SESSION 提供商传输崩溃
- 沙箱拒绝与沙箱不可用
- Windows 兼容性与故障排查
- 原生 Windows 上最小预设 Bash 失败
- 首次 Windows 工作区写入冻结
- Synology NAS 源码部署
- 重新连接后缺失的问题或审批卡片
- Output token limit reached
- Git 插件缺失其构建导出
- 压缩摘要因 token 上限被截断
- 插件对等依赖与忽略构建警告
- 响应与推理语言控制
- 修复跨提供商和思考模式的 reasoning_content 重放
- 提示在持久化之前被接受
- Windows 文件夹选择器工作线程崩溃
- 代理或企业 CA 后面的 DeepSeek API 获取失败
- 修复自定义网关上的 Web Search 身份验证
- 在不丢失目录兼容性的情况下配置 Bailian Token Plan
- 恢复重复提交的 Session 序列号
- 恢复在发送图片后卡在只读状态的 composer
- 为无头运行设置并验证推理强度
- 修复 spawn 子代理丢失推理强度的问题
- 修复后台子代理运行后的 unknown job
- 在不重复工具调用循环的情况下恢复过期的 MCP 会话
- 插件安装与已知良好恢复
- 在预设变为 ptc 后恢复历史 code Session
- 远程 Web 访问、SSH、HTTPS 与信任
- 按协议和权限路由 OpenCode Go 模型
- 从 Client 插件启动失败中恢复 Web
- 将共享依赖缓存设计为显式的工作区写入能力
- NixOS 和最小化 Linux 上的 PTY shell 路径
- 保护和恢复实时会话日志
- 在工作区移动后恢复 spawn bash ENOENT
- 分类并恢复上下文溢出
- 停止失控的 Agent 循环并控制支出
- 检测并恢复退化的重复模型输出
- 停止无法取消的工具
- 恢复被无效工具调用 JSON 污染的 Session
- 在空流式工具身份污染 Session 重放和恢复之前加以遏制
- 诊断成熟 Session 中的慢 TTFT
- 修复 Windows 上 HMR 监视配置的 ReplaceFileW EACCES
- 将 worker-thread Code Mode 视为宿主可信
- 修复从源码检出运行 --expose-internals HMR 启动的问题
- 修复 pnpm 全局原生绑定插件解析
- 修复 macOS 工作区选择器尾部冒号路径
- 在不破坏 Session 恢复的前提下持久化自定义插件事件
- 更新与破坏性变更

仓库结构

docs//
getting-started/     安装与首次运行
architecture/        运行时与生命周期说明
agent-patterns/      真实代理的设计决策
recipes/             可复现的代理构建
troubleshooting/     症状驱动的诊断页面
ecosystem/           插件、工具、技能与对比
updates/             上游变更覆盖
scripts/               内容与翻译验证
content-manifest.json  规范修订版本与语言区域状态

编辑与商业边界

DeepSeek Harness 始终是每个技术页面的主题。SandBase 维护本手册，并可能提供指向相关 Agent、模型、Skill 或 MCP 发现资源的克制链接。任何提及都不会被呈现为 DeepSeek 的官方推荐、兼容性保证或安全背书。

贡献

欢迎提供更正、可复现的示例、图表、故障排查案例、上游变更说明以及流畅的翻译审校。请阅读 CONTRIBUTING.md，遵守 Code of Conduct，并在提交拉取请求前运行 npm run check。

初次参与？请从公开路线图中选择一项范围明确的任务，提交文档请求，或使用支持路由找到正确的项目。可复现的证据比大型补丁更有价值。

当前有两个证据单元刻意保持小规模：审校五条简体中文导航摘要，或验证一行冷重启 Session 恢复记录。这两个议题都定义了隐私边界和可观察的验收证据。

主要来源

- DeepSeek Harness 官方仓库
- 官方架构文档
- 官方 Agent 生命周期
- 官方能力接缝
- 官方工具执行流水线
- 官方用户指南

许可证

Apache-2.0。参见 LICENSE。