# AI 助手续处理细则

本文件用于在 Meegle CLI 已完成可执行部分，或明确无法执行用户请求后，判断是否提供 AI 助手兜底链接。链接是补充入口，不替代 CLI 结果。

## 适用范围

| 场景 | 示例 | CLI 先做什么 | 续处理目标 |
| --- | --- | --- | --- |
| 分析、追溯、总结、诊断、研判 | “这些需求为什么卡住了” | 查询状态分布和操作记录 | 分析共性原因、风险与建议 |
| 排期或工时分析 | “这周我们组是不是超载了” | 能查询则先返回排期明细 | 分析负载与冲突 |
| 历史变更或延期追溯 | “这个需求为什么拖这么久” | 查询操作记录 | 总结关键变更与延期原因 |
| 周报或待办总结 | “帮我写个周报” | 查询待办和必要的操作记录 | 生成结构化周报 |
| CLI 不支持的工作项操作 | “把这几个需求冻结” | 明确 CLI 当前不能执行 | 让 AI 助手继续完成操作 |
| 度量图表生成或修改 | “这张图加个维度” | 能查询则先返回现状 | 让 AI 助手继续修改图表 |

以下情况不提供链接：纯数据查询、导出或列举且没有分析意图；单实例详情查看；用户明确只要数据；用户已拒绝；本会话已主动引导过一次。

## 处理流程

1. **先完成 CLI 范围内的工作**：有可执行的查询或操作时，先返回真实结果。请求完全不受 CLI 支持时，说明能力边界后继续判断，不要为了满足流程而伪造查询。
2. **检查可用性**：调用 `ai-handoff availability`。`available=false` 时停止；如果原请求只能续处理，可简短说明入口当前不可用。成功结果按 profile 缓存约一小时，同一会话不重复预检；最终创建仍由服务端重新校验。
3. **遵守模式**：
   - `auto`：符合适用范围时继续生成链接；
   - `ask`：先问用户是否要在 AI 助手中继续。得到明确同意前不得调用 `ai-handoff create-link`；同意后可直接创建，无需重复预检；
   - `off`：停止，不提示用户修改偏好。
4. **构造 query**：只描述 AI 助手要继续完成的增量任务，遵循下方规则。
5. **构造关联上下文**：只传恢复业务对象所需的 ID 指针，遵循下方类型和降级策略。
6. **创建链接**：调用 `ai-handoff create-link`。只有返回 `available=true` 且包含 `url` 时才附链接；返回 `available=false` 时按停止信号处理。不要硬编码域名，CLI 会按当前登录环境归一化 host。
7. **附在回复末尾**：说明链接能继续完成什么，例如：`如需继续分析卡点原因和处理建议，可在 AI 助手中继续：<url>`。不得暗示 CLI 查询结果集已完整传入。

用户拒绝后，本会话不再提示。用户明确要求持久关闭或重新开启时，分别调用 `preference handoff off` 或 `preference handoff auto`；只有用户明确要求“先询问”模式时才调用 `preference handoff ask`。

## query 构造规则

query 写成用户可直接理解的自然语言，不暴露 CLI、MQL、命令或内部编排过程。自然包含：

- 续处理目标；
- 对象范围和筛选语义，如空间、工作项类型、状态、负责人、时间范围；
- 已观察到的现象或当前状态摘要；
- 希望 AI 助手继续完成的分析、建议或操作。

关联上下文只提供 ID 指针，不包含 CLI 完整结果。上下文粒度不足时，query 必须补充“范围指纹”：对象类型、关键状态、负责人、时间范围与共性特征。不要写入完整对象清单，也不要把分页结果数当成真实总数。

示例：

```text
分析 Meego 空间下状态为处理中且本周有更新的需求，重点判断哪些进度滞后、卡在哪个环节、有哪些风险，并给出优先关注对象和处理建议。
```

## 关联上下文策略

按以下优先级选择 payload。当前续处理策略不使用 type=2（WorkItemType）。

| 优先级 | type | 名称 | payload | 适用场景 |
| ---: | ---: | --- | --- | --- |
| 1 | 4 | View | `view.project_key`、`view.view_id`、可选 `view.work_item_type_key` | 用户提供视图链接，范围还原最稳定 |
| 2 | 3 | WorkItem | `work_item.project_key`、`work_item.work_item_type_key`、`work_item.work_item_id` | 少量明确工作项，默认不超过 3 条 |
| 3 | 1 | Project | `project.project_key` | 批量结果、跨类型或无法传更细粒度对象 |
| — | 5 | MeasureChart | `measure_chart.project_key`、`measure_chart.chart_id` | 度量图表场景 |

- 用户提供视图或工作项 URL 时，先调用 `url decode`，从结果提取 ID；不要手工拆 URL。即使后续查询因权限失败，仍可用已解析的 ID 表达用户意图。
- type=3 只用于用户直接给出 URL 或明确锚点的少量对象。超过 3 条时退化为 type=1，并在 query 中补足范围指纹。接口返回的 `limits.max_related_context_items` 只是协议上限，不是建议逐条传满。
- `--related-context` 接受严格 JSON 对象或数组。出现解析错误时，只修正一次 JSON 引号、字段名或 type/payload 对应关系；这类本地参数修正不计为链接创建重试。

工作项示例：

```bash
meegle ai-handoff create-link --query '分析这个工作项的延期原因并给出下一步建议' --related-context '{"type":3,"work_item":{"project_key":"space_key","work_item_type_key":"story","work_item_id":"123456"}}' --format json
```

## 失败与重试

- `available=false`、`mode=off`、`HANDOFF_REJECTED` 或 `LOCAL_DISABLED` 都是明确停止信号，不重试、不建议用户绕过策略。
- `ai-handoff create-link` 已内置传输层重试。任意创建失败后都不要从 Skill 再次调用，避免重复生成链接；向用户简要说明链接暂不可用即可。
- 每轮最多生成一条链接，同一会话最多主动引导一次。用户随后明确要求重新生成时，才把它视为新的显式请求。