SD ZenTao CLI

sd-zentao-cli 是面向内部禅道开源版 21.4 的 CLI，提供 szt 命令，用于查询和处理禅道任务、Bug、子任务和工时。

快速开始

可以直接复制下面这段话发给 AI：

请先执行下面这条命令安装 SD 禅道 CLI：

npm install -g --registry=https://registry.npmjs.org/ @shendu-sdt/sd-zentao-cli

安装完成后，执行：

szt setup

之后请优先用 szt 查询和处理禅道任务、Bug、工时，例如 szt my tasks、szt my bugs、szt my workhours --week。

团队成员优先使用 npm 全局安装：

npm install -g @shendu-sdt/sd-zentao-cli
szt setup

初始化完成后，可以继续检查连接和查看当前任务：

szt doctor
szt my tasks

szt setup 会完成登录、保存密码、同步 AI skill。后续登录态过期时，CLI 会优先使用已保存的账号密码自动刷新。

怎么和 AI 聊

先把这几句当成最佳实践直接用，AI 会按当前 CLI 能力去执行：

帮我总结一下我今天做了什么
feat/v16.4 对应父任务 79829，记录昨天的工时
周二我已经整理过一次，这周还有哪些提交没处理
帮我写一份本周周报，总结我做的工作
确认 Bug 21305
把 Bug 21305 标记为已解决，备注已修复采购订单毛重字段取值问题

推荐心智模型：

• CLI 负责汇总事实：Git 提交、分支、任务映射、扫描状态、Bug/任务查询、工时写入。
• AI 负责协助用户决策：先扫什么、要不要补任务映射、周报怎么归纳、工时草稿怎么整理。
• 不让 CLI 替用户做主观判断：不自动决定工时内容、耗时、是否真的已记到禅道。

最佳实践

工时与提交

场景零：先把工作仓库快速配置好

👤 开发者：“把这几个项目加到工时仓库里：/path/to/demo-admin、/path/to/demo-web。” 🤖 AI 助手：“我先批量写入工作仓库配置，再回显当前配置结果给您确认。”

AI 执行：

szt work repo add /path/to/demo-admin /path/to/demo-web
szt work repo list

szt work repo add 会直接把仓库写入 ~/.szt-cli/work-repos.json。AI 场景下，优先使用 szt work repo add/list/remove 维护配置，不建议让用户手动编辑 JSON；只有做批量迁移、备份或排查时，才需要直接打开这个文件。

场景一：先看今天做了什么

👤 开发者：“帮我总结一下我今天的工作。” 🤖 AI 助手：“我先扫描今天的 Git 提交记录，按仓库、分支和日期汇总给您。”

AI 执行：

szt work scan --from 2026-06-06 --to 2026-06-06

如果提交标题不够具体，CLI 会自动补充变更文件摘要。AI 在此基础上再帮您概括，不直接替您生成主观工时。

场景二：后置补充分支对应的任务 ID

👤 开发者：“feat/v16.4 对应父任务 79829，记录昨天的工时。” 🤖 AI 助手：“我先保存这个分支和任务的映射，再重新扫描昨天的提交内容。”

AI 执行：

szt work branch set demo-admin feat/v16.4 --task 79829 --parent
szt work scan --from 2026-06-05 --to 2026-06-05

之后扫描结果会带上 [父任务 79829]。CLI 只保存分支和任务 ID 的对应关系，不自动创建子任务、不直接写工时。

场景三：周中已经处理过一部分提交，后续只想看没汇总过的

👤 开发者：“周二我已经整理过一次，这周还有哪些提交没处理？” 🤖 AI 助手：“我先把之前已经确认汇总的提交保存起来，后续只看未汇总提交。”

AI 执行：

szt work scan --from 2026-06-02 --to 2026-06-02 --save-scan
szt work scan --unscanned

~/.szt-cli/work-scans.json 只记录 commit hash 和摘要，用来区分“哪些提交已经汇总过”；工时是否记录、记录到哪个任务、耗时多少仍由用户决定。

周报

场景四：生成并总结周报

👤 开发者：“帮我写一份本周周报，总结我做的工作。” 🤖 AI 助手：“我先按周报周期扫描提交，再帮您整理成周报草稿。”

AI 执行：

szt work scan --week-mode report

周报周期规则：

• 周六：周一到周六
• 周日：周一到周日
• 周五：默认周一到周五
• 如果用户明确说“本周包括上周六”，再执行：

szt work scan --week-mode report --include-last-saturday

Bug 流程

场景五：查看我的 Bug

👤 开发者：“查看我的 Bug。” 🤖 AI 助手：“我先拉取当前指派给您的未关闭 Bug 列表，方便您选择要处理哪一个。”

AI 执行：

szt my bugs

只看激活或未确认 Bug 时：

szt my bugs --open
szt my bugs --unconfirmed

szt my bugs 默认显示当前登录账号被指派、且未关闭的 Bug。AI 应优先用这个列表帮助用户选择 Bug，不要一开始就拉大体量详情。

场景六：帮我修改 Bug

👤 开发者：“帮我修改 Bug 21305。” 🤖 AI 助手：“我先低成本核对标题和文字描述，判断是否需要查看操作记录或截图，再进入代码定位。”

AI 执行：

szt bug title 21305 --plain
szt bug steps 21305

如果 Bug 是重新激活、涉及评论历史，或文字描述里看不出为什么被打回，再执行：

szt bug actions 21305

只有当描述明确说“看图 / 如图 / 截图”，或文字不足以定位问题时，才拉图片：

szt bug steps 21305 --images

AI 拿到 Bug 信息后再去代码库定位、修改、验证。不要把“帮我修改 Bug”理解成直接确认或解决 Bug；状态流转应等用户确认修复后再执行。

场景七：确认 Bug

👤 开发者：“确认 Bug 21305。” 🤖 AI 助手：“这是把 Bug 状态标记为已确认，不是查看或分析。我先核对标题，再请您确认。”

AI 执行：

szt bug title 21305 --plain
szt bug confirm 21305 --dry-run
szt bug confirm 21305

场景八：解决 Bug

👤 开发者：“把 Bug 21305 标记为已解决，备注已修复采购订单毛重字段取值问题。” 🤖 AI 助手：“我先轻量核对标题和状态，然后直接执行 resolve，不额外追问一次，也不先停在 plan 或 dry-run。”

AI 执行：

szt bug title 21305 --plain
szt bug resolve 21305 --comment "已修复：采购订单毛重字段取值问题"

何时看详细说明

• AI 场景白话说明： AI_USER_GUIDE.md
• 想看完整命令和参数：继续看下面“安装 / 初始化 / 常规命令”

安装

npm install -g @shendu-sdt/sd-zentao-cli
szt --help

升级到最新版本：

npm install -g @shendu-sdt/sd-zentao-cli@latest

卸载：

npm uninstall -g @shendu-sdt/sd-zentao-cli

上面这条命令只会卸载全局 CLI，不会自动删除已经同步到各个 AI 客户端的 skill 文件，也不会删除本机登录态和配置。

如果要彻底卸载，可以继续按下面清理。

清理全局 AI skill（macOS / Linux）：

rm -rf ~/.codex/skills/sd-zentao-cli
rm -rf ~/.agents/skills/sd-zentao-cli
rm -rf ~/.claude/skills/sd-zentao-cli
rm -rf ~/.cursor/skills/sd-zentao-cli
rm -rf ~/.qoder/skills/sd-zentao-cli
rm -rf ~/.gemini/config/skills/sd-zentao-cli
rm -rf ~/.antigravity/skills/sd-zentao-cli
rm -rf ~/.windsurf/skills/sd-zentao-cli
rm -rf ~/.aider/skills/sd-zentao-cli
rm -rf ~/.trae/skills/sd-zentao-cli
rm -rf ~/.hermes/skills/sd-zentao-cli

如果之前还残留老目录名，也可以一并删除：

rm -rf ~/.codex/skills/zentao-cli
rm -rf ~/.agents/skills/zentao-cli
rm -rf ~/.claude/skills/zentao-cli
rm -rf ~/.cursor/skills/zentao-cli
rm -rf ~/.qoder/skills/zentao-cli
rm -rf ~/.gemini/config/skills/zentao-cli
rm -rf ~/.antigravity/skills/zentao-cli
rm -rf ~/.windsurf/skills/zentao-cli
rm -rf ~/.aider/skills/zentao-cli
rm -rf ~/.trae/skills/zentao-cli
rm -rf ~/.hermes/skills/zentao-cli

如果之前给某个项目写过项目级规则，还要手动删除项目里的规则文件：

rm -f /path/to/project/.cursor/rules/sd-zentao-cli.mdc
rm -rf /path/to/project/.antigravity/skills/sd-zentao-cli
rm -f /path/to/project/.antigravity/rules.md

如果连登录态和本地配置也要一起清掉，再删除：

rm -rf ~/.szt-cli

初始化

首次使用推荐运行：

szt setup

也可以指定账号，密码会用非明文交互输入：

szt setup -a <账号>

直接登录也会使用非明文密码输入，并默认把密码保存到本机配置，用于后续登录态过期时自动刷新：

szt login -a <账号>

常用登录态命令：

szt auth status
szt relogin
szt logout
szt logout --forget-credentials

内部默认禅道地址是 https://pm.sdpjw.com/index.php，一般不需要配置。只有连接其他环境时才需要修改：

szt config set url https://zentao.example.com/zentao

配置默认保存在 ~/.szt-cli/config.json。已保存的密码只写在本机配置文件里，文件权限会收紧为 0600，szt config show 会隐藏密码、token 和 session。

AI 助手接入

sd-zentao-cli 面向用户的核心价值是让 AI 助手能稳定调用真实 CLI，而不是让 AI 记住禅道规则。szt setup 会同步 AI skill，让 AI 知道什么时候应该调用 szt 查禅道、记录工时、处理 Bug 或生成工作总结。

安装和 szt setup 会把 AI skill 同步到常见目录：

~/.codex/skills/sd-zentao-cli/SKILL.md
~/.agents/skills/sd-zentao-cli/SKILL.md
~/.claude/skills/sd-zentao-cli/SKILL.md
~/.cursor/skills/sd-zentao-cli/SKILL.md
~/.qoder/skills/sd-zentao-cli/SKILL.md

同步 skill 后，AI 通常能识别这些意图：

查我的任务
查看我的 Bug
记录今天工时

如果安装工具跳过了 postinstall，可手动同步：

npm run sync-skill

Codex Desktop

Codex Desktop 可以读取 ~/.codex/skills/sd-zentao-cli/SKILL.md，所以 szt setup 后一般能识别“查任务 / 查 Bug / 记录工时 / 帮我修改 Bug”等用户意图。

Claude Code

szt setup 会同步：

~/.claude/skills/sd-zentao-cli/SKILL.md

Claude Code 看到“查任务 / 查 Bug / 记录工时 / 帮我修改 Bug”时，应选择这个 skill 并调用对应 szt 命令。也可以显式触发：

使用 sd-zentao-cli 技能，查看我的 Bug

Claude Desktop

Claude Desktop 通常不会自动读取本机 ~/.claude/skills 目录，也不会读取 Claude Code 的 hook。也就是说：

• szt setup 可以同步本机 skill 文件，但不等于 Claude Desktop 已启用这个 skill。
• 当前 sd-zentao-cli 没有内置 Claude Desktop skill 包上传流程。

Claude Desktop 里使用禅道功能时，推荐直接明确告诉 AI：

请使用 sd-zentao-cli，通过 szt my bugs 查看我当前的 Bug。

如果需要稳定识别，需要在客户端侧手动配置或上传对应 skill；本 CLI 当前不自动写入 Claude Desktop 配置。

Qoder

szt setup 会同步：

~/.qoder/skills/sd-zentao-cli/SKILL.md

Qoder 看到“查任务 / 查 Bug / 记录工时 / 帮我修改 Bug”时，应优先调用 szt，不要自行猜测禅道数据。

Cursor

Cursor 默认使用全局 skill；如果某个项目需要项目级规则，可以运行：

szt setup --cursor-project /path/to/project

这会写入：

/path/to/project/.cursor/rules/sd-zentao-cli.mdc

Cursor 规则会提示 AI 使用 szt 查询真实任务、Bug、工时和提交数据。

🪙 Token 极致节省设计

本项目在 AI 场景下的工作流遵循严格的 Token 优化规范，以降低开发者的 API 使用成本：

1. 按需逐步加载：
   • Bug 分析：默认只跑 szt bug steps 读取文字步骤。仅在包含截图且文字不足以定位时，AI 才会按需使用 szt bug steps --images 拉取图片链接，避免图像/大体积上下文吞噬数千 Token。
   • 对象确认：在指派、解决 Bug 状态流转前，AI 被要求仅读取单行 szt bug title <ID> --plain 进行轻量确认，拒绝拉取大体量的原始 Bug 报表。
2. 命令输出过滤 (rtk 代理)：
   • 团队环境支持全局 rtk (Rust Token Killer) 重写，对所有底层 CLI 命令输出进行高比例冗余过滤与内容压缩，为 AI 操作额外节省 60% ~ 90% 的 Token 损耗。
3. 精准意图匹配：
   • 技能定义（SKILL.md）显式规范了命令映射，防范 AI 由于理解偏差多次尝试不同命令而产生的无用 Token 浪费。

其他常规命令示例

下面示例面向 Codex、Claude、Cursor 这类 AI 助手。AI 应先查询、预览和确认，再执行写操作。

查看我的 Bug

用户说：

查看我的 Bug

AI 执行：

szt my bugs

只看激活或未确认 Bug 时：

szt my bugs --open
szt my bugs --unconfirmed

修改 Bug

用户说：

帮我修改 Bug 21305

AI 应先读取 Bug 标题和描述，必要时再看操作记录或图片：

szt bug title 21305 --plain
szt bug steps 21305
szt bug actions 21305

如果文字不足以定位问题，或 Bug 明确要求看截图，再执行：

szt bug steps 21305 --images

确认 Bug

用户说：

确认 Bug 21305

这里表示把 Bug 标记为已确认，不是查看或分析 Bug。AI 应先核对标题，再让用户确认：

szt bug title 21305 --plain
szt bug confirm 21305 --dry-run
szt bug confirm 21305

解决 Bug

用户说：

把 Bug 21305 标记为已解决，备注已修复采购订单毛重字段取值问题

AI 应先做轻量标题校对，然后直接执行 szt bug resolve：

szt bug title 21305 --plain
szt bug resolve 21305 --comment "已修复：采购订单毛重字段取值问题"

记录今天的工时

用户说：

帮我记录今天的工时

如果用户没有给任务 ID，AI 应先拉当前任务列表：

szt my tasks

用户确认任务后，再整理工时草稿并预览。例如用户确认任务 80576，并给出 4 条工时内容和统一剩余工时 40：

szt workhour add --task 80576 --date today --left 40 \
  "印尼销售订单物流节点问题修改" "2" \
  "补充操作日期选择和手动输入校验" "2" \
  "提交前校验及异常提示优化" "2" \
  "回归自测并整理处理记录" "2" \
  --dry-run

4 条及以上工时使用 --left 40 时，CLI 会把最后一条默认剩余工时收口为 0。如果用户逐条指定剩余工时，例如 8 6 4 2，则最后一条保持用户输入的 2。

扫描本周提交

首次使用运行向导，先填写 Git 作者，再填写本机 Git 仓库绝对路径；作者和项目路径都支持中文/英文逗号分隔。项目名默认使用路径最后一段，后续不用每周配置分支：

szt work setup

快速获取当前项目路径：

# macOS / Linux：先 cd 到项目目录
pwd

# Windows PowerShell：先 cd 到项目目录
(Get-Location).Path

# Windows CMD：先 cd 到项目目录
cd

也可以用命令批量追加项目：

szt work repo add /path/to/demo-admin /path/to/demo-web
szt work repo list
szt work repo remove demo-web
szt work branch set demo-admin feat/v16.4 --task 79829 --parent
szt work branch list

配置会保存到 ~/.szt-cli/work-repos.json，格式类似：

{
  "authors": ["张三", "zhangsan"],
  "repos": [
    { "name": "demo-admin", "path": "/path/to/demo-admin" },
    { "name": "demo-web", "path": "/path/to/demo-web" }
  ]
}

扫描默认周期是上周六到本周五；如果今天还没到周五，就截止到当天：

szt work scan
szt work scan --week-mode report
szt work scan --week-mode report --include-last-saturday
szt work draft
szt work scan --unscanned
szt work scan --save-scan
szt --json work scan
szt --json work draft
szt work scan --from 2026-05-30 --to 2026-06-05
szt my workhours --week
szt my workhours --yesterday

扫描结果会按仓库、分支、日期聚合提交，并附带 AI 工时草稿提示。如果提交标题过于简略（如“修改”“优化”“fix”），CLI 会读取该 commit 的变更文件列表并补充短摘要。AI 后续应结合 szt my tasks 的 taskType 选择子任务；如果关联到父任务，通常先创建子任务再记录工时。

szt work scan 默认使用工时结算周：上周六到今天/本周五。写周报时可切到周报周期：

• szt work scan --week-mode report：默认按周一到今天统计。
• 如果当天是周五，且用户明确说“本周包括上周六”，再加 --include-last-saturday，按上周六到周五统计。

如果后续才知道某个分支对应的禅道任务，可以补充映射：

szt work branch set demo-admin feat/v16.4 --task 79829 --parent
szt work branch set demo-web fix-pay-0605 --task 81379 --child

之后 szt work scan 和 szt work draft 会在对应分支提交前显示 [父任务 79829] 或 [子任务 81379]。CLI 只保存分支和任务 ID 的对应关系，不自动创建任务、不写工时。

szt work draft 会基于同一批扫描结果生成候选工时草稿，按日期列出每天最多 4-5 条、默认每条 1.5h 的内容建议。它不会写入禅道，提交前仍需要用 szt my tasks 确认子任务和剩余工时。

如果本周中途已经人工处理过一部分提交，可以把本次扫描结果保存为“已扫描”：

szt work scan --from 2026-06-02 --to 2026-06-02 --save-scan
szt work scan --unscanned

扫描状态保存到 ~/.szt-cli/work-scans.json。它只记录 commit hash 和提交摘要，用来区分“哪些提交已经被汇总过”；工时是否记录、记录到哪个任务、耗时多少仍由用户决定。

查看真实已登记工时

szt my workhours 查询禅道里已经登记的真实工时，不读取本地草稿，也不扫描 Git 提交；当前仅支持 legacy session：

szt my workhours
szt my workhours --today
szt my workhours --yesterday
szt my workhours --week
szt my workhours --date 2026-06-10
szt my workhours --from 2026-06-06 --to 2026-06-12
szt --json my workhours --week

默认查看今天。--week 使用工时结算周：上周六到本周五；如果今天还没到周五，就截止到当天。输出先按天汇总，再列出每条真实工时明细。查询会分页读取“我的贡献”中创建、指派、完成、关闭相关的历史任务，并按日期范围筛选真实工时，因此不会只局限于当前任务列表第一页或单一贡献分类；较长时间范围会比普通任务查询更慢。

记录指定日期的工时

用户说：

记录 2026-05-26 的工时，任务为 80576，工时为 物流节点问题修改 2、日期校验优化 2、提交交互优化 2、回归自测 2，剩余工时 40

AI 应先生成 dry-run：

szt workhour add --task 80576 --date 2026-05-26 --left 40 \
  "物流节点问题修改" "2" \
  "日期校验优化" "2" \
  "提交交互优化" "2" \
  "回归自测" "2" \
  --dry-run

用户确认预览无误后，再执行不带 --dry-run 的正式命令。写操作不能在非交互式终端用 --yes 跳过确认。

配置命令

szt setup
szt setup --cursor-project /path/to/project
szt auth status
szt relogin
szt me
szt doctor
szt logout
szt logout --forget-credentials

如果需要测试目录隔离，可以用 SZT_CLI_HOME 指定配置目录：

SZT_CLI_HOME=/tmp/szt-test szt doctor

传入 .../index.php 形式的地址时，CLI 会自动归一化为部署根路径，避免 legacy API 重复拼接 index.php。

My 命令

szt my tasks
szt my tasks --status wait,doing
szt my tasks --all --limit 50
szt my workhours
szt my workhours --today
szt my workhours --yesterday
szt my workhours --week
szt my workhours --from 2026-06-06 --to 2026-06-12
szt my bugs
szt my bugs --open
szt my bugs --unconfirmed
szt my bugs --confirmed
szt my bugs --status active,resolved
szt --json my tasks

szt my tasks 默认只显示当前登录账号相关、且未完成的任务，并在 taskType 列标识 父任务、子任务 或普通 任务，便于记录工时前判断是否需要先建子任务。若禅道任务返回了 mode 字段，CLI 还会额外显示 taskMode=多人任务；部分多人任务在禅道列表接口里 assignedTo 可能为空，CLI 不会再把这类任务误过滤掉。 szt my workhours 默认查看今天在禅道真实登记的工时；--yesterday 查看昨天，--week 查看本工时周，--from/--to 查看指定范围。它会分页读取“我的贡献”中创建、指派、完成、关闭相关的历史任务后再读取真实工时明细，不是本地草稿命令，也不会写入禅道；当前仅支持 legacy session。 szt my bugs 默认只显示当前登录账号被指派、且未关闭的 Bug；--open 只看激活 Bug，--unconfirmed 只看未确认 Bug，--confirmed 只看已确认 Bug。

Bug 命令

szt bug list --product 1
szt bug title 123
szt bug title 123 --plain
szt bug steps 123
szt bug steps 123 --images
szt bug actions 123
szt bug view 123 --brief
szt bug view 123
szt bug view 123 --actions
szt bug view 123 --ai
szt --json bug view 123
szt bug assign 123 --to zhangsan --dry-run
szt bug assign 123 --to zhangsan
szt bug resolve 123 --comment "已修复采购订单毛重字段取值问题" --dry-run
szt bug resolve 123 --comment "已修复采购订单毛重字段取值问题"

• szt bug title <id> / szt bug view <id> --brief 只输出 ID、标题、状态、指派人、创建人、严重程度、优先级等轻量字段，状态会映射成 激活(active) 这类中文值；如果 Bug 被重新激活，会带最近一次激活评论，适合确认操作前使用，避免把图片和完整历史记录带进 AI 上下文。
• szt bug title <id> --plain 输出单行纯文本，severity 和 pri 会放在最后，并映射成 一般(3)、低(3) 这类中文值；--plain 与全局 --json 互斥。
• szt bug steps <id> 输出 Bug ID、标题、描述文字、严重程度、优先级，不带图片链接；AI 定位问题时应先看这个输出。
• szt bug steps <id> --images 才输出描述里的图片链接，只有文字无法判断、或 Bug 明确依赖截图时再使用。
• szt bug actions <id> / szt bug view <id> --actions 输出 Bug 操作记录、评论和关键字段变更，适合判断谁解决、谁激活、激活原因和测试补充说明。
• szt bug view <id> 默认输出精简 Bug 详情，适合人工快速查看。
• szt bug view <id> --ai 输出完整 AI 分析结构，会保留图片链接；如果 Bug 被重新激活，也会包含最近一次激活评论。只在需要上下文、人员、产品、执行等字段一起分析时使用。
• szt --json bug view <id> 输出禅道原始完整响应，适合排查字段或兼容问题。
• “确认 Bug 21305 / 确认bug 21305”表示把 Bug 状态标记为已确认。AI 应先用 szt bug title <id> --plain 核对标题，向用户确认后执行 szt bug confirm <id>，不要理解成查看或分析 Bug。
• szt bug resolve <id> 固定按你们当前流程提交“解决方案=已解决、解决版本=主干”，优先指派回 Bug 创建人；取不到创建人时才保留默认指派人。可选 --comment 填备注；CLI 会把空备注或“已修复”这类泛备注整理为基于 Bug 标题的短备注。该命令会直接提交，不做 AI 二次追问，也不显示 CLI 最终确认。普通单条 Bug 解决不需要先停在 --dry-run，除非用户明确要预览，或者这是批量/高风险操作。
• szt bug confirm/assign 的 --dry-run 会先输出面向人和 AI 的摘要，再输出 legacy payload；正式提交时 CLI 会显示 Bug 标题和关键提交字段再要求确认。szt bug resolve 则直接提交。

Task 命令

szt task list --execution 49
szt task list --project 5
szt task view 88
szt task children 88
szt task finish 88 --dry-run
szt task finish 88 --consumed 2 --comment "done"

• szt task children <父任务ID> 只输出父任务下的子任务列表，比 szt task view <父任务ID> 更适合日常查看和 AI 上下文。

创建子任务

给父任务添加子任务时，只需要填写父任务 ID 和子任务名称：

szt task create-child --parent 88 --name "子任务名称" --dry-run
szt task create-child --parent 88 --name "子任务名称"

task create-child 会先读取父任务，再继承以下字段：

• 所属产品：product
• 当前实例所属产品兼容字段：keywords
• 执行：execution
• 类型：type
• 指派人：assignedTo
• 优先级：pri
• 状态：status

如果父任务是禅道的多人任务，CLI 会直接拒绝创建。禅道官方规则就是“多人任务不能创建子任务”；这类任务请直接用 szt workhour add --task <taskID> ... 记录工时，或者先把任务改成普通父子任务结构再拆分。

团队内部规则：新建子任务的预计工时默认写 0，剩余工时默认写 0。只有用户明确说“预计工时/计划工时/estimate 是 X 小时”时，才允许额外传 --estimate <hours>。用户说“耗时 X 小时”“记录 X 小时工时”只代表实际消耗，不能转换成 --estimate。

真实创建前建议先跑 --dry-run。如果已保存密码，登录态过期会自动刷新并重试；未保存密码时再手动登录：

szt relogin

Workhour 命令

日常记录工时时，CLI 会先看 --task 指向的任务类型：

• 普通父任务：默认先创建当天子任务，再把工时记到新子任务上
• 多人父任务：不能创建子任务，直接记到父任务
• 子任务 / 普通任务：直接记到当前任务
• 只有显式传 --no-child-task 时，普通父任务才会直接记到父任务

示例：

szt workhour add --task 79345 --date today --left 40 \
  "完成了印尼销售订单创建接口联调" "2" \
  "整理销售订单创建接口异常分支" "2" \
  "修正销售订单创建参数映射问题" "1.5" \
  "补充销售订单创建流程自测记录" "3" \
  --dry-run
szt workhour add --task 79345 --date today --left 40 \
  "完成了印尼销售订单创建接口联调" "2" \
  "整理销售订单创建接口异常分支" "2" \
  "修正销售订单创建参数映射问题" "1.5" \
  "补充销售订单创建流程自测记录" "3"

• add 会先读取 --task 指定的任务详情，再按默认规则决定是“直接记工时”还是“先创建当天子任务再记工时”。
• add 只允许给当前登录账号自己的任务记录工时：任务指派人必须是当前账号、当前账号在任务团队成员里，或任务是 assignedTo 为空的多人任务；否则会拒绝写入。
• 工时内容来自当天提交记录、AI 沟通总结或人工整理，格式为 "工时内容" "耗时" "剩余"。
• 如果用户只说“帮我建工时/记录工时”但没有给任务 ID，AI 应先执行 szt my tasks 拉当前指派任务列表，再让用户选择/确认任务 ID。
• 单次工时最多 5 条；总工时不再强制 8-9 小时。
• 每条耗时允许 1-6 小时，剩余工时不能小于 0。
• 每条工时包含日期、工时内容、耗时、剩余。剩余工时可逐条填写；未逐条填写时使用 --left <hours> 或 szt config set workhourDefaultLeft <hours> 配置的默认值。
• 当本次同一任务同一天记录 4 条及以上工时时，只有“由 --left 或配置默认值补出来”的最后一条剩余工时会自动归 0；用户逐条显式填写的最后一条剩余工时不会被覆盖。
• 如果 config 还没有默认剩余工时，且用户提供的是统一剩余工时，可用 --left <hours> 先预览；CLI 会提示是否把该值保存为默认剩余工时。
• 记录工时不修改任务预计工时；团队内部规则是预计工时保持 0。不要把耗时、工时、consumed 转换成 --estimate。
• --date 支持 today 或 YYYY-MM-DD，例如 --date 2026-05-20。补写历史工时时，draft、set、status、submit 都使用同一个日期。
• 如果普通父任务需要跳过“自动创建当天子任务”这条默认规则，可显式传 --no-child-task，直接把工时记到父任务。
• add 默认需要确认；正式提交前会读取任务名称，并在确认提示里展示任务 ID、任务名、日期、总耗时和明细。建议先跑 --dry-run 检查 payload。
• 确认必须来自交互式终端，不能用 echo "y" | szt ... 这类管道自动确认，也不能在非交互式终端用 --yes 跳过确认。必须先跑 --dry-run 预览，再到交互式终端提交。

如果确实需要“先创建当天子任务，再把工时写到子任务”，仍可使用兼容流程：

szt workhour draft --parent 79328 --date today
szt workhour set --date today "完成了印尼销售订单创建接口联调" "2"
szt workhour submit --date today --dry-run
szt workhour submit --date today

• draft 会保存草稿到 ~/.szt-cli/workhours/YYYY-MM-DD.json，默认只分配日期、耗时和剩余，不自动生成具体工时内容。
• 如果父任务是多人任务，draft/submit 也会直接拒绝，因为底层同样需要先创建子任务。
• draft/submit 创建的当天工时子任务预计工时固定为 0；即使旧草稿里残留了非 0 预计，提交时也会归零。
• set 用来写入从当天提交记录、AI 沟通总结或人工整理得到的工时，格式为 "工时内容" "耗时" "剩余"。
• 使用 "工时内容" "耗时" "剩余" 明确填写耗时时，可以省略 draft --target；子任务预计工时仍默认 0，不会自动使用耗时合计。
• 只有使用旧的 --work 兼容写法、让 CLI 自动分配耗时时，才需要提供 --target；目标工时只要求大于 0 且不超过 24 小时。
• submit 会校验工时内容不能为空。
• submit 默认需要确认；建议先跑 --dry-run 检查 payload。

补写指定日期示例：

szt workhour add --task 79345 --date 2026-05-20 --left 40 \
  "完成了印尼销售订单创建接口联调" "2" \
  "整理销售订单创建接口异常分支" "2" \
  "修正销售订单创建参数映射问题" "1.5" \
  "补充销售订单创建流程自测记录" "3" \
  --dry-run

实现说明

• 当前实现优先尝试 REST 登录：POST /api.php/v1/tokens，后续请求使用 Token 请求头。
• REST 不可用时自动降级到 legacy session：index.php?m=api&f=getSessionID&t=json + user-login。
• legacy session 请求使用 index.php?m=<module>&f=<method>&t=json，更适合当前已验证的 21.4 实例。
• 写操作默认需要交互确认；非交互式终端不能使用 --yes 跳过确认。
• 21.4 的具体路由可能因部署和权限存在差异，doctor 会检查基础连接和登录态。

🔮 未来规划 (Future Plans)

• Git 提交与工时草稿的无缝联动 (szt workhour set --from-git-scan)：支持将 szt work scan 扫描到的当天已关联任务 ID 的 Git commit 信息自动导入到 szt workhour 的本地当天草稿中，进一步简化日常工时录入流程。
• 任务协作状态管理：支持 szt task start <id> (开始任务) 及 szt task assign <id> <account> (指派任务) 等命令，完善任务生命周期的流转。