dsh-task-ledger 0.0.114 → 0.0.116

package/dist/host/errors.d.ts

@@ -19,8 +19,8 @@ export declare class LedgerDataError extends Error {
 export interface DegradedInfo {
     readonly workspaceId: string;
     readonly workspaceTitle: string;
-    /** 哪个读挂了——trend 同时读 list + history，必须能区分。 */
-    readonly op: "list" | "history" | "owners";
+    /** 哪个读挂了（skill 子命令；趋势走 `stats --trend`，单独一档便于区分）。 */
+    readonly op: "list" | "history" | "owners" | "trend";
     readonly code: LedgerErrorCode;
     /** 人话，可直接上界面（真源：脚本 stderr / records 校验文案）。 */
     readonly message: string;

package/dist/host/repositories/trend.repository.d.ts

@@ -0,0 +1,33 @@
+import type { LedgerWorkspace } from "../types.js";
+/** 趋势图的窗口（周数）：与首页右侧卡位一致（2026-10-17 定稿「近 8 周」）。 */
+export declare const TREND_WEEKS = 8;
+/** 一个人在一个周桶里的三个数（skill 口径：新增按 creator、完成 / 未结按 owner）。 */
+export interface OwnerCounts {
+    readonly added: number;
+    readonly done: number;
+    readonly open: number;
+}
+/** 一个周桶；`from` / `to` 是**本机时区**的日期（含边界）。 */
+export interface TrendBucket {
+    readonly from: string;
+    readonly to: string;
+    /** 该周新建。 */
+    readonly added: number;
+    /** 该周结案（全部人合计）。 */
+    readonly done: number;
+    /** 该周结束时仍未结案（全部人合计，含窗口前遗留）。 */
+    readonly open: number;
+    /** uuid → 按人明细（「只看我的」用；没要 / 该人该周没数据则没有这个 key）。 */
+    readonly owners?: Readonly<Record<string, OwnerCounts>>;
+}
+/** 单工作区的趋势。 */
+export interface WorkspaceTrend {
+    readonly buckets: readonly TrendBucket[];
+    /** 实际有数据的第一天（早于窗口起点则等于窗口起点）。 */
+    readonly coverageFrom: string;
+    readonly coverageTo: string;
+}
+/** 单工作区趋势（skill `stats --trend week --last 8w --by-owner`；过 1.5s 读缓存）。 */
+export declare function readTrend(workspace: LedgerWorkspace): Promise<WorkspaceTrend>;
+/** `stats --trend` → {@link WorkspaceTrend}（容器级严格：缺字段即坏，不当 0）。 */
+export declare function parseTrend(raw: unknown, where: string): WorkspaceTrend;

package/dist/host/repositories/trend.repository.js

@@ -0,0 +1,92 @@
+/**
+ * 趋势面取数：近 8 周的「完成 / 未结 / 新增」，**整段桶序列一次拿回**（skill `stats --trend`）。
+ *
+ * 为什么不再拼现有方法：`history --count-only` 只给单窗口总数、且按**结案时间**过滤（新增取不到）；
+ * 插件侧拉全量明细再聚合已被实测否决（20 万条 3s+、30MB 过进程边界）。
+ * 桶边界（周一起算 / 本机时区）与「未结 = 该周末仍未结案」的倒推算法全在 skill，
+ * 本文件只做形状校验 —— 与 stats 同一条纪律：数字真源只有 skill 一份。
+ *
+ * 形状不符一律抛 {@link LedgerDataError}（不拿 0 充数）。
+ */
+import { LedgerDataError } from "../errors.js";
+import { cached, cacheKey } from "./cache.js";
+import { runLedgerScript } from "./runner.js";
+/** 趋势图的窗口（周数）：与首页右侧卡位一致（2026-10-17 定稿「近 8 周」）。 */
+export const TREND_WEEKS = 8;
+const TREND_LAST = `${String(TREND_WEEKS)}w`;
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function num(source, key, where) {
+    const value = source[key];
+    if (typeof value !== "number" || !Number.isFinite(value))
+        throw new LedgerDataError(where, `${where}: stats --trend 输出缺少数字字段 ${key}，格式可能已变`);
+    return value;
+}
+function day(source, key, where) {
+    const value = source[key];
+    if (typeof value !== "string" || value === "")
+        throw new LedgerDataError(where, `${where}: stats --trend 输出缺少日期字段 ${key}，格式可能已变`);
+    return value;
+}
+/** 按人明细：没有这个字段（没要 --by-owner）返回 undefined；有就必须是合法的三数对象。 */
+function parseOwners(raw, where) {
+    if (raw === undefined)
+        return undefined;
+    if (!isPlainObject(raw))
+        throw new LedgerDataError(where, `${where}: stats --trend 的 owners 不是对象，格式可能已变`);
+    const out = {};
+    for (const [uuid, cell] of Object.entries(raw)) {
+        if (!isPlainObject(cell))
+            throw new LedgerDataError(where, `${where}: stats --trend 里 ${uuid} 的按人明细不是对象`);
+        out[uuid] = {
+            added: num(cell, "added", where),
+            done: num(cell, "done", where),
+            open: num(cell, "open", where),
+        };
+    }
+    return out;
+}
+/** 单工作区趋势（skill `stats --trend week --last 8w --by-owner`；过 1.5s 读缓存）。 */
+export async function readTrend(workspace) {
+    // 缓存 op 仍记 "stats"（脚本子命令就是 stats），detail 里写清是哪个窗口的趋势
+    return await cached(cacheKey(workspace.id, "stats", `trend:${TREND_LAST}`), async () => {
+        // 趋势自带 JSON 输出，**不能**再传 --json（skill 那边是用法错）
+        const result = await runLedgerScript("stats", 
+        // --by-owner：一次就把「全部」与「按人」两套数都拿回来 ⇒ 勾「只看我的」零请求
+        ["--repo", workspace.path, "--trend", "week", "--last", TREND_LAST, "--by-owner"], 
+        // 8 周窗口最坏要读 3 个历史文件，比单月读重：给到 20s 再判超时
+        { timeoutMs: 20_000 });
+        if (!result.ok)
+            throw new Error(`${workspace.title}: ${result.error}`);
+        return parseTrend(result.data, workspace.title);
+    });
+}
+/** `stats --trend` → {@link WorkspaceTrend}（容器级严格：缺字段即坏，不当 0）。 */
+export function parseTrend(raw, where) {
+    if (!isPlainObject(raw))
+        throw new LedgerDataError(where, `${where}: stats --trend 输出不是对象，格式可能已变`);
+    const coverage = raw.coverage;
+    if (!isPlainObject(coverage))
+        throw new LedgerDataError(where, `${where}: stats --trend 输出缺 coverage，无法判断数据从哪天起有效`);
+    if (!Array.isArray(raw.buckets))
+        throw new LedgerDataError(where, `${where}: stats --trend 输出缺 buckets 数组，格式可能已变`);
+    const buckets = raw.buckets.map((item) => {
+        if (!isPlainObject(item))
+            throw new LedgerDataError(where, `${where}: stats --trend 的桶不是对象`);
+        const owners = parseOwners(item.owners, where);
+        return {
+            from: day(item, "from", where),
+            to: day(item, "to", where),
+            added: num(item, "added", where),
+            done: num(item, "done", where),
+            open: num(item, "open", where),
+            ...(owners === undefined ? {} : { owners }),
+        };
+    });
+    return {
+        buckets,
+        coverageFrom: day(coverage, "from", where),
+        coverageTo: day(coverage, "to", where),
+    };
+}

package/dist/host/services/stats.service.js

@@ -3,10 +3,11 @@
  *
  * 数字真源全在 skill：每工作区跑 `stats --json`（在办各面）与两次
  * `history --count-only`（本周 / 上周完成），本文件只做跨工作区求和与降级归集。
- * 趋势图（近 8 周）没有 skill 方法，本轮不提供数据。
+ * 趋势图（近 8 周）由 `trend.service.ts` 走 `stats --trend` 单独算，随首屏一起打包回来。
  */
 import { codeOf, messageOf, settleWorkspaces, } from "../errors.js";
 import { getCurrentIdentity } from "../repositories/identity.repository.js";
+import { getBoardTrend } from "./trend.service.js";
 import { readOwners, readTasks } from "../repositories/ledger.repository.js";
 import { countClosed, readStats, } from "../repositories/stats.repository.js";
 import { weekWindow } from "./dates.js";
@@ -60,10 +61,11 @@ function dedupe(rows) {
  * 三条读并行（`stats` / `list` / `owners`），各自缓存；一个工作区坏只进 degraded，其余照常。
  */
 export async function getBoardHome(workspaces, now = new Date()) {
-    const [statsPayload, taskScope, ownerScope] = await Promise.all([
+    const [statsPayload, taskScope, ownerScope, trend] = await Promise.all([
         getBoardStats(workspaces, now),
         settleWorkspaces(workspaces, "list", readTaskScope, (rows) => rows),
         settleWorkspaces(workspaces, "owners", readOwners, (rows) => rows),
+        getBoardTrend(workspaces),
     ]);
     const identities = {};
     const tasks = [];
@@ -73,6 +75,7 @@ export async function getBoardHome(workspaces, now = new Date()) {
     }
     return {
         ...statsPayload,
+        trend: { buckets: trend.buckets, coverageFrom: trend.coverageFrom, coverageTo: trend.coverageTo },
         workspaces,
         tasks,
         identities,
@@ -81,6 +84,7 @@ export async function getBoardHome(workspaces, now = new Date()) {
             ...statsPayload.degraded,
             ...taskScope.degraded,
             ...ownerScope.degraded,
+            ...trend.degraded,
         ]),
     };
 }

package/dist/host/services/trend.service.d.ts

@@ -0,0 +1,13 @@
+import { type TrendBucket } from "../repositories/trend.repository.js";
+import type { LedgerWorkspace, TrendPayload, TrendView } from "../types.js";
+/**
+ * 跨工作区求和：同一天起止的周桶相加。
+ * 工作区之间周界一致（同机同时区、都由 skill 的周一起算），所以直接按 `from` 归并。
+ */
+export declare function mergeTrend(rows: readonly {
+    buckets: readonly TrendBucket[];
+    coverageFrom: string;
+    coverageTo: string;
+}[]): TrendView;
+/** 趋势图数据：逐工作区读、坏的进 degraded，全挂给空桶（不抛）。 */
+export declare function getBoardTrend(workspaces: readonly LedgerWorkspace[]): Promise<TrendPayload>;

package/dist/host/services/trend.service.js

@@ -0,0 +1,82 @@
+/**
+ * 首页趋势图的用例：跨工作区把「近 8 周」的桶**按周求和**。
+ *
+ * 数字真源全在 skill（每工作区 `stats --trend week --last 8w`），本文件只做两件事：
+ * 按 `from` 把各工作区同周的数加在一起、把读挂的工作区归进 `degraded`。
+ *
+ * ⚠️ 这里**不抛**「全部失败」：趋势只是首页的一块图，不能因为它把 8 张卡和列表一起打成 500。
+ * 全挂时返回空桶 + inherited degraded，界面显示空态（真源口径见 errors.ts 的 settleWorkspaces 注释）。
+ */
+import { codeOf, messageOf } from "../errors.js";
+import { readTrend } from "../repositories/trend.repository.js";
+const byFrom = (a, b) => a.from < b.from ? -1 : a.from > b.from ? 1 : 0;
+/**
+ * 跨工作区求和：同一天起止的周桶相加。
+ * 工作区之间周界一致（同机同时区、都由 skill 的周一起算），所以直接按 `from` 归并。
+ */
+export function mergeTrend(rows) {
+    const merged = new Map();
+    let coverageFrom = "";
+    let coverageTo = "";
+    for (const row of rows) {
+        for (const bucket of row.buckets) {
+            let current = merged.get(bucket.from);
+            if (current === undefined) {
+                current = {
+                    from: bucket.from,
+                    to: bucket.to,
+                    added: 0,
+                    done: 0,
+                    open: 0,
+                    owners: {},
+                };
+                merged.set(bucket.from, current);
+            }
+            // 已有对象就原地累加（同一份数据只在本函数里生成，不会被外部共享）
+            current.added += bucket.added;
+            current.done += bucket.done;
+            current.open += bucket.open;
+            for (const [uuid, cell] of Object.entries(bucket.owners ?? {})) {
+                const owner = current.owners[uuid] ?? { added: 0, done: 0, open: 0 };
+                current.owners[uuid] = {
+                    added: owner.added + cell.added,
+                    done: owner.done + cell.done,
+                    open: owner.open + cell.open,
+                };
+            }
+        }
+        // 有数据的第一天取各工作区里最早的；最后一天取最晚的
+        if (row.coverageFrom !== "") {
+            if (coverageFrom === "" || row.coverageFrom < coverageFrom)
+                coverageFrom = row.coverageFrom;
+        }
+        if (row.coverageTo !== "" && row.coverageTo > coverageTo)
+            coverageTo = row.coverageTo;
+    }
+    return {
+        buckets: [...merged.values()].sort(byFrom),
+        coverageFrom,
+        coverageTo,
+    };
+}
+/** 趋势图数据：逐工作区读、坏的进 degraded，全挂给空桶（不抛）。 */
+export async function getBoardTrend(workspaces) {
+    const settled = await Promise.allSettled(workspaces.map((workspace) => readTrend(workspace)));
+    const rows = [];
+    const degraded = [];
+    settled.forEach((result, i) => {
+        if (result.status === "fulfilled") {
+            rows.push(result.value);
+            return;
+        }
+        const workspace = workspaces[i];
+        degraded.push({
+            workspaceId: workspace.id,
+            workspaceTitle: workspace.title,
+            op: "trend",
+            code: codeOf(result.reason),
+            message: messageOf(result.reason),
+        });
+    });
+    return { ...mergeTrend(rows), degraded };
+}

package/dist/host/types.d.ts

@@ -114,6 +114,32 @@ export interface StatsPayload {
     readonly stats: BoardStatsView;
     readonly degraded: readonly DegradedInfo[];
 }
+/** 一个人在一个周桶里的三个数（新增按 creator、完成 / 未结按 owner，都是 skill 的口径）。 */
+export interface TrendOwnerCounts {
+    readonly added: number;
+    readonly done: number;
+    readonly open: number;
+}
+/** 趋势图的一根周桶（数字全由 skill `stats --trend --by-owner` 给，插件只跨工作区相加）。 */
+export interface TrendBucketView {
+    readonly from: string;
+    readonly to: string;
+    readonly added: number;
+    readonly done: number;
+    readonly open: number;
+    /** uuid → 按人明细；「只看我的」直接取自己那条，勾选零请求。 */
+    readonly owners: Readonly<Record<string, TrendOwnerCounts>>;
+}
+/** 趋势图数据：近 8 周桶序列 + 实际有数据的第一天。 */
+export interface TrendView {
+    readonly buckets: readonly TrendBucketView[];
+    readonly coverageFrom: string;
+    readonly coverageTo: string;
+}
+/** 趋势数据 + 降级（自带一条，免得拖垮整个快照）。 */
+export interface TrendPayload extends TrendView {
+    readonly degraded: readonly DegradedInfo[];
+}
 /** 一个工作区的花名册（skill `owners --json`：含当前没任务的人）。 */
 export interface WorkspaceOwners {
     readonly workspaceId: string;
@@ -130,6 +156,8 @@ export interface WorkspaceOwners {
  * 前端只筛不判。
  */
 export interface BoardHomePayload extends StatsPayload {
+    /** 首页右侧趋势图（近 8 周）。 */
+    readonly trend: TrendView;
     readonly workspaces: readonly LedgerWorkspace[];
     readonly tasks: readonly TaskRow[];
     readonly identities: Readonly<Record<string, string | null>>;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "dsh-task-ledger",
-	"version": "0.0.114",
+	"version": "0.0.116",
 	"description": "Task ledger board for dsh (DeepSeek Harness): read-only board over task-ledger skill workspaces. The task-ledger skill is bundled — install the plugin, get the skill globally.",
 	"keywords": [
 		"deepseek",

package/skill/SKILL.md

@@ -152,6 +152,44 @@ allowed-tools: Read,Edit,Bash,Grep
 
 举例：「我这有几条卡住了」→ `stats --mine`；「整体积压多严重」→ `stats --json`。
 
+#### `stats --trend` — 按周期分桶的趋势
+
+| 参数 | 含义 |
+|---|---|
+| `--trend <粒度>` | `day` / `week` / `month` / `quarter` / `year`（桶边界：日 00:00、**周一**、自然月、自然季、自然年，全按本机时区） |
+| `--last <N><d\|w\|m\|y>` | 最近 N 个日 / 周 / 月 / 年（与 `--since` / `--until` **二选一**；默认 `8w`） |
+| `--since` / `--until <日期>` | 显式区间（与 `list` 同样的本地时区口径）；首尾桶**按区间裁剪** —— 从周三起算，第一桶就只有周三起的数据 |
+| `--mine` / `--owner <uuid>[,<uuid>]` | 只看自己 / 某几个人（`--owner` 可给多个 uuid，与 `--mine` 互斥） |
+| `--by-owner` | 每个桶额外带按人明细（默认不返回，只给总数） |
+
+干什么：一次遍历返回**整段桶序列**（不按桶多次调用），每桶三个数 —— `added`（该桶内新建）、`done`（该桶内结案）、`open`（该桶**结束时**仍未结案）。
+
+口径：`added` 按 `created`、`done` 按 `finished`；`open` 由「当前在办 + 今天往前倒推」得出，天然含窗口之前遗留的基线。按人明细里 `added` 按 `creator`、`done` / `open` 按 `owner`（待认领不算任何人）。
+
+按人的 `open` 只算**你名下**的任务，倒推时同时减去「你在那天之后新建的」（按 owner 计，与展示用的 creator 无关）—— 否则窗口之后才建、早已结案的任务会被当成那天就在办，越靠前的桶虚高得越离谱。负责人转交过的任务按**今天**的负责人归账。
+
+**只出 JSON**（表格由界面渲染；给 `--json` 是用法错）：
+
+```json
+{
+  "granularity": "week",
+  "coverage": { "from": "2026-09-01", "to": "2026-10-29" },
+  "buckets": [
+    { "from": "2026-09-01", "to": "2026-09-06", "added": 3, "done": 5, "open": 12,
+      "owners": { "<uuid>": { "name": "某人", "added": 1, "done": 2, "open": 4 } } }
+  ],
+  "warnings": []
+}
+```
+
+- `from` / `to` 是**本地日期**（含边界）；展示标签（`第 40 周` / `2026-10` …）由前端按粒度自己生成，脚本不回任何标签。
+- `coverage.from` 是实际有数据的第一天；窗口里早于它的部分没有数据（前端显示「数据不足」，不画 0）。
+- `owners` 只有加 `--by-owner` 才出现；人名实时取自名册，不进缓存。
+- 上限按**时间跨度**定，不按读几个文件定：一次最多 10 年（3660 天）；`day` 粒度另有 365 天上限（一天一桶没人看十年）。超了直接报错，不返回半截数据。缓存文件不计入任何上限（命中的月份根本不读源文件）。
+- 已过完的本地月会落一份本机缓存（`~/.taskledger/cache/trend/`，不进 git、随时可删）；当月永远实时算。缓存不改变**能查多久**（历史文件从不清理，10 年就是 120 个文件在盘上），只决定**查得多快**。
+
+举例：「最近 8 周每周完成多少」→ `stats --trend week`；「今年每月按人看」→ `stats --trend month --last 12m --by-owner`。
+
 ### owners — 花名册
 
 | 参数 | 含义 |
@@ -243,7 +281,7 @@ allowed-tools: Read,Edit,Bash,Grep
 
 - 定位项目：`--repo <工作区根>`（**直接含有 `ledger/` 的那个目录**）给了就校验后用；不给就从当前目录逐级向上找。`ledger/` 本身、以及它下面的任何子目录都不是根，指过去会被直接拒绝（判据只看位置，不看目录里有哪些文件 —— 项目根自带 `pool.json`、`history/`、`worklog/` 都不影响）。
 - `--no-sync`（放在子命令**前**）：用户明确要求「先别同步」时才用；之后自己 `git add ledger && commit && push`。
-- `--json` 只对只读命令（`list` / `stats` / `owners` / `show` / `history` / `root` / `whoami` / `validate`）有意义；写命令不接收 `--json`，传了是用法错。
+- `--json` 只对只读命令（`list` / `stats` / `owners` / `show` / `history` / `root` / `whoami` / `validate`）有意义；写命令不接收 `--json`，传了是用法错。`stats --trend` 自带 JSON，不用也不接受 `--json`。
 - **给界面喂数**：要看在办用 `list`、要各面计数用 `stats`、要人选列表用 `owners`、要判断某个目录有没有台账用 `root` —— 都是只读、都不改台账；多个 / 跨工作区自己扇出，脚本一次只服务一个工作区。
 - **时间**：存盘一律 UTC，脚本对外**一律给本机时区**（人话表格与 `--json` 都是），拿到直接显示，不要再转一次；`--since` / `--until` / `--created` / `--finished` 也按本机时区给，脚本内部转 UTC 比较。过程文档正文里的时间是原文，脚本不碰。
 - 命令回执只用来确认生效；任务状态以 `show` / `list` 为准。

package/skill/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "task-ledger",
-	"version": "1.3.40",
+	"version": "1.3.42",
 	"description": "Task-ledger skill for coding agents: per-workspace progress tracking (ledger/pool.json + owners/<hash>.json shards + owners.json index, history, worklog) driven by a CLI script. Standalone install for CodeBuddy and other agents; also bundled inside the dsh-task-ledger DSH plugin.",
 	"keywords": [
 		"skill",