# @bojackduy/opencode-loopd 中文文档

规范地址：https://npmcn.com/package/%40bojackduy/opencode-loopd/

版本：1\.14\.6
npm 元数据更新时间：2026-10-27T19:38:45.333Z
中文译文更新时间：2026-11-08T10:15:10.555Z
软件包许可：AGPL-3\.0-or-later

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40bojackduy/opencode-loopd
原文对照：https://npmcn.com/package/%40bojackduy/opencode-loopd/?lang=original
项目主页：https://bojackduy.github.io/opencode-loopd/
源码仓库：https://github.com/bojackduy/opencode-loopd

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2 MB，12 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：2 个
- peer 依赖：solid-js \*，@opentui/core \*，@opentui/solid \*，@opencode-ai/plugin \>=1\.4\.0 \<3
- 首次发布：2026-08-21T21:28:35.561Z
- 最新版本发布：2026-10-27T19:38:44.993Z
- 近 30 天下载量：2316（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：46（近 12 个月 46 个）

## 中文简介

OpenCode的Codex启发背景目标引擎——自主子代理,由引擎驱动的循环,童工会话和模式TUI仪表板. 就像Claude Code循环OpenCode一样.

## 安装

```sh
npm install @bojackduy/opencode-loopd
```

也可以使用：`pnpm add @bojackduy/opencode-loopd`、`yarn add @bojackduy/opencode-loopd`、`bun add @bojackduy/opencode-loopd`

## README

# 打开编码锁定

**对OpenCode的持久目标监督——可核实的目标,范围重复,排程,以及一个目标仪表板. OpenCode 运行会话;循环监督目标.**

> 运行长期任务为 **儿童自主学习班** 主聊天时保持交互. 创建一个目标 `/goal`,在背景中注意它循环,从键盘驱动的TUI中监控一切——同时不阻碍母对话.

[![npm version](https://img.shields.io/npm/v/@bojackduy/opencode-loopd?style=flat-square&color=blue)](https://www.npmjs.com/package/@bojackduy/opencode-loopd) [![license](https://img.shields.io/badge/license-AGPL--3.0--or--later-blue?style=flat-square)](https://npmcn.com/package/%40bojackduy/opencode-loopd/LICENSE) [![opencode plugin](https://img.shields.io/badge/opencode-plugin-9cf?style=flat-square)](https://opencode.ai/) [![TUI](https://img.shields.io/badge/TUI-OpenTUI-purple?style=flat-square)](https://github.com/anomalyco/opentui)

![Loop Dashboard — modal TUI with goals, running indicator, and insert mode](https://npmcn.com/package/%40bojackduy/opencode-loopd/assets/demo.png)

_Modal仪表板(`/loop` 编号 : `<leader>o`:零聊天污染 – 密钥被困在对话框内,NORMAL vs INSERT模式,生动地进行每个状态的配色._

## 为什么打开代码

-   **背景代理, 不屏蔽聊天** – 一个 OpenCode 插件, 生成一个专用 **工人(儿童)会议** 每个目标。 父母可以自由地继续聊天.
-   **目标驱动的延续** ——本土v2执行结果推进目标政策与累积背景. 基于转写的闲置恢复仍然是遗留的相容路径.
-   **父母 子女可见度** —— 说 `list/inspect/read_transcript/send_input` 给予父母完全的可观察性。 双向收件箱允许您在中途运行 .
-   **默认安全** ——每个目标文物隔离`.opencode/loopd/goals/<id>/`, (中文(简体) ), `maxTurns`编号 :`maxFailures`编号 :`maxNoProgress`, 力- 成 \* 语义 `complete_goal` 通过醒悟注射的家长通知.
-   **排定间隔** —— 说 `scheduleEveryMs`编号 :`scheduleMaxRuns` 自动重排每 N 毫秒相同的入球(例如, `10s` 监视器, `1h` 页:1 `/goal` 垃圾邮件 `5s` 民意调查, `skip-if-running`, (中文(简体) ), `workspaceWrite` 序列化,收件箱 `Scheduled tick N/M`。 。 。 .
-   **Modal TUI 仪表板** —— 说 `<leader>o` 或者说 `/loop` 打开焦点对话框( 不漏出到聊天提示) 。 维姆式导航,活运行指示器,每个状态边框.
-   **命令会话, 不是被屏蔽的贝壳** ——运行安装,构建,dev服务器和REPL作为背景OS进程,并配有全屏终端,所有者退出通知,行级 `filter`编号 :`until` 手表和超时—— 而不是冻结代理上线 `bash`。 。 。 .
-   **切换身份中程** —— 说 `loopd_list_models` 发现模型和物剂; `switch_goal_identity` 改变目标模式、代理,或同时改变 _不变_ 工人/会议。 合并变化在解剖学上持续存在,在部分失败后倒退. 可选命令 `fallbackModels` 429s自动开关。 盘子 : `:model`编号 :`:agent` 财务报告和审定财务报表 `:models`编号 :`:agents`。 。 。 .
-   **交互式工作的手工模式** —— 说 `interactive: true` (或 `:interactive`停止引擎启动 自己开启; 每转来自你 `:send`冲啊 对于工人等待投入的任务.

关键词 : `opencode` `opencode-plugin` `background-agent` `autonomous` `subagent` `loop` `goal` `tui` `codex` `claude-code` `worker`

## 这是什么

在所支持的 v2 主机上, OpenCode 拥有执行, 队列中的消息发送和 周期。 循环拥有目标,验收,预算, 安排和跨目标协调。 见 [v2-第一监督](https://npmcn.com/package/%40bojackduy/opencode-loopd/docs/v2-supervisor.md) 对已审计合同,重新开始调节和遗留界限.

精确文件编辑合同及其执行边界记录于 [文件范围所有者](https://npmcn.com/package/%40bojackduy/opencode-loopd/docs/file-scope-ownership.md)启用 `write_scope: []` 改为 在要求文件之前进行探索; 省略范围保留了遗留的专有性.

每一个承诺的循环 是一个运行目标——检查完成,一个所有者 通知、 队列方向盘、 持久暂停、 最后清除 —— 列于 [生命周期合同](https://npmcn.com/package/%40bojackduy/opencode-loopd/docs/lifecycle-contract.md) 对一个真正的 `opencode serve` 在每次发布之前处理。 那道门是什么 `bun run smoke:v2-lifecycle` 运行; 这不是一个被嘲笑的单位测试.

打开码是一个 **打开代码插件** (服务器 + TUI ) **背景目标** 转到 OpenCode 。 每个目标都有一个 **工人(儿童)** 自动循环 **循环引擎** 驱动续作 **计时工** 在一个间隔上重排同一入球( n)`scheduleEveryMs`; 计 数 **仪表板** 财务报告和审定财务报表 **拥有工具** 保持父母的控制权。 考虑一下 _代码目标_ 或者说 _Claude 代码循环_,但本地化为 OpenCode 的会话模式 —— 定期重复对话.

## 安装

### 插件 — 简单( 没有安装器, 只有插件)

将软件包添加到 **两者** 相会相会.

**`~/.config/opencode/opencode.jsonc`** — 服务器引擎 :

```jsonc
{
  "plugin": ["@bojackduy/opencode-loopd"]
}
```

**`~/.config/opencode/tui.json`** - 仪表板(TUI模式):

```jsonc
{
  "plugin": ["@bojackduy/opencode-loopd"]
}
```

然后重新启动 OpenCode 。 校验 `/loop` (平板 ) 或 `<leader>o`。 。 。 .

本地检出 :

```jsonc
// opencode.jsonc
{ "plugin": ["./path/to/opencode-loopd"] }
// tui.json
{ "plugin": ["./path/to/opencode-loopd"] }
```

### 安装器——也安装 `/goal` + 技能

```bash
npx -y @bojackduy/opencode-loopd@latest
```

注册插件,安装 `/goal` 斜线命令和 `loopd` 技能进入 `~/.config/opencode/`。运行到更新。 礛 **重新启动 OpenCode**。 。 。 .

卸载 :

```bash
npx -y @bojackduy/opencode-loopd@latest --uninstall
```

或者通过全球npm:

```bash
npm install -g @bojackduy/opencode-loopd@latest
opencode-loopd            # install
opencode-loopd --uninstall # remove
```

然后重新启动 OpenCode .

### 手动( 本地 dev)

添加为 `~/.config/opencode/opencode.jsonc`数字 :

```json
{
  "plugin": ["@bojackduy/opencode-loopd"]
}
```

或用于本地检查 :

```json
{
  "plugin": ["/Users/you/Code/opencode-loopd"]
}
```

对于安全代码编辑默认,配置服务器插件时使用代理程序 校验命令 :

```json
{
  "plugin": [[
    "@bojackduy/opencode-loopd",
    {
      "defaultAgent": "smart-agent",
      "defaultChecks": ["bun test", "bun run typecheck"]
    }
  ]]
}
```

`opencode-loopd` 揭露:

-   `opencode-loopd/server` • 引擎插件
-   `opencode-loopd/tui` — 仪表板插件

## 使用量

### 1\. 建立一个目标 -- -- `/goal`

从任何会议,告诉代理:

```
/goal fetch the latest AI news and save 10 items to ai-news.md
```

或明确:

```
Create a background goal to find all .ts files in src/, count lines, and write the summary to line-counts.md — verify with grep -c.
```

代理人将澄清(什么/在哪里/如何核实),然后打电话 `loopd_create_goal`. 工人立即开始秘密的儿童会议.

### 2\. 带仪表板的监测器 - `/loop`

新闻 **`<leader>o`** 或打开命令调色板 **"圈盘"** (另见: `/loop`) (中文(简体) ).

挂板( NORMAL / InSERT) `:`——共同目标/命令分页:

-   `Tab` 切换目标/命令 `h` 目标 `l` 图标( E)`/commands` 在命令上打开)
-   `j/k` - 移动选择 `g/G` 上/下( 只活动标签)
-   `o` 目标: 开放式的儿童会话( 本地 OpenCode 视图) 命令: 关闭 弹出, 打开全屏终端页面( 路由) `opencode.loopd.terminal`(中文(简体) )
-   `p/r/R/x` ——暂停 / 恢复 / 重试 / 清除选定目标( 仅目标标签)
-   `c` – 在两个标签上切换完成( 已完成目标 ! 退出/ 终止/ 丢失命令)
-   `:interactive` ——切换手动模式(引擎从不开始转弯)- `:model <provider/model>` -切换入球的模型 - `:models` 供应商/存货模型
-   命令标签 : `X` \* 武力杀戮 `R` 重新启动.. `x` 删除完成 `:new <command> [args...]` \* 发射 `:interrupt` • 妇女 `:terminate` • 妇女 `:remove` 光文本 + Enter 写 stdin (所有者范围)
-   `:` - 插入模式- `:send <message>` 驾驶, `:force` 编号 : `:block` 手动完成
-   `?` 切换帮助 帮助在键入时保持开放
-   `Ctrl+N` 回到诺马尔
-   `q` - 关闭

> 仪表盘会夹住所有的密钥——即使通过调色板打开,聊天输入光标也不会在下方闪烁.

全屏终端页面:原始打字直接到PTY, `Ctrl+C` 中断( 从未关闭 OpenCode) , `Ctrl+]` 返回到您的会话 (命令持续运行——终止是明示的),粘贴是即时的.

### 3\. 主要代理人(所有者工具)的检查

父母从不需要仪表板——可以问:

```
list_background_goals()          — status snapshot
inspect_background_goal()        — full detail: objective, progress, blocker, runtime
read_goal_transcript()           — last N worker messages (what it's doing)
send_goal_input(goalID, msg)     — steer: "skip appendix PDFs"
pause_goal(goalID) / resume / clear
loopd_list_models()              — providers/models, quota status (unknown where hosts can't report it)
switch_goal_identity({goal_id, model?, agent?}) — same goal, new identity (same worker/session; at least one field required)
loopd_command_start(...)         — installs/builds/servers as background processes (never block the turn in bash)
```

### 4\. 工人工具(儿童会议)

儿童看到:

-   `get_goal` ——读取目标,合同,进度,失败
-   `report_goal_progress` ——经过耐用写作后
-   `complete_goal` - 只有在有证据的检查通过时
-   `block_goal` - 需要用户的真正阻塞器
-   `question` (OpenCode 内置) – 澄清 – TUI 屏蔽选项卡

完成是语义性的:孩子写摘要;插件通过醒悟注射将其转发给父母. 如果限制被击中, 引擎首先强制儿童 `complete_goal`;只有当被忽略时,它才会用通用消息自动屏蔽.

## 建筑

```
                        ┌─────────────────────────┐
                        │  Main session (parent)  │
                        │  owner tools            │
                        │  inspect / steer / pause│
                        └────────────┬────────────┘
                                     │  inbox → child
                                     │  wake-up ← engine
             ┌───────────────────────┼───────────────────────┐
             ▼                       ▼                       ▼
        ┌─────────┐           ┌──────────┐            ┌─────────┐
        │  Goal A │           │  Goal B  │            │  Goal C │
        │ active  │           │ blocked  │            │  paused │
        └────┬────┘           └────┬─────┘            └────┬────┘
             │                     │                       │
             └─────────────────────┼───────────────────────┘
                                   │
                     ┌─────────────┴─────────────┐
                     ▼                           ▼
              Loopd engine  ──────────►   Child worker (subagent)
              (plugin server)  steering   get_goal / report / complete
                 │  lease / retry / polling       │  block / question
                 │  force-finish / notify         ▼
                 │                         .opencode/loopd/goals/<id>/
                 │                           progress.md / artifacts
                 └─────────────────────────────────┘
```

-   **引擎驱动循环** (如"代码"): `session.idle` 租赁+重试+投票+再期子女。 不是家长驱动的再瞬间机.
-   **预定顺序** (1.7): (中文(简体) ) `createScheduleWorker` `5s` 扫描 `complete` 目标 `scheduleEveryMs`编号 :`maxRuns`· ; `complete→active` 以 `Scheduled tick N/M` 收发箱, `skip-if-running` 财务报告和审定财务报表 `workspaceWrite` 有门.
-   **累积上下文**:每个续作包括进度历史,笔录尾部,收件信息,以及文物目录(除非客观名称是另一个目录).
-   **家长醒来**: 当孩子打电话时 `complete_goal`编号 :`block_goal`, (中文(简体) ), `tool.execute.after` 把孩子的语义摘要注入主人公的会话中——你可以看到"Loop目标.完成:."没有投票.

## 艺术品

每个目标都在自己的目录下写作(`.opencode/loopd/goals/<goal-id>/`(三); `progressFile` 默认存在。 仪表盘和记录从不污染项目根. 如果你的目标说 `save to ./reports/`赢了.

## 示例——多转而用武力完成

```
# Parent: /goal
goal: "Generate 5 files file1..5.md under artifacts/, 2 lines each — verify with glob."
maxTurns: 1

# Turn 1: child writes file1..3, reports progress
# → engine hits maxTurns, injects FINAL REPORT REQUIRED
# Turn 2 (forced): child wraps up, calls complete_goal(summary="created 5 files…", evidence="glob confirmed…")
# → engine forwards to parent: "Loop goal … completed: created 5 files…"
# → Artifacts: .opencode/loopd/goals/<id>/file*.md
```

见 `assets/demo.png` 上面的仪表板,休息(0活,7个完成),有生动的状态颜色,运行自旋器,以及 `INSERT` 徽标.

## 配置

目标接受:

| 选项 | 默认 | 说明 |
| --- | --- | --- |
| `maxTurns` | `50` | 最大续作在完成前翻转 |
| `maxFailures` | `3` | 块前连续失败 |
| `maxNoProgress` | `3` | 在武力完成前没有进展 |
| `timeoutMs` | `300000` | 每轮租赁(5分钟) |
| `compactEvery` | —— 说 | 每个 N 个转弯 |
| `scheduleEveryMs` | —— 说 | 在 ms中间隔,每次完成后自动重排同一入球. 最低1000块。 允许重复减少对话框而无需手动重现 |
| `scheduleMaxRuns` | —— 说 | 最大总运行包括初始运行. 未定义 = 无限. 要求数 `scheduleEveryMs` |
| `checks` | `[]` | 必须经过的贝壳命令 `complete_goal` |
| `checkCwd` | 文物目录 | 完成检查运行的目录; 工作空间默认为工程根 |
| `workspaceWrite` | `true` | 标记共享-工作空间突变;只允许一个活跃的工作空间写入器. 设定 `false` 专为文物/只读作品 |
| `agent` | `defaultAgent` | 工人代理; 如果既不配置也不提供目标创建失败 |
| `interactive` | `false` | 手动模式:引擎从不开始转弯(`:send`/只动了). 对于等待投入的工人 |
| `fallbackModels` | `[]` | 已订购 `provider/model` 选择只针对配额/税率限制错误。 空 = 没有自动开关 |
| `progressFile` | `<artifactDir>/progress.md` | 交易状态文件 |
| `artifactDir` | `goals/<id>/` | 自动 - 仅在客观名称另加目录时更改 |

人工活体、原木和状态 `.opencode/loopd/` (项目-当地)。 锁住 `/tmp/loopd-locks/<project-hash>/` 避免瞬间出声.

工作空间写作目标必须有确定性的检查,并按序列进行 防止同时代理或 `git stash` 从每个操作覆盖 其它部分。 设定仅用于艺术的研究目标可同时运行 `workspaceWrite: false` 当然.

## 已排定目标——重复对话,无需手动重现

一个 `/goal` 现在可以在间隔上循环——引擎重排 **目标相同** 在每个之后 `complete`数字 :

```
loopd_create_goal({
  name: "hourly-report",
  objective: "Append date -u to tick.txt each run",
  agent: "smart-agent",
  checks: ["test -f tick.txt"],
  scheduleEveryMs: 3600000, // 1h, min 1000
  scheduleMaxRuns: 24,      // total incl initial, omit for unlimited
  workspaceWrite: false
})
```

-   **波尔:** `5s` `createScheduleWorker` 扫描 `complete` 预定目标; `skip-if-running` (租赁/`phase`编号 :`workspaceWrite` 门).
-   **重现 :** `complete → active` `phase=idle`,注入收件箱 `Scheduled tick N/M — re-execute objective`,则 `continueTurn`。 。 。 .
-   **状态 :** `scheduleRunCount`编号 :`nextRunAt`编号 :`lastScheduleAt` (单位:千美元)`v6` `state.json`, (中文(简体) ), `schedule.tick` 事件, `schedule.resurrected` 服务器日志 .
-   **现场证据 :** `sched-live-verify` `09cb837c` `10s` `maxRuns 3` → `tick.txt` `3` 线条 `02:00:56` `02:03:43` `02:05:47` 与 `runCount 3`。 。 。 .

没有计划,你就会发送 `/goal` 3x 手动; 附表一的创建覆盖 `monitor deploy`, (中文(简体) ), `periodic tests`, (中文(简体) ), `keep going until done`。 。 。 .

## 切换模型而不失去工人

当供应商达到配额或税率限制时:

```
loopd_list_models()                                   — what's connected, quota status (or honestly unknown)
switch_goal_identity({goal_id, model:"other-provider/good-model"}) — same goal, same worker/session, transcript kept
```

-   繁忙的工人将开关推迟到下个转弯(`→ pending … applies next turn`);闲置的立即切换. 在 v1 上, 新模型从下个提示生效( 没有中流会话切换 API); v2 切换支持的活会话, 否则报告 `unsupported` 没有触摸任何东西.
-   `fallbackModels: ["b/model", "c/model"]` 在创建中自动尝试其它选项——配额/429错误,每一次都永远不会循环. 交互式目标记录倒计时,但永远不能自动觉醒;你引导下个转弯.
-   盘子 : `:model <provider/model>` 财务报告和审定财务报表 `:models` 对人也一样.

## 盘盘提示

-   新闻 `:` 然后输入赤色文本 以 `send_goal_input` 到选定目标.
-   裸体 `:force my summary --evidence "glob ok"` 在孩子被卡住时绕过校验 .
-   `o` 跳转到本地的 OpenCode 儿童会话——完整记录,diffs,工具调用.

## 校验更改

```bash
bun run typecheck && bun test          # unit + integration
bun run build:server && bun run smoke:v2-lifecycle   # real OpenCode v2 host
```

`smoke:v2-lifecycle` 靴子丢弃 `opencode serve` 专用 `XDG_*`/数据库状态和当地固定模型,然后说明生命周期 保证结束。 线人以前开过 `npm publish`,并上传其私人 失败的文物。 见 [生命周期合同](https://npmcn.com/package/%40bojackduy/opencode-loopd/docs/lifecycle-contract.md) 页:1 它包含什么,它故意不包含什么.

## 相关/

打开代码插件 **背景代理人**, (中文(简体) ), **自动子剂**, (中文(简体) ), **循环**, (中文(简体) ), **目标**, (中文(简体) ), **TUI 仪表板**, (中文(简体) ), **代码**\- 继续, **克劳德代码** 循环替代, **打开代码图**, (中文(简体) ), **工人会议**. 与 `opencode-telescope` (搜索)和 `lazyjira`编号 :`lazyconfluence` (ATUI)来自同名作者.

## 许可证

AGPL-3.0-或-后期——见 [自由主义](https://npmcn.com/package/%40bojackduy/opencode-loopd/LICENSE)。 。 。 .

## 常见问题

### @bojackduy/opencode-loopd 是什么？

OpenCode的Codex启发背景目标引擎——自主子代理,由引擎驱动的循环,童工会话和模式TUI仪表板\. 就像Claude Code循环OpenCode一样\.

### 如何安装 @bojackduy/opencode-loopd？

在项目目录运行 npm install @bojackduy/opencode-loopd，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：solid-js（\*）、@opentui/core（\*）、@opentui/solid（\*）、@opencode-ai/plugin（\>=1\.4\.0 \<3）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 opencode-loopd，可以用 npx opencode-loopd 直接运行。

### @bojackduy/opencode-loopd 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/bojackduy\_\_opencode-loopd 是否存在。

### @bojackduy/opencode-loopd 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @bojackduy/opencode-loopd 可以商用吗？

@bojackduy/opencode-loopd 使用 AGPL-3\.0-or-later 许可。最严格的 Copyleft：除分发外，通过网络向用户提供基于它的服务也需要开源对应源码。闭源 SaaS 使用前务必评估。以上为概括，不构成法律意见，请以许可原文为准。

### @bojackduy/opencode-loopd 的下载量有多少？

根据 npm 官方下载统计，@bojackduy/opencode-loopd 在 2026/10/09 – 2026/11/07 这 30 天内被下载 2,316 次，日均约 77 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @bojackduy/opencode-loopd 还在维护吗？

最新版本 1\.14\.6 发布于 2026/10/28（11 天前）；至今共发布 46 个版本，其中过去 12 个月发布了 46 个；首次发布于 2026/08/22。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。