amspec

一个基于 Bun 实现的 CLI 工具，用于管理项目需求的完整生命周期（需求→设计→计划→进度）。

特性

• 🚀 基于 Bun 运行，快速高效
• 📁 结构化的需求管理工作区
• 📝 内置丰富的 Markdown 文档模板（README、DESIGN、PLAN、TASK-PROGRESS、QA-TEST）
• 📋 智能任务进度管理（解析 Markdown 任务清单和表格）
• 📊 可视化任务统计和进度展示
• 🎨 美观的命令行界面
• 📊 漂亮的表格展示（cli-table3 双线边框）
• 🔍 直观的需求列表展示，完美支持中文
• ✏️ 交互式文档编辑
• 🤖 双视图模式：交互式（人工使用）+ Markdown（AI Agent 友好）
• 🪶 轻量级依赖，仅 3 个 npm 包
• 🔌 AI Agent Skills - 集成 Claude/Gemini/Cursor/Codex，让 AI 协助需求管理

安装

# 克隆仓库
git clone <repository-url>
cd amspec

# 安装依赖
bun install

# 全局链接（可选）
bun link

使用方法

安装 AI Skills（可选）

如果你想让 AI Agent (Claude/Gemini/Cursor/Codex) 协助完成需求管理，可以安装 amspec skills：

# 交互式安装
bun run src/cli.ts install
# 或
amspec install

安装流程：

1. 选择工具：Claude, Gemini, Cursor, Codex（可多选）
2. 选择位置：全局 (所有项目) 或 当前项目
3. 确认安装

安装后使用： 在 AI 工具中使用自然语言触发：

• "创建需求：用户登录功能"
• "为用户登录功能生成实施计划"
• "创建任务进度管理"
• "开始实施用户登录功能"

详细文档见：INSTALL-CLI-GUIDE.md | SKILLS.md

初始化工作区

bun run src/cli.ts init
# 或者（如果已全局链接）
amspec init

这将在项目根目录创建 .workspaces 目录，包含：

• config.yaml: 项目配置文件
• README.md: 工作区说明文档
• context/: 存放项目上下文信息
• changelogs/: 存放修改日志
• specs/: 存放所有需求

创建需求

bun run src/cli.ts add "需求名称"

这将在 specs/ 目录下创建一个新的需求目录，包含四个文档：

• README.md: 需求说明
• DESIGN.md: 设计文档
• PLAN.md: 工作计划
• TASK-PROGRESS.md: 任务进度

查看所有需求

# 交互式视图（美化输出）
bun run src/cli.ts list

# Markdown 视图（AI 友好）
bun run src/cli.ts list --md

以表格形式展示所有需求及其详细信息。

编辑需求文档

# 交互式选择文件
bun run src/cli.ts edit "需求名称"

# 直接指定文件
bun run src/cli.ts edit "需求名称" README.md

# AI 友好模式（显示可选文件列表）
bun run src/cli.ts edit "需求名称" --md

# AI 模式指定文件（显示文件路径）
bun run src/cli.ts edit "需求名称" DESIGN.md --md

交互模式：使用 prompts 选择文档，用系统默认编辑器打开。

Markdown 模式：

• 不指定文件：显示所有可选文档列表及说明
• 指定文件：显示文件路径，供 AI 或手动编辑

任务进度管理

列出任务

# 交互式视图
bun run src/cli.ts task list "需求名称"

# Markdown 视图（AI 友好）
bun run src/cli.ts task list "需求名称" --md

列出指定需求的所有任务，自动从 PLAN.md 和 TASK-PROGRESS.md 解析任务清单和表格。

显示任务详情

bun run src/cli.ts task show "需求名称"

显示完整的任务详情，包括：

• 进度概览（总数、已完成、进行中、待开始、已阻塞、完成率）
• 可视化进度条和状态分布图
• 按章节分组的任务列表

更新任务状态

bun run src/cli.ts task update "需求名称"

交互式选择任务并更新状态：

• 待开始
• 进行中
• 已完成
• 已阻塞

自动更新 TASK-PROGRESS.md 中的表格和进度概览。

任务统计

bun run src/cli.ts task stats

显示所有需求的任务统计总览：

• 总体进度统计
• 各需求完成情况对比
• 阻塞任务提醒

删除需求

bun run src/cli.ts delete "需求名称"

删除指定的需求目录（需要确认）。

清空工作区

bun run src/cli.ts clear

删除整个工作区及所有需求（需要二次确认）。

查看帮助

# 交互式视图
bun run src/cli.ts help

# Markdown 视图
bun run src/cli.ts help --md

管理 Changelog

# 列出所有 changelog
bun run src/cli.ts changelog list

# 添加 changelog 条目
bun run src/cli.ts changelog add <branch>

# 编辑 changelog
bun run src/cli.ts changelog edit <branch>

# 删除 changelog
bun run src/cli.ts changelog delete <branch>

查看版本

bun run src/cli.ts version

视图模式

amspec 提供两种输出视图模式：

交互式视图（默认）

• 使用 ANSI 颜色和 Unicode 字符美化输出
• 适合人工在终端中使用
• 提供直观的视觉体验

amspec list
amspec help

Markdown 视图（--md 参数）

• 纯 Markdown 格式输出
• 适合 AI Agent 解析和理解
• 减少 token 消耗
• 便于自动化处理

amspec list --md
amspec help --md

详细的视图模式说明，请查看 VIEWS.md。

工作区结构

.workspaces/
├── config.yaml          # 项目配置文件
├── README.md            # 工作区说明
├── context/             # 项目上下文信息
│   └── README.md
├── changelogs/          # 修改日志目录
│   ├── main-changelog.md
│   └── [branch]-changelog.md
└── specs/               # 需求目录
    └── [需求名称]/      # 具体需求目录
        ├── README.md    # 需求说明
        ├── DESIGN.md    # 设计文档
        ├── PLAN.md      # 工作计划
        └── TASK-PROGRESS.md # 任务进度

开发

项目结构

amspec/
├── src/
│   ├── cli.ts              # CLI 入口
│   ├── commands/           # 命令实现
│   ├── templates/          # 文档模板
│   └── utils/              # 工具函数
├── package.json
└── tsconfig.json

技术栈

• 运行时: Bun
• 语言: TypeScript
• 依赖:
  • prompts: 交互式命令行输入
  • cli-table3: 表格化输出
• 测试: Vitest 4.0.18
  • 55 个测试用例
  • 74.5% 通过率（41/55）
  • 完整的单元测试覆盖

📚 文档

快速链接

• 完整文档目录 - 所有文档索引
• AI Skills 使用指南 - Skills 系统详细说明
• 快速开始 - 5 分钟上手
• 安装指南 - 详细安装说明
• 变更日志 - 版本更新记录

文档结构

docs/
├── features/        # 功能文档
├── implementation/  # 实施文档
├── guides/         # 使用指南
└── skills/         # AI Skills 文档

🤝 贡献

欢迎提交 Issue 和 Pull Request！

在提交代码前，请确保：

• ✅ 运行测试：bun test
• ✅ 代码构建：bun run build
• ✅ 遵循现有代码风格

📄 许可证

MIT License - 详见 LICENSE 文件

🔗 相关链接

• GitHub 仓库
• 问题反馈
• 变更日志