使用指南.txt

╔══════════════════════════════════════════════════════════════╗
║              Gangge Code — 使用快速指南                      ║
║              三种模式操作手册                                 ║
╚══════════════════════════════════════════════════════════════╝

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
一、三种模式选择
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ┌──────────┬──────────────────┬──────────────────────┐
  │  模式     │  启动命令          │  适合场景              │
  ├──────────┼──────────────────┼──────────────────────┤
  │  CLI     │ gangge "任务"    │ 快速单次、管道、脚本    │
  │  REPL    │ gangge            │ 终端交互式对话          │
  │  TUI     │ gangge (无参数)   │ 终端有样式界面          │
  │  桌面    │ python desktop/app.py │ 完整 IDE 体验       │
  └──────────┴──────────────────┴──────────────────────┘


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
二、CLI 模式（Claude Code 风格）
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  【启动】

    gangge                                  # 交互式 REPL
    gangge "创建 FastAPI 项目"              # 单次执行
    echo "分析这个日志" | gangge            # 管道输入

  【常用参数】

    gangge -w /path/to/project "任务"       # 指定工作目录
    gangge -p deepseek "任务"               # 指定 Provider
    gangge -p ollama -m llama3.1 "任务"     # 指定模型

  【交互式 REPL 内部命令】

    > 帮我写一个 Python 脚本                # 直接输入任务
    exit   或 quit   或 q                   # 退出 REPL
    Ctrl+C                                 # 取消当前任务
    Ctrl+D                                 # 退出（Windows）

  【管道组合示例】

    # 在 CI/CD 中使用
    npm test 2>&1 | gangge "分析测试失败原因并修复"

    # 串联 grep
    grep "FIXME" src/ -r | gangge "帮我修复这些 FIXME"

    # 从文件读取
    cat todo.txt | gangge "按列表依次实现"

  【注意事项】
    - CLI 模式下权限自动允许（不弹确认）
    - 每次执行完成自动显示 Token 消耗和费用
    - 需先在 .env 配置 API Key


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
三、TUI 模式（Textual 终端界面）
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  【启动】

    gangge                                  # 启动 TUI 界面
    gangge -v                               # 调试模式（显示详细日志）

  【界面布局】

    ┌──────────────────────────────────────┐
    │ Header: 模型 / 工作目录               │
    ├──────────────────────────────────────┤
    │                                      │
    │  对话区域（RichLog）                  │
    │  - LLM 回复用青色显示                 │
    │  - 工具调用用 ✓/✗ 显示               │
    │  - 用户输入用绿色 > 前缀              │
    │                                      │
    ├──────────────────────────────────────┤
    │ Tab: 对话 | 工具日志                  │
    ├──────────────────────────────────────┤
    │ > 输入框...                           │
    ├──────────────────────────────────────┤
    │ Footer: 快捷键提示                    │
    └──────────────────────────────────────┘

  【快捷键】

    Ctrl+P      切换规划模式
    Ctrl+N      新建会话
    Ctrl+C      取消当前操作
    Ctrl+Q      退出
    Y           权限确认（允许）
    N           权限确认（拒绝）
    A           权限确认（总是允许）

  【注意事项】
    - 依赖 textual 库
    - 需要终端支持（Windows Terminal 或 PowerShell 7+）
    - SSH 远程连接时可能无法正常显示


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
四、桌面应用（PyQt6 GUI）
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  【启动】

    python desktop/app.py                   # 启动桌面应用
    desktop/run.bat                         # Windows 双击启动

  【界面布局】

    ┌──────────────────────────────────────────────────────────┐
    │ [🔄新建] [⏹停止] [🗑清空]  Provider:[DeepSeek▼]  [⚙设置]│
    ├────────────┬─────────────────────────────────────────────┤
    │ 📋会话 │ 📂文件 │                                         │
    │            │          │  💬 对话 (主输出区)                 │
    │ → 项目骨架   │ src/     │                                   │
    │   todos CRUD│ main.py  │                                   │
    │            │          │                                   │
    │            │          ├───────────────────────────────────┤
    │            │          │ 🔧工具调用  │  📝文件变更          │
    │            │          │  (底栏，带 unified diff 预览)      │
    ├────────────┴──────────┴───────────────────────────────────┤
    │ 📝 输入任务... (Ctrl+Enter 执行)         [📋批量]  [▶ 执行]│
    ├──────────────────────────────────────────────────────────┤
    │ 状态栏                                                    │
    └──────────────────────────────────────────────────────────┘

  【快捷键】

    Ctrl+Enter     执行任务
    Ctrl+N         新建会话
    Ctrl+L         清空输出
    Ctrl+O         选择工作目录
    Ctrl+Q         退出

  【操作步骤】

    第一次使用：
      1. 点击工具栏 ⚙ 设置
      2. 选择 Provider（如 DeepSeek）
      3. 填入 API Key
      4. 选择工作目录（要点右下角"完成"保存）
      5. 在底部输入框输入任务，点击 ▶ 执行

    基本流程：
      1. 输入任务 → 点"执行"或 Ctrl+Enter
      2. 看左边栏了解当前进度（会话/文件）
      3. 看底栏"工具调用"查看 LLM 干了什么
      4. 看"文件变更"查看具体改了哪些代码行
      5. 任务完成后状态栏显示 Token 和费用

    高级功能：
      - 批量任务：多行输入，点"📋 批量"
      - 规划模式：⚙ 设置 → 勾选"规划模式"
      - 自动 Git 提交：⚙ 设置 → 勾选"自动 Git 提交"
      - 切换会话：点击左侧会话列表
      - 项目管理：在工作目录放 .ganggerules 文件

  【设置说明（⚙ 设置界面）】

    LLM 配置：
      API Key    — 你的 API 密钥
      Model      — 模型名称
      Base URL   — 自定义 API 地址（Ollama 需要）

    高级设置：
      最大轮数          — 每任务最多工具调用次数（默认 30）
      自动允许安全操作   — 安全命令不弹确认
      自动注入项目上下文 — 自动读 ARCH.md + 目录结构
      自动触发测试验证   — 改文件后自动让 LLM 跑测试
      自动 Git 提交      — 任务完成自动 git add + commit
      规划模式           — LLM 先出计划，批准后再执行


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
五、常用任务示例
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  # 项目初始化
  "创建一个 FastAPI 项目，包含 models、routers、schemas"

  # 代码修改
  "在 src/routers/todos.py 添加一个 delete 路由"
  "把 main.py 里的 print 全部改成 logger.info"

  # 代码审查
  "审查 src/ 目录下的代码，找出潜在 bug 和安全问题"

  # 测试
  "为 src/routers/todos.py 写 pytest 测试"
  "运行测试并修复失败"

  # 重构
  "把 models.py 拆分成多个文件，按功能归类"
  "把通用的数据库操作提取到 repositories/ 目录"

  # 文档
  "为 src/ 下所有函数生成 docstring"
  "更新 README.md，反映最新的 API 变化"

  # 批量任务（桌面端多行输入）
  创建项目骨架
  实现用户认证模块
  实现 Todo CRUD
  写测试并全部通过


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
六. 配置文件说明
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  .env — API 配置（CLI 和桌面共享）

    LLM_PROVIDER=deepseek
    DEEPSEEK_API_KEY=sk-xxx
    DEEPSEEK_MODEL=deepseek-chat
    MAX_TOKENS=8192

  .ganggerules — 项目规则（放在项目根目录）

    # 编码规范
    - 所有代码注释用中文
    - 每个新函数必须写 pytest 测试

  .gangge/progress.md — Memory Bank（自动维护）

    由 LLM 自动更新，记录项目进度和变更日志。
    下次启动时自动读入，LLM 知道之前做了什么。


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
七、常见问题
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Q: 桌面端启动报 "no module named PyQt6"？
  A: pip install PyQt6

  Q: CLI 模式 "gangge" 提示找不到命令？
  A: pip install -e .  或者用 python -m gangge.cli

  Q: 任务执行到一半想取消？
  A: 桌面点"⏹ 停止"，CLI 按 Ctrl+C

  Q: LLM 改坏了代码怎么回滚？
  A: 如果开启了"自动 Git 提交"，执行 git log 查看提交历史，
     git revert <commit_hash> 回滚。如果没有 Git，
     可以从 SQLite 会话记录找 before_content 手动恢复。

  Q: 桌面端 API Key 每次重启都要输？
  A: 设置完成后要点右下角"保存设置"，会自动写回 .env 文件。

  Q: token 消耗太大怎么办？
  A: 在设置里降低"最大轮数"或关闭"自动注入项目上下文"。
     也可以切换到 DeepSeek（便宜）或 Ollama（免费）。