คดีที่ 33: ผ่าพิมพ์เขียว OpenCreator — ถอดรหัสสถาปัตยกรรม AI ยุคใหม่ (12.2k Stars)

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

ทำไมโปรเจกต์ krillinai/OpenCreator ถึงได้รับความนิยมและมียอดกด Star ทะลุ 12.2k บน 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["⚙️ OpenCreator 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):

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

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

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

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

{
  "name": "opencreator-agent",
  "private": true,
  "type": "module",
  "packageManager": "[email protected]",
  "scripts": {
    "prebuild": "pnpm krillinai:build",
    "build": "pnpm -r build",
    "test": "pnpm -r test",
    "e2e": "playwright test",
    "perf:measure": "playwright test apps/web/e2e/scheduled-task-performance.spec.ts",
    "typecheck": "pnpm -r typecheck",
    "smoke:ci": "pnpm --filter @opencreator/daemon test -- test/unit/codex-smoke.test.ts",
    "perf:check": "node scripts/check-performance-baseline.mjs",
    "release:verify-scheduled-task-upgrade": "pnpm --filter @opencreator/daemon verify:schedule-upgrade",
    "daemon:dev": "pnpm --filter @opencreator/daemon dev",
    "web:dev": "pnpm --filter @opencreator/web dev",
    "harness": "pnpm --filter @opencreator/harness start",
    "desktop:dev": "pnpm --filter @opencreator/desktop dev",
    "desktop:build": "pnpm --filter @opencreator/desktop build",
    "desktop:package": "pnpm --filter @opencreator/desktop package",
    "desktop:dist": "pnpm --filter @opencreator/desktop dist",
    "desktop:release": "pnpm --filter @opencreator/desktop release",
    "desktop:test": "pnpm --filter @opencreator/desktop test",
    "templates:validate": "pnpm --filter @opencreator/daemon templates:validate",
    "templates:compile": "pnpm --filter @opencreator/daemon templates:compile",
    "templates:ci": "pnpm templates:validate && pnpm templates:compile",
    "templates:preview-videos": "node scripts/optimize-creator-preview-videos.mjs",
    "krillinai:build": "node scripts/build-krillinai.mjs",
    "krillinai:package": "node scripts/package-krillinai-release.mjs",
    "krillinai:test": "node scripts/build-krillinai.mjs --test-only"
  },
  "devDependencies": {
    "@playwright/test": "^1.61.1",
    "@types/node": "^22.10.7",
    "tsx": "^4.19.2",
    "typescript": "^5.7.3",
    "vitest": "^3.2.7"
  },
  "pnpm": {
    "overrides": {
      "fast-uri@>=3.0.0 <3.1.6": "3.1.6",
      "ip-address@<=10.3.0": "10.7.0",
      "undici@>=7.0.0 <7.29.0": "7.29.0",
      "find-my-way@<=9.6.0": "9.7.0",
      "postcss@<=8.5.17": "8.5.18",
      "brace-expansion@<1.1.18": "1.1.18",
      "brace-expansion@>=2.0.0 <2.1.4": "2.1.4",
      "brace-expansion@>=4.0.0 <5.0.9": "5.0.9",
      "browserslist@<=4.28.6": "4.28.7",
      "@xmldom/xmldom@>=0.7.0 <0.8.15": "0.8.15",
      "js-yaml@>=4.0.0 <4.3.2": "4.3.2",
      "nanoid@>=3.0.0 <3.3.18": "3.3.18",
      "tar@>=7.0.0 <=7.5.20": "7.5.21",
      "ws@>=8.0.0 <8.21.0": "8.21.0"
    }
  }
}

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

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

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

# OpenCreator 项目级 Agent 规则

## 执行效率与最小充分验证铁律

### 总原则

- 铁律：验证范围必须与改动风险和实际影响范围匹配。不得把小型、局部、低风险修改默认升级为全量测试、完整构建、服务重启、端到端测试或桌面打包。
- 铁律：先完成最小范围的代码定位和修改，再执行能够证明本次改动正确的最小验证集。只有验证结果表明存在更大影响时，才允许逐级扩大范围。
- 铁律：不得因为仓库存在无关的历史失败、脏工作区或其他模块问题而主动扩大当前任务；与本次改动无关的问题只需记录，不得顺手排查或修复。
- 用户明确要求完整测试、构建、打包、发布或跨平台一致性验证时，按用户要求执行，不受下述默认分级限制。

### 风险分级

- P0 低风险修改：文案、样式微调、默认值、局部展示条件、测试断言等不改变 Runtime/API/持久化协议的改动。
  - 默认只执行相关文件检查、最接近的定向测试；TypeScript 代码按需执行对应包的 `typecheck`。
  - 默认不执行全量测试、生产构建、端到端测试、Desktop 打包或服务重启。
- P1 中风险修改：共享状态、业务逻辑、持久化行为、跨组件交互、Runtime 请求参数或公共组件改动。
  - 执行受影响模块的定向测试和对应包的 `typecheck`。
  - 仅在涉及编译边界、懒加载、资源产物或构建配置时执行生产构建。
  - 仅在真实交互无法由定向测试充分覆盖时增加浏览器验证。
- P2 高风险修改：Daemon/Runtime、协议、数据库迁移、进程管理、服务配置、构建打包、发布链路或明确的 Web/Desktop 一致性改动。
  - 执行相关集成测试、构建、服务重启和健康检查。
  - 只有任务涉及 Desktop 或交付包时才执行 Desktop 构建、打包及一致性门禁。

### 服务操作

- 前端源码在正在运行的 Vite 开发服务下能够热更新时，不得仅为使页面生效而重启 Web 服务。
- 只有服务端代码、启动配置、环境变量、进程依赖发生变化，热更新失败，服务未启动，或用户明确要求时，才停止或重启对应服务。
- 重启前先确认目标端口和进程命令；重启后只验证对应服务和直接依赖的健康状态，避免无关服务操作。

### 验证升级条件

- 定向测试失败且失败与本次改动相关。
- 改动触及共享公共层，无法通过局部测试覆盖主要调用方。
- 类型检查或构建结果暴露跨模块影响。
- 用户要求更高等级验证，或任务目标本身是发布、打包、全流程验收、跨平台一致性。

### 交付说明

- 完成时只报告实际执行的验证，不得用未执行的全量验证暗示项目整体无回归。
- 若最小验证集已覆盖本次改动，应及时交付，不得为了形式上的“更完整”继续运行低收益验证。

## `opencreator-bug-fix` 使用铁律

- 铁律：普通开发、代码修复、体验优化和用户直接提出的需求，不得默认启用或附加 `opencreator-bug-fix` 流程。
- 只有用户明确要求读取、处理或回写 OpenCreator 飞书 Bug 文档时，才允许使用 `opencreator-bug-fix`。
- 未得到上述明确要求时，禁止因为任务看起来像 Bug 而读取飞书文档、执行文档闭环或按该流程自动创建 Git commit；应直接按当前需求完成代码修改与必要验证。

## Creator 模板协作面板架构铁律

- 铁律：视频翻译、封面生成、图像生成、视频生成及后续所有 Creator 模板必须共用唯一的 `CreatorCollaborationPanel`；禁止为单个模板复制或新建一套完整的 Agent Panel。
- 通用 Panel 统一负责 Agent 消息、Activity 时间线、Stage 状态卡、真实进度、审批、Composer、权限以及任务终止和继续。模板 Workspace 不得自行维护第二套消息、审批、SSE 或 Stage 展示逻辑。
- 模板差异只能通过 `CreatorPanelAdapter`、配置、回调或局部 slot 表达。Adapter 只负责 Stage/Phase/字段文案、Activity 语义化、进度标准化、Composer 默认提示和模板上下文摘要，不得复制通用交互框架。
- Workspace 只向通用 Panel 提供当前步骤、业务上下文、问题状态和快捷操作。真正只属于某个模板的能力可以使用局部 slot，但不得借此复制完整 Panel。
- 通用 Panel 禁止读取 `krillinEventPayload` 或其他执行器私有字段。Runtime 对外进度统一为 `phase`、`percent`、`message`、`completed`、`failed`、`total`；旧字段兼容只能存在于对应 Adapter 或 Runtime normalizer。
- 纯界面状态不得写入用户可见的创作动态，包括步骤索引、最远步骤、工作区页签、结果页签和草稿版本等 UI-only 字段。Activity 必须先语义化、过滤并合并连续同类更新。
- 未知模板必须使用 fallback adapter，显示稳定的通用文案，不得直接暴露内部 Stage ID、执行器名称或原始事件字段。
- 新增 Creator 模板时必须同时增加 Adapter 测试、Activity 过滤与去重测试、Stage 状态测试和真实进度测试；禁止以创建独立 Panel 作为交付方式。

## Web / Desktop 一致性铁律门禁

### 核心定义

- 铁律：OpenCreator 以 `apps/web` 作为唯一的前端实现和主要开发环境，Desktop 必须直接使用同一套 Web 前端构建产物，不得维护第二套页面、组件、样式或通用交互逻辑。
- 铁律：在相同业务数据、相同用户偏好和相同前端内容区尺寸下，Web 与 Desktop 的通用界面、文案、布局、状态、交互结果和 Runtime 请求必须一致。
- “一致”指通用产品能力一致，不要求浏览器模拟操作系统窗口、系统目录选择器、菜单栏、托盘和原生通知等系统能力。
- 不能因为 Web 和 Desktop 共用 React 代码就默认二者已经一致；一致性必须通过自动化测试和实际打包 App 验证。

### 通用能力铁律

- 默认项目、项目创建、项目选择、项目配置、会话、任务、计划、权限、模型、附件、文件编辑和其他业务能力必须由 Web 与 Desktop 共用的 Daemon/API/Service 实现。
- 通用业务不得分别为 Browser Bridge 和 Desktop Bridge 实现两套逻辑。
- 首次启动无项目时，Web 与 Desktop 必须得到相同的默认项目和可直接输入的会话状态，不得一端自动创建项目、另一端要求用户手动创建。
- 创建空白项目必须走统一的 Runtime 项目接口；Desktop Bridge 不得单独承担通用项目创建逻辑。
- Desktop Bridge 只负责必须依赖操作系统或 Electron 的能力，例如选择现有目录、解析文件夹拖放路径、窗口生命周期、菜单栏、托盘和原生通知。

### 平台能力铁律

- 禁止在共享 UI 中使用 `hostBridge.kind` 随意分叉通用业务、页面结构或样式。
- 平台差异必须通过明确的 capability 或可选回调表达，例如 `canSelectDirectory`、`canControlWindow`。

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

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

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

Enterprise Security & Architecture Consulting (รับงานที่ปรึกษาองค์กร)
- องค์กรขนาดใหญ่ต้องการนำ AI Agent มาใช้ แต่ติดปัญหา Data Leak และการควบคุม Tool Calling
- นำสถาปัตยกรรม FastMCP / Sandboxed Context ไปติดตั้งแบบ On-premise ค่าบริการเริ่มต้น 150,000 - 300,000 บาท/โปรเจกต์
Specialized AI Automation Micro-SaaS (สร้างบริการเฉพาะทาง)
- พัฒนาบริการ Agent สำหรับตรวจสอบช่องโหว่เว็บ (Bug Bounty as a Service) หรือเครื่องมือคุม Context สำหรับทีม Dev
- ตั้งราคาแบบ Subscription รายเดือน ($29 - $99/เดือน/ผู้ใช้)
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 แชร์บน X LinkedIn

💬

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

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