Files
deepseek-harness/packages/sdk/server/README.zh.md
T
Tianyi Cui a3cb678875 Merge master current-directory support into subagent activations
Integrate the observed master checkpoint 7ab215e23e5d977aae7eb5d4fb91782d39969dbb without rewriting the earlier published checkpoints. Master adds current-directory events, directory-aware consumers, and retained Git worktrees; its old subagent startup paths overlapped the unified activation implementation.

Resolve directory selection within managed startup after acquiring parent ownership. Preserve the original Session origin while setting each new local child directory, retain persisted directory state on cold resume, and pass a required absolute cwd to external providers. Keep unified local/external ownership, full completion notices, parked-input host completion, SDK wait/error/shutdown behavior, and ACP cancellation semantics. Retain removal of the old in-process driver and continuation managers.

Combine SDK wait with the new directory requests, preserve the new master directory/worktree fixtures, regenerate derived catalogs from the combined sources, and refresh only the four stale prompt/schema sidecars. Preserve every protected historical schema, archived note, catalog-v2 acknowledgement, and recorded predecessor input.

Validation: full build; 59 CI static gates; 855 subagent tests with 100% coverage on changed core/external sources; affected consumer suites including 119 repaired-fixture tests; SDK 11 and headless 16 recorded scenarios; two local headless expected cases; six built nested SDK/ACP cases; lint, strict cast inventory, workspace constraints, and whitespace checks. Native Windows worker diagnostics remain additive and require the next CI run to classify the original crash.
2026-10-06 10:52:35 +08:00

9.9 KiB
Raw Blame History

description, kind
description kind
面向让进程外 SDK 客户端在 DeepSeek Harness 运行时中打开会话并驱动 agent 的部署的 stdio JSON-RPC 服务插件。 package-reference

@deepseek-ai/dsh-sdk-jsonrpc-server

English | 中文

概述

dsh-sdk-jsonrpc-server 通过 stdio 服务 SDK 协议格式(wire format),使进程外客户端能够驱动 harness agent(智能体):它为每个 sessionId 打开一个会话、把用户提示词排入队列,并把每个会话事件与 agent 状态转换流式发回客户端。把它作为 jsonrpc 插件挂载到 Loader 组合中;外围插件树提供其余一切——agent、模型适配器、持久化与工具。Stdout 只承载 JSON-RPC 帧,因此部署不得组合 stdout logger。它通过 dispose(资源释放)根运行时并以 0 退出应答 shutdown;EOF 与信号退出归 app bin 负责。

目录


使用本包

session/working-directory/get 接收 { sessionId };session/working-directory/set 接收 { sessionId, path }。两者均返回 { cwd },并可创建未知 Session,而不启动模型轮次。读取通过工作目录服务恢复缺失目录;修改保留起始目录元数据与权限,并通过已记录的用户上下文告知模型。

当运行时必须服务 SDK 客户端时挂载本插件:把它加入组合了 agent 服务的 cordis.yml,启动运行时,客户端即可通过 stdio 连接。常用路径是显式的——插件需要 agents 服务;其余每个能力都来自外围插件树。

组装

插件在首次使用时为每个 sessionId 创建一个 agent。已注册的模型适配器优先用于该路由;尚无适配器负责的 deepseek-official 路由会挂载 DeepSeek 适配器,任何其他尚无适配器负责的提供方都会导致初始化失败。初始化成功前,所选适配器会解析确切模型与可选推理强度。

配置

字段 默认值 含义
maxTokensAsSuccess false 把 max-token 轮次或 subagent 终止报告为成功的 SDK 结果

profile 组合拥有每个根 agent 的工具。input、output 与 exit 是仅供测试的运行时传输钩子;生产环境使用进程 stdio 与 process.exit。生成的配置目录是每个受支持字段的穷尽式真源。

stdout 即协议

Stdout 只承载 JSON-RPC 帧,客户端可以逐字节解析;诊断信息应写入 stderr。请勿在组合的插件树中加入 stdout logger。

SDK 客户端可以做什么

initialize 是运行时就绪边界:服务器由 Loader 组合挂载时,会等待当前插件树完成所有加载任务后再响应,因此首次提示词能够看到 MCP 初始工具发现等异步同级能力。握手返回协议稳定标识 deepseek-harness-sdk-runtime。服务器会通过所选适配器校验提供方/模型路由与可选的非空 reasoningEffort,再保存这些值;省略时不会保存推理强度,因此模型保留自身默认值。可选的正整数 maxTokens 会成为每个 SDK 创建的 agent 及其进程内后代的请求输出上限,省略时则应用所选适配器或提供方路由的默认值。JSON-RPC 请求可能并发分派,因此在一次 initialize 成功完成之前,session/prompt 会拒绝;客户端必须等待握手完成后再发送提示词。已接受的提示词会把一条带标识的用户消息排入队列,并立即返回 { messageId };服务器随后把每个持久事实作为 session.event、把整个 agent 生命周期的每次状态转换作为 session.status 流式发出。它不会把某条助手消息或 turn/end 归属于某个提示词,同一会话上的独立请求可以继续排入更多工作。持久化根目录与 persona 来自外围组合。

session/wait 观察已有 SDK 会话,直到受管理后代及其触发的根 Agent 后续轮次完成。它拒绝未知或已释放的根 Agent,不会创建会话,并在后代检查期间根 Agent 持续空闲后响应。收件箱消息处于停放状态的空闲子级继续驻留,但不延迟此响应;后续唤醒输入可使其继续运行。完成前发出的会话通知在 stdio 传输上先于响应到达。Agent 的运行时错误会保留在对应的确切会话中,直到后续提交的 turn/end 记录结果;否则等待请求会失败,即使错误发生在等待请求之前。终止事件已经记录的错误仍通过会话事件表达,后续成功的活动会清除较早的运行时错误。

关闭与退出

插件应答 shutdown,刷新响应并 dispose 根上下文,使 SDK 持有的 agent、订阅与持久化达到完全停稳,然后以 0 退出。EOF 与信号退出归 app bin 负责,后者也会 dispose 根上下文。仅卸载此插件会停止服务,但不会退出进程。


理解实现

实现细节——点击展开

本节解释服务插件背后的设计;可观察行为已在使用本包中完整说明。

设计理念

本插件是轻量的展示适配器:HarnessSdkJsonRpcServer 负责协议方法与通知,传输与具名协议类型来自 dsh-sdk-protocol,与客户端 SDK 共享。它订阅会话、agent 与 subagent 生命周期事件,并把它们作为协议通知转发;只有当服务在生命周期建立快照时记录的 local 标志为 true 时才转发 subagent 完成事件——提供方名称、子级 id 与持久化谱系均不能证明本地性。

源码地图

文件 职责
src/index.ts 插件入口:Config schema、stdio 接线、请求分发、共享关闭与退出任务
src/server.ts HarnessSdkJsonRpcServer:协议方法、逐会话 agent 创建、生命周期订阅、清理

请求流程

每个协议方法在执行前都会校验输入并解析负责该请求的状态——initialize 保存 SDK 路由,session/prompt 解析存活的 agent 与会话配对并排入消息,shutdown 刷新响应,再 dispose 根上下文使其达到完全停稳,最后以 0 退出——共享退出任务确保竞争的 shutdown 请求绝不会重复 dispose 或退出。分发逻辑位于 src/index.ts 与 src/server.ts。

清理

server.shutdown() 关闭其精确根 Agent 下的后代准入,按子级优先顺序排空托管后代,再释放根句柄与适配器。它移除自身订阅,而仅卸载本插件时,无关父级树与外围上下文保持运行。后代排空失败会在其余根句柄与适配器的清理完成后报告。协议 shutdown 则 dispose 根 fiber,使持久化与整个运行时在进程退出前达到完全停稳。


进一步探索

当插件约定不够用时阅读以下页面。它们从协议格式进入客户端与可运行应用。


模型体验

SDK 用户消息

模型看到什么

对于每个已接受的 session/prompt,文本和持久内容引用会原样进入一条用户消息。内联 SdkEncodedImageBlock 会先通过组合中的附件存储完成校验与提交,因此会话日志保留内容寻址的图片引用而不是 base64 字节。此包不会添加系统提示词文本或工具 schema;这些内容来自组合中的其他插件。

Token 影响

依数据而定的用户消息 token 会进入保留的会话历史,并在后续轮次中重复发送,直至另一个包将其压缩(compaction)。JSON-RPC 帧、会话通知与服务器内部记录不会增加模型上下文 token。

KV Cache 影响

仅追加;新可见内容位于可复用请求前缀之后,不会使现有 KV Cache 条目失效。

已知限制与延期工作

这些限制说明本插件何时需要特别的运维注意。它们是当前包约束,不是与其他服务方式的对比或任务积压。

  • 协议没有逐会话关闭或提示词取消方法——SDK 创建的 agent 会一直存活到进程关闭。
  • 没有逐提示词结果——MessageId 只标识 inbox 准入;拥有自动化活动区间的客户端必须自行定义并观察该区间。
  • stdout 纯净性由部署保证——外围配置仍可能加载 stdout logger 并破坏 JSON-RPC 通道;此插件不会检查或否决同级 logger。
  • 自动挂载适配器仅支持 DeepSeek——initialize 可以复用任何预先注册的模型适配器,但唯一的回退行为是挂载 DeepSeek 适配器。

开发备注

维护者的工作上下文——点击展开

本开发备注是维护者的工作上下文,明确不具权威性——已交付的行为与限制见上文各节与代码。单文件可执行运行时分发将本插件与打包的 jsonrpc-demo bin 配对;请让关闭与退出约定与负责 EOF 和信号退出的 app bin 保持一致。没有记录其他未解决的开放设计问题。