DSH 的插件架构 与执行核心
DeepSeek Harness（DSH）是一个以插件组织能力的 AI Agent 运行框架。模型生成回答或提出工具调用请求，框架负责装配模型、工具和运行环境，调度任务执行、记录会话并衔接用户交互。理解 DSH，需要看清一次请求如何在这些组件之间流转，以及执行状态由谁管理。
本文从核心组件及其职责入手，用一次文件读取任务串联启动装配、模型调用、工具执行和会话记录。下方山海图提供十五个机制章节的阅读入口：可以沿正文建立整体认识，也可以点击地标查看具体机制；需要查询插件能力和配置时，再进入插件与包目录。地图按主题分区，不表示调用关系或执行顺序。
一、核心组件及其职责
执行核心按职责分工：模型生成决策，AgentLoop 调度调用，能力插件执行操作，Session 保存事实。模型适配器统一请求和流式响应，工具注册表统一工具描述、参数校验与分派；具体文件或进程操作由相应服务提供者完成。
| 组件 | 主要职责 | 调用或依赖的组件 |
|---|---|---|
Agentdsh-agent | 提供可控制的任务对象，接收消息，支持追加要求和取消 | AgentLoop |
AgentLoopdsh-agent-loop | 驱动任务：组织请求、调用模型、安排工具、判断是否继续 | 模型服务与工具注册表 |
| 模型适配器 | 把统一请求转换成具体模型厂商的协议，再把流式响应转回来 | 远端模型服务 |
工具注册表dsh-tools | 根据模型返回的工具名找到执行器，校验参数并进入工具执行链路 | read 执行器 |
文件工具dsh-tool-fs | 把 read 参数变成文件服务操作，再整理为模型能用的行号与文本结果 | ctx.fs 文件服务 |
本地文件提供者dsh-fs-local | 实现文件服务，实际访问宿主文件系统 | 本机磁盘 |
Sessiondsh-session | 记录输入、模型消息、工具调用与结果，供后续请求和恢复使用 | 所组合的持久化后端 |
这些组件通过 Cordis 提供的共享上下文、服务和事件连接。它们作为插件装配，连执行循环也可以替换。这条执行流程涉及三类职责：模型生成调用，循环与工具执行调用，Session 保存记录。
箭头表示标注的调用或依赖关系；点击组件定位正文。完整关系见下方文字说明。
箭头表示标注的调用或依赖关系；点击组件定位正文。完整关系见下方文字说明。
二、启动时的能力装配
接收任务之前，DSH 需要确定模型提供者、文件后端和会话存储。负责启动装配的 dsh-app-boot 根据选定的 profile（运行组合）加载插件；Cordis 随后把服务和工具连接起来。安装了某个包，不等于这次运行已经启用它。
以本页任务为例，我们选择一种具备模型适配器、本地文件工具和会话存储的组合。dsh-tool-fs 向工具注册表注册 read，dsh-fs-local 提供实际本地文件访问，模型适配器提供模型调用。少了 read，模型没有这个工具可选；少了文件提供者，工具也没有可调用的文件服务。
为什么还需要 bundle、patch 和不同 profile？
同一套核心可以做成 Web 应用、终端任务或 SDK 服务。bundle 汇集可复用的插件配置与代码，profile 选择这些 bundle，patch 则修改或插入配置行。装配顺序是：按声明顺序应用 bundles → profile patch → Harness home patch → 命令行 overlay。配置行中的 config 整体替换，不能当作字段深合并。
本资料版本中，web、headless、sdk、acp 使用 base 再叠加入口；sdk-minimal 使用独立显式配置树。Desktop 由 Electron 承载保留 profile，并启动完整 Web 应用能力。插件是否实际启用，仍须以运行配置为准。
装配完成后，Agent 才能使用这些组件处理输入。详细说明：装配规则 · 插件如何加载与释放。
三、文件读取任务的执行过程
示例任务：“读取项目的 README.md，告诉我怎样启动项目。”下面假设模型先调用一次 read，再根据结果回答。这是用于解释组件分工的一条可能路径，实际模型也可能先搜索文件，或需要多次读取。
Agent 接收输入并唤醒执行循环
界面或 SDK 将用户消息提交给
dsh-agent提供的Agent.followup()。Agent 将消息放进输入队列，并唤醒dsh-agent-loop的驱动。Agent 是外界控制任务的入口；AgentLoop 负责持续推进执行。dsh-agent· 接口摘录，省略上下文 · agent.followup · packages/core/agent/README.md// 用户或插件递交后续输入并唤醒下一轮；消息先进入 inbox，再由循环接纳。 handle.agent.followup({ content: [{ type: 'text', text: '解释项目启动方式。' }], source: { kind: 'user' }, })循环开启一个 turn（回合），认领排队消息。消息入队后仍需准备和接纳，期间可能失败或被取消，因此入队不代表已提交给模型。深入：队列、回合与取消。
AgentLoop 组装模型请求
循环调用
dsh-system-prompt收集系统规则和可用工具，与用户消息一同准备为模型请求。工具清单里的 schema 描述了 read 接受 file_path 等参数，模型因此知道该怎样提出调用。准备好后，循环把本次接纳的输入记入 Session，再交给模型服务。system-prompt 负责组装系统提示，AgentLoop 负责推进请求。深入：上下文从哪里来。
请求提交之前还有哪些检查？
上下文插件可以贡献项目指令等材料；agent/pre-step 监听器可以调整或拒绝本步输入。获准进入后，循环开启 step，经过请求扩展点并准备模型调用。准备就绪才协调并记录被接纳的系统提示、用户消息等事实，从日志导出并固定请求；准备阶段取消不会提交这些输入。详细顺序见执行与上下文章节。
模型适配器解析响应中的 read 调用
dsh-llm提供统一的模型服务接口，具体适配器处理所选厂商的请求格式、能力和流式响应。在这次示例中，远端模型返回的是一个结构化工具调用：read({file_path: "README.md"})，此时文件还没有被读取。dsh-llm· 接口摘录，省略上下文 · ctx.llm.stream · packages/llm/llm/README.md// AgentLoop 或摘要器发起单次提供者尝试，消费流片段并收到一个终止 finish。 for await (const chunk of ctx.llm.stream({ provider: 'deepseek-official', model: 'deepseek-v4-flash', messages: [{ role: 'user', content: [{ type: 'text', text: '解释启动方式。' }] }], })) { /* 处理片段 */ }适配器把响应转换成统一事件，循环提交
assistant/message，并安排其中的工具调用。界面可以同时显示实时增量；这类实时通知与已结算日志有不同用途。深入：路由、适配器与请求失败。工具注册表分派调用，文件提供者读取磁盘
循环把调用交给
dsh-tools。工具注册表负责查找 read、校验参数并执行工具链路；dsh-tool-fs的 read 执行器调用ctx.fs；在本例的本地配置中，实现这个服务的是dsh-fs-local。dsh-tool-fs· 接口摘录，省略上下文 · read · packages/fs/tool-fs/README.md// 模型以文件路径和可选行范围请求正文；tool-fs 解释参数并调用文件服务。 {"file_path":"README.md","offset":1,"limit":40}read 工具定义参数与返回结果，文件提供者实现文件访问。本例的
dsh-fs-local按宿主权限读取；现有dsh-fs-sandbox主要约束写入和编辑，不会把 read 限制在工作区。read 把读到的文字整理为带行号、受大小限制的结果，循环记录tool/call和tool/result。深入：执行顺序与工具策略 · 深入：权限检查与执行限制。AgentLoop 将读取结果纳入下一次模型请求
循环结束这一步，再从 Session 已记录的历史生成下一步请求。这时历史里既有用户问题，也有模型发出的 read 调用和读到的 README 内容。模型据此解释启动命令；循环记录这次回答。如果模型继续请求工具，循环就继续推进。
在这条路径里，第一次“请求模型并执行 read”是一个 step，第二次“请求模型并得到回答”又是一个 step，它们属于同一个 turn。满足结束条件且没有待处理输入后，循环经过停止检查并结束回合，Agent 回到空闲。turn 也可能因接纳失败而没有任何模型请求。深入：何时继续、何时停止。
Session 保存执行记录，支持后续恢复
dsh-session负责组织事实记录，所组合的持久化后端负责写出存储。重开会话时，系统从这些记录恢复历史，再创建运行中的 Agent；原进程中的运行对象不会恢复。若要确认后端已经完成写出，需要等待相应的持久化检查点。工具调用、工具结果、最终回答各有记录，因此既能供下一步模型使用，也能供界面回放和查询。进程在流式输出结算之前硬退出，则不能保证未结算片段也能恢复。深入：存储、恢复与格式演进。
执行顺序：Agent 收消息 → AgentLoop 组织请求 → 模型适配器取得决策 → 工具注册表分派 → 文件工具调用提供者 → 结果进入 Session → AgentLoop 再请求模型并结束回合。Session 贯穿过程记录事实，界面订阅运行状态和输出。
如果文件不存在，或者中途取消，会发生什么？
文件不存在时，文件工具把失败整理成稳定错误和恢复提示，模型才能据此改路径、搜索或向用户说明。取消则由 Agent 入口传入执行链路；各下游组件必须合作响应。请求准备阶段取消不会提交系统提示和用户输入；已经开始的模型尝试与工具调用还涉及结算和恢复规则。不同阶段不能笼统承诺“自动从头重跑”。
模型请求的重试在当前步骤内处理，不重新运行整套输入接纳；工具合作超时也不等于强制终止进程。具体条件见模型请求、工具执行与恢复机制。
四、运行状态、会话日志与界面显示
执行文件读取任务时，界面会显示读取状态和流式回答。这些显示内容的来源、保存方式和恢复条件各不相同。下表列出运行状态、会话日志及派生内容的区别。
| 在哪里 | 这条任务中的例子 | 负责什么 |
|---|---|---|
| 运行中的 Agent | 消息还在排队、循环正在请求模型、用户发来取消信号 | 控制当前执行；这些实时状态不等于已经保存的事实 |
| Session 日志 | 已接纳的问题、模型的 read 调用、文件内容结果、已结算回答 | 提供可回放和恢复的事实；持久化后端负责写出 |
| 由日志派生的内容 | 界面的文件调用卡片、下一次请求所用的模型历史 | 把同一批事实转成各自需要的表示；显示与请求不必完全相同 |
DSH 规定：模型可见的内容必须能从 Session 日志重建。例如 README 的读取结果需要记入日志，才能重建模型生成启动说明时所用的输入。另一方面，历史可能被压缩或替换后再进入模型，所以日志里有一条记录，也不表示它永远原样出现在每次请求里。
流式显示则有一个具体限制：如果进程在回答结算前硬退出，界面刚显示过的片段不保证已成为持久消息。恢复以已记录并保存的事实为基础。因此，实时显示过的内容与已持久化的内容需要分别判断。
五、组件拆分的收益与成本
本地文件读取经过执行循环、工具注册表、文件工具和文件提供者。这种分层使同一循环能够使用不同模型、工具和执行环境。比如把文件提供者换成受限后端时，循环不必理解每一种文件访问规则。
这种拆分也有成本：追踪一个操作，需要同时看配置和多个组件。下表根据上述机制分析各项选择的收益与成本。
| 选择 | 收益 | 需要承担的代价 |
|---|---|---|
| 用插件组合产品 | 替换实现、按运行形态选择能力，共用扩展点 | 理解行为需要同时看装配配置、服务和事件，目录结构本身不够 |
| 分开定义、提供者与消费者 | 切换执行环境时多个消费者可以复用新实现 | 接口需要覆盖真实消费者，并协调文件、子进程等能力所在的执行环境 |
| 由日志重建模型历史 | 恢复、回放和查询有可检查的事实来源 | 上下文变更需要记录与投影规则，持久格式演进必须维护兼容性 |
| 区分实时流与持久结算 | 实时显示与完整历史各自有明确用途 | 未结算流的崩溃恢复能力有限，界面需区分暂态与已提交状态 |
| 通过事件扩展执行 | 能力与策略可组合，减少执行循环需要直接处理的行为 | 必须理解事件顺序与委托语义；waterfall 监听器不调用 next 就会截断后续链路 |
六、从文件读取扩展到更复杂的任务
项目分析、文件修改和产品集成会涉及更多机制。以下按任务类型列出相关章节。
项目分析：上下文与压缩
项目指令、历史、工具结果都会占用模型窗口。上下文管理解释材料如何进入请求；上下文压缩接着解释空间不够时怎样裁剪或摘要，以及丢失细节的代价。
并行与长任务：子代理、作业和调度
独立调查可使用子代理与协作，相关章节说明创建、隔离和结果返回机制；让工作跨回合、后台或定时推进，则进入任务、作业与调度。这些能力各有生命周期，不能把“启动了”当作“必定完成”。
文件修改与命令执行：工具和权限
一旦任务开始写文件、运行命令，就需要理解工具执行与权限、审批和沙箱如何分工。若还要把文件交给用户，继续看附件、输出与交付，区分磁盘上的文件、持久附件和用户能打开的交付物。
产品集成：宿主、协议与外部扩展
宿主与协议说明 Web、Desktop、SDK、ACP 怎样连接核心；外部工具与扩展说明 MCP、技能和其他集成怎样加入能力。它们共用运行机制，但接入协议和信任条件不同。
运行维护：恢复、诊断与配置
重启后怎样接着做，看持久化与恢复；怎样查清哪里失败，看查询、诊断与可观测性；怎样调整能力组合，看装配与插件生命周期。各章附有相关包的目录链接，可查询具体能力与配置。
本页资料与核验范围
本页根据固定提交的架构文档整理，属于文档层核对；没有据此声称当前环境配置或运行行为已经实测。