在项目中评估CoalHearth，可以先看清用途边界：AI 编码代理的会话热恢复 + 切换日志 - 记录每个步骤，以便恢复中断的会话而不是重建。团队若要把它用于软件开发，应先处理依赖、接口和异常处理往往比主路径更影响采用，否则试用结果很容易失真。我的评估方法是在隔离分支完成一个可回滚的小任务，然后检查安装步骤、接口契约、测试结果和错误信息是否与文档一致。编辑判断上，需要可检查开发流程而非单次演示的工程师可以优先研究它；其他团队不必为了热门标签勉强接入。

这是什么

达到会话限制或崩溃会丢失正在进行的工作 - 计划、清单、您正在编辑的文件列表。 CoalHearth 减少损失：

• 恢复核心。 PostToolUse 钩子构建会话的尽力快照（来自 task.md 的目标 + 检查表，来自 AGENTS.md 的约束，从文件编辑工具累积的修改文件调用钩子观察 - 没有 git 生成，没有子进程）并将其 原子地 每一步记录到session_handoff.json。
• 启动时热恢复。在下一个会话的 SessionStart 上，如果上一个会话的日志仍标记为 in_progress，则 CoalHearth 会注入一个 markdown 恢复块 — 目标、清单、它所接触的文件、计划的后续步骤 — 这样您就可以从上下文中恢复，而不是手动重建它。
• 子代理死亡可见性。 生成的子代理的工具调用解析（成功或失败）现在通过状态+来自其自己报告的简短结果片段来捕获 - 恢复或推迟决策实际上需要“完成 11 项检查中的 7 项”，而不仅仅是名称。在克劳德·科德（Claude Code）上，一个未浮出水面的解决方案也会推动你的下一个提示——几秒钟到几分钟的时间，而不是重新启动会话。

[!IMPORTANT] 恢复块永远不会要求您盲目信任它 - 它总是告诉代理首先验证 git status / git diff，因为日志可能已过时或半应用。

恢复的核心就是价值。

它的作用（以及 NOT ）保证

CoalHearth 减少会话中断的损害 - 它不阻止会话中断，并且不保证任何内容：

• 恢复日志是 尽力快照，并不能保证它仍然准确 - 自上次保存以来代码可能已移动，这正是恢复块告诉代理根据 git 进行验证的原因。
• 由分散的工人在有限的时间内死亡的工作仍然在内容上无法恢复——一个死去的副代理人不会记录任何自己的东西。发生了什么变化（问题＃13）：如果子代理的工具称自己为 RESOLVED（即使处于失败状态），则父代理的日志现在会记录该结果 + 一个简短的自我报告片段 - 足以为恢复或推迟决策定价。其工具调用根本无法解决的子代理（真正的调度中死亡）在下一个 SessionStart 之前仍然不可见。
• Claude Code 保留自己的会话记录，但保留取决于版本，而不是其文档建议的保证 30 天 - 记录可以在您 --resume 之前提前进行垃圾收集。 CoalHearth 的日志是一个独立的本地网络，不依赖于它，并且恢复块标记已经消失的转录本。

诚实的销售：减少因中断而造成的工作损失——不是无限制的会话。

钩子

所有这些都是 Phoenix-13 钩子 — 失败沉默（任何错误都会被吞掉，退出 0，永远不会使主机崩溃），零依赖（仅限 Node 内置），无网络，无子进程，并且它们仅发出其唯一认可的通道。

• SessionStart→resume (bin/session-start.js)：读取日志（限制为 4 MiB；该工具写入的日志保持在该限制以下：过去大约 4 MiB，作者会删除最旧的记录路径，对它们进行计数，恢复块表示未列出该工具未写入的边界上的日志，或者未读取离开输出目录的链接，并且下一个记录的步骤将其替换为新的路径），并且如果前一会话被中断，则在批准的 SessionStart 上下文注入通道上打印恢复块，然后标记日志 resumed ，以便它不会在每次启动时重新注入。当定期自我更新检查到期时（请参阅 update.*），它还会在同一通道上打印一行 /coalhearth:update 微移 — 该钩子仅通过本地节流标记进行调度；在线检查是代理人的，经过同意。 headless/cron 启动在结构上是安全的——钩子只打印，从不询问任何信息。
• PostToolUse → 日志 (bin/post-tool-use.js)：构建状态快照并将其自动保存在每个工作空间锁下（因此两个并发会话不会丢失彼此的日志）。仅日志——它不发出任何信号。
• UserPromptSubmit → 子代理死亡助推（bin/user-prompt-submit.js，仅限克劳德代码 - 第 13 期）：常见情况是阅读一本廉价期刊，仅此而已。当生成的子代理的工具调用自上次触发以来具有 RESOLVED，并且其 status/outcome 尚未显示时，它会在批准的 UserPromptSubmit 上下文注入通道上打印一个轻推 - 描述、状态和自我报告的结果片段 - 然后将其标记为显示，以便相同的解决方案永远不会重复。这会在 SAME 会话中的下一个提示中出现，而不是等待可能需要几个小时的 SessionStart。每个状态都带有警告：它是由子代理自行报告的，并且已被观察到错误。

在所有其他平台上，简历 + 日记作业通过瘦适配器 — bin/ag-pre-invocation.js（简历）和 bin/ag-post-tool-use.js（日记） — 在一个共享核心上运行（lib/journal-step.js为日志，lib/resume-engine.js为恢复块）； Claude Code 日志钩子本身就是该核心上的一个薄适配器，行为相同。每个平台配置中的尾随参数选择发射形状（Antigravity flat JSON · Gemini 嵌套 hookSpecificOutput · CC- 形文件复制平台的普通克劳德代码标准输出）； parsing/journal 逻辑永远不会分叉。 子代理 status/outcome 捕获和丰富的恢复块渲染通过这些共享核心到达每个平台 — 只有中间会话 UserPromptSubmit 推动本身是 Claude-Code 特定的此版本（没有其他平台的配置将等效的每个提示事件连接到它；反重力的解耦 PreInvocation 变体是已命名的、未构建的）后续）。

安装

CoalHearth 是两个Phoenix-13钩子（简历+日志），因此它会安装在平台运行钩子的地方并且同时具有会话启动类事件和每个工具事件——产品需要的对（没有简历的日志是只写的；没有日志的简历没有任何内容可读）。所有平台都通过瘦适配器入口点运行相同的共享核心。

兼容矩阵（层诚实性：已验证 = 已在该平台上完成了真正的端到端运行·与一起使用=构建+针对平台的主要文档进行了严格测试，2026年7月15日获取 - 尚未在那里得到验证；只有在实际运行后，声明才变得已验证）：

¹ Gemini CLI 观众警告：individual/AI-Pro/Ultra 层级已于 2026 年 6 月 18 日被切断 — 现在它是一个商业级产品 (Standard/Enterprise)。 ² UserPromptSubmit（子代理死亡推动，第 13 期）仅是此版本的 Claude 代码 — 请参阅上面的“钩子”。

克劳德代码——经过验证

一个命令（这也连接了钩子）：

claude plugin marketplace add TheColliery/CoalHearth
claude plugin install coalhearth@coalhearth

就是这样——钩子会在你的下一个会话中激活。没有 API 密钥，没有网络，无需配置即可启动。

反重力 - 可以使用（没有观察到火焰；三项阴性测试，其中两次无头 - 见下文）

有记录： Antigravity 2.0 提供了一个真正的钩子引擎（hooks.json；antigravity.google/docs/hooks，根据 2026-07-13 的文档得到证实），它重新打开 CoalHearth 到 AG - 仅旧的“克劳德代码，因为没有其他代理运行钩子”的前提不再成立。该端口是根据该文档规范构建和密封测试的。

“根据 2026 年 7 月 12 日的经验证实”实际上建立了： 该日期的飞行员在 AG 上触发了一个实时的 Stop 钩子 - 证明引擎本身可以触发 - 但在同级插件 (CoalMine) 中，在另一个事件中。 CoalHearth 自己的 PreInvocation/PostToolUse 从未参与过那场火灾；它是根据飞行员确认的规格建造和测试的，从未观察到自行射击。本节之前通过将日期放在 CoalHearth 自己的声明旁边来暗示 - 此处更正。

于 2026 年 8 月 4 日进行测试，观察到： 本文档在下面命名的两个挂钩位置（全局 ~/.gemini/config/hooks.json 和每个项目 <workspace>/.agents/hooks.json）均已安装；新的 AG 会话运行了真正的工具调用（list_dir，在 AG 自己的转录日志中得到证实）；以相同方式编写的普通控制命令 FIRED（排除损坏的命令形状）。 CoalHearth 的 PreInvocation 钩子和 PostToolUse 钩子（使用通配符 * 匹配器和精确的工具名称匹配器进行测试）都没有生成单个日志行。

此后针对相同的底层钩子引擎（2026-08-22和2026-08-23）复制了两次：另外两个探针 - 在两天内通过 agy -p 无头运行，使用两种不同的工具调用形状 - 对共享跨工具位置处预先存在的、模式有效的 hooks.json 触发零钩子(~/.gemini/config/hooks.json)，每次运行时都会确认真实的工具执行情况。这些探针不是 CoalHearth-specific；他们使用相同的钩子引擎CoalHearth的PreInvocation/PostToolUse对依赖。在该探针系列中，可从无头 CLI 会话访问的每个 hooks.json 位置现已被尝试过，并且所有位置都是惰性的。

范围，精确说明，因此这不会被解读为比实际情况更被证实：已经测试的是无头CLI钩子射击。 2026-08-22/08-23 探针在 agy -p 下运行； 2026-08-04 测试的执行通道未记录。 交互式 IDE (GUI-driven) 路径从未被任何这些探测器执行过 — 这是一个真正不同的执行路径，这里没有说明是否会触发相同的配置。这也不是说 AG 的钩子引擎总体上被破坏了（同级插件的 Stop 钩子确实在 2026 年 7 月 12 日触发，如上所述）。 与一起工作在这里意味着“根据记录的规范构建+测试”；它从来就不是“确认开火”的意思，并且在观察到真正的火灾之前，反重力的说法也不会得到验证的支持。

AG没有插件管理器，因此安装是文件副本：

git clone https://github.com/TheColliery/CoalHearth.git --depth 1
# global (all workspaces):
Copy-Item -Recurse CoalHearth "$env:USERPROFILE.geminiconfigskillscoalhearth"

然后将 platform-configs/hooks.json 复制到 <workspace>/.agents/hooks.json（每个项目）或 ~/.gemini/config/hooks.json（全局），并将 __COALHEARTH_DIR__ 替换为复制的目录。事件映射（AG 从不触发 SessionStart）：热恢复运行会话的第一个 PreInvocation — 每个会话临时标记将其保留在每个会话一次，因为 PreInvocation 每次模型调用都会触发 — 并且日志运行 PostToolUse。

AG 的已知限制：该房间的钩对没有观察到火灾 - 三个独立的负面测试（2026-08-04，加上 2026-08-22 和 2026-08-23 针对共享 ~/.gemini/config/hooks.json 的无头 agy -p 探测器），跨越不同的日期和工具调用形状，并在每个中确认了真实的工具执行 - 请参阅上文以了解排除的内容。 本系列中没有探针到达交互式 IDE（GUI- 驱动）路径，因此 IDE 用户的结果是未知的而不是负面的。在依赖此平台之前重新测试 · 注入的上下文（injectSteps/ephemeralMessage JSON）的交付尚未实时验证（上图） · AG 工具名称映射比 write_to_file 尽了最大努力（未映射的工具根本没有记录 - 从来没有错误写入） ·每个会话一次的临时标记是 OS-reaped，而不是钩删除（AG 没有会话结束事件） · 故意不移植自更新微移（其有效负载是 Claude-Code 插件命令；在 AG 上，通过重新复制进行更新）。

Gemini CLI · Copilot CLI · Devin CLI · Kiro · Augment — 与（仅配置端口）配合使用

其中每一个都附带一个本机会话启动类事件，因此不需要 Antigravity 的每次会话一次标记解决方法 - 连接是一个配置文件，将两个事件指向相同的两个适配器入口点 (bin/ag-pre-invocation.js + bin/ag-post-tool-use.js)，由尾随参数切换 (SessionStart = Gemini 的嵌套hookSpecificOutput 发出·FileCopy = 普通克劳德代码形状（其他四个模型）。克隆存储库，将平台的模板从 platform-configs/hooks/ 复制到位，然后调整克隆路径 — 每个平台的路径、验证与最佳猜测注释以及该目录的 中的命名分歧。与反重力相同的诚实：与一起使用，未经验证 - 这些平台上的实时会话尚未运行连线。

其他代理 — 不支持

CoalHearth是仅钩子的，它需要会话启动+每个工具事件对：没有钩子层的平台没有任何东西可以运行；缺少一半对的平台无法承载该产品（Junie — 仅会话启动；Devin Desktop 的 Cascade 词汇 — 无会话启动；请参阅矩阵）。钩子表面是插件 CODE 而不是配置文件（OpenCode、Cline CLI）的平台是一个单独的未来通道。没有手动加载的read/analyze模式（CoalMine或CoalLedger船的方式之一）。

命令

CoalHearth的核心价值在于它的两个自动挂钩（上图）；下面的两个命令是唯一可调用的界面——自我更新和只读统计报告。

⚙配置

coalhearth.json 中的所有内容都是可调的（全局 ~/.claude/.coalhearth.json 由项目配置覆盖 - 每个组的嵌套键，整个值的顶级标量，如 language；项目查找从 cwd 开始，在您的主目录停止）。大多数密钥都是项目获胜的，因此您可以重新调整每个项目全局安装的 CoalHearth - 最接近的每个项目安静开关是 recovery.autoInjectPrompt: false （静默检测 + 扫描，无恢复块；日志挂钩仍然运行 - 完全关闭 = 卸载）。每个键都是可选的。

每个项目配置位置 - THE READ ORDER IS A RAIL，该系列的每个房间都相同：

1. <project>/.<the running agent's OWN dir>/coal/coalhearth.json — 实际执行的代理的目录（Claude Code = .claude，Antigravity = .agents，Gemini CLI = .gemini）。 这是规范路径 - 在 Claude Code 下，正是 .claude/coal/coalhearth.json。
2. 其他已知的代理目录，固定顺序：.claude → .agents → .gemini（第一个找到获胜）。
3. DEPRECATED — <project>/.claude/.coalhearth.json（嵌套的旧形状）。在每条规范路径之后仍然阅读。在此版本之前，加载程序根本不会读取它。
4. DEPRECATED — <project>/.coalhearth.json 位于项目根目录（2026 年 8 月 8 日之前的形状）。仍读，永远最后。

两种旧形状均已弃用，并且还没有任何破坏 - 但请移动您的配置。 将相同的内容放在 .claude/coal/coalhearth.json （或正在运行的代理自己的目录）中，或使用 node scripts/configure.mjs （如下）设置任何值，这会写入规范文件并为您删除旧文件（除非 git 跟踪它或无法判断它是否跟踪（存储库 git 拒绝读取）：保留旧文件，脚本会打印 git rm 行以在您查看更改后运行）。在 2.5.0 MINOR 已弃用；可移除不早于下一个 MAJOR。这个房间拥有迁移。此 README 注释和 CHANGELOG ### Deprecated 条目是公告 - 仅发布文本，因为钩子没有自己的经批准的渠道来公告（Phoenix #13）。

当遗留路径实际被击中时，你会看到什么。 这是公告中的一个单独的、较小的事情：这个房间已经批准的 SessionStart 上下文注入通道上的每个发现一行（与恢复块和 language 指令相同），将路径和替换命名为 [CoalHearth] LEGACY: <path> is deprecated but still read; canonical = .claude/coal/coalhearth.json。位于根本不符合上述读取顺序的路径中的配置文件（例如 .claude/coalhearth.json，缺少 coal/）将获取 [CoalHearth] IGNORED: <path> is not a config path; canonical = .claude/coal/coalhearth.json。位于步行读取但无法使用的路径处的配置获取 [CoalHearth] UNREADABLE: <path> exists but is not a readable config (<reason>); it was skipped — canonical = .claude/coal/coalhearth.json，其中 <reason> 是 malformed JSON、a directory、unreadable 之一（OS 拒绝读取，文件超过 1） MiB，或者不是常规文件或者是离开项目的链接）或 not a JSON object（有效的 JSON 是数组、字符串、数字或 null）。全局 ~/.claude/.coalhearth.json 也会被检查，当它失败时，该行将以全局文件自己的路径结束（canonical = <that path>），因为全局配置没有可以移动到的项目位置。不可读的旧文件仅获取 UNREADABLE，而绝不会获取 LEGACY。 “跳过”意味着该文件不提供任何设置；它不会打开通往较低优先级配置的大门，因为步行仍然停在保存文件的第一个路径处。该行会附加到 SessionStart 已经说过的内容，或者在会话保持沉默时单独打印。 只要遗留文件存在，它就会重复每个会话 - 每个会话一次，而不是一次 - 因此不断出现的推动正在发挥作用，而不是卡住；迁徙是让它沉默的原因。一个可读的规范配置本身，或者根本没有，不会打印任何内容。

它没有告诉你什么：在读取顺序中的真实路径上的配置只是丢失，不会被宣布。 只有找到的第一个配置才会被读取，因此，遗留在规范文件旁边的旧文件、第二个代理目录的规范文件或根 .coalhearth.json 一旦嵌套文件存在，就会默默地死亡 - 不需要对其进行编辑。迁移它或删除它。 （按读取顺序位于路径的 目录 是不同的：它会被传递 - 仅当它是文件时，遍历才算为路径，并且名为配置的目录不再锚定项目根 - 并且，除非它位于读取的配置之后，否则它会在上面报告为 UNREADABLE ... (a directory) ；根本没有读取配置，则会报告每个这样的目录。）

如果您同时保留两个旧文件，则嵌套文件将获胜。 在此版本之前，仅读取根 .coalhearth.json，因此 .claude/.coalhearth.json 已死亡；现在是先读。您的有效配置可以更改，而无需您编辑任何内容 - 并且上面的通知命名了现在正在读取的文件，而不是刚刚失效的根文件，因此请检查这两个文件，保留您想要的文件并迁移它。

写入目标=找到配置的任何地方 - 除了在写入时迁移在任一遗留路径中找到的配置（configure.mjs写入规范文件并删除遗留文件，除非git跟踪它或无法确定它是否这样做，在这种情况下，它会保留文件并打印git rm -- <path>行供您运行；钩子永远不会仅在读取时移动文件）；任何地方都找不到=正在运行的代理自己的目录。 coalhearth.json 仍然没有 HOOK writer - 运行每个会话的钩子从不写入配置，只读取它； “总是手工编辑”的一半仍然是正确的。更改内容：scripts/configure.mjs 现在是一个为您编辑它的 USER-INVOKED CLI — node scripts/configure.mjs --language th — 因此“从未由 CoalHearth 本身编写”不再描述整个画面。没有任何东西可以代表你运行它；您或您的代理显式运行它，就像您运行此存储库中的任何其他脚本一样。它拒绝（退出 1，不写入任何内容）它不能将其视为普通文件的配置：1 比 1 MiB、不是常规文件的配置，或者通过离开项目的链接到达的配置。它通过重命名的独占临时文件写入配置及其 .bak，因此放置在任一位置的链接都会被替换，而不会被写入，并且它会根据已读取的字节生成 .bak。 --global 仍然通过 ~/.claude/.coalhearth.json 处的链接进行写入，因为点文件管理器链接该文件；它的读取也是有限的。

高影响力的密钥，以及每个密钥的确切 CLI 标志（node scripts/configure.mjs <flag> <value>；--global 目标为 ~/.claude/.coalhearth.json 而不是项目配置；node scripts/configure.mjs --help 列出了所有七个）：

每个标志都是点分键逐字 — --journal.outputDirectory、--journal.atomicityRetries 和 --update.updateCheckDays 遵循下面相同的行，此处不再重复；扁平的 --outputDirectory 可以用两种方式拼写一个键，因此没有速记形式。

language 位于 coalhearth.json 的顶层，不嵌套在组下 - {"language": "auto"}，从不嵌套在 {"recovery": {"language": "auto"}} 下。 auto（出厂默认值）遵循对话自己的语言，并以英语为后备，无需额外的配置。锁 (th/en/ja/zh/es) 只能翻译散文 — 命令、路径、标识符、配置键和严重性标签无论锁如何，都保持逐字不变。真正尊重它的是什么：SessionStart 钩子自己的排放（恢复块、日志目录警告、自更新微调）在设置为 auto 以外的任何内容时附加一个命名锁定语言的指令；今天这个房间里没有其他东西可以读取钥匙。

项目获胜的两个例外： update.updateMode 和 recovery.autoInjectPrompt 控制向外的操作（轻推；整个恢复块注入），因此项目 .coalhearth.json - 不受信任，它随您克隆的任何存储库一起到达 - 只能 QUIETEN 相对于您的全局配置之一，永远不会重新启用某些东西你全局关闭了。所有其他键（大写字母、路径、stashUnsavedChanges）都保持简单的项目胜利。

完整密钥参考：每个密钥+默认值都位于 scripts/lib/config-schema.mjs 和注释模板 platform-configs/.coalhearth.json 中。

权限

CoalHearth 要求该系列中最轻的配置文件：它读取项目的规划文件（task.md、AGENTS.md）及其自己的日志，并且每次写入都包含在您的工作空间内 - 永远不会在工作空间之外。确切的目的地是 journal.outputDirectory (.coalhearth.json)，默认为它自己的命名空间 .claude/coalhearth/；该密钥是项目可配置的，并且项目配置是不受信任的（它与您克隆的任何存储库一起提供） - 项目可以将其重定向到像 src/ 这样的真实目录，包含但不再局限于 CoalHearth 自己的状态。没有网络，没有执行，没有子代理生成，也没有在其自己的 scratch/lock 文件之外进行删除。挂钩是其唯一的生命周期功能，其功能以平台附带的任何挂钩引擎为关键。

全系列矩阵+必失败集：权限矩阵

基准

测量中断损坏（2026-07-03，v1.0.0）：在 10 个文件的中期重构中，热恢复和冷重启均以 <1% 令牌增量正确完成 - 在小规模下，强大的模型会从树重建状态，因此 CoalHearth 的令牌保存具有 大型会话 效果。它的不可约值是状态保真度：运行中的子代理记录冷重启无法重建。全表+诚实范围：TheColliery/.github/benchmarks/CoalHearth。

TheColliery 的一部分

CoalHearth 是收益采集系列的 会话连续性 成员，其他成员包括：

• CoalMine — 优质金丝雀
• CoalTipple — model/effort 路由
• CoalBoard — 共识与辩论
• CoalFace — 扇出规则
• CoalWash — 内存碎片整理
• CoalLedger — 文档健康
• CoalGob — OS-垃圾删除防护（PUBLIC BETA v0.1.0-beta.1；发动机+测试船，无skill/hook尚未浮出水面）

安装一个，它是独立的；安装全部，它们组成没有冲突。

共享原则：Phoenix-13 挂钩（零依赖、无网络、故障静默、无子进程、确定性）、单一真实来源配置模式以及严格的无过度杀伤规则。系列主义：TheColliery/.github。

零依赖，默认离线，没有 API 密钥——“默认”是因为同意门控自我更新检查（/coalhearth:update）上线；钩子永远不会这样做。