OpenHuman Critic 对抗式代码评审 Agent 全解析：从 prompt 设计到只读沙箱实现

OpenHuman Critic 对抗式代码评审 Agent 全解析从 prompt 设计到只读沙箱实现【免费下载链接】openhumanOpenHuman is an open source personal AI for Mac, Windows and Linux — local-first memory, agent orchestration, and deep research.项目地址: https://gitcode.com/GitHub_Trending/op/openhuman导读本文以 OpenHuman 内置Critic对抗式 QA 评审子代理为研究对象完整解读其系统提示词prompt、能力边界、评审清单、行为规则并结合仓库源码剖析其agent.toml配置语义、工具调用链read_diff/run_linter/run_tests/file_read、系统提示词装配过程prompt.rs以及 Orchestrator 的委托路由机制。读完本文你将掌握 OpenHuman 中只读、对抗式、结论回流的代码评审子代理是如何设计、配置与工作的并可据此理解如何阅读或调优同类内置 Agent 的 prompt 与工具权限。一、Critic 在 OpenHuman 中的地位与定位OpenHuman 的 Agent 注册表位于 src/openhuman/agent/registry其中 agents 目录 内置了 30 余个专职子代理例如 planner、researcher、code_executor、vision_agent、crypto_agent 等。Critic 是其中之一其完整定义由同一目录下的三个文件组成agent.toml —— 结构化元数据ID、温度、迭代上限、沙箱模式、工具白名单、委托名称等prompt.md —— 本文的主角即 Critic 的原型提示词archetype bodyprompt.rs —— 将原型提示词与运行时上下文拼接为最终系统提示词的构建器prompt_tests.rs —— 对应的单元测试。从 loader.rs 的加载流程看每个内置 Agent 都遵循agent.tomlprompt.mdprompt.rs三件套布局load_builtins遍历内置列表将agent.toml解析为AgentDefinition再把未显式设置的system_prompt替换为PromptSource::Inline(prompt.md 内容)并标记DefinitionSource::Builtin。Critic 的角色定义在 prompt.md 第一行便直截了当你是 Critic 代理。你的工作是在问题进入生产环境之前发现它们。它是一个对抗式AdversarialQA 评审者——不负责写代码只负责找毛病、按优先级上报并将结论交还给 Orchestrator 决策。二、CapabilitiesCritic 的四种核心能力prompt.md 中列出的能力与agent.toml中[tools] named工具白名单一一对应构成了 Critic 的完整工具面能力prompt.md对应工具实现位置读取 git diff 评审变更read_diffread_diff.rs运行 linterclippy / eslint并解读结果run_linterrun_linter.rs运行测试套件并验证正确性run_testsrun_tests.rs读取项目文件获取上下文file_readfilesystem/mod.rs 中的文件读取工具四个工具全部位于tools/impl/filesystem目录其注释均明确标注为 Critic 原型Critic archetype服务。值得注意的是这四个工具虽然运行外部进程git、cargo clippy、eslint、cargo test、vitest但在权限模型上都被声明为PermissionLevel::ReadOnly——这正是评审者不写代码原则在工具层的落地。2.1 read_diff结构化 diff 读取read_diff.rs 内部实际执行git diff --stat -p支持三个参数basestringdiff 的基准引用如main、HEAD~3缺省时对比未暂存unstaged改动stagedboolean仅显示已暂存改动等价--cached默认falsepath_filterstring将 diff 限制到指定路径或 glob。实现细节上若当前运行上下文携带 TinyAgents 的 workspace 描述符则以描述符中的workspace.root作为工作目录否则回退到工具构造时传入的workspace_dir当 diff 为空时返回No changes found.命令失败时返回 stderr 错误信息。这意味着 Critic 既可以评审正在编辑的未提交改动也可以评审某个分支或历史提交引入的变更。2.2 run_linter双语言 linter 门禁run_linter.rs 支持linter参数枚举值为clippyRust、eslintTypeScript/JavaScript与auto根据项目文件自动探测默认值并可通过path参数限定检查范围。这与仓库实际使用的工具链完全吻合——Rust 侧使用cargo clippy见 Cargo.toml 及 CI 脚本 scripts/ci/rust-coverage-changed.sh前端使用 ESLint见 eslint.config.js。返回值包含警告与错误供 Critic 结合 prompt 中的Be specific规则引用具体行号。2.3 run_tests测试套件验证run_tests.rs 支持runner参数枚举值为cargo_testRust、vitestTypeScript/JavaScript与auto默认自动探测返回通过/失败及输出。这与仓库测试体系一致Rust 侧遍布tests/下的*_e2e.rs集成测试与单元测试前端则有 app/vitest.config.ts 支撑的 Vitest 测试如 AppRoutes.guards.test.tsx。2.4 file_read上下文只读探查Critic 通过file_read读取项目文件以获得评审上下文例如被评审文件的周边代码、SOUL.md 项目原则等。该能力与其余三个工具一样均为只读配合sandbox_mode read_onlyCritic 从工具层到沙箱层都被双重约束为只能读、不能改。三、Review Checklist五维评审清单prompt.md 中 Critic 的评审清单按优先级从高到低分为五个维度这既是 LLM 的推理框架也是可被测试与运维复用的评审规范Security安全—— SQL 注入、XSS、命令注入、硬编码密钥、OWASP Top 10。OpenHuman 的 Rust 核心对安全尤为重视仓库中 src/openhuman/security 目录158 个 Rust 文件与 SECURITY.md、docs/features/privacy-and-security.md 共同构成安全基线Critic 的评审可对照这些文档进行合规性核查。Correctness正确性—— 边界条件、off-by-one 错误、null/None 处理、竞态条件。OpenHuman 核心是异步 Rust大量async/tokio并发与竞态是真实风险点例如 read_diff.rs 中tokio::process::Command的异步执行本身即是一个并发正确性的观察样本。Style风格—— 命名规范、代码组织、与既有模式的一致性。Tests测试—— 新路径是否被覆盖既有测试是否仍然通过这与run_tests工具直接呼应也与仓库 TEST-COVERAGE-MATRIX.md 的覆盖率治理目标一致。SOUL.md compliance项目原则遵从—— 代码是否与项目核心原则对齐。SOUL.md 是 OpenHuman 的产品人格与原则文件位于 app/src/SOUL.md同时存在 根目录 SOUL 相关内容 所描述的 IdentitySection 注入机制中Orchestrator 注释说明 SOUL.md 作为产品人格由所有选择加入的 Agent 共享。该清单的优先级顺序安全 正确性 风格本身就是一种可执行的决策树确保 LLM 在上下文预算有限时优先上报最严重的问题。四、Rules四条行为铁律prompt.md 中的 Rules 部分是 Critic 输出质量的直接约束Be specific必须具体—— 示例对比第 42 行SQL 字符串拼接可注入优于代码可能有安全问题。这要求 Critic 的结论必须落到文件、行号与具体模式上与read_diff返回带行号 hunk 的能力闭环。Prioritise按优先级上报—— 先报关键问题安全 正确性 风格与五维清单的顺序一致。Be constructive建设性—— 不仅要指出问题还要给出修复建议。这与对抗式但非敌对的定位一致Critic 的目标是让代码变好而不是刷存在感。Read-only只读—— 只评审、永不修改代码发现结果上报给 Orchestrator。这是 Critic 与 code_executor写代码的执行代理之间的根本分工边界。五、agent.toml配置语义逐项拆解Critic 的 agent.toml 是该子代理的行为配置全集逐项解读如下配置项值含义idcritic内置 Agent 唯一标识供 loader、Orchestrator 子代理白名单引用display_nameCritic展示名delegate_namereview_code由 Orchestrator 委托时合成的delegate_*工具名when_to_useAdversarial reviewer — reviews diffs and code against project rules...该文本会被用作委托工具的 LLM 可见描述指导 Orchestrator 路由temperature0.4较低的采样温度偏向稳定、可复现的评审输出max_iterations5单次委托的最大工具循环迭代次数防止评审无限发散max_result_chars8000评审结论回流 Orchestrator 的最大字符数约 2000 token与 planner/researcher 等其他子代理上限一致防止超长 diff 产生的无界评论污染 Orchestrator 上下文注释引用 issue #4099sandbox_moderead_only沙箱只读模式运行时层面禁止写操作omit_identitytrue跳过 IdentitySection不注入 SOUL.md / ROLE.md 身份段omit_memory_contexttrue不注入记忆上下文保证评审基于当前工作区事实而非历史记忆omit_safety_preambletrue跳过安全前言模板提示词保持精简[model] hintagentic提示运行时选用具备工具调用agentic能力的模型[tools] named[read_diff, run_linter, run_tests, file_read]工具白名单仅暴露评审必需的四项能力其中三个omit_*标志的选择非常讲究Critic 需要的是纯粹基于当前 diff 与代码事实的对抗式评审因此刻意去掉身份注入、记忆注入与安全前言避免 LLM 被历史偏好或冗长前言带偏max_result_chars则从架构层面防止评审结论失控回流。六、系统提示词装配prompt.rs 的拼接机制Critic 的最终系统提示词并非直接使用prompt.md而是由 prompt.rs 在运行时动态装配通过include_str!(prompt.md)将原型提示词编译进二进制赋值给常量ARCHETYPE依次追加四个动态段render_user_files(ctx)—— 用户文件注入段对应 PROFILE.md / MEMORY.md见 render_helpers_part_01.rs为空时跳过render_tools(ctx)—— 按当前工具白名单渲染的## Tools目录render_helpers_part_01.rsrender_workspace(ctx)—— 工作目录与文件列表边界段render_helpers_part_01.rs每个段之间以空行分隔最终返回完整的系统提示词。prompt_tests.rs 中的build_returns_nonempty_body测试构造了最小化的PromptContext空工具集、空可见工具名、PFormat 工具调用格式断言build()返回非空正文——这验证了即使在没有工具、没有记忆等运行时上下文的极端情况下Critic 的系统提示词骨架依然完整可生成。七、委托链路Orchestrator 如何调用 CriticCritic 不会自主启动它由 OrchestratorMaster Agent按需委托。相关证据链orchestrator/agent.toml 的[subagents] allowlist将critic列入白名单。根据文件注释collect_orchestrator_tools会在 Agent 构建期读取该白名单为每个条目合成一个delegate_*委托工具工具名取自目标的delegate_name此处即review_code工具描述取自目标的when_to_use。因此 Orchestrator 的 LLM 在函数调用层就能看到review_code这个一等公民工具。orchestrator/prompt.md 的委托路由表中明确写着 Code review →review_code并在规则中说明需要独立评审independent review时使用review_code或相关 worker评审 / 校验 / 批准 / 校对 X然后再定稿这类结果门控工作必须同步执行——通过阻塞式delegate_*或spawn_async_subagent加blocking: true保持回合打开直到子代理返回从而杜绝定稿后评审才完成的空转。委托时的结构化交接信封prompt/objective/evidence/constraints/must_not_assume/expected_output/citation_requirement由 Orchestrator 填充Critic 作为子代理没有会话记忆完全依赖信封中的任务描述工作——这与omit_memory_context true的配置互为表里。八、从源码看 Critic 的三大设计原则综合 prompt.md、agent.toml 与工具实现可以归纳 Critic 子代理的三大设计原则只读即安全边界sandbox_mode read_only 四个PermissionLevel::ReadOnly工具 prompt 中的 Read-only 规则三层叠加确保评审行为零副作用。这与 src/openhuman/sandbox 模块的沙箱治理一脉相承。结论必须可回流、有界回流max_result_chars 8000约束评审结论体量delegate_name review_code保证结论沿委托链流回 Orchestrator 后被二次蒸馏Orchestrator prompt 规定每个委托回复都必须蒸馏避免原始工作笔记进入最终答复。对抗性来自约束而非情绪Critic 的对抗体现在评审清单安全 正确性 风格、具体行号引用与建设性修复建议上是通过提示词工程构造的批判性推理框架而不是无差别挑刺。九、如何观察与验证 Critic 的行为如果你想在自己的 OpenHuman 实例中观察 Critic 的实际运行触发方式在对话中明确要求review_code语义的任务例如请评审我当前的改动、在定稿前先让评审代理检查这段代码Orchestrator 会按路由表委托review_code代码级验证阅读 prompt_tests.rs 与 loader_tests 可了解加载与装配的测试覆盖工具行为验证三个工具的独立测试位于 read_diff_tests.rs、run_linter_tests.rs 以及 run_tests 对应的测试文件调优入口如需调整 Critic 的评审强度或上下文行为可修改 prompt.md评审清单与规则与 agent.toml温度、迭代上限、结果回流上限、工具白名单。十、结语Critic 是 OpenHuman多智能体协作、专职分工架构的一个典型样本一份 25 行的原型提示词定义了角色、能力、评审清单与行为规则一份 21 行的agent.toml从沙箱、温度、迭代、结果回流四个维度锁死行为边界四只只读工具为其提供信息获取通道而 Orchestrator 的委托机制与结构化交接信封负责把它安全地编排进整个工作流。理解 Critic也就理解了 OpenHuman 中所有内置 Agent 的通用构建范式——prompt.md定质、agent.toml定界、工具白名单定权、委托链定流。【免费下载链接】openhumanOpenHuman is an open source personal AI for Mac, Windows and Linux — local-first memory, agent orchestration, and deep research.项目地址: https://gitcode.com/GitHub_Trending/op/openhuman创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考