dsh-task-ledger 0.0.45 → 0.0.47

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/session.service.d.ts

@@ -0,0 +1,110 @@
+import type { LedgerWorkspace } from '../types.js';
+/** 模型路由：provider 与 model 必须成对。 */
+export interface ModelRoute {
+    readonly provider: string;
+    readonly model: string;
+}
+/** 会话首条 user 消息（`@deepseek-ai/dsh-llm` UserMessage 的最小同形面）。 */
+export interface UserMessageLike {
+    readonly id: string;
+    readonly role: 'user';
+    readonly content: readonly {
+        readonly type: 'text';
+        readonly text: string;
+    }[];
+    /**
+     * 生产者自有 kind（宿主 v4 格式要求；`kind: 'plugin'` 已废弃会被拒）。
+     * form/summary 给官方界面渲染成通知卡用。
+     */
+    readonly source: {
+        readonly kind: string;
+        readonly form: 'notice';
+        readonly summary: string;
+    };
+}
+/** `ctx.agents` 最小面（`CreateAgentOptions` 见 session-handoff 文档 §二）。 */
+export interface AgentsLike {
+    create(options: {
+        readonly sessionId: string;
+        readonly meta?: {
+            readonly cwd?: string;
+            readonly agentPreset?: string;
+        };
+        readonly agentOptions?: {
+            readonly provider?: string;
+            readonly model?: string;
+        };
+        readonly setup?: (agentCtx: unknown) => void | Promise<void>;
+    }): Promise<{
+        readonly agent: {
+            send(message: UserMessageLike, target: 'next-turn' | 'next-step', wakeup: boolean): void;
+        };
+    }>;
+}
+/** `ctx.agentPresets` 最小面：resolve 省略 id = 部署默认；mount 只在 setup 里调得到。 */
+export interface AgentPresetsLike {
+    resolve(id?: string): Promise<{
+        readonly id: string;
+    }>;
+    mount(agentCtx: unknown, id?: string): Promise<unknown>;
+}
+/** `ctx.agentDefaultModel` 最小面（部署默认模型）。 */
+export interface DefaultModelLike {
+    currentSelection(): ModelRoute;
+}
+/** 交接失败的原因码（路由层据此给状态码，文案在这里写成能直接上界面的）。 */
+export type HandoffErrorCode = 'no-agents' | 'no-preset' | 'no-model' | 'task-missing' | 'create-failed' | 'send-failed';
+export declare class HandoffError extends Error {
+    readonly code: HandoffErrorCode;
+    constructor(code: HandoffErrorCode, message: string);
+}
+/** 结束任务的预置提示词入参（纯数据，便于冒烟直接断言文案）。 */
+export interface ClosePromptInput {
+    readonly title: string;
+    readonly taskId: string;
+    /** 任务所在工作区绝对路径（`--repo` 就是它）。 */
+    readonly workspacePath: string;
+    /** 过程文档相对 `ledger/` 的路径；缺失传 null，提示词如实说「没有」。 */
+    readonly worklogPath: string | null;
+    /** 用户在弹框里留的话（可为空）。 */
+    readonly message: string;
+}
+/**
+ * 「结束任务」提示词（2026-10-18 用户口述定稿）。
+ *
+ * 结构照用户原话：**预置说明在前，用户留言放最末**（越靠后、越只讲一件事的段落遵守率越高 ——
+ * 参考插件真机结论）。三道硬约束缺一不可：
+ * ① 不要开新会话（用户：我要结束这个流程了，不能让模型再开一堆框）；
+ * ② 读过程文档后直接收尾（别再回头问，用户已经留言了）；
+ * ③ 写台账只经 skill 脚本（插件不手改文件，close 由模型执行）。
+ */
+export declare function buildClosePrompt(input: ClosePromptInput): string;
+/** 交接入参（路由层校验完协议字段后给）。 */
+export interface CloseHandoffRequest {
+    readonly workspace: LedgerWorkspace;
+    readonly taskId: string;
+    readonly message: string;
+    /** 用户选的模型；不给 = 用宿主默认。 */
+    readonly model?: ModelRoute;
+}
+export interface CloseHandoffResult {
+    readonly sessionId: string;
+    /** 非致命问题（如会话没能挂进工作区列表），如实回给调用方显示，不吞。 */
+    readonly warning?: string;
+}
+/** 依赖面（都是惰性服务，缺了给 503 人话，不硬崩）。 */
+export interface CloseHandoffDeps {
+    readonly agents: AgentsLike | undefined;
+    readonly presets: AgentPresetsLike | undefined;
+    readonly defaultModel: DefaultModelLike | undefined;
+}
+/**
+ * 起一个「结束任务」会话并发出首条提示词。
+ * 失败抛 {@link HandoffError}（带原因码）；成功返回 sessionId 供客户端 `openSession` 跳转。
+ */
+export declare function startCloseSession(deps: CloseHandoffDeps, request: CloseHandoffRequest): Promise<CloseHandoffResult>;
+/**
+ * 模型路由：用户选了就必须给全一对（只有一半 = 配错，直接人话拒绝）；
+ * 没选就走宿主部署默认。**没有兜底猜测**——猜一个模型去结案比报错更糟。
+ */
+export declare function resolveModelRoute(defaultModel: DefaultModelLike | undefined, explicit?: ModelRoute): ModelRoute;

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

@@ -0,0 +1,145 @@
+/**
+ * 会话交接（按钮侧方法层）：把一条任务交给模型去收尾。
+ *
+ * 事实（[`external/dsh-session-handoff.md`](../../../../docs/design/external/dsh-session-handoff.md)）：
+ * 浏览器半**没有**「往会话里发自由文本」的官方 API，唯一链路 = host `ctx.agents.create()` 自建会话
+ * + `agent.send()` 发预置提示词，客户端再 `openSession` 跳过去。
+ *
+ * 两条硬约束（都是参考插件真机踩出来的，不是猜的）：
+ * ① **必须带 preset**：`create` 里不 mount preset 的 agent 落到「空的全局层」——只剩根作用域的东西，
+ *    fs / bash 全无，模型连 `progress.py` 都跑不起来 ⇒ 这种会话建了等于白建。
+ * ② **provider + model 必须成对显式给**：缺省**不是**「走宿主默认路由」。用户没选模型时，
+ *    这里按宿主 `agentDefaultModel.currentSelection()` 取部署默认；取不到就报 503，不建半个会话。
+ *
+ * 本文件只管「结束任务」这一条（2026-10-18 用户拍板：认领 / 释放由 host 直写、不开会话；
+ * 结束要走会话，因为要带用户留言、要模型读过程文档后写摘要）。
+ */
+import { randomUUID } from 'node:crypto';
+import { getTask } from '../repositories/ledger.repository.js';
+import { SKILL_SCRIPT } from '../skill/registration.js';
+export class HandoffError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'HandoffError';
+    }
+}
+/**
+ * 「结束任务」提示词（2026-10-18 用户口述定稿）。
+ *
+ * 结构照用户原话：**预置说明在前，用户留言放最末**（越靠后、越只讲一件事的段落遵守率越高 ——
+ * 参考插件真机结论）。三道硬约束缺一不可：
+ * ① 不要开新会话（用户：我要结束这个流程了，不能让模型再开一堆框）；
+ * ② 读过程文档后直接收尾（别再回头问，用户已经留言了）；
+ * ③ 写台账只经 skill 脚本（插件不手改文件，close 由模型执行）。
+ */
+export function buildClosePrompt(input) {
+    const worklog = input.worklogPath === null || input.worklogPath === ''
+        ? '（这条任务没有登记过程文档）'
+        : `${input.workspacePath}/ledger/${input.worklogPath}`;
+    const message = input.message.trim() === '' ? '（用户没有留具体内容）' : input.message.trim();
+    return [
+        `用户从任务台账看板点了「结束」，要把任务「${input.title}」（任务号 ${input.taskId}）结案。`,
+        '',
+        `工作区：${input.workspacePath}`,
+        `过程文档：${worklog}`,
+        '',
+        '请按顺序做完这三件，然后停下：',
+        '1. 读过程文档的「背景 / 待办 / 下一步」，核对这次到底做了什么、还留了什么坑。',
+        `2. 用 task-ledger skill 的脚本结案（在工作区目录下、原样执行这一条命令）：`,
+        `   python3 ${SKILL_SCRIPT} close --id ${input.taskId} --repo ${input.workspacePath} --summary "<一句话说清做成了什么、留了什么坑>"`,
+        '   `--summary` 是必填参数，不许编套话；命令报错就原样报告错误，不要自己绕过、不要手改台账文件。',
+        '3. 收尾即结束——这就是本条消息的全部要求。',
+        '',
+        '【硬约束】',
+        '- 不要在会话里继续派活，**不要新建会话或子 agent**：这是收尾动作，不是新任务的开始。',
+        '- 用户已经明确要结束，不会再回答提问：信息不足就按留言与过程文档如实写进摘要/结论，**不要停下来反问**。',
+        '- 只动这一个任务，不顺带改别的记录；写台账只经上面那个 skill 脚本。',
+        '',
+        '用户现在处理结束，以下是用户的留言：',
+        message,
+    ].join('\n');
+}
+/**
+ * 起一个「结束任务」会话并发出首条提示词。
+ * 失败抛 {@link HandoffError}（带原因码）；成功返回 sessionId 供客户端 `openSession` 跳转。
+ */
+export async function startCloseSession(deps, request) {
+    const agents = deps.agents;
+    if (agents === undefined) {
+        throw new HandoffError('no-agents', '宿主未暴露 agents 服务，起不了会话（按钮交接暂不可用）');
+    }
+    const presets = deps.presets;
+    if (presets === undefined) {
+        throw new HandoffError('no-preset', '宿主未暴露 agentPresets 服务：起出来的会话没有 fs / bash 工具，模型跑不了 close');
+    }
+    const route = resolveModelRoute(deps.defaultModel, request.model);
+    // 任务此刻必须还在在办里（刚被别处结案 ⇒ 明确告知，不拿空标题去建会话）。
+    const task = await getTask(request.workspace, request.taskId);
+    if (task === null) {
+        throw new HandoffError('task-missing', `任务 ${request.taskId} 不在「${request.workspace.title}」的在办列表里（可能已被结案）`);
+    }
+    let presetId;
+    try {
+        presetId = (await presets.resolve()).id;
+    }
+    catch (error) {
+        throw new HandoffError('no-preset', `解析默认 preset 失败：${error instanceof Error ? error.message : String(error)}`);
+    }
+    const sessionId = randomUUID();
+    let handle;
+    try {
+        handle = await agents.create({
+            sessionId,
+            // cwd 必须是该工作区真实路径（会话 header 校验 + 工作区归组都按它判）。
+            meta: { cwd: request.workspace.path, agentPreset: presetId },
+            agentOptions: { provider: route.provider, model: route.model },
+            // setup 是发布前唯一能挂工具 / prompt sections / skill 的时机；抛错则整个作用域回滚。
+            setup: async (agentCtx) => { await presets.mount(agentCtx, presetId); },
+        });
+    }
+    catch (error) {
+        throw new HandoffError('create-failed', `会话没建起来（preset=${presetId}）：${error instanceof Error ? error.message : String(error)}`);
+    }
+    const prompt = buildClosePrompt({
+        title: task.title ?? request.taskId,
+        taskId: request.taskId,
+        workspacePath: request.workspace.path,
+        worklogPath: task.worklog ?? null,
+        message: request.message,
+    });
+    try {
+        handle.agent.send({
+            id: randomUUID(),
+            role: 'user',
+            content: [{ type: 'text', text: prompt }],
+            source: { kind: 'task-ledger', form: 'notice', summary: `结束任务 · ${task.title ?? request.taskId}` },
+        }, 'next-turn', true);
+    }
+    catch (error) {
+        throw new HandoffError('send-failed', `会话已建（${sessionId}）但首条消息没发出去：${error instanceof Error ? error.message : String(error)}`);
+    }
+    return { sessionId };
+}
+/**
+ * 模型路由：用户选了就必须给全一对（只有一半 = 配错，直接人话拒绝）；
+ * 没选就走宿主部署默认。**没有兜底猜测**——猜一个模型去结案比报错更糟。
+ */
+export function resolveModelRoute(defaultModel, explicit) {
+    if (explicit !== undefined) {
+        if (explicit.provider === '' || explicit.model === '') {
+            throw new HandoffError('no-model', 'provider 与 model 必须成对给出（只给一半会被拒，不做猜测）');
+        }
+        return explicit;
+    }
+    if (defaultModel !== undefined) {
+        try {
+            const route = defaultModel.currentSelection();
+            if (route.provider !== '' && route.model !== '')
+                return { provider: route.provider, model: route.model };
+        }
+        catch { /* 读不到就往下走，报同一句人话 */ }
+    }
+    throw new HandoffError('no-model', '宿主没有可用的默认模型：请在请求里给出 provider + model');
+}

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.d.ts → skill/registration.d.ts}

@@ -1,3 +1,5 @@
+/** skill 脚本绝对路径（提示词里直接给「原样执行这一条」的命令用；与注册共用同一份目录知识）。 */
+export declare const SKILL_SCRIPT: string;
 /** 宿主 ctx.skills.register 的最小面（外部事实文档的结构面）。 */
 export interface SkillRegistration {
     name: string;

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

@@ -4,10 +4,13 @@
  */
 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 所在目录>';
+/** skill 脚本绝对路径（提示词里直接给「原样执行这一条」的命令用；与注册共用同一份目录知识）。 */
+export const SKILL_SCRIPT = `${SKILL_DIR}/scripts/progress.py`;
 /** frontmatter 最小解析：只取 name / description（不引 YAML 库；值去首尾引号）。 */
 function parseFrontmatter(text) {
     const match = /^---\n([\s\S]*?)\n---/.exec(text);