diff --git a/docs/XCode-Agent-Framework-design.md b/docs/XCode-Agent-Framework-design.md
new file mode 100644
index 0000000..1f198fa
--- /dev/null
+++ b/docs/XCode-Agent-Framework-design.md
@@ -0,0 +1,213 @@
+Agent Framework 设计文档
+
+版本：v1.0
+项目代号：Project Codexium
+作者：svc.plus 架构组（Pan Haitao）
+目标：统一代码智能、运维智能与模型桥接能力的开发者工作台
+
+一、系统愿景
+
+“让 AI 不只是写代码，而是理解系统。”
+
+Codexium 的目标是构建一个统一的智能代理层，使得开发者在编程、测试、运维的整个生命周期中，都能通过 /api/agent/* 接口访问具备上下文记忆与验证能力的 LLM 工具链。
+
+系统分为三大支柱：
+
+模块	名称	职责
+/api/agent/code	CodeSmith	编码智能：分析、重构、生成、解释代码
+/api/agent/ops	OpsMind	运维智能：测试验证、性能剖析、异常诊断
+/api/agent/bridge	LLM-Bridge	桥接智能：与国内外大模型生态互联
+二、系统架构概览
+flowchart TB
+  subgraph UI["🖥️ Web IDE / Dashboard"]
+    C1[任务列表] --> C2[任务详情与日志]
+    C2 --> C3[运行面板（Playwright / DevTools / LLM）]
+  end
+
+  subgraph API["🧠 Agent Gateway (Node/Deno)"]
+    A1[/api/agent/code/]:::code --> A3
+    A2[/api/agent/ops/]:::ops --> A3
+    A4[/api/agent/bridge/]:::bridge --> A3
+    A3[(Runs Registry + Storage)]
+  end
+
+  subgraph Runtime["⚙️ Runners / Services"]
+    R1[Codex-CLI / Claude-CLI / Gemini-CLI]
+    R2[Playwright MCP Server]
+    R3[DevTools MCP Server]
+    R4[LLM-Bridge Adapter]
+  end
+
+  subgraph Infra["💾 Backend Infra"]
+    D1[(PostgreSQL / SQLite)]
+    D2[(S3 / Local Storage)]
+  end
+
+  UI --> API
+  API --> Runtime
+  API --> Infra
+  Runtime --> D2
+  classDef code fill=#C6E2FF,stroke=#4582EC;
+  classDef ops fill=#FFF2CC,stroke=#D6B656;
+  classDef bridge fill=#D9EAD3,stroke=#6AA84F;
+
+三、API 模块划分与命名语义
+模块路径	名称	职责描述	核心子接口
+/api/agent/code	CodeSmith	面向代码智能任务	analyze, refactor, generate, explain, review
+/api/agent/ops	OpsMind	面向运维与测试任务	playwright, devtools, profile, report
+/api/agent/bridge	LLM-Bridge	模型桥接与分发层	invoke, list-models, proxy
+四、功能说明
+1. CodeSmith（编码智能）
+
+目标： 让 LLM 理解项目上下文并参与重构。
+功能示例：
+
+功能	说明	CLI 或工具
+analyze	分析文件结构与依赖	codex-cli analyze
+refactor	自动重构、删除死代码	codex-cli refactor
+generate	根据提示生成新代码	claude-cli generate
+explain	对复杂逻辑生成自然语言解释	gemini-cli explain
+
+运行模式：
+通过 child_process.spawn 调用 CLI，并以 SSE 流式推送执行日志。
+每次执行结果存储为 run 记录，并关联到任务。
+
+2. OpsMind（运维智能）
+
+目标： 自动化验证与性能剖析。
+
+MCP 接口：
+
+功能	MCP Server	说明
+playwright	mcp-playwright	执行端到端测试、截图、trace
+devtools	mcp-devtools	运行 CPU/Heap Profiler
+profile	mcp-devtools	生成 trace.json 与指标摘要
+report	内部	汇总生成性能分析报告（HTML/PDF）
+
+示例工作流：
+
+POST /api/agent/ops/playwright
+→ 启动 Playwright MCP → trace.zip → 存储为附件 → 任务run状态更新
+
+3. LLM-Bridge（模型桥接层）
+
+目标： 在不暴露私钥的前提下，统一访问国内外大模型生态。
+
+功能	说明	适配对象
+invoke	通用调用接口（支持 OpenAI 格式）	ChatGPT / Claude / Qwen / Yi / Baichuan / Moonshot
+list-models	返回所有可用模型及状态	从注册表动态读取
+proxy	将 REST 调用转为相应 API 代理	可接入 WebSocket 流式返回
+
+配置结构示例：
+
+llm_bridge:
+  providers:
+    openai:
+      endpoint: https://api.openai.com/v1
+      api_key: $OPENAI_API_KEY
+    qwen:
+      endpoint: https://dashscope.aliyuncs.com/api/v1
+      api_key: $DASHSCOPE_API_KEY
+    moonshot:
+      endpoint: https://api.moonshot.cn/v1
+      api_key: $MOONSHOT_API_KEY
+
+
+作用：
+
+对上：所有 /api/agent/code、/api/agent/ops 请求可指定 provider 参数；
+
+对下：桥接各类 LLM API，兼容 JSON Schema 响应；
+
+提供统一上下文缓存机制（如 KV/Redis session）。
+
+五、数据库模型
+CREATE TABLE tasks (
+  id TEXT PRIMARY KEY,
+  title TEXT,
+  summary TEXT,
+  status TEXT CHECK (status IN ('todo','doing','done','archived')),
+  tags TEXT[],
+  created_at TIMESTAMP DEFAULT now(),
+  updated_at TIMESTAMP DEFAULT now()
+);
+
+CREATE TABLE runs (
+  id TEXT PRIMARY KEY,
+  task_id TEXT REFERENCES tasks(id),
+  runner TEXT,
+  input JSONB,
+  output JSONB,
+  status TEXT CHECK (status IN ('queued','running','passed','failed')),
+  artifacts TEXT[],
+  started_at TIMESTAMP,
+  finished_at TIMESTAMP
+);
+
+CREATE TABLE attachments (
+  id TEXT PRIMARY KEY,
+  task_id TEXT REFERENCES tasks(id),
+  name TEXT,
+  kind TEXT,
+  mime TEXT,
+  url TEXT,
+  size INT,
+  created_at TIMESTAMP DEFAULT now()
+);
+
+六、前端设计（Web 工作台）
+
+结构：
+
+区域	功能	技术栈
+左栏	任务列表（搜索、筛选、状态切换）	Zustand + SWR
+右栏	任务详情、运行面板、上传区	Tailwind + shadcn/ui
+底部	实时日志控制台	WebSocket/SSE
+顶部	模型选择（LLM-Bridge 模式切换）	Select + Context Provider
+七、安全与隔离设计
+
+Runner 容器隔离：
+所有 Playwright/DevTools Runner 运行于独立容器，带文件系统隔离。
+
+命令白名单：
+/api/agent/code 仅能执行 codex-cli 等注册命令。
+
+模型访问控制：
+LLM-Bridge 支持：
+
+统一 API Key 管理；
+
+访问审计；
+
+模型路由黑白名单（例如禁止访问海外模型）。
+
+上传验证：
+图片/trace 文件 MIME 检查 + 大小上限（默认 50MB）。
+
+八、部署与扩展
+
+推荐部署模式：
+
+服务	类型	部署建议
+API Gateway	Node 18+	Docker 容器，内网访问 MCP
+Playwright MCP	Sidecar	mcr.microsoft.com/playwright 镜像
+DevTools MCP	Sidecar	chrome-launcher 环境
+LLM-Bridge	统一服务	可独立部署，实现模型代理
+Storage	S3 或 MinIO	附件与 trace 存储
+DB	PostgreSQL	任务、运行、模型状态持久化
+九、未来路线图（v1 → v3）
+阶段	特性	说明
+v1.0	CodeSmith + OpsMind 基础实现	完成 CLI/MCP 集成、运行记录体系
+v1.1	LLM-Bridge 接入国内模型	Qwen、Yi、Baichuan、Moonshot
+v2.0	会话上下文与任务记忆	Redis + Vector Store
+v2.1	Web 工作流可视化（Flow View）	支持多步骤组合任务
+v3.0	多代理协作模式	让 CodeSmith 与 OpsMind 自动协作验证
+十、总结与命名哲学
+
+CodeSmith → “写得比人快一点”
+
+OpsMind → “想得比机器深一点”
+
+LLM-Bridge → “连接的不是模型，而是生态”
+
+三者共同组成一个统一的“Agent Infra”，能运行在开发机、CI/CD 管道、甚至本地容器中，为 Cloud-Neutral 工程体系提供智能层。