内容
<h1 align="center">🚦 代码操作系统适用于 Codex</h1>
<p align="center"><strong>适用于 Codex 项目的开源控制面板：可见进度、可恢复上下文、安全交接和可重用知识。</strong></p>
<p align="center"><strong>独立开源项目。与 OpenAI 无关。</strong></p>
<p align="center">
为 Codex 而建。通过 MCP 连接，保持项目真相在 Git 中，每次交接都可恢复。
</p>
<p align="center">
<a href="https://github.com/herry2059/project-os-for-codex/stargazers"><img src="https://img.shields.io/github/stars/herry2059/project-os-for-codex?style=for-the-badge" alt="GitHub Stars"></a>
<a href="https://github.com/herry2059/project-os-for-codex/forks"><img src="https://img.shields.io/github/forks/herry2059/project-os-for-codex?style=for-the-badge" alt="GitHub Forks"></a>
<a href="https://github.com/herry2059/project-os-for-codex/graphs/contributors"><img src="https://img.shields.io/github/contributors/herry2059/project-os-for-codex?style=for-the-badge" alt="Contributors"></a>
<a href="LICENSE"><img src="https://img.shields.io/github/license/herry2059/project-os-for-codex?style=for-the-badge" alt="Apache-2.0 License"></a>
<a href="https://github.com/herry2059/project-os-for-codex/commits/main"><img src="https://img.shields.io/github/last-commit/herry2059/project-os-for-codex?style=for-the-badge" alt="Last Commit"></a>
</p>
<p align="center">
<a href="#quick-start">🚀 快速开始</a> ·
<a href="docs/CODEX_SETUP.md">🤖 连接 Codex</a> ·
<a href="#key-features">🧭 功能</a> ·
<a href="docs/DEPLOYMENT.md">📦 部署</a> ·
<a href="docs/INTERFACES.md">🔌 接口</a>
</p>
代码操作系统适用于 Codex，旨在解决团队在 AI 协助开发过程中遇到的问题：
- 项目进度隐藏在聊天记录中。
- 下一个 AI 会话不知道从哪里开始。
- 人类无法确定哪些任务已完成、阻塞、风险或等待审查。
- 交接过程痛苦，因为上下文分散在提示、截图、提交和私人笔记中。
- 团队失去信任，因为没有可见的项目轨迹。
代码操作系统适用于 Codex 将这些分散的片段转化为一个工作空间：项目目标、验收标准、Git 记录、进度事件、风险、下一步骤、知识和交接包。
### 从实际交付工作中提炼
该系统并非周末概念，而是从许多实际内部和客户项目中提炼的常见问题，然后通过持续的 Codex 使用完善：上下文丢失、进度不可见、不明确的验收、困难的交接和交付后消失的知识。
下面的匿名 2026 年 7 月维护者快照显示了 **14,570 个 Codex 任务，8.8B 生命周期代币，23 天连胜和 743 个技能使用**。这些数字是维护者实践的证据，而不是存储库用户、下载量、采用率或 14,570 个独立项目。
### 用简单语言解释
将该系统视为 AI 协助开发的项目驾驶舱。
当 AI 帮助您构建项目时，它不仅应该编写代码，还应该留下：
- 它更改了什么；
- 为什么更改；
- 仍需要完成什么；
- 存在哪些风险；
- 下一个人类或 AI 应该首先阅读什么。
该存储库提供了该驾驶舱的结构。它帮助项目成为另一个人或 AI 可以继续的内容，而不是一次聊天记录。
## 连接 Codex
**不要** 给 AI 您的网站用户名和密码。从项目页面创建绑定到一个工作空间和一个项目的短期 AI 凭证，然后在您自己的终端中运行生成的 MCP 命令。
第一个面向生产的切片公开了两个实用的 MCP 工具：
- `project_os_get_context` — 读取启动卡、验收标准、AGENTS 规则、交接包、进度、Git 跟踪和下一步；
- `project_os_append_progress` — 追加一个经过验证、审计、幂等的进度事件、代理报告的验证笔记和一个匹配的项目记录 Git 提交。
凭证在 24 小时或 7 天后过期，可以独立撤销，仅存储为哈希，不能访问成员、密钥、删除、发布或部署。
[遵循 Codex 设置指南 →](docs/CODEX_SETUP.md)
### 设计围绕 Codex 的真实扩展点
- Codex 在工作开始前读取存储库的根 [`AGENTS.md`](AGENTS.md)。
- stdio MCP 服务器在初始化期间返回简洁的工作流指令。
- 工具注释区分只读上下文工具和作用域进度写入工具。
- [`.codex/config.toml.example`](.codex/config.toml.example) 显示了一个项目范围的配置，该配置转发本地环境变量而不提交秘密值。
- 相同的 MCP 配置可由 Codex CLI、Codex IDE 扩展和 ChatGPT 桌面应用程序在同一 Codex 主机上使用。
- 高风险操作保留在 MCP 表面之外，需要人类干预。
参见 OpenAI 的官方 [MCP](https://developers.openai.com/codex/mcp/) 和 [`AGENTS.md`](https://developers.openai.com/codex/guides/agents-md/) 文档。该存储库扩展了 Codex，具有项目上下文和进度记录；它不是 Codex 的分支或替代品。
## 核心循环
1. 使用启动卡创建项目。
2. 定义目标、验收标准、非目标、所有者和下一步。
3. 服务器为启动、进度、问题和交接文件创建本地 Git 支持的项目记录。
4. 人类或 AI 代理发布进度事件。
5. 重要的进度成为项目记录，可以链接到 Git 提交。
6. 仪表板显示状态、健康状况、进度和记录的下一步行动。
7. 交接包让下一个 AI 或人类无需重新阅读整个历史即可继续。
8. 回顾和项目笔记成为下一个项目的可重用知识。
## 主要功能
### 项目启动卡
使用清晰的简介启动每个项目：
- 项目目标；
- 预期结果；
- 验收标准；
- 非目标；
- 当前所有者；
- 下一步。
### 可见的 AI 进度
使用进度事件跟踪项目状态，而不是从聊天记录中猜测：
- 活动/暂停/完成项目状态；
- 进度百分比；
- 所有者；
- 下一步行动；
- 绿色/黄色/红色项目健康状况。
### Git 支持的证据
该系统围绕 Git 作为持久项目记录设计：
- 项目工作区记录；
- Git 文件跟踪；
- 提交友好的进度笔记；
- 审计跟踪，记录更改内容和原因。
### 交接包
生成另一个 AI 或人类可以立即使用的上下文：
- 项目总结；
- 当前状态；
- 重要文件；
- 最近的决定；
- 阻塞项；
- 下一步行动；
- 验收检查清单。
### 知识库和回顾
将完成的项目经验转化为可重用的知识：
- 项目经验教训；
- 交付模式；
- 可重用的提示和检查清单；
- 项目审查笔记；
- 未来的改进想法。
### 适配器友好的开源设计
开源版本将私有基础设施保留在可替换的边界后面：
- Git 数据库/Git 服务适配器；
- AI 提供商适配器；
- 知识库适配器；
- 部署和反向代理边界；
- 用于简单评估的本地 JSON 持久性。
不包含私钥、生产提供商地址、客户数据或内部部署秘密。
### AI 原生访问而非密码共享
- 每个 AI 和项目的一个短期凭证；
- 服务器强制执行工作区和项目隔离；
- 显式读取/追加范围；
- 幂等写入和 Git 请求 ID；
- 撤销和审计历史；
- Codex 的聚焦 MCP 集成。
### 当前范围和诚实的限制
当前版本是 Codex 周围的聚焦项目记录层，而不是替代代理运行时。
- 它不运行 Codex，自动监控 Codex 会话或控制 Codex 帐户。
- 它不连接或修改现有的源代码仓库。其 Git 提交属于本地项目 OS 记录仓库。
- 验证笔记由 Codex 报告并存储以供审查；服务器验证结构、身份、范围、幂等性和进度规则，但不独立证明源代码或部署是否通过。
- 已发布的 MCP 表面仅包含两个工具：作用域上下文读取和作用域进度追加。
- 现有的源代码仓库集成、更丰富的证据、交接草稿、知识草稿、远程 MCP 和 OAuth 仍在路线图中。
## 开源表面
该存储库是聚焦的 **OSS 项目 OS 表面**。它公开了项目驾驶舱、启动卡、Git 支持的进度、交接包、团队空间、知识库和回顾。
商业 SaaS 模块（例如销售后台页面、付费计划操作、平台管理、公告系统和支付基础设施）已从公共运行时和源代码树中删除。新的本地运行以正常项目工作区启动，而不是托管的商业管理控制台。
该存储库不包括托管的商业服务、私有提供商凭证、生产客户数据、支付基础设施或内部部署秘密。
## 适用人群
如果您：
- 使用 AI 编码代理构建项目；
- 管理多个 AI 协助的软件项目；
- 使用 Codex 进行实际的多会话软件交付；
- 尝试向队友、利益相关者或未来维护者展示 AI 工作；
- 厌倦在聊天会话之间丢失项目上下文；
- 构建内部 AI 项目管理平台；
- 探索上下文工程、代理交接和基于 Git 的 AI 工作流。
## 常见用例
- AI 项目管理仪表板
- AI 编码代理进度跟踪器
- 代理交接和上下文包生成器
- 基于 Git 的项目执行系统
- AI 团队的内部项目操作系统
- AI 交付工作的知识库
- 面向客户的项目进度可见性
- 多项目 AI 工作流控制中心
## 截图和图表
### 工作中的项目驾驶舱
### 连接 Codex
<details>
<summary> 亮色模式 </summary>
</details>
> 截图使用隔离的本地工作区和非敏感的示例内容。未显示客户帐户、生产端点或私有凭证。
### 工作流图
### Git 循环图
### 架构图
## 技术栈
- 前端：React、Vite、TypeScript、Tailwind CSS
- 后端：Node.js、Express
- 持久化：默认情况下使用本地 JSON 文件
- 项目记录模型：基于 Git 的项目工作区
- 许可证：Apache-2.0
## 快速开始
要求：
- Node.js 18+
- npm 或 pnpm
- Git
最快的本地启动方式是 Docker Compose：
```bash
docker compose up --build
```
打开 <http://localhost:8790>。包含的 Compose 文件绑定到 `127.0.0.1` 并仅启用本地评估的无密码访问。
对于手动开发启动，安装前端依赖项：
```bash
npm install
```
启动后端：
```bash
cd server
npm install
npm run seed
PROJECT_OS_DEV_NO_AUTH=true npm start
```
在另一个终端启动前端：
```bash
npm run dev
```
打开终端中显示的 Vite URL。API 监听：
```text
http://localhost:8790
```
生产环境拒绝在没有 `PROJECT_OS_AUTH_USER` 和 `PROJECT_OS_AUTH_PASSWORD` 的情况下启动。
有关本地、服务器、反向代理、存储、备份、Git、AI 提供商和知识库设置的更多信息，请参阅：
- [部署指南](docs/DEPLOYMENT.md)
- [接口和适配器合约](docs/INTERFACES.md)
- [Codex MCP 设置](docs/CODEX_SETUP.md)
- [发布安全检查清单](docs/SECURITY_PUBLICATION_CHECKLIST.md)
## 代理事件示例
项目秘密必须在 `X-Project-Key` 头部发送。不要将秘密放在 URL 中。
```bash
curl -X POST http://localhost:8790/api/projects/<project-id>/events \
-H 'Content-Type: application/json' \
-H 'X-Project-Key: <project-secret>' \
-H 'Idempotency-Key: progress-step-001' \
-d '{"message":"Add handoff checklist","verification":"The checklist page loaded and each acceptance item was reviewed.","progressTo":55,"nextStep":"Run acceptance smoke test"}'
```
## 存储库关键词
人们可能会在搜索以下内容时找到该项目：
- AI 项目管理
- Codex 项目管理
- Codex 交付工作流
- MCP 服务器
- 模型上下文协议
- AI 编码代理仪表板
- 代理交接
- 上下文工程
- 基于 Git 的项目管理
- AI 工作流自动化
- 项目进度跟踪器
- AI 团队的知识库
- AI 协助软件交付的开发者工具
## 当前状态
该存储库是早期公开开源版本。
在生产使用之前，请查看发布门控：
- 多租户权限审计；
- 无生产代币、私有域、私有文档或客户数据；
- `pnpm run check` 通过；
- 代理 API + MCP 验收测试通过；
- 浅色和深色 UI 截图审查；
- 清晰的部署、备份和回滚计划。
## 路线图
- 更强的项目角色模型
- 远程 OAuth 保护的 MCP 传输
- 更多用于交接草稿和知识草稿的范围工具
- 更好的视觉进度时间线
- 不附带私钥的提供商适配器示例
- Playwright 烟雾测试
- 短小的端到端工作流 GIF 和更多引导示例
- 更多适合初学者的设置配方
## 独立项目
Codex 是 OpenAI 的商标。该独立开源项目与 OpenAI 无关。
## 长期维护
该存储库旨在公开维护。每个版本都将记录已验证的添加、安全更改、已知限制和 [CHANGELOG.md](CHANGELOG.md) 和 [ROADMAP.md](ROADMAP.md) 中的下一个里程碑。
下一个里程碑是 **v0.3.0：更深入的 Codex 工作流** — Codex 的测试首次运行路径、更丰富的结构化证据、更安全的远程 MCP 传输和更清晰的 AGENTS.md 驱动的验收。计划的工作不会作为已发布的 功能呈现。
## 贡献
欢迎提出问题、想法和拉取请求。良好的贡献包括：
- 更清晰的文档；
- 适配器示例；
- 部署配方；
- UI 改进；
- 安全强化；
- 现实世界的 AI 项目工作流案例。
如果该项目对您有帮助，点亮存储库可以让更多 AI 构建者和项目团队更容易发现它。
