Plannotator 配置完整清单:环境变量与 config.json 选项速查表

原创2026-10-11 21:41:321,619 阅读
文章标签:开发者工具代码评审AI 应用前端后端CLIAI 插件AI 技能MCP 服务dsh-plugin

Plannotator 配置完整清单:环境变量与 config.json 选项速查表

Plannotator 是一款本地浏览器里的 AI 编码代理审查工具:当 Claude Code、Codex、Gemini CLI、OpenCode 等代理提出计划(plan)或写完代码后,它会自动在浏览器中打开一个可视化界面,让你批注、评论,并一键把反馈送回给代理。要让 Plannotator 贴合自己的工作流,核心就靠两类配置:环境变量和 config.json(默认位于 ~/.plannotator/config.json)。本文整理了一份完整清单速查表,覆盖全部常用 PLANNOTATOR_* 环境变量与 config.json 字段,帮助你快速完成安装与定制。

Plannotator 品牌横幅:协作式计划批注与代码审查界面

三种配置方式与优先级规则

Plannotator 的配置入口有三个,同一选项通常"多处可设、按优先级生效":

配置方式 位置 典型场景
⌨️ 命令行参数 每次命令后附加,如 plannotator review --no-git-remote-check 一次性临时覆盖
🔧 环境变量 shell 中 export PLANNOTATOR_XXX=... 全局或某台机器固定生效
📄 config.json ~/.plannotator/config.json(可手动编辑) 持久化个人偏好

优先级一般是:命令行参数 > 环境变量 > config.json > 默认值。例如 Jina 的判定顺序就是 --no-jina 标志 → PLANNOTATOR_JINA 环境变量 → config.json 的 jina 字段 → 默认开启,逻辑见 packages/shared/config.ts。

💡 布尔型环境变量的通用约定:1 / true / on 表示开启,0 / false / off / disabled 表示关闭,留空则视为"未设置"。

配置读取与写入的实现都在 packages/shared/config.ts,数据目录的解析逻辑在 packages/shared/data-dir.ts。

Plannotator 代码审查界面:并排 diff、文件树与批注气泡

核心环境变量速查表(最高频)

下面这张表是日常使用中最常用的核心变量,完整说明可查官方文档 environment-variables.md。

变量 默认值 作用
PLANNOTATOR_REMOTE 自动检测 强制远程模式(1/true)或本地模式(0/false);SSH 下可自动识别
PLANNOTATOR_PORT 本地随机 / 远程 19432 固定服务端口,也支持 19432-19463 这样的端口范围
PLANNOTATOR_URL_HOST localhost 仅用于展示的域名(如 Tailscale 主机名),让远程链接可被其他设备访问
PLANNOTATOR_BROWSER 系统默认 指定打开 UI 的浏览器,接受应用名、可执行路径或自定义脚本
PLANNOTATOR_DATA_DIR ~/.plannotator 整个数据根目录(计划、历史、草稿、config.json 等全部在此)
PLANNOTATOR_AI 启用 设为 disabled 关闭 Ask AI、Review Agents 等 AI 功能
PLANNOTATOR_SHARE 启用 设为 disabled 隐藏全部分享入口,适合敏感计划
PLANNOTATOR_ALLOWED_HOSTS 未设置 额外允许访问会话的 Host 头,配合反向代理 / Docker 使用
PLANNOTATOR_ORGAN — — —
PLANNOTATOR_ORIGIN 自动检测 显式指定代理来源(claude-code、opencode、gemini-cli 等)
PLANNOTATOR_PLAN_TIMEOUT_SECONDS 345600 仅 OpenCode:submit_plan 等待超时(秒),0 表示不超时

远程模式三件套:PORT + URL_HOST + ALLOWED_HOSTS

当你通过 SSH、devcontainer 或 Docker 使用 Plannotator 时,推荐组合配置:

export PLANNOTATOR_REMOTE=1
export PLANNOTATOR_PORT=19432
export PLANNOTATOR_URL_HOST=your-machine.tailnet.ts.net

端口解析顺序为:① PLANNOTATOR_PORT → ② 远程模式的 19432 → ③ 本地模式的随机端口(remote.md)。指定端口范围时会从低到高逐个尝试,绑定第一个可用端口。

你的批注成为代理的指令:Annotate 到 Agent 的数据流示意

Claude Code 与代理工具相关变量

如果你主要使用 Claude Code / Pi / OpenCode 2,这四个变量决定代理能"看到"哪些工具:

变量 默认值 说明
PLANNOTATOR_CLAUDE_MOD 开 Claude Code 2.1.287+ 的非阻塞 mod(不等 Claude 等待的审查体验);设 0 回退经典 hook
PLANNOTATOR_AGENT_TOOL Claude Code 开 / Pi、OpenCode 2 关 是否给代理注册 plannotator 工具,让它主动打开 Plannotator
PLANNOTATOR_INBOX_TOOL 同上 控制 Inbox 的 plannotator_inbox 工具与回复唤醒
PLANNOTATOR_MOD_DEBUG 关 设 1 后 mod 会写调试日志到 ~/.plannotator/claude-code-mod/debug.log,报障时很有用

⚠️ 注意:AGENT_TOOL 与 INBOX_TOOL 只在会话启动时读取,修改后需要重启代理或新开会话才生效。两者也都支持 config.json("agentTool": false、"inboxTool": { "pi": true })。

高级功能开关与沙箱变量

变量 默认值 作用
PLANNOTATOR_GIT_REMOTE_CHECK 启用 关闭后本地 Git 审查不再执行 git ls-remote,适合 SSH 依赖硬件安全密钥的场景
PLANNOTATOR_CURSOR_SANDBOX 启用 关闭 Cursor Agent 的强制沙箱参数(NixOS 等系统需要)
PLANNOTATOR_CLAUDE_SANDBOX 启用 为审查任务单独关闭 Claude Code 沙箱(缺少 bubblewrap 的 Linux 需要)
PLANNOTATOR_JINA 启用 URL 批注是否走 Jina Reader;可配合 JINA_API_KEY 提升速率限制
PLANNOTATOR_GLIMPSE / _WIDTH / _HEIGHT 启用 / 1280 / 900 Glimpse 原生窗口开关与尺寸
PLANNOTATOR_FEEDBACK_HISTORY 启用 关闭后不再把提交记录归档到 ~/.plannotator/feedback/
PLANNOTATOR_ANNOTATE_HISTORY 启用 关闭后 annotate 会话完全无状态
PLANNOTATOR_REVIEW_PROGRESS 启用 关闭后"已查看"标记不再跨会话记忆
PLANNOTATOR_AUTO_UPDATE 关 允许二进制每天最多一次后台检查更新
PLANNOTATOR_TODO_PROVIDER auto Pi 专属:是否把批准的计划清单镜像到 pi-todos
PLANNOTATOR_READY_FILE / PLANNOTATOR_SKIP_BROWSER_OPEN — 宿主插件内部使用的旁路信号,一般无需手动设置

自建服务与 Bitbucket 相关变量

自托管分享门户、paste 服务或对接 Bitbucket PR 审查时使用:

变量 默认值 说明
PLANNOTATOR_SHARE_URL https://share.plannotator.ai 分享链接的根地址(自托管分享门户时修改)
PLANNOTATOR_GUIDE_SHARE_URL https://guides.show Guided Review 分享链接上传的主机
PLANNOTATOR_GUIDE_VIEWER_URL https://guides.show/v1/ 已下载的可移植 guide 所固定的查看器地址
PLANNOTATOR_PASTE_URL https://plannotator-paste.plannotator.workers.dev paste 服务 API 地址
PASTE_PORT / PASTE_DATA_DIR / PASTE_TTL_DAYS / PASTE_MAX_SIZE / PASTE_ALLOWED_ORIGINS 19433 / ~/.plannotator/pastes / 7 / 5MB / 见文档 自托管 paste 服务自身的运行参数
PLANNOTATOR_BITBUCKET_TOKEN 未设置 Atlassian API token(需 4 个 bitbucket 权限范围);也可写进 config.json 的 bitbucketToken(明文,不推荐)
PLANNOTATOR_BITBUCKET_EMAIL 未设置 提供 token 的账号邮箱;不提供则按 Bearer 方式发送
PLANNOTATOR_BITBUCKET_API_URL https://api.bitbucket.org/2.0 API 基址,用于本地假 API 测试或企业代理

安装脚本专用变量

以下变量只被安装脚本读取(scripts/install.sh、scripts/install.ps1、scripts/install.cmd),运行时不生效:

变量 作用
PLANNOTATOR_VERIFY_ATTESTATION 安装时用 gh attestation verify 校验二进制来源(需装 gh CLI)
PLANNOTATOR_MINIMAL 只装 plannotator 二进制,跳过 skills、hooks、slash 命令等一切附加物
PLANNOTATOR_SKIP_SEM_INSTALL 跳过可选的 sem 语义 diff sidecar
PLANNOTATOR_INSTALL_CALLDIFF 预装 CallDiff(调用流分析)核心运行时
PLANNOTATOR_CALLDIFF_PATH 开发用:指向本地已构建的 CallDiff
PLANNOTATOR_SKIP_CODEX_INSTALL / _GEMINI_ / _KIRO_ / _VIBE_ / _OPENCODE_ 分别跳过对应代理的集成写入(对应 config.json 的 skipInstall 字段)
PLANNOTATOR_SKIP_SKILLS_INSTALL 跳过全部 skills / slash 命令检出,此时不再强依赖 git
CLAUDE_CONFIG_DIR 自定义 Claude Code 配置目录,hook 将写入此处

config.json 完整字段速查表

手动编辑 ~/.plannotator/config.json 时的全部可选字段(类型定义见 packages/shared/config.ts 中的 PlannotatorConfig 接口):

字段 默认 说明
displayName — 自定义显示名(批注署名,默认为自动生成的 形容词-名词-tater)
diffOptions — diff 外观:diffStyle、overflow、lineDiffType、showLineNumbers、fontSize、defaultDiffType 等,类型定义见 packages/core/config-types.ts
reviewAnalysis 语义开 / 调用流关 semanticDiff、callFlow 两个审查分析层
theme — 主题:mode(light/dark/system)+ 明暗两套调色板
favicon totman totman 或 classic 两种图标风格
prompts 内置模板 自定义发给代理的批准 / 拒绝 / 批注反馈文案,支持按 runtime 覆盖
conventionalComments / conventionalLabels — 是否启用及自定义"约定式评论标签"(如 blocking 标签)
agentTerminalSide left annotate 模式代理终端停靠侧:left / right / hidden
agentTerminalDefaultAgent 第一个可用 annotate 终端预选的代理 id
jina true URL 批注走 Jina Reader
annotateHistory true 保存 annotate 版本历史(版本 diff 的来源)
feedbackHistory true 归档提交的审查记录到 feedback/
guideHistory true 持久化成功的 Guided Review 到 guides/
markdownExtensions 空 让 annotate 把额外扩展名(如 .livemd)当 markdown 处理
reviewProgress true 跨会话记忆"已查看"文件
autoUpdate false 后台自动更新开关
claudeCodeMod true Claude Code mod 总开关
agentTool / inboxTool 按宿主 代理工具 / Inbox 工具开关,inboxTool 支持按宿主分别配置
inboxNotifications — Inbox 浏览器通知的 enabled / dismissed / allowedOrigin
inboxPhones false 手机端 Inbox 开关(面向 iPhone 应用开发)
pfmReminder false 每次 EnterPlanMode 注入 PFM 扩展提醒
glimpse true Glimpse 原生窗口开关
share enabled "disabled" 可关闭全部分享 UI
guideShareUrl — 自托管 guide 主机地址
bitbucketToken / bitbucketEmail — Bitbucket 凭据(token 为明文,优先用环境变量)
cursorSandbox / claudeSandbox true 审查任务的沙箱策略
gitRemoteCheck true 审查时是否查询 git 远程
urlHost — 同 PLANNOTATOR_URL_HOST 的持久化版本
todoProvider auto auto / off
skipInstall 全关 { "codex": true, "gemini": true, ... } 安装跳过清单
verifyAttestation false 安装时校验二进制 attestation

一个最小示例:

{
  "claudeCodeMod": false,
  "share": "disabled",
  "autoUpdate": true,
  "diffOptions": { "diffStyle": "split", "showLineNumbers": true },
  "theme": { "mode": "system" }
}

Plannotator 代码审查演示:在 diff 上批注并把反馈发回给代理

快速上手:3 条最常用的配置

1️⃣ SSH 远程开发:export PLANNOTATOR_REMOTE=1 + 端口转发,链接自动变为固定端口。

2️⃣ 敏感项目禁用分享:export PLANNOTATOR_SHARE=disabled(或 config.json 写 "share": "disabled"),Share 标签页、复制链接、导入审查全部隐藏。

3️⃣ 彻底无状态审查:同时设置 PLANNOTATOR_ANNOTATE_HISTORY=0 与 PLANNOTATOR_FEEDBACK_HISTORY=0,Plannotator 不再向磁盘写入任何历史记录。

常见疑问 FAQ

Q1:改了 config.json 要重启吗? 大多数字段(主题、diff 选项、沙箱开关等)在下一个会话启动时生效;agentTool、inboxTool 类字段只在会话开始读取一次,改完请新开会话或重启代理。

Q2:环境变量和 config.json 冲突听谁的? 环境变量优先。例外是 CLI 参数(如 --no-git-remote-check、--browser),它们永远赢。

Q3:数据目录可以搬走吗? 可以,设置 PLANNOTATOR_DATA_DIR=/some/path 即可整体迁移(含 config.json);未设置时已存在的 ~/.plannotator 永远优先于 XDG_DATA_HOME。

Q4:完整文档在哪看? 环境变量全表:environment-variables.md;配置总览:configuration.md;界面内设置说明:ui-settings.md;代码实现:packages/shared/config.ts。

掌握这份速查表后,你可以在一分钟之内把 Plannotator 配置成最贴合自己团队的工作模式——剩下的,就交给代理们慢慢改吧 🚀

登录后查看全文
plannotator