get-up-to-speed

快速上手

在独立的 快速上手工作区 中提供一份 快速入门指南，并附上可运行示例。通过做好调研、选择实用路径并进行充分说明，让读者更快上手。涵盖目标的核心能力及其相互关系，并通过一个有代表性的场景深入讲解，必要时辅以简短示例。

一次性交付约定范围内的全部内容。文档章节用于组织阅读内容；它们不是等待许可后才能继续的独立教学环节。后续对话用于澄清或扩展指南。本工作流不包含学习者练习、评估和学习记录。

英语输出

编写或修改英语文本之前，请使用已安装的 simple-english 技能。按名称加载，或阅读其 SKILL.md 和适用的参考资料。 重用当前上下文中已加载的说明。 阅读本约定后，在发送任何英语进度更新、草稿或最终回复之前，先加载此依赖项。

当风格规则发生冲突时，应保留原意、不确定性、要求的强度、领域术语和任务要求的格式。使用要求的语言。 保留代码、标识符、命令、原文引述和历史证据。

如果无法获取所需说明，只需报告一次这一情况，然后继续独立工作。在依赖项可用或用户明确授权例外之前，受影响的英语输出应保持为草稿。不要自动安装依赖项，也不要声称未经检查的草稿符合此要求。

1. 明确学习背景

以学习者已有的语言基础为起点。从零开始教授编程语言、系统性的基础课程和长期学习计划，不属于 Library 快速上手的范围。准备材料或创建工作区之前，先说明这种不匹配，并让学习者选择其他方向或缩小请求范围。

根据请求和可用上下文，确定目标、已有经验和预期用途。如果目标是一套产品，请查阅其官方概览，了解可选路径。只询问会实质性影响指南的缺失信息；如果学习者已说明贡献目标，就足以确定需要准备贡献内容。

明确教学语言：如果学习者明确选择了本次快速上手使用的语言，就按其选择；否则请学习者选择。指南和对话说明均使用该语言，同时保留代码标识符、命令和 API 名称的惯常形式。不能仅凭对话使用的语言来认定学习者已作出选择。

明确指南将帮助读者完成什么，以及哪些高级或替代路径不在范围内。根据这一目标选择细节，而不是强行规定字数、课程数量或完整项目课程。

**完成条件：**目标、预期成果、相关先验知识、范围和教学语言都已明确，足以选择一个有代表性的场景。

2. 研究并演示使用路径

阅读目标用途对应的官方概览、入门资料和指南。根据请求或相关安装选择版本；对于全新设置，使用当前有文档记录的版本，除非贡献目标要求使用特定源代码修订版。记录演示中安装、文档和源代码之间的关系。

选择一个能体现目标特征性决策和行为的场景。说明其他核心功能及其与此路径的关系；如果该场景无法解释必要概念，则补充说明。交付前准备好约定范围内的全部内容。

即使文档看起来已经足够，也要执行源代码准备。找到匹配的源代码，了解相关软件包和公共入口点，并追踪解释关键行为、默认值、优先级和限制所需的实现及测试。只需追踪到足以支撑指南说明的程度。区分公共契约与所检查修订版中的行为，并区分已阅读的测试和已运行的测试。

对于常规入门，在解释中以使用工具和推理不同情况所需的深度介绍关键机制。对于贡献目标，还要准备一条连贯路径，从可观察行为贯通相关实现、最小改动和回归测试：

• 说明如何找到入口点、追踪重要调用或数据转换，以及定位负责该行为的分支。
• 使用合适的现有问题、历史修复，或明确标注的教学改动。说明相关测试的设置、触发方式和断言，解释为何应在该位置进行改动，以及改动前后的测试结果能证明什么。教学改动不能作为上游存在缺陷的证据。
• 在教学工作区内的隔离检出环境中，演练相关的贡献设置、改动和定向测试。保留基准修订版、可复现补丁或已修改的源文件，以及重现所需的命令。将贡献示例与指南的主要场景联系起来。

在请求的目标位置创建工作区；如果未指定，则在当前工作区下新建 get-up-to-speed-<target> 目录。保留已有内容。使用 README.md 作为完整指南，并使用 examples/ 存放代码和测试资源；清单文件和配置文件放在工具要求的位置。根据需要保留辅助源代码检出或证据，并在指南中说明。所有操作均须在此工作区内进行；修改现有项目、配置服务或发布贡献均需单独授权。

亲自运行示例。UI 示例要检查实际渲染的界面，程序化示例要检查命令输出或生成的产物。如果示例会改变状态，则保留可运行的改动前后状态；使用常规清单文件和锁文件记录依赖项，并根据准备阶段核实已安装的版本。若观察结果与计划中的说明不一致，先解决差异，再撰写相关内容。

如果无法获取匹配的源代码或无法执行操作，应指出具体限制，并区分文档支持的主张、从源代码推导的解释、观察到的结果和预期结果。未经执行的演练可以作为有限指南的依据，但不能证明贡献路径已验证。如果缺失的证据导致无法实现预期目标，应说明阻碍，让学习者选择有证据支持的较小目标或暂缓；不要悄悄用不完整的指南替代原定内容。

**完成标准：**约定范围内的每个部分都有依据充分的说明和可复现示例，并附有执行结果，或明确说明仍足以支持约定目标的限制。

3. 编写完整指南

面向不了解前序对话的读者撰写。开篇说明目标的用途、读者预期达成的结果、所需背景知识，并简要介绍核心概念与功能。解释它们之间的关系，以及代表性场景在其中的位置。让版本详情和设置说明易于查找，同时避免让执行历史主导引言。

围绕场景中的决策和行为组织正文。对于每个重要概念或步骤：

• 说明它要解决的问题，并联系读者已有的知识。
• 在文档中展示相关代码，链接可运行文件，并解释重要命令、配置选择，以及输入如何转化为结果。
• 解释结果为何如此。当条件变化体现出重要差异时，展示一个小型变体，并说明它的效果和局限。

对于贡献准备，沿用同样的讲解方式，涵盖第 2 步中准备的源码路径、最小改动和回归测试。在正文中提供理解这一流程所需的代码片段和推理；源码链接用于佐证和延伸阅读，而不是替代讲解。

选择适合当前目标的章节和图示，无需反复套用固定的教学模板。将所有必要内容保留在主文档中。结尾提供可执行的运行说明、适用时提供简明的命令或 API 参考、说明范围边界，并推荐相关的后续参考资料。描述所涵盖的功能，但不要声称读者已经掌握了这些内容。

**完成标准：**指南从背景介绍到完整实践路径，涵盖了约定的目标；读者无需等待后续内容，也不必在链接材料中搜索必要的讲解，就能理解推理过程并复现示例。

4. 检查并交付

对于涉及多步设置、跨工具操作、贡献演练或环境相关结果的指南，如果有条件且收益足以抵偿设置成本，应安排独立读者复现。分配任务前，请阅读 独立复现。小幅文字修正或仅讲解概念的内容，不一定需要安排协作者。作者本人仍须执行；独立复现用于检查交付材料是否提供了读者所需的背景信息。

从学习者所述的起点阅读指南，并在交付前修正以下不足：

• **理解：**核心概念应说明其相互关系和影响；仅列出命名功能、命令表和源码链接并不足以满足要求。
• **推理：**重要选择和结果应有因果解释；相关变体应展示如何将推理应用于确切示例之外的情况。
• **目标：**实践路径应达到约定的终点。贡献指南应包括源码推理、最小改动和回归测试，而不是将这些内容推迟到后续课程。
• **复现：**文档片段应与保留的文件一致；命令应注明前置条件和工作目录；报告的结果应与证据相符。修正后重新检查受影响的示例。
• **完整性：**主文档应包含整个范围所需的讲解，链接应有效，并明确说明证据的局限。

交付指南和示例链接，并简要说明覆盖范围和重要执行限制。保留工作区，并停止为此启动的临时进程；如果有意为学习者保留仍在运行的进程，应予以说明。如果学习者提前结束工作，应明确指出已完成的部分材料和未覆盖的范围。

**完成标准：**完整指南和示例均可访问；约定范围内的上述检查均已通过；临时进程的管理责任已明确。