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

package/extension/README.md

@@ -0,0 +1,26 @@
+# GoTry Session Bridge(浏览器扩展)
+
+一次性安装的会话检索数据面(issue #21 传输层方案 C,2026-08-29 founder 定案):在你**自己的** Chrome 登录态里,只读嗅探携程机票检索回包([会话:ctrip-flight]。gotry 不再需要逐连接弹 Chrome 权限框,也不需要开 `chrome://inspect` 远程调试。
+
+## 它做什么 / 不做什么
+
+- ✅ 检索:你(或 agent)发起会话检索时,后台标签页打开携程机票列表页,被动嗅探页面自己发出的 `batchSearch` 响应,文本回传给本机的 gotry。收尾自动关闭自己开的标签。
+- ✅ 登录检查:只读登录票据 cookie 的**名字**(cticket/uid/uname/passport),判断「是否已登录」这个布尔事实。
+- ✅ 登录引导:把登录入口页**置前台**打开,登录由你在携程官网完成。
+- ❌ **不读取、不存储、不回传任何 cookie 值,不接触密码/验证码**;
+- ❌ 不向任何站点发起请求(检索请求由站点页面自己发出,扩展只听不写);
+- ❌ 不动你已打开的任何标签页(只创建/关闭自己的检索标签;登录标签留给你)。
+
+## 安装(每台浏览器一次,约 30 秒)
+
+1. 跑一次 `npx gotry setup`(或手动:把本目录整体拷到任意固定位置,建议 `~/.gotry/extension/`);
+2. Chrome 地址栏打开 `chrome://extensions`;
+3. 右上角开启「开发者模式」;
+4. 点「加载已解压的扩展程序」,选择本目录(manifest.json 所在目录)。
+
+装好即生效,无任何系统弹窗。卸载/随时可停:扩展卡片上的开关即是总闸(仍受 gotry 授权闸 `sessionAccess` 双重控制)。
+
+## 自检
+
+- 扩展 ID 应为固定的 `olpgkofjhhiiiahdkkbcninhjmegghfe`(manifest 带 `key`,跨机器稳定)——若不一致,说明 manifest 被改动过,不要安装;
+- gotry 侧运行 `npx gotry` 后发起一次会话检索,扩展图标应出现(无需点击);桥状态可看 `curl http://127.0.0.1:8791/status`(仅本机回环)。

package/extension/background.js

@@ -0,0 +1,160 @@
+/**
+ * GoTry Session Bridge — MV3 Service Worker(RFC user-session-data-rfc.md §2.2 通道 C,2026-08-29 定案为 PRIMARY 传输)。
+ *
+ * 职责(与 Node 侧 session/extension-bridge.ts 配对,零构建纯 JS):
+ *   - 长轮询取活:POST /jobs(桥最多 hold 20s;每次响应/失败都重置 SW 30s 生命周期,任务秒级触达);
+ *     断线每 5s 重试,chrome.alarms(30s)兜底唤醒防 SW 悬挂。
+ *   - 三种 job:
+ *       search       → 后台标签打开 job.url(仅 flights.ctrip.com 白名单),等 content hook 嗅探回包,收尾关自己的标签;
+ *       open-login   → 置前台打开登录入口页(登录页纪律 #34),标签留给用户,绝不代关;
+ *       cookie-names → chrome.cookies 只读票据 cookie **名字**(值即取即弃,永不离开扩展——红线)。
+ *   - 物理只读(ReadGuard 扩展车道形态):本 SW 绝不向站点发任何请求——检索请求由站点自己的
+ *     页面代码发出,我们只「导航 + 被动转发 NETWORK_HINTS 命中响应」;写不是被禁止的行为,是不存在的原语。
+ */
+
+'use strict'
+
+const BRIDGE_PORTS = [8791, 8792, 8793, 8794, 8795]
+const RETRY_MS = 5_000
+
+/** 站点注册表(与 Node 侧 LOGIN_TARGETS/LOGIN_COOKIE_NAMES 对账,防漂移测试守住) */
+const SITES = {
+  'ctrip-flight': {
+    domain: 'ctrip.com',
+    ticketNames: ['cticket', 'uid', 'uname', 'passport'],
+  },
+}
+
+let activePort = null
+let polling = false
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+async function detectPort() {
+  for (const p of BRIDGE_PORTS) {
+    try {
+      const r = await fetch(`http://127.0.0.1:${p}/health`, { headers: { 'x-gotry-bridge': 'v1' } })
+      if (r.ok) return p
+    } catch { /* 无人监听,试下一个端口 */ }
+  }
+  return null
+}
+
+async function postResult(jobId, result) {
+  if (activePort == null || !jobId) return
+  try {
+    await fetch(`http://127.0.0.1:${activePort}/results/${encodeURIComponent(jobId)}`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', 'x-gotry-bridge': 'v1' },
+      body: JSON.stringify(result),
+    })
+  } catch { /* 桥可能已退场;Node 侧超时兜底 */ }
+}
+
+/** 只读票据 cookie 名单(只上报名;chrome.cookies 的值就地丢弃,不进任何结果对象) */
+async function ticketNames(site) {
+  const conf = SITES[site]
+  if (!conf) return []
+  const cookies = await chrome.cookies.getAll({ domain: conf.domain }).catch(() => [])
+  return (Array.isArray(cookies) ? cookies : [])
+    .map((c) => c.name)
+    .filter((n) => conf.ticketNames.includes(n))
+}
+
+/** 后台标签等嗅探回包;超时带回页标题(供 Node 侧 CHALLENGE_RE 判定),收尾关自己的标签 */
+function waitSniff(tabId, timeoutMs) {
+  return new Promise((resolve) => {
+    let settled = false
+    let title = ''
+    const handler = (msg, sender) => {
+      if (!sender || !sender.tab || sender.tab.id !== tabId) return
+      if (msg && msg.type === 'gotry-page') { title = String(msg.title ?? title); return }
+      if (msg && msg.type === 'gotry-sniff' && !settled) {
+        settled = true
+        clearTimeout(timer)
+        chrome.runtime.onMessage.removeListener(handler)
+        resolve({ ok: true, kind: 'search', body: String(msg.body ?? ''), title })
+      }
+    }
+    const timer = setTimeout(() => {
+      if (settled) return
+      settled = true
+      chrome.runtime.onMessage.removeListener(handler)
+      resolve({ ok: false, kind: 'search', timeout: true, title })
+    }, Math.max(Number(timeoutMs) || 30_000, 5_000))
+    chrome.runtime.onMessage.addListener(handler)
+  })
+}
+
+async function handleJob(job) {
+  const jobId = job && job.jobId
+  if (typeof jobId !== 'string' || !jobId) return
+  const site = String((job && job.site) || '')
+  const conf = SITES[site]
+  try {
+    if (!conf) {
+      await postResult(jobId, { ok: false, error: `unknown site ${site}` })
+      return
+    }
+    if (job.kind === 'cookie-names') {
+      await postResult(jobId, { ok: true, kind: 'cookie-names', names: await ticketNames(site) })
+      return
+    }
+    if (job.kind === 'open-login') {
+      if (typeof job.url !== 'string' || !job.url.startsWith('https://')) {
+        await postResult(jobId, { ok: false, error: 'open-login 需要 https job.url' })
+        return
+      }
+      const tab = await chrome.tabs.create({ url: job.url, active: true })
+      await postResult(jobId, { ok: true, kind: 'open-login', opened: true, tabId: tab.id })
+      return
+    }
+    if (job.kind === 'search') {
+      if (typeof job.url !== 'string' || !job.url.startsWith('https://flights.ctrip.com/')) {
+        await postResult(jobId, { ok: false, error: `search 只允许 flights.ctrip.com 域(收到 ${String(job.url).slice(0, 80)})` })
+        return
+      }
+      const tab = await chrome.tabs.create({ url: job.url, active: false })
+      const result = await waitSniff(tab.id, job.timeoutMs)
+      await chrome.tabs.remove(tab.id).catch(() => { /* 用户先关了,无妨 */ })
+      await postResult(jobId, result)
+      return
+    }
+    await postResult(jobId, { ok: false, error: `unknown job kind ${String(job.kind)}` })
+  } catch (e) {
+    await postResult(jobId, { ok: false, error: String(e && e.message ? e.message : e).slice(0, 200) })
+  }
+}
+
+async function loop() {
+  if (polling) return
+  polling = true
+  try {
+    for (;;) {
+      if (activePort == null) activePort = await detectPort()
+      if (activePort == null) { await sleep(RETRY_MS); continue }
+      try {
+        const r = await fetch(`http://127.0.0.1:${activePort}/jobs`, {
+          method: 'POST',
+          headers: { 'content-type': 'application/json', 'x-gotry-bridge': 'v1' },
+          body: JSON.stringify({
+            extensionVersion: chrome.runtime.getManifest().version,
+            capabilities: Object.keys(SITES),
+          }),
+        })
+        const data = await r.json().catch(() => ({ job: null }))
+        if (data && data.job) await handleJob(data.job)
+      } catch { activePort = null; await sleep(RETRY_MS) }
+    }
+  } finally {
+    polling = false
+  }
+}
+
+// SW 冷启动 + 闹钟兜底双保险;loop() 幂等
+if (chrome.runtime.onStartup) chrome.runtime.onStartup.addListener(() => { void loop() })
+chrome.alarms.create('gotry-bridge-poll', { periodInMinutes: 0.5 })
+chrome.alarms.onAlarm.addListener((a) => { if (a.name === 'gotry-bridge-poll') void loop() })
+void loop()

package/extension/content-bridge.js

@@ -0,0 +1,41 @@
+/**
+ * GoTry Session Bridge — ISOLATED-world 桥(manifest 默认 world,document_start)。
+ *
+ * MAIN world(content-main.js)拿不到 chrome API;本脚本监听页面里的
+ * gotry-ctrip-sniff 自定义事件,把响应文本经 chrome.runtime.sendMessage 转发给
+ * Service Worker(onMessage 按 sender.tab.id 归属到对应 search job)。
+ *
+ * 附带页标题快报(gotry-page):SW 在嗅探超时/挑战判定(CHALLENGE_RE)时用它。
+ */
+;(function () {
+  if (window.__gotrySniffBridge) return
+  window.__gotrySniffBridge = true
+
+  window.addEventListener('gotry-ctrip-sniff', function (ev) {
+    try {
+      var d = (ev && ev.detail) || {}
+      if (!d.body) return
+      chrome.runtime.sendMessage({
+        type: 'gotry-sniff',
+        url: d.url,
+        body: d.body,
+        title: document.title || '',
+      }).catch(function () { /* SW 重启中,下一条嗅探再投 */ })
+    } catch { /* 不抛 */ }
+  })
+
+  function sendPage() {
+    try {
+      chrome.runtime.sendMessage({
+        type: 'gotry-page',
+        title: document.title || '',
+        url: location.href,
+      }).catch(function () { /* SW 侧无等待者,常态丢弃 */ })
+    } catch { /* 环境异常不抛 */ }
+  }
+  if (document.readyState === 'loading') {
+    window.addEventListener('DOMContentLoaded', sendPage, { once: true })
+  } else {
+    sendPage()
+  }
+})()

package/extension/content-main.js

@@ -0,0 +1,62 @@
+/**
+ * GoTry Session Bridge — MAIN-world 网络嗅探(manifest world:"MAIN",document_start)。
+ *
+ * MAIN world 没有 chrome.runtime,只负责:hook 站点自己的 fetch/XHR,把命中
+ * NETWORK_HINTS(batchSearch)的响应文本以 CustomEvent 派发到页面里;
+ * ISOLATED 侧的 content-bridge.js 监听事件并经 chrome.runtime 转发给 Service Worker。
+ *
+ * 只读被动转发:不修改请求、不重放、不伪造(§2.3 反模式红线)——响应由站点自己的
+ * 代码发出,我们只听。
+ */
+;(function () {
+  if (window.__gotrySniffInstalled) return
+  window.__gotrySniffInstalled = true
+
+  /** 与 Node 侧 adapters/ctrip-flight.ts NETWORK_HINTS 对账(run-all §38 防漂移断言) */
+  var HINT_RE = /search\/api\/search\/batchSearch/
+
+  function dispatch(url, body) {
+    try {
+      window.dispatchEvent(new CustomEvent('gotry-ctrip-sniff', { detail: { url: String(url), body: String(body) } }))
+    } catch { /* 页面环境异常不抛 */ }
+  }
+
+  var origFetch = window.fetch
+  if (typeof origFetch === 'function') {
+    window.fetch = function (input, init) {
+      return origFetch.apply(this, arguments).then(function (res) {
+        try {
+          var url = ''
+          if (typeof input === 'string') url = input
+          else if (input && typeof input.url === 'string') url = input.url
+          if (HINT_RE.test(url)) {
+            var clone = res.clone()
+            clone.text().then(function (t) { dispatch(url, t) }).catch(function () { /* 流不可读则跳过 */ })
+          }
+        } catch { /* 嗅探失败不影响站点自身 */ }
+        return res
+      })
+    }
+  }
+
+  var origOpen = XMLHttpRequest.prototype.open
+  var origSend = XMLHttpRequest.prototype.send
+  XMLHttpRequest.prototype.open = function (method, url) {
+    this.__gotryUrl = typeof url === 'string' ? url : String(url ?? '')
+    return origOpen.apply(this, arguments)
+  }
+  XMLHttpRequest.prototype.send = function () {
+    var xhr = this
+    xhr.addEventListener('load', function () {
+      try {
+        if (!xhr.__gotryUrl || !HINT_RE.test(xhr.__gotryUrl)) return
+        var body = ''
+        if (xhr.responseType === '' || xhr.responseType === 'text') body = xhr.responseText
+        else if (xhr.responseType === 'json') body = JSON.stringify(xhr.response)
+        else return
+        if (body) dispatch(xhr.__gotryUrl, body)
+      } catch { /* 嗅探失败不影响站点 */ }
+    })
+    return origSend.apply(this, arguments)
+  }
+})()

package/extension/manifest.json

@@ -0,0 +1,32 @@
+{
+  "manifest_version": 3,
+  "name": "GoTry Session Bridge",
+  "version": "0.1.0",
+  "description": "GoTry 会话检索桥(issue #21):在你自己的登录态里只读嗅探检索回包与登录票据 cookie 名;零凭证经手,登录在官网由你完成,检索只读不写。gotry 侧不再需要开启 Remote Debugging,也没有任何系统级权限弹窗。",
+  "key": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAnuzBX8rT8+RZKEUip5VRA0cY056pExy9PNdN9YCiuY3dgglRbcIBhjuFJoR6EX3/MaUv82vJVyItRVrowXLTwDk4WZof0vwFgKL0zBK304PC46pUaAKTSu1PgXeL1+j5KTAGz/9a9+RnPdbj7jND5rM/MOmBHNPVPpp1NlwxRGIgF9OxHSOfXORcH4Iyte1aJSFUJbFtNS/DaE5D+KjyupPLyIqVN/dCiKnNsTCEHQB9ngeli665PFp76hkccHQQZ4sVuMLS4zBPcazUsp1kcnW+xsQoUATkODTCY+Pzk3zUVF1QOESTjRCVnbNi8tkO43RMRs2q63gX/3inFivcEwIDAQAB",
+  "permissions": ["cookies", "alarms"],
+  "host_permissions": [
+    "http://127.0.0.1:8791/*",
+    "http://127.0.0.1:8792/*",
+    "http://127.0.0.1:8793/*",
+    "http://127.0.0.1:8794/*",
+    "http://127.0.0.1:8795/*",
+    "https://*.ctrip.com/*"
+  ],
+  "background": {
+    "service_worker": "background.js"
+  },
+  "content_scripts": [
+    {
+      "matches": ["https://flights.ctrip.com/*"],
+      "js": ["content-main.js"],
+      "run_at": "document_start",
+      "world": "MAIN"
+    },
+    {
+      "matches": ["https://flights.ctrip.com/*"],
+      "js": ["content-bridge.js"],
+      "run_at": "document_start"
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danceiny/gotry",
-  "version": "0.0.1-rc.14",
+  "version": "0.0.1-rc.16",
   "description": "GoTry — 从出发到下一次出发的 AI 旅行 Agent(dsh 插件)。npm 包入口 + vendored dsh runtime + 5 行 README 安装路径。",
   "type": "module",
   "main": "ts/src/index.ts",
@@ -20,6 +20,9 @@
     "ts/src/dsh-llm.ts",
     "ts/src/mock-llm.ts",
     "ts/src/state-ledger.ts",
+    "ts/src/booking-saga.ts",
+    "ts/src/bookable-facts.ts",
+    "ts/src/artifact-gate.ts",
     "ts/src/tool-packet.ts",
     "ts/src/memory-capture.ts",
     "ts/src/memory-utility.ts",
@@ -44,13 +47,16 @@
     "ts/capabilities/flyai.ts",
     "ts/capabilities/session-search.ts",
     "ts/capabilities/session/",
+    "extension/",
     "ts/package.json",
     "cordis.gotry-patch.yml",
     "README.md",
     "README.zh-CN.md",
     "LICENSE",
     "ts/capabilities/session-consent.ts",
-    "ts/capabilities/session-login.ts"
+    "ts/capabilities/session-login.ts",
+    "ts/capabilities/artifacts.ts",
+    "ts/capabilities/fact-log.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,
+  }
+}

package/ts/capabilities/fact-log.ts

@@ -0,0 +1,54 @@
+/**
+ * 可下单事实侧车持久化(issue #46,ADR-19):append-only JSONL 证据日志。
+ *
+ * 定位:这是**会话证据**而非用户状态——与 bridge-latency.jsonl / incidents.jsonl
+ * 同类(审计痕迹),不进账本投影。append-only 保历史(同 route+date 重查的旧快照
+ * 可回溯),读取侧经 dedupeFacts 取同 fact_id 最新。
+ *
+ * 路径:<stateRoot>/gotry-state/bookable-facts.jsonl
+ */
+
+import { appendFile, mkdir, readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { dedupeFacts, type BookableFact } from '../src/bookable-facts.ts'
+
+export const FACT_LOG_NAME = 'bookable-facts.jsonl'
+
+export function factLogPath(stateRoot: string): string {
+  const root = stateRoot === '.' ? process.cwd() : stateRoot
+  return join(root, 'gotry-state', FACT_LOG_NAME)
+}
+
+/** 追加事实(永不抛错:落盘失败不阻塞检索工具主路径,返回 false 由调用方记 incident) */
+export async function appendFacts(stateRoot: string, facts: BookableFact[]): Promise<boolean> {
+  if (facts.length === 0) return true
+  try {
+    const p = factLogPath(stateRoot)
+    await mkdir(join(p, '..'), { recursive: true })
+    await appendFile(p, facts.map(f => JSON.stringify(f)).join('\n') + '\n', 'utf-8')
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** 读注册表(去重后视图;无文件 = 空注册表,不抛) */
+export async function loadFactRegistry(stateRoot: string): Promise<BookableFact[]> {
+  try {
+    const raw = await readFile(factLogPath(stateRoot), 'utf-8')
+    const facts: BookableFact[] = []
+    for (const line of raw.split('\n')) {
+      const t = line.trim()
+      if (!t) continue
+      try {
+        const f = JSON.parse(t) as BookableFact
+        if (f.schema === 'gotry_bookable_fact.v1' && f.fact_id) facts.push(f)
+      } catch {
+        // 单行损坏不拖垮整本注册表(与 incidents/latency 日志同纪律)
+      }
+    }
+    return dedupeFacts(facts)
+  } catch {
+    return []
+  }
+}