huawei-cloud-openviking-agent-integration

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

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

Prerequisites

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

  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).

参数确认 (Required Inputs)

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.

1. 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).

1. 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.

1. 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.

1. 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.

1. 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.

1. 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).

核心命令

Workflow

Task 1: Check Integration Status

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

$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

$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

$SKILL_DIR/scripts/integrate.sh --all

Task 5: Unbind a Single Agent

$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

$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.

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 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).

Validation Rules

Quick verification after any integration or unbinding:

$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. Step-by-step verification methods: references/verification-method.md.

References

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.