设计文档：AI Agent 开发学习计划（agent_harness 仓库）¶
- 日期：2026-09-04
- 状态：已确认（2026-09-04 用户审阅通过；随后两次补充：§4.6 大白话原则、本地临床运行时 R + pharmaverse）
- 最终产出：GitHub 学习仓库（README / ROADMAP / docs/01–04 共 6 个文档 + 本设计文档）
1. 背景与动机¶
学习者是临床试验领域的 SAS 统计程序员（CDISC 专家：SDTM / ADaM / CT，受监管环境工作经验），面对 AI 对临床编程职业的冲击，希望系统转型为「临床 × AI Agent」复合型人才。
核心诉求：
- 由浅入深、可执行、注重实践的学习计划
- 第一步：2 个月内明显突破（作品集导向）
- 以 OpenAI Codex 开源仓库为研读案例
- 长期动态更新（跟随大模型演进），推送到 GitHub
- 知识要求：系统性、深度、实时性（不落后）——内容优先于时间，时间不够可加时或延长 timeline
2. 已确认的约束与画像¶
| 维度 | 确认结果 |
|---|---|
| 编程基础 | 会 Python 语法，无完整项目经验（SAS 之外） |
| 时间投入 | 每周 5–10 小时，可临时加码 |
| LLM API | 国内模型（DeepSeek / 通义 / GLM 等，OpenAI 兼容接口），入门月预算约 ¥20–100 |
| 本地环境 | Windows 10 + PowerShell；家里无 SAS（仅公司电脑有）；本地临床数据运行时用 R + pharmaverse 验证包（admiral / pharmaversesdtm / xportr / haven + renv 锁版本），可复现、贴近 FDA 申报生态（用户 2026-09-04 确认） |
| 练习数据 | 公开样例数据优先（CDISC 公开 pilot 数据等）；必要时由学习者脱敏后提供 |
| 长期方向 | 临床 × AI 复合方向 |
| 优先级 | 作品集（2 个月）> 工作影响（3–4 个月）> 转型准备（6 个月） |
3. 方案选择¶
| 方案 | 描述 | 结论 |
|---|---|---|
| A 先造后读（螺旋式） | W1–4 手写 API 调用、工具循环与 mini 框架；W5–8 解剖 Codex + 领域 capstone | ✅ 已选 |
| B 框架优先 | 用 Pydantic AI / LangGraph 等快速出活，原理后补 | 未选：框架 API 迭代快、贬值快；读源码缺底层参照 |
| C 源码优先 | 直接沉浸 Codex 源码 | 未选：Codex 96.6% Rust、1 万+ commits，对当前水平不现实；其合理内核（读设计而非逐行）已吸收进 W6–7 |
选择理由：第一性原理理解与作品集双达标；框架知识后置到阶段 2，有原理打底后 1–2 周即可补上（框架只是语法糖）。
4. 设计详情¶
4.1 八周冲刺（阶段 1，第 1–2 月，作品集导向）¶
每周结构固定：原理输入 1.5–2h + 动手实践 4–6h + 信息雷达扫描 30min + 笔记复盘。每周文档内置「裁剪顺序」（时间不够先砍什么）与「加餐清单」（时间充裕加什么）。
| 周 | 主题 | 原理输入 | 核心实践 | 产出物 |
|---|---|---|---|---|
| W1 | LLM API 破冰 | 训练管线鸟瞰（pretrain→SFT→RLHF/RLVR）、tokenizer 与上下文窗口、采样参数、推理模型对 agent 设计的影响 | ① 流式 CLI 聊天助手（~100 行，openai SDK + 国内 base_url）② SAS log 错误分析器（结构化 JSON 输出） | 学习仓库初始化 + 2 个小工具 + 笔记 1 |
| W2 | 工具调用（Function Calling） | 结构化输出的底层约束方式；模型如何选择工具 | 手写 tool dispatch 循环（不用框架）：read_file / run_python（subprocess+超时+输出截断）/ search_ct（CDISC CT 词表） | 工具版助手 + 循环图笔记 |
| W3 | 亲手造 nano-agent（最重要一周） | ReAct 原理、Reflexion 概念、停止条件设计 | 独立仓库从零写 300–500 行：@tool 注册器、Agent 类 run loop、消息历史、执行日志；验收任务：扫描 .sas 文件统计 data step/proc 并输出 markdown 报告 | nano-agent 仓库 v0.1 + 架构 README |
| W4 | 上下文工程 + 月度里程碑 | 注意力（概念级）与幻觉成因；Anthropic《Building Effective Agents》（workflows vs agents） | nano-agent 加 token 计数与历史摘要；里程碑：「SDTM spec 阅读器」（公开 spec Excel → 自然语言问答 + 命名/派生规则检查提示） | v0.2 + 可演示 demo + 月度复盘文 |
| W5 | 工程化加固 + Codex 初遇 | 沙箱与安全工程原则、子进程安全 | 审批分级（read-only / ask / full）+ pytest ≥10 个；安装跑通 Codex CLI（Windows），配置 provider，完成真实小任务并记录行为观察 | v0.3（安全模型）+「Codex 初体验」笔记 |
| W6 | 解剖 Codex Ⅰ | （随读随补） | 按指南读 docs/ → AGENTS.md → codex-rs 目录地图 → core 会话与循环 → prompt 构造 → 工具定义；与自己的实现写对照笔记；抄一个机制进 nano-agent | 2 篇源码笔记 |
| W7 | 解剖 Codex Ⅱ | （随读随补） | 读 exec/沙箱审批分级 → 上下文压缩 → 会话持久化；移植一个机制（compaction 或审批分级）并记录对比数据 | 2 篇笔记 + v0.4 |
| W8 | Capstone + 公开分享 | — | 三选一：① aCRF 审阅 agent（解析 PDF 注释→SDTM 映射检查）② SDTM xpt QC agent（pyreadstat 读公开 pilot 数据→CT/结构检查→findings 报告）③ ADaM 派生管线 agent（R + pharmaverse：spec/SDTM→生成 R 代码→本地执行→校验输出，renv 锁版本可复现；SAS 代码起草为变体、公司端验证）；必做 mini-eval（10–20 题基于 CDISC 知识，量化成功率） | capstone 仓库 + 两个月总结文 |
两个月验收清单（作品集导向）：
- nano-agent 仓库：从零写的框架，≥500 行核心，有测试、有安全模型、README 含架构图
- capstone 仓库：临床领域 agent，含 mini-eval 报告，外人 clone 后按 README 能跑
- ≥6 篇公开笔记（其中 ≥3 篇 Codex 源码解读）
- 3 个仓库（学习中枢 + nano-agent + capstone）贯穿 8 周的 commit 记录
- 四大件能力自检（能讲清 / 能实现 / 能评价）：agent 循环、工具调用、上下文管理、安全审批
4.2 仓库结构¶
agent_harness/ ← 学习中枢（GitHub）
├── README.md # 导航 + 状态看板 + 学习原则
├── ROADMAP.md # 四阶段课程地图 + 状态标记 + 月度复盘区
├── docs/
│ ├── 01-sprint-2months.md # 八周冲刺计划（任务/产出/验收/裁剪/加餐）
│ ├── 02-codex-study-guide.md # Codex 研读指南（路径/问题清单/笔记模板）
│ ├── 03-resources.md # 四层信息雷达 + 原理论文分级清单
│ ├── 04-learning-log.md # 学习日志（周记 + 月度复盘模板）
│ └── superpowers/specs/ # 设计文档归档（本文件）
├── （外部）nano-agent 仓库 # W3 创建
└── （外部）capstone 仓库 # W8 创建
设计决策：学习仓库只放计划/笔记/指南/日志，代码项目独立建仓——GitHub 主页三个仓库各司其职，作品集逻辑清晰；README 顶部放状态看板；ROADMAP 用 ⬜🔄✅⏸️ 状态标记。
4.3 长期课程地图（第 3–12 月）¶
| 阶段 | 时间 | 模块 | 对应优先级 |
|---|---|---|---|
| 2 落地 | 第 3–4 月 | 框架速成（Pydantic AI，~2 周）· MCP 实战（给 nano-agent 写 MCP server）· RAG 基础与 agentic RAG（embedding/检索/重排；SAP、guideline 问答场景）· 工作流试点（脱敏数据） | 工作影响 |
| 3 深化 | 第 5–7 月 | Evals 体系（LLM-as-judge、轨迹评测、领域评测集）· 多 agent 编排（supervisor/handoff/A2A 协议）· LLM 原理系统课（Transformer 架构、推理系统 KV cache/投机解码、RLVR 训练范式）· 安全攻防（prompt injection 攻防、沙箱对比、受监管行业 AI 合规） | 转型准备 |
| 4 深耕 | 第 8–12 月 | 本地部署（Ollama/vLLM 跑开源模型，临床数据不出境的合规场景）· 跟踪 Codex 上游演进并沉淀解读 · 开源贡献 · 领域产品化探索 | 长期竞争力 |
4.4 信息雷达（实时性保障）¶
四层信息源：
- 官方工程博客（一手深度）：OpenAI developers 博客、Anthropic engineering（Claude Code 构建系列）、DeepSeek 技术报告
- 一手仓库动态：codex、OpenHands、SWE-agent、MCP 规范仓库的 releases/discussions
- 评测与风向：SWE-bench 等 agent 榜单、Hacker News、1–2 个精选工程周报（如 Latent Space）
- 中文圈精选：1–2 个高质量技术博主，避免信息茧房
扫描节奏：每周 30 分钟（记录进 learning-log）→ 每月复盘汇总进 ROADMAP（「本月行业变化 + 对计划的影响」）→ 每季度大复盘决定是否改道。
4.5 应对模型迭代的策略¶
- 不贬值层（深耕）：agent 循环、上下文工程、评测思维、安全模型、CDISC 领域知识
- 快贬值层（用到再查）：具体 API 参数、prompt 小技巧、特定模型脾气
- Codex 仓库本身就是「生产级 agent 如何跟进模型能力」的活标本，跟踪其 release notes 即可获得一手演进视角
4.6 深度与广度的边界¶
明确不做（当前阶段）：数学级注意力推导、模型训练/微调实操。理由：对「造 agent」主线贡献最低；阶段 3 的 LLM 原理系统课为可选深入模块，兴趣驱动。若未来转向研究方向再补。
不做 ≠ 不讲（大白话原则，用户 2026-09-04 确认）：以上概念仍需建立直觉级理解——用可视化视频（3Blue1Brown）、科普演讲（Karpathy）、论文只读摘要与图示等方式，目标 = 能用自己的话讲明白「它在干什么、为什么重要」，不追求公式复现与动手实操。资源清单设「大白话专区」落实此原则。
5. 风险与应对¶
| 风险 | 应对 |
|---|---|
| Codex 的 Rust 门槛 | 读设计而非逐行；以 docs/、架构讨论、数据流为主线；Python 参照系（OpenHands / SWE-agent）做辅助 |
| 国内 API 与 Codex CLI 兼容性 | Codex 支持自定义 provider（config.toml 的 model_providers，OpenAI 兼容 wire API）；若跑不通则以源码研读为主、行为观察用其他工具替代 |
| R + pharmaverse 学习成本 | 只用最小包集（admiral 核心函数、xportr、haven、renv）；R 对 SAS 用户迁移友好（data step ↔ dplyr 心智映射）；验证方法论参考 R Validation Hub 白皮书与 pharmaverse 包验证状态 |
| 每周时间超支 | 每周文档内置裁剪顺序；用户已确认可加时或延长 timeline |
| 模型快速迭代导致知识贬值 | 不贬值层/快贬值层策略 + 四层信息雷达 + 月度复盘机制 |
| 内容膨胀失控 | 阶段化管理，两个月作品集目标不可动摇；加餐内容仅时间充裕时启用 |
6. 交付物清单（实施范围）¶
| 文件 | 内容要点 |
|---|---|
| README.md | 仓库定位、导航、状态看板、五条学习原则、更新节奏 |
| ROADMAP.md | 四阶段课程地图（含每周粒度的阶段 1）、状态标记、月度复盘区、行业变化记录区 |
| docs/01-sprint-2months.md | 八周详细计划：每周「目标/原理输入/实践任务/产出/验收清单/裁剪顺序/加餐」，两个月验收清单 |
| docs/02-codex-study-guide.md | 为什么先造后读、仓库事实卡（Apache-2.0、Rust 96.6%、codex-rs 结构）、六步阅读路径、每步问题清单、笔记模板、上游跟踪方式 |
| docs/03-resources.md | 四层信息雷达（含具体链接）、原理论文分级清单（必读/选读/深入/大白话专区）、本地临床运行时（R + pharmaverse）、每周扫描操作指引 |
| docs/04-learning-log.md | 周记模板（学了什么/做了什么/卡在哪/雷达发现/下周计划）、月度复盘模板、使用规则 |