@lyra_wang/dsh-terminal-context 0.0.0-stage → 0.4.0

package/README.md

@@ -1,3 +1,48 @@
-# Temporary Holding Version
+# @lyra_wang/dsh-terminal-context
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+把 **DSH 侧边栏终端**当前屏幕的内容交给 Agent，让它下一步的指令依据你真实的终端状态，
+而不是凭空安排。
+
+## 它解决什么
+
+你在侧边栏终端里跑命令时，Agent 看不到你敲了什么、看到了什么报错、在哪个目录。
+于是它给的指令经常"对着空气"：让你 `cd` 到已经在的目录、重复你已经做过的步骤、
+或者在你已经失败的前提下继续往下走。
+
+装上之后，Agent 能读到当前屏幕，于是：
+
+- 知道你**在哪个目录**（不用你说）
+- 知道你**上一条命令的结果**（成功/报错）
+- 你跑完之后，它能**接着结果往下做**
+
+## 怎么工作
+
+```
+界面侧（同一页面）               Host 侧
+读 .xterm-rows 渲染出的可见行  →  POST /plugins/terminal-context/push  →  内存缓存
+                                                                       ↓
+                                                          Agent 工具 read_terminal_context
+```
+
+**只读**：不改终端、不发输入、不落盘（终端里可能有 token，进程结束就没了）。
+
+## 已知限制
+
+- **只能读到当前可见的一屏**（最多 60 行）。向上滚出屏幕的缓冲读不到 —— 这是"看屏幕"这条路的固有代价。
+- 依赖 xterm 的 DOM 类名（`.xterm-rows`）。xterm 大改版会失效，失效表现是"没数据"，不会影响 DSH 启动。
+- 内容**变了才推**，每 2 秒检查一次。
+
+## 安全设计
+
+`inject: []` —— 界面插件不声明任何服务依赖。这是刻意的：DSH 的界面插件如果声明了一个
+不存在的服务，入口会永久 pending，**导致整个界面起不来**（v0.1.0 踩过这个坑）。
+不声明依赖，最坏情况是"插件没反应"，不会拖垮应用。
+
+## 要求
+
+- DSH 桌面端
+- 侧边栏打开过终端
+
+## 许可
+
+MIT

package/client.js

@@ -0,0 +1,85 @@
+/**
+ * 界面侧 · 读侧边栏（v0.4.0）
+ *
+ * 原来只读终端的 .xterm-rows。但侧边栏不止终端 —— 还可能挂着浏览器面板，
+ * 两者都是"你眼前的东西"，都该进 Agent 的上下文。
+ *
+ * 做法：先按已知结构读终端；再扫一遍可能的侧边栏容器，把它们的结构一起推回去。
+ * 为什么要推结构：不同面板的 DOM 差别很大，与其猜选择器，不如让页面自己报告
+ * "有哪些容器、各有多少字"，下一版照着写就一次到位。
+ *
+ * 三条硬约束（v0.1 事故的教训）：
+ *   inject: []      不声明依赖 → 不可能 pending → 不会拖垮启动
+ *   全部 try/catch  读失败只是"没数据"，不白屏
+ *   只读            不点击、不输入
+ */
+window.__ModuleLoader__.load({
+  id: '@lyra_wang/dsh-terminal-context',
+  factory() {
+    const MAX = 80
+    const clean = (t) => (t || '').replace(/\u00a0/g, ' ').replace(/[ \t]+$/gm, '')
+
+    const readTerminal = () => {
+      const rows = document.querySelectorAll('.xterm-rows > div')
+      if (!rows.length) return null
+      const out = []
+      for (const r of rows) out.push(clean(r.textContent))
+      while (out.length && !out[0].trim()) out.shift()
+      while (out.length && !out[out.length - 1].trim()) out.pop()
+      return out.slice(-MAX)
+    }
+
+    // 扫可能的侧边栏容器。命中后连结构和样本一起带回去，供下一版锁定选择器。
+    const scanPanels = () => {
+      const hits = []
+      const seen = new Set()
+      const nodes = document.querySelectorAll('[class*="sidebar"],[class*="rightbar"],[class*="panel"],[class*="terminal"],[class*="browser"],[id*="sidebar"],[id*="panel"]')
+      for (const el of nodes) {
+        if (seen.has(el) || el === document.body) continue
+        seen.add(el)
+        const text = clean(el.innerText || '')
+        if (text.length < 40) continue
+        hits.push({
+          tag: el.tagName.toLowerCase(),
+          cls: String(el.className || '').slice(0, 80),
+          chars: text.length,
+          sample: text.slice(0, 120).replace(/\n+/g, ' ⏎ '),
+        })
+        if (hits.length >= 8) break
+      }
+      return hits
+    }
+
+    return {
+      inject: [],
+      apply(ctx) {
+        let lastKey = ''
+        const push = () => {
+          try {
+            const lines = readTerminal()
+            const panels = scanPanels()
+            const key = JSON.stringify([lines && lines.slice(-5), panels.map((p) => p.cls + p.chars)])
+            if (key === lastKey) return
+            lastKey = key
+            fetch('/plugins/terminal-context/push', {
+              method: 'POST',
+              headers: { 'content-type': 'application/json' },
+              body: JSON.stringify({
+                lines: lines || [],
+                truncated: !!(lines && lines.length >= MAX),
+                diag: panels.length ? { panels } : null,
+              }),
+            }).catch(() => {})
+          } catch { /* 静默 */ }
+        }
+        try {
+          ctx.effect(() => {
+            const first = setTimeout(push, 1200)
+            const timer = setInterval(push, 2000)
+            return () => { clearTimeout(first); clearInterval(timer) }
+          })
+        } catch { /* ignore */ }
+      },
+    }
+  },
+})

package/cordis.patch.yml

@@ -0,0 +1,4 @@
+- insert:
+    - id: dsh-terminal-context
+      name: '@lyra_wang/dsh-terminal-context'
+      config: {}

package/icon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24" fill="none" stroke="#4D6BFE" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="3" y="4" width="18" height="16" rx="2"/><path d="M7 9l3 3-3 3"/><path d="M13 15h4"/></svg>

package/index.js

@@ -0,0 +1,96 @@
+/**
+ * Host half of terminal-context.
+ *
+ * The browser half subscribes to `terminalController.attach` (a Remote-only
+ * stream a Host plugin cannot open) and pushes the visible lines here. This
+ * half keeps only the most recent push in memory and exposes it to the agent
+ * through a tool. Nothing is written to disk: the terminal may contain
+ * secrets, so the buffer dies with the process.
+ */
+
+const PUSH_PATH = '/plugins/terminal-context/push'
+const MAX_LINES = 200
+
+let latest = { updatedAt: 0, terminalId: '', cwd: '', lines: [], truncated: false, diag: null }
+
+function send(res, status, payload) {
+  if (res && typeof res.writeHead === 'function') {
+    res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' })
+    res.end(JSON.stringify(payload))
+    return
+  }
+  return new Response(JSON.stringify(payload), {
+    status,
+    headers: { 'content-type': 'application/json; charset=utf-8' },
+  })
+}
+
+function readBody(req) {
+  if (req && typeof req[Symbol.asyncIterator] === 'function') {
+    return (async () => {
+      const chunks = []
+      for await (const chunk of req) chunks.push(chunk)
+      return Buffer.concat(chunks).toString('utf8')
+    })()
+  }
+  if (req && typeof req.text === 'function') return req.text()
+  return Promise.resolve('')
+}
+
+export const inject = ['tools', 'webServer']
+
+export function apply(ctx) {
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: PUSH_PATH,
+    handler: async (req, res) => {
+      try {
+        const body = JSON.parse(await readBody(req))
+        const lines = Array.isArray(body.lines) ? body.lines.slice(-MAX_LINES).map(String) : []
+        latest = {
+          diag: body.diag || null,
+          updatedAt: Date.now(),
+          terminalId: String(body.terminalId || ''),
+          cwd: String(body.cwd || ''),
+          lines,
+          truncated: Boolean(body.truncated),
+        }
+        return send(res, 200, { ok: true, lines: lines.length })
+      } catch (error) {
+        return send(res, 400, { ok: false, error: String((error && error.message) || error) })
+      }
+    },
+  }), 'terminal-context: push route')
+
+  ctx.effect(() => {
+    const dispose = ctx.tools.register({
+      name: 'read_terminal_context',
+      description:
+        'Return the last lines the user saw in their sidebar terminal, plus its working directory and how fresh it is. Use before proposing a command when the user is working in a terminal, and after they say a command finished.',
+      parameters: { type: 'object', properties: {}, additionalProperties: false },
+      output: {
+        schema: { type: 'object', additionalProperties: true },
+        render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+      },
+      async execute() {
+        if (!latest.updatedAt) {
+          return {
+            available: false,
+            reason: 'browser half has not pushed anything yet',
+            hint: 'the terminal-context client module must be installed and the page reloaded',
+          }
+        }
+        return {
+          available: true,
+          ageSeconds: Math.round((Date.now() - latest.updatedAt) / 1000),
+          terminalId: latest.terminalId,
+          cwd: latest.cwd,
+          truncated: latest.truncated,
+          diag: latest.diag,
+          lines: latest.lines,
+        }
+      },
+    })
+    return () => dispose()
+  })
+}

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "DSH Sidebar Context",
+    "description": "Feeds the DSH sidebar's current content (terminal / browser panel) to the agent so its next step matches what is on screen."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "DSH 侧边栏上下文",
+    "description": "把 DSH 侧边栏当前显示的内容（终端 / 浏览器面板）交给 Agent，让它依据你眼前真实的东西给下一步。"
+  }
+}

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@lyra_wang/dsh-terminal-context",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.4.0",
+  "type": "module",
+  "description": "把 DSH 侧边栏当前显示的内容（终端 / 浏览器面板）交给 Agent，作为它判断当前处境的上下文。",
+  "exports": {
+    ".": "./index.js",
+    "./locale/*.json": "./locale/*.json",
+    "./icon": "./icon.svg",
+    "./client": "./client.js"
+  },
+  "files": [
+    "index.js",
+    "client.js",
+    "cordis.patch.yml",
+    "locale/*.json",
+    "icon.svg"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "immediately": true,
+      "inject": []
+    }
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LyraWang6688/ai-capability-store.git",
+    "directory": "external-capabilities/plugin/dsh/terminal-context"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "terminal",
+    "context"
+  ]
 }