@kairyou/agent-tools 0.22.0 → 0.23.0

package/README.md

@@ -70,7 +70,20 @@ Usage:
 - `/at-zentao task <id> [request]` — work a task, start/pause/resume it, or log hours with a natural-language request
 - `/at-zentao story <id>` — read requirement scope and acceptance context without writing back
 
-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.
+Configure `~/.agent-tools/config.jsonc`:
+
+```jsonc
+{
+  "zentao": {
+    "url": "https://zentao.example.com",
+    "account": "user",
+    "password": "your-password",
+    // "password": { "env": "ZENTAO_PASSWORD" }, // Or read the password from an environment variable.
+    // Configure commentPrompt to customize bug/task comment formatting.
+    // "commentPrompt": "Use exactly this multiline format and field order:\nRoot cause: ...\nFix: ...\nBranch: ...\nVerification: ... (omit when not performed)\nCommit: ..."
+  }
+}
+```
 
 ## Capabilities
 
@@ -224,7 +237,7 @@ npx -y @kairyou/agent-tools@latest inspect-image <path|url> -q "What are the nav
 
 ## Extras
 
-See [extras](docs/en/extras.md) for situational content.
+See [extras](docs/en/extras.md) for optional tools outside the day-to-day development workflow.
 
 ## FAQ
 

package/README.zh-CN.md

@@ -70,7 +70,20 @@ npx -y skills@latest add kairyou/agent-tools --skill at-zentao -g -y
 - `/at-zentao task <id> [请求]` — 处理指定 task, 用自然语言开始/暂停/继续或记录工时
 - `/at-zentao story <id>` — 只读查看研发需求范围和验收信息
 
-配置: `~/.agent-tools/config.jsonc` → `"zentao": { "url", "account", "password" }`. 密码可以直接填写, 也可以使用 `"password": { "env": "ZENTAO_PASSWORD" }` 引用环境变量; 不要在对话中粘贴凭据或 token.
+配置 `~/.agent-tools/config.jsonc`:
+
+```jsonc
+{
+  "zentao": {
+    "url": "https://zentao.example.com",
+    "account": "user",
+    "password": "your-password",
+    // "password": { "env": "ZENTAO_PASSWORD" }, // 或者从环境变量读取密码.
+    // 需要自定义 bug/task 评论(备注)格式时, 可配置 commentPrompt.
+    // "commentPrompt": "严格使用以下多行格式和字段顺序:\n原因: ...\n修复: ...\n分支: ...\n验证: ...(未验证时省略)\nCommit: ..."
+  }
+}
+```
 
 ## Capabilities
 
@@ -218,7 +231,7 @@ npx -y @kairyou/agent-tools@latest inspect-image <path|url> -q "导航栏的背
 
 ## Extras
 
-[extras](docs/zh-CN/extras.md) 收录场景较窄的内容.
+[extras](docs/zh-CN/extras.md) 介绍日常开发主流程之外的可选工具.
 
 ## FAQ
 

package/docs/en/extras.md

@@ -1,11 +1,11 @@
 # Extras
 
-Fully usable, just situational. Install each on demand.
+This page lists optional tools outside the day-to-day development workflow.
 
 ## at-self-eval
 
-Summarize git history, a work log you provide, or both into a self-evaluation
-for performance cycles (quarterly, semi-annual, promotion).
+Turn Git commit history, a work log you provide, or both into a performance
+self-evaluation for quarterly reviews, half-year reviews, or promotion materials.
 
 ```bash
 npx -y skills@latest add kairyou/agent-tools --skill at-self-eval -g -y
@@ -25,7 +25,7 @@ Review the generated result before use.
 
 ## at-daily-log
 
-Distill each day's Git commits across projects into a work report; runs when invoked.
+Distill each day's Git commits across projects into a work report.
 
 ```bash
 npx -y skills@latest add kairyou/agent-tools --skill at-daily-log -g -y
@@ -35,12 +35,12 @@ Usage:
 
 - `/at-daily-log` — print today's log
 - `/at-daily-log 2026-07-31` — pick the date
-- `/at-daily-log last week` / `/at-daily-log the last two weeks` — one entry per active day, empty days skipped
+- `/at-daily-log last week` / `/at-daily-log the last two weeks` — one report per date with Git commits; dates without commits are skipped
 - `/at-daily-log summarize today for C:\projects\project-a` — only that project
 - `/at-daily-log also include C:\projects\project-c` — add to the default scope
 - `/at-daily-log record the log` — record to the configured file; rerunning a day only refreshes the generated part
 - `/at-daily-log record it to C:\logs\daily-log.md` — record to that file
-- `/at-daily-log record daily at 18:00` — guides you through an OS scheduled task; days without commits are not written
+- `/at-daily-log record daily at 18:00` — guides you through an OS scheduled task; no report is written when the day has no Git commits
 
 Recorded output example:
 
@@ -73,21 +73,6 @@ npx -y @kairyou/agent-tools@latest log -a claude codex opencode
 - `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:
-
-```markdown
-+ 2026-08-03
-<!-- log:2026-08-03:start -->
-  1. project-a: Found the cause of the login timeout: the renewal branch never updated the cache expiry, so the second request still read the old value. Patched session.ts and verified...
-  2. project-a: Fix is in, with 3 regression tests covering the renewal path; all passing.
-  3. project-b: Empty report exports came from an inverted permission filter, now corrected and confirmed working.
-<!-- log:2026-08-03:end -->
-```
-
-One line per turn, taken verbatim from the closing text of that turn's AI reply
-(truncated when long); no distilling, no cross-turn consolidation. Updates likewise
-rewrite only what sits between the markers.
-
 `detailed` output example (excerpt):
 
 ```markdown
@@ -114,6 +99,21 @@ Changes
 - src/auth/session.ts | diff +42/-8 | 3 ops
 ```
 
+`daily` output example:
+
+```markdown
++ 2026-08-03
+<!-- log:2026-08-03:start -->
+  1. project-a: Found the cause of the login timeout: the renewal branch never updated the cache expiry, so the second request still read the old value. Patched session.ts and verified...
+  2. project-a: Fix is in, with 3 regression tests covering the renewal path; all passing.
+  3. project-b: Empty report exports came from an inverted permission filter, now corrected and confirmed working.
+<!-- log:2026-08-03:end -->
+```
+
+One line per turn, taken verbatim from the closing text of that turn's AI reply
+(truncated when long); no distilling, no cross-turn consolidation. Updates likewise
+rewrite only what sits between the markers.
+
 ## Configuration
 
 All in `~/.agent-tools/config.jsonc`:

package/docs/zh-CN/extras.md

@@ -1,10 +1,10 @@
 # Extras
 
-完整可用, 只是场景较窄. 按需单独安装.
+这里收录日常开发主流程之外的可选工具.
 
 ## at-self-eval
 
-把 git 历史或你提供的工作日志归纳成自评产出清单, 用于季度/半年/晋升等绩效周期.
+基于 Git 提交历史或你提供的工作日志生成绩效自评, 可用于季度总结, 半年总结及晋升材料撰写.
 
 ```bash
 npx -y skills@latest add kairyou/agent-tools --skill at-self-eval -g -y
@@ -24,7 +24,7 @@ npx -y skills@latest add kairyou/agent-tools --skill at-self-eval -g -y
 
 ## at-daily-log
 
-按天把各项目的 Git 提交提炼成工作日报, 调用时生成.
+按天把各项目的 Git 提交提炼成工作日报.
 
 ```bash
 npx -y skills@latest add kairyou/agent-tools --skill at-daily-log -g -y
@@ -34,12 +34,12 @@ npx -y skills@latest add kairyou/agent-tools --skill at-daily-log -g -y
 
 - `/at-daily-log` — 输出今天的日报
 - `/at-daily-log 2026-07-31` — 指定日期
-- `/at-daily-log 上周` / `/at-daily-log 最近两周` — 范围内每天一条, 跳过没有提交的日子
+- `/at-daily-log 上周` / `/at-daily-log 最近两周` — 按日期生成日报, 跳过没有 Git 提交的日期
 - `/at-daily-log 统计 C:\projects\project-a 今天的工作` — 只统计指定项目
 - `/at-daily-log 另外包含 C:\projects\project-c` — 在默认范围上追加
 - `/at-daily-log 记录日报` — 记录到配置的文件; 同一天重复执行只更新生成的部分
 - `/at-daily-log 记录到 C:\logs\daily-log.md` — 记录到指定文件
-- `/at-daily-log 每天 18:00 自动记录` — 引导搭建系统定时任务; 没有提交的日子不会写入
+- `/at-daily-log 每天 18:00 自动记录` — 引导搭建系统定时任务; 当天没有 Git 提交时不写入日报
 
 记录到文件的示例:
 
@@ -71,20 +71,6 @@ npx -y @kairyou/agent-tools@latest log -a claude codex opencode
 - `format: "daily"`: 写入单个 Markdown 文件, 并按日期归档; 每个已完成且有实质结果的回答记录为一行, 不记录未完成的提问; 内容可能因长度限制被截断, 因此仅适合作为轻量活动索引
 - Codex 安装后运行 `/hooks` 批准一次; opencode 安装或更新后需要重启
 
-`daily` 输出示例:
-
-```markdown
-+ 2026-08-03
-<!-- log:2026-08-03:start -->
-  1. project-a: 已定位登录超时的原因: 会话缓存在续期分支上没有更新过期时间, 第二次请求拿到的还是旧值。已经在 session.ts 补上续期并本地验证通过, 接下来...
-  2. project-a: 修复完成, 新增 3 个回归用例覆盖续期路径, 全部通过。
-  3. project-b: 报表导出为空定位到权限过滤条件写反, 已修正并确认导出恢复正常。
-<!-- log:2026-08-03:end -->
-```
-
-每轮一行, 直接摘录那一轮 AI 回复的收尾内容(过长会截断), 不做提炼也不跨轮归纳;
-同样只重写标记之间的部分, 文件里的其他内容不会被碰.
-
 `detailed` 输出示例(节选):
 
 ```markdown
@@ -111,6 +97,20 @@ Changes
 - src/auth/session.ts | 变更 +42/-8 | 操作 3 次
 ```
 
+`daily` 输出示例:
+
+```markdown
++ 2026-08-03
+<!-- log:2026-08-03:start -->
+  1. project-a: 已定位登录超时的原因: 会话缓存在续期分支上没有更新过期时间, 第二次请求拿到的还是旧值. 已经在 session.ts 补上续期并本地验证通过, 接下来...
+  2. project-a: 修复完成, 新增 3 个回归用例覆盖续期路径, 全部通过.
+  3. project-b: 报表导出为空定位到权限过滤条件写反, 已修正并确认导出恢复正常.
+<!-- log:2026-08-03:end -->
+```
+
+每轮一行, 直接摘录那一轮 AI 回复的收尾内容(过长会截断), 不做提炼也不跨轮归纳;
+同样只重写标记之间的部分, 文件里的其他内容不会被碰.
+
 ## 配置
 
 都在 `~/.agent-tools/config.jsonc`:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kairyou/agent-tools",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Reusable Agent Skills, plus runtime capabilities (statusline, provider usage, vision) for Codex, Claude Code, and opencode.",
   "license": "MIT",
   "repository": {

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

@@ -78,6 +78,12 @@ node <skill-root>/scripts/zentao-cli.mjs hours task <id>
 `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.
+For Bugs and Tasks, a configured `zentao.commentPrompt` is returned as
+`writeback.commentPrompt`. Use it only when drafting a write-back comment; it
+is not item data or an existing comment. `get` also returns safe `comments`
+from action history, keeping only id, actor, action, date, and non-empty
+comment. An omitted `comments` means actions were unavailable; an empty array
+means actions were available but contained no comments.
 
 Write commands require JSON on stdin and are allowed only after the explicit
 confirmation steps below:
@@ -98,11 +104,11 @@ Input shapes:
 
 ```json
 {"comment":"Root cause and result."}
-{"resolution":"fixed","resolvedBuild":"trunk","comment":"Root cause and result, commit abc1234."}
+{"resolution":"fixed","resolvedBuild":"trunk","comment":"Root cause: stale session cache; Fix: refresh it during renewal; Commit: abc1234."}
 {"realStarted":"2026-08-11 09:00:00","comment":"Started implementation."}
 {"date":"2026-08-11","consumed":2,"left":14,"work":"Implemented the first part of the task."}
 {"work":"Corrected work description, commit abc1234."}
-{"currentConsumed":1.5,"realStarted":"2026-08-11 09:00:00","finishedDate":"2026-08-11 10:30:00"}
+{"currentConsumed":1.5,"realStarted":"2026-08-11 09:00:00","finishedDate":"2026-08-11 10:30:00","comment":"Completed: implemented session renewal; Commit: abc1234."}
 ```
 
 For `duplicate`, also pass `"duplicateBug": <id>`. Send JSON through stdin,
@@ -114,7 +120,7 @@ the task's current hours when starting or resuming it.
 `log-hours` defaults `date` to today, requires positive remaining hours,
 and keeps the task open. `hours` is read-only. `edit-hours` preserves omitted
 fields from the existing record and updates it through ZenTao's native effort
-workflow. Use `finish` when the task is complete.
+workflow. Use `finish` when the task is complete; its `comment` is optional.
 
 ## Usage
 
@@ -159,9 +165,11 @@ the current hours and never implies new consumed time.
 
 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.
+1. **Fetch details** — use the CLI `get` command. Review every returned comment,
+   including comments attached to resolution, activation, and lifecycle actions.
+   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
@@ -185,8 +193,20 @@ Follow these steps in order:
 
 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.
+write-back comment follows the current user request, then
+`writeback.commentPrompt`. Otherwise use the item or user's language and these
+defaults:
+
+- For a fixed Bug, use `Root cause`, `Fix`, optional `Verification`, and the
+  real `Commit`.
+- For a finished Task, use `Completed`, optional `Verification`, and `Commit`
+  only when the work has a related commit.
+- For other Bug resolutions, use `Conclusion` and applicable `Reason` or
+  `Evidence`.
+- Keep standalone and lifecycle comments free-form but concise.
+
+Formatting controls wording and layout only. Never invent missing facts;
+surface required gaps and put `Commit: <hash>` last.
 
 Immediately before confirming any ZenTao write that cites the latest commit,
 run `git rev-parse HEAD` and `git log -1 --format=%h`. Do not reuse a hash from
@@ -200,9 +220,10 @@ current entry and make that estimate editable in the confirmation; ask only
 when no reliable suggestion is possible. Draft `work` from the verified result
 when context is available. It is optional, so mention the omission without
 blocking the write when there is nothing useful to add. For a completed task,
-collect `currentConsumed` and draft a `finish` write. Never infer consumed
-hours. Show all submitted values and require the same explicit ZenTao
-confirmation before either write.
+collect `currentConsumed`, draft the completion comment from established facts,
+and include both in the `finish` write. Never infer consumed hours or a
+verification result. Show all submitted values and require the same explicit
+ZenTao confirmation before either write.
 
 To correct an existing time entry, use `hours` to select its effort id. Show
 the current and proposed `date`, `consumed`, `left`, and `work`, then obtain

package/skills/systems/at-zentao/scripts/zentao-cli.mjs

@@ -9,6 +9,8 @@ import { fileURLToPath } from "node:url";
 const JSON_LIMIT = 4 * 1024 * 1024;
 const BINARY_LIMIT = 20 * 1024 * 1024;
 const INPUT_LIMIT = 1024 * 1024;
+// Keep write-back guidance compact enough to remain useful in an agent response.
+const COMMENT_PROMPT_LIMIT = 1000;
 const SECRET_KEYS = /^(?:password|token|authorization|cookie|set-cookie)$/i;
 const RESOLUTIONS = new Set([
   "fixed",
@@ -148,6 +150,7 @@ export function loadConfig({ env = process.env, file = configFile(env) } = {}) {
   const rawAccount = env.ZENTAO_ACCOUNT || section.account;
   const rawPassword = env.ZENTAO_PASSWORD || section.password;
   const rawToken = env.ZENTAO_TOKEN;
+  const rawCommentPrompt = section.commentPrompt;
   const urlText = resolveValue(rawUrl, env, "zentao.url");
   let parsedUrl;
   try {
@@ -171,12 +174,23 @@ export function loadConfig({ env = process.env, file = configFile(env) } = {}) {
   const token = resolveValue(rawToken, env, "zentao.token", { required: false });
   const account = resolveValue(rawAccount, env, "zentao.account", { required: !token });
   const password = resolveValue(rawPassword, env, "zentao.password", { required: !token });
+  if (rawCommentPrompt !== undefined && typeof rawCommentPrompt !== "string") {
+    throw new CliError("config_error", "zentao.commentPrompt must be a string");
+  }
+  const commentPrompt = rawCommentPrompt?.trim() || null;
+  if (commentPrompt && commentPrompt.length > COMMENT_PROMPT_LIMIT) {
+    throw new CliError(
+      "config_error",
+      `zentao.commentPrompt must not exceed ${COMMENT_PROMPT_LIMIT} characters`
+    );
+  }
   return {
     url: parsedUrl.href.replace(/\/$/, ""),
     account,
     password,
     token,
     tokenOnly: Boolean(token),
+    commentPrompt,
     secrets: [account, password, token].filter(Boolean),
   };
 }
@@ -385,6 +399,23 @@ function pick(source, keys) {
   return output;
 }
 
+function normalizeComments(actions) {
+  const entries = Array.isArray(actions) ? actions : Object.values(actions || {});
+  const comments = [];
+  for (const entry of entries) {
+    if (!entry || typeof entry !== "object" || typeof entry.comment !== "string") continue;
+    const comment = entry.comment.trim();
+    if (!comment) continue;
+    const output = {};
+    for (const key of ["id", "actor", "action", "date"]) {
+      if (typeof entry[key] === "string" || typeof entry[key] === "number") output[key] = entry[key];
+    }
+    output.comment = comment;
+    comments.push(output);
+  }
+  return comments;
+}
+
 function normalizeDetail(kind, response) {
   const container = response?.data && typeof response.data === "object" ? response.data : response;
   const detail = container?.[kind] || container;
@@ -414,7 +445,12 @@ function normalizeDetail(kind, response) {
   } else if (kind === "story") {
     fields.push("stage", "category", "plan", "estimate", "spec", "verify", "source", "sourceNote");
   }
-  return { raw: detail, safe: pick(detail, fields) };
+  const safe = pick(detail, fields);
+  const actions = detail.actions ?? container?.actions;
+  if ((kind === "bug" || kind === "task") && actions && typeof actions === "object") {
+    safe.comments = normalizeComments(actions);
+  }
+  return { raw: detail, safe };
 }
 
 function attachmentUrls(detail) {
@@ -682,7 +718,13 @@ export async function run(argv, { env = process.env } = {}) {
     const resource = kind === "story" ? "stories" : `${kind}s`;
     const detail = normalizeDetail(kind, await client.json(`api.php/v1/${resource}/${id}`));
     const attachments = await downloadAttachments(client, detail.raw, directory);
-    return { item: detail.safe, attachments };
+    return {
+      item: detail.safe,
+      attachments,
+      ...(kind !== "story" && config.commentPrompt
+        ? { writeback: { commentPrompt: config.commentPrompt } }
+        : {}),
+    };
   }
 
   if (command === "comment") {
@@ -842,6 +884,9 @@ export async function run(argv, { env = process.env } = {}) {
     const input = await readInput();
     const current = Number(input.currentConsumed);
     if (!Number.isFinite(current) || current <= 0) throw new CliError("usage_error", "currentConsumed must be positive");
+    if (input.comment !== undefined && typeof input.comment !== "string") {
+      throw new CliError("usage_error", "comment must be a string when provided");
+    }
     const form = decodeLegacy(await client.json(`task-finish-${id}.json`));
     const task = form?.task || {};
     const previous = Number(task.consumed || 0);
@@ -855,6 +900,7 @@ export async function run(argv, { env = process.env } = {}) {
         consumed: previous + current,
         realStarted,
         finishedDate: input.finishedDate || localDateTime(),
+        comment: input.comment?.trim(),
       }),
     });
     return legacyResult(response);