plannotator

Plannotator CLI 参考

Plannotator 是一个面向 Agent 工作流的本地浏览器审查层：它会在标注界面中打开计划、差异和文档，由人工进行标注，然后将结构化反馈通过 stdout 返回给你。它以单个 plannotator 二进制文件和针对各主机的钩子进行安装，因此退出计划模式时会自动触发计划审查；其他所有场景都需要显式启动，有 plannotator 工具时使用该工具，否则使用 CLI。会话在随机的 localhost 端口上运行（远程模式下固定使用 19432 端口），并会一直阻塞，直到审查者提交反馈、批准或关闭标签页。

此技能是知识层。plannotator-review、plannotator-annotate 和 plannotator-last 技能是最常见三种操作的轻量启动器；需要自行选择合适的命令或标志时，请使用本参考。

如果你有 plannotator 工具，务必使用它

运行以下任何命令前，请先检查你的工具。如果你有一个名为 plannotator 的工具（它可能带有前缀，例如在 Claude Code 中为 mcp__plannotator__plannotator，也可能需要先通过工具搜索加载），务必调用它，而不是运行 plannotator annotate、plannotator review 或 plannotator last。这也包括审批：使用 { "action": "annotate", "target": "<file>", "gate": true } 调用，而不是使用 --gate --json。

该工具会立即返回。调用后请结束当前轮次并等待：审查者的决定会在之后作为消息送达。不要同时运行 CLI、轮询或重新打开会话。

仅当你没有此类工具，或要执行该工具无法完成的操作时，才使用 CLI：archive、guide、sessions、除 --base 和 --gate 以外的审查标志、除 --gate 和 --markdown 以外的标注标志，以及脚本通过退出代码检查的严格门控（--require-approval、--result-file）。如果你的工具提供 tailscale，请传入 tailscale: true，而不是使用 --tailscale。

选择命令

用户想要	运行（没有 plannotator 工具时使用 CLI）
审查你生成的计划	无需操作。退出计划模式时，钩子会自动打开计划审查。切勿自行运行不带参数的 plannotator。
审查并明确批准保存为文件的计划／规格说明	plannotator annotate <file> --gate --json
审查当前代码更改	plannotator review
审查 GitHub PR、GitLab MR 或 Bitbucket Cloud PR	plannotator review <PR_URL>
标注 Markdown、文本、配置或 HTML 文件	plannotator annotate <file>
标注网页	plannotator annotate <https-url>
标注正在运行的本地应用（开发服务器）	plannotator annotate <http://localhost:PORT/>
从文件夹中选择要标注的文件	plannotator annotate <folder/>
标注你最近发送的助手消息	plannotator last
浏览过往的计划决策	plannotator archive
导出或分享 Guided Review	plannotator guide export / plannotator guide share
重新打开或列出正在运行的会话	plannotator sessions
向对方提出问题，让对方稍后回答而不阻塞	如果有 plannotator_inbox 工具，则使用该工具；否则使用 Inbox 的 MCP 服务（plannotator inbox mcp）

会话模型

每个 review 或 annotate 命令都会启动本地 Web 服务器、打开浏览器，并阻塞等待人工决策。这可能需要几分钟；对于大型拉取请求，也可能超过一小时。启动时请设置较长的命令超时时间（或不设超时），也可以在后台运行，然后在进程退出后读取 stdout。在 Claude Code 中，后台命令会在 30 分钟后停止，除非你通过 run_in_background 并设置更长的 timeout（最长 7200000 ms）。不要为了“完成” review 而终止进程；会话结束时若没有决策，则视为没有反馈。如果会话因时间限制而停止，请重新运行相同的命令：批注草稿会恢复。

stdout 是交互接口，但具体约定因命令而异。对于 annotate 及其 last-message 变体：

• 纯文本（默认）：关闭时输出为空；批准时输出 The user approved.（如果批准附带备注，则改为输出“Approved with Notes”消息；请将备注视为指导，而非变更请求）；否则输出反馈文本。请在同一对话中处理返回的反馈。
• --json：输出一条 JSON 记录，包含 decision（approved、dismissed 或 annotated）以及可选的原始 feedback。批准仍可能在 feedback 中附带备注；请将其视为指导，而非变更请求。
• --hook：仅在真实的 PostToolUse/Stop hook 上下文中使用 hook 原生输出。批准/关闭时不输出内容（hook 放行）；有批注时输出 {"decision":"block","reason":"..."}。--hook 会启用门控 UI。请勿在普通交互调用中使用。

plannotator <command> --help 会打印用法说明，不会启动任何内容。裸命令 plannotator 是 hook 入口，需要从 stdin 接收 hook JSON。

plannotator review

plannotator review [--git | --gitbutler] [--base <ref>] [--diff-type <type>] [--local | --no-local] [--patch-file <path | ->] [--no-git-remote-check] [--tailscale] [--gate] [--json] [DIRECTORY | PR_URL]

Review 本地 VCS 变更；如果提供了 URL，则 review 对应的拉取请求。默认 stdout 保持纯文本：输出现有的关闭消息、批准提示或反馈。

使用 --json 时，直接 review 会输出一条记录：{ decision: 'approved' | 'annotated' | 'dismissed', message: string }。message 是 CLI 渲染的文本，与默认纯文本输出完全一致，但不包含末尾的控制台换行符。其中包括自定义提示，以及非阻塞的“批准并附带备注”说明；仅当 annotations.length > 0 时才会包含拒绝后缀，包括 PR 模式；平台状态为零条批注时则不会包含。

只能根据 decision 对结果进行分类，切勿根据 message 文本判断。approved review 中的备注属于指导，不是阻塞性的变更请求。此处渲染的 message 约定与 annotate 使用的原始反馈 JSON 以及未更改的 opencode-review 集成相互独立。--hook 仅适用于 annotate。

• VCS 会自动检测（支持 JJ、GitButler、Git 和 P4）。--git 强制使用普通 Git；--gitbutler 强制使用 GitButler（需要 but CLI 0.21.0+）。如果从包含嵌套仓库的非 VCS 父文件夹运行，会生成合并工作区 diff。
• 默认 diff 显示“当前 PR 会展示的所有内容”：主干分支与工作树的合并基准，以及未跟踪文件。--base <ref> 会以不同的比较目标（分支、origin/<branch>、标签或提交）打开会话，--diff-type <type> 会以不同的模式（since-base、merge-base、branch、uncommitted、staged、unstaged、last-commit、local-vs-remote、all）打开会话。两者都仅对当前会话生效：审阅者可以在 UI 中更改它们，且都不会修改用户保存的默认设置。
• 要审阅堆叠分支中的某一层？传入 --base <the branch below yours> — plannotator review --base feature/part-1 只显示这一层新增的内容，而不是自 main 以来的所有内容。
• 这两个标志仅适用于 Git：在 jj、GitButler、Perforce、多仓库工作区审阅和 PR URL 上使用时会报错（PR 的基准来自拉取请求）。无法解析的 --base 引用会导致启动错误，并列出名称相近的分支，绝不会悄悄显示错误的 diff。
• --patch-file <path> 可在完全没有仓库的情况下，审阅由调用方提供的静态统一 diff（使用 - 从 stdin 读取）：会话会原样提供补丁，不启用任何需要工作树的文件系统功能。它不能与 PR/MR URL、--base、--diff-type、--git/--gitbutler 或 --local/--no-local 一起使用。此会话会关闭所有工作树功能（暂存、扩展代码块上下文、在编辑器中打开、代码导航、切换 diff 类型/基准），其背后的端点会返回 400。
• 传入目录即可审阅另一个仓库或工作树：plannotator review ../feature-worktree 或 plannotator review ./backend --diff-type last-commit。路径相对于调用命令的目录解析；路径包含空格时请加引号。目录用于选择审阅工作区，而不是文件筛选器。接受一个目录或 PR URL；目录不能与 --patch-file 一起使用。无效目标会导致失败，不会回退到当前仓库。
• PR 审阅（plannotator review https://github.com/owner/repo/pull/123，也支持 GitLab MR 和 Bitbucket Cloud PR URL）需要已通过身份验证的 gh 或 glab CLI；Bitbucket Cloud（https://bitbucket.org/<workspace>/<repo>/pull-requests/<id>）则需要在 PLANNOTATOR_BITBUCKET_TOKEN 中设置 Atlassian API 令牌（以及 PLANNOTATOR_BITBUCKET_EMAIL）。默认的 --local 会在后台为 PR 头部构建本地检出，以提供完整的文件访问权限；--no-local 会跳过此步骤，仅审阅平台 diff。
• --no-git-remote-check 会阻止会话联系任何 git 远程端：不会运行 git ls-remote 获取默认分支，也不会执行“落后于 GitHub”基准检查。此时比较目标仅来自本地引用，且不会显示过时状态横幅，因此也无法使用其中的一键 Fetch 按钮（/api/fetch-base 端点仍可用）；在终端中获取不受影响。当远程探测开销较大或具有侵入性时可使用此选项——尤其是 SSH 身份验证依赖硬件令牌时，每次探测都会要求进行实体触碰确认。也可通过 PLANNOTATOR_GIT_REMOTE_CHECK=0 或在 ~/.plannotator/config.json 中设置 { "gitRemoteCheck": false } 来为整个会话关闭该检查（标志优先级高于环境变量，环境变量优先级高于配置键）。不关闭时，会在打开审阅、加载 diff、切换 diff 类型/基准以及 Fetch 时查询远程端；不会按计时器查询。
• --tailscale 会通过 tailscale serve 将本地回环会话发布到用户的 tailnet（HTTPS，绝不会公开到互联网），并打印带二维码的 URL。发布失败时会以非零状态退出，而不是让服务器一直挂起。仅当用户要求在其他设备（手机、平板）或通过 Tailscale 打开审阅时使用。如果有提供该功能的 plannotator 工具，请改为传入 tailscale: true（annotate、review、last）：这样“询问此会话”在 tailnet 上仍可用于拥有这台计算机的 Tailscale 登录账号。
• --gate 表示你正在等待审阅者签字确认后再继续（提交、打开 PR）：即使只点击“Approve”，结果也会传回给你。如果使用 plannotator 工具，请改为在 review 操作中传入 gate: true。

plannotator annotate

plannotator annotate <target> [--markdown] [--no-jina] [--app | --static] [--render-html] [--tailscale] [--gate] [--json] [--hook]

在注释界面中打开一个文档、页面或应用，并将用户的注释返回到 stdout。

普通的 annotate 仅用于反馈：它会显示 关闭，但不显示 批准 按钮。当用户要求审核、批准、接受或把关保存在文件中的生成计划、规范或文档时，如果有 plannotator 工具，请调用该工具并设置 "gate": true；否则始终添加 --gate --json。不要告诉用户可以在普通的 annotate 会话中批准。如果计划通过宿主 Agent 的原生计划流程移交，请勿启动 annotate；由计划退出钩子自动打开批准界面。

目标：

• Markdown 和文本文件：.md、.mdx、.txt。
• 以文本形式呈现的纯文本配置和数据文件：.yaml、.yml、.json、.jsonc、.json5、.toml、.ini、.cfg、.conf、.properties、.csv、.tsv、.log、.xml、.env.example。有意拒绝 .env 文件（其中通常包含机密信息，而且 annotate 历史记录会复制文件内容）。源代码文件应使用 plannotator review，而非 annotate。
• 在完整图表查看器中打开的图表源文件（可缩放、平移、弹出，并可点击节点／边／集群添加评论）：.mmd、.mermaid（Mermaid）以及 .dot、.gv（Graphviz）。文件内容就是完整图表，无需代码围栏；评论会附带对应部分的 id 和实际文件行号。
• HTML 文件（.html、.htm）：默认将原始页面作为页面呈现；--markdown 会改为将其转换为 Markdown。为保持兼容性，接受 --render-html；默认已是原始呈现。
• URL（https://...）：默认通过 Jina Reader 获取并转换；--no-jina 则改用普通抓取加 Turndown。
• 正在运行的本地应用：如果环回 http://localhost:PORT/ URL 的探测结果为 HTML，则会以实时应用模式打开（对实际运行的页面添加注释）。--app 强制使用实时模式，无法应用时会明确报错；--static 强制使用经典转换流程。非环回 URL 始终使用转换流程。
• 文件夹：plannotator annotate docs/ 会打开一个文件浏览器，浏览该文件夹中受支持的文件。
• 多个文件：plannotator annotate spec.md mock.html notes.md 会按给定顺序将它们作为一次审核打开，并作出一个决定。每个参数都必须是通过路径命名的现有文件（不能混入文本、URL 或文件夹）。使用 plannotator 工具时，将列表作为 target 传入。

单个文件大小上限为 2MB。文件会从磁盘上的稳定项目路径读取；请将待审核的源文件保留在原位置。

参数容错：可以添加额外文字（plannotator annotate look at notes.md please 会打开 notes.md），但若两个可解析目标与文本、URL 或文件夹混在一起，则会报错并指出这些目标；无法识别的连字符参数会关闭容错，因此参数拼写错误会明确报错。如果普通的多词调用没有解析出任何目标，CLI 会在 stdout 上输出面向 Agent 的移交说明并以 0 退出：请阅读说明，确定具体目标，然后使用准确路径或 URL 重新运行。

严格把关与退出代码

对于可由机器检查的批准把关，请添加 --gate --json，并至少添加以下严格标志中的一个：

plannotator annotate report.md --gate --json --require-approval --result-file /tmp/decision.json

• --require-approval：退出代码反映人工审核结果。
• --result-file <path>：stdout 中的决定 JSON 也会以原子方式发布到 <path>。父目录必须已存在，且文件必须不存在；结果路径相对于调用时的 cwd 解析。

启用严格标志时的退出代码（grep 约定）：

退出代码	含义
0	已批准。唯一表示成功的代码。
1	审核者未批准（添加了注释或已关闭）；决定记录仍会发布。
2	把关本身失败：标志组合错误、启动失败（文件缺失、URL 无法访问、文件过大）或结果文件无法发布。绝不可将其视为审核结果。
128+n	被信号 n 终止。

未启用严格标志时，启动失败会以 1 退出，退出代码不包含决定结果；请改为解析输出。两个严格标志都要求使用 --gate --json，且不允许与 --hook 同时使用。

plannotator annotate-last

plannotator annotate-last [--stdin] [--tailscale] [--gate] [--json] [--hook]
plannotator last

在标注界面中打开当前 Agent 会话中最新渲染的助手消息（last 是别名）。系统会自动按宿主查找会话日志；--stdin 则从 stdin 读取内容。

运行此命令前，不要立即输出评论或状态消息：该命令的目标是最新渲染的助手消息，因此前言会成为待标注的内容。

plannotator copilot-last

plannotator copilot-last [--gate] [--json] [--hook]

适用于实时 GitHub Copilot CLI 会话的 annotate-last 变体（读取 Copilot 的会话状态事件）。通常由 Copilot 插件的 /plannotator-last 命令调用；仅在 Copilot CLI 会话中使用。

plannotator archive

plannotator archive

打开一个只读浏览器，浏览 Plannotator 数据目录中保存的计划决策（已批准／已拒绝徽章）。不会收到反馈；用户点击 Done 后会话结束。

plannotator guide

plannotator guide list
plannotator guide export --id <savedGuideId> [--out <file.html>]
plannotator guide export --guide <guide.json> --patch <diff.patch> [--out <file.html>]
plannotator guide export --snapshot <snapshot.json> [--out <file.html>]
plannotator guide share --id <savedGuideId> [--public] [--ttl <7d|24h|30m|3600>] [--json]
plannotator guide unshare <id> --token <deleteToken>

Guided Review 是在代码审查界面中生成的 AI 差异讲解。CLI 可对已保存的讲解执行以下操作：

• list 显示 Plannotator 为当前仓库持久化保存的讲解。
• export 写入一个可移植、自包含的 HTML 文件（查看器从 guides.show 加载）。--guide + --patch 可根据统一差异导出你自行编写的讲解（--patch - 从 stdin 读取；验证非常严格，并会指出讲解引用但差异中不存在的文件）。--out - 将内容写入 stdout。--viewer-url 可覆盖固定的查看器基础 URL。
• share 上传讲解并输出链接。默认加密：密钥仅保存在 URL 片段中，主机只存储密文。--public 会以未加密形式存储，以便聊天应用展开预览。--ttl 设置过期时间；否则链接会一直保留，直到执行 unshare。已保存的讲解会记录其链接；再次执行 share --id 时会拒绝操作，以免丢失首个链接的删除令牌。
• unshare <id> --token <t> 使用分享时输出的删除令牌移除链接。

plannotator sessions

plannotator sessions [--open [N]] [--clean] [--json]

列出活动的 Plannotator 服务会话，并显示每个会话的完整目标（绝对路径、URL、PR URL 或已审查目录）；对于主机打开的审查，还会显示其 pn- ID。--open 会在浏览器中重新打开第 N 个会话（默认为 1），适用于审查过程中标签页关闭的情况。--clean 会删除过期条目。--json 会在 stdout 上以 JSON 数组形式输出列表。

plannotator inbox

plannotator inbox [--background | --no-open | --open] [--tailscale]
plannotator inbox mcp

Plannotator Inbox 是每台机器上一个本地窗口，你可以在其中给对方留言、发送对方点击即可回答的 :::question 区块、发送待标注文件和 Guided Review。它不会阻塞工作：发送后，你可以继续工作或结束当前轮次。

• 当对方可能没有在查看当前聊天时使用它：询问只有对方才能作出的决定（发送 :::question 区块，然后继续处理不依赖该决定的工作）、告知已完成的长任务（附上一条简短摘要，并将要查看的文件放在 attachments 中），或者在对方提出要求时使用。对方在聊天中时，请直接在聊天中询问，不要发送例行进度更新。若需要在继续之前就本文档或差异征求决定，请使用审查（计划审查、annotate、review）。
• 如果你有 plannotator_inbox 工具，请使用该工具；否则使用 stdio MCP 服务 plannotator inbox mcp。使用该工具时，对方的回复会自动到达你的会话中，因此请结束当前轮次，而不要等待。
• 首次使用前，运行一次 plannotator inbox --help 并阅读其内容：这是完整指南（工具和参数、线程、回复位置、问题语法、替换问题、连接其他 Agent）。
• 切勿只为发送消息而运行 plannotator inbox：调用会在后台启动已停止的 Inbox；单独运行 plannotator inbox 则会打开对方使用的窗口。--tailscale 由对方决定；切勿自行添加。
• 对方询问 Inbox 的位置或要求打开 Inbox（已关闭的标签页）时，运行 plannotator inbox --open：该命令会在对方的浏览器中打开窗口（如有需要，会在后台启动 Inbox）、在 stdout 上输出地址并立即返回。请告知对方该地址。

plannotator card

plannotator card <create|move|say|link|ship|drop|list> ...

仅当用户已在收件箱的 Settings → General 中开启 Board 时才可使用；Board 默认关闭，此时每次调用都会返回 board_off，且不会写入任何内容，因此仅在收件箱工具列出 card 或用户提出要求时使用。Board 会为每项持续时间超过一条回复的工作保留一张卡片，并将其放在对应阶段的列中（backlog、designing、your_look、building、your_review、shipped）。如果有 plannotator_inbox 工具，请使用其 card 操作；此 CLI 会从 shell 发起相同调用。plannotator card --help 会显示参数；Board 开启时，plannotator inbox --help 会显示其卡片部分。冰箱区仅供用户使用。

其他子命令

plannotator setup-goal <interview|facts> <bundle.json | -> [--json]
plannotator update [--check]
plannotator uninstall [--purge] [--yes] [--dry-run]
plannotator improve-context

• setup-goal 会打开 /goal 工作流的访谈或事实确认 UI；该流程由 plannotator-setup-goal 技能驱动，并接收一个 bundle JSON（- 表示从 stdin 读取）。不要手动构建 bundle。
• update 会立即安装最新版本（使用安装脚本，并沿用上次安装时的选项）；--check 只报告是否有可用更新。仅在用户要求更新 Plannotator 时运行：它会替换二进制文件。退出码：0 表示已是最新版本或已更新，1 表示失败，2 表示用法错误，130 表示中断。
• uninstall 会移除由 Plannotator 安装的组件（--purge 还会删除本地数据；没有 TTY 时必须使用 --yes；--dry-run 会预览操作）。
• improve-context 和 install-runtime 是内部集成命令（用于 hook 配置和托管运行时安装）。切勿直接运行 improve-context；plannotator install-runtime agent-terminal 可用于重新安装可选的 annotate-terminal 运行时，通常由安装程序运行。
• 其他宿主内部子命令（opencode-* 和 copilot-plan 系列）由其插件调用，不要自行调用。

会改变行为的环境变量

变量	用途
PLANNOTATOR_REMOTE=1	强制启用远程模式（固定端口 19432，宽范围绑定），用于 SSH/devcontainer 会话；0 强制启用本地模式。未设置时会自动检测 SSH。
PLANNOTATOR_PORT	固定端口，而非随机分配。
PLANNOTATOR_ORIGIN	覆盖 Agent 来源检测（claude-code、codex、opencode、pi、oh-my-pi、amp、droid、copilot-cli、gemini-cli、kiro-cli、mistral-vibe）。如果从检测无法穿透的包装程序启动 Plannotator，请设置此变量。
PLANNOTATOR_AI=disabled	在 UI 中禁用 Ask AI 和由 Agent 启动的审核界面。
PLANNOTATOR_SHARE=disabled	禁用 URL 分享，包括指南分享链接。
PLANNOTATOR_DATA_DIR	更改数据目录位置（默认值为 ~/.plannotator）：计划、历史记录、草稿和配置。
PLANNOTATOR_BROWSER	在指定浏览器中打开会话；none 表示不打开任何浏览器（会话 URL 始终会打印到 stderr）。
PLANNOTATOR_UPDATE_CHECK=0	禁用自动检查新版本（也不会显示更新通知或自动更新）。运行 plannotator update 时仍会检查。

将批注发送到实时会话

正在运行的计划审核会话会在其基础 URL 上提供一个小型 HTTP API，用于接收外部批注：POST /api/external-annotations 可添加审核者立即可见的行内批注；可使用 PATCH/DELETE 更新或删除批注，并通过 /api/external-annotations/stream 访问 SSE 流。UI 中的“复制 Agent 指令”操作会将当前会话的完整 API 契约（含正确的基础 URL）复制到剪贴板，以便交给 Agent 或脚本。如果用户粘贴了这类指令，请遵循其中内容；不要自行编造契约之外的端点。

向审阅者提问

将只有审阅者才能决定的问题作为问题块提出。答案会显示在反馈顶部（先是“Answers to your questions”，然后是“Unanswered”）。

:::question
Where should we keep the edit that loses a sync conflict?

When two devices edit one note offline, the later save wins and the other edit is lost. Local storage keeps it with no server work.

- [ ] Local only, purged after 30 days — cheap, no server change
- [ ] Server-side per user — survives reinstall, needs a retention policy
- [ ] Nowhere — accept silent loss for v1

Recommended: Local only, purged after 30 days
:::

• :::question 用于单选，:::question-multi 用于多选，:::question-text 用于自由文本（没有选项的区块也可以）。
• 第一行是问题；后续各行是背景信息。绝不要只发一个干巴巴的问题：审阅者可能刚加入，不了解情况，只会从产品层面思考，也不知道你掌握的信息。
  • 说明选项会带来什么影响、你了解或尝试过什么，以及你为什么推荐该选项，让他们无需查看其他内容也能做出决定。
  • 表达简洁：用简单的词写一到三句短句，不用术语或内部名称。
  • 对于视觉内容，添加截图（![alt](path)）。
  • 链接到能更清楚展示内容的文件（如计划、模型）：[the mock](mock.html)。在 Inbox 中也附上该文件；该链接会在讨论串旁边打开它。
• 选项格式为：- [ ] label，也可以写成 - [ ] label — why。审阅者也可以回答“Other”、添加备注或跳过。
• Recommended: <label> 用于标记你的推荐项（在 :::question-multi 中可写 A, B and C）；其他文本会作为另一个答案显示，并标记为 Recommended。
• 只问你无法独自决定的问题，每轮最多约 8 个。不要提出反问，也不要问代码库中已有答案的问题。
• - [x] 表示已确定的选项。重新提交时，勾选选定的答案，或删除该区块并用文字说明决定。
• 各部分之间留空行，让区块在 GitHub 上易于阅读。
• 每个答案都会显示在对应问题下方（格式为 ### Q2. <question> (line N)），内容为 Answer: <choice>；如果审阅者选择了你的推荐项，则会标记 (your recommendation)；也可能显示为 Other: …、引号中的自由文本或 Skipped，并附上任何 Note:。你标记为 - [x] 的问题已确定，只有在审阅者更改了答案或添加备注时才会再次显示。
• 在 Inbox 中，随着讨论进展，应撤回仍处于待处理状态的自有问题（read_thread 状态为 open 或 picked）：当较新的消息替代了这些问题、使其不再相关或对其进行了跟进，或者对方的回复已经用文字解决了这些问题时，在 supersedes（或 Replaces: 行）中列出它们，以免它们继续置顶显示在对方的列表中。

请勿

• 如果你有 plannotator 工具，请调用该工具；不要通过 shell 运行 plannotator annotate、review 或 last。
• 不要解析或抓取浏览器 UI 的 HTML；CLI 的 stdout（以及上文记录的 HTTP API）就是完整的约定。
• 不要在真实的 hook 上下文之外使用 --hook；需要结构化输出时，请使用 --json。
• 不要以交互方式直接运行 plannotator；它是 hook 的入口点。
• 不要猜测标志。拿不准时，运行 plannotator <command> --help；未知的带短横线标记的参数会导致 annotate 按设计失败。
• 不要将 plannotator annotate 指向源代码文件或 .env 文件；代码应通过 plannotator review 处理，且 .env 会被拒绝。
• 除非确实有人在场进行审阅，否则不要启动严格门禁（--require-approval）；会话会一直阻塞，直到有人采取操作。