BossAgentsPLM 协同接口规范（黑盒）
本文档定义 PLM 服务端需要提供的协同接口。
客户端通过这些接口与 PLM 交互，PLM 未实现时降级到本地 SQLite。
本规范是 PLM 服务端开发的需求定义，不是客户端实现。
一、PLM 需创建的 ItemType
1.1 Collaboration Task
``
ItemType: Collaboration Task
属性:
task_code string 任务编号 (CT-xxxx)
task_type string 任务类型 (identify/repair/generate/...)
priority integer 优先级 1-9
intent text 自然语言意图
state string pending/running/completed/failed (映射到 Life Cycle)
assigned_staff string 分配的数字员工ID
session_id string 所属协同会话ID
parent_task_id string 父任务ID (任务分解)
result_json text 执行结果 (JSON)
checkpoint_json text 最新断点 (JSON)
created_at date
completed_at date
`
1.2 Collaboration Session
`
ItemType: Collaboration Session
属性:
session_code string 会话编号
scenario string 场景标识
state string active/closed
member_count integer 成员数
task_count integer 任务数
metadata_json text 元数据 (JSON)
`
1.3 Task Checkpoint
`
ItemType: Task Checkpoint
属性:
task_id string 关联任务ID
step_number integer 步骤序号
step_name string 步骤名称
state_json text 完整执行状态 (JSON)
`
二、PLM 需创建的 RelationshipType
2.1 任务依赖（DAG边）
`
RelationshipType: Task Dependency
source: Collaboration Task
target: Collaboration Task
含义: source 依赖 target 完成（target 是 source 的前置条件）
`
2.2 会话包含任务
`
RelationshipType: Session Contains Task
source: Collaboration Session
target: Collaboration Task
`
2.3 任务分配
`
RelationshipType: Task Assigned To
source: Collaboration Task
target: Digital Employee (或 User)
`
2.4 任务的断点
`
RelationshipType: Task Has Checkpoint
source: Collaboration Task
target: Task Checkpoint
`
三、PLM 需提供的服务端方法（Server Method）
3.1 Get Ready Tasks
`
方法名: plm_GetReadyTasks
输入: session_id
逻辑: 查询 session 下所有 state=pending 的 Collaboration Task，
过滤出所有 Task Dependency 前置任务 state=completed 的任务
输出: 就绪任务列表
`
3.2 Batch Create Tasks
`
方法名: plm_BatchCreateTasks
输入: tasks[] (数组，含 title/type/priority/dependsOn)
逻辑: 单事务批量创建 Collaboration Task + Task Dependency 关系
输出: 创建结果列表
`
3.3 Get Task Tree
`
方法名: plm_GetTaskTree
输入: task_id, max_depth
逻辑: 递归查询 parent_task_id 和 Task Dependency 关系，构建任务树
输出: 嵌套任务树 JSON
`
3.4 Get Batch Status
`
方法名: plm_GetBatchStatus
输入: session_id
逻辑: GROUP BY state 统计任务状态
输出: { total, pending, running, completed, failed, ready, progress% }
`
3.5 Save Checkpoint
`
方法名: plm_SaveCheckpoint
输入: task_id, step_number, step_name, state_json
逻辑: 创建 Task Checkpoint + 关联到 Task
输出: checkpoint_id
`
3.6 Resume From Checkpoint
`
方法名: plm_ResumeFromCheckpoint
输入: task_id
逻辑: 查询最新 Task Checkpoint，恢复任务状态为 running
输出: { resumed, step_number, state_json }
`
3.7 Notify Task State Change（事件通知）
`
方法名: plm_NotifyTaskStateChange
触发: Collaboration Task state 变更时
逻辑: 调用配置的 webhook 或写入事件队列
输出: 通知已发送
`
四、PLM 需提供的 Life Cycle（状态流转）
4.1 Collaboration Task 生命周期
`
Preliminary → Submitted → In Progress → Completed
↘ Failed
↘ Cancelled
`
映射:
- pending → Preliminary
- running → In Progress
- completed → Completed
- failed → Failed
4.2 状态转换权限
- pending → running: 自动（getReadyTasks 选中后）
- running → completed: 自动（任务执行成功）
- running → failed: 自动（任务执行失败）
- 任意 → cancelled: 手动（人工取消）
五、客户端调用方式
客户端通过 AML 调用 PLM 接口，两种方式:
5.1 直接 AML 操作（CRUD）
`xml
`
5.2 调用服务端方法（复杂逻辑）
`xml
``
六、降级策略
| PLM 能力 | 降级方案 | 说明 |
|---|---|---|
| ItemType 不存在 | 本地 SQLite | 客户端检测到 ItemTypeNotFoundException |
| Server Method 不存在 | 客户端模拟 | 用多次 AML 查询模拟复杂逻辑 |
| 关系查询不可用 | 本地 SQLite depends_on | JSON 数组存储依赖 |
| 事件通知不可用 | 轮询查询 | 客户端定时查询任务状态 |
| 批量操作不可用 | 逐条创建 | 降级为循环单条创建 |
七、50×100 场景的 PLM 侧优化建议
- 关系索引: Task Dependency 的 source_id/related_id 建索引
- 批量事务: plm_BatchCreateTasks 用单事务创建 5000 条
- 图查询优化: plm_GetReadyTasks 用 SQL JOIN 而非逐条检查
- 状态缓存: plm_GetBatchStatus 用物化视图或缓存表
- 事件推送: plm_NotifyTaskStateChange 用 WebSocket/SSE 推送，避免轮询
