# 云谷 404 迷你黑客松：小红书小工具参赛指南

这份指南写给参加云谷 404 迷你黑客松的开发者。第一期的交付方向是小红书小工具：现场完成一个可以操作的核心页面，按小红书容器规范校验并打包，最后完成演示、投票和上传。

先记住一条：**先做出一个能打开、能操作、讲得清楚的版本，再补细节。**

## 1. 你要交付什么

活动结束前，至少准备好下面三样东西：

1. 一个可以完整体验核心流程的作品；
2. 一个符合小红书小工具规范、可上传的 ZIP 包；
3. 一段现场演示，能说清它解决什么问题，并完成一次真实操作。

现场演示入口和正式上传包不是一回事：

- 现场演示时，可以使用本地浏览器、小红书后台预览或现场认可的其他入口，重点是能稳定打开并操作；
- 上传到小红书后台的是离线 ZIP 包。小工具容器不联网，作品不能依赖接口、CDN、远程图片或在线字体。

## 2. 开始前的准备

建议提前完成这些准备，现场能省下不少排查时间：

- 登录[小红书创作服务平台](https://creator.xiaohongshu.com/new/red-app?source=official)，确认账号可以进入小工具上传页面；
- 阅读[小红书小工具开发文档](https://fe-video-qc.xhscdn.com/fe-platform-file/104101b8323q4m0uaga06277180ac7t8006ptl0e12ek1g)，了解容器支持和限制；
- 准备 Cursor、Claude Code、Codex 或其他可以读取本地 Skill 的 Agent；
- 确认本机可以预览静态网页、解压 ZIP，并能在手机上接收或打开测试产物；
- 尽量提前想好一个方向。到现场后允许调整，但不要把大部分时间花在重新选题上。

如果只是提前学习和测试，可以先做一个很小的样例：一个入口页、一个核心交互、一个结果页。跑通开发、校验、打包和上传这一整条链路，比提前堆很多功能更有用。

## 3. 现场流程

活动按下面的顺序进行，具体时间以现场通知为准。

### 3.1 自我介绍

自愿上台，每人最多 30 秒，只回答三个问题：

- 你是谁；
- 你在做什么；
- 今天想做什么。

不需要介绍完整履历，留下一个让大家认识你的入口就够了。

### 3.2 比赛规则

- 个人参赛，每个人独立完成并展示自己的作品；
- 现场开发，围绕一个明确想法做出核心页面；
- 作品必须能打开，演示时可以真实操作并看到结果；
- 上台讲清楚：它解决什么问题，以及为什么值得一票。

比赛不看功能多少。完成一个可体验的核心流程，比留下五个半成品页面更重要。

### 3.3 开始 Coding

推荐按这个顺序推进：

1. 用一句话写清楚要做什么；
2. 先跑通最核心的操作路径；
3. 再处理移动端适配、异常状态和视觉细节；
4. 提前留出校验、打包和演示排练的时间。

一个合格的一句话目标应该能让别人立刻理解，例如：

> 做一个只需点击屏幕，就能在两分钟内完成并生成结果的电竞能力测试。

如果一句话里塞了多个用户、多个场景和多套功能，范围通常已经太大了。

## 4. 小红书小工具的开发限制

小工具是运行在受限容器里的离线 H5，使用 HTML、CSS 和 JavaScript 开发。开发时重点检查下面几项。

### 4.1 必须做到

- ZIP 根目录直接放 `index.html`，不能再多套一层文件夹；
- 页面、脚本、样式、图片、字体和静态数据全部放进包内，并使用相对路径；
- JavaScript 放在外部 `.js` 文件中，通过普通 `<script src="./...">` 引入；
- 交互使用 `addEventListener`，移动端优先用 Pointer Events 或 Touch Events；
- 页面适配不同屏幕宽度，并处理顶部、底部安全区；
- ZIP 总大小不超过 10 MB，建议尽量控制在 2 MB 以内。

### 4.2 不要使用

- `fetch`、`XMLHttpRequest`、WebSocket、SSE 或其他联网能力；
- 外部 CDN、远程图片、在线字体和远程音视频；
- 内联 `<script>`、`onclick=` 等行内事件；
- `type="module"`、`import`、`export`；
- `eval()`、`new Function()`、WebAssembly、Worker；
- `iframe`、打开外链、新窗口、文件下载；
- 定位、剪贴板、传感器、全屏等容器禁用能力。

如果需要发布笔记、保存图片到相册或跳转小红书原生页面，只使用官方文档列出的 `window.xhs.miniTool.*` 接口。不要自己猜 Bridge 名称或参数。

## 5. 上传前，让 Agent 校验并打包

把下面这句话完整复制给你的 Agent：

```text
从 [https://fe-static.xhscdn.com/mini-tool/1.4.1/minitool-zip-builder.zip](https://fe-static.xhscdn.com/mini-tool/1.4.1/minitool-zip-builder.zip) 下载 skill，解压到工作区（Cursor/Claude Code → .claude/，Codex → .codex/，其余 → .skill/），读取 SKILL.md，对当前工作区产物按指引校验、修复并打包，输出校验摘要和产物路径。
```

Agent 输出后，至少确认这四件事：

- 校验摘要里没有未处理的阻断项；
- ZIP 解压后的第一层能直接看到 `index.html`；
- ZIP 里没有 `node_modules`、`.git`、`.DS_Store`、Source Map 或构建配置；
- 最终产物路径、文件大小和本次测试边界写清楚了。

## 6. 手动验收

Agent 校验通过不等于作品已经在小红书容器里跑通。上传前再手动走一遍。

### 核心流程

- [ ] 首页正常出现，没有白屏或资源缺失；
- [ ] 用户第一眼知道这是做什么的；
- [ ] 核心按钮可以点击，关键流程能从头走到结果；
- [ ] 重复点击、提前点击或快速切换不会让页面卡死；
- [ ] 结果页有返回、重试或继续操作的出口；
- [ ] 刷新或重新打开后，页面仍能正常开始。

### 手机体验

- [ ] 文字和按钮没有被刘海、状态栏或底部手势区遮住；
- [ ] 不依赖鼠标悬停或键盘才能完成关键操作；
- [ ] 页面不会横向溢出，滚动区域可以正常滑动；
- [ ] 输入框不会长期被软键盘挡住；
- [ ] 图片、动画和音视频不会明显拖慢首次打开。

### 容器与真机

- [ ] 小红书后台预览可以打开；
- [ ] 核心流程至少在一台真机上走通；
- [ ] 需要授权的相机、麦克风或相册能力，已实际测试授权、拒绝和再次进入；
- [ ] 使用 `window.xhs.miniTool.*` 的功能已在小红书 App 内测试，普通浏览器测试不能代替这一项。

## 7. 上传到小红书后台

1. 打开[小红书创作服务平台](https://creator.xiaohongshu.com/new/red-app?source=official)并登录；
2. 进入小工具应用的创建或编辑页面；
3. 按页面提示完善应用名称、介绍、图标、类目等资料；
4. 上传 Agent 最终输出的 ZIP，不要上传源码目录、旧包或外层文件夹；
5. 根据后台提示修正缺失项；
6. 使用后台提供的预览能力再次检查；
7. 确认资料、版本和预览结果无误后，再执行页面提供的提交操作。

后台字段和审核要求可能调整，以登录后页面的实际提示为准。若现场只要求上传或预览，不要自行执行正式提交，听现场安排。

## 8. 现场演示怎么讲

演示时长以现场通知为准。建议按下面的顺序，不要先讲技术栈：

1. 一句话说清作品解决什么问题；
2. 从入口开始，完整操作一次核心流程；
3. 展示最终结果；
4. 补充一个最值得记住的设计或实现细节。

演示前关闭无关窗口和通知，准备好初始页面，并再走一遍完整流程。如果作品依赖一次性的随机状态或权限弹窗，提前准备重置方法。

## 9. 现场投票

请完整看完每个作品的演示，再投给你最想继续看到的作品。判断可以围绕三个问题：

- 看得懂：想法清楚，第一眼知道它要解决什么；
- 跑得通：核心体验完整，现场可以真实操作；
- 记得住：有自己的表达，让人愿意继续关注。

投票结束后公布结果、颁奖并合影。记得带上你的作品，它是这次活动最重要的名片。

## 10. 最后检查

离开座位去演示前，快速确认：

- [ ] 一句话目标已经写清楚；
- [ ] 核心流程能从头跑到尾；
- [ ] 小红书后台预览或现场演示入口可以打开；
- [ ] 最终 ZIP 已备份，文件名和版本不会混淆；
- [ ] `index.html` 在 ZIP 根目录；
- [ ] 演示开场、操作步骤和结尾已经排练过一次；
- [ ] 需要现场协助的问题已经及时提出。

遇到问题可以直接举手。先保证作品能被打开，再处理不影响演示的细节。