🌟 它能做什么

AI 写 Python 很顺手。写 BSV？一编译满屏红——不是 AI 笨，是 BSV 太冷门，训练数据全是老版本。specmate 不替 Agent 写代码，它在 Agent 落笔之前先把坑指出来。

• 陷阱预测 — 你做 FIFO pipeline？上一个 Agent 在这翻了三次，我给你标出来。基于 30 个领域知识图谱节点，提前扫雷。
• 静态检查 — 19 条规则扫一遍 .bsv，方法顺序、Bool 运算符误用、SV 保留字冲突、字面量溢出。不调 bsc，秒出结果。
• 错误诊断 — 把 BSC 那满屏红丢进来，29 篇编码记忆逐一比对，告诉你根因和怎么修。不认识的新错误？自动入库记下来。
• 记仇的 code buddy — 编译报错 → capture 记一笔 → 修好 → resolve 归档。SQLite 驱动，每次命中自动 +1。同一条坑不踩两次——它真记仇。
• 代码审查 — tree-sitter 真解析 BSV 语法树，不是正则匹配。调度冲突矩阵、跨 rule 冲突、依赖图——给你画出来。

🚀 快速开始

安装

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

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

npm install @Alele496/bsv-specmate@0.2.0

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（Developer Tools 类别）。在支持 Registry 的客户端中，可通过 mcp add bsv-specmate 一键安装，无需手动编写配置文件。

🎚️ 三级干预强度：

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

验证

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

🔧 MCP 工具一览

specmate 通过 8 个 MCP 工具供 AI Agent 调用。

specmate_scan 是推荐统一入口，替代旧的多次分步调用。完整集成说明（AGENTS.md 模板、OpenCode 配置、角色提示词）见 Agent 集成手册。

📋 Agent 工作流

拿到 BSV 任务
  │
  ├─ specmate_scan({ task: "你的任务" })
  │   └→ 陷阱预测 + 设计建议 + 推荐范式
  │
  ├─ 写代码
  │
  ├─ specmate_check({ files: ["绝对路径/文件.bsv"] })
  │   └→ 19 条规则快速扫描
  │
  ├─ bsc 编译
  │   ├─ 通过 → specmate_resolve 固化经验 ✅
  │   └─ 报错 → specmate_diagnose 诊断 + specmate_capture 捕获
  │       └→ 修复 → 回到编译 → 通过 → resolve ✅

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

📊 效果速览

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

... View full README on GitHub