# Qwen Code 教学协同环境配置指南

版本：v1.0
日期：2026-08-19
适用：五本人工智能教材的全部实践资源

---

## 一、为什么选择 Qwen Code

Qwen Code 是命令行/编辑器内的AI协同开发工具，学生可以在本地环境中：
- 用自然语言描述任务，AI生成代码和修改建议
- 查看每次修改的差异（diff），决定接受或拒绝
- 在AI协助下完成专业领域技术（C语言、硬件配置、复杂算法），不被技术门槛卡住
- 保留完整的协同记录，形成可审计的证据链

**核心原则：AI负责扩大候选方案和加速实施，学生负责审查、判断和决定。**

## 二、两条模型路径

### 路径A：本地模型（推荐，主路径）

**优势**：免费、不依赖网络、无token费用、数据不外发、课堂统一

**配置步骤**：

1. 安装 Ollama（或课程批准的其他本地模型服务）
2. 下载课程推荐的模型：
   ```powershell
   ollama pull qwen2.5:7b
   ```
3. 配置 Qwen Code 连接本地模型：
   - 在 Qwen Code 设置中配置 OpenAI 兼容接口
   - Base URL: `http://localhost:11434/v1`
   - Model: `qwen2.5:7b`
   - API Key: 留空或填 `ollama`（本地不需要真实密钥）

**硬件要求**：
- 最低：8GB 内存，可运行 7B 量化模型
- 推荐：16GB 内存或独立 GPU，运行更快
- 如果机器不够：使用路径B，或课程提供的局域网共享模型服务

**能力检查**：
- `chat`：文本对话和代码生成 ✅ 7B 即可
- `embedding`：文本向量化 — 需要 `nomic-embed-text` 或类似模型
- `vision`：图像理解 — 需要 `qwen2.5-vl` 系列
- `tool_call`：工具调用 — 7B 支持，但稳定性不如更大模型

> 不是所有能力都需要本地运行。缺少某项能力时，教学资源提供预计算结果、录制输出或模拟提供者作为离线基线。

### 路径B：云端API（备选）

**适用场景**：本地机器性能不足、需要更强的模型能力、教师演示

**配置步骤**：

1. 获取课程批准的API密钥（学校统一提供或课程网关）
2. 配置 Qwen Code：
   - Base URL: 课程提供的API地址
   - Model: 课程指定的模型名称
   - API Key: 从环境变量读取，**不写入代码、Notebook或截图**

**安全规则**：
- API密钥只从环境变量读取
- 不将密钥写入任何文件、Notebook、截图或提交包
- 只发送完成任务必需且已脱敏的最小内容
- 摄像头帧、人脸、证件等敏感内容不得发送给云端模型

## 三、Qwen Code 课堂使用规范

### 3.1 工作区限定

- Qwen Code 的工作目录限定在当前章节项目目录内
- 不允许读取或修改其他章节、系统文件或用户私人文件
- 安装依赖、运行命令、访问硬件、联网操作前必须学生确认

### 3.2 五段协同留痕

第1-3章完整训练五段留痕；第4章以后只对本章关键修改保存证据。

```
1. 学生原始意图：我想完成什么，输入、输出和禁止事项
2. AI方案：Qwen Code 建议怎样做，涉及哪些文件和参数
3. 人工审查：学生接受、拒绝或改写了什么，理由是什么
4. 实际变更：查看差异后批准的最小修改，运行证据
5. 最终判断：结果是否达到验收，哪里可靠、哪里需要复核
```

记录可保存在 `ai_collaboration_log.md` 或 Notebook 的对应单元中。

### 3.3 学生不能做的事

- 不能把AI输出直接当作最终结论，必须审查和验证
- 不能自动批准所有修改，必须逐个查看差异
- 不能在未经教师确认的情况下安装软件或修改系统配置
- 不能将敏感数据发送给云端模型

### 3.4 学生必须做的事

- 每次AI协同后，至少保留一次完整的五段证据
- 修改前先写预测，修改后用结果验证
- 能说清"改了什么、为什么改、结果是否支持判断"

## 四、离线降级方案

当 Qwen Code 或模型服务不可用时：

| 情况 | 降级方案 |
|---|---|
| 本地模型服务未启动 | 启动 Ollama，或切换到录制输出 |
| 本地机器性能不足 | 切换到云端API，或使用预计算结果 |
| 网络不可用 | 使用 `mock_provider`、录制输出和 HTML 观察页 |
| Qwen Code 不可用 | 学生手动按教程步骤操作，AI协同部分用预录的对话截图替代 |

**核心原则：网络、模型或工具失败时仍能上课。** 离线模式不降低学习目标，只改变实现路径。

## 五、与印刷教材的关系

- 印刷教材讲稳定的概念、原理和方法
- Qwen Code 的版本、安装步骤、界面位置等易变信息放在本帮助页和在线模型卡中
- 印刷教材中的操作路径保持可用，不因工具升级而失效

## 六、权威链接

| 资源 | 地址 |
|---|---|
| Qwen Code 官方文档 | 待补充（以课程提供的版本为准） |
| Ollama 官方文档 | https://ollama.com/ |
| Python 中文文档 | https://docs.python.org/zh-cn/3/ |
| VS Code 官方文档 | https://code.visualstudio.com/docs |
| Jupyter 官方文档 | https://docs.jupyter.org/zh-cn/latest/ |
| TensorFlow 中文教程 | https://tensorflow.google.cn/tutorials?hl=zh-cn |
| 阿里云百炼模型服务 | https://help.aliyun.com/zh/model-studio/ |

> 外部接口和模型名称会变化。课程提供的模型卡应记录检查日期、服务地址、模型显示名称、能力类型和离线替代路径。