diff --git a/docs/design/HANDOFF.md b/docs/design/HANDOFF.md index 1022799..6dee128 100644 --- a/docs/design/HANDOFF.md +++ b/docs/design/HANDOFF.md @@ -1,23 +1,27 @@ -# 交接说明 / Handoff (2026-10-19) +# 交接说明 / Handoff (2026-10-20) ## 当前状态 -- main：PR #7–#17 已合入。#16 于 2026-10-19 合并，Phase 0 共享契约 C1–C8 已可用；说明见 `docs/design/CONTRACTS.md`、`docs/design/OWNERS.md`。 -- PR #17 `ws1/iroh-network` 已于 2026-10-19 合并，merge commit `a23858f`：iroh 默认网络、内置 relay、链接/二维码配对。集成评审补上双方独立确认的授权修复和两处空间测试同步修正；最终提交 `5a181c8` 的 7 项跨平台 CI 及 Release 检查全部通过。交接及剩余事项见 `docs/design/handoff/WS1-iroh.md`。 -- 本总交接文档在 #16 合并后才提交，已随 #17 补入 main。 -- #19（Claude cch 首轮 mock 实验）及 #18（第三方转换器与许可证）已合并。#20（WS2/WS3 本机代理）和 #22（WS5/WS6/WS7）正在本轮集成，最终状态以对应 PR 为准。#22 已合入 main 的 WS1 代码，补 Windows 持久化和多节点启动修复。 + +- 本轮 PR 已全部合并。代码基线为 main 的 `0d4bc49`（2026-10-20）；#22 经 #25 集成并保留原提交，GitHub 已将两者标记为 MERGED。 +- #16 提供 Phase 0 共享契约 C1–C8；#17 提供默认 iroh、内置 relay、链接/二维码配对与双方独立 SAS 确认，最终头 `5a181c8` 的 7 项检查通过。交接及剩余事项见 [WS1-iroh.md](handoff/WS1-iroh.md)。 +- #19 提供 Claude cch 首轮 mock 实验；#18 完成第三方转换器与许可证；#23 扩展默认 Unsupported 的 count_tokens/取消登录兼容接口；#20 提供 WS2/WS3 本机代理，最终头 `eedcc29` 的 15 项检查通过，合并提交 `31fadaf`。 +- #24 接通私有管理登录取消及独立 Messages 计数，最终头 `964a0cf` 的 7 项检查通过，合并提交 `fd1ed77`。界面取消按钮及四家 OAuth 原生计数仍缺。 +- #22 提供 WS5/WS6/WS7，最终头 `7ac8c99` 的 15 项检查通过。集成修复包括 Windows 节点栈溢出、持久化、配置快照、原生扩展冷启动，以及多节点/Web 端口和终端重连的测试同步。 +- #25 补 mesh 计数及 501 透传，包含 #22/#24 的完整集成；修复三节点测试中 Hub 凭据更新与启用列表变更的同步顺序。最终头 `60d3443` 的 15 项检查通过，合并后完整文件树与该头一致。 - 各工作流实际完成内容、真实链路缺口、证据边界及后续优先级见 [IMPLEMENTATION-STATUS.md](IMPLEMENTATION-STATUS.md)。设计规格不代表全部交付。 - 原工作区仍有未提交改动，本次评审使用独立 worktree；接手前检查状态，勿覆盖。 ## 合并顺序 -1. #16、#17 已按顺序合入 main；新工作可直接基于 main 开始。 -2. 本轮按 #19 → #18 → #20 → #22 集成；每个 PR 改为 main 后处理冲突并核验最新头 CI，禁止跳过草稿审核。 + +1. #16、#17 已按顺序合入 main。 +2. 本轮依次合并 #19 → #18 → #23 → #20 → #24 → #25；#22 原头在 #25 中保留并完成集成后随之合入。各 PR 均在最终头检查通过后合并。 3. 已有工作流先 merge main；新工作从 main 切 `wsN/...` 分支，按 `docs/design/tasks/NN-*.md` 执行。 ## 待接手工作流 | WS | 任务书 | 状态 | |---|---|---| | WS1 iroh | tasks/01 | 核心已合并（#17），UI、名册接入等剩余清单见 WS1-iroh.md | -| WS2 订阅代理核心 | tasks/02 | #18 已合并，#20 核心与 mock 回归已交付；计数/取消管理接口待贯通 | +| WS2 订阅代理核心 | tasks/02 | #20 核心与 mock 回归、#24 私管取消和独立计数、#25 mesh 计数；界面取消与四家 OAuth 原生计数仍缺 | | WS3 Codex/Kimi/国内厂商 | tasks/03 | #20 四家协议与 33 预设已交付；真实账户待验收 | | WS4 Claude 节点 | tasks/04 | #19 首轮 mock 结论已合并；真实订阅与跨节点未实现；详细规格不进公开仓库 | | WS5 Agent 适配（DSH 默认） | tasks/05 | #22 六 Agent 配置/会话/MCP；部分审批与 Pi 真工具回合待完成 | @@ -27,7 +31,7 @@ ## 规则 - 一个工作流一个分支，小 PR，CI 绿再合，禁止 force-push / 改历史，合 main 用 merge 不用 rebase。 - 契约（`cranibox-contracts`）变更需单独 PR，并在 PR 中说明影响的工作流。 -- 已知不稳定测试：`local_catalog_and_shell_survive_gateway_replacement`。 +- 本轮已修复 `local_catalog_and_shell_survive_gateway_replacement` 的关闭后身份锁释放问题，并强化为原节点对象仍存活时可重新打开；临时端口分配和 Windows 配置快照也已修复，验证边界见实现核对表。 ## 待产品负责人决定 - D1 Claude 先做请求模拟，不行再接真实 Claude Code（建议）。 diff --git a/docs/design/IMPLEMENTATION-STATUS.md b/docs/design/IMPLEMENTATION-STATUS.md index d852554..bdfbf0d 100644 --- a/docs/design/IMPLEMENTATION-STATUS.md +++ b/docs/design/IMPLEMENTATION-STATUS.md @@ -1,20 +1,31 @@ -# 设计实现核对（2026-10-19） +# 设计实现核对（2026-10-20） -本表逐项对照 [ARCHITECTURE](ARCHITECTURE.md)、[WORKPLAN](WORKPLAN.md)、[CONTRACTS](CONTRACTS.md) 和 [tasks/00–07](tasks/)。核对基线是 main 已有的 WS0/WS1、PR #19/#18、PR #20 的本机代理，以及 PR #22 的 Agent/Vault/个人界面；#20/#22 的最终合并状态以 GitHub 为准。原工作区尚未提交的修改不算交付。 +本表逐项对照 [ARCHITECTURE](ARCHITECTURE.md)、[WORKPLAN](WORKPLAN.md)、[CONTRACTS](CONTRACTS.md) 和 [tasks/00–07](tasks/)。核对基线为 main 的代码合并提交 `0d4bc49`：WS0/WS1、PR #19/#18/#20/#23，以及 #22 的 Agent/Vault/个人界面、#24 的私有管理取消与独立计数、#25 的 mesh 计数均已合并。#22 经 #25 集成，保留原提交，GitHub 已标记为 MERGED。原工作区尚未提交的修改不算交付。 **结论：已有核心模块和较多自动回归，但尚未达到 tasks/00 的完整端到端验收标准。** 下文的“已实现”指代码存在；mock、预置互信和真实账户验收分别标明，不能互相替代。 +## 本轮合并核验 + +| PR | 最终分支头 | 合并前该头检查 | main 合并提交 | +|---|---|---|---| +| #20 本机代理 | `eedcc29` | 15 项全部成功 | `31fadaf` | +| #24 私有管理取消/独立计数 | `964a0cf` | 7 项全部成功 | `fd1ed77` | +| #22 Agent/Vault/个人界面 | `7ac8c99` | 15 项全部成功 | 经 #25 集成：`0d4bc49`（集成提交 `b4e3845` 保留原头） | +| #25 mesh 计数及完整集成 | `60d3443` | 15 项全部成功 | `0d4bc49` | + +表内检查是对应 PR 最终头的结果；旧头失败、取消或尚在运行的任务不计为通过。#25 的最终头包含 #22/#24，合入 main 后核验完整文件树与该已通过检查的头一致。 + ## 工作流对照 | 工作流 | 已实现及证据 | 缺少或尚未验收 | |---|---|---| -| WS0 契约/集成 | #16 提供 C1–C8、8 个 fixture round-trip 测试、crate 骨架、挂载点、归属及 CI；本次补第三方 NOTICE | 各模块已能编译不等于产品闭环；C3 count_tokens/取消登录、WS1 契约请求仍需协调 | +| WS0 契约/集成 | #16 提供 C1–C8、8 个 fixture round-trip 测试、crate 骨架、挂载点、归属及 CI；#23 补 count_tokens、取消登录的向后兼容接口，旧实现默认明确返回 Unsupported；本次补第三方 NOTICE | 共享接口已由 #23 单独评审；私有管理 API 取消与远端计数分别见 #24/#25，界面取消与 WS1 契约请求仍需收尾 | | WS1 iroh/relay/配对 | #17：默认 iroh、内置 relay、实时 grant/route allowlist、流式 PeerTransport、15 分钟一次性票据、双方独立确认 SAS；见 [交接](handoff/WS1-iroh.md) | Web/Tauri App 尚未调用真实配对；OwnerDevice 名册/OwnerKey 接入缺失；Windows 配对控制 CLI 尚为 Unix socket；Cloudflare 实机验收缺失；CLI/MCP 仍有 Noise 内层，路由迁移默认 opt-in | -| WS2 模型代理 | #18/#20：loopback 3424、安全检查、UDS/Windows pipe 管理面、Chat/Responses/Messages 3×3 转换、SSE/工具/reasoning、首字节前账号故障切换、亲和与冷却、curl 解析；见 [实现说明](../../crates/cranibox-llm/tests/IMPLEMENTATION.md) | count_tokens 仅部分本机原生 Messages/API key 路径可用，OAuth/远端未统一；取消登录尚未贯通 C3 管理 API 与 UI；跨节点 Claude 选择仅有本机占位 | +| WS2 模型代理 | #18/#20：loopback 3424、安全检查、UDS/Windows pipe 管理面、Chat/Responses/Messages 3×3 转换、SSE/工具/reasoning、首字节前账号故障切换、亲和与冷却、curl 解析；#24 接通私有管理登录取消、独立 Messages 计数与刷新，#25 补 mesh 计数及 501 透传；见 [实现说明](../../crates/cranibox-llm/tests/IMPLEMENTATION.md) | 四家 OAuth adapter 原生计数仍返回 501；取消登录的私有管理 API 已接通，界面尚无取消按钮；Claude 真实订阅和跨节点能力仍未交付 | | WS3 订阅/国内厂商 | #20：Codex PKCE+手动 callback、Kimi device code、Gemini CodeAssist、Copilot 短 token、刷新轮换、33 个 API key 预设；mock 协议回归齐备，见 [端点与边界](../../crates/cranibox-llm/tests/providers/ENDPOINTS.md) | 四家真实订阅账户及真实 API key 尚未验收；Gemini 需部署者 OAuth client/CodeAssist 条件；Windows 不同用户与 SMB 管理面拒绝待实机确认 | | WS4 Claude 节点 | #19 仅交付首轮 cch 可行性实验：Claude Code 2.1.303 对本地 mock 上游的 5 次请求未含 cch；见 [实验结论](../../crates/cranibox-llm/tests/claude/CCH-FINDINGS.md)。Vault 已有 ClaudeOAuth never_sync 约束 | 未实现真实 Claude 订阅 adapter/CLI 桥、迁移与旧节点凭据清理、跨节点 claude/* 对话及离线错误闭环；mock 结果无法推导官方真实上游行为。本工作流仍后置 | | WS5 Agent 适配 | #22：DSH 默认及固定六种 Agent 注册表；原生配置写入、备份、漂移检测、恢复/解绑、session/MCP；DSH 固定版本与 SHA 校验；Pi models 和 stdio MCP 扩展；六 CLI 经本地 mock 可对话 | Codex/Hermes/OpenClaw 的 approval capability 为 false，未接入统一审批；OpenClaw 直接改 openclaw.json，偏离任务书优先 config set 的要求；Pi 真 CLI 完整 MCP 工具回合待验 | -| WS6 名册/Vault/租约 | #22：Owner 签名及 epoch 防重放、HPKE 封装 OwnerKey helper、SQLite 每记录 XChaCha+HPKE、默认仅本机启用、租约 fencing/接管回切、撤销后 DEK 轮换、远端路由与健康探测；预置互信的三进程 TCP/Noise 转发与 Hub 退出回退已有回归 | WS1 配对尚未分发 OwnerKey/加入名册；Models 启动仍自行 bootstrap Owner，传输仍是 DirectTransport；未完成真实配对后的 iroh 全链路、网络分区/延迟、Hub 恢复 30 秒与流中断边界验收 | +| WS6 名册/Vault/租约 | #22：Owner 签名及 epoch 防重放、HPKE 封装 OwnerKey helper、SQLite 每记录 XChaCha+HPKE、默认仅本机启用、租约 fencing/接管回切、撤销后 DEK 轮换、远端路由与健康探测；同一进程内预置互信的三实例 TCP/Noise 转发与 Hub 退出回退已有回归 | WS1 配对尚未分发 OwnerKey/加入名册；Models 启动仍自行 bootstrap Owner，传输仍是 DirectTransport；未完成真实配对后的 iroh 全链路、网络分区/延迟、Hub 恢复 30 秒与流中断边界验收 | | WS7 个人界面 | #22：Web/Tauri 五栏、状态胶囊、引导、模型/设备/高级页、中英/主题、HTTP cookie+CSRF/SSE 与 Tauri IPC；桌面 tray/通知代码；主流程移除旧连接表单 | 配对 App API 仍为 503/404 占位；首页 DSH 仅本机 iframe、远端禁用，缺服务健康检查；专用配对/能力/Computer Use/模型写审批未接齐；三 OS 原生通知/tray、真实七条用户路径待验 | ## 会阻断完整体验的连接点 @@ -29,8 +40,11 @@ - WS2/WS3 的本机模拟上游回归及性能样本见 [IMPLEMENTATION](../../crates/cranibox-llm/tests/IMPLEMENTATION.md)；历史 120 样本附加延迟 p50 859 μs。该数字不是本次完整集成后的性能复测，也不是公网厂商时延。 - WS5–7 的原交付含六 CLI 假 key/mock 上游、Web/桌面浏览器测试与中英截图。配对截图/SAS 来自 mock，远端互信由测试预置，均不能视为真实设备首次配对验收。 - `tests/integration/vault_netns.sh` 需要网络 namespace 能力；跳过（77）不算通过。Cloudflare、真实订阅、Windows 不同用户/SMB、原生系统通知和 Pi 工具回合继续列为待人工验收。 -- 本次集成解决 Cargo.lock/Cargo.toml 冲突，并修复 Windows 对只读句柄重复 fsync 的拒绝访问，以及 gateway 节点提前占用固定模型端口导致多节点启动失败。`write_private` 自带 sync，保留持久化语义；模型服务由 App/mesh 路由按需启动。最终 CI 请按 PR #20/#22 的最新提交核验，旧头失败不构成修复后的结果。 -- CI 还暴露了测试脚本重复分配同一临时端口、节点关闭后身份锁仅依赖析构释放、Windows 配置快照受路径和 CRLF 影响的问题。本轮改为同时预留 Web/网关端口、关闭结束时显式解锁、验证原生配置路径后规范化快照；远端回归为协作 5 条、节点 64 条（另 4 条按环境忽略）、适配器 9 条通过。 +- 本次集成解决 Cargo.lock/Cargo.toml 冲突，并修复 Windows 对只读句柄重复 fsync 的拒绝访问，以及 gateway 节点提前占用固定模型端口导致多节点启动失败。`write_private` 自带 sync，保留持久化语义；模型服务由 App/mesh 路由按需启动。最终头检查结果见上表；完整集成源码由 #25 的 `60d3443` 验证，旧头失败不构成修复后的结果。 +- CI 还暴露了测试脚本重复分配同一临时端口、节点关闭后身份锁仅依赖析构释放、Windows 配置快照受路径和 CRLF 影响、Node ESM 不能直接导入 Windows 绝对路径的问题。本轮改为同时预留 Web/网关端口、关闭结束时显式解锁、验证原生配置路径后规范化快照，并用 pathToFileURL 导入测试桥接脚本；远端回归为协作 5 条、节点 64 条（另 4 条按环境忽略）、适配器 9 条、原生扩展 3 条（包含空格及保留字符路径）通过。 +- #20/#22/#23 的组合源码在指定远端隔离容器通过 workspace/all-targets 编译、格式检查及 11 条契约测试（1 条单元、8 条 fixture、2 条旧实现兼容测试）。2026-10-20 将 #22 的 `7ac8c99`、#24 的 `964a0cf` 与 #25 计数补丁合并，在 `/config/validation-sources/count-mesh-merge-20261020` 通过格式检查、workspace/all-targets Clippy、220 条 LLM 测试与 64 条节点测试，0 失败，另 5 项已有环境测试明确忽略。计数包含三节点 TCP/Noise、连续 501 不降级健康状态和 Hub 退出回退，仍使用预置互信。 +- #22 的 `03b7404` 保留日志后确认 Windows 节点因主线程栈溢出退出；`91919f5` 将 CLI 异步状态置于堆上，该头的 PR Windows native 与桌面检查均已通过。后续 `7ac8c99` 修复测试隔离和异步同步：Web harness 使用 App mock 避免多实例争抢 3424，项目绑定完成后再读取，重载显式选择项目，迁移后等待原 Shell 在新身份下重新接入；Windows 审批冷启动设有 30 秒上限，子进程提前退出立即失败。远端通过原生扩展 3 条、多实例网络 17 条、相关浏览器 5 条。#22 的最终头及随后 #25 的完整集成头均已通过全部 15 项检查。 +- #25 的 `a6ec412` 在两次 Windows CI 中均于 Hub 退出后的计数回退返回 503。测试修改 Hub 凭据也会推进启用列表版本，B 必须先接收该版本再添加自身；否则后台同步能覆盖 B 的旧版本。`60d3443` 显式同步 Hub→C、Hub→B 后再修改 B，并检查版本和 C 的启用列表。指定远端反向验证去掉同步时出现启用记录覆盖/NoSecret，恢复后同一用例通过；没有放宽状态断言或忽略失败。该最终头的 15 项 GitHub 检查全部成功后，#25 于 2026-10-20 合入 main。 ## 下一步优先级 @@ -40,7 +54,7 @@ | P0 | 远端 DSH 与审批来源补齐 | 浏览器可在 Hub 对话；各真实审批事件可批准/拒绝且决策到达执行端 | | P1 | Vault/刷新/路由故障验收 | 真实 iroh 多节点、网络分区/延迟、Hub 下线本机兜底、恢复 30 秒回切、撤销后不可解密、流中断不重放 | | P1 | 真实账户与系统验收 | 四家订阅/API key、Pi MCP 工具回合、Windows pipe 用户隔离、三 OS tray/通知、Cloudflare 按清单通过 | -| P2 | 契约与适配收尾 | count_tokens/取消登录贯通；OpenClaw config set 或经明确评审调整规格；WS1 待决策与 OwnerKey 恢复方案确定 | +| P2 | 契约与适配收尾 | 登录取消按钮及四家 OAuth 计数能力确认；OpenClaw config set 或经明确评审调整规格；WS1 待决策与 OwnerKey 恢复方案确定 | | 后置 | WS4 Claude 节点 | 明确真实上游可行路线，再做登录/迁移/清理/跨节点对话/离线错误验收 | 不使用一个完成百分比混合代码量、自动回归与真实环境验收；后续更新本文件时应附对应提交与可复现证据。