CLI 命令

所有 LeanSpec CLI 命令的完整参考。

全局选项

适用于所有命令：

--help - 显示命令帮助
--version - 显示 LeanSpec 版本

命令

`lean-spec init`

在您的项目中初始化 LeanSpec。

lean-spec init

交互式提示：

选择设置路径（快速开始、选择模板或自定义）
处理现有文件（合并、备份或跳过）
配置初始设置

创建内容：

.lean-spec/config.json - 配置文件
.lean-spec/templates/ - 自定义模板目录
specs/ - 规范目录
AGENTS.md - AI 代理集成指导（如果不存在）

选项：

无（完全交互式）

`lean-spec create`

创建新规范。

lean-spec create <name> [options]

参数：

<name> - 规范名称（必需）

选项：

--title <title> - 设置自定义标题
--description <desc> - 设置初始描述
--tags <tags> - 逗号分隔的标签
--priority <priority> - 设置优先级（low、medium、high、critical）
--assignee <name> - 设置受让人
--template <template> - 使用特定模板
--field <name=value> - 设置自定义字段（可多次使用）
--no-prefix - 即使配置了也跳过日期前缀

示例：

# 基本规范
lean-spec create user-authentication

# 带元数据的规范
lean-spec create user-auth --status=planned --priority=high --tags=security,api

# 带自定义字段的规范
lean-spec create user-auth --field epic=PROJ-123 --field sprint=42

输出：

✓ 已创建：specs/001-user-authentication/
  编辑：specs/001-user-authentication/README.md

行为：

创建 specs/NNN-name/ 目录（扁平结构，全局编号）
从模板生成 README.md
分配顺序编号（NNN），在所有规范中全局编号
使用元数据设置前置元数据

注意：默认为扁平结构。对于基于日期的分组，在 .lean-spec/config.json 中配置 pattern: "custom"。

`lean-spec list`

列出所有规范并可选过滤。

lean-spec list [options]

选项：

--archived - 包括已归档的规范
--status <status> - 按状态过滤（planned、in-progress、complete、archived）
--priority <priority> - 按优先级过滤（low、medium、high、critical）
--tag <tag> - 按标签过滤（对多个标签使用多个 --tag 标志）
--assignee <name> - 按受让人过滤
--field <name=value> - 按自定义字段过滤（可指定多个）
--sort <field> - 按字段排序（id、created、name、status、priority）（默认：id）
--order <order> - 排序顺序（asc、desc）（默认：desc）

示例：

# 列出所有规范
lean-spec list

# 按状态过滤
lean-spec list --status=in-progress
lean-spec list --status=planned

# 按优先级过滤
lean-spec list --priority=high

# 按标签过滤
lean-spec list --tag api

# 按多个标签过滤
lean-spec list --tag api --tag backend

# 组合过滤器
lean-spec list --status planned --priority high --tag api

# 按自定义字段过滤
lean-spec list --field epic=PROJ-123

输出：

=== 规范 ===

📅 specs/001-user-authentication
   创建：2025-11-02 · 优先级：high · 标签：security, api

⏳ specs/002-password-reset
   创建：2025-11-02 · 优先级：medium

注意：输出显示扁平结构（默认）。配置日期分组后，路径将为 specs/YYYYMMDD/NNN-name/。

状态图标：

📅 计划中
⏳ 进行中
✅ 完成
📦 已归档

`lean-spec update`

更新规范元数据。

lean-spec update <spec> [options]

参数：

<spec> - 规范标识符（必需）。可以是：
- 规范编号：42 或 042
- 规范名称：unified-dashboard
- 完整文件夹：045-unified-dashboard

选项：

--status <status> - 更新状态（planned、in-progress、complete、archived）
--priority <priority> - 更新优先级（low、medium、high、critical）
--tags <tags> - 更新标签（逗号分隔，替换现有标签）
--assignee <name> - 设置受让人
--field <name=value> - 更新自定义字段（可多次使用）

示例：

# 更新状态（使用规范编号）
lean-spec update 1 --status=in-progress

# 更新优先级（使用规范名称）
lean-spec update user-auth --priority=critical

# 更新标签
lean-spec update 001-user-auth --tags=security,api,mvp

# 更新自定义字段
lean-spec update 1 --field epic=PROJ-123

# 更新多个字段
lean-spec update 1 --status=complete --priority=high

输出：

✓ 已更新：specs/001-user-auth
  字段：status, priority

特殊行为：

将状态设置为 complete 会自动添加 completed 时间戳
README.md 中的可视徽章自动更新
前置元数据和徽章保持同步

`lean-spec search`

跨所有规范全文搜索。

lean-spec search <query> [options]

参数：

<query> - 搜索查询（必需）

选项：

--status <status> - 按状态过滤结果
--priority <priority> - 按优先级过滤结果
--tag <tag> - 按标签过滤结果
--assignee <name> - 按受让人过滤结果
--field <name=value> - 按自定义字段过滤结果（可指定多个）

示例：

# 基本搜索
lean-spec search "authentication"

# 带过滤器的搜索
lean-spec search "JWT token" --status=in-progress
lean-spec search "API" --tag=security
lean-spec search "password" --field epic=PROJ-123

输出：

找到 2 个匹配 "authentication" 的规范：

📅 specs/001-user-authentication
   创建：2025-11-02
   匹配位置：概述、关键场景

⏳ specs/003-two-factor-auth
   创建：2025-11-02
   匹配位置：技术方法

搜索行为：

搜索规范内容（README.md）
不区分大小写
搜索标题、概述、场景、标准等
不搜索前置元数据

`lean-spec archive`

归档已完成的规范。

lean-spec archive <spec>

参数：

<spec> - 规范标识符（必需）。可以是：
- 规范编号：42 或 042
- 规范名称：unified-dashboard
- 完整文件夹：045-unified-dashboard

示例：

# 按规范编号归档
lean-spec archive 1

# 按名称归档
lean-spec archive user-auth

输出：

✓ 已归档：specs/001-user-auth
  移至：specs/archived/001-user-auth

行为：

将规范从 specs/ 移至 specs/archived/
保留目录结构
保留所有元数据
规范不再默认出现在 lean-spec list 中

最佳实践：

归档前将状态更新为 complete
工作完全完成后归档规范
用于保持活动工作区清洁

`lean-spec view`

查看规范内容。

lean-spec view <spec> [options]

参数：

<spec> - 规范标识符（必需）。可以是：
- 规范编号：42 或 042
- 规范名称：unified-dashboard
- 完整文件夹：045-unified-dashboard

选项：

--raw - 输出原始 markdown（用于管道/脚本）
--json - 输出为 JSON
--no-color - 禁用颜色

示例：

# 查看格式化的规范
lean-spec view 001-user-authentication

# 获取原始 markdown（用于脚本）
lean-spec view 001-user-auth --raw | grep "TODO"

# 获取结构化 JSON
lean-spec view 001-user-auth --json | jq '.frontmatter.status'

默认输出（格式化）：

━━━ 001-user-authentication ━━━

📅 状态：planned
🟡 优先级：high
📆 创建：2025-11-02
🏷️  标签：#security #api

────────────────────────────────────────────────────────────

# 用户身份验证

## 概述
...

原始输出（--raw）：

---
status: planned
priority: high
created: 2025-11-02
tags:
  - security
  - api
---

# 用户身份验证

## 概述
...

JSON 输出（--json）：

{
  "name": "001-user-authentication",
  "path": "specs/001-user-authentication",
  "frontmatter": {
    "status": "planned",
    "priority": "high",
    "created": "2025-11-02",
    "tags": ["security", "api"]
  },
  "content": "# 用户身份验证\n\n## 概述\n..."
}

用例：

默认：人类可读的规范查看
--raw：管道到其他工具、AI 上下文、版本控制差异
--json：程序化访问、CI/CD、集成

`lean-spec open`

在编辑器中打开规范。

lean-spec open <spec> [options]

参数：

<spec> - 规范标识符（必需）。可以是：
- 规范编号：42 或 042
- 规范名称：unified-dashboard
- 完整文件夹：045-unified-dashboard

选项：

--editor <editor> - 指定编辑器命令

示例：

# 在默认编辑器中打开
lean-spec open 001-user-authentication

# 在特定编辑器中打开
lean-spec open 001-user-auth --editor=code
lean-spec open 001-user-auth --editor=vim

编辑器选择：

如果提供了 --editor 标志
$VISUAL 环境变量
$EDITOR 环境变量
系统默认（macOS 上的 open、Linux 上的 xdg-open、Windows 上的 start）

行为：

打开规范的 README.md 文件
GUI 编辑器（VS Code、Atom）不会阻塞终端
终端编辑器（vim、nano）在关闭前阻塞

`lean-spec templates`

列出可用的项目模板。

lean-spec templates

输出：

=== 可用模板 ===

minimal        仅文件夹结构，无额外内容
standard       推荐 - 包括 AGENTS.md（默认）
enterprise     带审批和合规性的治理

使用：lean-spec init
然后选择"选择模板"选项

`lean-spec stats`

显示规范统计信息。

lean-spec stats

输出：

=== 规范统计 ===

总规范数：15
  计划中：5
  进行中：7
  完成：3

按优先级：
  关键：2
  高：6
  中：5
  低：2

按标签：
  api：8
  security：5
  ui：3

`lean-spec board`

按状态查看规范（看板风格）。

lean-spec board

输出：

╔═══════════════════════════════════════════════════════════╗
║                    LeanSpec 看板                          ║
╠═══════════════════════════════════════════════════════════╣
║ 计划中           进行中              完成                 ║
╠─────────────────┬────────────────────┬────────────────────╣
║ user-auth       │ api-gateway        │ login-ui           ║
║ rate-limiting   │ database-setup     │ password-hash      ║
║ oauth-provider  │ error-handling     │ session-mgmt       ║
║                 │                    │                    ║
║ 3 个规范        │ 3 个规范           │ 3 个规范           ║
╚═════════════════╧════════════════════╧════════════════════╝

`lean-spec deps`

显示规范的依赖关系（即将推出）。

lean-spec deps <spec>

参数：

<spec> - 规范标识符。可以是：
- 规范编号：42 或 042
- 规范名称：unified-dashboard
- 完整文件夹：045-unified-dashboard

**注意：**此功能已计划但尚未实现。

规范标识符

接受 <spec> 参数的所有命令都支持灵活格式：

# 规范编号（带或不带填充）
42
042

# 规范名称
unified-dashboard

# 完整文件夹名称
045-unified-dashboard

# 使用旧的基于日期的结构（仍然支持）
specs/20251102/001-user-auth
20251102/001-user-auth
001-user-auth

无论使用哪种格式，LeanSpec 都会找到规范。

配置

命令遵循 .lean-spec/config.json 中的设置：

{
  "template": "spec-template.md",
  "specsDir": "specs",
  "structure": {
    "pattern": "flat",
    "sequenceDigits": 3,
    "defaultFile": "README.md"
  },
  "frontmatter": {
    "required": ["status", "created"],
    "optional": ["tags", "priority"],
    "custom": {
      "epic": "string",
      "sprint": "number"
    }
  }
}

详见配置参考。

退出代码

0 - 成功
1 - 错误（无效参数、文件未找到等）
2 - 用户取消操作

下一步：探索配置或了解自定义字段。

全局选项​

命令​

lean-spec init​

lean-spec create​

lean-spec list​

lean-spec update​

lean-spec search​

lean-spec archive​

lean-spec view​

lean-spec open​

lean-spec templates​

lean-spec stats​

lean-spec board​

lean-spec deps​

规范标识符​

配置​

退出代码​

全局选项

命令

`lean-spec init`

`lean-spec create`

`lean-spec list`

`lean-spec update`

`lean-spec search`

`lean-spec archive`

`lean-spec view`

`lean-spec open`

`lean-spec templates`

`lean-spec stats`

`lean-spec board`

`lean-spec deps`

规范标识符

配置

退出代码