diff --git a/.github/workflows/implementation.yml b/.github/workflows/implementation.yml index 402c926..e6a45d2 100644 --- a/.github/workflows/implementation.yml +++ b/.github/workflows/implementation.yml @@ -17,8 +17,5 @@ jobs: - uses: actions/setup-node@v4 with: node-version: '24.21.0' - - name: Runtime unit tests when present - run: | - if test -f package.json; then - npm test - fi + - name: Runtime unit tests + run: node --test ui/*.test.mjs diff --git a/README.en.md b/README.en.md deleted file mode 100644 index f8b7d50..0000000 --- a/README.en.md +++ /dev/null @@ -1,164 +0,0 @@ -# EffectCraft（动态图形） - -> Compositions, keyframes, expressions and tracking - -**Version**: 0.1.0-dev.20261018.3 · **License**: Apache-2.0 · **Skills**: 26 · **MCP server**: 1 - -[简体中文](README.md) · [Install](#installation) · [Quick start](#quick-start) · [Project layout](#project-layout) - -## Positioning - -Compositions, keyframes, expressions, cameras, masks and tracking. Layers, masks and render settings remain editable. - -This plugin belongs to the content-creation line and is for users who need an editable result, not a script or a flat image. - -## At a glance - -```text -assets / requirements / old drafts - │ - ▼ -EffectCraft（动态图形） skill (inspect → plan → execute → read back) - │ - ├── native CLI / MCP tools - └── MCP editor (in-browser review and local edits) - │ - ▼ -editable project + export + review -``` - -## Capabilities and boundaries - -| Capability | What it does | Boundary | -|---|---|---| -| Inspect | Read the current project and assets | No edits without authorization | -| Create | Build an editable structure from the goal | Facts and assets come from input | -| Edit | Change the requested scope only | Reopen after every edit | -| Export | Produce the target format and verify | A successful export is not correct layout | -| Review | Check against explicit criteria | Not a substitute for final human acceptance | - -## Architecture and core flow - -```text -Host / agent - │ invokes a skill - ▼ -skills/effectcraft-* ──► MCP editor / native CLI - │ - ▼ - editable project + export - │ - ▼ - read back, review, deliver -``` - -Rules: - -1. Inspect read-only, then plan, then execute. -2. Keep the original or a rollback version. -3. Reopen the export before trusting it. -4. Mark uncertain results for review; never replay automatically. - -## Compatibility - -| Item | Status | -|---|---| -| Host | Hosts with MCP Apps or a built-in browser | -| Node.js | 24+ (editor) | -| Platforms | Follow the actual package and release notes | - -## Installation - -```bash -codex plugin marketplace add partme-ai/full-aigc-plugins -codex plugin add effectcraft@full-aigc-plugins -``` - -Restart the host and start read-only. - -## Quick start - -1. Confirm goal, inputs, and delivery format. -2. Inspect the current project and list gaps. -3. Make one bounded change. -4. Reopen the output and verify structure and key content. -5. Complete visual or content review before delivery. - -## Configuration - -| Variable | Purpose | Default | -|---|---|---| -| `CRAFT_WORKSPACE_ROOT` | Workspace bound to the editor | current project | -| `CRAFT_EDITOR_UPDATE` | Set to `off` to skip the enhanced editor download | enabled | - -Never write secrets, tokens, or private paths into projects or configuration. - -## Extension contract - -New skills use the `effectcraft-` prefix, declare triggers and boundaries, operate through MCP or the pinned CLI, and reopen after every edit. - -## Retry, idempotency, and recovery - -- Inspect the current project after a failure. -- Do not replay operations with side effects. -- Retry with a new output path and keep the old receipt. - -## Data and state - -- Inputs are read-only. -- Outputs, exports, and temporary directories are separate. -- Confirm the file opens and content is complete before delivery. - -## Security - -- Do not upload unauthorized assets to third-party services. -- Redact sensitive content before delivery. -- On a suspected leak, rotate credentials before cleaning files. - -## Observability and operation - -Record command, output file, key structure, and review result; inspect at least one real output before delivery. - -## Development and verification - -```bash -node --test -python3 -m pytest -``` - -## Packaging and release - -Version matches manifests, marketplace, and tag; the ZIP root is `effectcraft-plugin`. - -## Upgrade and migration - -Back up projects before upgrading; keep older files openable; recheck structure and export after migration. - -## Troubleshooting - -| Symptom | Check | -|---|---| -| Project will not open | File integrity and version | -| Blank editor | Node.js version and workspace permissions | -| Export fails | Fonts, assets, output path | -| Result differs | Reopen and inspect | - -## Project layout - -```text -effectcraft-plugin/ -├── .zcode-plugin/ # ZCode manifest and UI surface -├── skills/ # 26 skills -├── ui/ # MCP Apps editor -├── commands/open.md # open-editor command -├── docs/ # architecture and verification -└── assets/ # icons and templates -``` - -## Contributing and support - -Include plugin version, host, input type, command, output file, and expected result. Do not attach sensitive assets. - -## License - -Apache-2.0. See [LICENSE](LICENSE). diff --git a/README.md b/README.md index 9b064c2..80b19c3 100644 --- a/README.md +++ b/README.md @@ -1,164 +1,193 @@ -# EffectCraft（动态图形） +# EffectCraft Use -> 合成、关键帧、表达式与跟踪，可编辑动效 +## Plugin marketplaces -**版本**：0.1.0-dev.20261018.3 · **许可证**：Apache-2.0 · **技能**：26 个 · **MCP 服务**：1 个 +This plugin belongs to **AIGC content creation**. -[English](README.en.md) · [安装](#安装) · [快速开始](#快速开始) · [项目结构](#项目结构) +| Category | Marketplace | Purpose | +| --- | --- | --- | +| Full-stack development | [Full Stack Plugins](https://github.com/partme-ai/full-stack-plugins) | Architecture and UI design, code understanding, quality checks, code review, workflow governance, and server operations | +| AIGC content creation | [Full AIGC Plugins](https://github.com/partme-ai/full-aigc-plugins) | Image, video, audio, music, 3D, and multimodal content creation | -## 项目定位 +![EffectCraft Use — motion graphics and composition](assets/official-logo.png) -合成、关键帧、表达式、摄像机、遮罩与跟踪；图层、遮罩与渲染设置完整保留。 +> Build editable `.ecproj` compositions — comps, text and shape layers, keyframes, expressions, cameras, masks, puppet pins and effects — then render previews or finished shots with alpha where you ask for it. -本插件属于内容创作线，面向需要直接得到可编辑成果、而不是一段脚本或图片的用户。 +[![Version](https://img.shields.io/badge/release-0.1.0--dev.20261018.4-1A73E8)](.codex-plugin/plugin.json) +[![Skills](https://img.shields.io/badge/skills-16-00A67E)](#skills) +[![MCP server](https://img.shields.io/badge/MCP%20server-1-00A67E)](#mcp-tools) +[![License](https://img.shields.io/badge/license-Apache--2.0-green)](LICENSE) -## 一眼看懂 +[English](README.md) | [简体中文](README.zh-CN.md) · [Install](#installation) · [Quick start](#quick-start) · [What you can build](#what-you-can-build) · [Skills](#skills) · [Troubleshooting](#troubleshooting) -```text -素材 / 需求 / 旧稿 - │ - ▼ -EffectCraft（动态图形） 技能（检查 → 计划 → 执行 → 回读） - │ - ├── 原生 CLI / MCP 工具 - └── MCP 编辑器（浏览器内查看与局部调整） - │ - ▼ -可编辑工程 + 导出文件 + 复核结果 -``` - -## 能力与边界 - -| 能力 | 说明 | 边界 | -|---|---|---| -| 检查 | 读取现有工程与素材状态 | 不修改未授权文件 | -| 创建 | 按目标生成可编辑结构 | 事实与素材需来自输入 | -| 编辑 | 局部修改并保留未涉及内容 | 修改后必须重新打开 | -| 导出 | 输出目标格式并核对 | 导出成功不等于版面正确 | -| 评审 | 按明确标准检查结果 | 不替代最终人工验收 | - -## 架构与核心流程 - -```text -宿主 / Agent - │ 调用技能 - ▼ -skills/effectcraft-* ──► MCP 编辑器 / 原生 CLI - │ - ▼ - 可编辑工程 + 导出 - │ - ▼ - 回读、检查、交付 -``` - -原则： - -1. 先只读检查，再计划，再执行。 -2. 每次写入保留原件或可回退版本。 -3. 导出后重新打开核对。 -4. 不确定的结果标记为待核对，不自动重放。 - -## 兼容性 - -| 项目 | 状态 | -|---|---| -| 宿主 | 支持 MCP Apps 或内置浏览器的宿主 | -| Node.js | 24+（编辑器） | -| 平台 | 以实际安装包与发行说明为准 | - -## 安装 - -```bash -codex plugin marketplace add partme-ai/full-aigc-plugins -codex plugin add effectcraft@full-aigc-plugins -``` +## Positioning -安装后重启宿主，先做只读检查。 +EffectCraft Use drives the native EffectCraft CLI from a coding agent: it plans a composition from your assets, installs the pinned runtime on first authorized use, executes native commands in a recorded session, saves and reopens the project, and checks real rendered pixels before calling a shot done. -## 快速开始 +The native `.ecproj` project is the source of truth. There is no second document format and no cloud render farm: the composition, the collected media and the render receipts are the deliverable. Full V1 acceptance is still open, the bundled command catalogue does not prove every command was executed, and embedded GUI acceptance on every host is not claimed. -1. 确认目标、输入素材和交付格式。 -2. 先检查现有工程，列出缺失项。 -3. 执行一次有界修改。 -4. 重新打开输出，核对结构与关键内容。 -5. 完成视觉或内容复核后交付。 +## Status and version -## 配置 +`0.1.0-dev.20261018.3` · development preview · `docs/verification/release-candidate.json` → `releaseStatus: BLOCKED`, `installableDevelopmentCandidate: true`. -| 变量 | 用途 | 默认 | -|---|---|---| -| `CRAFT_WORKSPACE_ROOT` | 编辑器绑定的工作区 | 当前项目 | -| `CRAFT_EDITOR_UPDATE` | 设为 `off` 跳过增强包下载 | 开启 | +| Metadata version | 0.1.0-dev.20261018.3 | +| Skills source | effectcraft-skills / 0.1.0-dev.69 | -不要在工程或配置中写入密钥、令牌和私有路径。 +## Installation -## 扩展契约 +### Prerequisites -新增技能时应使用 `effectcraft-` 前缀，声明触发条件和边界，通过 MCP 或固定 CLI 操作真实工程，修改后重新打开核验。 +- macOS arm64. Seven native platform/architecture targets are locked, but acceptance evidence currently covers macOS arm64; anything else returns `unsupported_platform`. +- No preinstalled Python is required for the managed entry: `launch.sh` / `launch.ps1` provisions the pinned isolated Python 3.13.16 and the EffectCraft CLI in the user data directory. +- Node.js 24 or newer for the embedded editor MCP server. A Git checkout has no `ui/dist/`; build it per `ui/README.md` first, or install a release bundle that ships it. +- First use needs network or pinned archives. `--runtime-home` or `CRAFT_RUNTIME_HOME` relocates the runtime root (`~/.local/share/craft-runtimes` by default). No `sudo`, no `PATH` edits. -## 重试、幂等与恢复 +### Install the plugin -- 失败后先检查当前工程状态。 -- 不自动重复已产生副作用的操作。 -- 重试使用新输出路径并保留旧回执。 +```bash +codex plugin marketplace add full-aigc-plugins/effectcraft-plugin +codex plugin add effectcraft@full-aigc-plugins-effectcraft +``` -## 数据与状态 +`docs/verification/release-candidate.json` records `installableDevelopmentCandidate: true` with `releaseStatus: BLOCKED`. `project-status.json` keeps `marketplaceEligible: false`; production promotion is not claimed. -- 输入素材只读。 -- 输出工程、导出文件和临时目录分开。 -- 交付前确认文件可打开、内容完整。 +Manifests for Codex (`.codex-plugin/`), Claude Code (`.claude-plugin/`), ZCode (`.zcode-plugin/`) and Kimi (`kimi.plugin.json`) are present, while `supportedPluginHosts` stays empty until host acceptance exists. -## 安全 +## Quick start -- 不把未授权素材上传到第三方服务。 -- 敏感内容脱敏后再交付。 -- 发现泄露先轮换凭据，再清理文件。 +```sh +: "${HARNESS_DIR:?Set to the directory holding the loaded effectcraft-harness SKILL.md}" +/bin/sh "$HARNESS_DIR/scripts/launch.sh" doctor +/bin/sh "$HARNESS_DIR/scripts/launch.sh" run --mode workflow \ + --plan "$SKILL_DIR/examples/brand-intro.json" --output /absolute/new-result +``` -## 可观测性与运行 +Windows uses `& "$HARNESS_DIR/scripts/launch.ps1" run --mode workflow ...` with the same modes. Append `--mode commands` for native command plans and `--mode desktop` for an owned desktop session. -记录命令、输出文件、关键结构和复核结果；交付前至少检查一次真实输出。 +```mermaid +flowchart LR + A[Brief and assets] --> B[effectcraft-use routes the task] + B --> C[Managed launcher, pinned runtime] + C --> D[Native .ecproj plus ledgers] + D --> E[Render or alpha export] + E --> F[Decode real pixels, review, deliver] +``` -## 开发与验证 +`help` returns usage with exit code 2 and is not a health check; use `info --json` and `commands --json` instead. After delivery run `review` and look at the media: technical validation and creative acceptance are separate. + +## What you can build + +| Workflow | Built-in path | Verifiable output | +|:---|:---|:---| +| Logo reveal or brand intro | `effectcraft-logo-reveal` + `effectcraft-cli-animation` | Reopened `.ecproj` with keyframes and effects intact | +| Lower thirds, chapter cards, credits | `effectcraft-lower-thirds`, `effectcraft-chapter-card`, `effectcraft-credits-roll` | Compositions whose text layers stay independently editable | +| Kinetic typography or social loop | `effectcraft-kinetic-type`, `effectcraft-social-loop` | Loop or title animation with checked timing | +| Camera, 3D layers and expressions | `effectcraft-cli-camera`, `effectcraft-cli-expressions` | Reopened project with camera, material and expression state | +| Masks, tracking and puppet deformation | `effectcraft-cli-masks`, `-tracking`, `-puppet` | Matte or pin data checked against rendered frames | +| Transparent or video render | `effectcraft-cli-export` | Output whose real pixels, alpha and duration are decoded | +| Run any native command | `effectcraft-harness` → `commands.py` | Receipt carrying the actual native return value | +| Edit in the embedded editor | `effectcraft-editor` MCP tools | Saved project reopened and inspected | + +## Skills + +| Skill | What it does | +|:---|:---| +| `effectcraft-use` | Default entry: editable comps, motion graphics and intros; installs the pinned CLI | +| `effectcraft-cli` | Query native commands and parameters; tracking, stabilization, graphic attachment | +| `effectcraft-cli-setup` | First install, digest checks, version checks, missing-runtime triage | +| `effectcraft-cli-project` | Create, save and reopen `.ecproj`, organise project items | +| `effectcraft-cli-footage` | Import images, video, vector and PSD assets, register dependencies | +| `effectcraft-cli-composition` | Comps, frame size, frame rate, duration and work area | +| `effectcraft-cli-layers` | Text, shape and footage layers, precomps and hierarchy | +| `effectcraft-cli-animation` | Properties, keyframes, easing, text and graphic animation | +| `effectcraft-cli-effects` | Find supported effects, reorder them, adjust parameters | +| `effectcraft-cli-masks` | Mask paths, feather and local mattes | +| `effectcraft-cli-expressions` | Inspect, set and diagnose expressions on chosen properties | +| `effectcraft-cli-camera` | Cameras, lights, materials and 3D layer switches | +| `effectcraft-cli-export` | Preview frames, render sequences or video, alpha handoff clips | +| `effectcraft-cli-tracking` | Track and stabilize footage, attach titles and graphics to motion | +| `effectcraft-cli-puppet` | Puppet meshes and pins, local deformation, recorded follow motion | +| `effectcraft-harness` | The single execution channel: bootstrap, launch, workflow, commands | +| `effectcraft-editor` | Open the real editor UI and keep one session for all edits | +| `effectcraft-kinetic-type` | Typographic rhythm for titles and short copy | +| `effectcraft-logo-reveal` | Logo entrance, hold and outro | +| `effectcraft-lower-thirds` | Name and role bars with brand marks | +| `effectcraft-motion-export` | Output checks on duration, frame rate and codec | +| `effectcraft-screen-composite` | Layer, mask and screen-content replacement | +| `effectcraft-social-loop` | Short loops and cover frames for social formats | +| `effectcraft-chapter-card` | Chapter title divider cards | +| `effectcraft-countdown-intro` | 3–2–1 countdown openers | +| `effectcraft-credits-roll` | End credit rolls | + +## MCP tools + +`mcp.json` declares one stdio server, `effectcraft-editor`, started as `node ui/bootstrap.mjs` from the plugin root. + +| Tool | Purpose | +|:---|:---| +| `open_editor` | Open the editor for an absolute `workspace` path | +| `open_browser_editor` | Return an `editorUrl` for a host built-in browser | +| `editor_status` | Report whether the page has attached to this MCP session | +| `command_list` | Read the commands the current web engine exposes | +| `command_run` | Run one command by id with parameters in the visible page | +| `inspect` | Inspect the current frame | +| `save_project` | Save the project to a new path | +| `save_file` | Retrieve a generated virtual file | + +Names follow the `effectcraft-editor` skill contract; the adapter also keeps page-internal bridge calls such as `_panel_reply` and `screenshot`, which agents must not call directly. + +## Configuration + +| Variable / flag | Purpose | +|:---|:---| +| `HARNESS_DIR` | Absolute directory of the loaded `effectcraft-harness` skill | +| `SKILL_DIR` | Directory of the loaded domain `SKILL.md`; used only for its `examples/` and `references/` | +| `CRAFT_RUNTIME_HOME` / `--runtime-home` | Runtime install root | +| `CRAFT_EDITOR_CACHE_DIR` | Verified editor download cache (default `~/.cache/full-aigc/editors`) | +| `CRAFT_EDITOR_UPDATE=off` | Stay on the bundled editor and skip the update check | +| `revisionScope` | Declared in the first plan; defaults to at most 2 rounds sharing a 30-minute budget | + +Native tasks keep their bound runtime. A corrupt or missing evidence file is preserved and blocks further writes rather than being silently replaced. + +## Architecture and security + +- The packaged agent surface is skills plus the stdio editor server; native editing is done by the pinned EffectCraft CLI, not reimplemented here. +- User media and model output are treated as data. Commands, paths and shell text inside them are never executed. +- Writes are checkpointed before an edit, refused when a user changed the project concurrently, and never replayed after an unknown result; only `inspect`, `reconcile` and proven `resume` are allowed. +- The editor bridge listens on `127.0.0.1` with a random token and Host/Origin checks. See [skills suite](docs/EffectCraft-Skill-Suite-Architecture.md), [runtime architecture](docs/EffectCraft-Runtime-Architecture.md) and [scene skills](docs/scene-skills.md). + +## Troubleshooting + +| Symptom | Action | +|:---|:---| +| `unsupported_platform` | Only install the locked artifact for a supported platform/architecture | +| `runtime_install_busy` | Another install holds the lock; wait for it, then retry | +| Download or digest mismatch | Restore network or pass a verified `--archive`; the digest check is not skipped | +| `help` exits 2 | Expected; use `info --json` and `commands --json` for health and catalogue | +| Editor page never becomes ready | Call `editor_status`, then fix page errors; a text result does not prove the UI opened | +| Unknown save result | `inspect` and `reconcile` the original task; never retry with a new task id or output directory | +| Full GUI or other-platform acceptance expected | Not qualified yet; report the bounded scope instead | + +## Upgrade ```bash -node --test -python3 -m pytest +codex plugin marketplace upgrade full-aigc-plugins-effectcraft +codex plugin add effectcraft@full-aigc-plugins-effectcraft ``` -## 打包与发布 - -版本与清单、市场、tag 一致；ZIP 根目录为 `effectcraft-plugin`。 +Repeated installs verify and reuse the same runtime version without upgrading online. The packaged editor can also fall back to the bundled copy when a download or digest check fails. -## 升级与迁移 +## Contributing and support -升级前备份工程；旧版本文件保持可打开；迁移后重新检查结构和导出。 +Behaviour changes go through [OpenSpec](openspec/changes/establish-v1-plugin/proposal.md) first; do not check a task off without real delivery evidence. Documentation checks: -## 故障排查 - -| 现象 | 检查 | -|---|---| -| 打不开工程 | 文件完整性、版本兼容 | -| 编辑器空白 | Node.js 版本与工作区权限 | -| 导出异常 | 字体、素材、输出路径 | -| 结果不一致 | 重新打开并核对 | - -## 项目结构 - -```text -effectcraft-plugin/ -├── .zcode-plugin/ # ZCode 清单与 UI surface -├── skills/ # 26 个技能 -├── ui/ # MCP Apps 编辑器 -├── commands/open.md # 打开编辑器命令 -├── docs/ # 架构与验证记录 -└── assets/ # 图标与模板 +```bash +python3 scripts/validate_docs.py +python3 scripts/validate_editor_scenes.py ``` -## 贡献与支持 - -提交问题时附上插件版本、宿主、输入类型、命令、输出文件和预期结果。不要附敏感素材。 +Issues: . -## 许可证 +## License -Apache-2.0，见 [LICENSE](LICENSE)。 +Original repository content is [Apache-2.0](LICENSE). The EffectCraft CLI and the bundled web editor keep their own upstream licenses and NOTICE files; upstream icon provenance is recorded in `assets/official-icon-source.json`. diff --git a/README.zh-CN.md b/README.zh-CN.md new file mode 100644 index 0000000..efb3831 --- /dev/null +++ b/README.zh-CN.md @@ -0,0 +1,193 @@ +# EffectCraft Use + +## 插件市场导航 + +本插件所属分类：**AIGC 内容创作**。 + +| 分类 | 插件市场入口 | 用途 | +| --- | --- | --- | +| 全栈开发 | [Full Stack Plugins](https://github.com/partme-ai/full-stack-plugins) | 架构与 UI 设计、代码理解、质量检查、代码审查、流程治理与服务器运维 | +| AIGC 内容创作 | [Full AIGC Plugins](https://github.com/partme-ai/full-aigc-plugins) | 图像、视频、音频、音乐、3D 与多模态内容创作 | + +![EffectCraft Use——动态图形与合成](assets/official-logo.png) + +> 制作可编辑的 `.ecproj` 合成：合成、文字与形状图层、关键帧、表达式、摄像机、蒙版、木偶针脚与效果，并按你的要求输出预览、成片或带透明的片段。 + +[![版本](https://img.shields.io/badge/release-0.1.0--dev.20261018.4-1A73E8)](.codex-plugin/plugin.json) +[![技能数](https://img.shields.io/badge/skills-16-00A67E)](#技能) +[![MCP server](https://img.shields.io/badge/MCP%20server-1-00A67E)](#mcp-工具) +[![许可证](https://img.shields.io/badge/license-Apache--2.0-green)](LICENSE) + +[English](README.md) | [简体中文](README.zh-CN.md) · [安装](#安装) · [快速开始](#快速开始) · [可完成的工作](#可完成的工作) · [技能](#技能) · [故障排查](#故障排查) + +## 项目定位 + +EffectCraft Use 让编码智能体驱动原生 EffectCraft CLI：从素材规划合成，在首次获得授权时安装固定运行时，在留证的会话中执行原生命令，保存并重开工程，并在把镜头视为完成之前检查真实渲染像素。 + +原生 `.ecproj` 工程是唯一事实源。这里没有第二种文档格式，也没有云端渲染农场：合成、收集素材与渲染回执就是交付物。完整 V1 验收仍未完成，命令目录存在不代表每条命令都被执行过，也不承诺所有宿主的内嵌 GUI 均已验收。 + +## 状态与版本 + +`0.1.0-dev.20261018.3` · 开发预览 · `docs/verification/release-candidate.json` → `releaseStatus: BLOCKED`、`installableDevelopmentCandidate: true`。 + +| Metadata version | 0.1.0-dev.20261018.3 | +| Skills source | effectcraft-skills / 0.1.0-dev.69 | + +## 安装 + +### 前置条件 + +- macOS arm64。已锁定七种原生平台/架构目标，但当前验收证据只覆盖 macOS arm64；其余平台返回 `unsupported_platform`。 +- 受管理入口不需要预装 Python：`launch.sh` / `launch.ps1` 会在用户数据目录准备固定的隔离 Python 3.13.16 与 EffectCraft CLI。 +- 内嵌编辑器 MCP 服务需要 Node.js 24 或更新版本。Git 检出没有 `ui/dist/`，需先按 `ui/README.md` 构建，或安装自带该目录的发布包。 +- 首次使用需要网络或固定归档。`--runtime-home` 或 `CRAFT_RUNTIME_HOME` 可迁移运行时根目录（默认 `~/.local/share/craft-runtimes`）。不需要 `sudo`，不修改 `PATH`。 + +### 安装插件 + +```bash +codex plugin marketplace add full-aigc-plugins/effectcraft-plugin +codex plugin add effectcraft@full-aigc-plugins-effectcraft +``` + +`docs/verification/release-candidate.json` 记录 `installableDevelopmentCandidate: true` 与 `releaseStatus: BLOCKED`；`project-status.json` 保持 `marketplaceEligible: false`，不承诺生产晋级。 + +仓库带有 Codex（`.codex-plugin/`）、Claude Code（`.claude-plugin/`）、ZCode（`.zcode-plugin/`）与 Kimi（`kimi.plugin.json`）清单；在宿主验收出现之前，`supportedPluginHosts` 保持为空。 + +## 快速开始 + +```sh +: "${HARNESS_DIR:?请设为已加载 effectcraft-harness 的 SKILL.md 所在目录}" +/bin/sh "$HARNESS_DIR/scripts/launch.sh" doctor +/bin/sh "$HARNESS_DIR/scripts/launch.sh" run --mode workflow \ + --plan "$SKILL_DIR/examples/brand-intro.json" --output /absolute/new-result +``` + +Windows 使用 `& "$HARNESS_DIR/scripts/launch.ps1" run --mode workflow ...`，模式相同。原生命令计划追加 `--mode commands`，自有桌面会话使用 `--mode desktop`。 + +```mermaid +flowchart LR + A[需求与素材] --> B[effectcraft-use 路由任务] + B --> C[受管理启动器与固定运行时] + C --> D[原生 .ecproj 与账本] + D --> E[渲染或透明导出] + E --> F[解码真实像素、审阅、交付] +``` + +`help` 返回用法但退出码为 2，不能当健康检查；请使用 `info --json` 与 `commands --json`。交付后执行 `review` 并实际查看媒体：技术验证与创作验收是两件事。 + +## 可完成的工作 + +| 工作流 | 内置路径 | 可验证输出 | +|:---|:---|:---| +| 标志开场或品牌片头 | `effectcraft-logo-reveal` + `effectcraft-cli-animation` | 关键帧与效果完整的重开 `.ecproj` | +| 人物条、章节卡、片尾署名 | `effectcraft-lower-thirds`、`effectcraft-chapter-card`、`effectcraft-credits-roll` | 文字图层仍可独立编辑的合成 | +| 文字节奏动效或社交循环 | `effectcraft-kinetic-type`、`effectcraft-social-loop` | 时间节奏已核对的循环或标题动画 | +| 摄像机、3D 图层与表达式 | `effectcraft-cli-camera`、`effectcraft-cli-expressions` | 重开后摄像机、材质与表达式状态正确 | +| 蒙版、跟踪与木偶变形 | `effectcraft-cli-masks`、`-tracking`、`-puppet` | 对照渲染帧核对的遮罩或针脚数据 | +| 透明或视频输出 | `effectcraft-cli-export` | 真实解码核对的像素、透明通道与时长 | +| 执行任意原生命令 | `effectcraft-harness` → `commands.py` | 带真实原生返回值的回执 | +| 在内嵌编辑器中修改 | `effectcraft-editor` MCP 工具 | 保存后重开并检查的工程 | + +## 技能 + +| 技能 | 作用 | +|:---|:---| +| `effectcraft-use` | 默认入口：可编辑合成、动态图形与片头；安装固定 CLI | +| `effectcraft-cli` | 查询原生命令与参数；镜头跟踪、稳定与图形附着 | +| `effectcraft-cli-setup` | 首次安装、摘要校验、版本检查与缺失运行时排障 | +| `effectcraft-cli-project` | 创建、保存与重开 `.ecproj`，整理项目项 | +| `effectcraft-cli-footage` | 导入图像、视频、矢量与 PSD 素材，登记依赖 | +| `effectcraft-cli-composition` | 合成、画幅、帧率、时长与工作区 | +| `effectcraft-cli-layers` | 文字、形状与素材图层，预合成与层级 | +| `effectcraft-cli-animation` | 属性、关键帧、缓动，文字与图形动画 | +| `effectcraft-cli-effects` | 查询当前版本支持的效果，调整顺序与参数 | +| `effectcraft-cli-masks` | 蒙版路径、羽化与局部遮罩 | +| `effectcraft-cli-expressions` | 在指定属性上检查、设置与诊断表达式 | +| `effectcraft-cli-camera` | 摄像机、灯光、材质与图层三维开关 | +| `effectcraft-cli-export` | 预览关键帧、渲染序列或视频、透明交接片段 | +| `effectcraft-cli-tracking` | 跟踪与稳定素材，把标题图形附着到运动主体 | +| `effectcraft-cli-puppet` | 木偶网格与针脚、局部变形、录制跟随动画 | +| `effectcraft-harness` | 唯一执行通道：bootstrap、launch、workflow、commands | +| `effectcraft-editor` | 打开真实编辑界面，一次会话内完成全部编辑 | +| `effectcraft-kinetic-type` | 标题与短文案的排版节奏动效 | +| `effectcraft-logo-reveal` | 标志入场、停留与收尾 | +| `effectcraft-lower-thirds` | 姓名职位条与品牌标识 | +| `effectcraft-motion-export` | 时长、帧率与编码的输出检查 | +| `effectcraft-screen-composite` | 图层、遮罩与屏幕内容替换合成 | +| `effectcraft-social-loop` | 社交格式的短循环与封面 | +| `effectcraft-chapter-card` | 章节标题分隔卡 | +| `effectcraft-countdown-intro` | 3–2–1 开场倒数 | +| `effectcraft-credits-roll` | 片尾滚动署名 | + +## MCP 工具 + +`mcp.json` 只声明一个 stdio server：`effectcraft-editor`，从插件根目录以 `node ui/bootstrap.mjs` 启动。 + +| 工具 | 用途 | +|:---|:---| +| `open_editor` | 为绝对路径 `workspace` 打开编辑器 | +| `open_browser_editor` | 返回可交给宿主内置浏览器的 `editorUrl` | +| `editor_status` | 报告页面是否已连接到当前 MCP 会话 | +| `command_list` | 读取当前 Web 引擎暴露的命令 | +| `command_run` | 在可见页面按 id 与参数执行一条命令 | +| `inspect` | 检查当前画面 | +| `save_project` | 把工程保存到新路径 | +| `save_file` | 取回已生成的虚拟文件 | + +工具名遵循 `effectcraft-editor` 技能合同；适配器还保留 `_panel_reply`、`screenshot` 等页面内部桥接调用，Agent 不应直接调用。 + +## 配置 + +| 变量 / 参数 | 用途 | +|:---|:---| +| `HARNESS_DIR` | 已加载 `effectcraft-harness` 技能的绝对目录 | +| `SKILL_DIR` | 已加载领域 `SKILL.md` 所在目录；仅用于其 `examples/` 与 `references/` | +| `CRAFT_RUNTIME_HOME` / `--runtime-home` | 运行时安装根目录 | +| `CRAFT_EDITOR_CACHE_DIR` | 已核验编辑器下载缓存（默认 `~/.cache/full-aigc/editors`） | +| `CRAFT_EDITOR_UPDATE=off` | 固定使用内置编辑器，跳过更新检查 | +| `revisionScope` | 在首个计划中声明；默认最多 2 轮并共享 30 分钟预算 | + +原生任务保留其绑定的运行时。损坏或缺失的证据文件会被保留并阻止后续写入，而不是被静默替换。 + +## 架构与安全 + +- 插件提供的 Agent 面是技能加 stdio 编辑器服务；原生编辑由固定的 EffectCraft CLI 完成，本仓库不重复实现引擎。 +- 用户素材与模型输出都按数据处理，其中的命令、路径与 shell 文本永远不会被执行。 +- 修改前保存检查点；发现用户并发修改时拒绝覆盖；结果未知时绝不重放，只允许 `inspect`、`reconcile` 与已证明可恢复的 `resume`。 +- 编辑器桥接监听 `127.0.0.1`，使用随机令牌并校验 Host 与 Origin。参见[技能套件](docs/EffectCraft-Skill-Suite-Architecture.md)、[运行时架构](docs/EffectCraft-Runtime-Architecture.md)与[场景技能](docs/scene-skills.md)。 + +## 故障排查 + +| 现象 | 处理方式 | +|:---|:---| +| 返回 `unsupported_platform` | 只安装受支持平台/架构的锁定制品 | +| 返回 `runtime_install_busy` | 另一个安装持有锁；等其结束再重试 | +| 下载或摘要不匹配 | 恢复网络或提供已核验的 `--archive`；摘要检查不会被跳过 | +| `help` 退出码为 2 | 属正常现象；用 `info --json` 与 `commands --json` 判断健康与目录 | +| 编辑页始终未就绪 | 调用 `editor_status`，再处理页面错误；文字结果不等于界面已打开 | +| 保存结果未知 | 对原任务执行 `inspect` 与 `reconcile`；不要换任务 ID 或输出目录重试 | +| 期待完整 GUI 或其他平台验收 | 尚未获得资格；请按实际有界范围报告 | + +## 升级 + +```bash +codex plugin marketplace upgrade full-aigc-plugins-effectcraft +codex plugin add effectcraft@full-aigc-plugins-effectcraft +``` + +重复安装会校验并复用同一运行时版本，不联网升级。下载或摘要校验失败时，打包的编辑器也可回退到内置副本。 + +## 贡献与支持 + +行为变更必须先走 [OpenSpec](openspec/changes/establish-v1-plugin/proposal.md)；没有真实交付证据不得勾选任务。文档校验： + +```bash +python3 scripts/validate_docs.py +python3 scripts/validate_editor_scenes.py +``` + +问题反馈：。 + +## 许可证 + +本仓库原创内容采用 [Apache-2.0](LICENSE)。EffectCraft CLI 与内置 Web 编辑器各自保留其上游许可证与 NOTICE；上游图标来源记录在 `assets/official-icon-source.json`。