附录 C · 证据、统计与复现¶

本页记录本站审计基线、统计口径、源码一致性验证和可复跑命令。目的是让“243 个文件”“92 个方法”等数字可以被重新计算，而不是成为无法追溯的宣传。

C.1 审计基线¶

字段	值
上游仓库	`herdrdev/herdr`
固定提交	`bbd7c2094a44fcbcc4a3a3aedef236c4d697d793`
提交时间	2026-08-10T12:09:10Z
提交标题	`test(windows): serialize media player environment access (#2619)`
Cargo package	`herdr`
Cargo version	`0.8.0`
Rust edition	`2021`
审计日期	2026-08-10

本文分析的是固定源码快照，不声称代表未来 master。所有上游链接都带完整 commit SHA。

C.2 本地快照一致性验证¶

审计时，本地 herdr-master 是无 .git 的解压目录。为了避免把未知 archive 当作当前上游，抽取九个跨模块锚点，用 Git blob SHA 与 GitHub 固定提交逐一比对：

Cargo.toml
src/main.rs
src/server/headless.rs
src/app/state.rs
src/pane.rs
src/terminal/state.rs
src/protocol/wire.rs
src/detect/manifest.rs
docs/next/api/herdr-api.schema.json

这些文件的本地 git hash-object 与 GitHub API 返回 blob SHA 全部一致。锚点覆盖入口、主循环、状态、runtime、协议、检测和生成 schema，因此本文把本地目录视为该 commit 的可信工作副本。

边界

抽样 hash 不是全目录 Merkle proof。它足以确认本次用于分析的关键代码基线；需要位级完整复现时，应直接 clone 固定 commit并重新运行统计。

C.3 获取可复现源码¶

git clone https://github.com/herdrdev/herdr.git
cd herdr
git checkout --detach bbd7c2094a44fcbcc4a3a3aedef236c4d697d793
git status --short

最后一条应为空。以下命令都从该仓库根目录执行，要求 rg、find、awk、sed、wc 可用。

C.4 规模统计¶

Rust 文件与行数¶

rg --files src -g '*.rs' | wc -l
rg --files src -g '*.rs' -0 | xargs -0 wc -l | tail -1

结果：

243 files
220337 total lines

行数包含空行、注释、生产代码和源文件内测试，不是逻辑代码行（SLOC）。

最大 Rust 文件¶

rg --files src -g '*.rs' -0 | xargs -0 wc -l | sort -nr | sed -n '2,12p'

审计结果：

文件	行数
`src/server/headless.rs`	10,971
`src/pane/terminal.rs`	6,627
`src/app/mod.rs`	6,471
`src/app/actions.rs`	6,023
`src/terminal/state.rs`	5,746
`src/pane.rs`	4,356
`src/app/input/mouse.rs`	4,279
`src/ghostty/bindings.rs`	4,240
`src/app/api/panes.rs`	4,117
`src/integration/tests.rs`	4,051
`src/ghostty/mod.rs`	4,030

ghostty/bindings.rs 是生成式 FFI bindings，不能用其行数直接评价手写复杂度。

C.5 测试统计¶

rg -g '*.rs' -g '!vendor/**' -g '!target/**' -c '#\[test\]' . \
  | awk -F: '{s+=$2} END{print s}'

rg -g '*.rs' -g '!vendor/**' -g '!target/**' -c '#\[tokio::test' . \
  | awk -F: '{s+=$2} END{print s}'

rg -g '*.rs' -g '!vendor/**' -g '!target/**' -c '#\[ignore' . \
  | awk -F: '{s+=$2} END{print s}'

find tests -type f -name '*.rs' | wc -l
find scripts -maxdepth 1 -type f -name 'test_*.py' | wc -l

结果：

#[test]        3114
#[tokio::test]  344
total          3458
#[ignore]         1
tests/*.rs       24 files
test_*.py        11 files

口径排除 vendor/ 和 target/。属性文本统计可能把某些 cfg 下不可运行测试计入，也可能不包含使用其他宏生成的测试；它用于仓库规模对比，不替代 cargo nextest list。

C.6 领域枚举与资产统计¶

API 方法¶

rg -c '#\[serde\(rename = "' src/api/schema.rs

结果：92。该文件的这些 serde rename 对应 Method 外部方法名；若未来其他 rename 混入同文件，应改用 enum 范围切片。

EventKind¶

sed -n '/pub enum EventKind {/,/^}/p' src/api/schema/events.rs \
  | rg -c '^    [A-Za-z].*,'

结果：26。

Agent、Integration、Manifest¶

sed -n '/pub enum Agent {/,/^}/p' src/detect/mod.rs \
  | rg -c '^    [A-Za-z].*,'

sed -n '/pub enum IntegrationTarget {/,/^}/p' src/api/schema/integrations.rs \
  | rg -c '^    [A-Za-z].*,'

find src/detect/manifests -maxdepth 1 -type f -name '*.toml' | wc -l
find src/integration/assets -type f | wc -l

结果：

Agent enum variants       21
IntegrationTarget         16
Detection manifests       19
Integration asset files   32

Agent 变体多于 manifest 是合理的：部分 Agent 可能复用检测策略、主要依赖进程/hook，或当前没有独立 screen manifest。

C.7 协议与队列常量¶

以下值来自固定提交源码，适合作为阅读锚点，不应当作未来兼容承诺：

常量/机制	值	源码
Client protocol	20	`src/protocol/wire.rs`
AppEvent channel capacity	256	`src/app/mod.rs#L163`
AppEvent per-turn drain	64	`src/app/mod.rs#L164`
Snapshot version	3	`src/persist/snapshot.rs#L12`
Max FDs per handoff	64	`src/server/handoff.rs#L26`
PTY user-input queue	1024	PTY actor implementation
Normal wire payload	约 2 MiB	protocol constants
Graphics wire payload	约 32 MiB	protocol constants
Clipboard image	约 16 MiB	protocol constants/platform readers
Kitty image storage	约 64 MiB	terminal setup

“约”表示源码常量以字节表达，本表用 MiB 便于理解；精确字节值以链接代码为准。

C.8 API Schema 与 CI¶

wc -l docs/next/api/herdr-api.schema.json
find .github/workflows -type f | wc -l

固定快照结果：

API JSON Schema  10103 lines
GitHub workflows     9 files

Schema 行数受 pretty-print 格式影响，只说明公开 surface 规模，不是方法复杂度。

C.9 常用验证命令¶

根据 justfile：

# 主 Rust + maintenance/asset 测试
just test

# 格式、clippy、tests、Windows target lint、maintenance checks
just check

# 单个 nextest filter
just test-one codex_stale_working

# UI 热路径结构守卫
just test-ui-hot-path

# 渲染规模基准
just bench-render-scale

实际 recipe 名称/依赖工具以固定 justfile 为准。完整 suite需要 Rust toolchain、cargo-nextest、just、Python、Bun，以及某些平台依赖；并非所有命令能在任意 OS 完整运行。

C.10 关键证据如何支撑章节¶

章节结论	主要证据
默认 server/client	`main.rs`, `server/autodetect.rs`, `server/headless.rs`, client tests
state/runtime 分离	`AppState`, `TerminalState`, registry, `PaneState`, snapshot DTO
PTY/VT 双向协议	`pty/`, `pane/terminal.rs`, `ghostty/mod.rs`, keyboard fixtures
Agent 多源仲裁	`detect/mod.rs`, manifest engine/TOML, `TerminalState` arbitration tests
Live Handoff 回滚	`server/handoff.rs`, `handoff_runtime.rs`, headless socket restore, E2E tests
API wait 无竞态	`EventHub`, `wait.rs`, `subscriptions.rs` setup-window tests
Worktree 删除安全	`worktree.rs` pointer proof/replacement-dir tests, deferred operation IDs
慢客户端隔离	per-client render state、queue/baseline tests、multi-client integration
热路径约束	render signal、retained gates、scale bench、Python architecture guard
跨平台诚实能力	`PlatformCapabilities`, CI matrix, Windows ConPTY package suite

C.11 分析方法与限制¶

本拆解采用：

参考既有深度拆解的章节方法；
模块/类型/调用入口静态阅读；
关键状态机的正常路径与失败路径交叉阅读；
测试名、fixture、维护脚本和 CI 反证；
固定 commit blob 抽样校验；
文本统计建立规模口径。

没有做的事：

没有宣称运行完整的 Herdr 跨平台 test suite；
没有在三种 OS 上动态 profile；
没有把所有 92 个 API 方法逐一写成参考手册；
没有评估固定提交之后的上游变化；
没有对 vendored C/Rust 依赖做独立安全审计。

因此文中“代码事实”以固定链接为准，“设计解释/评价”应视为基于该快照的工程分析。

C.12 文档自身构建¶

本站使用 MkDocs Material，依赖固定为：

mkdocs==1.6.1
mkdocs-material==9.7.7

本地严格构建：

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
mkdocs build --strict

GitHub Pages 工作流使用 GitHub Actions 官方 Pages artifact/deploy 流程。仓库中 mkdocs.yml 是导航和 Markdown 扩展的唯一配置入口。