# OpesPro OpenCode — AI Agent Harness for Chinese Enterprise

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

[![npm version](https://img.shields.io/npm/v/opespro-opencode)](https://www.npmjs.com/package/opespro-opencode)
[![license](https://img.shields.io/npm/l/opespro-opencode)](LICENSE)

---

<!-- ⚡ LANGUAGE SWITCH: 中文在前 / Chinese first, English follows each section ⚡ -->

## 概述 / 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

```bash
# 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`：

```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
```

验证模型解析：

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

---

## 开发 / Development

### 前置条件 / Prerequisites

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

### 命令 / Commands

```bash
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

```bash
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 opespro-opencode@3.2.0latest
```

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

### 验证加载状态 / Verify Loading

```bash
# 检查 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