@danceiny/gotry 0.0.1-rc.9 → 0.2.0-rc.27

package/dist/capabilities/anything.js

@@ -1,93 +1,137 @@
-import { spawn } from 'node:child_process';
+/**
+ * Anything 通用搜索能力层:hbcli → hotel-be Anything 函数。
+ *
+ * 链路(同构 hbcli.ts):
+ *   gotry capabilities/anything.ts
+ *     → spawn hbcli --json search anything <kw> [opts]
+ *       → hotel-be /api/search/anything(httpdispatch 自动注册;httpdispatch 路由面)
+ *         → search/service/geography.go func Anything (mixed 城市+酒店搜索)
+ *
+ * wire 契约(2026-09-07 对齐上游源码;SearchItem = FuzzySearchItem + hotel):
+ *   req  { keyword, contentType?, context.destinationId?, minHotelCount? }
+ *   resp { candidates: [{ type: 'city'|'place'|'hotel',
+ *                         region?:  { id, name:{en,zh,ar}, coordinates:{centerLat,centerLng}, countryCode, … },
+ *                         place?:   { latlngCoordinator },
+ *                         matchScore?, hotel?: { id, name:{en,zh,ar}, star, latlngCoordinator:{google|gaode:{lat,lng} } } }] }
+ *
+ * 三值语义:
+ *   - hit:  命中候选(混合 city/hotel,maybe-coords)
+ *   - miss: hbcli exit 0,但 candidates 为空(查无结果)
+ *   - err:  hbcli exit ≠ 0 或超时(降级,降级产物 标 [实时API:hbcli-anything@error@ts])
+ *
+ * 契约(与 hbcli/weather/opensky 同构,L4 不变量):
+ *   - 永不抛错:网络/超时/解析失败一律降级返回;
+ *   - 证据链标注:成功 [实时API:hbcli-anything@ts];失败 [实时API:hbcli-anything@error@ts];
+ *   - 永不阻塞调用方:周边有 12s 默认超时,LLM 不等。
+ *
+ * 第 7 个能力层(与 hbcli.ts / weather.ts / opensky.ts 平级),data-sources.md §4
+ * Google Place 链路的「酒店-be 中间层」入口。
+ */
+import { hbcliBinCandidates } from './hbcli.js';
+import { spawnBounded } from './spawn-bounded.js';
+function i18nText(v) {
+    if (!v)
+        return '';
+    if (typeof v === 'string')
+        return v;
+    return v.zh || v.en || v.ar || '';
+}
+/** hotel-be Latlng:{lat,lng};google/gaode 双源取先非零者 */
+function latlngOf(coord) {
+    for (const src of [coord?.google, coord?.gaode]) {
+        const lat = typeof src?.lat === 'number' ? src.lat : undefined;
+        const lng = typeof src?.lng === 'number' ? src.lng : undefined;
+        if (lat !== undefined && lng !== undefined && (lat !== 0 || lng !== 0))
+            return { latitude: lat, longitude: lng };
+    }
+    return {};
+}
 function sh(cmd, args, opts) {
-    const ctrl = new AbortController();
-    const timer = setTimeout(()=>{
-        ctrl.abort();
-    }, opts.timeoutMs);
-    let child = null;
-    let killTimer = null;
-    return new Promise((resolve)=>{
-        child = spawn(cmd, args, {
-            env: opts.env,
-            cwd: process.cwd(),
-            signal: ctrl.signal
-        });
-        let stdout = '';
-        let stderr = '';
-        let error;
-        let killed = false;
-        child.stdout?.on('data', (d)=>{
-            stdout += d.toString();
-        });
-        child.stderr?.on('data', (d)=>{
-            stderr += d.toString();
-        });
-        child.on('error', (e)=>{
-            error = e.message.slice(0, 200);
-        });
-        child.on('close', (code)=>{
-            clearTimeout(timer);
-            if (killTimer) clearTimeout(killTimer);
-            resolve({
-                code: killed ? -2 : code ?? -1,
-                stdout,
-                stderr,
-                error
-            });
-        });
-        ctrl.signal.addEventListener('abort', ()=>{
-            if (!child) return;
-            try {
-                child.kill('SIGTERM');
-            } catch  {}
-            killTimer = setTimeout(()=>{
-                try {
-                    child?.kill('SIGKILL');
-                } catch  {}
-            }, 500);
-        });
-    });
+    return spawnBounded(cmd, args, { env: opts.env, cwd: process.cwd(), timeoutMs: opts.timeoutMs, signal: opts.signal });
+}
+/** --json 必须在子命令前(cli.ts 全局旗标预扫描只认子命令前位置;JSON 错误也走结构化 stderr) */
+function buildArgs(keyword, q) {
+    const args = ['--json', 'search', 'anything', keyword];
+    if (q.contentType)
+        args.push('--content-type', q.contentType);
+    if (q.parentDestinationId !== undefined)
+        args.push('--destination-id', String(q.parentDestinationId));
+    return args;
 }
-const upperFirst = (s)=>s ? s[0].toUpperCase() + s.slice(1) : s;
-const lowerFirst = (s)=>s ? s[0].toLowerCase() + s.slice(1) : s;
+/** 旧版 CLI 无 search anything 子命令时的可行动升级指引(issue #195:裸 unknown command 读起来像工具坏了) */
+function upgradeHint(stderr) {
+    return /unknown command/i.test(stderr)
+        ? 'hbcli 版本过旧(无 search anything 子命令)——请升级:hbcli update,或重跑 npx @danceiny/gotry setup'
+        : null;
+}
+/**
+ * 失败人话化(对齐 hbcli.ts 的 issue #24 口径)。
+ *
+ * 这条消息会直接渲染进用户回复(loop.ts 的 D-7a PoI 探针)并进入模型面,所以
+ * `(exit null)`、`spawn hbcli ENOENT` 这类进程噪音不能出现——hbcli 未装配是
+ * 可选实时源的降级设计行为,不是工具坏了;无法归类时也要说清发生了什么。
+ */
+function failureReason(r, cleanupError) {
+    const suffix = cleanupError ? `;${cleanupError}` : '';
+    if (/ENOENT/i.test(r.error ?? ''))
+        return `未安装 hbcli(可选实时源;npx @danceiny/gotry setup 可按官方脚本安装)${suffix}`;
+    if (r.timedOut)
+        return `hbcli 实时查询超时(本轮按降级处理)${suffix}`;
+    const detail = (r.stderr ?? '').trim().slice(0, 200);
+    if (detail)
+        return `hbcli 报错:${detail}${suffix}`;
+    return (r.code == null
+        ? 'hbcli 未返回可判定结果(进程异常结束,本轮按降级处理)'
+        : `hbcli 退出码 ${r.code},未返回可判定结果(本轮按降级处理)`) + suffix;
+}
+/** Anything 通用搜索 — 任何搜索失败走降级;不抛错 */
 export async function anythingSearch(q) {
     const started = Date.now();
     const ts = new Date().toISOString();
     const kw = (q.keyword ?? '').trim();
     if (!kw) {
         return {
-            ok: false,
-            via: 'hbcli-anything-error',
+            ok: false, via: 'hbcli-anything-error',
             evidence: `[实时API:hbcli-anything@error@${ts}] keyword empty`,
-            latencyMs: Date.now() - started,
-            verdict: 'error',
-            error: 'keyword is required'
+            latencyMs: Date.now() - started, verdict: 'error',
+            error: 'keyword is required',
         };
     }
-    const bin = q.hbcliBin ?? 'hbcli';
-    const args = [
-        bin,
-        'search',
-        'anything',
-        kw
-    ];
-    if (q.contentType) args.push('--content-type', q.contentType);
-    if (q.parentDestinationId !== undefined) {
-        args.push('--parent-destination-id', String(q.parentDestinationId));
+    const args = buildArgs(kw, q);
+    // spawn 级失败(ENOENT)按已知安装位回退(hbcli.ts callHbcliJson 同款);abort/超时/退码无重试无候选
+    const candidates = hbcliBinCandidates(q.hbcliBin ?? 'hbcli');
+    if (q.signal?.aborted) {
+        return {
+            ok: false, via: 'hbcli-anything-error',
+            evidence: `[实时API:hbcli-anything@abort@${ts}] pre-aborted, zero spawn`,
+            latencyMs: 0, verdict: 'error', error: 'aborted by host signal',
+        };
+    }
+    let r = { code: null, stdout: '', stderr: '', aborted: false, timedOut: false };
+    for (let i = 0; i < candidates.length; i++) {
+        r = await sh(candidates[i], args, { timeoutMs: q.timeoutMs ?? 12_000, env: process.env, signal: q.signal });
+        if (!(r.error && /ENOENT/.test(r.error) && !r.aborted && !r.timedOut && i < candidates.length - 1))
+            break;
     }
-    const r = await sh(bin, args.slice(1), {
-        timeoutMs: q.timeoutMs ?? 12_000,
-        env: process.env
-    });
     const latencyMs = Date.now() - started;
-    if (r.error || r.code !== 0) {
+    const cleanupError = r.groupReaped === false ? 'process group cleanup incomplete' : undefined;
+    if (r.aborted) {
+        return {
+            ok: false, via: 'hbcli-anything-error',
+            evidence: `[实时API:hbcli-anything@abort@${ts}]`,
+            latencyMs, verdict: 'error', error: ['aborted by host signal', cleanupError].filter(Boolean).join('; '),
+        };
+    }
+    if (r.error || r.groupReaped === false || r.code !== 0) {
+        const raw = [r.error, r.stderr.slice(0, 200), cleanupError].filter(Boolean).join('; ') || `(exit ${r.code})`;
         return {
             ok: false,
             via: 'hbcli-anything-error',
-            evidence: `[实时API:hbcli-anything@error@${ts}] ${r.error ?? `exit ${r.code}`}`,
+            // evidence 保留上游原话(溯源契约,anything-tests 锁);error 走人话面
+            evidence: `[实时API:hbcli-anything@${r.timedOut ? 'timeout' : 'error'}@${ts}] ${raw}`,
             latencyMs,
             verdict: 'error',
-            error: r.error ?? `${r.stderr.slice(0, 200)} (exit ${r.code})`
+            error: upgradeHint(r.stderr) ?? failureReason(r, cleanupError),
         };
     }
     let data;
@@ -95,45 +139,42 @@ export async function anythingSearch(q) {
         const jStart = r.stdout.indexOf('{') >= 0 ? r.stdout.indexOf('{') : r.stdout.indexOf('[');
         const json = jStart >= 0 ? r.stdout.slice(jStart) : r.stdout;
         data = JSON.parse(json);
-    } catch  {
+    }
+    catch {
         return {
-            ok: false,
-            via: 'hbcli-anything-error',
+            ok: false, via: 'hbcli-anything-error',
             evidence: `[实时API:hbcli-anything@error@${ts}] parse failed`,
             latencyMs,
             verdict: 'error',
-            error: 'failed to parse hbcli output as JSON'
+            error: 'failed to parse hbcli output as JSON',
         };
     }
     const rawItems = data.candidates ?? [];
-    const hits = rawItems.map((it)=>{
+    const hits = rawItems.map((it) => {
         const region = it.region ?? {};
         const hotel = it.hotel ?? {};
-        const isHotel = it.type === 'hotel' || it.type === 'SupplierHotelList' || Boolean(hotel.id);
+        const isHotel = it.type === 'hotel' || Boolean(hotel.id);
+        const hotelCoords = latlngOf(hotel.latlngCoordinator);
+        const placeCoords = latlngOf(it.place?.latlngCoordinator);
+        const center = region.coordinates ?? {};
         return {
-            type: isHotel ? 'hotel' : it.type === 'place' || it.type === 'City' ? lowerFirst(it.type) : 'city',
-            name: it.name ?? region.name_en ?? region.name ?? hotel.name ?? '?',
-            score: it.score ?? region.typeScore,
-            latitude: hotel.latitude ?? region.latitude,
-            longitude: hotel.longitude ?? region.longitude,
-            destinationId: region.id,
-            hotelId: hotel.id
+            type: (isHotel ? 'hotel' : (it.type === 'place' ? 'place' : 'city')),
+            name: i18nText(hotel.name) || i18nText(region.name) || '?',
+            score: it.matchScore,
+            latitude: hotelCoords.latitude ?? placeCoords.latitude ?? (typeof center.centerLat === 'number' ? center.centerLat : undefined),
+            longitude: hotelCoords.longitude ?? placeCoords.longitude ?? (typeof center.centerLng === 'number' ? center.centerLng : undefined),
+            destinationId: hotel.destinationId !== undefined ? String(hotel.destinationId) : (region.id !== undefined ? String(region.id) : undefined),
+            hotelId: hotel.id !== undefined ? String(hotel.id) : undefined,
+            star: typeof hotel.star === 'number' && hotel.star > 0 ? hotel.star : undefined,
         };
     });
     const verdict = hits.length > 0 ? 'hit' : 'miss';
     return {
-        ok: true,
-        via: 'hbcli-anything',
+        ok: true, via: 'hbcli-anything',
         evidence: `[实时API:hbcli-anything@${ts}] ${hits.length}/${rawItems.length} candidates`,
         latencyMs,
         verdict,
         hits,
-        totalCandidates: rawItems.length
+        totalCandidates: rawItems.length,
     };
 }
-export const _ = {
-    upperFirst
-};
-
-
-//# sourceURL=/Users/bytedance/work/gotry/ts/capabilities/anything.ts

package/dist/capabilities/artifacts.js

@@ -0,0 +1,370 @@
+/**
+ * 产物面(issue #25):agent 生成的文件不再只是「落在本地文件系统里的一个文件名」。
+ *
+ * 只读能力层,两个纯函数入口(dsh 工具 gotry_artifacts_list / gotry_artifacts_read 的实现):
+ *   - listArtifacts: 产物发现。权威源 = 账本 workflow_runs(ADR-15;无账本的旧 root 回退
+ *     扫描 gotry-state/async/*.deliverable.md 文件视图),外加 dsh 工作目录顶层 *.md
+ *     (agent 写出的行程/规划文件正落在这里——issue 截图里的 trip-2027-*.md 即此类)
+ *     与顶层 *.html/*.htm(issue #441:行程 HTML 产物需先能被发现)。
+ *     分页/搜索语义(issue #458):offset(零-based 非负整数)与 search(字面 case-insensitive
+ *     子串,匹配 id/title/filename,trim 后空串=不过滤)是先收集全部合格元数据 → 路径 dedupe →
+ *     搜索过滤 → updated DESC + (source,id,canonical path) 词典序 tie-break → 按
+ *     pageSize 切片的全局模型;pageSize 默认 20、上限 50;nextOffset 仅当
+ *     offset + returned < total;offset 越界返回空数组 + 准确 total + truncated:false +
+ *     无 nextOffset;total 反映已过滤集合的真实长度,不假装文件系统快照稳定。
+ *   - readArtifact: 产物阅读。行窗口(offset/limit)+ 原始行号,输出 dsh read 卡所需的
+ *     全部字段({number,text}[] / totalLines / lang),UI 侧渲染为行号文件视图。
+ *
+ * 纪律:本层只读(不写任何文件;WriteGate 红线不涉及);读取范围白名单 =
+ * stateRoot 根 + dsh 工作目录(排除 node_modules/.git),扩展名白名单 =
+ * 文本类(md/txt/json/jsonl/csv/log/yaml/yml/html/htm)——本工具是「产物查看」,
+ * 不是通用文件浏览器。HTML 在本层只作源码文本读取:不解析标记、不运行脚本/内联事件、
+ * 不发起抓取;列表项的主动打开走宿主原生 HTML 预览(客户端以 Open HTML preview 标注
+ * 并提示页面脚本可能运行,属宿主 renderer 行为),交互式 Lavish 本地编辑反馈归 #438/#443。
+ */
+import { createHash } from 'node:crypto';
+import { readdir, readFile, realpath, stat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { isAbsolute, join, resolve, sep } from 'node:path';
+import { openLedgerIfExists } from '../src/state-ledger.js';
+const MAX_LIST = 50;
+const DEFAULT_LIST = 20;
+const MAX_WINDOW = 400;
+const MAX_BYTES = 2 * 1024 * 1024;
+const TEXT_EXT_LANG = {
+    md: 'markdown', txt: 'text', json: 'json', jsonl: 'json', csv: 'csv', log: 'text', yaml: 'yaml', yml: 'yaml',
+    html: 'html', htm: 'html',
+};
+/** 工作目录顶层可发现的产物扩展名(大小写不敏感);html/htm 只作源码预览。 */
+const CWD_DISCOVER_EXT = /\.(md|html|htm)$/i;
+const DIR_DENY = ['node_modules', '.git'];
+/**
+ * Validate a nonnegative-integer pagination knob (`offset`). undefined defaults
+ * to 0; safe, integer, ≥0 numbers pass through; null / strings / nonfinite /
+ * noninteger / unsafe-integer (e.g. `Number.MAX_SAFE_INTEGER + 1`) values fail
+ * closed rather than being silently coerced. Safe-integer is the boundary that
+ * matters here: `Number.isInteger` would accept unsafe values whose arithmetic
+ * is no longer exact, and slicing into a sorted array with one is a real bug.
+ */
+function normalizeOffset(value, label) {
+    if (value === undefined)
+        return 0;
+    if (typeof value !== 'number' || !Number.isFinite(value) || !Number.isInteger(value) || value < 0) {
+        throw new Error(`${label} must be a nonnegative integer`);
+    }
+    if (!Number.isSafeInteger(value)) {
+        throw new Error(`${label} must be a safe integer (≤ Number.MAX_SAFE_INTEGER)`);
+    }
+    return value;
+}
+/**
+ * Validate and clamp a page-size knob (`limit`). Integer-shaped numbers
+ * (including zero / negative, to keep the pre-#458 clamp-on-1 contract) clamp
+ * to [1, MAX_LIST]; strings, nonfinite, and noninteger values fail closed
+ * without silent coercion. undefined defaults to DEFAULT_LIST.
+ */
+function clampLimit(value) {
+    if (value === undefined)
+        return DEFAULT_LIST;
+    if (typeof value !== 'number' || !Number.isFinite(value) || !Number.isInteger(value)) {
+        throw new Error(`limit must be a positive integer`);
+    }
+    return Math.max(1, Math.min(value, MAX_LIST));
+}
+/**
+ * Validate the optional `search` filter. Strings trim; empty / whitespace-only
+ * means no filter (already documented). Anything other than a string fails
+ * closed rather than passing through as a silent "no filter".
+ */
+function normalizeSearch(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string')
+        throw new Error(`search must be a string`);
+    const trimmed = value.trim();
+    return trimmed === '' ? undefined : trimmed;
+}
+function rootOf(stateRoot) {
+    return stateRoot === '.' ? process.cwd() : resolve(stateRoot);
+}
+function underRoot(p, root) {
+    const r = resolve(root);
+    return p === r || p.startsWith(r + sep);
+}
+function hasDeniedSegment(p) {
+    return p.split(sep).some(seg => DIR_DENY.includes(seg));
+}
+function asyncDeliverablePath(root, id) {
+    return join(root, 'gotry-state', 'async', `${id}.deliverable.md`);
+}
+/**
+ * Stable sort key for a list row. Order: `updated` DESC (ISO strings sort
+ * lexicographically), then `source` ASC, then `id` ASC, then canonical `path`
+ * ASC. The deterministic tie-break matters when many entries share an
+ * `updated` value (e.g. equal mtime): pagination would otherwise emit the
+ * same id on two adjacent pages. All comparisons are pure codepoint order
+ * (no `localeCompare`) so the order is stable across hosts/locales.
+ */
+function compareArtifacts(a, b) {
+    const updA = String(a.updated ?? '');
+    const updB = String(b.updated ?? '');
+    if (updA !== updB)
+        return updA < updB ? 1 : -1;
+    if (a.source !== b.source)
+        return a.source < b.source ? -1 : 1;
+    if (a.id !== b.id)
+        return a.id < b.id ? -1 : 1;
+    return a.path < b.path ? -1 : a.path > b.path ? 1 : 0;
+}
+function filenameOf(entry) {
+    const lastSep = entry.path.lastIndexOf(sep);
+    return lastSep >= 0 ? entry.path.slice(lastSep + 1) : entry.path;
+}
+/** Literal substring predicate (case-insensitive) over id/title/filename. */
+function matchesSearch(entry, needle) {
+    const lower = needle.toLowerCase();
+    return entry.id.toLowerCase().includes(lower)
+        || entry.title.toLowerCase().includes(lower)
+        || filenameOf(entry).toLowerCase().includes(lower);
+}
+/** 账本 workflow_runs 是权威(listWorkflowRuns 只读 SELECT 直查,不为一个视图改 ledger 类)。 */
+function listRunsFromLedger(root, tenant) {
+    const ledger = openLedgerIfExists(root, tenant);
+    if (!ledger)
+        return [];
+    const rows = ledger.db
+        .prepare('SELECT id, goal, status, deliverable, updated FROM workflow_runs WHERE tenant_id = ? ORDER BY updated DESC')
+        .all(ledger.tenant);
+    return rows.map(r => {
+        const file = asyncDeliverablePath(root, r.id);
+        return {
+            source: 'async-run',
+            id: r.id,
+            title: r.goal,
+            path: file,
+            status: r.status,
+            updated: r.updated,
+            bytes: r.deliverable?.length,
+        };
+    });
+}
+/** 无账本旧 root 的兼容视图:直接扫 async 目录的 deliverable 文件(只读,与清扫合同同一目录)。 */
+async function listDeliverableFiles(root) {
+    const dir = join(root, 'gotry-state', 'async');
+    let names = [];
+    try {
+        names = (await readdir(dir)).filter(n => n.endsWith('.deliverable.md'));
+    }
+    catch {
+        return [];
+    }
+    const entries = [];
+    for (const n of names) {
+        const p = join(dir, n);
+        const st = await stat(p).catch(() => null);
+        if (!st?.isFile())
+            continue;
+        const canonical = await realpath(p).catch(() => null);
+        if (!canonical || !underRoot(canonical, root) || hasDeniedSegment(canonical))
+            continue;
+        entries.push({
+            source: 'async-run',
+            id: n.replace(/\.deliverable\.md$/, ''),
+            title: n.replace(/\.deliverable\.md$/, ''),
+            path: p,
+            status: existsSync(p.replace(/\.deliverable\.md$/, '.json')) ? 'pending-view' : 'legacy',
+            updated: new Date(st.mtimeMs).toISOString(),
+            bytes: st.size,
+        });
+    }
+    return entries;
+}
+/**
+ * dsh 工作目录顶层可发现产物:md(agent 写出的行程规划等)+ html/htm 行程产物,
+ * 扩展名大小写不敏感;非递归,排除 dotfiles。每源在 dedupe/全局排序之前不限
+ * 数量——pageSize 由 listArtifacts 在排序后切片,避免 cwd 顶层 mtime 较老的
+ * 产物被提前丢失。
+ */
+async function listCwdArtifacts(cwd) {
+    let dirents;
+    try {
+        dirents = await readdir(cwd, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const entries = [];
+    for (const d of dirents) {
+        if (!d.isFile() || !CWD_DISCOVER_EXT.test(d.name) || d.name.startsWith('.'))
+            continue;
+        const p = join(cwd, d.name);
+        const st = await stat(p).catch(() => null);
+        if (!st)
+            continue;
+        const canonical = await realpath(p).catch(() => null);
+        if (!canonical || !underRoot(canonical, cwd) || hasDeniedSegment(canonical))
+            continue;
+        entries.push({
+            source: 'cwd-file',
+            id: d.name,
+            title: d.name.replace(CWD_DISCOVER_EXT, ''),
+            path: p,
+            updated: new Date(st.mtimeMs).toISOString(),
+            bytes: st.size,
+        });
+    }
+    return entries;
+}
+export async function listArtifacts(opts) {
+    const limit = clampLimit(opts.limit);
+    const offset = normalizeOffset(opts.offset, 'offset');
+    const needle = normalizeSearch(opts.search) ?? '';
+    const root = rootOf(opts.stateRoot);
+    const cwd = opts.cwd ? resolve(opts.cwd) : process.cwd();
+    const canonicalRoot = await realpath(root).catch(() => root);
+    const canonicalCwd = await realpath(cwd).catch(() => cwd);
+    // 1) collect all eligible entries per source, without per-source limits —
+    //    pageSize is applied to the merged/deduped/sorted set so older cwd files
+    //    stay reachable across pages.
+    const collected = [
+        ...listRunsFromLedger(canonicalRoot, 'local'),
+        ...(await listDeliverableFiles(canonicalRoot)),
+        ...(await listCwdArtifacts(canonicalCwd)),
+    ];
+    // 2) canonical-path dedupe (keep ledger authority when both sources point
+    //    at the same file).
+    const seenPath = new Set();
+    const deduped = [];
+    for (const e of collected) {
+        if (seenPath.has(e.path))
+            continue;
+        seenPath.add(e.path);
+        deduped.push(e);
+    }
+    // 3) literal, case-insensitive substring filter over id/title/filename.
+    const filtered = needle === '' ? deduped : deduped.filter(e => matchesSearch(e, needle));
+    // 4) deterministic global sort (updated DESC + lexical tie-break) so equal
+    //    mtimes have a stable page boundary.
+    filtered.sort(compareArtifacts);
+    // 5) page slice. offset may exceed total — return an empty page with the
+    //    known total and `truncated:false`.
+    const total = filtered.length;
+    const start = Math.min(offset, total);
+    const end = Math.min(start + limit, total);
+    const page = filtered.slice(start, end);
+    const hasMore = start + page.length < total;
+    const result = {
+        artifacts: page,
+        total,
+        truncated: hasMore,
+        limit,
+        /** Echo the requested offset (post-validation) — not the clamped page start — so the caller can detect a beyond-end request. */
+        offset,
+        roots: [canonicalRoot, canonicalCwd],
+    };
+    if (hasMore)
+        result.nextOffset = start + page.length;
+    if (needle !== '')
+        result.search = needle;
+    return result;
+}
+/**
+ * 读一个产物。path 三形态:
+ *   1. 裸工单 id(无 / 无 .)→ 账本 workflow_runs.deliverable(权威),文件视图缺失也能读;
+ *   2. list 返回的绝对/相对路径 → 限定在 stateRoot 根或 dsh 工作目录内(排除 node_modules/.git);
+ *   3. 相对文件名 → 先按 dsh 工作目录顶层,再按 gotry-state/async/ 找。
+ * 窗口:offset(1 起)/limit(≤400 行);超窗返回 windowed:true,UI 用 read 卡渲染行号视图。
+ */
+export async function readArtifact(opts) {
+    const root = rootOf(opts.stateRoot);
+    const cwd = opts.cwd ? resolve(opts.cwd) : process.cwd();
+    const canonicalRoot = await realpath(root).catch(() => root);
+    const canonicalCwd = await realpath(cwd).catch(() => cwd);
+    const raw = String(opts.path ?? '').trim();
+    if (!raw)
+        return { ok: false, error: 'path 必填(来自 gotry_artifacts_list 的 path,或异步工单 id)' };
+    let text = null;
+    let filePath = '';
+    // 1) 裸工单 id:账本权威读(文件视图缺失不挡阅读)
+    if (!raw.includes('/') && !raw.includes('\\') && !raw.includes('.')) {
+        const ledger = openLedgerIfExists(root, 'local');
+        const run = ledger?.db
+            .prepare('SELECT id, goal, status, deliverable FROM workflow_runs WHERE id = ? AND tenant_id = ?')
+            .get(raw, ledger.tenant);
+        if (run?.deliverable) {
+            text = run.deliverable;
+            filePath = asyncDeliverablePath(root, raw);
+        }
+        else {
+            const p = asyncDeliverablePath(root, raw);
+            const canonical = await realpath(p).catch(() => null);
+            if (canonical) {
+                if (!underRoot(canonical, canonicalRoot) || hasDeniedSegment(canonical)) {
+                    return { ok: false, error: `路径越界:${raw}`, hint: `只读 ${root} 与 dsh 工作目录内的文本产物` };
+                }
+                const ext = canonical.slice(canonical.lastIndexOf('.') + 1).toLowerCase();
+                if (!TEXT_EXT_LANG[ext]) {
+                    return { ok: false, error: `不支持的文件类型 .${ext}`, hint: `白名单:${Object.keys(TEXT_EXT_LANG).join('/')}` };
+                }
+                const st = await stat(canonical).catch(() => null);
+                if (!st?.isFile())
+                    return { ok: false, error: `文件不存在:${raw}`, hint: '先 gotry_artifacts_list 看在册产物' };
+                if (st.size > MAX_BYTES)
+                    return { ok: false, error: `文件过大(${st.size} bytes > ${MAX_BYTES})` };
+                filePath = canonical;
+                text = await readFile(canonical, 'utf-8');
+            }
+        }
+        if (text === null)
+            return { ok: false, error: `工单 ${raw} 无 deliverable(未交付或不存在)`, hint: '先 gotry_artifacts_list 看在册产物' };
+    }
+    // 2) 路径形态:目录白名单 + 扩展名白名单
+    if (text === null) {
+        const candidates = isAbsolute(raw) ? [resolve(raw)] : [resolve(cwd, raw), resolve(root, raw), resolve(root, 'gotry-state', 'async', raw)];
+        // 预检按 cwd/root 的非 canonical 与 canonical 两种形态放行:list 返回的是 canonical
+        // 路径(realpath 后的 cwd),而 macOS 上 /var 与 /private/var 这类符号链接会让
+        // canonical 路径不匹配字面 cwd,导致 list→read 串联断裂。边界权威仍是下方
+        // realpath 后的 canonical 复检,这里放宽不改变可读集合。
+        const inScope = (p) => (underRoot(p, cwd) || underRoot(p, root) || underRoot(p, canonicalCwd) || underRoot(p, canonicalRoot)) && !hasDeniedSegment(p);
+        // Prefer an existing candidate so a cwd miss does not mask a valid state-root file.
+        const allowed = candidates.find(p => inScope(p) && existsSync(p)) ?? candidates.find(inScope);
+        if (!allowed) {
+            return { ok: false, error: `路径越界:${raw}`, hint: `只读 ${root} 与 dsh 工作目录内的文本产物` };
+        }
+        const canonical = await realpath(allowed).catch(() => null);
+        if (!canonical) {
+            return { ok: false, error: `文件不存在:${raw}`, hint: '先 gotry_artifacts_list 看在册产物' };
+        }
+        if (!(underRoot(canonical, canonicalCwd) || underRoot(canonical, canonicalRoot)) || hasDeniedSegment(canonical)) {
+            return { ok: false, error: `路径越界:${raw}`, hint: `只读 ${root} 与 dsh 工作目录内的文本产物` };
+        }
+        const ext = canonical.slice(canonical.lastIndexOf('.') + 1).toLowerCase();
+        if (!TEXT_EXT_LANG[ext]) {
+            return { ok: false, error: `不支持的文件类型 .${ext}`, hint: `白名单:${Object.keys(TEXT_EXT_LANG).join('/')}` };
+        }
+        const st = await stat(canonical).catch(() => null);
+        if (!st?.isFile())
+            return { ok: false, error: `文件不存在:${raw}`, hint: '先 gotry_artifacts_list 看在册产物' };
+        if (st.size > MAX_BYTES)
+            return { ok: false, error: `文件过大(${st.size} bytes > ${MAX_BYTES})` };
+        filePath = canonical;
+        text = await readFile(canonical, 'utf-8');
+    }
+    const allLines = text.split('\n');
+    const offset = Math.max(1, Math.min(opts.offset ?? 1, allLines.length));
+    const limit = Math.max(1, Math.min(opts.limit ?? MAX_WINDOW, MAX_WINDOW));
+    const slice = allLines.slice(offset - 1, offset - 1 + limit);
+    const ext = filePath.slice(filePath.lastIndexOf('.') + 1).toLowerCase();
+    return {
+        ok: true,
+        source: underRoot(filePath, canonicalRoot) ? 'state-root' : 'cwd',
+        path: filePath,
+        offset,
+        lines: slice.map((t, i) => ({ number: offset + i, text: t })),
+        totalLines: allLines.length,
+        lang: TEXT_EXT_LANG[ext] ?? 'text',
+        version: createHash('sha256').update(text).digest('hex').slice(0, 12),
+        content: slice.join('\n'),
+        windowed: allLines.length > offset - 1 + slice.length,
+    };
+}