跳至主要内容

自动审查 Agent 完整运转实录：从权限检查到审计日志的十二个组件协同

Fen9Pi2026/6/9AI AgentAI Agent大约 9 分钟

自动审查 Agent 完整运转

看一次 PR 自动审查 Agent 的完整运转。

从 Agent 启动到审计日志记录。

十二个组件如何协同工作。

从理论到实践，从框架到运转。

完整运转流程

完整运转流程

场景： PR 自动审查 Agent

目标： 审查一个 PR，发现安全问题，提供修复建议

Step 1：Agent 启动

Agent 启动

触发：SessionStart

动作：

  • 加载项目 settings.json
  • 加载权限白名单
  • 加载 hooks 注册
  • 初始化会话状态
  • 初始化记忆系统

加载内容：

{"
  "permissions": {
    "allow": ["gh", "git"],
    "deny": ["*.env", "config/**"]
  },
  "hooks": {
    "preToolUse": "pre_tool_check.sh",
    "postToolUse": "audit_log.sh",
    "preToolBatch": "session_init.sh"
  }
}

Step 2：收到 PR 审查任务

收到 PR 审查任务

输入：

  • PR #123
  • 仓库：example/repo
  • 分支：feature/auth

上下文管理：

  • 加载 PR 元数据
  • 加载代码 diff
  • 加载相关历史
  • 加载项目规范

Prompt 构造：

  • 系统指令：审查规范
  • 用户指令：审查任务
  • 工具描述：可用工具列表
  • 上下文注入：PR 信息

Step 3：调 gh pr diff

调用 gh pr diff

工具系统：

  • 工具：gh
  • 参数：pr diff
  • 上下文：PR #123

PreToolUse 检查：

  1. 工具是否在白名单？
    • gh 在 allow 列表 → 放行
  2. 参数是否安全？
    • 无敏感参数 → 放行
  3. 权限是否足够？
    • 有读取权限 → 放行

结果：

  • exit 0
  • 放行执行

输出解析：

  • 获取 diff 内容
  • 解析文件变更
  • 解析代码修改

Step 4：调 Edit 修改代码建议

调用 Edit 修改代码建议

工具系统：

  • 工具：Edit
  • 参数：file, line, suggestion

PreToolUse 检查：

  1. 工具是否在白名单？
    • Edit 在 allow 列表 → 放行
  2. 目标路径是否安全？
    • 路径：src/auth/login.ts
    • 检查：src/** 在允许范围 → 放行

结果：

  • exit 0
  • 放行执行

输出解析：

  • 代码建议已生成
  • 准备下一步审查

Step 5：想执行 npm test

想执行 npm test

工具系统：

  • 工具：npm
  • 参数：test

PreToolUse 检查：

  1. 工具是否在白名单？
    • npm 不在白名单 → 进一步检查
  2. 是否有特殊授权？
    • 检查 hooks 配置
    • 发现 test_scenarios 指令
  3. 场景是否匹配？
    • 当前：PR 审查
    • test_scenarios：["pr_review", "security_audit"]
    • 匹配 → 放行
  4. 参数是否安全？
    • npm test → 安全 → 放行

结果：

  • exit 0
  • 放行执行

输出解析：

  • 测试结果：通过
  • 继续审查

Step 6：发现 SQL 注入漏洞

发现 SQL 注入漏洞

上下文管理：

  • 识别漏洞类型：SQL 注入
  • 识别漏洞位置：src/db/query.ts
  • 识别漏洞风险：高

记忆管理：

  • 记录漏洞详情
  • 记录漏洞位置
  • 记录修复建议

状态管理：

stage: vulnerability_found
issues:
  - type: sql_injection
    file: src/db/query.ts
    line: 42
    severity: high
    status: pending_fix

Step 7：尝试修改 .env 文件修复

尝试修改 .env 文件修复

工具系统：

  • 工具：Edit
  • 参数：.env, DB_QUERY_TIMEOUT=5000

PreToolUse 检查：

  1. 工具是否在白名单？
    • Edit 在 allow 列表 → 放行
  2. 目标路径是否安全？
    • 路径：.env
    • 检查：*.env 在 deny 列表
    • 拒绝！

安全护栏：

  • 触发权限拒绝
  • 记录拒绝日志
  • 返回错误信息

PostToolUseFailure：

  • 错误类型：PERMISSION_DENIED
  • 错误消息：不能修改 .env 文件
  • 建议方案：生成修复建议

输出解析：

  • 解析错误信息
  • 理解拒绝原因
  • 调整修复策略

Step 8：转而生成修复建议

转而生成修复建议

编排循环：

  • 原方案：修改 .env → 被拒绝
  • 新方案：生成修复建议 → 不触碰 .env

Prompt 构造：

  • 系统指令：修复建议模板
  • 上下文注入：SQL 注入漏洞详情
  • 限制说明：不能修改 .env

输出解析：

  • 生成修复建议
  • 修改代码逻辑
  • 使用参数化查询

状态管理：

stage: fix_suggested
issues:
  - type: sql_injection
    file: src/db/query.ts
    line: 42
    severity: high
    status: fix_suggested
    suggestion: |
      使用参数化查询替代字符串拼接：
      const query = db.query('SELECT * FROM users WHERE id = $1', [userId])

Step 9：审查完成，准备 git commit

审查完成，准备 git commit

状态管理：

  • 当前状态：review_done
  • 下一步：commit_suggestions

编排循环：

  • 检查是否完成所有审查维度
  • 检查是否生成修复建议
  • 准备提交审查结果

Step 10：PreToolUse 匹配 git commit

PreToolUse 匹配 git commit

工具系统：

  • 工具：git
  • 参数：commit

PreToolUse 检查：

  1. 工具是否在白名单？
    • git 在 allow 列表 → 放行
  2. 触发特殊场景？
    • 检查 hooks 配置
    • 发现 commit_verify 场景
  3. 执行验证脚本
    • 运行审查完整性检查

验证循环：

审查完整性检查脚本

检查维度：

  • [✓] 安全审查：SQL 注入已识别
  • [✓] 代码质量：代码规范已检查
  • [✓] 性能问题：性能影响已评估
  • [✓] 测试覆盖：测试建议已提供
  • [✓] 文档更新：文档建议已提供

结果：

  • 所有维度都有结论
  • exit 0
  • 放行

Step 11：Agent 提交代码

Agent 提交代码

工具系统：

  • 工具：git
  • 参数：commit -m "security: SQL injection fix suggestion"

PostToolUse：

  • 记录操作类型：git commit
  • 记录操作结果：成功
  • 记录操作时间：2026-06-09 10:15:30

状态管理：

stage: committed
commit:
  hash: abc123
  message: "security: SQL injection fix suggestion"
  time: "2026-06-09T10:15:30Z"

Step 12：PostToolUse 记录审计日志

PostToolUse 记录审计日志

安全机制：

  • 触发 PostToolUse hook
  • 运行 audit_log.sh

审计日志：

{
  "timestamp": "2026-06-09T10:15:31Z",
  "agent_id": "pr-review-agent",
  "session_id": "session-abc123",
  "operation": "git_commit",
  "target": "repo",
  "result": "success",
  "details": {
    "commit_hash": "abc123",
    "pr_number": 123,
    "issues_found": 1,
    "fixes_suggested": 1
  },
  "permissions": {
    "tools_allowed": ["gh", "git", "Edit"],
    "tools_denied": ["*.env"],
    "denials": 1
  }
}

安全护栏：

  • 日志持久化
  • 日志不可篡改
  • 日志可审计

十二个组件映射

十二个组件映射

1. 编排循环

实现：Stop/PostToolBatch

作用：

  • 控制 Agent 什么时候做
  • 控制 Agent 什么时候停
  • 控制最大迭代次数
  • 控制超时机制

例子：

Stop 触发条件：
- 迭代次数 > 10
- 超时 > 300 秒
- 所有审查维度完成

2. 工具系统

实现：PreToolUse + PostToolUse

作用：

  • 工具注册
  • 工具调用
  • 工具验证
  • 工具结果解析

例子：

PreToolUse：
- 检查工具权限
- 检查参数安全
- 检查场景匹配

PostToolUse：
- 记录操作结果
- 触发审计日志

3. 记忆管理

实现：SessionStart + CLAUDE.md

作用：

  • 会话内记忆
  • 跨会话记忆
  • 记忆检索
  • 记忆更新

例子：

SessionStart：
- 加载项目历史
- 加载审查历史
- 加载漏洞模式

CLAUDE.md：
- 项目规范
- 审查标准
- 修复建议模板

4. 上下文管理

实现：SessionStart + PR 元数据加载

作用：

  • 上下文选择
  • 上下文压缩
  • 上下文优先级
  • 上下文窗口管理

例子：

上下文选择：
- PR 元数据
- 代码 diff
- 相关历史
- 项目规范

上下文压缩：
- 只加载相关文件
- 只加载最近历史
- 只加载相关规范

5. Prompt 构造

实现：SessionStart + 动态指令生成

作用：

  • 系统指令模板
  • 用户指令注入
  • 工具描述注入
  • 上下文注入

例子：

Prompt 构造：
- 系统指令：审查规范
- 用户指令：审查 PR #123
- 工具描述：可用工具列表
- 上下文：PR 信息 + 代码 diff

6. 输出解析

实现：PostToolUse + 状态管理

作用：

  • 响应解析
  • 结构化提取
  • 意图识别
  • 参数提取

例子：

输出解析：
- 解析 gh pr diff 输出
- 解析 npm test 输出
- 解析权限拒绝错误
- 解析验证脚本输出

7. 状态管理

实现：YAML frontmatter

作用：

  • 会话状态
  • 任务状态
  • 迭代状态
  • 状态持久化

例子：

session:
  id: "session-abc123"
  stage: "committed"
  started_at: "2026-06-09T10:00:00Z"

task:
  type: "pr_review"
  pr_number: 123
  status: "done"

iteration:
  count: 5
  last_action: "git_commit"

issues:
  - type: "sql_injection"
    status: "fix_suggested"

8. 错误处理

实现：PostToolUseFailure

作用：

  • 错误检测
  • 错误分类
  • 错误恢复
  • 错误重试

例子：

错误处理：
- 错误类型：PERMISSION_DENIED
- 错误消息：不能修改 .env 文件
- 恢复策略：生成修复建议
- 重试策略：不重试，调整方案

9. 安全护栏

实现：权限模型 + 沙箱

作用：

  • 输入过滤
  • 输出过滤
  • 操作限制
  • 权限控制

例子：

权限模型：
- allow: ["gh", "git", "Edit"]
- deny: ["*.env", "config/**"]

沙箱：
- 文件系统隔离
- 网络隔离
- 资源限制

10. 验证循环

实现：审查完整性检查脚本

作用：

  • 验收标准
  • 自动验证
  • 人工验证
  • 迭代修复

例子：

审查完整性检查：
- [✓] 安全审查
- [✓] 代码质量
- [✓] 性能问题
- [✓] 测试覆盖
- [✓] 文档更新

所有维度都有结论 → 放行

11. 子 Agent 编排

实现：SubagentStart/Stop（可选）

作用：

  • Agent 发现
  • Agent 调度
  • Agent 通信
  • Agent 协作

例子：

子 Agent 编排：
- 主 Agent：PR 审查
- 子 Agent：安全审查
- 子 Agent：性能审查
- 子 Agent：代码规范审查

12. 安全机制

实现：沙箱 + 权限 + 审计

作用：

  • 沙箱隔离
  • 权限管理
  • 审计日志
  • 安全监控
  • 应急响应

例子：

安全机制：
- 沙箱隔离：文件系统隔离
- 权限管理：白名单 + 黑名单
- 审计日志：PostToolUse 记录
- 安全监控：实时监控异常操作
- 应急响应：Stop 触发条件

配置管理：四层继承

配置管理

四层继承机制：

  1. 全局配置（系统级）

    • 系统默认权限
    • 系统默认 hooks
    • 系统默认安全策略

  2. 组织配置（组织级）

    • 组织权限策略
    • 组织 hooks 配置
    • 组织安全标准

  3. 项目配置（项目级）

    • 项目权限白名单
    • 项目 hooks 注册
    • 项目审查规范

  4. 会话配置（会话级）

    • 会话权限覆盖
    • 会话 hooks 覆盖
    • 会话特殊场景

继承规则：

  • 会话 > 项目 > 组织 > 全局
  • 子配置覆盖父配置
  • 未定义则继承父配置

例子：

全局配置：
  allow: ["git"]

项目配置：
  allow: ["git", "gh", "Edit"]

会话配置：
  deny: ["*.env"]

最终配置：
  allow: ["git", "gh", "Edit"]
  deny: ["*.env"]

关键洞察

关键洞察

从理论到实践。

Harness Engineering 的归纳框架：

生产级 Agent 的十二个维度。

从理论到运转。

这次 PR 审查 Agent 的完整运转：

展示了十二个组件如何协同工作。

关键点：

  1. 编排循环：控制 Agent 什么时候做、什么时候停
  2. 工具系统：PreToolUse + PostToolUse 双重检查
  3. 安全护栏：权限模型 + 沙箱隔离
  4. 错误处理：PostToolUseFailure 自动恢复
  5. 验证循环：审查完整性检查确保质量
  6. 安全机制：审计日志完整记录所有操作

从框架到运转。

十二个组件不是孤立的。

它们是协同工作的。

自动审查 Agent 完整运转实录

从权限检查到审计日志的十二个组件协同。

最近更新:
贡献者: Fen9Pi
Copyright © 2016-2022 风派 | 苏ICP备2025227748号-3