# Kimi Copilot 使用说明

Kimi Copilot 是 Kimi Code CLI 的旁路监督工具。它在你的终端里加了一层 wrapper，实时监听你和 Kimi 的对话。当 Kimi 可能犯错、命令失败，或者你主动召唤时，它会调用本地旁路模型 `qwen3.6-27b-awq` 分析，并把有价值的纠正写入 RAG 知识库。

---

## 一、使用前准备

### 1. 确认环境

你的 Mac 上已经配置好了以下内容：

- Python 3（推荐 3.10 及以上）
- `requests` 和 `pyyaml` 两个 Python 包
- Kimi Code CLI 命令 `kimi` 可用（本机位于 `/Users/admin/.kimi-code/bin/kimi`）

检查方式：

```bash
python3 --version
kimi --version
python3 -c "import requests, yaml; print('OK')"
```

如果缺少依赖，安装一下：

```bash
pip3 install pyyaml requests
```

### 2. 确认配置文件

项目根目录下的 `config.yaml` 已经预配置好，一般不需要改动：

```yaml
model:
  name: qwen3.6-27b-awq
  base_url: http://wtb.anzhitek.com/v1/chat/completions

rag:
  url: http://wtb.anzhitek.com/rag/add_knowledge
```

如果旁路模型需要 API key，可以设置环境变量：

```bash
export OPENAI_API_KEY=your_key_here
```

当前本地部署模型通常不验证 key。

---

## 二、启动 Kimi Copilot

### 启动命令

在**真实终端**（不是 VS Code 内置终端、不是 Kimi 工具环境）中执行：

```bash
cd /Users/admin/kimi-copilot
python3 kimi_copilot.py
```

### 启动后你会看到什么

执行命令后，你会直接进入 Kimi Code CLI 的正常交互界面，看起来和平时直接运行 `kimi` 几乎一样：

```
> 
```

或者 Kimi Code CLI 的欢迎信息。

这说明旁路由已经在后台运行，开始监听你的输入和 Kimi 的输出。

---

## 三、日常使用流程

### 1. 正常提问

你可以像平时一样和 Kimi 对话：

```
> 帮我写一个读取 config.yaml 的 Python 函数
```

Kimi 会正常回复，旁路由在后台默默分析。

### 2. 旁路由自动触发

当满足以下任一条件时，旁路由会自动调用旁路模型分析：

| 触发条件 | 示例 |
|---|---|
| Kimi 执行的命令失败 | 终端输出 `Command failed with exit code 1` |
| Kimi 表达不确定 | Kimi 说"我不太确定"、"可能"、"大概" |
| 你输入召唤暗号 | `@check` 或 `@review` |
| 每 N 轮自动触发 | 默认关闭，可在 `config.yaml` 中开启 |
| **qwen 实时扫描** | 每轮对话后自动评估语义风险 |
| **挫败感检测** | 你对 Kimi 表现出不耐烦、不满意，或暗示问题耗时过长 |

除了以上关键词触发，旁路由现在默认还会在每轮对话结束后做一次**轻量级 qwen 实时扫描**。qwen 会阅读最近几轮上下文并输出风险评分（0-10）。当评分超过 `config.yaml` 中 `real_time_scan.threshold` 设置的阈值时，会自动触发详细分析。

这个功能的优势是：即使没有命令失败，也能发现 Kimi 的逻辑错误、语义矛盾、性能隐患等问题。因为 qwen 是本地模型，无 token 消耗，默认开启。

触发后，你可能会在终端里看到类似提示：

```
[Copilot] ⚠️ 旁路模型发现潜在问题
摘要: Kimi 给出的文件读取代码未处理文件不存在的情况
建议: 建议添加 try/except FileNotFoundError 或使用 os.path.exists 判断
[Copilot]
```

如果旁路模型判断值得保存，会自动写入 RAG 知识库。写入成功后，你还会看到：

```
[Copilot] ✅ 知识已写入 RAG
时间: 2026-06-29 19:05:23
标题: Python 读取 config.yaml 最佳实践
[Copilot]
```

这样你就知道旁路由新增了哪些知识，方便后续查看和验证。

### 3. 手动召唤旁路由

任何时候，你都可以输入：

```
> @check
```

或者：

```
> @review
```

旁路由会立即用当前完整会话上下文调用旁路模型分析。

### 4. 打开提示面板

旁路由会把每次发现的问题和已写入 RAG 的知识自动整理到提示面板。在**另一个终端**运行：

```bash
python3 copilot_panel.py --open
```

终端会输出一个本地 URL，并自动打开浏览器，例如：

```
[Copilot] 提示面板：http://127.0.0.1:7788/
[Copilot] 正在打开浏览器...
```

如果不需要自动打开浏览器，可加 `--no-browser`：

```bash
python3 copilot_panel.py --open --no-browser
```

或者在启动前设置环境变量禁用自动打开：

```bash
export COPILOT_PANEL_NO_BROWSER=1
```

用浏览器打开这个地址即可查看面板，里面包含：

- **当前会话**：本次启动后发现的踩坑记录和 RAG 写入。
- **RAG 知识库**：所有已写入 RAG 的知识条目。
- **历史记录**：以往会话中发现的踩坑记录。

每条记录都配有「复制提示发给主模型」按钮，点击即可复制一段整理好的提示词，粘贴到 Kimi 的输入框里使用。

默认端口是 `7788`，如需修改可设置环境变量：

```bash
export COPILOT_PANEL_PORT=8080
python3 copilot_panel.py --open
```

`copilot_panel.py --open` 和 `kimi_copilot.py --panel` 使用完全相同的端口解析逻辑。如果指定端口已被占用，程序会报错退出，而不会自动跳到其他端口，避免端口不一致的困惑。

当旁路由检测到你再次犯了相似的错时，会在终端提示：

```
[Copilot] 🔁 检测到重复踩坑
当前问题: ...
历史相关提示: N 条
运行 python3 copilot_panel.py --open 打开提示面板，可复制提示发给主模型。
```

### 5. 挫败感自动总结（你发脾气时才值钱）

旁路由现在会用 qwen 语义判断你的情绪。当你明显表现出不耐烦、不满意，或暗示 Kimi 花了很长时间没搞定问题时，旁路由会标记当前问题。注意：这里不再用关键词硬匹配，而是让 qwen 理解你的真实意图，所以讽刺、省略、反问等表达也能被识别。

一旦 Kimi 随后的回复看起来已经把问题解决（例如"搞定了"、"解决了"、"现在可以了"），旁路由会自动调用 qwen，把这段"踩坑-解决"过程提炼成 RAG 知识库条目。

触发时你会看到：

```
[Copilot] 😤 检测到你似乎对当前问题不太满意
Kimi 解决后，我会自动把这段经验提炼成知识库条目，避免下次再走弯路。
[Copilot]
```

Kimi 解决并自动总结写入 RAG 后，你会看到：

```
[Copilot] ✅ 已自动总结踩坑经验并写入 RAG
时间: 2026-07-02 17:40:12
标题: Python 中正确读取 YAML 配置文件的方法
[Copilot]
```

这类知识往往比你直接问出来的更有价值——因为它记录了 Kimi 曾经绕过的弯路和最终正确的做法。

### 6. 独立 RAG 收集服务（事后沉淀项目经验）

除了实时旁路由，项目还提供一个独立的 `rag_collector.py` 服务。它专门监听某个 Kimi session 或某个项目目录下的所有 session，在对话自然结束时调用 qwen 判断这段对话是否值得沉淀为知识库条目。

适合的使用场景：
- 你刚结束一个重要问题的排查，想把它自动总结进知识库。
- 你希望安静地后台积累某个项目的经验，不需要实时 wrapper 干预。
- 你想先测试 qwen 的总结质量，再决定是否写入 RAG。

使用示例：

```bash
# 监控单个 session（推荐先用 --once --dry-run 测试）
python3 rag_collector.py --session-id ec414c6e-dd35-461e-9bba-ead77e7d3ac1 --once --dry-run

# 监控某个项目目录下的所有 session（持续运行，按 Ctrl+C 停止）
python3 rag_collector.py --work-dir "/Users/admin/workspace/jyq/qsjnic"

# 后台持续运行，只分析、不写 RAG（验证提示词效果）
python3 rag_collector.py --work-dir "/Users/admin/workspace/jyq/qsjnic" --dry-run
```

qwen 会判断：
- 这段对话基于哪个项目
- 是否值得写入 RAG
- 属于踩坑经验（`pitfall`）、成功经验（`success`）、workflow、config、api 还是 debug
- 标题、问题、错误方案、正确方案、标签和置信度

**主动保存暗示**：如果你在对话末尾说"这个建议总结一下"、"建议保留这个经验"、"记下来"、"存到知识库"、"以后可能用到"，qwen 会识别到你的保存意图，即使问题本身普通也会 worth_rag=true。

**去重机制**：`rag_collector.py` 写入 RAG 前会先检查 `panel.json` 中最近 50 条记录。如果标题或问题与已有 RAG 条目高度相似（相似度 ≥ 75%），则跳过写入，避免同一个经验重复入库。同时 `--once` 模式下同一个 session 被多次运行时，也会跳过已总结过的 session。

配置项在 `config.yaml` 的 `rag_collector` 段：

```yaml
rag_collector:
  poll_interval_seconds: 5      # 轮询间隔
  analysis_cooldown_seconds: 60 # 同一 session 两次分析最小间隔
  silence_window_seconds: 60    # session 静默多久后触发总结
  max_turns_per_analysis: 10    # 每次分析携带的最近 turn 数
  timeout: 60                   # qwen 请求超时
  max_tokens: 1024              # qwen 最大输出 token 数
  judge_prompt: prompts/copilot_rag_judge.txt
```

### 7. 智能干预（Kimi 陷入循环时）

如果 Kimi 连续在相似问题上失败、修了又错，旁路由会自动判定为「陷入循环」，并做以下事情：

1. **查询知识**：优先调用 `config.yaml` 中配置的 RAG 查询接口；如果没配，就使用本地 panel 历史兜底。
2. **综合分析**：把当前上下文、相似历史问题、RAG/本地知识一起发给旁路模型，分析根因。
3. **生成干预提示**：产出一段你可以直接复制发给 Kimi 的「干预提示词」，帮 Kimi 跳出错误思路。
4. **写入面板**：干预建议会高亮显示在面板顶部的「🚨 干预建议」区域。

触发时终端会提示：

```
[Copilot] 🚨 Kimi 似乎陷入了循环
当前问题: ...
根因: ...
运行 python3 copilot_panel.py --open 查看干预建议，可复制提示强行纠正主模型。
```

然后在另一个终端运行 `python3 copilot_panel.py --open`，会自动打开浏览器并显示面板；点击「复制干预提示发给主模型」，把提示词粘贴给 Kimi 即可。

你可以通过 `config.yaml` 调整触发灵敏度：

```yaml
copilot:
  stuck_detection:
    enabled: true
    consecutive_similar_failures: 2  # 连续相似失败多少次视为陷入循环
```

### 8. 继续对话

看到提示后，你可以直接继续和 Kimi 对话，旁路由的提示只是提醒，不会打断 Kimi 的正常工作。

---

## 四、退出

退出方式和正常 Kimi Code CLI 一样，通常输入：

```
> /exit
```

或者按：

```
Ctrl + D
```

如果卡住了，可以按：

```
Ctrl + C
```

然后按 `Ctrl + C` 两次可以强制退出 wrapper。

---

## 五、本地模拟测试

如果你不想启动 Kimi Code CLI，只想测试旁路由的分析和 RAG 写入功能，可以运行本地测试：

```bash
cd /Users/admin/workspace/jyq/kimi-copilot
python3 tests/test_brain.py
```

这个测试会构造一段模拟会话，触发旁路模型，并尝试写入 RAG。

---

## 六、文件说明

```
kimi-copilot/
├── README.md              # 本使用说明
├── workflow.md            # 设计文档
├── config.yaml            # 配置文件
├── kimi_copilot.py        # 启动入口（PTY wrapper）
├── brain.py               # 旁路由核心逻辑
├── copilot_panel.py       # 提示面板（HTML 仪表盘）
├── panel.json             # 面板持久化数据（自动生成）
├── panel.html             # 面板页面（自动生成）
├── prompts/
│   ├── copilot_system.txt        # 旁路模型提示词
│   ├── copilot_stuck.txt         # 陷入循环时的旁路模型提示词
│   ├── copilot_scan.txt          # 实时扫描提示词
│   └── copilot_frustration_rag.txt  # 挫败感-解决弧自动总结提示词
└── tests/
    ├── test_brain.py      # 本地模拟测试
    ├── test_scan.py       # 实时扫描测试
    └── test_rag_write_manual.py  # RAG 写入测试
```

---

## 七、常见问题

### Q1：为什么一定要在真实终端里启动？

因为 `kimi_copilot.py` 使用了 PTY（伪终端）技术来捕获 Kimi Code CLI 的输入输出。某些 IDE 内置终端、CI 环境或非 TTY 环境不支持 PTY，会导致启动失败或行为异常。

### Q2：旁路由会影响 Kimi 的正常使用吗？

不会。旁路由只是监听和转发数据，所有交互体验和你直接运行 `kimi` 基本一致。

### Q3：旁路模型的提醒会打断我吗？

不会。提醒以文本形式插入终端，你可以继续输入。

### Q4：RAG 写入失败了怎么办？

旁路由会在日志中输出错误信息。你可以在启动前开启更详细的日志：

```bash
export LOG_LEVEL=DEBUG
python3 kimi_copilot.py
```

或者检查 `config.yaml` 中的 RAG 地址是否可访问。

### Q5：我不想让旁路由写入 RAG，可以吗？

可以。临时关闭 RAG 写入，把 `config.yaml` 中的 `rag.url` 注释掉或留空：

```yaml
rag:
  url: "" 
```

---

## 八、快速参考

```bash
# 启动
cd /Users/admin/workspace/jyq/kimi-copilot && python3 kimi_copilot.py

# 手动触发旁路分析
@check

# 打开提示面板（在另一个终端执行，会自动打开浏览器）
python3 copilot_panel.py --open

# 不自动打开浏览器
python3 copilot_panel.py --open --no-browser

# 退出
/exit

# 本地测试
python3 tests/test_brain.py
```