weichen
24185ac066
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
80 lines
7.2 KiB
Markdown
80 lines
7.2 KiB
Markdown
# 共享 Agent 执行器差异审计与架构归属（U3）
|
||
|
||
## 一、背景与审计目的
|
||
|
||
在推进“开发分支与 Agent 执行规范升级”（`development-governance-v2`）治理大任务中，核心要求之一是将 Agent CLI 执行约束由 Agent-System-Dev 的项目私有规则提升为 Development-Guidelines 的通用工程规范，并解决各仓库共享执行器的归属与复用问题。
|
||
|
||
本审计针对当前已存在的两个主要实现进行差异比对：
|
||
1. **Agent-System-Dev 控制器**：`scripts/agent_exec.py` + `scripts/agent_exec_adapters.py` + `scripts/agent_exec_config.py`；
|
||
2. **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 派发遵循完全一致的失败分流、收据解析与受控集成契约。
|
||
|
||
---
|
||
|
||
## 四、结论与验收判据
|
||
|
||
1. **合同在先，实现对齐**：通用规范（Development-Guidelines）只约束合同（有界单元、会话隔离、收据格式、受控准入、禁止代写），不绑定具体语言实现。
|
||
2. **工具符合性**：任何执行器（无论是 Dev 的 Python 脚本还是 DM 的 Go runner）必须通过相同的正负例验收判据（A8）才能声明为合规执行器。
|
||
3. **消除隐式代写**：所有工具实现均必须支持 `fallback_to_host: never`，在候选耗尽时明确返回受阻终态，不得放行 Host 隐式撰写业务代码。
|