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

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.

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)

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

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

Document	Description
agent-configs.md	Per-agent config files, injection blocks, persistence patterns, recall quotas, MCP tools
guardrails.md	Safety and authorization rules
troubleshooting.md	Common failure scenarios, slow-response diagnostics (model TTFB vs network vs MCP), and fixed unbind cleanup issues
iam-policies.md	Equivalent access controls (no Huawei Cloud IAM needed)
verification-method.md	Step-by-step verification for each workflow
related-commands.md	Restart/rebuild scripts, inspection commands, live-config verification
acceptance-criteria.md	Acceptance criteria for integration/unbinding
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.