# Skill + Script 协同打包设计

日期：2026-07-12  
状态：设计内容已由用户分段确认，等待书面规格审阅

## 1. 背景与目标

当前项目已经具备较完整的 LaoTai/LianTai ERP 自动化运行层：微信订单解析、四类创建路由、订单修改、游客名单导入、确认件导出、审计、查重和 ERP 回查均已分散在 `tools/` 与现有部署 Skill 中。

本次整理的目标不是重新实现 ERP，而是建立清晰的协同边界：

```text
用户自然语言
  -> Skill 理解与标准化
  -> 版本化任务 JSON
  -> ERP 操作脚本
  -> 结构化执行结果
  -> Skill 生成用户回复
```

目标消费者是从共享仓库工作的 Codex 用户。Skill 负责理解输入和编排，脚本负责确定性执行，现有 `tools/` 作为 ERP 运行基础继续复用。

## 2. 非目标与约束

- 不在 Skill 中重复编写 ERP 表单选择器、ASP 接口、等待逻辑或浏览器操作。
- 不允许 agent 自己拼接 ERP endpoint、`Act`、表单字段或临时命令绕过 dispatcher。
- 不因导出、PDF 或附件交付失败而重新保存已成功的订单。
- 不把真实 ERP 保存默认化；真实执行仍要求显式授权、本地安全配置、发送人校验、查重和保存后 ERP 回查。
- 原生 `team_batch / Act=DoInfoJHs` 继续延期，生产批量行为使用已经验证的 `team_single` 回退循环。
- 游客名单附件只作为路径传给脚本；Skill/agent 不在实时下单过程中手工读取或改写工作簿。
- PDF 转换作为独立交付能力，不自动成为 API-first 创建或源文件导出流程的一部分。

## 3. 分层架构

### 3.1 Skill 层

Skill 的职责：

- 判断用户意图：创建、修改/补充、导出/恢复或维护诊断。
- 选择唯一业务路由。
- 将中文字段归一化为脚本契约字段。
- 识别缺失字段、多个匹配、多个订单块和不安全指令。
- 生成版本化任务 JSON。
- 根据脚本结果生成业务化回复。

Skill 不负责：

- 调用 ERP 页面或接口。
- 解析浏览器 DOM、拼接 ASP payload 或决定 ERP selector。
- 自行读取游客 Excel 内容。
- 通过修改 Skill 文档来绕过安全阻断。

### 3.2 脚本层

脚本的职责：

- 校验任务 JSON。
- 读取本地配置和运行时状态。
- 执行 dispatcher、路由 executor 和 browser/API 操作。
- 执行查重、submit guard、锁和保存后回查。
- 生成审计记录、ERP 编号和导出文件结果。
- 返回稳定、机器可读的结果 JSON。

脚本不负责理解未结构化的用户自然语言；需要理解时由 Skill 先生成任务 JSON。

### 3.3 现有运行层

保留以下代码作为执行基础：

- `tools/erp_task_dispatcher.js`：统一执行入口。
- `tools/erp_wechat_adapter.js`、`tools/erp_operation_adapter.js`：现有输入适配和任务构造能力。
- `tools/erp_*_executor.js`：路由编排。
- `tools/erp_*_browser_operations.js`：ERP 页面/API 操作。
- `tools/erp_submit_guard.js`、`tools/erp_order_registry.js`、`tools/erp_task_lock.js`：安全和重复保护。
- `tools/erp_operation_handlers.js`：修改、导出和恢复操作。

新增脚本应是薄封装和校验层，避免复制以上业务逻辑。

## 4. Skill 包清单

### 4.1 P0 日常业务包

| Skill | 任务范围 | 主要运行能力 |
|---|---|---|
| `erp-coordinator` | 识别输入、生成任务 JSON、选择子 Skill | `erp_wechat_adapter.js`、`erp_operation_adapter.js`、dispatcher |
| `erp-create-order` | `team_single`、`team_batch` 回退、`split_parent`、`split_child` | 四类 executor 和 browser-operation 模块 |
| `erp-update-order` | 房间/TWN、备注、组合修改、游客名单、游客行修正 | update parser、traveler list/import、路线 updateOrder |
| `erp-export-recovery` | Xingyou、Liantai、JOB、游客详情和保存后的导出恢复 | operation handlers、路线导出模块、order registry |

### 4.2 P1 底层支撑包

| Skill | 定位 | 主要运行能力 |
|---|---|---|
| `erp-runtime-safety` | 业务 Skill 必须遵守的安全规则 | submit guard、order registry、task lock |
| `erp-session-runtime` | 登录、会话、等待和异常恢复 | session guard、live session manager、interactive login、condition wait |
| `erp-diagnostics-maintenance` | 维护者专用的健康检查、接口探针、页面检查和性能诊断 | deployment health check、API probes、inspect/performance tools |

### 4.3 P2 可选交付包

| Skill | 定位 | 主要运行能力 |
|---|---|---|
| `erp-pdf-delivery` | 独立 PDF 转换和附件交付 | `erp_pdf_conversion.js`、PDF 转换脚本 |

`deploy/hermes-travel-erp-api-order-operator/SKILL.md` 暂时作为兼容版本保留；Codex 使用的新主版本放在仓库的 `skills/` 目录。

## 5. 统一任务 JSON 契约

### 5.1 通用外壳

```json
{
  "status": "ready",
  "operation": "create_order",
  "route": "team_single",
  "task": {
    "schemaVersion": "erp-task-v1",
    "taskId": "task-20260712-001",
    "operation": "create_order",
    "route": "team_single",
    "fields": {},
    "updatePlan": {},
    "attachments": [],
    "originalText": "",
    "delivery": {}
  }
}
```

要求：

- `schemaVersion` 必填，后续契约变化不得静默破坏旧脚本。
- `operation` 与 `route` 必须匹配。
- 日期统一为 `YYYY-MM-DD`。
- 人数、房间数不得为负数；价格字段按现有业务规则处理正负调整。
- `attachments` 只传路径和附件元数据，不把工作簿内容塞入 Skill 输出。
- `originalText` 保留原始指令，供安全检查和审计使用。
- sender、chat、生产配置和密码不由 Skill 伪造；授权仍由调用参数和本地配置控制。

`dry-run`/`execute` 是脚本调用参数，与业务字段分离。Skill 只有在用户明确要求真实操作时才可选择 `execute`，脚本仍必须再次执行本地安全检查。

### 5.2 创建任务

```json
{
  "operation": "create_order",
  "route": "team_single",
  "fields": {
    "orderNature": "",
    "bookingCustomer": "",
    "productName": "",
    "departureDate": "YYYY-MM-DD",
    "pax": {},
    "rooms": {},
    "prices": {},
    "op": "",
    "salesperson": "",
    "remark": ""
  },
  "attachments": []
}
```

路由字段：

- `team_single`：单日期、客户、产品、人数、房型、价格、OP、销售。
- `team_batch`：客户、单产品、多 `departureDates`、默认人数/房型/价格、OP、跟单人、销售和特殊日期调整；脚本按日期使用 `team_single` 回退。
- `split_parent`：线路、日期范围、周期、计划人数、每日期母团数、跟团人。
- `split_child`：母团号或线路、出发日期、渠道客户、人数、价格、OP、销售和补充字段。

### 5.3 修改/名单任务

```json
{
  "operation": "update_order",
  "identifier": "LW-270520A-A",
  "updatePlan": {
    "status": "ready",
    "actions": [
      {
        "target": "rooms.TWN",
        "operation": "set",
        "value": 10
      },
      {
        "target": "remark",
        "operation": "append",
        "value": "客户备注"
      }
    ],
    "supplemental": {}
  },
  "attachments": ["C:\\path\\traveler-list.xls"]
}
```

支持已验证的房间/TWN、备注、组合修改、游客名单导入和游客行修正；价格/人数修改仍按“可选、需单独验证”处理。

名单附件由脚本解析、校验、导入并验证填充行增长；Skill 只表达“把此附件补充到该订单”。

### 5.4 导出/恢复任务

```json
{
  "operation": "export_confirmation",
  "identifier": "LW-270520A-A",
  "exportTypes": ["xingyou-confirm"],
  "recovery": {
    "exportOnly": true,
    "neverResave": true
  }
}
```

默认导出 Xingyou 源文件；Liantai、JOB/备案和游客详情必须由用户明确提出。母团不能直接导出客户确认件。导出失败后只允许继续导出/恢复阶段。

## 6. Skill 触发脚本流程

```text
用户输入
  -> 子 Skill 解析
  -> 生成 task.json
  -> validate_erp_task.js
  -> run_erp_task.js
  -> tools/erp_task_dispatcher.js
  -> 路由 executor
  -> ERP
  -> 结果 JSON
  -> Skill 生成回复
```

统一脚本入口：

```powershell
node scripts\validate_erp_task.js --task <task.json> --json
node scripts\run_erp_task.js --task <task.json> --mode dry-run --config config\erp-deployment.local.json --json
```

业务包可以提供薄封装：

```text
erp-create-order      -> run_create_order.js
erp-update-order      -> run_update_order.js
erp-export-recovery   -> run_export_recovery.js
```

薄封装只校验 operation/route、调用统一 runner 和返回 JSON，不复制 ERP 逻辑。

## 7. 状态、错误与恢复

统一状态：

| 状态 | 处理 |
|---|---|
| `needs_clarification` | 缺字段或有歧义；不调用 ERP |
| `invalid_task` | JSON 不符合契约；不调用 ERP |
| `blocked` | 查重、安全、配置或业务规则阻断；不写 ERP |
| `dry_run` | 计划已验证；不做真实保存 |
| `completed` | 执行完成且 ERP 已回查 |
| `post_save_recovery_required` | 已保存但导出/附件失败；只走恢复 |
| `execution_uncertain` | 保存状态未知；先查询，禁止盲目重试 |

结果最少包含：

```json
{
  "status": "completed",
  "saveState": "saved_verified",
  "identifiers": {},
  "artifacts": [],
  "auditPath": "",
  "nextAction": ""
}
```

Skill 对外只输出业务信息，不输出命令、内部路径、堆栈、接口、浏览器诊断、审计细节或游客隐私。

## 8. 测试与验收

### 8.1 测试层级

1. Skill 契约测试：自然语言 -> 预期任务 JSON。
2. 脚本单元测试：Schema、路由匹配、安全阻断、结果结构。
3. Dispatcher 集成测试：任务 JSON -> 正确 executor；dry-run 不产生 ERP 写入。
4. 无 ERP 回归：`npm test`、`npm run health:no-erp`。
5. 真实 ERP 测试：明确授权后使用非关键订单，做 dry-run、真实执行和 ERP 回查。
6. 恢复回归：保存后导出/附件失败时不重复创建订单。

### 8.2 每包交付标准

- 至少 3 个正常输入样例。
- 至少 3 个缺字段、歧义或安全阻断样例。
- JSON 能通过统一校验。
- 脚本返回结构化结果。
- 默认 dry-run，真实执行必须有授权和本地配置。
- 保存成功后的恢复路径可单独重跑。
- 审计记录对游客隐私自动脱敏。
- 用户回复不暴露内部实现细节。

每个包至少交付：`SKILL.md`、Schema、正常样例、异常样例、脚本调用示例、预期结果 JSON 和回归测试。

## 9. 协同分工与落地顺序

### Skill 维护者

- 编写触发条件、中文理解规则和字段映射。
- 维护任务 JSON 样例与缺字段/歧义话术。
- 编写 Skill 契约测试。

### 脚本维护者

- 实现 Schema 校验、薄封装和 dispatcher 调用。
- 维护 ERP executor、浏览器/API 操作、查重和回查。
- 编写单元、集成和无 ERP 测试。

### 建议顺序

1. 建立共享 Schema 和 `validate_erp_task.js`。
2. 建立 `erp-coordinator`，先接入现有 adapter。
3. 完成 `erp-create-order` 四路由包。
4. 完成 `erp-update-order` 和游客附件契约。
5. 完成 `erp-export-recovery` 源文件导出和恢复。
6. 整理安全/会话/诊断支撑包。
7. 最后拆出 PDF 交付包并验证与 API-first 边界。

## 10. 结构化文档与交接规范

Skill 和脚本之外，最终交付必须包含可供伙伴接手的结构化文档层：

```text
docs/erp-skill-packages/
├── overall-overview.md
├── complete-handoff.md
├── templates/
│   └── business-handoff-template.md
└── businesses/
    ├── create-order.md
    ├── update-traveler.md
    ├── export-recovery.md
    ├── safety-session.md
    └── diagnostics-pdf.md
```

### 整体说明文档

`overall-overview.md` 解释整体架构、Skill/脚本边界、任务 JSON 生命周期、包清单、运行入口、测试入口和状态含义。它回答“系统由什么组成、一次任务怎样运行、伙伴应该从哪里开始”。

### 完整交接文档

`complete-handoff.md` 记录当前可用能力、每个业务包的状态、已验证证据、未验证能力、已知阻断、恢复路径、协同分工、部署前检查和下一步。它回答“下一位伙伴如何从当前状态继续工作”。

### 业务交接文档

每个业务文档必须遵循同一模板，至少包含：

1. 业务目标和触发语句。
2. Skill 负责的理解与标准化规则。
3. 任务 JSON 示例和字段说明。
4. 对应脚本入口与现有 `tools/` 执行模块。
5. 成功结果、阻断结果和恢复结果。
6. 测试样例、证据链接和当前验证状态。
7. 风险、禁止事项、负责人和下一步。

单个 ERP 订单不再复制一份长篇交接文档；订单级事实通过任务 JSON、审计 JSON、订单 registry 和输出 artifact 管理，并由业务交接文档链接其规则和证据。

## 11. 未决事项

- 当前工作区的 `.git` 目录不是可用 Git 仓库，无法提交设计文档或运行 Git 漂移检查；需要后续修复仓库或在真正的 Git 仓库中提交。
- `skills/` 将作为 Codex 主目录，是否同步生成其他部署端 wrapper 不在本轮范围内。
- 既有 `deploy/` Skill 的淘汰时间需要在实现完成并通过回归后再决定。