# Kimi Copilot 旁路监督工作流

## 目标

实现一个 Python 旁路监督系统：

1. 监控 Kimi Code CLI 的输入输出。
2. 当检测到潜在错误、命令失败或用户主动召唤时，调用本地旁路大模型 `qwen3.6-27b-awq` 分析。
3. 将高价值的纠正方案写入 RAG 知识库，形成可检索的知识积累。

## 适用约束

- 单用户、单会话使用，不考虑并发。
- 使用 Python 全栈开发，优先开发效率。
- 旁路模型接口：`http://wtb.anzhitek.com/v1/chat/completions`。
- 模型名：`qwen3.6-27b-awq`。
- 上下文窗口：`65536` tokens。
- RAG 写入接口：`http://wtb.anzhitek.com/rag/add_knowledge`。
- 经测试，当前部署默认不输出 `<think>` 标签，无需额外传 `enable_thinking=false`。

## 整体架构

```
[用户终端]
    ↑↓
[kimi_copilot.py]   ← PTY wrapper + 流程编排
    ↑↓
[Kimi Code CLI]     ← 主工作模型
    ↓
[brain.py]          ← 上下文维护 + 触发判断 + 旁路调用 + RAG 写入
    ↓
[qwen3.6-27b-awq]   ← 旁路分析模型
    ↓
[RAG 知识库]
```

## 数据流

1. `kimi_copilot.py` 通过 `pty` 启动 Kimi Code CLI。
2. 用户输入同时转发给 Kimi 和 `brain` 上下文模块。
3. Kimi 输出同时显示给用户和 `brain` 上下文模块。
4. 触发器根据关键词规则决定是否调用旁路模型（高优先级、快速响应）。
5. 若关键词未触发，`brain` 会启动**实时 qwen 扫描**，对最近几轮上下文做轻量级风险评分。
6. 当风险评分超过阈值时，调用旁路模型做详细分析。
7. 旁路模型收到完整上下文，返回结构化 JSON。
8. 如果 `worth_rag=true`，调用 RAG 接口写入知识。

## 上下文维护

`brain` 维护一个消息数组：

```python
history = [
    {"role": "user", "content": "帮我写一个读取文件的函数"},
    {"role": "kimi", "content": "好的，这是代码..."},
    {"role": "tool", "content": "Command failed with exit code 1"},
]
```

- 角色：`user`、`kimi`、`tool`。
- 对 Kimi 输出做 ANSI strip 和基本清洗。
- 当接近上下文上限（如 60K tokens）时，保留最早的需求描述和最近的对话，做滑动窗口截断。

## 触发条件

| 触发条件 | 优先级 | 说明 |
|---|---|---|
| 命令失败 | 高 | 终端输出匹配 `Command failed`、`error`、`exit code != 0` 等 |
| 用户召唤 `@check` | 高 | 用户输入包含 `@check` 或类似暗号 |
| Kimi 表达不确定 | 中 | Kimi 回复包含"我不确定"、"可能"、"大概"等 |
| 定时轮询 | 低 | 每 N 轮对话自动触发一次（默认关闭，可配置） |
| qwen 实时扫描 | 中 | 每轮对话后由 qwen 做语义风险评分，超过阈值触发详细分析 |

## 旁路模型输出格式

旁路模型必须返回可解析的 JSON：

```json
{
  "has_issue": true,
  "severity": "low|medium|high",
  "summary": "问题摘要",
  "suggestion": "纠正建议",
  "worth_rag": true,
  "rag_entry": {
    "title": "xxx",
    "question": "原始问题",
    "wrong_approach": "Kimi 的错误做法",
    "correct_approach": "推荐做法",
    "tags": ["python", "file-io"]
  }
}
```

- `has_issue=false` 时，不提醒用户，不入 RAG。
- `worth_rag=false` 时，只显示提醒，不入 RAG。

## RAG 写入格式

```json
{
  "title": "Node.js 文件读取最佳实践",
  "content": "问题：如何正确读取文件？\n错误做法：fs.readFileSync 阻塞主线程。\n正确做法：fs.promises.readFile + async/await。\n标签：nodejs, file-io"
}
```

## 项目结构

```
kimi-copilot/
├── workflow.md              # 本文件
├── README.md                # 使用说明
├── config.yaml              # 配置文件
├── kimi_copilot.py          # 入口：PTY wrapper
├── brain.py                 # 核心逻辑
├── prompts/
│   └── copilot_system.txt   # 旁路模型 system prompt
└── tests/
    ├── test_brain.py        # 单元测试
    └── mock_session.json    # 模拟会话数据
```

## 实现步骤

1. 设计架构与接口契约（本文件）。
2. 实现 `kimi_copilot.py`：PTY wrapper 捕获 Kimi Code CLI 输入输出。
3. 实现 `brain.py` 中的上下文管理。
4. 实现旁路模型调用模块。
5. 实现触发策略。
6. 实现 RAG 写入模块。
7. 本地模拟测试：用 mock 数据验证旁路判断和 RAG 写入。
8. 真实接入 Kimi Code CLI 跑通闭环。
9. 验证并优化：减少误判、控制调用频率。

## 测试闭环

- 构造一段 Kimi 犯错的模拟会话。
- 触发旁路分析。
- 确认旁路模型正确识别问题。
- 确认 RAG 成功写入。
- 查询 RAG 确认知识可检索。
- 在真实 Kimi Code CLI 会话中复现一次。