aleskxyz/dsh-subagent-fork-lite

dsh-subagent-fork-lite

进程内 DeepSeek Harness 子代理提供程序，为每个子代理注入父级已完成对话的有界窗口——最后 N 个已完成的轮次——而非整个记录。

默认以 fork-lite 注册到 ctx.subagents。

支持矩阵

| Harness 标签 | npm 包版本线 | 类型检查 | 单元测试 | 备注 |
|---|---|---|---|---|
| dsh-v0.1.2-rc.1 | 0.1.2-rc.1 | 通过 | 通过 | sourceEventSeqs 重映射使用版本安全的读取方式 |
| dsh-v0.1.5-rc.2 | 0.1.5-rc.2 | 通过 | 通过 | 主要开发/CI 固定版本 |
| dsh-v0.1.6-alpha.1 | 0.1.6-alpha.1 | 通过 | 通过 | session.snapshotEvents() 已弃用但仍在使用（与原生 fork 相同） |

这些版本线上不存在原生 harness 种子窗口 API——此插件仍是有界种子提供程序。

特性

- 轮次窗口种子——配置子代理继承多少个已完成的父级轮次（maxCompletedTurns）
- 稳定的会话中途截断——进行中（未完成）的父级轮次永远不会被注入；仅注入截至最后一个 turn/end 的平衡历史
- 有效的会话种子——窗口事件会重新编号，使 seq 从 0 起连续（包括重映射的 sourceEventSeqs）
- 进程内子代理——深度限制、工具过滤、persona、结构化输出以及每次启动的 agentOptions
- 上下文继承标志——使用种子时声明 inheritsParentContext: true
- 命名预设——使用不同的 providerName / maxCompletedTurns 值挂载多个实例

快速开始

git 渠道（最新 main）
dsh plugin --profile web add "github:aleskxyz/dsh-subagent-fork-lite#main"

或从 npm 安装（发布后）
dsh plugin --profile web add dsh-subagent-fork-lite

重启 profile，然后验证该行
dsh --profile web --dump-config | grep -A6 'id: subagent-fork-lite'

使用提供程序名称 fork-lite 启动子代理（参见用法）。

安装与卸载

- git 渠道（最新 main）：dsh plugin --profile web add "github:aleskxyz/dsh-subagent-fork-lite#main"——包的 prepare 脚本会使用生产依赖进行构建；如果安装因 ERR_PNPM_IGNORED_BUILDS 停止，请批准 esbuild（以及 CLI 打印的任何其他键）。
- npm 渠道（已发布版本）：dsh plugin --profile web add dsh-subagent-fork-lite。
- tarball 渠道：在本仓库中运行 pnpm pack，然后运行 dsh plugin --profile web add ./dsh-subagent-fork-lite-.tgz。
- 卸载：dsh plugin --profile web remove dsh-subagent-fork-lite（或从 profile 补丁中移除该行）。

或者将该包插入你的 profile 补丁（参见 cordis.patch.yml）。

配置

所有可调项均为 Schemastery Config 字段（可从 cordis.yml 更改）。以 id 为目标的覆盖会替换整个配置行——请重新声明你需要的每个键。

| 字段 | 默认值 | 含义 |
|---|---|---|
| providerName | fork-lite | 注册到 ctx.subagents 的名称 |
| maxCompletedTurns | 2 | 要作为种子注入的已完成父轮次数量；0 表示不注入任何内容 |

- insert:
- id: subagent-fork-lite
name: dsh-subagent-fork-lite
config:
providerName: fork-lite
maxCompletedTurns: 2

多个预算

种子大小对每个挂载的实例是固定的。如需不同的窗口，请挂载多行：

- insert:
- id: subagent-fork-lite-2
name: dsh-subagent-fork-lite
config:
providerName: fork-lite-2
maxCompletedTurns: 2
- id: subagent-fork-lite-5
name: dsh-subagent-fork-lite
config:
providerName: fork-lite-5
maxCompletedTurns: 5

然后使用你需要的提供程序名称启动。

用法

const run = await ctx.subagents.start('fork-lite', {
parent,
prompt: [{ type: 'text', text: 'Your task for the child…' }],
signal,
// optional per-start route overrides:
agentOptions: { provider: 'deepseek-official', model: '…' },
// optional: toolFilter, persona, outputSchema, maxDepth, label
})

const result = await run.result
await run.dispose()

省略 agentOptions 以继承父级的 LLM 提供程序和模型。

工具与界面

| 界面 | 类型 | 说明 |
|---|---|---|
| fork-lite（可配置） | 子代理提供程序 | 注册在 ctx.subagents 上；通过 subagents.start(providerName, …) 使用 |
| cordis.patch.yml | 捆绑补丁 | 用于配置文件安装的默认插入行 |

没有命令、会话投影或客户端 UI。

种子注入的工作原理

1. 读取父会话日志，直到最后一个 turn/end（已完成轮次前缀）。
2. 仅保留这些轮次中最后 maxCompletedTurns 个轮次。
3. 将事件 seq 值重新编号为 0…k，以便子会话接受该种子。
4. 将种子交给进程内运行驱动程序；子级的首条用户消息就是你的 prompt。

随后子级在自己的会话中运行。之后的父轮次不会实时共享——种子是启动时的一次性快照。

种子包含的内容

在保留的轮次内，子级会收到父级记录的事件（用户/助手消息、工具调用/结果、轮次标记以及该窗口内的其他事件）。模型看到的是由这些事件衍生的表层历史。

它不包含的内容

- 早于该窗口的父轮次
- 父级当前未结束的轮次
- 在父日志之外定义的自定义或合成消息

能力

| 能力 | 是否支持 |
|---|---|
| agentOptions | 是 |
| outputSchema | 是 |
| depthLimit | 是 |
| toolFilter | 是 |
| persona | 是 |
| 可继续准备（prepareContinuable） | 是（种子在创建时捕获一次） |

已知限制

- 种子策略仅通过 Cordis 配置设置——不是每次 start() 调用上的字段。使用多个挂载的提供程序名称来实现离散预算。
- 窗口大小以已完成轮次衡量，而不是字符数或 token 数。
- 包含 sourceEventSeqs 指向窗口之外的表面替换的窗口无法重新编号，并且会导致种子构建失败。
- 在 0.1.6-alpha.1+ 上，同步的 session.snapshotEvents() 已被弃用；此提供程序仍在使用它（与原生 fork 相同的延迟迁移）。
- 启动后新注入的 AGENTS.md / 运行时与种子（agent/pre-step）是分开的；需要隔离的调用方必须自行过滤这些内容。

许可证

Apache-2.0