P2 重点主线 · 90 天不加量
系统设计 × AI 开发 × Harness
不仅学习模型怎样回答，更学习如何把任务、上下文、工具、状态、代码变更与人的判断组织成一个工作系统。
本地运行完整示例 · 不调用付费模型、不改真实代码
npm run learning:harness -- workflow内容已准备，P2 尚未启动。默认是脚本模型 + 内存虚拟仓库，用于理解 harness；不是已接入真实 LLM 的开发代理，也不改变个人学习进度。
本轮实践核验 ：四章已补充原理、案例与适用条件；厂商特定能力不等于通用最优方案。
H01 · S01—S21 · 总 Day 91—111
任务契约与上下文架构
讲透上下文选择、版本与记忆；用完整案例区分 Compaction、KV 前缀缓存、Skills 渐进加载和外部状态。
原理详解 · 完整案例推演 · 设计取舍 · 源码 →
H02 · S22—S42 · 总 Day 112—132
Harness 循环、状态与恢复
从四步执行到异步工具、后台请求与中途改方向，推演恢复、取消、幂等和晚到结果的因果关系。
原理详解 · 完整案例推演 · 设计取舍 · 源码 →
H03 · S43—S63 · 总 Day 133—153
工具接口与代码变更边界
解释工具搜索、程序化调用、MCP 版本演进及沙箱隔离；区分发现、授权、执行与版本绑定变更。
原理详解 · 完整案例推演 · 设计取舍 · 源码 →
H04 · S64—S84 · 总 Day 154—174
AI 开发完整工作流
从需求到最小完整变更，深入模型与 Harness 协同调整、Provider 消息流、轻量 Trace 和仓库知识回流。
原理详解 · 完整案例推演 · 设计取舍 · 源码 →
2026 实践核验：来源、适用条件与实现边界
核验日期：2026-09-12。 只覆盖 H01～H04 本轮新增的 Harness / AI 开发主题，不表示对全仓库 360 篇教材逐条重新核验。检索日不是资料发布日期，动态文档以后仍可能变化。
网页入口：Harness 主线 · 实践核验。正文已经写入机制、案例与取舍，不需要先读完全部外部资料。
学习状态：沿用原 P2 九十天安排，不增加天数、考试或进度账本。
A. 怎样理解这里的“最佳实践”
这里指：参考可核验的一手资料，解释一种做法解决什么问题、凭什么有效、在哪些条件下不值得采用。它不意味着存在一套能同时优化所有模型、任务、成本和风险的唯一配置。
教材分开四类结论。稳定工程原则包括责任分离、版本绑定、权限检查与未知状态的明确表达。具体产品能力包括 API 压缩项、异步工具与缓存参数，需要核对模型和接入方式。作者工程经验来自特定系统，有启发但不自动具有普遍性。本仓库原创设计是帮助学习的字段、状态表和反事实案例，不冒充厂商源码或已运行系统。
例如，Anthropic 的 2026 年应用开发文章报告了随模型变化简化 Harness 的经历；Managed Agents 文章讨论把持久会话、执行环境与可替换的 Harness 分开。可迁移的启发是“重新检查策略是否必要、明确状态所有者”，不是照搬角色数量或扩大自主范围。应用开发经验、Managed Agents 架构经验
B. 已落进四章的内容
| 阅读入口 | 新增的机制与案例 |
|---|---|
| H01 · 上下文架构 | 稳定前缀为何可以复用计算；Skills 如何先发现再展开；压缩后怎样保留 sum 的版本、提案和“未应用”状态；四种机制如何互相影响 |
| H02 · 运行与恢复 | Promise、后台请求与异步工具的区别；双任务并行时用户收窄范围；取消后的晚到结果；调用关联、执行状态与任务适用性分开 |
| H03 · 工具与边界 | 工具搜索为何不是授权；MCP 版本演进；挂载、凭证与网络的组合边界；程序化查询多个模块后怎样保留部分失败 |
| H04 · AI 开发 | 模型与 Harness 协同调整；目标约束与过程提示；一次 read 的 Provider 消息流；用 trace 定位信息传递失败；仓库知识的失效与回流 |
四章保留原有离线例子，新增设计解释它尚未覆盖的真实系统问题。缓存、异步和程序化调用是按需理解的选项，不是要把每个开关都打开。
C. 一手来源、版本与采用边界
下表资料在本轮实际打开核对。动态指南没有明确固定发布日期时，不编造日期；“当前”只指核验当天看到的文档。
| 来源 | 核验内容与采用边界 |
|---|---|
| OpenAI · Compaction | 阈值触发、独立压缩与续接项。压缩项不是普通可读摘要或外部动作账本；不同续接方式分别处理 |
| OpenAI · Prompt caching | 匹配前缀的计算复用。不缓存“正确答案”；不把旧参数、价格或保留期写成跨模型常量 |
| OpenAI · Build skills | 方法元信息、正文和附属资源。借鉴渐进加载，方法文件不能自行扩大任务权限 |
| OpenAI · Async tool calling | 模型继续工作、应用运行工具与结果关联。有模型和工具类型限制，不是任意 async 函数都具备此能力 |
| OpenAI · Background mode | 长模型请求后台执行与状态获取。不自动托管业务工具任务或永久保存应用状态 |
| OpenAI · Mid-turn steering | 工作中接收新指令。需核对模型与 WebSocket 路径，已发生的外部动作不会自动回滚 |
| OpenAI · Tool search | 延迟发现和加载工具定义。相关性、可见性与执行授权是不同判断 |
| OpenAI · Programmatic Tool Calling | 程序编排与中间结果处理。需保留失败与覆盖范围，不视为通用并发开关 |
| OpenAI · Sandbox Agents | Harness 与执行环境分离。核验时 SDK 能力为 beta；借鉴设计，不宣称本地已有相同隔离 |
| MCP · 2026-07-28 发布说明；基础协议 | 无状态核心与请求自描述。旧 initialize / session 流程不能标作新版本通用流程；历史笔记保留对照 |
| MCP · Tools；Caching | 工具结构与目录缓存。private 不跨授权上下文；public 只适合不含用户特定数据的结果；缓存不替代访问控制 |
| OpenAI · Model guidance；Models and providers | 模型相关指令、显式配置与兼容性。不预设最优型号；迁移时同时审视提示、工具与运行策略 |
| OpenAI · Agents；Function calling | 托管/SDK/直接 API 责任及调用结果关联。教材 JSON 仅为协议片段，未发出真实请求 |
| OpenAI · Integrations and observability | 调用、工具与交接的结构化 trace。本仓库只有简化事件，未启用 SDK 导出或上传正文 |
| Anthropic · Harness design，2026-03-24 | Harness 随模型与任务调整的经验。不引入文中的多轮评分门槛或完整多 Agent 平台 |
| Anthropic · Managed Agents，2026-04-08 | 持久会话、执行与可变 Harness 分离。作为系统设计阅读，不是本仓库的部署验证 |
API、SDK 与协议各有自己的版本。MCP 新版发布，不代表任意客户端已升级；某模型支持异步工具，也不意味着托管工具、程序化调用和所有传输可以任意组合。真正接入时沿所选路径核对兼容性，本轮不生成未经验证的跨产品配置。
D. 当前实现与教材设计的差距
源码仍为 src/learning/ai-harness/runtime.ts 与 demo.ts。本轮优化教材和页面，没有把概念扩成生产 Agent。
| 对象 | 已有教学实现 | 讲透但尚未实现 |
|---|---|---|
| 上下文 | 任务、路径白名单、最近观察、字符上限 | token 计数、Compaction、KV 缓存统计、Skills loader |
| 运行 | 单动作循环、预算、暂停 JSON、快照检查 | 后台服务、持久 job、异步工具调度、运行中 steering |
| 工具 | 内存 search/read、版本绑定预览、finish | MCP、工具搜索服务、程序化执行器、真实磁盘应用 |
| 隔离 | 精确字符串路径白名单，不执行 shell | OS sandbox、网络策略、受控挂载、凭证代理 |
| 模型与观测 | 脚本替身、ModelPort、步骤事件、handoff | 真实 Provider、usage、完整 trace、模型效果对比 |
“尚未实现”不等于只能写大纲：可以完整推演信息流、状态变化和失败原因，但不能写成自己的生产证据。sum 四步例子对应离线程序；双 job、协议 JSON 和 trace 是设计案例，未知耗时与 usage 不填零、不编造测量。
E. 不加天数，怎样学进去
H01 学完原案例后，比较缓存、压缩与状态的职责；H02 沿双 job 时间线理解“晚到但不再适用”；H03 比较工具目录、协议与执行隔离；H04 画出一次 Provider 调用，再用一条 trace 解释一个具体卡点。每次取一个问题深入即可，不要求同时学习所有 SDK。
CS329S、FSDL 与分布式系统课程继续提供原理，官方指南补充变化快的机制。完整课程地图保留在 docs/ai-deep-mastery/phase-2-systems/PROFESSIONAL_COURSE_REFERENCE_MAP.md。模型、SDK 或协议升级时，检查机制前提，再加有日期的更新说明；不只更换型号名字就宣称全部更新，也不把软件案例外推成 AGI 或真机能力。
完整规划与学习方法
规划更新：2026-09-12
学习范围：沿用 P2 第 91～180 天，不另加 90 天
重点：设计 AI 系统、构造开发上下文、实现 Agent harness、理解 AI 辅助软件开发
节奏：知识与动手优先，不求职、不增加考试或 Gate；已有教材全部保留
实践核验（2026-09-12）：四章已结合当前 OpenAI 官方指南、MCP 2026-07-28 规范与 Anthropic 一手工程经验补充机制、案例和取舍。请查看来源、版本与实现边界；此日期只覆盖本轮主题，不表示全部历史教材重新核验。
1. 重点怎样调整
下一阶段不以“遍历所有 AI 基础设施工具”为目标，而以“能解释并实现一个小型 AI 开发工作系统”为主线。模型只是其中一个部件；你要学会把需求、上下文、工具、状态、执行边界、变更和人的判断连接起来。
建议将约 60% 学习精力放在系统设计、harness 与 AI 开发工作流，约 25% 放在数据、版本、接口、观测等支撑知识，约 15% 留给训练/Serving 原理与个人兴趣。比例可调，不按小时打卡。
已有 S01～S90 日课与 12 周机制讲义继续作为参考库；下列 H01～H04 是同一个阶段的四段学习主线，不是四份额外作业。只选能解决当下问题的支撑材料，不要求同时全量阅读两套内容。
教材怎样读：先理解原理，再对照运行
H01～H04 已从专题导读扩写为四章原理教材。正文直接讲解概念为何成立、机制如何运作、设计取舍和失败边界，并逐步推演同一个 sum 修复提案。无需先跳到外部课程，才能理解这里的知识点。
| 章节 | 正文已经展开的问题 |
|---|---|
| H01 | 不完整信息下的决策、任务契约、预算与来源版本；Compaction、KV 前缀缓存、Skills 渐进加载和外部状态的分工 |
| H02 | 四步轨迹、暂停恢复、超时与幂等；异步工具与后台请求、中途改方向、双 job 时间线及晚到结果 |
| H03 | 四工具契约、版本绑定与注入；工具发现和逐次授权、MCP 版本演进、程序化调用、控制/执行平面隔离 |
| H04 | 需求与跨层影响、最小完整变更；模型与 Harness 协同调整、Provider 协议流、轻量 trace、知识回流与失效 |
每章页面都包含正文目录、示例命令和实际源码；正文中的设计扩展另行标明，不冒充已有实现。初读先顺着案例理解，遇到具体细节再展开源码与支撑日课即可，不增加每日提交或考试要求。
内容范围要分清：此次深化的是四章 Harness 主教材，不是重新写了 90 篇 Harness 日课。原 S01～S90 与 12 周讲义仍然保留，可按问题查阅；教材已写入不等于个人学习已完成。
2. 90 天路线：四段深入，六天整合
| 主线 | 对应日课 / 总日 | 系统设计问题 | AI 开发落地 |
|---|---|---|---|
| H01 · 任务与上下文架构 | S01～21 / Day091～111 | 如何把模糊目标变成边界清楚的任务？模型应该看到什么？ | Task contract、仓库地图、来源与版本、上下文预算 |
| H02 · Harness 运行与恢复 | S22～42 / Day112～132 | 谁控制循环？状态保存在哪里？什么时候停止？ | Model port、工具观察、状态机、预算、checkpoint 与恢复 |
| H03 · 工具与代码变更边界 | S43～63 / Day133～153 | 模型提出的调用与修改怎样进入可信执行层？ | Schema、scope、读后改、base hash、局部变更提案与交接 |
| H04 · AI 开发完整工作流 | S64～84 / Day154～174 | 如何用 AI 理解、设计、修改和维护系统，而非只生成代码？ | 需求澄清、影响分析、最小改动、轻量观察、review 与知识更新 |
| 轻量整合 | S85～90 / Day175～180 | 哪些是系统工程问题，哪些是能力研究问题？ | 一张系统图、一段可解释运行、三个研究兴趣；不作硬性产出 |
H01 的三周
第一周以一个已有函数或页面为样本，说明目标、输入输出、不改什么、谁负责决定。第二周把代码、文档和版本组织成可追溯上下文，并理解 Skills 的按需加载。第三周比较压缩、前缀缓存与外部状态的不同作用，把 W3 的训练内存作为选读；本阶段不要求训练模型。
H02 的三周
第一周画单 Agent 的 observe → decide → act 循环，区分固定 workflow 与模型自主选择。第二周理解状态、工具结果与停止原因，运行暂停/恢复示例。第三周沿双 job 案例理解异步调用、中途改方向与晚到结果；不要求部署后台服务，也不重放真实副作用。
H03 的三周
第一周设计少量目标明确的工具，约定参数、结果、错误和权限，并区分工具搜索与授权。第二周理解虚拟仓库与真实 OS sandbox、控制平面与执行平面的区别。第三周结合版本绑定提案，阅读 MCP 新旧版本和程序化调用案例；协议和批量调用都不替代执行边界。
H04 的三周
第一周用一份任务卡完成从需求到设计的推理，区分目标约束和过程提示。第二周运行本地开发闭环，再用 Provider 消息流理解真实模型接入责任。第三周用一条 trace 解释卡点，讨论模型与 Harness 的配合，再把经验提炼进仓库说明；不增加自动评分流水线。
3. Harness 到底是什么
这里把 harness 定义为围绕模型组织任务执行的工程运行层：构造上下文、调用模型、解析动作、执行工具、保存状态、管理资源与停止、留下交接信息。不同项目对词的边界不同，不把这个定义当成统一标准。
| 部件 | 负责什么 | 不负责什么 |
|---|---|---|
| 模型 | 根据上下文提出文本或动作 | 不自行决定真实权限，也不自动知道外部执行结果 |
| Harness | 上下文、循环、工具路由、状态、预算、停止 | 不等于 OS 隔离，也不让模型天然正确 |
| 工具适配器 | 把受限动作转成明确操作与观察 | 不从模型内容继承更高权限 |
| Sandbox | 限制进程、文件、网络等运行环境 | 不保证业务含义正确或代码质量 |
| 人的工作界面 | 目标、授权、review、反馈与交接 | 不应只是机械地点击“同意” |
一个更长的 Prompt 不能替代这些职责。反过来，也不必一开始就做多 Agent；单个可解释循环通常更适合学习状态与边界，再按实际瓶颈决定是否拆分。
4. 已实现的本地教学 Harness
入口：Harness 学习页。源码在 src/learning/ai-harness/runtime.ts、demo.ts，脚本在 scripts/ai-harness-lab.ts。
npm run learning:harness -- context
npm run learning:harness -- resume
npm run learning:harness -- boundaries
npm run learning:harness -- workflow
实现包括：任务读写白名单、有限上下文包、返回 Promise 的 model port（不等于异步工具调度）、严格动作 schema、search/read/propose_edit/finish 路由、步骤预算、暂停 checkpoint、快照一致性检查、版本绑定的改动预览、事件记录与 handoff。
默认 model 是确定性脚本替身，仓库是内存里的三份合成文件。完整示例能从搜索、读取走到代码修改提案，但没有接入真实 LLM，没有修改项目源码，没有启动 shell，没有访问网络，也没有生产级 sandbox。输出中的 needs_review 不是“开发完成”。
只有在明确选择模型服务、费用与数据范围后，才应新增真实 provider adapter。那时还需要 token 计数、超时与取消、速率限制、敏感数据处理、真实工具隔离和成本上限；当前不默默读取 API Key 或上传仓库。
5. 轻量练习原则
每次挑一个问题：为什么模型缺上下文；为什么工具返回太大；为什么它重复动作；为什么旧 patch 不能直接应用；为什么“我完成了”还缺证据。运行一个相关示例，改一处输入，再写两三句观察即可。
轻量不等于不用检查。可以沿用一个已有命令、一次页面浏览或一个小例子来确认当前变更，但不以测试数量和门槛为学习主角，也不搭建额外 gate 平台。
6. 专业阅读与选读边界
- Stanford CS329S：系统生命周期与工程设计背景。
- FSDL 2022：数据、开发工具、部署和持续学习的连接。
- Anthropic：Building Effective Agents：比较 workflow 与 agent 的结构；只取适合当前任务的复杂度。
- Anthropic：Context Engineering：上下文选择、动态获取与有限资源视角。
- Anthropic：Effective Harnesses：跨会话增量进展与结构化交接；不照搬文章中的大规模功能清单或测试流程。
- Anthropic：Writing Tools for Agents：工具的语义、结果长度和错误反馈。
以上为专业课程与一手工程经验，不是证明某一种架构普遍最优的定律。本仓库实现为自编教学例子，不能代表原作者产品或 SDK 的完整行为。
7. 未来延伸到 AGI 与具身智能
先学会归因：改了 harness 后任务成功，可能来自更好的工具、上下文或分解，不一定来自模型内在能力提升。P3 再研究规划、记忆、学习效率和泛化时，可以固定模型对比系统条件，或固定系统比较模型，避免混淆来源。
P4 把工具动作换成环境动作后，会出现延迟观测、状态估计、动作期限、不可逆后果与接管。软件开发中“先提案再 review”的思路可以参考，但不能直接当物理安全机制。当前继续只做纸面与仿真层面的延伸。