v1.2.0 to v1.2.1

- Integrate and unbind OpenViking long-term memory with coding agents. Supports 8 agents (CodeArts CLI, OpenCode, OpenClaw, Hermes, JiuwenSwarm, KimiCode, DeepSeek Harness, Prime Agent) via their native mechanism — MCP, HTTP memory provider, TypeScript extension hooks, or settings.json config. Both integration and unbinding require explicit user authorization.

- version: 1.2.0

- Integrate and unbind OpenViking long-term memory with coding agents. Most agents run in bwrap sandboxes under `/root/job-envs/sandboxes/` and use their **native mechanism** — MCP (`mcp__openviking__*` tools) or the HTTP memory provider — so the integration survives agent upgrades and matches how each agent natively consumes memory.

-

-

- Integration writes are **template-level persistent** for sandbox agents: config is injected into the agent's `start.sh` / config templates under `/root/template/<agent>/`, so a sandbox `stop + start` (which re-runs `start.sh`) preserves the integration.

-

-

- ## What Good Looks Like

- - `scripts/status.sh` reports all 8 agents as `✓` (template + live).

- - `scripts/verify_mcp.sh` passes the full MCP handshake (initialize → tools/list → health) against `http://127.0.0.1:1933/mcp`.

- - Restarting a sandbox does **not** lose the integration (template-level persistence, not live-only).

- - Agents surface OpenViking tools natively: `mcp__openviking__*` for MCP-based agents, dual-channel (MCP + native viking_*) for JiuwenSwarm.

- - Unbinding removes every trace: template blocks, live config, skills/AGENTS.md, config backups, and openviking keys in settings.json.

- - User authorization (`confirm`) is required for every mutation — nothing changes silently.

- | Agent | Native mechanism | Persistence |

- |-------|------------------|-------------|

- | CodeArts CLI | MCP in `.codeartsdoer/codearts_cli.json` + 4-section prompt (aligned with official `openviking-memory` skill semantics) | Template start.sh + live sandbox |

- | OpenCode | Official `@openviking/opencode-plugin` (installed on demand: npm domestic mirror first, on-demand GitHub raw mirror fallback; deployed from `$RUNTIME/opencode/openviking-plugin/`; `@opencode-ai/plugin` SDK via npm) + official `openviking-config.json` fields | Template start.sh (on-demand plugin install) |

- | OpenClaw | Official `clawhub:@openviking/openclaw-plugin` + `openviking setup --json` contract (domestic npm mirror fallback → on-demand source build fallback) + `contextEngine` slot | Template start.sh |

- | Hermes | Official built-in memory provider (`memory.provider: openviking`, no MCP SDK) | Template start.sh + live sandbox |

- | JiuwenSwarm | Dual-channel: native memory provider (`memory.engine: both` + `memory.external.provider: openviking`, HTTP REST) **+ MCP server** (`streamable-http`, 13 tools incl. `search`/`recall`/`find`) + `auto_memory_enabled: true` | Template start.sh + live config.yaml |

- | KimiCode | MCP via `mcp.json` | Template start.sh + live mcp.json |

- | DeepSeek Harness (dsh) | Official `@openviking/dsh-memory-plugin` bundle (installed on demand from `volcengine/OpenViking` via the domestic GitHub raw mirror list; self-contained peers + ESM-safe peer dep sync) installed into `web`/`dsh-tui` profile node_modules + `dsh.profile.bundles` | Template start.sh |

- | Prime Agent | Official `@openviking/pi-coding-agent-extension` (installed on demand from `volcengine/OpenViking` via the domestic GitHub raw mirror list, incl. tests/) | Template start.sh + live extensions dir |

- Per-agent config files, injection blocks, and recall quotas: [references/agent-configs.md](references/agent-configs.md).

- - OpenViking server running and accessible (default `http://127.0.0.1:1933`):

- ```bash

- curl -s http://127.0.0.1:1933/health

- # {"status":"ok","healthy":true,"version":"0.4.x","auth_mode":"dev"}

- ```

- - Host tools: `curl`, `python3`, `bash`. OpenCode/OpenClaw additionally need `npm` (domestic-first registry configured by the skill).

- - This skill operates on local bwrap sandboxes and the local hwcloud config only — no Huawei Cloud IAM policies required (see [references/iam-policies.md](references/iam-policies.md)).

- | `--agent <name>` | Yes (unless `--all`) | Target agent: `codearts`, `opencode`, `openclaw`, `hermes`, `jiuwenswarm`, `kimicode`, `deepseek-harness`, `prime-agent` | `--agent opencode` |

- | `--api-key <key>` | No | OpenViking API key (dev mode needs none). Never echo in chat or logs | `--api-key sk-xxx` |

- | `--dry-run` | No | Show changes without applying them | `--dry-run` |

- ## Dependencies

-

- - **OpenViking server** ≥ 0.4.x on `127.0.0.1:1933` (MCP endpoint `/mcp`, streamable HTTP).

- - **npm** (domestic-first registries: `mirrors.huaweicloud.com/repository/npm/` → `registry.npmmirror.com` → `registry.npmjs.org`) for OpenCode `@opencode-ai/plugin` SDK + `@openviking/opencode-plugin`, and OpenClaw plugin installs (ClawHub primary, npm mirrors as fallback, on-demand source build as third fallback).

- - **No MCP SDK needed for Hermes** — Hermes has a built-in OpenViking memory provider over HTTP REST (official `05-hermes.md`).

- - **openclaw CLI inside sandbox** for `openclaw openviking setup/status` (official JSON contract).

- - **dsh CLI** (`/root/runtime/deepseek-harness/bin/dsh`) for DeepSeek Harness, plus the official `@openviking/dsh-memory-plugin` bundle installed on demand from `volcengine/OpenViking` (domestic GitHub raw mirror list first; self-contained peer deps for `@deepseek-ai/dsh-llm`/`dsh-tools` plus all transitive `@deepseek-ai/*` packages synced as ESM-safe real copies (not symlinks — Node.js v22 ESM resolver does not follow symlinks for bare specifier imports)) — installed into `web`/`dsh-tui` profile `node_modules` + `dsh.profile.bundles`, no pnpm needed.

- - API script conventions are Bash + `curl` + `python3` only.

-

- ## Plugin Sources (on-demand, domestic-first)

-

- The skill ships **no plugin code** — industry convention is to install dependent plugins at

- integrate time from the ecosystem registry. Every `integrate.sh` run provisions the plugins

- it needs on demand (see `scripts/common.sh`):

-

- 1. **npm-published plugins** (`@openviking/opencode-plugin`, `@openviking/openclaw-plugin`)

- are installed via `npm install` using the **domestic-first registry list**

- (`mirrors.huaweicloud.com/repository/npm/` → `registry.npmmirror.com` →

- `registry.npmjs.org`); the first reachable registry wins.

- 2. **GitHub-only plugins** (`@openviking/dsh-memory-plugin`,

- `@openviking/pi-coding-agent-extension` — not yet on npm) are fetched from the official

- `volcengine/OpenViking` repo through the **domestic-first raw mirror list**

- (`ghfast.top` → `gh-proxy.com` → `raw.githubusercontent.com`), with the GitHub API used

- only for commit/tree metadata (domestic proxies 403 on the API).

- 3. **Source check is retained** — every downloaded file is verified **byte-for-byte against

- the authoritative GitHub blob SHA** from the official tree, so content is only accepted

- if it matches upstream regardless of which mirror served the bytes.

- 4. **Changed-files-only download** — the GitHub tree API is used to diff the previously

- installed commit vs upstream; only changed/new files are downloaded

- (with retry/backoff). If nothing under the plugin dir changed, only the recorded

- `.openviking-sync` commit is bumped — no download.

- 5. **Offline resilience** — installed copies live under `/root/runtime/` (outside the

- skill). If upstream is unreachable, the existing installed copy is reused as-is (warn),

- so integration never breaks on network hiccups.

- 6. **Fallthrough for OpenCode/OpenClaw** — plugin runtime installs sit at

- `/root/runtime/opencode/openviking-plugin` and `/root/runtime/openclaw/openviking-plugin-source`

- respectively, giving each agent `npm first → on-demand runtime copy` semantics.

- 7. **Cache-first on sandbox restart** (stop+start / undeploy+deploy) — template

- `start.sh` blocks use a 3-tier cache strategy to avoid re-downloading plugins on

- every boot:

- - **Tier 1 (already installed)**: Plugin already in sandbox `node_modules` → skip

- entirely (survives stop+start). Logs `cache hit`.

- - **Tier 2 (runtime cache)**: Copy from `/root/runtime/<agent>/...` persistent

- cache → no network call (survives undeploy+deploy, since `/root/runtime/` is

- outside the sandbox lifecycle).

- - **Tier 3 (online fallback)**: `npm install` / ClawHub → only on first integrate

- or cache miss. Logs `Cache miss`.

- - **DeepSeek Harness peer deps**: The 193-package `@deepseek-ai/*` sync loop is

- guarded by a `.openviking-peers-synced` marker file — if present, the entire

- copy loop is skipped. Marker is written after first sync completes.

- - **Prime Agent**: Already optimized via `diff -q` check (no change needed).

-

- | 查看集成状态 | `scripts/status.sh`（`--json` 机器可读，`--agent <name>` 指定 Agent） |

- ### Task 1: Check Integration Status

-

- $SKILL_DIR/scripts/status.sh # human-readable

- $SKILL_DIR/scripts/status.sh --json # machine-readable

- Status values per agent:

- - `template + live` — fully integrated and active

- - `template only` — will activate on next restart

- - `live only` — will be **lost on restart** (needs template fix)

-

- ### Task 2: Verify MCP Endpoint

-

- ```bash

- $SKILL_DIR/scripts/verify_mcp.sh

- ```

-

- Performs the full MCP protocol handshake (initialize → notifications/initialized → tools/list → tools/call health) and lists the OpenViking tools (find, search, recall, read, list, remember, add_resource, …).

-

- ### Task 3: Integrate a Single Agent

-

- ```bash

- $SKILL_DIR/scripts/integrate.sh --agent opencode # interactive (asks for confirmation)

- $SKILL_DIR/scripts/integrate.sh --agent opencode --endpoint URL --api-key KEY

- $SKILL_DIR/scripts/integrate.sh --agent opencode --dry-run # preview only

- $SKILL_DIR/scripts/integrate.sh --agent opencode --yes # automation only

- ```

-

- ### Task 4: Integrate All Agents

-

- ```bash

- $SKILL_DIR/scripts/integrate.sh --all

- ```

-

- ### Task 5: Unbind a Single Agent

-

- ```bash

- $SKILL_DIR/scripts/unbind.sh --agent opencode

- $SKILL_DIR/scripts/unbind.sh --agent opencode --dry-run

- $SKILL_DIR/scripts/unbind.sh --agent opencode --yes

- ```

-

- ### Task 6: Unbind All Agents

-

- ```bash

- $SKILL_DIR/scripts/unbind.sh --all

- ```

-

- ### Task 7: Rebuild OpenClaw Sandbox (Apply Template Changes)

-

- OpenClaw's gateway runs in an ephemeral bwrap; `stop + start` re-runs `start.sh`, which reinstalls the plugin and applies endpoint config. Do:

-

- 1. `curl -s -X POST $BASE/envs/openclaw/stop` (poll until `stopped`)

- 2. `curl -s -X POST $BASE/envs/openclaw/start` (poll until `running`)

- 3. Verify: `scripts/integrate.sh --agent openclaw --dry-run` reports endpoint configured

-

- Full restart/rebuild scripts (including the `stop → delete → create → deploy` fallback) and live-config verification from outside bwrap: [references/related-commands.md](references/related-commands.md).

-

-

- ## Authorization Model

-

- Both `integrate.sh` and `unbind.sh` require explicit user confirmation before modifying any agent configuration:

-

- ```

- ━━━ Authorization Required ━━━

- Action: Integrate OpenViking MCP

- Agent: opencode

- Details: Add OpenViking MCP to OpenCode template start.sh (persistent across restarts)

- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

-

- Type 'confirm' to proceed:

- ```

-

- - The user must type exactly `confirm`; any other input aborts.

- - `--yes` / `-y` skips the prompt (for automation only).

- - `--dry-run` shows what would happen without requiring authorization.

- - Never integrate or unbind without explicit user confirmation — see [references/guardrails.md](references/guardrails.md) for the full rules.

- ## Safety Rules

- - **Authorization is mandatory** — never integrate or unbind without explicit user confirmation.

- - **Never edit agent configs directly on the host** — all changes go through the skill scripts.

- - **No API keys in logs** — `--api-key` values must never appear in output or logs.

- - **Dry-run first** for unfamiliar targets.

- - **Slow responses are not an integration bug** — check model API TTFB before blaming MCP (see [references/troubleshooting.md](references/troubleshooting.md)).

-

- ## Validation Rules

- Quick verification after any integration or unbinding:

- ```bash

- $SKILL_DIR/scripts/status.sh # all agents green

- $SKILL_DIR/scripts/verify_mcp.sh # MCP handshake passes

- ```

- Acceptance criteria for each workflow (integrate/unbind per agent): [references/acceptance-criteria.md](references/acceptance-criteria.md).

- Step-by-step verification methods: [references/verification-method.md](references/verification-method.md).

- | [agent-configs.md](references/agent-configs.md) | Per-agent config files, injection blocks, persistence patterns, recall quotas, MCP tools |

- | [guardrails.md](references/guardrails.md) | Safety and authorization rules |

- | [troubleshooting.md](references/troubleshooting.md) | Common failure scenarios, slow-response diagnostics (model TTFB vs network vs MCP), and fixed unbind cleanup issues |

- | [iam-policies.md](references/iam-policies.md) | Equivalent access controls (no Huawei Cloud IAM needed) |

- | [verification-method.md](references/verification-method.md) | Step-by-step verification for each workflow |

- | [related-commands.md](references/related-commands.md) | Restart/rebuild scripts, inspection commands, live-config verification |

- | [acceptance-criteria.md](references/acceptance-criteria.md) | Acceptance criteria for integration/unbinding |

- | [demo/example-input.json](demo/example-input.json) | Example input for the integration workflow |

- The scripts use an **object-oriented design** with a base class, registry pattern,

- and per-agent subclasses. Adding a new agent = create one file in `agents/`.

-

- ```

- scripts/

- lib/ ── Framework (shared infrastructure)

- ui.sh Logging, authorization, dry-run, i18n

- json.sh JSON read/write/has/remove helpers

- plugins.sh Plugin provisioning (npm + GitHub, SHA-1 verified)

- base.sh Agent base class: sandbox discovery, backup, confirm,

- template injection, health check, default interface

- registry.sh Agent registry: auto-discover, list, validate, dispatch

- agents/ ── Agent subclasses (one file per agent)

- codearts.sh CodeArts CLI — MCP in codearts_cli.json

- opencode.sh OpenCode — plugin + openviking-config.json

- openclaw.sh OpenClaw — ClawHub plugin + contextEngine

- hermes.sh Hermes — built-in memory provider

- jiuwenswarm.sh JiuwenSwarm — dual-channel (provider + MCP)

- kimicode.sh KimiCode — MCP via mcp.json

- deepseek_harness.sh DeepSeek Harness — dsh-memory-plugin bundle

- prime_agent.sh Prime Agent — pi-coding-agent-extension

- integrate.sh Thin entry point → registry dispatch (80 lines, was 1919)

- unbind.sh Thin entry point → registry dispatch (74 lines, was 1084)

- status.sh Thin entry point → registry dispatch (122 lines, was 345)

- unset.sh Alias for unbind.sh

- verify_mcp.sh MCP protocol handshake (unchanged)

- common.sh Backward-compat shim → sources lib/*.sh

- ```

-

- ### OO Design

-

- - **Base class** (`lib/base.sh`): defines `agent::discover_sandbox`, `agent::backup_config`,

- `agent::confirm`, `agent::has_injection`, `check_ov_health`, `create_ov_config`, and

- default interface stubs (`agent::default_integrate/unbind/status`).

- - **Agent metadata** via associative array `AGENT_META[name, sandbox_pattern, template_path, mechanism, ...]`,

- populated by each subclass's `agent_<name>_register()`.

- - **Registry** (`lib/registry.sh`): `registry_discover()` auto-sources all `agents/*.sh`,

- `registry_dispatch(agent, method)` calls `agent_<name>_<method>()` with fallback to base.

- - **Subclass override**: each `agents/<name>.sh` defines `agent_<name>_integrate/unbind/status`,

- calling base class methods for shared operations (backup, confirm, sandbox lookup).

- - **Entry points** (integrate/unbind/status.sh): parse CLI args → discover agents → dispatch.

- No agent-specific logic in entry points — all in subclasses.

-

- All scripts are idempotent and create `.bak.<timestamp>` backups before each modification.