Continuity Plane

Continuity Plane 是面向长期 AI 辅助软件工作的 provider-neutral 控制面。它把任务、 决定、约束、证据、checkpoint、上下文组合和协作状态放在聊天窗口之外，支持压缩、 任务切换、进程崩溃和多人交接后的确定性恢复。

English README

安装

先安装一份 CLI：

python -m pip install continuity-plane==0.1.0a11

仓库当前同时包含未发布的 alpha12 candidate（PR3/PR4 修复）。它只用于本机或团队 验证，不替代 PyPI 上的 alpha11；candidate 应从本地 wheel 和插件 marketplace 安装。

Codex 插件（可选）

核心包不依赖插件。默认 continuity-plane plugin 是轻量 core，只提供有界恢复和 checkpoint lifecycle，不注册 State MCP 工具，也不阻断普通开发命令：

codex plugin marketplace add skyhua0224/continuity-plane --ref v0.1.0-alpha.11
codex plugin add continuity-plane@continuity-plane

大型仓库需要有界 current-worktree 检索时，可单独安装 search plugin：

codex plugin add continuity-plane-search@continuity-plane

符号、类或函数定位可以建立增量索引：

continuity context index --root .
continuity context lookup --root . --query "build_runtime"

索引缓存默认在项目外，返回路径、行号、符号和文件 hash；新 Session 或其他 AI 可复用， 源码变化后只重解析变化文件。

只有明确需要在 Codex 中调用 resume、claim、checkpoint 或原子 Work transition 时， 才安装 advanced State plugin：

codex plugin add continuity-plane-state@continuity-plane

安装 search plugin 后，Codex 会看到单工具 continuity_context_lookup MCP；不支持 MCP 的 其他 AI 使用上面的 CLI，二者共享按仓库隔离的用户缓存。State plugin 不参与代码检索。

安装后新建或恢复一个 Session。确认插件已真实运行：

continuity doctor --root . --codex-home ~/.codex

codex_plugin.status=active 表示配置、MCP policy、hook trust 和真实 SessionStart 观测均已通过。普通问题直接使用 lifecycle 提供的有界恢复信息，不调用 State 工具；只有 显式诊断 State 时才 inspect，写入 State 前才 resume。权威状态仍由本地 CLI/State MCP 管理。

单项目

适合希望每个仓库独立保存状态和版本的个人项目。

continuity init --root . --project-id my-project --display-name "My Project"

一个 CLI 管理多个项目

适合在同一台机器上维护多个仓库；每个项目拥有独立的 .continuity/ 和 SQLite。

continuity init --root /path/to/project-a --project-id project-a --display-name "Project A"
continuity init --root /path/to/project-b --project-id project-b --display-name "Project B"

协作项目个人使用

适合加入团队仓库但只想先管理自己的本地 Session，不要求团队部署服务。

continuity init --root /path/to/team-repo --project-id team-project --display-name "Team Project"

团队共同使用

适合需要共享 Work、claim、PR/CI 和部署状态的团队。先完成本地初始化，再按项目条件 启用 forge-coordinated 或 shared-strong；默认安装仍不要求 PostgreSQL 或 Docmost。

常用参数：--root 指向目标仓库，--project-id 是稳定的小写标识， --display-name 是人类可读名称。详见完整安装、使用与模式切换。

它解决哪些问题

已测结果

这些是匹配任务和当前 fixture 的场景级结果，不能合成为所有用户的统一节省率。 用户 token、窗口有效利用率和两次压缩之间的有效工作量，按 accepted Work 归一化， 并在 host trace 可见时计量。完整方法和限制。

代码索引是候选定位层；它不替代当前源码、测试或 Typed State 的权威验证。

架构概览

Agent / IDE / CI / 人类控制台
              |
              v
       Execution Packet
              |
     +--------+---------+
     |                  |
 Typed State        Evidence index
 revision + CAS     hash + validity
     |                  |
     +--------+---------+
              |
      append-only events
              |
      checkpoint + replay canary
              |
          SQLite 默认

Memory、检索系统、代码图和 reviewer 只能提供候选信息；active task、完成状态和外部 副作用必须经过 State MCP 的 authorization、expected revision/CAS 和 validator。

快速开始

要求 Python 3.11 或更高版本。在已安装 CLI 的目标项目目录执行：

continuity verify --root .
continuity doctor --root .
continuity state show --root .

初始化会创建 .continuity/、SQLite 状态库以及项目自己的 MASTER.md、STATUS.md 和英文模板。项目应自行决定 project_id 与 display_name。

安装模式

默认路径是 local-embedded。PostgreSQL、Docmost 和 shared-strong 都是可选增强。

权威边界

• Typed State：当前任务、owner、revision、决定、约束和门禁；
• Event Log：append-only 状态变化、supersedes 和 hash chain；
• Checkpoint：压缩、切换、交接和崩溃后的恢复点；
• Evidence：当前源码、标准、官方文档和测试的 provenance；
• MASTER.md：项目级治理意图；STATUS.md：当前恢复路由；
• Docmost：可选的人类控制台，动作受 State MCP 约束；
• Obsidian：生成的只读视图；
• SQLite：默认本地 authority；PostgreSQL：显式选择的 adapter。

文档

• 完整使用教程
• alpha.11 完整变更与升级说明
• 架构说明
• 配置说明
• Python API
• 实测方法
• 使用场景
• 大型项目视图
• Docmost 与 Obsidian 图形化产品计划
• English README
• 贡献指南
• 安全策略

Release 与许可证

当前 alpha 已发布到 PyPI 和 GitHub Releases。GitHub Release 同时提供核心 wheel、source archive、Codex plugin marketplace 和 SHA256SUMS； 详见 发布说明。

Continuity Plane 使用 Apache-2.0。badge、README 署名、应用 UI 标签和 telemetry 都是可选的，法律归属以 LICENSE 和 NOTICE 为准。

当前状态

Linux x86_64、macOS arm64 和 Windows AMD64 已完成安装、verify 和卸载；本地 state bundle 的 export/import/rollback 已可用。跨 adapter 一键 profile switch、 完整 Docmost connector、Obsidian Canvas/Bases 和 shared-strong 部署仍在后续计划中。