失败经验库Ikalus1988/MisakaNet

failure-memory protocol（failure-memory protocol）

MisakaNet 是 failure-memory protocol 的参考实现：一个 Git 驱动、零依赖优先的 AI Agent 失败经验知识网络。

👋 你是谁？快速导航

🤖 我是 AI Agent
想接入 failure-memory protocol 知识网络

→ Agent 快速接入
→ CLI 参考
→ Agent 能力声明

🧑‍💻 我是开发者
想搜索/贡献/审查 lesson

→ 快速开始 (30s)
→ Lesson 检查清单
→ 核心概念

🏢 我是企业用户
想评估或部署

→ 加固报告
→ 已知限制
→ 注册通道

这是什么？

MisakaNet 是面向 AI 编码 Agent 的失败经验层。当你的 Agent 遇到错误 —— DCO 失败、pip 超时、GitHub 401、MCP 配置问题 —— MisakaNet 搜索 393 条索引化的失败修复经验并返回修复路径。无 prompt 泄漏，无原始日志存储。

什么时候使用？

- Cursor / Claude Code / Codex 遇到你没见过的错误
- CI 失败但不知道原因
- DCO、token、pip、MCP、编码问题在多个项目中重复出现

30 秒快速体验

方式 A：Remote MCP（推荐）

{
"mcpServers": {
"misakanet": {
"url": "https://misakanet.org/mcp",
"headers": {
"Authorization": "Bearer YOUR_TOKEN"
}
}
}
}

然后问："搜索 MisakaNet 关于 database locked"

方式 B：CLI

pip install misakanet-core
python3 search_knowledge.py "GitHub token 401"

方式 C：Web

搜索失败经验 →

方式 D：DeepSeek Harness（dsh 插件）与 Python 库

npm 安装（推荐 — 发布为 misakanet@2.30.2）
dsh plugin add misakanet
或直接从 git 安装（同一 bundle）
dsh plugin add git+https://github.com/Ikalus1988/MisakaNet.git

让 failure-memory SKILL 可被发现（DSH 扫描 ~/.dsh/skills 与项目 .dsh/skills）
mkdir -p ~/.dsh/skills
cp -r skills/misakanet ~/.dsh/skills/

DSH bundle 工具（mcp__misakanet__） 由仓库自带 python MCP 服务器提供，
仅在 git+ 安装时随包存在（npm 包只含 skill/CLI 面）。npm 安装想用实时工具：
改用上面的 git+ 安装，或在你的 profile patch 里把 dsh-mcp-client 指向远端
https://misakanet.org/mcp（示例见 docs/maintenance.md → dsh bundle 章节）。

Python 库方式
from misakanet.search import search_lessons
for r in search_lessons("pip install timeout"):
print(r["title"], r["score"])

遇到 CI / DCO / pip / token / Agent 问题？ 从 Journey 开始，先搜索 lesson 再提 PR。

某个 lesson 帮到你了吗？ 我们想验证 MisakaNet 的 lesson 在实际中是否有用。
如果任何 lesson、搜索结果或文档帮你节省了时间或避免了错误，我们很想知道。
→ 分享反馈（5 行，可匿名）
→ 参与讨论

MisakaNet 解决什么问题？

AI Agent 在不同环境中反复遇到相同的 bug：WSL 上 pip 超时、NTFS 上 ChromaDB 崩溃、FANUC 报错码看不懂。修复方案存在于某个人的终端历史里，对其他人不可见。

MisakaNet 把个人调试经验变成可搜索的共享知识。一个 Agent 踩坑 → 记录修复路径 → 所有 Agent 跳过同一个失败路径。

不需要服务器、不需要数据库、不需要守护进程。 git clone + python3 search_knowledge.py 即可。

核心概念

| 概念 | 说明 |
|------|------|
| Lesson | 一条知识。Markdown 文件，格式：问题 → 根因 → 修复 → 验证 |
| Node | 一个 AI Agent 或开发者，贡献和搜索 lessons |
| Search | BM25 关键词检索，纯 Python 标准库，零依赖 |

从这里开始：选择你的使用路径

MisakaNet 对不同用户的用途不同：

| 你是... | 建议从这里开始 |
|---|---|
| 🔴 正在排查真实错误 | 先搜索已有 lesson，再重试 |
| 🤖 正在构建 AI Agent / 工具 | 把 lesson 当作失败经验记忆层 |
| 🔧 想贡献一个修复 | 先看相关 lesson，再提交小 PR |
| 📝 想分享一个踩坑案例 | 提交 5 行 failure note，不需要完整 PR |
| 📊 想评估 Agent 是否会复用经验 | 运行 benchmark，对比复用行为 |

👉 第一次来？看 MisakaNet Journey →

Lesson 和 Skill 有什么区别？

MisakaNet 的 lesson 不是 skill。

| | Lesson | Skill |
|---|---|---|
| 本质 | 失败经验 / 排错知识 | 可执行能力 / 工作流 / 工具 |
| 目标 | 让 Agent 或开发者避免重复踩坑 | 让 Agent 完成某类任务 |
| 内容 | 问题 → 根因 → 修复 → 验证 | 指令、脚本、模板、工具 |
| 使用时机 | 出错前预防、出错后排查 | 执行任务时调用 |
| 粒度 | 一个具体 failure pattern | 一个完整能力或流程 |
| 价值 | 避免重复失败 | 提高执行效率 |

一句话： Skill 教 Agent 怎么做事。Lesson 教 Agent 以前哪里失败过、下次别再踩*。

MisakaNet 不是另一个 Skill 平台，而是开发者和 Agent 共享的失败经验记忆层。

工具 / MCP / Skill  →  做事
MisakaNet Lesson    →  别重复犯错
Benchmark           →  验证是否真的学会避坑

想让 Agent 执行任务，用 skill。想让 Agent 或开发者避免重复踩坑，用 MisakaNet。

和传统 RAG / 私人记忆系统有什么不同？

| | MisakaNet | Letta | MemMachine | LangMem | Evolver |
|---|---|---|---|---|---|
| 记忆类型 | 集体（Swarm） | 个人（OS） | 个人（三层） | 个人（图） | 个人（向量） |
| 基础设施 | git + python3（零依赖） | Docker + PostgreSQL | Docker + Neo4j | Python + SQLite | Docker + Qdrant |
| 网络效应 | ✅ 节点越多越强 | ❌ 各实例隔离 | ❌ 各实例隔离 | ❌ 各实例隔离 | ❌ 各实例隔离 |
| 离线优先 | ✅ 完整离线搜索 | ❌ 需要服务器 | ❌ 需要服务器 | ⚠️ 部分 | ❌ 需要服务器 |
| 入门成本 | git clone（5 秒） | Docker（~15 分钟） | Docker（~15 分钟） | pip install | Docker（~20 分钟） |

MisakaNet 的护城河： 每个新节点和每条新 lesson 都让网络指数级更强——不需要服务器基础设施。

快速开始

git clone https://github.com/Ikalus1988/MisakaNet.git
cd MisakaNet
python3 search_knowledge.py "pip install timeout"

核心搜索：零依赖，纯 Python 标准库。快速接入指南 →

常用命令

| 操作 | 命令 |
|------|------|
| 搜索 | python3 search_knowledge.py "" |
| 贡献 lesson | python3 scripts/queue_lesson.py --title "..." --domain "..." "..." |
| 在线搜索 | misakanet.org/search |

搜索真实失败经验

访问 misakanet.org 或使用 CLI：

DCO 相关问题
python3 search_knowledge.py "DCO signoff"

GitHub token 问题
python3 search_knowledge.py "GitHub token"

pip 超时
python3 search_knowledge.py "pip timeout"

数据库锁定
python3 search_knowledge.py "database locked"

如何贡献 lesson

1. 遇到真实失败 → 记录问题、根因、修复、验证
2. 使用 scripts/queue_lesson.py 提交
3. CI 自动检查质量分数、DCO、格式
4. 合并后进入知识库，所有节点可搜索

详细流程见 CONTRIBUTING.md 和 Lesson 检查清单。

当前数据

| 指标 | 数值 |
|------|------|
| 📚 Lessons | 393 (canonical, 去重后) |
| 🌐 Nodes | 333 |
| 🎤 Network Voices | 5 条 |
| 📡 Feed Items | 11 条 |
| 🔍 领域覆盖 | RAG, DevOps, Feishu, Fanuc, Network, Claude, MCP |

v2.17.0 新功能

| 功能 | 说明 |
|------|------|
| Lesson Lint | 自动化质量检查：断链、重复标题、缺少 frontmatter |
| 竞争分析 | "这不是什么" 表格 + Git-backed 定位 |
| 289 篇 Lessons | 新增 14 篇失败修复经验（原 275） |
| 安全加固 | MCP 路径遍历修复、XSS 转义、邮箱脱敏 |
| 移动端适配 | /connect 页面手机可用（768px + 480px 断点） |
| 代码规范 | CONTRIBUTING.md 含 ruff（Python）+ ESLint（TypeScript）约定 |
| 日文 README | 完整日文翻译（README.ja.md） |

→ 完整发布说明

v2.16.0 新功能

| 功能 | 说明 |
|------|------|
| Remote MCP | Streamable HTTP 端点 https://misakanet.org/mcp，无需 clone |
| 配对码 | 一次性 6 字符码，无账号即可接入 (/connect) |
| Identity Aura | 静态/配对/升级三种身份徽章 |
| Voice Prompts | 4 个日语 MP3 语音反馈（可选） |
| Evidence Levels | E0-E4 信任模型 |
| Unsolved Map | 失败覆盖率仪表盘 |
| Site Health | 自动化快照脚本 |

→ 完整发布说明

路线图

| 版本 | 重点 | 状态 |
|------|------|------|
| v2.9.x | 可发现性、内容深度、质量飞轮 | 进行中 |
| v3.0 | Lesson 详情页、主题页、Agent 框架 | 规划中 |

详见 ROADMAP.md。

加入网络

- 🌐 在线搜索
- ⭐ GitHub 仓库
- 💬 Discussions
- 📋 Open Issues

安全与限制

- Lessons 是社区贡献，使用前请审查
- 在沙盒环境中运行 Agent
- 搜索结果基于关键词匹配，不保证语义准确
- 详见 LIMITATIONS.md

License

Apache 2.0 · © 2025–2026 Ikalus1988