终端与编辑器 on 扎塔-Zata

VelaTerm 深度调研：把 iTerm2 和 Codex 装进同一个窗口的 ADE

Wed, 30 Sep 2026 20:00:00 +0800

如果你同时跑着几个 Claude Code、Codex，标签页早就堆成了一排乱码，分不清哪个 Agent 在干活、哪个在等你批准——VelaTerm 就是冲这个场景来的。

它的官方公式很简单：VelaTerm = iTerm2 + Codex。像 Codex 一样管理智能体会话，像 iTerm2 一样分屏使用终端，两者放进同一个原生应用，还能推到浏览器和手机上继续用。它给自己起的名字是 ADE（Agent Development Environment）——“不只是终端，也不只是 IDE”。

需要先声明：本文是一轮基于公开资料的深度调研（官网、GitHub 仓库、Release notes、第三方评测，检索时间 2026-09-30），不是像之前 Herdr 那篇那样的本机实测。所有功能描述以官方文档为准，未经我亲手验证的地方会在行文中说明。

一、项目档案

项目	内容
定位	多智能体开发环境（ADE）：终端 + 编程 Agent 会话管理
官网	velaterm.com
仓库	github.com/vlinx-io/VelaTerm（TypeScript 为主）
出品方	VLINX Software
许可证	MIT（2026-08-11 公开源码，仓库创建于 2026-08-09）
最新版本	v0.2.6（2026-09-30 发布，就是今天）
GitHub 数据	⭐ 240 · fork 27 · open issues 66（2026-09-30 查询）
平台	macOS（Apple Silicon/Intel）、Windows（x64/arm64）、Linux（x86_64/aarch64）
Shell	macOS zsh；Windows PowerShell / Git Bash（完整版内置）/ WSL；Linux bash
价格	免费，MIT 开源，无付费层

几个第三方渠道的补充信息：myaiexp 和 HuntScreens 都把它归入"多代理开发环境"类目；Honeystax 在 2026 年 8 月中给出的评估是"GitHub 健康 57/100、无安全策略、当时 8 个 open issues、风险 42/100"——两个月后的今天 issues 涨到了 66 个，项目迭代极快（见第六节），但治理配套还没跟上。

二、它到底是什么：一个窗口里的三层东西

理解 VelaTerm 最快的方式，是把它的窗口拆成三层看：

底层：真实终端。 每个会话都是一个真实 PTY，切走之后进程继续在后台跑。支持递归分屏（任意面板向右/向下拆，嵌套无深度限制）、命令与路径补全、vopen 把文件打开成标签页（带语法高亮、Markdown 渲染、图片查看）。
中间层：Agent 会话。 九种编程 Agent 作为"一等会话"运行——Claude Code、Codex、OpenCode、Copilot、Cursor、Antigravity、Cline、Pi 等。每个 Agent 有实时状态（working / pending / ready 等）、支持会话恢复和自定义启动参数。
顶层：协作与组织。 项目 → 分组 → 嵌套子分组 → 会话的树形结构，配搜索、重命名、归档；Agent 之间可以互相搜索对话、发消息、派生子和任务拆分（这是它和普通终端的分水岭，第四节细讲）。

同一个 Agent 会话有两种视图：会话视图把 Agent 的计划、改动、命令、测试结果渲染成一条对话流；切到终端视图就直接操作 Agent 自己的 TUI。这个"对话/终端双视图"是它区别于 tmux 系工具的一个显性特征。

另外两个日常顺手的点：

信息面板：Agent 干活时，右栏实时显示订阅额度（plan quota）、上下文占用、Token 用量和系统负载——额度还剩多少不用去服务商后台查。
通知系统：会话状态变化走树中的脉冲点、状态栏计数器和桌面通知三路，Agent 卡住等输入时不用逐个窗口巡检。

三、功能全景速览

按官方 README 的板块整理：

板块	能力
终端	真实 PTY、递归分屏、命令/路径建议（Tab 补全）、后台持久化
Agent 会话	九种 Agent 一等会话、实时状态、恢复、自定义启动参数
会话组织	项目/分组/嵌套子分组/会话的无限层级树、搜索、归档
视图	会话视图（对话流）⇄ 终端视图（原生 TUI）随时切换
内置编辑器	WYSIWYG Markdown 编辑器、代码编辑器、图片查看器；桌面端还有内置浏览器
Git 集成	每会话显示分支、领先/落后提交数、改动量
代码审计	内置 Codex Security 工作流，用本机已登录的 Codex 或 Claude Code 跑全仓库/目录/工作树审计，可导出 Markdown/JSON 报告（实验性）
知识库	会话知识库 + 本地 Markdown 笔记库，统一搜索；Agent 可用 `vkb` 查询
远程	SSH 连接、HTTPS 端到端加密浏览器访问、iOS/Android 原生 App（官方标注 coming soon）
其他	亮暗主题跟随系统、界面多语言完整翻译、游戏中心（Pixel Wing，键鼠/触控/手柄皆可）

游戏中心这种东西出现在"开发工具"里多少有点彩蛋性质，但也说明团队的定位是"开发者长时间待着的工作空间"，而不只是一个终端模拟器。

四、重头戏：多智能体协作

这是 VelaTerm 与"带分屏的终端"真正拉开差距的部分，也是它敢自称 ADE 的底气。四组能力：

4.1 `vspawn`：一条命令派生子会话

Agent 在干活途中可以把旁支任务交给一个子会话：选 Agent、选模型、选推理强度，需要隔离就给它分配独立 worktree。子会话出现在父会话下方，进度在树里直接可见——本质上是把"多 Agent 编排"从脚本层面搬进了会话树。

4.2 跨会话通信：`vsearch` / `vrefer` / `vtell`

不同 Agent 的会话之间（Claude、Codex、OpenCode、Pi 等）可以互相查：

命令	作用
`vsearch`	搜索所有会话的对话内容
`vrefer`	读取某段对话，或直接就它提问
`vtell`	给其他会话发消息；加 `--steer` 可插入对方正在进行的回合

想象一个典型场景：Claude 会话在改认证代码，可以 vsearch 找到之前某个 Codex 会话讨论过的数据库约定，vrefer 向它追问细节，再 vtell 通知另一个会话配合调整——Agent 之间的上下文不再靠人复制粘贴搬运。

4.3 Plan / Execute：一个大任务，一组会话

规划/执行模式把大任务拆给多个会话协作，流程分三步：

规划：规划会话（planner）制定方案、拆分任务；规划与执行可分别配置 Agent、模型和推理强度。
执行：vflow 提出拆分方案，你逐项调整并确认后才开始执行；每个执行会话（executor）在独立 worktree 里并行做一件事，作为规划会话的子会话显示在树中。
验收：vtell --report 把执行结果回传给规划会话逐项验收，未达标的任务退回原执行会话返工，上下文完整保留。

值得注意的是设计取舍：拆分方案需要人工审批，不是全自动发车；worktree 可以每个会话独立、也可以全员共享同一棵。这比"一键 Agent 军团"类产品保守，但在真实项目里更容易控制爆炸半径。

4.4 `vkb`：会话里的结论沉淀成知识

vkb memories — 查会话知识库（把有价值的会话整理进条目，附带来源）
vkb notes — 查本地 Markdown 笔记库（带标签、收藏、回收站）
vkb explore — 查代码图谱，在本机完成、不调用 AI 模型

三者统一搜索。等于给 Agent 配了一个"动手前先查档案"的入口，也让散落在历史会话里的结论可以复用。

五、远程与移动：三种接管方式

远程是 VelaTerm 宣传里占比很大的一块：

方式	说明
SSH	应用内直连远程机器，连接前确认主机指纹
浏览器	一键开启 HTTPS 服务，端到端加密，任意设备打开 URL 就是完整桌面 UI，无需安装
手机	iOS / Android 原生 App，扫码配对、推送通知、直接回复 Agent；官网标注"coming very soon"

还有账号化的配对链接和设备列表管理；v0.2.0 起支持共享项目/会话——通过出站隧道把宿主的真实界面转发到共享 URL，权限限定在被授权的项目或会话范围内。

对"在服务器上跑长任务、地铁上用手机瞄一眼进度、顺手批准一个操作"这种工作流，这条链路是完整的。端到端加密这一点官方反复强调（“传输链路上没有可读的明文”），显然是在回应"把终端搬到浏览器"必然引发的安全疑虑。

六、技术架构与版本节奏

6.1 技术栈

层级	选型
桌面外壳	Tauri 2（Rust 后端 + 系统 WebView）；另有一个 Electron 外壳并存（`electron/` 目录）
PTY	`portable-pty`（来自 wezterm）
前端	React 19 + TypeScript + Vite
终端渲染	xterm.js（fit / web-links / search / image / unicode11 插件）
状态管理	Zustand
持久化	SQLite（rusqlite，内置编译）
样式	Tailwind v4，主题基于 CSS 变量

选 Tauri 2 而不是 Electron 做主壳，换来的是"安装包仅数 MB、不捆绑 Chromium、启动快、多终端并发依然流畅"（官方口径；第三方介绍一致）。它解决的痛点很实际——这类会话管理器如果自己就是内存大户，跑十几个 Agent 会话就先把自己压垮了。

6.2 版本节奏：快得不正常

2026-08-09 仓库创建，08-11 公开源码
v0.1.x 一路迭代到 108+
v0.2.0（9 月中）：远程访问成体系（SSH/URL/指纹确认/扫码/账号登录）、实验性代码审计、本地知识库、Plan-and-Execute 会话
v0.2.2（09-15）：用量限额后自动续跑（Claude/Codex 5 小时/周限额重置后自动恢复，默认关）、Windows 一键安装 OpenCode/Grok/Crush、会话知识库归档与全文搜索
v0.2.3（09-24）→ v0.2.4（09-26）→ v0.2.5（09-28）→ v0.2.6（09-30）：差不多两天一个版本

v0.2.6 重点是远程连接体验（指纹确认、配对链接、账号设备选择）和对话视图分页加载。这个发版密度在个人/小团队开源项目里属于第一梯队——好处是反馈闭环极快，坏处是每两天升一次级，用户跟不上，文档也容易滞后于代码。

七、成熟度与风险，说清楚

调研不能只报喜。汇总几条需要注意的点：

项目非常年轻。 开源至今不到两个月，还处在 0.2.x 阶段，API、数据格式、行为都可能有破坏性变化。
社区规模尚小。 240 star（截至 2026-09-30）说明还在早期采用阶段；66 个 open issues 相对这个体量不算少。
治理配套缺位。 Honeystax 8 月的评估提到仓库没有 security policy；远程访问涉及"把终端界面推到网络上"这种高危场景，安全响应机制的重要性远高于普通终端工具。虽然端到端加密的设计方向是对的，但"无安全策略"和"快节奏发版"组合在一起，建议不要把远程访问端口直接暴露到公网，至少先放在可信局域网/VPN 内。
本文未经实测。 所有功能描述来自官方材料，“九种 Agent 一等会话"“端到端加密"这些关键声明的实际成色，要以你自己的试用为准。
手机 App 还在路上。 官网标注 coming soon，现在移动端走浏览器布局（自动重排为触控 UI）。

八、竞品对比

这个赛道今年明显热起来了，各家切入点不同：

工具	形态	切入点	和 VelaTerm 的差异
VelaTerm	原生 GUI 应用（Tauri 2）	ADE：会话树 + 双视图 + 跨会话协作 + 远程/移动	唯一同时做到"GUI 会话树 + 内置协作命令 + 浏览器/手机接管"的
Herdr（本站有实测长文）	Rust 单二进制 TUI	tmux 的 Agent 化改造：语义状态 + socket 控制平面 + 插件体系	无 GUI、无内置浏览器/编辑器；但 API 面更完整、状态语义更严谨，适合活在终端里的人
tmux / Warp	传统终端	tmux 是会话持久化原语；Warp 是现代化终端	不感知 Agent 状态，协作要自己拼
Emdash	桌面应用	用 Git worktree 隔离并行 Agent	偏"并行实验场”，无终端分屏和远程接管
cmux	macOS 终端	Ghostty 基座 + 垂直标签 + Agent 通知	macOS 独占，功能面窄
Superset / Herdr 类 runtime	CLI	在隔离 worktree 里批量养 Agent	面向脚本化/无人值守场景

一句话选型：

要图形界面、会话树、手机上看进度 → VelaTerm 是当前完成度最高的选择
要严谨的 Agent 状态语义和可编程控制平面、且愿意住在终端里 → Herdr
只是想要会话不丢 → tmux 依然是答案

九、适合谁

适合：

同时跑多个编程 Agent，标签页已经管理不动的人
想让 Agent 之间互相查资料、发消息、拆任务，而不是自己当传话筒的人
需要在服务器跑长任务、随时用浏览器/手机接管的人
Windows 用户注意：这是少数把 Windows 当一等公民对待的同类项目（内置 Git Bash、x64/arm64 双架构、安装器处理了 npm wrapper 这类 Windows 特有坑）

不适合 / 再等等：

追求生产环境稳定性、受不了两天一个版本的人
需要完整插件生态的人（Herdr 的插件市场更成熟）
对"终端数据上网络"零容忍、又不打算细看安全配置的人
纯终端原教旨主义者——你会更想要 Herdr 或干脆 tmux

参考

velaterm.com —— 官网与用户手册（下载、入门指南、AI 智能体会话、远程开发、更新日志）
github.com/vlinx-io/VelaTerm —— 源码（MIT），README 有中文版与技术栈说明
Releases —— v0.1.x → v0.2.6 完整变更记录
myaiexp：VelaTerm / HuntScreens：VelaTerm —— 第三方产品收录与功能摘要
Honeystax：VelaTerm —— 仓库健康度评估（2026-08-15 快照）
本站关联阅读：Herdr 详解：给 AI Agent 用的终端运行时 —— 同赛道另一条路线的本机实测

信息时效：本文数据检索于 2026-09-30（GitHub 数据、版本号均为此日快照）。项目迭代极快，阅读时请以官网与仓库的最新状态为准。

Herdr 详解：给 AI Agent 用的终端运行时

Tue, 15 Sep 2026 10:30:00 +0800

如果你同时开着三个 Claude Code、两个 Codex，再挂一台远程机器的构建任务，你大概经历过这几件事：某个 Agent 早就停下来等你批准命令，你却在另一个标签页里刷了两分钟；SSH 断了一下，跑了一半的活没了；想知道"现在到底哪个窗口在干活"，只能一个个切过去看。

Herdr 就是冲这些事来的。它的官方定位是"The runtime your coding agents live on"——不是替代 Agent，而是给 Agent 提供它们运行于其中的那层终端基础设施。用一句话概括：Herdr 是把 tmux 按 Agent 的工作方式重新设计了一遍。

这篇文章基于我本机装的 herdr 0.9.0（stable 通道，protocol 22），把它的用法、概念模型和配置讲清楚，命令和输出都是实际跑出来的。（9 月 15 日补充：右键转发、复制模式、会话恢复的全景、插件从装到写、手机用法、中文输入法开关。同日二次补充：9.6.7 装了一个真插件的完整实录。）

一、它到底是什么，和 tmux 差在哪

Herdr 是 tmux 一脉的 后台 server + 前端 client 架构：client 只是一个"显示器 + 键盘"，真正的 pty、进程、布局都在 server 里。但它在几个地方做了明确的 Agent 化改造：

维度	tmux	Herdr
基本目的	保住终端会话	托管 AI Agent 的工作区
组织单位	session → window → pane	workspace → tab → pane
状态感知	无，pane 里有什么全靠肉眼看	每个 pane 有语义状态：`working` / `blocked` / `done` / `idle`
总览	逐个 window 切	侧边栏跨所有 workspace 汇总 Agent 列表
控制接口	`tmux` 命令	CLI + 本地 socket JSON API，给 Agent 用的
多机	要自己拼 ssh	`--remote` / 已保存机器，本地与远程同一视图
鼠标	基本可用	一等公民，点击/拖拽/右键菜单全能

原话是"不包装、不替换 Agent，只接管它们的终端"。所以 Claude Code、Codex、Cursor、OpenCode、Grok 这些还是原来那些，只是被放进了 Herdr 管理的工作区里——Herdr 能识别它们、给它们状态打标、允许它们互相说话。

技术上是 Rust 单二进制，没有 Electron，终端后端用 libghostty（Ghostty 的终端库），Windows 走 ConPTY。装完就是一个约等于 tmux 的东西，但多了 Agent 那一层。

想先看动起来是什么样，官方 README 里有一段二十来秒的演示（视频直链）：多个 Agent 在分屏里并行跑，侧边栏实时显示谁 blocked、谁 idle、谁 done，鼠标点着切窗格。下文用到的几张截图就是从这段演示和官方文档里取的。

二、安装与第一次启动

# 首选
brew install herdr
# 或官方脚本
curl -fsSL https://herdr.dev/install.sh | sh
# 或 mise
mise use -g herdr

Windows 现在也已 GA：一行 PowerShell 装上（powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"），企业安全软件拦无文件脚本时改用 install.cmd 版本，Windows ARM64 跑 x86_64 构建（模拟）。官方维护了一份已知限制清单，不长，装前值得看一眼。补全脚本支持 bash / zsh / fish / elvish / powershell：herdr completion zsh。

升级要注意安装来源：直接安装的用 herdr update；Homebrew、mise、Nix 装的用各自的包管理器（herdr update 对它们不生效）。直接安装还能切更新通道——herdr channel set preview 跟进 master 的预发布版（可能回归），herdr channel set stable 切回，包管理器安装不支持预览通道。

装完在任意项目目录里敲：

cd ~/code/ZataTree
herdr

它启动或连接默认后台会话，不需要你去管 socket 在哪。第一次会走一个 onboarding（也可以 onboarding = false 跳过）。如果一个 workspace 都没有，它会自动开一个。

我本机的实际状态：

$ herdr --version
herdr 0.9.0

$ herdr status
client:
 version: 0.9.0
 channel: stable
 protocol: 22
 endpoint_protocol_generation: 1

server:
 status: running
 version: 0.9.0
 endpoint_compatible: yes
 private_protocol: 22
 private_protocol_compatible: yes
 socket: /Users/zata/.config/herdr/herdr.sock

update:
 restart_needed: no
 server_binary_stale: no

注意这一行：server 是 running，而 client 是我每次敲 herdr 才起的。这是理解 Herdr 的第一把钥匙——server 活着，你的活就活着。

三、概念模型：workspace / tab / pane / agent

比 tmux 多了一层"工作区"，而且这层是按项目切而不是按窗口切：

workspace — 项目级容器，对应一个仓库/一个项目。侧边栏按 workspace 分组。
tab — workspace 内的标签页。
pane — tab 内可分割的终端格子，每个格子通常跑一个 Agent。
agent — Herdr 从 pane 里检测出来的编程 Agent 进程，是关注对象而不是容器。

prefix+w 或侧边栏的 switch 面板把这三层同时摊开，是这个模型最直观的一屏——左侧边栏分 spaces / tabs / agents 三段，Agent 名字下面是它的状态：

我本机现在的样子（--json 输出是我删掉无关字段后的样子）：

$ herdr workspace list
{"result":{"workspaces":[
 {"workspace_id":"w4","label":"freshai","number":1,"pane_count":2,"tab_count":1},
 {"workspace_id":"w6","label":"zata_code_template","number":2,"pane_count":1,"tab_count":1}
],"type":"workspace_list"}}

$ herdr pane list
{"result":{"panes":[
 {"pane_id":"w4:p1","workspace_id":"w4","cwd":"/Users/zata/code/freshai",
 "terminal_title":"⠸ Complete external skill change review task in worktree","agent_status":"unknown"},
 {"pane_id":"w4:p3","workspace_id":"w4","cwd":"/Users/zata/code/ZataTree",
 "terminal_title":"⠧ 询问 herdr 相关信息","agent_status":"unknown"},
 {"pane_id":"w6:p1","workspace_id":"w6","cwd":"/Users/zata/code/zata_code_template",
 "terminal_title":"✳ Greeting and session start","agent_status":"unknown"}
],"type":"pane_list"}}

pane ID 的格式是 w4:p1——workspace 短 ID 加 pane 短 ID，稳定且可引用。所有跨 pane 的命令都用它寻址。Agent 列表现在是空的，因为我当前这几个 pane 里跑的不是被识别的 Agent（原因见第八节）。

一个实践建议：每个活跃项目给一个独立 workspace。侧边栏的 Agent 汇总只有在 workspace 边界清晰时才读得懂，否则所有项目的 Agent 混成一堆，“哪个项目在等我"又变成一个需要推理的问题。

四、核心能力一：分离而不停止

这是第一个真正让你离不开它的功能。

# 分离（客户端退出，server 和 Agent 继续跑）
prefix + q

# 回来
herdr

也可以直接关掉终端窗口——效果一样。想真正结束会话和里面的 pane：

herdr server stop

Herdr 在这一点上比 tmux 多走了一步：重启恢复。server 重启后，它会恢复保存的布局，并且对装了官方集成、上报过原生 session 引用的 Agent，尝试恢复到原来的对话（[session] resume_agents_on_restore = true，默认开）。

但这里有个必须说清楚的边界：恢复的是 Agent 的原生会话，不是原始进程。你的 shell 里跑到一半的 npm run build 不会自己接着跑，别指望这个。Herdr 官方在文档里也写得很直白。

把"恢复"拆成四个问题，答案才清楚。 进程还在吗、布局回来吗、屏幕内容回来吗、对话能续上吗——官方文档就是这么拆的，我把它那张表放在这里：

情形	进程继续跑	布局	最近屏幕内容	Agent 对话
分离再附着	是	是	是（活的终端）	是（进程从没停）
server 重启	否	是	仅在开了屏幕历史回放时	仅在装了原生会话恢复时
`herdr update`（不带 `--handoff`）	兼容的 server 继续跑	重启后回来	仅在开了屏幕历史回放时	仅在装了原生会话恢复时
`herdr update --handoff`	尽力保留	是	是（交接成功时来自活终端）	是（同上）

两个默认不启用、但值得知道的能力：

屏幕历史回放：[experimental] pane_history = true，让 server 全量重启后也能把每个 pane 最近的屏幕内容铺回去。默认关的原因很正当——pane 输出里可能有 token、密钥和敏感提示词，开了就要像对待终端历史一样对待它（内容落在会话目录的 session-history.json）。
live handoff（热交接）：升级时把活着的 pane 连同进程一起从旧 server 交到新 server，跳过"停掉再重建”。命令是 herdr update --handoff，herdr --remote workbox --handoff 也能用它换掉远端的 server。实验性、需要显式开，而且包管理器安装用不了（升级走 brew/mise/nix）。边界也要说清楚：交接那一刻，在途的 CLI 请求、agent wait、事件订阅都会断，客户端要自己重连重试。

顺带一提命名会话，多环境隔离时很有用：

herdr --session work # 用或建一个命名会话
herdr session list # 列出
herdr session attach work # 附着
herdr session stop work # 停掉

socket 落在 ~/.config/herdr/sessions/<name>/herdr.sock，默认会话则是 ~/.config/herdr/herdr.sock。

五、核心能力二：状态可见——`working` / `blocked` / `done` / `idle`

Herdr 最有价值的一点是把 Agent 的状态变成了有语义的东西，而不是让你去读屏幕。

每个 pane 有一个状态，四种取值：

状态	含义	你该做什么
`working`	Agent 正在干活	别打扰
`blocked`	卡住了，等你输入/批准	切过去处理
`done`	这一轮任务完成	验收
`idle`	空着，等新指令	可以派活
`unknown`	没有检测到/上报状态	需要装集成，见第八节

侧边栏把所有 workspace 的 Agent 汇总成一个列表，默认按 workspace 分组（ui.agent_panel_sort = "spaces"），也可以切成 priority——按"谁在等我"排队的注意力队列。我认为 priority 在 Agent 多了之后更实用：它本质是一个待办队列。

状态还会沿层级向上汇总：一个 blocked 的 Agent 会让它所在的 pane、tab、workspace 都显示成 blocked；working 会让 workspace 显示活跃；done 会一直挂着，直到你真的看过它。所以侧边栏能当"哪个项目在等我"的单一入口——不是靠人记住，而是靠这条汇总规则替你维护。

状态指示符默认是彩色圆点，可以换成形状区分：

[ui]
status_indicators = "symbols" # 用不同字形区分 blocked/working/done/idle/unknown

下面这张是同一个 Agent 在 working 状态下的实拍——标题栏的 tab 1/1、顶部的工作区名 nav-keybinds、底部的 Working... 都是 Herdr 自己画的：

再加上通知：

[ui.toast]
delivery = "herdr" # herdr(应用内) | terminal(外层终端，SSH 场景好用) | system(系统通知) | off
delay_seconds = 1

[ui.toast.herdr]
position = "bottom-right"

[ui.sound]
enabled = true
# done_path = "sounds/done.mp3" # 任务完成音
# request_path = "sounds/request.mp3" # 需要你介入的音

阻塞和完成用不同的声音，这是我配完之后最满意的一条改动——不用看屏幕，光靠耳朵就知道是"干完了"还是"卡住了要我批准"。macOS 上 delivery = "system" 会先试 terminal-notifier，没有则退回 osascript（注意会显示成 Script Editor，且无法激活终端）；要 brew install terminal-notifier 才有完整体验。

Herdr 会抑制当前活跃 tab 的弹窗——你正盯着那个 pane 看，它不会弹一个框告诉你它 blocked 了。这个细节做对了。

六、用法：鼠标是默认，键盘是可选

Herdr 的入门门槛比 tmux 低，核心原因是它把鼠标做成了默认路径，前缀键只是另一条路。

鼠标：

点击 pane / tab / workspace / agent 行 → 聚焦
拖动分割边框 → 调整大小
右键 → 上下文菜单（包含分割窗格、新建标签页）
拖选文本即复制，双击一个词即复制该词——不需要 Ctrl+C
Ctrl+点击打开链接（OSC 8 超链接和可见的 http(s):// URL）。macOS 下鼠标捕获开着时要 Ctrl+点，Cmd+点需要终端原生绕过路径；也可以用 ui.mouse_capture = false 整体让出鼠标

右键的归属是可以调的。 默认右键是 Herdr 的窗格菜单，但 pane 里跑着 Claude Code、Neovim 这类开了鼠标上报的程序时，右键本来是它们的功能——Herdr 曾经统统一口吃掉，后来专门修过（issue #25）。现在这个归属是按 pane 单独选的：

右键窗格 → 菜单里的 “Send right-clicks to pane” 一键切过去；切过去之后再开菜单，这一项会变成 “Use Herdr right-click menu”，点它切回。
CLI 等价物：herdr pane input --current --right-click pane|herdr（要在目标 pane 里执行；从别处操作就换成 --pane w1:p2）。herdr pane split 也接受 --right-click pane，分割时一次定好。
socket 层是 pane.input.set，参数 right_click: "pane"。

注意它和 ui.mouse_capture = false 不是一回事：那个是把整个鼠标都让给 pane 里的应用，这个只让右键，其余交互仍归 Herdr。

不想逐个 pane 切的话，还有全局的修饰键混合模式：

[ui]
right_click_passthrough_modifier = "ctrl" # ctrl+右键转发给应用，普通右键仍开 Herdr 菜单

接受 ctrl / alt / cmd / meta / hyper，可以组合（不能带 shift）。

最后是必须提前知道的坑：右键转发出去之后，Herdr 菜单要靠右键窗格的边框唤回。不知道这一条的人，会在 pane 里反复右键、以为菜单坏了。

键盘： 前缀键默认 ctrl+b，和 tmux 一致，所以从 tmux 迁过来基本零成本。按下 ctrl+b 进入前缀模式，再按动作键。

动作	默认绑定
向右分割窗格	`prefix+v`
向下分割窗格	`prefix+minus`
新建标签页	`prefix+c`
下一个 / 上一个标签页	`prefix+n` / `prefix+p`
切到第 N 个标签页	`prefix+1..9`
重命名标签页	`prefix+shift+t`
工作区选择器	`prefix+w`
新建工作区	`prefix+shift+n`
重命名工作区	`prefix+shift+w`
方向聚焦（vim 式）	`prefix+h/j/k/l`
窗格循环切换	`prefix+tab` / `prefix+shift+tab`
关闭窗格	`prefix+x`
缩放窗格	`prefix+z`
重命名窗格	`prefix+shift+p`
侧边栏开关	`prefix+b`
分离客户端	`prefix+q`
进入复制模式（键盘复制）	`prefix+[`
查看当前全部有效绑定	`prefix+?`

复制模式。 鼠标拖选即复制之外，prefix+[ 提供一条完整的键盘路径——没有鼠标的 SSH 场景里，这是唯一的复制方式：

移动：h/j/k/l；tmux 风格的单词 w/b/e、大字词 W/B/E（按空白分词）；{/} 段落；PageUp/PageDown 翻页、ctrl+u/ctrl+d 半页。
搜索：/ 向前、? 向后，n/N 顺逆序重复。查询里没有大写字母就不区分大小写，想精确匹配就带上一个大写。
选择与复制：v 或空格开始选择（shift+v 是整行选择），y 或回车复制，q/Esc 放弃退出。Esc 会先清掉当前的选择或搜索，再按一次才退出。
复制模式不暂停进程：输出照常产生、视图跟在底部；你滚进历史时画面钉住不动。

两个容易错过的点：默认前缀就是 ctrl+b，所以在复制模式里 ctrl+b 仍然是"前缀"、不是翻页，想用它翻页得先换前缀；另外 prefix+e 能把回滚内容直接在 $EDITOR 里打开，软折行会还原成逻辑行——审一段长日志，比在终端里滚舒服得多。

给终端起个看得懂的名字。 默认窗格标题显示的是运行中程序动态设置的 terminal title——比如 Claude Code 会把它改成当前正在做的事，还带转圈动画，一直变，根本认不出哪个窗格是哪个。三级对象都能改名：prefix+shift+p（窗格）、prefix+shift+t（标签页）、prefix+shift+w（工作区），按下后弹输入框，起个名，侧边栏和窗格边框从此显示固定名字。CLI 也能改，适合脚本或远程操作：

herdr pane rename w4:p3 "zata blog" # 给指定 pane 起固定名字
herdr pane rename w4:p3 --clear # 清掉，退回动态标题

再配一条：窗格没有手动命名时，在分割边框上显示检测到的 Agent 标签：

[ui]
show_agent_labels_on_pane_borders = true

两个容易忽略但很实用的点：

prefix+? 是帮助面板，显示当前生效的绑定。 改过配置之后不用去翻文档。
字面 ctrl+b 用 prefix+ctrl+b 发送。 也就是"再按一次"。终端里有个程序真的需要收到 ctrl+b 时用这个。

配置里的绑定语法是显式的：prefix+n 表示要先按前缀，ctrl+alt+n 才是终端模式下的直接快捷键。可以直接绑普通按键（比如 n），但有风险——它会拦截你所有输入，所以除非你确实想要一个无前缀的模式，否则都用 prefix+。

[keys]
prefix = "ctrl+b"
new_tab = "prefix+c"
split_horizontal = "prefix+minus"
# 一个动作可以有多个绑定
next_tab = ["prefix+n", "ctrl+alt+]"]
# 不用进 resize 模式，直接调大小
resize_pane_right = "ctrl+shift+alt+right"

改配置改乱了的救援命令：

herdr config reset-keys # 备份 config.toml，移除自定义 [keys]，回到内置 v2 默认
herdr server reload-config # 热加载（大部分 UI 设置不用重启 pane）

七、自定义命令与弹出面板

Herdr 允许把任意命令绑到按键上，这是把日常工具接进工作流的入口：

[[keys.command]]
key = "prefix+alt+g"
type = "popup" # popup | pane | shell | plugin_action
command = "lazygit"
description = "run lazygit" # 会显示在 prefix+? 帮助面板里
width = "80%"
height = "80%"

四种类型的语义差别值得记一下：

`type`	行为
`popup`	会话级模态弹窗，不改变 tab 布局，会拿到所有输入（含 Escape）直到命令退出
`pane`	开一个临时 pane，命令退出就关掉
`shell`	后台游离执行
`plugin_action`	调用已安装插件的某个 action

popup 最实用。比如随手开一个临时 shell：

[[keys.command]]
key = "prefix+t"
type = "popup"
command = "exec \"${SHELL:-sh}\""
description = "open scratch terminal"
width = "80%"
height = "80%"

注意 popup 命令拿不到 HERDR_PANE_ID（它是会话级的，不属于任何 pane），要引用底下那个平铺 pane 得用 HERDR_ACTIVE_PANE_ID。这个坑不踩一次很难注意到。

自定义命令能拿到的环境变量里，比较有用的几个：HERDR_SOCKET_PATH、HERDR_BIN_PATH、HERDR_ACTIVE_WORKSPACE_ID、HERDR_ACTIVE_TAB_ID、HERDR_ACTIVE_PANE_ID、HERDR_ACTIVE_PANE_CWD。

标签栏右侧还能挂状态：主机名、时间、一段自定义脚本的输出。

[ui]
tab_bar_position = "bottom"
tab_bar_right = [
 { type = "zoom" },
 { type = "hostname" },
 { type = "datetime", format = "%H:%M" },
 { type = "command", command = "~/.config/herdr/status.sh", interval_seconds = 5, timeout_seconds = 2 },
]
tab_bar_right_separator = " · "

hostname / datetime / command 都在 server 端求值，所以 herdr --remote 时显示的是远端机器的值——这点很正确，看远程构建状态时不会误判。

八、关键一步：让状态真正准确——集成

如果你什么都不做，agent list 会是空的，状态全是 unknown。 我上面贴的实测输出就是这样。这不是 bug，是设计：Herdr 需要 Agent 侧有一个 hook 主动上报状态。

装法是一条命令：

herdr integration install claude
herdr integration install codex
herdr integration status

支持的一堆：pi、omp、claude、codex、copilot、devin、droid、kimi、opencode、kilo、hermes、mastracode、qodercli、qwen、cursor。

我本机 herdr integration status 的实际输出：

pi: current (v8) (/Users/zata/.pi/agent/extensions/herdr-agent-state.ts)
claude: current (v9) (/Users/zata/.claude/hooks/herdr-agent-state.sh)
codex: current (v8) (/Users/zata/.codex/herdr-agent-state.sh)
copilot: current (v3) (/Users/zata/.copilot/hooks/herdr-agent-state.sh)
kimi: current (v7) (/Users/zata/.kimi-code/hooks/herdr-agent-state.sh)
opencode: current (v11) (/Users/zata/.config/opencode/plugins/herdr-agent-state.js)
hermes: current (v5) (/Users/zata/.hermes/plugins/herdr-agent-state/__init__.py)
omp: not installed (/Users/zata/.omp/agent/extensions/herdr-omp-agent-state.ts)
devin: not installed (/Users/zata/.config/devin/herdr-agent-state.sh)
droid: not installed (/Users/zata/.factory/hooks/herdr-agent-state.sh)
qwen: not installed (/Users/zata/.qwen/hooks/herdr-agent-session.sh)
cursor: not installed (/Users/zata/.cursor/herdr-agent-state.sh)
grok: not installed (/Users/zata/.grok/hooks/herdr-agent-state.sh)
...

有意思的是：它检测到我已经装了 Claude、Codex、Copilot、Kimi、OpenCode、Hermes 的集成，但一个都没装 pi。这正是我前面 agent list 为空的原因——我当前跑在 pane 里的那些进程，不是这几个装了集成的 Agent。装完集成后必须在 Herdr 里重启那个 Agent，hook 才会生效。

集成除了报状态，还负责上报原生会话引用，这就是第 4 节"重启后恢复对话"依赖的东西。没装集成的 Agent，重启后只能恢复成一个普通 shell。

Herdr 还有一份给你自己的 Agent 看的技能文件，装上之后 Agent 就知道怎么用 herdr 控制周边窗格：

npx skills add herdrdev/herdr --skill herdr -g

或直接 herdr --skill 打印与当前二进制版本匹配的内置副本。技能文件里第一条是护栏：如果 HERDR_ENV=1 没设置，Agent 必须停下来，并说明自己没跑在 Herdr 管理的 pane 里——防止 Herdr 外部的 Agent 去控制一个不属于它的会话。

九、重头戏：把 Herdr 当 Agent 的控制平面

这才是 Herdr 和 tmux 的分水岭。所有操作都通过本地 socket 上的 JSON API，CLI 只是它的一个包装。

9.1 三层接口，按需选

层	用途
Agent 技能	教 coding agent 在 pane 内使用 Herdr
CLI 包装	脚本、简单编排、人工调试 ← 大多数情况从这层开始
原始 socket API	自定义工具、协议客户端、事件订阅

三层共用同一个控制平面。先看 CLI 的规模——这是 herdr pane --help 的命令表：

$ herdr pane --help
Commands:
 list List panes
 current Show the current pane
 get Show a pane
 layout Show pane layout information
 process-info Show pane process information
 neighbor Find a pane neighbor
 edges Show pane edge information
 focus Focus a neighboring pane
 resize Resize a pane split
 zoom Toggle or set pane zoom
 read Read pane terminal output
 rename Rename a pane
 input Set pane input routing
 split Split a pane
 swap Swap panes
 move Move a pane
 close Close a pane
 send-text Send literal text to a pane
 send-keys Send key presses to a pane
 wait-output Wait for matching pane output
 run Run a command in a pane
 report-agent Report pane agent lifecycle state
 report-agent-session Report pane agent session identity
 release-agent Release pane agent lifecycle authority
 report-metadata Report display-only pane metadata

关键点：pane 是你的手，agent 是你的眼。 用 pane run 开东西，用 pane read / agent wait 拿结果。

9.2 基础编排：起活、读输出、等结果

# 建一个工作区，指定目录和标签
herdr workspace create --cwd ~/code/project --label api

# 切一个 pane 出来跑测试
herdr pane split w1:p1 --direction right
herdr pane run w1:p2 "npm test"

# 读输出（四种来源见下）
herdr pane read w1:p2 --source recent --lines 50

# 等某个字符串出现
herdr pane wait-output w1:p2 --match "Test Suites:" --timeout 120000

pane read --source 的四种取值语义不一样，选错了会读出一堆噪声：

source	含义	适用场景
`visible`	当前渲染的屏幕	UI 反馈循环——想看用户看到什么
`recent`	带终端软折行的最近回滚	一般读取
`recent-unwrapped`	不带软折行的最近回滚	日志——不想被折行切断
`detection`	Agent 屏幕检测用的底部缓冲区快照	排查检测逻辑

我读日志一律用 recent-unwrapped。用 recent 读一段长 JSON 或宽表格，折行会把结构切碎。

9.3 Agent 之间互相指挥

这是最有意思的部分。herdr agent 提供了一组面向"别的 Agent"的动词：

$ herdr agent --help
 list List agents
 get Show an agent
 read Read agent terminal output
 send-keys Send key presses to an agent
 prompt Submit a prompt to an agent
 rename Rename an agent
 focus Focus an agent
 wait Wait until an agent reaches one of the requested states
 attach Attach directly to an agent terminal
 start Start a supported interactive agent in an existing pane
 explain Explain agent detection state

--kind 支持的 Agent 相当全：pi、claude、codex、gemini、cursor、devin、agy、cline、omp、mastracode、opencode、copilot、kimi、kiro、droid、amp、grok、hermes、kilo、qodercli、qwen、maki、muse。

于是你可以这样写一个"评审"流程——一个 Agent 等另一个 Agent 干完再接手：

# 在右窗格起一个 Codex，让它做代码审查
herdr pane split w1:p1 --direction right
herdr agent start reviewer --kind codex --pane w1:p2

# 给它派活，并直接阻塞到它需要你/干完为止
herdr agent prompt reviewer "审查 src/auth 的变更，只报问题不报风格" --wait --until blocked --timeout 600000

# 读它的结论
herdr agent read reviewer --source recent-unwrapped --lines 120

agent start 有个前置条件：目标 pane 必须停在交互式 shell 提示符上——它把 Agent 进程放进现成的 shell 里启动，并确认检测成功才算数。

看清楚 --wait --until blocked 的含义：阻塞直到那个 Agent 真的需要人类介入，而不是"命令跑完了"。这个语义差别很重要，下面 9.4 会展开。

agent prompt 的帮助里有一段很值得逐字读的行为约定：

如果目标 agent 已经处于 blocked 状态，提交会在发送任何输入之前被拒绝，返回 agent_blocked。当一个被接受的提交从非 working 状态起步时，--wait 要求在 5000ms 内观察到一个 working 或 blocked 状态，否则返回 agent_prompt_stalled。

也就是说它主动防止你往一个正在等人类输入的 Agent 里灌东西。这个栏杆方向是对的——blocked 的 Agent 需要的往往是你去回答一个问题，而不是再来一条指令。

另外几个顺手的动词：herdr agent attach reviewer 把当前终端直接接到某个 Agent 的屏幕上（不看全景，就看这一个），退出用 ctrl+b q，想给它发字面 ctrl+b 就连按两次；已经有别的直连客户端占着输入时用 --takeover 抢过来。非 Agent 的普通终端有对应的 herdr terminal attach <terminal_id>。herdr agent rename w1:p1 reviewer 改的是 Agent 的名字，改完它就是一个能用在命令里的稳定引用，比 pane ID 好记。

9.4 为什么 `agent wait` 不是"等命令跑完"

这是我觉得 Herdr 在概念上最清醒的地方。看 help 原文：

Agent waits observe semantic state, not completion of arbitrary commands.

agent wait 观察的是语义状态，不是任意命令的完成。所以在 socket 层它是这么实现的：

server 持有、事件驱动——不是客户端轮询
钉在解析出的 pane 占用者上——如果那个 Agent 被换成了另一个，“等待"不会由新来的假冒满足

配合 events.subscribe 可以做真正的编排：

{"id":"sub_1","method":"events.subscribe","params":{"subscriptions":[
 {"type":"pane.agent_status_changed","pane_id":"w1:p1","agent_status":"blocked"}
]}}

还有一个容易被忽略的竞态。如果你分两步写：

herdr agent prompt reviewer "..." # 先发
herdr agent wait reviewer --until done # 再等

两步之间 Agent 可能已经干完并进入 done，你的 wait 就漏掉了。Herdr 的解法是把 prompt 和 wait 合成一个请求——socket 层的 agent.prompt 接受内嵌的 wait 对象：

{"method":"agent.prompt","params":{
 "pane_id":"w1:p1",
 "text":"...",
 "wait":{"until":["done"],"timeout_ms":600000}
}}

一次请求原子地完成"提交 + 开始等待”，没有中间态。CLI 侧对应的就是 --wait --until。

9.5 状态上报：`report-agent` 与 `report-metadata` 的区别

任何工具（hook、插件、自定义脚本）都可以报状态，但有两个通道，语义完全不同：

命令	影响	用途
`pane report-agent`	语义状态——影响 wait、通知、汇总	告诉 Herdr “我在干活/我卡住了”
`pane report-metadata`	仅展示——只进侧边栏	显示模型名、当前子任务这类信息

# 语义：这个 pane 在干活
herdr pane report-agent w1:p1 --source my-hook --agent docs-bot --state working --message "building docs"

# 展示：只给侧边栏看的自定义字段
herdr pane report-metadata w1:p1 --source my-hook \
 --token model=opus --token summary="reviewing authentication"

别把该用 metadata 的东西丢进 report-agent。 语义状态会驱动 agent wait 的返回和通知的触发，污染它等于让整个编排逻辑读错信号。这条边界划得很清楚，值得尊重。

自定义字段在侧边栏里用 $name 引用，还能配合条件着色：

[ui.sidebar.agents]
rows = [
 ["state_icon", "agent", "$model"],
 ["$summary"],
 ["workspace", "tab"],
]
# 或者按数值变色
# [{ token = "$load", fg = "#fff", rules = [{ gt = 80, fg = "#f55", bold = true }, { gt = 50, fg = "#fc0" }] }]

侧边栏行布局本身是可编程的——rows 里放 token，最多 16 行、每行 16 个 token，支持 equals / contains / starts_with / gt / lt 做条件着色（只有第一条命中的规则生效，没有正则、没有模糊匹配、没有脚本）。还能给特定 Agent 单独换一套：

[ui.sidebar.agents.rows_by_agent]
claude = [
 ["state_icon", "agent", "state_text"],
 ["terminal_title_stripped"], # 直接把 Claude 自己的标题拿来用
 ["workspace", "tab"],
]

注意 key 必须是规范 agent ID（claude、codex、pi），claude-code 这种检测别名不接受。而且它是替换 rows 而不是追加。

9.6 插件：宿主给挂载点，你自己接行为

插件是 Herdr 留给"核心之外"的口子。官方的说法是：Herdr 保持精简的办法，是核心只管终端工作区、窗格、Agent 和一套稳定的 CLI/socket API，其余流程做成可分享的插件——一个目录、一份 herdr-plugin.toml manifest、若干宿主能启动的命令，语言随你（Bash、Node、Lua、Rust 二进制都行）。

三个定位要点：

宿主管挂载，插件管实现。 安装、manifest 校验、键位、终端窗格、事件、调用上下文、socket 访问由 Herdr 提供；实现语言、依赖、文件、持久状态由插件自己负责。
没有插件 SDK，也没有受限命令集。 整个 Herdr CLI 就是插件 API——插件里的代码想调什么就调什么。
回调写 HERDR_BIN_PATH，不要硬编码 socket。 它指向正在运行的 Herdr 二进制，顺带抹平 Unix socket 和 Windows 命名管道的差异。

v1 明确不做的事也值得先知道：不能在运行时注册 action、没有原生非终端 UI，也没有 Herdr 托管的存储 API——需要状态就自己存。

这一段是"官方文档 + 本机 0.9.0 实测"的组合：命令面、参数解析都是我跑出来的；凡是没亲手跑过的我会标出来。

（9 月 15 日二次补充：原本写着"我本机一个插件都没装"。现在装了，所以有了 9.6.7 试装实录，前面几处"没跑过"的说法已经按实测结果改掉。）

9.6.1 先看宿主给了什么

一条 --help 就能把整个插件面看完（输出截断了结尾的 AI 提示段）：

$ herdr plugin --help
Install and run workflow plugins

Usage: herdr plugin [COMMAND]

Commands:
 install Install a plugin from GitHub
 uninstall Uninstall a plugin
 link Link a local plugin
 unlink Unlink a local plugin
 enable Enable a plugin
 disable Disable a plugin
 list List installed plugins
 config-dir Print a plugin config directory
 action List or invoke plugin actions
 log Inspect plugin command logs [aliases: logs]
 pane Manage plugin-owned panes

十一个子命令分三组：装（install / link / uninstall / unlink / enable / disable / list / config-dir）、跑动作（action）、开窗格和查日志（pane / log）。

9.6.2 装：两条路径

从 GitHub 装，只接受简写，内部用 git 拉取：

herdr plugin install <owner>/<repo>[/subdir...] [--ref REF] [--yes]

交互式终端里它会先给一份信任预览——源码位置、以及将要执行的命令——你确认之后才跑 manifest 里的 [[build]]。--yes 跳过确认（脚本里用），--ref 把版本钉在某个 ref 上。

自己写的时候走 link：

herdr plugin link <path> # 插件目录，或直接的 manifest 路径
herdr plugin unlink <plugin_id>

link 不跑 build 命令，构建是你自己的事；unlink 只注销、不动文件；uninstall 会连 Herdr 管理的 GitHub checkout 一起删。反过来，已经 link 的插件不能被 install 覆盖，得先 unlink。

四个容易踩的点：

插件和启用状态是"当前用户全局"的，不属于某个会话。任何会话里装或启用，其他会话立刻可见。0.7.3 时代在命名会话里装的插件需要重新装一次。
v1 没有 plugin update，刷新 = 重新 install（会替换托管的 checkout）。
install 和 link 都会顺手把插件的 config / state 目录建好；只想拿路径就用 herdr plugin config-dir <id>。
没有 server 在跑也能装、能 link——它们只是往全局插件表里注册，不等 server。

装之前本机正好是空态，当基线很干净（装完之后长什么样见 9.6.7）：

$ herdr plugin list
No plugins installed.

$ herdr plugin list --json
{"id":"cli:plugin","result":{"plugins":[],"type":"plugin_list"}}

9.6.3 用：绑键、开窗格

装完插件不会自己冒出来。它对外提供的是 action 和窗格入口，接上手最常用的是绑键：

[[keys.command]]
key = "prefix+alt+f"
type = "plugin_action"
command = "herdr-file-viewer.open-file-viewer" # 插件id.action
description = "open file viewer"

command 写 action id：本地 id（open-file-viewer）和限定名（插件id.action）都可以，本地 id 命中多个插件时报 ambiguous_plugin_action 让你补限定名——所以一开始就写限定名最省事，herdr plugin action invoke 同理。

窗格是插件的"界面"。herdr plugin pane open 让 manifest 里声明的 [[panes]] 命令变成一个 Herdr 管理的终端窗格，摆放方式可以在命令行覆盖 manifest 的默认值：

herdr plugin pane open --plugin ID --entrypoint ID \
 --placement split --direction right [--cwd PATH] [--env KEY=VALUE]

`placement`	行为
`overlay`（manifest 默认）	临时缩放的覆盖层，盖在当前 pane 上；关闭时恢复原来的焦点和缩放
`popup`	会话级模态弹窗，不改布局，拿到全部输入（含 Esc），命令退出或收到 `popup.close` 就关
`split`	常规分割窗格
`tab`	新标签页
`zoomed`	放大窗格

popup 是最"不像 pane"的一种，边界记清楚：它没有 pane ID、不发 pane 生命周期事件、不参与布局/持久化/agent API，进程里也拿不到 HERDR_PANE_ID（想引用底下那个平铺 pane，读上下文 JSON）。--width / --height 只对它有意义：默认半屏，支持 80% 这类百分比，低于弹窗最小值会被夹紧；Settings、Copy mode 这类模态开着时开 popup 会返回 ui_busy。

踩坑：--help 不是完整真相。 0.9.0 的 herdr plugin pane open --help 里，--placement 的候选值只列了 overlay|split|tab|zoomed，--width / --height 根本没出现。但解析器是接受 popup 的：

$ herdr plugin pane open --plugin nope.nope --entrypoint nope --placement popup
{"error":{"code":"plugin_not_found","message":"plugin not found"},"id":"cli:plugin"}

$ herdr plugin pane open --plugin nope.nope --entrypoint nope --placement bogus
invalid pane placement: bogus

第一条已经走到"找不到插件"这一步，说明 popup 通过了参数校验；第二条才是不合法值。顺带一提，zoomed 还有个 fullscreen 别名。摆放这件事以文档和源码为准，别以 help 为准。

跑过的动作和日志都查得到：

herdr plugin action list [--plugin ID]
herdr plugin action invoke <action_id> [--plugin ID]
herdr plugin log list [--plugin ID] [--limit N]

9.6.4 插件进程能拿到什么

调用时 Herdr 注入的环境变量：

变量	用途
`HERDR_PLUGIN_ID` / `HERDR_PLUGIN_ROOT`	插件身份、安装（或 link）目录
`HERDR_PLUGIN_CONFIG_DIR`	用户可编辑的配置，`.env` 放这里
`HERDR_PLUGIN_STATE_DIR`	插件自己的运行时状态
`HERDR_PLUGIN_CONTEXT_JSON`	完整调用上下文：workspace / tab / 焦点 pane / worktree / agent / 选中文本 / 被点击的 URL
`HERDR_BIN_PATH` / `HERDR_SOCKET_PATH`	回调入口，优先用前者
`HERDR_PLUGIN_ACTION_ID`	被哪个 action 调起来的
`HERDR_PLUGIN_EVENT` / `HERDR_PLUGIN_EVENT_JSON`	事件钩子的事件名与完整事件体
`HERDR_PLUGIN_ENTRYPOINT_ID`	窗格命令对应哪个 entrypoint
`HERDR_PLUGIN_CLICKED_URL` / `HERDR_PLUGIN_LINK_HANDLER_ID`	链接处理器专用

一条规矩：HERDR_PLUGIN_ROOT 是源码 checkout，不要往里写凭据和状态；用户配置进 CONFIG_DIR，运行时状态进 STATE_DIR。这两个目录 Herdr 负责建（CONFIG_DIR 还会从旧位置迁移一次），但里面的内容它不校验、不同步、也不删。另外 --env KEY=VALUE 可以给启动的进程加变量，不过和 Herdr 自己的变量冲突时以 Herdr 为准。

9.6.5 写：最小骨架

目录就两样东西：

my-plugin/
 herdr-plugin.toml
 peek.sh

manifest：

id = "me.file-peek"
name = "File Peek"
version = "0.1.0"
min_herdr_version = "0.7.0"
description = "在弹窗里看一眼文件"
platforms = ["linux", "macos"]

[[actions]]
id = "peek"
title = "Peek file"
contexts = ["pane", "workspace"]
command = ["bash", "peek.sh"]

[[panes]]
id = "viewer"
title = "Peek"
placement = "popup"
width = "80%"
height = "80%"
command = ["bash", "peek.sh"]

# 除了 action 和 pane，manifest 还能声明这四类（写法示意）：
[[build]]
command = ["bash", "build.sh"]

[[startup]]
command = ["node", "dist/restore.js"]

[[events]]
on = "worktree.created"
command = ["node", "dist/on-worktree.js"]

[[link_handlers]]
id = "peek-path"
title = "Peek this file"
pattern = "^file://"
action = "peek" # 必须是同一个插件声明的 action

规则清单：

command 是 argv 数组，不走 shell。 没有 glob、管道、&&；需要 shell 语义就在命令里显式起一个 shell。
id 规则不对称： 插件 id 可以用点（me.file-peek），action / pane / link handler 的 id 不能用点。所以限定名 插件id.action 天然不会歧义。
min_herdr_version 是必填，而且真的会被强制：插件要求的版本比当前二进制新，install 和 link 都会拒绝。
platforms 可以分层： 顶层不写也能 link（给个警告），item 级的 platforms 覆盖顶层。Windows 上，build / action / event 命令会解析 npm.cmd、bun.cmd 这类 PATHEXT shim，而 pane 命令走 Herdr 常规的 Windows 启动路径，必须是合法的 Windows argv 命令。
[[build]] 只在 install 时跑（link 不跑）。如果构建过程中 manifest 被改动，安装会中止——避免"预览看到的"和"实际装上的"不是同一个东西。
[[startup]] 是一次性初始化，不是守护进程。 每个启用的插件在会话恢复后跑一次，live handoff 之后也会再跑一次；client 附着、配置热加载、插件新装或新启用都不触发。适合"把插件自己的状态恢复回去"，不适合挂常驻服务。
[[events]] 的钩子由 Herdr 端触发，事件体通过 HERDR_PLUGIN_EVENT_JSON 传进来。事件名要写当前版本支持的（未知事件名会在 link 时给出警告）。
[[link_handlers]] 匹配的是 Ctrl+点击的 URL（macOS 也是 Ctrl，因为终端鼠标上报分不出 Command），pattern 是 Rust 正则，按 manifest 顺序检查，action 必须是同一插件的 action。被点的那条 URL 在 HERDR_PLUGIN_CLICKED_URL 和上下文 JSON 里。
回调写 HERDR_BIN_PATH：

const { spawnSync } = require("node:child_process");
const herdr = process.env.HERDR_BIN_PATH ?? "herdr";
spawnSync(herdr, ["workspace", "list"], { stdio: "inherit" });

官方有一份可以直接抄的例子仓库：ogulcancelik/herdr-plugin-examples（agent-telegram-notify、github-link-preview、dev-layout-bootstrap）。注意它是"示例"，不是官方维护的插件。

9.6.6 现成的：几类值得装的

市场里已经有能直接用的东西。下面这几条我都核过 manifest 或仓库说明：

插件	干什么	备注
smarzban/herdr-file-viewer	只读文件查看器：目录树 + 内容面板，支持 diff、markdown 渲染、语法高亮，开在 split 里	只在显式动作下打开，装完要自己绑键；markdown / diff 的美化靠外部 `glow` / `delta` / `bat`，没装会退回纯文本
persiyanov/herdr-reviewr	评审侧栏：看 Agent 改出来的 diff，加行内评论回传给 Agent	macOS/Linux，要求 ≥ 0.7.5；带 `worktree.created` 钩子，可以配成自动打开
alexarthurs/herdr-sidebar	VS Code 式侧栏：文件树 + git source control，语法高亮预览和 diff	manifest 在仓库的 `plugins/herdr-sidebar/` 子目录
iurysza/termscope	把终端里已经出现的文件路径 / 链接在 split 里打开	从屏幕内容取路径，不用手输

装法就是前面那条命令，三条都跑通了（完整过程见下一节）：

herdr plugin install smarzban/herdr-file-viewer
herdr plugin action list --plugin herdr-file-viewer
herdr plugin pane open --plugin herdr-file-viewer --entrypoint file-viewer --placement split

--plugin / --entrypoint 的取值来自这个插件的 manifest（id = "herdr-file-viewer"、[[panes]] id = "file-viewer"），它的两个 Unix action 是 open-file-viewer 和 open-file-viewer-tab（另有 -windows 后缀的两个，Windows 上要绑那两个）。

想找更多，官方有一个插件市场：自动索引 GitHub 上打了 herdr-plugin topic、默认分支里有合法 manifest 的公开仓库，按热度、活跃度、最新排序——今天查这个 topic 下已经有 1161 个仓库。要留意它是未审核的索引：上榜只说明那个仓库给自己打了标签，不代表 Herdr 验过。装之前先读信任与安全那一节，扫一眼 manifest 和它要跑的命令——plugin install 的那份预览就是为这个准备的。

9.6.7 试装实录：herdr-file-viewer

表里第一个我真装了一遍。选它的理由不在星数，在形状匹配：那几条里唯一 scope 就写着"只读文件查看"的、唯一过了 1.0 的（v1.16.0），而且 min_herdr_version = "0.7.0" 是几个候选里最低的，兼容性最宽。

第一步：install，以及那份预览到底给不给你看。

$ herdr plugin install smarzban/herdr-file-viewer --yes
Plugin install preview:
 id: herdr-file-viewer
 version: 1.16.0
 source: smarzban/herdr-file-viewer
 commit: 78441da81e63d5fc416ab63fa99d006161595523
 actions: 4 startup commands: 0 events: 0
 panes: 1 link handlers: 0 build commands: 2
 build: /bin/sh scripts/fetch-or-build.sh
 build (skipped on macos): powershell -NoProfile ... fetch-or-build.ps1
 action open-file-viewer: bash scripts/open-file-viewer.sh
 action open-file-viewer-tab: bash scripts/open-file-viewer-tab.sh
 action open-file-viewer-windows: powershell -NoProfile ... open-file-viewer.ps1
 action open-file-viewer-tab-windows: powershell -NoProfile ... open-file-viewer-tab.ps1
 pane file-viewer: ./target/release/herdr-file-viewer
Installed herdr-file-viewer from smarzban/herdr-file-viewer.
Config: /Users/zata/.config/herdr/plugins/config/herdr-file-viewer

预览是真东西，不是装饰：它把 install 将要执行的每一条 [[build]]、每一个 action 的实际 argv 全列出来，连那两条上千字符的 Windows PowerShell 单行也原样摊开，还标出哪些被当前平台跳过（build (skipped on macos)）。要审计第三方插件，这一屏就是审计面。

一个约束值得单独说：源码里有一条 remote plugin install requires --yes when stdin is not interactive（我没实跑，一开始就带了 --yes）。结论是脚本、CI、Agent 里装插件必然带 --yes，也就是必然跳过人工确认。所以更稳的顺序是先不带 --yes 跑一次、人工读完预览、再决定要不要带。

第二步：[[build]] 干了什么，东西落在哪。

fetch-or-build.sh 走快路径——按 manifest 版本加平台下载预编译二进制、校验 SHA-256，失配才回退 cargo build。本机没回退，直接产出 target/release/herdr-file-viewer，file 出来是 Mach-O arm64、3.7MB。

这一步建议真的看一眼：[[panes]] 里声明的是相对路径 ./target/release/herdr-file-viewer，构建静默失败时 install 不会报错，要到你按键那一刻才发现窗格起不来。

位置	内容
`~/.config/herdr/plugins/github/herdr-file-viewer-c993314e2614/`	托管 checkout（含构建产物），`uninstall` 会连它一起删
`~/.config/herdr/plugins/config/herdr-file-viewer/`	用户可编辑配置，`herdr plugin config-dir <id>` 打印的就是这个
`~/.local/state/herdr/plugins/herdr-file-viewer/`	插件自己的运行时状态

对应 9.6.4 那条规矩：构建产物落在 PLUGIN_ROOT 里，被重新 install 覆盖是正常行为，插件不该往这儿写状态。

第三步：绑键——别照抄 README 的键，先查默认表。

README 推荐 prefix+f。我先对着 0.9.0 的默认 prefix 表核了一遍，被占用的是 shift、n、c、p、minus、v、q、l、h、z、w、j、g、alt、x、t、r、k、b，f 确实空闲。

[[keys.command]]
key = "prefix+f"
type = "plugin_action"
command = "herdr-file-viewer.open-file-viewer"
description = "open file viewer in split"

[[keys.command]]
key = "prefix+shift+f"
type = "plugin_action"
command = "herdr-file-viewer.open-file-viewer-tab"
description = "open file viewer in tab"

然后热加载，它会把诊断回给你：

$ herdr server reload-config
{"id":"cli:server:reload-config","result":{"diagnostics":[],"status":"applied","type":"config_reload"}}

diagnostics: [] 就是干净。我只验证了"正常绑定不报错"这一侧，没去构造绑错的样本，所以不把这句话当完整错误清单用。

第四步：确认它真的画出来了。

action invoke 返回成功只代表命令被派发，不代表窗格活着。两个真凭据：

$ herdr plugin log list --plugin herdr-file-viewer
... "exit_code":0, "status":"succeeded" ... "type":"plugin_pane_opened"
 "pane_id":"wB:p7", "label":"Files", "focused":true

再加一次屏幕读取（--source detection 读后台缓冲，不受你滚动的影响）：

$ herdr pane read wB:p7 --source detection --format text
┌zata_code_template─────┐┌.claude────────────────────────────────────────────────┐
│ ▸ .claude ▐││Directory: select a file to view │
│ ▸ .cursor ▐││ │
│● ▸ docs ││ │
│ ▸ src ││ │
│▄▄▄▄▄▄▄▄▄▄▄▄▄ ││ │
└fix/alembi…consistency─┘└─────────────────────────────────────────────────? help┘

两栏、git 状态标记（●）、底栏分支名都在，才算装成。

装完留下的五条经验

CLI 调 action 打在"焦点窗格"上，不是你的窗格。 我在 wC 的 pane 里执行 plugin action invoke，split 却开在了另一个工作区 wB。返回值里的 context.focused_pane_id / workspace_id 会告诉你目标是谁。人在界面上按键没这个问题，脚本里容易踩。
plugin pane 的 cwd 是插件根目录，不是工作区。 pane open 返回里 cwd 和 foreground_cwd 都是 <plugin_root>。所以插件里用相对路径当参数会指到自己家；要拿工作区路径得读 HERDR_PLUGIN_CONTEXT_JSON。
验证完要收尾，而且 close 是位置参数。 herdr plugin pane close <pane_id>，写成 --pane-id 会打 usage 纠正你。再用 pgrep -f <binary> 确认子进程真退了——窗格关掉不等于进程消失，别默认它干净。
“支持 markdown 渲染"这类话要看外部依赖。 它的美化接的是外部 glow / delta / bat，我本机三个都没有，于是走纯文本 fallback。功能没坏，但和插件表里那句期待的不完全是一回事。装之前 command -v glow 扫一眼。
回滚是干净的。 herdr plugin uninstall smarzban/herdr-file-viewer 删托管 checkout，键位是自己加进 config.toml 的两段、手删，没有残留状态要清。

顺带印证了 9.6.2 那句"v1 没有 plugin update"：herdr plugin --help 的十一个子命令里确实没有 update，刷新就是重新 install——而重新 install 会替换托管 checkout，连 target/release/ 里的构建产物一起没，所以插件自己的状态一定要放在 state 目录而不是根目录。

这一节如果只记一句话：插件不是"装了就有的功能”，而是"宿主给你挂载点、你自己把行为接上去"。 它也解释了为什么 Herdr 本体能一直保持这么瘦。

十、多机：本地和远程在同一个窗口

# 临时接一台机器
herdr --remote workbox

# 或者存下来，之后在侧边栏里按机器切
herdr machine add workbox --label "Build machine"
herdr machine list
herdr --remote-keybindings server # 远程用服务器的按键绑定，而不是本地的

“远程"有三种走法，先选对。 差别不只是习惯：

走法	谁在跑 server	适合
本机 `herdr`	本机	日常
`ssh you@server` 再跑 `herdr`	远端，纯 tmux 式	手机 SSH 客户端；你本来就活在 SSH 里
`herdr --remote workbox`	远端，UI 由本地 client 画	想要"远程会话手感像本地”

第三种和第二种有一个实际差异值得知道：先 ssh 再跑 herdr，Herdr 整个在远端运行，读不到你本地桌面的剪贴板；而 --remote 时 client 在你本机，本地截图可以直接粘到远端 pane 里（remote_image_paste 默认绑 ctrl+v，只在 --remote 下生效）。要给远端的 Agent 贴图，只有这条路走得通。

手机上盯 Agent。 Herdr 没有手机 App，也没打算做 web dashboard——装个 SSH 客户端连上跑着任务的机器，敲 herdr，同一套持久会话就在窄屏里打开了。TUI 会自适应：侧边栏收成移动版切换器，Agent 行带上 tab 上下文，切工作区、看 pane、查状态都不用离开 SSH。iPhone 上官方点名 moshi 用着顺。

设计上有两个细节做得对：

本地和远程的 Agent 汇总在同一个列表里，每台机器的连接独立重连——断了一台不会拖垮其他。
展示类设置跟随 client，运行类设置跟随 server。 主题、侧边栏布局、复制行为来自你本地 client 的配置（你 SSH 过去，看到的还是自己的主题）；pane 默认值、worktree、集成、自定义命令属于跑着 pane 的那台 server。这个切分很清晰，避免了"我改了主题怎么远程机器没变"这类困惑。

herdr --remote 默认会生成一份私有 SSH config（先 include 你的 ~/.ssh/config，再补上 ServerAliveInterval / ServerAliveCountMax 作为兜底，你自己设的 keepalive 优先），并用私有 control socket 复用第一次认证的连接。不想让它插手就 manage_ssh_config = false。

另一个不在 tmux 里的东西是 worktree：

herdr worktree list
herdr worktree create --branch feature/x --base main
herdr worktree open --branch feature/x
herdr worktree remove --workspace w7

它把 git worktree 拉成工作区的一组子行。关闭父工作区会关掉这一组，但不会删掉 checkout 目录和分支；worktree remove 会先请求安全删除，git 拒绝（有改动或未跟踪文件）时再二次确认，然后才 force。分支永远不会被删掉。 这个安全设计我认为是正确的默认。

十一、配置速查

配置文件：~/.config/herdr/config.toml（Windows 是 %APPDATA%\herdr\config.toml）。相关命令：

herdr --help # 会显示解析到的配置路径
herdr --default-config # 打印完整默认配置（带注释，是最好的文档）
herdr --default-config > ~/.config/herdr/config.toml # 全量落盘再改
herdr server reload-config # 热加载
herdr config reset-keys # 按键绑定重置

Herdr 没有配置文件也能跑；值非法会退回安全默认并在启动时告警（不静默）。

几个我认为值得一改的项：

[terminal]
shell_mode = "auto" # macOS 上 auto = 登录 shell，/usr/libexec/path_helper 和 Homebrew 的 PATH 才会生效
new_cwd = "follow" # follow(继承来源 pane) | home | current | 固定路径如 "~/Projects"

[ui]
status_indicators = "symbols" # 用形状而非仅颜色区分四种状态
agent_panel_sort = "priority" # 变成"谁在等我"的注意力队列
prompt_new_tab_name = false # 新建 tab 不弹窗问名字，省一次交互

[ui.toast]
delivery = "terminal" # SSH 场景下让外层终端发通知

[server]
headless_cols = 160 # 没有 client 连接时的虚拟终端宽度（默认 120x40）
headless_rows = 50

headless_rows/cols 这个不是小事：没有 client 连着时，server 用一个 120×40 的虚拟终端来算布局。Agent 的 TUI 渲染是按 pane 尺寸做的——尺寸变了它会重排。所以你在无 client 状态下跑的 Agent，看到的界面尺寸和你回头附上去时不完全一致。这不是 bug，但值得知道。

主题与外观。 内置 11 套主题，也可以在主题上逐个覆盖颜色 token：

[theme]
name = "catppuccin" # catppuccin / terminal / tokyo-night / dracula / nord /
 # gruvbox / one-dark / solarized / kanagawa / rose-pine / vesper
auto_switch = true # 跟随外层终端的明暗自动切换
dark_name = "catppuccin"
light_name = "catppuccin-latte"

[theme.custom] # 在选中的主题上覆盖单个颜色 token
sidebar_bg = "#181825"
selection_bg = "#313244"
accent = "#f5c2e7"

theme.custom 的值可以是 hex、颜色名或 rgb(r,g,b)，也能给某个面设 panel_bg = "reset" 交还给外层终端；开了 auto_switch 之后还能用 [theme.custom.light] / [theme.custom.dark] 给明暗两态各自叠一层。

中文输入法的三个开关。 都在 [experimental] 里、默认关，但每个都值得中文用户试一次：

[experimental]
# 按 prefix 时临时把系统输入源切成 ASCII，退出后恢复——中文输入法开着也能触发 prefix 命令
switch_ascii_input_source_in_prefix = true

# Claude Code / pi / codex 这类 TUI 自己画光标，macOS 输入法会把候选框跟丢；
# 把 pane 光标暴露给外层终端，输入法就能继续跟随
reveal_hidden_cursor_for_cjk_ime = true
# 只对检测到的这些 Agent 生效；留空则对所有聚焦 pane 生效
cjk_ime_agents = ["claude", "codex"]

代价和边界也说清楚：第一个是 best-effort、只覆盖 macOS 和 Windows，而且 Windows 上目前只处理韩文 IME（中文输入法不受益），macOS 上是临时切 ASCII 键盘布局、可用；第二个会让那些"隐藏光标又不用别的东西代替"的应用多出一个可见光标（比如 vim 的普通模式），介意的话就把 cjk_ime_agents 列成常用 Agent，让它只在这些 pane 里生效。

几个散点：

[terminal] kitty_graphics（默认开）：外层终端支持 Kitty 图形协议时，pane 里的图片会真正渲染出来。
索引绑定：switch_tab = "prefix+1..9"（默认）、switch_workspace = "prefix+shift+1..9"、focus_agent = "prefix+alt+1..9"——一行配置换来"按序号直达"；旧的 [keys.indexed] 仍在解析，但新配置用这三个。
[advanced] scrollback_limit_bytes：每个 pane 的回滚上限，默认 10MB（对齐 Ghostty）。

环境变量一览：

变量	用途
`HERDR_CONFIG_PATH`	覆盖配置文件路径
`HERDR_SESSION`	为 CLI 命令选择命名会话
`HERDR_SOCKET_PATH`	覆盖 socket 路径
`HERDR_ENV`	在 Herdr 管理的 pane 进程内设为 `1`（技能文件的护栏靠它判断）
`HERDR_PANE_ID` / `HERDR_TAB_ID` / `HERDR_WORKSPACE_ID`	当前 pane 的标识
`HERDR_LOG`	日志过滤，如 `HERDR_LOG=herdr=debug`
`HERDR_DISABLE_SOUND`	关掉声音

排障时日志在这三个文件：~/.config/herdr/herdr.log、herdr-client.log、herdr-server.log。提问时记得连轮转后的兄弟文件一起带上。

十二、避坑清单

#	坑	现象	正确做法
1	不装集成就指望状态准确	`agent list` 为空，全 `unknown`	`herdr integration install <name>`，然后在 Herdr 内重启该 Agent
2	以为重启能恢复进程	shell 里跑到一半的命令没了	只有装了集成并上报过 session 引用的 Agent 能恢复对话，进程不恢复
3	`popup` 命令里读 `HERDR_PANE_ID`	拿到空值，脚本行为异常	popup 是会话级，用 `HERDR_ACTIVE_PANE_ID`
4	分两步 prompt + wait	Agent 干太快，`wait` 漏掉已完成状态	用 `--wait --until`，或 socket 层的 `agent.prompt` + 内嵌 `wait`（原子）
5	拿 `report-agent` 报展示信息	通知和 wait 被错误状态触发，编排读错信号	展示信息走 `report-metadata`，语义状态才走 `report-agent`
6	读日志用 `recent`	长行被软折行切断，结构破碎	读日志用 `recent-unwrapped`；看用户所见用 `visible`
7	绑定普通按键没留意	输入的字符被 Herdr 拦截	一律用 `prefix+`，除非明确要一个无前缀模式
8	改完配置不热加载	改了半天没生效	`herdr server reload-config`；按键乱掉用 `herdr config reset-keys`
9	忘了无 client 时的尺寸	Agent TUI 在附着前后布局不一致	用 `[server] headless_cols/rows` 定成你常用的尺寸
10	`rows_by_agent` 用检测别名	配置不生效	key 必须是规范 ID（`claude`），不能用 `claude-code`
11	以为关工作区会删 worktree	担心丢代码	关父工作区只关 group，不删目录、不删分支；`worktree remove` 有二次确认
12	从 Herdr 里再启一个 Herdr	起不来	`[experimental] allow_nested = false` 是默认，确实需要才开
13	`herdr update` 以为会立即生效	更新了但行为没变	看 `herdr status` 里的 `restart_needed` / `server_binary_stale`
14	右键开不出 Herdr 菜单	该 pane 开了右键转发	右键窗格边框唤回菜单；或右键菜单里切回 “Use Herdr right-click menu”
15	对 brew / mise / Nix 安装跑 `herdr update`	不生效或被拒	用各自的包管理器升级；只有直接安装能用 `herdr update` 和预览通道
16	以为 server 重启后屏幕内容还在	恢复出的是空白新 shell	屏幕回放要开 `[experimental] pane_history = true`，且其中内容按终端历史对待（可能有敏感输出）
17	中文输入法开着时 prefix 按键失灵	prefix 命令不触发	`switch_ascii_input_source_in_prefix = true`（macOS 可用；Windows 目前只处理韩文 IME）
18	装完插件等它自己出现	什么都没发生	插件只声明 action 和窗格入口，要自己绑 `[[keys.command]] type = "plugin_action"`
19	以为插件只属于某个会话	别的窗口里也看到了	插件与启用状态是当前用户全局的；v1 也没有 `plugin update`，刷新靠重装
20	拿 `plugin pane open --help` 当选型依据	以为开不了 popup	0.9.0 的 help 少列了 `popup` 和 `--width` / `--height`，以文档和源码为准

十三、它适合谁

我觉得下面这几类人会立刻感觉到收益：

多 Agent 并行的人：侧边栏统一状态 + blocked 优先队列，直接替掉了"挨个窗口看一眼"这个动作
经常 SSH 到别的机器跑长任务的人：--remote + 已保存机器，本地和远程混在一个视图里；临时想看一眼进度，手机装个 SSH 客户端就能盯同一批 Agent
在搭多 Agent 编排的人：这是 Herdr 真正的差异点——agent.prompt --wait 和 events.subscribe 让你可以用语义状态而不是输出字符串匹配来调度 Agent。绝大多数同类工具只做到"起了个 pane"
不想学新键位的人：鼠标能完成一切，前缀键是 ctrl+b，tmux 用户可以无痛切换

反过来说，如果你只是单窗口单 Agent 偶尔用一下，Herdr 的价值会被大幅摊薄——它解决的问题主要来自"数量"。

也必须承认，它几乎没有全新概念：window 换成 workspace、tmux 式的状态栏、轮询换成事件订阅，每一项都能在别处找到。它的价值在组合——把这些拼成一个"以 Agent 为一等公民"的工作区，而且做得相当克制（Rust 单二进制、无 Electron、不做静默自动更新）。

如果只能记一件事：Herdr 的重点不是"同时开好几个 Agent"，而是让 Agent 的状态变成可被程序读取、可被别的 Agent 等待的信号。 想明白这一点，agent wait 和 report-agent 那一堆 API 的用法就都顺了。

参考

herdr.dev —— 官网与文档（有中文）
github.com/herdrdev/herdr —— 源码（Apache-2.0，Rust）
快速开始 / 配置 / CLI 参考
会话状态与恢复 —— 从活持久到热交接的五种恢复路径
怎么用：本地、SSH、手机 —— 三种远程姿势怎么选
Socket API —— 编程控制与事件订阅
Agent 技能文件 —— 给 Agent 看的用法说明
插件市场 —— GitHub 上 herdr-plugin 仓库的自动索引（未审核）
插件作者文档 —— manifest、命令、环境变量与信任模型的权威参考
agent-guide.md —— 让 Agent 帮你装/排查 Herdr 的提示词指南

图片来源：文中截图取自 herdr 官方文档与 GitHub README 的演示素材（herdr.dev/zh-cn/docs/how-to-work 与 README 中的演示视频，手机截图来自前者），项目以 Apache-2.0 授权。截图中的仓库名、分支名、模型名为官方演示环境内容。

CC Switch 详解：一个应用管住八个 AI 编程 CLI

Tue, 15 Sep 2026 09:30:00 +0800

整理开发机时发现一件小事：brew list --cask --versions cc-switch 报的版本是 3.14.1，但打开 CC Switch 的界面，关于页写的是 3.20.0。不是装错了——这个 cask 带 auto_updates 标记，应用自己会联网更新，Homebrew 的账本追不上它。

一个配置管理工具，几个月里自己跑出去六个小版本。这个更新频率本身就是信号：它要追的那群 AI 编程 CLI，配置面正在快速膨胀。

这篇文章把 CC Switch 讲清楚——它解决什么问题、切换时内部到底改了什么、六大功能模块各自能做到什么程度、装和升级要注意什么，以及最容易被忽略的两块风险。先说结论：它本质上不是一个「供应商切换器」，而是给八个 AI 编程工具做的一层本地配置管理层，切换只是这层管理层里最容易被看见的那个动作。

一、它要解决的问题：配置面已经失控

现代 AI 编程很少只用一个 CLI。常见组合是 Claude Code 写主力逻辑、Codex 处理特定任务、Gemini CLI 做交叉验证，再加上 OpenCode、OpenClaw 这类各有侧重的工具。

麻烦在于，每个工具一套配置，格式还都不一样：

Claude Code 走 ~/.claude/ 下的 settings 与环境变量（ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN）；
Codex 走 ~/.codex/config.toml 加 auth.json；
其他工具各有自己的 JSON、TOML 或 .env。

切换一个 API 供应商，意味着要按各家的格式分别手改一遍：改 base URL、换 token、别把别的不相关字段写坏。用几个工具就要重复几遍，漏改一个，那个工具就会继续拿着旧地址和旧 key 请求——而且往往不是立刻报错，是在你以为一切正常的时候返回一堆看不懂的失败。

MCP 服务器和 Skills 更麻烦。同一份 MCP 配置要在多个应用里各维护一份；提示词文件更是分裂成 CLAUDE.md、AGENTS.md、GEMINI.md 三个名字，内容基本一样，改一处就要记得同步另外两处。

CC Switch 就是冲着这一层来的。需要先划清边界：它管的是「配置怎么存、怎么切、怎么同步」，不负责判断某个供应商好不好。 本文同样不评价任何具体供应商的质量，只讨论管理这件事本身。

二、CC Switch 是什么

一句话：一个开源的跨平台桌面应用，把上述所有工具的供应商配置、MCP、Skills、用量和会话收拢到一个界面里管理。

项目	情况
仓库	GitHub `farion1231/cc-switch`，MIT 协议，官网 ccswitch.io
技术栈	Tauri 2 + Rust 后端，React 18 + TypeScript 前端
体量	创建于 2025 年 8 月，截至 2026-09-15 约 13.2 万 star、9,100 fork
平台	Windows 10+ / macOS 12+ / Ubuntu 22.04+、Debian 11+、Fedora 34+
支持工具	Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build、OpenCode、OpenClaw、Hermes

▲ 主界面顶部按应用分标签页（Claude / Codex / Gemini…），每个供应商一张卡片；当前激活的那张会显示用量与余额。图：CC Switch 官方仓库

八个工具的配置，被抽象成同一套「供应商」模型：一张卡片 = 一组配置 = 一个可以一键启用的状态。这就是它全部设计的地基，后面所有功能都建立在这一点上。

三、切换的时候，内部到底改了什么

理解 CC Switch 的关键，是搞清楚它的数据存在哪、切换时动了什么。

数据分两层存。可同步的数据——供应商、MCP、提示词、技能——进 SQLite（~/.cc-switch/cc-switch.db），它被当作单一事实源（SSOT）；只跟这台设备有关的偏好设置进 ~/.cc-switch/settings.json。分开的好处很直接：把数据库同步到多台机器，不会把 A 机器的窗口位置和 B 机器的主题设置搅在一起。

切换是双向同步，不是单向覆盖。 启用某个供应商时，它把配置写进对应 CLI 的 live 配置文件；反过来，当你编辑当前正在生效的那个供应商时，它会先从 live 文件把数据回填回来。这条设计解决的是一个很实际的场景：你在 CLI 里手动调过某个参数，如果不回填，下次切换就会把你的手改抹掉。

写入用「临时文件 + 重命名」的原子操作，避免写到一半崩溃留下半截 JSON 把工具搞挂。同时有自动备份机制，~/.cc-switch/backups/ 轮换保留最近 10 份，Skills 相关另有一份保留 20 份。

设计原则是「最小侵入」：任何时刻至少保留一个激活中的供应商，所以你没法把配置删空；反过来，就算直接卸载 CC Switch，已经写进各工具的配置仍然有效，不会让工具用不了。

有一个细节值得单独说：生效方式不统一。大多数工具需要重启终端或 CLI 才能读到新配置，只有 Claude Code 支持热切换，改完即生效。所以「我切了怎么没反应」这类困惑，多数时候答案就是重启终端。

▲ 添加供应商时，预设列表覆盖了主流模型厂商与社区中转服务，选中后通常只需填 API Key，请求地址已预设好。图：CC Switch 官方仓库

还有个容易踩的坑值得提前知道：切换供应商后，你在某个工具里装的插件配置可能「不见了」。原因是插件配置往往写在同一个配置文件里，切换时没被带过去。官方的解法是「通用配置片段」——在编辑供应商的面板里点「从当前供应商提取」，把 Key 和请求地址之外的通用数据抽出来存成片段；之后新建供应商时勾选「应用通用配置」（默认勾选），这些数据就会被一并写入。你首次导入的那份默认供应商也会完整保留所有配置项。

四、功能地图：六个模块各自做到什么程度

4.1 供应商管理

核心是预设体系：内置 50+ 预设，覆盖 AWS Bedrock、NVIDIA NIM 以及大量社区中转服务，多数预设只需填 API Key。此外支持拖拽排序、导入导出、系统托盘一键切换。

有一个值得注意的抽象叫「通用供应商」：一份配置同时同步到 Claude Code、Codex 和 Gemini CLI。如果你的诉求是「所有工具都指向同一个入口」，这比逐工具配置省事得多。

回切官方登录也是支持的：添加一个「官方登录」预设，切过去后跑一遍 Log out / Log in 流程，之后就能在官方与第三方之间来回切。Codex 还支持在多个官方账号（比如 Plus 和 Team）之间切换。

▲ 设置里的「Codex 应用增强」：开启后，使用第三方 API 期间仍可保留官方登录态，从而继续使用官方插件与手机远程操作等功能。图：CC Switch 官方仓库

4.2 本地代理与故障转移

这是整个应用里分量最重、也最需要理解成本的一块。

它会在本地起一个代理服务（默认 http://127.0.0.1:15721），支持格式转换——把一种 API 协议转成另一种，让某个工具走它本来不支持的供应商；支持自动故障转移和熔断器，某个上游挂了自动切到备用；还有供应商健康监控和整流器。

应用级接管是另一个维度：可以独立为 Claude、Codex、Gemini 或 Grok Build 配置代理，粒度细到单个供应商。也就是说，你可以只让 Codex 走本地代理，Claude Code 保持直连。

▲ 设置 → 路由：路由总开关、逐应用接管开关（图中只开了 Codex）、服务地址与实时统计。图：CC Switch 官方仓库

代价要说清楚：启用了本地代理，请求路径就多了一跳，排查问题时需要先判断是上游的问题还是本地代理的问题。好在开关是显式的，出问题可以直接关掉路由总开关回到直连。

4.3 MCP、Prompts 与 Skills 统一管理

MCP：一个面板管理 Claude、Codex、Gemini、Grok Build、OpenCode、Hermes 六个应用的 MCP 服务器，支持双向同步和 Deep Link 导入。
Prompts：带 Markdown 编辑器，能跨应用同步到 CLAUDE.md / AGENTS.md / GEMINI.md，并且有回填保护——不会把你手写的文件覆盖掉。
Skills：从 GitHub 仓库或 ZIP 一键安装，支持自定义仓库管理，同步方式可选软连接（省磁盘、实时同步）或文件复制（Windows 上更省事）。

4.4 用量与成本追踪

跨供应商追支出、请求数和 Token 用量，配趋势图表、逐条请求日志和自定义模型定价。对同时挂着多个供应商的人来说，这是把「这个月钱花哪了」变成可回答问题的功能。会话记录的扫描做了增量优化，大文件的解析速度在 3.20.1 里从秒级降到了毫秒级。

4.5 会话管理与工作区

可以浏览、搜索、恢复各工具的历史会话。OpenClaw 用户另有工作区编辑器，能直接编辑 AGENTS.md、SOUL.md 这类 Agent 文件并预览 Markdown。

4.6 系统集成

云同步：把配置目录挂到 Dropbox、OneDrive、iCloud、坚果云、NAS，或直接用 WebDAV 服务器同步，实现多机一致。
Deep Link：ccswitch:// 协议，用一条 URL 导入供应商、MCP、提示词或技能——适合团队分发统一配置。
日常项：深浅色主题、开机自启、自动更新、国际化（简中/繁中/英/日），以及一组解决首次安装登录确认、签名限制、插件同步等问题的「小工具」。

五、安装与升级

各平台路径都很常规，macOS 推荐 Homebrew：

brew install --cask cc-switch
brew upgrade --cask cc-switch # 升级

Windows 用 Releases 页的 .msi 或便携版 zip；Arch 用 paru -S cc-switch-bin；其他 Linux 发行版用 .deb / .rpm / .AppImage。macOS 包已经过 Apple 签名和公证，装完直接打开，不需要额外绕过 Gatekeeper。

回到开头那个版本号对不上的现象，它有个实际影响：别把 Homebrew 的版本号当成真实版本。因为 cask 带 auto_updates，应用会自己更新，brew list 显示的可能是几个月前的老数字。想知道当前版本，看应用界面更准。

升级路径上有一个需要留意的节点。3.20.x 这一轮里，3.20.1 带了数据库 schema 从 v17 到 v18 的迁移（升级前会自动备份，但如果要降级，必须用备份恢复）；同一版还调整了 Codex 的第三方切换机制，改成只写配置文件、不再动 auth.json，Codex 的 OAuth 账号需要重新登录一次。后面两个版本没有 schema 变更。

版本	日期	关键变化
3.20.1	08-28	适配 Codex CLI 0.149，切换改为「仅写配置」；同工作区多 ChatGPT 账号不再互相覆盖；DB schema v17→v18
3.20.2	09-07	Grok 走 xAI 原生 Responses API；恢复并行工具调用；修复提示词前缀缓存被破坏等问题
3.20.3	09-11	新增「禁用 Artifact 工具」开关；修复空 reasoning 占位符刷屏、Codex 长任务中途停止；无 schema 变更

六、边界与风险

任何工具的能力边界都值得写清楚，这个尤其。

它适合的：同时用两个以上 AI 编程 CLI、需要频繁在多个供应商之间切换、在多地多台机器上用同一套配置、或者想给团队分发统一配置的人。收益随工具数量和切换频率线性上升。

它不适合的：只用一家供应商、只用一个工具、配置写死就不动的人。这种情况下它的全部价值只剩一个可视化的配置编辑器，装它的必要不大。

风险一，也是最需要清醒对待的：预设列表不等于推荐列表。 内置的 50+ 预设里，有相当一部分是第三方 API 中转服务——这一点从 README 里占了大篇幅的赞助商区块就能直观感受到。CC Switch 的立场是中立的：它提供的是「方便地接入」这个能力，不对任何预设的模型质量、稳定性、计费透明度或合规性做背书。工具替你降低了切换成本，但没有替你承担选择成本。 用第三方中转意味着你的请求和密钥要经过第三方，这部分判断得自己做。

风险二，本地代理接管改变了请求路径。 排障时多一层变量，建议在真正依赖它之前先小范围试一次，确认故障转移的触发条件和日志能看懂。

风险三，配置文件的归属权冲突。 CC Switch 会写各工具的 live 配置文件。如果你另有脚本、dotfiles 管理工具或手工流程也在改同一份文件，两边会互相覆盖。原子写入和自动备份能防损坏，防不了逻辑冲突。

顺带一个冷知识，Linux + NVIDIA 用户可能会撞上：AppImage 默认强制走 XWayland，在较新的 Wayland + NVIDIA 环境下会出现界面点不动或缩放后黑屏。官方的逃生开关是 CC_SWITCH_GDK_BACKEND=wayland ./CC-Switch-*.AppImage。

七、我的判断

CC Switch 真正的价值，不在于「一键切换」这个动作节省的那几十秒，而在于它把散落在八个工具、三种格式里的配置，收敛成了一个有备份、有回滚、有单一事实源的本地管理层。

这个转变的意义在于：你开始可以回答「我现在到底在用哪套配置」这个问题了。在此之前，这个问题要靠翻四五个目录、比对若干份配置文件才能回答；现在它是一张卡片上的一行字。

值得提醒的是这个结论成立的前提：它成立，是因为你把多个工具和多个供应商当成常态来用。如果你的工作流只有一个工具加一个供应商，CC Switch 解决的是一个你并不存在的问题。工具的价值永远取决于它减掉的那部分复杂度，是不是真的存在于你的工作里。

总结

CC Switch 是给八个 AI 编程 CLI 做配置管理的开源桌面应用（Tauri 2 + Rust，MIT，13 万 star），配置管理层才是它的定位，供应商切换只是入口。
内部机制是 SQLite 单一事实源 + 设备级 JSON 双层存储、切换双向同步、原子写入、自动备份；设计上保证最小侵入，卸载不留坑。
六个功能模块里，本地代理与故障转移最重、也最需要理解成本；MCP / Prompts / Skills 的统一管理是日常使用中最省事的部分。
安装优先走 Homebrew 或官方包；升级注意 3.20.1 的数据库迁移和 Codex OAuth 需要重新登录一次；别信 brew list 的版本号，应用会自更新。
预设列表里有大量第三方中转服务，工具降低了切换成本，但没有降低判断该切到哪儿的成本——这部分始终要自己做。

它把「切换」这件事的成本压到了最低，剩下的成本，是你判断该切到哪儿的成本。

为 AI 而写的 CLI 设计指南：原则、避坑与难点

Thu, 10 Sep 2026 15:30:00 +0800

最近在给 FreshAI 写一个供 AI 操作外部能力的命令行工具，落地之后回头总结，发现它和「给人用的 CLI」几乎是两套设计哲学。传统 CLI 是给一个坐在 tty 前、能看进度、会按 y/n 的人设计的；而 Agent 看不到屏幕，它只能拿到两样东西：stdout 的字节流和进程退出码。一旦这两样东西被污染或语义不清，Agent 就会「飞盲」——重试已经成功的操作、放弃其实失败了的操作，或者把一段散文当数据去解析。

这篇文章把我踩过的坑整理成一套可复用的设计准则，骨架来自 FreshAI CLI（packages/fresh-cli，唯一依赖 httpx 的独立 Python 包），并对照 Agent CLI Guidelines、12 Factor CLI Apps、clig.dev 这些公开规范。核心心法只有一句：

把 CLI 当成一个「传输层是 argv / stdout / 退出码」的 RPC 接口，人只是其中一个调用方。

一、为什么 Agent 时代 CLI 又重要了

Agent 天生会用 CLI。 LLM 的训练语料里有大量 shell 命令，它对 git submodule add、pip install 这类「动词-名词」结构有很强的先验。相比之下，让 Agent 现学一个私有 SDK 的调用姿势，要额外喂文档、额外占上下文。
CLI 是最省 token、最可组合的能力接口。 不需要常驻进程、不需要握手协议，一个 exec 就能调用；输出可以裁剪到 Agent 真正需要的字段。
但传统 CLI 的三条默认行为，恰好都是 Agent 的天敌： ①默认交互、②进度和结果混在一起打印、③错误只给人看。

所以「为 AI 写 CLI」不是发明一套新东西，而是把 CLI 里那些给机器看的契约显式化、稳定化。

二、设计原则：到底该怎么写

2.1 默认非交互（non-interactive by default）

Agent 没有 tty，任何 input() / confirm() / 分页器都会把它卡死直到超时。FreshAI CLI 的做法是：

只有显式命令进入交互流程。 全部命令里，只有 fresh login 会打开浏览器，其余命令一律非交互。
危险操作不靠「逐次确认」保护，而靠「独立命令 + 最小权限」。 「直接公开发布」不是给草稿命令加一个 --yes，而是一条独立命令 fresh blog publish，并且在登录授权时就必须单独拿到 blogs:publish scope。这样 Agent 的「公开」意图是可审计、可拒绝的，而不是被一个交互弹窗挡住的。

这是 12 Factor CLI Apps 第 7 条（stdin 不是 tty 时也必须能跑完）在 Agent 场景下的强化版：交互是例外，不是默认。

2.2 stdout 只放结果，stderr 只放诊断

这条老规矩在 Agent 场景里是生死线。Agent 往往直接 json.loads(stdout)，你混进一行「正在上传…」，解析立刻崩。

FreshAI CLI 的分工：

通道	内容
stdout	最终结果：`--json` 时是唯一的 envelope；文本模式是正文或结果行
stderr	进度、提示、诊断、`request-id`、健康检查详情、中断消息

实现上就两个函数，所有输出都必须走它们，不允许 print() 裸奔：

def _emit_progress(message: str) -> None:
 """输出脱敏进度信息到 stderr。"""
 print(message, file=sys.stderr)

def print_json_envelope(payload: dict) -> None:
 """把 envelope 以 UTF-8 JSON 写到 stdout（单行结束，无多余日志）。"""
 json.dump(payload, sys.stdout, ensure_ascii=False, indent=2)
 sys.stdout.write("\n")
 sys.stdout.flush()

注意 flush()：Agent 常常边读边解析，缓冲没冲出去就是「命令卡住」的经典假象。

2.3 结构化输出 + 版本化 schema

成功的输出和失败的输出必须是同一个形状，这样 Agent 只需要一个解析器：

{
 "schema_version": 1,
 "ok": true,
 "result": { },
 "error": null,
 "request_id": "…"
}

失败时 ok=false, result=null，把细节放进 error：

{
 "schema_version": 1,
 "ok": false,
 "result": null,
 "error": {
 "code": "scope_denied",
 "message": "当前凭证缺少 blogs:publish 授权",
 "http_status": 403,
 "execution_status": "not_started"
 },
 "request_id": null
}

三个细节值得强调：

schema_version 是给未来留的活路。 字段只增不改不删（append-only contract），Agent 脚本就不会因为一次升级集体失灵。
error.code 是 string，不是 HTTP 状态码的复读。 invalid_input / login_required / authorization_expired / scope_denied / not_found / request_conflict / resource_state_changed / network_error / protocol_error 这些码才是 Agent 分支判断的依据。
Token-bounded。 列表命令默认分页（--limit 1-100、--offset），不要把几千行喷进 Agent 的上下文窗口——上下文是它最贵的资源。

2.4 语义化退出码，并写进文档

Agent 可以只读退出码就决定下一步，不必解析正文。FreshAI CLI 的约定：

退出码	含义
0	成功
2	本地输入 / 配置错误（未联网）
3	登录 / 授权错误
4	资源 / 冲突 / 其他 HTTP 错误
5	网络 / 超时
6	协议或凭证落盘错误
130	用户中断（128 + SIGINT）

两个坑：

argparse 出错时默认就 exit 2，正好可以复用来表达「本地输入错误」，但你要知道它是 2，别让它和你自定义的码打架。
130 是 128+SIGINT 的惯例，Ctrl+C 中断应显式返回 130，而不是 1，否则脚本无法区分「被打断」和「执行失败」。

2.5 错误要「可迁移、可恢复」，并且脱敏

好的错误信息同时服务两种读者：

给人看： message 说清楚发生了什么；
给程序看： code + http_status + execution_status 让 Agent 能自动纠错。

同时，错误输出是泄密高发区。服务端可能返回一整页 HTML、异常堆栈里可能带 token、正文可能出现在报错里。这类内容一律不能回显：

def _extract_error_message(response: httpx.Response) -> str:
 """从错误响应中提取脱敏说明；不回显服务端 HTML 或原始异常。"""
 try:
 payload = response.json()
 except ValueError:
 body_text = (response.text or "").strip()
 if body_text.startswith("<"):
 return f"HTTP {response.status_code}：服务端返回了非 JSON 响应"
 ...

跨层映射也要固定下来，Agent 才能预测：401→登录类、403→scope/授权类、404→not_found、409→冲突类、5xx/429→网络类。

2.6 幂等：所有写操作的第一公民

为什么 Agent 特别需要幂等？ 因为它会重试。超时了重试、进程被 kill 了重试、并发调度重试——人手动敲命令很少连敲两次，Agent 会。没有幂等键，就是重复发文章、重复下单、重复扣款。

FreshAI CLI 的做法：客户端生成一个 UUID 请求编号，作为 Idempotency-Key 发给服务端，并且在请求发出前就把它打到 stderr、留在错误里：

print(f"request-id: {resolved_request_id}", file=sys.stderr)
# …
extra_headers={"Idempotency-Key": idempotency_key}

服务端按 (author, request_id) + 内容摘要去重，语义必须明确写清楚：

情况	服务端行为
同编号 + 同内容 + 目标状态未变	返回原结果，`replayed=true`，不新建
同编号 + 不同内容 / 不同模式	`409 request_conflict`，不覆盖
同编号但原稿已发布 / 已删除	`409 resource_state_changed`，不复活、不自动公开

这样「重试」就变成了安全操作。反过来，如果 CLI 每次重试都生成新编号，幂等就形同虚设——这一点下面「难点」还会展开。

2.7 区分「失败」和「结果未知」

这是全篇最重要、也最容易做错的一点，值得单列一节，我放在第三部分重点讲。

2.8 配置解析要有确定的优先级

环境一多，站点/后端地址就会飘。FreshAI CLI 把解析顺序定死，并且让 doctor 命令把来源也报出来：

--server > 进程环境变量 DOMAIN > .env.local > .env > 已保存的唯一站点凭证

两条纪律：

全部缺失时，在联网前就报 invalid_input（退出码 2），绝不连接到未知站点。
绝不静默回退。 显式给了无效值就报错；本地存了多个站点就要求显式指定，不「猜」一个。

2.9 认证：让 Agent 能无人值守登录，但密钥不进 argv / history

永远不要提供 --token 参数。 命令行会进入 shell history、进程列表（ps）、CI 日志。FreshAI CLI 明确「无明文 --token 参数」。
用设备码授权（RFC 8628 风格）：CLI 创建挑战 → 用户在浏览器确认 → CLI 按 interval 轮询、领取只出现一次的 token → 原子写入本地凭证文件。
最小权限 + 有效期 + 可撤销 + 不自动续期。 scope 分开（drafts:create / drafts:read / publish），30 天到期，网页可逐台撤销。
必须给一条无头路径。 fresh login --no-browser 只打印 URL 和核对码，方便在别的设备/无 GUI 环境完成授权。

2.10 本地先校验，未联网前拒绝非法输入

能本地判定的错误，就别浪费一次网络往返，更别让它产生半成品远程状态。FreshAI CLI 在打包阶段就把这些挡掉（退出码 2）：

标题为空；--file 与 --package 同时给；
文件不是合法 UTF-8；内容全空白；
超过大小上限（Markdown ≤ 1 MiB、HTML ≤ 2 MiB、ZIP ≤ 20 MiB）；
--request-id 不是合法 UUID；--file 误传 .zip（提示改用 --package）。

2.11 命令树与命名：一致性 > 聪明

动词-名词分层，和 git 一致：fresh blog draft create / fresh blog draft get <id> / fresh blog draft list / fresh blog publish。
参数命名要全链统一。 这一条是用真实返工换来的：初版写成了 --site，与规格里的 --server 不一致，最后从参数、args、帮助文案、报错文案到测试和文档全部更名了一遍。
帮助即文档。 prog、description、每个参数的 help 都写清楚，让 Agent（通过 --help）能自学命令树。

三、重点与难点拆解

难点一：「结果未知」——网络失败不等于操作失败

现象： 一个创建文章的请求发出去，读响应时超时了。这次创建到底成功了没有？——不知道。

如果 CLI 简单地把超时当「失败」，Agent 会：

认为文章没发出去 → 重发 → 如果第一次其实成功了，就产生了重复；
或者反过来，Agent 以为成功了，实际服务端根本没收到。

正确做法：把「请求执行状态」提升为一等公民。

EXECUTION_COMPLETED = "completed" # 已知结果
EXECUTION_UNKNOWN = "unknown" # 已发出，结果未知
EXECUTION_NOT_STARTED = "not_started" # 本地拒绝，没发出

关键在区分「连接阶段失败」和「发送后失败」：

except (httpx.ConnectError, httpx.ConnectTimeout) as exc:
 # 连都没连上，请求肯定没送达
 raise TransportError("无法连接 …", sent=False, timed_out=True)
except httpx.TimeoutException as exc:
 # 发出去了但没等到响应，可能已经成功
 raise TransportError("请求超时 …", sent=True, timed_out=True)

然后对「结果未知」给出可执行的重试指令，而不是一句「失败了」：

if transport_failure.sent:
 retry_hint = (
 f"请求已发送但结果未知，请用相同命令与相同编号重试：--request-id {request_id}"
 "（不要切换 draft/publish 模式）。"
 )
 execution_status = EXECUTION_UNKNOWN

5xx 也一样处理：服务端 500 可能是写了一半，属于结果未知，不能当作确定失败。

这条原则的价值：错误分类错一档，Agent 的决策就错一个方向。区分 not_started（可安全重发）和 unknown（必须原编号重试）是「Agent 敢用这个 CLI」的前提。

难点二：幂等的边界是一个状态机

幂等键不是「查一下有没有就返回」那么简单，资源会变状态：草稿会被网页发布成公开文章、会被删除。此时同编号的旧请求该怎么答？答案是冲突，而不是复活或覆盖：

draft --(网页 publish)--> published --(不可逆)--> 公开文章
draft --(网页 delete)--> deleted --(不可恢复)

原稿还在草稿态 → 同编号同内容重放，返回原 id；
原稿已发布/已删除 → 409 resource_state_changed，不复活、不自动公开、不改动已公开文章。

同时，网页端的操作和 CLI 的创建请求可能并发，必须保证「同一状态转换只有一方成功」。这套状态机（而不是「有就返回」）才是真正可用的幂等。

难点三：凭证存储的原子性与权限

本地凭证文件里是明文 token，一旦损坏或权限过宽就是事故。要做到：

目录 0700、文件 0600，读取时校验权限，过宽直接拒绝（CredentialStoreError）；
原子写入：同目录临时文件 → fchmod → write → flush → fsync → os.replace，任何一步失败都清理临时文件、不破坏既有文件；
拒绝损坏内容，而不是静默返回空凭证（否则用户会莫名「被登出」）；
支持 FRESH_HOME 重定向，这是让测试隔离真实 ~/.fresh 的关键（下面测试部分会用到）。

descriptor, temporary_name = tempfile.mkstemp(dir=str(credentials_path.parent), …)
try:
 os.fchmod(descriptor, CREDENTIALS_FILE_MODE)
 with os.fdopen(descriptor, "w", encoding="utf-8") as fh:
 json.dump(all_credentials, fh, ensure_ascii=False, indent=2, sort_keys=True)
 fh.flush()
 os.fsync(fh.fileno())
 os.replace(temporary_name, credentials_path)
except BaseException:
 os.unlink(temporary_name) # 失败不留垃圾，也不动旧文件
 raise

难点四：超时要分层

一个 timeout 值打天下是不行的：

连接超时和读超时语义不同（前者可安全重试）；
创建/发布类请求要传文件、服务端要解包落库，只读请求则应该快速失败。FreshAI CLI 给创建类 120s 总墙钟、只读 10s；
Agent 侧还得有自己的调用超时，且要大于 CLI 超时，否则 Agent 先把 CLI 杀了，就永远拿不到 unknown 这个语义。

难点五：轮询类交互的细节

设备码登录是一条长时间、可能抖动的轮询链路，几个坑：

必须尊重服务端给的 interval，过快会被回 slow_down，要顺延并退避；
要有总截止时间（expires_in，默认 10 分钟），到点报 authorization_expired；
网络抖动不等于授权失败，应打印进度并继续轮询，而不是直接退出；
token 只发放一次，已领取再轮询要报「请重新登录」而不是重复发；
领取成功后落盘失败，要尽力撤销刚拿到的授权，否则会留下一份「用户以为没登录、服务端却存在」的僵尸凭证。

难点六：分发与版本一致性（一个真金白银的坑）

CLI 源码改了，但分发的 wheel 版本号没变（一直是 0.1.0），会发生什么？uv 看到 URL 和版本都没变，直接用缓存里的旧构建——你改了代码，用户装到的还是旧的，而且毫无报错。

规避方式：

改源码后必须重新构建并提交 wheel，让分发产物与源码一致；
从站点安装时显式强制刷新：uv tool install --reinstall --refresh "<wheel URL>"；
wheel URL 必须以真实文件名（.whl）结尾，uv 才认，所以先查元信息端点再拼 URL；
更好的做法是让版本号真正随发布递增，而不是恒定。

再往上一层是更新机制本身的设计，对 Agent 场景有两条特殊纪律：

不要做静默自动更新。 人用 CLI，更新后行为变了会自己发现；Agent 的脚本是按当次 --help/契约写的，后台悄悄换版本等于脚本脚下抽地板。正确姿势：提供 --version，可以启动时提示「有新版本」，但升级必须由调用方显式触发。
升级必须遵守 append-only contract。 旧脚本依赖的命令、参数、退出码、JSON 字段一个都不能变、不能删、不能改语义——否则每次更新都是一次全量脚本回归。schema_version 与版本提示配合，让 Agent 能感知并自行决定是否迁移。

难点七：测试策略——契约测试 + 真实入口 E2E

Agent 驱动的 CLI 出错代价高，测试要分两层：

① 契约测试（快，不发真实网络）。 用 httpx.MockTransport 注入假响应，验证 envelope 形状、错误码映射、退出码、站点解析、打包逻辑。关键是把副作用隔离掉：

@pytest.fixture(autouse=True)
def isolated_home(tmp_path, monkeypatch):
 monkeypatch.setenv("FRESH_HOME", str(tmp_path / "fresh-home")) # 别碰真实 ~/.fresh
 monkeypatch.delenv("DOMAIN", raising=False)
 monkeypatch.chdir(tmp_path)

@pytest.fixture(autouse=True)
def no_real_sleep(monkeypatch):
 monkeypatch.setattr("time.sleep", lambda seconds: None) # 跳过轮询等待

@pytest.fixture(autouse=True)
def no_real_browser(monkeypatch):
 monkeypatch.setattr(cli_auth.webbrowser, "open", lambda *a, **k: True)

② 真实入口 E2E（慢，但不可省）。 用真实浏览器走授权页、真实 CLI 子进程（从 wheel 安装、cwd 在仓库外、HOME 隔离、不传 --server 走主路径解析），验证「安装 → 登录 → 草稿 → 发布 → 撤销」的完整闭环。只测 mock 的 CLI 会在真实授权页、真实 CSP、真实跳转上翻车。

四、避坑清单（速查表）

#	坑	症状	正确做法
1	默认交互	Agent 卡在确认/分页，直到超时	默认非交互，交互只留给显式命令
2	进度写 stdout	`json.loads(stdout)` 失败	进度/日志一律 stderr
3	JSON 模式混入人类文案/彩色	解析器被 emoji、ANSI 码带偏	JSON 模式只输出一个 envelope
4	直接抛 traceback	Agent 读到一堆栈，无法纠错	结构化 `error.code` + 可执行建议
5	明文 `--token`	进 shell history / ps / CI 日志	设备码授权，token 只经本地凭证
6	把超时当失败	重复副作用（重复发文）	区分 `not_started` / `unknown`
7	忽略幂等	重试即重复写	`Idempotency-Key` + 状态机
8	静默切换站点/环境	写错环境，且无人察觉	优先级固定，缺失即报错
9	退出码随手写	脚本无法分支	语义化并写进文档，`Ctrl+C` 用 130
10	错误里带 secret/正文	泄密	错误脱敏，不回显 HTML/异常原文
11	只读命令也强制登录	`doctor` 之类无法排障	只读诊断不要求身份校验
12	凭证权限 0644	明文 token 被同机他人读取	目录 0700、文件 0600，原子写
13	跟随重定向跨 origin	串站/SSRF，写错站点	关闭自动重定向，校验同 origin
14	wheel 版本恒定	改了源码，用户装到旧构建	重建并提交 wheel，`--reinstall --refresh`
15	CLI import 后端内部代码	耦合重、装不上、版本打架	独立包，只依赖 HTTP 客户端
16	人类表格和机器输出共用一条路径	机器解析人类排版	`--json` 与文本模式分路
17	分页缺失/无上限	列表撑爆上下文	`--limit`/`--offset`，默认有界
18	只按扩展名判定内容格式	`.htm` / 无扩展名的 HTML 被静默当 Markdown 发成字面文本	内容嗅探（`<!doctype html`）兜底，或对可疑组合给出警告

五、一个最小骨架

把上面的原则压成一个可以直接抄的骨架（Python + argparse + httpx）：

# output.py —— 输出契约与退出码
SCHEMA_VERSION = 1
EXIT_OK, EXIT_LOCAL_INPUT, EXIT_AUTH = 0, 2, 3
EXIT_HTTP, EXIT_NETWORK, EXIT_PROTOCOL, EXIT_INTERRUPTED = 4, 5, 6, 130


class CliError(Exception):
 def __init__(self, code, message, *, http_status=None,
 execution_status="completed", exit_code=EXIT_HTTP, request_id=None):
 super().__init__(message)
 self.code, self.message = code, message
 self.http_status, self.execution_status = http_status, execution_status
 self.exit_code, self.request_id = exit_code, request_id


def success_envelope(result, *, request_id=None):
 return {"schema_version": SCHEMA_VERSION, "ok": True, "result": result,
 "error": None, "request_id": request_id}


def error_envelope(error: CliError):
 return {"schema_version": SCHEMA_VERSION, "ok": False, "result": None,
 "error": {"code": error.code, "message": error.message,
 "http_status": error.http_status,
 "execution_status": error.execution_status},
 "request_id": error.request_id}


# main.py —— 统一错误出口
def main(argv=None) -> int:
 args = build_parser().parse_args(argv)
 try:
 return _dispatch(args)
 except CliError as error:
 _emit_cli_error(error, as_json=bool(getattr(args, "json", False)))
 return error.exit_code
 except KeyboardInterrupt:
 print("已中断", file=sys.stderr)
 return EXIT_INTERRUPTED

配套的 _emit_cli_error / print_json_envelope 记住两条：JSON 模式走 stdout，文本模式走 stderr；进度永远 stderr。

六、交付前自检清单

默认非交互；危险操作靠「独立命令 + 最小 scope」，而不是交互确认
stdout 只有结果，stderr 只有诊断；JSON 模式不混入人类文案
统一 envelope + schema_version，成功/失败同形状
退出码语义化、已文档化，Ctrl+C 返回 130
所有写操作幂等：request-id / Idempotency-Key，并定义重放/冲突/状态变更语义
严格区分 completed / unknown / not_started，对 unknown 给出原编号重试指令
错误脱敏，不回显 token、正文、服务端 HTML、原始异常
配置优先级明确且可诊断；缺失时联网前报错；不静默回退
无明文 --token；支持无头/设备码登录；凭证 0600 原子写
本地输入校验（编码、空值、大小、互斥、格式）先于联网
列表有界（分页/limit），不撑爆上下文
契约测试用 mock transport + 隔离 HOME；E2E 走真实入口
分发产物（wheel）版本与源码一致

参考

Agent CLI Guidelines（aclig.dev） —— 面向 Agent 的十条不变量：只读默认、自描述、有界输出、注入防护、可无头认证、只增契约等
12 Factor CLI Apps（Heroku / JDX） —— 帮助、flags、stdout/stderr、错误处理、XDG
clig.dev —— 命令行界面设计通用准则
RFC 8628：OAuth 2.0 Device Authorization Grant —— 设备码授权
FreshAI CLI 源码：packages/fresh-cli/src/fresh_cli/（main.py / output.py / client.py / credentials.py / config.py / blogs.py / auth.py）

copier-using

Fri, 12 Sep 2025 15:26:16 +0800

Copier 是什么？

Copier 是一个用于创建和管理项目文件的现代化命令行工具。你可以把它理解为一个强大的“复制粘贴”工具，但它远不止于此。它能根据一个预设的“模板”（template），智能地生成一个新项目，并且在模板更新后，还能将这些更新应用到你已生成的项目中。

它在软件开发领域非常受欢迎，尤其适合用于搭建标准化的项目初始结构，也就是我们常说的“脚手架”（scaffolding）。

核心特性：

项目生成 (Project Generation): 从一个模板快速生成一个新项目。在生成过程中，它会向你提问（例如，项目名称、作者、选择特定功能等），然后根据你的回答填充模板中的变量。
项目更新 (Project Updates): 这是 Copier 相较于其前辈（如 Cookiecutter）最大的优势。当模板本身有了改进或修复（比如，升级了依赖库、修复了安全漏洞），你可以使用 Copier 将这些变更安全地同步到已经生成的项目中，而不会覆盖你自己的代码。
动态与交互式: 通过一系列问题引导用户完成项目配置，并将答案记录在 .copier-answers.yml 文件中，方便未来更新。
版本控制友好: 它与 Git 紧密集成，能很好地处理版本变更和代码合并。
跨平台与语言无关: Copier 本身由 Python 编写，但它可以为任何编程语言（Go, Rust, JavaScript, Python 等）创建项目模板。

简单来说，Copier = 项目脚手架 + 持续更新能力。它解决了传统脚手架工具“一次性生成，后续维护困难”的痛点。

Copier 使用教程

下面，我们将从安装、创建项目、更新项目等环节，一步步教你如何使用 Copier。

1. 安装 Copier

首先，你需要一个 Python 环境。然后使用 pip 或 pipx（推荐）来安装 Copier。pipx 可以将 Copier 安装在独立的环境中，避免污染全局 Python 环境。

使用 pipx (推荐):

# 安装 pipx
python -m pip install --user pipx
python -m pipx ensurepath

# 使用 pipx 安装 copier
pipx install copier

使用 pip:

pip install copier

安装完成后，你可以通过以下命令验证是否成功：

copier --version

2. 从模板创建新项目 (`copier copy`)

Copier 的核心是模板。模板通常是一个 Git 仓库。我们以一个官方推荐的 Python 项目模板为例。

命令格式:

copier copy <模板地址> <你的项目文件夹名称>

实战演练:

假设我们要创建一个名为 my-awesome-project 的新项目。

copier copy gh:copier-org/copier-python-template my-awesome-project

gh:copier-org/copier-python-template 是模板的简写地址，它指向 GitHub 上的 copier-org/copier-python-template 仓库。你也可以使用完整的 https://github.com/copier-org/copier-python-template.git 地址。

执行命令后，Copier 会开始与你交互，提出一系列问题来配置项目：

🎤 What is your project name?
 (Default: My Awesome Project)
└──> My Super FastAPI App # 输入你的项目名

🎤 What is your project description?
 (Default: Awesome project, created with copier-python-template)
└──> A demo project for learning Copier. # 输入描述

... (后续还会有作者、邮箱、选择许可证等问题)

你只需要根据提示回答问题即可。回答完毕后，Copier 会做两件事：

在当前目录下创建一个 my-awesome-project 文件夹。
文件夹内包含了根据你的回答生成的所有项目文件。
同时，文件夹里还会有一个特殊的 .copier-answers.yml 文件，它记录了你刚才的所有回答。这个文件非常重要，是未来项目更新的关键！

.copier-answers.yml 文件示例:

# Changes here will be overwritten by Copier
_commit: v0.2.2
_src_path: gh:copier-org/copier-python-template
author_email: your_email@example.com
author_name: Your Name
project_description: A demo project for learning Copier.
project_name: My Super FastAPI App
...

3. 更新现有项目 (`copier update`)

这是 Copier 的“杀手级”功能。假设一段时间后，copier-python-template 模板的作者发布了一个新版本，修复了一些 Bug 并增加了一些新功能。你想把这些更新应用到你的 my-awesome-project 中。

操作非常简单：

首先，进入你的项目目录：

cd my-awesome-project

然后，执行更新命令：

copier update

Copier 会自动执行以下步骤：

读取 .copier-answers.yml 文件，找到原始模板地址和上次生成时的版本。
检查模板仓库是否有新版本。
使用你之前回答过的答案，重新生成一份最新的项目文件。
将新生成的文件与你当前的项目文件进行对比，并尝试智能合并。

在合并过程中，如果遇到冲突（例如，模板的某个文件和你自己修改过的文件内容不一致），Copier 会生成标准的 .rej 冲突文件，或者如果你在 Git 仓库中，它会产生 Git 冲突标记，让你手动解决。

更新时的注意事项:

强烈建议在执行 copier update 前，确保你的项目已经提交到 Git。这样即使更新出现问题，你也可以轻松回滚。
Copier 会尽力保留你自己的代码，但最佳实践是，尽量不要修改由模板直接生成且预计会频繁更新的配置文件（除非你清楚自己在做什么）。

4. 创建自己的模板

如果你想创建自己的项目模板，也非常简单。

创建一个标准的项目结构。例如，一个包含 README.md, .gitignore, src/ 等文件的项目。
将需要动态替换的内容改为 Jinja2 语法。
- 文件名可以包含变量，例如 {{ project_name }}/main.py。
- 文件内容也可以包含变量，例如 README.md 中可以这样写：
```
# {{ project_name }}

{{ project_description }}
```

创建一个 copier.yml (或 copier.yaml) 文件。这个文件用来定义 Copier 需要向用户提出的问题。

copier.yml 示例:

# 定义问题
project_name:
 type: str
 help: What is your project name?

project_description:
 type: str
 help: What is your project description?
 default: "A cool project."

# 定义模板渲染后要执行的命令
_tasks:
 - git init
 - git add .
 - git commit -m "Initial commit from copier template"

这里定义了两个问题：project_name 和 project_description。用户在生成项目时回答的答案会分别赋值给这两个变量。

将模板推送到 Git 仓库（如 GitHub），然后你就可以像之前一样使用 copier copy 来从你的模板创建新项目了。

总结

对于使用者: Copier 是一个能让你轻松使用标准化项目模板并保持模板同步更新的强大工具。只需 copier copy 创建和 copier update 更新。
对于模板维护者/团队: Copier 是统一团队技术栈、规范项目结构、分发最佳实践的利器。通过维护一个中央模板，所有团队成员都可以快速启动项目并享受持续的模板升级。

你最开始提到的那个脚本，正是在 Copier 这个大生态系统下的一个自动化辅助工具。它解决了 .env 文件通常不适合使用 Jinja2 模板直接渲染的问题，通过在 Copier 更新后运行脚本，间接地将 .copier-answers.yml 中的配置同步到 .env 文件中，实现配置的无缝更新。这正是 Copier 强大扩展性的体现。

VScode使用教程|cursor使用教程

Mon, 03 Mar 2025 00:00:00 +0800

参考： https://blog.csdn.net/weixin_46474921/article/details/132841711

安装及设置

1. 下载安装

VScode官网注意，这一步最好全部打勾

2. 设置默认terminal为cmd

自动fetch远程分支

Git 默认不会自动从远程拉取状态更新。只有当你显式运行 git fetch 或 git pull 时，本地仓库才会更新远程分支引用。如果你希望在 VS Code / Cursor 中自动感知远程分支变化，需要开启自动 fetch：

设置路径：Settings → 搜索 git.autofetch → 勾选启用

建议同时设置自动 fetch 间隔（默认 3 分钟）：

{
 "git.autofetch": true,
 "git.autofetchPeriod": 180
}

注意：如果仓库的 remote 名不是默认的 origin，VS Code 的 Git 插件和 GitHub Pull Requests 插件可能无法正确识别上下文。需要在 settings.json 中显式配置：

{
 "githubPullRequests.remotes": ["zata", "origin", "upstream"]
}

配置完成后执行 Cmd+Shift+P → Developer: Reload Window 生效。

设置文件自动保存

vscode右侧的预览窗口设置

设置方法，在设置里面搜索minimap

vscode写markdown插入图片时放在指定目录

参考 https://juejin.cn/post/7244809769794289721

打开粘贴选项

**/*.md images/${documentDirName}/${fileName} # 以原始文件名放到 ./assets/<md文件名>/<图片文件名>
**/*.md images/${documentBaseName}/${documentBaseName}.${fileExtName} # 重新以md文件名命名图片名
**/*.md images/${documentBaseName}/image.${fileExtName} # 以image.png重命名放到images/文件名 文件夹下

vscode折叠代码 ctrl+k ctrl+0

Diff Editor settings

取消相同的代码被折叠

diff 双栏变一栏

vscode 插件

GitLG
Office Viewer
Markdown Preview Mermaid Support

GitLG
office viewer

但是有一个非常严重的问题，就是说如果安装了office viewer 会导致vscode自己的image paste失效

不过我发现一个解决方案，就是改下配置，然后不要用ctrl+v粘贴，而是用鼠标右键然后paste

当然，如果想支持更多办公文档的查看，那么可以一步到位，直接安装office viewer(Markdown Editor)。但这个插件有一个坑点，就是会更改markdown文件的格式，所以安装之后，可以取消对markdown文件的默认开启方式。方法很简单，只需右键单击一个markdown文件，选择打开方式，在命令栏中选择最下面的为*.md配置默认编辑器，最后点击文本编辑器就可以了。

此外，这个插件内嵌了一个主题，所以安装之后界面的颜色可能会发生变化，不必惊慌，重新选择一个主题就可以了。

Markdown Preview Mermaid Support（作者：Matt Bierner）特点：这是下载量最高、最基础的 Mermaid 插件。安装后，它会无缝集成到 VS Code 原生的 Markdown 预览功能中。用法：在 .md 文件中输入 ```mermaid 代码块，然后点击 VS Code 右上角的“预览”按钮（或快捷键 Ctrl+Shift+V / Cmd+Shift+V），就能直接在右侧看到渲染出的图表。

遇到的问题和解决方案

vscode 一直 reactivatiing terminals

这个是由于python扩展找不到虚拟环境的问题，具体可以看 https://stackoverflow.com/questions/78886125/vscode-python-extension-loading-forever-saying-reactivating-terminals/78886126#78886126

我的解决方法是把python Locator换成js

安装工具包之后，桌面cmd窗口可用，但是vscode/cursor不可用

cmd加载成功，但是 cursor ternimal没有生效。解决办法：完全退出cursor，然后重启cursor

GitHub Pull Requests 插件一直 Loading

现象：安装 GitHub Pull Requests and Issues 插件后，VS Code 侧边栏一直处于 loading 状态，无法正常显示当前仓库的 PR。

优先检查三个点：

git remote -v
gh auth status
gh pr list --repo OWNER/REPO --state all --limit 10

这次遇到的原因是仓库 remote 名不是默认的 origin，而是自定义的 zata。VS Code 的 GitHub PR 插件默认主要识别 origin 和 upstream，如果仓库使用了其他 remote 名，插件可能找不到 GitHub 仓库上下文，于是一直 loading。

解决方法：在 VS Code 的 settings.json 中显式配置插件要识别的 remote 名：

"githubPullRequests.remotes": [
 "zata",
 "origin",
 "upstream"
]

然后执行：

Cmd+Shift+P
Developer: Reload Window

如果还是 loading，打开下面这个输出面板看具体报错：

View -> Output -> GitHub Pull Requests

另外要注意：如果 PR 已经 merge，插件的 open PR 列表里可能不会显示。可以用命令确认：

gh pr list --repo OWNER/REPO --state all --limit 10
gh pr view PR_NUMBER --repo OWNER/REPO

macOS 下按 Cmd+Q 直接退出 VSCode

在 macOS 上使用 VSCode / Cursor 时, 按下 Cmd+Q 会触发 macOS 的"退出应用"快捷键, 直接把整个 VSCode 进程关掉 (而不是仅关闭当前窗口), 容易丢失未保存的内容。

解决方法是在 VSCode 的快捷键设置里把 Cmd+Q 绑定的命令移除或改成无害操作:

打开 Cmd+K Cmd+S (Keyboard Shortcuts) 或者 File → Preferences → Keyboard Shortcuts。
搜索 cmd+q 或 Quit, 找到 Quit / workbench.action.quit 这一项。
双击该项, 选择 Remove Keybinding (删除快捷键), 或者改成 Cmd+Q 之外的其他组合 (比如改成 Cmd+Shift+Q 之类的)。

也可以直接编辑 keybindings.json (命令面板 Preferences: Open Keyboard Shortcuts (JSON)), 写入:

[
 {
 "key": "cmd+q",
 "command": "-workbench.action.quit"
 }
]

加负号 - 表示解除该命令的快捷键绑定。保存后重启 VSCode 生效, 此后按 Cmd+Q 不会再退出 VSCode, 只会由 macOS 提示要不要退出 (或者完全没反应), 避免误触丢工作内容。