dsh-agent-lines 0.0.0-stage → 0.3.1

package/README.md

@@ -1,3 +1,261 @@
-# Temporary Holding Version
+# dsh-agent-lines
 
-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.
+[English](README.en.md) | 中文
+
+> DeepSeek Harness 社区插件，不是 DeepSeek 官方产品。
+
+> **100% Vibe Coding。** 架构、代码、测试、文档都在 AI agent 会话中完成。它是实验性项目：生产使用前请审阅代码并跑一遍集成测试。
+
+DSH 的 super agent 平替插件。
+
+你不用每次新开会话、手动把背景复制给几个 agent。让一个负责人 agent 带一支长期协作的团队：每个成员有名字、各负责一块，任务和消息不会丢，结果由负责人汇总给你。
+
+## 什么时候用
+
+如果你遇到这些情况，再考虑安装：
+
+- 你有一个长期项目，不想每次都从头解释背景；
+- 你希望几个 agent 长期分工，比如调研、架构、开发、测试、发布、运维；
+- 你需要给每个角色一个固定名字，能直接点名派任务；
+- 任务做到一半关掉窗口、重启 DSH，消息和上下文还要在；
+- 你希望一个负责人 agent 自己拆任务、建团队、追进度、收结果，最后向你汇报。
+
+如果只是同一次会话里的临时子任务，直接用 DSH 内置的 subagent / Agent Teams，不需要这个插件。
+
+## 安装
+
+一条命令安装（推荐，不需要自己找 profile）：
+
+    curl -fsSL https://raw.githubusercontent.com/Lencen/dsh-agent-lines/main/install.sh -o install.sh
+    bash install.sh
+
+脚本会自动选择 DSH Web 使用的 profile，安装后检查 agent-lines 是否可用；如果判断不了，会列出已有配置并提示你怎么指定。
+
+离线或 npm 不可用时，用本地 tarball：
+
+    bash install.sh ./dsh-agent-lines-0.3.1.tgz
+
+安装完成后，脚本会打印管理线配置文件的路径。把下面“管理线配置”整段粘贴进去一次即可。
+
+### 管理线配置
+
+```yaml
+- id: agent-lines
+  name: dsh-agent-lines
+  config:
+    agentId: agent-demo
+    dbPath: /home/me/.dsh/agent-lines/lines.db
+    allowCreate: true
+    allowClaim: true
+    allowSelfSend: false
+    dedupeWindowMs: 5000
+    maxReplyDepth: 8
+    createFrom: manager-line
+    maxLines: 16
+    childPreset: standard
+    lines:
+      - label: manager-line
+        sessionId: session-lines-manager
+        role: 任务对接、拆解与调度
+```
+
+只有 `createFrom` 指定的线能调用 `line_create`。worker profile 不要开 `allowCreate`。
+
+## 快速开始
+
+1. 运行上面的安装脚本。
+2. 按脚本提示打开配置文件，把“管理线配置”整段粘贴进去（只做一次）。
+3. 启动 DSH Web，打开任意根会话。
+4. 先调用 line_status；如果当前会话未绑定，调用 line_claim_manager({ confirm: "bind-manager" })。
+5. 直接说“按首次使用创建团队”，然后等它建好成员线；第一个任务再单独发。
+
+## 首次使用：组建开发团队
+
+在新根会话里直接复制下面这段。它会先绑定管理线，再创建一支团队；后续任务再单独发，不要让它自己开工。
+
+> 使用 dsh-agent-lines。如果当前会话尚未绑定，先调用 line_claim_manager，confirm 用 "bind-manager"。
+>
+> 你是开发团队负责人：负责任务拆解与分配、协调团队沟通、跟踪成员工作状态与进度、汇总工作结果、总结并汇报。你只做管理和协调，不执行具体开发任务。
+>
+> 请用 line_create 创建成员线，label 用英文，role 用中文：research（调研）、architecture（架构）、uiux（UIUX）、dev（开发）、test（测试）、acceptance（验收）、release（发布）、ops（运维）。
+>
+> 创建后用 line_list 确认，然后待命，等我发第一个任务；不要自行开始具体工作。
+
+label 必须是 ASCII 标识符；中文放在 role 里，不要用中文 label。这个提示词只创建一个团队；0.3 不支持同一插件实例同时多个团队。
+
+可直接复制的调用（由管理线 Session 执行）：
+
+~~~js
+line_create({ label: "research", role: "调研" })
+line_create({ label: "architecture", role: "架构" })
+line_create({ label: "uiux", role: "UIUX" })
+line_create({ label: "dev", role: "开发" })
+line_create({ label: "test", role: "测试" })
+line_create({ label: "acceptance", role: "验收" })
+line_create({ label: "release", role: "发布" })
+line_create({ label: "ops", role: "运维" })
+~~~
+
+创建后用 line_list 确认。
+
+![首次使用：绑定管理线、创建 8 条成员线、line_list 确认](docs/assets/first-use.gif)
+
+真实 DSH Web 演示 profile、通用 label；不含内部数据。
+
+## 场景：一个管理线 + 多条执行线
+
+负责人先建好团队，后面才是具体任务。
+
+1. 负责人按角色建立成员：调研、架构、UIUX、开发、测试、验收、发布、运维。
+2. 你给负责人一个具体任务，例如“给报表页加 CSV 导出，带测试和一页 runbook”。
+3. 负责人把任务拆开，派给对应的成员；每条消息都会留在本地。
+4. 成员收到任务、执行、确认收到，需要时回复负责人。
+5. 负责人收集结果，处理成员之间的分歧，统一口径。
+6. 你看到负责人的汇总；每个成员保留自己的上下文和消息记录。
+
+这只是“用提示词组织团队”的方式，不是插件内置的组织架构；怎么拆任务由负责人模型决定。技术细节（消息、状态、工具）在下面的“使用”和“投递语义”。
+
+## 使用
+
+管理线可以完全由对话驱动：
+
+> 你是管理线。用 `line_create` 创建 frontend-line、backend-line、ops-line，然后用 `line_list` 确认。
+
+工具：
+
+| 工具 | 作用 |
+|---|---|
+| `line_status` | 只读：当前会话绑定、manager Session 是否存在/live、线列表、修复命令；未绑定也可见 |
+| `line_claim_manager` | 把当前 live 根 Session 绑成 manager；需要 `allowClaim: true` 和 `confirm: "bind-manager"`；全局工具，不需要 shell |
+| `line_list` | 列出线、状态、未读数、当前线和 role |
+| `line_create` | 仅管理线：在管理线工作区（或指定的已有工作区）创建 DSH Session 并注册为线；同 label 幂等 |
+| `line_move_workspace` | 仅管理线：把已有线的 Session 挂到路径完全匹配的工作区 |
+| `line_send` | 发到 `line` 或 `agent#line`；可选 `idempotencyKey`、`replyTo`、`noReply`、`forceDistinct`、`ttlMs` |
+| `line_inbox` | 读当前线已投递消息 |
+| `line_ack` | 确认已处理 |
+
+除 `line_status`、`line_claim_manager` 外，line 工具只注册在已绑定线的 Session 上；这两个控制工具是全局的：status 只读，claim 仅限根会话且受 allowClaim 控制。
+
+`line_create` 在管理线所属工作区（没有工作区时回退当前目录）创建普通 DSH Session；它**不会**创建独立 OS 进程、profile 或端口，也不转移已有 Session。
+
+创建的线会记录 `created_by`，进程重启时由管理线恢复。line_create 会解析管理线所属工作区并传 workspaceId（DSH 会自动 attach），所以新线出现在该工作区而不是“未分组”；如果管理线本身不在工作区，则回退 cwd，线保持未分组。传 `workspace`（已有路径或 id）可指定其他工作区。若某条线的 Session 还从未落盘，首次投递可能 `session/not-found`；给它发一条任务（或重新创建）即可让它持久化。
+
+CLI：
+
+```bash
+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 claim --agent agent-demo --line manager --session "$DSH_SESSION_ID"
+dsh-agent-lines doctor
+```
+
+用 `--db` 或 `DSH_AGENT_LINES_DB` 指向插件同一个数据库。
+
+## 传输
+
+`transport` 默认 `sqlite`（local-first），也是 0.3 唯一发布的 transport；安装插件不需要 Postgres 或 Python 服务。
+
+## 架构
+
+~~~mermaid
+flowchart LR
+  U[用户] --> M[管理线 DSH Session]
+  M -->|line_create / line_send| P[dsh-agent-lines]
+  P --> Q[(SQLite lines.db)]
+  P -->|prompt requestId| W1[前端线 Session]
+  P -->|prompt requestId| W2[后端线 Session]
+  W1 -->|line_inbox / line_ack| P
+  W2 -->|line_inbox / line_ack| P
+~~~
+
+DSH 适配层负责线身份和“把消息送进 Session”；transport 负责持久消息和跨进程存储。默认是本地 SQLite。公开架构说明：[English](docs/ARCHITECTURE.en.md) | [中文](docs/ARCHITECTURE.md)。
+
+## 要求
+
+- DSH `>=0.2.1-rc.5 <0.3.0`
+- Node.js `^22.19.0 || >=24.0.0`
+- 本地文件系统（NFS/CIFS/SMB/FUSE 会被拒绝）
+
+## 工作区
+
+DSH 侧边栏按 workspace 的 sessionIds 成员表分组，不是按 cwd。line_create 通过 workspaceRegistry.resolveByPath 找到管理线所属工作区，传 workspaceId，DSH 会在创建时 attachSession，新线就不会落到“未分组”。如果管理线没有 workspace，插件回退 cwd，线仍未分组。
+
+line_move_workspace 把已有线挂到目标 workspace。DSH 只在 Session cwd 与 workspace path 完全一致时允许 attach；否则插件返回 WORKSPACE_ATTACH_FAILED。它不能把 Session 迁移到不同目录（那需要新 Session/交接）。
+
+## manager 绑定与 claim
+
+manager 是一条真实的 DSH Session。你打开另一个会话时，它不是 manager，line 工具会刻意不出现；先调用 `line_status` 看当前绑定和修复命令。
+
+根会话可以直接在对话里绑自己，不需要 shell：
+
+```json
+line_claim_manager({ "confirm": "bind-manager" })
+```
+
+插件会校验调用者是 live 根会话、释放旧 manager 租约、重绑 manager，并把选择写入 `manager_bindings`。不需要改 profile，也不需要重启；需要 `allowClaim: true`。
+
+运维仍可用 CLI 兜底：
+
+```bash
+dsh-agent-lines claim --agent agent-demo --line manager --session "$DSH_SESSION_ID"
+```
+
+claim 不会对每个新会话自动执行：需要用户明确要求，或运维显式调用。
+
+## 回声与重复保护
+
+- 同 `idempotencyKey` 返回已有消息。
+- 不传 key 时，同一 `dedupeWindowMs`（默认 5 秒）内的相同发送合并为一条；要故意发两条相同正文用 `forceDistinct: true`。
+- `replyTo` 会让 `hop` 递增；超过 `maxReplyDepth`（默认 8）返回 `LINE_REPLY_DEPTH_EXCEEDED`。
+- `noReply: true` 的消息不能被回复；尝试回复返回 `LINE_NO_REPLY`。
+- 默认禁止自己发自己（`LINE_SELF_SEND_FORBIDDEN`）；确需给自己留笔记时设 `allowSelfSend: true`。
+
+这是传输层保护，不保证两个 agent 不会主动继续聊天；用 `noReply` 和 reply depth 约束。
+
+## 投递语义
+
+`queued → claimed → delivered → acked`
+
+- `delivered`：目标 DSH Session 已接受 prompt。
+- `acked`：agent 显式调用 `line_ack`。
+- **至少一次**；靠 DSH 的 `requestId` 幂等让重试在 Session 日志里“有效一次”。不是分布式 exactly-once。
+- 接收方离线时消息留在队列；0.3 不自动拉起进程。
+- **一个 Session 只能有一个 writer。** 不要在另一个 DSH 进程（例如主 Web UI）里打开某条线的 Session；否则会 `session/writer-held`。关掉另一个视图，或给线独立 Session。
+
+## 安全
+
+- 插件在 DSH Host 进程内运行，拥有主机权限；只安装可信包。
+- 0.3 默认本地 SQLite，不开网络监听。
+- 只有 `createFrom` 管理线能建线；`maxLines` 限制增长。
+- 对端消息在 prompt 里明确标为 peer content，不是用户指令。
+- 详见 [docs/SECURITY.md](docs/SECURITY.md)。
+
+## 限制
+
+- 不做交接；不能把 Session 迁移到不同目录。
+- 多线是同进程多 Session，不是进程隔离。
+- 一个插件实例只支持一个 manager/团队；同一个 DSH 进程里同时跑开发、小说等多个团队不支持；独立 profile/DB 只是临时 workaround，不是产品模型。
+- 没有 `line_delete`；建线会产生持久行，测试也会留下真实记录。
+- 空白线 Session 可能需要第一条任务后才落盘。
+- 一个 Session 只能有一个 writer；不要从另一个 DSH 进程打开线 Session。
+
+## 状态
+
+实验性 `0.3.x`。DSH 处于 developer preview，API 可能变化；请同时锁定 DSH 与插件版本。
+
+## 致谢
+
+- 人类 vibecoding：**Lencen**
+- 开发 agent：**DeepSeek Harness agent (DSH)**
+- 使用模型：**deepseek v4.1 flash 1017**
+- 邮箱：[iamlencen@qq.com](mailto:iamlencen@qq.com)
+
+## 贡献
+
+见 [CONTRIBUTING.md](CONTRIBUTING.md)；行为准则 [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)；文档站 [lencen.github.io/dsh-agent-lines](https://lencen.github.io/dsh-agent-lines/)。
+
+## 许可
+
+Apache-2.0，见 [LICENSE](LICENSE)。

package/SECURITY.en.md

@@ -0,0 +1,7 @@
+# Security
+
+English | [中文](SECURITY.md)
+
+See [docs/SECURITY.en.md](docs/SECURITY.en.md).
+
+dsh-agent-lines is a DSH Host plugin: it runs in-process with the permissions of the DSH process. Install only reviewed packages. Report vulnerabilities through the repository's private security advisory or a minimal GitHub issue without credentials or customer data.

package/SECURITY.md

@@ -0,0 +1,7 @@
+# 安全
+
+[English](SECURITY.en.md) | 中文
+
+详细安全说明见 [docs/SECURITY.md](docs/SECURITY.md)。
+
+dsh-agent-lines 是 DSH Host 插件：它在 DSH 进程内运行，拥有该进程的权限。只安装经过审阅的包。漏洞请通过仓库的 private security advisory 报告，或开一个不含凭据和客户数据的最小 issue。

package/bin/dsh-agent-lines.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+/**
+ * dsh-agent-lines CLI: inspect and drive the same SQLite queue the plugin uses.
+ * It does not start DSH or load any Session.
+ */
+import { existsSync } from 'node:fs'
+import { LineStore, defaultDbPath } from '../lib/store.js'
+import { LineError, lineId } from '../lib/protocol.js'
+
+function usage() {
+  console.error(`Usage:
+  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]
+  dsh-agent-lines [--db <path>] [--json] ack --line <line> --id <messageId> [--agent <id>]
+  dsh-agent-lines [--db <path>] [--json] claim --line <line> --session <sessionId> [--agent <id>]
+  dsh-agent-lines [--db <path>] [--json] doctor
+  dsh-agent-lines [--db <path>] [--json] tail --line <line> [--agent <id>]
+
+Environment: DSH_AGENT_LINES_DB overrides the default DB path.
+`)
+}
+
+function parse(argv) {
+  const opts = { json: false, db: process.env.DSH_AGENT_LINES_DB ?? defaultDbPath() }
+  const positional = []
+  const args = [...argv]
+  while (args.length > 0) {
+    const token = args.shift()
+    if (token === '--json') { opts.json = true; continue }
+    if (token === '--db') { opts.db = args.shift() ?? ''; continue }
+    if (token.startsWith('--db=')) { opts.db = token.slice(5); continue }
+    if (token === '--help' || token === '-h') { usage(); process.exit(0) }
+    if (token.startsWith('--')) {
+      const key = token.slice(2)
+      const next = args[0]
+      opts[key] = next === undefined || next.startsWith('--') ? true : args.shift()
+      continue
+    }
+    positional.push(token)
+  }
+  return { command: positional.shift(), rest: positional, opts }
+}
+
+function print(value, json) {
+  if (json) process.stdout.write(JSON.stringify(value, null, 2) + '\n')
+  else if (typeof value === 'string') process.stdout.write(value + '\n')
+  else process.stdout.write(JSON.stringify(value, null, 2) + '\n')
+}
+
+function need(value, name) {
+  if (value === undefined || String(value).trim() === '') throw new LineError('LINE_INVALID_ARGUMENT', `--${name} is required`)
+  return String(value)
+}
+
+function main() {
+  const { command, opts } = parse(process.argv.slice(2))
+  if (command === undefined) { usage(); return 2 }
+  if (!existsSync(opts.db) && command !== 'doctor') {
+    console.error(`[agent-lines] database not found: ${opts.db}`)
+    return 2
+  }
+  const store = new LineStore(opts.db)
+  try {
+    if (command === 'list') {
+      print({ db: store.dbPath, lines: store.listLines(), counts: store.counts() }, opts.json)
+      return 0
+    }
+    if (command === 'doctor') {
+      print({
+        db: store.dbPath,
+        exists: existsSync(store.dbPath),
+        counts: store.counts(),
+        lines: store.listLines(),
+      }, opts.json)
+      return 0
+    }
+    if (command === 'send') {
+      const from = need(opts.from, 'from')
+      const to = need(opts.to, 'to')
+      const text = need(opts.text, 'text')
+      const row = store.send({
+        agentId: String(opts.agent ?? 'agent-deepseek'),
+        fromLine: from,
+        to,
+        text,
+        idempotencyKey: opts.key,
+        replyTo: opts['reply-to'],
+      })
+      print({ id: row.id, from: `${row.from_agent}#${row.from_line}`, to: `${row.to_agent}#${row.to_line}`, state: row.state, deduplicated: row.deduplicated === true }, opts.json)
+      return 0
+    }
+    if (command === 'inbox') {
+      const line = need(opts.line, 'line')
+      const messages = store.inbox({
+        agentId: String(opts.agent ?? 'agent-deepseek'),
+        line,
+        limit: Number(opts.limit ?? 20),
+        includeAcked: opts.all === '' || opts.all === true,
+      })
+      print({ line, messages }, opts.json)
+      return 0
+    }
+    if (command === 'claim') {
+      const line = need(opts.line, 'line')
+      const sessionId = need(opts.session, 'session')
+      const agentId = String(opts.agent ?? 'agent-deepseek')
+      const claim = store.requestClaim({ agentId, lineId: lineId(agentId, line), sessionId })
+      print({
+        claimId: claim.id,
+        lineId: claim.line_id,
+        sessionId: claim.session_id,
+        state: claim.state,
+        reused: claim.reused === true,
+        note: 'The running plugin will claim this request; ensure allowClaim: true.',
+      }, opts.json)
+      return 0
+    }
+    if (command === 'ack') {
+      const line = need(opts.line, 'line')
+      const id = need(opts.id, 'id')
+      const row = store.markAck({ agentId: String(opts.agent ?? 'agent-deepseek'), line, messageId: id })
+      print({ id: row.id, state: row.state, acked: true, alreadyAcked: row.alreadyAcked === true }, opts.json)
+      return 0
+    }
+    if (command === 'tail') {
+      const line = need(opts.line, 'line')
+      const agentId = String(opts.agent ?? 'agent-deepseek')
+      let seen = new Set()
+      const tick = () => {
+        const messages = store.messagesForLine({ agentId, line, limit: 100 })
+        for (const row of messages) {
+          if (seen.has(row.id)) continue
+          seen.add(row.id)
+          print({ id: row.id, from: `${row.from_agent}#${row.from_line}`, state: row.state, text: row.body }, opts.json)
+        }
+      }
+      opts.keepOpen = true
+      tick()
+      setInterval(tick, 1000)
+      process.on('SIGINT', () => { store.close(); process.exit(0) })
+      return 0
+    }
+    console.error(`[agent-lines] unknown command: ${command}`)
+    usage()
+    return 2
+  } catch (error) {
+    console.error(`[agent-lines] ${error?.code ?? 'ERROR'}: ${error?.message ?? String(error)}`)
+    return error?.code === 'LINE_LEASE_HELD' ? 3 : 1
+  } finally {
+    if (opts.keepOpen !== true) store.close()
+  }
+}
+
+process.exitCode = main()

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+# dsh-agent-lines bundle layer: inserts the host plugin.
+# The profile supplies agentId, line, sessionId and dbPath (see README).
+- insert:
+    - id: agent-lines
+      name: dsh-agent-lines

package/docs/ARCHITECTURE.en.md

@@ -0,0 +1,68 @@
+# Architecture
+
+English | [中文](ARCHITECTURE.md)
+
+This is the public architecture overview. Version plans and release operations
+live outside this repository.
+
+## Layers
+
+DSH Host
+  -> dsh-agent-lines
+       LineService      identity, line definitions, manager binding, claim/status
+       DeliveryLoop     owner-process prompt delivery
+       Tools            line_status, line_claim_manager, line_list, line_create,
+                        line_move_workspace, line_send, line_inbox, line_ack
+       Transport SPI
+         SqliteTransport  current implementation; local SQLite/WAL
+
+The DSH adapter owns who the current Session is and how a message enters a DSH
+Session. The transport owns durable line and message storage.
+
+SQLite is the only transport shipped in 0.3. The Transport SPI exists so a
+future transport can implement the same contract without changing the adapter;
+external transports are not part of this release.
+
+## Delivery model
+
+- A line is an ordinary DSH Session with a stable label.
+- One Session has one writer. The process that owns the Session is the only one
+  allowed to prompt it.
+- Delivery uses the message id as the DSH requestId. A retry after a crash
+  returns the original acceptance, so the Session log does not gain a duplicate.
+- A lease elects the owner of a line; a stale claim is requeued after the claim
+  timeout.
+- delivered means the target Session accepted the prompt; acked means the agent
+  called line_ack.
+
+## Manager and claim
+
+- The manager line is configured by createFrom and must be a live root Session.
+- line_status is global and read-only. It reports current binding, manager
+  Session live/persisted, known lines, and a repair command.
+- line_claim_manager is a global tool gated by allowClaim; it requires an
+  explicit confirm and accepts only a live root that is not bound to a worker.
+  The CLI remains an operator fallback. The plugin validates the Session,
+  releases the old manager lease, rebinds, and persists the choice in
+  manager_bindings.
+- Claim is not an automatic action for every new Session.
+
+## Workspace
+
+- DSH groups Sessions by workspace membership (workspace.attachSession), not by
+  cwd.
+- line_create resolves the manager workspace and passes workspaceId, so the new
+  Session is attached to that workspace.
+- line_move_workspace attaches an existing line only when its Session cwd exactly
+  matches the target workspace path. It does not move a Session between
+  different directories.
+
+## Boundaries
+
+- line_create creates a root DSH Session, not a subagent.
+- No handover: no Session transfer, no route switch, no unread migration.
+- No process isolation: multiple lines may share one DSH process.
+- One manager/team per plugin instance; simultaneous teams are not supported.
+- One Session, one writer: do not open a line Session from another DSH process.
+- No line_delete: created lines are durable rows; testing creates real data.
+- No network listener in the default SQLite transport.

package/docs/ARCHITECTURE.md

@@ -0,0 +1,59 @@
+# 架构
+
+[English](ARCHITECTURE.en.md) | 中文
+
+这是公开架构说明。版本计划与发布操作放在本仓库之外。
+
+## 分层
+
+DSH Host
+  -> dsh-agent-lines
+       LineService      线身份、线定义、manager 绑定、claim/status
+       DeliveryLoop     owner-process prompt 投递
+       Tools            line_status、line_claim_manager、line_list、line_create、
+                        line_move_workspace、line_send、line_inbox、line_ack
+       Transport SPI
+         SqliteTransport  当前实现；本地 SQLite/WAL
+
+DSH 适配层负责“当前 Session 是谁”以及“消息如何进入 DSH Session”；transport
+负责线/消息的持久存储。
+
+0.3 只发布 SQLite transport。Transport SPI 只是为未来 transport 留接口；外部
+transport 不属于本版本。
+
+## 投递模型
+
+- 一条线是一个普通 DSH Session 加一个稳定 label。
+- 一个 Session 只能有一个 writer；只有持有该 Session 的进程可以 prompt 它。
+- 投递把消息 ID 作为 DSH requestId；崩溃后重试会返回原 acceptance，不会在
+  Session 日志里多插一条。
+- lease 选出线的 owner；超过 claim timeout 的 stale claim 会被重新排队。
+- delivered 表示目标 Session 接受了 prompt；acked 表示 agent 调用了 line_ack。
+
+## manager 与 claim
+
+- manager 线由 createFrom 指定，必须是 live 根 Session。
+- line_status 是全局只读工具，返回当前绑定、manager Session 是否 live/persisted、
+  已知线列表和修复命令。
+- line_claim_manager 是受 allowClaim 控制的全局工具，要求显式 confirm，且只接受
+  未绑定 worker 的 live 根 Session；CLI 仍是运维兜底。插件会校验 Session、释放旧
+  manager lease、重绑，并把选择持久化到 manager_bindings。
+- claim 不是每个新 Session 自动执行的动作。
+
+## 工作区
+
+- DSH 按 workspace 成员表（workspace.attachSession）分组，不是按 cwd。
+- line_create 解析 manager 所属 workspace 并传 workspaceId，新 Session 会挂到
+  该工作区。
+- line_move_workspace 只在已有 Session 的 cwd 与目标 workspace path 完全一致时
+  允许 attach；不能把 Session 迁移到不同目录。
+
+## 边界
+
+- line_create 创建的是根 DSH Session，不是 subagent。
+- 不做交接：不迁移 Session、不切换路由、不迁移未读。
+- 没有进程隔离：多条线可以共享一个 DSH 进程。
+- 一个插件实例只支持一个 manager/团队；不支持同时多个团队。
+- 一个 Session 只能有一个 writer；不要从另一个 DSH 进程打开线 Session。
+- 没有 line_delete：建线会留下持久行，测试也会留下真实数据。
+- 默认 SQLite transport 不开网络监听。

package/docs/DEPLOY.en.md

@@ -0,0 +1,91 @@
+# Deploy
+
+English | [中文](DEPLOY.md)
+
+## One process, one or more lines
+
+0.3 supports multiple lines in one DSH process, each bound to an ordinary DSH Session. A manager line with `allowCreate: true` and `createFrom` can create more lines with `line_create`; those lines live in the same DSH process and the manager's working directory.
+
+It is still valid to run one line per DSH process (0.1 style) and share a `dbPath` across processes:
+
+```text
+DSH process A (profile lines-a, port 3081, line frontend) ─┐
+DSH process B (profile lines-b, port 3082, line backend)  ─┼─ ~/.dsh/agent-lines/lines.db
+DSH process C (profile lines-c, port 3083, line asset)    ─┘
+```
+
+`line_create` does **not** spawn a process/profile/port. If you need process isolation or different working directories per line, provision each line as its own DSH profile/process instead.
+
+## Where to put the DB
+
+- Local disk only. NFS/CIFS/SMB/FUSE are refused at startup.
+- Default: `~/.dsh/agent-lines/lines.db`.
+- The directory is created `0700`; the DB is chmod `0600`.
+
+## Session ownership
+
+A DSH Session has one active writer. Never open a line's Session in another DSH process (for example, the main Web UI at 3080) while the line process is serving it. DSH will reject the plugin's prompt with `session/writer-held`, and the queued message will eventually fail after the retry budget.
+
+If you need to inspect a line's Session, use the line process's own Web UI (it is the writer), or stop the line process first. For production, give each line its own Session and do not browse that Session from another DSH instance.
+
+## Always-on lines
+
+A line only consumes messages while its DSH process is alive. For an always-on line, run the DSH web profile as a user service:
+
+```ini
+[Unit]
+Description=DSH web (agent line frontend)
+After=network.target
+
+[Service]
+Type=simple
+# Replace the path with the dsh binary of your installation.
+ExecStart=%h/.npm-global/bin/dsh --profile lines-a web --no-open --host 127.0.0.1 --port 3081
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+```
+
+If the process is down, messages stay `queued` and are delivered after restart. 0.3 does not start processes on demand.
+
+## Manager binding and claim
+
+If the configured manager Session is stale, a root Session can call:
+
+```json
+line_claim_manager({ "confirm": "bind-manager" })
+```
+
+The global tool checks that the Session is a live root, releases the old manager lease, rebinds the line, starts a new delivery loop, and persists the choice in `manager_bindings`. `allowClaim: true` must be set; no restart is required. The CLI fallback is:
+
+```bash
+dsh-agent-lines claim --agent agent-demo --line manager --session "$DSH_SESSION_ID"
+```
+
+If the configured manager Session is missing at startup, the plugin does not acquire it and does not report it online; `line_status` shows the missing state and the repair command.
+
+## Session id
+
+Configured lines need an existing `sessionId`; find it in the DSH session list/log, or use `dsh-agent-lines doctor` to inspect the queue. A wrong id fails permanently with `session/not-found` and the message moves to `failed`.
+
+`line_create` generates a new `session-<uuid>` in the manager workspace (or cwd fallback) and returns it. The new line is an ordinary DSH Session, not a subagent; it does not get its own OS process.
+
+Dynamic lines store `created_by`; a manager with `allowCreate` restores its created lines on startup and re-acquires their leases. If another process still owns a line, restore skips it. A blank Session that was never materialized may fail its first delivery; send a task or recreate it.
+
+## Upgrades
+
+1. Stop the DSH process (or let systemd restart it).
+2. `dsh plugin --profile <p> add dsh-agent-lines@<version>`.
+3. Restart.
+4. Run `dsh-agent-lines doctor` and check leases/lines.
+
+The SQLite schema is versioned with `PRAGMA user_version`; 0.3 is version 6 (adds `lines.role`, `lines.created_by`, `claim_requests`, `manager_bindings`, and message `hop`/`no_reply`/`root_message_id`). Existing version-1 databases are migrated in place on open. Back up `lines.db` before upgrading across minor versions.
+
+## Uninstall / rollback
+
+1. Remove the plugin entry from the profile patch and run `dsh plugin --profile <p> remove dsh-agent-lines`.
+2. Restart DSH.
+3. The DB is not deleted automatically. Move or delete `lines.db` only after you no longer need the queued messages.
+4. The plugin never modifies `~/.dsh/sessions`.