快速入门指南

5 分钟上手 sce - 从安装到第一个 AI 辅助功能实现

版本: 1.46.2
最后更新: 2026-02-14
预计时间: 5 分钟
目标读者: 初学者

你将学到什么

完成本指南后，你将能够：

✅ 安装 sce 并设置你的第一个项目
✅ 创建完整的 Spec（需求 → 设计 → 任务）
✅ 为你的 AI 工具导出上下文
✅ 使用 AI 基于 Spec 实现功能
✅ 跟踪任务进度

为什么它比“随手提示词开发”更稳

先 Spec 后编码，减少需求歧义和返工。
多 Spec 可直接切换到编排模式，并行推进。
KPI 命令可输出机器可读结果，让“完成度”可衡量、可审计。

前置条件

开始之前，请确保你有：

Node.js 16 或更高版本（下载）
npm 8 或更高版本（随 Node.js 一起安装）
基本的命令行知识
一个 AI 编码工具（Claude、Cursor、Windsurf、Copilot 等）

检查你的版本：

node --version  # 应显示 v16.0.0 或更高
npm --version   # 应显示 8.0.0 或更高

步骤 1：安装 sce（30 秒）

使用 npm 全局安装 sce：

npm install -g scene-capability-engine

预期输出：

added 50 packages in 5s

验证安装：

sce --version

预期输出：

1.46.2

故障排除：

"sce: command not found" → 重启终端或检查 PATH
macOS/Linux 权限错误 → 使用 sudo npm install -g scene-capability-engine
Windows 权限错误 → 以管理员身份运行终端

步骤 2：在项目中采用 sce（1 分钟）

进入你的项目目录（或创建新项目）：

# 对于现有项目
cd your-project

# 或创建新项目
mkdir my-awesome-app
cd my-awesome-app
git init  # sce 最适合与 git 项目配合使用

采用 sce：

sce adopt

预期输出：

✓ 检测到项目类型：Node.js
✓ 创建 .sce/ 目录
✓ 创建 specs/ 目录
✓ 创建 steering/ 目录
✓ 生成 CORE_PRINCIPLES.md
✓ 生成 ENVIRONMENT.md
✓ 生成 CURRENT_CONTEXT.md

✅ 项目成功采用 sce！

下一步：
  1. 创建你的第一个 Spec：sce spec bootstrap --name 01-00-my-feature --non-interactive
  2. 阅读指南：.sce/README.md

创建的内容：

your-project/
├── .sce/
│   ├── specs/              # 你的 Spec 将存放在这里
│   ├── steering/           # AI 行为规则
│   │   ├── CORE_PRINCIPLES.md
│   │   ├── ENVIRONMENT.md
│   │   └── CURRENT_CONTEXT.md
│   └── README.md           # SCE 系统文档

验证：

sce status

预期输出：

Project: my-awesome-app
Specs: 0
Status: Ready

步骤 3：生成你的第一个 Spec 初稿（2 分钟）

让我们为用户登录功能生成一个 Spec 初稿：

sce spec bootstrap --name 01-00-user-login --non-interactive

预期输出：

✓ 生成 Spec 初稿：01-00-user-login
✓ 生成 requirements.md
✓ 生成 design.md
✓ 生成 tasks.md

📝 下一步：
  1. 编辑 requirements.md 定义你要构建什么
  2. 编辑 design.md 定义你将如何构建
  3. 编辑 tasks.md 分解实现步骤

多 Spec 场景下可直接使用：

sce spec bootstrap --specs "01-00-user-login,01-01-user-session" --max-parallel 3

上述命令会默认切换到 orchestrate 模式并并行推进。

3.0（可选）：30 秒验证可量化交付

先生成输入样例：

sce value metrics sample --out ./kpi-input.json --period 2026-W10 --json

再执行：

sce value metrics snapshot --input ./kpi-input.json --json

如果你想手工编辑输入，也可以创建 kpi-input.json：

{
  "period": "2026-W10",
  "metrics": {
    "ttfv_minutes": 25,
    "batch_success_rate": 0.86,
    "cycle_reduction_rate": 0.34,
    "manual_takeover_rate": 0.16
  },
  "notes": "quick-start smoke run"
}

该命令会输出机器可读快照、风险等级和产物路径，可直接用于周度跟踪。

3.1 编写需求

打开 .sce/specs/01-00-user-login/requirements.md 并编写：

# 用户登录功能

## 概述
使用户能够使用邮箱和密码登录应用程序。

## 用户故事

### US-1：用户登录
**作为** 用户  
**我想要** 使用邮箱和密码登录  
**以便** 访问我的账户

### US-2：登录验证
**作为** 用户  
**我想要** 在登录失败时看到清晰的错误消息  
**以便** 知道出了什么问题

## 功能需求

### FR-1：登录表单
系统应提供包含以下内容的登录表单：
- 邮箱输入字段
- 密码输入字段
- 提交按钮

### FR-2：凭据验证
**当** 用户提交有效凭据时  
**则** 系统验证用户并重定向到仪表板

**当** 用户提交无效凭据时  
**则** 系统显示错误消息"邮箱或密码无效"

### FR-3：输入验证
**当** 用户提交空邮箱时  
**则** 系统显示错误"邮箱为必填项"

**当** 用户提交无效邮箱格式时  
**则** 系统显示错误"请输入有效的邮箱"

**当** 用户提交少于 6 个字符的密码时  
**则** 系统显示错误"密码必须至少 6 个字符"

## 非功能需求

### NFR-1：安全性
- 密码必须在存储前进行哈希处理
- 使用 bcrypt，盐轮数 >= 10
- 实现速率限制（每分钟最多 5 次尝试）

### NFR-2：性能
- 登录响应时间 < 500ms
- 支持 100 个并发登录请求

### NFR-3：可用性
- 清晰的错误消息
- 可访问的表单（WCAG 2.1 Level AA）

## 验收标准

- [ ] 用户可以使用有效的邮箱和密码登录
- [ ] 用户在凭据无效时看到错误消息
- [ ] 邮箱验证正常工作
- [ ] 密码验证正常工作
- [ ] 密码在数据库中已哈希
- [ ] 速率限制防止暴力攻击
- [ ] 登录响应时间低于 500ms

3.2 编写设计

打开 .sce/specs/01-00-user-login/design.md 并编写：

# 用户登录 - 设计文档

## 概述
此设计实现了一个安全的用户登录系统，具有邮箱/密码认证、输入验证和速率限制。

## 架构

### 系统组件

```mermaid
graph TD
    A[登录表单] --> B[AuthController]
    B --> C[ValidationService]
    B --> D[AuthService]
    D --> E[UserRepository]
    D --> F[TokenService]
    E --> G[数据库]

API 设计

POST /api/auth/login

请求：

{
  "email": "user@example.com",
  "password": "secret123"
}

成功响应 (200)：

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "123",
    "email": "user@example.com",
    "name": "张三"
  }
}

错误响应 (401)：

{
  "success": false,
  "error": "邮箱或密码无效"
}

错误响应 (429)：

{
  "success": false,
  "error": "登录尝试次数过多。请稍后再试。"
}

组件设计

AuthController

职责： 处理认证的 HTTP 请求

方法：

login(req, res) - 处理登录请求
validateRequest(req) - 验证请求格式

ValidationService

职责： 验证用户输入

方法：

validateEmail(email) - 检查邮箱格式
validatePassword(password) - 检查密码要求
返回：{ valid: boolean, errors: string[] }

AuthService

职责： 认证的业务逻辑

方法：

authenticate(email, password) - 验证凭据
generateToken(user) - 创建 JWT 令牌
hashPassword(password) - 使用 bcrypt 哈希密码

UserRepository

职责： 用户的数据库操作

方法：

findByEmail(email) - 通过邮箱获取用户
updateLastLogin(userId) - 更新最后登录时间戳

RateLimiter

职责： 防止暴力攻击

配置：

最大尝试次数：每个 IP 每分钟 5 次
阻止时长：超过限制后 15 分钟

数据模型

User

{
  id: string,
  email: string,
  passwordHash: string,
  name: string,
  createdAt: Date,
  lastLoginAt: Date
}

安全考虑

密码哈希： 使用 bcrypt，10 个盐轮数
JWT 令牌： 使用密钥签名，24 小时后过期
速率限制： 实现每个 IP 的速率限制
输入清理： 清理所有用户输入
仅 HTTPS： 在生产环境中强制使用 HTTPS

错误处理

错误	HTTP 代码	消息
无效凭据	401	"邮箱或密码无效"
缺少邮箱	400	"邮箱为必填项"
无效邮箱格式	400	"请输入有效的邮箱"
缺少密码	400	"密码为必填项"
密码太短	400	"密码必须至少 6 个字符"
超过速率限制	429	"登录尝试次数过多。请稍后再试。"
服务器错误	500	"发生错误。请重试。"

技术栈

后端： Node.js + Express
数据库： PostgreSQL
认证： JWT (jsonwebtoken)
密码哈希： bcrypt
速率限制： express-rate-limit
验证： validator.js

需求追溯

需求	设计组件
FR-1：登录表单	AuthController.login()
FR-2：凭据验证	AuthService.authenticate()
FR-3：输入验证	ValidationService
NFR-1：安全性	bcrypt、JWT、RateLimiter
NFR-2：性能	索引数据库查询
NFR-3：可用性	API 响应中的清晰错误消息


### 3.3 编写任务

打开 `.sce/specs/01-00-user-login/tasks.md` 并编写：

```markdown
# 用户登录 - 实现任务

## 阶段 1：设置和模型

- [ ] 1.1 设置项目依赖
  - 安装 express、bcrypt、jsonwebtoken、validator、express-rate-limit
  - 配置 TypeScript（如果使用）

- [ ] 1.2 创建 User 模型和数据库架构
  - 定义 User 接口/类
  - 为 users 表创建数据库迁移
  - 在 email 字段上添加索引

## 阶段 2：核心服务

- [ ] 2.1 实现 ValidationService
  - 创建 validateEmail() 方法
  - 创建 validatePassword() 方法
  - 编写单元测试

- [ ] 2.2 实现 AuthService
  - 创建 hashPassword() 方法
  - 创建 authenticate() 方法
  - 创建 generateToken() 方法
  - 编写单元测试

- [ ] 2.3 实现 UserRepository
  - 创建 findByEmail() 方法
  - 创建 updateLastLogin() 方法
  - 编写单元测试

## 阶段 3：API 实现

- [ ] 3.1 实现 AuthController
  - 创建 login() 端点处理器
  - 添加请求验证
  - 添加错误处理
  - 编写集成测试

- [ ] 3.2 实现速率限制
  - 配置 express-rate-limit
  - 应用到登录端点
  - 测试速率限制行为

## 阶段 4：测试和文档

- [ ] 4.1 编写全面的测试
  - 所有服务的单元测试
  - API 端点的集成测试
  - 测试错误场景
  - 测试速率限制

- [ ] 4.2 创建 API 文档
  - 记录请求/响应格式
  - 添加示例请求
  - 记录错误代码

- [ ] 4.3 手动测试
  - 使用有效凭据测试
  - 使用无效凭据测试
  - 测试输入验证
  - 测试速率限制
  - 测试性能（响应时间 < 500ms）

## 阶段 5：部署

- [ ] 5.1 环境配置
  - 设置环境变量
  - 配置 JWT 密钥
  - 配置数据库连接

- [ ] 5.2 部署到预发布环境
  - 部署代码
  - 运行冒烟测试
  - 验证功能

## 注意事项
- 所有密码必须在存储前进行哈希处理
- 使用环境变量存储密钥
- 遵循项目编码标准
- 在标记任务完成前编写测试

步骤 4：为你的 AI 工具导出上下文（1 分钟）

现在你的 Spec 已完成，为你的 AI 工具导出它：

（可选）先执行标准化流程和闸口检查：

sce spec pipeline run --spec 01-00-user-login
sce spec gate run --spec 01-00-user-login --json

sce context export 01-00-user-login

预期输出：

✓ 上下文已导出到 .sce/specs/01-00-user-login/context-export.md
✓ 上下文大小：3.2 KB
✓ 准备好与 AI 工具一起使用

创建的内容： 位于 .sce/specs/01-00-user-login/context-export.md 的文件，包含：

所有需求
完整设计
任务列表
项目结构
为 AI 消费格式化

步骤 5：使用你的 AI 工具（1 分钟）

现在使用你的 AI 工具来实现功能。选择你的工具：

选项 A：Claude Code / ChatGPT

打开上下文文件：

# macOS
cat .sce/specs/01-00-user-login/context-export.md | pbcopy

# Windows
type .sce\specs\01-00-user-login\context-export.md | clip

# Linux
cat .sce/specs/01-00-user-login/context-export.md | xclip -selection clipboard

开始新对话 与 Claude 或 ChatGPT

粘贴上下文 并说：

我已提供用户登录功能的完整 Spec。
请实现任务 1.1："设置项目依赖"

Claude/ChatGPT 将：
- 理解你的需求和设计
- 生成适当的代码
- 遵循你的架构决策

选项 B：Cursor

生成任务特定提示：

sce prompt generate 01-00-user-login 1.1

打开 Cursor Composer（Cmd+K 或 Ctrl+K）
粘贴生成的提示
Cursor 将：
- 读取你的 Spec 文件
- 生成匹配你设计的代码
- 直接创建或修改文件

选项 C：Windsurf / Cline

简单地告诉 AI：

使用 sce 检查 01-00-user-login 的 spec 并实现任务 1.1

AI 将：
- 自动运行 sce context export 01-00-user-login
- 读取导出的上下文
- 实现任务
- 更新任务状态

选项 D：VS Code + Copilot

创建新文件（例如 src/auth/AuthController.js）

添加引用你的 Spec 的注释：

// 任务 1.1：设置项目依赖
// 参见：.sce/specs/01-00-user-login/design.md
// 
// 安装：express、bcrypt、jsonwebtoken、validator、express-rate-limit

Copilot 将：
- 基于你的 Spec 建议代码
- 遵循你的设计模式
- 生成适当的实现

步骤 6：跟踪你的进度（30 秒）

完成任务后，更新任务状态：

编辑 .sce/specs/01-00-user-login/tasks.md：

- [x] 1.1 设置项目依赖  ← 从 [ ] 改为 [x]
- [ ] 1.2 创建 User 模型和数据库架构

检查你的进度：

sce status

预期输出：

Project: my-awesome-app
Specs: 1

Spec: 01-00-user-login
  Total tasks: 15
  Completed: 1
  In progress: 0
  Not started: 14
  Progress: 6.7%

下一步

恭喜！你已完成快速入门。以下是接下来要做的：

了解更多关于集成的信息

选择你的 AI 工具获取详细指导：

Cursor 指南 - 深入了解 Cursor 集成
Claude 指南 - Claude Code 最佳实践
Windsurf 指南 - 使用 Windsurf 的自动化工作流
通用指南 - 适用于任何 AI 工具

探索高级功能

集成模式 - 原生、手动和 Watch 模式
Spec 工作流 - 深入了解 Spec 创建
命令参考 - 所有 sce 命令

查看真实示例

API 功能示例 - 完整的 RESTful API Spec
UI 功能示例 - React 仪表板 Spec
CLI 功能示例 - CLI 命令 Spec

故障排除

问题："sce: command not found"

解决方案：

重启终端
检查 npm 全局 bin 是否在 PATH 中：
```
npm config get prefix
```

如需要，添加到 PATH（macOS/Linux）：

export PATH="$(npm config get prefix)/bin:$PATH"

问题：上下文文件对 AI 工具来说太大

解决方案： 生成任务特定提示：

sce prompt generate 01-00-user-login 1.1

这会为该任务创建一个更小、更集中的上下文。

问题：AI 不遵循我的设计

解决方案：

使你的 design.md 更详细
在 design.md 中添加代码示例
在提示中明确说明："严格遵循设计文档"

包含 steering 规则：

sce context export 01-00-user-login --steering

问题：找不到我的 Spec 文件

解决方案： 所有 Spec 都在 .sce/specs/ 中：

ls .sce/specs/

总结

你已学会如何：

✅ 安装和设置 sce
✅ 创建包含需求、设计和任务的结构化 Spec
✅ 为 AI 工具导出上下文
✅ 使用 AI 基于 Spec 实现功能
✅ 跟踪实现进度

sce 工作流：

bootstrap Spec → pipeline/gate → 导出上下文 → AI 实现 → 更新任务 → 重复

准备好构建你的下一个功能了吗？ 🚀

sce spec bootstrap --name 02-00-your-next-feature --non-interactive

版本: 1.46.2
最后更新: 2026-02-14

FilesExpand file tree

quick-start.md

Latest commit

History

quick-start.md

File metadata and controls

快速入门指南

你将学到什么

为什么它比“随手提示词开发”更稳

前置条件

步骤 1：安装 sce（30 秒）

步骤 2：在项目中采用 sce（1 分钟）

步骤 3：生成你的第一个 Spec 初稿（2 分钟）

3.0（可选）：30 秒验证可量化交付

3.1 编写需求

3.2 编写设计

API 设计

POST /api/auth/login

组件设计

AuthController

ValidationService

AuthService

UserRepository

RateLimiter

数据模型

User

安全考虑

错误处理

技术栈

需求追溯

步骤 4：为你的 AI 工具导出上下文（1 分钟）

步骤 5：使用你的 AI 工具（1 分钟）

选项 A：Claude Code / ChatGPT

选项 B：Cursor

选项 C：Windsurf / Cline

选项 D：VS Code + Copilot

步骤 6：跟踪你的进度（30 秒）

下一步

了解更多关于集成的信息

探索高级功能

查看真实示例

故障排除

问题："sce: command not found"

问题：上下文文件对 AI 工具来说太大

问题：AI 不遵循我的设计

问题：找不到我的 Spec 文件

更多帮助

总结