AI 发展历程

人工智能经历了从规则系统到深度学习再到大模型的演进过程：

• 1950s-1960s 奠基阶段：图灵提出「图灵测试」（1950），感知机诞生（1958），ELIZA 聊天程序基于模式匹配模拟对话（1966）
• 1970s-1980s 符号主义与专家系统：基于规则和逻辑推理的专家系统迎来黄金期，代表性成果如 MYCIN（医疗诊断）、DENDRAL（化学分析）
• 1990s-2010s 机器学习时代：统计学习方法兴起，SVM、随机森林、朴素贝叶斯等算法广泛应用于分类、回归任务
• 2012 深度学习爆发：AlexNet 在 ImageNet 竞赛中大幅领先，CNN 在图像识别领域取得突破性进展
• 2017 Transformer 诞生：Google 发表《Attention Is All You Need》论文，提出自注意力机制，奠定了后续所有大模型的基础架构
• 2018-2019 预训练模型兴起：OpenAI 发布 GPT，Google 发布 BERT，「预训练 + 微调」范式成为主流
• 2020-2022 规模化竞赛：GPT-3（1750 亿参数）展示了大模型的涌现能力，模型规模和能力快速增长
• 2022.11 ChatGPT 发布：大模型进入公众视野，两个月内用户破亿，开启 AI 应用爆发期
• 2023 多模态元年：GPT-4V（2023.9）、Gemini（2023.12）等多模态模型涌现，能同时处理文本、图像、音频
• 2024 大模型全面落地：Claude 3 系列发布（2024.3），开源模型（Llama 3、Mistral）快速追赶，AI 应用在各行业加速渗透
• 2025-至今 Agent 时代：AI Agent 成为新方向，Claude Code（2025.2）、OpenAI Codex（2025.5）等编程 Agent 落地，AI 从「对话」走向「行动」

什么是大语言模型（LLM）

大语言模型（Large Language Model）是基于 Transformer 架构、通过海量文本数据训练而成的深度学习模型。它通过学习文本中的统计规律，掌握了语言理解和生成能力，能完成对话、翻译、摘要、代码生成等多种任务。

大模型的工作原理

本质上，大模型是一个「下一个 Token 预测器」——给定前面的文本，预测最可能出现的下一个词。通过海量数据训练，模型学会了语法、逻辑、常识甚至推理能力。

模型架构：不只有 Transformer

目前主流大模型（GPT、Claude、Gemini）底层仍是 Transformer，但也出现了几种值得关注的替代架构：

核心概念详解

Token（令牌）

Token 是模型处理文本的最小单位，并非简单的「字」或「词」，而是通过分词算法（如 BPE）切分出来的片段。

• 英文中一个常见单词约 1 个 Token，长单词可能被拆为 2-3 个 Token
• 中文约 1-2 个汉字为一个 Token，标点符号也占 Token
• 代码中的关键字、变量名、符号都各自占 Token
• 输入 Token（Prompt）：你发送给模型的全部内容，包括 System Prompt + 历史对话 + 当前问题
• 输出 Token（Completion）：模型生成的回复内容
• 费用计算：输入 Token 单价 × 输入量 + 输出 Token 单价 × 输出量（输出通常比输入贵 3-5 倍）

Context Window（上下文窗口）

模型单次对话能处理的最大 Token 数，包含输入和输出的总和。超出窗口限制的早期内容会被截断或「遗忘」，这就是为什么长对话后模型会「忘记」之前说过的话。

Temperature（温度）

控制模型输出的随机性和创造性。温度越低，输出越确定和一致；温度越高，输出越多样和有创意。

• Temperature = 0：每次输出几乎相同，最确定最保守。适合代码生成、数据提取、事实性问答
• Temperature = 0.3-0.5：轻微随机性，保持准确的同时有一定灵活度。适合技术文档、邮件撰写
• Temperature = 0.7：平衡创造性和准确性，大多数场景的默认值。适合日常对话、一般写作
• Temperature = 1.0+：高度随机，可能出现意想不到的表达。适合创意写作、头脑风暴、诗歌创作

System Prompt（系统提示词）

在对话开始前设定的指令，定义模型的角色、行为规范、输出格式和限制条件。相当于给模型一个「人设」和「工作手册」。好的 System Prompt 能显著提升输出质量。

你是一位资深 Java 后端工程师，擅长 Spring Boot 和微服务架构。
请用中文回答，代码要包含详细注释。
回答格式要求：先给出结论，再详细解释原因，最后给出代码示例。
如果不确定，请明确说明而不是猜测。

Top-P（核采样）

另一种控制输出多样性的参数。Top-P = 0.9 表示模型只从累计概率前 90% 的候选词中采样。通常与 Temperature 配合使用，不建议同时调高两者。

Max Tokens（最大输出长度）

限制模型单次回复的最大 Token 数。设置过小会导致回答被截断，设置过大会增加成本和延迟。一般建议根据任务类型设置：简单问答 500-1000，代码生成 2000-4000，长文写作 4000-8000。

主流大模型对比

Prompt Engineering（提示词工程）

提示词的质量直接决定模型输出的质量。掌握以下技巧可以显著提升效果：

1. 角色设定（Role Prompting）

给模型一个明确的身份，让它以专家视角回答问题。

你是一位有 10 年经验的 Java 架构师，精通 Spring Cloud 微服务体系。

2. 明确任务与约束

清晰描述输入、输出格式、约束条件，减少歧义。

请将以下 JSON 数据转换为 Java 实体类。
要求：使用 Lombok 注解，字段加上 Javadoc 注释，日期类型用 LocalDateTime。

3. Few-shot 示例

提供 1-3 个输入输出示例，让模型理解你期望的格式和风格。

4. 思维链（Chain of Thought）

要求模型「一步步思考」，对复杂推理任务效果显著。

请一步步分析这段代码的执行流程，找出可能导致空指针异常的位置。

5. 结构化输出

要求模型以特定格式（JSON、Markdown 表格、XML）输出，便于程序解析。

6. 限制与兜底

明确告诉模型不该做什么，以及不确定时如何处理。

只修改 UserService.java 文件，不要改动其他代码。
如果不确定某个方法的用途，请标注 TODO 而不是猜测。

什么是 AI Agent（智能体）

AI Agent 是在大模型基础上，增加了感知环境、自主规划、工具调用、记忆存储能力的自主系统。与普通对话不同，Agent 能够主动执行多步骤任务，而不仅仅是回答问题。

Agent vs 普通对话的区别

Agent 核心组件

1. 规划（Planning）

Agent 接收到复杂任务后，会将其拆解为多个子步骤，制定执行计划。

• 任务分解：将「重构用户模块」拆解为：分析现有代码 → 设计新结构 → 逐步修改 → 运行测试
• 动态调整：执行过程中根据结果调整后续步骤

2. 工具使用（Tool Use / Function Calling）

Agent 可以调用外部工具来完成自身无法直接完成的任务：

• 执行终端命令（编译、运行测试、Git 操作）
• 读写文件系统
• 调用外部 API（搜索、数据库查询）
• 浏览网页获取信息

3. 记忆（Memory）

• 短期记忆：当前对话的上下文，受 Context Window 限制
• 长期记忆：通过外部存储（向量数据库、文件）持久化关键信息
• 工作记忆：当前任务的中间状态和执行进度

4. 反思（Reflection）

Agent 能够检查自己的输出，发现错误并自我纠正。例如：代码编译失败后，自动分析错误信息并修复。

Agent 工作流模式

根据复杂度不同，Agent 有多种编排模式：

单 Agent 模式

一个 Agent 独立完成所有任务，适合简单场景。如 Claude Code 单独修复一个 Bug。

多 Agent 协作模式

多个专业 Agent 分工协作，各司其职：

• 串行链式：Agent A 的输出作为 Agent B 的输入（如：需求分析 → 代码生成 → 代码审查）
• 并行分发：多个 Agent 同时处理不同子任务，最后汇总结果
• 监督者模式：一个主 Agent 负责调度，多个子 Agent 执行具体任务

人机协作模式（Human-in-the-Loop）

Agent 在关键决策点暂停，等待人类确认后再继续。这是目前编程 Agent 的主流模式——工具会在执行危险操作前请求你的批准。

MCP 协议（Model Context Protocol）

MCP 是 Anthropic 提出的开放协议，旨在标准化 AI 模型与外部工具/数据源的连接方式。

MCP 的本质：给模型提供上下文

名字里的 Context 就是关键——MCP 本质上是一套标准化的上下文注入协议。大模型本身只能处理 Context Window 里的文本，MCP 解决的是「怎么把外部世界的信息塞进上下文」这个问题。

MCP Server 提供三类能力，都是在为模型补充上下文：

• Tools（工具）：让模型调用外部操作（查数据库、调 API、操作 Jira），执行结果作为上下文返回
• Resources（资源）：向模型暴露可读取的数据源（文件、文档、配置），模型按需拉取
• Prompts（提示模板）：预定义的提示词模板，引导模型以特定方式处理任务

为什么需要 MCP？

以前每个 AI 工具都要单独开发与外部系统的集成（N 个工具 × M 个数据源 = N×M 个适配器）。MCP 提供统一标准，让任何支持 MCP 的客户端都能连接任何 MCP 服务器，变成 N + M 的关系。

MCP 架构

┌──────────────┐     MCP 协议     ┌──────────────┐
│  AI 工具端    │ ◄──────────────► │  MCP Server  │
│ (Claude Code │                  │ (数据库/API/ │
│  Cherry Studio│                  │  文件系统等)  │
│  Roo Code)   │                  │              │
└──────────────┘                  └──────────────┘
    MCP Client                     MCP Server
    (消费工具)                      (提供工具)

MCP、Slash Commands、Skills 的关系

在 Claude Code 等工具中，你会接触到几种看起来相似的扩展机制，它们的定位其实不同：

它们的关系可以这样理解：MCP 是底层协议（连接外部世界）→ Skills 是能力封装（组合多种工具和 prompt）→ Slash Commands 是用户入口（一键触发某个 Skill）。三者是不同层次的抽象，而非互相替代。

RAG（检索增强生成）

RAG（Retrieval-Augmented Generation）是解决大模型「知识过时」和「幻觉」问题的关键技术。

工作原理

用户提问
   │
   ▼
┌─────────────┐    检索相关文档    ┌─────────────┐
│  向量检索     │ ◄──────────────► │  知识库       │
│  (Embedding) │                  │ (文档/数据库) │
└──────┬──────┘                  └─────────────┘
       │ 检索到的上下文
       ▼
┌─────────────┐
│   大模型      │ → 基于检索结果生成回答
└─────────────┘

RAG 的优势

• 知识实时更新：无需重新训练模型，更新知识库即可
• 减少幻觉：回答基于真实文档，可溯源
• 领域定制：接入企业内部文档，打造专属知识助手
• 成本低：比微调模型便宜得多

RAG vs Agent 探索：编程场景为什么不用 RAG？

你可能注意到，Claude Code、Codex 这类编程 Agent 并没有用 RAG，而是让子 Agent 实时探索代码库（grep、glob、读文件）。这不是偶然的选择：

简单说：代码是结构化的、频繁变动的、需要精确定位的——这恰好是 RAG 的弱项和 Agent 探索的强项。而企业知识库、客服文档这类大规模、相对静态、语义检索即可的场景，RAG 仍然是最佳方案。

AI 在软件开发中的应用场景

代码生成与补全

根据自然语言描述或上下文自动生成代码，提升编码效率 30%-50%。

代码审查与重构

AI 自动检查代码质量、发现潜在 Bug、建议重构方案。

Bug 定位与修复

给出错误信息，AI 自动分析堆栈、定位根因、生成修复代码。

测试生成

自动为现有代码生成单元测试，提高测试覆盖率。

文档生成

自动为代码生成注释、API 文档、技术方案文档。

需求分析与设计

辅助分析需求文档、生成数据库设计、绘制架构图。

整体架构概览

我们的 API KEY 池采用 NewAPI + Sub2API 的双层架构，实现多模型统一接入、密钥轮转和用量管控。

┌─────────────────────────────────────────────────┐
│                  用户 / 工具端                     │
│  (Cherry Studio / Roo Code / Claude Code / ...)  │
└──────────────────────┬──────────────────────────┘
                       │ 多格式 API（OpenAI / Anthropic / 等）
                       ▼
              ┌─────────────────┐
              │     NewAPI       │  ← API 网关层
              │  (统一入口管理)    │
              │  - 用户管理       │
              │  - 令牌分发       │
              │  - 用量统计       │
              │  - 模型路由       │
              └────────┬────────┘
                       │
          ┌────────────┼────────────┐
          ▼            ▼            ▼
   ┌────────────┐┌────────────┐┌────────────┐
   │ Sub2API #1 ││ Sub2API #2 ││ Sub2API #3 │  ← 号池层
   │ (Claude池) ││ (GPT池)    ││ (其他池)    │
   │ N 个 KEY   ││ N 个 KEY   ││ N 个 KEY   │
   └─────┬──────┘└─────┬──────┘└─────┬──────┘
         │             │             │
         ▼             ▼             ▼
   ┌──────────┐ ┌──────────┐ ┌──────────┐
   │ Anthropic│ │  OpenAI  │ │ Google/  │
   │   API    │ │   API    │ │ DeepSeek │
   └──────────┘ └──────────┘ └──────────┘

点击查看架构图

NewAPI —— 统一网关

NewAPI 是一个开源的 API 管理与分发平台，支持多种 AI 厂商 API 格式的统一接入与互相转换。

核心功能

• 多模型聚合：统一接入 Claude / GPT / Gemini / DeepSeek 等
• 用户与令牌管理：为每位成员分配独立令牌，设置额度
• 用量监控：实时统计每个用户、每个模型的调用量和费用
• 模型映射：自定义模型名称映射，对用户透明
• 渠道管理：配置多个上游渠道，支持优先级和权重

Sub2API —— 号池管理

Sub2API 负责管理同一厂商的多个 API KEY，实现自动轮转和故障切换。

核心功能

• KEY 轮转：请求自动分配到不同 KEY，避免单 KEY 限速
• 健康检查：自动检测失效 KEY 并剔除
• 负载均衡：支持轮询、随机、权重等策略
• 兼容输出：对外暴露标准 OpenAI 格式接口

为什么选择这个架构？

• 用户只需一个 KEY，即可访问所有模型
• KEY 池自动轮转，突破单 KEY 速率限制
• 统一计费和用量管控，便于成本核算
• 兼容多种 API 格式（OpenAI / Anthropic / Azure 等），并能灵活转换，几乎所有工具都能直接接入
• 只需一个 API Key 即可使用，无需注册各厂商账号——降低了解门槛和使用门槛，不用关心各平台的注册流程、付费方式、信用卡绑定等繁琐操作
• 故障自动切换，提高可用性

BYOK 与订阅模式

在使用 AI 工具时，获取 AI 能力通常有两种模式：

• 订阅模式（Subscription）：用户向工具厂商支付固定月费 / 年费，AI 服务已包含在内，开箱即用。典型例子：ChatGPT Plus、Claude Pro、Cursor Pro。
• BYOK 模式（Bring Your Own Key）：工具本身不捆绑 AI 服务，用户需要自行前往各 AI 厂商（如 OpenAI、Anthropic、Google 等）注册账号、申请 API Key，然后填入工具中使用。工具只收取软件本身的费用（或完全免费），AI 用量由用户直接与厂商结算。典型例子：Cherry Studio、TypingMind、Roo Code、Cline。

第一步：获取你的 API KEY

第二步：配置 API 地址

所有工具的配置都需要两个信息：API Base URL 和 API Key（上一步获取）。

可用的 API 地址（三选一）：

第三步：选择模型

KEY 池中已接入以下模型（以实际配置为准）：

• Claude claude-opus-4-6 / claude-sonnet-4-6 / claude-opus-4-5-thinking / claude-sonnet-4-5 / claude-haiku-4-5
• GPT gpt-5.4 / gpt-5.2 / gpt-5.1 / gpt-5 / gpt-5.3-codex / gpt-5.2-codex / gpt-5.1-codex / gpt-5-codex
• Gemini gemini-3.1-pro / gemini-3-pro-preview / gemini-3-flash / gemini-2.5-pro / gemini-2.5-flash
• DeepSeek deepseek-ai/DeepSeek-R1-0528 / deepseek-ai/DeepSeek-V3.2
• Kimi moonshotai/kimi-k2.5 / moonshotai/kimi-k2-thinking
• 其他 z-ai/glm4.7 / minimaxai/minimax-m2.1

第四步：测试连通性

选择以下任一方式验证配置是否正确：

curl（OpenAI 格式）

curl https://jp-ai.havefun.eu.cc/v1/chat/completions \
  -H "Authorization: Bearer sk-你的令牌" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.2",
    "messages": [{"role": "user", "content": "你好"}]
  }'

curl（Anthropic 格式）

curl https://jp-ai.havefun.eu.cc/v1/messages \
  -H "x-api-key: sk-你的令牌" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "你好"}]
  }'

Python（OpenAI SDK）

from openai import OpenAI

client = OpenAI(
    api_key="sk-你的令牌",
    base_url="https://jp-ai.havefun.eu.cc/v1"
)

response = client.chat.completions.create(
    model="gpt-5.2",
    messages=[{"role": "user", "content": "你好"}]
)
print(response.choices[0].message.content)

返回正常响应即表示配置成功。

常见问题

• Q: 报 401 错误？ → 检查 API Key 是否正确，是否过期
• Q: 报 404 错误？ → 检查 Base URL 是否正确，末尾不要加 /v1（部分工具会自动拼接）
• Q: 模型不存在？ → 确认模型名称与 NewAPI 中配置的一致
• Q: 响应很慢？ → 可能是网络问题，或尝试切换到更快的模型

简介

Cherry Studio 是一款开源的多模型聚合桌面客户端，支持 Windows / macOS / Linux。它提供美观的对话界面，是目前最受欢迎的大模型桌面客户端之一。

核心亮点

• 多模型切换：在同一对话中自由切换不同模型（GPT、Claude、Gemini、DeepSeek 等），方便对比效果
• 对话管理：支持多会话管理、对话分组、历史记录搜索，对话数据本地存储
• 知识库：支持导入文档构建本地知识库，实现基于文档的 AI 问答（RAG）
• MCP 支持：内置 MCP（Model Context Protocol）支持，可扩展 AI 的工具调用能力
• Prompt 模板：内置丰富的 Prompt 模板库，支持自定义模板
• 备份恢复：支持完整的配置导入/导出，方便团队统一配置分发

安装

配置 KEY 池 — 推荐方式：备份恢复（一键导入）

我们提供了预配置好的备份文件（zip 格式），其中已包含四种常用供应商（OpenAI、OpenAI-Response、Gemini、Anthropic）的配置。你只需导入备份后填入自己的 API Key 即可使用。

2

导入备份

打开 Cherry Studio，进入「设置 → 数据设置 → 备份与恢复」，点击「恢复」按钮，选择获取到的 zip 备份文件，等待导入完成。

⚠️ 警告：导入备份会覆盖当前所有数据，包括清空以往的聊天记录。请在导入前确认是否需要保留现有对话，必要时先手动导出备份。

点击查看截图

3

填入 API Key

导入完成后，进入「设置 → 模型服务」，在对应的服务商处填入你自己的 API Key 即可。备份文件中已配置好模型列表，无需手动添加模型。

重要：四种供应商（OpenAI、OpenAI-Response、Gemini、Anthropic）都使用同一个 KEY 池 API Key。你在「使用教程 → 获取 API Key」中获得的那个 Key，在每个供应商处都填入同一个即可，无需申请不同的 Key。

点击查看截图

配置 KEY 池 — 手动方式（备选）

如果你不使用备份恢复，也可以手动添加模型服务商。虽然所有模型都可以通过「OpenAI」格式统一接入，但推荐为不同厂商的模型选择各自的原生格式，以获得最佳体验。

1

打开设置

点击左下角齿轮图标，进入「模型服务」设置。你可以看到 Cherry Studio 支持多种供应商类型：

点击查看截图 — 供应商列表

2

添加供应商并配置

根据你需要使用的模型，选择对应的供应商类型添加。所有供应商都使用同一个 KEY 池 API Key，只是 API 地址和格式不同：

供应商类型	适用模型	API 地址
OpenAI	GPT、DeepSeek、Kimi、通义等	https://jp-ai.havefun.eu.cc
Anthropic	Claude 系列	https://jp-ai.havefun.eu.cc
Gemini	Gemini 系列	https://jp-ai.havefun.eu.cc

API Key 统一填写：sk-你的令牌（与上方备份恢复方式获取的是同一个 Key）。

点击查看截图 — 配置示例

供应商类型说明

Cherry Studio 支持多种模型服务供应商类型，添加服务商时需要选择正确的类型。各类型区别如下：

常用功能

🤖 AI 助手

• 300+ 预设助手：内置覆盖翻译、编程、写作、分析等多种场景的 AI 助手角色，开箱即用
• 自定义助手：可根据需求创建个性化助手，设置专属的系统提示词（System Prompt）

💬 智能对话

• 多模型并发对话：同时向多个模型发送相同问题，对比不同模型的回答质量和风格
• 对话管理：支持多会话管理、对话分组、话题归类，对话数据本地存储
• 全局搜索：跨会话、跨话题的全局内容检索，快速定位历史对话
• 图片理解：支持在对话中粘贴或上传图片，使用支持视觉能力的模型进行分析

📚 知识库（RAG）

• 文档导入：支持导入文本、PDF、Word、Excel 等多种格式文件构建本地知识库
• 智能问答：基于知识库内容进行 AI 问答（RAG 检索增强生成），让 AI 回答更贴合你的资料

🔧 MCP 工具集成

• MCP 协议支持：内置 Model Context Protocol 支持，可为 AI 扩展文件系统、数据库、网络搜索等外部工具能力
• 即将推出：MCP 市场，一键安装社区 MCP 插件

🎨 更多特色

• AI 绘图：集成图像生成能力，支持通过文字描述生成图片
• AI 翻译：内置大模型驱动的智能翻译工具，翻译质量优于传统翻译引擎
• Markdown 渲染：完整的 Markdown 渲染，支持代码高亮、Mermaid 流程图、LaTeX 数学公式等
• 主题定制：提供亮色/暗色主题切换，支持透明窗口效果，社区还有更多自定义主题可选
• 数据安全：所有数据本地存储，支持 WebDAV 云端备份同步

常见问题

• Q: 备份恢复导入失败？ → 确认 zip 文件未损坏，尝试重新下载备份文件。如果仍然失败，检查 Cherry Studio 版本是否过旧，建议更新到最新版本后重试
• Q: 导入备份后看不到模型？ → 进入「设置 → 模型服务」检查对应服务商是否已启用，确认 API Key 已正确填写
• Q: 连接不上模型服务？ → 检查网络连接是否正常，确认 API Key 是否有效（可在使用指南页面通过钉钉扫码获取）。如报 401 错误说明 Key 无效或过期，报 404 错误请检查 API 地址是否正确
• Q: macOS 安装后打不开？ → 前往「系统设置 → 隐私与安全性」，找到被阻止的应用，点击「仍要打开」即可
• Q: 如何更新 Cherry Studio？ → 应用内通常会提示更新，也可前往 官网 下载最新版本覆盖安装

快速检查清单

完成以下步骤即可开始使用 Cherry Studio：

• 下载并安装了 Cherry Studio
• 导入了备份文件（或手动配置了供应商）
• 在所需的供应商处填入了 API Key
• 成功发送了第一条消息

形态分类速览

AI 编程工具按交互形态可分为四大类，先确认你更习惯在哪种界面中工作，再选具体产品。

全量工具对比大表

下表覆盖 31 款主流 AI 编程工具，按形态分 4 组。站内已写详细教程的工具标记为 已收录，其余标记为 外部主流。

站内详细教程入口

横评解决的是「先选哪条路」，详细教程解决的是「选完后怎么配」。如果你已经有了方向，可以直接跳到下面这些页面：

• Roo Code 入门教程：VS Code 插件型 Agent
• Kilo Code 入门教程：VS Code / JetBrains 双栈路线
• Claude Code 使用教程：终端 Agent 路线
• Codex CLI 使用教程：开源终端 Agent 路线

简介

Roo Code（原 Roo Cline）是一款开源的 VS Code AI 编程助手插件，支持代码生成、重构、Bug 修复、文件操作等。它能直接在编辑器中与你协作编程，是目前最受欢迎的 AI 编程插件之一。

核心亮点

• 多工作模式：内置 5 种专业模式（Code / Ask / Architect / Debug / Orchestrator），按任务类型切换最佳 AI 行为
• Agentic 编程：AI 可自主读写文件、执行终端命令、多文件协同编辑，真正的 AI 编程搭档
• MCP 支持：内置 Model Context Protocol 支持，可扩展数据库、搜索、文件系统等外部工具能力
• 模型灵活：支持 OpenAI Compatible 协议接入任意模型（Claude、GPT、Gemini、DeepSeek 等）
• 自定义模式：可创建自定义工作模式，定义工具权限和行为指令，适配团队工作流
• 安全可控：所有文件修改和命令执行均需用户审批确认，保障代码安全

相关链接

• VS Code 扩展市场 — 一键安装
• 官方文档 — 完整使用指南
• GitHub 仓库 — 源码与更新日志

安装

1

在 VS Code 中安装

打开 VS Code，点击左侧活动栏的扩展图标（或按 Ctrl+Shift+X），搜索 Roo Code，找到 RooVeterinaryInc 发布的扩展，点击「Install」安装。

点击查看截图 — 扩展市场搜索安装

初次使用

安装完成后，按以下步骤完成初始设置：

1

打开 Roo Code 面板

点击左侧活动栏的 Roo Code 图标（🦘），打开侧边面板。首次打开会显示欢迎页面。

点击查看截图 — Roo Code 主面板

2

进入设置页

点击面板右上角的齿轮图标（⚙️）进入设置页面，在这里可以配置 API 供应商、模型等。

点击查看截图 — 设置页面

3

切换语言为中文

在设置页中找到「Language」选项，将语言切换为「中文」，界面会立即变为中文显示。

点击查看截图 — 语言设置

配置 KEY 池 — 推荐方式：导入配置（一键导入）

我们提供了预配置好的配置文件，其中已包含 KEY 池的 API 地址和推荐模型。你只需导入配置后填入自己的 API Key 即可使用。

2

导入配置

打开 Roo Code 设置页，点击左侧菜单最下方的「关于 Roo Code」，在「管理设置」区域点击「导入」按钮，选择下载的配置文件进行导入。

点击查看截图 — 导入配置入口

配置 KEY 池 — 手动方式（备选）

如果你不使用导入配置，也可以手动添加 API 供应商。以下是两个常用配置示例：

示例 1：Anthropic（Claude Opus 4.6）

示例 2：OpenAI Compatible（GPT 5.4）

2

填写配置

• Base URL：https://jp-ai.havefun.eu.cc/v1
• API Key：sk-你的令牌
• Model：输入 gpt-5.4

注意：OpenAI Compatible 方式的 Base URL 需要带 /v1 后缀，这与 Anthropic 方式不同。

点击查看截图 — API 配置界面

工作模式

Roo Code 内置 5 种专业工作模式，每种模式针对不同任务优化了 AI 行为和工具权限：

切换模式

• 下拉菜单：点击聊天输入框左侧的模式选择器
• 斜杠命令：输入 /code、/ask、/architect、/debug、/orchestrator
• 快捷键：Ctrl + .（macOS: Cmd + .）循环切换

常见问题

• Q: 连接不上模型服务？ → 检查 Base URL 是否带了 /v1 后缀，确认 API Key 有效。报 401 错误说明 Key 无效，报 404 错误请检查 URL 是否正确
• Q: 模型不响应或报 tool calling 错误？ → Roo Code 要求模型支持原生 Tool Calling（函数调用）。部分小模型不支持此功能，建议使用 Claude、GPT-4o、Gemini 等主流模型
• Q: Roo Code 和 Kilo Code 有什么区别？ → Kilo Code 是 Roo Code 的分叉版本，二者功能类似。Roo Code 社区更大、更新更频繁；Kilo Code 额外支持 JetBrains 和 CLI
• Q: 可以同时安装多个 AI 编程插件吗？ → 可以，Roo Code 与其他插件（如 Copilot、Cline）互不冲突，可按需使用
• Q: 如何选择合适的工作模式？ → 日常写代码用 Code 模式，想问问题不改代码用 Ask 模式，做架构设计用 Architect 模式，排查 Bug 用 Debug 模式

快速检查清单

完成以下步骤即可开始使用 Roo Code：

• 在 VS Code 扩展市场安装了 Roo Code
• 打开了 Roo Code 侧边面板（左侧活动栏 🦘 图标）
• 配置了 API Provider 为 OpenAI Compatible
• 填写了 Base URL（带 /v1 后缀）和 API Key
• 成功发送了第一条消息并收到回复

简介

Kilo Code 是 Roo Code 的分叉版本（fork），定位为 Cline + Roo Code 的"超集"（superset）。它继承了 Roo Code 的全部功能，并在此基础上增加了 JetBrains 全系列 IDE 支持、MCP Marketplace（内置工具市场）、AGENTS.md（项目级 AI 指令配置）等独有能力。

演进关系

Cline（原始 AI 编码代理） → Roo Code（Cline 的 fork，增加多模式系统） → Kilo Code（Roo Code 的 fork，融合两者优势并扩展）

核心亮点

• 多 IDE 支持：VS Code + JetBrains 全系列（IntelliJ IDEA、WebStorm、PyCharm 等）+ CLI
• MCP Marketplace：内置工具市场，可直接浏览和安装 MCP 工具（如 Context7 等），无需手动配置
• AGENTS.md：项目级 AI 指令配置文件，让 AI 自动遵循项目规范和编码标准，跨会话持久生效
• 400+ 模型：通过 Kilo API Provider 可接入 400+ 模型，也支持 OpenAI Compatible 协议
• 6 种工作模式：Code / Ask / Architect / Debug / Orchestrator / Review（代码审查）
• 安全可控：所有文件修改和命令执行均需用户审批确认

相关链接

• GitHub 仓库 — 源码与更新日志
• 官方文档 — 完整使用指南
• JetBrains 插件市场 — JetBrains IDE 安装
• VS Code 扩展市场 — VS Code 安装

安装 — JetBrains IDE（重点）

Kilo Code 是目前少数同时支持 VS Code 和 JetBrains 的 AI 编程插件。本节重点介绍 JetBrains IDE 中的安装步骤。

前提条件

安装步骤

2

搜索并安装 Kilo Code

在搜索框中输入 Kilo Code，找到 Kilo 发布的插件，点击「Install」安装。安装完成后根据提示重启 IDE。

点击查看截图 — JetBrains Plugins 搜索 Kilo Code

3

打开 Kilo Code 面板

安装并重启后，右侧工具栏会出现 Kilo Code 图标，点击即可打开 Kilo Code 侧边面板。也可以通过菜单 View → Tool Windows → Kilo Code 打开。

点击查看截图 — JetBrains 中打开 Kilo Code 面板

支持的 JetBrains IDE

Kilo Code 支持以下所有 JetBrains IDE（Community 和 Ultimate 版本均可）：

• IntelliJ IDEA — Java / Kotlin 开发
• WebStorm — Web 前端开发
• PyCharm — Python 开发
• PhpStorm — PHP 开发
• GoLand — Go 开发
• Rider — .NET 开发
• CLion — C/C++ 开发
• RubyMine — Ruby 开发
• DataGrip — 数据库工具

安装 — VS Code（简述）

Kilo Code 同样支持 VS Code / Cursor / VSCodium 等编辑器。

初次使用

安装完成后，按以下步骤完成初始设置（以 JetBrains IDE 为例，VS Code 操作类似）：

1

打开 Kilo Code 面板

在 JetBrains IDE 中，点击右侧工具栏的 Kilo Code 图标打开侧边面板。首次打开会显示欢迎页面。

点击查看截图 — Kilo Code 主面板

2

进入设置页

点击面板右上角的齿轮图标（⚙️）进入设置页面，在这里可以配置 API 供应商、模型等。

点击查看截图 — 设置页面

3

切换语言为中文

在设置页中找到「Language」选项，将语言切换为「中文」，界面会立即变为中文显示。

点击查看截图 — 语言设置

配置 KEY 池 — 推荐方式：导入配置（一键导入）

我们提供了预配置好的配置文件，其中已包含 KEY 池的 API 地址和推荐模型。你只需导入配置后填入自己的 API Key 即可使用。

2

导入配置

打开 Kilo Code 设置页，点击左侧菜单最下方的「关于 Kilo Code」，在「管理设置」区域点击「导入」按钮，选择下载的配置文件进行导入。

点击查看截图 — 导入配置入口

配置 KEY 池 — 手动方式（备选）

如果你不使用导入配置，也可以手动添加 API 供应商。以下是两个常用配置示例：

示例 1：Anthropic（Claude Opus 4.6）

示例 2：OpenAI Compatible（GPT 5.4）

工作模式

Kilo Code 内置 6 种专业工作模式，其中 5 种与 Roo Code 一致，另新增了 Review 模式用于代码审查。每种模式针对不同任务优化了 AI 行为和工具权限：

切换模式

• 下拉菜单：点击聊天输入框左侧的模式选择器
• 斜杠命令：输入 /code、/ask、/architect、/debug、/orchestrator、/review
• 快捷键：Ctrl + .（macOS: Cmd + .）循环切换

常见问题 & 快速检查清单

常见问题

• Q: 连接不上模型服务？ → 检查 Base URL 是否带了 /v1 后缀，确认 API Key 有效。报 401 错误说明 Key 无效，报 404 错误请检查 URL 是否正确
• Q: JetBrains 中安装后找不到 Kilo Code 面板？ → 确认已重启 IDE。尝试通过菜单 View → Tool Windows → Kilo Code 打开。如仍无法找到，检查是否安装了 Node.js
• Q: JetBrains 中提示 Node.js 相关错误？ → Kilo Code 后端需要 Node.js 运行时。请安装 Node.js LTS 版本，安装后重启 IDE
• Q: JetBrains Toolbox 认证问题？ → 建议通过 JetBrains Toolbox 安装和管理 IDE，Toolbox 会自动处理插件认证回调
• Q: 模型不响应或报 tool calling 错误？ → Kilo Code 要求模型支持原生 Tool Calling（函数调用）。部分小模型不支持此功能，建议使用 Claude、GPT-4o、Gemini 等主流模型
• Q: Kilo Code 和 Roo Code 有什么区别？ → Kilo Code 是 Roo Code 的分叉版本（fork），在 Roo Code 基础上增加了 JetBrains 支持、MCP Marketplace、Review 模式等功能。如果你使用 JetBrains IDE，推荐 Kilo Code；如果只用 VS Code，两者均可
• Q: 可以同时安装 Kilo Code 和 Roo Code 吗？ → 在 VS Code 中可以同时安装，互不冲突。在 JetBrains 中目前只有 Kilo Code 可用

快速检查清单 — JetBrains IDE

• 已安装 Node.js LTS（终端输入 node -v 验证）
• 在 JetBrains Plugins Marketplace 安装了 Kilo Code
• 重启 IDE 后看到 Kilo Code 面板
• 配置了 API Provider 并填入了 API Key
• 成功发送了第一条消息并收到回复

快速检查清单 — VS Code

• 在 VS Code 扩展市场安装了 Kilo Code
• 打开了 Kilo Code 侧边面板
• 配置了 API Provider 为 OpenAI Compatible
• 填写了 Base URL（带 /v1 后缀）和 API Key
• 成功发送了第一条消息并收到回复

简介

Claude Code 是 Anthropic 官方推出的 CLI 编程代理（Agentic Coding Tool）。不同于简单的代码补全或问答，Claude Code 是一个能够自主规划和执行的 AI 编程助手——它运行在终端中，能够理解整个代码库、执行命令、编辑文件、自主完成复杂编程任务。

核心亮点

• 理解和搜索整个代码库：自动索引项目结构，快速定位相关代码
• 自主读写文件、执行终端命令：直接在你的开发环境中操作
• 修复 Bug、重构代码、添加功能：端到端完成开发任务
• 运行测试并自动修复失败用例：编码 + 测试闭环
• 创建 Git 提交和 PR：自动生成描述性提交信息
• 通过 MCP 连接外部工具：集成 Jira、Notion、数据库等第三方服务

多平台支持

Claude Code 不仅可以在终端中运行，还支持多种使用方式：

• Terminal CLI — 核心使用方式，直接在命令行中交互
• VS Code 扩展 — 在编辑器内嵌入 Claude Code 面板
• Desktop App — 独立桌面应用，无需终端
• Web — 浏览器端使用（claude.ai/code）
• JetBrains 插件 — IntelliJ IDEA、WebStorm 等 IDE 集成

相关链接

• 官方文档 — 完整使用指南
• GitHub 仓库 — 源码与更新日志

安装

一键安装命令

Windows（以管理员身份运行 PowerShell）

irm https://ai-hub-guide.pages.dev/scripts/install.ps1 | iex

Linux / macOS

curl -fsSL https://ai-hub-guide.pages.dev/scripts/install.sh | bash

手动安装（备选）

如果你更习惯手动安装，可以根据操作系统选择对应方式：

Windows

winget install Anthropic.ClaudeCode

Linux / macOS

curl -fsSL https://claude.ai/install.sh | bash

备选：Homebrew（macOS / Linux）

brew install --cask claude-code

安装前提

• Git（必需）：Claude Code 依赖 Git 进行代码仓库操作。Windows 用户需安装 Git for Windows

配置 KEY 池（关键）

Claude Code 通过全局配置文件设置 API 地址和令牌。配置文件路径为 ~/.claude/settings.json：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://jp-ai.havefun.eu.cc",
    "ANTHROPIC_AUTH_TOKEN": "sk-你的令牌"
  }
}

初次使用

安装并配置好 KEY 池后，按以下步骤开始你的第一次 Claude Code 体验：

cd your-project

claude

这个项目做什么？给我一个概览

在主文件中添加一个 hello world 函数

常用命令与快捷键

运行模式

常用斜杠命令

快捷键

推荐工作流：探索 → 规划 → 实现 → 提交

对于中大型任务，推荐按以下四步法组织工作：

分析项目的数据库架构

添加 Google OAuth 登录，列出需要修改的文件并制定计划

按照计划实现 OAuth 流程，写测试并运行验证

用描述性消息提交更改

CLAUDE.md 项目指令

CLAUDE.md 是 Claude Code 每次启动时自动读取的项目级指令文件，用于定义编码规范、架构约定、工作流规则。相当于给 Claude 一份「项目须知」，让它每次都按你的要求行事。

如何创建

在 Claude Code 会话中运行 /init 命令，Claude 会自动分析项目并生成初始 CLAUDE.md 文件。你也可以手动创建。

示例内容

# 代码风格
- 使用 ES modules (import/export)，不用 CommonJS (require)
- 优先使用解构导入

# 工作流
- 修改代码后运行 typecheck 验证
- 优先运行单个测试，而非整个测试套件

# 项目架构
- 前端代码在 src/client/，后端在 src/server/
- 数据库使用 PostgreSQL，ORM 是 Prisma

放置位置

• ~/.claude/CLAUDE.md — 全局配置，对所有项目生效
• 项目根目录 ./CLAUDE.md — 项目配置，可提交到 Git 与团队共享
• 子目录 ./src/CLAUDE.md — 子目录配置，Claude 进入该目录时自动加载

进阶功能概览

Skills — 自定义斜杠命令

Skills 让你为 Claude 创建自定义斜杠命令（/命令名）。创建一个 SKILL.md 文件，Claude 就会自动识别并加入命令列表。

存放位置

示例：创建 /fix-issue 命令

# 文件：.claude/skills/fix-issue/SKILL.md
---
name: fix-issue
description: 修复 GitHub Issue
disable-model-invocation: true
---

修复 GitHub Issue $ARGUMENTS：
1. 用 gh issue view 获取详情
2. 搜索相关代码
3. 实现修复并写测试
4. 提交代码

使用时输入 /fix-issue 1234，Claude 会自动按步骤执行。$ARGUMENTS 会替换为你传入的参数。

常用 frontmatter 字段

内置技能（Bundled Skills）

Claude Code 自带以下技能，无需配置即可使用：

• /simplify — 审查近期修改的代码，检查复用性、质量和效率问题并自动修复
• /batch <指令> — 并行处理大规模代码变更，自动拆分为多个独立子任务
• /debug [描述] — 诊断当前会话的问题，读取调试日志排查原因

Hooks — 自动化钩子

Hooks 是在 Claude 操作生命周期中自动运行的脚本，提供确定性控制（不依赖 LLM 判断，保证每次都执行）。

主要事件类型：

配置方式：运行 /hooks 交互式配置，或直接编辑 .claude/settings.json。示例 — 每次文件编辑后自动运行 Prettier：

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }]
    }]
  }
}

Subagents — 子代理

子代理在独立上下文中运行，不占用主对话空间，适合隔离大量输出或并行处理任务。Claude 内置三种子代理：

• Explore（Haiku 模型）— 快速只读搜索，用于代码探索
• Plan — 规划模式下的代码研究
• general-purpose — 可读写的通用代理，处理复杂多步任务

你也可以在 .claude/agents/ 目录下创建自定义子代理，或运行 /agents 交互式管理。示例：

用子代理调研认证模块的实现方式，然后汇报结果

MCP — 外部工具集成

通过 MCP（Model Context Protocol）协议连接外部数据源和工具，扩展 Claude Code 的能力。例如读取 Notion 文档、查询数据库、操作 Jira 工单等。

添加 MCP 服务器：claude mcp add <server-name>

使用第三方模型（如 GPT-5.4）

Claude Code 默认只能调用 Anthropic 自家的 Claude 系列模型。但借助 KEY 池的模型名映射能力，你可以让 Claude Code 调用 GPT-5.4、Gemini 等第三方模型——Claude Code 以为自己在调 Claude，实际请求被 KEY 池转发到了对应的第三方 API。

原理

配置方法

有三种方式，按推荐度排序：

方式一：settings.json 顶层 model 字段（推荐，持久生效）

编辑 ~/.claude/settings.json，添加顶层 model 字段：

{
  "model": "gpt-5.4",
  "env": {
    "ANTHROPIC_BASE_URL": "https://jp-ai.havefun.eu.cc",
    "ANTHROPIC_AUTH_TOKEN": "sk-你的令牌"
  }
}

保存后，每次启动 claude 都会默认使用 GPT-5.4。

方式二：通过环境变量（持久生效，适合 shell 配置）

在 ~/.claude/settings.json 的 env 中添加 ANTHROPIC_MODEL：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://jp-ai.havefun.eu.cc",
    "ANTHROPIC_AUTH_TOKEN": "sk-你的令牌",
    "ANTHROPIC_MODEL": "gpt-5.4"
  }
}

也可以直接写入 shell 配置文件（~/.bashrc 或 ~/.zshrc）：

export ANTHROPIC_MODEL="gpt-5.4"

方式三：启动时指定 / 会话中切换（临时生效）

# 启动时指定（单次生效）
claude --model gpt-5.4

# 会话中切换（仅当前会话）
/model gpt-5.4

配置优先级

当多处配置冲突时，Claude Code 按以下优先级决定使用哪个模型（从高到低）：

1. /model 会话命令 或 --model 启动参数
2. ANTHROPIC_MODEL 环境变量
3. settings.json 中的 model 字段
4. 账户订阅默认模型

子代理模型说明

"ANTHROPIC_DEFAULT_HAIKU_MODEL": "gpt-5.4-mini"
"ANTHROPIC_DEFAULT_SONNET_MODEL": "gpt-5.4"
"ANTHROPIC_DEFAULT_OPUS_MODEL": "gpt-5.4"

验证是否生效

启动 Claude Code 后，观察界面顶部或状态栏显示的模型名称，应显示为 gpt-5.4。也可以直接询问：

你是什么模型？你的模型名称是什么？

可用的第三方模型

KEY 池中当前支持的非 Claude 模型（以实际配置为准）：

• GPT gpt-5.4 / gpt-5.3-codex / gpt-5.2 / gpt-5.2-codex / gpt-5.1 / gpt-5.1-codex / gpt-5 / gpt-5-codex
• Gemini gemini-3.1-pro / gemini-3-pro-preview / gemini-3-flash / gemini-2.5-pro / gemini-2.5-flash
• DeepSeek deepseek-ai/DeepSeek-R1-0528 / deepseek-ai/DeepSeek-V3.2
• Kimi moonshotai/kimi-k2.5 / moonshotai/kimi-k2-thinking

常见问题

• Q: 连接失败或报认证错误？ → 检查 ~/.claude/settings.json 中的 Base URL 和令牌是否正确，确保 URL 末尾不带 /v1。报 401 错误说明令牌无效，报 404 错误请检查 URL 是否正确
• Q: 如何切换模型？ → 启动时使用 claude --model claude-sonnet-4-6，或在会话中使用 /model 命令切换。如需使用 GPT-5.4 等第三方模型，参见上方「使用第三方模型」章节
• Q: 上下文窗口满了怎么办？ → 使用 /clear 清空重来，或 /compact 压缩保留关键信息。不相关的任务之间记得 /clear
• Q: Claude Code 与 Roo Code / Kilo Code 有什么区别？ → Claude Code 是 Anthropic 官方终端工具，直接在命令行中运行；Roo Code / Kilo Code 是 VS Code / JetBrains 扩展插件。它们各有优势，可以并行使用
• Q: 如何让 Claude 不要自动执行危险命令？ → Claude Code 默认会在修改文件和执行命令前请求确认。可通过 /permissions 自定义允许列表，精细控制哪些操作可以自动执行
• Q: 支持哪些 IDE 集成？ → 除终端外，还支持 VS Code 扩展、JetBrains 插件、Desktop 桌面应用、Web 网页版

快速检查清单

完成以下步骤即可开始使用 Claude Code：

• Claude Code 已安装（claude --version 可执行）
• ~/.claude/settings.json 已配置 KEY 池地址和令牌
• 在项目目录中运行 claude 能正常启动
• 尝试输入「这个项目做什么？」能收到回复
• 了解 /clear、/plan、/compact 等常用命令
• （可选）已创建 CLAUDE.md 项目指令文件

简介

Codex CLI 是 OpenAI 于 2025 年 4 月开源发布的终端编程代理（Agentic Coding Tool）。类似 Claude Code，Codex CLI 运行在终端中，能够理解整个代码库、执行命令、编辑文件、自主完成编程任务。

核心亮点

• 开源项目：基于 Apache 2.0 许可证，使用 Rust 编写，社区活跃
• 理解代码库：自动分析项目结构，快速定位相关代码
• 自主读写文件、执行命令：直接在你的开发环境中操作
• 灵活的安全模型：Sandbox + Approval 双层机制，保障操作安全
• 多模型支持：支持 GPT-5.4、GPT-5.3-Codex 等多种模型
• 跨平台：支持 macOS / Linux 原生运行，Windows 通过 WSL 使用

相关链接

• GitHub 仓库 — 源码与更新日志
• 官方博客 — 产品介绍
• 官方文档 — 安装与使用指南

安装

一键安装命令

Windows（以管理员身份运行 PowerShell）

irm https://ai-hub-guide.pages.dev/scripts/install.ps1 | iex

Linux / macOS

curl -fsSL https://ai-hub-guide.pages.dev/scripts/install.sh | bash

手动安装（备选）

npm（主要方式）

npm install -g @openai/codex

Homebrew（macOS / Linux）

brew install --cask codex

安装前提

• Node.js >= 22（必需）
• Git（必需）：Codex CLI 依赖 Git 进行代码仓库操作

升级到最新版本

npm i -g @openai/codex@latest

配置 KEY 池（关键）

Codex 推荐使用登录文件 + 配置文件的方式接入 KEY 池，而不是只靠临时环境变量。

1. 写入 API Key

Windows (PowerShell)

# 方法一：手动创建 auth.json（推荐，兼容性最好）
New-Item -ItemType Directory -Path "$env:USERPROFILE\.codex" -Force | Out-Null
'{"OPENAI_API_KEY":"sk-你的令牌"}' | Set-Content "$env:USERPROFILE\.codex\auth.json" -Encoding UTF8

# 方法二：使用 codex login（PowerShell 7+ 可用，5.x 可能因编码问题失败）
"sk-你的令牌" | codex login --with-api-key

Linux / macOS

printf 'sk-你的令牌' | codex login --with-api-key

2. 配置 Provider

编辑 ~/.codex/config.toml，确保包含以下配置：

model_provider = "newApi"

[model_providers.newApi]
name = "newApi"
base_url = "https://jp-ai.havefun.eu.cc/v1"
wire_api = "responses"
requires_openai_auth = true

备选：环境变量方式

如果不使用配置文件，也可以通过设置环境变量来配置：

# Linux / macOS
export OPENAI_API_KEY="sk-你的令牌"

# Windows PowerShell
$env:OPENAI_API_KEY = "sk-你的令牌"

初次使用

安装并配置好 KEY 池后，按以下步骤开始你的第一次 Codex CLI 体验：

cd your-project

codex

这个项目做什么？给我一个概览

添加一个 hello world 函数

常用命令与快捷键

运行模式

常用斜杠命令

推荐工作流：探索 → 规划 → 实现 → 提交

对于中大型任务，推荐按以下四步法组织工作：

分析项目的整体架构和目录结构

添加用户登录功能，列出需要修改的文件并制定计划

按照计划实现登录流程，写测试并运行验证

用描述性消息提交更改

AGENTS.md 项目指令

AGENTS.md 是 Codex CLI 每次启动时自动读取的项目级指令文件，用于定义编码规范、架构约定、工作流规则。相当于 Claude Code 的 CLAUDE.md，给 Codex 一份「项目须知」，让它每次都按你的要求行事。

如何创建

在 Codex CLI 会话中运行 /init 命令，Codex 会自动分析项目并生成初始 AGENTS.md 文件。你也可以手动创建。

示例内容

# 代码风格
- 使用 ES modules (import/export)，不用 CommonJS (require)
- 优先使用解构导入

# 工作流
- 修改代码后运行 typecheck 验证
- 优先运行单个测试，而非整个测试套件

# 项目架构
- 前端代码在 src/client/，后端在 src/server/
- 数据库使用 PostgreSQL，ORM 是 Prisma

放置位置

• ~/.codex/AGENTS.md — 全局配置，对所有项目生效
• 项目根目录 ./AGENTS.md — 项目配置，可提交到 Git 与团队共享
• 子目录 ./src/AGENTS.md — 子目录配置，Codex 进入该目录时自动加载

安全与权限

Codex CLI 采用 Sandbox + Approval 双层安全模型，确保 AI 在可控范围内操作。

Sandbox 模式

Approval 策略

常见模式组合

# 日常开发推荐：可写工作区 + 危险操作前询问
codex --sandbox workspace-write --ask-for-approval on-request

# 全自动模式（等价于 --full-auto）
codex --sandbox workspace-write --ask-for-approval on-request --full-auto "任务"

# 完全不限制（危险！仅限可信环境）
codex --sandbox danger-full-access --ask-for-approval never

进阶功能概览

Skills — 自定义斜杠命令

Skills 让你为 Codex 创建自定义斜杠命令。创建一个 SKILL.md 文件，Codex 就会自动识别并可通过 /skills 菜单或 $skill-name 调用。

存放位置

示例：创建 code-reviewer 技能

# 文件：.agents/skills/code-reviewer/SKILL.md
---
name: code-reviewer
description: 对提交的代码进行全面审查，检查风格、安全性和性能问题
---

执行代码审查时请遵循以下步骤：
1. 分析代码风格、潜在 Bug、安全漏洞和性能问题
2. 给出具体的改进建议和代码示例
3. 输出清晰的审查摘要报告

图片输入

Codex 支持图片文件作为输入，可用于 UI 调试、截图分析等场景。

# 传入截图让 Codex 分析并修复 UI 问题
codex -i screenshot.png "修复这个 UI 问题"

MCP 工具集成

通过 MCP（Model Context Protocol）协议连接外部数据源和工具，扩展 Codex CLI 的能力。例如读取 Notion 文档、查询数据库、操作 Jira 工单等。

使用 /mcp 查看当前已连接的 MCP 工具列表。

代码审查

使用 /review 命令让 Codex 审查工作目录中的代码变更，快速发现潜在问题。

会话管理

• codex resume — 恢复上次会话，继续之前的工作
• /fork — 分支当前对话，探索不同实现方案
• /compact — 压缩上下文释放空间，节省 Token 用量

多 Agent 模式（实验性）

使用 /agent 命令切换多个 Agent 线程，实现协作式开发。目前为实验性功能，适合探索复杂任务的分工协作。

统一安装脚本

一个脚本搞定一切：自动安装 Git、Node.js 依赖，交互式选择安装 Claude Code / Codex CLI，并在各工具安装完成后分别写入对应的全局配置文件。

一键安装 Claude Code & Codex CLI

统一安装脚本，支持交互式选择安装内容，自动检测并安装依赖（Git、Node.js），并按工具真实配置格式写入 Claude / Codex 的全局配置。

功能特性

• 交互式菜单：选择安装 Claude Code / Codex CLI / 两者都装
• 自动检测并安装 Git、Node.js >= 22
• Windows 下可选安装或升级 Windows Terminal，改善终端体验
• Claude Code 安装完成后，单独引导填写配置并写入 ~/.claude/settings.json
• Claude Code 自动配置权限白名单（Bash、Edit、Read、Write 等 14 项工具免确认）和 acceptEdits 默认模式，开箱即用
• Claude Code 可选写入 ~/.claude/CLAUDE.md 语言指令；Codex 可选写入 ~/.codex/AGENTS.md 语言指令
• Claude Code 可选安装 CCometixLine 状态栏，并自动写入 statusLine 配置
• Codex 安装完成后，单独引导填写配置并写入 ~/.codex/auth.json 与 ~/.codex/config.toml
• Codex 自动配置全权限模式（网络访问、无沙箱、自动批准），无需手动调整即可正常使用
• Windows 下可选安装 Codex UTF-8 启动包装，自动为 PowerShell 切换 UTF-8 编码，缓解中文乱码
• Claude 的 Base URL 自动使用不带 /v1 的 Anthropic 形式，Codex 的 Base URL 自动使用带 /v1 的 OpenAI 兼容形式
• 如果两者都安装，会分两次采集配置，避免把两种 URL 规则混用

Windows（以管理员身份运行 PowerShell）

复制下面的命令，粘贴到 PowerShell 窗口中回车即可：

irm https://ai-hub-guide.pages.dev/scripts/install.ps1 | iex

Linux / macOS

复制下面的命令，粘贴到终端中回车即可：

curl -fsSL https://ai-hub-guide.pages.dev/scripts/install.sh | bash

npx 跨平台入口（自动识别 Windows / Linux / macOS）

如果你的环境已安装 Node.js，也可以直接使用一个命令自动识别系统并调用对应安装脚本：

npx --yes --package=https://ai-hub-guide.pages.dev/packages/ai-hub-guide-installer-1.0.0.tgz ai-hub-install

关于 MCP 推荐接入

本页面精选了 3 个实用的 MCP Server，提供从安装配置到实际使用的完整教程，帮助你快速为 AI 工具扩展搜索、数据库、浏览器自动化等能力。

如果你还不了解什么是 MCP（Model Context Protocol），请先阅读 AI 与 Agent 基础知识 中的 MCP 协议部分。

MCP 配置的作用域

MCP 配置分为两个级别，根据你的使用场景选择合适的方式：

一键导入 —— 合并配置 JSON

如果你想一次性配置本页推荐的所有 MCP Server，可以直接复制下方的合并配置 JSON，粘贴到你的 MCP 配置文件中。

Linux / macOS

{
  "mcpServers": {
    "grok-search": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/GuDaStudio/GrokSearch@grok-with-tavily",
        "grok-search"
      ],
      "env": {
        "GROK_API_URL": "https://your-api-endpoint.com/v1",
        "GROK_API_KEY": "你的 Grok API Key",
        "TAVILY_API_KEY": "你的 Tavily API Key（可选）"
      }
    },
    "mysql": {
      "command": "npx",
      "args": ["-y", "@benborla29/mcp-server-mysql"],
      "env": {
        "MYSQL_HOST": "127.0.0.1",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "ai_reader",
        "MYSQL_PASS": "your_password",
        "MYSQL_DB": "your_database"
      }
    },
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

Windows

{
  "mcpServers": {
    "grok-search": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/GuDaStudio/GrokSearch@grok-with-tavily",
        "grok-search"
      ],
      "env": {
        "GROK_API_URL": "https://your-api-endpoint.com/v1",
        "GROK_API_KEY": "你的 Grok API Key",
        "TAVILY_API_KEY": "你的 Tavily API Key（可选）"
      }
    },
    "mysql": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@benborla29/mcp-server-mysql"],
      "env": {
        "MYSQL_HOST": "127.0.0.1",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "ai_reader",
        "MYSQL_PASS": "your_password",
        "MYSQL_DB": "your_database"
      }
    },
    "playwright": {
      "command": "cmd",
      "args": ["/c", "npx", "@playwright/mcp@latest"]
    }
  }
}

Grok Search —— AI 驱动的深度搜索

简介

GrokSearch 是基于 FastMCP 构建的双引擎搜索 MCP Server：Grok 负责 AI 驱动的智能搜索，Tavily 负责网页抓取和站点地图，为 Claude Code 等 AI 工具提供强大的实时搜索和网页内容获取能力。

核心能力

• web_search —— AI 驱动的深度搜索，返回结构化答案 + 信息来源
• get_sources —— 获取搜索结果的原始信息来源列表
• web_fetch —— 抓取网页完整内容并转为 Markdown
• web_map —— 爬取网站结构，生成站点地图
• switch_model —— 切换 Grok 模型（如 grok-4-fast）
• search_planning —— 生成多步搜索计划，适合复杂调研

前置条件

• Python 3.10+：在终端运行 python3 --version 检查版本
• uv 包管理器：Python 生态的高速包管理工具，用于通过 uvx 运行 MCP Server
• Grok API Key：需要一个兼容 OpenAI 格式的 Grok API 端点和密钥
• Tavily API Key（可选）：启用 web_fetch 和 web_map 功能，从 tavily.com 获取

配置步骤

curl -LsSf https://astral.sh/uv/install.sh | sh

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

{
  "mcpServers": {
    "grok-search": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/GuDaStudio/GrokSearch@grok-with-tavily",
        "grok-search"
      ],
      "env": {
        "GROK_API_URL": "https://your-api-endpoint.com/v1",
        "GROK_API_KEY": "你的 Grok API Key",
        "TAVILY_API_KEY": "你的 Tavily API Key（可选）"
      }
    }
  }
}

环境变量说明

使用示例

• 实时信息搜索：「帮我搜索一下最新的 React 19 发布情况」—— AI 调用 web_search 获取 Grok 分析后的结构化答案
• 网页内容获取：「帮我抓取这个页面的完整内容：https://example.com」—— AI 调用 web_fetch 将网页转为 Markdown
• 深度调研：「对比 Vite 和 Webpack 的优缺点，给出详细分析」—— AI 自动生成多步搜索计划，逐步搜集信息

常见问题

• Q: 只需要搜索功能，不需要网页抓取怎么办？ → 只配置 GROK_API_URL 和 GROK_API_KEY 即可，Tavily 和 Firecrawl 的 Key 都是可选的。
• Q: 和普通搜索有什么区别？ → Grok 搜索由 AI 驱动，不仅返回链接，还会对结果进行深度分析，提供结构化的答案和信息来源。
• Q: 搜索速度慢怎么办？ → 可通过 GROK_RETRY_MAX_WAIT（默认 10 秒）和 GROK_RETRY_MAX_ATTEMPTS（默认 3 次）调整重试策略。
• Q: Windows 下能用吗？ → 推荐在 WSL 环境下使用。Windows 原生环境可能存在 Python 路径和依赖兼容性问题。

MySQL 数据库 —— AI 驱动的数据查询

简介

@benborla29/mcp-server-mysql 让 AI 能够直接连接和查询 MySQL 数据库。它默认以只读模式运行，AI 可以浏览表结构、执行 SELECT 查询、分析数据，但不会修改任何数据。

核心能力

• mysql_query —— 执行 SQL 查询语句
• list_tables —— 列出数据库中的所有表
• describe_table —— 查看表结构（字段、类型、索引等）

前置条件

• Node.js 18+：在终端运行 node -v 检查版本
• 可访问的 MySQL 数据库：本地或远程均可，需要数据库连接信息（主机、端口、用户名、密码、数据库名）

配置步骤

-- 创建只读用户（在 MySQL 中执行）
CREATE USER 'ai_reader'@'%' IDENTIFIED BY 'your_password';
GRANT SELECT ON your_database.* TO 'ai_reader'@'%';
FLUSH PRIVILEGES;

{
  "mcpServers": {
    "mysql": {
      "command": "npx",
      "args": ["-y", "@benborla29/mcp-server-mysql"],
      "env": {
        "MYSQL_HOST": "127.0.0.1",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "ai_reader",
        "MYSQL_PASS": "your_password",
        "MYSQL_DB": "your_database"
      }
    }
  }
}

{
  "mcpServers": {
    "mysql": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@benborla29/mcp-server-mysql"],
      "env": {
        "MYSQL_HOST": "127.0.0.1",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "ai_reader",
        "MYSQL_PASS": "your_password",
        "MYSQL_DB": "your_database"
      }
    }
  }
}

使用示例

• 数据库探索：「帮我看看这个数据库有哪些表，每个表是干什么的」—— AI 会列出所有表并描述各表结构
• 数据查询分析：「查询最近 7 天的新用户注册数，按天分组」—— AI 会生成并执行 SQL，返回结果和分析
• SQL 生成辅助：「根据 orders 表结构，帮我写一个统计月度销售额的 SQL」—— AI 会先查看表结构再生成精准 SQL

常见问题

• Q: 会不会误操作删除数据？ → 默认只读模式，ALLOW_INSERT_OPERATION、ALLOW_UPDATE_OPERATION、ALLOW_DELETE_OPERATION 全部为 false。只有你显式设置为 true 才能执行写操作。
• Q: 支持远程数据库吗？ → 支持，将 MYSQL_HOST 设置为远程服务器 IP 即可。建议通过 SSH 隧道连接以确保安全。
• Q: 怎么连接多个数据库？ → 不填 MYSQL_DB 环境变量即可在会话中通过 USE database_name 切换数据库。
• Q: 查询结果太多怎么办？ → AI 通常会自动添加 LIMIT 限制返回行数。你也可以在提问时指定：「只看前 10 条」。

Playwright —— 浏览器自动化

简介

@playwright/mcp 是 Microsoft 官方出品的 MCP Server，让 AI 能够控制浏览器执行操作——导航网页、点击元素、填写表单、截图、读取页面内容等。适用于网页信息采集、本地开发调试、自动化操作等场景。

核心能力

• browser_navigate —— 导航到指定 URL
• browser_click —— 点击页面元素
• browser_type —— 在输入框中输入文字
• browser_snapshot —— 获取页面可访问性快照（文字内容）
• browser_take_screenshot —— 对页面截图
• browser_fill_form —— 填写表单
• browser_evaluate —— 执行 JavaScript 代码
• browser_press_key —— 模拟按键操作
• browser_tabs —— 管理浏览器标签页

前置条件

• Node.js 18+：在终端运行 node -v 检查版本
• 浏览器：首次运行时会自动下载 Chromium 浏览器（约 200MB），请确保网络通畅

配置步骤

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--headed"]
    }
  }
}

{
  "mcpServers": {
    "playwright": {
      "command": "cmd",
      "args": ["/c", "npx", "@playwright/mcp@latest"]
    }
  }
}

{
  "mcpServers": {
    "playwright": {
      "command": "cmd",
      "args": ["/c", "npx", "@playwright/mcp@latest", "--headed"]
    }
  }
}

使用示例

• 网页信息采集：「打开 HackerNews，总结今天前 5 条新闻的标题和链接」—— AI 会导航到页面、读取内容并整理
• 本地开发调试：「打开 localhost:3000，截图看看页面效果，检查控制台有没有报错」—— AI 会打开页面、截图、执行 JS 检查错误
• 自动化操作：「打开 xxx 页面，帮我填写这个表单并提交」—— AI 会识别表单元素并自动填写

常见问题

• Q: 首次运行很慢？ → 需要下载 Chromium 浏览器（约 200MB），请确保网络通畅，耐心等待。后续启动不会重复下载。
• Q: 支持哪些浏览器？ → 默认使用 Chromium，也支持 Firefox 和 WebKit，通过 --browser firefox 或 --browser webkit 参数切换。
• Q: WSL 下能用吗？ → Headless 模式可以正常使用。Headed 模式需要配置 X Server（如 VcXsrv）才能显示浏览器窗口。
• Q: 能同时操作多个标签页吗？ → 支持，AI 可以使用 browser_tabs 工具管理多个标签页，在不同页面之间切换。

什么是 Harness Engineering？

「Harness」一词源自 Anthropic 官方工程博文 Effective Harnesses for Long-Running Agents，指围绕 AI 编程 Agent 构建的外部控制结构——包括上下文注入、工作流编排、质量控制循环等能力。

如果把 AI 编程工具（Claude Code、Codex CLI 等）比作赛车的引擎，Harness 就是底盘、悬挂和空气动力学套件——同一台引擎装在不同底盘上，圈速天差地别。

形态分类速览

Harness 工具按核心能力可分为四大类，了解分类有助于按需选型。

全量工具对比大表

下表覆盖 Harness Engineering 领域的主流工具，按形态分组。本站实际使用的工具标记为 推荐，社区主流标记为 主流。

如何选择？

简介

Trellis 是一个开源的 AI 编程工作流系统，为 AI Agent 提供规范驱动、任务管理、多 Agent 编排和质量控制能力。核心理念：一套 .trellis/ 目录，统一管理所有 AI 编程工具的工作流。

上手体验

• 初始化简单：CLI 一行命令初始化，自动在项目根目录生成 .trellis/ 目录结构
• 学习曲线：中等。需要理解 spec/、tasks/、workspace/ 三层目录的职责划分，但上手后工作流非常自然
• 多平台无缝：同一个 .trellis/ 目录同时支持 Claude Code（.claude/）和 Codex CLI（.codex/），切换工具零成本

目录结构一览

.trellis/
├── spec/              # 项目规范（前端、后端、部署指南等）
│   ├── frontend/      # 前端规范
│   ├── backend/       # 后端规范
│   └── guides/        # 通用指南
├── tasks/             # 任务管理（每个任务一个目录）
│   └── <task-slug>/   # task.json + prd.md + *.jsonl
├── workspace/         # 开发者工作区
│   └── <developer>/   # journal、session 记录
├── workflow.md        # 工作流规则
├── config.yaml        # 项目级配置
└── scripts/           # 工具脚本

核心功能

1. 规范驱动开发（Spec 系统）

.trellis/spec/ 目录按层级存放项目规范（前端、后端、部署指南等），Agent 在编码前会自动读取相关规范。效果：代码风格一致性大幅提升，减少了"AI 写出来的代码不像项目原有风格"的问题。

2. 任务 PRD 生命周期

每个任务有独立目录，包含 task.json（状态）、prd.md（需求文档）和 .jsonl 上下文文件。从创建到归档的完整生命周期管理，让 AI 不再"一问一答"式工作，而是有计划地推进。

3. 多 Agent 编排（Pipeline）

通过 /trellis:parallel 命令启动 Multi-Agent Pipeline：Research → Implement → Check → Finish。每个子 Agent 使用独立的 Git Worktree 隔离工作，互不干扰。实测在复杂任务上效率提升显著。

4. 上下文自动注入

通过 Claude Code 的 PreToolUse Hook，在子 Agent 启动时自动注入 code-spec 上下文（JSONL 格式定义）。核心理念："Context is injected, not remembered"——Agent 不需要记住规范，每次都会被注入正确的上下文。

5. Ralph Loop 质量控制

基于 SubagentStop Hook 的自动验证循环：代码写完后自动运行检查，不通过则自动修复重试（最多 5 次）。显著减少了人工 review 的负担。

6. 会话连续性

多开发者 workspace 系统支持人类 + 多个 AI Agent 协作。Journal 日志自动记录工作上下文，Session Start Hook 在每次启动时自动恢复完整状态。

踩坑记录

• 模板同步冲突：Trellis 通过 template-hashes 机制维护模板同步，升级版本时偶尔遇到本地修改与模板冲突，需要手动合并
• Journal 行数限制：workspace journal 有 2000 行上限，长时间工作后需注意轮转，否则可能丢失早期上下文
• Worktree 清理：Multi-Agent Pipeline 使用 Git Worktree 隔离，Agent 异常退出可能留下残余 worktree 需手动清理
• 首次配置 Hook：Hook 系统功能强大但配置步骤较多（settings.json 中的 hooks 数组），建议参照模板配置

适合场景

推荐搭配：skill-garden 强化包

skill-garden 是一个 AI Agent 技能集中管理系统，支持将技能统一维护并灵活安装到多个项目。核心特性：

• 自动检测：安装脚本自动识别目标项目类型（.claude/ → Claude 技能，.codex/ → Codex 技能，.trellis/ → Agent 技能 + 命令）
• 双重注册：同一技能既作为 Agent Skill（YAML frontmatter）又注册为斜杠命令（/trellis:<name>）

日常推荐技能

安装方式

# 首次安装（远程）
bash install.sh --repo git@github.com:SilentFlower/skill-garden.git /path/to/project

# 后续更新
bash ~/.skill-garden/scripts/install.sh /path/to/project

简介

OpenSpec 是由 Fission AI（Y Combinator 孵化）打造的开源规范驱动开发框架。核心理念：先写规范，再让 AI 编码——通过轻量级的 Spec 文件（约 250 行）约束 AI Agent 的行为，确保实现与意图对齐。

快速开始

npm install -g @fission-ai/openspec@latest

openspec init

openspec/
├── specs/        # 源头真相：描述系统行为的规范文件
├── changes/      # 变更提案（proposal）
└── config.yaml   # 项目配置

核心工作流：三阶段状态机

OpenSpec 的工作流围绕三个核心阶段展开，形成"提议→实现→归档"的闭环。

阶段一：Propose（提议）

使用 /opsx:propose "你的想法" 创建变更提案，自动生成：

• proposal.md — 为什么要做这件事，改了什么
• specs/ — 需求与场景定义
• design.md — 技术方案
• tasks.md — 实现清单

阶段二：Apply（实现）

使用 /opsx:apply，AI 按照 Spec 逐步完成任务清单中的每一项。

阶段三：Archive（归档）

使用 /opsx:archive，完成的变更归档保存，Spec 更新为最新状态。

常用命令

适合场景

与 Trellis 对比

OpenSpec 和 Trellis 定位不同，可以互补使用：