@danceiny/gotry 0.0.1-rc.21 → 0.0.1-rc.24

package/dist/capabilities/artifacts.js

@@ -1,4 +1,19 @@
-import { readdir, readFile, stat } from 'node:fs/promises';
+/**
+ * 产物面(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 即此类)。
+ *   - readArtifact: 产物阅读。行窗口(offset/limit)+ 原始行号,输出 dsh read 卡所需的
+ *     全部字段({number,text}[] / totalLines / lang),UI 侧渲染为行号文件视图。
+ *
+ * 纪律:本层只读(不写任何文件;WriteGate 红线不涉及);读取范围白名单 =
+ * stateRoot 根 + dsh 工作目录(排除 node_modules/.git),扩展名白名单 =
+ * 文本类(md/txt/json/jsonl/csv/log/yaml/yml)——本工具是「产物查看」,不是通用文件浏览器。
+ */
+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';
@@ -6,19 +21,9 @@ const MAX_LIST = 50;
 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'
+    md: 'markdown', txt: 'text', json: 'json', jsonl: 'json', csv: 'csv', log: 'text', yaml: 'yaml', yml: 'yaml',
 };
-const DIR_DENY = [
-    'node_modules',
-    '.git'
-];
+const DIR_DENY = ['node_modules', '.git'];
 function rootOf(stateRoot) {
     return stateRoot === '.' ? process.cwd() : resolve(stateRoot);
 }
@@ -27,16 +32,20 @@ function underRoot(p, root) {
     return p === r || p.startsWith(r + sep);
 }
 function hasDeniedSegment(p) {
-    return p.split(sep).some((seg)=>DIR_DENY.includes(seg));
+    return p.split(sep).some(seg => DIR_DENY.includes(seg));
 }
 function asyncDeliverablePath(root, id) {
     return join(root, 'gotry-state', 'async', `${id}.deliverable.md`);
 }
+/** 账本 workflow_runs 是权威(listWorkflowRuns 只读 SELECT 直查,不为一个视图改 ledger 类)。 */
 function listRunsFromLedger(root, tenant, limit) {
     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 LIMIT ?').all(ledger.tenant, limit);
-    return rows.map((r)=>{
+    if (!ledger)
+        return [];
+    const rows = ledger.db
+        .prepare('SELECT id, goal, status, deliverable, updated FROM workflow_runs WHERE tenant_id = ? ORDER BY updated DESC LIMIT ?')
+        .all(ledger.tenant, limit);
+    return rows.map(r => {
         const file = asyncDeliverablePath(root, r.id);
         return {
             source: 'async-run',
@@ -45,23 +54,29 @@ function listRunsFromLedger(root, tenant, limit) {
             path: file,
             status: r.status,
             updated: r.updated,
-            bytes: r.deliverable?.length
+            bytes: r.deliverable?.length,
         };
     });
 }
+/** 无账本旧 root 的兼容视图:直接扫 async 目录的 deliverable 文件(只读,与清扫合同同一目录)。 */
 async function listDeliverableFiles(root, limit) {
     const dir = join(root, 'gotry-state', 'async');
     let names = [];
     try {
-        names = (await readdir(dir)).filter((n)=>n.endsWith('.deliverable.md'));
-    } catch  {
+        names = (await readdir(dir)).filter(n => n.endsWith('.deliverable.md'));
+    }
+    catch {
         return [];
     }
     const entries = [];
-    for (const n of names.slice(0, limit * 2)){
+    for (const n of names.slice(0, limit * 2)) {
         const p = join(dir, n);
-        const st = await stat(p).catch(()=>null);
-        if (!st?.isFile()) continue;
+        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$/, ''),
@@ -69,129 +84,137 @@ async function listDeliverableFiles(root, limit) {
             path: p,
             status: existsSync(p.replace(/\.deliverable\.md$/, '.json')) ? 'pending-view' : 'legacy',
             updated: new Date(st.mtimeMs).toISOString(),
-            bytes: st.size
+            bytes: st.size,
         });
     }
-    return entries.sort((a, b)=>String(b.updated).localeCompare(String(a.updated)));
+    return entries.sort((a, b) => String(b.updated).localeCompare(String(a.updated)));
 }
+/** dsh 工作目录顶层 *.md(agent 写出的行程规划等);非递归,排除 dotfiles。 */
 async function listCwdMarkdown(cwd, limit) {
     let dirents;
     try {
-        dirents = await readdir(cwd, {
-            withFileTypes: true
-        });
-    } catch  {
+        dirents = await readdir(cwd, { withFileTypes: true });
+    }
+    catch {
         return [];
     }
     const entries = [];
-    for (const d of dirents){
-        if (!d.isFile() || !/\.md$/i.test(d.name) || d.name.startsWith('.')) continue;
+    for (const d of dirents) {
+        if (!d.isFile() || !/\.md$/i.test(d.name) || d.name.startsWith('.'))
+            continue;
         const p = join(cwd, d.name);
-        const st = await stat(p).catch(()=>null);
-        if (!st) continue;
+        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(/\.md$/i, ''),
             path: p,
             updated: new Date(st.mtimeMs).toISOString(),
-            bytes: st.size
+            bytes: st.size,
         });
     }
-    return entries.sort((a, b)=>String(b.updated).localeCompare(String(a.updated))).slice(0, limit);
+    return entries.sort((a, b) => String(b.updated).localeCompare(String(a.updated))).slice(0, limit);
 }
 export async function listArtifacts(opts) {
     const limit = Math.max(1, Math.min(opts.limit ?? 20, MAX_LIST));
     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 seenPath = new Set();
     const merged = [];
-    for (const e of [
-        ...listRunsFromLedger(root, 'local', limit),
-        ...await listDeliverableFiles(root, limit),
-        ...await listCwdMarkdown(cwd, limit)
-    ]){
-        if (seenPath.has(e.path)) continue;
+    for (const e of [...listRunsFromLedger(canonicalRoot, 'local', limit), ...(await listDeliverableFiles(canonicalRoot, limit)), ...(await listCwdMarkdown(canonicalCwd, limit))]) {
+        if (seenPath.has(e.path))
+            continue;
         seenPath.add(e.path);
         merged.push(e);
     }
-    merged.sort((a, b)=>String(b.updated ?? '').localeCompare(String(a.updated ?? '')));
+    merged.sort((a, b) => String(b.updated ?? '').localeCompare(String(a.updated ?? '')));
     const total = merged.length;
-    return {
-        artifacts: merged.slice(0, limit),
-        total,
-        truncated: total > limit,
-        roots: [
-            root,
-            cwd
-        ]
-    };
+    return { artifacts: merged.slice(0, limit), total, truncated: total > limit, roots: [canonicalRoot, canonicalCwd] };
 }
+/**
+ * 读一个产物。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)'
-    };
+    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);
+        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 {
+        }
+        else {
             const p = asyncDeliverablePath(root, raw);
-            if (existsSync(p)) {
-                filePath = p;
-                text = await readFile(p, 'utf-8');
+            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 看在册产物'
-        };
+        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)
-        ];
-        const allowed = candidates.find((p)=>(underRoot(p, cwd) || underRoot(p, root)) && !hasDeniedSegment(p));
+        const candidates = isAbsolute(raw) ? [resolve(raw)] : [resolve(cwd, raw), resolve(root, raw), resolve(root, 'gotry-state', 'async', raw)];
+        const inScope = (p) => (underRoot(p, cwd) || underRoot(p, root)) && !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 工作目录内的文本产物`
-            };
+            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 看在册产物' };
         }
-        const ext = allowed.slice(allowed.lastIndexOf('.') + 1).toLowerCase();
+        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('/')}`
-            };
+            return { ok: false, error: `不支持的文件类型 .${ext}`, hint: `白名单:${Object.keys(TEXT_EXT_LANG).join('/')}` };
         }
-        const st = await stat(allowed).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 = allowed;
-        text = await readFile(allowed, 'utf-8');
+        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));
@@ -200,18 +223,14 @@ export async function readArtifact(opts) {
     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
-            })),
+        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
+        windowed: allLines.length > offset - 1 + slice.length,
     };
 }
-
-
-//# sourceURL=ts/capabilities/artifacts.ts

package/dist/capabilities/channel-health.js

@@ -1,51 +1,65 @@
+/**
+ * 通道健康面(channel health)——issue #106/#107/#108 编排设计
+ * (docs/design/tool-orchestration-design.md §2.2)的会话瞬态态 + 持久事件面。
+ *
+ * 两个粒度,均从既有 verdict 流派生,不新增运行时:
+ *  - 会话瞬态面:进程内 Map。检索通道 verdict≠hit 时记状态
+ *    (down=本会话别再试 / cooldown=节律闸冷却中),后续同意图工具结果的
+ *    routing 建议(channel-registry.routingAdvice)据此排除不可用通道;
+ *    成功调用(hit)自动清除——补装 key/装完扩展后不被陈旧状态锁死。
+ *    与断路器同先例(ADR-18):进程内瞬态,不是持久资产。
+ *  - 持久事件面:down/cooldown 事件 append-only 落
+ *    <stateRoot>/gotry-state/channel-health.jsonl,供 doctor(CLI 独立进程,
+ *    看不到进程内 Map)显示「最近一次达限/不可用时间」。只记状态变化,
+ *    不记成功(零写放大);落盘失败不阻塞检索主路径(事实侧车同纪律)。
+ *
+ * verdict → 状态映射的唯一入口是 noteChannelVerdict:
+ *   needs-setup → down(quota-or-setup)   challenged → down(challenged)
+ *   needs-login / needs-extension → down(同因,会话内改道;hit 即清除)
+ *   cooldown → cooldown(默认 30s,会话节律闸同款)
+ *   hit → 清除该通道全部状态
+ *   其余 verdict(miss/error 等)不改变通道状态——那是业务结果,不是通道健康。
+ *
+ * @module capabilities/channel-health
+ */
+/** 会话瞬态面(进程内;与断路器状态同生命周期先例) */
 const session = new Map();
+/** 默认 cooldown = 会话节律闸同款 30s */
 export const DEFAULT_COOLDOWN_MS = 30_000;
 export function markChannelDown(channel, reason, now = Date.now()) {
-    session.set(channel, {
-        state: 'down',
-        reason,
-        since: now
-    });
-    return {
-        channel,
-        state: 'down',
-        reason,
-        at: new Date(now).toISOString()
-    };
+    session.set(channel, { state: 'down', reason, since: now });
+    return { channel, state: 'down', reason, at: new Date(now).toISOString() };
 }
 export function markChannelCooldown(channel, cooldownMs = DEFAULT_COOLDOWN_MS, now = Date.now()) {
-    session.set(channel, {
-        state: 'cooldown',
-        until: now + cooldownMs,
-        since: now
-    });
-    return {
-        channel,
-        state: 'cooldown',
-        at: new Date(now).toISOString()
-    };
+    session.set(channel, { state: 'cooldown', until: now + cooldownMs, since: now });
+    return { channel, state: 'cooldown', at: new Date(now).toISOString() };
 }
+/** 成功即清除(恢复信号:下一次成功调用自动解锁,不要求显式复位) */
 export function clearChannel(channel) {
     session.delete(channel);
 }
+/** 读通道状态;cooldown 过期惰性清除。无状态返回 undefined。 */
 export function channelState(channel, now = Date.now()) {
     const e = session.get(channel);
-    if (!e) return undefined;
+    if (!e)
+        return undefined;
     if (e.state === 'cooldown' && (e.until ?? 0) <= now) {
         session.delete(channel);
         return undefined;
     }
-    return {
-        state: e.state,
-        reason: e.reason
-    };
+    return { state: e.state, reason: e.reason };
 }
+/** 测试隔离:清空全部会话态(生产路径不调) */
 export function resetChannelHealth() {
     session.clear();
 }
+/**
+ * verdict → 通道状态变化的唯一映射(工具层在拿到渠道结果后调用)。
+ * 返回落盘事件(down/cooldown 才有;hit 清除与其余 verdict 返回 undefined)。
+ */
 export function noteChannelVerdict(channel, verdict, opts = {}) {
     const now = opts.now ?? Date.now();
-    switch(verdict){
+    switch (verdict) {
         case 'hit':
         case 'found':
             clearChannel(channel);
@@ -62,16 +76,23 @@ export function noteChannelVerdict(channel, verdict, opts = {}) {
             return undefined;
     }
 }
+/** 持久事件面:append-only JSONL(<stateRoot>/gotry-state/channel-health.jsonl)。永不抛错。 */
 export async function recordChannelEvent(stateRoot, event) {
     try {
         const { mkdir, appendFile } = await import('node:fs/promises');
         const dir = `${stateRoot.replace(/\/+$/, '')}/gotry-state`;
-        await mkdir(dir, {
-            recursive: true
-        });
+        await mkdir(dir, { recursive: true });
         await appendFile(`${dir}/channel-health.jsonl`, `${JSON.stringify(event)}\n`, 'utf-8');
-    } catch  {}
+    }
+    catch { /* 证据侧车永不阻塞主路径 */ }
 }
+/**
+ * 读最近事件(每通道取最新一条)——doctor(CLI 独立进程)的持久面输入。
+ * 容忍坏行/空文件/缺文件;limitDays 过滤过旧事件(默认 30 天)。
+ * latest-wins:'ok' 恢复事件可超越同通道更早的 down/cooldown(外部事件接缝
+ * 第 1 段);消费方以 `state !== 'down'` 判当前健康,旧判定(`=== 'down'`)
+ * 不受影响。
+ */
 export async function readLatestChannelEvents(stateRoot, opts = {}) {
     const latest = new Map();
     try {
@@ -79,25 +100,24 @@ export async function readLatestChannelEvents(stateRoot, opts = {}) {
         const raw = await readFile(`${stateRoot.replace(/\/+$/, '')}/gotry-state/channel-health.jsonl`, 'utf-8');
         const nowMs = opts.now ?? Date.now();
         const cutoff = nowMs - (opts.limitDays ?? 30) * 86_400_000;
-        for (const line of raw.split('\n')){
+        for (const line of raw.split('\n')) {
             const t = line.trim();
-            if (!t) continue;
+            if (!t)
+                continue;
             try {
                 const ev = JSON.parse(t);
-                if (!ev || typeof ev.channel !== 'string' || typeof ev.state !== 'string') continue;
-                if (![
-                    'down',
-                    'cooldown',
-                    'ok'
-                ].includes(ev.state)) continue;
+                if (!ev || typeof ev.channel !== 'string' || typeof ev.state !== 'string')
+                    continue;
+                if (!['down', 'cooldown', 'ok'].includes(ev.state))
+                    continue;
                 const atMs = Date.parse(ev.at ?? '');
-                if (Number.isFinite(atMs) && atMs < cutoff) continue;
+                if (Number.isFinite(atMs) && atMs < cutoff)
+                    continue;
                 latest.set(ev.channel, ev);
-            } catch  {}
+            }
+            catch { /* 坏行跳过 */ }
         }
-    } catch  {}
+    }
+    catch { /* 无文件=无事件 */ }
     return latest;
 }
-
-
-//# sourceURL=ts/capabilities/channel-health.ts