# @cortexkit/pi-magic-context 中文文档

规范地址：https://npmcn.com/package/%40cortexkit/pi-magic-context/

版本：0\.49\.49
npm 元数据更新时间：2026-11-10T12:08:11.634Z
中文译文更新时间：2026-11-10T20:00:20.732Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：10.9 MB，112 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：7 个
- peer 依赖：typebox \*，@earendil-works/pi-tui \*，@earendil-works/pi-coding-agent \*
- 首次发布：2026-05-04T14:09:02.329Z
- 最新版本发布：2026-11-10T12:08:10.458Z
- 近 30 天下载量：16977（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：147（近 12 个月 147 个）

## 中文简介

Pi and OMP 为魔法背景提供的编码代理扩展——跨会话内存和上下文管理

## 安装

```sh
npm install @cortexkit/pi-magic-context
```

也可以使用：`pnpm add @cortexkit/pi-magic-context`、`yarn add @cortexkit/pi-magic-context`、`bun add @cortexkit/pi-magic-context`

## README

# 魔法背景- Pi / OMP 扩展名

跨会内存和上下文管理 [Pi 编码代理](https://github.com/earendil-works/pi-mono) 财务报告和审定财务报表 [哦,我的Pi (OMP) (英语)](https://github.com/can1357/oh-my-pi)。同一扩展包运行在主机上,并与该主机共享其SQLite数据库 [打开代码插件](https://www.npmjs.com/package/@cortexkit/opencode-magic-context)。 。 。 .

需要皮条 `>= 0.74.0` 办公室管理计划 `>= 17.1.7`。 。 。 .

* * *

## 它会做什么

魔法背景(Magic Context)是一个上下文引擎,通过:

| 特性 | 它会做什么 |
| --- | --- |
| **拖放+滴滴数** | 标记每个助手/用户/工具消息 `§N§` 因此,您可以在以后通过 `ctx_reduce` |
| **历史学家** | 背景子剂将旧对话压缩成隔间 + 在门槛压力下的事实或承诺边界 |
| **`<session-history>` 注射** | 预先将压缩历史输入系统, 提示每个转动, 这样代理商就不会失去上下文 |
| **项目记忆** | 有嵌入式语义搜索的持续跨会话知识库 |
| **梦中人** | 整理、核实、存档和改进所储存记忆的预定背景副剂 |
| **自动搜索提示** | 当用户提示提及先前讨论的主题时, 附加一个紧凑的内存提示 |
| **备注** | 自然工作界限的表面延后意图(承诺、待办事宜完成、历史学出版物) |
| **跨部门共享** | 由 OpenCode 所写的回忆出现在 Pi (反之亦然) 中,用于同一工程 |

* * *

## 安装

最快的路径是统一的"魔法背景CLI"—— `--harness pi` 选择 Pi 特定设置管道( 用 Pi 注册扩展名, 写一个明智的 `magic-context.jsonc`并验证你的模型选择:

```bash
npx @cortexkit/magic-context@latest setup --harness pi
```

这能帮你处理一切

1.  添加数 `npm:@cortexkit/pi-magic-context` 给Pi的 `packages` 阵列 `~/.pi/agent/settings.json` (同一地点) `pi install` 写到)
2.  创建 `~/.config/cortexkit/magic-context.jsonc` 默认
3.  激励你做历史学家、梦想家和嵌入模型的选择
4.  关于提供者特定模式的警告(例如 GitHub 副驾驶推理模型需要明确 `thinking_level`(中文(简体) )

如果您宁可直接用 Pi( 向导) 注册 Pi 扩展包, 请使用 Pi 自己的安装器 :

```bash
pi install npm:@cortexkit/pi-magic-context
```

这将扩展添加到 `~/.pi/agent/settings.json` 但不写 `magic-context.jsonc` 用于您 —— 手动创建共享配置 `~/.config/cortexkit/magic-context.jsonc` (见下文配置).

稍后检查安装状况:

```bash
npx @cortexkit/magic-context@latest doctor --harness pi
```

### 哦,我的Pi (OMP) (英语)

使用 OMP 特定设置路径 。 它通过 OMP 的插件管理器安装软件包,禁用 OMP 本地收缩和自动内存以防止上下文管理器重复,并验证有效的工程插件状态:

```bash
npx @cortexkit/magic-context@latest setup --harness omp
```

还支持手工安装:

```bash
omp plugin install @cortexkit/pi-magic-context
omp config set compaction.enabled false
omp config set memory.backend off
```

以 :

```bash
npx @cortexkit/magic-context@latest doctor --harness omp
```

OMP 遗留的 Pi 加载器地图 `@earendil-works/*` 进口到捆绑的 `@oh-my-pi/*` 运行时间。 魔法背景识别 OMP 从 `@oh-my-pi/pi-utils`正在处理中 `APP_NAME` 通过运行中的主机的模块图,而不是从可执行的基名,所以编译和同位链接的发射行为是一样的. 它还为历史学家和梦想家儿童重新启用了目前的主机可执行程序,因此OMP儿童仍然是OMP进程.

* * *

## 配置

魔法背景读取共享 CortexKit 配置( 项目覆盖用户) :

1.  `$cwd/.cortexkit/magic-context.jsonc`
2.  `~/.config/cortexkit/magic-context.jsonc`

会话发现跟随活动主机. 相对 `pi.subagent_extensions` 被主机故意隔离: Plain Pi solved them from `~/.pi/agent`,而正态识别的 OMP 进程用途 `PI_CODING_AGENT_DIR` 当设定并生成活性 `~/.omp` 配置/配置代理目录 .

### 最小配置

```jsonc
{
  "$schema": "https://raw.githubusercontent.com/cortexkit/magic-context/master/assets/magic-context.schema.json",
  "enabled": true,
  "historian": {
    "pi": {
      "model": "anthropic/claude-haiku-4-5"
    },
    "omp": {
      "model": { "model": "opencode/claude-haiku-4-5", "thinking_level": "auto" }
    }
  },
  "embedding": {
    "provider": "local"
  }
}
```

办公室管理计划的使用 `historian.omp ?? historian.pi` 财务报告和审定财务报表 `dreamer.omp ?? dreamer.pi`; 离开 OMP 块保留现有的 Pi 兼容配置。 OMP 支持 `off`, (中文(简体) ), `minimal`, (中文(简体) ), `low`, (中文(简体) ), `medium`, (中文(简体) ), `high`, (中文(简体) ), `xhigh`, (中文(简体) ), `max`, (中文(简体) ), `inherit`,以及 `auto` 思维水平.

完整的配置参考(包括梦人、自动搜索和实验功能)见 [说明.md](https://github.com/cortexkit/magic-context/blob/master/CONFIGURATION.md) 在主寄存器中——OpenCode,Pi,和OMP共享相同的schema.

* * *

## 斜线命令

所有命令触发 `triggerTurn: false` (从未被送到LLM):

| 命令 | 它会做什么 |
| --- | --- |
| `/ctx-status` | 活代码分解 + 队列化的操作 + 缓存状态 |
| `/ctx-flush` | 强制进程等待操作队列 |
| `/ctx-recomp` | 从原始历史中重建隔间(重型操作) |
| `/ctx-wrapup [messages_to_keep]` | 压缩旧的现场历史,同时保留最新消息 |
| `/ctx-dream` | 唤起梦想随叫随到 |

* * *

## 存储

魔法背景将一切存储在一个共享的 SQLite 数据库中 :

```
~/.local/share/cortexkit/magic-context/context.db
```

当主机孤立时 `XDG_DATA_HOME` 每个进程,设定 `MAGIC_CONTEXT_STORAGE_DIR` 到绝对,完全共享的魔法背景 存储目录。 明确的路径优先于 XDG 衍生路径 而不更改 Pi 的配置或会话目录。 东道主必须 向共享数据库的每个进程传播一个相同的值; Magic 背景绝不是该变量的默认来源 。 这影响到 仅使用带边数据库,而不是 `subc` 守护进程状态 。 混合版本进程 一个目录仍然屏蔽迁移,直到所有进程使用相容的构建.

这是 **同一数据库** openCode 插件和 OMP 扩展使用。 表格的范围包括:

-   `harness` 栏(`'pi'` 或者说 `'opencode'`用于会话范围的数据;办公室管理计划有意使用 `'pi'`
-   `project_path` (已解析出 git root)用于项目范围数据(记忆,嵌入,梦想者运行)

记忆和梦想者状态为同一个项目在所有三个工具之间共享;每部分标记都正确归属.

存储失败是致命的——"魔法背景"将拒绝注册钩子,而不会在瞬间状态下运行,因为这样会让背景在重启时无限制地增长.

* * *

## 跨部门一致性

为了使语义搜索能跨出绳子,每个主机必须使用 **相同的嵌入模式**. Magic Context 检测出 Pi 或 OMP 启动时的不匹配并警告:

```
WARN embedding model mismatch detected for project ...:
stored vectors use "openai-compatible:Qwen/Qwen3-Embedding-8B" but Pi is configured with "local:Xenova/all-MiniLM-L6-v2".
Cross-harness search will return zero results until vectors are re-embedded.
```

配置 `embedding` 共享中一次 `~/.config/cortexkit/magic-context.jsonc`; OpenCode, Pi, 和 OMP 全部读取. 使用 `$cwd/.cortexkit/magic-context.jsonc` 只有在项目需要修改时.

* * *

## 代理人可用的工具

| 工具 | 行动到位 | 目的 |
| --- | --- | --- |
| `ctx_search` | 无 | 搜索记忆 + 原始会话历史; 返回带有预览的排名结果 |
| `ctx_memory` | `write`, (中文(简体) ), `delete` | 明确管理项目记忆( 大多通过梦想者写作 ) |
| `ctx_note` | `read`, (中文(简体) ), `write`, (中文(简体) ), `update`, (中文(简体) ), `dismiss` | 推迟以后的意向——通过工作界限的注解来显示 |
| `ctx_expand` | `start`编号 :`end`, (中文(简体) ), `message`, (中文(简体) ), `verbose` | 恢复完整信件或扩展压缩谈话范围 |
| `ctx_reduce` | `drop` | 将标记为缓存安全切换的回合排队 |

`ctx_note`, (中文(简体) ), `ctx_expand`,以及 `ctx_reduce` 已设定会话范围,并在初级皮/OMP会话中曝光。 魔法背景从麻风中省略 `--no-session` 儿童过程,否则会针对隐藏的儿童会话; `ctx_reduce` 当压缩功能被禁用时,会额外省略.

* * *

## 架构和执行

此软件包是 [魔法背景单曲](https://github.com/cortexkit/magic-context). Pi和OMP共享相同的适配器层和核心执行:

| Pi 专用模块 | 责任 |
| --- | --- |
| `context-handler.ts` | Pi `pi.on("context", ...)` 适配器——标记、滴放、运行微软和自动搜索 |
| `subagent-runner.ts` | 重新启用当前 Pi/ OMP 主机 `--print --mode json --no-session`; 解析相对允许从 plain Pi 列表扩展 `~/.pi/agent` 或指定的 OMP 主机的有效代理目录; 并应用按代理工具隔离 |
| `tools/` | Pi `pi.registerTool` 围绕共享工具执行的包装 |
| `commands/` | Pi `pi.registerCommand` 5个的包装 `/ctx-*` 斜线命令 |
| `dreamer/` | 共享梦想器调度器的 Pi- side 适配器 |
| `system-prompt.ts` | Pi `before_agent_start` 用于 `<session-history>`, (中文(简体) ), `<project-memory>`, (中文(简体) ), `<project-docs>` |
| `config/` | 共享 CortexKit 配置加载器和遗留的 Pi 迁移回落 |

统一 [`@cortexkit/magic-context`](https://www.npmjs.com/package/@cortexkit/magic-context) CLI 单独曝光 `pi` 财务报告和审定财务报表 `omp` 设置/博士管线,同时使用这个运行时间适配器.

关于更深层次的建筑细节,见主回波 [四、建 议](https://github.com/cortexkit/magic-context/blob/master/ARCHITECTURE.md)。 。 。 .

* * *

## 许可证

麻省理工学院——见 [自由主义](https://github.com/cortexkit/magic-context/blob/master/LICENSE)。 。 。 .

## 常见问题

### @cortexkit/pi-magic-context 是什么？

Pi and OMP 为魔法背景提供的编码代理扩展——跨会话内存和上下文管理

### 如何安装 @cortexkit/pi-magic-context？

在项目目录运行 npm install @cortexkit/pi-magic-context，或使用 pnpm add / yarn add / bun add。

### @cortexkit/pi-magic-context 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/cortexkit\_\_pi-magic-context 是否存在。

### @cortexkit/pi-magic-context 支持 ESM 还是 CommonJS？

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

### @cortexkit/pi-magic-context 可以商用吗？

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

### @cortexkit/pi-magic-context 的下载量有多少？

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

### @cortexkit/pi-magic-context 还在维护吗？

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