repo-harmonization

仓库协调

如果斜杠命令或美元符号命令已将这些说明添加到对话中，请直接遵循。在这种情况下，不要再通过技能工具调用此技能。

使用一组相互依赖的仓库，产出经验证的发现、经用户批准的决策以及精准修改。 审计涵盖两类工作：

• 对齐：仓库之间的偏差、过时的交叉引用、重复内容和相互竞争的工作流。
• 转移：一个仓库使用得当、其他仓库也能受益的 Agent 指引、工作流和依赖项。针对接收方的惯例调整每项转移。

参数

$ARGUMENTS 是以空格分隔的仓库路径列表。允许展开波浪号。

• 至少需要两个路径，且每个路径都必须是现有的 Git 仓库根目录，并且解析后指向不同的仓库。清单辅助工具会强制执行这些规则；遇到不符合要求的输入时会以状态码 2 退出，并指出相关输入。此时请停止并转达其消息。
• 用户的请求（而非 $ARGUMENTS）可以将重点限定为对齐或转移。若无此类请求，则两者都要执行。传递给清单辅助工具的内容只能是仓库路径。唯一例外是模板偏差中的 --drift 标志。
• 不要根据链接、远程仓库或已安装副本推断其他仓库。提供的列表定义了审计范围。

约定

• 任何编辑前都要先调研，并严格保持调研只读。宿主环境支持子 Agent 时，应并行开展调研；否则，按顺序进行。
• 使用差异比较、内容哈希、重新生成后的往返校验或符号链接解析，以机械方式验证每项对齐或重复声明。绝不能只凭文字检查。每项发现都要附上文件和行号证据。
• 将每个仓库同时视为供体和接收方。对每项迁移候选内容，分别评估供体、实践和接收方。
• 一个迁移单元是一项实践：指导规则或项目技能、工作流（任务方案、脚本、CI 作业、钩子、工具链固定、lint、格式化、类型检查、测试或发布配置），或依赖项及其使用该依赖的工作流或代码。绝不要迁移接收方用不到的依赖项。
• 为每项迁移候选内容附上证据。提供供体中展示该实践及其实际运行情况的文件和行号（例如由任务、CI、钩子或代码调用）。还要提供接收方的搜索命令，以证明该实践缺失；搜索时须包含以其他名称实现的功能等效项，并提供接收方中说明其所解决需求的证据。
• 每项实质性发现只能归类一次，类别须来自整合与评估。
• 应做适配，而非照搬。根据接收方的语言、运行时版本、包管理器、任务运行器、命名、文件布局、格式和指导文风，改写每项迁移内容。迁移后的指导只能提及应用计划后接收方中实际存在的命令、路径和工具。
• 绝不要将供体中的机密、凭据、个人身份信息、主机名、地址，或项目专属名称和假设带入接收方。
• 优先采用精简修复，而非重构。除非能减少的复杂度大于新增的复杂度，否则不要引入 include 流程、模板层、共享参考资料或其他机制。
• 优先选择能实现收益的最小迁移：优先采用任务方案，而非新增脚本；配置文件，而非封装器；简短规则，而非整篇复制文档。共享包、模板仓库、同步流水线和子模块需逐案判断。
• 所有需逐案判断的事项都要先提交给用户，再制定计划。绝不要超出已批准的决策范围。
• 将已批准的结果及已解决的逐案判断视为实施授权边界，而非最初的文件清单。实施过程中发现完成这些决策所需的相关仓库内前置条件时，协调者可扩展清单、为新增范围协调权限，并委派所需的最小后续修复，无需再次询问。例如：开发依赖项、锁文件更新、配置存根或忽略规则。工作代理仍须严格遵守分配给自己的写入范围，并向协调者返回证据。
• 遵守每个仓库的生成流水线和钩子。只编辑规范来源文件。通过仅构建、不提交的流程重新生成产物。让设计为提交时运行的钩子在提交时运行。
• 不得让实施代理提交或推送。协调者按仓库提交，提交范围限于任务文件，并遵守宿主环境的协调和共享工作树规则。
• 在阶段变更时报告进度，并提供实际计数（已盘点的仓库数，以及已发现、已验证、已分类和已实施的发现数），而非耗时。

采集信息

使用提供的路径运行一次清单辅助脚本，并从此技能目录解析脚本路径。在运行任何可能重新生成、安装或以其他方式修改工作树的命令之前，先运行该脚本：

bun run "<skill-dir>/scripts/inventory.ts" <repo-path> <repo-path> [more-repos...]

该脚本会向标准输出打印一个 JSON 文档（schemaVersion: 1），输入无效时以状态码 2 退出，且不会产生其他副作用：

• repos[]：id、input、root、head、dirty（porcelain 格式的行）、packageManagers、ecosystems（每个生态系统解析出的依赖项数量）、files.guidance、files.workflow、files.manifest（已跟踪的路径）、tasks[]（runner 为 just 或 package.json，并包含 file 和 name），以及记录无法解析内容的 notes。
• dependencyGaps[]：某个生态系统中部分仓库存在、但并非所有仓库都存在的依赖项，包含 presentIn（仓库、清单、分区、规格、使用次数）和 missingIn。脚本会解析 package.json、pyproject.toml（uv：[project]、[dependency-groups]、[tool.uv]）、Cargo.toml 和 go.mod（直接的 require 和 tool 条目），并跳过工作区本地包。
• taskGaps[]：部分仓库存在、但并非所有仓库都存在的任务名称。
• summary：每个生态系统和任务的共享项及缺失项计数。

将 JSON 保存到主机的临时目录或暂存目录，并使用 jq 查询，而不要重新完整加载该文件。

• 后续收集证据时，将每个 root 视为已检查仓库的根目录。报告中保留每个 input 的原始形式。
• 将每个 dirty 列表视为研究前的 git status 快照。将这些预先存在的未提交修改视为其他 Agent 正在进行的工作：这是保护边界，绝不可将其作为审计目标、转移来源或转移目标。
• 只有在当前分支和远程配置会影响安装、发布或跨仓库引用时，才记录每个仓库的这些信息。
• 将文件列表视为初始清单。指导文件包括 AGENTS.md、CLAUDE.md、GEMINI.md、CONTRIBUTING.md、Copilot 和 Cursor 规则、.mcp.json，以及 .agents、.claude、.codex、.cursor、.gemini 和 .windsurf 下的入口文件。工作流文件包括任务运行器、CI、钩子、工具链版本固定文件和工具配置。快速检查每个仓库根目录和 CI 目录，查找清单遗漏的内容；并阅读清单中列出但尚未解析的清单文件，例如 requirements*.txt、foundry.toml、.gitmodules、Gemfile 和 composer.json。
• 阅读每个仓库的 README 和顶层指导文件，记录其概况：用途（库、应用、CLI、服务、目录）、语言、运行时和工具链版本、包管理器、任务运行器、CI 提供商，以及已配置的 Agent 客户端。适配决策取决于这些概况。

在得出结论前，先建立初步链接图。将链接图视为清单，而非两个文件应共用同一来源的证明。来源不明时应记录为未知。路径相似并不能证明两者有关联。

• 映射指向所列仓库之间的符号链接，包括其解析后的目标。将每个符号链接从其所在仓库解析，以区分有意指向仓库外部的符号链接和已断开的符号链接。
• 映射由另一个所列仓库生成的文件。在可能的情况下，标明已声明的来源。记录能够确立每种生成关系的生成器命令或清单条目。
• 映射会在仓库之间传递制品、技能、包或配置的安装和发布流程。注明每种流程是否会修改文件、创建外部状态，或仅验证源制品。
• 搜索 AI 上下文文件中对其他所列仓库的引用，包括 AGENTS.md、CLAUDE.md、README 指南、技能和本地说明。记录具体路径、命令或仓库标识符，而不只是其周围的说明文字。

模板漂移

当一个仓库是另一个仓库的模板时，请在运行清单辅助工具之前运行漂移表：

bun run "<skill-dir>/scripts/inventory.ts" --drift <template-root> <project-root>

辅助工具会输出一张 Markdown 表格，包含 surface、template、project 和 status 列。输入无效时会以状态码 2 退出， 且不会产生其他副作用。

• 该表格会双向比较以下内容：package.json 脚本和 devDependencies、lint 和格式化配置、tsconfig*.json 文件及其 compilerOptions 键、justfile 配方名称、git hooks，以及 CI 工作流文件。
• 对于配置、hook 或工作流文件，其值为简短的内容哈希。超过 60 个字符的值会以省略字符数结尾。
• status 为 same、missing-in-project、missing-in-template 或 differs。

将该表格用作这些内容的漂移清单：

• 将每个状态不是 same 的行视为漂移候选。分类前先通过 diff 验证。
• 对于每个内容项，让用户选择方向：从模板同步到项目、从项目同步到模板，或不做更改。
• 按照实施并收尾中的要求，逐项应用获批的同步方向。
• 绝不自动应用任何行，即使方向看起来显而易见。

调研

• 将仓库或其相互独立的子系统分配给不超过三名只读调查人员。为每人限定路径范围，并提供相同的仓库边界、辅助工具 JSON 路径和未提交文件列表。要求提供证据，而不是提出修改建议。
• 如果宿主环境无法运行调查人员，则按相同分工依次开展调研，不得降低证据标准。
• 每名调查人员都要针对其负责范围返回一致性证据和实践清单。若任务文本缩小了关注范围，则只收集匹配的部分。

一致性证据

• 梳理规范来源与生成产物之间的关系，以及生成产物的确切构建流水线。确定某个文件的规范来源归属前，先阅读构建配置和生成器输入。
• 找出重复和近似重复的指令、文档及脚本内容，并精确引用重复内容所在的两处。
• 使用适用于对应产物格式的标准化 diff 或内容哈希，验证疑似重复内容。精确副本使用字节比较；声称内容近似重复时，说明所用的标准化方法。
• 识别漂移，包括过时路径、版本不匹配、互相矛盾的规则和未发布的更改。针对相关规范来源、当前有效路径、版本来源或可复现命令，举证证明疑似漂移。
• 指出过时引用时，标明引用该内容的文件及其目标，而不只是给出仓库范围内的搜索结果。
• 找出用于完成同一任务的不同工作流。说明它们的输入、输出、副作用、文档中记载的触发条件，以及各自使用的规范来源。
• 找出对其他每个列出仓库的引用，并确定每个引用是否仍然有效。如果本地引用和远程或已发布的引用同时存在，应分别检查。
• 归类结果时，将生成产物与其来源区分开来。

实践清单

• 指导内容：规则、约定、命令、项目技能、hooks、权限和 MCP 服务，并分别标记为可移植或项目专属。
• 工作流：任务及其运行的命令、检查或生成的内容，CI 作业及其触发条件、hooks、工具链固定版本，以及 lint、格式化、类型检查、测试、覆盖率、安全、依赖更新和发布工具。
• 依赖项：与工具或共享关注点相关的差距矩阵条目，以及仓库使用每项依赖的方式（配置、任务或导入，注明文件:行号）。

综合整理

• 将所有调查结果整合为一份有证据支撑的全貌，并保留每项主张的来源。通过重新运行机械化检查来解决分歧，而不是选择说服力更强的文字描述。
• 由协调器构建跨仓库矩阵。针对每项实践，记录哪些仓库已采用该实践、采用了等效做法，或完全没有。根据功能而非名称判断是否等效：oxlint 与 eslint、just check 与 npm run lint、ruff 与 flake8 加 black。
• 通过搜索工具名称、配置文件、命令和功能等效项，以机械化方式核实每个接收仓库的缺项。记录命令和结果。
• 按每个迁移方向评估适配性：生态系统和运行时兼容性（engines、requires-python、rust-version、go 指令、peer 约束）、接收仓库的用途、冲突的工具或有文档记录的策略，以及维护或 CI 成本。概念层面的实践可以跨生态系统迁移（例如类型检查门禁、限定范围的格式化规则）。依赖项只能在同一生态系统内迁移，或迁移为经批准的生态系统等效工具。
• 跳过接收仓库已通过更广泛范围获得的指导，例如 Agent 上下文中加载的全局或父目录指令文件。重复添加只会增加上下文，不会改变行为。
• 对于工具候选项，在成本较低时以只读方式预览其影响：通过临时运行器（bunx、npx、uvx、go run、处于检查模式的 cargo）运行工具，不写入仓库文件；使用 git status --short 确认，并附上违规数量、可自动修复数量等统计。
• 在研究时通过接收仓库的包管理器检查当前注册表版本和运行时要求。实施时再次检查。

整合与评估

• 合并重复的观察结果，但不要丢弃最有力的文件名与行号证据以及机械证据。若关联但不完全相同的观察结果需要不同的修复或决策，则将它们分开保留。
• 合并来自多个供体、针对同一实践的迁移候选项。选取实现最完善的供体作为范例，并注明其他供体。
• 不要将未经核实的疑虑归类。将其退回研究阶段，或记录为待解问题。
• 通过仅限构建的路径重新生成疑似生成副本偏差，并通过 diff 对结果进行逐字节验证。保留重现验证所需的生成器输入和命令输出。
• 解析符号链接并比较其目标，然后再判定链接内容重复或存在差异。
• 将客观上有问题的引用与关于保留多少重复上下文的偏好区分开来。

将每项实质性发现恰好归类一次：

1. 确认存在偏差，需修复：通过机械方式证明其与规范来源、实际路径、版本来源或可复现命令不一致。
2. 单一来源候选项：确实存在重复内容，可由一个规范来源替代。由用户决定是否实施。
3. 建议迁移：有明确收益、已验证存在缺口、生态系统兼容、不与现有工具或已记录政策冲突，且成本低。
4. 需权衡的选择：替换或退役现有工具或竞争性工作流；引入新的生态系统、运行时、任务运行器、服务或必需的密钥；显著增加 CI 成本；涉及许可证问题；改变政策的指导，例如提交、发布或审查规则；新检查发现的既有违规（修复、建立基线或放弃）；精简重复材料的深度；以及发布或暂缓发布。
5. 有意不变或拒绝：有意或必要的重复、生态系统不匹配、项目特定做法、已有等效方案、价值较低，或与接收方记录在案的政策冲突。

若证据支持将自包含制品或独立安装的技能等副本视为设计约束所保护的内容，则将其标记为有意重复。即使副本逐字节相同，也应将自包含安装要求视为设计约束。保留不变和拒绝清单，并为每项列出机械证据和原因。

决策

• 落实用户已确立的决策以及已授权代为判断的事项。仅针对会实质改变结果的未决选项提问。请求批准前，先准备好证据和具体提案。
• 将确认存在的偏差与需权衡的选择分开呈现。通常将前者作为一个无争议的修复批次提出。为每项修复列出受影响的代码库和确切的机械证据。
• 将建议迁移的项目整理为精简表格，列出供体、接收方、证据、收益和成本。将其作为一个默认接受的批次提出，用户可删减。
• 将每个单一来源候选项和需权衡的选择都作为明确问题提出，并附上建议选项及其权衡。当某项选择决定计划时，备选方案应互斥。
• 若没有充分理由进行精简，则说明默认保留方案。
• 在规划每项变更前，先解决影响该变更的决策。等待某项选择期间，继续独立研究和已获授权的变更。不要将进度报告当作已完成用户所请求的工作。
• 在相关发现旁逐字记录用户的每项决策。若决策附带条件或例外，即使已批准变更，也要保留该限制。
• 将被拒绝的项目纳入不变和拒绝清单，而不是悄然省略。

计划

• 为每个仓库制定决策完整的计划。明确列出要创建或编辑的文件、权威来源、受影响的生成产物、每项移植所依据的源文件（文件:行号），以及依赖项和用于添加依赖项的包管理器命令。
• 将每项变更关联到对应的发现、验证命令，以及授权该变更的用户决策。
• 按顺序编辑：先修改权威来源，再处理其生成或安装后的对应产物。在每个接收仓库中，先处理依赖项，再处理使用这些依赖项的配置和任务，最后添加指导文档，确保文档描述的是实际存在的内容。
• 除非已安装的输出本身按仓库规则属于权威产物，否则不要手动编辑。
• 列出每条再生成命令，并说明它是仅用于构建、不提交更改，还是预计会修改文件。明确指出提交钩子的副作用，并将其与构建及再生成步骤区分开。
• 说明提交顺序、发布顺序，以及仓库之间的依赖关系。指出下游仓库何时可以安全地使用上游生成或安装后的产物。
• 在 Claude Code 中，优先使用计划模式。
• 如果有 $orchestration 可用，通过它委派实施工作；否则使用宿主子 Agent。如果这些方式也不可用，则直接实施。
• 无论采用哪种实施方式，都要为委派工作划分互不重叠的各仓库写入范围。指定一名负责人统一执行跨仓库验证，确保相关编辑完成后只运行一次。
• 计划仅限于用户已批准的决策。对于这些决策涵盖的技术前提，可自主扩展计划。只有当新发现引入主观选择、改变仓库范围或预期结果，或超出尚未批准的破坏性操作、发布或其他外部写入边界时，才报告并征求意见。

实施并完成

对于迁移：

• 使用接收方的包管理器添加依赖（例如 bun add -d、pnpm add -D、uv add --dev、 cargo add、go get -tool），选择符合其约束的最新稳定版本，并遵循其版本范围和固定版本的风格。让包管理器更新锁定文件。
• 调整捐赠方配置，删除引用捐赠方专属路径、名称或功能的选项。
• 遵循接收方的 CI 约定：提供方、操作固定版本的风格、运行器、缓存和最小权限原则。
• 如果指导文件是符号链接或生成的产物，请编辑其规范源文件。通过调整项目技能并将其放入接收方的技能目录来迁移，或者在捐赠方通过共享目录中的相同安装机制安装该技能时，沿用这一机制。
• 在接收方运行每项新增或更改的任务，并确认其效果与捐赠方版本一致。迁移的检查必须在接收方通过，或按用户决定处理接收方中已有的失败。
• 使用可用的本地检查工具或试运行验证 CI 和钩子变更，例如 actionlint。如果只有 CI 运行才能验证，请明确说明。
• 验证迁移的指导内容：其中提及的每条命令、路径和工具都必须存在于接收方。

对于每项变更：

• 将每个实现 Agent 的结果与可见工作树及其获准的写入范围逐一核对。将 Agent 报告的每个变更路径与获准范围比对后，才能认为 Agent 的工作已完成。
• 按字节原样保留已有的未提交更改和无关的并发变更。
• 运行足以证明预期编辑正确的最小范围仓库检查。应在包含相应规则和依赖的仓库中运行这些检查。
• 只运行一次跨仓库不变量检查，包括生成过程的幂等性，以及适用时的源文件与已安装文件差异检查。
• 采取行动前，先确定汇总失败的原因：首先排除本任务变更、格式化工具、钩子和生成器的影响，包括获准文件之外的下游失败。只有在证据表明失败无关且本任务自身的检查仍然通过时，才继续后续工作。
• 如果 $commit 可用，请在验证后使用它，并且只提交本任务的文件。切勿使用 git add -A、git commit -a、stash 或 reset 绕过它。
• 每个仓库分别提交，以便各自的历史记录、钩子和发布状态都能独立审计。在可行的情况下，每项迁移单独提交，以便能独立撤销。
• 创建下一个提交前，检查当前范围内的每个提交，确保上游提交仍可独立撤销。
• 源文件变更后，重新运行所有必需的发布或安装流程。不得发布未经验证的源文件，也不得发布与源文件不再匹配的已安装产物。
• 如果按用户决定暂缓发布，请保留已验证、可提交的源文件，并报告所需的发布步骤。

报告

• 以一行结果概述开头：按仓库列出已应用的修复和迁移，以及任何尚存的阻碍。
• 以表格列出已应用的修复和迁移：仓库或接收方、发现或做法、捐赠方来源（如有）、变更文件和提交标识。
• 报告每条验证命令及其结果。区分通过的检查和有意未运行的检查，并说明原因，包括仅限 CI 的验证。
• 在一个简明表格中列出有意不变、拒绝和推迟处理的项目及其原因。
• 说明剩余风险，包括未运行的发布流程、不可用的生成工具以及尚未解决的跨仓库引用。
• 列出推迟处理或在批准决策边界之后发现的待决问题。
• 确保报告可审计：每项结论都应关联到记录在案的发现、决定、证据或命令结果。