weichen/Agent-System
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ed4e17c81974c6d2b126fedb1ca4ed1e2c6c207f
Agent-System/.doc/remediation/2026-09-29-multi-repo-implementation-plan.md
T
weichen 8b4db5fe83
CI / go-vet-and-short-test (pull_request) Failing after 0s
Details
CI / backup-restore-drill (pull_request) Failing after 0s
Details
CI / web (pull_request) Failing after 2m11s
Details
docs(multi-repo): U1 closeout - baseline inventory, governance drill record, implementation plan 
- U1.4: dev synced fast-forward (fabd85a6..1bb48030, 337 commits), 11 tags pushed
- D5: 25 merged stale remote branches deleted, 10 remain
- U1.5 drill: branch protection N1-N5 all pass; self-approval forbidden by Gitea
  -> D2' amendment: agent-bot account created (author/reviewer separation)
- CI root cause found+fixed: docker network pool exhaustion (24 stale job networks pruned)
- D7: new migration workspace directive (no in-place Agent-System breakage)
2026-09-29 02:34:12 +00:00

17 KiB
Raw Blame History

title, date, type, task_id, basis, policy_state, execution_authority
title date type task_id basis policy_state execution_authority
多仓库架构实施方案：U1–U10 执行计划 2026-09-29 implementation-plan multi-repo-design-2026-09-28
.doc/remediation/2026-09-28-multi-repo-architecture-plan.md (rev 7)
.doc/audit/2026-09-28-multi-repo-evidence.md
2026-09-29 只读基线核实（Gitea API + 本地仓库）
proposed design_only; implementation requires user approval

多仓库架构实施方案（待审，不生效）

本文件把 2026-09-28 架构方案（rev 7）的 U1–U10 落成可执行的分阶段计划： 每个阶段给出前置、具体步骤（含 Gitea API/命令级细节）、验收、回退和暂停准则。 所有写操作（推送、建仓、改保护、停旧入口）都需用户按阶段批准后才执行；本文不构成授权。

一、2026-09-29 基线核实结果（只读）

与证据文档一致的事实

  • Gitea 1.27.3，读取身份 weichen（实例 admin）。
  • 六仓库：Agent-System 与 Development-Manager 非空，其余四个（Squad / Development-Documents / Development-Guidelines / Releases）仍为空、public、default=main。
  • Agent-System 远端 dev/test/main 未动：fabd85a / 0e4b111 / 210fe4a；Development-Manager 远端 dev=8867e38 与本地一致、干净。
  • 两仓 branch_protections 均为 []，releases 为空。

相对证据文档的关键更新

# 更新事实 对方案的影响
N1 实例级 runner 存在且在线：home-runner（id=1，online，labels：ubuntu-latest/docker/nightly） 架构方案"实施前须核实 runner"的前置已满足；U1/U2 的 Gitea 原生 CI 门禁可直接落地，但仍需用一个真实 workflow 验证标签匹配与执行语义
N2 本地 dev 领先 origin/dev 从 306 → 337 提交，HEAD 1bb48030（含方案三文档、rc-v1.1.0-beta.5/6 晋升、多个产品修复）；无 behind，纯 fast-forward U1 的"差异同步"对象扩大；同步本身仍是 U1 第一决策
N3 远端分支从 3 个 → 29 个（大量 2026-09-22~23 的陈旧 feature/* 分支） U1 基线盘点需含远端分支清理清单
N4 实例单用户（weichen，admin）、无组织 KTD4 的"每人一个 fork"退化场景成立：首期不需要 fork，直接 repo 内 feature 分支 + PR（见决策 D2）
N5 工作区有一个未提交删除：.cursor/rules/agentctl-mandatory.mdc 属于 U2a 内容，不应混入 U1 基线同步；先恢复，在 U2a 作为首个提交处理
N6 workflows 仍仅在 .github/workflows/（ci.yml、nightly-real-pi.yml），无 .gitea/workflows/ U2b 切换 CI 时需确认实例 ACTIONS 路径配置，避免双跑（沿用架构方案 KTD CI 节）

凭证说明：~/.secrets/gitea 为 YAML（url_prefix + access_token 两键），token 对 API 有效（token/Bearer 均可）。本文件不含凭证值。

二、总体执行序列

Phase 0  U1  基线与治理试点 ──────────────出口：治理替代清单可审、远端同步完成
Phase 1  U2a 本地减负 ─→ U2b 远端交接 ───出口：编码流程零 agentctl 依赖（V19–V26）
Phase 2a U7a Agent-Native 契约（最小模块）─出口：contract SHA 可供 U4 消费
Phase 2b U4 Squad 提取   ∥  U7b Native 内核提取
         U3 文档仓拆分   ∥  U8 Web 拆分   ∥  U10 单文件/多实例（可在现仓并行早启）
Phase 3  U5 外层仓收口 ─→ U6b 多仓组合发布
早交付线 U10 → U6a 单仓单文件内部 RC（不等待拆仓，Phase 0 后即可并行）
独立线   U9 PI parity（依赖 U7a 契约；能力盘点 U9a 可随时提前）

架构方案定的依赖顺序不变：U1→U2→U7a→U4/U7b；U3/U8 穿插；U5 收口；U9 独立验收。 每个 Phase 出口都是一个可暂停点：保留当时已验证的组合，不半开新门禁。

三、需用户确认的决策点（开工前批准）

ID 决策 建议 理由
D1 337 提交如何同步到远端 dev 整体 fast-forward push dev（不 push 全部分支）；test/main 暂不动 无 behind、无分叉，机械安全的路径；远端 dev 自 2026-09-24 起未变，阻塞了 U1 之后一切远端治理试点。push 前先 git push --dry-run + 备份 git bundle
D2 单用户下的协作模型 不建机器人账号 → D2'（09-29 演练修正）：已创建机器账号 agent-bot。演练证实 Gitea 1.27.3 硬禁止自批准（author approve own pull → "approve your own pull is not allowed"，admin 亦不可），单账号下 required_approvals 永远无法满足。最终模型：编码 Agent 以 agent-bot 提交/建 PR，用户以 weichen 批准+合并。不建 fork 见演练记录；agent-bot 凭据在 ~/.secrets/agent-bot（token scope: write:repository, read:user）
D3 新仓库创建时机 只新建 3 个：Agent-Native（U7a 时）、Agent-System-Web（U8 时）、Agent-System-Core（U5 时）；Agent-System-Releases-Internal（U6a 前，private）。其余 4 个复用空仓 仓库跟着实施单元走，避免空壳仓库先行；Releases-Internal 必须 private 并做匿名拒绝验证（V5）
D4 runner 信任边界 实例 runner 只有一台；U2b 起 PR 触发的 workflow 一律无秘密、无共享环境写权限（nightly 标签任务除外，它持部署凭证但只由 protected 分支/维护者触发） 单 runner 同时服务不可信 PR 代码与可信 nightly，必须按 Gitea Actions token 权限文档隔离；架构方案 CI Trust 节的落地
D5 29 个远端陈旧分支 U1 盘点后按清单删除已合入 dev 的；保留 dev/test/main 与仍活跃的（如 feature/squad-missing-target-retry 系列） 分支堆积干扰 U1 基线与后续 PR 流；删除可逆（reflog + 对象仍在）
D6 工作区未提交的 .cursor/rules/agentctl-mandatory.mdc 删除 U1 先 git restore 恢复；到 U2a 随"解除强制 hook"提交一起删除 保持 U1 基线同步为纯 fast-forward，不夹带治理变更
D7 （09-29 用户指令）不破坏现有 Agent-System 系统：所有拆分/迁移工作放入 ~/projects/ 下新目录（单一目录+submodule 结构，即未来外层仓工作区）；对现有仓的一切治理变更走 feature 分支 + PR，不直接改 dev 运行状态 新目录承载 Agent-Native/Web/Squad/Documents/Guidelines 各组件仓 clone 与外层结构；现有 Agent-System 保持在原位运行，直到 U5 收口以普通提交完成外层化 用户 09-29 指令；与 R9 可迁移可停止一致

四、Phase 0 — U1 基线与治理试点（预计 1–2 日）

目标：远端与本地一致、治理演练仓验证 Gitea 原生门禁真实行为、产出 U2 所需的完整替代清单。

步骤

  1. 本地备份：git bundle create ../agent-system-dev-$(date +%F).bundle --all 并验证 git bundle verify；记录恢复步骤。
  2. 处理脏工作区（D6）：git restore .cursor/rules/agentctl-mandatory.mdc。
  3. 盘点（只读，产出清单文件）：
    • 本地/远端分支映射表（29 远端 + 本地 feature/* 与 docs/*），逐条标注 keep/delete/merge-pending；
    • 活跃 worktrees（当前 3 个：u9u12-keys-rollout 注册在册，另 2 个目录核查归属）；
    • 运行制品身份：rc-v1.1.0-beta.* tags、主仓树内 *.test 二进制清单（后续移除对象，历史不重写）；
    • .locks/state.sqlite 快照（busy/recovery_required 计数）与活跃 agentctl 任务。
  4. 同步主干（D1 批准后执行）：git push --dry-run origin dev 核对 fast-forward → git push origin dev。不 push 其他分支；test/main 不动。
  5. 建演练仓（一次性、可删）：创建 weichen/governance-drill-2026-09（临时 private），在其中验证以下 Gitea 原生行为，逐项记录证据（对应架构方案 V6/V23 的前置）：
    • 分支保护 API：POST /repos/weichen/governance-drill-2026-09/branch_protections，字段组合：enable_push=false、required_approvals=1、block_on_official_review_requests=true、dismiss_stale_approvals=true、status_check_contexts=["ci/verify"]；
    • 验证旁路负例：API/Web/HTTP 直推被拒；无 approve 的合并被拒；head 更新后旧 approve 被撤销；required check 缺失时合并被拒；
    • 合并语义：merge/rebase/squash 各触发一次，记录 merge_commit_id/head_commit_id 行为，确认"合入后 tree 可核验"路径；
    • runner 真实执行：push 一个最小 workflow（on: pull_request，runs-on 匹配 ubuntu-latest 或 docker），确认实例 runner 认领并跑通，验证 job token 权限边界（尝试跨仓读应失败）；
    • .github/workflows/ 与 .gitea/workflows/ 双路径是否双跑（决定 U2b 迁移路径）。
  6. 产出：.doc/ops/ 下新增《U1 基线清单》+《Gitea 门禁演练记录》；按 KTD13 更新 retain/replace/remove 矩阵为最终可审版。

出口 / 回退

  • 出口：远端 dev=本地 dev；演练仓全部负例有证据；D5 清单获批；U2 范围冻结。
  • 回退：主干 push 不改变历史（纯 fast-forward），无需回退；演练仓直接删除。
  • 暂停准则：演练中任一门禁旁路成功（负例失败）→ 停止 U2 计划，先解决实例配置。

五、Phase 1 — U2 治理切换（预计 3–5 日，U1 后重估）

U2a 本地减负（先做，只依赖 U1 的基线核对）

  1. Development-Manager 侧修改 agentctl 职责（KTD13/KTD15）：
    • 删除普通编辑/提交的全局 with/SQLite 前置；锁域改为 workspace_id+path 局部身份；
    • overlaps 不再比较 path:. 类全局资源；候选冲突只隔离该候选工作区；
    • 失败分类落地：preflight_rejected / failed_known / outcome_unknown（V21）；
    • task 子系统退出编码流程：不再要求 register/claim/lease/close（历史只读保留）。
  2. 主仓侧配套（一次提交，含 N5 的 hook 删除）：
    • 删除 .cursor/rules/agentctl-mandatory.mdc 与对应 hook 转发；
    • AGENTS.md/PROJECT.md 按三层规范（Guidelines → 各仓短文件 → CI/执行器规则）改写；
    • 保留纯 Git 主干误提交保护、秘密防护、单工作区 owner。
  3. 新增测试（Development-Manager）：test_workspace_isolation.py、test_operation_outcomes.py、test_task_lifecycle.py、test_cleanup_allowlist.py；主仓保留与新合同相符的 test_agentctl*.py 子集。
  4. 验收（V19/V20/V22/V26 前半）：两个 worktree 改同路径互不阻塞；停 daemon/损坏缓存仍可本地开发提交；完整"修复→测试→提交→PR"流程零 agentctl 调用。

U2b 远端交接（依赖演练仓全部负例通过）

  1. Agent-System 正式设置分支保护：dev/test/main 按演练确认的字段组合（D4 信任边界）；首期 required_approvals=1 由用户人工 approve（D2）。
  2. 迁移 CI 到确定路径（避免双跑，N6）；PR workflow 无秘密；nightly 保持维护者触发 + nightly 标签。
  3. 停用旧本地 dev 推进入口（git-push-dev.sh 直推路径、agentctl integrate 入口）：先排空在途操作（agentctl status 无 running/busy），记录旧新权限清单，同一提交内生效。
  4. 切换验证（V23）：旧 token/hook/本地 integrate 不能推进远端；无 approve/CI 的 PR 不能合并；陈旧 head 不能合并。
  5. 四类日常演练（V24）：文档微调 / 单组件 bug / 跨仓 API 变更 / 共享 DB 迁移，确认低风险不再被旧模板强制全流程。

出口 / 回退

  • 出口：远端唯一写权威=Gitea 保护分支+PR；本地编码零 agentctl；治理命令调用数显著下降（记录基线对比）。
  • 回退：若保护/CI 行为异常，恢复旧入口前必须先关闭新写权威（不同时双开）；保留旧管理库只读。

六、Phase 2 — 组件拆分（可部分并行）

U7a Agent-Native 最小契约（预计 1–2 日，Phase 1 后立即）

  1. 现 chat-agent-system 仓内冻结助手/Squad 执行行为与副作用语义（不改默认后端）；
  2. 定义 contract 包（Execute 输入输出/事件/错误/能力/取消），不依赖 config/workspace；
  3. 新建 weichen/Agent-Native 仓（D3），首提交只含 contract + go.mod + conformance fake 测试；
  4. 推送、打 tag（如 contract/v0.1.0），产出 U4 可固定的 SHA。

U4 Squad 提取（预计 5–8 日）∥ U7b Native 内核（预计 4–7 日）

  • U4 按 KTD1：先现仓依赖注入/材料解析去耦（保持行为）→ filter-repo 抽取至 Agent-System-Squad（复用空仓）→ 主仓留临时 facade 适配 29 个调用文件 → 迁移算法测试 + 新增双侧 contract_test。主仓以相邻 replace（../squad、../agent-native）联调，GOWORK=off 正式构建。
  • U7b 迁 agentx/runtime、工具/模型/执行会话、PI transport 适配器至 Agent-Native；pi-native 旧名 alias、AGENTX_* 配置、transcript 根兼容期保留（V16）。
  • 共同出口：两库均无 chat-agent-system/internal/* import、可独立 go build/go test；真实 PI 与 Native 分别验证，fallback 不冒充 native PASS（V13）。

U3 文档拆分（预计 2–3 日）

  • 通用规范 → Development-Guidelines（复用空仓）；静态设计/审计 → Agent-System-Development-Documents（复用空仓）；
  • 机器契约 module-boundaries.yaml 留代码仓 configs/architecture/；CURRENT/MATRIX 活动文档暂留原路径（KTD2 首期不整体替换）；
  • 主仓建 development/ gitlinks；文档仓内容经 PR 合入后由主仓 gitlink 显式采纳；
  • 历史导入前先扫描将公开内容（架构方案 Risks 节的阻断出口）。

U8 Web 拆分（预计 3–5 日）

  • 迁 web 源码/npm 锁/前端测试至 Agent-System-Web（D3 新建）；Go embed 入口留应用侧 internal/webassets；
  • 构建链：固定 Web SHA → npm ci && npm run build → dist 物化到隔离构建上下文 → 摘要校验后编译；
  • static_assets 多路径猜测在发布模式禁用（V15）；新增 test_web_asset_assembly.py 与 manifest 校验。

U10 单文件/多实例（可与 Phase 2 并行，基于 U1 最低基线）

  • U10a：迁移 SQL/prompts/xlsx 等内嵌 fs.FS；同一程序 serve/init/migrate/config 子命令；
  • U10b：ConfigSnapshot 统一（默认→.env→进程 env→CLI→instance-settings），字段唯一 owner，saved/applied 分离（V28/V32）；
  • U10c：实例隔离（instance_id/目录重叠/cookie 独立/进程归属，V29–V31/V33/V34）；managed-local PG 为可选后续 profile，首期 CLI 明确 unsupported。

七、Phase 3 — 收口与发布

  • U5 外层仓（2–4 日）：剩余产品代码 → Agent-System-Core；主仓变纯组合入口（components.yaml + gitlinks + 构建配方）；验证全新 recursive clone / 源码 bundle / 无原路径构建（V9）。
  • U6b 多仓发布（2–3 日）：同一配方切换固定组件组合，重跑 U6a 全部验收；私有 RC → 用户审批 → 公开晋升，附件摘要一致（V5/V10/V11）。

八、早交付线 — U10 → U6a 单仓单文件内部 RC

Phase 0 后即可并行：在现单仓完成 U10a/U10b 最小集 → scripts/build-single-binary.sh 完善 → 干净 Ubuntu 26.04 amd64 验收（V9/V27 部分）→ 发布至 Agent-System-Releases-Internal（新建 private，D3）→ 匿名/无权限下载拒绝验证（V5）。不等待任何拆仓。

九、独立线 — U9 PI parity

U9a 盘点（1–2 日）可立即做：固定上游 0.85.1 三层基线，产出 parity matrix（available/partial/missing/not_required + 证据）。U9b–e 依赖 U7a 契约与 U7b 内核；全程禁用 fallback 验收 native（V17/V18），分批计划在 U9a 后单独报批。

十、风险与暂停准则（汇总）

风险 触发信号 动作
Gitea 保护旁路 演练负例未全部拒绝 停 U2b；不上线新权威
单 runner 被不可信代码滥用 PR workflow 越权访问跨仓/秘密 收紧 token/标签路由；必要时暂停 PR CI
拆仓等价性破坏 Squad/Native contract 回归失败 保留旧组合；该组件暂停，其他组件不受牵连
单文件验收失败 干净机启动缺资产/误连 dev DB U6a 不发布；修 U10 对应项
历史含敏感内容 公开导入扫描命中 阻断对应仓库公开化；仅走内部包
在途治理操作未排空 切换时存在 running/recovery_required 延后 U2b 切换；不清空管理库

三条独立回退路径保持不变：产品代码回退（git）、部署制品回退（Release 附件）、DB/用户文件恢复（备份）。

十一、验收映射

V1–V5/V10/V11 → Phase 0/U6；V6/V23/V24 → Phase 1；V13/V16/V19–V22/V25/V26 → Phase 1–2；V7/V8 → U4/U3；V9/V15/V27–V34 → U10/U6a/U6b；V12 → U5/U6b；V14 → U7 后新增 adapter 时；V17/V18 → U9。全部证据落 .doc/audit/ 或 Release 元数据，绑定最终 SHA。

Definition of Done（本方案自身）

用户批准决策点 D1–D6 并批准首个 Phase 后，本文件升级为生效执行计划；各单元完成以架构方案 Definition of Done（U1–U8、U10 出口 + V 证据）为准。未获批准前，一切远端写操作不执行。

Reference in New Issue View Git Blame Copy Permalink