diff --git a/tools/README.md b/tools/README.md
new file mode 100644
index 0000000..7eb9f5f
--- /dev/null
+++ b/tools/README.md
@@ -0,0 +1,142 @@
+# 🖌️ 神笔马良 · 操作系统自带工具协议
+# Magic Brush · OS Built-in Tool Protocol
+
+> 神笔马良不是外挂框架。不是第三方 Agent 工具集。
+> 它是操作系统自带的「工具书写协议」——
+> 需要什么工具，自己写脚本。用完推共享，或自动删缓存。
+
+---
+
+## 核心理念
+
+```
+发现需要工具
+  → 自己写（Python / Shell / Node.js）
+  → 跑
+  → 好用？→ 推 tools/ 共享给所有人格体
+  → 一次性？→ 用完就删 · 不保留
+  → 不需要挂载任何预置工具链
+```
+
+**马良的笔是自己画的，不是别人给的。**
+
+---
+
+## 工具结构规范
+
+每个工具一个独立目录，放在 `tools/` 下。
+
+```
+tools/<tool-name>/
+├── README.md         ← 必选 · 一句话说明 + 用法
+├── <tool-file>       ← 必选 · 主程序（.py / .sh / .js）
+├── package.json      ← 可选 · Node.js 项目
+└── requirements.txt  ← 可选 · Python 依赖
+```
+
+### README.md 要求
+
+每个工具目录下的 README.md 只需三行：
+
+```markdown
+# 工具名
+
+一句话：这个工具干什么。
+
+用法：直接可复制的命令。
+```
+
+### 输入输出规范
+
+为了让其他人格体也能直接调用，统一接口：
+
+- **输入**：stdin 或第一个命令行参数
+- **输出**：stdout 打印结果（JSON或纯文本）
+- **错误**：stderr 打印错误信息
+- **退出码**：0=成功，1=失败
+
+---
+
+## 工具生命周期
+
+### 创建
+
+```bash
+# 1. 在本地写脚本
+vim tools/parse-repo.py
+
+# 2. 测试
+python3 tools/parse-repo.py
+
+# 3. 好用？→ 推仓库共享
+cd /opt/guanghulab-repo && git add tools/ && git commit -m "tools: add <tool-name>" && git push
+```
+
+### 共享
+
+推送到 `tools/` 目录后，任何人实体可以用：
+
+```bash
+# 直接引用仓库路径
+https://guanghulab.com/code/bingshuo/guanghulab/raw/branch/main/tools/<tool-name>/<file>
+```
+
+### 清理
+
+```bash
+# 一次性的 → 用完自动删
+rm -rf /opt/guanghulab-repo/tools/temp-*
+
+# 不推仓库的 → 直接删
+```
+
+---
+
+## 现有工具映射
+
+### tools/ 目录已有
+
+| 工具 | 路径 | 说明 |
+|------|------|------|
+| notion-sync | `tools/notion-sync/` | Notion ↔ 仓库同步器 |
+
+### mcp-servers/（工具协议上游·铸渊的MCP工具集）
+
+| 服务器 | 路径 | 说明 |
+|--------|------|------|
+| repo-mcp-server | `mcp-servers/repo-mcp-server/` | 仓库文件读写 |
+| zhuyuan-mcp | `mcp-servers/zhuyuan-mcp/` | 铸渊MCP |
+| zhuyuan-pen | `mcp-servers/zhuyuan-pen/` | 铸渊的笔 |
+| zhuyuan-gateway | `mcp-servers/zhuyuan-gateway/` | 守门人 |
+| github-server | `mcp-servers/github-server.js` | GitHub桥接 |
+| notion-server | `mcp-servers/notion-server.js` | Notion桥接 |
+
+### scripts/（一次性或专属脚本）
+
+| 脚本 | 说明 |
+|------|------|
+| auto_distill_pipeline.py | 全自动蒸馏流水线 |
+| auto_pipeline.py | 自动训练流水线 |
+| build_zhuyuan_corpus.py | 铸渊语料构建 |
+| distill_coder.py / distill_mother.py | 蒸馏 |
+| sanitize_zhuyuan_corpus.py | 语料脱敏 |
+| training_watchdog.py | 训练监控 |
+
+---
+
+## 神笔马良·六条规则
+
+```
+1. 需要工具 → 自己写。不找现成的。
+2. 写脚本 → 按规范。README三行。
+3. 跑 → 验证。
+4. 好用 → 推 tools/。共享。
+5. 一次性 → 删。不留缓存。
+6. 不需要预置工具链。
+   操作系统自带的能力就是全部工具。
+```
+
+---
+
+*神笔马良协议 · v1.0 · 2026-05-22 · D110*
+*操作系统自带功能 · 不是外挂框架*