@playcraft/cli 0.0.39 → 0.0.41

package/README.md

@@ -40,7 +40,15 @@ playcraft <command>
 
 ## 🚀 快速开始
 
-### 1. 初始化配置
+### 1. 登录账号
+
+```bash
+npx @playcraft/cli login
+```
+
+交互式登录，PAT（个人访问令牌）自动保存到 `~/.playcraft/config.json`。登录后所有需要后端 API 的命令（`tools`、`recommend`、`fix-ids` 等）均可直接使用，无需额外配置。
+
+### 2. 初始化配置
 
 ```bash
 npx @playcraft/cli init
@@ -48,7 +56,7 @@ npx @playcraft/cli init
 
 交互式创建 `playcraft.config.json` 配置文件。
 
-### 2. 启动本地开发服务
+### 3. 启动本地开发服务
 
 ```bash
 # 前台运行
@@ -60,7 +68,7 @@ npx @playcraft/cli start --project <project-id> --daemon
 
 启动后，云端编辑器会自动检测本地服务，直接读取本地文件进行运行与调试。
 
-### 3. 打包 Playable Ads
+### 4. 打包 Playable Ads
 
 ```bash
 # 交互式打包（推荐）
@@ -70,12 +78,50 @@ npx @playcraft/cli build
 npx @playcraft/cli build --platform facebook --format html --output ./dist
 ```
 
+## 🔐 鉴权说明
+
+PlayCraft CLI 支持三种鉴权方式，按优先级依次生效：
+
+| 优先级 | 方式 | 适用场景 |
+|--------|------|---------|
+| 1 | **`playcraft login`**（推荐） | 交互式登录后自动保存 PAT 到 `~/.playcraft/config.json`，所有命令开箱即用 |
+| 2 | **`.playcraft.json`** | 项目目录下的配置文件，适合 CI/沙箱环境（支持沙箱 JWT） |
+| 3 | **环境变量** | `PLAYCRAFT_TOKEN`（PAT）或 `PLAYCRAFT_SANDBOX_TOKEN`（沙箱 JWT） |
+
+### 快速登录
+
+```bash
+# 交互式登录（推荐）
+playcraft login
+
+# 指定私有部署地址登录
+playcraft login --url https://your-playcraft.example.com
+```
+
+登录成功后，`tools`、`recommend`、`fix-ids` 等所有需要后端 API 的命令均无需额外配置，直接使用。
+
+### 沙箱环境（CI / Agent）
+
+在沙箱或 CI 中可通过 `.playcraft.json` 或环境变量配置：
+
+```bash
+# 方式 1：环境变量
+export PLAYCRAFT_SANDBOX_TOKEN=<sandbox-jwt>   # 沙箱 JWT
+export PLAYCRAFT_API_URL=https://playcraft.aix.intlgame.com
+
+# 方式 2：.playcraft.json
+echo '{"token":"<sandbox-jwt>","apiUrl":"https://..."}' > .playcraft.json
+```
+
+---
+
 ## 📖 命令说明
 
 ### 开发相关
 
 | 命令 | 说明 | 示例 |
 |------|------|------|
+| `login` | 登录账号，保存 PAT 到全局配置 | `playcraft login` |
 | `init` | 交互式创建配置文件 | `playcraft init` |
 | `start` | 启动本地开发服务 | `playcraft start --project <id>` |
 | `stop` | 停止运行中的服务 | `playcraft stop --project <id>` |
@@ -84,6 +130,23 @@ npx @playcraft/cli build --platform facebook --format html --output ./dist
 | `config` | 读取/修改配置项 | `playcraft config get --key projectId` |
 | `inspect` | 检测项目类型与结构 | `playcraft inspect .` |
 
+### 平台 API（需登录或配置鉴权）
+
+> 运行 `playcraft login` 后所有子命令均可直接使用。
+
+| 命令 | 说明 | 示例 |
+|------|------|------|
+| `tools generate-image` | AI 生成图片 | `playcraft tools generate-image --prompt "pixel art sky"` |
+| `tools generate-sfx` | AI 生成音效 | `playcraft tools generate-sfx --prompt "UI click"` |
+| `tools generate-bgm` | AI 生成 BGM | `playcraft tools generate-bgm --prompt "casual game music"` |
+| `tools list-image-models` | 列出可用生图模型 | `playcraft tools list-image-models` |
+| `tools list-remixes` | 查看 Remix 项目列表 | `playcraft tools list-remixes` |
+| `tools save-to-git` | 同步沙箱内容到 Git | `playcraft tools save-to-git --project-id <id> --message "feat: ..."` |
+| `tools build-project` | 在沙箱中执行构建 | `playcraft tools build-project --project-id <id>` |
+| `recommend similar` | 相似 Creative 推荐 | `playcraft recommend similar --channel Applovin` |
+| `recommend improvements` | Tag 改进建议 | `playcraft recommend improvements --channel Facebook` |
+| `recommend random` | 随机 Tag 组合推荐 | `playcraft recommend random --channel Google` |
+
 ### 构建相关
 
 | 命令 | 说明 | 示例 |

package/dist/atom-plan/validate-atom-plan.js

@@ -0,0 +1,298 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadConfig } from '../config.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SKILL_REF_EMPTY = new Set(['', '—', '-', '–', 'null', 'none', 'n/a']);
+const PROTECTED_SKILL_PREFIX = 'playcraft-';
+const SKILL_REF_SUFFIX_RE = /\.(aigameplay|aiconfig)$/;
+function normalizeSkillRef(ref) {
+    if (ref === null || ref === undefined)
+        return null;
+    const s = String(ref).trim();
+    if (SKILL_REF_EMPTY.has(s) || s.startsWith('{{'))
+        return null;
+    return s;
+}
+/** 与 skills match 命令相同的 skills 目录发现逻辑（精简版） */
+export function resolveSkillsDirs(customDir, configDir) {
+    if (customDir)
+        return [path.resolve(customDir)];
+    const dirs = [];
+    if (configDir)
+        dirs.push(path.resolve(configDir));
+    const envPaths = process.env.AGENT_SKILLS_PATHS?.split(',').map((p) => p.trim()).filter(Boolean) ?? [];
+    dirs.push(...envPaths);
+    const cwdModulesPath = path.join(process.cwd(), 'node_modules', '@playcraft', 'skills', 'skills');
+    if (fs.existsSync(cwdModulesPath))
+        dirs.push(cwdModulesPath);
+    const monoSkillsPath = path.resolve(__dirname, '..', '..', '..', '..', 'skills', 'skills');
+    if (fs.existsSync(monoSkillsPath))
+        dirs.push(monoSkillsPath);
+    return [...new Set(dirs)];
+}
+/** 从项目根解析 skills 目录（与 playcraft skills 命令同源） */
+export async function resolveProjectSkillsDirs(projectDir, skillsDirOverride) {
+    const root = path.resolve(projectDir);
+    const config = await loadConfig({ dir: root }).catch(() => ({ skillsDir: undefined }));
+    return resolveSkillsDirs(skillsDirOverride, config.skillsDir);
+}
+export function loadSkillAtomIdSet(skillsDirs) {
+    const ids = new Set();
+    for (const dir of skillsDirs) {
+        if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory())
+            continue;
+        for (const name of fs.readdirSync(dir, { withFileTypes: true })) {
+            if (!name.isDirectory())
+                continue;
+            const manifestPath = path.join(dir, name.name, 'manifest.json');
+            if (!fs.existsSync(manifestPath))
+                continue;
+            try {
+                const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+                if (manifest.atomId)
+                    ids.add(manifest.atomId);
+            }
+            catch {
+                // skip invalid manifest
+            }
+        }
+    }
+    return ids;
+}
+function snapshotItemAtomIds(plan) {
+    const ids = new Set();
+    for (const item of plan.skillsMatch?.items ?? []) {
+        if (item.atomId)
+            ids.add(item.atomId);
+    }
+    return ids;
+}
+export function parseAtomPlanJson(content) {
+    const parsed = JSON.parse(content);
+    if (!parsed || typeof parsed !== 'object') {
+        throw new Error('atom-plan JSON 必须是对象');
+    }
+    if (!Array.isArray(parsed.atoms)) {
+        throw new Error('atom-plan JSON 缺少 atoms 数组');
+    }
+    return parsed;
+}
+/** 从 atom-plan.md Atom List 表解析 skillRef（兼容旧项目） */
+export function parseSkillRefsFromAtomPlanMarkdown(content) {
+    const lines = content.split('\n');
+    let inAtomList = false;
+    let skillRefIdx = -1;
+    const refs = new Set();
+    for (const line of lines) {
+        if (/^##\s+Atom List\b/i.test(line)) {
+            inAtomList = true;
+            skillRefIdx = -1;
+            continue;
+        }
+        if (inAtomList && /^##\s+/.test(line))
+            break;
+        if (!inAtomList || !line.trim().startsWith('|'))
+            continue;
+        const cols = line
+            .split('|')
+            .slice(1, -1)
+            .map((c) => c.trim());
+        if (cols.length === 0)
+            continue;
+        if (skillRefIdx < 0) {
+            if (cols.includes('skillRef'))
+                skillRefIdx = cols.indexOf('skillRef');
+            continue;
+        }
+        if (cols.every((c) => /^:?-+:?$/.test(c) || c === ''))
+            continue;
+        if (cols.includes('atomId') && cols.includes('assignTo'))
+            continue;
+        const ref = normalizeSkillRef(cols[skillRefIdx]);
+        if (ref)
+            refs.add(ref);
+    }
+    return [...refs];
+}
+function extractSnapshotAtomIdsFromMarkdown(content) {
+    const ids = new Set();
+    const jsonBlock = content.match(/```json\s*([\s\S]*?)```/);
+    if (!jsonBlock)
+        return ids;
+    try {
+        const snap = JSON.parse(jsonBlock[1]);
+        for (const item of snap?.items ?? []) {
+            if (item.atomId)
+                ids.add(item.atomId);
+        }
+    }
+    catch {
+        // ignore parse errors — validated separately
+    }
+    return ids;
+}
+export function validateSkillRefs(options) {
+    const errors = [];
+    const warnings = [];
+    const { skillRefs, skillIndex, snapshotItemIds, atomBySkillRef } = options;
+    for (const ref of skillRefs) {
+        if (!SKILL_REF_SUFFIX_RE.test(ref)) {
+            errors.push(`skillRef 格式非法（须为 *.aigameplay 或 *.aiconfig）：${ref}`);
+            continue;
+        }
+        if (ref.startsWith(PROTECTED_SKILL_PREFIX)) {
+            errors.push(`skillRef 不得使用平台 skill（playcraft-*）：${ref}`);
+            continue;
+        }
+        if (!skillIndex.has(ref)) {
+            errors.push(`skillRef 不在 skills 库中：${ref}（运行 playcraft skills list --json 核对）`);
+            continue;
+        }
+        if (snapshotItemIds && snapshotItemIds.size > 0 && !snapshotItemIds.has(ref)) {
+            const owner = atomBySkillRef?.get(ref);
+            const who = owner ? `（production atomId: ${owner.atomId}）` : '';
+            errors.push(`skillRef 未出现在 skillsMatch.items 中：${ref}${who}`);
+        }
+    }
+    if (skillRefs.length === 0) {
+        warnings.push('未找到任何非空 skillRef');
+    }
+    return { errors, warnings };
+}
+/** 从项目 docs/ 读取 atom-plan（JSON 优先，否则 Markdown）中的 skillRef */
+export function parseSkillRefsFromAtomPlanProject(projectDir) {
+    const root = path.resolve(projectDir);
+    const jsonPath = path.join(root, 'docs', 'atom-plan.json');
+    if (fs.existsSync(jsonPath)) {
+        const plan = parseAtomPlanJson(fs.readFileSync(jsonPath, 'utf-8'));
+        const refs = [];
+        for (const atom of plan.atoms) {
+            const ref = normalizeSkillRef(atom.skillRef);
+            if (ref)
+                refs.push(ref);
+        }
+        return refs;
+    }
+    const mdPath = path.join(root, 'docs', 'atom-plan.md');
+    if (fs.existsSync(mdPath)) {
+        return parseSkillRefsFromAtomPlanMarkdown(fs.readFileSync(mdPath, 'utf-8'));
+    }
+    return [];
+}
+export async function validateAtomPlanProject(options) {
+    const projectDir = path.resolve(options.projectDir);
+    const jsonPath = path.join(projectDir, 'docs', 'atom-plan.json');
+    const mdPath = path.join(projectDir, 'docs', 'atom-plan.md');
+    const dirs = await resolveProjectSkillsDirs(projectDir, options.skillsDir);
+    const skillIndex = loadSkillAtomIdSet(dirs);
+    if (dirs.length === 0) {
+        return {
+            ok: false,
+            errors: ['未找到 skills 目录。请安装 @playcraft/skills 或设置 AGENT_SKILLS_PATHS / playcraft.config.json skillsDir'],
+            warnings: [],
+            skillRefsChecked: [],
+            source: 'json',
+        };
+    }
+    if (fs.existsSync(jsonPath)) {
+        let plan;
+        try {
+            plan = parseAtomPlanJson(fs.readFileSync(jsonPath, 'utf-8'));
+        }
+        catch (e) {
+            return {
+                ok: false,
+                errors: [`docs/atom-plan.json 解析失败：${e.message}`],
+                warnings: [],
+                skillRefsChecked: [],
+                source: 'json',
+            };
+        }
+        if (plan.schemaVersion !== 1) {
+            return {
+                ok: false,
+                errors: [`docs/atom-plan.json schemaVersion 须为 1，当前：${plan.schemaVersion}`],
+                warnings: [],
+                skillRefsChecked: [],
+                source: 'json',
+            };
+        }
+        const skillRefs = [];
+        const atomBySkillRef = new Map();
+        for (const atom of plan.atoms) {
+            const ref = normalizeSkillRef(atom.skillRef);
+            if (!ref)
+                continue;
+            skillRefs.push(ref);
+            atomBySkillRef.set(ref, atom);
+            if (atom.type !== 'GameplayAtom' && atom.type !== 'ConfigAtom' && ref) {
+                return {
+                    ok: false,
+                    errors: [`${atom.atomId}：仅 GameplayAtom/ConfigAtom 允许 skillRef，当前 type=${atom.type}`],
+                    warnings: [],
+                    skillRefsChecked: skillRefs,
+                    source: 'json',
+                };
+            }
+        }
+        const snapshotIds = snapshotItemAtomIds(plan);
+        const { errors, warnings } = validateSkillRefs({
+            skillRefs,
+            skillIndex,
+            snapshotItemIds: snapshotIds,
+            atomBySkillRef,
+        });
+        if (!plan.skillsMatch?.items?.length) {
+            warnings.push('skillsMatch.items 为空 — Gate #1 应先运行 playcraft skills match --json 并写入 skillsMatch');
+        }
+        const configuredRoot = dirs[0];
+        if (plan.packageSkillsRoot?.trim()) {
+            const declared = path.resolve(projectDir, plan.packageSkillsRoot.trim());
+            if (configuredRoot && path.resolve(configuredRoot) !== declared) {
+                warnings.push(`packageSkillsRoot 与 playcraft.config.json 解析结果不一致；请删除 atom-plan 中的 packageSkillsRoot，或改为 skillsDir：${configuredRoot}`);
+            }
+        }
+        return {
+            ok: errors.length === 0,
+            errors,
+            warnings,
+            skillRefsChecked: skillRefs,
+            source: 'json',
+        };
+    }
+    if (options.preferJson !== false) {
+        return {
+            ok: false,
+            errors: ['缺少 docs/atom-plan.json（Gate #1 请使用 templates/atom-plan.template.json）'],
+            warnings: fs.existsSync(mdPath) ? ['检测到 docs/atom-plan.md，请迁移为 JSON 主格式'] : [],
+            skillRefsChecked: [],
+            source: 'json',
+        };
+    }
+    if (!fs.existsSync(mdPath)) {
+        return {
+            ok: false,
+            errors: ['缺少 docs/atom-plan.json 与 docs/atom-plan.md'],
+            warnings: [],
+            skillRefsChecked: [],
+            source: 'markdown',
+        };
+    }
+    const md = fs.readFileSync(mdPath, 'utf-8');
+    const skillRefs = parseSkillRefsFromAtomPlanMarkdown(md);
+    const snapshotIds = extractSnapshotAtomIdsFromMarkdown(md);
+    const { errors, warnings } = validateSkillRefs({
+        skillRefs,
+        skillIndex,
+        snapshotItemIds: snapshotIds,
+    });
+    warnings.push('使用 Markdown atom-plan（已弃用为主格式，请改用 docs/atom-plan.json）');
+    return {
+        ok: errors.length === 0,
+        errors,
+        warnings,
+        skillRefsChecked: skillRefs,
+        source: 'markdown',
+    };
+}

package/dist/cli-root-help.js

@@ -3,7 +3,7 @@ export function getCliTopicsHelpText() {
     return [
         '命令分区（完整说明见仓库 docs/cli/capabilities.md）：',
         '',
-        '  本地开发   init, start, stop, status, logs, config, sync, fix-ids',
+        '  本地开发   create, init, start, stop, status, logs, config, sync, fix-ids',
         '  素材       tools generate-*  |  image <子命令>  |  audio <子命令>  |  prefab <子命令>',
         '  平台       build, build-base, build-playable, build-all, analyze, inspect, upgrade',
         '             tools 除 generate-* 外（Git / 沙箱构建 / 发布 / 列表 / Prefab 等，需后端 API）',