agent-seed-brain 0.1.0

把任意领域的知识，编译成智能体可无偏检索、可增量演进、可自我验证的「种子大脑」。

zero dependencies · deterministic · explainable · verifiable

它到底提升了什么

大多数 agent 在"选方案"这一步，靠的是预训练语料里最高频的那几个词。 这就是为什么你让它做科技感海报，它永远给你赛博霓虹；让它做数值计算，它永远给你梯度下降。

seedbrain 不提升模型的推理能力。它做的是另一件事：

把「选什么」从模型权重里搬出来，搬进一份可检索、可审计、可验证的数据里。

为什么收益与 harness、模型规模无关

这条因果链是项目的存在理由：

「选得对不对」   ← 由索引质量 + 匹配算法决定   ← 与模型无关
「选完之后怎么做」← 由模型推理能力决定         ← 与模型有关

seedbrain 只负责前半段。所以它在 任何 harness（Claude Code / Codex / pi / 自建循环）、任何模型（强或弱） 上的效果是一致的： 弱模型从"瞎猜"变成"查到同样的候选集"，强模型从"选得还行"变成"选得可解释、可复现"。

安装

① 从源码（当前可用，无需等 PyPI）

git clone https://github.com/hhx465453939/agent-seed-brain
cd agent-seed-brain
pip install -e .
seedbrain --version

② 从 PyPI（v0.1.0 发布后）

pip install agent-seed-brain

发布由 .github/workflows/release.yml 完成（Trusted Publishing / OIDC，不需要 API token）。 维护者先在 PyPI 配好 trusted publisher，再手动跑一次该 workflow；推 v* tag 只做验证与构建， 不会自动发布。

③ 零安装试用

git clone https://github.com/hhx465453939/agent-seed-brain
cd agent-seed-brain
PYTHONPATH=src python examples/minimal.py

部署到 agent harness

seedbrain 是库 + CLI，不绑定任何 harness。两种接法：

A. 当作命令行工具（最常见）

在 agent 的规则文件里加一句「选方案前先跑 seedbrain match」，它就会在执行前查库：

seedbrain match "科技感长图，深色底霓虹" \
  --profile profiles/taste.json \
  --root ~/agent-taste-seed-system \
  --k 8

B. 当作库嵌入自建循环

from seedbrain import SeedBrain

brain = SeedBrain.load("profiles/taste.json", root="~/agent-taste-seed-system")
for m in brain.match(task, k=8):
    ...

接上已有的知识库（SDK 与内容分离）

seedbrain build  --profile profiles/taste.json --root ~/agent-taste-seed-system
seedbrain verify --profile profiles/taste.json --root ~/agent-taste-seed-system

--root 指向内容所在的仓库。SDK 仓库里只有解析规则，不含任何种子内容——这是许可隔离的前提。

30 秒

pip install agent-seed-brain

from seedbrain import SeedBrain

brain = SeedBrain.load("profiles/example.json")   # 仓库内自带最小示例域
brain.build()

for m in brain.match("降维压缩，矩阵分解选型", k=5):
    print(f"{m.total:6.1f}  {m.seed.id:<24} {m.hits[:2]}")
#    6.5  tl-矩阵分解               (('矩阵', 1.8), ('阵分', 1.8))
#    4.1  tl-奇异值截断             (('降维', 1.8), ('压缩', 1.8))

想先看它体检？

seedbrain verify --profile profiles/example.json

它治的三个真实病灶

四个机制（都不靠随机）

刻意不用随机数：合适性由 IDF 决定（确定、可解释、可复现）；多样性由状态记忆产生——同一任务隔几天再跑，会拿到不同的同等合适候选，而不是随机的不合适候选。

验证：它自己证明自己

seedbrain verify --profile profiles/example.json --evidence docs/EVIDENCE.md

[PASS] T1a ID 唯一                  重复 0 个
[PASS] T2a 名字自召回@8              100.0%（漏 0）
[PASS] T3a 命中基尼系数               0.154
[PASS] T4a IDF 单调性                df=1「假设」2.48 vs df=19「信号」0.74
[PASS] T5  6 次连选的 top1 多样性      4 个不同
[PASS] T6a 层饥饿（有货却没给位）        0 次
[PASS] T9  top1 落在旧货架之外         50.0%
[PASS] T10 增量等价                 22/22 逐位一致
[PASS] T13 同义别名被识别             命中 cd-sampling（1.00）
...
结果：28/28 通过

配套 91 个单元/集成测试（标准库 unittest，不装任何东西就能跑）：

PYTHONPATH=src python -m unittest discover -s tests

断言是真的会失败的。本项目在开发期就被自己的断言抓出过两个真 bug： 「配额只有上限没有下限」（弱层有货却拿不到位）、「novelty 下限乘完次数惩罚掉到 0.11」（复现失效）。

生产实例：美学大脑

agent-taste-seed-system 用这套引擎管理 24 章 250+ 艺术家的风格种子库（352 粒章档 + 12 张代码基因卡 + 10 份情绪档）。

它解决的问题是：不同视觉任务老是收敛到赛博霓虹 / 瑞士平面那几粒。

接入后的实测：

SDK 与内容严格分离：本仓库只有引擎与解析规则，一根种子都不打包。 美学大脑的语料在它自己的仓库里，遵循 CC BY-NC-SA 4.0；本仓库同样采用 CC BY-NC-SA 4.0，但两者是各自独立的版权客体。

接入你自己的领域

一个领域 = 一份 JSON。不写一行 Python。

{
  "schema_version": 1,
  "name": "my-domain",
  "sources": [
    {
      "kind": "table",                       // 单行速查总库
      "path": "docs/methods.md",
      "layer": "method",
      "group_re": "^##\\s+(?P<group>.*)$",
      "entry_re": "^-\\s*\\*\\*(?P<name>[^*]+?)\\*\\*\\s*·\\s*(?P<tag>[^—]+?)\\s*——\\s*(?P<desc>.+)$"
    },
    {
      "kind": "card",                        // 一张卡一粒种子
      "dir": "docs/cards",
      "layer": "card",
      "title_re": "^#\\s+(?P<title>.+)$",
      "field_re": "^>\\s*\\*\\*(?P<key>[^*]+?)\\*\\*\\s*[：:]\\s*(?P<val>.*)$"
    }
  ],
  "layers": {
    "method": { "prefix": "m",  "quota": 0.6 },
    "card":   { "prefix": "cd", "quota": 0.4 }
  },
  "paths": {
    "index_jsonl": ".seedbrain/index.jsonl",
    "index_md":    ".seedbrain/SEED-INDEX.md",
    "additions":   ".seedbrain/additions.jsonl",
    "state":       ".seedbrain/state.json"
  }
}

seedbrain build  --profile my-domain.json
seedbrain match  "你的任务描述" --profile my-domain.json
seedbrain verify --profile my-domain.json

细节见 docs/METHODOLOGY.md。

运行时新增（不改源文件）

seedbrain add \
  --name "共形 PID 控制" \
  --layer method \
  --signals "在线控制,分布漂移,覆盖率保证" \
  --ref docs/methods.md

写入增量池 → 自动重建 → 立即可检索。三道护栏：ref 必须真实存在（防静默断链）、同层查重（包含度 ≥0.75）、ID 撞车只加后缀不改写。

许可

这是 source-available，不是 OSI 认可的开源软件（NC / SA 条款与开源定义不兼容）。 完整条款见 LICENSE，权利保留与来源说明见 NOTICE。

商业使用

本项目采用非商业许可。以下情形需要单独的商业授权：

• 集成进付费产品、SaaS、或企业内部生产系统
• 用它提供咨询、外包、培训等收费服务
• 在闭源产品中分发或嵌入

授权方式：开一个标题为 commercial license 的 issue 即可开始沟通。 贡献者已授予维护者再许可权（见 CONTRIBUTING.md）， 因此单份商业许可可以覆盖整个代码库。

非商业用途（学习、研究、个人项目、非营利项目）无需授权，直接使用即可。

路线图

• v0.1.0 — 等距平铺 / IDF 匹配 / 跨层配额 / 状态衰减 / 增量池 / 28 项断言 / CLI + 库 API
• v0.2.0 — profile 继承（领域公共配置复用）
• v0.3.0 — 可选向量后端（保持零依赖默认路径不变）
• v1.0.0 — API 冻结 + 迁移指南

_{Built with aesthetic-brain · CC BY-NC-SA 4.0 · source-available · zero runtime dependencies}