🚀 快速安装

复制以下命令并运行，立即安装此 Skill：

npx @anthropic-ai/skills install supercent-io/skills-template/plannotator

💡 提示：需要 Node.js 和 NPM

plannotator — 交互式计划与差异审查

关键词：plan | 源代码：https://github.com/backnotprop/plannotator

可视化地审查和注释 AI 编码代理的计划，与您的团队分享，一键发送反馈。
适用于 Claude Code、OpenCode、Gemini CLI 和 Codex CLI。

何时使用此技能

  • 您想在 AI 代理开始编码之前审查其实施计划
  • 您想在代理进行更改后注释 git 差异
  • 您需要一个反馈循环：直观地标记需要更改的内容，然后将结构化反馈发送回去
  • 您想通过链接与团队成员分享计划审查
  • 您想将已批准的计划自动保存到 Obsidian 或 Bear Notes

脚本（自动化模式）

所有模式在 scripts/ 目录中都有对应的脚本。您可以直接运行它们，或让代理调用它们。

脚本 模式 用途
scripts/install.sh CLI 安装 一键安装；--all 设置所有 AI 工具
scripts/setup-hook.sh Claude Code 钩子 配置 Claude Code 的 ExitPlanMode 钩子
scripts/setup-gemini-hook.sh Gemini CLI 钩子 配置 Gemini CLI 的 ExitPlanMode 钩子 + GEMINI.md
scripts/setup-codex-hook.sh Codex CLI 设置 配置 Codex CLI 的 developer_instructions 和提示词
scripts/setup-opencode-plugin.sh OpenCode 插件 注册插件和斜杠命令
scripts/check-status.sh 状态检查 验证所有集成和配置
scripts/configure-remote.sh 远程模式 SSH / 开发容器 / WSL 配置
scripts/review.sh 代码审查 启动差异审查界面

模式 1：安装

# 仅安装 CLI（macOS / Linux / WSL）
bash scripts/install.sh

# 安装 CLI 并获取 Claude Code 插件命令
bash scripts/install.sh --with-plugin

# 安装 CLI + 配置 Gemini CLI
bash scripts/install.sh --with-gemini

# 安装 CLI + 配置 Codex CLI
bash scripts/install.sh --with-codex

# 安装 CLI + 注册 OpenCode 插件
bash scripts/install.sh --with-opencode

# 一次性安装 CLI 并集成所有 AI 工具
bash scripts/install.sh --all

它的作用：

  • 检测操作系统（macOS / Linux / WSL / Windows）
  • 检查 Obsidian 是否存在，如果缺失则显示安装链接：https://obsidian.md/download
  • 通过 https://plannotator.ai/install.sh 安装
  • 验证安装和 PATH 环境变量
  • 可选地运行每个 AI 工具的集成脚本
  • 在 Windows 上：打印需要手动运行的 PowerShell / CMD 命令

模式 2：钩子设置（计划审查触发器）

# 将钩子添加到 ~/.claude/settings.json
bash scripts/setup-hook.sh

# 预览将要更改的内容（不实际写入）
bash scripts/setup-hook.sh --dry-run

它的作用：

  • 检查 plannotator CLI 是否已安装
  • 安全地将 ExitPlanMode 钩子合并到 ~/.claude/settings.json（首先备份）
  • 如果钩子已配置则跳过
  • 运行此脚本后请重启 Claude Code

替代方案：Claude Code 插件（无需手动设置钩子）

在 Claude Code 内部运行：

/plugin marketplace add backnotprop/plannotator
/plugin install plannotator@plannotator
# 重要：插件安装后重启 Claude Code

模式 3：计划审查（编码之前）

当 Claude Code 退出计划模式时，通过钩子自动触发。

当您的代理完成规划后（Claude Code：Shift+Tab×2 进入计划模式），plannotator 会自动打开：

  1. 查看 视觉界面中的代理计划
  2. 注释 清晰意图：
    • delete — 删除有风险或不必要的步骤
    • insert — 添加缺失的步骤
    • replace — 修正错误的方法
    • comment — 澄清约束或验收标准
  3. 提交 一个结果：
    • 批准 → 代理继续实施
    • 请求更改 → 您的注释作为结构化反馈发送回去，用于重新规划

模式 4：代码审查（编码之后）

# 审查所有未提交的更改
bash scripts/review.sh

# 审查特定的提交
bash scripts/review.sh HEAD~1

# 审查分支差异
bash scripts/review.sh main...HEAD

它的作用：

  • 检查 CLI 和 git 仓库状态
  • 在打开前显示差异摘要
  • 启动 plannotator review 界面
  • 在界面中：选择行号进行注释，切换统一/分屏视图，附加图像

模式 5：远程 / 开发容器模式

# 交互式设置（SSH、开发容器、WSL）
bash scripts/configure-remote.sh

# 查看当前配置
bash scripts/configure-remote.sh --show

# 直接设置端口
bash scripts/configure-remote.sh --port 9999

它的作用：

  • 检测 shell 配置文件（.zshrc、.bashrc、.profile）
  • 将 PLANNOTATOR_REMOTE=1 和 PLANNOTATOR_PORT 写入 shell 配置文件
  • 显示 SSH 和 VS Code 端口转发说明
  • 可选择设置自定义浏览器或共享 URL

手动环境变量：

export PLANNOTATOR_REMOTE=1    # 不自动打开浏览器
export PLANNOTATOR_PORT=9999   # 用于转发的固定端口
变量 描述
PLANNOTATOR_REMOTE 远程模式（不自动打开浏览器）
PLANNOTATOR_PORT 固定的本地/转发端口
PLANNOTATOR_BROWSER 自定义浏览器路径/应用
PLANNOTATOR_SHARE_URL 自定义共享门户 URL

模式 6：状态检查

bash scripts/check-status.sh

检查所有项目：

  • CLI 已安装及版本
  • Claude Code 钩子在 ~/.claude/settings.json 中（或检测到插件）
  • Gemini CLI 钩子在 ~/.gemini/settings.json 中
  • Codex CLI ~/.codex/config.toml 中的 developer_instructions
  • OpenCode 插件在 opencode.json 中及斜杠命令
  • Obsidian 安装
  • 环境变量配置
  • Git 仓库可用于差异审查

模式 7：Gemini CLI 集成

# 配置 Gemini CLI（钩子 + GEMINI.md 指令）
bash scripts/setup-gemini-hook.sh

# 预览将要更改的内容（不实际写入）
bash scripts/setup-gemini-hook.sh --dry-run

# 仅更新 settings.json 中的钩子（跳过 GEMINI.md）
bash scripts/setup-gemini-hook.sh --hook-only

# 仅更新 GEMINI.md（跳过 settings.json）
bash scripts/setup-gemini-hook.sh --md-only

它的作用：

  • 检查 plannotator CLI 是否已安装
  • 将 ExitPlanMode 钩子合并到 ~/.gemini/settings.json（格式与 Claude Code 相同）
  • 将 plannotator 使用说明追加到 ~/.gemini/GEMINI.md
  • 修改前备份现有文件

在 Gemini CLI 中设置后的用法：

# 进入计划模式（退出时钩子触发）
gemini --approval-mode plan

# 手动计划审查（使用验证格式）
python3 -c "
import json
plan = open('plan.md').read()
print(json.dumps({'tool_input': {'plan': plan, 'permission_mode': 'acceptEdits'}}))
" | plannotator > /tmp/plannotator_feedback.txt 2>&1 &

# 实施后的代码审查
plannotator review

注意： Gemini CLI 支持 gemini hooks migrate --from-claude 来自动迁移现有的 Claude Code 钩子。

模式 8：Codex CLI 集成

# 配置 Codex CLI（developer_instructions + 提示词文件）
bash scripts/setup-codex-hook.sh

# 预览将要更改的内容（不实际写入）
bash scripts/setup-codex-hook.sh --dry-run

它的作用：

  • 将 plannotator 指令添加到 ~/.codex/config.toml 的 developer_instructions 中
  • 创建 ~/.codex/prompts/plannotator.md（使用 /prompts:plannotator 调用）
  • 修改前备份现有配置

在 Codex CLI 中设置后的用法：

# 使用 plannotator 代理提示词
/prompts:plannotator

# 手动计划审查（使用验证格式）
python3 -c "
import json
plan = open('plan.md').read()
print(json.dumps({'tool_input': {'plan': plan, 'permission_mode': 'acceptEdits'}}))
" | plannotator > /tmp/plannotator_feedback.txt 2>&1 &

# 实施后的代码审查
plannotator review HEAD~1

注意：使用 heredoc 或 echo 的 plannotator plan - 可能会失败，出现 Failed to parse hook event from stdin。请使用上面的 python3 JSON 格式。

模式 10：通过导出 → 笔记选项卡手动保存

随时将当前计划保存到 Obsidian 或 Bear Notes，无需批准或拒绝。

如何访问

  1. 点击 plannotator 界面工具栏中的 导出 按钮
  2. 点击 笔记 选项卡（不是共享或注释选项卡）
  3. 您会看到：
    • Obsidian 行，显示配置的仓库路径和 保存 按钮
    • Bear 行，带有 保存 按钮
    • 全部保存 按钮，可同时保存到两者
  4. 每行旁边的绿点表示该集成已配置
  5. 点击 保存，完成后会显示 已保存

何时使用

  • 保存进行中的计划，而不承诺批准/拒绝
  • 审查后快速存档，无需最终决定
  • 保存带注释的计划供团队参考

要求

  • plannotator 必须在 钩子模式 下运行（正常的 Claude Code ExitPlanMode 钩子调用 = 钩子模式）
  • Obsidian/Bear 必须在设置（⚙️）→ 保存选项卡中配置
  • 设置存储在 cookies 中（而不是 localStorage），并在重启后持续存在

注意： 笔记选项卡使用 POST /api/save-notes，它直接写入仓库文件系统（Obsidian）或调用 bear://x-callback-url/create（Bear）。此端点仅在钩子模式下可用。

推荐的工作流程

快速开始（所有 AI 工具）

# 1. 一次性安装 CLI 并配置所有 AI 工具集成
bash scripts/install.sh --all

# 2. 验证一切
bash scripts/check-status.sh

# 3. 重启您的 AI 工具（Claude Code、Gemini CLI、OpenCode、Codex）

Claude Code（手动）

1. bash scripts/install.sh --with-plugin
   └─ 安装 CLI 并显示插件安装命令

2. bash scripts/setup-hook.sh          ← 如果使用插件则跳过
   └─ 配置自动计划审查触发器

3. bash scripts/check-status.sh
   └─ 确认一切就绪

4. [让代理在计划模式下工作 → Shift+Tab×2]
   └─ plannotator 自动打开

5. bash scripts/review.sh              ← 在代理完成编码后
   └─ 打开视觉差异审查界面

Gemini CLI（手动）

1. bash scripts/install.sh
2. bash scripts/setup-gemini-hook.sh
3. gemini --approval-mode plan          ← 在计划模式下工作
   └─ 退出时 plannotator 触发

Codex CLI（手动）

1. bash scripts/install.sh
2. bash scripts/setup-codex-hook.sh
3. /prompts:plannotator                 ← 在 Codex 会话内

OpenCode 设置

# 自动化（推荐）
bash scripts/setup-opencode-plugin.sh

# 或手动添加到 opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@plannotator/opencode@latest"]
}

设置完成后，重启 OpenCode。可用的斜杠命令：

  • /plannotator-review — 为当前 git 差异打开代码审查界面
  • /plannotator-annotate <文件.md> — 注释一个 markdown 文件

submit_plan 工具自动对代理可用，用于提交计划。

模式 9：Obsidian 集成设置

自动将已批准的计划保存到您的 Obsidian 仓库，并带有 YAML 前置元数据和标签。

前提条件

  1. 安装 Obsidian：https://obsidian.md/download
  2. 创建一个仓库：打开 Obsidian → 创建新仓库 → 选择位置
    • 例如：~/Documents/Obsidian/MyVault
  3. 验证仓库存在：Obsidian 在首次创建仓库后会生成 obsidian.json 配置文件
# 检查 Obsidian 安装（macOS）
ls /Applications/Obsidian.app

# 检查 Obsidian 配置文件是否存在（仓库检测依赖于此）
# macOS
cat ~/Library/Application\ Support/obsidian/obsidian.json
# Linux
cat ~/.config/obsidian/obsidian.json
# Windows
cat %APPDATA%/obsidian/obsidian.json

逐步设置

# 步骤 1：验证 Obsidian 已安装并至少有一个仓库
bash scripts/check-status.sh

# 步骤 2：触发一次计划审查（任何方法）
# Claude Code：Shift+Tab×2 → 计划模式 → 退出计划模式
# Gemini CLI：gemini --approval-mode plan
# OpenCode：代理创建一个计划

# 步骤 3：在 plannotator 界面中：
#   1. 点击 ⚙️（设置齿轮图标）
#   2. 转到 "保存" 选项卡
#   3. 打开 "Obsidian 集成" 开关
#   4. 从下拉菜单中选择您的仓库（自动检测）
#      - 如果仓库未检测到，或输入自定义路径
#   5. 设置文件夹名称（默认："plannotator"）

# 步骤 4：批准一个计划以测试集成
#   - 在 plannotator 界面中点击 "批准"
#   - 检查您的仓库中是否保存了文件

Obsidian 配置选项

设置 描述 默认值
仓库 Obsidian 仓库的路径 自动检测
文件夹 仓库中用于存放计划的子文件夹 plannotator
自定义路径 如果自动检测失败，手动输入路径 –

保存的文件格式

文件以人类可读的名称和 YAML 前置元数据保存：

文件名：{标题} - {月} {日}, {年} {时}-{分}{上下午}.md
例如：用户认证 - 2月 22, 2026 10-45下午.md

---
created: 2026-02-22T22:45:30.000Z
source: plannotator
tags: [plannotator, project-name, typescript, ...]
---

[[Plannotator 计划]]

# 原始计划内容...

标签提取：

  • plannotator — 始终包含
  • 项目名称 — 来自 git 仓库或目录名
  • 标题中的词 — 从 H1 标题中取前 3 个有意义的词
  • 语言 — 来自代码块（```typescript → typescript）

文件夹组织

使用子文件夹在仓库中组织计划：

仓库/plannotator/
├── approved/          ← 已批准的计划
├── denied/            ← 被拒绝的计划
└── 2026-02/           ← 按月存档

手动创建子文件夹（Obsidian 会自动检测它们）：

mkdir -p ~/path/to/仓库/plannotator/approved
mkdir -p ~/path/to/仓库/plannotator/denied
mkdir -p ~/path/to/仓库/plannotator/2026-02

或直接写入任何子文件夹：

cp ~/.plannotator/plans/<名称>-approved.md ~/path/to/仓库/plannotator/approved/

Bear Notes（替代方案）

如果您更喜欢 Bear Notes 而非 Obsidian：

  1. 在设置 → 保存选项卡中打开 “Bear Notes” 开关
  2. 计划通过 bear://x-callback-url/create 保存
  3. 标签作为话题标签追加
  4. 从终端验证回调：
open "bear://x-callback-url/create?title=Plannotator%20Check&text=Bear%20callback%20OK"
功能 Obsidian Bear
存储方式 文件系统 x-callback-url
前置元数据 YAML 无（使用话题标签）
支持平台 macOS/Windows/Linux macOS/iOS

故障排除

仓库未检测到：

# 1. 检查 Obsidian 配置文件是否存在
ls ~/Library/Application\ Support/obsidian/obsidian.json  # macOS

# 2. 如果缺失，先打开 Obsidian 并创建一个仓库
open /Applications/Obsidian.app

# 3. 创建仓库后，重启 plannotator

计划未保存：

# 检查仓库文件夹的写入权限
ls -la ~/path/to/仓库/plannotator/

# 检查浏览器控制台是否有错误（F12 → 控制台）

导出 → 笔记选项卡的保存按钮需要钩子模式：

  • 导出 → 笔记选项卡的保存按钮要求 plannotator 在 钩子模式 下运行（stdin JSON 输入）。在 CLI review/annotate 模式下，/api/save-notes 端点未激活。正常的 Claude Code 钩子调用（ExitPlanMode 钩子）总是在钩子模式下运行。

设置在自动化/无头浏览器中不可见：

  • Obsidian 集成设置必须在 plannotator 自动打开的系统浏览器中配置。设置存储在 cookies 中（而不是 localStorage）。自动化/无头浏览器配置文件（Playwright, Puppeteer）使用隔离的 cookie 存储，不会看到这些设置。

Bear 导出不工作：

  • 确认 Bear 应用已安装并至少打开过一次
  • 确认 open "bear://x-callback-url/create?..." 能从终端工作
  • 为 plannotator 设置使用系统浏览器会话；自动化/无头会话可能会阻止自定义 URI 处理程序

设置未持久化：

  • 设置存储在 cookies 中（而不是 localStorage）
  • 确保为 localhost 启用了 cookies
  • 设置在不同端口间持续存在

自动保存（总结）

Obsidian 集成是可选的 — 计划仍然可以在没有它的情况下进行审查和批准。

最佳实践

  1. 在代理开始编码之前使用计划审查 — 及早发现错误方法
  2. 使每个注释都与一个具体、可操作的更改相关联
  3. 在 “请求更改” 反馈中包含验收标准
  4. 对于差异审查，注释与预期行为变化相关的确切行范围
  5. 对于文本不足的 UI/UX 反馈，使用图像注释

参考链接

📄 原始文档

完整文档（英文）：

https://skills.sh/supercent-io/skills-template/plannotator

💡 提示：点击上方链接查看 skills.sh 原始英文文档，方便对照翻译。

声明：本站所有文章，如无特殊说明或标注，均为本站原创发布。任何个人或组织，在未征得本站同意时，禁止复制、盗用、采集、发布本站内容到任何网站、书籍等各类媒体平台。如若本站内容侵犯了原著者的合法权益，可联系我们进行处理。