内容
<div align="center">
#
### 人工智能上下文连续性引擎
**适用于长时间智能体会话的本地私有上下文切换工具。**
警告您有关上下文腐烂，保留决策和证据，并为下一个会话或模型提供忠实的7桶简报。
<br/>
<kbd>MCP stdio</kbd> · <kbd>SQLite Ledger</kbd> · <kbd>账户模式</kbd> · <kbd>Claude 代码</kbd> · <kbd>Codex</kbd> · <kbd>无遥测</kbd> · <kbd>节点 ≥ 22</kbd>
<br/>
`Cairn resume` · `Cairn 切换` · `Cairn 帮助`
**v1.4.0** · MIT 许可证
</div>
---
##
### 问题
长时间的AI会话会丢失最昂贵的信息：架构决策、理由、废弃的路径、精确的ID、代码和配置块。
Cairn在本地保存**记忆**，以便在智能体之间进行：无需后端，无需云。
| 没有 Cairn | 有 Cairn |
|---|---|
| 🌫️ 上下文充满，质量下降而不被察觉 | 🟢🟡🔴 区域指示器，相对于活动窗口 |
| 🧹 主机压缩丢失细节 | 📋 7桶简报：决策、证据、约束 |
| ✂️ 代码/ID 被转述 | 🔒 原样冻结，字节精确恢复 |
| 🔌 会话/模型切换很脆弱 | 🗄️ 持久决策/证据账本 |
| 🕵️ 内部工作应保持本地 | 🏠 stdio + SQLite，无遥测，无出口 |
---
##
### 工作原理
```mermaid
flowchart LR
host["主机代理<br/>Claude 代码或 Codex"]
handoff["切换"]
fv["原样冻结<br/>代码，ID，值"]
ledger[("本地 SQLite 账本")]
next["下一个会话<br/>或另一个模型"]
server["cairn stdio 服务器 (MCP)"]
cs["上下文状态<br/>绿色 / 黄色 / 红色"]
host -->|"主机产生的简报"| handoff --> fv --> ledger
ledger -->|"决策日志视图=当前"| next
host -->|"MCP 工具"| server --> cs
```
默认路径是**账户模式**：主机代理在您的Claude或Codex会话中编写切换简报。
Cairn只**存储和验证**它：**无**服务器端模型调用，**无**API密钥，**无**通过Cairn的出口。
---
##
### 30秒了解
```bash
git clone <仓库网址> cairn
cd cairn
npm install
node dist/server.js install # 检测 Claude 代码 + Codex，连接两者
```
然后在聊天中说出：
| 说… | …智能体执行 |
|---|---|
| **`Cairn resume`** | 重新注入账本（`决策日志视图=当前`）并继续以其为真实来源，**无需**重新读取仓库 |
| **`Cairn 切换`** | 从对话中创建7桶简报并将其持久化到账本中 |
| **`Cairn 帮助`** | 所有触发器、工具和 shell 命令的简要参考表 |
撤销：`node dist/server.js uninstall`
---
##
### 核心原则
| 原则 | 含义 |
|---|---|
| **MCP核心，无浏览器捕获** | 对话来自主机代理：无DOM抓取，无UI适配器。 |
| **保真度高于成本** | 保真度是首要的；成本仅在两个同样忠实的候选者之间作为替补。 |
| **表面相对区域** | 百分比相对于`min(模型最大值，表面上限，用户覆盖)`，而非模型最大值。 |
| **尊重主机生态系统** | 仅选择活动主机会话可达的内容用于实时使用。 |
| **原样优于压缩** | 在保真度下限以下，Cairn宁愿交付完整而非简短错误的内容。 |
| **默认本地私有** | SQLite文件，stdio进程，无遥测，无凭证在标准操作中。 |
> 绑定架构在 [docs/adr/ADR-cairn.md](docs/adr/ADR-cairn.md) 中有文档。
---
##
### 四个MCP工具
| 工具 | 任务 | 典型时刻 |
|---|---|---|
| `主机状态` | 检测已安装的主机CLI，登录（尽力而为），和活动模型。 | 会话开始时 |
| `决策日志` | 从账本中重新注入已接受和开放的决策。 | 开始/恢复 |
| `上下文状态` | 计算相对于活动窗口的区域。 | 持续进行中，长会话期间 |
| `切换` | 持久化主机产生的7桶简报，并具有原样保护。 | 在`/clear`，压缩，模型切换之前 |
区域故意简单：
| 区域 | 阈值 | 含义 |
|:--:|:--:|---|
| 🟢 **绿色** | `< 40 %` | 正常工作 |
| 🟡 **黄色** | `40–70 %` | 在下一个自然中断时计划切换 |
| 🔴 **红色** | `≥ 70 %` | 优先切换，选择最强的可达模型 |
---
##
### 7桶简报
每次切换都遵循相同的格式：
```text
决策 · 证据 · 开放问题 · 约束 · 原样 · 下一步 · 废弃
```
强制值，ID，路径，代码块和内联代码作为`requiredVerbatim` / `exactSpans`传递。
Cairn用`[[CAIRN-HOLD-n]]`掩盖它们，然后进行可选压缩，并在之后**字节精确**恢复。
新的切换**取代**前一个，因此账本保持精简，并且`决策日志视图=当前`仅携带最新的简报。
---
##
### Codex 环境区域和 Shell 命令
Codex 没有状态栏 API。Cairn 读取本地滚动文件 **只读** 并在终端或窗口标题中环境显示区域：
```bash
cairn status # 一行，例如 🟢 21% ctx · gpt-5.5
cairn window # 实时区域条作为第二个窗格（Windows Terminal / tmux / iTerm2）
cairn tab # 终端/选项卡标题中的区域 · 'cairn stop' 结束它
cairn list # 最近活动的 Codex 会话（使用 --session <uuid> 固定）
```
详细信息和 tmux/zellij 代码片段： [integration/codex/ambient-zone.md](integration/codex/ambient-zone.md).
---
##
### 安装
<details open>
<summary><b>路径 A：自我安装（推荐）</b></summary>
<br/>
尽力检测 Claude 代码和 Codex 并安装适合您系统的必要组件。
现有的配置通过标记块或合并的 JSON 部分进行**增强**，不会重写外部项目文件。
```bash
npm install
node dist/server.js install
```
</details>
<details>
<summary><b>路径 B：Claude 代码插件</b></summary>
<br/>
```text
/plugin marketplace add /ABSOLUTE/PATH/cairn
/plugin install cairn@cairn
```
插件包含MCP服务器、技能和钩子。对于完整的状态栏，自我安装仍然是最简单的路径。
</details>
<details>
<summary><b>路径 C：手动（Claude 代码/Codex）</b></summary>
<br/>
**Claude 代码：
```bash
claude mcp add cairn -- node /ABSOLUTE/PATH/cairn/dist/server.js
```
或作为 `.mcp.json`:
```json
{
"mcpServers": {
"cairn": {
"type": "stdio",
"command": "node",
"args": ["/ABSOLUTE/PATH/cairn/dist/server.js"],
"env": { "CAIRN_DB": "${HOME}/.cairn/cairn.sqlite" }
}
}
}
```
**Codex** 在 `~/.codex/config.toml` 中:
```toml
[mcp_servers.cairn]
command = "node"
args = ["/ABSOLUTE/PATH/cairn/dist/server.js"]
startup_timeout_sec = 30
tool_timeout_sec = 60
```
然后将 `integration/codex/AGENTS.cairn.md` 追加到 `~/.codex/AGENTS.md` 并将技能放入 `skills/` 目录中，放入 `~/.agents/skills/` 或 `~/.claude/skills/`。现成的代码片段在 [integration/](integration/) 中。
</details>
---
##
### 配置
> **语言：** Cairn 默认使用英语。德语可通过安装时使用 `--lang de` 标志选择（出现交互式提示 `语言/Sprache？[en]/de`），并通过 `CAIRN_LANG=en|de` 环境变量在运行时选择（环境变量覆盖安装选择）。
| 变量 | 效果 | 默认值 |
|---|---|---|
| `CAIRN_DB` | SQLite 账本路径 | `~/.cairn/cairn.sqlite` |
| `CAIRN_ENABLE_MODES` | 附加模式：`sampling`，`bridge`，`api` | 仅 `account` |
| `CAIRN_BRIDGE` | 桥接目标：`claude` 或 `codex` | 空 |
| `CAIRN_ENDPOINT_<NAME>` | 显式 API/组织端点 `provider|baseUrl|apiKeyEnv|model` | 空 |
| `CAIRN_CODEX_SESSIONS` | 替代 Codex 会话目录 | `~/.codex/sessions` |
| `CAIRN_CODEX_SESSION` | 通过 UUID/路径子字符串固定 Codex 滚动 | 最新匹配会话 |
| `CAIRN_LANG` | 运行时区域：`en` 或 `de`（覆盖安装选择） | `en` |
### 冷凝模式
| 模式 | 激活 | 通过 Cairn 出口？ | 用途 |
|---|---|:--:|---|
| `account` | 默认 | **否** | 主机代理在会话中生成简报；Cairn 仅持久化它。 |
| `bridge` | `CAIRN_ENABLE_MODES=bridge` | 是，通过另一个 CLI 本地 | 通过其他登录帐户进行冷凝。 |
| `sampling` | `CAIRN_ENABLE_MODES=sampling` | 客户端相关 | MCP 采样，当主机支持时。 |
| `api` | `CAIRN_ENABLE_MODES=api` + 端点 | 是 | 具有显式凭证的无头组织运行。 |
在没有显式配置的情况下，Cairn **拒绝** 所有非帐户路径。
---
##
### 数据和隐私
- 账本：`~/.cairn/cairn.sqlite`（或 `CAIRN_DB`）
- 追加：决策 **取代** 而不是删除
- `stdout` 保留用于 MCP
- 无后端，无遥测，无云同步
- 默认帐户模式需要 **无** API 密钥，并且在服务器上 **无** 模型调用
---
##
### 开发
```bash
npm run typecheck # tsc --noEmit，严格
npm test # vitest
npm run build # tsc -> dist/
npm run dev # 本地 MCP stdio 服务器
```
---
##
### 项目结构
```text
src/
server.ts MCP 服务器 + CLI 调度
core/ 模型配置文件，区域，提供程序，原样
store/ SQLite 账本（追加）
tools/ MCP 工具实现
surface/ Claude/Codex 表面逻辑
install/ 自我安装 + shell 快捷方式
skills/ 代理技能（cairn · resume · handoff · help）
integration/ 手动 Claude/Codex 配置 + 代码片段
docs/adr/ 绑定架构决策
```
---
##
### 状态 v1.4.0
- 具有四个工具和 SQLite 决策/证据账本的 MCP 核心
- 默认账户模式（无出口）
- Claude 代码状态栏和钩子 · Codex 环境区域通过滚动读取器
- 命名触发技能：`Cairn resume` · `Cairn 切换` · `Cairn 帮助`
- 精简账本：新的切换取代前一个简报
- 严格的 TypeScript + Vitest
- 英语优先，可选择德语用于命令（`cairn install --lang de`）和运行时输出（`CAIRN_LANG=de`）
**已知限制：** 区域边界是**暂定的**；Codex 滚动解析依赖于内部的、未版本化的 Codex 格式；登录检测是尽力而为的。
---
##
### 许可证
[MIT](LICENSE) 2026 CheswickDEV
