npm - @playcraft/cli - Versions diffs - 0.0.44 → 0.0.46 - Mend

@playcraft/cli 0.0.44 → 0.0.46

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (984) hide show

package/project-template/.claude/skills/playcraft-workflow/SKILL.md DELETED Viewed

@@ -1,485 +0,0 @@
----
-name: playcraft-workflow
-description: PlayCraft 可玩广告开发工作流与 Skill 体系入口。在开始构建任何游戏项目、选择组件、查找 Skill、生成图片/音频、创建 Remix 时自动触发。解释双层 Skill 体系并引导正确工作流。
-triggers: 构建游戏,开始开发,创建项目,选择组件,选择 skill,查找 skill,生成图片,生成音频,工作流,workflow
----
-# PlayCraft 工作流与 Skill 体系
-## 执行模式（首先判断）
-在开始任何工作前，先判断当前执行环境：
-### Multi-Agent Mode（默认，优先使用）
-如果当前环境支持 sub-agent 调用（Claude Code 的 `@agent` 语法可用）：
-1. **你是 orchestrator**，不要自己执行任何 Agent 的工作
-2. 按 `CLAUDE.md` 中 Orchestration Protocol 的阶段转换表 spawn sub-agents
-3. 每个 sub-agent 完成后，读取 `docs/project-state.md` 的 **`## Agent handoff`** YAML + Gates 表，再决定下一步
-4. **Orchestrator 会话**优先遵循 `.cursor/rules/playcraft-orchestrator.mdc`；子 Agent 会话不加载 orchestrator rule
-5. **仅 orchestrator** 对用户 `AskUserQuestion` — 子 Agent **禁止**问用户（见 `docs/team/agent-conduct.md`）
-   - `gate_pending` 非 null 且 `waiting_for: user_gate` 时：**只跑 Gate**，不得 invoke 子 Agent
-   - `subagent_stop: true` 时：只执行 `next_orchestrator_action`
-   - Gate #1 / #2a / #2b：`AskUserQuestion`（子 Agent 更新 handoff 后 STOP）
-   - **Gate #1 / #2b 前**：先 invoke `@reviewer design_check`（软性 checklist）
-   - Gate #3：Reviewer `load_check` 通过后展示 **devUrl**（用户只点链；玩法由用户判断）
-   - Gate / handoff 细则：`docs/team/collaboration.md` § Gate Protocol、§ Agent Handoff
-6. `devStatus: ui_ready` → `@reviewer ui_diff`；`ui_rework` → 按 report 修复 → 再 `@reviewer ui_diff`
-7. `devStatus: ready` → `@reviewer load_check` → Gate #3
-8. `devStatus: blocked_upstream` → 按 `devBlockers.routeTo` 调度 TA/Designer → 再 `@developer`
-9. 当前交付终点 = 用户在 Dev URL 验收通过（`done`），**不要求** `playcraft build`
-### ⚠️ Orchestrator 调度原则：传 WHAT 不传 HOW
-**Orchestrator 不是全知全能的指挥官。** 不要在调度时给子 Agent 写详细步骤——子 Agent 有完整的 `.claude/agents/<role>.md` + `refs/` + 相关 Skills。
-**正确的调度方式：**
-```
-@technical-artist
-目标：完成 atom-plan.json 中所有 assignTo: TA 的 atoms。
-注意：atom-plan.json → skillsMatch.mediaGroups 有 3 个预制图片资产可复用，优先 link。
-```
-**错误的调度方式（越俎代庖）：**
-```
-@technical-artist
-1. 先生成 tile_01.png，用绿幕...
-2. 然后 remove-background --tolerance 25...
-3. 接着 resize 到 128x128...
-```
-**原则：**
-- Orchestrator 只传递 **目标 + 约束 + 关键提醒**（如 mediaGroups 可用）
-- 子 Agent 自己读 `refs/` + Skills 找到正确方法论
-- Orchestrator 在 sub-agent STOP 后 **验证结果**（atom status 是否更新、Context 是否填写）
-### Orchestrator STOP 后验证清单
-Sub-agent STOP 返回后，Orchestrator 必须验证：
-```bash
-# 检查 atom status 是否全部更新
-cat docs/atom-plan.json | jq '[.atoms[] | select(.assignTo == "<agent>") | select(.status == "pending")] | length'
-# 应该 = 0（所有该 agent 的 atom 都已 done / skipped）
-# 检查 Context 是否填写
-grep -c "Pending" docs/atom-plan.md
-# 对应 agent 的 Context 区不应包含 "Pending"
-# 检查 actualOutput 文件是否存在
-cat docs/atom-plan.json | jq '.atoms[] | select(.assignTo == "<agent>" and .status == "done") | .actualOutput' | xargs -I {} test -f {}
-```
-如果验证失败 → 不转入下一阶段，而是要求该 agent 补全。
-### Single-Agent Mode（降级模式，当 sub-agent 不可用时）
-串行执行所有阶段，但**必须**：
-- 每进入一个新阶段时，先完整读取对应 `.claude/agents/<role>.md` 的所有指令
-- 不可跳过任何阶段的必选产出（特别是 TA 的完整素材生产——UI 图、VFX、精灵图都必须生产）
-- 必须执行 Spec Quick-Check：TA 在 production Wave 2 启动后 30s 内；Developer 在 `ui_pass` 启动后 30s 内
-- PM 定稿后运行 `playcraft skills link --from-atom-plan`；Developer 优先读 `.claude/skills/<atomId>/SKILL.md`，仅断链时用 `playcraft skills read`
----
-## 双层 Skill 体系
-PlayCraft 使用 **两套互补的 Skill 系统**：
-| 层                     | 位置                                            | 用途                                             | 发现方式                                                                                                                       |
-| ---------------------- | ----------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
-| **Claude Code Skills** | `.claude/skills/`                               | 平台工具使用指南（图片生成、音频、代码编辑器等） | IDE 自动发现和注入                                                                                                             |
-| **DAG Atom Skills**    | `playcraft skills match` 返回的 `skillDir` 路径 | 游戏积木（玩法规则、组件、图片、音效、配置）     | `playcraft skills match` CLI 推荐；PM 定稿后 `playcraft skills link --from-atom-plan` 软链到 `.claude/skills/` 供 IDE 自动发现 |
-**关键规则**：构建任何新游戏项目前，**必须先运行 `playcraft skills match`** 获取完整的推荐积木清单，再动手写代码。
----
-## 标准工作流（必须遵守）
-```
-① 运行本地 Skill 推荐（必须）
-   playcraft skills match --intent "<关键词,逗号分隔>" --json
-   # 自动推断引擎；若已定：加 --engine <threejs|phaser>
-② 评估本地 Skill 覆盖度
-   - 完整覆盖 → 进入步骤 ③
-   - 部分覆盖 → 进入步骤 ③，同时触发 ②-ext
-   - 完全没有 → 触发 ②-ext
-② -ext（本地不足时）网络研究补充
-   - 参阅 playcraft-research SKILL，按角色执行定向研究
-   - 研究结论写入 `docs/atom-plan.md` 的对应 Context 区域
-   - 标记候选新 Skill（在 DAG Revisions 中记录）
-③ 读取每个代码 Skill 的 SKILL.md（PM 已 link 后优先项目内路径）：
-   cat .claude/skills/<atomId>/SKILL.md
-   # 软链缺失时兜底：playcraft skills read <atomId>
-   - 理解 Recipe；列出将使用的 ref/ 文件
-   - 将关键信息记入 `docs/atom-plan.md` 对应的 Context 区域
-④ PM 定稿 `atom-plan.json` 后，软连接 DAG Skill 到项目（IDE 自动发现，强烈推荐）：
-   playcraft skills link --from-atom-plan --prune
-⑤ 执行 scaffold 命令，复制 ref 文件到项目（注：package.json/tsconfig.json 使用 merge-json 模式，不覆盖已有配置）
-   playcraft skills scaffold --engine <引擎> --atoms <skill1,skill2> --out ./game
-⑥ 按各媒体 Skill 的参数（或网络研究得出的参数）生成图片/音频资产
-   playcraft tools generate-image --prompt "..." --output ta-workspace/xxx.png
-   playcraft tools generate-sfx --prompt "..." --duration 1.5
-   playcraft tools generate-bgm --prompt "..."
-⑦ 在已有 ref 文件基础上（或基于研究方案）编写项目代码
-```
-**禁止**：
-- ❌ 未运行 `skills match` 就开始写引擎/布局/输入/渲染代码
-- ❌ 未读 SKILL.md（项目软链或 CLI 兜底）就跳过 Skill 内容直接从头实现
-- ❌ 对已有 ref 文件重新实现相同功能
-- ❌ 手动猜测 Skill 名称
-- ❌ 本地无 Skill 就直接凭感觉写——先做网络研究，把依据记录在活 DAG 里
----
-## Agent 自增强协议（Skill-on-Demand）
-> **核心原则**：Skill 是持续可用的资源，不是一次性查询。每个 Agent 在其专属阶段都应独立做角色相关的 Skill 发现。
-### 为什么需要多次 Skill 查询
-- 每个 Agent 是独立 session，不继承前一个 Agent 的 Skill 搜索结果
-- 每个角色需要的 Skill 类型完全不同
-- 在实现某个具体功能时才知道需要什么，无法在规划阶段完全预见
-### 按角色的 Skill 发现模式
-**PM（规划阶段）**
-```bash
-# 确认玩法类型的已有实现和依赖关系
-playcraft skills match --engine <engine> --intent "<gameplay_type>,<game_mechanic>" --json
-# 浏览所有可用配置封包
-playcraft skills list --category config --json
-```
-**Designer（创意样本生产阶段）**
-```bash
-# 找视觉资产参考和生成参数（aiimage Skill 包含 manifest.json 里的 generation 字段）
-playcraft skills list --category visual --json
-# 找音频资产参考
-playcraft skills list --category audio --json
-# 按具体元素类型搜索
-playcraft skills match --intent "<element_type>,<art_style>" --json
-```
-**Technical Artist（技术生产阶段）**
-```bash
-# 找精灵图/图集生产 Skill
-playcraft skills list --category visual --json
-playcraft skills match --intent "<element_type>,sprite,atlas,sheet" --json
-# 找 3D 渲染/翻转精灵图 Skill
-playcraft skills match --intent "3d,sprite,flip,render" --json
-# 找图片处理 Skill
-playcraft skills match --intent "image,processing,pipeline" --json
-# 找验证器（用于合规检查）
-playcraft skills list --category validator --json
-```
-**Developer（代码实现阶段）**
-```bash
-# 每实现一个 Atom 前，先搜索是否有现成的代码积木
-playcraft skills match --engine <engine> --intent "<feature_name>,<component_type>" --json
-# 找引擎适配层
-playcraft skills list --category engine --json
-# 找布局/UI 组件
-playcraft skills list --category layout --json
-```
-**Reviewer（质量验证阶段）**
-```bash
-# 找可用的校验器 Skill
-playcraft skills list --category validator --json
-# 按具体校验目标搜索
-playcraft skills match --intent "validator,balance,compliance,ux" --json
-```
-### "写代码前先查 Skill" 规则
-在实现任何非平凡组件之前，**必须先执行此检查**：
-```
-1. 我即将实现：<描述功能>
-2. 运行：playcraft skills match --engine <e> --intent "<功能关键词>" --json
-3a. 找到完整匹配 Skill → 读取其 SKILL.md → scaffold → 基于 ref 文件实现
-3b. 找到部分匹配 → 使用 Skill 作为基础，参阅 playcraft-research 补充网络研究
-3c. 完全未找到 Skill → 参阅 playcraft-research 执行定向网络研究 → 研究结论写入
-     `atom-plan.md` § Impl Skill Context → 在 `dagRevisions` / DAG Revisions 标注候选新 Skill → 实现
-```
-> 本地 Skill 库不可能穷尽所有场景。遇到陌生玩法、新艺术风格、特定算法时，**网络研究是标准流程，不是例外**。关键是把研究结论沉淀进活 DAG，让整个团队受益。
-**典型触发场景**：
-- 要写一个新的 UI 组件 → `skills match --intent "ui,component,<具体名称>"`
-- 要实现某种玩法规则 → `skills match --intent "<gameplay>,rules,algorithm"`
-- 要做图片后处理/精灵图 → 读取 `playcraft-image-generation` SKILL.md（涵盖后处理管线与脚本模板）
-- 要做音频生成/处理 → 读取 `playcraft-audio-generation` SKILL.md
-- 要读取某个 Skill 的完整说明 → `playcraft skills read <atomId>`
-### Skill 依赖链发现
-Atom Skill 之间通过 `imports` 字段形成依赖链。发现一个 Skill 可能引出更多：
-```bash
-# 读取某 Skill 的完整 SKILL.md（含 imports / Recipe / 操作流程）
-playcraft skills read <atomId>
-# match 输出的 JSON 中每个 item 包含 skillDir 字段，可直接访问 ref/ 目录
-# 例如读取 memory_match 的 PGS 规则骨架：
-playcraft skills match --engine phaser --intent "memory,match" --json \
-  | python3 -c "import json,sys; items=json.load(sys.stdin)['items']; [print(i['atomId'], i['skillDir']) for i in items]"
-# 查看 skill 的 ref/ 目录文件（先用 read 获取 skillDir）
-playcraft skills read <atomId>  # 找到 skillDir 路径
-# 然后直接读取 ref/ 文件：
-cat <skillDir>/ref/<file>
-# 按依赖 Skill 名称递归读取
-playcraft skills match --intent "<imported_skill_keywords>" --json
-```
----
-## 活 DAG 分层富集模式（保持一致性）
-> **问题**：多个 Agent 各自做 DAG/Skill 搜索，结果会不会冲突？谁的优先？
->
-> **答案**：不冲突。**活 DAG** 在 `docs/atom-plan.json`（`atoms[]` + `skillsMatch`）；各 Agent 在 `docs/atom-plan.md` 向专属 Context 区富集，形成统一知识库。
-### 活 DAG 的分层结构
-```
-docs/atom-plan.json
-├── skillsMatch                    ← PM：`playcraft skills match --json`（skillRef 唯一来源）
-├── atoms[]                        ← PM：排期 DAG；Gameplay/Config 的 skillRef 仅来自 skillsMatch.items
-└── dagRevisions[]                 ← 结构变更 / skills-match-gap（可与 md 同步）
-docs/atom-plan.md
-├── Atom List（可选镜像表）        ← 与 atoms[] 同步；可省略
-├── ## Acceptance Criteria         ← PM：每 atom 一条可测验收
-├── ## Asset Skill Context         ← Designer
-├── ## TA Skill Context            ← TA
-├── ## Impl Skill Context          ← Developer
-└── ## DAG Revisions               ← 人类可读修订记录
-```
-Skills 路径真源：`playcraft.config.json` → `agent.skillsDir`（**不要**在 atom-plan 写死 node_modules）。格式详解：[`docs/team/atom-plan-format.md`](../../docs/team/atom-plan-format.md)
-### 各 Agent 的读写职责
-| Agent                | 读取                                                     | 写入                                                                            |
-| -------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------- |
-| **PM**               | design-brief, layout-spec                                | `atom-plan.json`（skillsMatch + atoms[]）                                       |
-| **Designer**         | `atoms[]` + `mediaGroups` + design-brief                 | `atom-plan.md` § Asset Skill Context；`atoms[].status` + `atoms[].actualOutput` |
-| **Technical Artist** | `atoms[]` + `mediaGroups` + Asset Context + designer-log | `atom-plan.md` § TA Skill Context；`atoms[].status` + `atoms[].actualOutput`    |
-| **Developer**        | `atoms[]` + Context 区 + design-brief                    | `atom-plan.md` § Impl Skill Context；`atoms[].status` + `atoms[].actualOutput`  |
-| **Reviewer**         | JSON + MD（只读）                                        | 不写                                                                            |
-### ⚠️ Status Update 纪律（所有 Agent 必须遵守）
-每个 Agent 完成 atom 后 **立即** 更新 `atom-plan.json`：
-```json
-{
-  "atomId": "<id>",
-  "status": "done",
-  "actualOutput": "<deliverable_path>"
-}
-```
-- **Designer**: `actualOutput` = 文件路径 或 `"ASR:<sheet>:<region>"` (when covered by ASR)
-- **TA**: `actualOutput` = `"assets/images/<path>.webp"` (final WebP contract path)
-- **Developer**: `actualOutput` = `"game/<path>.ts"` (implementation file)
-**atom-plan 不是 PM 的一次性输出文档，而是贯穿全流程的活依赖追踪系统。**
-### mediaGroups 使用纪律（Designer + TA 必须遵守）
-`skillsMatch.mediaGroups` 包含 PM 通过 `playcraft skills match` 找到的可复用预制资产。
-**流程**：
-```
-Designer/TA 读 mediaGroups
-  ├─ 匹配当前 atom？
-  │   ├─ 是 → `playcraft skills link --atom <atomId>` → 后处理 → status=done
-  │   └─ 否 / 质量不够 → 记录跳过原因到 dagRevisions → 正常生产流程
-  └─ mediaGroups 为空？→ 正常生产流程
-```
-**禁止**：忽略 mediaGroups 中存在匹配的预制资产而从零生成（浪费 token + 引入不一致风险）。
-### 为什么这样设计能避免冲突
-**示例**：游戏风格为"像素风"
-```
-PM:
-  → 搜索 aigameplay skills，得到 arrow_pick_match_rules
-  → 在 atoms[] 填：arrow_rules | skillRef = arrow_pick_match_rules.aigameplay
-  → 不知道像素风需要什么具体的图片参数，留 VisualAtom skillRef 为空（—）
-Designer:
-  → 读到 StyleDirection = "像素风 8-bit 高饱和"
-  → 搜索 aiimage skills，得到 pixel_art_sprite.aiimage
-  → 读 pixel_art_sprite 的 manifest.json：了解 prompt 模板、block 尺寸参数
-  → 在 Asset Skill Context 写：bg_atom → pixel_art_sprite → 关键参数...
-  → 现在知道"像素风"具体怎么生产了
-Developer:
-  → 读 PM 的 skillRef = arrow_pick_match_rules.aigameplay
-  → 读 Designer 的 Asset Skill Context（了解视觉风格，确保代码绑定正确）
-  → 搜索额外的 aicomponent skills
-  → 在 Impl Skill Context 写：arrow_rules_impl → 实现细节...
-Reviewer:
-  → 读 Atom List + Asset Skill Context + Impl Skill Context
-  → 有了完整 Skill 依据，搜索 aivalidator skills 进行验证
-```
-**无冲突的根本原因**：每个 Agent 的写入区域不重叠。DAG 是合作共建的，不是争夺的。
----
-## Scaffold 所有权模型（防冲突）
-> **核心规则**：`playcraft skills match/list` 是只读操作，任何 Agent 随时可用，零冲突。
-> **唯一风险**：`playcraft skills scaffold`（写文件），必须遵守所有权规则。
-### 每个 Agent 的 Scaffold 域
-| Agent                | 可 Scaffold 的 Skill 类型                                      | 写入目录  | 禁止 Scaffold                                             |
-| -------------------- | -------------------------------------------------------------- | --------- | --------------------------------------------------------- |
-| **Developer**        | `aicomponent`, `aigameplay`, `aiconfig`                        | `game/`   | `aiimage`, `aiaudio`, `aivalidator`                       |
-| **Technical Artist** | ❌ 不 Scaffold（读 manifest.json generation 参数，直接调 CLI） | `assets/` | **全部**（TA 通过 CLI 管线生产，不 Scaffold）             |
-| **Designer**         | ❌ 不 Scaffold                                                 | `assets/` | **全部**（只读 manifest.json 的 generation 参数用于生成） |
-| **Reviewer**         | ❌ 不 Scaffold                                                 | 只读      | **全部**（read-only 角色）                                |
-| **PM**               | ❌ 不 Scaffold                                                 | `docs/`   | **全部**（只做规划 + 协调）                               |
-### 为什么 Designer 和 TA 不需要 Scaffold
-`aiimage` / `aiaudio` Skill 没有 `ref/` 代码文件，只有 `manifest.json` 中的 `generation` 字段（prompt、aspectRatio、duration 等）。Designer 和 TA 读取这些参数作为生成基准，通过 `playcraft image *`、`playcraft tools generate-image` 等 CLI 命令执行，不复制任何文件到项目。
-**Reviewer（convergence-v1）**
-- **`design_check`**：Gate #1 / #2b 前 — 文档完整性 checklist（无需浏览器）
-- **`ui_diff`**：读取 **`playwright-cli`** skill — 截图 vs MC 各面板
-- **`load_check`**：读取 **`playwright-cli`** skill — 页面加载 + console 无 Error
-### Production 串行编排（convergence-v1）
-Gate #2b 通过后 **严格串行**（见 `workflow-changelog.md`）：
-```
-Wave 1 Designer Ph.2 → Wave 2 TA → ui_pass Developer → ui_review (Reviewer ui_diff) → gameplay_pass Developer → load_check → Gate #3
-```
-Developer 在 **`ui_pass`** 写入 UI shell（无核心玩法）；**`gameplay_pass`** 叠加玩法逻辑。TA 已交付合同路径上的真实资产。
-### 避免重复 Scaffold 的规则
-同一个 Skill 不应被多次 Scaffold 到同一目录：
-- PM 在 `atom-plan.json` → `atoms[]` 标注 `skillRef`（若有）+ 调度元信息（assignTo/dependsOn/priority/parallelGroup/referenceSource）
-- Developer 在 **`ui_pass`** 开始时，按 `atoms[]` 中 `assignTo: Developer` 批量 scaffold 一次
-- **不要在实现单个 Atom 时反复 scaffold** — 先统一 scaffold 所有依赖，再逐一实现
----
-## 如何阅读 Atom Skill 的 SKILL.md
-每个 Atom Skill 的 `SKILL.md` 包含：
-1. **YAML frontmatter**：`name`（格式为 `<name>.<bundleType>`）、`description`、`triggers`
-2. **功能说明**：Skill 做什么、输出什么
-3. **Scaffold / Imports**：依赖哪些其他 Skill
-4. **Skill Definition 区块**（部分 Skill 有）：
-   ```yaml
-   ## Skill Definition
-   tools:
-     - bash
-     - read
-   prompt_extension: |
-     这里是注入给 agent 的操作指令
-   ```
-   `prompt_extension` 的内容是 agent 执行此 Skill 时需要遵循的具体指令。
----
-## Skill 推荐示例
-```bash
-# Three.js 3D 棋盘消除游戏
-playcraft skills match --engine threejs --intent "board,3d,path,animation"
-# Phaser 三消游戏
-playcraft skills match --engine phaser --intent "match3,grid,tile,score"
-# 跑酷游戏
-playcraft skills match --engine phaser --intent "parkour,left_right,run,obstacle"
-# 查看所有可用 Skill
-playcraft skills list --json
-```
----
-## 平台工具快速参考
-### Claude Code Skills（`.claude/skills/` 目录，自动注入）
-> ⚠️ 下表只列出**项目模板中实际存在**的 Skill。不要查找或引用表外的 Skill 名称。
-| Skill                          | 职责                                                                                                                   | 主要角色      |
-| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | ------------- |
-| `playcraft-workflow`（本文件） | 工作流入口、Skill 体系、DAG 协作规范                                                                                   | 全员          |
-| `playcraft-image-generation`   | AI 图片生成全指南：模型选择、gpt-image-2 双 provider、精灵图直出、绿幕策略、edit 变体、错误恢复、ta-workspace 脚本模板 | Designer / TA |
-| `playcraft-audio-generation`   | AI 音频生成全指南：SFX/BGM 生成参数、prompt 套路、本地音频后处理（compress/fade/loop）                                 | Designer      |
-| `playcraft-research`           | 网络研究协议：`tools research/fetch-url/search-image` 三工具标准流程、研究结果融入活 DAG                               | 全员          |
-### CLI 命令组（`playcraft <group>`，无需 Skill 文件）
-| 命令组                                              | 能力摘要                                                                                                                                                         | 主要角色             | 完整文档                                                     |
-| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | ------------------------------------------------------------ |
-| `playcraft tools generate-image`                    | AI 文生图/图生图；`--reference-image`、`--image-model`（裸模型名时后端按优先级 fallback）、`--count N`（同 prompt 批量出图）、`--timeout`                        | Designer / TA        | `docs/cli/tools.md §1.2`                                     |
-| `playcraft tools generate-sfx/bgm`                  | AI 音效/背景音乐生成                                                                                                                                             | Designer             | `docs/cli/tools.md §1.2`                                     |
-| `playcraft tools generate-3d` 系列                  | AI 3D 模型生成、贴图、重拓扑、UV 展开、动作                                                                                                                      | TA                   | `docs/cli/tools.md §1.3`                                     |
-| `playcraft tools research/fetch-url`                | AI 网络研究与 URL 读取                                                                                                                                           | 全员                 | `docs/cli/tools.md §1.7`                                     |
-| `playcraft tools save-to-git/build-project/publish` | 项目保存、构建、发布                                                                                                                                             | Developer            | `docs/cli/tools.md §1.4`                                     |
-| `playcraft image`                                   | 本地图片处理 + 后端抠图/分层：resize/crop/decompose-layers/segment/remove-background/sprite-split/sprite-sheet/batch/pipeline/animate/tint/overlay/gen-tile-back | TA                   | `docs/cli/tools.md §2`；分层与蒙版选型见 `playcraft-masking` |
-| `playcraft audio`                                   | 本地音频处理：compress/trim/fade/loop/normalize/mix                                                                                                              | Designer / TA        | `docs/cli/tools.md §3`                                       |
-| `playcraft 3d`                                      | 本地 3D 处理：白模库/apply-texture/optimize/convert                                                                                                              | TA                   | `docs/cli/tools.md §4`                                       |
-| `npm run dev`                                       | 项目 Dev 预览（`package.json` → `scripts.dev`）                                                                                                                  | Developer / Reviewer | 用户不执行；Gate #3 由 orchestrator 递 devUrl                |
-| `playcraft build / build-all`                       | 打包 Playable Ads（**未来**交付路径，非当前 `done` 条件）                                                                                                        | —                    | —                                                            |
-| `playcraft skills match/list/link/scaffold/read`    | DAG Atom Skill 推荐、IDE 软链、脚手架、内容读取（`link` 供 PM；`read` 供 Developer Preflight）                                                                   | 全员                 | —                                                            |
----
-## Skill 目录发现优先级
-`playcraft skills` 命令按以下优先级发现 Skill 目录：
-1. `--skills-dir <path>` 参数
-2. `playcraft.config.json` 中的 `skillsDir` 字段
-3. `AGENT_SKILLS_PATHS` 环境变量
-4. `<项目根>/node_modules/@playcraft/skills/skills`（npm 安装后）

package/project-template/docs/team/atom-plan-format.md DELETED Viewed

@@ -1,173 +0,0 @@
-# Atom Plan 格式（JSON 主 + Markdown 辅）
-> Gate #1 起，**机器可读主文件**为 `docs/atom-plan.json`；`docs/atom-plan.md` 仅承载各角色富集的 Context 与 DAG Revisions。
-## Skills 包路径（不在 atom-plan 里写死）
-**真源**：项目根 `playcraft.config.json` → `agent.skillsDir`（`playcraft create` 时可配置）。
-```json
-{
-  "agent": {
-    "dir": ".",
-    "skillsDir": "/path/to/your/skills/skills"
-  }
-}
-```
-`playcraft skills match` / `link` / `read` / `validate-atom-plan` 均按该配置（及 `AGENT_SKILLS_PATHS`、默认 `node_modules` 等）解析，**无需**在 `atom-plan.json` 重复填写 `packageSkillsRoot`。若误填了与 config 不一致的路径，校验会给出 warning。
-## 文件分工
-| 文件                    | 谁写                    | 内容                                                                                                                 |
-| ----------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------- |
-| `docs/atom-plan.json`   | **PM**（Gate #1）       | `skillsMatch`（`playcraft skills match --json` 原文）、`atoms[]`（排期 DAG + `skillRef`）                            |
-| `docs/atom-plan.md`     | PM 骨架 + 各 Agent 富集 | Gate #1：**仅** `## Acceptance Criteria` + 空 Context 占位 + `## DAG Revisions`；**不要** Atom List / DAG Order 镜像 |
-| `playcraft.config.json` | 项目初始化              | `agent.skillsDir` — skills 库磁盘路径                                                                                |
-## PM Gate #1 流程
-```bash
-# 确认 playcraft.config.json 已配置 agent.skillsDir（或依赖 node_modules/@playcraft/skills）
-playcraft skills match --intent "<gameplayType>,<mechanic>,<keywords>" --json \
-  > /tmp/skills-match.json
-# 包一层写入 docs/atom-plan.json（见下方 jq 示例）
-playcraft skills validate-atom-plan
-playcraft skills link --from-atom-plan --prune
-```
-PM **STOP** 时 hook `validate-atom-plan.mjs` 会再次校验：所有非空 `skillRef` ∈ skills 库，且在 `skillsMatch.items` 中。
-### 最小 atom-plan.json 骨架（无需 cp template）
-```bash
-jq -n \
-  --argfile sm /tmp/skills-match.json \
-  '{
-    schemaVersion: 1,
-    skillsMatch: $sm,
-    atoms: [],
-    dagRevisions: []
-  }' > docs/atom-plan.json
-```
-再编辑 `atoms[]`；`atom-plan.md` 仍可从 `templates/atom-plan.template.md` 复制（Context 区）。
-## skillRef 规则
-- 仅 **GameplayAtom** / **ConfigAtom** 可有 `skillRef`
-- 必须为 `*.aigameplay` 或 `*.aiconfig`
-- 禁止 `playcraft-*`（平台管线 skill 在 `.claude/skills/playcraft-*`）
-- 禁止编造未出现在 `skillsMatch.items` 的 atomId（除非 `dagRevisions` 记录 `skills-match-gap`）
-## 下游如何读
-| 角色                     | 读 JSON                  | 读 MD                    | Skills 路径                                      |
-| ------------------------ | ------------------------ | ------------------------ | ------------------------------------------------ |
-| Orchestrator / Developer | `atoms[]`、`skillsMatch` | `## Impl Skill Context`  | `playcraft.config.json` + `.claude/skills/` 软链 |
-| TA                       | `atoms[]`、`mediaGroups` | `## TA Skill Context`    | 同上                                             |
-| Designer                 | `atoms[]`、`mediaGroups` | `## Asset Skill Context` | 同上                                             |
-| Reviewer                 | 两者只读                 | 两者只读                 | —                                                |
-Developer 软链：`.claude/skills/<skillRef>/`（`playcraft skills link --from-atom-plan`）。断链时用 `playcraft skills read <skillRef>`（自动读 config，勿手抄 node_modules 路径）。
-## Status Update Protocol（所有产出 Agent 必须遵守）
-**atom-plan.json 是活的追踪系统，不是一次性规划文档。** 每个 Agent 完成 atom 后立即更新：
-```json
-{
-  "atomId": "<id>",
-  "status": "done", // or "skipped" with reason in dagRevisions
-  "actualOutput": "<path>" // the actual deliverable path on disk
-}
-```
-| Agent     | 何时更新                        | `actualOutput` 格式                                   |
-| --------- | ------------------------------- | ----------------------------------------------------- |
-| Designer  | Phase 2 每完成一个 atom         | `"assets/audio/bgm.mp3"` 或 `"ASR:ui_sheet:region_3"` |
-| TA        | 每完成一个 atlas/asset          | `"assets/images/ui/ui_atlas.webp"`                    |
-| Developer | 每完成一个 gameplay/config atom | `"game/gameplay/reducer.ts"`                          |
-**Context 回填同样强制**：对应 agent 的 `atom-plan.md` § Context 区不得为空（`Pending`）。Orchestrator 在阶段转换前验证。
-## `asrSlot` 字段（可选 — VisualAtom 基线绑定）
-`atoms[].asrSlot` 是 **VisualAtom**（`assignTo: Designer`）专用的可选字段，把"Designer ASR Coverage Matrix 上的网格坐标"机器可读化，TA 据此自动算 crop 像素坐标，省掉人工对照表的步骤。
-### Schema
-```ts
-type AsrSlot = {
-  sheet: "ui" | "element" | "element_2"; // element_2 = overflow ASR board when types > 12
-  row: number;                    // 1-based 行号 (row-major)
-  col: number;                    // 1-based 列号
-};
-// 字段位置
-atoms[i].asrSlot?: AsrSlot | null
-```
-### 谁写
-| 谁           | 何时                                              | 写什么                                                                                                                     |
-| ------------ | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| **PM**       | Gate #1（可选）                                   | 已知会出现在 ASR 的 VisualAtom 预填一个建议 slot（Designer 可改）；不确定时留空                                            |
-| **Designer** | Phase 1 完成 ASR 后（必填，所有 ASR-覆盖的 atom） | 与 `designer-log.md § ASR Coverage Matrix § Coverage` 一致；同时 `status: done` + `actualOutput: ASR:<sheet>:R{row}C{col}` |
-| **TA**       | 只读                                              | 用 `asrSlot.sheet/row/col` + `designer-log` § Sheet grid metadata → 算 `playcraft image crop` 像素                         |
-### TA crop 自动化（参考公式）
-`designer-log.md § ASR Coverage Matrix § Sheet grid metadata` 给出每张 sheet 的 `cellW × cellH × padding`。
-```
-sheetPath = sheet === "ui"
-  ? "assets/images/reference/ui_state_sheet_<selectedMcOption>.png"
-  : sheet === "element_2"
-    ? "assets/images/reference/element_state_sheet_<selectedMcOption>_2.png"
-    : "assets/images/reference/element_state_sheet_<selectedMcOption>.png"
-x = (col - 1) * (cellW + padding) + padding
-y = (row - 1) * (cellH + padding) + padding
-width  = cellW
-height = cellH
-playcraft image crop <sheetPath> --x <x> --y <y> --width <width> --height <height> --output <assetMapping_path>
-```
-### 与 `actualOutput` 的关系
-`asrSlot` 是**绑定信息**（这个 atom 对应 ASR 哪个格子），`actualOutput` 是**完成证明**（已交付到哪里）。
-两者并存而非互斥：
-```json
-{
-  "atomId": "vatom_tile_default",
-  "type": "VisualAtom",
-  "assignTo": "Designer",
-  "asrSlot": { "sheet": "element", "row": 1, "col": 2 },
-  "status": "done",
-  "actualOutput": "ASR:element_state_sheet_B:R1C2"
-}
-```
-TA 之后用 `asrSlot` 提取出 PNG 到 `assets/images/tiles/tile_default.webp`；这一步发生时 TA atom（不同的 atomId）有自己的 `actualOutput`，**不修改** Designer atom 的 `actualOutput`。
-### 禁止
-- 跨 ASR-mediaGroups 混用：`asrSlot` 只描述"本项目 Designer 产出的 ASR"，**不**复用 `skillsMatch.mediaGroups`（那是技能库预制资产，不在项目 ASR 上）。
-- ICP 补丁 PNG 的 VisualAtom 不设 `asrSlot`（已脱离 ASR 网格）。`actualOutput` 直接给文件路径。
-- TA atom 不写 `asrSlot`（这是 Designer-owned 字段，TA 通过 `dependsOn` 引用 Designer atom）。
-## mediaGroups 使用规则
-`skillsMatch.mediaGroups` 包含 `playcraft skills match` 自动发现的可复用预制资产（图片/音频/3D）。
-**协议**：
-1. **Designer / TA 必须读** `mediaGroups` 并对每个 entry 判断是否匹配当前 atom
-2. **匹配 → 直接 link**：`playcraft skills link --atom <atomId>` → 后处理（resize/convert/mix）→ `status: done`
-3. **不匹配 → 跳过并记录**：在 `dagRevisions` 记录 skip 原因
-4. **禁止**：mediaGroups 中有匹配项却无视、从零生成