Matlab-Simulink-SuperAgent

真正内嵌在 MATLAB / Simulink 中的本地 AI 工程助手

停靠式 uihtml 面板，自动感知 MATLAB 工程和活动模型，通过本地 sidecar 驱动 Claude Code / Codex，并复用 MATLAB MCP 操作当前 MATLAB 会话。

安装指南 · 变更日志 · 开发计划 · 贡献指南 · 最新 Release

当前实机界面

下面三张图由 v0.15.0 的 ui/index.html 在全屏浏览器预览中生成，展示与 MATLAB uihtml 面板相同的前端代码、布局和交互状态。

Matlab-Simulink-SuperAgent v0.15.0 实时计划、工程上下文与中断终态

_{全屏浏览器预览：复杂任务实时计划、可展开工程环境、可信模型事务与当前工具栏。}

Matlab-Simulink-SuperAgent v0.15.0 分阶段工程模型变更记录器

_{全屏浏览器预览：变更范围、批准/执行/验证阶段、模型级交付判断与证据包状态。}

Matlab-Simulink-SuperAgent v0.15.0 MBSE RFLPV 工程流程

_{全屏浏览器预览：完整 RFLPV 状态、分阶段设计源、人工批准门禁和真实工具箱能力。}

v0.15.0 最新更新

产品正式更名为 Matlab-Simulink-SuperAgent，同步更新 MATLAB 包命名空间、入口函数、工具条、UI、sidecar、安装包和 GitHub 仓库名称。
新主入口为 superagent()、superagent_doctor() 和 setupMatlabSimulinkSuperAgent()；原 copilot* 入口保留一版弃用兼容。
用户审计、变更证据、团队经验库与浏览器会话偏好迁移到新目录和新键；首次运行会尽量无损迁移旧数据，冲突时保留旧证据。
安装包保持原 Toolbox GUID，因此 v0.15.0 可覆盖升级既有安装，而不会注册成第二个无关工具箱。

历史版本的新增、修复和验证记录统一维护在 CHANGELOG.md。

系统架构

层	当前职责	关键实现
MATLAB / Simulink	内嵌 UI、上下文采集、每会话配置/快照/附件、本地确定性 MBD、MBSE 阶段工件和本地权限	`Panel.m`、`Context.m`、`Bridge.m`、`MBSEWorkflow.m`、`+matlabsimulinksuperagent/*`
Node sidecar	多会话注册表、adapter 生命周期、流式事件翻译、控制端口权限、审计	`server.js`、`protocol.js`、`permissionServer.js`
后端	推理、工具规划、回答生成；Claude 可选常驻，Codex 使用结构化 JSON 事件	`ClaudeCodeAdapter`、`CodexAdapter`
MATLAB MCP	读取、修改、测试当前已共享的 MATLAB / Simulink 会话	`matlab-mcp-server`

多会话生命周期

convId 是标签、Fork 和隐藏任务的隔离键。每个会话拥有独立的 adapter、配置、上下文快照、附件队列、启动 Promise 和生命周期代次；UI 关闭会话后还保留 tombstone，忽略迟到消息。

一轮消息的数据流

Matlab-Simulink-SuperAgent v0.15.0 消息数据流图

MATLAB 与 sidecar 使用 localhost TCP + 行分隔 JSON；线上字符串统一转为 ASCII \uXXXX，规避 tcpclient UTF-8 解码问题。
client 端口优先使用 8765，permission control 端口优先使用 8766；发生冲突时默认自动选择一对空闲端口，也可通过参数或环境变量覆盖。
UI 首消息传完整配置；sidecar 等 adapter ready 后才派发消息。
后端事件按 convId 回流；MATLAB 排空所有可用行后再送入当前 uihtml，UI 只更新目标标签或 Fork。
只有真正越过派发屏障的消息才消费目标会话附件；中断和关闭只撤销并清理对应会话的资源。

功能全景

AI 与模型交互

能力	当前实现
对话与工程问答	Claude Code / Codex 运行时切换，思考与工具过程可视化
实时执行计划	仅复杂任务触发；消费后端原生完整计划快照，动态显示当前步骤、状态和结构修订
上下文感知	活动编辑器、光标与选区、当前模型/子系统/选中 block、工作区、诊断、工程文件索引、Git 状态；最近快照按会话隔离
模型解释	读取真实模型参数后解释当前模型或选中 block
组件搜索	自然语言定位 block，回答标记与工具参数双通路提取路径，`hilite_system` 高亮
错误诊断	`sldiagviewer.DiagnosticReceiver` 结构化采集，诊断卡可跳转到 block
文档核实	优先核对 MathWorks 在线文档；不可用时降级到受限的本地 `help/which/exist/lookfor`
生成到光标	生成代码后写入当前编辑器光标位置，替代无公开 API 的灰字补全
批量编辑与自愈	自然语言定位目标、逐项确认修改；run → 诊断 → 修复 → 重跑，最多三轮
画布视觉分析	导出 Simulink 画布图并作为图像附件交给支持视觉的 agent

确定性 MBD 工程套件

模块	能力
`ModelDiff` / `VersionDiff`	修改前后参数、增删块和截图对比；当前模型与 Git 历史模型语义对比
`ModelFileDiff`	对记录器保存的 `.slx/.mdl` 前后快照执行隔离加载和块级语义对比，不触碰活动模型
`ChangeTransaction`	`model_edit` 检查点、编译/规范门禁、失败安全回退和机器可读运行证据
`ProjectChangeRecorder`	当前工程持续记录、任务元数据、保存前后快照、AI 事务、验证矩阵、风险判断、定向测试建议和最终证据包
`StandardsChecker`	本地规则检查；支持项目级 `modeling_rules.json`
`TestBridge`	发现并运行 `.mldatx`，汇总用例和决策/条件/MCDC 覆盖率缺口
`ReqTrace`	`requirements.csv` 与模型 block 双向锚定，结果写入可版本化 JSON
`MBSEWorkflow`	工程内 RFLPV 状态机；原生 `.slreqx`、三层 System Composer 架构、Allocation Set、物理 Profile 与验证报告
`SfExplain`	Stateflow 结构提取、不可达状态和无出口逻辑检查
`ImpactScan`	修改接口、信号、变量前扫描引用和影响面
`SimInsight`	读取最近 SDI run，计算终值、超调、稳定时间和范围
`ParamSweep`	参数取值批扫、仿真与输出指标对照
`KnowledgeBase`	将有效回答沉淀到项目 `.superagent_kb/`，按错误指纹自动召回
`DocGen`	从模型确定性提取接口、参数、层级和 Stateflow，生成 SWDD 骨架
本地辅助	MIL/SIL 对比提示、代码评审、自适应任务流、夜间批跑、并行体检

常用高级命令：/mdiff、/sf、/impact、/siminsight、/sweep、/silcheck、/swdd、/checkup、/night。输入 ? 你的需求 可在本地匹配功能，无需记忆命令。

会话与交互

多标签页、每页独立配置和后端会话；任意助手卡片可 Fork 为嵌套分支。
按项目保存历史并恢复；支持导出 Markdown、/compact 摘要播种和成本累计。
回答选区右键批注、多便签合并追问、黄色原文锚点。
回答期间支持队列或引导模式，Esc / Stop 中断并清理待处理任务。
多步骤任务显示可点击展开的实时计划；简单问答不创建计划。计划失败、中断和完成使用不同终态。
长对话轮次导航轨、悬停预览、点击跳转与 scroll-spy。
文本、代码和图片附件；输入框可直接粘贴截图。
快捷功能支持隐藏、单行横向浏览和全部多行展开三种形态；单行模式隐藏滚动条，可用鼠标滚轮、触控板或左右箭头浏览，输入框保持不变。
Light、Dark、跟随 MATLAB 三种主题；UI 单文件、无 CDN。

权限与安全

模式	只读操作	修改模型/写文件	执行 MATLAB / shell / 测试	MATLAB 本地确定性副作用
Ask	自动允许	显示确认卡	显示确认卡	显示确认卡
Auto	自动允许	自动允许并审计	仍显示确认卡	按操作类别确认并审计
Plan	自动允许	强制拒绝	强制拒绝	强制拒绝

安全不变量：

不使用 --dangerously-skip-permissions 或 Codex 的危险绕过参数。
面板未连接、确认超时 180 秒、控制连接断开和会话关闭都默认拒绝。
本地文档自省只允许单条 help/which/exist/lookfor；零字段或多个代码字段都不自动放行。
MCP 与 MATLAB 本地动作都写审计轨迹；状态从 pending 更新到真实执行结果。
/mdiff 只接受受限 Git ref，并使用参数化进程调用，避免命令拼接。

审计日志默认写入 ~/.matlab-simulink-superagent/audit-*.jsonl，面板内可查看会话操作留痕。工程变更记录保存在 ~/.matlab-simulink-superagent/change-records/<projectHash>/<sessionId>/，不写回被监视工程。

工程记录器不向模型注入 PostSaveFcn 或其他回调，因此不会修改用户模型配置。人工或脚本编辑在文件保存后进入记录；尚未保存的 AI model_edit 由 ChangeTransaction 通道即时进入时间线。单文件默认上限为 50 MB，生成目录、Git 元数据与 node_modules 自动忽略。

快速开始

前置条件

组件	要求
MATLAB	R2023b+，需要 Simulink；CI 覆盖 R2023b/R2025b，当前 Release 在 R2025b 完成实机验证
Node.js	20 或更高；sidecar 无运行时 npm 依赖
AI 后端	Claude Code 或 Codex CLI，至少安装并登录一个
MATLAB MCP	Simulink Agentic Toolkit 与 `matlab-mcp-server`；需要调用模型工具时执行 `satk_initialize`
MBSE 可选组件	Requirements Toolbox 用于 R 工件和 Implement 链接；System Composer 用于 F/L/P 架构、Allocation Set 与 Profile；V 中的 Test Manager 方法需 Simulink Test

安装与启动

从 Releases 下载 Matlab-Simulink-SuperAgent.mltbx，双击安装，或在 MATLAB 中执行：

matlab.addons.install('Matlab-Simulink-SuperAgent.mltbx')
setupMatlabSimulinkSuperAgent("repair")
satk_initialize
superagent_doctor()
superagent

源码运行：

addpath('E:/path/to/Matlab-Simulink-SuperAgent/matlab')
satk_initialize
superagent

完整安装、登录、端口、故障排查和卸载步骤见 INSTALL.md。

目录结构

matlab/
  superagent.m                       启动、共享 MATLAB 会话
  superagent_doctor.m                环境与 MCP 自检
  setupMatlabSimulinkSuperAgent.m            安装路径状态、修复与卸载
  build_toolbox.m                 生成 Matlab-Simulink-SuperAgent.mltbx
  +matlabsimulinksuperagent/
    Panel.m                       内嵌界面、事件路由、多会话、本地权限
    Bridge.m                      sidecar 进程与 ASCII TCP 协议
    Context.m                     MATLAB/Simulink/工程上下文
    ChangeTransaction.m           模型变更检查点、验证、回退与运行清单
    ModelFileDiff.m               已保存模型快照的隔离语义对比
    ModelDiff.m ... DocGen.m      确定性 MBD 工程模块
ui/
  index.html                      单文件聊天 UI，无 CDN
sidecar/
  src/server.js                   多会话、配置屏障、权限、审计
  src/permissionServer.js         零依赖 MCP JSON-RPC 权限服务
  src/projectChangeRecorder.js    工程文件基线、快照、时间线与报告
  src/adapters/                   Claude Code / Codex / Echo
  test/                           MATLAB 事务、模型差异、面板辅助与安装器测试
docs/images/                      当前产品截图与静态 SVG 图

架构细节、协议字段、后端命令、历史故障与扩展规则见 AGENTS.md。

开发与验证

Sidecar：

Set-Location sidecar
npm test

完整 Release 自动门禁：

Set-Location sidecar
npm ci
npx playwright install chromium
npm run release:verify

MATLAB 静态和类加载验证：

addpath('matlab')
checkcode('matlab/+matlabsimulinksuperagent/Panel.m', '-id')
meta.class.fromName('matlabsimulinksuperagent.Panel')

构建工具箱：

run('matlab/build_toolbox.m')

对最终安装包执行非破坏性 MATLAB 验收并生成机器可读报告：

addpath('matlab')
release_acceptance('Matlab-Simulink-SuperAgent.mltbx', ...
    ReportFile='_verify/matlab-release-acceptance.json')

详细发布步骤和受保护的 Add-On 安装验收见 Release 验收清单。

当前版本发布门槛包括：100 个 sidecar 测试、52 项 Playwright 桌面/窄屏回归、UI 两段脚本语法检查、MATLAB R2023b/R2025b CI、R2025b checkcode / 类加载与 20 项真实事务/快照/MCP/MBSE/安装辅助逻辑测试、最终 .mltbx 验收、SHA-256 生成和 GitHub Release 资产校验。

开发环境、代码边界、提交前测试和 Pull Request 要求见贡献指南。正式发布必须遵循 Release 验收清单，并以最终标签对应的 .mltbx 为验收对象。

已知边界

Simulink 新版右键菜单使用扩展点 API，当前稳定入口是面板中的“解释选中”。
MATLAB 未公开编辑器灰字补全 API，当前使用“生成到光标”。
AppContainer 真侧栏依赖未公开 API，当前使用受支持的 uifigure docking 方案并保留 normal window 兜底。
当前云端后端只有 Claude Code 与 Codex，不包含 Ollama 离线后端。
MATLAB 桌面只有一个实时活动状态；各标签保存自己的最近快照，但切回标签时会按当前 MATLAB 状态刷新。

Name		Name	Last commit message	Last commit date
Latest commit History 48 Commits
.github/workflows		.github/workflows
docs		docs
matlab		matlab
scripts		scripts
sidecar		sidecar
test		test
ui		ui
.gitattributes		.gitattributes
.gitignore		.gitignore
AGENTS.md		AGENTS.md
AUTHORS.md		AUTHORS.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
INSTALL.md		INSTALL.md
Matlab-Simulink-SuperAgent.mltbx		Matlab-Simulink-SuperAgent.mltbx
README.md		README.md
SHA256SUMS.txt		SHA256SUMS.txt
plan.md		plan.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Matlab-Simulink-SuperAgent

当前实机界面

v0.15.0 最新更新

系统架构

多会话生命周期

一轮消息的数据流

功能全景

AI 与模型交互

确定性 MBD 工程套件

会话与交互

权限与安全

快速开始

前置条件

安装与启动

目录结构

开发与验证

已知边界

License

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

Matlab-Simulink-SuperAgent

当前实机界面

v0.15.0 最新更新

系统架构

多会话生命周期

一轮消息的数据流

功能全景

AI 与模型交互

确定性 MBD 工程套件

会话与交互

权限与安全

快速开始

前置条件

安装与启动

目录结构

开发与验证

已知边界

License

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages