LWLT-AI/开发维护规范.md

# LTJT 项目开发与业务维护规范

版本：v0.1（项目基线草案）  
适用范围：业务人员、Skill 维护人员、ERP 控制脚本维护人员、业务系统维护人员  
维护位置：项目根目录；业务规则细节由 `agent设计规范/` 和 ERP 脚本/Schema 共同维护

## 1. 文档目的

本规范规定一个业务需求从“用户表达”到“业务系统任务”再到“ERP 操作”的开发方法，避免业务规则、Agent Prompt、Skill、ERP 脚本和测试各自维护、互相漂移。

以后新增或修改任何业务能力，都必须同时回答四个问题：

1. 用户用什么精确指令触发它？
2. Skill 如何理解这类业务、需要哪些用户事实、哪些字段由 ERP 派生？
3. ERP 控制脚本如何验证、填充、预检和回查？
4. 用什么 Schema、fixture、自动化测试和运行证据证明它没有破坏已有业务？

本规范不允许只修改 Prompt 让任务“看起来能用”，也不允许只修改 ERP 脚本而不更新业务契约和 Skill。

## 2. 总体架构和职责边界

```mermaid
flowchart LR
    U["用户输入\n首行精确业务指令"] --> A["Agent Prompt\n范围与指令路由"]
    A --> S["统一 Skill\n业务表达与 operation"]
    S --> T["业务系统任务\ntask_ready"]
    T --> E["ERP 控制脚本\n产品模板与精确 lookup"]
    E --> P["ERP 预检\n序列化与提交拦截"]
    P --> V["授权提交与 ERP 回查\nerp_ready / completed"]
```

| 层 | 必须负责 | 不得负责 |
|---|---|---|
| 用户输入 | 提供首行精确指令和业务事实 | 用模糊话术要求 Agent 猜业务类型 |
| Agent Prompt | 判断范围、识别首行指令、调用统一 Skill、原样返回结果 | 复制业务字段规则、猜值、操作 ERP |
| 统一 Skill | 选择业务类型、读取对应 reference、拆解事实、生成标准 operation、阻断不完整业务 | 调用浏览器、调用 ERP 接口、读取旅客文件内容、声称保存成功 |
| 业务系统 | 保存原文、创建任务、保存任务/会话元数据、展示状态 | 绕过 Skill 直接把自然语言送入 ERP |
| ERP 控制脚本 | 产品模板派生、精确 lookup、表单映射、dry-run、预检、提交拦截、回查 | 使用 AI 运行时决策、closest/fuzzy 选择、绕过安全门 |
| 交接文档 | 记录规则、证据、阻塞和下一步 | 替代可执行 Schema、脚本和测试 |

### 2.1 两种就绪状态

- `task_ready`：业务系统已经能够创建任务；不表示 ERP 字段已经解析完成，更不表示已经保存。
- `erp_ready`：ERP 产品模板、客户/专线/员工等精确 lookup、表单映射和预检都已经通过；仍不等于真实提交成功。
- `completed`：只有取得持久化业务编号或文件，并完成 ERP/业务系统回查后才能使用。
- `blocked`：任一必需业务事实、唯一匹配、安全授权或证据条件失败。

团队单/批量下单中，产品、出发日期、人数、房型、价格、OP、销售人属于 Agent 主要提取事实；客户、专线、行程、币种、团号前缀等可以由 ERP 的产品模板和精确 lookup 派生。缺失的 ERP 派生字段必须记录在 `data.resolution.deferred_fields`，不得伪造。

## 3. 项目文件职责和事实来源

### 3.1 当前项目文件

| 文件/目录 | 维护内容 | 修改时机 |
|---|---|---|
| `agent设计规范/agent-prompt.md` | Agent 范围判断、首行指令路由、Skill 调用规则 | 增加业务入口或改变 Agent 路由时 |
| `agent设计规范/skills/ltjt-business-operation/SKILL.md` | 唯一 Skill 入口、工作流、通用约束、reference 路由 | 改变业务处理流程或 Skill 入口时 |
| `agent设计规范/skills/ltjt-business-operation/references/*.md` | 各业务类型的表达、字段、阻断、resolution、样例 | 新增业务类型或修改业务规则时 |
| `schemas/standard_system_operation.schema.json` | 业务系统任务的标准 operation Schema | 增删字段、改变必填关系、改变状态语义时 |
| `schemas/orders_add_form_schema.json` | 实际 LTJT 下单页面的字段和表单结构 | ERP 页面字段发生变化并重新抽取时 |
| `mappings/orders_add.mapping.json` | 标准 operation 到 LTJT 表单的映射、限制和 lookup 说明 | 表单字段、映射、收款行或页面限制变化时 |
| `tools/browser_order_add_preflight.mjs` | ERP 表单预检、字段完整性、产品副作用和序列化验证 | 预检规则或执行路径变化时 |
| `tools/browser_order_add_raw_instruction_test.mjs` | 原始指令到产品模板派生的测试链路 | 原始指令测试链路或产品模板行为变化时 |
| `tools/dry_run_order_create.mjs` | 标准 operation 的离线映射和 dry-run | 需要调整离线映射或验证规则时 |
| `chrome-extension/ltjt-order-assistant/operation-plans.js` | 业务 action 路由、任务计划和执行边界 | action 路由、任务状态或能力边界变化时 |
| `mock-business-system/external-agent-client.mjs` | 云端 Agent 会话、SSE、响应归一化和外部错误 | 外部 Agent 接入协议变化时 |
| `archive/handoff/2026-07-12/` | 同伴交接、旧 `erp-task-v1` 和历史参考 | 只用于对照和兼容，不作为当前根契约的唯一来源 |
| `reports/`、诊断输出和运行 audit | 验证证据和运行记录 | 只生成，不把报告当作业务规则编辑 |
| `*.skill` | 可分发打包产物 | 由源文件重新生成，不手工编辑压缩包 |

### 3.2 冲突处理顺序

出现文档、Skill、脚本和交接包不一致时，按以下顺序判断：

1. 当前已观察到的 ERP 页面 Schema、真实表单行为和回查结果。
2. 当前项目的版本化 mapping、控制脚本和自动化测试。
3. 根目录的标准 operation Schema。
4. `agent设计规范/` 中的 Skill reference 和样例。
5. `archive/handoff/2026-07-12/` 中的旧任务格式、旧 Skill 或旧交接文档。

归档交接包中的 `erp-task-v1` 只能作为 Skill 内部兼容输入，不能要求云端 Agent 同时输出两种格式。

## 4. 首行精确业务指令规范

这是下一阶段必须落地的用户输入协议。每条业务输入的第一行非空文本必须是受控命令，Agent 不再从整段自然语言猜 action。

### 4.1 初始命令注册表

| 第一行精确指令 | 标准 action | 对应 Skill reference |
|---|---|---|
| `新增订单` | `team_order_create` | `create-orders.md` |
| `批量新增订单` | `team_order_batch_create` | `create-orders.md` |
| `创建散拼母团` | `shared_plan_create` | `create-orders.md` |
| `新增散拼子单` | `shared_child_order_create` | `create-orders.md` |
| `修改订单` | `order_update` | `updates-and-travelers.md` |
| `导入旅客名单` | `passenger_list_import` | `updates-and-travelers.md` |
| `导出确认件` | `confirmation_export` | `export-and-recovery.md` |
| `恢复导出确认件` | `confirmation_export` | `export-and-recovery.md` |

命令注册表是受控枚举，不允许用“应该是新增”“帮我改一下”“处理这个订单”等近似表达替代第一行命令。

### 4.2 输入格式

```text
新增订单
产品名称：遇见老挝
出发日期：2026-08-11
成人：2
占床儿童：1
不占床儿童：1
成人价格：520
占床儿童价格：220
不占床儿童价格：120
计调：测试
销售：琳琳
```

规则：

- 只跳过开头空行后读取第一行；第一行必须完整等于命令注册表中的一个值。
- 第二行及以后才是业务事实，允许使用自然语言，但不能改变第一行 action。
- 缺少第一行、第一行未知或第一行包含多个命令时，返回 `agent_parse_blocked`，阻断码使用 `invalid_command:first_line`，不调用 Skill。
- 第一行合法时，Agent 必须调用统一 Skill；Skill 负责判断该 action 的业务事实是否足够。
- 新增命令必须先登记 action、reference、Schema 影响、ERP 路由和测试 fixture，再开放给业务人员使用。

### 4.3 命令变更规则

新增、改名或废弃命令必须同步修改：

1. 命令注册表和 Agent Prompt。
2. `operation-matrix.md` 和对应业务 reference。
3. 标准 action 枚举和业务系统路由。
4. 至少一个通过样例和一个阻断样例。
5. 云端 Profile 发布版本和跨平台 `.skill` 包。

## 5. 新增或修改业务的标准流程

任何业务开发任务按以下顺序执行。

### 第 1 步：定义业务命令和边界

先写清楚：

- 第一行精确指令。
- 对应标准 action。
- 业务成功的定义。
- 允许的业务范围和明确不支持的范围。
- 需要用户提供的事实。
- 可以由 ERP 确定性派生的字段。
- 缺失、冲突、歧义和安全阻断条件。

没有完成这一步，不得先改 ERP 脚本。

### 第 2 步：完善 Skill

先修改或新增 `agent设计规范/skills/ltjt-business-operation/references/<business>.md`，至少包含：

1. 业务范围和命令。
2. Agent task minimum：用户必须提供的事实。
3. ERP-derived fields：ERP 可以通过产品模板或 lookup 派生的字段。
4. `task_ready` 和 `erp_ready` 的区别。
5. 标准字段、单位、日期、数量和价格规则。
6. 阻断码及其含义。
7. 一个 task-ready 样例、一个完整样例、一个阻断样例。
8. 后续 ERP reference 或控制脚本入口。

Skill 只描述业务语义和控制边界，不复制浏览器 selector、Cookie、凭据、临时 endpoint 或实现代码。详细的页面行为放到 ERP 控制脚本和 mapping。

### 第 3 步：更新标准契约

当业务需要新增字段、状态或 resolution 时：

- 先修改 `schemas/standard_system_operation.schema.json`。
- 明确字段属于用户事实、Skill 规范化、业务系统元数据还是 ERP 派生结果。
- 不用 `additionalProperties: true` 解决字段冲突。
- 保留旧 action 的兼容行为，除非明确执行迁移。
- 同步更新跨平台 Skill 内置 Schema。

### 第 4 步：开发或调整 ERP 控制脚本

ERP 控制脚本只接收标准 operation 或已规范化的任务，不接收自然语言。标准执行阶段为：

1. 读取任务和 `resolution`。
2. 校验 action、模式、日期、人数、房型、价格和附件限制。
3. 通过产品列表精确选择一个产品。
4. 在 ERP 页面执行 `Find_product/GetProduct` 产品模板副作用。
5. 从模板和页面 lookup 派生或校验行程、专线、客户、币种、团号前缀和隐藏 ID。
6. 对 SelectBox 绑定字段执行精确匹配和关联 `SetVal`，禁止 closest/fuzzy。
7. 重建或校验收款行、备注、数量、价格和必填字段。
8. 生成 dry-run 序列化结果并记录脱敏摘要。
9. 新写入路线先进行提交拦截，确认页面自己的 `SubmitInfoForm/DoInfoJH` 分支没有验证错误且网络被阻断。
10. 只有显式授权才允许真实提交；提交后必须通过 ERP 或业务系统回查确认持久化结果。

脚本默认只读或 dry-run。HTTP 200、弹窗、旧列表行或页面没有报错都不能单独代表成功。

### 第 5 步：补齐测试和样例

每个业务 action 至少有以下 fixture：

- 最小 task-ready：包含用户事实和必要 `deferred_fields`。
- 完整 task-ready：用户明确提供所有可提供字段。
- 阻断：缺少用户必填事实。
- 阻断：业务引用重复或无法唯一确认。
- 阻断：混合多个独立动作。
- 安全阻断：要求跳过校验、直接提交或使用 closest。
- ERP-ready/预检结果：仅在真实或受控 fixture 具备确定性解析证据时提供。

### 第 6 步：发布和交接

发布前必须：

- 验证 Skill frontmatter 和 references。
- 验证 Schema、fixture 和控制脚本测试。
- 重新生成跨平台 `.skill` 包，不把 `openai.yaml` 当作跨平台依赖。
- 重新发布云端 Prompt/Profile 和 Skill 内容。
- 更新业务交接文档、变更摘要、阻断和后续工作。

## 6. ERP 控制脚本开发规范

### 6.1 命名和入口

脚本名称要表达业务和阶段，例如：

- `tools/browser_order_add_raw_instruction_test.mjs`
- `tools/browser_order_add_preflight.mjs`
- `tools/dry_run_order_create.mjs`
- `tools/verify_order_marker.mjs`

一个脚本只负责一个可验证阶段；不要把自然语言解析、ERP lookup、真实提交和导出恢复揉成一个不可测试的大脚本。

### 6.2 输出规范

脚本必须支持机器可读 JSON，至少包含：

- `status`：如 `dry_run_passed`、`blocked`、`execution_uncertain`、`completed`。
- `blockers`：稳定、可定位、脱敏的阻断数组。
- `warnings`：不影响当前阶段但需要维护者关注的风险。
- `operation` 或 `task_id` 摘要。
- `evidence`：请求阶段、payload hash、回查状态或 artifact 摘要，不放凭据和 PII。

成功状态必须能对应一个明确证据；不确定状态不得自动重试或报告成功。

### 6.3 ERP 安全规则

- 不在脚本中存储密钥、Cookie、登录信息或授权码。
- 不把 selector、内部 endpoint、堆栈、旅客 PII 放到业务回复。
- 不使用 AI 在运行时选择产品、客户、专线、员工或资源。
- 不使用“最接近”匹配代替唯一匹配。
- 不因用户说“马上保存”自动打开真实提交。
- 不重复保存已确认成功的订单；导出失败走 recovery。
- 新增写入路线必须先有表单 Schema、mapping、dry-run、提交拦截和回查证据。

## 7. 验证矩阵

| 验证层 | 验证内容 | 通过标准 |
|---|---|---|
| Prompt 路由 | 首行命令识别、范围外阻断、Skill 必调 | 未知首行不调用 Skill；合法首行只路由一次 |
| Skill 结构 | frontmatter、references、命令和 action 映射 | `quick_validate.py` 通过 |
| Schema | task-ready、deferred、完整和阻断样例 | JSON Schema 通过，未知字段阻断 |
| Skill 行为 | 缺字段、歧义、混合动作、安全绕过 | 阻断码稳定，`operation` 不输出半成品 |
| 业务系统边界 | 任务创建、原文保留、元数据隔离 | task-ready 能建任务，session/任务元数据不进入 operation |
| ERP lookup | 产品、客户、专线、员工、资源精确匹配 | 0 个或多个候选均阻断 |
| 产品模板 | `Find_product/GetProduct` 联动和一致性 | 派生字段与显式业务字段一致 |
| 表单预检 | 必填、数量、价格、收款行、序列化 | 无缺失、无冲突、dry-run 通过 |
| 提交拦截 | 页面自身校验和 `DoInfoJH` 阻断 | 无 alert，捕获预期 payload，真实网络未发送 |
| 授权提交 | 测试/正式授权、payload hash、幂等和锁 | 所有安全门通过才允许提交 |
| 回查 | ERP/业务系统持久化状态 | 有持久化编号或 artifact 证据 |
| 云端回归 | 已发布 Profile 的实际 SSE 输出 | 返回标准 JSON，不再出现旧格式或旧阻断规则 |

## 8. 开发维护检查清单

### 8.1 业务/Skill 变更

- [ ] 第一行精确命令已登记。
- [ ] action 和 reference 已明确。
- [ ] 用户必填事实与 ERP 派生字段已分开。
- [ ] `task_ready`/`erp_ready` 边界已写清。
- [ ] 缺失、歧义、冲突和安全阻断已定义。
- [ ] 通过、deferred、阻断样例已补齐。
- [ ] 没有把 ERP selector、凭据或执行代码写入 Prompt/Skill。

### 8.2 ERP 脚本变更

- [ ] 输入是标准 operation，不是自然语言。
- [ ] mapping 和 ERP 表单 Schema 已同步。
- [ ] lookup 规则是精确、可复现、可审计的。
- [ ] 产品模板副作用已验证。
- [ ] dry-run 和提交拦截测试已通过。
- [ ] 真实写入有显式授权、幂等、锁和回查。
- [ ] 输出 JSON 已脱敏，失败状态可定位。

### 8.3 发布交接

- [ ] Skill 结构校验通过。
- [ ] 根 Schema 和 Skill 内置 Schema 一致。
- [ ] 业务系统测试和 ERP 脚本测试通过。
- [ ] 跨平台 `.skill` 包已重新生成。
- [ ] 云端 Profile/Prompt 已重新发布。
- [ ] 变更文件、测试证据、已知阻塞和下一步已记录。

## 9. 后续落地路线

### 阶段 0：命令注册表

先确定七类已有业务的首行精确指令，建立唯一 action 映射，并规定未知命令阻断。

### 阶段 1：Agent 输入协议

更新 Agent Prompt 和业务系统输入校验：首行不合法直接无效；合法首行才调用统一 Skill。同步补充缺少首行、未知首行和混合命令测试。

### 阶段 2：Skill 业务表达

按每个命令完善 reference：业务事实、ERP 派生字段、task-ready 输出、阻断码、样例和维护人。新增业务先完成 Skill，再进入脚本开发。

### 阶段 3：ERP 控制脚本

将每个已登记 action 映射到一个明确的控制脚本入口，先完成只读 lookup、产品模板副作用和 dry-run，再独立推进写入路线。

### 阶段 4：统一回归

建立命令级、Skill 级、Schema 级、ERP 预检级、提交拦截级和回查级测试矩阵。任何一个层级失败都不得发布云端 Profile。

### 阶段 5：业务维护机制

业务人员维护命令和表达 reference，脚本维护人员维护 ERP 解析和执行，交接负责人维护证据和状态；三者通过同一个 action、Schema 和 fixture 对齐。

## 10. 新业务开发任务模板

以后新增一个业务任务时，按以下结构提交：

```text
业务名称：
第一行精确指令：
标准 action：
业务目标：
不支持范围：

用户必须提供：
-

ERP 可以派生/校验：
-

task_ready 输出：
- Skill reference：
- Schema 变更：
- resolution/deferred 字段：

ERP 控制脚本：
- 脚本入口：
- mapping：
- 产品模板/lookup：
- dry-run：
- 提交拦截：
- 回查：

测试 fixture：
- 正常：
- deferred：
- 缺字段阻断：
- 歧义阻断：
- 安全阻断：

发布交接：
- Prompt/Profile：
- Skill 包：
- 已知阻塞：
- 下一步：
```

这份模板没有补齐之前，不进入正式 ERP 写入开发。