从这里开始

快速入门

本指南解释了安装并初始化 Rasen 后它是如何工作的。有关安装说明，请参阅安装指南。刚接触整个文档集？文档首页映射了所有内容。

我该在哪里输入这些命令？ 两个地方，混淆它们是最常见的早期绊脚石。

rasen ... 命令（如 rasen init）在你的终端中运行。

/rasen:... 命令（如 /rasen:propose）在你的 AI 助手的聊天中运行，即你请求它编写代码的相同输入框。

没有单独的"交互模式"需要启动。你只需在聊天中输入斜杠命令，你的助手就会接管。完整说明：命令的工作原理。

你的前五分钟

完整的循环，每个步骤都标记了发生的位置：

TERMINAL   $ npm install -g @atelierai/rasen@latest
TERMINAL   $ cd your-project && rasen init
AI CHAT      /rasen:explore                    (optional: think it through first)
AI CHAT      /rasen:propose add-dark-mode      (AI drafts the plan; you review it)
AI CHAT      /rasen:apply                      (AI builds it)
AI CHAT      /rasen:archive                    (specs updated, change filed away)

两个终端步骤用于设置，然后你在聊天中工作。本指南的其余部分将解释每个步骤的作用和你将看到的内容。

还不确定要构建什么？从 /rasen:explore 开始。 它是一个零成本的思考伙伴，会阅读你的代码库、权衡选择，并在任何产物或代码存在之前把一个模糊的想法打磨成具体的计划。当情况清晰后，它会交接给 /rasen:propose。这是与 AI 合作的最佳习惯，否则 AI 会自信满满地构建错误的东西。参见先探索指南。

工作原理

Rasen 是一套自主引擎：你只需提供意图，它便自行驱动改动走完规划、实施、评审、修复、交付、归档。

快速路径（核心命令集）：

/rasen:explore ──► /rasen:propose ──► /rasen:apply ──► /rasen:sync ──► /rasen:archive
   (optional)

当你在思考要做什么时从 /rasen:explore 开始，或者当你已经知道时直接跳到 /rasen:propose。Explore 在默认 full 配置和精简的 core 配置中都提供，所以除非你选择了省略它的 custom 配置，否则它都在那里。

扩展路径（逐步产物控制）：

/rasen:new ──► /rasen:ff or /rasen:continue ──► /rasen:apply ──► /rasen:verify ──► /rasen:archive

默认全局配置是 full，它安装所有工作流命令——你已经可以使用上述两条路径。如果你想精简到必需内容（propose、explore、apply、sync、archive），用 rasen config profile core 切换，然后运行 rasen update。

Rasen 创建什么

运行 rasen init 后，你的项目有以下结构：

rasen/
├── specs/              # 唯一事实来源（你的系统行为）
│   └── <domain>/
│       └── spec.md
├── changes/            # 提议的更新（每个变更一个文件夹）
│   └── <change-name>/
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       └── specs/      # 增量规格（正在改变的内容）
│           └── <domain>/
│               └── spec.md
└── config.yaml         # 项目配置（可选）

两个关键目录：

specs/ - 唯一事实来源。这些规格描述你的系统当前如何运作。按领域组织（例如 specs/auth/、specs/payments/）。
changes/ - 提议的修改。每个变更都有自己的文件夹，包含所有相关产物。当变更完成时，其规格合并到主 specs/ 目录。

理解产物

每个变更文件夹包含指导工作的产物：

产物	用途
`proposal.md`	"为什么"和"是什么" - 捕获意图、范围和方法
`specs/`	增量规格显示 ADDED/MODIFIED/REMOVED 需求
`design.md`	"怎么样" - 技术方法和架构决策
`tasks.md`	实现清单，带复选框

产物彼此承接：

proposal ──► specs ──► design ──► tasks ──► implement
   ▲           ▲          ▲                    │
   └───────────┴──────────┴────────────────────┘
            update as you learn

在实现过程中学习更多时，你可以随时回去完善早期产物。

增量规格如何工作

增量规格是 Rasen 中的关键概念。它们显示相对于你的当前规格正在发生什么变化。

格式

增量规格使用部分来指示变更类型：

# Delta for Auth

## ADDED Requirements

### Requirement: Two-Factor Authentication
The system MUST require a second factor during login.

#### Scenario: OTP required
- GIVEN a user with 2FA enabled
- WHEN the user submits valid credentials
- THEN an OTP challenge is presented

## MODIFIED Requirements

### Requirement: Session Timeout
The system SHALL expire sessions after 30 minutes of inactivity.
(Previously: 60 minutes)

#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 30 minutes pass without activity
- THEN the session is invalidated

## REMOVED Requirements

### Requirement: Remember Me
(Deprecated in favor of 2FA)

归档时会发生什么

当你归档一个变更时：

ADDED 需求被追加到主规格
MODIFIED 需求替换现有版本
REMOVED 需求从主规格中删除

变更文件夹移到 rasen/changes/archive/ 以供审计历史。

示例：你的第一次变更

让我们走一遍为应用添加暗色模式的过程。

1. 开始变更（默认）

You: /rasen:propose add-dark-mode

AI:  Created rasen/changes/add-dark-mode/
     ✓ proposal.md — why we're doing this, what's changing
     ✓ specs/       — requirements and scenarios
     ✓ design.md    — technical approach
     ✓ tasks.md     — implementation checklist
     Ready for implementation!

如果你启用了扩展工作流配置，你也可以分两步完成：/rasen:new 然后 /rasen:ff（或逐步 /rasen:continue）。

2. 创建的内容

proposal.md - 捕获意图：

# Proposal: Add Dark Mode

## Intent
Users have requested a dark mode option to reduce eye strain
during nighttime usage.

## Scope
- Add theme toggle in settings
- Support system preference detection
- Persist preference in localStorage

## Approach
Use CSS custom properties for theming with a React context
for state management.

specs/ui/spec.md - 显示新需求的增量：

# Delta for UI

## ADDED Requirements

### Requirement: Theme Selection
The system SHALL allow users to choose between light and dark themes.

#### Scenario: Manual toggle
- GIVEN a user on any page
- WHEN the user clicks the theme toggle
- THEN the theme switches immediately
- AND the preference persists across sessions

#### Scenario: System preference
- GIVEN a user with no saved preference
- WHEN the application loads
- THEN the system's preferred color scheme is used

tasks.md - 实现清单：

# Tasks

## 1. Theme Infrastructure
- [ ] 1.1 Create ThemeContext with light/dark state
- [ ] 1.2 Add CSS custom properties for colors
- [ ] 1.3 Implement localStorage persistence

## 2. UI Components
- [ ] 2.1 Create ThemeToggle component
- [ ] 2.2 Add toggle to settings page
- [ ] 2.3 Update Header to include quick toggle

## 3. Styling
- [ ] 3.1 Define dark theme color palette
- [ ] 3.2 Update components to use CSS variables

3. 实现

You: /rasen:apply

AI:  Working through tasks...
     ✓ 1.1 Created ThemeContext with light/dark state
     ✓ 1.2 Added CSS custom properties to globals.css
     ✓ 1.3 Implemented localStorage persistence
     ✓ 2.1 Created ThemeToggle component
     ...
     All tasks complete!

在实现过程中，如果你发现设计需要调整，只需更新产物并继续。

4. 归档

You: /rasen:archive

AI:  Archiving add-dark-mode...
     ✓ Merged specs into rasen/specs/ui/spec.md
     ✓ Moved to rasen/changes/archive/2025-01-24-add-dark-mode/
     Done! Ready for the next feature.

你的增量规格现在是主规格的一部分，记录了你的系统如何工作。

验证和审查

使用 CLI 检查你的变更：

# 列出活跃变更
rasen list

# 查看变更详情
rasen show add-dark-mode

# 校验规格格式
rasen validate add-dark-mode

# 交互式仪表板
rasen view

后续步骤

先探索 - 使用 /rasen:explore 在提交之前思考一个想法
审查变更 - 在 AI 草拟的计划中检查什么，在任何代码之前
编写好的规格 - 什么是强有力的需求和场景
在现有项目中使用 Rasen - 在大型存量代码库上开始
编辑与迭代变更 - 更新产物、回退、对账手工编辑
核心概念一览 - 整个心智模型在一页上
示例与食谱 - 真实的变更，从头到尾
工作流 - 常见模式和何时使用每个命令
命令 - 所有斜杠命令的完整参考
概念 - 更深入地理解规格、变更和模式
自定义配置 - 让 Rasen 按你的方式工作
Stores - 规划跨越多个仓库或团队？将其保留在自己的仓库中（测试版）
FAQ 和故障排除 - 当你卡住时