Communitygithub.com

dubbl-a/house-rules

该技能用于同步仓库中的供应商托管文件,确保本地编辑不会在无提示的情况下被丢弃。通过 `/house-rules:sync` 命令触发。

house-rules 是什么?

House sync 是一项 AI 代理技能,旨在同步 Git 仓库中由外部插件管理的文件(vendored house files),同时避免静默丢弃本地修改。它支持 `dubbl-a/house-rules` 插件,并通过 `/house-rules:sync` 命令触发。该技能会执行一个默认路径:首先确认仓库已初始化(存在 `house.json`),然后通过 `render` 命令进行预演(dry run),将每个受管文件分类为“干净”、“缺失”或“本地修改”。对于本地修改的文件,该技能不会自动合并或覆盖,而是提供三种退出策略:向上游 (upstream-first) 提交 PR、记录偏差并取消管理(deviation and unmanage)、或强制覆盖(force overwrite)。完成预演后,技能会应用更改(`--apply`),阶段化(stage)受管文件,更新 `.gitignore`,确认插件版本锁定,并通过供应商检查器 (`.house/check.mjs`) 和诊断工具验证同步结果。此外,该技能还会检查 Git 钩子设置、`jq` 路径、npm 脚本等,并路由需要上游修复的问题,以单个 issue 提交。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/dubbl-a/house-rules/tree/HEAD/plugins/house/skills/sync

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

仓库同步(House Sync)

将仓库供应商托管的文件更新到已安装插件的最新版本,同时确保不会静默丢弃本地编辑。仅通过 /house-rules:sync 调用此技能。这不是一个查询技能,并且会写入文件,因此它永远不会因关于约定的普通问题而触发(请使用 /house-rules:conventions 进行查询)。

该技能驱动的 CLI:

node ${CLAUDE_PLUGIN_ROOT}/scripts/house <init|render|check> [--repo <path>] [--apply] [--force-managed <path>]

--repo 默认为当前目录。下面不会发明 init、render、check 之外的子命令。

默认路径:计划,然后应用

Sync 只有一个默认路径。每次都按此顺序运行。

1. 确认仓库已采用 house

读取仓库根目录下的 house.json。如果缺少 house.json,则表示此仓库从未被引导:停止并告知用户先运行 /house-rules:bootstrap。不要将缺少清单视为“无需同步”。

2. 计划(预演)

node ${CLAUDE_PLUGIN_ROOT}/scripts/house render --repo <path>

没有 --apply 时,仅进行计划。它读取 .house/lock.json(每个条目包含:path、module、source、bodySha256),并将磁盘上每个受管文件的当前主体哈希与锁进行比较,然后与新渲染的主体进行比较。将每个受管文件准确分类到一个桶中:

  • 干净(Clean)。 磁盘上的哈希与锁匹配。计划:用新渲染的主体覆盖。
  • 缺失(Missing)。 文件在磁盘上不存在。计划:恢复它。
  • 本地修改(Locally modified)。 磁盘上的哈希既不匹配锁,也不匹配无操作渲染。计划:拒绝。参见下面的三个退出策略。

在执行任何其他操作之前打印计划。即使对于干净或缺失的文件,也不要在此步骤中应用任何内容。

3. 本地修改:三个退出策略,绝无静默选择

一个本地修改的受管文件不会被合并、覆盖或静默保留。打印磁盘文件与 house 将渲染的内容之间的差异,然后按此顺序准确打印这三个退出策略,并针对该文件停止(即使使用 --apply 也保持原样,它只是被排除在写入之外):

  1. 向上游优先(Upstream-first)。 针对 house 软件包仓库本身 (dubbl-a/house-rules) 提交一个包含预期变更的 PR,这样编辑就成为每个人的新 house 规则,而不是私有分支。这是首选的退出策略。
  2. 记录偏差并取消管理(Record a deviation and unmanage)。 在 house.json 的 deviations 数组中添加一个包含 why 的条目,从受管集合中删除该文件,并将其镜像到仓库的 CLAUDE.md 的 ## Deviations from house 部分。当编辑是真正特定于仓库且永远不会进入上游时使用。
  3. 强制覆盖(Force the overwrite)。 运行:
    node ${CLAUDE_PLUGIN_ROOT}/scripts/house render --repo <path> --force-managed <path>
    
    仅当本地编辑确认为可丢弃时使用此选项,切勿将其作为默认选项,因为它是最快的。在运行之前要求用户确认;切勿未经提示就替他们选择它。

不要提供第四个选项,也不要将其变成等待选择的交互式菜单。陈述这三个退出策略作为运行的结果,然后让用户(或此技能的后续调用)执行其中一个。

4. 应用

在处理干净和缺失的文件,并且每个本地修改的文件都被路由到三个退出策略之一(或故意保留为拒绝状态)之后,应用:

node ${CLAUDE_PLUGIN_ROOT}/scripts/house render --repo <path> --apply

这将写入干净和缺失的文件。它从不写入仍被拒绝的本地修改文件;--force-managed 是唯一能这样做的路径,并且仅针对指定的一个路径。

如果 render 打印了 warning: ... is git-ignored 行,请在继续之前停止并修复忽略规则:git 看不到的目标永远不会到达检查器或 CI。仅忽略 .claude/settings.local.json,切勿忽略 .claude/ 或 .house/。

如果 render 或检查器打印了 warning: module is not in house.json, but <dir>/ exists here,则表示在此仓库的 house.json 编写之后发布了一个模块,并且在该仓库在 modules 下添加 "<name>": {"enabled": true} 之前,其规则不会作为供应商提供。不要自己添加密钥:将警告行原样复制到同步 PR 正文中,位于说明新模块适用于此仓库并需要采用者选择的标题下方。

4b. 按路径暂存 render 写入的内容

git add house.json .house/ .claude/rules/house/

仅当渲染计划中列出了该目录下的文件时,才将 scripts/house/ 添加到该命令中;当任何路径规范不匹配任何内容时,git 会拒绝整个命令。通过显式路径,切勿 git add -A:检查器和 CI 读取 git ls-files,因此未暂存的渲染文件是无人检查的文件,而全量添加会扫入目录树中存在的其他任何内容。

Render 的“Scaffolded”列表(.github/PULL_REQUEST_TEMPLATE.md、.github/workflows/pr-checks.yml、CLAUDE.md 骨架)不是受管文件,因此 [untracked] 警告无法看到它:审查这些文件,然后也按路径暂存它们。

脚手架(scaffold)每个仓库只提供一次,而不是每次渲染都提供。锁的 scaffolds 列表记录了该仓库已经获得哪些模板;记录在案的模板永远不会再次写入,无论其文件是否仍在磁盘上。因此,已合并到 CLAUDE.md 并删除的 CLAUDE.md.house-skeleton 保持删除状态,并且重新同步不需要执行 rm。如果仓库想要回一个,render --apply --scaffold 会写入任何缺失的脚手架,并且仍然从不覆盖已有的文件。预计 scaffolds 键会在 0.2.3 或更高版本的首次同步时出现在锁差异中;它是一个记录,而不是哈希,没有任何东西会拒绝它。

4c. Gitignore 工具临时文件

确保仓库的 .gitignore 包含 .claude/worktrees/ 和 .superpowers/,追加任何缺失的行。出现在 git status 中的工具临时文件只需一个 git add -A 就会被提交。

5. 确认锁销

确认 house.json 现在包含已加载的插件版本;render 在写入它,切勿手动编辑。render --apply 将 version 字段设置为以下位置的插件版本:

${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json

永远不要读取 installed_plugins.json 来检查这一点。它记录跨仓库的安装状态,并且可能滞后或与当前加载的内容不同;CLAUDE_PLUGIN_ROOT 下的 plugin.json 是实际运行此同步的版本。

6. 使用供应商提供的检查器进行验证

像 CI 和 prebuild 实际运行的那样运行检查器,而不是插件的副本:

node .house/check.mjs

node ${CLAUDE_PLUGIN_ROOT}/scripts/house check --repo <path> 针对插件的有效负载运行相同的逻辑,并且在 .house/check.mjs 被作为供应商引入仓库之前(首次同步)很有用。一旦供应商副本存在,直接运行它证明发送的文件是正确的,而不是一个看起来相同的副本。

此处的 [untracked] 警告意味着该文件的步骤 4b 被跳过;暂存它并重新运行。[gitignored] 发现意味着步骤 4 中的忽略规则仍然吞没了受管文件。

7. 打印诊断输出

检查运行后,运行诊断器并报告其行:

node ${CLAUDE_PLUGIN_ROOT}/scripts/house doctor --repo <path>

每打印行的含义(标签如 doctor 打印的):

  • effective branch guard: plugin | repo | NONE。
    • NONE:没有 house.json 且没有仓库本地钩子。当前没有保护直接提交到受保护分支的操作。
    • repo:存在仓库本地的 .claude/hooks/no-direct-master.sh 文件,或者 .claude/settings.json 包含一个 hooks 块。迁移期间仓库钩子获胜;插件钩子推迟并退出并返回 0。
    • plugin:存在 house.json 且不存在仓库本地钩子信号。插件钩子是实际执行 branchPolicy 和 protectedBranches 的钩子。当 house.json 包含 guard 记录时,它打印为 plugin (recorded <date>);当不包含时,打印为 plugin (unrecorded),这只关乎检查器的 guard 警告是否消除:钩子在两种情况下执行相同的操作。
  • git-hook floor: ...。 供应商分发的 .githooks/ 树是否实际连接到 git 此克隆中。core.hooksPath 存在于 .git/config 中,因此它是机器状态,没有克隆、渲染或 PR 可以携带;检查器从不读取它(ADR 0008 使检查器仅限于仓库),而诊断器是报告它的地方。
    • armed (core.hooksPath=<path>, <scope>):git 在此处运行 floor。无需操作。
    • NOT armed -- core.hooksPath is unset in this clone:floor 已渲染但无效。house render --apply 会激活它,在安装了插件的仓库中启动会话也是如此。
    • NOT armed -- core.hooksPath is <other>:另一个工具(husky、lefthook、monorepo 约定)拥有此仓库唯一的 hooksPath。House 从不覆盖它。从那里的钩子链接 floor,或者取消设置并重新运行 render。
    • not rendered here (missing: <paths>):至少缺少七个 floor 文件之一,并且该行命名了哪些。全部七个缺失仅仅是尚未渲染 floor 的仓库。缺少一个文件比看起来更糟糕:每个监护人都会来源 .githooks/house-lib.sh 并在该来源失败时以非零退出,因此仅缺少库的 floor 会导致每次提交关闭时失败,而不是开放时失败。无论哪种方式,都请渲染。
    • not applicable:此根目录下没有 house.json,或者 branchPolicy 不是 pr。
    • 后续缩进行报告什么会使 floor 安静而不是具有保护性。foreign hooks in this clone's .git/hooks:拒绝激活,因为 core.hooksPath 会完全替换 .git/hooks 并静默禁用它们。not executable:git 在没有该位的情况下静默忽略钩子,因此丢失 mode 意味着失败开放;render 会恢复它(仅为已经可以读取该文件的类添加该位,因此故意设置为 0600 的钩子会以 0700 返回,并且永远不会被放宽)。reference-transaction: supported by git <version> (>= 2.28) 或 inert on git <version> (needs 2.28):在 2.28 及更高版本上,floor 有一个成员,没有标志可以关闭它,而 inert 行是一个真正的差距,而不是装饰性的。在 2.28 以下,--no-verify 一起跳过 pre-commit 和 pre-push,并且没有其他任何东西可以捕获它,因此在该 git 版本上,只有会话时 PreToolUse 钩子才能拒绝该标志,而当会话不在循环中时,该钩子不存在。将该行视为升级 git 的提示,而不是一条说明。
  • jq on PATH: yes | no。 没有它,钩子仍然拒绝(手写拒绝 JSON),但报告差距以便修复。
  • pin vX matches plugin vY | pin vX differs from installed plugin vY。 house.json 的 version 与插件自身的 plugin.json 的比较,与步骤 5 相同。differs 意味着锁销提升尚未生效或被跳过。
  • npm wiring (.house/check.mjs referenced by): <scripts> | none found。 期望一个调用 .house/check.mjs --only=drift,todo 的 check:docs(或等效的轻量级)脚本和一个调用完整 .house/check.mjs 的 check:house 脚本。如果任何一个缺失,请打印可复制粘贴的片段,而不是直接编辑 package.json:
    "check:docs": "node .house/check.mjs --only=drift,todo"
    "check:house": "node .house/check.mjs"
    
  • rule-load positive control: ...。 是否连接了 InstructionsLoaded 钩子,以及它自己的日志实际见证了什么;没有它,一个全局表达式从不匹配的规则看起来就像一个什么都不做的规则。repo (.claude/settings.json):仓库声明了自己的钩子。plugin hook; log <path>: last load <ts>, <n> of <m> vendored rules seen:插件自己的钩子已连接并且已记录至少一次加载,并带有它实际看到的已加载供应商规则文件数量的实际计数。当 <n> 小于 <m> 时,该行继续为 ; not seen in this log: <names>,列出日志中没有加载记录的每个供应商规则,因为仅凭计数可以说有问题但不知道要打开哪个文件。将该列表视为线索而不是结论:日志会自行修剪,因此规则可能只在很久以前加载后出现,而诚实的下一步是打开一个规则 paths: 声称的文件并重新运行诊断器。一个在该测试中幸存下来的名字意味着该规则的范围没有达到它为之编写的文件。plugin hook declared; no log yet for this checkout:插件的钩子已连接但尚未在此处记录任何内容——在此仓库中启动一个会话并重新运行诊断器。none wired:没有任何东西声明该钩子。
  • git-ignored house destinations: none | <paths>。 除了 none 之外的任何内容都是检查器无法看到的目标;按照步骤 4 中的说明修复忽略规则。

8. 路由仓库无法上游修复的问题,每个问题一个 issue

同步或合规性检查通常会显示只有软件包才能处理的发现和警告:检查器差距、命名此处不存在的文件的规则锚点、仓库需要但架构缺少的配置槽。对于每个这样的项目,要么在同一个会话中上游修复(分支并提交针对软件包仓库的 PR,与步骤 3 相同的上游优先退出策略),要么在每个可操作项目的软件包仓库中提交一个 issue,该 issue 足够小,可以通过单个更改关闭。

千万不要将它们批量处理到包含多个项目的摘要 issue 中:摘要 issue 在其最慢的项目落地之前无法关闭,其项目无法独立排序优先级,并且部分解决的摘要 issue 会累积。只保留此仓库可以修复的内容。

逃生舱(Escape hatches)

这些是在上述默认路径中内联的例外情况,而不是预先选择的不同菜单:

  • 无 house.json:在第 1 步停止,指向 /house-rules:bootstrap。
  • 本地修改的文件:步骤 3 中的三个退出策略。
  • 已确认可丢弃的本地编辑:--force-managed <path>,仅在询问之后。
  • 仓库中的首次同步,.house/check.mjs 尚未作为供应商提供:在第 6 步中使用 house check --repo <path> 代替供应商路径,并注意这是一次性替换,而不是稳定状态。

不要

  • 不要合并本地修改

…

[剪切以供翻译]

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

相关技能