v1.0.0 to v1.2.0
111 added, 41 removed. Audit B to B.
---
name: huawei-cloud-openviking-agent-integration
description: |
- Integrate and unbind OpenViking long-term memory with coding agents running in bwrap sandboxes. Supports 7 agents (CodeArts CLI, OpenCode, OpenClaw, Hermes, JiuwenSwarm, KimiCode, DeepSeek Harness) via their native mechanism — MCP or HTTP memory provider. Both integration and unbinding require explicit user authorization.
+ 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.
Use this skill when the user wants to: (1) integrate OpenViking memory into a coding agent, (2) unbind OpenViking from a coding agent, (3) check the integration status of all agents, (4) verify the OpenViking MCP endpoint, (5) rebuild the OpenClaw sandbox to apply template changes.
Trigger words: "OpenViking integration", "agent memory binding", "MCP setup", "OpenViking MCP", "integrate OpenViking", "unbind OpenViking", "记忆集成", "记忆解绑", "OpenViking 集成", "OpenViking 解绑", "agent long-term memory", "context database".
tags:
- openviking
- - mcp
- - agent-integration
- - memory
- - binding
- - unbinding
- - codearts
- - opencode
- - openclaw
- - hermes
- - jiuwenswarm
- - kimicode
- - deepseek-harness
- - dsh
- - mcp-client
+ - database
+ - agent
metadata:
- version: 1.0.0
+ version: 1.2.0
license: MIT
category: devtools
---
# Huawei Cloud Agent Integration (OpenViking Long-Term Memory)
## Overview
- Integrate and unbind OpenViking long-term memory with coding agents running in bwrap sandboxes under `/root/job-envs/sandboxes/`. Each agent uses its **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.
+ 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**: 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.
+ 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 7 agents as `✓` (template + live).
+ - `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, memory provider for JiuwenSwarm.
- - Unbinding removes every trace: template blocks, live config, skills/AGENTS.md, and config backups.
+ - 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.
## Supported Agents
| Agent | Native mechanism | Persistence |
|-------|------------------|-------------|
- | CodeArts CLI | MCP in `.codeartsdoer/codearts_cli.json` + 4-section prompt | Template start.sh + live sandbox |
- | OpenCode | Official `@openviking/opencode-plugin` (npm, Huawei Cloud mirror) | Template start.sh (plugin install) |
- | OpenClaw | Official OpenViking plugin (npm) + `contextEngine` slot | Template start.sh |
- | Hermes | MCP + MCP SDK (`pip install mcp`) | Template start.sh + live sandbox |
- | JiuwenSwarm | MCP + native memory provider | Template start.sh + live config.yaml |
+ | 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) | Built-in `@deepseek-ai/dsh-mcp-client` + profile patches (web/cc-tui) + skill/AGENTS protocol | Template start.sh |
+ | 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).
## Prerequisites
- 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"}
```
- Agent sandboxes exist under `/root/job-envs/sandboxes/` (managed by job-env-manager).
- - Host tools: `curl`, `python3`, `bash`. OpenCode/OpenClaw additionally need `npm` (Huawei Cloud mirror configured by the skill).
- - This skill operates on local bwrap sandboxes only — no Huawei Cloud IAM policies required (see [references/iam-policies.md](references/iam-policies.md)).
+ - 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)).
## 参数确认 (Required Inputs)
| Parameter | Required | Description | Example |
|-----------|----------|-------------|---------|
- | `--agent <name>` | Yes (unless `--all`) | Target agent: `codearts`, `opencode`, `openclaw`, `hermes`, `jiuwenswarm`, `kimicode`, `deepseek-harness` | `--agent opencode` |
- | `--all` | Yes (unless `--agent`) | Operate on all 7 agents | `--all` |
+ | `--agent <name>` | Yes (unless `--all`) | Target agent: `codearts`, `opencode`, `openclaw`, `hermes`, `jiuwenswarm`, `kimicode`, `deepseek-harness`, `prime-agent` | `--agent opencode` |
+ | `--all` | Yes (unless `--agent`) | Operate on all 8 agents | `--all` |
| `--endpoint <url>` | No | OpenViking server URL (default `http://127.0.0.1:1933`) | `--endpoint http://192.168.1.100:1933` |
| `--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` |
| `--yes` / `-y` | No | Skip authorization prompt (automation only) | `--yes` |
| `--json` | No | `status.sh`: machine-readable output | `--json` |
## Dependencies
- **OpenViking server** ≥ 0.4.x on `127.0.0.1:1933` (MCP endpoint `/mcp`, streamable HTTP).
- - **npm + Huawei Cloud mirror** (`registry.npmmirror.com` or equivalent) for OpenCode / OpenClaw plugin installs.
- - **Python MCP SDK** (`mcp==1.29.0`) injected by the skill for Hermes — not in the base template image.
- - **dsh CLI** (`/root/runtime/deepseek-harness/bin/dsh`) for DeepSeek Harness profile patches (`--dump-config` verification).
+ - **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） |
| 验证 MCP 端点 | `scripts/verify_mcp.sh` |
| 集成单个 Agent | `scripts/integrate.sh --agent <name> [--endpoint URL] [--api-key KEY] [--dry-run] [--yes]` |
| 集成全部 Agent | `scripts/integrate.sh --all` |
| 解绑单个 Agent | `scripts/unbind.sh --agent <name> [--dry-run] [--yes]` |
| 解绑全部 Agent | `scripts/unbind.sh --all` |
## Workflow
### Task 1: Check Integration Status
```bash
SKILL_DIR=/root/.agents/skills/huawei-cloud-openviking-agent-integration
$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.
- **Do not fabricate integration state** — always run `status.sh` to verify before reporting.
- **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).
## References
| Document | Description |
|----------|-------------|
| [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 |
- ## Scripts
+ ## Scripts (OO Architecture)
+ 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/status.sh Check integration status for all agents (--agent, --json)
- scripts/verify_mcp.sh Verify MCP endpoint via full protocol handshake
- scripts/integrate.sh Integrate single agent or all agents (--agent/--all, --dry-run, --yes)
- scripts/unbind.sh Unbind single agent or all agents (--agent/--all, --dry-run, --yes)
- scripts/unset.sh Alias for unbind.sh (backward-compatibility wrapper)
- scripts/common.sh Shared helpers (logging, confirmation, backups) — sourced by the others
+ 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.