sinapse-ai 5.0.8 → 6.0.1

package/docs/zh/guides/build-recovery-guide.md

@@ -1,266 +0,0 @@
-# 构建恢复指南
-
-> [EN](../../guides/build-recovery-guide.md) | **ZH**
-
-> **Story:** 8.4 - 构建恢复与恢复
-> **Epic:** Epic 8 - 自主构建引擎
-
----
-
-## 概述
-
-构建恢复系统使自主构建能够在失败或中断后从检查点恢复。构建不必从头开始,而是从最后成功的点继续。
-
----
-
-## 主要功能
-
-| 功能                      | 描述                                   |
-| ------------------------- | -------------------------------------- |
-| **检查点**                | 每个子任务完成后自动保存               |
-| **恢复**                  | 从最后一个检查点继续                   |
-| **状态监控**              | 实时构建进度                           |
-| **废弃检测**              | 对过时构建发出警报(> 1小时)          |
-| **失败通知**              | 卡住或达到最大迭代次数时发出警报       |
-| **尝试日志**              | 完整的调试历史记录                     |
-
----
-
-## 命令
-
-### 检查构建状态
-
-```bash
-# 单个构建
-*build-status story-8.4
-
-# 所有活动构建
-*build-status --all
-```
-
-### 恢复失败的构建
-
-```bash
-*build-resume story-8.4
-```
-
-### 查看尝试日志
-
-```bash
-*build-log story-8.4
-
-# 按子任务筛选
-*build-log story-8.4 --subtask 2.1
-
-# 限制输出
-*build-log story-8.4 --limit 20
-```
-
-### 清理废弃的构建
-
-```bash
-*build-cleanup story-8.4
-
-# 强制清理(即使是活动构建)
-*build-cleanup story-8.4 --force
-```
-
----
-
-## 构建状态 Schema
-
-构建状态存储在 `plan/build-state.json`:
-
-```json
-{
-  "storyId": "story-8.4",
-  "status": "in_progress",
-  "startedAt": "2026-01-29T10:00:00Z",
-  "lastCheckpoint": "2026-01-29T11:30:00Z",
-  "currentPhase": "phase-2",
-  "currentSubtask": "2.3",
-  "completedSubtasks": ["1.1", "1.2", "2.1", "2.2"],
-  "checkpoints": [...],
-  "metrics": {
-    "totalSubtasks": 10,
-    "completedSubtasks": 4,
-    "totalAttempts": 6,
-    "totalFailures": 2
-  }
-}
-```
-
----
-
-## 状态值
-
-| 状态          | 描述                         |
-| ------------- | ---------------------------- |
-| `pending`     | 构建已创建但尚未开始         |
-| `in_progress` | 构建正在运行                 |
-| `paused`      | 构建已手动暂停               |
-| `abandoned`   | 超过 1 小时无活动            |
-| `failed`      | 构建失败(可恢复)           |
-| `completed`   | 构建成功完成                 |
-
----
-
-## 检查点系统
-
-每个子任务完成后自动保存检查点:
-
-```
-plan/
-├── build-state.json        # 主状态文件
-├── build-attempts.log      # 尝试日志
-└── checkpoints/            # 检查点快照
-    ├── cp-lxyz123-abc.json
-    ├── cp-lxyz124-def.json
-    └── ...
-```
-
-每个检查点包含:
-
-- 时间戳
-- 子任务 ID
-- Git 提交(如果可用)
-- 修改的文件
-- 持续时间和尝试次数
-
----
-
-## 与 Epic 5 的集成
-
-构建恢复与恢复系统(Epic 5)集成:
-
-| 组件                  | 用途                       |
-| --------------------- | -------------------------- |
-| `stuck-detector.js`   | 检测循环失败               |
-| `recovery-tracker.js` | 跟踪尝试历史               |
-
-当构建卡住(连续 3 次以上失败)时,系统会:
-
-1. 根据错误模式生成建议
-2. 创建通知以供人工审核
-3. 将子任务标记为"卡住"
-
----
-
-## 废弃构建检测
-
-如果满足以下条件,构建将被标记为废弃:
-
-- 状态为 `in_progress`
-- 超过 1 小时无检查点(可配置)
-
-检测和处理:
-
-```bash
-# 检查是否废弃
-*build-status story-8.4  # 如果废弃会显示警告
-
-# 清理
-*build-cleanup story-8.4
-```
-
----
-
-## 编程式使用
-
-```javascript
-const { BuildStateManager, BuildStatus } = require('.sinapse-ai/core/execution/build-state-manager');
-
-// 创建管理器
-const manager = new BuildStateManager('story-8.4', {
-  planDir: './plan',
-});
-
-// 创建或加载状态
-const state = manager.loadOrCreateState({ totalSubtasks: 10 });
-
-// 开始子任务
-manager.startSubtask('1.1', { phase: 'phase-1' });
-
-// 完成子任务(自动检查点)
-manager.completeSubtask('1.1', {
-  duration: 5000,
-  filesModified: ['src/file.js'],
-});
-
-// 记录失败
-const result = manager.recordFailure('1.2', {
-  error: 'TypeScript error',
-  attempt: 1,
-});
-
-// 检查是否卡住
-if (result.isStuck) {
-  console.log('Suggestions:', result.suggestions);
-}
-
-// 恢复构建
-const context = manager.resumeBuild();
-
-// 获取状态
-const status = manager.getStatus();
-console.log(`Progress: ${status.progress.percentage}%`);
-```
-
----
-
-## 配置
-
-默认配置可以覆盖:
-
-```javascript
-const manager = new BuildStateManager('story-8.4', {
-  config: {
-    maxIterations: 10,        // 每个子任务的最大尝试次数
-    globalTimeout: 1800000,   // 30 分钟
-    abandonedThreshold: 3600000, // 1 小时
-    autoCheckpoint: true,     // 自动保存检查点
-  },
-});
-```
-
----
-
-## 故障排除
-
-### "No build state found"
-
-构建尚未开始。运行 `*build story-id` 以开始。
-
-### "Build already completed"
-
-无法恢复已完成的构建。如需要请启动新构建。
-
-### "Worktree missing"
-
-隔离的 worktree 已被删除。选项:
-
-1. 重新创建 worktree 并恢复
-2. 使用新构建重新开始
-
-### 构建卡住
-
-如果构建卡住(相同错误重复出现):
-
-1. 检查通知中的建议
-2. 查看尝试日志:`*build-log story-id`
-3. 尝试不同的方法或升级处理
-
----
-
-## 最佳实践
-
-1. 在长时间构建期间**定期检查状态**
-2. 调试失败时**查看日志**
-3. **清理废弃的构建**以释放资源
-4. **使用检查点** - 不要禁用自动检查点
-5. **监控通知**以获取卡住警报
-
----
-
-_Story 8.4 指南 - 构建恢复与恢复_
-_Epic 8 的一部分 - 自主构建引擎_

package/docs/zh/guides/contextual-greeting-system-guide.md

@@ -1,381 +0,0 @@
-# 上下文问候系统指南
-
-> [EN](../../guides/contextual-greeting-system-guide.md) | [PT](../../pt/guides/contextual-greeting-system-guide.md) | [ES](../../es/guides/contextual-greeting-system-guide.md) | **ZH**
-
----
-
-**故事:** 6.1.2.5 - 上下文代理加载系统
-**状态:** 组件已实现，集成待完成
-**日期:** 2025-01-15
-
----
-
-## 概述
-
-上下文问候系统是一项 UX 改进，使 SINAPSE 代理的问候变得智能和自适应，根据会话上下文显示相关信息和命令。
-
-## 已实现的内容
-
-### 核心组件 (Story 6.1.2.5)
-
-1. **ContextDetector** (`.sinapse-ai/core/session/context-detector.js`)
-   - 检测会话类型: `new`、`existing` 或 `workflow`
-   - 混合方法: 对话历史 (首选) + 会话文件 (后备)
-   - 非活动会话 TTL 1 小时
-
-2. **GitConfigDetector** (`.sinapse-ai/infrastructure/scripts/git-config-detector.js`)
-   - 检测项目的 git 配置
-   - TTL 5 分钟的缓存
-   - 1000ms 超时保护
-
-3. **GreetingBuilder** (`.sinapse-ai/development/scripts/greeting-builder.js`)
-   - 根据会话类型构建上下文问候
-   - 按可见性过滤命令 (full/quick/key)
-   - 150ms 超时并优雅回退
-
-4. **WorkflowNavigator** (`.sinapse-ai/development/scripts/workflow-navigator.js`)
-   - 检测当前工作流状态
-   - 根据状态建议下一个命令
-   - 预填充带上下文的命令 (story path, branch)
-
-5. **工作流模式** (`.sinapse-ai/data/workflow-patterns.yaml`)
-   - 定义了 10 个常见工作流
-   - 带下一步建议的状态转换
-   - 根据实际项目使用验证的模式
-
-### 待完成 (未来故事 - 6.1.4 或 6.1.6)
-
-**与激活流程的集成:**
-- 拦截代理激活 (当您输入 `@dev`、`@po` 等时)
-- 自动调用 GreetingBuilder
-- 在默认问候位置注入上下文问候
-
-## 会话类型
-
-### 1. 新会话
-
-**何时:** 首次交互或 1 小时不活动后
-
-**特点:**
-- 完整介绍 (archetypal 问候)
-- 代理角色描述
-- 项目状态 (如果配置了 git)
-- 完整命令 (visibility=full 的最多 12 个命令)
-
-**示例:**
-```
-💻 Dex (Builder) 准备就绪。让我们构建一些很棒的东西!
-
-**角色:** 专注于干净、可维护代码的全栈开发者
-
-📊 项目状态:
-🌿 main
-📝 5 个修改的文件
-📦 最后提交: feat: implement greeting system
-
-**可用命令:**
-   - `*help`: 显示所有可用命令
-   - `*develop`: 实现故事任务
-   - `*review-code`: 审查代码更改
-   - `*run-tests`: 执行测试套件
-   - `*build`: 为生产构建
-   ... (最多 12 个命令)
-```
-
-### 2. 现有会话
-
-**何时:** 在同一会话中继续工作
-
-**特点:**
-- 简短介绍 (named 问候)
-- 项目状态
-- 当前上下文 (上次操作)
-- 快速命令 (visibility=quick 的 6-8 个命令)
-
-**示例:**
-```
-💻 Dex (Builder) 准备就绪。
-
-📊 项目状态:
-🌿 feature/story-6.1.2.5
-📝 3 个修改的文件
-
-📌 **上次操作:** review-code
-
-**快速命令:**
-   - `*help`: 显示帮助
-   - `*develop`: 实现故事
-   - `*review-code`: 审查代码
-   - `*run-tests`: 运行测试
-   - `*qa-gate`: 运行质量门禁
-   ... (6-8 个最常用的命令)
-```
-
-### 3. 工作流会话
-
-**何时:** 在活动工作流中 (例如: 验证故事后)
-
-**特点:**
-- 最小介绍 (minimal 问候)
-- 压缩的项目状态
-- 工作流上下文 (正在处理 X)
-- **下一步建议** (新功能!)
-- 关键命令 (visibility=key 的 3-5 个命令)
-
-**示例:**
-```
-⚖️ Pax 准备就绪。
-
-📊 🌿 main | 📝 5 个修改 | 📖 STORY-6.1.2.5
-
-📌 **上下文:** 正在处理 Story 6.1.2.5
-
-**故事已验证! 下一步:**
-
-1. `*develop-yolo story-6.1.2.5.md` - 自主模式 (无中断)
-2. `*develop-interactive story-6.1.2.5.md` - 交互模式带检查点
-3. `*develop-preflight story-6.1.2.5.md` - 先计划，后执行
-
-**关键命令:**
-   - `*help`: 显示帮助
-   - `*validate-story-draft`: 验证故事
-   - `*backlog-summary`: 快速待办状态
-```
-
-## 命令可见性系统
-
-### 命令元数据
-
-每个命令现在有一个 `visibility` 属性，控制何时显示:
-
-```yaml
-commands:
-  - name: help
-    visibility: [full, quick, key]  # 始终可见
-    description: "显示所有可用命令"
-
-  - name: develop
-    visibility: [full, quick, key]  # 主要命令
-    description: "实现故事任务"
-
-  - name: review-code
-    visibility: [full, quick]  # 经常使用，但非关键
-    description: "审查代码更改"
-
-  - name: build
-    visibility: [full]  # 不常用，仅在新会话中
-    description: "为生产构建"
-
-  - name: qa-gate
-    visibility: [key]  # 在工作流中关键，但不总是需要
-    description: "运行质量门禁"
-```
-
-### 分类指南
-
-**`full` (12 个命令)** - 新会话
-- 所有可用命令
-- 展示代理的完整能力
-- 适合发现
-
-**`quick` (6-8 个命令)** - 现有会话
-- 经常使用的命令
-- 专注于生产力
-- 移除不常用的命令
-
-**`key` (3-5 个命令)** - 工作流会话
-- 当前工作流的关键命令
-- 最小干扰
-- 最大效率
-
-## 工作流导航
-
-### 定义的工作流
-
-**10 个常见工作流:**
-
-1. **story_development** - 验证 → 开发 → QA → 部署
-2. **epic_creation** - 创建史诗 → 创建故事 → 验证
-3. **backlog_management** - 审查 → 优先级 → 安排
-4. **architecture_review** - 分析 → 文档 → 审查
-5. **git_workflow** - 质量门禁 → PR → 合并
-6. **database_workflow** - 设计 → 迁移 → 测试
-7. **code_quality_workflow** - 评估 → 重构 → 测试
-8. **documentation_workflow** - 研究 → 文档 → 同步
-9. **ux_workflow** - 设计 → 实现 → 验证
-10. **research_workflow** - 头脑风暴 → 分析 → 文档
-
-### 状态转换
-
-每个工作流定义状态之间的转换:
-- **Trigger:** 成功完成的命令
-- **Greeting Message:** 上下文消息
-- **Next Steps:** 带预填充参数的下一个命令建议
-
-**示例 (Story Development):**
-
-```yaml
-story_development:
-  transitions:
-    validated:
-      trigger: "validate-story-draft 成功完成"
-      greeting_message: "故事已验证! 准备实现。"
-      next_steps:
-        - command: develop-yolo
-          args_template: "${story_path}"
-          description: "自主 YOLO 模式 (无中断)"
-        - command: develop-interactive
-          args_template: "${story_path}"
-          description: "交互模式带检查点 (默认)"
-        - command: develop-preflight
-          args_template: "${story_path}"
-          description: "先全部计划，然后执行"
-```
-
-## 如何测试
-
-### 选项 1: 自动测试脚本
-
-```bash
-node .sinapse-ai/development/scripts/test-greeting-system.js
-```
-
-此脚本测试 4 种场景:
-1. 新会话问候 (Dev)
-2. 现有会话问候 (Dev)
-3. 工作流会话问候 (PO)
-4. 简单问候回退
-
-### 选项 2: Node REPL 手动测试
-
-```javascript
-const GreetingBuilder = require('./.sinapse-ai/development/scripts/greeting-builder');
-const builder = new GreetingBuilder();
-
-// 模拟代理
-const mockAgent = {
-  name: 'Dex',
-  icon: '💻',
-  persona_profile: {
-    greeting_levels: {
-      named: '💻 Dex (Builder) 准备就绪!'
-    }
-  },
-  persona: { role: '开发者' },
-  commands: [
-    { name: 'help', visibility: ['full', 'quick', 'key'] }
-  ]
-};
-
-// 测试新会话
-builder.buildGreeting(mockAgent, { conversationHistory: [] })
-  .then(greeting => console.log(greeting));
-```
-
-### 选项 3: 等待完整集成
-
-当与激活流程的集成实现后 (Story 6.1.4/6.1.6)，系统将在激活任何代理时自动工作:
-
-```
-@dev              → 自动上下文问候
-@po               → 自动上下文问候
-@qa               → 自动上下文问候
-```
-
-## 相关文件
-
-### 核心脚本
-- `.sinapse-ai/core/session/context-detector.js` - 会话类型检测
-- `.sinapse-ai/infrastructure/scripts/git-config-detector.js` - Git 配置检测
-- `.sinapse-ai/development/scripts/greeting-builder.js` - 问候构建
-- `.sinapse-ai/development/scripts/workflow-navigator.js` - 工作流导航
-- `.sinapse-ai/development/scripts/agent-exit-hooks.js` - 退出钩子 (用于持久化)
-
-### 数据文件
-- `.sinapse-ai/data/workflow-patterns.yaml` - 工作流定义
-
-### 测试
-- `tests/unit/context-detector.test.js` - 23 个测试
-- `tests/unit/git-config-detector.test.js` - 19 个测试
-- `tests/unit/greeting-builder.test.js` - 23 个测试
-- `tests/integration/performance.test.js` - 性能验证
-
-### 配置
-- `.sinapse-ai/core-config.yaml` - 全局配置 (git + agentIdentity 部分)
-
-### 代理 (已更新)
-- `.sinapse-ai/agents/dev.md` - ✅ 命令可见性元数据
-- `.sinapse-ai/agents/po.md` - ✅ 命令可见性元数据
-- `.sinapse-ai/agents/*.md` - ⏳ 剩余 9 个代理 (待更新)
-
-## 下一步
-
-### 立即 (修复测试问题)
-1. 修复测试配置问题 (1-2 小时)
-2. 运行完整测试套件
-3. 执行性能测试
-
-### 短期 (Story 6.1.4 或 6.1.6)
-1. 实现与代理激活流程的集成
-2. 更新剩余 9 个代理的命令可见性元数据
-3. 使用真实代理激活进行测试
-
-### 长期 (Story 6.1.2.6)
-1. 实现动态工作流模式学习
-2. 添加基于使用的命令优先级
-3. 实现代理协作提示
-
-## 性能指标
-
-**目标 (来自 Story 6.1.2.5):**
-- P50 延迟: <100ms
-- P95 延迟: <130ms
-- P99 延迟: <150ms (硬限制)
-
-**预期 (基于代码审查):**
-- Git 配置 (缓存命中): <5ms ✅
-- Git 配置 (缓存未命中): <50ms ✅
-- 上下文检测: <50ms ✅
-- 会话文件 I/O: <10ms ✅
-- 工作流匹配: <20ms ✅
-- **总计 P99:** ~100-120ms ✅ (远低于限制)
-
-**优化:**
-- 并行执行 (Promise.all)
-- 基于 TTL 的缓存
-- 超时保护
-- 缓存命中时提前退出
-
-## 向后兼容性
-
-**100% 向后兼容:**
-- 没有可见性元数据的代理显示所有命令 (最多 12)
-- 任何错误时优雅回退到简单问候
-- 激活流程零破坏性更改
-- 渐进式迁移 (第 1 阶段: dev/po → 第 2 阶段: 剩余 9 个)
-
-## 常见问题
-
-**Q: 为什么我激活代理时问候不是上下文的?**
-A: 与激活流程的集成尚未实现。组件存在但尚未自动调用。
-
-**Q: 集成何时完成?**
-A: 在未来的故事中 (可能是 6.1.4 或 6.1.6)。取决于代理配置系统。
-
-**Q: 如何现在测试?**
-A: 使用测试脚本: `node .sinapse-ai/development/scripts/test-greeting-system.js`
-
-**Q: 如果代理没有可见性元数据会发生什么?**
-A: 回退: 显示所有命令 (最多 12)。不会破坏任何东西。
-
-**Q: 如何给我的命令添加可见性元数据?**
-A: 参见上面的 "命令可见性系统" 部分和 dev.md 和 po.md 代理中的示例。
-
-**Q: 我可以禁用上下文问候吗?**
-A: 可以，通过配置: `core-config.yaml` → `agentIdentity.greeting.contextDetection: false`
-
----
-
-**文档更新:** 2025-01-15
-**作者:** Quinn (QA) + Dex (Dev)
-**故事:** 6.1.2.5 - 上下文代理加载系统