specctl

交互式 CLI 工具，用于规格主仓与实现子仓之间的 release / consume 协作流程。

specctl 解决的核心问题：在多仓协作中，规格主仓发布版本快照（release），实现子仓选择性消费（consume），通过 Git tag 绑定实现版本可追溯、差异可感知、升级可检测。

功能概览

| 命令 | 场景 | 说明 | |------|------|------| | specctl release | 规格主仓 | 校验 Feature、生成 manifest.json + RELEASE.md、提交并打 Git tag | | specctl consume | 实现子仓 | 从远端 release tag 选择性消费 Feature 和共享层文件 | | specctl diff | 实现子仓 | 对比两个 release tag 之间的 manifest 差异 | | specctl check-update | 实现子仓 | 检测当前消费版本是否有可用更新 |

安装

pnpm install
pnpm build

链接为全局命令：

pnpm link --global
specctl --help

环境要求

• Node.js >= 18
• Git
• GITLAB_TOKEN 环境变量（consume / diff / check-update 需要访问远程仓库）

命令详解

specctl release

在规格主仓根目录执行，将当前工作区的共享层和 Feature 打包为一个不可变的版本快照。

specctl release

交互流程：

1. 输入版本号、类型（working / final）、标题（有缓存时回车复用）
2. 自动校验 Git 环境（分支、工作区状态、tag 冲突）
3. 扫描共享层（global/、contracts/、models/）和 Feature（specs/*/）
4. 三层校验每个 Feature 的文件完整性：
   • 必备项（6 项）：feature.yaml、README.md、spec.md、plan.md、tasks.md、acceptance.md
   • 增强项（5 项）：research.md、data-model.md、quickstart.md、tasks-fe.md、tasks-be.md
   • 治理项（2 项）：alignment-checklist.md、checklists/
5. 选择要纳入的 Feature（Space 选择 / A 全选 / I 反选）
6. 必备项不完整时警告并要求确认
7. 预览 release 草稿，确认后原子提交（manifest.json + RELEASE.md）并创建 tag
8. tag 创建失败时自动回滚 commit

产出物：

• manifest.json — 版本清单（提交到 git）
• RELEASE.md — 版本发布记录（提交到 git）
• Git tag — 格式为 spec-release/{version}-r{revision}（working）或 spec-release/{version}（final）

specctl consume

在实现子仓中执行，从远端主仓的 release tag 中选择性消费规格文件。

specctl consume

交互流程：

1. 输入主仓 Git URL（有缓存时直接回车复用）
2. 列出远端所有 release tag，选择要消费的版本
3. 预览 manifest 信息（版本、tag、共享层文件数、Feature 列表）
4. 自动差异展示：如果子仓已有 specs-version.json（上次消费留下），自动展示与目标版本的差异摘要
5. 选择要消费的 Feature
6. 确认后执行消费：共享层全量 + 所选 Feature 写入 .spec-consume/

产出物：

• .spec-consume/ — 消费的规格文件（建议 gitignore）
• specs-version.json — 消费声明（提交到 git），记录：
  • specRepo — 来源仓库地址
  • specTag — 消费的 tag
  • specCommit — tag 对应的 commit hash
  • releaseVersion / releaseType / releaseRevision — 版本信息
  • featureCodes — 消费的 Feature 列表
  • syncedAt — 消费时间
  • branch — 当前分支
  • domain — 可选，用户手动配置的分域标识（更新时自动保留）

specctl diff

对比两个 release tag 之间的 manifest 差异。

specctl diff <old-tag> <new-tag>

# 示例
specctl diff spec-release/0.0.1-r1 spec-release/0.0.1-r3

输出内容：

• 共享层变更：按路径判断新增 / 删除
• Feature 变更：按 featureKey 匹配，通过 featureVersion 和 featureStatus 变化判定新增 / 移除 / 修改
• 两个版本无差异时提示"内容一致，无需升级"

主仓地址自动从 specs-version.json 或缓存中读取。

specctl check-update

检测当前消费版本是否有可用的更新。

specctl check-update

• 读取 specs-version.json 中的版本信息
• 查询远端同 releaseVersion 下所有比当前 tag 更新的版本（working + final 都列出）
• 无 specs-version.json 时提示先执行 specctl consume

主仓目录结构

<spec-repo>/
├── global/              # 全局共享定义
├── contracts/           # 接口契约
├── models/              # 数据模型
├── manifest.json        # release 产出（自动生成）
├── RELEASE.md           # 版本记录（自动生成）
└── specs/               # Feature 目录
    └── <feature-key>/
        ├── feature.yaml          # 元信息（必需）
        ├── README.md             # Feature 概述
        ├── spec.md               # 功能规格
        ├── plan.md               # 实施计划
        ├── tasks.md              # 任务拆分
        ├── acceptance.md         # 验收标准
        ├── research.md           # 技术调研
        ├── data-model.md         # 数据模型
        ├── quickstart.md         # 快速上手
        ├── tasks-fe.md           # 前端任务
        ├── tasks-be.md           # 后端任务
        ├── alignment-checklist.md # 对齐检查
        └── checklists/           # 治理检查单

feature.yaml 格式

featureKey: "user-auth"
title: "用户认证模块"
featureVersion: "1.0.0"
featureStatus: "working"   # working | final
targetRelease: "1.0.0"

子仓产出物

<impl-repo>/
├── specs-version.json     # 消费声明（提交到 git）
├── .spec-consume/         # 消费的规格文件（建议 gitignore）
│   ├── global/
│   ├── contracts/
│   ├── models/
│   └── specs/
└── .specctl-cache.json    # 输入缓存（自动 gitignore）

版本标签规则

| 类型 | 格式 | 示例 | |------|------|------| | working | spec-release/{version}-r{revision} | spec-release/1.0.0-r1 | | final | spec-release/{version} | spec-release/1.0.0 |

• working 版本支持多次迭代（r1, r2, r3...），revision 自动递增
• final 版本每个 releaseVersion 只能发布一次

开发

pnpm dev          # 监听模式构建
pnpm build        # 构建
pnpm test         # 运行测试
pnpm lint         # 代码检查
pnpm format       # 格式化

许可证

ISC