OpesPro OpenCode — AI Agent Harness for Chinese Enterprise

企业级 AI Agent 编排平台 | OpenCode Plugin — 12 Agents + 20 Skills + 8 Hooks + Background Task Manager + Model Preset Switcher

概述 / Overview

OpesPro OpenCode 是面向中国企业场景的 OpenCode 插件平台，提供完整的多 Agent 编排能力。

OpesPro OpenCode is an OpenCode plugin platform for Chinese enterprise scenarios, providing full multi-agent orchestration capabilities.

| 能力 / Capability | 数量 / Count | 说明 / Description | |------------------|-------------|-------------------| | Agents | 12 | 2 primary (architect, executor) + 10 subagents | | Skills | 20 | 业务分析 / Bug 修复 / 代码审查 / Git 操作 / 驾驶舱生成 / 样式优化 | | Hooks | 8 | orchestrator / context-injector / rules-injector / edit-recovery / task-retry / agent-reminder / keyword-detector / session-notifier | | Tools | 9 | 后台任务(3) + Git 多平台(6) | | Model Presets | 3 | opencode-go / livedata / budget 一键切换 |

快速开始 / Quick Start

# 1. Install / 安装
npm install opespro-opencode

# 2. Register in OpenCode / 注册到 OpenCode
#    编辑 ~/.config/opencode/opencode.jsonc，添加：
#    { "plugin": ["opespro-opencode"] }

# 3. Configure models / 配置模型预设
cp opespro-opencode/opespro-opencode.jsonc.example .opencode/opespro-opencode.jsonc

# 4. Restart OpenCode / 重启 OpenCode
#    Agents、Skills、Hooks 自动加载

安装后发生了什么 / What Happens After Install

npm install opespro-opencode
    │
    ├─▶ node_modules/opespro-opencode/     ← npm 完整包
    │
    └─▶ postinstall.mjs 自动执行：
         ├─▶ dist/index.js  → ~/.config/opencode/plugins/opespro-opencode.js   ← 主插件入口
         ├─▶ agents/*.md    → ~/.config/opencode/agents/                        ← Agent 定义
         └─▶ skills/*/SKILL.md → ~/.config/opencode/skills/                     ← 技能定义

⚠️ plugins/opespro-opencode.js 不可删除！ 这是 OpenCode 自动发现并加载插件的主入口文件。删除后插件将无法加载。

项目结构 / Project Structure

opespro-opencode/
├── package.json                 # npm 包定义
├── tsconfig.json                # TypeScript 配置
├── meta-skill.yaml              # Skill ↔ Agent 路由注册表（298 行）
├── postinstall.mjs              # 安装后自动部署脚本
├── opespro-opencode.jsonc.example  # 模型预设配置模板
│
├── agents/                      # 12 个 Agent 定义（Markdown frontmatter）
│   ├── architect.md             # primary — 架构设计 / 任务编排
│   ├── executor.md              # primary — 原子任务执行
│   ├── router.md                # subagent — 意图识别 / 技能路由
│   ├── analyst.md               # subagent — 业务分析 / 需求建模
│   ├── builder.md               # subagent — 静态页面 / 驾驶舱设计
│   ├── debugger.md              # subagent — Bug 修复 / 诊断
│   ├── git-master.md            # subagent — Git 操作 / 工作流
│   ├── historian.md             # subagent — 演进追踪 / 变更日志
│   ├── craftsman.md             # subagent — 技能创建 / 维护
│   ├── librarian.md             # subagent — 知识检索（只读）
│   ├── looker.md                # subagent — 多模态理解（只读）
│   └── scribe.md                # subagent — 文档 / 图表编写
│
├── skills/                      # 20 个专业技能（每个目录含 SKILL.md + 可选 references/）
│   ├── easy/SKILL.md            # 智能路由（自然语言 → 最佳技能）
│   ├── auto/SKILL.md            # 复杂任务编排 + 并行调度
│   ├── expert/SKILL.md          # 直接技能调用
│   ├── ba/SKILL.md              # 业务分析 / 需求建模
│   ├── baseline/SKILL.md        # 业务基线提取
│   ├── bpm-workflow/SKILL.md    # BPM 审批流程设计
│   ├── bug-fixer/SKILL.md       # Bug 修复与诊断
│   ├── code-review/SKILL.md     # 代码审查
│   ├── security-check/SKILL.md  # 安全审计
│   ├── cockpit-page-builder/SKILL.md  # 驾驶舱 HTML 页面生成
│   ├── style-optimizer/SKILL.md # 前端样式优化
│   ├── git-safe/SKILL.md        # Git 安全操作
│   ├── git-workflow/SKILL.md    # Git 工作流指导
│   ├── module-doc/SKILL.md      # 代码模块文档化
│   ├── evo-tracker/SKILL.md     # 项目演进追踪
│   ├── workspace-manager/SKILL.md  # 工作空间管理
│   ├── model-preset/SKILL.md    # 模型预设切换
│   ├── skill-builder/SKILL.md   # 技能创建向导
│   ├── skill-maintainer/SKILL.md   # 技能批量维护
│   └── skill-refresh/SKILL.md   # 技能缓存刷新
│
├── schema/
│   └── config.schema.json       # opespro-opencode.jsonc 的 JSON Schema
│
├── scripts/
│   ├── verify-models.ts         # 模型解析验证（12 Agent × 3 Preset）
│   └── verify.sh                # 插件完整性检查（18 项）
│
└── src/                         # TypeScript 源码（116 模块）
    ├── index.ts                 # 插件主入口
    ├── agents/                  # Agent 注册 & Markdown 解析
    ├── config/                  # 配置加载 & 模型解析 & Provider 发现
    ├── hooks/                   # 8 个生命周期 Hook
    │   ├── orchestrator/        # Task 委派引导 + .opop 任务追踪
    │   ├── rules-injector/      # 项目规则自动注入
    │   ├── edit-recovery/       # 编辑失败自动恢复
    │   ├── task-retry/          # Task 失败重试指导
    │   ├── context-injector/    # 会话压缩上下文保存
    │   ├── keyword-detector/    # 关键词检测 → 技能推荐
    │   ├── agent-reminder/      # 委派使用提醒 + 状态持久化
    │   └── session-notifier/    # 会话生命周期日志
    ├── features/
    │   ├── workspace/           # OpopManager — .opop 目录完整管理
    │   ├── git-platform/        # 多平台 Git 操作 + 凭证加密
    │   ├── skill-loader/        # 技能安装 & 发现
    │   ├── meta-skill/          # meta-skill.yaml 解析 & 触发词索引
    │   └── background-agent/    # 后台任务管理器
    ├── tools/
    │   ├── background-task/     # 后台任务工具注册
    │   └── git-operations/      # Git 多平台工具注册
    └── shared/                  # 常量 / 日志 / 路径 / 哈希工具

Agent 体系 / Agent Architecture

分类 / Classification

| Agent | 类型 / Type | 角色 / Role | 默认模型 / Default Model | |-------|------------|------------|------------------------| | architect | primary | 系统架构设计与任务编排 / Architecture & Task Orchestration | go/reasoning | | executor | primary | 原子任务执行 / Atomic Task Execution | go/coding | | router | subagent | 意图识别与技能路由 / Intent Recognition & Routing | go/small | | analyst | subagent | 业务分析与需求建模 / Business Analysis | go/reasoning | | builder | subagent | 静态页面与驾驶舱设计 / Static Page & Cockpit Design | go/coding | | debugger | subagent | Bug 修复与诊断 / Debugging & Diagnostics | go/reasoning | | git-master | subagent | Git 操作与工作流 / Git Operations | go/coding | | historian | subagent | 演进追踪与变更日志 / Evolution Tracking | go/general | | craftsman | subagent | 技能创建与维护 / Skill Maintenance | go/coding | | librarian | subagent | 知识检索（只读）/ Knowledge Retrieval (read-only) | go/knowledge | | looker | subagent | 多模态理解（只读）/ Multimodal (read-only) | go/vision | | scribe | subagent | 文档与图表编写 / Documentation | go/max |

Skill → Agent 映射 / Skill-to-Agent Mapping

| Skill | Agent | Category | |-------|-------|----------| | easy | router | entry | | auto | architect | entry | | expert | executor | entry | | ba | analyst | workflow | | baseline | librarian | workflow | | bpm-workflow | analyst | workflow | | bug-fixer | debugger | workflow | | cockpit-page-builder | builder | visual-engineering | | style-optimizer | builder | visual-engineering | | git-safe | git-master | git | | git-workflow | git-master | git | | code-review | executor | quality | | security-check | executor | quality | | skill-maintainer | craftsman | meta | | skill-refresh | craftsman | meta | | skill-builder | craftsman | meta | | evo-tracker | historian | tools | | workspace-manager | executor | tools | | module-doc | scribe | tools | | model-preset | craftsman | tools |

模型预设系统 / Model Preset System

一键切换所有 12 个 Agent 的模型配置。编辑 .opencode/opespro-opencode.jsonc：

{
  // 切换为 livedata:
  "active_preset": "livedata"
  
  // 或省钱模式:
  // "active_preset": "budget"
}

| Preset | Provider | 费用 / Cost | |--------|----------|------------| | opencode-go | OpenCode Go | $10/mo | | livedata | Livedata 自定义 API | 按量 / Pay-per-use | | budget | 混合 / Mixed | 最低 / Lowest |

模型别名 / Model Aliases

go/reasoning → opencode-go/deepseek-v4-pro    ld/reasoning → livedata/deepseek-v4-pro
go/coding    → opencode-go/kimi-k2.7-code     ld/coding    → livedata/qwen3-coder-plus
go/general   → opencode-go/qwen3.7-plus       ld/general   → livedata/qwen3.7-plus
go/max       → opencode-go/qwen3.7-max        ld/max       → livedata/qwen3.7-max
go/small     → opencode-go/glm-5.2            ld/small     → livedata/glm-5.2
go/vision    → opencode-go/glm-5              ld/vision    → livedata/glm-5
go/knowledge → opencode-go/kimi-k2.5          ld/knowledge → livedata/kimi-k2.5
                                               ld/router    → livedata/glm-4.7

验证模型解析：

cd opespro-opencode && bun run scripts/verify-models.ts

开发 / Development

前置条件 / Prerequisites

• Node.js >= 18
• Bun >= 1.0

命令 / Commands

bun install          # 安装依赖 / Install deps
bun run build        # 构建 dist/ / Build
bun run typecheck    # 类型检查 / Type check
bun run test         # 运行测试 / Run tests
bun run verify       # 完整性验证 (18 项) / Integrity check

发布 / Publish

npm login
npm publish --access public

插件加载机制 / Plugin Loading Mechanism

两条加载路径 / Two Loading Paths

OpenCode 启动 / OpenCode Starts
    │
    ├─▶ 路径 1（优先）：~/.config/opencode/plugins/opespro-opencode.js
    │     ├─ 来源 / Source: postinstall.mjs 从 dist/index.js 复制
    │     ├─ 特点 / Feature: 独立运行，无需 node_modules 解析
    │     └─ 更新方式 / Update: 手动 cp 或 npm install 触发 postinstall
    │
    └─▶ 路径 2（回退）：~/.config/opencode/node_modules/opespro-opencode/dist/index.js
          ├─ 来源 / Source: npm install 安装到 node_modules
          ├─ 特点 / Feature: 通过 package.json "main" 字段解析
          └─ 更新方式 / Update: npm install [email protected]

⚠️ plugins/opespro-opencode.js 不可删除 — 它是 OpenCode 的第一优先级加载路径。删除后依赖回退路径，如果 node_modules 版本过期会导致功能缺失。

验证加载状态 / Verify Loading

# 检查 Agent 是否加载
ls ~/.config/opencode/agents/ | wc -l    # 应输出: 12

# 检查 Skill 是否安装
ls ~/.config/opencode/skills/ | grep -v myskills | wc -l  # 应输出: 20

# 检查插件文件
ls -la ~/.config/opencode/plugins/opespro-opencode.js

技术栈 / Tech Stack

| 层级 / Layer | 技术 / Technology | |-------------|-----------------| | 运行时 / Runtime | Bun + Node.js | | 类型系统 / Types | TypeScript 5.7 | | 构建 / Build | Bun build + tsc | | Schema 验证 / Schema | Zod 4.1 | | YAML 解析 / YAML | js-yaml 4.1 | | Glob 匹配 / Matching | picomatch 4.0 | | SDK | @opencode-ai/plugin ^1.1.19 |

License / 许可证

MIT