从哪里开始读代码

开发者文档不复制 Spec，也不把每个目录重新列一遍。它负责回答三个问题：代码从哪里进入、关键规则在哪里、什么测试能证明修改没有破坏行为。

先顺着一次调用读，不要按目录字母序读

interfaces/cli/main.py        解析命令，调用 bootstrap/application
        ↓
bootstrap.py                  读取可信配置并组装具体 adapter
        ↓
application/agent_loop.py     推进一次 Run，不实现 SDK 或文件细节
        ↓
runtime/*                     Context、Reducer、预算、Policy、Executor
        ↓
ports/*                       核心要求外部实现提供什么
        ↓
adapters/model|sqlite|tools   把 SDK、数据库和文件系统翻译到内部契约

第一遍只跟成功路径。第二遍选择一个失败，例如非法路径或预算耗尽，查看 Error 怎样变成 Event 和最终 RunState。第三遍再读安全测试，确认你看到的是受测试约束的边界，不只是代码恰好这样写。

一个 30 分钟源码实验

在 interfaces/cli/main.py 找到 run 命令调用；
在 bootstrap.py 找到 config/profile 怎样选择 adapter 和 Tool；
在 application/agent_loop.py 找到 Model 与 Tool Activity 前后的 Event append；
在 runtime/tool_executor.py 找到 Registry、prepare、Policy 与 adapter 的唯一执行路径；
运行 uv run pytest tests/integration/test_run_cli.py -q，对照成功、非法输入与查询失败的测试。

随后运行 uv run pytest tests/security/test_runtime_files.py -q，观察默认配置和自定义配置怎样被同一个文件边界保护。这组测试使用伪造 key，不需要读取你自己的配置。

第一次阅读

先看当前实现状态，避免把路线图当成已有功能；
如果还没实际运行过 P1，先走一遍第一次运行；
用Runtime 各部分怎样协作和P1 架构取舍理解调用与依赖方向；
找到当前 Feature 的 Spec、相关 ADR 和 Plan；
按下面的实现导读进入代码和测试；
修改后运行完整验证和治理检查，并为每个文档表面记录更新路径或 N/A 原因。

当前实现导读

F-0001：内部数据类型——ID、Message、Error、Event 以及模型 adapter 的翻译边界；
F-0002：状态和预算——具体 Event、Reducer、预算检查和修改顺序；
F-0003/F-0021：SQLite EventStore 与只读重建——transaction、migration、projection、Event-only 快照与故障测试；
F-0004/F-0017：ModelProvider 与协议 adapter——显式 protocol factory、三种流式翻译、Provider selection 和 live gate；
F-0006：Tool 执行边界——Registry、参数准备、默认拒绝 Policy 和统一 Executor；
F-0007：workspace 只读 Tool——跨平台路径边界、list/read/search 和安全测试；
F-0008：原子输出与 Artifact——同目录暂存、原子提交、结果元数据和故障窗口；
F-0016/F-0018：有界 Agent Loop 与证据边界——Context、RunCreated v4、contract fingerprint、串行调度和 K1-K6；
F-0019：安全结构化运行诊断——Event 写入数据库后输出有限日志，并保证日志失败不影响 Run；
F-0005/F-0020：生产 CLI 与查询——默认初始化、离线检查、composition root、inspect/events 和失败边界；
Feature 完成时怎样更新文档——哪些事实写在 docs/，哪些解释写在站点；
本地运行文档站——安装、构建和检查 Starlight。

不同问题去哪里找答案

P1 已于 2026-09-08 收口，F-0020 的配置保护、初始化和离线检查已合入 main，跨平台 CI 通过。P2 恢复和 P3 授权/隔离没有实现。F-0021 的 replay/check 已完成收口并通过跨平台 CI，保持只读；提交与验证记录见 PR #26。研究策略应通过未来的 port 提出建议，由 Runtime 保持执行约束。顺序和实验指标见从一次失败走向可比较的研究实验。

你要确认什么	首选位置
这个功能必须做到什么	Feature Spec
为什么选择当前方案	ADR
准备按什么顺序实现	Implementation Plan
当前模块如何连接	Architecture
行为是否真的成立	代码、测试和可复现命令
当前版本能否使用	站点状态页 + implemented Spec

S1 只写足够验收的精简 Spec，只有多片实施时才增加 Plan；S2 才使用完整 Spec、ADR 和 active Plan。提交前运行 uv run python scripts/check_governance.py，检查状态、索引、完成清单和内部引用。文档表面没有受到影响时记录 N/A 和原因，不为内部重构制造站点改动。

聊天讨论可以提出问题，但不会自动改变这些事实。决定只有写入仓库并通过审查后才生效。