dsh-foreman 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,105 @@
+# Changelog
+
+本仓库的历史从本项目自己的初始提交开始，**不携带上游 git 历史**（见 README 的「由来与致谢」）。
+下面 `0.2.0` 一节是从代码基线 `dsh-superagent-local` 沿袭下来的、那一份代码相对上游
+`dsh-superagent-prototype` 的改动记录，保留它是为了说明基线里已经有什么；**它不是本项目的发布版本**。
+
+本项目自己的版本从 `0.1.0` 开始。
+
+## 0.1.0 — 2026-11-07
+
+首个公开发布。**一个常驻主 loop，把工单派给多台在线设备上各自完整运行的 DSH，账本只有一份。**
+
+### 新增：设备与派单
+
+- **设备注册表**（`src/foreman/devices.ts`）：同一份 SQLite 里的 `foreman-device:` 家族，
+  令牌只存 SHA-256。加设备、换令牌、吊销都不需要重启主 loop。
+  CLI：`scripts/add-device.mjs add | list | rotate | revoke`。
+- **Selector**（`src/foreman/selector.ts`）：纯函数。吊销的、离线的、没有对应项目 root 的设备先出局；
+  显式点名或标签要求再收窄；剩下的按在跑数量最少，平局取最近心跳。
+- **选择落在 accept 上**：`Ticket.target` 在 accept 时确定，`newAssignment` 复制到
+  `Assignment.target`。选设备在 `prepareTicket` 缝上，**不在** Executor 里——Executor 没有写库通道。
+- **ForemanExecutor**（`src/foreman/executor.ts`）：本机目标原样交给 `DshExecutor`；
+  远端目标变成一个 `assign` 帧。设备不可达时报 `blocked`，**不伪造 failed，也不悄悄改成本机执行**。
+- **Foreman Hub**（`src/foreman/hub.ts` + `ws.ts`）：设备主动外连，`ws` 只出现在一个文件里，
+  只监听 `127.0.0.1`（对外由隧道终结 TLS）。握手校验令牌与协议版本；吊销在下一帧就生效。
+- **文本渲染**（`src/foreman/render.ts`）：任务文本在主 loop 侧定稿，**不带任何主 loop 路径**；
+  附件走 base64 字节，按编码后大小卡 256 KiB 上限。
+
+### 新增：断线与恢复
+
+- **断线绝不自动重派**。`assignmentInterrupted` 会走 `Tickets.restart` 立刻重开一张，
+  而设备可能还在跑——那是「同一件事执行两遍」。超时只转 `blocked`，交给人。
+- Hub 重启时，在飞的远端 assignment 一律先转 `blocked`，等设备 `hello` 对齐；
+  `DshExecutor.resume()` 按 target 跳过远端项。
+- 设备重连后先 `hello` 报「我在跑哪些」，Hub 对齐而不是假设。
+
+### 新增：设备侧插件（另一个包）
+
+- [`dsh-foreman-node`](https://www.npmjs.com/package/dsh-foreman-node)：连出去、接单、回报三件事。
+  job 会话是 `job-<assignmentId>`，权限是 **`workspace-write`**（不是主 loop 自己的 `danger-full-access`：
+  笔记本前没人，弹审批等于卡死）。
+- 设备上注册 `foreman_report` 工具（`progress` / `ready` / `blocked` / `failed`）。
+  **`dropped` 不允许**：那是判断，设备没有判断权。
+
+### 新增：面板
+
+- 「设置 › 设备」：在线点、在跑数、最近活动、项目名（**不显示设备自己的路径**）、吊销与换令牌。
+
+### 新增：飞书群即项目
+
+- Policy 的 `routing.chats`：群 → 工作区，同时约束设备选择（内网群只选带 `intranet` 标签的设备）。
+  映射按 settings 修订号缓存，改了对新到的消息生效。
+
+### 新增：迁移
+
+- `scripts/migrate.mjs`：`plan` / `checkpoint` / `pack` / `verify`。
+  必须先 checkpoint——库跑在 WAL 模式，只拷 `.sqlite` 会**静默丢掉**最近的工单。
+- [docs/migration.md](docs/migration.md) 五步 runbook。
+
+### 依赖
+
+- 唯一新增的运行时依赖是 `ws@8`。
+- `@deepseek-ai/*` 全是 `peerDependencies`，由装了本插件的 DSH 实例提供。
+
+---
+
+## 0.2.0 — 2026-11-01（上游基线，非本项目发布）
+
+> 这一节记录的是代码基线 `dsh-superagent-local` 相对上游 `dsh-superagent-prototype` 的改动。
+> 本项目的 `0.1.0` 已包含其中全部内容。
+
+### 新增：需求来自本机操作者
+
+- `src/sources/dsh.ts`，作为 `./local-watch` 导出，注册 Source kind `dsh`
+  （标题「本机操作者」）。主会话里由人手输入的消息（`message.source.kind === 'user'`）
+  变成 Trigger，主会话的回复回到同一条会话。
+- 消息里带的图片和文件随需求一起走：Trigger 的 `meta.attachments` 记录附件 id，
+  Executor 在派给 Worker 的任务说明里附上 `~/.dsh/attachments/v1/objects/<前两位>/<id>`
+  路径，Worker 用 `read_image` 打开后再动手。
+- 本地部署不再要求 GitHub 仓库：`resolveDeployment` 在没有远端时返回空 repository，
+  GitHub watcher 报 `paused` 而不是反复失败。
+
+### 新增：每个工作区一条主会话
+
+- `KV.runtime.masters` 记录 workspaceId 到 sessionId 的映射，重启后恢复。
+- `GET /orchestrator/api/master?workspace=<id>` 按需创建并返回该工作区的主会话，
+  会话 id 由工作区路径确定性生成，cwd 就是该工作区目录。
+- `Runtime.isMaster()` 让所有主会话都套 router preset、挂路由工具；主会话只有
+  路由类工具，没有 bash 和文件写入。
+- 客户端在每个工作区组标题行注入 ★ 按钮（`data-main-session-entry`），点它打开
+  该工作区的主会话，并把主会话行从侧栏列表里隐藏。
+
+### 修复：一次需求一张工单
+
+- `meta.newTicket` 让本地来源的每条消息都开新工单，不再被同 thread 的运行中工单
+  吸收，也不会复活已结束的工单。修正前第二条需求会挂到第一张工单上、复用同一个
+  Worker 会话。
+- 本地需求的 Worker 会话与主会话同组，产物落在该工作区目录，不再为每张工单建
+  `work/<工单名>` 工作区。
+
+### 改进：结果回给发起它的主会话
+
+- `relay` 与 `notice` 两个 effect 载荷带上 `sessionId`，工单结束通知回到创建它的
+  那条主会话，而不是固定回默认主会话。
+- 工单卡片带 `workspace` 字段说明产物目录，提示词要求主会话去那里读文件。

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,68 @@
-# Temporary Holding Version
+# dsh-foreman
 
-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.
+> **Not an official DeepSeek product.** 这是第三方项目，与 DeepSeek 官方无关。
+
+**一句话：一个常驻的主 loop，把工单派给多台在线设备上各自完整运行的 DSH，账本只有一份。**
+
+你在服务器上装 `dsh-foreman`，它拥有全部工单、策略和评估；你在每台个人机器上装
+[`dsh-foreman-node`](https://github.com/niechao136/dsh-foreman-node)，它只负责接单、在本地跑、
+把结构化回报交回来。设备上不建工单、不评估、不持有策略、不打开数据库。
+
+```
+┌──────────── 服务器：dsh-foreman（唯一账本）────────────┐
+│  Engine / SQLite / Policy / Tickets / Evals / 设备表    │
+│  每个项目一个主会话入口   ← 你在这里说话                  │
+│  Selector：accept 时决定这活交给哪台机器                  │
+│  Foreman Hub：设备主动连上来                              │
+└──────────────────────┬─────────────────────────────────┘
+                       │  设备外连（wss，稳定域名）
+        ┌──────────────┼──────────────┐
+        ▼              ▼              ▼
+   公司笔记本        宿舍电脑        服务器本机
+   dsh-foreman-node  dsh-foreman-node  本地直跑，不走网络
+```
+
+## 状态
+
+**早期开发中。** 设备注册表、Selector、ForemanExecutor、Hub、回报规则、设备侧插件、文本渲染、
+迁移脚本、面板设备页、飞书群路由都已落地，测试 1332 项。设计与实现计划见：
+- [设计](docs/superpowers/specs/2026-11-06-dsh-foreman-design.md)
+- [实现计划](docs/superpowers/plans/2026-11-06-dsh-foreman.md)
+- [交接文档](HANDOFF.md)
+
+部署两件事各有一份 runbook：[独立实例](docs/deploy-loop-instance.md) 与 [迁机](docs/migration.md)。
+
+## 一眼看懂它怎么派人
+
+accept 一张工单时，`prepareTicket` 这一步就选定了设备，写进 `Ticket.target`，再由 `newAssignment`
+复制到 `Assignment.target`——**不是** Executor 选的（Executor 没有写库通道）。之后：
+
+- `target.kind === 'local'`：原样交给本机的 `DshExecutor`，行为与没有设备时完全一样。
+- 远端：变成一帧 `assign` 发给那台设备。设备不在线就报 `blocked`，**不伪造 failed，也不悄悄改成本机跑**。
+
+断线**绝不自动重派**：设备可能还在跑，重派就是同一件事执行两遍。超时只转 `blocked`，交给人。
+
+## 由来与致谢
+
+本项目**不是**一个 git fork，但代码以
+[dsh-superagent-local](https://github.com/mengzhongjie/dsh-superagent-local) 为起点，
+而后者是 [dsh-superagent-prototype](https://github.com/deepseek-ai/dsh-superagent-prototype)
+（DeepSeek Harness 团队）的改编版。三者的关系：
+
+| 项目 | 作者 | 与本项目的关系 |
+| --- | --- | --- |
+| [dsh-superagent-prototype](https://github.com/deepseek-ai/dsh-superagent-prototype) | DeepSeek Harness Team | 原始研究原型；本项目的架构思想来源 |
+| [dsh-superagent-local](https://github.com/mengzhongjie/dsh-superagent-local) | mengzhongjie | 上述原型的本地化改编；本项目代码基线 |
+| **dsh-foreman** | niechao136 | 在多设备与迁移方向上的重写与扩展 |
+
+原始代码以 MIT 许可发布，Copyright (c) 2026 DeepSeek Harness Team，[LICENSE](LICENSE) 予以保留。
+本仓库的 git 历史从本项目自己的初始提交开始，不携带上游历史；**这不是假装原创，而是为了
+避免把一份无法与上游对齐的三方历史混进来**。要核对上游改动，请直接比对上面两个仓库。
+
+架构思想来自 DeepSeek Harness 团队的《Super-agent 设计探索：迈向更自主的 Agent 系统》。
+本项目借用了其中已经落地的部分（双层架构、Trigger/Thread/Subscription、计算与执行环境分离），
+并对该文第八节自己承认为未解的问题（尤其是 A2A 与安全）给出了自己的取舍，而不是声称解决。
+
+## 许可
+
+MIT，见 [LICENSE](LICENSE)。

package/cordis.patch.yml

@@ -0,0 +1,198 @@
+# dsh-foreman bundle layer: inserts the plugins without configuration, and the agent presets its Sessions run under. The
+# profile supplies the `dsh-foreman` entry's stateDir (see docs/006-deployment.md and examples/profile.cordis.patch.yml); the plugin
+# refuses to start without stateDir.
+- insert:
+    - id: dsh-foreman
+      name: dsh-foreman
+    - id: dsh-foreman-github
+      name: dsh-foreman/github-watch
+    # 椋炰功 IM 鏉ユ簮锛氱兢娑堟伅涓庣鑱婅繘宸ュ崟銆傛病鏈夐厤缃満鍣ㄤ汉 CLI 鏃跺畠鑷繁鎶ャ€屾湭璁剧疆鏈哄櫒浜?CLI銆嶏紝
+    # 涓嶅奖鍝嶅埆鐨勬潵婧愶紝鎵€浠ラ粯璁ゅ紑鐫€锛岃浜鸿兘鐩存帴鍦ㄨ缃噷濉€?
+    - id: dsh-foreman-feishu
+      name: dsh-foreman/feishu-watch
+    # 鏈湴 Source锛氭妸鎿嶄綔鑰呭湪涓讳細璇濋噷璇寸殑璇濆綋浣滈渶姹傛潵婧愶紱涓€涓疄渚嬭鐩栨墍鏈夊伐浣滃尯銆?
+    - id: dsh-foreman-dsh
+      name: dsh-foreman/local-watch
+    # 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-foreman-worker-preset
+      name: '@deepseek-ai/dsh-agent-preset'
+      config:
+        id: dsh-foreman-worker
+        name: dsh-foreman 鎵ц鍣?
+        description: dsh-foreman 鐨勬墽琛屽櫒 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-foreman-router-preset
+      name: '@deepseek-ai/dsh-agent-preset'
+      config:
+        id: dsh-foreman-router
+        name: dsh-foreman 涓?Session
+        description: dsh-foreman 鐨勪富 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
+              # The main Session routes; it must not carry work out itself. Without a shell tool it
+              # cannot write files (fs writes are already off), so a request can only become a ticket.
+              - id: tool-bash
+                name: '@deepseek-ai/dsh-tool-bash'
+                disabled: true
+              - id: tool-pwsh
+                name: '@deepseek-ai/dsh-tool-pwsh'
+                disabled: true
+          - 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

package/icon.svg

@@ -0,0 +1,23 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 96 96" role="img" aria-label="dsh-foreman">
+  <defs>
+    <linearGradient id="bg" x1="10" y1="6" x2="86" y2="90" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#5B7CFA"/>
+      <stop offset="1" stop-color="#8B5CF6"/>
+    </linearGradient>
+  </defs>
+  <!-- 底：圆角方块 + 渐变，和其他插件图标同尺寸、同圆角 -->
+  <rect width="96" height="96" rx="24" fill="url(#bg)"/>
+  <!-- 路由线：主会话把活儿分给三条支线 -->
+  <g stroke="#fff" stroke-opacity="0.7" stroke-width="4" stroke-linecap="round">
+    <path d="M48 58 L48 72"/>
+    <path d="M38 40 L24 30"/>
+    <path d="M58 40 L72 30"/>
+  </g>
+  <!-- 主会话：中心节点（中间留出品牌色小孔） -->
+  <circle cx="48" cy="44" r="12" fill="#fff" fill-opacity="0.96"/>
+  <circle cx="48" cy="44" r="4.5" fill="#6B6BFA"/>
+  <!-- 三个工作区节点 -->
+  <circle cx="48" cy="78" r="7" fill="#fff" fill-opacity="0.96"/>
+  <circle cx="20" cy="27" r="7" fill="#fff" fill-opacity="0.96"/>
+  <circle cx="76" cy="27" r="7" fill="#fff" fill-opacity="0.96"/>
+</svg>