Langfuse 仓库自治 Agent 实战：用 create-repo-agent 技能构建安全、可无人值守的自动化维护流水线-平芜编程栈

Langfuse 仓库自治 Agent 实战：用 create-repo-agent 技能构建安全、可无人值守的自动化维护流水线

【免费下载链接】langfuse🪢 Open source AI engineering platform: LLM evals, observability, metrics, prompt management, playground, datasets. Integrates with OpenTelemetry, LangChain, OpenAI SDK, LiteLLM, and more. 🍊YC W23项目地址: https://gitcode.com/GitHub_Trending/la/langfuse

本指南以 Langfuse 开源仓库内的 create-repo-agent 技能为核心，系统讲解如何设计、实现、审查与加固"仓库自有的自治 Agent"（repo-owned autonomous agent）。它适用于 LLM 驱动的 GitHub Actions、定时或手动派发的 Agent、Agent 创建的 PR、提示词、允许列表、令牌、不可信内容以及自我更新指令等场景。读完本文，你将掌握一套完整的"最小权限 + 独立校验 + 双阶段发布"的 Agent 工程方法论，并能对照仓库中真实的 model-price-audit.yml 落地到自己的项目中。

一、为什么需要"仓库自治 Agent"：目标与默认架构

create-repo-agent技能在 Purpose 一节就给出了清晰的定义：构建可以在无人值守下运行的仓库 Agent，且不向模型授予宽泛的写凭据、任意 Shell 或不受控的网络访问。

它的默认架构是一个两阶段流水线：

Phase 1（审计 Job）：只读审计任务。检出代码（不持久化凭据）、让 LLM 在只读权限下工作、独立校验产生的 diff、生成补丁（patch）产物与 PR 正文产物；
Phase 2（发布 Job）：拥有 GitHub 写入权。下载补丁、应用到确切的触发提交、推送机器人分支、创建或更新 PR。

关键原则是：LLM 步骤永不接触写凭据，写操作全部收敛到单独的发布 Job。技能还强调要与对应领域的 skill 搭配使用，例如价格维护 Agent 必须同时使用 add-model-price 领域技能。

在 Langfuse 仓库中，这一架构的落地范例是.github/workflows/model-price-audit.yml，它在下方各章节中会被反复引用作为实证。

二、八步工作流：从目标定义到可审查的 PR

create-repo-agent技能给出了一个可复用的 8 步工作流，这是构建任何仓库 Agent 的主干：

定义精确的维护目标：明确允许修改的文件、外部数据源、期望的"无变更"行为以及 PR 归属；
选择能力最小的运行时：优先采用定时/手动触发的 GitHub Action，LLM 步骤使用只读仓库检出、不携带任何写凭据；
编码 Prompt：显式声明允许的编辑面（allowed edit surface）、硬约束、证据要求与结构化输出；
仅授予受限工具：作用域化的文件工具、领域受限的抓取工具，以及精确的确定性校验命令；
独立校验 diff：覆盖未跟踪文件、路径允许列表、git diff --check、行数上限与领域专用校验器；
在独立 Job/步骤中发布：校验通过后，只用机器人凭据做分支推送与 PR 创建/更新；
若允许自我改进：将其限制在指定的 workflow 或 skill 引用文件内，并要求安全不变量保持不变；
.agents/**变更后运行 Agent 设置检查：pnpm run agents:sync与pnpm run agents:check，随后发布一个常规的、可由人类审查的 PR。

从源码结构看，这套工作流与.agents/README.md中描述的共享技能管理流程（编辑.agents/config.json→pnpm run agents:sync→pnpm run agents:check）是同一套治理体系的两个侧面：技能本身也是仓库资产，同样走人工审查 PR。

三、Non-Negotiables：不可逾越的安全底线

技能明确列出了多条"绝不"（Never），这是审查任何 Agent 实现的第一道清单：

绝不向 LLM Agent 步骤暴露任何可写 GitHub Token、PAT、GitHub App Token、OIDC Token、SSH 密钥、云凭据或包发布令牌；
绝不把 Prompt 指令当作唯一安全边界——文件与命令限制必须在 Agent 之外强制执行；
绝不整体暂存整个目录，只暂存经过校验的文件列表；
绝不在 diff 校验中忽略未跟踪文件；
绝不让自我改进绕过与普通编辑相同的 diff 允许列表和人工 PR 审查；
绝不向 LLM 授予任意Bash、curl、wget、gh、git push、包管理器、解释器、环境转储或进程检查工具；
绝不添加id-token: write，除非 Agent 确实需要 OIDC 且信任关系经过显式审查。

这些底线并非空泛原则——在 model-price-audit.yml 中可以逐条看到对应实现：LLM 步骤只拿到secrets.CLAUDE_API_KEY与只读的${{ github.token }}，工作流顶层permissions: contents: read，发布 Job 才使用secrets.GH_ACCESS_TOKEN。

四、安全标准详解：威胁模型、凭据模型与工具权限

security-standards.md 是技能强制要求的必读材料（"对于每个仓库 Agent 任务，在设计或编辑前先阅读"）。它比普通 CI 更严格，因为LLM 步骤会消费不可信指令、网页、源文件与先前输出。

4.1 威胁模型

将提供商网页、GitHub issue、PR 评论、发布说明、生成文件、包脚本与先前 Agent 输出一律视为不可信输入；
假设存在 Prompt 注入：可能诱导 Agent 泄露密钥、自行放宽权限、编辑无关文件、开放更大网络访问，或把恶意变更隐藏在格式噪音里；
假设 Agent 即便出于善意也可能犯错：独立校验必须能拦截错文件、超大 diff、非法生成产物与缺失的领域校验；
把自我改进视为代码执行策略变更：它有用，但绝不豁免于审查、路径允许列表与安全不变量。

4.2 凭据模型

LLM Agent 步骤只应获得：运行 Agent 所需的模型提供商 API Key，以及（若 Action 需要）只读的${{ github.token }}；
将 workflow/job 的permissions设为最小必要值，只读审计 Job 使用contents: read；
对会自行从环境发现令牌的 LLM Action，显式传入github_token: ${{ github.token }}，并保持 Job 权限只读；
不要向 LLM 步骤传递secrets.GH_ACCESS_TOKEN、写作用域 PAT、GitHub App 私钥、SSH 密钥、云凭据、包注册表令牌或 OIDC Token；
写凭据只放在单独的发布 Job 或校验后的步骤中，该步骤不调用 LLM；
每个密钥只放在需要的步骤上，不要定义宽泛的 Job 级密钥 env；
不要回显密钥、转储环境变量、开启全量 Agent 日志，或将未脱敏的 Agent 转录上传为产物；
除非存在经审查的 OIDC 信任边界，否则不添加id-token: write。

4.3 工具权限

文件工具优先用作用域化的Read/Edit/Write，精确到路径或路径 glob；
网络抓取优先用领域受限的WebFetch（仅官方来源），而非 Shell 网络工具；
Shell 工具只允许精确的Bash(command ...)，且仅限确定性的、仓库自有的校验器或简单非敏感命令（如date -u +%Y-%m-%dT00:00:00.000Z）；
禁止宽泛的 Shell 模式：Bash(*)、Bash(node:*)、Bash(python:*)、Bash(curl:*)、Bash(wget:*)、Bash(gh:*)、Bash(git:*)、Bash(pnpm:*)、Bash(npm:*)；
禁止cat、sed、grep、rg、jq、env、printenv、ps、ls等 Shell 读取或环境/进程检查命令，除非确需且安全；文件读取应走作用域化读取工具；
不在 LLM 步骤允许git push、PR 创建、GitHub API 调用、包安装、包发布、依赖更新或任意解释器；
确定性校验器应保存在仓库中、按普通代码审查，且只允许那一条精确命令。

在真实工作流中，这一点体现为--allowedTools参数里一长串精确条目，例如Read(/.github/workflows/model-price-audit.yml)、WebFetch(domain:docs.anthropic.com)、Bash(node .agents/skills/add-model-price/scripts/validate-pricing-file.mjs:*)、Bash(date -u +%Y-%m-%dT00:00:00.000Z)等（见 model-price-audit.yml 的 claude_args 段）。

五、Prompt 契约：让模型知道边界，但不依赖它执行边界

每个仓库 Agent 的 Prompt 必须声明：

Agent 的目标与显式的无变更行为；
可读、可编辑的文件；
可用的官方来源；
不可违反的硬约束；
结束前必须运行的校验器；
期望的结构化输出 schema；
任何变更所需的证据（含来源 URL 与换算计算）。

安全标准反复强调：Prompt 不是执行层——Prompt 引导模型，workflow 必须仍然强制文件、命令、令牌与发布边界。

workflow-blueprint.md 给出了一份可直接套用的 Prompt 模板：

You are running Langfuse's scheduled <task> audit. Read and follow: - <domain skill> - <domain references> Allowed edit surface: - <exact file> - <restricted glob> Task: 1. <business audit goal> 2. Make only surgical edits with official evidence. 3. Report uncertainty without changing code. 4. Update approved skill references when durable learnings are discovered. 5. Optionally update this workflow only for future prompt/tool/domain/validation improvements. 6. Run deterministic validation before finishing. Hard constraints: - Do not change generated files. - Do not change package manager files. - Do not run git push or create a PR. - Do not add broad wildcard behavior. - Preserve security invariants for workflow self-improvement. Final response: - No diff: report no changes and unresolved findings. - Diff: list changed business objects, source URLs, calculations, self-improvements, and validation commands.

业务规则要针对领域技能定制，不要留下"更新相关文件"这类模糊授权。仓库中 model-price-audit.yml 的 prompt 字段是这一模板的完整工业化实例：它列出了 6 个必读文件、4 类允许编辑面（workflow、pricing JSON、共享 LLM 类型、skill 引用文档）、11 条任务指令与 9 条硬约束，包括"保留default-model-prices.json每个可选模型数组的首条目"这类极其具体的领域规则。

5.1 结构化输出：机器可校验的契约

模板要求结构化 JSON 输出并渲染到 Job Summary。model-price-audit.yml中的--json-schema是完整范例：顶层要求summary、auditDate、pullRequestTitle、modelsChecked（每行含provider、model、pricingChecked、priceConfirmed枚举、usageKeysChecked、usageKeyCoverageConfirmed、tieringChecked、tieringCorrect、change枚举、officialSources数组、comments）、changedModels、skillReferenceUpdates、workflowUpdates、unresolvedFindings、validation，且全部additionalProperties: false。这样的 schema 让下游脚本（如scripts/model-price-audit/validate-and-render-audit-output.mjs）能确定性消费 Agent 输出，并渲染为可审查的 PR 正文。

六、Workflow 蓝图：顶层结构、输入校验与工具清单

workflow-blueprint.md 专门用于实现或修改.github/workflows/**下的定时/手动仓库 Agent。

6.1 顶层结构约定

name：显式的维护任务名；
on.schedule：使用可预测、低噪音的节奏；
on.workflow_dispatch.inputs：保持输入小而精，每个输入在插值进 Agent 参数前都必须校验；
为新建 Agent 提供手动 dry-run 输入：跳过模型步骤、输出合成的结构化结果，可选地生成一个允许列表内的 mock diff，从而在不花模型费用的情况下调试校验、补丁产物与"不发布"路径；
permissions：默认为contents: read；
concurrency：每个 Agent 一个稳定组，通常cancel-in-progress: true；
env：只放分支名与 PR 标题，顶层 env 不放密钥。

model-price-audit.yml完全符合：schedule为cron: "17 2 * * *"（旧金山晚间），workflow_dispatch提供claude_model（choice）、max_turns（1-500）、max_budget_usd（1-20）、additional_prompt（可选一次性指令）与dry_run_mode（choice），顶层env仅含BOT_BRANCH。

6.2 审计 Job 的要点

审计 Job 是唯一调用 LLM 的 Job：

用if: github.repository == 'langfuse/langfuse'守卫（仓库自有自动化）；
设有限的timeout-minutes；
用actions/checkout且persist-credentials: false、最小fetch-depth；
只安装确定性校验器所需的运行时；
在workflow_dispatch输入进入 Prompt/CLI 参数前校验它们；
调用模型前先跑廉价的确定性预检查；
生成校验器所需的被忽略的本地 Agent shim（在干净的 Actions 检出上）；
只把模型 API Key 与只读${{ github.token }}传给 LLM Action；
设置 Agent 超时与预算控制（如 max turns、max budget、API 超时、Shell 超时）；
使用--no-session-persistence，除非会话复用经过审查；
使用严格的--allowedTools列表；
使用结构化 JSON 输出并渲染到 Job Summary。

6.3 手动输入校验：防御插值攻击

模型名、模式、环境等枚举用type: choice；
自由数字输入用正则 + 数值范围校验后再使用；
会成为 CLI 参数的字符串输入，用允许列表正则或选择集校验；
可选的一次性指令输入（供手动调试或定向审计）可以允许，但必须校验长度与控制字符，追加到 Prompt 时放在清晰标注的低优先级区段，且不能覆盖硬约束、工具限制、凭据边界、校验门与发布边界；
绝不把未经校验的手动输入插值进 Shell 命令、JSON、分支名、文件路径或 LLM CLI 参数。

model-price-audit.yml的Validate workflow inputs步骤是教科书级实现：case校验 choice 枚举；max_turns用^[1-9][0-9]{0,2}$且上限 500；max_budget_usd用^[1-9][0-9]?$且上限 20；additional_prompt用 Node 脚本检查长度（≤4000 字符）、控制字符（[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]）与保留分隔符，并以 heredoc 分隔符安全地写入GITHUB_OUTPUT。

6.4 Dry-Run 输入的 YAML 陷阱

蓝图特别警告：dry-run 输入应使用 YAML 安全的 choice 值，如disabled、no_changes、mock_allowlisted_diff，避免off、on、yes、no、true、false这类布尔化令牌——GitHub 可能把它们解析或渲染为布尔值。Dry run 必须跳过 LLM Action 且不得发布 PR。model-price-audit.yml的选项为disabled | no_changes | mock_memory_diff | mock_workflow_diff，且在其输入校验中专门处理了false这种历史布尔化值并归一为disabled。

6.5 Allowed Tools 起点：先给空，再按需加

开始时不授予任何 Shell 或网络工具，然后只加任务所需的：

精确Read路径（源文件、技能文档、启用自我改进时的 workflow 文件）；
精确Edit路径（可变文件）；
Write仅限窄路径下的获批新文件（如 skill 引用 Markdown）；
领域受限的WebFetch（官方提供商文档与定价页）；
精确的确定性校验器命令。

禁止向 LLM 步骤添加宽泛 Shell、包管理器、GitHub CLI、git 写操作、curl/wget 或解释器访问。

七、Diff 强制校验：不信任 Agent 的任何输出

7.1 变更文件收集

独立 diff 校验必须在 Agent 之后、发布之前运行。第一步是用跟踪与未跟踪两个来源共同构建变更列表：

mapfile -t changed_files < <( { git diff --name-only git ls-files --others --exclude-standard } | sort -u )

然后：

无变更则干净退出；
用锚定的精确路径允许列表正则检查每个路径——不允许宽泛目录，除非任务需要在某目录下创建具名文件且正则可防穿越；
对未跟踪文件先git add -N -- "${untracked_files[@]}"（intent-to-add），再做 diff 检查与行数检查；
运行git diff --check -- "${changed_files[@]}"；
为外科手术式 Agent 设置变更行数上限（价格维护应保持小 diff）；
在暂存前对工作区文件运行领域校验器；
只暂存校验过的文件列表git add -- "${changed_files[@]}"；
用git diff --cached --name-only复查同一允许列表；
对比暂存 blob 与工作区内容，捕获 clean/smudge filter、生成产物突变或暂存意外；
对机器可读 schema 的文件（尤其 JSON）运行暂存 blob 校验；
提交前运行git diff --cached --check -- "${staged_files[@]}"。

model-price-audit.yml的Validate audit diff步骤完整实现了这条链路：允许列表正则为^(\.github/workflows/model-price-audit\.yml|worker/src/constants/default-model-prices\.json|packages/shared/src/server/llm/types\.ts|\.agents/skills/add-model-price/references/[^/]+\.md)$；行数上限为 700 行；未跟踪文件先 intent-to-add；随后git diff --check与 diff stat 写入 Job Summary。Prepare pull request artifact步骤则继续做暂存后复查、git show ":path"的暂存 blob 校验（cmp -s对比工作区）、staged 定价 JSON 校验，最后以git -c core.hooksPath=/dev/null commit --no-verify提交并git format-patch -1 --stdout HEAD生成补丁。

八、双阶段发布边界：审计与发布彻底分离

两阶段架构是 Agent 创建 PR 时的标准形态：

Phase 1 审计 Job：以persist-credentials: false检出代码、只读权限运行 LLM、校验 diff、禁用钩子本地提交、上传git format-patch补丁产物与 PR 正文产物；
Phase 2 发布 Job：下载补丁、拉取足够源引用历史找到触发提交、在干净的临时仓库中把补丁应用到确切触发提交、用写作用域机器人密钥推送分支、创建或更新 PR。

发布 Job 的要求：

不得调用 LLM；
在可行处清空 global/system git 配置，对任何提交或 push 邻近的 git 操作禁用钩子；
push 前用同一路径允许列表复查已应用提交的变更文件；
评审人指派应非致命（|| true），缺失评审权限不应使本可成功的维护 PR 失败。

model-price-audit.yml的publishJob 逐条对应：仅当needs.audit.outputs.has_changes == 'true' && needs.audit.outputs.dry_run_mode == 'disabled'运行；在$RUNNER_TEMP下git init新仓库、git fetch --no-tags --depth=100、校验$GITHUB_SHA存在后 checkout 到该 SHA；用GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null git -c core.hooksPath=/dev/null am --3way应用补丁；用 Node 校验 PR 标题必须匹配^chore$pricing$:且不得是泛化标题；用diff-tree复查应用文件均在允许列表内；git diff --check HEAD^ HEAD后以x-access-token:${GH_TOKEN}强制推送机器人分支；随后gh pr list查重、pr edit更新或pr create创建，评审人--add-reviewer hassiebp || true非致命。此外还配了notify-slack-on-failureJob 在失败时通知 Slack。

九、自我改进：有用的能力，严格的笼子

自我改进只在 workflow 显式选择启用时允许：

限制在具名文件，通常是 workflow 自身与仓库自有的技能引用文件；
保持外科手术式：Prompt 清晰度、官方域名允许列表、精确校验器/工具条目、输入默认值、超时/预算设置、输出 schema 改进；
要求最终输出列出每一项自我改进及其对后续运行的收益；
保留安全不变量：只读审计 Job、LLM 步骤无写令牌、独立发布器、显式令牌权限、路径允许列表、输入校验、暂存 blob 检查、禁用钩子的提交路径、人工 PR 审查；
不因自我改进而添加任意 Shell/网络工具、写 Job 权限、id-token: write、包管理器工具、gh、git push或宽泛文件 glob；
若所需改进会违反不变量，Agent 必须将其报告为 unresolved 而不是应用。

在 workflow 落地时（见 workflow-blueprint.md 的 Self-Improvement Pattern）：把 workflow 文件加入 Prompt 允许编辑面、为它加精确Read/Edit工具、加入所有 diff/staging 允许列表、加结构化输出字段（如workflowUpdates）、加列出必须保留的不变量的 Prompt 约束，且改进与业务变更放在同一 PR 中。合理的自我改进包括：新增发现的官方文档域名、收紧含糊 Prompt、添加仓库中已有的精确校验器命令、按实际需求调整 max-turn 默认值或超时、增加提升可审查性的结构化输出字段；禁止用它来放开 Shell、授予审计 Job 写权限、加 OIDC 或包管理器、移除校验器或允许列表、编辑无关 workflow 或生成文件。

十、Dry-Run 模式：不烧模型预算调试整条流水线

Dry-run 用于在不调用模型的情况下调试 Agent 周边的 workflow 机制：

添加一个workflow_dispatchchoice 输入，默认值为 YAML 安全的 disabled 值；
使用前校验输入；
用显式检查守卫 LLM Action，如if: <dry-run-mode> == 'disabled'；
为 dry-run 添加 mock 步骤，写出与 LLM Action 相同形状的结构化输出；
提供 no-change 模式测试干净退出；
提供允许列表 mock-diff 模式测试 diff 校验、暂存、提交、补丁创建与产物上传；
所有 dry-run 模式都跳过发布 Job，即使 mock diff 产生了补丁产物；
让 dry-run 摘要明确标注，维护者绝不把合成输出误认为真实审计。

model-price-audit.yml的Mock Claude price audit步骤展示了三种模式：mock_workflow_diff向 workflow 追加注释以生成 mock diff、mock_memory_diff向model-audit-memory.md追加注释、no_changes不产生任何 diff；三者都输出形状相同的结构化 JSON（pullRequestTitle在无业务变更时置空），且发布 Job 的守卫条件保证 dry-run 永不发布。

十一、发布前审查清单：合并前必须逐项核对

review-checklist.md 是最终审查或 PR 发布前必读的清单，核心是"阻断合并"（Block Merge If）条件：

LLM 步骤持有可写 GitHub Token、PAT、GitHub App Token、SSH 密钥、云凭据、包令牌或 OIDC Token；
LLM 步骤有任意 Shell、宽泛解释器、包管理器、curl/wget/gh/git push或宽泛网络访问；
workflow 仅依赖 Prompt 指令作为文件范围、命令范围或发布的唯一护栏；
diff 校验忽略未跟踪文件；
workflow 暂存整个目录而非校验后的文件列表；
发布路径可推送允许列表之外的任何文件；
自我改进可在没有路径允许列表、不变量 Prompt 与人工 PR 审查的情况下修改安全边界；
手动输入在校验前被插值；
workflow_dispatchchoice 值使用off/on/yes/no/true/false等布尔化令牌；
Agent 可在没有显式任务与专门审查的情况下修改生成文件、依赖锁文件、包管理器配置、CI 信任设置或密钥。

清单其余部分按 Scope、Credentials、Tool Allowlist、Prompt/Output、Diff/Validation、Publish Path、Self-Improvement、Operational Fit 八个维度展开，每项都对应本文前述的实现细节。其中操作适配性（Operational Fit）值得特别留意：调度频率要匹配提供商限流、模型成本与评审人注意力；timeout-minutes、max turns、max budget 要能约束失控循环；手动派发输入要足以安全调试而不让 Agent 变得任意；no-change 运行要廉价且可读；失败模式要为维护者留下足够上下文而不暴露密钥。

11.1 验证命令

仅 workflow 变更时，至少运行：YAML 解析或 workflow linter（可用时）、对抽取的内嵌 Shell 脚本跑bash -n（若已抽取或 lint）、git diff --check；
.agents/**变更时，额外运行：pnpm run agents:sync、pnpm run agents:check、对新/变更技能的 skill-creator 快速校验器；
领域文件变更时，运行领域技能指定的领域校验器与定向测试。

在 .agents/AGENTS.md 中也能看到这套治理的配套约束："更改 skills/AGENTS.md 后运行pnpm run agents:sync和pnpm run agents:check"、"创建或编辑.agents/skills/**时使用 skill-creator 技能"。

十二、从技能到落地：把 create-repo-agent 应用到你的仓库

以 Langfuse 的价格审计 Agent 为参照，落地一个仓库 Agent 的最小检查单如下：

目标：写下一个狭窄的维护目标（如"每日核对默认模型定价"）与明确的 no-change 成功路径；
技能组合：创建领域 skill（如 add-model-price）承载业务规则，用 create-repo-agent 的方法论搭 workflow；
凭据：审计 Jobpermissions: contents: read、persist-credentials: false、只传模型 API Key 与只读github.token；写令牌只进发布 Job；
输入：全部type: choice或正则+范围校验；dry-run 值用disabled/no_changes/mock_allowlisted_diff；
工具：--allowedTools只放精确 Read/Edit/Write 路径、官方域名 WebFetch、精确校验器 Bash 命令；
校验：未跟踪+跟踪文件收集变更、锚定允许列表正则、git add -N后git diff --check、行数上限、暂存 blob 对比、staged 校验、git diff --cached --check；
发布：干净临时仓库、git am --3way应用补丁到触发 SHA、复查允许列表、禁用钩子、--force推机器人分支、查重更新 PR、评审人非致命；
自我改进：显式启用、具名文件、不变量 Prompt、结构化输出字段、与业务变更同 PR；
审查：跑 review-checklist 的 Block Merge If 全项 + 验证命令。