Agent 学习项目实战清单

项目主线

不要做一堆互不相关 demo。所有项目都围绕一个最终作品累积:

Personal Knowledge Agent:基于 Obsidian 的个人知识库 Agent。

flowchart TD
    P0["P0 LLM Chat API"] --> P1["P1 Tool Calling"]
    P1 --> P2["P2 Obsidian RAG"]
    P2 --> P3["P3 Notes MCP Server"]
    P3 --> P4["P4 Learning Planner"]
    P4 --> P5["P5 Trace / Eval"]
    P5 --> Final["Personal Knowledge Agent"]

项目分级

主项目纵向切片

不要按“先写完模型层、再写完工具层、再写完 RAG 层”的方式推进。更稳的做法是每一轮都交付一个能从输入跑到证据和 trace 的纵向切片。

flowchart TD
    S0["Chat"] --> S1["Tool"]
    S1 --> S2["RAG"]
    S2 --> S3["MCP"]
    S3 --> S4["Planner"]
    S4 --> S5["Eval"]
    S5 --> PKA["PKA"]

纵向切片的价值是:每一步都能演示,每一步都能失败复盘,每一步都能继续扩展。横向堆模块很容易看起来“架构完整”,但用户问题进来后跑不通。

后端模块边界

判断边界是否清楚:删掉某个模块的实现细节,其他模块仍然知道“怎么调用它、得到什么结果、失败怎么看”。如果必须读完整源码才能知道模块怎么用,边界还没立住。

最小交付包

作品集不是只放代码仓库。每个阶段都应该有可检查交付包:

当前 demo 对照

demo 目录已经覆盖了第一个可运行纵向切片,不再只是空壳工程。

迭代节奏与质量红线

这个项目最容易失败的方式不是技术做不出来,而是每周都“看起来做了很多”,最后没有一个可复盘的系统。迭代要按纵向切片推进,每次只扩一个能力,但必须补齐证据链。

质量红线:

每周最小交付格式:

P0:LLM Chat API

目标

做一个可维护的模型调用后端,而不是 SDK demo。

功能

最小类结构

final class ChatController {
    private final ChatService chatService; // 接收 HTTP 请求，不写模型细节
}

final class ChatService {
    private final ModelGateway modelGateway; // 统一封装不同模型供应商
    private final ChatTraceRepository traceRepository; // 保存请求、耗时、token、错误
}

P1:Tool Calling Demo

目标

让模型调用真实后端能力,但所有执行都由服务端控制。

工具清单

调用链

验收

• 工具参数错时不会执行。
• 危险工具需要确认。
• 每次工具调用有 trace。
• 工具失败后模型能解释失败并给下一步。

P2:Obsidian RAG

目标

让 Agent 基于 F:\2. ObsidianNotes 回答,并且必须带来源。

MVP 范围

验收问题

P3:Notes MCP Server

目标

把笔记能力暴露给其他 Agent 客户端。

flowchart TD
    Client[MCP Client] --> Server[Notes MCP Server]
    Server --> Search[search_notes]
    Server --> Read[read_note]
    Server --> Recent[recent_notes]
    Server --> Map[get_ai_agent_map]
    Search --> Index[(Note Index)]
    Read --> Files[Markdown Files]

工具规格

当前 demo 的 MCP 落地边界

当前 demo 的 Memory 落地边界

当前 demo 的 Trace 落地边界

P4:学习计划 Agent

目标

从“问答”升级为“规划 + 执行追踪”。

状态表

验收

• 每个任务都有可检查产出。
• 未完成任务能滚动到下周。
• 计划能引用已有笔记。
• 复盘能改变下一周任务,而不是固定模板。

P5:Trace / Eval / Observability

目标

能复盘 Agent 为什么这么回答、为什么调用这个工具、为什么失败。

flowchart LR
    Input[User Input] --> Trace[Trace Event]
    Retrieval[Retrieved Chunks] --> Trace
    Tool[Tool Calls] --> Trace
    Model[Model Input/Output] --> Trace
    Trace --> Debug[Debug Report]
    Eval[Eval Cases] --> Debug

必记字段

项目依赖关系

graph TD
    P0 --> P1
    P0 --> P2
    P1 --> P3
    P2 --> P3
    P2 --> P4
    P3 --> P4
    P4 --> P5

作品集规格

优先级判断

核心结论

这组项目不是 6 个 demo,而是一个作品从底座到产品化的 6 次迭代。