一个开源项目的 README，能暴露多少产品成熟度

先说结论。

README 不能证明一个开源项目适合生产，却能快速暴露维护者是否想清楚用户、安装、失败、许可和升级。最有效的读法不是打一个总分，而是拿两个真实项目逐项找证据。

本文在 2026-07-15 对照 OfficeCLI 与 stitch-skills。前者是一套可直接操作 Word、Excel、PowerPoint 的 CLI；后者是依赖 Stitch MCP 的 Agent Skills 集合。它们都采用 Apache-2.0，但产品边界和成熟信号不同。

对照结论：完整不等于更适合

OfficeCLI README 已覆盖安装、命令、JSON 输出、可运行示例、格式能力、构建、故障排查入口和许可证。仓库在核验日默认分支有更新，并提供持续发布入口。它更像一个正在迭代的工具产品，适合进入受控文件任务试用；发布数量不作为稳定性评分。

stitch-skills README 的优点是结构清楚：说明兼容的 coding agents、插件安装、skill 目录规范、脚本与示例，并提供 CONTRIBUTING、SECURITY 与 LICENSE。它的发布历史相对短；README 还明确写明这不是官方支持的 Google 产品，也不在 Google 开源漏洞奖励计划范围内。它更像围绕外部服务的能力包，试用前要额外确认 Stitch MCP、账户和输出验证。

这不是“一个成熟、一个不成熟”的简单排名。OfficeCLI 的文档更接近独立产品交付，stitch-skills 的边界则更依赖外部运行环境。

适用场景不同：OfficeCLI 适合需要可审计办公文件批处理的工程团队，stitch-skills 适合已经具备 Stitch MCP 环境、想复用设计相关 Agent Skills 的团队；没有相应运行环境时，两者都只应停留在阅读阶段。

证据一：README 能否说清最小任务

OfficeCLI 在第一页就把任务收敛为读取、编辑和自动化办公文件，并给出查询、设置、批处理、渲染和校验命令。陌生读者可以据此设计最小试用：读取一份副本、改一个标题、导出预览、比较差异。

stitch-skills 说明它服务于 Stitch MCP，并展示 code-to-design、generate-design、react-components 等技能。这里的最小任务不是“安装一个 skill”，而是让已有 Stitch 项目产出一个可检查的设计或代码结果。若团队没有对应 MCP 环境，README 再清楚也不代表能立即进入工作流。

判断方法：读完 quick start 后，能否写出输入文件、执行动作、预期产物和失败时的停止点。只能写出安装命令，不能算最小任务明确。

证据二：安装与依赖是否被分层

OfficeCLI 同时给出单文件安装、从源码构建、SDK 和直接子进程调用方式，并说明从源码需要 .NET 10 SDK。这个信息让试用者能区分“运行工具”和“参与开发”的成本。

stitch-skills 提供 Codex、Claude Code 等入口，并解释 sparse checkout 和插件目录。但它的实际能力依赖 Stitch MCP 与相应服务，安装 skill 本身不是完整部署。README 对这一点有说明，使用者仍需继续读外部服务文档。

成熟信号不是依赖少，而是依赖是否显式。隐含账户、云服务、模型密钥或本地运行时，都会在交付时变成维护成本。

证据三：示例是否接近可验收产物

OfficeCLI 的示例包含 Word 标题替换、Excel 批量更新、PPT 内容导出、模板合并和文档校验，输入输出都比较具体。它还链接可运行脚本和生成文件，方便对照结果。

stitch-skills 展示每个 skill 的用途和 prompt 示例，并给出目录约定、scripts、resources 与 examples 的角色。这能证明方法被组织化，却不能单独证明生成页面符合团队设计系统。试用时要补截图、构建结果、响应式检查和人工评审。

一个实用检查是：把 README 示例换成一条不理想输入。OfficeCLI 可用损坏副本或复杂格式；stitch-skills 可用已有组件约束和不完整设计描述。能否清楚报告失败，比标准示例是否漂亮更重要。

证据四：license、release、issues 和限制分别说明什么

| 信号 | OfficeCLI | stitch-skills | 不能证明什么 | | --- | --- | --- | --- | | License | Apache-2.0，并有 NOTICE、第三方声明入口 | Apache-2.0 | 不能替代依赖和商标审查 | | Release | 有持续发布入口，核验日默认分支有更新 | 发布历史相对短，核验日默认分支有更新 | 数量多不等于兼容稳定 | | Issues | README 指向 GitHub Issues、SECURITY、故障排查 | 有 Issues、CONTRIBUTING、SECURITY | issue 少不等于缺陷少 | | 限制 | 说明源码构建要求、格式与运行方式 | 明示依赖 Stitch MCP，且非官方支持产品 | README 不会覆盖所有生产风险 |

这里最值得保留的是“证据分栏”。release 看交付节奏，issues 看问题处理，限制看边界意识，四者不能互相替代。

常见误区：把长 README 当成熟度分数

OfficeCLI 的 README 很长，也包含较强的产品表达。真正有用的是其中可执行命令、输出格式、示例、排错和许可，不是页面长度。它仍需在真实文件上验证格式保真、撤销、资源占用和版本兼容。

stitch-skills 的 README 较短，却清楚标出目录、兼容入口和非官方支持边界。对于一个技能集合，这些信息可能已经足够进入小试。不能用完整应用的文档要求，机械处罚一个窄资源库。

另一个误区是把 stars 或 trending 位置当产品成熟度。它们只反映注意力，回答不了升级后文件是否损坏、服务是否可用或责任由谁承担。

技术栈、上手成本、替代方案与投入判断

OfficeCLI 当前仓库主要语言是 C#，源码构建依赖 .NET 10 SDK；如果团队只需读取或生成少量 Office 文件，现有语言的文档库、Office 自动化接口或人工模板可能是更低成本替代。只有 CLI 的批处理、JSON 输出和跨文档动作能明显减少现有脚本复杂度时，才值得进入持续试用。

stitch-skills 当前仓库主要语言由 GitHub 标识为 TypeScript，但核心交付是 skill、脚本与资源组织，并依赖 Stitch MCP。已有设计到代码流程时，可以比较直接使用 Stitch、现有设计系统脚本或其他 Agent skill；没有 Stitch 环境时，不值得仅为阅读 README 搭整套依赖。两个项目都采用 Apache-2.0，第三方服务、生成资产和商标仍要单独审查。

判断是否投入，不比较 README 长短，而比较边界任务后的人工修正：OfficeCLI 是否保住复杂格式并留下可回滚文件，stitch-skills 是否遵守现有组件约束并产生可构建结果。任何一方只在标准示例成功、遇到异常输入无法解释，就先停在学习材料层。

十分钟评估清单

• 用途：能否补全“谁在什么条件下完成什么任务”；
• 最小路径：安装、输入、输出和失败提示是否可执行；
• 依赖：运行时、账户、外部服务和密钥是否显式；
• 示例：是否包含真实产物，而不只有截图；
• 维护：release、changelog、issues、security 是否互相可达；
• 许可：LICENSE、NOTICE、第三方资产和商业边界是否可见；
• 限制：不支持什么、由谁运维、如何退出是否说明。

关键项缺失时，不要立刻判项目差，只把结论降为“需要补证据”。许可证或数据去向不清时，应暂停商用试用。

边界与下一步：README 之后必须做边界任务

本文只核验公开页面，没有在生产环境部署两个项目，也不推断稳定性。页面、版本和维护状态会变化，正式采用当天应再次核验。

下一步可各做一个 30 分钟边界任务：用 OfficeCLI 修改办公文件副本并比较渲染前后；用 stitch-skills 处理一个带现有组件约束的页面，并记录 MCP 依赖与人工修正。README 决定是否值得投入这 30 分钟，真实任务才决定是否继续。