这篇文档是「AI Native全链路开发实战」知识库的统一入口。你不需要第一次就把所有文章从头读到尾，更合适的做法是先确定目标：是想尽快用上 Codex，还是想掌握 OpenSpec 的规范驱动流程，或者准备深入阅读 OncallAgent 的真实源码。
📷 [图片 token=VbjQbNHr4oA5DVxIC5JcwKsDnSc（未能下载，见飞书原文）]
整套内容围绕两个问题展开：怎样让 AI Coding 从“能生成代码”变成可规划、可验证、可维护的工程协作；怎样在一个真实项目中理解知识检索、Agent、MCP、AIOps 诊断与证据报告之间的关系。
📷 [图片 token=BBxHb3eXioPK4axcBzocMolKnjc（未能下载，见飞书原文）]
[!SUCCESS] **第一次阅读建议：**先完成「AI Coding 基础与工程约束」，再进入 OpenSpec 实践，最后阅读 OncallAgent 源码系列。已经有相关经验的读者，可以直接按下方目标表跳转。
这套知识库包含什么
02. AI Coding 基础与工程约束负责解决“怎样与 Codex 协作”的问题。从工具安装、需求表达，到 SDD 与 AGENTS.md，它帮助你建立最基础的 AI 编程工作习惯。
03. OpenSpec 工程化实践：从变更建模到知识沉淀负责解决“怎样把需求变成可追踪工程资产”的问题。这里会讲 proposal、delta specs、design、tasks、main specs，以及实现、验证、同步、归档和知识站沉淀的完整过程。
04. OncallAgent 功能与源码解析负责解决“这些工程方法怎样落到真实项目”的问题。OncallAgent 是一个本地优先的 AIOps Agent 工作台，前端使用 Vue 3、Vite 和 TypeScript，后端使用 FastAPI，并实现了知识检索、流式 Agent、用户级 MCP、LangGraph 诊断与证据报告等链路。
📷 [图片 token=T8vhbCQ3DosGACxzFMncG5eonEh（未能下载，见飞书原文）]
按学习目标选择入口
| 你的目标 | 建议先读 | 读完应该获得什么 |
|---|---|---|
| 第一次接触 AI Coding | Codex 与 OpenSpec 快速安装使用 | 完成环境准备，并走通一次最小 OpenSpec 流程 |
| 经常遇到 AI 跑偏或返工 | 规范驱动开发 SDD、AGENTS.md 详解 | 理解需求规范与仓库规则分别约束什么 |
| 想系统掌握 OpenSpec | OpenSpec 全流程实操介绍 | 建立从变更提出到归档沉淀的完整心智模型 |
| 想理解 RAG 与流式 Agent | 07. 知识文档上传、切分、索引与页面状态、09. LangChain 流式 Chat Agent 与前端 SSE | 看清知识进入系统、被检索并参与回答的链路 |
| 想理解真实 AIOps 诊断 | 11. 用户级 MCP 连接与真实工具调用、12. 告警到证据报告的 LangGraph 诊断闭环 | 理解从告警、SOP、工具取证到证据报告的闭环 |
| 准备简历或技术面试 | OpenSpec 高频追问与回答、怎么把 OpenSpec 融入简历描述 | 把真实做过的工程工作转化为准确表达 |
推荐主线：从会用工具到读懂项目
**第一阶段：建立 AI Coding 的基本动作。**先读项目开发经历，理解 AI 提升速度的前提并不是“自动完成一切”，而是人先做出边界与验收判断；然后完成 Codex 和 OpenSpec 的安装，再学习 SDD 与 AGENTS.md。
📷 [图片 token=WCCTbvnyGoCKurxZZ45c0j2znrr（未能下载，见飞书原文）]
**第二阶段：把一次需求沉淀为可检查的变更。**进入 OpenSpec 专题后，不要只记命令。重点是看清每份产物回答的问题、它们怎样相互约束，以及代码和测试怎样成为验收证据。
**第三阶段：用 OncallAgent 验证这些方法。**先建立架构全景，再按照共享契约、数据边界、知识链路、Agent 运行时、真实工具和诊断闭环逐步下钻。阅读源码时同时对照主规格与测试，不要仅凭文件名猜测系统行为。
**第四阶段：完成一次自己的纵向练习。**选择一个范围足够小的需求，从 proposal、spec、design 和 tasks 开始，经过实现、测试、verify、sync 与 archive。练习的目标不是生成更多代码，而是形成一条别人可以复查的需求—实现—证据链。
📷 [图片 token=UnxmbIJe4ob4WlxKXAPcchD2n3d（未能下载，见飞书原文）]
OpenSpec 专项阅读路线
如果你的主要目标是掌握 OpenSpec，可以按照“先看完整流程，再理解单个产物，随后学习追踪、归档和案例”的顺序阅读。
📷 [图片 token=SB9xbpEWZoe8WsxFHVAcLzkbnTd（未能下载，见飞书原文）]
OpenSpec 开发闭环：先建立从提出变更到完成归档的全局视角。
OpenSpec 核心产物：逐篇理解元数据、proposal、delta spec、design、tasks 与 main spec 的职责边界。
OpenSpec 追踪链路介绍：学习怎样把需求、场景、设计、任务、代码和测试连成证据链。
OpenSpec 归档与知识沉淀：理解 archive、wiki-sync 与仓库知识站之间的分工。
VitePress：启动与浏览 OncallAgent 项目知识站：在本地查看归档变更形成的项目知识页面。
OpenSpec 真实案例：通过 Qwen Embedding 批量限制和检索阶段排名可见化理解不同规模的变更。
OncallAgent 源码阅读路线
OncallAgent 目录中的 15 篇文章保持平铺编号。下面的分段只是阅读建议，不会改变实际目录结构。第一次阅读建议按编号前进；已经熟悉某一部分时，可以直接从对应阶段切入。
📷 [图片 token=HIGsbjDENohYLLxFW6Ncgb6lnec（未能下载，见飞书原文）]
**01～05：先建立系统边界。**这一段依次解释组合根、共享契约、认证与 tenant 隔离、模型配置，以及 Milvus 等本地基础设施。
📷 [图片 token=NXXfb6VUOoHaOXxCEYocuCpenZf（未能下载，见飞书原文）]
**06～10：理解知识链路与对话运行时。**这一段从持久化后台任务开始，串起知识文档摄取、混合检索、LangChain 流式聊天，以及 Prompt、Skill 和记忆配置。
📷 [图片 token=XKibb2xUQoF5ekxLhXgcMPKonOq（未能下载，见飞书原文）]
**11～15：进入真实工具与 AIOps 闭环。**这一段关注用户级 MCP、Alertmanager 告警入口、LangGraph 诊断、案例沉淀、工具审计、用户反馈和本地运行状态。
📷 [图片 token=NS9VbuSyHoPB8bx1HExcRUkgnje（未能下载，见飞书原文）]
阅读时始终保留三条工程判断
**先确认边界，再让 AI 执行。**需求、非目标、接口契约和验收方式如果没有明确，模型生成得越快，返工可能越多。
**让规格、实现和测试互相印证。**OpenSpec 产物不是为了增加文档数量，而是让每个重要判断都有位置，让代码变更可以被追踪和验证。
**证据不足就明确说明。**OncallAgent 的诊断结论必须建立在授权知识、真实 MCP 工具结果和持久化证据之上。没有日志、指标或工具返回时，不能编造根因、执行动作或成功状态。这既是项目约束，也是学习 AI Native 工程时最重要的可信性原则。
📷 [图片 token=WwXsbRmj1o9XYaxLFKocg00SnQb（未能下载，见飞书原文）]