八周冲刺计划（阶段 1 · 第 1–2 月）¶

目标：两个月后手握作品集——一个从零写的 agent 框架 + 一个临床领域 capstone。路线：先造后读。W1–4「造」，W5–8「读 + 用」。详细设计依据：设计文档

总则¶

每周节奏（周投入 5–10 小时，可加码）：

环节	时间	建议安排
原理输入	1.5–2h	一次整块时间，边读边记
动手实践	4–6h	拆 2–3 次，每次 ≥90 分钟（保持心流，避免碎片化调试）
信息雷达	30min	固定周日晚上，SOP 见 resources.md
笔记复盘	~1h	周末写周记 + 发布当周笔记

四条纪律：

数据红线：练习只用公开数据或脱敏数据。真实公司数据脱敏标准：受试者→PT-001、中心→Site-01、研究者→Dr-A，日期泛化为年份，自由文本逐条检查。
代码独立建仓：nano-agent 和 capstone 独立仓库，本仓库只放链接和笔记。
时间记账：周记记录实际投入。连续 2 周低于 5h 触发计划回顾（要么加时间，要么启用裁剪顺序，不硬撑）。
本地临床运行时 = R + pharmaverse：家里没有 SAS，凡需本地执行的临床数据操作一律用 R + pharmaverse 验证包（admiral / pharmaversesdtm / xportr / haven），renv 锁定包版本——可复现、贴近 FDA 申报生态。SAS 代码只能生成、不能本地执行（留到公司验证）。

裁剪与加餐：每周末尾给出「裁剪顺序」（时间不够先砍什么，按序砍）和「加餐清单」（时间充裕加什么）。裁剪的底线是保住产出物——产出物没了这周就白过。

W1 ｜ LLM API 破冰¶

目标：脱离教程独立调通 API，完成两个小工具，建立对「LLM 就是一个可编程的文本函数」的手感。

原理输入（1.5–2h）¶

训练管线大白话：预训练 = 海量阅读学会语言规律；SFT = 跟着问答例题学会听话；RLHF/RLVR = 按人类反馈改作业学会对齐。每个阶段模型获得了什么能力、缺什么能力。—— 看 Karpathy《Intro to Large Language Models》演讲。本节四个主题的配套资源（视频/交互工具/论文）集中在 resources.md 的「每周原理资源包」。
tokenizer 与上下文窗口：模型看到的是 token 不是字符（为什么模型数不清 strawberry 里有几个 r）；上下文窗口 = 工作记忆，超了就丢；token 是计价单位。
采样参数：temperature / top_p 到底在调什么（从概率分布里挑词的激进程度）；什么时候该 0（结构化输出）什么时候该高（头脑风暴）。
推理模型（o 系列 / DeepSeek-R1 类）：先思考后作答。对 agent 的意义：多步规划更强，但更慢更贵——什么任务值得用推理模型是 W3 之后持续讨论的问题。

动手实践（4–6h）¶

环境搭建（1h）：Python 3.11+、venv、pip install openai python-dotenv；注册 DeepSeek 开放平台并充值最小额度（¥10 即可开始）；API key 存 .env（加入 .gitignore，这一步出错等于把钱包贴到 GitHub 首页）。
项目 A：流式 CLI 聊天助手（~100 行，2h）：系统提示词、多轮对话历史、流式打印（stream=True）、/exit 退出、/reset 清空历史。骨架示例（DeepSeek 兼容 OpenAI SDK，base_url 以其官方文档为准）：

from openai import OpenAI
client = OpenAI(api_key=..., base_url="https://api.deepseek.com/v1")
stream = client.chat.completions.create(
    model="deepseek-chat", messages=history, stream=True)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="", flush=True)

项目 B：SAS log 错误分析器（2h）：读本地 .log 文件 → 正则提取 ERROR/WARNING 段落 → 送给 LLM 要求结构化 JSON 输出（字段：严重级别 / 原因猜测 / 建议修复 / 涉及步骤）→ 终端表格展示。用你手头任何一段旧 log（脱敏）或自造一段含 3 类错误的 log。
笔记 1：第一篇《我对 LLM API 的理解》——tokenizer、上下文、采样参数、流式，用自己的话。

产出物¶

学习仓库初始化（即本仓库）＋ 2 个小工具（放本仓库 lab/ 目录或独立小仓库，自行决定，W3 前都可）＋笔记 1。

验收清单¶

[ ] 两个工具不看教程可重复运行
[ ] 能口头解释 stream / messages / temperature 各自的作用
[ ] log 分析器对含 3 类错误的 log 输出合法 JSON
[ ] 完成首次信息雷达扫描并记录进周记

裁剪顺序¶

项目 B 可退化为「整段 log 塞给模型诊断」（跳过正则提取）
原理输入读不完：优先 tokenizer + 上下文窗口，训练管线可留到 W2 补

加餐清单¶

用 rich 库给 CLI 加 markdown 渲染
同一 prompt 在 temperature 0 vs 1.5 下跑 5 次对比输出分布
再注册 GLM 或通义，同一任务对比两家模型（只花几毛钱，建立「模型是可替换组件」的意识）

W2 ｜工具调用（Function Calling）¶

目标：理解 agent 的发动机——工具调用循环。不用任何框架，手写 dispatch。

原理输入（1.5–2h）¶

机制：工具的 JSON Schema 随请求注入 → 模型输出的是「调用意图」（工具名 + 参数 JSON）而非直接执行 → 你的代码执行工具 → 结果作为 tool 角色消息回填 → 模型决定继续调用还是作答。
模型如何选择工具：工具的 description 和参数说明是写给模型看的文档——写得含糊模型就乱调。这是 prompt 工程的工程化版本，也是 W3 框架设计的核心接口。
安全第一课（为 W5 铺垫）：路径穿越（../../）、命令注入、资源耗尽——模型的输出是你控制不了的用户输入。

配套资源见 resources.md 每周原理资源包（OpenAI Function Calling 官方指南为主线，HuggingFace Agents Course 为加餐）；中文主参考：《深入理解 AI Agent》第 1、4 章。配套知识库页（先读）：工具调用与结构化输出。

动手实践（4–6h）¶

三个工具 + Schema（2h），从 W1 项目 A 复制出新项目：
read_file：带路径白名单（只允许访问指定目录内）
run_python：subprocess + 超时（如 10s）+ 输出截断（如 2000 字符）
search_ct：本地 CDISC CT 词表 CSV 查询（从 NCI EVS 下载 1–2 个 codelist 如 SEX、NY 转 CSV，或手造 20 行样例；下载方式见 resources.md 领域数据源）
手写 dispatch 循环（2h）：

while True:
    resp = client.chat.completions.create(model=..., messages=history, tools=TOOL_SPECS)
    if not resp.choices[0].message.tool_calls:
        break  # 模型给出最终回答
    for call in resp.choices[0].message.tool_calls:
        result = execute(call.function.name, json.loads(call.function.arguments))
        history.append({"role": "tool", "tool_call_id": call.id, "content": result})

多步任务测试（1h）：问「SEX 词表里有哪些值，请在 Python 里验证一下回答的数量」——观察模型自主串联两个工具。
笔记 2：画一张工具循环图（手画或 mermaid），记录每个工具 schema 的设计取舍。

产出物¶

工具版聊天助手＋循环图笔记。

验收清单¶

[ ] 助手能自主决定先 search_ct 再回答词表问题
[ ] run_python 有超时和输出长度限制（亲手触发一次验证）
[ ] read_file 拒绝白名单外路径（亲手用 ../../ 试一次）
[ ] 能解释「为什么工具 description 是给模型看的文档」

裁剪顺序¶

run_python 最后做（风险最高）；2. search_ct 用最小 CSV（5 行也行）

加餐清单¶

加第 4 个工具 list_dir
把工具报错的 traceback 喂回模型，看它自我修复
通读 openai SDK 的 function calling 官方文档，标记与你的手写实现的对应关系

W3 ｜亲手造 nano-agent（最重要的一周）¶

目标：把 W1–2 的散装代码重构成一个真正的迷你框架。这是整个计划的心脏。

原理输入（1.5–2h）¶

ReAct（arXiv:2210.03629，读原理部分即可）：推理（Reason）与行动（Act）交替——agent 的学术原型，你的 dispatch 循环就是它的工程化。
Reflexion（arXiv:2303.11366，读摘要 + 图 1）：失败后生成自我反思，下次尝试更好——错误重试策略的理论依据。
停止条件设计：最大迭代数 / 模型声明完成 / token 预算上限。没有停止条件的 agent 是死循环制造机。

动手实践（4–6h，本周可加码）¶

新建独立仓库 nano-agent（0.5h）：README 先写设计再写代码（设计意图驱动的习惯）。
核心实现（3–4h，目标 ≤500 行核心代码）：
@tool 装饰器：函数 → 自动生成 JSON Schema（函数名/描述/docstring/类型注解）
ToolSpec 数据类：name / description / parameters / func
Agent 类：run(user_input) 主循环、消息历史管理、系统提示词组装
执行日志：每次工具调用记录时间、耗时、参数摘要、结果摘要
验收任务（1h）：让 agent 扫描一个含 5–10 个 .sas 文件的目录，统计每个文件的 data step / proc 步数，输出 markdown 报告。全程无人工干预。
v0.1 打 tag，README 补 mermaid 架构图。

产出物¶

nano-agent 独立仓库 v0.1 ＋架构图。

验收清单¶

[ ] 框架核心 ≤500 行（不含测试）
[ ] 新增一个工具只需「写函数 + 加装饰器」，不改框架代码（写一个新工具验证）
[ ] 验收任务全程无人工干预完成
[ ] 执行日志能复盘每一步决策
[ ] README 含 mermaid 架构图

裁剪顺序¶

执行日志可退化为 print；2. 架构图可推迟到 W4 补

加餐清单¶

「计划再执行」模式：先让模型输出计划，确认后逐步执行
错误自动重试（结合 Reflexion 思想：把失败原因附在重试请求里）
对比同一任务：单轮 prompt vs agent 循环，各自的成功率和 token 成本

W4 ｜上下文工程 + 月度里程碑¶

目标：解决「对话长了怎么办」——agent 的记忆管理。完成月度里程碑项目。

原理输入（1.5–2h）¶

注意力大白话：每个词「环顾四周」决定关注谁——3Blue1Brown 神经网络系列（中文配音版），建立直觉即可，不碰公式。
幻觉成因：模型在做「预测下一个 token」不是「检索事实」；对 agent 的启示：关键事实必须进上下文（工具结果比模型记忆可靠）。（延伸：Karpathy Deep Dive 的 hallucination 章节，见 resources.md 每周原理资源包）
Anthropic《Building Effective Agents》（必读，行业最重要的认知框架）：workflow（代码编排 LLM 调用）vs agent（LLM 自主决定调用）的分界；什么时候不该用 agent。链接见 resources.md。

配套知识库页（大白话解读，建议先读）：注意力机制直觉、上下文工程。

动手实践（4–6h）¶

nano-agent v0.2：上下文管理（2–3h）：
token 计数（tiktoken 近似估算即可，注意 DeepSeek 等模型的 tokenizer 与 GPT 不同，标注「估算」）
历史超限策略：旧对话调用 LLM 压缩成摘要，保留最近 N 轮原文 + 摘要
月度里程碑「SDTM spec 阅读器」（2–3h）：pandas/openpyxl 读 spec Excel（公开 spec 或自制样例，见 resources.md 领域数据源）→ 基于 nano-agent 提供：① 自然语言问答（「哪些变量是日期变量」「XX 的标签是什么」）② 命名规则检查（变量名 ≤8 字符、无特殊字符、--DT 数值型 vs --DTC 字符型的后缀合规）
月度复盘 #1：用 learning-log 月度模板，发布。

产出物¶

nano-agent v0.2 ＋ SDTM spec 阅读器 demo ＋月度复盘文。

验收清单¶

[ ] 20+ 轮长对话不超上下文，且摘要后 agent 仍记得开头的关键约定
[ ] spec 阅读器正确回答 5 个自拟问题
[ ] 规则检查抓出你故意埋的 3 个命名问题
[ ] 月度复盘文发布

裁剪顺序¶

spec 阅读器可退化为纯问答（砍规则检查）；2. 摘要策略只实现最简单一档

加餐清单¶

摘要策略对比实验：全量历史 / 滑动窗口 / 摘要+窗口，记录各自 token 消耗与事实保真度
对照 LangChain 的 memory 抽象，写一篇「框架替我做了什么」

W5 ｜工程化加固 + Codex 初遇¶

目标：给玩具加上安全模型和测试，然后第一次正面遭遇生产级 agent——Codex CLI。

原理输入（1.5–2h）¶

沙箱与安全工程一般原则：最小权限、审批分级、不可逆操作必须人工确认。
agent 安全为什么特殊：你的代码输入可控，模型的输入（来自文件、网页、工具结果的文本）不可控——prompt injection 入门：一段精心构造的文本让模型执行违背你意图的操作。

配套资源见 resources.md 每周原理资源包（Simon Willison 的 prompt injection 系列、OWASP LLM Top 10 清单）。

动手实践（4–6h）¶

nano-agent v0.3：审批分级（2h）：三级——read-only（只读工具自动放行）/ ask（每个写操作 CLI 询问 y/n）/ full（全自动）。工具执行前过审批回调。
pytest ≥10 个（1.5h）：注册器、dispatch、超时、路径白名单、审批门控各覆盖。第一次体验「给 agent 写测试」。
Codex CLI 初遇（1.5–2h）：
安装：npm install -g @openai/codex（Windows 支持，详见仓库 docs/install.md）

配置国内 provider：config.toml 的 model_providers，示例（以仓库 docs/config.md 为准，该文档随版本演进）：

[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com/v1"
env_key = "DEEPSEEK_API_KEY"
wire_api = "chat"

跑一个小任务（如「给这个目录的脚本加一个函数和对应测试」），观察并记录：它先做什么、怎么读文件、何时请求审批、上下文如何增长。
退路（若国内 provider 与 Codex CLI 不兼容）：行为观察改用其他可用模型完成，并把「为什么不兼容、差在哪」写成工程笔记——这本身就是 W6 的预习材料。

产出物¶

nano-agent v0.3（审批分级 + 测试）＋「Codex 初体验」观察笔记。

验收清单¶

[ ] read-only 模式下写文件被拦截（亲手验证）
[ ] pytest 全绿，覆盖核心路径
[ ] Codex CLI 完成 ≥1 个真实小任务，或退路方案完成并有记录
[ ] 观察笔记发布（含行为观察清单，不用懂源码，纯黑盒）

裁剪顺序¶

pytest 减到 6 个核心用例；2. Codex 任务选最小的（单文件修改）

加餐清单¶

给 nano-agent 加 --dry-run 模式（只打印将执行什么）
对比 Codex 与你的审批粒度差异，写下「如果我做产品会怎么设计审批」

W6 ｜解剖 Codex Ⅰ：核心循环与提示词¶

目标：带着 W1–5 建立的参照系，进入 Codex 源码。阅读路径、问题清单、笔记模板全部见 docs/02-codex-study-guide.md——本节只排日程。

动手实践（按指南的六步路径，本周走完 1–5 步）¶

步骤	内容	时间
1	README + docs/ 全览：产品形态、配置哲学	1h
2	AGENTS.md：OpenAI 用 agent 开发 agent 的规范	0.5h
3	codex-rs 工作区地图：每个 crate 一句话职责	1h
4	core：会话生命周期、turn 循环、事件流	1.5h
5	prompt 构造与工具定义（rg 搜系统提示词定位）	1.5h

对照笔记：我的 nano-agent vs Codex——消息类型、工具 schema、事件处理三张对照表；从 Codex 抄一个机制（如工具描述的写法风格）进 nano-agent。

产出物¶

2 篇源码笔记（每篇 ≥3 个「设计决策与理由」）＋一张自己画的数据流图。

验收清单¶

[ ] 能不看资料画出「用户输入 → 工具执行 → 回复」在 Codex 里的完整数据流
[ ] 2 篇笔记发布，每篇含至少 3 个设计决策分析
[ ] 从 Codex 抄的机制在 nano-agent 里验证可用

裁剪顺序¶

第 5 步可浅读（只看工具列表和系统提示词结构）；2. 笔记可合并为 1 篇深度长文

加餐清单¶

挑一个近期 merged PR，读讨论和 diff（学演进过程，不是学代码）
把 Codex 系统提示词与自己的对比，做 A/B 实验看行为差异

W7 ｜解剖 Codex Ⅱ：沙箱、压缩与持久化¶

目标：读完指南第 6 步，并完成「移植」——把一个生产级机制搬进自己的框架。

动手实践¶

内容	时间
exec / 沙箱与审批分级的实现	1.5h
上下文压缩机制（auto-compact：触发时机、保留什么丢什么）	1.5h
会话持久化（rollout / JSONL 结构）	1h
移植一个机制进 nano-agent v0.4（推荐：compaction 升级版，或审批分级细化）	2h
记录移植前后对比数据	0.5h

产出物¶

2 篇源码笔记＋ nano-agent v0.4 ＋前后对比数据。

验收清单¶

[ ] 能解释 Codex 审批粒度的划分逻辑（如为什么读文件宽松、执行命令严格）
[ ] 能解释 compaction 保留什么、丢什么、为什么
[ ] 移植机制有前后对比数据（token 消耗 / 长任务成功率）

裁剪顺序¶

会话持久化只读不移植；2. 对比数据可只测 token 一项

加餐清单¶

读 Codex 的测试目录，学「怎么给 agent 系统写测试」
给 nano-agent 加 rollout 式会话记录（JSONL）

W8 ｜ Capstone + 公开分享¶

目标：把两个月的积累变成一个能写进简历的作品。

Capstone 三选一（选择标准）¶

选项	内容	优势	难点	适合你如果…
A. aCRF 审阅 agent	PyMuPDF 解析 aCRF PDF 的 FreeText 注释 → SDTM 映射检查（域映射/变量映射/格式问题）	最差异化，CDISC 深度肉眼可见	PDF 注释解析有坑	想要「别人做不了」的作品
B. SDTM xpt QC agent	pyreadstat（或 R haven）读公开 pilot 数据 → CT 值检查 / 结构检查 / 变量顺序 → findings 报告	数据现成（CDISC pilot / PHUSE），工程最完整	亮点偏工程	想要最稳的交付
C. ADaM 派生管线 agent（R + pharmaverse）	公开 SDTM 数据 + spec → agent 生成 R 代码（admiral 派生 + xportr 导出合规准备）→ 本地 Rscript 执行 → 读回输出校验（变量存在性 / CT / 结构），renv 锁版本全程可复现	唯一能本地完整闭环（生成→执行→验证）的选项；pharmaverse 是 FDA 申报生态的 R 标准件	R 语法 + admiral 学习成本（对 SAS 用户友好）	想要闭环最完整、直接对齐行业方向的作品

公开数据源见 resources.md 领域数据源。无论选哪个，mini-eval 必做。

变体：C 也可改为「SAS 代码起草 agent」（spec → 映射代码草稿 + 自审清单，周一公司验证），但本地无法执行验证、作品闭环打折——默认推荐 R 版。若选 C：W6 周末先备好 R 环境（R 4.x + renv::init() + admiral / pharmaversesdtm / xportr / haven，lockfile 入库；包清单见 resources.md 第五节）。agent 调用 R 复用 W2 run_python 的 subprocess 模式（Rscript + 超时 + 输出截断）。

mini-eval（必做，差异化核心）¶

从你的 CDISC 知识出 10–20 道有标准答案的题（如「此变量取值是否在 CT 内」「--DTC 变量这个格式合规吗」）
跑 agent 记录成功率 → 迭代 prompt / 工具 → 再跑一轮 → 展示提升
「能评价」是工程师和调参侠的分水岭，也是别人抄不走的护城河

收尾¶

README 让外人 10 分钟内 clone 并跑起来（找一位朋友或让 AI 扮演陌生人验证）
两个月总结文发布（博客/知乎/掘金任一）：写「一个 SAS 程序员的两个月 AI agent 自学记录」——你自己的故事就是最好的传播素材
对照 ROADMAP 两个月验收清单逐项打勾

产出物¶

capstone 独立仓库（含 mini-eval 报告）＋两个月总结文。

验收清单¶

[ ] capstone 仓库公开，README 完整可复现
[ ] mini-eval 报告含两轮数据
[ ] 总结文发布
[ ] ROADMAP 两个月验收清单 5 项全部打勾

裁剪顺序¶

eval 题量保底 10 题；2. 总结文可延后一周发布（但不许跳过）

加餐清单¶

capstone 加 GitHub Actions CI（跑测试）
录 3 分钟演示 GIF 放 README 顶部
把总结文发到临床圈社群，收集第一批真实反馈——这同时是阶段 2「工作流试点」的用户调研

两月之后¶

进入阶段 2（框架速成 / MCP / RAG / 工作流试点），见 ROADMAP。八周内所有未完成的加餐项归档到 ROADMAP 的阶段 2 入口，不丢弃、不焦虑。

八周冲刺计划（阶段 1 · 第 1–2 月）¶

总则¶

W1 ｜ LLM API 破冰¶

原理输入（1.5–2h）¶

动手实践（4–6h）¶

产出物¶

验收清单¶

裁剪顺序¶

加餐清单¶

W2 ｜ 工具调用（Function Calling）¶

原理输入（1.5–2h）¶

动手实践（4–6h）¶

产出物¶

验收清单¶

裁剪顺序¶

加餐清单¶

W3 ｜ 亲手造 nano-agent（最重要的一周）¶

原理输入（1.5–2h）¶

动手实践（4–6h，本周可加码）¶

产出物¶

验收清单¶

裁剪顺序¶

加餐清单¶

W4 ｜ 上下文工程 + 月度里程碑¶

原理输入（1.5–2h）¶

动手实践（4–6h）¶

产出物¶

验收清单¶

裁剪顺序¶

加餐清单¶

W5 ｜ 工程化加固 + Codex 初遇¶

原理输入（1.5–2h）¶

动手实践（4–6h）¶

产出物¶

验收清单¶

裁剪顺序¶

加餐清单¶

W6 ｜ 解剖 Codex Ⅰ：核心循环与提示词¶

动手实践（按指南的六步路径，本周走完 1–5 步）¶

产出物¶

验收清单¶

裁剪顺序¶

加餐清单¶

W7 ｜ 解剖 Codex Ⅱ：沙箱、压缩与持久化¶

动手实践¶

产出物¶

验收清单¶

裁剪顺序¶

加餐清单¶

W8 ｜ Capstone + 公开分享¶

Capstone 三选一（选择标准）¶

mini-eval（必做，差异化核心）¶

收尾¶

产出物¶

验收清单¶

裁剪顺序¶

加餐清单¶

两月之后¶

W2 ｜工具调用（Function Calling）¶

W3 ｜亲手造 nano-agent（最重要的一周）¶

W4 ｜上下文工程 + 月度里程碑¶

W5 ｜工程化加固 + Codex 初遇¶

W6 ｜解剖 Codex Ⅰ：核心循环与提示词¶

W7 ｜解剖 Codex Ⅱ：沙箱、压缩与持久化¶