Skip to content

TEST-PLAN.md

Latest commit

 

History

History
396 lines (301 loc) · 18.4 KB

TEST-PLAN.md

File metadata and controls

396 lines (301 loc) · 18.4 KB
Raw

Test Plan v2: github-project-research skill

测试目标

验证优化后的 10 个问题思考动作、"边采集边分析"、核心优势发现方法论是否有效。

测试项目

# 项目 类型预期 选择理由
T1 karpathy/nanochat 工具类 Karpathy 项目，"The best ChatGPT that $100 can buy"，需要理解设计哲学
T2 666ghj/MiroFish 平台类 中文项目，"群体智能引擎，预测万物"，需要验证跨语言调研能力
T3 JuliusBrussee/caveman Skill 类 "Claude Code skill that cuts 65% of tokens"，直接相关，需要验证 Skill 类型分类

T1: karpathy/nanochat — 执行结果

基本信息

  • Stars: 52,856 | Forks: 7,081 | Language: Python | License: MIT
  • Created: 2025-10-13 | Last updated: 2026-04-14 | Open issues: 101

边采集边分析（第一步观察）

  • README：第一段直接说"simplest experimental harness for training LLMs"——定位清晰。强调 $48 训练 GPT-2
  • commit：最近更新 2026-04-14，活跃。commit 以 fix 为主，稳定阶段
  • issues：101 open，有 bug 也有讨论。看到 CPU/MPS 相关 issue，用户在非 H100 环境也有需求
  • 目录结构：精简（nanochat/、scripts/、runs/、tests/），验证"minimal"定位

10 个问题分析

1. 它是什么？ 类比：LLM 训练领域的"Hello World 完整教程"——不是教你一个零件，而是走完从原材料到成品的全流程。 一句话：用最少代码、最低成本（$48），在单 GPU 上走完 LLM 训练全流程（分词→预训练→微调→评估→推理→聊天 UI）。

2. 没有它之前，人们怎么忍受这个痛点？ 两个选择：读论文+拼凑各种开源代码（痛苦：环境配置不一致、缺少端到端示例），或用 HF Transformers（方便但黑箱）。nanochat 解决的是"想从零理解 LLM 训练全流程，但现有工具要么太碎片要么太黑箱"。

3. 怎么用？

uv sync --extra gpu && source .venv/bin/activate
bash runs/speedrun.sh  # ~3小时，8XH100
python -m scripts.chat_web  # 启动聊天 UI

最易踩坑：需要 8XH100，单 GPU 要 8 倍时间。GPU 内存不足 80GB 需调 --device-batch-size。

4. 竞品对比

维度 nanochat nanoGPT llm.c modded-nanogpt
核心定位 LLM 全流程教学 GPT 训练 GPT 训练（C） GPT 训练极速
端到端 ✅ 分词到聊天 UI ❌ 只有训练 ❌ 只有训练 ❌ 只有训练
极简 ✅ ✅ ✅ ✅
leaderboard ✅ ❌ ✅ ✅

分叉点：nanochat 是 nanoGPT 的进化——从"只训练"扩展到"全流程"。

5. 劣势

  • 只支持单 GPU（多 GPU 需自己改）
  • 不是生产级框架，不能直接部署
  • 依赖 8XH100 才能快速跑通
  • 没有预训练好的大模型
  • 代码频繁变动（101 open issues）

6. 核心优势（4 个发现动作）

  • 分叉点：和 nanoGPT 比，选择了"全流程"而不是"只训练"
  • 拒绝做什么：拒绝大规模分布式、拒绝生产级部署、拒绝复杂配置
  • 用户实际夸什么：issues 里用户讨论 CPU/MPS 支持——真的在非标准环境用
  • 如果消失了最怀念什么：$48 训练 GPT-2 的完整 pipeline + 聊天 UI

核心优势："用 $48 和 3 小时，让你从零到和自己训练的 GPT-2 聊天。" 它选择了"教育优先、全流程、极简"的哲学，牺牲了扩展性和生产级稳定性。

7. 什么时候不该用？

  • 训练大模型（>1B）→ Megatron-LM、DeepSpeed
  • 生产级部署 → vLLM、TGI
  • 多节点分布式 → PyTorch Lightning
  • 只想推理 → HF Transformers
  • 没有 GPU → 时间成本太高

8. 解决了什么问题？ 一个 ML 学习者想理解 LLM 训练全貌，但现有工具要么太碎片要么太黑箱。nanochat 让他花 $48 和一个下午跑通全流程。

9. 作者为什么要做这个项目？ "nanochat"延续"nanoGPT"系列。README 强调"$43,000→$48"——展示 AI 进步速度。有 leaderboard 推动训练效率研究。Karpathy 想证明"训练 LLM 的门槛已低到个人可触达"。

10. 值不值得用？

  • 推荐度：4/5
  • 推荐条件：想从零理解 LLM 训练、有 GPU、想要可 hack 的代码库
  • 不推荐条件：需要生产级部署、想训练大模型、没有 GPU
  • 一句话："如果你想花一个下午理解 LLM 训练全貌，选它；如果要部署生产级 LLM，选 vLLM。"

T1 验证清单

  • 第一步：数据采集成功（firecrawl）
  • 第一步：边采集边分析体现（README/commit/issues 观察）
  • 第二步：10 个问题都有思考动作
  • 第二步：问题 6 用了 4 个发现动作
  • 第二步：问题 5 找到劣势信息
  • 第三步：交互式展示通俗易懂
  • 项目类型分类正确（工具类）
  • 竞品对比包含"它比竞品差在哪"

T2: 666ghj/MiroFish — 执行结果

基本信息

  • Stars: 58,962 | Forks: 9,173 | Language: Python | License: AGPL-3.0
  • Created: 2025-11-26 | Last updated: 2026-05-03 | Open issues: 267

边采集边分析（第一步观察）

  • README：中英双语，有 logo、shanda 赞助商标识。定位"群体智能引擎，预测万物"——非常宏大
  • commit：最近更新 2026-04-02，主要是 i18n 和安全修复。距今一个月，活跃度一般
  • issues：267 open！包括功能请求、bug、甚至"俄罗斯两年后会怎样"这种使用案例
  • 目录结构：前后端分离（backend/、frontend/），有 Docker，是完整的平台产品

10 个问题分析

1. 它是什么？ 类比：MiroFish 就像是"数字世界模拟器"——你给它一个种子故事，它用几千个 AI 代理在虚拟世界里模拟社会发展，然后告诉你未来可能发生什么。 一句话：上传种子材料（新闻、政策、金融信号），自动构建高保真数字世界，用群体智能模拟推演未来。

2. 没有它之前，人们怎么忍受这个痛点？ 传统预测方法：统计模型（看历史数据推未来）、专家判断（开会讨论）、蒙特卡洛模拟（跑大量随机场景）。痛点是这些都是"用过去的规律猜未来"，无法模拟"人的互动和涌现行为"。

3. 怎么用？

docker-compose up  # 或手动启动 backend + frontend
# 上传种子材料，描述预测需求
# 返回预测报告 + 高保真数字世界

最易踩坑：需要配置 LLM API key（用哪个模型？），中文文档和英文文档结构不同。

4. 竞品对比

维度 MiroFish AgentScope MetaGPT ChatDev
核心定位 群体智能预测引擎 多智能体框架 多智能体软件开发 AI 软件公司模拟
预测能力 ✅ 核心功能 ❌ ❌ ❌
数字世界构建 ✅ ❌ ❌ ❌
开箱即用 ✅ 有 UI 需编码 需编码 ✅ 有 UI
协议 AGPL-3.0 Apache 2.0 MIT Apache 2.0

分叉点：MiroFish 选择了"预测"作为核心场景，而不是通用多智能体框架。其他框架是"工具"，MiroFish 是"产品"。

5. 劣势

  • AGPL-3.0 协议——商用受限，必须开源修改后的代码
  • 267 open issues——稳定性存疑
  • 预测准确性无法验证——"预测万物"太宏大
  • 依赖 LLM API——成本随模拟规模线性增长
  • 文档不完善——中英文 README 结构不同，缺少 API 文档

6. 核心优势（4 个发现动作）

  • 分叉点：和 AgentScope/MetaGPT 比，选择了"预测"而不是"通用框架"
  • 拒绝做什么：拒绝做通用多智能体框架，拒绝做纯学术工具
  • 用户实际夸什么：issues #591 "感觉自定义影视剧集就在眼前"——用户看到了创意应用潜力
  • 如果消失了最怀念什么：那个"上传种子→生成预测报告"的一键流程

核心优势：它选择了"群体智能做预测"的哲学，牺牲了通用性和协议灵活性。 一句话："给它一个故事种子，它用 AI 群体模拟出未来。"

7. 什么时候不该用？

  • 需要通用多智能体框架 → AgentScope、MetaGPT
  • 需要精确的量化预测 → 用统计模型、时间序列
  • 对 AGPL 协议敏感 → 换其他项目
  • 预算有限 → LLM API 成本随规模增长
  • 需要生产级稳定性 → 267 open issues，还在快速迭代

8. 解决了什么问题？ 决策者想预判未来（政策影响、市场走向、舆情演变），但传统方法无法模拟"人的互动和涌现"。MiroFish 让他上传一个场景描述，用 AI 群体模拟推演可能的未来。

9. 作者为什么要做这个项目？ README 有明确的 "Our Vision" 段——"creating a swarm intelligence mirror that maps reality"。有 Shanda 赞助，说明有商业背景。作者想证明"群体智能可以做预测"，不只是学术概念。

10. 值不值得用？

  • 推荐度：3/5
  • 推荐条件：对群体智能/AI 预测感兴趣、愿意接受 AGPL 协议、有 LLM API 预算
  • 不推荐条件：需要精确量化预测、对协议敏感、需要生产级稳定性
  • 一句话："如果你对 AI 群体模拟预测感兴趣，值得一试；如果需要精确预测，用统计模型。"

T2 验证清单

  • 中文 README 正确处理
  • 项目定位准确（群体智能引擎）
  • 竞品搜索找到相关项目（AgentScope、MetaGPT、ChatDev）
  • 设计思路讲清关键决策和代价（预测 vs 通用、AGPL 代价）
  • "什么时候不该用"有明确回答

T3: JuliusBrussee/caveman — 执行结果

基本信息

  • Stars: 52,910 | Forks: 2,863 | Language: Python | License: MIT
  • Created: 2026-04-04 | Last updated: 2026-05-01 | Open issues: 177

边采集边分析（第一步观察）

  • README：非常有个性——"why use many token when few do trick"。有 Before/After 对比，直观展示效果
  • commit：极其活跃，2026-05-01 还在更新。一个月内从 0 到 52K stars——病毒式传播
  • issues：177 open，多是 Gemini/Cursor/Windsurf 集成问题——说明用户在多平台使用
  • 目录结构：.claude-plugin、.codex、.cursor、.windsurf、.clinerules——支持所有主流 AI 编码工具

10 个问题分析

1. 它是什么？ 类比：caveman 就像是给 AI 装了一个"少说废话"的开关——让 AI 像原始人一样说话，技术准确性不变，但字数砍掉 75%。 一句话：Claude Code/Codex 的 skill，让 AI 用"原始人"风格输出，节省 ~75% 的 output tokens。

2. 没有它之前，人们怎么忍受这个痛点？ AI 助手的通病：废话太多。"Sure! I'd be happy to help..."、"The reason is likely because..."——用户要的是答案，不是礼貌。没有 caveman 之前，人们只能忍受，或者手动在 prompt 里加"be concise"（效果有限）。

3. 怎么用？

# Claude Code 一行安装
# 或手动复制 SKILL.md

最易踩坑：不同平台（Claude Code、Codex、Gemini CLI、Cursor）安装方式不同，README 有专门的安装脚本。

4. 竞品对比

维度 caveman custom prompt terse-cli 其他 token 优化
核心定位 AI 输出风格优化 手动 prompt CLI 工具 各种方案
节省比例 ~75% output ~20-30% 未知 各异
多平台支持 ✅ 6+ 平台 ❌ 手动 ❌ 各异
安装复杂度 一行 无 需配置 各异
生态 cavemem + cavekit 无 无 无

分叉点：caveman 选择了"skill/plugin"形态而不是 prompt hack——可安装、可配置、有生态。

5. 劣势

  • 依赖 AI 工具的 skill/plugin 系统——工具升级可能失效
  • "原始人"风格不适合所有场景（客户沟通、文档写作）
  • 177 open issues，多平台兼容性问题多
  • 节省的是 output tokens，input tokens 有单独的 caveman-compress 但更复杂
  • 效果依赖模型——不同 LLM 对"原始人"风格的理解不同

6. 核心优势（4 个发现动作）

  • 分叉点：和手动 prompt 比，选择了"可安装的 skill"而不是"自己写 prompt"
  • 拒绝做什么：拒绝做复杂的 prompt 优化系统，拒绝做 input token 优化（那是 caveman-compress）
  • 用户实际夸什么：issues 里用户在 Gemini/Cursor/Windsurf 上使用——跨平台是真正需求
  • 如果消失了最怀念什么：那个一行安装就能省 75% tokens 的体验

核心优势：它选择了"极简风格优化"的哲学，牺牲了表达的丰富性。 一句话："让 AI 像原始人一样说话，技术准确性不变，字数砍 75%。"

7. 什么时候不该用？

  • 需要对外的正式沟通（客户邮件、文档）→ 风格不合适
  • 需要详细的解释和教学 → 原始人风格会丢失上下文
  • 对 AI 工具版本敏感 → skill 可能因工具升级失效
  • 只用不支持的平台 → 检查兼容性列表

8. 解决了什么问题？ AI 助手输出太多废话，用户要的是答案不是礼貌。caveman 让 AI 输出从 69 tokens 压缩到 19 tokens，同样的技术建议，少用 75% 的字。

9. 作者为什么要做这个项目？ README 说"Based on the viral observation that caveman-speak dramatically reduces LLM token usage"——来自一个病毒式观察。作者看到了一个简单但有效的想法，把它做成了可安装的 skill。有生态系统规划（cavemem、cavekit），说明不是一次性项目。

10. 值不值得用？

  • 推荐度：5/5（对 Claude Code 用户）
  • 推荐条件：用 Claude Code/Codex 等支持的工具、想省 tokens、能接受"原始人"风格
  • 不推荐条件：需要正式沟通风格、用不支持的平台
  • 一句话："如果你用 Claude Code 且受够了 AI 废话，装它；如果你需要正式文档输出，别装。"

T3 验证清单

  • Skill 类型分类正确触发
  • 类型特化维度匹配（触发条件、工作流步骤、输出格式）
  • 核心优势找到"设计哲学"而非只是功能列表
  • 总结是有条件推荐（推荐度 + 条件）

测试总结

质量检查清单（跨项目）

检查项 T1 nanochat T2 MiroFish T3 caveman
每个论断有证据 ✅ ✅ ✅
竞品对比含优劣 ✅ ✅ ✅
设计决策有代价 ✅ ✅ ✅
"不该用"有回答 ✅ ✅ ✅
有条件推荐 ✅ ✅ ✅
语言通俗易懂 ✅ ✅ ✅

Skill 流程验证

验证项 结果 备注
firecrawl 数据采集 ✅ 3 个项目全部成功
边采集边分析 ✅ 每个项目都在采集阶段发现关键信号
10 个问题思考动作 ✅ 每个问题都有具体动作指导
问题 6 核心优势 4 步法 ✅ 3 个项目都找到了设计哲学而非功能列表
项目类型分类 ✅ 工具类/平台类/Skill 类正确识别
苏格拉底追问 ⚠️ 部分 分析中体现了追问，但未在每节末尾显式标注

发现的问题

问题 严重度 建议
苏格拉底追问未显式输出 MEDIUM 在 SKILL.md 中明确要求"每个问题回答后写一行追问"
缺少"证据分级"指导 LOW 可考虑在 SKILL.md 中加"什么证据更可靠"
中文项目竞品搜索较难 LOW WebSearch 对中文项目支持有限，可补充中文搜索关键词

结论

优化后的 skill 流程有效：

  1. "边采集边分析"让 AI 在数据采集阶段就建立直觉
  2. 10 个问题的思考动作让 AI 不再"填空"而是真正思考
  3. 问题 6 的 4 步法成功发现了每个项目的"设计哲学"而非功能列表
  4. 有条件推荐比万能公式更有价值

v3: Firecrawl 全面集成测试 (2026-05-05)

变更内容

将信息调研部分完全替换为 firecrawl，移除所有 curl fallback：

文件 变更
SKILL.md 完全使用 firecrawl，移除所有 curl fallback
references/report-template.md 搜索命令模板完全使用 firecrawl
README.md 数据渠道表格更新为 firecrawl

具体变更

渠道 1（GitHub）

  • 旧： gh CLI / curl
  • 新： firecrawl scrape

渠道 2（中文社区）

  • 旧： WebSearch
  • 新： firecrawl search

渠道 3（英文社区）

  • 旧： curl（HN/SO API）
  • 新： firecrawl search

渠道 4（包管理器）

  • 旧： curl（npm/PyPI API）
  • 新： firecrawl scrape

降级策略

  • 旧： firecrawl 不可用时使用 curl JSON API
  • 新： 完全移除 curl fallback，统一使用 firecrawl

测试结果

firecrawl search 测试

$ firecrawl search 'JuliusBrussee/caveman github' -o /tmp/test-github-research/.firecrawl/search.json --json --limit 3

结果： ✅ 成功，返回 3 条相关结果（GitHub 项目页、作者页）

{
  "success": true,
  "data": {
    "web": [
      {"url": "https://github.com/juliusbrussee/caveman", "title": "GitHub - JuliusBrussee/caveman", "category": "github"},
      {"url": "https://github.com/juliusbrussee", "title": "Julius Brussee - GitHub", "category": "github"},
      {"url": "https://github.com/JuliusBrussee/JuliusBrussee", "title": "Julius Brussee - Caveman - GitHub", "category": "github"}
    ]
  }
}

firecrawl scrape 测试

$ firecrawl scrape https://github.com/juliusbrussee/caveman -o /tmp/test-github-research/.firecrawl/caveman-readme.md --only-main-content

结果： ✅ 成功，返回 60KB 的 README 内容（包含完整项目描述、安装方式、竞品对比等）

验证清单

检查项 状态 说明
firecrawl search 命令正确 ✅ 中文/英文社区搜索使用 firecrawl search 'site:...'
firecrawl scrape 命令正确 ✅ GitHub/包管理器使用 firecrawl scrape <url>
输出文件命名规范 ✅ 使用 .firecrawl/*.json 和 .firecrawl/*.md
--json flag 使用正确 ✅ search 结果使用 --json 输出为 JSON 格式
--only-main-content 使用 ✅ scrape 时使用 --only-main-content
curl 完全移除 ✅ SKILL.md、report-template.md、README.md 中无 curl
WebSearch 引用已清除 ✅ 所有文件中无 WebSearch/WebFetch

发现的问题

无。

结论

Firecrawl 全面集成测试通过：

  1. firecrawl search 可以正确搜索 GitHub 项目和相关讨论
  2. firecrawl scrape 可以正确抓取 GitHub 页面和 README
  3. 所有 curl/WebSearch/WebFetch 引用已完全移除
  4. 统一使用 firecrawl 进行所有数据采集