kiro-spec-engine 1.0.0

package/locales/zh.json

@@ -0,0 +1,114 @@
+{
+  "cli": {
+    "name": "kiro-spec-engine",
+    "description": "🔥 Kiro Spec 引擎 - 基于 Spec 的驱动规则引擎",
+    "commands": {
+      "init": {
+        "description": "初始化新的 Kiro Spec Engine 项目",
+        "projectNamePrompt": "请输入项目名称:",
+        "forceOption": "强制初始化，即使 .kiro 目录已存在",
+        "alreadyExists": "⚠️  .kiro 目录已存在",
+        "overwritePrompt": "是否要覆盖它？",
+        "cancelled": "初始化已取消。",
+        "success": "🎉 Kiro Spec Engine 项目初始化成功！",
+        "nextSteps": "📋 下一步操作:",
+        "step1": "创建第一个 Spec: mkdir .kiro/specs/01-00-your-feature",
+        "step2": "编写基础 requirements.md",
+        "step3": "使用 Ultrawork 增强: kiro-spec-engine enhance requirements .kiro/specs/01-00-your-feature/requirements.md",
+        "startJourney": "🔥 开始你的 Ultrawork 之旅！",
+        "error": "❌ 初始化项目时出错:"
+      },
+      "enhance": {
+        "description": "使用 Ultrawork 精神增强文档质量",
+        "starting": "🔥 启动 {stage} 阶段 Ultrawork 增强...",
+        "toolNotFound": "❌ 找不到 Ultrawork 工具。请运行: kiro-spec-engine init",
+        "completed": "✅ Ultrawork 增强完成！",
+        "failed": "❌ 增强失败，错误代码:",
+        "pythonError": "❌ 运行 Python 工具时出错:",
+        "pythonTip": "💡 请确保已安装 Python 3.8+ 并在 PATH 中"
+      },
+      "createSpec": {
+        "description": "创建新的 Spec 目录",
+        "success": "✅ 已创建 Spec 目录:",
+        "nextSteps": "📋 下一步操作:",
+        "step1": "在 Spec 目录中创建 requirements.md",
+        "step2": "使用以下命令增强: kiro-spec-engine enhance requirements {specPath}/requirements.md",
+        "error": "❌ 创建 Spec 时出错:"
+      },
+      "status": {
+        "description": "检查项目状态和可用的 Specs",
+        "noProject": "⚠️  当前目录中未找到 Kiro Spec Engine 项目",
+        "initTip": "运行: kiro-spec-engine init 来初始化",
+        "title": "🔥 Kiro Spec Engine 项目状态",
+        "toolStatus": "Ultrawork 工具:",
+        "available": "✅ 可用",
+        "missing": "❌ 缺失",
+        "specsTitle": "📋 可用的 Specs:",
+        "noSpecs": "未找到 Specs",
+        "requirements": "需求文档:",
+        "design": "设计文档:",
+        "tasks": "任务文档:"
+      },
+      "doctor": {
+        "description": "检查系统要求和诊断信息",
+        "title": "系统诊断",
+        "checking": "正在检查系统要求...",
+        "nodejs": "Node.js",
+        "python": "Python",
+        "python_note": "注意: Ultrawork 质量增强功能需要 Python。",
+        "all_good": "所有系统要求均已满足！",
+        "ready": "您已准备好使用 Kiro Spec Engine 的所有功能，包括 Ultrawork 增强。",
+        "python_missing": "Python 不可用",
+        "basic_features": "基本 CLI 功能（init、status、create-spec）可以正常工作。",
+        "ultrawork_unavailable": "Ultrawork 增强功能需要 Python 3.8 或更高版本。"
+      }
+    }
+  },
+  "ultrawork": {
+    "spirit": {
+      "title": "🔥 Ultrawork 精神",
+      "subtitle": "像西西弗斯推石上山一样",
+      "principles": {
+        "relentless": "永不放弃，不懈努力",
+        "excellence": "追求专业级质量",
+        "improvement": "持续改进和优化",
+        "completion": "完美完成每个任务"
+      }
+    },
+    "quality": {
+      "scoring": "质量评分: {score}/10",
+      "professional": "✅ 文档已达到专业级标准！",
+      "improving": "🔄 第 {iteration} 轮改进: {improvements}",
+      "noImprovements": "⚠️ 无法识别更多改进点，停止迭代",
+      "scoreNotImproved": "⚠️ 质量评分未提升，停止迭代"
+    },
+    "stages": {
+      "requirements": "需求",
+      "design": "设计",
+      "tasks": "任务"
+    }
+  },
+  "messages": {
+    "success": "✅ 成功",
+    "error": "❌ 错误",
+    "warning": "⚠️ 警告",
+    "info": "💡 提示",
+    "processing": "🔄 处理中",
+    "completed": "🎉 完成"
+  },
+  "python": {
+    "available": "Python {version} 可用",
+    "not_found": "未安装 Python 或 Python 不在 PATH 中",
+    "version_too_old": "已安装 Python {version}，但需要 {required} 或更高版本",
+    "malformed_version": "无法解析 Python 版本: {version}",
+    "error_header": "✗ Ultrawork 质量增强功能需要 Python",
+    "install_header": "安装说明:",
+    "help_footer": "获取更多帮助，请访问: https://github.com/USERNAME/kiro-spec-engine#python-setup",
+    "install": {
+      "windows": "Windows:\n1. 从 https://www.python.org/downloads/ 下载 Python\n2. 运行安装程序并勾选 'Add Python to PATH'\n3. 重启终端并运行: python --version",
+      "macos": "macOS:\n1. 如果尚未安装 Homebrew，请先安装: /bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\"\n2. 安装 Python: brew install python\n3. 验证安装: python3 --version",
+      "linux": "Linux:\n1. Ubuntu/Debian: sudo apt-get update && sudo apt-get install python3 python3-pip\n2. Fedora/RHEL: sudo dnf install python3 python3-pip\n3. 验证安装: python3 --version",
+      "default": "请访问 https://www.python.org/downloads/ 下载并安装适合您操作系统的 Python 3.8 或更高版本。"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "kiro-spec-engine",
+  "version": "1.0.0",
+  "description": "Kiro Spec Engine - A spec-driven development engine with steering rules and quality enhancement powered by Ultrawork spirit",
+  "main": "index.js",
+  "bin": {
+    "kiro-spec-engine": "./bin/kiro-spec-engine.js",
+    "kse": "./bin/kiro-spec-engine.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "template/",
+    "locales/",
+    "README.md",
+    "README.zh.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "jest",
+    "test:unit": "jest tests/unit",
+    "test:integration": "jest tests/integration",
+    "test:properties": "jest tests/properties",
+    "test:watch": "jest --watch",
+    "coverage": "jest --coverage",
+    "prepublishOnly": "npm test",
+    "publish:manual": "npm publish --access public",
+    "install-global": "npm install -g .",
+    "uninstall-global": "npm uninstall -g kiro-spec-engine"
+  },
+  "keywords": [
+    "kiro",
+    "spec",
+    "spec-driven",
+    "engine",
+    "steering",
+    "rules-engine",
+    "development",
+    "quality",
+    "ultrawork",
+    "ai",
+    "productivity",
+    "cli",
+    "i18n",
+    "multilingual",
+    "chinese",
+    "english",
+    "development-tools",
+    "quality-enhancement",
+    "sisyphus"
+  ],
+  "author": "heguangyong",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/heguangyong/kiro-spec-engine.git"
+  },
+  "bugs": {
+    "url": "https://github.com/heguangyong/kiro-spec-engine/issues"
+  },
+  "homepage": "https://github.com/heguangyong/kiro-spec-engine#readme",
+  "engines": {
+    "node": ">=16.0.0",
+    "python": ">=3.8.0"
+  },
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "commander": "^9.0.0",
+    "fs-extra": "^10.0.0",
+    "inquirer": "^8.2.0",
+    "path": "^0.12.7"
+  },
+  "devDependencies": {
+    "fast-check": "^4.5.3",
+    "jest": "^27.5.1"
+  }
+}

package/template/.kiro/README.md

@@ -0,0 +1,288 @@
+# Kiro Spec 驱动开发体系
+
+> **用途**: 新项目引导文档，解释 Spec 驱动开发体系的设计思想和使用方法
+
+---
+
+## 🎯 这是什么？
+
+这是一套基于 Spec 驱动的 AI 辅助开发规范体系，包含：
+- **Steering 规范**：控制 AI 行为的规则和上下文
+- **Spec 工作流**：结构化的需求-设计-实施流程
+- **文件组织**：清晰的产物归档和知识沉淀
+
+---
+
+## 💡 为什么需要这套体系？
+
+### 问题 1：AI Session Token 有限
+
+**挑战**：
+- AI session 启动时会加载所有 Steering 文档
+- 历史数据和详细内容会快速消耗 token
+- Token 耗尽导致无法继续执行任务
+
+**解决方案**：
+- **分层管理**：稳定规则（CORE_PRINCIPLES）+ 动态场景（CURRENT_CONTEXT）
+- **精简原则**：Steering 只保留核心信息，详细内容放到 Spec 目录
+- **主动管控**：每个 Spec 完成后及时更新 CURRENT_CONTEXT
+
+### 问题 2：规范一致性难以保持
+
+**挑战**：
+- 不同 Spec 使用不同的开发流程
+- 产物散落在项目各处，难以查找
+- 缺乏上下文，不知道为什么要这样做
+
+**解决方案**：
+- **Spec 驱动**：所有工作基于 Spec 推进
+- **统一规范**：CORE_PRINCIPLES 适用于所有 Spec
+- **产物归档**：所有产物归档到对应的 Spec 目录
+
+---
+
+## 📚 文件组织
+
+### Steering 目录（AI 每次启动时加载）
+
+| 文件 | 职责 | Token 影响 | 更新频率 |
+|------|------|-----------|---------|
+| **RULES_GUIDE.md** | 索引和快速参考 | 低 | 很少 |
+| **CORE_PRINCIPLES.md** | 核心开发规范 | 中 | 很少 |
+| **ENVIRONMENT.md** | 环境配置 | 低 | 很少 |
+| **CURRENT_CONTEXT.md** | 当前 Spec 场景 | **高** ⚠️ | 每个 Spec |
+
+### Specs 目录（按需加载）
+
+```
+.kiro/specs/
+├── SPEC_WORKFLOW_GUIDE.md    # Spec 工作流指南
+└── {spec-name}/               # 具体的 Spec
+    ├── requirements.md        # 需求文档
+    ├── design.md              # 设计文档（可选）
+    ├── tasks.md               # 任务列表（可选）
+    ├── scripts/               # 脚本
+    ├── diagnostics/           # 诊断文档
+    └── results/               # 执行结果
+```
+
+---
+
+## 🔄 Steering 体系的核心思想
+
+### 1. 最小化 Token 消耗
+
+**原则**：
+- Steering 文档在每次 session 启动时**完全加载**
+- 必须保持精简，避免历史数据堆积
+- CURRENT_CONTEXT 需要随 Spec 推进及时更新
+
+**实践**：
+- ❌ 不要在 Steering 中保留详细的历史数据
+- ❌ 不要在 Steering 中保留详细的配置和命令
+- ✅ 历史数据归档到 Spec 目录
+- ✅ 详细配置放到 Spec 文档中
+
+### 2. 规范的可复用性
+
+**原则**：
+- CORE_PRINCIPLES 适用于所有 Spec
+- 新项目可以直接复制这套体系
+- 只需修正 ENVIRONMENT 和 CURRENT_CONTEXT
+
+**实践**：
+- ✅ CORE_PRINCIPLES 保持稳定，很少修改
+- ✅ ENVIRONMENT 记录项目特定的环境配置
+- ✅ CURRENT_CONTEXT 随 Spec 动态更新
+
+### 3. 上下文的聚焦性
+
+**原则**：
+- CURRENT_CONTEXT 只保留当前 Spec 的核心信息
+- 历史数据归档到 Spec 目录，不占用 Steering 空间
+- 每个 Spec 开始前必须更新 CURRENT_CONTEXT
+
+**实践**：
+- ✅ 每个新 Spec 开始前：更新 CURRENT_CONTEXT
+- ✅ Spec 推进中：及时精简已完成内容
+- ✅ Spec 完成后：清空 CURRENT_CONTEXT
+
+---
+
+## 🚀 如何在新项目中使用？
+
+### 步骤 1：复制 Steering 模板
+
+```bash
+# 从模板项目复制
+cp -r template-project/.kiro/ new-project/.kiro/
+```
+
+### 步骤 2：修正 ENVIRONMENT.md
+
+更新为新项目的实际环境：
+- 服务器信息（如有）
+- 数据库配置
+- 部署方式
+- AI 权限范围
+
+### 步骤 3：清空 CURRENT_CONTEXT.md
+
+删除旧项目的场景信息，标记为"无活跃 Spec"。
+
+### 步骤 4：检查 CORE_PRINCIPLES.md
+
+确认规范是否适用于新项目，必要时调整（但尽量保持稳定）。
+
+### 步骤 5：修正 SPEC_WORKFLOW_GUIDE.md
+
+更新项目特定的内容：
+- 项目名称
+- 技术栈
+- 示例
+
+---
+
+## 📖 Spec 驱动开发工作流程
+
+### 标准流程
+
+```
+1. 创建 Spec 目录
+   ↓
+2. 编写需求文档 (requirements.md)
+   ↓
+3. 编写设计文档 (design.md) - 可选
+   ↓
+4. 创建任务列表 (tasks.md) - 可选
+   ↓
+5. 执行任务（调研、分析、实现、测试）
+   ↓
+6. 所有产物归档到 Spec 目录
+   ↓
+7. 更新 CURRENT_CONTEXT 为下一个 Spec
+```
+
+### 为什么要用 Spec 驱动？
+
+**优点**：
+- ✅ 所有工作有明确的需求和设计支持
+- ✅ 产物有上下文，易于理解和维护
+- ✅ 可以追溯需求和设计决策
+- ✅ 团队协作更清晰
+- ✅ 知识沉淀在 Spec 中
+
+**不用 Spec 的问题**：
+- ❌ 脚本散落在项目各处，难以查找
+- ❌ 缺乏上下文，不知道为什么要这样做
+- ❌ 无法追溯需求来源
+- ❌ 临时文件堆积，项目混乱
+- ❌ 知识流失
+
+---
+
+## 💡 最佳实践
+
+### 1. 主动管控 Token
+
+**时机**：
+- 每完成一组任务后：精简 tasks.md
+- 每完成一个阶段后：精简 CURRENT_CONTEXT
+- 发现 token 使用率 > 50% 时：立即精简
+- 阶段切换时：更新 CURRENT_CONTEXT 聚焦新阶段
+
+**策略**：
+- ❌ 删除：已完成阶段的详细配置、命令、表格
+- ❌ 删除：历史测试数据和性能对比表格
+- ❌ 删除：详细的问题排查流程和检查清单
+- ✅ 保留：当前阶段的核心信息和关键经验
+
+### 2. 保持 Steering 精简
+
+**原则**：
+- CURRENT_CONTEXT 只保留当前信息
+- 历史数据归档到 Spec 目录
+- 详细配置放到 Spec 文档中
+
+**检查清单**：
+- [ ] CURRENT_CONTEXT 是否聚焦当前 Spec？
+- [ ] 历史阶段的详细内容是否已移除？
+- [ ] 详细数据是否已归档到 Spec 目录？
+- [ ] Token 使用率是否 < 50%？
+
+### 3. 规范的一致性
+
+**原则**：
+- 所有 Spec 遵循相同的规范
+- 不要在不同 Spec 中使用不同的流程
+- 发现问题及时更新 CORE_PRINCIPLES
+
+**实践**：
+- ✅ 基于 Spec 推进所有工作
+- ✅ 产物归档到对应的 Spec 目录
+- ✅ 不要在根目录生成临时文件
+
+### 4. 知识的沉淀
+
+**原则**：
+- 通用经验沉淀到 CORE_PRINCIPLES
+- Spec 特定经验保留在 Spec 目录
+- 定期回顾和更新规范
+
+**时机**：
+- Spec 完成后：总结经验教训
+- 新 Spec 开始前：评估现有规则是否适用
+- 发现重复问题时：更新 CORE_PRINCIPLES
+
+---
+
+## ⚠️ 常见错误
+
+### 错误 1：CURRENT_CONTEXT 膨胀
+
+**现象**：
+- session 启动后 token 使用率 > 50%
+- CURRENT_CONTEXT 包含大量历史数据
+
+**解决**：
+- 立即精简 CURRENT_CONTEXT
+- 将详细数据归档到 Spec 目录
+- 只保留当前阶段的核心信息
+
+### 错误 2：规范不一致
+
+**现象**：
+- 不同 Spec 使用不同的开发流程
+- 文件组织混乱
+
+**解决**：
+- 重新阅读 CORE_PRINCIPLES
+- 按照规范重新组织文件
+- 将散落的产物归档到 Spec 目录
+
+### 错误 3：产物散落
+
+**现象**：
+- 脚本、测试、报告散落在项目各处
+- 缺乏上下文，难以理解
+
+**解决**：
+- 所有产物归档到对应的 Spec 目录
+- 不要在根目录生成临时文件
+- 遵循 Spec 驱动开发原则
+
+---
+
+## 📚 相关文档
+
+- **Steering 索引**: `.kiro/steering/RULES_GUIDE.md`
+- **核心开发原则**: `.kiro/steering/CORE_PRINCIPLES.md`
+- **环境配置**: `.kiro/steering/ENVIRONMENT.md`
+- **当前场景**: `.kiro/steering/CURRENT_CONTEXT.md`
+- **Spec 工作流指南**: `.kiro/specs/SPEC_WORKFLOW_GUIDE.md`
+
+---
+
+**版本**: v1.0  
+**创建**: 2025-01-22  
+**说明**: 这是新项目引导文档，日常开发时不需要加载

package/template/.kiro/specs/SPEC_WORKFLOW_GUIDE.md

@@ -0,0 +1,134 @@
+# Kiro Specs 工作流指南
+
+> **用途**: Spec 驱动开发的完整工作流程和设计原则  
+> **适用**: 上海图书馆 MinIO 文件存储系统的所有 Spec 驱动的功能开发
+
+---
+
+## 📋 一、Spec 命名规范
+
+**格式**: `[功能名称]`（kebab-case）
+- 示例：`fix-duplicate-file-space-calculation`、`oauth-api-upgrade`
+
+**文档结构**:
+- `requirements.md` - 需求文档
+- `design.md` - 设计文档（可选）
+- `tasks.md` - 任务列表（可选）
+- `scripts/`, `diagnostics/`, `reports/`, `results/`
+
+---
+
+## 📁 二、三件套文档结构
+
+```
+XX-YY-功能名称/
+├── requirements.md  ← WHAT（做什么）
+├── design.md        ← HOW（怎么做）
+├── tasks.md         ← STEPS（执行步骤）
+└── scripts/, tests/, results/, reports/
+```
+
+### 2.1 requirements.md
+
+**结构**:
+```markdown
+# 功能名称
+## 1. 概述
+## 2. 用户故事
+## 3. 功能需求
+### 3.1 需求标题
+**描述**: ...
+**验收标准**: WHEN [条件] THEN [结果]
+## 4. 非功能需求
+## 5. 约束条件
+```
+
+### 2.2 design.md（可选）
+
+**结构**:
+```markdown
+# 功能名称 - 技术设计
+## 1. 架构概览
+## 2. 核心实现原则
+_Requirements: X.X_
+## 3. 组件设计
+## 4. 数据流
+## 5. 错误处理
+## 6. 测试策略
+```
+
+### 2.3 tasks.md（可选）
+
+**结构**:
+```markdown
+# 功能名称 - 实现任务
+## 阶段一: 诊断分析
+### 任务 1.1: 任务标题
+**Validates: Requirements X.X**
+- [ ] 子任务1
+- [ ] 子任务2
+```
+
+---
+
+## 🔄 三、Spec 创建工作流程
+
+### 阶段 1: Requirements
+1. 创建 requirements.md（使用 EARS 模式）
+2. 请求用户审核（`userInput` 工具）
+3. 等待批准 → 进入 Design 或直接执行
+
+### 阶段 2: Design（可选）
+1. 创建 design.md
+2. 请求用户审核
+3. 等待批准 → 进入 Tasks 或直接执行
+
+### 阶段 3: Tasks（可选）
+1. 创建 tasks.md
+2. 请求用户审核
+3. 等待批准 → Spec 创建完成
+
+---
+
+## ⚙️ 四、Spec 任务执行流程
+
+**核心原则**: 一次只执行一个任务
+
+**执行步骤**:
+1. 读取 requirements.md, design.md, tasks.md
+2. 更新任务状态为 `in_progress`
+3. 执行任务（遵循 design.md）
+4. 更新任务状态为 `completed`
+5. 停止并等待用户审核
+
+---
+
+## 🎯 五、核心设计原则
+
+1. **场景覆盖**: 覆盖原型系统的全部场景
+2. **风格一致性**: 与现有代码库保持风格一致
+3. **复杂性分解**: 大任务拆分为可独立验证的子任务
+4. **遗留清理**: 清理旧的临时代码和注释
+5. **实现整合**: 同一功能的实现整合在一处
+
+---
+
+## 🔗 六、双向追溯机制
+
+**正向追溯**（需求 → 设计 → 任务）:
+```markdown
+## 2. 核心实现原则
+_Requirements: 3.1, 3.2_
+```
+
+**反向追溯**（任务 → 需求）:
+```markdown
+### 任务 1.1: 实现进度条组件
+**Validates: Requirements 3.1**
+```
+
+---
+
+**版本**: v2.0  
+**更新**: 2026-01-22  
+**适用范围**: 上海图书馆 MinIO 文件存储系统的所有 Spec 驱动的功能开发