Metadata-Version: 2.4
Name: continuity-plane
Version: 0.1.0a11
Summary: Durable task state, bounded context, evidence, and collaboration control for long-running AI-assisted work
Author: Continuity Plane contributors
License-Expression: Apache-2.0
Project-URL: Documentation, https://github.com/skyhua0224/continuity-plane#readme
Project-URL: Issues, https://github.com/skyhua0224/continuity-plane/issues
Project-URL: Source, https://github.com/skyhua0224/continuity-plane
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
License-File: THIRD_PARTY_NOTICES.md
Requires-Dist: PyYAML<7,>=6.0.3
Requires-Dist: jsonschema<5,>=4.25.1
Provides-Extra: postgres
Requires-Dist: psycopg[binary]<4,>=3.3.4; extra == "postgres"
Provides-Extra: dev
Requires-Dist: build<2,>=1.3; extra == "dev"
Requires-Dist: psycopg[binary]<4,>=3.3.4; extra == "dev"
Requires-Dist: ruff<1,>=0.12; extra == "dev"
Dynamic: license-file

# Continuity Plane

[![Managed with Continuity Plane](docs/assets/managed-with-continuity-plane.svg)](https://github.com/skyhua0224/continuity-plane)

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

[English README](README.en.md)

## 安装

先安装一份 CLI：

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

### Codex 插件（可选）

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

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

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

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

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

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

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

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

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

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

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

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

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

### 单项目

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

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

### 一个 CLI 管理多个项目

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

```bash
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，不要求团队部署服务。

```bash
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` 是人类可读名称。详见[完整安装、使用与模式切换](USAGE.md)。

## 它解决哪些问题

| 场景 | 痛点 | 详情 |
|---|---|---|
| 压缩与长 Session | 刚刚还在修测试，压缩后却重答旧问题，甚至把做完的工作重新做一遍 | [场景详情](docs/use-cases.md#压缩后像换了一个人) |
| 多 Session 与部署竞态 | 两边都以为自己可以部署，直到 main、CI 和环境互相覆盖才发现冲突 | [场景详情](docs/use-cases.md#同一仓库的多个-session-会互相踩踏) |
| 多人和多 Agent | 别人已经在本地做完的东西不可见，协作者只能重复实现、重复查资料 | [场景详情](docs/use-cases.md#多人和多-agent-不知道别人已经做了什么) |
| Idea 与任务切换 | 一句临时想法让 Agent 离开主线，回来时找不到原任务的落点 | [场景详情](docs/use-cases.md#临时-idea-很容易把主线带跑) |
| 大型项目 | 几百个模块和跨仓依赖堆在一起，人和 AI 都不知道改动会影响哪里 | [场景详情](docs/use-cases.md#大型项目里人和-ai-都不知道哪里是哪里) |
| Memory、Skill、文档漂移 | 旧路径、旧决定和旧规则在压缩后重新冒出来 | [场景详情](docs/use-cases.md#memoryskill-和文档会漂移) |

## 已测结果

| 场景 | 结果 | 详情 |
|---|---|---|
| 压缩恢复 | input tokens `-40.25%`；近上限历史 `-95.06%`；quality `3/3` | [压缩实测](docs/benchmarks.md#压缩与恢复) |
| 代码检索 | input `-50.02%`；tool calls `-57.89%`；wall time `-27.41%`；quality `3/3` | [检索实测](docs/benchmarks.md#代码检索) |
| Skill 装载 | source bytes `-96.54%`；quality `3/3` | [Skill 实测](docs/benchmarks.md#skill-装载) |
| 多 Session 协调 | duplicate tool calls `-55.88%`；parallel wall time `-22.65%` | [协作实测](docs/benchmarks.md#多-session-协作) |
| 一致性 | 强一致性实验门 `10/10`；双 Session `1000/1000`；authority violation `0` | [一致性实测](docs/benchmarks.md#一致性与限制) |
| 大型项目视图 | 2,000 nodes / 5,000 edges；scale p95 `187.459764 ms` | [图形视图](docs/project-views.md) |

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


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

## 架构概览

```text
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 的目标项目目录执行：

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

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

## 安装模式

| 模式 | 外部服务 | 适用场景 | 详情 |
|---|---|---|---|
| `local-embedded` | 无 | 个人项目、离线开发、本机多 Session | [配置](docs/configuration.md) |
| `forge-coordinated` | 已有 Git forge | 普通开源团队协作 | [配置](docs/configuration.md#profiles) |
| 个人 PostgreSQL | 本地或私有 PostgreSQL | SQL 检查、备份、本地 worker | [配置](docs/configuration.md#profiles) |
| 个人 Docmost | Docmost + connector | 图表、审批、历史观察 | [图形化产品](docs/visual-products.md) |
| `shared-strong` | 显式 State MCP 服务 | 跨设备唯一 claim、lease 和 CAS | [配置](docs/configuration.md#profiles) |

默认路径是 `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。

## 文档

- [完整使用教程](USAGE.md)
- [alpha.11 完整变更与升级说明](CHANGELOG.md#010-alpha11)
- [架构说明](docs/architecture.md)
- [配置说明](docs/configuration.md)
- [Python API](docs/api.md)
- [实测方法](docs/benchmarks.md)
- [使用场景](docs/use-cases.md)
- [大型项目视图](docs/project-views.md)
- [Docmost 与 Obsidian 图形化产品计划](docs/visual-products.md)
- [English README](README.en.md)
- [贡献指南](CONTRIBUTING.md)
- [安全策略](SECURITY.md)

## Release 与许可证

当前 alpha 已发布到 [PyPI](https://pypi.org/project/continuity-plane/0.1.0a11/) 和
[GitHub Releases](https://github.com/skyhua0224/continuity-plane/releases)。GitHub
Release 同时提供核心 wheel、source archive、Codex plugin marketplace 和 SHA256SUMS；
详见 [发布说明](CHANGELOG.md)。

Continuity Plane 使用 [Apache-2.0](LICENSE)。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 部署仍在后续计划中。
