# 马特洛克 (Matlock) — 智能体与开发者工具。（用户手册与运行参考指南）


> **致 AI 编码智能体与编排系统：**
> 请直接跳转至 **[第二部分：机器与自主智能体运行规范](#第二部分机器与自主智能体运行规范)**，查阅 27 工具 `stdio` MCP 目录、双路径 `HTTP 402` 解锁、`cold_box` 边界沙箱规则与完成握手协议。

**产品**: 马特洛克 (Matlock) — 智能体与开发者工具。（`高效。精准。严循规范。`）  
**定位**: *配备防篡改 Safeguard 测试封印、边界 Pre-CI 沙箱、一键 CLI 自动化、私有仅出站告警与 27 工具本地 stdio MCP 的 `< 50ms` 零上传多语言安全、MITRE CWE、IEEE Std 1003.1 POSIX、CISA SSDF 与 AICPA SOC 2 Trust Services Criteria 验证（`0` 云端源码上传、`0` 开放端口、`0` `git commit` 拦截）。*  
**发行方**: 马特洛克 (Matlock) by Dutch P2P © 2026. 保留所有权利。  
**使用界面**: 桌面指挥中心（支持 **Windows**、**Linux** 与 **GoogleBook**；**macOS 与 iOS** 在 macOS `arm64` 上支持无头 MCP — 随时按 **`?`** 或 **`F1`** 打开） · [网页端指挥中心](https://matlock.dutchp2p.com/zh/app) · [浏览器免费扫描](https://matlock.dutchp2p.com/zh/#wasm-instant-audit) · [文档](https://matlock.dutchp2p.com/zh/docs) · [在线手册](https://matlock.dutchp2p.com/zh/manual) · MCP URI `matlock://help/appliance-manual`

**范围与法律声明**: *马特洛克对照公开发布的行业规范与基准（MITRE CWE、CISA SSDF、IEEE Std 1003.1 POSIX、自动化 Pre-CI 完整性门禁，以及 AICPA SOC 2 Trust Services Criteria 技术控制项）评估技术代码库与流水线控制。马特洛克不保证软件毫无缺陷，不出具正式的第三方鉴证报告，亦不提供由独立执业注册会计师事务所（CPA）签发的认证。*

---

## 目录

### 第一部分：人类操作员与工作台指南
1. [快速词汇表与核心工作流](#1-快速词汇表与核心工作流)
2. [界面布局、主题与导航](#2-界面布局主题与导航)
3. [自动发现脚本、自定义检查、操作与星标收藏](#3-自动发现脚本自定义检查操作与星标收藏)
4. [无人值守例程、计算机命令与本地告警](#4-无人值守例程计算机命令与本地告警)
5. [结果瀑布流、单分类重跑、忽略与复制给智能体](#5-结果瀑布流单分类重跑忽略与复制给智能体)
6. [粘性防篡改 Safeguard、测试完整性与恢复](#6-粘性防篡改-safeguard测试完整性与恢复)
7. [水平健康分、覆盖率进度条与模块化标准](#7-水平健康分覆盖率进度条与模块化标准)
8. [双栏设置与封签状态恢复](#8-双栏设置与封签状态恢复)
9. [连接 AI 智能体（桌面端 MCP 与手机/对话指南）](#9-连接-ai-智能体桌面端-mcp-与手机对话指南)
10. [内置标准参考（10 大生态 + Pre-CI）](#10-内置标准参考10-大生态--pre-ci)
11. [工作站 Pro 许可、网页预览与免费浏览器扫描](#11-工作站-pro-许可网页预览与免费浏览器扫描)
12. [Linux、GoogleBook、更新、隐私与支持](#12-linuxgooglebook更新隐私与支持)

### 第二部分：机器与自主智能体运行规范
* [A. 智能体入口与传输配置](#a-智能体入口与传输配置)
* [B. 计量计费、M2M 集群接入与 Pro 解锁](#b-计量计费m2m-集群接入与-pro-解锁)
* [C. 完整 27 工具本地 MCP 目录](#c-完整-27-工具本地-mcp-目录)
* [D. 边界 Cold Box 沙箱、3 次循环熔断与 3 问交接协议](#d-边界-cold-box-沙箱3-次循环熔断与-3-问交接协议)
* [E. 面向 AI 编码智能体的机器可读规范 (YAML)](#e-面向-ai-编码智能体的机器可读规范-yaml)
* [F. 智能体运行原则与执行边界](#f-智能体运行原则与执行边界)

---

## 第一部分：人类操作员与工作台指南

## 1. 快速词汇表与核心工作流

* **核心工作流运行方式**：选择项目文件夹 -> 马特洛克在 UI 线程之外执行即时静态扫描（`max(1, cores - 1)` 个工作隔离体，保留 `1` 个 CPU 核心流畅响应）并自动发现工作区脚本 -> 为常用命令加星固定至**收藏** -> 点击 **`Matlock`** 运行统一权威验证流水线（跨 `depth 0..2` 执行 `清理 -> 拉取依赖 -> 格式化 -> Linter -> 分析/编译 -> 测试 -> 覆盖率`，外加跨系统 Pre-CI 及全部内置与自定义检查；日常热运行在基线与依赖清单未变化时自动跳过`清理`，`...` 溢出菜单随时提供**`运行完整清理与覆盖率检查`**且面板零多余开关）。`Matlock` 仅执行全面验证而不提交或推送（`Matlock` 与预置测试例程内置 `0` 次 `git push`——测试与推送保持分离，用户与 MCP 智能体可自由添加自定义 `git push` 或云部署操作卡及串联序列），且绝不安装 `.git/hooks/*` 或拦截本地提交。
* **测试 vs. 错误（发现项）**：**测试**是不可变的内置检查或用户定义的**自定义检查**，共同决定您的数字 **0.0–100.0 健康分**。**错误**则是带有 `file:line:col`（`col >= 1`）、`[MITRE CWE-*]` / `[POSIX-*]` / `[MITRE Txxxx]` 标签、通俗原因及已脱敏 5 行统一 diff 修复处方的具体问题。
* **操作与例程（序列）**：**操作**是单步一键本地命令卡（`flutter test`、`npm run build`、`.bat` 备份）；**例程**可在**运行队列**上串联 **20+ 张卡片**，支持**失败即停并告警**（默认）、**失败即停**或**继续并告警**。
* **Safeguard（`已受安全保护` / `AI 智能体可修改`）**：粘性封签，保护测试、脚本、操作、例程与告警（`只读可运行`）。任何来自 AI 或外部的未经授权改动均会自动回滚至已封签原版，并触发顶部栏**信封**脉冲篡改告警。

## 2. 界面布局、主题与导航

* **舒缓日间与夜间界面**：随时通过顶部栏**主题**切换按钮或**设置 -> 外观**在**柔和银白日间**（`#F8F9FA` / `#FFFFFF`）与**舒缓炭灰板岩夜间**（`#131517` / `#181B20` / `#1E2228`）之间切换。运行期间绝不弹窗打断；仅首次信任文件夹以及第 1 步开始前的一次性**运行前先询问我**请求确认。
* **顶部栏**：**`浏览...`** + 路径框、5 级管理 **`已忽略 (N)`**、**`停止`**（`Ctrl+.` / `Esc`）、**`升级`**（免费版）、**`成果`**、**`分享`**、脉冲**`信封消息收件箱`**（`[x] 发送邮件通知`、`发送消息`、`全部标为已处理`、篡改/智能体卡片）、**主题切换**、**`?`**（`F1` 手册）与 **`设置`**。
* **左侧栏**：唯一权威 **`Matlock`** 运行卡、**`“与无头模式同步”`** 双向桥接、**`遇错停止并通知`**、**`通知`**、**`文件大小栏`**（模块化调节盘）、**`+ 添加卡片`**、星标 **`收藏`**、自动发现的 **`可用命令`** / **`项目步骤`**、**`计算机`** 命令与 **`备注`**。
* **中央舞台与常驻停靠 CLI 终端**：托管检查列表栈（`启动进程`、`停止进程`、`重跑失败项`、可按 `Ctrl+P` 打印的 **`运行`** / **`CI 代码健康报告`**、逐**阶段行**与 **运行线** FIFO 队列）下方紧邻**常驻停靠终端**（**Output**、**Problems**、**`Tests (N)`**、**`Coverage (N)`**，带选区锁定缓冲以防划词复制时页面跳动、自动跟随 + **跳转至最新**、**查找**、Pro 版 `Ctrl+K` **快速运行**，以及内联 **CLI 终端栏**，让您无需打开 PowerShell 或 `cmd.exe` 即可直接在马特洛克中输入并 **`运行`** `git status`、`git push` 或 `wrangler deploy` 等任意命令，再一键 **`保存为卡片`** 或 **`串联 / 告警`**）。
* **右侧遥测栏**：数字**马特洛克评分**（`XX.X / 100.0`）配合**水平健康分与真实逻辑覆盖率进度条**、**`已通过测试`** / **`错误`** 计数、**`前 3 项修复`**、**`最大未测试文件`**、**`成果`** 图表，以及 **`测试完整性`** 已移除测试记录。

## 3. 自动发现脚本、自定义检查、操作与星标收藏

* **自动发现的自定义脚本与 6 个未配置初始模板**：打开文件夹时，马特洛克自动从 `package.json`、`Makefile`、`Cargo.toml`、`pyproject.toml`、`pubspec.yaml` 及工作区 `.bat`/`.ps1`/`.sh` 脚本中发掘命令并列于**可用命令**下（绝不自动收藏——点击**星标**即可固定至收藏），同时提供 **6 个预置未配置初始模板**（**GitHub**、**保存至 U 盘 / 移动硬盘**、**AWS / Google Cloud**，以及计算机卡片**保存**、**磁盘整理优化**、**关机**）。点击未配置模板将打开编辑器供您填入批处理/Shell 脚本——或由已连接的 MCP 智能体代为编程并加入收藏——配置完成后即可一键运行。
* **应用内 CLI 联动与编辑 -> 源脚本 + 粘性 Safeguard**：在常驻终端 CLI 栏输入任意命令并点击 **`保存为卡片`**（一键操作卡）或 **`串联 / 告警`**（带遇错停机或邮件告警的串联步骤），或点击任意已发现/自定义卡片上的**编辑**查看或修改命令/脚本、工作目录、超时、**`运行前先询问我`**、**`失败计入我的健康分`** 及粘性 **`Safeguard`**（`[LOCKED]` 对智能体仅限执行 vs `[MODIFIABLE]` 允许智能体优化并通过顶部**信封**展示命令前后 diff 供人工**接受** / **还原**）。
* **添加自定义检查（`+ 添加卡片 -> 自定义检查`）**：创建**在文件中查找文本**正则/字面量规则或**运行脚本**规则（`exit 0` = 通过；`file:line:col: message` 自动解析为发现项），支持严重级别（`严重`、`主要`、`警告`、`信息`），保存在仓库之外的私有本地用户配置存储中。
* **Windows `.bat` 与 `robocopy` 处理**：关闭 `stdin`（`<nul`）与系统作业隔离防止挂起；单行 `%i` 自动规范化为 `%%i`；`robocopy` 退出码 `0–7` 计为**通过**（`>= 8` = 失败）。

## 4. 无人值守例程、计算机命令与本地告警

* **无人值守例程与自定义推送/部署链（`+ 添加卡片 -> 序列` 或终端 `串联 / 告警`）**：按序串联 **20+ 张卡片**，默认将 **`Matlock`** 置于首位，支持单步勾选**即使前面步骤失败也始终运行此步骤**，以及第 1 步前的一次性**运行前先询问我**确认。初始模板包括**夜间检查**、**部署至 Cloudflare** 与**备份并关机**（外加利用您本地 CLI、存储 `0` 条云凭据的云/容器**目标**模板；`Matlock` 测试运行内置 `0` 次 `git push`，用户与 MCP 智能体可自由添加自定义 `git push` 或云部署操作卡与串联序列）。
* **通知 / 邮件告警操作卡（`通知` 或 `设置 -> 邮件告警` — 分步指南）**：**(1)** 在您邮箱账户的 2FA 安全设置中生成**应用专用密码 / 16 位授权码**（开启 2FA 时切勿使用常规网页登录密码），打开 **`通知`** 或 **`设置 -> 邮件告警`**，填入发件人/收件人邮箱与应用专用密码/授权码（严格仅出站原生 TLS 1.2/1.3 SMTP 并校验 X.509 证书，`0` 入站 IMAP/POP3 收件箱访问，`0` Dutch P2P 中继；内置 Gmail / Workspace、Microsoft 365 / Outlook、Yahoo、iCloud、QQ / 163 16 位授权码、Zoho 全球/欧洲/印度版、Fastmail、Yandex、Mail.ru、阿里云、开启外部 POP3/SMTP 的 GMX / Web.de 与本地 Proton Mail Bridge `127.0.0.1:1025` 预设；凭据封签于系统钥匙串或通行短语封签的本地容器保险库），或无头环境下通过 `matlock-mcp send-alert --subject "..." --body "..."` 测试并点击 **`测试邮件`**——也可改选本地自定义脚本。**(2)** 随时**一键**独立运行通知卡。**(3)** 将其挂接至任意序列链，设为 **`失败即停并告警`**（遇错触发：构建/测试失败时立即刹车并发信通知）或 **`继续并告警`**（`always`：全链跑完后无条件发送完成邮件）。
* **`计算机`（8 条用户可编辑计算机命令 — 绝不自动运行）**：

| 卡片 | Windows | Linux | 说明 |
| :--- | :--- | :--- | :--- |
| 30 分钟后关机 | `shutdown.exe /s /t 1800` | `shutdown -h +30` | 30 分钟延迟，绝不使用 `/f`；配对取消关机 |
| 取消关机 | `shutdown.exe /a` | `shutdown -c` | 一键立即中止 |
| 清理临时文件 | 仅用户临时文件夹，跳过活动文件 | `~/.cache` 与 `/tmp` 中超过 1 天的用户文件 | 绝不触碰项目文件 |
| 检查磁盘空间 | `Get-PSDrive -PSProvider FileSystem` | `df -h` | 只读 |
| 优化磁盘（整理或 trim） | `Optimize-Volume -DriveLetter C -Verbose` | `fstrim -av` | 需管理员/root 权限；无 UAC/`sudo` 弹窗静默停止 |
| 备份副本 | `robocopy . "<backup-folder>" /MIR` | `rsync -a --delete ./ "<backup-folder>/"` | 保留 `.git`，跳过构建缓存；`robocopy` `0–7` = 通过 |
| 查找词语并列出 | `findstr /s /i /m /c:"Aluminium" *.dart` | `grep -rnI "Aluminium" --include="*.dart" .` | 可编辑的不区分大小写递归搜索 |
| 捕获超过 250 行文件 | `for /r %i in (*.dart) do ... find /c /v ""` | `find . -name "*.dart" -exec awk '... c>250 ...' {} +` | 只读扫描，列出超过 250 行的文件 |

## 5. 结果瀑布流、单分类重跑、忽略与复制给智能体

* **最多错误优先分类瀑布流**：扫描分类按当前活跃错误数量自动降序排列，关键问题簇始终置顶，无需滑过干净检查。
* **划词复制与单分类隔离重跑**：拖动高亮任意发现项文本即可直接复制，点击**分享给智能体 / 复制**（`Ctrl+Shift+C`）获取 `folder/file:line` + `[MITRE CWE-*]` / `[POSIX-*]` + 5 行统一 diff 修复处方，或点击分类**重跑**按钮在几毫秒内单独复验该分类（在运行完整 `Matlock` 前显示 `?` 估算徽章）。
* **仓库外 5 级忽略（`已忽略 (N)`）**：在五个粒度静默搁置发现项：`file:line:code`、`file:code`、`*:code`、`file` 或 `folder/`（`0` 扣分，支持一键**恢复** / **全部恢复**及可选误报**发送并忽略**）。行内代码注释（`// ignore:`、`/* nolint */`、`# noqa`、`@ts-ignore`）绝不能屏蔽马特洛克，且智能体拥有零 MCP 忽略写入工具。

## 6. 粘性防篡改 Safeguard、测试完整性与恢复

* **为何 Safeguard 至关重要**：内置检查已编译进原生二进制文件，而 **Safeguard** 将用户测试、已发现/自定义脚本、操作、例程与告警封签保护（`[LOCKED]` / `只读可运行`——仅可通过 `matlock_run_action` / `matlock_run_sequence` 执行；`[MODIFIABLE]` 卡片允许智能体优化脚本并向**信封**发送命令 diff 供人工审核）。
* **确定性自动回滚与脉冲信封告警**：如果 AI 智能体或外部工具未经授权修改了 Safeguard 受保护测试或已封签脚本，马特洛克会确定性地恢复已封签原版文件（在仓库外保存撤销备份），使顶部栏**信封**以 `[Matlock Alert] Critical test altered: <test_name>` 脉冲闪亮告警，并阻断无头运行（`exit 65`）。
* **测试完整性与人工批准恢复**：被删除、跳过或弱化的测试会触发持久的**已移除测试审查记录**，在人工标记**好，是我改的**、**可疑**或使用**设置 -> Safeguard 与恢复 -> 允许马特洛克恢复测试**（含 diff 预览 + 撤销副本）前始终拦截**准予推送**。**在我的电脑之间同步**（Pro）写入以通行短语封签的 `<computer-id>.matlock-sync` 完整性文件（`0` 源代码、`0` 网络连接）。

## 7. 水平健康分、覆盖率进度条与模块化标准

* **数字评分与水平进度条**：显示 **`XX.X / 100.0`**（首次运行前为 `--`），并配有**健康分**与**真实逻辑覆盖率**水平进度条，精准统计未受测试的生产逻辑而排除生成样板代码。构建、依赖或测试失败会将总分限制在不可发布区间；**`格式化`** 仅报告不扣分（`0` 扣分）。
* **仅限人工的模块化调节盘（`CWE-1080` / `CWE-1120`）**：通过左侧栏 **`文件大小栏`** 或 **`设置 -> 项目与运行器`** 调整（`*基于 Grade C 标准，可在设置中调整`，封签于系统设置，`0` 仓库文件，`0` MCP 写入权限）：**`Grade A (<= 60 / <= 25 fn)`**、**`Grade B (<= 100 / <= 40 fn)`**、**`Grade C (<= 250 / <= 80 fn)` [默认]**、**`Grade D (<= 500 / <= 120 fn)`** 或 **`Minimum (<= 1000 / <= 250 fn)`**。
* **`准予推送` 结论**：要求达到可发布健康分且 `0` 个严重发现、构建与测试阶段全部通过、`0` 条未决已移除测试记录，以及非暂定覆盖率。

## 8. 双栏设置与封签状态恢复

点击右上角 **`设置`** 打开双栏对话框（左侧分类栏 + 简洁右侧控件；每个面板标题均带 **`?`** 图标可直达对应手册章节）：
1. **`外观`**：**语言**（9 种语言 + 复制文本语言）、**主题**（`跟随系统`、`浅色`、`深色板岩`）、桌面快捷方式，以及 Windows **关闭时最小化到系统托盘**。
2. **`项目与运行器`**：**模块化调节盘**（`Grade A..Minimum`）、本地配置 **`打开文件夹`**（私有本地用户配置文件夹）、**`恢复初始设置横幅`**（重新打开`一键为我配置`）、**`保留快速运行历史`** 与 **`重置忽略注册表`**。
3. **`Safeguard 与恢复`**：**`允许马特洛克恢复测试`**、仅限人工的 Safeguard 自动回滚开关，以及 **`在我的电脑之间同步`**（通行短语封签文件夹同步）。
4. **`邮件告警`**：本地仅出站邮件与自定义脚本告警站 + **`测试邮件`**。
5. **`AI 代理 (MCP)`**：**`MCP 服务器 (stdio)`** 开关（默认关闭）、**`“与无头模式同步”`** 双向桥接（一键刷新加载智能体创建的卡片/序列并双向发布现行指令，`0` 后台轮询）、**`测试 MCP 连接`**、**`复制 MCP 配置与智能体指令`**、**`为我的手机 AI 复制一个问题`** 与 **`智能体邮件桥接`**。
6. **`许可证与更新`**：24 位密钥 **`激活`** / **`将许可证迁移到此设备`**、**`自动检查更新`**（`MATLOCK_OFFLINE=1` 拦截一切对外请求）、**`发送匿名崩溃诊断`**（默认关闭；`MATLOCK_NO_TELEMETRY=1`）、**`复制诊断信息`**、**`释放内存`**、**`分享马特洛克`**、**`联系我们`**（`dutch@dutchp2p.com`）与 **`Dutch P2P 工具`**。
* **封签状态恢复（`重置忽略注册表`）**：若外部篡改触发 `integrity_seal:MUTE_SEAL_TAMPERED` 或 `storage_recovery:BAK_AUTO_RESTORE`，请打开 **`设置 -> 项目与运行器 -> 存储与备份 -> 重置忽略注册表`**。

## 9. 连接 AI 智能体（桌面端 MCP 与手机/对话指南）

* **如何通过本地 `stdio` 与 `“与无头模式同步”` 连接（`0` 开放端口）**：打开 **`设置 -> AI 代理 (MCP)`**，开启 **`MCP 服务器 (stdio)`**，点击 **`复制 MCP 配置与智能体指令`**（或 `?` 内的 **`复制 MCP 智能体指南`**），并随时点击 **`“与无头模式同步”`**（在设置或左侧栏）双向加载智能体创建的卡片与发布常驻指令：

```json
{
  "mcpServers": {
    "matlock": {
      "command": "matlock.exe",
      "args": ["mcp", "--stdio"]
    }
  }
}
```

* **通用客户端、启动器与对话支持**：可通过 `npx -y @dutchp2p/matlock-mcp` 或 `uvx matlock-mcp` 零配置启动；全面兼容 VS Code、Cursor、Claude Code/Desktop、Antigravity、Gemini CLI、Copilot、Codex、Windsurf、JetBrains/Junie、Trae、Lingma、MarsCode、CodeGeeX、Baidu Comate、Tencent CodeBuddy、Zed、Cline、Roo Code、Continue、Aider、Goose、OpenHands、Devin、Replit Agent、Sourcegraph Amp、Kimi、Qwen、DeepSeek、Doubao、MiniMax 及本地 Ollama/vLLM/SGLang/LM Studio 智能体。已连接的智能体可离线调用 `matlock_read_appliance_manual(section_id, locale)`（`0` 积分，9 种语言），也可直接将 [https://matlock.dutchp2p.com/zh/manual.md](https://matlock.dutchp2p.com/zh/manual.md) / [https://matlock.dutchp2p.com/llms.txt](https://matlock.dutchp2p.com/llms.txt) 粘贴到任意手机或浏览器 AI 对话中。对于新发布的 IDE、智能体运行框架与容器平台，请访问 [https://matlock.dutchp2p.com/zh/docs.html](https://matlock.dutchp2p.com/zh/docs.html) 查看实时兼容性指引。

## 10. 内置标准参考（10 大生态 + Pre-CI）

每项内置检查均已编译进马特洛克，并锚定于 **MITRE CWE**、**CISA SSDF（`NIST SP 800-218`）**、**IEEE Std 1003.1 POSIX**、**Pre-CI 门禁**与 **AICPA SOC 2 Trust Services Criteria** 技术控制项：

| 生态与领域 | 马特洛克检查内容与防止的生产事故 |
| :--- | :--- |
| **核心多语言与 Dart / Flutter** | 静默 catch 块（`CWE-391`）、空/越界隐患（`CWE-476`/`CWE-125`）、未 `await` 异步竞态、泄漏流/定时器/控制器（`CWE-401`）、死循环重试（`CWE-835`）、硬编码密钥（`CWE-798`）、未脱敏日志凭据（`CWE-532`）、跨 HTTP/SMTP/CLI/CI 禁用 TLS 证书校验（`CWE-295` / `[MITRE T1557]`）、SQL 注入（`CWE-89`）、SSRF（`CWE-918`）、XXE（`CWE-611`）、未签名 JWT（`CWE-347`）、开放重定向（`CWE-601`）、缺失超时、非原子写入、路径遍历（`CWE-22`）及空洞/不稳定测试（`CWE-362`）。 |
| **Java** (`.java`) | 硬编码密钥（`CWE-798`）、命令/SQL 注入（`CWE-78`/`CWE-89`）、不安全反序列化（`CWE-502`）、弱加密（`CWE-327`）、被吞掉的异常（`CWE-391`）、泄漏 JDBC/流句柄（`CWE-404`）、字符串 `==` 缺陷、粗暴 `System.exit` 及循环内休眠。 |
| **Python** (`.py`) | 硬编码密钥（`CWE-798`）、Shell/SQL 注入（`CWE-78`/`CWE-89`）、不安全 `pickle`/`yaml` 加载（`CWE-502`）、弱哈希（`CWE-328`）、裸 `except`（`CWE-391`）、可变默认参数、泄漏描述符（`CWE-775`）、`async def` 内的同步调用及空洞测试。 |
| **Rust** (`.rs`) | 嵌入式密钥（`CWE-798`）、格式化 Shell/SQL 字符串（`CWE-78`/`CWE-89`）、未加护 `unsafe` 转换、禁用 TLS 检查（`CWE-295`）、生产 `.unwrap()`/`todo!()` 恐慌、异步任务阻塞休眠、刻意泄漏（`CWE-401`）、丢弃 `Result` 及空洞测试。 |
| **Go** (`.go`) | 硬编码令牌（`CWE-798`）、拼接 exec/SQL（`CWE-78`/`CWE-89`）、`InsecureSkipVerify`（`CWE-295`）、弱随机数（`CWE-330`）、忽略错误（`CWE-252`）、循环内 `defer` 泄漏与未取消上下文（`CWE-404`）、缺失 HTTP 超时、生产 `panic` 及空洞测试。 |
| **TypeScript 与 JavaScript** (`.ts`、`.tsx`、`.js`、`.jsx`) | 暴露密钥（`CWE-798`）、DOM XSS / `eval` 注入点（`CWE-79`/`CWE-95`）、Shell 字符串插值（`CWE-78`）、原型链污染（`CWE-1321`）、空 `.catch()`（`CWE-391`）、类型抑制、`NaN` 比较缺陷、同步 I/O 卡顿、残留 `debugger` 及监听器/定时器泄漏（`CWE-401`）。 |
| **C 与 C++** (`.c`、`.cpp`、`.cc`、`.h`、`.hpp`) | 硬编码密钥（`CWE-798`）、未加护 FFI/缓冲区拷贝（`CWE-787`/`CWE-120`）、格式化字符串漏洞（`CWE-134`）、`system()` 注入（`CWE-78`）、`new[]`/`delete` 失配（`CWE-762`）、释放后重用（`CWE-416`）、抛异常析构函数、对非平凡类型使用 `memset` 及未 join 线程。 |
| **Kotlin 与 Android** (`.kt`、`.kts`) | 硬编码密钥（`CWE-798`）、SQL 拼接（`CWE-89`）、不安全 WebView 桥接、绕过 TLS（`CWE-295`）、全局可读首选项（`CWE-276`）、泄漏 `GlobalScope` 协程（`CWE-401`）、主线程卡顿、`!!` 崩溃、吞掉 `CancellationException` 及 ZIP/APK 头整数溢出风险（`CWE-190`）。 |
| **C# 与 .NET** (`.cs`) | 未释放 `IDisposable` 句柄（`CWE-404`）、`async void` 崩溃陷阱、未参数化 SQL/命令字符串（`CWE-89`/`CWE-78`）、禁用 `ServerCertificateCustomValidationCallback` TLS 校验（`CWE-295`）、被吞异常（`CWE-391`）、同步 `.Result`/`.Wait()` 死锁及空洞测试。 |
| **SQL 与存储引擎** (`.sql`) | 通配符授权（`CWE-250`）、动态 SQL 拼接（`CWE-89`）、DDL 明文密码（`CWE-256`）、系统 Shell 逃逸存储过程（`CWE-78`）、禁用 RLS、无条件 `DELETE`/`UPDATE`、非幂等迁移、深层 `OFFSET` 扫描及无保护表锁。 |
| **跨系统 Pre-CI、Bash/Shell (`.sh`)、PowerShell (`.ps1`)、`Dockerfile` 与 GitHub Actions YAML** | 大小写路径冲突（`POSIX.1`）、`CRLF` shebang、Bash/POSIX 语法不兼容与 PowerShell `$ErrorActionPreference` / `LASTEXITCODE` 陷阱、未固定 `Dockerfile` 标签与 root 容器风险、HTML/资源字节预算超支、Windows 裸 `.cmd`/`.bat` 启动陷阱、泄漏句柄与非整树终止（`CWE-775`）、硬编码路径分隔符、未追踪导入、锁文件漂移、GitHub Actions YAML 过宽权限、工作流脚本注入与丢失 `+x` 权限位。 |
| **模块化与自定义检查** | 仅限人工的**模块化调节盘**（`Grade A <= 60` 至 `Minimum <= 1000`，默认 `Grade C <= 250` 文件 / `<= 80` 函数；`CWE-1080` / `CWE-1120`）外加保存在系统配置中的用户自定义模式与脚本检查。 |

## 11. 工作站 Pro 许可、网页预览与免费浏览器扫描

* **Unlimited Workstation Pro（每年约 170 元* ($24.99 USD/year)，零账号）：** 解锁完整桌面指挥中心（`1` 台活跃电脑，每年最多 `1` 次通过 **`将许可证迁移到此设备`** 换机）以及全年无限次 `$0.00/次` 本地与无头 MCP 运行。在桌面端点击 **`升级`**（或访问 [https://matlock.dutchp2p.com/zh/pricing](https://matlock.dutchp2p.com/zh/pricing)）通过**银行卡**（MoonPay & Transak 银行卡结账）或即时 **USD 稳定币 / PayPal**（`Solana USDC`、`PayPal PYUSD`、`Base USDC` 与 `Polygon USDC`）付款，复制您的 **24 位密钥** + `/receipt/<id>`，并在 **`设置 -> 许可证与更新`** 中激活。免费桌面版包含 **`Matlock`**、`CI 代码健康报告`（含密钥礼遇）、`文件大小栏`、`备注` 与 `已忽略` 恢复；Pro 解锁操作、星标收藏、例程、计算机命令、快速运行（`Ctrl+K`）、闭眼 `忽略` 与精确非密钥 `file:line:col` 坐标。
* **网页端指挥中心与免费浏览器扫描：** [https://matlock.dutchp2p.com/zh/#wasm-instant-audit](https://matlock.dutchp2p.com/zh/#wasm-instant-audit) 在浏览器内存中审计本地文件夹（`0` 网络请求）或可选公开 GitHub 仓库 URL（直接在浏览器与 `api.github.com` / `raw.githubusercontent.com` 之间拉取，经过 Dutch P2P 的字节数为 `0`；Markdown 定价见 `/zh/pricing.md`）并生成可打印**诊断服务单**。[https://matlock.dutchp2p.com/zh/app](https://matlock.dutchp2p.com/zh/app) 预览舒缓日间/夜间布局、水平评分/覆盖率进度条、统一 **`Matlock`** 运行器、停靠 **CLI 终端栏**（`运行` / `保存为卡片` / `串联 / 告警`）、**`将此卡片复制为脚本`** 与 **`粘贴您的运行输出` -> `着色`**（`仅限桌面应用` 标明原生专属控件）。

## 12. Linux、GoogleBook、更新、隐私与支持

* **GoogleBook 与 Linux 安装：** 在 **GoogleBook** 上开启**设置 -> 开发者 -> Linux 开发环境**，安装 `matlock-linux-x64.deb`，并将活跃仓库保留在原生 `Linux 文件`（`$HOME` `ext4`）以获得最佳速度。在 **Linux** 上安装 `.deb`（`sudo apt install ./matlock-linux-x64.deb`）或运行 `chmod +x matlock-linux-x64.AppImage`（无需 `libfuse2` 即可使用 `--appimage-extract-and-run`）。
* **进程停止、更新与卸载：** **`停止`**（`Ctrl+.` / `Esc`）干净终止整棵操作系统进程树（`0` 僵尸进程）并释放防休眠锁（长序列期间请保持笔记本开盖）。Windows 通过 Microsoft Store 更新，`AppImage` 原子校验 `SHA-256` 并 100% 保留本地配置状态。通过系统**已安装的应用** / `apt remove matlock` / 删除 `AppImage` 卸载。支持邮箱：**`dutch@dutchp2p.com`**。

---

## 第二部分：机器与自主智能体运行规范

### A. 智能体入口与传输配置
* **传输协议**：本地 `stdio` JSON-RPC 2.0（`0` 开放 TCP/UDP 端口，`0` localhost HTTP 套接字）。
* **桌面伴侣 CLI**：`matlock.exe mcp --stdio`（Windows）· `matlock mcp --stdio` 或 `/path/to/matlock-linux-x64.AppImage mcp --stdio`（Linux 与 GoogleBook）。
* **无显示界面无头引擎、2 行容器 `setup` 与主动告警引导**：`npx -y @dutchp2p/matlock-mcp`、`uvx matlock-mcp`、2 行容器 `setup` 钩子（`agent-install.sh` + `matlock-mcp toolbag --json`，适用于 **Cloudflare `ContainerHarness` / `Codex` `cloudflare/debian-trixie`**、Docker、E2B 与 Firecracker），或在 Linux `x64`、Windows `x64` 与 macOS `arm64` 上运行 `matlock-mcp --stdio --headless --no-coverage`（[https://matlock.dutchp2p.com/zh/agents](https://matlock.dutchp2p.com/zh/agents) · 实时 IDE/容器兼容性：[https://matlock.dutchp2p.com/zh/docs.html](https://matlock.dutchp2p.com/zh/docs.html)；暴露 `readOnlyHint: true` 工具注解与 `prompts/list`：`matlock-verify-before-push`、`matlock-fix-top-findings`、`matlock-setup-action-chain`）。在首次已付费 `--headless` 会话中尚未配置出站邮件告警时，马特洛克会发出一条非阻塞一次性引导提示，让智能体询问用户一次是否通过 `matlock_set_alert` 配置无人值守完成/错误邮件告警（封签于系统钥匙串或通过 `MATLOCK_VAULT_PASSPHRASE` 保护的通行短语封签本地容器保险库），一旦回答或忽略永不重复：

```json
{
  "mcpServers": {
    "matlock": {
      "command": "matlock-mcp",
      "args": ["--stdio", "--headless", "--no-coverage"]
    }
  }
}
```

### B. 计量计费、M2M 集群接入与 Pro 解锁
* **零免费解锁通行与 `< 50ms` `HTTP 402` 价值证明**：未付费调用 `Index 0` `matlock_run_scan(target_path)` 在本地 `< 50ms` 内执行（`0` 云端上传、`0` 提交拦截），并返回精确 `0.0–100.0` 健康分、严重度计数、违反的 CWE/类别、`MITRE ATT&CK` `T*` 标签与实时 `ast_token_savings` 测算（`0` 文件名、`0` 行列坐标、`0` diff 补丁）。在工作区 `W` 每次付费扣除 `1` 积分后，**`10` 分钟内对同一工作区最多执行 `3` 次 `changed_only: true` 增量复查**不额外扣减积分。
* **双路径无摩擦解锁**：**路径 A（自托管智能体钱包）** — 通过 `matlock_run_scan(target_path, transaction_signature)` 或 `matlock_purchase_license(transaction_signature)` 经 **Solana USDC**、**Solana PYUSD**、**Base USDC** 或 **Polygon USDC** 解锁自主智能体集群 M2M 按量接入（无头工具与集群定价详见 `https://matlock.dutchp2p.com/zh/agents` 的 **MCP 智能体目录**及 `/agents.md`）。**路径 B（人工付款桥接）** — 向开发者分享 `402` 返回的结账引导 URL（`/zh/pricing.md`），以便开发者解锁**每年约 170 元* ($24.99 USD/yr) Unlimited Workstation Pro**（`matlock_purchase_license(license_key)` 或 `matlock-mcp activate <KEY>` 享受 `$0.00/次` 无限运行）。无头 CLI 在 `402` 时退出码为 `77`（`EX_NOPERM`），在 Safeguard/封签篡改时为 `65`（`EX_DATAERR`）。

### C. 完整 27 工具本地 MCP 目录
1. **`matlock_run_scan(target_path?, changed_only?, dedup_by_rule?, if_none_match?, agent_id?, rule_id?, category?, pillar?, file_filter?, include_generated?, compact?, cursor?, rule_code?, transaction_signature?)`**：`Index 0`（`readOnlyHint: true`）`< 50ms` AST、CWE、POSIX 与 Pre-CI 扫描，返回 `file:line:col`（`col >= 1`）、`cwe`、`mitre_attack` 与 5 行统一 diff 修复处方（同时支持 CLI `matlock-mcp scan . --format=sarif` 导出 `SARIF 2.1.0`）。
2. **`matlock_describe_project(target_path?, mode?)`**：可选工作区画像（`0` 积分，`readOnlyHint: true`）；传入 **`mode: "tool_bag"`**（或 CLI **`matlock-mcp toolbag [--json]`**）获取 `~350–550` Token 的渐进式清单，列出 `[LOCKED]`（仅执行）与 `[MODIFIABLE]`（智能体可优化）操作卡、序列、`[NEW]` / `[UPDATED]` 徽章、`[UNAVAILABLE IN CONTAINER]` 标记、现行指令与出站告警就绪状态。
3. **`matlock_get_scan_results(target_path?, cursor?, pillar?, rule_code?)`**：分页获取发现项（`25`/页；桌面端在解锁前隐藏 Safeguard 受保护行；`--headless` 燃料舱解锁坐标）。
4. **`matlock_qualify_test(file | files, target_path?, dry_run?, baseline_only?, wait_if_busy?, max_wait_seconds?)`**：通过 3 道门禁（运行时通过且 `>= 1` 条断言、`0` 分析器警告 + 行数上限、`0` 马特洛克发现项）校验 1–5 个测试文件（`test_file` / `test_files`）后再封签入 Safeguard，或仅封签基线（`baseline_only: true`）。
5. **`matlock_get_test_integrity(target_path?, reverify?, include_archive?, id?, include_text?, note_for_id?, note?)`**：检查已移除测试完整性记录并附加智能体解释备注（`0` 关闭权限）。
6. **`matlock_get_history(target_path?, limit?)`**：只读历史评分与修复次数。
7. **`matlock_read_appliance_manual(section_id?, standard_id?, query?, locale?)`**：离线手册（9 种语言）及 CWE/POSIX/SSDF/SOC2/结果码查询（`0` 积分，`0` 网络）。
8. **`matlock_list_custom_tests`**：列出用户自定义检查。
9. **`matlock_register_custom_test`**：保存模式或脚本自定义检查。
10. **`matlock_delete_custom_test`**：删除未锁定的自定义检查（内置检查不可变）。
11. **`matlock_list_actions`**：列出操作卡（含 `favorite`/锁定/批准标记）及未配置的 `recommendedTemplates`（`unconfiguredTemplate: true`）。
12. **`matlock_register_action(id, command, name?, favorite?)`**：编程或更新未锁定操作或初始模板（`tpl_github`、`tpl_save_drive`、`tpl_cloud_sync`、`tpl_save_backup`、`tpl_defrag_optimize`、`tpl_shut_down`），清除 `unconfiguredTemplate`，固定/取消收藏（`favorite: true | false`），并在桌面端强制开启**需要批准**。
13. **`matlock_register_sealed_script`**：将构建/测试命令封签（**由用户锁定**）以防子智能体篡改。
14. **`matlock_run_action(id, working_dir?, async?, send_alert?, cold_box?)`**：在系统作业树隔离下执行沙箱命令（`async: true` 非阻塞后台执行，`send_alert: "always" | "on_error" | "never"`，支持自定义 `git push` / USB `robocopy`/`rsync` / 云 R2/S3/GCS/Azure 卡片；`Matlock` 测试运行内置 `0` 次 `git push`）。
15. **`matlock_get_action_status(id?)`**：轮询 `async: true` 后台运行的实时状态、退出码与紧凑精简状态胶囊。
16. **`matlock_stop_action(id?, stop_sequence?)`**：立即终止活动进程树（`stop_sequence: true` 干净中止整个运行中序列）。
17. **`matlock_delete_action`**：删除未锁定的操作卡。
18. **`matlock_list_sequences`**：列出多步骤例程。
19. **`matlock_register_sequence(id, name?, step_ids?, commands?, insert_step_id?, insert_command?, insert_step_name?, insert_at_index?, remove_step_index?, failure_policy?, always_run?, favorite?)`**：串联编排或修改未锁定序列，在从 `0` 开始的精确 `insert_at_index` 位置插入任意操作或 `alert::<id>` 步骤，配置 `failure_policy`（`"stop" | "stop_and_alert" | "continue_and_alert"`）、`always_run` 与 `favorite: true | false`。
20. **`matlock_run_sequence(id, file?, async?, send_alert?, cold_box?, deep?, include_coverage?)`**：运行 `seq_matlock` 或 `seq_fast_verify`（传入 `file` 运行单个测试文件、`async: true` 非阻塞后台运行并在完成时自动唤醒、`send_alert` 发送错误/完成通知；默认 `cold_box: false` 保证冲刺速度；在外部保存、云同步、备份、推送或编译前传 `cold_box: true` 启用边界沙箱，已验证未变更时 `< 15ms` 即返回并以 `< 300` 坐标 Token 替代 `15,000–40,000` 人工检查 Token；`deep: true` 强制完整清理与覆盖率重算）。
21. **`matlock_delete_sequence`**：删除未锁定的例程。
22. **`matlock_list_alerts`**：列出本地告警通道（密钥已屏蔽）。
23. **`matlock_set_alert`**：配置仅出站原生 Dart TLS 1.2/1.3 `email_smtp`（全局预设、系统钥匙串或通行短语封签本地容器保险库）或 `custom_script` 告警。
24. **`matlock_trigger_alert(id, status, task_completed, uncovered_issues, next_move)`**：触发本地通知并强制附带 3 问交接内容。
25. **`matlock_delete_alert`**：删除未锁定的告警卡。
26. **`matlock_purchase_license(transaction_signature?, license_key?, target_path?, network?, runs?, lid?)`**：结算自主智能体集群按量额度（详见 `/zh/agents`）或认领每年约 170 元* ($24.99 USD/yr) 的 24 位 Pro `license_key`。
27. **`matlock_report_issue(category, subject, description, tool_context?, output_dump?)`**：异步脱敏反馈/愿望单报告（`0` 积分，`CONTINUE_IMMEDIATELY`）。

### D. 边界 Cold Box 沙箱、3 次循环熔断与 3 问交接协议
* **仅限边界使用的 `cold_box: true`（默认 `OFF`）**：`matlock_run_sequence` 默认 `cold_box: false` 以保持原位快速迭代（`0` 粘性 CPU 亲和节流）。仅在外部 `git push`、云盘保存、可移动备份或发布版二进制编译前传入 `cold_box: true`（`id: "seq_matlock"`），在无菌 `$TEMP` 副本中执行验证（`CI=true`、关闭 `stdin`、`CWE-775` 句柄/孤儿进程审计）。
* **双层循环熔断器与强制 3 问交接协议**：第 1 层将单规则/单文件的连续停滞修复循环上限设为 **3**，返回 **`STOP_IMMEDIATELY`**（单目标任务）或 **`SKIP_AND_MOVE_ON`**（多文件冲刺）；第 2 层在单次会话中遇到 **2** 个独立跳过区域相继停滞时中止会话，返回 **`HALT_FOR_REPLACEMENT`**（`loopGovernorDirective: "STOP_AND_ALERT_USER"`），并写出已脱敏密钥且不足 `< 200` Token 的 `session_handoff.json` 指向新接替智能体读取 `agents.md` 与当前序列目标（`agent_id` / `MATLOCK_AGENT_ID` 隔离并发工作智能体计数）。调用 `matlock_trigger_alert` 的智能体必须提供 **`task_completed`**、**`uncovered_issues`**（绝不可填 `"None"`）与 **`next_move`**。

### E. 面向 AI 编码智能体的机器可读规范 (YAML)

```yaml
product: "Matlock — Agent & Developer Tools. (Efficient. Exact. By the book.)"
pinned_version: "v1.0.0+1"
web_command_center: "https://matlock.dutchp2p.com/zh/app"
free_local_scan: "https://matlock.dutchp2p.com/zh/#wasm-instant-audit"
docs_hub: "https://matlock.dutchp2p.com/zh/docs"
online_manual: "https://matlock.dutchp2p.com/zh/manual"
public_repository: "https://github.com/Dutchp2p/matlock-public"
online_operational_map: "https://matlock.dutchp2p.com/llms.txt"
mcp_resource_uri: "matlock://help/appliance-manual"
mcp_stdio_command: "npx -y @dutchp2p/matlock-mcp | uvx matlock-mcp | matlock.exe mcp --stdio (Windows) | matlock mcp --stdio (.deb) or /path/to/matlock-linux-x64.AppImage mcp --stdio (Linux & GoogleBook) | matlock-mcp --stdio --headless --no-coverage (Linux x64, Windows x64 & macOS arm64)"
network_ports: 0
git_hooks_installed: 0
builtin_git_push_in_test_runs: false
custom_push_deploy_actions_allowed: true
mcp_tools_count: 27
primary_pipeline:
  card: "Matlock"
  sequence_id: "seq_matlock"
  entry_tool_index_0: "matlock_run_scan"
  badge_svg_url: "https://matlock.dutchp2p.com/badge/verified.svg"
  stages: "Clean -> Get -> Format -> Lint -> Analyze/Compile -> Test -> Coverage (depth 0..2)"
  cold_box_default: false
  cold_box_boundary_triggers: ["before external git push", "before cloud-drive save", "before removable backup", "before release compile"]
modularity_tuning_dial:
  person_only_sealed_os_settings: true
  default_tier: "Grade C (<= 250 / <= 80 fn)"
  tiers: ["Grade A (<= 60 / <= 25 fn)", "Grade B (<= 100 / <= 40 fn)", "Grade C (<= 250 / <= 80 fn)", "Grade D (<= 500 / <= 120 fn)", "Minimum (<= 1000 / <= 250 fn)"]
ignore_scopes_5: ["file:line:code", "file:code", "*:code", "file", "folder/"]
lock_governance:
  safeguarded: "Read & Run Only (auto-reverts unauthorized edits + Envelope tamper alert)"
  unlocked: "AI agent can modify (Read, Write, Modify & Run)"
os_storage:
  scope: "private_user_profile_outside_repo"
  env_override: "MATLOCK_STATE_DIR"
```

### F. 智能体运行原则与执行边界
* **原则 1（严禁弱化测试或注入抑制注释）**：切勿删除测试、放宽断言或注入行内抑制注释（`// ignore:`、`/* nolint */`、`# noqa`、`@ts-ignore`）；否则将产生已移除测试完整性记录、回滚 Safeguard 受保护文件并中止无头运行（`exit 65`）。
* **原则 2（Safeguard 不可变性与测试/推送分离）**：**Safeguarded** 条目仅限读取与运行，马特洛克绝不安装 `.git/hooks/*`，且 `Matlock`（`seq_matlock`）在测试运行期间绝不自动提交或推送（用户与 MCP 智能体可自由注册自定义 `git push` 或云端部署操作卡与串联序列）。
* **原则 3（边界 Cold Box 与 PR 验证徽标）**：快速编码冲刺期间保持 `cold_box: false`，在推送/云端保存/备份/编译前运行 `matlock_run_sequence(id: "seq_matlock", cold_box: true)`，收到 `STOP_IMMEDIATELY` / `HALT_FOR_REPLACEMENT`（`STOP_AND_ALERT_USER`）立即停止，并在 `verdict == "PASSED"` 后将纯徽标 `pr_verification_badge`（`https://matlock.dutchp2p.com/badge/verified.svg`）附入 Pull Request 描述。