OpenLogos
面向 AI 时代的开源软件研发方法论。
OpenLogos 定义标准，RunLogos 让它更高效地落地。
什么是 OpenLogos？
OpenLogos 是一套面向 AI 时代的软件研发方法论，用来约束和引导 AI 参与真实软件项目的完整过程。
它反对直接把 AI 当作“代码自动生成器”使用，而是强调先明确：
- 为什么做
- 做什么
- 如何做
OpenLogos 把这套过程沉淀为可执行的规范、Skills、CLI 命令和验收规则，让 AI 在项目里沿着正确轨道推进，而不是把项目带向失控的 Vibe Coding。
OpenLogos 与 RunLogos
OpenLogos 定义标准。RunLogos 让标准更好落地。
- OpenLogos 是开源方法论，提供研发流程、AI Skills、CLI 工具和规范文档
- RunLogos 是构建在 OpenLogos 之上的专业桌面工具，用来把 AI 生成的文档、API、DB、测试与变更结果变成可视化、可编辑、可编排、可调试的工作空间
OpenLogos 可以独立工作，兼容多种 AI 编码工具。
RunLogos 则是它的效率增强层，适合需要更强可视化编辑、API 编排调试和结构化评审体验的团队或个人。
了解更多：
- OpenLogos 官网：openlogos.ai
- RunLogos 国际站：runlogos.com
- RunLogos 中国站：runlogos.cn
RunLogos 站点选择
runlogos.com：面向国际用户runlogos.cn：面向中国区用户
两者对应同一产品体系，但会根据不同区域用户提供更合适的访问入口与信息。
核心工作流
WHY -> 需求文档
WHAT -> 产品设计
HOW -> 技术架构 -> 场景建模 -> API / DB -> 测试设计 -> 代码实现 -> 验收验证核心原则：
- 反 Vibe Coding：AI 负责执行，人负责判断
- 场景驱动：从真实业务场景推导实现方案
- 测试先行：测试不是补充材料，而是开发规格的一部分
- 变更可追溯：通过 proposal / merge / archive 管理迭代
全自动流程（Flow 引擎）
从 0.11 起，OpenLogos 把整个变更生命周期建模为一台声明式状态机（flow 引擎），作为唯一事实源——status / next / watch 都从它被动派生「下一步该做什么」。launched 项目的每次变更沿固定链路推进：
plan（方案）→ spec（规格/delta）→ merge（合并）→ slice（切片规划）
→ implement（实现·切片循环 ↻）→ deliver（verify/部署/smoke）→ close（归档/push）两档授权：
- 半自动（默认）：merge、verify、部署、smoke、archive、push 都是人类确认点。
- 全自动 / 无人值守（
openlogos next --auto）：一次授权即让提案全链路自动跑到底，自动放行可跳过的门，代码转绿后自动执行 verify / smoke / archive / push，并把每次放行追加到GATE_AUTO_PASSED审计轨迹。
硬红线（安全底座）：implement 段对代码切片循环，直到测试转绿；达迭代上限仍未收敛会升级为不可跳过的 loop-exhausted 门。任何模式——即便 --auto——都绝不自动放行未通过测试的代码。
openlogos change add-dark-mode # 创建变更提案
openlogos next --auto # 一条命令，无人值守跑完整条链路
openlogos flow show --resolved # 查看应用 overlay 后的真实编排
openlogos watch # 流式查看实时派生状态深入了解：可编排研发流程
安装与前置条件
第一步：安装 OpenLogos CLI
需要 Node.js >= 18。
npm install -g @miniidealab/openlogos
openlogos --versionCLI 包说明见 cli/README.md。
第二步：安装宿主 AI 工具
OpenLogos 本身提供方法论、Skills、规范和 CLI，但 agent / 插件 / 命令面板是否可见，取决于你使用的宿主 AI 工具是否已正确安装并完成登录。
快速开始
openlogos init my-project
cd my-project
openlogos status
openlogos next一个典型流程通常是：
- 用
openlogos init初始化项目 - 让 AI 按当前 Phase 逐步补齐文档与设计
- 用
openlogos status/openlogos next检查进度和下一步动作 - 按场景实现代码与测试，并写入 OpenLogos reporter
- 用
openlogos verify生成验收结果 - 首轮开发完成后，用
openlogos launch进入活跃迭代阶段 - 后续迭代通过
openlogos change <slug>、merge、archive管理
支持的 AI 工具
OpenLogos 当前已支持：
| 工具 | 集成方式 |
|---|---|
| Cursor | AGENTS.md + .cursor/rules/ |
| Claude Code | 原生插件或 CLAUDE.md |
| OpenCode | 原生插件 + .opencode/commands/，或 AGENTS.md |
| Codex | 原生插件模式（.codex-plugin/ + .codex/config.toml）+ AGENTS.md 兜底 |
补充说明：
- Codex 已是一等集成能力，可自动部署
.agents/skills/、.codex-plugin/和.codex/config.toml - OpenLogos Skills 本身是平台无关的 Markdown 规范，因此也具备较强的跨工具兼容性
AI 工具安装前置条件
如果宿主 AI 工具本身没有安装好、没有登录成功，或者没有完全重启，OpenLogos 部署出来的 Skills / 插件 / agent 面板通常不会正常显示。
建议至少确认以下几点：
| 工具 | 需要先满足的条件 |
|---|---|
| Cursor | 已安装 Cursor 桌面端；可正常打开项目；允许读取项目根目录下的 AGENTS.md 与 .cursor/rules/；若规则未生效，重启 Cursor 或重新打开项目窗口 |
| Claude Code | 已安装 Claude Code；当前终端可正常启动；插件市场可用；安装或同步完成后重启 Claude Code，确保插件与 agent 面板重新加载 |
| OpenCode | 已安装 OpenCode；终端中可执行 opencode；项目根目录启动；openlogos sync 后重启 OpenCode，确保 .opencode/plugins/ 与 .opencode/commands/ 被重新加载 |
| Codex | 已安装 Codex CLI；当前终端可正常启动 codex；项目内允许读取 .codex/config.toml 与 .codex-plugin/；同步完成后重启会话，确保 hooks 与 .agents/skills/ 生效 |
通用建议：
- 先安装并确认
openlogosCLI：npm install -g @miniidealab/openlogos - 再安装对应 AI 工具本体，并确认命令可在当前终端环境中执行
- 在项目根执行
openlogos init或openlogos sync - 最后完全退出并重新打开 AI 工具
推荐顺序：
- 安装
openlogosCLI - 安装并登录宿主 AI 工具
- 在项目根执行
openlogos init或openlogos sync - 完全重启宿主工具，检查 Skills / 插件 / agent 面板是否出现
如果 agent / 插件面板仍不显示，优先检查：
- AI 工具是否已登录
- CLI 是否在当前终端
PATH中 - 是否在项目根目录启动
- 同步后是否真正重启了工具
核心 CLI 命令
| 命令 | 说明 |
|---|---|
openlogos init [name] | 初始化项目 |
openlogos sync | 重新生成 AI 指令文件与 Skills |
openlogos status | 查看当前阶段进度 |
openlogos next [--auto] | 输出下一步建议；--auto 为全自动无人值守模式 |
openlogos watch | 流式查看实时派生的研发流程状态 |
openlogos flow show | 查看 flow 编排（--resolved 应用 overlay） |
openlogos verify | 生成测试验收报告 |
openlogos deploy-done | 部署完成后受控落标 |
openlogos launch | 从首轮开发切换到活跃迭代 |
openlogos change <slug> | 创建变更提案 |
openlogos merge <slug> | 合并提案 deltas |
openlogos archive <slug> | 归档已完成提案 |
openlogos module list/add/rename/remove | 管理多模块项目 |
注意：以上命令应在项目根目录执行，也就是 logos/logos.config.json 所在目录。
可运行示例
仓库内提供了两个完整示例：
- examples/flowtask：Tauri 桌面应用，侧重 Claude Code 集成
- examples/money-log：Electron 桌面应用，侧重 OpenCode 集成
总览见 examples/README.md。
仓库结构
openlogos/
├── cli/ # OpenLogos CLI
├── skills/ # 平台无关的 AI Skills
├── spec/ # 方法论规范源码
├── docs/ # 工具与使用文档
├── plugin/ # Claude Code 插件
├── plugin-codex/ # Codex 插件模板
├── plugin-opencode/ # OpenCode 插件模板
└── examples/ # 可运行示例项目openlogos init 后的项目结构
your-project/
├── AGENTS.md
├── CLAUDE.md # 适用时生成
├── logos/
│ ├── logos.config.json
│ ├── logos-project.yaml
│ ├── resources/
│ ├── changes/
│ └── spec/
└── src/OpenLogos 会把方法论资产集中在 logos/ 目录中，尽量减少对现有代码结构的侵入。
许可证
- 代码与规范：Apache License 2.0
- 文档与教程：CC BY-SA 4.0
链接
- 官网：openlogos.ai
- RunLogos 国际站：runlogos.com
- RunLogos 中国站：runlogos.cn
- OpenCode 指南：docs/opencode.md
- CLI 说明：cli/README.md
- GitHub：github.com/miniidealab/openlogos