参考手册¶

参考手册适合查字段、入口和枚举，不负责从头教授架构。先明确你在查什么，再进入对应文档；直接打开最大的 JSONL 或事件目录，通常只会得到一个没有 owner 的字符串。

查命令：先分本地动作还是 Agent prompt¶

CLI 命令树 解释进程入口、flags 和子命令；Slash Command 参考 区分 local、local-jsx 与 prompt 三种 command type，以及 interactive、print、SDK、thin client 的实现 twin。

当一个命令“看起来执行了却没产生结果”时，先确认它只是打开 UI、写本地设置、展开成 Agent prompt，还是向宿主发 RPC。命令 handler 返回成功，不等于后续模型已经完成业务目标。

推荐顺序： CLI 命令树 -> 复杂 Slash Command 生命周期 -> CLI、SDK 与输出协议。

查工具：从 registry 回到执行合同¶

核心工具参考 记录内置工具的 schema、输入约束、权限与副作用；工具注册与宿主表面 解释 canonical name、alias、deferred 工具和不同 host 的可用集合。

看到一个工具名时，不要直接推断它在当前 session 可用。还要看 provider capability、workspace trust、feature/policy gate、工具 generation 与 host surface。

推荐顺序： 核心工具参考 -> 工具、权限与 Hooks -> Hook 事件参考。

查设置：字段存在不等于当前生效¶

Settings 全字段参考 适合查类型、默认和来源；Settings Resolution 与 Reload 解释 user/project/local/managed/CLI/environment 的逐字段合并、限制和 live reload；Feature Flags 与 Remote Config 处理远端求值、缓存和 Boundary。

同一个 setting 的值可能受来源限制、managed lock、当前运行模式与二次 gate 影响。只在 schema 里找到字段，最多证明声明存在。

查扩展：先确定谁提供能力¶

Plugins、Skills、Commands 与 LSP 解释本地扩展发现与缓存；MCP Runtime 生命周期 解释远端 server 的连接、认证、工具 generation 和动态刷新；Connectors、Catalog 与 MCP Operators 处理更高层的目录与操作入口。

Skill 是上下文与工作流材料，MCP 是运行时协议，Plugin 可以同时贡献命令、Hook 或工具。名称相近不代表状态 owner 相同。

查会话和存储：先确认恢复对象¶

Storage v5 参考 用于查本地持久结构；会话、Checkpoint 与 Memory 解释消息图、compact boundary、fork 和 rewind；项目 Purge、Import 与数据生命周期 解释预览、digest、archive guard 与部分完成。

删除本地文件、清理 transcript、rewind 代码和撤销远端动作是四类不同操作，不要因为都叫“恢复/清理”就混用。

查遥测、错误和 API：先找状态机，再找事件名¶

遥测事件目录 适合按场景查事件、payload 和出口资格；错误与诊断图谱 把异常连接到分类、恢复、用户结果和观察面；API、Beta 与路由所有权 区分真实 consumer、SDK 依赖、embedded reference 与远端 Boundary。

事件名、错误文案、URL 或 beta 字符串本身不证明调用发生。优先找到 owning mechanism，再用目录定位字段和源码位置。

推荐顺序： 遥测、日志与诊断 -> 遥测事件目录 -> 错误与诊断图谱。

查机器清单：用稳定字段做版本对比¶

机器清单字段阅读指南 解释 comparisonKey、comparisonValue、lexical function、immediate consumer 和证据等级。跨版本时先用稳定语义字段配对，再回到 reachable consumer；行号、minified symbol、bytecode hash 或整块反汇编变化不能单独升级成功能变化。

环境变量和 Feature key 的全量参考用于防漏，不是按名称猜功能的词典。它们记录 Static immediate consumer 时，只证明值接下来流向哪里；完整 fallback、状态变化、失败和用户影响仍要回到机制专题。

三个超大参考页不会把整页正文塞进浏览器搜索索引。需要按精确名称查找时，使用轻量的 Environment 标识符索引、Feature Key 标识符索引和 Telemetry Event 标识符索引；定位名称后再进入完整参考阅读 consumer、字段和 Boundary。

需要全部入口时¶

完整文章索引保留全部教程、参考手册和证据入口；2.1.235 深度技术指南适合已经建立运行模型后做系统查漏。不要把深度指南当第一篇，它的作用是覆盖，不是替代渐进解释。