mirror of
https://github.com/hansjone/oclaw.git
synced 2026-10-12 11:43:25 +08:00
oliver
dbbe3add6a
同时收敛启动与运维脚本默认行为（含 wiki worker）、更新 Admin 可观测性与相关测试，降低首轮时延并提高运行稳定性。 Made-with: Cursor
54 lines
2.9 KiB
Markdown
54 lines
2.9 KiB
Markdown
# ACPX Extension Notes
|
|
|
|
This file applies to work under `extensions/acpx/`.
|
|
|
|
## Purpose
|
|
|
|
The bundled ACPX extension is a thin OpenClaw wrapper around the published `acpx` package. Keep reusable ACP runtime logic in `openclaw/acpx`, not in this extension.
|
|
|
|
## Default Version Policy
|
|
|
|
- `extensions/acpx/package.json` should point at a published npm release by default.
|
|
- Do not leave the extension pinned to a temporary GitHub commit or local checkout once the ACPX release exists.
|
|
- Do not leave temporary pnpm build-script allowlist exceptions behind after switching back to a published ACPX package.
|
|
|
|
## Unreleased ACPX Development Flow
|
|
|
|
Use this flow when OpenClaw needs unreleased ACPX changes before the ACPX version is published.
|
|
|
|
1. Make the ACPX code change in the `openclaw/acpx` repo first.
|
|
2. In OpenClaw, temporarily point `extensions/acpx/package.json` at the ACPX GitHub commit you need.
|
|
3. If pnpm blocks ACPX lifecycle/build scripts for that temporary GitHub-sourced package, temporarily add `acpx` to `onlyBuiltDependencies` in both `package.json` and `pnpm-workspace.yaml`.
|
|
4. Refresh the root workspace lock:
|
|
- `pnpm install --lockfile-only --filter ./extensions/acpx`
|
|
5. Refresh the extension-local npm lock for install metadata:
|
|
- `cd extensions/acpx && npm install --package-lock-only --ignore-scripts`
|
|
6. Rebuild OpenClaw and restart the gateway before doing live ACP validation.
|
|
7. Once ACPX is released, switch `extensions/acpx/package.json` back to the published npm version and refresh the same lockfiles again.
|
|
8. Remove any temporary `acpx` build-script allowlist entries that were only needed for the GitHub-sourced development pin.
|
|
|
|
## Lockfile Notes
|
|
|
|
- `pnpm-lock.yaml` is the tracked workspace lockfile and must match the ACPX version referenced by `extensions/acpx/package.json`.
|
|
- `extensions/acpx/package-lock.json` is useful local install metadata for the bundled plugin package.
|
|
- If `extensions/acpx/package-lock.json` is gitignored in this repo state, regenerating it is still useful for local verification, but it will not appear in `git status`.
|
|
|
|
## Local Runtime Validation
|
|
|
|
When ACPX integration changes here, prefer this sequence:
|
|
|
|
1. `pnpm install --filter ./extensions/acpx`
|
|
2. `pnpm test:extension acpx`
|
|
3. `pnpm build`
|
|
4. Restart the local gateway if ACP runtime behavior or bundled plugin wiring changed.
|
|
5. If the change affects direct ACP behavior in chat, run a real ACP smoke after restart.
|
|
|
|
## Direct ACPX Binary Policy
|
|
|
|
- Prefer the plugin-local ACPX binary under `extensions/acpx/node_modules/.bin/acpx`.
|
|
- Do not rely on a globally installed `acpx` binary for OpenClaw ACP validation.
|
|
- If the plugin-local ACPX binary is missing or on the wrong version, reinstall it from the version pinned in `extensions/acpx/package.json`.
|
|
|
|
## Boundary Rule
|
|
|
|
If a change feels like shared ACP runtime behavior instead of OpenClaw-specific glue, move it to `openclaw/acpx` and consume it from here instead of re-implementing it inside `extensions/acpx`.
|