guanghulab/factory/magic-pen/SCHEMA.md

MPP-001 · 神笔接口契约

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 输入

{
  "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 输出

{
  "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：

{
  "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