dsh-agent-lines 0.0.0-stage → 0.3.0

package/README.md

@@ -1,3 +1,311 @@
-# 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 agent 的 super agent 平替插件。给 DSH agent 线（line）用的、可寻址的持久消息层。一条线是一个普通 DSH Session 加一个稳定 label；一个 DSH 进程可以承载多条线，管理线还可以通过 `line_create` 在对话里创建新线。
+
+## 什么时候用
+
+如果所有 worker 都是同一个 DSH 进程里、同一个父 Agent 的子任务，**优先用内置 subagent / Agent Teams**；更简单，不需要插件。
+
+需要下面这些时再用 **dsh-agent-lines**：
+
+- 线要能按 `agent#line` 寻址；
+- 线是独立 DSH Session，有自己的上下文和生命周期；
+- 收件箱要能跨接收方重启存活；
+- 同机多个 DSH 进程共享一个线数据库；
+- 管理线通过自然语言让模型创建 worker 线。
+
+插件只做传输 + 轻量建线，不做任务编排。**交接（handover）没有实现**。
+
+## 传输
+
+`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 会被拒绝）
+
+## 安装
+
+```bash
+dsh plugin --profile <profile> add dsh-agent-lines@0.3.0
+```
+
+包尚未发布时，用本地 tarball 安装：
+
+```bash
+dsh plugin --profile <profile> add ./dsh-agent-lines-0.3.0.tgz
+```
+
+不知道 `<profile>` 是什么，可以直接用一键脚本（自动选 `web`，没有 web 时选唯一 profile）：
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Lencen/dsh-agent-lines/main/install.sh -o install.sh
+bash install.sh
+# npm 未发布时：bash install.sh ./dsh-agent-lines-0.3.0.tgz
+```
+
+手动安装时，`<profile>` 是 **DSH profile 名**（对应 `~/.dsh/profiles/<profile>`），不是线名，也不是 agent 名。
+
+- 已有 profile：先 `ls ~/.dsh/profiles`，填实际目录名，例如 `web`、`headless`；
+- 想隔离安装：用新名字，例如 `agent-lines`，命令会自动初始化：
+
+```bash
+dsh plugin --profile agent-lines add dsh-agent-lines@0.3.0
+```
+
+不要把 `manager-line`、`research` 这类线名填进 `--profile`。
+
+### 管理线配置
+
+```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`。
+
+### Worker profile
+
+```yaml
+- id: agent-lines
+  name: dsh-agent-lines
+  config:
+    agentId: agent-demo
+    dbPath: /home/me/.dsh/agent-lines/lines.db
+    lines:
+      - label: frontend-line
+        sessionId: session-lines-frontend
+        role: 前端
+```
+
+旧的单线写法 `line: frontend-line` + `sessionId: ...` 仍然兼容。
+
+## 快速开始
+
+1. 安装：<code>dsh plugin --profile &lt;profile&gt; add dsh-agent-lines@0.3.0</code>，或用本地 tarball（见“安装”）。
+2. 配置一条管理线：<code>allowCreate: true</code>、<code>allowClaim: true</code>、<code>createFrom: manager-line</code>。
+3. 启动 profile，打开任意根 Session。
+4. 先调用 <code>line_status</code>。如果当前会话未绑定，调用 <code>line_claim_manager({ confirm: "bind-manager" })</code>；CLI 兜底：
+   ~~~bash
+   dsh-agent-lines claim --agent agent-demo --line manager-line --session "$DSH_SESSION_ID"
+   ~~~
+5. 对管理线说：“创建 frontend-line、backend-line、ops-line，然后分别发一条 hello。”
+6. worker 可以是独立 profile（共享同一个 <code>dbPath</code>），也可以是管理线进程内创建的线。
+
+任何新会话先看 <code>line_status</code>：它会告诉你是否绑定、manager 是谁、下一步怎么修。
+
+## 首次使用：组建开发团队
+
+在新根会话里直接复制下面这段。它会先绑定管理线，再创建一支团队；后续任务再单独发，不要让它自己开工。
+
+> 使用 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；不含内部数据。
+
+
+## 场景：一个管理线 + 多条执行线
+
+只要 profile 里有管理线配置，Session 不必预先绑定。打开任意根 Session，直接说：
+
+> 你是管理线。先用 line_claim_manager 把自己绑定为管理线，然后负责任务拆分与调度。需要建几个任务执行线，由你安排分配任务；你负责协调执行线中的工作内容、裁决纠纷、回收任务结果、汇总、总结、汇报。
+
+接下来会发生：
+
+1. 管理线调用 <code>line_create</code> 创建前端线、后端线、运维线、数据线，再用 <code>line_list</code> 确认。
+2. 用户给一个具体任务，例如：“给报表页加 CSV 导出，带测试和一页 runbook。”
+3. 管理线拆解后，用 <code>line_send</code> 发给对应执行线；消息落 SQLite。
+4. 执行线用 <code>line_inbox</code> 收任务、执行、<code>line_ack</code> 确认，需要时用 <code>line_send</code> 回复。
+5. 管理线收集结果；如果前端和后端对接口结构有分歧，管理线裁决并统一口径。
+6. 管理线汇总、总结、汇报；各执行线保留自己的上下文和消息历史。
+
+这是一个“提示词组织模式”，不是插件内置的组织架构：怎么拆任务由管理线模型决定。插件提供的是持久传输和硬约束：
+
+- <code>maxLines</code> 限制建线数量；
+- <code>noReply</code>、<code>maxReplyDepth</code> 和默认 self-send 禁止，防止自动回声；
+- <code>line_status</code> 诊断 manager 绑定；
+- 一个 Session 只能有一个 writer。
+
+如果管理线没绑定，<code>line_status</code> 会给出修复命令；先调用 <code>line_claim_manager</code>（或 CLI）再跑这个场景。
+
+## 使用
+
+管理线可以完全由对话驱动：
+
+> 你是管理线。用 `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` 指向插件同一个数据库。
+
+## 工作区
+
+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 不开网络监听。