sjskills

sjskills

使用 sjskills，根据项目已提交的 sjskills.toml 或工具固定的全局基线，协调精确的技能状态。该工具负责经验证的放置、来源信息、隔离和恢复；不会发布源代码更改，也不会临时从目录安装内容。

严格同步仅涵盖选定的全局或项目 .agents/skills 和 .claude/skills 根目录。未声明的目录会移入可恢复的隔离区，包括未知副本和本地修改过的副本。内置技能、插件缓存和旧版 Pi 副本不在此范围内。

之前由工具管理的目标副本若有本地编辑，也会先保存在隔离区，然后替换为经验证的已发布内容。计划会将这些情况报告为更新，原因是 local-modification。这要求同一来源具有可信的来源信息，且当前树可验证；未知的目标副本仍会阻止协调。恢复经过编辑的字节不会授予所有权。

请区分以下四种状态：

1. 源代码仓库的本地目录可编辑，但尚未发布。
2. 注册表标识协调可使用的已发布远程内容。
3. 项目已提交的 sjskills.toml 选择项目配置和直接声明。
4. 注册表定义一个固定且与机器无关的全局基线。

优先使用 PATH 中的 sjskills。在该工具的源代码仓库中，如果未安装该命令，请使用 bin/sjskills。除非用户提出要求，否则不要安装该命令或更改 PATH。

阅读状态检查，了解状态命令、新鲜度、提示信息和 JSON 解读。创建或更改配置，或解决经过身份验证的来源要求时，请阅读项目选择。仅凭状态或配置本身，都不足以授权协调。

对请求进行分类

• 同步已配置状态： 未限定范围的同步或协调此技能请求，同时授权固定的全局基线和当前项目已提交的 sjskills.toml（如果存在）。遵守明确指定的仅限项目、仅限全局、机器范围或保留限制。如果不存在项目清单，只协调全局基线并报告项目尚未配置；不要初始化项目，也不要根据已安装副本推断配置文件。
• 说明或检查： 使用 status 检查两个范围，使用 profiles 查看可用选择，或使用 plan / plan --global 全面检查所选范围。这些操作会保留受管理的根目录，但可能会临时获取预期内容。不带操作的直接调用默认进行状态检查。
• 配置项目： 当用户要求采用受管理的项目技能或更改选择时，创建或编辑 sjskills.toml。使用所选配置文件、直接声明，或参照项目选择说明同时使用两者。保留无关条目；仅配置并不授权执行应用操作或更改全局设置。
• 协调项目： 检查 plan；只有在用户要求安装、引导、协调或同步项目时才运行 apply，然后再次运行 plan。
• 恢复项目状态： 仅恢复用户指定的确切隔离标识符，并且只有在确认所有建模目标位置均不存在后才执行。
• 全局协调或恢复： 在进行全局变更前，阅读 references/global-rollout.md。同步请求即授予协调权限；自行准备并审查所需证据，不要要求用户批准哈希值。恢复操作仍需用户提出包含隔离标识符的请求。

使用常规 Skills CLI 工作流来发现源技能名称或执行用户要求的临时安装。对于由 sjskills 管理的项目，在 [[direct]] 中记录外部技能，并通过 sjskills 进行协调；在受管理根目录中未声明的临时安装将成为隔离候选项。Codex 插件应使用仓库的插件工作流。本地目录验证和发布不属于协调操作。

使用已配置的授权

请求授予权限；已提交的清单和固定基线定义期望集合。在该集合的受管理根目录中，继续执行已验证的安装、更新（包括隔离并替换本地编辑过的受管理副本）、来源信息迁移，以及对未声明副本进行可恢复的隔离。应用前概述已审查的操作，无需再等待用户回复。除非用户要求交互式检查点，否则对已获授权的应用操作使用 --yes。标志或计划产物不会产生授权。

遵守明确要求保持本地编辑生效或保留特定路径的请求：如果计划会替换或隔离这些内容，则停止受影响范围的操作。常规同步已授权在替换前将本地编辑内容保留在隔离区；无需覆盖标志或额外确认。

“覆盖并同步”无法解决未受管理的期望副本、来源不匹配、来源信息损坏、不安全边界或物化失败等问题。遇到这些冲突时，停止受影响范围的操作，并说明需要采取的具体解决措施。不要强行采纳、手动替换根目录、更改配置文件或加入另一台机器来让计划通过。除非用户要求全有或全无的结果，否则继续完成不受阻的独立范围。

项目工作流

1. 解析命令和项目根目录。如果不存在 sjskills.toml，除非用户要求采用或初始化，否则停止。
2. 对于包含配置档案的新清单，运行 sjskills profiles，使用用户选择的配置档案，并运行 sjskills init <profile> ...；然后添加请求的直接声明。对于仅包含直接声明的采用操作或现有清单，请参阅项目选择参考。不要根据已安装的副本推断配置档案，也不要用 init 覆盖现有清单。
3. 阅读清单并运行 sjskills plan。总结安装、更新、隔离、未更改的放置项、手动管理或由工作流管理的条目、警告和阻止项。 区分期望状态偏差或冲突与命令、网络请求或实体化失败；操作失败不构成有效计划。
4. 将 local-modification 更新作为保留并替换操作进行审查，包括当前树已与已发布的树匹配、但与其记录的安装状态不一致的情况。对于未受管理的期望副本、源不匹配、格式错误或不可信的来源信息、不安全的文件系统边界、无法验证的额外内容、实体化失败或其他冲突，在应用前停止。
5. 对于已授权的项目协调，在计划通过审查后运行 sjskills apply --yes。遵守任何明确要求停留在预览阶段或保留交互式确认的请求。
6. 再次运行 sjskills plan。如果仍有变更或阻止项，不要声称状态完全一致。在正常工作周期内保留所有报告的隔离标识符。

当注册表支持的源中预期内容发生变化时，协调只能使用已发布的远程内容。不要应用仅存在于本地的更改。如果请求发布，请遵循源代码仓库关于验证、审查、提交和发布的说明；这些操作不属于此技能的范围。协调前，解析注册表源，并验证其固定的远程引用包含每个预期技能树。注册表指向其他位置时，本地提交或功能分支提交并不足够。

恢复

将恢复视为单独的变更操作。要求用户指定隔离标识符，检查其当前状态，并确认所有目标位置均不存在。运行：

sjskills restore <quarantine-id>

不要为了成功恢复而移动、删除或覆盖活动目标。如果内容或来源信息发生变化，请保留双方并报告冲突。恢复不会使未知副本或本地修改的副本归属到受管理范围。经过编辑的备份会替换新安装的来源信息，不留下所有权记录。之后运行 sjskills plan：恢复后未声明的技能属于移除偏差；恢复后经过编辑的期望技能属于未受管理的冲突。

全局边界

全局协调使用固定且与机器无关的基线。配置档案用于选择项目技能；不要虚构全局配置档案，不要根据主机名推断，也不要合成 Pi 专用副本。检查请求只运行 sjskills plan --global；已配置的同步仍须通过已验证的应用流程继续。

--approved-plan 和 --approved-plan-sha256 标志会将全局应用绑定到经 Agent 审查的证据。它们的名称并不要求单独的人为审批流程：创建该文件，检查每项操作和警告，计算其摘要，并在应用和最终计划中使用同一个已验证的可执行文件。同步请求涵盖这项工作；审计、仓库验证或无关的设置请求则不涵盖。恢复和冲突解决仍与使已配置的期望集合完全一致相互独立。

完成情况

报告：

• 项目级或固定全局范围，以及工作是只读还是会产生变更；
• 适用时，所选配置文件或直接清单声明；
• 计划和最终计划的结果，包括剩余的额外项、阻塞项和范围外的旧状态；
• 涉及远程支持的本地变更时，提供已发布引用的证据；
• 保留或恢复的每个隔离标识符；以及
• 仍在等待明确授权的任何变更。