Agent 学习工作台

12 周 agent 架构学习方案 · 共 60 天

1第 1 周 · 代码阅读方法论(layer0)

第 1 周 · 第 1 天 · layer0待开始

代码阅读方法论

什么是「读懂一段代码」— 用 siliconflow.ts 示范三步：画流程骨架→标注函数意图→追踪数据变化

code_readingflow_skeletonfunction_intentdata_tracing

阅读文件：data/sources/apps/web/lib/ai/siliconflow.ts

第 1 周 · 第 2 天 · layer0待开始

代码阅读方法论

顺序执行的代码 — 读 reextract-v2.ts 前 50 行，用「变量追踪法」手动跑一遍值的变化

sequential_executionvariable_tracingstate_mutation

阅读文件：data/sources/apps/web/lib/batch/reextract-v2.ts

第 1 周 · 第 3 天 · layer0待开始

代码阅读方法论

条件分支与循环 — 读 books.ts 的查询构建部分，追踪 queryBuilder 条件拼接逻辑

conditional_branchquery_buildercontrol_flow

阅读文件：data/sources/apps/web/lib/db/books.ts

第 1 周 · 第 4 天 · layer0待开始

代码阅读方法论

交错练习：混合本周三种代码模式（顺序执行 + 条件分支 + API 调用），找一段代码说出用了哪些模式

interleaved_practicepattern_recognitionmixed_patterns

第 1 周 · 第 5 天 · layer0待开始

代码阅读方法论

本周闭眼回顾 — 不看代码，口头描述第一周学到的四种代码模式，写下来对照

review_week1recall_testcode_patterns

2第 2 周 · Agent 循环的直觉建立(layer0)

第 2 周 · 第 1 天 · layer0待开始

Agent 循环的直觉建立

最简 Agent 循环 — 画「输入→LLM 判断→工具执行→结果返回→判断完成？」流程图，对照 reading-plan 生成端点

agent_loopperceive_reason_actllm_decisiontool_routing

阅读文件：data/sources/apps/web/app/api/reading-plan/generate/route.ts

第 2 周 · 第 2 天 · layer0待开始

Agent 循环的直觉建立

上下文是什么 — 读 prompt-manager.ts，理解 message 数组如何拼接，什么时候上下文会爆

context_windowmessage_arrayprompt_compositiontoken_limit

阅读文件：data/sources/apps/web/lib/prompt-manager.ts

第 2 周 · 第 3 天 · layer0待开始

Agent 循环的直觉建立

工具调用的触发 — 读 extract-v2.ts 第一段，理解 function calling 的 schema 定义与触发条件

tool_usefunction_callingschema_definitiontrigger_condition

阅读文件：data/sources/apps/web/lib/prompts/extract-v2.ts

第 2 周 · 第 4 天 · layer0待开始

Agent 循环的直觉建立

交错练习：Week 2 的循环+上下文+工具与 Week 1 的代码模式交替，对照 Agent 循环和普通代码的区别

interleaved_practiceagent_vs_codeloop_vs_sequential

第 2 周 · 第 5 天 · layer0待开始

Agent 循环的直觉建立

两周总结与自测 — 随机出一道代码 Trace 题，闭眼做，对照答案；整理两张 A6 卡片：代码模式 + Agent 循环步骤

review_week2self_testtrace_exerciseknowledge_cards

3第 3 周 · 上下文工程(layer1)

第 3 周 · 第 1 天 · layer1待开始

上下文工程

System Prompt 的设计原则 — 读 extract-v2.ts 三阶段 Prompt，闭眼复述各阶段分工

system_promptmulti_stage_promptprompt_engineeringrole_assignment

阅读文件：data/sources/apps/web/lib/prompts/extract-v2.ts

第 3 周 · 第 2 天 · layer1待开始

上下文工程

消息历史管理与模板版本控制 — 读 prompt-manager.ts，预测 history 数组爆了会出什么错

history_managementtemplate_versioningcontext_injectionoverflow_error

阅读文件：data/sources/apps/web/lib/prompt-manager.ts

第 3 周 · 第 3 天 · layer1待开始

上下文工程

AGENTS.md / CLAUDE.md / SKILL.md 引导文件模式 — 理解 Agent 启动时的规则注入机制

agent_rulesbootstrap_filesskill_definitionrule_injection

阅读文件：data/sources/AGENTS.md, data/sources/CLAUDE.md, data/sources/SKILL.md

第 3 周 · 第 4 天 · layer1待开始

上下文工程

交错练习：Week 3 上下文工程 + Week 2 Agent 循环，对照 System Prompt 和 Agent Loop 的协作关系

interleaved_practicecontext_vs_loopprompt_in_agent

第 3 周 · 第 5 天 · layer1待开始

上下文工程

间隔复习 Week 1-2 — 不查代码，口头描述 LLMCallLog 结构和 Agent 循环的五步流程

spaced_reviewweek1_2_recallllm_call_logagent_loop_steps

4第 4 周 · 记忆系统(layer1)

第 4 周 · 第 1 天 · layer1待开始

记忆系统

短期记忆 vs 长期记忆 — 读 schema.prisma 的 LLMCallLog 和 UserEventLog 表结构，描述一条 log 的生命周期

memory_typesaudit_logevent_loglog_lifecycle

阅读文件：data/sources/apps/web/prisma/schema.prisma

第 4 周 · 第 2 天 · layer1待开始

记忆系统

向量检索与 RAG — 读 books.ts 的 pgvector 查询，预测阈值设太高会漏还是错判

vector_dbpgvectorsemantic_searchsimilarity_threshold

阅读文件：data/sources/apps/web/lib/db/books.ts

第 4 周 · 第 3 天 · layer1待开始

记忆系统

文件记忆模式 — 读 STATUS.md，理解人类可读的状态追踪与 Agent 记忆之间的关系

file_based_memorystatus_trackinghuman_readable_state

阅读文件：data/sources/STATUS.md

第 4 周 · 第 4 天 · layer1待开始

记忆系统

交错练习：Week 4 记忆系统 + Week 3 上下文工程，对照上下文窗口和文件记忆的容量、持久性和检索方式

interleaved_practicememory_vs_contextcapacity_comparison

第 4 周 · 第 5 天 · layer1待开始

记忆系统

间隔复习 Week 3 — 闭眼描述 prompt-manager 的三层结构和 System Prompt 的设计要点

spaced_reviewweek3_recallprompt_manager_layers

5第 5 周 · 规划与推理(layer1)

第 5 周 · 第 1 天 · layer1待开始

规划与推理

ReAct 模式 — 追踪 reading-plan 生成端点：用户输入→第一步调用→返回→下一步判断的完整链路

react_patternthought_action_observationplan_generationdecision_chain

阅读文件：data/sources/apps/web/app/api/reading-plan/generate/route.ts

第 5 周 · 第 2 天 · layer1待开始

规划与推理

CoT 多阶段推理 — 画 extract-v2.ts 三阶段之间数据流向图，理解阶段间依赖

chain_of_thoughtmulti_stageoutput_dependencydata_flow

阅读文件：data/sources/apps/web/lib/prompts/extract-v2.ts

第 5 周 · 第 3 天 · layer1待开始

规划与推理

Self-Reflection 与错误恢复 — 读 siliconflow.ts 的 retry/backoff 逻辑，预测 maxRetry=2 时的调用序列

self_reflectionretry_backofffallbackerror_recovery

阅读文件：data/sources/apps/web/lib/ai/siliconflow.ts

第 5 周 · 第 4 天 · layer1待开始

规划与推理

交错练习：Week 5 规划推理 + Week 4 记忆系统，对照向量检索和 ReAct Loop 的检索-推理循环有何异同

interleaved_practiceplanning_vs_memoryretrieval_reasoning_loop

第 5 周 · 第 5 天 · layer1待开始

规划与推理

间隔复习 Week 3-4 — 闭眼描述三阶段提取 Pipeline 和 pgvector 语义搜索的查询流程

spaced_reviewweek3_4_recallextract_pipelinevector_search

6第 6 周 · 安全与护栏(layer1)

第 6 周 · 第 1 天 · layer1待开始

安全与护栏

JWT 认证与路由守卫 — 追踪 auth.ts：请求进来→验证→拒绝/通过的完整判断链

threat_modelauth_guardjwtauth_chain

阅读文件：data/sources/apps/web/lib/auth.ts

第 6 周 · 第 2 天 · layer1待开始

安全与护栏

输出约束与枚举校验 — 读 book-tags.ts，预测 LLM 输出不在枚举表里会怎么处理

output_constraintsenum_validationguardrailsinvalid_output

阅读文件：data/sources/apps/web/lib/validation/book-tags.ts

第 6 周 · 第 3 天 · layer1待开始

安全与护栏

超时与隔离 — 读 siliconflow.ts 的 AbortController，手画 timeout 触发时机与信号传播链

timeoutabort_controllerrate_limitingsignal_propagation

阅读文件：data/sources/apps/web/lib/ai/siliconflow.ts

第 6 周 · 第 4 天 · layer1待开始

安全与护栏

交错练习：Week 6 安全护栏 + Week 5 规划推理，对照 retry 和 abort 的决策逻辑差异

interleaved_practicesafety_vs_reasoningretry_vs_abort

第 6 周 · 第 5 天 · layer1待开始

安全与护栏

间隔复习 Week 4-5 — 闭眼描述 retry/backoff 行为和 ReAct 的 Thought-Action-Observation 三步

spaced_reviewweek4_5_recallretry_behaviorreact_steps

7第 7 周 · 多 Agent 与消息传递(layer1)

第 7 周 · 第 1 天 · layer1待开始

多 Agent 与消息传递

多 Provider 协作 — 对照 siliconflow.ts 和 glm.ts 两个 Provider 封装的异同（GLM → DeepSeek v4-pro 演进）

multi_agentprovider_routingfallbackprovider_abstraction

阅读文件：data/sources/apps/web/lib/ai/siliconflow.ts, data/sources/apps/web/lib/ai/glm.ts

第 7 周 · 第 2 天 · layer1待开始

多 Agent 与消息传递

SSE 流式通信 — 追踪 rerun-needs-review 端点：SSE 事件的完整发送链与客户端接收

message_passingsse_protocolevent_streamstreaming

阅读文件：data/sources/apps/web/app/api/admin/rerun-needs-review/route.ts

第 7 周 · 第 3 天 · layer1待开始

多 Agent 与消息传递

Subagent 角色隔离 — 读 extract-v2.ts 三阶段 Prompt 变体，说明为什么三个阶段不能合并成一个 prompt

subagentrole_isolationprompt_variantsseparation_reasoning

阅读文件：data/sources/apps/web/lib/prompts/extract-v2.ts

第 7 周 · 第 4 天 · layer1待开始

多 Agent 与消息传递

交错练习：Week 7 多 Agent + Week 6 安全护栏，对照 AbortController 和 SSE abort 的取消机制

interleaved_practicemultiagent_vs_safetyabort_comparison

第 7 周 · 第 5 天 · layer1待开始

多 Agent 与消息传递

间隔复习 Week 5-6 — 闭眼描述 batch-analyze 的完整 Pipeline 和质量门禁的 hard-fail vs soft-flag

spaced_reviewweek5_6_recallbatch_pipelinequality_gate_patterns

8第 8 周 · 可观测性与评估(layer1)

第 8 周 · 第 1 天 · layer1待开始

可观测性与评估

全链路审计 — 读 schema.prisma 的 LLMCallLog 结构，写一条 SELECT 查出某次 batch 的完整调用链

observabilityaudit_trailcall_loggingfull_trace

阅读文件：data/sources/apps/web/prisma/schema.prisma

第 8 周 · 第 2 天 · layer1待开始

可观测性与评估

质量门禁 — 读 extract-v2.ts 的 qualityCheck 逻辑，预测 confidence < 0.6 时的系统行为

quality_gateconfidence_thresholdeval_metricslow_confidence_behavior

阅读文件：data/sources/apps/web/lib/prompts/extract-v2.ts

第 8 周 · 第 3 天 · layer1待开始

可观测性与评估

Coordinator 模式与状态追踪 — 读 COORDINATOR-INTEGRATION.md，理解进程编排与健康检查机制

status_trackingcoordinatorhealth_checkprocess_orchestration

阅读文件：data/sources/COORDINATOR-INTEGRATION.md

第 8 周 · 第 4 天 · layer1待开始

可观测性与评估

交错练习：Week 8 可观测性 + Week 7 多 Agent，对照 picturebook-kg 和 OpenClaw 的可观测性差异

interleaved_practiceobservability_vs_multiagentcross_project_compare

第 8 周 · 第 5 天 · layer1待开始

可观测性与评估

间隔复习 Week 6-7 — 闭眼描述 Week 1-8 学到的所有安全模式和 Agent 间通信方式

spaced_reviewweek6_7_recallsafety_patternsagent_communication

9第 9 周 · 最简 Agent 循环(layer2)

第 9 周 · 第 1 天 · layer2待开始

最简 Agent 循环

从零搭建：「发请求→拿回复」— 用 fetch 调 SiliconFlow DeepSeek v4-pro，实现最简 LLM 调用返回文本

build_agent_loopfetch_llmrequest_responseminimal_call

第 9 周 · 第 2 天 · layer2待开始

最简 Agent 循环

加 function calling 判断 — 给最简循环加 if/else 路由：LLM 返回 tool_call 时走工具分支，否则返回文本

build_tool_judgefunction_callingif_else_routetool_branch

第 9 周 · 第 3 天 · layer2待开始

最简 Agent 循环

加工具执行 — 实现一个「搜索图书」的工具函数，让 LLM 自主选择何时调用

build_tool_execsearch_tooltool_resultautonomous_choice

第 9 周 · 第 4 天 · layer2待开始

最简 Agent 循环

交错练习：加循环直到完成 — 处理多轮对话直到 LLM 回答「完成」，与 Week 1-2 的代码模式交替回顾

build_complete_loopmulti_turntermination_conditioninterleaved_practice

第 9 周 · 第 5 天 · layer2待开始

最简 Agent 循环

建造阶段总结 — 用不超过 50 行代码实现完整 Agent 循环，口头描述每一行的作用

build_review_week9mini_agentfifty_linesoral_walkthrough

10第 10 周 · 接入 picturebook-kg(layer2)

第 10 周 · 第 1 天 · layer2待开始

接入 picturebook-kg

接入现有数据库 — 让你的 mini agent 查询 picturebook-kg 的 book 表，替换硬编码数据

integrate_dbprisma_querybook_tablereplace_hardcode

第 10 周 · 第 2 天 · layer2待开始

接入 picturebook-kg

接 prompt-manager — 用 picturebook-kg 的 Prompt 模板替代你的硬编码 System Prompt

integrate_prompttemplate_reusesystem_prompt_integration

第 10 周 · 第 3 天 · layer2待开始

接入 picturebook-kg

接定时任务 — 让 Agent 每天自动跑一次，理解 cron 与 Agent 触发的关系

integrate_cronscheduled_jobautonomous_trigger

第 10 周 · 第 4 天 · layer2待开始

接入 picturebook-kg

交错练习：接 SSE 输出 — 把 Agent 结果流式返回到前端，对照 Week 7 的 SSE 协议

integrate_ssestreaming_outputsse_revisitinterleaved_practice

第 10 周 · 第 5 天 · layer2待开始

接入 picturebook-kg

建造阶段总结 — 回顾你的 mini agent 接入了哪些 picturebook-kg 组件，画出集成架构图

build_review_week10integration_architecturecomponent_map

11第 11 周 · 评测与迭代(layer2)

第 11 周 · 第 1 天 · layer2待开始

评测与迭代

加调用日志 — 参考 LLMCallLog 结构，为你的 mini agent 记录每次 LLM 调用的输入输出

add_loggingcall_recordinput_output_traceaudit_pattern

第 11 周 · 第 2 天 · layer2待开始

评测与迭代

加质量门禁 — 设置置信度阈值，低质量结果自动重试，参考 extract-v2.ts 的 qualityCheck

add_quality_gateconfidence_checkretry_on_lowquality_pattern

第 11 周 · 第 3 天 · layer2待开始

评测与迭代

测极限情况 — 输出去重、异常 schema、空结果、超长输入，记录你的 agent 在每种情况下的行为

edge_case_testdedupempty_resultoverlong_input

第 11 周 · 第 4 天 · layer2待开始

评测与迭代

交错练习：加 retry + backoff — 参考 siliconflow.ts 的退避策略，让你的 agent 在失败时自动恢复

add_retrybackoff_strategyself_healinginterleaved_practice

第 11 周 · 第 5 天 · layer2待开始

评测与迭代

建造阶段总结 — 给你的 mini agent 写 README，列出已知局限和改进方向

build_review_week11readme_writeuplimitationsimprovement_roadmap

12第 12 周 · 综合与复盘(layer2)

第 12 周 · 第 1 天 · layer2待开始

综合与复盘

完整系统架构回顾 — 用 Week 1-8 的卡片重新梳理 picturebook-kg 的 Agent 工作全貌

architecture_reviewfull_systemend_to_endknowledge_synthesis

第 12 周 · 第 2 天 · layer2待开始

综合与复盘

设计自己的下一个 Agent — 不是照着做，是独立设计：定义目标、选择工具、画架构图

system_designarchitecture_planningown_agentindependent_design

第 12 周 · 第 3 天 · layer2待开始

综合与复盘

12 周总复盘（上）— 口头描述 Ø 基础阶段（Week 1-2）和 I 理解阶段（Week 3-8）的核心收获

retrospective_part1phase_0_1_recalloral_retrospective

第 12 周 · 第 4 天 · layer2待开始

综合与复盘

交错练习：12 周总复盘（下）— 口头描述 II 建造阶段（Week 9-12）的实践经验，录音存档

retrospective_part2phase_2_recallaudio_recordinterleaved_practice

第 12 周 · 第 5 天 · layer2待开始

综合与复盘

制定下一阶段目标 — 基于 12 周自我评估，决定下一步深入哪个方向，写出学习路线图

next_stepslearning_roadmapself_assessmentfuture_direction