@kairyou/agent-tools 0.14.0 → 0.16.0

package/README.md

@@ -32,7 +32,7 @@ Usage:
 
 ### at-review
 
-Review changes for correctness bugs, regressions, convention violations, and high-value cleanup findings.
+Review local changes or a hosted PR/MR for correctness bugs, regressions, convention violations, and high-value cleanup findings.
 
 ```bash
 npx -y skills@latest add kairyou/agent-tools --skill at-review -g -y
@@ -40,7 +40,7 @@ npx -y skills@latest add kairyou/agent-tools --skill at-review -g -y
 
 Usage:
 
-- `/at-review [--fix] [<pr|branch|path>]` — reports review findings; `--fix` also applies them
+- `/at-review [--fix] [<pr-or-mr-url|branch|path>]` — reports review findings; private hosted targets require locally available read access, and `--fix` applies fixes only to a matching working tree
 
 ### at-simplify
 
@@ -69,7 +69,7 @@ Usage:
 - `/at-zentao bug <id>` — work a specific bug
 - `/at-zentao task <id>` — work a specific task
 
-Config: `~/.agent-tools/config.jsonc` → `"zentao": { "url", "account", "password" }`. First run guides you; fill `password` in the file yourself (or env `ZENTAO_PASSWORD`), never in chat.
+Config: `~/.agent-tools/config.jsonc` → `"zentao": { "url", "account", "password" }`. The password can be entered directly or referenced with `"password": { "env": "ZENTAO_PASSWORD" }`; never paste credentials or tokens into chat.
 
 ## Integrations
 

package/README.zh-CN.md

@@ -32,7 +32,7 @@ npx -y skills@latest add kairyou/agent-tools --skill at-commit -g -y
 
 ### at-review
 
-审查改动中的正确性 bug, 回归风险, 约定违规和高价值清理项.
+审查本地改动或托管的 PR/MR 中的正确性 bug, 回归风险, 约定违规和高价值清理项.
 
 ```bash
 npx -y skills@latest add kairyou/agent-tools --skill at-review -g -y
@@ -40,7 +40,7 @@ npx -y skills@latest add kairyou/agent-tools --skill at-review -g -y
 
 用法:
 
-- `/at-review [--fix] [<pr|分支|路径>]` — 输出审查结果; 加 `--fix` 则同时应用修复
+- `/at-review [--fix] [<PR/MR-URL|分支|路径>]` — 输出审查结果; 私有托管目标需要本地已有只读访问权限, `--fix` 仅对匹配的工作树应用修复
 
 ### at-simplify
 
@@ -69,7 +69,7 @@ npx -y skills@latest add kairyou/agent-tools --skill at-zentao -g -y
 - `/at-zentao bug <id>` — 直接处理指定 bug
 - `/at-zentao task <id>` — 直接处理指定 task
 
-配置: `~/.agent-tools/config.jsonc` → `"zentao": { "url", "account", "password" }`. 首次使用会引导; `password` 自己填进文件(或设环境变量 `ZENTAO_PASSWORD`), 不要发在对话里.
+配置: `~/.agent-tools/config.jsonc` → `"zentao": { "url", "account", "password" }`. 密码可以直接填写, 也可以使用 `"password": { "env": "ZENTAO_PASSWORD" }` 引用环境变量; 不要在对话中粘贴凭据或 token.
 
 ## Integrations
 

package/config.default.jsonc

@@ -19,9 +19,9 @@
   // log capability: AI session work log; see the extras doc for details.
   "log": {
     "enabled": true,                            // false: pause recording without uninstalling
-    "output": "~/.agent-tools/logs/ai-log.md",  // daily: one file; detailed: a directory
+    "output": "~/.agent-tools/logs/ai-log",     // detailed: one <date>.md file per day; daily: one file
     "language": "zh",                           // zh | en (detailed report headings)
-    "format": "daily",                          // daily | detailed
+    "format": "detailed",                       // detailed | daily
     "projects": [                               // record only these; empty: record everything
       // "C:\\projects\\project-a"
     ]

package/dist/log/hook.mjs

@@ -868,7 +868,8 @@ var ParseErrorCode;
 // integrations/log/hook.mjs
 var MAX_SNAPSHOT_BYTES = 512 * 1024;
 var MIN_RESULT_SUMMARY_LENGTH = 24;
-var DAILY_ITEM_MAX_CHARS = 160;
+var DAILY_ITEM_TARGET_CHARS = 160;
+var DAILY_ITEM_HARD_MAX_CHARS = 320;
 var INSTALL_ROOT = process.env.AGENT_TOOLS_HOME || path.join(os.homedir(), ".agent-tools");
 var CACHE_ROOT = path.join(INSTALL_ROOT, "cache", "log");
 async function main() {
@@ -980,7 +981,8 @@ async function loadLogConfig() {
   }
   const section = isPlainObject(parsed.log) ? parsed.log : {};
   const enabled = section.enabled !== false;
-  const format2 = pickFormat(section.format, "daily");
+  const inferredFormat = section.format === void 0 && typeof section.output === "string" && section.output.trim().toLowerCase().endsWith(".md") ? "daily" : "detailed";
+  const format2 = pickFormat(section.format, inferredFormat);
   const language = pickLanguage(section.language, "zh");
   const output = pickOutput(section.output, format2, defaultOutput(format2));
   const projects = [];
@@ -1239,11 +1241,23 @@ function buildDailyItems(state, scopeKey) {
 function dailyItemText(turn) {
   const request = String(turn.request_text || "");
   const outcome = String(turn.result_summary || "");
-  if (!hasSubstantiveTurn(request, outcome) || isTrivialTurn(request, outcome)) return "";
-  const source = outcome || request;
+  if (!outcome || !hasSubstantiveTurn(request, outcome) || isTrivialTurn(request, outcome)) return "";
+  const source = outcome;
   const flattened = source.split("\n").map((line) => line.replace(/^[#>*\-\s`|]+/, "").trim()).filter(Boolean).join(" ");
   if (!flattened) return "";
-  return flattened.length > DAILY_ITEM_MAX_CHARS ? `${flattened.slice(0, DAILY_ITEM_MAX_CHARS - 3)}...` : flattened;
+  return truncateDailyItem(flattened);
+}
+function truncateDailyItem(text) {
+  if (text.length <= DAILY_ITEM_HARD_MAX_CHARS) return text;
+  const limit = DAILY_ITEM_HARD_MAX_CHARS - 3;
+  const prefix = text.slice(0, limit);
+  const boundaries = [...prefix.matchAll(/[。！？；;]|[.!?](?=\s|$)/g)];
+  const boundary = boundaries.at(-1)?.index;
+  if (boundary !== void 0 && boundary + 1 >= Math.floor(DAILY_ITEM_TARGET_CHARS * 0.6)) {
+    return `${prefix.slice(0, boundary + 1)}...`;
+  }
+  const targetPrefix = text.slice(0, DAILY_ITEM_TARGET_CHARS - 3);
+  return `${targetPrefix}...`;
 }
 async function updateDailyFile(outputFile, day, items) {
   if (items.length === 0) return;

package/docs/en/extras.md

@@ -69,8 +69,8 @@ Independent of and complementary to `at-daily-log` above; use them together or a
 npx -y @kairyou/agent-tools@latest log -a claude codex opencode
 ```
 
-- `format: "daily"` (default): a single markdown file, one dated entry per day, each turn summarized into one line
-- `format: "detailed"`: one full report per day with each turn's request and outcome, the files changed, and approximate lines added/removed (measured against the current file when several turns touch one)
+- `format: "detailed"` (default): one detailed report per day with each turn's request and outcome, the files changed, and estimated lines added and removed
+- `format: "daily"`: writes to a single Markdown file grouped by date; each completed answer with substantive results is recorded as one line, while pending prompts are omitted; content may be truncated by the length limit, so use it only as a lightweight activity index
 - Codex: run `/hooks` once after installing to approve it; opencode: restart after installing or updating
 
 `daily` output example:
@@ -123,9 +123,9 @@ All in `~/.agent-tools/config.jsonc`:
   // log capability: AI session log
   "log": {
     "enabled": true,                // false: pause recording without uninstalling
-    "output": "C:\\logs\\ai-log.md",  // daily: one file; detailed: a directory
+    "output": "C:\\logs\\ai-log",     // detailed: one <date>.md per day; daily: one file
     "language": "zh",                 // zh | en
-    "format": "daily",                // daily | detailed
+    "format": "detailed",             // detailed | daily
     "projects": [                     // optional: record only these; entries may override the keys above
       "C:\\projects\\project-a",
       { "path": "C:\\projects\\project-b", "format": "detailed", "output": "C:\\logs\\project-b" }

package/docs/en/repository-structure.md

@@ -11,10 +11,10 @@ agent-tools/
 ├── skills/            # Reusable Agent Skills.
 │   ├── workflow/      # Workflow-oriented skills.
 │   │   ├── at-commit/   # Conventional Commit message skill.
-│   │   ├── at-review/   # Review changes for bugs and regressions.
+│   │   ├── at-review/   # Review local or hosted changes for bugs and regressions.
 │   │   └── at-simplify/ # Reduce complexity and duplication in changes.
 │   └── integrations/  # Skills that integrate external systems.
-│       └── at-zentao/   # ZenTao bug/task fixing workflow.
+│       └── at-zentao/   # Self-contained ZenTao workflow and secure API script.
 ├── docs/              # Advanced guides and contributor reference.
 ├── tools/             # Maintainer-only upstream sync and repository tooling.
 └── scripts/           # Install, sync, validation, and maintenance scripts.

package/docs/zh-CN/extras.md

@@ -67,8 +67,8 @@ npx -y skills@latest add kairyou/agent-tools --skill at-daily-log -g -y
 npx -y @kairyou/agent-tools@latest log -a claude codex opencode
 ```
 
-- `format: "daily"` (默认): 单一 md 文件, 每天一个日期条目, 每轮对话总结成一行
-- `format: "detailed"`: 每天一份详细报告, 含每轮的请求与结果, 改动的文件和近似的增删行数(多轮改同一文件时按当前文件计算)
+- `format: "detailed"` (默认): 每天生成一份详细报告, 记录每轮请求与结果, 修改的文件, 以及新增/删除代码行数的估算
+- `format: "daily"`: 写入单个 Markdown 文件, 并按日期归档; 每个已完成且有实质结果的回答记录为一行, 不记录未完成的提问; 内容可能因长度限制被截断, 因此仅适合作为轻量活动索引
 - Codex 安装后运行 `/hooks` 批准一次; opencode 安装或更新后需要重启
 
 `daily` 输出示例:
@@ -120,9 +120,9 @@ Changes
   // log capability: AI 会话日志
   "log": {
     "enabled": true,                // false: 临时停止记录, 不用卸载
-    "output": "C:\\logs\\ai-log.md",  // daily: 单一文件; detailed: 目录
+    "output": "C:\\logs\\ai-log",     // detailed: 每天一个 <date>.md; daily: 单一文件
     "language": "zh",                 // zh | en
-    "format": "daily",                // daily | detailed
+    "format": "detailed",             // detailed | daily
     "projects": [                     // 可选: 只记录这些目录, 条目可覆盖上面的键
       "C:\\projects\\project-a",
       { "path": "C:\\projects\\project-b", "format": "detailed", "output": "C:\\logs\\project-b" }

package/docs/zh-CN/repository-structure.md

@@ -11,10 +11,10 @@ agent-tools/
 ├── skills/            # 可复用的 Agent Skills.
 │   ├── workflow/      # 工作流类 skills.
 │   │   ├── at-commit/   # 生成 Conventional Commits message.
-│   │   ├── at-review/   # 审查改动中的 bug 与回归风险.
+│   │   ├── at-review/   # 审查本地或托管改动中的 bug 与回归风险.
 │   │   └── at-simplify/ # 减少改动中的冗余和复杂度.
 │   └── integrations/  # 对接外部系统的 skills.
-│       └── at-zentao/   # 禅道 bug/task 修复工作流.
+│       └── at-zentao/   # 自包含的禅道工作流和安全 API 脚本.
 ├── docs/              # 高级指南和贡献者参考.
 ├── tools/             # 仅供维护者使用的上游同步和仓库工具.
 └── scripts/           # 安装, 同步, 校验和仓库维护脚本.

package/integrations/log/hook.mjs

@@ -26,7 +26,8 @@ import { parse as parseJsonc } from "jsonc-parser";
 
 const MAX_SNAPSHOT_BYTES = 512 * 1024;
 const MIN_RESULT_SUMMARY_LENGTH = 24;
-const DAILY_ITEM_MAX_CHARS = 160;
+const DAILY_ITEM_TARGET_CHARS = 160;
+const DAILY_ITEM_HARD_MAX_CHARS = 320;
 
 const INSTALL_ROOT = process.env.AGENT_TOOLS_HOME || path.join(os.homedir(), ".agent-tools");
 const CACHE_ROOT = path.join(INSTALL_ROOT, "cache", "log");
@@ -167,7 +168,15 @@ async function loadLogConfig() {
   }
   const section = isPlainObject(parsed.log) ? parsed.log : {};
   const enabled = section.enabled !== false;
-  const format = pickFormat(section.format, "daily");
+  // Keep existing file-based configurations on daily while new installs use
+  // detailed by default. Explicit format always wins.
+  const inferredFormat =
+    section.format === undefined &&
+    typeof section.output === "string" &&
+    section.output.trim().toLowerCase().endsWith(".md")
+      ? "daily"
+      : "detailed";
+  const format = pickFormat(section.format, inferredFormat);
   const language = pickLanguage(section.language, "zh");
   const output = pickOutput(section.output, format, defaultOutput(format));
 
@@ -497,8 +506,11 @@ function buildDailyItems(state, scopeKey) {
 function dailyItemText(turn) {
   const request = String(turn.request_text || "");
   const outcome = String(turn.result_summary || "");
-  if (!hasSubstantiveTurn(request, outcome) || isTrivialTurn(request, outcome)) return "";
-  const source = outcome || request;
+  // Daily is an outcome index, not a prompt inbox. Keep request-only turns in
+  // detailed reports, but do not present an unfinished question as completed
+  // work in the compact daily file.
+  if (!outcome || !hasSubstantiveTurn(request, outcome) || isTrivialTurn(request, outcome)) return "";
+  const source = outcome;
   // Flattened rather than first-line: a structured summary often opens with a
   // preamble line, and the substance sits in the lines after it.
   const flattened = source
@@ -507,9 +519,23 @@ function dailyItemText(turn) {
     .filter(Boolean)
     .join(" ");
   if (!flattened) return "";
-  return flattened.length > DAILY_ITEM_MAX_CHARS
-    ? `${flattened.slice(0, DAILY_ITEM_MAX_CHARS - 3)}...`
-    : flattened;
+  return truncateDailyItem(flattened);
+}
+
+function truncateDailyItem(text) {
+  if (text.length <= DAILY_ITEM_HARD_MAX_CHARS) return text;
+  const limit = DAILY_ITEM_HARD_MAX_CHARS - 3;
+  const prefix = text.slice(0, limit);
+  // Prefer the longest complete sentence within the hard cap. The target is a
+  // soft guide: retaining more complete context is better when the next
+  // sentence ends before the hard limit.
+  const boundaries = [...prefix.matchAll(/[。！？；;]|[.!?](?=\s|$)/g)];
+  const boundary = boundaries.at(-1)?.index;
+  if (boundary !== undefined && boundary + 1 >= Math.floor(DAILY_ITEM_TARGET_CHARS * 0.6)) {
+    return `${prefix.slice(0, boundary + 1)}...`;
+  }
+  const targetPrefix = text.slice(0, DAILY_ITEM_TARGET_CHARS - 3);
+  return `${targetPrefix}...`;
 }
 
 async function updateDailyFile(outputFile, day, items) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kairyou/agent-tools",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Reusable Agent Skills, plus integrations (statusline, provider usage, vision) that install into Codex, Claude Code, and opencode.",
   "license": "MIT",
   "repository": {

package/skills/integrations/at-zentao/SKILL.md

@@ -6,143 +6,179 @@ argument-hint: "bug <id> | task <id> | bugs | tasks | export bug|task <id>"
 
 # ZenTao Bug/Task Workflow
 
+## Secure CLI boundary
+
+This Skill bundles `scripts/zentao-cli.mjs`. Resolve the Skill root as the
+directory containing this `SKILL.md`, then run the script with Node using its
+resolved path from any working directory:
+
+```text
+node <skill-root>/scripts/zentao-cli.mjs <command>
+```
+
+The script is the only component allowed to read ZenTao configuration,
+exchange credentials for a token, send authenticated requests, or inspect raw
+error responses. Run it directly without reading or copying its source into
+the conversation. Never read `~/.agent-tools/config.jsonc`, print ZenTao env
+vars, call the token endpoint, or construct a ZenTao `Token` header yourself.
+
+The CLI emits only sanitized JSON. Treat a nonzero exit as a stopped ZenTao
+operation and report its safe `error`, `message`, and optional HTTP `status`.
+Do not work around the CLI with `curl` when authentication or an endpoint
+fails.
+
 ## Configuration
 
-Primary config lives under a `zentao` key in `~/.agent-tools/config.jsonc` — or `$AGENT_TOOLS_HOME/config.jsonc` when `AGENT_TOOLS_HOME` is set, matching the rest of agent-tools. Every `~/.agent-tools/config.jsonc` below means this resolved path:
+The CLI reads the global `~/.agent-tools/config.jsonc`, or
+`$AGENT_TOOLS_HOME/config.jsonc` when `AGENT_TOOLS_HOME` is set. It never reads
+repository-level configuration. Basic configuration:
 
 ```jsonc
 {
   "zentao": {
-    "url": "http://zentao.example.com",
-    "account": "...",
-    "password": "..."
+    "url": "https://zentao.example.com",
+    "account": "user",
+    "password": "your-password"
   }
 }
 ```
 
-Resolution order (first match wins):
-
-- URL: env `ZENTAO_URL` → `zentao.url` in `~/.agent-tools/config.jsonc`.
-- Credentials: env `ZENTAO_ACCOUNT`/`ZENTAO_PASSWORD` → `zentao.account`/`zentao.password` in `~/.agent-tools/config.jsonc`.
-
-ZenTao config comes ONLY from env vars and the global `~/.agent-tools/config.jsonc`, never a repository-level file — so an untrusted repo can't redirect the endpoint to capture your credentials.
+To avoid storing the password in the file, use
+`"password": { "env": "ZENTAO_PASSWORD" }` and set that environment variable.
+Direct env overrides are `ZENTAO_URL`, `ZENTAO_ACCOUNT`, and
+`ZENTAO_PASSWORD`. `ZENTAO_TOKEN` may be used instead of password exchange; it
+is accepted only from the environment.
 
-**First-run setup** (when config is missing or incomplete):
+When configuration is missing, tell the user which file to edit and show the
+template above. Never ask them to paste a password or token into chat, and do
+not edit or inspect the file after they add credentials. Ask them to say
+"done", then validate with:
 
-1. If `~/.agent-tools/config.jsonc` has no `zentao` block, insert one INTO the root object (not appended after the closing `}`) — it is JSONC, so preserve existing keys and comments, and mind the trailing comma:
-   `"zentao": { "url": "", "account": "", "password": "" }`
-2. Ask for the URL and account as a PLAIN chat question and wait for the reply — never collect free-form values via a multiple-choice prompt (its fixed option labels would be submitted as the answer). Write the reply into the config — these are not secrets.
-3. NEVER ask the user to paste the password into the chat (it would persist in transcripts). Tell them — in the same message as step 2 — to fill `zentao.password` in the file themselves or set env `ZENTAO_PASSWORD`, and to say "done" when finished.
-4. Then validate immediately: exchange a token and call `GET /api.php/v1/user`. Report the result before doing any real work.
-
-## Authentication (once per session)
-
-ZenTao tokens expire, so exchange credentials for a fresh token at the start of each session:
-
-```
-POST $ZENTAO_URL/api.php/v1/tokens
-Content-Type: application/json
-{"account":"...","password":"..."}
+```text
+node <skill-root>/scripts/zentao-cli.mjs doctor
 ```
 
-The response's `token` field is used as a `Token: <token>` header on every subsequent API request. Keep it in memory for the session only; never write it to a file and never echo it in full. If any later call returns 401, exchange for a new token once and retry; if it still fails, stop and report.
+Report only whether the connection succeeded and whether authentication used
+`token` or `account-password`.
 
-If env `ZENTAO_TOKEN` is set, use it directly and skip the exchange (re-exchange is unavailable then — on 401, tell the user the token expired).
-
-**Connectivity check**: after obtaining the token, `GET $ZENTAO_URL/api.php/v1/user` must succeed before any other work. On failure, stop and tell the user to check URL/credentials.
-
-## Usage
+## CLI commands
 
-- `/at-zentao bug <id>` — handle a single bug
-- `/at-zentao task <id>` — handle a single task
-- `/at-zentao bugs` — list bugs assigned to the configured account; the user picks one or several (multiple = batch mode)
-- `/at-zentao tasks` — same for tasks
-- `/at-zentao export bug <id>` (or `export task <id>`) — export to a self-contained Markdown bundle for handoff; does NOT fix or write back (see Export mode)
+Read-only commands:
 
-## API endpoints (verified on ZenTao open source 18.12)
-
-All requests send the `Token: <token>` header — it works for both endpoint families below.
-
-**My work lists** (legacy `.json` pages; the entry point for picking what to fix):
-
-- `GET /my-work-bug.json` — bugs assigned to the configured account
-- `GET /my-work-task.json` — tasks assigned to the configured account
-- Response shape: `{"status":"success","data":"<JSON-encoded string>"}` — the `data` field is a STRING containing JSON (with `\uXXXX` escapes), so decode it a second time. Bugs are in `.bugs[]` (fields: `id`, `title`, `severity`, `pri`, `status`, `project`, `product`), tasks in `.tasks[]`. The first page usually suffices, but read the pager info inside `data` for the total — if there are more pages, tell the user (e.g. "showing 20 of 45; say more to load the rest") instead of silently truncating, and fetch further pages only on request.
-
-**Details and write-back** (REST v1):
-
-- `GET /api.php/v1/bugs/{id}` — bug details (title, steps, severity, module)
-- `GET /api.php/v1/tasks/{id}` — task details
-
-**Attachments / inline images** (legacy, same Token header; binary — save with `curl -o`, never read as text):
-
-- `GET /file-read-{fileID}.{ext}` — view/inline. Observed on 18.12: bug screenshots are embedded in the `steps` HTML as `<img src=".../file-read-{id}.png">` while the `files` list is empty — so scan `steps`, don't rely on `files`.
-- `GET /file-download-{fileID}.html` — download an attachment (when `files` is populated).
-
-**Resolving a bug** (the REST `PUT /bugs/{id}` does NOT perform a real resolve — do not use it for status changes; use the legacy action, which mirrors the web form and triggers the full workflow):
-
-1. `POST /bug-resolve-{id}.json` with a form body (`Content-Type: application/x-www-form-urlencoded`, same Token header):
-   `resolution=fixed&resolvedBuild=trunk&responsibleBy=<account>&comment=<...>`
-   where `responsibleBy` is the authenticated account (from config) — this instance requires it.
-   Encoding: NEVER pass non-ASCII (Chinese) text as a command-line argument — Windows curl.exe converts argv through the ANSI codepage and mangles it regardless of terminal. Feed such text via stdin: `--data-urlencode "comment@-"` plus a herestring/pipe/heredoc. ASCII fields may go inline in `-d`; all data flags merge into one form body. Verified one-liner:
-   `curl -s -X POST -H "Token: $TOKEN" -d "resolution=fixed&resolvedBuild=trunk&responsibleBy=<account>" --data-urlencode "comment@-" "$ZENTAO_URL/bug-resolve-{id}.json" <<< $'<comment line 1>\n<line 2>'`
-2. To add a comment WITHOUT changing status: `POST /action-comment-bug-{id}.json`, comment fed via stdin the same way (`--data-urlencode "comment@-"`).
-3. Check the DECODED response: legacy endpoints return HTTP 200 with `{"status":"success","data":"..."}` even on failure — the real outcome is inside `data` (`result: "fail"` + per-field `message`). Surface those validation messages to the user verbatim; if a required field is missing, discover the form's fields and defaults via `GET /bug-resolve-{id}.json`, fill it, and re-confirm with the user before retrying.
-
-**Finishing a task**:
+```text
+node <skill-root>/scripts/zentao-cli.mjs list bugs
+node <skill-root>/scripts/zentao-cli.mjs list tasks
+node <skill-root>/scripts/zentao-cli.mjs get bug <id>
+node <skill-root>/scripts/zentao-cli.mjs get task <id>
+node <skill-root>/scripts/zentao-cli.mjs get bug <id> --download-dir <path>
+```
 
-1. `GET /task-finish-{id}.json` — the decoded `data.task` object holds current values (`realStarted`, `consumed`, `openedBy`, ...).
-2. `POST /task-finish-{id}.json` (same Token header and stdin-encoding rules as bug resolve) with:
-   - `currentConsumed` — hours spent; a value only the user knows. ALWAYS ask the user for it; never invent or estimate it on their behalf.
-   - `consumed` — TOTAL consumed, must exceed the previous total: compute as `data.task.consumed + currentConsumed`.
-   - `realStarted` — required; reuse `data.task.realStarted` if set, otherwise use a sensible date confirmed with the user (format `YYYY-MM-DD HH:MM:SS`; a space, so either `--data-urlencode` it or write the space as `+` inside `-d`).
-   - `finishedDate` — now, same format.
-3. To comment on a task without finishing it: `POST /action-comment-task-{id}.json`.
+`get` downloads token-gated inline images and attachments into a temporary
+directory by default and returns only local paths. Inspect those local files;
+never pass the original ZenTao URL to an image tool.
 
-If a call fails, report the actual HTTP status and response body to the user instead of failing silently.
+Write commands require JSON on stdin and are allowed only after the explicit
+confirmation steps below:
 
-Do NOT browse via products/projects — always start from the my-work lists or an explicit id the user gives.
+```text
+node <skill-root>/scripts/zentao-cli.mjs comment bug <id>
+node <skill-root>/scripts/zentao-cli.mjs comment task <id>
+node <skill-root>/scripts/zentao-cli.mjs resolve bug <id>
+node <skill-root>/scripts/zentao-cli.mjs finish task <id>
+```
 
-## Per-item workflow (follow strictly, in order)
+Input shapes:
 
-1. **Fetch details** — pull title, reproduction steps, severity, and module via the API. Images are usually inline in the `steps` HTML (`<img src=".../file-read-{id}.png">`; the `files` list is often empty) — download each with the Token header to a temp file and Read it now, so the screenshot informs the fix. If you cannot see images, try an image-inspection tool with the downloaded file path — e.g. `inspect_image` (MCP server `agent-tools-vision`) — never the token-gated ZenTao URL; if none is available, work from the text details and note that screenshots were skipped.
-2. **Restate and confirm** — restate the problem and the intended fix in your own words. If the description is unclear or ambiguous, ask the user before touching code.
-3. **Locate the code** — search the current project for the relevant code and explain how it was identified.
-4. **Fix** — change only what this bug/task requires; no unrelated cleanups.
-5. **Verify** — proportionate to the change: run the narrowest check that exercises it (the affected tests, a targeted build/typecheck of the touched module — not a full build for a one-line fix). If the bug is reproducible from code, reproduce it before the fix and confirm it is gone after. Use the project's verify skill if one exists. For changes machines can't judge (UI/visual/interaction), say so honestly — state what WAS checked (compiles, tests pass) and that the visual result needs the user's eyes; the user verifies via the "not yet" path at the commit step. Never present an unverifiable change as verified. A failed check must not proceed to the next step.
-6. **git add** — first run `git diff --staged --name-only`; if the index already holds unrelated changes, STOP and ask the user (commit those separately / unstage them / proceed anyway) so the `bug#<id>` commit isn't polluted. Then stage only the files changed for THIS item, listing them explicitly (never `git add -A`).
-7. **Ask whether to commit** (never commit automatically):
-   - 1) Commit — generate and show a Conventional Commits message, following all at-commit conventions (language policy, ≤74-char single-line title). Right after `type(scope):`, add the ZenTao link token — `bug#<id>` or `task#<id>` — e.g. `fix(<scope>): bug#30887 <desc>` (scope optional). Rewrite the description from the diff rather than copying the title, keeping the title's domain terms.
-   - 2) Not yet — keep the changes staged and continue
-   - 3) Needs adjustment — take the feedback and return to step 4
-8. **Ask whether to update ZenTao** (never change status automatically). First DRAFT the write-back, then show it in the confirmation question. If the item was NOT committed (you chose "Not yet" at step 7), do not draft a `fixed` resolution or a commit hash — at most a comment with the status left unchanged, since a `fixed` write-back must reference a real commit:
-   - **Resolution** — pick the value that matches what actually happened (ZenTao's enum): `fixed` 已解决 (default after a code fix), `notrepro` 无法重现, `duplicate` 重复Bug (needs the duplicate bug id), `bydesign` 设计如此, `external` 外部原因, `postponed` 延期处理, `willnotfix` 不予解决. If investigation showed the bug needs no code fix, propose the fitting non-`fixed` resolution instead.
-   - **Comment** — one sentence: root cause + change summary, plus the commit hash if committed. Don't list files or expand into narrative.
-   - Options (reply with a number): 1) Submit  2) Edit first  3) Comment only (no status change).
-   - **For tasks**, default to adding a comment only (drafted the same way). Offer "finish" ONLY for simple tasks completable in one sitting — it asks the user for hours (`currentConsumed`) and submits once. For multi-day tasks or teams that log per-day workhours, do NOT attempt finish via API; post the comment and point the user to the web UI's 记录工时/完成 forms, which handle per-day entries properly.
+```json
+{"comment":"Root cause and result."}
+{"resolution":"fixed","resolvedBuild":"trunk","comment":"Root cause and result, commit abc1234."}
+{"currentConsumed":1.5,"realStarted":"2026-08-11 09:00:00","finishedDate":"2026-08-11 10:30:00"}
+```
 
-## Export mode (`export bug <id>` / `export task <id>`)
+For `duplicate`, also pass `"duplicateBug": <id>`. Send JSON through stdin,
+not as a command-line argument. The CLI handles UTF-8 form encoding and
+computes a task's total consumed hours from its current ZenTao value.
 
-Produce a self-contained handoff for someone (or another agent) WITHOUT ZenTao access. Read-only: do NOT fix, commit, or write status back.
+## Usage
 
-1. Fetch details as in step 1, including downloading every inline/attached image — they are token-gated, so the recipient cannot fetch them; the export must carry them.
-2. Ask the user where to save (a free-form value — ask in plain chat, never via a multiple-choice prompt); default to the Desktop, never the code repo (an export artifact doesn't belong in project source).
-3. Write the Markdown: a header (id, title, status, severity/pri, module/product, opened/assigned), the `steps` converted from HTML to Markdown, and comments/history when useful. Strip anything auth-bound — never include the token, credentials, or login-gated URLs.
-4. Layout by content:
-   - No images → a single file `<dest>/zentao-<bug|task>-<id>.md`.
-   - With images → a folder `<dest>/zentao-<bug|task>-<id>/` holding that `.md` plus the downloaded images; rewrite each `<img src=".../file-read-...">` to a relative `![](./file-read-<id>.png)` link. Keep images as real files (never base64) so another agent can Read/see them and every viewer renders them; to hand the folder over as one item, zip it.
+- `/at-zentao bug <id>` — handle a single bug.
+- `/at-zentao task <id>` — handle a single task.
+- `/at-zentao bugs` — list bugs assigned to the configured account; let the
+  user select one or more.
+- `/at-zentao tasks` — list assigned tasks and let the user select.
+- `/at-zentao export bug <id>` or `export task <id>` — create a read-only,
+  self-contained handoff bundle.
+
+If a list response includes pager data showing more items than returned, tell
+the user the shown and total counts. Do not silently imply the list is complete.
+Do not browse through products/projects; start from assigned lists or an
+explicit item id.
+
+## Per-item workflow
+
+Follow these steps in order:
+
+1. **Fetch details** — use the CLI `get` command. Read every downloaded image
+   now so screenshots inform the fix. If no image-inspection tool is available,
+   continue from text and state that screenshots were skipped.
+2. **Restate and confirm** — explain the problem and intended fix in your own
+   words. Ask before editing when the item is ambiguous.
+3. **Locate the code** — search the current project and explain how the relevant
+   code was identified.
+4. **Fix** — change only what this item requires.
+5. **Verify** — run the narrowest meaningful test, build, or typecheck. Reproduce
+   a code-observable bug before and after when practical. For visual changes,
+   state what was checked and what still needs the user's eyes. Stop on a failed
+   check.
+6. **Stage** — first inspect `git diff --staged --name-only`. If unrelated files
+   are staged, stop and ask how to handle them. Otherwise stage only files for
+   this item by explicit path; never use `git add -A`.
+7. **Ask whether to commit** — offer Commit, Not yet, or Needs adjustment. For a
+   commit, show a single-line Conventional Commit message before committing.
+   Put `bug#<id>` or `task#<id>` immediately after `type(scope):`, for example
+   `fix(auth): bug#30887 reject expired sessions`. Never commit automatically.
+8. **Ask whether to update ZenTao** — draft the exact resolution/comment and
+   offer Submit, Edit first, or Comment only. Never invoke a write CLI command
+   before confirmation. A `fixed` resolution must cite a real commit; without a
+   commit, offer at most a comment with status unchanged.
+
+Bug resolutions are `fixed`, `notrepro`, `duplicate`, `bydesign`, `external`,
+`postponed`, and `willnotfix`. Choose what matches the verified outcome. A
+write-back comment is one sentence containing root cause, change summary, and
+the commit hash when committed.
+
+For tasks, default to comment only. Offer `finish` only for a simple task
+completed in one sitting, and ask the user for `currentConsumed`; never invent
+hours. For multi-day work or per-day time records, comment and direct the user
+to ZenTao's web UI.
+
+## Export mode
+
+Export is read-only and never fixes code, commits, or writes back:
+
+1. Fetch the item with `get`, including every downloaded image/attachment.
+2. Ask where to save; default to the Desktop and never the code repository.
+3. Write a Markdown handoff with id, title, status, severity/priority,
+   module/product, description/steps, and useful history available in the safe
+   CLI response. Do not include credentials or login-gated URLs.
+4. With no images, write `<dest>/zentao-<bug|task>-<id>.md`. With images, create
+   a same-named directory containing the Markdown and real image files, rewrite
+   image references to relative paths, and zip only when a single artifact is
+   needed.
 
 ## Batch mode
 
-- Strictly sequential — one item at a time, each with its own stage/commit. Never mix changes from different bugs.
-- Continue to the next item ONLY after the current item's changes are committed. If the user chose "not yet" at the commit step, do not start the next item — its `git add`/commit would sweep up the still-staged changes (and same-file edits can't be untangled later). Instead ask: commit now / stash this item's changes and continue / stop the batch here.
-- After each item, ask: continue to the next / stop (summarize progress so far). The user can also name a specific pending item to skip.
-- Before starting, show the pending list and let the user confirm the order.
+- Process one item at a time, each with its own stage and commit.
+- Show the pending order before starting.
+- Continue only after the current item is committed. If it remains staged,
+  offer commit, stash and continue, or stop.
+- After each item, ask whether to continue or stop and summarize progress.
 
 ## Hard rules
 
-- Never commit and never change ZenTao status without asking first.
-- The commit subject MUST carry the `bug#<id>` / `task#<id>` token right after `type(scope):` — ZenTao's repo integration parses it to auto-link the commit, and it keeps IDs aligned in `git log --oneline`.
-- Confirmations may use a multiple-choice prompt if the agent has one (e.g. Claude Code's AskUserQuestion), but ONLY for enumerable decisions (commit? write back? which resolution?). Free-form values — URL, account, hours — are collected by asking in plain chat and waiting for the reply.
-- Never echo the password or token in full, and never write them anywhere except the `zentao` block of the user's global config (the password there is filled in by the user, not by you).
-- On API failures, report the HTTP status and response body verbatim; do not guess and continue.
+- Never expose account, password, token, cookies, or authorization headers.
+- Never bypass the bundled CLI for ZenTao authentication or API access.
+- Never commit or change ZenTao state without separate explicit confirmation.
+- Keep the `bug#<id>` or `task#<id>` token in every related commit subject.
+- Collect free-form values such as output paths and hours in plain chat, not a
+  fixed-choice prompt. Passwords and tokens are never collected in chat.