Qoder AI 编程助手新手完全使用指南

一、Qoder 基本介绍

Qoder 是阿里巴巴推出的新一代智能体编程平台（Agentic Coding Platform），专为真实软件开发场景设计。与普通代码补全工具不同，Qoder 能全面理解整个代码库，系统性地处理开发任务。

官网地址：

三种产品形态

Qoder IDE：独立图形化界面，新手首选
Qoder CLI：终端命令行版本
Qoder JetBrains 插件：直接集成到 IDEA / WebStorm 等 JB 全家桶

二、三大核心工作模式

模式	用途	是否消耗 Credits	适合场景
Ask 模式	只问不改，纯信息查询	不消耗	理解代码、咨询方案
Agent 模式	主力编码，读文件写代码	消耗	实现功能、修复 Bug
Quest 模式	先设计方案后执行	消耗	复杂功能、系统重构

黄金法则：Ask 理解 → Quest 规划 → Agent 执行

切换方式：

三、常用快捷键

功能	Windows	macOS
触发 AI 聊天面板	`Ctrl + L`	`⌘ L`
打开行间聊天	`Ctrl + I`	`⌘ I`
触发下一步编辑建议	`Alt + P`	`⌥ P`
应用代码建议	`Ctrl + Enter`	`⌘ ↩`
接受代码补全	`Tab`	`Tab`
打开设置	`Ctrl + Shift + ,`	`⌘ ⇧ ,`

四、省 Token 核心技巧

这是新手最需要掌握的内容，合理省 Token 可大幅降低成本。

1. 模式选择策略

text 复制代码

❌ 用 Agent 模式问技术问题（扫描文件 = 浪费）
✅ 用 Ask 模式问问题（免费）

切换方式：

合理选择模式和粗略可省token，否则对比效果：

2. 精准 @引用，不要全量投喂

text 复制代码

❌ 把整个项目目录加进上下文
✅ 只 @核心文件：@UserController.java + @UserService.java

3. 通过斜杠命令屏蔽无关工具

在自定义命令文件首行加入：

text 复制代码

Don't search project's files!   # 禁止扫描项目文件
Don't search web!                # 禁止网页搜索
Don't search memory!             # 禁止读取记忆

4. 上下文窗口健康管理

上下文窗口占用超过 60% → 立刻拆分任务，新开会话
把大任务拆成小步骤，避免"一锅端"

5. 让 AI 造工具，而非反复做同一件事

text 复制代码

场景：50 个接口要生成文档
❌ 让 AI 一个个生成
✅ 让 AI 先写一个批量生成工具，一次搞定，以后复用

五、@引用代码块的方式

在聊天框输入 @ 符号，可引用多种类型上下文：

引用类型	说明	示例
`@file`	引用具体代码文件	`@UserController.java`
`@folder`	引用整个目录	`@src/main/service`
`@image`	引用设计图/截图	`@design.png`
`@rules`	引用规则文件	`@code-style.md`
`@attachments`	引用本地文件	上传日志文件

使用示例：

text 复制代码

帮我改 @UserController.java 里的 createOrder 方法，增加用户等级判断
根据 @design.png 这张设计图生成 Vue 商品列表页，包含分页和搜索

六、斜杠命令（Slash Commands）

内置命令

命令	功能
`/plan`	触发规划 Agent，先出方案后执行
`/browser`	触发浏览器 Agent
`/code-review`	触发代码审查 Agent
`/canvas`	在 Canvas 中创建可视化内容
`/create-skill`	创建新技能

自定义斜杠命令

存储路径：

用户级（全局）：~/.qoder/r/c/commands/
项目级（共享）：<项目根目录>/.qoder/r/c/commands/

示例：创建 /java 命令（java.md）

markdown 复制代码

Don't search project's files! Don't search web! Don't search memory!
请根据你了解的 Java(8-25) 相关知识回答用户问题。

常用命令模板：

命令	用途	工具策略
`/java`	Java 知识查询	屏蔽全部工具
`/sql`	SQL 生成	结合项目 DB 上下文
`/translator`	英文翻译	屏蔽全部工具
`/bash`	生成命令行脚本	声明 OS 环境

七、规则（Rules）配置

规则是给 AI 灌"项目手册"，让 AI 生成的代码严格遵守团队规范。

规则文件位置

text 复制代码

<项目根目录>/
└── .qoder/
    └── rules/
        ├── code-style.md
        └── naming-convention.md

重要：.qoder 目录必须提交到 Git，不能加入 .gitignore！

规则生效方式

类型	说明
始终生效	在所有 Agent 会话中自动生效
指定文件生效	针对 `*.java` 等指定文件生效
手动引入	在上下文中手动 `@rules` 引用
模型决策	由模型判断是否激活

Java 项目规则示例

markdown 复制代码

# Java 编码规范
- 使用 Java 17+ 特性（Stream、Lambda、Optional）
- 统一使用 Lombok 简化 POJO 类
- 所有 Controller 方法必须加 Swagger/OpenAPI 注解
- 异常统一通过 GlobalExceptionHandler 处理
- 禁止在代码中硬编码密码和密钥

八、记忆功能（Memory）

Qoder 提供长期记忆功能，记录你的：

个人编码习惯（命名风格、技术偏好）
项目特定知识（特殊组件用法、架构决策）
历史错误解决方案（避免重复踩坑）

管理路径：设置 → 点击用户名 → 个人设置 → 记忆管理

记忆 vs 规则 vs Skills

机制	适用场景	示例
规则 Rules	固定的项目规范约束	"必须用公司组件库"
技能 Skills	专业领域工作流知识	数据库迁移、API 文档生成
记忆 Memory	个人习惯、历史经验	"某功能的实现方案"

九、技能（Skills）功能

Skills 将专业领域知识打包成可复用功能模块。

目录结构

text 复制代码

.qoder/skills/api-doc-generator/
├── SKILL.md          # 必需：主文件
├── REFERENCE.md      # 可选：详细参考文档
└── EXAMPLES.md       # 可选：示例

SKILL.md 格式

markdown 复制代码

---name: api-doc-generatordescription: Generate comprehensive API documentation from code.             Use when creating API docs, documenting endpoints,             or generating OpenAPI specs.---
# API Documentation Generator
## Instructions1. Identify all API endpoints and routes2. Document request/response formats3. Include authentication requirements4. Add example requests and responses

Skills 触发方式

自动触发 ：直接描述需求，模型自动识别 → "为这个 API 生成文档"
手动触发 ：输入 /api-doc-generator

十、子代理（Subagent）功能

Subagent 是独立上下文的专属 AI 代理，互不干扰。

内置 Agent

Agent	触发命令	功能
Plan Agent	`/plan`	先规划后执行
Browser Agent	`/browser`	浏览器自动化
Code Review Agent	`/code-review`	代码审查

典型协作场景

text 复制代码

全栈开发：  ├── frontend-agent（Vue UI 开发）  └── backend-agent（Spring Boot API）  → 两者并行，互不干扰
代码审查：  ├── security-auditor（安全漏洞扫描）  └── performance-reviewer（性能分析）  → 并行审查，主 Agent 汇总结果

十一、MCP 工具集成

MCP（Model Context Protocol）让 Qoder 接入数据库、API、浏览器等外部服务。

注意：MCP 仅在 Agent 模式下有效！

配置方式

打开设置（Ctrl + Shift + ,）→ MCP → 添加服务

配置示例：

json 复制代码

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your_token"
      }
    }
  }
}

十二、文档生成

Repo Wiki --- 代码库自动文档化

右键项目 → Generate Repo Wiki，自动生成：

项目架构图谱
模块说明文档
API 手册
依赖关系图

通过 Agent 批量生成文档

text 复制代码

"写一个 Java 工具，读取指定包下的 Controller 类，解析 Swagger 注解，生成 API 文档 XML 文件...[附上规范示例]"
→ 工具写好后批量执行，5 分钟搞定 50 个接口文档

十三、项目配置最佳实践

.qoder 目录完整结构

text 复制代码

<项目根目录>/
└── .qoder/
    ├── rules/              # 项目规则
    ├── skills/             # 项目级技能
    └── r/
        ├── a/agents/       # 自定义子代理
        └── c/commands/     # 自定义斜杠命令

AGENTS.md --- 项目级全局指令

在项目根目录创建 AGENTS.md，Qoder 每次执行都会强制读取：

markdown 复制代码

# 项目说明
## 技术栈- 后端：Spring Boot 3.2 + Java 17 + MyBatis
## 编码规范- 遵循阿里巴巴 Java 编码规范- 统一使用 Result<T> 包装返回值
## 注意事项- 禁止在代码中硬编码密码和密钥

十四、功能选择速查表

场景	推荐功能	原因
问技术问题	Ask 模式 + 斜杠命令	免费，省 Token
实现新功能	Agent + @精准引用	执行力强
复杂任务规划	Quest / Plan Agent	先出方案，降低返工
批量重复任务	Agent 造工具	一次搞定，持续复用
固定工作流	Slash Commands	一键调用
领域专业任务	Skills	自动触发，团队共享
并行多任务	Subagents	独立上下文互不干扰
接入外部工具	MCP	标准协议，生态丰富
统一团队规范	Rules + AGENTS.md	AI 强制遵守项目规范
记住个人习惯	Memory	越用越懂你
理解大型项目	Repo Wiki	自动生成知识图谱

核心思想 ：Qoder 的价值不在于"让 AI 替代你写代码"，而在于让你专注于定义问题和设计方案，把重复劳动交给 AI。掌握好上下文控制、模式选择和工具屏蔽，你就能真正驾驭 AI 编程的力量。