企业官网建设流程全解析

如何向TinyFish Cookbook贡献项目：从仓库结构到README规范的完整开源提交教程

【免费下载链接】tinyfish-cookbookA collection of sample apps and recipes built with the TinyFish web agent. Open-source examples for you to learn & build!项目地址: https://gitcode.com/gh_mirrors/ti/tinyfish-cookbook

TinyFish Cookbook 是一个基于 TinyFish Web Agent 的开源示例应用合集，收录了 Web 检索、并行浏览器代理、行情聚合等可直接运行的实战项目（recipe）。本文是一份面向新手的开源贡献指南，带你走完从理解仓库结构、Fork 克隆、编写规范 README 到提交 Pull Request 的完整流程，让你的第一个 PR 一次通过。

1. 先看懂仓库结构：每个项目就是一个独立文件夹 📁

TinyFish Cookbook 采用扁平化目录结构：每个示例应用直接放在仓库根目录，各自独立、互不嵌套。这一点在 CONTRIBUTING.md 中有明确说明：

TinyFish-cookbook/ ├── .github/ # CI 工作流、资产 ├── lego-hunter/ # 已有项目：乐高补货监控 ├── fast-qa/ # 已有项目：AI 测试执行平台 ├── YOUR-NEW-PROJECT/ # ← 这就是你要贡献的新项目！ ├── README.md # 仓库总目录（项目要登记在这里） ├── CONTRIBUTING.md # 贡献规范 ├── Makefile # 本地安全工具初始化 ├── renovate.json # 依赖自动升级配置 └── osv-scanner.toml # 依赖漏洞扫描配置

仓库根目录的 README.md 按"用途"而非技术栈对配方分类，常见类别有：

💡 贡献前建议先读 2~3 个同类项目的 README，感受仓库的文档风格。

2. 一键克隆仓库并创建功能分支

首次贡献开源项目？按下面三步操作即可（官方在 CONTRIBUTING.md 中也特别提到：第一次提交 PR 的同学可以在社区频道联系工程师一对一指导）：

# 1. 克隆仓库 git clone https://gitcode.com/gh_mirrors/ti/tinyfish-cookbook cd tinyfish-cookbook # 2. 创建独立功能分支，切勿直接在 main 分支上开发 git checkout -b your-name/cool-new-app # 3. 在根目录新建项目文件夹，开始编码 mkdir your-new-app

📌 三个关键习惯：分支命名带你的前缀、频繁提交、API Key 只放.env.local（仓库会扫描泄露的密钥）。

3. README 规范：必须写足 7 个要素 ✅

这是贡献中最重要的一环。根据 CONTRIBUTING.md 的规定，每个项目文件夹必须包含一个README.md，且写满以下 7 项：

1. 标题（Title）——项目名
2. 在线演示链接（Live link）——部署后的 Demo 地址
3. 2~3 句简介——说明应用做什么，并明确指出 TinyFish API 用在了哪里
4. 演示视频/动图——GIF 或视频均可
5. 调用 TinyFish API 的代码片段——Prompt 过长可截断
6. 运行说明——如何跑起来，声明所需的环境变量
7. 架构图（Architecture Diagram）——数据流向一目了然

仓库里的现成范例非常值得对照参考，比如 fast-qa/README.md 的 7 要素全部齐备：

其核心内容可以概括为：

• 简介：用自然语言描述测试用例 → TinyFish 浏览器代理并行执行 → 输出结构化通过/失败结果；
• 架构图：用 ASCII 图展示客户端、API 路由与 TinyFish SDK 的 SSE 事件流；
• Setup：声明TINYFISH_API_KEY、GROQ_API_KEY两个环境变量，npm install && npm run dev即可运行；
• Constraint Checklist 表格：列出"是否使用数据库、API Key 是否暴露到浏览器"等自检项。

tinyskills/README.md 则展示了演示截图的标准引用方式——使用本地相对路径，截图放在项目根目录：

## Demo [![TinySkills Demo](https://raw.gitcode.com/gh_mirrors/ti/tinyfish-cookbook/raw/dcf321cee6e89c0b1799c50c1fa8e2ae28add5e8/tinyskills/screenshot.png?utm_source=gitcode_repo_files)](https://link.gitcode.com/i/d4b7a76ba6363b189bf57195977b4f9a)

📸截图建议：横版界面截图（如 1280x720），存放在项目根目录或public/下，用相对路径引用；避免只放一张 Logo。

4. 写一段"点亮" TinyFish 的代码片段

规范要求的第 5 项是展示调用 TinyFish API 的代码。参考 lego-hunter/README.md 的做法，一段简短的 SDK 调用 + 事件流注释就足够：

// app/api/search-lego/route.ts const response = await client.agent.stream({ url, goal }); // EventType.STREAMING_URL → 实时 iframe // EventType.COMPLETE + RunStatus.COMPLETED → 解析 JSON 结果

再配合一段"结果长什么样"的说明（例如每个代理返回{ inStock, price, shipping, productUrl }），读者就能快速理解 TinyFish 在你的应用里扮演什么角色。

5. 本地运行与提交前的安全自检

提交 PR 前，先确保应用能跑通：

# 进入你的项目文件夹 cp .env.example .env.local # 填入 TINYFISH_API_KEY npm install npm run dev # 打开 http://localhost:3000

仓库内置了自动安全检查，你的 PR 会触发以下 CI 工作流：

🔐 常见翻车点：把真实TINYFISH_API_KEY写进了代码或提交进了.env——PR 会直接挂在密钥扫描上。提交前执行git diff复查，敏感值一律只留在.env.local。

此外，根目录的 Makefile 提供了make init，可一键配置本地 pre-commit 钩子与 TruffleHog 检查，建议提前跑一遍。

6. 提交 Pull Request 的 5 步流程

1. 充分自测：确保 Demo 可复现，README 覆盖 7 要素；
2. 推送到你的分支：git push origin your-name/cool-new-app；
3. 发起 PR：从你的分支指向仓库的main分支，标题建议写清"新增 XX 配方"，正文简述功能与 TinyFish 用法；
4. 等待审查：维护者会实际运行你的应用并给出反馈，及时响应即可；
5. 合并 🎉：通过后 PR 会被合并，你的项目会出现在仓库 README.md 的 Recipes 分类表中。

常见疑问 FAQ

Q1：项目必须用 Next.js 吗？不必。仓库里既有 Next.js 应用（如 fast-qa），也有 Python 后端 + 前端（如AABW_Vietnam_Hackathon_Samples/finsight）、纯 Discord Bot（waifu-deal-sniper）、n8n 工作流（N8N_WorkFlows/）。关键是结构独立、文档规范。

Q2：演示应用还没部署怎么办？可以先写_add URL after deploy_（多个已合并项目的 README 都这样标注），但合并前建议补上真实链接。

Q3：只贡献一个 Skill 或脚本可以吗？可以。仓库还有 skills/ 与 scripts/ 目录，相关变更由 validate-skills 工作流 自动校验，同样是受欢迎的贡献类型。

记住仓库的贡献者文化：卡住了就去找官方工程师聊聊。祝你的第一个 TinyFish 配方早日合入！🚀

【免费下载链接】tinyfish-cookbookA collection of sample apps and recipes built with the TinyFish web agent. Open-source examples for you to learn & build!项目地址: https://gitcode.com/gh_mirrors/ti/tinyfish-cookbook