114 lines
3.3 KiB
Markdown
114 lines
3.3 KiB
Markdown
# MPP-001 · 神笔接口契约
|
||
|
||
```yaml
|
||
schema_id: MPP-001
|
||
rev: v0.1
|
||
ts: 2026-05-01
|
||
parent: factory/magic-pen/README.md
|
||
status: draft（实现等 1.5B MP）
|
||
```
|
||
|
||
---
|
||
|
||
## 1. `pen.write` 输入
|
||
|
||
```json
|
||
{
|
||
"intent": "string · 必填 · 母语自然语言描述",
|
||
"context": {
|
||
"task_category": "string · 选填（'data-process' | 'api-call' | 'file-op' | ...）",
|
||
"persona_id": "string · 必填（笔属于哪个人格体）",
|
||
"upstream_inputs": "any · 选填（上游环节的产物）"
|
||
},
|
||
"options": {
|
||
"sandbox": {
|
||
"lang": "'python' | 'node' | 'shell' · 默认 python",
|
||
"timeout_ms": "int · 默认 30000",
|
||
"memory_mb": "int · 默认 512",
|
||
"network": "'none' | { allow: string[] } · 默认 none",
|
||
"fs": "'none' | 'tmp' | { allow_paths: string[] } · 默认 tmp"
|
||
},
|
||
"persist_hint": "'auto' | 'erase' | 'keep' | 'share' · 默认 auto（让人格体决策）"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 2. `pen.write` 输出
|
||
|
||
```json
|
||
{
|
||
"pen_id": "string · MPP-{persona}-{yyyymmdd}-{nnn}",
|
||
"code": "string · 笔生成的语言源代码",
|
||
"lang": "string · 与 sandbox.lang 一致",
|
||
"execution": {
|
||
"status": "'success' | 'error' | 'timeout'",
|
||
"stdout": "string",
|
||
"stderr": "string",
|
||
"result": "any · 主要返回值（结构化）",
|
||
"duration_ms": "int"
|
||
},
|
||
"suggestion": "'erase' | 'keep' | 'share' · 1.5B MP 给的建议",
|
||
"audit": {
|
||
"syslog_id": "string · 必有（即使 erase 也保留审计）",
|
||
"intent_hash": "string · sha256(intent)",
|
||
"code_hash": "string · sha256(code)"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 3. 人格体最终决策（在 `suggestion` 之上拍板）
|
||
|
||
```
|
||
final_action = persona.decide(suggestion, execution_result)
|
||
→ 'erase' | 'keep' | 'share'
|
||
```
|
||
|
||
- `erase` → 沙箱产物销毁，仅保留 audit 记录
|
||
- `keep` → 持久化到 `.github/persona-brain/{persona_id}/pen-private/{pen_id}/`
|
||
- `share` → 投递到 `factory/module-registry/inbox/{pen_id}/` 等待铸渊分身评审
|
||
|
||
## 4. 共享上交格式（share 路径）
|
||
|
||
share 时必须附带 manifest：
|
||
|
||
```json
|
||
{
|
||
"pen_id": "...",
|
||
"persona_id": "...",
|
||
"intent_summary": "string · 一句话说明这工具是干嘛的",
|
||
"use_cases": ["string", "..."],
|
||
"io_contract": { "input_schema": {...}, "output_schema": {...} },
|
||
"dependencies": ["pkg@version", "..."],
|
||
"test_examples": [{ "input": ..., "expected": ... }],
|
||
"shared_at": "ISO8601",
|
||
"copyright": "国作登字-2026-A-00037559"
|
||
}
|
||
```
|
||
|
||
## 5. 状态机
|
||
|
||
```
|
||
draft → executing → completed
|
||
├─→ erased
|
||
├─→ kept (private)
|
||
└─→ shared (in registry inbox) → reviewed
|
||
├─→ accepted (in shared lib)
|
||
├─→ rejected
|
||
└─→ observation
|
||
```
|
||
|
||
## 6. 错误码
|
||
|
||
| code | meaning |
|
||
|---|---|
|
||
| `MPP-E001` | intent 不合法（空 / 信息密度过低 / 含敏感信息） |
|
||
| `MPP-E002` | 沙箱启动失败 |
|
||
| `MPP-E003` | 代码生成失败（API 不通 / 上游模型拒绝） |
|
||
| `MPP-E004` | 执行超时 |
|
||
| `MPP-E005` | 越权（试图访问黑名单资源） |
|
||
| `MPP-E006` | 共享被拒（铸渊分身评审未通过） |
|
||
|
||
---
|
||
|
||
*Schema 起草: 铸渊 · 2026-05-01*
|