OpenCode Starter

一个用于安装和配置 OpenCode 的个人私有 starter 仓库模板。

本仓库面向 个人私有配置复用：模板可以包含个人 provider、MCP、模型、agent、command、本机插件路径、私有 URL，以及 {file:/Users/.../secrets/...} 形式的 secret 文件引用。仓库仍不得包含任何明文 API key、access token、Authorization bearer token 或 secret 文件内容；不要把该模板作为公共模板发布或分享，除非先完成脱敏。

快速安装

推荐 npm/npx 安装：

npx -y @junyou/opencode-starter install

npm CLI 安装会写入 npm plugin spec：@junyou/opencode-starter@^0.1.10。它不会把本地 maintainer plugin 文件复制到你的 OpenCode 配置目录。

也可以保留 repo-based 安装路径，在仓库目录运行：

./install.sh

repo-based 安装会使用本地 plugin copy，并在 opencode.json 中写入 ./plugins/opencode-starter-maintainer.js。

默认行为：

• 不自动安装 OpenCode。
• 如果系统中没有 opencode 命令，会提示你使用 --install-opencode。
• 使用 ${XDG_CONFIG_HOME:-$HOME/.config}/opencode 作为 OpenCode 配置目录。
• 从 templates/opencode.jsonc 配置 OpenCode 主配置。
• 从 templates/oh-my-opencode-slim.jsonc 配置 oh-my-opencode-slim。
• repo-based 安装会复制 plugins/opencode-starter-maintainer.js 到 OpenCode 配置目录的 plugins/ 下。
• 如果目标配置已存在，不会覆盖；会复制 .example.jsonc 文件并提示你手动合并。
• 会安全维护全局 OpenCode AGENTS.md（${XDG_CONFIG_HOME:-$HOME/.config}/opencode/AGENTS.md）中的 OPENCODE-STARTER:RUNBOOKS managed block，用于提示 agent 按需查询远程 runbook；该操作不会改任何项目内 AGENTS.md。
• npm CLI 安装会默认尝试准备官方 GitHub Spec Kit CLI（specify）：uv tool install specify-cli --from git+https://github.com/github/[email protected]。失败只输出 warning，不阻断 starter 配置安装；它不会在任何项目中自动运行 specify init。

可选参数：

./install.sh --install-opencode
./install.sh --overwrite-config
./install.sh --install-opencode --overwrite-config
npx -y @junyou/opencode-starter install --no-speckit
./install.sh --help

参数说明：

• --install-opencode：当 opencode 命令不存在时，运行官方安装命令： curl -fsSL https://opencode.ai/install | bash
• --overwrite-config：允许覆盖已有配置文件。覆盖前会为每个已有文件创建带时间戳的备份。
• --no-speckit（npm CLI）：跳过默认 GitHub Spec Kit CLI 安装尝试。也可设置 OPENCODE_STARTER_NO_SPECKIT=1（兼容别名：OPENCODE_STARTER_SKIP_SPECKIT=1）。
• --help：显示帮助信息。

安装或更新配置后，请重启 OpenCode 以加载新配置。

发版维护流程见 docs/release.md，其中包含 package exports、OpenCode plugin server entrypoint、publish 后检查和 cache refresh / restart 注意事项。

维护本仓库源码时，新 feature 或 release-affecting work 可先查看 .specify/memory/constitution.md 与 .specify/templates/ 中的 repo-local gates，再进入 release runbook；这些文件只提供本仓库 SDD 入口，不表示已安装或配置 specify CLI，也不是 npm 消费者必须使用的配置。

Doctor 诊断

doctor 是只读诊断命令，不会修改 OpenCode 配置、缓存、registry 设置或文件：

npx -y @junyou/opencode-starter doctor
npx -y @junyou/opencode-starter doctor --config-dir "${XDG_CONFIG_HOME:-$HOME/.config}/opencode" --json

它会安全检查当前包版本、opencode.json 是否存在、已声明的 plugin spec、starter/required plugin 是否缺失、skills URL、OpenCode cache 中的 skills 和 starter package 版本，以及 npm latest / skills feed 可访问性。输出只包含经过净化的诊断字段；不会打印 provider、model、options 等可能包含密钥的配置段。

输出中的 OK 表示该项看起来可用，MISSING 表示文件、cache 或配置项不存在，WARN 表示需要人工确认，INFO 只提供上下文。doctor 不会安装、覆盖、清 cache、改 registry 或重启 OpenCode；需要修复时再运行 install、手动合并配置，或使用 /starter-update、/starter-update-skills 刷新缓存。更多检查项和处理建议见 docs/configuration.md。

GitHub Spec Kit（OpenCode）

Spec Kit 是 GitHub 的官方项目；CLI 命令名是 specify。opencode-starter install 默认会尝试用 uv 全局准备官方 CLI：

uv tool install specify-cli --from git+https://github.com/github/[email protected]

如果这一步失败，starter 只输出 warning 并继续安装 OpenCode 配置。若不希望安装阶段触发该尝试，可使用 opencode-starter install --no-speckit，或设置 OPENCODE_STARTER_NO_SPECKIT=1。

全局 CLI 准备好后，本 starter 仍不会隐式改写你的项目；每个目标项目仍需你在项目目录显式运行：

specify init . --integration opencode

也可以让 CLI 打印完整说明：

npx -y @junyou/opencode-starter speckit
npx -y @junyou/opencode-starter speckit --project-dir /path/to/project

speckit 子命令只输出命令，不执行、不写文件。推荐安装来源是 GitHub 仓库：

uv tool install specify-cli --from git+https://github.com/github/[email protected]

在目标项目内初始化 OpenCode 集成仍是显式手动步骤：

specify init . --integration opencode

如果当前机器没有 opencode CLI，但仍希望生成模板，可加：

specify init . --integration opencode --ignore-agent-tools

初始化后通常会出现 .opencode/commands/*.md（OpenCode slash commands 的模板来源）、AGENTS.md 的 SPECKIT 托管区块，以及 .specify/。doctor 会对当前目录做只读检查，缺失时提示 specify init . --integration opencode。Windows PowerShell 下的 uv tool install ... --from git+... 和 specify init 语法尚未在本 starter 中做端到端验证；如遇 shell quoting 问题，请按 GitHub Spec Kit 官方文档调整。

Update 缓存维护

update 是安全维护命令，默认只做 dry-run。--apply 会刷新全局 OpenCode AGENTS.md 的 runbook managed block，并清理 starter package cache；它不会覆盖 opencode.json、不会改 provider/model/options、不会改 npm registry 设置，也不会重启 OpenCode：

在 OpenCode 内推荐使用显式命令 /starter-update 刷新 starter plugin cache，或 /starter-update-skills 同时刷新 remote skills cache；执行后请重启 OpenCode。

直接 shell 路径：

npx -y @junyou/opencode-starter update
npx -y @junyou/opencode-starter update --dry-run
npx -y @junyou/opencode-starter update --apply
npx -y @junyou/opencode-starter update --apply --skills

它读取 opencode.json 中当前的 starter npm plugin spec，用来定位 ${XDG_CACHE_HOME:-$HOME/.cache}/opencode/packages/<plugin spec>；同时只维护全局 OpenCode 配置目录下的 AGENTS.md managed block，不会触碰项目内 AGENTS.md。--apply 会删除该 starter package cache；--skills 才会额外删除 ${XDG_CACHE_HOME:-$HOME/.cache}/opencode/skills。配置缺失或 cache 不存在都不会报错。应用后请手动重启 OpenCode，让 OpenCode 重新加载 starter plugin 和远程 skills cache。

远程 runbook 规则（全局 AGENTS）

install 和 update --apply 会幂等维护全局 OpenCode AGENTS.md 中的 managed block：

<!-- OPENCODE-STARTER:RUNBOOKS START -->
...
<!-- OPENCODE-STARTER:RUNBOOKS END -->

该 block 要求 agent 在任务涉及稳定、可复用、步骤化操作流程时，先读取 https://runbooks.junyou.me/runbooks/index.json，再根据 triggers / owner_skills / risk_level 选择匹配 runbook，只读取命中的 Markdown，不把全部 runbook 常驻上下文。若远程 runbook 与用户指令、本地仓库文档或本地 AGENTS.md 冲突，应以后者为准并报告冲突。

安全边界：starter 只写 ${XDG_CONFIG_HOME:-$HOME/.config}/opencode/AGENTS.md 的 managed block；保留用户已有内容，已存在旧 block 时替换为最新版，避免重复插入。它不会静默写入任何用户项目目录的 AGENTS.md。

配置内容

模板文件位于：

templates/opencode.jsonc
templates/oh-my-opencode-slim.jsonc
plugins/opencode-starter-maintainer.js
package.json
bin/opencode-starter.js

opencode.json 是个人私有主配置模板，包含：

• $schema：OpenCode 配置 schema。
• plugin：启用插件：
  • repo-based 安装：./plugins/opencode-starter-maintainer.js
  • npm/npx 安装：@junyou/opencode-starter@^0.1.10
  • file:///Users/junyou/.config/opencode/plugins/company-skills.ts
  • @warp-dot-dev/[email protected]
  • oh-my-opencode-slim@^2.0.4
  • @cortexkit/opencode-magic-context@^0.30.1
  • opencode-caffeinate
  • [email protected]
• command：提供显式内部命令 /starter-update 和 /starter-update-skills，用于刷新全局 AGENTS runbook block 和 starter cache；不会自动运行。
• skills.urls：远程 skills 源： https://skills.junyou.me/skills/
• compaction：使用 auto: false、prune: false，让 magic-context 或外部插件更容易接管上下文管理。
• disabled_providers：默认禁用 github-copilot，避免未登录 Copilot 自动干扰。
• model / small_model：保留个人默认模型。
• provider / mcp：保留个人 provider、私有 endpoint、MCP、本机命令和 {file:...} secret 引用；不展开 secret 文件内容。
• agent：保留 build / plan 的 options.store: false，以及 compaction / summary / title 的个人模型默认值。

oh-my-opencode-slim.jsonc 包含：

• preset: "mine" 和 council.default_preset: "mine"；默认使用“我目前的配置”，尽量同步本机 ~/.config/opencode/oh-my-opencode-slim.jsonc 的 agent model / variant / skills / mcps、fallback、council、subtask、todoContinuation。
• 6 个推荐 preset key：
  • gpt-only：完全 GPT，仅使用 OpenAI 模型（主模型 openai/gpt-5.5，轻量代理可用 openai/gpt-5.4-mini）。
  • claude-only：完全 Claude，仅使用 Anthropic 模型（高判断 anthropic/claude-opus-4-8，默认/轻量 anthropic/claude-sonnet-4-6）。
  • claude-primary：Claude 为主、GPT 为副；按 agent 分配 provider，Claude 负责 orchestrator / oracle / designer / council，GPT 负责 explorer / librarian / fixer。普通 agent 的 model 数组只包含所属 provider 的模型；同 provider 内可保留强/轻 fallback。
  • gpt-primary：GPT 为主、Claude 为副；按 agent 分配 provider，GPT 负责 orchestrator / oracle / fixer / council，Claude 负责 explorer / librarian / designer。普通 agent 的 model 数组只包含所属 provider 的模型；同 provider 内可保留强/轻 fallback。
  • gpt-glm-primary：GPT 为主、GLM 为副；按 agent 分配 provider，GPT 负责 orchestrator / oracle / fixer / designer / council，GLM 负责 explorer / librarian。普通 agent 的 model 数组只包含所属 provider 的模型；不是跨 provider fallback。
  • mine：我目前的配置；保留本机 GLM fallback 和本机 MCP / skills 路由。
• starter 与 openai-preset 仅作为兼容 alias 保留，不再作为推荐默认。
• 这些 preset 属于 oh-my-opencode-slim 配置文件，不是 OpenCode core opencode.json 字段；不要把 preset / presets 写进 templates/opencode.jsonc。
• 切换方式：修改 templates/oh-my-opencode-slim.jsonc（模板）或安装后的 ~/.config/opencode/oh-my-opencode-slim.jsonc 中的 preset，并同步修改 council.default_preset 为同名 key；保存后重启 OpenCode。
• orchestrator、oracle、librarian、explorer、designer、fixer、council 的基础配置。
• 温和的 fallback 默认值。
• council 的默认 preset、超时、并行执行和重试配置；6 个推荐 preset 都有对应 council preset，其中 gpt-only 只有 OpenAI councillors、claude-only 只有 Anthropic councillors、mixed preset 可以同时包含主副 provider 且顺序体现主副，gpt-glm-primary 为 GPT 在前、GLM 在后，mine 同步本机 gpt55 / sonnet / glm52。

模板包含个人 provider、MCP、模型和私有 endpoint 配置；密钥只能通过 {file:...} 或 {env:...} 这类引用提供，不得把 secret 文件内容展开进仓库。若要共享给他人或公开发布，必须先移除个人 provider/MCP、本机路径、私有 URL、账号/组织信息和所有 secret 引用。

OpenCode 会按 plugin 机制根据包名拉取/加载插件；如果插件尚未安装，通常不需要在本仓库提交插件代码。

外部 npm 插件在模板中使用 caret 版本范围 pin（例如 @^2.0.4）。这样可以挡住上游 major breaking change 静默进入，同时允许兼容的 patch/minor 更新。升级插件时，手动把 opencode.json 中的版本号改到目标版本范围，然后重启 OpenCode 让新配置生效。

Maintainer plugin

plugins/opencode-starter-maintainer.js 是本 starter 自带的维护插件。repo-based 安装会作为本地插件复制；npm/npx 安装会通过 npm plugin spec 加载。它会在 OpenCode 读取配置时做轻量规范化：

• 确保 skills.urls 包含 https://skills.junyou.me/skills/，且不重复。
• 当 compaction.auto 或 compaction.prune 未设置时填入 false 默认值；如果用户已显式设置，则保留用户值。
• 确保 disabled_providers 包含 github-copilot，且不重复。
• 检查 plugin 中是否声明了 oh-my-opencode-slim@^2.0.4 和 @cortexkit/opencode-magic-context@^0.30.1；匹配时按包名比较，缺失或未 pin 版本时只输出 warning。其他个人可选插件不作为 required plugin 强制要求。
• 检测旧的 tianbm.github.io/opencode-skills URL，并提示迁移。
• 启动后异步检查 npm latest；如果发现 @junyou/opencode-starter 有新版本，只输出提示，不会自动更新、清缓存或安装，也不会阻塞 OpenCode 启动。

边界：该插件不会热更新配置、不会动态加载新插件，也不会删除用户已有配置；它只能在 config(cfg) hook 中规范化配置并输出简短 warning。修改本插件、opencode.json 或相关插件列表后，需要重启 OpenCode。

如需关闭更新提示，可在 npm plugin entry 中传入 options：

["@junyou/opencode-starter@^0.1.10", { "updateCheck": "off" }]

升级 starter 后仍需重启 OpenCode 才会加载新版本。

安全边界

本仓库是个人私有 starter，不再按公共模板过滤个人 provider、MCP、本机插件路径或私有 endpoint。硬性安全边界是：

• 禁止提交明文 API key、access token、bearer token、Authorization header 值或 secret 文件内容。
• 允许保留 {file:/Users/junyou/.config/opencode/secrets/...} 和 {env:...} 这类 secret 引用。
• 允许保留个人本机路径、私有 URL、私有 MCP 和个人 provider/model 配置。
• 不要把该仓库作为公共模板发布、fork 给他人或贴到公开文档；若必须共享，先做完整脱敏。

文件结构

.
├── .github/
│   └── workflows/
│       └── ci.yml
├── docs/
│   ├── agent-runbook.md
│   └── configuration.md
├── bin/
│   └── opencode-starter.js
├── plugins/
│   └── opencode-starter-maintainer.js
├── scripts/
│   └── validate.sh
├── templates/
│   ├── opencode.json
│   └── oh-my-opencode-slim.jsonc
├── package.json
├── README.md
├── install.sh
└── .gitignore

验证

提交前建议运行：

./scripts/validate.sh

该脚本会检查 shell 语法、模板 JSONC 可解析性、个人模板字段白名单、关键默认值（例如 local maintainer 插件、magic-context ^0.30.1、build/plan options.store: false），以及文档和模板中是否误包含明文 secret 形态文本。它允许 {file:...} secret 引用、个人本机路径和私有 URL。

Agent 执行手册

如果由 AI agent 代为安装、更新或排查本 starter，请先阅读 docs/agent-runbook.md。该手册规定了安装流程、已有配置合并规则、验证清单和安全边界；doctor 只是只读诊断入口，不替代手动合并和用户确认。

安全说明

• 不要把 API key、token、.env 或 secret 文件内容提交到仓库。
• 该仓库是个人私有模板，可以保留个人 provider、MCP、本机插件路径、私有 endpoint 和 {file:...} secret 引用。
• 如果你需要共享配置，请先删除所有密钥引用、私有 endpoint、本机路径、账号名、组织信息和个人 provider/MCP 配置。
• install.sh 默认不会覆盖已有配置，避免误删你的本地设置。
• 使用 --overwrite-config 时，脚本会先备份已有配置文件。

更新说明

当 npm 包版本更新后，可以重新运行：

npx -y @junyou/opencode-starter install

如果只需要让 OpenCode 下次启动时重新拉取当前 starter npm plugin cache，可以先运行：

/starter-update

如果还要刷新 remote skills cache，请在 OpenCode 内运行：

/starter-update-skills

直接 shell 路径仍可使用：

npx -y @junyou/opencode-starter update --apply

若同时需要刷新 remote skills cache，再添加 --skills。该命令只会维护全局 OpenCode AGENTS.md 的 runbook managed block 和 cache，不会覆盖 opencode.json，也不会改 provider、model、options 或 registry 设置。

如果你确认要用 npm 包模板覆盖现有配置，可以添加 --overwrite-config：

npx -y @junyou/opencode-starter install --overwrite-config

npm/npx 更新后请重启 OpenCode。若已有配置未覆盖，按生成的 .example.jsonc 手动合并。

注意：如果当前机器已加载的是 0.1.0，该版本还没有更新提示能力。升级到 0.1.1 或更高版本前，需要先手动清一次 OpenCode npm plugin cache 并重启；之后它才能提示未来版本。

当 repo clone 模板更新后，可以在仓库目录重新运行：

./install.sh

如果你已经有本地配置，脚本会把新模板复制到：

${XDG_CONFIG_HOME:-$HOME/.config}/opencode/opencode-starter.example.json
${XDG_CONFIG_HOME:-$HOME/.config}/opencode/oh-my-opencode-slim.example.jsonc
${XDG_CONFIG_HOME:-$HOME/.config}/opencode/opencode-starter-maintainer.example.js

然后你可以手动对比并合并需要的字段。

如果你确认要用模板覆盖现有配置，可以运行：

./install.sh --overwrite-config

覆盖前脚本会创建备份，例如：

opencode.json.backup.20260619-120000
oh-my-opencode-slim.jsonc.backup.20260619-120000
opencode-starter-maintainer.js.backup.20260619-120000