13 KiB
13 KiB
Skill + Script 协同打包设计
日期：2026-07-12
状态：设计内容已由用户分段确认，等待书面规格审阅
1. 背景与目标
当前项目已经具备较完整的 LaoTai/LianTai ERP 自动化运行层：微信订单解析、四类创建路由、订单修改、游客名单导入、确认件导出、审计、查重和 ERP 回查均已分散在 tools/ 与现有部署 Skill 中。
本次整理的目标不是重新实现 ERP，而是建立清晰的协同边界：
用户自然语言
-> 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 通用外壳
{
"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 创建任务
{
"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 修改/名单任务
{
"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 导出/恢复任务
{
"operation": "export_confirmation",
"identifier": "LW-270520A-A",
"exportTypes": ["xingyou-confirm"],
"recovery": {
"exportOnly": true,
"neverResave": true
}
}
默认导出 Xingyou 源文件；Liantai、JOB/备案和游客详情必须由用户明确提出。母团不能直接导出客户确认件。导出失败后只允许继续导出/恢复阶段。
6. Skill 触发脚本流程
用户输入
-> 子 Skill 解析
-> 生成 task.json
-> validate_erp_task.js
-> run_erp_task.js
-> tools/erp_task_dispatcher.js
-> 路由 executor
-> ERP
-> 结果 JSON
-> Skill 生成回复
统一脚本入口：
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
业务包可以提供薄封装：
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 |
保存状态未知；先查询，禁止盲目重试 |
结果最少包含：
{
"status": "completed",
"saveState": "saved_verified",
"identifiers": {},
"artifacts": [],
"auditPath": "",
"nextAction": ""
}
Skill 对外只输出业务信息，不输出命令、内部路径、堆栈、接口、浏览器诊断、审计细节或游客隐私。
8. 测试与验收
8.1 测试层级
- Skill 契约测试：自然语言 -> 预期任务 JSON。
- 脚本单元测试：Schema、路由匹配、安全阻断、结果结构。
- Dispatcher 集成测试：任务 JSON -> 正确 executor；dry-run 不产生 ERP 写入。
- 无 ERP 回归：
npm test、npm run health:no-erp。 - 真实 ERP 测试：明确授权后使用非关键订单，做 dry-run、真实执行和 ERP 回查。
- 恢复回归：保存后导出/附件失败时不重复创建订单。
8.2 每包交付标准
- 至少 3 个正常输入样例。
- 至少 3 个缺字段、歧义或安全阻断样例。
- JSON 能通过统一校验。
- 脚本返回结构化结果。
- 默认 dry-run，真实执行必须有授权和本地配置。
- 保存成功后的恢复路径可单独重跑。
- 审计记录对游客隐私自动脱敏。
- 用户回复不暴露内部实现细节。
每个包至少交付：SKILL.md、Schema、正常样例、异常样例、脚本调用示例、预期结果 JSON 和回归测试。
9. 协同分工与落地顺序
Skill 维护者
- 编写触发条件、中文理解规则和字段映射。
- 维护任务 JSON 样例与缺字段/歧义话术。
- 编写 Skill 契约测试。
脚本维护者
- 实现 Schema 校验、薄封装和 dispatcher 调用。
- 维护 ERP executor、浏览器/API 操作、查重和回查。
- 编写单元、集成和无 ERP 测试。
建议顺序
- 建立共享 Schema 和
validate_erp_task.js。 - 建立
erp-coordinator，先接入现有 adapter。 - 完成
erp-create-order四路由包。 - 完成
erp-update-order和游客附件契约。 - 完成
erp-export-recovery源文件导出和恢复。 - 整理安全/会话/诊断支撑包。
- 最后拆出 PDF 交付包并验证与 API-first 边界。
10. 结构化文档与交接规范
Skill 和脚本之外，最终交付必须包含可供伙伴接手的结构化文档层：
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 记录当前可用能力、每个业务包的状态、已验证证据、未验证能力、已知阻断、恢复路径、协同分工、部署前检查和下一步。它回答“下一位伙伴如何从当前状态继续工作”。
业务交接文档
每个业务文档必须遵循同一模板，至少包含：
- 业务目标和触发语句。
- Skill 负责的理解与标准化规则。
- 任务 JSON 示例和字段说明。
- 对应脚本入口与现有
tools/执行模块。 - 成功结果、阻断结果和恢复结果。
- 测试样例、证据链接和当前验证状态。
- 风险、禁止事项、负责人和下一步。
单个 ERP 订单不再复制一份长篇交接文档；订单级事实通过任务 JSON、审计 JSON、订单 registry 和输出 artifact 管理，并由业务交接文档链接其规则和证据。
11. 未决事项
- 当前工作区的
.git目录不是可用 Git 仓库，无法提交设计文档或运行 Git 漂移检查；需要后续修复仓库或在真正的 Git 仓库中提交。 skills/将作为 Codex 主目录，是否同步生成其他部署端 wrapper 不在本轮范围内。- 既有
deploy/Skill 的淘汰时间需要在实现完成并通过回归后再决定。