feat: add portable MATLAB runner skill

.github/workflows/ci.yml

@@ -35,3 +35,5 @@ jobs:
         run: python -m unittest discover -s tests -v
       - name: Test math-glossary
         run: python -m unittest discover -s skills/math-glossary/tests -v
+      - name: Test matlab-runner adapter
+        run: python -m unittest discover -s skills/matlab-runner/tests -v

.gitignore

@@ -19,3 +19,7 @@ glossary_*.xlsx
 glossary_backup_*.json
 修改记录.md
 扩充记录.md
+
+# Local MATLAB runner artifacts.
+skills/matlab-runner/examples/*.asv
+skills/matlab-runner/examples/damped_sine*.png

AGENTS.md

@@ -25,7 +25,9 @@ Run:
 ```bash
 python3 -m unittest discover -s tests -v
 python3 -m unittest discover -s skills/math-glossary/tests -v
+python3 -m unittest discover -s skills/matlab-runner/tests -v
 ```
 
 Package-level tests must use temporary directories and must not mutate source
-fixtures or a user's glossary.
+fixtures, a user's glossary, MATLAB files, or a shared MATLAB session. Static
+`matlab-runner` tests do not establish that MATLAB executed successfully.

CONTRIBUTORS.md

@@ -10,3 +10,18 @@
 
 The private intake ledger retains the submitted Chinese name and original
 filename. Public repository metadata uses the standardized English form only.
+
+## matlab-runner
+
+- Original contributor identifier: `njustar2002`
+- GitHub-associated email provided by the repository owner:
+  `njustar2002@vip.163.com`
+- VeryMath platform-neutral normalization: preserves the contributor workflow
+  while replacing client-specific paths and fixed MCP tool prefixes
+- Source-publication authorization: approved for MIT publication in this
+  repository
+
+The integration commit records the contributor with a `Co-authored-by` trailer.
+GitHub can attribute the contribution when the supplied email is verified on
+the contributor's account; this repository does not infer a public account
+handle from the email address.

PUBLISHING.md

@@ -17,6 +17,7 @@ python -m pip install \
   -r skills/math-glossary/requirements-ai.txt
 python -m unittest discover -s tests -v
 python -m unittest discover -s skills/math-glossary/tests -v
+python -m unittest discover -s skills/matlab-runner/tests -v
 git status --short
 ```
 
@@ -76,3 +77,11 @@ After the remote URL and passing CI run exist:
 提交作为 `main` 推送，CI 通过后再创建 `v0.1.0` Release。最后才同步
 AI4Math-Skill-Library 与 VeryMath 页面。任何一步都不得上传 `.intake/`、密钥、真实
 术语库或课程原始材料。
+
+## Adding later packages
+
+Later packages such as `matlab-runner` are integrated through a reviewed pull
+request rather than by rewriting the historical `v0.1.0` release. Validate the
+root suite and every affected package suite, inspect the public tree, and merge
+before deciding whether a new repository tag is warranted. Static adapter tests
+must not be described as MATLAB execution evidence.

README.md

@@ -11,6 +11,7 @@ runtime behavior.
 | Tool | Purpose | Status |
 | --- | --- | --- |
 | [`math-glossary`](skills/math-glossary/) | Build, review, back up, import, export, and maintain bilingual mathematical glossaries | Released in [`v0.1.0`](https://github.com/VeryMath/AI4Math-MathTool/releases/tag/v0.1.0) under the MIT License |
+| [`matlab-runner`](skills/matlab-runner/) | Route explicit MATLAB tasks through an available MATLAB MCP server with execution, testing, and numerical-validation evidence | Review candidate; unreleased |
 
 Each package keeps its own workflow, dependencies, provenance, normalization
 record, and tests. Course origin is recorded as metadata; it does not determine
@@ -21,6 +22,7 @@ repository boundaries.
 ```bash
 python3 -m unittest discover -s tests -v
 python3 -m unittest discover -s skills/math-glossary/tests -v
+python3 -m unittest discover -s skills/matlab-runner/tests -v
 ```
 
 ## Publication status
@@ -33,6 +35,11 @@ instruction and third-party review are recorded in
 The original submission remains in a teacher-controlled, Git-ignored archive.
 Contributor names use the course-wide English romanization convention.
 
+`matlab-runner` is a separate review candidate contributed by `njustar2002`.
+Its publication authorization and source checksum are recorded in
+[`skills/matlab-runner/PROVENANCE.yaml`](skills/matlab-runner/PROVENANCE.yaml).
+It is not included in the historical `v0.1.0` release.
+
 See [THIRD_PARTY.md](THIRD_PARTY.md) for dependency and material boundaries,
 [SECURITY.md](SECURITY.md) for safe operation, and
 [PUBLISHING.md](PUBLISHING.md) for the remote publication procedure.

README.zh-CN.md

@@ -10,6 +10,7 @@ AI4Math-MathTool 是 VeryMath 用于承载独立数学工具的仓库。进入
 | 工具 | 用途 | 状态 |
 | --- | --- | --- |
 | [`math-glossary`](skills/math-glossary/) | 构建、审阅、备份、导入、导出和维护双语数学术语库 | 已按 MIT 许可发布 [`v0.1.0`](https://github.com/VeryMath/AI4Math-MathTool/releases/tag/v0.1.0) |
+| [`matlab-runner`](skills/matlab-runner/) | 把明确的 MATLAB 任务路由到已配置的 MATLAB MCP Server，并记录执行、测试和数值验证证据 | Review Candidate，尚未发布 Release |
 
 每个 package 独立保留自己的工作流、依赖、来源、规范化记录和测试。课程来源只作为
 元数据，不作为代码仓库的职责边界。
@@ -19,6 +20,7 @@ AI4Math-MathTool 是 VeryMath 用于承载独立数学工具的仓库。进入
 ```bash
 python3 -m unittest discover -s tests -v
 python3 -m unittest discover -s skills/math-glossary/tests -v
+python3 -m unittest discover -s skills/matlab-runner/tests -v
 ```
 
 ## 发布状态
@@ -30,6 +32,11 @@ python3 -m unittest discover -s skills/math-glossary/tests -v
 原始提交仍单独保存在教师控制、Git 忽略的档案目录；贡献者姓名统一按课程名册转写为
 英文 `Given-name Surname`。
 
+`matlab-runner` 是由 `njustar2002` 贡献的独立 Review Candidate，发布授权与
+原始文件校验值记录在
+[`skills/matlab-runner/PROVENANCE.yaml`](skills/matlab-runner/PROVENANCE.yaml)。
+它不属于历史 `v0.1.0` Release。
+
 依赖与材料边界见 [THIRD_PARTY.md](THIRD_PARTY.md)，安全说明见
 [SECURITY.md](SECURITY.md)，创建远端、运行 CI 与发布版本的步骤见
 [PUBLISHING.md](PUBLISHING.md)。

SECURITY.md

@@ -15,3 +15,13 @@ AI enrichment sends selected terms to the endpoint configured by the user.
 Review the endpoint's privacy and data-retention terms before using real
 research data. Never store API keys in a glossary, command history, log, or
 repository file.
+
+The MATLAB runner may ask a connected MATLAB MCP server to execute code or
+write files. Review generated or third-party `.m` files before execution, use
+the narrowest requested capability, and keep destructive file operations under
+explicit user control. The package does not store MATLAB licenses, VPN
+credentials, MCP secrets, or local executable paths. Keep those values in the
+user's local client or environment configuration and never commit them.
+Do not expose one MATLAB MCP Server as a shared multi-user service; the
+upstream licensing guidance requires contacting MathWorks for shared or
+centralized deployments.

SKILL.md

@@ -10,6 +10,7 @@ Route each request to the narrowest matching package:
 | Request | Package |
 | --- | --- |
 | Build, update, query, back up, import, export, or review a bilingual mathematical glossary | `skills/math-glossary/SKILL.md` |
+| Explicitly use MATLAB, operate on `.m` files, or obtain MATLAB-specific execution, test, toolbox, license, or numerical-validation evidence | `skills/matlab-runner/SKILL.md` |
 
 Before running a package:
 

THIRD_PARTY.md

@@ -25,3 +25,26 @@ User-supplied dictionaries, corpora, papers, scans, PDFs, spreadsheets, and
 other source materials are not part of this repository. Users are responsible
 for confirming that they may process and redistribute any derived glossary
 content.
+
+## MATLAB Runner boundaries
+
+`skills/matlab-runner` contains routing instructions, references, tests, and
+small original MATLAB examples. It does not vendor MATLAB, MathWorks products,
+the MATLAB MCP Server, the MATLAB Agentic Toolkit, OpenCode, or another coding
+agent. It is a community adapter and is not an official MathWorks or OpenCode
+package.
+
+The following software, when selected by a user, is installed separately and
+remains governed by its upstream terms:
+
+| Dependency | Purpose | Upstream terms |
+| --- | --- | --- |
+| [MATLAB](https://www.mathworks.com/products/matlab.html) and optional toolboxes | Numerical runtime and product-specific functions | MathWorks product license selected by the user or institution |
+| [MATLAB MCP Server](https://github.com/matlab/matlab-mcp-server#licensing-and-usage) | Expose MATLAB execution capabilities to an MCP client | Upstream `LICENSE.md`; use only with MATLAB, do not share one server among multiple users, and contact MathWorks for shared or centralized use |
+| [MATLAB Agentic Toolkit](https://github.com/matlab/matlab-agentic-toolkit) | Optional upstream agentic components | Upstream `LICENSE.md`, including the MathWorks-products use condition |
+| [OpenCode](https://github.com/anomalyco/opencode) | One optional coding-agent client; not required by this package | MIT |
+
+The repository MIT license applies to the normalized `matlab-runner` package,
+not to separately installed MATLAB or MathWorks components. Users must provide
+their own valid MATLAB installation and license and follow each dependency's
+terms.

skills/matlab-runner/CHANGELOG.md

@@ -0,0 +1,200 @@
+# 版本记录
+
+## [0.1.8-verymath-review] - 2026-08-10
+
+### Coding agent 通用化
+
+- 保留原有触发、安全、错误分类、测试与数值验证流程；
+- 去除 OpenCode 固定路径、Windows 配置和固定 MCP 工具前缀；
+- 改为由 coding agent 检查当前工具目录，按能力和参数模式选择实际工具名；
+- 增加 VeryMath 来源、授权、规范化记录和通用客户端设置说明。
+
+## [0.1.8-review] - 2026-08-01
+
+### 恢复与超时
+
+- 新增 `MCP_TOOL_TIMEOUT`，用于区分 MCP 调用超时与 MATLAB 代码运行错误；
+- 超时后恢复成功时必须使用 `success (after recovery)` 并保留超时记录；
+- 不从超时本身推断 MATLAB 是否实际执行了代码。
+
+### 调用上限
+
+- 明确区分硬性调用上限与软性一次调用目标；
+- 用户明确规定“最多 N 次”时不得擅自超出，失败后应报告并请求重试许可；
+- 软性目标被恢复调用超过时，必须写明约束未满足和真实总次数。
+
+### 验证修正
+
+- 修正残差、参考解、维度或验收公式后，早期问题记录为恢复后的 `VALIDATION_FAILURE`；
+- 后续调用必须重新计算受影响的量；
+- 禁止把先前 MATLAB 输出硬编码进修正调用冒充复核；
+- ODE 残差必须使用参考解的真实导数项。
+
+### 轻量探测
+
+- 简单环境探测优先使用顶层语句与直接 `if`/`else`；
+- 不为轻量检查引入不必要的本地或嵌套辅助函数。
+
+### 交付状态
+
+- 汇总老师五项反馈和 v0.1.5–v0.1.7 回归结论；
+- 形成当前完整的 v0.1.8 Review Candidate 审阅包。
+
+
+## [0.1.7-review] - 2026-08-01
+
+### 验证基准
+
+- 解析解、期望值、参考向量或验收目标在作为真值前必须先通过最小必要验证；
+- ODE 参考解至少检查初值／边界条件和定义方程残差；
+- 无效基准不得用于解释求解器误差，未能纠正时分类为 `VALIDATION_FAILURE`。
+
+### 数组形状
+
+- 逐点数值比较前核对采样点、元素数量、方向与尺寸；
+- 禁止因行向量与列向量相减触发隐式扩展后继续解释错误结果；
+- 预期标量却得到向量时，视为形状诊断信号。
+
+### 调用审计
+
+- 最终摘要新增 MATLAB MCP 调用总数、成功数和失败数；
+- 所有失败、纠正和未采用的调用均计入；
+- 禁止把多次调用描述成“一次干净执行”。
+
+### 工具箱证据
+
+- 产品检测、函数解析和许可证测试必须作为独立证据；
+- MATLAB 调用成功本身不算产品检测；
+- 许可证测试成功不证明产品或函数已安装并可解析。
+
+### 待验证
+
+- 增加两道 v0.1.7 定向回归：三层工具箱证据，以及带错误候选解析解的 ODE 基准验证与形状安全。
+
+## [0.1.6-review] - 2026-08-01
+
+### 完成状态
+
+- 完成状态改为描述“用户请求是否完成”，不再把“目标工具箱不可用”等同于任务部分失败；
+- 可用性检查成功但依赖不可用时，使用 `Completion status: success`，并单独报告 `TOOLBOX_UNAVAILABLE`。
+
+### 错误恢复
+
+- 任一失败的 MATLAB MCP 调用都必须保留在最终执行记录中；
+- 重试后完成任务时，使用 `success (after recovery)`；
+- 统一报告恢复错误的类型、阶段、直接证据和修正动作。
+
+### 工具克制与数值说明
+
+- 禁止在核心计算末尾追加非必要的默认参数探测、试验性 API 或版本诊断；
+- 明确 `odeset()` 的空字段表示未显式设置，不是显示异常；
+- 默认求解器任务不需要打印确切默认值时，只报告使用了默认设置与实测结果。
+
+### 工具箱检查
+
+- 目标工具箱任务优先使用一次针对性 MATLAB 调用核对产品、函数和许可证；
+- 结论优先表述为“当前 MATLAB 环境可用／不可用”，不在证据不足时断言安装根因。
+
+### 待验证
+
+- 增加三道 v0.1.6 定向回归：工具箱状态语义、失败后恢复、ODE 干净默认执行。
+
+## [0.1.5-review] - 2026-08-01
+
+### 触发
+
+- 收紧 Skill 触发条件；
+- 普通数学、通用编程和不执行的 code-only 请求不再触发；
+- 明确 MATLAB 只是可选工具时不得误触发。
+
+### 环境检查
+
+- 改为渐进式、按需检查；
+- 已有 MCP 工具可用时直接执行；
+- 特定工具箱任务只检查目标依赖；
+- 禁止未经请求自动安装、重装或更新环境。
+
+### 可移植性
+
+- 三份 reference 改用 `./references/...`；
+- 明确相对于加载的 `SKILL.md` 目录解析；
+- 不再依赖固定 `.opencode/skills/...` 路径。
+
+### 错误与输出
+
+- 新增 Skill、MCP、MATLAB 会话、工具箱、代码执行、测试、验证和未解析环境八类错误；
+- 新增统一完成摘要，报告真实执行、工具、产物、测试、验证和结果位置。
+
+### 交付整理
+
+- 增加 v0.1.5 七个定向回归场景；
+- 根据作者偏好移除非必要的 `交付说明.md` 与 `MANIFEST.sha256`。
+
+### 待验证
+
+- v0.1.5 行为调整仍需作者本机 OpenCode/MATLAB 回归。
+
+## [0.1.4-review] - 2026-08-01
+
+### 定位
+
+- 从“稳定版”调整为 **Review Candidate / 可审阅原型**；
+- 明确项目是基于官方 MATLAB MCP 基础设施的 OpenCode 自定义 Skill，而非修改 Toolkit 源码。
+
+### 结构
+
+- 将单一大型 `SKILL.md` 拆为核心 Skill 和三份按需 reference；
+- 增加 reference 的懒加载规则；
+- 增加 `evaluate_matlab_code` 的绝对 `project_path` 要求。
+
+### 安全与配置
+
+- 示例权限改为人工确认优先；
+- shell 从 `allow` 改为 `ask`；
+- 执行类 MATLAB 工具改为 `ask`；
+- MCP 可执行文件改用 `<MCP_SERVER_EXE>` 占位符；
+- 安装文档增加实际文件名枚举；
+- 澄清 MCP `timeout` 是工具发现超时。
+
+### 示例
+
+- `matrix_report.m` 改为函数；
+- `plot_damped_sine.m` 改为函数，避免覆盖、基础工作区污染和遗留图窗；
+- 单元测试扩展为两个测试。
+
+### 证据与交付
+
+- 增加 `docs/evidence/`；
+- 区分直接摘录、会话摘要和待执行回归；
+- 增加 `.gitignore`、`NOTICE.md`、官方参考资料和审阅说明；
+- 文本统一为 UTF-8 无 BOM、LF；
+- ZIP 使用标准 `/` 路径和 UTF-8 文件名；
+- 增加 SHA-256 清单。
+
+### 待验证
+
+- v0.1.4 拆分结构需要在作者环境运行 ODE 与内存两道定向回归。
+
+## [0.1.3] - 2026-08-01
+
+- 强制使用 MATLAB 官方 `memory` 接口；
+- 禁止使用 Java preferences 或 `ArraySizeLimit` 代替内存字段；
+- 最终内存烟雾测试通过。
+
+## [0.1.2] - 2026-08-01
+
+- 要求在首次 MATLAB 工作流工具前加载 Skill；
+- 加强工具克制、单位一致性和未测量声明；
+- 加强实际代码忠实报告。
+
+## [0.1.1] - 2026-08-01
+
+- 改进触发描述；
+- 禁止 placeholder 和不完整执行代码；
+- 区分 ODE 局部容差与全局误差；
+- 区分数据存储与峰值工作内存。
+
+## [0.1.0] - 2026-08-01
+
+- 初始 MATLAB MCP 工具路由 Skill；
+- 共享工作区、文件保护、静态检查、测试和资源安全规则。

skills/matlab-runner/NORMALIZATION.md

@@ -0,0 +1,26 @@
+# MATLAB Runner normalization record
+
+This public review candidate preserves the contributor's trigger boundary,
+lightweight preflight, MATLAB implementation and execution flow, unit-testing
+rules, numerical validation rules, error taxonomy, and completion summary.
+
+The following repository-edition changes were made on 2026-08-10:
+
+- moved the canonical package from a client-specific `.opencode` layout to
+  `skills/matlab-runner/`;
+- replaced fixed OpenCode paths and Windows configuration with a relative,
+  coding-agent-neutral setup reference;
+- replaced fixed MCP tool prefixes with runtime discovery by capability and
+  argument schema;
+- added bilingual package documentation, provenance, tests, and repository
+  metadata;
+- excluded `.DS_Store`, local client configuration, the original archive, and
+  historical review/evidence files from the public package;
+- excluded `FINAL_SUBMISSION_AUDIT.md` because it described a `NOTICE.md` file
+  that was not present in the submitted archive;
+- retained the historical changelog as contributor-supplied context without
+  treating its review statements as current CI or MATLAB execution evidence.
+
+The normalization tests check repository shape and adapter portability. MATLAB
+was not executed by those Python tests, so this record makes no MATLAB runtime,
+license, toolbox, or numerical-success claim.