# 毕业设计 · 进度记录

> 本文件记录"端云协同编程智能体系统"作为**毕业设计**推进过程中的关键决策、产出与待办。
> 对应仓库文档：`实现方案_v2_端云协同编程智能体系统.md`（系统权威方案）、`实现方案_v3_Web应用化.md`（Web 应用化设计）、`references/毕业论文_参考文献清单.md`（参考文献）。

---

## 一、本次推进的议题（按时间顺序）

1. **毕业设计命题**：为"端云协同 LLM 协作系统"拟定可行的毕业论文命题。
2. **参考文献核实与下载**：确认命题能否找到对应中英文文献，并落地下载。
3. **Web 应用化技术选型**：确定"把整体项目做成 Web 应用"的技术栈与架构，并定稿设计方案。

---

## 二、关键决策记录

### 2.1 命题方向（已定）
- 对象：本科 · 计算机科学与技术；侧重 **端云协同架构**。
- **推荐命题**（2026-08 版，已被下条取代）：《基于端云协同的 LLM 服务成本优化系统设计与实现》（副标题：——以异构大小模型非对称协作为核心）。
- **✅ 定稿命题（2026-09-04）**：《基于端云协同的编程智能体系统设计与实现》（Design and Implementation of a Programming Agent System Based on Device-Cloud Collaboration；关键词：端云协同、编程智能体、大小模型协同、工具调用、级联升级）。改题理由：v4 落地后系统已是工具智能体形态（可操控工作目录文件），"编程智能体"更贴实现与演示重心；"成本优化"降为论文核心指标与实验章主题（北极星指标不变），不进标题。项目名/方案文档名/界面品牌已同步由"端云协同 LLM 协作系统"更名为"端云协同编程智能体系统"。
- 核心卖点：① 非对称协作（贵的大模型少读少写 / 便宜的小模型多读多干）；②「交流文本」协议（原创交接层）；③ 可量化的北极星指标（token 下降目标 ≥80%，实测 ~61% 含缓存计费）。
- 定位判断：这是**系统/工程类**毕设，非新算法类；命题应落在"面向成本约束的协作机制设计与实现"，避免宣称"提出了新模型/新方法"。
- 提醒：北极星指标在论文中勿写死"80%"，表述为"缓存计费下下降约 61%，结合前缀缓存复用目标 ≥80%"。

### 2.2 参考文献（已落地）
- 确认命题**文献充足**：已有英文路由/级联文献极强，另有"端云协同/大小模型协作"方向专门综述。
- **外文已下载 5 篇**（`references/arxiv_papers/`，已验证有效 PDF）：
  - 14 FrugalGPT (2305.05176)
  - 15 Small Models in the LLM Era Survey (2409.06857)
  - 16 Dynamic Model Routing & Cascading Survey (2603.04445)
  - 17 Edge SLMs + Cloud LLMs Collaboration Survey (2507.16731) ← 与命题几乎同名
  - 18 Collaborating Small and Large LLMs Survey (2510.13890)
- **中文文献**：由**使用者本人走校园网知网下载**到 `research/`（如《Token级多模型并联协作推理_王建辉》《大小模型端云协同进化技术进展_王永威》《大语言模型时代的人工智能_陈光》等）；另有开放获取的《大语言模型算法演进综述_中兴通讯技术》存于 `references/cnki_open/`。
- **提醒**：所有中文文献定稿前必须在知网逐条核对页码/作者/年份；外文 14–18 可放心引用。

### 2.3 Web 应用化技术选型（已定）
- **后端**：保持 **Python + FastAPI + uvicorn，不重写**（`router_system` 为纯标准库，229 项测试全绿）。
- **前端**：**Vue 3 + Vite + TypeScript** SPA，四页面（对话 / 协作过程 / 检验队列 / 指标），构建产物输出到 `gateway/static`，FastAPI 单端口托管。
- **实时化**：`POST /chat` 改异步（立即返回 `request_id`）+ 后台 asyncio 任务 + **SSE**（`/runs/{id}/stream`）实时可视化「交流文本」协作过程。
- **关键约束（D3）**：SSE 通过**监视 `runs/{id}/workspace.json`** 实现，**不修改 `router_system/pipeline.py`**，保住测试全绿。
- **避坑**：不上 Celery/Redis/微服务；asyncio + sqlite + 文件系统足够。
- 完整设计见 **`实现方案_v3_Web应用化.md`**（含 D1–D9、SSE 协议、目录结构、T1–T6、验收标准）。

---

## 三、本次产出文件

| 文件 | 说明 |
|---|---|
| `实现方案_v3_Web应用化.md` | Web 应用化权威设计方案（技术栈/架构/接口/步骤/验收） |
| `references/毕业论文_参考文献清单.md` | 参考文献初稿清单（已下载 / 需知网下载 / 提醒） |
| `references/arxiv_papers/14–18_*.pdf` | 5 篇新增外文文献（有效 PDF） |
| `references/cnki_open/中_大语言模型算法演进综述_中兴通讯技术.pdf` | 1 篇开放获取中文 PDF |
| `research/` 下多篇中文 PDF | 使用者自行从知网下载的中文文献 |

> 说明：`git status` 中 `router_system/`、`scripts/`、`tests/` 等处的改动为**本会话之前已存在的历史修改**，非本次 Web 应用化产出。

---

## 四、待办 / 下一步

1. **实施 Web 应用化**（按 `实现方案_v3_Web应用化.md` T1→T6）：
   - T1 后端异步化（`jobs.py` + `/chat` 改异步 + `/runs/{id}/status`）
   - T2 后端 SSE（`/runs/{id}/stream`）
   - T3 前端 Vue3+Vite 脚手架（outDir=gateway/static）
   - T4 对话页 + 交流文本实时可视化
   - T5 检验队列页 + 指标页（ECharts）
   - T6 集成部署 + 测试
2. **收尾答辩材料**：补齐中文文献题录（知网核对）、论文各章节、E1 `--live` 真实链路数据。
3. 将 v3 方案登记进 `任务拆解与执行计划.md`，并把 AGENTS.md 的"当前权威规划"指针同步到 v3。

---

*记录人：DSH Agent（2026）。*

---

## 五、2026-09-01 推进：模型池 + 工具智能体（叙事升级落地）

### 5.1 关键决策
- **叙事泛化（命题不变）**：把「端云分工」泛化为**按价位分工**——代码里角色轴
  （Architect 决策 / Worker 实现）与位置轴本来就正交（ArchitectClient 走 OpenAI 兼容协议、
  Worker 已有 mock/llama_server/openai 三后端），故"端云协同"收编为"多价位模型池"的两档特例。
  命题标题、开题材料、文献锚点全部不动，系统叙事升级（答辩加分项）。
- **术语**：对外表述用「多价位模型协作 / 分级调度 / 异构模型池」，**避免"融合"**
  （会被理解为模型级 ensemble）。FrugalGPT（文献 14）为新叙事主锚点。
- **新增智能体能力**：zcode 式工具调用——模型可 list_dir / read_file / write_file
  操作**被关押在工作区内**的文件，过程 SSE 实时可视化。
- 设计全文：`实现方案_v4_模型池与工具智能体.md`（D1–D6、接口清单、T16–T21、实验设计）。

### 5.2 产出
- 后端：`router_system/tools.py`（纯标准库工具内核）、`gateway/model_pool.py`（模型池）、
  `gateway/agent.py`（智能体服务）、`/pool` + `/agent` 全套端点、V2Stats 按模型分账。
- 前端：设置页「模型池」区块（角色指派/条目 CRUD/连通测试）、新「🤖 智能体」页
  （工具时间轴 + 工作区文件浏览）、指标页「按模型分账」卡。
- 顺手修复：SSE final 后重连回放导致的重复渲染；`/agent` 深链 SPA 路由。
- **测试**：全量 262 passed（基线 229 + 新增 33：tools 11 / pool 10 / agent 6）。
- **端到端实测**（DeepSeek 真跑 3 轮）：写 hello.py → 写 note.md+列目录 → 读 hello.py 审阅，
  工具事件实时渲染、工作区真实落盘、路径越界被拒、token 计量正确。

### 5.3 下一步
1. 论文表述更新：系统架构图加入"模型池 + 价位轴"；补一节工具智能体与护栏设计。
2. 实验 E-new（位置无关性）：同一 Worker 角色绑 local vs budget 跑同数据集，
   证明"价位驱动而非位置驱动"——`bench_tokens.py` 改造可跑。
3. Worker 步骤级工具化（可选增强）：协作管线内 Worker 也可用工具构建工件（opt-in 开关）。
4. 中文文献知网核对仍待完成（定稿前必做）。

*记录人：DSH Agent（2026）。*

### 5.4 增补（同日）：工作区选择 + harness 级工具（T22–T25）

- **需求来源**：智能体原先只能固定操作 `agent_workspace/`，"不能选择工作区"。
  参考 `deepseek-harness/`（DeepSeek 开源 agent harness）的"打开文件夹"体验与工具集设计。
- **落地**：① 工作目录可选——`/agent/fs` 磁盘目录浏览（Windows 盘符枚举）+
  最近工作区列表（持久化），运行记录所用目录，左侧文件面板跟随切换；
  ② 工具升级到 harness 级——`edit_file`（old_string 唯一命中才替换，防误改）、
  `search_files`（跨文件内容搜索，跳过 .git/node_modules 等）、
  `run_command`（**默认关闭**，UI 开关 allow_shell，超时+输出截断+Windows 无窗口）；
  ③ 前端 edit_file 渲染为红/绿 diff 卡，命令卡展示 `$ 命令` 与退出码输出。
- **实测**：选定 `E:\agent_demo\greet_app`，模型完成"读文件 → edit_file 加参数校验 →
  运行 python greet.py 验证"，磁盘文件真实变更（出现 __pycache__ 证明命令在工作区内执行）。
- **测试**：全量 274 passed（新增 12：tools 扩展 7 + 工作区选择 5）。
- **安全边界（论文可写）**：文件操作相对所选根关押；shell 独立开关默认关；
  唯一性约束防覆盖式误编辑——"能力开放 + 边界收窄"的设计权衡可作一节。

### 5.5 增补（同日）：两级智能体（T26，路线 B 落地）

- **形态**：大模型（规划者）拆解任务出指令 JSON → 本地小模型（执行者）跑工具轮并汇报 →
  大模型审查裁决 done/redo（有界交接，默认 2 轮）→ 最终答复。交接状态落
  `handoff.json`（智能体版交流文本），SSE 新增 phase/message 事件实时可视化。
- **测试**：+3 项（done 流 / redo 流 / 执行者故障），全量 277 passed。
- **事故与修复**：发现 `test_config_get_put_reset` 调 /config/reset 会清空真实
  settings.json——此前全量跑测把用户在设置页配置的 API key 抹掉了。已修复测试隔离
  （备份/恢复），并向用户说明需重配 key。
- **运维提醒**：网关用 taskkill /T 停止会连带杀掉其启动的 llama-server 子进程；
  重启网关后需在设置页重新启动 llama-server。

### 5.6 增补（同日）：Web 界面视觉升级

- 全局设计系统 `webapp/src/style.css`（设计令牌：色板/圆角/阴影/统一滚动条/焦点环），
  main.ts 正式引入（原为未使用的脚手架残留）。
- App.vue 重设计：顶部条 → 深色侧边栏壳（渐变 Logo、图标导航、激活态高亮条、网关状态脚注）。
- 各页浅层打磨：页面背景令牌化、卡片统一阴影、浏览器标题/lang 修正（原为"webapp"/en）。
- 功能零改动；构建产物同步。

### 5.7 增补（同日）：配色体系对齐 deepseek-harness Web

- 从 `deepseek-harness/packages/client/ui-theme/src/styles/design-platform.css` 提取
  官方色板（dsw-static-*）：DeepSeek 品牌蓝 deepseek-500 rgb(65,118,230)、
  bluish 中性灰阶、语义状态色，替换自拟配色。
- 风格修正：深色侧栏 → dsh 式**近白侧栏**（sidebar-fill bluish-50 + 透明描边）；
  扁平化阴影（描边负责层次）；交互悬停 rgba(38,49,72,.06)；滚动条 neutral-200 圆头。
- 全部视图旧硬编码蓝（#2563eb 系）批量替换为设计令牌，视觉单一来源。

### 5.8 增补（同日）：会话式智能体（T27，功能补齐 + 简洁化）

- **差距分析**（对照 deepseek-harness Web）：缺会话制、缺停止、非对话式布局。
- **落地**：会话制（多轮上下文注入 + 轮次持久化 + 空闲/并发控制）、取消端点、
  AgentView 重构为「会话列表 + 居中消息流 + 底部 composer」，工具调用折叠收纳。
- **实测**：本地 Qwen0.8B 全流程走通（会话自动创建/轮次记录/折叠时间轴/空响应提示）；
  深度协作质量待用户重配 DeepSeek key 后验证。
- **测试**：281 passed（新增 4：history 注入/会话多轮/置忙拒绝/取消）。
- **教训**：测试资源隔离清单再+1（settings.json、sessions 目录、pool.json、runs/）。

## 六、2026-09-04 推进：新方向立项——校园 AI 代理层

- **用户定调**：`AI代理功能开发/` 子目录定位为「端 ↔ 云之间的 AI 代理层」开发：
  面向校园场景的 LLM API 代理网关（如代理 DeepSeek key，学生持代理 key、代理持上游主 key）。
  商业模式 = **API 差价 + 缓存收益**；校园问题高重复 → 高缓存命中 → 高毛利；校园网提供基础设施。
- **方案草案**：`AI代理功能开发/方案_校园AI代理层.md`（架构 / 缓存经济学 / 现有系统复用映射 /
  MVP 任务 P1–P5 / 合规红线 / 实验 E-P1–E-P3）。
- **与主命题关系**：不改变已定命题《基于端云协同的编程智能体系统设计与实现》；
  作为扩展章与答辩亮点——代理层 = 端侧基础设施的规模化形态，核心贡献为"缓存感知的 LLM 代理网关"。
- **合规提醒（实现前必读）**：真实收费运营前需确认上游转售政策与生成式 AI 服务备案要求，
  从校内试点起步；上游主 key 仅存 env / settings.json，代码与文档零凭据字面量。

*记录人：ZCode Agent（2026-09-04）。*

---

## 六、2026-09-05 推进：代理层 M1 + 语义分析器全链（T-P/T-G）

### 6.1 代理层与缓存层（T-P0…T-P5，M1 达成）
- 备份锚点：tag `proxy-m1-tp5`（370 全绿）+ 仓库外 zip。
- 落地：gateway/proxy/ 十模块——鉴权账本（原子预扣 D-P11，并发 10 路不超扣实证）、
  上游客户端（三家 usage 归一/首 token 前 failover D-P4）、毫元计价（差异化售价），
  路由端到端（M1：httpx 手写 OpenAI SDK 合规断言，2550/1491 黄金账目）、
  规范化五规则。T-P6 语义缓存（M2）/T-P7 管理面前端/T-P8 压测（M3）待续。

### 6.2 语义分析器与三级分级（T-G0…T-G8 全链完成，M-G3 代码就绪）
- T-G0 骨架 → T-G1 Embedder（int8 量化）→ T-G2 观察埋点（100ms 批量）→
  T-G3 标签校准（四规则推导 + split-conformal + last-good）→
  T-G4 线性头（numpy 训练 + 纯 Python 推理，requirements-ml.txt 登记）→
  T-G5 Grader（特征门×概率×conformal，/v1/route）→
  T-G6 live 分流（pipeline tier_fn 钩子，D-G5 唯一受控改动，零回归）→
  T-G7 审计+前端（proxy 档位映射 + X-Campus-Tier 头 + T1 审计抽样 +
  Metrics tier 卡 + Settings 灰度区块）→ T-G8 E-G1 报告（晋升门自动判定）。
- **灰度纪律（D-G7）**：sense.enabled=false、mode=collect——代码全就位但
  分流未启用；晋升门四条（一致率≥85%/覆盖≤α+2%/标签≥500/T1 占比 40-55%）
  由 sense_report.py 自动判定，collect 攒满前不开 live。
- 测试：412 passed（318 → 412，本阶段 +94）。

### 6.3 下一步
1. 代理层 T-P6（语义缓存 M2）→ T-P7 管理面前端 → T-P8 压测（M3）。
2. 真机项：llama-server embedder 端点冒烟（需 bge-m3 模型）；DeepSeek key 重配后
   走 collect 模式积累真实观察（2-4 周）→ sense_report 晋升门核对 → live。
3. 备份锚点：`sense-m-g3` tag（412 全绿）。