00. 文档哲学 (Philosophy)

核心目标: 即便源代码完全丢失，AI Agent 也能仅凭这套“白皮书”完整复原 KeyApp 及其生态系统。

1. AI-First (AI 优先)

白皮书的第一读者是 AI Agent。人类读者的可读性是第二位的。

• 全息复原 (Digital Twin): 文档是代码的数字孪生。它不仅仅描述“是什么”，更包含了“怎么做”的全部逻辑蓝图。
• 显式上下文: 所有依赖关系、数据结构、状态流转必须显式声明。不要让 AI 猜测。
• 结构化表达: 优先使用 Mermaid 图表、Type Definitions、决策树和状态机表格，而非自然语言叙事。

2. Multi-Dimensional Access (多维交叉索引)

AI 在解决不同问题时（如修复 Bug、开发新功能、重构架构），会采用不同的检索路径。文档结构必须支持多维度的切入：

• 物理视图 (File-System View): 严格映射代码目录结构 (src/services/wallet -> 10-Wallet-Guide).
• 逻辑视图 (Logical View): 按功能模块组织 (如 "支付流程" 涉及 UI、Store、Service、Driver 多个层级).
• 数据视图 (Data View): 按数据流向组织 (如 "余额更新" 如何从链上流向 UI).

3. Strict Code Mapping (严格代码映射)

• 原则: 每一个重要的源代码文件，必须在文档中有且仅有一个对应的 Markdown 文件/章节。
• 定义"重要": 任何包含业务逻辑、状态管理、核心算法、接口定义的文件都是重要的。仅包含纯样式或简单透传的文件可忽略。
• 双向锚点:
  • 文档必须包含 Code Source 链接指向代码。
  • 代码注释必须包含 Doc Ref 指向文档（理想状态下）。