@danceiny/gotry 0.0.1-rc.14 → 0.0.1-rc.15

package/dist/src/booking-saga.js

@@ -0,0 +1,153 @@
+export const BOOKING_SAGA_SCHEMA = 'booking_saga_fsm.v1';
+export const SAGA_STATUSES = [
+    'pending',
+    'confirmed',
+    'compensated'
+];
+export const SAGA_EDGES = [
+    {
+        from: 'none',
+        trigger: 'propose',
+        to: 'pending',
+        event: 'write.pending',
+        guard: 'L2 只登记不执行;idem_key UNIQUE(重复提议 no-op)'
+    },
+    {
+        from: 'pending',
+        trigger: 'confirm',
+        to: 'confirmed',
+        event: 'write.confirmed',
+        guard: 'L3 具名 seam 确认,必携 receipt;已确认不可再确认'
+    },
+    {
+        from: 'pending',
+        trigger: 'compensate',
+        to: 'compensated',
+        event: 'write.compensated',
+        guard: '外部写未发生,取消即终态(无补偿动作)'
+    },
+    {
+        from: 'confirmed',
+        trigger: 'compensate',
+        to: 'compensated',
+        event: 'write.compensated',
+        guard: '已发生副作用的 saga 补偿(退改),receipt 保留(COALESCE)'
+    }
+];
+export const SAGA_REJECTIONS = [
+    {
+        from: 'none',
+        trigger: 'confirm',
+        reason: 'missing-subject'
+    },
+    {
+        from: 'none',
+        trigger: 'compensate',
+        reason: 'missing-subject'
+    },
+    {
+        from: 'pending',
+        trigger: 'propose',
+        reason: 'idem-exists'
+    },
+    {
+        from: 'confirmed',
+        trigger: 'propose',
+        reason: 'idem-exists'
+    },
+    {
+        from: 'confirmed',
+        trigger: 'confirm',
+        reason: 'already-confirmed'
+    },
+    {
+        from: 'compensated',
+        trigger: 'propose',
+        reason: 'idem-exists'
+    },
+    {
+        from: 'compensated',
+        trigger: 'confirm',
+        reason: 'absorbed-compensated'
+    },
+    {
+        from: 'compensated',
+        trigger: 'compensate',
+        reason: 'already-compensated'
+    }
+];
+export function resolveSagaTrigger(origin, trigger) {
+    const edge = SAGA_EDGES.find((e)=>e.from === origin && e.trigger === trigger);
+    if (edge) return {
+        ok: true,
+        from: origin,
+        trigger,
+        to: edge.to,
+        event: edge.event,
+        guard: edge.guard,
+        reason: null
+    };
+    const rejection = SAGA_REJECTIONS.find((e)=>e.from === origin && e.trigger === trigger);
+    return {
+        ok: false,
+        from: origin,
+        trigger,
+        to: null,
+        event: null,
+        guard: null,
+        reason: rejection.reason
+    };
+}
+export const SAGA_TRIGGER_EVENT = {
+    propose: 'write.pending',
+    confirm: 'write.confirmed',
+    compensate: 'write.compensated'
+};
+export function triggerOfEventKind(kind) {
+    if (kind === 'write.pending') return 'propose';
+    if (kind === 'write.confirmed') return 'confirm';
+    if (kind === 'write.compensated') return 'compensate';
+    return null;
+}
+export function sagaTraceViolations(events) {
+    const violations = [];
+    let stage = 'none';
+    for (const ev of events){
+        const trigger = triggerOfEventKind(ev.kind);
+        if (!trigger) continue;
+        const verdict = resolveSagaTrigger(stage, trigger);
+        const at = `seq=${ev.seq ?? '?'} ${ev.kind}`;
+        if (!verdict.ok) {
+            violations.push(`${at}: 非法(${stage} --${trigger}--> 拒绝 ${verdict.reason})`);
+            continue;
+        }
+        stage = verdict.to;
+        if (trigger === 'confirm' && (ev.receipt === undefined || ev.receipt === null || ev.receipt === '')) {
+            violations.push(`${at}: receipt 为空(L3 具名确认必携外部回执)`);
+        }
+    }
+    return violations;
+}
+export function sagaLegalPaths() {
+    return [
+        [
+            'propose'
+        ],
+        [
+            'propose',
+            'compensate'
+        ],
+        [
+            'propose',
+            'confirm'
+        ],
+        [
+            'propose',
+            'confirm',
+            'compensate'
+        ]
+    ];
+}
+
+
+//# sourceURL=/Users/bytedance/work/gotry/ts/src/booking-saga.ts

package/dist/src/dsh-llm.js

@@ -3,7 +3,17 @@ import { buildTimeAnchor } from './time-anchor.js';
 import { buildSlotSystem, flagExpiredSlots, normalizeExtraction } from './travel-slots.js';
 const model = ()=>process.env['LLM_MODEL'] ?? process.env['DEEPSEEK_MODEL'] ?? 'MiniMax-M2';
 const base = ()=>(process.env['LLM_BASE_URL'] ?? process.env['DEEPSEEK_BASE_URL'] ?? 'https://api.minimax.io/v1').replace(/\/$/, '');
-async function chat(messages, json) {
+function emptyUsage() {
+    return {
+        calls: 0,
+        inputTokens: 0,
+        outputTokens: 0,
+        inputCacheHitTokens: 0,
+        inputCacheMissTokens: 0,
+        responsesMissingUsage: 0
+    };
+}
+async function chat(messages, json, usage) {
     const key = process.env['LLM_API_KEY'] ?? process.env['DEEPSEEK_API_KEY'];
     if (!key) throw new Error('LLM_API_KEY 未设置(兼容 DEEPSEEK_API_KEY 别名)——真 LLM 路径不可用,请回退 mock(ADR-8)');
     const res = await fetch(`${base()}/chat/completions`, {
@@ -25,6 +35,18 @@ async function chat(messages, json) {
     });
     if (!res.ok) throw new Error(`llm ${res.status}: ${(await res.text()).slice(0, 300)}`);
     const data = await res.json();
+    if (usage) {
+        usage.calls += 1;
+        const u = data.usage;
+        if (u && Number.isFinite(u.prompt_tokens) && Number.isFinite(u.completion_tokens)) {
+            usage.inputTokens += u.prompt_tokens ?? 0;
+            usage.outputTokens += u.completion_tokens ?? 0;
+            usage.inputCacheHitTokens += u.prompt_cache_hit_tokens ?? 0;
+            usage.inputCacheMissTokens += u.prompt_cache_miss_tokens ?? u.prompt_tokens ?? 0;
+        } else {
+            usage.responsesMissingUsage += 1;
+        }
+    }
     const raw = data.choices[0]?.message?.content ?? '';
     return raw.replace(/<think>[\s\S]*?<\/think>/g, '').trim() || raw;
 }
@@ -50,6 +72,7 @@ const SKELETON_SYSTEM = `你是行程骨架抽取器。从对话中抽取行程
 scenario 判定:「洱海/大理/千岛湖/太湖+选目的地」→erhai(候选集);「普吉/workation/远程办公+多城链」→workation(五段链);「云南/大理丽江」→yunnan;不确定→generic。只输出 JSON。`;
 export function createOpenAICompatLlm(flightPackPath, clock = ()=>new Date()) {
     const pack = flightPackPath;
+    const usage = emptyUsage();
     const historyText = (h)=>h.map((t)=>`${t.role === 'user' ? '用户' : '助手'}: ${t.text}`).join('\n');
     const anchorContext = ()=>`时间锚点卡:\n${buildTimeAnchor(clock()).card}`;
     return {
@@ -63,7 +86,7 @@ export function createOpenAICompatLlm(flightPackPath, clock = ()=>new Date()) {
                     role: 'user',
                     content: `${anchorContext()}\n\n${historyText(history)}`
                 }
-            ], true);
+            ], true, usage);
             const obj = parseJsonBlock(out);
             if (!obj) return {
                 assumptions: []
@@ -91,7 +114,7 @@ export function createOpenAICompatLlm(flightPackPath, clock = ()=>new Date()) {
                     role: 'user',
                     content: `${context}\n\n${historyText(history)}`
                 }
-            ], true);
+            ], true, usage);
             const skeleton = parseJsonBlock(out);
             if (!skeleton || !Array.isArray(skeleton['segments']) || skeleton['segments'].length === 0) return null;
             if (!pack) return null;
@@ -148,7 +171,7 @@ export function createOpenAICompatLlm(flightPackPath, clock = ()=>new Date()) {
                     role: 'user',
                     content: historyText(history)
                 }
-            ], true);
+            ], true, usage);
             const obj = parseJsonBlock(out);
             if (!obj) return null;
             const ext = normalizeExtraction(obj, history.map((t)=>t.text).join('\n'));
@@ -164,9 +187,10 @@ export function createOpenAICompatLlm(flightPackPath, clock = ()=>new Date()) {
                     role: 'user',
                     content: `【${q.key}】${q.text}(为什么问:${q.why})`
                 }
-            ], false);
+            ], false, usage);
             return out.trim() || `【${q.key}】${q.text}`;
-        }
+        },
+        usage
     };
 }
 

package/dist/src/index.js

@@ -23,6 +23,7 @@ import { flyaiSearch } from '../capabilities/flyai.js';
 import { sessionFlightSearch } from '../capabilities/session-search.js';
 import { sessionLogin } from '../capabilities/session-login.js';
 import { createConsentGate, approvalFromContext } from '../capabilities/session-consent.js';
+import { listArtifacts, readArtifact } from '../capabilities/artifacts.js';
 export const name = 'gotry-tools';
 export const inject = [
     'tools',
@@ -1357,6 +1358,138 @@ export function apply(ctx, config) {
             };
         }
     }));
+    registerGuarded(defineTool({
+        name: 'gotry_artifacts_list',
+        description: 'List GoTry artifacts — deep-planning deliverables (async runs from the state ledger) plus agent-written markdown files ' + 'in the working directory (trip plans etc.). READ-ONLY discovery. ' + 'Use when the user asks to see/open/revisit a previously generated artifact ' + '(「看看刚才生成的行程」「上次的规划在哪」「打开那个 md」) — list first, then read with gotry_artifacts_read.',
+        parameters: {
+            query: {
+                type: 'json',
+                required: true,
+                description: '{ limit?: 20 }'
+            }
+        },
+        output: {
+            schema: {
+                type: 'json'
+            },
+            render: (_args, value)=>[
+                    {
+                        type: 'text',
+                        text: String(value.summary ?? JSON.stringify(value).slice(0, 600))
+                    }
+                ]
+        },
+        async execute (args, _exec) {
+            const q = unwrapQuery(args, 'limit');
+            const r = await listArtifacts({
+                stateRoot: config.stateRoot ?? '.',
+                limit: q.limit
+            });
+            const lines = r.artifacts.map((a)=>`- [${a.source}] ${a.title}${a.status ? `(${a.status})` : ''} — ${a.path}${a.updated ? ` @ ${a.updated.slice(0, 16).replace('T', ' ')}` : ''}`);
+            const summary = r.artifacts.length ? `在册产物 ${r.artifacts.length}/${r.total} 项${r.truncated ? '(截断,可加 limit)' : ''}:\n${lines.join('\n')}` : '无在册产物(异步深度规划交付与工作目录 md 文件都会出现在这里)';
+            return JSON.parse(JSON.stringify({
+                ok: true,
+                artifacts: r.artifacts,
+                total: r.total,
+                truncated: r.truncated,
+                summary
+            }));
+        },
+        presentCall: ()=>({
+                card: 'generic',
+                title: '列出产物',
+                kind: 'search'
+            }),
+        presentResult: (_args, value)=>{
+            const r = value;
+            return {
+                card: 'generic',
+                title: `产物:${r.total ?? 0} 项在册`,
+                content: [
+                    {
+                        type: 'text',
+                        text: String(r.summary ?? '')
+                    }
+                ]
+            };
+        }
+    }));
+    registerGuarded(defineTool({
+        name: 'gotry_artifacts_read',
+        description: 'Read one GoTry artifact as a line-numbered file view rendered directly in the chat UI. ' + 'Input: the path from gotry_artifacts_list, or a bare async ticket id (e.g. dp-xxxx). ' + 'Optional offset (1-based) / limit window for paging large files. ' + 'READ-ONLY; text artifacts only (md/txt/json/jsonl/csv/log/yaml).',
+        parameters: {
+            query: {
+                type: 'json',
+                required: true,
+                description: '{ path: "<list 返回的路径或工单 id>", offset?: 1, limit?: 400 }'
+            }
+        },
+        output: {
+            schema: {
+                type: 'json'
+            },
+            render: (_args, value)=>[
+                    {
+                        type: 'text',
+                        text: String(value.content ?? JSON.stringify(value).slice(0, 600))
+                    }
+                ]
+        },
+        async execute (args, _exec) {
+            const q = unwrapQuery(args, 'path');
+            if (!q.path) return JSON.parse(JSON.stringify({
+                ok: false,
+                error: 'path 必填(来自 gotry_artifacts_list)'
+            }));
+            const r = await readArtifact({
+                stateRoot: config.stateRoot ?? '.',
+                path: q.path,
+                offset: q.offset,
+                limit: q.limit
+            });
+            if (!r.ok) return JSON.parse(JSON.stringify(r));
+            return JSON.parse(JSON.stringify({
+                ...r,
+                summary: `${r.path}(${r.totalLines} 行)第 ${r.offset}-${r.offset + r.lines.length - 1} 行${r.windowed ? `(共 ${r.totalLines} 行,可翻页)` : ''}`
+            }));
+        },
+        presentCall: (args)=>({
+                card: 'generic',
+                title: `读产物:${String(args.query?.path ?? '')}`,
+                kind: 'read',
+                rawInput: args.query
+            }),
+        presentResult: (_args, value)=>{
+            const r = value;
+            if (!r.ok) {
+                return {
+                    card: 'generic',
+                    title: '读产物失败',
+                    content: [
+                        {
+                            type: 'text',
+                            text: String(r.error ?? '')
+                        }
+                    ]
+                };
+            }
+            return {
+                card: 'read',
+                title: r.path?.split('/').pop() ?? r.path ?? '',
+                path: r.path ?? '',
+                offset: r.offset ?? 1,
+                lines: r.lines ?? [],
+                totalLines: r.totalLines ?? 0,
+                lang: r.lang,
+                content: [
+                    {
+                        type: 'text',
+                        text: r.content ?? ''
+                    }
+                ]
+            };
+        }
+    }));
 }
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danceiny/gotry",
-  "version": "0.0.1-rc.14",
+  "version": "0.0.1-rc.15",
   "description": "GoTry — 从出发到下一次出发的 AI 旅行 Agent(dsh 插件)。npm 包入口 + vendored dsh runtime + 5 行 README 安装路径。",
   "type": "module",
   "main": "ts/src/index.ts",
@@ -20,6 +20,7 @@
     "ts/src/dsh-llm.ts",
     "ts/src/mock-llm.ts",
     "ts/src/state-ledger.ts",
+    "ts/src/booking-saga.ts",
     "ts/src/tool-packet.ts",
     "ts/src/memory-capture.ts",
     "ts/src/memory-utility.ts",
@@ -50,7 +51,8 @@
     "README.zh-CN.md",
     "LICENSE",
     "ts/capabilities/session-consent.ts",
-    "ts/capabilities/session-login.ts"
+    "ts/capabilities/session-login.ts",
+    "ts/capabilities/artifacts.ts"
   ],
   "engines": {
     "node": ">=22.0.0"

package/ts/capabilities/artifacts.ts

@@ -0,0 +1,235 @@
+/**
+ * 产物面(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 { readdir, readFile, stat } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { isAbsolute, join, resolve, sep } from 'node:path'
+
+import { openLedgerIfExists } from '../src/state-ledger.ts'
+
+export interface ArtifactEntry {
+  source: 'async-run' | 'cwd-file'
+  id: string
+  title: string
+  path: string
+  status?: string
+  updated?: string
+  bytes?: number
+}
+
+export interface ArtifactReadView {
+  ok: true
+  path: string
+  offset: number
+  lines: Array<{ number: number; text: string }>
+  totalLines: number
+  lang?: string
+  content: string
+  windowed: boolean
+}
+
+const MAX_LIST = 50
+const MAX_WINDOW = 400
+const MAX_BYTES = 2 * 1024 * 1024
+const TEXT_EXT_LANG: Record<string, string> = {
+  md: 'markdown', txt: 'text', json: 'json', jsonl: 'json', csv: 'csv', log: 'text', yaml: 'yaml', yml: 'yaml',
+}
+const DIR_DENY = ['node_modules', '.git']
+
+function rootOf(stateRoot: string): string {
+  return stateRoot === '.' ? process.cwd() : resolve(stateRoot)
+}
+
+function underRoot(p: string, root: string): boolean {
+  const r = resolve(root)
+  return p === r || p.startsWith(r + sep)
+}
+
+function hasDeniedSegment(p: string): boolean {
+  return p.split(sep).some(seg => DIR_DENY.includes(seg))
+}
+
+function asyncDeliverablePath(root: string, id: string): string {
+  return join(root, 'gotry-state', 'async', `${id}.deliverable.md`)
+}
+
+/** 账本 workflow_runs 是权威(listWorkflowRuns 只读 SELECT 直查,不为一个视图改 ledger 类)。 */
+function listRunsFromLedger(root: string, tenant: string, limit: number): ArtifactEntry[] {
+  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) as Array<{ id: string; goal: string; status: string; deliverable: string | null; updated: string }>
+  return rows.map(r => {
+    const file = asyncDeliverablePath(root, r.id)
+    return {
+      source: 'async-run' as const,
+      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: string, limit: number): Promise<ArtifactEntry[]> {
+  const dir = join(root, 'gotry-state', 'async')
+  let names: string[] = []
+  try {
+    names = (await readdir(dir)).filter(n => n.endsWith('.deliverable.md'))
+  } catch {
+    return []
+  }
+  const entries: ArtifactEntry[] = []
+  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
+    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.sort((a, b) => String(b.updated).localeCompare(String(a.updated)))
+}
+
+/** dsh 工作目录顶层 *.md(agent 写出的行程规划等);非递归,排除 dotfiles。 */
+async function listCwdMarkdown(cwd: string, limit: number): Promise<ArtifactEntry[]> {
+  let dirents
+  try {
+    dirents = await readdir(cwd, { withFileTypes: true })
+  } catch {
+    return []
+  }
+  const entries: ArtifactEntry[] = []
+  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
+    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,
+    })
+  }
+  return entries.sort((a, b) => String(b.updated).localeCompare(String(a.updated))).slice(0, limit)
+}
+
+export async function listArtifacts(opts: {
+  stateRoot: string
+  cwd?: string
+  limit?: number
+}): Promise<{ artifacts: ArtifactEntry[]; total: number; truncated: boolean; roots: string[] }> {
+  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 seenPath = new Set<string>()
+  const merged: ArtifactEntry[] = []
+  for (const e of [...listRunsFromLedger(root, 'local', limit), ...(await listDeliverableFiles(root, limit)), ...(await listCwdMarkdown(cwd, 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 ?? '')))
+
+  const total = merged.length
+  return { artifacts: merged.slice(0, limit), total, truncated: total > limit, roots: [root, cwd] }
+}
+
+/**
+ * 读一个产物。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: {
+  stateRoot: string
+  cwd?: string
+  path: string
+  offset?: number
+  limit?: number
+}): Promise<ArtifactReadView | { ok: false; error: string; hint?: string }> {
+  const root = rootOf(opts.stateRoot)
+  const cwd = opts.cwd ? resolve(opts.cwd) : process.cwd()
+  const raw = String(opts.path ?? '').trim()
+  if (!raw) return { ok: false, error: 'path 必填(来自 gotry_artifacts_list 的 path,或异步工单 id)' }
+
+  let text: string | null = 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) as { deliverable: string | null } | undefined
+    if (run?.deliverable) {
+      text = run.deliverable
+      filePath = asyncDeliverablePath(root, raw)
+    } else {
+      const p = asyncDeliverablePath(root, raw)
+      if (existsSync(p)) { filePath = p; text = await readFile(p, '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)]
+    const allowed = candidates.find(p => (underRoot(p, cwd) || underRoot(p, root)) && !hasDeniedSegment(p))
+    if (!allowed) {
+      return { ok: false, error: `路径越界:${raw}`, hint: `只读 ${root} 与 dsh 工作目录内的文本产物` }
+    }
+    const ext = allowed.slice(allowed.lastIndexOf('.') + 1).toLowerCase()
+    if (!TEXT_EXT_LANG[ext]) {
+      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 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,
+    path: filePath,
+    offset,
+    lines: slice.map((t, i) => ({ number: offset + i, text: t })),
+    totalLines: allLines.length,
+    lang: TEXT_EXT_LANG[ext] ?? 'text',
+    content: slice.join('\n'),
+    windowed: allLines.length > offset - 1 + slice.length,
+  }
+}