编程

Agent 接口、注册表、进程本地发起方作用域，以及 agent/* 事件词汇。每个插件（UI、钩子、编排器）都面向此处定义的 Agent handle 编程；它不依赖循环，因此循环可以替换。

agent（智能体）的唯一具体实现插件和循环驱动器。其包内部实现满足 Agent 接口，并驱动会话、轮次和步骤的生命周期。

按 preset 组装 agent（智能体）。preset 是一个目录，其中放置一份 agent.cordis.yml；roster 在整个进程内只把它挂载一次（常驻 scope），命名它的每个会话通过把自己 agent 的 scope key 认父到该挂载（dsh-scope 的父链）来加入。挂载的工具、提示词段落与投影单元只存在一份，覆盖所有已加入的 agent——其插件本就按 Session/Agent 分键存状态，会话在共享实例内互不串扰——而完全没有 agent 的宿主读取方（冷读记录）也能按 prese…

这是 @deepseek-ai/dsh-code-runtime seam 的 worker 线程实现：WorkerThreadCodeRuntime 会在每次运行中使用一个全新的 Node worker_threads.Worker，输入 TypeScript，由宿主侧剥离类型，通过消息端口桥接绑定，输出 { value, logs, error?

面向用户的 /goal 控制，基于 ctx.goals 实现。该插件通过 ctx.commands 注册一个全局命令，因此每个已组合的命令适配器都能发现并执行它，无需模型轮次。用户 goal 命令 Agent Note 负责用户体验与组合决策。

由插件负责、供交互式 UI 适配器使用的面向用户命令注册表。插件命令注册 Agent Note定义了其边界与分发约定。

事件溯源的同会话目标状态。该服务在 agent（智能体）的现有会话中保留一个当前待完成目标，同时将继续执行的权限作为进程本地续行启用状态。goal 领域 Agent Note 负责设计理由；goal 类型目录记录具体的数据形状。

ctx.goals 的同会话续行驱动器。它通过公开 Agent 与会话服务，把 phase 为 active 且已启用续行的目标转换为连续的 Goal Round；同会话驱动器 Agent Note 记载竞态与生命周期方面的设计理由。

@deepseek-ai/dsh-jobs 注册表约定的进程本地实现：LocalJobRegistry 把每条记录保存在内存中，按 kind 签发 <kind>-N id，并且只交出全新快照，从不交出实时状态。作为插件加载后即注册为 ctx.jobs。

按 agent（智能体）分别记录到日志的 plan 协作状态，提供由部署方配置的引导内容、用于直接进入的 /plan [message] 命令、用于直接退出的 /plan off 命令，以及经用户评审的 exit_plan_mode 退出方式。Plan mode 是软引导；沙箱模式和批准策略各自强制执行限制，且不读写 plan 状态。

这是一个仅提供建议的循环中断器，而非面向模型的工具：它不会出现在工具列表中，不会否决或改写调用，只增加一种行为。它监视每个 agent（智能体）的工具调用流，统计以完全相同的规范化参数连续调用同一工具的次数；达到所配置的连续次数时，它会注入逐级增强的提示，要求模型停止重复、重新阅读上一次结果，并改用其他方案或结束任务。究竟是换一种方式重试、收集更多证据还是完成任务，仍完全由模型决定：合理的重复调用既不会延迟，也不会受阻。决策记录见 repeat-tool-reminder Agent Note。

subagent seam 允许一个 agent（智能体）通过具名提供方把工作委派给子 agent。调用方统一使用 ctx.subagents 服务 API；提供方决定子 agent 在当前进程、其他进程，还是通过未来的传输方式运行。

fork 提供方会创建一个进程内子 agent（智能体），并以父 agent 已完成的对话轮次作为初始内容。它与 spawn 共用全部运行机制；唯一的行为差异是会话初始内容。

spawn 提供方会在当前进程中创建一个全新的子 Agent。子 agent（智能体）有自己的会话，看不到父 agent 的对话历史，并复用宿主的 agent 工厂及 LLM（大语言模型）/工具服务。

模型侧 ask_user_question 工具，基于 ctx.userQuestions 实现。当模型需要确认、选择结果或缺失的信息才能继续时，它可以借此向用户提出简明问题。

模型侧 bash 工具，注册在 ctx.shell 执行器 seam 上。前台执行始终位于该 seam 之后；后台进程句柄会注册到通用 ctx.jobs 运行时，并通过 job_output、job_list 和 job_kill 控制；这些工具由 @deepseek-ai/dsh-tool-jobs 提供。

工具调用超时强制执行器：单个 tools/execute 环绕分发监听器，会在 exec.signal 上设置单次调用的协作式截止时间；适用于声明了 timeoutMs 且声明位于其 ToolDefinition 上的工具。该截止时间先到时，它返回结构化 TOOL_TIMEOUT 结果。预算从工具自身的声明中读取（ToolDefinition.timeoutMs，由拥有该工具的插件设置），因此此插件是零配置的。它是 tools/execute 包装层的参考实现，也是面向模型工具调用预算的强制执行归属地（超时库 Ag…

面向模型的文件系统工具（read、read_image、write、edit）及其执行器。这是文件系统栈的消费方层：拥有工具名称、JSON Schema、参数校验、提示词段、读取窗口逻辑和结果格式化。它直接通过 ctx.fs 提供方约定（@deepseek-ai/dsh-fs）读取／写入／编辑。新鲜度／观察策略由独立插件（@deepseek-ai/dsh-fs-observation-policy）通过 fs/* 事件门禁贡献；工具不与其方法耦合。使用施加沙箱限制的提供方时，逐会话执行需要共享沙箱策略服务，工具还会…

ctx.goals 的面向模型控制 API：get_goal、create_goal 和 update_goal。goal 工具 Agent Note 负责权限拆分与 Codex 风格用户体验。

ctx.jobs 的面向模型控制器：三个与 kind 无关的工具、完成通知和一个后台工作提示词区段。加载该插件会附加 ctx.jobs.start() 所要求的控制器。

注册在 ctx.shell 执行器 seam 之上的面向模型的 pwsh 工具。面向由 PowerShell 执行器（如 @deepseek-ai/dsh-pwsh-local）支撑 ctx.shell 的 Windows 组合；工具约定是 PowerShell 方言：原生 C:\...

面向模型的 ralph 工具运行固定的前台工作流，把一个不可变目标依次交给多个全新子 agent（智能体）。它展示如何把专用编排策略实现为基于 ctx.workflowEngine 和 ctx.subagents 的普通插件：不会向 agent-loop 添加 Ralph 模式或全新 agent loop（智能体循环），同会话的目标领域也保持独立。策略和暂缓事项由 Ralph Agent Note（agent 决策记录）负责。

基于 ctx.fs、面向模型的独立 str_replace_editor。它可与持久 Bash、一次性 Bash、沙箱 Bash 或其他终端接口组合。

基于一个已配置 ctx.subagents 提供方、面向模型的委派工具。更换提供方只会改变传输，不会改变执行约定。

可选的全局具名 send_message、interrupt_agent 与 list_agents 工具是 ctx.subagents 之上的轻量适配器。绑定提供方的 @deepseek-ai/dsh-tool-subagent 实例会为每种传输注册不同的委派工具；这个单独加载的包只注册一次共享控制工具，因此多个委派工具绝不会重复注册全局控制工具。根插件注册 send_message 与 interrupt_agent，且只要求 subagents；可单独加载的 ./list-agents 插件注册 list_a…

可选的子级作用域 report 工具是 ctx.subagents.reportFrom() 之上的轻量适配器。它为每个可继续的进程内子级提供一条返回通道，指向启动该子级的 Agent（智能体），并安装指示子级使用该通道的提示词 section。本包注册的是可继续子级设置贡献，而不是全局工具，因此该工具及其指引只存在于这些子级内部。根 Agent、一次性 subagent、远程 subagent 提供方、同级作用域以及不关联 Agent 的工具执行都不会提供或执行它。安装本包只授予这项子级作用域能力；父到子方向仍由…

面向模型的 todo_write 工具：agent（智能体）的完整任务列表，每次调用都会整体替换。

面向模型的 workflow 工具：运行一段扇出 subagent 的 JavaScript 编排脚本，并返回脚本的最终值。本包负责基于 ctx.workflowEngine 定义面向模型的 schema 和运行生命周期；脚本解析、执行、上限与取消位于 seam 之后，消费方仍负责面向父级的 schema 和结果包络。

本包为 WorkflowEngine 提供实现，每次运行使用一个 Node worker thread。worker 执行编排脚本；子 agent（智能体）留在宿主上，脚本通过带类型的宿主／worker 协议经由 ctx.subagents 访问它们。

提供机器可读输出的结构化 Git 工具，并拦截高风险破坏性操作。