sumulige-claude 1.1.1 → 1.2.0

package/Q&A.md

@@ -1,308 +1,325 @@
-# Sumulige Claude 常见问题
+# Sumulige Claude 渐进式指南
 
-> 帮助你快速理解项目的核心设计理念
+> 从零开始，逐步理解项目的核心设计理念
 
 ---
 
-## Q1: 为什么要把 sumulige-claude 保留在项目中？
+## Level 1: 基础概念 (5 分钟)
 
-### 🔑 一句话答案
-**它不是"工具"，是"数字合伙人"**——需要跟随项目一起成长。
+### Q: sumulige-claude 是什么？
 
-### 📊 对比理解
+**一句话答案**：它是 Claude Code 的"能力扩展器"。
 
-| 普通 CLI 工具 | Sumulige Claude |
-|--------------|-----------------|
-| 全局安装，到处通用 | 嵌入项目，专属定制 |
-| 静态能力，版本固定 | 动态进化，持续学习 |
-| 扳手（用完即走） | 副驾驶（全程陪伴） |
-
-### 💡 四大设计深意
+**类比理解**：
 
 ```
-┌─────────────────────────────────────────────────────────────┐
-│  1️⃣ 共同进化                                                │
-│     Agent 技能随业务逻辑同步迭代                             │
-│     修改算法 → 同步更新 review 技能                          │
-├─────────────────────────────────────────────────────────────┤
-│  2️⃣ 上下文记忆                                               │
-│     .claude/rag/ 是 Agent 的"海马体"                        │
-│     项目架构决策 → 长期记忆沉淀                              │
-├─────────────────────────────────────────────────────────────┤
-│  3️⃣ 团队一致性                                               │
-│     工具链即代码 (Toolchain as Code)                        │
-│     git clone → pnpm install → 获得一致的 AI 环境            │
-├─────────────────────────────────────────────────────────────┤
-│  4️⃣ 构建联动                                                │
-│     修改共享类型 → 自动触发 Agent 重新构建                   │
-│     确保 AI 永不基于过时定义生成代码                         │
-└─────────────────────────────────────────────────────────────┘
+Claude Code       =  一辆基础款汽车
+sumulige-claude   =  给汽车加装：
+                      ├─ 导航系统 (Template)
+                      ├─ 自动驾驶 (Agents)
+                      └─ 第三方配件接口 (Skills)
 ```
 
----
+**核心价值**：
+1. **记忆** - 记住你的项目决策
+2. **分工** - 不同 AI 专注不同任务
+3. **复用** - 技能可以在项目间共享
 
-## Q2: 根目录 `.claude/` 和 `template/.claude/` 有什么区别？
+---
 
-### 🔑 一句话答案
-**`template/` 是"工厂"，根目录 `.claude/` 是"产品"。**
+## Level 2: 目录结构理解 (10 分钟)
 
-### � 类比理解
+### Q: 为什么要保留在项目中？
 
+**传统 CLI 工具**：
 ```
-template/.claude/          xxx/.claude/
-     │                          │
-     ▼                          ▼
-🏭 安装光盘                  💾 存档文件
-🎓 毕业证书模板              📝 你的毕业证
-🧬 DNA 模板                  🧑 具体的人
-📘 类定义 (Class)            📦 实例 (Instance)
+npm install -g tool    → 全局安装
+tool command           → 到处都能用
 ```
 
-### 🔍 详细对比
-
-| 特性 | **根目录 `.claude/`** | **template/.claude/** |
-|------|----------------------|----------------------|
-| **性质** | 实例 (Instance) | 模板 (Blueprint) |
-| **状态** | ✅ 有状态 | ❌ 无状态 |
-| **内容** | sessions/, 本地配置, 项目 RAG | commands/, skills/, thinking-routes/ |
-| **作用** | 记录"聊过什么" | 定义"能做什么" |
-| **Git** | 部分忽略 (sessions/) | 完整提交 |
-| **生命周期** | 随项目存在 | 发布即固化 |
-
-### 🔄 工作流程
-
+**sumulige-claude**：
 ```
-┌────────────────┐     smc template     ┌────────────────┐
-│                │  ─────────────────▶  │                │
-│ template/      │                      │ xxx/           │
-│   .claude/     │     复制模板         │   .claude/     │
-│   ├─commands/  │  ─────────────────▶  │   ├─commands/  │
-│   ├─skills/    │                      │   ├─skills/    │
-│   └─...        │                      │   ├─sessions/  │ ← 新增：对话记忆
-│                │                      │   ├─rag/       │ ← 新增：项目知识
-│                │                      │   └─...        │
-└────────────────┘                      └────────────────┘
-     工厂                                    产品
+npm install -g sumulige-claude    → 全局安装框架
+smc template                      → 每个项目专属配置
 ```
 
-### 💡 设计优势
+**关键区别**：
 
-| 优势 | 说明 |
-|------|------|
-| **升级解耦** | 更新 template/ → 发布新版 → 用户项目历史不丢失 |
-| **标准化** | 每个新项目自动获得最佳实践配置 |
-| **隔离性** | 项目 A 的对话记忆不会污染项目 B |
-
----
+| 特性 | 传统 CLI | sumulige-claude |
+|------|---------|-----------------|
+| 安装位置 | 全局 | 全局框架 + 项目配置 |
+| 配置方式 | 一个全局配置 | 每个项目独立配置 |
+| 记忆能力 | 无 | 项目级记忆 (RAG) |
+| 团队协作 | 每人各自配置 | 配置随项目共享 |
 
-## 总结：一张图看懂架构
+**为什么这样设计？**
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
-│                    Sumulige Claude 架构                      │
+│  场景：你有一个团队，大家在同一个项目上工作                   │
 ├─────────────────────────────────────────────────────────────┤
 │                                                             │
-│  ┌──────────────────┐          ┌──────────────────┐        │
-│  │  sumulige-claude │          │   你的项目        │        │
-│  │  (npm 全局安装)   │          │   (xxx/)         │        │
-│  ├──────────────────┤          ├──────────────────┤        │
-│  │  cli.js          │──smc───▶│  .claude/         │        │
-│  │  template/       │ template │   ├─ commands/   │        │
-│  │   └─.claude/     │──────────│   ├─ skills/     │        │
-│  │     ├─commands/  │  复制    │   ├─ sessions/   │ 记忆   │
-│  │     ├─skills/    │          │   ├─ rag/        │ 知识   │
-│  │     └─templates/ │          │   └─ settings    │ 配置   │
-│  └──────────────────┘          └──────────────────┘        │
-│         能力定义                      运行实例              │
-│        (无状态)                      (有状态)              │
+│  传统方式：                                                  │
+│  ├─ 每个人自己配置 Claude                                   │
+│  ├─ 张三用 Opus，李四用 Sonnet                              │
+│  ├─ 王五知道项目架构，赵六不知道                             │
+│  └─ 结果：代码风格不一致，决策不统一                         │
+│                                                             │
+│  sumulige-claude 方式：                                      │
+│  ├─ git clone 项目                                          │
+│  ├─ smc sync 获取统一配置                                   │
+│  ├─ 所有人使用相同的 Agent 定义                              │
+│  └─ RAG 系统让所有人了解项目历史                            │
 │                                                             │
 └─────────────────────────────────────────────────────────────┘
 ```
 
 ---
 
-## Q3: `smc template` 和 `smc sync` 有什么区别？
+## Level 3: 两个目录的区别 (15 分钟)
 
-### 🔑 一句话答案
-**`template` 是"全屋装修"，`sync` 是"添置物品"。**
+### Q: `.claude/` 和 `template/.claude/` 有什么不同？
 
-### 📊 对比理解
+**最简单的理解**：
 
-| 命令 | 行为 | 用途 | 风险 |
-|------|------|------|------|
-| `smc template` | **完整覆盖** | 新项目初始化 | ⚠️ 会覆盖已有文件 |
-| `smc sync` | **增量同步** | 现有项目更新 | ✅ 只补缺少的 |
+```
+template/.claude/   =  工厂 (生产配置)
+.claude/            =  家 (你实际使用的配置)
+```
 
-### 🏠 类比说明
+**类比**：
 
 ```
-smc template                    smc sync
-────────────                    ────────
+template/.claude/              你的项目 .claude/
+     │                              │
+     ▼                              ▼
+🏭 工厂                        🏠 你的家
+├─ 蓝图                        ├─ 实际建筑
+├─ 生产线                      ├─ 家具物品
+└─ 模板                        └─ 个人物品
+
+(无状态，不可变)              (有状态，可变化)
+```
 
-🏗️ 新房装修                      🛋️ 添置家具
+**详细对比**：
 
-空房子 ──→ 精装房                已住的房子 ──→ 补个沙发
+| 维度 | `template/.claude/` | 项目 `.claude/` |
+|------|---------------------|-----------------|
+| **性质** | 模板 | 实例 |
+| **状态** | 只读 | 可写 |
+| **内容** | commands/, skills/, hooks/ | + sessions/, rag/ |
+| **Git 追踪** | 完整提交 | sessions/ 忽略 |
+| **更新方式** | npm update | smc sync |
 
-全屋定制                         只买缺的
-（窗帘+地板+沙发）               （只买沙发）
+**工作流程**：
 
-覆盖原有装修                     不动已有物品
 ```
+┌──────────────────────┐
+│  template/.claude/   │  npm 包的一部分
+│  (能力定义)           │  定义"能做什么"
+└──────────┬───────────┘
+           │ smc template
+           ▼
+┌──────────────────────┐
+│  项目/.claude/       │  项目的一部分
+│  (运行状态)           │  记录"做过什么"
+│  ├─ commands/        │  (来自模板)
+│  ├─ skills/          │  (来自模板)
+│  ├─ sessions/        │  (新增：对话记录)
+│  └─ rag/             │  (新增：项目知识)
+└──────────────────────┘
+```
+
+---
 
-### 🔄 使用流程
+## Level 4: 命令选择 (20 分钟)
+
+### Q: `smc template` vs `smc sync`？
+
+**决策树**：
 
-**场景 A：启动新项目**
-```bash
-mkdir my-new-project
-cd my-new-project
-smc template    # ✅ 一次性配置好所有 AI 能力
 ```
+你的项目
+    │
+    ├─ 是空的？
+    │   └─ 是 → smc template
+    │          (全屋装修)
+    │
+    └─ 已有文件？
+        └─ 是 → smc sync
+               (添置家具)
+```
+
+**详细对比**：
+
+| 操作 | `smc template` | `smc sync` |
+|------|----------------|------------|
+| **用途** | 新项目初始化 | 现有项目更新 |
+| **行为** | 完整覆盖 | 增量同步 |
+| **风险** | 会覆盖已有文件 | 只补缺失的 |
+| **sessions/** | 创建空目录 | 完整保留 |
+
+**安全选项** (v1.1.0+)：
 
-**场景 B：已有项目想用 sumulige-claude**
 ```bash
-cd existing-project
-smc sync        # ✅ 增量添加，不覆盖已有配置
+smc template        # 默认：覆盖前备份
+smc template --safe # 跳过已存在的文件
+smc template --force# 强制覆盖，不备份
 ```
 
-### 📋 命令效果对比
+---
+
+## Level 5: 更新机制 (25 分钟)
 
-| 操作 | smc template | smc sync |
-|------|--------------|----------|
-| `.claude/` 目录 | ✅ 创建/覆盖 | ✅ 补充缺失 |
-| `CLAUDE.md` | ⚠️ 覆盖 | ✅ 保留已有 |
-| `hooks/*` | ⚠️ 覆盖 | ✅ 保留已有 |
-| `commands/*` | ⚠️ 覆盖 | ✅ 保留已有 |
-| `sessions/` | ✅ 新建空目录 | ✅ 完整保留 |
+### Q: 如何更新到新版本？
 
-### 💡 最佳实践
+**三层结构**：
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
-│  判断流程                                                    │
-├─────────────────────────────────────────────────────────────┤
-│                                                             │
-│  项目是空的？                                               │
-│       │                                                     │
-│       ├─ 是 → smc template                                 │
-│       │        (全屋装修)                                   │
-│       │                                                     │
-│       └─ 否 → smc sync                                     │
-│                (添置物品)                                   │
-│                                                             │
+│  全局层 (~/.claude/)      →  工具箱                         │
+│  项目层 (./.claude/)      →  工作台                         │
+│  代码层 (node_modules/)   →  零件                           │
 └─────────────────────────────────────────────────────────────┘
 ```
 
-### ⚠️ 注意事项
-
-`smc template` 会**覆盖**以下关键文件：
-- `.claude/CLAUDE.md` - 项目配置
-- `.claude/hooks/*` - 钩子脚本
-- `.claude/commands/*` - 命令定义
-
-**v1.1.0 新增安全选项**：
-- `smc template --safe`   - 跳过已存在的文件（不覆盖）
-- `smc template --force`  - 强制覆盖（不备份）
-- `smc template` (默认)   - 覆盖前自动备份到 `.claude/backup/`
-
-### 🛡️ 安全机制
-
-默认情况下，`smc template` 会自动备份被覆盖的文件：
+**更新流程**：
 
 ```bash
-smc template
-# 会创建备份文件：.claude/backup/CLAUDE.2026-01-15.bak
-```
+# 1️⃣ 更新全局包 (新零件)
+npm update -g sumulige-claude
 
-如果你不想要任何备份（确定要覆盖），使用 `--force`：
-```bash
-smc template --force  # 不备份，直接覆盖
+# 2️⃣ 同步到项目 (组装到工作台)
+cd your-project
+smc sync
 ```
 
-如果你想完全保留现有文件，使用 `--safe`：
-```bash
-smc template --safe  # 只添加缺失的文件
+**为什么需要两步？**
+
+```
+npm update                    smc sync
+     │                            │
+     ▼                            ▼
+┌─────────────────┐      ┌─────────────────┐
+│  更新工具箱      │      │  更新工作台      │
+│  ├─ 新的工具     │      │  ├─ 新的命令    │
+│  ├─ 新的模板     │      │  ├─ 新的技能    │
+│  └─ 新的能力     │      │  └─ 新的配置    │
+│                 │      │                 │
+│  但你的项目      │      │  把新能力        │
+│  还没用到       │      │  应用到项目      │
+└─────────────────┘      └─────────────────┘
 ```
 
 ---
 
-## Q4: sumulige-claude 发布新版本后如何更新？
-
-### 🔑 一句话答案
-**更新全局包 → 同步到项目**
+## Level 6: 深入架构 (30 分钟)
 
-### 📦 更新流程
-
-```bash
-# 1️⃣ 检查当前版本
-smc --version
+### Q: 整个系统是如何工作的？
 
-# 2️⃣ 更新全局包
-npm update -g sumulige-claude
+**数据流图**：
 
-# 3️⃣ 同步到项目（进入你的项目目录）
-cd your-project
-smc sync          # 增量同步新能力
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      用户输入                                │
+│                   "帮我实现一个 API"                         │
+└─────────────────────────────┬───────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    Conductor Agent                          │
+│  (理解需求，分解任务)                                         │
+│  ├─ 查询 RAG：了解项目架构                                    │
+│  ├─ 查询 Sessions：了解历史决策                               │
+│  └─ 生成任务计划                                             │
+└─────────────────────────────┬───────────────────────────────┘
+                              │
+              ┌───────────────┼───────────────┐
+              ▼               ▼               ▼
+    ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
+    │  Architect  │ │   Builder   │ │  Reviewer   │
+    │  设计架构   │ →  实现代码   │ →  审查代码   │
+    └─────────────┘ └─────────────┘ └─────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    Librarian Agent                          │
+│  (整理文档，更新知识库)                                       │
+│  ├─ 更新 RAG：新架构决策                                      │
+│  └─ 更新 Sessions：对话记录                                   │
+└─────────────────────────────────────────────────────────────┘
 ```
 
-### 🔄 管理逻辑差异
-
-| 维度 | 全局 `~/.claude/` | 项目 `./.claude/` |
-|------|-------------------|-------------------|
-| **作用域** | 用户级 | 项目级 |
-| **初始化** | `smc init` | `smc template` / `smc sync` |
-| **更新时机** | npm update 后 | 运行 smc sync |
-| **内容性质** | 能力定义 (能做什么) | 运行状态 (做过什么) |
+**记忆系统**：
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
-│  一句话区别                                                  │
+│  ThinkingLens (对话记忆)                                     │
+│  ├─ 记录每次对话的完整上下文                                  │
+│  ├─ 可搜索历史对话                                           │
+│  └─ 自动同步到项目                                           │
 ├─────────────────────────────────────────────────────────────┤
-│                                                             │
-│  全局 = "工具箱"    → 定义有什么工具可用                     │
-│  项目 = "工作台"    → 记录用工具做了什么                     │
-│                                                             │
-│  init  = "买工具箱"  → 一次购买，终身使用                    │
-│  template = "摆工具"  → 每个项目摆一次                       │
-│  sync   = "补工具"   → 发现缺什么补什么                      │
-│                                                             │
+│  RAG System (项目知识)                                       │
+│  ├─ 存储架构决策                                             │
+│  ├─ 存储代码风格约定                                         │
+│  └─ Agent 可以查询获取上下文                                  │
 └─────────────────────────────────────────────────────────────┘
 ```
 
-### 🔍 版本检查
+**质量门禁**：
+
+```
+git commit
+     │
+     ▼
+┌─────────────────────────────────────────────────────────────┐
+│  pre-commit hook                                            │
+│  ├─ 运行质量检查                                             │
+│  ├─ 检查代码行数                                             │
+│  ├─ 检查文件大小                                             │
+│  └─ 检查代码风格                                             │
+└─────────────────────────────┬───────────────────────────────┘
+                              │
+                    ┌─────────┴─────────┐
+                    ▼                   ▼
+              通过 ✅              失败 ❌
+                    │                   │
+                    ▼                   ▼
+              允许提交            阻止提交
+```
 
-sumulige-claude 采用**惰性检查**策略：
+---
 
-| 时机 | 检查方式 | 说明 |
-|------|---------|------|
-| `smc --version` | 主动检查 | 用户主动触发，零性能开销 |
-| `smc sync` | 主动检查 | 同步时已联网，无额外开销 |
-| 其他命令 | 不检查 | 不影响正常使用 |
+## 快速参考
 
-### 📋 发布端操作（作者）
+### 常用命令速查
 
 ```bash
-# 1️⃣ 更新版本号
-npm version patch  # 1.1.0 → 1.1.1 (bug fix)
-npm version minor  # 1.1.0 → 1.2.0 (新功能)
+# 初始化
+smc init              # 全局配置初始化
+smc template          # 新项目部署
+smc sync              # 增量同步
 
-# 2️⃣ 生成 changelog
-npm run release
+# 技能管理
+smc marketplace:list  # 浏览技能市场
+smc skill:list        # 查看已安装技能
 
-# 3️⃣ 推送并发布
-git push --follow-tags
-npm publish
-```
+# 质量检查
+smc qg:check          # 运行质量检查
+smc config:validate   # 验证配置文件
 
-### ✨ 自动化特性
+# 项目规划
+smc kickoff           # 启动项目规划
+```
 
-`postinstall` 钩子确保全局配置始终最新：
+### 配置文件位置
 
-```json
-"postinstall": "node cli.js init"
 ```
-
-运行 `npm update -g sumulige-claude` 时会自动执行 `smc init`。
+~/.claude/config.json           # 全局配置
+./.claude/settings.json         # 项目配置
+./.claude/quality-gate.json     # 质量门禁配置
+```
 
 ---
 
-*更多问题？查看 [README.md](./README.md)*
+*更多细节查看 [README.md](./README.md)*