specmate 🤝

BSV 的 AI 原生开发环境——编译前提醒你避坑，编译后帮你理清为什么错了，越用越懂你。

安装 • 工具 • 工作流 • 效果 • 状态 • 结构 • 文档 • 站点

🌟 它能做什么

AI 写 Python 很顺手。写 BSV？一编译满屏红——不是 AI 笨，是 BSV 太冷门，训练数据全是老版本。specmate 不替 Agent 写代码，它在 Agent 落笔之前把坑指出来，编译之后再帮它分析为什么错、怎么修。

编译前：预检查

• 陷阱预测 — 你做 FIFO pipeline？上一个 Agent 在这翻了三次，我给你标出来。基于 31 个领域知识图谱节点，提前扫雷。
• 静态检查 — 19 条规则扫一遍 .bsv，方法顺序、Bool 运算符误用、SV 保留字冲突、字面量溢出。不调 bsc，秒出结果。
• 代码审查 — tree-sitter 真解析 BSV 语法树，不是正则匹配。调度冲突矩阵、跨 rule 冲突、依赖图——给你画出来。

编译后：分析引擎（求解器）

• 错误诊断 — 把 BSC 那满屏红丢进来，36 篇编码记忆逐一比对，告诉你根因和怎么修。不认识的新错误？自动入库记下来。
• 收敛检测 — 同一个错误修了三轮还在报？specmate 告诉你"你在原地打转，换策略"。
• Session 回溯 — 每个开发 session 结束时自动分析：编译效率评分、横跳模式、知识缺口。不增加 Agent 操作负担。
• 跨 session 模式挖掘 — 多个 session 反复出现的未知错误，自动分析根因、生成知识条目草稿，人工审核确认后入库。

自增长知识闭环

• 记仇的 code buddy — 编译报错 → capture 记一笔 → 修好 → resolve 归档。SQLite 驱动，每次命中自动 +1。同一条坑不踩两次——它真记仇。
• 自动学习 — 不是每次新错误都需要人手写文档。模式挖掘管道自动发现、LLM 辅助分析、人审核确认——知识库自己长。

知识库自带 B-Lang-org/bsc 官方测试套件的 4,569 条示例代码（specmate example 可按关键词检索）——编译前检查规则与编译后诊断均可回溯到真实官方用例。

🚀 快速开始

安装

specmate 有两个发布渠道，根据你的需求选择：

GitHub Packages（推荐） — 主力发布渠道，每个版本都第一时间发布，始终最新：

npm install @Alele496/[email protected]

npm — 稳定发行版，仅在经过充分验证后发布，版本更新可能滞后：

npm install -g bsv-specmate

如何选择？ 追求新功能和最新陷阱知识选 GitHub Packages；在关键项目中使用、优先稳定性选 npm。两者功能完全一致，区别仅在于发布节奏。

需要 Node.js >= 18。使用 GitHub Packages 前需要先配置 npm registry，见 新手指南。

配置 MCP

在 BSV 项目根目录创建 .mcp.json：

{
  "mcpServers": {
    "bsv-specmate": {
      "command": "npx",
      "args": ["bsv-specmate"]
    }
  }
}

启动 AI 客户端（Claude Code / OpenCode 等），Agent 自动发现 specmate 工具。

📡 通过 MCP Registry 发现：specmate 已注册到 MCP Registry（命名空间 io.github.Alele496/bsv-specmate）。在支持 Registry 的客户端中，可通过 mcp add bsv-specmate 一键安装，无需手动编写配置文件。

🎚️ 三级干预强度：

| 模式 | 行为 | |------|------| | verify 社恐模式 | 零推送，默默旁观。code review 定稿前再出声 | | develop 日常模式（默认） | 编码前主动推送陷阱，该提醒的时候绝不含糊 | | tapeout 话痨模式 | 全量守护，交付前不留死角，每个检查项都过一遍 |

别名：silicon = verify、wafer = develop（tapeout 无别名）。代码与配置用 verify/develop/tapeout 三级，silicon/wafer 是同一等级的形象化别名（第四战实验即按 silicon/wafer/tapeout 三档命名）。

验证

让 Agent 写一段 BSV 代码，specmate 会自动介入。有返回结果就说明配置成功。详细步骤和常见问题见 新手指南。

🔧 MCP 工具一览

specmate 通过 9 个 MCP 工具供 AI Agent 调用（第 10 个工具 specmate_step 正在开发中，未随公开版发布）。

| 工具 | 用途 | 何时调用 | |------|------|---------| | specmate_scan ⭐ | 统一入口：陷阱预测 + AST 预扫描 + 设计建议 | 拿到新任务时，编码前 | | specmate_check | 19 条规则静态扫描 .bsv 文件 | 写完一段代码后，编译前 | | specmate_diagnose | 传入完整 BSC 编译输出，批量诊断 + 收敛检测 + 修复优先级建议 | 编译结果一屏幕红 | | specmate_capture | 解析 BSC 编译错误，自动新增知识 + 收敛告警 | 编译报错时 | | specmate_resolve | 固化修复方案，标记错误已解决 | 错误修好之后 | | specmate_analyze | tree-sitter 深度解析 BSV 语法树 | 排查调度冲突、依赖问题时 | | specmate_report | 跨 session 分析：错误趋势 / 文件热点 / 知识库健康度 / 知识增长机会 | 想看整体开发状况时 | | specmate_diff | 对比编译结果快照，追踪 warning 变化 | 重构后对比编译变化 | | specmate_guide | 分阶段指导（pre_code / on_error / continue / decide / pattern） | 需要分步引导时 |

specmate_scan 是推荐统一入口，替代旧的多次分步调用。specmate_diagnose 和 specmate_capture 内置了编译后分析引擎——收敛检测、session 回溯、修复优先级建议，Agent 零额外操作，自动嵌入响应。完整集成说明（AGENTS.md 模板、OpenCode 配置、角色提示词）见 Agent 集成手册。

📋 Agent 工作流

拿到 BSV 任务
  │
  ├─ specmate_scan({ task: "你的任务" })
  │   └→ 陷阱预测 + 设计建议 + 推荐范式
  │
  ├─ 写代码
  │
  ├─ specmate_check({ files: ["绝对路径/文件.bsv"] })
  │   └→ 19 条规则快速扫描
  │
  ├─ bsc 编译
  │   ├─ 通过 → specmate_resolve 固化经验 ✅
  │   └─ 报错 → specmate_diagnose 诊断
  │       ├→ 错误码匹配 + 根因分析
  │       ├→ 收敛检测："你在 G0004 上卡了 3 轮了"
  │       └→ 修复优先级："先修这个，能消除 5 个下游错误"
  │     specmate_capture 捕获 → 修复 → 回到编译
  │
  └─ Session 结束
      └→ 自动回溯分析：编译效率评分 + 知识缺口识别
         └→ 跨 session 模式挖掘：新错误模式 → LLM 分析 → draft → 人审核 → 入库

Agent 不知道 specmate？你不是第一个。 第一场实验里 Agent 全程 0 次调 specmate——不是工具不好，是它不知道有这个 mate。在对话里说一句"试试用 specmate_scan 扫一下你的任务"就够了。

📊 效果速览

不是随口说的——我们做了八场对照实验。Agent 完成同一个 BSV 项目，唯一区别是带了 specmate 还是裸写。

第一场，Agent 连 specmate 都不知道存在，全程 0 次调用——问题不在工具，在 Agent 不认识这个 mate。第二场 Agent 开始主动调用了，但时机不对——写完代码才 scan，等于考试交卷了才看复习笔记。第三场我们拉了不认识双方的 Agent 做双盲评审——带 specmate 的方案代码质量盲审高出 16%，评审人不知道哪份是谁写的。第四场优化了模板约束，首次编译通过率显著提高。第五场聚焦审查角色——最有效的不是堆更多规则，而是给 Agent 一个审查角色，让它知道该在什么时候调哪个工具。第六到第八战转向 specmate_bench 自动化评测框架：SD 卡战编码时间 -47%、SPI 战修复轮数再降 50%、第八战验证 /bench 全自动模式。

核心结论：specmate 的价值不是替 Agent 写代码，而是替 Agent 记住那些它学一次忘一次的 BSV 冷知识——以及它在哪些地方反复撞墙。

完整数据、实验设计和方法论分析见 SHOWDOWN 报告。

📈 当前状态

• 版本 0.2.0，通过 GitHub Packages 主力发布（@Alele496/[email protected]），npm 频道发布经过验证的稳定版本
• 9 个 MCP 工具全部可用，CI 自动化验证
• 32 条 BSV 陷阱，约 100 个 fixture 文件（pass + fail 对）
• 36 篇编码记忆覆盖常见 BSC 编译错误与仿真失败模式
• 31 个领域知识图谱节点，19 条静态检查规则
• 编译后分析引擎上线：收敛检测 + session 回溯 + 跨 session 模式挖掘
• 281 测试全绿（55 单元 + 18 fixture + 160 烟雾 + 48 HTTP）
• pre-commit hook 拦截 + GitHub Actions CI 双保险

📂 项目结构

specmate/
├── bin/                  # MCP 服务器入口（stdio / HTTP）
├── src/
│   ├── tools/            # 9 个 MCP 工具实现
│   ├── solver/           # 编译后分析引擎（收敛检测 / 回溯 / 模式挖掘）
│   ├── db/               # SQLite 知识库持久化（schema / operations / query 三层）
│   ├── api/              # HTTP API 路由
│   └── config.mjs        # SPECMATE_LEVEL 配置
├── docs/
│   ├── errors/           # 36 篇编码记忆（含 6 篇仿真失败模式）
│   ├── traps/            # 已验证陷阱文档
│   └── council/          # 议会决策记录
├── test/fixtures/        # 每条规则对应 pass.bsv + fail.bsv
├── scripts/              # 审核脚本 / 验证脚本
└── examples/             # BSV 示例代码

核心思路：MCP 工具层承接 Agent 调用 → 知识图谱做匹配 → 求解器做编译后分析 → SQLite 持久化经验。编译前提醒 + 编译后分析 = 全链路覆盖。

📖 文档

• 第一次用？ 读 新手指南 — 安装、配置、三步走完。
• 接入 Agent？ 读 Agent 集成手册 — AGENTS.md 模板、OpenCode 配置、角色提示词。
• 想了解设计？ 读 架构文档 — 设计决策、模块关系、数据流。
• 想看数据？ 读 SHOWDOWN 报告 — 八场对照实验完整设计和分析。
• 想了解未来方向？ 读 议会 S04E01 — specmate 从"知识引擎"到"硬件开发运行时"的长期路线。
• 深入源码？ 读 内部总览 — 源码结构、数据库 schema、工具实现细节。

🤝 贡献

specmate 的知识来自实战踩坑。你遇到 bsc 报错了，Agent 用 specmate_diagnose 诊断 → specmate_capture 记下来 → 修好以后 specmate_resolve 固化 → 补一篇文档说清根因和修复方案。编译后分析引擎会自动发现跨 session 的错误模式，生成知识条目草稿等待审核。每条知识都让下一个写 BSV 的人少踩一个坑。

欢迎提 Issue 和 PR。规则和陷阱的 fixture 贡献尤其欢迎。fixture 是什么？每条检查规则配两个 .bsv 文件——pass.bsv 是通过用例（写对了不该报），fail.bsv 是失败用例（故意触发规则应该报）。新增规则时跑 node test/fixtures/run-fixtures.mjs 验证全部 fixture，不通过不能合并——这是议会定的铁律，谁来都一样。具体目录结构和示例看 test/fixtures/check/ 下面已有的规则。

🔗 相关项目

• Kova — DKE 领域知识引擎框架，specmate 是它的第一个 BSV 实例
• bsc — Bluespec 官方编译器，specmate 的知识库依赖 bsc 的编译输出来积累经验
• bsc-contrib — Bluespec 社区库和工具集，写 BSV 时常配合使用

MIT License | Alele496