# 业务模板调试边界

本文是服务通知和多任务管理共用的生命周期与调试规则。只要本轮涉及 `business-templates.yaml`、Sandbox Session、模板同步、制品上传或真机调试，必须先区分下面四种动作，再读取具体能力文档。

## 先区分四种动作

| 动作 | 触发方式 | 内容与目的 | 是否改变持久化的平台模板 |
| --- | --- | --- | --- |
| Session 创建/重建 | 启动 `dbx dev` 后由模拟器链路创建 Session，或在 Web 调试面板点击“撤回并重建 session” | 将当前 Manifest 和可选业务模板放入临时 Sandbox Session 请求，供模拟器验证 | 否；不能据此推断正式或草稿模板已同步 |
| 模板单独同步 | `dbx app artifacts upload --business-templates-only` | 只校验并同步业务模板，不提交新的前端、Manifest 或 Skill 版本 | 是；以逐模板同步结果为准 |
| 完整制品上传 | `dbx app artifacts upload` | 上传 Manifest、Skill、前端资源和可选业务模板，并触发后续构建流程 | 是；模板是否成功仍以逐模板同步结果为准 |
| 真机调试包上传 | `dbx dev` 的真机调试工具链 | 上传该次真机调试所需的 Manifest、前端资源及其它调试产物 | 不等同于模板单独同步或正式制品上传 |

后文避免单独使用“模板已上传”描述结果；必须写明属于以上哪一种动作。

## 文件位置和路径解析

标准项目布局为：

```text
<project>/
├── manifest.yaml
└── business-templates.yaml   # 可选
```

各命令的路径规则不同：

| 命令 | 项目参数 | Manifest / 模板默认位置 | 相对路径基准 |
| --- | --- | --- | --- |
| `dbx dev` | `--project-path`，默认当前目录 | Manifest 默认是 `<project>/manifest.yaml`；业务模板默认是**解析后的 Manifest 同目录**下的 `business-templates.yaml` | `--manifest`、`--skill` 相对 `--project-path` 解析 |
| `dbx simulator eval` | `--project-path`，默认当前目录 | 默认读取项目目录下的 Manifest 和 Skill | 相对路径参数按 `--project-path` 解析 |
| `dbx app artifacts upload` | `--project`，默认当前目录 | 完整上传默认读取项目根目录的 `business-templates.yaml` | `--business-templates` 相对 `--project` 解析 |

因此，使用自定义 Manifest 路径时必须显式对齐本地调试和完整上传。例如 Manifest 为 `configs/manifest.yaml`：

```bash
dbx dev --manifest configs/manifest.yaml --mcp-endpoint <mcp_endpoint>

dbx app artifacts upload \
  --project <project_root> \
  --manifest configs/manifest.yaml \
  --business-templates configs/business-templates.yaml
```

不要把 `--project` 和 `--project-path` 互换，也不要假设所有相对路径都按当前目录解析。

## 文件缺省、移除和远端状态

- `dbx dev` 找不到 Manifest 同目录的 `business-templates.yaml` 是合法状态，表示新建的本地 Sandbox Session 不携带业务模板。
- 完整制品上传找不到项目根目录的 `business-templates.yaml` 时会跳过模板同步；这不表示删除或清空平台已有模板。
- 从 YAML 中移除某个模板也不表示删除或下线远端模板。删除或下线必须使用平台明确提供的管理操作。
- 业务模板是应用级资源；不要推断上传新版本或回滚应用版本会自动恢复某一版模板。

## 两级校验

本地开发与正式上传的校验门槛不同：

| 校验 | 使用位置 | 含义 |
| --- | --- | --- |
| 兼容校验 | `dbx dev` 启动预检、`dbx app artifacts validate` | 尽早发现结构和兼容性问题，适合本地开发 |
| 严格校验 | 模板单独同步、完整制品上传 | 正式进入平台模板同步前的最终门槛 |

兼容校验通过不保证严格校验一定通过。正式上传失败时，应以严格校验返回的 `code`、`path` 和逐模板结果为准。

必须遵守：

- 模拟器调试中，创建 Sandbox Session 的请求会携带当前 Manifest 和可选 `business-templates.yaml`。已有 Session 不会因为只修改本地 YAML 就自动获得新模板；模板变化后应按 CLI 支持的流程重新创建 Session。
- `dbx dev` 启动时会自动发现解析后 Manifest 同目录的可选 `business-templates.yaml`。文件存在时必须非空并通过兼容校验；文件不存在表示本次 Session 不配置业务模板。
- `dbx dev` 的自动兼容校验只发生在启动预检阶段。启动后修改业务模板，再点击“撤回并重建 session”不会自动重新运行这次 CLI 校验；必须先手动执行 `dbx app artifacts validate <business-templates.yaml路径> --type business-templates --json`，再重建 Session。仅刷新 Web 页面或点击“刷新资源并重载卡片”也不会更新已有 Session。
- Sandbox Session 由 CLI/平台模拟器链路创建和管理。Agent 和业务代码都不得调用私有接口手工创建 Session，不得自行构造、替换或持久化 Sandbox Session 凭证。
- 真机调试中，`business-templates.yaml` 必须跟随当前工具链要求与本次使用的 Manifest、前端资源及其它产物一起处理。只做模板单独同步，不能替代真机调试包上传。
- Session 创建/重建不等于真机调试包上传；模拟器验证通过也不等于真机调试通过。报告结果时必须明确写“模拟器调试”或“真机调试”。
- `--business-templates-only` 只用于明确的模板独立同步场景，不用于创建模拟器 Sandbox Session，也不用于代替真机调试整包上传。
- 如果当前 CLI 没有提供目标阶段所需的公开命令或返回了不支持错误，应报告该阶段受阻；不得绕过 CLI 调用私有 Session、模板或调试接口。

## 身份边界

- 模拟器中的用户身份和 Session 凭证只能来自平台模拟器链路实际注入的请求上下文。
- 缺少 OpenID、`X-DB-SessionToken` 或目标接口要求的可信身份时，停止对应调用并报告缺失项；不得使用固定用户、localhost 默认用户、伪造 Header 或其它 fallback 冒充已登录用户。
- 不得仅为了让通知或任务调用通过而增加用户信息权限。只有真实业务能力需要且用户同意时，才按认证和数据合规文档申请对应权限。
- 直接调用底层 OpenAPI 只能作为接口诊断，不能代替模拟器或真机的端到端验证，也不能证明平台实际注入了用户身份。

## 分层记录验证结果

不要用一个“成功”概括全部链路。至少分别记录：

1. `business-templates.yaml` 结构校验。
2. 当前阶段的请求或同步结果：Session 创建只记录文件是否加入请求和 Session 是否创建成功；模板单独同步、完整制品上传则检查逐模板结果。
3. 业务事件或 MCP 调用结果。
4. 通知发送或任务创建、更新的 OpenAPI 业务结果。
5. 模拟器或真机中的用户侧展示结果。

上一步通过不能自动推断下一步通过。只有确实观察到用户侧展示时，才把第五项写为 `PASS`。

推荐输出：

```text
调试阶段：模拟器调试
模板结构：PASS
Manifest 已加入 Session 创建请求：PASS
business-templates.yaml 已加入 Session 创建请求：PASS
Sandbox Session 创建：PASS
平台模板解析/持久化：NOT VERIFIED，Session 创建结果未提供逐模板同步结果
业务调用：PASS
平台接口：PASS
用户侧展示：NOT VERIFIED，当前没有观察到可确认的展示入口
```

## 用户侧展示能力

模拟器创建 Session、模板同步成功或平台接口返回成功，都不代表模拟器一定提供通知收件箱或任务展示入口。只有当前版本明确支持该入口并实际观察到结果时，才能声明“模拟器可见”。

若当前模拟器不提供对应入口，应将用户侧展示标记为 `UNSUPPORTED`；无法确认能力时标记为 `NOT VERIFIED`。不得为了得到可见结果而改用伪造身份、手工 Session 或另一条调试链路。