夜雨聆风Qoder AI 编程助手新手完全使用指南
一、Qoder 基本介绍
Qoder 是阿里巴巴推出的新一代智能体编程平台（Agentic Coding Platform），专为真实软件开发场景设计。与普通代码补全工具不同，Qoder 能全面理解整个代码库，系统性地处理开发任务。
官网地址：
https://qoder.com/
三种产品形态
- Qoder IDE
：独立图形化界面，新手首选 - Qoder CLI
：终端命令行版本 - Qoder JetBrains 插件
：直接集成到 IDEA / WebStorm 等 JB 全家桶
二、三大核心工作模式
| Ask 模式 | |||
| Agent 模式 | |||
| Quest 模式 |
黄金法则：Ask 理解 → Quest 规划 → Agent 执行
切换方式：
三、常用快捷键
Ctrl + L | ⌘ L | |
Ctrl + I | ⌘ I | |
Alt + P | ⌥ P | |
Ctrl + Enter | ⌘ ↩ | |
Tab | Tab | |
Ctrl + Shift + , | ⌘ ⇧ , |
四、省 Token 核心技巧
这是新手最需要掌握的内容，合理省 Token 可大幅降低成本。
1. 模式选择策略
❌ 用 Agent 模式问技术问题（扫描文件 = 浪费）✅ 用 Ask 模式问问题（免费）
切换方式：
合理选择模式和粗略可省token，否则对比效果：
2. 精准 @引用，不要全量投喂
❌ 把整个项目目录加进上下文✅ 只 @核心文件：@UserController.java + @UserService.java
3. 通过斜杠命令屏蔽无关工具
在自定义命令文件首行加入：
Don't search project's files! # 禁止扫描项目文件Don't search web! # 禁止网页搜索Don't search memory! # 禁止读取记忆
4. 上下文窗口健康管理
上下文窗口占用超过 60% → 立刻拆分任务，新开会话 把大任务拆成小步骤，避免"一锅端"
5. 让 AI 造工具，而非反复做同一件事
场景：50 个接口要生成文档❌ 让 AI 一个个生成✅ 让 AI 先写一个批量生成工具，一次搞定，以后复用
五、@引用代码块的方式
在聊天框输入 @ 符号，可引用多种类型上下文：
@file | @UserController.java | |
@folder | @src/main/service | |
@image | @design.png | |
@rules | @code-style.md | |
@attachments |
使用示例：
帮我改 @UserController.java 里的 createOrder 方法，增加用户等级判断根据 @design.png 这张设计图生成 Vue 商品列表页，包含分页和搜索
六、斜杠命令（Slash Commands）
内置命令
/plan | |
/browser | |
/code-review | |
/canvas | |
/create-skill |
自定义斜杠命令
存储路径：
用户级（全局）： ~/.qoder/r/c/commands/项目级（共享）： <项目根目录>/.qoder/r/c/commands/
示例：创建 /java 命令（java.md）
Don't search project's files! Don't search web! Don't search memory!请根据你了解的 Java(8-25) 相关知识回答用户问题。
常用命令模板：
/java | ||
/sql | ||
/translator | ||
/bash |
七、规则（Rules）配置
规则是给 AI 灌"项目手册"，让 AI 生成的代码严格遵守团队规范。
规则文件位置
<项目根目录>/└── .qoder/└── rules/├── code-style.md└── naming-convention.md
重要：
.qoder目录必须提交到 Git，不能加入.gitignore！
规则生效方式
| 始终生效 | |
| 指定文件生效 | *.java 等指定文件生效 |
| 手动引入 | @rules 引用 |
| 模型决策 |
Java 项目规则示例
# Java 编码规范- 使用 Java 17+ 特性（Stream、Lambda、Optional）- 统一使用 Lombok 简化 POJO 类- 所有 Controller 方法必须加 Swagger/OpenAPI 注解- 异常统一通过 GlobalExceptionHandler 处理- 禁止在代码中硬编码密码和密钥
八、记忆功能（Memory）
Qoder 提供长期记忆功能，记录你的：
个人编码习惯（命名风格、技术偏好） 项目特定知识（特殊组件用法、架构决策） 历史错误解决方案（避免重复踩坑）
管理路径：设置 → 点击用户名 → 个人设置 → 记忆管理
记忆 vs 规则 vs Skills
| 规则 Rules | ||
| 技能 Skills | ||
| 记忆 Memory |
九、技能（Skills）功能
Skills 将专业领域知识打包成可复用功能模块。
目录结构
.qoder/skills/api-doc-generator/├── SKILL.md # 必需：主文件├── REFERENCE.md # 可选：详细参考文档└── EXAMPLES.md # 可选：示例
SKILL.md 格式
---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
/plan | ||
/browser | ||
/code-review |
典型协作场景
全栈开发： ├── 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 → 添加服务
配置示例：
{"mcpServers": {"github": {"command": "npx","args": ["-y", "@modelcontextprotocol/server-github"],"env": {"GITHUB_PERSONAL_ACCESS_TOKEN": "your_token"}}}}
十二、文档生成
Repo Wiki — 代码库自动文档化
右键项目 → Generate Repo Wiki，自动生成：
项目架构图谱 模块说明文档 API 手册 依赖关系图
通过 Agent 批量生成文档
"写一个 Java 工具，读取指定包下的 Controller 类，解析 Swagger 注解，生成 API 文档 XML 文件…[附上规范示例]"→ 工具写好后批量执行，5 分钟搞定 50 个接口文档
十三、项目配置最佳实践
.qoder 目录完整结构
<项目根目录>/└── .qoder/├── rules/ # 项目规则├── skills/ # 项目级技能└── r/├── a/agents/ # 自定义子代理└── c/commands/ # 自定义斜杠命令
AGENTS.md — 项目级全局指令
在项目根目录创建 AGENTS.md，Qoder 每次执行都会强制读取：
# 项目说明## 技术栈- 后端：Spring Boot 3.2 + Java 17 + MyBatis## 编码规范- 遵循阿里巴巴 Java 编码规范- 统一使用 Result<T> 包装返回值## 注意事项- 禁止在代码中硬编码密码和密钥
十四、功能选择速查表
核心思想：Qoder 的价值不在于"让 AI 替代你写代码"，而在于让你专注于定义问题和设计方案，把重复劳动交给 AI。掌握好上下文控制、模式选择和工具屏蔽，你就能真正驾驭 AI 编程的力量。
