loop/loop

落地页对应的仓库子路径是 loop，仓库中的承载目录也叫 loop，npm 包名 dsh-loop（package.json:3），是 Ephemeral-AI-Lab/dsh-plugins monorepo 下的子包之一。本百科聚焦 loop 路径对应的能力。

一句话定位

为 DeepSeek Harness 增加"会话级循环闹钟"：让当前会话里的 agent 按你设定的秒级间隔自动收到一条用户消息，从而周期性地回头做一件事——比如定时检查构建、轮询日志、阶段性复盘。

核心能力

• 用自然语言或工具创建循环闹钟：告诉 agent"每 30 秒提醒我看一下任务进度"，agent 会自动调用 loop_create(prompt, time_in_seconds) 落库。
• 三个 agent 工具一套共用：loop_create 新建、loop_list 列出当前会话活跃循环、loop_delete(id) 删除一个（src/tools.ts:33-90）。
• 用 /loop 命令操作同一个后端：/loop <秒数> <提示> 新建、/loop list 列出、/loop delete <id> 删除（src/commands.ts:13-45）。
• 到点自动投递给 agent：把提示打包成 <heartbeat> 用户消息送到 session inbox 并带 wakeup:true，空闲 agent 通过 next-turn 接收、运行中的 agent 通过 next-step 接收，不打断当前操作（README.md:96-107）。
• 状态持久化在会话事件日志里：循环定义和每次触发都写成 loop/change session 事件，定时器是进程局部的、会话恢复时按事件日志重建（SPEC.md:115-121）。
• Web 端有一个紧凑的 Loop dock：显示活跃数量、每条间隔、下次倒计时、完整 prompt，并带一键删除按钮（src/ui/LoopsView.tsx:83-118）。

技术实现

• 语言: TypeScript（tsc 编译到 lib/，package.json:11 声明 "type": "module"）
• 关键依赖:
  • @deepseek-ai/cordis（>=4.0.0）：宿主插件框架，apply(ctx) 走标准 Cordis effect
  • @deepseek-ai/dsh-tools / @deepseek-ai/dsh-commands：用 defineTool 注册三个工具、用 ctx.commands.register 注册 /loop 命令
  • @deepseek-ai/dsh-session + @deepseek-ai/dsh-session-persistence：把循环状态写进会话事件日志并 flush
  • @deepseek-ai/dsh-client-ui-slots + @deepseek-ai/dsh-client-ui-conversation：Web 端把 Loop dock 注入到 conversation.input.dock 槽位
• 架构模式: Cordis 插件 + cordis.patch.yml 给宿主注入一行 loop。apply(ctx) 里监听 agent/created 事件，每个根 agent 绑一个 LoopRuntime，runtime 用 setTimeout 排下一次触发，到点调 agent.send(..., 'next-turn'|'next-step', true) 并回写 loop/change 事件；状态经一个 loop projection（stateVersion: 1）暴露给前端，事件类型 loop/change 通过运行时的 dsh-session 模块动态注册。
• 入口文件: loop/src/index.ts（export name = 'loop'、inject = ['tools','commands','agents','sessions','sessionPersistence','sessionProjections']，src/index.ts:13-14）

适用场景

当一个 DSH 会话需要 agent 主动周期性回头看一眼——比如让 agent 每 20 秒自查最新错误并给修复建议、每 60 秒给草稿挑三个最弱的地方、每 10 秒检查构建是否还健康——都可以用这个插件：创建一条循环后，agent 不用你催就会按节奏自我触发，适合长时间运行、需要持续观察状态的场景。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:Ephemeral-AI-Lab/dsh-plugins/loop

配置项

本插件无需额外配置。安装后重启 DSH 并新建会话即可使用，循环的间隔、提示词、ID 全部在运行时通过工具调用确定，不读取任何插件级配置文件或环境变量。

唯一会被校验的字段是 time_in_seconds（必须是正整数秒）、prompt（非空字符串）、id（非空且无首尾空白），这些是工具入参的硬约束，不算可配置项。

常见问题

Q: 装完之后怎么用？

A: 重启 DSH 并新建会话即可。在输入框打 /loop 10 看一下构建状态 就能立即创建第一条；agent 在会话里也能用自然语言要求"每 20 秒提醒我检查错误"自动调用 loop_create。无需新建 preset 或开关任何宿主配置。

Q: 想改一个循环的间隔或提示词怎么办？

A: v1 没有提供 loop_update/编辑/暂停/恢复/立即触发这一类操作（SPEC.md:38-44 明确列为非目标）。实际做法是先 loop_delete 再 loop_create 一次。

Q: DSH 进程关掉之后循环还在跑吗？

A: 不在。定时器是进程局部的，README.md:119-121 明确说"a stopped or cold process cannot run timers or wake itself"；会话恢复时 runtime 会按 loop/change 事件日志重建下一触发时间，所以休眠期间错过的提醒不会补送。

Q: 不同会话之间能不能共享同一个循环？

A: 不能。SPEC.md:49-58 规定每个循环归属于创建它的那个 session，其它会话既看不到也删不掉它；要做"全局循环"是 v2 的设计目标（见 SPEC_V2.md），v1 不实现。

Q: 收到提醒时 agent 正在跑别的任务，会不会被打断？

A: 不会。提醒是带 wakeup:true 的用户消息，runtime 根据 agent 当前状态投递：'running' 走 next-step，其它走 next-turn（src/loop.ts:229），即在下一个安全步骤边界处理，不抢断当前操作。

Q: Web 端有可视化吗？

A: 有。DSH Web 的对话输入框上方会显示一个紧凑的 Loop dock，展示活跃循环数量、每条的 every Xs/m/h 间隔、next in … 倒计时、完整 prompt 和一个一键删除按钮；循环达到 3 条以上会自动折叠成"X active loops · next in …"摘要（src/ui/LoopsView.tsx:79-100）。

Q: 间隔能填小数或分钟/小时单位吗？

A: 时间单位只能是秒。time_in_seconds 是正整数（src/tools.ts:45、src/loop.ts:369-370），需要分钟/小时就直接换算成秒再传。

Q: 怎么卸载？

A: 用对应的 dsh 卸载命令移除安装源即可；卸载后当前会话里还在跑的循环停止（runtime 随宿主 dispose），新会话也不再注册 loop_create / loop_list / loop_delete 三个工具和 /loop 命令。

上手难度

入门 — 装好就能用，没有配置文件、没有原生模块、没有特殊 preset 要建；最快 30 秒就能发出第一条 /loop 10 看一下构建状态。

已知问题与限制

• v1 没有循环修改/暂停/恢复/立即触发 API（SPEC.md:38-44），改间隔或提示词必须先删再新建。
• 运行时是会话局部、进程局部的：DSH 进程停掉或系统睡眠期间定时器不触发，也不会补送错过的提醒（SPEC.md:42-44、README.md:119-121）。
• 循环归属于创建它的会话，跨会话共享、跨会话可视化是 v2 设计目标（SPEC_V2.md），v1 不支持。
• 单次 setTimeout 最大延迟 2,147,483,647 ms（约 24.8 天），由 MAX_TIMER_DELAY_MS 强制钳制（src/loop.ts:17,255-257），超过此上限的间隔会被切分到多个定时器重排。
• 只声明了 dsh.client.platform: "web"（package.json:24），命令行/桌面端是否可用源码中未明确。
• Web 端 Loop dock 只在至少有 1 条活跃循环时渲染（src/ui/LoopsView.tsx:77），没有循环时输入框上方不会出现该区域。
• 包内不修改 DeepSeek Harness 宿主代码，全部走 Cordis effect 和 DSH 公共 API（SPEC.md:8-10），但这也意味着宿主一旦更换 dsh-session 公开事件类型，插件对 loop/change 的注册会同步失效（src/index.ts:18-25）。

Small, focused plugins that make DeepSeek Harness more capable, expressive, and pleasant to use.

Quick start · Packages · Development · Documentation

🧠 Give your DSH sessions better tools, durable workflows, and a cleaner path from idea to execution.

⚡ Quick start

Published plugins install directly into a DSH profile with one command. The examples below target the web profile; replace web with the profile you use.

🐚 Codex Terminal

# With the DSH CLI:
dsh plugin --profile web add [email protected]

# Without the `dsh` CLI:
npm install [email protected]

🔐 Codex Coding Plan

Reuse an existing file-backed codex login from the DSH Models page:

dsh plugin --profile web add ./coding-plan/codex

# Grok Coding Plan models from the existing `grok login`
dsh plugin --profile web add ./coding-plan/grok

⏰ Loop

# With the DSH CLI:
dsh plugin --profile web add [email protected]

# Without the `dsh` CLI:
npm install [email protected]

🧪 Mock — unstable

dsh-mock is published for early testing. Its commands, API, and UI may change before a stable release.

# With the DSH CLI:
dsh plugin --profile web add [email protected]

# Without the `dsh` CLI:
npm install [email protected]

🧭 Sessions

Inspect, create, read, and message DSH sessions with the current session tools:

# With the DSH CLI:
dsh plugin --profile web add [email protected]

# Without the `dsh` CLI:
npm install [email protected]

Restart DSH and create a new session after installing a plugin. If dsh is not on your PATH, run the same command from a DeepSeek Harness source checkout with pnpm dsh instead.

Direct npm installation downloads the package for use by your project. DSH profile installation is still required when you want DSH to load the plugin as part of a profile.

📦 Packages

🐚 dsh-codex-terminal

Run shell commands like a Codex-style agent: start long-running processes, poll for output, and send input to persistent sessions. PTY transport is used by default with a configured pipe fallback when PTY allocation is unavailable.

⏰ dsh-loop

Create durable, session-local recurring prompts that can be managed through agent tools, /loop commands, and the web UI. Loops resume with the session and keep each alarm independent from the others.

🧪 dsh-mock

Exercise deterministic mock model turns through /mock run and /mock replay while preserving the real DSH AgentLoop, ToolRuntime, policy, and event flow.

⚠️ Unstable: published as [email protected] for early testing. The command, API, and UI surface may change before a stable release.

Install it into the DSH web profile with one command:

dsh plugin --profile web add [email protected]

🛠️ Development

Each plugin is independently installable and testable. For example:

cd loop
pnpm install
pnpm test
pnpm build

The source tree intentionally stays outside the DeepSeek Harness repository; DSH composes plugins through profile-scoped installation and patch layers.

📚 Documentation

• Codex Terminal documentation
• Coding Plan core
• Codex Coding Plan documentation
• Grok Coding Plan documentation
• Loop documentation
• Mock documentation
• Mock implementation specification
• Sessions documentation
• Sessions specification
• DeepSeek Harness

🤝 Contributing

Issues, ideas, and pull requests are welcome. Keep plugins focused, document their runtime contracts, and include tests for changes to tools, persistence, or UI behavior.

📄 License

Released under the MIT License.