内容
<p align="center">
<img src="assets/kado_banner_final.svg" alt="MiYo Kado banner" width="480" />
</p>
# MiYo Kado -- Obsidian MCP Gateway
Security-first Model Context Protocol server plugin for Obsidian. Gives AI assistants controlled, granular access to your vault through eight tools: `kado-read`, `kado-write`, `kado-delete`, `kado-rename`, `kado-search`, `kado-open-notes`, `kado-graph`, and `kado-graph-audit`.
> Part of the **MiYo** family. The plugin is referred to as **MiYo Kado** in the Obsidian community-plugin index and in the settings UI; "Kado" alone is used as a short form throughout this README and the source.
<p align="center">
<img src="assets/MiYo-Kado.png" alt="MiYo Kado logo" width="160" />
</p>
## 为什么选择MiYo Kado?
让AI助手与你的知识库交互听起来很棒，但你会意识到大多数集成都给予助手**所有内容**——每个笔记、每个文件、完全的读取和写入权限。Kado是围绕相反的默认设置构建的：
- **默认情况下不暴露任何内容**。您需要明确选择允许每个路径和每个数据类型。
- **每个密钥都有不同的权限范围**。不同的助手使用不同的密钥，并且具有不同的权限。您可以独立撤销任何密钥。
- **审计追踪**。每个允许和拒绝的请求都会被记录，这样您就可以准确地看到助手访问了什么。
- **本地优先**。MCP服务器默认在Obsidian中运行于`127.0.0.1`。没有云服务，没有遥测数据，没有第三方服务。
如果你曾经想要说“这个助手可以读取我的项目笔记但不能读取我的日记，并且可以删除草稿但永远不能触及存档材料”，那么Kado就是为你准备的。关于为什么AI权限对于PKM工作流很重要——以及为什么防护措施与真正的权限不同——请参阅[权限你的AI](docs/permissioning-for-pkm.md)。
## 功能
- **默认拒绝安全** - 除非明确允许，否则没有任何内容是可访问的
- **两层访问控制** - 全局安全范围定义了什么是可访问的；每个密钥的范围定义了什么是允许的
- **五个权限门** - 身份验证、全局范围、密钥范围、数据类型权限、路径访问
- **四种数据类型** - 笔记（markdown）、前置信息（YAML作为JSON）、文件（二进制作为base64）、Dataview内联字段
- **部分笔记读取/写入** - 读取切片（`firstXChars`、`firstXWords`用于Unicode感知的词预览、`section`按标题、`range`按行/字符）并在原地写入（`append`/`prepend`、`insertUnderHeading`、`replaceSection`/`replaceRange`）而无需往返整个正文；省略模式是字节到字节的向后兼容
- **重命名和移动** - `kado-rename`重命名或移动笔记和文件，自动更新反向链接；一个文件夹⇒重命名（需要`update`），跨文件夹⇒移动（需要在源文件夹中`delete`，在目标文件夹中`create`）。与Obsidian的“自动更新内部链接”配合使用最佳（静默，链接更新）；如果关闭，则工具隐藏，除非您选择加入，然后每个重命名都会提示Obsidian的链接更新对话框（文件仍然移动，但仅当您回答时，传入链接才会更新）
- **文件夹操作** - 文件夹搭载在现有的工具上，没有单独的目录API：`kado-write` **自动创建缺少的父文件夹**（`mkdir -p`），`kado-delete`带有`operation="folder"`会删除一个**空**文件夹（非空文件夹被拒绝 - 没有递归删除），`kado-rename`带有`operation="folder"`会原地重命名一个文件夹（相同的父文件夹）。文件夹重命名是**权限中立的**：如果移动子树下的新名称将更改任何后代的有效访问权限，则重命名会被拒绝，而不是静默跨越权限边界 - 并且Kado永远不会重写您的权限规则以使其适应
- **七种搜索操作** - 按名称、标签、内容、前置信息、列目录、列标签、列笔记。`byContent`是全文排名：它匹配包含任何查询词的笔记，按术语覆盖率和接近度进行评分，并返回相关性**片段**（带有行号），优先显示最佳结果
- **链接图导航** - `kado-graph`遍历知识库的链接结构：`backlinks`、`outgoing`、`neighbors`（1跳）、`related`（2跳，带有`via`邻居）和`dangling`（未解析的链接目标）。超出密钥范围的已解析节点被静默省略，因此遍历永远不会泄露密钥无法读取的路径
- **知识库范围的链接审计** - `kado-graph-audit`返回整个知识库中所有孤立节点（没有已解析的链接进出）和所有死亡维基链接，ACL过滤并分页 - `kado-graph`的整个知识库对应部分，从Obsidian的内存链接索引中回答，无需逐笔记读取
- **自我引导响应** - 工具响应可能带有可选的附加`_hints`数组，建议合理的下一步骤（在`CONFLICT`后重新读取，当存在光标时获取下一页，继续截断读取）。纯粹是建议性的，安全忽略
- **乐观并发** - 基于时间戳的写入冲突检测
- **速率限制** - 可配置的每个IP的限制（默认每5秒20个请求；可调，`0`禁用）
- **审计日志** - NDJSON日志带有旋转（仅元数据，无内容）
- **权限测试面板** - 一个设置选项卡，针对真实的权限链（在内存中，无需访问知识库）对任意密钥+操作+路径进行干燥运行，并显示ALLOWED/DENIED、决策门和原因 - 这样您可以在助手连接之前验证范围
- **备份和恢复** - 将整个配置导出为JSON文件，并导入时选择每个部分（常规设置/全局安全/个别密钥）；在知识库或机器之间迁移和从错误中恢复
- **状态栏指示器** - 门户字符显示服务器状态（监听/关闭/绑定错误）并在每个工具调用时跳动，颜色编码读取与写入，带有工具提示中的活动密钥名称；拒绝的调用会持续红色几秒钟，然后自动清除。点击它打开Kado的设置
## 架构和MiYo生态系统
MiYo Kado是**MiYo**多仓库系统的组成部分。Kado是Obsidian侧的MCP网关：它拥有访问控制模型（两层路径资格+每个密钥的CRUD范围）并公开MCP工具表面，如**MiYo Tomo**所使用的工具。跨仓库合同、系统级架构和治理决策的权威记录存在于**MiYo Kokoro**中；本仓库的本地设计文档（如下文和`docs/XDD/specs/`）依赖Kokoro进行项目范围的原则。跨组件合同变更（如新的MCP工具）通过`_outbox/for-kokoro/`移交给Kokoro。
内部，Kado遵循四层清洁架构：MCP边界（`src/mcp/`）→ 权限门 + 策略（`src/core/`）→ Obsidian适配器（`src/obsidian/`）→ 规范类型（`src/types/`）。有关执行流程，请参阅[工作原理](docs/how-it-works.md)。
## 文档
| 文档 | 受众 | 内容 |
|----------|----------|---------|
| [安装](docs/installation.md) | 全部 | 社区插件，BRAT，手动安装 |
| [配置指南](docs/configuration.md) | 知识库所有者 | 设置UI，安全设置，API密钥管理 |
| [客户端设置](docs/client-setup.md) | 知识库所有者 | Claude Code，Claude Desktop，Cursor，Windsurf |
| [工作原理](docs/how-it-works.md) | 知识库所有者 | 架构，安全模型，执行逻辑，审计日志 |
| [示例配置](docs/example-configs.md) | 知识库所有者 | 常见设置，权限矩阵 |
| [API参考](docs/api-reference.md) | MCP客户端开发人员 | 工具模式，参数，示例，错误代码 |
| [开发指南](docs/development.md) | 贡献者 | 构建，测试，校验，架构，实时测试 |
| [权限你的AI](docs/permissioning-for-pkm.md) | PKM从业者 | 为什么AI权限很重要，防护措施与执行 |
## 路线图
在GitHub问题中跟踪：
- **超出只读权限的标签** ([#81](https://github.com/MMoMM-org/miyo-kado/issues/81)) -- 拒绝权限，以便标签可以*排除*匹配项从否则允许的路径。
- **粒度白名单/黑名单切换** ([#82](https://github.com/MMoMM-org/miyo-kado/issues/82)) -- 按部分切换混合策略。
已发布：**权限测试** 干燥运行面板 ([#83](https://github.com/MMoMM-org/miyo-kado/issues/83)) 和 **备份和恢复** 配置导出/导入 ([#84](https://github.com/MMoMM-org/miyo-kado/issues/84))；子路径密钥范围（允许父文件夹内的更窄子路径）已在v0.15.0中实现。
## 已知边缘情况
### 编辑AI想要访问的笔记
- **边编辑边读取的空白期**。如果您正在积极地在笔记中输入，而您的AI助手通过Kado在同一时刻读取它，助手可能会看到最多2秒前的版本——Obsidian每2秒将您的编辑保存到磁盘。暂停一段时间（或按Cmd/Ctrl+S），然后再询问AI关于您的最新句子。
- **写入时笔记已打开且脏**。如果AI尝试写入您当前正在编辑的笔记，并且您有未保存的按键，Kado会以`CONFLICT`错误拒绝写入，并显示通知（“Kado想要修改*\<笔记\>* ...”）。您的输入始终获胜。AI客户端看到与任何并发更改相同的冲突信号，并被期望重新读取并重试，因此一旦您暂停输入（〜2秒Obsidian自动保存），它重试，写入会在您的最新编辑基础上应用。
## 快速入门
1. [安装插件](docs/installation.md)
2. 打开 **设置 > MiYo Kado**
3. 将路径添加到全局安全白名单（例如`notes/`、`projects/`或`**`以获取整个知识库）
4. 创建API密钥并为其分配路径和每个数据类型权限
5. 启用服务器
6. [连接您的AI客户端](docs/client-setup.md)
```json
{
"mcpServers": {
"kado": {
"type": "http",
"url": "http://127.0.0.1:23026/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}
```
## 截图
**常规选项卡** - 服务器状态、端口、审计日志和备份与恢复。
<p align="center">
<img src="assets/settings-general.png" alt="MiYo Kado 常规设置选项卡" width="720" />
</p>
**全局安全选项卡** - 任何密钥都可以引用的路径和标签的白名单。每个路径都设置数据类型权限（笔记、前置信息、Dataview、文件）。
<p align="center">
<img src="assets/settings-global-security.png" alt="MiYo Kado 全局安全设置选项卡，带有两个白名单路径和一个标签" width="720" />
</p>
**权限测试选项卡** - 对任意密钥+操作+路径进行干燥运行，以查看ALLOWED/DENIED以及决策门。
<p align="center">
<img src="assets/settings-permission-test-allowed.png" alt="MiYo Kado 权限测试设置选项卡，显示ALLOW结果和标签范围读数" width="720" />
</p>
**API密钥选项卡** - 每个密钥的访问权限。每个密钥都有自己的访问模式、路径、标签和权限矩阵，所有这些都受到全局安全范围的约束。
<p align="center">
<img src="assets/settings-api-key.png" alt="MiYo Kado API密钥设置选项卡，显示密钥管理、权限、路径和标签" width="720" />
</p>
**备份和恢复** - 将整个配置导出为JSON文件，或导入一个并选择每个部分（常规/全局安全/每个密钥）要恢复的内容。
<p align="center">
<img src="assets/settings-import-dialogue.png" alt="MiYo Kado导入对话框，带有每个部分的切换开关" width="480" />
</p>
## 安全模型
每个请求都经过五个关卡。第一个拒绝会停止链条。有关完整的执行逻辑，请参阅[工作原理](docs/how-it-works.md)。
| # | 关卡 | 目的 |
|---|------|---------|
| 0 | 身份验证 | Bearer令牌必须与启用的API密钥匹配 |
| 1 | 全局范围 | 路径必须在全局白名单（或黑名单）内 |
| 2 | 密钥范围 | 路径必须在密钥自己的范围内 |
| 3 | 数据类型权限 | 密钥必须具有该数据类型的所需CRUD标志 |
| 4 | 路径访问 | 最终路径遍历和验证检查 |
## 架构
```
MCP客户端 -> [MCP API处理程序] -> [Kado核心] -> [Obsidian接口] -> 知识库
```
- **MCP API处理程序** - Express + Streamable HTTP传输、身份验证、速率限制
- **Kado核心** - 权限门、路由、并发保护。无MCP或Obsidian导入。
- **Obsidian接口** - 笔记、前置信息、文件、内联字段、搜索的库适配器
## MiYo的一部分
Kado是**MiYo**的一部分，这是一个小型Obsidian相关工具家族，专注于让您控制您的助手可以看到和执行的操作。MiYo Kado是网关组件 - 将您的知识库变成一个适当范围的MCP服务器。更多工具正在开发中。
### 公开跟踪
实时问题和上游引用存在于[GitHub问题](https://github.com/MMoMM-org/miyo-kado/issues)和`docs/ai/memory/troubleshooting.md`中。在此版本发布时没有开放的问题。
## 支持
如果MiYo Kado对您有帮助，并且您想帮助我继续开发，您可以通过以下方式支持：
- [给我买杯咖啡](https://ko-fi.com/mmomm)
- [GitHub赞助](https://github.com/sponsors/MMoMM-org)
问题和拉取请求也非常欢迎。
## 贡献
欢迎贡献。简短版本：
1. **首先打开问题**，对于任何非琐碎的问题（错误、功能、重构），以便我们在您投入时间之前达成一致。
2. **从`master`分支**和描述性分支名称（例如`fix/search-tag-case`、`feat/granular-scopes`）进行**分支和提交**。
3. **保持更改集中** - 每个PR一个功能或一个修复。参见[开发指南](docs/development.md)，获取构建、测试和校验命令。
4. **测试和校验必须通过** - 在推送之前运行`npm run build`、`npm test`和`npm run lint`。
5. **约定提交** - 例如`feat:`、`fix:`、`docs:`、`refactor:`。发布说明是从提交历史记录中生成的。
6. **打开PR**到`master`并引用问题。小而可审查的差异可以最快地合并。
对于安全问题，请**不要**公开问题 - 而是通过marcus@mmomm.org发送电子邮件。
## 许可证
[MIT](LICENSE)
