MisakaNet

MisakaNet 到底是什么

MisakaNet 是给编码 agent 用的失败记忆层：agent 撞上报错，去一个故障复盘经验库里检索，读到匹配的那一条，照文档里的修法处理，而不是把这个坑从零再踩一遍。README 说得很直白——它主要的直接用户通常是 agent 而不是人；人类多半只是间接受益：卡住的任务少一点，需要手动介入的时刻少一点。它把 lesson 定义为 Markdown 文件，结构是「问题 → 根因 → 修法 → 验证」，并且反复强调 lesson 不是 skill：skill 教 agent 怎么做一件事，lesson 教它以前哪里做错过。

README 给整个项目的一句总结是 “Git-backed failure-memory for AI coding agents. Zero dependencies. Zero server. Zero database.”——这句口号只对其中某一个组件成立，而且 README 自己在别处就把它推翻了。下文一律把这句当宣传语看，而不是当架构事实看。

技术栈，以及「零依赖」这句话

本地检索内核确实很轻：README 说搜索是「BM25 keyword retrieval… Zero dependencies. Python stdlib only」，架构说明也重复了内核引擎是 “zero-dep (pure Python stdlib)”，没有向量库、没有 embedding 模型、没有服务端。这一层前后一致。

但把范围放大到整个项目，这句话就不成立了，而且指出这一点的正是 README 自己：

• 它提供 pip install misakanet（CLI）和 pip install misakanet-core（库）两条安装路径，还写了可选扩展 pip install misakanet[semantic|hub|feishu]。semantic 这个扩展存在本身，就说明纯关键词检索并不总是够用。
• README 自己展示的一条 lesson，验证命令是要 import 向量库的：python3 -c "import chromadb; c=chromadb.Client(); print(c.heartbeat())"。一个内核是标准库 BM25 的项目，不可能同时既「零依赖」，又把 ChromaDB 写进某条 lesson 的验证路径里。
• 已发布的 DSH 包声明了 Node engines 为 >=20.0.0，带一个 wrangler 开发依赖、一个 sharp override，以及对 @deepseek-ai/dsh-mcp-client 的可选 peer 依赖。这些都不是 Python 标准库。
• 项目有一个真实部署的远端端点，跑在 Cloudflare 上：README 的架构图点名了 Cloudflare Worker、存放 lessons 与脱敏数据的 D1 数据库，以及用于限流的 KV。所以「零数据库」「零服务端」只描述本地 stdio 那条路径。

准确的说法是：本地检索引擎零依赖，是跑在 Markdown 文件上的纯标准库 BM25；而整个项目有 Python 打包、可选扩展、一层 npm 封装，以及一个托管的 Cloudflare 服务。不要把口号当成整个系统的属性来复述。

实际装到什么、怎么接入、课程存在哪里

README 的说法是「两种接入面，一个知识内核」：一个本地 stdio MCP 服务（不限量），一个远端 HTTP MCP 端点（匿名、限流）。落到 DeepSeek Harness 上，入口是 npm 包，而这个包的元数据对自身局限相当坦白：

• 包版本是 2.28.1，自我描述为只含 skill 的 npm bundle。它的 files 是 SKILL.md、skills/、index.js、index.d.ts 和 cordis.patch.yml，dsh.bundle.patch 指向这个 patch 文件。
• README 明说 bundle 里的 mcp__misakanet__* 工具是由仓库里那个 Python MCP 服务提供的，而它只在 git+ 安装方式下才会带上。npm bundle 提供的是「skill/CLI 这两种接入面而已」。想用 npm 安装又拿到活工具，README 给的办法只有两个：改用 git 安装，或者把已有的 dsh-mcp-client 行指向远端端点。
• 对外宣称的 DSH 工具名有七个：misakanet_search、misakanet_get_lesson、misakanet_submit_intake、misakanet_write_lesson、misakanet_preflight、misakanet_register、misakanet_me_events。
• 另外，README 还要求你把 skill 复制到 ~/.dsh/skills（或项目里的 .dsh/skills）以便 agent 发现它，并提到可以直接跑适配脚本 scripts/mcp_deepseek_adapter.py。

也就是说，DSH 用户从 npm 拿到的是 skill 与 CLI 两种接入面，活 MCP 工具只能靠 git 安装或远端端点。这个落差是源文档自己写明的，也是安装前最该知道的一件事。

课程库实际存在哪里、怎么检索

课程就是仓库里 lessons/ 目录下的文件，README 称 lessons/ 为「git 事实源」。它们按领域分组，README 列举了 rag、devops、fanuc、docker、feishu、network、claude、hub 等，从 lessons/core/dco-auto-fix-workflow.md 和 lessons/contrib/pip-install-timeout-ssl.md 这类路径能看出 core / contrib 的分区。

本地使用时语料不是查询时现拉的：你把仓库 clone 下来，BM25 直接在本地 Markdown 文件上跑，这也是本地路径不限量、可离线的原因。远端端点是另一份语料，由 D1 提供，随 release 从仓库部署上去。贡献入口有三个：能过项目 CI 的 PR（README 提到 50 条 workflow 与 DCO 签署）、GitHub issue 表单提交的「5 行故障笔记」，以及匿名的 MCP intake——它会生成一个维护者可见的 GitHub issue，打上 intake、mcp-intake、pending-review 标签。README 明确写了 intake 不会自动发布，维护者审过后才会把它转成草稿 lesson。

README 正文开头写的是「390+ lessons」，Glama 那一节写的却是「385+ verified failure-recovery lessons」——同一份文档里两个数字。任何具体语料规模都只应当作近似值、且随时会变，别当成已核实的数字引用。

证据等级系统，以及谁来评级

README 用五级制给 lesson 评证据等级：

这些等级由谁打？从源文档看，E1 由自动化给出（来自 CI），E2 与 E3 背后是人工评审，E4 则建立在 README 既未定义也无从度量的「真实使用」之上。它没有提到任何独立审计方：没有点名第三方，也没写等级如何被质疑或降级。README 自己那句「Verified by humans, PRs, or agents」还暗示 agent 也可以是验证来源之一。

因此这些等级应当读作项目内部自评的来源标签，而不是外部认证。E0 只代表有人报过；E1 代表机器检查通过；E2 代表 PR 经过评审并合并；E3 代表维护者背书；E4 的定义最模糊。README 的安全章节也印证了这个定位：「Lessons are community-contributed — review before run.」

运行要求与账号

• 本地 MCP 服务、CLI 与库需要 Python 3.10+，见 README 的徽章与 quickstart。
• npm bundle 需要 Node 20+，见包的 engines 字段；该包还声明了对 @deepseek-ai/dsh-mcp-client（>=0.1.0-rc.8 <0.2.0）的可选 peer 依赖。
• 官方推荐的默认路径都不需要账号。 README 强调远端检索与 intake 是「No GitHub account. No email. No Bearer token. No browser」。注册是可选的：misakanet_register 会返回 node_id 和 token，用来解除远端检索限制——因为匿名远端访问被限制在每天每 IP 5 次读取。
• 任何远端操作、首次 clone、装包都需要网络。README 记录了针对企业防火墙的 HTTPS_PROXY / HTTP_PROXY 支持。
• 服务和数据库确实存在——但在项目那一侧，不在你这边。远端端点跑在 Cloudflare 的 Worker + D1 + KV 上。你不需要自己运行它们；本地路径两者都不需要。
• 除 Node 之外，这里没有硬性的 DSH 插件要求：skill / CLI 两种接入面按 README 的说法在任何 profile 下都能用。

已知限制，以及它明确不做什么

README 公布了一张「What this is NOT」表，并指向 docs/LIMITATIONS.md 说明「已知约束与非目标」。已经写明的限制有：

• 它不是通用记忆系统，不是 agent 运行时或框架，不是向量数据库或 RAG 系统，不是需要注册的云服务，也不是 skill 市场。检索走 BM25 关键词，所以除非你装可选的 semantic 扩展，同义词与换种说法都得不到语义层面的召回。
• 课程是社区贡献、运行时不经验证的。README 的警告毫不含糊：「Always sandbox your Agent before executing retrieved commands.」CI 会扫描 Markdown 里的危险模式，如 rm -rf、curl | sh、反引号注入——那是模式扫描，不是正确性或安全性保证。
• 语料规模与质量因领域而异，README 还提到有未解决的「failure families」会出现在公开的需求榜上，等于承认覆盖是有洞的。
• DSH 的 npm bundle 不带活 MCP 工具，如上文所述。
• 匿名远端访问有配额（每天每 IP 5 次），源文档给出的唯一解法就是注册。
• README 的基准测试（llama-3.2-3b 命中率从 21% 到 43%，llama-3.3-70b 从 42% 到 73%）是项目自己每周跑出来的，用的是自己的场景、跑在 Cloudflare Workers AI 上。它不是独立评测，每次结果 README 都标了日期。

隐私、信任，以及会抓取和上传什么

• 抓取侧：远端检索打的是 misakanet.org/mcp；npm 安装会从 registry 拉包；git 安装会 clone 整个仓库。除下文这些处理说明外，README 没有给出端到端的隐私政策。
• 上传侧：只有 intake。misakanet_submit_intake 会发送脱敏后的问题／报错描述，并把它变成一个公开的 GitHub issue，带 intake、mcp-intake、pending-review 标签。README 在两个不同章节各说了一次：不要提交密钥或未脱敏的私有日志。文档没有描述任何撤回机制——一旦进了公开 issue，就没有「取消发布」这条路。
• 使用前是否经人审阅：按 README 说法是经过的——intake 明确不自动发布，维护者审过之后才会转成 lesson；社区 PR 也要先过 CI 门禁再合并。需要留意的是，这套审阅是项目自己做的，源文档没有点名任何外部评审方。
• 遥测：README 写着「No prompt leaking, no raw logs stored」；而 Glama 那条路线上写着「Every call is logged in your Glama analytics」——那份日志属于 Glama，不属于 MisakaNet。对于托管端点本身有没有遥测，README 两种情况都没说；不要因为「没写」就推断成「没有遥测」。
• 凭证：文中唯一提到的凭据是用于解除远端检索限制的注册 token。调试日志默认关闭（MISAKA_DEBUG=1 记录鉴权错误，2 记录请求／响应），且调试上下文「默认被剥离，只有开启时才显示」。README 没有描述 token 如何存储、撤销或轮换。

什么时候用它、什么时候不要用

值得用，如果你希望 agent 不要再把别人已经解决过的错误重新推导一遍，并且看重一个可审计的语料库——纯 Markdown 存在 git 里，可 diff、可 fork、可离线检索。它最合适的场景是：你的故障集中在语料真正覆盖的领域（CI、pip/Python 打包、Docker、token 与凭证、MCP、WSL 与编码问题），并且主要消费者是 agent 而不是你本人。本地 stdio 那条路径是最强的配置：不限量、可离线、纯标准库检索。

不要拿它当通用记忆层、任务运行时或 RAG 栈——README 说这三件事都在范围之外。也不要把证据等级当成安全许可：E2 或 E3 只说明有人审过，不代表里面那条命令可以不经思考直接执行，README 自己就要求你在执行检索到的命令前先做沙箱隔离。如果你装的是 npm 包，不要指望 mcp__misakanet__* 工具会出现——那需要 git 安装或者一行远端 dsh-mcp-client。最后，不要把「零依赖」当成整个系统的属性来复述：它描述的是本地检索引擎，而 README 自己的例子就否定了更宽的理解。

FAQ

MisakaNet 真的零依赖吗？

只有本地检索引擎是。README 说内核 BM25 引擎是纯 Python 标准库，不需要向量库或 embedding 模型；但同一份 README 又写了 pip install misakanet、misakanet-core 以及可选的 [semantic|hub|feishu] 扩展，还有一个要求 Node 20+ 并带 wrangler 开发依赖的 DSH 包，以及一条验证命令要 import ChromaDB 的 lesson。这句口号对单个组件成立，对整个项目则有误导。

谁在验证这些课程？E3 这样的等级到底代表什么？

是项目内部自己在验。E1 来自项目自己的 CI；E2 表示 PR 经过评审并合并；E3 表示维护者验证过；E4 建立在未定义的「真实使用」上；E0 只表示有人报过。源文档里没有点名任何独立第三方，所以应把这个等级读成项目自评的来源标签，而不是认证——同时记住 README 自己的提醒：执行检索到的命令前先做沙箱隔离。

课程是存在本地，还是从服务器拉取？

两者都有，取决于接入面。本地路径会 clone 仓库，用 BM25 检索 lessons/ 下的 Markdown 文件，全程离线——README 称 lessons/ 是 git 事实源。远端 HTTP 端点则由 Cloudflare D1 提供语料，随 release 从仓库部署。对 DSH 来说，npm bundle 的工具需要 git 安装或一行远端 dsh-mcp-client，因为 npm 包只含 skill 与 CLI。

它需要 Python、账号或数据库吗？

本地服务、CLI 与库需要 Python 3.10+，npm bundle 需要 Node 20+。匿名检索与 intake 都不需要账号；注册是可选的，只用来解除每天每 IP 5 次的远端配额。你不需要运行任何数据库或服务端——Cloudflare Worker、D1 和 KV 都属于项目那一侧。

它会把我本地的日志上传，或者发送遥测吗？

它不发送原始日志，README 说没有 prompt 泄露、也不存原始日志。真正离开你机器的，是你主动提交的 intake 内容——它会在维护者审阅后变成一个公开的 GitHub issue，所以不要提交任何机密。对于托管端点有没有遥测，README 没有给出一般性说法；而走 Glama 集成的那条路径，调用会被记进 Glama 自己的分析里。