agentic-awesome-skills 的 Pull Request 自主化信任边界、影子路由与受保护合并机制解析【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,115 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/gh_mirrors/an/agentic-awesome-skills导读本文以仓库维护文档 docs/maintainers/pr-autonomy.md 为主线系统拆解 agentic-awesome-skillsAAS仓库在低维护成本 PR 处理目标下的分阶段演进设计从无特权的 CI 证据收集、影子路由推荐到merge:batch基于受信main的完整重算与受保护规范同步canonical sync。读完本文你将理解为什么该仓库坚持CI 报告仅作参考、合并决定必须重算掌握四个必需检查pr-policy、pr-evidence、source-validation、artifact-preview的分工、Fork PR 的安全准入模型以及通往未来自动合并且前绝不自动合并的治理边界。一、总体架构先证据与路由而非自动合并该文档开篇即明确核心立场本仓库的 PR 自主化是分阶段的第一阶段的目标是证据生成与路由分流而不是自动合并。整套机制围绕一个矛盾展开——PR 的 CI 环境不可信但仓库又需要 CI 的高效反馈。解决方案是低权限 CI 负责产出咨询性证据特权操作合并必须从受信代码路径重新计算决定。这个设计可以从两个核心事实得到源码印证CI 无特权仓库主工作流 .github/workflows/ci.yml 顶层声明permissions: contents: read所有 job 继承该最小权限不接触任何仓库 secrets重算而非复用合并工具merge:batch命令入口见 package.json 与使用文档 docs/maintainers/merge-batch.md必须从本地HEAD等于origin/main的受信提交中物化评估器在隔离的 Python 进程中运行仅受跟踪的评估器PR 脚本、未跟踪文件、Python 环境覆盖、上传的工件一律不得进入授权路径。二、信任模型为什么 PR 产出的证据只能是咨询性文档对信任模型的阐述是整套机制的地基可归纳为三条原则原则一PR CI 无特权、无 secrets。PR 检出本身可以修改报告代码自身例如恶意 PR 篡改生成证据的脚本因此 PR 环境中生成的任何报告都明确为咨询性。原则二特权操作必须对不可变的 base/head 对象 ID 重算。任何特权或本地维护者操作都不得把 PR 生成的决策工件当作授权凭证而必须基于受信main代码对不可变的 base 与 head 对象 ID 重新计算决定。原则三merge:batch只信受信main。它在证明本地HEAD与origin/main一致后从该提交物化评估器并隔离运行未跟踪文件、PR 脚本、环境覆盖与上传工件均不在授权路径内。这与 .github/MAINTENANCE.md 中Always merge accepted PRs with the guardednpm run merge:batchcommand的维护纪律完全对应——它要求最终必须走 GitHub 受保护 squash 合并禁止本地整合后关闭 PR。三、证据工件preflight、changed-skills 与决策清单pr-evidencejob.github/workflows/ci.yml产出三类工件工件内容生成入口preflight.json变更文件、宽泛变更类别、source-only 策略状态、PR 模板状态tools/scripts/pr_preflight.cjs--json输出changed-skills.json变更的 canonical skill 的 before/after 证据审计发现、分数、安全标志、风险、来源provenance、确定性回归原因tools/scripts/changed_skill_evidence.pydecision-manifest.json带 schema 版本的影子路由推荐tools/scripts/pr_decision_manifest.cjsdecision-manifest.json始终包含固定结构{ schema_version: 1, mode: shadow, untrusted_advisory: true, route: human_review }其中untrusted_advisory: true是有意为之的标记任何工作流、合并命令或未来的 bot 都不得把该工件当作特权授权。此外pr-policyjob 还会输出impact_profile及其原因见 .github/workflows/ci.yml 的 job outputs 定义但它只是观察性影子遥测不会跳过、降级或满足任何必需 job、测试、审查或合并门禁。四、影子路由三种推荐与 v1 阶段的人工兜底证据工件生成后pr_decision_manifest.cjs会根据确定性证据给出影子路由block确定性仓库策略失败例如新引入的 changed-skill 回归或对生成工件derived artifacts的直接编辑human_review变更本身有效、可审查但触及 canonical skill 内容、敏感路径、来源/风险不确定或缺乏语义审查eligible_for_later_automation确定性证据未发现阻塞项且变更属于低风险类别——但当前阶段仅作咨询不启用自动合并。值得强调的 v1 硬性规则每个新增或迁移的 skill以及每个 canonical skill 内容变更都必须经过维护者审查。即便证据打上safe风险标签也不足以构成自动合并的依据。这正是影子二字的含义——推荐路径只观察、不执行。五、Fork 审查状态快速失败与双重结果分离5.1 准入前置从受保护 base 物化审查实现对于普通 Fork PRpr-policy会从精确的受保护 base 物化 intake 实现工作流中通过git worktree add --detach $trusted_root ${{ github.event.pull_request.base.sha }}检出受信 base并以NODE_PATH$trusted_root/node_modules只指向该 worktree绝不指向 PR 控制的node_modules见 .github/workflows/ci.yml在其依赖的必需 job 开始昂贵的 setup 或等待之前评估 Fork 安全性。这样做的效果是不安全的路径、模式、对象、大小与仓库身份能在无特权 CI 中快速失败。同样关键的是边界这不是授权。merge:batch会独立地从受信main重算完整决定是 Fork 运行批准与合并的唯一权威。5.2 Skill Review 工作流的两个结果Skill Review 工作流.github/workflows/skill-review.yml在paths上针对skills/**与plugins/**/skills/**触发将语义审查拆成两个可区分的检查结果review语义审查确实运行了且使用的是受信 base 脚本该工作流分别检出pull_request.head.sha内容与pull_request.base.sha到trusted-base路径再运行node trusted-base/tools/scripts/review_changed_skills.cjs见 .github/workflows/skill-review.ymlmanual-review-requiredTessl 凭据或额度不可用或 Tessl 未产生通过的语义结果此时维护者必须对精确 head SHA进行审查与证明attest。工作流通过TESSL_REVIEW_THRESHOLD: 80、TESSL_REVIEW_CACHE_VERSION: 2等环境变量控制审查行为并对已通过的审查按最近 skill 目录指纹做缓存复用key 为tessl-review-v2-${{ steps.plan.outputs.fingerprint }}保证嵌套示例、脚本、lockfile、引用、资产等捆绑文件无法绕过语义审查。文档特别强调manual-review-required检查成功只表示需求已被记录它不等于一次成功的语义审查。六、维护者重算merge:batch的八步信任链merge:batch必须把工作流批准与人工证明绑定到一个完整的 head SHA不重写 PR 正文也不通过关闭再重开 PR 来制造替换运行。在批准等待中的 Fork 运行前它独立执行对应 docs/maintainers/pr-autonomy.md 的八步重算捕获 base 与 head 对象 ID不检出 PR 代码的情况下 fetch 这些对象计算完整的 NUL 分隔原始 Git diff含完整对象 ID 与模式对外部 PR拒绝不安全路径、模式、符号链接、gitlink、可执行文件、未知类型、超大 blob、不完整元数据或非白名单工作流校验工作流事件、工作流身份、PR 编号与 head SHA在精确的 merge-base 到 head 记录集上重算 changed-skill 证据并要求覆盖每个 skill 内容 Git 记录一对一覆盖拒绝操作错误、畸形证据、不完整快照、分数组件回归、来源身份回归或任何其他确定性阻塞项只有受信 protected-base 账本记录了 skill、旧 slug、新 slug、上游仓库 ID、验证日期与 canonical GitHub URL 的精确source_repo重命名才可能通过在批准前与批准后、合并前立即各重新读取一次 PR 的 base 与 head。6.1 服务端保护前置条件真实合并还要求main具备有效的服务端保护四个精确的 GitHub-Actions 所属检查pr-policy、pr-evidence、source-validation、artifact-preview、严格的 up-to-date 强制、仅限 PR 的变更、管理员强制、无适用规则集绕过角色、无 merge queue。若无法证明这些强制有效merge:batch会拒绝非 dry-run 操作。此外merge:batch不自动重试 base 漂移也不复用过期证据——批次必须基于新的 (base, head) 元组重新运行。预先存在的 auto-merge 状态会被拒绝且 GitHub 即时合并端点必须返回merged: true之后才允许进入合并后工作。6.2 敏感 PR 的例外与 fail-closed敏感的同仓库 PR只有在PR 作者是仓库所有者 维护者对精确完整 head SHA 作出证明时才可使用仓库级 source 例外协作者collaborator撰写的敏感 PR不因分支位置继承信任在外部安全策略下 fail closed每个被接受的 PR 仍绑定受保护分支、受信 base 证据评估器、精确的 PR/base/head 元组、语义审查要求与必需检查head 仓库身份缺失或不匹配一律按外部 PR 处理。6.3--reviewed-headcanonical skill 变更的强制证明对 canonicalskills/skill-id/**子树下的任何受跟踪变更维护者必须提供--reviewed-head full-sha40 位完整 SHA。过期、缩写或不匹配的 SHA 一律 fail closed。Skill Review 的重用结果以完整最近 skill 目录指纹为键因此删除、复制、歧义移动与所有 canonical skill 内容变更在当前阶段仍保持纯人工处理——即便确定性证据没有回归。通过 ratchet棘轮式质量门槛不等于语义批准永远不会使 skill 进入自动合并范围。七、必需 CI 工作分工四条流水线的职责切分7.1 普通 source PR一次生成 验证预览对于普通 source PR.github/workflows/ci.yml 中IS_TRUSTED_CANONICAL_SYNC_PR ! true分支source-validation运行一次校验、测试、安全检查与生成态刷新npm run validate、npm run check:warning-budget、npm run test、npm run security:docs及一系列npm run plugin-compat:sync npm run index npm run bundles:sync npm run sync:metadata npm run catalog npm run build:aas-v1-catalog npm run sync:web-assets等派生刷新命令随后用 tools/scripts/ci_artifact_preview.cjs 上传字节规范的 JSON 预览清单清单绑定仓库、工作流 SHA、run ID/attempt 与精确 PR head SHAartifact-preview只下载并验证清单的摘要digest与身份仓库、run ID、attempt、workflow SHA、head SHA 逐一比对见 .github/workflows/ci.yml然后报告漂移不重复生成源。7.2 canonical-sync PR互补的轻量边界对于受保护的 canonical-sync PRautomation/canonical-repo-state分支pr-policy已从受信main精确复现期望树工作流在受信 worktree 中执行npm run sync:repo-state、git write-tree并与 PR HEAD 树对比因此source-validation仅作为轻量边界记录artifact-preview重新生成并确认 canonical head 无漂移对受管理文件执行git diff --name-only存在漂移即报错退出见 .github/workflows/ci.yml。受保护合并之后最终 CI 与 CodeQL 会显式派发对合并后的main提交做验证。7.3 测试计时与分片纪律测试运行器输出逐测试与汇总计时遥测供维护者在改动 DAG 前度量。确定性分片仅可通过显式的npm run test:local -- --shard-index N --shard-count M调用获得必需 CI 始终使用完整不分片的npm run test。无论是计时、分片还是impact_profile都不减少保障。八、受保护规范同步Protected Canonical Sync生成工件与贡献者致谢不再直接写入mainPush 与定时维护工作流在不持久化检出凭据的情况下重新生成仓库状态拒绝任何非受管理漂移并维护一条来自automation/canonical-repo-state分支的 bot PR由于 GitHub 会抑制用GITHUB_TOKEN创建的 PR 的普通工作流递归受信写入者会在 bot 分支上显式派发四个必需检查——该派发仅在精确分支上被接受、仅针对生成文件契约tools/scripts/generated_files.js声明的文件、且仅当重跑sync:repo-state能产生精确完整 Git 树时才被接受受信等待器把打开的 PR 绑定到其不可变 head校验四个精确的 GitHub Actions 检查确认main仍受保护且未变化执行即时的精确 head squash 合并再显式派发 main CI 与 CodeQLPages 保持 release-only绝不允许由 canonical 同步派发。这一流程在 .github/workflows/ci.yml 的main-validation-and-syncjob 中有完整实现npm run sync:repo-state后校验无未管理漂移、拒绝过期发布test $GITHUB_SHA $(git rev-parse origin/main)随后用peter-evans/create-pull-request创建/更新 bot PR最后由 tools/scripts/merge_canonical_sync_pr.cjs 在精确检查通过后执行合并--skip-pages即对应Pages 不可被同步派发的约束。九、后续阶段每个阶段都需要前一阶段的证据文档给出七个渐进阶段每阶段激活前都必须有前一阶段的证据支撑在真实 PR 上观察影子路由准确率与误报率将剩余 release 写入者迁移到受保护 release PRcanonical CI、hygiene 与 contributor-sync 写入者已走 bot PR 通道保持main由稳定的 app 绑定检查保护移除任何新引入的直接写入者增加 schema 校验的 fork 安全语义审查其特权代码始终来自受保护 base构建确定性 release-candidate PR渲染与发布分离扩展不可变上游提交/路径/hash 来源provenance当前第一个窄幅 delta 例外账本仅覆盖维护者验证过的source_repo重命名更宽泛的来源例外不在范围内仅在经验证实的文档或元数据类别上考虑自动合并新 skill、安全敏感内容、工作流、安装器、release、来源例外与策略变更始终是人工决策。最后文档明确两点边界merge queue 不属于当前计划——仓库为个人所有工作流目前不支持merge_group事件同时贡献者信用contributor credit必须通过受保护 squash 合并保留见 .github/MAINTENANCE.md 中Contributors must get credit的指令。十、实战对照维护者如何运行这一套机制将上述机制落到日常维护关键入口集中在 docs/maintainers/merge-batch.md# 批量按序合并GitHub 唯一 squash 合并派生工作交给 canonical-sync PR 通道 npm run merge:batch -- --prs 450,449,446,451 # canonical skill 子树有变更时审查后证明精确 head npm run merge:batch -- --prs 450 --reviewed-head 40-character-head-sha # 仅演练本地分类不批准运行也不合并 npm run merge:batch -- --prs 450 --dry-run前置条件包括干净的main且与origin/main完全一致、真实合并要求上述服务端严格保护dry-run 不需要、gh已用维护者权限认证、以 .github/MAINTENANCE.md 为治理政策。若出现CONFLICTING、需要源码改动的检查失败、README 致谢需人工决策、外部 PR 包含符号链接/gitlink/可执行模式/未知类型/超大 blob、工作流无法绑定到 PR 编号head SHA、Fork 批准或分支权限缺失、无法证明main的有效严格保护等情形应立即停下转入 docs/maintainers/merging-prs.md 人工流程。已审 Fork 捆绑例外PR #1337 与 #1413记录在 tools/config/reviewed-fork-skills.json仅允许该 skill 的scripts/子树内 Python 文件与根LICENSE的只读 Git copy 来源任何变更都会使例外失效。结语agentic-awesome-skills 的 PR 自主化设计本质上是把信任做成了显式可验证的工程对象低权限 CI 只生产带untrusted_advisory标记的证据影子路由只观察不执行merge:batch在受信main上完成八步重算并以服务端严格保护为硬前提canonical-sync 则以bot PR 显式派发 字节级复现隔离所有生成态写入。这套分阶段路径保证了自动化每前进一步都有前一阶段积累的实测证据支撑——而新 skill、安全内容与策略变更在可预见的阶段内始终保留给人类决策。【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,115 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/gh_mirrors/an/agentic-awesome-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考