维护者视角：
上游如何运转。

Remote API：给远程客户端开的点菜窗口

前十课里你的插件都跑在本地 Host 进程内。维护者要回答的下一个问题是： Web UI、SDK、ACP 这些远程客户端，怎么调用 Host 里的业务服务？ 答案是 Remote API——注意这个词在上游专指 Typert Remote 的 unary 调用， 一请求一结果；流式会话数据不在其列（本节末尾细说）。

编程模型一句话：Host 服务继承 TypertRemoteService，用 @Remote('方法名') 和 @RemoteScope(key) 自己挑选暴露面。 没标装饰器的方法不进生成物、经 ctx.remote 根本调不到—— 不是运行时权限拦截，而是构建期生成器根本看不见它们。 Typert 生成器读 Host 源码，为每个标了 @Remote 的方法生成两端的严格契约： Host 面的调用描述符，和 Client 面的类型化调用桩。

活对象不穿线

Agent 这样的活对象不能作为参数直接穿越 HTTP。声明 agent: Agent 参数时，Typert 把它映射成一个 agentId wire 字段， 运行时经 TypertLookupMap 注册的提供者还原成真对象； @RemoteScope 的上下文同样走 ctx.typert.contexts 还原。 agent/session 的标准解析策略（冷启动恢复、并发 resume 去重、拒绝 subagent 身份， 错误码 session/not-found、session/agent-busy） 统一收在 api-session-controller 里，Host 方法拿到的永远是已解析好的对象。

生成管线的硬顺序

两个产物落进各业务包的 lib/：typert.host.js（Host 面运行时反射与严格描述符） 和 typert.remote-client.js（Client 面可挂载的调用桩，含 declaration merge 与 source map 回指 Host 源码）。改了签名、码表、namespace 或导出名，必须重跑 pnpm run build:lib，否则两端契约不同步。 生成器还做严格分析：@Remote 方法必须公有、非静态、非泛型，参数必须有名字， 禁解构/默认值/rest/可选参数——契约要能从源码唯一确定，就没有「猜」的余地。

错误模型：一个类，一张码表

Remote 只有一种错误：RemoteError，配一张 <domain>/<reason> 格式的码表 （由各包 declaration merging 汇总）。单包独有的码放生产者包里，多包共用的放最低公共域包； gateway/bad-request、gateway/cancelled、gateway/internal 是基础设施码，不许复制仿造；未分类异常一律兜底成 gateway/internal。 调用侧按 result.ok 与 error.code 分支，不用 instanceof 错误家族—— 一条线、一张表，比一树错误类好维护得多。

Client 侧的装配只挂 dsh-api-remotes 一个门面：它挑选本应用要暴露的 Host 能力 （Commands、credentials、settings、Goal、动态 Cordis、文件与 Session 引用、插件清单、 Session/Workspace Controller 等），经 ctx.remote.$mount() 逐个挂载并 re-export 类型词汇； 调用方插件自己声明 inject: ['remote', 'remote.<ns>']。

双 aggregate：一个仓库为什么要两份 TypeScript 世界

打开仓库根目录，你会看到 tsconfig.host.json 和 tsconfig.client.json 两份配置（docs/development.md 的 contributor reference 是权威文本）。 原因藏在 Cordis 里：Host 侧和 Client 侧都要给 cordis 的 Context 接口做 declaration merging，同名 key（比如 sessions、loader） 在两侧挂的是不同的服务。TypeScript 不允许一个 ts.Program 里出现两份同名合并—— 于是切成两个互不相见的编译世界。

精妙之处在于：这个冲突只活在 ts.Program 内部，模块解析根本不会触发它。 所以根 solution tsconfig.json 可以同时 reference 两个 aggregate （它自己是 files: [] 的空壳，也是 tsserver 的发现入口）， tsc 挨个构建时各自独占一个世界，互不打架。

三条纪律

• tsconfig.base.json 永不加 include/files——否则两个世界被迫看见同一批文件，冲突复活。
• 要建仓库级 ts.Program 的脚本，必须显式 seed host 或 client aggregate，绝不 seed 根 solution。
• 新包只登记进一个 aggregate；少数两边都要检查的，走共享 leaf 或拆分包机制（见下）。

共享 leaf 与拆分包

有三个包两侧都引用：packages/host/webserver、packages/compaction/compaction、 packages/typert/registry——两侧必须 type-check 同一份源码的共享叶子。另有六个两头都有代码的包（api/remotes、api/gateway、 api/session-controller、api/workspace-controller、client/connection、 session-query/session-log-export）各带 host/client 两份 leaf config： 包根 tsconfig 只是 solution，聚合与直接消费方必须点名 leaf—— constraints 门沿 Project Reference 图逐个检查，指错脸直接拒绝。

测试文件也要分脸：命名 *.client.* 的归 Client aggregate， *.host.spec.ts 的归 Host，两个 aggregate 互相 exclude 对方脸的文件。 一份测试属于哪个编译世界，从文件名一眼可读。

Session 格式迁移：亲手加一条世代边

第 06 课讲过版本闸门与不可变世代：旧日志靠相邻迁移链升级到当前代， 已落盘的 generation 永不移动、覆盖、删除。这一节讲轮到你动手时的完整动作—— 权威手册是 docs/cookbook/adding-a-session-format-version.md， 固定范例是 packages/session/session-format-v2-to-v3/README.md。

先问要不要 bump

版本是单调整数，没有 major/minor。bump 判据只有一条： 旧运行时能否对新日志做全语义正确的读取。只有结构性变化 （header、envelope、核心事件语义、surface 机制）才值得 bump； 新增一种普通事件不动版本——给事件信封标 ignorable: true 即可， 默认不标就是必需事件，旧读取器遇到不认识的必需事件宁可拒绝也不静默跳过。

迁移包：一个包一条边

每个世代步由一个独立包负责：packages/session/session-format-v0-to-v1、 -v1-to-v2、-v2-to-v3，包与版本边一一对应。 邻接关系声明在包的 package.json 里，v2→v3 的真实 manifest 长这样：

迁移实现 migrateHeader / validateTargetHeader / createStage（每次调用独立状态），Stage 内用 transformEvent / transformRun / finish 经 context.emitEvent / emitRun 同步发出事件—— 一进可出零或多个。继承 cut 是逻辑事件数不是物理行数，未知 cut 绝不用 0 顶替。 目录结构由 scripts/gen-session-format-catalog.ts 把关： 0 到 writer 版本之间每步必须恰有一个相邻包，缺口、重复、多余边都拒绝； generated.ts 禁止手改。

发布节奏：release/* 集成分支

N+1 的开发用一条共享的 release/* 集成基分支承载基础变更 （writer、codec、catalog 接线、identity 迁移、验证），每个独立子分支从它切出、 做一项结构变换、PR 打回 release 分支；评审合并后整体验证发布。 发布后该相邻边冻结：后续结构变化必须开新边，不得修改已发布的边； release 分支受 force-push 与删除保护。

发布流程：三条版本线，CI 只彩排不发布

上游发版不是按一个按钮跑流水线，而是三条互不等待的版本线 （权威记录在 Agent Note 2026-08-10-npm-release-sequences.md）： 发 dsh 不会重发 vendor，发 vendor 不会重发 native。

第一步 · 版本在本地命令里落仓库

pnpm run release:dsh -- <major|minor|patch|显式版本> （scripts/release/bump.ts）把发布家族、全部私有包、workspace root 写成同一版本并连 lockfile 一起提交；人 merge 之后手工打 tag。 CI 永不写仓库。预发布排序 alpha < canary < rc < stable， dist-tag 映射：alpha/canary → 同名，rc → next，stable → latest。

第三步 · 无凭证彩排，每个 PR 都证明还能打包

第四五步 · 人工发布与 registry 三态判断

真正的发布只在 release-publish.yml 里发生：workflow_dispatch-only、 从 dsh-v* tag 运行，先重新打包再按 publishOrder （npm 安装关系 + peer 声明的拓扑序）逐个发布，全程置于 npm-publish 环境的人工审批之后。 发布脚本对 npm registry 做三态判断：

• registry 没有该版本 → 正常发布；
• 有，且 tarball 的 sha512 与已记录 integrity 一致 → 跳过（这是同一次发布的重跑）；
• 有，但 integrity 不同 → 失败：内容变了却没升版本。

连「代码变了忘升版本」都会被 integrity 对比抓住。另有两道护栏： verify-application-entrypoints 强制所有受支持的 Node 应用都从 dsh CLI + named profile 启动（包 bin、可执行源码、根 demo 全部白名单分类， 绕过 dsh 的启动路径一律拒绝）；FIXME 注释按约定应阻断发版。 发布成功的最后一项义务：核对 Session writer 与 release record， 发了更高格式就更新 docs/session-format-status.md 的双语记录与证据链接。

三个仪表盘：benchmarks · llm-retry · token-meter

仓库边缘有三个不直接做产品功能的包，它们是维护者回答日常问题的仪表盘： 多快（benchmarks）、挂了怎么办（llm-retry）、这次请求多挤（token-meter）。

benchmarks：仓库级性能红线

• 按被测用户路径组织——session-open、agent-continuation、conversation-fold、active-stream-reconnect、long-session-browser——不镜像包树；Host 用 *.bench.ts，Client 用 *.bench.client.ts（benchmarks/AGENTS.md）。
• 预算是代码内评审常量，环境变量不得覆盖；输入一律合成固定数据，绝不录 Session、用户素材或网络。
• CI 必需基准在标准 ubuntu-24.04 hosted runner 上独立跑（不受 selfhosted failover 影响），整个 job 15 分钟超时；session-open 的 open 端点预算按 50ms CI 期望 × 1.25 余量定为 63ms。
• 维护者介入点：改了被测路径的性能相关代码；预算门变红需要实测校准（阈值变更要求实测数据 + 正负对照）；换 runner 必须先跑一次真实 hosted 基准验证超时可信。

llm-retry：模型请求挂了怎么办

llm-retry 自己没有配置——重试策略长在每个 provider adapter（dsh-llm-deepseek、dsh-llm-pi-ai） 的 retryPolicy 里。不配置时是 normal 模式：针对 EMPTY_RESPONSE / RATE_LIMIT / SERVER / TIMEOUT / TRANSPORT 重试 5 次，500ms → 10s 有界指数退避加 10% jitter；always 模式无上限， 直到成功、取消或插件卸载。两条边界要背下来：只有 agent turn 是重试边界， 直接 ctx.llm.stream() 没有重试；重试对模型完全不可见 （事件、延迟、失败都不进模型上下文），而 每次重试都是又一次计费请求—— llm/retry-started 还会结束 token-meter 的 usage 替换域，让重试计入用量。

token-meter：这次请求有多挤

ctx.tokenMeter.measure(session) / estimateMessage(message) 通过重放持久日志做估算：确定性、零模型调用，compaction、占用率 UI、遥测共享同一个答案。 文本用「字符数 + 结构开销」的固定启发式（CJK 与 JSON schema 在四字符一 token 的启发式下会明显低估）， 有定价声明的图像走 provider 精确视觉 token；provider 自报 usage 只在请求 envelope 完全一致时复用。 会话投影可用时它注册三个 units：tokenUsage、contextPressure、 contextBreakdown，插件卸载即移除。定位要摆正：参考值，不是账单—— harness 里没有任何决策依赖它。

Agent Notes 读法：从「必须写」到「读出门道」

第 10 课讲过「每个非琐碎改动必须同 PR 带一篇 Agent Note」。 这一课补全读法与格式细节——权威手册是 .agents/notes/README.md。

路径即检索

.agents/notes/{lifecycle}/{class}/yyyy-mm-dd-topic.md： lifecycle 是 proposed / implemented / rejected， class 是 feature / bug-fix / simplification / architecture / process / testing 的闭集 （scripts/agent-note-tree.ts 是权威，分类门拒绝其他文件夹）。 组织全在路径里，三个人生阶段乘六个决策领域；没有集中 INDEX.md—— 有专门的决策删掉了它，交叉引用一律用相对 markdown 链接（verify-md-links 检查）。

implemented 骨架与 Alternatives considered

• 骨架：## Problem → ## Decision → 自由技术节 → ## Alternatives considered → ## Consequences。spec-speak（## Proposal、## Migration plan 等）在 implemented 里会被门拒绝。
• Alternatives considered 强制：每个真实备选写一段「它是什么、为何落败」。动机很直白——不记下被击败者，半年后就有人把它当新点子重提。
• proposed → implemented：把提案重写成现在时的决策陈述，验收标准与风险折进 Consequences；移动文件夹必须同一变更内更新 Status 行并满足目标骨架。
• archived 冻结：理由不再指导未来工作的 implemented 笔记移入 archived/，只许整组移动（英/中/sidecar 三件套）、插 Archived 日期行、修入链；此后永不可编辑、不得当现状权威。
• 中文 .zh.md 逐节镜像：header token（# Agent Note: 与 Status: 行）保持英文，由配对门校验。

写作本身也有门：一段一物理行（verify-md-wrap）、 文档里的 ts 块必须真实编译（doc-typecheck）、根文档有字数预算、 禁止叙述历史与手抄目录。docs 分层口诀一条记牢： bug → postmortem、理由 → Agent Notes、流程 → cookbook、类型 → subsystems、 包契约 → README、常驻命令 → 根 AGENTS.md——一个事实一个家。 postmortem 的触发标准是三条同时成立：机制不显然（subtle）、因测试/工具/惯例缺口而逃逸 （systemic）、重新发现代价高（costly to rediscover）。