Files

T

weichen 24185ac066 Document shared executor architecture audit for governance v2

Why:
Audit differences between Agent-System-Dev agent_exec.py and Development-Manager runner.go to clarify layer responsibilities for governance v2.

Evidence:
Architecture specification document created in docs/superpowers/specs/.

Impact:
Provides guidance for U3 shared executor convergence without duplicating logic across repositories.

Refs:
feature/development-governance-v2

2026-10-16 07:16:07 +00:00

7.2 KiB

Raw Blame History

共享 Agent 执行器差异审计与架构归属（U3）

一、背景与审计目的

在推进“开发分支与 Agent 执行规范升级”（development-governance-v2）治理大任务中，核心要求之一是将 Agent CLI 执行约束由 Agent-System-Dev 的项目私有规则提升为 Development-Guidelines 的通用工程规范，并解决各仓库共享执行器的归属与复用问题。

本审计针对当前已存在的两个主要实现进行差异比对：

Agent-System-Dev 控制器：scripts/agent_exec.py + scripts/agent_exec_adapters.py + scripts/agent_exec_config.py；
Development-Manager 任务运行器：internal/runner/runner.go + 相关适配器。

目标是确定唯一所有者边界，避免在十几个仓库中复制代码，也不在通用规范库中塞入守护进程与语言特定绑定。

二、两套实现的详细比对

维度	Agent-System-Dev (`agent_exec.py`)	Development-Manager (`runner.go`)	契约对齐与差距分析
调用模型	按需由 Host（CLI / Makefile / 脚本）调起的有界执行单元控制器	后台常驻守护进程，从 PostgreSQL 数据库轮询 `tasks` 记录并执行	DM 属于异步平台运行器，Dev 属于交互式/本地工程单元执行器。两者面向阶段不同。
配置权威	严格读取项目根目录 `AGENT-EXECUTION.md`，校验 schema 与角色路由	数据库中记录项目与任务信息，硬编码或配置注入 adapter 列表	DM 未对接各项目独立的 `AGENT-EXECUTION.md` 配置。
角色路由	支持 `implementation`、`repair`、`test`、`review` 四个独立角色候选列表	仅支持单一全局适配器列表遍历	DM 缺乏按任务角色（实施/修复/测试/审查）精细路由的能力。
候选轮换与重试	严格遵循候选顺序，每候选最多 3 次全新尝试；安全可恢复失败才换候选；全耗尽后支持一次 emergency profile	尝试按序获取可用适配器，未实现针对 profile 的精确尝试计数与失败分类	DM 缺少对失败语义的严格分流。
失败分类与 Fail-Stop	细分为 `unavailable`、`failed-clean`、`failed-unknown`、`scope-expansion`、`blocked`、`cancelled`；未知副作用严格 fail-stop	仅判断 err 是否为 nil，超时则记录预算耗尽，未提交改动记失败	DM 未对未知副作用进行防扩散控制，缺乏 fail-stop 门禁。
会话与进程隔离	每次尝试必为全新临时进程与工作区；禁止 `--continue`/`--resume`	在 `.worktrees/` 下新建 worktree，但适配器内部进程管理由适配器各自实现	两者均采用独立 worktree，但 Dev 控制器对 CLI 命令行参数和 session flag 做了强制隔离。
终态收据解析	实时消费事件流，严格从 CLI 原生信封（Cursor `result`、agy `result`/`json`、PI `message_end`）解码结构化收据	依赖适配器返回 `Receipt` 结构体，不校验底层事件信封篡改	Dev 控制器的解码更防伪造，严格区分自然语言完成与结构化 completed。
Git 权限与推送边界	Worker 完全无 Git 推送与 PR 权限；通过受控 transport 快照集成，并由 pre-commit admit 校验 HMAC	Runner 代办 `gitPush` 并调用 Gitea API 创建 PR，但 Worker 需在 worktree 内完成 commit	DM 模型直接将 Worker 的 commit 推送到远端，缺少 Host 主动审查与 transport 完整性准入。
Host Fallback	`fallback_to_host: never`，安全耗尽后输出 `blocked`/`unavailable`，绝不代写业务代码	任务失败后将任务置为 `open` 或打标签，但未约束本地主协调者行为	通用规范要求明确禁止 Host 隐式代写。

三、架构归属与分工决策

根据 Development-Guidelines 的要求与实现分离原则：

+-----------------------------------------------------------+
| Development-Guidelines (规范权威)                          |
| - 核心规则硬边界 8 (Core Baseline MUST)                   |
| - 通用 Agent 执行契约 (standards/agent-execution.md)        |
| - 机器校验 Schema (templates/schemas/agent-execution.json)|
| - 项目执行配置模板 (templates/AGENT-EXECUTION.md.template) |
+-----------------------------------------------------------+
                              │ 规定合同与合格判据
                              ▼
+-----------------------------------------------------------+
| 共享工具层 (Development-Manager 或 独立执行控制器包)       |
| - 可复用执行控制器 (Execution Controller)                 |
| - 标准 CLI 适配器 (Cursor / Antigravity / PI / Codex)     |
| - 事件流解码器与收据校验器 (Terminal Receipt Validator)   |
| - 受控 Transport 打包器与 Admission 准入校验器             |
+-----------------------------------------------------------+
                              │ 被各项目通过轻量入口调用
                              ▼
+-----------------------------------------------------------+
| 宿主项目仓库 (Agent-System-Dev / Core / Backend / ...)    |
| - 项目根目录 AGENT-EXECUTION.md (角色、候选、超时、豁免)  |
| - Makefile 薄封装 (make agent-exec-validate/apply/admit)  |
| - 项目特有豁免路径与测试验证入口                           |
+-----------------------------------------------------------+

1. 为什么不将控制器直接放入 Development-Guidelines？

Development-Guidelines 纯粹以文档、契约、schema 和规则为主，不依赖任何编程语言运行时（Python/Go/Node），也不包含守护进程。将几十页 Python 脚本或 Go 源码放入规范仓会破坏其轻量、项目无关和通用性。

2. 为什么不把 Dev 的 `scripts/agent_exec.py` 复制到各个仓库？

在 15 个以上的仓库中各复制一份 2700 行的 Python 脚本，会导致版本漂移、修复成本倍增和维护灾难。

3. 工具层演进路径

短期（当前试点期）：以 Agent-System-Dev 中验证成熟的 scripts/agent_exec.py、agent_exec_adapters.py、agent_exec_config.py 作为黄金参考实现（Reference Implementation）。
中期（共享工具化）：将该控制器抽取为独立 CLI 工具（如 agent-exec CLI）或作为 Development-Manager 的底层执行子命令（dm exec），供本地协调者与 CI/CD 统一调用。
长期（自动化闭环）：Development-Manager 异步调度器在后台派发任务时，直接复用该底层执行内核，确保自动化派发与本地 Host 派发遵循完全一致的失败分流、收据解析与受控集成契约。

四、结论与验收判据

合同在先，实现对齐：通用规范（Development-Guidelines）只约束合同（有界单元、会话隔离、收据格式、受控准入、禁止代写），不绑定具体语言实现。
工具符合性：任何执行器（无论是 Dev 的 Python 脚本还是 DM 的 Go runner）必须通过相同的正负例验收判据（A8）才能声明为合规执行器。
消除隐式代写：所有工具实现均必须支持 fallback_to_host: never，在候选耗尽时明确返回受阻终态，不得放行 Host 隐式撰写业务代码。

7.2 KiB Raw Blame History Unescape Escape