1context

1context 根据当前文件或用户消息，把相关项目知识发送给 Claude Code、Codex 和 Pi。它还会在长会话中再次提醒，记录每次发送，并提供候选知识的 A/B 验证流程。

这个目录是 npm 包源码，也是团队成员实际安装的版本。仓库根目录中的 Python 版只用于行为对拍。

安装和初始化

需要 Node.js 20 或更高版本。

npm install -g 1context
cd your-project
1context init

1context init 会生成或更新：

| 文件 | 作用 | | --- | --- | | .onecontext.json | 设置 Wiki 目录和再次提醒间隔 | | wiki/example-rule.md | 第一条示例；Wiki 中已经有 Markdown 文件时不生成 | | .claude/settings.local.json | 让 Claude Code 运行 1context hook | | .codex/hooks.json | 让 Codex 运行 1context hook --host codex | | .pi/settings.json | 让 Pi 加载 npm 包内的 dist/pi.js 扩展 |

宿主检测来自项目目录和 PATH。重复运行会更新 1context 自己的配置，不会 重复添加，也不会删除其他 hook 或扩展。

npm 包同时提供 1context 和 onecontext 两个命令名。它们完全相同。

写第一条知识

---
paths:
  - "src/api/**"
description: API 输入检查
---

读取任何字段前，先用 Zod 检查 API 输入。

重新启动 Agent。它用文件工具读取或修改 src/api/ 下的文件后，会在下一次 模型回复前收到正文。

也可以按用户消息中的关键词触发：

---
triggers:
  - "production release"
description: 生产发布检查
---

先运行 `npm run release:check`，通过后才能发布。

同时没有 paths 和 triggers 的条目是全局知识，在会话开始时发送。

为什么 Pi 使用扩展

Claude Code 和 Codex 支持通过标准输入和输出运行外部 hook，所以它们的 配置调用 CLI。Pi 只支持进程内 TypeScript 扩展，因此 npm 包把 ts/src/pi.ts 编译成 dist/pi.js，再把这个文件写入 .pi/settings.json。

本仓库只有这一份 Pi 扩展源码。早期独立的 adapters/pi/ 已删除，避免实验 代码和 npm 正式代码继续产生不同结果。

Pi 第一次读取项目级设置时会询问信任。无人值守的临时测试使用：

pi --approve -p "your task"

Pi 的路径知识只会被 read、edit、write 文件工具触发。通过 bash 读取 文件不会触发。

条目字段

---
paths:
  - "src/api/**"
triggers:
  - "deploy"
mode: full
description: API 发布检查
reinject_turns: 30
---

这里写发给 Agent 的具体规则。

| 字段 | 作用 | | --- | --- | | paths | 文件工具访问匹配路径后发送 | | triggers | 用户消息包含关键词时发送，不区分大小写 | | mode | full 发送正文；index 只发送说明和文件位置 | | description | 条目短说明，mode: index 时必须清楚 | | reinject_turns | 这条知识再次发送前至少间隔多少回合 |

正文支持两种特殊写法：

• @relative/file.md 在发送时引入另一个文件，最多三层；代码块内不展开。
• !`command` 插入命令输出。默认关闭，必须在 .onecontext.json 中 设置 "allowShellExecution": true。

常用命令

| 命令 | 用途 | | --- | --- | | 1context init | 创建项目文件并连接检测到的宿主 | | 1context install --claude\|--codex\|--pi | 单独连接一个宿主 | | 1context status | 显示项目、Wiki、条目和验证状态 | | 1context gc | 报告从未使用或需要复查的条目，不删除文件 | | 1context compile --target claude-rules\|agents-md | 生成静态宿主文件 | | 1context extract | 从 Claude Code、Codex 或 Pi 会话中提出候选知识 | | 1context gate | 用 Claude Code、Codex 或 Pi 比较有无候选知识的结果 | | 1context promote | 把已通过 gate 的候选移入正式 Wiki | | 1context analyze | 读取三种宿主的会话，判断已发送知识是否影响任务 | | 1context dream | 选择宿主和模型，在副本中整理重复、冲突和可能过期的条目 |

正式知识流程是：

extract → wiki/candidates/ → gate → promote → analyze → gc

wiki/candidates/ 中的文件不会发送给 Agent。

extract、gate、analyze 和 dream 都支持 --harness claude|codex|pi 和 --model <model>。extract 和 analyze 另有 --session-host，用于说明被读取的会话来自哪个宿主。

测试未发布的包

维护者先生成 tarball：

cd ts
npm pack

接收 tarball 的成员安装后，在临时项目测试：

npm install -g ./1context-0.0.3.tgz
cd your-project
1context init
1context status

npm pack 会先构建 TypeScript。npm publish 会先运行完整测试。使用 1context --version 可以确认当前 shell 实际找到的版本。