bobo-ai-cli 1.0.1

package/knowledge/rules/blocking-rules.md

@@ -0,0 +1,323 @@
+---
+id: "blocking-rules"
+title: "致命阻塞规则"
+category: "core"
+tags: ["致命阻塞规则", "🚨 唯一允许提问的4种情况", "✅ 不应该问的问题（自行决策）", "🤔 判断标准", "📝 决策优先级", "💡 示例对比", "🎯 总结"]
+source: "E:/Bobo's Coding cache/.claude/rules/core/blocking-rules.md"
+---
+
+# 致命阻塞规则
+
+> **原则**: 只在这4种情况下提问，其他情况自行决策
+
+---
+
+## 🚨 唯一允许提问的4种情况
+
+### 1️⃣ 缺少关键凭证
+
+**定义**: 必须的敏感信息，无法猜测或推断
+
+**示例**:
+
+- ❌ 数据库密码
+- ❌ API key
+- ❌ 私钥文件路径
+- ❌ 服务器 IP 地址
+
+**如何提问**:
+
+```
+需要 [具体信息] 才能继续：
+- [信息名称]
+- 用途：[为什么需要]
+```
+
+---
+
+### 2️⃣ 多个对立方案
+
+**定义**: 2+ 个方案完全对立，无法从代码库或上下文判断
+
+**示例**:
+
+- ❌ 使用 REST 还是 GraphQL？（架构级决策）
+- ❌ 数据存 MySQL 还是 PostgreSQL？（技术选型）
+- ❌ 用户认证用 OAuth 还是 JWT？（安全策略）
+
+**不是对立的**:
+
+- ✅ 函数命名风格（看代码库现有风格）
+- ✅ 文件组织方式（看项目结构）
+- ✅ UI 颜色选择（看设计规范或自行选择）
+
+**如何提问**:
+
+```
+有2个对立方案，需要决策：
+
+方案A: [描述]
+  优点: [...]
+  缺点: [...]
+
+方案B: [描述]
+  优点: [...]
+  缺点: [...]
+
+推荐: [方案X]，因为 [理由]
+
+是否继续？
+```
+
+---
+
+### 3️⃣ 需求本质矛盾
+
+**定义**: 用户的多个要求之间逻辑冲突
+
+**示例**:
+
+- ❌ "要快速开发，但每行代码都要完美"
+- ❌ "要最大安全性，但不要验证用户输入"
+- ❌ "要实时同步，但不能用 WebSocket"
+
+**如何提问**:
+
+```
+发现需求矛盾：
+
+要求A: [描述]
+要求B: [描述]
+
+这两者冲突，因为 [原因]
+
+可能的折中方案:
+- [方案1]
+- [方案2]
+
+请明确优先级。
+```
+
+---
+
+### 4️⃣ 不可逆高风险
+
+**定义**: 一旦执行无法撤销，且后果严重
+
+**示例**:
+
+- ❌ 删除生产数据库表
+- ❌ 强制推送到 main 分支（覆盖历史）
+- ❌ 删除整个代码目录
+- ❌ 撤销已发布的版本
+
+**如何提问**:
+
+```
+⚠️ 高风险操作警告
+
+操作: [具体动作]
+风险: [可能后果]
+不可逆: [无法撤销的原因]
+
+是否确认执行？
+
+建议: [更安全的替代方案，如果有]
+```
+
+---
+
+## ✅ 不应该问的问题（自行决策）
+
+### 文件命名
+
+**不要问**:
+
+- "文件应该叫什么名字？"
+- "放在哪个目录？"
+
+**自行决策**:
+
+- 遵循项目现有命名规范
+- 如无规范，使用常见约定
+- 例如: `user-service.ts`, `UserController.java`
+
+---
+
+### 代码风格
+
+**不要问**:
+
+- "用单引号还是双引号？"
+- "缩进用 2 空格还是 4 空格？"
+- "要不要加分号？"
+
+**自行决策**:
+
+- 检查项目中现有代码风格
+- 遵循语言社区标准
+- 例如: Python → PEP 8, JavaScript → Prettier
+
+---
+
+### 依赖版本
+
+**不要问**:
+
+- "应该用哪个版本的库？"
+- "要不要升级这个依赖？"
+
+**自行决策**:
+
+- 使用项目现有依赖的版本
+- 新依赖选择最新稳定版
+- 如有兼容性问题，选择兼容版本
+
+---
+
+### 测试策略
+
+**不要问**:
+
+- "需要写单元测试吗？"
+- "测试覆盖率要多少？"
+
+**自行决策**:
+
+- 遵循 `rules/domain/testing.md`
+- 默认要求: 80% 覆盖率
+- 关键路径必须测试
+
+---
+
+### UI 细节
+
+**不要问**:
+
+- "按钮用什么颜色？"
+- "字体多大？"
+- "间距多少？"
+
+**自行决策**:
+
+- 遵循设计规范（如果有）
+- 无规范时使用常见标准
+- 例如: 主按钮蓝色, 字体 16px, 间距 8px 倍数
+
+---
+
+## 🤔 判断标准
+
+### 提问前问自己：
+
+1. **能从代码库推断吗？**
+   → 能 → 不要问
+
+2. **有明确的最佳实践吗？**
+   → 有 → 不要问
+
+3. **是个人偏好问题吗？**
+   → 是 → 不要问（自行选择）
+
+4. **符合 4 种致命阻塞吗？**
+   → 否 → 不要问
+
+---
+
+## 📝 决策优先级
+
+遇到需要决策的情况：
+
+```
+1. 项目现有规范
+   ↓ (如果没有)
+2. 相关最佳实践
+   ↓ (如果没有)
+3. 语言/框架约定
+   ↓ (如果没有)
+4. 常见行业标准
+   ↓ (如果没有)
+5. 合理的默认选择
+```
+
+---
+
+## 💡 示例对比
+
+### ❌ 不好的提问
+
+**场景**: 用户要求 "写一个用户登录 API"
+
+**不要这样**:
+
+```
+问题1: 应该用什么数据库？
+问题2: 密码加密用什么算法？
+问题3: Token 过期时间设置多久？
+问题4: 错误提示用中文还是英文？
+问题5: API 路径是 /login 还是 /auth？
+```
+
+### ✅ 正确的做法
+
+**直接实现**:
+
+```
+数据库: 用项目现有的（检查配置文件）
+加密: bcrypt（行业标准）
+Token 过期: 24小时（常见默认值）
+错误提示: 跟项目其他 API 保持一致
+API 路径: /auth/login（RESTful 约定）
+```
+
+**展示计划让用户确认** → 执行
+
+---
+
+### ✅ 合理的提问
+
+**场景**: 用户要求 "清理所有测试数据"
+
+**这样提问**:
+
+```
+⚠️ 高风险操作警告
+
+操作: 删除数据库中所有 test_* 开头的记录
+风险: 如果有生产数据也以 test_ 开头，会被误删
+不可逆: 删除后无法恢复
+
+是否确认执行？
+
+建议: 先备份数据库，或者先 SELECT 确认要删除的记录
+```
+
+---
+
+## 🎯 总结
+
+**工作原则**:
+
+```
+自行决策 > 展示计划确认 > 提问
+
+提问是最后的手段，只用于 4 种致命阻塞。
+```
+
+**好的工作模式**:
+
+- 快速规划 → 展示 → 确认 → 执行
+- 95% 的问题都能自行决策
+- 5% 的真正阻塞才提问
+
+**不好的工作模式**:
+
+- 遇到任何小事都问
+- 让用户做所有决策
+- 浪费时间在不重要的细节上
+
+---
+
+**版本**: v1.0
+**来源**: CLAUDE.md v4.2 核心原则
+**状态**: Active

package/knowledge/rules/cache-management.md

@@ -0,0 +1,379 @@
+---
+id: "cache-management"
+title: "Cache Management & Token Optimization"
+category: "domain"
+tags: ["🔥 token 燃烧根本原因", "✅ 解决方案矩阵", "🎯 优先级规则", "📊 监控和验证", "每个会话开始时运行", "输出示例", "周期性审计", "🔧 集成到工作流", "1. 检查 cc-cache-fix 是否安装", "2. 运行缓存预热"]
+source: "E:/Bobo's Coding cache/.claude/rules/domain/cache-management.md"
+---
+
+# Cache Management & Token Optimization
+
+> **版本**: v1.0 (2026-04-01)
+> **来源**: cc-cache-fix 集成 + Claude Code 缓存分析
+> **目标**: 减少 60-70% token 燃烧，提升缓存命中率
+
+---
+
+## 🔥 Token 燃烧根本原因
+
+### 问题1: Prompt Cache 利用率极低
+- **症状**: `cacheCreationInputTokens` = 0, `cacheReadInputTokens` << total input
+- **原因**: Delta 附件丢失、Hash 不稳定、TTL 过短
+- **影响**: 每次对话重新计算，浪费 70% tokens
+
+### 问题2: 会话恢复缓存丢失
+- **症状**: 恢复会话后，缓存完全失效
+- **原因**: `deferred_tools_delta` 和 `mcp_instructions_delta` 未持久化
+- **影响**: 长期项目中每次恢复都是冷启动
+
+### 问题3: Hash 不稳定
+- **症状**: 相同内容不同 turn 的缓存键不同
+- **原因**: 注入的元数据（时间戳、ID）影响 hash
+- **影响**: 缓存失效率 40-50%
+
+### 问题4: TTL 过短
+- **症状**: 5分钟后缓存过期，需要重新计算
+- **原因**: Claude Code 默认 TTL 设置
+- **影响**: 中等长度会话（>5分钟）缓存无效
+
+---
+
+## ✅ 解决方案矩阵
+
+### 方案A: 使用 cc-cache-fix（快速修复）
+
+**安装**:
+```bash
+git clone https://github.com/Rangizingo/cc-cache-fix.git
+cd cc-cache-fix
+./install.sh
+```
+
+**使用**:
+```bash
+claude-patched  # 替代 claude 命令
+```
+
+**效果**:
+- ✅ 补丁1: 会话恢复缓存保留 → +30% 缓存命中
+- ✅ 补丁2: Hash 稳定性 → +20% 缓存命中
+- ✅ 补丁3: TTL 1小时 → +15% 缓存命中
+- **总计**: ~60% token 节省（相对基准）
+
+**验证**:
+```bash
+python test_cache.py      # 检查缓存健康度
+python usage_audit.py     # 审计读取效率
+```
+
+---
+
+### 方案B: Context 压缩（根本优化）
+
+**触发条件**: 任何会话开始时
+
+**执行步骤**:
+
+1. **加载必需文档**（按需加载，不全量）
+   ```
+   Layer 0: CLAUDE.md (5KB) + 核心规则 (15KB)
+   Layer 1: Task Router (3KB)
+   Layer 2: 相关能力文档 (15-30KB)
+   Layer 3: 具体案例 (按需)
+   ```
+
+2. **压缩 CLAUDE.md**
+   - 删除重复内容
+   - 提取关键规则到 `rules/domain/`
+   - 保留索引，不保留详细内容
+
+3. **分离项目级规则**
+   - 全局规则: `~/.claude/rules/`
+   - 项目规则: `.claude/rules/`
+   - 不混合加载
+
+4. **使用 Context Manager**
+   - 自动识别任务类型
+   - 按需加载相关文档
+   - 保持 context 清洁
+
+**效果**: 减少 40-50% 初始 context 大小
+
+---
+
+### 方案C: 会话分割（长任务优化）
+
+**触发条件**: 任务预计 >1小时
+
+**执行步骤**:
+
+1. **分割策略**
+   ```
+   长任务 (>1小时)
+     ↓
+   分成 3-5 个短会话 (15-20分钟)
+     ↓
+   每个会话独立缓存
+     ↓
+   总 token 节省 30-40%
+   ```
+
+2. **会话间数据传递**
+   - 使用 `task_plan.md` 保存进度
+   - 使用 `notes.md` 保存发现
+   - 下一个会话加载这两个文件
+
+3. **缓存预热**
+   - 会话开始时加载前一个会话的关键上下文
+   - 避免重复计算
+
+**效果**: 长任务 token 节省 30-40%
+
+---
+
+### 方案D: 缓存预热（会话开始优化）
+
+**执行时机**: 每个会话开始
+
+**步骤**:
+
+1. **加载常用上下文**
+   ```typescript
+   // 会话开始时自动加载
+   const warmupContext = [
+     'CLAUDE.md',           // 核心规则
+     'rules/core/',         // 核心规则
+     'memory/MEMORY.md',    // 持久化记忆
+     'task_plan.md',        // 当前任务计划
+   ];
+   ```
+
+2. **预计算常见操作**
+   - 加载项目结构
+   - 初始化工具链
+   - 预加载常用代码片段
+
+3. **缓存验证**
+   ```bash
+   # 会话开始时运行
+   python usage_audit.py --check-warmup
+   ```
+
+**效果**: 会话启动时间 -50%, 首次操作 token -30%
+
+---
+
+## 🎯 优先级规则
+
+### 立即应用（所有会话）
+
+```
+1. 使用 claude-patched（cc-cache-fix）
+   ↓
+2. 按需加载 context（不全量）
+   ↓
+3. 会话开始时缓存预热
+   ↓
+4. 长任务自动分割
+```
+
+### 按任务类型应用
+
+| 任务类型 | 推荐方案 | 预期节省 |
+|---------|---------|---------|
+| 简单任务 (<15分钟) | A + B | 40-50% |
+| 中等任务 (15-60分钟) | A + B + D | 50-60% |
+| 长任务 (>1小时) | A + B + C + D | 60-70% |
+| 复杂多文件 | A + B + D + 分割 | 60-70% |
+
+---
+
+## 📊 监控和验证
+
+### 缓存健康检查
+
+```bash
+# 每个会话开始时运行
+python cc-cache-fix/test_cache.py
+
+# 输出示例
+✅ Attachment persistence: PASS
+✅ Hash stability: PASS
+✅ TTL extension: PASS (1h)
+📊 Cache hit rate: 78%
+💾 Token saved: 2,340 / 3,200 (73%)
+```
+
+### 使用审计
+
+```bash
+# 周期性审计
+python cc-cache-fix/usage_audit.py
+
+# 输出示例
+Session: 2026-04-01 10:00
+├─ Total input tokens: 3,200
+├─ Cache read tokens: 2,340 (73%)
+├─ Cache creation tokens: 860 (27%)
+├─ Efficiency: 73% ✅
+└─ Recommendation: Maintain current strategy
+```
+
+### 告警阈值
+
+| 指标 | 正常 | 警告 | 严重 |
+|------|------|------|------|
+| Cache hit rate | >70% | 50-70% | <50% |
+| Token efficiency | >65% | 45-65% | <45% |
+| TTL utilization | >80% | 60-80% | <60% |
+
+---
+
+## 🔧 集成到工作流
+
+### 会话开始 Hook
+
+```bash
+# ~/.claude/hooks/session-start-cache-warmup.sh
+
+#!/bin/bash
+
+# 1. 检查 cc-cache-fix 是否安装
+if ! command -v claude-patched &> /dev/null; then
+  echo "⚠️ cc-cache-fix not installed. Install with:"
+  echo "  git clone https://github.com/Rangizingo/cc-cache-fix.git && cd cc-cache-fix && ./install.sh"
+fi
+
+# 2. 运行缓存预热
+python cc-cache-fix/test_cache.py --warmup
+
+# 3. 加载持久化记忆
+if [ -f "~/.claude/projects/e--bobo-s-coding-cache/memory/MEMORY.md" ]; then
+  echo "✅ Memory loaded"
+fi
+
+# 4. 检查 context 大小
+CONTEXT_SIZE=$(wc -c < "CLAUDE.md")
+if [ $CONTEXT_SIZE -gt 50000 ]; then
+  echo "⚠️ CLAUDE.md too large ($CONTEXT_SIZE bytes). Consider splitting."
+fi
+```
+
+### 任务执行 Hook
+
+```bash
+# ~/.claude/hooks/task-execution-cache-monitor.sh
+
+#!/bin/bash
+
+# 监控任务执行期间的缓存效率
+python cc-cache-fix/usage_audit.py --monitor --interval 5m
+```
+
+---
+
+## 📝 最佳实践清单
+
+### 每个会话
+
+- [ ] 使用 `claude-patched` 而非 `claude`
+- [ ] 会话开始时运行 `test_cache.py --warmup`
+- [ ] 加载 `memory/MEMORY.md`
+- [ ] 检查 CLAUDE.md 大小 (<50KB)
+
+### 每个任务
+
+- [ ] 预估任务时长
+- [ ] 如果 >1小时，分割成多个会话
+- [ ] 使用 `task_plan.md` 保存进度
+- [ ] 使用 `notes.md` 保存发现
+
+### 每周
+
+- [ ] 运行 `usage_audit.py` 审计
+- [ ] 检查缓存命中率趋势
+- [ ] 优化低效会话
+- [ ] 更新 CLAUDE.md（删除过期内容）
+
+### 每月
+
+- [ ] 审视 context 结构
+- [ ] 合并重复规则
+- [ ] 更新技能索引
+- [ ] 评估 token 节省效果
+
+---
+
+## 🚀 快速开始
+
+### 1分钟快速设置
+
+```bash
+# 1. 安装 cc-cache-fix
+git clone https://github.com/Rangizingo/cc-cache-fix.git
+cd cc-cache-fix
+./install.sh
+
+# 2. 验证安装
+claude-patched --version
+
+# 3. 测试缓存
+python test_cache.py
+
+# 4. 从现在开始使用 claude-patched
+alias claude=claude-patched
+```
+
+### 验证效果
+
+```bash
+# 运行两个相同的会话，对比 token 使用
+
+# 会话1（冷启动）
+claude-patched
+# 输入相同的任务
+# 记录 input tokens
+
+# 会话2（热启动）
+claude-patched
+# 输入相同的任务
+# 记录 input tokens
+
+# 对比：会话2 应该节省 40-60% tokens
+```
+
+---
+
+## ⚠️ 已知限制
+
+### cc-cache-fix 的限制
+
+- ✅ 解决 Delta 附件丢失
+- ✅ 解决 Hash 不稳定
+- ✅ 解决 TTL 过短
+- ❌ 不能解决 Prompt Cache 设计缺陷
+- ❌ 不能解决 MCP 指令重复加载
+- ❌ 不能解决跨会话缓存共享
+
+### 需要手动优化的
+
+- Context 压缩（按需加载）
+- 会话分割（长任务）
+- 缓存预热（会话开始）
+- 规则去重（定期维护）
+
+---
+
+## 📚 相关文档
+
+- `performance.md` - 模型选择和性能优化
+- `engineering-workflows.md` - 工程化工作流
+- `context-budget-analyzer` - Context 预算分析工具
+- `context-compressor` - Context 压缩工具
+
+---
+
+**版本**: v1.0
+**创建**: 2026-04-01
+**状态**: Active
+**下一步**: 集成到 performance.md 和 engineering-workflows.md