@becrafter/opencode-plugins

Opencode 插件合集 — 开箱即用的插件套件：记忆系统、强制中文回复、项目规范注入、Caveman 模式、跨会话消息、方案压榨、自主开发编排。

单一 npm 包，通过 craft.jsonc 一个配置文件控制全部插件的启用与参数；所有插件由 meta-plugin 自动发现，无需手动注册。

✨ 插件能力一览

| 插件 | 类型 | 核心能力 | 状态 | |------|------|---------|:---:| | memory | 工具 + 上下文注入 | 记忆搜索/保存/状态、上下文注入、dream 自动化 | ✅ 开箱即用 | | chinese-reply | 行为修饰 | 强制中文回复 | ✅ 开箱即用 | | convention-injector | 上下文注入 | 读取项目 agent.md/claude.md 注入约定 | ✅ 开箱即用 | | bark-notify | 通知 | 会话完成/错误/待权限时推送 Bark | 🔑 填 key 激活 | | caveman | 命令 + 注入 | token 压缩模式（/caveman） | ✅ 开箱即用 | | cross-session | 命令 + 消息 | 同机多会话互发消息（/peers） | ✅ 开箱即用 | | press | 命令 + agent | 方案压榨编排（/press） | ✅ 开箱即用 | | super-goal | 命令 + agent | 自主编码循环编排（/goal） | ✅ 开箱即用 |

插件以「出现即启用」为规则：setup 生成的 craft.jsonc 已包含全部插件 key，开箱即用；bark-notify 填 key 才真正激活，其余开箱即用。需停用某插件，在其 entry 写 "disabled": true。缺依赖的插件会在 debug 日志（craft/debug.log）中提示。

🚀 快速开始

1. 安装

npm install @becrafter/opencode-plugins
# 若安装输出提示依赖脚本未获准执行，手动运行（非交互注册）：
npx @becrafter/opencode-plugins setup --non-interactive

2. 注册并生成配置

# 交互式向导（TTY 中）：选择配置范围 → 勾选插件 → 按需填写配置 → 确认保存
npx @becrafter/opencode-plugins setup

# 非交互：注册到全局 opencode，生成全局 craft.jsonc（npm 安装时的默认行为）
npx @becrafter/opencode-plugins setup --non-interactive

# 直接配置当前项目（写入 <project>/.opencode/craft.jsonc；OpenCode 注册按规则处理）
npx @becrafter/opencode-plugins setup --project

setup 会自动：更新目标 opencode.json 的 plugin 数组注册本包（升级时替换旧条目）、在对应位置生成含插件模板的 craft.jsonc。

OpenCode 注册目标按以下规则决定：

• 全局 scope：使用 OpenCode 的全局配置目录（优先 $OPENCODE_CONFIG_DIR/opencode.json，否则 $XDG_CONFIG_HOME/opencode/opencode.json），缺失时创建；Craft 全局文件仍固定在 $XDG_CONFIG_HOME/opencode/craft.jsonc。
• 项目 scope：
  • 已有项目根 opencode.json：视为 legacy 配置，优先更新它，保留未知字段、注释和其他 plugin（不双写）。
  • 否则已有 .opencode/opencode.json：更新它。
  • 两者都没有：若全局 opencode.json 已注册本包，则不创建项目注册文件（项目直接继承全局），只写 .opencode/craft.jsonc；若全局未注册，则创建 .opencode/opencode.json 以保证项目可加载插件。

--remove 仅移除目标注册文件中的本包条目，不删除 craft 配置、不创建缺失的项目注册文件；--dry-run 只预览变更不写入。

3. 交互式配置向导

TTY 中直接运行 setup 会进入四步向导：

1. 配置范围：选择「全局配置」（$XDG_CONFIG_HOME/opencode/craft.jsonc）或「当前项目配置」（./.opencode/craft.jsonc），选项下显示真实路径；--project 可跳过此步。项目配置只写入项目级覆盖（稀疏），继承自全局的插件不会重复出现在项目文件里。OpenCode 注册目标同样按上述规则：全局已注册时项目不创建注册文件，需要项目级注册时使用 .opencode/opencode.json，已有根 opencode.json 则兼容更新。
2. 选择插件：列出每个插件的名称、介绍和当前状态（已启用/未启用/继承全局），空格切换启用，回车确认。
3. 全局设置：选择是否启用 debug（写入 craft/debug.log）。保持默认时不写入，项目范围下写 debug 会覆盖全局设置。
4. 配置插件：仅为选中的、带配置项的插件渲染表单。字段按 schema 渲染——文本用输入框、开关用「启用/关闭」、枚举用下拉、数字即时校验；secret（如 Bark key、API key）只显示来源并以隐藏方式输入，确认摘要不显示原值。带很多参数的插件（memory 等）把基础字段直接展示，高级字段收在「是否编辑高级配置」后面。项目范围下可一键把本地字段「恢复为继承全局」。
5. 确认保存：展示范围、目标文件、插件启停变化和字段 diff，确认后一次性原子写入。取消或 Ctrl-C 不会写入任何文件。

插件介绍与配置表单来自各插件目录的 setup.ts（src/plugins/<name>/setup.ts），setup 自动扫描编译产物 dist/plugins/*/setup.js——新增插件只要补一份 setup.ts 就会自动出现在向导里，无需改 setup 清单。

4. 配置插件（出现即启用，可逐项调整）

setup 生成的 craft.jsonc 已含全部插件 key——插件名出现在 plugins map 中即启用。只需按需调整参数（如填 Bark key、改模型），或对想停用的插件写 "disabled": true：

{
  "plugins": {
    "memory": {},                              // 记忆系统（dream 自动化需配 API key）
    "chinese-reply": {},                       // 强制中文回复
    "convention-injector": {},                  // 项目规范注入
    "bark-notify": { "key": "你的-bark-key" }, // 填 key 才激活通知
    "caveman": {},                             // token 压缩模式
    "cross-session": {},                       // 跨会话消息
    "press": { "disabled": true },             // 示例：停用 press（不写则启用，自动探测 opencode 已有模型）
    "super-goal": {}                           // 自主编码编排
  },
  "debug": false
}

依赖提示：bark-notify 缺 key、super-goal/press 的默认模型（deepseek）未在 opencode 配置、memory 的 dream 自动化缺 API key 时，都会在 debug 日志（craft/debug.log）中给出提示。

5. 启动使用

opencode

启用即生效——例如 memory 会在对话中自动注入记忆上下文、chinese-reply 强制中文回复、caveman 可通过 /caveman full 切换压缩模式、/goal 与 /press 命令可直接使用。

⚙️ 配置

配置位置

craft.jsonc 支持两级，项目覆盖全局（与 opencode 惯例一致）：

| 位置 | 说明 | |------|------| | $XDG_CONFIG_HOME/opencode/craft.jsonc（默认 ~/.config/opencode/craft.jsonc） | 全局配置（不受 OPENCODE_CONFIG_DIR 影响） | | <project>/.opencode/craft.jsonc | 项目级配置，覆盖全局同名项 |

准入规则

• plugins map 中出现插件 key 即启用；entry 写 disabled: true 才停用；不在 map 中则不加载
• 未配置 plugins（或值不是对象 map）时不加载任何插件——显式 opt-in
• 各插件参数（如 bark-notify.key、super-goal.worker.steps）写在 plugins.<name> 内

旧配置迁移：enabled 不再是插件准入字段。旧 "<name>": { "enabled": false } 表示停用，改为 { "disabled": true }；"enabled": true 可删除。旧数组 "plugins": ["memory"] 改为 map 形式。插件内部功能开关（memory.policy.*.enabled、super-goal.archReview.enabled）不受影响，不改名。

顶层字段

| 字段 | 类型 | 默认 | 说明 | |------|------|:---:|------| | plugins | object | 空（不加载） | 各插件开关与参数：出现即启用，disabled: true 停用 | | debug | boolean | false | 是否输出 debug 日志 | | connectors | object | — | 按 provider 配置凭证：connectors[provider].apiKey、connectors[provider].override.baseURL（memory daemon 等读取） |

📦 各插件配置详解

📝 memory — 记忆系统

能力：记忆工具（search/save/list/status/checkpoint/hybrid_search 等）+ 上下文注入 + dream 自动化。 依赖：dream 自动化需 API key（daemon.apiKey / connectors / {PROVIDER}_API_KEY），缺则运行时在 debug 日志提示；基础记忆/注入无需额外配置。

policy（记忆策略，均有默认值，只需覆盖想改的）：

| key | 类型 | 默认 | 含义 | |-----|------|:---:|------| | policy.enabled | boolean | true | 记忆策略总开关 | | policy.injection.enabled | boolean | true | 上下文注入开关 | | policy.injection.budgetTokens | int | 2000 | 注入预算 token | | policy.injection.maxEntries | int | 12 | 注入最大条数 | | policy.search.defaultLimit | int | 5 | 搜索默认返回数 | | policy.search.ftsCandidateLimit | int | 40 | FTS 候选上限 | | policy.save.currentBranchTag | boolean | true | 保存时打当前分支 tag | | policy.automation.mode | string | manual | 自动化模式（manual|candidates） | | policy.automation.autoCapture.* | boolean/int | 全关 | 自动捕获（enabled/idleDebounceSeconds=30/maxCandidatesPerSession=8/maxSourceChars=12000） | | policy.automation.dream.* | boolean/int | 全关 | dream 认知（enabled/minDistinctSessions=2/maxJobsPerDay=1/maxAttempts=3/backoffSeconds=300） | | policy.automation.agent.* | string/int | model=null | 自动化 agent（model/maxSteps=8/maxConcurrentJobs=1/maxCostUsdPerDay=0） | | policy.embedding | string/object | none | 向量嵌入引擎 | | policy.profile.enabled | boolean | false | 用户画像开关 |

daemon（dream 自动化所用 LLM，仅启用 dream 时生效）：

| key | 类型 | 默认 | 含义 | |-----|------|:---:|------| | daemon.provider | string | Anthropic | 模型 provider | | daemon.model | string | claude-sonnet-4-6 | 模型 id | | daemon.apiKey | string | 空 | API key（可由 connectors[provider].apiKey 或 {PROVIDER}_API_KEY 提供） | | daemon.baseURL | string | 空 | 自定义 baseURL | | daemon.pollIntervalMs | int | 300000 | 轮询间隔（毫秒） |

"memory": {
  "policy": { "injection": { "budgetTokens": 4000 } },
  "daemon": { "provider": "AgnesAI", "model": "agnes-2.5-flash", "apiKey": "..." }
}

💬 chinese-reply — 强制中文回复

仅需出现在 plugins map 中即启用，无专属配置。开启后 system prompt 注入语言指令，强制中文回复。无依赖。

"chinese-reply": {}

📋 convention-injector — 项目规范注入

仅需出现在 plugins map 中即启用，无专属配置。读取项目目录约定文件注入 system prompt，优先级 agent.local.md > agent.md > claude.local.md > claude.md。无依赖。

"convention-injector": {}

🔔 bark-notify — 会话通知

key 填 Bark App 的推送密钥即激活；留空停用（并在 debug 日志提示）。依赖：Bark App 推送密钥（bark.day.app）。

"bark-notify": { "key": "your-bark-key" }

🦖 caveman — token 压缩模式

/caveman 命令切换 lite/full/ultra/off；模式记录在 flag 文件（全局 ~/.config/opencode/craft/caveman-active，项目 .opencode/craft/caveman-active 存在则项目优先），或用环境变量 CAVEMAN_DEFAULT_MODE 设默认（默认 full）。无依赖。

"caveman": {}

🔗 cross-session — 跨会话消息

同机多 opencode 会话互发消息（/peers 查看、/peers-name 设置名称）。无依赖。支持以下配置（均有默认值）：

| key | 类型 | 默认 | 含义 | |-----|------|:---:|------| | storageDir | string | ~/.config/opencode/craft/cross-session | 存储根目录（可经项目 craft.jsonc 覆盖） | | name | string | 目录 basename | 本实例 peer 名（1-32 字符 [A-Za-z0-9 _-]） | | inboundPolicy | string | accept | 入站消息策略（accept|auto|hold|refuse） | | peerPermissions | string | allow | peer 权限（allow|ask|deny） | | heartbeatMs | int | 10000 | 心跳间隔 | | staleMs | int | 30000 | 判定 stale 阈值 | | maxQueue | int | 50 | 每会话最大队列 | | maxHeld | int | 100 | 最大 hold 消息数 | | maxMessageBytes | int | 8192 | 单条消息最大字节 | | heldExpiryMs | int | 300000 | hold 过期时间 | | maxMessageAgeMs | int | 300000 | 消息最大存活时间 | | sendRatePerMin | int | 10 | 每分钟发送限速 | | recvRatePerMin | int | 20 | 每分钟接收限速 | | sweepMs | int | 15000 | 可靠性清扫周期 |

🎯 press — 方案压榨

/press、/press-review 命令 + press-* agent，通过行业识别、候选方案扩散、证据链评分、定向迭代优化方案。依赖：模型 provider（默认 deepseek/deepseek-v4-pro，需 opencode 已配置该 provider，否则运行时在 debug 日志提示）。

自适应模型：未在 orchestrator.model 显式配置时，自动探测 opencode 已配置的 provider/model，无需手动指定；探测不到才回退默认 deepseek。

模型分配：press-orch / press-generator / press-reviewer 三个 agent 复用 orchestrator.model（无独立 worker 模型）。

| key | 类型 | 默认 | 含义 | |-----|------|:---:|------| | orchestrator.model.providerID | string | deepseek | press-orch / generator / reviewer 的 provider | | orchestrator.model.id | string | deepseek-v4-pro | press-orch / generator / reviewer 模型 | | orchestrator.temperature | number | 0.1 | 生成温度（0-2） |

🚀 super-goal — 自主编码编排

/goal 命令 + goal-orch/goal-worker/goal-reviewer agent，覆盖需求分解、用户澄清、架构规划、worker 调度、审查修复。依赖：模型 provider（默认编排 deepseek/deepseek-v4-pro、worker deepseek/deepseek-v4-flash，需 opencode 已配置该 provider，否则运行时在 debug 日志提示）。

自适应模型：未在 orchestrator.model / worker.model 显式配置时，插件会自动探测 opencode 已配置的 provider/model（优先 Anthropic/OpenAI 等常用 provider，其次第一个可用 provider），无需手动指定；探测不到才回退默认 deepseek。

模型分配：goal-orch 与 goal-reviewer 复用 orchestrator.model；goal-worker 用 worker.model。

| key | 类型 | 默认 | 含义 | |-----|------|:---:|------| | orchestrator.model.providerID | string | deepseek | goal-orch / goal-reviewer 的 provider | | orchestrator.model.id | string | deepseek-v4-pro | goal-orch / goal-reviewer 模型 | | orchestrator.temperature | number | 0.1 | goal-orch / goal-reviewer 温度 | | worker.model.providerID | string | deepseek | goal-worker provider | | worker.model.id | string | deepseek-v4-flash | goal-worker 模型 | | worker.temperature | number | 0.1 | goal-worker 温度 | | worker.steps | int | 15 | goal-worker 最大执行步数 | | archReview.enabled | boolean | true | 架构评审开关 | | archReview.maxIterations | int | 2 | 审查最大迭代次数 | | archReview.dimensions | int | 6 | 评估维度数量 |

🗂️ 数据目录

opencode 专属插件的运行时数据统一收敛到 craft/ 子目录（全局 ~/.config/opencode/craft/，项目 <project>/.opencode/craft/，项目优先）：

| 数据 | 全局路径 | 项目路径（优先） | |------|---------|-----------------| | 调试日志 | ~/.config/opencode/craft/debug.log | <project>/.opencode/craft/debug.log | | caveman 模式 flag | ~/.config/opencode/craft/caveman-active | <project>/.opencode/craft/caveman-active | | cross-session 数据 | ~/.config/opencode/craft/cross-session/（默认，机器级） | 经 plugins.cross-session.storageDir 覆盖 |

memory 是公共插件（CC + OC 共用），数据在 ~/.craft-memory/（或 CRAFT_MEMORY_HOME），不在 craft/ 目录内。

从旧路径迁移（手动）：

# 日志（旧名 craft-plugins.log → 新位置+新名）
mv ~/.config/opencode/craft-plugins.log ~/.config/opencode/craft/debug.log 2>/dev/null || true
# caveman flag
mv ~/.config/opencode/.caveman-active ~/.config/opencode/craft/caveman-active 2>/dev/null || true
# cross-session 数据
mv ~/.local/share/opencode-plugin-peers ~/.config/opencode/craft/cross-session 2>/dev/null || true

不迁移则插件按新默认路径重建（旧数据保留在原处不再读取）。

🛠️ 调试

设置顶层 "debug": true 后输出两类日志：

1. 文件日志（项目优先、全局回退）：<project>/.opencode/craft/debug.log → ~/.config/opencode/craft/debug.log
2. OpenCode 结构化日志：client.app.log()，用 opencode --print-logs --log-level DEBUG 查看

内容含插件初始化、钩子入口、子插件执行和脱敏的工具摘要。OPENCODE_CONFIG_DIR 不改变 Craft 全局配置或全局日志目录。

配置合并与优先级

• 全局配置先加载，项目配置后加载；项目顶层字段覆盖全局同名项
• plugins map 及插件内部对象递归合并（项目覆盖全局）
• 插件调用参数中的 options.plugins 只覆盖子插件准入列表，不替代 craft.jsonc 选项

opencode 本体的 opencode.json 独立于 craft.jsonc，优先级：OPENCODE_CONFIG_DIR（若设置）> 项目 .opencode/opencode.json > 全局 ~/.config/opencode/opencode.json；标量字段高优先级覆盖、map 字段同名覆盖不同名合并。用 opencode debug config 查看解析结果。

🧩 setup 元数据（setup.ts）

交互向导的插件介绍与配置表单来自每个插件的 src/plugins/<name>/setup.ts，导出纯数据的 setupMeta（不导入 @opencode-ai/plugin，不依赖运行时）。编译后位于 dist/plugins/<name>/setup.js，被 setup 自动扫描发现——新增插件只需补一份 setup.ts，无需改动 setup 清单。

import type { PluginSetupMeta } from "../types.js";

export const setupMeta: PluginSetupMeta = {
  name: "bark-notify",            // 必须与运行时 meta.name 一致
  description: "会话完成、错误或待授权时推送 Bark 通知",
  schema: {
    fields: [
      {
        path: "key",               // 插件 entry 内的点路径，如 "orchestrator.temperature"
        label: "Bark Key",
        type: "secret",            // text | secret | number | integer | boolean | select
        description: "Bark App 推送密钥",
      },
    ],
  },
};

SetupField 支持：path、label、description、type、default（仅展示，不写入）、options（select 必填，value/label/description）、min/max（number/integer 校验）、section（表单分组标题）、advanced（收进「编辑高级配置」）。无配置的插件用 schema: { fields: [] }。

元数据只负责展示、输入与校验；插件运行时的默认值、自动模型探测等逻辑仍由各插件 resolver 决定，setup 不会把这些默认值物化进 craft.jsonc。

卸载

# 从 opencode.json 移除插件注册
npx @becrafter/opencode-plugins setup --remove

# 卸载 npm 包
npm uninstall @becrafter/opencode-plugins

许可证

MIT