评估代理框架

对开源代理框架的投资就绪度进行结构化评估。新颖的价值在第 2-3 步：通过贡献存活率量化社区健康，并测量被取代风险 —— 外部工程精力被浪费的最常见原因。最终分类（INVEST / EVALUATE-FURTHER / CONTRIBUTE-CAUTIOUSLY / AVOID）在投入开发周期前校准资源分配。

适用场景

• 评估是否在生产中采用某代理框架
• 评估对项目所依赖框架的依赖风险
• 决定是否向外部项目投入工程精力
• 在 build-vs-adopt 决策中比较竞争框架
• 在重大版本、治理变更或收购后重新评估框架

输入

• 必需：framework_url —— 框架仓库的 GitHub URL
• 可选：
  • comparison_frameworks —— 用于基准对比的备选框架 URL 列表
  • use_case —— 用于架构对齐评估的预期用例（如"多代理编排"、"工具使用流水线"）
  • contribution_budget —— 计划工程小时数，用于校准投资档位

步骤

第 1 步：收集框架普查

在更深入分析之前，收集关于项目规模、活动和环境定位的基础数据。

1. 获取并阅读 README.md、CONTRIBUTING.md、LICENSE 及任何架构文档（docs/、ARCHITECTURE.md）
2. 收集定量指标：
   • Star、fork、未解决 issue、未解决 PR：gh repo view <repo> --json stargazerCount,forkCount,issues,pullRequests
   • 依赖仓库：检查 GitHub 的 "Used by" 计数或 gh api repos/<owner>/<repo>/dependents
   • 发布节奏：gh release list --limit 10 —— 注意频率以及发布是否遵循 semver
3. 计算 bus factor：识别过去 12 个月按提交计数的前 5 名贡献者。若头部贡献者占比 >60%，bus factor 极低
4. 映射环境定位：
   • 先驱者：先行者，定义了类别（高影响力，对追随者高被取代风险）
   • 快速跟随者：在先驱者后 6 个月内推出，迭代该概念
   • 后来者：在类别稳定后到达，在功能或治理上竞争
5. 若提供了 comparison_frameworks，为每个备选收集相同指标

预期结果： 普查表，包含 star、fork、依赖、发布节奏、bus factor 和目标（及对比若提供）的环境定位。

失败处理： 若仓库私有或 API 速率受限，回退到手动 README 分析。若指标不可用（如自托管 GitLab），记录差距并继续定性评估。

第 2 步：评估社区健康

量化项目是否欢迎、支持并留住外部贡献者。

1. 计算外部贡献存活率：
   • 拉取最后 50 个已关闭的 PR：gh pr list --state closed --limit 50 --json author,mergedAt,closedAt,labels
   • 将每个 PR 作者分类为内部（组织成员）或外部
   • 计算：survival_rate = merged_external_PRs / total_external_PRs
   • 健康阈值：>50% 存活率；担忧：<30%
2. 测量响应性：
   • issue 首次响应时间：从 issue 创建到首次维护者评论的中位时间
   • PR 合并延迟：外部 PR 从打开到合并的中位时间
   • 健康：<7 天首次响应、<30 天合并；担忧：>30 天首次响应
3. 评估贡献者多样性：
   • 过去 6 个月外部/内部贡献者比
   • 拥有 >=2 个已合并 PR 的独特外部贡献者数（重复贡献者表明健康生态系统）
4. 检查治理工件：
   • CONTRIBUTING.md 存在且可执行（不仅是"提交 PR"）
   • CODE_OF_CONDUCT.md 存在
   • 治理文档描述决策流程
   • issue/PR 模板指导贡献者

预期结果： 社区健康记分卡，包含存活率、响应时间、多样性比例和治理工件检查清单。

失败处理： 若 PR 数据不足（新项目 <20 个已关闭 PR），记录样本量限制并加重其他信号权重。若项目使用非 GitHub 平台，将查询适配该平台的 API。

第 3 步：计算被取代风险

确定外部贡献被内部开发淘汰的可能性 —— 框架采用者和贡献者的最大单一风险。

1. 抽样最后 50-100 个已合并的外部 PR（若更少则全部）
2. 对每个已合并的外部 PR，检查贡献的代码后来是否：
   • 被回滚：引用该 PR 的显式回滚提交
   • 被重写：相同文件/模块在 90 天内被内部贡献者大幅修改
   • 被淘汰：功能在后续版本中被移除或替换
3. 计算：supersession_rate = (reverted + rewritten + obsoleted) / total_merged_external
4. 将已发布的路线图（若可用）与外部贡献者活跃的领域对照：
   • 高重叠 = 高被取代风险（内部会覆盖外部工作）
   • 低重叠 = 较低被取代风险（外部填补内部不会做的空白）
5. 检查"贡献陷阱"：看起来对贡献友好但已计划内部重写的领域
6. 参考基准：NemoClaw 分析显示 71% 的外部 PR 在 6 个月内被取代 —— 用作校准点

预期结果： 被取代率（百分比），按类型分解（被回滚/被重写/被淘汰）。路线图重叠评估。

失败处理： 若提交历史浅或被压缩合并（丢失归属），通过比较外部 PR 文件路径与后续版本中更改的文件来估计被取代。注明对估计的信心降低。

第 4 步：评估架构对齐

评估框架架构是否在不过度锁定的情况下支持你的用例。

1. 映射扩展点：
   • Plugin/extension API：框架是否暴露已记录的插件接口？
   • 配置面：行为是否可在不 fork 的情况下定制？
   • Hook/callback 系统：能否在关键点拦截和修改框架行为？
2. 评估锁定风险：
   • 重写成本：估计迁移所需的工程精力（天/周/月）
   • 数据可移植性：能否以标准格式导出数据/状态？
   • 标准遵循：框架是否使用开放标准（agentskills.io、MCP、A2A）或专有协议？
3. 评估 API 稳定性：
   • 每个主要版本的破坏性变更计数（CHANGELOG、迁移指南）
   • 检查弃用政策（移除前的提前警告）
   • 评估 semver 遵循（破坏性变更仅在主版本）
4. 检查与具体用例的对齐：
   • 若提供了 use_case，评估框架架构是否自然支持它
   • 识别需要变通的任何架构不匹配
5. 评估互操作性：
   • agentskills.io 兼容性（技能模型对齐）
   • MCP 支持（工具集成）
   • A2A 协议支持（代理间通信）

预期结果： 架构对齐报告，包含扩展点清单、锁定风险评估（低/中/高）、API 稳定性评分和用例契合度评估。

失败处理： 若架构文档稀少，从代码结构和公开 API 表面推导评估。若框架太年轻无稳定历史，注明此并加重治理信号权重。

第 5 步：评估治理与可持续性

评估项目的治理模型是否支持长期可行性和对外部贡献者的公平对待。

1. 分类治理模型：
   • BDFL（终身仁慈独裁者）：单一决策者 —— 决策快、bus factor 风险
   • 委员会/核心团队：分布式决策 —— 较慢但更具弹性
   • 基金会支持：正式治理（Apache、Linux Foundation、CNCF）—— 最可持续
   • 企业控制：单一公司驱动开发 —— 警惕拔网线风险
2. 评估资金与可持续性：
   • 资金来源：VC 支持、企业赞助、资助、社区资助、无资助
   • 全职维护者数量：>=2 健康；0 是红旗
   • 收入模式（若有）：项目如何维持自身？
3. 评估贡献者保护：
   • 许可证类型：宽松（MIT、Apache-2.0）vs copyleft（GPL）vs 自定义
   • CLA 要求：签署 CLA 是否转移使贡献者处于不利地位的权利？
   • 贡献者认可：外部贡献者是否在版本、changelog、文档中获得致谢？
4. 检查安全态势：
   • 安全披露政策（SECURITY.md 或等价物）
   • 从 CVE 披露到补丁版本的中位时间
   • 依赖更新实践（Dependabot、Renovate、手动）
5. 评估轨迹：
   • 治理模型是否在演化（如向基金会转移）？
   • 是否近期有领导层变更、收购或重新许可？
   • 维护者与贡献者之间是否有公开冲突？

预期结果： 治理评估，包含模型分类、可持续性评级（可持续/有风险/危急）、贡献者保护评估和安全态势摘要。

失败处理： 若治理信息无文档，将缺失本身视为黄旗。通过检查谁合并 PR、谁关闭 issue、谁做发布决策来检查隐式治理。

第 6 步：分类投资就绪度

将所有发现综合为四档分类，附具体依据和可执行建议。

1. 对每个维度评分（1-5 量表）：
   • 社区健康：存活率、响应性、多样性
   • 被取代风险：率、路线图重叠、贡献陷阱（反转：越低越好）
   • 架构对齐：扩展点、锁定、稳定性、用例契合
   • 治理可持续性：模型、资金、保护、安全
2. 应用分类阈值：
   • INVEST（所有维度 >=4）：健康社区、低被取代（<20%）、对齐架构、可持续治理。可安全采用并投入工程精力。
   • EVALUATE-FURTHER（混合，无维度 <2）：信号混合，需要具体跟进。记录需要澄清的内容并设定重新评估日期。
   • CONTRIBUTE-CAUTIOUSLY（任一维度 2，无 <2）：高被取代（>40%）或治理担忧。将贡献限于显式请求的工作、维护者批准的范围，或与核心解耦的插件/扩展开发。
   • AVOID（任一维度 1）：关键红旗 —— 被遗弃项目、对外部敌对（存活率 <15%）、不兼容许可证或迫在眉睫的拔网线指标。不要投入工程精力。
3. 撰写分类报告：
   • 以档位分类和一句话理由开篇
   • 用关键证据汇总每个维度评分
   • 若提供了 contribution_budget，根据档位推荐如何分配那些小时数
   • 对于 EVALUATE-FURTHER，列出需要答案的具体问题并提议时间表
   • 对于 CONTRIBUTE-CAUTIOUSLY，指定哪些贡献类型安全（插件、文档、测试）vs 风险（核心功能）
4. 若评估了 comparison_frameworks，产出对所有框架排名的对比矩阵

预期结果： 分类报告，包含档位、维度评分、证据摘要和针对投资上下文定制的可执行建议。

失败处理： 若数据空隙阻碍自信分类，默认 EVALUATE-FURTHER 并显式记录缺失的数据及如何获取。在不确定时绝不默认 INVEST。

验证清单

• 收集普查数据：star、fork、依赖、发布节奏、bus factor、环境定位
• 量化社区健康：存活率、响应时间、贡献者多样性、治理工件
• 计算被取代风险，按类型分解（被回滚/被重写/被淘汰）
• 评估架构对齐：扩展点、锁定风险、API 稳定性、用例契合
• 评估治理：模型、资金、贡献者保护、安全态势
• 产出分类：INVEST / EVALUATE-FURTHER / CONTRIBUTE-CAUTIOUSLY / AVOID 之一
• 每个维度评分有来自分析的具体证据支持
• 建议可执行并校准到贡献预算（若提供）
• 显式记录数据空隙和信心限制

常见问题

• 将流行度与健康混淆：高 star 但低贡献者多样性意味着单点故障。一个 50k-star 项目只有一个维护者，比 2k-star 项目有 15 个活跃贡献者更不健康。
• 忽略被取代风险：外部贡献失败的最常见原因。若内部开发常规覆盖外部工作，欢迎社区毫无意义。
• 过度看重架构而不检查治理：精美设计的框架若治理模型不可持续或对外敌对仍可能失败。
• 将 EVALUATE-FURTHER 视为 AVOID：混合信号需要调查，而非拒绝。设定具体的重新评估日期并列出待回答的具体问题。
• 快照偏差：所有指标都是时间点的。当前指标良好但下降的项目，比当前指标平庸但改善的项目更糟。始终检查 6-12 个月的趋势方向。
• CLA 自满：某些 CLA 将版权转让给项目所有者，意味着你的贡献成为他们的专有资产。阅读 CLA 文本，而不只是复选框。
• 锚定单一框架：没有对比框架时，任何项目看起来要么很棒要么很糟。即使非正式地，也始终对照至少一个备选基准。

相关技能

• polish-claw-project —— 此评估告知的贡献工作流
• review-software-architecture —— 第 4 步用于架构评估
• forage-solutions —— 用于对比的备选框架发现
• search-prior-art —— 环境映射和先前工作分析
• security-audit-codebase —— 第 5 步引用的安全态势评估
• assess-ip-landscape —— 许可证和 IP 风险分析