t1k:cocos:base:apk-unbuild
| Field | Value |
|---|---|
| Module | base |
| Version | 4.51.9 |
| Effort | high |
| Tools | — |
Keywords: apk unbuild, cocos 2.4 apk, cocos-unbuild, decrypted client, editable project, editor open gate, rebuild from apk, shipped apk, slot lock, xxtea
How to invoke
Section titled “How to invoke”/t1k:cocos:base:apk-unbuild[<toolkit-root>] [--rebuild | --maintain | --re-verify]APK Unbuild — orchestrating the cocos-unbuild toolkit
Section titled “APK Unbuild — orchestrating the cocos-unbuild toolkit”The toolkit is its own private repo, The1Studio/cocos-unbuild. It turns a shipped Cocos Creator 2.4.x APK
into an editable project that opens in the editor and builds. This skill is the orchestrator’s half: it
never touches APK-derived data and never runs the toolkit for a verdict. It briefs headless omp lanes, then verifies
what they report. The toolkit’s own GUIDE.md and README tool index are the per-tool reference; read the
toolkit’s VERSION and top CHANGELOG.md entry first, because stage names and flags move between releases.
Decision tree
Section titled “Decision tree”| Intent | Path |
|---|---|
| Ship an editable project from an APK, first time | stage order — pipeline-stages (references/pipeline-stages.md) |
| Change the toolkit or the readable overlay, re-run | --maintain — pipeline-stages (references/pipeline-stages.md) § rerun |
| Prove an existing project still passes the gate | --re-verify — acceptance-and-evidence (references/acceptance-and-evidence.md) |
| Draft a lane brief | brief-template (references/brief-template.md) |
| A lane stalled, or exited without its report | lane-orchestration (references/lane-orchestration.md) § 3 |
| Which toolkit release this skill’s facts describe | SKILL.md § 0.2 — read VERSION and CHANGELOG.md first |
0. When this applies
Section titled “0. When this applies”Applies to: rebuilding an editable project from a shipped 2.4.x build; maintaining it; re-verifying it.
Not for: Cocos Creator 3.x, Unity references (see t1k-cocos-playable-pla-from-ref), repackaging or
signing an APK, or a project that already has readable sources, where there is nothing to unbuild.
0.1 Rule 1 — Claude Code only orchestrates
Section titled “0.1 Rule 1 — Claude Code only orchestrates”0.2 Toolkit versions — read VERSION and CHANGELOG.md first
Section titled “0.2 Toolkit versions — read VERSION and CHANGELOG.md first”This skill does not ship the toolkit; it points at The1Studio/cocos-unbuild. Stage names, flags and exit codes
move between releases, so a lane reads its clone’s VERSION and top changelog entry before its first step. As of
1.12.4 (each line checked against that release’s README, config README and changelog):
- Gate exemptions are per project. The shipped
WARNING_LEDGER.mdis a template (generic entries 1-5); the per-project entries are read from the project’s own ledger named by configgate.ledger(or--project-ledger). A missing, unset or placeholder ledger exempts nothing, and that is reported. - Example-config placeholders fail loudly. Copy
config/example.jsontoconfig/toolkit.json(or setTOOLKIT_CONFIG); loaders never fall back to the example, and an example value such aspath/to/project,build.unpackCheck: exampleorverify.apiHost: game.example:3000makesconfig/get.cjsexit 2 andpipeline.cjs --dry-runexit 1. - The runtime check needs project data. Without
verify.runtimeCases/verify.runtimeGoldenthe runtime check is NOT-RUN and the verify verdict caps atGREEN (no runtime). - The intake mirror lands in
<client.mirror>/assets, and the toolkit is self-contained.
Never cite this section against a different toolkit version.
1. The split — who may touch what
Section titled “1. The split — who may touch what”| Role | Owns | Never does |
|---|---|---|
| Orchestrator (this session) | plan, briefs, evidence cross-checks, user comms, git via t1k-git | anything in § 0.1 |
Worker lane (a headless omp process) | everything that reads the APK or runs the toolkit | open a PR, push, decide scope, add a ledger entry |
| Verify lane (a second, fresh-context worker) | re-runs the acceptance commands, runs the editor-open probe, writes a per-claim verdict | the same as a worker lane |
You verify a worker’s report by briefing a verify lane and cross-checking its evidence files, never by running the check yourself and never from the summary alone.
2. Preflight — say which line is missing, then stop
Section titled “2. Preflight — say which line is missing, then stop”Exact checks: lane-orchestration (references/lane-orchestration.md) § 1.
- toolkit present at
<toolkit-root>(GUIDE.md, README tool index,pipeline.cjs,gate.py,verify/); - the shipped APK and its split present at the paths the toolkit config (
TOOLKIT_CONFIG) resolves; - Python 3, Node 18+ (Node 22+ for
verify/), a Cocos Creator 2.4.15 install atcocos.creator, Chrome/Chromium for the browser stages; every tool and download: prerequisites (references/prerequisites.md). The toolkit runs onnode, neverbun—node pipeline.cjs, notbun pipeline.cjs;selftest.cjsresolves anode --teststep’s binary fromprocess.execPath, so under bun everynode --testsuite is executed by bun’s runner and fails, andbun --versionproves nothing about Node (#1573); - the
ompCLI works (omp --versionprints a version) — the lane’s only runtime dependency; - the shared editor slot lock
<toolkit-root>/.editor-slot.lockabsent, and no stray editor process.
Before the first lane launch, in one message: the prerequisites notice above, then the user notice and the
Bash(omp -p *) rule (permissions (references/permissions.md)) or the user’s choice to paste each printed command
with the ! prefix. The orchestrator may ls/stat the APK and split files, but never lists or opens their
contents — that is the lane’s job.
3. Stages
Section titled “3. Stages”Order, the command per stage, exit codes and what GREEN means: pipeline-stages (references/pipeline-stages.md).
In short: intake, uuid-map, rebuild, verify-pre, promote, build (slot lock), gate, verify, optional beautify,
preview, smoke, then the opt-in acceptance and native stages, compare, selftest. Split any stage into a part
that only writes derived files and a part that needs the editor slot, so two lanes never collide.
“Beautify” is a decision with five options, not one. Rename (the overlay, what the beautify stage applies)
plus four the toolkit ships separately: C strip the cc._RF frame (tools/strip_rf.cjs), D folder split by
feature (relayout/), E var f = function → function f (tools/fn_decl_rewrite.cjs), and the blind naming
audit (tools/naming_audit_blind.cjs). Before any beautify run, present every option to the user with the
toolkit’s own current status, one decision each — the table, the tools and the gate each option then needs:
pipeline-stages (references/pipeline-stages.md) § 2b. Never run one the user did not choose (#1575).
4. Briefing a worker lane
Section titled “4. Briefing a worker lane”Write the brief in English (brief-template (references/brief-template.md)), then start ONE headless lane:
omp -p @<brief-file> --cwd <toolkit-root> --max-time <duration> --no-session --auto-approve < /dev/null > <log> 2>&1The steps a lane executes live only in omp-run-plan (references/omp-run-plan.md); the brief names paths, the
duration and which plan steps this lane owns. Completion = the process exits AND the report file exists; a lane
that exits without it failed, whatever its exit code. Run loop, replacing a stalled lane and small-model hygiene:
lane-orchestration (references/lane-orchestration.md).
5. Acceptance before “it opens in the editor” — or a PR
Section titled “5. Acceptance before “it opens in the editor” — or a PR”Why the editor step is not optional: a fidelity oracle is GREEN on a defect copied faithfully from the shipped data, and a headless build never runs the scene-loading path. Oracles green is not “a human can open it”.
6. Evidence standard — CONFIRMED vs REPORTED
Section titled “6. Evidence standard — CONFIRMED vs REPORTED”Every claim carries the exact command, its exit code, and the raw output saved to a path (never retyped). A
claim with no evidence path is unverified, not fact. An independent verify lane re-runs the acceptance
commands and labels each claim CONFIRMED / MISMATCH / UNVERIFIABLE; a phase is done only after that verdict.
In anything you report to the user, label each number CONFIRMED or REPORTED. Detail:
acceptance-and-evidence (references/acceptance-and-evidence.md).
7. Approval gates — stop and ask the user
Section titled “7. Approval gates — stop and ask the user”Never decide these yourself: a warning-ledger entry (the shipped WARNING_LEDGER.md template or the project’s own
gate.ledger ledger), a logic deviation from shipped behaviour, a deletion (including “unused” code), opening or
merging a PR, and tearing down the lane run.
Related
Section titled “Related”references/omp-run-plan.md— the steps anomplane executes (the SSOT; hand it to the lane)references/pipeline-stages.md— stage order, commands, exit codes, invariants, what is NOT verifiedreferences/lane-orchestration.md— preflight, starting and replacing anomplane, small-model hygienereferences/prerequisites.md— tools and downloads to tell the user before the first lanereferences/permissions.md— theBash(omp -p *)rule, and the user-runs-it fallbackreferences/acceptance-and-evidence.md— the acceptance gate, the ledger and deviation path, evidence labelsreferences/brief-template.md— the short brief that wraps the planThe1Studio/cocos-unbuild— the pipeline itself; its README## Tool indexis the per-tool referencet1k-cocos-playable-pla-from-ref— the sibling for a Unity reference build (a different input, no APK)