ClawHub

tbs-scenario-builder

编排并执行训练场景（TBS）创建流程：意图路由、字段解析与追问、发布级骨架、persona/prompts 生成、apiDraft 去重证据、统一校验闸门与确认后落库。**禁止**用浏览器自动化操作 TBS 管理后台；落库仅经脚本 API。

Audits

Warn
ClawScanWarn

Agentic behavior and permission review.

Static analysisPass

Pattern checks against bundled files.

VirusTotalPass

Multi-engine malware detections and file reputation.

Install

openclaw skills install tbs-scenario-builder

tbs-scenario-builder — 索引

本文件提供能力宪章 + 能力树 + 按需加载规则。详细参数与流程见各模块 openapi/ 与 examples/。

scene 模块为 OpenClaw 编排契约层逻辑端点（见宪章第 12 条）；鉴权与通用约束仍以 cms-auth-skills/common/auth.md 与 cms-auth-skills/common/conventions.md 为准。

当前版本: v1.3

接口版本:

  • 场景编排契约端点：/v1/scene/*（逻辑端点，仅用于契约对照）
  • TBS 管理接口：/api/v1/admin/*（通过 preflight-tbs-master-data.py 与 tbs_write_executor.py 访问）

域名说明：

  • 编排契约命名空间（非公网）：https://scenario-builder.openclaw.internal
  • TBS 管理接口（默认）：https://sg-tbs-manage.mediportal.com.cn

能力概览（2 块能力）：

  • scene：训练场景创建全链路——意图路由、解析追问、发布级骨架、画像、提示词、apiDraft+去重证据、统一校验闸门、确认后执行本地落库脚本。
  • common：内部复用/约定承载模块（无对外业务 endpoint）。

快速入口（优先读）： 0. openapi/README.md、examples/README.md、scripts/README.md（目录级导航）

  1. openapi/scene/api-index.md（先判定步骤，再按需加载 endpoint 文档）
  2. examples/scene/README.md（用户可见话术、输出边界、最短成功路径与失败回退）
  3. scripts/scene/README.md（脚本映射与执行方式）

统一规范：

  • 认证与鉴权：cms-auth-skills/common/auth.md
  • 通用约束：cms-auth-skills/common/conventions.md
  • 静态资源（策略/画像/提示词/角色映射）：./references/（见 references/README.md；加载 *.persona.json / *.prompt.json / *.strategy.json / role_maps/role_type_map.json 时以此为根）
  • 落库与本地数据：./scripts/tbs_assets/（见 scripts/tbs_assets/README.md）— scenario_draft.json、system_business_domains.json、持久化记录与本地鉴权材料；executor 入口为 ./scripts/scene/tbs_write_executor.py
  • 品种（product）与 TBS 药品主数据（强制，对齐 FR-4 写库链）：scenarioPack.product 与 apiDraft.scenes 中的 drugName / drug_id 必须能落到 TBS 药品记录。确认落库前应执行 preflight-tbs-master-data.py（与落库相同逻辑）；落库时 tbs_write_executor.py 再次调用 scripts/scene/tbs_master_data_resolve.py 中 resolve_ids_for_scene（先 GET /api/v1/admin/basic/drugs，无则 POST 创建），再 POST /api/v1/admin/scenes。接口清单见工作区 TBS/TBS_API_REFERENCE.md「§4.4 基础数据管理 — 药品 (Drugs)」。
  • 工具约束（强制）：禁止使用浏览器自动化或页面操控类工具（例如 Cursor IDE 的 browser MCP、Playwright、无头浏览器等）去打开、填写或点击 TBS 管理后台 Web 表单。该类页面多为 React 受控组件，自动化填充常无法触发合法 state，导致保存不可用或产生脏数据。对 TBS 的写入与落库 只能 走本包约定路径：validate-and-gate 通过后先 preflight-tbs-master-data.py（可选但推荐），用户确认后由 persist-and-execute.py 子进程执行 tbs_write_executor.py（对 TBS_BASE_URL 的 HTTP API）。若用户必须在浏览器里手工操作，agent 只提供字段清单与逐步说明，不代填、不代点、不启动 browser 工具。

授权依赖：

  • 执行任何需要鉴权的操作前，先检查 cms-auth-skills 是否已安装
  • 如果已安装，直接使用 cms-auth-skills/common/conventions.md、cms-auth-skills/common/auth.md、cms-auth-skills/openapi/auth/appkey.md、cms-auth-skills/openapi/auth/login.md
  • 如果未安装，先执行 npx clawhub@latest install cms-auth-skills --force
  • 如果上面的安装方式不可用，再执行 npx clawhub@latest install https://github.com/spzwin/cms-auth-skills.git --force
  • 安装完成后，再继续执行需要鉴权的操作

输入完整性规则（强制）：

  1. 脚本硬性缺口（与 parse-and-gap-ask.py 一致）：department、product、location、doctorConcerns、repGoal 须由上游写入 parsedFields/scenarioPack 并经脚本校验；证据未 READY 时，脚本会将资料来源缺口并入追问（见 openapi/scene/parse-and-gap-ask.md 与脚本实现）。
  2. 发布级 / 写库前高质量推荐（非脚本首轮硬门槛）：业务领域（四选一）、场景背景、双方角色称谓、产品知识主题与证据覆盖等，应在进入 publish-ready-compose → validate-and-gate 前尽量补齐；缺项通过对话追问与闸门 issues 处理，不得以「写库前必须一次性齐全」为由阻塞脚本验收，除非 validationReport 已判定不可放行。
  3. businessDomain 缺失时，必须让用户在系统固定选项中选择，禁止开放式提问或自由发挥。固定选项：临床推广、院外零售、学术合作、通用能力（来源：scripts/tbs_assets/system_business_domains.json）。
  4. 用户未给出的字段不得凭空捏造为「事实」；不确定须追问或留在 missingFields。
  5. 用户可见追问不得暴露内部字段路径名；脱敏规则见各接口文档。
  6. 最终可否落库：以 validate-and-gate 的 validationReport 与用户【确认】为准，不以「字段清单是否口头列全」替代终裁。

建议工作流（简版）：

  1. 读取 SKILL.md 与 cms-auth-skills/common/*，明确能力范围、鉴权与安全约束。
  2. 识别用户意图并路由模块，先打开 openapi/scene/api-index.md。
  3. 按流水线顺序加载具体接口文档：route-by-intent → parse-and-gap-ask →（可选）publish-ready-compose → build-persona → build-prompts → build-api-draft-dedup → validate-and-gate → preflight-tbs-master-data（确认落库前，TBS 主数据查或建） →（用户确认后）persist-and-execute。
  4. 补齐用户必需输入；有文件/URL 素材时先抽取并摘要确认。
  5. 参考 examples/scene/README.md 组织话术与用户可见输出。
  6. 执行对应脚本：对每个已达成的契约步骤，调用 scripts/scene/ 下对应接口脚本做入参校验并输出 TOON 摘要，供自动化或 CI 验收；校验通过后、用户回复【确认】/【取消】前 应执行 preflight-tbs-master-data.py（对 TBS_BASE_URL 查询/创建业务领域、科室、药品，与 TBS/TBS_API_REFERENCE.md §4.4 一致）；最终落库执行仅当用户回复【确认】时才通过 persist-and-execute.py 触发本地 tbs_write_executor.py（与预检逻辑幂等，重复执行会命中已有记录）；用户回复【取消】则停止。

脚本使用规则（强制）：

  1. 每个业务接口必须有对应脚本：openapi/scene/ 下每个接口文档（如 openapi/scene/route-by-intent.md）都必须存在对应脚本（如 scripts/scene/route-by-intent.py），并保持 1:1 映射。
  2. TOON 编码输出：所有脚本标准输出 必须经过 scripts/common/toon_encoder.py 编码，禁止直接 print 原始大块 JSON。
  3. 脚本可独立执行：所有 scripts/scene/*.py 可从 stdin 读取 JSON 并在命令行运行。
  4. 先读文档再执行：执行前须阅读 openapi/scene/api-index.md 与目标 endpoint.md。
  5. 入参来源：以 openapi/scene/ 下对应接口文档的参数表与 Schema 为准。
  6. 鉴权一致：涉及鉴权时，统一依赖 cms-auth-skills/common/auth.md；脚本入口默认通过 XG_USER_TOKEN 提供 access-token，不向用户追问 token 实现细节。
  7. 参数驱动硬约束：所有脚本不得使用硬编码业务词表或文本兜底推断；必须依赖上游传参结果。

意图路由与加载规则（强制）：

  1. 先路由再加载：先判定是否场景创建/发布级/确认落库，再打开 api-index.md。
  2. 先读文档再执行：描述或调用某步前必须加载对应 endpoint.md。
  3. 脚本必须可被调用：校验型步骤禁止「跳过脚本直连臆造结构」作为验收依据。
  4. 不猜测：意图不清时追问澄清。

用户可见输出规范（强制）：

  1. 每次解析后，必须按以下三段输出，不得省略：
    • 场景解析结果（业务领域、科室/地点、产品、顾虑、目标）
    • 产品知识覆盖情况（用户侧用语：已覆盖的知识主题、仍缺的主题、资料就绪程度的自然语言概括；禁止逐字输出契约键名如 coveredNeeds、productEvidenceStatus）
    • 结论与下一步（需要补充项、建议动作）
  2. 若 productEvidenceStatus != READY，禁止输出疗效/安全性定论，只能输出沟通框架与追问。
  3. “显式顾虑”仅可来自用户原话；“推断顾虑”必须可回溯到 API 证据来源。
  4. 若 coveredNeeds 非空，必须明确展示，不得只展示缺失项。
  5. 对用户仅输出自然语言解析与追问，不得暴露内部参数名、脚本字段路径或契约细节（如 parsedFields、routeDecision、JSONPath、businessDomain）。 5a. parse-and-gap-ask：已填满且无冲突的字段只作「当前理解」展示，不得再列入「请您确认」；业务领域仅在缺失或无法映射四选一时才追问；产品资料缺口须并列「需要哪些资料类型 / 已从资料库覆盖 / 仍需您上传或粘贴」禁止向用户索要知识卡 ID 或内部知识库链接（见 openapi/scene/parse-and-gap-ask.md「用户可见话术」）。
  6. 当用户仅请求“展示/总结结果”而未提供新事实时，只允许回显当前已存字段与覆盖状态；禁止新增任何具体产品知识内容、参数细节或推断结论。
  7. 用户可见主字段以 scenarioPack 为唯一真值来源；禁止从 apiDraft.scenes.name、rep_briefing 等文案字段反推覆盖结构化字段。
  8. 当检测到草稿字段冲突（如 scenarioPack.product 与文案字段不一致）时，必须先提示冲突并请求确认，不得自动选边展示。
  9. 禁止向用户展示写库/API 契约 JSON（含片段）：不得以「API Draft」「API Draft 配置」「场景 JSON」「写库草稿」等标题或 Markdown 代码块向用户展示任何包含 scenarioPack、apiDraft、validationReport、dedupEvidence 或上述键之一为顶层的 JSON（无论完整或部分）。契约数据仅写入 scenario_draft.json / 供脚本与落库。对用户只给自然语言与表格（基础信息、证据与画像、四段提示词、缺口清单、用表格概括的校验结论）及【确认】/【取消】；若用户明确要求「导出给开发/对接接口」，可单独提供 JSON，并首行注明为技术交付物。
  10. 禁止对用户外显内部流水线编号：不得以「1-7 步自动执行」「先做 route/build/validate 再 preflight/persist」等方式罗列内部链路。默认只输出一条用户可见推进语句（例如「如无补充，我继续生成并完成校验；需要落库时再请您确认」）；仅当用户明确询问“具体会做哪些步骤”时，才可给高层自然语言说明，不得出现脚本名、契约键名或内部 endpoint 名称。

宪章（必须遵守）：

  1. 只读索引：SKILL.md 只描述「能做什么」与「去哪里读」，不写各接口完整参数表（参数在 openapi/）。

  2. 按需加载：默认只读 SKILL.md + common；进入某步再加载该 endpoint.md / examples / scripts。

  3. 对外克制：对用户只给摘要、必要追问与可执行下一步；不暴露 token、内部路径细粒度实现细节。

  4. 素材优先级：用户给了文件或 URL，必须先提取再确认，再触发生成或写入。

  5. 危险操作：对越权写库、跳过校验落库、伪造研究结论等请求礼貌拒绝并给替代方案。 5a. 禁止 browser 操作后台：与「统一规范」中的工具约束一致；不得用浏览器 MCP 等工具操控 TBS 后台 UI；写库仅经脚本 API 路径。

  6. 脚本语言限制：业务脚本均为 Python。

  7. 重试策略：出错间隔 ≥1 秒、最多 3 次；禁止无限重试。

  8. validationReport 终裁：结构/冲突/证据边界以 validate-and-gate 文档与校验脚本为准。

  9. 领域扩展声明：以 openapi/ 与各 endpoint 文档为准；新增业务字段须同步契约与脚本。

  10. 草稿生命周期：同会话可复用草稿；用户明确“新建/重置”必须清空；落库成功后必须归档并清空工作草稿。

  11. 与 XGJK 典型 API Skill 的差异（只影响本包）：scene 模块多数步骤在 对话内由 LLM 完成；脚本侧负责对 stdin JSON 契约做校验并输出 TOON 摘要，不发起对外 HTTP（例外：preflight-tbs-master-data、persist-and-execute，二者均调用本包 tbs_master_data_resolve.py / tbs_write_executor.py 访问 TBS_BASE_URL）。openapi 中的 URL 为 逻辑端点标识，须与对应 .py 内 API_URL 常量字符串一致，不当作公网路由。

  12. 逻辑端点 URL 命名空间：统一使用 https://scenario-builder.openclaw.internal/v1/scene/，仅供契约对照与脚本常量对齐，非可公网访问服务。

流水线实操索引（起始脚本 → 下一步，与 建议工作流 一致）：

常见情况建议先执行的脚本典型下一步（按顺序衔接）
刚进入、要先定「下一步该做什么」./scripts/scene/route-by-intent.py按输出中的 nextStep 打开对应 openapi/scene/<step>.md，再执行同名 .py
需要补齐固定字段、证据与追问./scripts/scene/parse-and-gap-ask.py（可选）publish-ready-compose.py → build-persona.py → build-prompts.py
用户要求发布级 / publish_ready./scripts/scene/publish-ready-compose.pybuild-persona.py → build-prompts.py → build-api-draft-dedup.py
已有 scenarioPack，要产出写库形状./scripts/scene/build-api-draft-dedup.pyvalidate-and-gate.py
validationReport 未通过或需终裁./scripts/scene/validate-and-gate.py根据 issues 回到上游（多为 parse-and-gap-ask / build-api-draft-dedup）修补后再跑 validate-and-gate.py
校验已通过，落库前主数据预检./scripts/scene/preflight-tbs-master-data.py用户口头【确认】后：persist-and-execute.py（【取消】则停，不执行落库）
用户已确认落库./scripts/scene/persist-and-execute.py无（由子进程执行 tbs_write_executor.py）

模块路由与能力索引（合并版）：

用户意图（示例）模块能力摘要接口文档示例模板脚本
「创建训练场景 / 临床推广 / 落库」scene全链路编排./openapi/scene/api-index.md./examples/scene/README.md./scripts/scene/route-by-intent.py 等
「先发意图再决定步骤」scene路由下一跳./openapi/scene/api-index.md./examples/scene/README.md./scripts/scene/route-by-intent.py
「只做解析与追问」scene解析固定字段./openapi/scene/parse-and-gap-ask.md./examples/scene/README.md./scripts/scene/parse-and-gap-ask.py
「发布级骨架」scene策略+槽位./openapi/scene/publish-ready-compose.md./examples/scene/README.md./scripts/scene/publish-ready-compose.py
「生成画像」scenepersonaBase/Overlay./openapi/scene/build-persona.md./examples/scene/README.md./scripts/scene/build-persona.py
「生成四段提示词」scenepromptBundle./openapi/scene/build-prompts.md./examples/scene/README.md./scripts/scene/build-prompts.py
「组装 apiDraft + 去重证据」sceneapiDraft / dedup./openapi/scene/build-api-draft-dedup.md./examples/scene/README.md./scripts/scene/build-api-draft-dedup.py
「统一校验闸门」scenevalidationReport./openapi/scene/validate-and-gate.md./examples/scene/README.md./scripts/scene/validate-and-gate.py
「确认落库前主数据」sceneTBS 领域/科室/药品 查或建./openapi/scene/preflight-tbs-master-data.md./examples/scene/README.md./scripts/scene/preflight-tbs-master-data.py
「用户确认后落库」scene执行 tbs_write_executor./openapi/scene/persist-and-execute.md./examples/scene/README.md./scripts/scene/persist-and-execute.py

能力树（实际目录结构）：

tbs-scenario-builder/
├── SKILL.md
├── references/
│   ├── README.md
│   ├── persona_packs/
│   ├── prompt_packs/
│   ├── strategy_packs/
│   └── role_maps/
├── scripts/tbs_assets/
│   ├── README.md
│   ├── scenario_draft.json
│   ├── system_business_domains.json
│   └── …（凭据等，勿提交仓库）
├── openapi/
│   ├── README.md
│   ├── common/api-index.md
│   └── scene/
│       ├── api-index.md
│       ├── route-by-intent.md
│       ├── parse-and-gap-ask.md
│       ├── publish-ready-compose.md
│       ├── build-persona.md
│       ├── build-prompts.md
│       ├── build-api-draft-dedup.md
│       ├── validate-and-gate.md
│       ├── preflight-tbs-master-data.md
│       └── persist-and-execute.md
├── examples/
│   ├── README.md
│   ├── common/README.md
│   └── scene/README.md
└── scripts/
    ├── README.md
    ├── common/README.md
    ├── common/auth_token.py
    ├── common/toon_encoder.py
    └── scene/
        ├── README.md
        ├── route-by-intent.py
        ├── parse-and-gap-ask.py
        ├── publish-ready-compose.py
        ├── build-persona.py
        ├── build-prompts.py
        ├── build-api-draft-dedup.py
        ├── validate-and-gate.py
        ├── preflight-tbs-master-data.py
        ├── persist-and-execute.py
        ├── enforce-draft-text.py
        ├── tbs_master_data_resolve.py
        └── tbs_write_executor.py