@lyra_wang/dsh-terminal-context 0.0.0-stage → 0.3.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,65 @@
+/**
+ * 界面侧 · 读终端画面（v0.3.0）
+ *
+ * 走的是"看屏幕"这条路，不是接口：终端是 xterm 渲染的 DOM，和对话在同一个页面里，
+ * 所以直接读渲染出来的行即可 —— 和"豆包看着 Word 的界面操作 Word"同一个思路。
+ *
+ * 为什么不用 terminalController：客户端 `ctx` 上只有 `fiber`，服务名找不到；
+ * 而 DOM 这条路不依赖任何内部 API。
+ *
+ * 三条硬约束（上次事故的教训）：
+ *   1. inject: []        —— 没有依赖，就不可能 pending，不可能拖垮启动
+ *   2. 全部 try/catch    —— 一个异常不该让界面白屏
+ *   3. 只读              —— 不改终端、不发输入
+ */
+window.__ModuleLoader__.load({
+  id: '@lyra_wang/dsh-terminal-context',
+  factory() {
+    const MAX_LINES = 60
+    const readScreen = () => {
+      // xterm 把可见区渲染成 .xterm-rows 下的若干行
+      const rows = document.querySelectorAll('.xterm-rows > div')
+      if (!rows.length) {
+        const screen = document.querySelector('.xterm-screen')
+        if (!screen) return null
+        const text = (screen.innerText || '').split('\n')
+        return text.slice(-MAX_LINES)
+      }
+      const lines = []
+      for (const row of rows) {
+        const text = (row.textContent || '').replace(/\u00a0/g, ' ').replace(/\s+$/, '')
+        lines.push(text)
+      }
+      while (lines.length && !lines[0].trim()) lines.shift()
+      while (lines.length && !lines[lines.length - 1].trim()) lines.pop()
+      return lines.slice(-MAX_LINES)
+    }
+    return {
+      inject: [],
+      apply(ctx) {
+        let last = ''
+        const push = () => {
+          try {
+            const lines = readScreen()
+            if (lines === null) return
+            const joined = lines.join('\n')
+            if (joined === last) return
+            last = joined
+            fetch('/plugins/terminal-context/push', {
+              method: 'POST',
+              headers: { 'content-type': 'application/json' },
+              body: JSON.stringify({ lines, truncated: lines.length >= MAX_LINES, diag: 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 @@
+{ "meta": { "title": "DSH Terminal Context", "description": "Feeds the DSH sidebar terminal's recent output to the agent so its next step matches what is actually on screen." } }

package/locale/zh.json

@@ -0,0 +1 @@
+{ "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.3.0",
+  "type": "module",
+  "description": "把侧边栏终端最近若干行交给 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"
+  ]
 }