kse - Kiro Spec Engine

![npm version](https://badge.fury.io/js/kiro-spec-engine)
![License: MIT](https://opensource.org/licenses/MIT)

> ⚠️ 重要说明: kiro-spec-engine (kse) 是一个 npm 包和 CLI 工具，用于 Spec 驱动开发。
> 它不是 Kiro IDE 桌面应用程序。如果你在寻找 Kiro IDE，请访问 https://kiro.dev

AI 编码工具的上下文提供者 - 结构化你的项目需求、设计和任务，让 AI 助手帮你构建更好的软件。

English | 简体中文

---

什么是 kse？

kse (Kiro Spec Engine) 是一个 AI 辅助开发的上下文管理系统。 它帮助你将项目信息组织成结构化的 "Spec"（需求 → 设计 → 任务），让 AI 工具能够理解和有效使用。

把 kse 想象成 AI 助手的图书管理员 - 它组织和呈现项目上下文，让你的 AI 工具准确知道你在构建什么、为什么构建以及如何构建。

$3

``mermaid graph LR A[你创建 Spec] --> B[kse 组织上下文] B --> C[AI 工具读取上下文] C --> D[AI 生成更好的代码]`

1. 你创建 Spec - 在结构化的 markdown 文件中编写需求、设计和任务 2. kse 组织上下文 - 导出为 AI 工具优化的格式 3. AI 工具读取上下文 - 你的 AI 助手理解项目结构 4. AI 生成更好的代码 - 符合你设计和需求的代码

`$3`

- ❌ 不是代码生成器 - kse 不写代码；你的 AI 工具写代码 - ❌ 不是 IDE - kse 与你现有的开发工具配合使用 - ❌ 不是特定 AI 工具 - 适用于 Claude、Cursor、Windsurf、Copilot 等任何 AI 工具 - ❌ 不是文档的替代品 - 它是组织项目上下文的结构化方式

`$3`

- ✅ 使用 AI 编码助手的开发者（Claude、Cursor、Copilot 等） - ✅ 需要结构化项目文档的团队 - ✅ 构建需要清晰需求和设计的功能的任何人 - ✅ 受益于 Spec 驱动开发的项目

---

`快速开始`

`$3`

只需告诉你的 AI：

`安装 kse 并用它以 Spec 驱动开发的方式管理这个项目。`

你的 AI 会： 1. 全局安装 kse（npm install -g kiro-spec-engine） 2. 在项目中采用它（kse adopt） 3. 阅读方法论指南（.kiro/README.md） 4. 按照 Spec 驱动方式开始工作

就这样！你的 AI 处理一切。不需要手动步骤。

---

`$3`


点击展开详细步骤
#### 步骤 1：安装 kse（30 秒）

`bash npm install -g kiro-spec-engine`

验证安装：`bash kse --version`

#### 步骤 2：在项目中采用 kse（30 秒）

导航到项目目录并运行：

`bash cd your-project kse adopt`

这会创建一个 .kiro/目录，包含： -README.md- 给 AI 的项目开发指南 -specs/- Spec 存放位置 -steering/ - 开发规则（可选）

#### 步骤 3：告诉 AI 项目的开发方法（30 秒）

在你的 AI 工具中（Cursor、Claude、Windsurf、Kiro 等），说：

`请阅读 .kiro/README.md 了解项目的开发方法。`

你的 AI 会学到： - 这个项目遵循 Spec 驱动开发 - 每个功能都从 Spec 开始（需求 + 设计 + 任务） - 如何按照这个方法论工作 - 何时使用 kse 命令

#### 步骤 4：开始构建功能

自然地让 AI 实现功能：

`我需要一个用邮箱和密码登录的功能。`

你的 AI 会自动： 1. 创建包含需求、设计和任务的 Spec 2. 按照 Spec 实现 3. 随着工作进展更新任务状态 4. 内部使用 kse 命令（你不需要运行它们）

示例对话： - 你："我需要用邮箱和密码登录的功能" - AI："我会为此创建一个 Spec。让我定义需求..." - AI："这是设计... 现在我会实现任务 1.1..." - AI："任务 1.1 完成。继续任务 1.2..."

---

关键洞察：你不是"使用 kse" - 你的项目"遵循 Spec 驱动方法论"，kse 帮助执行它。AI 为你处理所有 kse 命令。

`$3`

- 📖 阅读快速开始指南获取详细示例 - 🔧 查看你的工具集成指南：Cursor | Claude | Windsurf - 💡 了解集成模式

---

`核心概念`

`$3`

Spec 是功能或项目组件的结构化描述。每个 Spec 包含：

- 需求 (requirements.md) - 你要构建什么以及为什么 - 设计 (design.md) - 如何构建（架构、API、组件） - 任务 (tasks.md) - 分步实现清单

`$3`

上下文导出将你的 Spec 转换为 AI 工具优化的格式。它包括： - 所有需求、设计决策和任务 - 项目结构和约定 - Steering 规则（可选）用于 AI 行为

`$3`

kse 支持三种与 AI 工具协作的方式：

1. 原生集成 - AI 工具直接访问 kse（Kiro IDE） 2. 手动导出 - 你导出并粘贴上下文（Claude、ChatGPT、Cursor） 3. Watch 模式 - 文件更改时自动更新上下文（所有工具）

了解更多：集成模式指南

---

`与 AI 工具集成`

kse 适用于任何 AI 编码助手。选择你的工具获取具体指导：

`$3`

- Cursor - 带 AI 结对编程的 IDE - Claude Code - Anthropic 的编码助手 - Windsurf - 支持命令执行的 AI 代理 - Kiro - 原生集成，无需手动导出 - VS Code + Copilot - GitHub Copilot 集成 - 通用 AI 工具 - 适用于任何 AI 助手

`$3`

`mermaid sequenceDiagram participant 你 participant AI工具 participant kse 你->>AI工具: "我有一个 user-login 的 Spec，实现任务 1.1" AI工具->>kse: kse context export user-login kse->>AI工具: Spec 内容（需求、设计、任务） AI工具->>AI工具: 根据 Spec 生成代码 AI工具->>你: 这是实现 AI工具->>kse: 更新 tasks.md（标记任务完成）`

关键洞察：你留在 AI 工具中。AI 读取 Spec 并生成符合你设计的代码。

---

`文档`

`$3`


- 📖 快速开始指南 - 详细的 5 分钟教程
- 🤔 常见问题 - 常见问题解答
- 🔧 故障排除 - 常见问题和解决方案
$3

- 📋 Spec 工作流 - 深入理解 Spec
- 🔢 Spec 编号策略 - 如何为 Spec 编号
- 📄 文档治理 - 自动化文档管理
- 🔌 集成模式 - 三种集成 kse 的方式
- 📝 命令参考 - 所有 kse 命令
$3

- Cursor 集成
- Claude Code 集成
- Windsurf 集成
- Kiro 集成
- VS Code + Copilot 集成
- 通用 AI 工具
$3

- API 功能示例 - RESTful API Spec
- UI 功能示例 - React 仪表板 Spec
- CLI 功能示例 - CLI 命令 Spec
$3

- 采用指南 - 在现有项目中采用 kse
- 升级指南 - 版本升级说明
- 手动工作流 - 分步工作流
- 开发者指南 - 贡献和扩展 kse
$3

- 📚 文档索引 - 所有文档集中在一处
---
主要功能
$3

使用需求 → 设计 → 任务工作流结构化你的工作
$3

- 工作区注册表：从单一位置管理多个 kse 项目
- 快速切换：无需目录导航即可在项目间切换
- 数据原子性：单一数据源（

~/.kse/workspace-state.json

）
- 跨平台：Windows/Linux/macOS 一致的路径处理
- 自动迁移：从旧版工作区格式无缝升级
$3

- 环境注册表：管理多个环境配置（dev, test, staging, prod）
- 快速切换：自动备份的环境切换
- 自动备份：每次切换前创建时间戳备份
- 回滚支持：即时恢复上一个环境配置
- 验证功能：切换后验证环境配置
- 命令执行：在特定环境上下文中运行命令
- 跨平台：在 Windows、Linux 和 macOS 上无缝工作
$3

- 运维 Spec 管理：标准化运维文档（部署、监控、故障排查等）
- 渐进式 AI 自主：L1-L5 接管级别，逐步实现 AI 运维控制
- 审计日志：基于 SHA-256 的防篡改审计追踪
- 反馈集成：自动化用户反馈处理和分析
- 权限管理：基于环境的安全控制（开发、测试、预生产、生产）
- 运维验证：完整的 spec 验证和清晰的错误报告
$3

- 自动化文档生命周期管理
- 强制执行清洁项目结构
- 临时文件清理
- 产物组织
- Git hooks 合规性检查
$3

- 团队成员的个人工作空间
- 任务认领和跟踪
- 工作空间同步
$3

为 Claude Code、Cursor、Windsurf、Copilot 等导出上下文
$3

自动文件监控和上下文更新
$3

- 文档质量评分（0-10 分）
- 智能改进建议
- 专业标准执行
$3

英文和中文界面
---
命令概览

`bash

`项目设置`


kse adopt                          # 在现有项目中采用 kse
kse create-spec              # 创建新 Spec
上下文管理

kse context export      # 为 AI 工具导出上下文
kse prompt generate    # 生成任务特定提示
工作区管理（v1.11.0 新增）

kse workspace create  [path] # 注册新工作区
kse workspace list                 # 列出所有工作区
kse workspace switch         # 切换活动工作区
kse workspace info [name]          # 显示工作区详情
kse workspace remove         # 删除工作区
环境管理（v1.14.0 新增）

kse env list                       # 列出所有环境
kse env switch               # 切换到环境（自动备份）
kse env info                       # 显示活动环境详情
kse env register      # 注册新环境
kse env unregister           # 删除环境
kse env rollback                   # 回滚到上一个环境
kse env verify                     # 验证当前环境
kse env run ""            # 在环境上下文中运行命令
DevOps 运维

kse ops init         # 初始化运维 specs
kse ops validate []       # 验证运维完整性
kse ops audit [options]            # 查询审计日志
kse ops takeover           # 管理 AI 接管级别
kse ops feedback           # 管理用户反馈
任务管理

kse task claim      # 认领任务
kse task list                # 列出已认领任务
文档治理

kse docs diagnose                  # 检查文档合规性
kse docs cleanup                   # 删除临时文件
kse docs validate                  # 验证文档结构
kse docs archive --spec      # 组织 Spec 产物
kse docs hooks install             # 安装 Git pre-commit hooks
自动化

kse watch start                    # 启动 watch 模式
kse watch status                   # 检查 watch 状态
项目信息

kse status                         # 项目状态
kse workflows                      # 列出可用工作流


查看命令参考获取完整文档。
---
贡献与支持
$3
- 📖 文档：从快速开始指南开始
- 🐛 Bug 报告：GitHub Issues
- 💬 讨论：GitHub Discussions
$3
我们欢迎贡献！查看我们的贡献指南了解：
- 代码贡献
- 文档改进
- Bug 报告和功能请求
- 翻译帮助
$3

`bash git clone https://github.com/heguangyong/kiro-spec-engine.git cd kiro-spec-engine npm install npm link # 用于本地开发 npm test # 运行测试`

---

`许可证`

MIT 许可证 - 详见 LICENSE 文件。

---

`致谢`

- 受西西弗斯神话和高贵奋斗概念的启发 - 建立在 Kiro Spec 驱动开发的基础上 - 受 oh-my-opencode 和 Ultrawork 宣言的影响

---

准备好增强你的 AI 辅助开发了吗？ 🚀

`bash npm install -g kiro-spec-engine kse adopt kse create-spec 01-00-my-first-feature``

---

版本：1.4.5
最后更新：2026-01-24

kse - Kiro Spec Engine

![npm version](https://badge.fury.io/js/kiro-spec-engine)
![License: MIT](https://opensource.org/licenses/MIT)

AI 编码工具的上下文提供者 - 结构化你的项目需求、设计和任务，让 AI 助手帮你构建更好的软件。

English | 简体中文

---

什么是 kse？

把 kse 想象成 AI 助手的图书管理员 - 它组织和呈现项目上下文，让你的 AI 工具准确知道你在构建什么、为什么构建以及如何构建。

$3

``mermaid graph LR A[你创建 Spec] --> B[kse 组织上下文] B --> C[AI 工具读取上下文] C --> D[AI 生成更好的代码]`

`$3`

---

`快速开始`

`$3`

只需告诉你的 AI：

`安装 kse 并用它以 Spec 驱动开发的方式管理这个项目。`

就这样！你的 AI 处理一切。不需要手动步骤。

---

`$3`


点击展开详细步骤
#### 步骤 1：安装 kse（30 秒）

`bash npm install -g kiro-spec-engine`

验证安装：`bash kse --version`

#### 步骤 2：在项目中采用 kse（30 秒）

导航到项目目录并运行：

`bash cd your-project kse adopt`

这会创建一个 .kiro/目录，包含： -README.md- 给 AI 的项目开发指南 -specs/- Spec 存放位置 -steering/ - 开发规则（可选）

#### 步骤 3：告诉 AI 项目的开发方法（30 秒）

在你的 AI 工具中（Cursor、Claude、Windsurf、Kiro 等），说：

`请阅读 .kiro/README.md 了解项目的开发方法。`

你的 AI 会学到： - 这个项目遵循 Spec 驱动开发 - 每个功能都从 Spec 开始（需求 + 设计 + 任务） - 如何按照这个方法论工作 - 何时使用 kse 命令

#### 步骤 4：开始构建功能

自然地让 AI 实现功能：

`我需要一个用邮箱和密码登录的功能。`

你的 AI 会自动： 1. 创建包含需求、设计和任务的 Spec 2. 按照 Spec 实现 3. 随着工作进展更新任务状态 4. 内部使用 kse 命令（你不需要运行它们）

---

关键洞察：你不是"使用 kse" - 你的项目"遵循 Spec 驱动方法论"，kse 帮助执行它。AI 为你处理所有 kse 命令。

`$3`

- 📖 阅读快速开始指南获取详细示例 - 🔧 查看你的工具集成指南：Cursor | Claude | Windsurf - 💡 了解集成模式

---

`核心概念`

`$3`

Spec 是功能或项目组件的结构化描述。每个 Spec 包含：

- 需求 (requirements.md) - 你要构建什么以及为什么 - 设计 (design.md) - 如何构建（架构、API、组件） - 任务 (tasks.md) - 分步实现清单

`$3`

上下文导出将你的 Spec 转换为 AI 工具优化的格式。它包括： - 所有需求、设计决策和任务 - 项目结构和约定 - Steering 规则（可选）用于 AI 行为

`$3`

kse 支持三种与 AI 工具协作的方式：

了解更多：集成模式指南

---

`与 AI 工具集成`

kse 适用于任何 AI 编码助手。选择你的工具获取具体指导：

`$3`

关键洞察：你留在 AI 工具中。AI 读取 Spec 并生成符合你设计的代码。

---

`文档`

`$3`


- 📖 快速开始指南 - 详细的 5 分钟教程
- 🤔 常见问题 - 常见问题解答
- 🔧 故障排除 - 常见问题和解决方案
$3

- 📋 Spec 工作流 - 深入理解 Spec
- 🔢 Spec 编号策略 - 如何为 Spec 编号
- 📄 文档治理 - 自动化文档管理
- 🔌 集成模式 - 三种集成 kse 的方式
- 📝 命令参考 - 所有 kse 命令
$3

- Cursor 集成
- Claude Code 集成
- Windsurf 集成
- Kiro 集成
- VS Code + Copilot 集成
- 通用 AI 工具
$3

- API 功能示例 - RESTful API Spec
- UI 功能示例 - React 仪表板 Spec
- CLI 功能示例 - CLI 命令 Spec
$3

- 采用指南 - 在现有项目中采用 kse
- 升级指南 - 版本升级说明
- 手动工作流 - 分步工作流
- 开发者指南 - 贡献和扩展 kse
$3

- 📚 文档索引 - 所有文档集中在一处
---
主要功能
$3

使用需求 → 设计 → 任务工作流结构化你的工作
$3

- 工作区注册表：从单一位置管理多个 kse 项目
- 快速切换：无需目录导航即可在项目间切换
- 数据原子性：单一数据源（

~/.kse/workspace-state.json

）
- 跨平台：Windows/Linux/macOS 一致的路径处理
- 自动迁移：从旧版工作区格式无缝升级
$3

- 环境注册表：管理多个环境配置（dev, test, staging, prod）
- 快速切换：自动备份的环境切换
- 自动备份：每次切换前创建时间戳备份
- 回滚支持：即时恢复上一个环境配置
- 验证功能：切换后验证环境配置
- 命令执行：在特定环境上下文中运行命令
- 跨平台：在 Windows、Linux 和 macOS 上无缝工作
$3

- 运维 Spec 管理：标准化运维文档（部署、监控、故障排查等）
- 渐进式 AI 自主：L1-L5 接管级别，逐步实现 AI 运维控制
- 审计日志：基于 SHA-256 的防篡改审计追踪
- 反馈集成：自动化用户反馈处理和分析
- 权限管理：基于环境的安全控制（开发、测试、预生产、生产）
- 运维验证：完整的 spec 验证和清晰的错误报告
$3

- 自动化文档生命周期管理
- 强制执行清洁项目结构
- 临时文件清理
- 产物组织
- Git hooks 合规性检查
$3

- 团队成员的个人工作空间
- 任务认领和跟踪
- 工作空间同步
$3

为 Claude Code、Cursor、Windsurf、Copilot 等导出上下文
$3

自动文件监控和上下文更新
$3

- 文档质量评分（0-10 分）
- 智能改进建议
- 专业标准执行
$3

英文和中文界面
---
命令概览

`bash

`项目设置`


kse adopt                          # 在现有项目中采用 kse
kse create-spec              # 创建新 Spec
上下文管理

kse context export      # 为 AI 工具导出上下文
kse prompt generate    # 生成任务特定提示
工作区管理（v1.11.0 新增）

kse workspace create  [path] # 注册新工作区
kse workspace list                 # 列出所有工作区
kse workspace switch         # 切换活动工作区
kse workspace info [name]          # 显示工作区详情
kse workspace remove         # 删除工作区
环境管理（v1.14.0 新增）

kse env list                       # 列出所有环境
kse env switch               # 切换到环境（自动备份）
kse env info                       # 显示活动环境详情
kse env register      # 注册新环境
kse env unregister           # 删除环境
kse env rollback                   # 回滚到上一个环境
kse env verify                     # 验证当前环境
kse env run ""            # 在环境上下文中运行命令
DevOps 运维

kse ops init         # 初始化运维 specs
kse ops validate []       # 验证运维完整性
kse ops audit [options]            # 查询审计日志
kse ops takeover           # 管理 AI 接管级别
kse ops feedback           # 管理用户反馈
任务管理

kse task claim      # 认领任务
kse task list                # 列出已认领任务
文档治理

kse docs diagnose                  # 检查文档合规性
kse docs cleanup                   # 删除临时文件
kse docs validate                  # 验证文档结构
kse docs archive --spec      # 组织 Spec 产物
kse docs hooks install             # 安装 Git pre-commit hooks
自动化

kse watch start                    # 启动 watch 模式
kse watch status                   # 检查 watch 状态
项目信息

kse status                         # 项目状态
kse workflows                      # 列出可用工作流


查看命令参考获取完整文档。
---
贡献与支持
$3
- 📖 文档：从快速开始指南开始
- 🐛 Bug 报告：GitHub Issues
- 💬 讨论：GitHub Discussions
$3
我们欢迎贡献！查看我们的贡献指南了解：
- 代码贡献
- 文档改进
- Bug 报告和功能请求
- 翻译帮助
$3

`bash git clone https://github.com/heguangyong/kiro-spec-engine.git cd kiro-spec-engine npm install npm link # 用于本地开发 npm test # 运行测试`

---

`许可证`

MIT 许可证 - 详见 LICENSE 文件。

---

`致谢`

- 受西西弗斯神话和高贵奋斗概念的启发 - 建立在 Kiro Spec 驱动开发的基础上 - 受 oh-my-opencode 和 Ultrawork 宣言的影响

---

准备好增强你的 AI 辅助开发了吗？ 🚀

`bash npm install -g kiro-spec-engine kse adopt kse create-spec 01-00-my-first-feature``

---

版本：1.4.5
最后更新：2026-01-24