# Coding 模式(Beta)

> **Beta 功能**：Coding 模式是 QwenPaw 为编码场景打造的 IDE 化工作台，把 Agent 从「聊天助手」升级为「能直接读你代码、改你代码的协作者」。目前仍在持续迭代，欢迎在 [GitHub](https://github.com/agentscope-ai/QwenPaw/issues) 反馈。

QwenPaw 的普通聊天模式适合「问答 + 临时任务」，但当你想让 Agent **持续在某个项目里干活**——读源码、改文件、跑测试、查 git——聊天界面就不够用了。Coding 模式提供了一个轻量 IDE 视图，把项目文件、编辑器、Diff 预览和聊天放在一个布局里，同时给 Agent 装上两个专为代码理解优化的工具：`lsp`（精确定位定义/引用）和 `ast_search`（结构化语法查找）。

---

## 何时用 Coding 模式

| 场景                                     | 建议模式        |
| ---------------------------------------- | --------------- |
| 一次性问答 / 临时脚本 / 闲聊             | 普通 Chat 模式  |
| 在指定项目里读代码、改文件、修 bug、重构 | **Coding 模式** |
| 跨项目的探索 / 不绑定单一仓库的任务      | 普通 Chat 模式  |

> **一句话区分**：要让 Agent 把某个目录当「工作车间」连续干活，就开 Coding 模式；只是临时问一句，就用普通模式。

---

## 快速上手

### 1. 切换到 Coding 模式

在聊天界面顶部找到 `Code` / `Chat` 切换按钮，点击 `Code` 即可进入。

### 2. 选择项目

首次进入会弹出项目选择窗口，有两类方式：

- **直接打开已有目录** — 通过文件浏览器选择本机上已有的项目目录，Agent 直接在该目录下工作，不会复制任何文件。适合想让 Agent 直接操作现有项目的场景。
- **导入为副本** — **克隆远程仓库**、**复制本地文件夹**、**上传 zip** 或**新建空项目**，都会在 QwenPaw 工作区的 `coding_projects/<项目名>/` 下生成一份**副本**，你的原始目录不会被改动。

无论哪种方式，Agent 接下来读写的都是所选目录，它就是后文说的「项目目录」。

![项目选择弹窗](https://img.alicdn.com/imgextra/i3/O1CN01ofmycu235UOvIHxKZ_!!6000000007204-2-tps-3346-1670.png)

> **直接打开 vs 导入副本？** 如果你的项目 IDE 已打开、有未提交改动或跑着 CI，建议使用副本模式以避免 Agent 误操作影响工作树。副本仍保留 `.git`，可以正常 commit / push。如果你希望 Agent 直接在原目录工作（例如快速修改或审查代码），选择「打开目录」即可。

**终端 TUI 快捷方式：** 在项目目录下运行 `qwenpaw .`，或用
`qwenpaw tui /path/to/repo` 显式指定目录。这样只会为本次 TUI 会话启用
Coding 模式的提示和工具行为；不会修改 `agent.json`，也不会改变控制台里保存的项目。

### 3. 开始干活

进入 IDE 视图后，左侧是文件树，中间是带 Tab 的编辑器和 Diff 预览，右侧是聊天面板。直接像平时一样和 Agent 对话即可，例如：

- 「读一下 `src/auth/login.py`，告诉我 `verify_password` 是怎么实现的」
- 「在 `tests/` 下加一个 `test_login_rate_limit.py`，覆盖 5 次失败后锁定 10 分钟的场景」
- 「这个分支相比 main 改了哪些文件？帮我写个 PR description」

![Coding 模式 IDE 主界面](https://img.alicdn.com/imgextra/i4/O1CN014tF5921HlXCevvsBH_!!6000000000798-2-tps-3340-1678.png)

---

## Coding 模式做了什么

普通模式下 Agent 看到的是「一个工作空间」，没有特别的项目概念。打开 Coding 模式后，QwenPaw 会自动做这些事：

### 1. 注入编码专属的系统提示

告诉 Agent：

- **当前项目目录是 XXX，所有文件操作要用项目根目录下的绝对路径**
- 跑 shell 命令要显式指定 `cwd=` 到项目目录，否则会落在 Agent 工作区
- 引用代码时用 `path/to/file.py:42` 这种格式（IDE 可点击跳转）
- 非琐碎任务先创建 `{TASK}_TODO.md` 维护清单，做一步勾一步

### 2. 自动注册两个代码理解工具

| 工具         | 用途                                                                      | 何时自动启用                                              |
| ------------ | ------------------------------------------------------------------------- | --------------------------------------------------------- |
| `lsp`        | 精准查询符号定义、引用、跳转——回答「X 在哪定义？谁调用了 Y？」            | 项目里至少检测到一种 LSP 服务器（Python/TS 默认随包安装） |
| `ast_search` | 基于语法树的结构化查询——回答「所有接收 `Request` 返回 `Response` 的函数」 | 系统装了 `ast-grep` CLI（默认随包安装）                   |

两个工具都是**只读**的，不会修改任何文件。Agent 优先用它们而不是 `grep`，能避免误判和漏判。

### 3. 区分「项目目录」和「工作区目录」

- **项目目录**：你选的那个仓库，Agent 干活的主战场
- **工作区目录**：QwenPaw 内部存配置、会话历史、记忆等的隐藏目录，**Agent 默认不该碰**

Coding 模式的系统提示会反复强调这个区分，避免 Agent 在不该出现的地方 `ls` 或写文件。

---

## 退出 Coding 模式

点击同一个切换按钮，从 `Chat` 切回普通模式。Agent 的项目目录绑定和系统提示注入会立即解除，但你的项目文件、Git 状态等都保持不变。

---

## 常见问题

**Q：切换 Coding 模式会影响我已经存在的记忆 / Skills 吗？**

不会。Coding 模式只改 Agent 的系统提示和工具集，不动记忆、Skills、Persona 这些独立功能。

**Q：可以同时绑定多个项目吗？**

每个 Agent 同一时间只绑定一个项目目录。需要切换项目时，重新打开项目选择窗口选另一个即可。

**Q：`lsp` / `ast_search` 没出现在工具列表里？**

打开新对话再试。这两个工具是按项目和环境动态注册的，旧会话需要重启。如果项目里没装对应语言的 LSP 服务器（如纯 Go 项目但只装了 pylsp），`lsp` 会自动跳过对应语言。

**Q：Coding 模式和 Skills / Plan / Cron 这些可以一起用吗？**

可以。Coding 模式只是一个 UI 布局 + 工具增强层，和其他功能正交。