# M11 / issue-103 M4 AI 工具链从 Provider 到角色边界教程正文

- Issue：`#103`
- 里程碑：`M11 教程正文整理：从大纲到系列文章`
- 分支：`fys-dev/docs-m11-issue-103-m4-ai-article`
- 日期：`2026-03-27`

## 背景

`M2` 与 `M3` 正文已经落地，但 `M4` 目前仍主要停留在里程碑大纲和 issue 级开发日志层。

为了让读者真正理解“AI 工具链为什么要先拆 Provider、再做文件提取、缓存结构与角色边界”，本轮继续按教程整理流程，把 `M4` 扩写为一篇可独立阅读的正文文章。

## 本次目标

- 在 `docs/50-教程文章/` 中新增 `M4` 正文
- 更新正文目录，让 `M2 -> M4` 阅读路径连续
- 保持正文聚焦 `M4` 的 AI 最小闭环，不越界扩写 `M5 ~ M10`
- 继续维持正文、大纲、开发日志三层职责分离

## 非目标

- 不新增功能代码
- 不修改现有 `M4` 实现
- 不同时扩写其他里程碑正文
- 不把文章写成开发日志或提交记录

## Plan

1. 先复盘 `M4` 大纲与 `issue-13 ~ issue-16` 开发日志
2. 提炼正文主线，围绕“为什么先做 AI 最小闭环”组织全文
3. 更新正文目录，补齐本轮开发日志
4. 做文档级 review 与人工校对，再进入提交阶段

## 实际改动

- 更新 `docs/50-教程文章/README.md`
- 新增 `docs/50-教程文章/03-M4-AI-工具链从-Provider-到角色边界-为什么先做最小闭环.md`
- 新增本篇开发日志，记录本轮文档任务

## Review 记录

### 是否符合当前 Issue 与里程碑目标

符合。当前只做了：

- 增加 `M4` 正文文章
- 更新正文目录入口
- 补充本轮文档开发日志

没有提前进入：

- `M5 ~ M10` 正文扩写
- 功能实现或重构
- 文档体系大规模改动

### 是否存在可继续复用的结构

- 当前正文结构仍可继续复用到后续里程碑：
  - 为什么这个里程碑不能一上来就做重
  - 本轮真正交付什么
  - issue 拆解顺序
  - 关键设计取舍
  - 测试重点
  - 容易踩的坑
  - 与下一里程碑的衔接
- `docs/50-教程文章/README.md` 已形成连续正文目录，后续可继续顺序扩展

### Review 结论

- 通过
- 可进入文档级自测

## 自测结果

### 1. 正文目录校对

- 检查 `docs/50-教程文章/README.md` 是否包含 `M2 -> M4` 连续入口
- 结果：通过

### 2. 正文范围校对

- 检查文章是否仍聚焦 `M4` 的 AI 最小闭环
- 结果：通过
- 备注：正文围绕 Provider、文件提取、缓存报告与角色边界展开，没有扩写到后续队列、持久化与后台工作台实现

### 3. 文档分层校对

- 检查正文、大纲、开发日志之间是否职责清晰
- 结果：通过
- 结论：
  - `docs/40-教程与博客/` 继续保留里程碑大纲
  - `docs/30-开发日志/` 继续保留 issue 过程记录
  - `docs/50-教程文章/` 继续沉淀对外正文

## 遇到的问题

### 1. AI 主题很容易被写成“接 SDK 教程”

- 风险：如果正文只围绕某个厂商 SDK 展开，后续 provider 抽象与角色边界会被弱化
- 处理：改为围绕“为什么先做最小闭环”组织全文，把厂商调用放回适配层上下文中

### 2. `M4` 的实现天然容易扩到后续阶段

- 风险：很容易顺手把队列、Redis、持久化和更复杂工作流提前写进正文
- 处理：明确把正文边界限定在 `M4` 当前已完成的最小 AI 链路

## 后续可继续沉淀的点

- 继续按相同模板扩写 `M5 ~ M10` 正文
- 当正文数量足够后，再整理成面向外部读者的系列导航或 VitePress 侧边栏
