scene-capability-engine 3.0.0

package/docs/integration-philosophy.md

@@ -0,0 +1,313 @@
+# kse 集成哲学
+
+> kse 如何与 AI 编码工具配合工作
+
+---
+
+## 核心定位
+
+**kse 不是替代 AI 工具，而是增强 AI 工具**
+
+```
+┌─────────────────────────────────────┐
+│         AI 编码工具                  │
+│    (Codex/Claude/Cursor/Windsurf)   │
+│                                      │
+│  用户主要工作界面 ← 这里写代码        │
+└──────────────┬──────────────────────┘
+               │
+               │ 读取上下文
+               ▼
+┌─────────────────────────────────────┐
+│            kse                       │
+│                                      │
+│  Spec 管理 + 上下文生成               │
+│  (后台运行，提供结构化信息)            │
+└─────────────────────────────────────┘
+```
+
+---
+
+## 三种集成模式
+
+### 模式 1：AI 主动调用 kse（最佳）⭐
+
+**适用工具**：Windsurf、Cline、Aider（可执行命令的 AI）
+
+**工作流**：
+```
+用户 → AI 工具 → AI 自动执行 kse 命令 → 获取上下文 → 生成代码
+```
+
+**示例对话**：
+```
+用户：我要实现用户登录功能
+
+AI：好的，让我先查看项目的 Spec
+    [自动执行] kse context export 01-00-user-login
+    [读取文件] .kiro/specs/01-00-user-login/context-export.md
+    
+    我看到设计文档中定义了 AuthController...
+    [生成代码]
+    
+    [自动执行] kse task claim 01-00-user-login 1.1
+    任务已认领，开始实现...
+```
+
+**配置方法**：
+
+在 AI 工具的系统提示中添加：
+```markdown
+你可以使用以下 kse 命令来管理项目：
+
+- `kse context export <spec-name>` - 导出 Spec 上下文
+- `kse prompt generate <spec-name> <task-id>` - 生成任务提示
+- `kse task claim <spec-name> <task-id>` - 认领任务
+- `kse status` - 查看项目状态
+
+在实现功能前，先用 kse 命令查看相关 Spec。
+```
+
+**优势**：
+- ✅ 完全自动化
+- ✅ 用户无需手动操作
+- ✅ AI 自动管理 Spec 生命周期
+
+---
+
+### 模式 2：手动导出 + AI 使用（当前）
+
+**适用工具**：Claude Code、ChatGPT、GitHub Copilot
+
+**工作流**：
+```
+用户 → 手动执行 kse 命令 → 复制上下文 → 粘贴到 AI → AI 生成代码
+```
+
+**示例流程**：
+```bash
+# 1. 用户手动导出
+kse context export 01-00-user-login
+
+# 2. 复制内容
+cat .kiro/specs/01-00-user-login/context-export.md | pbcopy
+
+# 3. 粘贴到 Claude/ChatGPT
+
+# 4. 对话
+用户：请实现任务 1.1
+AI：[生成代码]
+
+# 5. 手动更新任务状态
+# 编辑 tasks.md: - [x] 1.1 ...
+```
+
+**改进建议**：
+```bash
+# 添加快捷命令
+kse clip 01-00-user-login          # 自动复制到剪贴板
+kse clip 01-00-user-login 1.1      # 只复制任务 1.1 的上下文
+```
+
+**优势**：
+- ✅ 适用于所有 AI 工具
+- ✅ 用户完全控制
+
+**劣势**：
+- ❌ 需要手动操作
+- ❌ 步骤较多
+
+---
+
+### 模式 3：Watch Mode 自动化（进阶）
+
+**适用场景**：频繁修改 Spec 的项目
+
+**工作流**：
+```
+用户修改 Spec → kse 自动检测 → 自动重新导出 → AI 工具自动刷新
+```
+
+**配置**：
+```bash
+# 启动 Watch Mode
+kse watch init
+kse watch install auto-export
+kse watch start
+
+# 现在修改任何 Spec 文件，都会自动重新导出
+```
+
+**Watch 配置示例**：
+```json
+{
+  "patterns": [
+    ".kiro/specs/**/requirements.md",
+    ".kiro/specs/**/design.md",
+    ".kiro/specs/**/tasks.md"
+  ],
+  "actions": [
+    {
+      "name": "auto-export",
+      "command": "kse context export ${spec-name}"
+    }
+  ]
+}
+```
+
+**优势**：
+- ✅ 完全自动化
+- ✅ Spec 修改立即生效
+
+---
+
+## 推荐配置
+
+### 对于 Windsurf/Cline 用户（推荐）⭐
+
+**在 AI 系统提示中添加**：
+
+```markdown
+# Spec 管理规则
+
+项目使用 kse (Kiro Spec Engine) 管理需求和设计。
+
+## 工作流程
+
+1. **查看 Spec**：实现功能前，先执行 `kse context export <spec-name>` 查看设计
+2. **认领任务**：开始工作前，执行 `kse task claim <spec-name> <task-id>`
+3. **实现代码**：严格按照 Spec 中的设计实现
+4. **更新状态**：完成后，在 tasks.md 中标记任务为完成 `[x]`
+
+## 可用命令
+
+- `kse status` - 查看项目状态
+- `kse context export <spec-name>` - 导出 Spec 上下文
+- `kse task claim <spec-name> <task-id>` - 认领任务
+- `kse prompt generate <spec-name> <task-id>` - 生成任务提示
+
+## 示例
+
+用户说："实现用户登录"
+你应该：
+1. 执行 `kse context export 01-00-user-login`
+2. 读取导出的上下文
+3. 根据设计文档实现代码
+4. 执行 `kse task claim 01-00-user-login 1.1`
+```
+
+### 对于 Claude/ChatGPT 用户
+
+**创建快捷脚本**：
+
+```bash
+# ~/.bashrc 或 ~/.zshrc
+alias kse-clip='kse context export $1 && cat .kiro/specs/$1/context-export.md | pbcopy && echo "✅ 已复制到剪贴板"'
+
+# 使用
+kse-clip 01-00-user-login
+# 然后直接粘贴到 Claude
+```
+
+### 对于 Cursor 用户
+
+**使用 Cursor Rules**：
+
+创建 `.cursorrules` 文件：
+```markdown
+# Spec 驱动开发
+
+项目使用 kse 管理 Spec。实现功能前：
+
+1. 查看 `.kiro/specs/<spec-name>/design.md`
+2. 按照设计实现
+3. 更新 `.kiro/specs/<spec-name>/tasks.md`
+
+示例：
+- 设计文档：`.kiro/specs/01-00-user-login/design.md`
+- 任务列表：`.kiro/specs/01-00-user-login/tasks.md`
+```
+
+---
+
+## 未来改进方向
+
+### 1. MCP (Model Context Protocol) 集成
+
+让 AI 工具通过 MCP 直接访问 kse：
+
+```javascript
+// AI 工具可以直接调用
+const context = await mcp.call('kse.getContext', '01-00-user-login');
+const tasks = await mcp.call('kse.getTasks', '01-00-user-login');
+```
+
+### 2. IDE 插件
+
+为主流 IDE 提供插件：
+- VS Code Extension
+- Cursor Extension
+- JetBrains Plugin
+
+功能：
+- 右键菜单："导出到 AI 工具"
+- 状态栏显示当前 Spec
+- 快捷键快速导出
+
+### 3. Web Dashboard
+
+提供 Web 界面：
+```bash
+kse serve
+# 打开 http://localhost:3000
+# 可视化管理 Spec，一键复制上下文
+```
+
+---
+
+## 常见问题
+
+### Q: 为什么不把 kse 做成 AI 工具的插件？
+
+**A**: 
+- kse 是**通用工具**，支持所有 AI 工具
+- 做成插件会限制在特定工具
+- CLI 工具更灵活，可以被任何工具调用
+
+### Q: 能否让 AI 工具自动读取 .kiro/ 目录？
+
+**A**: 
+- 部分工具支持（Cursor、Copilot）
+- 但需要明确的上下文导出更可靠
+- kse 的价值在于**结构化和格式化**上下文
+
+### Q: 两套工具确实有点麻烦，有更简单的方案吗？
+
+**A**: 
+- **短期**：使用 Windsurf/Cline，让 AI 自动调用 kse
+- **中期**：使用快捷脚本（如 `kse-clip`）
+- **长期**：MCP 集成，完全无缝
+
+---
+
+## 总结
+
+**kse 的定位**：
+- ❌ 不是独立的开发工具
+- ❌ 不是 AI 工具的竞争对手
+- ✅ 是 AI 工具的**上下文提供者**
+- ✅ 是项目的**Spec 管理系统**
+
+**最佳实践**：
+1. **用 kse 管理 Spec**（需求、设计、任务）
+2. **用 AI 工具写代码**（主要工作界面）
+3. **让 AI 工具调用 kse**（自动化集成）
+
+**选择合适的模式**：
+- 能执行命令的 AI → 模式 1（AI 主动调用）⭐
+- 不能执行命令的 AI → 模式 2（手动导出）
+- 频繁修改 Spec → 模式 3（Watch Mode）
+
+---
+
+**记住**：kse 是幕后英雄，AI 工具是前台明星。两者配合，才能发挥最大价值！🚀

package/docs/knowledge-management-guide.md

@@ -0,0 +1,263 @@
+# Knowledge Management Guide
+
+## Overview
+
+The Knowledge Management system allows you to build and maintain a personal knowledge base within your kse projects. Capture experiences, patterns, best practices, and lessons learned as you work.
+
+## Quick Start
+
+### Initialize Knowledge Base
+
+```bash
+kse knowledge init
+```
+
+This creates `.kiro/knowledge/` directory with:
+- `patterns/` - Design patterns and solutions
+- `lessons/` - Lessons learned
+- `workflows/` - Custom workflows
+- `checklists/` - Task checklists
+- `references/` - Reference materials
+
+### Add Knowledge Entry
+
+```bash
+# Add a design pattern
+kse knowledge add pattern "Repository Pattern Best Practices" \
+  --tags "design-pattern,database" \
+  --category backend
+
+# Add a lesson learned
+kse knowledge add lesson "Avoid N+1 Queries" \
+  --tags "performance,database" \
+  --category optimization
+```
+
+### List Entries
+
+```bash
+# List all entries
+kse knowledge list
+
+# Filter by type
+kse knowledge list --type pattern
+
+# Filter by tag
+kse knowledge list --tag database
+
+# Sort by date
+kse knowledge list --sort created:desc
+```
+
+### Search
+
+```bash
+# Search in titles and tags
+kse knowledge search "database"
+
+# Full-text search in content
+kse knowledge search "repository" --full-text
+```
+
+### View Entry
+
+```bash
+kse knowledge show kb-1770099318706-4dmali
+```
+
+### Delete Entry
+
+```bash
+# With confirmation
+kse knowledge delete kb-xxx
+
+# Skip confirmation
+kse knowledge delete kb-xxx --force
+
+# Without backup
+kse knowledge delete kb-xxx --force --no-backup
+```
+
+### Statistics
+
+```bash
+kse knowledge stats
+```
+
+## Entry Types
+
+### Pattern
+Design patterns, architectural solutions, code patterns.
+
+**Template sections**:
+- Context - When to use
+- Problem - What it solves
+- Solution - How to implement
+- Examples - Code examples
+- Trade-offs - Pros and cons
+- References - Related resources
+
+### Lesson
+Lessons learned from experience, mistakes, successes.
+
+**Template sections**:
+- Situation - Context
+- Challenge - Problem faced
+- Action - What you did
+- Result - Outcome
+- Lesson Learned - Key takeaway
+- Application - Future use
+
+### Workflow
+Custom workflows, processes, procedures.
+
+**Template sections**:
+- Purpose - What it's for
+- Prerequisites - Requirements
+- Steps - Step-by-step guide
+- Verification - How to verify
+- Troubleshooting - Common issues
+- References - Related docs
+
+### Checklist
+Task checklists, verification lists.
+
+**Template sections**:
+- Purpose - What it's for
+- Checklist Items - Items to check
+- Notes - Additional context
+- References - Related resources
+
+### Reference
+Reference materials, links, documentation.
+
+**Template sections**:
+- Overview - Brief description
+- Key Information - Important details
+- Usage - How to use
+- Examples - Practical examples
+- Related - Related references
+
+## Best Practices
+
+### When to Add Knowledge
+
+- ✅ After solving a difficult problem
+- ✅ When discovering a useful pattern
+- ✅ After making a mistake (lesson learned)
+- ✅ When creating a reusable workflow
+- ✅ When finding useful references
+
+### Tagging Strategy
+
+Use consistent, descriptive tags:
+- **Technology**: `javascript`, `python`, `react`, `node`
+- **Domain**: `backend`, `frontend`, `database`, `api`
+- **Type**: `design-pattern`, `performance`, `security`, `testing`
+- **Level**: `beginner`, `intermediate`, `advanced`
+
+### Organization Tips
+
+1. **Be Specific**: Clear, descriptive titles
+2. **Add Context**: Explain when and why
+3. **Include Examples**: Code snippets, screenshots
+4. **Link Related**: Reference other entries
+5. **Keep Updated**: Review and update periodically
+
+## Advanced Usage
+
+### Custom Templates
+
+Create custom templates in `.kiro/knowledge/.templates/`:
+
+```markdown
+---
+id: {{ID}}
+type: custom-type
+title: {{TITLE}}
+created: {{DATE}}
+updated: {{DATE}}
+tags: []
+status: active
+---
+
+## Your Custom Sections
+
+Content here...
+```
+
+### Bulk Operations
+
+```bash
+# Export all entries
+kse knowledge export --output my-knowledge.zip
+
+# Import entries
+kse knowledge import my-knowledge.zip
+```
+
+### Integration with Project
+
+Knowledge entries can reference project files:
+
+```markdown
+## Related Code
+
+See implementation in `lib/repository/user-repository.js`
+```
+
+## Troubleshooting
+
+### Knowledge Base Not Found
+
+```bash
+Error: Knowledge base not initialized
+```
+
+**Solution**: Run `kse knowledge init`
+
+### Entry Not Found
+
+```bash
+Error: Entry not found: kb-xxx
+```
+
+**Solution**: Check ID with `kse knowledge list`
+
+### Corrupted Index
+
+```bash
+Error: Failed to load index
+```
+
+**Solution**: Rebuild index:
+```bash
+# Delete index.json
+rm .kiro/knowledge/index.json
+
+# Reinitialize
+kse knowledge init
+```
+
+## FAQ
+
+**Q: Where is knowledge stored?**  
+A: In `.kiro/knowledge/` directory, organized by type.
+
+**Q: Can I edit entries manually?**  
+A: Yes, they're just Markdown files with YAML frontmatter.
+
+**Q: How do I share knowledge with team?**  
+A: Commit `.kiro/knowledge/` to git (except `.backups/`).
+
+**Q: Can I use custom entry types?**  
+A: Yes, create custom templates in `.kiro/knowledge/.templates/`.
+
+**Q: How do I backup my knowledge?**  
+A: Use `kse knowledge export` or commit to git.
+
+## See Also
+
+- [Command Reference](./command-reference.md)
+- [Quick Start](./quick-start.md)
+- [Spec Workflow](./spec-workflow.md)