@fectivnfy112358/minimax-code-web 0.1.0-preview.0 → 0.1.0-preview.3

package/server/assets/skills/skill-creator/references/anti-patterns.md

@@ -0,0 +1,149 @@
+# Anti-Patterns — Mavis 实际见过的 skill 反例
+
+> 这份清单不是从外部抄的，是从 Mavis 项目里见过的真实 skill 失败案例提炼的。每条都标注"为什么是反模式 + 该怎么改"。
+
+## 1. 默认建 `.env` / `.env.example` / `.gitignore`
+
+**反例来源**：旧版 `{{DATA_DIR}}/skills/skill-creator/SKILL.md` 把 `.env.example` 当 default scaffold。
+
+**为什么是反模式**：
+- 大多数 skill 不需要外部凭证（如 `pdf`、`mavis`）
+- 凭空建 `.env` 给用户错觉"必须配置"
+- `.gitignore` 是仓库级关心，不该放进 skill 包
+
+**怎么改**：只有 skill 实际需要 API key 等外部凭证时才建。skill 创建时主动确认"需要外部配置吗？"
+
+## 2. 把 README.md / CHANGELOG.md / INSTALLATION.md 塞进 skill 目录
+
+**反例来源**：从外部 marketplace 导入的 skill（如某些 ClawHub skill），同目录有 5 个 `.md` 文件。
+
+**为什么是反模式**：
+- skill 目录是给 LLM 读的，不是给人看的产品文档
+- README/CHANGELOG/INSTALLATION 是面向人类用户的，挤占模型 context
+- 模型不知道该不该读这些文件，浪费 token
+
+**怎么改**：skill 包里只放 LLM 执行需要的文件。版本演进信息放在 git history，使用说明写在 SKILL.md 的 `When to use` 里。
+
+## 3. 用 ALWAYS / NEVER / MUST 把模型限死
+
+**反例**：
+```markdown
+## Procedure
+1. ALWAYS read the entire codebase first
+2. NEVER use any tool other than Read
+3. MUST output JSON
+```
+
+**为什么是反模式**：
+- 模型读了大量 ALWAYS/NEVER 后会过拟合到字面规则，丢失判断力
+- 不解释 why，模型遇到边界情况只能僵硬执行或直接放弃
+- 遇到合理特例（如"这次需要一个小补丁，不需要读整个 codebase"）模型会卡住
+
+**怎么改**：写"为什么这么做"和"不这么做的后果"。例：
+```markdown
+1. 先读 codebase 大致结构（避免凭空假设导致改错文件）
+2. 优先用 Read，必要时也可以用 Grep（Read 慢但准，Grep 快但可能漏匹配）
+3. 输出 JSON 格式，因为下游脚本会解析；如果 JSON 不合适（比如纯叙述性回答），改用 markdown 但要在最后明确说"输出格式：markdown"
+```
+
+## 4. description 只堆关键词
+
+**反例**：
+```yaml
+description: PDF, text, extract, OCR, parse, document, file, read
+```
+
+**为什么是反模式**：
+- 没说"什么时候用"，LLM 看了关键词命中就触发，不管语境
+- 没说"什么时候不用"，会和近义 skill（如 pdf）冲突触发
+
+**怎么改**：见 `description-rubric.md`，必须含 What + When + Near misses。
+
+## 5. 一个 skill 包里塞多个 sub-skill / 多个 sub-agent
+
+**反例**：从外部抄来的 skill，目录里有 `agents/`、`sub-skills/`、`commands/`、`hooks/` 全套。
+
+**为什么是反模式**：
+- skill 是单一能力包，不是 mini-platform
+- 多 sub-skill 增加触发歧义，LLM 不知道该激活哪个
+- Mavis 已经有 Team Engine 处理多 agent 协作，skill 内部不需要再造一套
+
+**怎么改**：一个 skill 一个明确能力。需要协作多 agent 用 Team Engine plan，不要塞进 skill 内部。
+
+## 6. SKILL.md 超长（>500 行），全部塞主文件
+
+**反例来源**：一些社区 skill SKILL.md 写到 1000+ 行，包含 11 个思考模型 / 4-tier 复杂度等元理论。
+
+**为什么是反模式**：
+- 触发 skill 后这 1000 行全进 context，挤压用户对话空间
+- 大量元理论是写给 skill 作者看的，不是给执行的 LLM
+
+**怎么改**：SKILL.md 主体 ≤ 500 行，把详细参考拆 `references/<topic>.md`，主文件用"详见 references/foo.md"引用。LLM 需要时再读。
+
+## 6.5 把 SKILL.md 写成 README / 教程 / API 文档
+
+**反例**：主文件里充满 "What this tool does"、"How it works"、"Command line usage"、"As a Python module"，外加一长串示例命令。
+
+**为什么是反模式**：
+- skill 是给另一个模型执行的，不是给人类读产品说明
+- 背景介绍、功能导览、模块示例会稀释真正重要的执行规约
+- 这类内容最容易和 frontmatter 里的触发信息重复，白白占 context
+
+**怎么改**：
+- `description` 负责回答 "什么时候触发 / 什么情况别触发"
+- 正文只保留 procedure / output contract / failure handling / 极少量 canonical examples
+- 需要细节时，优先让模型读脚本、`--help` 或 `references/`
+
+## 7. 用 Python 工具链（与 Mavis 生态不一致）
+
+**反例**：从外部抄来的 skill 自带 `requirements.txt`、Python 脚本、需要 `pip install` 的依赖。
+
+**为什么是反模式**：
+- Mavis daemon / CLI 是 Node.js / TypeScript ESM
+- 引入 Python 依赖增加用户环境复杂度
+- 大多数 skill 需要的脚本（校验、聚合）用 Node.js + 内置 fs 就够
+
+**怎么改**：脚本用 Node.js 写，不依赖第三方 npm 包（除非是 Mavis 本来就装了的）。
+
+## 8. 抄外部 skill 的脚本/模板/schema 直接放进 Mavis
+
+**反例**：把上游 skill-creator 的 `quick_validate.py` / `evals.json` schema 复制改名直接用。
+
+**为什么是反模式**：
+- 外部 schema 是按外部生态设计的（Python/外部 coding agent），可能与 Mavis 不兼容
+- 抄过来即使能跑也是"陌生外科器官"——后续维护不知道为什么这么写
+- Mavis 自己的语境（Team Engine、scratchpad、agent system）需要不同的设计
+
+**怎么改**：思想可以借鉴，但每个文件都按 Mavis 实际需要原创实现。详见 `when-to-bundle-scripts.md`。
+
+## 9. 不解释"为什么这个 skill 存在"
+
+**反例**：frontmatter `description` 很弱，正文也直接进入 `## Procedure`，导致触发边界不清。
+
+**为什么是反模式**：
+- LLM 是否打开 skill 主要看 `description`
+- 如果 `description` 没讲清能力边界和 near misses，模型可能漏触发或误触发
+
+**怎么改**：先把 What / When / Near misses 写进 `description`。正文只在确实需要时补充输入要求，不要再复制一遍触发列表。
+
+## 10. 默认依赖外部安装脚本 / install.sh
+
+**反例**：`install.sh` 自动改用户的 `~/.bashrc` / `~/.zshrc`。
+
+**为什么是反模式**：
+- skill 是协议产物，不该有副作用
+- 用户对修改 shell config 极度敏感
+- Mavis 自己会发现并加载 skill，不需要 install 脚本
+
+**怎么改**：skill 包里不放 install.sh。如果真需要外部依赖，在 SKILL.md 的 `## Setup`（仅本次需要时才有这一节）里明确写"请手动 X"。
+
+## 11. Shell 命令只写 bash 版本，不做 Windows 适配
+
+**反例来源**：早期 skill 只写 `python3 scripts/xxx.sh | grep "Page size"` 这类 bash 命令，Windows 用户跑不起来。
+
+**为什么是反模式**：
+- Mavis 在 Windows 上直接用 PowerShell 执行命令，没有 Unix 兜底层
+- `python3`（Windows 上通常是 `python`）、`grep`、`sed`、`/tmp/` 等在 PowerShell 里不存在或行为不同
+- 用户不应该为了跑一个 skill 还要自己翻译命令
+
+**怎么改**：如果 skill 包含 shell 命令、脚本调用或 `python3` 引用，加 `## Windows (win32) platform notes` 段落，提供 PowerShell 等价命令或跨平台替代方案。纯流程 skill 可跳过。

package/server/assets/skills/skill-creator/references/commands-macos-linux.md

@@ -0,0 +1,38 @@
+# skill-creator Commands — macOS / Linux
+
+Shell: bash or zsh. Use these recipes only on `darwin` / `linux` platforms.
+
+Do not copy these snippets into Windows PowerShell. Windows has a separate reference: `commands-windows-powershell.md`.
+
+## run-lint
+
+```bash
+SKILL_DIR=<directory of the Location: path returned by skill({ name: "skill-creator" })>
+node "$SKILL_DIR/scripts/lint-skill.js" <path/to/new-skill/>
+```
+
+Replace `<path/to/new-skill/>` with the absolute path of the skill you just authored.
+
+## eval-scratch-dir
+
+Pick a writable scratch directory for eval outputs.
+
+```bash
+EVAL_SCRATCH="${TMPDIR:-/tmp}"
+```
+
+Use `${EVAL_SCRATCH}` everywhere the procedure mentions a scratch path. Do not hardcode `/tmp/` because some sandboxes set `TMPDIR` to a different location.
+
+## baseline-output-paths
+
+Write the eval subagent outputs under the scratch dir:
+
+```bash
+SKILL_NAME=<new-skill-name>
+mkdir -p "${EVAL_SCRATCH}/eval-${SKILL_NAME}"
+
+WITH_SKILL_OUTPUT="${EVAL_SCRATCH}/eval-${SKILL_NAME}/with-skill.md"
+BASELINE_OUTPUT="${EVAL_SCRATCH}/eval-${SKILL_NAME}/baseline.md"
+```
+
+Pass `${WITH_SKILL_OUTPUT}` and `${BASELINE_OUTPUT}` to the subagent prompts.

package/server/assets/skills/skill-creator/references/commands-windows-powershell.md

@@ -0,0 +1,48 @@
+# skill-creator Commands — Windows PowerShell
+
+Shell: Windows PowerShell 5.1+ or PowerShell 7+. Use these recipes only on `win32`.
+
+Do not use bash syntax in PowerShell: no `mkdir -p`, no `cat <<EOF`, no `/tmp`, no `.sh` scripts, and do not assume `python3` exists. Prefer PowerShell cmdlets and `Join-Path`.
+
+**Encoding**: Always pass `-Encoding UTF8` when using `Get-Content` or `Set-Content`. Windows
+PowerShell 5.1 defaults to the system ANSI code page (e.g. GBK on Chinese Windows), which
+silently corrupts UTF-8 content. Prefer Read/Write/Edit tools for file content operations.
+
+## run-lint
+
+```powershell
+$SkillDir = "<directory of the Location: path returned by skill({ name: 'skill-creator' })>"
+node (Join-Path $SkillDir "scripts/lint-skill.js") "<path\to\new-skill\>"
+```
+
+Replace `<path\to\new-skill\>` with the absolute path of the skill you just authored.
+
+## eval-scratch-dir
+
+Pick a writable scratch directory for eval outputs. Do NOT use `/tmp` — Windows does not have it.
+
+```powershell
+$EvalScratch = $env:TEMP
+```
+
+Use `$EvalScratch` everywhere the procedure mentions a scratch path.
+
+## baseline-output-paths
+
+Write the eval subagent outputs under the scratch dir:
+
+```powershell
+$SkillName = "<new-skill-name>"
+$EvalDir = Join-Path $EvalScratch "eval-$SkillName"
+New-Item -ItemType Directory -Force -Path $EvalDir | Out-Null
+
+$WithSkillOutput = Join-Path $EvalDir "with-skill.md"
+$BaselineOutput  = Join-Path $EvalDir "baseline.md"
+```
+
+Pass `$WithSkillOutput` and `$BaselineOutput` to the subagent prompts.
+
+## Safety notes
+
+- Do not add cleanup snippets with `Remove-Item`; the eval scratch dir does not need to be cleaned up immediately. If cleanup is truly required, prefer the project's recoverable trash flow over `Remove-Item`.
+- Use `py` or `python` for Python scripts on Windows; `python3` is not standard.

package/server/assets/skills/skill-creator/references/description-rubric.md

@@ -0,0 +1,83 @@
+# Description Rubric — 写好 description 的 4 要素
+
+> `description` 是 LLM 决定打不打开 skill 的唯一依据。写不好 → 该用没用（漏触发），或不该用却用了（误触发）。本文档列 4 要素 + 用 Mavis 现有 skill 做正反例。
+
+## 4 要素
+
+每条 description 必须能让另一个 LLM 同时回答这 4 个问题：
+
+1. **What**：这个 skill 能做什么（一句话，能力边界）
+2. **When**：用户会怎么说才该触发（含具体短语/关键词）
+3. **Near misses**：什么相邻请求**不该**触发它
+4. **适度 pushy**：扩大召回的同时给出明确边界，避免"模糊不愿用"
+
+## 例 1：skill-creator vs skill-refiner 的边界
+
+这两个 skill 都处理 Skill，但交付阶段不同：一个创建新 Skill，一个改进既有 Skill。
+
+**skill-creator**：
+> Use when the user wants to create a new reusable Skill from requirements, examples, or an existing workflow. Do not use it merely to review or tune an existing Skill.
+
+**skill-refiner**：
+> Use when the user wants to review, debug, evaluate, or improve an existing Skill. Do not use it to scaffold a brand-new Skill from scratch.
+
+**为什么这两条都写得好**：
+- 两条都明确声明交付阶段：new 与 existing
+- 两条都写出相邻请求的排除条件
+- 输入对象和目标状态不同，不会同时触发
+
+## 例 2：docx vs pptx 的近义区分
+
+两个 skill 都处理 Office 文档，但文件类型和交付物不同：
+
+**docx**：
+> Create, inspect, edit, repair, and verify Microsoft Word DOCX documents. Use this skill for formal Word deliverables, tracked document structure, WordprocessingML-level edits, rendering DOCX pages for visual QA, extracting text/styles/tables/images/comments, or preserving DOCX layout and section/header/footer behavior.
+
+**pptx**：
+> Read, inspect, generate, and edit PowerPoint PPTX presentations. Use this skill for extracting slide text, speaker notes, comments, embedded images, screenshots, metadata audits, creating new decks with PptxGenJS, imitating a reference deck's visual style, or editing an existing PPTX while preserving layout.
+
+**写得好的点**：
+- 两条都先声明文件类型（DOCX / PPTX），模型能用扩展名和交付物快速路由
+- `docx` 把 Word 特有的 section/header/footer、WordprocessingML、page render QA 写进边界
+- `pptx` 把 slide、speaker notes、screenshots、PptxGenJS、reference deck imitation 写进边界
+- 两条 description 不再用"Office 文件"这种泛化说法，避免任何 Office 请求都触发同一个 skill
+
+## 反例：什么是写得不好的 description
+
+**反例 A**（太抽象，触发不稳定）：
+```
+description: A useful skill for working with files.
+```
+问题：什么文件？什么操作？模型不知道什么时候该用。
+
+**反例 B**（只堆关键词，没有 when 和边界）：
+```
+description: PDF, text, extract, OCR, parse, document, file
+```
+问题：可能任何提到 PDF 的请求都触发，包括其实该用 `docx` 或其他相邻 skill 的。
+
+**反例 C**（把"什么时候不该用"漏掉）：
+```
+description: Use this skill to handle PDF files.
+```
+问题：用户说"生成 PDF 报告"也会触发它。
+
+## 自检清单
+
+写完 description 后用这 4 个问题自查：
+
+- [ ] 一句话说出做什么了吗？
+- [ ] 给了 ≥ 2 个具体触发短语吗（含中英文如果用户混用）？
+- [ ] 显式列了"不该触发"的相邻情况吗？
+- [ ] 适度 pushy（用 "load this skill when" / "trigger on" 等明确语气），但没夸大能力？
+
+## "适度 pushy" 的尺度
+
+**太弱**：`Can be useful for X` → LLM 看了不知道是不是该用
+**正确**：`Use this skill when X. Triggers on phrases like Y / Z` → 明确召回意图
+**过度**：`MUST always use this skill for any X-related task` → 把模型限死，反而过拟合
+
+参考 mavis 现有 skill 的 description（如 `lark-tools`）的写法：
+> Use this skill **whenever** the user mentions anything related to Feishu or Lark, including but not limited to: ...
+
+`whenever` + `including but not limited to` 是适度 pushy 的范例：扩大召回 + 留扩展空间。

package/server/assets/skills/skill-creator/references/skill-template.md

@@ -0,0 +1,101 @@
+# Skill Template — Mavis 自己的 SKILL.md 骨架
+
+> 这是一个用于参考的填空模板，不是一份"应当死板套用"的格式。先理解每个章节存在的理由，然后再决定本次 skill 是否需要它。
+
+## Frontmatter
+
+```yaml
+---
+name: <kebab-case-name>     # 必填，与目录同名
+description: |              # 必填，触发面，是 LLM 决定要不要打开 skill 的依据
+  一句话能力 + 具体触发场景 + 不该触发的相邻情况
+---
+```
+
+`description` 见 `description-rubric.md`。
+
+## 正文章节（推荐顺序）
+
+原则：`description` 负责触发；正文负责执行。不要把同一批触发条件在 body 里再写一遍。
+
+```markdown
+# <Skill Name>
+
+## Inputs to collect
+- 调用 skill 之前 LLM 要先问用户/读上下文确认的信息
+- 没有这一节，模型会用错误假设硬上
+
+## Procedure
+- 步骤动作（祈使句）
+- 每个步骤说"这样做的原因"，不是只给命令
+- 步骤里禁止写 ALWAYS / NEVER；写"为什么这么做"和"不这么做的后果"
+
+## Output contract
+- 这个 skill 应该输出什么形式
+- 文件、消息、还是结构化数据
+
+## Failure handling
+- 失败应该怎么办：放弃、降级、回报用户
+- 容易卡的地方提前打预防针
+
+## Examples
+- 真实例子（input → output），不是虚构的 placeholder
+- 1-2 个就够，不要写 5 个
+```
+
+可选章节：`Inputs to collect`。如果 skill 输入非常直接，可以省略。
+
+可选章节：`## Windows (win32) platform notes`。如果 skill 包含 shell 命令、脚本调用或 `python3` 引用，加一个 Windows 适配段落，提供 PowerShell 等价命令或跨平台替代方案。纯流程 skill（无 shell 命令）可跳过。
+
+不推荐章节：`When to use this skill`。触发条件应放进 frontmatter `description`，避免重复占用 context。
+
+## 模板示例：填空版
+
+下面是一个虚构的 `db-migrator` skill 用本模板填出来的样子：
+
+```markdown
+---
+name: db-migrator
+description: |
+  Generate and apply Postgres schema migrations. Use when the user asks to
+  "add a column", "migrate the database", "alter a table" or describes a
+  schema change. Do NOT use for one-off SQL queries (use direct psql instead).
+---
+
+# DB Migrator
+
+## Inputs to collect
+- 目标表名（用户没说就问）
+- 变更类型与具体字段
+- 是否需要在生产环境跑（影响是否要 wrap in transaction）
+
+## Procedure
+1. 读 `migrations/` 目录确认下一个序号
+   原因：避免序号冲突
+2. 用模板生成 up/down SQL
+   原因：down migration 是回滚保险
+3. 在本地 docker postgres 上 dry run
+   原因：catch 语法错误，不污染真实数据库
+
+## Output contract
+- 一个文件 `migrations/NNNN_<description>.sql`
+- 包含 `-- up` 和 `-- down` 两段
+
+## Failure handling
+- dry run 失败 → 报错给用户，不要尝试自动修复 SQL
+- 序号冲突 → 跳号，不要覆盖
+
+## Examples
+Input: "给 users 表加一个 last_login_at timestamp"
+Output: 创建 `migrations/0042_add_users_last_login_at.sql`
+```
+
+## 写作约束清单
+
+- 正文 ≤ 500 行；超出就拆 `references/<topic>.md` 然后用 `详见 references/...` 引用
+- 正文优先写执行动作、输出约束、失败处理；不要写 README 式背景介绍、功能导览、模块化 API 教程
+- 触发条件和 near misses 放 frontmatter `description`，不要在正文重复列一遍
+- 示例保留 1-2 个 canonical case；其余让模型通过脚本 `--help`、引用文件或代码自查
+- 假设读者是另一个模型，不假设它已知项目背景
+- 如果某段是写给人类看的（教学/历史背景），明确标注，避免污染模型 context
+- 章节顺序可以调，但前几节必须快速回答：要补什么输入、怎么执行、失败怎么办

package/server/assets/skills/skill-creator/references/when-to-bundle-scripts.md

@@ -0,0 +1,139 @@
+# When to Bundle Scripts — 何时建脚本 vs 用其他机制
+
+> 一个常见错误是"看到能写脚本就写脚本"。Mavis 已经有多种机制处理不同类型的工作；先判断**这件事本质上是什么**，再决定用什么。
+
+## 决策树
+
+```
+有一个动作要在 skill 里反复执行 →
+│
+├─ 这是确定性的本地计算（无需 LLM 判断）？
+│   ├─ 是 → 写 Node.js 脚本（放 scripts/）
+│   └─ 否 → 继续往下
+│
+├─ Mavis 原生 tool 已经支持了？
+│   ├─ 是 → 直接调用对应 tool（`mavis` / `skill` 等），不写脚本
+│   └─ 否 → 继续往下
+│
+├─ 涉及多 agent 协作 / 评审 / 对比？
+│   ├─ 是 → 用后台 Task 子代理（subagent），在 SKILL.md procedure 里描述分工
+│   └─ 否 → 继续往下
+│
+├─ 涉及跨 session 状态传递？
+│   ├─ 是 → 用 scratchpad（不写文件）
+│   └─ 否 → 继续往下
+│
+└─ 是判断性 / 创造性工作？
+    └─ 让 LLM 在 SKILL.md 的 procedure 里直接做，不用脚本
+```
+
+## 各类工作对应的机制
+
+### 用脚本（scripts/*.js）
+
+适合：**纯本地确定性计算 / 校验 / 格式化**
+
+例：
+- `lint-skill.js` — 校验 SKILL.md 格式、frontmatter
+- 文件解析、统计、转换
+
+**判断标准**：跑同样输入永远得同样输出，不需要 LLM 介入。
+
+**约束**：用 Node.js + 内置 fs，禁止依赖第三方 npm 包。
+
+### 用 Mavis 原生 tool
+
+适合：**Mavis 已封装的能力**
+
+例：
+- 列已有 skill → 看 context 里的 `<available_skills>` 块
+- 看 session 状态 → `mavis({ command: "session list" })`
+- 管理定时任务 → `mavis({ command: "cron list" })`
+
+**判断标准**：动作是否已经是 Mavis 的标准 API。是的话直接调用，不要包脚本。
+
+### 用后台 Task 子代理
+
+适合：**多 agent 协作 / 对比评审 / 需要 verify 闭环**（task 工具 + `run_in_background: true`；前台 task 调用是顺序阻塞的，后台才能真正并行）
+
+例：
+- skill 评测：producer / baseline 两个后台子代理并行跑 + 主 session 自己写 compare
+- 多角度审查：3 个 reviewer 并发独立审一个文档
+
+**判断标准**：动作是否需要"派活给多个 worker + 等结果 + 汇总"。是的话在 SKILL.md procedure 里用后台 Task 子代理表达，不要在脚本里手动编排。
+
+### 用 scratchpad
+
+适合：**跨 session 信息传递**
+
+例：
+- skill iterate 过程中 cycle N 的反馈传给 cycle N+1
+- 多个 worker 共享中间状态
+
+**判断标准**：信息是否需要被多个 session 看到。是的话写 scratchpad 文件，不要塞进 agent memory（agent memory 是经验沉淀，不是临时进度）。
+
+### 让 LLM 直接做
+
+适合：**判断性 / 创造性 / 需要理解上下文的工作**
+
+例：
+- 给 skill 起名字
+- 写 description
+- 决定该 reuse 还是 create
+- 评判两个 skill 输出哪个更好
+
+**判断标准**：换个输入就要换种处理方式 → 让 LLM 在 SKILL.md procedure 里直接做。
+
+## 反例：错误地建了脚本
+
+### 反例 A：写脚本扫已有 skill
+
+```js
+// scan-existing-skills.js — 不必要
+const skills = fs.readdirSync('{{DATA_DIR}}/skills/');
+const matches = skills.filter(s => s.includes(query));
+```
+
+**问题**：context 里的 `<available_skills>` 块已经列出全部 skill，直接看即可，不需要脚本。
+
+### 反例 B：写脚本跑 eval
+
+```js
+// run-eval.js — 不必要
+runWorker(`load ${skillPath} and handle: ${prompt}`);
+runWorker(prompt);  // baseline
+compareOutputs();
+```
+
+**问题**：这是典型的 producer/baseline/compare 工作流，应该用后台 Task 子代理。脚本里手动 spawn worker 等于在重写 subagent 编排。
+
+### 反例 C：写脚本汇总迭代反馈
+
+```js
+// summarize-iteration.js — 不必要
+const feedback = JSON.parse(fs.readFileSync('feedback.json'));
+const summary = aggregateByCategory(feedback);
+fs.writeFileSync('summary.md', summary);
+```
+
+**问题**：这是判断性工作（什么是"重要反馈"，什么是"噪声"），应该让 LLM 在 SKILL.md procedure 里读 eval 反馈 + scratchpad 直接处理。
+
+## 上游的"看 transcript 找重复造轮子"提示
+
+上游 skill-creator 提到一个有用的判断方法：**跑完几轮 eval 后，看 worker transcript，如果发现多个 worker 独立写了同一个辅助函数，那才说明这个动作该 bundle 成脚本**。
+
+换句话说：
+- 脚本不是预先决定要写的，是从迭代中**发现**该写的
+- 第一版 skill 不要急着写脚本，先用 LLM 直接做，看哪些动作真的高频且确定性
+- 高频 + 确定性的部分才下沉到脚本
+
+## 总结：奥卡姆剃刀清单
+
+写脚本前问：
+- [ ] Mavis 原生 tool 已经支持了吗？
+- [ ] 涉及多 agent 吗（→ 后台 Task 子代理）？
+- [ ] 涉及跨 session 吗（→ scratchpad）？
+- [ ] LLM 自己做就行吗（→ procedure 里直接写）？
+- [ ] 真的是确定性本地计算吗？
+
+5 个问题都答完，最后一个还是 "是"，才写脚本。