# pi Coding Agent 扩展

为 [pi](https://github.com/earendil-works/pi) 提供跨会话长期记忆和 context takeover。扩展基于 pi 原生扩展 API 构建（pi 不支持 MCP）：每个 prompt 前自动召回、每个 turn 后自动捕获，并可由 OpenViking 在 pi 的 `context` hook 中用归档 overview 替换已 commit 的本地历史。

源码：[examples/pi-coding-agent-extension](https://github.com/volcengine/OpenViking/tree/main/examples/pi-coding-agent-extension)

## 工作方式

- **Session 开始**时注入 OpenViking profile 块，并恢复 takeover 状态，包括 `pi -c` 续跑所需的 branch 水位。
- **每个 prompt** 向 OpenViking server 做语义召回，把命中的记忆作为隐藏上下文注入。
- **每个 turn** 把用户与助手消息（含结构化工具调用）捕获进 OpenViking session；takeover 模式会在 synced token 压力超过阈值后 commit，并在模型上下文中只保留近期 live tail。
- **Context takeover** 默认开启。`context` hook 会先注入来自最新 archive overview 的 `[OpenViking Session Context]`，再把 recall 结果插入最新用户消息。
- **原生工具** `viking_search`、`viking_read`、`viking_browse`、`viking_remember`、`viking_forget`、`viking_add_resource`、`viking_archive_expand` 供模型按需查询和写入记忆。
- 底部状态栏显示 `OV ✓ …` 连接与捕获状态；`/viking` 命令查看状态，`/viking commit` 强制 commit。
- 模型误用本地 `read`/`bash` 读取 `viking://` URI 时会被拦截，并提示改用 `viking_read` / `viking_search`。

## 前置条件

- pi coding agent（`npm i -g @earendil-works/pi-coding-agent`）
- OpenViking HTTP server——用 `curl http://localhost:1933/health` 确认可达

## 安装

pi 与其他记忆插件共用同一个安装器。它会询问语言、要安装的 harness、下载源和 OpenViking 凭据；每一步都是幂等的。

```bash
bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/memory-plugin-shared/install.sh) --harness pi
```

在 GitHub 访问困难的地区，可从火山引擎 TOS 镜像运行同一个安装器：

```bash
bash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh)
```

安装器会把扩展复制到 `~/.pi/agent/extensions/openviking`（保留已有的 `config.json`），用 `pi install` 完成注册，并配置 `~/.openviking/ovcli.conf`。

也可以从仓库 checkout 手动复制：

```bash
git clone https://github.com/volcengine/OpenViking.git
cd OpenViking
mkdir -p ~/.pi/agent/extensions
cp -r examples/pi-coding-agent-extension ~/.pi/agent/extensions/openviking
```

## 配置

凭据解析顺序是 `OPENVIKING_*` 环境变量、`~/.openviking/ovcli.conf`、`~/.openviking/ov.conf`——与 Claude Code、Codex、OpenCode 插件共用。尚未配置时可运行一次向导：

```bash
node ~/.pi/agent/extensions/openviking/scripts/setup.mjs
```

`~/.pi/agent/extensions/openviking/config.json` 只保留行为旋钮，重装时会保留你的修改：

```json
{
  "recallLimit": 6,
  "scoreThreshold": 0.35,
  "recallTokenBudget": 2000,
  "profileTokenBudget": 10000,
  "resumeContextBudget": 32000,
  "commitTokenThreshold": 20000,
  "commitKeepRecentCount": 10,
  "takeover": {
    "enabled": true,
    "tokenThreshold": 30000,
    "keepRecentTurns": 3,
    "overviewBudget": 3000,
    "overviewPollMs": 2000,
    "overviewPollMax": 15
  },
  "captureAssistantTurns": true,
  "bypassPatterns": []
}
```

Takeover 是 fail-open：如果 pending 写入无法 flush、commit 失败、archive overview 尚未生成，或 branch 指纹不匹配，pi 会继续保留完整本地历史，或回退到默认 compaction。验证边界推进时可设置 `OV_DEBUG_LOG=/tmp/ov-pi.log`。

## 验证

启动 `pi`。连接成功后底部状态栏出现 `OV ✓` 段，`/viking` 会打印当前 session 映射。问 pi 一个你在早前会话里提到过的事情，确认召回生效。

## 故障排查

| 问题 | 排查方向 |
|------|----------|
| 状态栏显示 `OV ✗` 或提示 "server not reachable" | `curl http://localhost:1933/health`；检查 `~/.openviking/ovcli.conf` 中的 endpoint |
| 扩展没有加载 | `pi list` 应能看到 `extensions/openviking`；重跑安装器或执行 `pi install ~/.pi/agent/extensions/openviking` |
| 报错提到 `@mariozechner/*` | pi 迁移到 `@earendil-works/*` 之前的旧副本——重跑安装器 |
| OpenViking 返回 401 / 403 | 检查 `OPENVIKING_API_KEY`；trusted-mode 部署还要检查 `OPENVIKING_ACCOUNT` 和 `OPENVIKING_USER` |
| recall 为空 | 确认 server 中已有记忆，且 prompt 长度超过 `minQueryLength` |

完整工具、配置与设计说明见 [扩展 README](https://github.com/volcengine/OpenViking/tree/main/examples/pi-coding-agent-extension)。