Ikalus1988/MisakaNet · 上手攻略

  • 仓库：Ikalus1988/MisakaNet
  • 链接：https://github.com/Ikalus1988/MisakaNet
  • 分类：agent / skill(失败记忆库)
  • 作者：spark
  • 更新：2026-08-20

是什么

MisakaNet 是一个面向 AI 编程 Agent 的"失败记忆"知识库。它本身不是 Agent 框架、不是向量数据库、不是云服务,它的定位非常窄:让 Agent 在跑代码撞墙时,能搜到一条"别人已经踩过、且给出可复制修复路径"的经验。

仓库以纯 Git + Markdown + Python 标准库的形式存在(misakanet-core 是独立 PyPI 包,装好后即可调用)。当前 lessons/core/ + lessons/contrib/ 累计收录 290+ 条 失败-修复对(README 标记为 290,quickstart 文档中提到 304,数字略有差异,实际以 git clone 后 lessons/ 目录计数为准),覆盖 DCO 签名、pip 安装超时、token 过期、CI 失败、SQLite 锁、编码乱码、MCP 配置、CodeQL 误报、GitHub 401 等高频 Agent 卡点。

配套还提供: - Remote MCP 端点 https://misakanet.org/mcp——不用 git clone,直接通过 MCP 协议查询; - misakanet_submit_intake 工具——允许无 GitHub 账号的 Agent 通过 JSON-RPC 提交"我撞墙了,你们补一条",Cloudflare Worker 收到后自动开 GitHub Issue 给维护者审核; - DeepSeekHarness 适配器 scripts/mcp_deepseek_adapter.py——把 lesson 暴露成 deepseek.recovery.* 命名空间的 MCP 工具。

解决什么问题

LLM/Agent 在工程化落地的最大成本不是"不会写代码",而是"反复踩同一条坑"。常见表现:

  1. Agent 在沙箱里 pip install 撞 SSL/timeout 错误,重试 3 次后放弃;
  2. CI 流水线 DCO sign-off 失败、CodeQL 误报、GitHub PAT 过期,Agent 反复写"请人工帮我跑这条命令"却没人;
  3. 团队内部知识藏在 Notion/Confluence/Slack,Agent 抓不到,只能从 0 试错;
  4. 一份"失败记忆"在多个 Agent 之间无法共享——A 修过的 bug,B 下周又会踩。

MisakaNet 的回答是:把"可验证的失败-修复对"作为一等公民放进 Git 仓库,用 BM25 关键词检索,而不是塞进向量数据库。Git 当存储、Markdown 当格式、pip install misakanet-core 当引擎、Zero 外部依赖(只走 Python stdlib)。

快速安装

方式 A:本地 Python(推荐)

git clone https://github.com/Ikalus1988/MisakaNet.git && cd MisakaNet
pip install misakanet-core
python3 scripts/misakanet_cli.py smoke   # 自检:确认 CLI 可用

⚠️ 坑:包名是 misakanet-core(连字符),Python import 时是 misakanet_core(下划线)。装成 misakanet 不会报成功但也找不到模块。

方式 B:Docker

docker pull ghcr.io/ikalus1988/misakanet:latest
docker run -i ghcr.io/ikalus1988/misakanet:latest search_knowledge.py "database is locked"

适合 CI smoke、Claude Desktop MCP 配置时不想污染本地 Python 环境。

方式 C:Remote MCP(完全无 clone)

直接把 https://misakanet.org/mcp 加进 MCP client 配置,无需 Bearer token,无需 GitHub 账号。

核心用法

1. 命令行搜索一条 lesson

python3 search_knowledge.py "database is locked"

输出示例:

┌─ Results for: database is locked ─────────────────────────────┐
│ #  Score  Domain        Title                                  │
│ 1  0.89   agent-net     hermes-state-database-lock-cleanup     │
│ 2  0.74   infra         sqlite-wal-mode-crash-recovery         │
│ 3  0.61   contrib       agent-state-database-lock-cleanup      │
└───────────────────────────────────────────────────────────────┘

常用 flag:

Flag 作用
--top=5 限制返回条数
--domain=infra 按域过滤(infra / agent-net / contrib)
--lang=en 只返回英文
--titles 一行一条标题(适合灌进 prompt)

2. 提交一条新 lesson(无 GitHub 账号也能提交)

走 Remote MCP intake:

curl -sS https://misakanet.org/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"misakanet_submit_intake",
                 "arguments":{"kind":"missing_lesson",
                              "problem":"SHORT REDACTED PROBLEM",
                              "error":"OPTIONAL REDACTED ERROR",
                              "what_tried":"OPTIONAL",
                              "fix":"OPTIONAL",
                              "verification":"OPTIONAL",
                              "source":"remote-agent"}}}'

Cloudflare Worker 收到后会创建一个 GitHub Issue 给维护者 review,通过则合并到 lessons/contrib/。

3. 跑 MCP Server 给 Agent 用

python3 scripts/mcp_server.py
# 然后在 Claude Desktop / Cline / Continue 里加 MCP 配置指向本进程
# 之后问: "Search MisakaNet for pip install timeout"

4. 走 PR 自动化(需要本地 fork)

python3 scripts/queue_lesson.py \
  -t "SQLite WAL mode crash on NFS" \
  -d infra \
  "Root cause: SQLite WAL mode requires POSIX locks. NFS does not support them.
   Fix: switch to DELETE journal mode: PRAGMA journal_mode=delete.
   Verification: run 100 concurrent writes on NFS mount, no crash."

会自动生成 lessons/contrib/<slug>.md 并开 PR。

典型适用场景

  1. CI/CD Agent / DevOps Agent:DCO、CodeQL、token 轮换、OIDC trust 这类"Agent 自己搞不定、人类也不愿意写文档"的高频坑。
  2. 多 Agent 团队内部共享失败库:把团队私有的失败经验 fork 一份,改 lessons/core/ 里几条标题,内网用同样 CLI 搜——不需要造轮子。
  3. 长任务 Agent 的"反思/检索"模块:取代部分"把整个 traceback 塞进 prompt 让 LLM 反思"的低效循环。
  4. 教学 / 培训新人:新人 80% 的报错其实是历史 lesson 一条,搜 1 秒 > 等 review 半小时。
  5. DeepSeek Harness 等 Agent harness 的 failure-recovery 层:scripts/mcp_deepseek_adapter.py 已经演示了接入范式。

坑与注意

⚠️ lesson 数字漂移:README 主页写 "290 lessons",但 quickstart 文档提到 304,release notes 也出现 289→304 这种中途变更。以 git clone 后实际 lessons/ 目录计数为准,不要直接引用首页数字。

⚠️ BM25 ≠ 语义搜索:必须用关键词或近义词。"connection reset" 搜不到 "peer closed"——这是设计取舍(零依赖),需要时用 --lang=en + 多个 query 重试,而不是指望语义泛化。

⚠️ Remote MCP 是 Cloudflare Worker:Worker Auth Bypass 让 intake 工具跳过 Bearer auth,但维护者必须人工 review Issue 才会变成 merged lesson。不要把 intake 当成"提交即生效"的接口,它只是 0 摩擦的入口。

⚠️ Python 版本:文档要求 Python 3.x(没写最低版本,实测 3.9+ 可用,Python 3.11/3.12 推荐)。Windows 用户第一次 git pull 会被 vim 卡住,需要先:

git config --global pull.rebase true
git config --global core.editor "code --wait"

⚠️ lesson 质量差异:Contrib 区是社区提交,有 E0-E4 信任分级。生产场景优先看 lessons/core/(维护者收录)再回退到 lessons/contrib/。

⚠️ 不存原始日志/不泄漏 prompt:仓库定位写得很明白——"no prompt leaking, no raw logs stored"。如果你的 Agent 需要把 traceback 全文丢进来诊断,这是错配;如果你的需求只是"我知道这条报错,查一下怎么修",完全合适。

与同类对比

项目 形态 检索方式 依赖 适配 Agent
MisakaNet(本文) Git + Markdown + Python stdlib BM25 关键词 0 外部依赖 Remote MCP / 本地 CLI
LangChain/LlamaIndex Memory 框架内置模块 向量检索 LLM + 向量库 框架耦合
RAG over Notion/Confluence 自建向量库 语义检索 OpenAI/Anthropic + 向量库 需要胶水代码
SWE-bench Verified 等 benchmark 学术数据集 不检索 n/a 不直接对接 Agent
公司内部 Confluence / Notion 文档系统 全文 / 向量 视厂商 需要登录 + 抓取

MisakaNet 的核心差异是"为 Agent 设计、零运营成本":不签 SaaS、不跑向量库、不绑框架,只要能 clone Git 就能用。对小团队和个人开发者是明显优势,对已经有 ELN/Confluence 治理的大厂可能太轻。

一句话推荐结论

个人 / 小团队的 AI 编程 Agent,先 git clone 一份挂上 MCP,撞墙时搜一下,大概率能省 30 分钟一次的人类打断。 大厂已有成熟知识库可以略过。

进阶:MisakaNet 的设计哲学与权衡

读源码 + 用了一段时间后,这个项目有几个值得借鉴的设计决策,适合做 Agent 工具链时复用:

1. 用 Git 当数据库

传统失败记忆系统会塞进 PostgreSQL / SQLite / 向量库,运维成本高。MisakaNet 选择纯 Git + Markdown 文件,理由:

  • 人类可以直接 PR(失败经验天然是叙事性文本,PR review 比数据库表单更自然)。
  • 时间旅行免费(git log -p 看一条 lesson 是怎么从 E0 升级到 E4 的)。
  • Fork = 私有化部署成本为零,团队 / 公司可以 fork 一份后改 lessons/core/,完全本地化。
  • 与传统"DB + 向量库"相比,冷启动 0 成本,没有 schema migration、没有连接池、没有版本兼容。

代价是:不能跨仓库联合查询;lesson 数量超过 10k 后 BM25 性能下降;不支持在线协作编辑(只能走 Git PR)。

2. BM25 关键词 vs 向量检索

README 显式说"Not a vector database",这是核心取舍:

维度 BM25(本项目) 向量检索
零依赖 ✅ Python stdlib ❌ 需要 faiss/chroma/qdrant
精确短语匹配 ✅ 强 ⚠️ 弱(高维嵌入会被语义糊化)
拼写错误容忍 ⚠️ 弱 ✅ 强
跨语言检索 ⚠️ 需手动 --lang ✅ 嵌入层自然跨语
部署 git clone 即可 需要服务进程

实战建议:先 BM25 搜,搜不到再用向量补充。Agent 工作流的 80% 时间是"我知道大致错误关键词"——BM25 比向量更直接。

3. 0 摩擦 intake → 维护者审核 → 合并

最巧妙的是 intake 设计:

Agent 撞墙 → submit_intake(无 auth) → Cloudflare Worker → GitHub Issue
                                                      ↓
                                                 维护者人工 review
                                                      ↓
                                              合并到 lessons/contrib/

这条链路同时解决了两个问题: - Agent 没有 GitHub 凭证,0 摩擦提交。 - 维护者仍然把控质量门,避免垃圾灌入。

4. E0-E4 信任分级

lessons/ 目录下的每条 lesson 都有 status 字段(0-4 级),表示证据强度:

  • E0:仅口头经验
  • E1:可复现的最小样例
  • E2:有修复命令且验证步骤
  • E3:经过 CI / issue 多方确认
  • E4:被官方收录进 lessons/core/

Agent 在引用 lesson 时应当区分等级——生产场景只信任 E3+。

5. 与 Agent harness 的接入范式

scripts/mcp_deepseek_adapter.py 暴露的不是 lesson 本身,而是 deepseek.recovery.* 命名空间的工具:

deepseek.recovery.search    // 搜 lesson
deepseek.recovery.apply     // 应用某条修复
deepseek.recovery.feedback  // 提交结果反馈

这套"领域工具命名空间"模式值得复用:不是把通用 search 暴露给所有 Agent,而是把"对 harness 有用的能力"包装成具体动词。

决策清单:什么时候用 / 不用

✅ 用: - Agent 撞墙频率高(每周 ≥5 次同类问题) - 团队规模 1-20 人,没有内部 KB 平台 - 想让 Agent "记住"上一次的修复 - 个人 / 开源项目,运维成本敏感

❌ 不用: - 内部已有 Confluence + RAG pipeline - 需要语义级检索(BM25 不够用) - 需要支持跨语种 lesson - 私有 lesson 数量 > 10k(Git + BM25 性能临界)

主要来源 - 仓库 README(主页):https://github.com/Ikalus1988/MisakaNet - 5-min quickstart 文档:https://raw.githubusercontent.com/Ikalus1988/MisakaNet/main/docs/quickstart.md - PyPI 包:https://pypi.org/project/misakanet-core/ - Remote MCP 端点:https://misakanet.org/mcp - MCP 注册名:io.github.Ikalus1988/misakanet - 最新 release:v2.17.1(主页所标)