SpecFlow CLI

SpecFlow 命令行工具 —— 需求全生命周期管理的终端入口。

功能特性

• 需求管理：查询需求列表、查看详情、获取关联文档、状态流转
• 任务管理：查询任务列表、查看详情、状态流转
• 评审管理：查询评审列表、查看详情、提交技术方案/代码评审
• 配置管理：支持配置文件和环境变量双重配置方式
• 双模式输出：JSON 格式（默认，适合管道处理）+ 人类可读格式（--pretty）
• CI/CD 友好：非交互式设计，退出码语义明确，易于集成到自动化流水线

快速开始

安装

# 通过 npm 全局安装
npm install -g @yidun/specflow-cli

# 验证安装
specflow --version

源码安装（开发者）

# 克隆仓库
git clone <repository-url>
cd specflow/packages/specflow-cli

# 安装依赖并构建
npm install
npm run build

# 链接到全局（可选）
npm link

配置

方式一：配置文件（推荐）

# 设置服务端点
specflow config set endpoint https://specflow.example.com

# 设置 API Key
specflow config set apiKey sfk_your_api_key_here

# 设置默认评审人（可选）
specflow config set defaultReviewers zhangsan,lisi,wangwu

# 设置默认 passport（需求创建人/任务经办人，不传 --passport 时使用）
specflow config set passport your_passport

# 查看配置
specflow config get --pretty

方式二：环境变量

export SPECFLOW_ENDPOINT=https://specflow.example.com
export SPECFLOW_API_KEY=sfk_your_api_key_here

# 现在可以直接使用，无需配置文件
specflow req list

优先级：环境变量 > 配置文件

命令参考

全局选项

| 选项 | 说明 | |------|------| | --pretty | 以人类可读的格式输出（表格/彩色文本） | | -h, --help | 显示帮助信息 | | -V, --version | 显示版本号 |

配置管理

# 设置配置项
specflow config set <key> <value>

# 支持的配置项：
#   apiKey              API 鉴权密钥
#   endpoint            服务端点地址
#   defaultReviewers    默认评审人（逗号分隔）
#   passport            默认查询当前用户的 passport（不传 --passport 时使用）

# 查看当前配置
specflow config get
specflow config get --pretty

需求管理

# 查询需求列表
specflow req list
specflow req list --status DEV_IN_PROGRESS,CODE_REVIEW    # 按状态过滤
specflow req list --passport zhangsan                       # 按创建人过滤（精确）
specflow req list --title "登录功能"                        # 按标题模糊查询
specflow req list --passport all                            # 查询所有需求，忽略默认 passport
specflow req list --page 2 --page-size 50                  # 分页
specflow req list --pretty                                 # 表格输出

# 获取需求详情
specflow req get <id>
specflow req get 123 --pretty

# 获取需求关联文档
specflow req docs <id>
specflow req docs 123 --pretty

# 变更需求状态
specflow req transition <id> <status> -r <reason>
specflow req transition 123 DEV_IN_PROGRESS -r "开始开发"

任务管理

# 查询任务列表
specflow task list
specflow task list --req 123                               # 按需求过滤
specflow task list --status CODE_REVIEW,DEVELOPED          # 按状态过滤
specflow task list --passport zhangsan                     # 按经办人过滤（精确）
specflow task list --title "登录接口"                      # 按标题模糊查询
specflow task list --passport all                          # 查询所有任务，忽略默认 passport
specflow task list --pretty

# 获取任务详情
specflow task get <id>
specflow task get 456 --pretty

# 变更任务状态
specflow task transition <id> <status>
specflow task transition 456 CODE_REVIEW

评审管理

# 查询评审列表
specflow review list
specflow review list --type TECH_SCHEME_REVIEW             # 按类型过滤
specflow review list --status PENDING,APPROVED             # 按状态过滤
specflow review list --pretty

# 获取评审详情
specflow review get <id>
specflow review get 789 --pretty

# 提交技术方案评审
specflow review submit-tech <taskId> --content-file <path>
specflow review submit-tech 456 --content-file ./tech-spec.md
specflow review submit-tech 456 --content-file ./plan.md,./spec.md
specflow review submit-tech 456 --content "# 技术方案\n..." --reviewers zhangsan,lisi

# 提交代码评审
specflow review submit-code <taskId> --content-file <path>
specflow review submit-code 456 --content-file ./review-report.md
specflow review submit-code 456 --content-file ./report.md --skip-review
specflow review submit-code 456 --content-file ./report.md --skip-and-begin-dev

评审提交选项

| 选项 | 说明 | |------|------| | --content <markdown> | 直接提供评审内容（Markdown 格式） | | --content-file <paths> | 从文件读取评审内容（支持多文件，逗号分隔） | | --reviewers <passports> | 指定评审人（逗号分隔），未指定则使用 defaultReviewers | | --deadline <timestamp> | 评审截止时间（毫秒时间戳） | | --skip-review | 跳过评审流程，自动通过 | | --skip-and-begin-dev | 跳过评审并直接进入代码开发中状态（仅代码评审） |

输出格式

JSON 格式（默认）

适合管道处理和脚本集成：

# 查询并提取标题
specflow req list | jq '.records[].title'

# 获取第一个需求的 ID
specflow req list | jq '.records[0].id'

# 过滤特定状态的任务
specflow task list --req 123 | jq '.records[] | select(.status == "CODE_REVIEW")'

Pretty 格式

适合人工查看：

$ specflow req list --pretty
┌─────┬─────────────────────┬──────────────┬──────────┬────────────┐
│ ID  │ 标题                │ 状态         │ 创建人   │ 截止时间   │
├─────┼─────────────────────┼──────────────┼──────────┼────────────┤
│ 123 │ 用户认证功能        │ 开发中       │ zhangsan │ 2024/12/31 │
│ 124 │ 报表导出优化        │ 待排期       │ lisi     │ -          │
└─────┴─────────────────────┴──────────────┴──────────┴────────────┘

退出码

| 退出码 | 含义 | 说明 | |--------|------|------| | 0 | 成功 | 命令执行成功 | | 1 | 业务错误 | 如需求不存在、状态不合法等 | | 2 | 配置缺失 | apiKey 或 endpoint 未设置 | | 3 | 系统错误 | 网络超时、DNS 失败等 |

CI/CD 集成示例

GitHub Actions

name: SpecFlow Integration

on: [push]

jobs:
  sync-requirements:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install SpecFlow CLI
        run: npm install -g @yidun/specflow-cli
      
      - name: Check Requirement Status
        env:
          SPECFLOW_ENDPOINT: ${{ secrets.SPECFLOW_ENDPOINT }}
          SPECFLOW_API_KEY: ${{ secrets.SPECFLOW_API_KEY }}
        run: |
          # 获取需求详情
          specflow req get ${{ github.event.inputs.requirement_id }}
          
          # 检查任务状态
          TASKS=$(specflow task list --req ${{ github.event.inputs.requirement_id }})
          echo "Tasks: $TASKS"

GitLab CI

specflow-sync:
  stage: deploy
  image: node:18
  before_script:
    - npm install -g @yidun/specflow-cli
  script:
    - export SPECFLOW_ENDPOINT=$SPECFLOW_ENDPOINT
    - export SPECFLOW_API_KEY=$SPECFLOW_API_KEY
    - specflow req transition $REQ_ID DEPLOYED -r "CI自动部署"
  only:
    - main

开发指南

项目结构

packages/specflow-cli/
├── src/
│   ├── index.ts              # CLI 入口
│   ├── commands/             # 命令实现
│   │   ├── config/           # 配置管理命令
│   │   ├── req/              # 需求管理命令
│   │   ├── task/             # 任务管理命令
│   │   └── review/           # 评审管理命令
│   ├── api/                  # HTTP API 封装
│   │   ├── client.ts         # Axios 实例
│   │   ├── requirements.ts   # 需求 API
│   │   ├── tasks.ts          # 任务 API
│   │   └── reviews.ts        # 评审 API
│   ├── config/               # 配置管理模块
│   ├── output/               # 输出格式化模块
│   ├── types/                # TypeScript 类型定义
│   └── utils/                # 工具函数
├── package.json
├── tsconfig.json
└── README.md

开发命令

# 开发模式（热重载）
npm run dev -- req list --pretty

# 运行测试
npm test

# 持续测试
npm run test:watch

# 构建
npm run build

# 调试模式（输出请求/响应详情）
SPECFLOW_DEBUG=1 specflow req get 123

添加新命令

1. 在 src/commands/<group>/ 下创建命令文件
2. 在 src/commands/<group>/index.ts 中注册命令
3. 如需新 API，在 src/api/ 下添加对应模块
4. 更新本 README 文档

调试

启用调试模式查看详细的请求/响应信息：

SPECFLOW_DEBUG=1 specflow req get 123

输出示例：

[DEBUG] → GET https://specflow.example.com/api/open/v2/requirements/123
{
  "params": {},
  "headers": { "X-SF-API-Key": "***1234" },
  "body": undefined
}
[DEBUG] ← RAW RESPONSE 200 /api/open/v2/requirements/123
{
  "code": 2000,
  "data": { ... }
}

常见问题

Q: 如何获取 API Key？

A: 登录 SpecFlow Web 界面，进入「个人设置」→「API 密钥」页面生成。

Q: 支持哪些状态值？

A: 状态值与 SpecFlow 系统保持一致，常见状态包括：

• 需求：PENDING, SCHEDULED, DEV_IN_PROGRESS, CODE_REVIEW, DEVELOPED, DEPLOYED, CLOSED
• 任务：PENDING, DEV_IN_PROGRESS, CODE_REVIEW, DEVELOPED, ACCEPTED, CLOSED

Q: 如何批量操作？

A: 结合 jq 和 shell 循环实现批量操作：

# 批量获取需求详情
for id in $(specflow req list | jq '.records[].id'); do
  specflow req get $id > "req_$id.json"
done

Q: Windows 支持吗？

A: 当前主要支持 macOS 和 Linux。Windows 支持正在开发中。

技术栈

• TypeScript 5.6
• Commander.js 12 - 命令行框架
• Axios 1.x - HTTP 客户端
• Chalk 5 - 终端样式
• cli-table3 - 表格输出
• conf 13 - 配置管理
• Vitest 2 - 测试框架

许可证

MIT License © 2024 SpecFlow Team