dsh-task-ledger 0.0.3 → 0.0.6

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` };
+}

package/dist/host/types.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 后端方法共享类型。
+ * 宿主能力（workspaceRegistry / webServer 等）的结构面在 index.ts 与 routes.ts 本地声明——
+ * 不 import 官方包（参考插件同款纪律：宿主 rc 接口会无声变，结构化声明 + external/ 文档坐标
+ * 比绑死官方类型更稳）。
+ */
+/** 一个活跃台账工作区：宿主 registry 条目 + 本地探测（ledger/progress.json 存在）。 */
+export interface LedgerWorkspace {
+    /** 宿主工作区 id。 */
+    readonly id: string;
+    /** 宿主 title（允许重名）。 */
+    readonly title: string;
+    /** canonical 绝对路径（宿主已 realpath 归一；skill 脚本 --repo 直传它）。 */
+    readonly path: string;
+}
+/** progress.json 任务对象的原始字段（skill 脚本 list --json 的值形状；缺字段按可选处理）。 */
+export interface TaskRecord {
+    title?: string;
+    status?: string;
+    creator?: string | null;
+    owner?: string | null;
+    created?: string | null;
+    started?: string | null;
+    finished?: string | null;
+    category?: string | null;
+    tags?: string[] | null;
+    worklog?: string | null;
+}
+/** 一条在办任务 = 原始字段 + 任务号 + 归属工作区（读取时打上）。 */
+export interface TaskRow extends TaskRecord {
+    readonly id: string;
+    readonly workspace: LedgerWorkspace;
+}
+/** history 一条已结案记录（脚本 history --json 的 record 形状；字段名以脚本为准）。 */
+export interface HistoryRecord {
+    /** 结案时间（首列）。 */
+    time?: string;
+    created?: string | null;
+    workpackage?: string;
+    category?: string | null;
+    tags?: string[] | null;
+    owner?: string;
+    /** 「完成了什么」列。 */
+    summary?: string;
+    /** 过程文档链接列。 */
+    log?: string | null;
+    /** 行所在历史文件（相对工作区，脚本打上）。 */
+    src?: string;
+    /** 归属工作区（读取时打上）。 */
+    readonly workspace?: LedgerWorkspace;
+}
+/** list / history 共用的过滤面（与 skill 脚本参数一一对应）。 */
+export interface LedgerFilter {
+    /** 状态（open/doing/blocked；history 侧忽略）。 */
+    status?: string;
+    owner?: string;
+    category?: string;
+    tag?: string;
+    /** 创建时间起 / 止（YYYY-MM-DD [HH:mm[:ss]]，脚本会补全）。 */
+    since?: string;
+    until?: string;
+    /** 列表分页大小（history 侧；script 的 --limit 在过滤 + 倒序后取前 N）。 */
+    limit?: number;
+    /** 只读最近 N 个月的历史文件（插件传 13；不传 = 脚本默认读全部）。 */
+    months?: number;
+}

package/dist/host/types.js

@@ -0,0 +1,7 @@
+/**
+ * 后端方法共享类型。
+ * 宿主能力（workspaceRegistry / webServer 等）的结构面在 index.ts 与 routes.ts 本地声明——
+ * 不 import 官方包（参考插件同款纪律：宿主 rc 接口会无声变，结构化声明 + external/ 文档坐标
+ * 比绑死官方类型更稳）。
+ */
+export {};

package/dist/host/workspace.d.ts

@@ -0,0 +1,13 @@
+import type { LedgerWorkspace } from './types.js';
+/** 宿主 workspaceRegistry.list() 条目的最小面（结构声明；事实与坐标见 external/dsh-workspace-registry.md）。 */
+export interface RegistryWorkspace {
+    readonly id: string;
+    readonly title: string;
+    readonly path: string;
+}
+/**
+ * 工作区发现：宿主 registry 全量 → 逐个查 <path>/ledger/progress.json，只返回有的。
+ * 未初始化（有 ledger/ 无 progress.json）= 隐藏，后端无此概念（2026-10-17 拍板）。
+ * 补充源（registry 未收录目录）暂不做——形态待拍板，见 architecture §五。
+ */
+export declare function resolveWorkspaces(registryList: readonly RegistryWorkspace[]): LedgerWorkspace[];

package/dist/host/workspace.js

@@ -0,0 +1,16 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+/**
+ * 工作区发现：宿主 registry 全量 → 逐个查 <path>/ledger/progress.json，只返回有的。
+ * 未初始化（有 ledger/ 无 progress.json）= 隐藏，后端无此概念（2026-10-17 拍板）。
+ * 补充源（registry 未收录目录）暂不做——形态待拍板，见 architecture §五。
+ */
+export function resolveWorkspaces(registryList) {
+    const found = [];
+    for (const workspace of registryList) {
+        if (existsSync(path.join(workspace.path, 'ledger', 'progress.json'))) {
+            found.push({ id: workspace.id, title: workspace.title, path: workspace.path });
+        }
+    }
+    return found;
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export declare const name = "dsh-task-ledger";
+/** 插件上下文的最小面（结构声明，不 import 官方包）。 */
+interface PluginContext {
+    inject(deps: readonly string[], callback: (ctx: Record<string, unknown>) => void): void;
+    /** 组合内副作用：进入时 setup、离开时执行返回的清理函数（cordis 核心面）。 */
+    effect(setup: () => (() => void) | undefined): void;
+}
+export declare function apply(ctx: PluginContext): void;
+export {};

package/dist/index.js

@@ -0,0 +1,42 @@
+/**
+ * dsh-task-ledger host 半入口：装配层，不写业务逻辑。
+ *
+ * 已落地：数据面路由（任务 3，routes.ts）、内嵌 skill 全局注册（任务 2，
+ * skill-registration.ts）。入口 / 图标 / 设置页（任务 1）与按钮会话交接
+ * （任务 4）各自落地时再往本文件加装配，业务逻辑一律进 host/ 对应文件。
+ *
+ * 服务等待写在 apply 内的 ctx.inject（参考插件真机教训：顶层 inject 声明组合
+ * 满足不了的依赖会令 entry 一直 pending、卡死整个 dsh 启动）；两条注入线
+ * 互相独立——skills 缺席不挡数据面，反之亦然。
+ */
+import { registerRoutes } from './host/routes.js';
+import { buildSkillRegistration } from './host/skill-registration.js';
+export const name = 'dsh-task-ledger';
+export function apply(ctx) {
+    // ── 数据面（任务 3） ──
+    ctx.inject(['workspaceRegistry', 'webServer'], (services) => {
+        const registry = services.workspaceRegistry;
+        const webServer = services.webServer;
+        if (registry === undefined || webServer === undefined) {
+            console.warn('[task-ledger] workspaceRegistry / webServer 未就位，数据面路由不注册');
+            return;
+        }
+        registerRoutes(webServer, { registry });
+        console.info('[task-ledger] 数据面路由已注册（/api/task-ledger/*）');
+    });
+    // ── skill 全局注册（任务 2） ──
+    // unscoped 注册落全局层，模型可 load；disposer 随插件 dispose 自动注销。
+    ctx.inject(['skills'], (services) => {
+        const skills = services.skills;
+        if (skills === undefined || typeof skills.register !== 'function') {
+            console.warn('[task-ledger] skills 服务未就位，内嵌 skill 不注册（数据面不受影响）');
+            return;
+        }
+        ctx.effect(() => {
+            const registration = buildSkillRegistration();
+            const dispose = skills.register(registration);
+            console.info(`[task-ledger] 已注册内嵌 skill：${registration.name}（正文 ${registration.content.length} 字）`);
+            return dispose;
+        });
+    });
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-task-ledger",
-  "version": "0.0.3",
-  "description": "Name reserved: upcoming dsh (DeepSeek Harness) plugin — task ledger board with the koc-ledger-progress skill bundled. First functional release in development.",
+  "version": "0.0.6",
+  "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",
     "harness",
@@ -10,12 +10,50 @@
     "task-ledger"
   ],
   "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "exports": {
+    ".": "./dist/index.js",
+    "./client": "./dist/client.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "skill",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "npm run build:host && npm run build:client",
+    "build:host": "tsc && node scripts/copy-skill.mjs",
+    "build:client": "tsc --noEmit -p tsconfig.client.json && tsdown --config tsdown.client.config.ts",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.client.json",
+    "smoke": "node scripts/smoke.mjs"
+  },
+  "engines": {
+    "node": ">=22.5"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.4",
+    "@types/react": "~18.3.1",
+    "tsdown": "^0.23.0",
+    "typescript": "^5.9.3"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/cq-guojia/dsh-task-ledger.git"
   },
-  "type": "module",
-  "files": [
-    "README.md"
-  ]
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-renderer",
+        "@deepseek-ai/dsh-client-ui-layout"
+      ]
+    }
+  }
 }