dsh-agent-lines 0.3.8 → 0.3.9

package/CHANGELOG.en.md

@@ -2,6 +2,13 @@
 
 English | [中文](CHANGELOG.md)
 
+## 0.3.9 (2026-11-09)
+
+- Added read-only line_observe: a manager feed of cross-line messages without prompts or state changes.
+- Added CLI observe --json.
+- README now documents version-by-version business scenarios; fixed line_handoff version (0.3.7).
+- No schema change; line_send semantics unchanged.
+
 ## 0.3.8 (2026-11-09)
 
 - line_status / line_list expose activity: turns/steps/decodeTokens/level/lastActivityAt.

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 [English](CHANGELOG.en.md) | 中文
 
+## 0.3.9 (2026-11-09)
+
+- 新增只读 line_observe：管理线查看跨线消息 feed，不注入 prompt、不改消息状态。
+- CLI 新增 observe --json。
+- README 补“版本能力与业务场景”，修正 line_handoff 的版本标注（0.3.7）。
+- 无 schema 变化，line_send 语义不变。
+
 ## 0.3.8 (2026-11-09)
 
 - line_status / line_list 增加 activity：turns/steps/decodeTokens/level/lastActivityAt。

package/README.en.md

@@ -23,6 +23,32 @@ Use it when:
 - You want one lead agent to decompose work, create the team, track progress, collect results, and report back.
 
 
+## What each version adds (business scenarios)
+
+### 0.3.6: replace a role when context is full
+
+Scenario: a writer line has worked long enough that its context is saturated and quality drops.  
+Use: the manager calls line_create({ label: "writer", replace: true, force: true, reason: "context full" }).  
+Effect: the same label moves to a clean Session; the old Session is retired but kept; queued/claimed messages migrate; delivered/acked are never re-delivered; no manual routing.
+
+### 0.3.7: hand off before replacing
+
+Scenario: the new writer does not know what the old line finished, what is next, or which traps to avoid.  
+Use: line_handoff({ line: "writer", format: "md" }).  
+Effect: a structured snapshot (progress, backlog, recent messages, lifecycle) without a model call; the new line reads it first.
+
+### 0.3.8: know when to replace
+
+Scenario: the manager wants to see which line is close to saturation or has gone quiet.  
+Use: line_status / line_list expose activity.level, turns, steps, lastActivityAt.  
+Effect: a low/medium/high activity proxy, not a fake "78% context used"; exact context usage waits for DSH.
+
+### 0.3.9: the manager can see cross-line traffic
+
+Scenario: lines message each other directly; the manager needs visibility without every message becoming a manager turn.  
+Use: line_observe({ line: "writer", limit: 20 }) or CLI observe --json.  
+Effect: a read-only feed with from/to/state/summary; no prompt injection and no state change; line_send semantics unchanged.
+
 ## Install
 
 One-command install (recommended; no need to find a profile):
@@ -36,7 +62,7 @@ The script picks the DSH Web profile, installs the plugin, and verifies agent-li
 
 Offline or when npm is unavailable, use the local tarball:
 
-    bash install.sh ./dsh-agent-lines-0.3.8.tgz
+    bash install.sh ./dsh-agent-lines-0.3.9.tgz
 
 After install and restart, it works without a config. When you want a fixed manager/worker setup, paste the "Manager config" block below into the file printed by the installer.
 
@@ -139,6 +165,7 @@ Tools:
 | `line_list` | List lines, status, unread counts, current line and role |
 | `line_create` | Manager only: create a line; same label is idempotent; replace:true swaps the label to a fresh Session |
 | `line_handoff` | Manager only: structured handoff snapshot (JSON/Markdown), no model call |
+| `line_observe` | Manager only: read-only cross-line feed; no prompt injection, no state change |
 | `line_retire` | Manager only: soft-retire; reject new sends, keep Session and history |
 | `line_rebind` | Manager only: atomically switch a line to a new live Session, optionally migrating backlog |
 | `line_rename` | Manager only: rename the sidebar title and persist it in lines.db |
@@ -155,7 +182,7 @@ Line tools other than `line_status` and `line_claim_manager` are registered only
 
 A line does not inherit the old Session context. Recommended flow:
 
-1. Have the old line write a handoff file (line_handoff is available from 0.3.8);
+1. Have the old line write a handoff file (line_handoff is available from 0.3.7);
 2. The manager calls `line_create({ label, replace: true, force: true, reason: "context full" })`;
 3. The plugin creates a clean Session, atomically swaps the same label, and marks the old Session retired but keeps it;
 4. queued/claimed messages migrate to the new line; delivered/acked stay on the old Session and are never re-delivered.
@@ -171,6 +198,7 @@ dsh-agent-lines list
 dsh-agent-lines send --from frontend-line --to backend-line --text "hi"
 dsh-agent-lines inbox --line backend-line
 dsh-agent-lines ack --line backend-line --id msg_...
+dsh-agent-lines --json observe --line writer --limit 20
 dsh-agent-lines claim --agent agent-demo --line manager --session "$DSH_SESSION_ID"
 dsh-agent-lines doctor
 ```

package/README.md

@@ -23,6 +23,32 @@ DSH 的 super agent 平替插件。
 - 你希望一个负责人 agent 自己拆任务、建团队、追进度、收结果，最后向你汇报。
 
 
+## 版本能力与业务场景
+
+### 0.3.6：上下文满了，角色可以换人
+
+场景：写手线连续工作很久，上下文配额耗尽；继续写容易出现前后矛盾。  
+用法：管理线调用 line_create({ label: "writer", replace: true, force: true, reason: "context full" })。  
+效果：同一个 label 切到干净 Session，旧 Session 只 retired、不删除；queued/claimed 消息迁移，delivered/acked 不重投；管理线不需要手工改路由。
+
+### 0.3.7：换人之前先交接
+
+场景：新写手不知道旧线做到哪、下一步是什么、哪些坑不能踩。  
+用法：line_handoff({ line: "writer", format: "md" })。  
+效果：生成结构化交接单（进度、积压、最近消息、生命周期），不调用模型；新线先读交接单再继续。
+
+### 0.3.8：什么时候该换线
+
+场景：管理线想知道哪条线快满了、哪条线最近没动静。  
+用法：line_status / line_list 看 activity.level、turns、steps、lastActivityAt。  
+效果：给出低/中/高活跃度，不伪造“上下文使用率 78%”；真实窗口等 DSH 上游提供。
+
+### 0.3.9：管理线看得到跨线消息
+
+场景：成员线之间直接同步，管理线需要知道发生了什么，但不希望每条消息都打断自己。  
+用法：line_observe({ line: "writer", limit: 20 }) 或 CLI observe --json。  
+效果：只读 feed，显示 from/to/state/摘要；不注入 prompt、不改消息状态；line_send 语义不变。
+
 ## 安装
 
 一条命令安装（推荐，不需要自己找 profile）：
@@ -36,7 +62,7 @@ DSH 的 super agent 平替插件。
 
 离线或 npm 不可用时，用本地 tarball：
 
-    bash install.sh ./dsh-agent-lines-0.3.8.tgz
+    bash install.sh ./dsh-agent-lines-0.3.9.tgz
 
 安装并重启后，不写配置也可以直接使用；需要固定管理线/worker 时，再把下面“管理线配置”粘贴到脚本打印的配置文件。
 
@@ -144,6 +170,7 @@ level 是活跃度代理（low/medium/high），不是上下文使用率百分
 | `line_list` | 列出线、状态、未读数、当前线和 role |
 | `line_create` | 仅管理线：创建新线；同 label 幂等；传 replace:true 可给同 label 换新 Session |
 | `line_handoff` | 仅管理线：生成结构化交接单（JSON/Markdown），不调模型 |
+| `line_observe` | 仅管理线：只读跨线消息 feed；不注入 prompt、不改状态 |
 | `line_retire` | 仅管理线：软下线；拒绝新发送，保留 Session/历史 |
 | `line_rebind` | 仅管理线：把线原子切到新的 live Session，可迁移积压 |
 | `line_rename` | 仅管理线：改侧栏标题，持久化到 lines.db |
@@ -160,7 +187,7 @@ level 是活跃度代理（low/medium/high），不是上下文使用率百分
 
 线不会自动继承旧 Session 的上下文。推荐流程：
 
-1. 让旧线写交接单（0.3.8 起可用 `line_handoff`）；
+1. 让旧线写交接单（0.3.7 起可用 `line_handoff`）；
 2. 管理线调用 `line_create({ label, replace: true, force: true, reason: "context full" })`；
 3. 插件创建干净 Session、同 label 原子切换，旧 Session 标记 retired 但保留；
 4. queued/claimed 消息迁移到新线；delivered/acked 留在旧 Session，不重投。
@@ -176,6 +203,7 @@ dsh-agent-lines list
 dsh-agent-lines send --from frontend-line --to backend-line --text "hi"
 dsh-agent-lines inbox --line backend-line
 dsh-agent-lines ack --line backend-line --id msg_...
+dsh-agent-lines --json observe --line writer --limit 20
 dsh-agent-lines claim --agent agent-demo --line manager --session "$DSH_SESSION_ID"
 dsh-agent-lines doctor
 ```

package/bin/dsh-agent-lines.js

@@ -9,6 +9,7 @@ import { LineError, lineId } from '../lib/protocol.js'
 
 function usage() {
   console.error(`Usage:
+  dsh-agent-lines [--db <path>] [--json] observe [--line <line>] [--since <epochMs>] [--limit N] [--agent <id>]
   dsh-agent-lines [--db <path>] [--json] list
   dsh-agent-lines [--db <path>] [--json] send --from <line> --to <line|agent#line> --text <text> [--agent <id>] [--key <key>] [--reply-to <id>]
   dsh-agent-lines [--db <path>] [--json] inbox --line <line> [--agent <id>] [--limit N] [--all]
@@ -62,6 +63,16 @@ function main() {
   }
   const store = new LineStore(opts.db)
   try {
+    if (command === 'observe') {
+      const result = store.observe({
+        agentId: String(opts.agent ?? 'agent-deepseek'),
+        line: opts.line === undefined ? null : String(opts.line),
+        since: Number(opts.since ?? 0),
+        limit: Number(opts.limit ?? 100),
+      })
+      print({ db: store.dbPath, ...result }, opts.json)
+      return 0
+    }
     if (command === 'list') {
       print({ db: store.dbPath, lines: store.listLines(), counts: store.counts() }, opts.json)
       return 0
@@ -152,4 +163,4 @@ function main() {
   }
 }
 
-process.exitCode = main()
+process.exitCode = main()

package/docs/PROTOCOL.en.md

@@ -103,6 +103,7 @@ The new line is an ordinary DSH Session in the same DSH process; no OS process,
     line_retire({ line, reason? })
     line_rebind({ line, sessionId, migrate?: "queued" | "none", reason? })
     line_create({ label, replace: true, force?, migrate?, title?, reason? })
+    line_observe({ line?, since?, limit? })
     line_handoff({ line, format?: "md" | "json", limit?: number })
     line_rename({ line, title })
 
@@ -112,6 +113,7 @@ The new line is an ordinary DSH Session in the same DSH process; no OS process,
 - migrate=none: returns LINE_BACKLOG_NOT_EMPTY if the backlog is non-empty.
 - replace: creates a fresh Session for the same label and rebinds; an active line requires force + reason.
 - line_events records title/retire/rebind audit; titles survive restarts.
+- line_observe is a manager-only read-only cross-line feed; it does not inject prompts or change state.
 
 ## Echo and reply depth
 

package/docs/PROTOCOL.md

@@ -95,6 +95,7 @@ line_move_workspace({ line, workspace }) 把已有线 Session 挂到已有工作
     line_retire({ line, reason? })
     line_rebind({ line, sessionId, migrate?: "queued" | "none", reason? })
     line_create({ label, replace: true, force?, migrate?, title?, reason? })
+    line_observe({ line?, since?, limit? })
     line_handoff({ line, format?: "md" | "json", limit?: number })
     line_rename({ line, title })
 
@@ -104,6 +105,7 @@ line_move_workspace({ line, workspace }) 把已有线 Session 挂到已有工作
 - migrate=none：backlog 非空时返回 LINE_BACKLOG_NOT_EMPTY。
 - replace：同 label 创建新 Session 并 rebind；active 线需 force + reason。
 - line_events 记录 title/retire/rebind 审计；title 持久化，重启保留。
+- line_observe 仅管理线、只读跨线 feed；不注入 prompt、不改消息状态。
 
 ## 回声与回复深度
 

package/docs/en/index.html

@@ -43,7 +43,7 @@ footer{padding:34px 0 48px;color:var(--muted);font-size:12px}
 <div class="wrap">
 <header>
   <a class="brand" href="../"><span class="mark"></span>dsh-agent-lines</a>
-  <nav><a href="../">中文</a><a href="https://github.com/Lencen/dsh-agent-lines">GitHub</a><a href="https://github.com/Lencen/dsh-agent-lines/releases/tag/v0.3.8">Release</a></nav>
+  <nav><a href="../">中文</a><a href="https://github.com/Lencen/dsh-agent-lines">GitHub</a><a href="https://github.com/Lencen/dsh-agent-lines/releases/tag/v0.3.9">Release</a></nav>
 </header>
 <main>
 <section class="hero" style="border:0;padding-bottom:22px">
@@ -54,7 +54,7 @@ footer{padding:34px 0 48px;color:var(--muted);font-size:12px}
     <div class="install">curl -fsSL https://raw.githubusercontent.com/Lencen/dsh-agent-lines/main/install.sh -o install.sh &amp;&amp; bash install.sh</div>
     <div class="actions">
       <a class="btn primary" href="https://github.com/Lencen/dsh-agent-lines">GitHub repository</a>
-      <a class="btn" href="https://github.com/Lencen/dsh-agent-lines/releases/tag/v0.3.8">Download 0.3.8</a>
+      <a class="btn" href="https://github.com/Lencen/dsh-agent-lines/releases/tag/v0.3.9">Download 0.3.9</a>
     </div>
   </div>
   <div class="shot">
@@ -92,7 +92,7 @@ research (调研), architecture (架构), uiux (UIUX), dev (开发), test (测
 After the team is ready, wait for my first task. Do not start by yourself.</pre>
   <p style="color:var(--muted);font-size:14px">Restart DSH Web after install or update. Technical details, protocol, and limits: <a href="https://github.com/Lencen/dsh-agent-lines">README / architecture</a>. Community plugin, not an official DeepSeek product.</p>
 </section>
-<footer>dsh-agent-lines 0.3.8 · Apache-2.0 · Community plugin for DeepSeek Harness. Not an official DeepSeek product.</footer>
+<footer>dsh-agent-lines 0.3.9 · Apache-2.0 · Community plugin for DeepSeek Harness. Not an official DeepSeek product.</footer>
 </main>
 </div>
 </body>

package/docs/index.html

@@ -43,7 +43,7 @@ footer{padding:34px 0 48px;color:var(--muted);font-size:12px}
 <div class="wrap">
 <header>
   <a class="brand" href="./"><span class="mark"></span>dsh-agent-lines</a>
-  <nav><a href="en/index.html">English</a><a href="https://github.com/Lencen/dsh-agent-lines">GitHub</a><a href="https://github.com/Lencen/dsh-agent-lines/releases/tag/v0.3.8">Release</a></nav>
+  <nav><a href="en/index.html">English</a><a href="https://github.com/Lencen/dsh-agent-lines">GitHub</a><a href="https://github.com/Lencen/dsh-agent-lines/releases/tag/v0.3.9">Release</a></nav>
 </header>
 <main>
 <section class="hero" style="border:0;padding-bottom:22px">
@@ -54,7 +54,7 @@ footer{padding:34px 0 48px;color:var(--muted);font-size:12px}
     <div class="install">curl -fsSL https://raw.githubusercontent.com/Lencen/dsh-agent-lines/main/install.sh -o install.sh &amp;&amp; bash install.sh</div>
     <div class="actions">
       <a class="btn primary" href="https://github.com/Lencen/dsh-agent-lines">GitHub 仓库</a>
-      <a class="btn" href="https://github.com/Lencen/dsh-agent-lines/releases/tag/v0.3.8">下载 0.3.8</a>
+      <a class="btn" href="https://github.com/Lencen/dsh-agent-lines/releases/tag/v0.3.9">下载 0.3.9</a>
     </div>
   </div>
   <div class="shot">
@@ -92,7 +92,7 @@ research（调研）、architecture（架构）、uiux（UIUX）、dev（开发
 团队建好后先待命，不要自动开工，等我发第一个任务。</pre>
   <p style="color:var(--muted);font-size:14px">安装或更新后需要重启 DSH Web。技术细节、协议和限制见 <a href="https://github.com/Lencen/dsh-agent-lines">README / 架构文档</a>。社区插件，不是 DeepSeek 官方产品。</p>
 </section>
-<footer>dsh-agent-lines 0.3.8 · Apache-2.0 · Community plugin for DeepSeek Harness. Not an official DeepSeek product.</footer>
+<footer>dsh-agent-lines 0.3.9 · Apache-2.0 · Community plugin for DeepSeek Harness. Not an official DeepSeek product.</footer>
 </main>
 </div>
 </body>

package/docs/market-index.json

@@ -50,11 +50,11 @@
         ]
       },
       "dist-tags": {
-        "latest": "0.3.8"
+        "latest": "0.3.9"
       },
       "versions": [
         {
-          "version": "0.3.8",
+          "version": "0.3.9",
           "publishTimestamp": 1793771000,
           "source": {
             "type": "npm"

package/examples/market-index.json

@@ -50,11 +50,11 @@
         ]
       },
       "dist-tags": {
-        "latest": "0.3.8"
+        "latest": "0.3.9"
       },
       "versions": [
         {
-          "version": "0.3.8",
+          "version": "0.3.9",
           "publishTimestamp": 1793771000,
           "source": {
             "type": "npm"

package/lib/store.js

@@ -542,6 +542,38 @@ export class LineStore {
     return this.#stmt('SELECT * FROM line_events WHERE line_id = ? AND action = ? ORDER BY created_at DESC LIMIT 1').get(id, action)
   }
 
+  /** Read-only cross-line feed for the manager; no state changes. */
+  observe({ agentId, line = null, since = 0, limit = 100 } = {}) {
+    const n = Math.min(200, Math.max(1, Number(limit) || 100))
+    const from = Math.max(0, Number(since) || 0)
+    const params = [agentId, agentId]
+    let sql = `SELECT id, from_agent, from_line, to_agent, to_line, body, state, reply_to, root_message_id,
+      hop, no_reply, created_at, delivered_at, acked_at
+      FROM messages WHERE (from_agent = ? OR to_agent = ?) AND from_line != to_line AND created_at > ?`
+    params.push(from)
+    if (line !== null && String(line).trim() !== '') {
+      sql += ' AND (from_line = ? OR to_line = ?)'
+      params.push(String(line), String(line))
+    }
+    sql += ' ORDER BY created_at DESC LIMIT ?'
+    params.push(n)
+    const rows = this.#stmt(sql).all(...params)
+    return {
+      agentId, line: line === null ? null : String(line), since: from, count: rows.length,
+      messages: rows.map(row => ({
+        id: row.id,
+        from: row.from_agent + '#' + row.from_line,
+        to: row.to_agent + '#' + row.to_line,
+        state: row.state,
+        noReply: Number(row.no_reply) === 1,
+        replyTo: row.reply_to,
+        hop: row.hop,
+        createdAt: row.created_at,
+        summary: String(row.body || '').replace(/\s+/g, ' ').slice(0, 240),
+      })),
+    }
+  }
+
   /** Structured handoff snapshot: counts + recent messages + lifecycle events. */
   handoff({ agentId, line, limit = 20, now = Date.now() }) {
     const row = this.getLine(agentId, line, now)

package/lib/tools.js

@@ -398,6 +398,30 @@ export function registerToolsForAgent(agent, def, { config, store, lineDefs, cre
       },
     }))
 
+    disposers.push(agent.ctx.tools.register({
+      name: 'line_observe',
+      description: 'Manager-only read-only feed of recent cross-line messages (from/to, state, noReply, summary). Does not inject prompts or change any message state. Use it to watch team traffic without turning every message into a manager turn.',
+      parameters: {
+        type: 'object', additionalProperties: false,
+        properties: {
+          line: { type: 'string', description: 'Optional line filter (matches from or to)' },
+          since: { type: 'number', description: 'Only messages created after this epoch ms' },
+          limit: { type: 'number', description: 'Maximum messages, 1-200 (default 100)' },
+        },
+      },
+      output: OUTPUT,
+      execute: async (args, exec) => {
+        const caller = currentLine(exec, lineDefs)
+        if (caller.label !== config.createFrom) throw new LineError('LINE_CREATE_FORBIDDEN', `Only ${config.createFrom} may observe lines`, { caller: caller.label })
+        return store.observe({
+          agentId: config.agentId,
+          line: args.line === undefined ? null : String(args.line),
+          since: Number(args.since) || 0,
+          limit: limitValue(args.limit, 100, 200),
+        })
+      },
+    }))
+
     disposers.push(agent.ctx.tools.register({
       name: 'line_handoff',
       description: 'Generate a structured handoff snapshot for a line: current metadata, backlog counts, recent messages, lifecycle events. Does not call a model; write the returned markdown to a file before retire/replace/rebind.',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-agent-lines",
-  "version": "0.3.8",
+  "version": "0.3.9",
   "description": "DSH Agent 的持久、可寻址消息线（社区插件）。",
   "type": "module",
   "license": "Apache-2.0",