# 🖌️ 神笔马良 · 操作系统自带工具协议
# 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*
*操作系统自带功能 · 不是外挂框架*