ace

Files (1)

• SKILL.md

SKILL.md (first lines)

# ACE 模式（总入口）

> **ACE Studio = 第三方宿主**：它**不走我们的桥**（没有心跳文件、没有 op、没有侧栏面板），
> 一切通过它自己的 **`acestudio-cli`** 或 **MCP server**（63 个工具，`<域>_read` / `<域>_edit`，与 CLI **同一套 surface**）。
> （另有**我们自己的 3 个 ACE 工具** `ace_state` / `ace_cli` / `acep` —— 那是 AKDAgent 的便利层，**与官方那套无关**，见 §3b。）
> ⚠️ 所以：**别让 ACE 用户"去跑 `AKDAgentBridge.lua`"**，也别用 `-sv`/`-ix` 那套判据找它的桥。
> 本技能是**入口**：它不重复官方技能的内容，只负责"**该看哪个**"。

## 1. 进 ACE 模式的第一件事：确认它在线

```powershell
$cli = "$env:ProgramFiles\ACE Studio\acestudio-cli.exe"
& $cli project info --json          # exit 0 = 在线；exit 3 = 桥不可达（ACE 没开 / 没开 External Agent Access）
```

- 快速判据：桥握手文件 `%LOCALAPPDATA%\Timedomain\ACE Studio\mcp-bridge.json` **在不在**（ACE 关掉它会消失）。
- **在 ACE 里开 Agent 连接是用户侧的事**（App 右下角 **Connect to Agents**）—— 我们不能替他开；探到 exit 3 就这么告诉他。
- ⚠️ 探到了也**不等于**有工程：没工程时命令会回 `NO_PROJECT_OPEN`，要请用户先开/建一个。
- **CLI 路径别硬编码**（用户可能装到别的盘）：可靠顺序 = **注册表** →
  `HKLM\SOFTWARE\{WOW6432Node}\Microsoft\Windows\CurrentVersion\Uninstall\*` 里找 `Publisher = 'Timedomain Inc.'` 且 `DisplayName like 'ACE Studio*'`
  （⚠️ **DisplayName 会本地化** —— 中文机上是「ACE Studio 版本 2.1.8」，**别精确匹配英文**）→ 取 `InstallLocation`（实测 `C:\Program Files\ACE Studio\`）→ 拼 `\acestudio-cli.exe`；
  再兜底 `%ProgramFiles%` / `%ProgramFiles(x86)%` / `%LOCALAPPDATA%`，最后**问用户**。
- **能力探测用 `--version`**（能用，别猜）—— **它同时兼作在线探测**（第 4 行就是连接状态）：
  ```
  acestudio-cli --version
  acestudio-cli 0.17.0
  Built for ACE Studio 2.1.8
  Remote Control Bridge Surface 17.1
  Connected to ACE Studio 2.1.8 (surface 17.1)     ← 这一行在 = 在线；不在/报错 = 桥不可达
  ```
  ⇒ 版本与本文不符时**按能力降级**，别假设命令都在。
  ⚠️ 读输出时**别只取前 3 行**（我们就是这么把连接那行截掉过一次）。

## 2. 分工表：该接哪一份（**按需加载，别全塞进来**）

| 你要做的事 | 加载/查这个 |
|---|---|
| 连不上、不知道 CLI/MCP 在哪、怎么在 App 里开 Agent 连接 | 官方 **`ace-studio-setup`** |
| ACE 有哪些功能、某个功能是什么、什么时候用 | 官方 **`ace-studio-features`** |
| 跨多步的活儿该怎么排顺序（生成歌 / 从音频返工 / 出谱） | 官方 **`ace-studio-workflows`** |
| 驱动第三方 VST3/AU 或内置效果（含用 computer use 操作插件界面） | 官方 **`ace-studio-audio-plugins`** |
| **调参数**（人声参数曲线、层、尺度、CC/pitchbend、怎么写） | 我们自己的 **`ace-params`**（真机花名册 + 写法规格） |
| **直接读写 `.acep` 工程文件**（容器/CBOR 格式、手改、音高曲线、ACE 认不认） | 我们自己的 **`acep`**（ACEP2 + CBOR + 六步安全写入 + ACE 加载复查行为） |
| 与 Synthesizer V / Instrument X 的**参数对照与换算** | **`akdagent-playbook`** §四 的「第三方宿主 ACE Studio」段 |
| 任何命令的**签名与枚举**（权威） | 见 **§2b**（本地 `help` 树 / `get_docs`） |

### 2b. 文档去哪找（**权威顺序** —— 别在别处瞎找）

1. **本地 `help` 树 = 权威，也是唯一完整的**（CLI 自带、随 ACE 一起装；**没有对应的网站**）：

   ```powershell
   & $cli help                      # 总览：34 个域 + 18 个 topic
   & $cli help vocalparam write     # 单条命令的完整文档
   & $cli help curve-encoding       # topic：error-codes / guardrails / tick-coordinates / pitch-values / jobs …
   & $cli help --search "dynamic"   # 命令 + topic 全文正则搜
   ```

   ⇒ **MCP 侧是同一份**：`get_docs {"path":"vocalparam write"}` —— 不是另一套文档。
   ⚠️ 别去找 `acestudio-cli` 的文档站点，**不存在**（`help` 里唯一的外链是 changelog 提的 keepachangelog 格式说明）。
2. **官方 agent skills 仓**（know-how 层；CLI 在 `help` 末尾自己指过去）：
   `https://github.com/BeatMagic/acestudio_agent_plugin` —— 我们的 `ace-studio-setup` / `-features` / `-workflows` / `-audio-plugins`
   就是它的 `skills/`（MIT，逐字节同版本）。
3. **给人看的用户手册**（GitBook）：`https://docs.acestudio.ai` —— 讲的是 **UI 层**（面板上有什么、怎么操作）。
   ⚠️ **层模型 / `scale` / `valueRange` / `vocalControlRoute` 这类实现细节它没有** ⇒ 那些只在 ① 里。
   ⇒ 一句话：**"面板上有没有这个按钮"看 ③ · "这个数是什么量纲、能不能写"看 ①。**

## 3. 工具面（两种走法，选一种）

| 走法 | 前提 | 说明 |
|---|---|---|
| **CLI（默认首选）** | ACE 装上就有 | `acestudio-cli <域> <子命令>`；文档自带（`help` / `help --search`） |
| MCP（可选） | 在 DSH profile 里注册 `ace-mcp-server.exe`（`serverName: ace-studio`） | 工具名会是 `mcp__ace-studio__<域>_read/_edit`；**代价**：多一个 ~12MB 进程 + 63 个工具进上下文 |

- **不注册也能干活**（CLI 路线已实测可用）——要不要注册问用户，别默认加。
- 两套 surface 的工具名/子命令**一一对应**，所以文档查一次两边都适用。
  实测核对（2026-10-03）：各域 `_read`+`_edit` 的 `subcommand` 总数 = CLI 同域命令数，**322 = 322、34/34 个域完全相同**
  ⇒ 注册 MCP **不会多也不会少任何操作**，只是换个调用面。
- ⚠️ **但 MCP 是"薄壳"，不是另一份文档**：**62/63** 个工具只有 `{subcommand, arguments}`，`arguments` 是**自由 object**；
  真正的参数细节只能**按 `subcommand` 去 `get_docs`（= CLI help 原文）查**
  ⇒ **参数权威始终在 CLI 的 help 树**（见 §2b），这也是默认首选 CLI 的理由。

### 3b. 我们自己的 ACE MCP 工具组（**2026-10-05 加，与官方 `ace-mcp-server` 无关**）

AKDAgent 的 MCP server（`server/src/ace/`）现在挂了 **3 个 ACE 工具**，把"CLI + 文件工具"两条路都包起来：

| 工具 | 干什么 | 为什么有它（不是多此一举的地方） |
|---|---|---|
| **`ace_state`** | 开工自检：ACE 在不在线、当前工程名/**路径**/`dirty`/`isTempProject`、CLI 位置、6 个技能脚本是否就位 | 一条命令替代"CLI 探测 + 脚本路径探测"；⚠️ 它内部走 **`project dirty`**（`project info` **没有** path/dirty） |
| **`ace_cli`** | 跑任意 `acestudio-cli` 子命令（**参数传数组、不经 shell**） | 绕开 PowerShell 的**引号/BOM/编码**三坑（`--points '[[0,0.5]]'` 这类 JSON 参数在 PS 5.1 下极易被吃掉）；自动补 `--json` 并解析 |
| **`acep`** | 跑 `skills/acep/scripts/*`（`acep` / `lane-report` / `tree-diff` / `lyric-tones` / `lane-poke` / `f0-contour`），**带写护栏** | MCP 加得上、裸脚本加不上的东西：**`--in-place` 默认拒**（把 `acep` 技能那套「只写副本」纪律变成可执行版）；允许时若 ACE 正打开该文件且 `dirty:true` 再拒一次 |

- ⚠️ **与官方 MCP 的边界**：官方那套（`mcp__ace-studio__*`，63 个薄壳）是**它自己**的 surface，与 CLI 一一对应；
  我们这 3 个是**AKDAgent 侧**的便利层 —— 两者可以并存，**都代替不了 `help` 树**（参数细节仍查 §2b）。
- ⚠️ **不是必需**：这 3 个工具只是把上面两条路包了一层。**没有它们也能干活**（一样是跑 CLI / 跑脚本）。
- ⚠️ MCP server 改完要**重启**才生效（跑的是 `server/dist`）⇒ 新工具没出现先想到这个。

## 4. 常见任务路线图（先读后写）

1. **看现状**：`project info` → `track list` → `clip list --track-index <N>` →（要看音符）`note get --note-uuid …`
   · 选区/光标：`selection get` / `caret get` · 编辑器状态：`editor status`
2. **加内容**：`track create --type <sing|instrument|genericMidi|audio|video|marker>` →
   `sound-source load`（或 `voice load`）→ `clip create --type … --pos/--dur` → `note add` / `lyric fill` / `chord insert`
3. **生成类**（Inspire Me / Music Enhancer）：它们是 **staged job** ⇒ `generative` 起 → `job list` / `job wait` → `job results` / `job place`
   ⚠️ 要额度：**`generative` 可能要 credits**（`CREDIT_INSUFFICIENT`），别当成失败重试。
4. **出片**：`export audio` / `export video`（**也是 job**）；⚠️ `export vocal-sample` **要 membership**（`MEMBERSHIP_REQUIRED`）。
   ⚠️ **CLI 没有"合成"命令**；要逼它真渲染一次就用 `export audio`（起 `export-audio` 作业 → `job wait <id>`），`project synthesis-status` 只报"当前有没有在跑"。
   ⚠️ 渲染**不会**把结果（分析 / 音素时长 / 音高）写回 `.acep`：实测渲染前后文件字节一致 ⇒ **文件里读得到的只有"被写过的数据"**。
5. **调声**：见 **`ace-params`**（先 `vocalparam layers` 读 `available`/`scale`/`shape`，再 `read`，最后 `write`）。
6. **换音色/插件/效果**：`voice list|load` · `sound-source get|set` · `instrument` / `fx` / `audio_plugin`（插件参数 `set-param` 用 `--value`(0..1) 或 `--display`(插件自己的文本)）。

### 4a. 能力边界总表：**CLI 能做 / 只能改文件 / 都做不了**（2026-10-05 实测汇总）

> 这张表是"遇到需求先判路线"用的。**能走 CLI 就别走文件**（CLI 有撤销、有指纹、ACE 立即认账）；
> 文件路线只在 CLI 没开放的地方用，且它有代价：**改完要 ACE 重开**（重载有明显提示）+ 没有撤销（只有你留的副本）。

| 需求 | CLI | 文件（`.acep`） | 备注 |
|---|---|---|---|
| 轨道 / 片段 / 音符 / 歌词 / 语言 / 音素拼写 | ✅ 全套（`track` `clip` `note` `lyric` `phoneme set`） | 也读得到 | — |
| **音素时长**（pin / 头尾辅音长度） | ✅ `phoneme move-boundary` · `set-consonant-timing` · `reset*` | 读得到，**写工具没做** | ⚠️ 换声库会**静默丢掉**另一种表示的时长（实测）；pin 的字节判据见 `acep` §2.4 |

From Akunda123/SVIXAGENT, MIT.

More from Akunda123/SVIXAGENT