AgentKit Studio文档

补丁治理与宿主兼容

生产基线保持 DSH 639ed015397290b3745d163aafe02ffee4aa3f84，当前补丁集为 34 项。阶段 5A 的清单及宿主 CI 已接入；5B 产品配置和本地运行验证已落地，最终平台验收仍在进行；5C 已加入维护分支归档、自动导出校验、事件消费者修正及运行时能力检查，候选升级与最终平台验收分别记录。

修改和构建入口

patches/dsh-v0.2.0-rc.2/manifest.json 记录每项补丁的类别、基线、内容 SHA-256、修改文件及所属包、依赖、合同、风险、维护角色、上游状态、删除条件和验证方式。验证要求是待执行场景，不能用登记记录代替通过证据。

同一文件的后续补丁必须通过依赖链声明前一个修改者。门禁拒绝依赖成环、依赖晚于使用者、混用基线、遗漏修改文件、未登记的补丁和内容摘要变化。文本格式检查使用 Git 解析器，支持新增及删除文件；完整应用检查另在固定基线的独立索引执行。桌面打包在克隆及运行工具前校验清单。

make patch-manifest-check
make verify-patched-host DSH_ROOT="<固定 DSH checkout>"

宿主验证在输出目录创建并锁定独立 checkout，从固定 commit 应用补丁。源码通过独立临时索引形成完整 Git tree，比较清单中的 tree ID 与完整 tree 清单 SHA-256；不依赖 diff 缩写或显示设置，不修改调用方索引。之后安装冻结依赖、构建官方 Web/Host，并把登记的测试路径作为参数交给 Vitest，不执行清单中的命令文本。构建结束再次检查源码指纹，报告实际通过、失败及跳过数量。

打包入口复用源码检查。缓存记录使用完整 tree 指纹；旧记录只在原指纹仍可验证时迁移，不能验证时保留原缓存并要求新输出目录。隔离 Windows checkout 启用长路径，独立 DSH workspace 按自身 packageManager 选择 pnpm。

CI 的 patched-dsh-host 在 PR 和 main 提交上使用标准 Linux、Windows runner，并保留报告。Web、Electron、生命周期、冻结 Build、平台包和真实安装更新分别验收，宿主测试不能代替这些结果。

已收敛的补丁

  • 007 随侧栏改为完整复用 DSH 会话列表而移除；Agent 选择不再过滤历史列表。
  • 021 随恢复上游默认更新动作而移除。上游已在空闲和检查失败时强制刷新，并按 available / ready 状态下载或安装；原补丁无条件强制检查会干扰后两种动作。恢复默认后，main-startup 的 114 项行为测试通过。
  • 001、002、003、005 由 035 的公开产品文案接口替代。构建输入控制首次渲染，运行时 locale 覆盖由所属 effect 释放；默认 DSH 仍显示原生文案及动画图标。产品值统一来自 Studio 配置。
  • 036 同步已有预设组合 API 的生成目录；037 单独修复 Hero 回放的空编辑器初始状态。两项分别维护，不合并到产品接口补丁中。

产品版本、App ID、更新源、默认 bundle、平台图标和发行工作流输入见产品配置。新建、已有、用户禁用及原生 bundle 四类 Profile 已通过打包内 Desktop Host 的本地验证，每类连续启动两次，检查用户状态、已有插件运行和释放、Host 接口、前端挂载及 IPC 正常退出。验收脚本使用桌面 runtime 的完整依赖图；普通 CLI 的依赖图不包含所有桌面产品插件，不能替代桌面入口。

当前证据及缺项

新增 039 在运行时清单封存前排除 .coveralls.yml / .coveralls.yaml，普通桌面包和安装更新验证包也保留同一归档排除项。它们是第三方依赖附带的 CI 上报配置，不参与应用运行。运行代码、许可证、package.json 和模型数据清单继续保留，准备清单仍须与实际 ASAR 的完整文件清单一致。回归先复现排除和清单不一致的问题，修复后直接依赖配置和文件策略的 15 个原生测试文件为 123 项通过、7 项平台跳过，官方 Host TypeScript 编译通过；归档检查另有 Unix 和 Windows 路径回归，拒绝残留文件后才报告通过。旧包已触发该拒绝；039 对应的 .36 macOS/Windows 新包已通过打包运行时、实际模块图及四类打包内 Profile 各两次启动检查。真实原生 UI 仍待复验，包内 Host 检查不代表原生安装更新通过。

新增 040 提供经校验的 DSH_DESKTOP_WEB_PORT，允许隔离 Desktop 实例使用操作系统分配的端口；省略时保留既有默认值，不迁移 Profile 或用户数据目录。本地 14 项端口配置测试、Host TypeScript 编译、双语配对和文档检查通过；新原生包仍须验证实际启动与重启。

在加入 039 前，32 项补丁的 .33 macOS/Windows 未签名包均完成打包运行时、147 个实际模块和四类 Desktop Profile 各两次启动检查；Web、开发 Electron 各 28 项回归通过，macOS 从 DMG 复制的实际应用也取得冷启动、已有历史回归及重启证据。首轮 UI 启动和菜单点击失败保留，补跑通过；这些组合证据不代表单次全量成功，也不覆盖新增的包内容排除规则。真实签名安装更新及回滚仍单独验收。

新增 038 将请求指纹保存在首次接收的原生入队消息中，修复已领取和取消队列的重复请求窗口。原生 28 项行为测试、官方完整构建及真实 Host 的 12 项冻结运行验收通过；后者覆盖磁盘重开、只读重放、旧请求头、模型冲突、领取和取消期间重试以及卸载。Host 根在同一进程内重建，模型和 MCP 上游受控；本项尚未完成最终平台包及安装升级验收。Studio 不再用可忽略的模型展示事件决定执行身份。

此前 31 项补丁对应 tree c2426c392335dde1ca31d5373fefef1940cb01db，14,123 个源码条目。干净源码的官方构建通过，受影响 Host 测试 928 项通过、1 项平台跳过；GUI 测试 9,549 项通过、6 项跳过。默认 DSH 与配置后的产品页面均通过真实浏览器验证。macOS 未签名包已完成构建和打包运行时检查；这不证明签名、安装升级、数据保留或回滚。

此前 31 项补丁在公开 CI 任务 38693027148 完成 Linux 和 Windows 宿主构建及测试，分别为 928 项通过 / 1 项跳过和 926 项通过 / 3 项跳过；两端源码 tree 均为上述指纹。任务 38696259649 在 Studio b9dd36d 上完成 Windows 未签名安装包构建、打包运行时冒烟和真实 app.asar 的 144 模块检查；签名未执行，真实安装升级、数据保留和回滚仍未验收。前一次归档检查的 JSON 加载器失败已保留并修复。

当前候选的 Web 回放先因缺少 WebKit 失败；安装 owning workspace 指定的 WebKit 后，受影响的两个文件共 10 项全部通过。合并原全量记录和补跑结果为 602 项通过、16 项原有跳过，无剩余失败；这是组合证据，不是第二次全量运行。维护来源工具加入后，941 项 Studio 源码测试及 538 文件实际 tarball 检查通过。维护分支的本地恢复、确定性导出和构建预检已通过，导出后的源码树不变；新工具在平台 CI 的执行结果另行记录。失败轮次、诊断和原始验收报告保存在忽略的 .artifacts/refactor/stage-5/，后续报告必须关联实际源码及包指纹。

维护来源和升级

上游状态区分 not-submitted、pending、merged-unreleased 和 in-baseline。没有核验回执时使用 unverified；删除前必须确认当前产品基线具有等价行为。

固定基线上的维护提交是宿主修改来源，.patch 是生成结果。维护分支以标准 Git bundle 保存在 host-source/dsh-v0.2.0-rc.2/maintenance.bundle，只包含基线之后的提交；上游许可证随归档保留。patches/dsh-v0.2.0-rc.2/source.json 固定分支、基线、提交顺序、最终源码树、各项导出摘要和 bundle 摘要，manifest 再固定该描述文件。维护归档不进入运行时 npm 包。

# DSH_ROOT 提供固定上游基线的 Git 对象；目标目录必须尚不存在。
make patch-source-import DSH_ROOT=../deepseek-harness DSH_MAINTENANCE_ROOT=../studio-dsh-maintenance

# 在维护分支修改、测试并提交。每项补丁对应一个提交，保留 Studio-Patch: NNN trailer。
# 修改已有项时整理对应提交及后续提交；新增项先登记 manifest 的合同、路径、归属和依赖。
make patch-source-export DSH_MAINTENANCE_ROOT=../studio-dsh-maintenance
make patch-source-verify DSH_ROOT=../deepseek-harness

导出要求工作目录干净、提交从基线线性延伸、编号和清单顺序一致。导出会更新补丁、摘要、源码指纹和 bundle，不替代合同、依赖和验收登记；缺失的评审字段仍会失败。重复导出保留相同归档字节。导入只创建新目录，不覆盖已有维护分支或用户源码。支持 Actions 常用的浅克隆基线：校验保留只读的浅克隆边界，导入时将该边界带入新仓库。

make public-gate 中的 patch-source-check 无需 DSH checkout，核对描述文件、归档和导出文件摘要。patch-source-verify 用基线对象在独立临时 Git 仓库恢复归档，检查父提交和 trailer，逐项重新生成补丁并比较字节。桌面打包、预检、开发安装及补丁应用检查均执行完整校验；Linux/Windows 宿主 CI 也在构建前执行并记录结果。仅改补丁并重写清单摘要仍会被完整校验拒绝。归档文件丢失时需取得源码仓库，不能从运行时包推断维护来源。

通用修复与会话持久化扩展分别评审；持久化复核 区分真实日志恢复和节点投影，并记录尚未接受的事件消费者。宿主兼容检查 从运行中的 DSH API 读取基线版本，按 Studio 集成合同检查所属 Host 的必要能力；冻结运行时随原生依赖作用域启动、关闭及恢复。候选升级只在独立 checkout 演练，记录需保留、已有等价实现、需重做的差异及耗时，失败不能自动切换生产基线或删除补丁。

候选升级演练

先固定候选 commit，使用干净 checkout 检查整组补丁；报告写到 checkout 外部。此命令只在临时 Git 索引应用补丁，不修改候选文件、用户索引或生产补丁。

node scripts/rehearse-dsh-patches.mjs "$CANDIDATE_ROOT" "$CANDIDATE_COMMIT" \
  patches/dsh-v0.2.0-rc.2 .artifacts/upgrade-application.json

报告绑定候选 commit/tree、生产基线和补丁组摘要，并记录逐项耗时、直接冲突及依赖阻塞。存在未应用项时退出码为 1；错误不能作为跳过前置依赖的理由。即使全部应用成功，acceptancePassed 仍为 false：还需构建、运行原补丁行为用例和产品集成测试。反向应用成功或文本已存在也不能自动判为等价可删除。

对 dsh-v0.2.1-alpha.3（2fbf4359b82fb94c03dcce0b831660d87f12ea5c）的一次演练中，32 项补丁有 5 项可以顺序应用、6 项直接冲突、21 项因前置依赖未应用而阻塞。可确认等价删除的补丁为 0；生产补丁全部保留。需要先处理 009、011、012、015、017、028，再复查依赖项，不能把 21 项阻塞当作 21 个独立冲突。

候选原生记录及 JSONL/Zstd 迁移测试通过 39 项；这是首轮和补跑的组合结果，首轮缺少本机文件锁模块的失败记录保留。沿用 016 的行为断言、当前 Studio Codex 记录器及旧日志事件名称的 4 项兼容探针全部失败：候选 Session.append 不保留旧调用传入的 ignorable，V3 迁移将未知可忽略事件改名为 plugin: 前缀。原日志字节和记录数据保留，但现有事件消费者不能据此视为兼容。016 需要重新设计生产和消费接口，并补齐迁移回归；候选新增记录 API 不能直接作为删除依据。

此次候选升级未通过，未进入完整 Studio Host 或桌面安装验收，也未修改产品基线。每轮报告及探针保存在忽略的 .artifacts/refactor/stage-5/，分别记录依赖准备、应用检查、环境修复、行为验证和总耗时；后续升级应复用相同场景比较成本。