opencode-workbench

OpenCode Workbench

可复现、自我记录且可恢复的 OpenCode 开发工作站 — 配置、Agent 技能、MCP 技术栈，以及一个可将整套配置克隆到任何 Linux 机器上的 MCP 服务（本地或通过 SSH）。

主页和远程 MCP： https://opencode-workbench.simonmak.com · POST https://opencode-workbench.simonmak.com/mcp

概览

此仓库是完整云开发工作站的唯一事实来源。从头重建所需的一切都在此进行版本管理：

• 工作站配置和自动化
• OpenCode 配置（模型、提供商、MCP 服务）
• Agent 技能（45 条可复用 AI 指令，涵盖研究、开发、数据、科学和运维）
• 运维提示词（灾难恢复、备份、安全）
• 恢复流程（操作手册、检查清单、差距分析）
• 安全治理（密钥管理、威胁模型）
• OpenCode 沙盒（bubblewrap）——在只读系统且不挂载任何密钥的环境中运行 Agent
• opencode-workbench——一个可在任何 Linux 机器上安装此配置的 MCP 服务

没有任何重要知识只存在于人的记忆中。

将此 Workbench 克隆到另一台 Linux 机器

向 OpenCode 注册 MCP 服务：

{
  "mcp": {
    "opencode-workbench": {
      "type": "local",
      "command": ["npx", "-y", "@simonmak-ascent/opencode-workbench"],
      "enabled": true,
      "timeout": 600000
    }
  }
}

然后让 Agent 依次运行 inspect_target → plan_clone → apply_clone { confirm: true } → verify_clone，目标可以是 { "mode": "local" } 或 { "mode": "ssh", "host": "<your-box>", "user": "<your-user>" }。apply_clone 需要获得同意：如果没有 confirm:true，它只会返回计划（组件 + 特权命令预览），不会进行任何更改。运行 list_required_credentials 可查看这台机器还需要哪些密钥以及如何获取；运行 bash scripts/selftest/run-selftest.sh 可验证其是否正常工作。参见 mcp-server/README.md 和 docs/architecture/clone-mcp.md。

此克隆过程不依赖密钥也能运行：即使没有模型密钥，也能通过 OpenCode Zen 免费基础配置启动；缺少凭据的 MCP 服务会被禁用并报告，而不会等到运行时才失败。

连接器不会读取或传输密钥值；它会写入一个空的 ~/.env.workbench 模板，供你填写。

快速开始（≤ 5 分钟）

**最快方式：**无需准备机器——使用 npx -y @simonmak-ascent/opencode-workbench 注册 MCP 服务（配置见 将此 Workbench 克隆到另一台 Linux 机器）；或者配置一台新机器：

# Create a new build box
gh SWAS create --repo simonmak-ascent/opencode-workbench --machine basicLinux32gb

# Wait for postCreate (3-5 min) — installs everything automatically
# Then start coding:
opencode

架构

flowchart TB
  AGENT["OpenCode agent"] -->|"npx @simonmak-ascent/opencode-workbench"| MCP["opencode-workbench MCP<br/>inspect · plan · apply · verify"]
  REPO[("Git repo — single source of truth")] --> MCP
  MCP -->|"local or SSH"| BOX["Target Linux box"]
  BOX --> PROF["Workstation profile<br/>OpenCode CLI · 35 MCP servers · 45 skills · Docker infra"]

克隆生命周期

apply_clone 需要获得同意：如果没有 confirm: true，它只会返回计划，不会进行任何更改。

sequenceDiagram
    autonumber
    participant A as OpenCode agent
    participant M as opencode-workbench MCP
    participant B as Target box (local or SSH)
    A->>M: inspect_target
    M-->>A: OS, toolchain, Docker, existing config
    A->>M: plan_clone
    M-->>A: components + privileged-command preview
    A->>M: apply_clone { confirm: true }
    M->>B: install components · write ~/.env.workbench template
    B-->>M: result
    A->>M: verify_clone
    M-->>A: pass/fail + missing credentials

MCP 工具概览

flowchart LR
    A["OpenCode agent"] --> D["Discovery<br/>describe_workbench · inspect_target"]
    A --> C["Clone<br/>plan_clone · apply_clone · verify_clone"]
    A --> K["Components<br/>install · remove · update_component"]
    A --> S["Credentials<br/>list_required_credentials · run_auth_flow"]

opencode-workbench/
├── mcp-server/                     # opencode-workbench: clone this profile onto Linux
│   ├── src/                        # inspect / plan / apply / verify, local + SSH
│   ├── test/                       # unit tests (vitest)
│   └── README.md
├── connector.json                  # MCP connector manifest / registration snippet
├── plugins/                        # memory.ts + doc-tools.ts OpenCode plugins
├── package.json                    # thin launcher for opencode-workbench (bin + prepare)
├── .devcontainer/                  # build box definition & bootstrap
│   ├── devcontainer.json           # Container image, features, ports, remoteEnv
│   ├── setup.sh                    # Post-create: installs opencode, MCPs, Docker infra
│   └── aliases.sh                  # Shell aliases sourced at runtime
├── .opencode/
│   └── skills/                     # 28 custom agent skills (10 research, 10 dev, 8 publishing)
├── vendor/                         # Vendored MCP source code
│   ├── perplexity-agent-mcp/
│   └── browserless-mcp/
├── configs/                        # Reference configurations
│   ├── mcp/                        # MCP server inventory & architecture
│   ├── opencode/                   # OpenCode settings documentation
│   ├── shell/                      # Shell configuration
│   ├── git/                        # Git configuration & hooks
│   └── providers/                  # AI provider configuration
├── docs/                           # Complete documentation system
│   ├── WORKBENCH_CHARTER.md        # Governance: mission, principles, requirements
│   ├── security-model.md           # Security architecture & threat model
│   ├── IMPROVEMENT_BACKLOG.md      # Tracked improvements and fixes
│   ├── CHANGELOG_WORKBENCH.md      # Append-only change history
│   ├── architecture/               # System documentation (incl. clone-mcp.md)
│   ├── recovery/                   # Recovery procedures (4 docs)
│   ├── prompts/                    # Operational prompt library (9 prompts)
│   └── backup-reports/             # Dated backup snapshots
├── scripts/                        # Automation scripts
│   ├── backup/                     # Master backup script
│   ├── inventory/                  # Auto-generate inventories (software, env, MCP, OpenCode)
│   ├── security/                   # Secret pattern scanner
│   ├── recovery/                   # Recovery validation
│   └── maintenance/                # Config sync, routine tasks
├── .github/workflows/              # CI (docs, inventory, gitleaks, mcp-server)
├── opencode.json                   # OpenCode configuration (MCP servers)
├── AGENTS.md                       # OpenCode agent instructions
└── README.md                       # This file

包含内容

类别	详情
OpenCode	最新稳定版 CLI、DeepSeek V4 Pro 模型、已启用 LSP
MCP 服务	已配置 35 个（33 个已启用，2 个已禁用），9 个远程 + 26 个本地
Agent 技能	.opencode/skills/ 中有 45 个可复用技能
基础设施	PostgreSQL 16（Docker）、Browserless Chromium（Docker）
工具	pandoc、jq、miller、sqlite3、GitHub CLI、Playwright Chromium
提示词	docs/prompts/ 中有 9 个运维提示词

工作站治理

此工作站依照正式章程运行。核心原则：

• 唯一事实来源：运行时必须与仓库一致。出现偏差即为 Bug。
• 秘密绝不写入磁盘：所有秘密均通过构建箱 Secrets 流转。
• 历史不可篡改：变更日志只追加内容。每项变更均可追溯。
• 文档与代码共存：文档描述系统的实际状态，而非设想中的状态。

阅读完整章程：docs/WORKBENCH_CHARTER.md

备份工作流

# Master backup — full inventory, security scan, commit prep
bash scripts/backup/run-master-backup.sh

# Quick backup — save state before risky operations
bash scripts/maintenance/sync-runtime-config.sh && \
  git diff > /tmp/quick-backup-$(date +%Y%m%d).diff

也可使用 OpenCode 提示词：

• docs/prompts/RUN_MASTER_BACKUP.md — 通过 AI 执行备份
• docs/prompts/QUICK_BACKUP.md — 快速保留状态

恢复工作流

假设构建箱已删除。只有 Git 仓库和构建箱 Secrets 得以保留。

# 1. Create new build box
gh SWAS create --repo simonmak-ascent/opencode-workbench --machine basicLinux32gb

# 2. Wait for automation (3-5 min)

# 3. If needed (usually done by setup.sh):
npx playwright install chromium
# Vercel MCP uses VERCEL_ACCESS_TOKEN (token auth — no OAuth step)

# 4. Validate recovery
bash scripts/recovery/validate-recovery.sh

完整详情：docs/recovery/RECOVERY_PLAYBOOK.md

MCP 架构

类型	数量	备注
远程	9	context7、gh_grep、vdd、exa、cloudflare、clerk、vercel（令牌认证）、sentry、stripe
本地	26	npm / vendored / 二进制 stdio 服务

总计：已配置 35 个（33 个已启用，2 个已禁用：google-search、google-workspace）。

参见：docs/architecture/mcp-inventory.md

秘密管理

所有秘密均存储在构建箱 Secrets 中。绝不存放于仓库文件中。

#	秘密	使用方
1	DEEPSEEK_API_KEY	OpenCode（主模型）
2	OPENCODE_API_KEY	OpenCode Zen / Console Go 提供商
3	SIMONMAK_ASCENT_PAT	GitHub MCP、shadcn MCP、gh
4	PERPLEXITY_API_KEY	Perplexity MCP
5	BRAVE_API_KEY	Brave Search MCP
6	BROWSERLESS_TOKEN	Browserless MCP + 容器
7	SENTRY_AUTH_TOKEN	Sentry MCP
8	VERCEL_ACCESS_TOKEN	Vercel MCP（令牌认证）

用于选择性启用服务的其他密钥（EXA_API_KEY、CLOUDFLARE_API_TOKEN、 STRIPE_SECRET_KEY、SURREAL_*、ALIBABA_CLOUD_*、AZURE_*、FIRECRAWL_API_KEY、 FRED_API_KEY、COMPANIES_HOUSE_API_KEY）已列于 docs/architecture/secrets.md — 仅记录名称，不记录值。

参见：docs/architecture/secrets.md

文档索引

文档	用途
docs/WORKBENCH_CHARTER.md	使命、原则、治理
docs/security-model.md	安全架构、威胁模型、事件响应
docs/IMPROVEMENT_BACKLOG.md	已跟踪的改进项和技术债务
docs/CHANGELOG_WORKBENCH.md	完整变更历史
docs/architecture/	系统文档（10 份清单文档）
docs/recovery/	恢复手册、灾难恢复、检查清单、差距分析
docs/prompts/	9 个运维提示词及索引
docs/backup-reports/	带日期的备份快照

向工作台添加内容

1. MCP 服务：将 npm 包添加到 .devcontainer/setup.sh，添加到 opencode.json，并记录在 docs/architecture/mcp-inventory.md
2. Agent 技能：创建 .opencode/skills/<name>/SKILL.md，并遵循命名规范
3. 工具：添加到 scripts/bootstrap-tools.sh
4. 提示词：在 docs/prompts/ 中创建，并更新 prompt-index.md
5. 每次变更后：更新 CHANGELOG_WORKBENCH.md，运行主备份

恢复评分：94/100

已验证仅使用仓库和构建箱 Secrets，即可在 < 10 分钟内完成灾难恢复。

与 Context7 配合使用

Context7 已索引最新的 OpenCode Workbench 文档，编码 Agent 可以按需将其纳入上下文。安装 Context7 MCP 服务或 ctx7 CLI 后，在提示词中指定库名：

use library /simonmak-ascent/opencode-workbench for API and docs

许可证

MIT — 请参阅 LICENSE。

---

由 Simon Mak 开发的工具。

如果它为你节省了时间，在 GitHub 上点个 ⭐，能帮助更多人发现它。