运行与编排
核心子系统即 packages/core，包含每个组合都会启动的包：事件溯源的会话日志、系统提示词组装、工具注册表、agent（智能体）类型，以及驱动它们的具体循环。本页说明 agent/agent-loop 这对包所声明的内容：agent 如何被创建与拥有，以及 Agent 句柄的投递、取消与拦截约定；本页还说明每个子系统都遵循的两个类型模式。该组的专属页面与目录其余部分见子系统 README。
scope 包提供身份、载体与作用域层词汇，使同一注册上下文同时表达每个 agent（智能体）的可见性和共享生命周期所有权。它是库原语，而不是 Cordis 服务；生命周期设计理由由 agent-scope 运行时设计 Agent Note规定，注册表层决策由共享存储 Agent Note规定，可调用 API 与过滤语义则由包 README规定。
源码：packages/core/scope/src/index.ts 与 packages/core/scope/src/store.ts。
dsh-invariants 是面向包自有运行时不变式检查的可配置注册表服务（ctx.invariants）。它是一个 support 组的包，不是三包能力 seam，也不属于 agent loop（智能体循环）主干：注册表拥有选择逻辑、名称保留、子 fiber 生命周期和归因到包的失败，而每个工作区包发布一个 ./invariant 配套插件，以自己确切的 npm 包名注册检查。检查可以断言什么（权威事件流或可变数据，绝不是服务或方法是否存在）是 AGENTS.md 中的运行时不变式约定；注册表设计由不变式服务 Agent Note规定。
源码：packages/runtime-diagnostics/invariants/src/index.ts
dsh-session 的内存事件溯源模型。Session 是一份由类型化 SessionEvent 组成的仅追加日志，是 agent（智能体）完整交互历史的唯一真源。LLM（大语言模型）消息历史从日志派生而来，从不单独存储；回放即从同一组事件重新派生。日志如何实现持久化（持久化 seam、后端、崩溃恢复）是兄弟文档 persistence.md 的关注点。
源码：packages/core/session/src/types.ts
本文定义逻辑会话语料库的查询词汇；当 live 数据存在时，该语料库优先使用 live 数据。Service Definition 包负责精确读取、来源优先级、关系追踪、语义提取，以及与提供方无关的过滤器；SQLite 提供方负责具体全文索引的生命周期。
源码：packages/session-query/session-query/src/types.ts
结构化的跨会话引用请求与准备后的消息上下文。包约定 定义规范 URI、当前表层投影、标签安全的 JSON 与字节保留、稳定错误和不可信的模型提示词。宿主适配器使用这些类型，而不会把各自 UI 的提及语法传入 agent（智能体）核心。
来源：packages/context/session-reference/src/types.ts
@deepseek-ai/dsh-session-title 所拥有的持久、后写覆盖的标题状态与可选异步提供方词汇。共享 LLM（大语言模型）辅助组件负责精确的辅助请求记录。各包 README 负责时序、回退、失败与 fork 行为；生成的持久化日志事件目录负责完整的事件声明。
源码：packages/session/session-title/src/index.ts、packages/session/session-title-llm/src/index.ts
会话投影 seam 是一项能力 seam：领域 host 插件经由它向客户端载体供给按会话的日志派生状态的当前全量值；三方分别是 Service Definition 与注册表（dsh-session-projection，ctx.sessionProjections）、领域贡献方（每个领域注册一个纯单元）与载体（dsh-host-apiproxy 的历史尾页与 session/projection 推送帧）。它是一项可选能力，不属于 agent loop（智能体循环）主干。框架负责驱动，领域负责计算：注册表只订阅一次 session/event，并把每个已提交事件折叠进每个单元；领域不持有任何订阅，客户端也从不折叠领域事件——它们收到的是成品值。设计权威：session-projection RFC；驱动、缓存与变更流约定：包 README。
源码：packages/session/session-projection/src/index.ts
事件日志的持久性 seam。session.md 描述了内存中的 Session：仅追加的 SessionEvent 日志即为真源。本页描述如何使该日志持久化：抽象的 SessionPersistence 服务、它的后端、flush 检查点、崩溃恢复，以及随日志一同存储的元数据头。日志承载的事件词汇在生成的持久化日志事件目录中逐项列举。
该 seam 是一个能力 seam：一个抽象服务（dsh-session-persistence，ctx.sessionPersistence）在现有 SessionEvent 上定义 locate/create/append、可复用的 Session 准备流程、逻辑 load/inspect、物理后缀读取，以及轻量的 list/snapshot 观察——没有平行的持久化事件类型——以及两个实现同一约定的可互换后端。见 session-persistence Agent Note。
spill 存储 seam 是一项能力 seam，它持久保存工具的超大文本，并返回面向模型的定位符与检索指引；该能力拆分到三个包：Service Definition（dsh-spill，ctx.spillStore）、Service Provider（dsh-spill-local，宿主文件系统中会话作用域的私有文件）和 Consumer（dsh-spill-policy，tools/post-execute 策略）。spill 是一项可选能力，不属于 agent loop（智能体循环）主干，因此其词汇记录在此处，而不在 core.md 中。预览机制仍归 dsh-output-retention 所有；该 seam 只保存策略交给它的最终文本。
源码：packages/spill/spill/src/types.ts
对外的会话上报拆分为一项能力 seam：Service Definition 与捕获协调器（dsh-session-telemetry，ctx.sessionTelemetry）拥有捕获点、固定分片投影、session-telemetry/record 脱敏 waterfall（瀑布式事件）、handoff 游标与最小后端约定；部署方加载的 Service Provider（dsh-session-telemetry-otel）则是原样配置的 OpenTelemetry JS SDK 日志流水线。它是一项可选能力，不属于 agent loop（智能体循环）主干，这里也没有任何内容会进入模型请求。边界公理（harness 的职责止于 emit()；批处理、重试、排队与丢失策略都属于上报 SDK）连同被否决的替代方案，均已在复活 Agent Note中定案；捕获点、游标与投影的约定见 Service Definition README。
源码：packages/session/session-telemetry/src/index.ts
packages/llm 提供对话与流式输出类型：每个请求和持久历史共用的 Message/ContentBlock 变体、完整组装的模型请求、原始 StreamChunk 协议、每个适配器必须实现的适配器约定（adapter contract），以及共享的 assembler。核心包在每个轮次持有并记录这些值；本页声明它们。
源码：packages/llm/llm/src/types.ts
@deepseek-ai/dsh-token-meter 公开一个独立的回放快照，用于表示请求压力与按位置计算的表层定价。logRevision 表示生成该计量中每个字段时所消费的持久事件数量。
来源：packages/llm/token-meter/src/types.ts
system-prompt 包负责管理提示词贡献者与一次组装调用之间交换的数据。该包的 README 记录注册、排序、作用域与渲染行为；本页记录各插件实现或传递的确切跨包类型。
源码：packages/core/system-prompt/src/index.ts。
压缩 seam 是一个能力 seam，与 bash 一样分为 Service Definition（dsh-compaction，ctx.compaction）、Service Provider（例如 dsh-compaction-basic 后端）和面向用户的 Consumer（dsh-command-compact）。压缩是一项可选能力，不属于 agent loop（智能体循环）主干，因此其词汇定义在此而非 core.md 中。基于 tokenizer 或模板的后端是实现同一接口的兄弟包。与 bash 不同，该接口必然依赖 dsh-session 和 dsh-llm：其动词作用于 agent 所有的 Session，而其持久摘要事件使用 ContentBlock 词汇（见压缩能力 seam Agent Note）。
源码：packages/compaction/compaction/src/types.ts
dsh-tools 的工具流水线。core.md 介绍了核心包共用、用于编写流水线的类型 ToolDefinition；面向模型的 ToolSchema 协议类型与模型请求一起声明。本页记录 ToolDefinition 的每个字段、用于构建它的类型化 schema DSL、带守卫的执行类型和 UI 展示类型。
源码：packages/core/tools/src/index.ts · packages/core/tools/src/schema.ts · packages/core/tools/src/presentation.ts
bash 执行 seam 分为 Service Definition（dsh-shell，ctx.shell）、Service Provider（dsh-bash-local 与 dsh-bash-sandbox）和 Consumer（dsh-tool-bash，即 bash schema）。通用后台任务的 job id、所有权与控制位于 jobs.md；本 seam 返回一个不含任务概念的进程句柄。原始进程组机制封装在子进程 seam之后。
源码：packages/shell/shell/src/types.ts
子进程 seam 分为 Service Definition（dsh-subprocess，ctx.subprocess）与 Service Provider（dsh-subprocess-local）；它的 Consumer 是其他能力 seam 与进程外后端：bash 执行器家族使用收集模式的批量输出，LSP 使用原始协议管道，PTY 后端使用终端原语，ACP（Agent Client Protocol）subagent 后端则使用通过管道传输的 ndjson，并让 stderr 采用 inherit。该 seam 拥有受管的 DSH_* 环境命名空间、共享的凭据清除（scrubbedParentEnv）与 CollectedOutput 形状；dsh-shell 重导出这套词汇，使 bash 消费方保持单一导入入口。
源码：packages/subprocess/subprocess/src/types.ts 与 packages/subprocess/subprocess/src/index.ts
PTY 后端、ctx.terminals 与面向模型的消费方共享的类型。持久 PTY Agent Note 负责记录决策依据；本页记录来自 packages/terminal/terminal/src/types.ts 的跨包词汇。
长时间运行的生产方、ctx.jobs 与任务控制命令共用的类型。运行时 Agent Note 负责设计；本页记录 packages/jobs/jobs/src/types.ts 中的确切字段和变体。
可选的文件系统能力由四个部分组成：dsh-fs 拥有 ctx.fs 以及带可选守卫的原子文本操作；dsh-fs-local 实现本地磁盘后端；dsh-fs-observation-policy 记录观测到的存在或缺失状态，并通过事件（而非服务）添加新鲜度规则；dsh-tool-fs 直接执行面向模型的 read/write/edit 调用并渲染窗口。它位于 agent loop（智能体循环）主干之外；替换后端不会改变策略或工具 schema。
dsh-fs-observation-policy 是可选插件。没有该插件时，FileSystem 服务定义、一个提供方和 dsh-tool-fs 消费方组成完整且不受约束的文件系统 seam：write 无条件创建或覆盖，edit 无条件替换字面文本。策略插件通过裁决 fs/* waterfall（瀑布式事件）来改变这些操作。移除该插件不会破坏工具，因为工具调用 ctx.fs 并分发事件，而不调用策略方法。加载了 dsh-tool-fs 的部署也应加载 dsh-fs-observation-policy，使默认行为为「先读后写/编辑」。
提供方源码：packages/fs/fs/src/types.ts 与 packages/fs/fs/src/index.ts。策略源码：packages/fs/fs-observation-policy/src/types.ts。读取渲染源码：packages/fs/tool-fs/src/read-render.ts。
LSP seam 是一个能力 seam：它在单一 ctx.lsp 服务上公开语义代码导航，并拆分到多个包：Service Definition（dsh-lsp，ctx.lsp + 提供方注册表）、通用 Service Provider（dsh-lsp-stdio，经过配置的 stdio 语言服务器宿主）和 Consumer（dsh-tool-lsp，即 lsp 工具 schema）。LSP 是一项可选能力，不属于 agent loop（智能体循环）主干，因此其词汇定义在此而非 core.md 中。更换提供方不会改变模型请求导航的方式。
源文件：packages/lsp/lsp/src/types.ts
代码执行 seam 是一个能力 seam：其 Service Definition（dsh-code-runtime，ctx.codeRuntime）使用宿主提供的异步绑定运行一段模型编写的程序，并报告其打印内容与返回值。代码执行是一项可选能力，不属于 agent loop（智能体循环）主干，因此其词汇定义在此而非 core.md 中。各后端的执行基底与源语言不同，这两项均为服务上的只读描述符；worker-thread Service Provider 与工具注册表 Consumer 的约定见 Code Mode 基础设计 和类型化返回约定。
源码：packages/code-runtime/code-runtime/src/types.ts
Web 访问 seam 是一个能力 seam，在同一个 ctx.web 服务上横跨两项操作（search 与 fetch），并拆分到多个包：Service Definition（dsh-web，ctx.web + 提供方注册表）、Service Provider（dsh-web-search-exa、dsh-web-search-perplexity、dsh-web-search-deepseek、dsh-web-fetch-http）与 Consumer（dsh-tool-web，即 web_search/web_fetch 工具 schema）。Web 是一项可选能力，不属于 agent loop（智能体循环）主干，因此其词汇定义在此而非 core.md 中。更换 search 提供方不会改变模型提交查询的方式，更换 fetch 提供方也不会改变模型请求 URL 的方式。
源码：packages/web/web/src/types.ts
skill（技能）能力族 包含 Service Definition（dsh-skill，ctx.skills）、本地 Service Provider（dsh-skill-filesystem）、可选的随包徽章提供方（dsh-skill-badge）和 Consumer（dsh-tool-skill）。注册表在其宿主层与各 scope 层之间合并各提供方的目录；提供方贡献本地或随包 skill；Consumer 拥有初始目录和替换目录，以及面向模型的 skill 工具。skill 是可选的指令而非会话事件，因此其词汇定义在此处而非 core.md。
源码：packages/skill/skill/src/index.ts、packages/skill/skill-filesystem/src/index.ts、packages/skill/skill-badge/src/index.ts 与 packages/skill/tool-skill/src/index.ts。
工作流 seam 允许 agent（智能体）运行由模型编写、会启动 subagent 的编排脚本。与 subagent 一样，它是一项可选能力，不属于 agent loop，因此其类型和操作记录在此处，而非 core.md。与 bash 一样，每个上下文只允许一个引擎实现提供 ctx.workflowEngine；没有命名提供方注册表（第二个引擎通过插件配置替换第一个，而不与它同时运行）。
Service Definition：dsh-workflow（ctx.workflowEngine + 下文词汇）。Service Provider 是 dsh-workflow-worker-thread（一个 node:worker_threads 引擎——每个 run 一个 worker，脚本的 vm 上下文位于其中）；面向模型的 Consumer 是 dsh-tool-workflow。提案与设计理由见 dynamic-workflows Agent Note。
源码：浏览器安全词汇位于 packages/workflow/workflow/src/types.ts，Host 请求与活跃运行句柄位于 runtime-types.ts。
subagent seam 让一个 agent（智能体）将工作委派给子 agent。与 bash 一样，它是一项可选能力，不属于 agent loop（智能体循环），因此其类型定义在此而非 core.md 中。它不同于其他能力 seam，因为同一上下文中可共存多个提供方实现，并按名称注册（ctx.subagents），而 bash 只允许一个执行器。该注册表遵循 LLM（大语言模型）适配器注册表，而非单服务的 bash 执行器。
Service Definition：dsh-subagent（ctx.subagents + 下文词汇）。Service Provider 是六个兄弟包：dsh-subagent-spawn-in-process、-fork、-acp、-codex、-claude-code、-dsh-sdk；面向模型的 Consumer 包括 dsh-tool-subagent（按提供方委派）、dsh-tool-subagent-control（可选的全局 send_message、interrupt_agent 与 list_agents 控制工具）和 dsh-tool-subagent-report（可选的 child 作用域 report 返回通道）。同一个 ctx.subagents 服务通过内部激活管理器负责可继续子 agent 编排，并直接基于会话存储和可选的会话持久化提供只读的 child 与后代发现。产品提供方设计理由见 Codex 与 Claude Code Agent Note；通用 seam 的设计理由见 subagent Agent Note、可继续 subagent Agent Note、report 工具 Agent Note、持久化目录 Agent Note、列表身份投影 Agent Note和服务合并 Agent Note。
源码：packages/subagent/subagent/src/types.ts、packages/subagent/subagent/src/index.ts和 packages/subagent/subagent/src/continuation.ts
dsh-user-approval 的用户审批 seam 回答一个问题：这个具体操作是否可以继续？它拥有共享的请求/结果词汇、ctx.approval 分发服务、approval/request 应答者 waterfall（瀑布式事件）、仅记录日志的审计事件对，以及按会话的 ask/never 策略。UI 通道可以提供人类应答者；ACP（Agent Client Protocol）自动化桥接层为其拥有的 agent（智能体）提供一次性机器决策。调用方如 dsh-tools 和 dsh-tool-bash 消费闭合的结果，除非结果为 allowed-once，否则一律拒绝。
源码：packages/interaction/user-approval/src/index.ts
dsh-permission-presets 的权限预设层（ctx.permissionPresets，PermissionPresetService）把两个相互独立的强制执行 knob，即沙箱模式（sandbox/mode）与审批策略（approval/policy），捆绑成具名预设，供客户端作为单个权限（Permissions）选择器提供。它是一项可选能力，不属于 agent loop（智能体循环）主干，也不拥有任何强制执行：执行、提示词叙述与回放仍然读取各自 knob的折叠结果，预设切换只记录意图，并通过每个 knob各自的规范 setter 写入。包 README 负责组合状态与限制；沙箱切换设计负责决策依据。
源码：packages/interaction/permission-presets/src/index.ts
dsh-sandbox 的进程沙箱 seam 将与宿主共享文件系统和内核的子进程 argv 包装在文件效果策略中，而不将消费方耦合到特定平台运行器。dsh-sandbox-local 提供 Linux bwrap/Landlock、macOS Seatbelt 与 Windows ACL 受限令牌后端；dsh-bash-sandbox 和 dsh-pwsh-sandbox 是其消费方。容器、microVM 和远程执行是完整能力 seam 的同级实现，而非 ctx.sandbox 的提供方。
源码：packages/sandbox/sandbox/src/index.ts
计划模式是 dsh-plan-mode 拥有的、记录到日志的逐 agent（智能体）协作状态（ctx.planMode，PlanModeController）：激活期间，每个模型请求都会包含一段部署持有的指引。计划模式是软性指引。沙箱模式与审批策略分别强制限制；两者都不读写计划状态，因此部署需要分别配置它们。该包是可选项，agent loop（智能体循环）不依赖它。它贡献 plan:policy 提示词段落，并注册 exit_plan_mode 工具和 /plan 命令。设计说明负责决策依据；包 README负责模型体验与限制细节。
源码：packages/plan/plan-mode/src/index.ts
dsh-user-questions 的用户交互 seam。它是工具或权限插件需要人类回答后 agent（智能体）才能继续时所使用的、提供方无关的词汇。UI 界面提供活跃的 UserQuestionProvider；host 运行时把请求转发给其连接的客户端。
源码：packages/interaction/user-questions/src/index.ts
dsh-commands 提供的用户命令注册表服务。交互式适配器用它发现插件拥有的命令，并针对确切的 agent（智能体）直接执行这些命令，而不创建模型消息。命令 Agent Note 负责分发与生命周期的决策依据；包 README 负责组合方式与限制。
来源：packages/interaction/commands/src/index.ts
事件溯源目标服务及其策略消费方共享的类型。目标领域 Agent Note 负责记录持久化与激活决策；本页记录 packages/goal/goal/src/types.ts 中的确切字段和变体。
Schedule 拥有持久提醒；这些提醒会作为普通的后续对话轮次返回原 live Session。持久 Schedule Agent Note 负责持久化与生命周期决策，对话式交付 负责无回执边界，显式时区边界 负责浏览器本地解释，有界固定速率 Schedule 负责重复调度。本页记录 packages/schedule/schedule/src/types.ts 中的持久数据形状和面向模型的数据形状；包 README 负责组合、工具行为与确切的提醒 framing。
dsh-host-webserver 是 GUI 宿主的浏览器 HTTP 载体：它是一个提供 ctx.webServer 的 node:http 插件，包含具名路由注册表、index.html 转换回调，以及一个可由插件认领的回退处理器。它不属于 agent loop（智能体循环），也不是能力 seam；它不了解任何 harness 概念。其他插件负责注册所有功能路由，包括 /api 桥接、插件 bundle 和 HMR（热模块替换）事件流（分层说明）。该服务器只服务浏览器：Electron 通过 file:// 加载已构建文件，并经 IPC 桥接发送 fetch 请求，不使用本服务器。
源码：packages/host/webserver/src/index.ts
以下类型由生成的 Remote 产物、Host Gateway 与消费方 API assembly 共用。Typert Gateway Agent Note 负责架构与传输决策；本页记录 dsh-typert-protocol 和 dsh-api-gateway 中公共约定的字面定义。
Web 插件表：dsh-client-modules 中 client 模块系统的 Node 半，以 ctx.clientModules（ClientModuleRegistry）形式提供。它扫描宿主 Loader 的 entry，找出声明了 dsh.client 的包，组合出 window.__DSH_BOOT__ entry 图，在 /plugins/<id>/client.js 提供各个 bundle，并经 index 转换（index tap）注入启动 manifest（元数据清单）——这是同一个服务的四个面。它是 Web GUI 栈的一项可选能力，不属于 agent loop（智能体循环）主干，并且是 dsh-host-webserver 的消费方：web-server.md 所述的载体提供本服务注册的前缀路由与 index 转换。同一个包的浏览器半（ctx.modules，即拉取并物化这些 bundle 的 lazy CJS 模块表）属于内核机件，记录在包 README中，不在本页。
源码：packages/client/modules/src/client/manifest.ts
存储子系统持久保存一切不属于会话事件日志的数据（会话日志有自己的 seam——见 persistence.md）。它是一项可选能力，不属于 agent loop（智能体循环）主干，并按能力 seam 拆分：枢纽（hub）与 Service Definition（dsh-storage，ctx.storage）、Service Provider（注册为 json 的 dsh-storage-json 与注册为 sqlite 的 dsh-storage-sqlite），以及 Consumer 数据形式（dsh-storage-domain，ctx.storageDomain，也可经 ctx.storage.domain 访问）——它是后端约定的唯一 Consumer，也是其他一切所使用的类型化 API。枢纽自身不做任何 IO：后端拥有介质，数据形式拥有语义，产品包绝不直接触碰后端。设计记录：领域 KV 存储 Agent Note。
源码：packages/storage/storage/src/backend.ts · packages/storage/storage-domain/src/spec.ts · packages/storage/storage-domain/src/events.ts
工作区（workspace）是用户工作目录的持久记录：一个建立在规范路径之上的稳定 id、一个显示标题，以及归属于它的会话的有序账本。该子系统是单个包（package）（dsh-workspace，ctx.workspaceRegistry）——一项宿主侧可选能力，不属于 agent loop（智能体循环）主干，并且对模型不可见（没有工具、没有提示词文本、没有会话事件）。它通过存储领域数据形式存储自己的记录，并对照 SessionHeader.cwd 校验会话成员资格，因此 storageDomain 与 sessionPersistence 是必需的启动依赖：持久化这一依赖不可用时，插件保持 pending，而不是把这种不可用误当作空历史。设计记录：领域 KV 存储 Agent Note（agent 决策记录）；引导与 GUI 顺序：Workspace UI 产品流程 Agent Note。
源码：packages/workspace/workspace/src/types.ts
dsh-settings 的用户设置 seam 持有一份按 namespace 分节的用户文档，并把每个已注册 namespace 解析为：schema 默认值，然后注册方的组合 base，最后用户分节。dsh-settings-file 这类提供方存储原始文档并推送外部编辑；消费方插件注册 schema 后读取或观察解析值。组合配置仍留在 cordis.yml——namespace 只承载用户可编辑子集。
来源：packages/settings/settings/src/index.ts
dsh-credentials 的凭据 seam 把机密挡在配置之外：settings 分节与 cordis.yml 条目携带的是引用（环境变量名），值归 dsh-credentials-local 这类提供方所有，消费方每个操作解析一次引用——LLM（大语言模型）适配器每次模型请求解析一次，因此轮换后的凭据无需任何重启即可作用于紧随其后的下一次请求。一条 seam 级规则约束每个提供方：空的存储值在任何地方都视为不存在。