--- name: ascend310b-writing-case description: Ascend310 实践案例教材写作。用于案例1至案例9的 src/experiment 正文、样例入口和教学验收;sidebar 由 ascend310b-writing-vuepress 维护;要求面向初学者先讲基础知识与必要理论,再以最小示范、分步实验、证据解释和迁移任务递进,使用灵活语义标题,不把部署手册、发布报告或板端日志直接当成教材;案例发布仍必须从 GitHub 固定 commit 获取程序、从 Hugging Face 固定 revision 下载模型。 compatibility: 固定来源与板端复现依赖 ascend310b-case-testing 和 Ascend 板端工具;依赖缺失时经验性结果保持 untested。 --- # 实践案例教材写作 这个 skill 写的是**学生读完以后能够理解、运行、解释并迁移的教材章节**,不是实验报告、发布验收报告、运维手册或 README 的拼接。案例正文不得呈现为“先列实验环境与版本,再罗列步骤和结果表”的报告式结构。工程证据必须保留,但工程证据要服务于教学主线,而不能占据教学主线。 适用对象:没有完整 Ascend 310B 工程经验、能够按前置章节完成基本 Linux/Python 操作的初学者。案例正文必须使用简体中文回答四个连续问题: ```text 为什么要做这个案例? 先要理解哪些概念? 怎样先跑通一个最小结果? 怎样解释结果、定位失败并迁移到新任务? ``` 命令、API、路径、模型名、版本号和日志原文保留英文;标题、解释、步骤、判断、练习和结论必须是中文。英文术语首次出现时给中文解释。成段英文或英文教学标题不能通过`prose-language`。 ## 范围与冻结规则 只处理 `src/experiment/case1.md` 到 `case9.md` 及案例内容。`src/.vuepress/sidebar.ts` 和生成区块由 `ascend310b-writing-vuepress` 独占;案例 skill 只提供页面标题、目标路径和导航意图。案例冻结标题来自 `AGENTS.md`,必须保持: ```text 案例 N:<纯中文任务名> ``` 不得给标题增加硬件型号前缀、英文副标题或自造编号。`case4.md` 对应“案例 4:掌纹识别”,必须自包含,不得链接或依赖任何其他仓库文档;只可链接自己的源码、图片和外部来源。 标题编号由渲染器生成:H1 保留冻结标题;H2–H6 只写语义标题,不手写 `1.`、`1.1` 或 `4.1`。手写章节号违反 `heading-manual-number`,并可能在插入或移动小节后造成重复编号。 示例: ```markdown # 案例 4:掌纹识别 ## 这项任务解决什么问题 {#src-experiment-case4-problem} ### 最小闭环 {#src-experiment-case4-minimal-loop} ``` ## 教学设计依据 本 skill 采用经过长期课程设计实践使用的几条教学原则,并把它们转换成仓库可检查的写作规则: - **Backward design**:先写学生完成后能做出的可观察产出,再决定概念、练习和证据,不从作者拥有的日志表开始写。 - **Scaffolding / gradual release**:从教师示范或最小可运行例开始,逐步转为提示下练习,再转为学生独立任务。 - **Worked example 与 think-aloud**:沿适合案例的真实输入、数据帧、控制过程或推理调用解释“为什么这样做、应该观察到什么”;不要求每个案例都以服务请求为叙事主线。 - **Formative assessment**:在章节中设置预测题、检查点和短练习,让学生在最终验收前发现误解。 - **Active learning**:学生需要执行命令、观察输出、解释差异,而不是只阅读一串已完成结果。 - **证据分层**:教学烟测、数值一致性、任务质量、性能和 UI 证据分别标注,工程报告不替代教材解释。 公开参考: - [Gareth Manning 的 Education Agent Skills](https://github.com/GarethManning/education-agent-skills):将学习目标、课程设计、形成性评价和证据限制拆成可复用 skill,并明确区分研究依据与实践框架。 - [VoltAgent Awesome Agent Skills](https://github.com/VoltAgent/awesome-agent-skills):作为 skill 结构、可组合工作流和质量筛选的参考目录;它不是本教材的教学证据来源。 - [Cornell CTI:Engaging Students](https://teaching.cornell.edu/teaching-resources/engaging-students):强调让学生参与思考、问题和共同练习,而不是只接收讲义。 - [Cornell CTI:Assessing Student Learning](https://teaching.cornell.edu/teaching-resources/assessing-student-learning):区分形成性评价和总结性评价,并要求评价能反馈学习目标达成情况。 这些来源提供方法启发,不替代本仓库的冻结标题、310B 板端事实和证据规则。 ## 案例教学合同 动笔前先读取 `docs/curriculum_plan.md`(由 `ascend310b-curriculum-planning` 维护),并把对应案例行作为唯一教学目标来源。需要内部展开时使用 [references/case-teaching-plan.md](references/case-teaching-plan.md),但不得创建与主计划冲突的第二套学习目标或评估矩阵。至少明确: | 字段 | 要回答的问题 | | --- | --- | | 学习者 | 学生已经会什么?哪些术语不能直接假定? | | 中心问题 | 学生为什么需要这个系统/模型/设备链路? | | 学习目标 | 学生完成后能解释、实现、诊断、验证或设计什么? | | 概念地图 | 哪些概念必须先讲,哪些可以留到进阶? | | 最小成功 | 学生最先能看到的可验证结果是什么? | | 分步任务 | 每一步的动作、预期信号、检查点和失败分支是什么? | | 迁移任务 | 学生如何把本案例方法改到另一个输入、模型、端口或设备? | | 证据边界 | 哪些是 observed-pass,哪些仍是 untested/blocked? | 学习目标使用可观察动词:解释、画出、运行、读取、比较、诊断、验证、设计。避免只写“了解”“熟悉”“掌握”。每个目标至少绑定一个学生产出:命令输出、结构图、JSON 响应、错误分类、输入合同、判断理由或小型改动。 ## 正文与工程文档分层 案例正文、样例 README、`samples/caseN/docs/` 和发布报告承担不同职责: | 内容 | 案例正文 | 工程 docs / 验收记录 | | --- | --- | --- | | 为什么做、概念和原理 | 必须讲清 | 可简写 | | 最小运行路径 | 必须给出 | README 仍须保留可执行的源码/模型获取与运行指令,不能只链接正文 | | 一次代表性结果的解释 | 必须讲清 | 记录证据摘要和路径;原始日志仅在用户授权保留时附入仓库 | | 全量模型矩阵、版本矩阵、哈希表 | 只保留学习所需摘要 | 详细记录放 docs | | 每轮性能、完整异常历史、部署变更 | 不堆入主叙事 | 放验证报告/台账 | | 发布复现命令与固定来源 | 给出可复制入口 | 保存完整锁、清单和报告 | 一般案例正文可以引用自己的源码、图片和工程 docs,但不能把工程 docs 当成学生必须先读的隐式前置。`case4.md` 是更严格的例外:只可链接自己的源码、图片和外部来源,不得链接或依赖任何其他仓库文档,包括 README、工程 docs、理论章节、附录和其他案例;必要知识与操作必须在本篇讲清。 一个简单判断:如果删除某张日志表后,学生仍然无法理解概念或完成任务,说明正文缺教学解释;如果删除后只影响历史审计细节,应移到工程 docs。 ## 教学主线与语义结构 以下是教学功能示意,不是必须照抄的 H2 模板。按案例内容使用具体的语义标题,可合并或拆分小节;不能手写章节编号。先铺垫基础知识和必要理论,再进入完整实验;最小示范可穿插在概念讲解中,但不能让学生在尚未理解必要概念时照抄完整流程。 ```text 案例 N:任务名 这项任务解决什么问题 你将学会什么 开始前需要什么 先理解:核心概念 先跑通:最小闭环 沿数据流或控制流读懂实现 分步实验:从观察到解释 两条路线或进阶能力 结果、失败与边界 小结与迁移练习 发布复现与证据 ``` ### 这项任务解决什么问题 从学生能理解的真实情境开始:用户要完成什么任务,边缘设备受到什么约束,最终输入和输出是什么。先给一张端到端图或一句任务主线,再引入硬件、框架和模型名称;采集、控制等案例不必套用服务请求叙事。 禁止开篇连续堆叠:双板发行矩阵、全部模型 profile、端口表、CANN 版本、完整验收数字和未验收功能清单。它们可以在后文出现,但不能替代问题情境。 ### 你将学会什么 写 3–5 个可观察目标,并为每个目标给出产出或检查点。例如: ```text 完成后你能(按案例任务选择适用目标): 1. 画出数据输入、处理模块、设备/模型和输出之间的职责边界; 2. 解释一帧数据、一次采集、一次控制动作或一条请求如何经过系统; 3. 根据状态、日志和输出判断失败发生在哪一层; 4. 修改一个受控参数并用证据说明变化; 5. 说明本案例结论不能推广到哪些硬件/模型组合。 ``` ### 开始前需要什么 只列学生真正需要的前置知识、硬件、环境和来源。将“必须先完成”和“本节会解释”分开: - 必须先完成:Linux shell、Python 基础、必要理论概念或输入合同;`case4.md` 必须在本篇提供必要说明,不得要求先读其他仓库文档; - 本节会解释:本案例新增的架构、模型输入、鉴权边界和失败层; - 不要把整份部署报告、历史日志或作者内部路径列成学生前置。 ### 先理解:核心概念 每个核心概念使用以下微结构: ```text 学生问题 → 一段浅解释 → 一个最小例子/图 → 一条边界 → 一个检查题 ``` 术语第一次出现时写中文解释,再给英文/API 名称。不要让学生在第一次看到 `Provider`、KV cache、SSE、ACL、OM、SoC 或 Bearer 时自行猜含义。复杂概念拆成不超过一个主要新关系的小段,并在段末让学生预测下一步输出。 ### 先跑通:最小闭环 概念之后给一条最短、可复现、能看到结果的路径: 1. 获取固定 commit 的源码; 2. 获取固定 revision 的模型或工件; 3. 激活 `ascend` 与 CANN; 4. 启动最小服务或执行最小推理、采集或控制任务; 5. 提供一次代表输入或触发一个可观察动作; 6. 指出预期输出的关键字段和成功信号。 每个命令块前写执行目录和目的,命令块后写“你应该看到什么”。不要把一百轮稳定性、完整性能协议和所有硬件差异放进第一次成功路径。 ### 沿数据流或控制流读懂实现 选择适合案例的真实请求、视频帧、采集周期、控制过程或模型调用,从输入到输出逐层追踪,不强制使用请求模型。至少说明: - 哪个文件接收输入; - 哪个模块做验证/预处理; - 哪一层调用 ACL、MindSpore、OM 或服务接口; - 返回值如何变成学生能观察的输出; - 哪个错误信号能判断层级。 代码路径要指向学生将要阅读或修改的入口,不要只列模块清单。一次完整追踪比十张 API 表更适合入门。 ### 分步实验:从观察到解释 实验步骤必须是“问题—动作—预期信号—解释—若不符怎么办”的循环: ````markdown ### 检查模型是否已准备 先预测:如果权重缺失,服务启动会在哪一层失败? ```bash <命令> ``` 预期:<字段/状态/一行关键输出>。 解释:<这个输出证明了什么,不证明什么>。 若不符合:先检查 <最早失败层>,不要直接改用 CPU 或另一个模型。 ```` 逐步从教师示范转为学生操作:先给可检查的完整示范,再让学生完成带提示的修改或操作,继而独立判断并选择验证方法,最后完成小型迁移任务。命令型实验可从填写参数开始;采集、控制和硬件操作按其自然交互设计。 ### 两条路线或进阶能力 只有当学生已经跑通共同最小闭环后,才比较 8T/20T、MindSpore/ACL、OM/非 OM 或不同模型路径。比较表只保留“为什么不同、哪些不能互换、学生该如何选择”,完整版本矩阵和哈希放工程 docs。 未验收的语音、摄像头、设备协议或未来设计只用范围框说明:它解决什么问题、当前状态是什么、为什么不能从文字链路推导通过;不要让未验收扩展占据主案例主线。 ### 结果、失败与边界 正文选少量代表结果,并逐项解释: - `observed-pass`:在什么板、什么模型 revision、什么命令上通过; - `observed-fail`:失败在哪一层,保留什么最小证据; - `untested`:为什么尚未验证; - `blocked`:缺哪个前置条件。 运行通过、数值烟测、任务质量、性能和 UI 分开写。不要用 HTTP 200、模型加载成功或一次输出正常替代任务质量结论。逐轮性能、历史异常和全量表格由 `samples/caseN/docs/` 承载,原始日志仅在用户授权时入库;一般案例可链接工程记录,`case4.md` 不得链接这些文档,正文必须直接解释教学所需的代表样本与证据边界。 ### 小结与迁移练习 小结必须回扣学习目标,不是重复架构名词。至少包含: - 学生现在能解释什么; - 哪个检查点证明了什么; - 哪些结论不能推广; - 一个独立完成的迁移题。 迁移题应匹配案例领域,可以要求学生设计新输入合同、比较 SoC 上的路径、改变一个采集/控制参数、从日志判断最早失败层;若案例包含服务,也可分析 `401`、服务健康但推理失败或输出预算。题目必须有可检查的产出,不能只写“思考一下”。 ### 发布复现与证据 发布复现是教材的一部分,但放在学生已经理解并跑通最小闭环之后: - 程序从 GitHub 固定 commit 在板端检出; - 模型从 Hugging Face 固定 revision 下载,默认 `HF_ENDPOINT=https://hf-mirror.com`; - 记录文件大小、SHA-256、许可证和输入输出合同; - 明确这条路径是在线下载还是 `offline-bundle`; - 完整锁文件、模型矩阵、OM/报告哈希由工程 docs 承载;板端长日志默认留在板端,只有用户明确授权才保留到样例证据目录或指定外部归档。`case4.md` 不链接工程文档。 不能在正文用作者电脑上的本地模型、未提交源码或本地 OM 代替公开复现来源。作者按 `ascend310b-case-testing` 的维护流程准备来源信息;该 skill 不是学生前置,也不得作为 `case4.md` 的链接或依赖。 ## Case9 等复杂案例的改写规则 对于同时包含两块板、两种框架、多个模型和未验收扩展的案例: 1. 先讲一个共同的用户任务和端到端数据流; 2. 先完成一条默认板路的最小闭环; 3. 再解释第二条路线为什么不同、哪些工件不能共用; 4. 把语音等未验收扩展压缩为范围/限制框; 5. 正文保留一组教学代表结果,完整发布记录放 `samples/caseN/docs/`; 6. 最后用练习要求学生判断失败层、选择证据或迁移配置。 不要让开篇的“发布矩阵”替代入门,不要让连续的验收表替代解释,不要让未来设计占据已验收主链。 ## 写作流程 1. 运行 `ascend310b_writing_audit scope=experiment`,确认冻结名、链接、图片和 Markdown 卫生。 2. 读对应 `samples/caseN/README.md`、`samples/case-index.json`、相关 `samples/caseN/docs/README.md`,把工程资料与学生正文分开。 3. 读 `ascend310b-curriculum-planning`,建立“目标—先修—概念—动作—检查点—证据”矩阵。 4. 先填写 [case-teaching-plan.md](references/case-teaching-plan.md),再写正文;不要从日志、版本矩阵或最终报告反向拼正文。 5. 按教学功能组织语义小节:问题、目标、基础与必要理论、最小示范、实现追踪、分步实验、迁移练习、限制和发布复现;完整实验前必须完成必要概念铺垫,不强制固定标题或请求叙事。 6. 复跑 `ascend310b_writing_audit scope=experiment`,并用 `ascend310b_writing_style scope=experiment` 检查报告腔、元话语和空转套话。 7. 案例正文修改后运行 `pnpm run docs:dev`,打开 `experiment/caseN.html`,再运行 `ascend310b_writing_page_layout` 或 `node scripts/check_page_layout.mjs --url ` 做本地页面排版检查,覆盖桌面和移动端。 8. `human-review: pending` 只保留在外部任务或审查元数据中,不写入发布正文;用户人工检查教学顺序、命令入口、预期输出和练习后,才能将该状态改为通过。 9. 推送前运行 `ascend310b_writing_push_check`。 ## 证据与工程边界 - 摄像头:区分 MIPI/CSI、USB、实际分辨率和真实读帧; - 服务:HTTP 健康通过不等于 NPU 推理通过; - 模型:模型、OM、数据和运行报告不能用截图替代; - 性能:标明 8T/20T、warmup、iterations、repeats 和报告路径; - 无法在板端验证的内容写 `untested` 或 `blocked`; - 验收摘要和报告放 `samples/caseN/docs/`;原始日志仅在用户明确授权时入库,正文只保留教学所需代表证据,且 `case4.md` 不链接其他仓库文档。 ## 停止条件 以下任一情况都不能把案例称为教材完成稿: - 开篇直接进入版本矩阵、端口表、日志或验收表,没有问题情境和学习目标; - 核心术语在没有解释、例子或输入输出合同前直接出现; - `prose-language`报告正文以英文为主; - 没有最小成功路径,只有完整部署/发布路径; - 必要基础知识和理论没有在完整实验前讲清; - 步骤没有预期输出、解释或失败分支; - 没有形成性检查点和独立迁移练习; - 工程报告、性能表或未验收设计占据正文主线; - 样例入口和正文命令不一致; - 板端证据缺失却要写“通过”; - `case4.md` 依赖其他仓库文档; - 链接/图片目标不存在; - 案例正文出现 `.dot` 路径、字体名、pt/dpi 或作者自检备注; - 没有本地网页人工校验,却被描述为最终完成。