diff --git a/docs/proposals/2026-10-13-versioned-dependencies-and-workspaces.md b/docs/proposals/2026-10-13-versioned-dependencies-and-workspaces.md index e7488dc..409b68d 100644 --- a/docs/proposals/2026-10-13-versioned-dependencies-and-workspaces.md +++ b/docs/proposals/2026-10-13-versioned-dependencies-and-workspaces.md @@ -1,6 +1,6 @@ # 版本化依赖与按需源码工作区改造方案 r1 -状态:proposed;方案与以下实施顺序待人工评审,尚未切换现行规则。 +状态:approved(方案 r1,批准对象 commit `4a7b9293e9d74804833f98cebd52e235c9375d3c`);2026-10-13 用户批准重构,并要求当前及后续工作分支平稳过渡。实施计划细化、实施与自检连续推进;正式验收与发布边界保留。批准不等于机制已经切换。 负责人:weichen;编制:Codex;更新时间:2026-10-13(北京时间)。 需求来源:本次会话确认保留独立功能仓、替换 submodule 依赖方式,并保留从 Dev 按需修改功能仓的体验;同时提交通用规范与项目细则。 实施授权来源:用户「可以,帮我实现吧……之后的项目也都可以按照此思路来进行开发和管理」。该指示允许启动改造;本仓 `policy/delivery.md` 的具体方案、实施计划与验收评审,以及发布双钥匙边界仍须满足。本文不是对用户的代签批准。 @@ -43,8 +43,9 @@ | R12 | 旧版本可重建和回退 | 新源码部署入口能物化一个旧 submodule 候选及一个新版本依赖候选;不改业务数据库 | | R13 | 通用规则供后续项目采纳 | Guidelines 正文无本项目仓名、主机、端口、秘密路径;模板声明依赖权威、开发覆盖与正式门禁 | | R14 | 规则与能力一致 | 项目规则、脚本、CI 与实际检查一致;通用合入不自动修改其他项目的固定规则 | +| R15 | 在途及后续分支平稳过渡 | 不改动其他活动工作区;旧版本构建保留;显式迁移保留分支/提交/未保存文件;新任务默认新布局;真实仓覆盖旧任务同步、组件修改、冲突和回退 | -R1–R14 均纳入本方向;本次仅确认了目标与实施请求,本文新增的具体契约和验收表待评审。没有实测的能力保持 NOT_RUN。 +R1–R14 随 r1 获批;R15 来自本次批准消息的明确约束,纳入同一改造。没有实测的能力保持 NOT_RUN。 ## 3. 依赖权威和目标目录 @@ -188,7 +189,7 @@ U1 未通过不执行 U3 的公开路径推广;U5 未通过不移除旧 submod 推荐评审本文后批准 U1–U7 的实施顺序;U1 的真实下载与编辑准备验证是后续推广的硬前置,失败即停止受影响工作。若用户明确授权按本文连续完成实施与自检,记录授权范围,仍保留正式验收、平台准入与双钥匙边界;未取得连续推进授权时按项目阶段和增量逐项评审。 -目前:启动检查与独立工作区已建立;本文待审;U1–U8 实施、迁移测试、PR、发布与部署均 NOT_RUN。 +批准记录:用户「批准,可以进行重构,但要注意的是,当前还有其他工作中的分支,要保证这些和后续的工作分支都能够平稳过渡」。实施进展及命令证据放 Dev 任务卡,不能从批准推断任何测试、合入、发布或部署结果。 ## 10. 官方依据 diff --git a/docs/proposals/2026-10-13-versioned-dependencies-implementation-plan.md b/docs/proposals/2026-10-13-versioned-dependencies-implementation-plan.md new file mode 100644 index 0000000..1096f84 --- /dev/null +++ b/docs/proposals/2026-10-13-versioned-dependencies-implementation-plan.md @@ -0,0 +1,110 @@ +# Versioned Dependencies and Component Workspaces Implementation Plan + +> **For agentic workers:** Use ce-work native subagents for independent units and host-owned verification/commits. Steps use checkbox syntax; progress is recorded in the Dev task card and commits, not by rewriting this plan. + +**Goal:** 保留独立仓库及 Dev 单入口,以真实版本依赖和按需编辑源码工作区替换重复 submodule,并让在途分支安全过渡。 +**Architecture:** 项目清单提供批准来源和模块映射;应用/文档锁固定源码,语言依赖由消费方解析。工作区工具处理普通 clone、开发覆盖和过渡;正式构建隔离开发覆盖,旧提交继续使用旧物化方式。 +**Tech Stack:** Python 3 标准库、Git、Go 1.27、npm/TypeScript/Vite、现有 Make/evidence/Gitea CI。 +**Spec:** [已批准方案 r1 与 R15 补充](2026-10-13-versioned-dependencies-and-workspaces.md)。 +**Execution authority:** 2026-10-13 用户批准上轮请求的具体方案与实施顺序,允许计划细化、重构及自检连续推进;正式验收、共享部署和发布不被该授权替代。 + +## Global Constraints + +- Go 模块身份采用 `git-ssh.u1680832.nyat.app/weichen/.git`,子模块追加目录;端口只属于传输。 +- 正式构建 `GOWORK=off`、无本地路径 replace;私有获取的 Git 配置限进程,禁止全局改写。 +- 不修改其他活动工作区;不重写历史、不发布 tag、不操作运行服务和业务数据。 +- 原生临时 Git 仓覆盖正常、拒绝及失败恢复;命令输出由 evidence 保存,来源 SELF 不提升。 +- 原旧 submodule 提交可重建;新功能分支默认新布局;迁移是显式操作,不能静默 stash/reset/提交他人现场。 + +## Review Focus + +1. 删除 gitlinks 后遗留的 `.git` 管理目录可能仍被其他 worktree 使用:保留原目录,拒绝回收外部依赖。 +2. 老组件分支含未提交和未推送代码:先报告并复制到独立新工作区,原现场保持不动;冲突交给 owner。 +3. 发布构建误消费 go.work/npm 链接:构建单独物化固定源码,导出实际模块图和资产摘要。 +4. 私有 Go/Git npm 获取期间运行候选代码:认证获取与无凭据执行分阶段,并验证来源白名单。 +5. 新主干合入时旧任务仍使用旧脚本:提供版本识别、显式迁移入口及分支过渡操作说明,不强制修改所有检出。 + +## U1. Prove remote module consumption + +**Files:** Logging-System/Error-Code-System 的 go.mod、Go import、README;Dev 传输检查及源码记录。 +**Consumes:** 批准模块映射、现有 SSH 访问;**Produces:** 可获取的两个候选提交与 Go 自动生成的 pseudo-version。 + +- [ ] 从各仓本次获取的 origin/main 建独立任务分支;保留其他 worktree。 +- [ ] 先在隔离消费方证明旧短模块无法按新路径直接消费;写清被测 SHA 和失败类型。 +- [ ] 机械改模块声明和 import,在组件内运行 `GOWORK=off go test ./...`;此机械配置改动以编译/独立消费替代镜像测试。 +- [ ] 保存并推送候选分支(非 tag/版本发布),以进程级 SSH 映射运行干净缓存的 Go 下载和真实调用。 +- [ ] 成功才推广;失败保留现场、修复已批准传输机制,不以本地 replace 通过代替远端消费。 + +## U2. Prepare editable component workspaces + +**Files:** Dev `scripts/workspace.py`、`scripts/workspace/`、`tests/test_workspace.py`;清单与 Make 接线由 host 集成。 +**Consumes:** `components.json` 的 schema=1、components 列表(id/repo/path/legacy_path/role/modules/target);应用/资料锁的固定 commit; +**Produces:** prepare/edit/unlink/status/verify/transition CLI,`.workspace/state.json` 及本地 go.work。 + +Public CLI: `python3 scripts/workspace.py [--root ROOT] prepare|edit|unlink|status|verify|transition [--name ID] [--branch feature/SLUG]`;transition 默认只报告,显式 apply 才准备新现场。 + +- [ ] 先建真实临时远端测试:prepare 固定 commit;edit 建独立分支;错误名称、路径逃逸和不匹配 origin 被拒。 +- [ ] 运行新测试并记录预期失败,再实现最小清单/Git/状态模块。 +- [ ] 补充分支、脏/ignored 文件、Git 锁、部分 clone、幂等重试、开发链接/解除测试;通过实际 Go 调用验证覆盖。 +- [ ] 库编辑基线优先解析消费方实际 Go 模块版本及 Origin;旧布局只在过渡时从原 gitlink 获取,不能默认最新 main。 +- [ ] transition 报告和准备均保留原 legacy 仓、refs、未保存文件;不会修改其他登记工作区;不能把冲突称为成功。 +- [ ] 测试通过后 host 检查并按本单元实际文件提交。 + +## U3. Migrate Go providers and consumers + +**Files:** Core/Native/Intent/Command/Squad 及 adapters/cmd、Backend、RDM 的 Go 源码、go.mod/go.sum、README/边界检查。 +**Consumes:** U1 可用传输/候选版本;**Produces:** 无源码目录 replace 的组件和两个实际消费方。 + +- [ ] 每个组件从本次权威 main 起步,记录仓库与基线;批量改 import 前核对标准 import 块及 Go internal 范围。 +- [ ] 按 Error/Logging → Core/Native/Intent/Command → Squad 子模块 → Backend → RDM 的实际依赖顺序提交候选。 +- [ ] `go get MODULE@COMMIT` 生成版本;保留实际第三方版本,核对 MVS 差异,不抬高无关依赖。 +- [ ] 各模块跑 `GOWORK=off go test ./...`,Backend/RDM 干净构建;新旧版本路径明确,不遗留短模块本地 replace。 +- [ ] 更新边界规则的模块前缀,不重置业务分层基线;在途分支的新代码用显式前缀迁移辅助检查。 + +## U4. Package UI and contracts + +**Files:** Core TS 契约包、UI package/出口、Frontend package/lock/Vite/TS 配置与包消费测试。 +**Consumes:** 固定 Core 类型及 UI 源码;**Produces:** `@agent-system/contracts`、`@agent-system/ui` 包出口及无需相邻源码的前端构建。 + +- [ ] 读取 DESIGN 和三仓指引;先验证 npm pack 成员、类型/CSS 出口和独立 consumer 缺包时失败。 +- [ ] 契约由 Core 单一源码生成;UI/Frontend 声明包依赖,保留 @ui 调用的包出口适配。 +- [ ] 包版本/来源固定于提交及 npm lock,不依赖未批准 Registry 发布;所有包生成/生命周期在无 checkout 凭据环境运行。 +- [ ] 运行 UI typecheck/test、Frontend build/test、两份 design-guard;检查 React 单副本和实际包消费。 +- [ ] 新包提交 SHA 由 host 回填消费方锁;作者不自行提交共享代码或推送。 + +## U5. Adapt build, governance and historical materialization + +**Files:** Dev Makefile、task.sh、check-worktree.py、evidence.py、check-evidence.py、边界脚本、CI、svc.sh、相关真实仓测试。 +**Consumes:** U2 CLI 和 U3/U4 固定候选;**Produces:** 新旧布局均可运行、当前对象可取证的工具入口。 + +- [ ] 扩充现有 test_task/test_evidence/test_ci_credentials/test_svc 用例,先观察旧实现失败。 +- [ ] 新布局 task-start 不递归初始化;task-sync 识别旧任务并报告迁移;prepare 不覆盖编辑分支。 +- [ ] evidence 记录源码清单、组件实际 HEAD/dirty 与包图,保持旧收据可读;finish 保守核对独立 worktree 和 ignored 唯一文件。 +- [ ] 凭据阶段只允许固定身份获取;候选代码执行环境移除凭据;CI 验证固定来源和当前 HEAD。 +- [ ] Make 构建在独立固定目录装配 frontend dist/backend embed,输出 resolved manifest;源码部署按候选版本选择物化器。 +- [ ] `make test-governance`、`make test`、`make build` 和历史候选 fixture 通过后提交。 + +## U6. Capture reusable standards and project adoption + +**Files:** Guidelines multi-repo/collaboration/adoption/README/templates/CHANGELOG/VERSION;Dev policy/dependencies、AGENTS/PROJECT;Documents。 +**Consumes:** 批准原则和实测接口;**Produces:** 项目无关通用条文、显式项目采纳及旧分支过渡说明。 + +- [ ] 通用正文不包含本项目名称/端口/凭证;固定快照和语言依赖作为可选默认,保留 submodule 兼容方式。 +- [ ] 写明旧任务/新任务/组件 owner 的过渡职责、覆盖/回退和凭据边界;其他宿主不自动采纳。 +- [ ] 文档检查差异、相对链接、义务强度和术语;VERSION 的草稿递增不等于发布 tag。 +- [ ] 依据 U2/U5 已验证行为填项目命令和执行能力;未验证 platform 能力不标 enforced。 + +## U7. Cut over without damaging active branches + +**Files:** Dev manifests、.gitmodules/gitlinks、.gitignore、workspace-transition 接线与分支过渡指南;组件 legacy deps/pins。 +**Consumes:** U1–U6 实测出口;**Produces:** 新 clone 无 submodule 构建,旧任务和版本仍可复现。 + +- [ ] 保存活动工作区只读清单及其元数据;全过程不 checkout/reset/stash/clean 他人现场。 +- [ ] 只移除本任务索引中已替代 gitlinks;保留旧物理目录和 Git 管理数据,不通过目录删除来完成迁移。 +- [ ] 临时真实仓模拟旧任务独有组件 commit、未提交/ignored 文件、旧 PR 合入、主干前进和文本/接口冲突;原内容可复核且拒绝路径诚实。 +- [ ] 新 clone prepare/build/test 和本地 Native 编辑/解除链路,RDM product/product-smoke 均验证。 +- [ ] 最终候选固定后提交正式验收材料;未获正式验收结论不声称可合入。 + +## U8. Review, merge and close + +独立重放与代码 Review、最新 main 同步、精确 HEAD 的 GATE CI、实际 PR 合入和 owner 授权的回收分别记录。禁止以 SELF 或计划文件代替正式放行;本实施终点先到可审实现与自检,后续人工验收和发布边界保留。