dsh-superagent-inbox 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek Harness Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,154 @@
-# Temporary Holding Version
+# dsh-superagent-inbox
 
-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.
+> 让 [DeepSeek Harness](https://www.deepseek.com/en/harness/) 上的 [dsh-superagent](https://github.com/deepseek-ai/dsh-superagent-prototype) **零外部依赖**跑起来：一个基于本地文件收件箱的 Source 插件。投放一条 JSON 消息，Super-agent 评估、建单、派出 Worker、把结果写回你的文件夹。
+
+本项目是 dsh-superagent（DeepSeek Harness 团队的 Super-agent 研究原型）的**扩展发行版**：在官方 bundle 之上新增了 `inbox` Source 插件（`./inbox-watch`），其余代码保持上游原样，MIT 许可，出处见文末。
+
+---
+
+## 1. 背景：这套东西解决什么问题
+
+DeepSeek Harness 团队在 2026-10-31 发布了文章 [《Super-agent 设计探索：迈向更自主的 Agent 系统》](https://mp.weixin.qq.com/s/zoS7GlReWPhfCjENGxXCdg)，并提出开源原型 dsh-superagent。其核心判断是：单任务 Coding Agent 已经可用，瓶颈转向**人的注意力**——一个人通常只能同时跟进 3–5 个活跃 Session。
+
+Super-agent 用四个特征回应：**连续**（跨信道只有一个 Agent）、**高效**（多任务并发）、**主动**（事件驱动）、**持久**（异常自愈）。支撑它的五个模块：
+
+| 模块 | 一句话 |
+|---|---|
+| 双层架构 | Router 层常驻路由（只分派、不执行），Worker 层上下文隔离并发执行 |
+| 事件驱动 | 环境事件即 Trigger；两级过滤（程序 Fast Path + 模型 Slow Path）、订阅直通、Inline & Spill、链式召回 |
+| 面向人的交互 | 异步 ReAct Loop；多信道带宽匹配（IM ≤100 词硬上限，只在需要人时说话） |
+| 存算分离 | Agent Loop 无状态化，Session 状态入库，执行环境留在原地（BYOM） |
+| Watchdog | 主系统外部的 Control Loop，既查基础设施也查任务实质进展 |
+
+官方原型内置 GitHub 与飞书两个 Source（事件来源），但都需要账号/机器人配置。**本项目新增的 `inbox` Source 补上"最后一公里"：任何有终端的人，用一个文件夹就能驱动整条 Trigger → Eval → Ticket → Worker → Channel 链路。**
+
+## 2. inbox 插件设计
+
+### 2.1 目录协议
+
+```text
+<root>/                      ← 面板里配置的收件箱根目录
+  ops/                       ← 一个"对话"（conversation）
+    in/                      ← 你把消息 JSON 投到这里
+      done/                  ← 已被 Agent 接收的消息（自动移入，相当于读取游标）
+    out/                     ← Agent 的回复 JSON 出现在这里
+  town/                      ← 另一个对话，可以有不同的接收策略
+```
+
+### 2.2 消息格式（投放 `in/*.json`）
+
+```json
+{
+  "id": "m-001",              // 必填，对话内唯一（重放安全：Trigger id 由 conversation+id 派生）
+  "from": "alice",            // 必填，发送者身份（进入 Policy 白名单判断）
+  "text": "把设置页的保存按钮文案改成「保存更改」",
+  "to": "agent",              // 可选：写 agent（或配置的 agentName）= 向智能体喊话 → 显式授权强度
+  "at": "2026-11-01T10:00:00+08:00",
+  "bot": false,               // 可选：true 标记为机器人/CI，永远不能自行授权工作
+  "thread": "m-000",          // 可选：所属话题的根消息 id（同话题后续消息直通 Worker）
+  "reply_to": "m-000",        // 可选：直接回复哪条消息（评估时展示上下文）
+  "url": "https://..."        // 可选：原文链接
+}
+```
+
+### 2.3 回复格式（出现在 `out/*.json`，文件名即消息 id，天然幂等）
+
+```json
+{
+  "id": "d402...c1",
+  "conversation": "ops",
+  "to": "m-001",
+  "thread": "m-001",
+  "reply_to": "m-001",
+  "from": "dsh-superagent",
+  "text": "已提交 <产物路径>，可验收。",
+  "at": "2026-11-01T10:12:33.000Z",
+  "ticket_id": "T-0001"
+}
+```
+
+### 2.4 与 Super-agent 领域模型的集成点
+
+| 领域概念 | inbox 的映射 |
+|---|---|
+| Trigger | 一个消息文件；id = `key('inbox', conversation, id)`，重放安全 |
+| Thread | `<conversation>:<根消息 id>`——同话题连续消息构成事件流，**订阅直通**由此生效 |
+| Actor / Policy | `from` 进白名单；`to: agent` 即显式喊话（explicit 强度）；bot 消息最多成为推断候选 |
+| Admission | 每个对话一行准入表：`mentions`（仅 @）或 `all`（全部消息） |
+| Channel | 回复写 `out/`，以消息 id 幂等（`wx` 标志），永不"永久失败" |
+| threadContext | 评估时读取该话题全部消息（含 Agent 回复，标记 bot），分页供链式召回 |
+| Worker 环境变量 | `DSH_SUPERAGENT_INBOX_CONVERSATION` 告诉 Worker 工单来自哪个对话 |
+
+安全模型沿用 dsh-superagent 的完整 Policy：不在白名单里的人、bot、CI **不能授权工作**；白名单 + 显式喊话才产生 explicit 工单；观察性工作（auto 模式的规则匹配）只在你启用并写明规则后发生。
+
+## 3. 安装（DeepSeek Harness）
+
+前置：DeepSeek Harness `dsh ^0.2.1-alpha.2`、Node `^22.19 || >=24`、pnpm。
+
+```bash
+git clone https://github.com/JHOpenDev/dsh-superagent-inbox.git
+cd dsh-superagent-inbox
+pnpm install && pnpm check      # typecheck + 全部测试 + 构建 lib/
+```
+
+1. 按 [SETUP.md](SETUP.md) 完成 dsh-superagent 的基础部署（仓库、GitHub 账号；GitHub 账号是 Worker 提交 PR 用的，若只跑 inbox 也可以配一个最小权限账号）。
+2. 在 profile 的 `cordis.patch.yml`（`$DSH_HOME/profiles/<profile>/`）中启用 inbox：
+
+```yaml
+- id: dsh-superagent
+  config:
+    stateDir: /home/me/.dsh/state/superagent
+- id: dsh-superagent-inbox
+  disabled: false
+```
+
+3. 重启 Harness，打开 **Superagent 侧边栏面板 → Sources → Local inbox**，配置：
+   - `root`：收件箱根目录（绝对路径）
+   - `conversations`：至少一个对话，如 `{ id: "ops", listen: "mentions" }`
+4. **Eval → On each Source → Local inbox**：把你自己（`from` 的值）加入 allowed 名单。
+
+## 4. 使用
+
+```bash
+# 1) 投放一条工作请求
+cat > $ROOT/ops/in/m-001.json <<'EOF'
+{ "id": "m-001", "from": "alice", "to": "agent",
+  "text": "把 README 的安装命令从 npm 改成 pnpm" }
+EOF
+
+# 2) 等 Router pass（秒级轮询）：面板会看到 Eval → accept → Ticket → Worker 运行
+# 3) 结果出现在回复目录
+cat $ROOT/ops/out/*.json
+# 4) 在同话题追问（thread: "m-001"）会直通该工单的 Worker，无需再 @
+```
+
+同话题后续消息（带 `thread` 字段）经**订阅直通**直达 Worker，不消耗 Router 判断；一段纯闲聊会被两级过滤安静丢弃（面板 Sources 页可见 `filtered` 审计）。
+
+## 5. 验证
+
+**单元与构建**：`pnpm check`（tsc + vitest + tsdown）1202/1204 通过；唯一失败项是上游 `environment.spec` 的 git 报错文案断言（本机 git 文案差异，未修改的上游基线同样失败）。新增 `tests/inbox.spec.ts` 7 项全绿。
+
+**真实运行时端到端**（DeepSeek Harness `dsh 0.2.1-rc.3`，专用 superagent profile）：
+
+```text
+收件箱投放 m-015 → Trigger 接收(移入 done/) → 评估接单(白名单+to:agent=explicit)
+→ 创建工单 → Worker 会话(bash/fs/gh 可用) → 修改 README → 提交分支
+→ PR #1 创建 → out/ 收到交付回复(≤100词, 附 PR 链接)
+```
+
+期间同样验证了：同 Thread 追问被评估按"同一请求已由工单承接"去重；显式停止指令经评估收回授权；
+纯闲聊被两级过滤安静丢弃（面板可见 filtered 审计）。
+
+**版本要求（重要）**：bundle 依赖的 `@deepseek-ai/dsh-*` 工具包必须与运行时 DSH 版本一致——
+加载器会禁用版本不匹配的预设插件行（症状：Worker 会话没有 bash/fs/gh 工具）。本仓库全部锁定
+`0.2.1-rc.3` 并把它们放进 `dependencies`；使用其他 DSH 版本时请同步调整。
+
+## 6. ZCode 适配器（adapters/zcode-plugin）
+
+同一套架构思想在 ZCode 上的移植（技能 + 斜杠命令实现：Router=主会话、Worker=后台子代理、订阅直通=SendMessage、Watchdog=巡检命令）。它不依赖本 bundle，安装方法见 [adapters/zcode-plugin/README.md](adapters/zcode-plugin/README.md)。两个实现的领域术语保持一致（Trigger/Thread/Ticket/Mandate/Watchdog），可作为"harness 无关的 Super-agent 架构"的对照样本。
+
+## 7. 出处与致谢
+
+- 架构与领域模型来自 DeepSeek Harness 团队的文章与实践：**《Super-agent 设计探索：迈向更自主的 Agent 系统》**（微信公众号「DeepSeek Harness 团队」，2026-10-31）与官方原型 [deepseek-ai/dsh-superagent-prototype](https://github.com/deepseek-ai/dsh-superagent-prototype)（MIT）。本仓库绝大部分代码属于他们——本项目的增量是 `src/sources/inbox.ts`、`tests/inbox.spec.ts`、bundle 接线与这份文档。
+- 遵循原型的哲学：**尽可能少占用人的注意力，尽可能多地交付价值。** inbox Source 默认只接收配置过的对话、只让白名单里的人发起工作、只在需要人行动或结果可交付时写 `out/`。
+- License: [MIT](LICENSE)（保留原许可与版权）。

package/cordis.patch.yml

@@ -0,0 +1,197 @@
+# dsh-superagent bundle layer: inserts the plugins without configuration, and the agent presets its Sessions run under. The
+# profile supplies the `dsh-superagent` entry's stateDir (see docs/006-deployment.md and examples/profile.cordis.patch.yml); the plugin
+# refuses to start without stateDir.
+- insert:
+    - id: dsh-superagent
+      name: dsh-superagent-inbox
+    - id: dsh-superagent-github
+      name: dsh-superagent-inbox/github-watch
+    # Optional Feishu Source; requires configuring a bot CLI after enabling.
+    - id: dsh-superagent-feishu
+      name: dsh-superagent-inbox/feishu-watch
+      disabled: true
+    # Optional local-inbox Source; point its root at a directory of message files after enabling.
+    - id: dsh-superagent-inbox
+      name: dsh-superagent-inbox/inbox-watch
+      disabled: true
+    # The agent preset of every Executor Session (WORKER_PRESET in src/app/sessions.ts); the main Session has its own, below.
+    # It is DSH's `standard` preset with only what a worker needs, and a shell whose foreground command moves to a background job
+    # after 5 seconds, so a long command does not hold back a person's message, which the Session takes at its next step. Left
+    # out: questions to a person, presenting, plan mode, the plugin manager and market, scheduling, goals, workflows, web fetch,
+    # and forked subagents, which would run under this preset; spawned subagents run under `standard`, whose shell moves a
+    # command to a background job only after 60 seconds, as a subagent's jobs are killed when it ends. A preset row has no
+    # setting that hides it from the preset picker, so its name and description say whom it is for.
+    - id: dsh-superagent-worker-preset
+      name: '@deepseek-ai/dsh-agent-preset'
+      config:
+        id: dsh-superagent-worker
+        name: dsh-superagent 执行器
+        description: dsh-superagent 的执行器 Session 专用，不供手动选择。前台命令超 5 秒转入后台，只含执行工作所需的工具。
+        order: 90
+        plugins:
+          - id: persona
+            name: '@deepseek-ai/dsh-persona'
+            config:
+              prefix: You are a coding agent powered by the {{model}} model.
+          - id: agent-instructions
+            name: '@deepseek-ai/dsh-agent-instructions'
+            config:
+              maxBytes: 65536
+          - id: time-context
+            name: '@deepseek-ai/dsh-time-context'
+          # A foreground command waits at most 5 s, then the shell tool moves it to a background job.
+          - id: shell
+            name: cordis:group
+            group: true
+            isolate:
+              shell: true
+            config:
+              - id: bash-sandbox
+                name: '@deepseek-ai/dsh-bash-sandbox'
+                disabled: !!js process.platform === 'win32'
+                config:
+                  timeoutMs: 5000
+                  maxTimeoutMs: 5000
+              - id: pwsh-sandbox
+                name: '@deepseek-ai/dsh-pwsh-sandbox'
+                disabled: !!js process.platform !== 'win32'
+                config:
+                  timeoutMs: 5000
+                  maxTimeoutMs: 5000
+              - id: tool-bash
+                name: '@deepseek-ai/dsh-tool-bash'
+                disabled: !!js process.platform === 'win32'
+              - id: tool-pwsh
+                name: '@deepseek-ai/dsh-tool-pwsh'
+                disabled: !!js process.platform !== 'win32'
+          - id: tool-fs
+            name: '@deepseek-ai/dsh-tool-fs'
+          - id: tool-fs-search
+            name: '@deepseek-ai/dsh-tool-fs-search'
+            config:
+              sampleOverCapGlobResults: false
+          # A wait for a job ends after 5 s too; the job's end wakes the worker with its result.
+          - id: tool-jobs
+            name: '@deepseek-ai/dsh-tool-jobs'
+            config:
+              waitTimeoutMs: 5000
+              maxWaitTimeoutMs: 5000
+          - id: skill-filesystem
+            name: '@deepseek-ai/dsh-skill-filesystem'
+          - id: tool-skill
+            name: '@deepseek-ai/dsh-tool-skill'
+          - id: compaction
+            name: cordis:group
+            group: true
+            isolate:
+              compaction: true
+              toolResultPruner: true
+            config:
+              - id: compaction-basic
+                name: '@deepseek-ai/dsh-compaction-basic'
+              - id: command-compact
+                name: '@deepseek-ai/dsh-command-compact'
+              - id: tool-result-pruner
+                name: '@deepseek-ai/dsh-compaction-tool-result-pruner'
+                config:
+                  thresholdChars: 8192
+                  headChars: 4096
+                  tailChars: 1024
+          - id: delegation
+            name: cordis:group
+            group: true
+            isolate:
+              workflowEngine: true
+            config:
+              - id: tool-subagent-control
+                name: '@deepseek-ai/dsh-tool-subagent-control'
+              - id: tool-subagent
+                name: '@deepseek-ai/dsh-tool-subagent'
+                config:
+                  provider: spawn
+                  toolName: subagent
+                  modelSelection: true
+                  modelDiscovery: true
+                  agentPreset: standard
+          - id: tool-todo
+            name: '@deepseek-ai/dsh-tool-todo'
+            config:
+              allowParallelInProgress: true
+          - id: tool-web
+            name: '@deepseek-ai/dsh-tool-web'
+            config:
+              fetch: false
+              searchTimeoutMs: 60000
+    # The agent preset of the main Session (ROUTER_PRESET in src/app/sessions.ts). The worker's 5-second shell and job waits, so a command or a wait does not hold back the next candidates, and
+    # only what the main Session uses: no subagents, web, file search or writes, todo list, questions to a person, presenting,
+    # plan mode, plugin manager, scheduling, goals or workflows. No persona: the main Session's prompt is complete, so it has
+    # no other section.
+    - id: dsh-superagent-router-preset
+      name: '@deepseek-ai/dsh-agent-preset'
+      config:
+        id: dsh-superagent-router
+        name: dsh-superagent 主 Session
+        description: dsh-superagent 的主 Session 专用，不供手动选择。前台命令和任务等待超 5 秒转入后台，只含路由所需的工具。
+        order: 91
+        plugins:
+          - id: agent-instructions
+            name: '@deepseek-ai/dsh-agent-instructions'
+            config:
+              maxBytes: 65536
+          - id: time-context
+            name: '@deepseek-ai/dsh-time-context'
+          - id: shell
+            name: cordis:group
+            group: true
+            isolate:
+              shell: true
+            config:
+              - id: bash-sandbox
+                name: '@deepseek-ai/dsh-bash-sandbox'
+                disabled: !!js process.platform === 'win32'
+                config:
+                  timeoutMs: 5000
+                  maxTimeoutMs: 5000
+              - id: pwsh-sandbox
+                name: '@deepseek-ai/dsh-pwsh-sandbox'
+                disabled: !!js process.platform !== 'win32'
+                config:
+                  timeoutMs: 5000
+                  maxTimeoutMs: 5000
+              - id: tool-bash
+                name: '@deepseek-ai/dsh-tool-bash'
+                disabled: !!js process.platform === 'win32'
+              - id: tool-pwsh
+                name: '@deepseek-ai/dsh-tool-pwsh'
+                disabled: !!js process.platform !== 'win32'
+          - id: tool-fs
+            name: '@deepseek-ai/dsh-tool-fs'
+            config:
+              write: false
+              edit: false
+          - id: tool-jobs
+            name: '@deepseek-ai/dsh-tool-jobs'
+            config:
+              waitTimeoutMs: 5000
+              maxWaitTimeoutMs: 5000
+          - id: skill-filesystem
+            name: '@deepseek-ai/dsh-skill-filesystem'
+          - id: tool-skill
+            name: '@deepseek-ai/dsh-tool-skill'
+          - id: compaction
+            name: cordis:group
+            group: true
+            isolate:
+              compaction: true
+              toolResultPruner: true
+            config:
+              - id: compaction-basic
+                name: '@deepseek-ai/dsh-compaction-basic'
+              - id: command-compact
+                name: '@deepseek-ai/dsh-command-compact'
+              - id: tool-result-pruner
+                name: '@deepseek-ai/dsh-compaction-tool-result-pruner'
+                config:
+                  thresholdChars: 8192
+                  headChars: 4096
+                  tailChars: 1024