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. 总体架构和职责边界

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 输入格式

新增订单
产品名称：遇见老挝
出发日期：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. 新业务开发任务模板

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

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

用户必须提供：
-

ERP 可以派生/校验：
-

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

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

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

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

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