🛡️ AgentSeed

为 AI 编码代理准备的反幻觉护栏。

一个混合式 Agent Plugins 插件（技能 + MCP 服务器），它强制进行规范驱动开发，并在代码被标记为「完成」之前验证代码——于是「Done, all tests pass」成为一项可观察到的事实，而非一句声明。

English · 中文 · 日本語

⭐ 喜欢这个项目吗？可以考虑给它加一颗星——它能帮助开发者在把幻觉代码发布出去之前，先找到这些护栏。

为什么需要 AgentSeed

LLM 会产生幻觉——体现在代码中，就是发明不存在的 API、使用未定义的标识符、虚假的测试通过，以及过分自信的断言。数字如下：

• 15.1% 的代码幻觉属于知识冲突：调用了未定义或从未导入的 API (arXiv:2404.00971)。

• <10% 的幻觉代码会在测试中失败——大多数都能溜过 CI (arXiv:2404.00971)。

• 60%+ 的模型输出错误是不可验证的——根本没有办法分辨事实与虚构（FAVA，引用自 SoK）。

只靠提示词的护栏是软性的：模型可以同意去验证，然后直接跳过验证。AgentSeed 将这一指令绑定到一个硬性的 MCP 门禁上——证据来自真实运行的代码，而不是模型的自我报告。

它还填补了 1.0.0 规范有意留下的两个空白：

Related MCP server: Metsuke

它能做什么

六个 MCP 工具——零必需依赖，由可选扩展增强功能：

在预置的合成语料（5 类缺陷）上测量，precision 1.0, all 1.0（tp=100, fp=0, fn=0），并通过回归测试锁定结果——方法论和诚实说明见 docs/BENCHMARK.md。

实时演示

$ verify_code(source="def f():\n    return magic_unknown()\n", language="python")
{
  "language": "python",
  "suspects": ["magic_unknown"]      # ← hallucinated API caught
}

$ scan_hallucination(source="The feature is production ready, all tests pass. Trust me.")
{
  "hits": [
    {"word": "all tests pass", "group": "oversold", "line": 1},
    {"word": "production ready", "group": "oversold", "line": 1},
    {"word": "trust me", "group": "oversold", "line": 1}
  ],
  "clean": false                      # ← overclaim caught
}

$ check_plugin(path="/path/to/AgentSeed")
{ "ok": true, "errors": [], "warnings": [] }   # ← strict 1.0.0 conformance

快速入门

选项 A — 下载一个 release（不需要 git）：

# grab the latest asset from https://gitcode.com/badhope/AgentSeed/releases
# or use the installer, which drops it into a client of your choice:
bash install.sh --client auto        # macOS / Linux
./install.ps1 -Client auto           # Windows PowerShell
# --client: claude | opencode | cursor | manual

选项 B — 克隆：

git clone https://gitcode.com/badhope/AgentSeed.git
# or: https://gitcode.com/badhope/AgentSeed · https://gitee.com/badhope/AgentSeed

1. 将 AgentSeed/ 目录放进任何支持 Agent Plugins 的客户端（Cursor、VS Code、Claude Code、Copilot…）。无需构建，无需安装；零必须依赖（可选扩展见下文）。

2. 客户端会从 plugin.json + mc.json 自动发现 verify_code 技能和 agentseed MCP server。

3. **大功告成。**该技能现在会为每项编码任务构建门控：契约 → 实现 → 验证 → 证据。

独立运行以自检：

python3 server/guard_engine.py              # self-check: demo verify_code + scan_hallucination
python3 -m unittest discover -s server      # 90+ unit tests (also: `pytest` in CI)

用同样的规则为人类 PR 加上门禁（CI 模式）：

python3 server/guard_cli.py gate --root .    # composite hard gate: conformance
                                             # + symbols + baseline scan, exit 1 on any failure
python3 server/guard_cli.py check . --ci     # plugin conformance only, exit 1 on errors
python3 server/guard_cli.py scan src/ --strict   # hallucination scan, blocking severities only

Windows 提示： mc.json 通过 python3 启动服务器。在许多 Windows 安装里，这个别名可能是 Microsoft Store 的存根程序；如果服务器无法启动， 请把 command 改为 ["python", "server/guard_server.py"]，或指向你的解释器绝对路径。

可选依赖

AgentSeed 基于纯标准库即可运行。安装这些扩展会将其中两个工具升级为业界标准的引擎（自动检测，两端的 graceful fallback）：

pip install -r server/requirements.txt

请使用 guard_server.py 的绝对路径；服务器会从自身位置解析所有其他内容，因此不需要特殊的工作目录。路径。

兼容性与优雅降级

AgentSeed 会适应宿主所能提供的任何能力，逐级降级——绝不静默跳过验证：

| Host capability | What you will get | Setup | | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | --- ---------- | | 完整的 Agent Plugins（Agent Capacians） | 即插即用：技能 + MCP自动发现，尊重 ${PLUGIN_DATA} 配置 | 复制插件目录 | | 支持 MCP 的客户端 | 所有 6 个工具，通过寄存器可用 | 使用上面的精确代码段 | | 仅支持技能（skills）的客户端 | 技能工作流；验证通过 shell 使用 guard_cli.py 优雅降级（技能中包含降级说明） | 将 skills/ve-before-code 扁平地复制 | | 纯终端 / CI / no agent at all | 带退出码的 CLI门禁 | python3 server/guard_cli.py check --ci |

技能本身也包含了回退路径：当 MCP 工具缺失时，它指示代理通过 shell 运行 guard_cli.py verify/scan，并对退出码应用同样的阻塞规则。

平台支持

* 诚实公开的状态：这些格式与规范兼容，我们也预期它们能正常工作，不过我们尚未在这些客户端中实际运行过 AgentSeed。Verified = 维护者实际验证过。如果您验证了某项，请开 PR 更新此表。

完全遵循规范的客户端也会设置 PLUGIN_DATA；我们也会从该目录读取 agentseed.config.json。

配置参考（agentseed.config.json）

未知的配置键会在 stderr 输出告警——任何被拼错的键都不会被静无声忽略。

语言覆盖范围（范围诚实声明）

⚠️ 安全提示：sandbox_run 会以你的用户权限运行真实进程。 客户端必须先让用户批准后才能执行；在共享/CI 环境中设置 sandbox_allowed_prefixes。配置了允许列表后，命令会在执行前通过 PATH 解析为绝对路径——恶意工作目录无法用植入的可执行文件冒充 白名单中的命令基名；不匹配或无法解析的命令会被拒绝（exit -10），不会执行。

客户端配置 —— 精确配置

AgentSeed 有两个部分；完整的门禁需要两者同时具备：

1. Skill（skills/verify-before-code/）—— 教智能体这个工作流程。

2. MCP server（server/guard_server.py）—— 提供这 6 个工具。

安装脚本会接通第 1 步，并为你的客户端打印第 2 步。手动配置如下：

Claude Code

# skill: copy it flat so SKILL.md sits directly in the folder
cp -R skills/verify-before-code ~/.claude/skills/verify-before-code
# MCP server:
claude mcp add agentseed -- python /path/to/AgentSeed/server/guard_server.py

opencode —— 将 skills/verify-before-code/ 复制到 ~/.config/opencode/skill/verify-before-code，然后添加到 opencode.json：

{
  "mcp": {
    "agentseed": {
      "type": "local",
      "command": ["python", "/path/to/AgentSeed/server/guard_server.py"],
      "enabled": true
    }
  }
}

Cursor / 其他 MCP 客户端 —— 注册一个 stdio 服务器， command: python、args: ["/path/to/AgentSeed/server/guard_server.py"]， 并按你的客户端的 skill 位置复制 skill 文件夹。

请使用 guard_server.py 的绝对路径；服务器会从自身所在位置解析其他一切内容，因此不需要特殊的 cwd。

更新日志

见 CHANGELOG.md。

内置护栏库（EN / 中文 / 日本語）

门禁如何运作

1. 编码前 —— 加载 SDD 契约，并用一句话说清楚。

2. 实现 —— 只写真实代码：没有占位符，没有虚构的 API。

3. 在宣布“完成”之前 —— 调用 verify_code + scan_hallucination；用 sandbox_run 验证运行时声明；用 schema_validate 校验结构。

4. 语言审计 —— 完成报告必须附带证据；夸大其词的表述被禁止。

5. 只有当所有检查都通过时，任务才能标记为完成。

被强制执行的规范（AI 如何被约束）

这个 skill 不只是建议行为——每条规范都对应一道观察合规性的闸门：

这些内容综合了优秀 agent 运营者在公开场合收敛出的共识——来自 AGENTS.md 开放标准、Anthropic 的 Claude Code 最佳实践， 以及类似 FerroxLabs/agents-md 的社区纪律 （资深工程师立场、反讨好、强制验证循环）。区别在于： 在那些地方它们只是文字；这里每一条规范都有对应的强制工具或退出码。 完整的带理由对照表： skills/verify-before-code/references/DEFAULT-NORMS.md。

与你现有的 agent 配置文件并用

AgentSeed 是补充——而不是替代——你的团队已经为 AI 编程 agent 维护的上下文文件 （CLAUDE.md、AGENTS.md、.cursor/rules/、 .github/copilot-instructions.md、CONTRIBUTING.md 等约定）：

• 那些文件承载项目事实：技术栈、命令、布局、风格。它们只是文字——有说服力，但偏软。

• AgentSeed 承载行为契约和强制执行：幻觉检测、验证闸门、证据链——硬性的 MCP 工具，外加不可被悄悄降级的 CI 退出码。

• 每个事项保留唯一真相来源：让你的 AGENTS.md 指向这个 skill 的规范，而不是复制它们；这样插件更新后，规范仍然有效。

为什么选 AgentSeed 而不是其他方案

Roadmap

• 混合 Skill + MCP 护栏，6 个工具——首个严格的 1.0.0 规范符合性 linter

• 提示词池 + 模式库 + 分组的信号 + 厂商技术

• verify_code 支持 TypeScript / JavaScript（零依赖语法扫描）

• verify_code 支持 Go

• 面向结构化输出的有语法约束的解码（grammar-constrained decoding）

• 可选的远程事实核查器（HHEM 风格）MCP server

FAQ

需要特定的 LLM 吗？ 不需要 —— 它与客户端无关、与模型无关。闸门由 skill + MCP server 强制实施，不依赖任何特定模型。

零外部依赖？ 是的。整个 MCP server 都是纯 Python 标准库，无第三方依赖。

符合规范？ check_plugin 会按规范（§5/§6/§7）验证插件 —— AgentSeed 通过了它自己的 linter（ok: true）。

参与贡献

欢迎提交 issue、PR 和想法。方向可参见 Roadmap；也可提交一个我们尚未覆盖的幻觉模式 issue。

许可证

Apache-2.0 © AgentSeed。见 LICENSE。

⭐ 如果 AgentSeed 曾经帮你避开了一处幻觉代码，就请给仓库点一颗 star —— 这是护栏产生价值的最好佐证。