开源 AI 工具文档示例：示例要能复制运行
一、文档示例决定第一印象
开源 AI 工具的 README 往往决定用户是否继续尝试。很多项目介绍很酷，但示例代码复制下来跑不通：缺少环境变量、版本不匹配、模型 Key 没说明、输出格式和文档不一致。用户不会耐心猜。
示例不是装饰，它是第一个集成测试。能复制运行的示例，比一长段功能介绍更能建立信任。
二、示例要覆盖最短路径
flowchart TD A[安装] --> B[配置密钥] B --> C[运行最小示例] C --> D[看到预期输出] D --> E[扩展到真实项目]最小示例应该只做一件事，并展示预期输出。不要在第一个示例里同时讲插件、缓存、流式、工具调用和部署。用户先跑通，再逐步深入。
环境变量、Node 或 Python 版本、依赖安装命令，都要写在示例前面。缺一步，体验就断掉。
三、示例也要自动测试
import { createClient } from "tiny-ai-kit" const client = createClient({ apiKey: process.env.AI_API_KEY! }) const result = await client.chat("Summarize this project in one sentence.") console.log(result.text)README 里的代码最好能被测试脚本提取运行。否则代码在文档里慢慢过期，直到用户发现。
docs_example_test: run_readme_snippets: true require_env_placeholder: true check_expected_output_shape: true run_on_release: true测试不必依赖真实模型，可以用 mock provider 验证接口和输出结构。真实模型示例可以单独放在集成测试里。
四、复杂示例要分层
高级示例可以展示流式输出、工具调用、Agent、部署，但要放在独立章节。每个示例都应说明适用场景和不适用场景。
还要避免示例代码过度封装。用户看示例是为了理解工具怎么用，不是为了阅读项目内部框架。示例越直接，越容易被复制到真实项目里。
示例还要标明成本和外部依赖。AI 工具示例通常需要模型调用，如果默认示例会产生费用或依赖网络，就要提前说明。对于开源项目，最好提供本地 mock 示例和真实模型示例两套路径。
example_levels: quickstart_mock: requires_api_key: false expected_runtime_seconds: 5 real_model_demo: requires_api_key: true expected_cost: "low"版本兼容也要写清楚。示例对应哪个包版本、哪个运行时版本、是否支持 ESM/CJS，都会影响用户能否跑通。很多 Issue 其实不是功能问题，而是示例没有说明环境。
文档站可以给每个示例加“最后验证版本”和“复制命令”。当示例被自动测试覆盖时，把测试状态展示出来，用户会更放心。
示例还要展示失败路径。比如缺少 API Key 时会看到什么错误，网络不可用时如何切换 mock provider。很多用户第一次使用工具时，遇到的不是成功路径，而是配置错误。文档提前写出常见失败，可以减少大量重复 Issue。
if (!process.env.AI_API_KEY) { throw new Error("Missing AI_API_KEY. Use mock provider for local quickstart.") }这种错误提示看似简单，却能让用户知道下一步该做什么。
五、总结
开源 AI 工具文档示例要覆盖最短路径、明确环境、展示预期输出，并纳入自动测试。
文档不是写给项目作者看的。示例能跑通，用户才会相信工具能进入自己的工程。
)
