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..db85f209 --- /dev/null +++ b/.doc/audit/2026-09-28-multi-repo-evidence.md @@ -0,0 +1,344 @@ +--- +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 实测为准。 + +## Revision 2: Web and Agent-Native + +授权来源：用户在原方案审阅中追加前端拆仓和 pi-native/agent-native 共享执行基础设计；沿用 task_id，不启动实施。 +本轮源码基线仍为 a3db288a7aa055ff5884e3aa4d91511959cff721，文档上一提交为 de90d0cd70e5cfadbd680e8caf8bdf18724e44a8。 +旧机器登记已 done，agentctl 不提供 reopen；新增同 worktree 的执行登记 multi-repo-design-2026-09-28-r2，逻辑任务和三个允许写路径不变。 + +### Confirmed Wiring + +| 证据位置 | 确认的事实 | +|---|---| +| internal/agent/backend.go:38–60 | 公共 Backend/Execute，工厂支持 pi-agent/pi-native；native 包裹 PI fallback；未知名默认 Stub | +| internal/app/app.go:132–133 | 通过同一工厂创建助手 dialogueBackend 并注入 coordinator | +| internal/coordinator/dialogue_llm.go:126 | 助手调用 Execute，交付 reply.md；当前非直接返回文本接口 | +| internal/squad/service.go:261、402 | Squad 任务/工作流也调用同一后端工厂 | +| internal/config/config.go:109 | 源码默认 AGENT_BACKEND 为 pi-agent；不证明运行配置 | +| internal/app/app.go:162–186 | 语义摘要、文档变更叙事、U9 segment 仍有 pi-agent 名称条件 | +| internal/agent/pinative.go:17–28、96 | PiNativeBackend 是产品配置/工作区与 agentx.Run 的适配层 | +| internal/agentx/loop.go | 具备原生 loop、tool 调度、stream、usage、turn cap；不是完整产品持久任务控制面 | +| internal/agentx/llm/client.go:14 | 当前是兼容 Chat Completions 的 client，不能推断全供应商适配 | +| internal/agentx/session/jsonl.go | 本地 JSONL transcript 与对象 mutex；不是跨进程执行租约 | +| internal/agent/fallback.go:21–41 | native 不成功且 context 未取消时尝试 PI；Name 仍可为 pi-native，仅日志记录实际回退 | +| internal/taskrun/backend.go | 另有后端名称 allowlist 和生产 stub 限制，改名需全入口一致 | +| web/package.json / vite.config.ts | 独立 npm 构建、测试与 Vite API proxy，可作为独立源码仓 | +| web/embed.go:14 | 当前 Go embed 与前端目录共置，不能直接整体搬走而不处理 Go import | +| internal/server/static_assets.go:16、20–36、resolveDistDir | 导入主模块 web；磁盘资源优先，多个相对路径可能遮蔽内嵌 UI | +| web/src/api/* / admin/console | 手写 API 客户端、auth header/cookie、后端信息展示需要契约与兼容检查 | + +CodeGraph sync 成功并 explore PiNativeBackend；rg 再确认助手/Squad 工厂调用和 agentx import 依赖。 +未读取业务 output.md、workspace.json、模型密钥或运行实例环境；没有调用真实模型或产品 Agent。 +所以结论是“源码支持双方选择 native、具备公共接口”，不是“当前两条线上路径已运行 native”或“native 全能力已验收”。 + +### Revision Decisions + +1. 新增 Agent-System-Web 与 Agent-Native 仓库建议；Core 不再承载前端源码和通用 Agent 内核。 +2. Agent-Native 包含 contract/runtime/adapters/conformance；公共 contract 不反向依赖 Core/Squad，Core 注入后端，Squad 只使用契约。 +3. 模型适配、完整 Agent 适配、工具适配分开；保留未来吸收先进实现的空间，不承诺任意 SDK/CLI 即插即用。 +4. pi-native 旧名、AGENTX 配置与 .agentx 数据路径提供兼容；默认后端不随拆仓切换。 +5. 区分 native 自身成功与 PI fallback 成功；未知副作用不自动跨后端重放。 +6. Web 构建产物在隔离构建上下文物化到 Core embed 目录，仍可发布一个包含 UI 的服务二进制；不提交 dist 或软链接越界。 +7. 增加 U7/U8、R11–R13、V13–V16，同步更新仓库地图、拓扑、Core/Squad 依赖、发布组合和描述；没有只追加一个与旧建议矛盾的附录。 + +### Revision Verification + +本轮针对新增边界做源码/官方资料核对与作者一致性复核，不复用第一轮六视角结果作为修订 2 的新增审查证据；未发起额外外部模型复核。 +复核修正：U7a 先形成可独立获取的最小 contract 模块，U4 消费它，U7b 再迁 native/PI 实现，避免 Squad 和完整 Native 提取相互等待。 +Go embed 的包/模块边界据[官方文档](https://pkg.go.dev/embed)确认；Vite 独立构建/后端集成据[官方指南](https://vite.dev/guide/backend-integration)核对；工具与完整 Agent 的区别参考[MCP 架构](https://modelcontextprotocol.io/docs/learn/architecture)。 +仅实施计划中定义真实 native/PI、浏览器与平台验收，本轮未运行，不能标 PASS。 + +## Revision 3: Ubuntu-only and PI Core Parity + +用户确认近期不需要 Ubuntu ARM/Apple Silicon；异步澄清确认目标为“对齐核心能力并逐步替代”，不是仅兼容接口或完整上游复刻。仍未授权实施。 +本机 uname -m=x86_64，os-release=Ubuntu 26.04.1 LTS；当前支持目标改为 linux/amd64，无需本期交叉编译。 +只读核对 deploy/pi-agent/Dockerfile 固定包0.85.1；npm 该版本元数据 gitHead=d981de1229ef899957bbe968bc8dcda02a21f477，repository=earendil-works/pi，license=MIT。通过内存读取发布tarball检查README/compaction/rpc/extensions文档，无安装/执行包代码；未验证运行容器版本。 +项目 pi-args 默认 --mode rpc --no-session，workspace 为受限工具且加载扩展；Runner提供 /v1/run 与 /v1/search，typed-result-v1 与 Tavily 属于实际依赖范围。 +agentx 已有 loop/tools/session/stream/steering/follow-up；没有因此推断完整 PI compaction/扩展/会话兼容。 +现有 abtest/Suite 只有6例；Judge比较成功率/P0/P95≤1.3倍；live测试直接 NewPiNativeBackend 禁止隐性fallback，RUN_AGENTX_AB=1 才运行。本轮未运行它，不把既有测试代码当通过证据。 +新增独立 U9 能力盘点→补齐→对比→渐进启用→替代收口；移除本期双平台要求、macOS签名阻断与ARM构建要求；更新描述与验收。 +来源：https://registry.npmjs.org/@earendil-works%2fpi-coding-agent/0.85.1 与固定提交的上游 README/docs；上游main仅用于导航，能力基线以固定版本为准。 + +## Revision 4: Governance Review + +用户要求根据多仓/Ubuntu/Agent-Native方案复审锁、agentctl及规范，可在方案中删减不必要/频繁出问题的机制并补齐缺项。 +授权仍为研究和待审文档，不执行规范切换，不改变现行工具/配置/数据库/远端设置。 + +### Confirmed Issues and Evidence + +ISSUE-20260928-governance-lock-domain，issue_state=investigating，owner=Codex（方案），影响为独立工作区无关写入被全仓恢复状态阻塞。 +已证实机制：scripts/agentctl.py:532–557 的 path 资源和 overlaps 没有工作区标识；path:. 覆盖所有相对路径。 +scripts/agentctl_console.py:186 为 integrate_prepare 获取 path:. + git:index + git:dev；:211–220 对合并失败尝试abort后仍标 recovery_required。 +scripts/agentctl.py:982–998 的持锁比较继续纳入 recovery_required，因此一个候选冲突/失败可能长期挡住不同worktree。 +本会话 r2 提交与 r3 文档写入实际均被同一 operation 拒绝；它不是仅根据代码猜测的风险。 +没有调查那个集成任务具体合并失败的底层原因，不能声称已经定位其全部根因。 + +问题类别还包括过度恢复升级：execute 在带 env/git:dev 的命令非零退出时统一需要恢复（agentctl.py:1145–1146）；应按实际副作用证据区分，不能因此把真正未知结果直接释放。 +physical_names 将 git:dev 与 env:dev 绑定同一 dev-integration.lock；固定制品部署后可分离代码引用与运行环境锁。 + +另有 task 生命周期不一致：规范允许 blocked并要求原task_id续办，task close 只支持done/cancelled，register拒绝非active的同ID。 +本会话曾尝试blocked而被CLI明确拒绝；新增-r2/-r3只是受限工具下的执行登记，逻辑研究任务一直保持原ID。 +建议新工具原ID可reopen/update-state，执行尝试另有attempt_id，旧运行副作用日志保留。 + +治理快照（本轮只读SQLite URI mode=ro）：completed=1455、failed=208、recovered=167、busy=21、recovery_required=1。 +其中recovered为command=144、integrate_prepare=22、integrate=1；这不是错误率、误报率或性能基准，不把正常恢复也算缺陷。 +阻塞operation为 integrate-nightly-advance-2026-09-28-r2-prepare-838577a7，resources含git:dev/path:./该候选tree，exit_code=1。 +稍后复核该记录已为recovered，本代理没有调用recover、删锁或修改管理数据库状态来解除它；正常agentctl with随后返回成功。 +Development-Manager中的对应overlaps/Lease/prepare与task close逻辑仍同类，不能靠只把工具搬仓根治。 + +### Decisions and Replacements + +方案KTD6改用Gitea原生PR合并/保护/CI，取消默认自建签名收据网关、机器人直推与manually-merged回写。 +仍显式验证base/head/候选tree/组件manifest，合入后的真实SHA绑定制品和部署；不能将PR head测试当合并候选通过。 +方案KTD13给出retain/replace/remove矩阵、局部资源身份、known-failure/unknown分类、任务续办、清理和规范层级。 +U2负责替代治理与切换，补V19–V23负例；不是另外堆一套大型协调服务。 +工作区的源码副本不互锁；同实际目录和共享环境保留适用保护；产品数据库事务/文档职责/运行租约不在工程锁裁剪范围。 + +暂不修改共享ISSUES/lessons索引：本次用户明确仅允许三个待审文档，本节保存问题主记录候选，实施/正式文档集成时由相应owner补索引。 +没有修复和回归运行，不把上述问题标resolved或经验标validated；既有coordination-authority问题继续按原状态追踪。 + +### Authority and Exception Record + +曾因正常入口仍被全仓恢复锁阻塞，请求只针对这三份文档的临时租约豁免。 +用户批准：owner=Codex，原因=待审文档落盘被无关恢复操作阻塞，覆盖=本任务三文档的agentctl with前置，禁止=解锁/改工具或现行规范/提交/推送；有效期=保存完成即结束；恢复动作=保留可审diff，恢复正常租约流程。 +实际结果：原阻塞先恢复，r3与r4方案主体通过agentctl with保存；随后新操作integrate-nightly-advance-automation-2026-09-28-r7-prepare-dca474ad再次进入recovery_required，正常入口拒绝最后的文档写入。 +本轮最后保存使用用户已批准的豁免，仅对原三文档直接写入；没有调用recover、删除锁、修改hook/agentctl/现行规范或提交/推送。完成保存和校验即终止豁免，后续回归正常租约流程。 +用户确认的“仅三份待审文档、不提交或推送”作为本次交付限制保留。 + +修订3的Ubuntu单平台和U9原生核心替代已经本轮正常落盘；修订2工作区改动一并保留，没有丢弃或覆盖其他任务文件。 +本次审查是源码/运行元数据/官方Gitea资料的定向核对与作者一致性检查，未声称重复进行了首轮六视角或外部模型审查。 + +最终校验：3份文档、6个相对链接、15项要求、9个实施单元、23项验收场景，结构/ID/链接/旧方案残留检查通过；git diff --check exit=0。收口盘点cleanup total=18/blocked=18/ready=0，未清理；docs drift regressions=0/open_capabilities=3。没有实施、编译或真实运行验收。本轮使用的一次性三文档豁免至此结束，不提交/不推送。 + +## Revision 5: Proportionate Everyday Rules + +用户追加“很多规范过严，按最新方案适当完善”；本轮仍仅修订原方案、证据与任务，不批准或启用新规范。 +读当前AGENTS、PROJECT、验证契约、经验闭环、收口模板及KTD13；核实已有纯文档免全量测试/按机制选场景/矩阵按声明更新等合理条款，未把它们误报为全都缺失。 + +问题是执行尺度和入口一致性：Go/接口验证矩阵列全包vet/short，而报告章节又说明不无条件全量；需明确本地迭代/组件CI/组合发布三个检查阶段。 +启动阅读、每次收口盘点、任务与多表状态、逐修复lesson要求，对小改动容易叠加成本；应区分硬边界、默认做法和工具建议。 +本会话没有测试耗时/误报率统计，不虚构量化收益；提出的改进以规则文本和已出现流程阻塞为依据。 +保留真实权限、持久性、运行制品、敏感数据和已确认外部副作用边界。 + +新增KTD14及验证分层/证据复用/规则强度说明，扩展U2的规范模板同步和日常演练，新增R16/V24/V25。 +不新增implementation unit或独立报告，避免为了精简流程再扩大产物层级。 +本轮仅修订三文档，使用新的r5执行登记承载同一个逻辑task_id；上一轮一次性豁免已结束，本轮不自动沿用。 + +修订5验证：三文档结构、6个相对链接、R1–R16/U1–U9/V1–V25唯一性与待审状态检查通过，git diff --check通过。只读cleanup为18项blocked、0项ready，docs drift无回退；未清理工作区。正常agentctl with写入，无需也未沿用上轮临时豁免；未提交、推送、修改生效规范或执行产品测试。 + +## Revision 6: Remove Coding Workflow Dependence + +用户明确反馈Agent主要精力被agentctl任务领取、提交、合并消耗。本轮收敛KTD13/14的职责，新增KTD15：普通编码流程零agentctl依赖，任务/PR单一状态来源；治理恢复归维护者，发布部署独立。 +这不是已经测得时间占比；依据为用户观察与本会话两次跨工作区锁阻塞、登记续办及blocked CLI不匹配的实际记录。 +修改U2优先顺序，先完成本地减负与Gitea交接，再做多仓适配；不把新的task/reopen/claim平台作为减负前提。新增V26端到端日常流程验收。 +本轮仅修订原三份待审文档，不启用新规则，不提交/推送；现行登记仍按当前工具执行，逻辑task_id未变。 + +## Revision 7: Single Executable, Instance Configuration and Native Infrastructure + +用户连续补充：同一套单文件应用供测试/生产等多个实例，通过启动配置隔离；希望.env、CLI、系统设置后读覆盖；进一步评估KB/DB/文档库用launcher、daemon、应用内启动或原生程序。 +本轮作为原任务续办，只完善原三文档；此前中断段只读检查已完成，没有启动或变更产品服务。 + +### Baseline and Current Source Checks + +原研究worktree仍HEAD=de90d0cd（业务源码基线a3db288a）；主目录本轮已为test@fd177f8dd5c7e5714476b59efc1b9a2ae27bdb22，dev=b9339cd27206f519f423eaa6a1601d3a67dfac01。 +没有切换/重置主目录或重新合并业务源码。 +对a3db288a..dev的config/localpg/sysadmin settings/db migrate/main/app/templates/web embed/build-single-binary以及kb/storage/workspace/docrevision相关路径做diff --stat，无差异输出；本节结论同时适用于本轮核对的这些dev路径，不能推及未查模块或运行环境。 +没有读取.env真实值、用户output.md、workspace.json、运行数据库数据或修改系统设置。 + +### Source Findings + +| 来源 | 已确认事实与影响 | +|---|---| +| cmd/server/main.go:22–40、config/config.go:103、159–174 | 默认→env文件→进程env，CLI只覆盖env/port/host/backend；默认.env路径与Load空字符串的overlay路径不同 | +| config/config.go:99、localpg/localpg.go:36/48/74 | 存在dev默认路径与部分直接os.Getenv读取；尚非统一最终配置快照 | +| sysadmin/settings.go:78/229/275 | 独立DB→进程env→默认解析，不直接消费已合并CLI/.env的cfg；不能说所有系统设置已整体覆盖启动配置 | +| sysadmin/service.go:NewService、settings/store | 系统设置来自所选业务PG，key无实例命名空间；用它配置自身连接会循环 | +| sysadmin/apply.go、settings.go:199、app/app.go | 部分键推送PI /admin/reload；保存、热更新和真正启动消费并不等价 | +| db/migrate.go:RunMigrations/ResolveMigrationsDir | 当前Goose从磁盘SQL目录读取；现有二进制尚未内嵌全部迁移 | +| web/embed.go、templates/embed.go、template/loader.go、squad/service.go | Web与部分Markdown已内嵌，agent指令和xlsx等仍依赖磁盘路径 | +| localpg/localpg.go:100/123/271/287 | 查找已安装PG→可initdb建cluster→createdb建应用库→启用vector；不是安装数据库，也不创建独立KB语料库 | +| localpg/localpg.go:187/261/307、cmd/server/main.go | 当前按端口就绪判断、已有角色bootstrap、started标记与defer清理不足以证明所有权/崩溃恢复；os.Exit可绕过defer | +| kb/client.go:75/94、kb/store.go、kb/embed.go | KB是应用内检索代码直连PG；embedding/reranker为外部HTTP能力；连通不等于语料与索引已准备 | +| storage/cas.go:42、workspace/capability.go、docrevision/pg_store.go | 文档库由PG账本/内容与持久文件组成，非独立文档daemon | +| app/app.go:224、workspace/lease.go | 进程内workspace租约不足以宣称多副本共享同一数据根已安全；独立实例与HA副本分开 | +| cmd/server/main.go:71、cmd/events/main.go | server已有可选内置events consumer，单文件模式可收敛到同一程序角色，不必分发第二个应用程序 | + +两项后续调查候选：配置解析双路径/生效声明不一致、managed-local PG所有权与失败回收不足。 +本轮没有运行复现或修复，不登记为resolved，不改共享ISSUES索引；U10中给出针对性正负例。 +既有data-dir-doubled、PI runner DATA_DIR覆盖、隔离DB经验直接用于路径归一化与禁止隐式dev回退的验收设计。 + +### Decisions + +1. 单版本单个Ubuntu amd64应用文件内置Web/SQL/prompts/xlsx等资产，同文件可启动多个独立实例；配置/数据/日志不打进程序。 +2. 不新增应用launcher/KB/文档daemon；同一二进制提供serve/init/migrate/config检查，系统服务管理应用和原生PG。 +3. 产品部署设置放独立实例配置根的instance-settings文件，作为普通部署参数的最终层；产品业务策略仍在所选DB，key各有唯一owner。 +4. bootstrap identity/config_root/settings读取模式不自覆盖；DB/KB/目录等可经UI配置，但须重启/迁移后确认applied，不能在进行中任务里换一半。 +5. 默认existing；显式创建逻辑库与安装PG/建立cluster/迁移schema/导入KB区分；managed-local仅可选自有cluster。 +6. 配置身份、DB角色、可写目录、cookie/密钥、Runner上下文和文件/数据库备份同时隔离；一套二进制不构成隔离证明。 +7. U10为应用部署新工作，U6a要先满足其最小单文件/外部PG出口；不把该需求隐藏在U9的PI能力替代里。 + +复核由独立只读子审查覆盖配置链、存储/进程依赖与设计一致性，补齐saved/applied、最终配置冲突检查和外部进程停止权。 +本轮没有额外外部模型审查、编译、initdb、建库、启动/停止daemon、服务配置写入或业务数据迁移。 + +### Primary References + +- [PostgreSQL initdb](https://www.postgresql.org/docs/current/app-initdb.html)：cluster初始化与原生进程身份。 +- [CREATE DATABASE](https://www.postgresql.org/docs/current/sql-createdatabase.html)：逻辑数据库创建。 +- [PostgreSQL启动与系统服务](https://www.postgresql.org/docs/current/server-start.html)：原生postgres/pg_ctl和系统服务职责。 +- [pg_ctl](https://www.postgresql.org/docs/current/app-pg-ctl.html)：原生管理边界。 +- [pgvector项目](https://github.com/pgvector/pgvector)：PG内扩展而非单独daemon。 +systemd官方man页面本次抓取403，未将该失败当作成功资料；系统服务建议参考PostgreSQL官方启动文档。 + +修订7验证：3文档结构、6个相对链接、R1–R19/U1–U10/V1–V34唯一性与待审标记检查通过，git diff --check通过；只读cleanup为20项blocked/0项ready，docs drift无回退，未清理。源码/配置/生命周期定向复核完成；未编译、建库、运行实例或部署。文档通过正常agentctl with保存，本次未使用临时豁免，仍不提交/不推送。 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..013fd098 --- /dev/null +++ b/.doc/ops/short-term/2026-09-28-multi-repo-design.md @@ -0,0 +1,126 @@ +--- +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 执行迁移。 + +## 修订 2：前端与 Agent-Native（2026-09-28） + +用户追加前端拆仓、自研 Agent 和第三方 Agent 接入方向；原“待审、不生效”授权边界继续适用。 +沿用逻辑 task_id 与 worktree；旧执行登记已关闭且工具无 reopen，续办执行登记为 multi-repo-design-2026-09-28-r2，不扩大三个文档路径 scope。 + +完成源码确认：助手与 Squad 共用 agent.Backend/NewBackend；原生内核位于 agentx，pinative 是产品适配；源码默认仍 pi-agent，部分增强功能仍按该名称装配，运行态未验证。 +新增 Agent-System-Web/Agent-Native 设计、契约与权限边界、旧名兼容、PI fallback 真正执行身份、Web 单二进制资产装配，以及对应迁移单元与验收。 +通用规范/模块契约记忆仅辅助定位，当前结论来自新读源码；没有实施或扩大运行权限。 +不新增 validated lesson；本轮未修复或运行验证。 +原任务的首轮审查/盘点保留为历史记录，修订 2 的结果单独记于证据。 + +## 修订 3：Ubuntu与原生核心替代 + +用户确认Ubuntu 26.04 x86_64单平台与PI核心能力对齐方向；新增执行登记multi-repo-design-2026-09-28-r3，逻辑task_id与三个写路径保持。U9独立于拆仓与现版发布，不实施、不改默认后端、不推送或部署。 + +## 修订 4：多仓开发治理精简 + +来源：用户明确要求重新审视规范、锁、agentctl，可删减无必要或反复阻塞的机制并增加适合新方案的能力；只修订待审方案。 +沿用multi-repo-design-2026-09-28逻辑任务及仍active的r3执行登记；仅更新原三个文档。 +交付变化：KTD6改为Gitea原生准入；新增KTD13治理取舍/锁与恢复模型，重写U2，增加R15与V19–V23；补落盘上轮Ubuntu单平台和PI核心能力对齐U9。 +已核验一次全仓恢复阻塞的实际因果链，并保存为audit中的问题候选；未修复工具，不把历史恢复次数当错误率。 + +临时例外：用户批准仅三份待审文档的一次性写入租约豁免，owner=Codex，期限=保存即终止，禁止改锁/工具/现行规范/提交/推送，恢复为正常租约写入。 +原锁先恢复，方案主体通过agentctl with保存；随后新候选准备操作出现相同全仓恢复阻塞，最终三文档保存使用已批准豁免。没有解锁或修改现行工具/规则；保存校验结束立即终止豁免，按用户明确范围不提交或推送。 +本轮研究产物完成后仍review_state=pending、policy_state=proposed，部署/实施/远端设置均未执行。 + +最终校验：3份文档、6个相对链接、15项要求、9个实施单元、23项验收场景，结构/ID/链接/旧方案残留检查通过；git diff --check exit=0。收口盘点cleanup total=18/blocked=18/ready=0，未清理；docs drift regressions=0/open_capabilities=3。没有实施、编译或真实运行验收。本轮使用的一次性三文档豁免至此结束，不提交/不推送。 + +## 修订 5：日常规范按影响适配 + +用户要求按最新方案适当完善过严规范；继续只更新三份待审文档，不提交/推送/实施。 +逻辑task_id不变；机器执行登记multi-repo-design-2026-09-28-r5承接本次，旧登记不重开。 +增加KTD14：四类工作影响、精简默认、按阶段验证与适用证据复用、硬边界/默认/建议区分；U2负责同步规范、模板、客户端与CI。 +保留原规范已合理的纯文档轻验证、按机制回归和真实证据要求；不把放宽流程误写为跳过必要验证或扩大外部授权。 + +修订5验证：三文档结构、6个相对链接、R1–R16/U1–U9/V1–V25唯一性与待审状态检查通过，git diff --check通过。只读cleanup为18项blocked、0项ready，docs drift无回退；未清理工作区。正常agentctl with写入，无需也未沿用上轮临时豁免；未提交、推送、修改生效规范或执行产品测试。 + +## Revision 6: Remove Coding Workflow Dependence + +用户明确反馈Agent主要精力被agentctl任务领取、提交、合并消耗。本轮收敛KTD13/14的职责，新增KTD15：普通编码流程零agentctl依赖，任务/PR单一状态来源；治理恢复归维护者，发布部署独立。 +这不是已经测得时间占比；依据为用户观察与本会话两次跨工作区锁阻塞、登记续办及blocked CLI不匹配的实际记录。 +修改U2优先顺序，先完成本地减负与Gitea交接，再做多仓适配；不把新的task/reopen/claim平台作为减负前提。新增V26端到端日常流程验收。 +本轮仅修订原三份待审文档，不启用新规则，不提交/推送；现行登记仍按当前工具执行，逻辑task_id未变。 + +## 修订 7：单文件应用与可配置多实例 + +用户要求统一单文件应用制品、通过启动配置隔离test/prod及其他实例，并评估存储依赖的启动方式。 +新增KTD16–18、实例隔离与数据目录、U10；替换旧外置assets部署包合同，扩充R17–R19及V27–V34。 +推荐应用入口内置、自带应用静态资产，PG原生服务，KB/文档逻辑在应用内；部署设置使用独立config_root的本地持久层解决DB启动循环。 +实例名不再绑定Git分支；同版本制品只构建一次，各实例固定版本与自己的配置/数据。 +原任务worktree/逻辑task_id不变，执行登记multi-repo-design-2026-09-28-r7。主目录当前test，未切换/部署；对本轮涉及路径复核最新dev差异。 +仍只修改三文档、不提交或推送；新配置/初始化/迁移与服务生命周期尚未实施，不会因方案示例创建目录或数据库。 + +修订7验证：3文档结构、6个相对链接、R1–R19/U1–U10/V1–V34唯一性与待审标记检查通过，git diff --check通过；只读cleanup为20项blocked/0项ready，docs drift无回退，未清理。源码/配置/生命周期定向复核完成；未编译、建库、运行实例或部署。文档通过正常agentctl with保存，本次未使用临时豁免，仍不提交/不推送。 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..083ff07d --- /dev/null +++ b/.doc/remediation/2026-09-28-multi-repo-architecture-plan.md @@ -0,0 +1,1116 @@ +--- +title: "Agent-System 多仓库、PR 协作与发布架构方案" +date: 2026-09-28 +revision: 7 +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 指产品中生成文档与处理复杂任务的小队；开发协作治理工具可以另行考虑；内部测试制品必须私有，公开版公开。 +修订 3：用户确认近期仅交付当前 Ubuntu 26.04 x86_64 平台；确认自研 Agent-Native 对齐 PI 核心能力并逐步替代。本轮仍只修订方案。 +修订 4：按用户要求重新评估锁/agentctl/文档与集成规范，以原生 Gitea 门禁和实际共享资源保护替换跨工作区的全局开发门禁；所有新规则待审。 +本次补充：用户希望前端独立管理，将 pi-native 演进为可复用的 Agent-Native，既支持自研执行内核，也能接入其他 Agent；本修订替换上一版“不拆 Frontend”的建议。 +修订 7：用户要求一个单文件应用按启动配置运行多个隔离实例，新增配置优先级/生效模型和数据库、知识库、文档存储的原生运行与启动职责。 +以下推荐技术选择均为待审建议，不把本次答复理解为实施授权。 + +--- + +## 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 发布 Ubuntu 26.04 x86_64（linux/amd64）单文件应用制品；Apple Silicon 与 Ubuntu ARM64 暂缓 | +| R8 | 内部测试发布私有，公开测试/稳定版公开；权限隔离经未授权访问测试验证 | +| R9 | 迁移可追溯、可分阶段停止，保留活跃任务与运行数据，不自动改数据库 | +| R10 | 本轮仅调研与待审方案，描述先拟稿，不让新方案生效 | +| R11 | 前端独立源码仓、构建与测试，继续支持同源访问和嵌入单服务二进制发布 | +| R12 | Agent-Native 作为助手与 Squad 共用的版本化执行基础，支持原生内核与外部 Agent 适配 | +| R13 | 区分模型接入、Agent 接入和工具接入；新增后端经能力与行为验证，不隐式扩大权限或切换默认实现 | +| R14 | 以固定 PI/Runner 基线对齐自研 Agent-Native 的产品核心能力，经独立验收和渐进启用逐步替代；不要求上游全产品复刻 | +| R15 | 简化开发治理：独立工作区不相互锁死，Gitea 管远端准入，真实共享资源保留互斥/恢复，agentctl 不成为普通开发的单点依赖 | +| R16 | 日常规范按实际影响适配：低风险工作精简记录与验证，高风险保留适用门禁；硬边界、默认做法和建议明确区分 | +| R17 | 同版本只构建一个单文件应用，通过配置启动任意命名的多个隔离实例，不按环境分别编译 | +| R18 | 统一.env、进程环境、显式CLI、实例系统设置的覆盖、来源和生效时机，解决启动循环与配置旁路 | +| R19 | 应用内置启动/初始化入口，生产PG采用原生服务，KB/文档逻辑留应用内；明确创建、连接、停止与数据恢复归属 | + +### Actors and Flows + +A1 开发者/编码 Agent：写 fork 功能分支，提交组件 PR 与组合 PR。 +A2 审核者：确认产品边界、代码与测试，批准精确 head；作者不替代自己的审批。 +A3 受控合并执行者：按仓/分支串行处理候选，经Gitea原生PR入口合并；不直推或代替 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 构建产物与 Agent-Native；迁移仍与数据写者同仓 | +| Agent-System-Web（拟新建） | React/Vite 前端、API/SSE 客户端、交互与浏览器测试 | 独立 npm 构建；不因独立仓库而强制独立域名/部署 | +| Agent-Native（拟新建） | 公共执行契约、自研 Agent 内核、模型/工具能力、外部 Agent 适配与契约测试 | 从 agentx 与 agent 分层提取，默认进程内调用；agent-native 为规范后端名 | +| 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，不能声称过渡态已完成最终结构。 + +前端改为独立 Agent-System-Web；自研执行基础与适配器放 Agent-Native，不再另建泛化的 Agent-System-Runner/Contracts 仓。 +暂不单拆数据库迁移、公共 Types/Contracts、每个 agent 或每种 workflow；契约由生产方代码仓维护，避免循环依赖。 +现有 `deploy/pi-agent/` 先原位保留以保持可回退；其通用 runner 协议实现/发布资产在 U7 的兼容阶段逐项迁到 Agent-Native 的 adapters/pi-runner，产品环境配置、授权、workspace 映射留 Core/主仓。 +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/web/ # Agent-System-Web + modules/agent-native/ # Agent-Native + 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：助手产品逻辑、授权与数据"] + Root --> Web["Web：独立前端构建"] + Root --> Native["Agent-Native：执行契约与多后端"] + Root --> Squad["Squad：执行与质量能力"] + Root --> Docs["Development Documents：项目知识"] + Root --> Guide["Development Guidelines：通用规范"] + Root --> Manager["Development Manager：开发治理工具"] + Web -->|"同源 API / SSE"| Core + Core -->|"任务编排"| Squad + Core -->|"助手执行 / 注入已授权后端"| Native + Squad -->|"窄执行契约"| Native + Native --> Local["自研内核：loop / model / tools"] + Native --> External["外部 Agent 适配器：现有 PI Runner 等"] + Root --> Build["组合构建与原生验收"] + Build --> Internal["私有 Releases Internal"] + Internal -->|"发布批准 + 制品摘要核对"| Public["公开 Releases"] +``` + +### KTD1. Split Ownership Without Splitting Runtime + +Squad 独立 Go 模块，以公开 API 提供执行能力，主应用注入依赖。 +其执行端口复用 Agent-Native 的小型公开 contract 包，不自行创建 native 内核或选择外部后端；contract 不依赖 Squad/Core，具体适配器由 Core 组合根装配。 +不直接导入 `chat-agent-system/internal/*`，不改名伪装成主仓以规避 Go internal 限制。 +独立库不持有产品 DB 连接、用户鉴权或正式文档提交权。[Go 官方模块布局](https://go.dev/doc/modules/layout) + +| 现有耦合 | Squad 边界 | Core 保留 | +|---|---|---| +| config/backend factory | Options + Agent-Native 执行契约 | 环境授权、凭证注入、后端选择；通用执行适配在 Agent-Native | +| 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/活动任务暂留原管理路径。 +完成文档 PR 权限、结构/证据 CI 与多仓证据 URI 适配后，再迁移活动文档；旧 docs apply/收据在新链路验证后退休，不继续扩展成多仓审批数据库。 +新证据引用使用仓库标识 + 完整 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` 与 `../agent-native`，Squad 的 contract 依赖指向 `../agent-native`；整个组合仍由 gitlink 锁定。 +Agent-Native 自身必须可单独拉取编译测试，不反向依赖 Core/Squad。Web 是 npm 项目，不要求为了 go:embed 人为成为 Go 子模块。 +Core 可独立 clone，但构建前须按受控 bootstrap 获取固定依赖；组件 CI也使用同一个依赖解析入口。 +`go.work` 仅本地可选，正式构建设 `GOWORK=off`，避免开发者私有 workspace 掩盖依赖缺失。 +Squad 自身可在物化固定版本 Agent-Native 契约依赖后独立构建测试；Core/Squad 依赖版本的精确物化由主仓候选流程提供。 + +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–U9 的当前交付承诺。漏事件由轮询补偿。 + +自动后台只允许 fetch 和状态提示。 +同步器遇到脏文件、正在测试、未提交子仓或冲突时停止工作区改动，记录 sync_required；不 stash/reset/自动提交。 +共享/已公开任务分支默认 merge upstream 保留历史；rebase 仅由 owner 在自己的可重写分支上显式发起，不后台强推。 + +子仓有新提交时创建组件更新 PR，由组合验收决定是否采用；不自动跳过主仓审核。 +队列准入绑定 repo_id、PR ID、source head、target base、组件清单摘要与策略版本。 +任一值变化，旧验证失效；需要重新生成受影响候选和相应审核，不能拿旧 SHA 的绿色结果放行。 + +“同步及时”与“测试可复现”同时成立的标准是：可见地落后、在明确检查点更新、被测组合不在测试中途变化。 +不承诺所有工作区每秒都等于上游。 + +### KTD6. Gitea Owns PR Integration + +本次治理复审替换前版“自建签名收据网关 + 机器人直推 + manually-merged 回写”的默认路线。 +采用 Gitea 原生 PR 合并、分支保护、非作者审核及必需 CI 作为远端准入权威，减少本地与远端两套审批/引用推进机制。 +主仓仍保留dev→test→main的源码晋升约定；运行实例由不可变制品与配置定义，名称不绑定分支。子仓main表示已审核组件，不代表部署；公开发布/环境晋升仍独立授权。 + +禁止开发者和普通 CI token 直推受保护分支、禁止强推；明确 required checks，内容变化撤销旧审批，过期分支阻止合并。 +保护规则适用于 API/Web/SSH/HTTP 等入口；具体实例行为先在演练仓验收。[Gitea 保护分支](https://docs.gitea.com/usage/access-control/protected-branches/) +不再把开发机 SQLite 或本地 hook 当作远端授权边界；Gitea 不可用时可以继续离线编辑/提交，合并、发布和部署等待恢复。 + +合并前测试绑定目标 base D、PR head T、合并候选源码 tree 与组件 manifest 摘要。 +Gitea PR Actions 默认是 head ref，必须显式构建合并候选；不能直接把 head 测试当组合通过。[Gitea Actions FAQ](https://docs.gitea.com/usage/actions/faq/) +队列首期只允许一个受控合并身份经原生 PR API 合并，普通开发者和其他机器人没有并行合并权；按 repo+target branch 串行，不锁文件编辑。 +原生“分支必须最新”与 head/base 复核共同防陈旧结果；目标前进则重建受影响候选。此处是拟实施流程，不声称实例已自带完整 merge queue。 + +Gitea 可以生成不同元数据的合并提交，因此移除“本地预生成 merge SHA 必须原样成为远端 SHA”的惯例。 +保留更直接的证明：合入后的确切 commit/tree/gitlinks 与被测候选内容一致；正式构建、签名、发布和部署全部绑定合入后的真实 SHA 和制品摘要。 +使用保留内容的 merge 模式；检测到 tree 不符、意外父链或新 base 变化时，不发布、不部署，进入重新验证或普通 revert PR。 +若 runner/native protection 不能可靠阻止过期合并，首期人工受控串行审核合并并显式重验；不在能力缺失时放开多写者，也不为此默认建立全新分布式控制平台。 + +对共享运行环境、迁移与发布仍保留执行互斥，但独立 build/test、开发分支和文档不需要占用它。 +切换前先排空/核清旧 agentctl 操作，处理本地未同步提交，再正式停用旧本地 dev 推进入口；未切换前现行规则继续有效。 + +### 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 当作产品协调状态。 +agentctl 的本地登记/索引仅是可重建辅助；普通编辑/提交不要求其常驻或连库。受信部署/发布执行器保留独立持久操作日志，其记录不能当缓存删除。 +具体裁剪与替代项见 KTD13；先验证 Gitea 与环境执行器的保护，再移除旧本地强制门禁。 + +### KTD9. Agent-Native Is a Shared Execution Foundation + +结论：可行且有价值，建议将仓库命名为 Agent-Native，规范后端标识为 agent-native。 +这里的 native 表示项目自有的执行内核，不承诺只能本机运行，也不把外部 Agent 排除在接入层之外。 +仓库包含轻量公共执行契约、原生实现和可选外部适配器；它不是产品助手本身，不负责完整业务流程。 + +已确认当前复用关系： +- internal/app/app.go:132 为助手组装 agent.NewBackend，注入 coordinator。 +- internal/coordinator/dialogue_llm.go:126 调用 Backend.Execute，当前通过 reply.md 获取回答。 +- internal/squad/service.go:261、402 使用相同工厂执行任务和工作流。 +- internal/agent/backend.go 同时支持 pi-agent/pi-native/stub；pi-native 实际是 native 主执行 + pi-agent fallback 包装。 +- internal/agent/pinative.go 将请求接到 internal/agentx；后者有 loop、llm、tools、session，非测试实现主要在自身子包间依赖。 +- 源码默认后端是 pi-agent；本次没有读取或变更运行实例的有效后端。 +- semantic summary、文档变更叙事和 U9 segment 在 app 组合根仍检查 backendName == pi-agent，不能宣称这些功能已对 native 完全等价。 + +因此，用户记忆中的“共有后端”在接口与工厂层成立，尚不是全部功能、运行状态、故障语义统一的成熟插件平台。 +只搬 pinative.go 会遗漏真正的内核，也会留下 config/workspace/materialization 反向依赖。 + +建议一个仓库内分四层，首期一个 Go module，不另外建立公共 Types 仓： + +| 层 | 职责 | 依赖边界 | +|---|---|---| +| contract | Execute 输入输出、事件、错误、能力、取消和产物标识 | 不依赖具体内核、产品类型或数据库 | +| runtime | agentx 演进的多轮循环、工具调度、模型调用、执行会话 | 实现 contract；不导入 Core/Squad | +| adapters | 当前 PI Runner transport/result-v1；未来其他 SDK/CLI/远程 Agent | 对外部差异做显式映射，不伪造缺失能力 | +| conformance | 所有 backend 共用行为验收与兼容 fixtures | fake 验证契约，真实 adapter 验证能力，两者分别记证据 | + +Core 保留用户/项目身份、业务上下文与记忆、工具授权、模型凭证选择、任务持久终态、正式文档提交、数据库以及产品型搜索/工作流适配。 +Squad 保留任务分解、角色/步骤协作、质量门禁、步骤级预算与重试决策。 +Agent-Native 执行一次授权的 Agent 调用，接收已裁剪上下文与受限能力；不能自行扩展工具或拿产品 DB 凭证。 +执行 transcript 与产品聊天历史不是同一账本；Core 可通过 SessionStore/ExecutionJournal 端口映射持久存储。 +当前 .agentx/transcript.jsonl 不是跨实例租约或 exactly-once 执行证明，目录名称在兼容期保留，不因改名搬业务数据。 +原生工具的路径约束也不是 OS 沙箱；执行不可信第三方工具需要相应进程/容器隔离，不能由独立仓库或接口名称推导隔离已经成立。 + +当前 Request 的 Targets/文件交付偏向任务执行；新 contract 支持明确的文本结果与可选产物，保留 file-only facade 兼容 reply.md/既有 target 流程。 +统一输入至少表达 execution_id、session_scope、messages/context、workspace handle、工具策略、预算与截止时间、所需 capabilities。 +结果/事件区分文本、文件候选、完成/失败/取消/unknown、token 用量以及副作用状态。 +这些字段为设计要求，不表示当前接口已实现。 +Core 将执行事件映射为产品 SSE/任务事件；不把供应商私有消息字段直接变成长期 Web 合同。 + +### KTD10. Three Extension Seams and Controlled Routing + +“接入模型”和“接入完整 Agent”分别建接口： + +1. ModelProvider：给自研 runtime 提供模型推理、流式文本、工具调用和用量。当前 llm.Client 是兼容 Chat Completions 的实现，并不自动兼容所有供应商 API。 +2. AgentBackend：接入已自带循环、工具与会话机制的 SDK/CLI/远程 Agent。自研 agent-native 是一个实现，现有 pi-agent 是另一个实现。 +3. ToolProvider：向允许工具调用的执行实例提供工具/资源，例如本地受限工具或后续 MCP 适配。MCP 的上下文/工具交换不能替代整个 Agent 执行合同。[MCP 官方架构](https://modelcontextprotocol.io/docs/learn/architecture) + +未来吸收其他 Agent 的能力，优先做可替换策略（上下文裁剪、工具调度、规划、重试、记忆），不把多个完整主循环叠起来争用会话、工具和预算。 +借用实际开源代码前记录来源版本、许可和必要归属；本轮不选定新厂商 SDK，也不承诺任意 Agent 无需适配即可接入。 + +BackendDescriptor 声明可验证的 text/files、stream、tools、cancel、resume、usage、structured-output 等能力。 +Core 的策略 resolver 按任务需求与授权选择实现；Squad 只表达需求、使用已注入后端。 +不支持必须能力时拒绝，非必须功能可显式降级；未知 backend ID 返回错误，生产不能落到 StubBackend。 +当前工厂 default 返回 StubBackend，而 taskrun 有另一个 allowlist，实施时统一所有助手/Squad/CLI/管理入口的解析，不仅修改一个 switch。 +前端只展示经过授权的后端能力和实际状态；不能把浏览器传入的任意名称当授权。 + +pi-native → agent-native 采用兼容迁移： +- 新名称在统一 registry 注册，旧 pi-native 保留明确 alias 和弃用周期；客户端和 CLI 在兼容期都可解析。 +- AGENTX_* 等现有配置先由 Core 适配注入，保留旧字段；新增 AGENT_NATIVE_* 时明确新字段优先、冲突警告只报字段名不报值。 +- 不借改名改变默认后端、默认模型、工具范围、fallback 或已有 transcript 根；这些变化需要独立验收。 +- 配置迁移、taskrun allowlist、CLI 帮助、管理 UI、日志、fixture、receipt 一起清查，防止部分入口拒绝新名而另一些静默变 stub。 +- 已有 pi-agent 专属增强功能在兼容清单中保持原策略，逐项以能力门禁替换品牌判断；未验收不放开。 + +当前 fallback 在 native 未成功且未取消时会尝试 pi-agent；仅查看请求的 backend 名称或最终 Success 不能证明 native 实际完成。 +迁移收据记录 requested_backend、effective_backend、adapter_version、model/provider 与 fallback_reason，并区分“未派发”“确认未执行”“可能已有副作用”。 +原生失败已有文件/外部动作或结果 unknown 时禁止无条件换 Agent 重放；重试与 fallback 共享 execution_id、预算/截止时间和恢复判断。 +步骤级重试归 Squad，transport 内有界重试归 adapter，循环 turn 上限归 runtime，避免层层相乘。 + +共享后端代码不等于共享可变会话。 +可以复用无会话的客户端连接池；执行上下文、workspace、transcript、授权与预算按 tenant/project/session/execution 隔离。 +取消必须传到模型请求/工具/子进程；不支持可靠取消的外部 Agent不能伪报已取消，暴露 cancel_requested/unknown 并由 Core 恢复。 + +首期保留现有进程内 native 与 HTTP PI Runner 两种边界；不引入 Go 动态 plugin、万能 shell 命令拼接或任意远程 URL 执行。 +后续 CLI adapter 需固定 argv/schema、受控进程组、工作目录、环境与凭证最小化，并验证取消与进程退出；HTTP adapter 需明确认证、服务信任、幂等和网络故障语义。 +新增后端先通过 conformance，再在助手与 Squad 的隔离真实路径试运行，最后通过配置 PR 显式启用。 + +### KTD11. Independent Web Source, Unified Product Delivery + +建议 Agent-System-Web 独立管理。 +现有 web/package.json、vite.config.ts 和 npm 锁文件已形成独立构建边界；主要产品耦合是 API/SSE/auth 合同和二进制资产打包。 +独立源码不要求独立公网域名或独立部署：首期仍由 Core 同源提供 UI 与 /api，开发阶段用 Vite proxy。 +浏览器不能直连 Agent-Native/PI Runner 或持有模型密钥，产品授权继续经 Core 执行。 + +API 和 SSE schema 归 Core，Web 固定消费已审核版本。 +第一步盘点现有手写 TS DTO、错误信封、鉴权头/cookie、SSE 事件与断线续传、文档刷新失效机制；不要假设已有完整 OpenAPI。 +新增 Core contracts/http 与 contracts/events 的版本化合同及 fixtures，Web 在自身客户端做 contract tests；不为每个 JSON 字段另建共享仓。 +兼容的追加字段优先；破坏性修改走关联 PR 和组合版本更新。首期只承诺同一主仓组合配对的 Web/Core；前端独立热升级或 N/N-1 跨版本支持是后续专项。 + +保留二进制嵌入能力的方法： +1. 主仓按 gitlink 导出 Web，npm ci/build 得到不可变 dist 与摘要。 +2. 在隔离构建上下文中，将 dist 物化到 Core 的 internal/webassets/dist；embed.go 留 Core，源码仓不提交 dist。 +3. 校验 index.html、引用的 chunks、字体和预压缩资源齐全后编译 Go，制品记录 Web SHA/资产摘要。 +4. 公开包使用声明的内嵌资产；显式外置资产模式才允许磁盘覆盖，并要求清单匹配。 + +现有 web/embed.go 随 web 目录一起搬走会断开 Core 的 Go import。 +不能改成 go:embed ../web/dist，也不能用软链接跨模块绕过；Go embed 受包相对路径和模块边界限制。[Go embed 文档](https://pkg.go.dev/embed) +推荐构建时复制不可变产物，不建立另一个手工维护的前端副本。 + +Core 尚未提取时，internal/webassets 先位于当前应用仓，U5 再随应用整体迁移；不提前要求新的 Core 仓存在。 +现有 static_assets.go 优先搜索 cwd 与 DATA_DIR 附近的 web/dist，拆仓后可能误取旧前端而覆盖内嵌版本。 +发布模式必须禁用隐式多路径猜测；开发模式可显式指定受控资源目录。 +保留 SPA 路由回退、缺失 /assets 返回 404、index 不长期缓存、hash chunk 缓存、gzip/br 协商；跨仓后仍跑现有 static_assets/web_assets 回归。 +从旧源码目录启动新二进制，也必须服务该制品声明的前端版本。 + +前端独立 npm test/build 负责本组件；API、权限、SSE、刷新/重启与真实文档任务仍在主仓固定组合中浏览器验收。 +测试 fixtures 与 e2e 可跟随 Web，但真实测试环境/账号准备由主仓显式提供，不把真实 .env、数据或凭证复制进前端仓。 + +### KTD12. PI Core Capability Parity and Gradual Replacement + +用户已确认目标：让自研 Agent-Native（现 pi-native）对齐现有 PI Agent 的核心能力，逐步具备替代条件。 +对外继续使用自有名称 Agent-Native；pi-agent 保留为外部基线适配器，不把两个 backend ID 合并、互相冒名或自动切默认。 + +分三种完成声明： +- 协议兼容：能接收现有调用、返回正确结果，并不代表工具、质量、恢复等行为已对齐。 +- 产品核心能力可替代：明确列出的助手/Squad 场景与关键扩展，在相同权限及资源条件下达到验收标准。本次选择此目标。 +- 上游全产品复刻：完整终端 UI、主题、所有供应商登录、TypeScript 扩展 ABI、全部 SDK/RPC 等。当前不纳入，也不承诺原样运行任意 PI 插件。 + +对标基线必须同时固定三层：上游包版本、项目 PI Runner/扩展版本、模型/参数/工具策略。 +本仓 Dockerfile 固定 @earendil-works/pi-coding-agent@0.85.1；npm 元数据对应 gitHead=d981de1229ef899957bbe968bc8dcda02a21f477，发布清单还需固定包完整性与 runner 镜像摘要。 +该值是源码配方，不是运行容器版本证明；实施首步核对真实制品。不要对着不断变化的上游 main 宣称 parity。 +上游产品确有 RPC/SDK、会话与压缩、扩展机制；本项目包装器默认 --no-session、受限工具，还增加 Tavily 与 typed-result-v1，必须将“上游能力”和“项目实际依赖能力”分别列账。[上游说明](https://github.com/earendil-works/pi/blob/d981de1229ef899957bbe968bc8dcda02a21f477/packages/coding-agent/README.md) + +| 对标域 | 当前原生基础/证据 | 拟对齐范围与出口 | +|---|---|---| +| 执行循环/模型流 | agentx 有多轮 loop、工具调用、usage 与 turn cap | 流结束、错误、预算/超时语义和所需模型特性逐项对齐 | +| 文件与工具 | 已有读写编辑/list/grep 与路径检查 | 按产品 allowlist 对照工具语义、长输出截断、错误与越界负例；不自动开放 shell | +| 搜索/项目扩展 | PI Runner 含 Tavily 扩展及 /v1/search；native 没有由此自动继承 | 抽取或重写产品确实依赖的搜索工具，验证引用、失败反馈与密钥隔离 | +| 长上下文 | 有消息列表与本地 transcript，未证明上游 compaction 等价 | token 预算、压缩/裁剪与长文任务信息保留；与 Core 的产品记忆分工 | +| 会话/执行恢复 | JSONL 持久记录不等于幂等恢复；现 PI 包装器是临时会话 | 恢复/取消/unknown 与产品 task_runs 合同一致，不盲目复播有副作用工具 | +| 指令/技能/扩展 | 支持 prompt/instructions 和注册工具；非 TS extension ABI | 首期只迁移产品必需指令/工具/技能语义；不自动执行任意上游扩展 | +| 产物/协议 | Backend.Result 与 PI typed-result-v1 已有入口 | 文本/文件非空、run_id、错误分类、交付边界与事件映射兼容，未知结果失败关闭 | +| 产品质量 | 已有 6 个简单双后端 A/B 用例 | 覆盖真实助手、商务/研发文档、复杂任务、失败修复及权限；六例仅作 smoke | + +现有 internal/agentx/abtest/live_test.go 直接 NewPiNativeBackend，避免工厂 fallback 污染，这一点应保留。 +judge.go 只比较成功率、原生 P0 和 P95≤PI 的1.3倍，不能作为完整替代门禁；需新增用例集完整性、绝对成功门槛、语义质量及恢复/权限检查。 +对齐要求不追求随机自然语言逐字一致，而比较确定性协议、必须内容、任务质量和授权副作用。 + +替代分两阶段比较：先保持同模型/参数/上下文/工具限制，隔离执行引擎差异；之后再评估引擎各自适合的模型配置并分别报告。 +禁止只看最终 Success，原生验收必须禁用 PI fallback，失败保留为 native FAIL；生产 fallback 另行测试。 +双执行在独立 workspace/测试数据中进行，不能让原生和 PI 同时提交同一正式文档或调用两次外部写工具。 +低风险回放可以保存脱敏输入；有副作用操作用受控 fixture 或明确授权的独立沙盒，不能复制真实用户任务后双重执行。 + +### KTD13. Simplify Governance Around Actual Shared Resources + +用户授权在待审方案中重新评估旧规范与 agentctl；本节是拟议替换，不使旧规则立即失效。 +目标是让开发者在自己的 fork/工作区自由完成授权工作，把不可绕过的控制放在真正共享的资源和发布边界。 + +已确认的阻塞机制： +- scripts/agentctl.py 的 overlaps 仅比较 path: 后的相对路径；path:. 会与同管理库下所有 worktree 的路径冲突。 +- integrate_prepare 获取 path:.、git:index、git:dev；候选本来写自己的工作区，但其锁域覆盖全仓。 +- 候选 merge 失败/孤儿进程后，即使尝试 abort，也一律保留 recovery_required；未按“仅候选冲突”与“远端/环境状态未知”区分。 +- 普通 execute 对带 git:dev/env 资源的非零退出统一要求恢复；这有保护价值，但授权资源集合代替了实际副作用分类。 +- 同一物理 dev-integration.lock 同时用于 git:dev/env:dev，在部署改用固定制品后不必继续捆绑。 +- 本会话数据库快照存在1项这样的全仓恢复阻塞；历史167次recovered（144 command、22 prepare、1 integrate）只能证明人工恢复负担，不能把它们全称误报或缺陷。 +- 规则要求任务可 blocked/续办，工具 task close 只接受 done/cancelled，已关闭登记不能 reopen，导致本任务多次新增执行登记。 +- Development-Manager 的对应实现仍有相同锁逻辑，复制到独立仓本身不能解决。 + +不采用“把所有锁都删掉”；按资源和副作用替换： + +| 机制 | 取舍 | 新边界/替代 | +|---|---|---| +| 独立工作区每次编辑/提交都需全局 with | 删除常规路径硬门禁 | 工作区单 owner；Git 自身 index/ref 锁；本地检查不依赖中心库 | +| 跨 worktree 的 path/scope/mutex 排他 | 删除源码副本之间的硬冲突 | 同一文件可在不同分支并行；需求/改动重叠只提示，通过 PR 处理冲突 | +| 同一实际工作区被多个进程写 | 保留局部保护 | workspace_id+canonical path，单写者；别名/symlink不能绕过；允许协作时显式划分资源 | +| 只生成候选就锁 git:dev/path:. | 删除 | 临时独立候选；真正合并才按 repo+target branch 串行 | +| 普通失败一律恢复阻塞 | 重做分类 | 已知失败终止操作并释放对应执行资源；未知外部副作用隔离具体资源 | +| CURRENT/MATRIX 的 docs apply+内容收据 | 从普通 Git 文档流程删除 | PR版本历史、结构校验、差异检查、审批和证据链接；不再维护第二份可写状态 | +| 自建 pre-receive 收据网关/直推/手工合并回写 | 从默认方案删除 | Gitea 原生保护与合并；构建部署绑定最终 SHA/制品摘要 | +| 任务台账/目录库/语义重叠确认 | 收缩 | 一个任务主记录或 Issue/PR；索引只读可重建，语义相似结果不阻塞写入 | +| 共享 dev/test/main 环境写操作与长 E2E | 保留 | 按真实 environment_id 执行锁，凭证只在授权执行器；独立测试不占共享环境 | +| 发布/数据库迁移 | 保留并独立命名 | release repo+version、DB实例+schema；幂等操作和未知结果恢复 | +| 主目录必须承担开发集成与运行 | 调整 | 受保护分支以远端为准，部署从固定源码/制品入口；开发工作区不拥有共享服务凭证 | +| 所有 ignored 文件都挡清理 | 精简 | 对唯一成果/配置保留硬保护，已识别可再生缓存按清单清理；拒绝时不 force | +| 所有会话都全文读取/重复填多表 | 精简 | 短入口+按任务触发的规范；实质结论一个主记录，其他只链接 | +| CodeGraph、客户端 hooks、catalog、daemon | 降为辅助 | 可选、可重建、不因不可用阻止普通开发；权威保护在服务端/执行端 | +| 产品 IAM/文档职责/数据库事务/租约 | 保留 | 与开发工具锁不同，不能随本轮工程治理精简删除 | + +### Lock and Failure Model + +拟保留的资源身份只覆盖真实共享对象： +- 同工作区编辑：host_id/workspace_id/path（通常由单owner约定与Git本身处理，不开启跨副本排他）。 +- 远端合并：gitea_instance/repo_id/target_branch。 +- 共享验收/部署：environment_id（不是字符串dev在所有主机泛用）。 +- 数据库迁移：db_instance/schema；发布：release_repo/version。 +资源别名应归一化；不同 fork 的名字相同不意味着是同一个资源，不同路径指向同一实体也不能双占。 + +操作状态区分 preflight_rejected、running、failed_known、succeeded、outcome_unknown；这些是拟议操作结果，任务仍用现有五状态。 +预检拒绝没有启动动作，不生成“需要恢复的外部操作”。 +候选合并冲突只留下该候选工作区；子进程确认退出、target未变后释放合并准备资源。未确认仍只隔离实际候选资源。 +远端推送/发布/部署/迁移结果未知时保留恢复记录，查询目标真实状态后决定补记、重试或人工介入。 +超时/TTL只触发调查，不自动授予第二执行者写权；进程或租约过期不能证明外部命令未执行。 +恢复不靠删除锁文件；只对受影响资源执行有证据的恢复，失败不能阻塞其他工作区保存文档。 + +单Ubuntu主机首期采用本地执行器锁加持久操作日志；禁止把“锁超时可恢复”宣传为多机协调。 +多主机共享执行将来单独实现服务端身份/授权/租约/fencing；不共享SQLite文件，不提前部署分布式数据库来解决普通编辑阻塞。 + +### Agentctl Minimal Role + +保留名称也可以，但角色改为可选的统一入口： +- workspace start/status：创建或检查 clone/worktree，显示上游落后，不执行隐式stash/reset/pull。 +- verify：转发组件/组合检查，生成绑定SHA的报告；实际命令可直接在本地执行。 +- pr/status：查询或在已授权时调用Gitea，不另建审批库或取得直推权限。 +- deploy/release/recover：只在受信执行器处理真实外部副作用和环境授权，不接受任意shell作为万能远端动作。 +- doctor/cleanup inspect：只读定位问题，错误要列出资源、owner、操作与可行恢复步骤。 + +任务层与运行层分开：task_id稳定，attempt/execution_id区分每次执行。 +单一任务来源应表达in_progress/blocked/完成和续办；按KTD15不再为编码流程专门建设agentctl reopen，不能要求Agent造-r2/-r3业务任务才能继续。 +SQLite可继续作为本地缓存/操作日志，不再承担跨仓源码写权限或与Markdown双写的权威状态。 +CLI缓存损坏不阻止编辑/本地提交；共享环境执行器日志损坏则只停止它负责的高风险动作。 +不把缓存可重建推广到迁移/发布恢复日志：后者是不可随意丢弃的证据。 + +规范压缩为三层：Guidelines通用原则 → 各仓短AGENTS/PROJECT与机器契约 → CI/受信执行器规则。 +每条硬门禁需标明所保护的资源/风险、唯一执行入口、失败后的恢复范围与实际负例；不能只写“enforced”。 +任务/PR负责工作状态，CURRENT变成只读摘要或停止维护；FEATURE-MATRIX保留能力声明与审核证据，Git/CI校验替代专用docs写回协议。 +允许有证据的能力降级，经PR审查；保留异常回退告警，不将历史done永久冻结。 +产品运行模板和业务文档职责仍按产品规则处理，不与开发文档简化混为一谈。 + +### Governance Migration and Acceptance + +不做一次性卸载。U1先给每条现行规则列retain/replace/remove与新owner，U2完成替代门禁演练，然后才停旧入口。 +迁移顺序：保护Gitea与授权执行器 → 固定构建/部署对象 → 解除独立工作区全局依赖 → 文档改为PR治理 → 清理重复hooks/登记/收据路径。 +旧未完成操作单独核清；在途推送/部署/迁移结果未知时不能靠升级工具清空状态。 +导出必要历史与唯一证据，冻结旧管理库为只读；不是复制它到所有fork。旧记录可查询，但不得恢复为第二写权威。 +新工具故障时允许继续本地开发，合并/环境写动作暂停；回退治理入口需确认唯一权威后切换，不同时启用旧新两套保护分支写者。 + +验收必须包括： +1. 两个clone或worktree修改同路径，均可编辑和提交；一个仓库候选冲突不会阻塞另一个草稿。 +2. 同一工作区重复writer被提示/阻止；repo/path别名不能冒充独立资源。 +3. SQLite/daemon/CodeGraph不可用仍可本地开发；无审批/无CI/陈旧PR无法在Gitea合并。 +4. 源head或base变化导致候选过期；合入后tree与清单校验；部署只使用最终受验制品。 +5. 普通测试失败无需recover；孤儿进程、未知发布/DB结果保留有界恢复；无TTL盲目接管。 +6. 共享环境只允许一个write/E2E owner；隔离环境可并行；用户审批和凭证不扩散到fork CI。 +7. 旧任务原ID续办，blocked不伪装done；清理可再生缓存不丢未提交/唯一ignored成果。 +8. CURRENT/MATRIX迁移后状态/证据不丢失，任何旧agentctl入口都不能绕过新的远端/部署权限。 +9. 收集操作次数、known failure次数、unknown恢复次数及阻塞对象范围；把“正常任务要求手工recover”和“跨工作区无关阻塞”作为失败，而非把所有恢复次数当缺陷率。 + +### KTD14. Proportionate Rules for Everyday Work + +本节进一步精简日常规范，补充KTD13的工具/锁改革；适用的是开发流程，不放宽产品用户授权和数据边界。 +现行验证契约已经允许纯文档只检查diff/链接，也明确不机械穷举所有场景；保留这些合理规则，消除表格、模板、客户端习惯之间的过度解释。 +以行为影响和资源风险决定流程，不以改动行数、仓库数量或“使用AI”自动升级；同一改动多种影响并存时只合并相关检查，不复制整套流程。 + +| 工作影响 | 默认工作方式 | 足够的记录与验证 | +|---|---|---| +| 简单查询、排版/错字、无行为普通文档 | 直接答复或在自己已有工作区修改；无需独立计划和机器登记 | 简短说明、diff与受影响链接；变更进入共享分支仍按PR规则 | +| 单组件普通功能/修复 | 已授权后自主实施；复用自己专用功能分支/工作区，必要时才新建 | PR或原任务内说明目标、影响、相关测试与缺项；不强制另建plan/report/handoff | +| 公共接口、跨仓联动、授权/持久化语义 | 一个可审设计与change_set，明确owner和兼容顺序 | 相关单测/契约/集成/负例；真实用户路径变更追加浏览器或执行后端验收 | +| 共享环境、数据库迁移、发布或破坏性操作 | 使用已批准的操作范围及受信执行入口 | 必要互斥、固定对象、前后核验和恢复证据；未授权范围才追加批准 | + +普通Markdown也可能包含生效规范、运行prompt或发布决定；按真实语义归类，不能仅凭.md后缀降级。 +一行权限条件、迁移号或默认后端变更可能是高风险；大量纯格式调整也不必因此全系统验收。 + +拟替换/澄清的默认规则： +- 启动只读短入口与当前任务相关资料；同一会话未变更的规范不重复全文读取。跨模块/规则修订再补读；经验按症状或机制查找一次，有重要命中才记录，不为“无命中”建表。 +- 授权内的本地编辑、相关验证和可逆修订自主继续；不对每个步骤重复询问。用户要求方案待审就停在方案；push、公开发布、环境操作以已有明确授权为准，不因规范口号推定授权。 +- 沿用原任务和专用功能工作区。独立clone/worktree均可；新任务有脏改动/并行写者/隔离需要时再新建，不强制固定物理目录或“每次追问一分支”。主运行目录和受保护主干仍不作随意开发。 +- 小改动只保留一处记录，PR/Issue/原任务均可；长调研的独立结论才落设计/审计。状态投影自动生成或链接，不同步手填task、CURRENT、MATRIX、报告多份相同信息。 +- 文档目录/命名是可发现性约定，不作为安全门禁。优先既有分类；确有合适新目录时记录用途并更新入口，无需为命名/排版召开审批。保护唯一内容、可追溯链接和敏感资料归属。 +- Conventional Commits作为统一推荐，轻量lint给出具体纠正提示；不对贡献者个人WIP提交追溯整治。进入上游的标题清晰、变更可回退即可，不按层机械拆提交，不强迫重写共享历史。 +- 常规PR一次有效审核即可，不默认本地审核+多Agent+外部模型+逐章节批准全部叠加。高风险变化才追加合适专长；审查只追踪有后果的问题，已解决问题不循环重审。远端所需独立审批不得由同一作者换角色自批。 +- 自检/修订不逐次制造新审查文；变更、证据、剩余事项在同一处更新。安全/数据/外部副作用例外须明确授权；纯建议不需要登记“例外审批”才能偏离。 +- 常规修复留复现、机制、修复和回归摘要；严重/复发/跨模块问题补独立issue与经验。能从代码/测试直接看懂的常规改动不强制新建lesson，真实未解决问题仍须可追踪。 +- 收口只交代结果、验证和未完成项；未部署/未push等状态仅在相关或可能误解时说明，不每次重复完整状态矩阵。工作区清理和docs drift放到维护任务或明确触发时执行，不成为每次聊天结束的前置。 + +### Verification Scaling and Evidence Reuse + +开发阶段先跑直接相关测试；无新变化/失败/证据缺口时，不重复同一套已完成检查。 +合并阶段由稳定CI入口判定影响范围并报告本次需跑的组件、接口和集成检查。 +实际影响不清、公共依赖/构建配方变化、架构边界或鉴权/数据层变化时扩大范围；不能以“只是小改”绕过相关负例。 +全组件短测/构建用于相应组件准入和明确依赖变更；完整产品回归留给发布候选、跨模块风险和周期检查，不要求每次本地迭代执行。 + +浏览器验收覆盖受影响用户流程；真实模型/Agent验收覆盖其执行语义、运行prompt、适配器与任务链变化。 +纯文案/样式走相称的渲染/受影响页面检查，不机械调用真实模型；runtime prompt不当普通文案。 +原生能力对齐必须验证真正native执行，PI回退不能替代。前端、API与执行器证据各有边界，不相互冒充。 +测试框架/fixture可加速开发，但PG/权限/恢复及真实产品链路必须在其被声明通过的层级实际执行。 + +允许复用已有报告中确实仍适用的证据：相关源文件、依赖、配置、工具链/环境和测试输入不变，并记录原SHA与本次适用理由。 +元数据或无关文档变化不强迫重跑昂贵模型/浏览器测试；最终合并SHA、manifest、制品摘要和相关检查仍需绑定。 +有代码、环境或接口变化则重跑受影响检查；无法判定依赖范围时扩大验证，不悄悄沿用。 +CI影响过滤即使无需某套件，也输出明确not_applicable及理由；真正被要求的套件零用例、SKIP或基础设施失败不能成为PASS。 +把产品“未运行”与“未受影响”分开，不因整体CI绿色而宣称所有平台/后端/场景已经通过。 + +验证报告默认只含：改动/被测对象、实际命令或CI链接、结果、必要证据、缺项。 +需要他人复现的复杂故障/迁移/发布才展开完整报告；不强制保存全部原始日志和截图，也不为报告完整复制业务正文或秘密。 + +### Rule Strength and Change Control + +各条规范标成三类：硬边界（授权/敏感数据/真实副作用保护）、默认做法（有理由可调整）、建议（工具/目录/格式）。 +只对硬边界设置阻断门禁；推荐做法偏离时在已有PR/任务中用一句理由说明，足以复核则不再要求单独批准。 +软性目录、命名、阅读、文档篇幅、固定测试顺序或工具偏好不能升级成全局写阻断。 +新硬门禁必须说明实际风险、唯一执行位置、正负例和恢复路径；已有平台保护能承担的，不再增加本地审批数据库。 +不设置按日期自动失效的安全规则；在迁移/复发/成本明显过高时按证据复审，历史规则保留替代说明。 + +迁移时同步修改AGENTS/PROJECT、验证契约、经验闭环、任务/收口模板、客户端转发和CI，避免正文放宽而旧hook仍拒绝。 +补充四类日常演练到U2：文档微调、单组件bug、跨仓API变更、共享DB迁移；验证流程负担随风险升降。 +验收不只要求“危险操作被挡住”，也要求“已授权低风险工作无须重复批准、无关工具正常或故障都能完成”。 +这些新默认在审阅、对应工具/CI替代及生效登记后才执行，本轮不会直接改现行规则。 + +### KTD15. Remove Agentctl from the Coding Agent Workflow + +用户反馈Agent大量精力消耗在agentctl领取/提交/合并，说明前版“精简但仍由工具贯穿流程”的定位还不够。 +本次将目标明确为：编码Agent的正常开发闭环对agentctl零依赖。治理工具故障不得成为编码Agent的待办任务。 +没有测得全体Agent耗时占比，不给出虚构百分比；本会话已实际遇到登记续办、关闭状态不匹配以及无关全仓恢复锁，足以说明应改变流程责任。 + +正常开发只有：接受用户/Issue任务 → 普通Git功能分支或隔离clone/worktree → 编辑与相关测试 → 在已授权时提交PR。 +本地提交使用普通Git；PR由Gitea审核/CI/合并，不要求编码Agent创建候选工作区、准备集成收据或代管共享部署。 +任务状态以Issue/PR或原任务记录为准；不再要求同步一套agentctl任务、claim、运行许可和CURRENT行。 +已有工作区的owner/任务边界由调用方或启动器交接一次，不让执行Agent反复争抢同一个登记。 + +对编码Agent删除：task register/claim/lease/close/reopen、docs apply、integrate prepare/integrate、recover、常规cleanup报告与目录库ack等强制步骤。 +前版提出的task reopen不再作为编码流程的新必备功能：agentctl任务子系统在该流程退出，历史task/attempt仅只读保留；若部署执行器需要job ID，限定为部署操作自身。 +workspace创建/验证命令可以是独立薄脚本或直接Git/测试命令，不需要agentctl统一代理每个工具。 +Development-Manager可保留可选只读聚合视图与受信部署/发布执行器，但不再另造通用编码任务管理平台。 +Gitea token、环境凭证与运行权限按角色分离；普通开发不携带修改共享环境的权限，不能靠删除门禁去扩大Agent授权。 + +常见合并冲突返回PR作者在自己的分支解决；CI基础设施/队列/执行器故障由维护者处理，报告清楚失败类别。 +任务没有涉及治理工具时，Agent不得为解除阻塞顺带修复agentctl、改锁或接管另一任务；记录一个可复现故障即可，不进入循环重试。 +源代码自己的实际Bug仍需正常诊断修复；不是把所有测试失败都推给维护者。 + +优先实施两个小出口，而不是先造新的大型协调器： +- U2a 本地减负：基于U1中必要的工作区/权限基线，解除普通编辑/提交对本地任务库和守护进程的依赖；保留纯Git主干误提交保护、秘密防护和单工作区owner。无需等待模块拆仓/全部文档搬迁。 +- U2b 远端交接：Gitea保护、CI、受限PR合并先验证，再停用旧本地integrate入口；在此之前不开放保护分支直推。发布/部署继续走独立授权入口。 +后续多仓工具只实现版本清单/构建等实际缺口；不得为了实现新规范重新引入同等规模的task/claim/receipt审批层。 + +验收以完整日常任务为单位：从接任务到PR审核合并，编码Agent不调用agentctl，不维护第二套任务状态，不手工恢复治理锁。 +测试中停agentctl daemon、让旧任务库不可用，普通本地开发仍完成；Gitea上的无审批合并、陈旧候选和无权环境写仍被拒绝。 +观察治理命令调用数、基础设施人工介入次数与阻塞原因，不用代码行数或“工具更少”代替验证。 +正常任务出现一次必须人工修agentctl才能继续，即本单元未验收；真正共享部署结果未知的维护者恢复不计为编码流程成功所必需步骤。 +本节优先于KTD13中为一般编码保留可选agentctl生命周期的旧建议；所有替换仍待用户审阅后生效。 + +### KTD16. One Application Binary, Many Configured Instances + +用户补充要求：应用只发布一套单文件二进制，测试、生产及其他实例通过配置隔离；不再为每个环境编译不同程序，也不把环境名称写死为dev/test/main。 +每个版本只构建一次Ubuntu 26.04 linux/amd64的agent-system，固定摘要后可被多个实例共同使用。 +不同实例默认是独立进程、独立配置/业务DB/可写目录；同一业务部署的多副本HA另行验证，不能把两者混为一谈。 + +二进制内置Core、Web dist、Squad、Agent-Native、默认运行prompt/Markdown/xlsx、workflow manifests和迁移SQL。 +不要求源码checkout、Node前端构建、额外events可执行文件或外置assets目录才能运行应用。 +配置、用户数据、日志和备份仍是外部可写文件；校验/签名/SBOM属于发布元数据，不是第二个运行程序。 +Go embed只覆盖已纳入的资源；当前只嵌入Web和部分Markdown，SQL/prompt/xlsx仍需U10实际改造，不能把现有build-single-binary脚本当完整单文件验收。 + +同一个二进制拟提供serve、init、migrate、config check/explain等子命令；不再独立发布一个应用launcher或events binary。 +默认serve启动HTTP、产品模块和内置worker。以后确需拆API/worker进程，可用同一可执行文件的角色参数，但必须先验证任务/事件认领与缓存一致性。 +CLI名称/参数是拟议接口，当前代码还未实现；部署只需理解“一个程序+一个实例配置入口”，不暴露工程治理流程。 + +建议实例布局如下（非本轮创建）： +- 只读程序：/opt/agent-system/releases//agent-system。 +- 实例配置：/etc/agent-system//，包含.env、实例部署设置和受保护的凭证引用。 +- 实例数据：/var/lib/agent-system//，可分别配置workspace、documents、blobs、cache、logs。 +- systemd实例单元：agent-system@.service，配置明确的运行用户、配置根及不可变程序版本。 + +实例名只是标签；独立instance_id记录身份，生产安全策略由显式profile决定，不从Git分支/cwd/名字猜测。 +共享同一版本二进制不等于必须所有实例同时升级：测试可先指向新版本，生产继续使用旧的不可变版本。 +禁止全实例共用一个可变latest路径并在覆盖程序后隐式改变生产下次启动版本；升级/回退按实例执行。 +角色、配置和业务数据不编译进“test版/prod版”，版本晋升复用同一摘要制品。 + +### KTD17. Configuration Precedence Without Bootstrap Cycles + +采纳用户“后读覆盖先读”的方向，对普通部署配置采用： +内置默认 → 显式选定的.env（多文件按声明顺序）→ 已登记的进程环境变量 → 显式CLI参数 → 本实例持久化部署设置。 +系统设置界面负责编辑最后一层；启动参数只有实际传入才覆盖，flag默认值不能抹掉.env。 +进程环境这一层兼容systemd/秘密注入，放在.env之后、CLI之前；不扫描父目录/源码根的.env，也不自动混入其他环境overlay。 +路径相对固定config_root解析，与启动cwd无关；显式配置文件缺失、未知键或类型错误应说明字段和来源并拒绝启动，不能默默用dev默认值。 + +为让DB连接和数据目录也能由系统设置最终覆盖，将“实例部署设置”保存到config_root/instance-settings.json，先于业务DB连接读取。 +不把这些字段继续放到业务库system_settings中作为启动权威，否则“读DB连接配置需要先连同一个DB”构成循环。 +业务策略（例如文档职责、功能策略）仍可以在选定业务DB中持久化，由启动后的对应服务消费；它们不能反向更换数据库连接、实例身份或部署目录。 +UI可统一展现两组设置，但每个key只归一个store，没有JSON与DB双写同一个配置项的常态。 +迁移旧system_settings时按key ownership映射、校验和切换，保留来源与旧值恢复证据，不能复制一份后继续两边修改。 + +| 配置类别 | 例子 | 来源与生效 | +|---|---|---| +| 启动定位 | instance_id、config_root、settings读取模式、凭证解析根 | 默认/环境/显式CLI定位；不由它定位的设置文件自覆盖 | +| 实例部署 | 监听地址、APP_DB/KB连接、workspace/document/blob目录、后端地址 | .env→进程env→CLI→instance settings；连接/目录变更需受控重启或迁移 | +| 可热更新运行项 | 已实现动态消费的并发额度、选定模型等 | 相同部署配置管道，校验后以配置revision整体生效；未接线的项不标支持 | +| 产品业务策略 | 文档策略、项目设置、界面业务参数 | 选定业务DB中的授权服务；不承担启动定位 | + +除必要启动定位字段外，不因为“不方便”排除用户想在系统设置管理的部署参数。 +也不把后读覆盖解释为权限扩大：一个实例管理员的设置只能影响该实例，被拒绝的工具/凭证/环境权限不能由普通配置打开。 +由本机运维显式指定的settings-mode=ignore可以跳过最后一层做恢复；这是可见的启动控制项，不是配置文件悄悄抢优先级，更不能跳过产品鉴权。 + +每个配置项记录value（秘密脱敏）、source、desired_revision、applied_revision及生效类别。 +缺省、显式空串、false、0与删除override分别解析；删除override恢复继承，显式空值是否有效由该字段schema决定。 +最终合并后一次整体校验；DB URL/分字段冲突、目录重叠、端口占用、外部后端缺凭证等不能留到部分启动后才发现。 +各包消费统一的不可变ConfigSnapshot/受控更新对象，移除后续os.Getenv旁路覆盖和sysadmin自行用默认值覆盖已解析cfg的行为。 +连接串和密码不直接作为推荐CLI参数，优先secret-file/受保护凭证引用；日志、explain与审计只报告来源/状态，不打印值。 +提供config check/explain，解释最终值来自哪层、哪些变更待重启；该检查不创建DB、不写业务目录。 + +启动顺序：读取定位参数 → 合并文件/env/CLI/实例部署设置 → 校验及预检 → 取得本实例启动所有权 → 按显式模式连接/初始化存储 → 读取业务策略 → 构造服务/worker → 健康/诊断入口可先就绪，业务入口在readiness通过前拒绝处理。 +管理界面保存是desired状态；只有消费方确认成功才更新applied。 +热更新按字段组合原子应用，失败保持上次applied并显示错误；已有Agent任务固定其创建时配置，新任务再用新revision。 +需重启的连接/端口不得显示“已生效”；数据目录与DB切换走迁移准备、停新任务、排空、映射核对、切换、验收，重启不自动搬文件。 +修改业务DB等身份位置时使用已授权的部署配置流程，不能让页面一次保存导致服务自行跨环境重连。 + +### KTD18. Native Infrastructure and Explicit Ownership + +推荐“一个应用入口+操作系统原生服务”；不新增Agent-System启动器daemon、KB daemon或文档daemon。 +原因不是服务数量越少越好，而是当前KB/文档能力并没有独立进程必需边界，自己维护通用daemon会再次引入编排、租约、重启与恢复成本。 + +| 对象 | 推荐运行方式 | 责任与边界 | +|---|---|---| +| HTTP/Web/Squad/Native/应用worker | 同一应用二进制，默认单进程 | systemd或明确前台启动管理该实例；应用负责自身模块的启动/排空/停止 | +| PostgreSQL与pgvector | 本机或远端原生PostgreSQL服务；生产由系统服务/数据库运维管理 | 应用连接并校验，不因应用退出停止共享PG；pgvector是扩展，不另起daemon | +| 知识库 | 应用内KB模块+显式选择的KB数据库/语料存储 | embedding/reranker等是已配置的外部模型能力；空库不等于已有知识内容 | +| 文档库 | 应用内文档治理+业务PG元数据/内容账本+持久文件/对象存储 | document_root/blob_root可配置；不默认新引入另一种数据库或文档服务 | +| 外部PI或其他Agent | 显式外部服务/适配器，只有选择它才成为依赖 | 是兼容选项，不包装成已被Go内嵌；原生可替代程度由U9证明 | +| 开发专用本地PG | 可选：同一应用调用已安装的原生initdb/pg_ctl | 仅自有专用cluster，需单独验收所有权/失败恢复；非首期生产必选 | + +PostgreSQL官方区分initdb创建cluster与CREATE DATABASE创建其中的逻辑数据库；本方案同样区分安装软件、启动服务、创建database、迁移schema和导入KB数据。[initdb](https://www.postgresql.org/docs/current/app-initdb.html)、[CREATE DATABASE](https://www.postgresql.org/docs/current/sql-createdatabase.html) +Ubuntu服务器默认采用发行版/原生服务设施管理PG；应用不重复做一个数据库进程守护器。[PostgreSQL启动说明](https://www.postgresql.org/docs/current/server-start.html) + +正常serve默认storage_mode=existing，只连接明确目标并检查实例身份/schema；连接失败或表缺失不静默退回内存/开发库。 +init或显式授权的bootstrap/create-if-missing模式可以在已运行PG中创建该实例的逻辑库、角色/扩展/schema；按各操作权限最小化。 +CREATE DATABASE与迁移并非一个跨资源事务，初始化记录步骤，可幂等重试；无权建库、目标已存在但非本实例、扩展不可用都明确失败，不覆盖或删除既有库。 +接入已有未标记数据库时先做只读识别，并经明确adopt/迁移步骤建立实例归属，不自动把任意可连接的库当成自己的空库。 +已初始化实例的数据库后来丢失时，不能因create-if-missing自动新建空库掩盖事故；instance marker与持久化bootstrap状态必须区分首次创建与恢复。 +迁移默认check；显式migrate或已批准的自动迁移策略才写schema，按真实DB/schema串行；生产升级前有备份与兼容检查。 +建库需要的临时管理凭证只用于初始化，不留给普通应用连接池。 + +创建PG cluster只发生在可选managed-local模式，不等于安装PG/pgvector；程序缺失时报告缺项，不启动时在线下载执行。 +cluster的PGDATA、socket、port和身份必须匹配，不能只凭端口可连便认领；已有shared/external PG没有应用停止权。 +托管PG只允许一个owner；启动失败、应用异常退出/重启须核实子进程和实际PG身份，不删数据目录、不盲目杀进程。专用managed-local默认正常退出时停止本次明确拥有的cluster；应用异常退出后的遗留进程先核验身份与未完成操作，再受控认领或停止，不能只凭旧PID文件决定。应用只能停止本次明确拥有的子服务。 +生产推荐systemd分别管理应用实例和PG服务；应用短期断线应显式degraded/ready=false并有界重试，不能不断创建新DB或新cluster。 + +### Instance Isolation and Storage Layout + +默认每个独立实例有独立APP_DB/database role、config_root、workspace_root、document_root、blob_root、cache/log、HTTP端口、会话签名/加密密钥及外部Agent上下文。 +可以共用一台PG主机/cluster，但生产与测试默认不同database/role；不同账号没有彼此库的写权限。 +生产/测试优先使用不同OS服务账号、配置权限和运行目录；仅不同路径但共用同UID不构成恶意进程隔离，也不替代DB授权。 +需要更强故障/性能隔离时使用独立PG cluster/服务或主机，不由“不同数据库名”推导操作系统级隔离。 +UI/导出/启动摘要展示instance_id、版本、配置revision和非敏感目标标识，便于确认操作对象。 + +KB允许显式共享已批准的公共语料，只读连接是默认共享方式；测试私有材料、会话记忆、草稿及其索引不得自动写进生产KB。 +可用独立KB库，或经验证的namespace+ACL设计；首期选择独立库/专用角色，避免仅靠字符串前缀隔离。 +共享KB schema升级/语料写入由独立owner管理，不随任意测试实例启动执行。 +初始化KB schema、导入语料、生成embedding/index分成可观察步骤；ready需区分DB连接正常与知识索引可用。 + +document_root指用户文档/投影，asset指内置只读模板，blob_root指原始上传与CAS，workspace_root指执行临时/持久工作区；不能混用一个目录名称。 +现有账本可能已在PG保存正文，磁盘是投影；不能搬document_root后把某个文件目录自动改成新的事实源。 +启动将目录归一化为绝对路径，校验真实路径/symlink与owner marker；两个独立实例禁止相同或包含式重叠可写根，已声明只读共享目录除外。 +本机可用每实例/实际目录的轻量进程锁检测误重复启动，不依赖agentctl；跨主机共享可写文件树首期不支持，不能只靠本机marker宣称安全。 + +共享同一外部Runner若它有全局/admin/reload，会使实例配置互相覆盖。首期每实例独立Runner，或使用已验证的按请求/租户隔离服务；不得用一套全局热配置伪装隔离。 +同一浏览器host不同端口不提供cookie隔离，实例需独立cookie名称/签名或独立域名；API授权仍校验本实例身份。 +备份/恢复必须配对APP_DB与workspace/document/blob映射，保持内容hash/账本一致性；配置目录与加密密钥按权限单独保护。 +不能把数据库恢复到旧版本却继续使用另一时间点的文件树，或对所有实例共用一个自动覆盖的备份目录。 + +--- + +## Release Design + +### Platform Matrix + +近期唯一必交平台为 Ubuntu 26.04 x86_64（linux/amd64），使用当前主机原生构建与隔离验收。 +本轮实查 uname -m=x86_64，/etc/os-release 为 Ubuntu 26.04.1 LTS；这是开发主机事实，不等于制品已经验收。 +Apple Silicon/darwin-arm64 与 Ubuntu/linux-arm64 均暂缓，不列入本期 CI、交付出口、签名工作或工期；保留后续扩展接口，不为尚未支持的平台发布占位附件。 + +| 制品 | 编译目标 | 验收环境 | 交付内容 | +|---|---|---|---| +| Ubuntu 26.04 x86_64 | linux/amd64，CGO_ENABLED=0 | 干净的同架构 Ubuntu 26.04 环境 | 单文件agent-system；所需静态资产内置，配置/服务模板可按需导出 | + +当前构建不需要跨架构交叉编译；以后恢复目标平台范围时，再补相应编译器、原生验收、macOS 签名与公证。 +不由“Linux 静态二进制”推导兼容所有发行版；其他 Ubuntu 版本、CPU 基线、PG/Node/PI 依赖按各自证据声明。 + +### Package Contract + +本期公开/内部Release的运行制品是同一种Ubuntu 26.04 linux/amd64单文件应用agent-system。 +应用运行不再依赖外置Web dist、templates/configs源码目录、迁移SQL或第二个events可执行文件；这些运行资产必须嵌入程序。 +.env、instance-settings及业务数据是每实例外部状态，不随升级覆盖；单文件指应用交付，不表示数据库、模型服务和所有外部Agent都变成一个进程。 + +Release另附可选校验/签名/SBOM/许可与说明元数据，不作为启动必须下载的额外程序。 +配置示例、systemd模板和默认资源可由同一二进制输出到stdout；按需导出只写显式目录，不自动安装服务/覆盖现有配置。 +初始化不需要额外应用launcher；数据库软件由原生安装管理。选择external PI/backend时，其服务是明确的外部依赖；选择native时不得静默启动PI代替通过验收。 +PostgreSQL/pgvector仍为原生外部运行依赖，KB检索和文档治理代码集成于应用。KTD16–18定义单文件、多实例配置和进程归属。 + +验收在没有源码目录/外置assets的干净Ubuntu主机进行；只提供一个可执行文件和实例配置，验证实际UI、文档生成/上传、SQL迁移与检索。 +这不承诺无网络模型/embedding或无需数据库软件；离线运行、专用managed PG及额外外部Agent各自标能力范围。 +部署后每实例报告同一binary digest、自己的instance/config revision和存储身份；测试/生产差异全部由配置与数据边界表达。 + +### 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 原生分支保护、非作者审批、required checks、陈旧分支拒绝与受限合并身份；验证 API/Web/Git 各入口没有未登记旁路。 +出口：基线与唯一远端集成权威明确，完整治理替代清单可审；产品仓仍走原流程。U2 通过后才切换，不先卸载旧门禁。 +不在本阶段改变 test/main 部署。 + +### U2. Replace Heavy Local Gates with Scoped Governance + +覆盖 R4–R6/R9/R15/R16；预计在 U1 盘点后重估，依赖 U1，具体取舍见 KTD6/KTD13。 +优先在 Development-Manager 修改工具职责及主仓入口，不把两仓旧代码各自再扩展一套。 +先完成 Gitea 原生PR保护/候选CI、最终SHA/组件制品清单、环境执行权限；再停旧本地dev推进/文档收据入口。 +普通开发取消全局 with/SQLite 前置；同工作区单写者与共享资源执行器仍有适用保护。 +编码流程退出agentctl task/claim/lease子系统，Issue/PR或原任务作为单一任务状态来源；历史task/attempt只读保留，部署job另行限定范围。 +语义重叠/CodeGraph/缓存索引保持辅助，不进入源码写入硬门禁。 +改 candidate 导出为多仓精确导出，保护同一源码组合；不为简化而改用可变工作目录构建。 + +建议新增 Development-Manager scripts/tests/test_workspace_isolation.py、test_operation_outcomes.py、test_task_lifecycle.py、test_cleanup_allowlist.py。 +主仓新增 scripts/tests/test_component_export.py、test_gitea_merge_contract.py，并保留与新合同仍相符的测试；旧“任何写都需中央租约”的测试随规则显式退休，不为兼容旧实现保留旧缺陷。 +覆盖独立工作区同路径并行、缓存/daemon故障、候选冲突不阻塞无关任务、普通失败与unknown分类、同环境互斥、任务续办、受保护分支旁路与过期候选。 +源码路径：scripts/agentctl*.py、agent_worktree.py、.cursor/hooks/.cursor/rules、configs/agent-governance.json；规则路径：AGENTS/PROJECT、policy-registry、worktree-workflow、validation-contract、任务/收口模板。 +每条删除规则有替代责任与负例，不以脚本文件变少作为验收。 +优先交付KTD15的U2a本地减负和U2b远端交接；U2a只依赖U1必要的工作区/权限核对，不等待完整迁移盘点或拆仓。 +按KTD14同步精简验证契约、经验闭环、任务/收口模板与客户端入口；用文档微调、单组件bug、跨仓接口及共享迁移四类任务演练，确保低风险不会继续被旧模板/hook强制套完整流程。 + +切换时核清旧未完成操作/发布/部署真实状态，记录旧新权限清单与生效提交；不清空管理库，不同时启用旧本地和新Gitea两个主干写者。 +出口：独立开发不受全局锁牵连，未批准PR/陈旧候选/无权环境写仍失败关闭；最终制品可追溯；所有旧入口无绕过。 +此阶段失败只暂停切换，共享环境保持已验证版本，本地研究与编辑仍按当时有效规则进行。 + +### U3. Separate Guidelines and Development Documents + +覆盖 R3；预计 2–3 日，依赖 U2 的相关子能力。 +先拆通用 Guidelines 与静态 Documents，机器契约留代码仓；活动文档采用 PR/结构 CI，必要历史收据只读归档；不再要求专用 docs apply 写回。 +改对应入口链接、客户端规则、archtest 清单位置、文档索引和证据查找。 +声明版本采纳规则、owner 与旧路径只读状态。 + +新增文档链接/归属检查；继续验证 `internal/archtest`、`scripts/tests/test_agentctl*.py`。 +覆盖旧文档链接可追溯、新文档 PR 独立、缺文档权限仍能构建公开源码、能力状态不能因冲突被意外退回、子仓 gitlink 不能绕过子仓审批和证据校验。 +出口：每项内容有唯一写来源，无业务数据或运行模板误迁。 +先抽取少量静态文档试点；失败通过普通 PR 恢复路径与 gitlink，不删除新仓历史。 + +### U4. Extract Product Squad + +覆盖 R2/R6；预计 5–8 日，依赖 U2 和 U7a 的执行契约；接口冻结后可与 U3/U8 部分并行。 +现仓先完成依赖注入与材料解析去耦，保持行为；随后抽取至 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/R11/R12；预计 2–4 日，依赖 U3/U4/U7/U8 稳定。 +将其余产品代码作为一个 Core 仓提取；DB/产品运行配置与业务规则同仓，Web 与 Agent-Native 单独固定版本，主仓变为组合入口。 +调整 Docker COPY、构建入口、Go replace、测试根目录、CodeGraph 索引、运行服务入口与资产根。 +迁移源为批准的固定 SHA；源仓历史原样保留。 +开发数据与生产数据目录不随代码树挪动；路径切换必须显式映射并在隔离环境验收。 + +新增主仓 component manifest 校验与 smoke 测试，复用 Core 全部门禁。 +验收全新 recursive clone、源码 bundle 解压、无原源码路径构建启动、组合指针回退、当前运行版本识别。 +出口：外层仓不承载业务实现，组件固定组合可完整重建。 + +### U6. Build and Release Portable Packages + +覆盖R7/R8/R17–R19；新增单文件/多实例工作在U10估算后重排，分两个连续子阶段，沿用同一应用制品与发布入口。 +U6a 在U1基线/授权边界明确后，对当前固定单仓源码完成U10a及U10b的最小资产内嵌/实例配置/外部PG能力，再交付单文件内部版本，不等待Core提取。任何远端发布仍需要该实施阶段的明确授权。 +U6b 在 U5 后把同一配方切换为固定组件组合并重新验收；U6a 的结果是部署基线，不替代 U6b 的多仓版本验收。 +主仓实现固定组合构建与发布 metadata；组件实现必要的资产定位/版本输出。 +先构建固定 Web SHA 的 dist，校验摘要后在临时 Core 源码包内物化 embed 资源；Agent-Native/Squad 随相同组合编译。记录 frontend_sha、frontend_asset_digest、agent_native_sha、squad_sha、core_sha 与协议版本。 +新增私有内部发布仓、发布账号最小权限，拟定描述在本阶段或 U1 审批后一次性设置。 +完善 scripts/build-single-binary.sh、candidate-images-build.sh、release/promote 入口和目标平台部署模板。 + +新增包内容/摘要/权限检查与Ubuntu 26.04 amd64 原生部署 smoke；CI 具体路径依实例 workflow 配置决定。 +验收干净 Ubuntu 26.04 amd64，启动/health/ready/真实产品任务、升级、失败恢复、下载权限、重复发布冲突。 +出口：私有 RC 实际可安装；公开晋升经授权且附件摘要一致。 +业务数据库升级若存在，单列备份、前向兼容与恢复窗口；Git 回退不能宣称数据库已回退。 + +### U7. Extract Agent-Native and Normalize Execution Contracts + +覆盖 R12/R13；预计 5–9 日。 +U7a 依赖 U2：在现仓冻结助手/Squad 的执行行为、类型与副作用语义，定义小型 contract 和统一 backend resolver，保留原名 alias/原有默认，拆掉产品 config/workspace 反向依赖；先在 Agent-Native 建立只含公开 contract 的最小可独立编译模块，审核合入并固定可获取的 SHA，供 U4 使用。 +U4 接入此合同后，U7b 提取 agentx/runtime、公共工具/模型/执行会话与 PI transport 适配器，验证两个调用方再迁移通用 sidecar 资产。 +先设计合同，再发布最小 contract 模块（U7a），然后 U4 消费，最后 U7b 填入具体实现；U4 不等待整个原生内核提取完成，U7b 也不阻塞 U7a 的契约发布。 + +现路径：internal/agentx/**、internal/agent/{backend,pinative,piagent,fallback,resultv1,remote_result,deliverable,limiter}.go、internal/taskrun/backend.go、internal/app/app.go、coordinator/dialogue_llm.go、squad/service.go、config、CLI 与管理入口。 +原生核心移入 Agent-Native/runtime；产品 workspace 登记/文档落账不搬；HTTP transport 通用部分移 adapters/pi-runner，环境 sidecar 选择由 Core 注入。 + +测试复用 agentx/loop_test、session/jsonl_test、tools/tools_test、llm/sse_test、agent/pinative_test、fallback_test、resultv1_test、remote_result_test。 +新增 Native contract/conformance 与 Core integration 测试：旧别名/新名/未知名、不同能力 profile、native 与 PI fallback 实际身份、取消/unknown、跨用户会话隔离、有副作用故障不得重放。 +助手 reply.md 与 Squad output 的兼容回归，及 pi-agent 专属 summary/narrative/segment 功能不得因拆仓误启用。 +出口：Agent-Native 无 Core/Squad import 可独立构建；两个调用方使用同一合同；真实 Native 与 PI Runner 分别验证，fallback 不替代 native PASS。 +首期以现有两个真实 backend 验证可插拔边界；新增第三方 Agent 的真正支持必须另有具体 adapter 的真实验收，fake conformance 不能宣称已接入。 + +### U8. Extract the Web and Preserve Embedded Assets + +覆盖 R11；预计 3–5 日，依赖 U2，可与 U3/U7 并行，在 U5 前完成。 +迁出 web 源码、npm 锁文件、配置和前端/e2e 测试至 Agent-System-Web；Go embed 入口留应用并迁到 internal/webassets。 +改主仓 build-single-binary、Dockerfile 构建上下文、CI 路径、候选导出、版本清单及服务静态资源入口。 +新增 Core HTTP/SSE 合同基线与 Web contract fixtures；缺正式 schema 时先记录真实接口，再逐步类型生成，不假定全自动。 + +新增主仓 test_web_asset_assembly.py 与 Core web_asset_manifest_test.go；沿用 server/static_assets_test.go、web_assets_test.go、Web npm test/build 和相关 Playwright。 +场景：全新 checkout、dist 缺失、Web SHA/摘要不符、旧 cwd 目录污染、深链接、旧 chunk 404、预压缩协商、鉴权/续流/刷新。 +出口：Web 独立构建；一个产品版本能在无源码机器上提供正确 UI；npm 测试不替代固定 Core 组合的真实浏览器验收。 + +### U9. PI Core Parity Track + +覆盖 R14，依赖 U7 的公开执行契约；能力调研/用例盘点可提前，与拆仓分开验收，不阻塞先发布当前 PI 版本。 +U9a 基线：固定上游0.85.1、项目 wrapper/扩展/模型参数，建立 parity matrix，每项标记 available/partial/missing/not_required 及证据；确认应用实际依赖。 +U9b 能力补齐：先满足文件交付、工具/搜索、流与错误，再补长上下文、会话隔离、取消和恢复；保留安全边界，不照搬 --approve 或产品不需要的工具权限。 +U9c 对比验收：扩展现有6例，覆盖上述每一必需域的正常/异常/边界与真实浏览器任务；新增 semantic rubric、双后端同输入、实际后端身份及副作用检查。 +U9d 渐进启用：先隔离环境/内部账号允许清单，再按任务类别开放；每次变更通过配置 PR，保留 PI 回退路径与明确熔断条件，禁止验收通过后无审批改默认。 +U9e 替代收口：所有标记必需的能力和受支持任务满足出口，经过批准观察窗口，无未解释回退或严重缺陷后，才允许将原生设为目标场景默认；PI适配器继续保留供回退及第三方接入参考。 + +建议新增 Agent-Native conformance/parity 测试与固定语料；Core 保留真实助手/Squad/文档权限/SSE/restart 集成。 +复用 internal/agentx/abtest/{judge,live_test}.go、internal/agent/{pinative_test,fallback_test,resultv1_test}.go 和现有真实产品验收入口，修订旧 gate 不能混用新旧 PASS。 +准入最低条件：必需协议/权限/路径/取消故障用例全部通过；原生独立执行的必需产品场景全部通过；语义质量无重大缺项且不低于基线；严重缺陷为0。 +固定代表性集合做重复配对实验，报告样本量/成功数/超时/成本/延迟分布；P95≤1.3倍暂沿用已有起点，但不得由6次样本推断稳定统计结论。窗口与资源上限在 U9a 冻结，失败不得事后删样本。 +成本与资源预算独立设置，不能以低成功率基线或相对指标掩盖双方都失败。 +已运行任务绑定其执行版本与后端；回退只作用于新执行或确认可安全重试的任务，unknown 先恢复，不跨引擎强行迁移活动会话。 + +本路线属于新增产品能力工程，不能沿用“只拆仓保持行为”等价证明，也不包含在原 U1–U8 估算中。 +U9a 先做1–2日盘点后给补齐成本与明确分批计划；不在缺口未知时承诺全量复刻工期。 + +### U10. Single Binary and Instance Bootstrap + +覆盖R17–R19；与仓库拆分分开推进，基于U1最低存储/环境边界盘点即可在现仓实施；U6a必须消费本单元最小单文件/配置成果，U6b再验证多仓组合。 +U10a 统一资产与入口：迁移SQL、prompts、xlsx等内置fs.FS/只读字节源，去除源码cwd依赖；同一程序提供serve/init/migrate/config check/explain，不再分发必需events或launcher程序。 +U10b 实例配置与生产外部存储：统一ConfigSnapshot、env/CLI/实例设置、字段来源与生效类别；设置项按部署JSON/业务DB划定唯一owner；实现explicit existing/init、schema check及最小权限。 +U10c 生命周期与隔离：实例身份、根路径、DB/KB/cookie/Runner边界、启动失败回收、优雅退出、配置revision及systemd实例模板。 +managed-local PG属于本单元可选后续profile；外部PG生产模式通过不等于托管cluster已经验收。若首期不实现，CLI明确unsupported，不用现有localpg路径冒充完整支持。 + +涉及cmd/server、cmd/events、internal/config、localpg、sysadmin、app、bizdev、db、kb、workspace、storage、docrevision、template/quote、Web设置页及构建配方。 +现有config.Load、sysadmin resolver和直接os.Getenv入口统一接线；区分保存与实际应用；旧system_settings部署键一次迁移后冻结旧写入口。 +存量路径转换与配置升级只在独立环境演练；创建/移动真实用户目录和更换数据库需要该实施阶段授权。 + +建议新增Core internal/config/precedence_test.go、instance_settings_test.go、internal/bootstrap/instance_isolation_test.go、storage_init_test.go、internal/assets/embed_contract_test.go，及settings生效API/UI测试。 +原有config/compose测试迁为显式兼容profile，不把Compose和固定dev/test/main当新部署前提。 +验收同一文件摘要运行测试/生产两个实例、显式值覆盖/空值/false/0、任意cwd、无外置assets、错DB/路径重叠/旧目录、缺库/错owner、初始化中断重试、修改目录后未迁移拒启、热更新失败不改applied、重启后真正消费设置。 +执行真实文档生成/上传/检索、刷新重启和一次配置切换；证明两实例不能看见或修改彼此私有数据。 +应用退出不停止external PG/另一个实例；可选managed模式另测own-cluster停止、孤儿恢复和端口冒认负例。 +不在本轮构建程序或启动这些服务；默认后端改为Native仍受U9门禁，外部PI作为显式配置依赖可以先保留。 + +此前 U1–U8 为24–41人日的多平台粗估；本次平台范围收敛后在 U1/U2 重新估算，U6a/U8 可并行。新增 U9 能力补齐单独估算，不把它藏进拆仓预算。 +建议依赖顺序为U1→U2→U7a→U4/U7b，U3/U8可穿插；U10可在当前单仓按U1最低基线先做，U6a依赖U10的单文件/外部PG配置出口。U3/U4/U7/U8通过后做U5，再做U6b；无需等待U9全面替代PI。 +可以在独立阶段出口暂停；暂停时保留兼容的旧组合，不自动开启新后端。 + +--- + +## 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 并发合入 | 两个 PR 候选竞争同一 base，或非授权身份尝试合并 | 原生保护+按仓/分支串行，只采用新基线的有效候选；合入后tree与最终SHA可验证 | +| V7 Squad 语义 | 文档生成/复杂任务 + 失败/权限/恢复变体 | 事件、正式文档、持久状态符合原产品合同 | +| V8 文档治理 | CURRENT/MATRIX 迁移为摘要/PR治理，父仓更新文档gitlink | 单一来源、子仓审批和证据可追溯；不依赖本地docs收据，不丢历史状态 | +| V9 完整包 | 从任意 cwd 在无源码的干净机器启动 | Web/模板/xlsx/SQL 可用；缺依赖明确失败；不误连 dev DB | +| V10 平台 | Ubuntu 26.04 x86_64 干净环境 | 最终 linux/amd64 包完成原生验收；本期不要求 Apple Silicon 或 ARM64 | +| V11 发布恢复 | 上传一半中断、重复同版本、不同摘要同版本 | 幂等补齐/拒绝冲突；公开前附件完备；旧版不被覆盖 | +| V12 回退 | 回退主仓 gitlinks，已有旧任务/数据 | 代码版本可回退；schema/任务格式不兼容时明确停止和恢复路径 | +| V13 双调用方 | 助手对话与 Squad 分别调用 agent-native、pi-agent；记录实际后端 | 契约一致、权限各自有效；fallback 不伪称 native 成功；不改变默认后端 | +| V14 新 Agent 接入 | 新 adapter 运行契约套件、原生平台 smoke 与沙盒端到端 | 不改 Squad 业务流程即可接入；不支持取消/文件/工具权限时明确拒绝对应任务 | +| V15 Web 构建发布 | 固定前端构建嵌入 Core；放置旧 cwd/web/dist，测试缺 chunk | 只服务声明制品；旧目录不能覆盖；chunk 缺失返回 404 而非 HTML；API/SSE 与鉴权兼容 | +| V16 兼容与隔离 | pi-native 旧名、旧 AGENTX 配置、旧 transcript；并发会话/已副作用失败 | 别名解析一致；不隐式移动数据；会话不串用；未知执行结果不自动换后端重放 | +| V17 核心对齐 | 固定 PI/Runner/模型基线，原生禁用 fallback，配对语料与异常用例 | 必需协议/安全/产品场景通过，质量达标；旧6例仅作 smoke；缺项/SKIP 不算通过 | +| V18 渐进替代 | 按任务类型启用，注入原生失败与unknown，回退新请求 | 新执行可回退PI，活动会话不强迁；副作用不重放；可核验实际后端身份 | +| V19 工作区互不阻塞 | A候选冲突/恢复，B独立worktree编辑同路径文档并本地提交 | B可完成；故障只隔离实际共享或A自己的资源 | +| V20 工具非单点 | 停本地daemon/损坏可重建缓存；尝试本地开发和远端合并 | 开发继续，远端仍遵守PR/CI；执行器恢复日志损坏仅阻塞对应高风险动作 | +| V21 故障分类 | 预检拒绝、确定失败、孤儿进程、外部结果未知 | 前两类不需手工recover；后两类可定位、有限隔离，不能TTL盲目接管 | +| V22 续办与清理 | 原task_id从done重开或blocked；存在缓存与唯一ignored证据 | 状态/attempt可追溯；缓存可按清单处理，唯一成果保留；禁止force绕过 | +| V23 治理切换 | 冻结旧入口，验证旧token/hook/本地integrate不能推进权威远端 | 仅新权威有效，历史可查；回退也必须保持一个写权威 | +| V24 适度流程 | 文档微调、单组件bug、跨仓接口与DB迁移四类任务 | 阅读/记录/验证与影响相称；低风险不套全系统流程，高风险必要负例不被取消 | +| V25 证据与软规则 | 无关文档变更、相关依赖变更、命名偏好差异、必需测试零用例 | 前者可说明复用证据，依赖变化重验；偏好不阻塞写入，零用例不计PASS | +| V26 日常流程零依赖 | 完整修复→本地测试/提交→PR审核合并；agentctl守护进程和旧任务库不可用 | 编码Agent不调用agentctl、不填第二套状态、不恢复治理锁；远端/环境权限保护仍有效 | +| V27 单文件 | 无源码/外置assets目录，只有一个应用文件与实例配置启动 | UI/SQL/prompt/xlsx及内置worker可用，不需events/launcher第二程序 | +| V28 配置覆盖 | 同key文件/env/CLI/系统设置冲突、false/0/空值、缺文件、任意cwd | 明确最后来源；bootstrap不循环；无隐式dev回退；config check无业务副作用 | +| V29 多实例 | 同一binary启动test/prod/custom；错库、重叠根、同Runner配置、同host cookie | 默认互相隔离；错误目标拒绝；共享仅限声明并验证的能力；不宣称HA副本支持 | +| V30 存储初始化 | existing缺库、显式首次create、中途失败、非本实例库、已初始化后丢库 | 不静默建/覆盖/删库或重新初始化；可审计幂等恢复；管理凭证不进运行池 | +| V31 进程归属 | 停应用/启动失败/PG短断线；可选managed端口冒认与孤儿 | 外部PG/其他实例不被停；只有确认owned cluster可管理；不能连接即认领 | +| V32 设置生效 | 保存DB/目录/模型设置、更新失败、重启/迁移 | desired/applied区分；任务不混用新旧配置；重启真消费，未迁移不伪称完成 | +| V33 数据恢复 | 独立DB与文档/blob/workspace备份恢复、KB导入/索引缺失 | 账本/内容hash一致；连接成功不等于KB可用；不串用生产私有材料 | +| V34 独立晋升 | 两实例共用v1，test选择v2而prod重启 | prod仍用固定v1；相同版本摘要相同；应用配置与数据不被程序替换覆盖 | + +现有可复用命令为 `./scripts/arch-check.sh --mode block`、`go vet ./...`、`go test -short ./...`、web 的 `npm test`/`npm run build`，迁移后在对应组件目录运行。 +实施阶段在本方案获审后按KTD14修订的验证契约选择PG、真实后端与浏览器验收；生效前遵循当前契约。使用独立环境，共享环境须独占。 +本轮只做文档差异、链接和事实一致性检查，没有执行上述实施验收，不记录为 PASS。 + +--- + +## Repository Descriptions + +以下为审批后的拟写描述；本轮未调用更新 API。 + +| 仓库 | 拟用描述 | +|---|---| +| Agent-System | Agent-System 产品集成主仓：管理组件版本、开发入口、组合验证与发布流程。 | +| Agent-System-Core | Agent-System 核心服务：API、助手产品逻辑、身份权限、工作流、文档治理与数据持久化。 | +| Agent-System-Web | Agent-System Web 前端：对话、项目与文档工作台、管理界面及交互验收。 | +| Agent-Native | 可复用的 Agent 执行基础：自研运行内核、模型与工具接入、外部 Agent 适配，为助手与智能体小队提供统一执行能力。 | +| Agent-System-Squad | Agent-System 产品智能体小队：文档生成、复杂任务编排、执行协作与质量检查。 | +| Agent-System-Development-Documents | Agent-System 项目开发文档：需求、架构、设计决策、计划、审计与验收记录。 | +| Development-Guidelines | 与具体项目无关的开发规范、协作流程、审查标准及工程实践模板。 | +| Development-Manager | 多项目开发辅助与受信执行工具：工作区、验证、Gitea协作、部署发布及故障恢复。 | +| Agent-System-Releases | Agent-System 公开测试版与稳定版发布：Ubuntu 26.04 x86_64 单文件应用、校验及多实例部署说明。 | +| Agent-System-Releases-Internal | Agent-System 私有内部测试与候选版本：受限单文件应用、版本清单及多实例验收说明。 | + +--- + +## Risks and Decisions + +需要用户审阅的核心建议：同意分阶段拆仓、复用 Development-Manager、最终新增 Core/Web/Agent-Native 承接对应能力，并采用 Gitea 原生准入及精简后的开发治理。 +已确认的内部私有/公开隔离按本方案执行；不再作为未决问题。 + +实施前仍需验证、但本轮无法以只读研究证明的条件： + +- Gitea 原生审批/检查/过期拒绝、受限串行合并及合入后tree核验的真实行为；以及旧本地门禁退役后的权限负例。 +- Ubuntu 26.04 x86_64 的隔离 runner、干净部署测试环境与明确的运行依赖版本。 +- 全量历史导出是否包含不应公开的内容；未扫描历史不能认为空仓导入自然安全。 +- Core/Squad 公开模块命名空间，以及远期独立 go get 分发是否需要稳定域名。 +- 切换时仍在运行的任务/操作、Workspace 格式兼容与实际部署资产布局。 + +这些是对应阶段的阻断出口，不妨碍先审阅整体架构。 +出现无法恢复的未知副作用、缺少授权环境、活动任务无法排空、子仓 SHA 不可获取时停止相应阶段；保留当前已验证组合。 +保持产品代码回退、部署制品回退、DB/用户文件恢复三条独立路径。 + +--- + +## Definition of Done + +本轮研究完成条件：现状证据、推荐与替代方案、仓库职责、协作/版本语义、迁移/回退、平台发布、可见性隔离、描述草稿与验收矩阵齐备，并交付用户审阅；不以实施状态衡量研究完成。 + +未来拆仓与Ubuntu发布完成条件：U1–U8及U10必选出口、V1–V16与V19–V34均有证据；主仓是可重建组合；所有组件 PR 与 gitlinks 可追溯；真实部署包在承诺平台完成原生产品验收；内部制品未被未授权访问；远端与运行状态分别记录。 +U9 是独立的原生核心替代交付线：V17/V18 与全部必需能力验收通过后才具备启用条件；U1–U8 完成不等于 PI 已被替代。 +未获得公开发布授权时，内部验收通过不自动发布公开版本。 + +--- + +## Sources + +本地证据与方法见[调研记录](../audit/2026-09-28-multi-repo-evidence.md)。 +Git/Gitea/Go 官方链接随影响决策的段落引用；本机 Swagger 用于验证实例字段，但字段存在不证明流程已演练。 +本方案没有修改现行规范的效力。