_{📷 真实运行截图：MATLAB R2025b 桌面内停靠的 Copilot 面板 · 工具调用卡 · 富文本表格回答 · 整排快捷动作 · Claude Code / opus 工具栏}

_{🎨 界面元素图解（标注示意）：用户气泡 / 助手·思考 / 工具调用 / 权限确认 / 成本状态的配色与布局}

📌 这是什么

官方 MATLAB Copilot / Simulink Copilot 在中国无法使用。本项目自研一套同类工具，核心价值是 「原生内嵌的 UI 外壳 + 把已跑通的 agent 能力搬进 MATLAB 界面」，并做到能力只多不少：

• 🧠 大脑 = 你自己的 Claude Code 或 Codex CLI（绑定你的账号/订阅，可运行时切换）
• ✋ 手 = 复用官方 MATLAB MCP Server（读写你的实况模型与工作区）
• 🪟 外壳（本项目）= 进程内原生可停靠面板 + 上下文感知 + 权限确认 + 流式渲染

💡 为什么自研有意义：官方产品在中国不可用，而「操作 MATLAB 的手」（MCP）和「agent 大脑」（Claude/Codex）都已现成。本项目把它们接进 MATLAB 自己的界面，并补齐了 MBD 工程化、会话持久化、双后端切换等官方没有的能力。

🏗️ 系统架构

一句话：面板 = MATLAB 进程内原生 UI；干活 = 本地 sidecar 驱动的 headless 后端；操作 MATLAB 的手 = 复用已有 MATLAB MCP；MATLAB 自身充当 UI ↔ 上下文 ↔ sidecar 的中继。

🔄 一轮对话的数据流

• 线上全 ASCII：MATLAB tcpclient 会错解码 UTF-8，故 JSON 一律 \uXXXX 转义。
• 常驻 / 每轮可选：Claude Code 支持常驻进程模式（⚡ 开关）消除每轮冷启；默认走可靠的 resume 模式。
• 权限旁路：破坏性操作经独立控制端口转成 UI 确认卡（见下方安全模型）。

✨ 功能全景

🆕 v0.9.0 新增：确定性 MBD 工程套件 + 高阶九连 + 功能发现

一次面向团队赋能的大版本（14 项能力）。核心思路「确定性优先」：检查/对比/统计由本地代码保证准确、可复现、零 token、秒回，AI 只做解释、归因与建议。

性能:修复 asciiJson 序列化热点(293KB 事件 0.001s,千倍级提速),"AI 操作模型慢"根因消除。详见 CHANGELOG.md。

🆕 v0.7.5 新增：对话轮次导航轨（长对话一键跳转）

长对话里「找回之前某个问答」很费滚动？左侧多了一条紧凑的轮次导航轨——每轮一个刻度、等距压成一小块，悬停看富预览、点击直接跳转。灵感来自 Codex 的 navigation rail，但更紧凑、信息更全：

_{左侧紧凑刻度轨 · 悬停弹富预览卡（轮次 / 用户问 / 调用的工具 + 💬 回合数 ✓ ✕ 工具状态 ⟨⟩ 代码 ◈ diff 徽章）· 点击平滑跳转并整轮高亮 · scroll-spy 高亮当前所在轮}

• 等距紧凑刻度：每条用户消息一个刻度，自适应缩距压成一块，长对话也不松散、永不需要滚动轨道；≥ 3 轮才出现，空/短会话自动隐藏。
• 悬停富预览：一眼看清这轮「问了什么、AI 回了几条、调了哪些工具、成功还是失败、有没有改代码 / 动模型」。
• 点击跳转 + scroll-spy：点刻度平滑滚动到那一轮并整轮高亮；滚动时高亮当前所在轮的刻度。
• per-tab 隔离：导航轨始终针对当前标签页的会话重建，切换会话正确跟随。

🆕 v0.7.0 新增：边读边问 · 边答边干预

长回答看到一半想追问某一句？答到一半想补需求或叫停？这两个场景在 v0.7.0 被打通——全部真实运行截图：

📝 选区批注：在助手回答里选中有疑问的文字 → 右键，就地弹出批注框（标题锚定你选的那段）。

🟡 高亮 + 🗒 便签 + ⏸ 队列 + ⌨ Esc：被批注段落持久黄色高亮；多条追问以便签卡片贴在发送区一起发；回答中插入的新指令在右下角灰显排队；红色 停止 按钮 / Esc 即时中断本轮。

• 📝 选区批注 / 便签追问：右键选中 → 批注框 → 多段连续批注汇总成一条发送；每条便签锚定原文，AI 清楚你针对哪几处；批注状态按标签页隔离不串台。
• ⏸ 回答中插入新指令：队列模式排队、上一轮结束逐条自动发（右下角灰显回显）；引导模式立即抢占、优先执行新指令。
• ⌨ Esc 即时中断：回答中按 Esc（或点 Stop）立即停下本轮。

🎯 对标官方 Simulink Copilot（6 项能力 + 可追溯 + 任务编排，已全部对齐或超过）

额外更强：在中国可用 · R2025b 可用 · 双后端运行时切换 · 思考/工具可视化 · 多页面 + Fork · 主题三选。
故意不做编辑器内灰字补全（MATLAB 无公开补全 API），以 ↳ 生成到光标 替代。

🔧 MBD 工程化（面向汽车 / 嵌入式 / 认证）

💬 会话与平台能力

🔐 权限与安全模型

绝不使用 --dangerously-skip-permissions。 每个工具调用都过这套门控。

• 只读工具 + 只读文档自省（help/which/exist/lookfor 单条）→ 自动放行。
• 破坏性工具（model_edit/run_matlab_file/evaluate_matlab_code/model_test）→ 按编辑模式判定：
  • Ask（默认）逐条弹确认卡（带 diff 预览）；
  • Auto 改模型/写文件放行，但运行代码/跑测试仍需确认；
  • Plan 破坏性工具一律拒绝（sidecar 强制，不靠 LLM 自觉）。
• 兜底：面板未连接默认拒绝 · 确认 180s 超时默认拒绝 · 自动放行严格门控（多代码字段不放行）· 全程审计留痕。

🚀 快速开始

完整步骤、验证方法、FAQ 见 INSTALL.md；版本变更见 CHANGELOG.md（当前 v0.9.0）。

% 1. 安装工具箱(双击 .mltbx 或)
matlab.addons.install('MATLAB-Copilot.mltbx')

% 2. (终端)装并登录后端 CLI
%    npm i -g @anthropic-ai/claude-code && claude login

% 3. 装 Simulink Agentic Toolkit(附加功能),然后共享会话
satk_initialize

% 4. 环境自检
copilot_doctor()

% 5. 启动(面板停靠在 MATLAB 界面内)
copilot

打开模型后试：「解释当前模型」（出工具卡）、「把某 Gain 改成 2」（出确认卡）、点 🩺 诊断报错。

📂 目录结构

matlab/
  copilot.m                    启动入口;claude 后端自动共享会话
  copilot_doctor.m             环境自检(6 项)
  build_toolbox.m              打包成 .mltbx(零依赖,不含 node_modules)
  install_toolstrip.m          Simulink 工具条 COPILOT 选项卡
  sl_customization.m           Simulink Tools 菜单入口
  +matlabcopilot/
    Panel.m                    可停靠 uifigure + uihtml 面板,事件路由
    Bridge.m                   启动 sidecar + tcpclient 行协议(ASCII 序列化已向量化)
    Context.m                  上下文采集 + 工程级索引 + addpath 路径感知
    ModelSearch.m              模型组件高亮
    Diagnostics.m              结构化诊断采集
    Tasks.m                    自适应任务流
    Editor.m                   读光标 / 光标处插入
    ModelDiff.m                model_edit 前后语义 diff(参数/增删块/截图)
    StandardsChecker.m         建模规范确定性检查(modeling_rules.json 可配)
    TestBridge.m               Test Manager 真跑 + 覆盖率缺口
    ReqTrace.m                 需求(飞书 CSV)↔ block 双向追溯
    VersionDiff.m              当前模型 vs git 历史版本对比
    SfExplain.m                Stateflow 解析 + 死逻辑检测
    ImpactScan.m               接口/变量影响面扫描
    SimInsight.m               SDI 仿真结果指标分析
    ParamSweep.m               标定参数敏感度批扫
    KnowledgeBase.m            团队经验库(沉淀 + 指纹召回)
    DocGen.m                   SWDD 设计文档骨架生成
ui/
  index.html                   聊天界面(单文件,无 CDN):多标签 + Fork + Markdown
sidecar/                       零 npm 依赖
  src/
    index.js                   入口:makeAdapter 工厂 + 启动 Server
    server.js                  TCP server + 运行时切换 + 权限路由 + 审计
    protocol.js                行协议 + ASCII 序列化
    streamJsonParser.js        Claude stream-json → UI 事件
    permissionServer.js        权限确认 MCP(手写 JSON-RPC,零依赖)
    adapters/                  claudeCode / codex / echo / types
  test/                        56 个单元/集成测试(10 文件)
docs/images/                   架构/数据流/权限/功能 SVG 图示 + 真实运行截图(导航轨/批注/便签/队列)

🧪 测试

cd sidecar && npm test        # 57 个单元/集成测试,10 个文件

覆盖：stream-json 翻译、thinking、codex item 映射（含 turn.failed 收尾、per-child 守卫、看门狗/用户中断对排队的处理）、TCP 全链路、权限路由（只读放行 / auto 编辑放行·执行仍确认 / plan 强制只读 / 安全自省 / control 断开清理）、操作审计、多会话路由、运行时切换、Markdown 渲染、上下文 preamble、常驻后端（开关/中断重启/resetSession/FIFO 排队续发）。MATLAB 侧用 matlab -batch + checkcode/meta.class 验证类加载/语法/工程索引逻辑。

🛠️ 技术亮点

• 零 npm 依赖的 sidecar：权限 MCP 手写 JSON-RPC over stdio，不用 @modelcontextprotocol/sdk → 不打包 node_modules，彻底规避 Windows 260 MAX_PATH 导致的 approval not found。
• 跨异步边界的并发安全：两个后端适配器统一用 per-child 闭包 + this.child === child 守卫 + per-child kill 标记，消除「同步 kill + 立即新建」与「异步 close 回调」的竞态。
• 全 ASCII 线协议：绕开 MATLAB tcpclient 的 UTF-8 错解码。
• 进程内单例无常驻定时器：按窗口 UserData 查找面板，避免 clear classes 与 timer/persistent 互锁导致面板关不掉。

更多设计决策与踩坑详见 AGENTS.md（AI agent 工作手册）与 plan.md（开发计划与对标差距表）。

🗺️ 路线图

已实现：⚡ 常驻后端 · 会话持久化 · 工程级索引 · 批量编辑/测试编排/需求追溯/代码评审/自愈环。

规划中：on-prem 离线 LLM（Ollama，差异化卖点）· 文档离线 docroot 索引 · AppContainer 真侧栏 · 右键菜单用 R2026a 扩展点 API 重做 · 每标签页独立上下文/附件。

🙏 致谢

• Anthropic Claude Code / OpenAI Codex — agent 大脑
• MathWorks Simulink Agentic Toolkit — MATLAB MCP Server

顶部为 MATLAB 桌面内的真实运行截图；架构 / 数据流 / 权限 / 功能为 SVG 可视化图示。