快速上手

这篇 quickstart 适合第一次使用 RunLogos 的用户。你会从一个空目录开始，完成项目初始化、用 RunLogos 打开项目、连接 Agent、生成第一份需求文档，并预览 Phase 2 Product Design 生成的 HTML 原型。

预计用时 20 到 30 分钟。完成后，你会得到一个包含 logos/ 规格链目录、AGENTS.md 协作规则、需求文档和产品设计原型的最小项目。

这篇文档不会讲高级部署、复杂 API 编排、数据库迁移和团队协作流程。那些内容可以在后续阅读 规格链概览。

先理解三个角色

很多新手卡住，是因为不知道 RunLogos、OpenLogos CLI 和 Agent 到底谁负责什么。先记住下面这句话：

OpenLogos CLI 建好项目规则，RunLogos 让你看得见和管得住，Agent 按规则帮你写文档、写测试和写代码。三者读写的是同一个项目目录。

换成更直白的话：RunLogos 是桌面端工作台，OpenLogos CLI 是项目规则和命令工具，Agent 是 AI 编程助手。你不用让 RunLogos 去写代码，也不用让 Agent 去“操作 RunLogos 界面”；Agent 只需要读写同一个项目目录里的文件。

你实际使用时通常是这样配合：

1. 在 RunLogos 里新建并初始化项目，得到 logos/ 规格链目录和 AGENTS.md。
2. 在 RunLogos 侧边栏查看当前阶段和文档。
3. 在 RunLogos Agent 面板或外部 Agent 中发送提示词。
4. Agent 读取 AGENTS.md、logos/logos-project.yaml 和对应 Skill 后生成文档。
5. 回到 RunLogos 查看 Agent 生成的需求、原型、测试和验收结果。

开始前确认

请先确认这几件事：

• 已安装 RunLogos 桌面端。
• 至少准备一个可用 Agent：RunLogos 内置 Agent 面板，或 Codex / Claude Code / Cursor / OpenCode 等外部 Agent。
• 准备一个空目录或试验目录。

这篇 quickstart 的初始化、打开项目和推进阶段都在 RunLogos 里完成，不需要手动敲命令行。OpenLogos CLI 是可选的，只有在最后一步运行 openlogos verify 验收时才会用到。

如果你还没有安装 Agent，先阅读 Agent 安装指南。Agent 安装完成后再回到这里继续。

第 1 步：用 RunLogos 新建并初始化项目

在哪里操作：RunLogos 桌面端。

操作

RunLogos 的意义就是让你摆脱命令行。新建项目时你不需要打开终端，也不需要手动敲 openlogos init，直接在 RunLogos 里完成即可。

打开 RunLogos，在新建项目入口里：

1. 选择一个空目录或试验目录作为项目位置。
2. 填写项目名称。
3. 选择文档语言（中文项目选择 zh）。
4. 选择你主要使用的 AI 工具（例如 Codex、Claude Code、Cursor、OpenCode）。
5. 点击创建。RunLogos 会在后台完成项目初始化。

如果你已经有一个现成代码仓库，不要走这个新建项目流程。请先阅读 现存项目接入，用存量项目方式接入，避免误把已有项目当成新项目初始化。

预期结果

初始化完成后，RunLogos 会在项目根目录生成类似结构：

my-first-runlogos-project/
├── AGENTS.md
└── logos/
    ├── logos.config.json
    ├── logos-project.yaml
    ├── resources/
    │   ├── prd/
    │   ├── api/
    │   ├── database/
    │   ├── test/
    │   └── scenario/
    └── changes/

AGENTS.md 是给 Agent 看的协作规则。logos/logos.config.json 是项目配置。logos/logos-project.yaml 是项目资源索引，Agent 会通过它判断当前项目下一步该做什么。

第 2 步：确认 RunLogos 里的资源树

在哪里操作：RunLogos 桌面端。

操作

初始化完成后，RunLogos 会自动打开这个项目。你不需要再手动选目录。在侧边栏确认 logos/ 资源树是否正常展示即可。

如果你是下次重新打开项目，记得选择包含 AGENTS.md 和 logos/logos.config.json 的项目根目录，不要只选择 logos/ 子目录，也不要只选择 src/ 或其它业务代码子目录。RunLogos 和 Agent 后续都应该工作在同一个项目根目录。

预期结果

RunLogos 读取 logos/logos-project.yaml 后，侧边栏会展示 logos/ 资源树。你应该能看到需求、产品设计、API、数据库、测试、验收、变更提案等资源分组。

如果项目树为空，通常是因为重新打开时选错了目录。请重新打开包含 logos/logos.config.json 的项目根目录。

第 3 步：连接或打开 Agent

在哪里操作：RunLogos Agent 面板，或项目根目录中的外部 Agent。

还没有 Agent？先看 Agent 安装指南

操作

你可以使用 RunLogos 内置 Agent 面板，也可以在终端或外部工具中启动 Codex、Claude Code、Cursor、OpenCode 等 Agent。无论使用哪种方式，都要确认 Agent 的工作目录是包含这些文件的项目根目录：

AGENTS.md
logos/logos.config.json
logos/logos-project.yaml

然后把下面这段提示词发给 Agent：

请读取 AGENTS.md 和 logos/logos-project.yaml，告诉我当前项目下一步应该做什么。

预期结果

Agent 应该先读取项目规则，返回当前 Phase、需要读取的 Skill，以及下一步建议。它不应该直接开始写业务代码。

如果 Agent 说找不到 AGENTS.md，请检查它是否真的在项目根目录启动。

第 4 步：让 Agent 引导你写需求文档

在哪里操作：RunLogos 桌面端 + Agent 对话。

操作

新项目通常从 Phase 1 Requirements 开始，因为还没有需求文档。你不需要记住复杂的提示词，直接对 Agent 说：

请帮我写需求文档

Agent 会读取 AGENTS.md、logos/logos-project.yaml 和需求 Skill，进入引导流程，用小白能回答的问题向你澄清产品目标、目标用户、核心场景和验收标准。它应该先提问，而不是直接生成完整文档，更不应该马上写代码。

按 Agent 的问题逐条补充信息。你可以先回答得很粗糙，后面再逐步细化。

下面这句产品想法可以作为开头的参考：

我想做一个面向个人开发者的任务管理工具，目标用户是经常用 AI 写代码但需求容易散乱的人。第一个核心场景是用户创建一个项目，并把需求、任务和验收标准整理到同一个地方。

预期结果

Agent 会在 logos/resources/prd/1-product-requirements/ 下生成需求文档。你可以在 RunLogos 中打开这份文档，检查产品目标、用户画像、核心场景和验收标准是否符合你的想法。

如果需求不满意，不要急着进入代码阶段。继续补充上下文，让 Agent 修改需求文档。

首先，对 Agent 输入「请帮我写需求文档」启动需求流程：

接着，根据 Agent 的提问，逐条补全需求的必要内容：

最后，Agent 生成结构化的需求文档：

第 5 步：推进产品设计

在哪里操作：RunLogos 桌面端。

操作

需求文档确认后，你不需要手动拼提示词去启动下一阶段。RunLogos 会在当前阶段给出下一步建议，例如「基于需求文档撰写产品设计」。直接点击该建议右边的小三角按钮，RunLogos 就会把对应的产品设计提示词发给 Agent，推动 Phase 2 Product Design。

预期结果

Agent 会读取需求文档和产品设计 Skill，在 logos/resources/prd/2-product-design/ 下生成产品设计文档和 HTML 原型。你可以在 RunLogos 中点击 Preview 查看原型。

第 6 步：检查原型并记录修改意见

在哪里操作：RunLogos 桌面端 + Agent 对话。

操作

打开 HTML 原型 Preview 后，重点检查：

• 页面结构是否符合你的产品想法。
• 关键操作路径是否完整。
• 按钮文案是否清楚。
• 空状态、错误状态和加载状态是否合理。
• 用户第一次进入页面时是否知道下一步做什么。

给 Agent 的修改意见尽量具体。例如：

请修改产品设计和原型：注册按钮点击后不要直接进入主界面，要先进入邮箱验证步骤；邮箱验证页面需要有重新发送验证码的按钮和验证码过期提示。

预期结果

Agent 应该按文档规则更新功能规格和 HTML 原型。你回到 RunLogos 刷新后，可以继续预览修改后的原型。

第 7 步：继续推进规格链

在哪里操作：RunLogos、终端、Agent 对话。

操作

需求和产品设计确认后，继续沿着规格链推进：

1. 场景建模：把用户流程变成时序图。
2. API / DB 设计：如果项目有接口和数据库，生成 OpenAPI 与 SQL 设计。
3. 测试设计：先定义 UT / ST 用例。
4. 代码生成：让 Agent 按测试和规格实现代码。
5. 验收验证：在终端运行 openlogos verify。

预期结果

每一步都会读取上一步产物。你不需要每次重新解释全部背景，只需要确认本轮改动是否符合目标。

常见问题

openlogos 命令不存在

回到 安装 文档，检查 Node.js、npm 和 OpenLogos CLI 是否安装成功，并确认 npm 全局命令目录已经加入 PATH。

RunLogos 打开后看不到项目

确认你选择的是包含 logos/logos.config.json 的项目根目录。不要只打开 logos/、src/ 或 src-tauri/。

Agent 不知道项目规则

确认 Agent 启动目录是项目根目录，然后先发送：

请读取 AGENTS.md 和 logos/logos-project.yaml，告诉我当前项目下一步应该做什么。

Agent 想直接写代码

要求它先按当前 Phase 读取对应 Skill，并先产出需求、设计、测试等规格文档。设计文档完成前，不要直接进入实现阶段。

不知道该在 RunLogos 里做，还是对 Agent 说

简单区分：

• 查看、预览、导航、对照规格链：在 RunLogos 里做。
• 生成、修改、排查、实现：交给 Agent。
• 初始化、创建变更、合并规格、验收验证：用 OpenLogos CLI。

不知道需求怎么写

先用一句话说明产品、目标用户和第一个核心场景。Agent 会继续问你缺失的信息。

下一步

继续阅读 规格链概览，了解需求、设计、场景、API、数据库、测试、代码和验收如何串联。