opc-architecture

OPC Architecture Understanding

OPC（Orchestrated Parallel Claude）扩展 Claude Code，而不是替代它。

核心概念

Claude Code CLI 是执行引擎。OPC 通过以下方式增加编排能力：

• Hooks：拦截 Claude Code 事件（PreToolUse、PostToolUse、SessionStart 等）
• Skills：向 Claude Code 加载提示词
• Scripts：由 hooks/skills 调用以进行协调
• Database：在多个 Claude Code 实例之间存储状态

智能体如何工作

当你生成一个智能体时：

1. 主 Claude Code 实例（你的终端）在 Task 工具上运行 hook
2. Hook 调用 subprocess.Popen(["claude", "-p", "prompt"])
3. 一个新的 Claude Code 实例作为子进程生成
4. 子进程独立运行，读写协调数据库
5. 父进程通过数据库中的 PID 跟踪子进程

$ claude ← 主 Claude Code（你的终端） ↓ Task 工具触发 hook ↓ subprocess.Popen(["claude", "-p", "..."]) ├── claude -p "research..." ← 子智能体 1 ├── claude -p "implement..." ← 子智能体 2 └── claude -p "test..." ← 子智能体 3

OPC 不是什么

• OPC 不是独立应用
• OPC 在没有 Claude Code 的情况下无法运行
• OPC 不直接拦截 Claude API 调用
• OPC 不修改 Claude Code 的内部行为

OPC 是什么

• OPC 是 Claude Code 从 .claude/hooks/ 加载的 hooks
• OPC 是 Claude Code 从 .claude/skills/ 加载的 skills
• OPC 是 hooks/skills 为协调而调用的 scripts
• OPC 是跨 Claude Code 实例保存状态的数据库后端

关键文件

.claude/ ├── hooks/ ← Claude Code 运行的 TypeScript hooks ├── skills/ ← Claude Code 加载的 SKILL.md 提示词 ├── settings.json ← Hook 注册，Claude Code 读取此文件 └── cache/ ← 状态文件、智能体输出

opc/ ├── scripts/ ← 由 hooks 调用的 Python 脚本 ├── docker-compose.yml ← PostgreSQL、Redis、PgBouncer └── init-db.sql ← 数据库 schema

协调流程

1. 用户在终端运行 claude
2. Claude Code 从 .claude/settings.json 加载 hooks
3. 用户说“生成一个研究智能体”
4. Claude 使用 Task 工具
5. PreToolUse hook 触发，检查资源
6. Hook 以子进程方式生成 claude -p "research..."
7. Hook 将 PID 存入 PostgreSQL
8. 子智能体运行，将输出写入 .claude/cache/agents/<id>/
9. 子进程完成，向 PostgreSQL 广播“done”
10. 父进程检查数据库，读取子进程的输出文件

请记住

• 每个“智能体”只是另一个 claude -p 进程
• Hooks 拦截事件，它们不创建新功能
• 所有协调都通过文件和 PostgreSQL 进行
• Claude Code 始终是执行引擎