Langfuse 仓库自治 Agent 上线审查清单:为 LLM 驱动的 GitHub Actions 建立安全发布基线
Langfuse 仓库自治 Agent 上线审查清单:为 LLM 驱动的 GitHub Actions 建立安全发布基线
导读
本文基于 Langfuse 仓库 .agents/skills/create-repo-agent 技能体系中的核心审查清单(references/review-checklist.md)展开,系统梳理仓库自治 Agent(repo-owned autonomous agent)在合并上线前必须满足的安全与工程验收项。阅读本文后,你将掌握:为什么"由 LLM 驱动的 GitHub Actions"必须采用"只读审计 + 独立发布"的两阶段架构、如何用凭据模型与工具白名单收敛攻击面、如何在发布前对 diff 做独立于 Agent 的强制校验,以及修改 .agents/** 后仓库要求的验证命令。适用于设计、实现或评审任何由 LLM 生成 PR 的定时/手动维护 Agent。
背景:为什么 LLM Agent 比普通 CI 更危险
在 Langfuse 的安全标准(security-standards.md)中,开篇就明确:这些标准有意比普通 CI 工作流更严格,因为 LLM 步骤会消费不受信任的指令、网页、源文件以及自身此前的输出。Langfuse 的威胁模型(threat model)把以下内容一律视为不可信输入:
- 供应商网页、GitHub Issue、PR 评论、发布说明;
- 生成文件、包脚本、之前的 Agent 输出。
攻击面包括:提示注入诱导 Agent 泄露密钥、放宽自身权限、编辑无关文件、打开更广的网络访问、在格式噪声中隐藏恶意改动;以及 Agent 即使出于善意也可能犯错——因此必须由独立于 Agent 的校验兜底,捕捉错误文件、超大 diff、非法生成产物和缺失的领域校验。自改进(self-improvement)本质上是"代码执行策略变更",绝不豁免于评审、路径白名单与安全不变量。
一、审查清单总览:十类检查项
审查清单(review-checklist.md)将合并前检查组织为十个维度:
- Block Merge If(一票否决项)
- Scope And Objective(范围与目标)
- Credentials And Permissions(凭据与权限)
- Tool Allowlist(工具白名单)
- Prompt And Output(提示词与结构化输出)
- Diff And Validation(Diff 与校验)
- Publish Path(发布路径)
- Self-Improvement(自改进)
- Operational Fit(运行适配性)
- Verification Commands(验证命令)
下文逐一展开,并结合 workflow-blueprint.md 与 create-repo-agent 技能(SKILL.md)中的默认架构说明其落地方式。
二、Block Merge If:十项一票否决条件
以下任一条件成立,即阻止合并(Block Merge),这是清单中优先级最高的部分:
| 编号 | 否决条件 | 对应架构原则 |
|---|---|---|
| 1 | LLM 步骤持有可写 GitHub token、PAT、GitHub App token、SSH key、云凭据、包发布 token 或 OIDC token | 写凭据只允许出现在 publish job |
| 2 | LLM 步骤拥有任意 shell、宽泛解释器、包管理器、curl/wget/gh/git push 或宽泛网络访问 |
工具按最小权限白名单化 |
| 3 | 工作流仅依赖提示词作为文件范围、命令范围或发布的唯一护栏 | 强制在 Agent 之外做文件/命令限制 |
| 4 | Diff 校验忽略未跟踪文件(untracked files) | git ls-files --others --exclude-standard 必须参与 |
| 5 | 工作流整体暂存目录而非经过校验的文件清单 | 只 git add 校验过的文件 |
| 6 | 发布路径可能推送白名单未覆盖的文件 | 推送前再次逐文件核验 |
| 7 | 自改进可绕过路径白名单、不变量提示词与人工 PR 评审去修改安全边界 | 自改进与普通编辑走同一套允许清单与评审 |
| 8 | 手动输入在校验前被插值 | 先校验、后使用 |
| 9 | workflow_dispatch 的 choice 值使用 YAML 布尔型标记(off/on/yes/no/true/false) |
使用 YAML 安全的枚举值(详见第四节) |
| 10 | Agent 可在没有明确任务与专项评审的情况下改动生成文件、依赖锁文件、包管理器配置、CI 信任设置或密钥 | 生成文件/锁文件一律冻结 |
其中第 9 条是一个容易被忽略的 GitHub Actions 陷阱:workflow_dispatch 的 choice 值若写成 off、on、yes、no、true、false,GitHub 可能将其解析或渲染为布尔值,导致输入语义漂移。workflow 蓝图给出的替代方案是使用 disabled、no_changes、mock_allowlisted_diff 这类安全枚举。
三、范围与目标:让维护 Agent"小"而"可预测"
- 目标足够窄:足以支撑定时(scheduled)或手动分派(manually dispatched)的维护 Agent。
- 无变更路径必须显式定义且视为成功:no-change 是合法结果,不是失败。
- 允许文件是精确路径或窄 glob:蓝图中的提示词模板用"Allowed edit surface:
<exact file>/<restricted glob>"显式声明编辑面。 - 为业务逻辑配备领域技能或参考文档:例如定价类 Agent 必须同时使用
add-model-price技能(见 SKILL.md 的说明)。 - PR 标题、分支名、评审人行为必须是确定性的:避免每次运行产生随机命名,方便维护者跟踪与去重。
四、凭据与权限:读审计、写发布
- 顶层/审计 job 权限最小化,通常是
contents: read。 - checkout 使用
persist-credentials: false,并设置最小必要的fetch-depth。 - LLM 步骤只接收模型 API key,以及(若 action 需要)只读的
${{ github.token }}。安全标准特别强调:要显式把github_token: ${{ github.token }}传给那些会自行从环境发现 token 的 LLM action,同时保持 job 权限只读。 - 写凭据只存在于 publish job:审计阶段没有
secrets.GH_ACCESS_TOKEN、写作用 PAT、GitHub App 私钥、SSH key、云凭据、包注册表 token 或 OIDC token。 - 密钥按步骤(step)粒度注入,不放入宽泛的 job 级
env,除非有具体理由。 - 禁止上传密钥值、环境变量 dump 或完整敏感日志。
id-token: write缺省不得出现,除非有经评审的 OIDC 信任边界且任务确实需要。
蓝图中还要求:env 只放分支名与 PR 标题,绝不把密钥放进顶层 env。
五、工具白名单:没有宽泛 Bash
清单要求工具收敛到以下形态:
- 文件工具限定精确路径或窄 glob;
- 网络工具限定官方域名(domain-scoped
WebFetch); - shell 工具是精确的、确定性的验证器命令;
- 禁止宽泛的
Bash(node:*)、Bash(python:*)、Bash(curl:*)、Bash(gh:*)、Bash(git:*)以及包管理器访问; - Agent 不能 push、创建 PR、安装依赖、发布包、查看全部环境变量或修改 git config。
安全标准进一步细化:即使连 cat、sed、grep、rg、jq、env、printenv、ps、ls 这类"只读"shell 命令也应避免,文件读取应走作用域化的 read 工具,除非该精确命令确实必要且安全。一个可接受的精确命令示例是 date -u +%Y-%m-%dT00:00:00.000Z 这类无敏感性的确定性命令。
推荐的工具组合(按需添加):
- 精确
Read路径(源文件、技能文档、启用自改进时的工作流文件); - 精确
Edit路径(可变文件); - 仅对窄路径下经批准的新文件开放
Write(如技能参考 markdown); - 领域限定的
WebFetch(官方供应商文档与定价页); - 精确的确定性验证器命令。
六、提示词与结构化输出:引导而非设防
提示词(prompt)必须覆盖:允许读取/编辑的文件、可用的官方来源、不可违反的硬约束、完成前必须运行的验证器、期望的结构化输出 schema,以及任何变更所需的证据(源 URL、换算计算等)。
蓝图给出的提示词模板包含以下固定小节:任务目标、Allowed edit surface、带编号的任务清单、Hard constraints(不改生成文件、不改包管理器文件、不执行 git push/创建 PR、不添加宽泛通配行为、为工作流自改进保留安全不变量)、Final response(无 diff 时报告 no changes 与 unresolved findings;有 diff 时列出变更的业务对象、源 URL、计算过程、自改进项与验证命令)。
关键原则(清单原文):"提示词只是引导,不是执法层"(Do not rely on the prompt as the enforcement layer)。工作流仍必须在文件、命令、token 与发布边界上强制执行。结构化输出 schema 应包含 summary、changed objects、unresolved findings、validation、self-improvement 等字段,并在 job summary 中以可评审格式渲染。
workflow_dispatch 输入校验的补充规则:
- 模型名、模式、环境等枚举优先用
type: choice; - 自由数字输入先用正则与数值范围校验;
- 会成为 CLI 参数的字符串输入须对照允许清单正则或 choice 集合校验;
- 一次性指令输入(manual debugging 用)可允许,但必须校验长度与控制字符,并渲染到明确标注的低优先级 prompt 小节,不得覆盖硬约束、工具限制、凭据边界、校验门与发布边界;
- 未校验的手动输入不得插值进 shell 命令、JSON、分支名、文件路径或 LLM CLI 参数。
七、Diff 与校验:独立于 Agent 的强制关卡
清单要求在 Agent 完成后、发布前执行一整套独立的 diff 校验序列:
- 同时计算 tracked 与 untracked 变更:changed files 由
git diff --name-only与git ls-files --others --exclude-standard合并去重得到(蓝图给出了sort -u的 mapfile 片段); - 每个变更文件在暂存前后都对照同一个锚定 allowlist 校验;
- 未跟踪文件先
git add -N(intent-to-add)再参与 diff 检查; - 对变更文件运行
git diff --check; - 变更行数上限拒绝非外科手术式(non-surgical)的大 diff——定价类维护任务的行数上限应当很小;
- 暂存前运行领域专属验证器;
git add后将暂存 blob 与工作区文件比对,捕捉 clean/smudge filter、生成文件变异或暂存意外;- 对机器可读文件(尤其是 JSON)从
git show ":path"校验暂存 blob; - 提交前运行
git diff --cached --check; - 本地提交后、生成补丁前再次运行验证器。
八、发布路径:补丁传递,而非工作区传递
发布(publish)是整个架构中唯一拥有 GitHub 写权限的环节,清单约束如下:
- 只有校验通过后才运行 publish job;
- publish job 不调用 LLM(安全标准:publish job 不得运行 LLM,也不得处理新的不可信网络内容);
- 机器人提交路径禁用 git hooks;
- publish job 把校验过的补丁产物应用到触发基线 commit,而不是一个含有未校验文件的可变工作区(蓝图:在干净的临时仓库中按触发 commit SHA 精确检出,
git am --3way应用补丁); - 推送前重新检查已应用 commit 的变更文件是否仍符合同一路径白名单,并运行
git diff --check HEAD^ HEAD; - 机器人分支只应被有意强推(force-push)到预期仓库;
- 复用已有 PR 而非创建重复 PR;
- 评审人请求失败不致命(
|| true),避免缺失评审人权限导致合法维护 PR 整体失败。
审计 job 内部提交的完整序列(蓝图):重新计算 changed_files → 重跑同一 allowlist → intent-to-add 未跟踪文件 → 重跑领域验证器与 git diff --check → 配置 bot 作者 → 禁用 hooks 创建分支 → 只暂存 changed_files → 用 git diff --cached --name-only 核对 → 比对暂存 blob 与工作区 → 从 git show ":path" 校验机器可读文件 → git diff --cached --check → git -c core.hooksPath=/dev/null commit --no-verify 提交 → 重跑验证器 → git format-patch -1 --stdout HEAD 生成补丁(仅当 allowlist 明确允许二进制文件时才用 --binary)→ 校验补丁非空 → 生成包含 scope、validation、diff stat 与 agent summary 的 PR body 产物。
九、自改进:安全边界上的受控进化
自改进(self-improvement)只有在工作流显式启用时才允许:
- 允许的自编辑文件必须具名(通常只有工作流自身与仓库自有的技能参考文件);
- 提示词列出必须保持不变的安全不变量(security invariants);
- diff 校验包含自编辑文件但不扩大到更宽路径;
- 结构化输出逐条列出每个 workflow 或 skill-reference 改进项;
- PR body 让评审人可见自改进内容;
- 未经直接、经评审的理由,不得放宽工具、token、权限或发布边界。
蓝图给出的"合理自改进"示例:新增新发现的官方文档域名、收紧模糊的提示词措辞、添加仓库中已存在的精确验证器命令、基于观察到的合法需求调整 max-turn 默认值或超时、增加提升可评审性的结构化输出字段。而"禁止用于自改进"的清单包括:放宽 shell 访问、授予审计 job 写权限、增加 OIDC 或包管理器访问、移除验证器或 allowlist、编辑无关工作流或生成文件。若某项改进会违反不变量,Agent 必须将其报告为 unresolved 而不是自行应用。
十、运行适配性:调度、预算与失败模式
- 调度频率不得超过供应商速率限制、模型成本与评审人注意力的承受范围;
- 用
timeout-minutes、max turns、max budget 约束失控循环(蓝图还建议在支持处设置 API timeout 与 shell timeout); - 手动分派输入既要足够排查问题,又不能使 Agent 任意化;
- 手动 dry-run 模式可跳过模型步骤、输出合成的结构化结果,并可选择生成一个白名单内的 mock diff,从而在不产生模型开销、不发布的前提下调试校验、补丁产物与 no-publish 路径;
- no-change 运行应当廉价且可读;
- 失败模式要为主持人保留足够的 summary 上下文,同时不暴露密钥。
dry-run 的工程要点(蓝图):dry-run choice 输入的默认值为 YAML 安全的 disabled 值;先用 if: <dry-run-mode> == 'disabled' 显式守卫 LLM action;mock 步骤写出与 LLM action 相同的结构化输出形状;提供 no-change 模式测试干净退出;提供 allowlisted mock-diff 模式测试 diff 校验、暂存、提交、补丁创建与产物上传;所有 dry-run 模式都跳过 publish job;summary 中显式标注合成输出,避免维护者把 mock 结果误认为真实审计。
十一、验证命令:修改后的必跑检查
清单把验证命令分为三级:
仅工作流(workflow-only)变更至少运行:
- YAML 解析或可用的 workflow linter;
- 对提取/静态检查出的内嵌 shell 脚本运行
bash -n; git diff --check。
.agents/** 变更额外运行(这三个命令在根 package.json 中已定义):
pnpm run agents:sync—— 对应node scripts/agents/sync-agent-shims.mjs,把.agents/config.json的规范配置投影生成各工具的发现文件(.claude/settings.json、.claude/skills/*、.cursor/mcp.json、.vscode/mcp.json、.mcp.json、.codex/config.toml等),并将共享技能投影到.claude/skills/;pnpm run agents:check—— 在 sync 之上追加--check-paths,解析每个AGENTS.md引用的路径,遇到损坏引用即失败(lint job 会运行它);- 新建或修改技能时运行 skill-creator 快速验证器。
领域文件变更:运行领域技能指定的领域验证器与定向测试。
补充说明(来自 .agents/README.md):pnpm install 的 postinstall 只运行 sync 与 shim 检查(--check),故意不运行路径校验——路径校验一旦失败会拖垮所有需要安装依赖的 CI job。另注意生成文件是提交为 symlink 而非本地生成(如根 AGENTS.md → .agents/AGENTS.md、每个 AGENTS.md 旁配套 CLAUDE.md shim),因此新增任何 AGENTS.md 都必须同时提交其生成 shim,否则 CI 失败。
十二、仓库内相关证据与延伸阅读
- 技能入口与工作流:.agents/skills/create-repo-agent/SKILL.md —— 8 步实现工作流与 6 条 Non-Negotiables(其中第 5 条"绝不依赖提示词作为唯一安全边界"与清单第 3 条否决项一一对应)。
- 安全标准全文:.agents/skills/create-repo-agent/references/security-standards.md —— 威胁模型、凭据模型、工具权限、diff 强制、发布边界、日志与产物、第三方 action 的 commit SHA 钉扎。
- 工作流蓝图:.agents/skills/create-repo-agent/references/workflow-blueprint.md —— 顶层形状、audit/publish 双 job、输入校验、提示词模板、diff 校验步骤、补丁准备与 dry-run 模式的完整 YAML 级落地细节。
- 本清单:
.agents/skills/create-repo-agent/references/review-checklist.md(合并前最终评审必读)。 - shim 同步脚本:scripts/agents/sync-agent-shims.mjs ——
agents:sync/agents:check的实际实现,含--check-paths路径解析逻辑。 - Agent 配置源与生成说明:.agents/config.json 与 .agents/README.md。
结语
Langfuse 的 Repo Agent Review Checklist 实质上是一套**"最小权限 + 独立强制 + 双阶段发布"**的可执行安全基线:凭据上"读审计、写发布",能力上"精确工具、无宽泛 shell",校验上"tracked + untracked 全量、暂存前后双重 allowlist、行数上限、领域验证器",发布上"补丁传递、禁用 hooks、推送前复核",自改进上"具名文件 + 安全不变量 + 人工评审"。遵循这份清单,可以让 LLM 驱动的维护 Agent 在无人值守运行时,即使面对提示注入与自身失误,也无法越过仓库的安全边界——这正是把 AI 代码贡献安全地接入持续维护流程的关键。