持久智能体 f4ah6o/dsh-dots

@f12o/dsh-dots

为 DeepSeek Harness 提供持久化命名智能体（「dots」），带一个根级 Dots 面板，以及一个控制器，能把多台 DSH 主机合并成一份 dot 列表。

dot 是一个持久化的主会话，外加它自己的工作区：

$DSH_HOME/dots/
registry.json # local dot records
hosts.json # optional remote host list (controller only)
dot-researcher-a1b2c3/
AGENTS.md # managed operating contract
MEMORY.md # durable semantic memory
report.md # optional output
.dsh-dot/manifest.json

每个 dot 都有：

- 私有工作区和沙箱根目录；
- 重启后仍然存活的主会话；
- 通过常规 AGENTS.md 机制加载的运行契约；
- 每次派发任务时注入有长度上限的 MEMORY.md；
- 能唤醒冷会话的持久化调度；
- 执行期工具白名单；
- 主机归属信息，让一个控制器能管理多台 DSH 机器上的 dot；
- 根级侧边栏面板，支持创建、状态查看、派发任务、记忆、调度和归档操作。

仓库：<https://github.com/f4ah6o/dsh-dots>

本包为实验性质，目标 DSH 版本为 0.2.1-rc.2。

日本語クイックスタート

1. 各ホスト（マシン）の Web プロファイルへこのバンドルを入れます。
2. リモートにしたいホストだけ peer.enabled: true と bearer token を設定します。
3. 制御側ホストの $DSH_HOME/dots/hosts.json に、各ホストの URL と token を書きます。
4. 制御側の DSH で「mac-mini に researcher という dot を作って」と依頼します。
5. 左サイドバーの Dots から、全ホストの dot と到達性を確認できます。新規作成・依頼・記憶の追記・定期実行・アーカイブはパネルから行えます。UI は DSH の言語設定に従い、日本語と英語を切り替えます。
モデル向けには dot_list / dot_assign / dot_schedule も同じ操作を提供します。

「複数の dsh を束ねる」は、制御側 1 台 + 各ホストに同じプラグイン、という構成です。各ホストが落ちても他のホストの dot は動き続けます。制御側が落ちても、各ホストのスケジュールは動き続けます。

安装

先构建 bundle，再装进配置档：

git clone https://github.com/f4ah6o/dsh-dots.git
cd dsh-dots
pnpm install
pnpm build

dsh plugin --profile web add "$PWD"

cordis.patch.yml 会以 id: dots 插入这一行。改完代码后重新构建并重启主机。主机需要 Web 组合（Session 控制器，以及 peer 模式所需的 ctx.webServer）。

给另一台机器安装时，先打一个 tarball，再装这个包：

pnpm pack
copy f12o-dsh-dots-0.1.1.tgz to the peer, then:
dsh plugin --profile web add ./f12o-dsh-dots-0.1.1.tgz

Peer 主机配置

在控制器需要访问的每台主机上，到 $DSH_HOME/profiles/web/cordis.patch.yml 里启用 peer 模式：

- id: dots
config:
peer:
enabled: true
name: mac-mini
tokenFile: /Users/you/.dsh/dots/peer-token

创建 token 文件，权限设为仅所有者可读写：

mkdir -p ~/.dsh/dots
openssl rand -hex 32 > ~/.dsh/dots/peer-token
chmod 600 ~/.dsh/dots/peer-token

peer 路由是 POST /dots-peer/rpc。它只用 bearer token 做认证；它不浏览器 /api 的认证。把宿主 Web 服务器绑定到可信网络（Tailscale/WireGuard/LAN）；如果超出可信 tailnet 范围，就在它前面终止 TLS。不要用明文 HTTP 把这条路由暴露到公网。

控制器主机配置

在控制器上创建 $DSH_HOME/dots/hosts.json（权限 0600）：

{
"version": 1,
"hosts": [
{
"id": "mac-mini",
"label": "Mac mini",
"url": "http://100.64.0.7:8080",
"token": "paste-the-peer-token-here"
}
]
}

- id：[A-Za-z0-9_.-]{1,64}；local 为保留值。
- url：结尾不带斜杠；http 或 https；不能内嵌凭据。
- token：至少 16 个字符；用对端 token 文件的内容。
- path：可选，默认 /dots-peer/rpc。
- timeoutMs：可选，单个主机的超时时间。

控制器自己也管理本地 dots，所以 dot_list 里始终有 local。hosts.json 格式错误会让插件激活失败，而不是悄悄丢掉主机。

Dots 面板

这个包除了 Host 工具，还带一个浏览器面板。安装后，侧边栏会在 Workspaces 和 Automation tasks 旁边加一个根级 Dots 入口，并加一个主面板，功能包括：

- 显示所有本地和远程 dot，以及主机可达性和实时状态；
- 在本地或远程主机上创建 dot，包括指定模型和推理强度；
- 打开本地 dot 的 Session，或打开远程主机自己的 DSH UI；
- 排队任务、追加持久记忆、创建每 N 秒执行一次的调度、归档 dot；
- 跟随 DSH 语言设置：内置英文和日文文案，自带的语言选择器会实时切换两者。

面板从 POST /dots/api 读数据。这条路由需要所有者认证，用的是和 Web UI 其余部分相同的浏览器登录 token cookie 以及 Host/Origin 校验。机器对机器的对端路由仍是 /dots-peer/rpc，用 bearer token；浏览器永远拿不到那个 token。

客户端部分在 pnpm build 时打包进 lib/client.js，由常规的客户端模块图提供。UI 状态只存在于页面内，每 8 秒轮询一次，不进入 Session 日志。

使用

这些工具面向模型。让助手去创建/查看/分配，或者直接调用工具。

| 工具 | 含义 |
| dot_create | 在 host 上创建 dot（省略则为本地），可指定名称、用途、预设、权限预设、允许列表，以及可选的 provider/model/推理强度。 |
| dot_list | 合并本地和远程 dot，包括每个主机的可达性和实时状态。 |
| dot_assign | 排队一个任务。任务进入收件箱时返回；这不是完成。 |
| dot_update | 替换用途/契约、追加记忆，或替换允许列表。 |
| dot_schedule | 在 dot 所在主机上创建持久调度；必须选一个时间选择器。 |
| dot_archive | 删除活动调度、取消当前轮次，并把 dot 从活动列表移除。单个调度或取消失败会作为警告返回。 |
引用可以接受 id、名称，或 host:name / host:id。只给名称时，优先在本地解析；如果多个远程主机都有这个名称，调用会失败并列出候选。每次 dot_list 和按裸名称解析时都会拉取远程列表；离线主机会被报告出来，不做缓存。

示例：

Create a dot named "release-notes" on mac-mini. Its job is to keep the release notes aligned with
the approved changelog. Use the standard preset and allow only read, grep, web_search, and web_fetch.

Assign release-notes: compare the draft against the approved changelog and write report.md.

Schedule release-notes every weekday at 09:00 Asia/Tokyo with this prompt: check the changelog and
prepare a short delta report.

Dot 设置

面板和 dot_create 提供以下按 dot 维度的设置：

| 设置 | 含义 |
| Name | 稳定的 dot 标识，同时用作 Workspace/Session 标题。 |
| Purpose | 受管理的 AGENTS.md 契约：目标、事实来源、质量标准、升级路径。 |
| Host | 本地或已配置的远程 DSH 主机；dot 的工作区、会话和调度都放在那里。 |
| Agent preset | DSH 预设组合（工具、人设、委派）。默认 standard。 |
| Permission preset | DSH 沙箱 + 审批组合，例如 workspace-write。 |
| Allowed tools | 执行允许列表，写精确工具名或以 结尾的前缀。留空则全部拒绝。 |
| Model / reasoning effort | 会话级服务商/模型/推理强度。省略则用部署默认值。 |
| Assignment | 一个排队任务；进入 dot 的收件箱，按顺序串行处理。 |
| Memory note | 带日期的条目，追加到 MEMORY.md，注入后续任务。 |
| Schedule | 面板里填标题、任务提示词和每 N 秒的间隔；dot_schedule 额外支持 cron/每日/每周/一次性。 |

主机和部署设置不在 dot 内：

- $DSH_HOME/dots/hosts.json：远程主机 id、标签、URL、token、路径、超时。
- Profile peer 配置：peer 启用开关、bearer token/token 文件、路由路径、请求体上限。
- 插件配置：root、defaultPreset、defaultPermissionPreset、maxDots、maxTaskBytes、maxPurposeBytes、maxMemoryBytes、enforceToolAllowlist、hostsFile、requestTimeoutMs、peer.。

模型选择

模型属于主会话，不属于单个任务。dot_create 接受 provider、model 和可选的 reasoning_effort；Host 会用实时模型目录校验它们，并在创建会话后调用 sessionController.selectModel()。选择会持久化在该会话上，之后每次 dot_assign 和定时唤醒都走同一条路由，不会按任务重新选择。

不传模型时，会话使用部署默认值。在此字段出现之前创建的 dot 没有存储模型，继续使用部署默认值。你仍然可以更改模型来自 dot 会话自带的 composer 模型选择器；Dots 面板的 Model 行记录创建时所做的选择。

UI 目录因主机而异：本地 dot 使用本机的服务商，远程 dot 使用对端的目录。如果目录为空或无法访问，表单只提供「Deployment default」。

工作原理

创建

1. 校验 name/purpose/allowlist 和本地上限。
2. 创建 $DSH_HOME/dots/<id>/、AGENTS.md、MEMORY.md 和 .dsh-dot/manifest.json。
3. 为该目录注册 Workspace（可用时）。
4. 用配置好的预设创建 home 会话，并挂到 Workspace 上。
5. 重命名会话，应用权限预设，选择请求的模型，持久化 dot 记录。

如果 Workspace 注册失败，dot 仍可从其目录运行。如果 Workspace 创建后会话创建失败，保留残缺目录，并在错误中指明该目录；用新 dot 重试，或手动清理。

派发

dot_assign 解析 dot，通过 Session controller 恢复冷会话，读取 MEMORY.md 尾部（最多 maxMemoryBytes），并通过 agent.followup() 排队一条 [DOT ASSIGNMENT] 消息。来源类型为 dot。运行中的 dot 在后续轮次收到派发；一个 dot 串行处理派发。controller 记录 lastAssignedAt 和 assignmentCount。

调度

dot_schedule 在 dot 所在主机上调用 Host Schedule 服务。存储的提示词用 [DOT SCHEDULED TASK] 包裹，并指示 dot 先读取 AGENTS.md 和 MEMORY.md。目标到期时，Host Schedule 服务恢复冷会话，因此调度能在主机重启后存活。循环调度只保留最近一次错过的触发，这是底层 Schedule 契约的规定。

记忆

AGENTS.md 由本包管理，当 dot_update 更改 purpose 或 allowlist 时重新生成。把持久学到的信息放进 MEMORY.md；dot 会收到指示，追加带日期的条目。通过 controller 给出反馈：

Tell release-notes to remember that the user prefers a one-paragraph summary with links.

controller 调用 dot_update(add_memory: ...)；下一次派发会注入该记忆，即使经过压缩或冷恢复也不例外。

权限与护栏

- dot 的 home 会话可以携带任何已配置的权限预设（sandbox 模式 + 审批策略）。
- allowedTools 由 tools/pre-execute 监听器强制执行：精确名称或尾部 前缀。空数组拒绝所有工具。工具 schema 仍然可见；只拒绝执行。
- dot 永远不能调用 dot_ 工具，因此 dot 无法创建或管理其他 dot。
- allowlist 中的 bash 仍允许在 sandbox 内执行任意命令；allowlist 不是 shell 级策略。
- 没有可用的审批应答者时，现有审批接缝按失败关闭处理。无人值守的 dot 应使用适合自主工作的权限预设，或让工作保持只读/仅草稿。

多主机

每台主机都有自己的注册表、点目录、会话、调度和凭据。控制器不复制远程状态，而是调用对等 RPC。只要远程 dot 所在主机在运行，即使控制器离线，远程 dot 也会继续运行。控制器在下一次 dot_list 时会重新看到它。如果某台主机离线，列表会报告该情况，需要该主机的操作会以 dots/peer-offline 失败；不会排队等待稍后投递。

配置

除特别注明外，所有字段均为可选。

| 字段 | 默认值 | 含义 |
| root | $DSH_HOME/dots | 本地 dot 根目录（注册表、工作区、主机列表）。 |
| defaultPreset | standard | dot_create 未指定时，新 dot 使用的智能体预设。 |
| defaultPermissionPreset | 未设置 | 应用到新 dot 的权限预设。 |
| maxDots | 32 | 本地活动 dot 的最大数量。每台主机各自执行自己的上限。 |
| maxTaskBytes | 20000 | 单条任务分配或记忆笔记的最大 UTF-8 字节数。 |
| maxPurposeBytes | 4000 | purpose 的最大 UTF-8 字节数。 |
| maxMemoryBytes | 8192 | 每次任务分配注入的 MEMORY.md UTF-8 字节数。 |
| enforceToolAllowlist | true | 在执行时强制执行 allowedTools。 |
| hostsFile | $DSH_HOME/dots/hosts.json | 控制器远程主机列表。 |
| requestTimeoutMs | 15000 | 每次远程调用的默认截止时间。 |
| peer.enabled | false | 注册 POST /dots-peer/rpc。 |
| peer.token | 未设置 | 内联 bearer token（优先用 tokenFile）。 |
| peer.tokenFile | 未设置 | 包含 bearer token 的文件。 |
| peer.path | /dots-peer/rpc | 对等路由的精确路径。 |
| peer.name | 未设置 | ping 返回的诊断名称。 |
| peer.maxBodyBytes | 1048576 | 对等请求体的最大字节数。 |

安全

- 对等路由运行在 DSH 主机进程中，拥有主机用户的权限。请把 token 当作主机管理员凭据。
- 每台主机使用唯一 token，存放在 0600 文件中，重启对等端即可轮换。
- 优先使用 tailnet/WireGuard 网络或 TLS。该路由没有速率限制、CSRF 防护或浏览器认证；它是机器对机器的 API。
- 远程 dot 使用远程主机的沙箱和权限预设执行；它们的 AGENTS.md 和 MEMORY.md 位于那台主机上。
- 不要把机密放进 MEMORY.md、AGENTS.md 或任务分配中。记忆对模型可见。

限制

- 每个 dot 只有一个 home 会话；任务分配串行执行。要并行，请创建更多 dot，或在 dot 内使用子代理。
- 归档会让 dot 从 Dots 面板隐藏，但它的 Workspace 和 Session 仍保留在 Workspaces 侧边栏。如果想让侧边栏干净，请单独删除它们。
- 面板的调度表单创建固定的每 N 秒调度。cron、每日、每周或一次性调度请使用 dot_schedule 或 dot 本身。
- 面板每 8 秒轮询一次，没有实时推送；状态变化可能短暂滞后。
- 不提供自动云 VM 预配。这是本地前台/宿主机模式。dot 的工作区就在它的宿主机上。
- 没有 Slack/Teams/SMS/email 渠道。
- 之后在 dot 会话的 composer 里更换模型，不会写回 dot 记录；面板的 Model 行显示的是创建时的选择。
- 没有自动的 token/费用配额。定时任务和自主工作都会消耗模型 token。
- 控制器在激活时加载 hosts.json；要添加宿主机，请编辑后重启。
- 远程 dot 名称通过列出每台宿主机来解析；宿主机数量很大时，裸名称解析的耗时与宿主机数量成正比。用 host:name 可实现确定性路由。
- 归档操作跨宿主机不是事务性的：无法删除的定时任务，或无法取消的轮次，会记录在 warnings 中，而 dot 记录仍会被归档。如果出现警告，请检查远程宿主机。

开发

pnpm install
pnpm build
pnpm typecheck
pnpm test
npm pack --dry-run

测试使用结构化的 FakeHost；不需要运行中的 DSH 进程或模型密钥。针对在线宿主机的集成检查应使用单独的 DSH_HOME 和非默认端口。

许可证

MIT