从“能运行”到“能交给别人运行”
整理 GitHub 项目时，我意识到：一段程序在自己的电脑上跑过，和别人能够拿到它并运行，是两件需要分别检查的事。
自己的环境里可能已经有依赖、配置和数据。别人只有仓库，需要从说明里建立这些条件。
README 首先要告诉别人拿到了什么
我希望读者先知道项目解决什么问题，当前包含什么，以及哪些部分还没有公开。
以 Agent 项目为例，公开仓库目前主要是说明，源码待补。这样的仓库可以介绍设计，但不能给出一个并不存在的启动命令。
NPC 则还有另一个区别：第一篇论文的本地实验已经完成一百回，公开仓库的示例却没有完整包含那批实验使用的实现与材料。
因此，公开代码不完整不能证明实验没做；实验做完了，也不代表别人能用公开仓库复现。介绍时需要把两边说清楚。
一条命令前面，需要哪些条件
运行环境、依赖版本、配置方式和外部服务权限，都会影响第一次启动。
我希望说明回答：使用什么运行时，怎样安装依赖，哪些环境变量必填，怎样授权数据源，以及成功启动后到哪里访问。
配置示例只提供占位值，真实密钥通过运行环境读取。把自己电脑上的文件路径写进命令，也需要说明它应当怎样替换。
博客接入 Notion 就是一个例子。设置令牌之外，还需要连接获得博客数据库访问权限。只有配置变量，没有页面授权，读取仍然会失败。
默认配置，不是实验结果
研究项目尤其容易把示例规模和完成的数据混在一起。
代码里写了多少场、多少轮，只能说明按该配置运行会尝试生成什么。实际完成多少，应该依据输出记录、失败情况和统计口径。
我的第一次 NPC 最终实验有一百份日志，每份十五次角色标记输出。文章中使用这批实际记录，而不是用公开示例的默认参数推算成果。
进一步复现，还需要提供对应提示词、模型标识、采样参数、执行条件和评价方法。具体模型更新后，也未必会逐字重现相同输出。
最小示例要能确认成功
一个示例不只是“运行这个脚本”，还应该说明预期发生什么：生成哪个文件，打开哪个页面，返回哪些字段。
这样别人能够区分程序正在工作、外部请求失败和配置缺失。
我会先选择规模小、结果明确的流程。例如，NPC 先验证一个角色的一次调用，内容工具先验证读到一个已授权页面，再扩大执行范围。
验证也有不同层次
语法检查、单元测试、模拟 API、真实服务调用和线上浏览器检查，各自能发现不同的问题。
例如，博客模拟数据的生产构建通过，只能说明这套代码处理模拟输入没有阻塞；真实 Notion 授权、图片和语言路由，还需要实际检查。
Night 的单元测试通过，也不能直接说明 Safari 的弹窗和权限都正确。把验证范围写清楚，比一句“测试通过”更有用。
把陌生人的第一次运行当作使用场景
以后整理项目，我想更认真地检查一次从零开始的过程：依赖是否能装，配置是否讲清楚，命令是否有效，输出是否容易判断。
遇到失败时，也希望能提供准确的错误说明与排查方向，让别人不必靠猜测理解我的环境。
仓库是项目的一部分。把说明、配置与可核查的运行材料整理好，才能让自己的开发和研究真正被别人理解。
项目主页：XinzheGao