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 技能 为核心系统讲解如何设计、实现、审查与加固仓库自有的自治 Agentrepo-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它在下方各章节中会被反复引用作为实证。二、八步工作流从目标定义到可审查的 PRcreate-repo-agent技能给出了一个可复用的 8 步工作流这是构建任何仓库 Agent 的主干定义精确的维护目标明确允许修改的文件、外部数据源、期望的无变更行为以及 PR 归属选择能力最小的运行时优先采用定时/手动触发的 GitHub ActionLLM 步骤使用只读仓库检出、不携带任何写凭据编码 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 Langfuses 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: readconcurrency每个 Agent 一个稳定组通常cancel-in-progress: trueenv只放分支名与 PR 标题顶层 env 不放密钥。model-price-audit.yml完全符合schedule为cron: 17 2 * * *旧金山晚间workflow_dispatch提供claude_modelchoice、max_turns1-500、max_budget_usd1-20、additional_prompt可选一次性指令与dry_run_modechoice顶层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}$且上限 500max_budget_usd用^[1-9][0-9]?$且上限 20additional_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 --depth100、校验$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三者都输出形状相同的结构化 JSONpullRequestTitle在无业务变更时置空且发布 Job 的守卫条件保证 dry-run 永不发布。十一、发布前审查清单合并前必须逐项核对review-checklist.md 是最终审查或 PR 发布前必读的清单核心是阻断合并Block Merge If条件LLM 步骤持有可写 GitHub Token、PAT、GitHub App Token、SSH 密钥、云凭据、包令牌或 OIDC TokenLLM 步骤有任意 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 全项 验证命令。create-repo-agent技能的价值在于把LLM 参与代码维护从一次性脚本提升为一套可审查、可复用、可自我改进的工程规范让模型做它擅长的事理解业务、比对来源、生成变更让工作流做它擅长的事强制边界、独立校验、受控发布两者各司其职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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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 技能 为核心系统讲解如何设计、实现、审查与加固仓库自有的自治 Agentrepo-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它在下方各章节中会被反复引用作为实证。二、八步工作流从目标定义到可审查的 PRcreate-repo-agent技能给出了一个可复用的 8 步工作流这是构建任何仓库 Agent 的主干定义精确的维护目标明确允许修改的文件、外部数据源、期望的无变更行为以及 PR 归属选择能力最小的运行时优先采用定时/手动触发的 GitHub ActionLLM 步骤使用只读仓库检出、不携带任何写凭据编码 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 Langfuses 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: readconcurrency每个 Agent 一个稳定组通常cancel-in-progress: trueenv只放分支名与 PR 标题顶层 env 不放密钥。model-price-audit.yml完全符合schedule为cron: 17 2 * * *旧金山晚间workflow_dispatch提供claude_modelchoice、max_turns1-500、max_budget_usd1-20、additional_prompt可选一次性指令与dry_run_modechoice顶层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}$且上限 500max_budget_usd用^[1-9][0-9]?$且上限 20additional_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 --depth100、校验$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三者都输出形状相同的结构化 JSONpullRequestTitle在无业务变更时置空且发布 Job 的守卫条件保证 dry-run 永不发布。十一、发布前审查清单合并前必须逐项核对review-checklist.md 是最终审查或 PR 发布前必读的清单核心是阻断合并Block Merge If条件LLM 步骤持有可写 GitHub Token、PAT、GitHub App Token、SSH 密钥、云凭据、包令牌或 OIDC TokenLLM 步骤有任意 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 全项 验证命令。create-repo-agent技能的价值在于把LLM 参与代码维护从一次性脚本提升为一套可审查、可复用、可自我改进的工程规范让模型做它擅长的事理解业务、比对来源、生成变更让工作流做它擅长的事强制边界、独立校验、受控发布两者各司其职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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考