NemoClaw Advisor 共享工具库解析PR Review Advisor 的确定性审查基础设施【免费下载链接】NemoClawRun agents like Hermes, LangChain Deep Agents, and OpenClaw more securely inside NVIDIA OpenShell with managed inference项目地址: https://gitcode.com/gh_mirrors/ne/NemoClaw导读tools/advisors/是 NemoClaw 仓库中为模型驱动的审查顾问model-backed advisor提供共享实现工具包的目录其消费方是tools/pr-review-advisor/下的 PR Review Advisor 专家入口。本文基于仓库中的 tools/advisors/README.md 与该目录源码梳理这套基础设施的职责边界、核心模块与信任模型重点讲解仓库受限只读工具、确定性回合协议、风险计划与 E2E 推荐机制以及staging-brev-launchable焦点映射的行为所有者规则。读完本文你将理解 NemoClaw 如何在不授予顾问任意写权限、不依赖仓库开发依赖的前提下让 LLM 顾问产出可审计、可复现的 PR 审查结论。目录定位与职责边界tools/advisors/本身不提供独立的命令行入口它是被tools/pr-review-advisor/PR Review Advisor 专家入口复用的共享层。README 明确列出该目录提供的七类能力仓库受限、只读的 Pi SDK 会话工具repository-confined, read-only Pi SDK session tools确定性回合作用域上下文工具与回合校验deterministic turn-scoped context tools and turn validationGit diff 与元数据辅助Git diff and metadata helpersJSON 提取与净化辅助JSON extraction and sanitization helpers产物与文件 I/O 辅助artifact and file I/O helpersGitHub API 与粘性评论辅助GitHub API and sticky-comment helpers提供给 PR Review Advisor 专家的受信任 E2E 清单trusted E2E inventory。目录下共 13 个 TypeScript 模块与上述能力一一对应模块职责repo-read-only-tools.mts仓库受限只读工具read/grep/find/ls与结果字节上限控制turn-protocol.mts回合类型定义、工具清单解析、回合流校验与修复提示risk-plan.mts风险计划RiskPlan构建风险族、必选 Job/Target 映射e2e-recommendations.mts受信任 E2E 推荐清单与结果归一化e2e-text.mtsE2E 相关文本形状识别git.mtsdiff、diff-stat、commit 列表、head SHA 读取github.mtsGitHub REST/GraphQL 客户端与粘性评论 upsert/删除json.mtsJSON 提取、枚举校验、记录/字符串数组净化canonical-json.mts规范化 JSON 序列化http-dispatcher.mtsHTTP 调度辅助io.mts参数解析、产物路径规划、JSON 读写session.mts会话相关辅助provider-constants.mts提供商常量定义从源码结构可以推断这套库的设计目标有两个一是把模型可能出错的部分自由文本、任意文件访问、任意工具调用约束到确定性代码的边界之内二是让生产环境的顾问运行不依赖仓库的开发依赖。职责边界只推荐不派发README 特别强调了一个关键边界E2E 清单inventory只是给 PR Review Advisor 专家提供审查上下文的它不会派发任务也不会决定合并就绪与否。当维护者需要为一个 PR 运行真实 E2E 时需要通过 .github/workflows/e2e.yaml 显式运行并遵循维护者 E2E 流程处理候选资格、凭据、部署与清理。以往 PR 上的 E2E 检查上下文仍然只具有建议性质advisory。这一点在代码层面有直接体现e2e-recommendations.mts 中normalizeE2eCoverageResult对模型输出做了严格的净化sanitize自由格式的模型散文永远不会被保留在归一化结果中源码注释明确写道Free-form model prose is never retained in the normalized E2E result模型只能从受信任标识符集合中挑选newE2eRecommendations始终返回空数组置信度low在存在必选测试或风险族时会被强制提升为medium。仓库受限只读工具repo-read-only-tools.mts该模块是顾问会话安全的基石。它基于earendil-works/pi-coding-agentPi SDK提供的read/grep/find/ls四个工具定义做二次封装核心逻辑是createRepoConfinedReadOnlyTools(cwd, onRead?, additionalRoots?)路径守卫RepoPathGuardcreateRepoPathGuard将候选路径解析为词法路径与真实路径realpath同时校验候选路径必须落在工作区根以及显式声明的附加根之内。守卫会拒绝前缀、Unicode 空白字符、~展开后越界以及符号链接重定向到工作区之外的路径对应canonicalRepoReadPath。字节上限MAX_ADVISOR_TOOL_RESULT_JSON_BYTES 16 * 102416 KiBboundAdvisorToolResult对序列化后的工具结果做二分截断并在截断提示中给出offset续读指引如[Advisor session limit reached. Use offsetN to continue.]确保每次工具返回都落在会话安全上限内。只读观察回调onRead回调会记录读取的路径、起始 offset、结束 offset、文件大小与是否读到文件末尾AdvisorReadObservation这些观测事件是回合流校验的输入之一。从代码可以推断onRead产生的观测会被上层session/turn逻辑消费用于实现必须先读取指定证据文件再输出分析之类的硬性回合约束。确定性回合协议turn-protocol.mtsturn-protocol.mts定义了顾问与模型之间单次回合turn的确定性契约核心类型是AdvisorPromptTurn其字段构成了一套可组合的约束语言字段含义name/prompt回合名与提示词contextToolResults本回合暴露的确定性上下文工具零参数必调工具内容来自受信任代码而非模型activeToolNames/requiredToolNames本回合可用的附加工具 / 必须成功完成的工具requireToolsBeforeText必须先完成才能输出文本的工具含上下文工具requiredReadOneOfPaths输出分析前必须真实读取的路径之一requireAssistantText回合结束时必须存在非空分析文本atomicTerminalToolName原子终结工具必须是本回合唯一的活动与必选工具禁止上下文、文本要求与其他工具terminalSubmitToolName终态提交工具可跟随上下文、读取、散文与其他草稿工具最多一次成功resolveAdvisorTurnTools会对回合配置做编译期式校验未注册工具、原子终结工具与终态提交工具同时出现、原子终结工具附带上下文或文本要求等都会直接抛错。advisorTurnFlowErrors则基于事件流text/read/tool_start/tool_end做运行时校验例如必须提交的分析缺失omitted required analysis在必调工具完成前输出了文本emitted text before ... completed终态提交工具的成功次数不是恰好 1 次、成功后仍有活动non-submit activity after successful ...。模块还提供三类修复repair协议assistantTextRepairPrompt纯散文续写、atomicTerminalRepairPrompt纯工具续写、terminalSubmitRepairPrompt恰好一次成功提交续写。README 对此的概括是修复尽可能保留已完成的回合——缺散文给一次纯散文续写缺原子提交给一次纯工具续写终态提交允许围绕一次成功存在已了结的失败尝试或给予一次续写。这把模型行为不可控压缩成了有限、可审计的修复路径。风险计划与确定性 E2E 推荐risk-plan.mts与e2e-recommendations.mtsRiskPlan 结构risk-plan.mts导出版本号为RISK_PLAN_VERSION 25buildRiskPlan接受headSha与changedFiles输出包含以下字段的RiskPlanversion/headSha/planHash版本、提交 SHA 与 SHA-256 计划摘要planDigest对除 hash 外的全部字段做 SHA-256changedFiles/tier变更文件集合与整体风险层级RiskTier 0 | 1 | 2 | 3families命中的风险族RiskPlanFamily每个族携带summary、tier、matchedFiles、invariants不变量、requiredJobs与requiredTargetsrequiredJobs/requiredTargets汇总后的必选 Job 与 Target 列表。风险规则RISK_RULES是声明式的每条规则定义匹配函数、风险层级、不变量与必选 Job。例如lifecycle-statetier 2onboarding/sandbox 状态必须在持久化元数据、上报状态与真实运行时之间收敛必选onboard-resume、onboard-repairgateway-topologytier 2网关拓扑变化必须保持沙箱可见主机地址位于沙箱网络子网之外并使用单一地址权威inference-policytier 2推理选择、可达性与网络策略必须在真实主机到沙箱边界一致必选inference-routing、network-policycredentials-securitytier 3凭据与安全边界变化必须保持保密、净化与失败关闭fail-closed策略e2e-control-planetier 3E2E 选择、执行与证据变化必须保持可信派发与失败关闭的结果分类缺失/跳过/畸形/不匹配的证据都不能产生通过的闸门managed-image-multiarch与managed-image-protected-runtimetier 3受保护托管镜像必须在每个支持架构上以精确的 base 与候选 digest 构建并直接启动全部发货 Agent。受信任 E2E 清单与归一化e2e-recommendations.mts从受信任的.github/workflows/e2e.yaml、E2E 目标目录E2E_TARGET_CATALOGUE来自 tools/e2e/target-catalogue.mts与免凭据测试清单tools/e2e/credential-free-tests.mts构建trustedE2eRecommendationInventory()输出workflow: e2e.yaml、fanoutId: e2e-allselectorTypes: [all, target, job]allowedJobIds可从E2E_JOB: 1注释等信号提取的、可被 PR 计划自动选中的 JobmanualOnlyJobIds仅限人工控制的 Job如inference-routing、managed-image-protected-runtime定义于PR_E2E_MANUAL_CONTROLLER_JOB_IDSliveSupportedTargetIds注册表中受支持的真实运行目标。关键的信任设计在归一化路径中normalizeE2eTargetAdvisorResult中被分析的 PR 工作流文本被视为不可信输入——它可以解释为什么某个变更测试没有可信选择器但绝不能引入受信任工作流与目录之外的 Job源码注释The analyzed workflow is untrusted input... it must never introduce one absent from the trusted workflow or catalogue。同时 README 强调清单读取器只使用 Node.js 内建模块与仓库内已检入的 TypeScript 模块因此生产顾问不需要 TypeScript、Vitest 等仓库开发依赖。未接线测试的兜底e2e-recommendations.mts还实现了未接线 live 测试检测如果变更中的test/e2e/live/*.test.ts既没有对应 Job 接线、也没有出现在工作流文本中则findUnwiredFreeStandingLiveTests会将其识别出来missingLiveWiringReason会给出提示——例如新 E2E 测试未接入 e2e 工作流无法被派发需要先添加免凭据标签、独立 Job 或类型化 live 目标才能把 PR 视为可运行 E2E。staging-brev-launchable焦点映射详解README 花费最多篇幅描述的是确定性焦点映射对staging-brev-launchable行为所有者的推荐规则这些规则全部实现在risk-plan.mts的BREV_LAUNCHABLE_FILES、BREV_LAUNCHABLE_MODULE_PREFIXES与BREV_LAUNCHABLE_SCENARIO_FILE中1. 网关发现与所有权、共享转发恢复或启动、连接/探针入口文件级精确匹配BREV_LAUNCHABLE_FILES是一个显式文件集合包括网关绑定与管理src/lib/onboard/gateway-binding.ts、gateway-management.ts、gateway-ownership.ts、gateway-teardown-authority.ts、gateway-host-runtime.ts仪表盘转发src/lib/onboard/agent-dashboard-forward.ts、dashboard-forward-control.ts、dashboard.tsOpenShell 适配器src/lib/adapters/openshell/command-execution.ts、forward-cli.ts、forward-runtime.ts、forward.ts转发恢复与进程恢复src/lib/actions/sandbox/forward-recovery.ts、process-recovery.ts、status/process-recovery.ts连接与启动就绪src/lib/actions/sandbox/connect.ts、terminal-connect-probe.ts、launch-readiness.ts端到端场景文件test/e2e/live/launch-agent-turn.ts与tools/e2e/brev-launchable-e2e.sh。2. 运行时模块前缀含新增嵌套 helperBREV_LAUNCHABLE_MODULE_PREFIXES包含两个前缀凡是变更文件以这些前缀开头且通过isRuntimeRelevant过滤排除单元测试、文档、支持单元测试等即视为命中src/lib/onboard/gateway-binding/src/lib/actions/sandbox/launch-readiness/3.full-e2e场景与配套源文件BREV_LAUNCHABLE_SCENARIO_FILE是一个正则/^test\/e2e\/(?:fixtures|live)\/full-e2e(?:[./-].*)?\.[cm]?[jt]s$/它匹配test/e2e/live/与test/e2e/fixtures/下以full-e2e开头的场景及其配套文件包括full-e2e/目录中的新增 helper。匹配边界与不可移除性README 明确了几条边界规则代码中同样可见模块匹配排除source-unit tests 与文档场景匹配包含live tests 与 source helpers但排除文档与支持单元测试isRuntimeRelevant的实现docs/、fern/、测试目录、*.test.*、*.md/*.mdx/*.txt一律不视为运行时相关同名兄弟模块与 Hermes-only 相邻实现不触发映射——README 写明 Similarly named sibling modules and Hermes-only neighboring implementations do not trigger this mapping现有生命周期推荐保持选中且顾问specialist输出不能从确定性计划中移除 Brev。在buildRiskPlan中焦点映射产生的 Job 以focused-e2e风险族身份合入requiredJobs而normalizeFocusedE2eJobs对选择器的 id 有正则约束/^[A-Za-z0-9][A-Za-z0-9_-]*$/u且要求每个匹配文件必须真实存在于changedFiles中否则抛错——这保证了映射结果始终是受信、确定的。运行前提与操作约束README 特别提醒staging-brev-launchable推荐需要完整运行时场景而staging-brev-launchable-identity只能证明镜像身份image identity。因此实际运行时由已授权的维护者在main上通过受信任工作流选择jobsstaging-brev-launchable且targets必须为空不要将jobsstaging-brev-launchable与其他 Job ID 组合Do not combine that selector with other job IDs候选资格、凭据、部署与清理遵循维护者 E2E 流程该推荐本身不派发运行、不授权部署——它只回答这个 PR 应该跑什么 E2E 覆盖。Git、GitHub、JSON 与 I/O 辅助Git 辅助git.mtsgetChangedFiles、getDiff、getDiffStat、getCommits在git diff上采用双形式容错先尝试三原点形式${base}...${head}需要本地 merge base失败后再尝试两点形式${base}..${head}以兼容缺少本地 merge base 的检出环境。getDiff使用--find-renames --find-copies --unified80以保留足够的重命名/复制与上下文信息getHeadSha通过git rev-parse获取精确提交 SHA。GitHub 辅助github.mts提供 REST 与 GraphQL 客户端以及两个高价值操作upsertStickyComment按 marker 在 PR 上查找既有评论并更新PATCH不存在则创建POST——这就是粘性评论机制用于让顾问结论在同一位置持续更新而非不断新增评论deleteBotOwnedStickyComments仅删除github-actions[bot]所有、首行匹配指定 marker 的评论避免误删人工评论。所有请求携带X-GitHub-Api-Version: 2022-11-28错误处理区分http非 2xx与decode响应不是合法 JSON并附带x-github-request-id便于排障。JSON 与 I/O 辅助json.mts的extractJson按四种候选依次尝试解析原始文本、json 围栏块、tag标签块、首尾花括号平衡截取这覆盖了 LLM 输出中最常见的 JSON 包裹形式enumValue、recordItems、stringArray、stringOrUndefined提供类型安全的净化入口。io.mts的advisorArtifactPaths规划了六类产物路径prompt、raw、result、finalResult、summary、sessionHtmlparseArgs将--kebab-case参数规范化为驼峰键parsePositiveInt提供正整数回退。信任模型与工作流集成README 给出了两条重要的运维约定GitHub workflows 必须从受信任的ADVISOR_DIR检出执行顾问入口而 PR 工作区只是惰性的分析数据PR workspaces remain inert analysis data only。这保证了顾问代码包括上述所有辅助模块永远来自仓库可信检出而不是来自被分析 PR 的内容——在e2e-recommendations.mts中这一点体现为TRUSTED_REPO_ROOT与process.cwd()的区分读取受信任工作流用前者读取 PR 变更来源用后者。生产顾问不依赖仓库开发依赖TypeScript、Vitest 等清单读取器只用 Node.js 内建模块与已检入模块。这与仓库中 tools/pr-review-advisor/ 的专家入口specialists/下 9 个专家定义、blocker-gate.mts、deterministic-context.mts、specialist-catalog.mts等配合构成了确定性外壳 模型推理内核的整体架构。与这套顾问基础设施配套的工作流包括 .github/workflows/pr-review-advisor.yaml顾问执行入口与 .github/workflows/e2e.yaml维护者显式运行 live E2E 的受信任工作流风险计划本身的正确性由 test/automation/pull-requests/ 下的测试保障risk-plan.mts源码注释提到test/automation/pull-requests/pr-risk-plan.test.ts持续守护清单的有意且有界。小结tools/advisors/用约 13 个 TypeScript 模块为 NemoClaw 的模型驱动审查体系提供了四层确定性保障访问边界只读工具被路径守卫与 16 KiB 字节上限双重约束顾问无法越出仓库、无法产生失控输出行为边界回合协议把读证据 → 调工具 → 输出分析 → 终态提交编排为可校验的事件流并提供三类有限修复通道内容边界风险计划与 E2E 清单由受信任代码确定性地从变更文件推导模型只能从受信标识符中挑选且无法移除 Brev 等确定性推荐运行边界生产执行不依赖开发依赖工作流只从可信检出运行顾问代码。这套设计回答了如何让 LLM 参与代码审查而不失可控性的问题模型的自由度被严格限定在分析与选择受信标识符之内凡是可能影响正确性、安全性与可审计性的环节全部由确定性代码接管。【免费下载链接】NemoClawRun agents like Hermes, LangChain Deep Agents, and OpenClaw more securely inside NVIDIA OpenShell with managed inference项目地址: https://gitcode.com/gh_mirrors/ne/NemoClaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考