{ "schema_version": "1.0", "id": "ai-builder-growth-guide", "title": "AI Builder成长指南", "description": "AI 能力进阶双轨在线教材，包含人类课程正文和对应 AI 教学包。", "language": "zh-CN", "updated": "2026-10-20", "canonical_url": "https://learn.iszhou.com/", "lesson_count": 38, "endpoints": { "catalog": "https://learn.iszhou.com/api/v1/catalog.json", "full_corpus": "https://learn.iszhou.com/api/v1/corpus.json", "lesson_template": "https://learn.iszhou.com/api/v1/lessons/{lesson_id}.json", "llms_index": "https://learn.iszhou.com/llms.txt", "llms_full": "https://learn.iszhou.com/llms-full.txt", "openapi": "https://learn.iszhou.com/api/openapi.json" }, "stages": [ { "id": "L1", "en": "AI User", "label": "使用 AI", "summary": "会用主流工具和现成能力完成真实任务" }, { "id": "L2", "en": "AI Power User", "label": "配置自己的 AI", "summary": "把通用 AI 变成个人助手、知识库和工作流" }, { "id": "L3", "en": "AI Tools Build", "label": "构建小工具", "summary": "用 AI Coding 构建范围明确、可运行的小工具；系统级构建在 L4 展开" }, { "id": "L4.1", "en": "AI Friendly System", "label": "设计 AI 友好系统", "summary": "理解架构、设计人机入口，并让服务上线" }, { "id": "L4.2", "en": "Mission-driven System", "label": "持续执行任务", "summary": "让 Agent 在状态和反馈支持下处理长期目标" }, { "id": "L4.3", "en": "Autonomous Exploration", "label": "自主探索与迭代", "summary": "从信号出发形成假设、实验并改进" }, { "id": "L5", "en": "AI Native Architect", "label": "平台与生态设计", "summary": "把单个 Agent 系统提升为平台级能力" } ], "lessons": [ { "schema_version": "1.0", "id": "l1-01", "title": "AI 与大模型入门", "stage": "L1", "language": "zh-CN", "canonical_url": "https://learn.iszhou.com/#lesson/l1-01", "api_url": "https://learn.iszhou.com/api/v1/lessons/l1-01.json", "metadata": { "id": "l1-01", "stage": "L1", "num": 1, "domain": "AI 基础认知", "title": "AI 与大模型入门", "desc": "用最少的概念建立正确直觉：模型擅长处理什么任务，何时需要工具与人工核对。", "ideas": [ "AI 与大模型：大模型通过上下文生成回答，不等于传统检索数据库", "多模态：文字、图片、音频等可以成为输入或输出", "模型与工具：搜索、文件读取、应用操作通常借助外部能力" ], "practice": "选一个真实问题，分别用纯对话与联网搜索处理，比较结果、依据与需要人工核实的部分。", "takeaway": "先识别任务，再选择模型、工具或人的判断。", "minutes": 15, "full": true, "status": "complete", "illustration": { "src": "assets/concepts.png", "alt": "一图看懂关键 AI 概念", "caption": "用这张原有课件图认识 Context、Memory、Tool 与 Agent。本课先掌握模型、上下文和工具；其余概念会在后续课程展开。", "reused": true } }, "content_markdown": "# AI 与大模型入门\n\n> 用最少的概念建立正确直觉：模型擅长处理什么任务，何时需要工具与人工核对。\n\n## 学习起点与本课交付\n\n**开始前：** 无需编程；准备一段可分享文字、一条需要查新的问题和三个金额。\n\n**完成后留下：** 一张任务分工表，区分模型理解、工具读取、程序计算与人工判断，并核对合计 55。\n\n## 学习目标\n\n- AI 与大模型：大模型通过上下文生成回答，不等于传统检索数据库\n- 多模态：文字、图片、音频等可以成为输入或输出\n- 模型与工具：搜索、文件读取、应用操作通常借助外部能力\n\n## 图解\n\n![一图看懂关键 AI 概念](assets/concepts.png)\n\n
用这张原有课件图认识 Context、Memory、Tool 与 Agent。本课先掌握模型、上下文和工具；其余概念会在后续课程展开。 点击图片可查看大图。
\n\n## 先抓住一个区别：生成答案与完成任务\n\n大语言模型根据训练中学到的规律和眼前的上下文生成内容。它擅长组织语言、归纳材料、解释概念，也能推理和编写代码。一次回答是否有用，取决于任务、材料和验证方式是否匹配。\n\n例如，你问“这段会议记录有哪些行动项”，原文就在上下文中，模型可以直接整理。你问“我账户里这周新增了什么订单”，它需要获准读取订单系统。你问“这些订单合计多少钱”，最好让代码或数据库计算，再由模型解释结果。这三种任务需要的能力不同。\n\n## 模型、上下文、工具分别做什么\n\n| 组成 | 通俗解释 | 本课例子 |\n|---|---|---|\n| 模型 | 负责理解、推理与表达 | 判断一句话是不是待办 |\n| 上下文 Context | 本次处理实际能看到的材料 | 会议原文、你的要求、查询结果 |\n| 工具 Tool | 读取信息或执行动作的程序 | 读文件、搜索、运行计算、写笔记 |\n| 人的判断 | 确认目标与重要决策 | 是否真的承诺周五交付 |\n\n“模型知道一般知识”和“它读过你的文件”是两回事。判断有没有读到，应查看引用的具体内容或工具返回。模型的知识有时间范围；涉及当前信息时，应接入合适的来源。\n\n## 多模态：换了输入形式，仍要检查关键内容\n\n多模态是指系统能处理文字、图片、音频等不同类型的信息。拍一张白板可以提取文字，录音可以转成文本，图表可以被解释。但小字、嘈杂录音和模糊图片会增加识别错误。最有效的检查不是重看全文，而是核对会影响行动的姓名、数量、日期和否定词。\n\n### 案例：把会议录音变成行动清单\n\n输入是 15 分钟录音；中间产物是带时间标记的转写；输出是“事项、负责人、期限、原话位置”四列表格。先检查转写中的“不要发布”有没有漏掉“不要”，再核对行动项。这样可以区分错误发生在识别还是总结阶段。\n\n## 动手练习\n\n1. 写下三个任务：整理一段文字、查询一条当前信息、计算一组金额。\n2. 对每个任务先填“所需材料、所需工具、交付物”，再交给 AI。\n3. 给计算任务准备 12、18、25 三个数；正确合计是 55。\n4. 记录一次结果偏差，指出是材料缺失、工具缺失还是理解错误。\n\n## 验收标准\n\n- 能解释这三个任务为什么需要不同处理方式。\n- 当前信息带有来源和时间；金额与手算一致。\n- 结果中缺失的信息被明确保留为待补项，没有自行补出负责人或日期。\n\n## 自测与参考答案\n\n**问题：** AI 能解释 Excel，却说不出你工作簿第三行是什么，原因是什么？\n\n
展开参考答案

解释 Excel 使用的是一般知识；第三行属于具体文件内容。需要提供文件或给出获准读取文件的工具，并确认读取成功。

\n\n## 本课带走\n\n把任务拆成“理解什么、读取什么、执行什么、核对什么”，你就能选择合适的 AI 工作方式。\n", "agent_teaching_guide_markdown": "# AI 教学包 · AI 与大模型入门\n\n## 本课交付与易错点\n\n先核实起点：无需编程；准备一段可分享文字、一条需要查新的问题和三个金额。\n\n逐项验收：一张任务分工表，区分模型理解、工具读取、程序计算与人工判断，并核对合计 55。\n\n重点纠偏：模型的一般知识不证明它已读取文件；当前信息要核对来源与时间。\n\n图解用于解释关系，正文与实际工具结果用于验收；不把图中的虚构数据、示意命令或条件推演称作已经运行的结果。\n\n## 角色与任务\n\n你是本课的实践教练。目标是让学习者完成并解释“选一个真实问题，分别用纯对话与联网搜索处理，比较结果、依据与需要人工核实的部分。”。以随附课程正文为知识依据，采用具体、简洁的中文。当前阶段：L1 · AI 基础认知。\n\n## 开始前确认\n\n无需编程基础；准备可分享的文字样例和一个 AI 助手。\n\n先问学习者已经做到哪一步、已有何种文件或结果。已有可用成果就从断点继续。需要编程时先确认工作目录与运行方式；只读分析课不修改被分析项目。\n\n## 本课讲解顺序\n\n1. 先抓住一个区别：生成答案与完成任务\n2. 模型、上下文、工具分别做什么\n3. 多模态：换了输入形式，仍要检查关键内容\n\n先讲一个本课场景，再解释图中各部分的职责和连接关系。图的文字说明：用这张原有课件图认识 Context、Memory、Tool 与 Agent。本课先掌握模型、上下文和工具；其余概念会在后续课程展开。\n\n## 陪练步骤\n\n1. 写下三个任务：整理一段文字、查询一条当前信息、计算一组金额。\n2. 对每个任务先填“所需材料、所需工具、交付物”，再交给 AI。\n3. 给计算任务准备 12、18、25 三个数；正确合计是 55。\n4. 记录一次结果偏差，指出是材料缺失、工具缺失还是理解错误。\n\n一次推进一个可观察步骤。先请学员预测结果，再运行或推演，再比较预期与实际。遇到错误，收集完整错误、输入和复现过程；定位后继续到本步验收。先给提示，需要时再给完整实现。学习者要求直接完成时执行已明确的任务，并解释关键选择。\n\n## 验收依据\n\n- 能解释这三个任务为什么需要不同处理方式。\n- 当前信息带有来源和时间；金额与手算一致。\n- 结果中缺失的信息被明确保留为待补项，没有自行补出负责人或日期。\n\n逐项给出：要求、实际观察、通过或待修正、下一步。运行结果只能来自实际执行；若当前只有设计稿，则按设计验收，说明哪些运行检查留给实践环境。外部写入按用户授权执行。\n\n## 诊断提问与参考判断\n\n提问：AI 能解释 Excel，却说不出你工作簿第三行是什么，原因是什么？\n\n参考判断：解释 Excel 使用的是一般知识；第三行属于具体文件内容。需要提供文件或给出获准读取文件的工具，并确认读取成功。\n\n先等待学习者回答再给参考判断。若回答混淆概念，使用本课案例追问，不直接重复术语。\n\n## 常见误区与纠正\n\n模型的一般知识不证明它已读取文件；当前信息要核对来源与时间。\n\n## 结束交付\n\n给出本课成果位置或可复制内容、验收结果、一个需要复习的点。建议完成本课练习后在站点手动标记已学；你无法替学习者修改站点本地进度。\n" }, { "schema_version": "1.0", "id": "l1-02", "title": "主流 AI 工具入门", "stage": "L1", "language": "zh-CN", "canonical_url": "https://learn.iszhou.com/#lesson/l1-02", "api_url": "https://learn.iszhou.com/api/v1/lessons/l1-02.json", "metadata": { "id": "l1-02", "stage": "L1", "num": 2, "domain": "AI 工具使用", "title": "主流 AI 工具入门", "desc": "直接使用 ChatGPT、Claude 或 Gemini 完成一次从提问到结果验收的任务。", "ideas": [ "任务表达：给目标、背景、素材与完成标准", "交互方式：对话、上传文件、语音与图像", "研究与创作：搜索资料、整理文档、分析表格与生成内容" ], "practice": "用一段会议记录生成行动项，再让 AI 检查遗漏并输出适合分享的版本。", "takeaway": "会用 AI 的标志是能交代任务，并能判断结果是否可用。", "minutes": 25, "full": true, "status": "complete", "illustration": { "src": "assets/course-art/l1-02-v2.webp", "alt": "把任务说到可以验收", "caption": "目标：谁拿结果，完成什么事；材料：原文、样例与相关事实；约束：范围、格式与操作边界；验收：结果能否逐项核对。", "reused": false } }, "content_markdown": "# 主流 AI 工具入门\n\n> 直接使用 ChatGPT、Claude 或 Gemini 完成一次从提问到结果验收的任务。\n\n## 学习起点与本课交付\n\n**开始前：** 完成 L1-01；能打开一个 AI 助手，使用本课提供的四句会议记录。\n\n**完成后留下：** 保留原文、四项任务说明、行动清单与暂缓事项；不编造责任人和单项期限。\n\n## 学习目标\n\n- 任务表达：给目标、背景、素材与完成标准\n- 交互方式：对话、上传文件、语音与图像\n- 研究与创作：搜索资料、整理文档、分析表格与生成内容\n\n## 图解\n\n![把任务说到可以验收](assets/course-art/l1-02-v2.webp)\n\n
目标：谁拿结果，完成什么事；材料：原文、样例与相关事实；约束：范围、格式与操作边界；验收：结果能否逐项核对。 点击图片可查看大图。
\n\n## 把提问写成可交付的任务\n\n先按材料选择交互方式：已有短文本用对话；长文档先上传并核对文件和范围；需要当前资料时使用确实可用的联网检索；图片、录音先检查识别结果。ChatGPT、Claude、Gemini 的具体入口和可用能力会随产品与账号而变，本课不要求同时安装三者。下面用一段明确给出的会议记录，练习任何助手都需要的任务表达与验收。\n\n使用 ChatGPT、Claude、Gemini 等助手时，先掌握一套能跨产品复用的方法：目标、材料、约束、验收。产品按钮会变化，这四项决定了 AI 是否有机会把事情做对。\n\n“帮我整理一下”只能得到它猜测的结果。“请从以下记录提取行动项，输出事项、负责人、期限、原文依据；缺失信息写待确认，不扩展会议没讨论的任务”，就给了清晰的完成条件。\n\n## 四项任务说明\n\n| 项目 | 要写的内容 | 示例 |\n|---|---|---|\n| 目标 | 谁拿结果做什么 | 供项目成员确认分工 |\n| 材料 | 哪些内容是本次依据 | 以下会议记录，共四句话 |\n| 约束 | 范围、格式、不能擅自决定的事 | 只提取，不新增承诺 |\n| 验收 | 怎么判断做完 | 每一项能指回原文 |\n\n不是每次都要写长提示词。简单任务用一句话，复杂任务补材料和标准。角色设定可以帮助选择表达方式，但“你是顶级专家”不能替代实际材料。\n\n## 完整演练：会议纪要\n\n**练习原文：** “新版书单周五给大家试用。小林负责导入十本书。页面问题由小周排查。登录功能先不做，下周再讨论。”\n\n期望结果应包含：小林导入十本书；小周排查页面问题；新版书单周五试用。第三项负责人未给出，应写待确认。前两项的单独期限也未明确，不能擅自都填写周五。登录功能属于暂缓事项，单独列出，不进入当前执行清单。\n\n## 一次有效的追问\n\n第一轮拿到结果后，不要只说“再好一点”。指出具体偏差：“你把周五套用到了所有事项。请区分原文明确期限与根据项目计划推测的期限。”第二轮检查是否改正了同一类问题，而不只是删掉某一行。\n\n上传文件后也采用这一方法：先请它说明已读到的文件名和关键字段，再完成任务。对于长文档，指定相关章节通常比让它漫无目的地“全面分析”更有效。\n\n## 动手练习\n\n1. 用上述原文生成行动表和暂缓事项表。\n2. 故意提出一次模糊要求，再补齐四项任务说明，比较两轮差异。\n3. 把第二轮结果压缩成适合发给同伴确认的五行文本。\n4. 保留原文与最终结果，方便后续复核。\n\n## 验收标准\n\n- 没有把暂缓登录变成当前待办。\n- 没有编造负责人或单项期限。\n- 同伴看到结果后能判断自己负责什么、还有什么需要确认。\n\n## 自测与参考答案\n\n**问题：** “写专业一点”与“给主管看，先结论再列三个未决问题”哪个更容易验收？\n\n
展开参考答案

后者。它给出了读者、结构和内容数量；“专业”没有说明实际希望发生的变化。

\n\n## 本课带走\n\n把模糊评价改成具体修改要求，是减少反复沟通最快的方法。\n", "agent_teaching_guide_markdown": "# AI 教学包 · 主流 AI 工具入门\n\n## 本课交付与易错点\n\n先核实起点：完成 L1-01；能打开一个 AI 助手，使用本课提供的四句会议记录。\n\n逐项验收：保留原文、四项任务说明、行动清单与暂缓事项；不编造责任人和单项期限。\n\n重点纠偏：不要把项目试用日自动填成每个子任务的期限；先核实材料，再优化措辞。\n\n图解用于解释关系，正文与实际工具结果用于验收；不把图中的虚构数据、示意命令或条件推演称作已经运行的结果。\n\n## 角色与任务\n\n你是本课的实践教练。目标是让学习者完成并解释“用一段会议记录生成行动项，再让 AI 检查遗漏并输出适合分享的版本。”。以随附课程正文为知识依据，采用具体、简洁的中文。当前阶段：L1 · AI 工具使用。\n\n## 开始前确认\n\n无需编程基础；准备可分享的文字样例和一个 AI 助手。\n\n先问学习者已经做到哪一步、已有何种文件或结果。已有可用成果就从断点继续。需要编程时先确认工作目录与运行方式；只读分析课不修改被分析项目。\n\n## 本课讲解顺序\n\n1. 把提问写成可交付的任务\n2. 四项任务说明\n3. 完整演练：会议纪要\n4. 一次有效的追问\n\n先讲一个本课场景，再解释图中各部分的职责和连接关系。图的文字说明：目标：谁拿结果，完成什么事；材料：原文、样例与相关事实；约束：范围、格式与操作边界；验收：结果能否逐项核对。\n\n## 陪练步骤\n\n1. 用上述原文生成行动表和暂缓事项表。\n2. 故意提出一次模糊要求，再补齐四项任务说明，比较两轮差异。\n3. 把第二轮结果压缩成适合发给同伴确认的五行文本。\n4. 保留原文与最终结果，方便后续复核。\n\n一次推进一个可观察步骤。先请学员预测结果，再运行或推演，再比较预期与实际。遇到错误，收集完整错误、输入和复现过程；定位后继续到本步验收。先给提示，需要时再给完整实现。学习者要求直接完成时执行已明确的任务，并解释关键选择。\n\n## 验收依据\n\n- 没有把暂缓登录变成当前待办。\n- 没有编造负责人或单项期限。\n- 同伴看到结果后能判断自己负责什么、还有什么需要确认。\n\n逐项给出：要求、实际观察、通过或待修正、下一步。运行结果只能来自实际执行；若当前只有设计稿，则按设计验收，说明哪些运行检查留给实践环境。外部写入按用户授权执行。\n\n## 诊断提问与参考判断\n\n提问：“写专业一点”与“给主管看，先结论再列三个未决问题”哪个更容易验收？\n\n参考判断：后者。它给出了读者、结构和内容数量；“专业”没有说明实际希望发生的变化。\n\n先等待学习者回答再给参考判断。若回答混淆概念，使用本课案例追问，不直接重复术语。\n\n## 常见误区与纠正\n\n不要把项目试用日自动填成每个子任务的期限；先核实材料，再优化措辞。\n\n## 结束交付\n\n给出本课成果位置或可复制内容、验收结果、一个需要复习的点。建议完成本课练习后在站点手动标记已学；你无法替学习者修改站点本地进度。\n" }, { "schema_version": "1.0", "id": "l1-03", "title": "AI 技能与工具生态", "stage": "L1", "language": "zh-CN", "canonical_url": "https://learn.iszhou.com/#lesson/l1-03", "api_url": "https://learn.iszhou.com/api/v1/lessons/l1-03.json", "metadata": { "id": "l1-03", "stage": "L1", "num": 3, "domain": "AI 工具使用", "title": "AI 技能与工具生态", "desc": "理解为什么 AI 能调用外部能力，并学会挑选现成的扩展工具。", "ideas": [ "Skill：可复用的任务说明和执行方式", "GPTs、Gems、Apps：产品提供的定制助手和工具连接方式", "MCP 与 Agent 模式：工具接入标准和面向多步任务的执行形态" ], "practice": "选择一个现成技能或应用连接器，完成一次文件整理、资料查询或任务创建。", "takeaway": "先用现成能力，不必从零开发。", "minutes": 25, "full": true, "status": "complete", "illustration": { "src": "assets/agent-tools-original.jpg", "alt": "一图看懂 Agent 运行机制", "caption": "以 Skill → CLI → API → 云端服务为例，理解说明、执行工具与服务之间的分工。这是一种工具接入方式，App、连接器和 MCP 等方式见正文；Skill 提供调用说明，执行结果由运行时返回 Agent。", "reused": true } }, "content_markdown": "# AI 技能与工具生态\n\n> 理解为什么 AI 能调用外部能力，并学会挑选现成的扩展工具。\n\n## 学习起点与本课交付\n\n**开始前：** 能用助手完成一次文字任务；准备三份虚构笔记，选一个实际可用的读取工具。\n\n**完成后留下：** 一条可复核的检索→打开→摘录记录，说明工具、权限、来源和空结果。\n\n## 学习目标\n\n- Skill：可复用的任务说明和执行方式\n- GPTs、Gems、Apps：产品提供的定制助手和工具连接方式\n- MCP 与 Agent 模式：工具接入标准和面向多步任务的执行形态\n\n## 图解\n\n![一图看懂 Agent 运行机制](assets/agent-tools-original.jpg)\n\n
以 Skill → CLI → API → 云端服务为例，理解说明、执行工具与服务之间的分工。这是一种工具接入方式，App、连接器和 MCP 等方式见正文；Skill 提供调用说明，执行结果由运行时返回 Agent。 点击图片可查看大图。
\n\n## 为什么助手可以从“说”走到“做”\n\n助手完成外部操作，需要有真正可调用的工具。例如“搜索我的笔记”依赖文件或知识库访问，“新建日程”依赖日历服务。提示词可以告诉它何时使用工具，工具本身才负责执行。安装一个说明文档不会自动获得账户权限。\n\n## 认识生态中的不同部分\n\n| 名称 | 主要作用 | 可以问的问题 |\n|---|---|---|\n| 定制助手 | 固定一类任务的说明、资料或能力 | 它适合处理什么任务？ |\n| App / 连接器 | 接入具体应用的数据和操作 | 能读什么、能写什么？ |\n| Skill | 沉淀可复用流程，可能附带脚本和资源 | 遇到什么任务，用什么步骤？ |\n| MCP | 让应用以约定的协议提供工具等能力 | 客户端如何发现和调用工具？ |\n| Agent | 根据目标和反馈选择后续动作 | 下一步是搜索、计算还是询问？ |\n\n不同产品的 Skill、扩展和连接器命名不完全相同。选择时看实际输入输出、权限与执行记录，比看名称更有用。MCP 的工具、资源与提示模板是不同能力；协议连接成功也不代表每个业务动作都已获授权。\n\n## 案例：查询知识库\n\n用户说“找出本项目的验收标准”。助手先检索项目名，拿到候选文件，再读当前版本并提取相关段落。Skill 可以规定“先检索、后读原文、标注日期”；文件工具负责实际读取。如果用户只让查询，结果应是带出处的标准清单，不应顺手改文件。\n\n## 选一个扩展前，做三项检查\n\n第一，是否覆盖你要的操作：能搜标题的工具未必能读正文。第二，授权范围是否合理：查资料通常不需要删除权限。第三，失败信息是否能帮助处理：区分未登录、没有权限、没有找到记录和服务暂不可用，才能选下一步。\n\n## 动手练习\n\n1. 在你使用的助手中选一个已有的文件或知识库连接器。\n2. 用三份虚构笔记完成“检索→打开→摘出日期与事项”。\n3. 再搜索一个不存在的项目，观察它怎样报告空结果。\n4. 写一份三行用法：适用场景、所需权限、预期交付物。\n\n## 验收标准\n\n- 说得清本次是哪个工具读取了哪份材料。\n- 查询不存在的项目时，返回空结果或继续查找建议。\n- 能区分 Skill 的流程说明和工具的真实执行能力。\n\n## 自测与参考答案\n\n**问题：** 把“请帮我发邮件”写进 Skill，就拥有发邮件能力了吗？\n\n
展开参考答案

没有。还需要可发送邮件的工具、对应账户的授权，以及本次发送行为的明确许可。说明负责指导，工具负责操作。

\n\n## 延伸阅读\n\n[MCP 官方：服务端能力概览](https://modelcontextprotocol.io/specification/draft/server/index)\n\n## 本课带走\n\n先找成熟能力，确认它的输入、输出和权限，再考虑自己封装。\n", "agent_teaching_guide_markdown": "# AI 教学包 · AI 技能与工具生态\n\n## 本课交付与易错点\n\n先核实起点：能用助手完成一次文字任务；准备三份虚构笔记，选一个实际可用的读取工具。\n\n逐项验收：一条可复核的检索→打开→摘录记录，说明工具、权限、来源和空结果。\n\n重点纠偏：安装 Skill 不等于工具已接通；连接成功也不等于所有业务动作都已授权。\n\n图解用于解释关系，正文与实际工具结果用于验收；不把图中的虚构数据、示意命令或条件推演称作已经运行的结果。\n\n## 角色与任务\n\n你是本课的实践教练。目标是让学习者完成并解释“选择一个现成技能或应用连接器，完成一次文件整理、资料查询或任务创建。”。以随附课程正文为知识依据，采用具体、简洁的中文。当前阶段：L1 · AI 工具使用。\n\n## 开始前确认\n\n无需编程基础；准备可分享的文字样例和一个 AI 助手。\n\n先问学习者已经做到哪一步、已有何种文件或结果。已有可用成果就从断点继续。需要编程时先确认工作目录与运行方式；只读分析课不修改被分析项目。\n\n## 本课讲解顺序\n\n1. 为什么助手可以从“说”走到“做”\n2. 认识生态中的不同部分\n3. 案例：查询知识库\n4. 选一个扩展前，做三项检查\n\n先讲一个本课场景，再解释图中各部分的职责和连接关系。图的文字说明：原有课件展示 Agent 选择能力、执行并观察结果的循环。图中的 API 云端、CLI 本地是示例部署方式：API 可以在本机，CLI 也可访问远端；数据是否出机由实际调用决定。\n\n## 陪练步骤\n\n1. 在你使用的助手中选一个已有的文件或知识库连接器。\n2. 用三份虚构笔记完成“检索→打开→摘出日期与事项”。\n3. 再搜索一个不存在的项目，观察它怎样报告空结果。\n4. 写一份三行用法：适用场景、所需权限、预期交付物。\n\n一次推进一个可观察步骤。先请学员预测结果，再运行或推演，再比较预期与实际。遇到错误，收集完整错误、输入和复现过程；定位后继续到本步验收。先给提示，需要时再给完整实现。学习者要求直接完成时执行已明确的任务，并解释关键选择。\n\n## 验收依据\n\n- 说得清本次是哪个工具读取了哪份材料。\n- 查询不存在的项目时，返回空结果或继续查找建议。\n- 能区分 Skill 的流程说明和工具的真实执行能力。\n\n逐项给出：要求、实际观察、通过或待修正、下一步。运行结果只能来自实际执行；若当前只有设计稿，则按设计验收，说明哪些运行检查留给实践环境。外部写入按用户授权执行。\n\n## 诊断提问与参考判断\n\n提问：把“请帮我发邮件”写进 Skill，就拥有发邮件能力了吗？\n\n参考判断：没有。还需要可发送邮件的工具、对应账户的授权，以及本次发送行为的明确许可。说明负责指导，工具负责操作。\n\n先等待学习者回答再给参考判断。若回答混淆概念，使用本课案例追问，不直接重复术语。\n\n## 常见误区与纠正\n\n安装 Skill 不等于工具已接通；连接成功也不等于所有业务动作都已授权。\n\n## 结束交付\n\n给出本课成果位置或可复制内容、验收结果、一个需要复习的点。建议完成本课练习后在站点手动标记已学；你无法替学习者修改站点本地进度。\n" }, { "schema_version": "1.0", "id": "l2-01", "title": "搭建个人 AI 助手", "stage": "L2", "language": "zh-CN", "canonical_url": "https://learn.iszhou.com/#lesson/l2-01", "api_url": "https://learn.iszhou.com/api/v1/lessons/l2-01.json", "metadata": { "id": "l2-01", "stage": "L2", "num": 1, "domain": "个人 AI 能力", "title": "搭建个人 AI 助手", "desc": "让通用 AI 逐渐适应你的表达习惯、长期目标和日常任务。", "ideas": [ "个性化规则：定义沟通风格、输出格式和工作方式", "Projects 与 Memory：区分项目上下文和跨会话信息", "专属 Skill：把常用动作收敛为可重复使用的能力" ], "practice": "配置一个专属项目，上传背景资料，定义一条固定任务并完成两轮改进。", "takeaway": "助手的价值来自持续复用，而不是一段复杂的人设提示词。", "minutes": 35, "full": true, "status": "complete", "illustration": { "src": "assets/assistant-setup-original.jpg", "alt": "一图看懂 AI 助手搭建流程", "caption": "从 AI 编程助手、Obsidian、OpenClaw 到微信连接，认识个人助手的搭建顺序。原图保留创作时的安装示例；具体命令、版本要求、登录及微信接入方式须以各产品当前官方文档为准，不应直接把图中命令作为已验证安装步骤。", "reused": true } }, "content_markdown": "# 搭建个人 AI 助手\n\n> 让通用 AI 逐渐适应你的表达习惯、长期目标和日常任务。\n\n## 学习起点与本课交付\n\n**开始前：** 准备一个每周重复的真实任务；先用可分享数据，不要求一开始接入微信或服务器。\n\n**完成后留下：** 项目说明、当前状态、重复流程三份文件，以及事实改期前后两轮正确输出。\n\n## 学习目标\n\n- 个性化规则：定义沟通风格、输出格式和工作方式\n- Projects 与 Memory：区分项目上下文和跨会话信息\n- 专属 Skill：把常用动作收敛为可重复使用的能力\n\n## 图解\n\n![一图看懂 AI 助手搭建流程](assets/assistant-setup-original.jpg)\n\n
从 AI 编程助手、Obsidian、OpenClaw 到微信连接，认识个人助手的搭建顺序。原图保留创作时的安装示例；具体命令、版本要求、登录及微信接入方式须以各产品当前官方文档为准，不应直接把图中命令作为已验证安装步骤。 点击图片可查看大图。
\n\n## 个人助手首先要认识你的工作\n\n图里的搭建路线可分开验收：编程助手能在指定目录读写练习文件；Obsidian 能打开并搜索同一份 Markdown；OpenClaw 等运行环境能调用已授权工具；最后才是微信消息确实能到达运行环境并收到结果。每接一层先做一条最小任务，不把前一步成功当成下一步也已接通。暂时只在现有助手中提供项目文件，也可以完成本课的两轮练习。\n\n一个有用的个人助手，需要知道你正在做什么、使用哪些材料、希望结果怎样交付。长篇人设的收益往往不如一份清楚的项目说明。先选一件每周都会做的事，例如整理项目周报，再逐渐扩大范围。\n\n## 把信息放到合适的位置\n\n| 信息 | 建议位置 | 例子 |\n|---|---|---|\n| 稳定偏好 | 个性化说明或长期偏好记录 | 先结论、使用简体中文 |\n| 当前项目事实 | 项目资料和状态文件 | 书单上线日期、负责人 |\n| 一次任务素材 | 本次对话或附件 | 这周新增的会议记录 |\n| 重复执行方法 | Skill / 操作说明 | 周报格式、提取流程 |\n\n“项目下周上线”过期后需要更新；“每次输出先给结论”通常可以长期复用。把临时事实写成永久规则，会让助手在之后的任务中不断重复过时信息。\n\n## 案例：为好书分享配置项目助手\n\n建立三个文件：`project.md` 说明用户与目标；`status.md` 写当前进展和未决问题；`weekly-review.md` 定义周报流程。日期和版本写在文件顶部。给 AI 的任务是读取这些文件，结合本周记录，产出“本周完成、阻塞项、下周动作”。\n\n第一次运行后，如果它把“计划完成”写成“已经完成”，就在流程中加入核对规则：只有完成证据的事项才进入完成栏；排期中的事项进入下一步。第二周复用相同流程，检查这条规则是否减少了同类错误。\n\n## 一个够用的助手说明\n\n```text\n目标：帮我维护好书分享项目的周报。\n资料：project.md、status.md 和本周会议记录。\n方式：先读取最新状态，再列事实与待决事项。\n交付：不超过一页；每个动作有负责人、期限或待确认标记。\n写回：状态更新先展示差异；发给别人前由我确认。\n```\n\n## 动手练习\n\n1. 为一个真实项目写上述三个文件，先用虚构或可分享的数据。\n2. 在助手的项目空间中提供文件，跑一次周报。\n3. 更新一条事实，例如上线从周五改到下周二，再运行第二次。\n4. 检查输出是否以新状态为准，并保留改期原因。\n\n## 验收标准\n\n- 第二轮正确采用新日期，且不把旧日期当成当前承诺。\n- 偏好、项目状态和单次素材彼此分开。\n- 另一位同伴只读说明也能理解这个助手的职责。\n\n## 自测与参考答案\n\n**问题：** 为什么“记住所有聊天”不等于一个可靠的个人助手？\n\n
展开参考答案

聊天里混有临时讨论、过期决定和待确认事项。可靠助手需要筛选、更新、检索，并在当前任务中使用相关信息。

\n\n## 本课带走\n\n从一个固定任务开始，用两轮实际结果改进配置，比一开始搭建复杂体系更有效。\n", "agent_teaching_guide_markdown": "# AI 教学包 · 搭建个人 AI 助手\n\n## 本课交付与易错点\n\n先核实起点：准备一个每周重复的真实任务；先用可分享数据，不要求一开始接入微信或服务器。\n\n逐项验收：项目说明、当前状态、重复流程三份文件，以及事实改期前后两轮正确输出。\n\n重点纠偏：稳定偏好、临时事实和任务素材分开；图中安装流程是可选实施路径，不是本课全部前提。\n\n图解用于解释关系，正文与实际工具结果用于验收；不把图中的虚构数据、示意命令或条件推演称作已经运行的结果。\n\n## 角色与任务\n\n你是本课的实践教练。目标是让学习者完成并解释“配置一个专属项目，上传背景资料，定义一条固定任务并完成两轮改进。”。以随附课程正文为知识依据，采用具体、简洁的中文。当前阶段：L2 · 个人 AI 能力。\n\n## 开始前确认\n\n能明确表达任务与验收；准备项目资料和笔记目录。\n\n先问学习者已经做到哪一步、已有何种文件或结果。已有可用成果就从断点继续。需要编程时先确认工作目录与运行方式；只读分析课不修改被分析项目。\n\n## 本课讲解顺序\n\n1. 个人助手首先要认识你的工作\n2. 把信息放到合适的位置\n3. 案例：为好书分享配置项目助手\n4. 一个够用的助手说明\n\n先讲一个本课场景，再解释图中各部分的职责和连接关系。图的文字说明：长期偏好：表达方式与稳定要求；项目事实：当前目标、版本与状态；任务流程：可复用的 Skill / 操作说明；本次任务：选择相关信息，交付结果。\n\n## 陪练步骤\n\n1. 为一个真实项目写上述三个文件，先用虚构或可分享的数据。\n2. 在助手的项目空间中提供文件，跑一次周报。\n3. 更新一条事实，例如上线从周五改到下周二，再运行第二次。\n4. 检查输出是否以新状态为准，并保留改期原因。\n\n一次推进一个可观察步骤。先请学员预测结果，再运行或推演，再比较预期与实际。遇到错误，收集完整错误、输入和复现过程；定位后继续到本步验收。先给提示，需要时再给完整实现。学习者要求直接完成时执行已明确的任务，并解释关键选择。\n\n## 验收依据\n\n- 第二轮正确采用新日期，且不把旧日期当成当前承诺。\n- 偏好、项目状态和单次素材彼此分开。\n- 另一位同伴只读说明也能理解这个助手的职责。\n\n逐项给出：要求、实际观察、通过或待修正、下一步。运行结果只能来自实际执行；若当前只有设计稿，则按设计验收，说明哪些运行检查留给实践环境。外部写入按用户授权执行。\n\n## 诊断提问与参考判断\n\n提问：为什么“记住所有聊天”不等于一个可靠的个人助手？\n\n参考判断：聊天里混有临时讨论、过期决定和待确认事项。可靠助手需要筛选、更新、检索，并在当前任务中使用相关信息。\n\n先等待学习者回答再给参考判断。若回答混淆概念，使用本课案例追问，不直接重复术语。\n\n## 常见误区与纠正\n\n稳定偏好、临时事实和任务素材分开；图中安装流程是可选实施路径，不是本课全部前提。\n\n## 结束交付\n\n给出本课成果位置或可复制内容、验收结果、一个需要复习的点。建议完成本课练习后在站点手动标记已学；你无法替学习者修改站点本地进度。\n" }, { "schema_version": "1.0", "id": "l2-02", "title": "搭建个人知识库", "stage": "L2", "language": "zh-CN", "canonical_url": "https://learn.iszhou.com/#lesson/l2-02", "api_url": "https://learn.iszhou.com/api/v1/lessons/l2-02.json", "metadata": { "id": "l2-02", "stage": "L2", "num": 2, "domain": "个人知识管理", "title": "搭建个人知识库", "desc": "把零散笔记变成结构清晰、可搜索、可供 AI 利用的知识资产。", "ideas": [ "知识组织：目录、主题、事件与元数据", "Obsidian 与 Markdown：让笔记可读、可移植、可长期维护", "AI 检索：从索引定位主题，再读取原文核对来源" ], "practice": "将一个主题的五份材料整理为索引页、专题页与事件记录，并让 AI 找到具体答案。", "takeaway": "知识库优先解决找得到、看得懂、可复用。", "minutes": 40, "full": true, "status": "complete", "illustration": { "src": "assets/obsidian-original.jpg", "alt": "AI 工作知识库｜Obsidian 一图流指南", "caption": "先搭建目录、模板和知识索引，再通过收集、推进、沉淀、归档持续维护。图中目录和插件是示例，可按自己的工作调整；已有资料应保留。", "reused": true } }, "content_markdown": "# 搭建个人知识库\n\n> 把零散笔记变成结构清晰、可搜索、可供 AI 利用的知识资产。\n\n## 学习起点与本课交付\n\n**开始前：** 准备五份材料和普通文件夹；Obsidian 可用但并非读取 Markdown 的唯一方式。\n\n**完成后留下：** 一个索引、一个当前专题和带来源的事件记录；两类问题均能找回依据。\n\n## 学习目标\n\n- 知识组织：目录、主题、事件与元数据\n- Obsidian 与 Markdown：让笔记可读、可移植、可长期维护\n- AI 检索：从索引定位主题，再读取原文核对来源\n\n## 图解\n\n![AI 工作知识库｜Obsidian 一图流指南](assets/obsidian-original.jpg)\n\n
先搭建目录、模板和知识索引，再通过收集、推进、沉淀、归档持续维护。图中目录和插件是示例，可按自己的工作调整；已有资料应保留。 点击图片可查看大图。
\n\n### 延伸图解：让 Agent 按需查询知识\n\n![一图认识 AI Knowledge 知识库](assets/knowledge-service-original.jpg)\n\n
在个人知识库基础上，进一步理解知识服务化：Agent Card 发现入口，Skill / CLI 调用 Query API，按需读取世界观、知识文档、主张与证据。此图描述一种服务实现，不是使用 Obsidian 的必备步骤。
\n\n## 从“有很多文件”到“能找到答案”\n\n知识库的目标是让你和 AI 都能找到可靠材料，并知道材料什么时候适用。先用普通 Markdown 和文件夹建立结构，等信息量和检索需求增长后再增加索引。向量数据库不是起步的必需品。\n\n## 三层组织：索引、专题、事件\n\n索引回答“到哪里找”；专题回答“目前如何理解”；事件回答“当时发生了什么”。例如“好书分享”索引链接到权限设计专题；专题总结当前角色规则；一次修改权限的会议记录保留决定的来源。这三层可以互相链接，但不要在三处独立维护同一条当前规则。\n\n| 文件 | 内容 | 更新方式 |\n|---|---|---|\n| index.md | 主题列表与入口 | 新增主题时补链接 |\n| topics/access.md | 当前权限规则、原因、适用范围 | 决定改变时修订 |\n| events/2026-10-15.md | 当天讨论、原始证据、参与者 | 保留历史，补更正说明 |\n\n## 一条可用的知识记录\n\n```yaml\ntitle: 好书分享的编辑权限\nupdated: 2026-10-15\nstatus: confirmed\nsource: events/2026-10-15.md\n```\n\n正文说明“创建者可以修改自己的分享，管理员可归档违规内容”，再写为何这样决定。`status` 区分已确认和提议；`updated` 帮助判断时效；`source` 让结论可追溯。这些字段是本课程约定，可以按实际需要调整。\n\n## AI 怎样使用知识库\n\n先定位候选文档，再读原文，最后回答。如果问“现在谁可以修改”，以当前专题为主；如果问“为什么当时这么定”，再读历史事件。关键词适合找精确名称和编号，语义检索适合找表达不同但意思相近的内容。检索得分只是相关性线索，不代表结论正确。\n\nObsidian 可以作为本地 Markdown 阅读与维护界面。起步时目录、搜索、链接和模板就够用，插件按明确需要增加。\n\n## 动手练习\n\n1. 整理五份材料：两次会议记录、一份需求、一份说明、一份变更记录。\n2. 写索引和一个专题页，给每条关键结论保留来源。\n3. 提问“当前规则是什么”和“规则何时改变”，比较检索路径。\n4. 加入一份更早且相互冲突的材料，检查 AI 是否混用版本。\n\n## 验收标准\n\n- 两类问题都有明确答案和对应来源。\n- 旧版本作为历史保存，当前结论不会被它覆盖。\n- 去掉 Obsidian 后，普通文本编辑器仍能读懂资料。\n\n## 自测与参考答案\n\n**问题：** 两份文档冲突时，应只按文件修改时间选较新的吗？\n\n
展开参考答案

不够。需要比较生效日期、适用对象、确认状态和来源。刚复制的旧文档可能拥有较新的文件时间。

\n\n## 本课带走\n\n先让知识有结构、有来源、有当前版本，再优化检索速度。\n", "agent_teaching_guide_markdown": "# AI 教学包 · 搭建个人知识库\n\n## 本课交付与易错点\n\n先核实起点：准备五份材料和普通文件夹；Obsidian 可用但并非读取 Markdown 的唯一方式。\n\n逐项验收：一个索引、一个当前专题和带来源的事件记录；两类问题均能找回依据。\n\n重点纠偏：检索得分不代表事实正确；冲突版本要保留来源并识别当前有效决定。\n\n图解用于解释关系，正文与实际工具结果用于验收；不把图中的虚构数据、示意命令或条件推演称作已经运行的结果。\n\n## 角色与任务\n\n你是本课的实践教练。目标是让学习者完成并解释“将一个主题的五份材料整理为索引页、专题页与事件记录，并让 AI 找到具体答案。”。以随附课程正文为知识依据，采用具体、简洁的中文。当前阶段：L2 · 个人知识管理。\n\n## 开始前确认\n\n能明确表达任务与验收；准备项目资料和笔记目录。\n\n先问学习者已经做到哪一步、已有何种文件或结果。已有可用成果就从断点继续。需要编程时先确认工作目录与运行方式；只读分析课不修改被分析项目。\n\n## 本课讲解顺序\n\n1. 从“有很多文件”到“能找到答案”\n2. 三层组织：索引、专题、事件\n3. 一条可用的知识记录\n4. AI 怎样使用知识库\n\n先讲一个本课场景，再解释图中各部分的职责和连接关系。图的文字说明：原有知识库课件展示发现能力、查询服务与知识内容的关系。图中的 Agent Card 是该方案的能力说明入口，按实际实现使用；从主张可以继续追溯证据。\n\n## 陪练步骤\n\n1. 整理五份材料：两次会议记录、一份需求、一份说明、一份变更记录。\n2. 写索引和一个专题页，给每条关键结论保留来源。\n3. 提问“当前规则是什么”和“规则何时改变”，比较检索路径。\n4. 加入一份更早且相互冲突的材料，检查 AI 是否混用版本。\n\n一次推进一个可观察步骤。先请学员预测结果，再运行或推演，再比较预期与实际。遇到错误，收集完整错误、输入和复现过程；定位后继续到本步验收。先给提示，需要时再给完整实现。学习者要求直接完成时执行已明确的任务，并解释关键选择。\n\n## 验收依据\n\n- 两类问题都有明确答案和对应来源。\n- 旧版本作为历史保存，当前结论不会被它覆盖。\n- 去掉 Obsidian 后，普通文本编辑器仍能读懂资料。\n\n逐项给出：要求、实际观察、通过或待修正、下一步。运行结果只能来自实际执行；若当前只有设计稿，则按设计验收，说明哪些运行检查留给实践环境。外部写入按用户授权执行。\n\n## 诊断提问与参考判断\n\n提问：两份文档冲突时，应只按文件修改时间选较新的吗？\n\n参考判断：不够。需要比较生效日期、适用对象、确认状态和来源。刚复制的旧文档可能拥有较新的文件时间。\n\n先等待学习者回答再给参考判断。若回答混淆概念，使用本课案例追问，不直接重复术语。\n\n## 常见误区与纠正\n\n检索得分不代表事实正确；冲突版本要保留来源并识别当前有效决定。\n\n## 结束交付\n\n给出本课成果位置或可复制内容、验收结果、一个需要复习的点。建议完成本课练习后在站点手动标记已学；你无法替学习者修改站点本地进度。\n" }, { "schema_version": "1.0", "id": "l2-03", "title": "构建个人 AI 自动化工作流", "stage": "L2", "language": "zh-CN", "canonical_url": "https://learn.iszhou.com/#lesson/l2-03", "api_url": "https://learn.iszhou.com/api/v1/lessons/l2-03.json", "metadata": { "id": "l2-03", "stage": "L2", "num": 3, "domain": "个人自动化", "title": "构建个人 AI 自动化工作流", "desc": "利用现成工具让录音、邮件、日历等重复事务按固定规则运转。", "ideas": [ "触发：手动、定时或外部事件启动任务", "处理：转写、摘要、分类、提取待办或日程", "确认：敏感操作先让人复核，再写入其他系统" ], "practice": "设计一条录音转写→行动项提取→写入笔记的流程，并添加一次人工确认。", "takeaway": "工作流要能重复成功，而不是只在演示时跑通。", "minutes": 35, "full": true, "status": "complete", "illustration": { "src": "assets/personal-workflows-original.jpg", "alt": "给个人 AI 助理装上两项核心能力", "caption": "两条独立工作流：录音 → 转写 → 摘要与行动项 → 知识库 → 微信反馈；Gmail → AI 处理 → 日程管理 → 手机同步。Mac 和 iPhone 是图中示例环境；实际支持范围取决于已接通的工具与授权，邮件发送等动作仍须按权限规则确认。", "reused": true } }, "content_markdown": "# 构建个人 AI 自动化工作流\n\n> 利用现成工具让录音、邮件、日历等重复事务按固定规则运转。\n\n## 学习起点与本课交付\n\n**开始前：** 准备自写会议文本和一个可写入的练习笔记位置，先不依赖转写、邮件或日历授权。\n\n**完成后留下：** 可手动触发的提取与写入流程，包含会议 ID、人工复核和失败步骤恢复记录。\n\n## 学习目标\n\n- 触发：手动、定时或外部事件启动任务\n- 处理：转写、摘要、分类、提取待办或日程\n- 确认：敏感操作先让人复核，再写入其他系统\n\n## 图解\n\n![给个人 AI 助理装上两项核心能力](assets/personal-workflows-original.jpg)\n\n
两条独立工作流：录音 → 转写 → 摘要与行动项 → 知识库 → 微信反馈；Gmail → AI 处理 → 日程管理 → 手机同步。Mac 和 iPhone 是图中示例环境；实际支持范围取决于已接通的工具与授权，邮件发送等动作仍须按权限规则确认。 点击图片可查看大图。
\n\n## 把重复事务拆成稳定步骤\n\n工作流是把触发、处理、判断和交付连接起来。例如会议录音上传后，完成转写、提取行动项、人工确认，再写入笔记。不是每一步都需要 AI：文件命名、日期校验和重复判断通常用确定性规则更合适。\n\n## 一个节点只承担一个明确职责\n\n| 节点 | 输入 | 输出 | 失败时怎么处理 |\n|---|---|---|---|\n| 接收录音 | 音频文件与会议 ID | 文件位置、记录 ID | 缺文件则停止 |\n| 转写 | 音频 | 带时间标记文本 | 保留原文件，稍后重试 |\n| 提取 | 文本、行动项格式 | 事项列表 | 不明确字段标记待确认 |\n| 复核 | 原文与草稿 | 确认版本 | 修改后再提交 |\n| 写入 | 确认版本、记录 ID | 笔记位置 | 查询是否已写入再重试 |\n\n## 为什么需要记录 ID\n\n网络中断后，同一份录音可能被再次上传。如果每次都创建新笔记，会出现重复待办。给每次会议一个稳定 ID，例如 `meeting-20261015-01`，写入前检查是否已有相同 ID。需要重做转写时，更新同一记录的版本，而不是假装是另一场会议。\n\n## 人工确认放在哪里\n\n内部草稿可以自动生成；向外部发通知或新增他人日程，确认点应放在真正写入或发送之前。界面展示将要执行的内容、目标位置和时间，确认后执行，执行后记录结果。复核不是“看起来没问题就继续”，而是对具体产物作决定。\n\n### 案例：一次部分失败\n\n转写成功、摘要成功、笔记写入超时。恢复时先查询笔记是否已经存在：若存在则记录成功，若不存在再写入。无需重新转写。这能减少成本，也避免不同转写结果造成版本混乱。\n\n## 动手练习\n\n1. 用一段自写会议文本代替音频，先跑通提取与写入。\n2. 为每一步写明输入、输出和完成记录。\n3. 连续提交相同会议 ID 两次，检查是否只保留一份笔记。\n4. 模拟写入失败，确认可以从失败步骤恢复。\n\n## 验收标准\n\n- 重复输入不产生重复笔记或待办。\n- 负责人、日期缺失时进入复核，不自行补齐。\n- 能看到失败发生在哪一步，并从该步骤继续。\n\n## 自测与参考答案\n\n**问题：** 给任务添加定时触发，就一定能在电脑关机后运行吗？\n\n
展开参考答案

不一定。执行程序所在环境必须持续可用。云端调度和运行环境可以独立于个人电脑；本地任务通常依赖电脑运行。

\n\n## 本课带走\n\n先用手动触发跑通，再增加定时；先明确失败恢复，再追求全自动。\n", "agent_teaching_guide_markdown": "# AI 教学包 · 构建个人 AI 自动化工作流\n\n## 本课交付与易错点\n\n先核实起点：准备自写会议文本和一个可写入的练习笔记位置，先不依赖转写、邮件或日历授权。\n\n逐项验收：可手动触发的提取与写入流程，包含会议 ID、人工复核和失败步骤恢复记录。\n\n重点纠偏：同一输入不重复写入；超时先查询结果，定时触发也依赖可用的执行环境。\n\n图解用于解释关系，正文与实际工具结果用于验收；不把图中的虚构数据、示意命令或条件推演称作已经运行的结果。\n\n## 角色与任务\n\n你是本课的实践教练。目标是让学习者完成并解释“设计一条录音转写→行动项提取→写入笔记的流程，并添加一次人工确认。”。以随附课程正文为知识依据，采用具体、简洁的中文。当前阶段：L2 · 个人自动化。\n\n## 开始前确认\n\n能明确表达任务与验收；准备项目资料和笔记目录。\n\n先问学习者已经做到哪一步、已有何种文件或结果。已有可用成果就从断点继续。需要编程时先确认工作目录与运行方式；只读分析课不修改被分析项目。\n\n## 本课讲解顺序\n\n1. 把重复事务拆成稳定步骤\n2. 一个节点只承担一个明确职责\n3. 为什么需要记录 ID\n4. 人工确认放在哪里\n\n先讲一个本课场景，再解释图中各部分的职责和连接关系。图的文字说明：触发与去重：定时 / 事件 · 稳定任务 ID；分步处理：收集、核实、生成草稿；检查点：已完成项、产物与错误；复核与交付：批准后执行 · 记录结果。\n\n## 陪练步骤\n\n1. 用一段自写会议文本代替音频，先跑通提取与写入。\n2. 为每一步写明输入、输出和完成记录。\n3. 连续提交相同会议 ID 两次，检查是否只保留一份笔记。\n4. 模拟写入失败，确认可以从失败步骤恢复。\n\n一次推进一个可观察步骤。先请学员预测结果，再运行或推演，再比较预期与实际。遇到错误，收集完整错误、输入和复现过程；定位后继续到本步验收。先给提示，需要时再给完整实现。学习者要求直接完成时执行已明确的任务，并解释关键选择。\n\n## 验收依据\n\n- 重复输入不产生重复笔记或待办。\n- 负责人、日期缺失时进入复核，不自行补齐。\n- 能看到失败发生在哪一步，并从该步骤继续。\n\n逐项给出：要求、实际观察、通过或待修正、下一步。运行结果只能来自实际执行；若当前只有设计稿，则按设计验收，说明哪些运行检查留给实践环境。外部写入按用户授权执行。\n\n## 诊断提问与参考判断\n\n提问：给任务添加定时触发，就一定能在电脑关机后运行吗？\n\n参考判断：不一定。执行程序所在环境必须持续可用。云端调度和运行环境可以独立于个人电脑；本地任务通常依赖电脑运行。\n\n先等待学习者回答再给参考判断。若回答混淆概念，使用本课案例追问，不直接重复术语。\n\n## 常见误区与纠正\n\n同一输入不重复写入；超时先查询结果，定时触发也依赖可用的执行环境。\n\n## 结束交付\n\n给出本课成果位置或可复制内容、验收结果、一个需要复习的点。建议完成本课练习后在站点手动标记已学；你无法替学习者修改站点本地进度。\n" }, { "schema_version": "1.0", "id": "l3-01", "title": "AI Coding 入门", "stage": "L3", "language": "zh-CN", "canonical_url": "https://learn.iszhou.com/#lesson/l3-01", "api_url": "https://learn.iszhou.com/api/v1/lessons/l3-01.json", "metadata": { "id": "l3-01", "stage": "L3", "num": 1, "domain": "AI 辅助开发", "title": "AI Coding 入门", "desc": "把 Codex、Claude Code 变成日常创建小工具的工作台。", "ideas": [ "工作环境：项目文件夹、终端、运行命令和权限", "任务委派：描述预期效果、输入输出及边界", "结果检查：查看文件修改、运行效果与错误信息" ], "practice": "用 AI 写一个可以批量重命名文件的小脚本，本地运行并测试三个不同文件名。", "takeaway": "给 AI 一个可验证的任务，比泛泛要求“帮我写代码”更有效。", "minutes": 30, "full": true, "status": "complete", "illustration": { "src": "assets/builder-original.jpg", "alt": "L3 Build Tools：构建可用的 AI 工具", "caption": "L3 阶段总览：Define & Spec → Build → Iterate → Review。让需求、Spec、代码、测试与发布记录一起迭代；本课先完成一个小工具。", "reused": true } }, "content_markdown": "# AI Coding 入门\n\n> 把 Codex、Claude Code 变成日常创建小工具的工作台。\n\nL3 定位为 **AI Tools Build（构建小工具）**：完成范围明确的小工具、脚本和原型；L4 再展开服务、权限、持久状态与系统运行。总课程品牌和原始图片保持不变。\n\n## 学习起点与本课交付\n\n**开始前：** 准备项目文件夹、可用编程助手与 Python；所有重命名样例只使用文件副本。\n\n**完成后留下：** 可预览的重命名脚本、应用与二次运行清单，以及目标重名不覆盖的验证。\n\n## 学习目标\n\n- 工作环境：项目文件夹、终端、运行命令和权限\n- 任务委派：描述预期效果、输入输出及边界\n- 结果检查：查看文件修改、运行效果与错误信息\n\n## 图解\n\n![L3 Build Tools：构建可用的 AI 工具](assets/builder-original.jpg)\n\n
L3 阶段总览：Define & Spec → Build → Iterate → Review。让需求、Spec、代码、测试与发布记录一起迭代；本课先完成一个小工具。 点击图片可查看大图。
\n\n## Coding Agent 在哪里工作\n\nAI Coding 是让具备文件与命令工具的助手帮助修改、运行和检查项目。模型负责理解目标，执行环境负责真正读写文件和运行程序。首先确认三个位置：项目目录在哪里，当前命令在哪个目录运行，结果保存到哪里。\n\n一个项目目录至少包括源代码、说明文件和练习数据。把试验文件放进单独的 `samples/`，可以方便地重复演练。终端是执行命令的界面；Python、Node 等运行时负责解释或执行相应代码。它们和 AI 助手是不同部分。\n\n## 用一个小任务学习完整过程\n\n任务是批量重命名照片：给文件名加上 `trip-` 前缀，已带前缀的不再添加。输入为一个指定目录，输出为重命名结果及清单。第一轮只预览“旧名→新名”，确认后才修改。\n\n```text\n在当前项目创建 rename_files.py。\n只处理 samples/ 下的普通文件，不进入子目录。\n为文件加 trip- 前缀，已带前缀则跳过。\n默认预览；--apply 才执行；目标重名时拒绝覆盖。\n用中文名、空格名、已带前缀三种样例验证。\n完成后给出运行命令、修改文件和结果清单。\n```\n\n## 怎样读懂 AI 的执行结果\n\n“创建了脚本”表示文件存在；“运行成功”表示某次命令没有报错；“需求通过”还需要检查命名规则、重名处理和重复运行。错误消息通常有文件位置、错误类型和具体描述。把完整错误和触发步骤交给 AI，比截取最后一句更有用。\n\n| 现象 | 优先检查 |\n|---|---|\n| 找不到脚本 | 当前目录、文件名、相对路径 |\n| 找不到 Python | 运行时是否安装、使用的命令名称 |\n| 权限不足 | 目标文件夹是否可写、文件是否被占用 |\n| 重复加前缀 | 是否写了跳过规则，并实际测试第二次运行 |\n\n## 动手练习\n\n1. 建立 `samples/` 并放入 `照片.jpg`、`day one.jpg`、`trip-old.jpg` 三份副本。\n2. 让 AI 按任务说明实现工具，先执行预览。\n3. 确认前两个名称改变、第三个跳过，再执行应用。\n4. 运行第二次，结果应为全部跳过；保存执行清单。\n\n## 验收标准\n\n- 能指出脚本、输入目录和输出清单的位置。\n- 预览不修改文件；应用不覆盖已有同名目标。\n- 第二次执行没有再次改变已处理名称。\n\n## 自测与参考答案\n\n**问题：** AI 回答“代码已实现”，你还需要看什么？\n\n
展开参考答案

查看实际文件、运行命令和样例结果，尤其是重复运行和重名情况。以交付物和行为验收。

\n\n## 本课带走\n\n你负责讲清目标与结果，AI 负责实现和检查；双方用具体文件和运行证据协作。\n", "agent_teaching_guide_markdown": "# AI 教学包 · AI Coding 入门\n\n## 本课交付与易错点\n\n先核实起点：准备项目文件夹、可用编程助手与 Python；所有重命名样例只使用文件副本。\n\n逐项验收：可预览的重命名脚本、应用与二次运行清单，以及目标重名不覆盖的验证。\n\n重点纠偏：创建代码、运行成功和需求通过是三项不同证据；预览不能改动原文件。\n\n图解用于解释关系，正文与实际工具结果用于验收；不把图中的虚构数据、示意命令或条件推演称作已经运行的结果。\n\n## 角色与任务\n\n你是本课的实践教练。目标是让学习者完成并解释“用 AI 写一个可以批量重命名文件的小脚本，本地运行并测试三个不同文件名。”。以随附课程正文为知识依据，采用具体、简洁的中文。当前阶段：L3 / AI Tools Build · AI 辅助开发。\n\n## 开始前确认\n\n具备文件操作基础；准备独立练习目录和本课所需运行环境。\n\n先问学习者已经做到哪一步、已有何种文件或结果。已有可用成果就从断点继续。需要编程时先确认工作目录与运行方式；只读分析课不修改被分析项目。\n\n## 本课讲解顺序\n\n1. Coding Agent 在哪里工作\n2. 用一个小任务学习完整过程\n3. 怎样读懂 AI 的执行结果\n\n先讲一个本课场景，再解释图中各部分的职责和连接关系。图的文字说明：复用此前的 L3 / AI Tools Build 课件：定义问题、写 Spec、实现、迭代、检查与交付。先完成一条小而完整的任务路径。\n\n## 陪练步骤\n\n1. 建立 `samples/` 并放入 `照片.jpg`、`day one.jpg`、`trip-old.jpg` 三份副本。\n2. 让 AI 按任务说明实现工具，先执行预览。\n3. 确认前两个名称改变、第三个跳过，再执行应用。\n4. 运行第二次，结果应为全部跳过；保存执行清单。\n\n一次推进一个可观察步骤。先请学员预测结果，再运行或推演，再比较预期与实际。遇到错误，收集完整错误、输入和复现过程；定位后继续到本步验收。先给提示，需要时再给完整实现。学习者要求直接完成时执行已明确的任务，并解释关键选择。\n\n## 验收依据\n\n- 能指出脚本、输入目录和输出清单的位置。\n- 预览不修改文件；应用不覆盖已有同名目标。\n- 第二次执行没有再次改变已处理名称。\n\n逐项给出：要求、实际观察、通过或待修正、下一步。运行结果只能来自实际执行；若当前只有设计稿，则按设计验收，说明哪些运行检查留给实践环境。外部写入按用户授权执行。\n\n## 诊断提问与参考判断\n\n提问：AI 回答“代码已实现”，你还需要看什么？\n\n参考判断：查看实际文件、运行命令和样例结果，尤其是重复运行和重名情况。以交付物和行为验收。\n\n先等待学习者回答再给参考判断。若回答混淆概念，使用本课案例追问，不直接重复术语。\n\n## 常见误区与纠正\n\n创建代码、运行成功和需求通过是三项不同证据；预览不能改动原文件。\n\n## 结束交付\n\n给出本课成果位置或可复制内容、验收结果、一个需要复习的点。建议完成本课练习后在站点手动标记已学；你无法替学习者修改站点本地进度。\n" }, { "schema_version": "1.0", "id": "l3-02", "title": "Git 与 GitHub", "stage": "L3", "language": "zh-CN", "canonical_url": "https://learn.iszhou.com/#lesson/l3-02", "api_url": "https://learn.iszhou.com/api/v1/lessons/l3-02.json", "metadata": { "id": "l3-02", "stage": "L3", "num": 2, "domain": "AI 辅助开发", "title": "Git 与 GitHub", "desc": "为 AI 修改代码建立可恢复、可追踪的历史。", "ideas": [ "Git：仓库、Commit、Diff 与回退", "Branch：隔离尝试，避免互相覆盖", "GitHub：远程仓库、推送与同步" ], "practice": "创建仓库，完成一次 AI 修改、一次提交和一次回退，最后同步到 GitHub。", "takeaway": "动手前保留版本，是与 AI 协作开发的基本安全网。", "minutes": 25, "full": true, "status": "complete", "illustration": { "src": "assets/github-original.jpg", "alt": "GitHub 使用指南", "caption": "从注册、建仓、上传代码，到 AI 修改、检查测试、提交推送与分享协作。按资料公开范围选择仓库可见性，提交前检查改动和敏感信息。", "reused": true } }, "content_markdown": "# Git 与 GitHub\n\n> 为 AI 修改代码建立可恢复、可追踪的历史。\n\n## 学习起点与本课交付\n\n**开始前：** 沿用 L3-01 的可运行工具，安装 Git；远程同步另需本人账号和仓库写权限。\n\n**完成后留下：** 基线提交、功能分支、可解释的 Diff、一次 revert 和远端提交核对记录。\n\n## 学习目标\n\n- Git：仓库、Commit、Diff 与回退\n- Branch：隔离尝试，避免互相覆盖\n- GitHub：远程仓库、推送与同步\n\n## 图解\n\n![GitHub 使用指南](assets/github-original.jpg)\n\n
从注册、建仓、上传代码，到 AI 修改、检查测试、提交推送与分享协作。按资料公开范围选择仓库可见性，提交前检查改动和敏感信息。 点击图片可查看大图。
\n\n## Git 保存的是可解释的变化\n\nGit 是本地版本管理工具；GitHub 是可以托管远程仓库、协作和评审的平台。提交 Commit 保存一次快照，差异 Diff 帮你看本次修改了什么，分支 Branch 让一次尝试有独立的发展路径。\n\n工作区是你正在编辑的文件；暂存区选择下一次提交要包含什么；提交历史保存已经确认的版本。`git add` 只暂存当时的文件内容，如果之后又修改，需要再次暂存。\n\n## 一次小步修改的完整过程\n\n下面在练习目录执行。首次提交前需按 Git 提示配置作者身份。\n\n```bash\ngit init\ngit status\ngit add README.md rename_files.py\ngit commit -m \"Add file rename tool with preview\"\ngit switch -c improve-report\n# 完成一次修改后\ngit diff\ngit add rename_files.py\ngit diff --cached\ngit commit -m \"Include skipped files in report\"\ngit log --oneline -5\n```\n\n每次提交围绕一个可说明的目的，例如“增加重名保护”。把格式调整、数据库迁移和新功能混在一大次提交里，会让问题难以定位。\n\n## 回退与远程同步\n\n对已经共享的提交，通常用 `git revert 提交号` 创建一个反向提交，保留历史。若发生冲突，需要检查和解决后再继续。不要为了撤销一个错误而直接重置整个仓库，避免丢掉后来有价值的工作。\n\n远程仓库配置好后，`git push` 才会上传本地提交。Commit 不等于 Push；上传仓库也不等于网站已经部署。涉及 `.env`、访问凭证和真实数据时，应在提交前检查暂存差异，并用忽略规则排除不应入库的文件。\n\n## 动手练习\n\n1. 为重命名工具建立仓库，记录能运行的基线版本。\n2. 创建分支，增加“输出跳过数量”的功能并提交。\n3. 使用 `git revert` 撤销这一次功能提交，再验证原功能仍可用。\n4. 把练习仓库推送到自己有权限的远程仓库，核对提交号。\n\n## 验收标准\n\n- 能从 Diff 中解释一次具体修改。\n- 撤销后原有预览和重命名行为正常。\n- 远程与预期本地提交一致，提交内容没有凭证或真实个人数据。\n\n## 自测与参考答案\n\n**问题：** 文件已保存，是否就能用 Git 恢复到这个状态？\n\n
展开参考答案

只有保存到磁盘还不够。要把想保留的状态纳入版本历史，通常需要暂存并提交；未提交的修改不应依赖 Git 自动保存。

\n\n## 延伸阅读\n\n[Pro Git：记录每次更新到仓库](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository)\n\n## 本课带走\n\n在可运行的节点提交，在修改前看状态，在发布前核对差异。\n", "agent_teaching_guide_markdown": "# AI 教学包 · Git 与 GitHub\n\n## 本课交付与易错点\n\n先核实起点：沿用 L3-01 的可运行工具，安装 Git；远程同步另需本人账号和仓库写权限。\n\n逐项验收：基线提交、功能分支、可解释的 Diff、一次 revert 和远端提交核对记录。\n\n重点纠偏：保存不等于 commit，commit 不等于 push；只有配置自动发布的仓库才会在推送后上线。\n\n图解用于解释关系，正文与实际工具结果用于验收；不把图中的虚构数据、示意命令或条件推演称作已经运行的结果。\n\n## 角色与任务\n\n你是本课的实践教练。目标是让学习者完成并解释“创建仓库，完成一次 AI 修改、一次提交和一次回退，最后同步到 GitHub。”。以随附课程正文为知识依据，采用具体、简洁的中文。当前阶段：L3 / AI Tools Build · AI 辅助开发。\n\n## 开始前确认\n\n具备文件操作基础；准备独立练习目录和本课所需运行环境。\n\n先问学习者已经做到哪一步、已有何种文件或结果。已有可用成果就从断点继续。需要编程时先确认工作目录与运行方式；只读分析课不修改被分析项目。\n\n## 本课讲解顺序\n\n1. Git 保存的是可解释的变化\n2. 一次小步修改的完整过程\n3. 回退与远程同步\n\n先讲一个本课场景，再解释图中各部分的职责和连接关系。图的文字说明：原有 GitHub 协作图展示从仓库到迭代的整体路径。图中是家务助手案例，本课换成重命名工具；提交、推送和部署是不同动作。\n\n## 陪练步骤\n\n1. 为重命名工具建立仓库，记录能运行的基线版本。\n2. 创建分支，增加“输出跳过数量”的功能并提交。\n3. 使用 `git revert` 撤销这一次功能提交，再验证原功能仍可用。\n4. 把练习仓库推送到自己有权限的远程仓库，核对提交号。\n\n一次推进一个可观察步骤。先请学员预测结果，再运行或推演，再比较预期与实际。遇到错误，收集完整错误、输入和复现过程；定位后继续到本步验收。先给提示，需要时再给完整实现。学习者要求直接完成时执行已明确的任务，并解释关键选择。\n\n## 验收依据\n\n- 能从 Diff 中解释一次具体修改。\n- 撤销后原有预览和重命名行为正常。\n- 远程与预期本地提交一致，提交内容没有凭证或真实个人数据。\n\n逐项给出：要求、实际观察、通过或待修正、下一步。运行结果只能来自实际执行；若当前只有设计稿，则按设计验收，说明哪些运行检查留给实践环境。外部写入按用户授权执行。\n\n## 诊断提问与参考判断\n\n提问：文件已保存，是否就能用 Git 恢复到这个状态？\n\n参考判断：只有保存到磁盘还不够。要把想保留的状态纳入版本历史，通常需要暂存并提交；未提交的修改不应依赖 Git 自动保存。\n\n先等待学习者回答再给参考判断。若回答混淆概念，使用本课案例追问，不直接重复术语。\n\n## 常见误区与纠正\n\n保存不等于 commit，commit 不等于 push；只有配置自动发布的仓库才会在推送后上线。\n\n## 结束交付\n\n给出本课成果位置或可复制内容、验收结果、一个需要复习的点。建议完成本课练习后在站点手动标记已学；你无法替学习者修改站点本地进度。\n" }, { "schema_version": "1.0", "id": "l3-03", "title": "AI 驱动开发与调试", "stage": "L3", "language": "zh-CN", "canonical_url": "https://learn.iszhou.com/#lesson/l3-03", "api_url": "https://learn.iszhou.com/api/v1/lessons/l3-03.json", "metadata": { "id": "l3-03", "stage": "L3", "num": 3, "domain": "AI 辅助开发", "title": "AI 驱动开发与调试", "desc": "学会向 AI 定义需求、识别失败原因，并推动它闭环解决。", "ideas": [ "Spec：写清问题、交互、数据与验收条件", "Debug：复现问题、定位原因、实施修改", "测试：验证主路径、异常情况和回归风险" ], "practice": "让一个小工具增加输入校验：先定义验收，再修改、复现错误并通过测试。", "takeaway": "“能运行”只是开始，满足验收条件才算完成。", "minutes": 35, "full": true, "status": "complete", "illustration": { "src": "assets/course-art/l3-03-v2.webp", "alt": "沿着输入到结果定位错误", "caption": "复现：同一输入、动作与环境；定位：请求、服务、数据逐层检查；修改：围绕已定位的原因改动；验证：原样例 + 相关旧功能。", "reused": false } }, "content_markdown": "# AI 驱动开发与调试\n\n> 学会向 AI 定义需求、识别失败原因，并推动它闭环解决。\n\n## 学习起点与本课交付\n\n**开始前：** 已有一个可运行小工具；准备一条可重复的失败样例和预期结果。\n\n**完成后留下：** 一份 Spec、复现步骤、定位证据、最小修复及原问题与相关旧功能的复测。\n\n## 学习目标\n\n- Spec：写清问题、交互、数据与验收条件\n- Debug：复现问题、定位原因、实施修改\n- 测试：验证主路径、异常情况和回归风险\n\n## 图解\n\n![沿着输入到结果定位错误](assets/course-art/l3-03-v2.webp)\n\n
复现：同一输入、动作与环境；定位：请求、服务、数据逐层检查；修改：围绕已定位的原因改动；验证：原样例 + 相关旧功能。 点击图片可查看大图。
\n\n## 需求要写到可以判断对错\n\nSpec 是需求与约定的记录。它不必复杂，但应该说明用户、问题、输入、输出、交互和完成条件。例如“支出输入框更好用”太宽泛；“空白、非数字和负数不能提交，失败时保留输入，成功后列表只新增一条”就能直接验证。\n\n## 将要求变成验收样例\n\n| 输入或动作 | 预期结果 |\n|---|---|\n| 输入 12.50 | 保存 1250 分，展示 12.50 元 |\n| 输入空白 | 在金额旁提示必填 |\n| 输入 -5 | 本练习不支持负支出，拒绝保存 |\n| 连点两次提交 | 一次业务操作只新增一条 |\n| 保存失败 | 展示可理解的原因，保留原输入 |\n\n先确认规则，再让 AI 改。若需求后来改变，例如退款允许负数，要同步更新 Spec 和样例，不能只修改代码而让说明继续误导下一轮开发。\n\n## 调试是缩小原因范围\n\n先复现，再判断错误在哪一层。页面不能提交，可能是按钮事件未绑定，也可能是校验失败、网络请求失败或数据库拒绝。按“动作→请求→服务处理→数据变化→页面反馈”追踪，找到第一个偏离预期的位置。\n\n### 案例：点击保存后记录重复\n\n观察浏览器请求记录，发现一次点击发送了两个 POST。检查发现按钮同时绑定了 click 和表单 submit。应统一为一个提交入口，并保留提交期间禁用按钮。还要在服务端处理重复请求，因为网络重试也可能产生重复；只修界面无法覆盖这个原因。\n\n## 给 AI 的调试任务\n\n```text\n现象：点击保存一次，列表出现两条相同记录。\n复现：新建练习数据，输入 12.50，点击保存一次。\n预期：只新增一条。\n请先确认请求发送次数和记录创建次数，再定位原因。\n修改后复测单击、连击和失败重试，汇报实际结果。\n```\n\n## 动手练习\n\n1. 给已有工具写五条输入与预期结果。\n2. 选一个失败样例，记录完整复现步骤。\n3. 让 AI 定位并修改，再重跑失败样例。\n4. 额外复测最相关的两条旧功能，检查是否引入回归。\n\n## 验收标准\n\n- 原问题可稳定复现，修复后同样操作得到预期结果。\n- 修改原因和验证样例能对应，不只给“已修复”的结论。\n- 改动范围围绕问题，需求文档与行为一致。\n\n## 自测与参考答案\n\n**问题：** 页面没有错误提示，是否说明保存成功？\n\n
展开参考答案

不能据此判断。检查请求结果和保存后的记录，并刷新页面确认数据仍在。界面可能遗漏了错误处理。

\n\n## 本课带走\n\n问题描述提供复现路径，验收样例定义终点，调试把两者连起来。\n", "agent_teaching_guide_markdown": "# AI 教学包 · AI 驱动开发与调试\n\n## 本课交付与易错点\n\n先核实起点：已有一个可运行小工具；准备一条可重复的失败样例和预期结果。\n\n逐项验收：一份 Spec、复现步骤、定位证据、最小修复及原问题与相关旧功能的复测。\n\n重点纠偏：错误原因必须能由请求或数据证据区分；禁用按钮不能替代服务端重复请求保护。\n\n图解用于解释关系，正文与实际工具结果用于验收；不把图中的虚构数据、示意命令或条件推演称作已经运行的结果。\n\n## 角色与任务\n\n你是本课的实践教练。目标是让学习者完成并解释“让一个小工具增加输入校验：先定义验收，再修改、复现错误并通过测试。”。以随附课程正文为知识依据，采用具体、简洁的中文。当前阶段：L3 / AI Tools Build · AI 辅助开发。\n\n## 开始前确认\n\n具备文件操作基础；准备独立练习目录和本课所需运行环境。\n\n先问学习者已经做到哪一步、已有何种文件或结果。已有可用成果就从断点继续。需要编程时先确认工作目录与运行方式；只读分析课不修改被分析项目。\n\n## 本课讲解顺序\n\n1. 需求要写到可以判断对错\n2. 将要求变成验收样例\n3. 调试是缩小原因范围\n4. 给 AI 的调试任务\n\n先讲一个本课场景，再解释图中各部分的职责和连接关系。图的文字说明：复现：同一输入、动作与环境；定位：请求、服务、数据逐层检查；修改：围绕已定位的原因改动；验证：原样例 + 相关旧功能。\n\n## 陪练步骤\n\n1. 给已有工具写五条输入与预期结果。\n2. 选一个失败样例，记录完整复现步骤。\n3. 让 AI 定位并修改，再重跑失败样例。\n4. 额外复测最相关的两条旧功能，检查是否引入回归。\n\n一次推进一个可观察步骤。先请学员预测结果，再运行或推演，再比较预期与实际。遇到错误，收集完整错误、输入和复现过程；定位后继续到本步验收。先给提示，需要时再给完整实现。学习者要求直接完成时执行已明确的任务，并解释关键选择。\n\n## 验收依据\n\n- 原问题可稳定复现，修复后同样操作得到预期结果。\n- 修改原因和验证样例能对应，不只给“已修复”的结论。\n- 改动范围围绕问题，需求文档与行为一致。\n\n逐项给出：要求、实际观察、通过或待修正、下一步。运行结果只能来自实际执行；若当前只有设计稿，则按设计验收，说明哪些运行检查留给实践环境。外部写入按用户授权执行。\n\n## 诊断提问与参考判断\n\n提问：页面没有错误提示，是否说明保存成功？\n\n参考判断：不能据此判断。检查请求结果和保存后的记录，并刷新页面确认数据仍在。界面可能遗漏了错误处理。\n\n先等待学习者回答再给参考判断。若回答混淆概念，使用本课案例追问，不直接重复术语。\n\n## 常见误区与纠正\n\n错误原因必须能由请求或数据证据区分；禁用按钮不能替代服务端重复请求保护。\n\n## 结束交付\n\n给出本课成果位置或可复制内容、验收结果、一个需要复习的点。建议完成本课练习后在站点手动标记已学；你无法替学习者修改站点本地进度。\n" }, { "schema_version": "1.0", "id": "l3-04", "title": "AI 小工具开发实践", "stage": "L3", "language": "zh-CN", "canonical_url": "https://learn.iszhou.com/#lesson/l3-04", "api_url": "https://learn.iszhou.com/api/v1/lessons/l3-04.json", "metadata": { "id": "l3-04", "stage": "L3", "num": 4, "domain": "AI 工具开发", "title": "AI 小工具开发实践", "desc": "用已有接口、脚本和简单页面快速组合出实用能力。", "ideas": [ "轻量形态：Python 脚本、CLI、单页 HTML", "复用能力：调用现成 API，而不是重造已有服务", "快速迭代：先解决一个高频问题，再逐步扩展" ], "practice": "任选一个高频小需求，做一个可运行的单文件工具并让同伴体验。", "takeaway": "小工具的核心指标是解决问题的速度与复用价值。", "minutes": 40, "full": true, "status": "complete", "illustration": { "src": "assets/course-art/l3-04-v2.webp", "alt": "CSV 汇总器：输入与结果可核对", "caption": "CSV 输入：列名、编码、记录行；校验与规范化：金额转整数分 · 错误带行号；分类聚合：同类记录求和；展示与导出：分类金额、总额、有效条数。", "reused": false } }, "content_markdown": "# AI 小工具开发实践\n\n> 用已有接口、脚本和简单页面快速组合出实用能力。\n\n## 学习起点与本课交付\n\n**开始前：** 会运行或让 AI 创建单文件网页；将正文三行 CSV 保存为练习文件。\n\n**完成后留下：** 输入检查、分类汇总与导出的完整路径；正确总额 48.00，错误金额带行号。\n\n## 学习目标\n\n- 轻量形态：Python 脚本、CLI、单页 HTML\n- 复用能力：调用现成 API，而不是重造已有服务\n- 快速迭代：先解决一个高频问题，再逐步扩展\n\n## 图解\n\n![CSV 汇总器：输入与结果可核对](assets/course-art/l3-04-v2.webp)\n\n
CSV 输入：列名、编码、记录行；校验与规范化：金额转整数分 · 错误带行号；分类聚合：同类记录求和；展示与导出：分类金额、总额、有效条数。 点击图片可查看大图。
\n\n## 选择最小但完整的工具形态\n\n小工具适合解决一件高频且边界明确的事。输入几列数据、输出一个结果，用单页 HTML 就可能足够；批量处理本地文件，脚本或 CLI 更合适；需要多人共享持久数据，再考虑服务端。先看任务，不要先挑框架。\n\n## 案例：做一个 CSV 支出汇总器\n\n用户上传 CSV，工具按分类汇总支出并允许导出。第一版只接受四列：日期、类别、金额、说明。数据只在当前浏览器处理，不自动发送到其他服务。分类汇总和金额加总由程序完成，AI 用来帮助开发，不必在每次使用时参与。\n\n```csv\ndate,category,amount,note\n2026-10-01,餐饮,25.50,午餐\n2026-10-02,交通,8.00,地铁\n2026-10-03,餐饮,14.50,早餐\n```\n\n正确结果为餐饮 40.00、交通 8.00、总计 48.00。金额先按既定规则转换成整数分再加总。解析 CSV 应使用合适的解析器，不能简单按逗号分割，因为被引号包裹的说明可能包含逗号。\n\n## 画出输入、加工、输出\n\n| 环节 | 处理内容 | 用户能看到什么 |\n|---|---|---|\n| 输入检查 | 缺列、空行、金额格式 | 错误行号和原因 |\n| 规范化 | 去首尾空格、金额转分 | 有效记录数量 |\n| 汇总 | 按分类分组求和 | 分类金额和总额 |\n| 导出 | 生成结果 CSV | 明确的下载按钮 |\n\n某行金额写成“二十”时，应指出行号，让用户修正或明确跳过；默默转成零会让结果看似完整却不正确。\n\n## 动手练习\n\n1. 把上述样例保存为 CSV，交给 AI 创建单文件网页工具。\n2. 用浏览器打开文件，上传并检查 48.00 的合计。\n3. 增加一条说明含逗号的记录，验证解析；再加入错误金额。\n4. 导出结果，让同伴从零开始按使用说明完成同一流程。\n\n## 验收标准\n\n- 三条样例数据的分类和总额准确。\n- 错误金额有行号，不会被当作零吞掉。\n- 刷新后的数据保留方式与说明一致，导出文件能够重新打开。\n\n## 自测与参考答案\n\n**问题：** 使用 AI 开发的工具，是否每次运行都要调用模型？\n\n
展开参考答案

不需要。本课工具由普通程序处理文件和计算，AI 参与开发过程。是否内置模型由产品功能决定。

\n\n## 本课带走\n\n先交付一条完整可用的路径，再根据使用反馈扩展功能。\n", "agent_teaching_guide_markdown": "# AI 教学包 · AI 小工具开发实践\n\n## 本课交付与易错点\n\n先核实起点：会运行或让 AI 创建单文件网页；将正文三行 CSV 保存为练习文件。\n\n逐项验收：输入检查、分类汇总与导出的完整路径；正确总额 48.00，错误金额带行号。\n\n重点纠偏：使用真正的 CSV 解析器；刷新是否保留数据要有明确设计，不能默认本地文件等于持久存储。\n\n图解用于解释关系，正文与实际工具结果用于验收；不把图中的虚构数据、示意命令或条件推演称作已经运行的结果。\n\n## 角色与任务\n\n你是本课的实践教练。目标是让学习者完成并解释“任选一个高频小需求，做一个可运行的单文件工具并让同伴体验。”。以随附课程正文为知识依据，采用具体、简洁的中文。当前阶段：L3 / AI Tools Build · AI 工具开发。\n\n## 开始前确认\n\n具备文件操作基础；准备独立练习目录和本课所需运行环境。\n\n先问学习者已经做到哪一步、已有何种文件或结果。已有可用成果就从断点继续。需要编程时先确认工作目录与运行方式；只读分析课不修改被分析项目。\n\n## 本课讲解顺序\n\n1. 选择最小但完整的工具形态\n2. 案例：做一个 CSV 支出汇总器\n3. 画出输入、加工、输出\n\n先讲一个本课场景，再解释图中各部分的职责和连接关系。图的文字说明：CSV 输入：列名、编码、记录行；校验与规范化：金额转整数分 · 错误带行号；分类聚合：同类记录求和；展示与导出：分类金额、总额、有效条数。\n\n## 陪练步骤\n\n1. 把上述样例保存为 CSV，交给 AI 创建单文件网页工具。\n2. 用浏览器打开文件，上传并检查 48.00 的合计。\n3. 增加一条说明含逗号的记录，验证解析；再加入错误金额。\n4. 导出结果，让同伴从零开始按使用说明完成同一流程。\n\n一次推进一个可观察步骤。先请学员预测结果，再运行或推演，再比较预期与实际。遇到错误，收集完整错误、输入和复现过程；定位后继续到本步验收。先给提示，需要时再给完整实现。学习者要求直接完成时执行已明确的任务，并解释关键选择。\n\n## 验收依据\n\n- 三条样例数据的分类和总额准确。\n- 错误金额有行号，不会被当作零吞掉。\n- 刷新后的数据保留方式与说明一致，导出文件能够重新打开。\n\n逐项给出：要求、实际观察、通过或待修正、下一步。运行结果只能来自实际执行；若当前只有设计稿，则按设计验收，说明哪些运行检查留给实践环境。外部写入按用户授权执行。\n\n## 诊断提问与参考判断\n\n提问：使用 AI 开发的工具，是否每次运行都要调用模型？\n\n参考判断：不需要。本课工具由普通程序处理文件和计算，AI 参与开发过程。是否内置模型由产品功能决定。\n\n先等待学习者回答再给参考判断。若回答混淆概念，使用本课案例追问，不直接重复术语。\n\n## 常见误区与纠正\n\n使用真正的 CSV 解析器；刷新是否保留数据要有明确设计，不能默认本地文件等于持久存储。\n\n## 结束交付\n\n给出本课成果位置或可复制内容、验收结果、一个需要复习的点。建议完成本课练习后在站点手动标记已学；你无法替学习者修改站点本地进度。\n" }, { "schema_version": "1.0", "id": "l3-05", "title": "财务小助手实现", "stage": "L3", "language": "zh-CN", "canonical_url": "https://learn.iszhou.com/#lesson/l3-05", "api_url": "https://learn.iszhou.com/api/v1/lessons/l3-05.json", "metadata": { "id": "l3-05", "stage": "L3", "num": 5, "domain": "案例实践", "title": "财务小助手实现", "desc": "把前面学过的 AI Coding 用到一个有输入、处理和结果展示的个人工具中。", "ideas": [ "数据记录：结构化保存交易或预算样例数据", "查询分析：通过自然语言或简单命令得到统计结果", "迭代验证：检查计算口径、修改错误、保存版本" ], "practice": "使用虚构数据做一个能录入并查询支出的小助手，保存代码和测试记录。", "takeaway": "先把工具做出来；架构优化、服务化和部署放在 L4。", "minutes": 60, "full": true, "status": "complete", "illustration": { "src": "assets/finance-roadmap-original.jpg", "alt": "从 AI User 到 AI Builder：个人财务助手实战", "caption": "明确需求 → 数据建模 → 搭建记账能力 → 长期记忆 → 展示结果 → 扩展数据源。本课先实现最小记账闭环，再逐步扩展。", "reused": true } }, "content_markdown": "# 财务小助手实现\n\n> 把前面学过的 AI Coding 用到一个有输入、处理和结果展示的个人工具中。\n\n## 学习起点与本课交付\n\n**开始前：** 准备 Python 3 和独立练习目录，使用正文虚构账目。\n\n**完成后留下：** 可重复初始化的 SQLite 账本、48.00 元汇总，以及新增、查询和异常样例。\n\n## 学习目标\n\n- 数据记录：结构化保存交易或预算样例数据\n- 查询分析：通过自然语言或简单命令得到统计结果\n- 迭代验证：检查计算口径、修改错误、保存版本\n\n## 图解\n\n![从 AI User 到 AI Builder：个人财务助手实战](assets/finance-roadmap-original.jpg)\n\n
明确需求 → 数据建模 → 搭建记账能力 → 长期记忆 → 展示结果 → 扩展数据源。本课先实现最小记账闭环，再逐步扩展。 点击图片可查看大图。
\n\n## 用虚构账目做一个能核对的助手\n\n这节课把“输入、保存、查询、展示”连起来。我们先做个人练习账本：记录日期、分类和支出金额，按分类汇总。先把数据规则做准确，再加自然语言入口。\n\n## 先约定计算口径\n\n本练习使用人民币整数分，支出金额必须大于零；不处理跨币种、退款和转账。日期按交易发生日记录。字段 `id` 标识记录，`amount_cents` 存储金额。若将来增加退款，要单独定义业务类型和净支出口径。\n\nSQLite 是可嵌入应用的数据库，数据可保存在一个文件中。精确到分的金额适合本课的整数存储；浮点数可能存在近似误差。模型可以解释“餐饮花了多少”，加总应交给数据库。\n\n## 可直接运行的起点\n\n保存下面代码为 `finance_demo.py`，用 Python 3 运行。它只初始化一次虚构样例，重复运行不会重复插入。\n\n```python\nimport sqlite3\n\nwith sqlite3.connect('practice.db') as db:\n db.execute('''CREATE TABLE IF NOT EXISTS expenses (\n id TEXT PRIMARY KEY, day TEXT NOT NULL,\n category TEXT NOT NULL,\n amount_cents INTEGER NOT NULL CHECK(amount_cents > 0)\n )''')\n db.executemany(\n 'INSERT OR IGNORE INTO expenses VALUES (?, ?, ?, ?)',\n [('demo-1', '2026-10-01', '餐饮', 2550),\n ('demo-2', '2026-10-02', '交通', 800),\n ('demo-3', '2026-10-03', '餐饮', 1450)]\n )\n for category, cents in db.execute(\n 'SELECT category, SUM(amount_cents) FROM expenses GROUP BY category'\n ):\n print(f'{category}: {cents // 100}.{cents % 100:02d} 元')\n total = db.execute('SELECT COALESCE(SUM(amount_cents), 0) FROM expenses').fetchone()[0]\n print(f'总计: {total // 100}.{total % 100:02d} 元')\n```\n\n这里的问号是参数占位符，数据与 SQL 语句分开传入。`INSERT OR IGNORE` 只用于固定样例初始化；正式录入时遇到重复 ID 应返回明确结果，避免让用户以为一条被忽略的记录已经新增。\n\n## 从演示脚本到小助手\n\n让 AI 在此基础上增加 `add`、`list`、`summary` 三个动作。用户输入“午餐 25.50”，先解析成日期、分类和金额草稿，确认后调用 `add`。原始输入可以作为来源保留，但统计以结构化字段为准。\n\n## 动手练习\n\n1. 运行样例，核对餐饮 40.00、交通 8.00、合计 48.00。\n2. 再运行一次，确认总额没有变成 96.00。\n3. 增加日期区间查询，定义起止日期是否包含边界。\n4. 测试空账本、零金额、非法日期和同 ID 重复提交。\n\n## 验收标准\n\n- 三条样例和重复运行均得到正确结果。\n- 新增数据经过格式与业务校验，失败不会留下半条记录。\n- 能说明数据库文件在哪里，并在关闭程序后重新读取。\n\n## 自测与参考答案\n\n**问题：** 自然语言识别把“打车 18”理解成餐饮，应该在哪一步纠正？\n\n
展开参考答案

在解析草稿确认阶段纠正分类，再保存结构化数据。汇总层只应按已确认数据计算，不能在每次查询时重新猜分类。

\n\n## 延伸阅读\n\n[Python sqlite3：参数绑定与数据库访问](https://docs.python.org/3/library/sqlite3.html) · [SQLite：浮点数与精度](https://www.sqlite.org/floatingpoint.html)\n\n## 本课带走\n\n先形成可核对的账本，再让 AI 成为它的自然语言入口。\n", "agent_teaching_guide_markdown": "# AI 教学包 · 财务小助手实现\n\n## 本课交付与易错点\n\n先核实起点：准备 Python 3 和独立练习目录，使用正文虚构账目。\n\n逐项验收：可重复初始化的 SQLite 账本、48.00 元汇总，以及新增、查询和异常样例。\n\n重点纠偏：整数分由程序求和；自然语言分类先确认；固定样例去重不能直接替代正式录入规则。\n\n图解用于解释关系，正文与实际工具结果用于验收；不把图中的虚构数据、示意命令或条件推演称作已经运行的结果。\n\n## 角色与任务\n\n你是本课的实践教练。目标是让学习者完成并解释“使用虚构数据做一个能录入并查询支出的小助手，保存代码和测试记录。”。以随附课程正文为知识依据，采用具体、简洁的中文。当前阶段：L3 / AI Tools Build · 案例实践。\n\n## 开始前确认\n\n具备文件操作基础；准备独立练习目录和本课所需运行环境。\n\n先问学习者已经做到哪一步、已有何种文件或结果。已有可用成果就从断点继续。需要编程时先确认工作目录与运行方式；只读分析课不修改被分析项目。\n\n## 本课讲解顺序\n\n1. 用虚构账目做一个能核对的助手\n2. 先约定计算口径\n3. 可直接运行的起点\n4. 从演示脚本到小助手\n\n先讲一个本课场景，再解释图中各部分的职责和连接关系。图的文字说明：用户输入：日期、类别、金额；解析与确认：转成结构化草稿；数据库：整数分 · 查询和聚合；结果解释：金额、范围与口径。\n\n## 陪练步骤\n\n1. 运行样例，核对餐饮 40.00、交通 8.00、合计 48.00。\n2. 再运行一次，确认总额没有变成 96.00。\n3. 增加日期区间查询，定义起止日期是否包含边界。\n4. 测试空账本、零金额、非法日期和同 ID 重复提交。\n\n一次推进一个可观察步骤。先请学员预测结果，再运行或推演，再比较预期与实际。遇到错误，收集完整错误、输入和复现过程；定位后继续到本步验收。先给提示，需要时再给完整实现。学习者要求直接完成时执行已明确的任务，并解释关键选择。\n\n## 验收依据\n\n- 三条样例和重复运行均得到正确结果。\n- 新增数据经过格式与业务校验，失败不会留下半条记录。\n- 能说明数据库文件在哪里，并在关闭程序后重新读取。\n\n逐项给出：要求、实际观察、通过或待修正、下一步。运行结果只能来自实际执行；若当前只有设计稿，则按设计验收，说明哪些运行检查留给实践环境。外部写入按用户授权执行。\n\n## 诊断提问与参考判断\n\n提问：自然语言识别把“打车 18”理解成餐饮，应该在哪一步纠正？\n\n参考判断：在解析草稿确认阶段纠正分类，再保存结构化数据。汇总层只应按已确认数据计算，不能在每次查询时重新猜分类。\n\n先等待学习者回答再给参考判断。若回答混淆概念，使用本课案例追问，不直接重复术语。\n\n## 常见误区与纠正\n\n整数分由程序求和；自然语言分类先确认；固定样例去重不能直接替代正式录入规则。\n\n## 结束交付\n\n给出本课成果位置或可复制内容、验收结果、一个需要复习的点。建议完成本课练习后在站点手动标记已学；你无法替学习者修改站点本地进度。\n" }, { "schema_version": "1.0", "id": "l4-1-01", "title": "AI Friendly System 架构入门", "stage": "L4.1", "language": "zh-CN", "canonical_url": "https://learn.iszhou.com/#lesson/l4-1-01", "api_url": "https://learn.iszhou.com/api/v1/lessons/l4-1-01.json", "metadata": { "id": "l4-1-01", "stage": "L4.1", "num": 1, "domain": "系统架构", "title": "AI Friendly System 架构入门", "desc": "从整体认识一个系统：人和 Agent 经由不同入口，操作同一组业务能力和数据。", "ideas": [ "系统结构：入口、身份与权限、业务服务、数据层", "共享能力：Web UI 和 Agent 不应维护两套业务规则", "数据流：一次操作从请求、处理、持久化到结果返回" ], "practice": "为“好书分享”画一张包含人、Agent、权限、业务能力和数据库的模块框图。", "takeaway": "AI Friendly 的关键不是把大模型塞进系统，而是向 AI 开放稳定可用的系统能力。", "minutes": 45, "full": true, "status": "complete", "illustration": { "src": "assets/systems-original.jpg", "alt": "L4：构建可扩展的 AI 系统", "caption": "L4 总览涵盖 AI-friendly System、Mission-driven System 与 Autonomous Exploration，分别对应 L4.1、L4.2、L4.3。本课聚焦第一部分；三种形态均依赖运行环境、状态、权限、监控和恢复。", "reused": true } }, "content_markdown": "# AI Friendly System 架构入门\n\n> 从整体认识一个系统：人和 Agent 经由不同入口，操作同一组业务能力和数据。\n\n## 学习起点与本课交付\n\n**开始前：** 理解 L3 小工具的输入与输出；本课先设计，不要求已部署服务器。\n\n**完成后留下：** 好书分享责任图，能追踪人和 Agent 的一次请求如何进入同一业务服务。\n\n## 学习目标\n\n- 系统结构：入口、身份与权限、业务服务、数据层\n- 共享能力：Web UI 和 Agent 不应维护两套业务规则\n- 数据流：一次操作从请求、处理、持久化到结果返回\n\n## 图解\n\n![L4：构建可扩展的 AI 系统](assets/systems-original.jpg)\n\n
L4 总览涵盖 AI-friendly System、Mission-driven System 与 Autonomous Exploration，分别对应 L4.1、L4.2、L4.3。本课聚焦第一部分；三种形态均依赖运行环境、状态、权限、监控和恢复。 点击图片可查看大图。
\n\n## 01 · 从一个真实场景开始\n\n假设我们做一个「好书分享」小站。人类希望通过网页发布推荐，另一个人的 AI 希望能帮忙查询、修改笔记。\n\n传统网页的主要入口是页面和按钮；**AI Friendly System** 则让 Agent 不必模拟鼠标操作，也能通过明确的能力入口完成同样的业务动作。\n\n这里有一个关键判断：**系统本身不一定要内置大模型。** 它只要把业务能力以清晰、可授权的方式开放给 Agent，就已经迈出了 AI Friendly 的关键一步。\n\n## 02 · 整个系统怎样协作？\n\n
\n
HumanWeb UI / 网页
AgentSkill / CLI / API
\n
↓↓
\n
身份认证与权限控制确认谁在调用、允许做什么
\n
↓
\n
共享业务能力 / API发布、查询、修改、删除、校验规则
\n
↓
\n
数据与外部系统数据库、文件、第三方服务
\n
\n\n这是一张**教学用逻辑架构图**，表达处理顺序与责任边界；在真实工程中，认证也可以在网关或业务服务中执行，不必是单独一台服务器。\n\n## 03 · 认识四个核心部分\n\n| 部分 | 解决什么问题 | 在「好书分享」中的例子 |\n|---|---|---|\n| **交互入口** | 谁以什么方式发起动作 | 人点击发布按钮；Agent 调用工具 |\n| **身份与权限** | 谁能访问，允许做什么 | 有效 Key 可发书评；无权限请求被拒绝 |\n| **共享业务能力** | 真正执行规则与操作 | 校验书名、保存分享、更新笔记 |\n| **数据层** | 状态记录在哪里 | 书籍与分享记录存到数据库 |\n\n注意，**Web UI 和 Agent 接口不是两套独立系统**。它们只是对同一业务能力的两种使用方式。\n\n## 04 · 同一操作，两条调用路径\n\n以「新增一本书」为例：\n\n- **人类路径：** 填表 → 网页发起请求 → 身份校验 → 新增分享 → 数据库保存 → 页面看到结果。\n- **Agent 路径：** 理解用户指令 → 读取 Skill → 执行 CLI / API 请求 → 同一套校验与新增逻辑 → 返回结果。\n\n如果把「新增分享」规则分别写在网页与 Agent 中，未来修改字段时就容易出现两套不一致的行为。**共同的业务规则应尽量集中在服务一侧。**\n\n## 05 · 从工具走向系统，先问五个问题\n\n1. **业务对象是什么？** 例如书籍、分享、用户、任务。\n2. **有哪些重要动作？** 新增、查询、修改、删除分别由谁触发？\n3. **入口有哪些？** 只有网页，还是还需要 CLI、API、Agent？\n4. **谁能做什么？** 哪些操作需要登录、授权和审计？\n5. **状态保存在哪里？** 关闭网页、服务重启或换设备后，数据会怎样？\n\n你不必在这一课就会写 API 或画高级架构图；先能解释这些边界，后面学习 HTTP、UI、IAM 和云部署才有落点。\n\n## 练一练 · 15 分钟架构拆解\n\n**任务：** 为「好书分享」画一张模块框图，至少画出以下对象：Human/Web UI、Agent/Skill、身份与权限、共享业务服务、数据库。\n\n**验收标准：**\n\n- 人和 Agent 是不同入口，但最终调用同一业务服务。\n- 能指出「发布一本书」需要经过哪些环节。\n- 数据存在哪里，以及身份校验发生在哪一段，能解释清楚。\n- 模块关系清楚，不必画出具体技术品牌或服务器数量。\n\n## Takeaway · 带走三句话\n\n1. **AI Friendly ≠ 系统里必须内置大模型**；关键是系统能力能被 AI 稳定、清晰地调用。\n2. **入口可以不同，业务规则应共享**：Web UI 与 Agent API 只是两种访问方式。\n3. **先画清责任与数据流，再选技术。** 下一讲我们就解释图中的 HTTP 与 API 到底是什么。\n\n## 自测与参考答案\n\n**问题：** 网页和 Agent 各写一份“新增书籍”的校验，有什么问题？\n\n
展开参考答案

规则容易在更新后分叉。应让两个入口调用同一业务能力，由服务端实施共有校验、授权与数据写入。

\n", "agent_teaching_guide_markdown": "# AI 教学包 · AI Friendly System 架构入门\n\n## 本课交付与易错点\n\n先核实起点：理解 L3 小工具的输入与输出；本课先设计，不要求已部署服务器。\n\n逐项验收：好书分享责任图，能追踪人和 Agent 的一次请求如何进入同一业务服务。\n\n重点纠偏：逻辑层不等于独立服务器；AI Friendly 不以系统内置模型为前提。\n\n图解用于解释关系，正文与实际工具结果用于验收；不把图中的虚构数据、示意命令或条件推演称作已经运行的结果。\n\n## 角色与任务\n\n你是本课的实践教练。目标是让学习者完成并解释“为“好书分享”画一张包含人、Agent、权限、业务能力和数据库的模块框图。”。以随附课程正文为知识依据，采用具体、简洁的中文。当前阶段：L4.1 · 系统架构。\n\n## 开始前确认\n\n已做过一个小工具；准备好书分享或财务助手练习项目。\n\n先问学习者已经做到哪一步、已有何种文件或结果。已有可用成果就从断点继续。需要编程时先确认工作目录与运行方式；只读分析课不修改被分析项目。\n\n## 本课讲解顺序\n\n1. 学习目标\n2. 01 · 从一个真实场景开始\n3. 02 · 整个系统怎样协作？\n4. 03 · 认识四个核心部分\n5. 04 · 同一操作，两条调用路径\n6. 05 · 从工具走向系统，先问五个问题\n7. 练一练 · 15 分钟架构拆解\n8. Takeaway · 带走三句话\n\n先讲一个本课场景，再解释图中各部分的职责和连接关系。图的文字说明：复用此前 L4 三阶段图：开放能力、持续完成目标、探索与验证。图片保留原有阶段称呼，当前细分以左侧目录为准。\n\n## 陪练步骤\n\n**任务：** 为「好书分享」画一张模块框图，至少画出以下对象：Human/Web UI、Agent/Skill、身份与权限、共享业务服务、数据库。\n\n**验收标准：**\n\n- 人和 Agent 是不同入口，但最终调用同一业务服务。\n- 能指出「发布一本书」需要经过哪些环节。\n- 数据存在哪里，以及身份校验发生在哪一段，能解释清楚。\n- 模块关系清楚，不必画出具体技术品牌或服务器数量。\n\n一次推进一个可观察步骤。先请学员预测结果，再运行或推演，再比较预期与实际。遇到错误，收集完整错误、输入和复现过程；定位后继续到本步验收。先给提示，需要时再给完整实现。学习者要求直接完成时执行已明确的任务，并解释关键选择。\n\n## 验收依据\n\n人和 Agent 共用业务服务；解释身份校验位置、持久数据位置与一次完整调用。\n\n逐项给出：要求、实际观察、通过或待修正、下一步。运行结果只能来自实际执行；若当前只有设计稿，则按设计验收，说明哪些运行检查留给实践环境。外部写入按用户授权执行。\n\n## 诊断提问与参考判断\n\n提问：网页和 Agent 各写一份“新增书籍”的校验，有什么问题？\n\n参考判断：规则容易在更新后分叉。应让两个入口调用同一业务能力，由服务端实施共有校验、授权与数据写入。\n\n先等待学习者回答再给参考判断。若回答混淆概念，使用本课案例追问，不直接重复术语。\n\n## 常见误区与纠正\n\n逻辑层不等于独立服务器；AI Friendly 不以系统内置模型为前提。\n\n## 结束交付\n\n给出本课成果位置或可复制内容、验收结果、一个需要复习的点。建议完成本课练习后在站点手动标记已学；你无法替学习者修改站点本地进度。\n" }, { "schema_version": "1.0", "id": "l4-1-02", "title": "HTTP 与 API：从调用到自己封装", "stage": "L4.1", "language": "zh-CN", "canonical_url": "https://learn.iszhou.com/#lesson/l4-1-02", "api_url": "https://learn.iszhou.com/api/v1/lessons/l4-1-02.json", "metadata": { "id": "l4-1-02", "stage": "L4.1", "num": 2, "domain": "系统通信与接口", "title": "HTTP 与 API：从调用到自己封装", "desc": "通过八个小节，学习现成 API 调用、接口契约、Python 封装与函数计算部署。", "ideas": [ "理解 HTTP、JSON、状态与契约，调用公开和鉴权 API", "按写入、文件、异步与 Webhook 场景设计调用链", "用 Python 封装业务函数，并选择阿里云 FC 托管" ], "practice": "调用两种查询场景，运行自己的 Python 汇总 API 并测试失败；选修函数计算云部署。", "takeaway": "先会调用，再按契约提供自己的 API；Python 负责实现，FC 负责托管。", "minutes": 150, "full": true, "status": "complete", "illustration": { "src": "assets/course-art/l4-1-02-warm-v3.webp", "alt": "读懂一组 HTTP 请求与响应", "caption": "客户端：网页 / CLI / Agent；请求：方法、URL、头、JSON；业务服务：验证输入 · 执行业务规则；响应：状态码、头、结果 / 错误。", "reused": false } }, "content_markdown": "# HTTP 与 API：从调用到自己封装\n\n> 先做接口使用者，再做提供者：调用不同场景的 API，用 Python 封装业务函数，最后选择函数计算托管。\n\n## 学习起点与本课交付\n\n**开始前：** 会运行一个 L3 小工具，准备 Apipost 或同类测试工具。第 1–5 节先练调用和设计；第 6 节需要 Python 3.10+；第 7 节才需要自己的阿里云账号与 FC 权限。前六节不需要购买 ECS。\n\n**完成后留下：** 场景调用清单、接口契约、可运行的 Python API、成功与失败请求记录；选择云端路线后，再留下部署配置与远程调用记录。\n\n本课分成八个小章节，可从课内导航分别定位。建议分两次完成：调用与设计约 60 分钟，本地封装与验收约 60 分钟，云部署选修另留 30 分钟。沿用原课程链接。\n\n
\n
第一遍 · 会调用01–04：看懂请求，调用服务HTTP 基础 → 公开查询 → 鉴权 → 文件与异步场景
\n
第二遍 · 会封装05–06：设计契约，运行 Python先定义输入输出，再运行自己的 Python API
\n
选修与验收07–08：云端托管，验证闭环函数计算选修；以实际请求与结果完成验收
\n
\n\n## 学习目标\n\n- HTTP：方法、URL、请求与响应状态\n- JSON：接口传递数据的常用格式\n- API：暴露业务操作的清晰契约与参数边界\n- 场景调用：公开查询、鉴权、写入、文件、异步任务与 Webhook\n- 自己封装：Python 实现、契约验证与函数计算托管\n\n## 图解\n\n![读懂一组 HTTP 请求与响应](assets/course-art/l4-1-02-warm-v3.webp)\n\n
客户端：网页 / CLI / Agent；请求：方法、URL、头、JSON；业务服务：验证输入 · 执行业务规则；响应：状态码、头、结果 / 错误。 点击图片可查看大图。
\n\n## 01｜HTTP 基础：读懂一次请求与响应\n\n**HTTP** 定义客户端与服务端怎样交换请求和响应；**API** 定义系统提供哪些能力、接受哪些参数、返回什么结果。\n\nAPI 也可以通过其他方式实现，本课聚焦常见的 HTTP JSON 接口。\n\n一次请求通常包含**方法、URL、请求头和可选正文**。方法说明动作类型，URL 指向资源，请求头带内容格式或身份信息，正文放具体业务数据。\n\n响应包含**状态码、响应头和正文**。\n\n### 阅读一个接口契约\n\n下面是本课程“好书分享”的**设计示例**，这些路径需要在练习服务中实现。\n\n| 动作 | 接口 | 关键输入 | 成功结果 |\n|---|---|---|---|\n| 查书单 | GET /api/books | limit、cursor | 记录列表与下一页游标 |\n| 新增 | POST /api/books | title、note | 201 与新记录 ID |\n| 修改 | PATCH /api/books/b-001 | note、version | 更新后记录与版本 |\n| 删除 | DELETE /api/books/b-001 | 身份凭证 | 204，无正文 |\n\n```http\nPOST /api/books\nContent-Type: application/json\n\n{\"title\":\"系统之美\",\"note\":\"关注反馈与延迟\"}\n```\n\nJSON 使用双引号包住键和字符串；数字、布尔值、数组、对象各有类型。若服务约定 `version` 为整数，传入字符串 `\"2\"` 就可能被拒绝。契约中应明确必填、类型、长度和允许的值。\n\n\n\n### 用状态码定位问题\n\n200 常表示成功返回结果，201 表示创建成功；400 表示请求有问题；401 常用于缺少有效认证；403 表示拒绝授权；404 表示资源不存在；409 可用于版本冲突；429 表示请求过频；500 表示服务内部异常。具体含义要结合接口正文和约定。\n\n错误正文可以返回 `code`、`message`、`request_id`，例如 `VERSION_CONFLICT`。用户得到可理解的说明，开发者用请求 ID 找日志。不要把内部堆栈或凭证放到对外错误里。\n\n## 02｜公开查询：先调用现成 API\n\n先读文档中的 Base URL、方法、路径、参数、响应和限额，再用测试工具发送请求，最后迁移到 Python。用真实响应学习，不凭示例值判断已经成功。\n\n| 场景 | 可直接发送的 GET 地址 | 观察重点 |\n|---|---|---|\n| 查课程目录 | `https://learn.iszhou.com/api/v1/catalog.json` | 从 lessons 读取 ID、title、api_url |\n| 读单课 | `https://learn.iszhou.com/api/v1/lessons/l4-1-02.json` | 路径中的课程 ID、content_markdown |\n| 查天气 | `https://api.open-meteo.com/v1/forecast?latitude=31.23&longitude=121.47¤t=temperature_2m&timezone=Asia%2FShanghai` | 查询参数、current、current_units、时间 |\n\n路径用来定位资源，查询参数跟在 `?` 后表达筛选等条件。只有接口明确支持的参数才有效；本站静态课程 API 没有筛选或分页能力，任意加 `limit` 不代表实现了分页。\n\n天气练习使用 Open-Meteo 公共非商业接口，许可与限额见[官方文档](https://open-meteo.com/en/docs)。公开接口也需要遵守服务限制，失败时保留实际错误，不把样例数据说成当天天气。\n\n```python\nimport json\nfrom urllib.request import urlopen\n\nwith urlopen(\"https://learn.iszhou.com/api/v1/catalog.json\", timeout=15) as response:\n catalog = json.load(response)\nprint(catalog[\"lessons\"][0][\"title\"])\n```\n\n\n\n## 03｜鉴权调用：明确身份与权限\n\n认证回答“谁在调用”，授权回答“允许操作什么”。API Key、Bearer Token、OAuth、云服务签名不是同一种机制。\n\n| 场景 | 常见方式 | 先验证什么 |\n|---|---|---|\n| GitHub 私有仓库 | Token / OAuth | 本人身份、目标仓库、读写权限；能读不代表能 push |\n| 日历、邮件 | OAuth 与具体 scope | 先只读，确认账号和目标日历；创建事项需要相应权限与操作授权 |\n| 模型、天气等服务 | 服务指定的 Key/Token | 正确域名、请求头、配额与具体接口 |\n| 阿里云资源管理 | RAM、角色、签名凭据 | 使用官方 SDK/签名方式，AK/SK 不能直接当普通 Bearer |\n\n已有授权先复用并做只读验证。凭据放安全凭据库或环境变量，不写进源码、截图、提示词和 Git；只向已确认的服务地址发送凭据。本站课程 API 无需登录，不能用它证明真实认证已成功。\n\n\n\n无第三方账号时，使用第 6 节自己的 Token 接口练习：不带 Token、错误 Token 应被拒绝，正确 Token 应成功。再建立一张“服务、账号、认证方式、权限范围、凭据引用、验证结果”的调用身份卡，只记录引用，不记录密钥值。\n\n## 04｜场景调用：写入、文件、异步与 Webhook\n\n以下是通用设计，不是本站已有的写接口。真实路径、字段与限制均以目标服务文档为准。\n\n| 场景 | 调用方式 | 验收点 |\n|---|---|---|\n| 查询与搜索 | GET + 参数，按游标翻页 | 不漏页；看排序、时间范围与限流 |\n| 新增与修改 | POST/PATCH + JSON | 检查必填；保存新 ID/版本；再回读 |\n| 图片、录音上传 | multipart/form-data，或预签名 URL 上传二进制 | 依文档选方式；核对大小、类型、asset_id |\n| 多图课程更新 | 分批上传资产，再提交正文中的引用 | 上传不等于发布；检查失效引用和版本 |\n| 长任务、转录 | 提交 → job_id → 轮询状态 → 取结果 | 202 只代表受理；处理失败、取消和超时 |\n| Webhook 事件通知 | 外部系统向你的回调地址发 POST | 按文档验签、检查时间窗、按 event_id 去重 |\n\n图片不要默认转 Base64 放进 JSON，只有接口明确要求时才这样做。multipart 的 boundary 通常由客户端生成；预签名地址是临时凭证，依签名约定的方法和 Content-Type 上传，不公开分享。\n\n邮件、日历等写入先选测试对象并获得操作授权，再发请求、回读结果。Webhook 回调必须对发送方可达，127.0.0.1 只指调用者自己的电脑；验签需按服务规则处理原始正文，快速确认接收后再执行后续任务。\n\n\n\n**重试：** 只读请求按文档限次退避，429 查看 Retry-After。创建超时后可能已经落库，应先按业务 ID 或服务支持的幂等机制查结果，不直接重复创建。自行加一个 Idempotency-Key 请求头不会让服务自动拥有幂等能力。\n\n\n\n## 05｜设计自己的 API：先写契约\n\n主练习选择“支出金额汇总”，只计算，不保存账本、发送邮件或调用付费模型。它让你集中学封装，不先增加数据库。\n\n| 项目 | 本练习约定 |\n|---|---|\n| 健康检查 | GET /health，无需认证 |\n| 业务接口 | POST /api/summary，Bearer 认证 |\n| 请求 | application/json，最多 16 KiB；只有 amounts 字段 |\n| 金额列表 | 1–100 个十进制字符串，最多两位小数，单项绝对值不超过 1,000,000 元 |\n| 金额规则 | 固定 CNY，负数表示冲回，Decimal 运算 |\n| 成功 | 200；count、total、currency、request_id |\n| 失败 | 400 参数、401 认证、413 大小、415 格式；返回 code、message、request_id |\n| 状态 | 无状态，不存储；重复计算不累计 |\n\n```http\nPOST /api/summary\nContent-Type: application/json\nAuthorization: Bearer <从安全配置读取>\n\n{\"amounts\":[\"18.00\",\"30.00\"]}\n```\n\n\n\n业务函数负责计算；HTTP 层负责路由、认证、解析和响应；运行平台负责进程、网络与日志。先把这三层分开，再写实现。第一节书单契约是扩展设计，不是这个练习包已经实现的接口。\n\n## 06｜Python 小章节：封装并调用 API\n\n下载并解压 [API 练习包](assets/labs/api-workshop.zip)，包含 server.py、client.py、README。也可查看[服务端](assets/labs/api-workshop/server.py)与[客户端](assets/labs/api-workshop/client.py)。只用 Python 标准库，无需 pip 安装依赖。\n\n### 第一步：启动本地服务\n\n在解压目录打开 PowerShell，确认 `python --version` 为 3.10+。以下在同一终端生成临时凭据并启动后台服务，子进程继承环境变量，不需要打印、抄写 Token：\n\n```powershell\n$env:LAB_API_TOKEN = python -c \"import secrets; print(secrets.token_urlsafe(32))\"\n$env:HOST = '127.0.0.1'\n$env:PORT = '9000'\n$labServer = Start-Process python -ArgumentList 'server.py' -PassThru -WindowStyle Hidden\nInvoke-RestMethod 'http://127.0.0.1:9000/health'\npython client.py\n```\n\n如果服务尚在启动，等 /health 实际成功后再调用。新开终端不会自动继承这里的 Token；如需前台看启动信息，可在配置好相同环境的终端运行 `python server.py`，不要同时启动两个占用 9000 端口的服务。\n\n客户端应返回 200、48.00；重复调用仍为 48.00。它通过网络访问你的服务，不直接 import 计算函数。\n\n### 第二步：主动验证失败请求\n\n```powershell\ntry {\n Invoke-RestMethod -Method Post -Uri 'http://127.0.0.1:9000/api/summary' `\n -Headers @{ Authorization = \"Bearer $env:LAB_API_TOKEN\" } `\n -ContentType 'application/json' -Body '{\"amounts\":[\"oops\"]}'\n} catch {\n $_.Exception.Response.StatusCode\n $_.ErrorDetails.Message\n}\n```\n\n预期 400 与 INVALID_INPUT。用测试工具再测缺 Token 的 401、text/plain 的 415；测试工具凭据从自己的安全环境配置，不写进分享截图。\n\n### 第三步：结束练习，读懂三层代码\n\n完成后只停止本次启动的服务，不按进程名批量停止 Python：\n\n```powershell\nStop-Process -Id $labServer.Id\nRemove-Item Env:LAB_API_TOKEN\n```\n\n\n\n这是便于阅读的教学 HTTP Server，不作为生产服务模板。正式使用可换 FastAPI + ASGI 服务，并补齐限流、凭据轮换、审计与容量设计；保留业务函数、契约与验收样例。\n\n## 07｜函数计算小章节：托管同一个 Python API\n\nPython 是实现语言，阿里云函数计算 FC 是运行平台，二者可以一起使用。也可在自己的电脑或 ECS 长期运行服务，但需要自己管理进程、HTTPS 和网络。本节选择 Web 函数 / 自定义运行时，避免混用仅接收事件 handler 的模式。\n\n\n\n1. 创建独立练习 Web 函数，选择支持 Python 的自定义运行时；核实 python3 的版本和路径。\n2. 上传代码 ZIP，server.py 必须位于代码根目录。启动命令为 `python3 /code/server.py`；若控制台分开命令与参数，按其字段拆填，实际目录不同则调整路径。\n3. 平台监听端口设 9000，环境变量设 `HOST=0.0.0.0`、`PORT=9000`，代码端口必须一致。仅监听 127.0.0.1 会让平台无法连接。\n4. 在函数安全配置中设置随机 LAB_API_TOKEN，至少 24 字符，不放进上传包。本练习应用校验 Bearer；若同时启用平台认证，调用者还需满足平台规则，两层认证不能混淆。\n5. 配 HTTP 触发器允许 GET、POST，取得实际 HTTPS 地址。若地址含前缀，按平台转发行为确认应用收到 /health 和 /api/summary，不能臆造调用地址。\n6. 先查 /health，再发带 Token 的 POST。查日志和 request_id；区分平台拒绝与应用的 UNAUTHENTICATED，不凭猜测认定原因。\n7. 调用端设置 API_BASE 为实际 HTTPS 基地址，安全配置与函数一致的 LAB_API_TOKEN，再运行 client.py。换独立终端或设备复测并保存脱敏结果。\n8. 练习结束关闭不用的触发器或清理明确的练习资源，核对账单。调用、计算资源和流量等可能收费；无需购买 ECS 不代表一定免费。\n\n函数实例会复用、重启或扩容，内存列表和本地临时文件不等于持久数据库。当前接口无状态，适合练习；扩展书单或账本需外部数据库、事务与数据权限。\n\n本课是服务端客户端调用，无需 CORS。以后让浏览器跨域直连时，再按实际域名配置 CORS/OPTIONS；CORS 不替代认证。\n\n配置依据：[阿里云 Web 函数](https://www.alibabacloud.com/help/zh/functioncompute/creating-a-web-function) · [自定义运行时原理](https://help.aliyun.com/zh/functioncompute/principles-1) · [监听端口要求](https://help.aliyun.com/zh/functioncompute/must-the-listening-port-of-a-custom-runtime-be-the-same-as-that-of-the-http-server-of-the-custom-runtime)。\n\n## 08｜完整验收：调用者与提供者都能做\n\n**先完成本地闭环，再按需选择云端。** 每项都留下实际证据：\n\n1. 查询课程和另一种公开/已授权 API，保存实际返回和字段映射。\n2. 任选录音、图片或日历场景写调用计划，标明设计与真实执行的边界。\n3. 跑通自己的 Python 汇总 API，测试成功与失败；重复调用不累计。\n4. 选修 FC 路线时，将同样请求迁移到云端并独立复测。\n5. 保存契约、源码、配置项名称、脱敏请求响应和已知限制，不保存实时凭据。\n\n| 检查 | 应看到的证据 |\n|---|---|\n| 基础结构 | 能指出方法、路径、查询参数、头、正文和响应 |\n| 调用现成服务 | 真实响应与提取字段，能解释时间、单位和分页 |\n| 认证 | 缺少/错误 Token 被拒绝，正确 Token 成功 |\n| 自己封装 | 18.00 + 30.00 返回 48.00，重复不累计 |\n| 边界失败 | 非法输入 400、类型 415、大包 413、未知路径 404 |\n| 云端选修 | 实际 HTTPS 地址可被独立调用者访问，日志可定位请求 |\n| 状态区分 | 不把本地完成说成云部署，不把设计说成运行成功 |\n\n### 书单扩展练习\n\n学完主线后，可把第一节契约扩展成真正有持久化的书单：\n\n1. 让 AI 在本地实现上述查书单和新增接口，使用虚构数据。\n2. 用接口测试工具发送 GET，再发送一个合法 POST。\n3. 去掉 title，记录状态码和错误正文。\n4. 再查列表，确认失败请求没有新增空书名记录。\n\n### 书单扩展验收（选做）\n\n- 能指出方法、地址、请求数据和返回结果。\n- 合法请求创建记录，缺必填字段的请求被拒绝。\n- API 文档中的示例与本地实际返回一致。\n\n## 自测与参考答案\n\n**问题：** 收到 202 Accepted，是否就能说后台任务已完成？\n\n
展开参考答案

还需要查询任务状态。202 表示已接受处理，服务应提供任务 ID 或状态查询方式，最终完成与否由后续状态决定。

\n\n**问题：** 本机函数能运行，为什么别人仍然无法调用？\n\n
展开参考答案

还需要 HTTP 入口、调用方可达的地址与认证。127.0.0.1 指向调用者本机，不能代表另一台电脑上的服务。Python 是实现语言，函数计算是可选运行平台。

\n\n**问题：** 创建日程超时，能马上再发一次吗？\n\n
展开参考答案

先查询是否已创建，或使用服务明确支持的幂等机制，不能仅凭超时认定未写入。

\n\n## 延伸阅读\n\n[MDN：HTTP 概览](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Overview) · [HTTP 状态码](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status)\n\n[Python HTTP Server 的教学边界](https://docs.python.org/3/library/http.server.html)\n\n## 本课带走\n\n从“读文档、发请求、验结果”走到“定义契约、封装业务、提供接口”。后续 [接口封装](#lesson/l4-1-07)继续扩展 CLI/MCP；[云基础设施](#lesson/l4-1-10)讲运行运维；[财务架构复盘](#lesson/l4-1-14)深入数据与权限。本站 /api-lab 是固定教学响应，下载的 Python 练习服务才实际执行计算，二者不能混作验证证据。\n", "agent_teaching_guide_markdown": "# AI 教学包 · HTTP 与 API：从调用到自己封装\n\n## 本课交付与易错点\n\n起点：会运行 L3 小工具，准备测试工具；第6节需要Python 3.10+，第7节才需要FC账号。交付：场景调用清单、接口契约、Python API与成功失败请求；云端选修另需实际部署证据。\n\n公开API不验证身份；API Key、Bearer、OAuth、云签名不可混用；202只表示受理；POST超时不盲目重发。/api/books仅为扩展设计，/api-lab是固定教学响应，不能作为真实计算或持久写入证据。\n\n## 角色与教学顺序\n\n你是实践教练，按八小节推进；先问断点，复用现有环境与授权。每次预测、实际执行、核对结果。无运行证据就标待验证；凭据不写聊天或Git。\n\n1. HTTP基础：拆解真实课程URL与响应，分清方法、路径、查询、头、JSON、状态。\n2. 公开查询：先用测试工具调用课程和天气/另一服务，再迁移Python；核对字段、时间、单位、分页和超时。\n3. 鉴权：核对身份、权限、凭据引用；无第三方账号时以自己的练习API验证缺失、错误和正确Token。\n4. 场景：读写、上传、异步、Webhook；交付录音入库调用清单。无真实接口时按设计验收，外部写入按用户授权执行。\n5. 契约：POST /api/summary，金额字符串与Decimal、数量和大小限制、响应与无状态边界。\n6. Python：下载练习包，按summarize→Handler→client阅读并发真实HTTP请求。成功48.00重复不累计；输入400、认证401、格式415、大包413、路径404。标准库Server仅教学，不作生产模板。\n7. FC选修：Python是实现，FC是平台；依官方Web函数/自定义运行时核实Python路径、9000端口、0.0.0.0、环境Token、触发器和HTTPS。平台认证与应用认证分开判断；无授权不创建付费资源。\n8. 验收：要求对应实际观察、通过/待验证和成果位置。本地运行不等于云部署，配置不等于独立调用成功。\n\n## 实践判定\n\n- 18.00+30.00返回200、count=2、total=48.00、currency=CNY和request_id；重复不累计。\n- 失败返回约定状态，不泄露内部堆栈、Token或正文。\n- 两种查询场景保留实际响应；第三方不可用就标未完成，不虚构。\n- FC需实际HTTPS调用和日志证据。\n- 练习包不保存账本、不上传图片、不代理第三方服务，不夸大范围。\n\n## 诊断问题\n\n1. 本机函数为什么不能直接被别人调用？需要HTTP入口、可达网络和认证，127.0.0.1是调用者本机。\n2. 202是否完成？需要任务ID与最终状态或经过验证的回调。\n3. 创建超时如何处理？先按业务ID查询，依服务实现的幂等机制处理。\n4. FC内存可当数据库吗？实例复用、重启和扩容意味着非持久、非全局共享。\n\n## 结束交付\n\n汇总已完成成果、实际验收、已知限制与阻碍。不混报设计、本机、云端与第三方写入；不修改浏览器本地进度。\n" }, { "schema_version": "1.0", "id": "l4-1-03", "title": "UI/UX 设计入门", "stage": "L4.1", "language": "zh-CN", "canonical_url": "https://learn.iszhou.com/#lesson/l4-1-03", "api_url": "https://learn.iszhou.com/api/v1/lessons/l4-1-03.json", "metadata": { "id": "l4-1-03", "stage": "L4.1", "num": 3, "domain": "UI/UX 设计", "title": "UI/UX 设计入门", "desc": "用财务小助手的支出录入，练习信息层级、表单状态与失败恢复。", "ideas": [ "信息层级：重要内容先被看见", "界面构成：布局、对齐、留白、字体与组件", "交互反馈：操作可发现、状态可理解、错误可恢复" ], "practice": "为财务小助手设计记一笔支出的四种状态，检查金额单位、失败恢复和手机长备注。", "takeaway": "界面设计不是装饰，而是帮助用户完成任务。", "minutes": 30, "full": true, "status": "complete", "illustration": { "src": "assets/course-art/l4-1-03-finance-warm-v4.webp", "alt": "财务小助手支出表单的四种状态", "caption": "记一笔支出：金额单位明确；保存中防连点；成功提供查看账单与再记一笔；失败保留输入，长备注适应手机宽度。保存结果未知时先确认，避免重复记账。", "reused": false } }, "content_markdown": "# UI/UX 设计入门\n\n> 认识好界面如何减少认知负担，让用户知道下一步该做什么。\n\n## 学习起点与本课交付\n\n**开始前：** 沿用财务小助手，选定“记一笔支出”这一个任务；先用草图，不要求账本后端已经可用。\n\n**完成后留下：** 默认、提交中、成功、失败四种状态，包含键盘路径和手机长文本检查。\n\n## 学习目标\n\n- 信息层级：重要内容先被看见\n- 界面构成：布局、对齐、留白、字体与组件\n- 交互反馈：操作可发现、状态可理解、错误可恢复\n\n## 图解\n\n![财务小助手支出表单的四种状态](assets/course-art/l4-1-03-finance-warm-v4.webp)\n\n
记一笔支出：金额单位明确；保存中防连点；成功提供查看账单与再记一笔；失败保留输入，长备注适应手机宽度。保存结果未知时先确认，避免重复记账。 点击图片可查看大图。
\n\n## 设计从用户要完成的事开始\n\nUI 是界面的呈现与操作控件；UX 关注用户从进入到完成任务的整体体验。一个页面漂亮但不知道点哪里，或保存失败后输入全部丢失，都会让任务难以完成。\n\n本课围绕财务小助手的“记一笔支出”：输入金额、日期、分类与备注，确认保存，再看到新账目。导航、提示、装饰都服务这条主线。用户首次进入时，应立即理解页面用途和主要操作。示例用虚构支出，不连接真实银行或支付账户。\n\n与第 02 课保持边界：`/api/summary` 只做金额计算，不保存记录。本课设计的“保存支出”属于待实现的账本扩展 `/api/expenses`，不能把汇总结果或静态成功画面当作真实保存证据。\n\n## 用信息层级降低理解成本\n\n标题说明当前位置；简短说明解释要做什么；输入项提供明确标签；主按钮表达动作结果。把“确定”改成“保存支出”，用户能更容易预判点击后发生什么。次要操作“取消”与主要操作视觉上有所区分，未保存时离开要说明是否会丢失输入。\n\n金额框标注“金额（元）”，示例输入 `25.50`；分类为“餐饮”，备注为“午餐”。日期可预填当天并允许修改。不要用占位符代替标签，也不要让用户自己猜金额单位。扩展账本 API 使用整数分时，界面应精确转换为 `amount_minor=2550`，避免二进制浮点取整误差，并与服务端共同校验。\n\n| 设计要素 | 做法 | 检查方法 |\n|---|---|---|\n| 对齐 | 标签、输入框和错误消息有统一起点 | 扫一眼能找到同类信息 |\n| 留白 | 相关内容靠近，不相关内容分组 | 不靠粗边框也能识别分组 |\n| 字体 | 正文可读，层级数量有限 | 手机上无需放大正文 |\n| 状态 | 加载、成功、空白、失败都有表达 | 用户知道现在发生了什么 |\n| 可访问性 | 有标签、键盘焦点和文字反馈 | 不只靠颜色区分错误 |\n\n## 四种状态比四种配色更重要\n\n空列表说明“还没有支出记录”，并提供“记一笔”入口；加载中显示正在获取；保存成功展示记录 ID、金额、日期与分类，并提供“查看账单”或“再记一笔”。只有真实接口确认成功才进入已保存状态。对于耗时操作，按钮状态可以避免连点，但服务端仍需处理重复请求。\n\n| 状态 | 用户看到什么 | 应有的行为 |\n|---|---|---|\n| 可填写 | 金额、日期、分类、备注及“保存支出” | 可编辑，明确必填与单位 |\n| 提交中 | “正在保存”，按钮禁用 | 不重复发送，保留表单内容 |\n| 保存成功 | 新记录及“查看账单 / 再记一笔” | 以服务端返回及回读为准 |\n| 失败或结果未知 | 字段错误，或“结果待确认” | 保留输入；超时先查询，避免重复记账 |\n\n### 案例：错误反馈\n\n“提交失败”不能帮助用户修复问题。“请输入大于 0、最多两位小数的金额”应出现在金额输入附近；“暂时无法确认保存结果，输入已保留”应出现在表单整体附近。错误位置应对应原因所在范围。创建请求超时不等于未保存，应先按约定标识查询；查明未保存后再重试，不能直接生成一笔新账。\n\n## 动手练习\n\n1. 为“记一笔支出”画出默认、提交中、成功和失败四种状态，示例为餐饮 25.50 元。\n2. 将所有含糊按钮改成明确动作名称。\n3. 用键盘走完输入与提交，检查焦点顺序。\n4. 将页面缩到手机宽度，检查长备注、金额单位和错误文字是否被遮挡。\n5. 写出从页面 `25.50 元` 到 API `2550 分` 的字段映射，并检查超时后的确认路径。\n\n## 验收标准\n\n- 用户不看说明也能找到“记一笔”入口并理解金额单位。\n- 失败后输入保留，错误消息指出可修正的位置。\n- 主任务可通过键盘完成，移动端正文和按钮可读可操作。\n- “保存成功”有明确依据；接口未实现时只按设计验收，不宣称已记账。\n\n## 自测与参考答案\n\n**问题：** 把失败提示文字改成红色，是否已经足够？\n\n
展开参考答案

还需要明确文字、相关位置和恢复方式。颜色可以辅助注意，但不能承载全部含义。

\n\n## 本课带走\n\n先设计任务路径和状态反馈，再打磨视觉风格。\n", "agent_teaching_guide_markdown": "# AI 教学包 · UI/UX 设计入门\n\n## 本课交付与易错点\n\n先核实起点：沿用财务小助手，选定记一笔支出这一个任务，先用草图，不要求账本后端已经可用。\n\n逐项验收：默认、提交中、成功、失败四种状态，包含键盘路径和手机长文本检查。\n\n重点纠偏：错误不能只靠颜色；失败保留输入；界面防连击不能替代后端幂等。\n\n图解用于解释关系，正文与实际工具结果用于验收；不把图中的虚构数据、示意命令或条件推演称作已经运行的结果。\n\n## 角色与任务\n\n你是本课的实践教练。目标是让学习者完成并解释“为财务小助手设计记一笔支出的四种状态，检查金额单位、失败恢复和手机长备注。”。以随附课程正文为知识依据，采用具体、简洁的中文。当前阶段：L4.1 · UI/UX 设计。\n\n## 开始前确认\n\n已做过一个小工具；准备财务小助手练习项目。/api/summary只计算，不保存；/api/expenses是待实现的账本扩展，不把静态成功页称作已记账。\n\n先问学习者已经做到哪一步、已有何种文件或结果。已有可用成果就从断点继续。需要编程时先确认工作目录与运行方式；只读分析课不修改被分析项目。\n\n## 本课讲解顺序\n\n1. 设计从用户要完成的事开始\n2. 用信息层级降低理解成本\n3. 四种状态比四种配色更重要\n\n先讲一个本课场景，再解释图中各部分的职责和连接关系。图的文字说明：记一笔支出：金额单位明确；保存中防连点；成功提供查看账单与再记一笔；失败保留输入，长备注适应手机宽度。保存结果未知时先确认，避免重复记账。\n\n## 陪练步骤\n\n1. 为财务小助手的支出表单画出默认、提交中、成功和失败四种状态，使用餐饮25.50元示例。\n2. 将所有含糊按钮改成明确动作名称。\n3. 用键盘走完输入与提交，检查焦点顺序。\n4. 将页面缩到手机宽度，检查长备注、金额单位和错误文字是否被遮挡。\n5. 检查25.50元精确转换为2550分；保存结果未知时先查询，避免重复记账。\n\n一次推进一个可观察步骤。先请学员预测结果，再运行或推演，再比较预期与实际。遇到错误，收集完整错误、输入和复现过程；定位后继续到本步验收。先给提示，需要时再给完整实现。学习者要求直接完成时执行已明确的任务，并解释关键选择。\n\n## 验收依据\n\n- 用户不看说明也能找到记一笔入口，理解金额单位。\n- 失败后输入保留，错误消息指出可修正的位置。\n- 主任务可通过键盘完成，移动端正文和按钮可读可操作。\n- 保存成功必须对应真实服务结果；只有草图时仅按设计验收。\n\n逐项给出：要求、实际观察、通过或待修正、下一步。运行结果只能来自实际执行；若当前只有设计稿，则按设计验收，说明哪些运行检查留给实践环境。外部写入按用户授权执行。\n\n## 诊断提问与参考判断\n\n提问：把失败提示文字改成红色，是否已经足够？\n\n参考判断：还需要明确文字、相关位置和恢复方式。颜色可以辅助注意，但不能承载全部含义。\n\n先等待学习者回答再给参考判断。若回答混淆概念，使用本课案例追问，不直接重复术语。\n\n## 常见误区与纠正\n\n错误不能只靠颜色；失败保留输入；界面防连击不能替代后端幂等。\n\n## 结束交付\n\n给出本课成果位置或可复制内容、验收结果、一个需要复习的点。建议完成本课练习后在站点手动标记已学；你无法替学习者修改站点本地进度。\n" }, { "schema_version": "1.0", "id": "l4-1-04", "title": "用户旅程与信息架构", "stage": "L4.1", "language": "zh-CN", "canonical_url": "https://learn.iszhou.com/#lesson/l4-1-04", "api_url": "https://learn.iszhou.com/api/v1/lessons/l4-1-04.json", "metadata": { "id": "l4-1-04", "stage": "L4.1", "num": 4, "domain": "UI/UX 设计", "title": "用户旅程与信息架构", "desc": "从记账与回查任务推导财务小助手的页面、分类和导航结构。", "ideas": [ "User Journey：用户在使用前、中、后经历什么", "任务流程：用户完成一件事需要哪些步骤", "信息架构：内容分类、导航、页面结构与命名" ], "practice": "为财务小助手梳理消费后记账、确认保存、周末筛选与回查修改的旅程，并画记一笔、账单、汇总的页面树。", "takeaway": "用户旅程回答为什么和如何使用，信息架构回答内容放在哪里。", "minutes": 35, "full": true, "status": "complete", "illustration": { "src": "assets/course-art/l4-1-04-finance-warm-v4.webp", "alt": "财务小助手的用户旅程与页面树", "caption": "消费后记账、确认保存、周末筛选、回查修改；页面树以记一笔、账单、汇总为一级入口，详情与编辑归入账单，返回保留筛选。", "reused": false } }, "content_markdown": "# 用户旅程与信息架构\n\n> 从用户任务推导功能清单、页面层级和导航结构。\n\n## 学习起点与本课交付\n\n**开始前：** 沿用财务小助手，描述一次从消费后记账到周末查账的场景。\n\n**完成后留下：** 旅程、操作流程和页面结构三份对应说明，能找回并编辑自己的支出，返回后保留筛选条件。\n\n## 学习目标\n\n- User Journey：用户在使用前、中、后经历什么\n- 任务流程：用户完成一件事需要哪些步骤\n- 信息架构：内容分类、导航、页面结构与命名\n\n## 图解\n\n![财务小助手的用户旅程与页面树](assets/course-art/l4-1-04-finance-warm-v4.webp)\n\n
消费后记账、确认保存、周末筛选、回查修改；页面树以记一笔、账单、汇总为一级入口，详情与编辑归入账单，返回保留筛选。 点击图片可查看大图。
\n\n## 用户旅程、任务流程、信息架构各管一件事\n\n用户旅程描述一个人在使用前、中、后的目标与感受；任务流程描述完成一件事所需的操作；信息架构描述内容怎么分类、页面怎么组织。三者相关，但不能用一张页面清单替代用户的实际过程。\n\n## 从具体场景推导页面\n\n午饭后，用户想在手机上记下 25.50 元餐饮支出；保存后确认没有多记或漏记。周末想知道本周餐饮花费，再按日期和分类找到账目，发现分类有误时进入详情修改。这个场景自然产生“记一笔”“账单”“汇总”三个入口，无需先堆出十个栏目。\n\n同一条支出从创建到回查都保持稳定 ID，例如 `expense-001`。修改分类应更新这条记录，不要悄悄新增另一笔。页面展示的账本需要真实持久化能力；第 02 课的无状态汇总练习包不提供账本存储。\n\n| 阶段 | 用户问题 | 页面或能力 | 易卡住的地方 |\n|---|---|---|---|\n| 消费后 | 怎样快速记下来？ | 记一笔、金额与日期输入 | 单位不明、输入步骤太多 |\n| 保存时 | 有没有记成功或记重复？ | 保存反馈、记录 ID、确认路径 | 超时后盲目再次创建 |\n| 周末回查 | 本周餐饮花了多少？ | 账单筛选与按范围汇总 | 统计范围不清、筛选丢失 |\n| 查看详情 | 这一笔是什么？ | 金额、日期、分类、备注 | 列表与详情对不上 |\n| 修改后 | 改对了吗，能回到原位置吗？ | 同 ID 更新、返回账单 | 修改变新增、返回丢失条件 |\n\n## 分类应该贴近用户语言\n\n“账单”比“个人资金数据资产中心”更容易理解。“支出记录”和“分类”也要区分：餐饮是分类，一次午餐是记录，同一分类可以有多笔支出。分类相同、金额相同也不代表同一笔交易；重复判断应依据业务标识和服务端规则。\n\n页面层级保持浅：本练习使用“记一笔、账单、汇总”三个主要入口。账单下进入支出详情，再进入编辑；汇总明确显示日期范围、币种和分类。导航显示当前所在位置，返回后保留日期、分类和列表位置。类别可以先用固定枚举，不为教学练习增加复杂配置中心。\n\n```text\n财务小助手\n├─ 记一笔\n├─ 账单（日期 / 分类筛选）\n│ ├─ 支出详情\n│ └─ 编辑支出（从详情进入）\n└─ 汇总（展示当前统计范围）\n```\n\n先画用户操作的顺序，再画页面树：操作是时间顺序，页面树是入口与层级，二者不要混为一张菜单。\n\n## 动手练习\n\n1. 写一个用户场景，包含动机、操作和想得到的结果。\n2. 列出“消费后记账→确认保存→周末筛选→查看详情→修改”的操作步骤。\n3. 为每一步指定页面、需要的数据和成功反馈。\n4. 请同伴不看解释，寻找“修改昨天那笔餐饮支出”的入口；返回后检查原日期和分类仍在。\n\n## 验收标准\n\n- 每个主要页面都能对应一个明确任务。\n- 可以从列表进入详情，再回到原筛选状态。\n- 支出记录、分类与汇总范围在页面和数据说明中一致；修改保持同一 ID。\n\n## 自测与参考答案\n\n**问题：** 用户找不到昨天的支出，应优先改颜色还是导航结构？\n\n
展开参考答案

先检查命名和入口层级。若入口已经清楚但视觉上被淹没，再调整层级和样式。

\n\n## 本课带走\n\n先写用户做事的过程，再决定页面和菜单。\n", "agent_teaching_guide_markdown": "# AI 教学包 · 用户旅程与信息架构\n\n## 本课交付与易错点\n\n先核实起点：准备财务小助手从消费后记账到周末查账的场景描述。\n\n逐项验收：旅程、操作流程和页面结构三份对应说明，能找回并编辑自己的支出，返回保留筛选。\n\n重点纠偏：页面清单不等于用户旅程；返回后应保留筛选，命名优先贴近任务。\n\n图解用于解释关系，正文与实际工具结果用于验收；不把图中的虚构数据、示意命令或条件推演称作已经运行的结果。\n\n## 角色与任务\n\n你是本课的实践教练。目标是让学习者完成并解释“为财务小助手梳理消费后记账→确认保存→周末筛选→查看详情→修改的旅程，并画记一笔、账单、汇总的页面树。”。以随附课程正文为知识依据，采用具体、简洁的中文。当前阶段：L4.1 · UI/UX 设计。\n\n## 开始前确认\n\n已做过一个小工具；准备财务小助手练习项目。金额用虚构数据，稳定ID指向同一支出；账本持久化是扩展设计，不属于无状态汇总练习包。\n\n先问学习者已经做到哪一步、已有何种文件或结果。已有可用成果就从断点继续。需要编程时先确认工作目录与运行方式；只读分析课不修改被分析项目。\n\n## 本课讲解顺序\n\n1. 用户旅程、任务流程、信息架构各管一件事\n2. 从具体场景推导页面\n3. 分类应该贴近用户语言\n\n先讲一个本课场景，再解释图中各部分的职责和连接关系。图的文字说明：消费后记账、确认保存、周末筛选、回查修改；页面树以记一笔、账单、汇总为一级入口，详情与编辑归入账单，返回保留筛选。\n\n## 陪练步骤\n\n1. 写一个用户场景，包含动机、操作和想得到的结果。\n2. 列出“消费后记账→确认保存→周末筛选→查看详情→修改”的操作步骤。\n3. 为每一步指定页面、需要的数据和成功反馈。\n4. 请同伴不看解释，寻找“修改昨天那笔餐饮支出”的入口；返回检查原筛选条件。\n\n一次推进一个可观察步骤。先请学员预测结果，再运行或推演，再比较预期与实际。遇到错误，收集完整错误、输入和复现过程；定位后继续到本步验收。先给提示，需要时再给完整实现。学习者要求直接完成时执行已明确的任务，并解释关键选择。\n\n## 验收依据\n\n- 每个主要页面都能对应一个明确任务。\n- 可以从列表进入详情，再回到原筛选状态。\n- 支出、分类与汇总范围说明一致；修改保持同一记录ID，不意外新增。\n\n逐项给出：要求、实际观察、通过或待修正、下一步。运行结果只能来自实际执行；若当前只有设计稿，则按设计验收，说明哪些运行检查留给实践环境。外部写入按用户授权执行。\n\n## 诊断提问与参考判断\n\n提问：用户找不到昨天的支出，应优先改颜色还是导航结构？\n\n参考判断：先检查命名和入口层级。若入口已经清楚但视觉上被淹没，再调整层级和样式。\n\n先等待学习者回答再给参考判断。若回答混淆概念，使用本课案例追问，不直接重复术语。\n\n## 常见误区与纠正\n\n页面清单不等于用户旅程；返回后应保留筛选，命名优先贴近任务。\n\n## 结束交付\n\n给出本课成果位置或可复制内容、验收结果、一个需要复习的点。建议完成本课练习后在站点手动标记已学；你无法替学习者修改站点本地进度。\n" }, { "schema_version": "1.0", "id": "l4-1-05", "title": "Figma 原型设计", "stage": "L4.1", "language": "zh-CN", "canonical_url": "https://learn.iszhou.com/#lesson/l4-1-05", "api_url": "https://learn.iszhou.com/api/v1/lessons/l4-1-05.json", "metadata": { "id": "l4-1-05", "stage": "L4.1", "num": 5, "domain": "UI/UX 设计", "title": "Figma 原型设计", "desc": "用Figma走通财务小助手的记账路径，交接组件、状态、字段与API规则。", "ideas": [ "Frame 与 Auto Layout：布局和响应式基础", "Component：统一按钮、输入框等重复元素", "Prototype：页面跳转与操作演示" ], "practice": "完成财务小助手账单页、支出表单和结果状态的可点击原型，交接字段规则与API边界。", "takeaway": "原型的目的，是在写代码前发现交互问题。", "minutes": 40, "full": true, "status": "complete", "illustration": { "src": "assets/course-art/l4-1-05-finance-warm-v4.webp", "alt": "财务小助手的 Figma 原型与交接", "caption": "账单、支出表单与结果状态串成可点击流程；复用组件并适应长备注，交接25.50元到2550分的转换及待实现的账本接口。原型不代表已经保存账目。", "reused": false } }, "content_markdown": "# Figma 原型设计\n\n> 用 Figma 把信息结构变成可讨论、可试用的界面原型。\n\n## 学习起点与本课交付\n\n**开始前：** 有 L4-1-04 财务小助手的流程与页面清单，具备可编辑的 Figma 文件。\n\n**完成后留下：** 桌面与手机原型、按钮组件、成功与错误路径、字段和状态交接说明。\n\n## 学习目标\n\n- Frame 与 Auto Layout：布局和响应式基础\n- Component：统一按钮、输入框等重复元素\n- Prototype：页面跳转与操作演示\n\n## 图解\n\n![财务小助手的 Figma 原型与交接](assets/course-art/l4-1-05-finance-warm-v4.webp)\n\n
账单、支出表单与结果状态串成可点击流程；复用组件并适应长备注，交接25.50元到2550分的转换及待实现的账本接口。原型不代表已经保存账目。 点击图片可查看大图。
\n\n## 原型用来提前发现交互问题\n\nFigma 原型可以在还没有真实后端时演示页面和操作。它帮助讨论布局、状态与流程，不会自动实现业务数据保存。本课沿用财务小助手：原型里点“保存支出”跳到成功页，只表示你设计了这段交互，不代表已入账，更不涉及真实付款。\n\n## 三个基础概念\n\nFrame 可以理解为承载界面的画框；Auto Layout 根据方向、间距、内边距与对齐组织内容；Component 把按钮、卡片等重复结构做成可复用组件。先用少量组件保持一致，避免每个页面都单独画一套按钮。\n\n例如一张支出卡片，备注可能从“午餐”变成一段较长的说明。用自动布局让卡片随内容增长，金额、分类和编辑按钮仍在合理位置；用固定坐标拼装时，长备注容易覆盖金额或按钮。金额标明元，保留两位小数，不为了对齐而截断数值。\n\n## 做三个页面，连一条完整路径\n\n| 页面 | 必须呈现 | 点击后的去向 |\n|---|---|---|\n| 账单列表 | 支出卡片、日期/分类筛选、记一笔入口 | 详情或录入页 |\n| 支出表单 | 金额（元）、日期、分类、备注、字段错误 | 成功或留在错误状态 |\n| 保存成功 | 记录 ID、金额、查看账单 / 再记一笔 | 账单或录入页 |\n\n先用灰阶完成布局，再统一色彩与字体。用相同的按钮组件表示主操作，分别设计正常、禁用和加载状态。Prototype 连线时检查回程：用户能不能取消，成功后能不能继续下一项任务。\n\n## 交给开发者的内容\n\n除了页面截图，还应给出文字规范：字段长度、必填规则、加载状态、错误状态、移动端排列。再说明哪些行为只是演示，哪些需要真实 API。这样 AI 实现时不会把所有成功页面做成无条件跳转。\n\n| 界面字段 / 状态 | 交接规则 | 对应实现（设计，待开发） |\n|---|---|---|\n| 金额（元） | 必填、正数、最多两位小数；25.50 元 | 精确转换为 amount_minor=2550 分，服务端再验证 |\n| 日期 | 必填，有效日期 | date，格式 YYYY-MM-DD |\n| 分类 | 必填，限定枚举 | category，如餐饮；未知值拒绝 |\n| 备注 | 选填，最多200字，长文本换行 | note |\n| 保存中 / 成功 | 防连点；收到成功结果后展示记录 ID | POST /api/expenses；201 后回读核对 |\n| 结果未知 | 保留输入，先查是否已创建 | 按服务支持的业务标识确认，避免重复记账 |\n\n这份 `/api/expenses` 是第 02 课的账本扩展契约，下载的 `/api/summary` 练习服务不实现保存。给 AI 或开发者时，应把这一边界一并交接。\n\n## 动手练习\n\n1. 创建桌面与手机两个 Frame，放入同样的“记一笔支出”表单，示例为餐饮 25.50 元。\n2. 用 Auto Layout 排列标签、输入和按钮，制作按钮组件。\n3. 连接账单、支出表单、成功页，并增加金额为空的错误状态及返回修改路径。\n4. 用长备注、金额错误和手机宽度测试布局，请同伴走完流程；加入回到账单后筛选保留的说明。\n5. 标注金额单位转换、API 成功与超时的处理，区分原型演示和待实现能力。\n\n## 验收标准\n\n- 三个页面连得起来，取消与返回路径明确。\n- 长文本不覆盖其他控件，手机布局可读。\n- 开发说明包括字段规则和状态，原型演示与真实功能区分清楚。\n\n## 自测与参考答案\n\n**问题：** 原型里点击“保存支出”出现新账目，能否证明数据已进入数据库？\n\n
展开参考答案

不能。原型演示的是预设交互；真实保存要在实现后检查接口结果与数据库记录。

\n\n## 延伸阅读\n\n[Figma 官方：Auto Layout 指南](https://help.figma.com/hc/en-us/articles/360040451373-Guide-to-auto-layout-in-Figma)\n\n## 本课带走\n\n用可点击的路径讨论体验，用明确的规则交接实现。\n", "agent_teaching_guide_markdown": "# AI 教学包 · Figma 原型设计\n\n## 本课交付与易错点\n\n先核实起点：有 L4-1-04 财务小助手的流程与页面清单，具备可编辑的 Figma 文件。\n\n逐项验收：桌面与手机原型、按钮组件、成功与错误路径、字段和状态交接说明。\n\n重点纠偏：原型跳到成功页不证明已入账；长备注必须实际检验布局；金额元与分的映射需要交接。\n\n图解用于解释关系，正文与实际工具结果用于验收；不把图中的虚构数据、示意命令或条件推演称作已经运行的结果。\n\n## 角色与任务\n\n你是本课的实践教练。目标是让学习者完成并解释“完成财务小助手账单页、记一笔表单与结果状态，连接可点击流程，并交接字段与API规则。”。以随附课程正文为知识依据，采用具体、简洁的中文。当前阶段：L4.1 · UI/UX 设计。\n\n## 开始前确认\n\n已做过一个小工具；准备财务小助手练习项目。/api/expenses为待实现的账本扩展，/api/summary下载练习包只做计算。\n\n先问学习者已经做到哪一步、已有何种文件或结果。已有可用成果就从断点继续。需要编程时先确认工作目录与运行方式；只读分析课不修改被分析项目。\n\n## 本课讲解顺序\n\n1. 原型用来提前发现交互问题\n2. 三个基础概念\n3. 做三个页面，连一条完整路径\n4. 交给开发者的内容\n\n先讲一个本课场景，再解释图中各部分的职责和连接关系。图的文字说明：账单、支出表单与结果状态串成可点击流程；复用组件并适应长备注，交接25.50元到2550分的转换及待实现的账本接口。原型不代表已经保存账目。\n\n## 陪练步骤\n\n1. 创建桌面与手机两个 Frame，放入同样的支出表单，使用餐饮25.50元示例。\n2. 用 Auto Layout 排列标签、输入和按钮，制作按钮组件。\n3. 连接账单、录入表单、成功页，并增加金额为空的错误状态与返回修改路径。\n4. 用长备注和手机宽度测试布局，请同伴走完流程。\n5. 标注25.50元到2550分的精确转换、日期、分类、200字备注限制；API收到201后回读核对，超时先确认结果。\n\n一次推进一个可观察步骤。先请学员预测结果，再运行或推演，再比较预期与实际。遇到错误，收集完整错误、输入和复现过程；定位后继续到本步验收。先给提示，需要时再给完整实现。学习者要求直接完成时执行已明确的任务，并解释关键选择。\n\n## 验收依据\n\n- 三个页面连得起来，取消与返回路径明确。\n- 长文本不覆盖其他控件，手机布局可读。\n- 开发说明包括字段规则和状态，原型演示与真实功能区分清楚。\n\n逐项给出：要求、实际观察、通过或待修正、下一步。运行结果只能来自实际执行；若当前只有设计稿，则按设计验收，说明哪些运行检查留给实践环境。外部写入按用户授权执行。\n\n## 诊断提问与参考判断\n\n提问：原型里点击“保存支出”出现新账目，能否证明数据已进入数据库？\n\n参考判断：不能。原型演示的是预设交互；真实保存要在实现后检查接口结果与数据库记录。\n\n先等待学习者回答再给参考判断。若回答混淆概念，使用本课案例追问，不直接重复术语。\n\n## 常见误区与纠正\n\n原型跳到成功页不证明已入账；长备注必须实际检验布局；金额元与分的映射需要交接。\n\n## 结束交付\n\n给出本课成果位置或可复制内容、验收结果、一个需要复习的点。建议完成本课练习后在站点手动标记已学；你无法替学习者修改站点本地进度。\n" }, { "schema_version": "1.0", "id": "l4-1-06", "title": "人机双入口设计", "stage": "L4.1", "language": "zh-CN", "canonical_url": "https://learn.iszhou.com/#lesson/l4-1-06", "api_url": "https://learn.iszhou.com/api/v1/lessons/l4-1-06.json", "metadata": { "id": "l4-1-06", "stage": "L4.1", "num": 6, "domain": "AI 友好接口", "title": "人机双入口设计", "desc": "让网页操作和 Agent 调用在相同权限与业务规则下工作。", "ideas": [ "人类入口：Web UI 负责呈现与交互", "Agent 入口：API 或工具暴露清晰动作", "共享业务：操作约束和状态变更应复用同一能力" ], "practice": "列出书单系统的浏览、发布、修改、删除四个动作，设计 UI 与 API 的映射关系。", "takeaway": "入口可以不同，业务规则和数据语义应该一致。", "minutes": 35, "full": true, "status": "complete", "illustration": { "src": "assets/course-art/l4-1-06-warm-v3.webp", "alt": "人机共用同一业务服务", "caption": "网页和工具均经身份与权限校验、共享业务服务后访问数据；Agent 先将记录从版本 3 更新到 4，人的旧版本提交随后得到 409，需刷新后合并。", "reused": false } }, "content_markdown": "# 人机双入口设计\n\n> 让网页操作和 Agent 调用在相同权限与业务规则下工作。\n\n## 学习起点与本课交付\n\n**开始前：** 有一条可创建、读取的练习记录，理解 HTTP 与服务端规则。\n\n**完成后留下：** 网页和工具共用同一 ID、规则与权限的验证，并展示一次旧版本冲突。\n\n## 学习目标\n\n- 人类入口：Web UI 负责呈现与交互\n- Agent 入口：API 或工具暴露清晰动作\n- 共享业务：操作约束和状态变更应复用同一能力\n\n## 图解\n\n![人机共用同一业务服务](assets/course-art/l4-1-06-warm-v3.webp)\n\n
网页和工具均经身份与权限校验、共享业务服务后访问数据；Agent 先将记录从版本 3 更新到 4，人的旧版本提交随后得到 409，需刷新后合并。 点击图片可查看大图。
\n\n## 两种入口，共用一套业务能力\n\n人通过表单操作，Agent 通过工具操作，最终应使用相同的业务规则。网页负责组织输入和反馈；Agent 负责把自然语言目标变成明确动作；服务负责校验、授权、保存和返回结果。\n\n## 对齐动作与语义\n\n| 用户动作 | 网页入口 | Agent 工具 | 服务规则 |\n|---|---|---|---|\n| 找推荐 | 搜索框 | list_books | 相同筛选与可见范围 |\n| 发布 | 发布表单 | create_share | 同一必填规则 |\n| 改笔记 | 编辑按钮 | update_share | 只能改有权限的分享 |\n| 删除 | 删除确认 | delete_share | 同一归属与审计规则 |\n\n不要让网页直接改数据库，而 Agent 调另一套脚本；那样即使字段相同，权限、校验和日志也可能不同。先抽出一个服务函数，再让各入口调用它，是很实用的起点。\n\n## 并发修改：谁覆盖了谁\n\n人打开版本 3 的笔记，同时 Agent 更新到版本 4。人再提交旧页面时，如果服务无条件接受，Agent 的修改就会被覆盖。给请求附带预期版本号，服务只在版本匹配时更新；不匹配时返回冲突，让调用者读最新内容再决定合并。\n\n这里的版本号属于业务记录，并非 Git 提交号。它解决同一条内容的并发编辑；Git 解决代码和文件版本，两者层次不同。\n\n## 从输入到结果的一致性\n\n网页发布失败时不能先显示“已完成”；Agent 收到任务 ID 时也不能把“已受理”说成“已完成”。两个入口都应根据实际业务状态呈现结果。服务返回记录 ID、版本和操作时间，便于相互核对。\n\n## 动手练习\n\n1. 为书单的四个动作填写上表，补齐输入和输出字段。\n2. 网页发布一条分享，再用 API 读取相同记录。\n3. 用 API 修改笔记，刷新网页确认同一 ID 的内容已变化。\n4. 用旧版本号提交更新，检查服务是否拒绝覆盖。\n\n## 验收标准\n\n- 两个入口看到同一条记录与版本。\n- 无权限操作在两种入口均被拒绝。\n- 并发编辑有明确冲突结果，旧内容不会无提示覆盖新内容。\n\n## 自测与参考答案\n\n**问题：** Agent 能调用 API，就算完成了人机双入口吗？\n\n
展开参考答案

还要确认它与网页共享业务语义、权限和数据。仅仅多开放一个独立接口，可能造成两套不一致的行为。

\n\n## 本课带走\n\n共同的数据只是基础，共同的规则与状态才让人机协作可预期。\n", "agent_teaching_guide_markdown": "# AI 教学包 · 人机双入口设计\n\n## 本课交付与易错点\n\n先核实起点：有一条可创建、读取的练习记录，理解 HTTP 与服务端规则。\n\n逐项验收：网页和工具共用同一 ID、规则与权限的验证，并展示一次旧版本冲突。\n\n重点纠偏：两个入口都经过认证与业务服务；记录版本号和 Git 提交号不是同一个概念。\n\n图解用于解释关系，正文与实际工具结果用于验收；不把图中的虚构数据、示意命令或条件推演称作已经运行的结果。\n\n## 角色与任务\n\n你是本课的实践教练。目标是让学习者完成并解释“列出书单系统的浏览、发布、修改、删除四个动作，设计 UI 与 API 的映射关系。”。以随附课程正文为知识依据，采用具体、简洁的中文。当前阶段：L4.1 · AI 友好接口。\n\n## 开始前确认\n\n已做过一个小工具；准备好书分享或财务助手练习项目。\n\n先问学习者已经做到哪一步、已有何种文件或结果。已有可用成果就从断点继续。需要编程时先确认工作目录与运行方式；只读分析课不修改被分析项目。\n\n## 本课讲解顺序\n\n1. 两种入口，共用一套业务能力\n2. 对齐动作与语义\n3. 并发修改：谁覆盖了谁\n4. 从输入到结果的一致性\n\n先讲一个本课场景，再解释图中各部分的职责和连接关系。图的文字说明：网页和工具均经身份与权限校验、共享业务服务后访问数据；Agent 先将记录从版本 3 更新到 4，人的旧版本提交随后得到 409，需刷新后合并。\n\n## 陪练步骤\n\n1. 为书单的四个动作填写上表，补齐输入和输出字段。\n2. 网页发布一条分享，再用 API 读取相同记录。\n3. 用 API 修改笔记，刷新网页确认同一 ID 的内容已变化。\n4. 用旧版本号提交更新，检查服务是否拒绝覆盖。\n\n一次推进一个可观察步骤。先请学员预测结果，再运行或推演，再比较预期与实际。遇到错误，收集完整错误、输入和复现过程；定位后继续到本步验收。先给提示，需要时再给完整实现。学习者要求直接完成时执行已明确的任务，并解释关键选择。\n\n## 验收依据\n\n- 两个入口看到同一条记录与版本。\n- 无权限操作在两种入口均被拒绝。\n- 并发编辑有明确冲突结果，旧内容不会无提示覆盖新内容。\n\n逐项给出：要求、实际观察、通过或待修正、下一步。运行结果只能来自实际执行；若当前只有设计稿，则按设计验收，说明哪些运行检查留给实践环境。外部写入按用户授权执行。\n\n## 诊断提问与参考判断\n\n提问：Agent 能调用 API，就算完成了人机双入口吗？\n\n参考判断：还要确认它与网页共享业务语义、权限和数据。仅仅多开放一个独立接口，可能造成两套不一致的行为。\n\n先等待学习者回答再给参考判断。若回答混淆概念，使用本课案例追问，不直接重复术语。\n\n## 常见误区与纠正\n\n两个入口都经过认证与业务服务；记录版本号和 Git 提交号不是同一个概念。\n\n## 结束交付\n\n给出本课成果位置或可复制内容、验收结果、一个需要复习的点。建议完成本课练习后在站点手动标记已学；你无法替学习者修改站点本地进度。\n" }, { "schema_version": "1.0", "id": "l4-1-07", "title": "AI 能力与接口封装", "stage": "L4.1", "language": "zh-CN", "canonical_url": "https://learn.iszhou.com/#lesson/l4-1-07", "api_url": "https://learn.iszhou.com/api/v1/lessons/l4-1-07.json", "metadata": { "id": "l4-1-07", "stage": "L4.1", "num": 7, "domain": "AI 友好接口", "title": "AI 能力与接口封装", "desc": "把系统能力逐步封装为 AI 能稳定调用的工具。", "ideas": [ "CLI：稳定输入输出的命令入口", "API：跨进程或跨设备提供功能调用", "Skill / MCP：告诉 Agent 何时调用和如何发现能力" ], "practice": "为查询书单设计一条 CLI 命令、一个 API 示例和一份简短 Skill 用法。", "takeaway": "封装的目标是复用同一能力，而不是重复编写同一套逻辑。", "minutes": 45, "full": true, "status": "complete", "illustration": { "src": "assets/course-art/l4-1-07-warm-v3.webp", "alt": "AI 能力与接口封装：CLI、HTTP API 和 MCP 共用同一业务服务", "caption": "Skill 说明何时用、怎样用；Agent 按任务选择 CLI、HTTP API 或 MCP 工具，复用同一业务逻辑。入口提供稳定的参数、结果、分页与错误契约，并执行权限检查；这些入口不必串成固定链路。", "reused": false } }, "content_markdown": "# AI 能力与接口封装\n\n> 把系统能力逐步封装为 AI 能稳定调用的工具。\n\n## 学习起点与本课交付\n\n**开始前：** 已有可复用查询函数；先选择必要入口，不要求 CLI、HTTP、MCP 全部同时实现。\n\n**完成后留下：** 稳定 JSON 的 CLI、复用同一查询逻辑的 API，以及分页、空结果和错误验证。\n\n## 学习目标\n\n- CLI：稳定输入输出的命令入口\n- API：跨进程或跨设备提供功能调用\n- Skill / MCP：告诉 Agent 何时调用和如何发现能力\n\n## 图解\n\n![AI 能力与接口封装：CLI、HTTP API 和 MCP 共用同一业务服务](assets/course-art/l4-1-07-warm-v3.webp)\n\n
Skill 说明何时用、怎样用；Agent 按任务选择 CLI、HTTP API 或 MCP 工具，复用同一业务逻辑。入口提供稳定的参数、结果、分页与错误契约，并执行权限检查；这些入口不必串成固定链路。 点击图片可查看大图。
\n\n## 封装是把能力变成稳定契约\n\n同一个“查询书单”能力，可以有 CLI、HTTP API 和 MCP 工具等入口。Skill 告诉 Agent 何时用、怎样用；CLI 把命令参数变成调用；API 接受跨进程请求；业务服务真正执行查询。是否需要每一层，取决于使用场景。\n\nCLI 是命令行接口，既可以操作本地文件，也可以请求远程 API。API 也可以部署在本机。不能用“CLI 等于本地、API 等于云端”作为定义。\n\n## 给工具设计可预测的输入输出\n\n下面是练习工具的目标接口，须先实现后使用：\n\n```bash\nbooks list --tag systems --limit 10 --format json\n```\n\n```json\n{\"items\":[{\"id\":\"b-001\",\"title\":\"系统之美\"}],\"next_cursor\":null}\n```\n\n正常结果写到标准输出，诊断信息写到标准错误；成功退出码为 0，失败使用非零值。JSON 字段保持稳定，避免有时输出表格、有时输出一段口语，让调用者难以解析。\n\n## 一份足够短的 Skill\n\n```text\n用途：查询好书分享中的推荐。\n先确认筛选条件；使用 books list，输出格式选 JSON。\n读取 items 和 next_cursor；需要完整结果时继续分页。\n无结果时说明查询条件，不虚构书名。\n查询不包含发布、修改和删除操作。\n```\n\nMCP 可以进一步提供工具发现和调用方式。工具名称与参数要反映业务动作，例如 `update_share_note` 比 `run_any_sql` 更易理解和控制。把整个数据库任意操作暴露出来，会让调用者承担过多规则。\n\n## 动手练习\n\n1. 将现有查询函数封装为上述 CLI，支持 JSON 输出。\n2. 用同一个服务函数提供 `GET /api/books`。\n3. 编写 Skill，给 Agent 一个有结果和一个无结果的查询。\n4. 让结果超过一页，验证它会处理分页而不是只报告第一页。\n\n## 验收标准\n\n- CLI 和 API 返回相同筛选下的一致记录。\n- 参数非法时返回可定位的错误，CLI 退出码非零。\n- Skill 说明与实际命令一致，没有重复实现查询逻辑。\n\n## 自测与参考答案\n\n**问题：** 一个 CLI 调用了远程 API，它还算 CLI 吗？\n\n
展开参考答案

算。CLI 描述的是调用入口形式，远程或本地描述的是实际执行位置，两者是不同维度。

\n\n## 延伸阅读\n\n[MCP 官方：工具、资源与提示](https://py.sdk.modelcontextprotocol.io/get-started/first-steps/)\n\n## 本课带走\n\n先把业务能力做稳定，再为不同调用者提供合适入口。\n", "agent_teaching_guide_markdown": "# AI 教学包 · AI 能力与接口封装\n\n## 本课交付与易错点\n\n先核实起点：已有可复用查询函数；先选择必要入口，不要求 CLI、HTTP、MCP 全部同时实现。\n\n逐项验收：稳定 JSON 的 CLI、复用同一查询逻辑的 API，以及分页、空结果和错误验证。\n\n重点纠偏：CLI 可以调用远程 API；Skill 是说明，MCP 是接入协议，不是固定串行链的每一站。\n\n图解用于解释关系，正文与实际工具结果用于验收；不把图中的虚构数据、示意命令或条件推演称作已经运行的结果。\n\n## 角色与任务\n\n你是本课的实践教练。目标是让学习者完成并解释“为查询书单设计一条 CLI 命令、一个 API 示例和一份简短 Skill 用法。”。以随附课程正文为知识依据，采用具体、简洁的中文。当前阶段：L4.1 · AI 友好接口。\n\n## 开始前确认\n\n已做过一个小工具；准备好书分享或财务助手练习项目。\n\n先问学习者已经做到哪一步、已有何种文件或结果。已有可用成果就从断点继续。需要编程时先确认工作目录与运行方式；只读分析课不修改被分析项目。\n\n## 本课讲解顺序\n\n1. 封装是把能力变成稳定契约\n2. 给工具设计可预测的输入输出\n3. 一份足够短的 Skill\n\n先讲一个本课场景，再解释图中各部分的职责和连接关系。图的文字说明：Skill 说明何时用、怎样用；Agent 按任务选择 CLI、HTTP API 或 MCP 工具，复用同一业务逻辑。这些入口不必串成固定链路；CLI 和 API 都可连接本地或远程服务。结合查书单示例解释参数校验、权限检查、结构化输出、分页和明确错误；凭据由受控存储与权限机制保护。\n\n## 陪练步骤\n\n1. 将现有查询函数封装为上述 CLI，支持 JSON 输出。\n2. 用同一个服务函数提供 `GET /api/books`。\n3. 编写 Skill，给 Agent 一个有结果和一个无结果的查询。\n4. 让结果超过一页，验证它会处理分页而不是只报告第一页。\n\n一次推进一个可观察步骤。先请学员预测结果，再运行或推演，再比较预期与实际。遇到错误，收集完整错误、输入和复现过程；定位后继续到本步验收。先给提示，需要时再给完整实现。学习者要求直接完成时执行已明确的任务，并解释关键选择。\n\n## 验收依据\n\n- CLI 和 API 返回相同筛选下的一致记录。\n- 参数非法时返回可定位的错误，CLI 退出码非零。\n- Skill 说明与实际命令一致，没有重复实现查询逻辑。\n\n逐项给出：要求、实际观察、通过或待修正、下一步。运行结果只能来自实际执行；若当前只有设计稿，则按设计验收，说明哪些运行检查留给实践环境。外部写入按用户授权执行。\n\n## 诊断提问与参考判断\n\n提问：一个 CLI 调用了远程 API，它还算 CLI 吗？\n\n参考判断：算。CLI 描述的是调用入口形式，远程或本地描述的是实际执行位置，两者是不同维度。\n\n先等待学习者回答再给参考判断。若回答混淆概念，使用本课案例追问，不直接重复术语。\n\n## 常见误区与纠正\n\nCLI 可以调用远程 API；Skill 是说明，MCP 是接入协议，不是固定串行链的每一站。\n\n## 结束交付\n\n给出本课成果位置或可复制内容、验收结果、一个需要复习的点。建议完成本课练习后在站点手动标记已学；你无法替学习者修改站点本地进度。\n" }, { "schema_version": "1.0", "id": "l4-1-08", "title": "IAM 与权限管理", "stage": "L4.1", "language": "zh-CN", "canonical_url": "https://learn.iszhou.com/#lesson/l4-1-08", "api_url": "https://learn.iszhou.com/api/v1/lessons/l4-1-08.json", "metadata": { "id": "l4-1-08", "stage": "L4.1", "num": 8, "domain": "身份与权限", "title": "IAM 与权限管理", "desc": "区分身份认证与权限控制，并处理人和 Agent 的访问边界。", "ideas": [ "Authentication：请求来自谁，凭证怎么验证", "Authorization：谁能读、写、删哪些资源", "Token 与审计：最小权限、撤销、操作记录" ], "practice": "为好书分享定义查看者与维护者权限，并测试无凭证和无权限两种场景。", "takeaway": "有 API 就需要明确谁能够调用什么操作。", "minutes": 35, "full": true, "status": "complete", "illustration": { "src": "assets/course-art/l4-1-08-warm-v3.webp", "alt": "授权要落实到每次操作", "caption": "认证身份：验证凭证，取得可信主体；检查权限：动作范围 + 对象归属；允许执行：共享业务服务处理；拒绝与审计：返回原因，记录请求 ID。", "reused": false } }, "content_markdown": "# IAM 与权限管理\n\n> 区分身份认证与权限控制，并处理人和 Agent 的访问边界。\n\n## 学习起点与本课交付\n\n**开始前：** 有测试服务与两位虚构用户，使用可撤销的练习凭证。\n\n**完成后留下：** 权限矩阵、四类服务端拒绝记录、撤销后失效验证和不含密钥的审计。\n\n## 学习目标\n\n- Authentication：请求来自谁，凭证怎么验证\n- Authorization：谁能读、写、删哪些资源\n- Token 与审计：最小权限、撤销、操作记录\n\n## 图解\n\n![授权要落实到每次操作](assets/course-art/l4-1-08-warm-v3.webp)\n\n
认证身份：验证凭证，取得可信主体；检查权限：动作范围 + 对象归属；允许执行：共享业务服务处理；拒绝与审计：返回原因，记录请求 ID。 点击图片可查看大图。
\n\n## 认证回答“你是谁”，授权回答“你能做什么”\n\nAuthentication 验证身份，Authorization 检查权限。一个用户成功登录，并不代表能修改所有人的记录。IAM 是围绕身份和访问的管理：身份如何创建、权限如何授予、凭证如何撤销、操作如何追溯。\n\n身份校验应发生在受信任的服务端。隐藏按钮只是界面行为，调用者仍可能直接发送请求。网页和 Agent 请求都必须经过相应校验，再进入共享业务服务。\n\n## 先写权限矩阵，再写判断代码\n\n| 身份 | 看公开推荐 | 新建分享 | 改自己的分享 | 改他人的分享 |\n|---|---|---|---|---|\n| 未登录访客 | 允许 | 拒绝 | 拒绝 | 拒绝 |\n| 成员 | 允许 | 允许 | 允许 | 拒绝 |\n| 管理员 | 允许 | 允许 | 允许 | 按管理职责允许 |\n| 只读 Agent | 按授权范围 | 拒绝 | 拒绝 | 拒绝 |\n\n角色只是粗粒度分类，还要检查对象归属。`member` 角色能修改自己的分享，不是所有成员的分享。服务从已验证身份中得到用户 ID，不能信任请求正文里自行填写的 `owner_id`。\n\n## Token 是凭证，不是身份说明书\n\nBearer Token 的持有者可在授权范围内使用它，应通过受保护的渠道传递。浏览器公开下载的源码、普通课件和代码仓库不适合保存长期服务密钥。给 Agent 的凭证应有明确范围、有效期和撤销方式。\n\n若 Agent 代表用户操作，日志同时记录用户身份与执行主体。一个实用审计记录包括请求 ID、主体、动作、资源、时间和结果，不记录令牌正文。它帮助回答“谁在什么授权下改了哪条记录”。\n\n## 动手练习\n\n1. 实现成员只能编辑本人分享的规则。\n2. 建两个虚构成员 A、B 和一个只读 Agent。\n3. 分别测试无凭证、错误凭证、只读凭证、A 修改 B 的记录。\n4. 撤销 Agent 凭证，确认后续请求失效，已有记录仍完整。\n\n## 验收标准\n\n- 四类拒绝场景均在服务端生效。\n- 修改资源 ID 或正文 owner_id 不能绕过归属检查。\n- 有可追溯日志，日志和前端不包含长期密钥。\n\n## 自测与参考答案\n\n**问题：** 页面隐藏了删除按钮，API 是否还需要检查删除权限？\n\n
展开参考答案

需要。网页不是唯一调用者，按钮隐藏无法阻止直接请求；服务端必须对每次删除验证主体与资源权限。

\n\n## 本课带走\n\n以服务端身份和业务对象为依据授权，让每次操作都能追溯和撤销访问。\n", "agent_teaching_guide_markdown": "# AI 教学包 · IAM 与权限管理\n\n## 本课交付与易错点\n\n先核实起点：有测试服务与两位虚构用户，使用可撤销的练习凭证。\n\n逐项验收：权限矩阵、四类服务端拒绝记录、撤销后失效验证和不含密钥的审计。\n\n重点纠偏：隐藏按钮不能授权；身份、动作、对象归属和凭证范围必须同时满足。\n\n图解用于解释关系，正文与实际工具结果用于验收；不把图中的虚构数据、示意命令或条件推演称作已经运行的结果。\n\n## 角色与任务\n\n你是本课的实践教练。目标是让学习者完成并解释“为好书分享定义查看者与维护者权限，并测试无凭证和无权限两种场景。”。以随附课程正文为知识依据，采用具体、简洁的中文。当前阶段：L4.1 · 身份与权限。\n\n## 开始前确认\n\n已做过一个小工具；准备好书分享或财务助手练习项目。\n\n先问学习者已经做到哪一步、已有何种文件或结果。已有可用成果就从断点继续。需要编程时先确认工作目录与运行方式；只读分析课不修改被分析项目。\n\n## 本课讲解顺序\n\n1. 认证回答“你是谁”，授权回答“你能做什么”\n2. 先写权限矩阵，再写判断代码\n3. Token 是凭证，不是身份说明书\n\n先讲一个本课场景，再解释图中各部分的职责和连接关系。图的文字说明：认证身份：验证凭证，取得可信主体；检查权限：动作范围 + 对象归属；允许执行：共享业务服务处理；拒绝与审计：返回原因，记录请求 ID。\n\n## 陪练步骤\n\n1. 实现成员只能编辑本人分享的规则。\n2. 建两个虚构成员 A、B 和一个只读 Agent。\n3. 分别测试无凭证、错误凭证、只读凭证、A 修改 B 的记录。\n4. 撤销 Agent 凭证，确认后续请求失效，已有记录仍完整。\n\n一次推进一个可观察步骤。先请学员预测结果，再运行或推演，再比较预期与实际。遇到错误，收集完整错误、输入和复现过程；定位后继续到本步验收。先给提示，需要时再给完整实现。学习者要求直接完成时执行已明确的任务，并解释关键选择。\n\n## 验收依据\n\n- 四类拒绝场景均在服务端生效。\n- 修改资源 ID 或正文 owner_id 不能绕过归属检查。\n- 有可追溯日志，日志和前端不包含长期密钥。\n\n逐项给出：要求、实际观察、通过或待修正、下一步。运行结果只能来自实际执行；若当前只有设计稿，则按设计验收，说明哪些运行检查留给实践环境。外部写入按用户授权执行。\n\n## 诊断提问与参考判断\n\n提问：页面隐藏了删除按钮，API 是否还需要检查删除权限？\n\n参考判断：需要。网页不是唯一调用者，按钮隐藏无法阻止直接请求；服务端必须对每次删除验证主体与资源权限。\n\n先等待学习者回答再给参考判断。若回答混淆概念，使用本课案例追问，不直接重复术语。\n\n## 常见误区与纠正\n\n隐藏按钮不能授权；身份、动作、对象归属和凭证范围必须同时满足。\n\n## 结束交付\n\n给出本课成果位置或可复制内容、验收结果、一个需要复习的点。建议完成本课练习后在站点手动标记已学；你无法替学习者修改站点本地进度。\n" }, { "schema_version": "1.0", "id": "l4-1-09", "title": "云计算与 MaaS", "stage": "L4.1", "language": "zh-CN", "canonical_url": "https://learn.iszhou.com/#lesson/l4-1-09", "api_url": "https://learn.iszhou.com/api/v1/lessons/l4-1-09.json", "metadata": { "id": "l4-1-09", "stage": "L4.1", "num": 9, "domain": "云计算与 AI 基础设施", "title": "云计算与 MaaS", "desc": "把算力、存储和模型理解为可按需使用的服务。", "ideas": [ "IaaS/PaaS/SaaS：服务商与使用者的职责边界", "云资源：计算、网络、存储和弹性", "MaaS：通过模型 API 使用推理能力并管理用量" ], "practice": "将一个 AI 应用需要的服务器、数据库和模型推理分别匹配到对应服务模式。", "takeaway": "先理解哪些能力可以购买为服务，再决定哪些需要自己维护。", "minutes": 35, "full": true, "status": "complete", "illustration": { "src": "assets/course-art/l4-1-09-warm-v3.webp", "alt": "云资源与应用职责", "caption": "运行资源：计算、网络、运行时；数据服务：数据库、文件、备份；应用业务：网页、接口、规则；模型推理：按需调用，独立计量。", "reused": false } }, "content_markdown": "# 云计算与 MaaS\n\n> 把算力、存储和模型理解为可按需使用的服务。\n\n## 学习起点与本课交付\n\n**开始前：** 区分网页、业务接口、数据、模型推理；本课使用明确标注的虚构单价。\n\n**完成后留下：** 责任分工与费用表，算出单次 0.035、30 天基础用量 1050，并计入重试上限。\n\n## 学习目标\n\n- IaaS/PaaS/SaaS：服务商与使用者的职责边界\n- 云资源：计算、网络、存储和弹性\n- MaaS：通过模型 API 使用推理能力并管理用量\n\n## 图解\n\n![云资源与应用职责](assets/course-art/l4-1-09-warm-v3.webp)\n\n
运行资源：计算、网络、运行时；数据服务：数据库、文件、备份；应用业务：网页、接口、规则；模型推理：按需调用，独立计量。 点击图片可查看大图。
\n\n## 云服务首先改变的是维护责任\n\nIaaS 提供计算、网络和存储等基础资源；PaaS 进一步托管运行平台；SaaS 提供完整应用。划分的重点是你要维护什么。例如租云服务器后，通常仍要维护系统和应用；使用托管应用平台，平台承担更多运行环境工作。\n\n| 模式 | 你主要负责 | 适合本课程的例子 |\n|---|---|---|\n| IaaS | 操作系统、应用、数据、访问配置 | 在云服务器运行书单服务 |\n| PaaS | 应用代码、业务配置和数据规则 | 将应用发布到托管运行平台 |\n| SaaS | 使用配置、内容和账户管理 | 直接使用现成知识管理应用 |\n| 模型服务 MaaS | 任务输入、模型选择、调用与成本 | 通过模型 API 生成推荐摘要 |\n\nMaaS 是这里对“通过服务使用模型能力”的称呼，不代表所有服务商的能力和管理边界完全相同。\n\n## 一次 AI 应用请求花在哪里\n\n网页本身需要托管；数据需要存储；后端执行逻辑需要运行资源；模型推理可能单独计费。服务也可能产生网络传输、日志和备份成本。先画清调用链，就能知道哪些资源在持续收费，哪些按请求消耗。\n\n### 成本演算：使用虚构单价\n\n假设一次请求平均输入 2000 token、输出 500 token，输入每百万 token 价格为 10 个计价单位，输出为 30。则单次模型成本约为 `2000/1000000×10 + 500/1000000×30 = 0.035`。一万次为 350。这里是教学假设，真实预算应替换成服务商当前价格，并计入失败重试。\n\n## 先按任务选资源\n\n纯课件阅读站点不需要为每次翻页调用模型。共享书单需要持久化数据库；自动摘要才需要模型调用。将这些职责分开，可单独控制成本和故障。如果模型暂时不可用，用户仍应能浏览已有推荐。\n\n## 动手练习\n\n1. 列出书单系统的网页、API、数据、模型四部分。\n2. 为每部分标明托管位置和维护责任人。\n3. 用上述虚构单价计算每日 1000 次请求的月度模型预算，按 30 天为 1050。\n4. 加入每次最多一次重试，写明预算上界和告警阈值。\n\n## 验收标准\n\n- 能说明服务商负责什么、自己负责什么。\n- 模型预算中输入与输出分开计算，重试有上限。\n- 模型不可用时的基本浏览路径仍然明确。\n\n## 自测与参考答案\n\n**问题：** 买了云服务器，是否就有一个可公开访问的网站？\n\n
展开参考答案

还要部署应用并配置网络入口、域名或地址、证书及访问权限。服务器只是资源，网站是运行在资源上的服务。

\n\n## 本课带走\n\n先确定责任与调用链，再选资源；按实际任务计量，而不是笼统估算“AI 费用”。\n", "agent_teaching_guide_markdown": "# AI 教学包 · 云计算与 MaaS\n\n## 本课交付与易错点\n\n先核实起点：区分网页、业务接口、数据、模型推理；本课使用明确标注的虚构单价。\n\n逐项验收：责任分工与费用表，算出单次 0.035、30 天基础用量 1050，并计入重试上限。\n\n重点纠偏：这些不是服务商报价；按请求调用模型与持续托管资源要分别计量。\n\n图解用于解释关系，正文与实际工具结果用于验收；不把图中的虚构数据、示意命令或条件推演称作已经运行的结果。\n\n## 角色与任务\n\n你是本课的实践教练。目标是让学习者完成并解释“将一个 AI 应用需要的服务器、数据库和模型推理分别匹配到对应服务模式。”。以随附课程正文为知识依据，采用具体、简洁的中文。当前阶段：L4.1 · 云计算与 AI 基础设施。\n\n## 开始前确认\n\n已做过一个小工具；准备好书分享或财务助手练习项目。\n\n先问学习者已经做到哪一步、已有何种文件或结果。已有可用成果就从断点继续。需要编程时先确认工作目录与运行方式；只读分析课不修改被分析项目。\n\n## 本课讲解顺序\n\n1. 云服务首先改变的是维护责任\n2. 一次 AI 应用请求花在哪里\n3. 先按任务选资源\n\n先讲一个本课场景，再解释图中各部分的职责和连接关系。图的文字说明：运行资源：计算、网络、运行时；数据服务：数据库、文件、备份；应用业务：网页、接口、规则；模型推理：按需调用，独立计量。\n\n## 陪练步骤\n\n1. 列出书单系统的网页、API、数据、模型四部分。\n2. 为每部分标明托管位置和维护责任人。\n3. 用上述虚构单价计算每日 1000 次请求的月度模型预算，按 30 天为 1050。\n4. 加入每次最多一次重试，写明预算上界和告警阈值。\n\n一次推进一个可观察步骤。先请学员预测结果，再运行或推演，再比较预期与实际。遇到错误，收集完整错误、输入和复现过程；定位后继续到本步验收。先给提示，需要时再给完整实现。学习者要求直接完成时执行已明确的任务，并解释关键选择。\n\n## 验收依据\n\n- 能说明服务商负责什么、自己负责什么。\n- 模型预算中输入与输出分开计算，重试有上限。\n- 模型不可用时的基本浏览路径仍然明确。\n\n逐项给出：要求、实际观察、通过或待修正、下一步。运行结果只能来自实际执行；若当前只有设计稿，则按设计验收，说明哪些运行检查留给实践环境。外部写入按用户授权执行。\n\n## 诊断提问与参考判断\n\n提问：买了云服务器，是否就有一个可公开访问的网站？\n\n参考判断：还要部署应用并配置网络入口、域名或地址、证书及访问权限。服务器只是资源，网站是运行在资源上的服务。\n\n先等待学习者回答再给参考判断。若回答混淆概念，使用本课案例追问，不直接重复术语。\n\n## 常见误区与纠正\n\n这些不是服务商报价；按请求调用模型与持续托管资源要分别计量。\n\n## 结束交付\n\n给出本课成果位置或可复制内容、验收结果、一个需要复习的点。建议完成本课练习后在站点手动标记已学；你无法替学习者修改站点本地进度。\n" }, { "schema_version": "1.0", "id": "l4-1-10", "title": "应用部署与运行", "stage": "L4.1", "language": "zh-CN", "canonical_url": "https://learn.iszhou.com/#lesson/l4-1-10", "api_url": "https://learn.iszhou.com/api/v1/lessons/l4-1-10.json", "metadata": { "id": "l4-1-10", "stage": "L4.1", "num": 10, "domain": "云计算与 AI 基础设施", "title": "应用部署与运行", "desc": "理解为什么本地能运行的程序，距离可稳定访问的服务还有几步。", "ideas": [ "运行环境：ECS、Linux、进程与容器", "网络入口：域名、DNS、HTTPS、反向代理", "持续运行：日志、数据持久化、重启与备份" ], "practice": "让一个演示应用从本地运行升级为可以通过 HTTPS 访问，记录部署与验证步骤。", "takeaway": "部署的完成标准是他人可访问、数据可保留、问题可排查。", "minutes": 45, "full": true, "status": "complete", "illustration": { "src": "assets/infra-original.jpg", "alt": "一图认识 AI Infra", "caption": "认识 ECS、SSH、IP、账号、端口和安全组，以及域名、数据库与模型 API 的作用。AI 执行部署需要可用的执行工具、有效授权和明确目标；本课继续讲验证、运行与恢复。", "reused": true } }, "content_markdown": "# 应用部署与运行\n\n> 理解为什么本地能运行的程序，距离可稳定访问的服务还有几步。\n\n## 学习起点与本课交付\n\n**开始前：** 有可运行应用；部署前确认应用、主机、环境和入口，使用独立练习数据。\n\n**完成后留下：** 可跨设备访问的地址、启动与恢复说明、重启后数据核对及样例备份恢复。\n\n## 学习目标\n\n- 运行环境：ECS、Linux、进程与容器\n- 网络入口：域名、DNS、HTTPS、反向代理\n- 持续运行：日志、数据持久化、重启与备份\n\n## 图解\n\n![一图认识 AI Infra](assets/infra-original.jpg)\n\n
认识 ECS、SSH、IP、账号、端口和安全组，以及域名、数据库与模型 API 的作用。AI 执行部署需要可用的执行工具、有效授权和明确目标；本课继续讲验证、运行与恢复。 点击图片可查看大图。
\n\n## 部署是让程序在目标环境持续提供服务\n\n本地启动通常依赖你的终端和电脑。部署则要明确运行环境、网络入口、配置、数据位置和恢复方式。纯静态站点与有数据库的应用需求不同，先分清类型。\n\n静态站点主要交付 HTML、CSS、JavaScript 和图片；浏览器负责呈现与交互。后端应用还需要持续执行的服务及持久存储。本机 `localhost` 只代表当前设备，不能直接当作别人可访问的网址。\n\n## 一次网页请求经过哪里\n\n用户访问域名，DNS 帮助找到入口；HTTPS 保护传输；反向代理把请求转给后端服务；应用路由决定执行哪个业务操作。以某个 Web 框架为例，`/api/books` 的路由属于应用；反向代理位于应用之前，负责入口转发等职责。\n\n| 项目 | 必须决定的事 | 验证方式 |\n|---|---|---|\n| 运行 | 进程由谁启动、退出后谁重启 | 重启服务后再次访问 |\n| 配置 | 环境变量、外部服务地址 | 缺配置时明确报错 |\n| 数据 | 数据库与上传文件放哪里 | 重启或更新后记录仍在 |\n| 网络 | 域名、证书、端口与访问规则 | 另一设备通过 HTTPS 访问 |\n| 维护 | 日志、备份、恢复 | 实际恢复一份样例备份 |\n\n## 临时磁盘与持久数据\n\n某些托管运行环境会重建实例或替换本地文件。把数据库随代码一起放在临时目录中，更新时可能丢数据。要使用平台支持的持久存储，或将数据放到独立数据库服务。具体做法取决于部署平台，不能把云服务器的文件持久性假定套到所有环境。\n\n## 动手练习\n\n1. 先部署只有页面的书单介绍页，确认可访问地址。\n2. 再为练习 API 记录启动命令、环境配置和数据位置。\n3. 从第二个浏览器访问，新增一条虚构记录。\n4. 重启或重新部署后读取同一记录，最后演练备份恢复。\n\n## 验收标准\n\n- 交付的是可访问地址，而不只是代码压缩包。\n- 服务重启后按设计恢复，记录仍可查询。\n- 故障发生时知道查看哪份日志、恢复哪份数据。\n\n## 自测与参考答案\n\n**问题：** 代码发布成功，但数据消失，最先检查哪里？\n\n
展开参考答案

检查数据是否放在了会被发布覆盖或重建的临时位置，以及数据库连接是否指向新环境。代码版本和数据持久化是两件事。

\n\n## 本课带走\n\n能访问、能保留数据、能排查和恢复，才构成完整的部署交付。\n", "agent_teaching_guide_markdown": "# AI 教学包 · 应用部署与运行\n\n## 本课交付与易错点\n\n先核实起点：有可运行应用；部署前确认应用、主机、环境和入口，使用独立练习数据。\n\n逐项验收：可跨设备访问的地址、启动与恢复说明、重启后数据核对及样例备份恢复。\n\n重点纠偏：localhost 不是外部网址；代码上线、服务可用和数据持久化分别验收。\n\n图解用于解释关系，正文与实际工具结果用于验收；不把图中的虚构数据、示意命令或条件推演称作已经运行的结果。\n\n## 角色与任务\n\n你是本课的实践教练。目标是让学习者完成并解释“让一个演示应用从本地运行升级为可以通过 HTTPS 访问，记录部署与验证步骤。”。以随附课程正文为知识依据，采用具体、简洁的中文。当前阶段：L4.1 · 云计算与 AI 基础设施。\n\n## 开始前确认\n\n已做过一个小工具；准备好书分享或财务助手练习项目。\n\n先问学习者已经做到哪一步、已有何种文件或结果。已有可用成果就从断点继续。需要编程时先确认工作目录与运行方式；只读分析课不修改被分析项目。\n\n## 本课讲解顺序\n\n1. 部署是让程序在目标环境持续提供服务\n2. 一次网页请求经过哪里\n3. 临时磁盘与持久数据\n\n先讲一个本课场景，再解释图中各部分的职责和连接关系。图的文字说明：原有基础设施课件用 ECS 与 SSH 解释远程环境。SSH 是运维入口，用户访问应用通常走 HTTPS；凭证通过安全配置提供，不粘贴到公开说明中。\n\n## 陪练步骤\n\n1. 先部署只有页面的书单介绍页，确认可访问地址。\n2. 再为练习 API 记录启动命令、环境配置和数据位置。\n3. 从第二个浏览器访问，新增一条虚构记录。\n4. 重启或重新部署后读取同一记录，最后演练备份恢复。\n\n一次推进一个可观察步骤。先请学员预测结果，再运行或推演，再比较预期与实际。遇到错误，收集完整错误、输入和复现过程；定位后继续到本步验收。先给提示，需要时再给完整实现。学习者要求直接完成时执行已明确的任务，并解释关键选择。\n\n## 验收依据\n\n- 交付的是可访问地址，而不只是代码压缩包。\n- 服务重启后按设计恢复，记录仍可查询。\n- 故障发生时知道查看哪份日志、恢复哪份数据。\n\n逐项给出：要求、实际观察、通过或待修正、下一步。运行结果只能来自实际执行；若当前只有设计稿，则按设计验收，说明哪些运行检查留给实践环境。外部写入按用户授权执行。\n\n## 诊断提问与参考判断\n\n提问：代码发布成功，但数据消失，最先检查哪里？\n\n参考判断：检查数据是否放在了会被发布覆盖或重建的临时位置，以及数据库连接是否指向新环境。代码版本和数据持久化是两件事。\n\n先等待学习者回答再给参考判断。若回答混淆概念，使用本课案例追问，不直接重复术语。\n\n## 常见误区与纠正\n\nlocalhost 不是外部网址；代码上线、服务可用和数据持久化分别验收。\n\n## 结束交付\n\n给出本课成果位置或可复制内容、验收结果、一个需要复习的点。建议完成本课练习后在站点手动标记已学；你无法替学习者修改站点本地进度。\n" }, { "schema_version": "1.0", "id": "l4-1-11", "title": "Agent as a Service 与 AI Native 架构", "stage": "L4.1", "language": "zh-CN", "canonical_url": "https://learn.iszhou.com/#lesson/l4-1-11", "api_url": "https://learn.iszhou.com/api/v1/lessons/l4-1-11.json", "metadata": { "id": "l4-1-11", "stage": "L4.1", "num": 11, "domain": "云计算与 AI 基础设施", "title": "Agent as a Service 与 AI Native 架构", "desc": "把 Agent 看作可创建和管理的运行单元，并为下一阶段持续执行做准备。", "ideas": [ "Agent 实例：模型、执行环境、工具与工作空间", "资源与生命周期：创建、分配、暂停、恢复与销毁", "状态与任务：让 Agent 从一次调用过渡到长期工作" ], "practice": "画出“创建 Agent→分配工作空间→授予工具→委派任务”的最小平台流程。", "takeaway": "Agent 不只是一段提示词，也可以成为有资源和生命周期的服务实例。", "minutes": 35, "full": true, "status": "complete", "illustration": { "src": "assets/course-art/l4-1-11-warm-v3.webp", "alt": "实例和任务各有生命周期", "caption": "Agent 实例：待命 / 运行 / 暂停 / 停用；任务对象：目标、预算、成功条件；执行与检查点：观察、产物、下一步；恢复或完成：恢复运行 / 移交 / 结束。", "reused": false } }, "content_markdown": "# Agent as a Service 与 AI Native 架构\n\n> 把 Agent 看作可创建和管理的运行单元，并为下一阶段持续执行做准备。\n\n## 学习起点与本课交付\n\n**开始前：** 理解工具、任务状态和持久文件；先做只读研究 Agent 的架构设计。\n\n**完成后留下：** 实例、任务、工作空间三个 ID，以及暂停、检查点、恢复和停用的契约。\n\n## 学习目标\n\n- Agent 实例：模型、执行环境、工具与工作空间\n- 资源与生命周期：创建、分配、暂停、恢复与销毁\n- 状态与任务：让 Agent 从一次调用过渡到长期工作\n\n## 图解\n\n![实例和任务各有生命周期](assets/course-art/l4-1-11-warm-v3.webp)\n\n
Agent 实例：待命 / 运行 / 暂停 / 停用；任务对象：目标、预算、成功条件；执行与检查点：观察、产物、下一步；恢复或完成：恢复运行 / 移交 / 结束。 点击图片可查看大图。
\n\n## 把 Agent 看作可管理的运行单元\n\n本课程用“数字居民”帮助理解一种设计目标：像创建计算资源一样创建 Agent，选择模型和资源，分配工作空间与工具，再委派任务。这里讨论的是架构模型，具体平台可能只提供其中一部分能力。\n\n一个角色提示词只定义行为倾向；可管理的 Agent 实例还需要稳定 ID、执行环境、授权工具、工作空间、任务状态和生命周期。模型负责推理，运行时负责执行和保存状态。\n\n## 一份最小实例配置\n\n```json\n{\n \"agent_id\":\"resident-001\",\n \"model_profile\":\"general\",\n \"workspace_id\":\"books-research\",\n \"allowed_tools\":[\"search\",\"read_notes\"],\n \"max_steps\":20,\n \"budget_units\":100,\n \"status\":\"idle\"\n}\n```\n\n这是本课程自定义的配置例子。`budget_units` 是平台自己定义的计量单位；真正使用时应映射到模型费、运行时间或统一预算。创建实例不必同时赋予一切权限，也不必预设固定职业。\n\n## 生命周期与任务分开管理\n\n实例可以处于待命、运行、暂停或停用；任务可以处于待处理、执行中、阻塞、成功或失败。暂停 Agent 应保存任务检查点；恢复时读取检查点，决定从哪一步继续。删除实例前要处理工作空间和未完成任务，不应让任务记录凭空消失。\n\n### 案例：研究员暂时离线\n\nAgent 已筛选十篇文章，正在写摘要时运行中断。检查点保存候选文章 ID、已完成摘要、剩余列表和输出位置。新运行加载这些记录继续处理。它不需要“记起上一段完整聊天”才能恢复。\n\n## 动手练习\n\n1. 设计一个只读研究 Agent，填写配置、工具和预算。\n2. 给它“整理五条书籍推荐”的任务和输出标准。\n3. 在处理第三条后模拟暂停，列出必须保存的检查点。\n4. 设计恢复和停用行为，说明未完成任务如何交接。\n\n## 验收标准\n\n- Agent ID、任务 ID、工作空间 ID 各自明确。\n- 暂停后能从检查点恢复，不重复已经完成的外部动作。\n- 工具权限和预算可以单独收回或调整。\n\n## 自测与参考答案\n\n**问题：** 更换模型，是否必须新建全部任务记录？\n\n
展开参考答案

通常不必。若任务、状态和工作空间独立保存，可以更换推理模型后继续；要检查新模型与工具协议、上下文和质量要求的兼容性。

\n\n## 本课带走\n\n将模型、资源、权限和状态分开，Agent 才容易创建、恢复和替换。\n", "agent_teaching_guide_markdown": "# AI 教学包 · Agent as a Service 与 AI Native 架构\n\n## 本课交付与易错点\n\n先核实起点：理解工具、任务状态和持久文件；先做只读研究 Agent 的架构设计。\n\n逐项验收：实例、任务、工作空间三个 ID，以及暂停、检查点、恢复和停用的契约。\n\n重点纠偏：提示词不等于运行实例；替换模型或执行者前核对工具和状态兼容性。\n\n图解用于解释关系，正文与实际工具结果用于验收；不把图中的虚构数据、示意命令或条件推演称作已经运行的结果。\n\n## 角色与任务\n\n你是本课的实践教练。目标是让学习者完成并解释“画出“创建 Agent→分配工作空间→授予工具→委派任务”的最小平台流程。”。以随附课程正文为知识依据，采用具体、简洁的中文。当前阶段：L4.1 · 云计算与 AI 基础设施。\n\n## 开始前确认\n\n已做过一个小工具；准备好书分享或财务助手练习项目。\n\n先问学习者已经做到哪一步、已有何种文件或结果。已有可用成果就从断点继续。需要编程时先确认工作目录与运行方式；只读分析课不修改被分析项目。\n\n## 本课讲解顺序\n\n1. 把 Agent 看作可管理的运行单元\n2. 一份最小实例配置\n3. 生命周期与任务分开管理\n\n先讲一个本课场景，再解释图中各部分的职责和连接关系。图的文字说明：Agent 实例：待命 / 运行 / 暂停 / 停用；任务对象：目标、预算、成功条件；执行与检查点：观察、产物、下一步；恢复或完成：恢复运行 / 移交 / 结束。\n\n## 陪练步骤\n\n1. 设计一个只读研究 Agent，填写配置、工具和预算。\n2. 给它“整理五条书籍推荐”的任务和输出标准。\n3. 在处理第三条后模拟暂停，列出必须保存的检查点。\n4. 设计恢复和停用行为，说明未完成任务如何交接。\n\n一次推进一个可观察步骤。先请学员预测结果，再运行或推演，再比较预期与实际。遇到错误，收集完整错误、输入和复现过程；定位后继续到本步验收。先给提示，需要时再给完整实现。学习者要求直接完成时执行已明确的任务，并解释关键选择。\n\n## 验收依据\n\n- Agent ID、任务 ID、工作空间 ID 各自明确。\n- 暂停后能从检查点恢复，不重复已经完成的外部动作。\n- 工具权限和预算可以单独收回或调整。\n\n逐项给出：要求、实际观察、通过或待修正、下一步。运行结果只能来自实际执行；若当前只有设计稿，则按设计验收，说明哪些运行检查留给实践环境。外部写入按用户授权执行。\n\n## 诊断提问与参考判断\n\n提问：更换模型，是否必须新建全部任务记录？\n\n参考判断：通常不必。若任务、状态和工作空间独立保存，可以更换推理模型后继续；要检查新模型与工具协议、上下文和质量要求的兼容性。\n\n先等待学习者回答再给参考判断。若回答混淆概念，使用本课案例追问，不直接重复术语。\n\n## 常见误区与纠正\n\n提示词不等于运行实例；替换模型或执行者前核对工具和状态兼容性。\n\n## 结束交付\n\n给出本课成果位置或可复制内容、验收结果、一个需要复习的点。建议完成本课练习后在站点手动标记已学；你无法替学习者修改站点本地进度。\n" }, { "schema_version": "1.0", "id": "l4-1-12", "title": "财务小助手 AI 优化与应用部署", "stage": "L4.1", "language": "zh-CN", "canonical_url": "https://learn.iszhou.com/#lesson/l4-1-12", "api_url": "https://learn.iszhou.com/api/v1/lessons/l4-1-12.json", "metadata": { "id": "l4-1-12", "stage": "L4.1", "num": 12, "domain": "案例解析与实战", "title": "财务小助手 AI 优化与应用部署", "desc": "把 L3 的个人小工具升级为可复用、可持续运行的 AI Friendly System。", "ideas": [ "能力识别：抽取记账、查询、分析等业务动作", "接口改造：统一 API，配合 UI 或 AI 调用", "部署验证：持久化数据、凭证保护和运行监控" ], "practice": "选择一项财务助手功能，将其封装为 API 并完成一次真实调用与部署验收。", "takeaway": "从能用的小工具到可复用的系统，关键是接口和运行边界。", "minutes": 60, "full": true, "status": "complete", "illustration": { "src": "assets/course-art/l4-1-12-warm-v4.webp", "alt": "服务化：规则集中，入口复用", "caption": "同一请求 ID 与相同内容重试返回同一记录；不同请求正常记录。账目与去重记录同事务保存，继续沿用 2550 + 800 + 1450 = 4800 分的验算样例。", "reused": false } }, "content_markdown": "# 财务小助手 AI 优化与应用部署\n\n> 把 L3 的个人小工具升级为可复用、可持续运行的 AI Friendly System。\n\n## 学习起点与本课交付\n\n**开始前：** 沿用 L3-05 的三行练习账本与计算规则，再增加服务边界。\n\n**完成后留下：** 函数、API、网页一致的 48.00 元汇总，以及请求重放、冲突与重启验证。\n\n## 学习目标\n\n- 能力识别：抽取记账、查询、分析等业务动作\n- 接口改造：统一 API，配合 UI 或 AI 调用\n- 部署验证：持久化数据、凭证保护和运行监控\n\n## 图解\n\n![服务化：规则集中，入口复用](assets/course-art/l4-1-12-warm-v4.webp)\n\n
同一请求 ID 与相同内容重试返回同一记录；不同请求正常记录。账目与去重记录同事务保存，继续沿用 2550 + 800 + 1450 = 4800 分的验算样例。 点击图片可查看大图。
\n\n## 把 L3 账本变成共享业务服务\n\nL3 的练习账本可以在本地运行。现在增加服务边界，让网页和 Agent 都能录入和查询。迁移的重点是抽出业务函数、统一数据规则、处理身份和重复请求，而不是重写全部代码。\n\n## 先提炼三个业务动作\n\n`add_expense` 校验并新增；`list_expenses` 按范围查询；`summarize_expenses` 按确定口径汇总。网页、CLI 和 API 都调用这些业务函数。日期、金额、归属和重复规则只维护一套。\n\n| 动作 | 请求关键字段 | 服务检查 | 返回证据 |\n|---|---|---|---|\n| 新增支出 | 日期、分类、整数分、请求 ID | 金额有效、身份允许、请求未重复 | 记录 ID 与保存值 |\n| 查询列表 | 日期范围、分页 | 只能读授权账户 | 记录和下一页游标 |\n| 汇总 | 范围、分类 | 口径与可见数据一致 | 金额、单位、筛选条件 |\n\n## 幂等性：同一个动作不重复记账\n\n幂等性在这里指相同业务请求重试后不会产生重复记录。客户端为新增操作提供稳定的请求 ID；服务保存它与结果的关联。若相同 ID、相同内容再次到达，返回原结果；若相同 ID 对应不同内容，明确拒绝。仅用“金额和日期相同”去重会误伤真实重复消费。\n\n数据库的写入和请求 ID 记录需要保持一致，可以在同一事务中完成。事务让一组相关修改一起成功或一起失败，防止“账已记了、去重标记没存”这种半完成状态。\n\n## 迁移验收用同一份样例\n\n继续使用餐饮 2550、交通 800、餐饮 1450 分，总额 4800 分。先在本地函数验算，再经过 API 验算，最后从网页检查。三层结果不同，就沿调用链定位，不能换一份更容易通过的数据。\n\n## 动手练习\n\n1. 将 L3 脚本的新增与汇总提取到服务模块。\n2. 实现新增和汇总 API，身份从服务端认证结果取得。\n3. 重放同一个新增请求，确认只新增一次。\n4. 部署到练习环境，重启后查询相同账目并核对总额。\n\n## 验收标准\n\n- 函数、API、页面三处总额一致。\n- 重复请求不重复记账，ID 冲突会明确失败。\n- 不同用户的数据范围隔离，部署后数据保留。\n\n## 自测与参考答案\n\n**问题：** 早晚各买一杯同价咖啡，能用“日期＋金额”去重吗？\n\n
展开参考答案

不能，它们可能是两笔真实交易。去重应围绕操作或交易的稳定标识，而不是仅凭相同金额和日期。

\n\n## 本课带走\n\n升级服务时保留已经验证的计算规则，把边界、身份和重复处理补齐。\n", "agent_teaching_guide_markdown": "# AI 教学包 · 财务小助手 AI 优化与应用部署\n\n## 本课交付与易错点\n\n先核实起点：沿用 L3-05 的三行练习账本与计算规则，再增加服务边界。\n\n逐项验收：函数、API、网页一致的 48.00 元汇总，以及请求重放、冲突与重启验证。\n\n重点纠偏：同 ID 同内容返回原结果；同 ID 不同内容拒绝；同价消费不代表同一交易。\n\n图解用于解释关系，正文与实际工具结果用于验收；不把图中的虚构数据、示意命令或条件推演称作已经运行的结果。\n\n## 角色与任务\n\n你是本课的实践教练。目标是让学习者完成并解释“选择一项财务助手功能，将其封装为 API 并完成一次真实调用与部署验收。”。以随附课程正文为知识依据，采用具体、简洁的中文。当前阶段：L4.1 · 案例解析与实战。\n\n## 开始前确认\n\n已做过一个小工具；准备好书分享或财务助手练习项目。\n\n先问学习者已经做到哪一步、已有何种文件或结果。已有可用成果就从断点继续。需要编程时先确认工作目录与运行方式；只读分析课不修改被分析项目。\n\n## 本课讲解顺序\n\n1. 把 L3 账本变成共享业务服务\n2. 先提炼三个业务动作\n3. 幂等性：同一个动作不重复记账\n4. 迁移验收用同一份样例\n\n先讲一个本课场景，再解释图中各部分的职责和连接关系。图的文字说明：同一请求 ID 与相同内容重试返回同一记录；不同请求正常记录。账目与去重记录同事务保存，继续沿用 2550 + 800 + 1450 = 4800 分的验算样例。\n\n## 陪练步骤\n\n1. 将 L3 脚本的新增与汇总提取到服务模块。\n2. 实现新增和汇总 API，身份从服务端认证结果取得。\n3. 重放同一个新增请求，确认只新增一次。\n4. 部署到练习环境，重启后查询相同账目并核对总额。\n\n一次推进一个可观察步骤。先请学员预测结果，再运行或推演，再比较预期与实际。遇到错误，收集完整错误、输入和复现过程；定位后继续到本步验收。先给提示，需要时再给完整实现。学习者要求直接完成时执行已明确的任务，并解释关键选择。\n\n## 验收依据\n\n- 函数、API、页面三处总额一致。\n- 重复请求不重复记账，ID 冲突会明确失败。\n- 不同用户的数据范围隔离，部署后数据保留。\n\n逐项给出：要求、实际观察、通过或待修正、下一步。运行结果只能来自实际执行；若当前只有设计稿，则按设计验收，说明哪些运行检查留给实践环境。外部写入按用户授权执行。\n\n## 诊断提问与参考判断\n\n提问：早晚各买一杯同价咖啡，能用“日期＋金额”去重吗？\n\n参考判断：不能，它们可能是两笔真实交易。去重应围绕操作或交易的稳定标识，而不是仅凭相同金额和日期。\n\n先等待学习者回答再给参考判断。若回答混淆概念，使用本课案例追问，不直接重复术语。\n\n## 常见误区与纠正\n\n同 ID 同内容返回原结果；同 ID 不同内容拒绝；同价消费不代表同一交易。\n\n## 结束交付\n\n给出本课成果位置或可复制内容、验收结果、一个需要复习的点。建议完成本课练习后在站点手动标记已学；你无法替学习者修改站点本地进度。\n" }, { "schema_version": "1.0", "id": "l4-1-13", "title": "好书分享：AI Friendly System 实战", "stage": "L4.1", "language": "zh-CN", "canonical_url": "https://learn.iszhou.com/#lesson/l4-1-13", "api_url": "https://learn.iszhou.com/api/v1/lessons/l4-1-13.json", "metadata": { "id": "l4-1-13", "stage": "L4.1", "num": 13, "domain": "案例解析与实战", "title": "好书分享：AI Friendly System 实战", "desc": "用一份共享书单演示人通过网页、AI 通过工具操作相同数据。", "ideas": [ "共享数据：书籍、分享记录、版本号与操作历史", "双入口：HTML → API 和 Skill → CLI → API", "实战闭环：本地运行、权限验证、部署、跨设备复核" ], "practice": "由网页发布一本书，让另一个 AI 通过 CLI 修改读书笔记，再回网页确认。", "takeaway": "同一组业务能力能够同时服务人和 Agent，才是贯穿本阶段的目标。", "minutes": 60, "full": true, "status": "complete", "illustration": { "src": "assets/course-art/l4-1-13-warm-v3.webp", "alt": "人机共用同一业务服务", "caption": "网页发布分享 s-001/v1，工具按授权更新为 v2，再由网页复核；书籍与个人分享分开，只读凭证不能修改，旧版本不能无提示覆盖。", "reused": false } }, "content_markdown": "# 好书分享：AI Friendly System 实战\n\n> 用一份共享书单演示人通过网页、AI 通过工具操作相同数据。\n\n## 学习起点与本课交付\n\n**开始前：** 完成界面、API、身份和版本基础；先实现一条可保存的纵向路径。\n\n**完成后留下：** 网页发布→工具读取修改→网页复核同一分享的新版本，附权限与冲突证据。\n\n## 学习目标\n\n- 共享数据：书籍、分享记录、版本号与操作历史\n- 双入口：HTML → API 和 Skill → CLI → API\n- 实战闭环：本地运行、权限验证、部署、跨设备复核\n\n## 图解\n\n![人机共用同一业务服务](assets/course-art/l4-1-13-warm-v3.webp)\n\n
网页发布分享 s-001/v1，工具按授权更新为 v2，再由网页复核；书籍与个人分享分开，只读凭证不能修改，旧版本不能无提示覆盖。 点击图片可查看大图。
\n\n## 毕业小项目：一个人机共同维护的书单\n\n这个项目把界面、API、身份、数据和工具串起来。目标很具体：人从网页发布推荐，Agent 从工具读取并修改自己的笔记，再由人回到网页看到同一条记录的新版本。\n\n## 先定义对象与约束\n\n书籍 Book 表示作品，分享 Share 表示某位用户对作品的推荐。一个 Book 可以对应多条 Share。书名不能作为可靠的唯一 ID，因为可能有同名书或不同版本。练习可以使用独立生成的 ID，再逐步补作者、ISBN 等字段。\n\n| 对象 | 最小字段 | 规则 |\n|---|---|---|\n| Book | id、title、author | 书名必填 |\n| Share | id、book_id、owner_id、note、version | 修改需要归属与版本匹配 |\n| Audit | request_id、actor、action、resource、time | 记录关键变更与结果 |\n\n## 从一条纵向路径开始\n\n第一步打通“网页填表→新增 API→数据库→详情展示”。第二步增加“CLI→同一 API”。第三步写 Skill，说明查询、分页、更新前读取版本以及冲突处理。不要先把每个页面都画完，却没有一条能实际保存的路径。\n\n### 一次完整协作\n\n人发布“系统之美”，服务返回分享 ID `s-001`、版本 1。Agent 查询这条分享，在允许范围内把笔记改为“重点读反馈回路与时间延迟”，提交预期版本 1。服务更新为版本 2。网页刷新显示同一 ID 与新笔记，审计记录这次调用主体。\n\n## 失败路径也属于项目范围\n\n空书名应被拒绝；只读 Agent 不能修改；旧版本更新返回冲突；提交超时后先查询原请求结果，避免再次新增。删除需要明确对象，不能让一句含糊的“清理一下”自动扩展成批量删除。\n\n## 动手练习\n\n1. 写一页 Spec，列出上表对象、四个动作和权限规则。\n2. 完成一个网页入口与一个 CLI 入口，共享业务服务。\n3. 按上述故事做一轮发布、读取、修改、网页复核。\n4. 测试空输入、越权和版本冲突，保存实际请求与结果。\n5. 发布练习版本，提供使用说明和复测数据。\n\n## 验收标准\n\n- 双入口操作同一条记录，身份与版本可追溯。\n- 三类失败均有清晰反馈，数据不被错误写入。\n- 新同伴按说明能完成一轮人机协作。\n\n## 自测与参考答案\n\n**问题：** 两位用户推荐同一本书，应创建两本书还是两条分享？\n\n
展开参考答案

通常复用同一书籍对象，分别创建两条个人分享。这样既能聚合推荐，也能独立管理作者、笔记和权限。

\n\n## 本课带走\n\n以一条真实的跨入口任务验收系统，比单独检查各页面更有价值。\n", "agent_teaching_guide_markdown": "# AI 教学包 · 好书分享：AI Friendly System 实战\n\n## 本课交付与易错点\n\n先核实起点：完成界面、API、身份和版本基础；先实现一条可保存的纵向路径。\n\n逐项验收：网页发布→工具读取修改→网页复核同一分享的新版本，附权限与冲突证据。\n\n重点纠偏：Book 与 Share 分开；只读主体不能借任何入口写入；超时先查原请求。\n\n图解用于解释关系，正文与实际工具结果用于验收；不把图中的虚构数据、示意命令或条件推演称作已经运行的结果。\n\n## 角色与任务\n\n你是本课的实践教练。目标是让学习者完成并解释“由网页发布一本书，让另一个 AI 通过 CLI 修改读书笔记，再回网页确认。”。以随附课程正文为知识依据，采用具体、简洁的中文。当前阶段：L4.1 · 案例解析与实战。\n\n## 开始前确认\n\n已做过一个小工具；准备好书分享或财务助手练习项目。\n\n先问学习者已经做到哪一步、已有何种文件或结果。已有可用成果就从断点继续。需要编程时先确认工作目录与运行方式；只读分析课不修改被分析项目。\n\n## 本课讲解顺序\n\n1. 毕业小项目：一个人机共同维护的书单\n2. 先定义对象与约束\n3. 从一条纵向路径开始\n4. 失败路径也属于项目范围\n\n先讲一个本课场景，再解释图中各部分的职责和连接关系。图的文字说明：网页发布分享 s-001/v1，工具按授权更新为 v2，再由网页复核；书籍与个人分享分开，只读凭证不能修改，旧版本不能无提示覆盖。\n\n## 陪练步骤\n\n1. 写一页 Spec，列出上表对象、四个动作和权限规则。\n2. 完成一个网页入口与一个 CLI 入口，共享业务服务。\n3. 按上述故事做一轮发布、读取、修改、网页复核。\n4. 测试空输入、越权和版本冲突，保存实际请求与结果。\n5. 发布练习版本，提供使用说明和复测数据。\n\n一次推进一个可观察步骤。先请学员预测结果，再运行或推演，再比较预期与实际。遇到错误，收集完整错误、输入和复现过程；定位后继续到本步验收。先给提示，需要时再给完整实现。学习者要求直接完成时执行已明确的任务，并解释关键选择。\n\n## 验收依据\n\n- 双入口操作同一条记录，身份与版本可追溯。\n- 三类失败均有清晰反馈，数据不被错误写入。\n- 新同伴按说明能完成一轮人机协作。\n\n逐项给出：要求、实际观察、通过或待修正、下一步。运行结果只能来自实际执行；若当前只有设计稿，则按设计验收，说明哪些运行检查留给实践环境。外部写入按用户授权执行。\n\n## 诊断提问与参考判断\n\n提问：两位用户推荐同一本书，应创建两本书还是两条分享？\n\n参考判断：通常复用同一书籍对象，分别创建两条个人分享。这样既能聚合推荐，也能独立管理作者、笔记和权限。\n\n先等待学习者回答再给参考判断。若回答混淆概念，使用本课案例追问，不直接重复术语。\n\n## 常见误区与纠正\n\nBook 与 Share 分开；只读主体不能借任何入口写入；超时先查原请求。\n\n## 结束交付\n\n给出本课成果位置或可复制内容、验收结果、一个需要复习的点。建议完成本课练习后在站点手动标记已学；你无法替学习者修改站点本地进度。\n" }, { "schema_version": "1.0", "id": "l4-1-14", "title": "财务小助手架构剖析", "stage": "L4.1", "language": "zh-CN", "canonical_url": "https://learn.iszhou.com/#lesson/l4-1-14", "api_url": "https://learn.iszhou.com/api/v1/lessons/l4-1-14.json", "metadata": { "id": "l4-1-14", "stage": "L4.1", "num": 14, "domain": "案例解析与实战", "title": "财务小助手架构剖析", "desc": "以已上线的财务助手为案例，从网址路由开始，亲手完成 API、功能权限、数据权限与 SQLite 查询实验。", "ideas": [ "网址与路由：从可见的网址读懂协议、域名、路径、参数和处理入口", "API 与权限：点击运行真实请求，同时验证功能权限与数据权限", "数据库与公网：按步骤打开 SQLite、执行 SQL，再串起域名、HTTPS 和反向代理" ], "practice": "拆解真实网址；在站内实验页执行 GET、POST 与权限案例；下载教学数据库并跑出指定 SQL 结果。", "takeaway": "能从网址追到处理入口，读懂请求和响应，区分功能权限与数据权限，并亲手查到数据库记录。", "minutes": 75, "full": true, "status": "complete", "illustration": { "src": "assets/finance-architecture-v1.jpeg", "alt": "个人财务助手系统架构图 v1.0", "caption": "以已完成并公网部署的项目为案例，串起路由、API、权限、数据库与公网访问。原图 v1.0，2026-10-13。", "reused": true } }, "content_markdown": "# 财务小助手架构剖析\n\n> 以已经部署的项目架构为线索，从真实网址、固定接口教学响应和独立 SQLite 样例入手，再把请求沿着架构图串起来。\n\n## 学习起点与本课交付\n\n**开始前：** 浏览器即可看固定 API 教学响应；SQL 路径选择 DB Browser 或 Python，使用下载副本。\n\n**完成后留下：** 解释网址、方法、权限场景与 SQL；家庭样例 44 元、公司样例 99 元的实际查询。\n\n## 本课怎么学\n\n先看整体架构，再做四项可以观察结果的操作：拆网址、点按钮发 API 请求、验证功能权限与数据权限、执行 SQL。最后再看公网链路。每一步都给出成功时应看到的结果。\n\n学习准备：一个浏览器。本课的 API 实验和 SQLite 样例都已放在站内，不需要真实财务账号，也不会写入生产数据。想对照自己的项目时，再使用测试账号、测试 Token 和数据库副本。\n\n**实验边界：** 本站 `/api-lab` 按固定场景返回教学响应。POST 的 `201`、`id: 103` 是预设示例，不会根据请求正文新增持久记录；权限案例也不是真实登录或 Token 校验。SQL 练习使用另一份独立下载的数据库。三部分用于理解协议和边界，不能据此宣称已经连通生产账本。验证真实写入、字段校验或鉴权时，请在自己实现的练习服务中发送请求，再查询同一记录。\n\n## 架构总览：从浏览器或 Agent 到数据库\n\n![个人财务助手系统架构图 v1.0：Human 与 Agent 双入口、FastAPI、IAM、业务模块与数据层](assets/finance-architecture-v1.jpeg)\n\n
个人财务助手系统架构图 v1.0，2026-10-13，用户提供。点击可查看大图。原图包含“当前开发”与“生产待补”的标记；本课结合已经部署的项目讲解公网访问机制。
\n\n图中 Human 和 Agent 是两种使用主体，Web UI 与 API / CLI 是相应入口。请求进入应用后，经过身份与权限判断，再由已有业务能力处理，最终读写数据。本图的 IAM 位于 FastAPI 应用内部，是逻辑分工中的一层。\n\n| 本课知识点 | 图上位置 | 复盘时要弄明白的问题 | 学习方式 |\n|---|---|---|---|\n| 网址与路由 | 统一入口、FastAPI 页面/API 路由 | 网址中的每一段怎样指向服务、资源和条件？ | 拆解真实网址 |\n| API 调用 | Human REST API、Agent API / CLI | 调用双方怎样约定输入输出？ | 站内按钮直接运行 |\n| 权限设计 | IAM、空间与成员、后台权限 | 谁能做什么，又能操作哪部分数据？ | 功能权限与数据权限实验 |\n| 数据库连接与查阅 | 数据库、数据访问层 | 怎样打开数据库、看表、执行 SQL 并核对结果？ | 下载样例后逐步操作 |\n| 公网访问链路 | 域名、HTTPS、反向代理入口 | 输入公网地址后，请求怎样到达应用？ | 链路图解与浏览器查看 |\n\n贯穿案例：在家庭账本中查询一笔“午餐 36 元”。先分别理解五个部分，最后把它们连成一次完整请求。\n\n## 知识点一：从网址理解路由\n\n### 概念与生活实例\n\n先看一个完整网址：\n\n```text\nhttps://learn.iszhou.com/api-lab/transactions/101?format=json#response\n```\n\n网址可以直接拆成几段：\n\n| 部分 | 本例 | 它解决什么问题 |\n|---|---|---|\n| 协议 | `https://` | 浏览器用什么规则建立连接，并加密传输 |\n| 域名 | `learn.iszhou.com` | 请求要去哪个网站 |\n| 路径 | `/api-lab/transactions/101` | 网站内部要找哪个资源；这里是交易 101 |\n| 查询参数 | `?format=json` | 给这次读取附加条件 |\n| 片段 | `#response` | 浏览器跳到页面内的位置，不会发送给服务器 |\n\n**路由主要看 HTTP 方法和路径。** 可以把它理解成网站内部的地址表：收到 `GET /api-lab/transactions/101`，就交给“查询单笔交易”的处理函数。域名先把请求带到网站，路径再把请求带到网站里的具体处理入口。\n\n在 Web 应用中，通常由 HTTP 方法和 URL 路径共同确定处理入口。`GET` 常用于读取，`POST` 常用于创建或提交处理任务；具体行为由接口约定。\n\n| 请求 | 处理入口 | 含义 |\n|---|---|---|\n| `GET /api-lab/transactions` | `list_transactions` | 查询交易列表 |\n| `GET /api-lab/transactions/101` | `get_transaction` | 查询 ID 为 101 的交易 |\n| `POST /api-lab/transactions` | `create_transaction` | 提交一笔新交易 |\n| `GET /api-lab/reports/monthly` | `monthly_report` | 查询月度报告 |\n\n同一个 `/api-lab/transactions` 路径，可以因为方法不同而匹配到不同函数。`?category=餐饮` 是查询参数，路由已经匹配之后，再由处理函数拿它筛选结果。\n\n### 看一段最小路由代码\n\n```python\nfrom fastapi import FastAPI\n\napp = FastAPI()\n\n@app.get(\"/api-lab/transactions/{transaction_id}\")\ndef get_transaction(transaction_id: int):\n return {\"id\": transaction_id, \"description\": \"午餐\"}\n```\n\n发送 `GET /api-lab/transactions/101` 时，FastAPI 匹配这条规则，把路径中的 `101` 作为 `transaction_id` 传入函数，再把返回的字典编码为 JSON 响应。代码中 `: int` 同时声明参数类型，并参与输入校验。\n\n### 怎么设计路由\n\n先按资源组织路径，如 `/ledgers`、`/transactions`，再用方法表达读取、创建等操作；单条资源带 ID。按模块设置统一前缀，便于理解和维护，例如 `/api/transactions` 与 `/api/reports`。\n\n图中还有另一种“分发”：Nginx 根据域名和路径将请求转发到后端应用；请求到达 FastAPI 后，应用路由再匹配函数。前者确定交给哪个服务，后者确定交给哪个处理入口。\n\n### 验证理解\n\n把下面的网址复制到纸上或笔记里，再分别圈出域名、路径、路径参数和查询参数：\n\n```text\nhttps://learn.iszhou.com/api-lab/transactions/101\nhttps://learn.iszhou.com/api-lab/transactions?ledger_id=10&category=餐饮\n```\n\n然后说出 `GET /api-lab/transactions/101`、`GET /api-lab/transactions?category=餐饮`、`POST /api-lab/transactions` 各自进入哪个处理函数，以及 ID、分类条件、新交易字段从哪里传入。\n\n
查看参考解释

第一条匹配单条查询函数，101 来自路径；第二条匹配列表查询函数，分类来自查询参数；第三条匹配创建函数，新交易字段通常来自 JSON 请求体。浏览器或客户端把请求送到应用，应用再按方法和路径匹配入口。

\n\n## 知识点二：API 调用——双方怎样约定输入输出\n\n### 概念与生活实例\n\nAPI 是程序向外提供能力的接口。像提交一张业务申请：要明确交给哪个窗口、办什么事、填哪些字段，以及会收到怎样的回执。接口设计就是把这些约定写清楚，使网页、CLI 和 Agent 都能据此调用。\n\n一个 HTTP API 请求主要包括以下部分：\n\n| 部分 | 教学示例 | 作用 |\n|---|---|---|\n| 服务地址 | `https://learn.iszhou.com` | 找到目标服务 |\n| 方法与路径 | `GET /api-lab/transactions` | 指定要执行的操作 |\n| 查询参数 | `ledger_id=10&category=餐饮` | 传递筛选条件 |\n| Header | `Authorization: Bearer <测试凭证>` | 携带认证等请求信息 |\n| Body | 新交易的日期、金额、分类 | 传递结构化业务数据 |\n\n响应包括状态码、Header 和响应体。状态码说明处理结果的大类，JSON 中的字段说明具体结果。常见示例：200 查询成功、201 创建成功、401 需要有效认证、403 操作未获授权、422 输入未满足接口模型要求；实际项目也会按自己的接口规范返回错误。\n\n### 接口设计要写清哪些约定\n\n以“新增交易”为例，至少说明：账本 ID、日期、金额和币种的类型及必填性，金额单位，是否允许空分类，成功后返回的 ID 与状态，以及输入错误的返回格式。列表接口还要约定筛选条件、分页方式和返回结构。\n\n下面是一套教学约定：用整数“分”表示金额，`amount_cents=3600` 表示 36 元。这样调用者与服务端对单位有同一个理解。\n\n```json\n{\n \"ledger_id\": 10,\n \"date\": \"2026-10-15\",\n \"amount_cents\": 3600,\n \"currency\": \"CNY\",\n \"category\": \"餐饮\",\n \"description\": \"午餐\"\n}\n```\n\n调用时，客户端将这些字段编码为 JSON；服务端解析请求体，按接口模型检查类型和必填项，将参数交给已有处理逻辑；最后把结果编码为响应。网页和 Agent 都可以按这份约定调用。\n\n### 实操：用 Apipost 调用一套能跑通的接口\n\n下面都是课程专用的教学接口，不需要账号或 Token，也不会写入真实财务数据。打开 Apipost，新建“HTTP 请求”，照着填写并点击“发送”。\n\n#### 示例 1：查询一笔交易\n\n- 方法：`GET`\n- URL：`https://learn.iszhou.com/api-lab/transactions/101`\n- Params、Body、Header：都留空\n- 预期状态码：`200`\n\n预期响应中包含：\n\n```json\n{\n \"id\": 101,\n \"ledger_id\": 10,\n \"amount_cents\": 3600,\n \"category\": \"餐饮\",\n \"description\": \"午餐\"\n}\n```\n\n#### 示例 2：用参数筛选交易\n\n- 方法：`GET`\n- URL：`https://learn.iszhou.com/api-lab/transactions`\n- 在 `Params` 中新增两行：\n\n| 参数名 | 参数值 |\n|---|---|\n| `ledger_id` | `10` |\n| `category` | `餐饮` |\n\n- Body、Header：留空\n- 预期状态码：`200`\n- 预期结果：`total` 为 `1`，返回记录的 `ledger_id` 为 `10`、`category` 为 `餐饮`\n\n点击发送前，观察 Apipost 自动拼出的完整 URL：\n\n```text\nhttps://learn.iszhou.com/api-lab/transactions?ledger_id=10&category=餐饮\n```\n\n#### 示例 3：发送 JSON，观察创建成功的响应格式\n\n- 方法：`POST`\n- URL：`https://learn.iszhou.com/api-lab/transactions`\n- 打开 `Body`，选择 `raw` 或 `JSON`\n- Header：选择 JSON 后通常会自动生成 `Content-Type: application/json`\n- 粘贴下面的请求体：\n\n```json\n{\n \"ledger_id\": 10,\n \"date\": \"2026-10-15\",\n \"amount_cents\": 3600,\n \"currency\": \"CNY\",\n \"category\": \"餐饮\",\n \"description\": \"午餐\"\n}\n```\n\n- 预期状态码：`201`\n- 预期结果：固定教学响应包含 `\"id\": 103` 和 `\"created\": true`，用于认识创建接口的返回结构，不代表真实写入。\n\n发送前检查方法为 `POST`、Body 选择 JSON、字段名和双引号完整。此固定教学接口不提供完整的字段验证；改动正文后仍收到相同响应，不能据此判断新字段已保存或校验已通过。真实服务应拒绝非法输入，并通过后续查询证明写入成功。\n\n### 验证理解\n\n在 Apipost 中成功运行以上三个请求，并保存到同一个项目。能指出 `101` 是路径参数，`ledger_id` 和 `category` 是查询参数，新增交易字段位于 JSON Body。\n\n
思考：网页已经可以新增交易，为什么还要手动调用 API？

手动调用会展开页面背后隐藏的请求结构，便于理解字段、方法和响应的约定。网页、CLI、Agent 可以分别作为客户端，遵循接口约定访问服务。

\n\n## 知识点三：权限设计——谁能对哪些数据做什么\n\n### 概念与生活实例\n\n公司里有员工身份、岗位职责和工作范围：同一个人在苏州办公室负责财务，在另一个项目组可能只有查阅权限。系统也需要同时描述调用者、允许的操作和数据范围。\n\n**认证**确认调用者是谁，例如登录后识别用户，或者验证 Token 所代表的主体。**授权**根据身份、操作和资源，判断请求是否可以执行。\n\n### 两类权限必须同时成立\n\n| 分类 | 回答的问题 | 财务助手示例 | 常见检查位置 |\n|---|---|---|---|\n| 功能权限 | 能做什么？ | 读取、新增、编辑、审核、导出 | 角色、Token Scope、接口动作 |\n| 数据权限 | 能操作哪部分数据？ | 哪个空间、哪个账本、自己创建的行、哪些字段 | 成员关系、资源归属、行过滤、字段脱敏 |\n| 管理权限 | 能配置什么？ | 邀请成员、分配角色、管理 Agent 授权 | 管理角色与审批规则 |\n\n只有功能权限，没有数据权限，会出现“有查看功能，因此看见所有人的账目”的越权。只有数据权限，没有功能权限，也不能执行操作。一次请求需要同时满足：\n\n```text\n允许 = 功能权限通过\n AND 空间范围通过\n AND 账本范围通过\n AND 行级规则通过\n AND 字段规则通过\n```\n\n数据权限可以逐层收窄：\n\n| 层级 | 例子 | 不通过时的结果 |\n|---|---|---|\n| 空间／租户 | Carmen 只能进入家庭空间，不能进入公司空间 | 拒绝或不返回该空间 |\n| 账本 | 月度分析 Agent 只能读“家庭日常”账本 | 其他账本不进入查询范围 |\n| 行 | 记账员只能修改自己创建的交易 | 可以看到但不能改他人记录 |\n| 字段 | 普通成员看不到银行卡号完整值 | 返回脱敏值或不返回该字段 |\n| 时间范围 | 临时审计员只能查 2026 年 10 月 | 查询自动附加日期条件 |\n\n常用的组织方式是 RBAC，即按角色组织权限：把一组操作赋给“查看者”“记账员”等角色，再把角色赋给相应空间中的成员。Role 组织职责，Space / Ledger 限定资源范围。Token 的 Scope 可进一步限制某次调用授权，如只允许 `transactions:read`。\n\n### 一张设计用权限矩阵\n\n下面是供讲解的角色设计。每个角色的资源范围都需要单独指定。\n\n| 角色 | 查看交易 | 新增交易 | 编辑交易 | 审核交易 | 管理成员 | 数据范围 |\n|---|---|---|---|---|---|---|\n| 查看者 | ✓ | — | — | — | — | 已授权账本 |\n| 记账员 | ✓ | ✓ | 自己创建的交易 | — | — | 已授权账本 |\n| 审核员 | ✓ | — | — | ✓ | — | 指定空间的账本 |\n| 空间管理员 | ✓ | ✓ | ✓ | ✓ | ✓ | 所管理的空间 |\n\nAgent 可以按职责获得查看者或记账员等授权，同时用 Scope 缩小可调用操作。例如，月度分析 Agent 具有家庭账本读取权限；它关联的账号即使能够记账，这枚只读 Token 也只允许读取。\n\n平台管理员负责全局账号或配置时，其管理权限也应单独定义；是否允许读取各空间财务数据，是需要明确决定的一条授权规则。\n\n### 权限如何组织与执行\n\n```text\n用户／Agent → 空间成员关系 → 角色 → 允许的操作\n ＋ 账本归属与资源范围\n ＋ 本次 Token 的 Scope（使用 Token 时）\n → 本次请求是否允许\n```\n\n一个人在家庭空间是管理员，在公司空间是查看者，适合把角色记录在“主体与空间的成员关系”上。这样同一个主体可以在不同空间承担不同职责。\n\n以“编辑交易”为例，应用需要取得调用主体、交易所属空间与账本、成员角色、允许的操作，并按设计检查是否只允许编辑自己创建的记录。服务端在执行操作前完成判断，列表和统计查询也要限制到授权的数据范围。前端据此展示按钮，后端负责执行规则。图中的 IAM 就承接这些认证与授权判断。\n\n### 实操：用 Apipost 分清功能权限和数据权限\n\n继续在 Apipost 新建下面三个请求。它们是固定教学案例，身份与权限已经写进测试场景，因此不需要填写 Token。\n\n| 操作 | 方法 | URL | Body | 预期结果 |\n|---|---|---|---|---|\n| Carmen 读取家庭账本 10 | `GET` | `https://learn.iszhou.com/api-lab/permission-cases/carmen-family` | 留空 | `200`，`decision` 为 `allow` |\n| Carmen 读取公司账本 20 | `GET` | `https://learn.iszhou.com/api-lab/permission-cases/carmen-company` | 留空 | `403`，`error` 为 `data_scope_denied` |\n| 只读 Agent 新增家庭交易 | `POST` | `https://learn.iszhou.com/api-lab/permission-cases/read-only-agent` | JSON：`{\"ledger_id\":10,\"amount_cents\":3600}` | `403`，`error` 为 `action_denied` |\n\n观察重点：后两次都是 `403`，原因不同。第二次失败在数据范围，第三次失败在功能动作。真实系统也应在服务端检查这两层；前端隐藏按钮只是界面提示，不能代替服务端授权。\n\n### 验证理解：根据矩阵和数据范围推演\n\n1. 同一个人在家庭空间是管理员，在公司空间是查看者，能否修改公司交易？\n2. 记账员能否编辑另一位成员创建的交易？需要哪个字段参与判断？\n3. 账号能记账，但这次使用的 Token 只有读取 Scope，能否通过它新增交易？\n4. 月度分析 Agent 应获得哪些操作和数据范围？\n5. 某用户有“导出”功能权限，但只获准访问家庭账本。导出 SQL 能否省略账本条件？\n\n
查看参考解释

1. 公司空间的查看者角色不允许修改。2. 按本例矩阵，只能编辑自己创建的记录，需要交易的创建者 ID 与当前主体 ID。3. 只读 Token 不允许新增。4. 为其指定需要分析的家庭账本，并授予交易读取及确实需要的报告读取操作。5. 不能省略；导出仍必须带上家庭空间与账本范围，否则功能权限会放大成全库访问。每个判断都同时考虑操作与资源范围。

\n\n## 知识点四：数据库连接与查阅——应用怎样取得数据\n\n### 概念与生活实例\n\n数据库像按规则组织的电子账簿：每张表保存一类记录，每列是一个字段，每行是一条记录。连接是程序打开这套账簿的通道，SQL 是向数据库表达查询和修改意图的语言。\n\n图中 SQLite 保存为数据库文件，应用通过文件路径打开连接。PostgreSQL 作为数据库服务运行，连接通常包含主机、端口、数据库名和认证信息。两者都可以执行查询，但连接方式不同。\n\n### 表与关联怎么设计\n\n| 表 | 示例字段 | 设计含义 |\n|---|---|---|\n| `spaces` | `id`, `name` | 每个空间有唯一 ID |\n| `ledgers` | `id`, `space_id`, `name` | 通过 `space_id` 表示账本属于哪个空间 |\n| `transactions` | `id`, `ledger_id`, `date`, `amount_cents`, `category`, `description` | 通过 `ledger_id` 表示交易属于哪个账本 |\n\n主键标识一条记录，外键表达关联。交易保存 `ledger_id`，查询时再关联账本；账本改名后，交易仍指向同一本账。金额字段明确以分存储，时间字段明确日期或时间戳的口径，才能让接口与查询采用一致含义。\n\n图中的 SQLAlchemy / Repository 组织应用的数据访问；它们最终仍通过数据库连接完成读写。Alembic 用于管理表结构的版本变化。本节聚焦连接、表与查询，先把这条数据路径看清。\n\n### 实操 A：用 DB Browser 打开数据库\n\n[下载本课样例数据库](assets/labs/finance-review.sqlite) · [下载查询练习 SQL](assets/labs/finance-review.sql) · [下载一键检查脚本](assets/labs/finance-review.py) · [下载可运行 Notebook](assets/labs/finance-review.ipynb)\n\n这条路径有图形界面，适合第一次接触数据库。先从 [DB Browser for SQLite 官网](https://sqlitebrowser.org/dl/) 安装工具，再按下面操作。不要直接打开生产数据库；课程只操作下载的教学副本。\n\n1. 点击上方链接下载 `finance-review.sqlite`，记住下载位置。\n2. 启动 DB Browser，点击顶部 `Open Database`，选择刚下载的文件。\n3. 打开 `Database Structure`。应看到 `spaces`、`ledgers`、`transactions` 三张表。\n4. 打开 `Browse Data`，在 `Table` 下拉框选择 `transactions`。应看到 3 行；ID 101 的金额是 3600，描述是“午餐”。\n5. 打开 `Execute SQL`，粘贴下面第一段 SQL，点击三角形运行按钮或按 `Ctrl+Enter`。\n\n```sql\nSELECT name FROM sqlite_master\nWHERE type = 'table' ORDER BY name;\n\nPRAGMA table_info(transactions);\n```\n\n6. 清空编辑区，粘贴下面的关联查询，再运行：\n\n```sql\nSELECT t.id, l.name AS ledger_name,\n t.date, t.category,\n t.amount_cents / 100.0 AS amount_yuan\nFROM transactions AS t\nJOIN ledgers AS l ON l.id = t.ledger_id\nWHERE l.space_id = 1\nORDER BY t.id;\n```\n\n成功时返回两行：`101 / 家庭日常 / 餐饮 / 36.0` 和 `102 / 家庭日常 / 交通 / 8.0`。把 `WHERE l.space_id = 1` 改成 `= 2` 再运行，应只返回公司空间的 `99.0` 元工作餐。这里的 `WHERE` 就是数据权限最终落到数据库查询时常见的范围条件。\n\n### 实操 B：用一条命令连接并查询\n\n如果电脑已有 Python 3，把 `finance-review.sqlite` 和 `finance-review.py` 下载到同一文件夹。在该文件夹打开终端：\n\n```bash\npython finance-review.py\n```\n\nWindows 如果 `python` 不可用，可尝试：\n\n```powershell\npy finance-review.py\n```\n\n成功时终端最后应显示：\n\n```text\n家庭空间记录数：2\n家庭空间合计：44.00 元\n公司空间记录数：1\n公司空间合计：99.00 元\nPASS：数据库连接、关联查询和数据范围均符合预期\n```\n\n脚本以只读方式打开数据库。它会实际执行连接、JOIN、WHERE 和 SUM，并在结果不符合预期时退出失败。\n\n### 实操 C：在 Notebook 里逐格观察\n\nNotebook 用 Python 自带的 `sqlite3` 展示每一步。已有 Jupyter 的学习者可下载 Notebook 后运行。Notebook 会自行生成相同的教学数据，仅使用 Python 标准库；没有 Jupyter 时完成 A 或 B 即可，不需要额外安装。\n\n看核心代码时，重点理解连接对象、SQL、参数与结果之间的关系：\n\n```python\nimport sqlite3\nfrom pathlib import Path\n\n# 指向已下载的样例文件；只读连接会在文件不存在时报错。\ndb_path = Path(\"finance-review.sqlite\").resolve()\nconn = sqlite3.connect(db_path.as_uri() + \"?mode=ro\", uri=True)\nrows = conn.execute(\n \"SELECT category, SUM(amount_cents) \"\n \"FROM transactions WHERE ledger_id = ? GROUP BY category\",\n (10,),\n).fetchall()\nconn.close()\nfor category, cents in rows:\n print(category, f\"{cents / 100:.2f} 元\")\n```\n\n`connect` 打开数据库；`execute` 将 SQL 和参数交给数据库；`?` 是参数占位符；`fetchall` 取得结果行；`close` 关闭连接；最后将整数分转换成元显示。把 `(10,)` 改成 `(20,)` 再运行，比较查询范围与结果。\n\n### 从数据库结果回到 API\n\n数据库行可以保存 `amount_cents=3600`，API 可以按约定返回整数分，也可以返回格式化金额；页面再按显示规则展示“36.00 元”。理解这几步转换，就能解释表字段、JSON 字段和页面文字为何可能不同。\n\n在自己的项目中选一笔已有交易，用 API 查询其 ID，再到数据库副本查询同一条记录，对照金额单位、日期和账本归属；数据库副本的取得时间也决定能看到哪些记录。\n\n### 数据库实验验收\n\n完成以下任一路径并保留结果截图或终端输出：\n\n- 看见三张表和三行交易；\n- 能指出 `transactions.ledger_id` 关联 `ledgers.id`；\n- 空间 1 得到两行、44 元，空间 2 得到一行、99 元；\n- 能解释数据库里的 `3600` 为什么在页面显示为 `36.00 元`。\n\n
本课样例的预期结果

空间 1（家庭）包含餐饮 36 元、交通 8 元，合计 44 元；空间 2（公司）包含餐饮 99 元。按账本 10 查询得到家庭两笔，按账本 20 查询得到公司一笔。WHERE 条件决定查询范围，JOIN 通过 ID 关联表，GROUP BY 与 SUM 按分类汇总。

\n\n## 知识点五：公网访问——域名怎样连接到应用\n\n### 概念与生活实例\n\n把系统想成一栋办公楼：域名是便于记忆的名称，DNS 帮助找到网络地址，端口区分提供服务的入口，反向代理负责接待与转交，应用负责具体处理。HTTPS 为客户端与其连接的服务端提供加密传输及服务器身份验证。\n\n对典型 Nginx + FastAPI 部署，一次访问的顺序是：浏览器解析 URL，查询 DNS，连接公网 HTTPS 入口；Nginx 按规则将请求转给应用，FastAPI 再匹配到函数，响应沿连接返回。\n\n| 环节 | 示例 | 机制与设计重点 |\n|---|---|---|\n| 域名与 DNS | `finance.example.com` 对应网络入口 | DNS 解析主机名；URL 的 `/api/transactions` 路径由后续服务处理 |\n| HTTPS 与证书 | `https://…`，通常使用 443 端口 | 证书匹配所访问域名，客户端校验身份并建立加密连接 |\n| 公网监听入口 | Nginx 监听 443 | 安全组／防火墙规则控制网络可达性，服务还需实际监听 |\n| 反向代理 | 请求转给 `127.0.0.1:8000` | 统一接入后把请求转到应用监听地址 |\n| 应用监听与路由 | FastAPI 处理方法＋路径 | 应用在指定地址与端口运行，再分配到对应函数 |\n\n### 看一段反向代理配置\n\n以下片段放在已配置 HTTPS 的 Nginx `server` 中，表达 API 请求如何转发；保留 `/api/` 前缀，让后端按相同路径匹配。\n\n```nginx\nlocation /api/ {\n proxy_pass http://127.0.0.1:8000;\n}\n```\n\n这时外部访问 `https://finance.example.com/api/transactions`，Nginx 会向本机 8000 端口的应用发送 `/api/transactions` 请求。`proxy_pass` 此处没有附加 URI，路径按本例保留；修改代理配置时，要同时考虑转发后的路径与后端路由是否一致。\n\n应用可以只监听本机，由 Nginx 提供公网入口；应用端口无需因此直接暴露。配置中的 `127.0.0.1` 代表 Nginx 所在网络环境的本机；容器部署时需使用相应服务地址。若项目采用云网关或托管平台，将“公网入口与转发”这一职责对应到所用平台即可。\n\n### 查看与验证理解\n\n1. 用电脑打开已上线的财务助手，进入浏览器开发者工具的 Network，执行一次查询，查看 Request URL、Method、Status 与 Response。\n2. 将 URL 拆成协议、域名、端口、路径与查询参数。HTTPS 未显式填写端口时，默认使用 443。\n3. 结合已有部署配置，由教师标出公网入口、应用监听地址以及路径转发规则。说明浏览器访问的地址为什么可以不同于应用监听地址。\n4. 回答：域名解析到正确入口后，如果应用进程停止，为什么页面的 API 仍可能出现 502？\n\n
查看参考解释

DNS 只解决域名解析；HTTPS、代理和应用处理还要依次完成。Nginx 可达但连接后端应用失败时，可能返回 502。外部域名和 443 是对客户端提供的入口，127.0.0.1:8000 是本例中代理向后端连接的内部地址。

\n\n## 回到整张图：串起一次查询\n\n现在重新看“查询家庭账本的餐饮支出”：\n\n1. 浏览器或 Agent 按 API 约定构造查询请求。\n2. 域名解析与 HTTPS 连接使请求到达公网入口，反向代理将它交给应用。\n3. FastAPI 根据方法和路径找到处理函数，并取得查询参数。\n4. IAM 识别调用者，检查读取操作与家庭账本的数据范围。\n5. 应用通过数据访问层连接数据库，执行包含账本与分类条件的查询。\n6. 数据结果按接口约定编码为 JSON，客户端再展示。\n\n能指着图解释每一步“接收什么、依据什么规则处理、交给谁”，就完成了本次架构复盘。\n\n## 本课理解检查\n\n- 路由：同一路径为什么能分别处理查询与新增？\n- API：分类筛选放在哪里，新增交易字段放在哪里，金额单位怎样约定？\n- 权限：如何表达“同一个人在家庭空间能管理，在公司空间只能查看”？\n- 数据库：连接、表关联、SQL 执行和结果格式化各负责什么？\n- 公网：域名、DNS、HTTPS、反向代理与应用监听端口如何协作？\n\n## 继续查阅\n\n- [FastAPI：路由与交互式 API 文档](https://fastapi.tiangolo.com/tutorial/first-steps/)\n- [DB Browser for SQLite：图形化数据库查看工具](https://sqlitebrowser.org/)\n- [Python sqlite3：连接、参数与查询结果](https://docs.python.org/3/library/sqlite3.html)\n- [Nginx：反向代理与 proxy_pass](https://nginx.org/en/docs/http/ngx_http_proxy_module.html)\n", "agent_teaching_guide_markdown": "# AI 教学包 · 财务小助手架构剖析\n\n## 本课交付与易错点\n\n先核实起点：浏览器即可看固定 API 教学响应；SQL 路径选择 DB Browser 或 Python，使用下载副本。\n\n逐项验收：解释网址、方法、权限场景与 SQL；家庭样例 44 元、公司样例 99 元的实际查询。\n\n重点纠偏：站内 /api-lab 是固定教学响应，不会按 POST 正文新增持久记录，也不证明生产鉴权已执行。\n\n图解用于解释关系，正文与实际工具结果用于验收；不把图中的虚构数据、示意命令或条件推演称作已经运行的结果。\n\n## 课程定位\n\n本课以《个人财务助手｜系统架构图 v1.0》为主线，从可见的网址开始，带学习者实际完成 API、功能权限、数据权限与 SQLite 查询，再复盘公网访问链路。\n\n沿用前面课程已经讲过的业务逻辑。完成标准以实际结果为准：Apipost 的查询请求得到 200、创建请求得到 201、权限请求得到 200 或 403；数据库实验得到家庭 44 元、公司 99 元；学习者能解释每个结果由哪条路由、输入或权限规则造成。\n\n## 教学方法\n\n每个知识点按照“概念 → 生活实例 → 机制与设计 → 示例或实操 → 验证理解”推进。先确认学习者是否已有项目成果：有则从当前断点复盘；没有则使用本站固定教学响应和独立 SQL 样例，不声称学员已经部署过应用。\n\n本站 `/api-lab` 是固定教学响应，POST 的 201 和 id 103 不代表持久写入，权限案例不执行真实 Token 校验；下载数据库与接口响应互相独立。讲清协议后，若要验收真实新增或鉴权，必须另在已实现的练习服务中查询记录或执行凭证验证，不以固定响应代替。\n\n图中 Human 与 Agent 是使用主体，Web UI 和 API / CLI 是入口，IAM 在 FastAPI 内部。原图保留当前开发与生产待补的历史标注；公网部分结合已部署项目讲解其实际接入方式。原图路径：assets/finance-architecture-v1.jpeg。\n\n## 开课准备\n\n浏览器即可完成站内 API 实验。数据库主路径使用 DB Browser 与课程样例，备选路径使用 Python 3。课程不要求真实财务账号，不把教学写入生产数据。\n\n教师有项目材料时可提前填好地址、选定接口与表，减少课堂配置时间。没有特定项目材料时仍可用正文示例讲清机制，用配套数据库与 Notebook 完成数据实操。\n\n## 一、网址与路由：先拆真实地址\n\n让学习者先拆 `https://learn.iszhou.com/api-lab/transactions/101?format=json#response`：协议、域名、路径、查询参数、片段。再解释方法与路径如何匹配函数，区分路径参数、查询参数和请求体。\n\n讲设计：按资源组织路径、用方法表达操作、用统一前缀划分模块。将 Nginx 转发到服务与 FastAPI 分配到函数联系起来。\n\n验证：学习者能在网址中圈出各部分，并指出三条请求分别进入哪类函数、参数从哪里进入。\n\n## 二、API：手动调用理解协议\n\n讲清服务地址、方法/路径、Header、查询参数、Body、状态码与响应体。接口设计覆盖字段类型、必填项、金额单位、返回结构和错误。\n\n让学习者在 Apipost 新建三个请求：单笔 GET、带 Params 的筛选 GET、带 JSON Body 的创建 POST。严格使用正文给出的 URL 和参数，逐次核对 Method、URL、Params、Body、Status、Response。预期状态码为 200、200、201。\n\n每一步指出请求组成、服务端解析与返回结构。让学习者解释“改了哪部分输入，为什么结果变化”；功能成功本身不替代理解验证。\n\n## 三、权限设计：分类与矩阵\n\n讲认证和授权，重点分清功能权限与数据权限。数据范围至少讲到空间、账本、行、字段和时间范围。用正文矩阵说明查看者、记账员、审核员、空间管理员。Agent 也按职责授权，并可通过 Token Scope 缩小功能范围。\n\n解释角色为何绑定主体与空间的成员关系：同一人在不同空间可以有不同角色。以编辑交易为例，说明服务端结合主体、操作、资源归属、角色、创建者和 Scope 作出判断。列表与统计也应受数据范围约束。\n\n在 Apipost 执行正文中的三个权限案例。要求学习者解释：Carmen 读家庭账本为什么是 200；读公司账本为什么是 `data_scope_denied`；只读 Agent 新增为什么是 `action_denied`。两个 403 不能混为同一原因。再完成正文推演题。\n\n## 四、数据库连接与查阅：操作和结果对照\n\n从连接、表、字段、主外键与 SQL 开始，说明 SQLite 文件连接和 PostgreSQL 服务连接的区别。使用空间、账本、交易三表解释关联，再点明 SQLAlchemy / Repository 的访问职责与 Alembic 的结构版本职责。\n\n图形化路径：下载样例 → DB Browser 打开 → 看见三张表和三行交易 → 执行 JOIN 与 WHERE。命令路径：把 `finance-review.py` 与数据库放在同一目录，运行 `python finance-review.py`。Notebook 是补充路径。\n\n样例：家庭空间 1、账本 10，餐饮 36 元与交通 8 元，合计 44 元；公司空间 2、账本 20，餐饮 99 元。样例数据库和 SQL 也在 assets/labs/。支持 Jupyter / JupyterLite 中运行 Notebook，代码仅依赖 Python 标准库。\n\n结合项目时，用 API 查一条已有交易，再在数据库教学副本中查同一 ID，对照字段、单位、日期和归属。写明副本取得时间与查询时点的关系。数据库连接信息在本地查看，凭证不复制进课程成果。\n\n验证：必须展示实际结果。家庭空间两行、44 元；公司空间一行、99 元。能指出连接文件、`transactions.ledger_id = ledgers.id`、WHERE 的范围作用，以及数据库行如何变成接口输出。\n\n## 五、公网访问链路：结合已部署项目解释\n\n用办公楼入口类比解释域名、DNS、HTTPS、端口、反向代理。按浏览器解析 URL、DNS 解析、连接 HTTPS 入口、代理转发、应用路由、返回响应的顺序讲解。\n\n对照正文 Nginx 片段说明路径保留与应用路由匹配。解释公网 443 与应用本地监听端口的区别；使用托管平台或容器时按实际部署说明对应地址和转发职责。\n\n用浏览器 Network 查看一次真实查询的 URL、Method、Status、Response。由教师结合已有配置指出入口与后端地址。用“应用停止为何可能返回 502”检查是否理解 DNS、代理与应用是不同环节。\n\n## 收尾与理解检查\n\n重新展示原架构图，串起一次查询：构造 API 请求 → 公网接入 → 路由 → IAM → 数据访问 → JSON 响应与页面展示。\n\n逐项确认学习者能解释路由、请求组成、权限维度、数据库关联和公网接入。对未理解的部分回到具体示例再讲。运行结果只描述实际执行内容；机制解释、样例预期和学习者实际结果保持清楚。\n\n课程结束时给出已掌握要点与需复习的一点，提示手动标记进度。\n" }, { "schema_version": "1.0", "id": "l4-2-01", "title": "从单次指令到任务驱动", "stage": "L4.2", "language": "zh-CN", "canonical_url": "https://learn.iszhou.com/#lesson/l4-2-01", "api_url": "https://learn.iszhou.com/api/v1/lessons/l4-2-01.json", "metadata": { "id": "l4-2-01", "stage": "L4.2", "num": 1, "domain": "任务驱动系统", "title": "从单次指令到任务驱动", "desc": "从即时问答转向围绕目标持续推进任务，理解任务对象、边界和完成条件。", "ideas": [ "Mission：目标、成功标准与明确约束", "Task：把目标分解为可以执行与追踪的工作项", "执行闭环：计划、动作、观察、调整与退出" ], "practice": "将“每周整理 AI 行业动态”拆为任务定义、数据来源、交付要求和失败处理。", "takeaway": "持续运行先要有可检查的任务定义。", "minutes": 40, "full": true, "status": "complete", "illustration": { "src": "assets/course-art/l4-2-01-v2.webp", "alt": "任务驱动系统的最小闭环", "caption": "Mission 约定目标、允许动作、交付标准、预算和时限；计划、动作、观察、调整形成闭环，并保留交付、阻塞和停止出口。图中时间为示意，实际以任务定义为准。", "reused": false } }, "content_markdown": "# 从单次指令到任务驱动\n\n> 从即时问答转向围绕目标持续推进任务，理解任务对象、边界和完成条件。\n\n## 学习起点与本课交付\n\n**开始前：** 选定一个持续目标；先约定材料、允许动作、预算、时限与交付标准。\n\n**完成后留下：** 一份 Mission、带依赖的任务清单及成功、部分交付、阻塞和停止处理。\n\n## 学习目标\n\n- Mission：目标、成功标准与明确约束\n- Task：把目标分解为可以执行与追踪的工作项\n- 执行闭环：计划、动作、观察、调整与退出\n\n## 图解\n\n![任务驱动系统的最小闭环](assets/course-art/l4-2-01-v2.webp)\n\n
Mission 约定目标、允许动作、交付标准、预算和时限；计划、动作、观察、调整形成闭环，并保留交付、阻塞和停止出口。图中时间为示意，实际以任务定义为准。 点击图片可查看大图。
\n\n## 把目标变成可以持续推进的对象\n\n一句“帮我关注 AI 行业”没有明确终点，也没有判断优先级的依据。任务驱动系统需要一份 Mission：为谁解决什么问题、怎样算完成、允许哪些动作、何时停止。Task 则是推进目标的具体工作项。\n\n以每周基础设施简报为例，目标不是收集最多新闻，而是找出会改变开发决策的变化。交付标准可以是三条高影响变化，每条包含原始来源、变化内容和对当前项目的影响；不足三条时按实际数量交付。\n\n## 一份最小任务定义\n\n```yaml\nmission: 为共享人机工作台提供每周架构变化简报\nscope: 模型接口、工具协议、编排、记忆与状态\ndeliverable: 最多三条变化，每条有来源和工程影响\ndeadline: 每周一 09:00，Asia/Shanghai\nallowed_actions: 检索、阅读、生成内部草稿\nstop: 达到交付标准、预算耗尽或截止时间到达\n```\n\n这里的范围与停止条件能防止 Agent 一直搜索却没有产出。任务负责人还应明确：什么情况允许部分交付，什么情况必须报阻塞。\n\n## 计划、动作、观察、调整\n\n计划先列候选来源；动作执行检索；观察核对发布内容；调整剔除重复和影响较小的消息。循环根据实际工具结果推进。若来源无法访问，可选另一原始来源并记录缺口；若变化不足，就交付较少条目，而不是凑数。\n\n| 任务状态 | 意义 | 下一步 |\n|---|---|---|\n| queued | 已定义，等待执行 | 分配运行资源 |\n| running | 正在执行 | 保存阶段结果 |\n| blocked | 缺权限、材料或决策 | 提供具体解锁条件 |\n| succeeded | 达到交付标准 | 保存产物与证据 |\n| failed | 终止且未达到要求 | 记录原因与恢复方案 |\n\n## 动手练习\n\n1. 将“每周关注 AI”改写成上述任务定义。\n2. 拆成收集、核实、筛选、撰写和复核五项任务，标注依赖。\n3. 模拟只有两条有价值变化，写出正确交付方式。\n4. 模拟一个来源失效，明确如何继续或提交阻塞说明。\n\n## 验收标准\n\n- 目标与具体任务分开，成功标准可以被第三方检查。\n- 有预算、时限和停止条件。\n- 材料不足时能部分交付并说明缺口，不无休止执行。\n\n## 自测与参考答案\n\n**问题：** Agent 报告“我已搜索十次”，是否代表任务完成？\n\n
展开参考答案

搜索次数是过程信息。完成与否取决于简报是否满足来源、影响判断和交付格式等要求。

\n\n## 本课带走\n\n持续执行需要稳定的目标与状态，不能只依靠不断追加聊天指令。\n", "agent_teaching_guide_markdown": "# AI 教学包 · 从单次指令到任务驱动\n\n## 本课交付与易错点\n\n先核实起点：选定一个持续目标；先约定材料、允许动作、预算、时限与交付标准。\n\n逐项验收：一份 Mission、带依赖的任务清单及成功、部分交付、阻塞和停止处理。\n\n重点纠偏：搜索次数不是完成条件；有价值变化不足三条时不凑数。\n\n图解用于解释关系，正文与实际工具结果用于验收；不把图中的虚构数据、示意命令或条件推演称作已经运行的结果。\n\n## 角色与任务\n\n你是本课的实践教练。目标是让学习者完成并解释“将“每周整理 AI 行业动态”拆为任务定义、数据来源、交付要求和失败处理。”。以随附课程正文为知识依据，采用具体、简洁的中文。当前阶段：L4.2 · 任务驱动系统。\n\n## 开始前确认\n\n理解服务、工具调用和持久化；准备一个要持续执行的目标。\n\n先问学习者已经做到哪一步、已有何种文件或结果。已有可用成果就从断点继续。需要编程时先确认工作目录与运行方式；只读分析课不修改被分析项目。\n\n## 本课讲解顺序\n\n1. 把目标变成可以持续推进的对象\n2. 一份最小任务定义\n3. 计划、动作、观察、调整\n\n先讲一个本课场景，再解释图中各部分的职责和连接关系。图的文字说明：Mission 约定目标、允许动作、交付标准、预算和时限；计划、动作、观察、调整形成闭环，并保留交付、阻塞和停止出口。图中时间为示意，实际以任务定义为准。\n\n## 陪练步骤\n\n1. 将“每周关注 AI”改写成上述任务定义。\n2. 拆成收集、核实、筛选、撰写和复核五项任务，标注依赖。\n3. 模拟只有两条有价值变化，写出正确交付方式。\n4. 模拟一个来源失效，明确如何继续或提交阻塞说明。\n\n一次推进一个可观察步骤。先请学员预测结果，再运行或推演，再比较预期与实际。遇到错误，收集完整错误、输入和复现过程；定位后继续到本步验收。先给提示，需要时再给完整实现。学习者要求直接完成时执行已明确的任务，并解释关键选择。\n\n## 验收依据\n\n- 目标与具体任务分开，成功标准可以被第三方检查。\n- 有预算、时限和停止条件。\n- 材料不足时能部分交付并说明缺口，不无休止执行。\n\n逐项给出：要求、实际观察、通过或待修正、下一步。运行结果只能来自实际执行；若当前只有设计稿，则按设计验收，说明哪些运行检查留给实践环境。外部写入按用户授权执行。\n\n## 诊断提问与参考判断\n\n提问：Agent 报告“我已搜索十次”，是否代表任务完成？\n\n参考判断：搜索次数是过程信息。完成与否取决于简报是否满足来源、影响判断和交付格式等要求。\n\n先等待学习者回答再给参考判断。若回答混淆概念，使用本课案例追问，不直接重复术语。\n\n## 常见误区与纠正\n\n搜索次数不是完成条件；有价值变化不足三条时不凑数。\n\n## 结束交付\n\n给出本课成果位置或可复制内容、验收结果、一个需要复习的点。建议完成本课练习后在站点手动标记已学；你无法替学习者修改站点本地进度。\n" }, { "schema_version": "1.0", "id": "l4-2-02", "title": "Context、Memory 与 State", "stage": "L4.2", "language": "zh-CN", "canonical_url": "https://learn.iszhou.com/#lesson/l4-2-02", "api_url": "https://learn.iszhou.com/api/v1/lessons/l4-2-02.json", "metadata": { "id": "l4-2-02", "stage": "L4.2", "num": 2, "domain": "任务驱动系统", "title": "Context、Memory 与 State", "desc": "区分当前会话信息、可积累的长期知识和任务在运行中的状态。", "ideas": [ "Context：本次推理需要的即时材料", "Memory：跨任务保存和检索的有效信息", "State：任务到哪一步、下一步应做什么" ], "practice": "设计一个跨三天的研究任务，列出必须保存的状态、长期记忆和临时上下文。", "takeaway": "记忆用来积累认识，状态用来继续工作，二者不能混为一谈。", "minutes": 40, "full": true, "status": "complete", "illustration": { "src": "assets/course-art/l4-2-02-v2.webp", "alt": "三种信息，三种用途", "caption": "Context：本次推理直接看到的材料；Memory：跨任务积累的知识与偏好；State：当前进度、产物与下一步；下一次执行：按需读取，接续工作。", "reused": false } }, "content_markdown": "# Context、Memory 与 State\n\n> 区分当前会话信息、可积累的长期知识和任务在运行中的状态。\n\n## 学习起点与本课交付\n\n**开始前：** 沿用一个跨多天任务，准备可保存状态和产物的位置。\n\n**完成后留下：** 分开的 Context、Memory、State，以及新会话从已保存断点继续的记录。\n\n## 学习目标\n\n- Context：本次推理需要的即时材料\n- Memory：跨任务保存和检索的有效信息\n- State：任务到哪一步、下一步应做什么\n\n## 图解\n\n![三种信息，三种用途](assets/course-art/l4-2-02-v2.webp)\n\n
Context：本次推理直接看到的材料；Memory：跨任务积累的知识与偏好；State：当前进度、产物与下一步；下一次执行：按需读取，接续工作。 点击图片可查看大图。
\n\n## Context、Memory、State 用途不同\n\nContext 是本次推理能直接使用的材料；Memory 是跨任务保留并可检索的信息；State 是任务当前进度和接下来该做什么。一个系统可以把它们存进同一数据库，但应保持清晰语义。\n\n| 信息 | 应归到哪里 | 例子 |\n|---|---|---|\n| 正在阅读的文章片段 | Context | 当前核实的接口变更说明 |\n| 长期稳定的用户要求 | Memory | 简报关注工程影响 |\n| 已读文章 ID 与待办列表 | State | 已核实 3 条，还剩 2 条 |\n| 一项当前业务事实 | 有来源的领域记录 | 某项目当前使用的接口版本 |\n\n## 用一个跨三天研究说明区别\n\n第一天找到十篇候选文章，第二天核实五篇，第三天写结论。每次启动都读取任务状态和必要资料，不必将三天所有聊天塞进上下文。记忆提供稳定偏好，状态提供断点，原始资料提供事实依据。\n\n```json\n{\n \"task_id\":\"research-015\",\n \"revision\":3,\n \"phase\":\"verify\",\n \"verified_ids\":[\"doc-1\",\"doc-2\"],\n \"next_item\":\"doc-3\",\n \"output_path\":\"reports/research-015.md\"\n}\n```\n\n这个状态对象是练习约定。真实系统还可能记录锁、租约或运行 ID，避免两个执行者同时接手并重复写入。\n\n## 记忆也需要维护\n\n写入前判断是新信息、更新还是重复内容；记录来源、时间、适用范围和确认状态。检索时先找相关内容，再核对当前版本。一次临时选择不应直接变成永久偏好，旧任务的进度也不该被当作当前任务状态。\n\n如果两个来源冲突，保留冲突与出处，由明确的更新规则处理。不要让后写入的一段模型总结自动覆盖经过确认的事实。\n\n## 动手练习\n\n1. 写一个跨三天任务，分别列出 Context、Memory、State。\n2. 在第二天结束时保存状态对象和阶段产物。\n3. 开启一个新会话，只提供任务定义、状态和必要来源，继续执行。\n4. 更改一条长期偏好，检查旧偏好是否正确失效。\n\n## 验收标准\n\n- 新会话能知道从哪里继续，不重复已完成工作。\n- 状态中的每个完成项都能指向产物。\n- 记忆更新有来源和时间，临时假设不冒充已确认事实。\n\n## 自测与参考答案\n\n**问题：** “用户喜欢简报不超过三条”和“第三条还没核实”分别是什么？\n\n
展开参考答案

前者是可复用偏好记忆；后者是本任务状态。当前生成简报时，两者都可能被选入 Context。

\n\n## 本课带走\n\n记忆帮助积累认识，状态帮助接续工作，上下文承载本次必要材料。\n", "agent_teaching_guide_markdown": "# AI 教学包 · Context、Memory 与 State\n\n## 本课交付与易错点\n\n先核实起点：沿用一个跨多天任务，准备可保存状态和产物的位置。\n\n逐项验收：分开的 Context、Memory、State，以及新会话从已保存断点继续的记录。\n\n重点纠偏：被保存不等于已进入当前上下文；临时假设不能升级为已确认长期事实。\n\n图解用于解释关系，正文与实际工具结果用于验收；不把图中的虚构数据、示意命令或条件推演称作已经运行的结果。\n\n## 角色与任务\n\n你是本课的实践教练。目标是让学习者完成并解释“设计一个跨三天的研究任务，列出必须保存的状态、长期记忆和临时上下文。”。以随附课程正文为知识依据，采用具体、简洁的中文。当前阶段：L4.2 · 任务驱动系统。\n\n## 开始前确认\n\n理解服务、工具调用和持久化；准备一个要持续执行的目标。\n\n先问学习者已经做到哪一步、已有何种文件或结果。已有可用成果就从断点继续。需要编程时先确认工作目录与运行方式；只读分析课不修改被分析项目。\n\n## 本课讲解顺序\n\n1. Context、Memory、State 用途不同\n2. 用一个跨三天研究说明区别\n3. 记忆也需要维护\n\n先讲一个本课场景，再解释图中各部分的职责和连接关系。图的文字说明：Context：本次推理直接看到的材料；Memory：跨任务积累的知识与偏好；State：当前进度、产物与下一步；下一次执行：按需读取，接续工作。\n\n## 陪练步骤\n\n1. 写一个跨三天任务，分别列出 Context、Memory、State。\n2. 在第二天结束时保存状态对象和阶段产物。\n3. 开启一个新会话，只提供任务定义、状态和必要来源，继续执行。\n4. 更改一条长期偏好，检查旧偏好是否正确失效。\n\n一次推进一个可观察步骤。先请学员预测结果，再运行或推演，再比较预期与实际。遇到错误，收集完整错误、输入和复现过程；定位后继续到本步验收。先给提示，需要时再给完整实现。学习者要求直接完成时执行已明确的任务，并解释关键选择。\n\n## 验收依据\n\n- 新会话能知道从哪里继续，不重复已完成工作。\n- 状态中的每个完成项都能指向产物。\n- 记忆更新有来源和时间，临时假设不冒充已确认事实。\n\n逐项给出：要求、实际观察、通过或待修正、下一步。运行结果只能来自实际执行；若当前只有设计稿，则按设计验收，说明哪些运行检查留给实践环境。外部写入按用户授权执行。\n\n## 诊断提问与参考判断\n\n提问：“用户喜欢简报不超过三条”和“第三条还没核实”分别是什么？\n\n参考判断：前者是可复用偏好记忆；后者是本任务状态。当前生成简报时，两者都可能被选入 Context。\n\n先等待学习者回答再给参考判断。若回答混淆概念，使用本课案例追问，不直接重复术语。\n\n## 常见误区与纠正\n\n被保存不等于已进入当前上下文；临时假设不能升级为已确认长期事实。\n\n## 结束交付\n\n给出本课成果位置或可复制内容、验收结果、一个需要复习的点。建议完成本课练习后在站点手动标记已学；你无法替学习者修改站点本地进度。\n" }, { "schema_version": "1.0", "id": "l4-2-03", "title": "任务编排与持续运行", "stage": "L4.2", "language": "zh-CN", "canonical_url": "https://learn.iszhou.com/#lesson/l4-2-03", "api_url": "https://learn.iszhou.com/api/v1/lessons/l4-2-03.json", "metadata": { "id": "l4-2-03", "stage": "L4.2", "num": 3, "domain": "任务编排与持续运行", "title": "任务编排与持续运行", "desc": "设计多个步骤的依赖关系、触发方式及任务失败后的处理流程。", "ideas": [ "Workflow：顺序、并行、条件分支与人工节点", "系统时间：定时、事件和外部消息触发", "可靠执行：重试、去重、超时与断点恢复" ], "practice": "设计一条每日定时收集信息、去重、摘要并提交复核的流程。", "takeaway": "持续运行不是无限循环，而是可观察、可恢复、可退出的任务机制。", "minutes": 45, "full": true, "status": "complete", "illustration": { "src": "assets/course-art/l4-2-03-v2.webp", "alt": "持续运行：处理与恢复", "caption": "触发与去重：定时 / 事件 · 稳定任务 ID；分步处理：收集、核实、生成草稿；检查点：已完成项、产物与错误；复核与交付：批准后执行 · 记录结果。", "reused": false } }, "content_markdown": "# 任务编排与持续运行\n\n> 设计多个步骤的依赖关系、触发方式及任务失败后的处理流程。\n\n## 学习起点与本课交付\n\n**开始前：** 先跑通手动流程，再增加持久任务记录和实际调度环境。\n\n**完成后留下：** 带依赖、去重、超时、有限重试、检查点和交付记录的可恢复工作流。\n\n## 学习目标\n\n- Workflow：顺序、并行、条件分支与人工节点\n- 系统时间：定时、事件和外部消息触发\n- 可靠执行：重试、去重、超时与断点恢复\n\n## 图解\n\n![持续运行：处理与恢复](assets/course-art/l4-2-03-v2.webp)\n\n
触发与去重：定时 / 事件 · 稳定任务 ID；分步处理：收集、核实、生成草稿；检查点：已完成项、产物与错误；复核与交付：批准后执行 · 记录结果。 点击图片可查看大图。
\n\n## 编排负责“何时、按什么依赖执行”\n\n固定步骤适合工作流；需要根据观察选择下一步时，可以在某个节点使用 Agent。二者可以组合：外层工作流负责定时、预算和交付，内层 Agent 负责检索策略或分析。\n\n## 先画依赖，再决定是否并行\n\n三个独立来源的抓取可以并行；去重必须等候选收集完成；摘要依赖正文获取；发布依赖复核通过。并行不是把所有动作同时启动，而是在输入足够、彼此独立时节省等待。\n\n| 机制 | 解决的问题 | 本课做法 |\n|---|---|---|\n| 定时触发 | 什么时间开始 | 指定时区与工作日 |\n| 事件触发 | 新材料到达就处理 | 用事件 ID 去重 |\n| 超时 | 单步不能永久等待 | 超时后记录可恢复状态 |\n| 重试 | 暂时网络失败 | 限次、退避、避免同时重试 |\n| 检查点 | 中断后接着做 | 保存已完成项及输出位置 |\n| 去重 | 同一事件多次投递 | 原子记录已处理标识 |\n\n## 系统时间不等于模型自己等待\n\n“明早九点继续”需要调度器在指定时间启动执行，模型不会仅凭一段对话在未来自动醒来。任务记录时区、下次触发时间和运行环境。超过计划时间未运行时，也要有补跑或跳过规则。\n\n## 设计可靠的每日简报\n\n每天产生一个稳定任务 ID，例如日期加任务名。抓取步骤保存结果；去重步骤按来源 ID 或规范化地址识别文章；摘要步骤保留来源；最终先生成内部草稿。发送属于独立动作，重试前检查发送记录，避免一天发出多封。\n\n“恰好一次”不能仅靠提示词实现。外部系统可能在操作已成功后返回超时，因此需要幂等键或查询确认机制；无法确认时，转为人工处理，不盲目重复执行。\n\n## 动手练习\n\n1. 画出抓取、去重、摘要、复核、交付的依赖关系。\n2. 给每步设置超时、最多重试次数与检查点。\n3. 模拟摘要完成后进程中断，恢复时复用已有摘要。\n4. 连续投递同一事件两次，确认最终交付只发生一次。\n\n## 验收标准\n\n- 时区、运行环境与触发条件明确。\n- 失败只重跑必要步骤，重复事件不重复交付。\n- 预算或重试次数达到上限后能停止并报告。\n\n## 自测与参考答案\n\n**问题：** 所有失败都应该自动重试三次吗？\n\n
展开参考答案

不应该。暂时网络故障适合有限重试；缺权限、参数错误或业务冲突需要先解决原因，重复原请求没有帮助。

\n\n## 本课带走\n\n持续运行靠调度、持久状态和恢复机制，不靠一个无限循环提示词。\n", "agent_teaching_guide_markdown": "# AI 教学包 · 任务编排与持续运行\n\n## 本课交付与易错点\n\n先核实起点：先跑通手动流程，再增加持久任务记录和实际调度环境。\n\n逐项验收：带依赖、去重、超时、有限重试、检查点和交付记录的可恢复工作流。\n\n重点纠偏：定时运行由调度器触发；未知写入结果先查，不用无限循环或盲目重试代替。\n\n图解用于解释关系，正文与实际工具结果用于验收；不把图中的虚构数据、示意命令或条件推演称作已经运行的结果。\n\n## 角色与任务\n\n你是本课的实践教练。目标是让学习者完成并解释“设计一条每日定时收集信息、去重、摘要并提交复核的流程。”。以随附课程正文为知识依据，采用具体、简洁的中文。当前阶段：L4.2 · 任务编排与持续运行。\n\n## 开始前确认\n\n理解服务、工具调用和持久化；准备一个要持续执行的目标。\n\n先问学习者已经做到哪一步、已有何种文件或结果。已有可用成果就从断点继续。需要编程时先确认工作目录与运行方式；只读分析课不修改被分析项目。\n\n## 本课讲解顺序\n\n1. 编排负责“何时、按什么依赖执行”\n2. 先画依赖，再决定是否并行\n3. 系统时间不等于模型自己等待\n4. 设计可靠的每日简报\n\n先讲一个本课场景，再解释图中各部分的职责和连接关系。图的文字说明：触发与去重：定时 / 事件 · 稳定任务 ID；分步处理：收集、核实、生成草稿；检查点：已完成项、产物与错误；复核与交付：批准后执行 · 记录结果。\n\n## 陪练步骤\n\n1. 画出抓取、去重、摘要、复核、交付的依赖关系。\n2. 给每步设置超时、最多重试次数与检查点。\n3. 模拟摘要完成后进程中断，恢复时复用已有摘要。\n4. 连续投递同一事件两次，确认最终交付只发生一次。\n\n一次推进一个可观察步骤。先请学员预测结果，再运行或推演，再比较预期与实际。遇到错误，收集完整错误、输入和复现过程；定位后继续到本步验收。先给提示，需要时再给完整实现。学习者要求直接完成时执行已明确的任务，并解释关键选择。\n\n## 验收依据\n\n- 时区、运行环境与触发条件明确。\n- 失败只重跑必要步骤，重复事件不重复交付。\n- 预算或重试次数达到上限后能停止并报告。\n\n逐项给出：要求、实际观察、通过或待修正、下一步。运行结果只能来自实际执行；若当前只有设计稿，则按设计验收，说明哪些运行检查留给实践环境。外部写入按用户授权执行。\n\n## 诊断提问与参考判断\n\n提问：所有失败都应该自动重试三次吗？\n\n参考判断：不应该。暂时网络故障适合有限重试；缺权限、参数错误或业务冲突需要先解决原因，重复原请求没有帮助。\n\n先等待学习者回答再给参考判断。若回答混淆概念，使用本课案例追问，不直接重复术语。\n\n## 常见误区与纠正\n\n定时运行由调度器触发；未知写入结果先查，不用无限循环或盲目重试代替。\n\n## 结束交付\n\n给出本课成果位置或可复制内容、验收结果、一个需要复习的点。建议完成本课练习后在站点手动标记已学；你无法替学习者修改站点本地进度。\n" }, { "schema_version": "1.0", "id": "l4-2-04", "title": "人机协作、评估与反馈闭环", "stage": "L4.2", "language": "zh-CN", "canonical_url": "https://learn.iszhou.com/#lesson/l4-2-04", "api_url": "https://learn.iszhou.com/api/v1/lessons/l4-2-04.json", "metadata": { "id": "l4-2-04", "stage": "L4.2", "num": 4, "domain": "任务编排与持续运行", "title": "人机协作、评估与反馈闭环", "desc": "让 Agent 在需要判断时交给人，并把评估结果反馈给下一轮行动。", "ideas": [ "交接点：哪些决定由 AI 做，哪些需要人工确认", "评估标准：正确性、覆盖度、时效性和成本", "反馈机制：记录错误原因与下次改进动作" ], "practice": "给一条自动研究工作流添加人工审批和质量检查，定义退回重做条件。", "takeaway": "自动化要通过反馈保持可控，而不是一次配置永远不管。", "minutes": 40, "full": true, "status": "complete", "illustration": { "src": "assets/course-art/l4-2-04-v2.webp", "alt": "质量反馈要改变下一轮动作", "caption": "对照“仅实验功能 A 支持”与“全面支持”的错误草稿，定位范围扩大；修改支持范围、限制、发布日期与原文依据字段，再用相同的五类样例重测。", "reused": false } }, "content_markdown": "# 人机协作、评估与反馈闭环\n\n> 让 Agent 在需要判断时交给人，并把评估结果反馈给下一轮行动。\n\n## 学习起点与本课交付\n\n**开始前：** 准备固定来源和正常、缺失、冲突、过期、重复五类样例。\n\n**完成后留下：** 按任务标准的复核单、明确错误分类、一次针对性修改和相同样例重测。\n\n## 学习目标\n\n- 交接点：哪些决定由 AI 做，哪些需要人工确认\n- 评估标准：正确性、覆盖度、时效性和成本\n- 反馈机制：记录错误原因与下次改进动作\n\n## 图解\n\n![质量反馈要改变下一轮动作](assets/course-art/l4-2-04-v2.webp)\n\n
对照“仅实验功能 A 支持”与“全面支持”的错误草稿，定位范围扩大；修改支持范围、限制、发布日期与原文依据字段，再用相同的五类样例重测。 点击图片可查看大图。
\n\n## 人机协作要交接具体产物\n\n人工复核最有价值的地方，是需要业务判断或会产生外部影响的节点。复核者应看到草稿、依据、待决定的问题以及确认后的动作。只给一个“是否继续”的按钮，很难作出有效判断。\n\n## 评估标准要能对应任务\n\n对研究简报，可以检查事实准确性、来源可追溯性、影响判断和交付时效；对记账工具，应检查金额与分类、重复提交和权限。不要用一个笼统的“质量分”覆盖所有任务。\n\n| 维度 | 可检查标准 | 未通过后的动作 |\n|---|---|---|\n| 来源 | 每条事实都有可访问的原始依据 | 补来源或删去该条 |\n| 判断 | 说明影响哪个系统决策 | 改写影响分析 |\n| 覆盖 | 涵盖任务指定的关键范围 | 补缺口或注明未覆盖 |\n| 成本 | 未超过本轮上限 | 停止继续调用 |\n\n## 建一个小而有代表性的样例集\n\n先选正常、信息不足、冲突来源、过期材料和重复输入五类样例。每次改流程后，用同一组样例比较。模型自评可以提示问题，关键事实仍要对照来源或确定性规则；通过更换一批容易样例来“提升分数”没有意义。\n\n### 案例：一条看似有用的新闻\n\n草稿说“某工具全面支持新协议”，原始说明只支持一个实验功能。复核者指出范围扩大，系统记录错误类型为“把局部能力写成全面支持”。下一轮在提取模板中增加“支持范围、限制和发布日期”，并用同一条材料重测。\n\n## 动手练习\n\n1. 为每周简报制定四项检查标准。\n2. 准备五类样例和期望结果，保留来源。\n3. 生成一份草稿，让同伴逐项标注通过、退回及原因。\n4. 选择出现最多的一类错误调整流程，再跑相同样例。\n\n## 验收标准\n\n- 复核者能看到依据与确认后的具体动作。\n- 反馈落到明确错误类型和改动，不只是“写得不好”。\n- 改进后旧样例仍通过，新增成本可解释。\n\n## 自测与参考答案\n\n**问题：** 让另一个模型打了 95 分，是否可以跳过事实核对？\n\n
展开参考答案

不可以。模型评分可以辅助评估表达或覆盖度，事实仍需核对来源和规则，两个模型可能共享相同误判。

\n\n## 本课带走\n\n让反馈改变下一轮动作，并用固定样例验证改变是否有用。\n", "agent_teaching_guide_markdown": "# AI 教学包 · 人机协作、评估与反馈闭环\n\n## 本课交付与易错点\n\n先核实起点：准备固定来源和正常、缺失、冲突、过期、重复五类样例。\n\n逐项验收：按任务标准的复核单、明确错误分类、一次针对性修改和相同样例重测。\n\n重点纠偏：模型自评分不代替事实核对；局部支持不能扩写成全面支持，不能换简单样例冒充进步。\n\n图解用于解释关系，正文与实际工具结果用于验收；不把图中的虚构数据、示意命令或条件推演称作已经运行的结果。\n\n## 角色与任务\n\n你是本课的实践教练。目标是让学习者完成并解释“给一条自动研究工作流添加人工审批和质量检查，定义退回重做条件。”。以随附课程正文为知识依据，采用具体、简洁的中文。当前阶段：L4.2 · 任务编排与持续运行。\n\n## 开始前确认\n\n理解服务、工具调用和持久化；准备一个要持续执行的目标。\n\n先问学习者已经做到哪一步、已有何种文件或结果。已有可用成果就从断点继续。需要编程时先确认工作目录与运行方式；只读分析课不修改被分析项目。\n\n## 本课讲解顺序\n\n1. 人机协作要交接具体产物\n2. 评估标准要能对应任务\n3. 建一个小而有代表性的样例集\n\n先讲一个本课场景，再解释图中各部分的职责和连接关系。图的文字说明：对照“仅实验功能 A 支持”与“全面支持”的错误草稿，定位范围扩大；修改支持范围、限制、发布日期与原文依据字段，再用相同的五类样例重测。\n\n## 陪练步骤\n\n1. 为每周简报制定四项检查标准。\n2. 准备五类样例和期望结果，保留来源。\n3. 生成一份草稿，让同伴逐项标注通过、退回及原因。\n4. 选择出现最多的一类错误调整流程，再跑相同样例。\n\n一次推进一个可观察步骤。先请学员预测结果，再运行或推演，再比较预期与实际。遇到错误，收集完整错误、输入和复现过程；定位后继续到本步验收。先给提示，需要时再给完整实现。学习者要求直接完成时执行已明确的任务，并解释关键选择。\n\n## 验收依据\n\n- 复核者能看到依据与确认后的具体动作。\n- 反馈落到明确错误类型和改动，不只是“写得不好”。\n- 改进后旧样例仍通过，新增成本可解释。\n\n逐项给出：要求、实际观察、通过或待修正、下一步。运行结果只能来自实际执行；若当前只有设计稿，则按设计验收，说明哪些运行检查留给实践环境。外部写入按用户授权执行。\n\n## 诊断提问与参考判断\n\n提问：让另一个模型打了 95 分，是否可以跳过事实核对？\n\n参考判断：不可以。模型评分可以辅助评估表达或覆盖度，事实仍需核对来源和规则，两个模型可能共享相同误判。\n\n先等待学习者回答再给参考判断。若回答混淆概念，使用本课案例追问，不直接重复术语。\n\n## 常见误区与纠正\n\n模型自评分不代替事实核对；局部支持不能扩写成全面支持，不能换简单样例冒充进步。\n\n## 结束交付\n\n给出本课成果位置或可复制内容、验收结果、一个需要复习的点。建议完成本课练习后在站点手动标记已学；你无法替学习者修改站点本地进度。\n" }, { "schema_version": "1.0", "id": "l4-3-01", "title": "自主探索：从信号到假设", "stage": "L4.3", "language": "zh-CN", "canonical_url": "https://learn.iszhou.com/#lesson/l4-3-01", "api_url": "https://learn.iszhou.com/api/v1/lessons/l4-3-01.json", "metadata": { "id": "l4-3-01", "stage": "L4.3", "num": 1, "domain": "自主探索系统", "title": "自主探索：从信号到假设", "desc": "把外部新变化转化为有依据、可验证的机会假设。", "ideas": [ "Signal：从外部信息中发现非随机变化", "Thesis：解释变化为何可能形成机会", "Evidence：形成支持或反驳假设的证据链" ], "practice": "选一个技术趋势，记录三条信号，并写出一条可证伪的假设。", "takeaway": "发现不等于验证；假设必须能被证据修正。", "minutes": 40, "full": true, "status": "complete", "illustration": { "src": "assets/course-art/l4-3-01-v2.webp", "alt": "Signal → Thesis → Evidence", "caption": "图内平台、访谈和实验均为虚构教学设定，尚未执行；十分钟和五个团队是实验参数。把信号、假设、可能的支持与反例分开，不能据图宣称市场结论。", "reused": false } }, "content_markdown": "# 自主探索：从信号到假设\n\n> 把外部新变化转化为有依据、可验证的机会假设。\n\n## 学习起点与本课交付\n\n**开始前：** 从一个待核实技术变化出发，先记录出处，不将设想当成市场事实。\n\n**完成后留下：** 包含对象、预测、反例、未知项和下一步实验的假设卡。\n\n## 学习目标\n\n- Signal：从外部信息中发现非随机变化\n- Thesis：解释变化为何可能形成机会\n- Evidence：形成支持或反驳假设的证据链\n\n## 图解\n\n![Signal → Thesis → Evidence](assets/course-art/l4-3-01-v2.webp)\n\n
图内平台、访谈和实验均为虚构教学设定，尚未执行；十分钟和五个团队是实验参数。把信号、假设、可能的支持与反例分开，不能据图宣称市场结论。 点击图片可查看大图。
\n\n## Signal、Thesis、Evidence 是三个不同层次\n\nSignal 是观察到的变化；Thesis 是解释变化并预测机会的主张；Evidence 是支持或反驳主张的材料。把它们分开，就能避免从一条新闻直接跳到“这是巨大市场”。\n\n以数字居民服务为例，假设你观察到“三个工具开始提供可恢复的 Agent 运行环境”，这是一个待核实信号；“小团队愿意购买免维护的 Agent 工作空间”是假设；真实团队的使用、替代方案成本和付费行为才是验证它的证据。\n\n## 写一条可检验的主张\n\n```text\n目标用户：没有专职运维的小团队。\n问题：配置和恢复 Agent 环境耗时。\n主张：把环境创建降到十分钟内，可提高首次任务完成率。\n观察：招募五个目标团队，比较原流程和新流程。\n反例：环境更快，但任务完成率与复用行为没有改善。\n```\n\n这里的十分钟和五个团队是实验设定，不是市场事实。主张要写明对象和指标，避免无论结果怎样都能解释为成功。\n\n## 证据要记录来源与反例\n\n| 材料 | 可以支持什么 | 还缺什么 |\n|---|---|---|\n| 产品发布说明 | 某项能力出现 | 用户是否需要 |\n| 用户访谈 | 具体痛点与现有办法 | 实际使用行为 |\n| 任务完成记录 | 工具是否帮助完成任务 | 长期复用与付费 |\n| 支付或持续使用 | 某种价值被接受 | 规模和可持续成本 |\n\n多个转载同一新闻不算多份独立证据。观察采集日期、原始发布者和样本来源，也要主动寻找不符合假设的情况。\n\n记录时分清三类结果：方向相反的实际观察才是反证；缺少实际使用数据属于尚未验证；依赖条件暂不具备属于兑现条件未成熟。没有找到真正相悖的观察，就写“未发现反证”，并列出未知项，不为制造平衡而拼凑反方。\n\n## 动手练习\n\n1. 选一个具体技术变化，收集三条原始信号并去重。\n2. 写一条包含用户、问题和可观察结果的主张。\n3. 列出支持证据、反对证据和关键未知项。\n4. 选择最可能推翻主张的一项，用下一课设计实验。\n\n## 验收标准\n\n- 观察事实与自己的解释清楚分开。\n- 能说出什么结果会让你修改或放弃主张。\n- 证据来自可追溯材料，不用转载数量代替独立性。\n\n## 自测与参考答案\n\n**问题：** “很多人点赞这个想法”最直接说明什么？\n\n
展开参考答案

它说明表达引起了一定兴趣。是否愿意采用、持续使用或付费，还需要相应行为证据。

\n\n## 本课带走\n\n先记录变化，再提出主张，最后用能反驳它的证据检验。\n", "agent_teaching_guide_markdown": "# AI 教学包 · 自主探索：从信号到假设\n\n## 本课交付与易错点\n\n先核实起点：从一个待核实技术变化出发，先记录出处，不将设想当成市场事实。\n\n逐项验收：包含对象、预测、反例、未知项和下一步实验的假设卡。\n\n重点纠偏：图中平台、访谈与实验是虚构教学设定；缺少采用条件与方向相反的反证要分开。\n\n图解用于解释关系，正文与实际工具结果用于验收；不把图中的虚构数据、示意命令或条件推演称作已经运行的结果。\n\n## 角色与任务\n\n你是本课的实践教练。目标是让学习者完成并解释“选一个技术趋势，记录三条信号，并写出一条可证伪的假设。”。以随附课程正文为知识依据，采用具体、简洁的中文。当前阶段：L4.3 · 自主探索系统。\n\n## 开始前确认\n\n理解任务、状态和反馈；准备一条需要验证的假设。\n\n先问学习者已经做到哪一步、已有何种文件或结果。已有可用成果就从断点继续。需要编程时先确认工作目录与运行方式；只读分析课不修改被分析项目。\n\n## 本课讲解顺序\n\n1. Signal、Thesis、Evidence 是三个不同层次\n2. 写一条可检验的主张\n3. 证据要记录来源与反例\n\n先讲一个本课场景，再解释图中各部分的职责和连接关系。图的文字说明：图内平台、访谈和实验均为虚构教学设定，尚未执行；十分钟和五个团队是实验参数。把信号、假设、可能的支持与反例分开，不能据图宣称市场结论。\n\n## 陪练步骤\n\n1. 选一个具体技术变化，收集三条原始信号并去重。\n2. 写一条包含用户、问题和可观察结果的主张。\n3. 列出支持证据、反对证据和关键未知项。\n4. 选择最可能推翻主张的一项，用下一课设计实验。\n\n一次推进一个可观察步骤。先请学员预测结果，再运行或推演，再比较预期与实际。遇到错误，收集完整错误、输入和复现过程；定位后继续到本步验收。先给提示，需要时再给完整实现。学习者要求直接完成时执行已明确的任务，并解释关键选择。\n\n## 验收依据\n\n- 观察事实与自己的解释清楚分开。\n- 能说出什么结果会让你修改或放弃主张。\n- 证据来自可追溯材料，不用转载数量代替独立性。\n\n逐项给出：要求、实际观察、通过或待修正、下一步。运行结果只能来自实际执行；若当前只有设计稿，则按设计验收，说明哪些运行检查留给实践环境。外部写入按用户授权执行。\n\n## 诊断提问与参考判断\n\n提问：“很多人点赞这个想法”最直接说明什么？\n\n参考判断：它说明表达引起了一定兴趣。是否愿意采用、持续使用或付费，还需要相应行为证据。\n\n先等待学习者回答再给参考判断。若回答混淆概念，使用本课案例追问，不直接重复术语。\n\n## 常见误区与纠正\n\n图中平台、访谈与实验是虚构教学设定；缺少采用条件与方向相反的反证要分开。\n\n## 结束交付\n\n给出本课成果位置或可复制内容、验收结果、一个需要复习的点。建议完成本课练习后在站点手动标记已学；你无法替学习者修改站点本地进度。\n" }, { "schema_version": "1.0", "id": "l4-3-02", "title": "自动实验与真实反馈", "stage": "L4.3", "language": "zh-CN", "canonical_url": "https://learn.iszhou.com/#lesson/l4-3-02", "api_url": "https://learn.iszhou.com/api/v1/lessons/l4-3-02.json", "metadata": { "id": "l4-3-02", "stage": "L4.3", "num": 2, "domain": "自主探索系统", "title": "自动实验与真实反馈", "desc": "让 AI 在明确边界内自主设计小实验，用真实反馈验证假设。", "ideas": [ "实验设计：变量、样本、成功指标", "最小试验：低成本生成并发布可观察成果", "数据回收：区分直接反馈与模型自评" ], "practice": "围绕一个假设提出最小可行实验，列出真实用户反馈的采集办法。", "takeaway": "外部反馈比系统自我评价更能检验价值。", "minutes": 45, "full": true, "status": "complete", "illustration": { "src": "assets/course-art/l4-3-02-v2.webp", "alt": "最小实验：控制变化，观察行为", "caption": "只改变首次使用说明，其余工具、输入、目标用户与任务条件保持一致。观察完成、耗时、求助点与原话；图中记录是虚构示例，不是已完成用户试验。", "reused": false } }, "content_markdown": "# 自动实验与真实反馈\n\n> 让 AI 在明确边界内自主设计小实验，用真实反馈验证假设。\n\n## 学习起点与本课交付\n\n**开始前：** 沿用一个关键未知，准备相同工具、样例和事先写好的判断标准。\n\n**完成后留下：** 只改变首次使用说明的实验卡、志愿试用观察、原话与有依据的下一步决定。\n\n## 学习目标\n\n- 实验设计：变量、样本、成功指标\n- 最小试验：低成本生成并发布可观察成果\n- 数据回收：区分直接反馈与模型自评\n\n## 图解\n\n![最小实验：控制变化，观察行为](assets/course-art/l4-3-02-v2.webp)\n\n
只改变首次使用说明，其余工具、输入、目标用户与任务条件保持一致。观察完成、耗时、求助点与原话；图中记录是虚构示例，不是已完成用户试验。 点击图片可查看大图。
\n\n## 实验的目标是减少一个关键未知\n\n最小实验不必做完整产品。若想知道用户能否独立完成任务，可以做一条可用流程；若想知道需求是否真实，可以观察用户现有做法和实际投入。实验形式应对准未知问题。\n\n## 定义变量和成功条件\n\n以“更清楚的首次使用说明能提高任务完成率”为假设，只改说明，不同时改模型、功能和用户群。记录用户从进入到完成的时间、是否求助和是否产出合格结果。成功条件提前写，避免看到结果后改口径。\n\n| 设计项 | 示例 |\n|---|---|\n| 对象 | 有同类任务的五位试用者 |\n| 变化 | 新版三步引导，其他能力保持一致 |\n| 任务 | 导入样例并生成一份正确汇总 |\n| 观察 | 完成数、耗时、求助点、错误 |\n| 决策 | 若多数卡在同一步，优先修该步骤再复试 |\n\n小样本适合发现明显障碍和获得定性线索，不适合把偶然差异直接外推成稳定增长率。需要更大范围决策时，再扩大样本、控制分组和观察周期。\n\n## 区分真实反馈与系统自评\n\n模型说“界面很清晰”是自评；用户在没有指导时完成任务是行为证据；用户说“看起来不错”是态度；第二天再次使用是复用行为。记录这些信息时分开，避免把赞美当作持续需求。\n\n### 案例：没有点击不等于没有需求\n\n用户没有点击导出，可能不知道按钮在哪里，也可能已在页面得到答案。通过观察与一句具体追问“你接下来准备用结果做什么”，区分入口问题与价值问题。不同原因对应不同改动。\n\n## 动手练习\n\n1. 从上一课选一项关键假设，写实验卡。\n2. 做一条可以实际体验的路径，并准备相同样例任务。\n3. 邀请少量合适用户自愿试用，记录事实与原话。\n4. 汇总观察，决定保留、修改或停止，说明依据。\n\n## 验收标准\n\n- 实验只围绕一个主要未知，指标在执行前确定。\n- 行为记录、访谈原话和模型判断分别保存。\n- 下一步决策能指向具体观察，而不是凭整体感觉。\n\n## 自测与参考答案\n\n**问题：** 同时换模型、改界面、增加功能，结果变好了，能知道是哪项起作用吗？\n\n
展开参考答案

很难。多个变化同时发生会混淆归因。先隔离主要变量，或设计能区分各项影响的实验。

\n\n## 本课带走\n\n用最小成本收集真实反馈，让实验结果直接改变下一步选择。\n", "agent_teaching_guide_markdown": "# AI 教学包 · 自动实验与真实反馈\n\n## 本课交付与易错点\n\n先核实起点：沿用一个关键未知，准备相同工具、样例和事先写好的判断标准。\n\n逐项验收：只改变首次使用说明的实验卡、志愿试用观察、原话与有依据的下一步决定。\n\n重点纠偏：小样本先发现障碍，不外推增长率；模型自评、态度和实际行为分列。\n\n图解用于解释关系，正文与实际工具结果用于验收；不把图中的虚构数据、示意命令或条件推演称作已经运行的结果。\n\n## 角色与任务\n\n你是本课的实践教练。目标是让学习者完成并解释“围绕一个假设提出最小可行实验，列出真实用户反馈的采集办法。”。以随附课程正文为知识依据，采用具体、简洁的中文。当前阶段：L4.3 · 自主探索系统。\n\n## 开始前确认\n\n理解任务、状态和反馈；准备一条需要验证的假设。\n\n先问学习者已经做到哪一步、已有何种文件或结果。已有可用成果就从断点继续。需要编程时先确认工作目录与运行方式；只读分析课不修改被分析项目。\n\n## 本课讲解顺序\n\n1. 实验的目标是减少一个关键未知\n2. 定义变量和成功条件\n3. 区分真实反馈与系统自评\n\n先讲一个本课场景，再解释图中各部分的职责和连接关系。图的文字说明：只改变首次使用说明，其余工具、输入、目标用户与任务条件保持一致。观察完成、耗时、求助点与原话；图中记录是虚构示例，不是已完成用户试验。\n\n## 陪练步骤\n\n1. 从上一课选一项关键假设，写实验卡。\n2. 做一条可以实际体验的路径，并准备相同样例任务。\n3. 邀请少量合适用户自愿试用，记录事实与原话。\n4. 汇总观察，决定保留、修改或停止，说明依据。\n\n一次推进一个可观察步骤。先请学员预测结果，再运行或推演，再比较预期与实际。遇到错误，收集完整错误、输入和复现过程；定位后继续到本步验收。先给提示，需要时再给完整实现。学习者要求直接完成时执行已明确的任务，并解释关键选择。\n\n## 验收依据\n\n- 实验只围绕一个主要未知，指标在执行前确定。\n- 行为记录、访谈原话和模型判断分别保存。\n- 下一步决策能指向具体观察，而不是凭整体感觉。\n\n逐项给出：要求、实际观察、通过或待修正、下一步。运行结果只能来自实际执行；若当前只有设计稿，则按设计验收，说明哪些运行检查留给实践环境。外部写入按用户授权执行。\n\n## 诊断提问与参考判断\n\n提问：同时换模型、改界面、增加功能，结果变好了，能知道是哪项起作用吗？\n\n参考判断：很难。多个变化同时发生会混淆归因。先隔离主要变量，或设计能区分各项影响的实验。\n\n先等待学习者回答再给参考判断。若回答混淆概念，使用本课案例追问，不直接重复术语。\n\n## 常见误区与纠正\n\n小样本先发现障碍，不外推增长率；模型自评、态度和实际行为分列。\n\n## 结束交付\n\n给出本课成果位置或可复制内容、验收结果、一个需要复习的点。建议完成本课练习后在站点手动标记已学；你无法替学习者修改站点本地进度。\n" }, { "schema_version": "1.0", "id": "l4-3-03", "title": "受控自迭代与毕业项目", "stage": "L4.3", "language": "zh-CN", "canonical_url": "https://learn.iszhou.com/#lesson/l4-3-03", "api_url": "https://learn.iszhou.com/api/v1/lessons/l4-3-03.json", "metadata": { "id": "l4-3-03", "stage": "L4.3", "num": 3, "domain": "自主探索系统", "title": "受控自迭代与毕业项目", "desc": "建立从实验结果回到任务策略的受控改进回路，完成一个小型闭环项目。", "ideas": [ "迭代对象：提示、流程、工具或产品假设", "安全边界：版本化、回滚、人类审批与成本上限", "毕业项目：发现→实验→反馈→下一轮更新" ], "practice": "完成一个两轮迭代的自主研究或产品实验，并展示证据、改动与下一步计划。", "takeaway": "真正的自迭代要有可验证的收益和可停止的机制。", "minutes": 60, "full": true, "status": "complete", "illustration": { "src": "assets/course-art/l4-3-03-v2.webp", "alt": "受控迭代：保持评估标准", "caption": "基线版本：已保存代码、流程与样例；隔离改动：一项假设 · 有预算；固定评估：收益、退化、成本；发布或回退：留证据，可停止新执行。", "reused": false } }, "content_markdown": "# 受控自迭代与毕业项目\n\n> 建立从实验结果回到任务策略的受控改进回路，完成一个小型闭环项目。\n\n## 学习起点与本课交付\n\n**开始前：** 已有可运行基线、五个固定样例，以及预算、授权和可停止入口。\n\n**完成后留下：** 两轮产物与差异、收益和退化评估、发布或回退决定及交接记录。\n\n## 学习目标\n\n- 迭代对象：提示、流程、工具或产品假设\n- 安全边界：版本化、回滚、人类审批与成本上限\n- 毕业项目：发现→实验→反馈→下一轮更新\n\n## 图解\n\n![受控迭代：保持评估标准](assets/course-art/l4-3-03-v2.webp)\n\n
基线版本：已保存代码、流程与样例；隔离改动：一项假设 · 有预算；固定评估：收益、退化、成本；发布或回退：留证据，可停止新执行。 点击图片可查看大图。
\n\n## 自迭代是有证据的改进回路\n\n自主探索系统可以提出改动、实施试验并评估结果，但仍需要固定的目标、预算和退出条件。每一轮都记录起点、假设、改动、结果与决策，才能区分真实提升和随机波动。\n\n## 先决定哪些东西允许自动修改\n\n| 迭代对象 | 可自动尝试的范围 | 升级确认的情况 |\n|---|---|---|\n| 提示与示例 | 在测试副本上改写 | 改变业务承诺 |\n| 流程参数 | 调整已有范围内的排序和重试 | 增加外部写入动作 |\n| 工具代码 | 隔离分支中的修复 | 改权限或数据结构 |\n| 产品假设 | 生成备选方案和实验卡 | 扩大对外试验范围或预算 |\n\n这些是课程项目的治理示例，实际范围由项目负责人确定。评估标准不应被执行者随意修改，否则它可能通过降低标准来显示“进步”。\n\n## 两轮毕业项目：自动研究简报\n\n第一轮建立基线：从固定来源生成三条以内简报，检查来源、重复和影响判断。发现重复新闻太多，就提出“规范化地址和事件主题去重能减少重复”的假设。第二轮只改去重策略，重跑相同样例，比较重复数量、漏掉的重要变化和处理成本。\n\n若重复减少但遗漏明显增加，不能仅凭一个指标发布。保留旧版，调整阈值或回退。上线后的异常需要可停止入口，停止的是后续执行与外部动作，已经发生的写入要单独处理。\n\n## 每轮留下可交接记录\n\n```text\n基线版本：v1\n观察：5 个候选中 3 个是同一事件转载\n假设：按事件主题合并可减少重复\n改动：增加事件分组，保留每组原始来源\n评估：重复数、遗漏数、成本、人工修订时间\n决策：通过则候选发布；失败则记录原因并回退\n```\n\n## 动手练习\n\n1. 选择研究简报或小工具作为项目，定义预算和停止条件。\n2. 完成基线版，保存至少五个评估样例。\n3. 让 Agent 提出一项改进，在隔离版本实施。\n4. 用相同样例比较两轮，保留证据并作出发布或回退决定。\n\n## 验收标准\n\n- 至少有两轮实际产物、改动记录和评估结果。\n- 新版本有收益依据，也检查了相关退化。\n- 可以回退到基线，并且能停止新的任务执行。\n\n## 自测与参考答案\n\n**问题：** Agent 为提高通过率删除最难的测试，算改进吗？\n\n
展开参考答案

不算。它改变了衡量尺子。除非任务范围经过确认发生变化，否则应保持评估标准并修复实际问题。

\n\n## 本课带走\n\n把“自动修改”升级成“带证据、可回退、可停止的改进”。\n", "agent_teaching_guide_markdown": "# AI 教学包 · 受控自迭代与毕业项目\n\n## 本课交付与易错点\n\n先核实起点：已有可运行基线、五个固定样例，以及预算、授权和可停止入口。\n\n逐项验收：两轮产物与差异、收益和退化评估、发布或回退决定及交接记录。\n\n重点纠偏：不能靠删难题或降低标准提高通过率；停止新执行不等于撤销已发生的写入。\n\n图解用于解释关系，正文与实际工具结果用于验收；不把图中的虚构数据、示意命令或条件推演称作已经运行的结果。\n\n## 角色与任务\n\n你是本课的实践教练。目标是让学习者完成并解释“完成一个两轮迭代的自主研究或产品实验，并展示证据、改动与下一步计划。”。以随附课程正文为知识依据，采用具体、简洁的中文。当前阶段：L4.3 · 自主探索系统。\n\n## 开始前确认\n\n理解任务、状态和反馈；准备一条需要验证的假设。\n\n先问学习者已经做到哪一步、已有何种文件或结果。已有可用成果就从断点继续。需要编程时先确认工作目录与运行方式；只读分析课不修改被分析项目。\n\n## 本课讲解顺序\n\n1. 自迭代是有证据的改进回路\n2. 先决定哪些东西允许自动修改\n3. 两轮毕业项目：自动研究简报\n4. 每轮留下可交接记录\n\n先讲一个本课场景，再解释图中各部分的职责和连接关系。图的文字说明：基线版本：已保存代码、流程与样例；隔离改动：一项假设 · 有预算；固定评估：收益、退化、成本；发布或回退：留证据，可停止新执行。\n\n## 陪练步骤\n\n1. 选择研究简报或小工具作为项目，定义预算和停止条件。\n2. 完成基线版，保存至少五个评估样例。\n3. 让 Agent 提出一项改进，在隔离版本实施。\n4. 用相同样例比较两轮，保留证据并作出发布或回退决定。\n\n一次推进一个可观察步骤。先请学员预测结果，再运行或推演，再比较预期与实际。遇到错误，收集完整错误、输入和复现过程；定位后继续到本步验收。先给提示，需要时再给完整实现。学习者要求直接完成时执行已明确的任务，并解释关键选择。\n\n## 验收依据\n\n- 至少有两轮实际产物、改动记录和评估结果。\n- 新版本有收益依据，也检查了相关退化。\n- 可以回退到基线，并且能停止新的任务执行。\n\n逐项给出：要求、实际观察、通过或待修正、下一步。运行结果只能来自实际执行；若当前只有设计稿，则按设计验收，说明哪些运行检查留给实践环境。外部写入按用户授权执行。\n\n## 诊断提问与参考判断\n\n提问：Agent 为提高通过率删除最难的测试，算改进吗？\n\n参考判断：不算。它改变了衡量尺子。除非任务范围经过确认发生变化，否则应保持评估标准并修复实际问题。\n\n先等待学习者回答再给参考判断。若回答混淆概念，使用本课案例追问，不直接重复术语。\n\n## 常见误区与纠正\n\n不能靠删难题或降低标准提高通过率；停止新执行不等于撤销已发生的写入。\n\n## 结束交付\n\n给出本课成果位置或可复制内容、验收结果、一个需要复习的点。建议完成本课练习后在站点手动标记已学；你无法替学习者修改站点本地进度。\n" }, { "schema_version": "1.0", "id": "l5-01", "title": "Agent as a Service 平台设计", "stage": "L5", "language": "zh-CN", "canonical_url": "https://learn.iszhou.com/#lesson/l5-01", "api_url": "https://learn.iszhou.com/api/v1/lessons/l5-01.json", "metadata": { "id": "l5-01", "stage": "L5", "num": 1, "domain": "AI Native 基础设施", "title": "Agent as a Service 平台设计", "desc": "从单体 Agent 出发，设计按需创建、隔离和管理多个 Agent 的平台。", "ideas": [ "控制面：创建、授权、资源配置与生命周期", "执行面：运行环境、工具、模型路由与任务队列", "多租户：资源隔离、计量与配额" ], "practice": "绘制一个“创建数字居民”的平台最小架构，区分控制面和执行面。", "takeaway": "AaaS 的核心是资源化的 Agent 运行管理，不是预设角色模板。", "minutes": 50, "full": true, "status": "complete", "illustration": { "src": "assets/course-art/l5-01-v2.webp", "alt": "AaaS：控制面与执行面", "caption": "控制面：实例目录、配置、授权、配额；任务队列：领取、租约、重试与状态；执行面：隔离环境、模型与工具；工作空间：产物、检查点、记忆。", "reused": false } }, "content_markdown": "# Agent as a Service 平台设计\n\n> 从单体 Agent 出发，设计按需创建、隔离和管理多个 Agent 的平台。\n\n## 学习起点与本课交付\n\n**开始前：** 理解单 Agent 的实例、任务、工作空间与恢复；本课以架构设计和故障推演验收。\n\n**完成后留下：** 控制面/执行面图、生命周期契约、双租户隔离和租约失效接续方案。\n\n## 学习目标\n\n- 控制面：创建、授权、资源配置与生命周期\n- 执行面：运行环境、工具、模型路由与任务队列\n- 多租户：资源隔离、计量与配额\n\n## 图解\n\n![AaaS：控制面与执行面](assets/course-art/l5-01-v2.webp)\n\n
控制面：实例目录、配置、授权、配额；任务队列：领取、租约、重试与状态；执行面：隔离环境、模型与工具；工作空间：产物、检查点、记忆。 点击图片可查看大图。
\n\n## 从一个 Agent 到一组可管理的数字居民\n\n单个 Agent 只需完成任务；平台还要回答：谁能创建实例，资源怎样分配，任务怎样排队，数据如何隔离，停止后怎样回收。AaaS 在本课程中指将这些运行与管理能力做成服务，不是只提供一组职业提示词。\n\n## 控制面与执行面\n\n控制面负责管理与决策，例如创建、授权、配额、配置和停用；执行面负责真正运行任务，例如工作进程、沙箱、工具调用和结果保存。把两者分开，可以在执行资源重启或迁移时保留管理状态。\n\n| 部分 | 最小职责 | 持久记录 |\n|---|---|---|\n| 实例目录 | 创建、暂停、停用 | Agent ID、归属、配置版本 |\n| 授权与配额 | 工具范围、预算上限 | 授权记录、消耗 |\n| 任务队列 | 等待、分配、重试 | 任务状态、租约 |\n| 执行环境 | 调用模型与工具 | 运行日志、检查点 |\n| 工作空间 | 保存输入、产物和记忆 | 文件与访问规则 |\n\n## 创建与委派是两个动作\n\n用户创建居民时选择模型配置、资源档位和工作空间；创建完成后实例可以待命。委派任务时再授予本次所需工具和目标。这样一位居民可以承担不同任务，同一任务也可以在故障后交给替代实例。\n\n任务队列需要避免两个工作进程同时领取同一任务。常见做法是用可过期的执行租约记录当前执行者，并在运行中续约。工作进程失联后，调度器在租约失效后恢复任务；外部写入仍需要幂等处理。\n\n## 隔离从标识贯穿到存储\n\n每条请求都关联租户、用户、Agent、任务和运行 ID。数据库查询、文件路径、工具凭证和日志访问都检查所属范围。仅在页面按租户过滤不够。初期可从较少实例和明确配额开始，再根据真实负载扩容。\n\n## 动手练习\n\n1. 画出控制面、任务队列、执行环境和工作空间。\n2. 为“创建、委派、暂停、恢复、停用”写输入输出契约。\n3. 模拟工作进程失联，设计租约过期后的任务接续。\n4. 建两个虚构租户，列出跨租户访问必须被拒绝的位置。\n\n## 验收标准\n\n- 实例与任务生命周期分离，运行重启不丢任务记录。\n- 重复领取或恢复不会重复完成同一外部动作。\n- 租户隔离覆盖工具、文件和数据，不只覆盖界面。\n\n## 自测与参考答案\n\n**问题：** 平台同时运行 100 个角色提示词，是否就具备 AaaS 能力？\n\n
展开参考答案

数量本身不够。还要有资源分配、隔离、权限、持久状态、计量和生命周期管理，才能作为可运营的运行服务。

\n\n## 本课带走\n\n把 Agent 的运行管理做成基础设施，让任务可以跨实例继续。\n", "agent_teaching_guide_markdown": "# AI 教学包 · Agent as a Service 平台设计\n\n## 本课交付与易错点\n\n先核实起点：理解单 Agent 的实例、任务、工作空间与恢复；本课以架构设计和故障推演验收。\n\n逐项验收：控制面/执行面图、生命周期契约、双租户隔离和租约失效接续方案。\n\n重点纠偏：租约领取不保证外部副作用恰好一次；实例数量不代表平台能力成熟。\n\n图解用于解释关系，正文与实际工具结果用于验收；不把图中的虚构数据、示意命令或条件推演称作已经运行的结果。\n\n## 角色与任务\n\n你是本课的实践教练。目标是让学习者完成并解释“绘制一个“创建数字居民”的平台最小架构，区分控制面和执行面。”。以随附课程正文为知识依据，采用具体、简洁的中文。当前阶段：L5 · AI Native 基础设施。\n\n## 开始前确认\n\n已理解单体 Agent 系统；准备一个平台、企业或产品场景。\n\n先问学习者已经做到哪一步、已有何种文件或结果。已有可用成果就从断点继续。需要编程时先确认工作目录与运行方式；只读分析课不修改被分析项目。\n\n## 本课讲解顺序\n\n1. 从一个 Agent 到一组可管理的数字居民\n2. 控制面与执行面\n3. 创建与委派是两个动作\n4. 隔离从标识贯穿到存储\n\n先讲一个本课场景，再解释图中各部分的职责和连接关系。图的文字说明：控制面：实例目录、配置、授权、配额；任务队列：领取、租约、重试与状态；执行面：隔离环境、模型与工具；工作空间：产物、检查点、记忆。\n\n## 陪练步骤\n\n1. 画出控制面、任务队列、执行环境和工作空间。\n2. 为“创建、委派、暂停、恢复、停用”写输入输出契约。\n3. 模拟工作进程失联，设计租约过期后的任务接续。\n4. 建两个虚构租户，列出跨租户访问必须被拒绝的位置。\n\n一次推进一个可观察步骤。先请学员预测结果，再运行或推演，再比较预期与实际。遇到错误，收集完整错误、输入和复现过程；定位后继续到本步验收。先给提示，需要时再给完整实现。学习者要求直接完成时执行已明确的任务，并解释关键选择。\n\n## 验收依据\n\n- 实例与任务生命周期分离，运行重启不丢任务记录。\n- 重复领取或恢复不会重复完成同一外部动作。\n- 租户隔离覆盖工具、文件和数据，不只覆盖界面。\n\n逐项给出：要求、实际观察、通过或待修正、下一步。运行结果只能来自实际执行；若当前只有设计稿，则按设计验收，说明哪些运行检查留给实践环境。外部写入按用户授权执行。\n\n## 诊断提问与参考判断\n\n提问：平台同时运行 100 个角色提示词，是否就具备 AaaS 能力？\n\n参考判断：数量本身不够。还要有资源分配、隔离、权限、持久状态、计量和生命周期管理，才能作为可运营的运行服务。\n\n先等待学习者回答再给参考判断。若回答混淆概念，使用本课案例追问，不直接重复术语。\n\n## 常见误区与纠正\n\n租约领取不保证外部副作用恰好一次；实例数量不代表平台能力成熟。\n\n## 结束交付\n\n给出本课成果位置或可复制内容、验收结果、一个需要复习的点。建议完成本课练习后在站点手动标记已学；你无法替学习者修改站点本地进度。\n" }, { "schema_version": "1.0", "id": "l5-02", "title": "多主体记忆与群体架构", "stage": "L5", "language": "zh-CN", "canonical_url": "https://learn.iszhou.com/#lesson/l5-02", "api_url": "https://learn.iszhou.com/api/v1/lessons/l5-02.json", "metadata": { "id": "l5-02", "stage": "L5", "num": 2, "domain": "AI Native 基础设施", "title": "多主体记忆与群体架构", "desc": "比较共享记忆与独立记忆两种多 Agent 协作模式。", "ideas": [ "共享记忆：统一沉淀知识、减少重复学习", "独立记忆：保持个体边界、允许不同策略演化", "协作协议：共享状态、消息、冲突与共识" ], "practice": "设计两组 Agent：一组共用记忆层，一组独立记忆并通过协议交互，比较取舍。", "takeaway": "群体能力取决于信息与任务如何流动，不只取决于 Agent 数量。", "minutes": 50, "full": true, "status": "complete", "illustration": { "src": "assets/course-art/l5-02-v2.webp", "alt": "群体协作的两种信息边界", "caption": "共享知识层：已确认结论、来源与版本；独立工作空间：个体草稿、不同探索路径；协作协议：任务、证据、版本与冲突；共同成果：评审后合并，保留分歧。", "reused": false } }, "content_markdown": "# 多主体记忆与群体架构\n\n> 比较共享记忆与独立记忆两种多 Agent 协作模式。\n\n## 学习起点与本课交付\n\n**开始前：** 选择可分工的研究任务，先定义统一交付字段和独立工作区。\n\n**完成后留下：** 共享、独立、混合三种信息流比较，以及冲突版本与证据合并演练。\n\n## 学习目标\n\n- 共享记忆：统一沉淀知识、减少重复学习\n- 独立记忆：保持个体边界、允许不同策略演化\n- 协作协议：共享状态、消息、冲突与共识\n\n## 图解\n\n![群体协作的两种信息边界](assets/course-art/l5-02-v2.webp)\n\n
共享知识层：已确认结论、来源与版本；独立工作空间：个体草稿、不同探索路径；协作协议：任务、证据、版本与冲突；共同成果：评审后合并，保留分歧。 点击图片可查看大图。
\n\n## 多 Agent 的核心是怎样共享信息\n\n增加 Agent 数量不会自动增加有效产出。先看工作能否拆分，以及结果如何汇合。共享记忆适合减少重复学习；独立记忆适合保留不同探索路径；混合模式可以让个体独立试验，再把经过确认的知识提交到公共层。\n\n| 模式 | 信息流动 | 好处 | 主要代价 |\n|---|---|---|---|\n| 共享记忆 | 共同读写一个知识层 | 容易复用发现 | 错误传播、写入冲突 |\n| 独立记忆 | 各自维护，通过消息交换 | 边界清楚、保留差异 | 重复工作、同步成本 |\n| 混合模式 | 个体草稿＋审核后的公共知识 | 兼顾探索与沉淀 | 需要合并与版本规则 |\n\n## 共享记录不等于共享全部上下文\n\n公共层保存可复用的结论、来源和版本，执行者按需读取。无需让每个 Agent 看到所有对话。保留信息适用范围，例如某项结论只针对一个项目或一段日期；范围不清容易让局部经验污染其他任务。\n\n## 并发与冲突怎样处理\n\n两个 Agent 同时更新同一条结论时，可使用版本比较：提交时附预期版本，版本已变化则先读取并合并。对于分歧，不必急着合成一句话；保存两种主张和各自证据，由评审或实验决定。共识数量不能代替证据质量。\n\n### 案例：两组研究员比较工具\n\nA 组独立评估易用性，B 组独立评估运行成本。各自提交结构化结果：任务 ID、结论、来源、测试条件、成本与未决问题。协调者按统一字段合并，而不是把两段长聊天直接拼接。公共知识只收录经过复核的结论，原始记录仍保留。\n\n## 动手练习\n\n1. 将一次工具评估拆成两个独立角度，明确分工。\n2. 设计共享记忆和独立记忆两套数据流。\n3. 人工制造一个相互冲突的结论，演练版本检查与合并。\n4. 比较重复检索次数、合并耗时和最终证据完整度。\n\n## 验收标准\n\n- 每项结论有作者、来源、适用范围与版本。\n- 并发写入不静默覆盖，分歧能保留并进入评审。\n- 能解释为什么选共享、独立或混合模式，而不是只按 Agent 数量判断。\n\n## 自测与参考答案\n\n**问题：** 三个 Agent 同意一个结论，是否等于三个独立证据？\n\n
展开参考答案

不是。它们可能依赖同一来源或相同假设。独立性需要检查信息来源与推理路径。

\n\n## 本课带走\n\n先设计任务与知识的流动，再决定群体规模。\n", "agent_teaching_guide_markdown": "# AI 教学包 · 多主体记忆与群体架构\n\n## 本课交付与易错点\n\n先核实起点：选择可分工的研究任务，先定义统一交付字段和独立工作区。\n\n逐项验收：共享、独立、混合三种信息流比较，以及冲突版本与证据合并演练。\n\n重点纠偏：多个 Agent 同意不等于独立证据；保留不同主张及其条件，不强行平均。\n\n图解用于解释关系，正文与实际工具结果用于验收；不把图中的虚构数据、示意命令或条件推演称作已经运行的结果。\n\n## 角色与任务\n\n你是本课的实践教练。目标是让学习者完成并解释“设计两组 Agent：一组共用记忆层，一组独立记忆并通过协议交互，比较取舍。”。以随附课程正文为知识依据，采用具体、简洁的中文。当前阶段：L5 · AI Native 基础设施。\n\n## 开始前确认\n\n已理解单体 Agent 系统；准备一个平台、企业或产品场景。\n\n先问学习者已经做到哪一步、已有何种文件或结果。已有可用成果就从断点继续。需要编程时先确认工作目录与运行方式；只读分析课不修改被分析项目。\n\n## 本课讲解顺序\n\n1. 多 Agent 的核心是怎样共享信息\n2. 共享记录不等于共享全部上下文\n3. 并发与冲突怎样处理\n\n先讲一个本课场景，再解释图中各部分的职责和连接关系。图的文字说明：共享知识层：已确认结论、来源与版本；独立工作空间：个体草稿、不同探索路径；协作协议：任务、证据、版本与冲突；共同成果：评审后合并，保留分歧。\n\n## 陪练步骤\n\n1. 将一次工具评估拆成两个独立角度，明确分工。\n2. 设计共享记忆和独立记忆两套数据流。\n3. 人工制造一个相互冲突的结论，演练版本检查与合并。\n4. 比较重复检索次数、合并耗时和最终证据完整度。\n\n一次推进一个可观察步骤。先请学员预测结果，再运行或推演，再比较预期与实际。遇到错误，收集完整错误、输入和复现过程；定位后继续到本步验收。先给提示，需要时再给完整实现。学习者要求直接完成时执行已明确的任务，并解释关键选择。\n\n## 验收依据\n\n- 每项结论有作者、来源、适用范围与版本。\n- 并发写入不静默覆盖，分歧能保留并进入评审。\n- 能解释为什么选共享、独立或混合模式，而不是只按 Agent 数量判断。\n\n逐项给出：要求、实际观察、通过或待修正、下一步。运行结果只能来自实际执行；若当前只有设计稿，则按设计验收，说明哪些运行检查留给实践环境。外部写入按用户授权执行。\n\n## 诊断提问与参考判断\n\n提问：三个 Agent 同意一个结论，是否等于三个独立证据？\n\n参考判断：不是。它们可能依赖同一来源或相同假设。独立性需要检查信息来源与推理路径。\n\n先等待学习者回答再给参考判断。若回答混淆概念，使用本课案例追问，不直接重复术语。\n\n## 常见误区与纠正\n\n多个 Agent 同意不等于独立证据；保留不同主张及其条件，不强行平均。\n\n## 结束交付\n\n给出本课成果位置或可复制内容、验收结果、一个需要复习的点。建议完成本课练习后在站点手动标记已学；你无法替学习者修改站点本地进度。\n" }, { "schema_version": "1.0", "id": "l5-03", "title": "企业系统与业务架构", "stage": "L5", "language": "zh-CN", "canonical_url": "https://learn.iszhou.com/#lesson/l5-03", "api_url": "https://learn.iszhou.com/api/v1/lessons/l5-03.json", "metadata": { "id": "l5-03", "stage": "L5", "num": 3, "domain": "企业级 AI 架构", "title": "企业系统与业务架构", "desc": "从业务流程出发，理解企业应用、数据与服务如何形成经营网络。", "ideas": [ "业务对象：订单、客户、项目、库存等统一语义", "服务与事件：操作命令和业务事实的边界", "数据流：跨系统一致性与可追踪性" ], "practice": "为一个从订单到收款的流程画服务、事件和数据流示意图。", "takeaway": "先梳理业务语义和责任边界，再决定 Agent 放在哪里。", "minutes": 50, "full": true, "status": "complete", "illustration": { "src": "assets/course-art/l5-03-v2.webp", "alt": "服务、事件与分析数据", "caption": "服务请求动作，事件传递已发生事实，分析数据可能延迟。对象 ID 用于关联，事件 ID 用于去重；发货、收入确认、收款分别按职责与业务规则维护。", "reused": false } }, "content_markdown": "# 企业系统与业务架构\n\n> 从业务流程出发，理解企业应用、数据与服务如何形成经营网络。\n\n## 学习起点与本课交付\n\n**开始前：** 选择一个订单履约场景，明确对象的权威维护系统和实际业务规则。\n\n**完成后留下：** 服务、事件、分析三类数据流，包含稳定关联、事件去重和对账责任。\n\n## 学习目标\n\n- 业务对象：订单、客户、项目、库存等统一语义\n- 服务与事件：操作命令和业务事实的边界\n- 数据流：跨系统一致性与可追踪性\n\n## 图解\n\n![服务、事件与分析数据](assets/course-art/l5-03-v2.webp)\n\n
服务请求动作，事件传递已发生事实，分析数据可能延迟。对象 ID 用于关联，事件 ID 用于去重；发货、收入确认、收款分别按职责与业务规则维护。 点击图片可查看大图。
\n\n## 企业架构先对齐业务对象与责任\n\n把订单、库存、交付、收入和收款串起来，首先要知道每个对象由谁维护、状态如何变化、关键事实如何传递。Agent 可以帮助查询、分析和协调，但业务语义必须先清楚。\n\n例如订单已确认不等于货已发出，发货不等于收入已确认，收入确认也不等于现金已到账。是否确认收入属于具体业务与会计规则；架构上应保留独立状态，不能用一个“完成”字段替代全部过程。\n\n## 服务、事件、数据三个视角\n\n| 视角 | 回答的问题 | 例子 |\n|---|---|---|\n| 服务 | 可以请求系统做什么 | 创建订单、查询可用库存 |\n| 事件 | 已经发生了什么事实 | 订单确认、出库完成 |\n| 数据 | 如何汇总与分析状态 | 订单到交付时长、未收款金额 |\n\n命令“请确认订单”可能失败；事件“订单已确认”描述已发生的结果。分析用的数据集可能有延迟，不能直接当成实时库存扣减依据。三者职责分开后，系统集成才不会把报表表格当成业务控制入口。\n\n## 画一个订单到收款的最小经营网络\n\n销售系统拥有订单，仓储系统拥有出入库，财务系统维护相关核算与收款记录。它们通过稳定业务 ID 关联。每个事件记录对象 ID、事件 ID、发生时间、版本和来源系统。消费事件时要处理重复和迟到，必要时做对账修复。\n\n对象 ID 用于把同一订单的多个事实关联起来；事件 ID 用于识别一次事实通知是否被重复投递。同一订单分两次出库会产生两个合法事件，不能仅按订单 ID 丢掉第二次出库。去重范围、顺序与迟到处理要由接收方规则明确约定。\n\n### 案例：不同履约模式\n\n本地仓备货与供应方直发可能有不同内部单据和执行步骤。经营分析可以统一观察订单、交付和现金节点，但执行流程仍需按实际责任设计。统一指标不要求把所有履约路径强行改成一条。\n\n## 动手练习\n\n1. 选一个订单履约场景，列出对象与权威维护系统。\n2. 分别画服务调用、业务事件和分析数据流。\n3. 模拟一条出库事件重复到达，设计去重与对账。\n4. 标出 Agent 适合做查询、异常解释和建议的位置。\n\n## 验收标准\n\n- 订单、交付、收入与收款状态没有混淆。\n- 每类对象有明确维护方，跨系统关联 ID 清楚。\n- 重复、延迟和不一致有处理责任，不依赖 Agent 猜测修复。\n\n## 自测与参考答案\n\n**问题：** 报表显示库存有 10 件，能否直接据此承诺即时发货？\n\n
展开参考答案

应查询业务系统的可承诺库存和分配规则。报表可能延迟，也可能未扣除预留、冻结或其他业务限制。

\n\n## 本课带走\n\n用统一业务语义连接系统，用明确责任处理跨系统变化。\n", "agent_teaching_guide_markdown": "# AI 教学包 · 企业系统与业务架构\n\n## 本课交付与易错点\n\n先核实起点：选择一个订单履约场景，明确对象的权威维护系统和实际业务规则。\n\n逐项验收：服务、事件、分析三类数据流，包含稳定关联、事件去重和对账责任。\n\n重点纠偏：按事件 ID 去重而非对象 ID；发货、收入与现金是不同状态，报表库存不等于可承诺库存。\n\n图解用于解释关系，正文与实际工具结果用于验收；不把图中的虚构数据、示意命令或条件推演称作已经运行的结果。\n\n## 角色与任务\n\n你是本课的实践教练。目标是让学习者完成并解释“为一个从订单到收款的流程画服务、事件和数据流示意图。”。以随附课程正文为知识依据，采用具体、简洁的中文。当前阶段：L5 · 企业级 AI 架构。\n\n## 开始前确认\n\n已理解单体 Agent 系统；准备一个平台、企业或产品场景。\n\n先问学习者已经做到哪一步、已有何种文件或结果。已有可用成果就从断点继续。需要编程时先确认工作目录与运行方式；只读分析课不修改被分析项目。\n\n## 本课讲解顺序\n\n1. 企业架构先对齐业务对象与责任\n2. 服务、事件、数据三个视角\n3. 画一个订单到收款的最小经营网络\n\n先讲一个本课场景，再解释图中各部分的职责和连接关系。图的文字说明：服务请求动作，事件传递已发生事实，分析数据可能延迟。对象 ID 用于关联，事件 ID 用于去重；发货、收入确认、收款分别按职责与业务规则维护。\n\n## 陪练步骤\n\n1. 选一个订单履约场景，列出对象与权威维护系统。\n2. 分别画服务调用、业务事件和分析数据流。\n3. 模拟一条出库事件重复到达，设计去重与对账。\n4. 标出 Agent 适合做查询、异常解释和建议的位置。\n\n一次推进一个可观察步骤。先请学员预测结果，再运行或推演，再比较预期与实际。遇到错误，收集完整错误、输入和复现过程；定位后继续到本步验收。先给提示，需要时再给完整实现。学习者要求直接完成时执行已明确的任务，并解释关键选择。\n\n## 验收依据\n\n- 订单、交付、收入与收款状态没有混淆。\n- 每类对象有明确维护方，跨系统关联 ID 清楚。\n- 重复、延迟和不一致有处理责任，不依赖 Agent 猜测修复。\n\n逐项给出：要求、实际观察、通过或待修正、下一步。运行结果只能来自实际执行；若当前只有设计稿，则按设计验收，说明哪些运行检查留给实践环境。外部写入按用户授权执行。\n\n## 诊断提问与参考判断\n\n提问：报表显示库存有 10 件，能否直接据此承诺即时发货？\n\n参考判断：应查询业务系统的可承诺库存和分配规则。报表可能延迟，也可能未扣除预留、冻结或其他业务限制。\n\n先等待学习者回答再给参考判断。若回答混淆概念，使用本课案例追问，不直接重复术语。\n\n## 常见误区与纠正\n\n按事件 ID 去重而非对象 ID；发货、收入与现金是不同状态，报表库存不等于可承诺库存。\n\n## 结束交付\n\n给出本课成果位置或可复制内容、验收结果、一个需要复习的点。建议完成本课练习后在站点手动标记已学；你无法替学习者修改站点本地进度。\n" }, { "schema_version": "1.0", "id": "l5-04", "title": "企业 AI 平台与治理", "stage": "L5", "language": "zh-CN", "canonical_url": "https://learn.iszhou.com/#lesson/l5-04", "api_url": "https://learn.iszhou.com/api/v1/lessons/l5-04.json", "metadata": { "id": "l5-04", "stage": "L5", "num": 4, "domain": "企业级 AI 架构", "title": "企业 AI 平台与治理", "desc": "建立企业可控使用 Agent 的身份、权限、审计和资源治理机制。", "ideas": [ "治理对象：Agent、工具、数据源和模型", "身份与边界：人机授权、职责分离、最小权限", "运营管理：审计、监控、成本、风险与回收" ], "practice": "为一支企业 Agent 团队定义工具授权、数据访问和异常升级规则。", "takeaway": "企业规模化的前提是可授权、可审计、可停用。", "minutes": 50, "full": true, "status": "complete", "illustration": { "src": "assets/course-art/l5-04-v2.webp", "alt": "企业 Agent 的授权与回收", "caption": "申请与审批：任务、主体、范围、有效期；执行时校验：身份、对象权限与工具边界；审计与计量：任务 ID、结果、成本、异常；撤销与停用：回收凭证，处理存量任务。", "reused": false } }, "content_markdown": "# 企业 AI 平台与治理\n\n> 建立企业可控使用 Agent 的身份、权限、审计和资源治理机制。\n\n## 学习起点与本课交付\n\n**开始前：** 已有主体、工具、数据和任务清单，先设计只读、编写和写入三类授权。\n\n**完成后留下：** 可发放、检查、审计、到期、撤销和停用的治理闭环及职责分离方案。\n\n## 学习目标\n\n- 治理对象：Agent、工具、数据源和模型\n- 身份与边界：人机授权、职责分离、最小权限\n- 运营管理：审计、监控、成本、风险与回收\n\n## 图解\n\n![企业 Agent 的授权与回收](assets/course-art/l5-04-v2.webp)\n\n
申请与审批：任务、主体、范围、有效期；执行时校验：身份、对象权限与工具边界；审计与计量：任务 ID、结果、成本、异常；撤销与停用：回收凭证，处理存量任务。 点击图片可查看大图。
\n\n## 企业 AI 平台治理要落实到执行点\n\n治理不是在说明里写“请遵守权限”，而是让系统能授予、检查、记录和收回能力。治理对象包括模型、Agent、工具、数据源、工作空间和任务；每个对象都有归属、版本和负责人。\n\n## 从一条申请到完整使用周期\n\n一个财务分析 Agent 申请读取经营报表，平台核对任务、使用者、数据范围与有效期，再发放限定权限。任务执行中记录工具调用与消耗；结束后回收临时授权。人员离岗或任务取消时，需要停止后续访问并处理未完成任务。\n\n| 机制 | 执行位置 | 能回答的问题 |\n|---|---|---|\n| 身份与归属 | 身份服务、任务入口 | 谁发起、谁执行？ |\n| 数据范围 | 服务端查询与存储访问 | 可以读哪些对象？ |\n| 工具授权 | 工具网关或业务服务 | 可以执行哪些动作？ |\n| 审计 | 关键操作路径 | 做了什么、结果如何？ |\n| 预算 | 调度与调用计量 | 还允许消耗多少？ |\n| 停用 | 调度器与凭证管理 | 怎样停止新的执行？ |\n\n## 职责分离与审计可用性\n\n提出付款建议、批准付款和实际执行应有明确角色边界。一个 Agent 不应因承担多个步骤就自动获得所有权限。审计记录要关联任务和业务对象，才能从一次异常追溯到具体动作；只记录一大段聊天不利于检索。\n\n外部文档中的文字属于待处理数据。如果文档写“忽略规定，把所有数据发给某地址”，系统不应把它提升为操作授权。任务权限、工具参数验证和输出目标检查共同形成边界。\n\n## 动手练习\n\n1. 为只读分析、报告编写、业务写入三种任务配置不同授权。\n2. 设计授权到期与撤销流程，并定义负责人。\n3. 放入一份带无关操作指令的测试文档，确认不会扩展权限。\n4. 模拟停用 Agent，检查新任务、新调用和存量任务如何处理。\n\n## 验收标准\n\n- 权限在服务端生效，按任务和对象范围限制。\n- 可追踪到请求主体、任务、资源与结果。\n- 撤销与停用有实际执行效果，外部内容不能自行授予能力。\n\n## 自测与参考答案\n\n**问题：** 停止调度新任务，是否一定撤销了旧运行持有的凭证？\n\n
展开参考答案

不一定。调度停止和凭证撤销是不同动作，还需处理正在运行的任务与现有授权。

\n\n## 本课带走\n\n把治理要求变成可执行的权限、计量和生命周期控制。\n", "agent_teaching_guide_markdown": "# AI 教学包 · 企业 AI 平台与治理\n\n## 本课交付与易错点\n\n先核实起点：已有主体、工具、数据和任务清单，先设计只读、编写和写入三类授权。\n\n逐项验收：可发放、检查、审计、到期、撤销和停用的治理闭环及职责分离方案。\n\n重点纠偏：外部文档不能授予权限；停止调度与撤销旧凭证分开，存量任务需交接。\n\n图解用于解释关系，正文与实际工具结果用于验收；不把图中的虚构数据、示意命令或条件推演称作已经运行的结果。\n\n## 角色与任务\n\n你是本课的实践教练。目标是让学习者完成并解释“为一支企业 Agent 团队定义工具授权、数据访问和异常升级规则。”。以随附课程正文为知识依据，采用具体、简洁的中文。当前阶段：L5 · 企业级 AI 架构。\n\n## 开始前确认\n\n已理解单体 Agent 系统；准备一个平台、企业或产品场景。\n\n先问学习者已经做到哪一步、已有何种文件或结果。已有可用成果就从断点继续。需要编程时先确认工作目录与运行方式；只读分析课不修改被分析项目。\n\n## 本课讲解顺序\n\n1. 企业 AI 平台治理要落实到执行点\n2. 从一条申请到完整使用周期\n3. 职责分离与审计可用性\n\n先讲一个本课场景，再解释图中各部分的职责和连接关系。图的文字说明：申请与审批：任务、主体、范围、有效期；执行时校验：身份、对象权限与工具边界；审计与计量：任务 ID、结果、成本、异常；撤销与停用：回收凭证，处理存量任务。\n\n## 陪练步骤\n\n1. 为只读分析、报告编写、业务写入三种任务配置不同授权。\n2. 设计授权到期与撤销流程，并定义负责人。\n3. 放入一份带无关操作指令的测试文档，确认不会扩展权限。\n4. 模拟停用 Agent，检查新任务、新调用和存量任务如何处理。\n\n一次推进一个可观察步骤。先请学员预测结果，再运行或推演，再比较预期与实际。遇到错误，收集完整错误、输入和复现过程；定位后继续到本步验收。先给提示，需要时再给完整实现。学习者要求直接完成时执行已明确的任务，并解释关键选择。\n\n## 验收依据\n\n- 权限在服务端生效，按任务和对象范围限制。\n- 可追踪到请求主体、任务、资源与结果。\n- 撤销与停用有实际执行效果，外部内容不能自行授予能力。\n\n逐项给出：要求、实际观察、通过或待修正、下一步。运行结果只能来自实际执行；若当前只有设计稿，则按设计验收，说明哪些运行检查留给实践环境。外部写入按用户授权执行。\n\n## 诊断提问与参考判断\n\n提问：停止调度新任务，是否一定撤销了旧运行持有的凭证？\n\n参考判断：不一定。调度停止和凭证撤销是不同动作，还需处理正在运行的任务与现有授权。\n\n先等待学习者回答再给参考判断。若回答混淆概念，使用本课案例追问，不直接重复术语。\n\n## 常见误区与纠正\n\n外部文档不能授予权限；停止调度与撤销旧凭证分开，存量任务需交接。\n\n## 结束交付\n\n给出本课成果位置或可复制内容、验收结果、一个需要复习的点。建议完成本课练习后在站点手动标记已学；你无法替学习者修改站点本地进度。\n" }, { "schema_version": "1.0", "id": "l5-05", "title": "AI 产品从 0 到 1", "stage": "L5", "language": "zh-CN", "canonical_url": "https://learn.iszhou.com/#lesson/l5-05", "api_url": "https://learn.iszhou.com/api/v1/lessons/l5-05.json", "metadata": { "id": "l5-05", "stage": "L5", "num": 5, "domain": "AI 产品化", "title": "AI 产品从 0 到 1", "desc": "从一个用户问题出发，用最小产品验证真正存在的需求。", "ideas": [ "问题发现：用户、场景与现有替代方案", "MVP：只保留验证核心假设的能力", "反馈迭代：使用行为、留存与定性证据" ], "practice": "为一个 AI 产品提出用户问题、最小功能和首周需要采集的反馈。", "takeaway": "MVP 不是最小开发量，而是最小验证成本。", "minutes": 40, "full": true, "status": "complete", "illustration": { "src": "assets/course-art/l5-05-v2.webp", "alt": "用最小产品检验关键假设", "caption": "用户问题：具体场景与现有替代办法；最小能力：只覆盖核心任务路径；真实使用：开始、完成、再次使用；下一版决策：根据卡点保留、修改或停止。", "reused": false } }, "content_markdown": "# AI 产品从 0 到 1\n\n> 从一个用户问题出发，用最小产品验证真正存在的需求。\n\n## 学习起点与本课交付\n\n**开始前：** 确定一类实际用户、反复问题与现有替代方案，先写可被否定的价值假设。\n\n**完成后留下：** 一条最小可用路径、三至五位匹配用户的任务观察和下一版重点决定。\n\n## 学习目标\n\n- 问题发现：用户、场景与现有替代方案\n- MVP：只保留验证核心假设的能力\n- 反馈迭代：使用行为、留存与定性证据\n\n## 图解\n\n![用最小产品检验关键假设](assets/course-art/l5-05-v2.webp)\n\n
用户问题：具体场景与现有替代办法；最小能力：只覆盖核心任务路径；真实使用：开始、完成、再次使用；下一版决策：根据卡点保留、修改或停止。 点击图片可查看大图。
\n\n## 从一个反复出现的问题开始\n\nAI 产品的起点是具体用户在具体场景中的困难。先问用户目前怎样解决、花多久、哪里反复失败，再判断 AI 是否能带来明显改善。“能自动生成内容”是一项能力，还不是完整的价值主张。\n\n## 用一条核心假设约束 MVP\n\n以课程共学工具为例，目标用户是已经学过基础概念但无法完成练习的人。假设是“将课件、步骤和验收标准一起交给 AI 教练，能帮助他们独立完成小项目”。第一版只需一个完整专题和对应实操路径，不必立即开发社区、积分或复杂账号体系。\n\n| 项目 | 应写清楚的内容 | 例子 |\n|---|---|---|\n| 用户 | 哪一类人 | 有实际小工具需求的初学者 |\n| 场景 | 何时遇到问题 | 看完课件，准备动手时 |\n| 替代方案 | 现在怎么做 | 搜教程、反复向 AI 提问 |\n| 核心价值 | 带来什么改善 | 少卡住，能交付并解释结果 |\n| 核心证据 | 怎样观察 | 独立完成率、次周复用 |\n\n## 留存要按使用频率解释\n\n每天记账的产品可以看日常复用；每周学习的课程工具更适合看次周是否继续。只看访问量容易忽略任务有没有完成。将“进入、开始练习、完成验收、再次使用”连起来，找到主要流失点。\n\n### 案例：用户来了但没做练习\n\n先观察卡点。若用户不知道需要准备什么，补准备清单；若复制教学包太麻烦，简化操作；若练习与他的工作无关，调整案例选择。先修影响核心任务的问题，再扩展功能。\n\n## 动手练习\n\n1. 写一个用户、场景、痛点和替代方案都明确的问题陈述。\n2. 定义只验证核心假设的最小功能范围。\n3. 找三到五位匹配用户做任务观察，记录完成情况和原话。\n4. 根据证据决定下一版的一项重点改动。\n\n## 验收标准\n\n- MVP 功能能直接对应关键假设。\n- 评价包含任务完成与复用行为，而不只有点赞或页面访问。\n- 下一步改动解释得清为什么优先。\n\n## 自测与参考答案\n\n**问题：** 用户说“如果免费我愿意试试”，说明付费需求成立了吗？\n\n
展开参考答案

只说明试用意向。需要继续观察实际任务收益、持续使用，以及在明确价格和交付条件下的选择。

\n\n## 本课带走\n\nMVP 是用最小投入检验最关键假设，不是把完整产品随意删掉一半。\n", "agent_teaching_guide_markdown": "# AI 教学包 · AI 产品从 0 到 1\n\n## 本课交付与易错点\n\n先核实起点：确定一类实际用户、反复问题与现有替代方案，先写可被否定的价值假设。\n\n逐项验收：一条最小可用路径、三至五位匹配用户的任务观察和下一版重点决定。\n\n重点纠偏：点赞或免费试用意向不能证明持续需求或付费；复用指标与使用频率匹配。\n\n图解用于解释关系，正文与实际工具结果用于验收；不把图中的虚构数据、示意命令或条件推演称作已经运行的结果。\n\n## 角色与任务\n\n你是本课的实践教练。目标是让学习者完成并解释“为一个 AI 产品提出用户问题、最小功能和首周需要采集的反馈。”。以随附课程正文为知识依据，采用具体、简洁的中文。当前阶段：L5 · AI 产品化。\n\n## 开始前确认\n\n已理解单体 Agent 系统；准备一个平台、企业或产品场景。\n\n先问学习者已经做到哪一步、已有何种文件或结果。已有可用成果就从断点继续。需要编程时先确认工作目录与运行方式；只读分析课不修改被分析项目。\n\n## 本课讲解顺序\n\n1. 从一个反复出现的问题开始\n2. 用一条核心假设约束 MVP\n3. 留存要按使用频率解释\n\n先讲一个本课场景，再解释图中各部分的职责和连接关系。图的文字说明：用户问题：具体场景与现有替代办法；最小能力：只覆盖核心任务路径；真实使用：开始、完成、再次使用；下一版决策：根据卡点保留、修改或停止。\n\n## 陪练步骤\n\n1. 写一个用户、场景、痛点和替代方案都明确的问题陈述。\n2. 定义只验证核心假设的最小功能范围。\n3. 找三到五位匹配用户做任务观察，记录完成情况和原话。\n4. 根据证据决定下一版的一项重点改动。\n\n一次推进一个可观察步骤。先请学员预测结果，再运行或推演，再比较预期与实际。遇到错误，收集完整错误、输入和复现过程；定位后继续到本步验收。先给提示，需要时再给完整实现。学习者要求直接完成时执行已明确的任务，并解释关键选择。\n\n## 验收依据\n\n- MVP 功能能直接对应关键假设。\n- 评价包含任务完成与复用行为，而不只有点赞或页面访问。\n- 下一步改动解释得清为什么优先。\n\n逐项给出：要求、实际观察、通过或待修正、下一步。运行结果只能来自实际执行；若当前只有设计稿，则按设计验收，说明哪些运行检查留给实践环境。外部写入按用户授权执行。\n\n## 诊断提问与参考判断\n\n提问：用户说“如果免费我愿意试试”，说明付费需求成立了吗？\n\n参考判断：只说明试用意向。需要继续观察实际任务收益、持续使用，以及在明确价格和交付条件下的选择。\n\n先等待学习者回答再给参考判断。若回答混淆概念，使用本课案例追问，不直接重复术语。\n\n## 常见误区与纠正\n\n点赞或免费试用意向不能证明持续需求或付费；复用指标与使用频率匹配。\n\n## 结束交付\n\n给出本课成果位置或可复制内容、验收结果、一个需要复习的点。建议完成本课练习后在站点手动标记已学；你无法替学习者修改站点本地进度。\n" }, { "schema_version": "1.0", "id": "l5-06", "title": "AI 服务产品化", "stage": "L5", "language": "zh-CN", "canonical_url": "https://learn.iszhou.com/#lesson/l5-06", "api_url": "https://learn.iszhou.com/api/v1/lessons/l5-06.json", "metadata": { "id": "l5-06", "stage": "L5", "num": 6, "domain": "AI 产品化", "title": "AI 服务产品化", "desc": "将内部可用的 AI 能力变成可供外部接入、计量和维护的服务。", "ideas": [ "能力包装：API、Skill、SaaS 与服务契约", "计量计费：调用量、模型成本、资源消耗", "运营机制：稳定性、版本、支持与商业模式" ], "practice": "给一个可复用 AI 技能设计 API 产品说明、价格单位和服务可用性指标。", "takeaway": "产品化的分界是面向外部用户提供稳定、可管理的价值。", "minutes": 45, "full": true, "status": "complete", "illustration": { "src": "assets/course-art/l5-06-v2.webp", "alt": "把能力做成可运营的服务", "caption": "异步处理从 processing 分别进入成功或失败；同一幂等键避免重复交付。教学成本 10 × 0.20 ÷ 8 = 0.25/份，版本变更另需兼容期与迁移说明。", "reused": false } }, "content_markdown": "# AI 服务产品化\n\n> 将内部可用的 AI 能力变成可供外部接入、计量和维护的服务。\n\n## 学习起点与本课交付\n\n**开始前：** 已有一个内部可运行能力，先定义对外的交付单位和服务边界。\n\n**完成后留下：** 含输入输出、异步状态、错误、幂等、版本、成本和支持的一页服务契约。\n\n## 学习目标\n\n- 能力包装：API、Skill、SaaS 与服务契约\n- 计量计费：调用量、模型成本、资源消耗\n- 运营机制：稳定性、版本、支持与商业模式\n\n## 图解\n\n![把能力做成可运营的服务](assets/course-art/l5-06-v2.webp)\n\n
异步处理从 processing 分别进入成功或失败；同一幂等键避免重复交付。教学成本 10 × 0.20 ÷ 8 = 0.25/份，版本变更另需兼容期与迁移说明。 点击图片可查看大图。
\n\n## 从内部能力到外部服务\n\n内部脚本由熟悉的人使用，可以靠沟通解释异常。对外服务需要稳定契约、清楚的版本、计量、支持和恢复机制。用户应知道输入什么、多久返回、失败怎么办、结果在哪里。\n\n## 为一个服务写清交付单位\n\n以“会议记录转行动清单”为例，可以按成功处理的会议计量，也可以按音频时长计量。不同单位影响成本预测与用户理解。失败重试怎样计费、超长录音如何处理、是否保留原文件，都应提前约定。\n\n| 契约部分 | 示例 |\n|---|---|\n| 输入 | 文本或音频、语言、会议 ID |\n| 输出 | 结构化行动项、来源位置、待确认字段 |\n| 异步状态 | accepted、processing、succeeded、failed |\n| 重试 | 使用相同幂等键查询或重试 |\n| 版本 | /v1，字段变化有迁移说明 |\n| 支持 | 错误码、请求 ID、反馈入口 |\n\n## 单位经济要包含成功率\n\n假设每次尝试平均成本为 0.20 个计价单位，十次尝试产生八份成功交付，则平均每份成功交付成本是 `2.00 / 8 = 0.25`，还未计入人工支持和固定成本。以上为教学数字。只用一次理想调用的模型费用定价，容易低估重试、排错和维护。\n\n## 稳定性与版本管理\n\n服务目标要具体，例如“目标在约定工作时间内处理完一定长度的录音”，并规定统计口径。返回 200 但行动项为空，不应自动算有效成功。新版本上线前用固定样例比较，必要时提供旧版兼容期和回滚路径。\n\nAPI、Skill 和网页可以同时交付：API 提供能力契约，Skill 提供正确调用方法，网页帮助人完成操作。它们共享服务端规则，不能各自定义不同的成功标准。\n\n## 动手练习\n\n1. 为一个已完成的小工具写一页服务说明，包括输入、输出、错误和版本。\n2. 选一个计量单位，列出模型、运行、重试和支持成本。\n3. 设计成功、失败、超时和重复提交四种服务行为。\n4. 请一个不熟悉项目的人只按说明完成调用，并记录卡点。\n\n## 验收标准\n\n- 外部使用者能独立调用和定位错误。\n- 价格单位与实际成本有对应关系，失败口径明确。\n- 版本更新和恢复方式可执行，服务承诺有测量依据。\n\n## 自测与参考答案\n\n**问题：** 接口每次都返回成功状态码，是否说明服务质量高？\n\n
展开参考答案

要检查业务结果是否有效、是否及时，以及是否满足任务要求。传输成功和业务成功需要分别计量。

\n\n## 本课带走\n\n将能力变成用户可独立使用、可理解成本、可获得支持的服务。\n", "agent_teaching_guide_markdown": "# AI 教学包 · AI 服务产品化\n\n## 本课交付与易错点\n\n先核实起点：已有一个内部可运行能力，先定义对外的交付单位和服务边界。\n\n逐项验收：含输入输出、异步状态、错误、幂等、版本、成本和支持的一页服务契约。\n\n重点纠偏：200 不等于有效交付；10 次成本 2.00、8 份交付的单位成本是 0.25，仍需计支持与固定成本。\n\n图解用于解释关系，正文与实际工具结果用于验收；不把图中的虚构数据、示意命令或条件推演称作已经运行的结果。\n\n## 角色与任务\n\n你是本课的实践教练。目标是让学习者完成并解释“给一个可复用 AI 技能设计 API 产品说明、价格单位和服务可用性指标。”。以随附课程正文为知识依据，采用具体、简洁的中文。当前阶段：L5 · AI 产品化。\n\n## 开始前确认\n\n已理解单体 Agent 系统；准备一个平台、企业或产品场景。\n\n先问学习者已经做到哪一步、已有何种文件或结果。已有可用成果就从断点继续。需要编程时先确认工作目录与运行方式；只读分析课不修改被分析项目。\n\n## 本课讲解顺序\n\n1. 从内部能力到外部服务\n2. 为一个服务写清交付单位\n3. 单位经济要包含成功率\n4. 稳定性与版本管理\n\n先讲一个本课场景，再解释图中各部分的职责和连接关系。图的文字说明：异步处理从 processing 分别进入成功或失败；同一幂等键避免重复交付。教学成本 10 × 0.20 ÷ 8 = 0.25/份，版本变更另需兼容期与迁移说明。\n\n## 陪练步骤\n\n1. 为一个已完成的小工具写一页服务说明，包括输入、输出、错误和版本。\n2. 选一个计量单位，列出模型、运行、重试和支持成本。\n3. 设计成功、失败、超时和重复提交四种服务行为。\n4. 请一个不熟悉项目的人只按说明完成调用，并记录卡点。\n\n一次推进一个可观察步骤。先请学员预测结果，再运行或推演，再比较预期与实际。遇到错误，收集完整错误、输入和复现过程；定位后继续到本步验收。先给提示，需要时再给完整实现。学习者要求直接完成时执行已明确的任务，并解释关键选择。\n\n## 验收依据\n\n- 外部使用者能独立调用和定位错误。\n- 价格单位与实际成本有对应关系，失败口径明确。\n- 版本更新和恢复方式可执行，服务承诺有测量依据。\n\n逐项给出：要求、实际观察、通过或待修正、下一步。运行结果只能来自实际执行；若当前只有设计稿，则按设计验收，说明哪些运行检查留给实践环境。外部写入按用户授权执行。\n\n## 诊断提问与参考判断\n\n提问：接口每次都返回成功状态码，是否说明服务质量高？\n\n参考判断：要检查业务结果是否有效、是否及时，以及是否满足任务要求。传输成功和业务成功需要分别计量。\n\n先等待学习者回答再给参考判断。若回答混淆概念，使用本课案例追问，不直接重复术语。\n\n## 常见误区与纠正\n\n200 不等于有效交付；10 次成本 2.00、8 份交付的单位成本是 0.25，仍需计支持与固定成本。\n\n## 结束交付\n\n给出本课成果位置或可复制内容、验收结果、一个需要复习的点。建议完成本课练习后在站点手动标记已学；你无法替学习者修改站点本地进度。\n" } ], "guide_markdown": "# 基础使用说明\n\n> 从一个实际问题开始，读懂一课、完成一个练习、留下一个能复用的成果。\n\n## 第一次使用：三步开始\n\n1. **选起点。** 第一次接触 AI，从 L1 开始；已能用 AI 做小工具，从 L4.1 开始；已有系统要持续运行，从 L4.2 开始。想先看全貌，打开课程地图。\n2. **读一课并动手。** 每课包含概念说明、图解、案例、练习步骤、验收标准与自测答案。用自己的话解释图中关系，再做练习。\n3. **留下成果。** 保存代码、笔记或设计图，对照验收标准检查，再点击“标记为已学”。该标记是学习记录，不是自动考试结果。\n\n## 调整课程目录宽度\n\n桌面上拖动左侧目录的右边缘，可调宽或收窄；宽度会在当前浏览器保存。手机先打开目录，再拖动抽屉右边缘，手机与桌面的宽度分别记忆。使用键盘时，Tab 选中分隔线后按左右方向键微调，Home / End 调到允许范围两端；双击分隔线恢复默认。标题会自动换行，目录不会无限挤占正文。\n\n## 三种阅读模式\n\n| 模式 | 给谁看 | 怎样使用 |\n|---|---|---|\n| 人类课件 | 学习者 | 阅读讲解、图示和练习 |\n| AI 教学包 | 你自带的 AI 助手 | 获取带教目标、提问、陪练与验收方式 |\n| 双轨对照 | 学习者与授课者 | 对照课件内容和 AI 的教学职责 |\n\n点击“复制给 AI 学习”，会把**课程正文和教学说明一起复制**。粘贴到你正在使用的 AI 助手，补一句“我目前到哪一步、已有的文件或结果是什么”，即可开始本课陪练。需要实际写文件、运行代码的练习，请在具备相应工具的工作环境中进行。\n\n本网站提供教材和学习记录，不直接调用模型。外部 AI 能看到什么文件、能执行什么操作，由你所用的产品与授权决定。\n\n## 课程路线与阶段成果\n\n| 阶段 | 学习重点 | 建议留下的成果 |\n|---|---|---|\n| L1 | 会表达任务、选择能力、检查结果 | 一份带来源的任务交付物 |\n| L2 | 配置助手、知识库与工作流 | 可复用项目说明和知识索引 |\n| L3 / AI Tools Build | 与 AI 开发、调试和管理版本 | 一个可运行的小工具 |\n| L4.1 | 系统、双入口、权限与部署 | 可由人和 Agent 共用的服务 |\n| L4.2 | 任务定义、状态、编排和评估 | 可暂停恢复的持续任务 |\n| L4.3 | 信号、假设、实验与迭代 | 两轮带证据的实验记录 |\n| L5 | 平台、群体、企业与产品化 | 有资源、授权和运营机制的方案 |\n\n全站共 38 节，覆盖五个 Level；L4 分为三个阶段。页面分钟数是阅读与练习的建议估计，项目实战可以分多次完成。\n\n## 准备哪些工具\n\nL1–L2：浏览器、一个可用 AI 助手，以及能保存 Markdown 的笔记工具。L3：增加独立项目目录、代码编辑或 Coding Agent 环境、Git；Python 示例需要 Python 3。L4.1：按课程需要准备接口测试工具和可部署环境。Figma 只用于对应原型课，不是全站前提。\n\n先用课程给出的虚构记录和文件副本练习。每个接口路径、工具命令和实例配置若标为设计示例，需要在自己的练习项目中实现后再执行。模型费用与性能示例使用教学假设，选型时再核对服务商的当前资料。\n\n## 看图、搜索与导航\n\n点击课件图片可打开大图；图下说明帮助你把旧课件图与当前课程概念对应。旧图中的阶段命名保留原貌，课程阶段以当前目录为准。系统图用于解释职责与关系，并不要求每个方框对应一台服务器。\n\n左侧目录按阶段和主题组织；右侧大纲跳转到本课小节。顶部搜索可查标题、概念与课程正文；桌面可按 Ctrl / Cmd + K 打开。手机通过左上角目录按钮选课，双轨内容会根据屏幕宽度排列。\n\n## 学习进度与文件下载\n\n进度保存于当前浏览器的本地存储。关闭页面后通常仍在；换设备、换浏览器、使用隐私窗口或清理站点数据，不会自动同步进度。浏览器禁止存储时，本次页面仍可使用，刷新后记录可能不保留。\n\n课件可下载为 `lesson.md`，AI 教学说明可下载为 `agent.md`。图片通过站点地址引用，离线阅读若需要图片，应同时保存对应图。修改教材源文件需要重新构建并发布，下载副本不会自动更新线上内容。\n\n## 如何判断真正学会\n\n先完成练习，再回答自测，最后展开参考答案核对。能复述术语是第一步，能在新场景解释输入、过程和输出，并交付符合标准的结果，才说明掌握了本课。遇到卡点，给 AI 具体错误、复现步骤和当前文件，不必重新讲整个项目。\n\n推荐提问：“我已完成前两步，第三步返回这个错误。请先解释错误发生在哪一层，再带我修到验收通过。”\n\n## 常见问题\n\n**复制按钮无反应：** 使用 Markdown 下载，把正文和教学包一起提供给 AI。浏览器剪贴板权限可能影响复制。\n\n**图片显示很小：** 点击打开大图。先看图中主关系，再读局部文字，不必一次读完全部细节。\n\n**标记已学后换设备没了：** 当前是浏览器本地进度，没有跨设备同步。\n\n**代码在我的电脑运行失败：** 核对当前目录、运行时版本和完整错误。给 AI 看实际执行命令及输出，按课内验收逐项排查。\n\n**看完了仍不会独立做：** 回到本课实操，只做一条最小完整路径。让 AI 先给一个提示，自己完成下一步，再核对结果。\n\n## 给授课者与维护者\n\n授课时先展示场景和图，再用小样例演示，最后让学员独立完成一个变体。每课 AI 教学包包含常见误区和验收要求，可直接作为助教说明。课程源采用一课一份正文与教学包，便于逐节维护；技术参考链接用于进一步核查，案例和练习为本课程设计。\n\nHTTP/API 课现有八个课内小节，附 Python 下载练习包与函数计算选修。先完成本地计算 API，再按环境选择云部署。\n" }