scene-capability-engine 3.0.0

package/docs/zh/tools/windsurf-guide.md

@@ -0,0 +1,378 @@
+# 在 Windsurf 中使用 kse
+
+> 将 kse 与 Windsurf IDE 集成进行 AI 辅助开发的完整指南
+
+---
+
+**版本**: 1.42.0  
+**最后更新**: 2026-02-11  
+**工具**: Windsurf IDE  
+**集成模式**: 原生 + Watch 模式  
+**预计设置时间**: 2 分钟
+
+---
+
+## 概述
+
+**Windsurf** 是一个 AI 驱动的 IDE，具有强大的命令执行能力。它可以直接运行 shell 命令，使其成为 kse 的理想选择。
+
+**kse 与 Windsurf 的集成**支持**原生模式**和**Watch 模式**，实现最无缝的体验。
+
+### 为什么在 Windsurf 中使用 kse？
+
+- ✅ **原生命令执行** - Windsurf 可以直接运行 kse 命令
+- ✅ **自动化工作流** - 无需手动导出/粘贴
+- ✅ **Watch 模式支持** - 自动上下文更新
+- ✅ **完全集成** - 最无缝的 kse 体验
+
+---
+
+## 集成模式
+
+**模式：** 原生 + Watch 模式
+
+**工作原理：**
+1. 你在 kse 中创建 Spec（需求、设计、任务）
+2. 你告诉 Windsurf："使用 kse 检查 spec 并实现任务 1.1"
+3. Windsurf 自动运行 `kse context export`
+4. Windsurf 读取导出的上下文
+5. Windsurf 生成代码
+6. Windsurf 可以更新 tasks.md 中的任务状态
+
+---
+
+## 设置
+
+### 前置条件
+
+- 已安装 **Windsurf IDE**（[下载](https://windsurf.ai/)）
+- 已全局安装 **kse**（`npm install -g kiro-spec-engine`）
+- 项目已被 kse **采用**（`kse adopt`）
+
+### 步骤 1：验证 kse 可访问
+
+在 Windsurf 终端中：
+```bash
+kse --version
+```
+
+应显示版本号（例如 1.3.0）。
+
+### 步骤 2：启用 Watch 模式（可选但推荐）
+
+Watch 模式在文件更改时自动更新上下文：
+
+```bash
+kse watch start
+```
+
+这会在后台启动文件监视器。
+
+---
+
+## 使用方法
+
+### 方法 1：直接命令（推荐）
+
+**最简单的方法** - 只需告诉 Windsurf 使用 kse！
+
+**步骤：**
+
+1. **在 Windsurf 中打开聊天**
+
+2. **告诉 Windsurf：**
+   ```
+   使用 kse 检查 01-00-user-login 的 spec 并实现任务 1.1
+   ```
+
+3. **Windsurf 将：**
+   - 运行 `kse context export 01-00-user-login`
+   - 读取导出的上下文
+   - 理解需求和设计
+   - 生成代码
+   - 创建或修改文件
+   - 可选：更新 tasks.md
+
+### 方法 2：分步命令
+
+**更多控制** - 明确告诉 Windsurf 每一步做什么。
+
+**步骤：**
+
+1. **导出上下文：**
+   ```
+   请运行：kse context export 01-00-user-login
+   ```
+
+2. **读取上下文：**
+   ```
+   请读取 .kiro/specs/01-00-user-login/context-export.md
+   ```
+
+3. **实现任务：**
+   ```
+   现在请实现任务 1.1："设置项目依赖"
+   严格遵循 design.md 中的架构。
+   ```
+
+4. **更新任务状态：**
+   ```
+   请在 .kiro/specs/01-00-user-login/tasks.md 中将任务 1.1 标记为完成
+   ```
+
+### 方法 3：Watch 模式 + 自动更新
+
+**最自动化** - 文件更改时自动更新上下文。
+
+**步骤：**
+
+1. **启动 Watch 模式：**
+   ```bash
+   kse watch start
+   ```
+
+2. **配置 Watch 模式以在更改时导出：**
+   ```bash
+   kse watch add --pattern ".kiro/specs/*/requirements.md" --action "kse context export {spec}"
+   kse watch add --pattern ".kiro/specs/*/design.md" --action "kse context export {spec}"
+   ```
+
+3. **现在，当你更新 Spec 文件时：**
+   - Watch 模式自动重新导出上下文
+   - Windsurf 始终拥有最新的上下文
+   - 无需手动重新导出！
+
+---
+
+## 工作流示例
+
+### 完整功能实现工作流
+
+```bash
+# 1. 创建 Spec
+kse spec bootstrap --name 01-00-user-login --non-interactive
+
+# 2. 编写 requirements.md、design.md、tasks.md
+
+# 3. 在 Windsurf 中告诉 AI：
+"使用 kse 检查 01-00-user-login 的 spec 并实现任务 1.1"
+
+# 4. Windsurf 自动：
+# - 导出上下文
+# - 读取 Spec
+# - 生成代码
+# - 更新任务状态
+
+# 5. 审查更改
+
+# 6. 对下一个任务重复
+"现在请实现任务 1.2"
+```
+
+### 使用 Watch 模式的迭代开发
+
+```bash
+# 1. 启动 Watch 模式
+kse watch start
+
+# 2. 在 Windsurf 中实现任务
+"使用 kse 实现 01-00-user-login 的任务 1.1"
+
+# 3. 如果需要，更新 design.md
+# Watch 模式自动重新导出上下文
+
+# 4. 继续下一个任务
+"现在请实现任务 1.2"
+# Windsurf 使用更新的上下文
+```
+
+---
+
+## 最佳实践
+
+### 1. 使用自然语言
+
+Windsurf 理解自然语言。只需说：
+```
+"使用 kse 检查 user-login spec 并实现下一个任务"
+```
+
+### 2. 让 Windsurf 管理任务
+
+Windsurf 可以更新任务状态：
+```
+"实现任务 1.1 并在 tasks.md 中标记为完成"
+```
+
+### 3. 使用 Watch 模式进行活跃开发
+
+在活跃开发期间启动 Watch 模式：
+```bash
+kse watch start
+```
+
+完成后停止：
+```bash
+kse watch stop
+```
+
+### 4. 批量实现任务
+
+Windsurf 可以实现多个任务：
+```
+"使用 kse 实现 01-00-user-login 的任务 1.1、1.2 和 1.3"
+```
+
+### 5. 要求验证
+
+让 Windsurf 验证实现：
+```
+"实现任务 1.1 并运行测试以验证它是否有效"
+```
+
+---
+
+## 示例提示
+
+### 实现新功能
+
+```
+使用 kse 检查 .kiro/specs/01-00-user-login/ 中的 spec 并实现任务 1.1："设置项目依赖"。
+
+严格遵循 design.md 中的架构。
+完成后在 tasks.md 中标记任务为完成。
+```
+
+### 实现多个任务
+
+```
+使用 kse 检查 01-00-user-login spec 并实现阶段 1 的所有任务（1.1 和 1.2）。
+
+对于每个任务：
+1. 实现代码
+2. 编写测试
+3. 在 tasks.md 中标记为完成
+```
+
+### 调试问题
+
+```
+我正在实现 01-00-user-login spec。
+
+任务 2.1 已完成，但测试失败。请：
+1. 使用 kse 检查 spec
+2. 审查我的代码
+3. 识别问题
+4. 修复它
+5. 运行测试以验证
+```
+
+---
+
+## Watch 模式配置
+
+### 基本 Watch 配置
+
+在 Spec 更改时自动导出上下文：
+
+```bash
+# 监视 requirements.md 更改
+kse watch add --pattern ".kiro/specs/*/requirements.md" --action "kse context export {spec}"
+
+# 监视 design.md 更改
+kse watch add --pattern ".kiro/specs/*/design.md" --action "kse context export {spec}"
+
+# 监视 tasks.md 更改
+kse watch add --pattern ".kiro/specs/*/tasks.md" --action "kse context export {spec}"
+```
+
+### 高级 Watch 配置
+
+在 Spec 更改时运行测试：
+
+```bash
+# 在任务更新时运行测试
+kse watch add --pattern ".kiro/specs/*/tasks.md" --action "npm test"
+
+# 在设计更改时运行 linter
+kse watch add --pattern ".kiro/specs/*/design.md" --action "npm run lint"
+```
+
+### 检查 Watch 状态
+
+```bash
+# 查看 Watch 模式是否正在运行
+kse watch status
+
+# 列出所有 watch 规则
+kse watch list
+
+# 停止 Watch 模式
+kse watch stop
+```
+
+---
+
+## 故障排除
+
+### 问题：Windsurf 找不到 kse 命令
+
+**解决方案：**
+1. 验证 kse 已全局安装：
+   ```bash
+   npm list -g kiro-spec-engine
+   ```
+2. 重启 Windsurf
+3. 检查 PATH 是否包含 npm 全局 bin
+
+### 问题：Watch 模式未触发
+
+**解决方案：**
+1. 检查 Watch 模式是否正在运行：
+   ```bash
+   kse watch status
+   ```
+2. 验证文件模式是否正确：
+   ```bash
+   kse watch list
+   ```
+3. 重启 Watch 模式：
+   ```bash
+   kse watch stop
+   kse watch start
+   ```
+
+### 问题：Windsurf 不遵循设计
+
+**解决方案：**
+1. 使你的 design.md 更详细
+2. 在提示中明确："严格遵循 design.md"
+3. 要求 Windsurf 先读取设计：
+   ```
+   首先读取 .kiro/specs/01-00-user-login/design.md
+   然后实现任务 1.1
+   ```
+
+---
+
+## 相关文档
+
+- 📖 [快速入门指南](../quick-start.md) - 开始使用 kse
+- 🔌 [集成模式](../integration-modes.md) - 理解原生和 Watch 模式
+- 📋 [Spec 工作流](../spec-workflow.md) - 创建有效的 Spec
+- 🔧 [故障排除](../troubleshooting.md) - 常见问题
+
+---
+
+## 下一步
+
+- 尝试使用 Windsurf 的原生命令实现你的第一个任务
+- 设置 Watch 模式进行自动上下文更新
+- 探索批量任务实现
+- 查看 [API 示例](../examples/add-rest-api/) 获取完整的 Spec 示例
+
+---
+
+**版本**: 1.42.0  
+**最后更新**: 2026-02-11
+

package/docs/zh/value-observability-guide.md

@@ -0,0 +1,127 @@
+# Value 可观测指南
+
+> 使用 `kse value metrics` 将 Spec 交付变成可量化、可审计的周度结果。
+
+---
+
+## 为什么这很重要
+
+很多 AI 开发流程可以“产出代码”，但难以回答：
+
+- 本周是否比上周交付更快？
+- 质量是在改善还是恶化？
+- Day30/Day60 是否应该放行？
+
+kse 通过机器可读 KPI 快照、基线生成、趋势分析和门禁摘要，解决以上问题。
+
+---
+
+## 四条命令跑通 KPI 流程
+
+```bash
+# 0) 首次使用先生成输入样例
+kse value metrics sample --out ./kpi-input.json --period 2026-W10 --json
+
+# 1) 生成当周快照
+kse value metrics snapshot --input ./kpi-input.json --period 2026-W10 --checkpoint day-60 --json
+
+# 2) 从最早历史快照生成 baseline
+kse value metrics baseline --from-history 3 --period 2026-W10 --json
+
+# 3) 基于最近窗口输出趋势与风险
+kse value metrics trend --window 6 --json
+```
+
+---
+
+## 最小输入示例
+
+如果不使用 `sample` 命令，也可以手工创建 `kpi-input.json`：
+
+```json
+{
+  "period": "2026-W10",
+  "metrics": {
+    "ttfv_minutes": 25,
+    "batch_success_rate": 0.86,
+    "cycle_reduction_rate": 0.34,
+    "manual_takeover_rate": 0.16
+  },
+  "notes": "weekly review snapshot"
+}
+```
+
+---
+
+## 预期 JSON 输出示例
+
+`snapshot --json` 会返回可机器读取的摘要结果：
+
+```json
+{
+  "success": true,
+  "period": "2026-W10",
+  "risk_level": "medium",
+  "triggered_metrics": [
+    "manual_takeover_rate"
+  ],
+  "snapshot_path": ".kiro/specs/114-00-kpi-automation-and-observability/custom/weekly-metrics/2026-W10.json",
+  "gate_summary_path": ".kiro/specs/114-00-kpi-automation-and-observability/custom/weekly-metrics/gate-summary.2026-W10.day-60.json",
+  "contract_path": "metric-definition.yaml"
+}
+```
+
+`trend --json` 会返回时间窗口、风险和指标方向信息：
+
+```json
+{
+  "success": true,
+  "period": "2026-W10",
+  "window_size": 3,
+  "range": {
+    "from": "2026-W08",
+    "to": "2026-W10"
+  },
+  "risk_level": "high",
+  "triggered_metrics": [
+    "ttfv_minutes"
+  ],
+  "metrics": [
+    {
+      "metric_id": "ttfv_minutes",
+      "delta": 3,
+      "trend": "up",
+      "better_direction": "lower",
+      "status": "degraded",
+      "target_passed": true
+    }
+  ],
+  "trend_path": ".kiro/specs/114-00-kpi-automation-and-observability/custom/weekly-metrics/trend.latest.json"
+}
+```
+
+---
+
+## 周度运行节奏（建议）
+
+1. 每周主要交付批次完成后执行一次 `snapshot`。
+2. 当流程或范围发生明显变化时重建 baseline。
+3. Day30/Day60 决策前执行 `trend`。
+4. 将输出 JSON 作为评审证据附在周报/门禁记录中。
+
+---
+
+## 你将获得
+
+- **可审计**：每次计算都有输入输出可追溯。
+- **可比较**：跨周、跨 Agent 使用统一指标口径。
+- **可门禁复用**：直接生成 Day30/Day60 可消费的决策输入。
+- **可行动**：风险触发原因清晰，不再依赖主观判断。
+
+---
+
+## 相关文档
+
+- [命令参考](../command-reference.md#value-metrics)
+- [快速入门](quick-start.md)
+- [Spec 工作流](../spec-workflow.md)

package/docs//344/272/244/344/273/230/346/270/205/345/215/225.md

@@ -0,0 +1,75 @@
+# kiro-spec-engine v1.42.0 交付清单
+
+## ✅ 交付物
+
+### 1. npm 包
+
+- ✅ **kiro-spec-engine@1.42.0** (npm registry)
+  - 安装: `npm install -g kiro-spec-engine`
+  - 验证: `kse --version` → 1.42.0
+
+### 2. 新功能（v1.25.0 ~ v1.42.0 Scene 系列）
+
+#### Spec 87: Scene Template Engine (v1.25.0)
+- ✅ 模板变量 Schema（string, number, boolean, enum, array）
+- ✅ 多文件渲染（`{{variable}}`、`{{#if}}`、`{{#each}}`）
+- ✅ 三层继承（L1-Capability / L2-Domain / L3-Instance）
+- ✅ CLI: `scene template-validate`, `scene template-resolve`, `scene template-render`
+
+#### Spec 90: Moqui ERP Adapter (v1.39.0)
+- ✅ MoquiClient — JWT 认证生命周期 HTTP 客户端
+- ✅ MoquiAdapter — 绑定处理器（实体 CRUD、服务调用、屏幕发现）
+- ✅ CLI: `scene connect`, `scene discover`
+
+#### Spec 91: Moqui Scene Template Extractor (v1.40.0)
+- ✅ MoquiExtractor — 分析 Moqui 资源，识别业务模式
+- ✅ Header/Item 后缀模式分组，生成治理合约
+- ✅ CLI: `scene extract`
+
+#### Spec 92: Scene Template Quality Pipeline (v1.41.0)
+- ✅ Lint 引擎 — 7 类质量检查（清单、绑定、治理、一致性、变量、文档）
+- ✅ 质量评分 — 4 维度 0-100 分制
+- ✅ 一站式贡献流水线（validate → lint → score → preview → publish）
+- ✅ CLI: `scene lint`, `scene score`, `scene contribute`
+
+#### Spec 93: Scene Ontology Enhancement (v1.42.0)
+- ✅ OntologyGraph — 语义关系图（depends_on, composes, extends, produces）
+- ✅ Action Abstraction — intent, preconditions, postconditions
+- ✅ Data Lineage — source → transform → sink 数据血缘
+- ✅ Agent Hints — summary, complexity, duration, permissions, sequence
+- ✅ Agent Readiness 评分 — 质量评分加分维度（最高 +10）
+- ✅ Lint 扩展 — 3 个新检查类别（action_abstraction, data_lineage, agent_hints），共 10 类
+- ✅ CLI: `scene ontology show|deps|validate|actions|lineage|agent-info`
+
+### 3. 质量保证
+
+- ✅ **测试**: 2361 tests passing, 88 suites (100%)
+- ✅ **跨平台**: Windows/Unix 路径兼容
+- ✅ **文档**: README.md, README.zh.md, docs/command-reference.md 已同步更新
+
+## 📊 技术指标
+
+- **Node.js**: >= 16.0.0
+- **Python**: >= 3.8.0 (可选)
+- **测试套件**: 88 suites, 2361 tests
+- **Spec 完成数**: 93
+
+## 📝 文档
+
+- **README.md** / **README.zh.md** — 项目说明（已更新至 v1.42.0）
+- **docs/command-reference.md** — 命令参考（已更新至 v1.42.0）
+- **docs/scene-runtime-guide.md** — Scene 功能完整指南
+- **CHANGELOG.md** — 变更日志
+
+## 📧 支持资源
+
+- **GitHub**: https://github.com/heguangyong/scene-capability-engine
+- **文档**: `docs/README.md`
+- **快速开始**: `docs/quick-start.md`
+- **故障排除**: `docs/troubleshooting.md`
+
+---
+
+**交付日期**: 2026-02-11  
+**版本**: v1.42.0  
+**状态**: ✅ 已完成