jd-opensource · yuzzjj · Apr 24, 2026 · Apr 24, 2026 · Apr 24, 2026 · Apr 24, 2026
diff --git a/.gitignore b/.gitignore
@@ -34,8 +34,6 @@ share/python-wheels/
 MANIFEST
 
 # PyInstaller
-#  Usually these files are written by a python script from a template
-#  before PyInstaller builds the exe, so as to inject date/other infos into it.
 *.manifest
 *.spec
 
@@ -62,23 +60,10 @@ cover/
 *.mo
 *.pot
 
-# Crew stuff:
-demo_stands/
-
-# Django stuff:
+# Logs
 *.log
-local_settings.py
-db.sqlite3
-db.sqlite3-journal
-db/*sqlite3
-*_stand/
 backend/logs/*
-# Flask stuff:
-instance/
-.webassets-cache
-
-# Scrapy stuff:
-.scrapy
+backend/app/logs
 
 # Sphinx documentation
 docs/_build/
@@ -95,60 +80,28 @@ profile_default/
 ipython_config.py
 
 # pyenv
-#   For a library or package, you might want to ignore these files since the code is
-#   intended to run in multiple environments; otherwise, check them in:
 # .python-version
 
-# pipenv
-#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
-#   However, in case of collaboration, if having platform-specific dependencies or dependencies
-#   having no cross-platform support, pipenv may install dependencies that don't work, or not
-#   install all needed dependencies.
-#Pipfile.lock
-
-# poetry
-#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
-#   This is especially recommended for binary packages to ensure reproducibility, and is more
-#   commonly ignored for libraries.
-#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
-#poetry.lock
-
 # pdm
-#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
-#pdm.lock
-#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
-#   in version control.
-#   https://pdm.fming.dev/#use-with-ide
 .pdm.toml
 
-# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+# PEP 582
 __pypackages__/
 
-# Celery stuff
-celerybeat-schedule
-celerybeat.pid
-
-# SageMath parsed files
-*.sage.py
-
 # Environments
 *.env
 .env
 .venv
 # env.* 会误伤 backend/alembic/env.py，故只忽略根目录下的 env.*
 /env.*
 !frontend/lib/core/config/env.ts    # 允许前端配置文件
-src/ENV/
 venv/
 ENV/
 env/
 env.bak/
 venv.bak/
-.django_venv
-.crew_venv
 *venv
 venvs/
-run_program/manager.env
 !src/.env
 !src/debug.env
 
@@ -183,10 +136,6 @@ dmypy.json
 cython_debug/
 
 # PyCharm
-#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
-#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
-#  and can be added to the global gitignore or merged into this file.  For a more nuclear
-#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 .idea/
 
 # VSCode
@@ -195,8 +144,6 @@ cython_debug/
 # Logging files
 log.txt
 .telemetry_log/
-
-backend/langgraph_app.*
 backend/app/logs
 *.jsonl
 
@@ -221,17 +168,11 @@ api_keys.json
 .secrets.baseline.scan.json
 .secrets.baseline.tmp
 
-# Additional tool
-additional_tools/
-make_scripts/backups
-
 # Savefiles
 **/savefiles
 
 # FRONTEND GIT ignore
 
-
-
 # Compiled output
 frontend/dist
 frontend/tmp
@@ -281,13 +222,7 @@ frontend/typings
 frontend/.DS_Store
 Thumbs.db
 
-executions
-openai-realtime-console
-src/django_app/staticfiles/*
-
-
-#knowledge data
-knowledge/graph_data/
+/executions
 
 # IDE/Editor folders
 .claude/

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -29,8 +29,7 @@ repos:
       - id: ruff-format
         files: ^backend/
 
-  # Backend - Ruff check (强制检查，不允许错误)
-  # 注意：此 hook 会检查整个 backend 目录，确保没有 lint 错误
+  # Backend - Ruff strict check
   - repo: local
     hooks:
       - id: backend-ruff-check
@@ -39,22 +38,10 @@ repos:
         language: system
         files: ^backend/.*\.py$
         pass_filenames: false
-        always_run: false  # 只在有 Python 文件更改时运行
-        stages: [commit]
+        always_run: false
+        stages: [pre-commit]
 
-  # Python - Type checking (mypy runs in Backend CI job only; skipped in pre-commit)
-  # - repo: https://github.com/pre-commit/mirrors-mypy
-  #   rev: v1.13.0
-  #   hooks:
-  #     - id: mypy
-  #       files: ^backend/app/
-  #       args: [--ignore-missing-imports]
-  #       additional_dependencies:
-  #         - types-requests
-  #         - types-PyYAML
-
-  # Frontend - ESLint (强制检查，不允许错误)
-  # 注意：此 hook 会检查整个 frontend 目录，确保没有 lint 错误
+  # Frontend - ESLint + TypeScript type-check + Prettier format check
   - repo: local
     hooks:
       - id: frontend-lint
@@ -63,8 +50,26 @@ repos:
         language: system
         files: ^frontend/.*\.(ts|tsx|js|jsx)$
         pass_filenames: false
-        always_run: false  # 只在有前端文件更改时运行
-        stages: [commit]
+        always_run: false
+        stages: [pre-commit]
+
+      - id: frontend-type-check
+        name: Frontend TypeScript Check
+        entry: bash -c 'cd frontend && bun run type-check || exit 1'
+        language: system
+        files: ^frontend/.*\.(ts|tsx)$
+        pass_filenames: false
+        always_run: false
+        stages: [pre-commit]
+
+      - id: frontend-format-check
+        name: Frontend Prettier Check
+        entry: bash -c 'cd frontend && bun run format:check || exit 1'
+        language: system
+        files: ^frontend/.*\.(ts|tsx|js|jsx|json|css|md)$
+        pass_filenames: false
+        always_run: false
+        stages: [pre-commit]
 
 # CI configuration
 ci:

diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
@@ -28,8 +28,8 @@ This document provides detailed instructions for setting up and running the JoyS
 Using Docker (recommended):
 
 ```bash
-cd backend/docker
-./start.sh
+cd deploy
+docker compose -f docker-compose-middleware.yml up -d
 ```
 
 Or manually start PostgreSQL and Redis on your system.

diff --git a/README.md b/README.md
@@ -220,11 +220,15 @@ All modes support remote deployment scenarios:
 
 **Key design principles:**
 
+- **Single source of truth for value domains** — `core/contracts/` defines every canonical value (status, error code, trigger source) as Literal types + set constants; no magic strings
+- **Engine protocol + registry** — all execution engines implement `ExecutionEngine` Protocol; `EngineRegistry` maps `runtime_kind` to engine instances; adding a new engine is a 3-file change
+- **Two-phase event bus** — Phase 1 (persistence + state transition) shares a DB transaction and commits atomically; Phase 2 (WebSocket + task sync) fans out in parallel
+- **Centralized state machines** — 6 entity state machines (`Agent`, `Version`, `Release`, `Run`, `Execution`, `Task`) with `transition_*()` as the only status-mutation functions
+- **Normalized error system** — `AppError.to_payload()` produces a canonical `ErrorDescriptor` (`{code, message, data, source, retryable, user_action}`) consumed identically across HTTP, WebSocket, SSE, and DB
+- **Port/Adapter boundaries** — `core/ports/` defines Protocol interfaces; `services/` provides implementations; `core/` never imports concrete services
+- **OTel-backed observation** — `ObservationCollector` injected into `ExecutionContext`; spans exported to both DB and WebSocket for real-time trace display
 - **Graph-based execution** — every agent workflow is a stateful LangGraph, enabling pause, resume, and branch
-- **Unified Run Center** — Chat, Copilot, and Skill Creator share a single event-sourced run lifecycle (Run → Event → Snapshot)
-- **Unified WebSocket layer** — BaseWsClient abstract class; Chat / Run / Notification clients share lifecycle, auth (ws-token), and reconnect logic
-- **Full-chain trace_id propagation** — contextvars-based request tracing from HTTP/WS entry through LangGraph to persistence
-- **Glass-box observability** — real-time Langfuse tracing of every agent decision and state transition
+- **Unified WebSocket layer** — BaseWsClient abstract class; Execution / Notification clients share lifecycle, auth (ws-token), and reconnect logic
 - **RAII sandbox isolation** — per-user Docker containers with automatic handle release, zero state leakage
 - **Canonical model identifiers** — full-stack (provider_name, model_name) resolution via ModelService → ModelFactory
 - **Layered skill system** — skills are versioned units that compose into workflows without coupling
@@ -262,6 +266,10 @@ All modes support remote deployment scenarios:
 
 | Tag | Feature | What it means |
 |-----|---------|---------------|
+| **NEW** | **Architecture Hardening** | 5-layer execution architecture with Engine Protocol, EngineRegistry, two-phase EventBus, centralized state machines, and Port/Adapter boundaries |
+| **NEW** | **Unified Error Contract** | `AppError.to_payload()` produces canonical `ErrorDescriptor` consumed identically across HTTP, WS, SSE, and DB; frontend `ApiError` mirrors the shape with typed `source`/`retryable`/`userAction` |
+| **NEW** | **State Machine Centralization** | 6 entity state machines (`Agent`, `Version`, `Release`, `Run`, `Execution`, `Task`) with `transition_*()` as the only status-mutation functions |
+| **NEW** | **Observation Tracing** | OTel-backed `ObservationCollector` injected into `ExecutionContext`; spans exported to DB and WebSocket for real-time trace display |
 | **NEW** | **Run Center Architecture** | Chat & Copilot fully integrated into Run Center — run details, session recovery, and live event replay on page refresh |
 | **NEW** | **Dark Mode & Preferences** | System / Light / Dark theme switching; redesigned profile page with language & theme preferences |
 | **NEW** | **Unified WebSocket Layer** | BaseWsClient abstract class — Chat, Run, and Notification clients share lifecycle, auth (ws-token), and reconnect logic |

diff --git a/README_CN.md b/README_CN.md
@@ -220,11 +220,15 @@
 
 **核心设计原则：**
 
+- **值域唯一来源** —— `core/contracts/` 以 Literal 类型 + set 常量定义所有规范化值（状态、错误码、触发来源），杜绝魔术字符串
+- **引擎协议 + 注册表** —— 所有执行引擎实现 `ExecutionEngine` Protocol；`EngineRegistry` 将 `runtime_kind` 映射到引擎实例；添加新引擎只需改 3 个文件
+- **两阶段事件总线** —— 第 1 阶段（持久化 + 状态变迁）共享 DB 事务，原子提交；第 2 阶段（WebSocket + 任务同步）并行扇出
+- **集中化状态机** —— 6 个实体状态机（`Agent`、`Version`、`Release`、`Run`、`Execution`、`Task`），`transition_*()` 是唯一的状态修改入口
+- **规范化错误系统** —— `AppError.to_payload()` 输出规范的 `ErrorDescriptor`（`{code, message, data, source, retryable, user_action}`），HTTP/WS/SSE/DB 各传输路径一致消费
+- **端口/适配器边界** —— `core/ports/` 定义 Protocol 接口；`services/` 提供实现；`core/` 不导入具体服务
+- **OTel 观测追踪** —— `ObservationCollector` 注入 `ExecutionContext`；span 导出到 DB 和 WebSocket，支持实时追踪展示
 - **图式执行** —— 每个 Agent 工作流都是有状态的 LangGraph，支持暂停、恢复与分支
-- **统一 Run Center** —— Chat、Copilot、Skill Creator 共享同一套事件溯源运行生命周期（Run → Event → Snapshot）
-- **统一 WebSocket 层** —— BaseWsClient 抽象基类；Chat / Run / Notification 三端客户端共享生命周期、认证（ws-token）与重连逻辑
-- **trace_id 全链路追踪** —— 基于 contextvars 的请求追踪，从 HTTP/WS 入口贯穿 LangGraph 直至持久化
-- **白盒可观测性** —— 基于 Langfuse 实时追踪每一步 Agent 决策与状态流转
+- **统一 WebSocket 层** —— BaseWsClient 抽象基类；Execution / Notification 客户端共享生命周期、认证与重连逻辑
 - **RAII 沙箱隔离** —— 用户级 Docker 容器，句柄自动释放，会话间零状态泄露
 - **规范化模型标识** —— 全栈统一 (provider_name, model_name) 解析路径：ModelService → ModelFactory
 - **分层技能体系** —— 技能是版本化单元，可自由组合成工作流，互不耦合
@@ -262,6 +266,10 @@
 
 | 标签 | 功能 | 一句话说明 |
 |------|------|-----------|
+| **NEW** | **架构硬化** | 5 层执行架构：引擎协议 + EngineRegistry + 两阶段事件总线 + 集中化状态机 + 端口/适配器边界 |
+| **NEW** | **统一错误契约** | `AppError.to_payload()` 输出规范 `ErrorDescriptor`，HTTP/WS/SSE/DB 一致消费；前端 `ApiError` 镜像类型化 `source`/`retryable`/`userAction` |
+| **NEW** | **状态机集中化** | 6 个实体状态机（Agent、Version、Release、Run、Execution、Task），`transition_*()` 为唯一状态修改入口 |
+| **NEW** | **观测追踪** | 基于 OTel 的 `ObservationCollector` 注入 ExecutionContext；span 导出到 DB 和 WebSocket，支持实时追踪 |
 | **NEW** | **Run Center 架构** | Chat 与 Copilot 全面迁入 Run Center——支持运行详情查看、会话恢复、页面刷新后实时事件回放 |
 | **NEW** | **深色模式与偏好设置** | 系统/浅色/深色三种主题切换；重新设计个人资料页面，新增语言与主题偏好 |
 | **NEW** | **统一 WebSocket 层** | 引入 BaseWsClient 抽象基类——Chat、Run、Notification 三端客户端共享生命周期、认证（ws-token）与重连逻辑 |

diff --git a/backend/README.md b/backend/README.md
@@ -48,6 +48,38 @@ cd backend
 uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
 ```
 
+## 项目结构
+
+```
+app/
+├── api/v1/                  # REST 路由模块
+├── common/
+│   └── app_errors.py        # 统一异常层次 + ErrorDescriptor 序列化
+├── core/
+│   ├── contracts/           # 值域唯一来源（DefinitionKind、RuntimeKind、ErrorCode、ErrorSource 等）
+│   ├── engine/              # 执行引擎协议、注册表、4 个内建引擎（CLI/Graph/Code/Copilot）
+│   ├── events/              # 两阶段事件总线（ExecutionEventBus）+ 4 个内建订阅者
+│   ├── state_machines/      # 集中化状态机（6 个实体的转换规则）
+│   ├── observation/         # OTel-backed 观测追踪（注入 ExecutionContext）
+│   ├── ports/               # Protocol 接口，解耦 core/ 与 services/
+│   ├── agent/               # CLI agent 后端（claude_code、codex、openclaw）
+│   ├── copilot/             # Copilot 服务
+│   ├── graph/               # DeepAgents 图构建器 + 代码执行器
+│   ├── skill/               # 技能系统（渐进式加载）
+│   ├── model/               # 模型提供商 + 凭据管理
+│   ├── tools/               # 工具解析器 + MCP 集成
+│   └── a2a/                 # Agent-to-Agent 协议
+├── models/                  # SQLAlchemy ORM 模型
+├── repositories/            # 数据访问层
+├── schemas/                 # Pydantic 请求/响应 Schema
+├── services/                # 服务层（DispatchService、ExecutionOrchestrator、40+ 模块）
+├── websocket/               # WebSocket 处理器（/ws/executions、/ws/notifications、/ws/openclaw）
+├── templates/               # 邮件模板（Jinja2）
+└── utils/                   # 共享工具
+```
+
+> 完整架构文档：[`docs/ARCHITECTURE.md`](../docs/ARCHITECTURE.md) | [中文版](../docs/ARCHITECTURE_CN.md)
+
 ## API 文档
 
 - Swagger UI: http://localhost:8000/docs