源码导航图¶

本页把“想回答的问题”映射到建议阅读顺序。路径均相对于 paperclip-master 快照；上游源码入口可从Paperclip GitHub打开。

1. 从一个问题开始¶

你想回答的问题	先看	再看
Agent 为什么被唤醒	`server/src/services/heartbeat.ts :: enqueueWakeup`	`agent_wakeup_requests.ts`、assignment/dependency/recovery services
Agent 实际做了什么	`heartbeat.ts :: executeRun`	`adapter-utils`、`heartbeat_runs.ts`、run-liveness
谁拥有 Issue	`services/issues.ts :: checkout`	`schema/issues.ts`、`routes/issues.ts`、checkout tests
为什么不能抢任务	checkout conditional update	stale adoption、release、recovery
为什么 UI 有延迟	`LiveUpdatesProvider.tsx`	`live-events-ws.ts`、query invalidation batcher
工具为什么被拒绝	`tool-gateway.ts`	`tool-access.ts`、policy/profile schemas、MCP governance doc
Secret 怎样进入进程	`services/secrets.ts`	agent secret bindings、tool credential refs、run setup
插件能做什么	`doc/plugins/PLUGIN_SPEC.md`	worker manager、host services、manifest validator
技能怎样运行	`company-skills.ts`	skills catalog、runtime selections、adapter skills
任务为什么卡住	recovery service + issue-liveness	run status、leases、watchdog、workspace operations
发布怎样验证	`.github/workflows/release-verify.yml`	release.sh、Docker smoke、package map

2. 入口按层排列¶

flowchart TB
  SH["shared: constants / types / validators"]
  DB["db: schema / migrations"]
  RT["adapter-utils: execution SPI"]
  SR["server: routes / services / middleware"]
  UI["ui: pages / API / Query / WebSocket"]
  CL["cli: setup / context / control-plane client"]
  EX["plugins / skills / teams / MCP"]
  SH --> DB
  SH --> RT
  DB --> SR
  RT --> SR
  SR --> UI
  SH --> UI
  SR --> CL
  EX --> SR

3. Server 目录地图¶

目录	读法
`server/src/routes/`	HTTP 形状、输入校验、状态码、actor/resource 入口
`server/src/services/`	业务状态机、transaction、恢复、副作用
`server/src/middleware/`	actor、日志、压缩、hostname、mutation guard
`server/src/realtime/`	WebSocket upgrade、ping/pong、terminal/live channels
`server/src/auth/`	Better Auth、JWT 与 session 辅助
`server/src/services/recovery/`	liveness、retry、orphan、notice
`server/src/__tests__/`	高风险服务的行为与并发边界

4. 最值得优先搜索的符号¶

enqueueWakeup
executeRun
setRunStatusFromLive
checkout
release
adminForceRelease
resolveAuthorization
isAgentInvokable
resolveExecutionWorkspace
acquireEnvironmentLease
finalizeWorkspace
publishLiveEvent
toolGatewayService
refreshCatalog
evaluatePolicy
materializeRuntimeSkills
reconcile

5. 上游路径链接¶

下面的链接指向上游仓库 master，行号可能随上游变化；以文件和符号为主要定位手段。

6. 测试优先阅读¶

如果要确认某个不变量，不要只读实现，优先搜索测试主题：

rg -n "checkout|stale|idempot|concurr|budget|lease|liveness" \
  server/src/__tests__ packages ui cli

测试往往把“什么时候必须拒绝”写得比产品说明更精确。