# @codemem/pi-extension 中文文档

规范地址：https://npmcn.com/package/%40codemem/pi-extension/

版本：0\.49\.1
npm 元数据更新时间：2026-11-15T20:37:07.566Z
中文译文更新时间：2026-11-15T04:39:47.015Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40codemem/pi-extension
原文对照：https://npmcn.com/package/%40codemem/pi-extension/?lang=original
项目主页：https://github.com/kunickiaj/codemem
源码仓库：https://github.com/kunickiaj/codemem

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：298 kB，23 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：0 个
- peer 依赖：typebox \*，@earendil-works/pi-coding-agent \>=1\.1\.0 \<2
- 首次发布：2026-09-21T15:55:00.381Z
- 最新版本发布：2026-11-15T20:37:07.172Z
- 近 30 天下载量：2184（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：30（近 12 个月 30 个）

## 中文简介

用于 pi 编码代理的 CodeMem 扩展名 — 摄入、注入和本地记忆工具

## 安装

```sh
npm install @codemem/pi-extension
```

也可以使用：`pnpm add @codemem/pi-extension`、`yarn add @codemem/pi-extension`、`bun add @codemem/pi-extension`

## README

# @ codemem/ pi- extension (帮助)

Pi 编码代理扩展 [代码](https://github.com/kunickiaj/codemem):会话摄入并转动局部内存注入.

## 安装

需要Pi 1.1.0或更新,低于2.0. 升级旧主机 `pi update` (单位:千美元)`pi update --extensions` 调节已安装的软件包,而不是主机.

```bash
npm i -g codemem
codemem setup --pi-only
```

一起更新 CLI 和 Pi 扩展,然后重新运行设置并重新启动 Pi 扩展的 CLI 折返使用分组 `memory` 财务报告和审定财务报表 `session` 命令。 老一点 如果扩展单独升级, CLI 可能不会支持这些路径 .

设置后重启 Pi. `codemem setup --pi-only` 只配置 Pi。 添加新设置 `npm:@codemem/pi-extension@<version>` 改为 `settings.json` `packages` (单位:千美元)`PI_CODING_AGENT_DIR` 设定时, 否则 `~/.pi/agent`; 现有的已配置dev路径可能被保留。 有用的旗帜 :

| 旗帜 | 目的 |
| --- | --- |
| `--pi-only` | 只配置 pi |
| `--pi-mcp` | 通过第三方选择进入MCP `pi-mcp-adapter` (写作) `mcp.json` 仅在检测到时) |
| `--pi-extension-path <path>` | Dev: 写一个本地路径 `packages` 条目,而不是 npm 针 |

Dev / 本地路径安装( 等同 `--pi-extension-path`:

```json
{
  "packages": ["/absolute/path/to/codemem/packages/pi-extension"]
}
```

先盖好 `dist/index.js` 已存在( e)`pnpm --filter @codemem/pi-extension build`) (中文(简体) ).

**卸载 :** 删除 `@codemem/pi-extension` 软件包条目并重新启动 pi 。 共享记忆库保存完好.

## 它会做什么

-   **无礼** 常会活动`session_start`,用户/助理消息,工具呼叫/结果) `POST /api/pi-hooks` (单位:千美元)`source: "pi"`),与 `codemem pi-hook-ingest` CLI回落(失败时的集合). 边界事件`session_before_compact`, (中文(简体) ), `session_shutdown`) 总是尝试 CLI 路径, 以便冲出可以运行; 失败是打开的 .
-   **注射** - 临τ `context` 事件,附件 a `## codemem memories` 块到最近的用户消息 **请求副本** (系统从不提示,从不保存会话). 更年长的用户信件重放已经为它们注入的精确字节,只为最新的未确定的消息取取出一个新的包,因此提供者的前缀缓存保持稳定. 当装包反应携带出料器时,已经抛出的物品被从新包中取出. 合同有效的HTTP或 `memory pack --json` 反应,包括一个零项包,获取的结束; `{}` 错误的躯体掉入。 这些跨度的成功记录 `inject.pack.ok source=pi` 到插件日志, 同一行 `pi-hook-inject` 当它是倒计时,写作。 决定存于记忆中: 重新开始抓取 .
-   **文件上下文** ——成功内置后 `read`,相关记忆可能附在该工具结果后。 读取失败并跳过其他工具 .
-   **工具** - 登记15人 `memory_*` 本地工具( 首选的 HTTP, CLI 倒置), 包括 `memory_session_search` 超过存储的 Pi 会话文本。 每一次HTTP操作首先证明取景者有目标意识(`GET /api/prompt-pack-profile` 必须报告此过程的 `db_path` + 键 `identity_target`)并重新将目标发送到查询上,因此端口上的一个外人或呆滞的更年长的取景者永远不会被信任(409或未经证实 ~ 有目标的CLI路径). 非专有能力 `memory_remember` 对模棱两可的 HTTP 失败不进行 CLI 重放( 发送后超时出/ 重置) 。 没有 `pi-mcp-adapter` 需要帮助。 跳过时 `pi.tools_mode` 实值 `mcp-adapter`。 。 。 .
-   **压缩** —— 说 `session_before_compact` 仅尝试冲出,而不返回自定义摘要. `session_compact` 仅当 `willRetry` 设置和 `reason` 没有 `manual`失败收缩, `agent_settled`,手动收缩,以及稍后的用户信息清除跳过。 一个阈值紧凑的跳过 只有当同一个守卫匹配.
-   **叉子/重置** ——每集重键串流身份 `session_start`。通过 `pi.appendEntry` (单位:千美元)`codemem.cursor`) (中文(简体) ). 召回决定留在记忆中,并在 `session_start`; 重新启动反切.
-   **交叉代理** ——一个共享,项目范围商店. 从OpenCode/Claude/Codex注入pi和倒置的记忆.
-   **盘子** —— pi行出现在源不可知的种子/会话/项目标签中,没有额外的设置.

工具目的和故障排除: [Pi 扩展](https://github.com/kunickiaj/codemem/blob/main/docs/plugin-reference.md#pi-extension)。 。 。 .

## 观察员衍生(v1)

设置可以填补未设置 `observer_*` pi 的 API- key 提供者的密钥( 便宜型- first) 。 证书只保存在内存中,从未被写入代码化配置. `unconfigured (oauth-only)` 当只有 OAuth 证书时, 而不是每个观察员连接的状态时, 是自动开发状态 。 单独配置观察员证书或连接,必要时由提供者或模型覆盖([观察员认证](https://github.com/kunickiaj/codemem/blob/main/docs/user-guide.md#observer-auth-configuration)) (中文(简体) ). 明确 `observer_*` 配置/env总是获胜.

## 配置

从 `CODEMEM_CONFIG` 设定时, 否则 `$XDG_CONFIG_HOME/codemem` 或者说 `~/.config/codemem`,使用现有的 `config.json` 接下来 `config.jsonc`Pi 键在 `pi` 对象,与 `CODEMEM_PI_*` env 覆盖.

| 密钥/ 隐藏 | 默认 | 含义 |
| --- | --- | --- |
| `pi.tools_mode` 编号 : `CODEMEM_PI_TOOLS_MODE` | `native` | `native` 在此登记工具; `mcp-adapter` 跳过本地注册; 单独配置 MCP |
| `pi.inject_prompts` 编号 : `CODEMEM_PI_INJECT_PROMPTS` | `true` | 将内存包附加到每个模型请求中的最新用户信件 |
| `pi.file_context` 编号 : `CODEMEM_PI_FILE_CONTEXT` | `true` | 将相关记忆添加到成功的内置读取结果 |

共享取景器 / 注射取号( 和其他客户端相同 ) :

| 信封 | 默认 | 含义 |
| --- | --- | --- |
| `CODEMEM_VIEWER_HOST` | `127.0.0.1` | 查看器主机 |
| `CODEMEM_VIEWER_PORT` | `38888` | 查看器端口 |
| `CODEMEM_VIEWER` | `1` | 启用查看器使用 |
| `CODEMEM_VIEWER_AUTO` | `1` | 自动启动 `codemem serve start` 需要时 |
| `CODEMEM_RAW_EVENTS_BACKOFF_MS` | `10000` | HTTP 流失败后退后再试 |
| `CODEMEM_INJECT_LIMIT` | `8` | 包件限制 |
| `CODEMEM_INJECT_TOKEN_BUDGET` | `800` | 包装符号预算 |
| `CODEMEM_INJECT_MAX_CHARS` | `16000` | 最大注入块字符 |
| `CODEMEM_INJECT_RETAINED_TOKEN_BUDGET` | 未封装 | 会话中已经注入的区块的可选近似符号上限(估计为 `ceil(chars / 4)`) (中文(简体) ). 取消设置、 零、 负值和无效值表示没有上限; 启用时, 完全上限不附加任何新内容, 不获取任何内容, 绝不删除或切换已附加的块 |
| `CODEMEM_PI_HOOK_HTTP_TIMEOUT_MS` | `5000` | 最出名和本土工具HTTP超时 (ms). 不设置套装超时 |

示例配置 :

```json
{
  "pi": {
    "tools_mode": "native",
    "inject_prompts": true,
    "file_context": true
  }
}
```

## 生命周期

Per pi扩展规则:工厂仅接线. 查看器自动启动和其它会话资源开始 `session_start` {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}然后把自己打扫干净 `session_shutdown`会话状态从 `ctx.sessionManager.getSessionId()` 每页 `session_start`; 持久的摄入光标持续通过 `pi.appendEntry` (单位:千美元)`codemem.cursor`) (中文(简体) ). 召回决定不是会话条目 .

## 同伴依赖关系

-   `@earendil-works/pi-coding-agent` `>=1.1.0 <2` (宣布的主机对等)
-   `typebox` (工具参数计划)

没有 `@codemem/core` 或本地模块在 pi 进程内加载.

## 常见问题

### @codemem/pi-extension 是什么？

用于 pi 编码代理的 CodeMem 扩展名 — 摄入、注入和本地记忆工具

### 如何安装 @codemem/pi-extension？

在项目目录运行 npm install @codemem/pi-extension，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：typebox（\*）、@earendil-works/pi-coding-agent（\>=1\.1\.0 \<2）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @codemem/pi-extension 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @codemem/pi-extension 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @codemem/pi-extension 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @codemem/pi-extension 可以商用吗？

@codemem/pi-extension 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @codemem/pi-extension 的下载量有多少？

根据 npm 官方下载统计，@codemem/pi-extension 在 2026/10/10 – 2026/11/08 这 30 天内被下载 2,184 次，日均约 73 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @codemem/pi-extension 还在维护吗？

最新版本 0\.49\.1 发布于 2026/11/16（今天）；至今共发布 30 个版本，其中过去 12 个月发布了 30 个；首次发布于 2026/09/21。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。