89088414/16gagent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

🎉 init: 小龙的工作空间

Browse Source
This commit is contained in:
大海
2026-06-06 10:40:48 +08:00
commit a188ee1426
3201 changed files with 231817 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
COMPATIBILITY-STRATEGY.md
+335
View File
@@ -0,0 +1,335 @@
# COMPATIBILITY-STRATEGY.md — OpenClaw Compatibility & Upgrade Strategy
> Generated: 2026-06-06 05:20 GMT+8
> Scope: AGENTS.md · GOVERNANCE.md · PORTFOLIO.md · Audit Scripts · Templates · OpenClaw Core Integration
---
## A. Compatibility Surface Map
### A1. Classification
```
Layer │ Path │ Type │ OpenClaw Dep
════════════════════════╪═══════════════════════════════════╪══════════════╪══════════════
│ │ │
Protocol Layer │ AGENTS.md │ Config │ TOOL NAME
│ GOVERNANCE.md │ Config │ NONE
│ PORTFOLIO.md │ Config │ NONE
│ │ │
Configuration Layer │ MEMORY.md │ Config │ NONE
│ HEARTBEAT.md │ Config │ NONE
│ SOUL.md / IDENTITY.md / USER.md │ Config │ NONE
│ │ │
Template Layer │ scripts/templates/* │ Config │ NONE
│ │ │
Audit Engine │ scripts/audit-agents.mjs │ Script │ NONE
│ scripts/audit-governance.mjs │ Script │ NONE
│ scripts/audit-portfolio.mjs │ Script │ NONE
│ scripts/audit-all.mjs │ Script │ NONE
│ │ │
Runtime │ scripts/runtime.mjs │ Script │ src/agent-runtime/*
│ scripts/guard-*.mjs │ Script │ NONE (tool name check only)
│ │ │
Orchestration │ .openclaw/cron/jobs.json │ OpenClaw │ HIGH (cron format)
│ scripts/dream-cycle.sh │ Script │ OpenClaw cron trigger
│ │ │
Memory Integration │ memory_search / memory_get │ OpenClaw API │ HIGH (LLM tool)
│ ctx_search / ctx_index │ OpenClaw API │ HIGH (LLM tool)
```
### A2. Integration Points Detail
| # | Integration | File | OpenClaw Dependency | Risk |
|---|------------|------|---------------------|------|
| IP1 | `ctx_search` tool reference | AGENTS.md §3b (Learning Context) | Tool name in protocol doc | LOW |
| IP2 | `memory_search` tool reference | AGENTS.md §3b (Learning Context) | Tool name in protocol doc | LOW |
| IP3 | `ctx_index` tool reference | AGENTS.md §Over-budget | Tool name in protocol doc | LOW |
| IP4 | `cron` scheduling | .openclaw/cron/ (Dream Cycle) | OpenClaw cron format | MEDIUM |
| IP5 | `memory_search` tool name check | scripts/guard-memory-backend.mjs | String in code | LOW |
| IP6 | `memory_get` tool name check | scripts/guard-memory-backend.mjs | String in code | LOW |
| IP7 | Runtime pipeline imports | scripts/runtime.mjs | src/agent-runtime/* | MEDIUM |
| IP8 | Session context injection | (injected by OpenClaw at runtime) | Implicit | MEDIUM |
| IP9 | `fs.readFileSync` (stdin) | scripts/runtime.mjs | Node.js built-in | NONE |
| IP10 | Task execution cwd | audit-all.mjs runs in workspace | Agent workspace context | LOW |
### A3. Surface Map Summary
```
OpenClaw Core Custom Workspace
───────────── ───────────────
Tool Runtime ───── tool name ref ──────────► AGENTS.md (§3b, §budget)
Cron Engine ───── cron config ─────────────► .openclaw/cron/jobs.json
───── cron trigger ─────────► scripts/dream-cycle.sh
Memory API ───── memory_search ──────────► AGENTS.md (§3b)
───── memory_get ───────────► (used at runtime by agent)
───── ctx_search ───────────► AGENTS.md (§3b)
───── ctx_index ────────────► AGENTS.md (budget resolution)
Session API ───── context injection ──────► (runtime prompt context)
───── tool listing ─────────► guard-*.mjs (string checks)
Node.js fs ◄──── fs.readFileSync ────────► audit-*.mjs (pure Node.js)
Node.js path◄──── path.resolve ───────────► audit-*.mjs (pure Node.js)
BEST PRACTICE: audit scripts have ZERO OpenClaw dependency.
Protocol files have MINIMAL (5 tool name refs total).
```
---
## B. Upgrade Risk Matrix
### B1. Risk Classification
| Risk Level | Criteria | Examples |
|------------|----------|----------|
| **LOW** | Only depends on public/stable interfaces | Tool names (`ctx_search`, `memory_search`), markdown config formats |
| **MEDIUM** | Depends on configuration format or structural assumptions | Cron job format, session context structure, pipeline import paths |
| **HIGH** | Modifies core runtime or depends on internal APIs | None found in current workspace |
### B2. Risk Matrix
```
┌──────────────────────────────────────────────────────────────────┐
│ INTEGRATION │ RISK │ MIGRATION EFFORT │ BREAKAGE │
├──────────────────────────────────────────────────────────────────┤
│ AGENTS.md tool refs │ LOW │ None (name stable)│ UNLIKELY │
│ GOVERNANCE.md │ NONE │ N/A │ NONE │
│ PORTFOLIO.md │ NONE │ N/A │ NONE │
│ audit-*.mjs │ NONE │ N/A │ NONE │
│ Templates (7 files) │ NONE │ N/A │ NONE │
│ │ │ │ │
│ cron/jobs.json │ MEDIUM│ Re-export + │ POSSIBLE │
│ │ │ re-register │ (format │
│ │ │ │ change) │
│ dream-cycle.sh │ MEDIUM│ Update cron │ POSSIBLE │
│ │ │ registration │ │
│ │ │ │ │
│ runtime.mjs (src/*) │ MEDIUM│ Port to new │ POSSIBLE │
│ │ │ runtime API │ │
│ │ │ │ │
│ guard-memory-backend.mjs │ LOW │ Update string │ UNLIKELY │
│ │ │ comparison │ │
│ │ │ │ │
│ TASK EXECUTION │ LOW │ Standard exec │ UNLIKELY │
│ (fs/path/child_process) │ │ │ │
└──────────────────────────────────────────────────────────────────┘
```
### B3. Upgrade Scenario Impact
| Upgrade Type | Impact | Auto-Migration | User Action |
|-------------|--------|---------------|-------------|
| OpenClaw patch (x.y.Z) | MINIMAL | ✓ | Run upgrade-test, expect 0 FAIL |
| OpenClaw minor (x.Y.0) | LOW | Partial | Re-register cron jobs, verify tool names |
| OpenClaw major (X.0.0) | MEDIUM | Guided | Run upgrade-playbook, possibly update compatibility layer |
| OpenClaw deprecation | HIGH | None | Self-hosting mode (see §G) |
---
## C. Compatibility Architecture
### C1. Layer Structure
```
┌─────────────────────────────────────────────────────────────┐
│ CUSTOM PROTOCOL LAYER │
│ AGENTS.md · GOVERNANCE.md · PORTFOLIO.md │
│ (Protocol definitions — no OpenClaw direct refs) │
└───────────────────────────┬─────────────────────────────────┘
│ references abstract interfaces
▼
┌─────────────────────────────────────────────────────────────┐
│ COMPATIBILITY LAYER (abstract) │
│ │
│ Interface │ OpenClaw Binding │
│ ─────────────────────────┼────────────────────────────────── │
│ knowledge_base_search() │ ctx_search() │
│ memory_query() │ memory_search() / memory_get() │
│ knowledge_index() │ ctx_index() │
│ schedule_job() │ cron() │
│ agent_plan() │ sessions_spawn() │
│ tool_exec() │ exec() │
│ file_read() │ read() │
│ web_fetch_raw() │ web_fetch() │
│ │
│ ALL abstract → concrete mapping in ONE place. │
└───────────────────────────┬─────────────────────────────────┘
│ calls through
▼
┌─────────────────────────────────────────────────────────────┐
│ OPENCLAW CORE │
│ Tool Runtime · Cron Engine · Memory API · Session API │
└─────────────────────────────────────────────────────────────┘
```
### C2. Key Design Decision
**DO NOT create a physical compatibility layer file.**
Why:
- Current integration surface is MINIMAL (5 tool name refs in one file)
- Adding a physical layer adds ~2KB of code and maintenance
- The tool names (`ctx_search`, `memory_search`) are STABLE — OpenClaw has not renamed them
- A 5-entry mapping is trivially updateable inline
**IF a rename happens, the change is:**
```
AGENTS.md: s/ctx_search/knowledge_search/g (2 occurrences)
AGENTS.md: s/memory_search/memory_query/g (2 occurrences)
AGENTS.md: s/ctx_index/knowledge_index/g (1 occurrence)
guard-memory-backend.mjs: update string comparison (1 occurrence)
```
That's 5 lines changed across 2 files. **A physical compatibility layer would be over-engineering at this scale.**
### C3. Watch Points
Monitor these OpenClaw interfaces for breaking changes:
| Interface | Stability | Check Frequency |
|-----------|-----------|-----------------|
| Tool names (ctx_search, memory_search, etc.) | Stable | Per major upgrade |
| Cron job format | Stable | Per major upgrade |
| Session context structure | Internal | Not relied upon |
| `src/agent-runtime/` (custom) | Custom code | Per local change |
---
## D. Version Contract
See `version-contract.md` for the full contract.
### D1. Summary
| Field | Value |
|-------|-------|
| Supported OpenClaw | v0.9.x, v0.10.x |
| Required Interfaces | Tool names, cron format, exec, file I/O |
| Forbidden Interfaces | None currently used |
---
## E. Upgrade Test Suite
See `scripts/upgrade-test.mjs`.
### E1. Test Coverage
| Test | What It Checks |
|------|----------------|
| AGENTS compatibility | All sections present, no syntax errors |
| GOVERNANCE compatibility | All sections present, state machine valid |
| PORTFOLIO compatibility | All sections present, project states valid |
| Audit compatibility | All 4 audit scripts run without crash |
| Template compatibility | All 7 templates are valid markdown |
| Cross-ref integrity | No broken references between docs |
---
## F. Migration Strategy
See `upgrade-playbook.md` for the full playbook.
### F1. Strategy Summary
| Upgrade | Pre-check | Migration | Verification | Rollback |
|---------|-----------|-----------|-------------|----------|
| Minor | Run upgrade-test | Update cron, verify tools | Re-run audit-all | Revert cron config |
| Major | Read changelog | Update compatibility mappings | Full audit + manual review | git revert |
| Patch | Run upgrade-test | No action | Re-run audit-all | N/A |
---
## G. Self-Hosting Readiness
### G1. Assessment
Scored across 5 dimensions, 0–20 points each.
| Dimension | Score | Rationale |
|-----------|-------|-----------|
| **Protocol Files** | 20/20 | Pure markdown. Zero runtime dependency. |
| **Audit Scripts** | 20/20 | Pure Node.js fs/path. Zero OpenClaw dependency. |
| **Templates** | 20/20 | Pure markdown templates. |
| **Runtime** | 10/20 | `runtime.mjs` depends on `src/agent-runtime/*` (custom code, but needs an engine) |
| **Orchestration** | 10/20 | Dream Cycle depends on OpenClaw cron. Can be replaced with system cron. |
| **Total** | **80/100** | |
### G2. Self-Hosting Mode Architecture
```
Without OpenClaw Core:
Protocol Files ──► Manual reading (no automation loss)
Audit Scripts ──► node scripts/audit-all.mjs (STILL WORKS)
Templates ──► Manual filling (no automation loss)
Runtime ──► Would need: express or CLI wrapper for src/agent-runtime/*
Orchestration ──► systemd/crontab instead of OpenClaw cron
Memory ──► JSON files + grep instead of memory_search (reduced capability)
```
### G3. Critical Path
The ONLY non-replaceable dependency is:
1. **LLM model access** — without an LLM, the protocol is a static document
2. **Tool execution** — without OpenClaw tools, the agent can't execute tool calls
Everything else can be replaced with standard POSIX tools + Node.js.
### G4. Self-Hosting Readiness Score: **80/100**
Top 20% gap is LLM-dependent features (memory_search, ctx_search at runtime).
Protocol layer (documents + scripts) is fully portable.
---
## H. Final Recommendation
### H1. Current Status
```
Compatibility: ✅ PASS — 0 conflicts, 0 internal API deps
Self-Hosting: ✅ 80/100 — All documents + scripts portable
Upgrade Risk: ✅ LOW — 5 tool name refs in 2 files
Audit Safety: ✅ PASS — 0 OpenClaw deps in audit scripts
Maintenance: ✅ LOW — Patch upgrades require 0 changes
```
### H2. Do NOT
- ❌ Do NOT create a physical compatibility layer (over-engineering for 5 refs)
- ❌ Do NOT abstract tool names in protocol files (increases complexity, reduces clarity)
- ❌ Do NOT modify protocol files to "future-proof" — the current codebase is already future-proof
### H3. Do
- ✅ Run `scripts/upgrade-test.mjs` after each OpenClaw upgrade
- ✅ Monitor the 5 tool name refs during major upgrades
- ✅ Keep `version-contract.md` up to date with tested OpenClaw versions
- ✅ Follow `upgrade-playbook.md` for major upgrades
### H4. OpenClaw Upgrade Cost Estimate
```
Patch upgrade (v0.9.1 → v0.9.2): 0 min, no changes needed
Minor upgrade (v0.9 → v0.10): 5 min, re-register cron, verify tool names
Major upgrade (v1.0): 15 min, run upgrade-test, update 5 refs if renamed
OpenClaw deprecation: 2h, configure alternate LLM + crontab
```
### H5. Summary
The three-layer protocol architecture (AGENTS + GOVERNANCE + PORTFOLIO) is **designed for portability** — it's pure markdown with zero framework lock-in. The audit scripts are **pure Node.js** with zero OpenClaw dependency. The only integration points are **5 tool name references** in AGENTS.md, which are trivially updateable.
**No action required for current version.**
**Upgrade cost: near-zero.**
**Self-hosting readiness: excellent.**