Loong

提问的智慧：怎样提出容易得到答案的技术问题

Thu, 24 Sep 2026 16:00:00 GMT

本文是对 Eric S. Raymond 与 Rick Moen 的 How To Ask Questions The Smart Way 的归纳与改写，参考了《提问的智慧》简体中文版。示例和模板为本文新增，并非原文翻译。

一个好问题，不是把困难扔给别人，而是把目标、现象、证据和已做的尝试整理好，让别人能迅速判断：问题是什么、卡在哪里、怎样帮你最有效。

从遇到问题到得到答案

flowchart TD
    A[遇到问题] --> B[写清真正目标与实际现象]
    B --> C[搜索文档、FAQ、已有讨论与报错]
    C --> D[动手验证，尽量缩小复现范围]
    D --> E{已经解决？}
    E -- 是 --> F[记录解法，结束]
    E -- 否 --> G[选对项目、社区或同事]
    G --> H[写出可复现、可回答的问题]
    H --> I[根据回复补充信息并验证]
    I --> J[公开补充最终原因与解法]

这套流程的目的不是规定提问前必须独自耗尽所有办法，而是避免让回答者重新做一遍你已经做过的排查。说明自己查过什么、试过什么、发现了什么，往往比写一句“求助”更有用。

提问前：先弄清自己要解决什么

先说目标，再说卡住的做法。 例如，真正的目标是“正确解析 CSV 文件”，却只问“怎样删除字符串里的逗号”，回答者可能会帮你实现一个会破坏带引号字段的做法。交代目标，别人才有机会指出更合适的路径。

接着做三件事：

搜索完整报错、官方文档、FAQ、已有 issue 或讨论；必要时读相关源码。
自己运行一次可控的实验，找出触发问题的最少步骤、输入或代码。
找合适的地方问：项目自身的问题去项目渠道，语言或框架问题去对应社区，内部系统问题找掌握上下文的人。

提问时：让对方一次看懂

一个技术问题通常需要以下信息。按重要程度写，能省略的就省略：

信息	应该写什么
标题	技术或功能、具体症状、触发条件；避免“救命”“出错了”
目标	你最终想实现什么，而不只是当前尝试了哪一步
预期与实际	原本希望发生什么，实际发生了什么
复现步骤	从什么环境和输入开始，依次做了什么
证据	关键报错、相关日志、最小复现代码；只贴与问题有关的部分
已做尝试	查过什么、试过什么、每次得到什么结果
具体请求	希望别人帮你判断原因、指出排查方向，还是检查某段代码

描述观察到的症状，并把“我怀疑是缓存导致的”标成猜测。不要把未经验证的原因写成事实。代码问题尽量提供能重现异常的短例子；数百行代码加一句“不能运行”，通常让人无从下手。

一个对照示例

难以回答：

Python 排序报错，怎么修？急！

更容易回答：

标题： Python 3.12 中按时间戳排序时，含 None 的记录触发 TypeError

我想按 created_at 时间戳升序排列记录，并把缺少时间戳的记录放在最后。数据里有 None；运行下面的最小例子会报错：
records = [{"created_at": 3}, {"created_at": None}, {"created_at": 1}]
sorted(records, key=lambda item: item["created_at"])
实际报错是 TypeError: '<' not supported between instances of 'NoneType' and 'int'。我确认去掉 None 后可以排序，但业务上需要保留这些记录。怎样写排序键，才能让有时间戳的记录正常排序、None 稳定地排在最后？

第二种问法给出了目标、触发条件、最小复现、实际结果和清楚的求助点。回答者可以直接针对问题作答，也能指出提问者未考虑到的边界。

得到回复后：把问题收尾

如果回答需要更多信息，就补充可验证的结果；如果建议有效，回到原讨论说明最终原因、采用的解法和适用条件。这样既尊重帮助你的人，也让后来遇到同样问题的人能搜到完整答案。如果暂时没人回复，先检查问题是否发对地方、是否缺少复现信息，再补充关键证据。

可复制的提问模板

### 标题
<技术/功能> 在 <条件> 下出现 <具体症状>

### 我想实现
<最终目标，以及必要背景>

### 环境
<相关版本、系统、配置；只列会影响问题的内容>

### 复现步骤
1. <步骤一>
2. <步骤二>

### 预期与实际
- 预期：<应该发生什么>
- 实际：<发生了什么；附关键报错或最小复现>

### 我已尝试
- <尝试及结果>

### 想请教
<一个明确、可回答的问题>

记住一句话： 好问题让回答者看见你要去哪里、现在站在哪里，以及已经走过哪些路。

来源

从 cmux 切到 herdr：一份可照做的上手指南

Thu, 06 Aug 2026 16:00:00 GMT

面向已经习惯 cmux 管理多个 Coding Agent 的人。目标:30 分钟内用 herdr 跑起一个三端项目(RN App / Web 前端 / 运营后台)的多 Agent 工作流。

0. 先建立心智模型:cmux ↔ herdr 概念对照

你在 cmux 里的东西	herdr 里对应什么	关键差别
原生 macOS 窗口(libghostty 渲染)	你自己的终端里的 TUI	herdr 不自带渲染器,跑在 iTerm/Ghostty/Warp/Windows Terminal 里都行
分屏 pane	pane(同名)	一样支持鼠标拖拽边框、右键菜单
标签页	tab	一样
—	workspace(多出来的一层)	比 tab 更上一层。建议一个 workspace = 一个仓库/一个端
会话保存在 app 里	后台常驻 server	关掉终端 / SSH 断线,Agent 继续跑
只能在这台 Mac 上	SSH 进服务器后 `herdr` 直接接管	这是切过去最大的实际收益
Agent 状态靠自己看	侧边栏统一显示 `working / blocked / done / idle`	herdr 的核心卖点
你去驱动 Agent	Agent 也能反过来开 pane、互相下 prompt(socket API)	可脚本化编排

一句话: cmux 是"给 Agent 定制的 GUI 终端",herdr 是"知道 Agent 在干嘛的 tmux"。切过去要接受的心理落差是:没有原生 GUI 那层壳;换来的是 SSH 常驻 + 可脚本编排。

顺带一提:两者不冲突。herdr 可以直接跑在 cmux 的一个 pane 里,你不必一次性砍掉 cmux。

1. 安装(2 分钟)

macOS / Linux 任选其一:

# 官方安装脚本(推荐,自带 herdr update --handoff 能力)
curl -fsSL https://herdr.dev/install.sh | sh

# 或 Homebrew
brew install herdr

# 或 mise
mise use -g herdr

Windows(beta):

powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"

验证:

herdr --version
herdr --default-config    # 打印全部默认配置,先扫一眼有哪些可调项

⚠️ 用 brew/nix 装的话,后面 herdr update --handoff(热迁移进程,不中断 Agent)用不了,只能走包管理器升级 + 重启 server。如果你在意"升级不打断 Agent",装官方脚本版。

2. 第一次启动(3 分钟)

cd ~/code/my-app     # 先进你的项目目录
herdr

发生了什么:

它启动或接管一个后台默认 session,你不用管 socket、不用 new-session -s xxx 这套 tmux 仪式
没有 workspace 时会自动建一个
界面是鼠标优先的:pane / tab / workspace 都能点、边框能拖、右键有菜单 → 第一天你可以完全不背快捷键

然后在 pane 里直接跑 Agent:

claude

或 codex、opencode、pi、droid、cursor-agent、amp 等。herdr 自动识别,侧边栏立刻出现这个 Agent 的状态灯。

试一下"离开再回来"(这是 herdr 的灵魂)

给 claude 派个活儿,让它跑起来
按 ctrl+b 然后 q detach —— 或者直接把终端窗口关了
重新开终端,敲 herdr
Agent 还在跑,输出都在

要彻底停掉后台 server:

herdr server stop

3. 只背 6 个快捷键就够(prefix 默认 `ctrl+b`,和 tmux 一致)

动作	键
新建 tab	`prefix + c`
向右分屏	`prefix + v`
向下分屏	`prefix + -`
pane 之间移动	`prefix + h / j / k / l`
workspace 切换面板	`prefix + w`
detach 离开	`prefix + q`

第二梯队(用顺手了再加):

动作	键
pane 全屏放大 / 还原	`prefix + z`
关掉 pane	`prefix + x`
调整 pane 大小(模式)	`prefix + r`
复制模式(翻历史、搜索)	`prefix + [`
跳转选择器(模糊搜所有 pane/workspace)	`prefix + g`
开/关侧边栏	`prefix + b`
新建 workspace	`prefix + shift + n`
切到第 N 个 tab	`prefix + 1..9`

复制模式里:h/j/k/l w/b/e 移动,/ 搜索,v 或空格选中,y 或回车复制,q/Esc 退出。

prefix + g 是最被低估的一个键。Agent 一多,靠眼睛找 pane 就崩了,直接模糊搜。

4. 用你的真实项目搭一套布局(三端项目)

思路:一个 workspace = 一个端,每个 workspace 里 = 1 个 Agent pane + 1 个跑命令的 pane。

手动搭一遍(建议第一次手动做,建立肌肉记忆):

prefix + shift + n 新建 workspace,prefix + shift + w 重命名为 app
在 pane 里 cd ~/code/my-app && claude
prefix + v 向右分屏,在新 pane 里跑 npx expo start 或你的 RN 启动命令
重复 1–3,建 web(前端)和 ops(运营后台)两个 workspace
prefix + b 打开侧边栏 —— 现在三个端的 Agent 状态一屏可见

给 Agent 起名字,这样脚本和 prefix+g 里才好认:

herdr agent rename w1:p1 app-dev
herdr agent rename w2:p1 web-dev
herdr agent rename w3:p1 ops-dev

# 之后可以直接按名字跳过去
herdr agent attach web-dev

# 清掉自定义名字
herdr agent rename web-dev --clear

没有现成项目?用这个示例项目练手

mkdir -p ~/herdr-demo && cd ~/herdr-demo
git init && npm init -y
mkdir -p src && printf 'export const add=(a,b)=>a+b;\n' > src/math.js
herdr

然后在 herdr 里:

workspace demo-a:pane1 跑 claude,让它"给 src/math.js 写单测"
prefix + v 分屏,pane2 跑 npm test -- --watch
prefix + shift + n 建 workspace demo-b,跑 codex,让它"给这个项目加 ESLint 配置"
prefix + b 看侧边栏:两个 Agent 谁在 working、谁 blocked(等你确认)一目了然

这个 demo 的唯一目的:体感一下"blocked 状态灯"帮你省了多少次来回切窗口。

5. 装 hook 集成 —— 让状态灯变准(强烈建议做)

herdr 判断 Agent 状态有两条路:生命周期 hook(准)和读屏幕快照 + TOML 规则匹配(兜底)。装上 hook 之后状态判断才是权威的。

herdr integration install claude
herdr integration status        # 看哪些装了、哪些还在靠读屏

如果哪个 Agent 状态一直不对,用这个排查:

herdr agent explain <target>                                   # 解释它为什么判成这个状态
herdr agent explain --file screen.txt --agent codex --json     # 拿离屏文本调试规则

你之前在 cmux 上折腾过 hook 追踪 session ID 那套 —— herdr 这里是同一个思路,但状态语义(working/blocked/done/idle)是内置的,不用你自己定义。

6. 配置文件:一份够用的起步版

路径:

macOS / Linux → ~/.config/herdr/config.toml
Windows → %APPDATA%\herdr\config.toml

onboarding = false

[terminal]
new_cwd = "follow"          # 新 pane 继承当前目录,多仓库场景很关键

[keys]
prefix = "ctrl+b"           # 想避开 tmux 冲突可改成 "ctrl+a" 或 "ctrl+space"

# 自定义弹窗命令:prefix+alt+g 开 lazygit
[[keys.command]]
key = "prefix+alt+g"
type = "popup"
command = "lazygit"
description = "run lazygit"
width = "80%"
height = "80%"

[theme]
name = "catppuccin"
auto_switch = true
light_name = "catppuccin-latte"
dark_name = "catppuccin"

[ui]
tab_bar_position = "top"

# 侧边栏每个 Agent 显示两行:状态+位置 / 名字
[ui.sidebar.agents]
row_gap = 0
rows = [
  ["state_icon", "workspace", "tab"],
  ["agent"],
]

# 侧边栏 workspace 区显示 git 分支和状态
[ui.sidebar.spaces]
row_gap = 0
rows = [
  ["state_icon", "workspace"],
  ["branch", "git_status"],
]

[ui.toast]
delivery = "herdr"
delay_seconds = 1

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

[session]
resume_agents_on_restore = true   # server 重启后尝试恢复 Agent 会话

想看全量可选项:herdr --default-config。

7. 会话生命周期:哪些能恢复、哪些不能(别踩坑)

场景	结果
detach(`prefix+q` / 关终端)	server 不停,进程原样继续。`herdr` 重连即可
server 停了再起	快照恢复:workspace / tab / pane / 目录布局回来了,但进程没了
Agent 会话本身	若 Agent 支持原生 session restore(且开了 `resume_agents_on_restore`),对话可以续上
pane 里的历史输出	默认不保留,需显式开实验特性
升级 herdr	`herdr update --handoff` 尝试把活进程热迁移到新 server(仅官方安装脚本版可用)

开启 pane 输出回放:

[experimental]
pane_history = true

⚠️ 安全提醒:pane 输出里可能含 token、密钥、prompt 原文。开了 pane_history 就意味着这些会落盘到 session 文件。如果产品处理用户隐私数据,建议要么别开,要么把 herdr 的 session 目录纳入你之前做的 redactor / PII lint 那套检查。

8. 进阶:脚本化编排(cmux 给不了你的东西)

这是切过去真正的杠杆。herdr 的 CLI 就是它的编排 API,创建类命令返回 JSON,用 jq 取 ID,不要自己猜 ID。

核心命令速查:

# 布局
herdr workspace create --cwd <path> --label <name> [--no-focus]
herdr tab create <workspace>
herdr pane split <pane_id> --direction right|down [--no-focus]

# Agent 控制
herdr agent start <name> --kind <type> --pane <pane_id> -- <args>
herdr agent prompt <agent> "<text>" --wait --timeout <ms>
herdr agent wait <agent> --until <idle|done|blocked|working> --timeout <ms>
herdr agent send-keys <agent> <key|chord>
herdr agent read <agent> --source recent|visible --lines <N>
herdr agent get <pane_id>

# 裸 pane 控制(跑测试/构建)
herdr pane run <pane_id> "<command>"
herdr pane send-text <pane_id> "<text>"
herdr pane wait-output <pane_id> --regex "<pattern>" --timeout <ms>
herdr pane read <pane_id> --lines <N>

可直接改用的脚本:一键起三端

存成 ~/bin/stack-up.sh,chmod +x:

#!/usr/bin/env bash
set -euo pipefail

boot () {
  local label="$1" dir="$2" agent="$3" cmd="$4"

  ws=$(herdr workspace create --cwd "$dir" --label "$label" --no-focus | jq -r '.result.id')
  pane=$(herdr pane split "$ws:p1" --direction right --no-focus | jq -r '.result.id')

  herdr agent start "$label" --kind claude --pane "$ws:p1"
  herdr pane run "$pane" "$cmd"

  echo "✅ $label 就绪 (workspace=$ws, side-pane=$pane)"
}

boot app ~/code/my-app   claude "npx expo start"
boot web ~/code/my-web   claude "pnpm dev"
boot ops ~/code/my-ops   claude "pnpm dev"

herdr

先把三行 boot 里的路径和启动命令换成你实际的。--kind 按你要用的 Agent 改(claude / codex / …)。

更有意思的用法:把你的双 Agent bugfix 流水线搬过来

你之前设计的"实现 Agent + 审查 Agent + 人工审批闸门"那套,在 herdr 里可以这样落地:

#!/usr/bin/env bash
set -euo pipefail
ISSUE="$1"

# 1. 实现 Agent 干活,阻塞等它完成
herdr agent prompt impl "按 .rca/${ISSUE}/facts.lock.json 修复该问题,只改必要文件" \
  --wait --timeout 1800000

# 2. 等它真的进 done 态
herdr agent wait impl --until done --timeout 1800000

# 3. 把结果交给审查 Agent
herdr agent prompt reviewer "审查 impl 针对 ${ISSUE} 的改动,对照 facts.lock.json 逐条核验" \
  --wait --timeout 900000

# 4. 审查 Agent 一旦 blocked(需要人拍板),侧边栏会亮起来提醒你
herdr agent wait reviewer --until blocked --timeout 900000
echo "⚠️ ${ISSUE} 需要人工审批,去 reviewer pane 看"

关键点:--wait / wait --until 让你能写真正的串行编排,而不是靠人肉盯屏幕。这正好接上你 .rca/<issue-id>/ 文件契约那套设计 —— 状态机由 herdr 管,事实由 git 里的文件管。

9. 从 cmux 迁移的实际注意事项

prefix 冲突:你如果本来就在用 tmux,ctrl+b 会打架。要么改 herdr 的 prefix,要么别嵌套(herdr 本身就是多路复用器,不需要再套 tmux)。
别指望 GUI 特性跟过来:cmux 的浏览器自动化、系统通知这类原生能力,herdr 没有。真需要的话,让 herdr 跑在 cmux 的一个 pane 里,两边都要。
第一天用鼠标就行:herdr 是鼠标原生的,不必先背快捷键再开工。
状态灯不准 ≠ 坏了:先 herdr integration install <agent>,再 herdr agent explain 排查。
进程恢复的边界:server 重启后布局回来但进程不回来 —— 长任务前先确认别手滑 herdr server stop。
许可证:herdr 是 Apache-2.0(对比页面上有 AGPL 的说法,以仓库 LICENSE 为准),商用前建议自己确认一遍当前版本。

10. 第一天验收清单

herdr --version 有输出
herdr 能起来,pane 里能跑 claude,侧边栏出现状态灯
关掉终端 → 重开 → herdr → Agent 还在跑
herdr integration install claude + herdr integration status 显示已装
写好 ~/.config/herdr/config.toml,主题/侧边栏是你想要的样子
三个 workspace(app / web / ops)建起来并重命名
prefix + g 能模糊跳到任意 pane
stack-up.sh 能一键复现整套布局
至少跑通一次 herdr agent prompt ... --wait

附:官方文档入口

快速开始 — https://herdr.dev/docs/quick-start/
安装 — https://herdr.dev/docs/install/
Agent 支持与检测 — https://herdr.dev/docs/agents/
会话状态 / 恢复 — https://herdr.dev/docs/session-state/
配置 — https://herdr.dev/docs/configuration/
键位 — https://herdr.dev/docs/keyboard/
Agent 自动化(CLI / socket API)— https://herdr.dev/docs/agent-automation/
仓库 — https://github.com/herdrdev/herdr

小技巧:herdr 官方提供了一份"agent guide",你可以直接把 https://herdr.dev/docs/ 丢给 Claude Code,让它读完之后在你机器上边配边解释,比看文档快。

herdr 实操：Flutter 双模拟器 + 双 Agent 工作流

Thu, 06 Aug 2026 16:00:00 GMT

项目:一个单仓 Flutter App(下文路径用 ~/code/my-flutter-app 代替) 目标:iOS 模拟器 + Android 模拟器双开,Claude Code 写实现 / Codex 做审查从 cmux 切过来,预计 40 分钟跑通全套

1. 开工前自检(2 分钟)

先跑这几条,确认下面的脚本里哪些需要改:

cd ~/code/my-flutter-app

pwd && ls -1                      # 确认有 lib/ test/ pubspec.yaml ios/ android/
grep -n "^name:" pubspec.yaml     # 拿到包名
flutter --version
flutter devices                   # ★ 记下 iOS/Android 的 device id,后面脚本要用
git branch --show-current
ls -d */ | head -20               # 看有没有 packages/ 之类的子目录

flutter devices 输出大概长这样,把两个 id 抄下来:

iPhone 15 Pro (mobile) • 3A2B1C4D-...-E5F6 • ios      • com.apple.CoreSimulator...
sdk gphone64 arm64 (mobile) • emulator-5554 • android-arm64 • Android 14 (API 34)

后面脚本里我用占位 <IOS_ID> / <ANDROID_ID>,你替换成实际值。也可以偷懒用 -d ios / -d android,但同时开两台同类设备时会歧义。

2. 安装 herdr(2 分钟)

curl -fsSL https://herdr.dev/install.sh | sh
herdr --version

用官方脚本装,不要用 brew —— 后面 herdr update --handoff(升级时热迁移进程、不打断正在跑的 Agent 和 flutter run)只有脚本版支持。

3. 装 Agent 集成(1 分钟,别跳过)

herdr 判断 Agent 状态有两条路:生命周期 hook(准)和读屏幕快照 + 规则匹配(兜底)。你要挂两个 Agent,状态灯准不准直接决定这套东西有没有用。

herdr integration install claude
herdr integration install codex
herdr integration status          # 两行都应该显示已安装

后面如果发现某个 Agent 状态一直不对:

herdr agent explain impl          # 解释它为什么被判成当前状态

4. 配置文件(3 分钟)

写到 ~/.config/herdr/config.toml:

onboarding = false

[terminal]
new_cwd = "follow"

[keys]
prefix = "ctrl+b"

# prefix+alt+g 弹 lazygit —— Flutter 项目改动碎,这个很顺手
[[keys.command]]
key = "prefix+alt+g"
type = "popup"
command = "lazygit"
description = "run lazygit"
width = "80%"
height = "80%"

[theme]
name = "catppuccin"
auto_switch = true
light_name = "catppuccin-latte"
dark_name = "catppuccin"

[ui]
tab_bar_position = "top"

# 侧边栏:两个 Agent 各占两行,一眼看出谁在 working / 谁 blocked
[ui.sidebar.agents]
row_gap = 0
rows = [
  ["state_icon", "workspace", "tab"],
  ["agent"],
]

[ui.sidebar.spaces]
row_gap = 0
rows = [
  ["state_icon", "workspace"],
  ["branch", "git_status"],
]

[ui.toast]
delivery = "herdr"
delay_seconds = 1

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

[session]
resume_agents_on_restore = true

⚠️ 特别注意:不要开 [experimental] pane_history = true。 如果 App 处理用户隐私数据,pane 输出里会出现真实的用户数据、API token、prompt 原文,开了这个就意味着这些内容落盘到 herdr 的 session 文件。要开的话,先把 herdr 的 session 目录纳入你之前那套 redactor / PII lint 检查再说。

5. 手动搭一遍布局(第一次务必手动做)

设计:两个 workspace,职责分离。

workspace: cr-impl            workspace: cr-review
┌──────────┬──────────┐       ┌──────────┬──────────┐
│ claude   │ flutter  │       │ codex    │ flutter  │
│ (impl)   │ run ios  │       │ (review) │ analyze  │
│          ├──────────┤       │          ├──────────┤
│          │ flutter  │       │          │ flutter  │
│          │ run andr │       │          │ test     │
└──────────┴──────────┘       └──────────┴──────────┘

操作步骤:

终端里 cd ~/code/my-flutter-app && herdr
prefix + shift + w 把当前 workspace 改名 cr-impl
左边 pane 跑 claude
prefix + v 向右分屏 → flutter run -d <IOS_ID>
prefix + - 在右侧再向下分屏 → flutter run -d <ANDROID_ID>
prefix + shift + n 新建 workspace,prefix + shift + w 改名 cr-review
左 pane 跑 codex;prefix + v 分屏跑 flutter analyze --watch(或 flutter test)
prefix + b 打开侧边栏 —— 两个 Agent 的状态灯出来了

给 Agent 起名,后面脚本和 prefix+g 全靠它:

herdr agent rename w1:p1 impl
herdr agent rename w2:p1 review

herdr agent attach impl      # 之后直接按名字跳过去

验证"离开再回来"

给 claude 派个活儿,然后 prefix + q detach,把终端窗口关掉,重开终端敲 herdr —— Agent 还在跑,两个 flutter run 也还活着。这是切过来最实在的收益:再也不会因为误关终端把双模拟器热重载会话搞没。

6. 只背这 7 个键

动作	键
pane 间移动	`prefix + h/j/k/l`
向右 / 向下分屏	`prefix + v` / `prefix + -`
pane 全屏放大(看 flutter 日志时救命)	`prefix + z`
模糊跳转到任意 pane / workspace	`prefix + g`
开关侧边栏	`prefix + b`
复制模式(翻 stack trace)	`prefix + [`
detach	`prefix + q`

复制模式里:/ 搜索、v 选中、y 复制、q 退出。Flutter 的异常栈很长,prefix+[ 然后 /Exception 直接定位。

7. 一键起项目:`cr-up.sh`

存成 ~/bin/cr-up.sh 并 chmod +x ~/bin/cr-up.sh:

#!/usr/bin/env bash
set -euo pipefail

REPO=~/code/my-flutter-app
IOS_ID="<IOS_ID>"          # ← 换成 flutter devices 里的实际值
ANDROID_ID="<ANDROID_ID>"  # ←

# ---------- workspace 1: 实现 ----------
ws1=$(herdr workspace create --cwd "$REPO" --label cr-impl --no-focus | jq -r '.result.id')
p_ios=$(herdr pane split "$ws1:p1" --direction right --no-focus | jq -r '.result.id')
p_and=$(herdr pane split "$p_ios"  --direction down  --no-focus | jq -r '.result.id')

herdr agent start impl --kind claude --pane "$ws1:p1"
herdr pane run "$p_ios" "cd $REPO && flutter run -d $IOS_ID"
herdr pane run "$p_and" "cd $REPO && flutter run -d $ANDROID_ID"

# ---------- workspace 2: 审查 ----------
ws2=$(herdr workspace create --cwd "$REPO" --label cr-review --no-focus | jq -r '.result.id')
p_test=$(herdr pane split "$ws2:p1" --direction right --no-focus | jq -r '.result.id')

herdr agent start review --kind codex --pane "$ws2:p1"
herdr pane run "$p_test" "cd $REPO && flutter analyze"

# 把 pane id 存下来,给后面的热重载脚本用
cat > ~/.cr-panes <<EOF
CR_IOS_PANE=$p_ios
CR_AND_PANE=$p_and
CR_TEST_PANE=$p_test
EOF

echo "✅ cr-impl=$ws1  cr-review=$ws2"
echo "   ios=$p_ios  android=$p_and  test=$p_test"
herdr

跑一次 cr-up.sh,整套环境起来。

jq 没装的话:brew install jq。创建类命令返回 JSON,不要自己猜 pane id,一定从 .result.id 取。

8. Flutter 专属杀手锏:让 Agent 改完代码自动热重载

这是 cmux 给不了你的东西。flutter run 的热重载是靠**在那个终端里按 r**触发的 —— herdr 能远程把这个键送过去。

存成 ~/bin/cr-reload.sh:

#!/usr/bin/env bash
set -euo pipefail
source ~/.cr-panes

herdr pane send-keys "$CR_IOS_PANE" r    # hot reload iOS
herdr pane send-keys "$CR_AND_PANE" r    # hot reload Android
echo "🔥 双端已热重载"

R(大写)是 hot restart,状态全清:

herdr pane send-keys "$CR_IOS_PANE" R

组合起来:Agent 改完 → 自动重载 → 自动 analyze

~/bin/cr-task.sh:

#!/usr/bin/env bash
set -euo pipefail
source ~/.cr-panes
TASK="$1"

# 1. 派活给 claude,阻塞等它做完(30 分钟上限)
herdr agent prompt impl "$TASK" --wait --timeout 1800000
herdr agent wait impl --until done --timeout 1800000

# 2. 双端热重载
herdr pane send-keys "$CR_IOS_PANE" r
herdr pane send-keys "$CR_AND_PANE" r

# 3. 跑静态检查,等它出结果
herdr pane run "$CR_TEST_PANE" "flutter analyze && flutter test"
herdr pane wait-output "$CR_TEST_PANE" --regex "All tests passed|Some tests failed|error •" --timeout 600000

# 4. 把检查结果读出来
herdr pane read "$CR_TEST_PANE" --lines 60

用法:

cr-task.sh "把 lib/pages/record_detail.dart 里的时间格式统一成 yyyy-MM-dd HH:mm,补上对应 widget test"

这就是从 cmux 切过来最大的收益:以前你得人肉盯着 claude 什么时候写完、切过去按 r、再切到另一个 pane 跑 analyze;现在一条命令串起来。

9. 双 Agent 流程:claude 实现 + codex 审查

对应你之前设计的那套「实现 Agent + 审查 Agent + 人工审批闸门」。~/bin/cr-review.sh:

#!/usr/bin/env bash
set -euo pipefail
ISSUE="$1"

# 1. claude 实现
herdr agent prompt impl \
  "修复 ${ISSUE}。只改必要文件,改完把涉及的文件列表输出出来" \
  --wait --timeout 1800000
herdr agent wait impl --until done --timeout 1800000

# 2. 把改动交给 codex 审查
herdr agent prompt review \
  "审查工作区当前未提交的改动(git diff),针对 ${ISSUE}。重点看:空安全、await 遗漏、setState 在 dispose 后调用、用户隐私数据是否被打进日志。有问题直接指出文件和行号" \
  --wait --timeout 900000

# 3. 审查 Agent 一旦 blocked = 需要你拍板,侧边栏会亮
herdr agent wait review --until blocked --timeout 900000 || true

echo "⚠️  ${ISSUE} 审查完成/需人工确认 → prefix+g 跳到 review"
herdr agent read review --source recent --lines 80

配合你 .rca/<issue-id>/ 那套文件契约:状态机交给 herdr 管,事实交给 git 里的文件管,两边不重叠。

10. 日常三个高频动作

① 改一行 UI 想看双端效果 prefix+g → 跳到 claude pane → 说需求 → 等状态灯变 done → cr-reload.sh

② 模拟器卡死要重启

source ~/.cr-panes
herdr pane send-keys "$CR_IOS_PANE" q          # 退出 flutter run
herdr pane run "$CR_IOS_PANE" "flutter run -d <IOS_ID>"

③ 想看某个 Agent 最近说了啥,但不想切过去

herdr agent read impl --source recent --lines 40

11. 从 cmux 迁过来的实际注意事项

prefix 冲突:如果你还在用 tmux,ctrl+b 会打架。herdr 本身就是多路复用器,别嵌套;非要共存就把 herdr 的 prefix 改成 ctrl+space。
cmux 的原生能力不会跟过来:浏览器自动化、系统通知这些没有。真需要就让 herdr 跑在 cmux 的一个 pane 里,不必一次性砍掉 cmux。
server 重启 ≠ 进程恢复:herdr server stop 之后重启,workspace/tab/pane/目录布局会回来,但 flutter run 和 Agent 进程不会自动复活 —— 重跑 cr-up.sh 就行。
第一天用鼠标:herdr 是鼠标原生的,pane 能点能拖能右键,不必先背快捷键。
iOS 构建慢:第一次 flutter run -d ios 可能几分钟,pane wait-output 的 timeout 别设太短。

12. 验收清单

flutter devices 拿到两个 device id 并填进 cr-up.sh
herdr integration status 显示 claude 和 codex 都已安装
~/.config/herdr/config.toml 写好,确认没开 pane_history
cr-up.sh 一键起来:2 个 workspace、双模拟器在跑、两个 Agent 有状态灯
关掉终端 → herdr → 一切还在
cr-reload.sh 能触发双端热重载
cr-task.sh "随便一个小改动" 能跑完整条链路
prefix + g 能在 4 个 pane 之间瞬移

附:命令速查

# 布局
herdr workspace create --cwd <path> --label <name> [--no-focus]
herdr pane split <pane_id> --direction right|down [--no-focus]

# Agent
herdr agent start <name> --kind claude|codex --pane <pane_id>
herdr agent rename <pane_id> <name>
herdr agent attach <name>
herdr agent prompt <name> "<text>" --wait --timeout <ms>
herdr agent wait <name> --until idle|done|blocked|working --timeout <ms>
herdr agent read <name> --source recent|visible --lines <N>
herdr agent explain <name>

# Pane(Flutter 交互全靠这几条)
herdr pane run <pane_id> "<command>"
herdr pane send-keys <pane_id> r        # hot reload
herdr pane send-keys <pane_id> R        # hot restart
herdr pane wait-output <pane_id> --regex "<pattern>" --timeout <ms>
herdr pane read <pane_id> --lines <N>

# 集成 / 会话
herdr integration install <agent>
herdr integration status
herdr server stop
herdr update --handoff

官方文档:https://herdr.dev/docs/ · 仓库:https://github.com/herdrdev/herdr

用 pilot-shell 跑通第一个 /spec：Claude Code 规格驱动开发实操

Mon, 22 Jun 2026 16:00:00 GMT

# 安装
curl -fsSL https://raw.githubusercontent.com/maxritter/pilot-shell/main/install.sh | bash
# 激活
pilot activate <你的-license-key>
# 使用
pilot update
pilot
codex/claude

下面这份从零到第一个 /spec 跑通的完整流程,我用你正在做的那个 React Native 英语学习 app 当真实示例,这样每一步都能对得上你的实际场景。

阶段一:前置准备(只做一次)

装 Claude Code(native installer) — 如果你之前用 npm install -g 或 brew 装过,先卸载干净,否则 pilot 会冲突。pilot 安装器检测不到 Claude Code 时会尝试帮你装,但建议自己先装好。
确认 Claude 订阅档位 — 单人开发选 Max 5x(中度)或 Max 20x(重度)。你深度用 Claude API + 要跑 TDD 全流程,实测会很吃 token,建议直接 20x。
终端(可选但推荐) — cmux 的竖向标签页适合开多个 session 并行跑 spec;iTerm2 / Ghostty 也行。
Claude Chrome 扩展(推荐) — 这个对你特别有用。你的 app 有动画 flashcard UI,/spec 在 verify 阶段会用浏览器自动化逐条跑 E2E 场景,装了扩展才能真正验证 UI。
(可选)Codex 对抗式 review — 需要 ChatGPT Plus($20/月)。它在 /spec 规划和验证阶段给一个独立第二意见。你之前折腾过 Claude Code ↔ Codex 通信,这个你应该会喜欢,但默认是关的,可以先跳过。

阶段二:安装(只做一次,全局生效)

运行安装脚本:

curl -fsSL https://raw.githubusercontent.com/maxritter/pilot-shell/main/install.sh | bash

等 7 步安装器跑完。它会做:检查/装依赖(Node、Python 3.12+、uv、git、jq)→ 写入 ~/.claude/ → 装开发工具(Semble 代码搜索、CodeGraph、RTK token 压缩、language servers、Chrome DevTools MCP、playwright-cli)→ 配置 bash/zsh/fish 的 pilot 别名 → 装 VS Code 扩展。
装完后,重开一个终端窗口(让 pilot 别名生效)。

全局装一次就够,所有项目共用 ~/.pilot/ 和 ~/.claude/,不用每个项目重装。

阶段三:首次配置(每个项目一次)

以你的英语学习 app 为例:

cd ~/projects/english-learning-app
pilot                              # 首次会让你登录 Claude
pilot activate <你的-license-key>   # 从 polar.sh/max-ritter/portal 拿 key

跑 /setup-rules — 这一步很关键,别跳过:

> /setup-rules

它会用语义搜索 + 结构分析探索你的代码库,自动识别出你用的是 Expo、Zustand、SM-2 spaced repetition 这些技术栈和约定,生成模块化的项目规则({slug}-project.md)。它还会检测你现有的 CLAUDE.md / AGENTS.md 并迁移进去。之后每次 session 都自带这些上下文,Claude 就不会忘记你的架构了。

(可选)启用 Codex review:

> /codex:setup

认证后去 Console 的 Settings → Reviewers 里打开。

阶段四:完整示例——用 `/spec` 加一个功能

假设你要给学习 app 加一个"连续打卡 streak + 每日复习提醒"功能。完整走一遍:

1. 先想清楚再写代码(可选,适合需求模糊时)

如果只是模糊想法,先用 /prd 头脑风暴:

> /prd "加一个学习连续打卡和每日复习提醒,提升用户留存"

它会抛 3-5 个方向跟你对线,收敛成一份 PRD(存到 docs/prd/),最后问你要不要直接交给 /spec。需求已经清楚的话,跳过这步。

2. 切到 Opus 做规划

> /model opus

⚠️ 注意:有个 spec-mode-guard 钩子会硬性拦截在非 Opus 模型上跑 /spec——规划必须用 Opus。这是故意的,规划质量直接决定后面所有产出。

3. 启动 spec 工作流

> /spec "添加学习连续打卡(streak):每日完成复习后 streak +1,断签清零,首页展示当前/历史最高 streak,并在每天固定时间推送复习提醒"

接下来它会自动走这个循环:

Discuss → Plan → Approve → Implement(TDD) → Verify → Done
                                    ↑              ↓
                                    └──── Loop ────┘

Plan 阶段: 用语义搜索摸清你的 Zustand store 和 SM-2 逻辑 → 问你澄清问题(比如"streak 按本地时区还是 UTC 算?""提醒时间用户可配置吗?")→ 写出带 scope/任务/完成定义的详细 spec → 因为有 UI,会写可被浏览器执行的 E2E 测试场景 → 一个 spec-review 子 agent 检查完整性 → 停下来等你批准。
批准前你可以可视化批注: 打开 Console(浏览器访问 localhost:41777),在 Specifications 标签页默认是 Annotate 模式,选中任何一段文字或点 + 就能写批注("streak 断签判断要考虑跨夜的边界情况")。agent 会在下一个检查点读你的批注、改 plan、再请你批准。批准对了再往下走,比在 PR 阶段才发现问题省事得多。

4. 切到 Sonnet 实现

批准后切模型省钱:

> /model sonnet[1m]

Implement 阶段: 自动建一个隔离的 git worktree → 每个任务严格 TDD(RED 写失败测试 → GREEN 实现 → REFACTOR)→ 质量钩子在每次编辑后自动跑 lint / format / 类型检查 → 每个任务后跑全套测试。

5. Verify(自动)

跑全套测试 + 实际执行程序 → 统一 review 子 agent 检查(合规 + 质量 + 目标达成)→ UI 功能逐条用浏览器自动化跑 E2E 场景(你那个 flashcard 动画就在这里被真实验证)→ 自动修复发现的问题 → 通过后 squash merge 回 main。

6. 最终 code review(可选但建议)

在 Console 的 Changes 标签页开 Review 模式,在 diff 行上点 + 加行级批注,agent 读完逐条解决后才标记为 verified。等于在代码离开你机器前先过一遍 PR review。

日常使用速查

场景	命令
小改动 / 探索	直接聊(Quick 模式,默认。TDD 和质量钩子照常生效)
新功能 / 重构 / 架构改动	`/spec "..."`(先 `/model opus`)
修单点 bug	`/fix "复习进度在保存重载之间丢失"`(单文件根因 bug,自动 TDD)
模糊想法变需求	`/prd "..."`
切模型	`/model opus` 规划 → `/model sonnet[1m]` 实现
看进度 / 改设置	浏览器开 `localhost:41777`

/fix 有个聪明的 bail-out:如果调查发现 bug 是多组件/架构性的,它会干净地停下来让你改用 /spec,不会硬修。

维护(每隔几周)

跑久了 session 日志和缓存会拖慢速度,定期 reset 一次:

# 1. Claude Code 内登出
/logout
# 2. 备份配置
mv ~/.claude.json ~/.claude.json.bak
mv ~/.claude ~/.claude.bak
mv ~/.pilot ~/.pilot.bak
# 3. 重装
curl -fsSL https://raw.githubusercontent.com/maxritter/pilot-shell/main/install.sh | bash
# 4. 重新登录激活
pilot
pilot activate <你的-license-key>

跑顺了再删掉 .bak 副本。

一个实操建议:第一次别上来就跑大功能。 先在你的 app 上挑一个小而完整的功能(比如就那个 streak 计数)走完一遍 /spec 全流程,把"它怎么问澄清问题、E2E 怎么验证、Console 批注怎么用"这套手感跑熟,再上复杂的。