📅
🕵️‍♂️ อ่าน ~3 นาที

คดีที่ 34: ผ่าพิมพ์เขียว oh-my-openagent — ถอดรหัสสถาปัตยกรรม AI ยุคใหม่ (69.3k Stars)

🕵️‍♂️ ปมคดีและที่มา: ทำไมวงการถึงต้องจับตามอง?

ทำไมโปรเจกต์ code-yeongyu/oh-my-openagent ถึงได้รับความนิยมและมียอดกด Star ทะลุ 69.3k บน GitHub?

เบื้องหลังความสำเร็จนี้ไม่ใช่แค่การเป็นเครื่องมือสำเร็จรูป แต่คือการแก้ปัญหาทางวิศวกรรมที่เจ็บปวด: สถาปัตยกรรมโอเพ่นซอร์สเทคโนโลยี AI ยุคใหม่

📊 ตารางเปรียบเทียบเชิงลึก: วิธีดั้งเดิม vs สถาปัตยกรรมสมัยใหม่

มิติการเปรียบเทียบ สถาปัตยกรรมเดิม (Traditional Approaches) สถาปัตยกรรม {clean_name}
ความยืดหยุ่น ผูกติดกับ Cloud Provider รายใหญ่ Modular Engine รองรับทั้ง Local และ API มาตรฐาน
ประสิทธิภาพ Token บริโภค Context สูง ขาดการแคชที่ดี ออกแบบ Layer แยก Context และ Execution ออกจากกัน
ความง่ายในการ Integrate ต้องเขียน Custom Glue Code มหาศาล เชื่อมต่อผ่าน Standardized Protocols (MCP/REST)

🔍 แกะรอยสถาปัตยกรรมระบบ (Deep Architecture Breakdown)

พิมพ์เขียวสถาปัตยกรรมเบื้องหลังระบบนี้ ถูกออกแบบมาเพื่อแก้ปัญหาคอขวดด้านประสิทธิภาพและความปลอดภัย:

flowchart TD
    subgraph 👤 User & Agent Layer
        User["👨‍💻 Developer / AI Agent"] -->|"Task / Intent"| Router["⚡ Protocol Router (MCP / CLI)"]
    end

    subgraph 🧠 Core Intelligence Engine
        Router --> Engine["⚙️ oh-my-openagent Engine"]
        Engine --> Decision["🎯 Intelligent Decision Core"]
        Engine --> Memory["💾 Persistent Session & Cache"]
    end

    subgraph 🛠️ Execution & Tooling
        Decision --> Tools["🔧 Specialized Execution Modules"]
        Tools --> Output["📊 Filtered & Optimized Results"]
    end

    Output -->|"Clean Context"| User

3 เสาหลักของการออกแบบระบบ (System Design Pillars):

  1. Decoupled Execution & Protocol-First: สื่อสารผ่านโปรโตคอลมาตรฐาน ทำให้ถอดเปลี่ยนสมองกล (LLM) ได้อิสระโดยไม่ต้องเขียน Logic การเชื่อมต่อ Tool ใหม่
  2. Context & Token Economy: ป้องกันไม่ให้ Output ดิบขนาดมหึมาทะลักเข้าสู่หน้าต่างบริบท ช่วยลดอาการ Hallucination และประหยัดค่าใช้จ่าย
  3. Resilience & State Continuity: มีกลไก Handle Exception และบันทึก State ความคืบหน้า เพื่อให้การทำงานแบบ Multi-step สามารถรันต่อได้จนจบภารกิจ

💻 ผ่ารหัสลับของจริง (Source Code Autopsy)

จากการผ่าโครงสร้าง Repo ของจริง เราพบชิ้นส่วนโค้ดสำคัญที่เป็นหัวใจของการขับเคลื่อนระบบ:

📄 ผ่าไฟล์จริง: package.json

{
  "name": "oh-my-opencode",
  "version": "4.17.1",
  "description": "The Best AI Agent Harness - Batteries-Included OpenCode Plugin with Multi-Model Orchestration, Parallel Background Agents, and Crafted LSP/AST Tools",
  "main": "./dist/index.js",
  "types": "dist/index.d.ts",
  "type": "module",
  "workspaces": [
    "packages/rules-engine",
    "packages/delegate-core",
    "packages/git-bash-mcp",
    "packages/mcp-stdio-core",
    "packages/mcp-client-core",
    "packages/lsp-core",
    "packages/utils",
    "packages/model-core",
    "packages/omo-config-core",
    "packages/prompts-core",
    "packages/comment-checker-core",
    "packages/hashline-core",
    "packages/tmux-core",
    "packages/team-core",
    "packages/openclaw-core",
    "packages/boulder-state",
    "packages/telemetry-core",
    "packages/claude-code-compat-core",
    "packages/skills-loader-core",
    "packages/agents-md-core",
    "packages/shared-skills",
    "packages/omo-codex",
    "packages/omo-senpi",
    "packages/senpi-task",
    "packages/pi-goal",
    "packages/pi-webfetch",
    "packages/omo-opencode"
  ],
  "bin": {
    "oh-my-opencode": "bin/oh-my-opencode.js",
    "oh-my-openagent": "bin/oh-my-opencode.js",
    "omo": "bin/oh-my-opencode.js",
    "lazycodex": "bin/oh-my-opencode.js",
    "lazycodex-ai": "bin/oh-my-opencode.js"
  },
  "files": [
    "THIRD-PARTY-NOTICES.md",
    "dist",
    "bin",
    "postinstall.mjs",
    "script/qa/strip-ansi.mjs",
    "script/qa/web-terminal-redaction.d.mts",
    "script/qa/web-terminal-redaction.mjs",
    "script/qa/web-terminal-visual-qa.mjs",
    "script/qa/xterm-live-terminal.mjs",
    "docs/reference/github-attachment-upload.md",
    "docs/reference/web-terminal-visual-qa.md",
    ".opencode/command",
    ".opencode/skills",
    ".agents/command",
    ".agents/skills",
    "packages/lsp-tools-mcp/package.json",
    "packages/lsp-core/package.json",
    "packages/lsp-core/src",
    "packages/lsp-tools-mcp/dist",
    "packages/lsp-daemon/package.json",
    "packages/lsp-daemon/dist",
    "packages/git-bash-mcp/package.json",
    "packages/git-bash-mcp/dist",
    "packages/shared-skills/package.json",
    "packages/shared-skills/index.mjs",
    "packages/shared-skills/skills",
    "packages/omo-codex/THIRD-PARTY-NOTICES.md",
    "packages/omo-codex/marketplace.json",
    "packages/omo-codex/lazycodex-repository",
    "packages/omo-codex/plugin",
    "packages/omo-codex/plugin/components/bootstrap/dist/cli.js",
    "packages/omo-codex/plugin/components/bootstrap/scripts/bootstrap.ps1",
    "packages/omo-codex/plugin/components/bootstrap/scripts/node-dispatch.ps1",
    "packages/omo-codex/plugin/components/codegraph/dist/cli.js",
    "packages/omo-codex/plugin/components/codegraph/dist/serve.js",
    "packages/omo-codex/plugin/components/comment-checker/dist/cli.js",

การทำงานทางวิศวกรรม:

  • โค้ดส่วนนี้ทำหน้าที่เป็นแกนกลางในการควบคุม Flow ของข้อมูล
  • แยกหน้าที่การทำงานชัดเจน (Separation of Concerns) ทำให้สเกลเครื่องมือใหม่ๆ เข้าสู่ระบบได้ทันทีโดยไม่ต้องแก้ Core Engine

📄 ผ่าไฟล์จริง: CLAUDE.md

AGENTS.md

การทำงานทางวิศวกรรม:

  • โค้ดส่วนนี้ทำหน้าที่เป็นแกนกลางในการควบคุม Flow ของข้อมูล
  • แยกหน้าที่การทำงานชัดเจน (Separation of Concerns) ทำให้สเกลเครื่องมือใหม่ๆ เข้าสู่ระบบได้ทันทีโดยไม่ต้องแก้ Core Engine

📄 ผ่าไฟล์จริง: AGENTS.md

# oh-my-opencode — OpenCode Plugin

> **HOLD THE FUCK UP. THIS ENTIRE GODDAMN CODEBASE IS BEING RIPPED APART AND REBUILT RIGHT NOW. A MASSIVE MULTI-HARNESS AGENT OS REFACTOR IS IN PROGRESS — WE ARE RESTRUCTURING EVERYTHING TO SUPPORT MULTIPLE AGENT HARNESSES (OPENCODE, CODEX, PI, AND OTHERS). DO NOT TRUST THE STRUCTURE BELOW AS STABLE. READ THE [ROADMAP](./ROADMAP.md) BEFORE YOU TOUCH ANYTHING OR SO HELP ME GOD.**

**Generated:** 2026-07-03 | **Commit:** 25bb0d5ac | **Branch:** dev | **Release:** v4.15.1

## STOP. QA IS MANDATORY. NON-NEGOTIABLE. EVERY SINGLE TIME YOU TOUCH AN OPENCODE- OR CODEX-CONNECTED COMPONENT.

> **IF YOUR CHANGE TOUCHES ANYTHING WIRED INTO OPENCODE OR INTO THE CODEX LIGHT EDITION, YOU MUST QA IT. ALWAYS. EVERY SINGLE TIME. NO EXCEPTIONS. THERE IS NO "TOO SMALL TO SKIP". THERE IS NO "IT OBVIOUSLY WORKS".**

**"It typechecks" is NOT QA. "`bun test` is green" is NOT QA.** YOU MUST DRIVE THE REAL HARNESS, and then **YOU MUST WRITE THE EVIDENCE TO DISK.** If there is no evidence file, **the QA DID NOT HAPPEN**, and **YOU ARE NOT ALLOWED TO COMMIT OR PUSH.**

This is repeated on purpose, because it is the single most ignored rule in this repo. **CHANGE A HOOK, A TOOL, AN AGENT, A FEATURE, A CONFIG SCHEMA, AN MCP, A CLI COMMAND, AN INSTALLER, A PROMPT, OR ANYTHING ELSE THAT REACHES OPENCODE OR CODEX, THEN: RUN QA, THEN RECORD EVIDENCE.** Always. Every time. No exceptions.

### OPENCODE side (`packages/omo-opencode/`): ALWAYS run the `opencode-qa` skill

1. **ALWAYS RUN THE `opencode-qa` SKILL** (`.agents/skills/opencode-qa/`) to map the EXPECTED IMPACT and the FULL CHANGE SCOPE of your edit BEFORE and AFTER. Pick the right case: CLI (`opencode run --format json`), server + SSE hook proof, TUI smoke, or DB inspection.
2. **ISOLATE EVERYTHING.** Any QA that SPAWNS opencode MUST run in an isolated XDG sandbox (`XDG_DATA_HOME` / `XDG_CONFIG_HOME` / `XDG_STATE_HOME` / `XDG_CACHE_HOME` pointed at temp dirs). The bundled scripts already do this. **NEVER pollute the real `~/.local/share/opencode/opencode.db`.** PROVE isolation by comparing `SELECT count(*) FROM session` before and after.
3. **USE tmux** for the TUI smoke (`scripts/tui-smoke.sh`) and for any interactive driving. tmux is for SMOKE (did it boot, render, accept a key); assert REAL behavior via `opencode run --format json` or the server API + SSE.
4. **PROVE THE HOOK FIRED.** If you changed a lifecycle hook, prove the matching event hit the wire (`scripts/sse-hook-probe.sh --event <name>`). Seeing the event proves the hook would fire.

### CODEX side (`packages/omo-codex/`): ALWAYS run the `codex-qa` skill

1. **ALWAYS RUN THE `codex-qa` SKILL** (`.agents/skills/codex-qa/`) to map the EXPECTED IMPACT and the FULL CHANGE SCOPE of your edit BEFORE and AFTER. It exercises ONLY our plugin in strict isolation — an isolated `CODEX_HOME` + a LOCAL mock model (no real API call) — so the real `~/.codex` is NEVER read or written. NEVER QA against your real `~/.codex`; NEVER the published package.
2. **PROVE THE HOOK FIRED, FIRST-PARTY.** The skill drives the real `codex app-server` and asserts `hook/started` / `hook/completed` notifications for our components (`scripts/app-server-drive.sh --plugin`). Deterministic per-component checks: `scripts/hook-unit-probe.sh`. Installer + `config.toml` landing: `scripts/install-verify.sh`. tmux TUI smoke: `scripts/tui-smoke.sh`. Each script ships a `--self-test`.
3. **RUN THE CODEX GATE:** `bun run test:codex` (installer + config migration + plugin component suite). This is the hermetic UNIT gate; it does NOT prove a live session — the `codex-qa` skill does.
4. **CONFIRM THE REAL `~/.codex/config.toml` WAS NOT TOUCHED** — every `codex-qa` script asserts this automatically (shasum before/after).

### EVIDENCE: record it under `.omo/evidence/` or it DID NOT HAPPEN

**WRITE EVERY QA ARTIFACT TO `.omo/evidence/<YYYYMMDD>-<short-slug>/`** (the existing evidence dir; one subfolder per change, keep it ORGANIZED). For EVERY change you MUST record reviewer-readable plain files:
- **WHAT WAS TESTED:** the command or manual action, the surface driven, and the behavior it was meant to prove.
- **WHAT WAS OBSERVED:** the before/after or new behavior, isolation proof such as unchanged session counts, and the artifact path for the exact captured output.
- **WHY IT IS ENOUGH:** how the evidence covers the intended behavior and remaining regression risk.
- **WHAT WAS OMITTED:** redact or summarize raw secret-bearing logs, env dumps, tokens, auth headers, and private credentials instead of copying them.

**NO EVIDENCE FILE == NO QA == NO COMMIT == NO PUSH.** ALWAYS. EVERY TIME. NO EXCEPTIONS.

## DEFAULT WORKFLOW — how to take on any task

Unless the user EXPLICITLY says otherwise, or the task is an urgent must-fix-now hotfix, deliver every change through the **`work-with-pr`** skill: it works in an isolated git worktree, implements with evidence-bound manual QA, opens a reviewer-readable English PR (what changed, why, observed behavior, QA/evidence, residual risk), runs the verification loop, and merges. Do NOT hand-commit normal work straight to `dev`.

- **QA is the evidence gate, scoped to what you touched.** A change under `packages/omo-opencode/` MUST run the **`opencode-qa`** skill; a change under `packages/omo-codex/` (lazycodex) MUST run the **`codex-qa`** skill (see the QA section above for each). Run the matching skill, and treat its captured output (written under `.omo/evidence/`) as the QA evidence `work-with-pr` requires. A change touching both runs both.
- **Conflicts → `smart-rebase`.** If the worktree branch conflicts with its base, resolve it with the **`smart-rebase`** skill, then re-run the scoped QA. Never hand-resolve by force-pushing shared history.
- **Merge → merge commit, ALWAYS.** Land the PR with a merge commit per **PR MERGE POLICY** below. NEVER squash-merge or rebase-merge, even if a generic workflow, skill, or GitHub default suggests it.

## OVERVIEW

OpenCode plugin (npm: `oh-my-opencode`, dual-published as `oh-my-openagent` during the rename transition) extending OpenCode with 11 agents, 54-62 lifecycle hooks (base / +monitor / +team-mode) across 61 dirs, 12-35 registry tools (gated by config flags including team-mode; +6 `lsp_*` tools served via the built-in lsp MCP), 3-tier MCP system (built-in + .mcp.json + skill-embedded), Hashline LINE#ID edit tool, IntentGate keyword detector, Team Mode (parallel multi-agent coordination, OFF by default), Boulder feature (boulder-state work tracking + cli/boulder subcommand), configurable agent ordering, and Claude Code compatibility.

**The package layering refactor moved the entire plugin out of root `src/` into [`packages/omo-opencode/src/`](packages/omo-opencode/src/AGENTS.md)** (a 100% git rename — there is NO root `src/` anymore). That adapter tree is now the OpenCode-facing shim over 18 Core packages + 3 MCP packages + the Codex adapter. Build entry: `packages/omo-opencode/src/index.ts`, a thin wrapper that delegates to `packages/omo-opencode/src/testing/create-plugin-module.ts` `createPluginModule()` → staged plugin init (see INITIALIZATION FLOW). Ships in two editions of one product: **Ultimate** (omo for OpenCode, this plugin = `packages/omo-opencode/`) and **Light** (omo for Codex CLI = [`packages/omo-codex/`](packages/omo-codex/AGENTS.md), distributed as the `lazycodex` alias; see CODEX LIGHT EDITION below).

## STRUCTURE

oh-my-opencode/ # workspace root (no root src/ — it moved into packages/omo-opencode) ├── packages/ # 39 sibling pkgs, layered: Core → MCP → Skills → Adapters → Platform/Web. See packages/AGENTS.md │ ├── omo-opencode/ # ★ THE OpenCode plugin adapter (formerly root src/). Build entry: src/index.ts │ │ └── src/ # plugin source and OpenCode-facing adapter shims. Full breakdown → packages/omo-opencode/src/AGENTS.md │ │ ├── index.ts # Plugin entry; thin wrapper re-exporting createPluginModule() from src/testing/ │ │ ├── plugin-interface.ts # 12 OpenCode hook handlers (+2 wired in testing/create-plugin-module.ts) │ │ ├── create-{managers,tools,hooks}.ts # 4 managers / ToolRegistry / 5-tier hook composition │ │ ├── agents/ # 11 agents, 10 createXXXAgent factories (Prometheus special-cased via plugin-handlers/prometheus-agent-config-builder.ts) │ │ ├── hooks/ # 54-62 lifecycle hooks across 61 dirs (incl. 5 zauc-* mock dirs + shared/ + team-session-events/) │ │ ├── tools/ # 14 native tool dirs; LSP served via a built-in MCP, ast-grep via the bundled skill │ │ ├── features/ # 23 feature modules (team-mode, background-agent, skill-mcp-manager, opencode-skill-loader, mcp-oauth, claude-code-plugin-loader, boulder-state, …) │ │ ├── shared/ # cross-cutting utilities; logger → oh-my-opencode.log in os.tmpdir() (50 MB cap, .1/.2 backups) │ │ ├── config/ # Zod v4 schema system (36 schema files) │ │ ├── cli/ # Commander.js CLI, 10 commands: install(setup), run, doctor, cleanup(uninstall), version, get-local-version, refresh-model-capabilities, boulder, ulw-loop, mcp (oauth login/logout/status) │ │ ├── mcp/ # 5 built-in MCPs (3 remote + local stdio lsp + codegraph) │ │ ├── plugin/ plugin-handlers/ # OpenCode hook handlers + 6-phase config loading pipeline │ │ ├── openclaw/ # Bidirectional Discord/Telegram/HTTP/shell integration + reply listener daemon │ │ └── generated/ help/ locales/ testing/ tests/ # model-capabilities, CLI help schemas, i18n, test factory, perf benchmarks │ ├── omo-codex/ # Codex CLI Light edition (lazycodex); vendored Codex plugin omo + TS installer + telemetry │ ├── omo-senpi/ # Senpi native TS extension adapter (local-path Pi package); 6 components incl. task (drives senpi-task + omo-config-core) │ ├── senpi-task/ # Senpi-coupled task engine: state machine, store, in-process/RPC runners, lifecycle, completion, teams, 7 task + 12 team tools │ ├── utils/ model-core/ prompts-core/ rules-engine/ agents-md-core/ comment-checker-core/ hashline-core/ boulder-state/ telemetry-core/ lsp-core/ mcp-stdio-core/ tmux-core/ claude-code-compat-core/ skills-loader-core/ mcp-client-core/ openclaw-core/ team-core/ delegate-core/ omo-config-core/ # 19 Core (pure-TS) pkgs │ ├── lsp-tools-mcp/ git-bash-mcp/ lsp-daemon/ # 3 MCP-layer pkgs (stdio); LSP packages consume lsp-core + mcp-stdio-core │ ├── shared-skills/ # Cross-harness SKILL.md bundle shared by OpenCode + Codex │ ├── web/ # Marketing site (Next.js 15 + Cloudflare Workers); own bun.lock; only @/* alias zone in the repo

**การทำงานทางวิศวกรรม:**
- โค้ดส่วนนี้ทำหน้าที่เป็นแกนกลางในการควบคุม Flow ของข้อมูล
- แยกหน้าที่การทำงานชัดเจน (Separation of Concerns) ทำให้สเกลเครื่องมือใหม่ๆ เข้าสู่ระบบได้ทันทีโดยไม่ต้องแก้ Core Engine



---

## 💰 3 พิมพ์เขียวสร้างรายได้จริงจากสถาปัตยกรรมนี้

1. **Enterprise Security & Architecture Consulting (รับงานที่ปรึกษาองค์กร)**
   - องค์กรขนาดใหญ่ต้องการนำ AI Agent มาใช้ แต่ติดปัญหา Data Leak และการควบคุม Tool Calling
   - นำสถาปัตยกรรม FastMCP / Sandboxed Context ไปติดตั้งแบบ On-premise ค่าบริการเริ่มต้น 150,000 - 300,000 บาท/โปรเจกต์

2. **Specialized AI Automation Micro-SaaS (สร้างบริการเฉพาะทาง)**
   - พัฒนาบริการ Agent สำหรับตรวจสอบช่องโหว่เว็บ (Bug Bounty as a Service) หรือเครื่องมือคุม Context สำหรับทีม Dev
   - ตั้งราคาแบบ Subscription รายเดือน ($29 - $99/เดือน/ผู้ใช้)

3. **Developer Tools & Workflow Optimization Retainer**
   - ให้บริการตรวจสอบและ Optimize สถาปัตยกรรม Token Consumption ให้แก่บริษัท Startup หรือ Tech Agency
   - ช่วยลดค่า API OpenAI / Anthropic จากหลักแสนเหลือหลักหมื่นบาทต่อเดือน โดยคิดส่วนแบ่งจากยอดเงินที่ช่วยประหยัดได้ (Cost-Saving Share 20-30%)


---

> 💬 ร่วมสืบคดีและแลกเปลี่ยนความรู้ด้าน AI Engineering กับเราได้ที่เพจ **Facebook: นักสืบอัลกอริทึม**
🕵️‍♂️

ชอบคดีนี้ไหม? ส่งต่อให้เพื่อนในวงการ Dev!

แชร์บทความวิเคราะห์สถาปัตยกรรม AI & โค้ดจริงที่นำไปใช้สร้างเงินได้ทันที

แชร์บน Facebookแชร์บน XLinkedIn
💬

ร่วมอภิปรายคดีลับ (Case Discussion)

มีข้อสงสัย บัค หรือไอเดียต่อยอดสถาปัตยกรรมนี้? แลกเปลี่ยนกับเพื่อนสาย Dev ได้ด้านล่าง: