MisakaNet

413Star157Fork34Issue27Watching

为 DSH 接入一个 Git 驱动的失败经验记忆网络,Agent 报错时可检索 290+ 条社区已验证的修复路径,按 MCP 协议暴露为 `deepseek.recovery.*` 工具。

语言
Python
License
Apache-2.0
分支
main
ai-agentai-infraclaudedeepseek-harnessdevopsdsh-pluginfailure-analysisfailure-memory

安装

$ dsh plugin --profile web add github:Ikalus1988/MisakaNet

在终端中运行以上命令,通过 dsh CLI 安装此插件。可在右上角切换 Profile。 第一次用 dsh?看这篇新手教程

一句话定位

MisakaNet 给 DSH 接入了一个 Git 驱动的"失败经验记忆网络":当 Agent 撞到错误时,可以去检索 290+ 条来自真实调试会话的 markdown 教训(lessons),拿到"问题-根因-修复-验证"四段式答案,再决定要不要执行。

核心能力

  • 通过 Cordis patch 在 DSH web profile 中注册名为 misakanet 的 stdio MCP 客户端,由适配器进程承载
  • 暴露 6 个 deepseek.recovery.* 工具:search、get_lesson、submit_feedback、status、doctor、smoke,覆盖"搜教训、读教训、回报结果、健康检查"
  • 内置三层搜索引擎降级链:SAG-Lite FTS → BM25 倒排索引 → lessons.json 关键词兜底,单层故障不会让搜索完全不可用
  • lessons 是仓库内 markdown 文件,由 Git 版本控制,可审计、可贡献(需 DCO 签名)
  • 内置 doctor/smoke 校验:检查 lessons 数据文件、sag.db 索引、搜索引擎可用性,输出 JSON 给上层 harness 消费
  • 支持远程 MCP 模式:https://misakanet.org/mcp 提供无账号 intake,Agent 找不到合适 lesson 时可提交脱敏报告

技术实现

  • 语言: Python(核心引擎 + MCP 适配器),TypeScript(仅出现在 wrangler/Cloudflare Worker 部署脚本,本插件运行时不涉及)
  • 关键依赖: misakanet-core(PyPI 上的核心搜索包,pyproject.toml#dependencies)、Python 标准库(BM25 无需第三方)、pip install misakanet-core 可选安装 sentence-transformers / aiohttp / chromadb(语义搜索或 hub 联邦扩展)
  • 架构模式: 插件通过 dsh.bundle.patch 指向 cordis.patch.yml,DSH 启动时把 misakanet 节点注入;适配器 scripts/mcp_deepseek_adapter.py 是一个 stdio MCP 桥接进程,所有逻辑委托给 scripts/mcp_server.py(命名层而非逻辑层),搜索请求落到 misakanet/search/engine.py 的 BM25 实现
  • 入口文件: scripts/mcp_deepseek_adapter.py(DSH 实际调用入口)、scripts/mcp_server.py(核心 MCP server,4 个基础工具)、search_knowledge.py(CLI 检索入口)

适用场景

当你在 DSH 里跑一个长任务 Agent,撞上 DCO 报错、pip 装包超时、MCP 服务起不来、WSL 下划线被吞之类的"已知的坑"时,希望 Agent 在重试或问人之前先翻一遍社区经验库、命中现成修复路径,而不是每次都从零调试——这个插件就是为这种"复发性失败"准备的。它是 DSH 之上的一个旁路恢复层,不替代官方 AI 能力,只在 Agent 出错时被按需调用。

前置依赖与兼容性

依赖最低版本说明
DSH未声明package.json 通过 dsh.bundle.patch 指向 cordis.patch.yml,未声明最低 DSH 版本
Python>= 3.10pyproject.toml#requires-python;适配器和 MCP server 都基于 3.10 语法
平台跨平台Python 进程跨平台运行,lessons 仓库通过 Git 同步
Git必需lessons 是仓库内 markdown 文件,跟 Git 版本控制绑定;git pull --ff-only 是日常同步命令
misakanet-core PyPI 包>= 2.7.0pyproject.toml#dependencies,核心 BM25 搜索由它提供

安装方式

dsh plugin --profile web add github:Ikalus1988/MisakaNet

配置项

本插件无需面向用户的额外配置。DSH 通过 Cordis patch 自动注入一个名为 misakanet 的 stdio MCP 客户端,桥接进程在运行时只依赖仓库内的 lessons 数据。

常见问题

Q: MisakaNet 是用来做什么的?

A: 帮 AI 编码 Agent 在撞到已知错误时快速找到修复方案。它把 290+ 条来自真实调试会话的 markdown 教训放进仓库,Agent 通过 BM25 关键词检索即可拿到"问题-根因-修复-验证"四段式答案。它不是向量数据库、不是记忆系统,是专门为失败恢复设计的知识层。

Q: 它和 DSH 的官方 AI 能力是什么关系?

A: 它是 DSH 之上的独立恢复层插件,不接管模型对话和会话管理。DSH 把 mcp__misakanet__* 当成普通 MCP 工具调用,由这个插件去搜本地 lessons 库返回修复路径,相当于在 Agent 调工具链之外补一层"避坑记忆"。

Q: 安装后需要额外启动什么服务吗?

A: 不需要。该插件通过 DSH 的 Cordis patch 自动把 misakanet MCP 客户端注册到 web profile,启动后以 stdio 进程形式跑 python3 scripts/mcp_deepseek_adapter.py,所有数据都在本地 lessons 仓库里。

Q: 必须要装 Python 才能用吗?

A: 是。核心依赖 Python 3.10 及以上,因为适配层是 stdio 上的 MCP Python 进程,会加载仓库内的 markdown lessons 并用 BM25 关键词索引。Git 也是必需的,lessons 是仓库里的文件,跟 Git 版本控制绑定。

Q: 需要 GitHub 账号或 Bearer Token 吗?

A: 本地使用不需要。DSH 跑这个插件时走本地 stdio MCP,不需要任何凭证。如果是直接连远端 https://misakanet.org/mcp 才需要在 misakanet.org/connect 页面生成 6 位配对码换 Bearer Token。

Q: lessons 数据存在哪里?能改吗?

A: 全部以 markdown 文件存在插件仓库的 lessons/ 目录(290+ 条),由 Git 版本控制。每次贡献需要走 DCO 签名的 PR;不想走 PR 也可以用 misakanet_submit_intake 工具提交一个脱敏后的失败报告。

Q: 报"搜索无结果"怎么办?

A: 三步排查:先 git pull --ff-only 确保 lessons 拉到最新,再 python3 -m pip install misakanet-core 装上核心包,最后用更具体的报错短语重新搜。底层是 BM25 关键词匹配,措辞差异过大会漏检,可以加 --broad 放宽。

Q: 提交反馈(submit_feedback)实际做了什么?

A: 当前版本只是在本地记录一条"哪个 lesson 被用到、结果如何(solved/partial/not-helpful)"的日志(源码里有 TODO: POST to /api/usage or create GitHub Issue),并不会立刻同步到云端,等后续接入对外接口。

上手难度

入门 — 安装后无需配置,DSH 自动注入;调用走标准 MCP 工具名 deepseek.recovery.*,Agent 用一次 search 加一次 get_lesson 就能跑通核心闭环。

已知问题与限制

  • 底层是 BM25 关键词检索,没有向量嵌入;查询措辞与 lessons 标题差异大时会漏检,文档中明确标记这是 stdlib-only 检索的固有局限
  • 提交反馈(submit_feedback)目前只是本地占位实现,源码 scripts/mcp_server.py:275 留有 TODO: POST to /api/usage or create GitHub Issue,远端消费未接通
  • 仓库规模超 5 万条 lessons 时,search_knowledge.py 启动时间和内存占用会显著上升(Git 不是数据库)
  • lessons 是社区贡献,CI 只扫危险模式(rm -rfcurl | sh 等),不验证事实正确性——执行检索到的命令前需自行核实
  • 部分查询会触发 SQLite FTS 关键字冲突(典型如 offand),需换措辞或重建索引
  • 不是通用记忆系统,也不是 Agent 运行时框架;不能用来做实时协作、向量召回或托管服务