🎉 init: 小龙的工作空间
This commit is contained in:
大海
@@ -0,0 +1,194 @@
|
||||
# Upgrade Playbook
|
||||
|
||||
> Migration strategy for upgrading OpenClaw core while maintaining protocol compatibility.
|
||||
> Part of COMPATIBILITY-STRATEGY.md §F.
|
||||
|
||||
---
|
||||
|
||||
## §1 Pre-Upgrade Checklist
|
||||
|
||||
Before any upgrade:
|
||||
|
||||
```markdown
|
||||
- [ ] Run `node scripts/upgrade-test.mjs` — record baseline PASS count
|
||||
- [ ] Run `node scripts/audit-all.mjs` — record baseline WARN/FAIL counts
|
||||
- [ ] Commit all outstanding changes (`git status` should be clean)
|
||||
- [ ] Read OpenClaw changelog for the target version
|
||||
- [ ] Check version-contract.md §3 Required Interfaces for changes
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## §2 Patch Upgrade (v0.9.1 → v0.9.2)
|
||||
|
||||
**Definition:** Bugfix release. No breaking changes.
|
||||
|
||||
### Procedure
|
||||
|
||||
```
|
||||
1. Upgrade OpenClaw ← per OpenClaw install instructions
|
||||
2. Run upgrade-test ← node scripts/upgrade-test.mjs
|
||||
3. Run full audit ← node scripts/audit-all.mjs
|
||||
4. Verify ← all PASS, no regressions
|
||||
```
|
||||
|
||||
**Expected changes:** 0 files modified.
|
||||
|
||||
**Rollback:** `openclaw restart` with previous version.
|
||||
|
||||
---
|
||||
|
||||
## §3 Minor Upgrade (v0.9.x → v0.10.x)
|
||||
|
||||
**Definition:** Feature release. Possible tool name additions, config format changes.
|
||||
|
||||
### Procedure
|
||||
|
||||
```text
|
||||
PRE-CHECK
|
||||
├─ Read OpenClaw changelog for:
|
||||
│ ├─ Tool name changes
|
||||
│ ├─ Cron format changes
|
||||
│ └─ Config format changes
|
||||
├─ Run baseline tests (upgrade-test + audit-all)
|
||||
└─ git stash or commit
|
||||
|
||||
MIGRATION
|
||||
├─ [IF tool names changed] Update AGENTS.md §3b, §6, §CPB
|
||||
│ ├─ s/old_name/new_name/ in ctx_search references
|
||||
│ └─ s/old_name/new_name/ in memory_search references
|
||||
├─ [IF cron format changed] Re-register Dream Cycle job:
|
||||
│ cron(action="remove", ...) → cron(action="add", ...)
|
||||
├─ [IF config format changed] Update `.openclaw/` config files
|
||||
└─ git commit -m "chore: adapt to OpenClaw v0.10.x"
|
||||
|
||||
VERIFICATION
|
||||
├─ node scripts/upgrade-test.mjs ← all PASS
|
||||
├─ node scripts/audit-all.mjs ← baseline match
|
||||
└─ Manual: verify Dream Cycle runs at next scheduled time
|
||||
|
||||
ROLLBACK
|
||||
├─ git revert the migration commit
|
||||
├─ Re-register old cron job format
|
||||
└─ openclaw restart
|
||||
```
|
||||
|
||||
### Common Minor Upgrade Actions
|
||||
|
||||
| Change | Affects | Action |
|
||||
|--------|---------|--------|
|
||||
| Tool API signature change | AGENTS.md §3b | Update search parameter format |
|
||||
| New tool addition | — | Optional: add to protocol if relevant |
|
||||
| Cron syntax change | .openclaw/cron/ | Re-register all jobs |
|
||||
| Memory format change | None (protocol uses abstract) | No action |
|
||||
|
||||
---
|
||||
|
||||
## §4 Major Upgrade (v0.x → v1.0)
|
||||
|
||||
**Definition:** Breaking change release. Requires full compatibility review.
|
||||
|
||||
### Procedure
|
||||
|
||||
```text
|
||||
PRE-CHECK
|
||||
├─ Same as minor upgrade, PLUS:
|
||||
├─ Read full migration guide from OpenClaw
|
||||
├─ Review COMPATIBILITY-STRATEGY.md §A (Surface Map)
|
||||
├─ Review version-contract.md §3 (Required Interfaces)
|
||||
├─ Review version-contract.md §4 (Forbidden Interfaces)
|
||||
└─ Create recovery branch: git checkout -b upgrade/v1.0-prep
|
||||
|
||||
MIGRATION
|
||||
├─ Phase 1: Update tool references
|
||||
│ ├─ Update all tool name references in AGENTS.md
|
||||
│ ├─ Update guard-memory-backend.mjs string comparisons
|
||||
│ └─ Run: node scripts/upgrade-test.mjs
|
||||
│
|
||||
├─ Phase 2: Update cron integration
|
||||
│ ├─ List current cron jobs: cron(action="list")
|
||||
│ ├─ Remove all: cron(action="remove", ...)
|
||||
│ ├─ Re-register with new format
|
||||
│ └─ Verify: cron(action="list")
|
||||
│
|
||||
├─ Phase 3: Update runtime if needed
|
||||
│ ├─ Check if runtime.mjs still compiles
|
||||
│ ├─ Check src/agent-runtime/* imports
|
||||
│ └─ Update import paths if needed
|
||||
│
|
||||
├─ Phase 4: Run full verification
|
||||
│ ├─ node scripts/upgrade-test.mjs ← must PASS all
|
||||
│ ├─ node scripts/audit-all.mjs ← 0 FAIL, baseline WARN
|
||||
│ └─ Manual walkthrough of one complex task
|
||||
│
|
||||
└─ git commit -m "chore: migrate to OpenClaw v1.0"
|
||||
|
||||
VERIFICATION
|
||||
├─ Same as minor, PLUS:
|
||||
├─ Verify all 3 protocol layers are self-consistent
|
||||
├─ Verify audit-report.md generates correctly
|
||||
└─ Mark tested version in version-contract.md §1
|
||||
|
||||
ROLLBACK
|
||||
├─ git checkout main (pre-upgrade branch)
|
||||
├─ Restore .openclaw/cron/ from git backup
|
||||
├─ openclaw restart
|
||||
└─ Note: Any data created during v1.0 may be incompatible
|
||||
```
|
||||
|
||||
### Major Upgrade Risk Areas
|
||||
|
||||
| Area | Breakage Likelihood | Recovery Difficulty |
|
||||
|------|---------------------|---------------------|
|
||||
| Tool names | MEDIUM (known to be stable) | LOW (5 refs to update) |
|
||||
| Cron format | LOW | LOW (re-register) |
|
||||
| Session context | LOW (not relied upon) | NONE |
|
||||
| runtime.mjs imports | MEDIUM | MEDIUM (port to new API) |
|
||||
| LLM behavior changes | MEDIUM (prompt sensitivity) | LOW (adjust prompts) |
|
||||
|
||||
---
|
||||
|
||||
## §5 OpenClaw Deprecation / Self-Host Mode
|
||||
|
||||
**Definition:** OpenClaw core is no longer available or maintained.
|
||||
|
||||
### Procedure
|
||||
|
||||
```text
|
||||
PRE-CHECK
|
||||
├─ Read SELF-HOSTING READINESS in COMPATIBILITY-STRATEGY.md §G
|
||||
├─ Score is 80/100 — protocol layer is portable
|
||||
└─ Identify which features to maintain vs drop
|
||||
|
||||
MIGRATION OPTIONS
|
||||
├─ Option A: Replace with basic CLI
|
||||
│ ├─ Audit scripts run via: node scripts/audit-all.mjs (STILL WORKS)
|
||||
│ ├─ Protocol docs are static markdown (readable anywhere)
|
||||
│ └─ Lost: memory_search, ctx_search, cron-Triggered Dream Cycle
|
||||
│
|
||||
├─ Option B: Replace with custom agent runtime
|
||||
│ ├─ Build minimal tool executor (5-10 tools)
|
||||
│ ├─ Use system cron or launchd for Dream Cycle
|
||||
│ ├─ Use grep/ripgrep + sqlite for memory search (reduced capability)
|
||||
│ └─ Keep: all protocol docs, audit scripts, templates
|
||||
│
|
||||
└─ Option C: Hybrid
|
||||
├─ Keep protocol docs and audit scripts
|
||||
├─ Replace only cron + memory with POSIX equivalents
|
||||
└─ Import protocol docs into new toolchain
|
||||
|
||||
SELF-HOSTED VERIFICATION
|
||||
├─ node scripts/upgrade-test.mjs ← all PASS (no OpenClaw dep!)
|
||||
├─ node scripts/audit-all.mjs ← all PASS
|
||||
└─ Manual: verify cron/launchd triggers Dream Cycle
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## §6 Upgrade History Log
|
||||
|
||||
| Date | From | To | Type | Changed Files | Duration | Issues |
|
||||
|------|------|----|------|---------------|----------|--------|
|
||||
| — | — | — | — | — | — | — |
|
||||
|
||||
*(Populate on each upgrade)*
|
||||
Reference in New Issue
Block a user