OpenCodeDocs

简体中文

English
繁體中文
日本語
한국어
Español
Français
Deutsch
Português
Русский

简体中文

English
繁體中文
日本語
한국어
Español
Français
Deutsch
Português
Русский

主题

快速开始：5分钟上手 Plannotator ​

学完你能做什么 ​

  • ✅ 了解 Plannotator 的核心功能和使用场景
  • ✅ 在 5 分钟内完成 Plannotator 安装
  • ✅ 配置 Claude Code 或 OpenCode 集成
  • ✅ 完成首次计划评审和代码评审

你现在的困境 ​

Plannotator 是一个为 Claude Code 和 OpenCode 设计的交互式评审工具，可以帮你解决以下问题：

痛点 1：AI 生成的实施计划在终端里阅读，文字量大、结构不清晰，评审起来很累。

痛点 2：想给 AI 反馈时，只能用文字描述"删除第3段"、"修改这个函数"，沟通成本高。

痛点 3：代码评审时，需要打开多个终端或 IDE，来回切换，难以集中注意力。

痛点 4：团队成员想参与评审，但不知道如何共享计划内容。

Plannotator 能帮你：

  • 可视化 UI 替代终端阅读，结构清晰
  • 选中文本即可添加注释（删除、替换、评论），精确反馈
  • Git diff 可视化评审，支持行级注释
  • URL 分享功能，无需后端即可团队协作

什么时候用这一招 ​

使用场景：

  • 使用 Claude Code 或 OpenCode 进行 AI 辅助开发
  • 需要评审 AI 生成的实施计划
  • 需要审查代码变更
  • 需要与团队成员共享计划或代码评审结果

不适用场景：

  • 纯手工编写代码（不涉及 AI 生成计划）
  • 已经有完整的代码审查流程（如 GitHub PR）
  • 不需要可视化评审工具

核心思路 ​

Plannotator 是什么 ​

Plannotator 是一个为 AI Coding Agent（Claude Code、OpenCode）设计的交互式评审工具，主要提供两大功能：

  1. 计划评审：可视化评审 AI 生成的实施计划，支持添加注释、批准或拒绝
  2. 代码评审：可视化评审 Git diff，支持行级注释和多种视图模式

工作原理 ​

┌─────────────────┐
│  AI Agent      │
│  (生成计划)    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Plannotator   │  ← 本地 HTTP 服务器
│  (可视化 UI)   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  浏览器        │
│  (用户评审)    │
└─────────────────┘

核心流程：

  1. AI Agent 完成计划或代码变更
  2. Plannotator 在本地启动 HTTP 服务器，打开浏览器
  3. 用户在浏览器中查看计划/代码，添加注释
  4. 用户批准或拒绝，Plannotator 将决策返回给 AI Agent
  5. AI Agent 根据反馈继续实施或修改

安全性 ​

所有数据本地处理，不会上传到云端：

  • 计划内容、代码 diff、注释都存储在你的本地机器
  • 本地 HTTP 服务器使用随机端口（或固定端口）
  • URL 分享功能通过压缩数据到 URL hash 中实现，无需后端

🎒 开始前的准备 ​

系统要求：

  • 操作系统：macOS / Linux / Windows / WSL
  • 运行时：Bun（安装脚本会自动处理）
  • AI 环境：Claude Code 2.1.7+ 或 OpenCode

安装方式选择：

  • 如果使用 Claude Code：需要安装 CLI + 插件
  • 如果使用 OpenCode：需要配置插件
  • 如果只做代码评审：只需安装 CLI

跟我做 ​

第 1 步：安装 Plannotator CLI ​

macOS / Linux / WSL：

bash
curl -fsSL https://plannotator.ai/install.sh | bash

Windows PowerShell：

powershell
irm https://plannotator.ai/install.ps1 | iex

Windows CMD：

cmd
curl -fsSL https://plannotator.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

你应该看到：安装脚本会自动下载 Plannotator CLI 并将其添加到系统路径中，并显示版本号（如 "plannotator v0.6.7 installed to ..."）。

安装脚本做了什么？

安装脚本会：

  1. 下载最新版本的 Plannotator CLI
  2. 添加到系统路径（PATH）
  3. 清理可能存在的旧版本
  4. 自动安装 /plannotator-review 命令（用于代码评审）

第 2 步：配置 Claude Code（可选） ​

如果你使用 Claude Code，需要安装插件。

在 Claude Code 中运行：

/plugin marketplace add backnotprop/plannotator
/plugin install plannotator@plannotator

重要：安装插件后，必须重启 Claude Code 才能让 hook 生效。

你应该看到：插件安装成功后，Claude Code 的插件列表中会出现 plannotator。

手动配置方式（可选）

如果你不想使用插件系统，可以手动配置 hook。详见 Claude Code 插件安装 章节。

第 3 步：配置 OpenCode（可选） ​

如果你使用 OpenCode，需要编辑 opencode.json 文件。

编辑 opencode.json：

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

重启 OpenCode。

你应该看到：重启后，OpenCode 会自动加载插件，submit_plan 工具将可用。

第 4 步：首次计划评审（Claude Code 示例） ​

触发条件：让 Claude Code 生成一个实施计划，并调用 ExitPlanMode。

示例对话：

用户：帮我写一个用户认证模块的实施计划

Claude：好的，这是实施计划：
1. 创建用户模型
2. 实现注册 API
3. 实现登录 API
...
（调用 ExitPlanMode）

你应该看到：

  1. 浏览器自动打开 Plannotator UI
  2. 显示 AI 生成的计划内容
  3. 可以选中计划文本，添加注释（删除、替换、评论）
  4. 底部有"Approve"和"Request Changes"按钮

操作：

  1. 浏览器查看计划
  2. 如果计划没问题，点击 Approve → AI 继续实施
  3. 如果需要修改，选中要改的文本，点击 Delete、Replace 或 Comment → 点击 Request Changes

你应该看到：点击后，浏览器会自动关闭，Claude Code 会收到你的决策并继续执行。

第 5 步：首次代码评审 ​

在项目目录中运行：

bash
/plannotator-review

你应该看到：

  1. 浏览器打开代码评审页面
  2. 显示 Git diff（默认是未提交的变更）
  3. 左侧是文件树，右侧是 diff viewer
  4. 点击行号可以选中代码范围，添加注释

操作：

  1. 在 diff viewer 中浏览代码变更
  2. 点击行号选择要评审的代码
  3. 在右侧面板添加注释（comment/suggestion/concern）
  4. 点击 Send Feedback 发送给 agent，或点击 LGTM 批准

你应该看到：点击 Send Feedback 后，浏览器会关闭，终端中会输出格式化的反馈内容，agent 会自动处理。

检查点 ✅ ​

完成以上步骤后，你应该能够：

  • [ ] 安装脚本显示 "plannotator vX.X.X installed to ..."
  • [ ] 在 Claude Code 中触发计划评审，浏览器自动打开 UI
  • [ ] 在 UI 中选中计划文本，添加注释
  • [ ] 点击 Approve 或 Request Changes，看到浏览器关闭
  • [ ] 运行 /plannotator-review，看到代码评审界面
  • [ ] 在代码评审中添加行级注释，点击 Send Feedback

如果某一步失败，详见：

踩坑提醒 ​

常见错误 1：安装后运行 plannotator 提示"command not found"

原因：PATH 环境变量未更新，或需要重启终端。

解决：

  • macOS/Linux：运行 source ~/.zshrc 或 source ~/.bashrc，或重启终端
  • Windows：重启 PowerShell 或 CMD

常见错误 2：Claude Code 安装插件后，计划评审没有触发

原因：未重启 Claude Code，hook 未生效。

解决：完全退出 Claude Code（不只是关闭窗口），然后重新打开。

常见错误 3：浏览器没有自动打开

原因：可能是远程模式（如 devcontainer、SSH），或者端口被占用。

解决：

  • 检查是否设置了 PLANNOTATOR_REMOTE=1 环境变量
  • 查看终端输出的 URL，手动在浏览器中打开
  • 详见 远程/Devcontainer 模式

常见错误 4：代码评审显示"No changes"

原因：当前没有未提交的 git 变更。

解决：

  • 先运行 git status 确认有变更
  • 或运行 git add 暂存一些文件
  • 或切换到其他 diff 类型（如 last commit）

本课小结 ​

Plannotator 是一个本地运行的评审工具，通过可视化 UI 提升计划评审和代码评审的效率：

核心功能：

  • 计划评审：可视化评审 AI 生成的计划，支持精确注释
  • 代码评审：可视化评审 Git diff，支持行级注释
  • URL 分享：无需后端即可分享评审内容
  • 第三方集成：自动保存批准的计划到 Obsidian/Bear

核心优势：

  • 本地运行，数据安全
  • 可视化 UI，提升效率
  • 精确反馈，减少沟通成本
  • 团队协作，无需账号系统

下一课预告 ​

下一课我们学习 Claude Code 插件安装。

你会学到：

  • 详细的 Claude Code 插件安装步骤
  • 手动配置 hook 的方法
  • 如何验证安装是否成功
  • 常见安装问题的解决方法

附录：源码参考 ​

点击展开查看源码位置

更新时间：2026-01-24

功能文件路径行号
CLI 入口（计划评审）apps/hook/server/index.ts1-50
CLI 入口（代码评审）apps/hook/server/index.ts46-84
计划评审服务器packages/server/index.ts1-200
代码评审服务器packages/server/review.ts1-150
Git 工具packages/server/git.ts1-100
计划评审 UIpackages/editor/App.tsx1-200
代码评审 UIpackages/review-editor/App.tsx1-200

关键常量：

  • MAX_RETRIES = 5：端口重试次数（packages/server/index.ts:80）
  • RETRY_DELAY_MS = 500：端口重试延迟（packages/server/index.ts:80）

关键函数：

  • startPlannotatorServer()：启动计划评审服务器（packages/server/index.ts）
  • startReviewServer()：启动代码评审服务器（packages/server/review.ts）
  • runGitDiff()：运行 git diff 命令（packages/server/git.ts）

环境变量：

  • PLANNOTATOR_REMOTE：远程模式标志（apps/hook/server/index.ts:17）
  • PLANNOTATOR_PORT：固定端口（apps/hook/server/index.ts:18）
  • PLANNOTATOR_BROWSER：自定义浏览器（apps/hook/README.md:79）
  • PLANNOTATOR_SHARE：URL 分享开关（apps/hook/server/index.ts:44）