# 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-overview