附录 A · 源码地图¶
本页不是把 rg --files 换成表格，而是按“我正在追什么问题”给出入口、下一跳和验证文件。全部链接固定到提交 bbd7c2094a44fcbcc4a3a3aedef236c4d697d793。
A.1 启动与进程角色¶
| 问题 | 第一入口 | 下一跳 |
|---|---|---|
herdr 如何分流 |
src/main.rs#L502 |
cli, remote, server::autodetect, update |
| 默认 daemon 如何发现/拉起 | src/server/autodetect.rs |
client status、protocol handshake、daemon detach |
| session 路径怎样隔离 | src/session.rs |
config/data dir、API/client socket |
| 后台 server 怎样启动 | run_server |
HeadlessServer::new/run |
| 单进程兼容模式 | App::run |
app runtime/input/render |
建议验证：tests/auto_detect.rs、tests/detach_reattach.rs、tests/cli/sessions.rs。
A.2 Server/Client 与帧协议¶
| 问题 | 第一入口 | 下一跳 |
|---|---|---|
| server 主循环 | HeadlessServer::run |
internal event drain、API、client、render |
| client transport/handshake | src/server/client_transport.rs |
wire enums、writer queue |
| wire 版本/上限 | src/protocol/wire.rs |
protocol constants、framing |
| 客户端请求 | ClientMessage |
input、resize、focus、takeover |
| 服务端消息 | ServerMessage |
frame、title、error、shutdown |
| semantic frame | CellData、FrameData |
style/cursor/cells |
| ANSI/semantic diff | src/server/render_stream.rs |
baseline、repaint、BlitEncoder |
| 虚拟渲染与广播 | render_and_stream |
retained frame、per-client state |
建议验证：tests/multi_client.rs、tests/client_mode.rs、tests/cli/protocol_guard.rs。
A.3 App、状态与身份¶
| 类型/问题 | 定义 | 关键关系 |
|---|---|---|
App |
src/app/mod.rs#L98 |
state + runtimes + channels/deadlines/caches |
AppState |
src/app/state.rs#L1326 |
terminals + workspaces + mode/view/config |
TerminalState |
src/terminal/state.rs#L119 |
可恢复事实 + Agent 仲裁 |
TerminalRuntime |
src/terminal/runtime.rs#L17 |
包装 legacy PaneRuntime |
| runtime registry | src/terminal/runtime_registry.rs |
TerminalId -> TerminalRuntime |
PaneState |
src/pane/state.rs#L6 |
attachment + seen + UI preference |
PaneRuntime |
src/pane.rs#L998 |
PTY/VT/actor/tasks |
TerminalId |
src/terminal/id.rs |
state/runtime 连接键 |
| public ID 解析 | src/app/ids.rs |
CLI/API aliases → internal objects |
动作入口可从 src/app/actions.rs、src/app/api/panes.rs 和 src/app/creation.rs 交叉阅读。
A.4 Workspace、Tab 与布局¶
| 问题 | 第一入口 | 关键符号 |
|---|---|---|
| workspace identity/tab/counters | src/workspace.rs#L171 |
Workspace |
| tab 的 layout/panes/zoom | src/workspace/tab.rs#L38 |
Tab |
| 内部 pane id | src/layout.rs#L11 |
PaneId |
| BSP node | src/layout.rs#L73 |
Node::Pane/Split |
| layout 操作 | TileLayout |
split/move/resize/navigation |
| UI worktree actions | src/app/worktrees.rs |
modal + async result |
A.5 PTY、VT、输入和渲染¶
| 问题 | 第一入口 | 下一跳 |
|---|---|---|
| Unix/Windows PTY | src/pty/ |
actor/read/write/resize/pause |
| terminal 适配层 | src/pane/terminal.rs |
process bytes、key/mouse、snapshot、dirty patch |
| Ghostty FFI | src/ghostty/mod.rs |
libghostty-vt terminal/render/callback |
| raw input decoder | src/raw_input.rs |
escape/Kitty/legacy partial sequence |
| app input router | src/app/input/ |
terminal/navigate/mouse/copy |
| mode | src/app/state.rs#L780 |
Mode |
| 派生几何 | compute_view |
runtime-aware variants |
| 纯绘制 | render |
sidebar/mobile/dialog/widget |
| 合并脏信号 | src/render_signal.rs |
PTY sources / generic dirty |
建议验证：keyboard corpus、src/pane/terminal.rs 内部测试、scripts/test_ui_hot_path_architecture.py。
A.6 Agent 检测¶
| 问题 | 第一入口 | 下一跳 |
|---|---|---|
| raw state/Agent enum | src/detect/mod.rs |
process identification、screen detection |
| manifest parser/evaluator | src/detect/manifest.rs |
regions、gates、priority、explain |
| bundled rules | src/detect/manifests/ |
19 TOML manifests |
| manifest 更新 | src/detect/manifest_update.rs |
source/version/cache |
| 有效状态仲裁 | recompute_effective_state |
hook authority/visible blocker/sequence |
| 进程平台数据 | src/platform/mod.rs |
ForegroundJob/Process |
A.7 持久化与交接¶
| 问题 | 第一入口 | 下一跳 |
|---|---|---|
| snapshot schema/version | src/persist/snapshot.rs |
capture/migration/validation |
| 文件 I/O | src/persist/io.rs |
session/history temp+rename |
| 恢复 runtime | src/persist/restore.rs |
restore plan/agent resume/handoff |
| handoff transport | src/server/handoff.rs |
manifest/private socket/FD receive |
| runtime export/import | src/handoff_runtime.rs |
PTY state/ownership |
| public socket rollback | src/server/headless.rs |
restore/wait after failed handoff |
建议验证：tests/fixtures/session/、tests/live_handoff.rs。
A.8 API、事件与 CLI¶
| 问题 | 第一入口 | 下一跳 |
|---|---|---|
| Method/request schema | src/api/schema.rs |
分域 schema modules |
| local API server | src/api/server.rs |
request loop/long wait dispatch |
| EventHub | src/api/event_hub.rs |
sequence/history |
| Agent/output/event wait | src/api/wait.rs |
probe/identity/timeout |
| subscriptions | src/api/subscriptions.rs |
setup window/de-dup/filter |
| App API dispatch | src/app/api.rs |
分域 handlers |
| CLI | src/cli/ |
typed client/printing |
| checked schema | herdr-api.schema.json |
跨语言契约 |
A.9 Integrations 与 Plugins¶
| 问题 | 第一入口 | 下一跳 |
|---|---|---|
| integration target schema | src/api/schema/integrations.rs |
16 targets |
| availability/aliases | src/integration/registry.rs |
command/path/platform |
| install/uninstall | src/integration/targets.rs |
Agent-specific actions |
| 配置安全编辑 | src/integration/config_edit.rs |
ownership/legacy/idempotence |
| bundled assets | src/integration/assets/ |
JS/TS/PS1/sh/Python |
| plugin manifest | src/app/api/plugins/manifest.rs |
raw parse + validation |
| plugin runtime | src/app/api/plugins/runtime.rs |
external commands/logs/events |
| plugin panes | src/app/api/plugins/panes.rs |
placement/open/focus/close |
| registry persistence | src/persist/plugin_registry.rs |
strict mutation/lenient startup |
A.10 Git Worktree¶
| 问题 | 第一入口 | 下一跳 |
|---|---|---|
| command/porcelain/安全删除 | src/worktree.rs |
add/remove/status/admin path |
| workspace Git discovery | src/workspace/git/discovery.rs |
repo root/checkout key/membership |
| Git status cache | src/workspace/git/status.rs |
branch/dirty/common dir |
| UI orchestration | src/app/worktrees.rs |
modal/force/background event |
| API deferred ops | src/app/api/worktrees/deferred.rs |
operation id/checkout key/response |
A.11 Remote、平台与更新¶
| 问题 | 第一入口 | 下一跳 |
|---|---|---|
| remote attach/install | src/remote/attach.rs |
SSH/platform/artifact/protocol/forward |
| Unix host bridge | src/remote/host_unix.rs |
bidirectional copy/flush |
| 平台共享边界 | src/platform/mod.rs |
process/capability/clipboard/signal |
| 配置 model/load | src/config/model.rs、io.rs |
overlay/diagnostics/reload |
| update | src/update.rs |
stable/preview/package manager/handoff |
| checksum | src/checksum.rs |
SHA-256 validation |
| build identity | src/build_info.rs |
channel/version/build id |
A.12 性能与测试¶
| 问题 | 入口 |
|---|---|
| render profile events | src/render_prof.rs |
| render scale benchmark | justfile 的 bench-render-scale |
| hot-path structural guard | scripts/test_ui_hot_path_architecture.py |
| 主 CI | .github/workflows/ci.yml |
| release/preview | .github/workflows/ |
| vendored guards | scripts/test_vendor_* |
A.13 一条实用的调试顺序¶
当行为不正确时，不要先在巨大 handler 里随机加日志。按边界定位：
- 身份：public id 解析到哪个
PaneId/TerminalId？ - 事实：
TerminalState/AppState当前是什么，revision/sequence 是多少？ - 运行时：registry 是否有同一
TerminalId，PTY/child 是否活？ - 输入/输出：消息是否过 lease/mode，VT content sequence 是否推进？
- 推导：manifest/hook explain 选了哪条证据？
- 呈现：render request 是 generic 还是 PTY dirty，是否 full fallback？
- 传输：该 client baseline/queue/foreground role 是否正确？
- 持久化/异步：operation id/generation 是否把结果判旧？
这个顺序从稳定 identity 向外扩散，通常比从 UI 症状直接追到 OS I/O 更快。