dsh-task-ledger 0.0.44 → 0.0.46

package/dist/host/{ledger-read.js → repositories/ledger.repository.js}

@@ -1,6 +1,10 @@
+import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
-import { runLedgerScript } from './script.js';
+import { runLedgerScript } from './runner.js';
+import { parseHistoryRecords, parseTaskList } from './records.js';
+/** 台账目录名（各工作区根下的这一个目录；布局知识只在本文件出现一次）。 */
+const LEDGER_DIR = 'ledger';
 /**
  * LedgerFilter → skill 脚本参数（只拼调用方给了的；undefined 一律不拼，
  * 让脚本走自己的默认——插件不替脚本决定默认值）。
@@ -26,21 +30,29 @@ export function filterArgs(filter) {
     return args;
 }
 /**
- * 在办任务（包 `list --json`；结果打上 workspace）。
- * 脚本失败抛错——路由层转 500 + 人话，不静默返空（空 = 撒谎）。
+ * 台账工作区探测：`<path>/ledger/progress.json` 在才算（未初始化 = 后端不可见，
+ * 2026-10-17 拍板）。全 host 对台账目录的 IO 只在本文件——别处再写 existsSync 即为分层倒退。
+ */
+export function hasLedger(workspacePath) {
+    return existsSync(path.join(workspacePath, LEDGER_DIR, 'progress.json'));
+}
+/**
+ * 在办任务（包 `list --json`；结果过 records 入口校验后打上 workspace）。
+ * 脚本失败 / 形状不符抛错——由 service 层捕获进 degraded，路由层转 500 + 人话，
+ * 不静默返空（空 = 撒谎）。
  */
 export async function readTasks(workspace, filter = {}) {
     const result = await runLedgerScript('list', ['--repo', workspace.path, '--json', ...filterArgs(filter)]);
     if (!result.ok)
         throw new Error(`${workspace.title}: ${result.error}`);
-    return Object.entries(result.data).map(([id, task]) => ({ ...task, id, workspace }));
+    return parseTaskList(result.data, workspace);
 }
-/** 已结案记录（包 `history --json`；结果打上 workspace）。 */
+/** 已结案记录（包 `history --json`；`records` 必须存在且为数组，缺了即坏数据）。 */
 export async function readHistory(workspace, filter = {}) {
     const result = await runLedgerScript('history', ['--repo', workspace.path, '--json', ...filterArgs(filter)]);
     if (!result.ok)
         throw new Error(`${workspace.title}: ${result.error}`);
-    return (result.data.records ?? []).map((record) => ({ ...record, workspace }));
+    return parseHistoryRecords(result.data, workspace);
 }
 /** 单条在办（展开行 / 详情用）。取不到回 null，不抛。 */
 export async function getTask(workspace, taskId) {
@@ -56,7 +68,7 @@ export async function readWorklog(workspace, task) {
     if (relative === undefined || relative === null || relative === '')
         return null;
     try {
-        return await readFile(path.join(workspace.path, 'ledger', relative), 'utf-8');
+        return await readFile(path.join(workspace.path, LEDGER_DIR, relative), 'utf-8');
     }
     catch {
         return null;

package/dist/host/repositories/records.d.ts

@@ -0,0 +1,5 @@
+import type { HistoryRecord, LedgerWorkspace, TaskRow } from '../types.js';
+/** `list --json`（任务号为键的对象）→ TaskRow[]（打上 id 与 workspace）。 */
+export declare function parseTaskList(raw: unknown, workspace: LedgerWorkspace): TaskRow[];
+/** `history --json`（`{count, filters, records}`）→ HistoryRecord[]（打上 workspace）。 */
+export declare function parseHistoryRecords(raw: unknown, workspace: LedgerWorkspace): HistoryRecord[];

package/dist/host/repositories/records.js

@@ -0,0 +1,48 @@
+/**
+ * 入口校验（纯函数）：skill 脚本 JSON → 领域对象。
+ *
+ * 口径：**容器级严格、元素级宽松**。
+ * - 容器：`list --json` 顶层必须是 plain object（任务号为键）；`history --json` 的 `records`
+ *   必须存在且为数组（现状 `records ?? []` 的容忍在脚本回归时会静默产出空历史 = 撒谎）；
+ * - 元素：是 object 就收，字段缺失一律放行（TaskRecord 全字段可选是脚本既有契约，
+ *   旧 8 列 history 不因此被误杀）。
+ * 失败抛 {@link LedgerDataError}——由 service 层捕获进 degraded，不静默。
+ */
+import { LedgerDataError } from '../errors.js';
+function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/** `list --json`（任务号为键的对象）→ TaskRow[]（打上 id 与 workspace）。 */
+export function parseTaskList(raw, workspace) {
+    if (!isPlainObject(raw)) {
+        throw new LedgerDataError(workspace.id, `${workspace.title}: 台账 list 输出不是「任务号为键的对象」，拒绝当成空列表`);
+    }
+    const rows = [];
+    for (const [id, value] of Object.entries(raw)) {
+        if (!isPlainObject(value)) {
+            throw new LedgerDataError(workspace.id, `${workspace.title}: 任务 ${id} 不是对象，台账格式可能已变`);
+        }
+        if (id === '') {
+            throw new LedgerDataError(workspace.id, `${workspace.title}: 台账存在空任务号，格式可能已变`);
+        }
+        rows.push({ ...value, id, workspace });
+    }
+    return rows;
+}
+/** `history --json`（`{count, filters, records}`）→ HistoryRecord[]（打上 workspace）。 */
+export function parseHistoryRecords(raw, workspace) {
+    if (!isPlainObject(raw)) {
+        throw new LedgerDataError(workspace.id, `${workspace.title}: 台账 history 输出不是对象，拒绝当成空历史`);
+    }
+    const records = raw.records;
+    if (!Array.isArray(records)) {
+        throw new LedgerDataError(workspace.id, `${workspace.title}: 台账 history 输出缺 records 数组，格式可能已变`);
+    }
+    const rows = [];
+    for (const record of records) {
+        if (!isPlainObject(record))
+            continue; // 元素级宽松：坏行跳过，不整板炸
+        rows.push({ ...record, workspace });
+    }
+    return rows;
+}

package/dist/host/{script.js → repositories/runner.js}

@@ -1,10 +1,11 @@
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 /**
- * 内嵌 skill 脚本的默认路径：dist/host/script.js → 包根 skill/scripts/progress.py。
+ * 内嵌 skill 脚本的默认路径：dist/host/repositories/runner.js → 包根 skill/scripts/progress.py
+ * （比原 host/script.js 深一层 ⇒ 相对路径多一级 `../`）。
  * 构建时 scripts/copy-skill.mjs 把 packages/skill 拷到 packages/plugin/skill/。
  */
-const DEFAULT_SCRIPT_PATH = fileURLToPath(new URL('../../skill/scripts/progress.py', import.meta.url));
+const DEFAULT_SCRIPT_PATH = fileURLToPath(new URL('../../../skill/scripts/progress.py', import.meta.url));
 /** 单次脚本调用超时上限（ms）。实测单仓 5 万行全量 1.2s，10s 是宽松上限。 */
 const DEFAULT_TIMEOUT_MS = 10_000;
 /**

package/dist/host/routes.js

@@ -1,5 +1,5 @@
 import { getHomeAggregate, getFilterOptions, queryClosed } from './board.js';
-import { getTask, readTasks, readWorklog } from './ledger-read.js';
+import { getTask, readTasks, readWorklog } from './repositories/ledger.repository.js';
 import { resolveWorkspaces } from './workspace.js';
 /** API 前缀（唯一真源就在这一处）。 */
 const API_PREFIX = '/api/task-ledger';
@@ -47,7 +47,7 @@ function filterFromQuery(url) {
         filter.months = months;
     return filter;
 }
-/** 每请求重新解析工作区（registry 可能刚变；existsSync × N 是微秒级，不缓存）。 */
+/** 每请求重新解析工作区（registry 可能刚变；探测走 hasLedger()，微秒级，不缓存）。 */
 function workspacesOf(deps) {
     return resolveWorkspaces(deps.registry.list());
 }
@@ -64,7 +64,7 @@ export function registerRoutes(webServer, deps) {
         handler: async (_req, res) => {
             try {
                 const home = await getHomeAggregate(workspacesOf(deps));
-                sendJson(res, 200, { ...home.snapshot, closed: home.closed, trend: home.trend });
+                sendJson(res, 200, { ...home.snapshot, closed: home.closed, trend: home.trend, degraded: home.degraded });
             }
             catch (error) {
                 sendJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
@@ -116,7 +116,8 @@ export function registerRoutes(webServer, deps) {
         handler: async (req, res) => {
             try {
                 const filter = filterFromQuery(new URL(req.url ?? '/', 'http://localhost'));
-                sendJson(res, 200, { records: await queryClosed(workspacesOf(deps), filter) });
+                const result = await queryClosed(workspacesOf(deps), filter);
+                sendJson(res, 200, { records: result.records, degraded: result.degraded });
             }
             catch (error) {
                 sendJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
@@ -128,7 +129,8 @@ export function registerRoutes(webServer, deps) {
         path: `${API_PREFIX}/filters`,
         handler: async (_req, res) => {
             try {
-                sendJson(res, 200, await getFilterOptions(workspacesOf(deps)));
+                const result = await getFilterOptions(workspacesOf(deps));
+                sendJson(res, 200, { ...result.options, degraded: result.degraded });
             }
             catch (error) {
                 sendJson(res, 500, { error: error instanceof Error ? error.message : String(error) });

package/dist/host/services/dates.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 日期口径（纯函数层，零 IO）：本机时区、周一为一周之始（与 skill 脚本同口径）。
+ * 所有函数显式收 `now`——不自己读时钟，便于单测与跨时区复现。
+ */
+/** Date → `YYYY-MM-DD`。 */
+export declare function ymd(date: Date): string;
+/** 时刻串（`YYYY-MM-DD HH:mm:ss` / `YYYY-MM-DD`）→ 日期部分；解析不了回 null。 */
+export declare function dayOf(stamp: string | null | undefined): string | null;
+/** 某日期所在周的周一（00:00）。 */
+export declare function mondayOf(day: string): Date;
+/**
+ * 第 offset 周的起止（offset 0 = 本周，-1 = 上周；返回日期串，含边界）。
+ * ⚠️ 本周只到今天（周还没结束），上周才是完整周一~周日——否则「本周」会把明天之后的
+ * 日子也画进区间，tooltip 里的截止日撒谎。
+ */
+export declare function weekWindow(offset: number, now: Date): {
+    from: string;
+    to: string;
+};
+/** 第 offset 月的起止（offset 0 = 本月，-1 = 上月；含边界）。
+ *  同 {@link weekWindow}：本月只到今天，上月才是完整自然月。 */
+export declare function monthWindow(offset: number, now: Date): {
+    from: string;
+    to: string;
+};
+/** 日期是否落在 [from, to]（含边界，字符串比较即可——ISO 字典序即时间序）。 */
+export declare function inWindow(day: string | null, window: {
+    from: string;
+    to: string;
+}): boolean;
+/** 「YYYY-MM-DD HH:mm:ss」→ 距今天数（解析不了 / 未来都按 0；不编造）。 */
+export declare function daysSince(stamp: string | null | undefined, now: Date): number | null;
+/** 近 N 周的桶骨架（`{week, end}`，历史周 end=周日、当前周 end=今天）。 */
+export declare function buildWeeks(count: number, now: Date): readonly {
+    week: string;
+    end: string;
+}[];

package/dist/host/services/dates.js

@@ -0,0 +1,71 @@
+/**
+ * 日期口径（纯函数层，零 IO）：本机时区、周一为一周之始（与 skill 脚本同口径）。
+ * 所有函数显式收 `now`——不自己读时钟，便于单测与跨时区复现。
+ */
+function pad(value) {
+    return String(value).padStart(2, '0');
+}
+/** Date → `YYYY-MM-DD`。 */
+export function ymd(date) {
+    return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+}
+/** 时刻串（`YYYY-MM-DD HH:mm:ss` / `YYYY-MM-DD`）→ 日期部分；解析不了回 null。 */
+export function dayOf(stamp) {
+    if (stamp === null || stamp === undefined || stamp === '')
+        return null;
+    const day = String(stamp).slice(0, 10);
+    return /^\d{4}-\d{2}-\d{2}$/.test(day) ? day : null;
+}
+/** 某日期所在周的周一（00:00）。 */
+export function mondayOf(day) {
+    const date = new Date(`${day}T00:00:00`);
+    date.setDate(date.getDate() - ((date.getDay() + 6) % 7));
+    return date;
+}
+/**
+ * 第 offset 周的起止（offset 0 = 本周，-1 = 上周；返回日期串，含边界）。
+ * ⚠️ 本周只到今天（周还没结束），上周才是完整周一~周日——否则「本周」会把明天之后的
+ * 日子也画进区间，tooltip 里的截止日撒谎。
+ */
+export function weekWindow(offset, now) {
+    const monday = mondayOf(ymd(now));
+    monday.setDate(monday.getDate() + offset * 7);
+    const sunday = new Date(monday);
+    sunday.setDate(sunday.getDate() + 6);
+    const last = offset === 0 ? now : sunday;
+    return { from: ymd(monday), to: ymd(last < sunday ? last : sunday) };
+}
+/** 第 offset 月的起止（offset 0 = 本月，-1 = 上月；含边界）。
+ *  同 {@link weekWindow}：本月只到今天，上月才是完整自然月。 */
+export function monthWindow(offset, now) {
+    const first = new Date(now.getFullYear(), now.getMonth() + offset, 1);
+    const last = new Date(now.getFullYear(), now.getMonth() + offset + 1, 0);
+    const end = offset === 0 ? now : last;
+    return { from: ymd(first), to: ymd(end < last ? end : last) };
+}
+/** 日期是否落在 [from, to]（含边界，字符串比较即可——ISO 字典序即时间序）。 */
+export function inWindow(day, window) {
+    return day !== null && day >= window.from && day <= window.to;
+}
+/** 「YYYY-MM-DD HH:mm:ss」→ 距今天数（解析不了 / 未来都按 0；不编造）。 */
+export function daysSince(stamp, now) {
+    if (stamp === null || stamp === undefined || stamp === '')
+        return null;
+    const parsed = new Date(String(stamp).replace(' ', 'T'));
+    if (Number.isNaN(parsed.getTime()))
+        return null;
+    const days = Math.floor((now.getTime() - parsed.getTime()) / 86_400_000);
+    return days > 0 ? days : 0;
+}
+/** 近 N 周的桶骨架（`{week, end}`，历史周 end=周日、当前周 end=今天）。 */
+export function buildWeeks(count, now) {
+    const weeks = [];
+    for (let offset = count - 1; offset >= 0; offset -= 1)
+        weeks.push(weekWindow(-offset, now).from);
+    return weeks.map((week, i) => {
+        const monday = new Date(`${week}T00:00:00`);
+        const sunday = new Date(monday);
+        sunday.setDate(sunday.getDate() + 6);
+        return { week, end: i === weeks.length - 1 ? ymd(now) : ymd(sunday) };
+    });
+}

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

@@ -0,0 +1,24 @@
+import { type DegradedInfo } from '../errors.js';
+import type { FilterOptions, HistoryRecord, LedgerFilter, LedgerWorkspace, TrendScope } from '../types.js';
+/** 已结案列表默认分页大小（「加载更多」= 调用方加大 limit 重取）。 */
+export declare const DEFAULT_HISTORY_LIMIT = 500;
+/**
+ * 已结案列表：默认近 13 个月 + limit 500，跨工作区合并后按创建时间倒序。
+ * shortcut: 分页用「加大 limit 重取」的笨办法（skill 脚本无 offset）；
+ * 单工作区内 limit 已生效，合并边界的全局精确排序暂不保证（500 条一页无感）。
+ * 要全量老数据：调用方显式传 months: undefined（不拼 --months，脚本读全部，按秒计）。
+ */
+export declare function queryClosed(workspaces: readonly LedgerWorkspace[], filter?: LedgerFilter): Promise<{
+    records: HistoryRecord[];
+    degraded: readonly DegradedInfo[];
+}>;
+/** 候选值收集（纯函数）：owner/category/tag 去重 + 排序。 */
+export declare function collectFilterOptions(scopes: readonly TrendScope[]): FilterOptions;
+/**
+ * 筛选项候选：在办（全量）+ 近 13 个月历史的去重值（owner / category / tag）。
+ * 按需调用（/filters 路由），非首屏——历史侧在极端量级下是百毫秒级。单工作区坏 ⇒ 进 degraded。
+ */
+export declare function getFilterOptions(workspaces: readonly LedgerWorkspace[]): Promise<{
+    options: FilterOptions;
+    degraded: readonly DegradedInfo[];
+}>;

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

@@ -0,0 +1,61 @@
+/**
+ * 已结案列表 / 筛选项候选用例（history tab 与筛选控件用；非首屏，按需调用）。
+ */
+import { readHistory, readTasks } from '../repositories/ledger.repository.js';
+import { settleWorkspaces } from '../errors.js';
+import { RECENT_MONTHS, readTrendScope } from './trend.service.js';
+/** 已结案列表默认分页大小（「加载更多」= 调用方加大 limit 重取）。 */
+export const DEFAULT_HISTORY_LIMIT = 500;
+/**
+ * 已结案列表：默认近 13 个月 + limit 500，跨工作区合并后按创建时间倒序。
+ * shortcut: 分页用「加大 limit 重取」的笨办法（skill 脚本无 offset）；
+ * 单工作区内 limit 已生效，合并边界的全局精确排序暂不保证（500 条一页无感）。
+ * 要全量老数据：调用方显式传 months: undefined（不拼 --months，脚本读全部，按秒计）。
+ */
+export async function queryClosed(workspaces, filter = {}) {
+    const windowed = { months: RECENT_MONTHS, ...filter };
+    const { data, degraded } = await settleWorkspaces(workspaces, 'history', (workspace) => readHistory(workspace, windowed), (rows) => rows.flat()
+        .sort((a, b) => String(b.created ?? b.time ?? '').localeCompare(String(a.created ?? a.time ?? '')))
+        .slice(0, filter.limit ?? DEFAULT_HISTORY_LIMIT));
+    return { records: data, degraded };
+}
+/** 候选值收集（纯函数）：owner/category/tag 去重 + 排序。 */
+export function collectFilterOptions(scopes) {
+    const owners = new Set();
+    const categories = new Set();
+    const tags = new Set();
+    const addTask = (task) => {
+        if (task.owner !== undefined && task.owner !== null && task.owner !== '')
+            owners.add(task.owner);
+        if (task.creator !== undefined && task.creator !== null && task.creator !== '')
+            owners.add(task.creator);
+        if (task.category !== undefined && task.category !== null && task.category !== '')
+            categories.add(task.category);
+        for (const tag of task.tags ?? [])
+            tags.add(tag);
+    };
+    const addRecord = (record) => {
+        if (record.owner !== undefined && record.owner !== '')
+            owners.add(record.owner);
+        if (record.category !== undefined && record.category !== null && record.category !== '')
+            categories.add(record.category);
+        for (const tag of record.tags ?? [])
+            tags.add(tag);
+    };
+    for (const scope of scopes) {
+        for (const task of scope.tasks)
+            addTask(task);
+        for (const record of scope.history)
+            addRecord(record);
+    }
+    const sorted = (values) => [...values].sort((a, b) => a.localeCompare(b, 'zh-Hans-CN'));
+    return { owners: sorted(owners), categories: sorted(categories), tags: sorted(tags) };
+}
+/**
+ * 筛选项候选：在办（全量）+ 近 13 个月历史的去重值（owner / category / tag）。
+ * 按需调用（/filters 路由），非首屏——历史侧在极端量级下是百毫秒级。单工作区坏 ⇒ 进 degraded。
+ */
+export async function getFilterOptions(workspaces) {
+    const { data, degraded } = await settleWorkspaces(workspaces, 'history', readTrendScope, collectFilterOptions);
+    return { options: data, degraded };
+}

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

@@ -0,0 +1,13 @@
+import { type DegradedInfo } from '../errors.js';
+import type { BoardSnapshot, LedgerWorkspace, TaskScope } from '../types.js';
+/** 停滞判定阈值：doing / blocked 且 created 至今超过这么多天（2026-10-17 拍板，显示级）。 */
+export declare const STALE_DAYS = 14;
+/** 快路径读法：单工作区 readTasks + git 身份（并行；供 settle 逐工作区调）。 */
+export declare function readTaskScope(workspace: LedgerWorkspace): Promise<TaskScope>;
+/** 在办行加工 + 六个统计面 + identities（纯函数；`now` 显式传入）。 */
+export declare function computeSnapshot(scopes: readonly TaskScope[], now: Date): BoardSnapshot;
+/** 快路径端点：在办快照（统计卡 + 身份 + 行加工）。单工作区坏 ⇒ 进 degraded，其余照常。 */
+export declare function getSnapshot(workspaces: readonly LedgerWorkspace[]): Promise<{
+    snapshot: BoardSnapshot;
+    degraded: readonly DegradedInfo[];
+}>;

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

@@ -0,0 +1,50 @@
+/**
+ * 首页**快路径**用例：在办快照 + 统计卡。
+ * 只读 progress.json（list）+ git 身份，**不碰 history**——首屏耗时与历史总量解耦
+ * （20 万条量级实测：527ms vs 合并端点 4.4s，见 docs/design/host-data-plane.md §四）。
+ * 慢路径（趋势）在 ./trend.service.ts；组合入口（/board 兼容全量）在 ../board.ts。
+ */
+import { readTasks } from '../repositories/ledger.repository.js';
+import { getCurrentIdentity } from '../repositories/identity.repository.js';
+import { settleWorkspaces } from '../errors.js';
+import { daysSince } from './dates.js';
+/** 停滞判定阈值：doing / blocked 且 created 至今超过这么多天（2026-10-17 拍板，显示级）。 */
+export const STALE_DAYS = 14;
+/** 快路径读法：单工作区 readTasks + git 身份（并行；供 settle 逐工作区调）。 */
+export async function readTaskScope(workspace) {
+    const [tasks, identity] = await Promise.all([readTasks(workspace), getCurrentIdentity(workspace)]);
+    return { workspace, tasks, identity };
+}
+/** 在办行加工 + 六个统计面 + identities（纯函数；`now` 显式传入）。 */
+export function computeSnapshot(scopes, now) {
+    const withMeta = scopes.flatMap((scope) => scope.tasks.map((task) => {
+        const working = task.status === 'doing' || task.status === 'blocked';
+        const ageDays = working ? daysSince(task.started ?? task.created, now) : null;
+        return { ...task, ageDays, stale: ageDays !== null && ageDays > STALE_DAYS };
+    }));
+    const openTasks = withMeta.filter((task) => task.status === 'open');
+    const blockedTasks = withMeta.filter((task) => task.status === 'blocked');
+    const myActive = scopes.reduce((sum, scope) => sum + scope.tasks.filter((task) => task.owner === scope.identity && (task.status === 'doing' || task.status === 'blocked')).length, 0);
+    const myBlocked = scopes.reduce((sum, scope) => sum + scope.tasks.filter((task) => task.owner === scope.identity && task.status === 'blocked').length, 0);
+    const identities = {};
+    for (const scope of scopes)
+        identities[scope.workspace.id] = scope.identity;
+    const stats = {
+        myActive,
+        myBlocked,
+        open: openTasks.length,
+        doing: withMeta.filter((task) => task.status === 'doing').length,
+        blocked: blockedTasks.length,
+        stale: withMeta.filter((task) => task.stale).length,
+        staleDays: STALE_DAYS,
+        oldestOpenDays: openTasks.length === 0
+            ? null
+            : openTasks.reduce((max, task) => Math.max(max, daysSince(task.created, now) ?? 0), 0),
+    };
+    return { at: now.toISOString(), workspaces: scopes.map((scope) => scope.workspace), tasks: withMeta, stats, identities };
+}
+/** 快路径端点：在办快照（统计卡 + 身份 + 行加工）。单工作区坏 ⇒ 进 degraded，其余照常。 */
+export async function getSnapshot(workspaces) {
+    const { data: scopes, degraded } = await settleWorkspaces(workspaces, 'list', readTaskScope, (rows) => rows);
+    return { snapshot: computeSnapshot(scopes, new Date()), degraded };
+}

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

@@ -0,0 +1,26 @@
+import { type DegradedInfo } from '../errors.js';
+import type { ClosedSummary, LedgerFilter, LedgerWorkspace, TrendPeriods, TrendScope } from '../types.js';
+/** 历史窗口：只读最近 13 个月的文件（2026-10-17 拍板；脚本默认读全部，窗口由插件显式传）。 */
+export declare const RECENT_MONTHS = 13;
+/** 趋势图桶数：近 8 周（2026-10-17 定稿）。 */
+export declare const WEEKLY_WEEKS = 8;
+/** 慢路径读法：单工作区 readTasks + readHistory(months) + git 身份（并行；供 settle 逐工作区调）。 */
+export declare function readTrendScope(workspace: LedgerWorkspace): Promise<TrendScope>;
+/**
+ * 近 N 周分组桶（完成按结案时间、新增按创建时间）× 所有 / 我的（纯函数）。
+ *
+ * 新增必须**合并两个来源**：已结案的任务被 close 移出 progress.json，只在 history 里；
+ * 在办的只在 progress.json 里。两者不相交（close 是移动），合并即全集、不会重复计。
+ * remaining：某任务在「第 i 周截止时」仍未完成 ⇔ 创建 ≤ weekEnd_i 且（未结案 或 结案 > weekEnd_i）。
+ */
+export declare function computeClosedSummary(scopes: readonly TrendScope[], now: Date): ClosedSummary;
+/** 四个自然周期（只算「全部工作区」范围；图表切换不带动卡片）——纯函数。 */
+export declare function computeTrendPeriods(scopes: readonly TrendScope[], now: Date): TrendPeriods;
+/** 慢路径端点：趋势 + 周期（读 history）。异步加载，首屏不等。单工作区坏 ⇒ 进 degraded。 */
+export declare function getTrend(workspaces: readonly LedgerWorkspace[]): Promise<{
+    closed: ClosedSummary;
+    trend: TrendPeriods;
+    degraded: readonly DegradedInfo[];
+}>;
+/** 趋势端点用的历史 filter（窗口由本模块策略决定，repository 零默认值注入）。 */
+export declare function trendHistoryFilter(extra?: LedgerFilter): LedgerFilter;

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

@@ -0,0 +1,134 @@
+/**
+ * 首页**慢路径**用例：近 8 周趋势 + 四个自然周期。
+ * 读 history（months=RECENT_MONTHS）+ 在办 + git 身份——首屏不等它（异步/按需拉）。
+ *
+ * ⚠️ 窗口必须是 13 个月而不是 2：8 周桶在月初会横跨 3 个自然月（如 10 月第 1 周回溯到 8 月），
+ * `--months` 是**文件级**过滤，缩到 2 会静默漏掉 8 月结案记录、趋势少算（2026-10-18 架构评审结论）。
+ */
+import { readHistory, readTasks } from '../repositories/ledger.repository.js';
+import { getCurrentIdentity } from '../repositories/identity.repository.js';
+import { settleWorkspaces } from '../errors.js';
+import { buildWeeks, dayOf, inWindow, monthWindow, mondayOf, weekWindow, ymd } from './dates.js';
+/** 历史窗口：只读最近 13 个月的文件（2026-10-17 拍板；脚本默认读全部，窗口由插件显式传）。 */
+export const RECENT_MONTHS = 13;
+/** 趋势图桶数：近 8 周（2026-10-17 定稿）。 */
+export const WEEKLY_WEEKS = 8;
+/** 慢路径读法：单工作区 readTasks + readHistory(months) + git 身份（并行；供 settle 逐工作区调）。 */
+export async function readTrendScope(workspace) {
+    const [tasks, history, identity] = await Promise.all([
+        readTasks(workspace),
+        readHistory(workspace, { months: RECENT_MONTHS }),
+        getCurrentIdentity(workspace),
+    ]);
+    return { workspace, tasks, history, identity };
+}
+/**
+ * 近 N 周分组桶（完成按结案时间、新增按创建时间）× 所有 / 我的（纯函数）。
+ *
+ * 新增必须**合并两个来源**：已结案的任务被 close 移出 progress.json，只在 history 里；
+ * 在办的只在 progress.json 里。两者不相交（close 是移动），合并即全集、不会重复计。
+ * remaining：某任务在「第 i 周截止时」仍未完成 ⇔ 创建 ≤ weekEnd_i 且（未结案 或 结案 > weekEnd_i）。
+ */
+export function computeClosedSummary(scopes, now) {
+    const weeks = buildWeeks(WEEKLY_WEEKS, now);
+    const weekEnds = weeks.map((slot) => slot.end);
+    const make = () => new Map(weeks.map((slot) => [slot.week, { done: 0, created: 0, remaining: 0 }]));
+    const bucketsAll = make();
+    const bucketsMine = make();
+    const bump = (map, week, field) => {
+        const bucket = map.get(week);
+        if (bucket !== undefined)
+            map.set(week, { ...bucket, [field]: bucket[field] + 1 });
+    };
+    const bumpRemaining = (map, createdDay, closeDay) => {
+        if (createdDay === null)
+            return;
+        for (let i = 0; i < weeks.length; i += 1) {
+            if (createdDay <= weekEnds[i] && (closeDay === null || closeDay > weekEnds[i])) {
+                const bucket = map.get(weeks[i].week);
+                if (bucket !== undefined)
+                    bucket.remaining += 1;
+            }
+        }
+    };
+    for (const scope of scopes) {
+        const identity = scope.identity;
+        for (const task of scope.tasks) {
+            const created = dayOf(task.created);
+            if (created === null)
+                continue;
+            const week = ymd(mondayOf(created));
+            const createdMine = identity !== null && (task.creator ?? null) === identity;
+            bump(bucketsAll, week, 'created');
+            if (createdMine)
+                bump(bucketsMine, week, 'created');
+            const ownedMine = identity !== null && (task.owner ?? null) === identity;
+            bumpRemaining(bucketsAll, created, null);
+            if (ownedMine)
+                bumpRemaining(bucketsMine, created, null);
+        }
+        for (const record of scope.history) {
+            const closed = dayOf(record.time);
+            if (closed !== null) {
+                const week = ymd(mondayOf(closed));
+                bump(bucketsAll, week, 'done');
+                if (identity !== null && (record.owner ?? null) === identity)
+                    bump(bucketsMine, week, 'done');
+            }
+            const created = dayOf(record.created);
+            if (created !== null) {
+                const week = ymd(mondayOf(created));
+                bump(bucketsAll, week, 'created');
+                // 新增（我的）= 我创建的（creator）；旧 8 列历史无 creator 列 ⇒ 兜底 owner
+                const createdMine = identity !== null && ((record.creator ?? null) === identity
+                    || ((record.creator ?? null) === null && (record.owner ?? null) === identity));
+                if (createdMine)
+                    bump(bucketsMine, week, 'created');
+            }
+            const ownedMine = identity !== null && (record.owner ?? null) === identity;
+            bumpRemaining(bucketsAll, created, closed);
+            if (ownedMine)
+                bumpRemaining(bucketsMine, created, closed);
+        }
+    }
+    const toBuckets = (map) => weeks.map((slot, i) => ({
+        week: slot.week, end: weekEnds[i], ...(map.get(slot.week) ?? { done: 0, created: 0, remaining: 0 }),
+    }));
+    return { weekly: { all: toBuckets(bucketsAll), mine: toBuckets(bucketsMine) } };
+}
+/** 四个自然周期（只算「全部工作区」范围；图表切换不带动卡片）——纯函数。 */
+export function computeTrendPeriods(scopes, now) {
+    const windows = {
+        thisWeek: weekWindow(0, now),
+        lastWeek: weekWindow(-1, now),
+        thisMonth: monthWindow(0, now),
+        lastMonth: monthWindow(-1, now),
+    };
+    const doneEntries = scopes.flatMap((scope) => scope.history.map((record) => ({ day: dayOf(record.time), owner: record.owner ?? null })));
+    const createdEntries = scopes.flatMap((scope) => [
+        ...scope.tasks.map((task) => ({ day: dayOf(task.created), owner: task.owner ?? null })),
+        ...scope.history.map((record) => ({ day: dayOf(record.created), owner: record.owner ?? null })),
+    ]);
+    const period = (window) => ({
+        done: doneEntries.filter((entry) => inWindow(entry.day, window)).length,
+        created: createdEntries.filter((entry) => inWindow(entry.day, window)).length,
+        from: window.from,
+        to: window.to,
+    });
+    return {
+        thisWeek: period(windows.thisWeek),
+        lastWeek: period(windows.lastWeek),
+        thisMonth: period(windows.thisMonth),
+        lastMonth: period(windows.lastMonth),
+    };
+}
+/** 慢路径端点：趋势 + 周期（读 history）。异步加载，首屏不等。单工作区坏 ⇒ 进 degraded。 */
+export async function getTrend(workspaces) {
+    const now = new Date();
+    const { data: scopes, degraded } = await settleWorkspaces(workspaces, 'history', readTrendScope, (rows) => rows);
+    return { closed: computeClosedSummary(scopes, now), trend: computeTrendPeriods(scopes, now), degraded };
+}
+/** 趋势端点用的历史 filter（窗口由本模块策略决定，repository 零默认值注入）。 */
+export function trendHistoryFilter(extra = {}) {
+    return { months: RECENT_MONTHS, ...extra };
+}

package/dist/host/{skill-registration.js → skill/registration.js}

@@ -4,8 +4,9 @@
  */
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
-/** 内嵌 skill 目录：dist/host/skill-registration.js → 包根 skill/（copy-skill 产物）。 */
-const SKILL_DIR = fileURLToPath(new URL('../../skill', import.meta.url));
+/** 内嵌 skill 目录：dist/host/skill/registration.js → 包根 skill/（copy-skill 产物；
+ *  比原 host/skill-registration.js 深一层 ⇒ 相对路径多一级 `../`）。 */
+const SKILL_DIR = fileURLToPath(new URL('../../../skill', import.meta.url));
 /** SKILL.md 里指示脚本位置的占位符（注册时替换为绝对路径，模型据此找到脚本）。 */
 const SKILL_DIR_TOKEN = '<本 SKILL.md 所在目录>';
 /** frontmatter 最小解析：只取 name / description（不引 YAML 库；值去首尾引号）。 */