From 787bcc53d496f8014f136e31f35206ea103ce77b Mon Sep 17 00:00:00 2001 From: weichen Date: Tue, 29 Sep 2026 00:16:05 +0000 Subject: [PATCH] =?UTF-8?q?docs(multi-repo):=20=E8=90=BD=E7=9B=98=E4=BF=AE?= =?UTF-8?q?=E8=AE=A22-7=E7=9A=84=E5=89=8D=E7=AB=AF=E6=8B=86=E4=BB=93/Agent?= =?UTF-8?q?-Native/=E5=8D=95=E6=96=87=E4=BB=B6=E5=BA=94=E7=94=A8=E6=96=B9?= =?UTF-8?q?=E6=A1=88?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .doc/audit/2026-09-28-multi-repo-evidence.md | 191 +++++ .../2026-09-28-multi-repo-design.md | 58 +- ...2026-09-28-multi-repo-architecture-plan.md | 761 +++++++++++++++--- 3 files changed, 910 insertions(+), 100 deletions(-) diff --git a/.doc/audit/2026-09-28-multi-repo-evidence.md b/.doc/audit/2026-09-28-multi-repo-evidence.md index 67114ce4..db85f209 100644 --- a/.doc/audit/2026-09-28-multi-repo-evidence.md +++ b/.doc/audit/2026-09-28-multi-repo-evidence.md @@ -151,3 +151,194 @@ CodeGraph 在开始与收口运行 sync -q 成功；其近似索引仅辅助定 - [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 index 72f56707..013fd098 100644 --- a/.doc/ops/short-term/2026-09-28-multi-repo-design.md +++ b/.doc/ops/short-term/2026-09-28-multi-repo-design.md @@ -56,6 +56,7 @@ remote_sync: not_requested 用户补充：Squad 为产品文档生成与复杂任务小队，开发治理工具可单列建议；内部测试版需要私有隔离，公开版公开。两项已写入方案。 交付： + - [待审方案](../../remediation/2026-09-28-multi-repo-architecture-plan.md) - [调研证据与审查记录](../../audit/2026-09-28-multi-repo-evidence.md) @@ -64,7 +65,62 @@ remote_sync: not_requested ## 收口 研究任务 done；方案 review_state=pending/policy_state=proposed。用户审阅仍是后续实施入口。 -本地文档将以独立 Conventional Commit 保存；不合入 dev、不 push、不部署、不设置仓库描述/权限。 +本地文档以独立 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 index d50a8079..083ff07d 100644 --- a/.doc/remediation/2026-09-28-multi-repo-architecture-plan.md +++ b/.doc/remediation/2026-09-28-multi-repo-architecture-plan.md @@ -1,6 +1,7 @@ --- title: "Agent-System 多仓库、PR 协作与发布架构方案" date: 2026-09-28 +revision: 7 type: refactor task_id: multi-repo-design-2026-09-28 policy_state: proposed @@ -23,6 +24,10 @@ execution: code 当前 AGENTS/PROJECT/worktree 规范仍生效。 用户已补充确认：Squad 指产品中生成文档与处理复杂任务的小队；开发协作治理工具可以另行考虑；内部测试制品必须私有，公开版公开。 +修订 3：用户确认近期仅交付当前 Ubuntu 26.04 x86_64 平台；确认自研 Agent-Native 对齐 PI 核心能力并逐步替代。本轮仍只修订方案。 +修订 4：按用户要求重新评估锁/agentctl/文档与集成规范，以原生 Gitea 门禁和实际共享资源保护替换跨工作区的全局开发门禁；所有新规则待审。 +本次补充：用户希望前端独立管理，将 pi-native 演进为可复用的 Agent-Native，既支持自研执行内核，也能接入其他 Agent；本修订替换上一版“不拆 Frontend”的建议。 +修订 7：用户要求一个单文件应用按启动配置运行多个隔离实例，新增配置优先级/生效模型和数据库、知识库、文档存储的原生运行与启动职责。 以下推荐技术选择均为待审建议，不把本次答复理解为实施授权。 --- @@ -48,16 +53,25 @@ execution: code | R4 | 支持 fork + 功能分支 + PR 审核；开发工作区相互隔离 | | R5 | 上游更新可感知，合并只能基于当前上游与已验证的精确组件组合 | | R6 | 支持关联多仓 PR，明确非原子合并、兼容过渡与失败恢复 | -| R7 | 在 Gitea 发布 macOS Apple Silicon、Ubuntu Server 二进制部署包 | +| 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 中央集成执行者：维护队列、重建候选、执行保护分支更新；不代替 A2 的审核。 +A3 受控合并执行者：按仓/分支串行处理候选，经Gitea原生PR入口合并；不直推或代替 A2 审核。 A4 发布维护者：批准已验证组合进入内部或公开发布；持独立发布凭证。 A5 测试者/部署者：按权限下载对应平台包，不依赖开发仓现场。 @@ -85,7 +99,7 @@ Gitea 1.27.3 的 dev 为 `fabd85a65e15f3417431ba6f004a8bcdf9cb83cb`，图遍历 已读到六个 Gitea 仓库；五个用户指定仓库均可复用，另外已有 Development-Manager。 主仓与 Development-Manager 的 branch_protections 都为空；不能把本地 hook 当作 Gitea PR 门禁。 两仓 repository-level runner 列表为空，不能据此断言没有实例级或组织级 runner，实施前须核实 runner 标签和实际执行。 -尚未执行跨平台编译、原生启动、PR 合并或发布演练。 +尚未执行目标平台编译、原生启动、PR 合并或发布演练。 Squad 依赖七个主仓内部包，约 29 个非测试文件直接导入它。 现有单二进制脚本可嵌入 Web；PostgreSQL、pgvector、PI Runner、部分运行资产仍是部署依赖。 @@ -104,7 +118,9 @@ Squad 依赖七个主仓内部包，约 29 个非测试文件直接导入它。 | 仓库 | 目标职责 | 初期处理 | |---|---|---| | Agent-System | 产品总入口、submodule gitlinks、组合构建/测试、发布配方、项目策略入口 | 保留现有远端、dev/test/main 与历史 | -| Agent-System-Core（拟新建） | Go 应用装配、HTTP API、IAM、工作流与文档治理、DB/迁移、Web UI、产品运行配置与 PI Runner 适配 | 在 Squad/工具试点通过后整体提取；Web 和迁移继续同仓 | +| 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 | 无产品依赖的开发规范、模板、证据分层和通用协作原则 | 可复用空仓；按版本显式采纳 | @@ -115,9 +131,9 @@ Squad 依赖七个主仓内部包，约 29 个非测试文件直接导入它。 Core 是让外层最终成为纯组合仓的必要承接点，但不应首刀移动所有业务代码。 如审阅时希望控制首期仓库数量，可以让业务代码暂留主仓；达到真正外层结构后再建立 Core，不能声称过渡态已完成最终结构。 -暂不单拆 Frontend、数据库迁移、公共 Types/Contracts、每个 agent 或每种 workflow。 -这些边界当前共同变化频繁；增加仓库会放大联动 PR 数量。 -PI Runner 已是部署依赖，但初期留在 Core 的 `deploy/pi-agent/`；仅当独立生命周期/复用需求成立，再评估 Agent-System-Runner。 +前端改为独立 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 @@ -134,6 +150,8 @@ Agent-System/ .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 @@ -142,12 +160,19 @@ Agent-System/ ```mermaid flowchart TB - Root["Agent-System：固定产品组合"] --> Core["Core：应用、Web、授权与数据"] + 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：开发治理工具"] - Core -->|"公开接口 / 主仓适配器"| Squad + 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"] @@ -156,12 +181,13 @@ flowchart TB ### 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 + Backend/Result/Failure 接口 | 环境配置、PI endpoint、凭证、具体执行适配 | +| config/backend factory | Options + Agent-Native 执行契约 | 环境授权、凭证注入、后端选择；通用执行适配在 Agent-Native | | stream/SSE | 有类型的进度、步骤和完成事件 | SSE 映射、task_runs 持久事件、权限与重放 | | workflowdef/task keys | 版本化任务/流程输入 DTO、profile | 工作流审批、冻结快照、项目状态 | | template/instructions | 明确的资产 provider | 与业务绑定的模板、提示词及版本选择 | @@ -189,7 +215,7 @@ IDE 中 `data/dev/workspaces/.../output.md`、`workspace.json` 是业务数据 首期不把整个 `.doc` 原位替换成 submodule。 先建立 `development/documents`，迁移静态设计资料和归档；CURRENT/MATRIX/活动任务暂留原管理路径。 -完成文档收据、证据 URI 与 hook 的多仓适配后，再迁移活动文档。 +完成文档 PR 权限、结构/证据 CI 与多仓证据 URI 适配后，再迁移活动文档；旧 docs apply/收据在新链路验证后退休，不继续扩展成多仓审批数据库。 新证据引用使用仓库标识 + 完整 commit + 路径 + 内容摘要；未提交草稿不能当作生效证据。 对每个迁移文档只设一个可编辑来源。 @@ -212,10 +238,11 @@ components.yaml 区分 build-required 与 development-only；公开源码构建 主仓 PR 不接受“本地可用、远端取不到”的 gitlink。 检验父仓、每个子仓的脏状态，拒绝把未提交文件混入制品。 -首期 Go 联调采用明确的相邻源码 replace：Core 指向 `../squad`；整个组合仍由 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 自身必须可独立构建测试；Core 依赖版本的精确物化由主仓候选流程提供。 +Squad 自身可在物化固定版本 Agent-Native 契约依赖后独立构建测试；Core/Squad 依赖版本的精确物化由主仓候选流程提供。 Gitea 当前访问 URL 带自定义端口，Go module path 不能直接照抄带端口 URL。 首期以固定源码组合与本地 replace 消除直接 go get 的路由依赖；模块名使用经批准的不含端口稳定命名空间。 @@ -238,7 +265,7 @@ A 合入后上游为 R1；B 同步到 R1 时采用 R1 的组件组合，另保 ### KTD5. Freshness at Safe Boundaries 首期必交：在开始工作、开始关键验证、请求审核、进入合并队列四个检查点强制检查上游，并记录人工触发还是工具执行。 -完成首期迁移后，可增加常驻通知/轮询，目标为上游合并后 5 分钟内标记相关活跃任务落后；这个时效是后续自动化阶段的验收条件，不属于 U1–U6 的首期承诺。漏事件由轮询补偿。 +完成首期迁移后，可增加常驻通知/轮询，目标为上游合并后 5 分钟内标记相关活跃任务落后；这个时效是后续自动化阶段的验收条件，不属于 U1–U9 的当前交付承诺。漏事件由轮询补偿。 自动后台只允许 fetch 和状态提示。 同步器遇到脏文件、正在测试、未提交子仓或冲突时停止工作区改动，记录 sync_required；不 stash/reset/自动提交。 @@ -251,36 +278,28 @@ A 合入后上游为 R1；B 同步到 R1 时采用 R1 的组件组合，另保 “同步及时”与“测试可复现”同时成立的标准是：可见地落后、在明确检查点更新、被测组合不在测试中途变化。 不承诺所有工作区每秒都等于上游。 -### KTD6. Reviewed PRs and One Integration Authority +### KTD6. Gitea Owns PR Integration -主仓暂保留 dev → test → main 的现行生命周期，不在拆仓时顺带重新定义环境。 -子仓默认 main + 功能分支 + 不可变组件 tags；子仓 main 只是已审核组件，不等于产品已部署。 -Releases 仓 main 只存发布元数据；RC/stable 由 tag 和可见性决定。 +本次治理复审替换前版“自建签名收据网关 + 机器人直推 + manually-merged 回写”的默认路线。 +采用 Gitea 原生 PR 合并、分支保护、非作者审核及必需 CI 作为远端准入权威，减少本地与远端两套审批/引用推进机制。 +主仓仍保留dev→test→main的源码晋升约定；运行实例由不可变制品与配置定义，名称不绑定分支。子仓main表示已审核组件，不代表部署；公开发布/环境晋升仍独立授权。 -推荐 Gitea 分支保护：禁止开发者直推受保护分支、禁止强推、要求非作者审批、陈旧审批失效、拒绝请求修改状态、要求明确命名的 CI checks。 -权限存在不等于某项操作已获授权；机器人也不获得自动部署 test/main 的权限。 -私有子仓的源码访问另配权限，不用公开 fork CI 中的秘密令牌补洞。 +禁止开发者和普通 CI token 直推受保护分支、禁止强推；明确 required checks，内容变化撤销旧审批，过期分支阻止合并。 +保护规则适用于 API/Web/SSH/HTTP 等入口；具体实例行为先在演练仓验收。[Gitea 保护分支](https://docs.gitea.com/usage/access-control/protected-branches/) +不再把开发机 SQLite 或本地 hook 当作远端授权边界；Gitea 不可用时可以继续离线编辑/提交，合并、发布和部署等待恢复。 -现有“本地 agentctl 精确候选后推进 dev”与“Gitea 服务器自行生成合并提交”必须选定一个权威，不能并行各自合入。 -推荐延续精确候选语义，增加中央 PR 集成控制器： +合并前测试绑定目标 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。 -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 可以生成不同元数据的合并提交，因此移除“本地预生成 merge SHA 必须原样成为远端 SHA”的惯例。 +保留更直接的证明：合入后的确切 commit/tree/gitlinks 与被测候选内容一致；正式构建、签名、发布和部署全部绑定合入后的真实 SHA 和制品摘要。 +使用保留内容的 merge 模式；检测到 tree 不符、意外父链或新 base 变化时，不发布、不部署，进入重新验证或普通 revert PR。 +若 runner/native protection 不能可靠阻止过期合并，首期人工受控串行审核合并并显式重验；不在能力缺失时放开多写者，也不为此默认建立全新分布式控制平台。 -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 实现。 +对共享运行环境、迁移与发布仍保留执行互斥，但独立 build/test、开发分支和文档不需要占用它。 +切换前先排空/核清旧 agentctl 操作，处理本地未同步提交，再正式停用旧本地 dev 推进入口；未切换前现行规则继续有效。 ### KTD7. Cross-Repository Changes Are Staged @@ -306,7 +325,456 @@ Gitea PR Actions 默认 ref 指向 PR head，不是 GitHub 式合并预览。 先适配 Git common-dir/gitdir/worktree/submodule 身份，显式识别“工具源码仓”与“被管理目标仓”。 工具作为 submodule 消费，不把其自身 .locks 当作产品协调状态。 -本地状态归属明确的 repo_id + host/workspace；共享权威只存在中央执行入口。 +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/账本一致性；配置目录与加密密钥按权限单独保护。 +不能把数据库恢复到旧版本却继续使用另一时间点的文件树，或对所有实例共用一个自动覆盖的备份目录。 --- @@ -314,37 +782,31 @@ Gitea PR Actions 默认 ref 指向 PR head，不是 GitHub 式合并预览。 ### 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、交付出口、签名工作或工期；保留后续扩展接口，不为尚未支持的平台发布占位附件。 + | 制品 | 编译目标 | 验收环境 | 交付内容 | |---|---|---|---| -| 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 26.04 x86_64 | linux/amd64，CGO_ENABLED=0 | 干净的同架构 Ubuntu 26.04 环境 | 单文件agent-system；所需静态资产内置，配置/服务模板可按需导出 | -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 的摘要拿来证明公开附件一致。 +当前构建不需要跨架构交叉编译；以后恢复目标平台范围时，再补相应编译器、原生验收、macOS 签名与公证。 +不由“Linux 静态二进制”推导兼容所有发行版；其他 Ubuntu 版本、CPU 基线、PG/Node/PI 依赖按各自证据声明。 ### Package Contract -每个平台交付一个版本化 tar.gz/zip，包含： +本期公开/内部Release的运行制品是同一种Ubuntu 26.04 linux/amd64单文件应用agent-system。 +应用运行不再依赖外置Web dist、templates/configs源码目录、迁移SQL或第二个events可执行文件；这些运行资产必须嵌入程序。 +.env、instance-settings及业务数据是每实例外部状态，不随升级覆盖；单文件指应用交付，不表示数据库、模型服务和所有外部Agent都变成一个进程。 -- `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；首期“源码之外可部署”不等于“所有依赖离线打包”。 +Release另附可选校验/签名/SBOM/许可与说明元数据，不作为启动必须下载的额外程序。 +配置示例、systemd模板和默认资源可由同一二进制输出到stdout；按需导出只写显式目录，不自动安装服务/覆盖现有配置。 +初始化不需要额外应用launcher；数据库软件由原生安装管理。选择external PI/backend时，其服务是明确的外部依赖；选择native时不得静默启动PI代替通过验收。 +PostgreSQL/pgvector仍为原生外部运行依赖，KB检索和文档治理代码集成于应用。KTD16–18定义单文件、多实例配置和进程归属。 -PostgreSQL/pgvector 继续是独立运行依赖；`localpg` 会查找已安装的 pg_ctl，不是数据库被静态编进服务。 -默认服务器部署使用显式 DSN 和独立持久数据目录；受支持的 managed 本地模式另测。 -PI Runner 可以用固定镜像或受支持 Node 运行方式，模型/工具密钥由部署环境注入。 - -禁止安装包依赖原源码 checkout 的相对 cwd。 -资产根、配置根、数据根分别指定；从任意目录启动均能定位正确资产。 -从发布包在干净主机启动、完成真实任务，才算“可以部署”，仅 go build 成功不够。 +验收在没有源码目录/外置assets的干净Ubuntu主机进行；只提供一个可执行文件和实例配置，验证实际UI、文档生成/上传、SQL迁移与检索。 +这不承诺无网络模型/embedding或无需数据库软件；离线运行、专用managed PG及额外外部Agent各自标能力范围。 +部署后每实例报告同一binary digest、自己的instance/config revision和存储身份；测试/生产差异全部由配置与数据边界表达。 ### Build and Publication @@ -352,7 +814,7 @@ PI Runner 可以用固定镜像或受支持 Node 运行方式，模型/工具密 从固定 root SHA 递归导出全部参与构建的组件 SHA，生成源码物料清单。 修复现有 candidate-images-build 的仅主仓 git archive 假设；不得退回读取开发者的可变工作目录。 前端使用锁文件 npm ci，Go 工具链和构建器固定版本/digest，禁用发布时隐式采用未知工具链。 -交叉编译与原生验收拆成独立 jobs，结果绑定最终制品摘要。 +构建与原生验收拆成独立 jobs，结果绑定最终制品摘要。 建议版本：组件用各自 SemVer；产品 RC 用 `vX.Y.Z-rc.N`，稳定版 `vX.Y.Z`。 保留旧 rc-v1.1.0-beta.* tags；新命名启用前兼容现有 promotion 脚本，不能重打历史 tag。 @@ -405,38 +867,47 @@ Gitea job token 默认不等于跨仓发布权限；发布机器人使用只覆 Development-Manager 已有独立历史，做差异合并，不再抽取覆盖。 受影响入口：现行 PROJECT/AGENTS、scripts/git-push-dev.sh、agentctl 集成和 Gitea settings（后续写入）。 -最小演练：在获授权的演练仓核对 Gitea 分支保护配置可用、管理员可部署服务端校验、manually-merged 能指向指定已合入提交；此阶段验证基础能力，不要求尚未编写的控制器已工作。 -出口：基线和保留策略明确、唯一集成权威选定、平台能力可行；产品仓仍走原流程。完整控制器验收归 U2，不能在 U1 先要求它通过。 +最小演练：在获授权的演练仓核对 Gitea 原生分支保护、非作者审批、required checks、陈旧分支拒绝与受限合并身份；验证 API/Web/Git 各入口没有未登记旁路。 +出口：基线与唯一远端集成权威明确，完整治理替代清单可审；产品仓仍走原流程。U2 通过后才切换，不先卸载旧门禁。 不在本阶段改变 test/main 部署。 -### U2. Adapt Multi-Repository Tooling +### U2. Replace Heavy Local Gates with Scoped Governance -覆盖 R4–R6/R9；预计 3–5 日，依赖 U1。 -修改 Development-Manager 的 agentctl/agent_worktree/git hooks/catalog，以及主仓薄入口、candidate 导出和收据 schema。 -新增 repo_id、组件清单、跨仓证据 URI；明确 clone 和 submodule Git 身份。 -Gitlink 门禁验证子仓受保护提交、文档审批与实际内容，不只检查父仓文件名。 +覆盖 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_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 合入；无凭证测试执行器不能写权威仓/环境。 +建议新增 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，机器契约留代码仓，活动状态/收据最后迁移。 +先拆通用 Guidelines 与静态 Documents，机器契约留代码仓；活动文档采用 PR/结构 CI，必要历史收据只读归档；不再要求专用 docs apply 写回。 改对应入口链接、客户端规则、archtest 清单位置、文档索引和证据查找。 声明版本采纳规则、owner 与旧路径只读状态。 新增文档链接/归属检查；继续验证 `internal/archtest`、`scripts/tests/test_agentctl*.py`。 -覆盖旧文档链接可追溯、新文档 PR 独立、缺文档权限仍能构建公开源码、能力状态不能因冲突退回、子仓 gitlink 不能绕过收据。 +覆盖旧文档链接可追溯、新文档 PR 独立、缺文档权限仍能构建公开源码、能力状态不能因冲突被意外退回、子仓 gitlink 不能绕过子仓审批和证据校验。 出口：每项内容有唯一写来源，无业务数据或运行模板误迁。 先抽取少量静态文档试点；失败通过普通 PR 恢复路径与 gitlink，不删除新仓历史。 ### U4. Extract Product Squad -覆盖 R2/R6；预计 5–8 日，依赖 U2，接口冻结后可与 U3 部分并行。 +覆盖 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。 @@ -449,8 +920,8 @@ Core/主仓保留一层临时 facade 适配 29 个调用文件，注明清除条 ### U5. Finish the Outer Repository -覆盖 R1/R3/R6；预计 2–4 日，依赖 U3/U4 稳定。 -将其余产品代码作为一个 Core 仓提取；保留 Web/DB/运行配置/Runner 同仓，主仓变为组合入口。 +覆盖 R1/R3/R6/R11/R12；预计 2–4 日，依赖 U3/U4/U7/U8 稳定。 +将其余产品代码作为一个 Core 仓提取；DB/产品运行配置与业务规则同仓，Web 与 Agent-Native 单独固定版本，主仓变为组合入口。 调整 Docker COPY、构建入口、Go replace、测试根目录、CodeGraph 索引、运行服务入口与资产根。 迁移源为批准的固定 SHA；源仓历史原样保留。 开发数据与生产数据目录不随代码树挪动；路径切换必须显式映射并在隔离环境验收。 @@ -461,20 +932,87 @@ Core/主仓保留一层临时 facade 适配 29 个调用文件，注明清除条 ### U6. Build and Release Portable Packages -覆盖 R7/R8；预计 3–5 日，分两个连续子阶段，沿用同一包格式与发布入口。 -U6a 在 U1 基线/授权边界明确后即可对当前固定单仓源码补齐运行资产、双平台包与私有发布演练，不等待 Core 提取。任何远端发布仍需要该实施阶段的明确授权。 +覆盖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 入口和目标平台部署模板。 -新增包内容/摘要/权限检查与两平台原生部署 smoke；CI 具体路径依实例 workflow 配置决定。 -验收干净 macOS arm64、Ubuntu amd64、可选 Ubuntu arm64，启动/health/ready/真实产品任务、升级、失败恢复、下载权限、重复发布冲突。 +新增包内容/摘要/权限检查与Ubuntu 26.04 amd64 原生部署 smoke；CI 具体路径依实例 workflow 配置决定。 +验收干净 Ubuntu 26.04 amd64，启动/health/ready/真实产品任务、升级、失败恢复、下载权限、重复发布冲突。 出口：私有 RC 实际可安装；公开晋升经授权且附件摘要一致。 业务数据库升级若存在，单列备份、前向兼容与恢复窗口；Git 回退不能宣称数据库已回退。 -粗略总工作量约 16–27 人日；这不是固定工期，U6a 可以并行，U1/U2 演练后重估。 -可以在 U3 或 U4 完成后暂停，而不强迫一次完成全部拆分。 +### 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。 +可以在独立阶段出口暂停；暂停时保留兼容的旧组合，不自动开启新后端。 --- @@ -487,16 +1025,38 @@ U6b 在 U5 后把同一配方切换为固定组件组合并重新验收；U6a | V3 跨仓版本 | 子仓 PR 未合入、SHA 仅在 fork | 主仓正式准入拒绝；候选联调明确非发布 | | V4 精确组合 | 改任一组件 gitlink 或构建配方 | manifest 摘要变化，原组合验收无效 | | V5 权限 | 无审核 push、fork CI 读发布 secret、匿名下载内部包；私有资料嵌入唯一测试标记 | 未授权访问均拒绝；token 不进测试进程；公开运行/源码包不得包含测试标记与未批准路径 | -| V6 并发合入 | 两个 controller/候选竞争同一 base | 只有一个推进，另一个重建；未知结果先 reconciliation | +| V6 并发合入 | 两个 PR 候选竞争同一 base，或非授权身份尝试合并 | 原生保护+按仓/分支串行，只采用新基线的有效候选；合入后tree与最终SHA可验证 | | V7 Squad 语义 | 文档生成/复杂任务 + 失败/权限/恢复变体 | 事件、正式文档、持久状态符合原产品合同 | -| V8 文档治理 | CURRENT/MATRIX 子仓变化，父仓 gitlink 更新 | 子仓收据/审批可追溯；不能因 gitlink 隐藏绕过 | +| V8 文档治理 | CURRENT/MATRIX 迁移为摘要/PR治理，父仓更新文档gitlink | 单一来源、子仓审批和证据可追溯；不依赖本地docs收据，不丢历史状态 | | V9 完整包 | 从任意 cwd 在无源码的干净机器启动 | Web/模板/xlsx/SQL 可用；缺依赖明确失败；不误连 dev DB | -| V10 平台 | darwin/arm64、linux/amd64 真机；arm64 可选 | 对最终包执行原生验收，交叉编译不能替代 | +| 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`，迁移后在对应组件目录运行。 -PG、真实 PI 与浏览器验收遵守当前验证契约，使用独立环境；共享环境须独占。 +实施阶段在本方案获审后按KTD14修订的验证契约选择PG、真实后端与浏览器验收；生效前遵循当前契约。使用独立环境，共享环境须独占。 本轮只做文档差异、链接和事实一致性检查，没有执行上述实施验收，不记录为 PASS。 --- @@ -508,25 +1068,27 @@ PG、真实 PI 与浏览器验收遵守当前验证契约，使用独立环境 | 仓库 | 拟用描述 | |---|---| | Agent-System | Agent-System 产品集成主仓：管理组件版本、开发入口、组合验证与发布流程。 | -| Agent-System-Core | Agent-System 核心应用：API、Web、身份权限、工作流、文档治理与数据持久化。 | +| 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 | 多项目开发协作治理工具：任务与工作区管理、执行约束、验证收据和集成控制。 | -| Agent-System-Releases | Agent-System 公开测试版与稳定版发布：macOS Apple Silicon、Ubuntu Server 部署包、校验与升级说明。 | -| Agent-System-Releases-Internal | Agent-System 私有内部测试与候选版本：受限部署包、版本清单及验收说明。 | +| 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 承接应用、采用受审 PR 的中央精确候选集成。 +需要用户审阅的核心建议：同意分阶段拆仓、复用 Development-Manager、最终新增 Core/Web/Agent-Native 承接对应能力，并采用 Gitea 原生准入及精简后的开发治理。 已确认的内部私有/公开隔离按本方案执行；不再作为未决问题。 实施前仍需验证、但本轮无法以只读研究证明的条件： -- Gitea 精确候选发布、服务端收据验证与 manually-merged 状态回写的端到端行为。 -- 可用的 macOS/Ubuntu 原生 runner、最低平台版本与公共 macOS 签名条件。 +- Gitea 原生审批/检查/过期拒绝、受限串行合并及合入后tree核验的真实行为；以及旧本地门禁退役后的权限负例。 +- Ubuntu 26.04 x86_64 的隔离 runner、干净部署测试环境与明确的运行依赖版本。 - 全量历史导出是否包含不应公开的内容；未扫描历史不能认为空仓导入自然安全。 - Core/Squad 公开模块命名空间，以及远期独立 go get 分发是否需要稳定域名。 - 切换时仍在运行的任务/操作、Workspace 格式兼容与实际部署资产布局。 @@ -541,7 +1103,8 @@ PG、真实 PI 与浏览器验收遵守当前验证契约，使用独立环境 本轮研究完成条件：现状证据、推荐与替代方案、仓库职责、协作/版本语义、迁移/回退、平台发布、可见性隔离、描述草稿与验收矩阵齐备，并交付用户审阅；不以实施状态衡量研究完成。 -未来实施完成条件：U1–U6 对应出口和 V1–V12 均有证据；主仓是可重建组合；所有组件 PR 与 gitlinks 可追溯；真实部署包在承诺平台完成原生产品验收；内部制品未被未授权访问；远端与运行状态分别记录。 +未来拆仓与Ubuntu发布完成条件：U1–U8及U10必选出口、V1–V16与V19–V34均有证据；主仓是可重建组合；所有组件 PR 与 gitlinks 可追溯；真实部署包在承诺平台完成原生产品验收；内部制品未被未授权访问；远端与运行状态分别记录。 +U9 是独立的原生核心替代交付线：V17/V18 与全部必需能力验收通过后才具备启用条件；U1–U8 完成不等于 PI 已被替代。 未获得公开发布授权时，内部验收通过不自动发布公开版本。 ---