Release v0.28.0: active timelines, app-created projects and client fixes

.github/workflows/ci.yml

@@ -92,3 +92,27 @@ jobs:
           cache: npm
       - run: npm ci
       - run: npm test
+
+  python-client:
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            python: '3.9'
+          - os: ubuntu-latest
+            python: '3.14'
+          - os: windows-latest
+            python: '3.9'
+          - os: windows-latest
+            python: '3.14'
+          - os: macos-latest
+            python: '3.14'
+    runs-on: ${{ matrix.os }}
+    name: Python client (${{ matrix.os }}, ${{ matrix.python }})
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python }}
+      - run: python -m unittest discover -s python/tests -v

CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to capcut-cli are documented here. The format follows [Keep
 
 ## [Unreleased]
 
+## [0.28.0] — 2026-10-03
+
+### Added
+
+- `--active-timeline` explicitly follows a validated `Timelines/project.json` pointer on app builds without a verified storage fixture (#50). Invalid, deleted, symlinked or conflicting selected timelines are refused; normal defaults and write guards remain unchanged. Writes keep root and active IDs and preserve other timelines.
+- `compile --into <project>` populates an existing empty project created in CapCut (#52). It preserves project identity, per-document app markers and unknown settings, stages content-correct media, and commits imported-media registration with timeline writes. Failed copies and commits clean up only newly owned assets; the shared store index is never rewritten. `--check`, `--plan` and `--dry-run` validate both spec and destination without writing. Nested layouts require active selection. Desktop acceptance on these opt-in paths remains unverified.
+
+- `describe --compact` emits a small command discovery index with names, summaries, usage, and write status. `describe --command <name>` returns complete contracts for selected commands; repeat the flag for several names. The full v2 command contract remains the default. Python client v0.1.3 forwards these options through `capcut.describe(compact=True, command="compile")`.
+
+### Fixed
+
+- Python client v0.1.3 parses quoted Windows `CAPCUT_CLI` paths without retaining surrounding quotes or losing backslashes. Escaped quotes, trailing backslashes, and empty arguments follow Windows argv quoting; malformed quotes fail before spawning a process. POSIX command quoting and shell-free execution remain unchanged. Python client regression tests now run on Linux, macOS, and Windows, including Python 3.9 and 3.14.
+
 ## [0.27.0] — 2026-10-03
 
 ### Added

README.md

@@ -105,9 +105,20 @@ The host reads a draft and passes its JSON as tool input. The component itself h
 
 ## Release notes
 
+> **New in v0.28.0:** opt-in active-timeline selection; compilation into empty app-created projects; compact command discovery and selection by name for agents; Windows command-path quoting fixed in Python client v0.1.3; and Python client CI on Linux, macOS, and Windows. Full details in the [changelog](./CHANGELOG.md).
+
 > **New in v0.27.0:** content-safe media replacement; automatic import registration after replacement and relink; recursive, ambiguity-safe relinking; exact fractional-second compile boundaries; operation preflight and failed-build cleanup; payload-bound queue IDs; canonical project locks; bounded queue results; and local OTIO file/relative references. Full details in the [changelog](./CHANGELOG.md).
 
-> **Fixed in v0.26.1:** ratio-only compile canvases and full source-media durations; JSON-escaped Windows fixture redaction with automatic leak verification; and active-timeline edits on the fixture-backed CapCut 8.7.0 Windows layout. A patched desktop round-trip remains pending. Full details in the [changelog](./CHANGELOG.md).
+For an existing nested project, use `capcut diagnose <project> --active-timeline` to inspect the selected document before editing. The opt-in follows the pointer on unverified builds and refuses invalid or conflicting selected documents; it does not bypass write guards.
+
+To populate a project that CapCut already owns, create an empty project in the app and quit CapCut, then run:
+
+```sh
+capcut compile spec.json --into /path/to/app-created-project --active-timeline --check
+capcut compile spec.json --into /path/to/app-created-project --active-timeline
+```
+
+Omit `--active-timeline` for a flat project without `Timelines/`. Every root and active mirror must be empty. The project keeps its name and registration; canvas and frame rate change only when supplied in the spec. Imported media is staged under the project, with registration and timeline backups committed together. Reopen, save, close and reopen in CapCut to check that edits persist. Automated safety tests cover these paths; desktop acceptance on your app build remains unverified.
 
 ## Built with capcut-cli
 
@@ -136,6 +147,8 @@ JSON by default (pipe to `jq`); add `-H` for a human-readable table. Pass `--jia
 | **Long-form → short** | `cut` · `detect-scenes` (ffmpeg scene-cut detection) · `detect-silence` · `detect-retakes` (repeated takes) |
 | **Automation** | `serve` (stateless JSONL runner) · `migrate` · `doctor` · `sync-timelines` (8.7 mirror repair) |
 
+`capcut describe --compact` lists command names, summaries, usage, and write status. Fetch a complete contract with `capcut describe --command compile`; repeat `--command` for several commands. Plain `capcut describe` still emits the full registry.
+
 **Full reference** for every command, option, and exit code: **[docs/command-reference.md](./docs/command-reference.md)** (简体中文: [docs/command-reference.zh-CN.md](./docs/command-reference.zh-CN.md)).
 
 ## Sponsor

README.zh-CN.md

@@ -82,9 +82,9 @@ Claude Code 也可以把它作为插件加载：
 
 ## 发布说明
 
-> **v0.27.0 新增：** 按文件内容安全替换媒体；替换和重链接后自动更新媒体导入登记；递归搜索并报告同名歧义；精确处理小数秒时间边界；编译前校验操作并清理失败输出；将队列 ID 绑定到任务参数；统一项目锁；限制队列输出；以及解析 OTIO 的本地文件 URL 和相对路径。完整说明见[更新日志](./CHANGELOG.md)。
+> **v0.28.0 新增：** 显式选择活动时间线、向应用创建的空项目编译，以及精简的命令发现索引与按命令名筛选；Python 客户端 v0.1.3 修复 Windows 命令路径的引号解析，并在 Linux、macOS、Windows 上运行客户端 CI。详见 [更新日志](./CHANGELOG.md)。
 
-> **v0.26.1 修复：** 仅指定比例的编译画布与完整源媒体时长；对 JSON 转义的 Windows 路径进行 fixture 脱敏并自动检查泄漏；以及基于真实 fixture 的 CapCut 8.7.0 Windows 活动时间线编辑。修复后的桌面应用往返验证仍待完成。完整说明见[更新日志](./CHANGELOG.md)。
+> **v0.27.0 新增：** 按文件内容安全替换媒体；替换和重链接后自动更新媒体导入登记；递归搜索并报告同名歧义；精确处理小数秒时间边界；编译前校验操作并清理失败输出；将队列 ID 绑定到任务参数；统一项目锁；限制队列输出；以及解析 OTIO 的本地文件 URL 和相对路径。完整说明见[更新日志](./CHANGELOG.md)。
 
 ## 使用 capcut-cli 构建
 
@@ -95,6 +95,17 @@ Claude Code 也可以把它作为插件加载：
 项目描述须经其维护者确认。收录不代表背书或关联。
 
 
+使用 `capcut diagnose <project> --active-timeline` 检查嵌套项目中的活动时间线。此显式选项依据 `Timelines/project.json` 选择文档；无效、已删除、符号链接或相互冲突的文档会被拒绝，现有写入保护仍然生效。
+
+若要填充 CapCut 已创建的项目，先在应用中创建空项目并退出应用，然后运行：
+
+```sh
+capcut compile spec.json --into /path/to/app-created-project --active-timeline --check
+capcut compile spec.json --into /path/to/app-created-project --active-timeline
+```
+
+没有 `Timelines/` 的平面项目请省略 `--active-timeline`。所有根目录和活动时间线镜像必须为空；保留项目名称、身份和注册信息，只有 spec 明确指定时才修改画布和帧率。媒体写入项目的 assets 目录，时间线与媒体注册信息一起备份和提交。`--check`、`--plan`、`--dry-run` 均不写入。请在应用中打开、保存、关闭并重新打开，确认编辑保留；自动测试覆盖写入安全性，尚未验证此路径在各应用版本中的桌面往返行为。
+
 ## 常用命令
 
 默认输出 JSON（可管道给 `jq`）；加 `-H` 显示人类可读表格。加 `--jianying` 使用剪映枚举命名空间。运行 `capcut <command> --help` 查看完整参数。
@@ -113,6 +124,8 @@ Claude Code 也可以把它作为插件加载：
 | **长视频切短** | `cut` · `detect-scenes`（ffmpeg 场景切点检测）· `detect-silence` · `detect-retakes`（重复口播段落）|
 | **自动化** | `serve`（无状态 JSONL 执行器）· `migrate` · `doctor` · `sync-timelines`（8.7 时间线镜像修复）|
 
+`capcut describe --compact` 列出命令名、简介、用法和是否写入。`capcut describe --command compile` 返回指定命令的完整契约；重复 `--command` 可选择多个命令。不带选项的 `capcut describe` 仍输出完整注册表。
+
 **完整命令参考**（每个命令、参数与退出码）：**[docs/command-reference.zh-CN.md](./docs/command-reference.zh-CN.md)**（[英文原版](./docs/command-reference.md)）。
 
 ## 赞助