四、统一任务接口规范 v0.1
目标：任何项目通过"一份任务清单 + 一组遵守约定的脚本"接入执行工作台，不改执行引擎。
1. 任务清单（projects/<project>/tasks.json）
{
"project": "bagcomply",
"repoRoot": "C:/Users/15755/WorkBuddy/bagcomply.com",
"tasks": [
{
"id": "validate",
"entry": "npm run --silent validate",
"description": "数据全量校验（10 闸）",
"sideEffects": "read-only",
"timeoutMs": 600000,
"resultSource": "stdout-json"
},
{
"id": "collect-page",
"entry": "node scripts/collect-page.mjs",
"params": { "url": "string", "airline": "string" },
"sideEffects": "mutating",
"timeoutMs": 300000
}
]
}
字段定义：
id：任务标识，项目内唯一，全局寻址为<project>:<task>entry：执行入口命令（在 repoRoot 下执行）params：输入参数 schema（执行台校验后以环境变量EXEC_PARAMS（JSON 字符串）+ 命令行参数双通道传入）sideEffects：none | read-only | mutating（mutating 必须带 confirm 才执行）timeoutMs：超时上限，超时杀进程树resultSource：stdout-json（信封在 stdout）|result-file:<path>（信封写到文件）|none（仅退出码）
2. 执行环境约定
- Node 22，脚本以
node --experimental-strip-types直跑 TS（与五站现状一致） - cwd = 项目 repoRoot
- 注入环境变量：
EXEC_RUN_ID、EXEC_PROJECT、EXEC_TASK、EXEC_PARAMS、EXEC_CODE_SHA（执行台预查的 gitSha） - 项目自有敏感配置由服务器 env 文件注入，不进清单
3. 结构化结果信封（stdout 最后一行或 result-file）
{
"ok": true,
"task": "bagcomply:validate",
"runId": "由执行台注入，回填",
"codeVersion": { "sha": "<gitSha>", "clean": true },
"startedAt": "2026-10-24T07:22:00Z",
"finishedAt": "2026-10-24T07:24:31Z",
"durationMs": 151000,
"exitCode": 0,
"stats": { "airlinesChecked": 155, "errors": 0 },
"checks": [
{ "name": "check-refs", "ok": true },
{ "name": "check-freshness", "ok": false, "detail": "3 sources stale > 30d" }
],
"artifacts": ["data/verify-logs/xxx.json"],
"errors": []
}
规则：
ok / task / exitCode / codeVersion / stats / checks / errors为必填；stats.checks.artifacts内容各项目自由定义（业务统计不强制统一）- 失败时
ok:false，errors[]每项{code, message, hint}；code建议复用 workbench 现有 11 类失败分类（timeout / git-failed / source-unreachable …） - 兼容期约定：旧脚本不改造也能接入——无信封时执行台以退出码 + 摘要日志构造降级信封，
"envelope": "legacy"标记。这样五个站可以立即接入，再逐个升级。
4. 执行台对数据工作台暴露的 HTTP API
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /api/runs |
{project, task, params?, confirm?} → {runId}；mutating 任务无 confirm 返回 409 |
| GET | /api/runs/:id |
完整运行记录（含信封、日志路径、双版本） |
| GET | /api/runs?project&task&status&since |
过滤查询 |
| POST | /api/runs/:id/retry |
重试（复用现有实现） |
| GET | /api/projects |
列出 manifest 已注册项目与任务（含 enabled/sideEffects） |
| GET | /api/health |
{version, sha, uptime}（部署核验用） |
| POST | /api/execution-results |
（回调方向）推给数据工作台，鉴权 X-Node-Token |
5. 新项目接入步骤（目标：半天内）
- 项目仓库内确认/编写要暴露的任务脚本，输出约定信封（或先接受 legacy 降级）
- 在执行台
projects/<name>/写project.config.json+tasks.json POST /api/runs手动跑一遍验证 → 在数据工作台登记该项目- 需要调度则在数据工作台（决策侧）配置，执行台只接受请求