跳转到内容

接入已有项目

已经有一个在跑的项目了?本指南会带你在不打乱现有代码库的前提下接入 OpenLogos。你将在几分钟内启用完整的方法论基础设施——变更管理、AI Skills、verify 门禁。

所需时间: 接入约需 15 分钟,之后按你自己的节奏迭代。


快速开始假设这是一个全新项目,带你从零走过 Phase 1 → 2 → 3。那不是你现在的情况。

当你接入一个已有项目时:

方面新项目(init)已有项目(adopt)
起点空目录代码已存在
模块生命周期initial(阶段驱动)launched(变更驱动)
Phase 1–3 文档编码前必需可选——逐步补全
变更管理launch 之后激活立即激活
首个建议动作编写需求直接创建第一个变更提案(openlogos change <slug>)

关键区别:adopt 会立即把你的模块设为 lifecycle: launched、bootstrap: adopted。你跳过了初始文档基线的要求,直接进入迭代工作流。


Terminal window
npm install -g @miniidealab/openlogos
openlogos --version

在你的项目根目录(即 package.json、Cargo.toml 或 pyproject.toml 所在处):

Terminal window
openlogos adopt

CLI 会问你两个问题:

Choose language / 选择语言:
1. 中文 (default)
2. English
Your choice [1/2] (default: 1): 2
Choose AI coding tool / 选择 AI 编码工具:
1. Claude Code (default)
2. OpenCode
3. Codex
4. Cursor
5. Other
6. All (deploy for all tools)
7. ZCode
8. Qoder
9. WorkBuddy
Your choice [1/2/3/4/5/6] (default: 1): 1

或者传入参数以跳过交互提示:

Terminal window
openlogos adopt --locale en --ai-tool claude-code

--ai-tool 可取 claude-code、opencode、codex、cursor、zcode、qoder、workbuddy、other 或 all。

如果 adopt 检测到你的技术栈,还会列出尚未被 git 忽略的路径(例如依赖目录、构建产物目录),询问是否加入 .gitignore 的 OpenLogos 托管区块。之后可以用 openlogos ignore 调整。

your-project/
├── AGENTS.md ← AI 指令文件(自动生成)
├── CLAUDE.md ← Claude Code 指令文件
├── .gitignore ← OpenLogos 托管区块(logos/.openlogos-runtime/ + 已接受的建议)
├── .claude/(或 .cursor/ 等) ← 所选 AI 工具的宿主集成
│
└── logos/
├── logos.config.json ← 项目配置
├── logos-project.yaml ← AI 协作索引
│ (lifecycle: launched, bootstrap: adopted)
├── resources/ ← 空目录,待填充
│ ├── prd/
│ ├── api/
│ ├── database/
│ ├── test/
│ └── verify/
├── skills/ ← AI Skills(Codex、Cursor、ZCode、Qoder、WorkBuddy 从各自宿主目录加载)
├── spec/ ← 方法论规格
└── changes/ ← 变更提案工作区

第 3 步:配置 tech_stack 和 skip_phases

Section titled “第 3 步:配置 tech_stack 和 skip_phases”

打开 logos/logos-project.yaml 并填入你的技术栈。这能给 AI 提供生成准确代码和文档所需的上下文。

tech_stack:
language: TypeScript
framework: Next.js 15
database: PostgreSQL
hosting: Vercel
auth: NextAuth.js

如果你的项目没有 HTTP API 或数据库,声明 skip_phases 来告诉 OpenLogos 跳过哪些阶段:

modules:
- id: core
name: Core
lifecycle: launched
bootstrap: adopted
skip_phases: [api, database, scenario] # CLI tool, no HTTP API
取值跳过何时使用
apiAPI 设计阶段桌面应用、CLI 工具、库
databaseDB 设计阶段无状态服务、纯计算
scenario编排测试通常与 api 搭配使用

检查 openlogos verify 能否找到并运行你的测试:

Terminal window
cat logos/logos.config.json

你应该能看到一个 verify 区块:

{
"verify": {
"result_path": "logos/resources/verify/test-results.jsonl",
"pre_run_command": "npm test"
}
}

如果 pre_run_command 缺失或不对,手动编辑它:

{
"verify": {
"result_path": "logos/resources/verify/test-results.jsonl",
"pre_run_command": "npm test",
"sandbox_mode": "auto"
}
}

Terminal window
openlogos status

你会看到类似这样的输出:

📊 OpenLogos Project Status
⏭️ Phase 1 · 需求文档 (WHY) — 文档基线已跳过(存量项目接入)
⏭️ Phase 2 · 产品设计 (WHAT) — 文档基线已跳过(存量项目接入)
⏭️ Phase 3-0 · 技术架构 — 文档基线已跳过(存量项目接入)
...
🧩 模块
✅ core (Core) [launched]
💡 无需先单独建立基线;运行 openlogos change <slug> 直接创建新提案(baseline-seed begin 仅为显式可选加速器)

带 ⏭️ 的阶段被跳过了——这是预期的。你的项目处于 launched 生命周期,这意味着变更管理已立即激活。从这里开始,每次代码改动都需要一份变更提案。


第 6 步:从第一个变更提案开始

Section titled “第 6 步:从第一个变更提案开始”

开始真正的工作之前,不需要先单独做一份基线提案。直接为你第一个想做的改动创建提案:

Terminal window
openlogos change my-first-change

这会创建 logos/changes/my-first-change/,内含 proposal.md 和 tasks.md。告诉 AI:

请阅读 logos/changes/my-first-change/proposal.md 并帮我填写。

规划提案时,change-writer Skill 会按本次改动触达的功能与场景自动闭包:目标规格已存在则修改;缺失则完整新建,记录被触达部分当前的实际行为。logos/resources/ 就这样随每个提案增长,从你真正改动的部分开始。


第 7 步:给你的测试加上 OpenLogos reporter

Section titled “第 7 步:给你的测试加上 OpenLogos reporter”

为了让 openlogos verify 正常工作,你的测试需要把结果写入 logos/resources/verify/test-results.jsonl。给你的测试运行器加上 OpenLogos reporter。

vitest.config.ts
import { defineConfig } from 'vitest/config';
export default defineConfig({
test: {
reporters: ['default', './logos/spec/openlogos-reporter.ts'],
},
});

然后用 OpenLogos ID 给你的测试命名:

it('UT-S01-01: should register user with valid email', () => { ... });
it('ST-S01-01: full registration flow', () => { ... });

完整的 reporter 规格和可直接复制的模板见测试结果格式。


接入完成后,每次变更都遵循 Delta 工作流:

  1. 创建提案

    Terminal window
    openlogos change my-feature
  2. 让 AI 填写提案

    Read logos/changes/my-feature/proposal.md and help me fill it in.
  3. 产出 delta 文件 —— 更新的规格、API 变更、新的测试用例。写作过程中用 openlogos change-lint 检查 proposal、tasks 与 delta,问题在合并前就暴露出来。

  4. 合并(人类确认点)

    Terminal window
    openlogos merge my-feature

    一次调用、原子地应用全部 delta——要么全部写入,要么一项都不写。

  5. 规划代码切片 —— slice-planner Skill 通过 openlogos slice plan --file <slices.json> 写出 tasks.md 的 [code] 段

  6. 实现代码 + 测试 —— AI 按已合并的规格逐片实现

  7. 验证(人类确认点)

    Terminal window
    openlogos verify
  8. 归档(人类确认点;若提案含 [deploy] 段,则在部署与 smoke 之后)

    Terminal window
    openlogos archive my-feature

我必须先填完所有 Phase 1–3 文档才能做任何事吗?

不必。有了 bootstrap: adopted,Phase 1–3 文档都是可选的。你可以立即开始迭代,并在开发过程中逐步补全——每个功能提案都是记录相关场景和架构决策的好机会。

如果我的项目有多个模块怎么办?

运行 openlogos module add <name> 注册更多模块。每个模块都独立追踪自己的阶段进度和生命周期状态。

Terminal window
openlogos module add payment
openlogos module add admin

我能在一个已经用 init 初始化过的项目上用 adopt 吗?

不能——如果 logos/logos.config.json 已存在,adopt 会报错退出。如果你用 init 初始化过,又想切换到 launched 生命周期,请改用 openlogos launch。

bootstrap: adopted 究竟做了什么?

它告诉 OpenLogos 这个项目跳过了初始文档基线。效果如下:

  • openlogos status 把 Phase 1–3 显示为 ⏭️(跳过)而非 ❌(缺失)
  • openlogos next 建议直接创建变更(openlogos change <slug>),而非”编写需求”
  • openlogos launch 不再要求 Phase 1–3 文档必须存在

我的测试命令很复杂——怎么配置?

直接编辑 logos/logos.config.json:

{
"verify": {
"result_path": "logos/resources/verify/test-results.jsonl",
"pre_run_command": "docker compose up -d && npm test && docker compose down"
}
}