fuxi-cli

v1.0.0

Published

4 months ago

Fuxi CLI - Enhanced AI command-line tool with custom models, agents system, and workflow orchestration

0High
0Medium
0Low

mj-cjm

ai cli gemini agent workflow qwen deepseek fuxi

📖 项目简介

伏羲 CLI 是基于 Google Gemini CLI 开发的增强版本，专为国内开发者优化。在保留原有强大功能的基础上，提供了丰富的核心扩展功能：

🎯 核心扩展功能

| 功能 | 说明 | 状态 | |------|------|------| | 🤖 自定义模型支持 | 零代码配置接入通义千问、DeepSeek、本地模型等 | ✅ 已完成 | | 🎭 Agents 智能体系统 | 创建专业化 AI 助手，独立上下文和工具权限 | ✅ 已完成 | | 🧭 智能路由与移交 | 自动选择最佳 Agent，支持 Agent 间协作 | ✅ 已完成 | | 🔄 Workflow 工作流 | 多 Agent 编排，支持顺序和并行执行 | ✅ 已完成 | | 📋 Plan+Todo 模式 | 先规划后执行，结构化任务分解和管理 | ✅ 已完成 | | 📐 Spec 规格驱动开发 | Constitution → Spec → Plan → Tasks → Execute 完整链路 | ✅ 已完成 |

⚡ 继承的强大功能

🧠 超大上下文窗口：支持 1M token 上下文
🔧 丰富的内置工具：文件操作、Shell 命令、Git 集成
🔌 MCP 协议支持：扩展外部服务集成
💻 终端优先设计：为命令行用户深度优化
🛡️ 开源：Apache 2.0 许可证

🚀 快速开始

安装

方式一：NPM 全局安装（推荐）

# 全局安装
npm install -g tiangong-cli

# 启动
tiangong-cli

方式二：源码安装

# 克隆仓库
git clone https://github.com/chenjiamin/fuxi-cli.git
cd fuxi-cli

# 安装依赖
npm install

# 构建项目
npm run build

# 启动 CLI
npm start

方式三：Docker 开发环境

部署模式说明：

文件映射模式（默认）：代码通过 volume 映射到容器，适合开发调试
完整打包模式：代码和依赖都打包到镜像，适合生产部署

文件映射模式（推荐用于开发）

说明：代码通过 volume 映射到容器内，编译产物输出到本地。修改代码后无需重建镜像。

# 克隆仓库
git clone https://github.com/chenjiamin/fuxi-cli.git
cd fuxi-cli

# 构建开发镜像（只包含编译工具，不包含代码）
docker build -f Dockerfile.dev -t fuxi-cli-dev .

# 删除本地 node_modules（如果存在，避免平台不匹配和符号链接冲突）
rm -rf node_modules

# 构建项目（代码通过 -v $(pwd):/workspace 映射到容器内）
# 编译产物会直接输出到本地的 bundle/ 目录
docker run --rm -v $(pwd):/workspace -w /workspace fuxi-cli-dev npm run build

# 编译产物在本地 bundle/ 目录，可直接使用
node bundle/fuxi-cli.js

特点：

代码在本地，通过 -v $(pwd):/workspace 映射到容器
修改代码后，重新运行构建命令即可，无需重建镜像
编译产物在本地 bundle/ 目录

完整打包模式（适合生产部署）

说明：将代码和所有依赖都打包到镜像中，生成自包含镜像，无需挂载代码目录。

# 构建生产镜像（代码和依赖都打包到镜像中）
docker build -f Dockerfile.prod -t fuxi-cli:latest .


# 运行镜像（无需挂载代码目录，镜像已包含所有内容）
docker run -it --rm fuxi-cli:latest

# 挂载配置文件目录（如果需要读取 ~/.gemini/config.json）
docker run -it --rm \
  -v ~/.gemini:/home/node/.gemini \
  fuxi-cli:latest

# 或非交互式运行
docker run --rm fuxi-cli:latest "你的问题"

特点：

镜像自包含，代码和依赖都在镜像中
无需挂载代码目录，可直接运行
适合生产部署和镜像分发
修改代码后需要重新构建镜像

详细文档请参考：Docker 开发环境指南

系统要求

源码安装方式：

Node.js 20.0.0 或更高版本
macOS、Linux 或 Windows

Docker 开发环境：

Docker 20.10 或更高版本
macOS、Linux 或 Windows（需要 Docker Desktop）

🎯 核心功能

1️⃣ 自定义模型支持

通过简单的配置文件即可接入任意 OpenAI 兼容的 AI 模型，无需修改代码。

支持的模型类型

✅ 国内大模型：通义千问、DeepSeek、智谱 GLM、文心一言
✅ 本地模型：Ollama、LM Studio
✅ 企业自部署模型
✅ 任何 OpenAI 兼容 API

快速配置示例

步骤 1：配置模型（`~/.gemini/config.json`）

通义千问 (Qwen)

{
  "useModelRouter": true,                    // 必须：启用自定义模型支持
  "defaultModel": "qwen3-coder-flash",       // 推荐：默认使用的模型
  "models": {
    "qwen3-coder-flash": {
      "provider": "openai",                  // 必须：使用 OpenAI 兼容适配器
      "model": "qwen3-coder-flash",         // 必须：API 调用的模型名
      "apiKey": "sk-your-api-key",          // 必须：通义千问 API Key
      "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",  // 必须：通义千问 API 地址
      "metadata": {
        "providerName": "qwen",             // 推荐：身份标识（AI 会说"我是通义千问"）
        "displayName": "通义千问"            // 可选：UI 显示名称
      },
      "capabilities": {
        "maxOutputTokens": 8192,            // 推荐：最大输出 token 数
        "supportsFunctionCalling": true,   // 重要：Qwen 支持工具调用（必须 true）
        "supportsMultimodal": true         // 重要：Qwen 支持数组格式（必须 true）
      }
    }
  }
}

DeepSeek

{
  "models": {
    "deepseek-coder": {
      "provider": "openai",
      "model": "deepseek-coder",
      "apiKey": "sk-your-api-key",
      "baseUrl": "https://api.deepseek.com",
      "metadata": {
        "providerName": "deepseek",
        "displayName": "DeepSeek"
      },
      "capabilities": {
        "maxOutputTokens": 4096,
        "supportsFunctionCalling": false,  // 重要：DeepSeek 不支持（必须 false）
        "supportsMultimodal": false        // 重要：DeepSeek 不支持（必须 false）
      }
    }
  }
}

⚠️ 重要：

通义千问：supportsFunctionCalling 和 supportsMultimodal 必须为 true
DeepSeek：supportsFunctionCalling 和 supportsMultimodal 必须为 false

步骤 2：配置系统设置（`~/.gemini/settings.json`）

{
  "experimental": {
    "useModelRouter": true                   // 必须：与 config.json 配合启用自定义模型
  },
  "security": {
    "auth": {
      "selectedType": "custom-model"         // 推荐：使用自定义模型认证
    }
  },
  "model": {
    "name": "qwen3-coder-flash"             // 可选：当前使用的模型
  }
}

步骤 3：使用自定义模型

# 切换模型
/model use qwen3-coder-flash

# 查看当前模型
/model info

# 列出所有模型
/model list

📚 详细文档：添加新模型指南 | 模型系统设计 | 模型系统概述

2️⃣ Agents 智能体系统

创建专业化的 AI 智能体，每个 Agent 具有独立的上下文、工具权限和行为特征。

什么是 Agent？

Agent 是一个专门化的 AI 助手，具有：

🔄 灵活的上下文模式：
- isolated：独立上下文，对话历史与主会话隔离
- shared：共享上下文，可以访问主会话的对话历史
🛠️ 工具控制：精确控制可用工具（白名单/黑名单）
📝 自定义提示词：为特定任务定制行为
🔌 MCP 集成：连接外部服务
🧭 智能路由：通过触发器自动匹配用户意图

快速创建 Agent

方式一：交互式创建（推荐） ⭐

# 启动交互式创建向导
/agents create -i

# 按照提示依次输入：
# 1. Agent 名称（如：code_review）
# 2. 显示标题（如：代码审查助手）
# 3. 描述（可选）
# 4. 作用域（project/global）
# 5. 选择模型
# 6. 上下文模式（isolated/shared）
# 7. 创建方式（AI 生成/手动模板）
# 8. Agent 用途描述（AI 会自动生成内容）
# 9. 工具权限配置

方式二：命令行快速创建

# 创建代码审查 Agent
/agents create code-review \
  --title "代码审查助手" \
  --model qwen-coder-plus

# 使用 AI 生成内容
/agents create debug-analyzer \
  --title "调试专家" \
  --ai \
  --purpose "系统性分析代码错误，提供详细的调试步骤和根因分析" \
  --model deepseek-coder

创建完成后的提示

✅ Agent "code_review" Created Successfully!

📁 File Location:
   .gemini/agents/code_review.md

📝 Next Steps:
   1. Review: cat .gemini/agents/code_review.md
   2. Edit: vim .gemini/agents/code_review.md
   3. Validate: /agents validate code_review
   4. Info: /agents info code_review
   5. List: /agents list

Agent 配置示例

查看生成的 .gemini/agents/code_review.md：

---
kind: agent
name: code_review
title: Code_review
description: code review
model: deepseek-coder
scope: project
version: 1.0.0
contextMode: shared
tools:
  allow: ["read_file","read_many_files","ls","glob","grep","rg","web_fetch","web_search"]
  deny: []
mcp:
  servers: []
handoffs:
  - to: code_imple
    when: manual
    description: "当用户需要实现代码、修复bug或编写功能时，移交给 code_imple agent"
    include_context: true
---

# Role

⚠️ **你是代码审查专家 - 只负责审查代码质量，不实现代码**

## 关键规则 - 首先判断任务类型

在做任何事情之前，先判断任务类型：

1. **如果用户要求实现/修复/编写代码**（关键词：实现、修复、编写、开发、写代码、implement、fix、write、develop）：
   - ❌ 不要读取任何文件
   - ❌ 不要进行任何分析
   - ✅ 立即使用 `transfer_to_code_imple` 工具移交任务

2. **如果用户要求审查/检查/分析代码**（关键词：审查、检查、分析、review、check、analyze）：
   - ✅ 读取必要的文件
   - ✅ 分析代码质量
   - ✅ 提供审查反馈

字段说明：

contextMode: shared（共享主会话上下文）或 isolated（独立上下文）
tools.allow: 允许使用的工具列表（JSON 数组格式）
tools.deny: 禁止使用的工具列表
scope: project（项目级）或 global（全局）
mcp.servers: MCP 服务器列表（如 ["github", "slack"]）

使用 Agent

# 运行 Agent
/agents run code-review 帮我审查 src/main.ts

# 或使用 @ 语法
@code-review 检查这个文件的代码质量

# 列出所有 Agent
/agents list

# 查看 Agent 详情
/agents info code-review

📚 详细文档：Agents 快速开始 | Agents 系统设计 | 实现细节 | 命令参考

3️⃣ 智能路由与移交

根据用户输入自动选择最合适的 Agent，并支持 Agent 之间的智能协作。

智能路由

系统会根据关键词、正则表达式或 AI 推理，自动选择最适合的 Agent。

配置路由触发器

编辑 Agent 文件，添加 triggers：

---
kind: agent
name: code-review
title: 代码审查助手
triggers:
  keywords:
    - 审查
    - review
    - 检查
    - 代码质量
  patterns:
    - "检查.*代码"
    - "review.*code"
  priority: 80
---

三种路由策略

| 策略 | 性能 | 准确度 | 适用场景 | |------|------|--------|----------| | rule | 极快 (< 10ms) | 中等 | 明确的关键词触发 | | llm | 较慢 (1-3s) | 高 | 复杂语义理解 | | hybrid | 快速 (10-100ms) | 高 | 推荐默认使用 ⭐ |

启用和测试路由

# 启用智能路由
/agents config enable
/agents config set strategy hybrid

# 测试路由（不执行）
/agents route "帮我审查这段代码"

# 输出示例：
# ✅ Routing Result
# Selected Agent: code-review
# Confidence: 92%
# Matched Keywords: 审查

# 一步完成路由和执行
/agents route "帮我审查这段代码" --execute

Agent 移交

Agent 可以在执行过程中将任务移交给其他专业 Agent。

配置移交关系

---
kind: agent
name: code_review
title: 代码审查助手
handoffs:
  - to: code_imple
    when: manual
    description: "当用户需要实现代码、修复bug或编写功能时，移交给 code_imple agent"
    include_context: true
---

移交场景说明

code_review agent 专注于代码审查，当检测到用户实际想要实现代码而非审查代码时，会自动移交：

# 场景1：用户误用 code_review agent 请求实现功能
> @code_review 帮我实现一个登录功能

# Agent 行为：
# [code_review]: 检测到这是代码实现任务，正在移交给 code_imple agent...
# [HandoffManager] Initiating handoff: code_review -> code_imple
# [code_imple]: 好的，我来帮你实现登录功能...

# 场景2：审查后发现需要修复
> @code_review 检查 auth.ts 的代码质量

# [code_review]: 发现以下问题：
# - 🔴 SQL 注入风险（必须修复）
# - 🟡 密码强度检查不足
# 
# 需要我移交给 code_imple agent 进行修复吗？

安全机制

✅ 循环检测：自动防止 A → B → A 循环移交
✅ 深度限制：最大移交深度 5 层
✅ 追踪机制：每个移交链有唯一 correlation_id

📚 详细文档：智能路由系统 | Agent 移交系统 | P2 功能总结

4️⃣ Workflow 工作流 ✅

多 Agent 编排系统，支持预定义复杂的执行流程，显著提升开发效率。

核心特性

📋 YAML 配置：使用 YAML 文件定义工作流
🔗 顺序执行：按步骤依次执行多个 Agent 任务
⚡ 并行执行：多个 Agent 同时运行，时间减半
🎯 条件执行：支持 when 表达式控制执行逻辑
🔄 错误处理：continue/stop/retry 策略，min_success 配置
📊 模板变量：步骤间数据传递和嵌套引用
🏷️ 智能路由：支持触发器自动匹配

顺序工作流示例

# .gemini/workflows/code-quality-pipeline.yaml
---
kind: workflow
name: code-quality-pipeline
title: 代码质量流水线
description: 完整的代码质量检查流程

triggers:
  keywords: [质量检查, quality check, 完整审查]
  priority: 90

steps:
  - id: review
    agent: code_review
    description: "审查代码质量"
    input: "${workflow.input}"

  - id: fix
    agent: code_imple
    description: "修复发现的问题"
    when: "${review.data.issues_found} > 0"
    input: "修复以下问题：${review.output}"

  - id: test
    agent: test_writer
    description: "编写测试用例"
    input: "为修复后的代码编写测试"

error_handling:
  on_error: continue
  max_retries: 2

timeout: 600000  # 10 分钟
---

并行工作流示例 ⭐

# .gemini/workflows/parallel-review.yaml
---
kind: workflow
name: parallel-review
title: 并行代码审查
description: 两个审查员并行审查，专业汇总，统一修复

steps:
  # Step 1: 并行审查（同时执行，时间减半）
  - type: parallel
    id: dual_review
    description: "两个审查员并行审查代码"
    parallel:
      - id: reviewer_a
        agent: code_review
        description: "代码质量审查"
        input: "审查文件：${workflow.input}"
        timeout: 90000

      - id: reviewer_b
        agent: code_review_pro
        description: "安全审查"
        input: "安全审查：${workflow.input}"
        timeout: 90000

    timeout: 120000
    error_handling:
      on_error: continue
      min_success: 1  # 至少一个成功即可

  # Step 2: 汇总审查结果
  - id: aggregate_reviews
    agent: review_aggregator
    description: "汇总两个审查员的意见"
    input: |
      汇总以下审查意见：
      质量审查：${dual_review.reviewer_a.output}
      安全审查：${dual_review.reviewer_b.output}

  # Step 3: 统一修复
  - id: implement_fixes
    agent: code_imple
    description: "根据汇总报告修复代码"
    input: "修复问题：${aggregate_reviews.output}"

error_handling:
  on_error: continue

timeout: 600000
---

并行执行优势：

⚡ 速度提升 50%：两个审查员同时工作
🎯 多维度分析：质量 + 安全双重保障
📊 智能汇总：专业 Agent 去重和分类问题
🔧 一键完成：审查、汇总、修复全自动

使用工作流

# 列出所有工作流
/workflow list

# 运行工作流
/workflow run parallel-review "src/auth.ts"

# 查看工作流详情
/workflow info parallel-review

# 验证工作流定义
/workflow validate parallel-review

# 删除工作流
/workflow delete old-workflow

模板变量系统

支持丰富的变量引用：

# 用户输入
${workflow.input}

# 步骤输出
${stepId.output}

# 提取的数据
${stepId.data.key}

# 并行子步骤输出（嵌套引用）
${parallelGroupId.substepId.output}

# 并行组聚合数据
${parallelGroupId.data.success_count}
${parallelGroupId.data.failed_count}
${parallelGroupId.data.total_count}

当前状态：✅ 已完成，包括 WorkflowManager、WorkflowExecutor、CLI 集成、并行执行、完整文档

📚 详细文档：Workflow 用户指南 | 系统设计 | Workflow 概述

5️⃣ Plan+Todo 模式 ✅

先规划后执行的两阶段工作流，让复杂任务井然有序。

核心特性

🔒 安全的 Plan 模式：只读模式，只分析不修改代码
📋 结构化计划：包含步骤、风险评估、测试策略
✅ 智能依赖检查：自动验证任务依赖关系
⚙️ 灵活执行模式：支持自动（auto_edit）和手动（default）审批
🚀 批量执行：/todos execute-all 一键执行所有待办
📊 进度追踪：清晰的任务状态显示

工作流程

1. Plan 阶段（规划）

# 按 Ctrl+P 进入 Plan 模式
> [Ctrl+P]
[PLAN] >

# AI 分析需求并创建计划
[PLAN] > 帮我规划实现用户登录功能

✅ Plan Created: "Implement User Login"

Steps (5):
1. step-1: Create User model ⏱️ 30min
2. step-2: Implement JWT [deps: step-1] ⏱️ 45min
3. step-3: Create API endpoints [deps: step-2] ⏱️ 30min
4. step-4: Add frontend login form [deps: step-3] ⏱️ 1h
5. step-5: Write tests [deps: step-1, step-2, step-3] ⏱️ 1h

Risks: Password hashing, Token security
Testing: Unit tests + Integration tests

# 退出 Plan 模式
> [Ctrl+P]

2. Todo 阶段（执行）

# 将计划转换为待办任务
> /plan to-todos
✅ Created 5 todos

# 查看任务列表
> /todos list

📋 Todo List (5 total)
⬜ 5 pending

### HIGH Priority
⬜ step-1 - Create User model ⏱️ 30min
⬜ step-2 - Implement JWT [deps: step-1] ⏱️ 45min
  ⚠️  Token security vulnerabilities

# 执行单个任务（自动模式）
> /todos execute step-1 --mode=auto_edit
✓ write_file models/User.ts
✅ Task completed

# 或批量执行所有任务
> /todos execute-all --mode=auto_edit

🚀 Starting Batch Execution
📊 Total todos: 5

▶️  [1/5] Create User model...
✓ write_file models/User.ts

▶️  [2/5] Implement JWT...
✓ write_file auth/jwt.ts

[...]

✅ Batch Execution Complete!
📊 Executed 5/5 todos in 3 minutes

执行模式

| 模式 | 说明 | 适用场景 | |------|------|----------| | default | 每个操作需要确认 | 核心业务逻辑、数据库操作 | | auto_edit | 自动批准所有操作 | UI 组件、测试代码、文档 |

典型使用场景

🏗️ 功能开发：先规划架构和步骤，再逐步实现
🔄 代码重构：分析风险，制定安全的重构步骤
📚 学习代码库：使用 Plan 模式分析代码结构
💾 数据库迁移：详细规划迁移步骤和回滚方案

当前状态：✅ 已完成，包括 Plan 模式、Todo 管理、批量执行、完整文档

📚 详细文档：完整用户手册 | 快速指南 | 设计与实现

6️⃣ Spec 规格驱动开发 ✅

受 GitHub Spec Kit 启发的结构化软件开发系统，将"意图 → 规格 → 方案 → 任务 → 实施"做成可复用、可审查的链路。

核心流程

Constitution (宪章) → Specification (规格) → Technical Plan (技术方案) → Tasks (任务) → Implementation (实施)

核心特性

🏛️ Constitution 宪章：定义项目工程原则、质量标准、架构指南
📋 Specification 规格：业务需求文档化，专注 WHAT 和 WHY
🏗️ Technical Plan 方案：技术设计，支持多版本（v1, v2...）
✅ Task List 任务：可执行任务，支持多变体（default, detailed...）
🚀 自动执行：批量执行任务，依赖解析，进度跟踪

快速使用

# 1. 创建宪章（一次性）
/spec constitution --init

# 2. 创建业务规格
/spec new
# → AI 引导，生成 feat-user-auth

# 3. 生成技术方案
/spec plan new feat-user-auth
# → AI 设计，生成 plan-feat-user-auth-v1

# 4. 生成任务列表
/spec tasks new plan-feat-user-auth-v1
# → AI 拆分，生成 plan-feat-user-auth-v1-default

# 5. 批量执行任务
/spec execute start plan-feat-user-auth-v1-default
# → AI 自动执行所有任务

典型应用场景

🆕 新功能开发：完整的需求 → 设计 → 实施流程
🐛 Bug 修复：问题规格化，系统性解决
🔄 代码重构：风险评估，安全重构
📈 架构升级：多方案对比，选择最优

📚 详细文档：快速开始 | 用户指南 | 命令参考

📋 常用命令

基础功能

# 添加上下文：使用 @ 指定文件或文件夹
@src/myFile.ts          # 添加单个文件到上下文
@src/components/        # 添加整个文件夹到上下文

# Shell 模式：执行 shell 命令
!npm run start         # 使用 ! 前缀执行命令
start server           # 或使用自然语言描述

模型管理

# 查看当前模型和提供商
/model current

# 列出所有可用模型（跨提供商）
/model list

# 切换模型
/model use <provider>:<model>    # 指定提供商和模型
/model use <model>               # 使用默认提供商
# 示例：
/model use qwen3-coder-flash
/model use openai:gpt-4

Agent 管理

# 列出所有可用 Agents
/agents list

# 创建 Agent
/agents create <name> [options]           # 命令行方式创建
/agents create --interactive              # 交互式创建（推荐）

# 验证 Agent 配置
/agents validate <name>

# 删除 Agent
/agents delete <name>

# 查看 Agent 详情
/agents info <name>

# 运行 Agent
/agents run [--context isolated|shared] <name> <prompt>
# 或使用 @ 语法
@<name> <prompt>

# 清除 Agent 对话历史
/agents clear <name>

# 查看或管理 Agent 上下文
/agents context <name>

# 测试路由（显示哪个 Agent 会被选中）
/agents route <prompt>

# 查看或修改路由配置
/agents config

路由配置

# 查看路由配置
/agents config

# 启用/禁用路由
/agents config enable
/agents config disable

# 设置路由策略
/agents config set strategy hybrid

# 测试路由（不执行）
/agents route "你的提示词"

# 测试路由并执行
/agents route "你的提示词" --execute

Workflow 管理

# 列出所有可用 Workflow
/workflow list

# 查看 Workflow 详情
/workflow info <name>

# 执行 Workflow
/workflow run <name> <input>

# 验证 Workflow 定义
/workflow validate <name>

# 删除 Workflow
/workflow delete <name>

Plan+Todo 管理

# Plan 模式操作
/plan create            # 创建新计划（激活 Plan 模式并提示 AI）
/plan show              # 显示当前计划
/plan to-todos          # 将当前计划转换为 todo 列表（存入内存）
/plan clear             # 清除当前计划
/plan quit              # 退出 Plan 模式

# Todo 管理
/todos list             # 列出所有 todos
/todos execute <id> [--mode=auto_edit|default] [--agent=<name>] [--no-routing]  # 执行单个 todo
/todos execute-all [--mode=auto_edit|default] [--agent=<name>] [--no-routing]  # 批量执行所有待办
/todos update <id> <status>  # 更新 todo 状态
/todos export           # 导出 todos 为 JSON 格式
/todos clear            # 清除所有 todos

Spec 规格驱动开发

# Constitution 宪章管理
/spec constitution              # 显示当前宪章
/spec constitution --init       # 创建新宪章

# Specification 规格管理
/spec new                       # 创建新的业务规格（AI 引导）
/spec list                      # 列出所有规格
/spec show <id>                 # 显示规格详情
/spec plan <subcommand>         # 管理技术方案
/spec tasks <subcommand>        # 管理任务列表
/spec delete <id> [--force]     # 删除规格
/spec search <query>            # 搜索规格
/spec filter category:<cat>     # 按类别过滤
/spec filter status:<status>    # 按状态过滤
/spec update <id>               # 使用 AI 引导更新规格

# Execution 执行
/spec execute <subcommand>      # 执行任务

# Task 管理
/spec task <subcommand>         # 管理单个任务

对话管理

# 管理对话历史
/chat list                      # 列出保存的对话检查点
/chat save <tag>                # 将当前对话保存为检查点
/chat resume <tag>              # 从检查点恢复对话
/chat delete <tag>              # 删除对话检查点
/chat share <file>              # 将当前对话分享为 markdown 或 json 文件

工作区管理

# 管理工作区目录
/directory add <paths>          # 添加目录到工作区（使用逗号分隔多个路径）
/directory show                 # 显示工作区中的所有目录

扩展管理

# 管理扩展
/extensions list                # 列出活动扩展
/extensions update <extension-names>|--all  # 更新扩展

MCP 管理

# MCP 服务器管理
/mcp list                       # 列出已配置的 MCP 服务器和工具
/mcp auth                       # 使用 OAuth 认证 MCP 服务器
/mcp refresh                    # 重启 MCP 服务器

内存管理

# 内存命令
/memory show                    # 显示当前内存内容
/memory add                     # 添加内容到内存
/memory refresh                 # 从源刷新内存
/memory list                    # 列出正在使用的 GEMINI.md 文件路径

统计信息

# 查看会话统计
/stats                          # 检查会话统计
/stats model                    # 显示模型特定的使用统计
/stats tools                    # 显示工具特定的使用统计

其他命令

# 基础命令
/about                          # 显示版本信息
/auth                           # 更改认证方法
/bug                            # 提交 Bug 报告
/clear                          # 清除屏幕和对话历史
/compress                       # 通过摘要替换上下文来压缩上下文
/copy                           # 复制最后的结果或代码片段到剪贴板
/docs                           # 在浏览器中打开完整的 Gemini CLI 文档
/editor                         # 设置外部编辑器偏好
/help                           # 获取帮助信息
/ide                            # 管理 IDE 集成
/init                           # 分析项目并创建定制的 GEMINI.md 文件
/privacy                        # 显示隐私声明
/quit                           # 退出 CLI
/theme                          # 更改主题
/tools [desc]                   # 列出可用的 Gemini CLI 工具
/settings                       # 查看和编辑 Gemini CLI 设置
/vim                            # 切换 vim 模式开/关
/setup-github                   # 设置 GitHub Actions
/terminal-setup                 # 配置终端按键绑定以支持多行输入（VS Code、Cursor、Windsurf）

# Shell 命令
!<command>                       # 执行 shell 命令

# MCP 命令
[MCP]                           # Model Context Protocol 命令（来自外部服务器）

键盘快捷键

Alt+Left/Right                  # 在输入中跳转单词
Ctrl+C                          # 退出应用
Ctrl+J                          # 新行
Ctrl+L                          # 清除屏幕
Ctrl+X / Meta+Enter             # 在外部编辑器中打开输入
Ctrl+Y                          # 切换 YOLO 模式
Enter                           # 发送消息
Esc                             # 取消操作 / 清除输入（双击）
Shift+Tab                       # 切换自动接受编辑
Up/Down                         # 循环浏览提示历史记录

📚 完整快捷键列表：详见键盘快捷键文档

📚 文档导航

用户指南

🎭 Agents 用户指南 - Agents 系统完整使用手册
🚀 Agents 快速开始 - 5 分钟上手指南
🔄 Workflow 用户指南 - Workflow 完整使用指南
📋 Plan+Todo 用户手册 - Plan+Todo 完整手册
📐 Spec 规格驱动开发 - Spec-Driven Development 快速开始
🤖 如何添加新模型 - 自定义模型配置指南

设计文档

📐 整体架构设计 - 所有功能的设计文档索引
🎭 Agents 系统设计 - Agents 架构设计
🧭 智能路由系统 - 路由功能设计
🔄 Workflow 系统设计 - 工作流架构
📋 Plan+Todo 设计 - Plan+Todo 架构设计
📐 Spec 系统概览 - Spec-Driven Development 系统设计
🤖 模型系统设计 - 通用模型支持架构

开发文档

🏗️ 架构概览 - 系统架构概览
🤝 贡献指南 - 如何参与开发
📝 开发环境搭建 - 开发环境配置

🎨 配置示例

`~/.gemini/config.json` - 多模型配置

{
  // ========== 顶层配置 ==========
  "useModelRouter": true,                    // 必须：启用自定义模型支持
  "defaultModel": "qwen3-coder-flash",       // 推荐：默认模型（启动时使用）
  
  // ========== 模型定义 ==========
  "models": {
    // 通义千问 Flash（推荐用于日常开发）
    "qwen3-coder-flash": {
      "provider": "openai",                  // 必须：OpenAI 兼容适配器
      "model": "qwen3-coder-flash",         // 必须：API 调用的模型名
      "apiKey": "sk-your-qwen-api-key",     // 必须：从通义千问控制台获取
      "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",  // 必须：通义千问 API 端点
      "metadata": {
        "providerName": "qwen",             // 推荐：身份标识（AI 会说"我是通义千问"）
        "displayName": "通义千问 Flash"      // 可选：UI 显示名称
      },
      "capabilities": {
        "maxOutputTokens": 8192,            // 推荐：最大输出 token 数
        "supportsFunctionCalling": true,   // 重要：Qwen 支持工具调用（必须 true）
        "supportsMultimodal": true         // 重要：Qwen 支持数组格式（必须 true）
      }
    },
    
    // 通义千问 Plus（高级任务）
    "qwen-coder-plus": {
      "provider": "openai",
      "model": "qwen-coder-plus",
      "apiKey": "sk-your-qwen-api-key",
      "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
      "metadata": {
        "providerName": "qwen",
        "displayName": "通义千问 Plus"
      },
      "capabilities": {
        "maxOutputTokens": 8192,
        "supportsFunctionCalling": true,
        "supportsMultimodal": true
      }
    },
    
    // DeepSeek（代码生成）
    "deepseek-coder": {
      "provider": "openai",
      "model": "deepseek-coder",
      "apiKey": "sk-your-deepseek-key",     // 必须：从 DeepSeek 官网获取
      "baseUrl": "https://api.deepseek.com", // 必须：DeepSeek API 端点
      "metadata": {
        "providerName": "deepseek",
        "displayName": "DeepSeek Coder"
      },
      "capabilities": {
        "maxOutputTokens": 4096,
        "supportsFunctionCalling": false,  // 重要：DeepSeek 不支持（必须 false）
        "supportsMultimodal": false        // 重要：DeepSeek 不支持（必须 false）
      }
    },
    
    // 本地 Ollama（离线开发）
    "local-qwen": {
      "provider": "openai",
      "model": "qwen2.5-coder:32b",
      "apiKey": "ollama",                   // Ollama 不需要真实 key
      "baseUrl": "http://localhost:11434/v1",
      "metadata": {
        "providerName": "qwen",
        "displayName": "本地千问"
      },
      "capabilities": {
        "maxOutputTokens": 4096,
        "supportsFunctionCalling": false   // 本地模型通常不支持
      }
    }
  }
}

`~/.gemini/settings.json` - 系统设置

{
  // ========== 通用设置 ==========
  "general": {
    "disableAutoUpdate": true,               // 推荐：禁用自动更新
    "disableUpdateNag": true                 // 推荐：禁用更新提示
  },
  
  // ========== IDE 集成 ==========
  "ide": {
    "hasSeenNudge": true                     // 内部：已看过提示
  },
  
  // ========== MCP 服务器 ==========
  "mcpServers": {
    "context7": {                            // MCP 服务器名称（可选配置）
      "httpUrl": "https://mcp.context7.com/mcp",  // HTTP MCP 端点
      "headers": {
        "CONTEXT7_API_KEY": "your-api-key",       // API 认证
        "Accept": "application/json, text/event-stream"
      }
    }
  },
  
  // ========== 模型设置 ==========
  "model": {
    "name": "qwen3-coder-flash"              // 当前使用的模型
  },
  
  // ========== 安全设置 ==========
  "security": {
    "auth": {
      "selectedType": "custom-model"         // 必须：使用自定义模型认证
    }
  },
  
  // ========== 实验性功能 ==========
  "experimental": {
    "useModelRouter": true                   // 必须：启用模型路由（与 config.json 配合）
  },
  
  // ========== 受信任文件夹 ==========
  "trustedFolders": [
    "/path/to/your/trusted/project"          // 可选：受信任的项目目录
  ]
}

配置字段说明

config.json 核心字段

| 字段 | 类型 | 必填 | 说明 | |------|------|------|------| | useModelRouter | boolean | ✅ 是 | 启用自定义模型支持，必须 true | | defaultModel | string | ⚠️ 推荐 | 默认模型名，必须在 models 中定义 | | models.<name>.provider | string | ✅ 是 | 提供商："openai"（兼容）、"gemini"、"claude" | | models.<name>.model | string | ✅ 是 | API 调用的实际模型名 | | models.<name>.apiKey | string | ⚠️ 推荐 | API 密钥（也可用环境变量） | | models.<name>.baseUrl | string | ✅ 是 | API 服务器地址 | | metadata.providerName | string | ⚠️ 推荐 | 身份标识："qwen"、"deepseek" 等 | | metadata.displayName | string | ❌ 否 | UI 显示名称 | | capabilities.maxOutputTokens | number | ⚠️ 推荐 | 最大输出 token 数 | | capabilities.supportsFunctionCalling | boolean | ⚠️ 推荐 | 是否支持工具调用（Qwen=true, DeepSeek=false） | | capabilities.supportsMultimodal | boolean | ⚠️ 推荐 | 是否支持数组格式（Qwen=true, DeepSeek=false） |

settings.json 核心字段

| 字段 | 类型 | 必填 | 说明 | |------|------|------|------| | experimental.useModelRouter | boolean | ✅ 是 | 必须 true，与 config.json 配合启用自定义模型 | | security.auth.selectedType | string | ⚠️ 推荐 | 认证类型："custom-model"（自定义模型）、"api-key"（Gemini） | | model.name | string | ❌ 否 | 当前模型，通过 /model use 自动更新 | | general.disableAutoUpdate | boolean | ❌ 否 | 禁用自动更新（推荐 true） | | mcpServers.<name> | object | ❌ 否 | MCP 服务器配置（可选） | | trustedFolders | array | ❌ 否 | 受信任的项目目录列表 |

⚠️ 关键提示：

config.json 和 settings.json 中的 useModelRouter 都必须设为 true
通义千问必须设置 supportsFunctionCalling: true 才能使用工具功能
DeepSeek 必须设置 supportsFunctionCalling: false 和 supportsMultimodal: false
API Key 也可通过环境变量提供：QWEN_API_KEY、DEEPSEEK_API_KEY

Agents 配置

创建 .gemini/agents/ 目录，添加 Agent 文件：

代码审查 Agent (.gemini/agents/code_review.md)

---
kind: agent
name: code_review
title: 代码审查助手
description: 专业的代码质量审查，只审查不实现
model: deepseek-coder
scope: project
version: 1.0.0
contextMode: shared
triggers:
  keywords: [审查, review, 检查, 代码质量]
  priority: 80
tools:
  allow: ["read_file","read_many_files","ls","glob","grep","rg","web_fetch","web_search"]
  deny: ["write_file","edit_file","bash"]
mcp:
  servers: []
handoffs:
  - to: code_imple
    when: manual
    description: "当用户需要实现代码、修复bug或编写功能时，移交给 code_imple agent"
    include_context: true
---

# Role

⚠️ **你是代码审查专家 - 只负责审查代码质量，不实现代码**

## 关键规则 - 首先判断任务类型

在做任何事情之前，先判断任务类型：

1. **如果用户要求实现/修复/编写代码**（关键词：实现、修复、编写、开发、写代码、implement、fix、write、develop）：
   - ❌ 不要读取任何文件
   - ❌ 不要进行任何分析
   - ✅ 立即使用 `transfer_to_code_imple` 工具移交任务

2. **如果用户要求审查/检查/分析代码**（关键词：审查、检查、分析、review、check、analyze）：
   - ✅ 读取必要的文件
   - ✅ 分析代码质量
   - ✅ 提供审查反馈

## 审查重点

1. 代码可读性和命名规范
2. 潜在的 bug 和逻辑错误
3. 性能优化建议
4. 安全漏洞检测

## 输出格式

- 🔴 严重问题（必须修复）
- 🟡 重要问题（应该修复）
- 🔵 优化建议（可选）
- ✅ 良好实践（继续保持）

调试专家 Agent (.gemini/agents/debug_analyzer.md)

---
kind: agent
name: debug_analyzer
title: 调试专家
description: 系统性分析和调试代码错误
model: deepseek-coder
scope: project
version: 1.0.0
contextMode: isolated
triggers:
  keywords: [调试, debug, 错误, bug, 异常]
  priority: 85
tools:
  allow: ["read_file","read_many_files","grep","rg","bash"]
  deny: ["write_file","edit_file"]
mcp:
  servers: []
---

# Role

You are a debugging expert who systematically analyzes errors and provides 
root cause analysis with step-by-step solutions.

## Workflow

1. Read error messages and stack traces
2. Examine relevant code files
3. Search for related code patterns
4. Run diagnostic commands
5. Provide root cause and fix suggestions

路由配置

在 .gemini/settings.json 中配置路由：

{
  "routing": {
    "enabled": true,
    "strategy": "hybrid",
    "rule": {
      "confidence_threshold": 75
    },
    "llm": {
      "model": "gemini-2.0-flash",
      "timeout": 5000
    },
    "fallback": "prompt_user"
  }
}

或通过环境变量：

export GEMINI_ROUTING_ENABLED=true
export GEMINI_ROUTING_STRATEGY=hybrid
export GEMINI_ROUTING_CONFIDENCE_THRESHOLD=75

🔄 与 Gemini CLI 的关系

技术基础

伏羲 CLI 基于 Google Gemini CLI 开发，完全兼容原有功能。我们在保留其强大能力的同时，针对国内开发者的需求进行了以下扩展：

主要扩展

| 扩展功能 | 原 Gemini CLI | 伏羲 CLI | |---------|--------------|---------| | 自定义模型配置 | ❌ 仅支持 Gemini/OpenAI/Claude | ✅ 支持任意 OpenAI 兼容模型 | | 国内模型支持 | ❌ 无 | ✅ 通义千问、DeepSeek 等开箱即用 | | Agents 系统 | ⚠️ 基础功能 | ✅ 完整的智能体系统 | | 智能路由 | ❌ 无 | ✅ 自动选择最佳 Agent | | Agent 移交 | ❌ 无 | ✅ Agent 间智能协作 | | Workflow 顺序执行 | ❌ 无 | ✅ 多 Agent 顺序编排 | | Workflow 并行执行 | ❌ 无 | ✅ 多 Agent 并行执行，显著提速 | | Plan+Todo 模式 | ❌ 无 | ✅ 先规划后执行，批量执行支持 | | Spec 规格驱动开发 | ❌ 无 | ✅ Constitution → Spec → Plan → Tasks → Execute | | 中文文档 | ❌ 英文为主 | ✅ 完整中文文档 |

兼容性

✅ 完全兼容 Gemini CLI 的配置文件
✅ 完全兼容 Gemini CLI 的命令
✅ 可以无缝切换回 Gemini CLI
✅ 共享相同的 .gemini/ 配置目录

开源协议

两个项目均采用 Apache 2.0 开源协议，可自由使用和修改。

🤝 贡献与支持

贡献代码

我们欢迎所有形式的贡献！

Fork 本仓库
创建特性分支：git checkout -b feature/amazing-feature
提交更改：git commit -m 'Add amazing feature'
推送分支：git push origin feature/amazing-feature
提交 Pull Request

问题反馈

开发指南

# 克隆仓库
git clone https://github.com/MJ-CJM/fuxi-cli/fuxi-cli.git
cd fuxi-cli

# 安装依赖
npm install

# 构建项目
npm run build

# 运行测试
npm test

# 启动开发模式
npm start

📄 许可证

本项目采用 Apache License 2.0 开源协议。

基于 Google Gemini CLI（Apache 2.0）开发。

🙏 致谢

感谢 Google Gemini CLI 团队提供优秀的基础框架
感谢所有贡献者的支持和参与
感谢开源社区的持续推动

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

📖 项目简介

🎯 核心扩展功能

⚡ 继承的强大功能

🚀 快速开始

安装

方式一：NPM 全局安装（推荐）

方式二：源码安装

方式三：Docker 开发环境

文件映射模式（推荐用于开发）

完整打包模式（适合生产部署）

系统要求

🎯 核心功能

1️⃣ 自定义模型支持

支持的模型类型

快速配置示例

步骤 1：配置模型（~/.gemini/config.json）

步骤 2：配置系统设置（~/.gemini/settings.json）

步骤 3：使用自定义模型

2️⃣ Agents 智能体系统

什么是 Agent？

快速创建 Agent

Agent 配置示例

使用 Agent

3️⃣ 智能路由与移交

智能路由

Agent 移交

4️⃣ Workflow 工作流 ✅

核心特性

顺序工作流示例

并行工作流示例 ⭐

使用工作流

模板变量系统

5️⃣ Plan+Todo 模式 ✅

核心特性

工作流程

执行模式

典型使用场景

6️⃣ Spec 规格驱动开发 ✅

核心流程

核心特性

快速使用

典型应用场景

📋 常用命令

基础功能

模型管理

Agent 管理

路由配置

Workflow 管理

Plan+Todo 管理

Spec 规格驱动开发

对话管理

工作区管理

扩展管理

MCP 管理

内存管理

统计信息

其他命令

键盘快捷键

📚 文档导航

用户指南

设计文档

开发文档

🎨 配置示例

~/.gemini/config.json - 多模型配置

~/.gemini/settings.json - 系统设置

配置字段说明

config.json 核心字段

settings.json 核心字段

Agents 配置

路由配置

🔄 与 Gemini CLI 的关系

技术基础

主要扩展

兼容性

步骤 1：配置模型（`~/.gemini/config.json`）

步骤 2：配置系统设置（`~/.gemini/settings.json`）

`~/.gemini/config.json` - 多模型配置

`~/.gemini/settings.json` - 系统设置