e27d38efd6
A composition that shares one `isolate` realm across rows needs a `cordis:group` row, and a preset living outside this workspace — the authored ones under the Harness home — cannot resolve `@cordisjs/plugin-group` by name: Node's upward `node_modules` walk never reaches the harness from there. Registering it as a loader builtin beside `cordis:include` loads both through the ambient module pipeline instead. Record it in the preset Agent Note, which leans on the realm vocabulary without saying where the group row comes from, and drop the preset README's limitation claiming this builtin is unavailable — it described the state this change ends. The test's assertion had a vacuous escape: `provide` mints the root symbol unconditionally, so the `rootKey === undefined` disjunct could never hold and the comment claiming the root realm never learned the name was wrong. Pin both halves — the symbol exists, nothing is stored under it — and clean up the global the fixture writes.
12 KiB
@deepseek-ai/dsh-app-boot
English | 中文
供 app bin（dsh、dsh-cli-demo、dsh-acp-demo）共用的启动粘合层：每个 bin 都是在这些 helper 上构建的精简自执行组合，并以自身诊断前缀参数化。这样，Loader 故障行为只由一处负责，不会在已发布产物之间逐渐分化。
| 导出 | 职责 |
|---|---|
resolveConfigPath(path, snapshotMode, cwd?) |
生成绝对配置路径；当 snapshotMode === 'replay' 时，把 basename 为 cordis.yml/.yaml 的文件替换为同级 cordis.snapshot.yml |
loadEnv(binName, dir?, warn?) |
加载已被 git 忽略的 .env（Node process.loadEnvFile）；文件不存在不影响启动，文件无法加载时输出一行带标签的警告（默认写入 stderr） |
installFailLoud(binName, proc?, release?) |
将启动期或后续未处理的 Loader rejection 转换为一行带标签的 stderr 消息并执行 exit(1)；两者之间会等待可选的 release 拆卸回调（以 FAIL_LOUD_RELEASE_TIMEOUT_MS 为上限），使持有终端的界面能在退出前恢复终端；返回卸载函数 |
FAIL_LOUD_RELEASE_TIMEOUT_MS |
installFailLoud 等待其 release 回调的时长；卡住的 disposer 只会延迟致命退出，而不会取消它 |
assertEntriesLoaded(ctx, binName) |
树结算后，如果其中存在已启用但没有 fiber 的条目，则抛出异常，并以 Cordis 启动故障的形式报告每个未解析插件的名称 |
assertEntriesActivated(ctx, binName) |
先执行 assertEntriesLoaded 检查，再在 Loader 结算后等待每个已启用配置项；抛出的错误包含每个失败插件的原始错误堆栈，或每个等待中插件尚未解析的服务 |
loadOptionalPatches(binName, file) |
解析一份可选的 patch 列表文件（即 profile 的 cordis.patch.yml）：其顶层是一个 YAML 数组，内容为 include 的 PatchOptions（按 id 定位的配置覆盖、insert 列表，允许 !!js）；文件不存在时返回 undefined，文件不可读、不可解析或内容不是数组时抛出异常 |
loadOverlayPatches(binName, file) |
解析一份形状相同的必需 patch 列表文件；文件缺失同样抛出异常，因为该文件是调用方指名的 |
mountRootInclude(ctx, absoluteConfigPath, patches?) |
注册静态导入的 cordis:include 与 cordis:group builtin，挂载 include，并保留用户 patch 层 HMR（热模块替换）使用的确切根配置项 |
watchUserPatches(ctx, options) |
向现有 Cordis HMR 服务注册指名的 patch 文件；每次新增、变更或移除都会通过调用方的 compose 闭包（应用自有层围绕当前用户层）以事务方式重新组合完整 patch 列表，并返回异步 disposer |
resolveProfileDir / initProfile / loadProfile / readProfileManifest / writeProfileManifest / resolveBundleDir / composeEntries / healProfilesModuleFallback / PROFILE_TEMPLATES / DEFAULT_PROFILE_BUNDLES / PROFILES_DIR / PROFILE_PATCH_FILENAME |
Profile 机制（见 Profile） |
boot(binName, absoluteConfigPath, patches?, prepare?) |
创建根上下文，向 Loader !!js 配置表达式暴露 dshHomePath(...segments) 并安装 Loader，在配置树条目挂载前执行可选的宿主准备操作（prepare 可以使用 Loader，也可以提供由启动器拥有的上下文插槽），再挂载并等待 include 树结算，断言所有条目均已加载并激活，最后返回根上下文——失败时 dispose（资源释放）部分构造的上下文，并以带标签的错误 reject |
renderConfigDump(binName, absoluteConfigPath, layers, warn?) |
离线合成基础配置与带标签的覆盖层——使用 include 自己的解析器和补丁算法（entryListSchema/applyEntryPatches），因此结果与 boot() 挂载的内容一致——并渲染为 YAML，!!js 表达式原样保留；每段来源相同的连续行之前都有一条 # == 注释，标明贡献该段的文件以及修补过它的层，输出仍是一份可加载的文档；未匹配到行的补丁连同其层标签交给 warn（默认：一行 stderr），读取／解析／形状失败则抛出 |
addHarnessSourceSection(ctx, sourceRoot) |
添加全局 harness:source 提示词段落（顺序紧随 harness 身份、位于 persona 之前），告知 agent（智能体）DSH 实现代码 checkout 的磁盘路径，同时提醒它不得据此推断当前工作目录，而应使用 pwd；如果已启动树没有此项服务，则不执行操作并返回 undefined。这里的服务是 systemPrompt；该段落注册到它的 fiber，因此开发环境 HMR（热模块替换）重新加载系统提示词后，它会消失直至下次启动 |
HARNESS_SOURCE_SECTION |
'harness:source' 段落名称，供 addHarnessSourceSection 注册使用 |
Loader 结算会在导入或生命周期失败时 reject，并携带失败的配置项与阶段；boot() 会 dispose 部分构造的上下文，并用 bin 名称包装该失败。结算后遗留的配置项由独立审计处理：assertEntriesLoaded 将已启用却没有 fiber 的配置项转换为 rejection 并列出每个未解析插件；assertEntriesActivated 会显式等待每个失败的 fiber，把原始错误堆栈写入启动 rejection，并列出每个等待中配置项尚未解析的服务。抛出错误前，审计会通过一个进程级检查点标记这些 rejection 的确切原因，从而让 installFailLoud 将 Loader 的重复通知合并为一次，而所有无关的未处理 rejection 仍然致命。
Loader 并发挂载各个条目，因此当其他环节失败时，某个界面可能已经持有终端：此时不经过整棵树自身的拆卸就退出，会把 raw 模式、bracketed paste 和键盘协议残留在用户的 shell 上，而尚未返回的终端查询响应会在下一个提示符处显示为字面文本。配置树失败会经 boot() 结算：它先释放部分构建的上下文（从而执行该界面自身的 shutdown），再抛出带标签的 rejection。对于 boot() 看不到的 rejection（插件游离的异步工作在挂载期间或挂载完成后失败），持有终端的 bin 会传入 release，在提交退出前释放整棵树；dsh 在 boot() 的 prepare 回调中捕获根上下文，而不是取其返回值，使该回调覆盖整个挂载窗口。release 执行期间处理函数保持注册并加闩：被报告的始终是第一个 rejection，后续 rejection（包括拆卸自身的）会被吞掉，而不会变成未捕获错误、在拆卸中途杀死进程。
cordis:group 与 cordis:include 一并注册，使一份组装能把一个提供方与它的消费方放进同一个 isolate realm。两者都通过宿主的模块管线加载，而非被包含树自身的说明符解析，这正是让本工作区之外的组装——放在 Harness home 下的 agent preset——能够使用 group 行的原因。
配置中的裸插件 specifier（@deepseek-ai/dsh-*、npm 包（package））通过 Cordis Loader 的内部模块 loader 解析。仓库 bin 会安装 Loader 的可选 peer node-addon-require-builtin；外部调用方必须提供该组件，或者把插件安装到普通 Node import 解析可以找到的位置。相对 specifier 无需原生 helper，并以配置目录为基准解析。构建后的 dsh-app-boot 产物内嵌静态挂载的 Include 实现，但仍将 Loader 保持为外部依赖，因此 include 树与 host 会绑定到同一个 Loader peer。dsh 源码启动器还会将 manifest（元数据清单）声明的 workspace 包映射到其 TypeScript 源码；其配置门禁要求每个已交付的原始／Web 裸插件都出现在解析所用 manifest 的 dependencies 中。
此包不包含 loader 钩子，也不提供开发模式接口。dsh 应用持有自己的 Node 源码启动钩子，并在启动序列中使用这些 helper；构建后的消费方仍使用普通 Node 包解析。
Profile
profile 是位于 $DSH_HOME/profiles/<name> 下的目录（Harness home 由 resolveDshHome 解析：先取 $DSH_HOME，否则取 ~/.dsh），其中包含一个 package.json（树外插件 dependencies，加上 profile manifest dsh.profile 及其有序的 bundles 层列表）和用户自己的 cordis.patch.yml。组合包是在 manifest 中声明 "dsh": { "bundle": { "patch": "./cordis.patch.yml" } } 的 npm 包；loadProfile 以双锚点解析每个 dsh.profile.bundles 名称（先从 dsh 安装目录，再从 profile 目录），列出的包若没有组合包声明则大声失败。composeEntries 通过 include 自己的 applyEntryPatches 在空条目列表之上应用各 patch 层，因此组合、标志推导和配置 dump 绝不会与实际启动内容发生偏离。healProfilesModuleFallback 维护扁平的 $DSH_HOME/profiles/node_modules 目录（安装目录的应用与各组合包依赖的每个包对应一个符号链接），使任意 profile 中的裸插件名都能经 Node 常规的逐级向上查找解析，而 pnpm 从不管理随安装内置的包。PROFILE_TEMPLATES（web、headless）在首次使用时自动初始化；其他名称在 initProfile 创建之前都会大声失败（即 dsh plugin 路径）。
用户级的机器本地偏好同样位于 Harness home 中：
.env：dsh-credentials-local的凭据存储，只由该 provider 读取。没有任何表层会把它提升进process.env：那样做会让每个已存密钥在下次运行时看起来都像只读的启动时覆盖，从而阻断从 Web 设置页面轮换密钥。环境层次由环境中的值与调用目录的.env构成（由 bin 加载；process.loadEnvFile从不覆盖已有值），没有凭据 provider 的组合仍然只从这两者解析密钥。cordis.patch.yml（home 级）与profiles/<name>/cordis.patch.yml：用户 patch 层，应用在所有组合包层之后（先应用逐 profile 的文件，再应用 home 级文件，因此后者优先级更高）：按 id 定位的 patch 会替换对应条目的整个config（未改字段也要重述），insert会添加条目，!!js表达式则在挂载时插值。如果 patch 指定的条目 id 不在组合后的树中，则输出一条 stderr 警告。空文件或仅含注释的文件会抛出异常（其解析结果为空，而不是列表）；如需禁用该层，请使用[]。
长期运行的 surface 会持续应用 cordis.patch.yml 的变更，具体由 watchUserPatches 负责；一次性运行只读取启动时的值。即使该文件或其直接父目录不存在，watcher 仍会监视确切路径；它会串行处理突发变更，并按调用方的层次顺序重新组合用户 patch（组合包层在下、overlay／标志 patch 在上）。读取失败、解析失败或 Loader 候选被拒时，最后一个可用树会继续运行；HMR 服务记录错误后广播 hmr/config-update-failed(filename, Error)，并隔离 observer 失败。上下文 dispose 时会关闭 watcher，并等待进行中的刷新结束。
模型体验
模型通过此包加载的插件树间接受到影响；该树决定最终应用中的提示词、schema、消息和模型适配器。唯一贡献模型可见文本的导出 addHarnessSourceSection，也只有在消费方启动后调用它时才会产生影响。
KV Cache 影响
boot() 不会直接使缓存失效；消费方调用 addHarnessSourceSection 时，会在系统提示词靠前位置、逐请求内容之前添加一行短文本，因此不会使跨轮次缓存失效。请求前缀的其他任何变化均由相应的具名消费方持有。
已知限制与延期工作
- 裸包 specifier 依赖 Loader 内部机制：生产 bin 需要 Loader 的可选原生 helper；没有该 helper 的进程内调用方必须使用可解析的相对／file specifier，或提供自己的模块解析钩子。
- 快照回放替换仅识别特定 basename：只有以
cordis.yml或cordis.yaml结尾的配置会映射到同级cordis.snapshot.yml；自定义配置名称需要调用方自行选择。 - 环境加载局限于 cwd 且为可选操作：helper 只加载一个
.env文件，并在失败时发出警告；它不会搜索父目录、合并 profile 或验证必需变量。 - 用户 patch 层采用 patch 形式：按 id 定位的 patch 会替换条目的整个
config，而不是深度合并，因此 profile 覆盖必须重述需要保留的组合包字段。