一、为什么要做“治理优先”的编码Agent？

当下不少代码Agent实现，把重心放在提升模型生成效果上：Prompt调优、复杂多轮对话、更多工具调用。但工程落地时会遇到一堆现实痛点：

  1. AI随意修改项目内无关文件，改动范围不可控；
  2. 模型调用失败降级后静默假成功，用户以为任务完成实际什么都没产出；
  3. 生成语法错误的坏代码直接写入工程，引发连锁故障；
  4. 任务卡死、状态错乱，异常直接抛出500，没有审计与排查线索；
  5. Token、运行时长无管控，长任务成本不可控。

AICodeX 的核心立场：没有护栏的能力，不接入主流程。
它不是简单包装大模型API，而是一套完整工程系统，强制闭环：规划→执行→校验→修复重试，同时叠加权限、熔断、沙箱、审计全套治理能力。整套设计遵循四条核心原则：

  • 治理优先于能力：能生成代码，不等于可以随便生成代码；
  • 模型驱动 + 规则兜底：模型正常走模型；密钥缺失、调用失败自动切规则降级，并且降级行为对用户显式可见，绝不静默假成功；
  • 白盒可观测：全部关键动作经由事件总线广播，前端实时展示，审计日志落库；
  • 最小权限：文件写入受锁定清单、路径沙箱双重约束，越权直接拒绝。

二、五层分层架构：所有任务统一走Supervisor入口

系统自上而下分为五层，依赖单向向下，所有任务必须经过监督调度层supervisor单例，从流程层面锁死执行顺序，避免多任务互相串扰。

┌─────────────────────────────────────────────────────────────┐
│ 接入层        REST接口 / WebSocket长连接                     │
├─────────────────────────────────────────────────────────────┤
│ 监督调度层    Supervisor（六态状态机、编排、护栏、变更暂存）  │
├─────────────────────────────────────────────────────────────┤
│ 智能体层      Planner / Designer / Deployer / Executor / Verifier │
├─────────────────────────────────────────────────────────────┤
│ 工具与中间件  工具注册中心、原子写入、路径沙箱、语法校验等    │
├─────────────────────────────────────────────────────────────┤
│ 基础设施层    模型路由、上下文管理、知识图谱、事件总线       │
└─────────────────────────────────────────────────────────────┘

几个关键设计细节：
1. 大量核心组件（调度器、各个智能体、模型路由、工具注册中心、事件总线等）采用模块级单例，避免跨任务调用串扰，熔断器、审计逻辑只需要一次绑定；
2. 事件总线是整个系统可观测的基石，进程内发布订阅，全链路关键事件向外广播，供给审计日志、监控指标、前端实时面板、WebSocket推送；
3. 接入层同时支持REST同步调用与WebSocket流式推送，两套入口最终复用同一套调度逻辑，保证行为一致性。

三、六态状态机：把编码任务变成可控的状态流转

AICodeX用一套六态有限状态机定义任务完整生命周期，定义文件：app/core/orchestration/state_machine.py。

状态 含义
IDLE 任务空闲
PLAN 规划中
EXEC 代码执行落盘
VERIFY 后置校验
DONE 正常完成（终态）
CANCELLED 取消/熔断终止（终态）

合法状态转移规则：

IDLE     → {PLAN, CANCELLED}
PLAN     → {EXEC, PLAN, CANCELLED}        # PLAN→PLAN支持重新规划
EXEC      → {VERIFY, CANCELLED}
VERIFY    → {DONE, EXEC, CANCELLED}        # 校验失败自动回退EXEC修复重试
DONE      → {}
CANCELLED → {}

非法状态转移会直接抛出IllegalTransitionError，杜绝流程错乱。

执行闭环逻辑：规划完成直接进入执行，没有人工审核计划的中间状态。执行完成自动进入校验；校验不通过，会自动回到执行阶段做修复，最多重试governance.verify_retry_max次（默认2次），重试耗尽直接置为CANCELLED，防止死循环。

核心循环伪代码：

while True:
    supervisor.execute()                 # Executor执行落盘
    if state in (CANCELLED, DONE):
        return 终止报告
    report = supervisor.verify()         # Verifier后置校验
    if report.passed or not verification_retryable:
        return report
    # 校验失败，回到EXEC自动修复

REST和WebSocket两套入口，都会跑这套闭环，保证行为统一。

四、多智能体分工：不同任务，走不同智能体链路

系统内置5个智能体，各司其职，不会让同一个Agent既做架构设计、又写代码、又做校验。任务类型TaskType决定智能体执行路径：

任务类型 触发场景 智能体链路
SIMPLE_QA 普通问答 直接模型回答，不走代码生成闭环
CODING 编码修改、新增代码 Planner → Executor → Verifier
ARCHITECTURE 架构设计需求 Designer → Planner → Executor → Verifier
DEPLOYMENT 部署配置任务 Deployer → Planner → Executor → Verifier

4.1 四层意图判定链

不再使用简单关键词分类，采用L0~L3四层判定链：
- L0极速通道（规则）：寒暄、确认类指令直接识别为普通问答，省去模型调用；
- L1模型主判：模型输出意图、关键词、符号、文件路径；
- L2规则降级：模型不可用的时候，规则打分兜底，保证无密钥环境也可以跑；
- L3澄清：信息不足，向前端推送澄清卡片，而不是粗暴归为普通问答。

识别出来的文件路径、符号直接喂给代码知识图谱做召回，帮助Agent理解现有代码库。

4.2 各个智能体核心职责

Planner（规划智能体）
只输出结构化计划，不调用任何工具执行代码；低温度保证输出确定性。强制每个会产出文件的步骤必须写明目标文件，缺失会重试+正则补全。同时结合知识图谱召回现有代码，让AI知道应该改哪些文件。模型故障时回退规则模板，并且显式标记降级。

Designer / Deployer（专家智能体）
在Planner之前运行，输出架构/部署文档落盘到工作区docs目录；系统强制保证设计产出必须有对应的落盘步骤，避免“只输出思考，不产出文件”。

Executor（执行智能体）
只能修改计划阶段锁定清单内的文件，越权直接拒绝。生成代码后先做语法预检，预检失败直接放弃落盘，返回错误，不让语法错误的坏文件污染工程。单步执行失败不会杀死整个任务，标记失败继续跑后续步骤。

Verifier（校验智能体）
对所有变更文件做校验：检查文件是否生成、Python/JS语法是否合法；校验结果驱动自动修复重试，达到重试上限终止任务。

五、整套护栏体系：治理能力是怎么落地的

这是AICodeX区别普通Agent最核心的部分，多层防护同时生效。

1. 任务文件锁定 LockedFileSet

规划阶段输出本次任务允许修改的文件清单，Executor只能修改清单内文件，禁止触碰项目其他文件；任务结束自动清空锁定集合。执行过程新增文件可以动态加入锁定集合。

2. 超控熔断 BudgetGuard

双重阈值保护任务成本：
- 时长阈值：单任务最长执行时间，默认600秒超时；
- Token阈值：软阈值触发警告；硬阈值触发暂停。

软提醒机制：触发熔断不会直接杀掉任务，而是暂停，向前端推送BUDGET_EXCEEDED事件，等待用户确认继续还是终止；用户无应答兜底终止，兼顾安全和灵活性。

3. 路径沙箱 PathSandbox

全部文件操作统一经过沙箱校验，限制在工作区根目录以内，拦截../路径穿越攻击；服务端/fs/*文件接口复用同一套沙箱逻辑，不会出现接口和Agent两套校验逻辑不一致。

4. 原子写入 AtomicWriter

写入流程：生成临时文件 → fsync刷盘 → os.replace原子替换。防止进程崩溃造成文件半写损坏；区分文件和目录，特殊文件名白名单放行。

5. Schema参数校验

基于Pydantic v2强校验所有工具入参，拦截危险路径；全部工具调用返回标准化ToolResult，统一错误码，前端可以友好展示错误信息。

6. 故障韧性设计

  • 链路异常不返回500，返回结构化错误，同时复位状态机，避免任务卡死；
  • 降级模式下的产物会被校验器识别，不会判定为任务成功，避免假性成功；
  • 编码任务没有产出任何文件，直接报错提示，防止静默失败；
  • 重试次数硬上限，避免校验修复进入无限死循环。

六、模型路由与知识图谱

模型路由 model_router

不同任务类型默认绑定不同优先级模型，同时支持自定义模型端点。候选模型按顺序自动降级，单模型连续失败达到阈值会临时熔断，全部熔断后重置放行主模型。每次模型调用统计Token，对接预算熔断器。

配置config.yaml的model.base_url即可开启自定义端点模式，所有任务统一走自定义LLM服务。

代码知识图谱kg工具集

把代码索引封装成标准工具，Agent通过工具注册表调用语义检索、符号查询、调用关系分析；图谱不可用时自动降级，不会阻断主流程；同时限制扫描文件数量、上下文长度，防止上下文爆炸。

七、可观测性：事件总线、审计与监控

系统一共定义22种事件，覆盖任务全生命周期：任务启停、状态变更、意图识别、规划结果、工具调用、模型调用、校验结果、预算超限、异常报错等。

事件发布前自动做敏感信息脱敏，防止API密钥、密码泄露。事件订阅方包括：
1. 审计模块：事件落库，支持事后回溯审计；
2. Metrics指标：对外暴露Prometheus监控；
3. WebSocket网关：向前端实时推送，实现过程可视化；
4. 本地Dashboard快照接口。

配套接口：健康检查、指标接口、任务状态查询、变更暂存管理、会话管理、任务取消接口、文件操作接口等，同时支持REST和WebSocket两套交互方式。

八、记忆、配置与测试保障

  1. 用户记忆偏好：系统会提取用户长期编码偏好（例如习惯Python、需要详细注释），生成阶段注入模型System Prompt，问答链路、Agent编码链路分别处理。
  2. 核心配置：全部集中在config.yaml，工作区根目录、超时时间、Token阈值、重试次数、沙箱白名单等均可调整；密钥建议通过环境变量注入，配置文件加入gitignore，避免密钥泄露。
  3. 测试保障：内置完整测试套件，包含端到端冒烟测试、故障韧性测试，全量316个用例全部通过，覆盖降级、语法错误、异常复位、规划强制带目标文件等边界场景。

项目也明确说明已经裁撤的模块：原Web应用生成器、进程级执行沙箱，属于零调用死代码，直接移除，减少维护负担。

九、简单看一遍REST模式完整时序

用户输入需求，到系统输出结果的完整流程：
1. 用户提交需求，前端发起POST /messages；
2. 服务端交给Supervisor启动任务，进入PLAN状态；
3. 若为架构/部署任务，先运行Designer/Deployer专家智能体；再运行Planner输出结构化规划，锁定本次修改文件；
4. 调度器驱动Executor执行，原子写入变更文件；
5. Verifier执行校验，语法、文件存在性检查；
6. 校验失败自动回到EXEC阶段修复，达到重试上限终止；校验通过置DONE；
7. 将报告返回前端，同时全流程事件被审计落库。

十、总结思考：Agent编码工程化的启示

AICodeX这套系统给我们一个启示：AI编码Agent的工程落地，难点不完全在于大模型本身，更多在于外围治理体系。

当我们只把Agent理解成“调用大模型+调用工具”，很容易忽略状态管控、权限隔离、异常兜底、可观测审计这些工程要素，上线之后就会遇到乱改文件、静默失败、任务失控等线上问题。

AICodeX的设计选择：
1. 用状态机把任务流程锁死，禁止非法流转；
2. 文件锁定+沙箱+原子写入，多层防护代码库安全；
3. 校验+自动修复闭环，同时设置重试上限，兼顾自动化与防死循环；
4. 模型降级必须显式，拒绝静默假成功；
5. 事件总线做全链路白盒可观测，所有行为可审计可排查。

当然这套方案也有取舍：增加治理层带来一定的系统复杂度；没有保留进程内Shell执行沙箱，放弃命令执行能力，换来了更高安全性。

如果你在做AI编码Agent相关开发，这套白皮书和源码可以作为一份不错的工程参考基线。