From de90d0cd70e5cfadbd680e8caf8bdf18724e44a8 Mon Sep 17 00:00:00 2001 From: weichen Date: Mon, 28 Sep 2026 07:50:51 +0000 Subject: [PATCH] docs: propose multi-repo architecture and release workflow --- .doc/audit/2026-09-28-multi-repo-evidence.md | 153 +++++ .../2026-09-28-multi-repo-design.md | 70 +++ ...2026-09-28-multi-repo-architecture-plan.md | 553 ++++++++++++++++++ 3 files changed, 776 insertions(+) create mode 100644 .doc/audit/2026-09-28-multi-repo-evidence.md create mode 100644 .doc/ops/short-term/2026-09-28-multi-repo-design.md create mode 100644 .doc/remediation/2026-09-28-multi-repo-architecture-plan.md diff --git a/.doc/audit/2026-09-28-multi-repo-evidence.md b/.doc/audit/2026-09-28-multi-repo-evidence.md new file mode 100644 index 00000000..67114ce4 --- /dev/null +++ b/.doc/audit/2026-09-28-multi-repo-evidence.md @@ -0,0 +1,153 @@ +--- +title: "多仓库架构研究证据与审查记录" +date: 2026-09-28 +task_id: multi-repo-design-2026-09-28 +evidence_basis: current_source_and_readonly_api +--- + +# 多仓库调研证据 + +范围：[待审方案](../remediation/2026-09-28-multi-repo-architecture-plan.md)。 +记录只读 API 和源码事实，不包含业务正文、凭证值、认证头、原始数据库或敏感截图。 +未对远端执行 POST/PATCH/DELETE，也未 push、部署或创建远端仓库。 + +## Git and Gitea + +本地研究基线：dev@a3db288a7aa055ff5884e3aa4d91511959cff721，开始时主目录干净。 +任务 worktree：.worktrees/multi-repo-design-2026-09-28，分支 feature/multi-repo-design-2026-09-28。 +`git rev-list --left-right --count fabd85a65e15f3417431ba6f004a8bcdf9cb83cb...a3db288a7aa055ff5884e3aa4d91511959cff721` 返回 `0 306`。 +因此领先 306 不是仅依据缓存 origin/dev；远端实时 API 的 SHA 与缓存一致，且祖先关系已核对。 +本轮未 fetch 修改 remote-tracking ref，未同步远端。 + +Gitea GET /api/v1/version 返回 1.27.3。 +GET /api/v1/user/repos 分页（本次一页已取完六仓），仅保留所需元数据： + +| 仓库 | private | empty | default_branch | description | 结论 | +|---|---|---|---|---|---| +| weichen/Agent-System | false | false | dev | 空 | 保留主仓 | +| weichen/Agent-System-Squad | false | true | main | 空 | 名称可复用，尚无组件内容 | +| weichen/Agent-System-Development-Documents | false | true | main | 空 | 可复用，导入内容须分类 | +| weichen/Development-Guidelines | false | true | main | 空 | 可复用 | +| weichen/Agent-System-Releases | false | true | main | 空 | 只适合公开发布目标 | +| weichen/Development-Manager | false | false | dev | 空 | 已有治理工具，不应重建覆盖 | + +仓库 has_actions=true 只证明设置开启，不证明 runner/CI/权限可用。 +所有六仓当前读取身份有 admin/push/pull 权限；此事实不扩大本轮授权。 + +Agent-System 实时分支摘要： +- dev: fabd85a65e15f3417431ba6f004a8bcdf9cb83cb +- test: 0e4b111dff3726f5379e8168e3d00a244e111747 +- main: 210fe4a7bb2fd56c34a215c53e07617cccf81e49 +- 三分支 protected=false，GET branch_protections 返回 []。 + +Development-Manager 的 branch_protections 同样返回 []。 +两仓 GET releases?limit=3 返回 []；只说明本次未列出发布记录，不把 Git tags 当 Releases。 +两仓 repository-level GET actions/runners 返回 runners=[]；没有检查实例级/组织级 runner，不推断整个实例无 runner。 +四个 empty 仓的 branches 返回 null，与 empty 状态一起解释为没有可列出的分支，不虚构 main 已有提交。 + +读取本机 /swagger.v1.json： +MergePullRequestOption 的 do enum 包含 merge/rebase/rebase-merge/squash/fast-forward-only/manually-merged； +包含 head_commit_id、merge_commit_id、force_merge。 +BranchProtection 包含 required_approvals、dismiss_stale_approvals、block_on_outdated_branch、status_check_contexts、push/merge allowlist 等。 +这是字段证据，未验证运行语义；方案 U1/U2 要做授权演练。 + +## Existing Development Manager + +远端 README/PROJECT/MIGRATION 当前可读。 +MIGRATION 记录：2026-09-24T15:39Z，从 Agent-System dev@edbe59247872ef5861bafd30068955e22288c6ff 复制式拆出；新初始历史，未携带 .locks。 +PROJECT 将其定位为治理工具权威演进仓，阶段 A 通过 projects 聚合本机各项目 .locks，阶段 B 中央 API 尚预留。 +这是仓库文档的当前声明，不等于运行态部署证明。 + +本机 Development-Manager 目录存在，dev@8867e38ceb7cc71fa65d1a0f80178faff53fcb4c，工作树干净，缓存 origin/dev 无领先/落后提示。 +本次未单独核对其远端 dev SHA，因此不声称实时完全同步。 +本机 Development-Guidelines 目录不存在；历史记忆中的同名旧工作区不作为当前事实。 + +## Squad Boundary Evidence + +| 路径 | 当前机制 | 设计影响 | +|---|---|---| +| internal/squad/service.go:113 | Service 引用主仓 config.Config | 注入 Options，不反向依赖主仓 | +| internal/bizdev/service.go:195 | 直接 squad.NewService(cfg) | 装配与适配保留产品应用 | +| internal/squad/workflow.go:547 | agent.Request、重试/失败分类与物化 | 执行端口、失败语义、重试归属要显式 | +| internal/squad/service.go:256 | 直接主仓 stream 事件 | Squad 事件由应用映射至 SSE/持久状态 | +| internal/squad/workspace_adapter.go:6 | 返回主仓 WorkspaceRef | 适配留应用侧 | +| internal/squad/service.go:524 | templates/xlsx/cdo_quote.xlsx | 运行包资产不能仅包含 Markdown | +| internal/bizdev/service_task_finalize.go:68 | 质量失败短路 | 不可将执行完成等同正式提交 | +| internal/bizdev/service_task_finalize.go:35 | 编制人提交身份与 OnBehalfOf 分离 | 不改变产品授权 | +| .doc/system-design/module-boundaries.yaml:283 | 七包依赖 allowlist | 先解耦，再独立 Go 模块 | + +rg 穷举正式 Go import 显示 Squad 直接使用方涉及 29 文件/9 目录，包括 bizdev/chat/coordinator/server/intent/materialindex/projectcontext 与 CLI/script。 +主模块 `go.mod` 为 `module chat-agent-system`，Go 版本声明 1.27.1；本轮不推断目标机器工具链已安装。 +独立模块继续 import 主仓 internal 包不可行。 +现行模块开发标准明确模块化单体；仓库独立不自动授权增加 RPC/微服务。 + +## Tooling and Documentation Evidence + +| 路径 | 观察 | 必须适配 | +|---|---|---| +| scripts/agentctl.py:598–610 | Git common-dir 需等于 main/.git | 标准 submodule 的 .git 文件布局当前不支持 | +| scripts/agent_worktree.py:95–102 | 要求主工作区 .git 为目录 | 不能仅改 agentctl 一个入口 | +| scripts/agentctl.py:642–669 | 直接 sqlite3.connect 至本地主仓 .locks/state.sqlite | 多 clone 不是共享协调域 | +| scripts/agentctl.py:2861 | 本地 manager.lock 与队列循环 | 本地 daemon 不等于跨机服务 | +| scripts/agentctl.py:1599–1625 | 按父仓 staged 文件识别共享文档并查收据 | .doc gitlink 不能替代内容级检查 | +| scripts/agentctl.py:1287 / 1333 / 2245 | git show / cat-file 读取 HEAD/dev 中的文档与证据 | 跨仓 repo+SHA+path 引用 | +| internal/archtest/boundaries.go:107 | 机器模块契约位于 .doc | 留在代码仓，不作为普通文档搬离 | +| scripts/candidate-images-build.sh:60 | 仅 git archive 主仓提交 | 子模块源码固定递归导出 | +| scripts/pi_subagents.py、agentctl_w4.py、.cursor | 多处固定 .doc 位置 | 客户端入口、报告及治理一起迁移 | + +主目录 agentctl status 本轮返回 status=ok、protocol version=1； +实际 policy revision 为 agent-governance-2026-09-23-fav-constraint-restored。 +CURRENT 顶部历史摘要仍有 2026-09-23 信息，活跃任务表更晚；方案未用其历史环境状态代替 Git/API 现状。 + +## Build and Runtime Assets + +- scripts/build-single-binary.sh 构建 Web，然后 CGO_ENABLED=0 构建 cmd/server，写入版本 ldflags；不是全平台发布流程。 +- web/embed.go 的 go:embed all:dist 可将前端纳入二进制。 +- templates/embed.go 仅嵌入 docs/*.md；internal/template/loader.go 读取 configs/agents 指令和 configs/shared/writing.md。 +- deploy/app/Dockerfile 仍显式复制 web/dist、迁移、templates、configs，构建 server/events。 +- internal/localpg/localpg.go 查找本机 pg_ctl；数据库不是被 Go 服务自带。 +- deploy/pi-agent/Dockerfile 使用 Node 22 与单独 PI 包，固定 CLI 0.85.1；Runner 是额外执行依赖。 +- .github/workflows/ci.yml 有 Go/PG/Web 验证；nightly-real-pi.yml 有 Gitea 专用 runner/上传兼容说明。 +- 主仓 tree 跟踪 docgov.test、notification.test、projectinstance.test、storage.test；制品仓应避免继续提交二进制正文，历史不自动重写。 +- 未编译新平台、未启动服务、未读模型密钥、未读取 IDE 中业务 output.md。 + +## Lessons Reused + +检索 .doc/audit/ISSUES.md 与 .doc/ops/lessons/INDEX.md，核对当前源码后采纳： +- LESSON-20260923-matrix-status-cas：文档状态与 CAS 收据不能因拆仓失效。 +- LESSON-20260924-cursor-hook-advisory-gates：客户端提示与硬门禁分层，不称 UI/本地 hook 足以保护远端。 +- LESSON-20260926-failclosed-bypass-contract：缺失组件/收据/权限失败关闭，禁止 gitlink 绕过。 +- LESSON-20260927-server-facts-and-iso-db-recipe：未来验证使用明确隔离 DB，不回退至真实 dev。 +- 当前 Squad step-empty-output、squad-commit-authority、quality-heading 相关台账按原状态保留；本轮不修复、不关闭。 + +这次没有实施与运行验证，不新增 validated 经验；多仓适配风险在本研究记录和计划出口追踪，进入实施后按对应失败事实建问题/回归记录。 +未修改共享 ISSUES/CURRENT/MATRIX，避免把待审架构建议写成现行缺陷修复/生效规范。 + +## Review Record + +ce-plan 研究后，由 ce-doc-review 的一致性、可执行性、安全、范围、产品价值、反向挑战视角复核。 +本地审查的四项实际修订： +1. 五分钟上游通知明确为后续自动化目标，首期检查点不伪称实现该 SLA。 +2. U1 只验基线/平台可行性，完整候选队列/回写恢复在 U2 实现后验收，消除前置依赖循环。 +3. 内部完整源码包与公开源码包分开；公开包采用允许清单，排除私有开发资料，并加入负例。 +4. U6a 提前从当前固定单仓基线交付私有包试点，U6b 在拆仓后复验同一构建合同。 + +补充跨模型检查曾通过 ce-doc-review 的 claude CLI 路线请求 claude-opus-5/high，对 security/product/adversarial/whole-doc 发起只读复核。四个任务在本地审查完成后仍未返回结果，主代理主动终止附加检查；runner 记录 timeout（reaped on request before completion），result 读取均返回 3、没有审查产物。未验证实际服务模型，未将其计为独立复核或 PASS。此限制不改变本地六视角的事实与修订记录。 + +本地审查汇总：coherence 1、feasibility 1、security 1、product 1 项已修订；scope/adversarial 没有追加有效问题。未对复用同一子代理上下文的后续角色作独立性加权。 +用户要求完整待审方案，允许对本轮草稿调整完善，四项修改均保持 Product Contract 与用户已确认边界；不存在需要以草稿修订为由提前实施的动作。 + +最终文档检查：三份 Markdown 的 frontmatter、代码围栏、相对链接、R1–R10/U1–U6/V1–V12 覆盖与 whitespace 检查通过；git diff --check 通过。实施测试均未运行。 +只读收口：agentctl cleanup report exit=0，19 worktrees，ready=0、blocked=19；没有删除。agentctl docs drift exit=0，30 records、regressions=0、open_capabilities=3；没有改 MATRIX。 +CodeGraph 在开始与收口运行 sync -q 成功；其近似索引仅辅助定位，依赖完整性以 rg 核对。 +这些是文档审查修订，不是系统已支持的能力。 + +## External References + +- [Git submodule](https://git-scm.com/docs/git-submodule)：固定提交、相对 URL 解析。 +- [Go 模块布局](https://go.dev/doc/modules/layout)：internal 可见性与公开包。 +- [Go cgo](https://go.dev/cmd/cgo/)：交叉编译与 C 工具链边界。 +- [Gitea Actions FAQ](https://docs.gitea.com/usage/actions/faq/)：PR head 与合并候选区别。 +- [Gitea Actions token](https://docs.gitea.com/usage/actions/token-permissions/)：fork 和跨仓权限。 +- [Gitea 保护分支](https://docs.gitea.com/usage/access-control/protected-branches/)：审批与状态检查配置。 +- [Gitea 仓库权限](https://docs.gitea.com/1.22/usage/permissions/)：私有仓访问语义；最终以实例 ACL 实测为准。 diff --git a/.doc/ops/short-term/2026-09-28-multi-repo-design.md b/.doc/ops/short-term/2026-09-28-multi-repo-design.md new file mode 100644 index 00000000..72f56707 --- /dev/null +++ b/.doc/ops/short-term/2026-09-28-multi-repo-design.md @@ -0,0 +1,70 @@ +--- +title: "多仓库架构与 fork/PR 协作设计" +task_id: multi-repo-design-2026-09-28 +status: done +created: 2026-09-28 +updated: 2026-09-28 +owner: Codex +task_type: research +task_tier: multi_stage +policy_revision: "agent-governance-2026-09-23-fav-constraint-restored @ a3db288a7aa055ff5884e3aa4d91511959cff721" +branch: feature/multi-repo-design-2026-09-28 +worktree: .worktrees/multi-repo-design-2026-09-28 +base_dev_sha: a3db288a7aa055ff5884e3aa4d91511959cff721 +write_scope: + - .doc/ops/short-term/2026-09-28-multi-repo-design.md + - .doc/remediation/2026-09-28-multi-repo-architecture-plan.md + - .doc/audit/2026-09-28-multi-repo-evidence.md +allowed_environments: [] +mutex: path:multi-repo-design-documents +review_state: pending +integration_state: not_required +deployment: not_required +cleanup: retained-with-reason +cleanup_owner: "审核后独立维护者" +cleanup_trigger: "用户审阅完成且原 owner 退出" +remote_sync: not_requested +--- + +# 多仓库设计任务 + +## 用户目标与授权 + +来源：2026-09-28 本会话用户要求深入设计主仓 + 子仓 + submodule、fork/PR/上游同步、Gitea 多平台二进制发布，先提交待审方案，未审阅前不生效。允许读取本地代码和 Gitea 仓库元数据，生成本任务文档。仓库描述本轮仅拟稿，实际远端写入留到用户审阅通过后的执行阶段。 + +交付终点为可审方案与证据；不迁移代码、不创建或改写远端仓库、不调整权限/描述、不 push、不合入 dev、不部署、不访问业务正文。本地创建任务 worktree 和登记仅承载研究产物。 + +## 相关问题与经验 + +检索词：submodule、fork、跨仓、迁移、路径、candidate、squad、failclosed。 +采纳现有经验中的路径/快照一致性、拒绝旁路和未知状态、CURRENT/MATRIX 收据与证据绑定检查。 +历史多主机协调方案仅作线索，已重新核查本次源码与机器状态，不将方案当上线事实。 +本任务不修复已有业务问题，不将候选经验升级为 validated。 + +## 步骤与验收 + +1. 核对本地 dev、实时 Gitea、仓库用途和保护设置。 +2. 研究 Squad、文档、规范、治理工具、构建发布边界。 +3. 制定方案、分阶段迁移/回退与验收矩阵。 +4. 完成文档复核、差异/链接检查及只读收口盘点。 + +## 验证与交接 + +本地基线 a3db288a7aa055ff5884e3aa4d91511959cff721；Gitea dev 实时为 fabd85a65e15f3417431ba6f004a8bcdf9cb83cb，已验证远端为祖先，本地多 306 提交。本轮不同步。 +任务登记采用三个独占文件 scope；不修改 CURRENT/MATRIX 共享内容。 + +用户补充：Squad 为产品文档生成与复杂任务小队，开发治理工具可单列建议；内部测试版需要私有隔离，公开版公开。两项已写入方案。 + +交付： +- [待审方案](../../remediation/2026-09-28-multi-repo-architecture-plan.md) +- [调研证据与审查记录](../../audit/2026-09-28-multi-repo-evidence.md) + +验收：三份文档的格式、链接、要求/单元/验收项覆盖和 git diff --check 已通过。本地六视角审查收敛四项修改；附加外部模型检查未返回并主动终止，不计 PASS。只读 cleanup report 为 19/blocked=19/ready=0；docs drift regressions=0。未运行实施测试或真实产品验证。 + +## 收口 + +研究任务 done；方案 review_state=pending/policy_state=proposed。用户审阅仍是后续实施入口。 +本地文档将以独立 Conventional Commit 保存；不合入 dev、不 push、不部署、不设置仓库描述/权限。 +worktree 保留供审阅，cleanup=retained-with-reason；用户审阅结束、owner 退出后由独立维护者处理，不能因为研究完成便删除唯一待审产物。 +本轮不新增 validated lesson；所有迁移风险仅是方案检查项，尚无修复验收证据。 +接管者先读本任务、方案与证据，再核对最新 dev/Gitea/在途任务；不得仅凭此任务 done 执行迁移。 diff --git a/.doc/remediation/2026-09-28-multi-repo-architecture-plan.md b/.doc/remediation/2026-09-28-multi-repo-architecture-plan.md new file mode 100644 index 00000000..d50a8079 --- /dev/null +++ b/.doc/remediation/2026-09-28-multi-repo-architecture-plan.md @@ -0,0 +1,553 @@ +--- +title: "Agent-System 多仓库、PR 协作与发布架构方案" +date: 2026-09-28 +type: refactor +task_id: multi-repo-design-2026-09-28 +policy_state: proposed +review_state: pending +execution_authority: "design_only; implementation requires user approval" +product_contract_source: ce-plan-bootstrap +artifact_contract: ce-unified-plan/v1 +execution: code +--- + +# Agent-System 多仓库架构方案（待审，不生效） + +## Goal Capsule + +目标：让产品模块、项目文档、通用规范分别演进，以审核过的组件组合交付可部署版本，同时允许开发者在独立工作区并行开发。 +主仓成为版本组合与集成入口；拆仓不默认拆进程，不改变产品授权、数据和运行环境边界。 + +本轮仅交付方案与[调研证据](../audit/2026-09-28-multi-repo-evidence.md)，[任务记录](../ops/short-term/2026-09-28-multi-repo-design.md)保存授权、验证和交接。 +所有新流程、仓库描述、权限、CI 与拆分均待用户审阅。 +当前 AGENTS/PROJECT/worktree 规范仍生效。 + +用户已补充确认：Squad 指产品中生成文档与处理复杂任务的小队；开发协作治理工具可以另行考虑；内部测试制品必须私有，公开版公开。 +以下推荐技术选择均为待审建议，不把本次答复理解为实施授权。 + +--- + +## Product Contract + +### Problem Frame + +原思路合理，但需要纠正四点： + +1. fork 是服务器上的仓库派生关系；本地隔离使用 clone/worktree。通常每位开发者每个上游仓一个长期 fork，每项功能一个分支，无须每项功能新建远端仓库。 +2. 同一仓库内的并行任务可以从相同 SHA 出发；不同独立仓库没有共同父提交。跨仓基线应表示为“主仓 SHA + 各子仓 SHA”的版本向量。 +3. “一直最新”不能要求后台强制 pull 并改写正在开发/测试的工作区。改为上游变更及时通知、安全检查点同步、入队前强制最新、候选过期必须重验。 +4. submodule 只记录另一个仓库的固定提交，不负责跨仓 PR、依赖兼容、权限、CI、原子发布。必须补齐这些机制。 + +### Requirements + +| ID | 要求 | +|---|---| +| R1 | 现有 Agent-System 保留为外层主仓，维护产品版本组合与集成入口，历史不重写 | +| R2 | 产品 Squad 独立管理，保留文档生成、复杂任务、质量检查与执行生命周期行为 | +| R3 | 项目开发文档、通用规范、可执行开发工具分开归属，运行模板和业务数据不误迁 | +| R4 | 支持 fork + 功能分支 + PR 审核；开发工作区相互隔离 | +| R5 | 上游更新可感知，合并只能基于当前上游与已验证的精确组件组合 | +| R6 | 支持关联多仓 PR，明确非原子合并、兼容过渡与失败恢复 | +| R7 | 在 Gitea 发布 macOS Apple Silicon、Ubuntu Server 二进制部署包 | +| R8 | 内部测试发布私有，公开测试/稳定版公开；权限隔离经未授权访问测试验证 | +| R9 | 迁移可追溯、可分阶段停止，保留活跃任务与运行数据，不自动改数据库 | +| R10 | 本轮仅调研与待审方案，描述先拟稿，不让新方案生效 | + +### Actors and Flows + +A1 开发者/编码 Agent：写 fork 功能分支，提交组件 PR 与组合 PR。 +A2 审核者：确认产品边界、代码与测试，批准精确 head；作者不替代自己的审批。 +A3 中央集成执行者：维护队列、重建候选、执行保护分支更新；不代替 A2 的审核。 +A4 发布维护者：批准已验证组合进入内部或公开发布；持独立发布凭证。 +A5 测试者/部署者：按权限下载对应平台包，不依赖开发仓现场。 + +F1 单仓功能：固定基线 → 功能分支 → PR → 同步上游 → 组合候选验证 → 审核 → 受控合并。 +F2 跨仓功能：创建 change_set_id → 子仓扩展兼容能力 → 子仓 PR 合入 → 主仓 gitlink PR → 全组合验收 → 发布。 +F3 并行任务跟进：A 合入上游 → B 收到落后提示 → B 在安全检查点合并上游 → 对新组合重测；B 的未提交工作不被后台改写。 +F4 发布：固定主仓及组件 SHA → 构建包 → 原生平台验收 → 私有 RC → 必要审批 → 同摘要制品公开；任何重构建必须重新验收。 + +### Scope Boundaries + +本方案包括仓库职责、submodule、组件依赖、fork/PR、版本组合、治理迁移、二进制发布、Gitea 设置建议与仓库描述。 +不包含本轮代码修改、推送、权限调整、服务部署、数据库迁移和正在发生的业务缺陷修复。 +不因拆仓引入 Kubernetes、消息总线、微服务或一套新的远程 Agent 调度平台。 +完整跨主机协调服务仅在将来出现多个共享环境执行者时另立项目；首期只有一个中央集成/发布执行者。 + +--- + +## Planning Contract + +### Current Evidence + +调研基线：本地 dev 为 `a3db288a7aa055ff5884e3aa4d91511959cff721`。 +Gitea 1.27.3 的 dev 为 `fabd85a65e15f3417431ba6f004a8bcdf9cb83cb`，图遍历确认远端为祖先、本地领先 306 提交；这是本次快照，不代表后续仍未变化。 + +已读到六个 Gitea 仓库；五个用户指定仓库均可复用，另外已有 Development-Manager。 +主仓与 Development-Manager 的 branch_protections 都为空；不能把本地 hook 当作 Gitea PR 门禁。 +两仓 repository-level runner 列表为空，不能据此断言没有实例级或组织级 runner，实施前须核实 runner 标签和实际执行。 +尚未执行跨平台编译、原生启动、PR 合并或发布演练。 + +Squad 依赖七个主仓内部包，约 29 个非测试文件直接导入它。 +现有单二进制脚本可嵌入 Web；PostgreSQL、pgvector、PI Runner、部分运行资产仍是部署依赖。 +现有治理工具拒绝标准 submodule Git 布局，构建 `git archive` 不包含子模块；这些是先决改造，不是小概率问题。 + +### Alternatives + +| 方案 | 优点 | 代价 | 结论 | +|---|---|---|---| +| 继续单仓，只划模块目录 | 原子修改最简单，CI 低成本 | 不满足独立权限/版本/仓库目标 | 保留为迁移前基线 | +| 分阶段多仓 + 精确版本组合 | 满足独立管理，能逐个验收，保留单体部署 | 需要组件合同、组合 CI 和治理适配 | 推荐 | +| 一次拆所有目录并服务化 | 表面隔离彻底 | 同时改变代码、协议、部署、数据和工具；失败难定位 | 不采用 | + +### Repository Map + +| 仓库 | 目标职责 | 初期处理 | +|---|---|---| +| Agent-System | 产品总入口、submodule gitlinks、组合构建/测试、发布配方、项目策略入口 | 保留现有远端、dev/test/main 与历史 | +| Agent-System-Core（拟新建） | Go 应用装配、HTTP API、IAM、工作流与文档治理、DB/迁移、Web UI、产品运行配置与 PI Runner 适配 | 在 Squad/工具试点通过后整体提取；Web 和迁移继续同仓 | +| Agent-System-Squad | 产品任务编排、小队执行、质量检查、公共执行契约和 profile 支持 | 先解耦再独立 Go 模块，继续链接进同一进程 | +| Agent-System-Development-Documents | 产品需求/架构/ADR/计划/审计/开发经验/脱敏验收报告 | 可复用空仓；机器契约与活动治理文档按阶段迁移 | +| Development-Guidelines | 无产品依赖的开发规范、模板、证据分层和通用协作原则 | 可复用空仓；按版本显式采纳 | +| Development-Manager | 可执行协作治理工具、agentctl、worktree、客户端集成 | 复用已有代码仓，先比对差异，禁止覆盖式再次导入 | +| Agent-System-Releases | 公开测试版和稳定版的发布清单、说明、校验文件与 Release 附件 | 可复用空仓，保持公开 | +| Agent-System-Releases-Internal（拟新建） | 受限内部 RC/测试包、内部验收信息 | 新建私有仓，限制测试者与发布机器人 | + +Core 是让外层最终成为纯组合仓的必要承接点，但不应首刀移动所有业务代码。 +如审阅时希望控制首期仓库数量，可以让业务代码暂留主仓；达到真正外层结构后再建立 Core，不能声称过渡态已完成最终结构。 + +暂不单拆 Frontend、数据库迁移、公共 Types/Contracts、每个 agent 或每种 workflow。 +这些边界当前共同变化频繁；增加仓库会放大联动 PR 数量。 +PI Runner 已是部署依赖，但初期留在 Core 的 `deploy/pi-agent/`；仅当独立生命周期/复用需求成立，再评估 Agent-System-Runner。 +Releases 仓不作为主仓 submodule，避免发布依赖源码、源码又依赖发布记录的环。 + +### Target Layout + +以下路径为未来目标，并非当前已存在： + +```text +Agent-System/ + AGENTS.md, PROJECT.md, README.md + .gitmodules + components.yaml # 组件用途、依赖和兼容条件；不复制可手改 SHA + policy/ # 项目特定规则、采纳的规范版本与生效条件 + scripts/ # 薄入口、组合构建/验收/版本导出 + .gitea/workflows/ + .doc/ # 过渡期保留治理状态/研究入口，分阶段缩小 + modules/core/ # Agent-System-Core + modules/squad/ # Agent-System-Squad + development/documents/ # Agent-System-Development-Documents + development/guidelines/ # Development-Guidelines + development/manager/ # Development-Manager（工具源码只读消费） +``` + +```mermaid +flowchart TB + Root["Agent-System：固定产品组合"] --> Core["Core：应用、Web、授权与数据"] + Root --> Squad["Squad：执行与质量能力"] + Root --> Docs["Development Documents：项目知识"] + Root --> Guide["Development Guidelines：通用规范"] + Root --> Manager["Development Manager：开发治理工具"] + Core -->|"公开接口 / 主仓适配器"| Squad + Root --> Build["组合构建与原生验收"] + Build --> Internal["私有 Releases Internal"] + Internal -->|"发布批准 + 制品摘要核对"| Public["公开 Releases"] +``` + +### KTD1. Split Ownership Without Splitting Runtime + +Squad 独立 Go 模块，以公开 API 提供执行能力，主应用注入依赖。 +不直接导入 `chat-agent-system/internal/*`，不改名伪装成主仓以规避 Go internal 限制。 +独立库不持有产品 DB 连接、用户鉴权或正式文档提交权。[Go 官方模块布局](https://go.dev/doc/modules/layout) + +| 现有耦合 | Squad 边界 | Core 保留 | +|---|---|---| +| config/backend factory | Options + Backend/Result/Failure 接口 | 环境配置、PI endpoint、凭证、具体执行适配 | +| stream/SSE | 有类型的进度、步骤和完成事件 | SSE 映射、task_runs 持久事件、权限与重放 | +| workflowdef/task keys | 版本化任务/流程输入 DTO、profile | 工作流审批、冻结快照、项目状态 | +| template/instructions | 明确的资产 provider | 与业务绑定的模板、提示词及版本选择 | +| quote | 可选任务准备/产物处理接口 | 报价领域规则、核算、xlsx 资产 | +| workspace | 已授权 workspace 句柄、受限文件能力 | 数据根、租约、路径授权、环境隔离 | +| 正式文档提交 | 候选产物、质量结果与证据 | 编制人身份、OnBehalfOf、账本、事务、人工确认 | + +首期业务 profile 与运行模板继续由 Core 提供；只有确属 Squad 自有算法/通用 profile 的资产随库迁移。 +`internal/materialindex` 等仅为文本抽取而依赖 Squad 的调用应回归材料解析能力，避免依赖反向扩散。 +明确重试只有一个责任层：库负责步骤策略，Backend 返回标准化失败与已执行状态；不得两层重试产生重复写入。 +冻结现有 JSON、事件、任务键、workspace/manifest 格式；对旧版本未完成任务进行恢复兼容验证。 + +### KTD2. One Source of Truth Per Kind of Content + +开发文档仓保存“如何设计和验证产品”；规范仓保存“与产品无关的工作规则”；工具仓保存“执行这些规则的程序”。 +规范采用固定 tag/SHA，由项目 policy 显式更新并登记生效；上游规范合并不会自动覆盖项目授权或改变客户端行为。 + +`configs/agents/`、`configs/shared/writing.md`、`templates/docs/`、`templates/xlsx/` 是运行内容。 +IDE 中 `data/dev/workspaces/.../output.md`、`workspace.json` 是业务数据。 +这两类都不迁入开发文档仓；真实业务文件和数据库保持原有授权与备份策略。 + +`.doc/system-design/module-boundaries.yaml` 是机器契约，先移到对应代码仓的 `configs/architecture/`，与接口/表写者修改在同一个 PR 验证。 +每个代码仓保留短 AGENTS/PROJECT/README、CI 合同和本仓规则；不要求贡献者为普通编译读取私有文档。 +产品跨仓 ADR、路线图和汇总验收放 Documents；与源代码同提交必须成立的接口说明/生成规范留代码仓。 + +首期不把整个 `.doc` 原位替换成 submodule。 +先建立 `development/documents`，迁移静态设计资料和归档；CURRENT/MATRIX/活动任务暂留原管理路径。 +完成文档收据、证据 URI 与 hook 的多仓适配后，再迁移活动文档。 +新证据引用使用仓库标识 + 完整 commit + 路径 + 内容摘要；未提交草稿不能当作生效证据。 + +对每个迁移文档只设一个可编辑来源。 +旧路径变成短指针或历史只读文件，记录来源 SHA 与新路径；不长期双写。 +文档仓的新提交先经 PR 合入，再通过主仓 gitlink 显式采纳。报告记录其验证对象的源码 SHA；不把随后接入报告的主仓 SHA 倒填成被测对象，避免循环引用。 + +### KTD3. Gitlink Is the Component Version Authority + +主仓 tree 中的 gitlink 是实际源码版本权威。 +`components.yaml` 管仓库逻辑标识、职责、兼容范围、可见性和构建参与角色；不再手工维护第二套 SHA。 +构建时从固定 root SHA 生成不可变 resolved manifest，包含 root、子仓、规范、工具、资产、构建器/工具链及摘要；该生成物随收据/制品发布，不提交一个“包含自身最终 SHA”的循环锁文件。 + +`.gitmodules` 默认写上游绝对 URL，避免 fork 到不同 owner 后相对地址被解释到错误仓库。 +URL 只作定位，不作稳定 repo_id；repo_id 使用明确逻辑 ID 或 Gitea 实例+仓库 ID。 +本地 fork 只配置各子仓自己的 origin/upstream/push URL，不把个人 fork 地址提交进 .gitmodules。[Git submodule 官方说明](https://git-scm.com/docs/git-submodule) + +CI/发布使用固定提交 checkout，不执行 `submodule update --remote`。 +构建/验收所必需组件缺失、不可访问、未审核或仅存在个人 fork 的 SHA，组合准入失败。 +components.yaml 区分 build-required 与 development-only；公开源码构建可以只初始化 Core/Squad 等批准公开的 build-required 组件，不递归获取私有开发资料。全量内部发布/治理校验在具备相应权限的执行器进行。 +主仓 PR 不接受“本地可用、远端取不到”的 gitlink。 +检验父仓、每个子仓的脏状态，拒绝把未提交文件混入制品。 + +首期 Go 联调采用明确的相邻源码 replace：Core 指向 `../squad`；整个组合仍由 gitlink 锁定。 +Core 可独立 clone，但构建前须按受控 bootstrap 获取固定依赖；组件 CI也使用同一个依赖解析入口。 +`go.work` 仅本地可选，正式构建设 `GOWORK=off`，避免开发者私有 workspace 掩盖依赖缺失。 +Squad 自身必须可独立构建测试；Core 依赖版本的精确物化由主仓候选流程提供。 + +Gitea 当前访问 URL 带自定义端口，Go module path 不能直接照抄带端口 URL。 +首期以固定源码组合与本地 replace 消除直接 go get 的路由依赖；模块名使用经批准的不含端口稳定命名空间。 +若以后要求通过版本号直接 go get，再配置稳定域名/vanity 路由或私有 Go proxy，另行验收；不能只改 go.mod 就宣称分发可用。 + +### KTD4. Fork Once, Isolate Each Task + +Gitea 上为每个开发者/机器身份建立必要的长期 fork；仅修改涉及的子仓才需要 fork。 +同一 Gitea owner 不是无限创建同名 fork 的空间；若所有 Agent 共用一个账号，使用同一 fork 的多功能分支，或明确的开发组织/服务身份。 +独立 repo/clone 是工作区隔离；一个远端 repo 对应一个稳定组件边界，不与功能任务一一对应。 + +远端约定：origin 指向自己的 fork，upstream 指向权威仓。 +本地可以每个任务一个独立 recursive clone；涉及 submodule 的复杂任务初期优先此方式。 +现有无 submodule 任务继续受控 worktree；嵌套 submodule + linked worktree 只有在 Development-Manager 拓扑测试通过后才启用，不能直接套现脚本。 + +示例基线：任务 A/B 同从 root@R0 开始，R0 固定 Core@C0、Squad@S0。 +A 合入后上游为 R1；B 同步到 R1 时采用 R1 的组件组合，另保留 B 自己在变更清单中声明的组件分支。 +不是把所有子仓各自更新到各自最新 main；那会形成未经验证的新组合。 + +### KTD5. Freshness at Safe Boundaries + +首期必交：在开始工作、开始关键验证、请求审核、进入合并队列四个检查点强制检查上游，并记录人工触发还是工具执行。 +完成首期迁移后，可增加常驻通知/轮询，目标为上游合并后 5 分钟内标记相关活跃任务落后；这个时效是后续自动化阶段的验收条件，不属于 U1–U6 的首期承诺。漏事件由轮询补偿。 + +自动后台只允许 fetch 和状态提示。 +同步器遇到脏文件、正在测试、未提交子仓或冲突时停止工作区改动，记录 sync_required；不 stash/reset/自动提交。 +共享/已公开任务分支默认 merge upstream 保留历史；rebase 仅由 owner 在自己的可重写分支上显式发起，不后台强推。 + +子仓有新提交时创建组件更新 PR，由组合验收决定是否采用；不自动跳过主仓审核。 +队列准入绑定 repo_id、PR ID、source head、target base、组件清单摘要与策略版本。 +任一值变化，旧验证失效；需要重新生成受影响候选和相应审核，不能拿旧 SHA 的绿色结果放行。 + +“同步及时”与“测试可复现”同时成立的标准是：可见地落后、在明确检查点更新、被测组合不在测试中途变化。 +不承诺所有工作区每秒都等于上游。 + +### KTD6. Reviewed PRs and One Integration Authority + +主仓暂保留 dev → test → main 的现行生命周期，不在拆仓时顺带重新定义环境。 +子仓默认 main + 功能分支 + 不可变组件 tags；子仓 main 只是已审核组件，不等于产品已部署。 +Releases 仓 main 只存发布元数据；RC/stable 由 tag 和可见性决定。 + +推荐 Gitea 分支保护：禁止开发者直推受保护分支、禁止强推、要求非作者审批、陈旧审批失效、拒绝请求修改状态、要求明确命名的 CI checks。 +权限存在不等于某项操作已获授权；机器人也不获得自动部署 test/main 的权限。 +私有子仓的源码访问另配权限，不用公开 fork CI 中的秘密令牌补洞。 + +现有“本地 agentctl 精确候选后推进 dev”与“Gitea 服务器自行生成合并提交”必须选定一个权威，不能并行各自合入。 +推荐延续精确候选语义，增加中央 PR 集成控制器： + +1. 从 Gitea 读取已审核 PR，冻结 base D 与 head T，重核审阅绑定。 +2. 在可信控制平面创建两父 merge 候选 M，在隔离的无写凭证执行器测试 M 及完整组件清单。 +3. 排他队列内再读 target/base、source/head、审批与检查；变化即作废重建。 +4. 只有受保护的 integration 机器人可发布已验证的 M；常规贡献者与 UI 合并不具备推进该分支的权力。 +5. 推进前要求远端仍为 D，拒绝非快进、未知目标和验证缺失。服务端 pre-receive/验证网关核验签名准入收据，使“机器人直推白名单”不能变成无审核旁路。 +6. 上游接受 M 后核对远端 SHA，再将 Gitea PR 标记为 manually-merged 并附 M 与验证链接；任一回写失败进入 reconciliation，禁止重复合并或隐藏已发生的推进。 + +Gitea 1.27.3 本机 Swagger 已存在 `do=manually-merged`、`head_commit_id`、`merge_commit_id` 字段。 +其权限、PR 状态回写及保护规则联动未实测；必须先在获授权的演练仓完成端到端验证。 +不假设 Gitea 自带与现有本地 gate 等价的 merge queue。 +如果管理员不能部署收据校验或手工合并标记行为不满足审计，停止此路线；改用 Gitea 原生合并模式需要单独调整现有“精确候选 SHA”规范并获审，不能临时两套并行。 + +Gitea PR Actions 默认 ref 指向 PR head，不是 GitHub 式合并预览。 +因此 PR head 单测只能作为输入检查，组合验收须显式构造目标基线与 PR 的合并候选。[Gitea Actions FAQ](https://docs.gitea.com/usage/actions/faq/) + +开发 clone 的本地锁只保护本地；共享环境、schema 迁移号、发布序号与保护分支由中央执行者协调。 +将来多主机共享执行才引入远程 claim/lease、epoch、fencing、日志与恢复，不通过复制或共享 SQLite WAL 实现。 + +### KTD7. Cross-Repository Changes Are Staged + +一个 change_set_id 关联全部子仓 PR、主仓组合 PR、接口版本、兼容矩阵和验证清单。 +预合并联调可以使用明确列出的 PR SHA，但只能在候选清单中使用，不能当作正式发布依赖。 + +合并顺序：提供方向后兼容扩展 → 消费方适配 → 子仓全部进入受保护分支 → 主仓更新 gitlinks → 系统验证 → 发布。 +同一功能没全部就绪前，主仓继续固定旧组合；必要时新接口关闭启用，不借拆仓改变默认行为。 +旧契约在所有受支持组合退出后再删除，不把跨仓同步大改作为唯一迁移方式。 + +子仓已合入、主仓失败时，子仓可保留未采用的新版本，主仓保持旧 SHA。 +撤回主仓采用记录使用普通 revert PR；不改写子仓历史，也不自动反向数据库迁移。 +跨仓 Git 没有原子事务，原子“产品版本”由主仓固定组合及一次发布晋升提供。 + +### KTD8. Reuse Development-Manager Without Duplicating Authority + +远端 Development-Manager 已存在，PROJECT 将它定义为治理工具权威演进仓；MIGRATION 记录 2026-09-24 从 Agent-System 复制拆出。 +当前仅能据此确认仓库定位与内容，不能推导两个项目的工具已经同步、所有主机已接入或中央服务已运行。 + +实施前比较其源头映射与本次 Agent-System 工具改动，逐项选择保留/回移，不用旧复制覆盖新修复。 +通用规范抽到 Guidelines；Development-Manager 保留可执行工具及其自身开发文档；Agent-System 的环境端口、路径、模块 ownership 保留为项目 policy。 +根仓脚本最终只作固定版本的工具入口，工具更新也经组件 PR 和兼容测试。 + +先适配 Git common-dir/gitdir/worktree/submodule 身份，显式识别“工具源码仓”与“被管理目标仓”。 +工具作为 submodule 消费，不把其自身 .locks 当作产品协调状态。 +本地状态归属明确的 repo_id + host/workspace；共享权威只存在中央执行入口。 + +--- + +## Release Design + +### Platform Matrix + +| 制品 | 编译目标 | 验收环境 | 交付内容 | +|---|---|---|---| +| macOS Apple Silicon | darwin/arm64，CGO_ENABLED=0 | 实际 Apple Silicon macOS 主机 | agent-server、资产、启动/停止说明、launchd 模板 | +| Ubuntu Server x86_64 | linux/amd64，CGO_ENABLED=0 | 实际 amd64 Ubuntu Server | agent-server、资产、systemd 单元与部署说明 | +| Ubuntu Server ARM64 | linux/arm64，CGO_ENABLED=0 | 实际 arm64 Ubuntu Server | 相同职责的平台包；有硬件验收后才列为支持 | + +Ubuntu 架构未被用户限定，建议同时规划 amd64/arm64；首个发布的最低必交为 macOS arm64 与 Ubuntu amd64，arm64 若缺真机证据须标 experimental，不伪称已支持。 +最低 OS/CPU/PG 版本在发布演练确定并记清单；无验证证据不先作宽泛兼容承诺。 +Go 目标可交叉编译；出现 CGo 依赖时需相应 C 工具链，不能仅设置 GOOS/GOARCH 即宣称可用。[Go cgo 官方说明](https://go.dev/cmd/cgo/) + +macOS 公共分发加入 Developer ID 签名/公证的实施检查；签名凭证仅在受信发布步骤使用。 +签名改变字节时，对签名后的最终包重新计算摘要并验收；不能把签名前 RC 的摘要拿来证明公开附件一致。 + +### Package Contract + +每个平台交付一个版本化 tar.gz/zip，包含： + +- `bin/agent-server`：嵌入构建后的 Web 资源；如保留独立 events worker，另附平台匹配的 events，并明确单进程/独立模式不能重复消费。 +- `assets/`：迁移 SQL、运行配置模板、agent 指令、Markdown 模板、xlsx 等完整运行资产；逐项做包含校验。 +- `deploy/`：systemd 或 launchd 示例、启动/停止/健康检查与升级说明；不携带真实 .env。 +- `manifest.json`、`checksums.txt`、签名、SBOM、第三方许可、变更与升级/回退说明。 +- PI Runner 的固定版本素材或镜像 digest、Node/PI 版本与配置说明；不会伪装成已编译进 Go。 +- 对可完全离线安装的要求单列 profile；首期“源码之外可部署”不等于“所有依赖离线打包”。 + +PostgreSQL/pgvector 继续是独立运行依赖；`localpg` 会查找已安装的 pg_ctl，不是数据库被静态编进服务。 +默认服务器部署使用显式 DSN 和独立持久数据目录；受支持的 managed 本地模式另测。 +PI Runner 可以用固定镜像或受支持 Node 运行方式，模型/工具密钥由部署环境注入。 + +禁止安装包依赖原源码 checkout 的相对 cwd。 +资产根、配置根、数据根分别指定；从任意目录启动均能定位正确资产。 +从发布包在干净主机启动、完成真实任务，才算“可以部署”，仅 go build 成功不够。 + +### Build and Publication + +源码权威在组件仓，构建配方与组合规则在主仓；Releases 仓不复制应用源码，也不独立维护另一份构建逻辑。 +从固定 root SHA 递归导出全部参与构建的组件 SHA，生成源码物料清单。 +修复现有 candidate-images-build 的仅主仓 git archive 假设；不得退回读取开发者的可变工作目录。 +前端使用锁文件 npm ci，Go 工具链和构建器固定版本/digest，禁用发布时隐式采用未知工具链。 +交叉编译与原生验收拆成独立 jobs，结果绑定最终制品摘要。 + +建议版本：组件用各自 SemVer；产品 RC 用 `vX.Y.Z-rc.N`，稳定版 `vX.Y.Z`。 +保留旧 rc-v1.1.0-beta.* tags；新命名启用前兼容现有 promotion 脚本，不能重打历史 tag。 +root release tag 固定产品组合；Releases 仓同名 tag 指向发布元数据提交，并在 manifest 明确 source_root_sha，二者不是同一个 Git 提交。 + +制品放 Gitea Release 附件或受控 package storage，不直接 commit 二进制到 Git。 +当前主仓已跟踪若干 *.test 二进制；后续停止新增并以普通提交移除当前树中的误入制品，保留历史；不为缩体积自动重写历史。 +Gitea 自带的“源码 zip”只覆盖被打 tag 的发布仓元数据，不代表完整产品源码。 +内部完整 source-bundle 可以包含受权构建所需组件；公开 source-bundle 必须按公开批准清单与构建角色导出，默认排除 development/documents、development/manager、内部证据和私有配置，不能直接打包全部 gitlinks。 +公开源码包逐项检查归档成员与敏感内容；必要构建依赖未获公开授权时，阻断公开源码包，不能自动扩大权限。公开运行包同样进行内容检查；两种包的可公开性分别判定。 + +发布状态：built → native_verified → internal_rc_published → approved_for_public → public_published。 +不可变内容以 manifest_digest + asset SHA256 标识。 +公开发布重新校验批准的内部制品，不从各子仓最新分支再构建一遍。 +如果重新构建/签名/重打包，作为新制品进入验证，不能沿用旧字节的 PASS。 + +跨仓发布不是事务：上传到 draft、逐项检查数量/大小/摘要、回读下载、最后发布；相同版本与摘要重试幂等，不同摘要冲突拒绝覆盖。 +外部请求结果未知时先查 tag、release、附件与摘要，补齐或终止；不得盲目重复发版。 +已公开错误版本标撤回/失效并发布修正版，不静默换同名附件。 + +内部发布仓必须 private。 +公开仓的 prerelease 标记只是发布成熟度，不能当访问控制；私有附件/API/源码包均需测试匿名和无权限账号拒绝。 +公开说明及 SBOM 不携带内部测试数据、凭证、私有路径与敏感下载 URL。[Gitea 仓库权限](https://docs.gitea.com/1.22/usage/permissions/) + +### CI Trust and Promotion + +贡献者 fork PR 在隔离、无秘密、无宿主共享环境写权限的 runner 测试。 +受信集成控制面与不可信候选代码执行面分开；测试进程不能拿 integration token、签名密钥或 Release 写 token。 +发布 job 不通过 pull_request_target checkout 未审核代码来取得秘密。 +Gitea job token 默认不等于跨仓发布权限；发布机器人使用只覆盖目标发布仓的最小授权，fork 流程不可获取它。[Gitea Actions token 权限](https://docs.gitea.com/usage/actions/token-permissions/) + +现仓使用 .github/workflows 且有 Gitea 特定兼容处理。 +迁移时检查实例实际 ACTIONS workflow 路径配置，再统一到确定路径；不能同时复制两套导致双跑。 +不得默认套用 GitHub 专属 artifact action；现有 nightly 已记录 upload-artifact@v4 不兼容，发布演练直接验收实际 Gitea 上传/下载接口。 + +--- + +## Implementation Units + +所有单元在审阅通过后另建实施任务；本节是执行路线，不代表本次已启动。 +估算按单个有上下文的实施者的工作日，不含等待硬件、证书、审阅和业务回归时长；阶段出口优先于日期。 + +### U1. Establish Baseline and Governance Pilot + +覆盖 R1/R4/R5/R9；预计 1–2 日。 +记录所有本地/远端 branches、tags、活跃 worktrees、未提交成果和运行制品身份；冻结迁移范围与历史保留策略。 +先备份/验证 Git 对象与恢复方法，再经审阅决定如何将本地 306 提交差异同步至 Gitea；不机械 push 全部分支。 +建立迁移映射 source_repo/source_sha/source_path → target_repo/target_sha/target_path。 +对子仓抽取可在临时 clone 中 filter-repo 保留相关历史并保存 commit-map，先扫描整个将要公开的历史；不重写现有主仓。 +Development-Manager 已有独立历史，做差异合并，不再抽取覆盖。 + +受影响入口：现行 PROJECT/AGENTS、scripts/git-push-dev.sh、agentctl 集成和 Gitea settings（后续写入）。 +最小演练：在获授权的演练仓核对 Gitea 分支保护配置可用、管理员可部署服务端校验、manually-merged 能指向指定已合入提交；此阶段验证基础能力，不要求尚未编写的控制器已工作。 +出口：基线和保留策略明确、唯一集成权威选定、平台能力可行；产品仓仍走原流程。完整控制器验收归 U2，不能在 U1 先要求它通过。 +不在本阶段改变 test/main 部署。 + +### U2. Adapt Multi-Repository Tooling + +覆盖 R4–R6/R9；预计 3–5 日，依赖 U1。 +修改 Development-Manager 的 agentctl/agent_worktree/git hooks/catalog，以及主仓薄入口、candidate 导出和收据 schema。 +新增 repo_id、组件清单、跨仓证据 URI；明确 clone 和 submodule Git 身份。 +Gitlink 门禁验证子仓受保护提交、文档审批与实际内容，不只检查父仓文件名。 + +建议新增测试：Development-Manager 的 `scripts/tests/test_multi_repo_topology.py`、`test_multi_repo_receipts.py`、`test_integration_queue.py`。 +主仓新增 `scripts/tests/test_component_export.py`；保留现有 test_agentctl/test_agent_worktree 回归。 +覆盖普通 clone、linked worktree、标准 submodule、路径别名、子仓缺失/脏状态、两候选竞争、修改 head/base 导致审批或验收失效、无审核 push 拒绝、manually-merged 回写失败恢复、操作未知后重试、报告 gitlink 绕过。 +仅在 U2 完整出口通过后，按批准的切换窗口排空旧集成入口、锁定当前 base、切换产品仓权威；演练失败不改变原产品集成流程。 +出口：隔离演练仓可通过审核 PR 按精确 M 合入；无凭证测试执行器不能写权威仓/环境。 + +### U3. Separate Guidelines and Development Documents + +覆盖 R3；预计 2–3 日，依赖 U2 的相关子能力。 +先拆通用 Guidelines 与静态 Documents，机器契约留代码仓，活动状态/收据最后迁移。 +改对应入口链接、客户端规则、archtest 清单位置、文档索引和证据查找。 +声明版本采纳规则、owner 与旧路径只读状态。 + +新增文档链接/归属检查；继续验证 `internal/archtest`、`scripts/tests/test_agentctl*.py`。 +覆盖旧文档链接可追溯、新文档 PR 独立、缺文档权限仍能构建公开源码、能力状态不能因冲突退回、子仓 gitlink 不能绕过收据。 +出口：每项内容有唯一写来源，无业务数据或运行模板误迁。 +先抽取少量静态文档试点；失败通过普通 PR 恢复路径与 gitlink，不删除新仓历史。 + +### U4. Extract Product Squad + +覆盖 R2/R6；预计 5–8 日，依赖 U2，接口冻结后可与 U3 部分并行。 +现仓先完成依赖注入与材料解析去耦，保持行为；随后抽取至 Squad。 +Core/主仓保留一层临时 facade 适配 29 个调用文件，注明清除条件。 +受影响：internal/squad、internal/bizdev、coordinator/chat/server/intent/projectcontext/materialindex、cmd/bizdev-cli、go.mod、模板 provider。 + +保留并迁移 Squad 算法测试；新增 Squad `contract_test.go` 与 Core `internal/squadadapter/contract_test.go`。 +关键回归沿用 quality_projection、squad_commit_actor、task_run_idempotent_sse、task_run_resume_pg、quality_repair_contract、step_retry 等。 +用原例、同类变体和正常行为比较；尤其旧工作区恢复、质量失败零正式投影、非编制人代理提交、传输失败残留文件不得当成功。 +出口：库可独立测试；真实 PI + 浏览器的商务/研发任务、权限负例、刷新/重启均通过。 +发现现存故障时拆分问题记录，避免把搬迁顺带修复当作等价性证据。 + +### U5. Finish the Outer Repository + +覆盖 R1/R3/R6；预计 2–4 日，依赖 U3/U4 稳定。 +将其余产品代码作为一个 Core 仓提取；保留 Web/DB/运行配置/Runner 同仓，主仓变为组合入口。 +调整 Docker COPY、构建入口、Go replace、测试根目录、CodeGraph 索引、运行服务入口与资产根。 +迁移源为批准的固定 SHA；源仓历史原样保留。 +开发数据与生产数据目录不随代码树挪动；路径切换必须显式映射并在隔离环境验收。 + +新增主仓 component manifest 校验与 smoke 测试，复用 Core 全部门禁。 +验收全新 recursive clone、源码 bundle 解压、无原源码路径构建启动、组合指针回退、当前运行版本识别。 +出口：外层仓不承载业务实现，组件固定组合可完整重建。 + +### U6. Build and Release Portable Packages + +覆盖 R7/R8；预计 3–5 日，分两个连续子阶段，沿用同一包格式与发布入口。 +U6a 在 U1 基线/授权边界明确后即可对当前固定单仓源码补齐运行资产、双平台包与私有发布演练，不等待 Core 提取。任何远端发布仍需要该实施阶段的明确授权。 +U6b 在 U5 后把同一配方切换为固定组件组合并重新验收；U6a 的结果是部署基线，不替代 U6b 的多仓版本验收。 +主仓实现固定组合构建与发布 metadata；组件实现必要的资产定位/版本输出。 +新增私有内部发布仓、发布账号最小权限，拟定描述在本阶段或 U1 审批后一次性设置。 +完善 scripts/build-single-binary.sh、candidate-images-build.sh、release/promote 入口和目标平台部署模板。 + +新增包内容/摘要/权限检查与两平台原生部署 smoke；CI 具体路径依实例 workflow 配置决定。 +验收干净 macOS arm64、Ubuntu amd64、可选 Ubuntu arm64，启动/health/ready/真实产品任务、升级、失败恢复、下载权限、重复发布冲突。 +出口：私有 RC 实际可安装；公开晋升经授权且附件摘要一致。 +业务数据库升级若存在，单列备份、前向兼容与恢复窗口；Git 回退不能宣称数据库已回退。 + +粗略总工作量约 16–27 人日；这不是固定工期，U6a 可以并行，U1/U2 演练后重估。 +可以在 U3 或 U4 完成后暂停，而不强迫一次完成全部拆分。 + +--- + +## Verification Contract + +| 验收面 | 输入/动作 | 必须结果 | +|---|---|---| +| V1 Git 基线 | 同仓 A/B 从 R0 开始，A 先合并 | B 被标落后；旧候选失效；同步后基于 R1 重验 | +| V2 脏工作区 | B 含未提交代码/子仓，收到同步事件 | 只提示，不 pull/reset/stash，不丢文件 | +| V3 跨仓版本 | 子仓 PR 未合入、SHA 仅在 fork | 主仓正式准入拒绝；候选联调明确非发布 | +| V4 精确组合 | 改任一组件 gitlink 或构建配方 | manifest 摘要变化，原组合验收无效 | +| V5 权限 | 无审核 push、fork CI 读发布 secret、匿名下载内部包；私有资料嵌入唯一测试标记 | 未授权访问均拒绝；token 不进测试进程；公开运行/源码包不得包含测试标记与未批准路径 | +| V6 并发合入 | 两个 controller/候选竞争同一 base | 只有一个推进，另一个重建；未知结果先 reconciliation | +| V7 Squad 语义 | 文档生成/复杂任务 + 失败/权限/恢复变体 | 事件、正式文档、持久状态符合原产品合同 | +| V8 文档治理 | CURRENT/MATRIX 子仓变化，父仓 gitlink 更新 | 子仓收据/审批可追溯；不能因 gitlink 隐藏绕过 | +| V9 完整包 | 从任意 cwd 在无源码的干净机器启动 | Web/模板/xlsx/SQL 可用；缺依赖明确失败；不误连 dev DB | +| V10 平台 | darwin/arm64、linux/amd64 真机；arm64 可选 | 对最终包执行原生验收，交叉编译不能替代 | +| V11 发布恢复 | 上传一半中断、重复同版本、不同摘要同版本 | 幂等补齐/拒绝冲突；公开前附件完备；旧版不被覆盖 | +| V12 回退 | 回退主仓 gitlinks，已有旧任务/数据 | 代码版本可回退；schema/任务格式不兼容时明确停止和恢复路径 | + +现有可复用命令为 `./scripts/arch-check.sh --mode block`、`go vet ./...`、`go test -short ./...`、web 的 `npm test`/`npm run build`，迁移后在对应组件目录运行。 +PG、真实 PI 与浏览器验收遵守当前验证契约，使用独立环境；共享环境须独占。 +本轮只做文档差异、链接和事实一致性检查，没有执行上述实施验收，不记录为 PASS。 + +--- + +## Repository Descriptions + +以下为审批后的拟写描述；本轮未调用更新 API。 + +| 仓库 | 拟用描述 | +|---|---| +| Agent-System | Agent-System 产品集成主仓：管理组件版本、开发入口、组合验证与发布流程。 | +| Agent-System-Core | Agent-System 核心应用：API、Web、身份权限、工作流、文档治理与数据持久化。 | +| Agent-System-Squad | Agent-System 产品智能体小队：文档生成、复杂任务编排、执行协作与质量检查。 | +| Agent-System-Development-Documents | Agent-System 项目开发文档：需求、架构、设计决策、计划、审计与验收记录。 | +| Development-Guidelines | 与具体项目无关的开发规范、协作流程、审查标准及工程实践模板。 | +| Development-Manager | 多项目开发协作治理工具：任务与工作区管理、执行约束、验证收据和集成控制。 | +| Agent-System-Releases | Agent-System 公开测试版与稳定版发布：macOS Apple Silicon、Ubuntu Server 部署包、校验与升级说明。 | +| Agent-System-Releases-Internal | Agent-System 私有内部测试与候选版本：受限部署包、版本清单及验收说明。 | + +--- + +## Risks and Decisions + +需要用户审阅的核心建议：同意分阶段拆仓、复用 Development-Manager、最终新增 Core 承接应用、采用受审 PR 的中央精确候选集成。 +已确认的内部私有/公开隔离按本方案执行；不再作为未决问题。 + +实施前仍需验证、但本轮无法以只读研究证明的条件： + +- Gitea 精确候选发布、服务端收据验证与 manually-merged 状态回写的端到端行为。 +- 可用的 macOS/Ubuntu 原生 runner、最低平台版本与公共 macOS 签名条件。 +- 全量历史导出是否包含不应公开的内容；未扫描历史不能认为空仓导入自然安全。 +- Core/Squad 公开模块命名空间，以及远期独立 go get 分发是否需要稳定域名。 +- 切换时仍在运行的任务/操作、Workspace 格式兼容与实际部署资产布局。 + +这些是对应阶段的阻断出口，不妨碍先审阅整体架构。 +出现无法恢复的未知副作用、缺少授权环境、活动任务无法排空、子仓 SHA 不可获取时停止相应阶段；保留当前已验证组合。 +保持产品代码回退、部署制品回退、DB/用户文件恢复三条独立路径。 + +--- + +## Definition of Done + +本轮研究完成条件：现状证据、推荐与替代方案、仓库职责、协作/版本语义、迁移/回退、平台发布、可见性隔离、描述草稿与验收矩阵齐备，并交付用户审阅；不以实施状态衡量研究完成。 + +未来实施完成条件：U1–U6 对应出口和 V1–V12 均有证据；主仓是可重建组合；所有组件 PR 与 gitlinks 可追溯；真实部署包在承诺平台完成原生产品验收；内部制品未被未授权访问；远端与运行状态分别记录。 +未获得公开发布授权时，内部验收通过不自动发布公开版本。 + +--- + +## Sources + +本地证据与方法见[调研记录](../audit/2026-09-28-multi-repo-evidence.md)。 +Git/Gitea/Go 官方链接随影响决策的段落引用；本机 Swagger 用于验证实例字段，但字段存在不证明流程已演练。 +本方案没有修改现行规范的效力。