Skip to content

The open-source full-stack studio for Opus 5.5 motion video. Reverse engineering for any video. Code video with HTML: recreate, edit and render. BYOA + BYOK · Motion.md · Images, Video, Music & Voice.

feat(delivery): add verified Agent installation guide and controlled R2 upload

罗高8303d2227136
diff --git a/.github/scripts/publish-install-guide.mjs b/.github/scripts/publish-install-guide.mjs
new file mode 100644
index 00000000..7bd7330c
--- /dev/null
+++ b/.github/scripts/publish-install-guide.mjs
@@ -0,0 +1,67 @@
+import assert from 'node:assert/strict';
+import { createHash } from 'node:crypto';
+import { mkdtemp, readFile, writeFile, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { runFile, sha256, writeJSON } from '../../scripts/runtime-assets.mjs';
+
+export function storagePlan(record, { endpoint, bucket, publicOrigin }) {
+ const api = new URL(endpoint), origin = new URL(publicOrigin);
+ assert(api.protocol === 'https:' && api.hostname.endsWith('.r2.cloudflarestorage.com') && api.pathname === '/' && !api.port, 'Require an R2 S3 HTTPS origin');
+ for (const url of [api, origin]) assert(url.protocol === 'https:' && !url.username && !url.password && !url.search && !url.hash && url.pathname === '/', 'Require plain HTTPS origins');
+ assert(/^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$/.test(bucket || ''), 'Require the configured R2 bucket');
+ assert(['test', 'stable'].includes(record.channel), 'Unknown publication channel');
+ assert(/^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-test\.[1-9]\d*(?:\.[1-9]\d*)*)?$/.test(record.version), 'Invalid guide version');
+ assert.equal(record.version.includes('-test.'), record.channel === 'test', 'Channel and version differ');
+ const prefix = record.channel === 'test' ? 'open-motion/dev' : 'open-motion';
+ return { endpoint: api.origin, bucket, publicOrigin: origin.origin, versionKey: `${prefix}/versions/${record.version}/install.md`, fixedKey: `${prefix}/install.md` };
+}
+
+export async function publishGuide(directory, config, { run = runFile, fetcher = fetch } = {}) {
+ const file = path.join(directory, 'install.md'), record = JSON.parse(await readFile(path.join(directory, 'install-record.json'), 'utf8'));
+ assert.equal(record.candidate, false, 'Build previews cannot be published');
+ assert.equal(await sha256(file), record.guideSHA256, 'Generated guide changed after validation');
+ const plan = storagePlan(record, config), expected = await readFile(file);
+ const args = ['--endpoint-url', plan.endpoint, '--region', 'auto', 's3api'];
+ const aws = async (operation, rest) => JSON.parse(await run('aws', [...args, operation, '--bucket', plan.bucket, ...rest]) || '{}');
+ const work = await mkdtemp(path.join(os.tmpdir(), 'motion-install-publish-'));
+ try {
+ const get = async (key, destination) => {
+ try { const response = await aws('get-object', ['--key', key, destination]); return { etag: response.ETag, bytes: await readFile(destination) }; }
+ catch (error) { if (/NoSuchKey|\(404\)|Not Found/.test(error.message)) return null; throw error; }
+ };
+ const verifyPublic = async key => {
+ const url = new URL('/' + key, plan.publicOrigin);
+ const response = await fetcher(url, { redirect: 'error', signal: AbortSignal.timeout(20_000), headers: { 'cache-control': 'no-cache', 'user-agent': 'OpenMotion-install-publisher' } });
+ assert(response.ok, `Public installation guide returned HTTP ${response.status}`);
+ assert(Buffer.from(await response.arrayBuffer()).equals(expected), 'Public installation guide bytes differ');
+ };
+ const put = (key, condition, cache) => aws('put-object', ['--key', key, '--body', file, '--content-type', 'text/markdown; charset=utf-8', '--cache-control', cache, ...condition]);
+ const existing = await get(plan.versionKey, path.join(work, 'version.md'));
+ if (existing) assert(existing.bytes.equals(expected), 'An immutable version already has different installation instructions');
+ else await put(plan.versionKey, ['--if-none-match', '*'], 'public, max-age=31536000, immutable');
+ await verifyPublic(plan.versionKey);
+ const previous = await get(plan.fixedKey, path.join(work, 'previous.md'));
+ if (previous) {
+ assert(previous.etag, 'Existing guide requires an ETag for conditional promotion');
+ await writeFile(path.join(directory, 'previous-install.md'), previous.bytes);
+ }
+ const publication = { ...record, ...plan, previousSHA256: previous ? createHash('sha256').update(previous.bytes).digest('hex') : null,
+ previousETag: previous?.etag ?? null, phase: 'before-fixed-promotion' };
+ await writeJSON(path.join(directory, 'publication.json'), publication);
+ if (!previous?.bytes.equals(expected)) {
+ publication.phase = 'fixed-write-attempted'; await writeJSON(path.join(directory, 'publication.json'), publication);
+ await put(plan.fixedKey, previous ? ['--if-match', previous.etag] : ['--if-none-match', '*'], 'public, max-age=60, must-revalidate');
+ }
+ publication.phase = 'fixed-written-public-unverified'; await writeJSON(path.join(directory, 'publication.json'), publication);
+ await verifyPublic(plan.fixedKey);
+ publication.phase = 'verified'; await writeJSON(path.join(directory, 'publication.json'), publication);
+ return publication;
+ } finally { await rm(work, { recursive: true, force: true }); }
+}
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+ assert.equal(process.argv.length, 3, 'Usage: publish-install-guide.mjs <generated-guide-directory>');
+ for (const name of ['AWS_ACCESS_KEY_ID', 'AWS_SECRET_ACCESS_KEY']) assert(process.env[name], `Missing protected environment secret: ${name}`);
+ await publishGuide(path.resolve(process.argv[2]), { endpoint: process.env.MOTION_R2_ENDPOINT, bucket: process.env.MOTION_R2_BUCKET, publicOrigin: process.env.MOTION_INSTALL_PUBLIC_ORIGIN });
+}
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 05155512..3a69d08f 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -22,6 +22,18 @@ on:
description: 'Publication is disabled during migration; leave unchecked'
type: boolean
default: false
+ install_guide_package:
+ description: 'Already-published npm package name for an installation guide; empty keeps the ordinary build'
+ type: string
+ default: ''
+ install_guide_version:
+ description: 'Exact accepted npm version; non-empty selects guide validation instead of rebuilding the application'
+ type: string
+ default: ''
+ upload_install_guide:
+ description: 'Publish the verified guide to R2; requires the protected motion-install-docs environment'
+ type: boolean
+ default: false
permissions:
contents: read
@@ -32,6 +44,7 @@ concurrency:
jobs:
standalone:
+ if: github.event_name != 'workflow_dispatch' || inputs.install_guide_version == ''
runs-on: ubuntu-24.04
timeout-minutes: 40
defaults:
@@ -56,8 +69,10 @@ jobs:
env:
PACKAGE_FORMAT: ${{ inputs.format || 'npm' }}
PUBLISH: ${{ inputs.publish || false }}
+ UPLOAD_GUIDE: ${{ inputs.upload_install_guide || false }}
run: |
if [ "$PUBLISH" = true ]; then echo 'Motion publishing is disabled during migration.' >&2; exit 1; fi
+ if [ "${UPLOAD_GUIDE:-false}" = true ]; then echo 'An exact install_guide_version is required for guide upload.' >&2; exit 1; fi
case "$PACKAGE_FORMAT" in
npm|full) ;;
*) echo 'Unknown package format' >&2; exit 1 ;;
@@ -70,7 +85,7 @@ jobs:
npm run typecheck:studio
npm run build:studio
- name: Validate standalone installation and packaging
- run: node --experimental-strip-types --test tests/install.test.ts tests/npm-installer.test.ts tests/npm-package.test.ts tests/test-package.test.ts tests/source-install.test.ts tests/bootstrap.test.ts tests/mcp-registry.test.ts tests/phase1.test.ts tests/adapters.test.ts tests/package.test.ts tests/recreate-measure.test.ts tests/workflow.test.ts tests/catalog.test.ts tests/prism-templates.test.ts tests/extension-boundary.test.ts tests/connections.test.ts
+ run: node --experimental-strip-types --test tests/install.test.ts tests/npm-installer.test.ts tests/npm-package.test.ts tests/test-package.test.ts tests/source-install.test.ts tests/bootstrap.test.ts tests/mcp-registry.test.ts tests/phase1.test.ts tests/adapters.test.ts tests/package.test.ts tests/recreate-measure.test.ts tests/workflow.test.ts tests/catalog.test.ts tests/prism-templates.test.ts tests/extension-boundary.test.ts tests/connections.test.ts tests/install-guide.test.ts
- name: Studio regression
run: npm run test:studio -- --maxWorkers=2
- name: Build phase-one ZIP and exercise all public tools
@@ -92,6 +107,122 @@ jobs:
node scripts/test-package.mjs build "$target" "$version" --template-env="$TEMPLATE_ENVIRONMENT"
done
fi
+ - name: Generate candidate installation guide
+ if: (inputs.format || 'npm') == 'npm' && (inputs.template_environment || 'prod') == 'prod'
+ run: |
+ version=$(node scripts/test-package.mjs version "$GITHUB_RUN_NUMBER" "${GITHUB_RUN_ATTEMPT:-1}")
+ candidate=$(node --input-type=module -e 'import fs from "node:fs"; const m=JSON.parse(fs.readFileSync(process.argv[1]));process.stdout.write(m.installer.url.replace(/^\.\//,""));' "dist/$version/release-npm.json")
+ node --experimental-strip-types scripts/install-guide.mjs "dist/$version/$candidate" .artifacts/install-guide --candidate
+ - name: Retain candidate installation guide for review
+ if: (inputs.format || 'npm') == 'npm' && (inputs.template_environment || 'prod') == 'prod'
+ uses: actions/[email protected]
+ with:
+ name: motion-install-guide-preview-${{ github.run_id }}-${{ github.run_attempt }}
+ path: .artifacts/install-guide/
+ retention-days: 14
+ if-no-files-found: error
- name: Record validation scope
run: |
- echo 'Motion standalone artifacts were built and checked; no package or release was published.' >> "$GITHUB_STEP_SUMMARY"
+ echo 'Motion artifacts were built and checked; the candidate guide is a review artifact only. No npm, R2 or Release publication occurred.' >> "$GITHUB_STEP_SUMMARY"
+
+ install-guide-validation:
+ if: github.event_name == 'workflow_dispatch' && inputs.install_guide_version != ''
+ runs-on: ubuntu-24.04
+ timeout-minutes: 10
+ env:
+ GUIDE_PACKAGE: ${{ inputs.install_guide_package }}
+ GUIDE_VERSION: ${{ inputs.install_guide_version }}
+ GUIDE_DIRECTORY: .artifacts/install-guide-validated
+ outputs:
+ channel: ${{ steps.identity.outputs.channel }}
+ steps:
+ - uses: actions/[email protected]
+ with:
+ ref: ${{ github.sha }}
+ - uses: actions/setup-node@v6
+ with:
+ node-version: '26.11.1'
+ - name: Validate exact package selection
+ id: identity
+ run: |
+ node --experimental-strip-types --input-type=module <<'JS'
+ import { appendFileSync } from 'node:fs';
+ import { validateGuideSpec } from './scripts/install-guide.mjs';
+ const channel = validateGuideSpec(process.env.GUIDE_PACKAGE, process.env.GUIDE_VERSION);
+ appendFileSync(process.env.GITHUB_OUTPUT, `channel=${channel}\n`);
+ JS
+ - name: Fetch the actual published package without running its scripts
+ run: |
+ mkdir -p "$RUNNER_TEMP/motion-guide-package"
+ npm pack "$GUIDE_PACKAGE@$GUIDE_VERSION" --ignore-scripts --json --pack-destination "$RUNNER_TEMP/motion-guide-package" > "$RUNNER_TEMP/motion-guide-package/pack.json"
+ candidate=$(node --input-type=module -e 'import fs from "node:fs";import path from "node:path";const [p]=JSON.parse(fs.readFileSync(process.argv[1]));if(path.basename(p.filename)!==p.filename)throw Error("Unsafe npm filename");process.stdout.write(p.filename);' "$RUNNER_TEMP/motion-guide-package/pack.json")
+ node --experimental-strip-types scripts/install-guide.mjs "$RUNNER_TEMP/motion-guide-package/$candidate" "$GUIDE_DIRECTORY"
+ node --input-type=module <<'JS'
+ import { readFileSync } from 'node:fs';
+ import assert from 'node:assert/strict';
+ const record=JSON.parse(readFileSync(process.env.GUIDE_DIRECTORY+'/install-record.json'));
+ assert.equal(record.packageName,process.env.GUIDE_PACKAGE);
+ assert.equal(record.version,process.env.GUIDE_VERSION);
+ JS
+ - name: Retain verified guide and immutable package identity
+ uses: actions/[email protected]
+ with:
+ name: motion-install-guide-validated-${{ github.run_id }}-${{ github.run_attempt }}
+ path: ${{ env.GUIDE_DIRECTORY }}/
+ retention-days: 14
+ if-no-files-found: error
+
+ publish-install-guide:
+ needs: install-guide-validation
+ if: github.event_name == 'workflow_dispatch' && inputs.upload_install_guide == true
+ runs-on: ubuntu-24.04
+ timeout-minutes: 10
+ environment: motion-install-docs
+ concurrency:
+ group: motion-install-guide-${{ needs.install-guide-validation.outputs.channel }}
+ cancel-in-progress: false
+ steps:
+ - uses: actions/[email protected]
+ with:
+ ref: ${{ github.sha }}
+ - uses: actions/setup-node@v6
+ with:
+ node-version: '26.11.1'
+ - uses: actions/[email protected]
+ with:
+ name: motion-install-guide-validated-${{ github.run_id }}-${{ github.run_attempt }}
+ path: ${{ runner.temp }}/motion-install-guide
+ - name: Confirm the accepted channel still selects this exact version
+ env:
+ GUIDE_PACKAGE: ${{ inputs.install_guide_package }}
+ GUIDE_VERSION: ${{ inputs.install_guide_version }}
+ GUIDE_CHANNEL: ${{ needs.install-guide-validation.outputs.channel }}
+ APPROVED_PACKAGE: ${{ vars.MOTION_NPM_PACKAGE }}
+ run: |
+ if [ -z "$APPROVED_PACKAGE" ] || [ "$GUIDE_PACKAGE" != "$APPROVED_PACKAGE" ]; then echo 'Set the approved MOTION_NPM_PACKAGE in the protected publication environment.' >&2; exit 1; fi
+ tag=test
+ if [ "$GUIDE_CHANNEL" = stable ]; then tag=latest; fi
+ actual=$(npm view "$GUIDE_PACKAGE@$tag" version)
+ if [ "$actual" != "$GUIDE_VERSION" ]; then echo 'The accepted npm channel does not select this exact version.' >&2; exit 1; fi
+ - name: Upload versioned guide, then conditionally update and verify the fixed URL
+ id: upload
+ env:
+ AWS_ACCESS_KEY_ID: ${{ secrets.MOTION_R2_ACCESS_KEY_ID }}
+ AWS_SECRET_ACCESS_KEY: ${{ secrets.MOTION_R2_SECRET_ACCESS_KEY }}
+ AWS_EC2_METADATA_DISABLED: 'true'
+ AWS_MAX_ATTEMPTS: '3'
+ AWS_PAGER: ''
+ MOTION_R2_ENDPOINT: ${{ secrets.MOTION_R2_ENDPOINT }}
+ MOTION_R2_BUCKET: ${{ vars.MOTION_R2_BUCKET }}
+ MOTION_INSTALL_PUBLIC_ORIGIN: ${{ vars.MOTION_INSTALL_PUBLIC_ORIGIN }}
+ run: |
+ aws --version
+ node .github/scripts/publish-install-guide.mjs "$RUNNER_TEMP/motion-install-guide"
+ - name: Retain publication state and prior instructions for recovery
+ if: always()
+ uses: actions/[email protected]
+ with:
+ name: motion-install-guide-publication-${{ github.run_id }}-${{ github.run_attempt }}
+ path: ${{ runner.temp }}/motion-install-guide/
+ retention-days: 30
+ if-no-files-found: warn
diff --git a/docs/README.md b/docs/README.md
index 2e9ac412..b5772344 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -19,6 +19,7 @@
- [motion-director.md](motion-director.md)
- [motion-extension-scope.md](motion-extension-scope.md)
- [npm-installation.md](npm-installation.md)
+- [Agent installation guide source template](install.md)
- [test and stable acceptance](release-guide.md)
- [product/architecture.md](product/architecture.md)
- [product/media-generation-design.md](product/media-generation-design.md)
diff --git a/docs/install.md b/docs/install.md
new file mode 100644
index 00000000..462c9658
--- /dev/null
+++ b/docs/install.md
@@ -0,0 +1,36 @@
+# Install OpenMotion {{VERSION}}
+
+This guide pins the complete npm application `{{PACKAGE_SPEC}}` on the **{{CHANNEL}}** software channel. It includes MCP, the built Studio and five Skills. The default template environment is **{{TEMPLATE_ENVIRONMENT}}**; a software test version does not select DEV templates.
+
+If you are reading this file in the source repository and see `{{...}}`, it is a template, not a published installation instruction. Do not guess a package name or version.
+
+## Instructions for the Agent
+
+1. Check the user's OS/CPU, Node.js and npm, and selected Agent. Node.js 22.18+ with npm and the Agent must already be installed. Supported native targets: {{TARGETS}}. Do not claim support for another target from package-download success.
+2. Use the current host if it is supported; otherwise ask the user to select one. Setup supports `codex`, `claude`, `deepseek` and `workbuddy`. Configure only that host. Preserve existing projects, credentials and unrelated MCP/Skills settings.
+3. For a test candidate, use a separate host profile, application home, project data and Skills directory. Keep those paths and reuse them for prepare and future reconnects. The [platform installation recipes]({{DETAILS_URL}}) describe the actual supported options. Do not run a test candidate into the user's daily profile by default.
+4. Install the exact package version below, run prepare, then reconnect/reload that host. Confirm the application version, template environment, eleven public Tools and five Skills. A registration entry alone does not prove the host has loaded them.
+5. Report the result and any failed step. Introduce the available capabilities and wait for the user's next request. Installation does not authorize generating a video or calling a paid model.
+
+For a normal Codex installation, the command shape is:
+
+```sh
+npx --yes --package "{{PACKAGE_SPEC}}" openmotion setup --host codex
+npx --yes --package "{{PACKAGE_SPEC}}" openmotion prepare
+```
+
+For test installations, add the isolated paths/profile from step 3 before executing. For another supported host, use its setup `--host` value and documented profile settings. Setup installs the selected host's MCP and Skills; a second installer or application/manifest download is unnecessary.
+
+## Runtime and environment
+
+Setup copies the checked application into a managed writable directory and installs its locked production npm dependencies. The application and user projects do not run from the temporary npx cache. FFmpeg, ffprobe and the browser are downloaded and verified by prepare or first native use; this is not an offline package.
+
+There is no persisted switch-environment command in this version. Internal DEV testing uses its separately configured installation; merely setting an environment variable while running setup does not configure a later desktop Agent. Do not silently fall back from one environment to another.
+
+## Upgrade, recovery and feedback
+
+Pin this exact version when reproducing an issue. Before an upgrade, finish active exports, back up project data and close only this installation's old MCP/backend connections; reconnect after setup/prepare. Preserve unrelated settings. Older applications may not read newer data formats: compatible reinstall or backup restoration requires separate verification. Moving a server-side default does not downgrade installed clients.
+
+Include the exact version, OS/CPU, Node/Agent versions, template environment, project/revision, reproduction and redacted logs in a report. Installation, real Agent creation, technical MP4 export and human audiovisual acceptance are separate results.
+
+Release identity: source `{{COMMIT}}`; npm tgz SHA256 `{{TGZ_SHA256}}`. [Source and installation details]({{DETAILS_URL}}).
diff --git a/docs/npm-installation.md b/docs/npm-installation.md
index d8eb9283..1cd5f537 100644
--- a/docs/npm-installation.md
+++ b/docs/npm-installation.md
@@ -101,3 +101,7 @@ The runtime lock pins HTTPS URLs, versions, target OS/CPU and SHA256 for FFmpeg,
A local `--manifest /absolute/release-npm.json` remains available for legacy delivery and controlled fixtures. HTTP, URL credentials, unsafe extraction paths and invalid hashes are rejected. Do not remove a leftover install lock until its owning process is confirmed stopped.
For defects, include exact package/app version, source SHA, OS/CPU, Node/Agent version, template environment/catalog version, project/revision, reproduction steps and redacted logs. Installation, native preparation, host discovery, model creation, technical MP4 checks and human playback are separate evidence. Follow the [acceptance manual](release-guide.md); unrun Windows/host/creation checks remain unrun.
+
+## Shared Agent installation entry
+
+The hosted [installation guide template](install.md) provides the short Agent entry. Ordinary CI retains a candidate preview; the controlled guide mode fetches an already published exact npm version before any R2 upload. Public URLs, environment credentials, channel acceptance and deployment restrictions must be configured separately. See [hosted instruction publication](release-guide.md#hosted-installation-instructions).
diff --git a/docs/product/architecture.md b/docs/product/architecture.md
index faa5672d..67f97a49 100644
--- a/docs/product/architecture.md
+++ b/docs/product/architecture.md
@@ -183,7 +183,7 @@ Explicit test/stable prod builds produce publishable artifact metadata with test
## 演进约束
-本地测试包按 mac-arm64 / win-x64 准备固定公开原生依赖。The application npm format is the default; complete platform ZIPs are backups. Native installation, Agent creation and human playback need separate evidence. Projects remain outside the package; CI only builds and validates, without upload or publication. See [package checks](../test-packages.md).
+本地测试包按 mac-arm64 / win-x64 准备固定公开原生依赖。The application npm format is the default; complete platform ZIPs are backups. Native installation, Agent creation and human playback need separate evidence. Projects remain outside the package; ordinary CI builds and validates, and retains candidate installation-guide previews. A separate manual guide mode can verify a published npm version and, only through a configured protected environment, upload versioned/fixed instructions to R2. It does not publish npm or Release assets. The guide path, environment prerequisites and current default-branch dispatch limitation are documented in the release guide. See [package checks](../test-packages.md).
已确认方向是继续支持多 Agent 接入、可编辑工程与一个工作区内的发现/制作闭环。
diff --git a/docs/release-guide.md b/docs/release-guide.md
index 4aad953d..5b64cd29 100644
--- a/docs/release-guide.md
+++ b/docs/release-guide.md
@@ -1,6 +1,6 @@
# Test and stable package acceptance
-This is the maintainer and tester manual for the application npm format. It defines required checks, not a claim that all platforms or a published registry version have passed. [Installation](npm-installation.md) supplies macOS/PowerShell commands, DEV template setup, host adapters and recovery boundaries. Ordinary CI still does not upload or publish packages.
+This is the maintainer and tester manual for the application npm format. It defines required checks, not a claim that all platforms or a published registry version have passed. [Installation](npm-installation.md) supplies macOS/PowerShell commands, DEV template setup, host adapters and recovery boundaries. Ordinary CI retains candidate installation instructions for review; npm, R2 and Release publication remain separate controlled actions.
## One record per candidate
@@ -47,3 +47,32 @@ Confirm npm ownership/authentication and target versions first. A public Release
Stop recommending a failed candidate. Under channel-management authorization, point test/latest back to an already verified compatible version; do not overwrite/unpublish it as a recovery mechanism. Users still need an explicit compatible reinstall/reconnect or backup restoration. If there is no prior stable release, state that instead of inventing a rollback target.
Each defect needs exact package/source/OS/host/environment/catalog identity, project/revision, steps, expected/actual behavior, redacted logs and artifact links. Keep installation, host discovery, technical export, real creation and human acceptance as separate statuses.
+
+## Hosted installation instructions
+
+[docs/install.md](install.md) is the public Agent-facing source template. The generator reads the actual complete npm tgz and its embedded manifest, pins the npm name/version and built source SHA, and records the guide and package hashes. It does not build or publish the application.
+
+Ordinary npm/prod CI builds generate a **candidate-only** guide and retain it as an Actions artifact for 14 days. The publisher rejects candidate previews. DEV/private packages cannot produce a public guide.
+
+The existing `Motion standalone checks` workflow has a separate manual guide mode:
+
+1. Set `install_guide_package` and an exact `install_guide_version` already published to npm. Leave `upload_install_guide=false` to fetch the registry package with lifecycle scripts disabled, render its guide and retain the result without R2 credentials.
+2. Before promoting an entry, complete registry/package acceptance and select that version through npm `test` or `latest`. A guide publication does not publish npm or move its tags.
+3. An explicitly authorized run with `upload_install_guide=true` enters the protected `motion-install-docs` environment. It checks the approved package name and current npm channel, creates immutable version instructions, verifies the public bytes, saves the prior fixed instructions and conditionally updates the fixed entry. The canonical public URLs must return matching bytes; a cache-busting URL does not prove the fixed entry is current.
+4. Test software uses `open-motion/dev/install.md`; stable uses `open-motion/install.md`. Each also has `versions/<exact-version>/install.md` under the same prefix. The `dev` path is the existing proposed software test-channel path, not a switch to DEV template data.
+
+After publication, the website can give the Agent a short prompt: "Read `<approved-public-origin>/open-motion/install.md`, install OpenMotion MCP and Skills for my current supported Agent host, preserve existing projects/settings, and report installation and preparation results." Use `/open-motion/dev/install.md` for the test software channel. These are path examples until the public origin and publication are verified.
+
+An administrator must configure `motion-install-docs` with required reviewers and deployment-branch restrictions for the reviewed publishing branch. Place credentials on this environment, not in the low-privilege PR job. No R2 resource, credential or environment is created by this PR.
+
+| Environment setting | Purpose |
+| --- | --- |
+| Secret `MOTION_R2_ACCESS_KEY_ID` / `MOTION_R2_SECRET_ACCESS_KEY` | Bucket-scoped S3 credentials |
+| Secret `MOTION_R2_ENDPOINT` | R2 S3 HTTPS origin |
+| Variable `MOTION_R2_BUCKET` | Approved destination bucket |
+| Variable `MOTION_INSTALL_PUBLIC_ORIGIN` | Public HTTPS origin for that bucket; routing must already work |
+| Variable `MOTION_NPM_PACKAGE` | Approved public npm package name |
+
+The publisher uses the runner's AWS CLI with conditional writes and short fixed-entry caching. Publication records and prior public instructions are retained for 30 days. If readback fails, the run fails; inspect `publication.json` and the previous bytes before a separately authorized recovery. A network failure during `fixed-write-attempted` may mean the write completed: check storage rather than assuming nothing changed. Restore only the intended guide/channel; this does not downgrade installed clients or migrate projects.
+
+The repository default branch currently contains the legacy project and lacks the Motion manual-dispatch trigger. Do not assume a Run workflow button is available from this feature PR. Registering a trusted dispatch entry/default-branch workflow remains a separate administrator task; this PR does not change main.
diff --git a/docs/test-packages.md b/docs/test-packages.md
index da7382d9..c5554178 100644
--- a/docs/test-packages.md
+++ b/docs/test-packages.md
@@ -17,7 +17,7 @@ MCP 公开入口由包内 `shared/mcp-release.json` 固化,详见[一期注册
| `npm`(默认) | Application npm `.tgz` with embedded app/manifest, plus external archive, release record and SHA256 | 目标机按应用 lockfile 安装 npm 依赖;首次需要时下载固定原生工具 |
| `full`(备用) | Mac arm64 / Windows x64 完整 ZIP、SHA256、`release-<target>.json` | 内置目标平台 Node、生产依赖和原生工具 |
-当前 本仓库工作流只构建和校验,不上传 Actions 制品,不发布 npm、Release 或存储对象;两种格式误勾 `publish` 均会失败。本地构建的制品位于 `dist/`,The tgz alone is sufficient for setup; adjacent application/manifest files are evidence and an explicit-manifest fallback. See [installation](npm-installation.md) and [test/stable acceptance](release-guide.md).
+Ordinary builds retain candidate installation-guide artifacts for review; they do not publish npm, Release or R2 objects. Separate manual guide publication follows the release guide; 两种格式误勾 `publish` 均会失败。本地构建的制品位于 `dist/`,The tgz alone is sufficient for setup; adjacent application/manifest files are evidence and an explicit-manifest fallback. See [installation](npm-installation.md) and [test/stable acceptance](release-guide.md).
Explicit builds accept stable `MAJOR.MINOR.PATCH` or `MAJOR.MINOR.PATCH-test.N[.N]`. The CI helper selects next-patch `test.<run>.<attempt>` (for example, 0.6.3 → 0.6.4-test.42.1). All embedded identities agree; output directories cannot be overwritten and source versions do not change. DEV and unversioned local builds remain private; explicit prod test/stable metadata selects test/stage. Publication remains disabled.
diff --git a/scripts/distribution.ts b/scripts/distribution.ts
index 4eed6157..46b1d6ae 100644
--- a/scripts/distribution.ts
+++ b/scripts/distribution.ts
@@ -11,7 +11,7 @@ export const distributionDocuments = [
'docs/product/architecture.md', 'docs/product/media-generation-design.md',
'docs/agent-adapters.md', 'docs/browser-runtime.md', 'docs/design-system.md', 'docs/editor-fork.md',
'docs/hyperframes.md', 'docs/mcp-phase1-tools.md', 'docs/model-gateway.md', 'docs/motion-director.md',
- 'docs/motion-extension-scope.md', 'docs/npm-installation.md', 'docs/release-guide.md', 'docs/project-workspace.md',
+ 'docs/motion-extension-scope.md', 'docs/npm-installation.md', 'docs/install.md', 'docs/release-guide.md', 'docs/project-workspace.md',
'docs/repository-migration.md', 'docs/session-architecture.md', 'docs/shared-editor.md',
'docs/README.zh-CN.md', 'docs/usage.md', 'docs/motion-md.md', 'docs/motion-md.zh-CN.md',
'docs/collections/README.md', 'docs/collections/README.zh-CN.md',
diff --git a/scripts/install-guide.mjs b/scripts/install-guide.mjs
new file mode 100644
index 00000000..e0d0b4e6
--- /dev/null
+++ b/scripts/install-guide.mjs
@@ -0,0 +1,55 @@
+import assert from 'node:assert/strict';
+import { mkdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { runFile, sha256, writeAtomic, writeJSON } from './runtime-assets.mjs';
+import { checkReleaseVersion } from './test-package.mjs';
+
+export function validateGuideSpec(name, version) {
+ assert.match(name || '', /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/, 'Require an npm package name');
+ assert(name.length <= 214, 'npm package name is too long');
+ checkReleaseVersion(version);
+ return version.includes('-test.') ? 'test' : 'stable';
+}
+
+export function validateGuideIdentity(pkg, manifest) {
+ validateGuideSpec(pkg.name, pkg.version);
+ assert.equal(pkg.private, false, 'Only public release candidates may have a public installation guide');
+ assert.equal(pkg.version, manifest.version, 'Package and embedded manifest versions differ');
+ assert.equal(manifest.schemaVersion, 1, 'Unsupported release manifest');
+ assert.equal(manifest.templateEnvironment, 'prod', 'Public guides require prod defaults');
+ assert.equal(pkg.bin?.openmotion, 'scripts/npm-installer.mjs', 'Missing Motion entry point');
+ assert.match(manifest.commit || '', /^[a-f0-9]{40}$/, 'Require the built source SHA');
+ for (const hash of [manifest.application?.sha256, manifest.locks?.npm, manifest.locks?.native]) assert.match(hash || '', /^[a-f0-9]{64}$/, 'Require release checksums');
+ const targets = Object.values(manifest.runtime?.targets || {});
+ assert(targets.length > 0 && targets.every(t => t.platform && t.arch && t.minimumOS), 'Require native target declarations');
+ return pkg.version.includes('-test.') ? 'test' : 'stable';
+}
+
+export async function generateInstallGuide(tgz, output, candidate = false) {
+ const readEntry = async entry => JSON.parse(await runFile('tar', ['-xOf', path.resolve(tgz), entry]));
+ const pkg = await readEntry('package/package.json'), manifest = await readEntry('package/payload/release-npm.json');
+ const channel = validateGuideIdentity(pkg, manifest);
+ const digest = await sha256(tgz), packageSpec = `${pkg.name}@${pkg.version}`;
+ const values = { VERSION: pkg.version, PACKAGE_SPEC: packageSpec, CHANNEL: channel, COMMIT: manifest.commit,
+ TEMPLATE_ENVIRONMENT: manifest.templateEnvironment, TGZ_SHA256: digest,
+ TARGETS: Object.values(manifest.runtime.targets).map(t => `${t.platform}/${t.arch} (${t.minimumOS}+)`).join(', '),
+ DETAILS_URL: `https://github.com/nexu-io/html-anything/blob/${manifest.commit}/docs/npm-installation.md` };
+ const template = await readFile(new URL('../docs/install.md', import.meta.url), 'utf8');
+ // The repository warning is unnecessary after all release placeholders are resolved.
+ const text = (candidate ? '> Build preview only: this candidate is not an approved registry installation entry.\n\n' : '') + template.replace(/^If you are reading this file.*\n\n/m, '').replace(/\{\{([A-Z0-9_]+)\}\}/g, (_, key) => {
+ assert(Object.hasOwn(values, key), 'Unknown installation placeholder: ' + key); return values[key];
+ });
+ assert(!text.includes('{{'), 'Installation guide has unresolved placeholders');
+ await mkdir(output, { recursive: true });
+ await writeAtomic(path.join(output, 'install.md'), text);
+ const record = { schemaVersion: 1, candidate, packageName: pkg.name, version: pkg.version, packageSpec, channel,
+ templateEnvironment: manifest.templateEnvironment, commit: manifest.commit, tgzSHA256: digest,
+ applicationSHA256: manifest.application.sha256, locks: manifest.locks, guideSHA256: await sha256(path.join(output, 'install.md')) };
+ await writeJSON(path.join(output, 'install-record.json'), record);
+ return record;
+}
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+ assert([4, 5].includes(process.argv.length) && (process.argv[4] === undefined || process.argv[4] === '--candidate'), 'Usage: install-guide.mjs <complete-npm.tgz> <output-directory> [--candidate]');
+ console.log(JSON.stringify(await generateInstallGuide(process.argv[2], path.resolve(process.argv[3]), process.argv[4] === '--candidate')));
+}
diff --git a/tests/install-guide.test.ts b/tests/install-guide.test.ts
new file mode 100644
index 00000000..6a2f6f35
--- /dev/null
+++ b/tests/install-guide.test.ts
@@ -0,0 +1,108 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, readFile, writeFile, rm } from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { generateInstallGuide, validateGuideSpec, validateGuideIdentity } from '../scripts/install-guide.mjs';
+import { publishGuide, storagePlan } from '../.github/scripts/publish-install-guide.mjs';
+import { runFile } from '../scripts/runtime-assets.mjs';
+
+const pkg = { name: '@example/motion', version: '0.6.4-test.1', private: false, bin: { openmotion: 'scripts/npm-installer.mjs' } };
+const manifest = { schemaVersion: 1, version: pkg.version, templateEnvironment: 'prod', commit: 'a'.repeat(40),
+ application: { sha256: 'b'.repeat(64) }, locks: { npm: 'c'.repeat(64), native: 'd'.repeat(64) },
+ runtime: { targets: { mac: { platform: 'darwin', arch: 'arm64', minimumOS: '26.0' } } } };
+const config = { endpoint: 'https://example.r2.cloudflarestorage.com', bucket: 'example-guides', publicOrigin: 'https://download.example.invalid' };
+async function fixture(t: any, candidate = false) {
+ const root = await mkdtemp(path.join(os.tmpdir(), 'motion-guide-test-')); t.after(() => rm(root, { recursive: true, force: true }));
+ await mkdir(path.join(root, 'package/payload'), { recursive: true });
+ await writeFile(path.join(root, 'package/package.json'), JSON.stringify(pkg));
+ await writeFile(path.join(root, 'package/payload/release-npm.json'), JSON.stringify(manifest));
+ const tgz = path.join(root, 'candidate.tgz');
+ await runFile('tar', ['-czf', tgz, '-C', root, 'package']);
+ const directory = path.join(root, 'guide'), record = await generateInstallGuide(tgz, directory, candidate);
+ return { directory, record };
+}
+function storage(directory: string, record: any, previous = 'previous accepted instructions') {
+ const plan = storagePlan(record, config), objects = new Map<string, Buffer>(), writes: any[] = [];
+ objects.set(plan.fixedKey, Buffer.from(previous));
+ const run = async (command: string, args: string[]) => {
+ assert.equal(command, 'aws');
+ const operation = args[args.indexOf('s3api') + 1], key = args[args.indexOf('--key') + 1];
+ if (operation === 'get-object') {
+ if (!objects.has(key)) throw new Error('AWS (NoSuchKey)');
+ await writeFile(args.at(-1)!, objects.get(key)!); return JSON.stringify({ ETag: '"previous-etag"' });
+ }
+ assert.equal(operation, 'put-object');
+ const bytes = await readFile(args[args.indexOf('--body') + 1]);
+ writes.push({ key, args }); objects.set(key, bytes); return JSON.stringify({ ETag: '"new-etag"' });
+ };
+ const fetcher = async (url: URL) => new Response(objects.get(url.pathname.slice(1)) ?? 'not found', { status: objects.has(url.pathname.slice(1)) ? 200 : 404 });
+ return { plan, objects, writes, run, fetcher };
+}
+
+test('guide rendering pins the exact npm package, built source and hash while rejecting unresolved or private identities', async t => {
+ const { directory, record } = await fixture(t);
+ const text = await readFile(path.join(directory, 'install.md'), 'utf8');
+ assert(text.includes(`npx --yes --package "${pkg.name}@${pkg.version}"`));
+ assert(text.includes(manifest.commit) && text.includes(record.tgzSHA256));
+ assert(!text.includes('{{') && !text.includes('see `{{...}}`'));
+ assert(text.includes('eleven public Tools') && text.includes('five Skills'));
+ assert.equal(record.channel, 'test'); assert.equal(record.candidate, false);
+ assert.equal(validateGuideSpec('openmotion', '0.6.4'), 'stable');
+ for (const name of ['https://evil.invalid/a', 'x;echo bad', '--script', '@bad/no/extra']) assert.throws(() => validateGuideSpec(name, pkg.version));
+ assert.throws(() => validateGuideSpec(pkg.name, 'latest'));
+ assert.throws(() => validateGuideIdentity({ ...pkg, private: true }, manifest), /public/);
+ assert.throws(() => validateGuideIdentity(pkg, { ...manifest, templateEnvironment: 'dev' }), /prod/);
+ assert.throws(() => validateGuideIdentity(pkg, { ...manifest, version: '0.6.4' }), /versions differ/);
+});
+
+test('publication verifies the immutable URL before conditional fixed promotion and retains the prior guide', async t => {
+ const { directory, record } = await fixture(t), store = storage(directory, record);
+ const result = await publishGuide(directory, config, { ...store, fetcher: async (url: URL) => {
+ assert.equal(url.search, '', 'Verify the canonical URL that users receive');
+ return store.fetcher(url);
+ } });
+ assert.deepEqual(store.writes.map(x => x.key), [store.plan.versionKey, store.plan.fixedKey]);
+ assert(store.writes[0].args.includes('--if-none-match'));
+ assert(store.writes[1].args.includes('--if-match') && store.writes[1].args.includes('"previous-etag"'));
+ assert(store.writes[1].args.includes('public, max-age=60, must-revalidate'));
+ assert.equal(await readFile(path.join(directory, 'previous-install.md'), 'utf8'), 'previous accepted instructions');
+ assert.equal(result.phase, 'verified'); assert(result.previousSHA256);
+});
+
+test('an immutable version mismatch or failed public version verification leaves the fixed entry untouched', async t => {
+ const { directory, record } = await fixture(t), store = storage(directory, record);
+ store.objects.set(store.plan.versionKey, Buffer.from('other release bytes'));
+ await assert.rejects(publishGuide(directory, config, store), /immutable/); assert.equal(store.writes.length, 0);
+ store.objects.delete(store.plan.versionKey);
+ await assert.rejects(publishGuide(directory, config, { ...store, fetcher: async () => new Response('wrong edge bytes') }), /bytes differ/);
+ assert.equal(store.objects.get(store.plan.fixedKey)!.toString(), 'previous accepted instructions');
+});
+
+test('a post-promotion public failure records the partial state and preserves recovery bytes', async t => {
+ const { directory, record } = await fixture(t), store = storage(directory, record);
+ await assert.rejects(publishGuide(directory, config, { ...store, fetcher: async (url: URL) => url.pathname.endsWith('/versions/'+record.version+'/install.md') ? store.fetcher(url) : new Response('stale edge bytes') }), /bytes differ/);
+ const state = JSON.parse(await readFile(path.join(directory, 'publication.json'), 'utf8'));
+ assert.equal(state.phase, 'fixed-written-public-unverified');
+ assert.equal(await readFile(path.join(directory, 'previous-install.md'), 'utf8'), 'previous accepted instructions');
+});
+
+test('candidate previews, changed guide bytes and unsafe storage destinations cannot publish', async t => {
+ const preview = await fixture(t, true); let calls = 0;
+ await assert.rejects(publishGuide(preview.directory, config, { run: async () => { calls++; return '{}'; } }), /previews/); assert.equal(calls, 0);
+ const { directory, record } = await fixture(t); await writeFile(path.join(directory, 'install.md'), 'tampered');
+ await assert.rejects(publishGuide(directory, config), /changed after validation/);
+ for (const endpoint of ['http://example.r2.cloudflarestorage.com', 'https://evil.invalid', 'https://user:[email protected]']) assert.throws(() => storagePlan(record, { ...config, endpoint }));
+ assert.throws(() => storagePlan(record, { ...config, bucket: '../other' }));
+});
+
+test('CI publication stays manual, disabled by default and in the dedicated credential environment', async () => {
+ const workflow = await readFile(new URL('../.github/workflows/ci.yml', import.meta.url), 'utf8');
+ assert(workflow.includes('upload_install_guide:') && workflow.includes("type: boolean\n default: false"));
+ const publish = workflow.split(' publish-install-guide:\n')[1];
+ assert(publish.includes("github.event_name == 'workflow_dispatch' && inputs.upload_install_guide == true"));
+ assert(publish.includes('environment: motion-install-docs') && publish.includes('needs: install-guide-validation'));
+ assert(publish.includes('Confirm the accepted channel still selects this exact version'));
+ assert(!workflow.split(' publish-install-guide:\n')[0].includes('secrets.MOTION_R2_'));
+ assert(workflow.includes('candidate installation guide') && workflow.includes('--candidate'));
+});