MATLAB 编程助手（matlabassitant）

一个以 DeepSeek API 驱动的 MATLAB 编程辅助工具，覆盖代码生成、解释、调试、审查与测试五大场景。项目包含两个方向的实现，当前已完成并上线的是 DeepSeek Harness Web 客户端插件。

源码归档：本仓库 limit/ 目录（@deepseek-ai/dsh-client-matlab-assistant，含源码、测试与安装指南） 在线运行版：部署于 DeepSeek Harness 仓库的 packages/client/matlab-assistant/

---

一、功能全景

1. 五大编程能力（同一会话内可随时切换）

能力	输入	输出
生成与补全	需求描述；或半成品代码 + %%CURSOR%% 续写标记	可直接运行的完整 MATLAB 代码 + 使用说明
解释代码	任意 MATLAB 代码	逐段解释、关键语法/维度分析、改进建议
调试修复	代码 + 报错信息（可选）	错误根因分析 + 修复后的完整代码
审查优化	代码	正确性/性能/健壮性/可读性四维审查报告 + 优化代码
测试生成	被测代码 + 测试要求（可选）	matlab.unittest 单元测试脚本 + 运行方式

所有能力共享同一套 MATLAB 专属人设提示词（向量化优先、中文注释、工具箱假设标注），保证输出风格一致。

2. 会话与上下文管理

• 工作区 → 会话两级结构：左侧栏为工作区（通过浏览器"选择文件夹"创建，回退到名称输入），一个工作区可开多个会话，每个会话有独立的历史记录（消息、输入草稿、附件、当前能力标签）
• 多轮对话：每次发送自动重放会话近期历史作为上下文，按 128k tokens 预算从最新向最早截断
• 上下文圆环：会话头部环形进度显示已用/总预算（128k），超过 80% 变琥珀色
• 会话管理：新建/重命名/删除会话，删除工作区，会话与工作区数据随选随恢复

3. 本地文件支持

• 输入区可上传本地文件（多选），作为 【参考文件】 文本块注入请求，模型可直接阅读
• 仅文本文件（.m .mlx .txt .csv .json .py .c .cpp .java .ts .sql .tex 等），单文件 ≤ 256KB、每会话 ≤ 10 个 / 1MB，超限有中文提示
• 每个附件进入请求时按 4000 tokens 截断，防止撑爆上下文

4. 数学公式

• 输入区支持 LaTeX 公式（$...$ / $$...$$），并有 Σ 插入公式 快捷按钮（光标处插入定界符）
• 输出经 KaTeX 渲染，公式以真正的数学排版显示

5. 输出与交互

• 流式输出（SSE），可随时停止
• 代码块主题高亮（深/浅色自适应）+ 语言标签 + 一键复制；消息级复制
• 上下文中的历史消息完整呈现（用户请求 + 助手回复 + 时间戳 + 能力标签）

6. 数据安全与持久化

• API Key 只存浏览器（localStorage），只发往 DeepSeek 端点，绝不经过 DSH harness；可随时清除
• 模型可选（deepseek-v4-flash / deepseek-v4-pro 及旧别名），API 地址可自定义（支持代理/网关）
• 历史存于专用 IndexedDB 数据库（dsh-matlab-assistant）：服务重启、插件升级、浏览器清理策略变化均不丢失；localStorage 保留为镜像与旧数据迁移源
• 设置抽屉支持一键导出/导入 JSON 备份，可离线保管

---

二、技术架构

packages/client/matlab-assistant/
├── src/client/
│   ├── index.ts                 # 插件入口：注册到侧边栏 footer.action 槽位
│   ├── MatlabAssistantAction.tsx # 侧边栏入口按钮 + 模态框
│   ├── MatlabAssistantPanel.tsx  # 主面板：状态编排、流式发送、持久化调度
│   ├── WorkspaceSidebar.tsx      # 左侧栏：工作区/会话列表（纯展示）
│   ├── SessionPane.tsx           # 会话视图：圆环/能力条/消息流/输入区
│   ├── ContextGauge.tsx          # 上下文占用环形进度（纯 SVG）
│   ├── deepseek.ts               # DeepSeek 客户端：prompt 组装、SSE 解析、错误归一
│   ├── store.ts                  # 数据模型：工作区/会话/消息/附件 + token 估算
│   ├── persistence.ts            # IndexedDB 持久化层（自动降级 localStorage）
│   ├── settings.ts               # API Key/模型/地址持久化
│   └── locales.ts                # 中/英文案字典
└── tests/                        # 5 个测试文件，86 个用例

关键设计

• 纯浏览器直连：插件直接 fetch DeepSeek API（已验证 CORS），不经过 harness 代理，Key 不外泄
• 流式解析健壮：SSE 按行增量解析，content: null 的思考帧自动跳过，错误按状态码归一为中文提示（401 密钥无效 / 402 余额不足 / 429 限流）
• 升级安全：存储读取对缺失字段宽容（补默认值而非丢弃）；面板首次打开只读不写，杜绝"打开即覆盖旧数据"
• 前端约束：零组件库依赖（纯 CSS Modules + 主题 token）、无 React Context、状态全部组件化、可测试性优先

质量验证

• 单元/组件测试 86/86 通过（含类型检查全绿）
• 通过 DSH 仓库全部相关门禁：constraints、README 中英配对、Model Experience、包不变式
• 开发链路：pnpm run dev:web 热更 bundle，HMR 自动重载，http://127.0.0.1:3080 验证

---

三、使用指南

1. 打开 DSH Web GUI（http://127.0.0.1:3080），刷新浏览器
2. 侧边栏底部点击 MATLAB 助手 按钮
3. 右上角 ⚙ 设置 → 填入你自己的 DeepSeek API Key（sk- 开头）→ 保存
4. 左侧 新建工作区（选择文件夹）→ 新建会话
5. 选能力标签页 → 输入内容（可上传文件、插入公式）→ 发送（或 Ctrl+Enter）
6. 日常建议：会话做完后到设置里导出数据备份一次

---

四、已知限制与路线图

当前限制

• 附件仅文本格式（.mat 等二进制被拒）；单文件 256KB 上限
• 持久化在浏览器内（IndexedDB），不跨浏览器/机器同步；真正的服务器磁盘存储需新增 DSH host RPC
• 工作区文件夹选择依赖 Chromium 内核（其他浏览器回退为名称输入）

路线图

• 方向二：MATLAB Add-On（App Designer）——复用同一套 prompt 与能力设计，把助手嵌入 MATLAB 编辑器，直接读写活动文档
• DSH host 存储 RPC：历史真正落到服务器磁盘，跨浏览器可见
• 会话手动上下文管理（固定/清除指定历史段）
• 附件类型扩展（.mat 结构化读取、图片等）

---

文档更新于 2026-08-14，与插件当前实现一致。