zentao17

Files (4)

• .gitignore
• LOCAL.example.md
• SKILL.md
• zentao17.py · scripts/

SKILL.md (first lines)

# 禅道 17.8 CLI（zentao17）

> **已迁移，这里是最后一版快照**：自 2026-11-05 起，zentao17 随 LSP 项目的 lsp-web 仓库分发（`frontend/.agents/skills/zentao17/`），后续改动只提交到那里，本目录不再更新。用户目录里的旧部署副本请按 lsp-web `frontend/README.md`「新机器初始化」第 4 节迁移；不要删掉本目录，旧版 `self-update` 还要从这里取到这份快照。

公司禅道自部署于固定 IP，版本 **17.8**。官方 `zentao-cli` 需要 API 2.0（禅道 22+），在本环境不可用（会误报「用户名和密码不正确」）。本技能使用 `zentao17` 命令，基于 v1 RESTful API（禅道 12.0+ 均支持）；v1 不开放的激活、转派、独立备注走网页会话通道。

本技能只管「怎么读写禅道」。具体项目的处理流程（何时 resolve、推送顺序、流转给谁）由上层技能规定，例如 LSP 项目的 zentao-bug-handling／zentao-unattended；**上层技能已授权的写操作，按上层规定执行，不再逐条向用户复述确认**。

**CLI 版本：2026-11-05.2**（`zentao17 --version` 应输出同一值）。

## 开工自检（每次调用都执行）

1. **先看版本与同步状态**：执行 `zentao17 self-update`。本技能随 lsp-web 仓库分发（`lsp-web/frontend/.agents/skills/zentao17/`），这条命令只报告版本、以及本技能目录是否落后远端：它会 fetch，但不合并、不改工作区。输出带「fetch 失败」时，在回复里提一句网络或凭据问题。报「落后远端」时提醒用户在 lsp-web 主 checkout 执行 `git pull`，不要自己去拉；报「不在 git 仓库里」说明 `zentao17` 还指向迁移前的旧部署副本，按 lsp-web `frontend/README.md`「新机器初始化」重建链接。
2. **再核对版本**：`zentao17 --version` 与上面的 CLI 版本不同，或对话里记得的命令表与 `zentao17 --help` 不一致时，重新读本文件与同目录的 `LOCAL.md`，以新读到的为准。长会话里早先读过的内容可能已经过期。版本**低于**本文件记载时，多半是 `zentao17` 还指向迁移前的旧副本：查看 `~/.local/bin/zentao17`（Windows 为 PATH 里的 `zentao17.cmd`）指向哪里，不在 lsp-web 的 `frontend/.agents/skills/zentao17/` 下就提醒用户按 lsp-web `frontend/README.md`「新机器初始化」第 4 节迁移。
3. **检查失败不阻塞**：git 不可用或网络不通时按当前版本继续，在回复里提一句。不要为此执行 `git reset`、`git pull` 之类改动仓库的命令。
4. **能力以 `--help` 为准**：说「CLI 不支持某操作」之前，先执行 `zentao17 --help`（必要时 `zentao17 <子命令> --help`）。只有确认命令不存在，或实际执行后失败（退出码 1/3/4），才可以说做不到，并附上命令输出。记忆、旧文档和 spec 里的历史记录都不能作为「做不到」的依据。
5. **做不到时不用别的写操作凑结果**：例如不能转派时，不得用 resolve（含 `-r external`）代替；保持原状态，带上命令输出向用户说明。
6. **编码自检（本会话第一次写禅道之前）**：用文件工具（不是 shell 的 echo／heredoc／`Set-Content`）把样本 `禅道検証・中文テスト①（全角）✅` 写进一个 UTF-8 临时文件，执行 `zentao17 doctor --probe-file <该文件>`；打算用 `-c` 传备注的，再执行一次 `zentao17 doctor --probe "禅道検証・中文テスト①（全角）✅"`。退出码 5 说明该通道会损坏中日文：按输出的处理步骤修好后重跑，修好之前只用通过检测的通道写禅道。输出里的「⚠」环境提示（如 Windows 未启用 UTF-8）不影响已通过探针的通道，不要为此去改系统或持久配置；用 `-F` 传文件即可。Windows 上尤其不能省（2026-10-31 #48775 就是 Windows 环境把中日文换成了「?」后写入）。

## 本地配置与路径

- `LOCAL.md` 与本文件在同一目录（lsp-web 主 checkout 的 `frontend/.agents/skills/zentao17/LOCAL.md`，已 gitignore；worktree 里的 `frontend/.agents` 是指向它的链接）。里面有禅道地址、Bug 拉取口径、课题映射和**常用角色账号**（本人／产品／后端）。转派前先在这里查对方账号，查不到再用 `zentao17 users --search <姓名>`，不要把整张用户表交给用户去挑。
- shell 报 `command not found: zentao17` 时，说明 `~/.local/bin` 不在该工具的 PATH 里，不代表没装。改用 `~/.local/bin/zentao17 …`，或在 worktree 的 `frontend` 下执行 `python3 .agents/skills/zentao17/scripts/zentao17.py …`。

## 首次使用：安装 CLI 命令

`zentao17` 命令即本技能目录下的 `scripts/zentao17.py`（自带 shebang，仅依赖 Python 标准库）。把它软链到 PATH 中任意目录即可（`<lsp-web>` 为本机 lsp-web 克隆路径）：

```bash
ln -sf <lsp-web>/frontend/.agents/skills/zentao17/scripts/zentao17.py ~/.local/bin/zentao17
zentao17 --help
```

之后创建本地私有配置：`cp LOCAL.example.md LOCAL.md`，填写禅道地址、Bug 拉取口径与课题号映射（该文件已 gitignore，不入库）。最后按「凭证安全」一节在终端执行 `zentao17 login`。

更新方式：本技能的改动与 lsp-web 的其他技能一样提交到 lsp-web，其他机器 `git pull` lsp-web 即生效。2026-11-05 之前本技能在个人 skills 仓库分发、经 `self-update` 同步到 `~/.agents/skills/zentao17/`，那份部署副本已停止更新。

## 凭证安全

- 严禁在对话中收集账号密码。未登录时引导用户在终端执行 `zentao17 login` 交互式配置（凭证存于 `~/.config/zentao17/`，权限 600）。
- 严禁读取 `~/.config/zentao17/` 下的凭证文件。所有数据通过 `zentao17` 命令获取；需要知道「我是谁」时用 `zentao17 whoami`。

## 命令速查

| 意图 | 命令 |
|------|------|
| 当前操作账号 | `zentao17 whoami`（工号＋姓名；**actions 的 actor 字段是姓名**，判断「本人动作」用这里的姓名比对） |
| 查账号/工号 | `zentao17 users --search <姓名或工号>` |
| 项目(课题)列表/搜索 | `zentao17 projects [--search 名称或编号] [--all]` |
| 某项目下的执行/迭代 | `zentao17 executions --project <id> --status all` |
| 产品列表（查产品 ID） | `zentao17 products` |
| 产品 Bug 列表（推荐口径） | `zentao17 bugs --product <id> [--status unclosed] [--keyword 词 ...] [--assigned me]` |
| 执行/迭代 Bug 列表 | `zentao17 bugs --execution <id> [--status ...]`（只含已挂执行的单，见「拉取口径」） |
| 指派给我的未关闭 Bug | `zentao17 bugs --product <id> --status assignedtome` |
| Bug 详情 | `zentao17 bug <id>`：步骤文本（截图位置标 `[图N]`）＋截图/附件清单＋actions 全历史（含字段变化与完整备注） |
| 下载截图/附件 | `zentao17 download <id> [--dir 目录]`（默认 `$TMPDIR/zentao17-files/<id>`） |
| 巡检预检 | `zentao17 changes --product <id> --state <快照.json> [--own-prefix 前缀] [--set-tracked ID,...] [--update]`（见下文） |
| 解决 Bug | `zentao17 resolve <id> -c "备注(如 commit hash)"` |
| 解决(其他方案) | `zentao17 resolve <id> -r duplicate --duplicate-bug <id>`（可选: fixed/notrepro/bydesign/duplicate/external/postponed/willnotfix/tostory） |
| 关闭 Bug | `zentao17 close <id> -c "备注"` |
| 激活 Bug | `zentao17 activate <id> [-c "备注"] [--assign 账号]`（网页会话通道；默认指派给上次解决人） |
| 转派 Bug | `zentao17 assign <id> --to <账号> [-c "备注"]`（网页会话通道，保留原状态） |
| 添加备注 | `zentao17 comment <id> -c "备注"`（网页会话通道，不改状态） |
| 备注从文件读 | 所有写命令都可用 `-F <UTF-8 文件>` 代替 `-c`（`-c -` 读标准输入）；见「中日文备注的传入方式」 |
| 环境自检 | `zentao17 doctor [--probe "<样本>"] [--probe-file <文件>]`（见「开工自检」第 6 条） |
| 版本与同步状态 | `zentao17 self-update`（只报告，不拉取） |

常用选项：`--limit 50 --page 1` 分页；`--all` 取全部页；`--order id_desc` 排序；`--json` 输出原始 JSON 供程序处理；`--insecure` 忽略自签名证书（全局参数，放在子命令前）。

## 写命令的回读与退出码（防重复写）

resolve／close／activate／assign／comment 都会**先读、再写、再回读 actions 自验证**，只认本次新增的 action：

| 退出码 | 含义 | 下一步 |
|---|---|---|
| 0 | 已生效；或目标状态已满足（如已是 resolved），提示「未重复执行」 | 继续 |
| 1 | 服务端明确拒绝、参数错误 | 按错误信息处理 |
| 3 | 回读确认**未生效**（含网络中断后回读确认未写入） | 核对后可重试 |
| 4 | **结果未知**：写请求中断且回读也失败 | 先 `zentao17 bug <id>` 核对 actions，确认未生效再重试；**切勿直接重试** |
| 5 | 备注**疑似编码损坏**（连续问号、U+FFFD、「ã€」类错码、文件不是 UTF-8），已拦截、**未写入** | 执行 `zentao17 doctor`，改用 `-F` 传 UTF-8 文件后重试；确认内容本来如此才加 `--allow-suspicious` |
| 6 | 已写入，但禅道**保存的备注与发送内容不一致** | **不要重复写同样内容**；先 `zentao17 doctor` 修好环境，再追加一条「【乱码修正】」备注说明以新备注为准 |
| 7 | 备注**未通过上层技能的模板校验**，已拦截、**未写入** | 按输出逐条改备注后重试；不得用 `--skip-lint` 绕过，只有用户明确要求时才可以跳过 |

**备注模板校验**：上层技能可以规定备注格式。写命令发出前，zentao17 会查找校验脚本（环境变量 `ZENTAO17_COMMENT_LINT` 指定，否则从当前目录向上找 `.agents/skills/*/scripts/zentao17_comment_lint.py`），把备注从标准输入传给它，并附上命令、读者账号与角色、解决方案、本人姓名与账号。读者：resolve／close 是开单人（按测试），assign 是 `--to`，activate 是 `--assign`（不带时为上次解决人），comment 是当前指派人；角色按 `LOCAL.md`「常用角色账号」判定（产品、后端、本人；账号等于 `whoami` 的也算本人），其余按测试，上层校验脚本有自己的角色表时以它为准。校验脚本约定退出码 10＝不符合模板（zentao17 报退出码 7），其他非 0 视为脚本出错（报退出码 1）。找不到脚本时不校验；`zentao17 doctor` 会显示当前用的是哪个脚本。所以写禅道时，要在项目目录（如 worktree 的 `frontend`）下执行 zentao17。

读请求遇到超时、连接重置会自动重试 3 次；写请求不自动重试，以回读为准。超时不等于失败。

## 中日文备注的传入方式

- **推荐**：用文件工具把备注写成 UTF-8 文件，再 `-F <文件>` 传入。文件工具直接写 UTF-8，不经过 shell 的编码转换，在任何系统上都可靠。也认带 BOM 的 UTF-8／UTF-16。
- `-c "…"` 只在本会话 `doctor --probe` 通过后使用。
- **不要**用管道把中日文喂给 zentao17（`echo … | zentao17 … -c -`），也不要用 PowerShell 的 `Set-Content` 生成备注文件：Windows PowerShell 5.1 的管道按 ASCII 编码、`Set-Content` 按 ANSI 代码页写文件，中日文会被换成「?」（`Out-File` 默认写带 BOM 的 UTF-16，zentao17 能读，但仍推荐用文件工具）。
- 写入前的拦截只能识别常见的损坏形态；GBK／UTF-8 互相误转之类不留明显痕迹的情况，要靠第 6 条自检把住通道。

## 意图识别与解析规则

**禅道网页链接解析**（Path-Info 格式 `http://<禅道主机>/<模块>-<方法>-<ID>.html`，主机地址见本目录 `LOCAL.md`）：
- `bug-view-<BugID>.html` → `zentao17 bug <BugID>`
- `execution-bug-<执行ID>.html` → `zentao17 bugs --execution <执行ID>`
- `product-browse-<产品ID>.html` → `zentao17 bugs --product <产品ID>`
- 链接中的 `?tid=xxx` 是网页会话参数，忽略

**课题号映射表与 Bug 拉取口径**维护在本目录 `LOCAL.md`（课题号是公司外部系统编号，不在禅道数据中，人工维护）。需要把课题号对应到禅道产品/项目/执行时，先读该文件。

用户给出**新课题号**时：先 `zentao17 projects --search <课题号> --all` 查编号；查不到则用项目名搜或询问用户对应哪个禅道项目，确认后把映射补进 `LOCAL.md` 的映射表。

**拉取口径**：
- **产品级是权威来源**：测试员从产品入口提单，新单常常不挂执行。执行级查询只能看到已挂执行的子集，会漏单。批量处理一律用 `bugs --product <id>`，执行级仅作补充。
- 项目级接口（`/projects/{id}/bugs`）对普通账号返回 403。
- **状态筛选在客户端执行**：执行级接口忽略 `status` 参数（`unclosed` 也会返回已关闭单），产品级默认只返回未关闭单；脚本对 `--status`／`--keyword`／`--assigned` 一律取全部页后在本地过滤，输出首行会注明。

## 巡检预检（changes）

给定时巡检用，目的是「没有变化就不做重活」：

- `zentao17 changes --product <id> --state <快照>`：拉产品未关闭全量，与快照比对，输出 `NEW`（快照里没见过的未关闭单，`--keyword` 只做命中标注不过滤）、`CHANGED`（跟踪单的状态／指派人／最新 action 变化，附新增 actions）、`CLOSED`（跟踪单已关闭），末行 `RESULT: none|changed`。
- 跟踪集合用 `--set-tracked`（整体替换）／`--track`／`--untrack` 维护；新纳入跟踪的单首次只建基线，不算变化。
- `--own-prefix "<前缀>"`：actor 是本人（`whoami` 的姓名）且备注以该前缀开头的动作视为本方动作，不算变化（如自动代理自己的备注、转派、resolve）。不带前缀的本人动作仍算变化（那是开发者亲手操作）。
- **`--update` 只在本轮处理完成后执行**：把当前未关闭单全部记为「已见过」、刷新跟踪单指纹。预检阶段不带 `--update`，否则新单会在未分诊前被标记为已见。收尾时先不带 `--update` 再跑一次，确认处理期间没有新出现的变化，再带 `--update` 落盘。

From huyikai/skills, MIT.

More from huyikai/skills