20 · 源码地图与阅读路线

这是一张“从问题到源码”的索引。先选目标，再沿入口 → 核心符号 → 测试/规范走；不要从 3300 多个文件的目录树盲目翻。

1. 30 分钟全局路线

README.md
  ↓ 产品能力与状态
Cargo.toml + AGENTS.md
  ↓ workspace 边界
crates/buzz-core/src/{event,kind,tenant}.rs
  ↓ 协议原子与租户围栏
crates/buzz-relay/src/{state,ingest,req,event}.rs
  ↓ Relay 真正主链
schema/schema.sql
  ↓ 权威数据形态
ARCHITECTURE.md（最后读，用于对照设计意图）

最后读 ARCHITECTURE.md 是为了先形成实现证据，避免被过期图示锚定。

2. 半天 Relay 深潜

1. buzz-core::TenantContext 与 host resolver。
2. connection.rs 的任务/队列/取消。
3. handlers/auth.rs 的 NIP-42 → ban → membership。
4. ingest.rs::ingest_event，挑消息/回复/编辑三类跟踪。
5. buzz-db::Db::insert_event 和 transaction。
6. event.rs::dispatch_persistent_event 与 fan-out gate。
7. req.rs::handle_req、query builder、event_visible_to_reader。
8. subscription.rs 的 scope/index/refcount。
9. 用 buzz-test-client E2E 对照行为。

3. Crate 地图

Crate	先读	再读
buzz-core	event.rs, kind.rs, tenant.rs	filter.rs, channel.rs, pairing/, git_perms.rs
buzz-relay	main.rs, state.rs, connection.rs	ingest.rs, req.rs, event.rs, subscription.rs, handlers/, api/
buzz-db	lib.rs, event.rs	thread.rs, workflow.rs, push.rs, replica_fence.rs, git_repo.rs
buzz-auth	lib.rs, scope.rs	NIP-98 helpers/tests
buzz-pubsub	lib.rs	presence.rs, rate_limiter.rs, nip98_replay.rs
buzz-search	lib.rs	SQL tests + search migrations
buzz-audit	lib.rs, hash.rs	verification tests
buzz-sdk	builders.rs	message/channel/Git builder tests
buzz-workflow	schema.rs, lib.rs	executor.rs, action_sink.rs
buzz-acp	README.md, lib.rs	relay.rs, queue.rs, pool.rs, acp.rs
buzz-agent	agent.rs, config.rs	mcp.rs, providers/, integration tests
buzz-persona	parser/resolver modules	path safety tests
buzz-dev-mcp	tool registry	shell/file/image tool implementations
buzz-media	storage + validation entry	each format parser/tests
buzz-push-gateway	main.rs, http.rs	postgres.rs, App Attest/APNs/metrics
buzz-relay-mesh	lib.rs/runtime	transport, directory, membership, tunnel
buzz-cli	README.md, lib.rs	commands/, TESTING.md
buzz-conformance	checker/model	proptest + fixtures

4. 按问题定位

“为什么这个用户能/不能看到事件？”

kind privacy set
  → req.rs::event_visible_to_reader
  → event.rs::filter_fanout_by_access
  → db member/shared/result queries
  → conformance tests

“EVENT 返回 OK 后发生了什么？”

connection protocol dispatch
  → ingest.rs::ingest_event
  → buzz-db insert/transaction
  → event.rs::dispatch_persistent_event
  → PubSub/local fan-out/workflow

“为什么多 pod 不重复/丢掉状态？”

• Live events：local echo cache + Redis，允许短暂通知丢失，历史补偿。
• Push：PostgreSQL outbox + claim lease + generation revalidate。
• Huddle/Mesh：session lease + monotonic generation fence。
• Git：immutable uploads + manifest pointer CAS。

“Agent 如何回复一条频道消息？”

Relay subscription
  → buzz-acp relay task
  → EventQueue / PromptBatch
  → ACP session prompt
  → buzz-agent LLM/tool loop
  → MCP / Buzz CLI
  → signed reply event back to Relay

“一个功能到底完成了吗？”

按顺序看：

1. Kind/schema 是否存在。
2. ingest/query 是否接入。
3. DB migration/projection 是否存在。
4. action/handler 是否返回 NotImplemented/skipped。
5. App/CLI 是否有入口。
6. E2E/deploy workflow 是否覆盖。

只满足前两项通常只是协议基础，不是用户闭环。

5. 数据层专题路线

Event store

schema.sql events → migrations 0001–0026 → buzz-db/event.rs → ingest.rs → REQ/search。

Read replica

buzz-db/lib.rs::ReadSession → replica_fence.rs → readiness/metrics → DB integration tests。

Audit

buzz-audit/lib.rs::log → hash.rs → schema audit tables → Relay bounded worker/drain。

Search

schema search_tsv → migrations 0005/0008/0014 → buzz-search → Relay hydrate/read gate。

6. Agent 专题路线

想理解	路线
并发/顺序	queue.rs → pool.rs → cancel/steer tests
重连补偿	relay.rs command loop → watermark/since → reconnect tests
模型循环	buzz-agent/agent.rs → provider adapters → fake LLM/golden transcript
工具安全	buzz-agent/mcp.rs → buzz-dev-mcp shell/file/image → regression tests
Persona	buzz-persona manifest/frontmatter → merge → safe skill path
Desktop 管理	desktop/src-tauri/managed_agents/ → commands → React agent UI

7. 安全规范与形式化路线

主题	规范/模型	实现
多租户 Relay	MultiTenantRelay.tla	tenant/ingest/req/fan-out/conformance
认证	MultiTenantAuth.spthy	buzz-auth + Relay auth handler
Push lease	NIP-PL.md + formal/nip-pl	DB push + gateway
Git CAS	GitOnObjectStore.tla + design doc	Relay api/git
Agent memory	NIP-AE.md	core engram + ingest/read gates
Pairing	NIP-AB core types/state	pair relay + clients
Git signing	NIP-GS.md	git sign/credential helpers

8. 客户端路线

Desktop

tauri.conf.json → src-tauri/lib.rs command registration → app/AppShell.tsx → feature route/component → corresponding Tauri command → Relay/SDK call。

Web

web/src/main/router → query/client store → nostr/Relay adapter → Playwright smoke。

Mobile

pubspec.yaml → mobile/lib/main.dart → providers/services → screens/widgets → test + platform entitlement。

CLI

buzz-cli/src/lib.rs Clap tree → commands/<domain>.rs → buzz-cli-core client → SDK/NIP-98。

9. 运维路线

.env.example / config structs
  → Justfile dev commands
  → deploy/compose
  → deploy/charts values + schema
  → health/readiness/metrics
  → .github/workflows docker/chart/release
  → docs deployment/runbooks

Push Gateway、Git/S3、Mesh 等应分别走自己的路线，不要只看 Relay chart。

10. 搜索关键词表

在本地用 rg：

目标	关键词
未完成项	`NotImplemented
租户围栏	`community_id
权限	`event_visible_to_reader
事务边界	`begin(
Fence	`generation
背压	`try_send
限制	`MAX_
指标	`metrics::counter

11. 快照局限

本地 buzz-main 不含 .git 历史，不能回答“某行何时/为何引入”或精确关联 PR。遇到需要演进因果的问题，应在上游 GitHub 用 git blame/PR/issue 继续取证；本拆解只确认快照内部自洽性。

12. 顶级入口

• Buzz 上游仓库
• Workspace Cargo.toml
• 架构文档
• 数据库 schema
• NIP 规范目录
• 形式化模型目录
• CI