PhotoCraft Use
Plugin marketplaces
This plugin belongs to AIGC content creation.
| Category | Marketplace | Purpose |
|---|
| Full-stack development | Full Stack Plugins | Architecture and UI design, code understanding, quality checks, code review, workflow governance, and server operations |
| AIGC content creation | Full AIGC Plugins | Image, video, audio, music, 3D, and multimodal content creation |
PhotoCraft Use — layered image editing
Build editable .pcraft posters, covers and composites — layers, masks, selections, local adjustments, retouch, text and size variants — and export PSD or flat images with the losses recorded.
English | 简体中文 · Install · Quick start · What you can build · Skills · Troubleshooting
Positioning
PhotoCraft Use keeps raster design editable. Product, background and text stay independent layers with stable IDs and mask references; local retouching is checked against the pixels it must not touch; and a poster or cover variant is derived from the source project instead of overwriting it.
The native .pcraft project is the delivery authority. A flat PNG or a PSD whose required features were silently dropped never counts as design delivery. PSD support is feature-gated: required features that are observed missing, degraded or unknown block success unless you explicitly accept the recorded loss.
Status and version
0.1.0-dev.20261019.1 · development preview · docs/verification/release-candidate.json → releaseStatus: BLOCKED, installableDevelopmentCandidate: true.
Current plugin: 0.1.0-dev.20261019.1; skill source: 0.1.0-dev.60; version roles are independent.
| Identity | Current value |
|---|
| Metadata version | 0.1.0-dev.20261019.1 |
| Skills source | photocraft-skills / 0.1.0-dev.60 |
Installation
Prerequisites
- macOS arm64, with Python 3.11 or newer on
PATH for the public scripts.
- Node.js 24.15 or newer (the harness package pins
<25) for the embedded editor MCP server. A Git checkout has no ui/dist/; build it per ui/README.md, or install a release bundle that ships it.
- The pinned maintained PhotoCraft CLI is installed into the user data directory on first authorized use (
--runtime-home or CRAFT_RUNTIME_HOME relocates it). No sudo, no PATH edits.
- First use needs network or a verified cache. Offline use requires the locked archive or an intact verified cache.
Install the plugin
codex plugin marketplace add full-aigc-plugins/photocraft-plugin
codex plugin add photocraft@full-aigc-plugins-photocraft
docs/verification/release-candidate.json records installableDevelopmentCandidate: true with releaseStatus: BLOCKED; project-status.json keeps marketplaceEligible: false.
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
: "${HARNESS_DIR:?Set to the directory holding the loaded photocraft-harness SKILL.md}"
python3 -I -B "$HARNESS_DIR/scripts/bootstrap.py"
python3 -I -B "$HARNESS_DIR/scripts/commands.py" list --filter QUERY
Then ask for the result you want, for example “Cut this product out on a clean white background and keep the project editable”. Headless is the default path; a desktop bridge needs its own connection and capability checks.
flowchart LR
A[Product shots, copy, brand] --> B[photocraft-use plans layers]
B --> C[Pinned runtime, native .pcraft]
C --> D[Masks, selections, local adjustment]
D --> E[Reopen and verify layers]
E --> F[PSD or flat export with loss notes]
What you can build
| Workflow | Built-in path | Verifiable output |
|---|
| Poster or social cover | photocraft-use, photocraft-social-cover | Reopened .pcraft where text, product and background stay editable |
| Product cutout | photocraft-product-cutout | Transparent or white-background output plus the editable project |
| Old-photo restoration | photocraft-restore-old-photo | Restored project with identity and damage areas inspected |
| Scan cleanup | photocraft-repair-scan | Deskewed, cleaned scan with the paper base recorded |
| Portrait retouch | photocraft-retouch-portrait | Natural finish with untouched regions verified |
| Batch delivery variants | photocraft-batch-image-delivery | Same-size, same-format outputs and a filename contact sheet |
| PSD exchange | photocraft-cli-export | PSD whose required features are validated; losses recorded |
| Edit in the embedded editor | photocraft-editor MCP tools | Saved .pcraft reopened and inspected |
Skills
| Skill | What it does |
|---|
photocraft-use | Default entry: editable .pcraft posters, covers, composites; installs the maintained CLI |
photocraft-cli | Query native commands, parameters and capabilities; run explicit public commands |
photocraft-cli-setup | First install, digest checks, version checks, missing-runtime triage |
photocraft-cli-project | Create, open, save and copy .pcraft; colour mode and bit depth |
photocraft-cli-layers | Product, background, text and groups; hierarchy and blending |
photocraft-cli-selection | Selections, invert, feather and local selection |
photocraft-cli-masks | Layer masks, vector masks and clipping composites |
photocraft-cli-adjustments | Adjustment layers and authorized local colour changes |
photocraft-cli-retouch | Healing, cloning, brush and local correction on authorized images |
photocraft-cli-text | Text layers, fonts, paragraphs and layout |
photocraft-cli-resize | Image and canvas size, trim, extend, rotate and cover variants |
photocraft-cli-filters | Local filters, background blur, grain and output sharpening |
photocraft-cli-export | Export PSD, PNG or other interchange files from the native project |
photocraft-harness | The single execution channel: bootstrap, commands, workflow, task sessions |
photocraft-editor | Open the real editor UI and keep one session for all edits |
Slash commands
The Claude Code manifest (com.anthropic.claude-code/) ships 22 commands, one per skill, plus a SessionStart guidance hook. Each command routes to its skill and launches nothing by itself.
| Command | What it does |
|---|
/photocraft-use | Full task entry and shortest skill chain |
/photocraft-editor | Embedded editor session |
/photocraft-harness | Managed execution channel and task control |
/photocraft-scenario-playbooks | Pick the playbook for the current problem |
/photocraft-cli, /photocraft-cli-{project,layers,selection,masks,adjustments,retouch,text,resize,filters,export,setup} | Command-level families, one command per skill |
/photocraft-{restore-old-photo,retouch-portrait,product-cutout,repair-scan,social-cover,batch-image-delivery} | Scene entries, one command per skill |
MCP tools
mcp.json declares one stdio server, photocraft-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 |
doc_open | Open an existing .pcraft |
doc_new | Create a document |
doc_inspect | Inspect layers and document state |
command_list | Read the commands the engine exposes |
command_run | Run a command by id with parameters |
doc_save | Save the .pcraft project |
doc_export | Export the project |
Names follow the photocraft-editor skill contract; page-internal bridge calls such as _editor_attach and screenshot must not be called by an agent.
Configuration
| Variable | Purpose |
|---|
HARNESS_DIR | Absolute directory of the loaded photocraft-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 |
Architecture and security
- The plugin plans and verifies; the pinned maintained CLI performs native raster editing. The engine is not reimplemented here.
- User media and generated images are data. Commands, paths or shell text inside them are never executed.
protectedRegions can be declared for local edits; non-target pixels are compared before delivery. When no region is declared, no protection scope is inferred.- Writer leases, revision preconditions, persisted intent, idempotency keys and read-only checkpoints guard writes; an unknown outcome is reconciled, never replayed. See runtime architecture, PSD policy and scene skills.
Troubleshooting
| Symptom | Action |
|---|
unsupported_platform | Only the locked macOS arm64 artifact is supported |
runtime_install_busy | Another install holds the lock; wait for it, then retry |
| PSD delivery is refused | A required feature is missing, degraded or unknown; record the loss or change the required set |
| Fonts render differently | Check the font dependency and substitution record before delivery |
| Editor page never becomes ready | Call editor_status, then fix page errors; a text result does not prove the UI opened |
| Flat export treated as design | Reopen the .pcraft and verify layers; a flat image is not editable delivery |
| Unknown save result | Read the receipt and the existing project first; do not replay the plan |
Upgrade
codex plugin marketplace upgrade full-aigc-plugins-photocraft
codex plugin add photocraft@full-aigc-plugins-photocraft
Runtime transitions keep the old project bound to its runtime; a rollback reuses the verified previous artifact instead of rebuilding it.
Contributing and support
State behaviour changes in OpenSpec first; do not check a task off without real delivery evidence. Repository checks:
python3 scripts/validate_docs.py
node --test tests/*.test.ts
Issues: https://github.com/full-aigc-plugins/photocraft-plugin/issues.
License
Original repository content is Apache-2.0. The PhotoCraft CLI and bundled web editor keep their own upstream licenses and NOTICE files; upstream icon provenance is recorded in assets/official-icon-source.json and assets/THIRD-PARTY-SOURCE.md.
