核心机制
本页介绍 Cordis 插件模型和生命周期状态机。
服务是一个插件向其他插件公开的能力。inject 声明插件需要哪些服务。
事件是 Cordis 插件间通信的核心机制。Harness 大量使用事件来实现松耦合的扩展点。
Cordis 是 DeepSeek Harness 底层的插件框架：它是一个小型运行时，其中的每项能力，包括工具、LLM（大语言模型）适配器、文件访问乃至 agent loop（智能体循环）本身，都是挂载到共享上下文中的插件。本教程通过动手实践讲解 Cordis：每一章都是一个可以运行的示例，你将在本仓库内的临时目录中逐步构建它，最后把一个插件接入真实的 harness 服务。
本教程面向 agent 开发者。你不需要深入掌握 TypeScript；下文的 TypeScript 说明会解释可能陌生的语法，并且每一章都会给出确切命令和预期输出。
如果你想阅读精简的概念参考，而不是逐步实践，请参阅 Cordis 入门。详尽的 API 参考见子系统页面上生成的 cordis-surface 区块，以及 Cordis 核心 API 页面。
如果你要为 harness 本身编写插件——由 cordis.yml 加载、在 Web UI 中驱动，而不是下面这个启动器——请从第一个 Harness 插件开始。
在本教程使用的 loader 配置中，Cordis 插件模块通过命名导出提供 apply 函数。Cordis 加载模块时，会用一个 上下文 调用 apply；该上下文就是 ctx 对象，插件通过它注册自己贡献的所有内容。
Cordis 插件可能因修改配置、热重载、显式资源释放或所需服务消失而卸载。通过 Cordis API 建立的注册属于 effect，会在所属插件卸载时撤销；在这些 API 之外管理的资源必须包装在 ctx.effect() 中。
服务是一个插件提供、其他插件通过 ctx 消费的具名能力。在 harness 中，ctx.tools、ctx.llm 和 ctx.agents 都是服务。消费方只指定 'tools' 之类的能力，而不导入其提供方，因此配置可以选择提供方，无需修改消费方。
服务支持直接调用；事件让插件无需知道有哪些插件正在监听，就能发出通知。harness 使用事件处理工具结果、模型请求和审批决定等交互。
cordis.yml 中的每个 Cordis 配置项都可以携带 config 块，插件则声明一个 schema，在运行 apply 前验证该块。错误配置会导致加载失败，并给出准确的错误：插件绝不会在配置不完整时启动。
到目前为止构建的每项能力都是插件，cordis.yml 则选择应用的插件树。本章会改变这种组合、热重载一个插件，并诊断始终无法加载的插件。
本章会向 harness 的 tools 服务注册一个可由模型调用的工具，通过 harness 工具流水线执行它，并观察结果事件。整个示例无需密钥，也不会调用模型。
Cordis 是 DeepSeek Harness 底层以 vendor 方式引入的插件框架。本文介绍 harness 插件作者在阅读子系统页面上生成的服务/事件参考之前需要了解的 Cordis 核心概念；Cordis 教程则通过实践逐一讲解这些概念。vendor 源码与同步流程见 vendor/README.md。
每个子系统一页，覆盖 DeepSeek Harness 的全部子系统：它是什么、它操作哪些数据结构，以及——当它由某个 ctx 服务或事件作用域支撑时——一段生成的 Cordis API 小节，承载其服务与事件参考。本目录与 architecture.md 互补：后者描述跨子系统的行为（服务映射、会话/轮次/步骤生命周期、事件分类体系）；这里的每一页是单个子系统词汇与接线的参考。
| 页面 | 负责内容 |
|---|---|
| core.md | packages/core 如何控制 agent loop（智能体循环）：逐包的循环说明、agent 创建与所有权（AgentHandle）、Agent 句柄的投递/取消/拦截约定，以及全仓通用类型模式（…Map → 派生联合、品牌化 id） |
| llm-streaming.md | packages/llm 的对话类型——Message/ContentBlock、组装完成的模型请求、StreamChunk wire protocol 和适配器约定（adapter contract）、BlockAssembler，以及 LlmAdapter 提供方约定 |
| token-meter.md | 不可变的标量与位置回放度量，附带已消费日志修订号 |
| scope.md | 作用域注册标识、dispatch 载体，以及拥有的 Scope 上下文 |
| typert.md | 远程调用描述符、lookup/Context 声明、Typert 注册表，以及 Host Gateway/Client API 边界 |
| goal.md | 持久 goal 标识、生命周期快照、激活、变更记录与 Round 归属 |
| schedule.md | 仅限 Session 内的提醒记录、持久转换、活动视图与普通对话交付 |
| commands.md | 人类命令注册表服务：定义、适配器发现、直接调用、结果与解析视图 |
| session.md | 完整的 SessionEventMap 变体目录、TurnTrigger/TurnEndReason、deriveMessages()、执行封闭与独立事件 |
| persistence.md | 持久性 seam：SessionPersistence、JSONL + SQLite 后端、session/flush、崩溃恢复、SessionHeader |
| settings.md | 用户设置 seam：SettingsNamespace 注册、分层解析（默认值 → 组合 base → 用户文档）、owner scope、热提交 |
| credentials.md | 凭据 seam：配置中的 CredentialRef 引用（绝不含值）、按操作解析、对 UI 安全的 CredentialInfo、提供方来源层 |
| session-query.md | 逻辑记录、有界精确事件读取、关系追踪、语义筛选器/文档与全文检索结果页 |
| feedback.md | 绑定生命周期的逐消息反馈记录、乐观版本、伴随记录持久化与 Host Remote 契约 |
| session-title.md | 持久标题快照、被引用的来源消息 seq 与异步提供方约定 |
| session-reference.md | 结构化跨会话引用：SessionReferenceInput/Candidate、prepared 消息上下文、稳定错误分类 |
| system-prompt.md | 逐次组装的上下文、工具提供方结果、提示词段落与协作式组装 |
| tools.md | ToolDefinition 完整字段、schema DSL、ToolExecution/ToolResult、工具展示 UI 类型，以及受保护的执行流水线 |
| user-questions.md | UI 支持的人工问答 seam：AskUserQuestionRequest、answer/options 词汇、提供方 API、错误分类体系 |
| approval.md | 一次性用户审批 seam：ApprovalRequest、ApprovalOutcome、逐会话策略、审计事件和 answerer 约定 |
| attachment.md | 持久图片标识与元数据、校验输入、经校验读取，以及 AttachmentStore seam |
| shell.md | bash 执行器 seam：ShellExecRequest/Spec、ShellRunResult、后台 ShellProcess 句柄 |
| subprocess.md | 子进程 seam：完全显式的 SubprocessSpawnSpec、基于偏移的输出读取器、不含分类的 SubprocessOutcome，以及受管 DSH_* 环境词汇 |
| terminal.md | 持久化终端 ID、后端/会话约定、发送就绪状态、有界读取与 owner 可见快照 |
| sandbox.md | 每会话策略解析与进程约束 seam：文件效果模式、执行/提供方策略、ConfinedArgv、强制执行与故障关闭错误 |
| code-runtime.md | 代码执行 seam：CodeRunRequest/Result、绑定命名空间、捕获日志、CodeRunFailure 分类体系 |
| extensions.md | 带版本的动态 Cordis Plugin 与 Package、Host/Client 激活、审批、运行时检查和生命周期撤销 |
| filesystem.md | 文件系统 seam：FsTarget、读/写/编辑结果、观测到的文件状态、FsErrorCode |
| lsp.md | LSP 导航 seam：LspQueryRequest/Result、LspProvider/Service、四种操作、LspError |
| skills.md | skill（技能）服务：发现优先级、SkillSummary/SkillDefinition、会话前缀目录、面向模型的 skill 加载 |
| compaction.md | 压缩（compaction）seam：compaction/* 会话事件、CompactionResult、CompactionEngine 接口 |
| subagent.md | subagent seam：命名提供方注册表、SubagentStartRequest/Result/Run、启动时与运行时能力拆分 |
| web.md | Web 访问 seam：WebSearchRequest/Result、WebFetchRequest/Result、WebFetchBody、提供方可用性、WebError |
| spill.md | spill 存储 seam：SaveTextSpill、SpillOwner/SpillSource、SpillRef、品牌类型 SpillLocator |
| workflow.md | 工作流 seam：WorkflowStartRequest、WorkflowMeta、WorkflowRun/Result、workflow/* 事件载荷、WorkflowError 致命性 |
| jobs.md | 后台任务运行时：品牌化 JobId、producer 约定、消费方视图和 ctx.jobs 服务行为 |
| permission-presets.md | 权限预设层：PresetSpec/PresetOption、派生的 custom 状态、仅记日志的 permission/preset 事件 |
| plan.md | 计划模式：仅记日志的 plan/mode 状态、待定选择的冲刷、PlanModeConfig、exit_plan_mode 审阅流程 |
| invariants.md | 运行时不变式注册表：选择配置 Config、InvariantInstaller/InvariantFailure、空配套插件约定 |
| web-server.md | HTTP 载体：WebRouteKind/WebRoute、匹配顺序、可认领的回退席位、index 渲染挂接点 |
| storage.md | 存储子系统：后端约定（StorageBackend）、StorageForms、DomainSpec/Domain、domain/changed |
| workspace.md | 工作区注册表：Workspace/WorkspaceId、注册与解析、与会话 cwd 的关系 |
| client-modules.md | Web 插件表：dsh.client 声明、WebBootGraph 线上组合、bundle 路由与 index 转换 |
| session-projection.md | 投影 seam：SessionProjectionMap、纯函数 ProjectionDefinition 单元、ProjectionSnapshot 的一致切面、变更馈送 |
| session-telemetry.md | 对外会话上报能力 seam：SessionTelemetryRecord/SessionTelemetrySeverity、SessionTelemetrySink 约定和 session-telemetry/record 脱敏 waterfall |
这些页面上的类型声明及其 JSDoc 与源码等价，并由
pnpm run verify-type-equiv检查漂移（见 development.md）。普通块保留完整声明；public-api块保留去除实现体的公开 class 声明。Cordis 服务与事件使用每页生成的 Cordis API 小节。
能力 Seams 与核心服务
Section titled “能力 Seams 与核心服务”服务可以是核心主干服务、可替换的能力 seam，也可以是组合包／组合点。下图展示了拥有服务声明的包、已知实现包，以及直接消费该服务的包。
flowchart LR pkg_attachment["attachment"] svc_attachments["ctx.attachments<br/>Durable binary attachment storage"] pkg_attachment_local["attachment-local"] pkg_host_runtime["host-runtime"] pkg_llm_pi_ai["llm-pi-ai"] pkg_llm["llm"] svc_llm["ctx.llm<br/>LLM adapter registry"] pkg_llm_deepseek["llm-deepseek"] pkg_llm_replay["llm-replay"] pkg_agent_loop["agent-loop"] pkg_compaction_basic["compaction-basic"] pkg_token_meter["token-meter"] svc_tokenMeter["ctx.tokenMeter<br/>Replay token measurement"] pkg_compaction_tool_result_pruner["compaction-tool-result-pruner"] svc_toolResultPruner["ctx.toolResultPruner<br/>Model-free tool-result pruning"] pkg_session["session"] svc_sessions["ctx.sessions<br/>In-memory session store"] pkg_agent["agent"] pkg_session_persistence["session-persistence"] pkg_session_query["session-query"] pkg_session_query_sqlite["session-query-sqlite"] pkg_subagent_inprocess["subagent-inprocess"] pkg_invariants["invariants"] pkg_message_feedback["message-feedback"] svc_invariants["ctx.invariants<br/>Package-owned invariant registry"] pkg_scope["scope"] pkg_typert_registry["typert-registry"] svc_typert["ctx.typert<br/>Runtime type registry"] pkg_typert_loader["typert-loader"] pkg_api_gateway["api-gateway"] svc_typertGateway["ctx.typertGateway<br/>Typert Host invocation gateway"] svc_sessionPersistence["ctx.sessionPersistence<br/>Durable session persistence seam"] pkg_session_persistence_jsonl["session-persistence-jsonl"] pkg_session_persistence_sqlite["session-persistence-sqlite"] pkg_tool_bash["tool-bash"] pkg_hooks_claude_code["hooks-claude-code"] pkg_hooks_codex["hooks-codex"] pkg_settings["settings"] svc_settings["ctx.settings<br/>User-settings seam"] pkg_settings_file["settings-file"] pkg_apiproxy["apiproxy"] pkg_credentials["credentials"] svc_credentials["ctx.credentials<br/>Credential seam"] pkg_credentials_local["credentials-local"] pkg_session_telemetry["session-telemetry"] svc_sessionTelemetry["ctx.sessionTelemetry<br/>Session telemetry seam"] pkg_session_telemetry_otel["session-telemetry-otel"] pkg_storage["storage"] svc_storage["ctx.storage<br/>Non-session storage hub"] pkg_storage_json["storage-json"] pkg_storage_sqlite["storage-sqlite"] pkg_storage_domain["storage-domain"] svc_storageDomain["ctx.storageDomain<br/>Domain data facility"] pkg_workspace["workspace"] svc_messageFeedback["ctx.messageFeedback<br/>Lifecycle-bound message feedback"] svc_workspaceRegistry["ctx.workspaceRegistry<br/>Workspace entity registry"] svc_sessionQuery["ctx.sessionQuery<br/>Session reads, traces, filters, and search"] pkg_session_reference["session-reference"] pkg_tool_session_query["tool-session-query"] svc_sessionReferenceResolver["ctx.sessionReferenceResolver<br/>Cross-session snapshot preparation"] pkg_session_title["session-title"] svc_sessionTitle["ctx.sessionTitle<br/>Log-backed session titles"] pkg_session_title_first_prompt_llm["session-title-first-prompt-llm"] pkg_session_title_all_prompts_llm["session-title-all-prompts-llm"] pkg_system_prompt["system-prompt"] svc_systemPrompt["ctx.systemPrompt<br/>System prompt assembly registry"] pkg_tools["tools"] pkg_tool_fs["tool-fs"] pkg_tool_terminal["tool-terminal"] pkg_tool_web["tool-web"] svc_tools["ctx.tools<br/>Tool registry and guarded execution pipeline"] pkg_tool_ask_user["tool-ask-user"] pkg_tool_cordis["tool-cordis"] pkg_tool_skill["tool-skill"] pkg_tool_subagent["tool-subagent"] pkg_tool_todo["tool-todo"] pkg_user_questions["user-questions"] svc_userQuestions["ctx.userQuestions<br/>Human question/answer seam"] pkg_plan_mode["plan-mode"] svc_planMode["ctx.planMode<br/>Plan collaboration state"] pkg_agent_presets["agent-presets"] svc_agentPresets["ctx.agentPresets<br/>Per-session agent composition"] pkg_commands["commands"] svc_commands["ctx.commands<br/>Human command registry"] pkg_session_projection["session-projection"] svc_sessionProjections["ctx.sessionProjections<br/>Session projection units"] pkg_host_apiproxy["host-apiproxy"] pkg_session_projection_cache["session-projection-cache"] svc_sessionProjectionCache["ctx.sessionProjectionCache<br/>Persisted projection cache"] pkg_skill["skill"] svc_skills["ctx.skills<br/>Skill provider registry"] pkg_skill_badge["skill-badge"] pkg_skill_filesystem["skill-filesystem"] svc_agents["ctx.agents<br/>Agent service"] pkg_acp["acp"] pkg_agent_default_model["agent-default-model"] svc_agentDefaultModel["ctx.agentDefaultModel<br/>Default Agent model selection"] pkg_headless["headless"] svc_agentLoop["ctx.agentLoop<br/>Concrete loop driver"] pkg_agent_spine_demo["agent-spine-demo"] pkg_goal["goal"] svc_goals["ctx.goals<br/>Same-session goal domain"] pkg_e2b["e2b"] svc_e2b["ctx.e2b<br/>E2B sandbox lifecycle owner"] pkg_fs_e2b["fs-e2b"] pkg_subprocess_e2b["subprocess-e2b"] pkg_subprocess["subprocess"] svc_subprocess["ctx.subprocess<br/>Subprocess seam"] pkg_subprocess_local["subprocess-local"] pkg_bash_local["bash-local"] pkg_bash_sandbox["bash-sandbox"] pkg_terminal_bash["terminal-bash"] pkg_lsp_stdio["lsp-stdio"] pkg_subagent_acp["subagent-acp"] pkg_subagent_codex["subagent-codex"] pkg_subagent_claude_code["subagent-claude-code"] pkg_shell["shell"] svc_shell["ctx.shell<br/>Bash executor seam"] pkg_pwsh_local["pwsh-local"] pkg_tool_pwsh["tool-pwsh"] pkg_shell_env["shell-env"] svc_shellEnv["ctx.shellEnv<br/>Managed bash environment registry"] pkg_terminal["terminal"] svc_terminals["ctx.terminals<br/>Persistent PTY session registry"] pkg_sandbox["sandbox"] svc_sandbox["ctx.sandbox<br/>Process-sandbox seam"] pkg_sandbox_local["sandbox-local"] pkg_sandbox_policy["sandbox-policy"] svc_sandboxPolicy["ctx.sandboxPolicy<br/>Sandbox policy home"] pkg_fs_sandbox["fs-sandbox"] pkg_approval["approval"] svc_approval["ctx.approval<br/>Approval seam"] pkg_permission_presets["permission-presets"] svc_permissionPresets["ctx.permissionPresets<br/>Permission presets"] pkg_code_runtime["code-runtime"] svc_codeRuntime["ctx.codeRuntime<br/>Code-execution seam"] pkg_code_runtime_worker["code-runtime-worker"] pkg_fs["fs"] svc_fs["ctx.fs<br/>Filesystem provider seam"] pkg_fs_local["fs-local"] pkg_fs_observation_policy["fs-observation-policy"] pkg_compaction["compaction"] svc_compaction["ctx.compaction<br/>Compaction seam"] pkg_subagent["subagent"] svc_subagents["ctx.subagents<br/>Subagent provider and continuation service"] pkg_subagent_spawn_in_process["subagent-spawn-in-process"] pkg_subagent_fork_in_process["subagent-fork-in-process"] pkg_subagent_dsh_sdk["subagent-dsh-sdk"] pkg_tool_subagent_control["tool-subagent-control"] pkg_tool_ralph["tool-ralph"] pkg_jobs["jobs"] svc_jobs["ctx.jobs<br/>Background job registry"] pkg_jobs_local["jobs-local"] pkg_tool_jobs["tool-jobs"] pkg_web["web"] svc_web["ctx.web<br/>Web access provider registry"] pkg_web_search_exa["web-search-exa"] pkg_web_search_perplexity["web-search-perplexity"] pkg_web_search_deepseek["web-search-deepseek"] pkg_web_fetch_http["web-fetch-http"] pkg_spill["spill"] svc_spillStore["ctx.spillStore<br/>Spill storage seam"] pkg_spill_local["spill-local"] pkg_spill_policy["spill-policy"] pkg_directory_picker["directory-picker"] svc_directoryPicker["ctx.directoryPicker<br/>Workspace-directory picking seam"] pkg_directory_picker_native["directory-picker-native"] pkg_directory_picker_browse["directory-picker-browse"] pkg_webserver["webserver"] svc_webServer["ctx.webServer<br/>HTTP route registration"] pkg_connection["connection"] pkg_modules["modules"] pkg_hmr["hmr"] svc_clientModules["ctx.clientModules<br/>Client plugin graph host"] pkg_workflow["workflow"] svc_workflowEngine["ctx.workflowEngine<br/>Workflow script engine"] pkg_workflow_worker_thread["workflow-worker-thread"] pkg_tool_workflow["tool-workflow"] pkg_lsp["lsp"] svc_lsp["ctx.lsp<br/>Language-server navigation seam"] pkg_lsp_local["lsp-local"] pkg_tool_lsp["tool-lsp"] svc_apiProxy["ctx.apiProxy<br/>Host API dispatch"] pkg_cordis_host_runner["cordis-host-runner"] svc_dynamicCordisRunner["ctx.dynamicCordisRunner<br/>Dynamic Cordis package host runner"] svc_cordisInspect["ctx.cordisInspect<br/>Dynamic Cordis inspect registry"] pkg_acp --> svc_approval pkg_agent --> svc_agents pkg_agent_default_model --> svc_agentDefaultModel pkg_agent_loop --> svc_agentLoop pkg_agent_presets --> svc_agentPresets pkg_api_gateway --> svc_typertGateway pkg_apiproxy --> svc_apiProxy pkg_approval --> svc_approval pkg_attachment --> svc_attachments pkg_attachment_local --> svc_attachments pkg_bash_local --> svc_shell pkg_bash_sandbox --> svc_shell pkg_code_runtime --> svc_codeRuntime pkg_code_runtime_worker --> svc_codeRuntime pkg_commands --> svc_commands pkg_compaction --> svc_compaction pkg_compaction_basic --> svc_compaction pkg_compaction_tool_result_pruner --> svc_toolResultPruner pkg_cordis_host_runner --> svc_cordisInspect pkg_cordis_host_runner --> svc_dynamicCordisRunner pkg_credentials --> svc_credentials pkg_credentials_local --> svc_credentials pkg_directory_picker --> svc_directoryPicker pkg_directory_picker_browse --> svc_directoryPicker pkg_directory_picker_native --> svc_directoryPicker pkg_e2b --> svc_e2b pkg_fs --> svc_fs pkg_fs_e2b --> svc_fs pkg_fs_local --> svc_fs pkg_fs_sandbox --> svc_fs pkg_goal --> svc_goals pkg_invariants --> svc_invariants pkg_jobs --> svc_jobs pkg_jobs_local --> svc_jobs pkg_llm --> svc_llm pkg_llm_deepseek --> svc_llm pkg_llm_pi_ai --> svc_llm pkg_llm_replay --> svc_llm pkg_lsp --> svc_lsp pkg_lsp_local --> svc_lsp pkg_message_feedback --> svc_messageFeedback pkg_modules --> svc_clientModules pkg_permission_presets --> svc_permissionPresets pkg_plan_mode --> svc_planMode pkg_pwsh_local --> svc_shell pkg_sandbox --> svc_sandbox pkg_sandbox_local --> svc_sandbox pkg_sandbox_policy --> svc_sandboxPolicy pkg_session --> svc_sessions pkg_session_persistence --> svc_sessionPersistence pkg_session_persistence_jsonl --> svc_sessionPersistence pkg_session_persistence_sqlite --> svc_sessionPersistence pkg_session_projection --> svc_sessionProjections pkg_session_projection_cache --> svc_sessionProjectionCache pkg_session_query --> svc_sessionQuery pkg_session_query_sqlite --> svc_sessionQuery pkg_session_reference --> svc_sessionReferenceResolver pkg_session_telemetry --> svc_sessionTelemetry pkg_session_telemetry_otel --> svc_sessionTelemetry pkg_session_title --> svc_sessionTitle pkg_session_title_all_prompts_llm --> svc_sessionTitle pkg_session_title_first_prompt_llm --> svc_sessionTitle pkg_settings --> svc_settings pkg_settings_file --> svc_settings pkg_shell --> svc_shell pkg_shell_env --> svc_shellEnv pkg_skill --> svc_skills pkg_skill_badge --> svc_skills pkg_skill_filesystem --> svc_skills pkg_spill --> svc_spillStore pkg_spill_local --> svc_spillStore pkg_storage --> svc_storage pkg_storage_domain --> svc_storageDomain pkg_storage_json --> svc_storage pkg_storage_sqlite --> svc_storage pkg_subagent --> svc_subagents pkg_subagent_acp --> svc_subagents pkg_subagent_claude_code --> svc_subagents pkg_subagent_codex --> svc_subagents pkg_subagent_dsh_sdk --> svc_subagents pkg_subagent_fork_in_process --> svc_subagents pkg_subagent_spawn_in_process --> svc_subagents pkg_subprocess --> svc_subprocess pkg_subprocess_e2b --> svc_subprocess pkg_subprocess_local --> svc_subprocess pkg_system_prompt --> svc_systemPrompt pkg_terminal --> svc_terminals pkg_terminal_bash --> svc_terminals pkg_token_meter --> svc_tokenMeter pkg_tools --> svc_tools pkg_typert_registry --> svc_typert pkg_user_questions --> svc_userQuestions pkg_web --> svc_web pkg_web_fetch_http --> svc_web pkg_web_search_deepseek --> svc_web pkg_web_search_exa --> svc_web pkg_web_search_perplexity --> svc_web pkg_webserver --> svc_webServer pkg_workflow --> svc_workflowEngine pkg_workflow_worker_thread --> svc_workflowEngine pkg_workspace --> svc_workspaceRegistry svc_agentDefaultModel --> pkg_headless svc_agentDefaultModel --> pkg_host_apiproxy svc_agentLoop --> pkg_agent_spine_demo svc_agents --> pkg_acp svc_agents --> pkg_agent_loop svc_agents --> pkg_subagent_inprocess svc_apiProxy --> pkg_connection svc_approval --> pkg_tool_bash svc_approval --> pkg_tools svc_attachments --> pkg_host_runtime svc_attachments --> pkg_llm_pi_ai svc_clientModules --> pkg_hmr svc_codeRuntime --> pkg_tools svc_compaction --> pkg_compaction_basic svc_cordisInspect --> pkg_tool_cordis svc_credentials --> pkg_apiproxy svc_credentials --> pkg_llm_deepseek svc_credentials --> pkg_llm_pi_ai svc_directoryPicker --> pkg_apiproxy svc_dynamicCordisRunner --> pkg_tool_cordis svc_e2b --> pkg_fs_e2b svc_e2b --> pkg_subprocess_e2b svc_fs --> pkg_tool_fs svc_invariants --> pkg_agent svc_invariants --> pkg_agent_loop svc_invariants --> pkg_scope svc_invariants --> pkg_session svc_jobs --> pkg_tool_bash svc_jobs --> pkg_tool_jobs svc_jobs --> pkg_tool_subagent svc_jobs --> pkg_tool_terminal svc_llm --> pkg_agent_loop svc_llm --> pkg_compaction_basic svc_lsp --> pkg_tool_lsp svc_sandbox --> pkg_bash_sandbox svc_sandbox --> pkg_terminal_bash svc_sandboxPolicy --> pkg_bash_sandbox svc_sandboxPolicy --> pkg_fs_sandbox svc_sandboxPolicy --> pkg_terminal_bash svc_sessionPersistence --> pkg_agent_loop svc_sessionPersistence --> pkg_hooks_claude_code svc_sessionPersistence --> pkg_hooks_codex svc_sessionPersistence --> pkg_message_feedback svc_sessionPersistence --> pkg_session_query svc_sessionPersistence --> pkg_session_query_sqlite svc_sessionPersistence --> pkg_tool_bash svc_sessionProjectionCache --> pkg_host_apiproxy svc_sessionProjections --> pkg_host_apiproxy svc_sessionProjections --> pkg_session_title svc_sessionProjections --> pkg_tool_todo svc_sessionQuery --> pkg_session_reference svc_sessionQuery --> pkg_tool_session_query svc_sessions --> pkg_agent svc_sessions --> pkg_agent_loop svc_sessions --> pkg_invariants svc_sessions --> pkg_message_feedback svc_sessions --> pkg_session_persistence svc_sessions --> pkg_session_query svc_sessions --> pkg_session_query_sqlite svc_sessions --> pkg_subagent_inprocess svc_settings --> pkg_apiproxy svc_settings --> pkg_llm_deepseek svc_settings --> pkg_llm_pi_ai svc_shell --> pkg_hooks_claude_code svc_shell --> pkg_hooks_codex svc_shell --> pkg_tool_bash svc_shell --> pkg_tool_pwsh svc_shellEnv --> pkg_tool_bash svc_shellEnv --> pkg_tool_pwsh svc_skills --> pkg_tool_skill svc_spillStore --> pkg_spill_policy svc_storage --> pkg_storage_domain svc_storageDomain --> pkg_message_feedback svc_storageDomain --> pkg_workspace svc_subagents --> pkg_tool_ralph svc_subagents --> pkg_tool_subagent svc_subagents --> pkg_tool_subagent_control svc_subprocess --> pkg_bash_local svc_subprocess --> pkg_bash_sandbox svc_subprocess --> pkg_lsp_stdio svc_subprocess --> pkg_subagent_acp svc_subprocess --> pkg_subagent_claude_code svc_subprocess --> pkg_subagent_codex svc_subprocess --> pkg_terminal_bash svc_systemPrompt --> pkg_agent_loop svc_systemPrompt --> pkg_tool_fs svc_systemPrompt --> pkg_tool_terminal svc_systemPrompt --> pkg_tool_web svc_systemPrompt --> pkg_tools svc_terminals --> pkg_tool_terminal svc_tokenMeter --> pkg_compaction_basic svc_toolResultPruner --> pkg_compaction_basic svc_tools --> pkg_agent_loop svc_tools --> pkg_tool_ask_user svc_tools --> pkg_tool_bash svc_tools --> pkg_tool_cordis svc_tools --> pkg_tool_fs svc_tools --> pkg_tool_skill svc_tools --> pkg_tool_subagent svc_tools --> pkg_tool_terminal svc_tools --> pkg_tool_todo svc_tools --> pkg_tool_web svc_typert --> pkg_api_gateway svc_typert --> pkg_typert_loader svc_userQuestions --> pkg_tool_ask_user svc_web --> pkg_tool_web svc_webServer --> pkg_connection svc_webServer --> pkg_hmr svc_webServer --> pkg_modules svc_workflowEngine --> pkg_tool_ralph svc_workflowEngine --> pkg_tool_workflow svc_workspaceRegistry --> pkg_apiproxy svc_fs -. event gate .-> pkg_fs_observation_policy
| ctx 键 | 角色 | 所属包 | 实现 | 直接消费方 | 配套插件 | 说明 |
|---|---|---|---|---|---|---|
ctx.attachments | seam | attachment | attachment-local | host-runtime, llm-pi-ai | - | 宿主会在会话事件之前提交已接受的图片；提供方适配器将已授权的持久引用解析为提供方原生内容。 |
ctx.llm | seam | llm | llm-deepseek, llm-pi-ai, llm-replay | agent-loop, compaction-basic | - | 适配器注册提供方实现；agent loop（智能体循环）与压缩功能调用提供方无关的流服务。 |
ctx.tokenMeter | core | token-meter | - | compaction-basic | - | 拥有按会话隔离的回放折叠区；压力消费方共享不可变且带修订版本的测量结果。 |
ctx.toolResultPruner | core | compaction-tool-result-pruner | - | compaction-basic | - | 在摘要压缩前，通过可回放的单节点表层替换来改写过大的当前工具结果。 |
ctx.sessions | core | session | - | agent-loop, agent, session-persistence, session-query, session-query-sqlite, subagent-inprocess, invariants, message-feedback | - | 拥有仅追加的 Session 实例，并发出持久的会话事件流。 |
ctx.invariants | core | invariants | - | session, agent, scope, agent-loop | - | 配套子路径注册所属包本地的检查；该服务负责选择、唯一性、子 fiber，以及标明所属包的失败。 |
ctx.typert | core | typert-registry | - | typert-loader, api-gateway | - | 插件直接或通过 dsh-typert-loader 注册实时 zod 贡献；API 网关消费调用描述符和提供方，其他运行时消费方则在各自边界查询 schema 与反射元数据。 |
ctx.typertGateway | core | api-gateway | - | - | - | 将生成的 Remote 描述符与实时 Cordis 服务关联，解析已注册的身份，并通过共享的 Connection RPC 载体提供一元调用。 |
ctx.sessionPersistence | seam | session-persistence | session-persistence-jsonl, session-persistence-sqlite | agent-loop, tool-bash, hooks-claude-code, hooks-codex, session-query, session-query-sqlite, message-feedback | - | 各后端持久化同一套 SessionEvent 词汇；应用在组合时选择后端。 |
ctx.settings | seam | settings | settings-file | llm-deepseek, llm-pi-ai, apiproxy | - | 插件注册命名空间 schema 并解析分层值；提供方存储原始文档。LLM（大语言模型）适配器在用户分区下将其入口配置注册为组合基础；Web 网关提供经过脱敏的分层描述符，并写入用户层。 |
ctx.credentials | seam | credentials | credentials-local | llm-deepseek, llm-pi-ai, apiproxy | - | 配置携带对机密信息的引用；提供方拥有实际值。消费方按操作解析，因此轮换后的凭据会在紧接着的下一次请求中生效；Web 网关提供不含实际值的视图和只写存储。 |
ctx.sessionTelemetry | seam | session-telemetry | session-telemetry-otel | - | - | 该 seam 捕获会话记录、进行脱敏并交给一个后端；没有其他组件消费该服务，其输出会离开当前进程。 |
ctx.storage | seam | storage | storage-json, storage-sqlite | storage-domain | - | 各后端以不同名称并列注册；数据形态（领域优先）挂载到枢纽上，并将类型化操作转换为不透明的 KV 单元原语。 |
ctx.storageDomain | core | storage-domain | - | workspace, message-feedback | - | 等待所有已配置后端就绪，然后将领域形态发布为一个受生命周期约束的服务，用于类型化持久状态。 |
ctx.messageFeedback | core | message-feedback | - | - | - | 拥有本地逐 assistant 消息反馈、生命周期与目标校验、逐条目 compare-and-set 及 Host 一元 Remote 契约，且不进入 Session 历史或遥测。 |
ctx.workspaceRegistry | core | workspace | - | apiproxy | - | 通过领域设施拥有带 WorkspaceId 品牌类型的记录；稳定的 sessionIds 账户驱动 Host RPC 与 GUI 投影。 |
ctx.sessionQuery | seam | session-query | session-query-sqlite | session-reference, tool-session-query | - | 该接口提供精确读取、过滤和追踪；具体后端还提供全文协调、排序、摘要片段和游标世代，而模型消费方负责工作区权限与不含游标的渲染。 |
ctx.sessionReferenceResolver | core | session-reference | - | - | - | 将当前表层中有界的对话快照投影为持久但不可信的消息上下文；Host 适配器负责提及语法。 |
ctx.sessionTitle | seam | session-title | session-title-first-prompt-llm, session-title-all-prompts-llm | - | - | 负责确定性回退、最新标题折叠区，以及唯一的可选异步提供方注册。 |
ctx.systemPrompt | core | system-prompt | - | agent-loop, tools, tool-fs, tool-terminal, tool-web | - | 为每个步骤收集提示词各部分和面向模型的工具 schema。 |
ctx.tools | core | tools | - | agent-loop, tool-ask-user, tool-bash, tool-cordis, tool-fs, tool-terminal, tool-skill, tool-subagent, tool-todo, tool-web | - | 注册能力，负责 Code Mode 传输，并让调用依次经过策略前处理、单调守卫、环绕分派、策略后处理和最终结果观测。 |
ctx.userQuestions | seam | user-questions | - | tool-ask-user | - | UI 前端提供当前生效的人工回答提供方；tool-ask-user 在提供方无关的 ask() promise 上暂停工具调用。 |
ctx.planMode | core | plan-mode | - | - | - | 折叠已记录的计划／模式状态，在轮次边界刷新用户选择，渲染由部署方拥有的指导信息，注册 /plan，并在状态转换期间保持计划退出 schema 稳定。 |
ctx.agentPresets | core | agent-presets | - | - | - | 在受信任根目录与用户创作根目录上发现 preset 目录，并在创建期把一份 preset cordis.yml 挂载到 agent 作用域之下，拒绝始终未激活或向根服务 realm 发布服务的行。 |
ctx.commands | core | commands | - | - | - | 插件注册直接面向人的命令，而不会把调用发送给模型。 |
ctx.sessionProjections | core | session-projection | - | tool-todo, session-title, host-apiproxy | - | 各领域注册由状态驱动的折叠单元；主动驱动过程维护每个会话的水位状态，api-proxy 提供基线并推送发生变化的值。 |
ctx.sessionProjectionCache | core | session-projection-cache | - | host-apiproxy | - | 按会话持久保存投影单元状态的检查点（节流检查点，以及轮次／结束／分离时的必选检查点），并提供冷读取阶梯：缓存行加持久化尾部回放，因此列表读取永远不需要加载完整日志。 |
ctx.skills | seam | skill | skill-badge, skill-filesystem | tool-skill | - | 合并提供方的 skill（技能）目录；tool-skill 渲染会话前缀目录，并加载完整的 skill 正文。 |
ctx.agents | core | agent | - | agent-loop, acp, subagent-inprocess | - | 拥有实时 Agent 句柄、创建／恢复工厂 seam，以及进程本地的发起方传播。 |
ctx.agentDefaultModel | core | agent-default-model | - | headless, host-apiproxy | - | 通过 settings 分层默认 ModelSelection，让直接入口与 Host 支撑的 Agent 入口共享同一个状态所有者。 |
ctx.agentLoop | bundle | agent-loop | - | agent-spine-demo | - | 唯一的具体循环插件；扩展包依赖 dsh-agent 的事件和服务，而不依赖此包。 |
ctx.goals | core | goal | - | - | - | 从会话日志折叠带修订版本的目标状态，并将实时延续激活保留在进程本地。 |
ctx.e2b | core | e2b | - | fs-e2b, subprocess-e2b | - | 拥有一个共享的 E2B SDK 句柄、远程工作目录和最终沙箱处置，使两个基础 E2B 提供方处于同一个 Linux 运行时中。 |
ctx.subprocess | seam | subprocess | subprocess-local, subprocess-e2b | bash-local, bash-sandbox, terminal-bash, lsp-stdio, subagent-acp, subagent-codex, subagent-claude-code | - | Bash 执行器、PTY shell 后端、LSP Host，以及进程外 ACP、Codex 和 Claude Code subagent 后端都通过 ctx.subprocess 执行 spawn；该服务负责进程坐标、进程树／会话生命周期、stdio 处置、终端机制和 kill 升级。 |
ctx.shell | seam | shell | bash-local, bash-sandbox, pwsh-local | tool-bash, tool-pwsh, hooks-claude-code, hooks-codex | - | 面向模型的 shell 工具和钩子桥接消费此 seam；沙箱、远程或 PowerShell 执行器可以替换 bash-local，而无需改动这些消费方。 |
ctx.shellEnv | core | shell-env | - | tool-bash, tool-pwsh | - | 插件声明限定于 effect 作用域的 DSH_* 事实；每个 shell 工具在每次执行时收集一份可信快照，其执行器据此重建命名空间。 |
ctx.terminals | seam | terminal | terminal-bash | tool-terminal | - | 注册表负责精确到 Agent 的会话身份和清理；后端负责终端机制，tool-terminal 则提供限定于所有者作用域的模型接口。 |
ctx.sandbox | seam | sandbox | sandbox-local | bash-sandbox, terminal-bash | - | 消费方交出即将执行 spawn 的确切 argv；与宿主共享文件系统和内核的后端按每次调用的策略包装该 argv，并报告强制执行情况。 |
ctx.sandboxPolicy | core | sandbox-policy | - | bash-sandbox, fs-sandbox, terminal-bash | - | 统一保存部署默认模式和工作区根目录；只有沙箱执行器和提供方读取该服务（工具层使用它同时导出的纯 sandbox/mode 折叠区）。两类强制执行组件都读取该服务，因此 bash 与 fs 不会限制到不同的根目录。 |
ctx.approval | seam | approval | acp | tools, tool-bash | - | 一次性权限决策通过 approval/request waterfall（瀑布式事件）分派；回答方是监听器（即 ACP 为自身 agent 提供的桥接），没有回答方时以 unavailable 关闭失败。 |
ctx.permissionPresets | core | permission-presets | - | - | - | 面向用户的预设表（workspace-write／danger-full-access），将沙箱模式与审批策略选项组合在一起；一次切换会写入一个 permission/preset 事件，并贯通到两个选项事件。 |
ctx.codeRuntime | seam | code-runtime | code-runtime-worker | tools | - | 使用 Host 提供的异步绑定运行一段由模型编写的程序；各后端采用不同的基础环境和语言（工具注册表在 Code Mode 下消费该服务）。 |
ctx.fs | seam | fs | fs-local, fs-sandbox, fs-e2b | tool-fs | fs-observation-policy | tool-fs 通过 ctx.fs 执行读取／写入／编辑；fs-sandbox 按共享沙箱模式限制变更；fs-observation-policy 通过 fs/* 事件门禁贡献基于观测状态的检查。 |
ctx.compaction | seam | compaction | compaction-basic | compaction-basic | - | 基础后端消费步骤后的压力事件和请求错误恢复事件；不存在面向模型的压缩工具。 |
ctx.subagents | seam | subagent | subagent-spawn-in-process, subagent-fork-in-process, subagent-acp, subagent-codex, subagent-claude-code, subagent-dsh-sdk | tool-subagent, tool-subagent-control, tool-ralph | - | 提供方实现传输；该服务还负责可选的、基于 Activation 的延续编排，tool-subagent 选择一次性或可延续委派，tool-subagent-control 传递后续消息，而 tool-ralph 要求一条全新的结构化输出路由。 |
ctx.jobs | seam | jobs | jobs-local | tool-bash, tool-terminal, tool-subagent, tool-jobs | - | 生产方（后台 bash、PTY 发送和 subagent 委派）登记正在运行的工作；tool-jobs 是面向模型的控制器，用于读取、列出和终止这些工作；jobs-local 是进程本地注册表。 |
ctx.web | seam | web | web-search-exa, web-search-perplexity, web-search-deepseek, web-fetch-http | tool-web | - | 搜索和抓取提供方注册到同一个 ctx.web seam；tool-web 负责稳定的面向模型名称。 |
ctx.spillStore | seam | spill | spill-local | spill-policy | - | 后端保存过大的工具文本，并返回面向模型的定位信息和取回提示；spill-policy 是 tools/post-execute 消费方，负责决定何时 spill。 |
ctx.directoryPicker | seam | directory-picker | directory-picker-native, directory-picker-browse | apiproxy | - | 带判别标记的交互能力：原生后端在 Host 显示设备上打开一个操作系统选择器，浏览后端为应用内浏览器提供列表与创建原语；双端后端通过其浏览器侧填充 ui-workspace 目录流程的 slot（不通过协议发布）。 |
ctx.webServer | core | webserver | - | connection, modules, hmr | - | 普通的 node:http 载体：具名路由注册表、索引转换 tap，以及静态 dist 回退；Web 传输插件注册自己的路由。 |
ctx.clientModules | core | modules | - | hmr | - | 通过增量 dsh.client 扫描组合 DSH_BOOT 入口图，提供插件组合包，并通知重建／图变更订阅方。 |
ctx.workflowEngine | seam | workflow | workflow-worker-thread | tool-workflow, tool-ralph | - | 每个上下文使用一个引擎，与 bash 相同，且没有具名提供方注册表；通用工作流与固定 Ralph 消费方启动运行，其中的 agent() 调用通过 ctx.subagents 扇出。 |
ctx.lsp | seam | lsp | lsp-local | tool-lsp | - | 提供方注册与选择，加上恰好四种操作的标准化查询执行；该 seam 不提供协议逃生口，后端必须转换为标准化请求和结果。 |
ctx.apiProxy | core | apiproxy | - | connection | - | 与传输无关的 Host 网关接口：它分派浏览器 API 调用，每条打开的 Host 流自行订阅转发事件，而不是由广播方法向其推送。 |
ctx.dynamicCordisRunner | core | cordis-host-runner | - | tool-cordis | - | 拥有内存定义注册表、Host 半的 vm 沙箱和 request-run 往返流程；浏览器页面通过其 Remote 命名空间在线访问同一服务。 |
ctx.cordisInspect | core | cordis-host-runner | - | tool-cordis | - | 注册 Host inspect 提供方、镜像 Client 提供方 manifest，并通过动态 Cordis 传输路由 Client 查询。 |
维护模式：混合模式。服务从 Cordis 声明中发现；接口、实现和消费方角色在 scripts/gen-doc-graphs.ts 中分类，并设有完整性守卫。
Agent 轮次与步骤生命周期
Section titled “Agent 轮次与步骤生命周期”此时序图是 architecture.md 的配套图示。持久的回放事实保存在 session/event 中，实时控制与状态则保存在 agent/* 中。
sequenceDiagram
participant User
participant Agent
participant Driver
participant Hooks as hook listeners
participant Prompt as ctx.systemPrompt
participant LLM as ctx.llm
participant Tools as ctx.tools
participant Session
participant SDK as UI or SDK listener
User->>Agent: followup(content)
Agent-->>SDK: <code>agent/inbox/spliced</code>
Agent-->>SDK: <code>agent/inbox/inserted</code> { message }
Agent->>Driver: queued work wakes driver
Driver-->>SDK: <code>agent/status</code> running
Driver->>Session: <code>turn/start</code>
Note over Agent,Driver: claim pending next-step input plus one queued prompt
Driver-->>SDK: <code>agent/inbox/spliced</code> pure deletion
Driver-->>SDK: <code>agent/inbox/claimed</code> { message, turn } per message
Driver->>Hooks: <code>agent/pre-step</code> waterfall
Hooks-->>Driver: authoritative reject or enter(messages)
alt proposed step rejected or pre-step failed
Driver-->>Driver: claimed batch stays removed, the open turn spends no step
else enter proposed step
Driver->>Session: <code>step/start</code>
Driver->>Session: <code>user/message</code> per entered message
Driver->>Prompt: <code>system-prompt/assemble</code> waterfall
Driver->>LLM: <code>agent/request</code> waterfall, then <code>llm/stream</code> waterfall
LLM-->>Driver: StreamChunk*
Driver->>Session: <code>assistant/chunk</code>*
Session-->>SDK: <code>session/event</code> <code>assistant/chunk</code>*
alt final adapter or terminal in-band request failure
Driver->>Session: <code>step/end</code>
Driver->>Hooks: <code>agent/request-error</code> waterfall
Hooks-->>Driver: return retry action or preserve the original error
else model request succeeded
Driver->>Session: <code>assistant/message</code>
Driver->>Tools: classify pending call by executionMode
loop barriers and bounded rolling pool, reclassify before start
opt call starts
Driver->>Session: <code>tool/call</code>
Driver->>Tools: ordered pre, concurrent execute
Tools-->>Session: tool-owned events when applicable
end
opt next model-order result ready
Driver->>Tools: ordered post
Driver->>Session: <code>tool/result</code>
end
end
Driver->>Session: <code>step/end</code>
opt natural stop and next-step inbox empty
Driver->>Hooks: <code>agent/turn-stopping</code> serial terminal checkpoint
end
opt next-step input is pending
Driver-->>Driver: claim pending next-step input
Driver-->>SDK: <code>agent/inbox/claimed</code> { message, turn } per message
Driver->>Hooks: <code>agent/pre-step</code> waterfall
Hooks-->>Driver: authoritative reject or enter(messages)
end
end
end
Driver->>Session: <code>turn/end</code>
Driver-->>SDK: <code>agent/status</code> idle
assistant/message 事件会记录每次成功的提供方调用，包括返回空内容或以 max-tokens 结束的调用。空内容不会进入派生历史，但该持久事件仍会保留用量，并通过 sourceEventSeqs 精确列出对应的 assistant/chunk 事件，包括显式空列表。
dsh-compaction-basic 在派生请求之前通过 agent/pre-step 处理压力，而 agent/request-error 仅用于规范的上下文溢出。任一触发条件满足后，系统都会先执行可选的工具结果剪枝，再选择摘要。恢复发生在失败步骤结束之后、失败轮次结束之前；只有当剪枝或摘要生成推进了 surface replacement generation 时，系统才会开启一个全新的重试轮次，否则仍以原始请求错误为准。
以返回的 agent/pre-step 决策为准；通过包装 next() 的监听器会保留下游消息，除非有意替换这些消息。steering（中途引导）和注入的上下文在后续的认领操作取得其下一步骤批次后，会经过同一 waterfall（瀑布式事件）。
需要可回放 transcript（文本记录）数据的 SDK 用户应当消费 session/event；agent/* 是用于队列与状态、提示词拦截、请求构造、steering、继续执行和错误处理的实时协调接口。
维护模式：英文源文件包含人工维护的 Mermaid 时序图，并由生成器写出；本中文文件作为经评审对侧通过双语配对维护。确切的事件签名位于生成的 Cordis 目录中。
工具执行流水线
Section titled “工具执行流水线”此图展示策略、钩子、沙箱、文件系统守卫、结果重写、最终结果观察和 UI 渲染在不改变循环的情况下何时运行。tools/pre-execute waterfall（瀑布式事件）首先运行，随后是单调守卫，然后运行 tools/execute 和 tools/post-execute waterfall；这三个 waterfall 可以改写一次调用。由定义自身控制的 finalizeContent 和 tools/result 在此之后运行。
flowchart TD model["Assistant message contains tool-call block"] toolCall["Session event: <code>tool/call</code><br/>logged before execution"] presentCall["UI pending card<br/>presentCall(args)"] pre["<code>tools/pre-execute</code> waterfall<br/>hooks, permission, sandbox"] guards["Registered monotonic guards<br/>deny or abstain; identity protected"] denied["denied or approval refused<br/>tool body skipped"] approval["<code>ctx.approval</code> one-shot prompt<br/>absent or unanswerable: deny"] around["<code>tools/execute</code> waterfall<br/>timeout, retry, metrics (around dispatch)"] toolBody["Registered tool execute() body"] fsGate["<code>fs/write-intent</code> or <code>fs/edit-intent</code><br/>tool-fs mutations only"] owned["Tool-owned session events<br/><code>todo/write</code>, <code>fs/observed</code>, <code>hook/invoked</code>, <code>hook/result</code>, <code>tool/code-dispatch</code>"] post["<code>tools/post-execute</code> waterfall<br/>accept, block, replace, add context"] normalized["Registry outer normalization<br/>pipeline/result snapshot throws become isError"] finalize["ToolDefinition.finalizeContent<br/>last content-only invariant"] final["<code>tools/result</code> synchronous notification<br/>frozen authoritative outcome"] context["Active-batch additionalContexts FIFO<br/>injected user/message after recorded tool results"] toolResult["Session event: <code>tool/result</code><br/>single model-facing outcome"] allResults["Tool batch settled<br/>recorded tool/result events complete"] presentResult["UI completed card<br/>presentResult(args, result)"] model --> toolCall toolCall --> presentCall toolCall --> pre pre -->|allow| guards guards -->|allow| around guards -->|deny| denied guards -.->|throw| normalized around --> toolBody pre -->|deny| denied pre -->|ask| approval approval -->|allowed-once| guards approval -->|rejected, cancelled, unavailable| denied approval -.->|throw| normalized denied --> post pre -.->|throw| normalized toolBody --> fsGate fsGate --> toolBody toolBody --> owned toolBody --> around around --> post around -.->|wrapper throws| normalized post -.->|throw| normalized post --> finalize normalized --> finalize finalize --> final final --> toolResult toolResult --> presentResult toolResult --> allResults allResults --> context
文件系统的先读后编辑检查位于 tool-fs 之下，通过 fs/* 事件实现。通用的前置／后置 waterfall 承载钩子与审批策略；ctx.approval 在单调守卫之前处理询问，而不得重新排序的所有者策略仍作为已注册的守卫。超时等环绕分发关注点对 tools/execute 进行包装。注册表会对候选结果进行无损快照；如果快照失败，则会先将失败规范化，之后再由可见定义中已随快照固定的 finalizeContent 回调强制执行其同步且仅限内容的不变式。随后，tools/result 会观察不可变、可由 JSON 无损表示的结果。这样一来，钩子便可跨越不同工具系列，而无需让工具与某个策略服务耦合。Code Mode 会将保留的 run_code 传输及其序列化子调用都送入流水线；子调用携带父级 token、记录 tool/code-dispatch、将拒绝呈现为具有约束力的驳回，并省略 additionalContexts，以保持调用与结果相邻。
维护模式：英文源文件包含人工维护的 Mermaid 流程图，并由生成器写出；本中文文件作为经评审对侧通过双语配对维护。确切的工具 schema 与事件签名位于生成的目录中。