@zenaigc/zenmcp 0.1.9 → 0.1.11

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 (50) hide show
  1. package/INSTALL.md +114 -102
  2. package/dist/src/assets/index.js +1 -1
  3. package/dist/src/assets/model-library.js +157 -16
  4. package/dist/src/core/schema.js +1 -0
  5. package/dist/src/doctor.js +0 -0
  6. package/dist/src/effects/index.js +54 -13
  7. package/dist/src/engine/card.js +5 -2
  8. package/dist/src/engine/direct.js +2 -0
  9. package/dist/src/engine/generate.js +15 -2
  10. package/dist/src/engine/steps.js +84 -9
  11. package/dist/src/inspect/index.js +51 -12
  12. package/dist/src/mcp/guidance.js +1 -1
  13. package/dist/src/mcp/server.js +247 -19
  14. package/dist/src/timeline/conform.js +19 -5
  15. package/dist/src/timeline/cuts.js +13 -13
  16. package/dist/src/timeline/diff.js +25 -7
  17. package/dist/src/timeline/index.js +2 -2
  18. package/dist/templates/pop-title/render.js +28 -8
  19. package/package.json +1 -1
  20. package/skills/zenmcp/SKILL.md +77 -46
  21. package/skills/zenmcp/references/00-model-card.md +165 -0
  22. package/skills/zenmcp/references/01-dissect-and-checkpoints.md +68 -0
  23. package/skills/zenmcp/references/02-character-and-tryon.md +63 -0
  24. package/skills/zenmcp/references/03-wan3-camera-and-audio.md +43 -0
  25. package/skills/zenmcp/references/04-hyperframes-effects.md +61 -0
  26. package/skills/zenmcp/references/05-interaction-and-media.md +203 -0
  27. package/skills/zenmcp/references/06-work-delivery.md +29 -0
  28. package/skills/zenmcp/scripts/build-contact-sheet.mjs +179 -0
  29. package/skills/zenmcp/scripts/build-dissect-report.mjs +1233 -0
  30. package/skills/zenmcp/scripts/build-height-ruler.mjs +49 -0
  31. package/skills/zenmcp/scripts/build-side-by-side.mjs +56 -0
  32. package/skills/zenmcp/widgets/fixtures/zenmcp-budget-confirm.readonly.json +31 -0
  33. package/skills/zenmcp/widgets/zenmcp-account/template.json +1 -1
  34. package/skills/zenmcp/widgets/zenmcp-account/widget.html +8 -10
  35. package/skills/zenmcp/widgets/zenmcp-budget-confirm/template.json +5 -2
  36. package/skills/zenmcp/widgets/zenmcp-budget-confirm/widget.html +50 -13
  37. package/skills/zenmcp/widgets/zenmcp-install-checklist/template.json +1 -1
  38. package/skills/zenmcp/widgets/zenmcp-install-checklist/widget.html +18 -12
  39. package/skills/zenmcp/widgets/zenmcp-spend-confirm/template.json +13 -83
  40. package/skills/zenmcp/widgets/zenmcp-spend-confirm/widget.html +88 -65
  41. package/dist/src/setup/targets.js +0 -314
  42. package/skills/zenmcp/widgets/fixtures/zenmcp-asset-roles.json +0 -24
  43. package/skills/zenmcp/widgets/fixtures/zenmcp-model-picker.json +0 -25
  44. package/skills/zenmcp/widgets/fixtures/zenmcp-trim-range.json +0 -19
  45. package/skills/zenmcp/widgets/zenmcp-asset-roles/template.json +0 -54
  46. package/skills/zenmcp/widgets/zenmcp-asset-roles/widget.html +0 -73
  47. package/skills/zenmcp/widgets/zenmcp-model-picker/template.json +0 -31
  48. package/skills/zenmcp/widgets/zenmcp-model-picker/widget.html +0 -28
  49. package/skills/zenmcp/widgets/zenmcp-trim-range/template.json +0 -53
  50. package/skills/zenmcp/widgets/zenmcp-trim-range/widget.html +0 -52
package/INSTALL.md CHANGED
@@ -1,59 +1,44 @@
1
1
  # ZenMCP Agent 自助安装指南
2
2
 
3
- 请按「识别唯一宿主 → 环境检查 → 单次安装与自检 → 能力匹配配置 → 绑 Key → Skill → 诚实验收」流程执行。**平台 Key 不得在对话、命令行参数或日志中出现明文。**
3
+ 请直接在后台完成环境检查、安装、当前软件配置、平台 Key 检查与技能投递。**平台 Key 不得在对话、命令行参数或日志中出现明文。**
4
4
 
5
- ## 交互要求与红线
5
+ ## 面向非技术创作者的沟通原则(最高优先级)
6
6
 
7
- - **单宿主铁律(最高优先级)**:先确认当前对话所在的**唯一目标软件**(若会话存在 `mcp_superone_*` / `widget_show` 等工具,即使底层模型/引擎是 Claude、Codex、Grok、DeepSeek 或 Cursor,目标宿主一律为 **SuperOne**)。除非用户明确要求配置其他软件,**严禁扫描、询问或修改本机其他 AI 客户端的配置文件、软链或技能目录**。
8
- - **五步进度清单**:向用户展示并随真实进度更新:`环境检查 → 安装 → 客户端配置 → 绑定平台 Key → 启用与验证`。
9
- - **诚实勾选原则**:只有当前会话已实际挂载 `zenmcp` 工具并成功调用 `account_status` 时,最后一项才可标 `[x]`;凡需用户在界面手动粘贴配置或重载/新开会话才能生效时,对应项必须保持 `[ ] 待粘贴/重载后生效`,**严禁在终端手搓脚本调用 `server.js` 冒充会话已连通**。
10
- - **最少打扰与隐私脱敏**:
11
- - 缺失系统依赖只合并询问一次,列出所有缺项并提供「全部安装 / 我自行安装」选项(有选项式提问工具时优先使用)。
12
- - 将 `zenmcp-doctor` 输出整理成「通过 / 缺失」表格,不直接贴大段原始 JSON;`config` 三项(`ZENMCP_BASE_URL`、`ZENMCP_TOKEN`、`credentials_file`)只说明是否已配置,不展示值或凭据文件路径。
13
- - Key 不进入聊天:引导通过 `zenmcp-setup` 本机网页或终端 `zenmcp login` 隐藏输入保存;若用户自行粘贴到聊天,不回显并提示立即前往账户页撤销重建。
7
+ - **用户不是程序员**:正常检查与安装步骤直接执行即可,无需每跑一条命令就播报终端日志。最后**只输出一段精简结果**(除需填写的配置信息外控制在 **8 行以内**),用日常语言讲清两件事:**① 已经自动备好了什么**、**② 下一步需要用户点哪里**。
8
+ - **不输出底层术语、长表格与 `[x]` 符号**:给用户的回复中不要放进度表格,不要使用 `[x]` / `[ ]` 勾选符号(非技术用户容易把 `x` 误看成报错打叉),也不要堆砌 `zenmcp-doctor`、`ok: true`、`Node / FFmpeg / ffprobe / Chrome / render.js` 版本号、`ZENMCP_BASE_URL`、`ZENMCP_TOKEN`、`credentials_file`、`in_app_sandbox`、`0600`、`127.0.0.1`、`SKILL.md`、`widgets`、`nvm`、`Homebrew` 等内部细节或关于本文档本身的解释说明。
9
+ - **正常项直接通过,仅需用户配合时才打扰**:环境齐全、组件就绪、本机已有平台 Key 时直接进入下一步;仅当**电脑缺少基础软件需征得安装同意**,或**本机尚无平台 Key 需用户在网页保存**时,才用一句大白话请用户配合。
10
+ - **Key 零明文与一句话换绑**:绝不让用户把 Key 发到聊天里(若用户误发,不回显并提醒前往 https://zenaigc.com/console 撤销重建)。本机已有 Key 时无需再介绍绑 Key 命令;若用户主动说「帮我更换 ZenMCP 的 Key」,直接在后台运行 `"<node_path>" "<setup_bin>"` 打开本机绑定网页即可。
14
11
 
15
- | 异常 | 下一步 |
16
- | --- | --- |
17
- | 命令找不到 | 改用 `zenmcp-doctor` 返回的 `node_path` 与 `server_entry` 绝对路径(`command` 填 `node_path`,`args` 填 `[server_entry]`)。 |
18
- | `token_missing` | 按第 4 步在账户页创建 Key,通过本机 `zenmcp-setup` 或终端 `zenmcp login` 保存;保存后免重启客户端即可重试 `account_status`。 |
19
- | `invalid_credential` | 查看报错提示的凭据来源:来自本机凭据文件时重新执行登录保存即可;来自 `env.ZENMCP_TOKEN`(优先于凭据文件)时,移除或更新客户端配置中的 `env.ZENMCP_TOKEN` 后重载客户端。 |
20
- | 网络失败 | 检查网络连接及客户端能否访问 https://api.zenaigc.com,恢复后重试只读账户查询。 |
12
+ ---
21
13
 
22
- ## 1. 识别当前宿主与检查本机环境
14
+ ## 执行步骤
23
15
 
24
- 结合自身系统提示词/内置工具列表、当前工作目录路径及环境变量确认唯一宿主(可参考第 2 步 `zenmcp-doctor` 的 `runtime.detected_host_hint`,但以“外层对话软件优先于底层引擎”为准)。
16
+ ### 1. 识别当前宿主软件并检查基础环境
25
17
 
26
- 随后检查依赖:`node -v`(确认 Node.js ≥ 22)、`ffmpeg -version`、`ffprobe -version`,并检查 Google Chrome 已安装且可启动。
18
+ - **锁定当前宿主**:结合系统提示词/内置工具列表、工作目录及环境变量确认当前对话所在的宿主软件(若会话具备 `mcp_superone_*` / `mcp__superone__*` / `widget_show` 等工具,无论底层引擎是 Claude、Codex、Antigravity、Grok 还是 DeepSeek,目标宿主均为 **SuperOne**)。除非用户明确要求,不要扫描或修改本机其他无关 AI 软件的配置。
19
+ - **检查运行依赖**:检查 `node -v`(≥ 22)、`ffmpeg -version`、`ffprobe -version` 与 Google Chrome。全部具备时直接进入下一步;若有缺失,用一句大白话征得用户同意后按系统安装:
20
+ - macOS:`brew install node@22 ffmpeg`、`brew install --cask google-chrome`
21
+ - Windows:`winget install OpenJS.NodeJS.LTS`、`winget install Gyan.FFmpeg`、`winget install Google.Chrome`
22
+ - Linux:`apt` 安装 Node.js(≥ 22)、FFmpeg 与 Google Chrome 官方 deb 包
27
23
 
28
- 有缺失时,先合并告知缺项并征得用户同意,再按系统安装:
24
+ ### 2. 安装或更新并读取本机路径
29
25
 
30
- - macOS:`brew install node@22 ffmpeg`、`brew install --cask google-chrome`(确保 Node.js 在 `PATH` 中)。
31
- - Windows:`winget install OpenJS.NodeJS.LTS`、`winget install Gyan.FFmpeg`、`winget install Google.Chrome`。
32
- - Linux:使用 `apt` 安装 Node.js、FFmpeg 与 Google Chrome(使用官方 deb 包交给 `apt` 安装);若默认源 Node.js < 22,先说明需要配置兼容软件源并获同意后再处理。
33
-
34
- 安装后重新打开终端或刷新环境并复查;FFmpeg 应同时提供 `ffprobe`。
35
-
36
- ## 2. 安装 ZenMCP 并运行单次自检
37
-
38
- 优先指定 npm 官方源安装,避免国内镜像源滞后在旧版本(仅当官方源不可达时回退默认 `npm install -g @zenaigc/zenmcp`):
26
+ 优先从 npm 官方源安装(仅官方源不可达时回退默认源),随后执行自检读取真实路径:
39
27
 
40
28
  ```bash
41
29
  npm install -g @zenaigc/zenmcp --registry=https://registry.npmjs.org
42
- ```
43
-
44
- 随后运行一次本机自检:
45
-
46
- ```bash
47
30
  zenmcp-doctor
48
31
  ```
49
32
 
50
- - 确认 `"ok": true`(否则按缺项修复后重跑)。未绑 Key 前 `config` 中 `ZENMCP_BASE_URL`、`ZENMCP_TOKEN` 与 `credentials_file` 为 `false` 属正常,不影响自检。
51
- - 从返回的 `runtime` 读取 `node_path`、`server_entry`、`setup_bin`、`skill_dir`、`in_app_sandbox`、`headless_or_ssh` 与 `detected_host_hint`(若遇旧版尚无 `runtime` 字段,用 `command -v node` / `where.exe node` 与 `npm root -g` 定位 `<npm root -g>/@zenaigc/zenmcp/dist/src/mcp/server.js` 等路径)。
52
- - **沙盒免双装规则**:当 `in_app_sandbox` 为 `true`(如豆包电脑版内置 `sandbox_runtime`)时,**禁止再往用户的 `nvm`、Homebrew 或系统目录重复安装第二遍**;后续统一使用 `runtime.node_path` 与 `runtime.server_entry` 绝对路径,GUI 与沙盒均可直接独立启动。
33
+ - 确认 `"ok": true`,从 `runtime` 读取 `node_path`、`server_entry`、`setup_bin`、`skill_dir`、`in_app_sandbox`、`headless_or_ssh` 与 `detected_host_hint`(旧版无 `runtime` 时用 `command -v node` / `where.exe node` 与 `npm root -g` 定位)。
34
+ - **沙盒环境直接使用内置路径**:`in_app_sandbox` 为 `true`(如豆包电脑版或 WorkBuddy 内置 Node 环境)时,不要再往系统 `nvm` 或 Homebrew 重复安装第二份,后续配置直接使用 `runtime.node_path` 与 `runtime.server_entry` 绝对路径。
35
+ - **以本指南为准**:无需再回读 `node_modules` 包内的旧版说明,完成后直接按文末回复模板收尾。
36
+
37
+ ### 3. 按当前软件写入用户级(User-scope)MCP 配置
53
38
 
54
- ## 3. 按宿主的 MCP 注册能力配置当前软件
39
+ - **用户级安装原则(User-scope)**:一律注册到当前软件的**用户级(全局)**配置位置,让用户切换任何文件夹或项目都能直接使用;除非用户明确指定仅限某单一项目,**不要**写入当前工作区下的局部配置(如项目内的 `.mcp.json`、`.cursor/mcp.json`、`.vscode/mcp.json`、`.codex/config.toml`)。
55
40
 
56
- GUI 客户端常不继承终端 `nvm` / Homebrew 的 `PATH`,配置一律使用**无密钥绝对路径**(内置默认地址 `https://api.zenaigc.com/api/v1`,无需配置 `ZENMCP_BASE_URL`):
41
+ 标准无密钥配置结构(内置默认服务地址,无需写 `ZENMCP_BASE_URL`):
57
42
 
58
43
  ```json
59
44
  {
@@ -66,69 +51,96 @@ GUI 客户端常不继承终端 `nvm` / Homebrew 的 `PATH`,配置一律使用
66
51
  }
67
52
  ```
68
53
 
69
- ### 三种注册模式
70
-
71
- - **M1(原生 CLI 注册)**:调用当前宿主的官方 CLI 命令原子写入用户级配置。
72
- - **M2(本地配置文件备份合并)**:仅操作当前宿主自己的配置文件(已有文件先备份),按其语法方言合并 `zenmcp` 节点,保留其他全部已有配置与服务。
73
- - **M3(封闭存储 / 界面手动添加)**:当前宿主无公开外部配置文件时,**不改其他客户端文件、不用桌面自动化点击宿主自身窗口**;向用户输出填好真实 `<node_path>` 与 `<server_entry>` 的配置块并指明界面入口,清单对应项保持 `[ ] 待你在界面粘贴启用`。
74
-
75
- ### 主流宿主能力匹配表
54
+ - **M1(原生 CLI 用户级注册)**:调用官方 CLI 原子写入用户级配置。
55
+ - **M2(用户级配置文件备份合并)**:先备份目标软件的用户级配置文件,再按其语法合并 `zenmcp` 条目,完整保留其他已有服务。
56
+ - **M3(界面手动添加)**:当前软件不支持外部直接写入生效时,不强改其他软件配置,在最终回复中给出精确的界面填写值。
76
57
 
77
- | 宿主软件 | MCP 注册模式与目标位置 / 语法方言 | Skill 模式(第 5 步) |
58
+ | 宿主软件 | MCP 用户级注册方式与位置 | Skill / 组件投递(第 5 步) |
78
59
  | --- | --- | --- |
79
- | **SuperOne** | **M2 / M3**:在其 MCP 设置中添加标准 `mcpServers` JSON | **S2**:整目录复制到 `~/.agents/skills/zenmcp`,并将 `widgets/zenmcp-*` 复制到 `~/.superone/widget/`(alpha 为 `~/.superone/alpha/widget/`) |
80
- | **Claude Code** | **M1**:执行 `claude mcp add -s user zenmcp -- "<node_path>" "<server_entry>"` | **S1**:`~/.claude/skills/zenmcp/SKILL.md` |
81
- | **Codex** (OpenAI) | **M1 / M2-TOML**:执行 `codex mcp add zenmcp -- "<node_path>" "<server_entry>"`,或备份合并 `~/.codex/config.toml` 的 `[mcp_servers.zenmcp]` | **S1**:`~/.codex/skills/zenmcp/SKILL.md` |
82
- | **Grok CLI** (xAI) | **M2-TOML**:备份合并 `~/.grok/config.toml` 的 `[mcp_servers.zenmcp]`(`command = "<node_path>"`、`args = ["<server_entry>"]`),可用 `grok inspect` 检查 | **S1**:`~/.grok/skills/zenmcp/SKILL.md` |
83
- | **DeepSeek Harness (`dsh`)** | **M2-YAML**:在 `~/.dsh/` 当前 profile 的 Cordis 配置中为 `@deepseek-ai/dsh-mcp-client` 添加 stdio 服务 | **S1**:`~/.dsh/skills/zenmcp/SKILL.md` |
84
- | **Cursor** | **M2-JSON**:备份合并 `~/.cursor/mcp.json`(`mcpServers`) | **S1**:`~/.cursor/skills/zenmcp/SKILL.md` |
85
- | **Trae / Trae CN** | **M2-JSON**:备份合并 `~/.trae/mcp.json`(`mcpServers`) | **S1**:当前项目工作区 `.trae/skills/zenmcp/SKILL.md`(无工作区则跳过) |
86
- | **CodeBuddy / WorkBuddy** | **M2-JSON**:CodeBuddy 合并 `~/.codebuddy/mcp.json`;WorkBuddy 合并 `~/.workbuddy/mcp.json`(`mcpServers`) | **S1**:CodeBuddy 为 `~/.codebuddy/skills/zenmcp/SKILL.md`;WorkBuddy 如无 skills 目录则跳过 |
87
- | **豆包电脑版** | **M3**:输出绝对路径 JSON 块,引导左侧「技能·连接器 → 添加 MCP」粘贴 | **S1**:复制到豆包 Agent 工作区的 `.user_skills/zenmcp/SKILL.md` |
88
- | **Claude Desktop** | **M2-JSON**:备份合并 macOS `~/Library/Application Support/Claude/claude_desktop_config.json` 或 Windows `%APPDATA%\Claude\claude_desktop_config.json` | **S0**:跳过 |
89
- | **VS Code (Copilot)** | **M2-异构 JSON**:合并用户级 `mcp.json` 或工作区 `.vscode/mcp.json`,**顶层键为 `"servers"`**,条目为 `{"type":"stdio","command":"<node_path>","args":["<server_entry>"]}` | **S0 / S1**:有项目工作区可写 `.github/skills/zenmcp/SKILL.md`,否则跳过 |
90
- | **OpenCode** | **M2-异构 JSON**:备份合并 `~/.config/opencode/opencode.json`,在 **`"mcp"`** 下配置 `"zenmcp": {"type":"local","command":["<node_path>","<server_entry>"],"enabled":true}` | **S1**:`~/.config/opencode/skills/zenmcp/SKILL.md` |
91
- | **Gemini CLI** | **M2-JSON**:备份合并 `~/.gemini/settings.json`(`mcpServers`,保留全部其他字段) | **S1**:`~/.gemini/skills/zenmcp/SKILL.md` |
92
- | **Antigravity / Windsurf / Kiro** | **M2-JSON**:分别合并 `~/.gemini/antigravity/mcp_config.json`、`~/.codeium/windsurf/mcp_config.json`、`~/.kiro/settings/mcp.json`(`mcpServers`) | **S1**:支持全局 `skills/` 时写入对应 `skills/zenmcp/SKILL.md`,否则跳过 |
93
- | **OpenClaw** | **M2-JSON5**:先读取 `~/.openclaw/openclaw.json` 确认结构后合并或通过 `mcporter` 注册 | **S1**:`~/.openclaw/skills/zenmcp/SKILL.md` |
94
- | **Muse / Cherry Studio / Cline / Roo Code** | **M3**:输出绝对路径 JSON 块,引导在当前软件的「Settings → Connectors」或「MCP 服务器」面板粘贴 | **S0**:跳过 |
95
-
96
- ### 未知宿主自省兜底流程
97
-
98
- 当当前软件未在上表中出现时,按三步自主探索:
99
-
100
- 1. 检查自身工具列表是否有内置 MCP 注册工具,或在终端尝试 `<当前宿主CLI> mcp --help` 查看原生命令。
101
- 2. 若具备联网搜索或本地文档检索能力,主动查询 `<当前软件名> MCP configuration file format path skills directory`,核实配置文件路径与顶层键名。
102
- 3. 凡无法 100% 确认外部配置文件路径与格式时,**严禁盲猜写文件**,自动退回 **M3 模式**,输出已填好真实绝对路径的标准配置块,请用户在当前软件的 MCP / 连接器设置界面粘贴。
103
-
104
- 首次写入或粘贴完成后,重载或新开一次宿主会话使工具挂载生效。
105
-
106
- ## 4. 按运行环境匹配零密文绑 Key 通道(一次保存,同机共用)
107
-
108
- 引导用户前往 https://zenaigc.com/console (或 https://api.zenaigc.com )登录并创建平台 Key,按环境分流:
109
-
110
- - **A0(已绑定)**:`zenmcp-doctor` 显示 `config.credentials_file: true` 时直接跳过,说明本机安全凭据库已有可用 Key。
111
- - **A1(本机图形桌面,`headless_or_ssh: false`)**:由 Agent 直接运行以下命令启动本机 `127.0.0.1` 网页连接卡片(保存后临时端口自动关闭,写入 `0600` 权限凭据库,同机所有客户端共用且免重启生效):
112
- ```bash
113
- "<node_path>" "<setup_bin>"
114
- ```
115
- 若宿主沙盒禁止弹出浏览器,改用 `"<node_path>" "<setup_bin>" --no-open` 输出本地地址或将该完整命令交由用户执行。
116
- - **A2(纯终端或远程 SSH,`headless_or_ssh: true`)**:请用户在运行 `zenmcp` 的机器终端自行执行以下命令隐藏粘贴保存(若 `zenmcp` 已在系统 `PATH` 可直接运行 `zenmcp login`):
117
- ```bash
118
- "<node_path>" "<setup_bin>" --terminal
119
- ```
120
-
121
- 如需按单个客户端单独指定 Key,也兼容在客户端配置块中加入 `"env": { "ZENMCP_TOKEN": "<平台Key>" }` 并重载客户端(注意:`env.ZENMCP_TOKEN` 优先级高于本机凭据文件;若其中旧 Key 已失效,需先移除或更新并重载)。如需清除本机保存的凭据,可运行 `"<node_path>" "<setup_bin>" logout`(或 `zenmcp logout`)。
122
-
123
- ## 5. 只投递当前宿主的 Skill(S0 / S1 / S2)
124
-
125
- 使用第 2 步得到的 `skill_dir`:
126
-
127
- - **S2(SuperOne)**:将 `<skill_dir>` 整个目录复制到 `~/.agents/skills/zenmcp`(含 `SKILL.md` 与 `widgets/`),并把 `<skill_dir>/widgets/zenmcp-*` 复制到 `~/.superone/widget/`(alpha 版为 `~/.superone/alpha/widget/`)。
128
- - **S1(支持 `SKILL.md` 的其他宿主)**:先创建当前宿主对应的 `skills/zenmcp` 目录,**仅复制 `<skill_dir>/SKILL.md` 单文件**(不复制 `widgets/`,更不写入其他客户端的目录)。
129
- - **S0(不支持 Skills 的宿主)**:跳过本步。
130
-
131
- ## 6. 连通验证与收尾
132
-
133
- - **当前会话已原生挂载 `zenmcp` 工具时**:直接调用只读工具 `account_status`,原样展示积分信息与「可以这样说」欢迎块(有效可用积分为 0 时引导前往 https://zenaigc.com/console 充值或调整 Key 限额),五步清单全部标 `[x]`。
134
- - **需界面粘贴(M3)或尚未重载会话(M1/M2)时**:保持「启用与验证」为 `[ ]`,明确提示用户在完成界面粘贴或重载/新开对话后,发送「检查我的 ZenMCP 账户状态」即可完成最后一步验证。
60
+ | **SuperOne** | **M1 / M2(全自动用户级双写,免手动粘贴)**:SuperOne「设置 → MCP」直接读取底层引擎的用户级配置。请将 `zenmcp` 写入 `~/.claude.json` 顶层 `mcpServers`(或执行 `claude mcp add -s user zenmcp -- "<node_path>" "<server_entry>"`),若存在 `~/.codex` 则同步写入 `~/.codex/config.toml` 的 `[mcp_servers.zenmcp]`(或 `codex mcp add zenmcp -- "<node_path>" "<server_entry>"`),使用户新开任意会话即自动生效(手动兜底入口为「设置 → MCP → 添加服务器 → 粘贴」) | **S2**:整目录复制到 `~/.agents/skills/zenmcp`(若存在 `~/.claude/skills`、`~/.codex/skills` 亦同步),并将 `widgets/zenmcp-*` 复制到 `~/.superone/widget/`(alpha 为 `~/.superone/alpha/widget/`) |
61
+ | **豆包电脑版** | **M3(分字段 STDIO 表单)**:在「豆包 工作」的「新工作任务(本地电脑)」中执行安装后,按文末「场景 A1(豆包电脑版专属)」给出「插件·技能·工作台 → 添加 → 新建自定义连接器(STDIO)」三项填写值;**注意「命令」完整路径必须外包英文双引号**(防止 `Application Support` 等空格拆断命令导致运行失败),「参数」单填 `<server_entry>` 不加引号 | **S1**:整目录复制到豆包 Agent 工作区 `.user_skills/zenmcp` |
62
+ | **WorkBuddy / CodeBuddy** | **M2-JSON**:备份合并 `~/.workbuddy/mcp.json`(CodeBuddy 为 `~/.codebuddy/mcp.json`)的 `mcpServers`;完成后按「场景 B1(WorkBuddy)」指引用户在「专家·技能·连接器 → 连接器 → 自定义连接器」保存加载并点击 `zenmcp` 旁的「信任」 | **S1**:`~/.workbuddy/skills/zenmcp`(CodeBuddy 为 `~/.codebuddy/skills/zenmcp`) |
63
+ | **Claude Code** | **M1**:`claude mcp add -s user zenmcp -- "<node_path>" "<server_entry>"` | **S1**:`~/.claude/skills/zenmcp` |
64
+ | **Codex** (OpenAI) | **M1 / M2-TOML**:`codex mcp add zenmcp -- "<node_path>" "<server_entry>"`,或合并 `~/.codex/config.toml` 的 `[mcp_servers.zenmcp]` | **S1**:`~/.codex/skills/zenmcp` |
65
+ | **Claude Desktop** | **M2-JSON**:合并 macOS `~/Library/Application Support/Claude/claude_desktop_config.json` 或 Windows `%APPDATA%\Claude\claude_desktop_config.json` | **S0**:跳过 |
66
+ | **Grok CLI** (xAI) | **M2-TOML**:合并 `~/.grok/config.toml` 的 `[mcp_servers.zenmcp]`(`command = "<node_path>"`、`args = ["<server_entry>"]`) | **S1**:`~/.grok/skills/zenmcp` |
67
+ | **DeepSeek Harness (`dsh`)** | **M2-YAML**:在 `~/.dsh/` 当前 profile 的 Cordis 配置中为 `@deepseek-ai/dsh-mcp-client` 添加 stdio 服务 | **S1**:`~/.dsh/skills/zenmcp` |
68
+ | **Cursor** | **M2-JSON**:合并 `~/.cursor/mcp.json`(`mcpServers`) | **S1**:`~/.cursor/skills/zenmcp` |
69
+ | **Trae / Trae CN** | **M2-JSON**:合并 `~/.trae/mcp.json`(`mcpServers`) | **S1**:优先 `~/.trae/skills/zenmcp`(仅支持工作区技能时再按实际处理,否则跳过) |
70
+ | **VS Code (Copilot)** | **M2-异构 JSON**:只合并用户级 `mcp.json`(macOS `~/Library/Application Support/Code/User/mcp.json`、Windows `%APPDATA%\Code\User\mcp.json`、Linux `~/.config/Code/User/mcp.json`),**顶层键为 `"servers"`**,条目 `{"type":"stdio","command":"<node_path>","args":["<server_entry>"]}` | **S0**:无全局技能目录则跳过 |
71
+ | **OpenCode** | **M2-异构 JSON**:合并 `~/.config/opencode/opencode.json` 的 **`"mcp"`** 下 `"zenmcp": {"type":"local","command":["<node_path>","<server_entry>"],"enabled":true}` | **S1**:`~/.config/opencode/skills/zenmcp` |
72
+ | **Gemini CLI** | **M2-JSON**:合并 `~/.gemini/settings.json`(`mcpServers`,保留其他字段) | **S1**:`~/.gemini/skills/zenmcp` |
73
+ | **Antigravity / Windsurf / Kiro** | **M2-JSON**:分别合并 `~/.gemini/antigravity/mcp_config.json`、`~/.codeium/windsurf/mcp_config.json`、`~/.kiro/settings/mcp.json` | **S1**:支持全局 `skills/` 时整目录复制到对应 `skills/zenmcp`,否则跳过 |
74
+ | **OpenClaw** | **M2-JSON5**:先读取 `~/.openclaw/openclaw.json` 确认结构后合并或通过 `mcporter` 注册 | **S1**:`~/.openclaw/skills/zenmcp` |
75
+ | **Muse / Cherry Studio / Cline / Roo Code** | **M3**:引导在当前软件「Settings → Connectors」或「MCP 服务器」面板粘贴标准 JSON | **S0**:跳过 |
76
+
77
+ - **未知软件兜底**:未在上表出现时,① 先查自身内置 MCP 工具或 `<当前CLI> mcp --help`;② 有检索能力时确认该软件官方**用户级** MCP 配置路径与格式;③ 无法 100% 确认时不要盲猜写文件,退回 **M3(场景 A2)** 请用户在软件设置中添加。
78
+
79
+ ### 4. 检查或引导绑定平台 Key(一次保存,同机共用)
80
+
81
+ - **A0(已有 Key,`config.credentials_file: true`)**:直接跳过,无需向用户提及绑 Key 命令或更换流程。
82
+ - **A1(无 Key + 本机桌面,`headless_or_ssh: false`)**:在后台运行 `"<node_path>" "<setup_bin>"` 自动弹出本地绑定网页,用一句话告诉用户:「已为你打开本机绑定页面,请点击页面入口登录 https://zenaigc.com/console 获取平台 Key,粘贴保存后告诉我一声即可(请勿把 Key 发到聊天里)。」若沙盒限制无法自动弹窗,改运行 `"<node_path>" "<setup_bin>" --no-open` 把本机网页链接发给用户点击。
83
+ - **A2(无 Key + 纯终端 / 远程 SSH,`headless_or_ssh: true`)**:请用户前往 https://zenaigc.com/console 创建 Key,并在服务器终端执行 `"<node_path>" "<setup_bin>" --terminal`(或 `zenmcp login`)隐藏输入保存。
84
+
85
+ ### 5. 投递当前软件的 Skill 与组件
86
+
87
+ - **S2(SuperOne)**:将 `<skill_dir>` 整目录复制到 `~/.agents/skills/zenmcp`(及已存在的 `~/.claude/skills/zenmcp`、`~/.codex/skills/zenmcp`),并将 `<skill_dir>/widgets/zenmcp-*` 复制到 `~/.superone/widget/`(alpha 为 `~/.superone/alpha/widget/`)。
88
+ - **S1(支持 `SKILL.md` 的软件)**:将 `<skill_dir>` 整目录复制到对应用户级 `zenmcp` 技能目录(包含 `SKILL.md`、`references/` 与 `scripts/`)。
89
+ - **S0(不支持的软件)**:跳过。
90
+ - **生图默认档位约定(日常创作时遵守,安装回复中勿提及)**:用户生图且未主动指定画质或分辨率时,默认采用 `quality="medium"`(`med`)、`resolution="1K"`(报价时省略以沿用目录默认值即可),**切勿擅自选 `high` 或 `2K`/`4K`**。
91
+
92
+ ### 常见排障参考(仅遇到报错时使用)
93
+
94
+ - 命令找不到 / 豆包报 `COMMAND_NOT_FOUND`:检查是否使用了 `runtime.node_path` 与 `runtime.server_entry` 绝对路径;豆包 STDIO「命令」栏含空格路径必须外包英文双引号 `"<node_path>"`,「参数」栏保持单条路径不加引号。
95
+ - `token_missing`:按第 4 步打开绑定网页或终端隐藏输入保存,免重启即可重试。
96
+ - `invalid_credential`:若来自本机凭据文件则重新运行 `"<node_path>" "<setup_bin>"` 更换;若客户端配置了 `env.ZENMCP_TOKEN`(优先于凭据文件),移除旧环境变量并重载软件。
97
+ - 网络失败:检查本机能否访问 https://api.zenaigc.com。
98
+
99
+ ---
100
+
101
+ ## 最终对用户的回复模板(按实际场景选一,保持精炼)
102
+
103
+ 当前对话未挂载 `zenmcp` 工具时,不要在终端手动运行 `server.js` 模拟连通,直接按对应模板输出即可。
104
+
105
+ ### 场景 A1:豆包电脑版(需在 STDIO 表单分项填入)
106
+
107
+ > **ZenMCP 已安装就绪**(本地环境、核心组件、平台 Key 与创作技能均已备好)。
108
+ >
109
+ > **最后一步(在豆包界面添加连接器):**
110
+ > 1. 打开左侧 **「插件·技能·工作台」** → 点击右上角 **「添加」** → **「新建自定义连接器」**,传输类型选 **`STDIO`**,按下面三项原样填入后点 **「保存」**:
111
+ > - **服务器名称**:`zenmcp`
112
+ > - **命令**(请保留首尾英文双引号):`"<真实 node_path>"`
113
+ > - **参数**(点一次「添加」填入,不加引号):`<真实 server_entry>`
114
+ > 2. 看到 `zenmcp` 蓝色开关开启后,点左侧 **「新工作任务」**(保持「本地电脑」),发送 **「检查我的 ZenMCP 账户状态」** 即可开拍。
115
+
116
+ ### 场景 A2:其他需手动粘贴 JSON 的软件(M3 通用)
117
+
118
+ > **ZenMCP 已安装就绪**(本地环境、核心组件与平台 Key 均已备好)。
119
+ >
120
+ > **最后一步:** 打开当前软件的 MCP 设置面板,粘贴下方配置保存,随后新开对话发送 **「检查我的 ZenMCP 账户状态」** 即可使用:
121
+ > ```json
122
+ > {
123
+ > "mcpServers": {
124
+ > "zenmcp": {
125
+ > "command": "<真实 node_path>",
126
+ > "args": ["<真实 server_entry>"]
127
+ > }
128
+ > }
129
+ > }
130
+ > ```
131
+
132
+ ### 场景 B1:WorkBuddy(已自动写入 `~/.workbuddy/mcp.json`,需信任启用)
133
+
134
+ > **ZenMCP 已自动安装并写入用户级配置**(核心组件、平台 Key 与创作技能均已就绪)。
135
+ >
136
+ > **下一步:** 打开左侧 **「专家·技能·连接器 → 连接器 → 自定义连接器」**(若列表未刷新,点右上「添加 MCP → 保存 → 返回 MCP 列表」),点击 `zenmcp` 旁的 **「信任」** 看到绿点后,点击 **「新建任务」** 发送 **「检查我的 ZenMCP 账户状态」** 即可开始创作。
137
+
138
+ ### 场景 B2:SuperOne / Claude Code / Codex 等已自动写好用户级配置的软件
139
+
140
+ > **ZenMCP 已自动安装并配置完成**(核心组件、用户级全局配置、平台 Key 与创作技能均已就绪)。
141
+ >
142
+ > **下一步:** 请**新开一个会话**(或重启当前软件),发送 **「检查我的 ZenMCP 账户状态」** 即可开始使用。
143
+
144
+ ### 场景 C:当前对话已挂载 `zenmcp` 工具(调用 `account_status` 成功后)
145
+
146
+ 直接回复一句 **「ZenMCP 已安装并连通成功!」**,随后展示 `account_status` 返回的积分余额与「可以这样说」创作示例(可用积分为 0 时附一句前往 https://zenaigc.com/console 充值的提示)。
@@ -1,3 +1,3 @@
1
1
  export { inspectImage, validateAsset, ingestAsset, normalizeImage, setAssetAttributes, approveAsset } from "./images.js";
2
2
  export { composeReference, GatewayImageGenerator } from "./generator.js";
3
- export { ModelLibrary } from "./model-library.js";
3
+ export { ModelLibrary, MODEL_REF_LABEL_PATTERN } from "./model-library.js";
@@ -1,5 +1,5 @@
1
1
  import { constants } from "node:fs";
2
- import { copyFile, mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
2
+ import { copyFile, link, mkdir, open, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
3
3
  import { randomUUID } from "node:crypto";
4
4
  import { join } from "node:path";
5
5
  import { z } from "zod";
@@ -7,11 +7,60 @@ import { parseJob, SHA256_PATTERN } from "../core/schema.js";
7
7
  import { sha256File } from "../core/hash.js";
8
8
  import { ingestAsset } from "./images.js";
9
9
  import { child, directory, safeId } from "./files.js";
10
+ export const MODEL_REF_LABEL_PATTERN = /^[a-z0-9][a-z0-9_-]{0,63}$/;
11
+ const IMAGE_EXT_REGEX = /\.(?:png|jpg|webp)$/;
12
+ export async function detectImageExtension(filePath) {
13
+ const fh = await open(filePath, "r");
14
+ try {
15
+ const buf = Buffer.alloc(16);
16
+ const { bytesRead } = await fh.read(buf, 0, 16, 0);
17
+ if (bytesRead >= 8 &&
18
+ buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4e && buf[3] === 0x47 &&
19
+ buf[4] === 0x0d && buf[5] === 0x0a && buf[6] === 0x1a && buf[7] === 0x0a) {
20
+ return "png";
21
+ }
22
+ if (bytesRead >= 3 && buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff) {
23
+ return "jpg";
24
+ }
25
+ if (bytesRead >= 12 &&
26
+ buf.subarray(0, 4).toString("ascii") === "RIFF" &&
27
+ buf.subarray(8, 12).toString("ascii") === "WEBP") {
28
+ return "webp";
29
+ }
30
+ throw new Error("unsupported_image_format");
31
+ }
32
+ finally {
33
+ await fh.close();
34
+ }
35
+ }
36
+ const fileSlot = (baseName, requireExtension = false) => z.strictObject({
37
+ path: z.string().regex(new RegExp(`^${baseName}${requireExtension ? "\\.(?:png|jpg|webp)" : "(?:\\.(?:png|jpg|webp))?"}$`)),
38
+ sha256: z.string().regex(SHA256_PATTERN),
39
+ });
40
+ const referenceSlotSchema = z.strictObject({
41
+ label: z.string().regex(MODEL_REF_LABEL_PATTERN),
42
+ path: z.string().regex(/^ref-[a-z0-9][a-z0-9_-]{0,63}(?:\.(?:png|jpg|webp))?$/),
43
+ sha256: z.string().regex(SHA256_PATTERN),
44
+ }).refine(slot => slot.path.replace(IMAGE_EXT_REGEX, "") === `ref-${slot.label}`, "reference path must match ref-<label>");
10
45
  const modelSchema = z.strictObject({
11
46
  id: z.string(), name: z.string().min(1), version: z.number().int().positive(), description: z.string(),
12
- original: z.strictObject({ path: z.literal("original"), sha256: z.string().regex(SHA256_PATTERN) }),
13
- identity: z.strictObject({ path: z.literal("identity"), sha256: z.string().regex(SHA256_PATTERN) }),
47
+ original: fileSlot("original"),
48
+ identity: fileSlot("identity"),
49
+ preview: fileSlot("preview-sheet", true).optional(),
50
+ notes: z.string().optional(),
51
+ references: z.array(referenceSlotSchema).max(16).optional(),
52
+ }).superRefine((model, ctx) => {
53
+ const seen = new Set();
54
+ model.references?.forEach((ref, index) => {
55
+ if (seen.has(ref.label)) {
56
+ ctx.addIssue({ code: "custom", path: ["references", index, "label"], message: `duplicate reference label ${ref.label}` });
57
+ }
58
+ seen.add(ref.label);
59
+ });
14
60
  });
61
+ function normalizeQuery(text) {
62
+ return text.trim().toLowerCase().replace(/[\s\p{P}\p{S}]+/gu, "");
63
+ }
15
64
  export class ModelLibrary {
16
65
  root;
17
66
  constructor(root) {
@@ -20,22 +69,50 @@ export class ModelLibrary {
20
69
  /** Explicit user action only. Every version is immutable; model.json points to latest. */
21
70
  async save(input) {
22
71
  safeId(input.id);
72
+ if (input.references && input.references.length > 16)
73
+ throw new Error("too_many_references");
74
+ const seenLabels = new Set();
75
+ for (const ref of input.references ?? []) {
76
+ if (!MODEL_REF_LABEL_PATTERN.test(ref.label))
77
+ throw new Error(`invalid_reference_label: ${ref.label}`);
78
+ if (seenLabels.has(ref.label))
79
+ throw new Error(`duplicate_reference_label: ${ref.label}`);
80
+ seenLabels.add(ref.label);
81
+ }
23
82
  await mkdir(this.root, { recursive: true });
24
83
  const modelDir = await directory(this.root, "models", input.id);
25
84
  const manifest = await child(modelDir, "model.json");
26
85
  const versions = await directory(modelDir, "versions");
27
86
  const numbers = (await readdir(versions)).filter(name => /^[1-9]\d*$/.test(name)).map(Number);
28
87
  const version = Math.max(0, ...numbers) + 1;
29
- const record = modelSchema.parse({ id: input.id, name: input.name, description: input.description, version,
30
- original: { path: "original", sha256: await sha256File(input.originalImage) },
31
- identity: { path: "identity", sha256: await sha256File(input.identityImage) } });
32
88
  const stage = await directory(modelDir, `stage-${randomUUID()}`);
33
89
  try {
34
- await copyFile(input.originalImage, join(stage, "original"), constants.COPYFILE_EXCL);
35
- await copyFile(input.identityImage, join(stage, "identity"), constants.COPYFILE_EXCL);
36
- // Hash the copied bytes, so concurrent source edits cannot invalidate the manifest.
37
- record.original.sha256 = await sha256File(join(stage, "original"));
38
- record.identity.sha256 = await sha256File(join(stage, "identity"));
90
+ const stageSlot = async (src, baseName) => {
91
+ const ext = await detectImageExtension(src);
92
+ const slotName = `${baseName}.${ext}`;
93
+ const dest = join(stage, slotName);
94
+ await copyFile(src, dest, constants.COPYFILE_EXCL);
95
+ return { path: slotName, sha256: await sha256File(dest) };
96
+ };
97
+ const original = await stageSlot(input.originalImage, "original");
98
+ const identity = await stageSlot(input.identityImage, "identity");
99
+ const preview = input.previewImage ? await stageSlot(input.previewImage, "preview-sheet") : undefined;
100
+ const references = [];
101
+ for (const ref of input.references ?? []) {
102
+ const staged = await stageSlot(ref.image, `ref-${ref.label}`);
103
+ references.push({ label: ref.label, path: staged.path, sha256: staged.sha256 });
104
+ }
105
+ const record = modelSchema.parse({
106
+ id: input.id,
107
+ name: input.name,
108
+ description: input.description,
109
+ version,
110
+ original,
111
+ identity,
112
+ ...(preview ? { preview } : {}),
113
+ ...(input.notes !== undefined ? { notes: input.notes } : {}),
114
+ ...(references.length ? { references } : {}),
115
+ });
39
116
  await writeFile(join(stage, "model.json"), JSON.stringify(record, null, 2), { flag: "wx" });
40
117
  const destination = await child(versions, String(version));
41
118
  await mkdir(destination); // Reserve this version; a concurrent save must fail, never replace it.
@@ -70,6 +147,73 @@ export class ModelLibrary {
70
147
  throw new Error("model version mismatch");
71
148
  return record;
72
149
  }
150
+ async list() {
151
+ const modelsRoot = join(this.root, "models");
152
+ const entries = await readdir(modelsRoot, { withFileTypes: true }).catch(() => []);
153
+ const items = [];
154
+ for (const entry of entries) {
155
+ if (!entry.isDirectory())
156
+ continue;
157
+ try {
158
+ items.push(await this.get(entry.name));
159
+ }
160
+ catch { /* skip incomplete staging dirs */ }
161
+ }
162
+ return items.sort((a, b) => a.id.localeCompare(b.id));
163
+ }
164
+ async find(query) {
165
+ const all = await this.list();
166
+ const raw = query.trim();
167
+ if (!raw)
168
+ return all;
169
+ const exactId = all.filter(m => m.id.toLowerCase() === raw.toLowerCase());
170
+ if (exactId.length === 1)
171
+ return exactId;
172
+ const norm = normalizeQuery(raw);
173
+ if (!norm)
174
+ return [];
175
+ const exactName = all.filter(m => normalizeQuery(m.name) === norm || normalizeQuery(m.id) === norm);
176
+ if (exactName.length === 1)
177
+ return exactName;
178
+ return all.filter(m => [m.id, m.name, m.description, m.notes ?? ""].some(field => normalizeQuery(field).includes(norm)));
179
+ }
180
+ async resolvePaths(id, version) {
181
+ const record = await this.get(id, version);
182
+ const versionDir = await child(this.root, "models", id, "versions", String(record.version));
183
+ const verify = async (slot) => {
184
+ const p = await child(versionDir, slot.path);
185
+ if (await sha256File(p) !== slot.sha256)
186
+ throw new Error(`model ${slot.path} hash mismatch`);
187
+ if (IMAGE_EXT_REGEX.test(slot.path))
188
+ return p;
189
+ const ext = await detectImageExtension(p);
190
+ const extPath = await child(versionDir, `${slot.path}.${ext}`);
191
+ const existingSha = await sha256File(extPath).catch(() => null);
192
+ if (existingSha === slot.sha256)
193
+ return extPath;
194
+ if (existingSha !== null)
195
+ await rm(extPath, { force: true });
196
+ try {
197
+ await link(p, extPath);
198
+ }
199
+ catch {
200
+ await copyFile(p, extPath, constants.COPYFILE_EXCL);
201
+ }
202
+ return extPath;
203
+ };
204
+ const references = {};
205
+ for (const ref of record.references ?? []) {
206
+ references[ref.label] = await verify(ref);
207
+ }
208
+ const paths = {
209
+ versionDir,
210
+ original: await verify(record.original),
211
+ identity: await verify(record.identity),
212
+ preview: record.preview ? await verify(record.preview) : null,
213
+ references,
214
+ };
215
+ return { record, paths };
216
+ }
73
217
  async remove(id) {
74
218
  safeId(id);
75
219
  const dir = await child(this.root, "models", id);
@@ -77,11 +221,8 @@ export class ModelLibrary {
77
221
  await rm(dir, { recursive: true, force: true });
78
222
  }
79
223
  async useModel(job, id, version, jobDir = join(this.root, "jobs", job.job_id)) {
80
- const record = await this.get(id, version);
81
- const path = await child(this.root, "models", id, "versions", String(record.version), "identity");
82
- if (await sha256File(path) !== record.identity.sha256)
83
- throw new Error("model identity hash mismatch");
84
- const asset = await ingestAsset(jobDir, path, "identity");
224
+ const { paths } = await this.resolvePaths(id, version);
225
+ const asset = await ingestAsset(jobDir, paths.identity, "identity");
85
226
  return parseJob({ ...job, assets: [...job.assets, asset] });
86
227
  }
87
228
  }
@@ -165,6 +165,7 @@ export const checkStatuses = [
165
165
  "error",
166
166
  ];
167
167
  export const checkResultSchema = strict({
168
+ stage: z.enum(["inspect", "conform", "effects", "mix", "export", "report"]).optional(),
168
169
  requirement: safeId.optional(),
169
170
  segment: safeId.optional(),
170
171
  check: nonEmpty,
File without changes
@@ -10,6 +10,30 @@ import { assertFontCoverage, advanceWidthEm } from './font.js';
10
10
  import { validateCheck } from './check.js';
11
11
  const exec = promisify(execFile);
12
12
  const FONT_SIZE_RATIO = 0.092;
13
+ const PRESETS = {
14
+ 'pop-title': { ratio: FONT_SIZE_RATIO, defaultY: 0.52 },
15
+ 'hero-title': { ratio: 0.088, defaultY: 0.12 },
16
+ 'top-tag': { ratio: 0.050, defaultY: 0.10 },
17
+ 'voice-caption': { ratio: 0.046, defaultY: 0.84 },
18
+ };
19
+ function stripHighlightBraces(line) {
20
+ let out = '';
21
+ let hl = false;
22
+ for (const ch of Array.from(line)) {
23
+ if (ch === '{' && !hl) {
24
+ hl = true;
25
+ continue;
26
+ }
27
+ if (ch === '}' && hl) {
28
+ hl = false;
29
+ continue;
30
+ }
31
+ out += ch;
32
+ }
33
+ if (hl)
34
+ throw new Error('pop_title_lines: unclosed {highlight} brace');
35
+ return out;
36
+ }
13
37
  const template = fileURLToPath(new URL('../../templates/pop-title/', import.meta.url));
14
38
  const cli = join(dirname(createRequire(import.meta.url).resolve('hyperframes/package.json')), 'bin/hyperframes.mjs');
15
39
  const SAFE_ENV_KEYS = [
@@ -99,13 +123,15 @@ export class PopTitleRenderer {
99
123
  if (failed.length)
100
124
  throw new Error(`effect_runtime_unavailable: ${failed.join(', ')}`);
101
125
  }
102
- async author(layers) {
103
- const source = this.job.storyboard.source;
126
+ async author(layers, canvasOverride) {
127
+ const rawSource = this.job.storyboard.source;
128
+ const source = canvasOverride ? { ...rawSource, width: canvasOverride.width, height: canvasOverride.height } : rawSource;
104
129
  const cuts = [0, ...cutsOf(this.job.storyboard), source.frames];
105
130
  const font = await readFile(join(template, 'vendor/NotoSansCJKsc-Bold.otf')).catch(() => { throw new Error('effect_font_unavailable'); });
106
131
  return layers.map((input, effect) => {
107
132
  const layer = effectSchema.parse(input);
108
- if (layer.template !== 'pop-title')
133
+ const preset = PRESETS[layer.template];
134
+ if (!preset)
109
135
  throw new Error(`unsupported_effect_template: ${layer.template}`);
110
136
  const start_frame = cuts[layer.start_cut];
111
137
  const end_frame = cuts[layer.end_cut];
@@ -114,23 +140,32 @@ export class PopTitleRenderer {
114
140
  const lines = layer.slots.lines;
115
141
  if (!Array.isArray(lines) || lines.length < 1 || lines.length > 2 || !lines.every(l => typeof l === 'string' && l.length > 0))
116
142
  throw new Error('pop_title_lines: expected one or two nonempty strings');
117
- if (Object.keys(layer.slots).some(k => k !== 'lines') || Object.keys(layer.assets).length || Object.keys(layer.style).some(k => !['position', 'color'].includes(k)))
143
+ if (Object.keys(layer.slots).some(k => k !== 'lines') || Object.keys(layer.assets).length || Object.keys(layer.style).some(k => !['position', 'color', 'highlight_color', 'font_scale'].includes(k)))
118
144
  throw new Error('unsupported_pop_title_parameter');
119
- assertFontCoverage(font, lines.join(''));
145
+ const plainLines = lines.map(stripHighlightBraces);
146
+ if (plainLines.some(l => l.length === 0))
147
+ throw new Error('pop_title_lines: expected one or two nonempty strings');
148
+ assertFontCoverage(font, plainLines.join(''));
120
149
  const position = layer.style.position;
121
150
  if (position !== undefined && (!position || typeof position !== 'object' || Array.isArray(position) || Object.keys(position).some(k => !['x', 'y'].includes(k))))
122
151
  throw new Error('pop_title_position: expected {x, y}');
123
152
  const x = position?.x ?? 0.5;
124
- const y = position?.y ?? 0.52;
153
+ const y = position?.y ?? preset.defaultY;
125
154
  if (typeof x !== 'number' || typeof y !== 'number' || !Number.isFinite(x) || !Number.isFinite(y) || x < 0 || x > 1 || y < 0 || y > 1)
126
155
  throw new Error('pop_title_position: expected fractions in 0..1');
127
156
  const color = layer.style.color ?? '#ffffff';
128
157
  if (typeof color !== 'string' || !/^#[\da-f]{6}$/i.test(color))
129
158
  throw new Error('pop_title_color: expected #RRGGBB');
130
- const size = Math.round(source.width * FONT_SIZE_RATIO);
159
+ const highlight_color = layer.style.highlight_color ?? '#ffe14d';
160
+ if (typeof highlight_color !== 'string' || !/^#[\da-f]{6}$/i.test(highlight_color))
161
+ throw new Error('pop_title_color: expected #RRGGBB');
162
+ const font_scale = layer.style.font_scale ?? 1;
163
+ if (typeof font_scale !== 'number' || !Number.isFinite(font_scale) || font_scale < 0.3 || font_scale > 1.5)
164
+ throw new Error('pop_title_scale: expected 0.3..1.5');
165
+ const size = Math.max(12, Math.round(source.width * preset.ratio * font_scale));
131
166
  // Chrome rounds each inline-block advance to 1/64px. Do not spend check's 2px tolerance.
132
- const width = Math.max(...lines.map(line => advanceWidthEm(font, line) * size + Array.from(line).length / 64));
133
- const height = lines.length * Math.ceil(size * 1.08 * 64) / 64;
167
+ const width = Math.max(...plainLines.map(line => advanceWidthEm(font, line) * size + Array.from(line).length / 64));
168
+ const height = plainLines.length * Math.ceil(size * 1.08 * 64) / 64;
134
169
  // Bundled font Range boxes extend beyond 1.08 line boxes; calibrated at 29/99px.
135
170
  // .224em bounds that extension, .04em is half the stroke, shadow adds .08/.1em.
136
171
  const left = size * 0.04 + 1;
@@ -141,18 +176,24 @@ export class PopTitleRenderer {
141
176
  y * source.height - height / 2 < top || (1 - y) * source.height - height / 2 < bottom) {
142
177
  throw new Error('pop_title_overflow');
143
178
  }
144
- return { effect, start_frame, end_frame, lines, x, y, color };
179
+ return { effect, template: layer.template, start_frame, end_frame, lines, x, y, color, highlight_color, size };
145
180
  });
146
181
  }
147
182
  async validate(layers) {
148
183
  await this.author(layers);
149
184
  }
150
185
  async render(base, layers, output) {
151
- const authored = await this.author(layers);
152
- const source = this.job.storyboard.source;
186
+ let authored = await this.author(layers);
187
+ const rawSource = this.job.storyboard.source;
153
188
  const facts = await probe(base);
154
- if (facts.frames !== source.frames || facts.fps.num * source.fps.den !== source.fps.num * facts.fps.den)
189
+ if (facts.frames !== rawSource.frames || facts.fps.num * rawSource.fps.den !== rawSource.fps.num * facts.fps.den)
155
190
  throw new Error('effect_base_timeline_mismatch');
191
+ const source = facts.width * rawSource.height === facts.height * rawSource.width
192
+ ? { ...rawSource, width: facts.width, height: facts.height }
193
+ : rawSource;
194
+ if (source.width !== rawSource.width || source.height !== rawSource.height) {
195
+ authored = await this.author(layers, source);
196
+ }
156
197
  output = resolve(output);
157
198
  await mkdir(dirname(output), { recursive: true });
158
199
  const work = await mkdtemp(join(dirname(output), '.pop-title-'));