内容
# Ambient Project Layer
中文 | [English](README_EN.md)
让 Codex 在工作过程中安静地整理项目进展，并将任务、Bug、决定、风险和里程碑同步到 Plane。
[Plane](https://plane.so/open-source) 是一款采用 AGPL-3.0 许可证的开源项目管理平台，既可以免费自行部署 Community Edition，也提供免费的云端方案。其自托管 Community Edition 不限制用户数，云端 Free 方案目前支持最多 12 名用户，因此非常适合个人开发者、一人公司（OPC）和小团队使用；具体额度以 [Plane 官方定价页](https://plane.so/pricing) 为准。
[](LICENSE)
[](CHANGELOG.md)
Ambient Project Layer 是一个 Codex 插件。它从当前工作回合中捕获真正有项目价值的事件，先可靠写入本地 SQLite Outbox，再异步同步到 Plane。你可以继续在 Plane 中做完整的项目管理，也可以在 Codex 内通过轻量 Panel 查看最近工作项并修改状态。
开发工作已经在 Codex 中发生，但任务、决定和风险往往要靠人再次整理到项目管理工具中。Ambient Project Layer 把这段重复劳动压缩成一个安静、可审查的后台流程。
## 产品界面
Panel 默认展示最多 5 个相关工作项，支持按 Backlog、Todo、In Progress 和 Done 筛选，并可通过状态菜单或拖拽更新状态。完整创建、编辑、归档和项目管理仍在 Plane 中完成。
Panel 的 UI 直接沿用 Plane 开源产品的视觉风格，包括配色、状态标签、卡片层级和交互方式，让用户在 Codex 与 Plane 之间获得一致的使用体验。该界面由本项目实现，并非 Plane 官方组件。
## 主要能力
- 自动识别任务、Bug、决定、想法、风险、里程碑、计划、进展和完成事件。
- 使用本地 SQLite Outbox 保证事件先落盘，再异步同步到 Plane。
- 首次进入项目目录时列出真实 Plane 项目，由用户明确选择绑定目标。
- 在 Codex 内提供轻量 Inline Panel，查看相关工作项、同步状态并跳转 Plane。
- 不保存完整对话、源码、终端输出或 Plane API Key。
- 每个平台的 Release 包自带 Node.js 22.22.1，无需用户另装 Node、pnpm 或 bun。
## 支持平台
从 [GitHub Releases](https://github.com/Bene-2020/plane-codex-mcp/releases/latest) 下载与机器匹配的压缩包：
| Release 目标 | 系统 | 架构 |
| --- | --- | --- |
| `darwin-arm64` | macOS | Apple Silicon |
| `darwin-x64` | macOS | Intel |
| `linux-x64` | Linux | x86_64 |
| `linux-arm64` | Linux | ARM64 / aarch64 |
| `win32-x64` | Windows | x86_64 |
不确定架构时，可在 macOS/Linux 运行 `uname -m`：`arm64` 或 `aarch64` 选择 ARM64，`x86_64` 选择 x64。当前不提供 Windows ARM64 安装包。
## 安装
### 1. 准备 Plane
你需要：
- 一个可访问的 Plane Cloud 或自托管实例；
- Workspace slug，例如 `https://app.plane.so/my-team/` 中的 `my-team`；
- 一个有目标项目读写权限的 Plane Personal Access Token。
Plane 官方文档说明了 [API Key 的创建位置与使用方式](https://developers.plane.so/api-reference/introduction)。请把 API Key 当作密码保管。
### 2. 安装对应平台的插件包
下载形如 `ambient-project-layer-v0.1.4-<target>.zip` 的资产，解压到不会随意移动的目录。下文用 `<RELEASE_DIR>` 表示解压后的绝对路径；该目录应直接包含 `.agents/plugins/marketplace.json`。
```bash
codex plugin marketplace add "<RELEASE_DIR>"
codex plugin add ambient-project-layer@ambient
codex plugin list
```
Codex 官方将插件定义为可安装的技能、MCP Server 和可选 UI 组合；本地开发或独立分发的插件通过 local marketplace 安装。可参考 [Build plugins](https://learn.chatgpt.com/docs/build-plugins)。
安装后，打开 Codex 的 Hook 管理界面，逐一复核并信任当前版本的以下 Hook：
- `SessionStart`
- `UserPromptSubmit`
- `PostToolUse`
- `Stop`
- `SessionEnd`
插件显示 `enabled` 不等于 Hook 已获得信任。安装或升级后如果 Hook 显示 `modified`，需要重新信任。
### 3. 配置 Plane 连接
正式插件不读取仓库或项目目录中的 `.env`。Plane 配置保存在用户级 `~/.codex/config.toml` 中，并由 Codex 启动 `ambient-project` MCP Server 时注入。
先新建一次 Codex task，让 Hook 创建插件数据目录。随后把 MCP 的 `AMBIENT_DB_PATH` 指向同一个 `PLUGIN_DATA/ambient.sqlite`：
- macOS/Linux：`$HOME/.codex/plugins/data/ambient-project-layer-ambient/ambient.sqlite`
- Windows：`%USERPROFILE%\.codex\plugins\data\ambient-project-layer-ambient\ambient.sqlite`
macOS/Linux 示例：
```bash
codex mcp add ambient-project \
--env "AMBIENT_DB_PATH=$HOME/.codex/plugins/data/ambient-project-layer-ambient/ambient.sqlite" \
--env "PLANE_MODE=sdk" \
--env "PLANE_TYPE_MODE=default" \
--env "PLANE_BASE_URL=https://api.plane.so" \
--env "PLANE_WORKSPACE_SLUG=replace-with-your-workspace" \
--env "PLANE_API_KEY=replace-in-config-toml" \
-- "<RELEASE_DIR>/plugins/ambient-project-layer/runtime/bin/ambient-node" \
"<RELEASE_DIR>/plugins/ambient-project-layer/runtime/mcp/index.js"
```
Windows PowerShell 示例：
```powershell
codex mcp add ambient-project `
--env "AMBIENT_DB_PATH=$env:USERPROFILE\.codex\plugins\data\ambient-project-layer-ambient\ambient.sqlite" `
--env "PLANE_MODE=sdk" `
--env "PLANE_TYPE_MODE=default" `
--env "PLANE_BASE_URL=https://api.plane.so" `
--env "PLANE_WORKSPACE_SLUG=replace-with-your-workspace" `
--env "PLANE_API_KEY=replace-in-config-toml" `
-- "<RELEASE_DIR>\plugins\ambient-project-layer\runtime\bin\ambient-node.cmd" `
"<RELEASE_DIR>\plugins\ambient-project-layer\runtime\mcp\index.js"
```
然后编辑 `~/.codex/config.toml`，仅在 `[mcp_servers.ambient-project.env]` 中把占位值替换为真实 Workspace slug 和 API Key。不要把真实 Key 放进上面的命令、仓库、Issue、日志或截图中，以免进入 shell history 或公开记录。
`PLANE_TYPE_MODE` 控制工作项分类策略：
- `default`（默认，适合 Plane Free）：不访问付费的 Work Item Types 目录，创建时使用 Plane 默认类型，并把语义分类写入标题前缀，例如 `[Bug]-登录失败`、`[Decision]-采用 SQLite`。
- `custom`（适合 Plane Pro / Business）：为 Task、Bug、Decision、Idea、Risk、Milestone 解析或创建对应的自定义 Work Item Type。类型目录只在创建工作项且映射缺失时读取，普通刷新、计数和状态更新不会访问它。
修改 `PLANE_TYPE_MODE` 后必须完全重启 Codex。不同模式不会自动重写已有工作项。
升级到 v0.1.4 后，后台同步 Worker 会为每个终态失败批次提供一次自动恢复机会，包括升级前遗留的历史失败。多个 MCP Worker 通过 SQLite 共享同一节流队列：Plane 请求默认间隔 2 秒，自动恢复批次至少间隔 10 秒；遇到 429 时按服务端重置时间暂停全局队列，限流等待不消耗业务重试次数。恢复仍失败的批次会继续保持终态；之后可在 Panel 中人工 Retry、Correct 或 Dead-letter。
自托管 Plane 用户还需要把 `PLANE_BASE_URL` 换成实例的 API Base URL。
在本机检查 MCP 配置：
```bash
codex mcp get ambient-project
```
该命令的输出可能包含 Plane API Key。不要把输出复制到 Issue、日志、聊天或截图中；对外排查问题时只提供已经移除凭据的内容。
完成后完全退出并重新启动 Codex，再新建一个 task。已经运行的 MCP 进程不会自动读取修改后的配置。
## 第一次使用
1. 在一个真实项目目录中新建 Codex task。
2. Ambient Project Layer 会列出当前 Plane Workspace 中的项目并询问绑定目标。
3. 明确选择一个项目；插件不会根据目录名或 Git remote 自动猜测。
4. 继续正常使用 Codex。发生有意义的项目变化时，事件会先进入本地 Outbox，再同步到 Plane。
5. 对 Codex 说“打开项目面板”，即可查看相关工作项和同步状态。
如果暂时不想选择，可以回复“稍后再说”；本次 task 不会重复询问。如果明确要求某个目录以后不再询问，插件会只在本地保存这一偏好，之后也可以要求恢复绑定。
Ambient Plane 绑定只使用宿主工具 `mcp__ambient_project__list_projects` 的本轮真实返回；用户明确请求 Codex Projects 时，`codex_app__list_projects` 仍可正常使用，但不能作为 Plane 绑定证据。绑定提示中的每个 bullet 只接受精确的 `identifier | name` 成对格式（允许字段分别使用 Markdown 粗体、下划线粗体或行内代码），不会接受前后缀、额外字段、`path`、`projectKind`、`hostId` 或本地项目名。
## 数据、权限与隐私
Ambient Project Layer 的数据边界如下：
| 数据 | 保存位置 | 说明 |
| --- | --- | --- |
| 工作项和项目状态 | Plane | 用户可见项目数据的最终来源 |
| 项目绑定、Outbox、精简缓存和 Hook 审计 | 本地 SQLite | 默认位于插件的 `PLUGIN_DATA` 目录 |
| Plane API Key | Codex 用户级配置与 MCP 进程内存 | 不写入 SQLite、Panel 或 Hook 输出 |
| Panel 临时令牌 | 当前 MCP 进程内存 | 每次进程启动重新生成 |
插件不会把完整 Codex transcript、源码、终端输出、附件或 API Key 保存到本地数据库，也不会把 Plane API Key 发送到浏览器 Panel。运行时对外只需要访问你配置的 Plane API。
插件需要 Plane 项目读写权限，用于读取项目与工作项、创建捕获到的工作项、写入进展评论和更新状态。它不提供自动删除、跨项目移动或人员分配工具。
## 升级
1. 从 Releases 下载同一平台的新版本，用新内容替换原来的稳定 Release 目录。
2. 从同一个 local marketplace 重新安装插件：
```bash
codex plugin add ambient-project-layer@ambient
```
3. 确认 `ambient-project` MCP 仍指向稳定的 Release 目录和原有 SQLite 文件。
4. 在 Hook 管理界面重新复核并信任五个 Hook。
5. 完全退出并重启 Codex，再用新 task 验证绑定、同步和 Panel。
升级时不要删除或切换已有 SQLite 文件，否则本地绑定、Outbox 和来源引用不会自动迁移到新文件。
## 卸载
```bash
codex plugin remove ambient-project-layer@ambient
codex plugin marketplace remove ambient
codex mcp remove ambient-project
```
这些命令不会替你删除 Plane 中已经同步的工作项。若确定不再需要本地绑定和 Outbox，可在备份后手动删除对应的 `ambient.sqlite`；保留数据库不会影响 Plane 数据。
## 常见问题
### 插件已启用，但新 task 没有项目引导
先检查五个 Hook 是否已被当前版本信任。若显示未信任或 `modified`，重新信任并新建 task；已错过的 `SessionStart` 不会在旧 task 中补跑。
### `mcp__ambient_project__list_projects` 返回认证错误或没有项目
检查 `PLANE_MODE=sdk`、Base URL、Workspace slug、API Key 以及 Token 对目标 Workspace 的权限。修改配置后必须完全重启 Codex。
### MCP 工具正常，但 Panel 暂时不可用
重新调用“打开项目面板”。MCP 进程重启后，旧 Panel 的临时会话会失效；新调用会创建新的 Panel 会话。
### 工作项显示“待同步”
本地事件已经落盘，但 Plane 同步失败。检查网络、API Key 和 Plane 服务状态；恢复后 Outbox 会继续处理，不要通过删除 SQLite 来“重试”。
### 项目根目录为什么没有 `.env`？
正式插件使用 `~/.codex/config.toml`，不需要项目级 `.env`。只有从源码运行独立开发入口时才复制 `.env.example` 为 `.env`。
### 它会上传我的代码或完整对话吗？
不会。插件只记录经过归纳的项目事件、短来源摘录和同步所需元数据；不保存完整 transcript、源码或终端输出。
## 从源码构建
开发环境需要 Node.js 22、Corepack 和 Git。
```bash
git clone https://github.com/Bene-2020/plane-codex-mcp.git
cd plane-codex-mcp
corepack enable pnpm
pnpm install --frozen-lockfile
cp .env.example .env
pnpm test
pnpm lint
pnpm build
pnpm validate:plugin
pnpm smoke:plugin
```
`.env.example` 默认使用隔离的 `PLANE_MODE=fake`，适合本地测试。连接真实 Plane 时，请只在本地 `.env` 中填写凭据，不要提交 `.env`。
构建全部五个平台的插件目录：
```bash
pnpm run build:packages
pnpm run build:apps
pnpm package:plugin -- --all
node scripts/validate-plugin-runtime.mjs dist/plugins/ambient-project-layer --all
```
产物位于 `dist/plugins/ambient-project-layer/<target>/`。当前机器会真实执行本机架构的 sidecar；其他平台只做结构验证，最终 Release 还应在对应平台的 CI Runner 上完成原生 smoke test。
## 参与项目
- 提交代码前请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。
- 安全问题请按 [SECURITY.md](SECURITY.md) 私下报告，不要公开提交含漏洞细节的 Issue。
- 版本变化记录在 [CHANGELOG.md](CHANGELOG.md)。
- 第三方组件许可见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。
## 许可证
Copyright © 2026 Wenyan Wei。
本项目使用 [MIT License](LICENSE)。
连接信息
猜你喜欢
暂无推荐服务器