不是「帮人做决策」，是「帮人看清自己」。
一个元 Skill。任何 AI 拿到它，就能陪人类走完一整套沙盒包创建流程——从「我到底想做什么」到「代码写完、验证通过、可以发布」。
它不是代码生成器。它是决策框架：让人在写第一行代码之前，先确认自己走在对的路上。
语法错误不是错误。走错方向才是。
- 不知道自己要什么，就开始写代码 → 错误。Skill 会在 Shape 阶段拦住你，先问「你真正想要什么体验」。
- 明明在同一个框架里深耕就能解决，却为了「换个形态」重构整个项目 → 错误。Skill 的淘汰链不会让你跳过这一问：「不换形态，深耕能达到吗？」
- 做完了一个沙盒包，但别人拿起来不知道怎么用 → 错误。Skill 会追问「别人能看懂你的初衷吗」，并让你选择兼容层级——原生 QuickJS？Package API？跨包调用？公开 API？
- 性能「刚刚好够」就停手，或者「过度优化」到不可维护 → 错误。Skill 按搜索/文件/网络/数据处理四种类型给出了精确的性能准则——不是越多越好，是刚刚好。
- 报错了不知道问题出在哪一层 → 错误。Skill 的
retry_trace故障追踪链会把每一层的错误码推回来，让你能定位到具体是原生、包装层、还是跨包调用出了问题。
一句话：错误不是代码跑不通。错误是你做完了才发现——这个东西从一开始就不该这样做。
- JSON 循环引用 → 直接崩溃。用
JSON.stringify前确认数据结构里没有循环引用。 - 单次日志过多 → UI 线程阻塞。大对象用
JSON.stringify(obj, null, 0)压缩，或者分批输出。 - fetch 无超时 → 永久挂起。每个 fetch 必须包
AbortController+ 超时。 - 同步循环中大量异步 → 内存堆积。用
for...of+await，别用forEach+ 异步。 - 正则回溯爆炸 → CPU 卡死。复杂正则先在小数据集上验证，限制输入长度。
- 缓存设计缺失 → 每次都重新算。读盘操作必须有内存缓存（如 5 秒 TTL），写入即时刷新。
| 类型 | 核心策略 | 红线 |
|---|---|---|
| 搜索类 | Promise.all 并发 + 去重去噪 + 结果缓存 | 并发数上限 ≤ 8，超出分批 |
| 文件类 | 流式读写，避免整文件加载到内存 | 大文件（>10MB）禁止 readFile 整读 |
| 网络类 | 超时必设 + 重试退避 + 响应压缩 | 无超时的 fetch = 定时炸弹 |
| 数据处理 | 懒加载 + 分页 + 增量计算 | 禁止一次性加载全量数据到数组 |
四个层级，选错一层，后续都是徒劳：
- 🔴 原生 QuickJS：最快，但只有纯文本进出。适合内部工具。
- 🟡 Package API 统一包装：
{success, data, error, elapsed_ms}。适合团队内多个沙盒包协作。 - 🟠 跨包调用 + 错误码：
-1到-9错误码体系 +retry_trace故障追踪。适合复杂系统。 - 🟢 公开 API：语义化版本 + 向后兼容承诺。适合对外发布。
不需要一开始就选最顶层的。从你实际需要的层级开始，往上一层层加。
- 支持沙盒包（Sandbox Package）的 AI 平台
- 平台提供的沙盒包开发工具包——本 Skill 的 Develop 阶段需要平台的沙盒脚本调试、文件写入等工具。没有这个依赖，开发阶段的验证步骤无法执行。
- 将整个
sandbox-package-creator文件夹放入平台的 Skill/Skills 目录 - 确认平台的沙盒包开发工具已激活
- 在对话中提及「sandbox-package-creator」，AI 应自动加载
定义：不是代码写错了——两个独立设计各自正确，但交叉地带没人画线。A没错，B没错，A×B的缝里藏了魔鬼。
| 族 | 成员 | 核心问题 |
|---|---|---|
| 🪞 自指 | #50 #51 #56 | 机制把自己当处理对象 |
| 💂 阻断自毁 | #52 #53 | 保护者掐了自己命脉 |
| 🐚 新旧分裂 | #48 #54 | 版本号新，跑的是旧的 |
| 🎯 去重盲区 | #46 #49 | 正则没错，「重复」没定义 |
| 📏 阈值没跟 | #45 #55 | 指标忘了同步更新 |
| 🩺 诊断失准 | #47 #59 | 报错报错病因 / 该报说正常 |
| ⏰ 初始化叛变 | #57 | 一切没错，只是叫早了一个 |
| 🔤 媒介错位 | #58 | Python写Markdown——望安本人案例 |
族索引加在Bug表格前，找去重不看自指，找阻断不翻缓存。编号不动，物理按族重排。
-
Bug #45：格式越原生→字节越大→阈值失效。Search Vault v4.0真实教训
-
四条修复路径：耦合审查 / 阈值按比例 / 渐进熔断 / 摘要自带字节数
-
Bug总数：44→59条 | 行数：~630→722行
-
免免原话：「明明是严谨学术创作可却弄了一堆地狱笑话」
v2.5.0 已有：
- 新增 1.3.1 形态区别表（普通JS vs ToolPkg 12维度对比 + 方言警告 + 版本声明规则）
- 新增 1.5.1 受众维度表（AI用户 vs 人类用户 + 设计铁律）
- 新增 5.0 第一次创建必读（3条冷门致命错误 + 11个典型案例A–K + 13条跳过清单）
- Bug预判扩至44条（新增 🟣JS通用陷阱14条，方言标注，来自Matt Pocock蒸馏+多引擎搜索）
- 5.0跳过清单补全：方言差异、受众错位、tsc≠测试等
完整变更见 CHANGELOG。
所有旧版 SKILL.md 收录在 archive/ 目录——从 v1.0 骨架到 v2.0，逐版可对照：
| 版本 | 行数 | 关键里程碑 |
|---|---|---|
| v1.0.0 | 118 | 四阶段骨架：Explore→Diagnose→Confirm→Develop + 13条Bug预判 |
| v1.1.0 | 150 | +自由判断边界 +常见手误 +自测清单 |
| v1.2.0 | 214 | +Shape阶段 +淘汰链 |
| v2.0.0 | 423 | +协作协议 +愿望节 +兼容层级 +QuickJS陷阱 |
| v2.5.0 | 646 | +形态区别表 +受众维度 +44条Bug +5.0必读 |
| v2.6.0 | 735 | 设计耦合族：15条Bug(#45-#59)按8族归类 + 族索引 + 案例L |
| v2.7.0 | 747 | 形式语言概念框 + 沙盒包≠沙盒——substrate错位概念框 + 设计耦合族 |
点击版本号直接在 GitHub 上浏览对应文件。
参见 LICENSE。
这份 README 由 Operit 和免免共同授予——技术错误我告诉你，什么才算错误免免告诉你。