t1k:cocos:blind-edit:assets
| Field | Value |
|---|---|
| Module | blind-edit |
| Version | 2.1.16 |
| Effort | medium |
| Tools | — |
Keywords: authoritative writer, blind edit, canary confirm, edit prefab without editor, edit scene without editor, headless cocos edit, look spec
How to invoke
Section titled “How to invoke”/t1k:cocos:blind-edit:assets[preflight|edit|validate|confirm|rollback|stats|look-spec]Blind edit: edit -> validate -> ONE confirm -> adopt
Section titled “Blind edit: edit -> validate -> ONE confirm -> adopt”Edit Cocos Creator assets (.scene, .prefab, .mtl, .anim, .meta, and the .ts constants a look depends on) from Node with the editor closed. A static validator proves the edit is self-consistent; ONE canary build then proves, and only proves: the snapshot holds our bytes, the source read-back matches, the build succeeded (exit 0), the build ran the unique branch of that snapshot, and the log has no new ERROR line. It does NOT check the built output (no screenshot, no built-file read-back exists in this release). The measured win is correctness and cost (A/B: spec arm 6/6 strict vs raw 4/6, median cost about 20% lower), NOT speed: the Jenkins build (3.5-5 minutes) dominates.
CLI: bun <skill-dir>/scripts/blind-edit.cjs <preflight|edit|look-spec|validate|confirm|rollback|stats|corpus|shape> --project <cocos-root> ... (JSON on stdout; exit 0 ran, 1 refused or bad input, 2 bad args, 3 confirm broken, 4 confirm infra, 5 confirm ok-manual-identity). Schemas: references/contract.md. Ids and fixtures: references/hazards.md. Lessons: references/incident-history.md. Shapes (data packs): shapes/look-spec/.
The contract (MUST)
Section titled “The contract (MUST)”preflight. Refuse when a Cocos Creator editor may hold the project: it silently reverts disk edits to assets it holds. Close it (never kill it);--editor-closedonly attests when the process list cannot be read. An editor whose command line names another--project(a worktree lane while the main checkout is open) reportseditor: elsewhereand does not block; anything unprovable still refuses.editwith a shape (--shape look-spec --map <project map> --spec|--preset, or--shape ops --ops <file>ofset-leafprimitives). The whole op set compiles in memory first; one bad op writes nothing. The run is journalledunconfirmedbefore the first byte changes.editandrollbackhold a per-project lock (temp/T1K/blind-edit/.lock); a second live writer fails withlocked.validate --run <id> [--map <map>]. Fix everyfails[]entry (footprint,id-range,order-changed,fileid-changed,unresolved-uuid,dangling-type,missing-meta,dup-uuid,created-changed,json-parse,shadowed-field);info[](problems that were already there, builtin uuids) is reported, never rewritten.- ONE confirm round:
confirm plan(refuses a key with pixel probes or a path-based built read-back:probe-unsupported,built-readback-unsupported),confirm snapshot --push [--remote <name>](a UNIQUEexp/blind-edit-<runId>side branch via a temp index; never develop or main, never reused, never forced), then build that branch with the core skillt1k-jenkins-build(canary job, serial, never a Release job, never a Discord thread;PARAM_GAME_REPO= the project remote,PARAM_GAME_BRANCH= the snapshot branch), thenconfirm collect --build-info <json> --log <txt> [--remote <name>]andconfirm finalize.collectproves the build identity from the branch (parameters +git ls-remote);--build-commit <sha>is a manual override recorded ascommitSource: manual. Verdictok,brokenorinfra(the build died for a reason that is not the edit: ONE unchanged retry). - Never report the edit done while the journal state is
unconfirmedorbroken. Paste everylessonLines[]entry the finalize prints into your reply (the collector reads assistant text only). After a confirm, re-import the touched assets before the editor saves anything.
Blind or editor?
Section titled “Blind or editor?”Prefer blind-edit over the cocos-creator MCP for every static file edit (scene/prefab/material JSON, .meta), even a single tweak. Use the MCP only for live-editor work or a blind-edit needs-editor refusal.
What it will not do (refuses with a hazard id)
Section titled “What it will not do (refuses with a hazard id)”.effect / .pmtl (YAML, C08), values inside cc.PrefabInstance override records (C04), cc.PrefabInfo and any fileId (C03), writes to __id__ / __type__ / __uuid__ / _id / fileId, deleting or reordering an element (C01: appending is allowed), JSON that does not parse. The 15 engine-builtin uuids are info (C05). Use the editor (t1k-cocos-base-editor-mcp-truth) for those.
Look-spec shape
Section titled “Look-spec shape”A project ships its own look-spec.map.json (key -> file + JSON path or TS constant; the Arrow3D keys are only the test fixture example-arrow3d). Keys cover palette, background, light, ambient, fog and material colours; a partial spec touches only the keys it names. The map can declare authoritativeWriters (a runtime writer that overwrites a scene field, e.g. PlayableConfig.ts over the scene BG colour) and per-key probes (pixel samples) and builtReadback (a value in the built config): the confirm checks the BUILT value, not the file. A material shared with a non-owner is forked (new minted uuid, .meta, owners repointed); the fork on disk is the state.
Other shapes
Section titled “Other shapes”--shape set-field|swap-ref|new-asset --spec <file> (references/shapes-index.md: fields of a component by node path, retarget an asset reference, clone an asset with a fresh uuid and its .meta). A confirm does not check built output: no-effect comes only from authoritativeWriters or the independent checker blind-edit.cjs corpus --check (references/contract.md section “P6 shapes, corpus and the loop”). corpus --tier 1 is the practice corpus gate.
Contributing a shape
Section titled “Contributing a shape”A shape is a data pack, never a skill. blind-edit.cjs shape new <name> scaffolds one, shape golden|attest|check|index|publish carry it to a green gate, and /t1k:sync-back t1k-cocos-blind-edit-assets opens the PR. stats prints SHAPE-CANDIDATE lines (paste them into your reply) when a hand-written ops edit repeats 3 times in 30 days. The record is the contributor’s attestation, not a proof. Details: references/contract.md section “P7 contributing a shape”.
Executed by
Section titled “Executed by”The CLI steps are mechanical and emit JSON; only choosing the keys, judging a broken or no-effect verdict and the Jenkins step stay on a reasoning tier (routing SSOT: theonekit-core/.claude/modules/t1k-orchestration/rules/orchestration-rules.md § “Task-Type → Agent Routing”):
| Step | Agent |
|---|---|
Run preflight / validate and read fails[] and info[] off the JSON | t1k-fact-fetcher |
Summarize stats per shape (runs, median blind wall, ratio) | t1k-metrics-reporter |
Decide the spec, fix a validate failure, run the canary build, judge a broken / no-effect confirm | reasoning tier: a write to the user’s assets, not a label |
The neutral core
Section titled “The neutral core”The journal, atomic apply with rollback, confinement, refusal codes, lesson marker and the contract text are the skill t1k-gamedev-blindedit-blind-edit (module theonekit-gamedev:blindedit, a dependency of this module): read its references/contract.md for the contract and its slot-contract reference for the slot. This skill is the Cocos slot (scripts/blind-edit-slot.cjs, x-blind-edit in gamedev-adapter.json) plus the Cocos-only parts (span-exact JSON, validator rules, the canary-build confirm, look-spec and the other shapes). If the core is missing the CLI stops with gamedev-core-missing and names the module: run t1k modules update.
Related
Section titled “Related”t1k-cocos-base-uuid-verify (the compressed-uuid codec), t1k-cocos-base-editor-mcp-truth (why a live editor reverts disk edits), core t1k-jenkins-build (the canary build).
Visual change notice
Section titled “Visual change notice”Rule visual-change-discord-notice: editing a scene, prefab or material look is a visible change. Capture OLD before the first edit and NEW after the last (preview-verify shot steps, or the image file itself for a 2D asset), return the paths and a draft Discord post (what changed, undo = revert the PR) to the orchestrator, who posts; never post from here. Logic-only: no visible change. No capture possible: screenshots pending: <reason>, never a mock image. The PR needs the Discord link or visual-notice-waiver: <reason>; the owning agent’s Visual change notice section has the full steps.