{"_id":"@buddhilive/dsh-subagent-fork-in-process","name":"@buddhilive/dsh-subagent-fork-in-process","dist-tags":{"alpha":"0.1.2-alpha.3","latest":"0.1.2-alpha.3"},"versions":{"0.1.2-alpha.3":{"name":"@buddhilive/dsh-subagent-fork-in-process","description":"In-process fork subagent backend: runs a child agent seeded with a prefix of the parent's log","version":"0.1.2-alpha.3","publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/Buddhilive/buddhi-ai-harness.git","directory":"packages/subagent/subagent-fork-in-process"},"type":"module","main":"lib/index.js","types":"lib/types/index.d.ts","exports":{".":{"types":"./lib/types/index.d.ts","default":"./lib/index.js"},"./invariant":{"types":"./lib/types/invariant.d.ts","default":"./lib/invariant.js"},"./src/*":"./src/*","./package.json":"./package.json"},"license":"MIT","peerDependencies":{"@buddhilive/dsh-agent":"^0.1.2-alpha.3","@buddhilive/dsh-invariants":"^0.1.2-alpha.3","@buddhilive/dsh-session":"^0.1.2-alpha.3","@buddhilive/dsh-subagent":"^0.1.2-alpha.3","@deepseek-ai/cordis":"^4.0.2","@buddhilive/dsh-subagent-in-process-driver":"^0.1.2-alpha.3"},"dependencies":{"@deepseek-ai/schemastery":"^3.18.2"},"devDependencies":{"@buddhilive/dsh-agent":"^0.1.2-alpha.3","@buddhilive/dsh-agent-loop":"^0.1.2-alpha.3","@deepseek-ai/cordis-plugin-loader":"^1.0.3","@buddhilive/dsh-invariants":"^0.1.2-alpha.3","@buddhilive/dsh-agent-loop-testkit":"^0.1.2-alpha.3","@buddhilive/dsh-session":"^0.1.2-alpha.3","@buddhilive/dsh-llm":"^0.1.2-alpha.3","@buddhilive/dsh-subagent":"^0.1.2-alpha.3","@buddhilive/dsh-subagent-in-process-driver":"^0.1.2-alpha.3","@buddhilive/dsh-subagent-spawn-in-process":"^0.1.2-alpha.3","@buddhilive/dsh-session-projection":"^0.1.2-alpha.3","@deepseek-ai/cordis":"^4.0.2"},"_id":"@buddhilive/dsh-subagent-fork-in-process@0.1.2-alpha.3","bugs":{"url":"https://github.com/Buddhilive/buddhi-ai-harness/issues"},"homepage":"https://github.com/Buddhilive/buddhi-ai-harness#readme","_integrity":"sha512-bOUuYikGzXsgJsLFzSzNCNLAnT23C+vJHbgduLBXxomopwSEfOqb1wD/8rM3CE+RPaq+ECVvAF+J+Tv8Id5JbA==","_resolved":"C:\\DevDojo\\Buddhi\\buddhi-ai-harness\\dist\\npm\\buddhilive-dsh-subagent-fork-in-process-0.1.2-alpha.3.tgz","_from":"file:C:/DevDojo/Buddhi/buddhi-ai-harness/dist/npm/buddhilive-dsh-subagent-fork-in-process-0.1.2-alpha.3.tgz","_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-bOUuYikGzXsgJsLFzSzNCNLAnT23C+vJHbgduLBXxomopwSEfOqb1wD/8rM3CE+RPaq+ECVvAF+J+Tv8Id5JbA==","shasum":"a2255c61dbc80a30dcadcb79b7b2fdf22cef3f46","tarball":"https://registry.npmjs.org/@buddhilive/dsh-subagent-fork-in-process/-/dsh-subagent-fork-in-process-0.1.2-alpha.3.tgz","fileCount":9,"unpackedSize":27683,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCCW86dIt+1k6RN03MdutUj4GvczHCrusACriOM4L3jkwIhAIyv5GSgPiM/QxVCa86USw/EISXa0eLi9XbqXpIuEfe3"}]},"_npmUser":{"name":"buddhilive","email":"visitbudkavin@gmail.com"},"directories":{},"maintainers":[{"name":"buddhilive","email":"visitbudkavin@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/dsh-subagent-fork-in-process_0.1.2-alpha.3_1788165833795_0.26147087660973156"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-31T08:43:53.474Z","0.1.2-alpha.3":"2026-08-31T08:43:53.935Z","modified":"2026-08-31T08:43:54.197Z"},"maintainers":[{"name":"buddhilive","email":"visitbudkavin@gmail.com"}],"description":"In-process fork subagent backend: runs a child agent seeded with a prefix of the parent's log","homepage":"https://github.com/Buddhilive/buddhi-ai-harness#readme","repository":{"type":"git","url":"git+https://github.com/Buddhilive/buddhi-ai-harness.git","directory":"packages/subagent/subagent-fork-in-process"},"bugs":{"url":"https://github.com/Buddhilive/buddhi-ai-harness/issues"},"license":"MIT","readme":"---\ndescription: \"面向用户与维护者的进程内 fork subagent 后端说明，用于选择、配置或排查以父级已完成轮次作初始内容的子 agent。\"\nkind: \"package-reference\"\n---\n\n# @buddhilive/dsh-subagent-fork-in-process\n\n[English](README.md) | 中文\n\n## 概述\n\n`dsh-subagent-fork-in-process` 是一个进程内 subagent 后端：它以父级已完成的对话轮次作为每个子 agent（智能体）的初始内容——子 agent 能看到所有已完成轮次，但看不到进行中的轮次，因此后续工作可以在对话基础上继续，而无需复制对话。委派工具以 `fork` 提供方名称找到它，其行为与 spawn 后端一致，唯一差异是会话初始内容。当子任务延续当前对话时选择它；当子 agent 必须独立运行时选择 spawn。初始内容是 fork 时的一次性快照：此后父级记录的任何内容都不会到达子 agent。\n\n## 目录\n\n- [使用本包](#use-this-package)\n- [理解实现](#understand-the-implementation)\n- [进一步探索](#further-exploration)\n- [模型体验](#model-experience)\n- [已知限制与延期工作](#known-limitations-and-deferred-work)\n- [开发备注](#dev-note)\n\n-----\n\n<a id=\"use-this-package\"></a>\n## 使用本包\n\n当委派的工作必须建立在父级对话之上时，挂载此后端。常用路径与 spawn 相同：加载 subagent 服务与本后端，再把 `dsh-tool-subagent` 之类的委派工具指向 `fork` 提供方。\n\n### 何时选择\n\n当子 agent 需要对话的已完成轮次时——后续分析、审查、延续——选择 fork。当子 agent 应全新开始时选择 spawn；当子 agent 不能共享本进程时选择进程外后端。初始内容只传递对话历史：子 agent 仍获得全新的工具作用域，且不继承父级的任何权限。\n\n### 初始内容边界\n\n初始内容止于父级最后一个已完成的轮次。subagent 启动时，父级当前的工具调用轮次仍在进行，因此该进行中的轮次绝不会被包含；在第一个已完成轮次之前，初始内容为空，子 agent 的行为与全新 spawn 相同。\n\n### 最小配置\n\n先加载 subagent 服务与本后端，再配置一个委派工具。此组合暴露由 fork 支撑的 `subagent` 工具：\n\n```yaml\n- name: '@buddhilive/dsh-subagent'\n- name: '@buddhilive/dsh-subagent-fork-in-process'\n- name: '@buddhilive/dsh-tool-subagent'\n  config:\n    provider: fork\n```\n\n| 字段 | 默认值 | 含义 |\n|---|---|---|\n| `providerName` | `fork` | 注册到 `ctx.subagents` 的提供方名称 |\n\n生成的[配置目录](../../../docs/config-catalog.zh.md#buddhilivedsh-subagent-fork-in-process)是每个受支持字段及其 JSDoc 的穷尽式真源。\n\n### 一次 fork 委派会做什么\n\n一次工具调用启动一个以已完成轮次为初始内容的子 agent，并等待其结果：子 agent 能看到截至父级最后一个已完成轮次的对话，在自有会话中工作，父级只接收其最终输出——取消、拒绝、token 上限截断或启动被拒时则收到出错的工具结果。初始内容在启动时只捕获一次；此后的父级轮次绝不会到达子 agent。\n\n-----\n\n<a id=\"understand-the-implementation\"></a>\n## 理解实现\n\n<details>\n<summary>实现细节——点击展开</summary>\n\n本节解释后端背后的设计决策，以及[使用本包](#use-this-package)中行为的来源。\n\n### 设计理念\n\n与 spawn 的差异只有一处，且以数据表达：后端计算父级日志的已配平已完成轮次前缀，并把它作为子 agent 的会话初始内容交给共享进程内驱动器。由于实时序号等于数组下标，前缀始终是自序号零开始的合法初始内容；驱动器记录其长度，使结果读取器不会把作为初始内容的父级消息误认为子 agent 输出。\n\n### 源码地图\n\n| 文件 | 职责 |\n|---|---|\n| [`src/index.ts`](src/index.ts) | 提供方注册：前缀计算、`Config` schema、能力声明 |\n| [`src/invariant.ts`](src/invariant.ts) | 不变式伴生插件 |\n\n### 运行流程\n\n`start` 时，从父级事件日志中截取截至最后一个 `turn/end` 的前缀；共享驱动器随后以该初始内容创建子 agent，应用相同的 persona、工具过滤器与结构化输出设置，驱动一项任务，读取子 agent 自身的最终输出，并完全停稳地 dispose。该提供方声明 `agentOptions`，以及与 spawn 相同的输出、深度、过滤与 persona 能力。`prepareContinuable` 在创建时只捕获一次前缀，因为它会成为子 agent 自身持久 transcript（文本记录）的一部分。\n\n### 一次性绑定\n\nbase bundle 与 ACP/headless 示例在委派工具上把本提供方绑定为 `backgroundMode: one-shot`：可继续 fork 子 agent 会在继承历史之前携带子级作用域的 `report` 工具及其提示词 section，从而破坏逐字节前缀复用。CLI preset 保留可继续 fork，并接受该前缀损失（见[保持 fork 缓存的 Agent Note](../../../.agents/notes/implemented/architecture/2026-08-10-fork-children-stay-one-shot.zh.md)）。\n\n</details>\n\n-----\n\n<a id=\"further-exploration\"></a>\n## 进一步探索\n\n当包级约定不够用时阅读以下页面；它们从共享 subagent 模型进入兄弟后端，以及一次性绑定的设计证据。\n\n- [Subagent 子系统](../../../docs/subsystems/subagent.zh.md)——启动请求、结果、提供方约定与进程内深度和初始内容。\n- [dsh-subagent-in-process-driver](../subagent-in-process-driver/README.zh.md)——本后端调用的共享运行驱动器。\n- [dsh-subagent-spawn-in-process](../subagent-spawn-in-process/README.zh.md)——全新子级的兄弟后端。\n- [dsh-tool-subagent](../tool-subagent/README.zh.md)——指向该提供方的面向模型委派工具。\n- [生成配置目录](../../../docs/config-catalog.zh.md#buddhilivedsh-subagent-fork-in-process)——每个受支持配置字段及其源声明。\n- [fork 保持 one-shot](../../../.agents/notes/implemented/architecture/2026-08-10-fork-children-stay-one-shot.zh.md)——随附组合为何把 fork 绑定为 one-shot。\n\n-----\n\n<a id=\"model-experience\"></a>\n## 模型体验\n\n### 子 agent 历史与包络\n\n#### 模型看到什么\n\n子 agent 先接收由父级已配平的已完成轮次构成的前缀，再逐字接收新的任务内容。配置的 persona 会在子 agent 的全新作用域中遮蔽提示词文本；工具限制会过滤其全局协议 schema、可执行工具查找与 PTC mode SDK 绑定，但不影响独立指导内容。父级的工具视图与权限不会被继承；可选的结构化输出请求会添加仅属于子 agent 的约定；父级当前进行中的轮次会被排除。\n\n#### Token 影响\n\nfork 会把保留的已完成历史复制到子 agent 的请求中，子 agent 随后独立累积自己的 token。persona 会改变重复提示词的成本；过滤会改变 schema 或生成 SDK 的成本；首轮 fork 没有继承历史。\n\n#### KV Cache 影响\n\n在提供方与模型相同的前提下，子 agent 可以复用继承的逐字节相同前缀。persona、工具过滤、生成 SDK 或路由变化可能在继承历史之前使复用失效；后续子 agent 历史仅追加。base bundle 与 ACP/headless 示例使用一次性 fork 来保留此前缀。CLI preset 保留可继续 fork，并接受子级作用域的 `report` 工具及其提示词 section 使此前缀失效（见[保持 fork 缓存的 Agent Note](../../../.agents/notes/implemented/architecture/2026-08-10-fork-children-stay-one-shot.zh.md)）。\n\n### 父级工具结果（间接）\n\n#### 模型看到什么\n\n父级只通过 `dsh-tool-subagent` 接收子 agent 自身的最终输出，不接收继承的前缀或中间工作。\n\n#### Token 影响\n\n父级输入增加一个取决于数据的最终结果，并保留到上下文压缩（context compaction）为止。\n\n#### KV Cache 影响\n\n仅追加；新增可见内容位于可复用请求前缀之后，不会使现有 KV Cache 条目失效。\n\n## 已知限制与延期工作\n\n<a id=\"known-limitations-and-deferred-work\"></a>\n\n\n这些限制说明何时选择该后端是错误的；它们是当前包约束。\n\n- **初始内容是一次性快照**——子 agent 只能看到 fork 时父级已完成的轮次，看不到父级此后记录的任何内容；不会实时共享上下文。\n- **fork 生命周期策略因组合而异**——base bundle 与 ACP/headless 示例使用一次性 fork 来保留前缀复用；CLI preset 使用可继续 fork，并接受子级作用域的 [`report` 返回通道](../tool-subagent-report/README.zh.md)使此前缀失效。要让可继续 fork 保留缓存，子 agent 的系统提示词与工具 schema 必须和父级逐字节一致。理由与重新开放条件见[保持 fork 缓存的 Agent Note](../../../.agents/notes/implemented/architecture/2026-08-10-fork-children-stay-one-shot.zh.md)。\n- **随附 fork 工具不公开子级 LLM 路由选择**——它们继承父级提供方与模型，使复制的历史仍有资格复用 KV Cache。在某项改动能保留复用或公开有界重算成本前，路由选择保持禁用；[模型选择路由 Agent Note](../../../.agents/notes/implemented/feature/2026-08-18-model-selected-subagent-routes.zh.md)说明这项限制。\n\n<a id=\"dev-note\"></a>\n### 开发备注\n\n<details>\n<summary>维护者的工作上下文——点击展开</summary>\n\n无。\n\n</details>\n","readmeFilename":"README.zh.md","_rev":"1-e964976a45d80c04f23fcaf21caaa4c0"}