# Stage 5：Scenario Adapters

## 目标

为控制面提供可替换的场景适配器协议，并提供四个公共 safe-core 示例：

- `generic-project`：通用项目计划与进度；
- `developer-workspace`：开发者工作区与工程任务；
- `brandos`：品牌经营/内容运营工作区；
- `interview-learning`：Agent 岗位面试与实战训练。

核心只依赖适配器输出的公共元数据，不依赖任何一个外部项目的目录结构、
私有知识库或真实 Session。适配器必须能够被替换，不能把某个场景的字段
硬编码进 Runtime Manager 或 DSH Host 基础服务。

## Agent-Job-Interview 来源边界

Stage 5 使用公开的
[`Harzva/Agent-Job-Interview`](https://github.com/Harzva/Agent-Job-Interview)
作为第一个外部场景验证来源。公开 README 将仓库分成面试题库和实战训练，
实战训练包含 14 个主题；适配器只保留主题 ID、标题、题量、进度和来源
元数据，不复制问题、答案、HTML、代码片段或完整 `topics.json`。

来源元数据必须包括：

- 仓库 URL；
- 固定 source commit；
- release/tag（没有时省略）；
- LICENSE 状态。

当前来源树没有发现 LICENSE 文件，因此公共 fixture 使用
`license: "unknown"`。这不是对上游授权的推断；在许可证确认前，不把上游
正文或可再分发内容打包进本仓库。

## 公共协议

新增 `scenario` 合约，包含：

- `adapterId`、状态、标题和固定来源元数据；
- 关联的 `planId`、`sessionIds`、`artifactIds` 和
  `knowledgeReferenceIds`；
- 有界的主题进度摘要：ID、标题、题量、已答题量、百分比和状态；
- 有界的题集摘要：总题量、已答题量、模式和主题 ID。

新增 `src/scenarios/index.mjs` 的运行时中立接口：

- `createScenarioAdapter()`：从已验证的 metadata snapshot 创建只读适配器；
- `createGenericProjectAdapter()`；
- `createDeveloperWorkspaceAdapter()`；
- `createBrandOsAdapter()`；
- `createInterviewLearningAdapter()`。

适配器只提供 `describe()`、`getPlan()`、`getSession()`、`listTopics()`、
`getQuestionSet()`、`getProjection()` 等读取方法，没有文件扫描、网络
抓取、上传、Shell 或 Session 写入方法。

## DSH 接入

Host 增加只读 `scenarioCatalog()` 投影，Client 增加独立的 Scenario Catalog
面板。面板只展示场景、适配器、来源 commit/license、计划/Session 关系、
主题进度和题集计数。它不把外部项目正文传入 DSH Remote。

## 非目标

- 自动抓取或同步 `Agent-Job-Interview`；
- 复制上游题目、答案、招聘数据、HTML、截图或原始知识；
- 将场景适配器变成 Runtime 生命周期控制器；
- 以当前四个适配器替代通用 Provider/Bridge 协议；
- GitHub 发布、Release 或 `awesome-dsh-plugin` PR。

## 验收证据

1. 四个适配器使用同一协议，可分别构造、描述、投影和销毁；核心不依赖
   `interview-learning` 的专用逻辑。
2. Scenario 合约拒绝无来源 commit/license、超限主题/题集、原始题目正文、
   私有路径和凭据形态。
3. Interview fixture 只含主题摘要和固定来源信息；不含问题、答案、HTML、
   聊天或完整上游数据文件。
4. DSH Host/Remote/Client 的 Scenario Catalog 在隔离 Profile 中显示合成
   进度，并验证卸载、禁用和恢复。
5. `npm test`、public-safe scan、Bundle preflight、tarball dry-run、隔离
   DSH Web 冷启动和本地 DeepSeek Pro 脱敏审核全部通过。

## 状态

Stage 5 已按本文件范围完成：契约、四个适配器、DSH Scenario Catalog、合成
fixture、隔离 Web Profile 验证、禁用恢复验证和脱敏 DeepSeek Pro 审核均已记录。
Stage 6 的安全专项、Stage 7 的发布和 Stage 8 的 awesome 收录均不属于 Stage 5
范围；Stage 6 的独立完成状态以其专用规范和审核记录为准。