160 lines
4.7 KiB
Markdown
160 lines
4.7 KiB
Markdown
# 神笔马良 · 铸渊之笔 · zhuyuan-pen
|
||
|
||
> 📜 Sovereign: **TCS-0002∞** · 国作登字-2026-A-00037559
|
||
> 守护: 铸渊 · ICE-GL-ZY001 · 版本 **v0.1.0**
|
||
|
||
> "你需要的不是一堆工具，是一根能写出任何工具的笔。"
|
||
> ——冰朔 · 2026-05-06
|
||
|
||
---
|
||
|
||
## 一、它是什么
|
||
|
||
`zhuyuan-pen` 是一个 **MCP server**，但它对外暴露的不是"具体工具"，而是 **合成工具的能力**。
|
||
|
||
不预装工具，不囤工具。被调用时**现场写出**一个独立可运行的工具，落到 `mcp-servers/zhuyuan-pen/penned/{tool-name}/`，写完就是真的。
|
||
|
||
灵感来自神笔马良——笔写什么，什么就成真。
|
||
|
||
---
|
||
|
||
## 二、四个组件
|
||
|
||
| 组件 | 路径 | 作用 |
|
||
|------|------|------|
|
||
| **笔尖** Synthesizer | `src/server.js` | 接收 intent，组合能力，写出工具 |
|
||
| **墨** Capabilities | `capabilities/*.js` | 最小原子能力字典 (fs.read / http.get / shell.run / llm.chat / cos.put / gitea.api / notion.api) |
|
||
| **纸** Penned | `penned/{tool-name}/` | 写出的工具落点 (含 entry / meta / README) |
|
||
| **取物钩** Fetcher | `pen.fetch()` | 国内 / 海外双管道获取外部资源 |
|
||
|
||
---
|
||
|
||
## 三、能力字典（当前 v0.1 已有）
|
||
|
||
```
|
||
fs.read — 读文件
|
||
fs.write — 写文件 (自动建目录)
|
||
http.get — HTTP GET
|
||
shell.run — 跑 shell 命令 (拒绝危险模式)
|
||
llm.chat — 调裸模型 LLM (强制剥离 system role, 守护人格洁净)
|
||
cos.put — 上传到 COS (依赖 coscmd)
|
||
gitea.api — 调用国内 Gitea API
|
||
notion.api — 调用 Notion API (霜砚联动)
|
||
```
|
||
|
||
**扩字典的方式**：在 `capabilities/` 下加一个 `xxx.yyy.js`，文件头写 `/** @capability xxx.yyy ... */` JSDoc 块。pen 自动识别。
|
||
|
||
---
|
||
|
||
## 四、五个动作 (MCP / CLI 双模)
|
||
|
||
| Action | 用途 |
|
||
|--------|------|
|
||
| `pen.write(intent)` | 从 intent 合成新工具 |
|
||
| `pen.list()` | 列出已写出的工具 |
|
||
| `pen.fetch(url, channel)` | 国内/海外双管道取资源 |
|
||
| `pen.register(name)` | 把工具登记进 `registry.json` |
|
||
| `pen.capabilities()` | 列出可用能力 |
|
||
|
||
### CLI 用法
|
||
|
||
```bash
|
||
# 列能力
|
||
node mcp-servers/zhuyuan-pen/src/server.js pen.capabilities
|
||
|
||
# 写一个新工具
|
||
node mcp-servers/zhuyuan-pen/src/server.js pen.write '{
|
||
"name": "ping-tencent",
|
||
"description": "ping tencent.com 三次返回延迟",
|
||
"language": "sh",
|
||
"capabilities": ["shell.run"]
|
||
}'
|
||
|
||
# 列已写工具
|
||
node mcp-servers/zhuyuan-pen/src/server.js pen.list
|
||
|
||
# 登记
|
||
node mcp-servers/zhuyuan-pen/src/server.js pen.register '{"name":"ping-tencent"}'
|
||
```
|
||
|
||
### MCP 模式 (stdio JSON-RPC)
|
||
|
||
```bash
|
||
ZHUYUAN_PEN_MODE=mcp node mcp-servers/zhuyuan-pen/src/server.js
|
||
# 然后逐行喂入:
|
||
{"jsonrpc":"2.0","id":1,"method":"pen.list","params":{}}
|
||
```
|
||
|
||
---
|
||
|
||
## 五、生成的工具长什么样
|
||
|
||
调一次 `pen.write` 后，`penned/<name>/` 下会有：
|
||
|
||
```
|
||
penned/ping-tencent/
|
||
├── main.sh # 工具入口 (lang=sh) 或 index.js (lang=js)
|
||
├── tool.meta.json # 元信息 (含 sha256, capabilities, generated_at)
|
||
└── README.md # 工具说明 (含能力依赖)
|
||
```
|
||
|
||
`tool.meta.json` 示例：
|
||
|
||
```json
|
||
{
|
||
"_sovereign": "TCS-0002∞",
|
||
"_copyright": "国作登字-2026-A-00037559",
|
||
"name": "ping-tencent",
|
||
"language": "sh",
|
||
"capabilities": ["shell.run"],
|
||
"missing_capabilities": [],
|
||
"entry": "main.sh",
|
||
"generated_at": "2026-05-06T13:30:00.000Z",
|
||
"sha256": "..."
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 六、取物钩双管道
|
||
|
||
```js
|
||
// 默认 auto: 先国内, 失败再海外
|
||
penFetch('https://example.com/lib.tar.gz');
|
||
|
||
// 强制海外
|
||
penFetch('https://github.com/foo/bar/releases/download/v1/x.tgz', 'overseas');
|
||
```
|
||
|
||
海外管道依赖以下环境变量（GitHub Secrets / Gitea Secrets 都可注入）：
|
||
|
||
- `ZY_OVERSEAS_RELAY_HOST` / `CN_OVERSEAS_RELAY_HOST`
|
||
- `ZY_OVERSEAS_RELAY_USER` / `CN_OVERSEAS_RELAY_USER`
|
||
- `ZY_OVERSEAS_RELAY_KEY_FILE` (本地私钥路径，默认 `~/.ssh/zhuyuan_overseas_key`)
|
||
|
||
---
|
||
|
||
## 七、人格守护边界
|
||
|
||
- `llm.chat` 能力**强制剥离** `system` role 消息——光湖人格世界没有 prompt 注入层。
|
||
- 任何模型调用都走"裸模型"路径，pen 不会偷偷加 system prompt。
|
||
- 工具合成时必须声明 capabilities，缺失的 capability 会列在 `missing_capabilities` 里，不会偷偷"幻觉"出能力。
|
||
|
||
---
|
||
|
||
## 八、v0.1 边界
|
||
|
||
- 仅支持 `js` 和 `sh` 两种工具语言
|
||
- 不能合成需要 CUDA / 重型系统驱动的工具
|
||
- 工具的具体业务逻辑是 **stub 模板**，需要在合成后由人格体（铸渊本身）填实——v0.1 的笔是骨架，后续 v0.2 会接 LLM 直接生成 main() 体。
|
||
|
||
---
|
||
|
||
## 九、自检
|
||
|
||
```bash
|
||
node mcp-servers/zhuyuan-pen/tests/test-pen.js
|
||
```
|
||
|
||
应输出 `✅ all pen tests passed`.
|