# Aigis AI Coding Assistant 用户手册
版本 1.0.0

Aigis AI Coding Assistant 是一款面向 VS Code 和 JetBrains IDE 的 AI 编程助手插件，集成 AI 对话、代码理解、代码检阅、代码修复、注释生成与智能代码补全能力，并通过本地 Aigis 后端服务与大模型交互。

## 目录

1. [登录与认证](#login-authentication)
2. [AI 对话面板](#ai-chat-panel)
3. [会话管理](#session-management)
4. [代码右键菜单](#code-context-menu)
5. [AI 行内代码补全](#inline-code-completion)
6. [代码注释生成](#comment-generation)
7. [本地后端服务管理](#local-backend)
8. [模型选择](#model-selection)
9. [国际化](#internationalization)
10. [IDE 集成](#ide-integration)
11. [技术支持](#support)

---

<a id="login-authentication"></a>
## 1. 登录与认证

使用 Aigis AI 前，需要先完成登录。插件支持两种登录方式，登录成功后所有功能才会启用。

### 1.1 打开登录窗口

首次打开 IDE 时，如果检测到未登录，会自动弹出登录窗口。

也可以手动打开登录窗口：
- 在编辑器中右键点击，选择 **Aigis AI → Sign In（登录）**。
- 或在 IDEA 状态栏点击 Aigis 登录状态图标。

### 1.2 账号密码登录

1. 在登录窗口中选择 **账号密码** 标签页。
2. 输入后端服务地址（IP 或 URL）。
3. 输入账号和密码。
4. 点击登录按钮。

### 1.3 手机号验证码登录

1. 在登录窗口中选择 **手机验证码** 标签页。
2. 输入后端服务地址（IP 或 URL）。
3. 输入手机号。
4. 点击 **获取验证码**。
5. 输入收到的短信验证码。
6. 点击登录按钮。

### 1.4 登录成功

- 登录成功后，插件会保存 Token。
- 后续请求本地后端服务和大模型接口时，会自动携带 Token。
- 状态栏会显示当前已登录的用户名。

### 1.5 退出登录

- 在编辑器中右键点击，选择 **Aigis AI → Sign Out（退出登录）**。
- 退出后，当前聊天窗口和会话状态会自动清空，需要重新登录才能使用 AI 功能。

### 1.6 多窗口共享登录态

- 在 IDE 中同时打开多个项目窗口时，登录状态会全局共享，只需登录一次即可。

---

<a id="ai-chat-panel"></a>
## 2. AI 对话面板

登录成功后，可以通过侧边栏的 AI 对话面板与模型进行交互。

### 2.1 打开对话面板

- 在 JetBrains IDE 中，点击 IDE 右侧工具栏的 **Aigis AI** 图标，打开侧边栏聊天窗口。
- 在 VS Code 中，点击左侧活动栏中的 Aigis 图标。

### 2.2 发起对话

1. 在面板底部的输入框中输入问题或需求。
2. 按 `Enter` 发送消息。
3. 如果需要在输入中换行，按 `Shift + Enter`。

### 2.3 流式输出与思考过程

- AI 回复会以流式方式逐字显示在对话区域。
- 如果模型支持思考过程，插件会在正式回答前展示 AI 的推理过程。

### 2.4 停止当前输出

- 在 AI 回复过程中，发送按钮会变成停止按钮，点击即可中断当前输出。

### 2.5 自动携带上下文

对话会自动包含以下上下文信息，帮助 AI 更准确地理解问题：

- 当前工作区 / 项目目录
- 当前打开的文件
- 当前选中的代码
- 光标附近的代码

### 2.6 工具命令支持

AI 在对话过程中可以调用本地工具来辅助回答，例如：

- 列出当前目录内容（如 `ls`、`dir` 等命令）
- 查看当前工作目录（如 `pwd`、`cd` 等命令）
- 读取项目中的文件内容
- 查找文件或代码片段
- 运行简单的命令或脚本

当 AI 需要执行这些操作时，插件会在本地执行并将结果返回给 AI，用户可以在对话面板中看到工具的调用过程和返回结果。

### 2.7 权限请求弹窗

当 AI 需要修改文件或执行敏感操作时，插件会弹出确认对话框，只有点击确认后才会继续执行。

---

<a id="session-management"></a>
## 3. 会话管理

在 AI 对话面板中，可以对聊天会话进行管理。

### 3.1 新建会话

- 点击聊天面板顶部的 `+` 按钮。
- 插件会生成一个新的会话 ID，开启一个全新对话，之前的对话不会混入当前会话。

### 3.2 连续对话

- 在同一个会话中连续提问，AI 会自动关联上下文，基于前面的交流继续回应。

### 3.3 查看历史会话

- 打开聊天面板且没有活跃会话时，会显示历史会话列表。
- 默认展示最近 **5 条** 会话。
- 如果历史会话超过 5 条，底部会显示 **显示全部（共 X 条）** 链接，点击后展开完整列表。

### 3.4 切换会话

- 在历史会话列表中点击某个会话标题。
- 插件会加载该会话的完整对话记录，并可以继续在该会话中提问。

### 3.5 收起历史列表

- 展开全部历史后，点击 **收起** 链接，历史列表会恢复到只显示最近 5 条。

### 3.6 自动加载最新会话

- 打开聊天面板且当前没有活跃会话时，插件会自动加载最近一条有内容的历史会话详情。

### 3.7 清空会话显示

- 退出登录时会自动清空当前聊天窗口和会话状态。
- 点击 `+` 新建会话也可以开始一个空白的新对话。

---

<a id="code-context-menu"></a>
## 4. 代码右键菜单

在编辑器中选中代码，或将光标放在代码上，右键点击选择 **Aigis AI** 菜单组，即可使用以下功能。如果未登录，这些菜单项会隐藏或不可用。

> **提示**：以下"解释代码""检阅代码""优化/重构代码""修复代码"等功能，**如果当前没有选中任何代码，默认会以当前整个文件作为处理对象**；"生成注释"功能在未选中代码时，会针对光标所在行生成注释。

### 4.1 解释代码

- 选择 **Explain Code（解释代码）**。
- AI 会在对话面板中解释选中代码的含义和作用。
- 未选中代码时，默认解释当前整个文件。

### 4.2 检阅代码

- 选择 **Review Code（检阅代码）**。
- AI 会检查选中代码中的潜在 Bug、边界条件、可维护性和安全风险，并给出建议。
- 未选中代码时，默认检阅当前整个文件。

### 4.3 优化/重构代码

- 选择 **Optimize/Refactor Suggestions（优化/重构建议）**。
- AI 会针对可读性、可维护性和简洁性给出优化建议，必要时会提供改进后的代码。
- 未选中代码时，默认针对当前整个文件给出建议。

### 4.4 修复代码

- 选择 **Fix Code（修复代码）**。
- AI 会尝试发现错误、潜在 Bug 或边界条件问题，并给出修复后的代码。
- 未选中代码时，默认修复当前整个文件。
- 修复完成后会弹出 Diff 预览窗口，用户确认后才会应用到源代码中。

### 4.5 生成注释

- 选择 **Generate Comment（生成注释）**。
- 对方法会优先生成 JavaDoc 风格注释，对普通代码片段生成 `//` 行注释，并直接插入源代码中。
- 未选中代码时，默认针对光标所在行生成注释。

### 4.6 开启/关闭 AI 代码补全

- 选择 **AI Code Completion On/Off**。
- 用于切换 AI 行内代码补全功能的启用状态。

### 4.7 登录/退出登录

- **Sign In**：手动打开登录窗口。
- **Sign Out**：退出当前登录账号。

---

<a id="inline-code-completion"></a>
## 5. AI 行内代码补全

AI 行内代码补全可以在编写代码时自动给出建议，以 IDE 原生的 Ghost Text 形式显示。

### 5.1 触发补全

- 在编辑器中编写代码，插件会根据当前代码上下文自动生成补全建议。
- 建议以灰色 Ghost Text 显示在光标后方。

### 5.2 接受建议

- 看到补全建议后，按 `Tab` 键接受，建议内容会插入到当前光标位置。

### 5.3 单行与多行补全

- 支持单行补全，也支持多行代码片段补全。

### 5.4 开启/关闭补全

- 通过右键菜单 **Aigis AI → AI Code Completion On/Off** 切换。
- 也可以在状态栏或设置中找到相关入口。

### 5.5 格式清洗

- 接受补全后，插件会自动对插入的代码进行基础格式化与缩进修正，使其更符合当前项目的代码风格。

---

<a id="comment-generation"></a>
## 6. 代码注释生成

注释生成是右键菜单中 **Generate Comment** 的具体说明。

### 6.1 使用方法

1. 选中一段代码，或将光标放在目标方法/代码行上。
2. 右键选择 **Aigis AI → Generate Comment（生成注释）**。

### 6.2 方法级注释

- 如果选中的是 Java 方法，插件会优先生成 JavaDoc 风格的注释，放在方法声明之前。

### 6.3 普通代码注释

- 对于普通代码片段，插件会生成简洁的 `//` 行注释。

### 6.4 插入位置

- 生成的注释会直接插入到源代码中对应位置，无需手动复制粘贴。

---

<a id="local-backend"></a>
## 7. 本地后端服务管理

Aigis 插件需要连接本地 Aigis 后端服务才能正常工作。

### 7.1 端口探测

- 插件默认探测本地 **9427 端口**。
- 如果 9427 端口被占用，插件会向后顺延查找下一个可用端口（如 9428、9429...）。

### 7.2 自动启动后端

- 找到可用的端口后，插件会自动启动内置的本地后端可执行文件。

### 7.3 平台适配

- macOS 和 Windows 分别打包了对应平台的后端可执行文件，插件会根据当前系统启动对应的版本。

---

<a id="model-selection"></a>
## 8. 模型选择

### 8.1 模型列表加载

- 插件启动时会自动从本地后端服务读取可用的模型列表。
- 模型列表显示在聊天面板顶部的下拉框中。

### 8.2 切换模型

1. 在聊天面板顶部找到模型下拉菜单。
2. 点击选择想要使用的模型。

### 8.3 模型作用范围

- 选择模型后，后续的对话、代码处理、代码补全等请求都会使用所选模型。

---

<a id="internationalization"></a>
## 9. 国际化

### 9.1 自动跟随 IDE 语言

- 插件界面（登录框、提示信息、会话面板按钮、Prompt 等）会自动跟随 IDE 语言环境切换中英文。

### 9.2 手动指定语言

- 可通过配置项 `aigis.language` 手动指定界面语言。

---

<a id="ide-integration"></a>
## 10. IDE 集成

### 10.1 支持的 IDE

- VS Code
- IntelliJ IDEA / JetBrains 系列 IDE

### 10.2 上下文联动

- 插件与当前工作区、当前文件、选中代码、光标位置实时联动。

### 10.3 状态栏登录状态

- IDE 状态栏会显示当前 Aigis 登录状态，点击可快速登录或退出。

- **未登录时**：显示 **Aigis: Not signed in（Aigis: 未登录）**。
  - 点击状态栏图标可以快速打开登录窗口。
- **已登录时**：显示 **Aigis: 用户名**。
  - 点击状态栏图标可以快速退出登录。
  - 鼠标悬停时会显示更详细的登录提示信息。

### 10.4 交互入口

- 编辑器右键菜单
- 侧边栏工具窗口

---

<a id="support"></a>

## 11 技术支持
如需帮助、反馈或报告错误，请通过您所在组织的支持渠道或 Aigis 官方网站联系 Aigis Code 团队。

感谢您使用 Aigis AI Coding Assistant！