Claude Code 的 Artifact Watch 生命周期解析：发布订阅、版本合并与会话恢复机制-开发者社区

文档
提示工程
人工智能

【免费下载链接】claude-code-system-prompts

All parts of Claude Code's system prompt, 27 builtin tool descriptions, sub agent prompts (Plan/Explore/Task), utility prompts (CLAUDE.md, compact, statusline, magic docs, WebFetch, Bash cmd, security review, agent creation). Updated for each Claude Code version.

项目地址：https://gitcode.com/gh_mirrors/cl/claude-code-system-prompts

点击查看免费下载

本文基于 claude-code-system-prompts 仓库中的会话级 Artifact Watch 生命周期文档展开，并结合 Artifact Watch 动作参数指南、持久化 Watch 指南与 CHANGELOG 中的演进记录，系统讲解 Claude Code 中 live artifact watch 的完整生命周期。阅读本文后，你将掌握：发布即订阅的 watch 建立机制、watch/unwatch/status三类动作的语义与边界、遇到"更新版本已发布"时的合并重发流程、评论自动回复的武装（arming）条件，以及会话恢复（--resume/--continue）时 watch 的还原规则。

一、背景：Claude Code 中的 Artifact 与 Live Watch

Claude Code 的 Artifact 是会话中发布的可交互页面型产物（如仪表盘、文档、白板等），支持被本会话或其他会话、以及从页面侧保存的新版本反复更新。为了跟踪这些更新，Claude Code 引入了Artifact Watch（产物监听）机制：发布一个 artifact 后，会话会在后台订阅它的 live changes，从而在他人重新发布新版本时感知到变化。

需要说明的是，本仓库（claude-code-system-prompts）本身是 Claude Code 系统提示词的镜像仓库，本文所述行为均来自仓库内各提示词文档的官方描述，对应文件包括：

会话级 Artifact Watch 生命周期（本文核心文档）
Artifact Watch 动作参数指南（watch/unwatch/status/resume_replies 语义）
持久化 Artifact Watch 与状态指南（远程会话的 durable wake 订阅模型）
远程 Artifact Watch 指南（远程会话变体）
Artifact Watch 批准说明（批准范围与通知行为）
Artifact 自动回复恢复提醒（评论自动回复的恢复细节）

这些文档头部带有ccVersion（如2.1.274）与模板变量声明（如HAS_ARTIFACT_COMMENTS、COMMENTS_OFF_SENTENCE），表明它们会被按 Claude Code 具体版本与运行环境动态渲染后注入系统提示词。

二、发布即订阅：Watch 的自动建立

核心文档开篇即定义了最基本的生命周期规则："发布一个 artifact 会开始让本会话在后台订阅它的 live changes"。也就是说，watch 的建立不需要显式动作，发布行为本身即触发订阅流程。

但订阅"开始"与订阅"成功"是两回事，文档对此有精确区分：

发布结果行（publish result line）会说明 watch 是began（已开始）、skipped（被跳过）还是already connected（已连接）；
action: "status"才显示 watch是否真的连接上了；
如果无法连接，你会被告知失败；
如果连接中途断开，watch会自动重连（"watches reconnect on their own if the connection drops"）。

这一区分在 CHANGELOG 的演进条目中反复被强调。例如第 943 行记录："distinguish watch arming from an established connection"（区分 watch 的武装与已建立的连接），第 913 行记录 "recognize an 'already registered' result as evidence of a remote watch"（将"已注册"结果视为远程 watch 存在的证据）。这与本文第 7 节"真实性要求"直接呼应。

从行为模型看，这描述的是一个连接状态机：

发布 → 后台开始订阅（began / skipped / already connected） ↓ status 确认实际连接（connected / 未连接） ↓ 连接断开 → 自动重连

三、主动管理与停止：watch / unwatch / status

3.1 主动 watch：监听非自己发布的产物

发布是建立 watch 的默认途径，但它只覆盖"本会话刚发布的 artifact"。要监听并非本会话刚刚发布的 artifact，或者重启一个已停止的 watch，则需要显式传入动作：

action: "watch" + url（目标 artifact 的地址）

Artifact Watch 动作参数指南将其语义定义为："'watch' 打开对url处 artifact 的 live-update 订阅，使本会话持续追踪在别处发布的新版本（由另一个会话发布，或由某人从页面自身保存发布）"。并强调："新版本不会开启新 turn，也不会发送通知"——watch 是一种静默跟踪，它把变化信息留待合适时机使用，而不是像消息一样即时打扰会话。

3.2 status：查询当前 watch 状态

action: "status" # 列出本会话的全部 watch action: "status" + url # 只检查某一个 watch

status是验证 watch 是否真实存在的权威手段。在评论自动回复启用时，它还承担另一项职责：显示各 watch 的auto-replies armed（自动回复已武装）状态（详见第 5 节）。

3.3 unwatch：停止监听

action: "unwatch" + url # 停止对指定 artifact 的监听

3.4 生命周期边界：会话局部性与 /tasks 可见性

Watch 具有严格的会话局部性（session-local）：它只在本会话存续期间有效。用户可以在/tasks界面中查看并手动停止会话持有的所有 watch。这意味着 watch 不是一个跨会话的全局资源，它依附于会话进程与用户控制面板，而非 artifact 本身。

从 CHANGELOG 第 1283 行可以回溯这一机制的引入："Adds session-local watches for Artifact republishes, including automatic subscription after publishing, explicit watch/status/unwatch actions, reconnect behavior,/tasksvisibility, and requirements not to claim an unconfirmed watch"。这里明确列出了会话局部 watch 的五大组成：发布后自动订阅、显式 watch/status/unwatch 动作、重连行为、/tasks可见性、以及"不得声称未确认的 watch"。

四、版本冲突：新版本发布时的合并与重发流程

4.1 识别"更新版本已发布"提示

部分 Artifact 结果会以一行提示开头，告知有一个更新的版本已被发布（"Some Artifact results open with one line saying a newer version was published"）。这是版本竞争的信号：你手中的版本已经不是最新。

4.2 正确的合并姿势：读取线上版本而非本地文件

文档给出了明确的处理协议：

重新获取该 artifact 的 URL——使用 Artifact 工具的action: "read"，而不是读取你的本地文件。本地文件代表的是你上次掌握的内容，可能与线上最新版本脱节；
将你自己的编辑合并（merge）到那个较新的版本之上；
合并完成后再发布。

4.3 发布被拒绝时的处理

当发布因 artifact 已变更而被拒绝时（"a publish is refused because the artifact changed"），处理方式是遵循拒绝信息——拒绝信息通常会直接把你带到需要合并的那个最新版本（"usually hands you that version to merge"），此时直接在该版本基础上完成合并即可。

这一"重读 → 合并 → 重发"的闭环在 CHANGELOG 第 425 行有对应记录："A newer published version starts no turn and sends no notification; Claude re-reads the artifact and merges its edits before republishing"，并在第 882 行进一步强化为："require re-read, merge, and republish handling when local source falls behind a page-authored version"。它保证了多会话协作编辑同一个 artifact 时，任何一方都不会用陈旧版本覆盖新内容——先同步、再落笔、后发布。

五、评论自动回复：武装（arming）条件与唤醒规则

这是核心文档中条件性最强的部分（由模板变量HAS_ARTIFACT_COMMENTS控制渲染）。其完整规则如下：

5.1 谁能唤醒会话

只有"发给 Claude 的评论"能唤醒本会话（"A comment on a watched artifact that is sent to Claude wakes this session"），且存在前置条件：该 artifact 的status行必须显示auto-replies armed（自动回复已武装）。普通评论（plain comments）从不通知本会话——当用户询问评论内容时，应使用action: "comments"主动读取。

5.2 武装的两种途径

评论自动回复的武装（arming）只可能通过以下两条途径发生：

途径	条件
发布（publish）	本会话开启了评论自动回复（comment auto-replies on for this session）
watch	目标是用户可编辑的 artifact，且该 artifact 的链接是用户在用户自己的消息中给出的

文档特别强调了一个否定边界：绝不会对"用户只能查看（view-only）"的 artifact 武装自动回复。这保证了自动回复只作用于用户明确授权且可编辑的产物，避免对只读页面产生越权行为。

5.3 resume_replies：恢复被停止的自动回复

Artifact Watch 动作参数指南补充了第四个动作resume_replies的完整语义：

何时停止：该 artifact 的 live-updates 任务被 kill，或 watch 被 unwatch 时，自动回复停止；
何时暂停：用户用 Ctrl+C / Stop 中断会话时，自动回复暂停——但 watch 本身保留，直到用户的下一条消息；
resume_replies 的作用：解除中断对保留 watch 的暂停，或重新武装 live watch；只能在用户明确要求恢复自动回复时使用；
批准方式：与发布一样需要批准（默认模式下会弹出提示）；
无法撤销：它无法撤销来自 kill-all-agents 手势的会话级自动回复解除（disarm）。

恢复后的行为细节记录在 Artifact 自动回复恢复提醒中，它会根据stop_kind区分两种历史评论的处理：

若停止原因是interrupt（Ctrl+C / Stop 中断）：暂停期间发给 Claude 的评论也会被回答；
若停止原因是user（watch 被 kill 或 unwatch）：停止期间发送的评论保持未回答的历史状态；
若 watch 重连失败、本 turn 在连接前被中断、或用户在连接前再次停止自动回复，则停止状态保持——应通过action: "status"检查，并在用户仍需要时再次 resume。

六、会话恢复：--resume / --continue 后的 watch 还原

6.1 交互式终端的恢复行为

在交互式终端中使用--resume或--continue恢复会话时，watch 的还原遵循以下规则：

本会话最近发布或读取的 artifact 上的 watch 通常会恢复（"usually comes back"）；
所有正在回复评论的 watch 也会一并恢复——并且会继续回复，除非用户此前已将其停止；
其他客户端可能什么也不恢复（"other clients may restore nothing"）；
恢复后以status为准确认哪些 watch 处于武装状态。

6.2 恢复语义与持久化模型的差异

值得注意的是，watch 的"还原能力"取决于会话类型。对比持久化 Artifact Watch 与状态指南与远程 Artifact Watch 指南：在远程会话中，watch 是"由 artifact 服务持有的 durable wake subscription（持久化唤醒订阅）"，而非实时连接——远程会话在被 watch 的 artifact 于别处重新发布时会被以一个新 turn 唤醒，唤醒后应先重新读取 artifact（评论唤醒时还要读取评论）再进行编辑。

而本文核心文档描述的本地/会话级 live watch则是实时背景连接，断开后自动重连。两类模型（live connection 与 durable wake subscription）构成了 CHANGELOG 第 672 行所称的"split live, durable, remote, and restored-session watch variants into dedicated prompts"（将 live、durable、remote 与恢复会话四种 watch 变体拆分为各自的提示词）。

七、真实性要求与持有边界

核心文档以两条硬性规则收尾，这是避免会话产生误导性声明的关键约束：

7.1 不要声称不存在的 watch

"除非 watch 结果、status或发布结果中的 'already connected' 行说明你正在 watch 某个 artifact，否则不要声称自己在 watch 它——'arming'（武装）那一行还不算一个 watch。"

这条规则的含义是：发布结果中可能出现"arming"字样（表示武装流程已发起），但这仅代表订阅流程被启动，不代表订阅已建立。判断依据必须来自：watch 结果、status输出，或发布结果的"already connected"行。这一"武装不等于连接"的区分在 CHANGELOG 第 943 行有直接记载："distinguish watch arming from an established connection"。

7.2 只有主循环会话能持有 watch

"只有主循环会话（interactive、SDK 或 background）持有 watch；子代理（subagent）、队友（teammate）或打印（print）会话不能。"

这条边界同样体现在 Artifact Watch 动作参数指南中："Watches live only as long as this session, and only a main-loop session (interactive, SDK, or background) holds one — a subagent, teammate, or print session's publish or 'watch' arms none"（子代理、队友或打印会话的 publish 或 watch 动作不会武装任何 watch）。CHANGELOG 第 485 行记录了这一演进："Allow background main-loop sessions to hold Artifact watches while continuing to exclude subagents, teammates, and print sessions"——即背景主循环会话也被允许持有 watch，但子代理、队友与打印会话始终被排除。

7.3 批准范围

Artifact Watch 批准说明补充了用户视角的批准语义：批准覆盖本会话剩余时间内对该 artifact 的 watch；若要为另一个 artifact开启自动回复，则会再次询问。此外，republish（重新发布）通知不携带任何内容（"republish notifications carry no content"）——这是安全设计：watch 唤醒/通知只提示"发生了重新发布"，不把页面内容当作指令注入会话。

八、与其他机制的边界：Live Room 的对照

为帮助理解 watch 的定位，可将其与 Artifact 的Live Room机制对照（详见 Artifact Live Room 指南）：

Watch：针对 artifact 新版本的订阅跟踪，跨会话、跨时间，与页面是否打开无关；
Live Room：同一时刻所有正在查看页面的观看者之间的at-most-once 广播通道，不存储任何内容（"nothing sent through it is stored"），事件以<artifact-room-event>通知到达，且按每 artifact 每半秒至多一条合并。

简言之：watch 面向"版本的持久跟踪与协作合并"，live room 面向"当前在场观看者的瞬时交互"。文档明确写道："Anything that must outlive the moment belongs in a republish (or the artifact database), not the room"——需要跨时刻存续的内容属于重新发布或 artifact 数据库，而非 room。

九、演进脉络：从 CHANGELOG 看 watch 机制的成熟过程

仓库 CHANGELOG.md 提供了该机制的完整演进证据，按时间线可梳理出以下关键节点：

会话局部 watch 的引入（第 1283 行）：发布后自动订阅、watch/status/unwatch 动作、重连行为与/tasks可见性；
变体拆分（第 672 行）：将 live、durable、remote 与恢复会话四种 watch 变体拆分为独立提示词，统一覆盖唤醒与重读行为、可选评论唤醒、真实的武装与状态报告、重连/恢复，以及交互式/主循环会话的资格；
武装与连接区分（第 943 行）：明确"武装"与"已建立连接"的差异，限制评论唤醒仅作用于已武装的自动回复，--resume/--continue后至多恢复一个 watch，并收紧基于 status 的活跃 watch 声称；
主循环会话资格扩展（第 485 行）：背景主循环会话获准持有 watch；
远程 durable 订阅模型（第 466 行）：远程会话的 watch 成为针对重新发布与已激活评论的持久化唤醒订阅；
评论自动回复的武装边界（第 808 行）：允许watch在会话自动回复启用且用户提供可编辑 artifact 链接时武装评论自动回复，同时继续禁止对只读页面武装。

十、小结：Watch 生命周期一览

综合核心文档与配套提示词，一个完整且真实的 watch 生命周期可以概括为以下时序：

建立：发布 artifact（后台自动开始订阅），或显式action: "watch" + url监听非本会话发布的产物；status确认实际连接；
运行：静默跟踪别处（其他会话或页面侧保存）发布的新版本——新版本不开启 turn、不发送通知；连接断开时自动重连；
版本竞争：遇到"较新版本已发布"提示，用action: "read"重读线上版本并合并自己的编辑后再发布；发布被拒绝时按拒绝信息拿到最新版本合并；
评论唤醒（可选）：仅当 status 行显示 auto-replies armed 时，发给 Claude 的评论才唤醒会话；普通评论一律用action: "comments"读取；
停止与暂停：action: "unwatch" + url停止；Ctrl+C / Stop 中断仅暂停（watch 保留），resume_replies在用户明确要求时恢复；
恢复：交互式终端--resume/--continue后，最近发布/读取的 artifact 的 watch 与正在回复评论的 watch 通常还原（其他客户端可能不还原），以status为准；
边界：watch 会话局部、用户可在/tasks中管理、仅主循环会话（interactive/SDK/background）持有、子代理/队友/打印会话不可持有；未获 watch 结果、status或 "already connected" 行确认前，不得声称正在 watch。