dsh-task-ledger 0.0.1 → 0.0.5

package/README.md

@@ -3,6 +3,6 @@
 Name reserved for an upcoming [DeepSeek Harness](https://www.npmjs.com/package/@deepseek-ai/dsh) (dsh) plugin:
 
 - a **task ledger board** UI (per-workspace todos, history by owner, reports)
-- the **koc-ledger-progress** skill bundled for global agent use
+- the **task-ledger** skill bundled for global agent use
 
 First functional release in development.

package/cordis.patch.yml

@@ -0,0 +1,6 @@
+# bundle 补丁：把本 npm 包作为插件插入宿主组合（顶层 YAML 数组，条目 = loader patch 项）。
+# 参考 dsh-task-dispatch-table/cordis.patch.yml 同款格式。
+- insert:
+    - id: dsh-task-ledger
+      name: dsh-task-ledger
+      config: {}

package/dist/host/board.d.ts

@@ -0,0 +1,54 @@
+import type { HistoryRecord, LedgerFilter, LedgerWorkspace, TaskRow } from './types.js';
+/** 已结案列表默认分页大小（「加载更多」= 调用方加大 limit 重取）。 */
+export declare const DEFAULT_HISTORY_LIMIT = 500;
+/** 首页统计卡的两个完成类计数。 */
+export interface ClosedCounts {
+    /** 本周已完成（最近 2 个月文件内、创建时间落在本周）。 */
+    readonly weekDone: number;
+    /** 近一年完成（最近 13 个月文件行数；capped = 已触顶，值即下限）。 */
+    readonly yearDone: number;
+    readonly yearCapped: boolean;
+}
+export interface BoardSnapshot {
+    readonly at: string;
+    readonly workspaces: readonly LedgerWorkspace[];
+    /** 全部在办任务（UI 自己筛「我的 / 待认领」——筛选是前端的事）。 */
+    readonly tasks: readonly TaskRow[];
+    readonly stats: {
+        readonly myActive: number;
+        readonly open: number;
+    };
+}
+/**
+ * 当前 git 身份（cwd = 该工作区）——「我的待办」判定源。
+ * 与 agent 在会话里跑 skill 时的取值环境一致；取不到回 null（非 git 目录 / 没配身份），
+ * 该工作区的「我的」统计按 0 计（不谎报）。
+ */
+export declare function getCurrentIdentity(workspace: LedgerWorkspace): Promise<string | null>;
+/**
+ * 首页快照（在办路径）：并发跑全部工作区的 list + 身份解析。
+ * 与历史量彻底无关——progress.json 只装没结案的任务（close 会移走），永远有界。
+ */
+export declare function getBoardSnapshot(workspaces: readonly LedgerWorkspace[]): Promise<BoardSnapshot>;
+/**
+ * 完成类统计（数行封顶，与总量脱钩）：本周 = 最近 2 个月文件 + 创建时间落在本周；
+ * 近一年 = 最近 13 个月文件行数。任一工作区失败即抛（聚合数部分失败 = 错数，不兜）。
+ */
+export declare function getClosedCounts(workspaces: readonly LedgerWorkspace[]): Promise<ClosedCounts>;
+/**
+ * 已结案列表：默认近 13 个月 + limit 500，跨工作区合并后按创建时间倒序。
+ * shortcut: 分页用「加大 limit 重取」的笨办法（skill 脚本无 offset）；
+ * 单工作区内 limit 已生效，合并边界的全局精确排序暂不保证（500 条一页无感）。
+ * 要全量老数据：调用方显式传 months: undefined（不拼 --months，脚本读全部，按秒计）。
+ */
+export declare function queryClosed(workspaces: readonly LedgerWorkspace[], filter?: LedgerFilter): Promise<HistoryRecord[]>;
+export interface FilterOptions {
+    readonly owners: string[];
+    readonly categories: string[];
+    readonly tags: string[];
+}
+/**
+ * 筛选项候选：在办（全量）+ 近 13 个月历史的去重值（owner / category / tag）。
+ * 按需调用（/filters 路由），非首屏——历史侧在极端量级下是百毫秒级。
+ */
+export declare function getFilterOptions(workspaces: readonly LedgerWorkspace[]): Promise<FilterOptions>;

package/dist/host/board.js

@@ -0,0 +1,125 @@
+import { spawn } from 'node:child_process';
+import { readHistory, readTasks } from './ledger-read.js';
+import { runLedgerScript } from './script.js';
+/** 历史窗口：只读最近 13 个月的文件（2026-10-17 拍板；脚本默认读全部，窗口由插件显式传）。 */
+const RECENT_MONTHS = 13;
+/** 已结案列表默认分页大小（「加载更多」= 调用方加大 limit 重取）。 */
+export const DEFAULT_HISTORY_LIMIT = 500;
+/** 完成类统计的封顶值：超出显示「1万+」（2026-10-17 拍板，显示级封顶，精确值走搜索）。 */
+const COUNT_CAP = 10_000;
+/** 周一所在日期（YYYY-MM-DD）。skill 的 --since 只给日期按当天 00:00 解析。 */
+function mondayDateString(now) {
+    const date = new Date(now);
+    const mondayOffset = (date.getDay() + 6) % 7;
+    date.setDate(date.getDate() - mondayOffset);
+    const pad = (value) => String(value).padStart(2, '0');
+    return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+}
+/**
+ * 当前 git 身份（cwd = 该工作区）——「我的待办」判定源。
+ * 与 agent 在会话里跑 skill 时的取值环境一致；取不到回 null（非 git 目录 / 没配身份），
+ * 该工作区的「我的」统计按 0 计（不谎报）。
+ */
+export function getCurrentIdentity(workspace) {
+    return new Promise((resolve) => {
+        const child = spawn('git', ['config', 'user.name'], { cwd: workspace.path, stdio: ['ignore', 'pipe', 'ignore'] });
+        let stdout = '';
+        child.stdout.on('data', (chunk) => { stdout += chunk.toString(); });
+        child.on('error', () => { resolve(null); });
+        child.on('close', (code) => {
+            const name = stdout.trim();
+            resolve(code === 0 && name !== '' ? name : null);
+        });
+    });
+}
+/**
+ * 首页快照（在办路径）：并发跑全部工作区的 list + 身份解析。
+ * 与历史量彻底无关——progress.json 只装没结案的任务（close 会移走），永远有界。
+ */
+export async function getBoardSnapshot(workspaces) {
+    const perWorkspace = await Promise.all(workspaces.map(async (workspace) => ({
+        workspace,
+        tasks: await readTasks(workspace),
+        identity: await getCurrentIdentity(workspace),
+    })));
+    const tasks = perWorkspace.flatMap((entry) => entry.tasks);
+    const myActive = perWorkspace.reduce((sum, entry) => sum + entry.tasks.filter((task) => task.owner === entry.identity && (task.status === 'doing' || task.status === 'blocked')).length, 0);
+    const open = tasks.filter((task) => task.status === 'open').length;
+    return { at: new Date().toISOString(), workspaces, tasks, stats: { myActive, open } };
+}
+/**
+ * 完成类统计（数行封顶，与总量脱钩）：本周 = 最近 2 个月文件 + 创建时间落在本周；
+ * 近一年 = 最近 13 个月文件行数。任一工作区失败即抛（聚合数部分失败 = 错数，不兜）。
+ */
+export async function getClosedCounts(workspaces) {
+    const monday = mondayDateString(new Date());
+    const perWorkspace = await Promise.all(workspaces.map(async (workspace) => {
+        const [week, year] = await Promise.all([
+            runLedgerScript('history', ['--repo', workspace.path, '--json', '--count-only', '--months', '2', '--since', monday]),
+            runLedgerScript('history', ['--repo', workspace.path, '--json', '--count-only', '--months', String(RECENT_MONTHS)]),
+        ]);
+        if (!week.ok)
+            throw new Error(`${workspace.title}: ${week.error}`);
+        if (!year.ok)
+            throw new Error(`${workspace.title}: ${year.error}`);
+        return { week: week.data.count ?? 0, year: year.data.count ?? 0, yearCapped: year.data.capped === true };
+    }));
+    const yearCapped = perWorkspace.some((entry) => entry.yearCapped);
+    return {
+        weekDone: perWorkspace.reduce((sum, entry) => sum + entry.week, 0),
+        yearDone: yearCapped ? COUNT_CAP : perWorkspace.reduce((sum, entry) => sum + entry.year, 0),
+        yearCapped,
+    };
+}
+/**
+ * 已结案列表：默认近 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 perWorkspace = await Promise.all(workspaces.map((workspace) => readHistory(workspace, windowed)));
+    return perWorkspace.flat()
+        .sort((a, b) => String(b.created ?? b.time ?? '').localeCompare(String(a.created ?? a.time ?? '')))
+        .slice(0, filter.limit ?? DEFAULT_HISTORY_LIMIT);
+}
+/**
+ * 筛选项候选：在办（全量）+ 近 13 个月历史的去重值（owner / category / tag）。
+ * 按需调用（/filters 路由），非首屏——历史侧在极端量级下是百毫秒级。
+ */
+export async function getFilterOptions(workspaces) {
+    const perWorkspace = await Promise.all(workspaces.map(async (workspace) => ({
+        tasks: await readTasks(workspace),
+        history: await readHistory(workspace, { months: RECENT_MONTHS }),
+    })));
+    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 entry of perWorkspace) {
+        for (const task of entry.tasks)
+            addTask(task);
+        for (const record of entry.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) };
+}

package/dist/host/ledger-read.d.ts

@@ -0,0 +1,20 @@
+import type { HistoryRecord, LedgerFilter, LedgerWorkspace, TaskRow } from './types.js';
+/**
+ * LedgerFilter → skill 脚本参数（只拼调用方给了的；undefined 一律不拼，
+ * 让脚本走自己的默认——插件不替脚本决定默认值）。
+ */
+export declare function filterArgs(filter: LedgerFilter): string[];
+/**
+ * 在办任务（包 `list --json`；结果打上 workspace）。
+ * 脚本失败抛错——路由层转 500 + 人话，不静默返空（空 = 撒谎）。
+ */
+export declare function readTasks(workspace: LedgerWorkspace, filter?: LedgerFilter): Promise<TaskRow[]>;
+/** 已结案记录（包 `history --json`；结果打上 workspace）。 */
+export declare function readHistory(workspace: LedgerWorkspace, filter?: LedgerFilter): Promise<HistoryRecord[]>;
+/** 单条在办（展开行 / 详情用）。取不到回 null，不抛。 */
+export declare function getTask(workspace: LedgerWorkspace, taskId: string): Promise<TaskRow | null>;
+/**
+ * 过程文档正文（`task.worklog` 相对 `ledger/` 的路径）。
+ * 读不到回 null（文件被清 / 路径坏都不炸——由调用方展示「过程文档缺失」）。
+ */
+export declare function readWorklog(workspace: LedgerWorkspace, task: TaskRow): Promise<string | null>;

package/dist/host/ledger-read.js

@@ -0,0 +1,64 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { runLedgerScript } from './script.js';
+/**
+ * LedgerFilter → skill 脚本参数（只拼调用方给了的；undefined 一律不拼，
+ * 让脚本走自己的默认——插件不替脚本决定默认值）。
+ */
+export function filterArgs(filter) {
+    const args = [];
+    if (filter.status !== undefined)
+        args.push('--status', filter.status);
+    if (filter.owner !== undefined)
+        args.push('--owner', filter.owner);
+    if (filter.category !== undefined)
+        args.push('--category', filter.category);
+    if (filter.tag !== undefined)
+        args.push('--tag', filter.tag);
+    if (filter.since !== undefined)
+        args.push('--since', filter.since);
+    if (filter.until !== undefined)
+        args.push('--until', filter.until);
+    if (filter.limit !== undefined)
+        args.push('--limit', String(filter.limit));
+    if (filter.months !== undefined)
+        args.push('--months', String(filter.months));
+    return args;
+}
+/**
+ * 在办任务（包 `list --json`；结果打上 workspace）。
+ * 脚本失败抛错——路由层转 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 }));
+}
+/** 已结案记录（包 `history --json`；结果打上 workspace）。 */
+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 }));
+}
+/** 单条在办（展开行 / 详情用）。取不到回 null，不抛。 */
+export async function getTask(workspace, taskId) {
+    const rows = await readTasks(workspace);
+    return rows.find((row) => row.id === taskId) ?? null;
+}
+/**
+ * 过程文档正文（`task.worklog` 相对 `ledger/` 的路径）。
+ * 读不到回 null（文件被清 / 路径坏都不炸——由调用方展示「过程文档缺失」）。
+ */
+export async function readWorklog(workspace, task) {
+    const relative = task.worklog;
+    if (relative === undefined || relative === null || relative === '')
+        return null;
+    try {
+        return await readFile(path.join(workspace.path, 'ledger', relative), 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}

package/dist/host/routes.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 数据面路由薄壳：只做协议（参数解析 + JSON 响应 + 错误转 500），
+ * 一行业务逻辑都不多写——全部调 board / ledger-read 的方法（2026-10-17 定稿）。
+ * 宿主事实（handler = 原始 Node req/res、发头后不抛错、重复 path 注册直接 throw）
+ * 见 external/host-webserver.md。
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { type RegistryWorkspace } from './workspace.js';
+/** 宿主 webServer.register 的最小面（WebRoute 形状见 external/host-webserver.md）。 */
+export interface WebServerLike {
+    register(route: {
+        kind: 'exact' | 'prefix';
+        path: string;
+        handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>;
+    }): unknown;
+}
+/** 宿主 workspaceRegistry 的最小面（事实见 external/dsh-workspace-registry.md）。 */
+export interface WorkspaceRegistryLike {
+    list(): readonly RegistryWorkspace[];
+}
+export interface RouteDeps {
+    readonly registry: WorkspaceRegistryLike;
+}
+export declare function registerRoutes(webServer: WebServerLike, deps: RouteDeps): void;

package/dist/host/routes.js

@@ -0,0 +1,140 @@
+import { getBoardSnapshot, getClosedCounts, getFilterOptions, queryClosed } from './board.js';
+import { getTask, readTasks, readWorklog } from './ledger-read.js';
+import { resolveWorkspaces } from './workspace.js';
+/** API 前缀（唯一真源就在这一处）。 */
+const API_PREFIX = '/api/task-ledger';
+function sendJson(res, status, body) {
+    res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
+    res.end(JSON.stringify(body));
+}
+/** URL query → LedgerFilter（只认白名单键；limit/months 非正数忽略）。 */
+function filterFromQuery(url) {
+    const filter = {};
+    const str = (key) => {
+        const value = url.searchParams.get(key);
+        return value !== null && value !== '' ? value : null;
+    };
+    const int = (key) => {
+        const raw = str(key);
+        if (raw === null)
+            return undefined;
+        const value = Number.parseInt(raw, 10);
+        return Number.isFinite(value) && value > 0 ? value : undefined;
+    };
+    const status = str('status');
+    if (status !== null)
+        filter.status = status;
+    const owner = str('owner');
+    if (owner !== null)
+        filter.owner = owner;
+    const category = str('category');
+    if (category !== null)
+        filter.category = category;
+    const tag = str('tag');
+    if (tag !== null)
+        filter.tag = tag;
+    const since = str('since');
+    if (since !== null)
+        filter.since = since;
+    const until = str('until');
+    if (until !== null)
+        filter.until = until;
+    const limit = int('limit');
+    if (limit !== undefined)
+        filter.limit = limit;
+    const months = int('months');
+    if (months !== undefined)
+        filter.months = months;
+    return filter;
+}
+/** 每请求重新解析工作区（registry 可能刚变；existsSync × N 是微秒级，不缓存）。 */
+function workspacesOf(deps) {
+    return resolveWorkspaces(deps.registry.list());
+}
+export function registerRoutes(webServer, deps) {
+    webServer.register({
+        kind: 'exact',
+        path: `${API_PREFIX}/workspaces`,
+        handler: (_req, res) => { sendJson(res, 200, { workspaces: workspacesOf(deps) }); },
+    });
+    // 首页一次拿全：在办快照 + 两个完成类统计。
+    webServer.register({
+        kind: 'exact',
+        path: `${API_PREFIX}/board`,
+        handler: async (_req, res) => {
+            try {
+                const workspaces = workspacesOf(deps);
+                const [snapshot, closed] = await Promise.all([getBoardSnapshot(workspaces), getClosedCounts(workspaces)]);
+                sendJson(res, 200, { ...snapshot, closed });
+            }
+            catch (error) {
+                sendJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
+            }
+        },
+    });
+    webServer.register({
+        kind: 'exact',
+        path: `${API_PREFIX}/tasks`,
+        handler: async (req, res) => {
+            try {
+                const filter = filterFromQuery(new URL(req.url ?? '/', 'http://localhost'));
+                const perWorkspace = await Promise.all(workspacesOf(deps).map((workspace) => readTasks(workspace, filter)));
+                sendJson(res, 200, { tasks: perWorkspace.flat() });
+            }
+            catch (error) {
+                sendJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
+            }
+        },
+    });
+    // 任务详情 + 过程文档正文（query 传 ws/id，不做路径段解析——任务号含中文和连字符）。
+    webServer.register({
+        kind: 'exact',
+        path: `${API_PREFIX}/task`,
+        handler: async (req, res) => {
+            try {
+                const url = new URL(req.url ?? '/', 'http://localhost');
+                const workspace = workspacesOf(deps).find((item) => item.id === url.searchParams.get('ws'));
+                const taskId = url.searchParams.get('id');
+                if (workspace === undefined || taskId === null) {
+                    sendJson(res, 400, { error: '缺少 ws / id 参数' });
+                    return;
+                }
+                const task = await getTask(workspace, taskId);
+                if (task === null) {
+                    sendJson(res, 404, { error: '任务不存在' });
+                    return;
+                }
+                sendJson(res, 200, { task, worklog: await readWorklog(workspace, task) });
+            }
+            catch (error) {
+                sendJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
+            }
+        },
+    });
+    webServer.register({
+        kind: 'exact',
+        path: `${API_PREFIX}/history`,
+        handler: async (req, res) => {
+            try {
+                const filter = filterFromQuery(new URL(req.url ?? '/', 'http://localhost'));
+                sendJson(res, 200, { records: await queryClosed(workspacesOf(deps), filter) });
+            }
+            catch (error) {
+                sendJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
+            }
+        },
+    });
+    webServer.register({
+        kind: 'exact',
+        path: `${API_PREFIX}/filters`,
+        handler: async (_req, res) => {
+            try {
+                sendJson(res, 200, await getFilterOptions(workspacesOf(deps)));
+            }
+            catch (error) {
+                sendJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
+            }
+        },
+    });
+    // POST /sessions（按钮会话交接）归「任务按钮与会话交接」任务——写入路径 A/B 拍板后再接。
+}

package/dist/host/script.d.ts

@@ -0,0 +1,23 @@
+export type LedgerScriptResult<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * 全插件唯一碰 Python 的地方：spawn python3 跑内嵌 skill 脚本，收 stdout JSON。
+ * 不解析任何台账格式——解析真源只有 skill 脚本一份（2026-10-17 用户拍板）。
+ *
+ * 出错一律归一为 { ok:false, error }（人话，直接可上界面）：
+ * 起不了 python3 / 超时（kill）/ 非零退出（stderr 原文）/ 输出不是 JSON。
+ *
+ * @param sub - 子命令（list / history / show…）
+ * @param args - 参数数组，由调用方自拼（含 --repo / --json / --months 等）
+ * @param opts.scriptPath - 测试用：覆盖脚本路径
+ * @param opts.timeoutMs - 覆盖超时
+ */
+export declare function runLedgerScript<T = unknown>(sub: string, args: readonly string[], opts?: {
+    scriptPath?: string;
+    timeoutMs?: number;
+}): Promise<LedgerScriptResult<T>>;

package/dist/host/script.js

@@ -0,0 +1,59 @@
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+/**
+ * 内嵌 skill 脚本的默认路径：dist/host/script.js → 包根 skill/scripts/progress.py。
+ * 构建时 scripts/copy-skill.mjs 把 packages/skill 拷到 packages/plugin/skill/。
+ */
+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;
+/**
+ * 全插件唯一碰 Python 的地方：spawn python3 跑内嵌 skill 脚本，收 stdout JSON。
+ * 不解析任何台账格式——解析真源只有 skill 脚本一份（2026-10-17 用户拍板）。
+ *
+ * 出错一律归一为 { ok:false, error }（人话，直接可上界面）：
+ * 起不了 python3 / 超时（kill）/ 非零退出（stderr 原文）/ 输出不是 JSON。
+ *
+ * @param sub - 子命令（list / history / show…）
+ * @param args - 参数数组，由调用方自拼（含 --repo / --json / --months 等）
+ * @param opts.scriptPath - 测试用：覆盖脚本路径
+ * @param opts.timeoutMs - 覆盖超时
+ */
+export function runLedgerScript(sub, args, opts) {
+    const scriptPath = opts?.scriptPath ?? DEFAULT_SCRIPT_PATH;
+    const timeoutMs = opts?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    return new Promise((resolve) => {
+        const child = spawn('python3', [scriptPath, sub, ...args], { stdio: ['ignore', 'pipe', 'pipe'] });
+        let stdout = '';
+        let stderr = '';
+        let settled = false;
+        const timer = setTimeout(() => {
+            child.kill();
+            settle({ ok: false, error: `skill 脚本超时（>${timeoutMs}ms）：${sub} ${args.join(' ')}` });
+        }, timeoutMs);
+        const settle = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(result);
+        };
+        child.stdout.on('data', (chunk) => { stdout += chunk.toString(); });
+        child.stderr.on('data', (chunk) => { stderr += chunk.toString(); });
+        child.on('error', (error) => {
+            settle({ ok: false, error: `起不了 python3（${error.message}）——本插件需要 python3 运行内嵌 skill 脚本` });
+        });
+        child.on('close', (code) => {
+            if (code !== 0) {
+                settle({ ok: false, error: stderr.trim() || `skill 脚本退出码 ${String(code)}` });
+                return;
+            }
+            try {
+                settle({ ok: true, data: JSON.parse(stdout) });
+            }
+            catch {
+                settle({ ok: false, error: `skill 脚本输出不是 JSON：${stdout.slice(0, 200)}` });
+            }
+        });
+    });
+}

package/dist/host/skill-registration.d.ts

@@ -0,0 +1,27 @@
+/** 宿主 ctx.skills.register 的最小面（外部事实文档的结构面）。 */
+export interface SkillRegistration {
+    name: string;
+    description: string;
+    content: string;
+    whenToUse?: string;
+    path?: string;
+    source?: string;
+    resourceBase?: {
+        kind: 'directory';
+        path: string;
+    };
+    metadata?: Record<string, unknown>;
+}
+/** 宿主 skills 服务的最小面。 */
+export interface SkillsRegistry {
+    register(skill: SkillRegistration): () => void;
+}
+/**
+ * 组装注册体：读内嵌 SKILL.md → 取 name / description → 正文里的脚本路径占位符
+ * 替换为绝对路径。
+ *
+ * 相对资源解析的二选一（external/dsh-skill-registration.md §三）**未拍板**；
+ * 最小闭环选「插值绝对路径」——resourceBase 的消费者呈现未验证，不押注。
+ * 拍板后如改走 resourceBase，只动本函数，调用方无感。
+ */
+export declare function buildSkillRegistration(skillDir?: string): SkillRegistration;

package/dist/host/skill-registration.js

@@ -0,0 +1,43 @@
+/**
+ * 内嵌 skill 的注册体组装（任务 2「skill 注册最小闭环」）。
+ * 宿主事实（0.2.0-rc.2 npm pack 亲验）：external/dsh-skill-registration.md。
+ */
+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.md 里指示脚本位置的占位符（注册时替换为绝对路径，模型据此找到脚本）。 */
+const SKILL_DIR_TOKEN = '<本 SKILL.md 所在目录>';
+/** frontmatter 最小解析：只取 name / description（不引 YAML 库；值去首尾引号）。 */
+function parseFrontmatter(text) {
+    const match = /^---\n([\s\S]*?)\n---/.exec(text);
+    if (match === null)
+        throw new Error('SKILL.md 缺 frontmatter（--- 包裹的头）');
+    const field = (key) => {
+        const line = (match[1] ?? '').split('\n').find((item) => item.startsWith(`${key}:`));
+        if (line === undefined)
+            throw new Error(`SKILL.md frontmatter 缺 ${key}`);
+        return line.slice(key.length + 1).trim().replace(/^["']|["']$/g, '');
+    };
+    return { name: field('name'), description: field('description') };
+}
+/**
+ * 组装注册体：读内嵌 SKILL.md → 取 name / description → 正文里的脚本路径占位符
+ * 替换为绝对路径。
+ *
+ * 相对资源解析的二选一（external/dsh-skill-registration.md §三）**未拍板**；
+ * 最小闭环选「插值绝对路径」——resourceBase 的消费者呈现未验证，不押注。
+ * 拍板后如改走 resourceBase，只动本函数，调用方无感。
+ */
+export function buildSkillRegistration(skillDir = SKILL_DIR) {
+    const text = readFileSync(`${skillDir}/SKILL.md`, 'utf-8');
+    const { name, description } = parseFrontmatter(text);
+    const content = text.split(SKILL_DIR_TOKEN).join(skillDir);
+    if (content.includes(SKILL_DIR_TOKEN)) {
+        throw new Error('占位符替换失败：SKILL.md 里仍残留脚本路径占位符');
+    }
+    if (!content.includes(`${skillDir}/scripts/progress.py`)) {
+        throw new Error('占位符替换异常：替换后找不到脚本路径');
+    }
+    return { name, description, content, path: `${skillDir}/SKILL.md` };
+}