@kairyou/agent-tools 0.10.0 → 0.10.2

package/README.md

@@ -1,6 +1,6 @@
 # Agent Tools
 
-Reusable Agent Skills and installable integrations — statusline, provider usage, and vision — for Codex, Claude Code, and opencode.
+Reusable Agent Skills, plus integrations (statusline, provider usage, vision) that install into Codex, Claude Code, and opencode.
 
 Requires Node.js >= 22.
 
@@ -153,21 +153,23 @@ Output examples:
 
 ```text
 # Plan limits (sub2api / openai-compatible).
-D $0.0/$100 | W $0.0/$300 | Exp 07-08
+D $0.0/$100 | W $0.0/$300 ⟳3d1h | Exp 07-08
 
 # Multi-window limits (claude-code-hub).
 5h $2.1/$10.0 | D $8.0/$20.0 | T $19.0/$100 | Exp 08-31
 
 # Balance and usage (one-api / one-hub / done-hub / new-api / openrouter).
-balance $15.0 | used $5.0/$20.0
+balance $15.0 | used $5.0/$20.0 | ⟳3d1h
 
 # Wallet and recent spend (sub2api).
 balance $362 | today $61.7 | 30d $566
 ```
 
 Fields: `5h/D/W/M/T` are five-hour/daily/weekly/monthly/total spend against
-limits; `Exp` is the plan expiry; `balance` is wallet credit; `used` is consumed
-credit; `today` and `30d` are today's and the last 30 days' API spend.
+limits; `⟳` is the time until a known limit reset; `Exp` is the plan expiry;
+`balance` is wallet credit; `used` is consumed credit; `today` and `30d` are
+today's and the last 30 days' API spend. A reset countdown is shown only when
+the gateway returns enough timing information to determine it reliably.
 
 #### Custom gateway routes
 
@@ -216,6 +218,10 @@ To diagnose the provider setup or test recognition quality manually:
 npx -y @kairyou/agent-tools@latest inspect-image <path|url> -q "What are the navbar background color and height?"
 ```
 
+## Extras
+
+See [extras](docs/en/extras.md) for situational content.
+
 ## Run from Git
 
 To run directly from the repository, replace the npm package name with

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md)
 
-可复用的 Agent Skills, 以及面向 Codex, Claude Code 与 opencode 的可安装 integrations: statusline, provider usage 与跨模型识图.
+可复用的 Agent Skills, 以及可装入 Codex, Claude Code 与 opencode 的 integrations: statusline, provider usage 与跨模型识图.
 
 需要 Node.js >= 22.
 
@@ -149,20 +149,22 @@ npx -y @kairyou/agent-tools@latest usage -a claude codex opencode
 
 ```text
 # 套餐限额 (sub2api / openai-compatible).
-D $0.0/$100 | W $0.0/$300 | Exp 07-08
+D $0.0/$100 | W $0.0/$300 ⟳3d1h | Exp 07-08
 
 # 多窗口限额 (claude-code-hub).
 5h $2.1/$10.0 | D $8.0/$20.0 | T $19.0/$100 | Exp 08-31
 
 # 余额与用量 (one-api / one-hub / done-hub / new-api / openrouter).
-balance $15.0 | used $5.0/$20.0
+balance $15.0 | used $5.0/$20.0 | ⟳3d1h
 
 # 钱包与近期消耗 (sub2api).
 balance $362 | today $61.7 | 30d $566
 ```
 
-字段含义: `5h/D/W/M/T` 是 5 小时/日/周/月/总消耗与上限, `Exp` 是套餐到期日,
-`balance` 是钱包余额, `used` 是已用额度, `today` / `30d` 是今日与近 30 天 API 消耗.
+字段含义: `5h/D/W/M/T` 是 5 小时/日/周/月/总消耗与上限, `⟳` 后面是已知限额的
+重置倒计时, `Exp` 是套餐到期日, `balance` 是钱包余额, `used` 是已用额度,
+`today` / `30d` 是今日与近 30 天 API 消耗. 只有网关返回的信息足以可靠确定
+重置时间时才会显示倒计时.
 
 #### 自定义网关路由
 
@@ -171,7 +173,7 @@ balance $362 | today $61.7 | 30d $566
 
 ### Vision(跨模型识图)
 
-让不支持图片的主模型借助多模态模型识图, 适用于读取报错截图、按设计稿还原 UI、定位测试反馈截图里的界面问题.
+让不支持图片的主模型借助多模态模型识图, 适用于读取报错截图, 按设计稿还原 UI, 定位测试反馈截图里的界面问题.
 
 #### 安装
 
@@ -211,6 +213,10 @@ npx -y @kairyou/agent-tools@latest vision -a claude codex opencode
 npx -y @kairyou/agent-tools@latest inspect-image <path|url> -q "导航栏的背景色和高度是多少"
 ```
 
+## Extras
+
+[extras](docs/zh-CN/extras.md) 收录场景较窄的内容.
+
 ## 从 Git 运行
 
 如需直接使用仓库版本, 可将 npm 包名替换为 `github:kairyou/agent-tools` (本机需已安装 Git):

package/dist/usage/core.mjs

@@ -1309,6 +1309,14 @@ async function requestJson(url, options = {}) {
 
 // integrations/usage/lib/format.mjs
 var ONE_API_HARD_LIMIT_SENTINEL_USD = 1e6;
+var RESET_TIME_FIELDS = Object.freeze({
+  // Sub2API rate-limit entries returned alongside quota usage.
+  SUB2API_RATE_LIMIT: "reset_at",
+  // Sub2API /v1/usage response: subscription weekly-window anchor.
+  SUB2API_SUBSCRIPTION_WEEKLY_START: "weekly_window_start",
+  // OpenRouter /api/v1/key response: absolute key-limit reset.
+  OPENROUTER_KEY_LIMIT: "limit_reset"
+});
 function pickNumber(obj, keys) {
   for (const key of keys) {
     const value = obj?.[key];
@@ -1337,6 +1345,39 @@ function shortDate(value) {
   const match = String(value).match(/^(\d{4})-(\d{2})-(\d{2})/);
   return match ? `${match[2]}-${match[3]}` : "";
 }
+function timestampMs(value) {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value < 1e12 ? value * 1e3 : value;
+  }
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? parsed : void 0;
+}
+function compactDurationUntil(value) {
+  const resetMs = timestampMs(value);
+  if (resetMs === void 0) return "";
+  const remainingMs = resetMs - Date.now();
+  if (remainingMs <= 0) return "";
+  let seconds = Math.floor(remainingMs / 1e3);
+  if (seconds <= 0) return "0m";
+  const days = Math.floor(seconds / 86400);
+  seconds %= 86400;
+  const hours = Math.floor(seconds / 3600);
+  seconds %= 3600;
+  const minutes = Math.floor(seconds / 60);
+  if (days) return `${days}d${hours}h`;
+  if (hours) return `${hours}h${minutes}m`;
+  return `${minutes}m`;
+}
+function rateLimitResetAt(entry) {
+  const value = entry?.[RESET_TIME_FIELDS.SUB2API_RATE_LIMIT];
+  return timestampMs(value) === void 0 ? void 0 : value;
+}
+function weeklyResetAt(subscription) {
+  const startMs = timestampMs(
+    subscription?.[RESET_TIME_FIELDS.SUB2API_SUBSCRIPTION_WEEKLY_START]
+  );
+  return startMs === void 0 ? void 0 : startMs + 7 * 86400 * 1e3;
+}
 function hasSubscriptionLimits(root) {
   const sub = root?.subscription || {};
   return [
@@ -1437,7 +1478,7 @@ function formatOpenRouterLine(data) {
   const limit = pickNumber(root, ["limit", "limit_remaining", "total_credits"]);
   const remaining = pickNumber(root, ["limit_remaining", "remaining_credits"]);
   const used = pickNumber(root, ["usage", "total_usage", "spend"]);
-  const reset = root?.limit_reset || root?.reset_at ? shortDate(root.limit_reset || root.reset_at) : "";
+  const reset = compactDurationUntil(root?.[RESET_TIME_FIELDS.OPENROUTER_KEY_LIMIT]);
   const parts = [];
   if (remaining !== void 0) parts.push(`balance ${formatMoney(remaining)}`);
   if (used !== void 0 && limit !== void 0 && limit !== remaining) {
@@ -1445,7 +1486,7 @@ function formatOpenRouterLine(data) {
   } else if (used !== void 0) {
     parts.push(`used ${formatMoney(used)}`);
   }
-  if (reset) parts.push(`Reset ${reset}`);
+  if (reset) parts.push(`\u27F3${reset}`);
   if (parts.length === 0) throw new Error("OpenRouter payload has no usage fields");
   return parts.join(" | ");
 }
@@ -1511,7 +1552,8 @@ function formatQuotaLimitedLine(root) {
       const window = entry?.window;
       const rateLimit = pickNumber(entry, ["limit"]);
       const rateUsed = pickNumber(entry, ["used"]);
-      return window && rateLimit !== void 0 && rateUsed !== void 0 ? `${window} ${formatMoney(rateUsed)}/${formatMoney(rateLimit)}` : "";
+      const reset = compactDurationUntil(rateLimitResetAt(entry));
+      return window && rateLimit !== void 0 && rateUsed !== void 0 ? `${window} ${formatMoney(rateUsed)}/${formatMoney(rateLimit)}${reset ? ` \u27F3${reset}` : ""}` : "";
     }).filter(Boolean);
     if (rateParts.length > 0) parts.push(rateParts.join(", "));
   }
@@ -1538,9 +1580,12 @@ function formatUsageLine(root) {
   const monthlyLimit = pickNumber(sub, ["monthly_limit_usd"]);
   const monthlyUsage = pickNumber(sub, ["monthly_usage_usd"]);
   const expires = shortDate(sub.expires_at);
+  const weeklyReset = compactDurationUntil(weeklyResetAt(sub));
   const parts = [];
   if (dailyLimit > 0 && dailyUsage !== void 0) parts.push(`D ${formatMoney(dailyUsage)}/${formatMoney(dailyLimit)}`);
-  if (weeklyLimit > 0 && weeklyUsage !== void 0) parts.push(`W ${formatMoney(weeklyUsage)}/${formatMoney(weeklyLimit)}`);
+  if (weeklyLimit > 0 && weeklyUsage !== void 0) {
+    parts.push(`W ${formatMoney(weeklyUsage)}/${formatMoney(weeklyLimit)}${weeklyReset ? ` \u27F3${weeklyReset}` : ""}`);
+  }
   if (monthlyLimit > 0 && monthlyUsage !== void 0) parts.push(`M ${formatMoney(monthlyUsage)}/${formatMoney(monthlyLimit)}`);
   if (expires) parts.push(`Exp ${expires}`);
   return parts.join(" | ");

package/docs/en/extras.md

@@ -0,0 +1,24 @@
+# Extras
+
+Fully usable, just situational. Install each on demand.
+
+## at-self-eval
+
+Summarize a contributor's git history into a review-friendly self-evaluation for
+performance cycles (quarterly, semi-annual, promotion).
+
+```bash
+npx -y skills@latest add kairyou/agent-tools --skill at-self-eval -g -y
+```
+
+Usage:
+
+- `/at-self-eval` — current git identity, current quarter
+- `/at-self-eval [<author>] [--from yyyy-mm-dd] [--to yyyy-mm-dd]` — pick author and range
+- Plain language works too: say "summarize the first half of the year" instead of writing flags
+- Paste a daily/weekly log, or give a file path, to add business context (optional)
+- Mention other repositories or branches to aggregate across projects; a remote
+  URL prompts before cloning anything
+
+Output is a draft: it never invents deliverables, and every line traces back to a
+commit or to a log entry you confirmed. Review it before submitting.

package/docs/zh-CN/custom-gateway-routes.md

@@ -36,7 +36,7 @@ export async function run(context, { requestJson, agentConfig }) {
   const session = await login.json();
 
   // requestJson 会解析 JSON, 并在非 2xx 响应时抛错; 需要时可在这里传入
-  // authorization、cookie 等自定义认证 header.
+  // authorization, cookie 等自定义认证 header.
   const me = await requestJson(`${context.baseUrl}/api/user/self`, {
     headers: { authorization: `Bearer ${session?.data?.accessToken}` },
   });

package/docs/zh-CN/extras.md

@@ -0,0 +1,21 @@
+# Extras
+
+完整可用, 只是场景较窄. 按需单独安装.
+
+## at-self-eval
+
+把贡献者的 git 历史归纳成评审友好的自评产出清单, 用于季度/半年/晋升等绩效周期.
+
+```bash
+npx -y skills@latest add kairyou/agent-tools --skill at-self-eval -g -y
+```
+
+用法:
+
+- `/at-self-eval` — 默认当前 git 用户, 当前季度
+- `/at-self-eval [<作者>] [--from yyyy-mm-dd] [--to yyyy-mm-dd]` — 指定作者与日期范围
+- 在对话里直接说 `统计上半年的工作` / `统计 1-3月的产出` 即可, 无需手写参数
+- 可粘贴日报/周报文本或提供文件路径, 补充业务背景(可选)
+- 可提及其他仓库或分支以跨项目聚合; 远程地址会先询问是否 clone 到临时目录
+
+输出是草稿: 不编造产出, 每条都能追溯到 commit 或你确认过的日志条目. 提交前请人工核对.

package/integrations/usage/lib/format.mjs

@@ -6,6 +6,15 @@ import { newApiQuotaScale, providerUsageDays } from "./config.mjs";
 
 const ONE_API_HARD_LIMIT_SENTINEL_USD = 1_000_000;
 
+const RESET_TIME_FIELDS = Object.freeze({
+  // Sub2API rate-limit entries returned alongside quota usage.
+  SUB2API_RATE_LIMIT: "reset_at",
+  // Sub2API /v1/usage response: subscription weekly-window anchor.
+  SUB2API_SUBSCRIPTION_WEEKLY_START: "weekly_window_start",
+  // OpenRouter /api/v1/key response: absolute key-limit reset.
+  OPENROUTER_KEY_LIMIT: "limit_reset",
+});
+
 export function pickNumber(obj, keys) {
   for (const key of keys) {
     const value = obj?.[key];
@@ -40,6 +49,45 @@ function shortDate(value) {
   return match ? `${match[2]}-${match[3]}` : "";
 }
 
+function timestampMs(value) {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value < 1e12 ? value * 1000 : value;
+  }
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+function compactDurationUntil(value) {
+  const resetMs = timestampMs(value);
+  if (resetMs === undefined) return "";
+
+  const remainingMs = resetMs - Date.now();
+  if (remainingMs <= 0) return "";
+
+  let seconds = Math.floor(remainingMs / 1000);
+  if (seconds <= 0) return "0m";
+  const days = Math.floor(seconds / 86400);
+  seconds %= 86400;
+  const hours = Math.floor(seconds / 3600);
+  seconds %= 3600;
+  const minutes = Math.floor(seconds / 60);
+  if (days) return `${days}d${hours}h`;
+  if (hours) return `${hours}h${minutes}m`;
+  return `${minutes}m`;
+}
+
+function rateLimitResetAt(entry) {
+  const value = entry?.[RESET_TIME_FIELDS.SUB2API_RATE_LIMIT];
+  return timestampMs(value) === undefined ? undefined : value;
+}
+
+function weeklyResetAt(subscription) {
+  const startMs = timestampMs(
+    subscription?.[RESET_TIME_FIELDS.SUB2API_SUBSCRIPTION_WEEKLY_START]
+  );
+  return startMs === undefined ? undefined : startMs + 7 * 86400 * 1000;
+}
+
 function hasSubscriptionLimits(root) {
   const sub = root?.subscription || {};
   return [
@@ -163,7 +211,7 @@ export function formatOpenRouterLine(data) {
   const limit = pickNumber(root, ["limit", "limit_remaining", "total_credits"]);
   const remaining = pickNumber(root, ["limit_remaining", "remaining_credits"]);
   const used = pickNumber(root, ["usage", "total_usage", "spend"]);
-  const reset = root?.limit_reset || root?.reset_at ? shortDate(root.limit_reset || root.reset_at) : "";
+  const reset = compactDurationUntil(root?.[RESET_TIME_FIELDS.OPENROUTER_KEY_LIMIT]);
   const parts = [];
 
   if (remaining !== undefined) parts.push(`balance ${formatMoney(remaining)}`);
@@ -172,7 +220,7 @@ export function formatOpenRouterLine(data) {
   } else if (used !== undefined) {
     parts.push(`used ${formatMoney(used)}`);
   }
-  if (reset) parts.push(`Reset ${reset}`);
+  if (reset) parts.push(`⟳${reset}`);
 
   if (parts.length === 0) throw new Error("OpenRouter payload has no usage fields");
   return parts.join(" | ");
@@ -254,8 +302,9 @@ function formatQuotaLimitedLine(root) {
         const window = entry?.window;
         const rateLimit = pickNumber(entry, ["limit"]);
         const rateUsed = pickNumber(entry, ["used"]);
+        const reset = compactDurationUntil(rateLimitResetAt(entry));
         return window && rateLimit !== undefined && rateUsed !== undefined
-          ? `${window} ${formatMoney(rateUsed)}/${formatMoney(rateLimit)}`
+          ? `${window} ${formatMoney(rateUsed)}/${formatMoney(rateLimit)}${reset ? ` ⟳${reset}` : ""}`
           : "";
       })
       .filter(Boolean);
@@ -290,10 +339,13 @@ function formatUsageLine(root) {
   const monthlyLimit = pickNumber(sub, ["monthly_limit_usd"]);
   const monthlyUsage = pickNumber(sub, ["monthly_usage_usd"]);
   const expires = shortDate(sub.expires_at);
+  const weeklyReset = compactDurationUntil(weeklyResetAt(sub));
 
   const parts = [];
   if (dailyLimit > 0 && dailyUsage !== undefined) parts.push(`D ${formatMoney(dailyUsage)}/${formatMoney(dailyLimit)}`);
-  if (weeklyLimit > 0 && weeklyUsage !== undefined) parts.push(`W ${formatMoney(weeklyUsage)}/${formatMoney(weeklyLimit)}`);
+  if (weeklyLimit > 0 && weeklyUsage !== undefined) {
+    parts.push(`W ${formatMoney(weeklyUsage)}/${formatMoney(weeklyLimit)}${weeklyReset ? ` ⟳${weeklyReset}` : ""}`);
+  }
   if (monthlyLimit > 0 && monthlyUsage !== undefined) parts.push(`M ${formatMoney(monthlyUsage)}/${formatMoney(monthlyLimit)}`);
   if (expires) parts.push(`Exp ${expires}`);
   return parts.join(" | ");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kairyou/agent-tools",
-  "version": "0.10.0",
-  "description": "Reusable Agent Skills and installable integrations (statusline, provider usage, vision) for Codex, Claude Code, and opencode.",
+  "version": "0.10.2",
+  "description": "Reusable Agent Skills, plus integrations (statusline, provider usage, vision) that install into Codex, Claude Code, and opencode.",
   "license": "MIT",
   "repository": {
     "type": "git",

package/skills/workflow/at-self-eval/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: at-self-eval
+description: "Summarize a contributor's git history into a concise, review-friendly self-evaluation for performance cycles (quarterly / semi-annual / promotion). Use when the user asks for a PBC, self-review, or work summary. A daily/weekly log may be pasted or a path provided to enrich the result; other repos or branches may be mentioned to aggregate across projects (all optional)."
+argument-hint: "[<author>] [--from yyyy-mm-dd] [--to yyyy-mm-dd]"
+---
+
+# Self-Evaluation Summary
+
+`git log → group by business line → dedupe → ≤8 concise output points → human review`
+
+## Phase 0 — Gather the evidence
+
+Normalize every input form — flags, partial flags, or plain language like
+`统计 1-3月的产出` / `统计上半年的工作` — into a **determined** `(author, from,
+to)` triple, then query. The user's explicit date range always wins; defaults
+only fill what the user did not say. Re-state the resolved window in the output
+header so the user can catch a wrong inference at a glance.
+
+```bash
+# author — default to the current git identity, do NOT guess variants
+AUTHOR=$(git config user.name)
+# --until is EXCLUSIVE of its date, so push it +1 day to include the last day
+git log --author="$AUTHOR" --since="<from>" --until="<to + 1 day>" --no-merges --format="%ad %s" --date=short
+```
+
+**Author — do not guess:**
+
+1. Default `<author>` to `git config user.name`. Query only with that name; do
+   not infer or try variants. Note that `git log --author` uses regex matching,
+   so this rule limits identity guessing rather than promising strict equality.
+2. If 0 commits come back, do NOT auto-try pinyin/Chinese variants (risk of
+   mismatching a different person or inflating counts). Tell the user nothing
+   was found and show how to self-identify:
+   ```bash
+   git log --format='%an' | sort -u
+   ```
+3. If results come back, end the output with a one-line hint: the user may have
+   commits under other names and can rerun with `--author "name1\|name2"`.
+
+**Date range — `--until` is exclusive, `--since` is inclusive:**
+
+`git log --until=2026-06-30` means *before 2026-06-30 00:00:00* — it silently
+drops every commit on June 30. Always pass `<to + 1 day>` as `--until`.
+
+Fill missing dimensions (user's explicit range always wins):
+
+| User gave | resolved to |
+| --- | --- |
+| Both `--from` and `--to` | use as-is (apply the `--until +1 day` fix) |
+| Only `--from` | `to` = today |
+| Only `--to` | `from` = Jan 1 of `to`'s year |
+| Neither / plain-language time | **current quarter** |
+
+Plain-language time (`上半年` / `1-3月` / `近三个月` / `Q1` etc.) → parse to dates,
+defaulting to the current year; if the current month is earlier than the spoken
+months (e.g. it's Feb and the user says `统计 11-12 月`), use the previous
+calendar year. `上半年/下半年` → Jan–Jun / Jul–Dec; `Q1…/一季度…` → calendar
+quarter; `近三个月/最近一个月` → rolling window ending today. No time given →
+current quarter.
+
+`--no-merges` always — merge commits are not deliverables.
+
+**Re-state the window (required):** the output MUST begin with a one-line header
+so the user can verify or correct an auto-inferred window:
+
+```
+> 作者: <author> · 窗口: 2026-01-01 ~ 2026-03-31 · (时间窗口为自动推断, 如不对请指正后重跑)
+```
+
+When aggregating multiple repos, append a second line listing each repo and the
+branch used. Use plain words, never git jargon like "HEAD":
+
+```
+> 仓库: <repo1> (分支 next) · <repo2> (分支 main) · (未指定的均用各仓库当前分支, 如不对请指正)
+```
+
+No commit count, no "source" line — they add noise without review value.
+
+### Supplementary context (optional, conversation-driven)
+
+Daily/weekly logs, other repos, and other branches are all **optional
+supplementary context**, handled the same way — never via flags. The user offers
+them in conversation; the skill asks to clarify only when the user has already
+expressed intent. Do not prompt for these at the start.
+
+**Daily/weekly log** (pasted text or a provided file path) is background context:
+1. Format-agnostic — do not assume any date sectioning or schema; read as
+   continuous text to pick up business-line attribution and intent that commit
+   messages lack.
+2. No fabrication — commit-backed items may be summarized directly. Log-only
+   items must not be mixed into confirmed deliverables; if one appears to be a
+   real non-code outcome (design, research, review, training, delivery support,
+   coordination), list it separately for user confirmation. Include it in the
+   final summary only after the user confirms it.
+3. No time re-attribution — dates come from git log only; for a confirmed
+   log-only outcome, use only a date explicitly present in the log or provided
+   by the user.
+
+**Other repos** (user pastes a path or a remote URL):
+- **Local path** → query with `git -C <path> log ...`; resolve that repo's author
+  independently (same no-guessing rule as the primary repo). Default to that
+  repo's current branch, surfaced in the header for correction.
+- **Remote URL** → do NOT auto-clone. Ask the user whether to clone into a temp
+  dir for this run; only clone on explicit yes. On yes, clone to a temp dir,
+  query it, then delete the temp dir when done (keep it only if the user asks).
+  On no, ask for a local path or have them clone it themselves. Never clone
+  silently — clone has side effects (disk, auth, slow, may fail).
+- Path does not exist / not a git repo → ask, do not guess.
+
+**Other branches** (user names them, e.g. "也包含 dev 分支"):
+- Query those branches explicitly. Never run `git log --all` unprompted — on
+  large repos it pulls tens of thousands of commits and overruns context.
+- Confirm scope with the user before scanning all branches.
+
+**Dedup across repos/branches:** identical commit hashes count once. Do not
+mechanically delete commits by date/subject — separate work can share a generic
+message, while cherry-picked work can have different dates. During grouping,
+merge likely duplicates only when repository, subject, files, and change intent
+show they represent the same work; surface uncertain cases for user confirmation.
+
+### Language for user-facing text
+
+All output and prompts to the user use plain words. Avoid git jargon ("HEAD",
+"ref", "upstream", "cherry-pick") — users who say "I also worked on the dev
+branch" may not know what HEAD means. Keep "commit" and branch names (with
+context) as those are widely understood.
+
+## Phase 1 — Group and dedupe
+
+Group commits into **business lines / modules** and merge related commits into
+one deliverable. Collapse many commits into the 1–3 outcomes they achieved —
+`fix: lint`, `chore: fmt`, repeated `feat: sync` fold into the larger deliverable
+they supported. If a group has only trivial housekeeping, merge it into a
+related group or drop it. Do not inflate a single commit into a "deliverable."
+
+## Phase 2 — Write the summary
+
+Output a **numbered list**, one deliverable per line, grouped by business line.
+Each line:
+
+- starts with the business line / module, a colon, then 2–4 sub-points or a
+  one-sentence outcome;
+- is verb-led and outcome-oriented (built / shipped / refactored / migrated),
+  not a feature-name dump;
+- is concrete enough to be credible but concise enough to scan.
+
+- **≤8 top-level items — prioritize impact.** When work exceeds 8 lines, keep
+  the high-impact deliverables (built from scratch, major customer delivery,
+  architectural refactor, key fix) and merge or drop routine housekeeping
+  (lint, format, version bumps, repeated sync). Do not split 8 evenly across
+  business lines if that dilutes the standout work.
+- A volume/peak note is worth citing inline **only when a business line clearly
+  concentrated in one month** (e.g. "5月密集完成 <业务线>"), as a distribution
+  cue — not as a self-justifying metric.
+- Match the user's language (Chinese request → Chinese output). Identifiers and
+  product names stay as-is.
+- Do NOT fabricate. Every confirmed deliverable must trace back to a commit or
+  to a user-confirmed log entry. Surface uncertain or log-only outcomes as
+  candidates for confirmation rather than stating it as fact.
+
+Example shape (header + numbered list, placeholders only):
+
+```
+> 作者: <author> · 窗口: 2026-01-01 ~ 2026-06-30 · (时间窗口为自动推断, 如不对请指正后重跑)
+
+1. <业务线A>: <动词开头的产出>; <2–4 个关键点或一句成果>
+2. <业务线B>: ...
+```
+
+End with a one-line reminder: this is a draft — verify before submitting, since
+AI may merge or misattribute work. Do not write the summary to any file unless
+the user asks.
+
+**Conditional hints — only when this run likely under-represents the work.**
+Do NOT prompt every time; a clean, complete result ends with just the draft
+reminder above. Append ONE short line only in these cases:
+
+- A log-only item looks like real work but lacks user confirmation → "日志中还有未对应到 commit 的工作; 如属有效产出, 确认后可纳入总结."
+- No daily/weekly log was given AND commit messages are terse / hard to
+  attribute → "本次仅基于 commit 归纳; 若有日报/周报可粘贴文本或提供路径, 能补充业务背景使产出更准."
+- There is concrete evidence that other repos/branches may contain relevant
+  work (the user mentioned them, or the supplied log names work absent from the
+  scanned repo) → "可能还有其他仓库或分支的工作未覆盖; 告知路径/分支后可继续聚合统计."
+
+One line, never a follow-up question. Accept pasted text or a path equally —
+log formats vary widely, never assume a schema.