# 1. clone 仓库（替换为你的 fork / 你的 git remote）
git clone <repo> ~/Github/creative-subagent-runner-mcp
cd ~/Github/creative-subagent-runner-mcp

# 2. 装依赖
npm install

# 3. 复制 .env 模板,填 3 个 Key
cp .env.example .env
chmod 600 .env
nano .env   # 必填: MCP_AUTH_TOKEN / OPENAI_API_KEY / GEMINI_API_KEY
            # 可选: PORT (默认 3037), HOST (默认 0.0.0.0)

# 4. 编译
npm run build

# 5. 一键装 systemd (用户级 service,不需要 root)
./deploy/deploy.sh install

WAN: <your-public-ip>:PORT
  ↓ 路由器端口转发规则
LAN: <lan-ip-of-server>:3037

sudo ufw allow <PORT>/tcp

# 本机
./deploy/deploy.sh verify

# 外网
curl https://mcp.your-domain.com/healthz
curl -X POST https://mcp.your-domain.com/mcp \
  -H "Authorization: Bearer *** $MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

./deploy/deploy.sh restart   # 重启
./deploy/deploy.sh stop      # 停止
./deploy/deploy.sh status    # 状态
./deploy/deploy.sh logs      # 最近 50 行日志
./deploy/deploy.sh verify    # 验证
./deploy/deploy.sh uninstall # 卸载（保留代码）

cd ~/Github/creative-subagent-runner-mcp
git pull
npm install
npm run build
./deploy/deploy.sh restart

真实 Key 只写入服务器 .env。
不要提交 Git。.gitignore 已包含 .env
不要写进 README / Notion / 聊天。
不要在日志中打印。

{
  "mcpServers": {
    "creative-subagent-runner": {
      "url": "http://<your-public-host>:PORT/mcp",
      "headers": {
        "Authorization": "Bearer <MCP_AUTH_TOKEN>"
      }
    }
  }
}

# 调 list_subagent_roles
curl -X POST http://<your-public-host>:PORT/mcp \
  -H "Authorization: Bearer *** $MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"list_subagent_roles","arguments":{}},"id":1}'

import urllib.request, json

token = "YOUR_MCP_TOKEN"
url = "http://<your-public-host>:PORT/mcp"

req = urllib.request.Request(
    url,
    data=json.dumps({
        "jsonrpc": "2.0",
        "method": "tools/call",
        "params": {
            "name": "run_subagent",
            "arguments": {
                "role": "chapter_writer",
                "task_id": "demo-ch01",
                "project_context": {
                    "l1_core": "...",
                    "l0_world": "...",
                    "series_l2": "...",
                    "current_season_l2": "...",
                },
                "chapter_context": {
                    "chapter_title": "...",
                    "chapter_beats": "...",
                },
                "style_rules": {"tone": "...", "anti_patterns": []},
                "output_contract": {"format": "markdown", "word_count": "350-450", "language": "zh-CN"},
            },
        },
        "id": 1,
    }).encode(),
    headers={
        "Authorization": "Bearer " + token,
        "Content-Type": "application/json",
        "Accept": "application/json, text/event-stream",
    },
)
with urllib.request.urlopen(req, timeout=120) as r:
    for line in r.read().decode().split("\n"):
        if line.startswith("data: "):
            payload = json.loads(line[6:])
            text = payload["result"]["content"][0]["text"]
            result = json.loads(text)
            print(result["content"])  # 写手的正文
            # print(result["report"])   # 审计员的报告

{
  "p0": [],
  "p1": ["第4段: '圆月'比作'小船'在儿童认知中略微违和，建议改'珍珠'或'灯笼'"],
  "score": 9.5,
  "pass": true,
  "summary": "结构完整，Beat执行精准，完美契合L0-L2的温馨基调，结尾的'风声'成功埋下季L2中下一项'听风'的钩子。"
}

{
  "p0": [],
  "p1": ["'忽然'用2次违和 style_rules '温柔安静'基调，建议替换为'这时'或自然变化描写"],
  "score": 9.5,
  "pass": true,
  "summary": "文本高度契合3-6岁目标读者，完美落实了温柔安静的童谣基调。"
}

creative-subagent-runner-mcp/
├── src/
│   ├── index.ts                  # 入口
│   ├── server.ts                 # Express + MCP Streamable HTTP
│   ├── tools/
│   │   ├── healthCheck.ts        # health_check 工具
│   │   ├── listSubagentRoles.ts  # list_subagent_roles 工具
│   │   └── runSubagent.ts        # run_subagent 工具（核心）
│   ├── roles/
│   │   └── index.ts              # 4 角色 prompt + requiredInputFields
│   ├── schemas/
│   │   └── runSubagentInput.ts   # Zod 校验 + missing_context
│   ├── llm/
│   │   ├── openaiCompatibleClient.ts  # GPT /v1/chat/completions
│   │   ├── geminiNativeClient.ts      # Gemini /v1beta/.../generateContent
│   │   └── modelRouter.ts             # 角色路由 + provider_role_mismatch
│   ├── security/
│   │   ├── auth.ts               # Bearer Token 鉴权（常量时间比较）
│   │   └── redact.ts             # API Key / Token 脱敏
│   └── utils/
│       └── env.ts                # .env 加载 + Zod schema 校验
├── deploy/
│   ├── creative-subagent-runner-mcp.service  # systemd unit
│   └── deploy.sh                              # 一键安装/运维脚本
├── scripts/
│   ├── test-llm.ts               # 直连双 LLM 测试
│   ├── e2e-test.py               # 端到端 chapter_writer 测试
│   └── e2e-test-auditors.py       # 端到端审计员测试
├── dist/                          # TypeScript 编译产物
├── .env.example                  # 模板（无 Key，可提交）
├── .env                          # 真实 Key（不入 Git，600 权限）
├── .gitignore
├── package.json
├── tsconfig.json
└── README.md