huawei-cloud-openviking-agent-integration · v1.2.0 · 2026-08-24 · sha256 11c97f3ab1a7171a
huawei-cloud-openviking-agent-integration v1.2.0B
Immutable. This exact content is served forever at /api/v1/blob/11c97f3ab1a7171a.
---
name: huawei-cloud-openviking-agent-integration
description: |
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
- database
- agent
metadata:
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. 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.
## Supported Agents
| 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).
## 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` (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`, `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** (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 (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/
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.