【免费下载链接】OpenShellOpenShell is the safe, private runtime for autonomous AI agents.项目地址https://gitcode.com/gh_mirrors/op/OpenShell点击查看免费下载OpenShell 是一个 agent-first 项目仓库内大量文件技能清单、工作流链、架构表、Issue/PR 模板、跨文件引用相互引用任何一处改动都可能造成文档漂移。本文基于仓库内的 sync-agent-infra 技能定义 完整讲解其一致性问题域、漂移检查清单、结构化漂移报告格式与修复策略并结合 AGENTS.md、CONTRIBUTING.md、README.md 及技能目录的实际状态给出可复用的核查方法。读完本文你可以在本仓库中独立完成一次全量 Agent 基础设施一致性审计并在技能、crate、工作流变更后快速定位并修复所有引用漂移。什么是 Agent 基础设施漂移在 OpenShell 中Agent 基础设施指的是那组相互引用、必须保持一致的文件集合。技能skill被重命名后如果模板、文档、工作流链中仍有旧名Agent 按图索骥时就会走到死路。sync-agent-infra技能的核心职责就是检测并修复这类漂移。该技能定义.agents/skills/sync-agent-infra/SKILL.md开头明确声明这些文件references each other and must stay consistent相互引用且必须保持一致。被追踪的文件清单如下文件追踪内容AGENTS.md项目身份、工作流链、架构概览、Issue/PR 约定、技能维护指针CONTRIBUTING.md技能表、工作流链、何时开 Issue 指引、技能引用CONTRIBUTING.md 的 Issue 生命周期章节面向人类的 Issue 状态、roadmap 决策、验收信号、直接指令与队列模式下的 Agent 职责README.mdUse OpenShell with Your Agent 与 Built With Agents 章节.github/ISSUE_TEMPLATE/bug_report.yml诊断指引中的技能名引用.github/ISSUE_TEMPLATE/feature_request.yml调研指引中的技能名引用.github/ISSUE_TEMPLATE/config.yml联系链接文本中的技能引用.github/workflows/issue-triage.yml评论文本中的技能引用.agents/skills/triage-issue/SKILL.md门控检查与诊断步骤中的技能名引用skills/*/SKILL.md面向用户的独立操作指引以及指向文档、附带文件和关联技能的链接.agents/skills/create-github-pr/SKILL.md提 PR 前的 Agent 基础设施检查.agents/skills/review-github-pr/SKILL.md评审时的 Agent 基础设施检查.agents/skills/build-from-issue/SKILL.md标签感知与提交前的 Agent 基础设施检查.claude/agents/principal-engineer-reviewer.md文档引用共享的评审时 Agent 基础设施检查何时应运行该检查技能文档给出了明确的触发时机清单覆盖变更之后与提交之前两类场景在skills/或.agents/skills/中新增、删除、重命名或移动了技能之后在crates/中新增、删除或重命名了 crate 之后技能之间工作流链关系发生变化之后某个技能覆盖的产品域或开发域发生变化之后修改了 Issue 或 PR 模板之后打开一个触及上述任何文件的 PR 之前。也就是说它既是事后核对工具也是提 PR 前的准入检查项——后一点可以通过 create-github-pr 和 review-github-pr 两个技能在流程中被强制执行。技能维护路由图变更域 → 需要复查的技能当产品行为、命令或开发工作流变化时文档提供了一张变更域 → 技能路由表用于快速定位需要同步更新的技能。它被明确定位为路由辅助工具而非穷举依赖清单并附有一条关键纪律在下结论前必须在skills/和.agents/skills/两个目录中同时搜索变更的命令、字段、组件或工作流。变更域需要复查的技能CLI 命令、参数、默认值或工作流openshell-cli沙箱策略 schema、预设或执行行为generate-sandbox-policy、openshell-cliSupervisor 中间件策略、注册、运行时或故障行为generate-sandbox-policy、openshell-cli、debug-openshell-cluster网关部署、Helm、运行时驱动或健康检查debug-openshell-cluster、helm-dev-environment推理提供商、原生模型端点或从已退役托管端点的迁移debug-inference、openshell-cli、generate-sandbox-policyTUI 架构、导航、数据获取或 UXtui-development发布产物或发布后冒烟覆盖test-release-canaryGitHub Actions 工作流、必需检查项或 CI 诊断watch-github-actions发布冒烟覆盖方面还有test-release-canaryGator 测试框架、沙箱镜像、监督或模型覆盖launch-openshell-gatorSBOM 生成、依赖元数据或许可证工作流sbomIssue 模板、标签、贡献门控或 spike/build 工作流triage-issue、create-spike、build-from-issue、create-github-issuePR 模板、评审约定或 vouch 机制create-github-pr、review-github-pr、build-from-issue安全评审或漏洞修复工作流review-security-issue、fix-security-issueRFC 模板、编号或生命周期create-rfc文档结构、导航或文档更新工作流update-docs-from-commits技能、crate、工作流链、Issue/PR 模板或 Agent 交叉引用sync-agent-infra本技能这张表本身就是自我维护的第 4 步修复动作中专门有一条技能覆盖域变化 → 更新本文件中的维护路由图及受影响的交叉引用确保路由表不落后于现实。前提在仓库根目录执行文档的 Prerequisites 只有一条必须位于 OpenShell 仓库根目录。因为所有清单命令ls -1 skills/等和路径约定都以仓库根为基准脱离根目录执行会得到错误的漂移结论。第 1 步盘点当前状态盘点的目的是为每一类实体收集事实来源source of truth后续所有比对都以盘点结果为准。技能盘点公共技能与贡献者技能必须分开列ls -1 skills/ ls -1 .agents/skills/两个目录按受众划分且这是规范性约定skills/存放可公开发布、可安装的用户/运维技能.agents/skills/存放面向贡献者和维护者的内部工作流。文档的原话是Every other file must agree with both inventories其他所有文件都必须与这两份清单保持一致。在当前仓库中实际验证这一约定skills/ 目录下恰好有 4 个公共技能——openshell-cli、generate-sandbox-policy、debug-inference、debug-openshell-cluster而 .agents/skills/ 目录下有 18 个内部技能包括triage-issue、build-from-issue、create-github-pr、review-github-pr、helm-dev-environment、watch-github-actions、test-release-canary、launch-openshell-gator、sbom、sync-agent-infra等。Crate 盘点ls -1 crates/当前仓库的 crates/ 目录包含 38 个 crateopenshell-cli、openshell-server、openshell-sandbox、openshell-supervisor、各计算驱动openshell-driver-*、openshell-prover等这个清单将作为第 2 步核对 AGENTS.md 架构表的基准。工作流链规范的工作流链定义在 AGENTS.md 的 ## Workflow Chains 小节中——该小节是技能管线的唯一事实来源。当前 AGENTS.md 定义了四条链Community inflow社区流入triage-issue→ 人工判定与 roadmap 归位 → 需要时create-spike→build-from-issueInternal development内部开发create-spike→ 人工判定与 roadmap 归位 →build-from-issueSecurity安全review-security-issue→fix-security-issuePolicy iteration策略迭代openshell-cli→generate-sandbox-policy。CONTRIBUTING.md 中也有对应的工作流链小节两者必须逐字一致。标签Label清单规范标签集被技能与模板共同使用。关键标签包括state:triage-needed、state:needs-info、state:validated、state:accepted、agent:plan-requested、agent:plan-ready、agent:implementation-requested、agent:in-progress、agent:pr-opened、roadmap、topic:security、good first issue、help wanted、spike以及相关的area:*、topic:*、integration:*、test:*系列。文档特别强调了一条语义规则这是很多漂移检查容易漏掉的细节生命周期标签与agent:*请求标签只门控无人值守的队列拾取并不阻止用户的直接指令——当用户直接要求某个阶段时Agent 会对每个缺失或不完整的工作流标签发出警告然后不改标签、继续执行所请求的阶段。AGENTS.md 的 Issue and PR Conventions 一节也重复了相同语义an explicit user instruction authorizes an agent … the agent warns the user and continues without changing those labels两处表述必须同步。第 2 步逐文件检查漂移对第 1 步表中的每个文件按下述清单检查不一致项。CONTRIBUTING.md的检查项公共技能表——skills/中每个技能都必须出现在 Skills for Using OpenShell 表中且不得混入任何贡献者技能贡献者技能表——.agents/skills/中每个技能都必须出现在 Agent Skills for Contributors 表中且不得混入任何公共技能清单路径——两张表中任何技能都不应引用不存在的目录工作流链——必须与 AGENTS.md 的工作流链完全一致正文中的技能引用——任何被点名的技能必须恰好存在于两个技能目录之一。对照当前仓库CONTRIBUTING.md 的两个表格正是按此组织的Skills for Using OpenShell 表列出 4 个公共技能Agent Skills for Contributors 表按 CategoryContributing / Reviewing / Triage / Platform / Documentation / Maintenance / Reference分组列出内部技能且sync-agent-infra自身也出现在 Maintenance 行中。AGENTS.md的检查项架构概览——crates/中每个 crate 都必须出现在架构表中且python/、proto/、deploy/、.agents/等行也必须存在技能布局——架构表必须包含skills/与.agents/skills/两个独立行受众描述准确工作流链——验证链中命名的每个技能恰好存在于两个技能目录之一Issue/PR 约定——验证被引用的技能create-github-issue、create-github-pr、build-from-issue存在技能维护指针——验证指针仍然指向sync-agent-infra且不重复本技能中的维护路由图。当前 AGENTS.md 的架构表满足这些要求38 个 crate 各有对应行表尾还有skills/Public agent skills、.agents/skills/Contributor agent skills、.agents/agents/等行AGENTS.md 附近的维护指针写的是 Use thesync-agent-infraskill for the maintenance map and consistency checks只指向技能而不内嵌路由图符合第 5 条不重复维护图的要求。Issue 生命周期文档的检查项CONTRIBUTING.md 的 Issue 生命周期章节中状态、roadmap、验收信号、Agent 工作流的含义必须与 AGENTS.md 一致调用模式——生命周期标签与agent:*请求标签必须门控队列拾取但不阻断直接指令直接模式警告——指引必须要求 Agent 对每个缺失或不完整的工作流标签警告、继续所请求阶段、且不改动标签。这三条本质上是在校验同一套语义在两份文档中的表述等价性属于纯文本层的漂移容易被简单的技能名是否存在检查漏掉。README.md的检查项公共安装指引——README 必须区分skills/与.agents/skills/包含npx skills add NVIDIA/OpenShell命令且只把规范的公共技能列为可安装项Built With Agents 章节——贡献者技能名必须存在于.agents/skills/工作流描述必须与 AGENTS.md 的链一致。当前 README.md 中确实存在 Use OpenShell with Your Agent 与 Built With Agents 两个章节后者的维护段落点名了sync-agent-infra与update-docs-from-commits等内部工作流——这些名字都对应.agents/skills/下真实存在的目录。Issue 模板的检查项bug_report.yml——必须收集 User Story、Problem Statement、Impact / Why This Matters、Acceptance Criteria、Reproduction Steps、Environment日志可选且必须与 bug 相关不得强制报告者提供诊断信息feature_request.yml——必须收集 User Story、Problem Statement、Impact / Why This Matters、Proposed Design、Acceptance Criteria、Alternatives Considered设计部分只描述工作流与可观察行为、不规定内部实现Agent 调研为可选项config.yml——联系链接中的技能分类描述必须准确。AGENTS.md 的 Issue and PR Conventions 对模板字段有等价描述Bug reports and feature requests must include a User Story, Problem Statement, Impact / Why This Matters, and Acceptance Criteria …两者构成互相校验的证据链。Issue 分诊工作流的检查项.github/workflows/issue-triage.yml 中重定向评论文本里出现的技能名必须存在。技能交叉引用的检查项triage-issue——门控检查与诊断步骤中引用的技能必须存在openshell-cli——伴随技能表companion skills table中的条目必须恰好位于一个规范位置build-from-issue——标签名必须与项目标签体系匹配生命周期与请求标签门控无人值守队列拾取而直接请求在发现工作流不一致时警告后继续create-spike——其中下一步指向build-from-issue的引用必须准确review-security-issue/fix-security-issue——两者之间的互相引用必须准确对应工作流链 Securityreview-security-issue→fix-security-issuePR 创建与评审检查——create-github-pr、review-github-pr、build-from-issue及 principal-engineer-reviewer 子代理定义对sync-agent-infra的引用必须存在且其触发条件与本技能一致。技能布局、元数据与可移植性检查项这是八条中信息密度最高的一组涉及公共技能必须能脱离源码树独立运行这一设计约束放置位置——4 个公共技能openshell-cli、generate-sandbox-policy、debug-inference、debug-openshell-cluster只能位于skills/其余所有仓库技能只能位于.agents/skills/内部元数据——每个.agents/skills/*/SKILL.md必须设置metadata.internal: true公共技能不得设置该元数据。文档明确把它当作发现过滤器而不是访问控制边界名称唯一——解析两个根下所有SKILL.md的name字段每个名称必须全局唯一且与文档清单一致本地引用——技能内每个相对 Markdown 链接与被引用文件必须能在该已安装技能目录内解析除非是显式的已发布 URL规范路径——贡献者技能中如指明某公共技能的源码位置必须写skills/name/...绝不能写.agents/skills/name/...公共可移植性——公共技能不得依赖仓库相对路径下的docs/、architecture/、crates/、deploy/、.agents/文件不得要求源码构建、mise或仓库 E2E 工作流。命令语法以已安装环境的openshell --help为准产品文档以已发布的 OpenShell 文档站以.md结尾的 URL 可直接作为 Markdown 读取为准禁止复制规范文档——审查公共技能的参考文件与大段命令/schema 代码块删除只是照抄 CLI help、策略 schema、架构文档或已发布运维文档的内容只保留技能特有的推理与真实交互示例发现验证——从干净检出或一次性副本中运行npx -y skills add . --list输出必须恰好列出 4 个公共技能检查后删除生成的锁文件或已安装目录。CONTRIBUTING.md 对第 2 条有完全一致的表述They are marked internal so the Agent Skills CLI excludes them from ordinary public discovery … Internal metadata is a discovery filter, not an access-control boundary.第 3 步报告漂移发现不一致时必须以固定结构输出漂移报告模板如下与技能文档中的模板逐段对应## Agent Infrastructure Drift Report ### Skills Inventory - PUBLIC ADDED (exists in skills/ but missing from CONTRIBUTING.md): list - PUBLIC REMOVED (documented as public but missing from skills/): list - CONTRIBUTOR ADDED (exists in .agents/skills/ but missing from CONTRIBUTING.md): list - CONTRIBUTOR REMOVED (documented as contributor but missing from .agents/skills/): list - METADATA/PATH/NAME ERRORS: list - OK: public count public and contributor count contributor skills consistent ### Architecture Table - ADDED (exists in crates/ but missing from AGENTS.md): list - REMOVED (in AGENTS.md but missing from crates/): list - OK: count components consistent ### Workflow Chains - STALE: chain name references non-existent skill skill - OK: count chains consistent ### Cross-References - file:line references non-existent skill skill - file:line references non-existent label label - The skill maintenance map has a stale or missing change-area mapping: details - OK: count references consistent如果未找到任何漂移报告固定为一句Agent infrastructure is consistent. No drift detected.这种模板化的报告格式本身就是漂移的一部分防线它把查了什么显式化技能清单、架构表、工作流链、交叉引用四个维度每个维度都有 OK 计数行使通过与失败都可被脚本化核对也为后续 Agent 或人类复查留下可追溯的凭证。第 4 步修复漂移修复动作按漂移类型编号列出共 8 类新增技能——把它加入 CONTRIBUTING.md 技能表的正确分类若它参与工作流链同时更新 AGENTS.md 与 CONTRIBUTING.md 中的链删除技能——从所有文件中移除并检查模板和其他技能中的残留引用重命名技能——更新所有文件中的每一处引用新增 crate——在 AGENTS.md 架构表中新增一行删除 crate——从架构表中删除对应行工作流链变化——同时更新 AGENTS.md 与 CONTRIBUTING.md 中的链若变化对用户可见还要更新 README.md 的 Built With Agents 章节技能覆盖域变化——更新本技能文件中的维护路由图及受影响的交叉引用或伴随技能表受众或可移植性漂移——把技能移到规范根目录、修正内部元数据、替换过期的公共技能路径、修复本地链接并把照抄的产品文档替换为 CLI 自发现--help或已发布文档链接。关键收尾约束修复完成后必须重跑第 2 步以验证一致性——即修复-再验证闭环防止修复本身引入新漂移。第 5 步总结变更最后用固定格式汇报修复内容示例## Changes Made - Updated CONTRIBUTING.md skills table: added skill - Updated AGENTS.md architecture table: removed crate - Fixed cross-reference in .agents/skills/triage-issue/SKILL.md: old → new仓库实况交叉验证这套检查如何落在当前代码库上把上述检查项与当前仓库实际状态对照可以看到sync-agent-infra并非纸面流程双目录约定成立skills/ 下 4 个目录与技能文档第 2 步技能布局要求的 4 个公共技能名单逐一对应.agents/skills/ 下 18 个内部技能目录且 CONTRIBUTING.md 的贡献者技能表按分类列出了其中的 18 项含build-openshell-mxc-windows、sbom等。工作流链双写一致AGENTS.md 与 CONTRIBUTING.md 中 Community inflow、Internal development、Security 等链的表述结构一致链中命名的技能triage-issue、create-spike、build-from-issue、review-security-issue、fix-security-issue、openshell-cli、generate-sandbox-policy在两个技能目录中均能找到对应目录。架构表与 crates 目录对应crates/ 的 38 个 crate 全部出现在 AGENTS.md 架构表中表尾按第 2 步检查项的要求保留了python/openshell/、sdk/typescript/、proto/、deploy/、docs/、skills/、.agents/skills/等行。维护指针唯一AGENTS.md 只以一句话指向sync-agent-infra未复制路由图符合指针不重复维护图的约束。README 双章节就位README.md 的 Use OpenShell with Your Agent 与 Built With Agents 章节存在后者点名的sync-agent-infra、update-docs-from-commits均对应.agents/skills/下真实目录。模板与工作流文件就位.github/ISSUE_TEMPLATE/ 下bug_report.yml、feature_request.yml、config.yml与 .github/workflows/issue-triage.yml 均存在构成模板侧检查的被检对象。小结sync-agent-infra的价值在于把文档一致性从模糊的维护责任转化为可执行的五步过程盘点以skills/、.agents/skills/、crates/、AGENTS.md 工作流链、标签集为事实来源→ 逐文件比对技能表、架构表、链、模板、交叉引用、布局与可移植性八条→ 结构化漂移报告 → 按类型修复并重验 → 变更总结。它针对的是 agent-first 仓库特有的风险当技能、crate 或工作流变化时一组相互引用的元文档会静默失步。文中所有检查项均可在当前仓库根目录下用只读方式复现——先ls -1 skills/ .agents/skills/ crates/再对照 AGENTS.md、CONTRIBUTING.md、README.md 的对应章节即可独立完成一次全量一致性审计。赞分享【免费下载链接】OpenShellOpenShell is the safe, private runtime for autonomous AI agents.项目地址https://gitcode.com/gh_mirrors/op/OpenShell点击查看免费下载相关推荐Plasticity命令系统深度剖析从Arc到Zone的完整命令清单Plasticity命令系统深度剖析从Arc到Zone的完整命令清单 Plasticity是一款强大的开源3D建模软件它以其直观的命令系统和专业的几何建模能You Dont Know JS 系列俄语仓库之《Types Grammar》附录 A混合环境中的 JavaScript 实战指南You Dont Know JS 系列俄语仓库之《Types Grammar》附录 A混合环境中的 JavaScript 实战指南 导读 本篇文章基教程文档TextureLab性能优化指南如何高效使用GPU加速功能提升纹理生成效率TextureLab性能优化指南如何高效使用GPU加速功能提升纹理生成效率 TextureLab是一款免费、跨平台的GPU加速程序化纹理生成器它利用现代GP上一篇async-http-client异常监控指南完整手册下一篇Blinko数据安全终极指南如何实现笔记备份与恢复零风险创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
