Paean 游戏技能集 paean-ai/8x-skills

8x 技能

可移植的智能体技能，用来在 Paean Apps Square（.clide.app / 8x.gg）上构建、发布和混搭游戏 —— 支持 Zero CLI、Claude Code、Codex、Gemini CLI、Cursor、Antigravity 和 DeepSeek Harness（或任何能读取 SKILL.md 并运行 Node 脚本的智能体）。

面向小红书创作者，专门的 Red Skill 版 把中文创作入口与现有的转换、录制、SDK、发布和混搭工作流打包成一个可安装包。默认产出一个离线小工具，需要时再追加 8x 平台版本。用 node scripts/build-redskill.mjs 构建；把生成的技能 ZIP 上传到 Red Skill，把生成的作品* ZIP 上传到小工具。

| 技能 | 作用 |
| paean-skills-update | 更新本仓库，并为 Zero CLI、Claude Code、Codex、Gemini CLI、Cursor、Antigravity 或 DeepSeek Harness 重新安装 Paean 技能。 |
| paean-cloud-computer | 给你的 Personal Agent 配一台创意云电脑：管理个人环境、委派持久云任务、取回私有结果，并打开 Harness 供人观察。附可移植命令行与远程 MCP 指南。 |
| paean-zero-setup | 安装 Zero CLI 并登录 Paean，让发布/混搭脚本能从 Zero 或 Paean token 文件读取本地凭据。 |
| paean-game-create | 创建或大幅升级一款达到商业水准、移动优先的 Paean 网页游戏。定义美术、玩法、吸引模式预览、响应式 UI、纯 JS 架构、精简资源和 Playwright 发布验证的制作标准。 |
| paean-tts | 用创作者的登录，通过 Paean TTS 生成游戏对白、语音教程、发音示例和演示视频旁白。包含本地命令行、可续传的 WAV 输出，以及可选的保调变速。 |
| paean-sdk | 设计并集成云存档、排行榜、付费访问/IAP、激励广告/IAA、多人房间、AI（含运行时 TTS/朗读）、共享数据和分享。一个入口分流到各能力的设计指南；包含集成模块和离线 mock 宿主。 |
| paean-publish | 把静态前端（顶层 index.html）部署到 .clide.app，可以只做托管（--hosting-only，不在 Apps Square 上架），也可以作为公开 Square 条目上架。支持自定义 handle、密钥扫描，以及 Worker/D1/R2 兼容性检查。还指导打赏（含自打赏）、Express Boost，以及为已有 Square 作品做创作者内容 Boost。 |
| paean-convert-to-ad | 把成品作品转成 HTML5 试玩广告包（Google Ads MEDIA_BUNDLE）：找到直接进入核心玩法的接缝，调好展示流程，自动播放后交还控制权，退出到商店，并自检整个包完全离线。 |
| paean-convert-to-rednote | 把成品转成 RedNote（小红书）小工具：一个完全离线的 zip，基线为 Chrome 61。附带构建流水线、兼容性与产物审计，以及一套发布标准，涵盖自动演示和入口 UI 中的来源署名、可选虚拟景观与映射控件、14 字文案、游戏专属图标，以及从最终 ZIP 导出的 30 秒高清视频。需要 esbuild。 |
| paean-record-demo | 从成品录制 20–30 秒街机风格吸引演示片：通过游戏自身的接缝驱动其进入真实会话，在其上叠加可选标题卡、定时字幕和 CTA 尾卡，并导出 MP4/WebM/GIF 加一张封面帧。需要 Playwright；ffmpeg 可选。 |
| paean-sessions | 私下备份真实 JSONL 创作记录，并关联到当前拥有的应用发布；支持独立提交与恢复，不涉及平台共享或训练授权。 |
| paean-remix | 把一个或多个已发布游戏混编成新游戏。将主来源（完整素材）克隆到用户工作区，通过 8x.gg MCP 服务器读取次要来源，并搭建带多父级混编图的项目（例如 h1 玩法 + h2 美术 + h3 主题），确保每位上游创作者恰好署名一次。 |

设计能力时，说 paean iap、paean iaa、paean net、paean rank 或 paean ai，也可以组合使用（例如「用 paean rank 加一个可选的 paean iaa 复活」）。这些是自然语言意图，由 paean-sdk 路由，不是命令行命令，也不是单独安装的技能。Create 和 Remix 在生产简报阶段选择同一批指南。共享 SDK 契约集中在一处；详细设计与验收位于 paean-sdk/reference/design-.md，仅在相关时加载。

发布/混编技能以自包含 Node 脚本形式提供——无需 npm install，除 Node 运行时外没有外部依赖。归档在进程内打包和解包，因此脚本在 macOS、Linux 和 Windows 上行为一致。paean-game-create 技能附带游戏生产标准加静态/Playwright 校验器。paean-sdk 技能附带浏览器参考文件（无服务器、无构建），你复制到自己的应用里。paean-record-demo 需要 Playwright 进行捕获，并在 PATH 上有 ffmpeg 时使用它；paean-convert-to-rednote 需要 esbuild。paean-tts 需要 Node.js 20+ 和 Paean 登录；FFmpeg 仅在本地变速或视频混音时需要。

每件原创作品和混编作品都应同时适配竖屏和横屏，而不是要求玩家旋转设备。按可用屏幕重新编排游戏区和 UI，在方向变化时保留状态，并在发布前验证两种方向下的实际游玩。保持 UI 简洁紧凑，让游戏区保持清晰，文字可读，触控舒适小屏幕上的目标，以及能跨分辨率自适应的布局。默认用明亮、亲切的休闲配色和有触感的表面，除非主题或明确的视觉方向要求另一种风格。

8x-skills/
├── claude-code/ # canonical skill content
│ ├── paean-skills-update/
│ ├── paean-zero-setup/
│ ├── paean-cloud-computer/
│ ├── paean-game-create/
│ ├── paean-tts/
│ ├── paean-sdk/
│ ├── paean-publish/
│ ├── paean-sessions/
│ ├── paean-remix/
│ ├── paean-record-demo/
│ ├── paean-convert-to-ad/
│ └── paean-convert-to-rednote/
├── codex/ # same twelve skills + Codex guidance
├── zero/ # same twelve skills + Zero CLI guidance
├── gemini/ # same twelve skills + Gemini CLI guidance
└── cursor/ # same twelve skills + Cursor guidance

五个源变体都带同一套脚本和参考文件，只有 SKILL.md 的打包方式不同。每个技能目录都包含入口文件，以及随附的 scripts/、reference/ 或 references/ 资源。每个变体都带 name 和 description 的 YAML frontmatter，供发现机制使用。Gemini 和 Cursor 有原生的发现与调用说明；Antigravity 和 DeepSeek Harness 安装可移植的 claude-code/ 源。

claude-code/ 是权威版本：在这里编辑，然后运行 node scripts/sync-variants.mjs 重新生成 codex/、zero/、gemini/ 和 cursor/（--check 在它们出现偏差时失败）。
测试：node --test tests/.test.mjs。

Square 应用在顶层放三个资源：favicon.svg、800×400 的 banner.jpg 和 512×512 的 icon.jpg。付费应用（Steam 风格：免费看演示，买一次即可游玩）用 paean-publish --price <credits> 声明，并在应用里用 PaeanSDK.access.require() 做门禁；参见 paean-sdk 及其离线 mock 宿主 reference/paean-mock.js。

标准发布现在默认使用服务器分配的随机 handle、公开的 Square 列表，以及私有的 JSONL 创作会话备份与发布关联。把当前工作的真实记录准备为 .clide/creation-session.jsonl，或传入 --session-jsonl <path>；显式指定 --no-session、--hosting-only 和自定义 handle 会覆盖相关默认值。参见发布工作流。
记录缺失或 API 不可用时，报告为待处理，绝不当作已完成的证明。当前标签是 Creation session linked。同一数据源也供给独立的原创性认证和流量支持系统；它们的最终决定与本 API 的关联状态相互独立。

Requirements

- Node.js 18+（用于全局 fetch）；paean-tts 需要 20+。
- 一个 Paean JWT（Paean web 应用 / Zero CLI 使用的 token）。

发布、remix、TTS 的 API 辅助脚本只用 Node 标准库；macOS、Linux 和 Windows 支持。可选的采集、转换和音频处理依赖列在上面。
不再需要 zip / unzip 命令 —— 发布/混音归档由它们自带的 scripts/zip.mjs 在进程内构建和读取。

凭据

安装 Zero CLI 并登录 Paean（推荐）：

npm install -g @paean-ai/zero-cli
zero provider clear
zero login
zero auth status --json

发布/混音脚本读取 Zero 保存在 ~/.zero/credentials.json 里的 Paean 凭据。
如果无法用浏览器登录，可以通过环境变量或凭据文件设置 Paean JWT：

export PAEAN_AUTH_TOKEN="<your-paean-jwt>"
or: ~/.paean/credentials.json → {"token":"<your-paean-jwt>"}

在 Windows（PowerShell）上，$env:PAEAN_AUTH_TOKEN = "<your-paean-jwt>" 只为当前会话设置它；上面凭据路径里的 ~ 指用户配置档目录（$env:USERPROFILE）。

如果存在 ~/.zero/credentials.json，脚本也会读取它。绝不要把 token 粘贴到聊天里 —— 把它留在环境变量或凭据文件中。可选：PAEAN_API_BASE 覆盖 API 端点（默认 https://api.paean.ai）。ZERO_API_BASE / ZERO_CLI_BASE_URL 只有在指向 .paean.ai 主机时才生效 —— 尤其是 ZERO_CLI_BASE_URL 经常被设成 LLM 网关（一个 Anthropic 兼容的服务商 URL），它不是 Paean API 地址，会被忽略。

TTS 辅助脚本依次接受 PAEAN_AUTH_TOKEN、旧版 PAEAN_TOKEN、~/.paean/credentials.json（paean_token / token）或 ~/.zero/credentials.json（token）。
显式指定的凭据文件优先。显式环境 token 为空或已过期时会直接失败，而不是悄悄切换身份。TTS 使用固定的官方 API 源；上面的 API 基址覆盖只对发布/混音生效，不影响语音辅助脚本。

安装和更新本地技能

从检出目录运行自带安装器（Node.js 18+，无依赖、无需网络）：

node scripts/install-skills.mjs --target claude-code,codex,zero,gemini,cursor,antigravity,deepseek-harness --dry-run
node scripts/install-skills.mjs --target claude-code,codex,zero,gemini,cursor,antigravity,deepseek-harness
node scripts/install-skills.mjs --target claude-code,codex,zero,gemini,cursor,antigravity,deepseek-harness --check

只选你想安装的客户端。同样的命令在 PowerShell 里也能用。每个技能都直接安装为 <skills-root>/paean-/SKILL.md，脚本和参考文件放在它旁边。安装器会更新仓库里所有技能，包括 TTS 和录音器。它把有改动的现有文件备份到目标父目录下的 .8x-skills-backups/，保留无关技能和额外的本地元数据，并拒绝技能目标内的符号链接。恢复自定义修改前先查看备份；--check 比较的是仓库拥有的文件，不含额外的本地文件。
--check 和 --dry-run 都不写入任何内容；需要更新时 --check 以 1 退出。
安装过程不会登录，不会复制账号凭据，也不会改动模型或代理设置。

客户端目录

Gemini 和 Cursor 的路径核对于 2026-10-15，其他客户端核对于 2026-10-05。
~ 指 macOS、Linux 或 Windows 上的用户主目录。用 --dest 指定单个目标，可覆盖默认路径，也可装进某个项目。如果第一个副本已经被发现，就不要再往别名根目录里装第二份。

| 安装器目标 | 全局目标路径 | 项目目标路径 / 说明 |
| claude-code | ~/.claude/skills/ | .claude/skills/ |
| codex | ~/.agents/skills/ | .agents/skills/；已在用 $CODEX_HOME/skills/ / ~/.codex/skills/ 的客户端，可用 --dest 原地更新 |
| zero | ~/.zero/skills/ | .zero/skills/ |
| gemini | ~/.gemini/skills/ | .gemini/skills/；也支持 .agents/skills/，同一作用域内后者优先 |
| cursor | ~/.cursor/skills/ | .cursor/skills/；也会发现 .agents/skills/ 以及兼容的 Claude/Codex 根目录；先检查已有副本 |
| antigravity | ~/.gemini/config/skills/ | .agents/skills/；桌面版 2.0 与独立 IDE；IDE 还支持旧路径 ~/.gemini/antigravity/skills/ |
| antigravity-cli | ~/.gemini/antigravity-cli/skills/ | .agents/skills/；用命令行时单独选这一项 |
| deepseek-harness | $DSH_HOME/skills/，否则 ~/.dsh/skills/ | .dsh/skills/；也支持 .agents/skills/、$DSH_AGENTS_HOME/skills/（默认 ~/.agents/skills/）以及配置的自定义根目录 |

来源：Codex local skills、 Gemini CLI skills、 Cursor skills、 Antigravity skills by surface、 DeepSeek Harness filesystem provider。
Harness 只发现直接的技能目录，不会去找仓库里任意层级的嵌套副本。
Harness 的分支可能选用不同的主目录；先查看它配置的主目录，再用 --dest。

Update an existing Codex installation without adding a duplicate in ~/.agents/skills
node scripts/install-skills.mjs --target codex --dest "$HOME/.codex/skills"
Install only in a Gemini project
node scripts/install-skills.mjs --target gemini --dest /path/to/project/.gemini/skills
Install only in a Cursor project
node scripts/install-skills.mjs --target cursor --dest /path/to/project/.cursor/skills
Explicit custom Harness home (no global environment change)
node scripts/install-skills.mjs --target deepseek-harness --dest /path/to/harness-home/skills

Gemini：用 gemini skills list 或 /skills list 查看，更新后用 /skills reload。
Cursor：在 Customize → Skills 里查看，或在 Agent 对话里输入 /paean-publish；更新后的技能没出现，就新开一个会话。
Antigravity IDE：查看 Customizations 菜单；桌面端如有需要，开一个新会话。
Harness：文件系统服务商监视技能；确认技能在它的目录中，并且能加载。
Codex 自动检测变更；如果变更没有出现，就重启。复制文件只能验证安装，不能验证运行中客户端的目录或权限授予。你也可以在提示词或项目指令文件中直接引用任意 SKILL.md。

Gemini 和 Cursor 快速开始

安装两个原生变体，或只选你用的客户端：

node scripts/install-skills.mjs --target gemini,cursor --dry-run
node scripts/install-skills.mjs --target gemini,cursor
node scripts/install-skills.mjs --target gemini,cursor --check

默认目标目录是 ~/.gemini/skills/paean-/ 和 ~/.cursor/skills/paean-*/。
安装器会从通用源就地更新较旧的 Gemini 副本，并备份改动过的文件。如果共享的 .agents/skills/ 副本已经生效，就用 --dest 更新那个已验证的目标目录，不要再添加一份不生效的重复副本。同一作用域内，Gemini 的别名优先；Cursor 也能发现已有的 Claude/Codex 技能副本。

在 Gemini 中，说「Use paean-publish to preview this project's release」，然后查看 /skills list。
在 Cursor 中，调用 /paean-publish 并要求 dry-run，或者正常描述任务，让它自动选择技能。把所有随附资源放在 SKILL.md 旁边；仓库里的 gemini/ 和 cursor/ 文件夹是分发源，本身不是发现根目录。
技能按需加载；不需要额外的 GEMINI.md 或 .cursorrules。

Cursor 的全局技能默认留在本地，除非你显式为 Cloud Agents 同步。做远程工作时，用提交到该项目仓库的项目技能，或用你选定的 Cursor 同步方案。
安装本仓库的技能不会配置该同步，也不会传输凭据。

关于 8x.gg 发现，Gemini/Cursor MCP 指南 包含 Gemini settings.json 和 Cursor mcp.json 的 JSON 模板，使用各客户端自己的环境变量语法。MCP 注册与安装技能是两回事；保留现有设置，并使用你的 Paean 登录。Node 和可选的工作流依赖必须在智能体实际运行的环境中可用。

创作过程中的语音

说「use Paean TTS for this game's tutorial」、「给演示视频加中文旁白」，或 paean tts。
Create、Remix、Record Demo 和 Red Skill 版会把固定语音资源路由到 paean-tts。应用内动态朗读使用 paean-sdk 的 AI 指南 和播放器的主机会话。不需要上游 DashScope 密钥：本地助手用创作者的 Paean JWT 认证，上游凭据由 Paean 管理。这是已认证账号访问，不是匿名或无限量服务。绝不要把 JWT 放进前端代码、构建时环境变量、浏览器存储、Git、日志或 ZIP 里。 运行时应用使用播放器的 SDK 宿主会话，不得请求或存储自己的 JWT。遵守 TTS 技能的安全要求，分享或发布前检查最终产物里有没有凭据。

Public availability / voices; no synthesis
node <skill-dir>/scripts/paean_tts.mjs status
Validate an authored UTF-8 script without credentials, network, or output writes
node <skill-dir>/scripts/paean_tts.mjs synthesize --text-file narration.txt --voice Cherry --out audio/narration --dry-run
Generate when narration is part of the requested work; may consume platform usage
node <skill-dir>/scripts/paean_tts.mjs synthesize --text-file narration.txt --voice Cherry --out audio/narration

把返回的音频保存到本地并复用；临时音频 URL 不是永久资产。RedNote 离线小工具在当前白名单下无法调用云端 TTS，也不能直接打包 WAV/MP3。它们各自的演示视频可以使用生成的旁白。技能文档说明了状态、音色、分段、认证、支持的字段，以及出错时的有界恢复。

用法

已发布作品的标题、描述、发现标签和面向玩家的 README 默认用英文，除非用户明确要求其他语言。为玩法、游玩风格、美术风格、主题、设定/背景和独特设计特征选用具体、准确的关键词；技术实现相关的表述放在单独的开发者文档里。这条规则适用于新作品、改编和发布更新。参见发布文案标准。

在 Square 发布之前，把审核过的 title、summary、category 和完整的 tags 保存到项目的 clide.json，并对照 README 检查 dry-run 解析出的元数据。

在你要发布的项目里执行：

Prepare and locally review this work’s real creation record; keep it private
mkdir -p .clide
node <skill-dir>/scripts/sessions.mjs prepare --file /path/to/actual-session.jsonl --out .clide/creation-session.jsonl

Preview, then publish publicly with a random first handle and private session linking
node <skill-dir>/scripts/publish.mjs --dry-run
node <skill-dir>/scripts/publish.mjs --yes

Preview, then deploy to Clide hosting without an Apps Square listing
node <skill-dir>/scripts/publish.mjs --dry-run --hosting-only --dir dist
node <skill-dir>/scripts/publish.mjs --yes --hosting-only --dir dist

Square 发布结果返回 url 和 shareUrl，格式为 https://www.8x.gg/apps/{hashKey}。分享作品时用这个规范链接。playUrl 保留运行时地址；shellUrl 是可选的诊断地址。仅托管项目没有 Square 上架信息，因此保留其实际的 Clide URL。dry-run 不会生成已发布链接。

独立提交创作记录

用 paean-sessions 处理「提交这个作品的 JSONL 创作记录做原创认证」或「补交创作备份」。
它既能上传新的私有记录，也能关联已经就绪的资产，无需重新发布：

node <paean-sessions-dir>/scripts/sessions.mjs submit --file /private/path/creation-session.jsonl --app OWNED_APP_HASH
node <paean-sessions-dir>/scripts/sessions.mjs bind --asset ASSET_ID --app OWNED_APP_HASH

它为独立的原创认证系统和流量支持系统提供公共数据源。提交或关联的结果，要与它们的最终决定分开汇报。这个辅助脚本不会主动加入平台研究共享，也不会参与模型训练。

给已有作品打赏和 Boost

用 paean-publish 处理「给这个作品打赏 100 credits」「给我自己的作品打赏 100 credits」，或「给这个作品做一次 500 credits 的极速 Boost」，同时附上实际作品链接。
这些只是示例请求，不是默认消费金额。你也可以登录后在 https://www.8x.gg/apps/{hashKey} 使用 Tip 或 Boost，无需重新发布。

支持给自己打赏，收益仍按平台/二创分成规则分配。作品页的 Boost 是 Express Boost，可用于你自己或他人已上架的作品；创作者内容 Boost 则是为你自己已上架的作品预留一笔美元预算，用于信息流投放。
页面操作步骤、报价、支付 API、收据和重复扣费恢复，见 Tip and Boost guide。publish.mjs 没有 tip/boost 参数，发布也不会自动购买这两项操作。

Tip 支持和 Boost 能帮作品吸引玩家注意；内容 Boost 能增加展示和获取流量的机会。效果取决于作品本身、受众反应和平台分发。打赏不是固定的排名倍数，Express Boost 的计数也不能作为自然触达的证据。

校验和二创游戏

发布新创建或二创的游戏之前，先校验它自包含的项目和浏览器运行时（工作环境里必须装好 Playwright）：

node <paean-game-create-skill-dir>/scripts/validate-game.mjs <game-dir> \
--screenshots <temporary-screenshot-dir>

把已有游戏二创成新游戏：

h1 is the primary: cloned server-side (full assets) into the user's workspace.
h2/h3 are read through the 8x.gg MCP server (text sources, no workspace).
Then build the new game and publish it — every parent is credited exactly once.
node <skill-dir>/scripts/remix.mjs --yes h1=gameplay h2=art h3=theme --dir my-remix

8x.gg MCP 服务器

https://api.paean.ai/8x/mcp 是二创流程中负责发现和研究的那一半：find_app / search_apps 把任意 8x.gg 或 clide.app 链接、标题或描述解析成应用；get_app / get_remix_lineage / get_app_growth 判断它值不值得二创；list_app_files / read_app_file 让智能体直接读源码，不用克隆任何东西。
脚本负责交付这一半（完整资产、本地脚手架、发布）。paean-zero-setup 按主机注册服务器（包括 Gemini/Cursor 配置模板），用的是同一个 Paean token；在 Paean Mac 应用内，它会自动注册为 8xgg。

任何脚本都可以加 --help 运行，查看完整用法。智能体应遵循的完整工作流，见每个技能的 SKILL.md。

混编图谱（clide.json）

paean-remix 会写出 clide.json 清单，同时用两种兼容形式记录血缘：

{
"schemaVersion": 1,
"title": "Neon Drift Racer",
"summary": "Chase high scores in a fast-paced drift racer through a neon-noir cyberpunk city. Chain slides around rain-slick corners, choose branching shortcuts, and keep your combo alive beneath glowing skylines.",
"category": "racing",
"tags": ["drift-racing", "score-attack", "fast-paced", "neon-noir", "cyberpunk", "city-at-night", "branching-shortcuts", "drift-combos"],
"license": "MIT",
"remix": {
"parent": "h1", // tree form: primary upstream
"parents": [ // graph form: the remix DAG
{ "hashKey": "h1", "role": "gameplay", "weight": 1 },
{ "hashKey": "h2", "role": "art", "weight": 1 },
{ "hashKey": "h3", "role": "theme", "weight": 1 }
]
}
}

remix.parent 让只认树形结构的消费方（以及后端的 remixOfHashKey 主父字段）继续可用；remix.parents[] 则是多父混编 DAG 的邻接表——每个直接上游都带上它贡献的方面和建议的收益 weight。paean-publish 会把直接父级的 hashKey 作为 remixOfHashKeys 转发出去，于是 zero-api 为整张图记录 SquareRemixEdge 行。

安全

- 两种模式都会创建可公开访问的站点。脚本要求显式确认（或加 --yes）；仅托管模式从不创建工作区，也不创建 Apps Square 上架条目。
- Wrangler/Worker/D1/R2 项目会被判定为运行时不兼容，并在上传前拦截，除非用户用 --allow-static-only 明确接受纯前端部署。
- 发布的游戏应在 index.html 中包含标准的 paean.ai 版权注释，并带有项目 LICENSE；混编作品还应把直接父级记录到 clide.json。
- 游戏应附带顶层 favicon.svg 和 800x400 的 banner.jpg。两者缺失或 banner 尺寸不对时，发布脚本会警告，但不阻止发布。
- 凭据只从环境变量 / 凭据文件读取——绝不硬编码，也绝不写进发布产物。
- 高置信度密钥扫描器会拦截疑似私钥或 API token 的文件，不让其发布。
- 默认情况下，下载的原始上游源码（.remix-sources/）和 clide.json 清单不会进入发布站点。
- paean-publish --delete 会区分模式：Square 项目先下架，再删除其 Clide 文件删除，而仅托管类项目只删除自己的站点。它可以从已保存或显式指定的 handle 解析出缺失的 Square 哈希，当无法安全确定 Square 身份时拒绝清理。

许可证

MIT — 见 LICENSE。