142 lines
7.2 KiB
Markdown
142 lines
7.2 KiB
Markdown
---
|
||
name: zentao-ai-channel
|
||
description: |
|
||
禅道 AI 通道接口技能（生产环境直连）。封装禅道 AI 通道的三个接口：
|
||
①评估结果提交（工作量指标/验收标准写入需求扩展信息）；
|
||
②AI 批量创建任务（为需求批量建研发/测试任务，重名自动跳过）；
|
||
③文件上传并绑定（PRD/代码审查报告/工作日志/测试文档/会议纪要等上传到需求或会议）。
|
||
三个接口可在需求生命周期中组合使用，也可独立调用任意一个。
|
||
触发关键词：提交评估结果到禅道、禅道批量建任务/拆任务、上传文档到禅道/绑定需求、
|
||
代码审查报告上传、验收标准提交、/zentao
|
||
---
|
||
|
||
# zentao-ai-channel
|
||
|
||
## 定位
|
||
|
||
禅道系统（ITSM）AI 对接通道的统一入口。所有调用通过客户端脚本完成：
|
||
|
||
```
|
||
python .agents/skills/zentao-ai-channel/zentao_client.py <子命令> [参数...]
|
||
```
|
||
|
||
子命令与接口一一对应，可独立使用：`submit`（接口一）、`batch-add-tasks`（接口二）、`upload`（接口三）。
|
||
|
||
## 接入信息（公共）
|
||
|
||
- **Base URL（生产）**：`https://itsm.sino-assist.com/zentao`（脚本默认值，可用环境变量 `ZENTAO_BASE_URL` 覆盖）
|
||
- **鉴权**：请求头 `Authorization: <token>`，**直接放 token 原文，不要加 "Bearer " 前缀**。令牌为 ai 账号永久令牌，已内置在脚本中，可用环境变量 `ZENTAO_AI_TOKEN` 覆盖
|
||
- **统一响应**：`{"code": 0, "message": "成功", "data": {...}}`；`code=0` 成功，`code=-1` 失败（message 为失败原因）
|
||
- 令牌问题排查：`请登录` = 未带或无效 token；`该接口仅AI框架通道可用` = 非 ai 账号令牌
|
||
|
||
---
|
||
|
||
## 接口一：评估结果提交（submit）
|
||
|
||
`POST /zt-story-expand/saveOrUpdate` — 需求评估完成后，将工作量评估指标与验收标准写入需求扩展信息。**同一需求重复提交 = 覆盖更新（幂等）**。
|
||
|
||
```bash
|
||
python .agents/skills/zentao-ai-channel/zentao_client.py submit \
|
||
--story-id <需求ID> \
|
||
--number-units <S> \
|
||
--b <单元业务复杂度B> \
|
||
--ft <技术复杂度系数F(T)> \
|
||
--ga <AI效率系数G(A)> \
|
||
--w <评估工时W，人日> \
|
||
--status <inProgress|finished> \
|
||
[--completion-degree <0~100>] \
|
||
[--acceptance-criteria <Markdown文本> | --acceptance-criteria-file <md文件路径>] \
|
||
[--product-person <中文名>] [--develop-person <中文名>] [--test-person <中文名>]
|
||
```
|
||
|
||
注意事项：
|
||
|
||
- `storyId` 为空时接口返回成功但不处理——务必确认已传
|
||
- **`--status finished` 会锁定记录**（后续提交被拒绝，提示"该需求已完成，不可再修改"）并结算当月工作量；未确认完成前一律用 `inProgress`
|
||
- `finished` 时完成度由服务端自动置 100，无需传 `--completion-degree`
|
||
- 验收标准为可选；若 Spec 工作区存在 `02_acceptance` 产物，建议用 `--acceptance-criteria-file` 一并提交
|
||
|
||
## 接口二：AI 批量创建任务（batch-add-tasks）
|
||
|
||
`POST /zt-task/aiBatchAdd` — 为指定需求批量创建研发/测试任务。
|
||
|
||
```bash
|
||
python .agents/skills/zentao-ai-channel/zentao_client.py batch-add-tasks \
|
||
--story-id <需求ID> \
|
||
--tasks-json '[{"name":"后端接口开发","type":"devel","desc":"实现 xx 接口","assignedTo":"zhangsan","aiEvaluationTime":8,"planStartDate":"2026-08-10","deadline":"2026-08-11"},{"name":"接口测试","type":"test","aiEvaluationTime":4}]'
|
||
```
|
||
|
||
`tasks[]` 字段：
|
||
|
||
| 字段 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| name | 是 | 任务名称 |
|
||
| type | 是 | `devel`=开发 / `test`=测试，其他值整批拒绝 |
|
||
| desc | 否 | 任务描述，写入任务描述 |
|
||
| assignedTo | 否 | 指派人**登录账号**（非中文名） |
|
||
| aiEvaluationTime | 否 | AI 评估工时（小时），写入任务预计工时 |
|
||
| planStartDate / deadline | 否 | 日期格式 `yyyy-MM-dd` |
|
||
|
||
注意事项：
|
||
|
||
- **整批拒绝**：任一任务不合法（类型错误/名称为空/日期格式错误），本批全部不创建
|
||
- **需求状态拦截**：需求为 已发布（含待验收/验收不通过，其 status 均为 `released`）/ 已完成（验收通过，`finished`）/ 已关闭（`closed`）时整批拒绝，报错"需求已发布/已完成/已关闭，不允许创建任务"（仅 AI 通道拦截，人工拆任务不受此限）
|
||
- **防重**：同需求下已存在同名同类型（未删除）任务 → 跳过并记入响应 `skipped`，不算失败；全部命中防重时返回 `code:0, created:0`
|
||
- 新任务初始状态"未开始"，创建人显示为 ai；响应 `data.taskIds` 为新建任务 ID 列表
|
||
|
||
## 接口三：文件上传并绑定（upload）
|
||
|
||
`POST /common/uploadBind`（multipart/form-data）— 上传文件并一步绑定到需求/会议，页面即时可见，操作记录留痕。
|
||
|
||
```bash
|
||
python .agents/skills/zentao-ai-channel/zentao_client.py upload \
|
||
--file <文件路径> \
|
||
--object-type <见下表> \
|
||
--object-id <需求ID或会议ID> \
|
||
[--title <文件标题>] \
|
||
[--review-result <pass|reject>] # 仅 aiCodeReview 有效
|
||
```
|
||
|
||
`--object-type` 对照表：
|
||
|
||
| objectType | 含义 | 绑定后效果 |
|
||
|------------|------|-----------|
|
||
| story | 需求文档（PRD 等） | 需求文档链接更新 |
|
||
| aiCodeReview | 代码审查报告 | 审查报告链接更新；带 `--review-result` 时同步审查状态 |
|
||
| aiWorkLog | 工作日志 | 工作日志链接更新 |
|
||
| aiDocUpdate | AI 项目文档更新记录 | 更新记录链接更新 |
|
||
| testCase | 测试用例 | 测试用例链接更新 |
|
||
| testReport | 测试报告模版 | 报告模版链接更新 |
|
||
| testReportSubmit | 测试报告提交 | 报告提交链接更新（SOP 流程卡点依据） |
|
||
| testOther | 其他测试文档 | 其他文档链接更新 |
|
||
| meeting | 会议纪要 | 会议纪要链接更新（object-id 填会议 ID） |
|
||
|
||
注意事项：
|
||
|
||
- 同一对象同一类型可多次上传形成文件列表，业务对象链接字段始终指向**最新一份**
|
||
- objectType/objectId 错误、对象不存在均会拒绝且不落盘
|
||
- 响应 `data.url` 为相对路径，拼在系统域名后即可访问
|
||
|
||
---
|
||
|
||
## 组合使用（需求生命周期动线）
|
||
|
||
三个接口常在同一会话按序使用，但每步都可独立执行：
|
||
|
||
1. 需求评估完成 → `submit`（status=inProgress）→ 可用 `upload --object-type story` 上传 PRD
|
||
2. 进入开发 → `batch-add-tasks` 拆分研发/测试任务
|
||
3. 过程中 → `upload` 上传审查报告（aiCodeReview + review-result）、工作日志（aiWorkLog）、测试文档（testCase/testReportSubmit 等）
|
||
4. 需求完成 → `submit`（status=finished，**锁定，最后一步执行**）
|
||
|
||
## 常见错误速查
|
||
|
||
| code | message | 处理 |
|
||
|------|---------|------|
|
||
| -1 | 请登录 | 检查 Authorization 头 / token |
|
||
| -1 | 该接口仅AI框架通道可用（需ai账户token） | 换用 ai 账号令牌（脚本默认已内置） |
|
||
| -1 | 该需求已完成，不可再修改 | 需求已 finished 锁定（接口一） |
|
||
| -1 | 需求不存在:xxx / 会议不存在:xxx | 核对 storyId / objectId |
|
||
| -1 | uploadBind不支持的objectType:xxx | 对照接口三取值表 |
|
||
| -1 | 任务类型仅支持devel/test:xxx | 修正 tasks[].type（接口二） |
|
||
| -1 | 日期格式错误，应为yyyy-MM-dd:xxx | 修正日期格式（接口二） |
|