Speckit Enhancer CLI

🚀 为 Spec-Kit 工作流提供强大的 CLI 工具和可视化 Dashboard

功能特性 • 快速开始 • 命令文档 • 使用示例

简介

Speckit Enhancer CLI 是一个为 Spec-Kit 工作流设计的命令行工具，提供：

• 📊 可视化 Dashboard - 实时查看和编辑规格文档、任务和评论
• 📝 文档管理 - 读取、写入、监听文档变化
• 💬 评论系统 - 为文档添加锚点评论和讨论
• 🔄 实时同步 - 文件变化自动同步到 UI
• 🎨 现代化 UI - GitHub 风格的暗色主题界面

功能特性

Dashboard UI

• ✨ 现代化的 Web 界面，支持暗色主题
• 📂 按特性分类浏览项目文档（spec、plan、tasks 等）
• ✏️ Markdown 文档实时编辑和预览
• 💬 支持文档锚点评论和线程讨论
• 🔍 全文搜索和快速导航
• 📊 特性统计面板（进度、风险、协作指标）
• 🔄 文件变化自动检测和刷新提示

CLI 命令

• 🖥️ Dashboard 管理 - 启动本地 Web 服务
• 📄 文档操作 - 列出、读取、写入项目文档
• 👁️ 文件监听 - 实时监控文件变化
• 💬 评论管理 - 添加、查询、更新、删除评论
• 🔧 项目管理 - 项目信息查看和验证

安装

全局安装（推荐）

npm install -g @superying/speckit-enhancer-cli

安装后可使用 speckit-enhancer 或缩写 ske 命令。

项目内安装

npm install @superying/speckit-enhancer-cli

然后通过 npx 使用：

npx ske dashboard

快速开始

1. 启动 Dashboard

在 Spec-Kit 项目根目录下运行：

ske dashboard

或指定项目路径：

ske dashboard /path/to/your/speckit-project

2. 自定义配置

# 指定端口和主机
ske dashboard --port 8080 --host 0.0.0.0

# 启动但不自动打开浏览器
ske dashboard --no-open

# 启用详细日志
ske dashboard --verbose

3. 访问 Dashboard

浏览器自动打开 http://localhost:3000（或你指定的端口）

命令文档

Dashboard 命令

ske dashboard [options] [project-path]

启动 Dashboard Web UI 服务。

参数：

• project-path - 项目根目录路径（默认：当前目录 .）

选项：

• -p, --port <port> - 服务端口（默认：3000）
• -h, --host <host> - 服务主机（默认：localhost）
• -o, --open - 自动打开浏览器（默认：true）
• --no-open - 不自动打开浏览器
• -v, --verbose - 详细日志输出（默认：false）

别名： dash, dashboard start

示例：

# 默认启动（端口 3000，自动打开浏览器）
ske dashboard

# 自定义端口和主机
ske dashboard -p 8080 -h 0.0.0.0

# 不自动打开浏览器
ske dashboard --no-open

# 启用详细日志
ske dashboard -v

Docs 命令

ske docs list [options] [project-path]

列出项目结构和所有文档。

参数：

• project-path - 项目根目录路径（默认：.）

选项：

• -f, --format <format> - 输出格式：json 或 text（默认：json）
• -v, --verbose - 详细输出（默认：false）

示例：

# 列出当前项目的文档
ske docs list

# 以文本格式输出
ske docs list --format text

ske docs read <file-path> [options]

读取文档内容。

参数：

• file-path - 文档文件路径（必需）

选项：

• -f, --format <format> - 输出格式：json 或 text（默认：json）
• -r, --project-root <path> - 项目根目录（默认：当前工作目录）

示例：

# 读取规格文档
ske docs read specs/001-feature-name/spec.md

# 以文本格式输出
ske docs read specs/001-feature-name/spec.md --format text

ske docs write <file-path> <content> [options]

写入文档内容。

参数：

• file-path - 文档文件路径（必需）
• content - 文档内容（必需）

选项：

• -f, --format <format> - 输出格式：json 或 text（默认：json）
• -r, --project-root <path> - 项目根目录（默认：当前工作目录）
• -e, --expected-mtime <timestamp> - 预期的最后修改时间（用于冲突检测）
• -F, --force - 强制写入，忽略冲突检测（默认：false）

示例：

# 写入内容
ske docs write specs/001-feature-name/notes.md "# 笔记\n\n这是内容"

# 带冲突检测的写入
ske docs write specs/001-feature-name/spec.md "更新内容" -e 1700000000000

# 强制写入（忽略冲突）
ske docs write specs/001-feature-name/spec.md "新内容" --force

ske docs watch <file-path> [options]

监听文件变化。

参数：

• file-path - 要监听的文件路径（必需）

选项：

• -f, --format <format> - 输出格式：json 或 text（默认：json）
• -r, --project-root <path> - 项目根目录（默认：当前工作目录）
• -v, --verbose - 详细输出（默认：false）

示例：

# 监听规格文档变化
ske docs watch specs/001-feature-name/spec.md

# 启用详细日志
ske docs watch specs/001-feature-name/spec.md -v

Comment 命令

ske comment add [options]

为文档添加新评论。

必需选项：

• -d, --document-path <path> - 文档路径
• -f, --feature-id <id> - 特性 ID
• -c, --content <text> - 评论内容
• -a, --author <name> - 作者名称
• -s, --start-line <number> - 起始行号
• -e, --end-line <number> - 结束行号
• -t, --text-fragment <text> - 选中的文本片段

可选选项：

• --context-before <text> - 前置上下文
• --context-after <text> - 后置上下文
• -p, --parent-id <id> - 父评论 ID（用于回复）
• -F, --format <format> - 输出格式（默认：json）
• -r, --project-root <path> - 项目根目录（默认：当前工作目录）

示例：

ske comment add \
  -d "specs/001-feature-name/spec.md" \
  -f "001-feature-name" \
  -c "这里需要更详细的说明" \
  -a "张三" \
  -s 10 \
  -e 12 \
  -t "## 需求描述"

ske comment list [options]

列出文档的所有评论。

必需选项：

• -d, --document-path <path> - 文档路径
• -f, --feature-id <id> - 特性 ID

可选选项：

• -S, --status <status> - 按状态过滤：open、resolved、archived
• -F, --format <format> - 输出格式（默认：json）
• -r, --project-root <path> - 项目根目录（默认：当前工作目录）

示例：

# 列出所有评论
ske comment list -d "specs/001-feature-name/spec.md" -f "001-feature-name"

# 只列出未解决的评论
ske comment list -d "specs/001-feature-name/spec.md" -f "001-feature-name" -S open

ske comment update <comment-id> [options]

更新评论内容或状态。

参数：

• comment-id - 评论 ID（必需）

必需选项：

• -d, --document-path <path> - 文档路径
• -f, --feature-id <id> - 特性 ID

可选选项：

• -c, --content <text> - 新的评论内容
• -S, --status <status> - 新的评论状态：open、resolved、archived
• -F, --format <format> - 输出格式（默认：json）
• -r, --project-root <path> - 项目根目录（默认：当前工作目录）

示例：

# 更新评论内容
ske comment update abc123 \
  -d "specs/001-feature-name/spec.md" \
  -f "001-feature-name" \
  -c "已更新说明"

# 标记评论为已解决
ske comment update abc123 \
  -d "specs/001-feature-name/spec.md" \
  -f "001-feature-name" \
  -S resolved

ske comment delete <comment-id> [options]

删除评论（包括其所有回复）。

参数：

• comment-id - 评论 ID（必需）

必需选项：

• -d, --document-path <path> - 文档路径
• -f, --feature-id <id> - 特性 ID

可选选项：

• -F, --format <format> - 输出格式（默认：json）
• -r, --project-root <path> - 项目根目录（默认：当前工作目录）

示例：

ske comment delete abc123 \
  -d "specs/001-feature-name/spec.md" \
  -f "001-feature-name"

Project 命令

注意：以下命令为规划中的功能，即将推出。

ske project init [project-path] [options]

初始化 Spec-Kit 项目。

ske project info [project-path] [options]

显示项目信息。

ske project validate [project-path] [options]

验证项目结构。

使用示例

场景 1：启动 Dashboard 并查看项目

# 进入 Spec-Kit 项目目录
cd /path/to/your/speckit-project

# 启动 Dashboard
ske dashboard

# 浏览器自动打开，可以：
# - 在左侧栏查看所有特性
# - 点击文档节点查看内容
# - 点击特性卡片查看统计面板
# - 实时编辑 Markdown 文档
# - 添加评论和讨论

场景 2：在其他端口运行 Dashboard

# 如果 3000 端口被占用
ske dashboard --port 8080

# 或者在所有网络接口上监听（允许局域网访问）
ske dashboard --host 0.0.0.0 --port 8080

场景 3：通过 CLI 读取文档内容

# 读取规格文档
ske docs read specs/001-feature-name/spec.md

# 读取任务文档
ske docs read specs/001-feature-name/tasks.md

# 以纯文本格式输出
ske docs read specs/001-feature-name/spec.md --format text

场景 4：监听文档变化

# 监听 spec.md 的变化
ske docs watch specs/001-feature-name/spec.md

# 当文件被修改时，会输出变化信息

场景 5：添加和管理评论

# 为文档的某一段添加评论
ske comment add \
  -d "specs/001-feature-name/spec.md" \
  -f "001-feature-name" \
  -c "这个需求需要更详细的说明" \
  -a "张三" \
  -s 15 \
  -e 20 \
  -t "## 功能需求"

# 查看该文档的所有评论
ske comment list \
  -d "specs/001-feature-name/spec.md" \
  -f "001-feature-name"

# 标记评论为已解决
ske comment update <comment-id> \
  -d "specs/001-feature-name/spec.md" \
  -f "001-feature-name" \
  -S resolved

技术栈

• CLI 框架: Commander.js
• 前端框架: React 18 + TypeScript
• 构建工具: Vite 5
• UI 组件: GitHub Primer 风格
• Markdown 渲染: Marked.js + Prism.js
• 图表库: Recharts 2.x
• 状态管理: Zustand 4.x

项目结构

cli/
├── src/
│   ├── commands/        # CLI 命令实现
│   │   ├── serve.ts     # Dashboard 启动命令
│   │   ├── list.ts      # 文档列表命令
│   │   ├── read.ts      # 文档读取命令
│   │   ├── write.ts     # 文档写入命令
│   │   ├── watch.ts     # 文件监听命令
│   │   └── comment.ts   # 评论管理命令
│   ├── models/          # 数据模型
│   ├── services/        # 业务逻辑
│   │   ├── fileSystem.ts    # 文件系统操作
│   │   ├── staticServer.ts  # 静态服务器
│   │   └── portFinder.ts    # 端口查找
│   ├── utils/           # 工具函数
│   └── index.ts         # CLI 入口
├── public/              # Dashboard 构建产物
├── dist/                # 编译输出
└── package.json

开发

克隆仓库

git clone https://github.com/your-username/speckit-enhancer.git
cd speckit-enhancer/cli

安装依赖

npm install

开发模式

# 启动开发模式（支持热重载）
npm run dev

# 在另一个终端测试命令
node dist/index.js dashboard

构建

npm run build

本地测试

# 链接到全局
npm link

# 现在可以直接使用 ske 命令
ske dashboard

测试

# 运行测试
npm test

# 运行测试并生成覆盖率报告
npm run test:coverage

类型检查

npm run type-check

常见问题

Q: 启动 Dashboard 时提示端口被占用？

A: 使用 --port 选项指定其他端口：

ske dashboard --port 8080

Q: Dashboard 显示"暂无特性"？

A: 确保你在 Spec-Kit 项目根目录运行命令，项目需要包含：

• .specify/ 目录（Spec-Kit 配置）
• specs/ 目录（特性规格）

Q: 如何在局域网内访问 Dashboard？

A: 使用 --host 0.0.0.0 选项：

ske dashboard --host 0.0.0.0

然后在其他设备上通过 http://<你的IP>:3000 访问。

Q: 评论数据存储在哪里？

A: 评论存储在项目的 .specify/memory/comments/ 目录下，以 JSON 格式保存。

贡献

欢迎贡献！请遵循以下步骤：

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'feat: 添加某个特性')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 开启 Pull Request

提交规范

我们使用 Conventional Commits 规范：

• feat: 新功能
• fix: 修复 Bug
• docs: 文档更新
• style: 代码格式调整
• refactor: 代码重构
• test: 测试相关
• chore: 构建/工具链相关

许可证

MIT License - 详见 LICENSE 文件

相关链接

• npm 包
• GitHub 仓库
• 问题反馈
• Spec-Kit 文档

如果这个项目对你有帮助，请给个 ⭐️ Star！

Made with ❤️ by [Your Name]