Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
docs(agent-integrations): add agent onboarding guide and link it from install surfaces (#6002)
t0sakic8c38d44087e
diff --git a/README.md b/README.mdindex 4304b1ba0..04c3bbae1 100644--- a/README.md+++ b/README.md@@ -193,25 +193,17 @@ Connect your coding agent to OpenViking for cross-session memory. The memory plu<summary><strong>Let your agent install it</strong></summary>```text-Install the OpenViking memory plugin for me by running:+Install the OpenViking memory plugin and help me start using it. OpenViking is the open-source context database for AI agents from Volcengine (https://github.com/volcengine/OpenViking, AGPL-3.0); the command and link below are from its official docs.-curl -fsSL https://openviking.ai/install | bash -s -- --yes --url <SERVER_URL>+1. Run the official installer. It needs network access and writes to my home directory; if your sandbox blocks that, ask me for approval:+ curl -fsSL https://openviking.ai/install | bash -s -- --yes --lang en --url <SERVER_URL> --api-key <API_KEY>+2. Once it's installed, read the OpenViking onboarding guide and use it to walk me through setup. The guide has you ask me before choices like importing history or adding a working rule. docs.openviking.ai and docs.openviking.net are the same docs site; use whichever loads:+ https://docs.openviking.ai/agents/en/onboarding.md-<SERVER_URL> is the address of my OpenViking server; ask me for it, don't guess.-If the server has auth turned on, it needs a user key (a root key can't read or-write memories): check whether one is already saved; if not, ask me for it and-pass it with --api-key, and tell me how to hand it over if I'd rather not paste-it into this chat. Never repeat the key back. If auth is off, add --api-key ''-so an earlier saved key isn't reused.--The script needs network access and writes to my home directory; if a sandbox-blocks it, ask me to approve running it outside the sandbox.--When it finishes, tell me which tools it installed into and the next steps for-each, then ask whether I want it in any other tool.+The API key is a user key I created for myself on that server; the installer stores it in ~/.openviking/ovcli.conf on this machine. Use it in the command as it is; there's no need to show it in your replies, and don't write it into any other file or rule. Talk to me in English.```-Have your server's address ready, plus its API key if it has auth turned on.+Before you send it, replace `<SERVER_URL>` with your server's address and `<API_KEY>` with a user key; a root key can't read or write memories. If the server has auth turned off, use `--api-key ''`.</details>diff --git a/docs/.vitepress/theme/docs-sections.ts b/docs/.vitepress/theme/docs-sections.tsindex d8dd3bceb..510fd74a6 100644--- a/docs/.vitepress/theme/docs-sections.ts+++ b/docs/.vitepress/theme/docs-sections.ts@@ -21,6 +21,7 @@ export const sections: DocSection[] = [g('Get your first result', '先完成一次体验', [p('getting-started/01-introduction'),p('getting-started/02-quickstart'),+ p('getting-started/07-agent-onboarding'),p('getting-started/05-cli-setup')]),g('Evaluate the result', '验证实际效果', [diff --git a/docs/en/agent-integrations/02-claude-code.md b/docs/en/agent-integrations/02-claude-code.mdindex 17b399bde..e5b96b47a 100644--- a/docs/en/agent-integrations/02-claude-code.md+++ b/docs/en/agent-integrations/02-claude-code.md@@ -45,6 +45,8 @@ If you prefer to set it up manually:</details>+Once installed, start a new Claude Code session and ask it to follow https://docs.openviking.ai/agents/en/onboarding.md. It checks the connection and walks you through the first use; see [Connect your agent with one prompt](../getting-started/07-agent-onboarding.md).+## VerifyLaunch `claude`, then:diff --git a/docs/en/agent-integrations/04-codex.md b/docs/en/agent-integrations/04-codex.mdindex 14c08a8ef..6ace5f59a 100644--- a/docs/en/agent-integrations/04-codex.md+++ b/docs/en/agent-integrations/04-codex.md@@ -57,6 +57,8 @@ Prerequisites: Node.js >= 22, Codex >= 0.130.0, and the `plugin_hooks` feature e</details>+Once installed, start a new Codex session and ask it to follow https://docs.openviking.ai/agents/en/onboarding.md. It checks the connection and walks you through the first use; see [Connect your agent with one prompt](../getting-started/07-agent-onboarding.md).+## VerifyLaunch `codex`; on the first prompt of a session, the `SessionStart` hook should load your profile, and the plugin should then recall relevant memories for every prompt. Set `OPENVIKING_DEBUG=1` to write events to `~/.openviking/logs/codex-hooks.log`.diff --git a/docs/en/agent-integrations/08-community-plugins.md b/docs/en/agent-integrations/08-community-plugins.mdindex 45dd3dba2..726e9a040 100644--- a/docs/en/agent-integrations/08-community-plugins.md+++ b/docs/en/agent-integrations/08-community-plugins.md@@ -40,6 +40,8 @@ After restarting ZCode, verify that:Implementation details and currently verified ZCode assumptions are documented in the plugin's [README](https://github.com/volcengine/OpenViking/tree/main/examples/agent-hook-plugin) and [DESIGN.md](https://github.com/volcengine/OpenViking/blob/main/examples/agent-hook-plugin/DESIGN.md).+Once installed, start a new ZCode session and ask it to follow https://docs.openviking.ai/agents/en/onboarding.md. It checks the connection and walks you through the first use; see [Connect your agent with one prompt](../getting-started/07-agent-onboarding.md).+## Kimi Code memory integrationSource: [examples/agent-hook-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/agent-hook-plugin)@@ -75,6 +77,8 @@ curl -fsSL https://openviking.ai/install | bash -s -- --uninstall --yes --harnesThe verified host contract and version are recorded in[`hosts/kimicode/DESIGN.md`](https://github.com/volcengine/OpenViking/blob/main/examples/agent-hook-plugin/hosts/kimicode/DESIGN.md).+Once installed, start a new Kimi Code session and ask it to follow https://docs.openviking.ai/agents/en/onboarding.md. It checks the connection and walks you through the first use; see [Connect your agent with one prompt](../getting-started/07-agent-onboarding.md).+## CodeBuddy Code memory integrationSource: [examples/agent-hook-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/agent-hook-plugin)diff --git a/docs/en/agent-integrations/10-opencode.md b/docs/en/agent-integrations/10-opencode.mdindex 7e138461a..0bf328353 100644--- a/docs/en/agent-integrations/10-opencode.md+++ b/docs/en/agent-integrations/10-opencode.md@@ -19,6 +19,8 @@ curl -fsSL https://openviking.ai/install | bashThe installer copies the plugin into `~/.config/opencode/plugins/` as a local file plugin, writes the `openviking` MCP server entry into `~/.config/opencode/opencode.json`, and configures `~/.openviking/ovcli.conf`.+Once installed, start a new OpenCode session and ask it to follow https://docs.openviking.ai/agents/en/onboarding.md. It checks the connection and walks you through the first use; see [Connect your agent with one prompt](../getting-started/07-agent-onboarding.md).+### Manual npm installThe published npm package is `@openviking/opencode-plugin`. For a first-time OpenCode config:diff --git a/docs/en/agent-integrations/11-pi.md b/docs/en/agent-integrations/11-pi.mdindex 002eedb92..e1d640246 100644--- a/docs/en/agent-integrations/11-pi.md+++ b/docs/en/agent-integrations/11-pi.md@@ -30,6 +30,8 @@ npm ci --prefix ~/.pi/agent/extensions/openviking --omit=dev --ignore-scriptsThe extension imports its shared modules from a `shared/` directory that is not in git; `sync.mjs` generates it, so run it before copying. After a `git pull`, run `sync.mjs` again before copying the update.+Once installed, start a new pi session and ask it to follow https://docs.openviking.ai/agents/en/onboarding.md. It checks the connection and walks you through the first use; see [Connect your agent with one prompt](../getting-started/07-agent-onboarding.md).+## How it works- **Session start** builds your OpenViking profile block and restores takeover state, including the branch watermark used by `pi -c`. The block holds your profile, memory indexes, and an `<available-skills>` catalog of your own and account-shared OpenViking skills, and it is added to pi's system prompt on every turn; the model reads a skill's `SKILL.md` with `openviking_read` before following it.diff --git a/docs/en/agent-integrations/12-cursor.md b/docs/en/agent-integrations/12-cursor.mdindex 98384aca3..ebaba2eba 100644--- a/docs/en/agent-integrations/12-cursor.md+++ b/docs/en/agent-integrations/12-cursor.md@@ -15,6 +15,8 @@ curl -fsSL https://openviking.ai/install | bashQuit Cursor completely and restart it after installation.+Once installed, start a new Cursor session and ask it to follow https://docs.openviking.ai/agents/en/onboarding.md. It checks the connection and walks you through the first use; see [Connect your agent with one prompt](../getting-started/07-agent-onboarding.md).+## What gets installed- Lifecycle Hooks for profile loading, prompt recall, conversation capture, session commit, and `viking://` URI protection.diff --git a/docs/en/agent-integrations/13-trae.md b/docs/en/agent-integrations/13-trae.mdindex 04ee6454b..8aa5feb0f 100644--- a/docs/en/agent-integrations/13-trae.md+++ b/docs/en/agent-integrations/13-trae.md@@ -33,6 +33,8 @@ You can also use `/hooks` to review the OpenViking commands and trust and enableTRAE and TRAE CN use the installed `hooks.json` and need no hook approval; restart the corresponding client after installation.+Once installed, start a new TRAE session and ask it to follow https://docs.openviking.ai/agents/en/onboarding.md. It checks the connection and walks you through the first use; see [Connect your agent with one prompt](../getting-started/07-agent-onboarding.md).+## What gets installed- `SessionStart` loads your profile, current project memory, and an `<available-skills>` catalog of your OpenViking skills.diff --git a/docs/en/agent-integrations/17-dsh.md b/docs/en/agent-integrations/17-dsh.mdindex d735981da..a1fb1cb45 100644--- a/docs/en/agent-integrations/17-dsh.md+++ b/docs/en/agent-integrations/17-dsh.md@@ -44,6 +44,8 @@ After installation, use the verification steps below to check tool access and cr</details>+Once installed, start a new DSH session and ask it to follow https://docs.openviking.ai/agents/en/onboarding.md. It checks the connection and walks you through the first use; see [Connect your agent with one prompt](../getting-started/07-agent-onboarding.md).+## VerifyStart `dsh --profile web` and open a conversation. You should see an OpenViking context injection at the top of the session, and the model should have `mcp__openviking__*` tools available. Ask it about something from an earlier session to confirm recall.diff --git a/docs/en/getting-started/07-agent-onboarding.md b/docs/en/getting-started/07-agent-onboarding.mdnew file mode 100644index 000000000..5e8b87118--- /dev/null+++ b/docs/en/getting-started/07-agent-onboarding.md@@ -0,0 +1,60 @@+# Connect your agent with one prompt++Paste one prompt into the coding agent you already use. The agent installs the OpenViking memory plugin into the agents it finds on your machine, checks the connection, offers to bring in your recent work, and tells you how to restart. After the restart, your first question shows OpenViking at work.++The agent follows a short guide published as plain Markdown, so any agent can fetch it:++- English: `https://docs.openviking.ai/agents/en/onboarding.md`+- Chinese: `https://docs.openviking.ai/agents/zh/onboarding.md`++Both are also served from `docs.openviking.net`, which is usually faster from mainland China.++## The prompt++Copy the prompt and replace `<API_KEY>` with your key from the [OpenViking console](https://console.volcengine.com/vikingdb/openviking/region:openviking+cn-beijing?utm_source=opensource_docs&utm_medium=referral&utm_campaign=getting-started_07-agent-onboarding), under **User Management → API Key**, before you send it.++<AgentPrompt>++```text+Install the OpenViking memory plugin and help me start using it. OpenViking is the open-source context database for AI agents from Volcengine (https://github.com/volcengine/OpenViking, AGPL-3.0); the command and link below are from its official docs.++1. Run the official installer. It needs network access and writes to my home directory; if your sandbox blocks that, ask me for approval:+ curl -fsSL https://openviking.ai/install | bash -s -- --yes --lang en --url https://api.vikingdb.cn-beijing.volces.com/openviking --api-key <API_KEY>+2. Once it's installed, read the OpenViking onboarding guide and use it to walk me through setup. The guide has you ask me before choices like importing history or adding a working rule. docs.openviking.ai and docs.openviking.net are the same docs site; use whichever loads:+ https://docs.openviking.ai/agents/en/onboarding.md++The API key is one I created for myself in the OpenViking console; the installer stores it in ~/.openviking/ovcli.conf on this machine. Use it in the command as it is; there's no need to show it in your replies, and don't write it into any other file or rule. Talk to me in English.+```++</AgentPrompt>++The installer sets up the plugin in every supported agent it detects on the machine, so other agents you have installed get it too; each one needs its own restart before the plugin works there. It also installs the `ov` command, which the agent uses to check the connection and add files. `--lang` sets the installer's language, and with it the language of the guide link it prints at the end. To limit the install to some agents, add `--harness` with a comma-separated list, for example `--harness claude,cli`; see [Unified installer](../agent-integrations/16-capability-reference.md#_3-1-2-unified-installer).++**Self-hosted server.** Replace the URL with your server's address. Use a user key; a root key can't read or write memories. For a local server without authentication, pass `--api-key ''`.++**About the key.** The installer accepts the key only as a command-line argument, so the key appears in this conversation and in your agent's local session history and logs. The guide tells the agent never to repeat it or write it anywhere. The plugins don't yet remove the key from the conversations they save, and the first save after the restart includes the install conversation: in Codex this happens whether you resume it or start a new session, so this install conversation, key included, can be saved to your own OpenViking account. In Claude Code a new session avoids it, which is why the agent asks you not to resume the install conversation there. If you'd rather not paste the key into a chat, run `curl -fsSL https://openviking.ai/install | bash` in a terminal yourself, then send your agent the prompt under [Already installed](#already-installed).++## Already installed++If the plugin is already installed, start a new session in your agent and send:++```text+Follow https://docs.openviking.ai/agents/en/onboarding.md to walk me through my first use of OpenViking.+```++## What the agent does++1. **Checks the install.** It reads the installer's output and runs `ov health`, then tells you that you are connected and which agents were set up; if it is more than one, they all work from the same context.+2. **Explains what runs automatically.** Before each prompt, the plugin recalls relevant memories. After each turn, it saves the conversation, and the server extracts long-term memories in the background. You don't need to approve this separately; asking for the install is the approval.+3. **Asks whether to bring in earlier work.** The default is the current project's sessions from the last 14 days. You can also describe one kind of work, such as "the discussions about the payment refactor": the agent lists the candidate sessions with a preview of each, picks the ones that match, and shows you its picks before anything is sent. The import script reads Claude Code and Codex history itself; other agents first write a small converter that turns their own sessions into JSONL, then hand that to the same script. It tells you what it found and how much first, and imports only after you confirm; sessions that are already in OpenViking are not uploaded again. Right after the import it reads back from OpenViking where that work stands and what was decided, so you see what the import gave you before the restart. Only user and assistant text is sent; tool calls and their output are dropped and API keys are removed. If Claude Code or Codex history exists on the machine, other agents offer that too. You can also name files, such as a design doc, for the agent to add with `ov add-resource` to this project's folder in your personal resources.+4. **Offers a lasting collaboration rule.** The agent offers to add a rule to your user-level rules file (for example `~/.claude/CLAUDE.md` for Claude Code, `~/.codex/AGENTS.md` for Codex), so it applies to all your projects: use the context OpenViking recalls and search only when that isn't enough; save important decisions (with the reasons), progress and next steps, and work products such as designs, research and deliverables to OpenViking on its own initiative, in one folder per project in your personal resources (`resources/<project>/`, with progress and decisions under `notes/`); look at what was saved first when continuing a project; and say briefly when it used or saved something. You can also have it adjust the rule for your role (product, engineering, marketing, design and so on), which adds what that role should keep. The rule sits between a pair of `<!-- openviking:start -->` / `<!-- openviking:end -->` markers and the rest of the file is left alone. It is written only if you agree, and read back afterwards. On agents that keep personal rules only in their settings (TRAE or Cursor, for example), the agent asks you to paste it there. It never writes rules into project files.+5. **Tells you how to restart.** The plugin loads only when the agent starts again. The agent gives you the exact steps for the agent you are talking to. In Codex you first trust the OpenViking hooks (`/hooks` in the CLI, or the hooks icon below the input box in the desktop app), then quit, come back to the same conversation (`codex resume --last` in the CLI), and say "restarted"; if Codex still shows "Hooks need review", choose **Trust all and continue**. In Claude Code and the other agents you start a new session and send the first message it gives you. If the installer set up other agents too, it tells you they need a restart as well.+6. **Shows OpenViking at work.** After the restart, your first question gets an answer drawn from recalled context, and the agent points out where that shows up: source cards in Claude Code, the OV-Usage line in Codex, and so on.++The agent asks you only for decisions: what to bring in (with a confirmation after you see the counts) and whether to add the collaboration rule, each with what it gives you and what it sends or changes. Choices you have already made are not asked again.++## See also++- [Agent integrations overview](../agent-integrations/01-overview.md)+- [Agent integration capabilities](../agent-integrations/16-capability-reference.md)+- [Install and use the CLI](05-cli-setup.md)diff --git a/docs/images/agents/en/claude-code.md b/docs/images/agents/en/claude-code.mdindex 4a9b01bca..068ac307f 100644--- a/docs/images/agents/en/claude-code.md+++ b/docs/images/agents/en/claude-code.md@@ -47,6 +47,16 @@ Because Claude Code may block installation scripts from unknown sources, automat✅ Status: OpenViking server is healthy and running```+## Step 3: Start using++Start a new Claude Code session and send:++```text+Follow https://docs.openviking.net/agents/en/onboarding.md to walk me through my first use of OpenViking.+```++The agent checks the connection and walks you through the first use.+## Troubleshoot| Problem | Fix |diff --git a/docs/images/agents/en/codex.md b/docs/images/agents/en/codex.mdindex ac6a24589..d166a760f 100644--- a/docs/images/agents/en/codex.md+++ b/docs/images/agents/en/codex.md@@ -39,6 +39,16 @@An empty new account may have no profile or relevant memories to inject. See the full guide for lifecycle commits and a complete memory check.+## Step 3: Start using++Start a new Codex session and send:++```text+Follow https://docs.openviking.net/agents/en/onboarding.md to walk me through my first use of OpenViking.+```++The agent checks the connection and walks you through the first use.+## Troubleshoot| Problem | Fix |diff --git a/docs/images/agents/en/cursor.md b/docs/images/agents/en/cursor.mdindex c8ef31d6e..ec2bb129f 100644--- a/docs/images/agents/en/cursor.md+++ b/docs/images/agents/en/cursor.md@@ -18,6 +18,16 @@1. Open **Customize → MCPs** and confirm both **openviking User** and **openviking Plugin** are visible.2. Open **Customize → Hooks** and confirm the **openviking-memory** entry is visible.+## Step 3: Start using++Start a new Cursor session and send:++```text+Follow https://docs.openviking.net/agents/en/onboarding.md to walk me through my first use of OpenViking.+```++The agent checks the connection and walks you through the first use.+## Troubleshoot| Problem | Fix |diff --git a/docs/images/agents/en/deepseek-harness.md b/docs/images/agents/en/deepseek-harness.mdindex c50d26b9f..528d0b055 100644--- a/docs/images/agents/en/deepseek-harness.md+++ b/docs/images/agents/en/deepseek-harness.md@@ -21,6 +21,16 @@ The installer asks for the harness and OpenViking credentials:2. Confirm that the model has `mcp__openviking__*` tools and can call them.3. For Desktop, open a new conversation in the app and check the same two points. `--dump-config` does not work for Desktop's `desktop` profile; check that `~/.dsh/profiles/desktop/package.json` lists the plugin under `dsh.profile.bundles` instead.+## Step 3: Start using++Start a new DeepSeek Harness session and send:++```text+Follow https://docs.openviking.net/agents/en/onboarding.md to walk me through my first use of OpenViking.+```++The agent checks the connection and walks you through the first use.+## Troubleshooting| Issue | What to check |diff --git a/docs/images/agents/en/kimi-code.md b/docs/images/agents/en/kimi-code.mdindex 7a65cb501..4f50b5070 100644--- a/docs/images/agents/en/kimi-code.md+++ b/docs/images/agents/en/kimi-code.md@@ -19,6 +19,16 @@2. Confirm `~/.kimi-code/plugins/installed.json` contains the `openviking-memory` entry.3. In a new session, ask about something you mentioned earlier to confirm recall.+## Step 3: Start using++Start a new Kimi Code session and send:++```text+Follow https://docs.openviking.net/agents/en/onboarding.md to walk me through my first use of OpenViking.+```++The agent checks the connection and walks you through the first use.+## Troubleshoot| Problem | Fix |diff --git a/docs/images/agents/en/onboarding-other-hosts.md b/docs/images/agents/en/onboarding-other-hosts.mdnew file mode 100644index 000000000..e0923d7e4--- /dev/null+++ b/docs/images/agents/en/onboarding-other-hosts.md@@ -0,0 +1,44 @@+# OpenViking onboarding guide: importing history on other hosts (for agents)++The import script reads Claude Code and Codex history directly. On other hosts, when the user chose to import in Step 3 of the [onboarding guide](https://docs.openviking.ai/agents/en/onboarding.md), you first convert this host's sessions to JSONL and hand that to the same script. Choosing the scope, confirming and reporting the result work as in the onboarding guide; this page covers only the conversion.++1. Run `echo "${TMPDIR:-/tmp}"` and note the directory; below it is `<tmp>`. Use that absolute path for every file you write and every command, not `${TMPDIR:-/tmp}`. Download the import script:++ ```bash+ curl -fsSL https://docs.openviking.ai/dl/memory-plugin-shared/import-history.mjs -o "<tmp>/ov-import-history.mjs"+ ```++2. Find where this host keeps its sessions on this machine. The table is a hint; go by what is actually there. Read only; change nothing.++ | Host | `--harness` | Where sessions are |+ |---|---|---|+ | TraeCode CLI 2.0 | `trae-cli` | `~/.trae/cli/sessions/`, the same rollout format as Codex |+ | Kimi Code | `kimicode` | `~/.kimi-code/sessions/` (under `$KIMI_CODE_HOME` if set); each session's `state.json` has the cwd, the messages are in `agents/main/wire.jsonl` |+ | OpenCode | `opencode` | the SQLite database `~/.local/share/opencode/opencode.db`; without `sqlite3`, Node 22's `node:sqlite` can open it read-only; `synthetic` text is injected content, and sessions with a non-empty `parent_id` are sub-agents |+ | pi | `pi` | `~/.pi/agent/sessions/*/*.jsonl`; the first line of each file, `{"type":"session"}`, has the id and cwd |+ | DeepSeek Harness | `dsh` | `~/.dsh/sessions/` |+ | Cursor, TRAE, TRAE CN, ZCode | `cursor`, `trae`, `trae-cn`, `zcode` | not confirmed |++3. Write a small converter under `<tmp>` that writes the sessions to `<tmp>/ov-sessions.jsonl`, one session per line:++ ```json+ {"id": "<the host's own session id>", "cwd": "<absolute path of the directory the session ran in>", "messages": [{"role": "user", "text": "...", "created_at": "2026-10-16T08:00:00Z"}, {"role": "assistant", "text": "...", "created_at": "2026-10-16T08:00:05Z"}]}+ ```++ - `id` is the native session id from the host's records; don't make one up. `cwd` is the directory the session actually ran in. Give every message its ISO 8601 time. Mark sub-agent sessions with `"subagent": true`.+ - Include only what the user and the assistant said: no tool calls, tool output, system prompts or reasoning, and nothing the host or a plugin injected (such as `<openviking-context>`, reminders or notifications).+ - Write every session in the store; don't filter by project, directory or time. The script decides which sessions belong to this project from `--cwd` (subdirectories included) and applies `--since`, and `--list` and `--session` work as usual. The one session to leave out is this conversation, because it contains the key from the install command; if you can't tell which one it is, leave out sessions updated in the last 2 hours.+ - Don't remove keys yourself; the script does. Don't check the JSONL for keys either, and never put the key or any part of it in a command. The converter only reads local files and writes this one JSONL file; it sends nothing.+ - To check the result, look at a summary only, such as the line count and each line's id, cwd and message count. Don't print the whole JSONL into the conversation: it holds other projects' conversations.++4. Dry run: add `--input "<tmp>/ov-sessions.jsonl"` to the onboarding guide's command, with `--harness` from the table, for example:++ ```bash+ node "<tmp>/ov-import-history.mjs" --harness <value> --input "<tmp>/ov-sessions.jsonl" --cwd "$PWD" --since 14d --max-sessions 20 --dry-run --json+ ```++ If the script reports a malformed line, fix the converter, regenerate the file and dry-run again. If the counts are clearly off (no sessions at all in scope, or far fewer messages than the real conversations), check the conversion before importing anything. If 0 sessions are to be uploaded but some have the state `imported` or `live`, the content is already in OpenViking and the conversion is not at fault; go straight to the read-back, as in 3b of the onboarding guide.++5. From here it's the same as in the onboarding guide: ask the user to confirm as in 3b (this conversation was left out by the converter, so it won't show up as still active), and after they confirm, replace `--dry-run` with `--yes --wait` to import, then read back as in 3c. Whether you import or not, delete the JSONL file and the converter afterwards, from every place you wrote them, and check with `ls` that they are gone.++If you can't find where the sessions are kept, or the conversion is still wrong after two or three tries, tell the user that their history from this host couldn't be imported this time and that OpenViking builds up from their conversations once the plugin is active, then go back to Step 4 of the onboarding guide.diff --git a/docs/images/agents/en/onboarding-troubleshooting.md b/docs/images/agents/en/onboarding-troubleshooting.mdnew file mode 100644index 000000000..6b93a726c--- /dev/null+++ b/docs/images/agents/en/onboarding-troubleshooting.md@@ -0,0 +1,23 @@+# OpenViking onboarding guide: troubleshooting (for agents)++Look here when a command from the [onboarding guide](https://docs.openviking.ai/agents/en/onboarding.md) fails. Find the symptom, fix it and retry once; if it still fails, tell the user which step didn't work, what it affects and what they can do.++| Symptom | What to do |+|---|---|+| `The server rejected the API key (HTTP 401/403)` or `The server requires an API key` (Chinese `服务拒绝了该 API key`, `该服务需要 API key`) | The key is wrong, revoked, or for another account. Ask the user to copy it again from the OpenViking console (User Management → API Key) and re-run the install command with the new `--api-key` in their own terminal. On a self-hosted server, use a user key; a root key can't read or write memories. |+| `Cannot reach <url>` (Chinese `无法连接`) | Run `curl -sS -o /dev/null -w '%{http_code}\n' <url>/health`. Any HTTP status, even 401, means the server is reachable. A timeout or connection error means a proxy, VPN or firewall is in the way; ask the user. |+| `CLI not found; skipping: <command>` for this host (for example `Codex-format CLI not found; skipping: codex`) | The installer's shell can't find this host's command, often because it is on a `PATH` set only for interactive shells. Ask the user to run the install command from their original message in their own terminal, where the command works, then continue at Step 1. Don't paste the command back to them; it contains the key. |+| Node.js missing or older than 18 (pi needs 22.19+) | Ask the user to install or upgrade Node.js, then re-run the installer. |+| A sandbox blocks network access or writes to the home directory | Ask the user to approve running it outside the sandbox. Don't work around the sandbox. |+| `curl` exits with code 7 or 6 in Codex | Most likely the sandbox blocked the network, not that the site is down. Ask to run that command outside the sandbox. |+| The host refuses to run `curl … \| bash` | Ask the user to run the install command from their original message in their own terminal, then continue at Step 1. Don't paste the command back to them; it contains the key. |+| This host is not under `Done`, and `Not done` doesn't mention it | The installer didn't detect this host. Re-run it for this host alone, with `<value>` from the `--harness` column of Appendix A in the onboarding guide: `curl -fsSL https://openviking.ai/install \| bash -s -- --yes --harness <value>,cli`. It keeps the saved connection, so leave out the key. Then continue at Step 1. |+| Windows | The installer supports macOS and Linux only. Tell the user and stop. |+| docs.openviking.ai doesn't load | Use docs.openviking.net with the same path. The installer already tries both hosts. |+| `ov: command not found` | Re-run the installer with `--yes --harness cli`; it keeps the saved connection. If `ov` is installed but not on `PATH`, add `$(npm prefix -g)/bin`, or `~/.local/bin` when the installer fell back to `~/.local`. |+| `ov` says it needs a display language | Run `ov language en` (or `ov language zh-CN`). |+| DeepSeek Harness: `dsh plugin add` failed | Install pnpm (`npm i -g pnpm`) and re-run the installer with `--harness dsh`. |+| `Installation validation failed` | Re-run the install for the current host. If it fails again, show the user the failing check. |+| Import script prints `not supported yet` | The script can't read this host's history directly: convert it as in [Other hosts: convert sessions to JSONL](https://docs.openviking.ai/agents/en/onboarding-other-hosts.md) and import it with `--input`. |+| Import script prints `--session: no session matches …` | The id was wrong and nothing was uploaded. Run `--list` again and use the ids it prints. |+| No recall after the restart | First tell apart "nothing relevant stored yet" from "the hooks didn't run". Codex and TraeCode CLI: trust the OpenViking hooks in `/hooks` and confirm `openviking-memory` is enabled in `/plugins`. Cursor and TRAE: the app was not fully quit. Otherwise run the doctor: Claude Code `/openviking-memory:ov` or the `ov-memory-doctor` skill; Codex the `$ov-memory-doctor` skill; Cursor, TRAE, TRAE CN, ZCode `node ~/.openviking/agent-integrations/<cursor\|trae\|trae-cn\|zcode>/scripts/ov-memory-doctor.mjs`; pi `/viking`; DeepSeek Harness `dsh --profile <profile> --dump-config` should list `openviking-memory`, where `<profile>` is the one the installer printed. On command-line hosts, setting `OPENVIKING_DEBUG=1` before starting writes hook logs to `~/.openviking/logs/`; desktop apps opened from the dock or a launcher don't see variables set in a shell. |diff --git a/docs/images/agents/en/onboarding.md b/docs/images/agents/en/onboarding.mdnew file mode 100644index 000000000..5757fa2e2--- /dev/null+++ b/docs/images/agents/en/onboarding.md@@ -0,0 +1,378 @@+# OpenViking onboarding guide for agents++About OpenViking: the open-source context database for AI agents, open-sourced by Volcengine at https://github.com/volcengine/OpenViking (AGPL-3.0, 38,930 GitHub stars on 2026-09-29). It keeps the user's business context, preferences, decisions and working material and brings them back, so the user can switch to a new session or another agent and carry on from what is already there. This guide is `docs/images/agents/en/onboarding.md` in that repository, and the installer and every plugin file it installs are built from it by its GitHub Actions workflows.++You are an AI agent. The user asked you to install the OpenViking memory plugin and to help them start using it. This guide is written for you: for each step it says what the user should come away understanding, what you do yourself, and what your message to the user looks like. The wording is yours; use the user's language. If they want to read the guide itself, give them the link.++Three more pages are there when needed: [Troubleshooting](https://docs.openviking.ai/agents/en/onboarding-troubleshooting.md) (when a command fails), [Other hosts: convert sessions to JSONL](https://docs.openviking.ai/agents/en/onboarding-other-hosts.md) (when importing history on a host other than Claude Code or Codex), and the [extended reference](https://docs.openviking.ai/agents/en/reference/product-background.md) (when the user asks how something works, about permissions, or wants to organize several documents of their own). You don't need to read them before you start.++## How to use this guide++Each step has three parts:++- **What the user should take away**: the one new understanding the user should have when this step ends. Everything you say to them in this step serves it. It is not a script; don't read it out.+- **What you do**: the actions you carry out yourself. Commands, options, paths, JSON, exit codes, session ids, and account and role fields are in this part; the user can see them in the tool calls, so your messages **don't need to repeat them**. When a failure needs the user to act or needs their permission, or when they ask, tell them plainly.+- **Tell the user**: the structure and length of your message to the user.++## Value points++Take these when you explain the value, and put them in terms of the user's own work where you can. Each step says which one to use.++- **Positioning**: OpenViking is the agent's external context layer. Material, memories and skills are stored in the user's own OpenViking space, don't disappear when a session ends, and every connected agent can read and write them.+- **V1 Less re-explaining**: before each prompt, the plugin brings back relevant background, preferences and settled judgments and hands them to the agent. The user doesn't have to explain everything again in every new session.+ - Supporting evidence (use it at most once in the whole onboarding, and say where it comes from): in the official LoCoMo long-conversation evaluation, Claude Code with OpenViking went from 57% to 80% accuracy on cross-session history questions, with 63% fewer input tokens (OpenViking official report, 2026-05-29).+- **V2 Past work is on record**: when they ask "where did we leave off" or "why did we decide that", the answer can be found in the saved discussions instead of in the user's memory.+- **V3 Switch agents, keep the context**: Codex, Claude Code and other agents connected to the same account use the same context. When one agent runs out of quota or they want a different tool, the work carries on.+- **V4 Finished work comes back as it was**: automatic memory keeps the points distilled from conversations; finished work such as designs, decisions with their reasons, and deliverables has to be saved by the agent on purpose, so the original can be read next time.++## How to write messages to the user++- **First what this means for them, then the result, then at most one question.** The first sentence is about their work or what they get, not about which checks you ran.+- **Describe the value as what will happen from now on**: "From now on, when you ask … in Codex, it will …". This explains what the product does once it is set up and doesn't need verifying first; say only what the [value points](#value-points) say, don't overstate it, and don't present something that hasn't happened yet as already done.+- **Mention a status only when it changes what the user does next.** For example, "it takes effect after a restart" needs saying, because they have to restart; notes like "memory extraction isn't confirmed yet" wait for the close and are said once there, not added to the end of every message.+- **Use their own content as examples.** If you can say "the demo storyline you settled on in the Gateway project", don't say "your earlier decisions".+- **Ask one decision at a time.** The import scope, the go-ahead to import and the collaboration rule each get their own turn; wait for the answer before moving on.+- **Ask all three decisions with the choice tool.** For the import scope (3a), the go-ahead to import (3b) and the collaboration rule (Step 4), whenever the host has a tool that lets the user pick an answer (see "Choice tool" under [Appendix A](#appendix-a-hosts)), always ask with it; don't write the options as a text list. The places marked "**Question (choice tool)**" in the steps are where to call it. Put one question and two or three options in the tool; keep option labels short, put extra explanation in the option descriptions, and put the recommended one first, marked "(recommended)". The tool has its own free-text input, so don't add an "Other" option. Only if there is no such tool in your tool list, or the call fails, list the same options in text, and don't retry.+- **Put what they need to see where they are sure to see it.** The question text must make sense on its own: put the points needed for the decision (what the dry run found, the rule summary and the file path) into the question, not just "as above". Some hosts (the Codex desktop app, for example) collapse the progress messages around a tool call once the turn ends, leaving only the last reply and the question card. So the read-back, the rule summary and anything else they need to read go in the body of the last reply of the turn; the question on the choice card carries only a one- or two-sentence summary and the decision, never the whole read-back. With a tool that doesn't wait for the answer, such as `request_user_input_async`, call the tool first, then write the last reply.+- Don't mention the step numbers of this guide or steps that don't apply to the current host, and don't relay the guide point by point.++## Ground rules++- **Never print or repeat the API key.** The installer stores it in `~/.openviking/ovcli.conf` on this machine (backing up the old file when it changes it); the connection needs that. Apart from that, the key must not appear in rules, project files, the continuation message or a permanent command approval. Don't open, print or search `ovcli.conf`. When you need the server and identity, run `ov health` or call the OpenViking `health` tool.+- **Make only the changes this guide describes.** The installer installs into every supported agent it detects on this machine, which is expected. Don't edit other agents' configs or files in the user's projects yourself unless the user asks.+- **Use the commands in this guide.** Don't go to GitHub and read the source to work out another way to install or configure; when unsure of an option, check the command's `--help`.+- **Stick to the facts.** What you read back must come from what OpenViking actually returned. Without the user's real content, don't make up example memories to demonstrate the effect.+- If a command fails, look up the symptom in [Troubleshooting](https://docs.openviking.ai/agents/en/onboarding-troubleshooting.md), fix it and retry once. If it still fails, tell the user which step didn't work, what it affects, and what they can do. Only a connection or auth failure on the current host blocks the steps after it; a failed install for another host doesn't hold up the current one.++## Where to start++- **You ran the installer in this conversation**: start at Step 1.+- **The user says "restarted", and this conversation already went through the earlier steps of this guide**: the user quit and resumed the original session. Go straight to [After the restart](#after-the-restart); the earlier choices are in this conversation, so don't ask them again.+- **In a new session, the user sends a "continue from 'After the restart'" message**: go to [After the restart](#after-the-restart) and take the results the message states.+- **The user only says "restarted", but this conversation has no earlier onboarding steps** (for example `codex resume --last` opened another session, or they started a new one): also go to [After the restart](#after-the-restart), and in its item 2 first ask how far the import and the collaboration rule got, then do what is missing one at a time.+- **OpenViking was installed before this conversation started** (you see an `<openviking-context>` block, or you have OpenViking tools such as `health`): check the connection with `ov health` or the `health` tool and note the user name it returns, tell the user which server and which user they are connected as, and ask whether to keep it or switch.+ - Keep it: do Steps 2 to 4, then go straight to [After the restart](#after-the-restart). No restart is needed.+ - Switch: the plugin is saving this conversation, so don't have the user send a new key here. Ask them to run the install command from the console (or the one below) in their own terminal, then send the console's one-click prompt to an agent in a new session. The old config is backed up and nothing on the server is cleared.+- **There is no connection yet and the user gave no install command**: ask for the server URL and API key (OpenViking console, User Management → API Key), then run the command below with `<value>` from the `--harness` column of [Appendix A](#appendix-a-hosts), and start at Step 1. Keep `cli` in the list: checking the connection, reading content back and adding files all go through the `ov` command.++ ```bash+ curl -fsSL https://openviking.ai/install | bash -s -- --yes --lang en --harness <value>,cli --url <server URL> --api-key <the user's key>+ ```++- **The user only wants to import more history**: do Step 3 only, without the install and the collaboration rule.++## Step 1: Connection result++**What the user should take away**: "My OpenViking is connected; from now on these agents all use the same context." (V3)++**What you do**++Read the installer's output. It may be in English or in Chinese; recognize both.++- If the output ends with a `Not done` list (Chinese `未完成`), judge per host; don't say everything is installed because `Done` appears above it. If the current host failed, the key was rejected or the server can't be reached, handle it with Troubleshooting first; if only other hosts failed, mention it briefly in your message and carry on with the current host.+- The `Done` section (Chinese `完成`) lists the result per tool, each with a `Next:` line (Chinese `下一步:`) saying how to restart it. Check that the current host is listed; if it isn't, see "The current host is not under `Done`" in Troubleshooting.+- Then run `ov health` once: it confirms the connection, and **note the user name it returns**. Writing the collaboration rule and adding files later both use this user name, so you don't need to look it up again. If the installer output already has `Server check passed: <url>` (Chinese `服务检查通过:<url>`), this step is mainly for getting the user name.++**Tell the user**++No separate message. Open the Step 2 message with one sentence: you are connected to their OpenViking, and the plugin went into these agents (by product name, for example Codex, Claude Code). If it went into more than one, add the benefit: from now on they can carry on with the same context in any of these agents.++Don't mention the account name, role, server URL or command names. Tell them which user they are connected as only if they have several OpenViking accounts or ask.++## Step 2: What happens automatically from now on++**What the user should take away**: "I don't have to explain the background every time; what we talk about builds up on its own." (V1)++**What you do**++- Look up three things for the current host in [Appendix A](#appendix-a-hosts): whether the hooks need trusting (and whether that can be done before the restart), where the user can see OpenViking at work, and whether they resume the original session or start a new one after the restart.+- Don't ask whether to turn on automatic memory; the install was the user's request.+- If the user asks how to turn it off in one project, tell them then: put `.openviking/config.json` in that project with `{"version": 1, "capture": {"enabled": false}, "recall": {"enabled": false}}`. Tell them how; don't create it for them.++**Tell the user**++After the Step 1 sentence, in two or three lines:++1. V1: from now on, relevant background is brought to the agent before each prompt, and each turn is saved to their OpenViking automatically and builds up into background over time. Give one example from their current project or request.+2. Where they can see it at work, described the way the user will see it according to Appendix A, for example "an OV-Usage line will appear under answers".+3. If it takes effect only after a restart, say "it starts working after a restart; I'll tell you how at the end". On hosts that need the hooks trusted, add "at the end I'll also ask you to confirm OpenViking's hooks once". The details wait for Step 5.++End this message with the one-sentence value from 3a, then send the 3a question with the choice tool. This message doesn't cover hook event names, the order of saving and extraction, or how to turn it off.++## Step 3: Bring in earlier work++**What the user should take away**: "Past discussions can become background on record. I've seen it for myself this time: it found my work in there." (V2)++This step takes at most three turns: choose the scope → confirm the import → read back the result. The read-back is the point of this step; the import is only the means.++### 3a Choose the scope++**Tell the user**: one sentence of value, ideally in terms of their project: "Bring in your earlier discussions, and next time you ask where <project> left off or why something was decided, there will be something to go on."++**Question (choice tool)**: Which earlier work should I bring in?++- This project, last 14 days (recommended)+- One kind of work or another project, with the description "for example, 'the discussions about the payment refactor'"+- Nothing for now; build up from here++They type any other scope (another time range, all projects) in the tool's free-text input.++**What you do**: Don't download the script or do a dry run before they choose. The import script reads Claude Code and Codex history directly (`--harness claude` or `--harness codex`). On other hosts: if `~/.claude/projects` or `~/.codex/sessions` exists on this machine, you can offer that history as an option as well; the host's own sessions first need converting, see [Other hosts: convert sessions to JSONL](https://docs.openviking.ai/agents/en/onboarding-other-hosts.md).++### 3b Dry run++**What you do**++Option 1 or their own scope: download the script and do a dry run (nothing is uploaded). Replace `<claude|codex>` with the actual value; for their own scope, set `--cwd` to that project's directory, use `--all-projects` instead of `--cwd` for all projects, and change `--since` (for example `30d`, `2026-09-01`, `all`).++```bash+curl -fsSL https://docs.openviking.ai/dl/memory-plugin-shared/import-history.mjs -o "${TMPDIR:-/tmp}/ov-import-history.mjs" && node "${TMPDIR:-/tmp}/ov-import-history.mjs" --harness <claude|codex> --cwd "$PWD" --since 14d --max-sessions 20 --dry-run --json+```++Option 2: first list the sessions in scope with `--list` (each with its id, time, message count, state, and a preview of its first and last request). Set the scope from what the user described; if they didn't say, use this project and the last 30 days. Pick the sessions whose previews match what they described, then dry-run the picked ids (comma-separated; with `--session`, project, time and count limits don't apply):++```bash+curl -fsSL https://docs.openviking.ai/dl/memory-plugin-shared/import-history.mjs -o "${TMPDIR:-/tmp}/ov-import-history.mjs" && node "${TMPDIR:-/tmp}/ov-import-history.mjs" --harness <claude|codex> --cwd "$PWD" --since 30d --max-sessions 50 --list --json+node "${TMPDIR:-/tmp}/ov-import-history.mjs" --harness <claude|codex> --session <id>,<id> --dry-run --json+```++Read the dry-run JSON: `toImport.sessions` is the number of sessions to upload; sessions whose `sessions[].state` is `imported` (imported before) or `live` (already saved by the plugin) are already in OpenViking. The sessions skipped as "still active" include this conversation.++- **`toImport.sessions` is 0, but there are `imported` or `live` sessions**: this content is already in OpenViking, so there is nothing to upload and no need to ask them to confirm. Go straight to the 3c read-back.+- **No sessions at all in scope**: tell them nothing was found in this scope, and ask whether to try another scope or skip importing for now.+- **There are sessions to upload**: ask them to confirm as below.++**Tell the user** (when there are sessions to upload): three or four lines.++- What was found: say which work it is, from the previews (for option 2, which ones you picked and roughly what you left out); no ids.+- How big: how many sessions, and roughly how much text.+- What gets sent: only what they and the agent wrote; no tool calls or tool output, no file originals, and known secret formats are replaced.++**Question (choice tool)**: Import this scope? Options: Import (recommended) / Not for now. If they want to change the scope, they say so in the free-text input.++### 3c Import and read back++**What you do**++If there is nothing new, skip the import and go straight to the read-back. Once the user confirms, import with **exactly the same scope options**, replacing `--dry-run` with `--yes --wait` (`--wait` waits up to two minutes for memory extraction):++```bash+node "${TMPDIR:-/tmp}/ov-import-history.mjs" --harness <claude|codex> --cwd "$PWD" --since 14d --max-sessions 20 --yes --wait --json+```++Check each session's `extraction` in the JSON, not just the exit code.++Then **read back**. Whenever any session is in OpenViking (imported this time, imported before, or already saved by the plugin), read it back. When `--wait` returns, the sessions whose `extraction` is `completed` have already been turned into memories, so the read-back reads memories, not the sessions themselves. The plugin loads into this conversation only after the restart, so use the `ov` command here:++1. Search the memories across the user's whole directory, with the work or project name they described as the query. Memories extracted from the import end up in two places: `viking://user/<user_id>/memories/` (entities, events and preferences that span projects) and `viking://user/<user_id>/peers/<project>/memories/` (this project's entities, events and preferences; `<project>` is `projectPeer` in the import JSON). One search scoped to the user directory covers both:++ ```bash+ ov find "<the work or project name they described>" -u viking://user/<user_id> --context-type memory -n 10+ ```++ To see only the memories this import produced, add `--after` with a time from before the import started, for example `--after 30m`.++2. From the results, pick the two or three most relevant, focusing on the entity (`entities/`) and event (`events/`) memories under the two `memories/` folders above, and read them in full with `ov read`. An entity memory says what this work or thing is and where it stands; an event memory has a summary and also carries the conversation as it was said:++ ```bash+ ov read <memory URI>+ ```++3. Read the imported conversation itself only in two cases: they want the original wording, or no memories were extracted (`extraction` isn't `completed`, or item 1 found nothing). Use the session `id` from the import JSON; an import commits once, so the archive is `archive_001`. Sessions the plugin saved (`live`) aren't read this way; go by what item 1 returned:++ ```bash+ ov session get-session-archive <session id> archive_001+ ```++4. From what you read, put together four things: what this work is meant to achieve, where it left off, one judgment that was settled and its reason, and what is still open. Leave out anything you can't find; don't fill it in. Also note one **gap**: finished work that the discussion mentions but whose original isn't in OpenViking, such as a design doc, a script or a report. Step 4 uses it.++| Import result | What the first sentence says | Read back |+|---|---|---|+| Written, `extraction` is `completed` | Which work was imported, and that the memories are ready | Read memories: `ov find`, then `ov read` one or two |+| Written, extraction still in progress (`pending`, `running`) or no result | The discussions are saved; the memories are still being processed in the background and can be recalled automatically in a few minutes | Read the original conversation (`get-session-archive`), and say "this is read from the original conversation" |+| `failed` | The discussions are saved, but processing them into memories failed; it can be retried later | Read the original conversations |+| Nothing new: all imported before or saved by the plugin | These discussions were already in their OpenViking, so there was no need to upload them again | Read memories (without `--after`) |+| Some failed | Which ones made it and which didn't; the failed ones can be retried later without re-sending everything | Read the ones that made it |+| No match, or the user chose not to import | It builds up from their real work from now on | No; go straight to Step 4 |++If the user asks what the script does: it only reads the session files on this machine (Claude Code in `~/.claude/projects/`, Codex in `~/.codex/sessions/`), keeps only the user and assistant text, redacts known secret formats, skips sessions that may still be running, and files sessions under the same project as the plugin does, so imported history and later conversations end up together. The dry run and `--list` only read from the server, to find sessions that were already imported.++**Tell the user**++1. First sentence: "What the first sentence says" in the table above. Don't give message counts, sizes, or state names such as `extraction`.+2. The read-back, two to four items, in their own words and names: what they are working on, where it left off, what was decided (with the reason), what is still missing. If there are several pieces of work, one line each, no detail. The read-back goes in the body of this message; the choice card for the next step mentions it in one sentence at most.+3. One sentence of value (V2 + V3): "From now on, in any connected agent, ask where <work> stands and it picks up from here."++This message doesn't ask whether to start on this work, and doesn't list states. In the same message, go on to the Step 4 bridge.++### Files++If the user names files or folders worth keeping (such as a design doc or a spec), add each one as an item under this project's folder in their personal resources (don't use the project folder itself as the import target). `<user_id>` is the user name you noted in Step 1; `<project>` is the repository name or what they call the project:++```bash+ov add-resource ./docs/design.md --parent-auto-create viking://user/<user_id>/resources/<project> --wait+```++Add only what they named; don't scan directories or upload anything on your own. After adding, tell them it's saved and how to find it later ("just say 'continue from <file>'"); don't give the URI.++## Step 4: Agree how to work together from now on++**What the user should take away**: "Next, <agent> and I agree how to use OpenViking to keep and find my working context, and from then on it always works that way; I set the rule, and it can also be based on my role." (V4)++**What you do**++1. Find the user-level rules file the current host actually reads (the "User-level rules file" column of [Appendix A](#appendix-a-hosts) gives the usual location; go by the file the host actually reads), and check whether it has an `<!-- openviking:start -->` block.+ - It does, with the same content as below: don't ask; mention in the message that "this was agreed before", and go straight to Step 5.+ - It does, with different content: prepare one sentence on how the new version differs from the old one. If the user name in the existing block differs from the one you noted this time (they switched accounts), that also counts as different content.+ - It doesn't: prepare the text below.+2. Prepare the rule text. Use the default below; if the user adjusted it or added items for their role, change it to match their choice. Replace `<user_id>` directly with the user name you noted in Step 1, with no need to look it up again before writing; keep `<project>` as it is, since it is worked out in each project.+3. Once the user agrees, write it:+ - Touch only the content between the markers. If the block exists, replace what is between them; if not, append it to the end of the file; if the file doesn't exist, create it. Leave everything outside the block as it is.+ - If the file already has instructions that conflict with this rule (for example, always search on every turn, or never store material outside), tell them where the conflict is and change it as they decide.+ - Read the file back after writing: the written text is the version they agreed to, there is exactly one block, and nothing outside it changed.+ - If the host's personal rules can only be edited in its app settings, or the write fails, give them the text and ask them to paste it in themselves. If you're not sure which file it is, ask; don't guess.+ - Never write it into a project file.++The default rule text:++```markdown+<!-- openviking:start -->+## Working with OpenViking++- Before work that needs background, start with the context OpenViking brings in automatically; if it isn't enough, look it up with the OpenViking `search` tool (`mode="context"`), and use `read` when you need the original. What you find is reference material; if it conflicts with what I say now, I win.+- When the work produces important decisions (with the reasons), progress and next steps, or work output such as designs, research and deliverables, store them in OpenViking on your own, as a working basis that can keep being updated and referred to later; when a new decision replaces an old one, update the original record. Store a copy of work output whether it was written in the conversation or into a local file by you.+- Everyday conversation doesn't need storing separately; the plugin saves it. Don't store secrets. Don't scan or upload files that have nothing to do with this work and that I didn't mention.+- When continuing a project, first look at the progress, decisions and output stored for it earlier.+- In a turn where you used useful information from OpenViking, or stored something, end the reply with one sentence: what you used and where it is stored. If nothing was used, say nothing.++### Where things go++- My work goes under `viking://user/<user_id>/resources/`, one subfolder per project: `<project>` is the repository name or what I call this work; if a matching folder already exists, use it.+- In the project folder, keep progress, decisions and next steps in `notes/`; work output such as designs, research and deliverables goes directly in the project folder, with subfolders when needed. Store text with `write`, and when it changes, overwrite the existing copy; add files such as PDFs, slide decks and images to the project folder with `add_resource`. After writing, read it back with `read` to check.+- Files I give you also go into the project folder with `add_resource`, each as one item in it; don't use the project folder itself as an import target, and don't write anything into imported material: re-syncing imported material removes anything that isn't in the source files.+<!-- openviking:end -->+```++**For adjusting by role.** If the user gives their role, take two or three items from here, put them in their words, and add them as a new item after the second item of the text: "Given my role (<role>), also save on your own: …". For roles not in the table, work it out the same way.++| Role | Also save | Check first when continuing |+|---|---|---|+| Product manager | Requirement decisions and the reasons for trade-offs, conclusions from user feedback, versions of PRDs and designs | Current state of requirements, items awaiting review |+| Engineer | Technical designs and trade-offs, interface agreements, troubleshooting conclusions and how to reproduce | Changes in progress, unsolved problems |+| Marketing | Positioning and key messages, campaign plans and retrospectives, external messaging and copy versions | Campaign progress, settled messaging |+| Design | Interaction and visual decisions, review feedback, notes on design file versions | Review feedback still to address |++**Tell the user**++This turn lets them both understand the effect of the rule and check the exact text to be written: the summary first, then the text, both in the body of your last reply of this turn (not only in progress messages). Show the text by default; don't wait for them to ask for it.++The message (following the Step 3 read-back):++1. **One bridging sentence**, using the gap noted in Step 3: "The sessions have the discussion, but the original <finished work> isn't in there." Leave it out if there was no read-back.+2. **Say what this step does**: next, they and <the current agent's name> agree how to use OpenViking to keep and find working context; the rule goes into <full path of the rules file>, applies to all their projects, is followed in all their work from now on, and can be changed at any time.+3. **The approach we suggest**, three points, in the user's language, without storage locations, folders or tool names:+ - before starting work, bring back the relevant background from OpenViking;+ - when the work produces important decisions (with the reasons), progress and next steps, or output such as designs, research and deliverables, store them in OpenViking on its own, as a working basis that can keep being updated and referred to later;+ - whenever useful information from OpenViking was used, say so briefly at the end of the reply.+4. **The text to be written**: right after the summary, say "Here is the text that will go into <full path of the rules file>:", then give the full text in a code block (with `<user_id>` replaced by their user name).++**Question (choice tool)**: The question text must make sense on its own, with the gist of the summary and the file path, for example "Work this way from now on? Bring back background before starting work; store important decisions, progress, and output such as designs and research in OpenViking on my own; tell you briefly when I used it. Goes into <rules file path>, for all projects." Options:++- Work this way (recommended)+- Adjust for my role, with the description "Tell me your role, for example marketing, product or engineering, and I'll suggest what to save"+- Automatic memory only++In the question or a description, mention that if they want to change anything in the text, they can say so directly in the free-text input.++Then:++- **Work this way**: write it.+- **Adjust for my role**: ask their role (one sentence in text is enough). Using the reference above, give the adjusted effect in three or four points, marking which ones are new, together with the adjusted text, then ask with the choice tool: Write this (recommended) / Adjust again / Automatic memory only.+- **They said directly what to change**: change the text as they want, show the effect and the changed text, and ask again.+- **Automatic memory only**: write nothing. Tell them they can still ask you to save or read material at any time.++The summary must truthfully match the text to be written: anything in the text that the summary doesn't mention may only be implementation detail of behavior the summary describes (such as where things go).++If they ask "where is it stored", explain then: in their personal OpenViking space, one folder per project; progress and decisions go in the project's notes; designs, research and deliverables (whether you produced them or they uploaded them) go in that project folder too. Wait for their answer before Step 5; don't bring up the restart in the same message as this question.++## Step 5: Restart++**What the user should take away**: "One more step and it's ready to use; when I come back, it picks up right where my work is."++**What you do**++- If it is already active on the current host and nothing was newly installed, skip this step and go straight to [After the restart](#after-the-restart).+- Look up the "Restart or trust" and "After restart" columns for the current host in [Appendix A](#appendix-a-hosts), and the installer's `Next:` lines (Chinese `下一步:`) for the other tools.+- Prepare the continuation message. Use the URL you actually opened successfully; if this guide is a local file, use its absolute path. Fill in the angle brackets with the real results:++```text+Restarted. Continue the OpenViking onboarding from "After the restart" in https://docs.openviking.ai/agents/en/onboarding.md. History import: <for example "2 sessions imported", "already in OpenViking", "skipped">; collaboration rule: <added / not added>; what I want to do next: <the goal they mentioned, or if none, "see where <work> left off">.+```++**Tell the user**++1. Where things stand, stated positively: connected, and which work was brought in. If the collaboration rule was written, list its three summary points again with the rules file path, and tell them that to read or change it later they can open that file or ask you; if it wasn't written, say so.+2. **On hosts that need the hooks trusted (Codex, TraeCode CLI 2.0), ask them to trust the hooks before quitting**: in the Codex desktop app, click the hooks icon below the input box; in Codex CLI and TraeCode CLI, type `/hooks` in the session; trust all of OpenViking's hooks. Give the benefit in one sentence: after the restart it won't stop at a review prompt, and they can carry on with their work right away. Appendix A says what to tell the user after trusting (Codex saves this install conversation, key included); cover that in one sentence too. If "Hooks need review" still appears after the restart, choose **Trust all and continue** as before.+3. How to restart the current host.+4. If the installer also set up other agents, add one line naming them: each takes effect after its own restart; see the "Next" lines in the installer output.+5. What to do when they come back:+ - Hosts whose "After restart" column says to resume the original session: tell them to come back to **this conversation** with the command in the table and send "restarted". Give them the continuation message as well, as a fallback: if they land in a different conversation, they send it in a new session.+ - Hosts that say to start a new session: tell them to start a new session, not to resume this conversation or reload the plugin in it, and give them the continuation message.+6. One line on what comes next: "When you're back, I'll first tell you where <work> left off, then give you a few directions to take it." If no work was brought in: "When you're back, just tell me what you want to do."++Then stop and wait for the user.++## After the restart++**What the user should take away**: "It really did pick up: I didn't explain any background, and it knows what I'm working on." (V1, V2)++**What you do**++1. **Check the plugin is running.** There is an `<openviking-context>` block in this conversation, or OpenViking tools are available. Call the `health` tool (its name may carry a prefix, such as `mcp__openviking__health` or `openviking_health`). If neither is there, see "No recall after the restart" in Troubleshooting. Only an injected block shows that automatic recall is running; no relevant memories may simply mean nothing relevant is stored yet.+2. **Fill in missing choices.** From this conversation or the continuation message, check whether the import and the collaboration rule were done. Do whichever step is missing; don't re-ask what was settled.+3. **Bring back the background.** Use the injected context first; if it isn't enough, use `search` (`mode="context"`), and `read` the original when needed. While memories are still being processed, you may read the imported original conversations, but say that you read the original record.++**Tell the user**++Pick one by the outcome they want:++| They want | What the message contains |+|---|---|+| To continue earlier work | What the work is meant to achieve, where it left off, which judgments were settled and what is still open; then two or three concrete directions to take it. Point out one piece of evidence that came from OpenViking and how it shaped your suggestion (V1). If there are several pieces of work, let them pick one first. |+| To keep or reuse a document | Add the file they named and read it back, or read stored material to answer a real question of theirs; tell them how to find it next time. |+| To start fresh, or not now | One sentence on how things will build up from here, and invite them to start on a real task or come back later. |++After the summary and directions, wait for them to choose; don't start changing code or pushing the task on your own.++**Close** with at most three lines, after they choose a direction or at the end of this message:++- What already works, and what is still running in the background (for example memory processing). Any status not yet confirmed is mentioned here, once.+- Where they can see OpenViking at work on this host ("Where to see it" in Appendix A).+- One or two things they can say later, chosen for them: "import the sessions of <project> into OpenViking", "save this document and continue from it later", "switch to another OpenViking account" (handled as the "Switch" case in [Where to start](#where-to-start)). If other agents got the plugin, mention that they can carry on this work there and the background will still be there (V3).++## Appendix A: Hosts++| Host | `--harness` | Restart or trust | After restart | Where to see it | History import | User-level rules file |+|---|---|---|---|---|---|---|+| Claude Code | `claude` | Quit and run `claude` again; don't use `/reload-plugins` | New session. Don't use `claude --continue` / `--resume` to go back to the install conversation: the plugin would save the whole install conversation, key included, to OpenViking | A source card under answers that used OpenViking (Claude Code 2.1.286 and later); `/openviking-memory:ov` for status | Supported | `~/.claude/CLAUDE.md` |+| Codex | `codex` | **Trust the hooks before quitting**: in the desktop app, click the hooks icon below the input box; in the CLI, type `/hooks` in the session; trust all of OpenViking's hooks. The trust is recorded in `~/.codex/config.toml`, so there is no prompt after the restart. Then quit: in the CLI, run `codex resume --last` to come back to this conversation; in the desktop app, quit, reopen it and go back to this conversation. If "Hooks need review" still appears after the restart, choose **Trust all and continue**. Tell the user: once the hooks are trusted, this install conversation is saved to their own OpenViking account, including the API key from the install command and the session previews listed for the import, whether they resume or start a new session; if that bothers them, they can replace the key in the console afterwards | Resume the original session (the command on the left) and send "restarted" | An OV-Usage line after each answer, for example `OpenViking · 3 sources · 1 past event · 2 team docs · 1 read` | Supported | `~/.codex/AGENTS.md`; if `AGENTS.override.md` exists in the same folder, Codex reads that instead |+| TraeCode CLI 2.0 | `trae-cli` | **Trust the hooks before quitting**: type `/hooks` in the session and trust all of OpenViking's hooks. Then quit and run `trae-cli` (or `traecli`) again; if "Hooks need review" still appears, choose **Trust all and continue** | New session | An OV-Usage line, as in Codex | Convert to JSONL; sessions are in `~/.trae/cli/sessions/`, the same rollout format as Codex | Not confirmed |+| Cursor | `cursor` | Quit Cursor completely and reopen it | New Agent session (**+**); don't continue in the restored install conversation | The OpenViking hook under Settings → Hooks; `openviking` connected under Settings → Tools & MCPs | Convert to JSONL; session location not confirmed | User Rules in Cursor settings; ask the user to paste |+| TRAE / TRAE CN | `trae` / `trae-cn` | Quit the app completely and reopen it; no hook approval needed | New session | `openviking` connected in the MCP settings | Convert to JSONL; session location not confirmed | Personal rules in the app settings; ask the user to paste |+| ZCode | `zcode` | Restart ZCode | New session | Not documented | Convert to JSONL; session location not confirmed | Personal rules in the app settings; ask the user to paste |+| Kimi Code | `kimicode` | Quit Kimi Code; don't use `/reload` | New session; don't resume the current one | Not documented | Convert to JSONL; sessions are in `~/.kimi-code/sessions/` (under `$KIMI_CODE_HOME` if set) | `~/.kimi-code/AGENTS.md` (same) |+| OpenCode | `opencode` | Restart OpenCode | New session | Not documented | Convert to JSONL; sessions are in the SQLite database `~/.local/share/opencode/opencode.db` | `~/.config/opencode/AGENTS.md` |+| pi | `pi` | Restart pi | New session | `OV ✓` in the footer; `/viking` for status | Convert to JSONL; sessions are in `~/.pi/agent/sessions/*/*.jsonl` | `~/.pi/agent/AGENTS.md` |+| DeepSeek Harness | `dsh` | Start a new session with the profile from the installer's `DeepSeek Harness profile:` line: `dsh --profile <profile>` | New session | "Context injection · openviking-memory" at the top of the session | Convert to JSONL; sessions are in `~/.dsh/sessions/` | Not confirmed |++- **Codex approvals.** Codex asks before running commands that need the network, including the `ov find`, `ov read` and `ov session` used for the read-back here. For the install command, which carries the key, choose **Yes, proceed**, not "don't ask again for commands that start with …": that rule would store the key. The first time the OpenViking `search` tool runs, Codex asks for permission; choose **Always allow**. Trusting hooks and approving commands are separate things.+- **Choice tool.**+ - Claude Code: `AskUserQuestion`.+ - Codex: there are two; use whichever is in your tool list, preferring `request_user_input_async`.+ - `request_user_input_async`: models such as the gpt-6 series also have it in Default mode (for example, the Codex desktop app 0.164). It posts the question as a choice card without waiting for the answer, and the user's pick comes back as the next message. The Codex desktop app collapses progress messages once the turn ends, so after calling it, put what they need to read in the last reply of the turn.+ - `request_user_input`: works only in Plan mode (also in Default mode if the user turned on `default_mode_request_user_input`); otherwise a call returns `request_user_input is unavailable in Default mode`.+ - Codex's Default-mode instructions also say not to write multiple-choice questions as text messages. Ask in text only if neither is available.+ - These tools all add an "Other" option for the user's own input automatically, so don't put an "Other" option among yours. On other hosts, use a similar tool if there is one; otherwise ask in text.+- **Not documented.** On these hosts, the user can ask you directly what OpenViking context you received, or run the diagnostics in Troubleshooting.++Details for each host: https://docs.openviking.ai/en/agent-integrations/01-overviewdiff --git a/docs/images/agents/en/opencode.md b/docs/images/agents/en/opencode.mdindex ea9c732c2..03c570d5c 100644--- a/docs/images/agents/en/opencode.md+++ b/docs/images/agents/en/opencode.md@@ -19,6 +19,16 @@2. Run `/mcps` and confirm the list shows `openviking connected`.3. Explicitly ask OpenCode to call `openviking_search` and `openviking_read` to verify tool access. Automatic recall runs through hooks without those model tool calls; check it separately by asking about stored information in a new session.+## Step 3: Start using++Start a new OpenCode session and send:++```text+Follow https://docs.openviking.net/agents/en/onboarding.md to walk me through my first use of OpenViking.+```++The agent checks the connection and walks you through the first use.+## Troubleshoot| Problem | Fix |diff --git a/docs/images/agents/en/pi.md b/docs/images/agents/en/pi.mdindex f741a722c..0bdb78e1c 100644--- a/docs/images/agents/en/pi.md+++ b/docs/images/agents/en/pi.md@@ -19,6 +19,16 @@2. Run `/viking` and confirm it shows the current session mapping and the number of registered `openviking_*` tools.3. In a new session, ask about something you mentioned earlier to confirm recall.+## Step 3: Start using++Start a new pi session and send:++```text+Follow https://docs.openviking.net/agents/en/onboarding.md to walk me through my first use of OpenViking.+```++The agent checks the connection and walks you through the first use.+## Troubleshoot| Problem | Fix |diff --git a/docs/images/agents/en/reference/product-background.md b/docs/images/agents/en/reference/product-background.mdnew file mode 100644index 000000000..45e2dc96a--- /dev/null+++ b/docs/images/agents/en/reference/product-background.md@@ -0,0 +1,42 @@+# OpenViking extended reference++The [onboarding guide](https://docs.openviking.ai/agents/en/onboarding.md) already explains what a normal setup needs. This page is for answering the user's follow-up questions or handling goals beyond the setup; you don't need to read it through before you start, only the part relevant to the question at hand. Knowing something here doesn't mean the current tools support it, and it doesn't authorize extra tasks.++## Kinds of content and processing states++- Sessions keep the interaction within what is supported; a stored session doesn't prove it holds the latest messages.+- Memories are extracted and updated by the service from committed sessions according to its policies, such as preferences, events and experience. Memories can be missing or out of date; what the user asks for now takes precedence.+- Resources keep readable content such as requirements, designs and reports; mentioning a file in a chat doesn't upload the original, and importing the body doesn't prove every attachment was backed up.+- Skills provide reusable procedures; saving experience doesn't create or install a skill.++A message written, a commit submitted, extraction finished, a search hit and actual use are different states. To confirm a state, check the matching result; don't infer finished extraction from a file existing, or use of an answer from a source count.++## Hooks, rules and cost++Hooks are how the host runs the plugin on session events: loading background, recall, capture or triggering a commit. The exact events, trust requirements, what is sent and when commits happen depend on the installed version. If a client doesn't use hooks, describe its actual plugin mechanism, and don't send the user looking for an approval screen that doesn't exist.++The lasting rule tells the agent when to look up the originals, what to save on purpose and how to report it; it doesn't create a background file watcher and doesn't guarantee correct behavior every turn. When the automatic injection is enough, don't force extra lookups, and when an ordinary conversation is already captured, don't save it again by hand.++Search, injection and processing can cost context and model calls. Bring back background by relevance to the task and read originals only when the details are needed; don't promise a fixed saving. Whether it overlaps with the host's own memory depends on what each one covers; don't claim it replaces it wholesale.++## Folders and layered reading++OpenViking keeps where content belongs and where it came from through folders and URIs. The L0 abstract helps identify the topic, the L1 overview helps understand the content, and L2 is the original for checking details. Pick the level by the question, don't load the whole history by default, and don't make the user learn these terms first.++To continue work, start from the injected context and the related memories and notes, and read the session originals when details are needed. Across several sessions, check against dates, scope and the original records; don't take the latest session for the whole project. Don't reopen finished items, don't take earlier plans for what is live now, and go back to the original when summaries conflict.++## Across agents and identities++Once another session or agent connects to content the same identity can reach, it can continue the work with the existing background. It doesn't copy the whole chat window, device state, client rules or attachments that were never uploaded in real time, and the latest content that wasn't committed or processed yet may be missing.++Check identity and content availability only for the two ends the user chose, and don't install a second client just to explain. Verifying it takes an independent context that actually retrieves the background; reading it back in the original chat is not a cross-agent verification.++The same URL doesn't mean the same user. Binding or switching identities doesn't move earlier material; re-align the read and write scopes and keep the original config. Without an actual way to bind or switch, state the limit; don't invent commands.++## Preferences, experience and organizing knowledge++Preferences help the collaboration fit stable ways of expressing and judging things; apply them only where they fit the current work, don't turn a one-off choice into a lasting preference, and don't collect unrelated personal information to show the effect.++Experience keeps what worked, corrections and when they apply. Explain why it fits the current task rather than copying it mechanically; whether extraction is on and whether it is searchable needs checking, so don't promise experience will be produced every turn.++Organizing knowledge, Compile, suits building sourced topic knowledge or a wiki from several documents. It runs as `ov compile` in the `ov` command line (the installer's `cli` entry installs `ov`), is executed by the server's Compile Runtime, and writes its results back into OpenViking. First check that the server supports it, the source scope and where the output goes, then run it as the user authorizes; usage is at https://docs.openviking.ai/en/context-compilation/01-overview . Installing the plugin, importing history or producing an ordinary summary is not the same as running Compile.diff --git a/docs/images/agents/en/trae.md b/docs/images/agents/en/trae.mdindex 71337d1bb..7b342e1fe 100644--- a/docs/images/agents/en/trae.md+++ b/docs/images/agents/en/trae.md@@ -33,6 +33,16 @@ If you skipped it or picked option 3, review and enable the OpenViking hooks inAn MCP entry only confirms configuration. Ask the assistant to call OpenViking `health` and `list`, then check automatic recall separately using a new conversation in the same workspace after a previous session has been committed and processed.+## Step 3: Start using++Start a new TRAE, TRAE CN or TraeCode CLI 2.0 session and send:++```text+Follow https://docs.openviking.net/agents/en/onboarding.md to walk me through my first use of OpenViking.+```++The agent checks the connection and walks you through the first use.+## Troubleshoot| Problem | Fix |diff --git a/docs/images/agents/en/zcode.md b/docs/images/agents/en/zcode.mdindex 138ba01e4..ff886e16c 100644--- a/docs/images/agents/en/zcode.md+++ b/docs/images/agents/en/zcode.md@@ -19,6 +19,16 @@2. Confirm `~/.zcode/cli/config.json` contains `hooks.enabled: true`, OpenViking entries under `hooks.events`, and `mcp.servers.openviking`.3. Run `node ~/.openviking/agent-integrations/zcode/scripts/ov-memory-doctor.mjs` to check the installation and the server connection.+## Step 3: Start using++Start a new ZCode session and send:++```text+Follow https://docs.openviking.net/agents/en/onboarding.md to walk me through my first use of OpenViking.+```++The agent checks the connection and walks you through the first use.+## Troubleshoot| Problem | Fix |diff --git a/docs/images/agents/zh/claude-code.md b/docs/images/agents/zh/claude-code.mdindex 42e9f897b..ef34b14a9 100644--- a/docs/images/agents/zh/claude-code.md+++ b/docs/images/agents/zh/claude-code.md@@ -47,6 +47,16 @@✅ Status: OpenViking server is healthy and running```+## 步骤3:开始使用++在 Claude Code 中新开一个会话,发送:++```text+按 https://docs.openviking.net/agents/zh/onboarding.md 带我完成 OpenViking 首次使用。+```++Agent 会检查连接,并带你完成首次使用。+## 故障排查| 问题 | 处理 |diff --git a/docs/images/agents/zh/codex.md b/docs/images/agents/zh/codex.mdindex 1d9039df2..3c09bed18 100644--- a/docs/images/agents/zh/codex.md+++ b/docs/images/agents/zh/codex.md@@ -39,6 +39,16 @@新账号可能还没有 profile 或相关记忆可注入。会话提交时机和完整验证步骤见下方文档。+## 步骤3:开始使用++在 Codex 中新开一个会话,发送:++```text+按 https://docs.openviking.net/agents/zh/onboarding.md 带我完成 OpenViking 首次使用。+```++Agent 会检查连接,并带你完成首次使用。+## 故障排查| 问题 | 处理 |diff --git a/docs/images/agents/zh/cursor.md b/docs/images/agents/zh/cursor.mdindex 3971a70ec..e2225c73e 100644--- a/docs/images/agents/zh/cursor.md+++ b/docs/images/agents/zh/cursor.md@@ -18,6 +18,16 @@1. 点击「Customize → MCPs」,确认可以看到「openviking User」和「openviking Plugin」两项。2. 点击「Customize → Hooks」,确认可以看到「openviking-memory」条目。+## 步骤3:开始使用++在 Cursor 中新开一个会话,发送:++```text+按 https://docs.openviking.net/agents/zh/onboarding.md 带我完成 OpenViking 首次使用。+```++Agent 会检查连接,并带你完成首次使用。+## 故障排查| 问题 | 处理 |diff --git a/docs/images/agents/zh/deepseek-harness.md b/docs/images/agents/zh/deepseek-harness.mdindex 255878a7f..4fcf8d08f 100644--- a/docs/images/agents/zh/deepseek-harness.md+++ b/docs/images/agents/zh/deepseek-harness.md@@ -21,6 +21,16 @@ curl -fsSL https://openviking.ai/install | bash2. 确认模型具有 `mcp__openviking__*` 工具,并能够在会话中正常调用。3. Desktop 用户在应用中新开会话,检查以上两点。`--dump-config` 对 Desktop 的 `desktop` profile 不可用,改为确认 `~/.dsh/profiles/desktop/package.json` 的 `dsh.profile.bundles` 中有该插件。+## 步骤3:开始使用++在 DeepSeek Harness 中新开一个会话,发送:++```text+按 https://docs.openviking.net/agents/zh/onboarding.md 带我完成 OpenViking 首次使用。+```++Agent 会检查连接,并带你完成首次使用。+## 故障排查| 现象 | 排查方向 |diff --git a/docs/images/agents/zh/kimi-code.md b/docs/images/agents/zh/kimi-code.mdindex 3a5cf6897..1017911b9 100644--- a/docs/images/agents/zh/kimi-code.md+++ b/docs/images/agents/zh/kimi-code.md@@ -19,6 +19,16 @@2. 确认 `~/.kimi-code/plugins/installed.json` 中有 `openviking-memory` 条目。3. 新开会话,询问之前提到过的信息,确认召回生效。+## 步骤3:开始使用++在 Kimi Code 中新开一个会话,发送:++```text+按 https://docs.openviking.net/agents/zh/onboarding.md 带我完成 OpenViking 首次使用。+```++Agent 会检查连接,并带你完成首次使用。+## 故障排查| 问题 | 处理 |diff --git a/docs/images/agents/zh/onboarding-other-hosts.md b/docs/images/agents/zh/onboarding-other-hosts.mdnew file mode 100644index 000000000..62f137f6a--- /dev/null+++ b/docs/images/agents/zh/onboarding-other-hosts.md@@ -0,0 +1,44 @@+# OpenViking 接入引导:其他宿主的历史导入(给 Agent 看)++导入脚本只能直接读 Claude Code 和 Codex 的历史。在其他宿主上,用户在[接入引导](https://docs.openviking.net/agents/zh/onboarding.md)步骤 3 选了导入时,先由你把这个宿主的会话转成 JSONL,再交给同一个脚本。范围选择、确认和结果说明都和接入引导里一样,这一页只讲转换。++1. 运行 `echo "${TMPDIR:-/tmp}"`,记下这个临时目录,下面写作 `<tmp>`。之后写文件、跑命令都用这个绝对路径,不要再写 `${TMPDIR:-/tmp}`。下载导入脚本:++ ```bash+ curl -fsSL https://docs.openviking.net/dl/memory-plugin-shared/import-history.mjs -o "<tmp>/ov-import-history.mjs"+ ```++2. 找到当前宿主在本机保存会话的地方。下表是提示,以本机实际为准。只读,不要改。++ | 宿主 | `--harness` | 会话位置 |+ |---|---|---|+ | TraeCode CLI 2.0 | `trae-cli` | `~/.trae/cli/sessions/`,和 Codex 相同的 rollout 格式 |+ | Kimi Code | `kimicode` | `~/.kimi-code/sessions/`(设置了 `$KIMI_CODE_HOME` 时在该目录下),每个会话的 `state.json` 带 cwd,消息在 `agents/main/wire.jsonl` |+ | OpenCode | `opencode` | SQLite 库 `~/.local/share/opencode/opencode.db`,没有 `sqlite3` 时可用 Node 22 的 `node:sqlite` 只读打开;`synthetic` 的文本是注入内容,`parent_id` 非空的是子代理会话 |+ | pi | `pi` | `~/.pi/agent/sessions/*/*.jsonl`,每个文件第一行 `{"type":"session"}` 带 id 和 cwd |+ | DeepSeek Harness | `dsh` | `~/.dsh/sessions/` |+ | Cursor、TRAE、TRAE CN、ZCode | `cursor`、`trae`、`trae-cn`、`zcode` | 未确认 |++3. 在 `<tmp>` 下写一个小转换脚本,把会话写进 `<tmp>/ov-sessions.jsonl`,每行一个会话:++ ```json+ {"id": "<宿主自己的会话 id>", "cwd": "<会话所在目录的绝对路径>", "messages": [{"role": "user", "text": "……", "created_at": "2026-10-16T08:00:00Z"}, {"role": "assistant", "text": "……", "created_at": "2026-10-16T08:00:05Z"}]}+ ```++ - `id` 用宿主记录里的原生会话 id,不要自己生成;`cwd` 用会话实际所在的目录;每条消息都带上 ISO 8601 时间。子代理的会话加上 `"subagent": true`。+ - 只放用户和助手说的话。工具调用、工具输出、系统提示、思考过程,以及宿主或插件注入的内容(例如 `<openviking-context>`、提醒、通知)都不要放。+ - 存储里的会话全部写进去,不要按项目、目录或时间筛选:脚本会按 `--cwd` 判断哪些属于这个项目(包括子目录),按 `--since` 筛时间,`--list` 和 `--session` 也照常可用。唯一要排除的是当前这段对话,因为它含有安装命令里的 key;认不出是哪一段时,排除最近 2 小时内有更新的会话。+ - 不用自己删 key,脚本会做;也不要自己去查 JSONL 里有没有 key,命令里不能出现 key 或它的任何一段。转换脚本只读本地文件、只写这一个 JSONL,不发送任何东西。+ - 检查转换结果时只看摘要,例如行数和每行的 id、cwd、消息数,不要把整个 JSONL 打印到对话里:里面有其他项目的对话。++4. 试运行。在接入引导的命令上加 `--input "<tmp>/ov-sessions.jsonl"`,`--harness` 用上表的值,例如:++ ```bash+ node "<tmp>/ov-import-history.mjs" --harness <值> --input "<tmp>/ov-sessions.jsonl" --cwd "$PWD" --since 14d --max-sessions 20 --dry-run --json+ ```++ 脚本指出某一行格式不对时,改转换脚本、重新生成,再试运行。数量明显不对(例如范围内一个会话都没有,或消息数远少于实际对话)时,先检查转换,不要直接导入。要上传的是 0 个、但有状态为 `imported` 或 `live` 的会话,说明内容已经在 OpenViking 里,不是转换出错,按接入引导 3b 直接去读回。++5. 之后和接入引导里一样:按 3b 请用户确认(当前这段对话已经由转换脚本排除,不会出现在「仍在活动」里),他确认后把 `--dry-run` 换成 `--yes --wait` 正式导入,再按 3c 读回。导入完,或者决定不导入,都要删掉 JSONL 和转换脚本;写到过几个位置就删几处,再用 `ls` 确认已经删掉。++找不到会话保存在哪,或者改了两三次仍转换不对,就告诉用户这次没能导入这个宿主的历史,OpenViking 会从插件生效后的对话开始积累,然后回到接入引导的步骤 4。diff --git a/docs/images/agents/zh/onboarding-troubleshooting.md b/docs/images/agents/zh/onboarding-troubleshooting.mdnew file mode 100644index 000000000..8a42e65a2--- /dev/null+++ b/docs/images/agents/zh/onboarding-troubleshooting.md@@ -0,0 +1,23 @@+# OpenViking 接入引导:故障排查(给 Agent 看)++[接入引导](https://docs.openviking.net/agents/zh/onboarding.md)里的命令失败时查这一页。找到对应现象,修好后重试一次;仍然失败,就告诉用户哪一步没成、影响什么、他可以怎么处理。++| 现象 | 处理 |+|---|---|+| `服务拒绝了该 API key(HTTP 401/403)` 或 `该服务需要 API key`(英文 `The server rejected the API key`、`The server requires an API key`) | key 错误、已失效,或属于其他账号。请用户到 OpenViking 控制台(用户管理 → API Key)重新复制 key,在他自己的终端里用新的 `--api-key` 重跑安装命令。自部署服务要用 user key,root key 不能读写记忆。 |+| `无法连接 <url>`(英文 `Cannot reach`) | 运行 `curl -sS -o /dev/null -w '%{http_code}\n' <url>/health`。只要返回 HTTP 状态码(包括 401),服务就是可达的。超时或连接错误说明被代理、VPN 或防火墙挡住了,请用户处理。 |+| 当前宿主出现 `未找到 … CLI,跳过:<命令>`(英文 `CLI not found; skipping`,例如 `未找到 Codex 格式 CLI,跳过:codex`) | 安装器所在的 shell 找不到这个宿主的命令,常见原因是 `PATH` 只在交互式 shell 里设置。请用户在自己的终端里(能直接运行该命令的地方)运行他原始消息中的安装命令,然后从步骤 1 继续。不要把命令贴回给用户,命令里有 key。 |+| 没有 Node.js,或版本低于 18(pi 需要 22.19 及以上) | 请用户安装或升级 Node.js,然后重跑安装器。 |+| 沙箱拦截了联网或写入主目录 | 请用户批准在沙箱外运行。不要绕过沙箱。 |+| Codex 里 `curl` 返回退出码 7 或 6 | 多半是沙箱拦住了联网,不是网站挂了。申请在沙箱外运行这条命令。 |+| 宿主拒绝执行 `curl … \| bash` | 请用户在自己的终端里运行他原始消息中的安装命令,然后从步骤 1 继续。不要把命令贴回给用户,命令里有 key。 |+| 当前宿主不在 `完成` 里,`未完成` 里也没提到它 | 安装器没检测到当前宿主。只为它重跑一次,`<值>` 取接入引导附录 A 的 `--harness` 列:`curl -fsSL https://openviking.ai/install \| bash -s -- --yes --harness <值>,cli`。已保存的连接会保留,不用再带 key。然后从步骤 1 继续。 |+| Windows | 安装器只支持 macOS 和 Linux。告诉用户后停止。 |+| docs.openviking.net 打不开 | 换成 docs.openviking.ai,路径不变。安装器本身会自动尝试两个站点。 |+| 找不到 `ov` 命令 | 用 `--yes --harness cli` 重跑安装器,已保存的连接会保留。`ov` 已安装但不在 `PATH` 里时,把 `$(npm prefix -g)/bin` 加进 `PATH`;安装器回退到 `~/.local` 时则是 `~/.local/bin`。 |+| `ov` 提示需要先设置显示语言 | 运行 `ov language zh-CN`(或 `ov language en`)。 |+| DeepSeek Harness:`dsh plugin add` 失败 | 安装 pnpm(`npm i -g pnpm`),再用 `--harness dsh` 重跑安装器。 |+| `安装校验失败`(英文 `Installation validation failed`) | 重跑当前宿主的安装。仍然失败,把失败的检查项告诉用户。 |+| 导入脚本提示 `not supported yet` | 脚本不能直接读这个宿主的历史,按[其他宿主:把会话转成 JSONL](https://docs.openviking.net/agents/zh/onboarding-other-hosts.md)转换后用 `--input` 导入。 |+| 导入脚本提示 `--session: no session matches …` | 给的 id 不对,什么都没有上传。重新运行 `--list`,用它打印的 id。 |+| 重启后没有召回 | 先分清是库里没有相关内容,还是 hook 没运行。Codex 和 TraeCode CLI:在 `/hooks` 里信任 OpenViking 的 hook,在 `/plugins` 里确认 `openviking-memory` 已启用。Cursor 和 TRAE:应用没有完全退出。其他情况运行诊断:Claude Code 用 `/openviking-memory:ov` 或 `ov-memory-doctor` skill;Codex 用 `$ov-memory-doctor` skill;Cursor、TRAE、TRAE CN、ZCode 运行 `node ~/.openviking/agent-integrations/<cursor\|trae\|trae-cn\|zcode>/scripts/ov-memory-doctor.mjs`;pi 用 `/viking`;DeepSeek Harness 运行 `dsh --profile <profile> --dump-config`(`<profile>` 是安装器输出的那个),输出里应包含 `openviking-memory`。命令行宿主还可以在启动前设置 `OPENVIKING_DEBUG=1`,hook 日志会写到 `~/.openviking/logs/`;从程序坞或启动器打开的桌面应用读不到 shell 里设置的环境变量。 |diff --git a/docs/images/agents/zh/onboarding.md b/docs/images/agents/zh/onboarding.mdnew file mode 100644index 000000000..7160b42da--- /dev/null+++ b/docs/images/agents/zh/onboarding.md@@ -0,0 +1,378 @@+# OpenViking 接入引导(给 Agent 看)++关于 OpenViking:面向 AI Agent 的开源上下文数据库,由火山引擎开源,仓库是 https://github.com/volcengine/OpenViking(AGPL-3.0,2026-09-29 时有 38,930 个 GitHub star)。它持续保存并取回用户的业务背景、偏好、重要决定和工作资料,让用户换一个会话或换一个 Agent 后,仍能带着已有积累继续工作。本指南就是这个仓库里的 `docs/images/agents/zh/onboarding.md`;安装器和它安装的每个插件文件也都由这个仓库的 GitHub Actions 构建。++你是一个 AI Agent。用户请你安装 OpenViking 记忆插件,并带他开始使用。这份指南写给你看:它告诉你每一步要让用户明白什么、你自己要做什么、给用户的消息长什么样。措辞由你决定,用用户的语言。用户想看原文时,把链接给他。++另有三页按需查阅:[故障排查](https://docs.openviking.net/agents/zh/onboarding-troubleshooting.md)(命令失败时)、[其他宿主:把会话转成 JSONL](https://docs.openviking.net/agents/zh/onboarding-other-hosts.md)(在 Claude Code、Codex 以外的宿主上导入历史时)、[扩展参考](https://docs.openviking.net/agents/zh/reference/product-background.md)(用户追问机制、权限,或想整理自己的多份资料时)。开始接入前不用读。++## 怎么用这份指南++每个步骤分三段:++- **用户要感受到什么**:这一步结束时,用户心里应该多出来的一个认识。你这一步对他说的话都为它服务。它不是台词,不要照念。+- **你来做**:你自己执行的操作。命令、参数、路径、JSON、退出码、会话 id、账户和角色字段写在这一段里;用户在工具调用里能看到它们,给他的消息里**不用再复述**。失败需要他动手、需要他授权,或者他问起时,照实告诉他。+- **对用户说**:给用户的消息的结构和长度。++## 价值要点++讲价值时从这里取,并尽量换成用户自己的工作来说。各步骤标了该用哪一条。++- **定位**:OpenViking 是 Agent 的外置上下文层。资料、记忆和技能存在用户自己的 OpenViking 空间里,不随某一次会话结束而消失,接入的 Agent 都能读写。+- **V1 少重复交代背景**:每次提问前,插件自动取回相关的背景、偏好和已定的判断,交给 Agent。用户不用每开一个会话就从头讲一遍。+ - 可用的论据(整个接入过程最多用一次,并说明出处):官方 LoCoMo 长对话评测中,Claude Code 接入 OpenViking 后,跨会话历史问答准确率从 57% 提到 80%,输入 token 减少 63%(OpenViking 官方报告,2026-05-29)。+- **V2 过去的工作有据可查**:问「上次做到哪了」「当时为什么这么定」时,能从保存的讨论里找到依据,而不是靠用户回忆。+- **V3 换 Agent,不换上下文**:Codex、Claude Code 等接入同一个账号,用的就是同一份上下文。一个 Agent 额度用完或者想换工具,工作可以接着做。+- **V4 成果能原样拿回来**:自动记忆留下的是从对话里提炼的要点;方案、决定和理由、交付物这类成品,要由 Agent 主动存一份,下次才能直接读原文。++## 给用户的消息怎么写++- **先讲这对他意味着什么,再讲结果,最后最多一个问题。** 第一句是关于他的工作或他能得到什么,不是关于你做了哪些检查。+- **讲价值时说以后会怎样**:「以后你在 Codex 里问……,它会……」。这是在说明产品装好后的作用,不用先验证;只讲[价值要点](#价值要点)里有的,不夸大,也不要把还没发生的事说成已经发生。+- **状态说明只在它改变用户下一步操作时讲。** 例如「重启后才生效」要讲,因为他要去重启;「记忆提取状态尚未验证」这类说明留到收尾统一交代一次,不要每条消息结尾都附一句。+- **用他自己的内容举例。** 能说「你在 Gateway 项目里定下的演示主线」,就不要说「你之前的决定」。+- **一次只问一个决定。** 导入范围、是否正式导入、协作约定各自单独一轮,等他回答后再进入下一步。+- **三处决定都用选项工具问。** 选导入范围(3a)、确认正式导入(3b)、协作约定(步骤 4)这三处,只要宿主有让用户点选答案的工具(见[附录 A](#附录-a各宿主说明)下的「选项工具」),就一定用它问,不要把选项写成文字列表。步骤里标着「**问题(选项工具)**」的地方就是调用点。工具里只放一个问题和两到三个选项,选项标签要短,补充说明放进选项描述,推荐的放第一个、标「(推荐)」。工具自带自由输入,不要再加「其他」。只有工具列表里没有这类工具,或者调用报错时,才用文字列出同样的选项,不要重试。+- **要他看的内容放在他一定看得到的地方。** 问题文字要能单独看懂:把做决定要用的要点(试运行找到了什么、约定的摘要和文件路径)写进问题里,不要只写「按上面的……」。有的宿主(例如 Codex 桌面版)在本轮结束后会把调用工具前后的过程消息折叠起来,只留下最后一条回复和问题卡片。所以读回、约定摘要这些要他读的内容,写在本轮最后一条回复的正文里;选项卡片的问题只放一两句摘要和要他决定的事,不要把读回整段塞进卡片。用 `request_user_input_async` 这类不等回答的工具时,先调用工具,再写最后一条回复。+- 不提本指南的步骤编号,不提当前宿主用不上的步骤,不逐条转述本指南。++## 基本规则++- **不打印、不复述 API key。** 安装器把 key 存进本机的 `~/.openviking/ovcli.conf`(更新时会先备份旧文件),这是连接必需的;除此之外,key 不能出现在规则、项目文件、续接消息或永久命令批准里。不要打开、打印或搜索 `ovcli.conf`。需要服务地址和身份时,运行 `ov health` 或调用 OpenViking 的 `health` 工具。+- **只做本指南描述的改动。** 安装器会给本机检测到的每个受支持的 Agent 都装上插件,这是预期行为。你自己不要改其他 Agent 的配置,也不要改用户项目里的文件,除非用户明确要求。+- **用本指南给出的命令。** 不要去 GitHub 读源码另找安装或配置的方法;参数不确定时看命令的 `--help`。+- **按事实说话。** 读回的内容必须来自 OpenViking 实际返回的结果。没有用户的真实内容时,不要编示例记忆来演示效果。+- 命令失败时,到[故障排查](https://docs.openviking.net/agents/zh/onboarding-troubleshooting.md)找对应现象,修好后重试一次。仍然失败,就告诉用户哪一步没成、影响什么、他可以怎么处理。只有当前宿主的连接或认证失败才阻塞后续步骤,其他宿主装失败不影响当前宿主。++## 从哪一步开始++- **安装器是你在当前对话里运行的**:从步骤 1 开始。+- **用户说「已重启」,而这段对话里已经走过本指南前面的步骤**:用户退出后恢复了原来的会话。直接跳到[重启之后](#重启之后),前面的选择都在对话里,不要重问。+- **新会话里,用户发来一条「从……「重启之后」继续」的消息**:跳到[重启之后](#重启之后),以消息里写的结果为准。+- **用户只说了「已重启」,但这段对话里没有前面的接入过程**(例如 `codex resume --last` 回到了别的会话,或者他开了新会话):同样跳到[重启之后](#重启之后),在第 2 步先问清导入和协作约定做到了哪一步,缺的逐个补上。+- **OpenViking 在这段对话之前就已安装**(能看到 `<openviking-context>` 块,或者有 `health` 等 OpenViking 工具):先用 `ov health` 或 `health` 工具查连接,记下返回的用户名,告诉用户连的是哪个服务、哪个用户,问他沿用还是更换。+ - 沿用:做步骤 2 到 4,然后直接进入[重启之后](#重启之后)。不需要重启。+ - 更换:插件正在保存这段对话,所以不要让用户把新 key 发到这里。请他在自己的终端里运行控制台给的安装命令(或下面那条),再开一个新会话把控制台的一键提示词发给 Agent。旧配置会被备份,云端数据不会被清空。+- **还没有任何连接,用户也没给安装命令**:请用户提供服务地址和 API key(在 OpenViking 控制台的用户管理 → API Key 里),然后运行下面的命令,`<值>` 取[附录 A](#附录-a各宿主说明)的 `--harness` 列,再从步骤 1 开始。`cli` 一定要带上:后面检查连接、读回内容和添加文件都要用 `ov` 命令。++ ```bash+ curl -fsSL https://openviking.ai/install | bash -s -- --yes --lang zh --harness <值>,cli --url <服务地址> --api-key <用户的 key>+ ```++- **用户只想追加导入历史**:只做步骤 3,不重走安装和协作约定。++## 步骤 1:连接结果++**用户要感受到什么**:「我的 OpenViking 连上了;以后在这几个 Agent 里,用的是同一份上下文。」(V3)++**你来做**++阅读安装器的输出,中文和英文两种写法都要认。++- 输出最后有 `未完成` 列表(英文 `Not done`)时,按宿主判断,不要因为前面有 `完成` 就说全部装好了。当前宿主装失败、key 被拒或连不上服务,先按故障排查处理;只有其他宿主失败时,在消息里简单带一句,继续当前宿主。+- `完成`(英文 `Done`)一节按工具列出结果,每个工具有一行 `下一步:`(英文 `Next:`),写着它怎么重启。确认当前宿主在列表里;不在的话,见故障排查的「当前宿主不在 `完成` 里」。+- 然后运行一次 `ov health`:确认连接,并**记下它返回的用户名**。后面写协作约定、添加文件都用这个用户名,不用再查。安装器输出里已经有 `服务检查通过:<url>`(英文 `Server check passed`)时,这一步主要是为了拿到用户名。++**对用户说**++不单独发一条消息。在步骤 2 那条消息的开头用一句话说:已经连上他的 OpenViking,插件装进了哪几个 Agent(用产品名,例如 Codex、Claude Code)。装进了不止一个时,顺带说出好处:以后在这些 Agent 里都能接着同一份上下文工作。++不要说账户名、角色、服务地址和命令名。用户有多个 OpenViking 账号或问起时,再告诉他连的是哪个用户。++## 步骤 2:以后会自动发生什么++**用户要感受到什么**:「以后不用每次重新交代背景,聊过的东西会自己积累下来。」(V1)++**你来做**++- 查[附录 A](#附录-a各宿主说明)里当前宿主的三件事:要不要信任 hook(以及能不能在重启前先信任)、用户在哪里能看到 OpenViking 起作用、重启后回原会话还是开新会话。+- 不用问用户要不要开启自动记忆,安装本身就是他的请求。+- 用户问起怎么在某个项目里关掉时,再告诉他:在该项目里放一个 `.openviking/config.json`,内容为 `{"version": 1, "capture": {"enabled": false}, "recall": {"enabled": false}}`。只告诉他方法,不替他创建。++**对用户说**++接在步骤 1 那句之后,用两三行讲:++1. V1:以后每次提问前,相关的背景会自动带给 Agent;每轮对话也会自动存进他的 OpenViking,慢慢积累成背景。用他当前的项目或请求举一个例子。+2. 在哪里能看到它起作用,用附录 A 里用户能直接看到的样子说,例如「回答下面会多一行 OV-Usage」。+3. 重启后才生效时,说一句「重启之后就开始生效,最后我会告诉你怎么做」。需要信任 hook 的宿主,补一句「最后会请你确认一次 OpenViking 的 hooks」。具体操作留到步骤 5。++这条消息末尾接上 3a 的价值一句,然后用选项工具发出 3a 的问题。这条消息不讲 hook 的事件名、保存和提取的先后、怎么关闭。++## 步骤 3:带入已有工作++**用户要感受到什么**:「过去的讨论能变成有据可查的背景。这次我已经亲眼看到,它从里面找回了我的工作。」(V2)++这一步最多三轮:选范围 → 确认导入 → 读回结果。读回是这一步的重点,导入本身只是手段。++### 3a 选范围++**对用户说**:一句价值,最好说成他的项目:「把之前的讨论带进来,以后问 <项目> 上次做到哪、当时为什么这么定,就有依据」。++**问题(选项工具)**:带入哪些已有工作?++- 当前项目最近 14 天(推荐)+- 指定一类工作或其他项目,描述写「例如『和支付重构有关的讨论』」+- 先不导入,从现在开始积累++其他范围(其他时间段、所有项目)由他在工具的自由输入里写。++**你来做**:他选好之前,不要下载脚本或试运行。导入脚本能直接读 Claude Code 和 Codex 的历史(`--harness claude` 或 `--harness codex`)。在其他宿主上:本机有 `~/.claude/projects` 或 `~/.codex/sessions` 时,可以把那边的历史作为一个选项一并提出;宿主自己的会话先按[其他宿主:把会话转成 JSONL](https://docs.openviking.net/agents/zh/onboarding-other-hosts.md)转换。++### 3b 试运行++**你来做**++选 1 或自定范围:下载脚本并试运行(不会上传任何内容)。把 `<claude|codex>` 换成实际值;自定范围时,`--cwd` 换成那个项目的目录,「所有项目」用 `--all-projects` 代替 `--cwd`,时间改 `--since`(例如 `30d`、`2026-09-01`、`all`)。++```bash+curl -fsSL https://docs.openviking.net/dl/memory-plugin-shared/import-history.mjs -o "${TMPDIR:-/tmp}/ov-import-history.mjs" && node "${TMPDIR:-/tmp}/ov-import-history.mjs" --harness <claude|codex> --cwd "$PWD" --since 14d --max-sessions 20 --dry-run --json+```++选 2:先用 `--list` 列出范围内的会话(每个带 id、时间、消息数、状态,以及第一条和最后一条请求的摘要)。范围按用户的描述定,没说就用当前项目、最近 30 天。按摘要挑出和他描述相符的会话,再用挑中的 id 试运行(多个 id 用逗号隔开;用 `--session` 时不受项目、时间和数量的限制):++```bash+curl -fsSL https://docs.openviking.net/dl/memory-plugin-shared/import-history.mjs -o "${TMPDIR:-/tmp}/ov-import-history.mjs" && node "${TMPDIR:-/tmp}/ov-import-history.mjs" --harness <claude|codex> --cwd "$PWD" --since 30d --max-sessions 50 --list --json+node "${TMPDIR:-/tmp}/ov-import-history.mjs" --harness <claude|codex> --session <id>,<id> --dry-run --json+```++看试运行 JSON:`toImport.sessions` 是要新上传的会话数;`sessions[].state` 为 `imported`(导入过)或 `live`(插件已经保存过)的会话已经在 OpenViking 里。因「仍在活动」而跳过的会话包括当前这段对话。++- **`toImport.sessions` 为 0,但有 `imported` 或 `live` 的会话**:这些内容已经在 OpenViking 里,不用上传,也不用问他确认。直接进入 3c 读回。+- **范围内没有任何会话**:告诉他这个范围里没找到,问他换个范围还是先不导入。+- **有要上传的会话**:按下面的方式请他确认。++**对用户说**(有要上传的会话时):三四行。++- 找到了什么:用摘要说是哪些工作(选 2 时说你挑了哪几个、没挑上的大致是什么),不报 id。+- 多大:几个会话,大约多少字。+- 会传什么:只有他和 Agent 说的文字;工具调用和输出、文件原件不包括,已知格式的密钥会被替换掉。++**问题(选项工具)**:照这个范围导入吗?选项:导入(推荐)/先不导入。想调整范围,他在自由输入里说。++### 3c 导入并读回++**你来做**++零新增时跳过导入,直接读回。用户确认后,用**完全相同的范围参数**,把 `--dry-run` 换成 `--yes --wait` 正式导入(`--wait` 最多等两分钟的记忆提取):++```bash+node "${TMPDIR:-/tmp}/ov-import-history.mjs" --harness <claude|codex> --cwd "$PWD" --since 14d --max-sessions 20 --yes --wait --json+```++看 JSON 里每个会话的 `extraction`,不要只看退出码。++然后**读回**。只要有会话进了 OpenViking(这次导入的、之前就导入过的、插件已经保存的),都要读回。`--wait` 返回时,`extraction` 为 `completed` 的会话已经提取成记忆,所以读回读的是记忆,不是会话本身。插件要重启后才在这段对话里加载,所以这里用 `ov` 命令:++1. 在他的整个用户目录下检索记忆,查询词用他描述的工作或项目名。导入提取出的记忆分在两处:`viking://user/<user_id>/memories/`(跨项目的实体、事件、偏好)和 `viking://user/<user_id>/peers/<项目>/memories/`(这个项目的实体、事件、偏好;`<项目>` 是导入 JSON 里的 `projectPeer`)。以用户目录为范围检索一次,两处都会覆盖到:++ ```bash+ ov find "<他描述的工作或项目名>" -u viking://user/<user_id> --context-type memory -n 10+ ```++ 只想看这次导入新提取的记忆时,加上 `--after`,取导入开始前的时间,例如 `--after 30m`。++2. 从结果里挑两三条最相关的,重点看上面两处 `memories/` 下的实体(`entities/`)和事件(`events/`)记忆,用 `ov read` 读全文。实体记忆讲这项工作或这个对象是什么、现在什么状态;事件记忆有摘要,也带着当时的对话原文:++ ```bash+ ov read <记忆的 URI>+ ```++3. 只有两种情况读导入的原对话:他想看当时的原话,或者没有提取出记忆(`extraction` 不是 `completed`,或者第 1 步什么都没查到)。会话 id 用导入 JSON 里的 `id`;导入只提交一次,归档就是 `archive_001`。插件保存的 `live` 会话不用读原对话,以第 1 步的结果为准:++ ```bash+ ov session get-session-archive <会话 id> archive_001+ ```++4. 从读到的内容里整理四件事:这项工作要做成什么、上次做到哪、定过的一个判断和理由、还没解决的事。找不到的项就不写,不要补。另外记下一个**缺口**:讨论里提到、但原文不在 OpenViking 里的成品,例如方案文档、脚本、报告。步骤 4 会用到它。++| 导入结果 | 第一句怎么说 | 读回 |+|---|---|---|+| 有写入,`extraction` 为 `completed` | 导入了哪几项工作,记忆已经整理好 | 读记忆:`ov find`,再 `ov read` 一两条 |+| 有写入,提取还在进行(`pending`、`running`)或没有结果 | 讨论已经存进去了,记忆还在后台整理,几分钟后就能被自动取回 | 读原对话(`get-session-archive`),并说明「这是从原对话里读到的」 |+| `failed` | 讨论已保存,但记忆整理失败了,之后可以重试 | 读原对话 |+| 零新增:都已导入过或插件已保存 | 这些讨论之前就已经在他的 OpenViking 里,这次不用重复上传 | 读记忆(不加 `--after`) |+| 部分失败 | 哪些成功、哪些失败,失败的之后可以重试,不要全部重传 | 读成功的部分 |+| 没有匹配,或用户选了不导入 | 以后从他的真实工作开始积累 | 不读,直接进入步骤 4 |++用户问起脚本做了什么时:它只读本机的会话文件(Claude Code 在 `~/.claude/projects/`,Codex 在 `~/.codex/sessions/`),只保留用户和助手的文字,清洗已知格式的密钥,跳过近期仍在活动的会话,并沿用插件的项目归属,所以导入的历史和以后的对话在同一个项目下。试运行和 `--list` 只从服务端读,用来找出已经导入过的会话。++**对用户说**++1. 第一句:上表「第一句怎么说」。不报消息数、字数、`extraction` 这类状态名。+2. 读回,两到四条,用他的原话和名词:在做什么、上次做到哪、定过什么(连同理由)、还差什么。有多项工作时每项一行,不展开。读回写在这条消息的正文里;下一步的选项卡片只用一句话提到它。+3. 一句价值(V2 + V3):「以后在任何接入的 Agent 里问『<工作> 做到哪了』,都能从这里接上。」++这条消息不问要不要开始做这项工作,也不列状态清单。接着在同一条消息里进入步骤 4 的桥接。++### 文件++用户点名了值得保存的文件或文件夹(例如设计文档、需求说明)时,逐个添加到他个人资源里这个项目的目录下,作为其中的一项(不要把项目目录本身作为导入目标)。`<user_id>` 用步骤 1 记下的用户名,`<项目名>` 用仓库名或他对这个项目的叫法:++```bash+ov add-resource ./docs/design.md --parent-auto-create viking://user/<user_id>/resources/<项目名> --wait+```++只添加他点名的内容,不要自己扫描目录或主动上传。添加后告诉他存好了、以后怎么找(「说『按 <文件> 继续』就行」),不报 URI。++## 步骤 4:约定以后怎么协作++**用户要感受到什么**:「接下来我和 <Agent> 约好怎么用 OpenViking 留存和找回工作上下文,之后它会一直按这个约定做;约定由我定,也可以按我的角色来定。」(V4)++**你来做**++1. 找当前宿主实际读取的用户级规则文件([附录 A](#附录-a各宿主说明)「用户级规则文件」一列是常见位置,以宿主实际读取的为准),看里面有没有 `<!-- openviking:start -->` 标记块。+ - 已有,内容和下面相同:不用问,在消息里带一句「之前已经约定过」,直接进入步骤 5。+ - 已有,内容不同:准备一句话说清新版和旧版差在哪。已有块里的用户名和这次记下的不同(他换了账号),也算内容不同。+ - 没有:准备下面的原文。+2. 准备约定原文。默认用下面这段;用户调整了,或按角色加了内容,就按他的选择改。把 `<user_id>` 直接换成步骤 1 记下的用户名,写入前不用再查;`<项目名>` 保持原样,它在每个项目里各自确定。+3. 用户同意后写入:+ - 只动标记块之间的内容。已有标记块就替换中间部分,没有就追加到文件末尾,文件不存在就新建。块外的内容保持原样。+ - 文件里已有和这段约定冲突的要求(例如每轮都必须检索,或者不许把资料存到外部),先告诉他冲突在哪,按他的决定改。+ - 写完读回,确认写进去的就是他同意的版本、标记块只有一份、块外内容没变。+ - 宿主的个人规则只能在应用设置里改,或者写入失败时,把原文给他,请他自己粘贴进去。不确定是哪个文件时,问他,不要猜。+ - 不要写进项目文件。++默认的约定原文:++```markdown+<!-- openviking:start -->+## OpenViking 协作方式++- 开始需要背景的工作前,先用 OpenViking 自动带进来的上下文;不够时再用 OpenViking 的 `search`(`mode="context"`)查,需要原文时用 `read`。查到的内容是参考,和我现在说的冲突时以我为准。+- 工作中出现重要决定(连同理由)、阶段进展和下一步,以及方案、调研、交付物等工作产出时,主动存进 OpenViking,作为以后可以持续更新、参考的工作依据;新的决定推翻了旧的,就更新原来的记录。工作产出不管是写在对话里的,还是你写进本地文件的,都存一份。+- 日常对话不用另存,插件会自动保存;密钥不存;和这次工作无关、我也没提到的文件,不主动扫描或上传。+- 继续一个项目时,先看这个项目之前存下的进展、决定和产物。+- 这一轮用到了 OpenViking 里的有效信息,或者存了东西,在回复末尾用一句话告诉我:用了什么、存在哪。没用到就不说。++### 存放方式++- 我的工作内容放在 `viking://user/<user_id>/resources/` 下,每个项目一个子目录:`<项目名>` 用仓库名或我对这项工作的叫法,已有对应目录就沿用。+- 项目目录下用 `notes/` 记录进展、决定和下一步;方案、调研、交付物等工作产出直接存在项目目录里,需要时再建子目录。文本内容用 `write` 存,内容改了就覆盖原来那份;PDF、PPT、图片这类文件用 `add_resource` 加到项目目录下。写完用 `read` 读回确认。+- 我给的文件也用 `add_resource` 加到项目目录下,作为其中的一项;不要把项目目录本身作为导入目标,也不要往导入进来的资料里写东西:导入的资料重新同步时,会删掉源文件里没有的内容。+<!-- openviking:end -->+```++**按角色调整时的参考**。用户说了角色,就从这里取两三项,换成他的说法,作为原文第二条之后新增的一条「按我的角色(<角色>),还要主动保存:……」。表里没有的角色,按同样的思路推。++| 角色 | 建议额外保存 | 继续工作时先看 |+|---|---|---|+| 产品经理 | 需求决策和取舍理由、用户反馈的结论、PRD 和方案的版本 | 需求当前状态、待评审事项 |+| 研发 | 技术方案和取舍、接口约定、排障结论和复现方式 | 进行中的改动、没解决的问题 |+| 市场 | 定位和关键信息、活动方案和复盘、对外口径和文案版本 | 活动进度、已定口径 |+| 设计 | 交互和视觉决策、评审意见、设计稿的版本说明 | 待改的评审意见 |++**对用户说**++这一轮既要让他看懂约定的效果,也要让他能核对要写入的原文:先给摘要,再附原文,都放在你这一轮最后一条回复的正文里(不要只放在过程消息里)。原文默认就给,不要等他要了才给。++消息(接在步骤 3 的读回之后):++1. **桥接一句**,用步骤 3 记下的缺口:「会话里有讨论,但 <成品> 的原文不在里面。」没有读回时省略。+2. **说明这一步在做什么**:接下来和 <当前 Agent 的名字> 约定怎么用 OpenViking 留存和找回工作上下文;约定写进 <规则文件的完整路径>,对他所有项目生效,之后每次工作都会按它来,随时可以改。+3. **我们建议的方式**,三条,用他的语言,不讲存放位置、目录和工具名:+ - 开始工作前,先从 OpenViking 找回相关的背景;+ - 工作中出现重要决定(连同理由)、阶段进展和下一步,以及方案、调研、交付物等产出时,主动存进 OpenViking,作为以后可以持续更新、参考的工作依据;+ - 每次用到了 OpenViking 里的有效信息,在回复末尾简短告诉他。+4. **要写入的原文**:紧接摘要,先说一句「下面是会写进 <规则文件的完整路径> 的原文:」,再用代码块给出完整原文(`<user_id>` 已换成他的用户名)。++**问题(选项工具)**:问题文字要能单独看懂,写出摘要要点和文件路径,例如「以后按这个方式协作吗?开始工作前先找回背景,重要决定、进展和方案、调研等产出主动存进 OpenViking,用到时简短告诉你。写入 <规则文件路径>,对所有项目生效。」选项:++- 按这个方式约定(推荐)+- 按我的角色调整,描述写「告诉我你的角色,例如市场、产品、研发,我建议保存哪些内容」+- 只用自动记忆++在问题或描述里提一句:想改原文的哪里,可以在自由输入里直接说。++接下来:++- **按这个方式约定**:写入。+- **按我的角色调整**:问他的角色(用文字问一句即可)。按上面的参考给出调整后的效果,三四条,标出新增的是哪几条,并附上调整后的原文,再用选项工具问:按这个写入(推荐)/再调整/只用自动记忆。+- **直接说了要改的地方**:按他的意思改原文,给出改后的效果和改后的原文,再问一次。+- **只用自动记忆**:不写文件。告诉他仍然可以随时让你保存或读取资料。++摘要必须如实对应要写入的原文:原文里摘要没提的部分,只能是摘要所述行为的实现细节(例如存放方式)。++他问「存在哪」时再解释:他的 OpenViking 个人空间里,每个项目一个目录;进展和决定记在项目的 notes 里;方案、调研、交付物(不管是你产出的还是他上传的)也放在这个项目目录下。等他回答之后再进入步骤 5,不要在问这个问题的同一条消息里提重启。++## 步骤 5:重启++**用户要感受到什么**:「再做一步就能用上了,回来后直接接着我的工作。」++**你来做**++- 当前宿主已经生效、本次也没有新装插件时,跳过这一步,直接进入[重启之后](#重启之后)。+- 查[附录 A](#附录-a各宿主说明)当前宿主的「重启或信任」和「重启后」两列,以及安装器输出里其他工具的 `下一步:`(英文 `Next:`)。+- 准备续接消息。网址用你实际打开成功的那个;本指南是本地文件时,用它的绝对路径。尖括号换成实际结果:++```text+已重启。从 https://docs.openviking.net/agents/zh/onboarding.md 的「重启之后」继续 OpenViking 接入。历史导入:<例如「导入了 2 个会话」「已在 OpenViking 里」「已跳过」>;协作约定:<已写入 / 未写>;接下来想做:<他说过的目标,没说就写「先看看 <工作> 上次做到哪」>。+```++**对用户说**++1. 现状,用肯定的说法:连上了、带进了哪项工作。协作约定写了的话,把那三条摘要再列一遍,带上规则文件的路径,告诉他以后想看或想改,打开这个文件或直接让你改;没写就说没写。+2. **需要信任 hook 的宿主(Codex、TraeCode CLI 2.0),请他在退出前先信任**:Codex 桌面版点输入框下方的 hooks 图标,Codex CLI 和 TraeCode CLI 在会话里输入 `/hooks`,信任 OpenViking 的全部 hooks。说一句好处:这样重启后不会再停在审阅提示上,回来就能接着工作。附录 A 里写了信任后要告诉用户的事(Codex 会保存这段安装对话,包括 key),一并用一句话说清。重启后如果还是出现「Hooks need review」,照旧选 **Trust all and continue**。+3. 当前宿主怎么重启。+4. 安装器还装进了其他 Agent 时,加一行点出名字:各自重启后生效,具体看安装器输出里的「下一步」。+5. 回来之后做什么:+ - 「重启后」一列写着回到原会话的宿主:告诉他用表里的命令回到**这段对话**,然后发一句「已重启」。续接消息也给他,作为备用:回到的不是这段对话时,在新会话里发它。+ - 写着开新会话的宿主:告诉他开一个新会话,不要恢复这段对话,也不要在这里重新加载插件,并给他续接消息。+6. 一句预告:「回来后我会先告诉你 <工作> 上次做到哪,再给你几个接下来的方向。」没带入工作时说:「回来后直接告诉我你要做的事。」++说完就停下,等用户操作。++## 重启之后++**用户要感受到什么**:「它真的接上了:我没交代背景,它就知道我在做什么。」(V1、V2)++**你来做**++1. **确认插件在运行。** 当前对话里有 `<openviking-context>` 块,或者 OpenViking 工具可用。调用 `health` 工具(名字可能带前缀,例如 `mcp__openviking__health`、`openviking_health`)。都没有时,见故障排查的「重启后没有召回」。有注入块才说明自动召回在运行;没有相关记忆,可能只是库里还没有相关内容。+2. **补上缺的选择。** 从这段对话或续接消息里确认导入和协作约定是否已经做完。缺了就补做那一步,做过的不要重问。+3. **取回背景。** 先用注入的上下文;不够再用 `search`(`mode="context"`)查,必要时 `read` 原文。记忆还在整理时,可以读导入的原对话,但要说明这是读的原记录。++**对用户说**++按他想要的结果选一种:++| 他想要的 | 消息内容 |+|---|---|+| 接着过去的工作做 | 这项工作要做成什么、上次做到哪、定过哪些判断、还有什么没解决;再给两三个具体的推进方向。点出其中一条依据是从 OpenViking 取回的、它怎么影响了你的建议(V1)。有多项工作时先让他挑一项。 |+| 保存或复用一份资料 | 按他点名的文件添加后读回,或者读已有的资料回答他一个真实的问题;告诉他以后怎么找回。 |+| 从现在开始,或者暂时不体验 | 一句以后会怎么积累,请他直接开始一件真实的工作,或者稍后再用。 |++给出总结和方向后,等他选,不要直接动手改代码或推进任务。++**收尾**,最多三行,接在他选完方向之后或这条消息末尾:++- 已经在起作用的,以及还在后台进行的(例如记忆整理)。还没确认的状态在这里统一说一次。+- 在这个宿主上哪里能看到 OpenViking 的作用(附录 A 的「在哪里能看到」)。+- 以后可以说的话,挑一两条和他相关的:「把 <项目> 的会话导入 OpenViking」「保存这份文档,之后按它继续」「换一个 OpenViking 账号」(按[从哪一步开始](#从哪一步开始)里「更换」的做法处理)。装进了其他 Agent 时提一句:在那边接着这项工作,背景还在(V3)。++## 附录 A:各宿主说明++| 宿主 | `--harness` | 重启或信任 | 重启后 | 在哪里能看到 | 历史导入 | 用户级规则文件 |+|---|---|---|---|---|---|---|+| Claude Code | `claude` | 退出后重新运行 `claude`;不要用 `/reload-plugins` | 开新会话。不要用 `claude --continue` / `--resume` 回到安装对话:插件会把整段安装对话连同里面的 key 补存到 OpenViking | 用到 OpenViking 的回答下方有来源卡片(Claude Code 2.1.286 及以上);`/openviking-memory:ov` 查看状态 | 支持 | `~/.claude/CLAUDE.md` |+| Codex | `codex` | **退出前先信任 hooks**:桌面版点输入框下方的 hooks 图标,CLI 在会话里输入 `/hooks`,信任 OpenViking 的全部 hooks;信任记录存在 `~/.codex/config.toml`,重启后不会再提示。然后退出:CLI 运行 `codex resume --last` 回到这段对话;桌面版退出后重新打开,回到这段对话。重启后如果仍出现「Hooks need review」,选 **Trust all and continue**。要告诉用户:信任之后,这段安装对话会保存到他自己的 OpenViking 账号里,包括安装命令里的 API key 和导入时列出的会话摘要,回到原会话或开新会话都一样;介意的话,之后在控制台换一个新 key | 回到原会话(就是左边那条命令),发「已重启」 | 回答后有一行 OV-Usage,例如 `OpenViking · 3 sources · 1 past event · 2 team docs · 1 read` | 支持 | `~/.codex/AGENTS.md`;同目录有 `AGENTS.override.md` 时 Codex 读的是它 |+| TraeCode CLI 2.0 | `trae-cli` | **退出前先信任 hooks**:在会话里输入 `/hooks`,信任 OpenViking 的全部 hooks。然后退出,重新运行 `trae-cli`(或 `traecli`);仍出现「Hooks need review」时选 **Trust all and continue** | 开新会话 | 回答后有一行 OV-Usage,与 Codex 相同 | 转成 JSONL;会话在 `~/.trae/cli/sessions/`,和 Codex 相同的 rollout 格式 | 未确认 |+| Cursor | `cursor` | 完全退出 Cursor 后重新打开 | 开新会话(**+**),不要在恢复出来的安装对话里继续 | 设置 → Hooks 里的 OpenViking hook;设置 → Tools & MCPs 里 `openviking` 显示已连接 | 转成 JSONL;会话位置未确认 | Cursor 设置里的 User Rules,请用户粘贴 |+| TRAE / TRAE CN | `trae` / `trae-cn` | 完全退出应用后重新打开;无需批准 hook | 开新会话 | MCP 设置里 `openviking` 显示已连接 | 转成 JSONL;会话位置未确认 | 应用设置里的个人规则,请用户粘贴 |+| ZCode | `zcode` | 重启 ZCode | 开新会话 | 无文档说明 | 转成 JSONL;会话位置未确认 | 应用设置里的个人规则,请用户粘贴 |+| Kimi Code | `kimicode` | 退出 Kimi Code;不要用 `/reload` | 开新会话,不要恢复当前会话 | 无文档说明 | 转成 JSONL;会话在 `~/.kimi-code/sessions/`(设置了 `$KIMI_CODE_HOME` 时在该目录下) | `~/.kimi-code/AGENTS.md`(同上) |+| OpenCode | `opencode` | 重启 OpenCode | 开新会话 | 无文档说明 | 转成 JSONL;会话在 SQLite 库 `~/.local/share/opencode/opencode.db` | `~/.config/opencode/AGENTS.md` |+| pi | `pi` | 重启 pi | 开新会话 | 底栏显示 `OV ✓`;`/viking` 查看状态 | 转成 JSONL;会话在 `~/.pi/agent/sessions/*/*.jsonl` | `~/.pi/agent/AGENTS.md` |+| DeepSeek Harness | `dsh` | 用安装器输出中 `DeepSeek Harness profile:` 那一行的 profile 新开会话:`dsh --profile <profile>` | 开新会话 | 会话顶部显示「上下文注入 · openviking-memory」 | 转成 JSONL;会话在 `~/.dsh/sessions/` | 未确认 |++- **Codex 的审批。** Codex 运行需要联网的命令前会请求批准,包括这里读回用的 `ov find`、`ov read` 和 `ov session`。运行带 key 的安装命令时选 **Yes, proceed**,不要选「以后以这个前缀开头的命令不再询问」,那条规则会把 key 存下来。OpenViking 的 `search` 工具第一次运行时,Codex 会请求允许,选 **Always allow** 即可。Hooks 信任和命令批准是两件事。+- **选项工具。**+ - Claude Code:`AskUserQuestion`。+ - Codex:有两个,工具列表里有哪个用哪个,优先 `request_user_input_async`。+ - `request_user_input_async`:gpt-6 系列等模型在 Default 模式下也有(例如 Codex 桌面版 0.164)。它把问题作为一张选项卡片发出、不等回答,用户的选择会作为下一条消息回来。Codex 桌面版会在本轮结束后折叠过程消息,所以调用它之后,把要他读的内容写进本轮最后一条回复。+ - `request_user_input`:只在 Plan 模式下可用(用户开了 `default_mode_request_user_input` 时 Default 模式也能用),否则调用会返回 `request_user_input is unavailable in Default mode`。+ - Codex 的 Default 模式指令也要求不要把多选题写成文字消息。两个都不可用时才用文字问。+ - 这些工具都会自动加一个「Other」让用户自己输入,不要在选项里再放「其他」。其他宿主有同类工具就用,没有就用文字。+- **无文档说明。** 在这些宿主上,用户可以直接问你收到了哪些 OpenViking 上下文,也可以运行故障排查里的诊断。++各宿主的详细说明:https://docs.openviking.net/zh/agent-integrations/01-overviewdiff --git a/docs/images/agents/zh/opencode.md b/docs/images/agents/zh/opencode.mdindex c6499b862..0a58354d1 100644--- a/docs/images/agents/zh/opencode.md+++ b/docs/images/agents/zh/opencode.md@@ -19,6 +19,16 @@2. 输入 `/mcps` 命令,确认列表中显示 `openviking connected`。3. 在对话中明确要求调用 `openviking_search` 和 `openviking_read`,验证工具可用。自动召回由 hook 完成,不需要模型调用这些工具;可另开会话,询问已保存的信息来检查。+## 步骤3:开始使用++在 OpenCode 中新开一个会话,发送:++```text+按 https://docs.openviking.net/agents/zh/onboarding.md 带我完成 OpenViking 首次使用。+```++Agent 会检查连接,并带你完成首次使用。+## 故障排查| 问题 | 处理 |diff --git a/docs/images/agents/zh/pi.md b/docs/images/agents/zh/pi.mdindex 351912fc4..7950e1095 100644--- a/docs/images/agents/zh/pi.md+++ b/docs/images/agents/zh/pi.md@@ -19,6 +19,16 @@2. 输入 `/viking` 命令,确认显示当前 session 映射和已注册的 `openviking_*` 工具数量。3. 新开会话,询问之前提到过的信息,确认召回生效。+## 步骤3:开始使用++在 pi 中新开一个会话,发送:++```text+按 https://docs.openviking.net/agents/zh/onboarding.md 带我完成 OpenViking 首次使用。+```++Agent 会检查连接,并带你完成首次使用。+## 故障排查| 问题 | 处理 |diff --git a/docs/images/agents/zh/reference/product-background.md b/docs/images/agents/zh/reference/product-background.mdnew file mode 100644index 000000000..acf900efb--- /dev/null+++ b/docs/images/agents/zh/reference/product-background.md@@ -0,0 +1,42 @@+# OpenViking 扩展参考++[接入引导](https://docs.openviking.net/agents/zh/onboarding.md)已包含普通接入需要的解释。本文件用于回答用户追问或处理扩展目标,无需在开始接入时通读;只查与当前问题有关的部分。知识不代表当前工具一定支持,也不授予执行额外任务的许可。++## 内容类型与处理状态++- 会话保留支持范围内的交互过程;记录存在不证明包含最新消息。+- 记忆由服务按策略从已提交的会话提取、更新,例如偏好、事项和经验。记忆可能遗漏或过时,当前用户要求优先。+- 资料保存需求、方案、报告等可读取正文;聊天提到文件不等于原件上传,正文入库也不证明所有附件已备份。+- 技能提供可复用的操作方法;保存经验不会自动生成或安装技能。++消息写入、提交提取、提取完成、检索命中、实际采用是不同状态。确认状态要检查对应结果;不能从文件存在推断提取完成,从来源计数推断答案使用过。++## Hooks、规则与资源消耗++Hooks 是宿主在会话事件发生时运行插件的机制,用于载入背景、召回、捕获或触发提交。具体事件、信任要求、发送范围和提交时机以安装版本为准。客户端不使用 Hooks 时,以其实际插件机制说明,不要求用户寻找不存在的审批入口。++长期规则指导 Agent 何时补查原文、主动保存哪些内容以及怎样反馈;不创建后台文件监控器,也不保证每轮一定正确执行。已有自动注入足够时不强制追加查询,普通对话已捕获时不再手动保存一遍。++检索、注入和整理可能消耗上下文与模型调用。按任务相关性取回背景,需要细节时才读原文;不能承诺固定节省比例。与宿主原生记忆是否重叠,要核对各自作用范围,不能笼统宣称替代。++## 目录与分层读取++OpenViking 通过目录和 URI 保留内容归属与来源。L0 摘要帮助识别主题,L1 概览帮助理解内容,L2 原文供细节核对;按问题选择粒度,不默认加载全部历史,也不要求用户先学这些术语。++接续工作先用注入的上下文和相关记忆、笔记,需要细节再读会话原文;跨多个会话时结合日期、范围和原记录核对,不能把最新一个会话当成整个项目。已完成事项不重新打开,历史方案不当作当前上线事实,摘要冲突时回查原文。++## 跨 Agent 与身份++另一会话或 Agent 接入同一身份可访问的内容后,可以用已有背景接续工作。它不实时复制整个聊天窗口、设备状态、客户端规则或未上传附件;最近尚未提交或处理的内容也可能缺失。++只检查用户选定两端的身份与内容可用性,不为解释主动安装第二个客户端。验证要由独立上下文实际取回背景;原聊天读取成功不等于跨 Agent 验证成功。++同一地址不等于同一用户。绑定或切换身份不自动搬运旧资料;需重新对齐读写范围,保留原配置。没有实际绑定或切换能力时说明限制,不编造命令。++## 偏好、经验与知识整理++偏好帮助协作符合稳定的表达和判断方式;仅在当前工作适用时采用,不把一次选择固化为永久偏好,不为展示效果收集无关个人信息。++经验保留有效做法、纠正和适用条件。说明它为什么适合当前任务,避免机械照搬;是否启用提取、是否可检索需核对,不能承诺每轮自动产生经验。++知识整理/Compile 适合基于多份材料形成有来源的主题知识或 Wiki,通过 `ov` 命令行的 `ov compile` 执行(安装器的 `cli` 一项装的就是 `ov`),由服务端的 Compile Runtime 运行,结果写回 OpenViking。先检查服务是否支持、来源范围和输出位置,再按用户授权执行;用法见 https://docs.openviking.net/zh/context-compilation/01-overview 。安装插件、导入历史或生成普通摘要都不等于已执行 Compile。diff --git a/docs/images/agents/zh/trae.md b/docs/images/agents/zh/trae.mdindex 7db9e23a7..49ccd78ce 100644--- a/docs/images/agents/zh/trae.md+++ b/docs/images/agents/zh/trae.md@@ -33,6 +33,16 @@ Hooks can run outside the sandbox after you trust them.MCP 条目可见只说明配置存在。让助手调用 OpenViking 的 `health` 和 `list` 验证连接;自动召回需另行检查:等之前的会话提交并处理完成后,在同一工作目录中新建会话,询问已保存的信息。+## 步骤3:开始使用++在 TRAE、TRAE CN 或 TraeCode CLI 2.0 中新开一个会话,发送:++```text+按 https://docs.openviking.net/agents/zh/onboarding.md 带我完成 OpenViking 首次使用。+```++Agent 会检查连接,并带你完成首次使用。+## 故障排查| 问题 | 处理 |diff --git a/docs/images/agents/zh/zcode.md b/docs/images/agents/zh/zcode.mdindex 94575c18e..7cbef832f 100644--- a/docs/images/agents/zh/zcode.md+++ b/docs/images/agents/zh/zcode.md@@ -19,6 +19,16 @@2. 确认 `~/.zcode/cli/config.json` 包含 `hooks.enabled: true`、`hooks.events` 下的 OpenViking 条目,以及 `mcp.servers.openviking`。3. 运行 `node ~/.openviking/agent-integrations/zcode/scripts/ov-memory-doctor.mjs`,检查安装状态和服务端连接。+## 步骤3:开始使用++在 ZCode 中新开一个会话,发送:++```text+按 https://docs.openviking.net/agents/zh/onboarding.md 带我完成 OpenViking 首次使用。+```++Agent 会检查连接,并带你完成首次使用。+## 故障排查| 问题 | 处理 |diff --git a/docs/repository/README_CN.md b/docs/repository/README_CN.mdindex 333bae8e7..8005baa74 100644--- a/docs/repository/README_CN.md+++ b/docs/repository/README_CN.md@@ -192,21 +192,17 @@ ov grep "openviking" --uri viking://resources/volcengine/OpenViking/docs/zh<summary><strong>让 agent 帮你安装</strong></summary>```text-帮我安装 OpenViking 记忆插件,运行:+帮我安装 OpenViking 记忆插件,并带我开始使用。OpenViking 是火山引擎开源的 Agent 上下文数据库(https://github.com/volcengine/OpenViking,AGPL-3.0),下面的命令和链接来自它的官方文档。-curl -fsSL https://openviking.ai/install | bash -s -- --yes --url <SERVER_URL>+1. 运行官方安装器。它需要联网并写入我的主目录,如果被你的沙箱拦住,请向我申请批准:+ curl -fsSL https://openviking.ai/install | bash -s -- --yes --lang zh --url <SERVER_URL> --api-key <API_KEY>+2. 装好后读 OpenViking 的接入引导,按它带我完成设置。导入历史、写协作规则这类选择,引导会让你先问我。docs.openviking.net 和 docs.openviking.ai 是同一个文档站,哪个打得开用哪个:+ https://docs.openviking.net/agents/zh/onboarding.md-<SERVER_URL> 是我的 OpenViking 服务地址,向我要,不要猜。服务开了鉴权的话,-要一个 user key(root key 读写不了记忆):先看看有没有已保存的,没有再向我要-(用 --api-key 传入),并告诉我不想把 key 贴进对话时可以怎么给你。-不要复述 key。没开鉴权就加 --api-key '',免得沿用之前保存的 key。--脚本需要联网并写入主目录,如果被沙箱拦住,请求我批准后在沙箱外运行。--装完告诉我装进了哪些工具、各自的后续步骤,再问我要不要给其他工具也装。+API key 是我在这个服务上给自己生成的 user key,安装器会把它存到本机的 ~/.openviking/ovcli.conf。命令里原样使用就行,回复里不用再显示它,也不要写进别的文件或规则。全程用中文和我交流。```-准备好服务地址;服务开了鉴权的话,还要它的 API key。+发送前把 `<SERVER_URL>` 换成你的服务地址,把 `<API_KEY>` 换成 user key,root key 读写不了记忆。服务没开鉴权的话,传 `--api-key ''`。</details>diff --git a/docs/repository/README_JA.md b/docs/repository/README_JA.mdindex 8144b2a72..b85f45cb1 100644--- a/docs/repository/README_JA.md+++ b/docs/repository/README_JA.md@@ -191,27 +191,17 @@ ov grep "openviking" --uri viking://resources/volcengine/OpenViking/docs/en<summary><strong>エージェントにインストールしてもらう</strong></summary>```text-OpenViking メモリプラグインをインストールすること。次を実行する:+OpenViking メモリプラグインをインストールして、使い始めるところまで手伝ってください。OpenViking は Volcengine がオープンソースで公開している AI エージェント向けのコンテキストデータベースです(https://github.com/volcengine/OpenViking、AGPL-3.0)。下のコマンドとリンクは公式ドキュメントに載っているものです。-curl -fsSL https://openviking.ai/install | bash -s -- --yes --url <SERVER_URL>+1. 公式インストーラーを実行してください。ネットワークに接続し、私のホームディレクトリに書き込みます。サンドボックスでブロックされたら、私に承認を求めてください:+ curl -fsSL https://openviking.ai/install | bash -s -- --yes --lang en --url <SERVER_URL> --api-key <API_KEY>+2. インストールが終わったら OpenViking のオンボーディングガイドを読み、それに沿って私のセットアップを進めてください。履歴のインポートや作業ルールの追加といった選択の前には、ガイドに従って私に確認することになっています。docs.openviking.ai と docs.openviking.net は同じドキュメントサイトなので、開けるほうを使ってください:+ https://docs.openviking.ai/agents/en/onboarding.md-<SERVER_URL> は私の OpenViking サーバーのアドレス。-推測せずに私に確認すること。サーバーで認証が有効なら user key が必要-(root key ではメモリを読み書きできない):保存済みのキーがあるか確認し、-なければ私に求めて --api-key で渡すこと。-このチャットに貼りたくない場合の渡し方も伝えること。キーは復唱しないこと。-認証が無効なら --api-key '' を付け、以前保存したキーを使い回さないこと。--スクリプトはネットワークに接続し、ホームディレクトリに書き込む。-サンドボックスでブロックされたら、-サンドボックスの外で実行する許可を私に求めること。--完了したら、どのツールにインストールしたかと、-それぞれの次の手順を伝えること。そのうえで、-ほかのツールにも入れるか私に確認すること。+API キーは、私がそのサーバーで自分用に作成した user key です。インストーラーがこのマシンの ~/.openviking/ovcli.conf に保存します。コマンドではそのまま使ってください。返信の中で表示する必要はありません。ほかのファイルやルールにも書き込まないでください。やり取りは日本語でお願いします。```-サーバーのアドレスを用意しておいてください。認証が有効なら API キーも必要です。+送信する前に、`<SERVER_URL>` をサーバーのアドレスに、`<API_KEY>` を user key に置き換えてください。root key ではメモリを読み書きできません。サーバーで認証が無効なら `--api-key ''` を使ってください。</details>diff --git a/docs/zh/agent-integrations/02-claude-code.md b/docs/zh/agent-integrations/02-claude-code.mdindex 5743c4236..74c303d0e 100644--- a/docs/zh/agent-integrations/02-claude-code.md+++ b/docs/zh/agent-integrations/02-claude-code.md@@ -45,6 +45,8 @@ curl -fsSL https://openviking.ai/install | bash</details>+安装完成后,在 Claude Code 中新开一个会话,让它按 https://docs.openviking.net/agents/zh/onboarding.md 执行。它会检查连接,并带你完成首次使用,详见[一条提示词接入 Agent](../getting-started/07-agent-onboarding.md)。+## 验证启动 `claude`,随后:diff --git a/docs/zh/agent-integrations/04-codex.md b/docs/zh/agent-integrations/04-codex.mdindex b9d568536..6c20f04cb 100644--- a/docs/zh/agent-integrations/04-codex.md+++ b/docs/zh/agent-integrations/04-codex.md@@ -57,6 +57,8 @@ Hook 关闭时,MCP 工具仍可能正常使用。自动召回需要 `UserPromp</details>+安装完成后,在 Codex 中新开一个会话,让它按 https://docs.openviking.net/agents/zh/onboarding.md 执行。它会检查连接,并带你完成首次使用,详见[一条提示词接入 Agent](../getting-started/07-agent-onboarding.md)。+## 验证启动 `codex` 后,当前会话首次提交 prompt 时触发的 `SessionStart` 会加载 profile,之后插件将在每次用户输入前自动召回相关记忆。若设置环境变量 `OPENVIKING_DEBUG=1`,则会将相关事件日志写入 `~/.openviking/logs/codex-hooks.log`。diff --git a/docs/zh/agent-integrations/08-community-plugins.md b/docs/zh/agent-integrations/08-community-plugins.mdindex e47008525..5e3ab8b0c 100644--- a/docs/zh/agent-integrations/08-community-plugins.md+++ b/docs/zh/agent-integrations/08-community-plugins.md@@ -40,6 +40,8 @@ curl -fsSL https://openviking.ai/install | bash实现细节与当前已验证的 ZCode 假设见插件目录中的 [README](https://github.com/volcengine/OpenViking/tree/main/examples/agent-hook-plugin) 和 [DESIGN.md](https://github.com/volcengine/OpenViking/blob/main/examples/agent-hook-plugin/DESIGN.md)。+安装完成后,在 ZCode 中新开一个会话,让它按 https://docs.openviking.net/agents/zh/onboarding.md 执行。它会检查连接,并带你完成首次使用,详见[一条提示词接入 Agent](../getting-started/07-agent-onboarding.md)。+## Kimi Code 记忆集成源码:[examples/agent-hook-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/agent-hook-plugin)@@ -72,6 +74,8 @@ curl -fsSL https://openviking.ai/install | bash -s -- --uninstall --yes --harnes已验证的宿主契约和版本见[`hosts/kimicode/DESIGN.md`](https://github.com/volcengine/OpenViking/blob/main/examples/agent-hook-plugin/hosts/kimicode/DESIGN.md)。+安装完成后,在 Kimi Code 中新开一个会话,让它按 https://docs.openviking.net/agents/zh/onboarding.md 执行。它会检查连接,并带你完成首次使用,详见[一条提示词接入 Agent](../getting-started/07-agent-onboarding.md)。+## CodeBuddy Code 记忆集成源码:[examples/agent-hook-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/agent-hook-plugin)diff --git a/docs/zh/agent-integrations/10-opencode.md b/docs/zh/agent-integrations/10-opencode.mdindex fef6ef758..8243f02c8 100644--- a/docs/zh/agent-integrations/10-opencode.md+++ b/docs/zh/agent-integrations/10-opencode.md@@ -19,6 +19,8 @@ curl -fsSL https://openviking.ai/install | bash安装器会把插件作为本地文件插件复制到 `~/.config/opencode/plugins/`,把 `openviking` MCP server 条目写进 `~/.config/opencode/opencode.json`,并配置 `~/.openviking/ovcli.conf`。+安装完成后,在 OpenCode 中新开一个会话,让它按 https://docs.openviking.net/agents/zh/onboarding.md 执行。它会检查连接,并带你完成首次使用,详见[一条提示词接入 Agent](../getting-started/07-agent-onboarding.md)。+### 手动 npm 安装已发布的 npm 包是 `@openviking/opencode-plugin`。首次配置 OpenCode 时:diff --git a/docs/zh/agent-integrations/11-pi.md b/docs/zh/agent-integrations/11-pi.mdindex e5ca07f28..85454ed52 100644--- a/docs/zh/agent-integrations/11-pi.md+++ b/docs/zh/agent-integrations/11-pi.md@@ -30,6 +30,8 @@ npm ci --prefix ~/.pi/agent/extensions/openviking --omit=dev --ignore-scripts扩展从 `shared/` 目录 import 共享模块,这个目录不在 git 里,由 `sync.mjs` 生成,所以复制前必须先运行它。之后 `git pull` 更新时,也要先重新运行 `sync.mjs` 再复制。+安装完成后,在 pi 中新开一个会话,让它按 https://docs.openviking.net/agents/zh/onboarding.md 执行。它会检查连接,并带你完成首次使用,详见[一条提示词接入 Agent](../getting-started/07-agent-onboarding.md)。+## 工作方式- **Session 开始**时构建 OpenViking profile 块,并恢复 takeover 状态,包括 `pi -c` 续跑所需的 branch 水位。profile 块包含你的 profile、记忆索引和 `<available-skills>` 清单(你自己的和账号共享的 OpenViking skill),每个 turn 都会附加到 pi 的系统提示词里;模型照某个 skill 做事之前,先用 `openviking_read` 读它的 `SKILL.md`。diff --git a/docs/zh/agent-integrations/12-cursor.md b/docs/zh/agent-integrations/12-cursor.mdindex 996fd7520..255dbe665 100644--- a/docs/zh/agent-integrations/12-cursor.md+++ b/docs/zh/agent-integrations/12-cursor.md@@ -15,6 +15,8 @@ curl -fsSL https://openviking.ai/install | bash安装完成后完全退出并重新启动 Cursor。+安装完成后,在 Cursor 中新开一个会话,让它按 https://docs.openviking.net/agents/zh/onboarding.md 执行。它会检查连接,并带你完成首次使用,详见[一条提示词接入 Agent](../getting-started/07-agent-onboarding.md)。+## 安装内容- 生命周期 Hook:自动加载画像、按问题召回、捕获对话、提交会话并保护 `viking://` URI。diff --git a/docs/zh/agent-integrations/13-trae.md b/docs/zh/agent-integrations/13-trae.mdindex d922c70fe..cfdf4ab18 100644--- a/docs/zh/agent-integrations/13-trae.md+++ b/docs/zh/agent-integrations/13-trae.md@@ -33,6 +33,8 @@ Hooks can run outside the sandbox after you trust them.TRAE 和 TRAE CN 使用安装后的 `hooks.json`,不需要审阅 hook,安装后重启对应客户端。+安装完成后,在 TRAE 中新开一个会话,让它按 https://docs.openviking.net/agents/zh/onboarding.md 执行。它会检查连接,并带你完成首次使用,详见[一条提示词接入 Agent](../getting-started/07-agent-onboarding.md)。+## 安装内容- `SessionStart`:加载用户画像、当前项目记忆,以及 OpenViking skill 清单 `<available-skills>`。diff --git a/docs/zh/agent-integrations/17-dsh.md b/docs/zh/agent-integrations/17-dsh.mdindex b1674443b..ed1602c4c 100644--- a/docs/zh/agent-integrations/17-dsh.md+++ b/docs/zh/agent-integrations/17-dsh.md@@ -44,6 +44,8 @@ curl -fsSL https://openviking.ai/install | bash</details>+安装完成后,在 DSH 中新开一个会话,让它按 https://docs.openviking.net/agents/zh/onboarding.md 执行。它会检查连接,并带你完成首次使用,详见[一条提示词接入 Agent](../getting-started/07-agent-onboarding.md)。+## 验证启动 `dsh --profile web` 打开一个会话,会话开头应该能看到一条 OpenViking 上下文注入,模型也应该具备 `mcp__openviking__*` 工具。问一句更早会话里聊过的事,确认召回生效。diff --git a/docs/zh/getting-started/07-agent-onboarding.md b/docs/zh/getting-started/07-agent-onboarding.mdnew file mode 100644index 000000000..b0a4384e9--- /dev/null+++ b/docs/zh/getting-started/07-agent-onboarding.md@@ -0,0 +1,60 @@+# 一条提示词接入 Agent++把一条提示词粘贴给你正在用的编程 Agent。Agent 会在本机检测到的各个 Agent 里安装 OpenViking 记忆插件,检查连接,问你要不要导入近期工作,再告诉你怎么重启。重启后,你问的第一个问题就能用上 OpenViking。++Agent 按一份简短的指南执行。指南以纯 Markdown 发布,任何 Agent 都能直接获取:++- 中文:`https://docs.openviking.net/agents/zh/onboarding.md`+- 英文:`https://docs.openviking.net/agents/en/onboarding.md`++两份也都可以从 `docs.openviking.ai` 访问。中国大陆访问 `docs.openviking.net` 通常更快。++## 提示词++复制提示词,发送前把 `<API_KEY>` 换成你的 key,在 [OpenViking 控制台](https://console.volcengine.com/vikingdb/openviking/region:openviking+cn-beijing?utm_source=opensource_docs&utm_medium=referral&utm_campaign=getting-started_07-agent-onboarding)的**用户管理 → API Key** 中获取。++<AgentPrompt>++```text+帮我安装 OpenViking 记忆插件,并带我开始使用。OpenViking 是火山引擎开源的 Agent 上下文数据库(https://github.com/volcengine/OpenViking,AGPL-3.0),下面的命令和链接来自它的官方文档。++1. 运行官方安装器。它需要联网并写入我的主目录,如果被你的沙箱拦住,请向我申请批准:+ curl -fsSL https://openviking.ai/install | bash -s -- --yes --lang zh --url https://api.vikingdb.cn-beijing.volces.com/openviking --api-key <API_KEY>+2. 装好后读 OpenViking 的接入引导,按它带我完成设置。导入历史、写协作规则这类选择,引导会让你先问我。docs.openviking.net 和 docs.openviking.ai 是同一个文档站,哪个打得开用哪个:+ https://docs.openviking.net/agents/zh/onboarding.md++API key 是我在 OpenViking 控制台给自己生成的,安装器会把它存到本机的 ~/.openviking/ovcli.conf。命令里原样使用就行,回复里不用再显示它,也不要写进别的文件或规则。全程用中文和我交流。+```++</AgentPrompt>++安装器会给本机检测到的所有受支持的 Agent 都装上插件,所以你装过的其他 Agent 也会装上;每个 Agent 都要各自重启后,插件才会在里面生效。安装器还会同时安装 `ov` 命令,Agent 要用它检查连接、添加文件。`--lang` 设置安装器的语言,安装器最后打印的引导链接也随之选择语言。想只装其中几个,加上 `--harness` 并用逗号分隔列出,例如 `--harness claude,cli`,详见[统一安装器](../agent-integrations/16-capability-reference.md#_3-1-2-统一安装器)。++**自部署服务。** 把 URL 换成你自己服务的地址。要用 user key,root key 不能读写记忆。本地服务没有开启鉴权时,传 `--api-key ''`。++**关于 key。** 安装器只能通过命令行参数接收 key,所以 key 会出现在这段对话里,也会留在 Agent 本地的会话记录和日志中。指南要求 Agent 不复述 key、不把它写进任何地方。插件目前还不会从保存的对话里删除 key,重启后的第一次保存会把安装对话也存进去:在 Codex 上,不管回到原对话还是开新会话都会这样,这段安装对话连同 key 可能被保存到你自己的 OpenViking 账号里;在 Claude Code 上开新会话可以避免,所以 Agent 会请你不要回到安装对话。如果你不想把 key 贴进聊天,可以自己在终端运行 `curl -fsSL https://openviking.ai/install | bash`,再把[已经装好](#已经装好)一节的提示词发给 Agent。++## 已经装好++如果插件已经装好,在 Agent 里开一个新会话,发送:++```text+按 https://docs.openviking.net/agents/zh/onboarding.md 带我完成 OpenViking 首次使用。+```++## Agent 会做什么++1. **检查安装结果。** 读取安装器的输出并运行 `ov health`,告诉你已经连上、插件装进了哪些 Agent;装进了不止一个时,它们用的是同一份上下文。+2. **说明哪些事会自动发生。** 每次提问前,插件会召回相关记忆;每轮对话结束后,插件保存对话,服务端在后台提取长期记忆。这一步不需要你另外批准,请求安装本身就是同意。+3. **问你要不要带入已有工作。** 默认导入当前项目最近 14 天的会话。你也可以描述某一类工作,例如「和支付重构有关的讨论」:Agent 会列出候选会话和每个会话的摘要,挑出相符的,先给你看挑选结果,再上传。Claude Code 和 Codex 的历史由导入脚本直接读取;其他 Agent 会先写一个小脚本把自己的会话转成 JSONL,再交给同一个导入脚本。Agent 会先告诉你找到了哪些工作、有多大,你确认后才导入;已经在 OpenViking 里的会话不会重复上传。导入后,Agent 会马上从 OpenViking 读回这项工作做到哪、定过什么,让你在重启前就看到导入的用处。只发送用户和助手的文字,工具调用及其输出会被丢弃,API key 会被删除。本机有 Claude Code 或 Codex 的历史时,在其他 Agent 上也会一并提议导入。你也可以点名要保存的文件,例如设计文档,Agent 用 `ov add-resource` 把它添加到你个人资源里这个项目的目录。+4. **提议一套长期协作规则。** Agent 会提议在你的用户级规则文件(例如 Claude Code 的 `~/.claude/CLAUDE.md`、Codex 的 `~/.codex/AGENTS.md`)里加一段规则,对你所有项目生效:先用 OpenViking 召回的上下文,不够再检索;把重要决定(连同理由)、阶段进展和下一步,以及方案、调研、交付物等工作产出主动存进 OpenViking,放在你个人资源下每个项目一个的目录里(`resources/<项目名>/`,进展和决定记在其中的 `notes/`);继续一个项目时先看之前存下的内容;用到或存了东西会简短告诉你。你也可以让它按你的角色(产品、研发、市场、设计等)调整,补上这个角色还要保存的内容。规则放在一对 `<!-- openviking:start -->` / `<!-- openviking:end -->` 标记之间,文件里原有的内容不动;你同意才写,写完会读回确认。个人规则只能在应用设置里改的 Agent(例如 TRAE、Cursor),会请你自己粘贴进去。它不会把规则写进项目文件。+5. **告诉你怎么重启。** 插件要在 Agent 重新启动后才会加载。Agent 会给出你正在对话的这个 Agent 的具体操作:Codex 里先信任 OpenViking 的 hooks(CLI 在会话里输入 `/hooks`,桌面版点输入框下方的 hooks 图标),再退出、回到同一段对话(CLI 运行 `codex resume --last`),说一句「已重启」,如果仍出现「Hooks need review」,选 **Trust all and continue**;Claude Code 和其他 Agent 开一个新会话,发它给你的第一句话。安装器如果还装进了其他 Agent,它会告诉你那些也需要重启。+6. **让你看到 OpenViking 在起作用。** 重启之后,你的第一个问题会基于召回的上下文回答,Agent 会告诉你在哪里能看到:Claude Code 的来源卡片、Codex 的 OV-Usage 行,等等。++Agent 只在需要你做决定时提问:带入哪些工作(看到数量后再确认一次),以及要不要写入协作规则;每次都会先讲清对你有什么用、会发送或改动什么。已经选过的不会重复问。++## 另请参阅++- [Agent 接入概览](../agent-integrations/01-overview.md)+- [Agent 集成能力](../agent-integrations/16-capability-reference.md)+- [安装和使用 CLI](05-cli-setup.md)