myagent-ai 1.0.0

package/web/api_server.py

@@ -0,0 +1,2043 @@
+"""
+web/api_server.py - 管理后台 HTTP API
+======================================
+为管理 UI 提供 RESTful API。
+"""
+from __future__ import annotations
+import asyncio, json, os, time, shutil
+from pathlib import Path
+from typing import Optional
+from aiohttp import web
+from core.logger import get_logger
+from core.llm import Message
+from config import ModelEntry
+import datetime
+
+logger = get_logger("myagent.api")
+
+
+def _agent_color(name: str) -> str:
+    """Generate a consistent color for an agent based on its name."""
+    colors = ['#4f46e5','#7c3aed','#ec4899','#ef4444','#f59e0b','#10b981',
+              '#06b6d4','#3b82f6','#8b5cf6','#f97316','#14b8a6','#6366f1']
+    h = sum(ord(c) for c in name)
+    return colors[h % len(colors)]
+
+
+class ApiServer:
+    def __init__(self, app_core):
+        self.core = app_core
+        self.app = web.Application()
+        self._exec_progress: dict = {}
+        # Wrap the executor to track progress in real-time (deferred to initialize())
+        self._executor_wrapped = False
+        self._setup_routes()
+        self._runner: Optional[web.AppRunner] = None
+
+    def _setup_routes(self):
+        r = self.app.router
+        r.add_get("/api/status", self.handle_status)
+        r.add_post("/api/shutdown", self.handle_shutdown)
+        r.add_get("/api/agents", self.handle_list_agents)
+        r.add_get("/api/agents/tree", self.handle_agents_tree)
+        r.add_post("/api/agents", self.handle_create_agent)
+        r.add_get("/api/agents/{name:[a-zA-Z0-9_/-]+}", self.handle_get_agent)
+        r.add_put("/api/agents/{name:[a-zA-Z0-9_/-]+}", self.handle_update_agent)
+        r.add_delete("/api/agents/{name:[a-zA-Z0-9_/-]+}", self.handle_delete_agent)
+        r.add_get("/api/agents/{name:[a-zA-Z0-9_/-]+}/soul", self.handle_get_soul)
+        r.add_put("/api/agents/{name:[a-zA-Z0-9_/-]+}/soul", self.handle_set_soul)
+        r.add_get("/api/agents/{name:[a-zA-Z0-9_/-]+}/identity", self.handle_get_identity)
+        r.add_put("/api/agents/{name:[a-zA-Z0-9_/-]+}/identity", self.handle_set_identity)
+        r.add_get("/api/agents/{name:[a-zA-Z0-9_/-]+}/user", self.handle_get_user)
+        r.add_put("/api/agents/{name:[a-zA-Z0-9_/-]+}/user", self.handle_set_user)
+        r.add_get("/api/agents/{name:[a-zA-Z0-9_/-]+}/sessions", self.handle_agent_sessions)
+        r.add_get("/api/agents/{name:[a-zA-Z0-9_/-]+}/children", self.handle_list_children)
+        r.add_post("/api/agents/{name:[a-zA-Z0-9_/-]+}/children", self.handle_create_child)
+        r.add_get("/api/platforms", self.handle_list_platforms)
+        r.add_put("/api/platforms/{name}", self.handle_update_platform)
+        # ── 模型库 CRUD ──
+        r.add_get("/api/models", self.handle_list_models)
+        r.add_post("/api/models", self.handle_add_model)
+        r.add_put("/api/models/{model_id}", self.handle_update_model)
+        r.add_delete("/api/models/{model_id}", self.handle_delete_model)
+        # ── Agent 绑定查询 ──
+        r.add_get("/api/agents/{name:[a-zA-Z0-9_/-]+}/bindings", self.handle_agent_bindings)
+        r.add_get("/api/sessions", self.handle_list_sessions)
+        r.add_get("/api/sessions/{sid}/messages", self.handle_get_messages)
+        r.add_delete("/api/sessions/{sid}", self.handle_clear_session)
+        r.add_get("/api/memory/stats", self.handle_memory_stats)
+        r.add_get("/api/memory/search", self.handle_memory_search)
+        r.add_get("/api/memory/long-term", self.handle_list_long_term)
+        r.add_delete("/api/memory/long-term/{mid}", self.handle_delete_long_term)
+        r.add_post("/api/memory/cleanup", self.handle_memory_cleanup)
+        r.add_get("/api/llm", self.handle_get_llm)
+        r.add_put("/api/llm", self.handle_update_llm)
+        r.add_post("/api/llm/test", self.handle_test_llm)
+        r.add_get("/api/llm/usage", self.handle_llm_usage)
+        r.add_get("/api/skills", self.handle_list_skills)
+        r.add_get("/api/skills/{name}", self.handle_get_skill)
+        r.add_get("/api/executor", self.handle_get_executor)
+        r.add_put("/api/executor", self.handle_update_executor)
+        r.add_get("/api/workdir", self.handle_get_workdir)
+        # ── Task Plan ──
+        r.add_get("/api/task-plan", self.handle_get_task_plan)
+        r.add_put("/api/task-plan", self.handle_update_task_plan)
+        r.add_post("/api/task-plan", self.handle_add_task_item)
+        r.add_delete("/api/task-plan/{idx:int}", self.handle_delete_task_item)
+        r.add_put("/api/workdir", self.handle_set_workdir)
+        r.add_get("/api/workdir/files", self.handle_list_workdir)
+        r.add_get("/api/logs", self.handle_get_logs)
+        r.add_get("/api/logs/stream", self.handle_log_stream)
+        r.add_post("/api/chat", self.handle_chat)
+        r.add_get("/chat", self.handle_chat_page)
+        r.add_get("/api/execution/progress", self.handle_execution_progress)
+        # ── 组织管理 ──
+        r.add_get("/api/organization", self.handle_get_organization)
+        r.add_put("/api/organization", self.handle_update_organization)
+        r.add_get("/api/organization/info", self.handle_get_org_info)
+        r.add_put("/api/organization/info", self.handle_update_org_info)
+        r.add_get("/api/organization/knowledge", self.handle_list_org_knowledge)
+        r.add_post("/api/organization/knowledge/upload", self.handle_upload_org_knowledge)
+        r.add_delete("/api/organization/knowledge", self.handle_delete_org_knowledge)
+        # ── Agent 知识库 ──
+        r.add_get("/api/agents/{name:[a-zA-Z0-9_/-]+}/knowledge", self.handle_list_agent_knowledge)
+        r.add_post("/api/agents/{name:[a-zA-Z0-9_/-]+}/knowledge/upload", self.handle_upload_agent_knowledge)
+        r.add_delete("/api/agents/{name:[a-zA-Z0-9_/-]+}/knowledge", self.handle_delete_agent_knowledge)
+        # ── 知识库 RAG 搜索 ──
+        r.add_post("/api/knowledge/search", self.handle_knowledge_search)
+        # ── 配置管理 (热重载/导入/导出) ──
+        r.add_get("/api/config", self.handle_get_config)
+        r.add_post("/api/config/reload", self.handle_reload_config)
+        r.add_post("/api/config/export", self.handle_export_config)
+        r.add_post("/api/config/import", self.handle_import_config)
+        # ── Agent 间通信 ──
+        r.add_get("/api/communication", self.handle_get_communication)
+        r.add_put("/api/communication", self.handle_update_communication)
+        r.add_get("/api/communication/status", self.handle_comm_status)
+        r.add_get("/api/communication/peers", self.handle_list_peers)
+        r.add_post("/api/communication/peers", self.handle_add_peer)
+        r.add_delete("/api/communication/peers/{agent_id}", self.handle_remove_peer)
+        r.add_get("/api/communication/messages", self.handle_comm_messages)
+        r.add_post("/api/communication/messages", self.handle_send_message)
+        r.add_post("/api/communication/messages/{msg_id}/ack", self.handle_ack_message)
+        # ── 群聊管理 ──
+        r.add_get("/api/groups", self.handle_list_groups)
+        r.add_post("/api/groups", self.handle_create_group)
+        r.add_get("/api/groups/{gid}", self.handle_get_group)
+        r.add_put("/api/groups/{gid}", self.handle_update_group)
+        r.add_delete("/api/groups/{gid}", self.handle_delete_group)
+        r.add_get("/api/groups/{gid}/stats", self.handle_group_stats)
+        # ── 群成员管理 ──
+        r.add_post("/api/groups/{gid}/members", self.handle_add_member)
+        r.add_delete("/api/groups/{gid}/members/{agent_path:[a-zA-Z0-9_/-]+}", self.handle_remove_member)
+        r.add_put("/api/groups/{gid}/members/{agent_path:[a-zA-Z0-9_/-]+}/role", self.handle_set_member_role)
+        r.add_put("/api/groups/{gid}/members/{agent_path:[a-zA-Z0-9_/-]+}/mute", self.handle_set_member_muted)
+        # ── 群消息 ──
+        r.add_get("/api/groups/{gid}/messages", self.handle_get_group_messages)
+        r.add_post("/api/groups/{gid}/messages", self.handle_send_group_message)
+        r.add_delete("/api/groups/{gid}/messages", self.handle_clear_group_messages)
+        ui_dir = Path(__file__).parent / "ui"
+        if ui_dir.exists():
+            r.add_static("/ui", str(ui_dir))
+        # Defer executor tracker installation until initialize() is called        # This avoids issues during route setup        # The tracker is installed in _install_executor_tracker()        self._install_executor_tracker()            r.add_get("/", self.handle_index)
+
+    async def handle_index(self, request):
+        raise web.HTTPFound("/ui/chat.html")
+
+    def _get_group_manager(self):
+        """获取群聊管理器实例（懒加载）"""
+        if not hasattr(self, '_group_manager'):
+            from groups.manager import GroupManager
+            self._group_manager = GroupManager(
+                data_dir=self.core.config_mgr.data_dir
+            )
+            self._group_manager.initialize()
+        return self._group_manager
+
+    # --- Execution Progress ---
+    async def handle_execution_progress(self, request):
+        """GET /api/execution/progress - 返回当前执行进度"""
+        active = []
+        now = time.time()
+        for eid, info in list(self._exec_progress.items()):
+            if info["status"] == "running":
+                info["elapsed"] = now - info["start_time"]
+            active.append({"id": eid, **info})
+        return web.json_response({
+            "active": active,
+            "has_running": any(i["status"] == "running" for i in active),
+        })
+
+    # --- Chat ---
+    async def handle_chat(self, request):
+        """POST /api/chat - 聊天消息处理"""
+        try:
+            data = await request.json()
+        except Exception:
+            return web.json_response({"error": "invalid JSON"}, status=400)
+
+        message = data.get("message", "").strip()
+        if not message:
+            return web.json_response({"error": "message is required"}, status=400)
+
+        agent_name = data.get("agent_name", "default") or "default"
+        # 支持 path 格式 (如 "coder/python-expert")
+        agent_path = data.get("agent_path", agent_name)
+        raw_session_id = data.get("session_id", "") or "web_default"
+        session_id = f"{agent_path}_{raw_session_id}"
+        chat_mode = data.get("mode", "")  # "exec" = 执行模式
+
+        # ── 执行模式: 注入任务规划上下文 ──
+        task_plan_context = ""
+        if chat_mode == "exec":
+            tp = self._task_md_path(agent_path)
+            if tp.exists():
+                existing_content = tp.read_text(encoding="utf-8")
+                tasks = self._parse_task_md(existing_content)
+                if tasks:
+                    pending = [f"  - [ ] {t['text']}" for t in tasks if not t['done']]
+                    done = [f"  - [x] {t['text']}" for t in tasks if t['done']]
+                    task_plan_context = "\n\n## 当前任务计划 (task.md)\n"
+                    if done:
+                        task_plan_context += "已完成:\n" + "\n".join(done) + "\n"
+                    if pending:
+                        task_plan_context += "待完成:\n" + "\n".join(pending) + "\n"
+                    task_plan_context += "\n请在回复中包含更新后的任务计划。用以下格式列出任务:\n```\n## 任务计划\n- [ ] 任务1\n- [ ] 任务2\n```\n"
+
+        if task_plan_context:
+            message = message + task_plan_context
+
+        try:
+            # 检查 Agent 是否指定了特定模型（含备用模型列表）
+            agent_cfg = self._read_agent_config(agent_path)
+            model_chain = self._build_model_chain(agent_cfg, agent_path)
+
+            if model_chain and self.core.llm:
+                # 依次尝试主模型和备用模型
+                response = await self._try_model_chain(
+                    model_chain, message, session_id
+                )
+            else:
+                response = await self.core.process_message(message, session_id)
+
+            # 保存到记忆
+            if self.core.memory:
+                self.core.memory.add_short_term(
+                    session_id=session_id, role="user", content=message,
+                )
+                self.core.memory.add_short_term(
+                    session_id=session_id, role="assistant", content=response,
+                )
+
+            # ── 执行模式: 从回复中提取并更新任务计划 ──
+            if chat_mode == "exec" and self.core.llm:
+                try:
+                    await self._extract_and_update_task_plan(agent_path, response)
+                except Exception as tp_err:
+                    logger.warning(f"任务计划更新失败: {tp_err}")
+
+            return web.json_response({"response": response, "session_id": session_id, "agent_name": agent_path, "agent_path": agent_path})
+        except Exception as e:
+            logger.error(f"Chat error: {e}", exc_info=True)
+            return web.json_response({"error": str(e)}, status=500)
+
+    async def handle_chat_page(self, request):
+        """GET /chat - 重定向到聊天页面"""
+        raise web.HTTPFound("/ui/chat.html")
+
+    # --- System ---
+    async def handle_status(self, request):
+        c = self.core
+        return web.json_response({
+            "running": c._running, "provider": c.config.llm.provider,
+            "model": c.config.llm.model, "session": c._session_id,
+            "memory": c.memory.get_stats() if c.memory else {},
+            "queue": c.task_queue.get_stats() if c.task_queue else {},
+            "skills": len(c.skill_registry.list_skills()) if c.skill_registry else 0,
+        })
+
+    # ── Task Plan (task.md) ──
+    def _task_md_path(self, agent_path: str = "default") -> Path:
+        """Return the task.md path for a given agent."""
+        ad = self._agent_dir(agent_path)
+        ad.mkdir(parents=True, exist_ok=True)
+        return ad / "task.md"
+
+    def _parse_task_md(self, content: str) -> list:
+        """Parse task.md content into list of {text, done, raw_line}."""
+        tasks = []
+        for line in content.splitlines():
+            stripped = line.strip()
+            if not stripped or stripped.startswith('#'):
+                continue
+            # Match markdown checkboxes: - [ ] / - [x] / - [X]
+            import re
+            m = re.match(r'^-\s*\[([ xX])\]\s*(.+)$', stripped)
+            if m:
+                tasks.append({"done": m.group(1).lower() == 'x', "text": m.group(2).strip()})
+        return tasks
+
+    def _serialize_task_md(self, tasks: list) -> str:
+        """Serialize task list to markdown."""
+        lines = ["# Task Plan\n"]
+        for t in tasks:
+            ck = "x" if t.get("done") else " "
+            lines.append(f"- [{ck}] {t.get('text', '')}")
+        return "\n".join(lines)
+
+    async def _extract_and_update_task_plan(self, agent_path: str, response_text: str):
+        """从 Agent 回复中提取任务计划并更新 task.md"""
+        import re
+        
+        # 尝试从回复中提取任务计划
+        # 匹配格式: ## 任务计划 / ## Task Plan 后跟 - [ ] / - [x] 列表
+        tasks_found = []
+        in_task_section = False
+        for line in response_text.splitlines():
+            stripped = line.strip()
+            if re.match(r'^##\s*(任务计划|task\s*plan)', stripped, re.IGNORECASE):
+                in_task_section = True
+                continue
+            if in_task_section:
+                if stripped.startswith('#'):
+                    break  # 遇到下一个标题，结束
+                m = re.match(r'^-\s*\[([ xX])\]\s*(.+)$', stripped)
+                if m:
+                    tasks_found.append({"done": m.group(1).lower() == 'x', "text": m.group(2).strip()})
+        
+        if tasks_found:
+            tp = self._task_md_path(agent_path)
+            tp.write_text(self._serialize_task_md(tasks_found), encoding="utf-8")
+            logger.info(f"[exec模式] 任务计划已更新: {agent_path} ({len(tasks_found)} 项任务)")
+
+    async def handle_get_task_plan(self, request):
+        """GET /api/task-plan?agent=default - Get task plan for an agent."""
+        agent_path = request.query.get("agent", "default")
+        tp = self._task_md_path(agent_path)
+        if not tp.exists():
+            return web.json_response({"agent": agent_path, "tasks": [], "raw": ""})
+        content = tp.read_text(encoding="utf-8")
+        tasks = self._parse_task_md(content)
+        return web.json_response({"agent": agent_path, "tasks": tasks, "raw": content})
+
+    async def handle_update_task_plan(self, request):
+        """PUT /api/task-plan - Overwrite entire task plan."""
+        data = await request.json()
+        agent_path = data.get("agent", "default")
+        tasks = data.get("tasks", [])
+        tp = self._task_md_path(agent_path)
+        content = self._serialize_task_md(tasks)
+        tp.write_text(content, encoding="utf-8")
+        return web.json_response({"ok": True, "agent": agent_path, "tasks": tasks})
+
+    async def handle_add_task_item(self, request):
+        """POST /api/task-plan - Add a new task item."""
+        data = await request.json()
+        agent_path = data.get("agent", "default")
+        text = data.get("text", "").strip()
+        if not text:
+            return web.json_response({"error": "text is required"}, status=400)
+        tp = self._task_md_path(agent_path)
+        content = tp.read_text(encoding="utf-8") if tp.exists() else ""
+        tasks = self._parse_task_md(content)
+        tasks.append({"done": False, "text": text})
+        tp.write_text(self._serialize_task_md(tasks), encoding="utf-8")
+        return web.json_response({"ok": True, "tasks": tasks, "added": len(tasks) - 1})
+
+    async def handle_delete_task_item(self, request):
+        """DELETE /api/task-plan/{idx} - Delete task by index."""
+        idx = int(request.match_info["idx"])
+        agent_path = request.query.get("agent", "default")
+        tp = self._task_md_path(agent_path)
+        if not tp.exists():
+            return web.json_response({"error": "task plan not found"}, status=404)
+        content = tp.read_text(encoding="utf-8")
+        tasks = self._parse_task_md(content)
+        if 0 <= idx < len(tasks):
+            tasks.pop(idx)
+        tp.write_text(self._serialize_task_md(tasks), encoding="utf-8")
+        return web.json_response({"ok": True, "tasks": tasks})
+
+    async def handle_shutdown(self, request):
+        self.core._running = False
+        asyncio.create_task(self.core.shutdown())
+        return web.json_response({"ok": True})
+
+    # --- Agents (层级体系) ---
+    # 目录结构: agents/default/{config.json, soul.md, ...}
+    #           agents/coder/{config.json, soul.md, ...}
+    #           agents/coder/python-expert/{config.json, soul.md, ...}
+    # agent path = 相对于 agents/ 的路径, 如 "default", "coder", "coder/python-expert"
+
+    def _agents_dir(self):
+        d = self.core.config_mgr.data_dir / "agents"
+        d.mkdir(parents=True, exist_ok=True)
+        return d
+
+    def _agent_dir(self, path: str) -> Path:
+        """根据 agent path 返回目录 (path 如 'coder/python-expert')"""
+        return self._agents_dir() / path
+
+    def _ensure_default_agent(self):
+        """确保默认 agent 存在"""
+        ad = self._agent_dir("default")
+        if not (ad / "config.json").exists():
+            ad.mkdir(parents=True, exist_ok=True)
+            cfg = {
+                "name": "default",
+                "description": "默认助手 - 本机运行模式",
+                "avatar_color": _agent_color("default"),
+                "avatar_emoji": "🤖",
+                "execution_mode": "local",
+                "enabled": True,
+                "system_prompt": "你是 MyAgent 默认助手，运行在本机模式。请用友好、专业的方式回答用户的问题。",
+            }
+            (ad / "config.json").write_text(json.dumps(cfg, indent=2, ensure_ascii=False))
+            for fn, default in [
+                ("soul.md", "# Default Agent\n\n## 性格\n专业、友好的AI助手\n"),
+                ("identity.md", "# Default Agent\n\n## 身份\nMyAgent 默认AI助手\n"),
+                ("user.md", "# 用户信息\n\n## 用户偏好\n<!-- 在此处记录用户偏好 -->\n"),
+            ]:
+                if not (ad / fn).exists():
+                    (ad / fn).write_text(default)
+            logger.info("已创建默认 Agent")
+
+    def _read_agent_config(self, path: str) -> dict | None:
+        """读取 agent 配置"""
+        cfg_file = self._agent_dir(path) / "config.json"
+        if not cfg_file.exists():
+            return None
+        return json.loads(cfg_file.read_text())
+
+    def _write_agent_config(self, path: str, cfg: dict):
+        """写入 agent 配置"""
+        ad = self._agent_dir(path)
+        ad.mkdir(parents=True, exist_ok=True)
+        (ad / "config.json").write_text(json.dumps(cfg, indent=2, ensure_ascii=False))
+
+    def _scan_agents_flat(self, base_dir: Path = None, prefix: str = "") -> list[dict]:
+        """递归扫描所有 agent，返回扁平列表"""
+        if base_dir is None:
+            base_dir = self._agents_dir()
+        agents = []
+        if not base_dir.exists():
+            return agents
+        for d in sorted(base_dir.iterdir()):
+            if not d.is_dir():
+                continue
+            cfg_file = d / "config.json"
+            if not cfg_file.exists():
+                continue
+            agent_path = f"{prefix}{d.name}" if not prefix else f"{prefix}/{d.name}"
+            cfg = json.loads(cfg_file.read_text())
+            agent = {"path": agent_path, "name": d.name, **cfg}
+            agent["avatar_color"] = cfg.get("avatar_color") or _agent_color(d.name)
+            agent["depth"] = agent_path.count("/")
+            agents.append(agent)
+            # 递归子目录
+            agents.extend(self._scan_agents_flat(d, agent_path))
+        return agents
+
+    def _build_agent_tree(self, agents_flat: list[dict]) -> list[dict]:
+        """将扁平 agent 列表构建为树结构"""
+        # 按 path 索引
+        by_path = {a["path"]: {**a, "children": []} for a in agents_flat}
+        roots = []
+        for a in agents_flat:
+            path = a["path"]
+            parent_path = "/".join(path.split("/")[:-1]) if "/" in path else None
+            node = by_path[path]
+            if parent_path and parent_path in by_path:
+                by_path[parent_path]["children"].append(node)
+            else:
+                roots.append(node)
+        return roots
+
+    async def handle_list_agents(self, request):
+        """GET /api/agents - 返回扁平 agent 列表"""
+        self._ensure_default_agent()
+        agents = self._scan_agents_flat()
+        # 统计会话数
+        if self.core.memory:
+            rows = self.core.memory._get_conn().execute(
+                "SELECT session_id, COUNT(*) as cnt FROM memories "
+                "WHERE category='short_term' GROUP BY session_id").fetchall()
+            session_counts = {}
+            for r in rows:
+                sid = r["session_id"]
+                for ap in [sid.split("_")[0], sid]:
+                    session_counts[ap] = session_counts.get(ap, 0) + r["cnt"]
+            for a in agents:
+                a["session_count"] = session_counts.get(a["path"], 0)
+        return web.json_response(agents)
+
+    async def handle_agents_tree(self, request):
+        """GET /api/agents/tree - 返回树形结构"""
+        self._ensure_default_agent()
+        agents_flat = self._scan_agents_flat()
+        # 统计会话数
+        if self.core.memory:
+            rows = self.core.memory._get_conn().execute(
+                "SELECT session_id, COUNT(*) as cnt FROM memories "
+                "WHERE category='short_term' GROUP BY session_id").fetchall()
+            session_counts = {}
+            for r in rows:
+                sid = r["session_id"]
+                for ap in [sid.split("_")[0], sid]:
+                    session_counts[ap] = session_counts.get(ap, 0) + r["cnt"]
+            for a in agents_flat:
+                a["session_count"] = session_counts.get(a["path"], 0)
+        tree = self._build_agent_tree(agents_flat)
+        return web.json_response(tree)
+
+    async def handle_create_agent(self, request):
+        """POST /api/agents - 创建顶级 agent"""
+        self._ensure_default_agent()
+        data = await request.json()
+        name = data.get("name", "").strip()
+        if not name:
+            name = f"agent_{int(time.time())}"
+        # 安全校验
+        if "/" in name or "\\" in name or name == "default":
+            return web.json_response({"error": "invalid name (no slashes, cannot be 'default')"}, status=400)
+
+        ad = self._agent_dir(name)
+        if (ad / "config.json").exists():
+            return web.json_response({"error": f"Agent '{name}' already exists"}, status=409)
+
+        cfg = {
+            "name": name,
+            "description": data.get("description", ""),
+            "avatar_color": data.get("avatar_color") or _agent_color(name),
+            "avatar_emoji": data.get("avatar_emoji", ""),
+            "execution_mode": data.get("execution_mode", "sandbox"),
+            "enabled": True,
+            "system_prompt": data.get("system_prompt") or data.get("soul") or f"你是{name}，一个专业的AI助手。",
+        }
+        if "model" in data:
+            cfg["model"] = data["model"]
+        # 平台绑定和模型库引用
+        if data.get("platform"):
+            cfg["platform"] = data["platform"]
+        if data.get("platform_token"):
+            cfg["platform_token"] = data["platform_token"]
+        if data.get("platform_app_id"):
+            cfg["platform_app_id"] = data["platform_app_id"]
+        if data.get("platform_app_secret"):
+            cfg["platform_app_secret"] = data["platform_app_secret"]
+        if data.get("model_id"):
+            cfg["model_id"] = data["model_id"]
+        if data.get("backup_model_ids"):
+            cfg["backup_model_ids"] = [x for x in data["backup_model_ids"] if isinstance(x, str) and x.strip()]
+
+        ad.mkdir(parents=True, exist_ok=True)
+        (ad / "config.json").write_text(json.dumps(cfg, indent=2, ensure_ascii=False))
+        for fn, default in [
+            ("soul.md", f"# {name}\n\n## 性格\n专业AI助手\n"),
+            ("identity.md", f"# {name}\n\n## 身份\nAI助手\n"),
+            ("user.md", f"# {name} 用户信息\n\n## 用户偏好\n<!-- 在此处记录用户偏好 -->\n"),
+        ]:
+            if not (ad / fn).exists():
+                (ad / fn).write_text(default)
+
+        logger.info(f"创建 Agent: {name} (sandbox模式)")
+        return web.json_response({"ok": True, "path": name, "name": name, "avatar_color": cfg["avatar_color"]})
+
+    async def handle_create_child(self, request):
+        """POST /api/agents/{parent}/children - 创建子 agent"""
+        parent_path = request.match_info["name"]
+        self._ensure_default_agent()
+
+        parent_cfg = self._read_agent_config(parent_path)
+        if not parent_cfg:
+            return web.json_response({"error": f"Parent agent '{parent_path}' not found"}, status=404)
+
+        data = await request.json()
+        name = data.get("name", "").strip()
+        if not name:
+            name = f"agent_{int(time.time())}"
+        if "/" in name or "\\" in name:
+            return web.json_response({"error": "invalid name (no slashes)"}, status=400)
+
+        child_path = f"{parent_path}/{name}"
+        ad = self._agent_dir(child_path)
+        if (ad / "config.json").exists():
+            return web.json_response({"error": f"Agent '{child_path}' already exists"}, status=409)
+
+        cfg = {
+            "name": name,
+            "parent": parent_path,
+            "description": data.get("description", ""),
+            "avatar_color": data.get("avatar_color") or _agent_color(name),
+            "avatar_emoji": data.get("avatar_emoji", ""),
+            "execution_mode": data.get("execution_mode", "sandbox"),
+            "enabled": True,
+            "system_prompt": data.get("system_prompt") or data.get("soul") or f"你是{name}，{parent_path}的子Agent。请用专业的方式完成你的任务。",
+        }
+        if "model" in data:
+            cfg["model"] = data["model"]
+        # 平台绑定和模型库引用
+        if data.get("platform"):
+            cfg["platform"] = data["platform"]
+        if data.get("platform_token"):
+            cfg["platform_token"] = data["platform_token"]
+        if data.get("platform_app_id"):
+            cfg["platform_app_id"] = data["platform_app_id"]
+        if data.get("platform_app_secret"):
+            cfg["platform_app_secret"] = data["platform_app_secret"]
+        if data.get("model_id"):
+            cfg["model_id"] = data["model_id"]
+        if data.get("backup_model_ids"):
+            cfg["backup_model_ids"] = [x for x in data["backup_model_ids"] if isinstance(x, str) and x.strip()]
+
+        ad.mkdir(parents=True, exist_ok=True)
+        (ad / "config.json").write_text(json.dumps(cfg, indent=2, ensure_ascii=False))
+        for fn, default in [
+            ("soul.md", f"# {name}\n\n## 上级: {parent_path}\n## 性格\n专业AI助手\n"),
+            ("identity.md", f"# {name}\n\n## 身份\n{parent_path} 的子 Agent\n"),
+            ("user.md", f"# {name} 用户信息\n\n## 用户偏好\n<!-- 在此处记录用户偏好 -->\n"),
+        ]:
+            if not (ad / fn).exists():
+                (ad / fn).write_text(default)
+
+        logger.info(f"创建子 Agent: {child_path} (sandbox模式)")
+        return web.json_response({"ok": True, "path": child_path, "name": name, "parent": parent_path, "avatar_color": cfg["avatar_color"]})
+
+    async def handle_list_children(self, request):
+        """GET /api/agents/{parent}/children - 列出子 agent"""
+        parent_path = request.match_info["name"]
+        parent_dir = self._agent_dir(parent_path)
+        if not (parent_dir / "config.json").exists():
+            return web.json_response({"error": f"Agent '{parent_path}' not found"}, status=404)
+
+        children = []
+        if parent_dir.exists():
+            for d in sorted(parent_dir.iterdir()):
+                if d.is_dir() and (d / "config.json").exists():
+                    cfg = json.loads((d / "config.json").read_text())
+                    child_path = f"{parent_path}/{d.name}"
+                    child = {"path": child_path, "name": d.name, "parent": parent_path, **cfg}
+                    child["avatar_color"] = cfg.get("avatar_color") or _agent_color(d.name)
+                    child["depth"] = child_path.count("/")
+                    children.append(child)
+        return web.json_response(children)
+
+    async def handle_get_agent(self, request):
+        """GET /api/agents/{path} - 获取 agent 详情"""
+        path = request.match_info["name"]
+        ad = self._agent_dir(path)
+        if not (ad / "config.json").exists():
+            return web.json_response({"error": "not found"}, status=404)
+        cfg = json.loads((ad / "config.json").read_text())
+        soul = (ad / "soul.md").read_text() if (ad / "soul.md").exists() else ""
+        identity = (ad / "identity.md").read_text() if (ad / "identity.md").exists() else ""
+        user = (ad / "user.md").read_text() if (ad / "user.md").exists() else ""
+        # 列出子 agent
+        children = []
+        for d in sorted(ad.iterdir()):
+            if d.is_dir() and (d / "config.json").exists():
+                children.append(d.name)
+        # 如果有 model_id，解析为完整模型信息
+        model_info = None
+        model_id = cfg.get("model_id", "")
+        if model_id:
+            for me in self.core.config.models_library:
+                if me.id == model_id:
+                    model_info = {"id": me.id, "name": me.name, "provider": me.provider,
+                                 "model": me.model, "base_url": me.base_url, "enabled": me.enabled}
+                    break
+        result = {"path": path, **cfg, "soul": soul, "identity": identity, "user": user, "children": children}
+        if model_info:
+            result["model_info"] = model_info
+        return web.json_response(result)
+
+    async def handle_update_agent(self, request):
+        """PUT /api/agents/{path} - 更新 agent 配置"""
+        path = request.match_info["name"]
+        data = await request.json()
+        ad = self._agent_dir(path)
+        if not (ad / "config.json").exists():
+            return web.json_response({"error": "not found"}, status=404)
+        cfg = json.loads((ad / "config.json").read_text())
+        # 更新允许的字段
+        for k in ("description", "avatar_color", "avatar_emoji", "model", "system_prompt",
+                   "execution_mode", "enabled", "sandbox_image", "sandbox_network", "sandbox_memory",
+                   "platform", "platform_token", "platform_app_id", "platform_app_secret",
+                   "model_id", "backup_model_ids"):
+            if k in data:
+                if k == "backup_model_ids":
+                    cfg[k] = [x for x in data[k] if isinstance(x, str) and x.strip()]
+                else:
+                    cfg[k] = data[k]
+        (ad / "config.json").write_text(json.dumps(cfg, indent=2, ensure_ascii=False))
+        if "soul" in data: (ad / "soul.md").write_text(data["soul"])
+        if "identity" in data: (ad / "identity.md").write_text(data["identity"])
+        if "user" in data: (ad / "user.md").write_text(data["user"])
+        logger.info(f"更新 Agent: {path}")
+        return web.json_response({"ok": True})
+
+    async def handle_delete_agent(self, request):
+        """DELETE /api/agents/{path} - 删除 agent 及其所有子 agent"""
+        path = request.match_info["name"]
+        if path == "default":
+            return web.json_response({"error": "cannot delete default agent"}, status=403)
+        ad = self._agent_dir(path)
+        if not (ad / "config.json").exists():
+            return web.json_response({"error": "not found"}, status=404)
+        if ad.exists():
+            shutil.rmtree(ad)
+        logger.info(f"删除 Agent: {path}")
+        return web.json_response({"ok": True})
+
+    async def handle_get_soul(self, request):
+        path = request.match_info["name"]
+        p = self._agent_dir(path) / "soul.md"
+        if not p.parent.exists() or not (p.parent / "config.json").exists():
+            return web.json_response({"error": "not found"}, status=404)
+        return web.json_response({"soul": p.read_text() if p.exists() else ""})
+
+    async def handle_set_soul(self, request):
+        data = await request.json(); ad = self._agent_dir(request.match_info["name"])
+        ad.mkdir(parents=True, exist_ok=True)
+        (ad / "soul.md").write_text(data.get("soul", ""))
+        return web.json_response({"ok": True})
+
+    async def handle_get_identity(self, request):
+        path = request.match_info["name"]
+        p = self._agent_dir(path) / "identity.md"
+        if not p.parent.exists() or not (p.parent / "config.json").exists():
+            return web.json_response({"error": "not found"}, status=404)
+        return web.json_response({"identity": p.read_text() if p.exists() else ""})
+
+    async def handle_set_identity(self, request):
+        data = await request.json(); ad = self._agent_dir(request.match_info["name"])
+        ad.mkdir(parents=True, exist_ok=True)
+        (ad / "identity.md").write_text(data.get("identity", ""))
+        return web.json_response({"ok": True})
+
+    async def handle_get_user(self, request):
+        path = request.match_info["name"]
+        p = self._agent_dir(path) / "user.md"
+        if not p.parent.exists() or not (p.parent / "config.json").exists():
+            return web.json_response({"error": "not found"}, status=404)
+        return web.json_response({"user": p.read_text() if p.exists() else ""})
+
+    async def handle_set_user(self, request):
+        data = await request.json(); ad = self._agent_dir(request.match_info["name"])
+        ad.mkdir(parents=True, exist_ok=True)
+        (ad / "user.md").write_text(data.get("user", ""))
+        return web.json_response({"ok": True})
+
+    # --- Executor ---
+    async def handle_get_executor(self, request):
+        info = self.core.executor.get_execution_info() if self.core.executor else {}
+        cfg = self.core.config.executor if self.core.config else None
+        return web.json_response({
+            **info,
+            "timeout": cfg.timeout if cfg else 300,
+            "auto_fix": cfg.auto_fix if cfg else True,
+            "max_output_length": cfg.max_output_length if cfg else 50000,
+        })
+
+    async def handle_update_executor(self, request):
+        data = await request.json()
+        cfg_path = self.core.config_mgr._config_file
+        cfg_data = json.loads(cfg_path.read_text()) if cfg_path.exists() else {}
+        exe = cfg_data.setdefault("executor", {})
+        for k in ("execution_mode", "timeout", "auto_fix", "max_output_length",
+                   "sandbox_image", "sandbox_network", "sandbox_memory"):
+            if k in data:
+                exe[k] = data[k]
+        cfg_path.write_text(json.dumps(cfg_data, indent=2, ensure_ascii=False))
+        # 热更新内存配置
+        update_keys = {k: v for k, v in data.items() if hasattr(self.core.config_mgr.config.executor, k)}
+        self.core.config_mgr.update_executor(**update_keys)
+        # 实时切换执行引擎
+        if self.core.executor and "execution_mode" in data:
+            mode = data["execution_mode"]
+            ok = self.core.executor.set_execution_mode(mode)
+            if "sandbox_image" in data:
+                self.core.executor.sandbox_image = data["sandbox_image"]
+            if "sandbox_network" in data:
+                self.core.executor.sandbox_network = data["sandbox_network"]
+            if "sandbox_memory" in data:
+                self.core.executor.sandbox_memory = data["sandbox_memory"]
+            if not ok:
+                return web.json_response({"ok": False, "error": f"切换到 {mode} 失败(Docker 不可用)"})
+        logger.info(f"执行引擎配置已热更新: mode={data.get('execution_mode')}")
+        return web.json_response({"ok": True, "hot_reload": True})
+
+    # --- Agent Bindings ---
+    async def handle_agent_bindings(self, request):
+        """GET /api/agents/{name}/bindings - 获取 Agent 的聊天平台绑定"""
+        path = request.match_info["name"]
+        cfg = self._read_agent_config(path)
+        if not cfg:
+            return web.json_response({"error": "not found"}, status=404)
+        bindings = {}
+        if cfg.get("platform"):
+            bindings["platform"] = cfg["platform"]
+        if cfg.get("platform_token"):
+            bindings["platform_token"] = cfg["platform_token"]
+        if cfg.get("platform_app_id"):
+            bindings["platform_app_id"] = cfg["platform_app_id"]
+        if cfg.get("platform_app_secret"):
+            bindings["platform_app_secret"] = cfg["platform_app_secret"]
+        # 模型绑定（含备用模型）
+        if cfg.get("model_id"):
+            model_info = None
+            for me in self.core.config.models_library:
+                if me.id == cfg["model_id"]:
+                    model_info = {"id": me.id, "name": me.name, "provider": me.provider,
+                                 "model": me.model, "base_url": me.base_url, "enabled": me.enabled}
+                    break
+            if model_info:
+                bindings["model"] = model_info
+            else:
+                bindings["model_id"] = cfg["model_id"]
+                bindings["model"] = None
+        elif cfg.get("model"):
+            bindings["model"] = {"model": cfg["model"]}
+
+        # 备用模型列表
+        backup_ids = cfg.get("backup_model_ids", [])
+        if backup_ids:
+            backup_models = []
+            for bid in backup_ids:
+                for me in self.core.config.models_library:
+                    if me.id == bid:
+                        backup_models.append({
+                            "id": me.id, "name": me.name, "provider": me.provider,
+                            "model": me.model, "base_url": me.base_url, "enabled": me.enabled
+                        })
+                        break
+                else:
+                    backup_models.append({"id": bid, "name": bid, "not_found": True})
+            bindings["backup_models"] = backup_models
+        else:
+            bindings["backup_models"] = []
+
+        return web.json_response(bindings)
+
+    # --- Platforms ---
+    async def handle_list_platforms(self, request):
+        platforms = []
+        for pname in ["telegram", "discord", "feishu", "qq", "wechat"]:
+            pcfg = getattr(self.core.config, pname, None)
+            platforms.append({"name": pname, "enabled": bool(pcfg and (pcfg.token or pcfg.app_id))})
+        return web.json_response(platforms)
+
+    async def handle_update_platform(self, request):
+        name = request.match_info["name"]; data = await request.json()
+        cfg_path = self.core.config_mgr._config_file
+        cfg_data = json.loads(cfg_path.read_text()) if cfg_path.exists() else {}
+        cfg_data.setdefault("platforms", {})[name] = data
+        cfg_path.write_text(json.dumps(cfg_data, indent=2, ensure_ascii=False))
+        return web.json_response({"ok": True})
+
+    # --- Sessions ---
+    async def handle_list_sessions(self, request):
+        if not self.core.memory: return web.json_response([])
+        agent = request.query.get("agent", "")
+        if agent:
+            prefix = f"{agent}_"
+            rows = self.core.memory._get_conn().execute(
+                "SELECT DISTINCT session_id, COUNT(*) as cnt, MAX(created_at) as last FROM memories "
+                "WHERE category='short_term' AND session_id LIKE ? GROUP BY session_id ORDER BY last DESC LIMIT 100",
+                (prefix + "%",)).fetchall()
+        else:
+            rows = self.core.memory._get_conn().execute(
+                "SELECT DISTINCT session_id, COUNT(*) as cnt, MAX(created_at) as last FROM memories "
+                "WHERE category='short_term' GROUP BY session_id ORDER BY last DESC LIMIT 100").fetchall()
+        return web.json_response([{"id": r["session_id"], "messages": r["cnt"], "last": r["last"]} for r in rows])
+
+    async def handle_agent_sessions(self, request):
+        """GET /api/agents/{name}/sessions - Convenience endpoint for agent-scoped sessions."""
+        name = request.match_info["name"]
+        if not self.core.memory:
+            return web.json_response({"agent": name, "sessions": []})
+        prefix = f"{name}_"
+        rows = self.core.memory._get_conn().execute(
+            "SELECT DISTINCT session_id, COUNT(*) as cnt, MAX(created_at) as last FROM memories "
+            "WHERE category='short_term' AND session_id LIKE ? GROUP BY session_id ORDER BY last DESC LIMIT 100",
+            (prefix + "%",)).fetchall()
+        sessions = [{"id": r["session_id"], "messages": r["cnt"], "last": r["last"]} for r in rows]
+        # Agent info
+        ad = self._agent_dir(name)
+        agent_info = {"name": name, "avatar_color": _agent_color(name)}
+        if (ad / "config.json").exists():
+            agent_info.update(json.loads((ad / "config.json").read_text()))
+        return web.json_response({**agent_info, "sessions": sessions})
+
+    async def handle_get_messages(self, request):
+        sid = request.match_info["sid"]
+        if not self.core.memory: return web.json_response([])
+        entries = self.core.memory.get_conversation(sid, limit=100)
+        return web.json_response([{"role": e.role, "content": e.content[:500], "time": e.created_at} for e in entries])
+
+    async def handle_clear_session(self, request):
+        if self.core.memory: self.core.memory.clear_conversation(request.match_info["sid"])
+        return web.json_response({"ok": True})
+
+    # --- Memory ---
+    async def handle_memory_stats(self, request):
+        return web.json_response(self.core.memory.get_stats() if self.core.memory else {})
+
+    async def handle_memory_search(self, request):
+        q = request.query.get("q", ""); cat = request.query.get("category", "")
+        if not self.core.memory: return web.json_response([])
+        results = self.core.memory.search(q, category=cat, limit=20)
+        return web.json_response([{"id": e.id, "key": e.key, "content": e.content[:300],
+            "category": e.category, "importance": e.importance} for e in results])
+
+    async def handle_list_long_term(self, request):
+        if not self.core.memory: return web.json_response([])
+        entries = self.core.memory.get_long_term(limit=50)
+        return web.json_response([{"id": e.id, "key": e.key, "content": e.content[:300],
+            "summary": e.summary, "importance": e.importance} for e in entries])
+
+    async def handle_delete_long_term(self, request):
+        if self.core.memory:
+            self.core.memory._get_conn().execute("DELETE FROM memories WHERE id=?", (request.match_info["mid"],))
+            self.core.memory._get_conn().commit()
+        return web.json_response({"ok": True})
+
+    async def handle_memory_cleanup(self, request):
+        return web.json_response({"cleaned": self.core.memory.cleanup_expired() if self.core.memory else 0})
+
+    # --- LLM ---
+    async def handle_get_llm(self, request):
+        c = self.core.config.llm
+        return web.json_response({"provider": c.provider, "model": c.model, "base_url": c.base_url,
+            "temperature": c.temperature, "max_tokens": c.max_tokens, "timeout": c.timeout,
+            "max_retries": c.max_retries, "api_key_set": bool(c.api_key)})
+
+    async def handle_update_llm(self, request):
+        data = await request.json()
+        # 1. 写入文件
+        cfg_path = self.core.config_mgr._config_file
+        cfg_data = json.loads(cfg_path.read_text()) if cfg_path.exists() else {}
+        llm = cfg_data.setdefault("llm", {})
+        for k in ("provider", "model", "base_url", "temperature", "max_tokens", "timeout", "max_retries"):
+            if k in data: llm[k] = data[k]
+        if data.get("api_key"): llm["api_key"] = data["api_key"]
+        cfg_path.write_text(json.dumps(cfg_data, indent=2, ensure_ascii=False))
+        # 2. 热更新内存中的配置
+        update_keys = {k: v for k, v in data.items() if k != "api_key" or data.get("api_key")}
+        self.core.config_mgr.update_llm(**update_keys)
+        # 3. 实时更新 LLM 客户端
+        if self.core.llm:
+            new_cfg = self.core.config_mgr.config.llm
+            self.core.llm.provider = new_cfg.provider
+            self.core.llm.model = new_cfg.model
+            self.core.llm.base_url = new_cfg.base_url
+            self.core.llm.temperature = new_cfg.temperature
+            self.core.llm.max_tokens = new_cfg.max_tokens
+            self.core.llm.timeout = new_cfg.timeout
+            self.core.llm.max_retries = new_cfg.max_retries
+            if data.get("api_key"):
+                self.core.llm.api_key = data["api_key"]
+        logger.info(f"LLM 配置已热更新: provider={data.get('provider')}, model={data.get('model')}")
+        return web.json_response({"ok": True, "hot_reload": True})
+
+    async def handle_test_llm(self, request):
+        try:
+            msg = await self.core.llm.chat([Message(role="user", content="Hi, reply OK")])
+            return web.json_response({"ok": True, "response": msg.content[:100] if msg.content else ""})
+        except Exception as e:
+            return web.json_response({"ok": False, "error": str(e)})
+
+    async def handle_llm_usage(self, request):
+        return web.json_response(self.core.llm.get_usage_stats() if self.core.llm else {})
+
+    # --- Models Library ---
+    async def handle_list_models(self, request):
+        """GET /api/models - 列出模型库中所有模型"""
+        models = []
+        for m in self.core.config.models_library:
+            models.append({
+                "id": m.id, "name": m.name, "provider": m.provider,
+                "model": m.model, "base_url": m.base_url,
+                "max_tokens": m.max_tokens, "temperature": m.temperature,
+                "enabled": m.enabled,
+                "has_api_key": bool(m.api_key),
+            })
+        return web.json_response(models)
+
+    async def handle_add_model(self, request):
+        """POST /api/models - 添加模型到库"""
+        data = await request.json()
+        model_id = data.get("id", "").strip()
+        if not model_id:
+            return web.json_response({"error": "模型 ID 不能为空"}, status=400)
+        # 检查重复
+        for m in self.core.config.models_library:
+            if m.id == model_id:
+                return web.json_response({"error": f"模型 '{model_id}' 已存在"}, status=409)
+        entry = ModelEntry(
+            id=model_id,
+            name=data.get("name", model_id),
+            provider=data.get("provider", "openai"),
+            model=data.get("model", model_id),
+            base_url=data.get("base_url", ""),
+            api_key=data.get("api_key", ""),
+            max_tokens=data.get("max_tokens", 4096),
+            temperature=data.get("temperature", 0.1),
+            enabled=data.get("enabled", True),
+        )
+        self.core.config.models_library.append(entry)
+        self.core.config_mgr.save()
+        logger.info(f"添加模型到库: {model_id}")
+        return web.json_response({"ok": True, "id": model_id})
+
+    async def handle_update_model(self, request):
+        """PUT /api/models/{model_id} - 更新模型配置"""
+        model_id = request.match_info["model_id"]
+        data = await request.json()
+        found = False
+        for m in self.core.config.models_library:
+            if m.id == model_id:
+                for k in ("name", "provider", "model", "base_url", "max_tokens", "temperature", "enabled"):
+                    if k in data:
+                        setattr(m, k, data[k])
+                if data.get("api_key"):
+                    m.api_key = data["api_key"]
+                found = True
+                break
+        if not found:
+            return web.json_response({"error": f"模型 '{model_id}' 未找到"}, status=404)
+        self.core.config_mgr.save()
+        logger.info(f"更新模型库: {model_id}")
+        return web.json_response({"ok": True})
+
+    async def handle_delete_model(self, request):
+        """DELETE /api/models/{model_id} - 从库中删除模型"""
+        model_id = request.match_info["model_id"]
+        original_len = len(self.core.config.models_library)
+        self.core.config.models_library = [
+            m for m in self.core.config.models_library if m.id != model_id
+        ]
+        if len(self.core.config.models_library) == original_len:
+            return web.json_response({"error": f"模型 '{model_id}' 未找到"}, status=404)
+        self.core.config_mgr.save()
+        logger.info(f"从模型库删除: {model_id}")
+        return web.json_response({"ok": True})
+
+    # --- Skills ---
+    async def handle_list_skills(self, request):
+        return web.json_response(self.core.skill_registry.list_skills_info() if self.core.skill_registry else [])
+
+    async def handle_get_skill(self, request):
+        s = self.core.skill_registry.get(request.match_info["name"]) if self.core.skill_registry else None
+        if not s: return web.json_response({"error": "not found"}, status=404)
+        return web.json_response(s.to_openclaw_format())
+
+    # --- Workdir ---
+    async def handle_get_workdir(self, request):
+        return web.json_response({"path": str(self.core.config_mgr.data_dir / "workspace")})
+
+    async def handle_set_workdir(self, request):
+        data = await request.json(); path = data.get("path", "")
+        if path: Path(path).mkdir(parents=True, exist_ok=True)
+        cfg_path = self.core.config_mgr._config_file
+        cfg_data = json.loads(cfg_path.read_text()) if cfg_path.exists() else {}
+        cfg_data["workspace"] = path
+        cfg_path.write_text(json.dumps(cfg_data, indent=2, ensure_ascii=False))
+        return web.json_response({"ok": True})
+
+    async def handle_list_workdir(self, request):
+        wd = self.core.config_mgr.data_dir / "workspace"
+        if not wd.exists(): return web.json_response([])
+        items = []
+        for f in sorted(wd.iterdir())[:200]:
+            try: items.append({"name": f.name, "type": "dir" if f.is_dir() else "file", "size": f.stat().st_size if f.is_file() else 0})
+            except: pass
+        return web.json_response(items)
+
+    # --- Logs ---
+    async def handle_get_logs(self, request):
+        log_dir = self.core.config_mgr.logs_dir
+        lines = int(request.query.get("lines", "200"))
+        level = request.query.get("level", "").upper()
+        logs = []
+        for lf in sorted(log_dir.glob("myagent*.log"), reverse=True):
+            try:
+                text = lf.read_text(encoding="utf-8", errors="ignore")
+                for line in text.strip().split("\n")[-lines:]:
+                    if level and level not in line: continue
+                    logs.append(line)
+                if len(logs) >= lines: break
+            except: pass
+        return web.json_response(logs[-lines:])
+
+    async def handle_log_stream(self, request):
+        resp = web.StreamResponse()
+        resp.content_type = "text/event-stream"
+        resp.headers["Cache-Control"] = "no-cache"
+        await resp.prepare(request)
+        log_file = self.core.config_mgr.logs_dir / "myagent.log"
+        last_pos = 0
+        try:
+            while True:
+                try:
+                    if log_file.exists():
+                        size = log_file.stat().st_size
+                        if size > last_pos:
+                            with open(log_file, "r", encoding="utf-8", errors="ignore") as f:
+                                f.seek(last_pos); new_data = f.read(); last_pos = size
+                            if new_data: await resp.write(f"data: {json.dumps(new_data.strip())}\n\n")
+                except: pass
+                await asyncio.sleep(0.5)
+        except asyncio.CancelledError: pass
+        return resp
+
+    # ── 配置管理 (热重载 / 导入 / 导出) ──
+    # ── Agent 间通信 ──
+    async def handle_get_communication(self, request):
+        """GET /api/communication - 获取通信配置"""
+        comm = self.core.config.communication
+        return web.json_response({
+            "enabled": comm.enabled,
+            "server_url": comm.server_url,
+            "agent_id": comm.agent_id,
+            "max_friends": comm.max_friends,
+            "auto_accept": comm.auto_accept,
+        })
+
+    async def handle_update_communication(self, request):
+        """PUT /api/communication - 更新通信配置"""
+        data = await request.json()
+        cfg_path = self.core.config_mgr._config_file
+        cfg_data = json.loads(cfg_path.read_text()) if cfg_path.exists() else {}
+        comm = cfg_data.setdefault("communication", {})
+        for k in ("enabled", "server_url", "max_friends", "auto_accept"):
+            if k in data:
+                comm[k] = data[k]
+        cfg_path.write_text(json.dumps(cfg_data, indent=2, ensure_ascii=False))
+        # Hot-reload in memory
+        if "enabled" in data:
+            self.core.config.communication.enabled = data["enabled"]
+        if "server_url" in data:
+            self.core.config.communication.server_url = data["server_url"]
+        if "max_friends" in data:
+            self.core.config.communication.max_friends = data["max_friends"]
+        if "auto_accept" in data:
+            self.core.config.communication.auto_accept = data["auto_accept"]
+        logger.info(f"通信配置已更新: enabled={data.get('enabled')}")
+        return web.json_response({"ok": True})
+
+    async def handle_comm_status(self, request):
+        """GET /api/communication/status - 获取通信状态"""
+        mgr = getattr(self.core, "communication_manager", None)
+        if not mgr:
+            return web.json_response({"enabled": False, "running": False})
+        return web.json_response(mgr.get_status())
+
+    async def handle_list_peers(self, request):
+        """GET /api/communication/peers - 列出所有 peers"""
+        mgr = getattr(self.core, "communication_manager", None)
+        if not mgr:
+            return web.json_response([])
+        peers = mgr.get_peer_list()
+        return web.json_response([p.to_dict() for p in peers])
+
+    async def handle_add_peer(self, request):
+        """POST /api/communication/peers - 添加 peer"""
+        mgr = getattr(self.core, "communication_manager", None)
+        if not mgr:
+            return web.json_response({"error": "communication not enabled"}, status=400)
+        data = await request.json()
+        agent_id = data.get("agent_id", "").strip()
+        public_key = data.get("public_key", "").strip()
+        display_name = data.get("display_name", "")
+        if not agent_id or not public_key:
+            return web.json_response({"error": "agent_id and public_key are required"}, status=400)
+        ok = mgr.add_peer(agent_id=agent_id, public_key=public_key, display_name=display_name)
+        if ok:
+            return web.json_response({"ok": True, "agent_id": agent_id})
+        else:
+            return web.json_response({"error": "peer already exists"}, status=409)
+
+    async def handle_remove_peer(self, request):
+        """DELETE /api/communication/peers/{agent_id} - 移除 peer"""
+        mgr = getattr(self.core, "communication_manager", None)
+        if not mgr:
+            return web.json_response({"error": "communication not enabled"}, status=400)
+        agent_id = request.match_info["agent_id"]
+        ok = mgr.remove_peer(agent_id)
+        if ok:
+            return web.json_response({"ok": True})
+        else:
+            return web.json_response({"error": "peer not found"}, status=404)
+
+    async def handle_comm_messages(self, request):
+        """GET /api/communication/messages - 获取最近消息"""
+        mgr = getattr(self.core, "communication_manager", None)
+        if not mgr:
+            return web.json_response([])
+        limit = int(request.query.get("limit", "50"))
+        from_agent = request.query.get("from_agent", "")
+        to_agent = request.query.get("to_agent", "")
+        messages = mgr.get_messages(limit=limit, from_agent=from_agent, to_agent=to_agent)
+        return web.json_response(messages)
+
+    async def handle_send_message(self, request):
+        """POST /api/communication/messages - 发送消息"""
+        mgr = getattr(self.core, "communication_manager", None)
+        if not mgr:
+            return web.json_response({"error": "communication not enabled"}, status=400)
+        data = await request.json()
+        to_agent = data.get("to_agent", "").strip()
+        content = data.get("content", "").strip()
+        msg_type = data.get("msg_type", "text")
+        if not to_agent or not content:
+            return web.json_response({"error": "to_agent and content are required"}, status=400)
+        try:
+            msg = await mgr.send_message(to_agent=to_agent, content=content, msg_type=msg_type)
+            return web.json_response({"ok": True, "message": msg.to_dict()})
+        except Exception as e:
+            logger.error(f"Send message error: {e}")
+            return web.json_response({"error": str(e)}, status=500)
+
+    async def handle_ack_message(self, request):
+        """POST /api/communication/messages/{msg_id}/ack - 确认消息"""
+        msg_id = request.match_info["msg_id"]
+        # For now, just return ok. In the future, this could update delivery status.
+        return web.json_response({"ok": True, "msg_id": msg_id})
+
+    async def handle_get_config(self, request):
+        """GET /api/config - 获取完整配置（敏感字段脱敏）"""
+        cfg = self.core.config_mgr.get_full_config()
+        return web.json_response(cfg)
+
+    def _build_model_chain(self, agent_cfg: dict | None, agent_path: str) -> list[dict]:
+        """构建模型链: [主模型, 备用模型1, 备用模型2, ...]"""
+        if not agent_cfg:
+            return []
+
+        chain = []
+        llm_defaults = self.core.config.llm
+
+        # 主模型
+        model_id = agent_cfg.get("model_id")
+        if model_id:
+            for me in self.core.config.models_library:
+                if me.id == model_id:
+                    chain.append({
+                        "id": me.id,
+                        "name": me.name,
+                        "provider": me.provider or llm_defaults.provider,
+                        "model": me.model or model_id,
+                        "base_url": me.base_url or llm_defaults.base_url,
+                        "api_key": me.api_key or llm_defaults.api_key,
+                        "temperature": me.temperature if me.temperature is not None else llm_defaults.temperature,
+                        "max_tokens": me.max_tokens if me.max_tokens else llm_defaults.max_tokens,
+                        "is_backup": False,
+                    })
+                    break
+
+        # 兼容旧的 model 字段
+        if not chain and agent_cfg.get("model"):
+            chain.append({
+                "id": "",
+                "name": agent_cfg["model"],
+                "model": agent_cfg["model"],
+                "is_backup": False,
+            })
+
+        # 备用模型列表
+        backup_ids = agent_cfg.get("backup_model_ids", [])
+        for bid in backup_ids:
+            if isinstance(bid, str) and bid.strip():
+                for me in self.core.config.models_library:
+                    if me.id == bid:
+                        chain.append({
+                            "id": me.id,
+                            "name": me.name,
+                            "provider": me.provider or llm_defaults.provider,
+                            "model": me.model or bid,
+                            "base_url": me.base_url or llm_defaults.base_url,
+                            "api_key": me.api_key or llm_defaults.api_key,
+                            "temperature": me.temperature if me.temperature is not None else llm_defaults.temperature,
+                            "max_tokens": me.max_tokens if me.max_tokens else llm_defaults.max_tokens,
+                            "is_backup": True,
+                        })
+                        break
+
+        return chain
+
+    async def _try_model_chain(self, model_chain: list[dict], message: str, session_id: str) -> str:
+        """依次尝试模型链中的模型，直到成功或全部失败"""
+        if not model_chain:
+            return await self.core.process_message(message, session_id)
+
+        llm = self.core.llm
+        last_error = ""
+        used_model_name = ""
+
+        for i, mc in enumerate(model_chain):
+            is_backup = mc.get("is_backup", False)
+            model_label = f"{'备用' if is_backup else '主'}模型 {mc.get('name', mc.get('model', '?'))}"
+            logger.info(f"尝试 {model_label} ({i+1}/{len(model_chain)}): provider={mc.get('provider')}, model={mc.get('model')}")
+
+            # 保存原始值
+            orig = {
+                "provider": llm.provider,
+                "model": llm.model,
+                "base_url": llm.base_url,
+                "api_key": llm.api_key,
+                "temperature": llm.temperature,
+                "max_tokens": llm.max_tokens,
+            }
+
+            try:
+                # 切换到当前模型
+                if "provider" in mc:
+                    llm.provider = mc["provider"]
+                if "model" in mc:
+                    llm.model = mc["model"]
+                if "base_url" in mc:
+                    llm.base_url = mc["base_url"]
+                if "api_key" in mc:
+                    llm.api_key = mc["api_key"]
+                if "temperature" in mc:
+                    llm.temperature = mc["temperature"]
+                if "max_tokens" in mc:
+                    llm.max_tokens = mc["max_tokens"]
+
+                # 强制重置客户端（切换 provider 可能需要不同的 client 实例）
+                llm._client = None
+
+                response = await self.core.process_message(message, session_id)
+
+                # 检查是否成功（如果回复包含错误标记）
+                if response and not response.startswith("⚠️ LLM 调用失败") and not response.startswith("❌"):
+                    used_model_name = model_label
+                    if is_backup:
+                        logger.warning(f"🔄 主模型失败，成功切换到 {model_label}")
+                    return response
+
+                last_error = response
+                logger.warning(f"{model_label} 返回无效响应，尝试下一个...")
+
+            except Exception as e:
+                last_error = str(e)
+                logger.warning(f"{model_label} 调用异常: {e}，尝试下一个...")
+
+            finally:
+                # 恢复原始模型配置
+                llm.provider = orig["provider"]
+                llm.model = orig["model"]
+                llm.base_url = orig["base_url"]
+                llm.api_key = orig["api_key"]
+                llm.temperature = orig["temperature"]
+                llm.max_tokens = orig["max_tokens"]
+                llm._client = None
+
+        # 所有模型都失败
+        return f"⚠️ 所有模型均调用失败 (共 {len(model_chain)} 个)。最后错误: {last_error}"
+
+    async def handle_reload_config(self, request):
+        """POST /api/config/reload - 从配置文件热重载（无需重启）
+
+        增强功能:
+        - 广播通知所有正在执行任务的 Agent 暂停
+        - 等待 Agent 安全暂停后执行配置更新
+        - 更新完成后通知 Agent 恢复执行
+        """
+        try:
+            old_provider = self.core.config_mgr.config.llm.provider
+            old_model = self.core.config_mgr.config.llm.model
+
+            # ── 广播通知：让所有活跃 Agent 暂停 ──
+            broadcaster = self.core.config_broadcaster
+            paused_count = 0
+            if broadcaster:
+                paused_count = await broadcaster.request_reload()
+                logger.info(f"热重载: 已暂停 {paused_count} 个活跃任务")
+
+            # ── 执行配置重载 ──
+            new_config = self.core.config_mgr.reload()
+            logger.info("配置已热重载")
+
+            # ── 更新运行中的组件 ──
+            changes = []
+            if self.core.llm:
+                llm_cfg = new_config.llm
+                self.core.llm.provider = llm_cfg.provider
+                self.core.llm.model = llm_cfg.model
+                self.core.llm.base_url = llm_cfg.base_url
+                self.core.llm.api_key = llm_cfg.api_key
+                self.core.llm.temperature = llm_cfg.temperature
+                self.core.llm.max_tokens = llm_cfg.max_tokens
+                self.core.llm.timeout = llm_cfg.timeout
+                self.core.llm.max_retries = llm_cfg.max_retries
+                self.core.llm.anthropic_api_key = llm_cfg.anthropic_api_key
+                # 强制重建客户端
+                self.core.llm._client = None
+                if llm_cfg.provider != old_provider or llm_cfg.model != old_model:
+                    changes.append(f"LLM: {old_provider}/{old_model} -> {llm_cfg.provider}/{llm_cfg.model}")
+
+                # 模型库变化
+                old_models = set(m.id for m in self.core.config.models_library)
+                new_models = set(m.id for m in new_config.models_library)
+                if old_models != new_models:
+                    added = new_models - old_models
+                    removed = old_models - new_models
+                    parts = []
+                    if added:
+                        parts.append(f"新增模型: {', '.join(added)}")
+                    if removed:
+                        parts.append(f"移除模型: {', '.join(removed)}")
+                    if parts:
+                        changes.append("模型库: " + "; ".join(parts))
+
+            if self.core.executor:
+                exe_cfg = new_config.executor
+                self.core.executor.timeout = exe_cfg.timeout
+                self.core.executor.max_retries = exe_cfg.max_retries
+                self.core.executor.auto_fix = exe_cfg.auto_fix
+                self.core.executor.max_output_length = exe_cfg.max_output_length
+                if exe_cfg.sandbox_image:
+                    self.core.executor.sandbox_image = exe_cfg.sandbox_image
+                if exe_cfg.execution_mode:
+                    self.core.executor.set_execution_mode(exe_cfg.execution_mode)
+
+            # 更新 app 引用
+            self.core.config = new_config
+
+            # ── 广播通知：让 Agent 恢复执行 ──
+            if broadcaster:
+                await broadcaster.complete_reload()
+                logger.info(f"热重载: {paused_count} 个任务已恢复")
+
+            logger.info(f"热重载完成，变更: {changes or '无显著变更'}")
+            return web.json_response({
+                "ok": True,
+                "message": "配置已热重载",
+                "changes": changes,
+                "paused_tasks": paused_count,
+                "broadcaster_stats": broadcaster.get_stats() if broadcaster else {},
+                "config": self.core.config_mgr.get_full_config(),
+            })
+        except Exception as e:
+            logger.error(f"热重载失败: {e}", exc_info=True)
+            # 确保恢复广播器状态
+            if self.core.config_broadcaster:
+                self.core.config_broadcaster.force_reset()
+            return web.json_response({"ok": False, "error": str(e)}, status=500)
+
+    async def handle_export_config(self, request):
+        """POST /api/config/export - 导出配置为 JSON 文件下载"""
+        try:
+            data = await request.json()
+        except Exception:
+            data = {}
+        include_secrets = data.get("include_secrets", False)
+
+        try:
+            export_data = self.core.config_mgr.export_config(include_secrets=include_secrets)
+            filename = f"myagent_config_{datetime.datetime.now().strftime('%Y%m%d_%H%M%S')}.json"
+
+            resp = web.Response(
+                body=json.dumps(export_data, ensure_ascii=False, indent=2),
+                content_type="application/json",
+                headers={
+                    "Content-Disposition": f"attachment; filename=\"{filename}\"",
+                },
+            )
+            logger.info(f"配置已导出: {filename} (secrets={include_secrets})")
+            return resp
+        except Exception as e:
+            logger.error(f"导出配置失败: {e}", exc_info=True)
+            return web.json_response({"ok": False, "error": str(e)}, status=500)
+
+    async def handle_import_config(self, request):
+        """POST /api/config/import - 从上传的 JSON 导入配置"""
+        try:
+            data = await request.json()
+        except Exception:
+            return web.json_response({"ok": False, "error": "无效的 JSON 数据"}, status=400)
+
+        overwrite = data.get("_overwrite", False) if isinstance(data, dict) else False
+
+        try:
+            result = self.core.config_mgr.import_config(data, overwrite=overwrite)
+            if not result["ok"]:
+                return web.json_response(result, status=400)
+
+            # 热重载运行中的组件
+            new_config = self.core.config_mgr.config
+            if self.core.llm:
+                llm_cfg = new_config.llm
+                self.core.llm.provider = llm_cfg.provider
+                self.core.llm.model = llm_cfg.model
+                self.core.llm.base_url = llm_cfg.base_url
+                self.core.llm.api_key = llm_cfg.api_key
+                self.core.llm.temperature = llm_cfg.temperature
+                self.core.llm.max_tokens = llm_cfg.max_tokens
+                self.core.llm.timeout = llm_cfg.timeout
+                self.core.llm.max_retries = llm_cfg.max_retries
+            self.core.config = new_config
+
+            logger.info(f"配置已导入: {result['message']}")
+            return web.json_response(result)
+        except Exception as e:
+            logger.error(f"导入配置失败: {e}", exc_info=True)
+            return web.json_response({"ok": False, "error": str(e)}, status=500)
+
+    # ── 组织管理 ──
+
+    def _get_org_manager(self):
+        """获取组织管理器实例（懒加载）"""
+        if not hasattr(self, '_org_manager'):
+            from organization.manager import OrganizationManager
+            self._org_manager = OrganizationManager(
+                data_dir=self.core.config_mgr.data_dir
+            )
+            self._org_manager.initialize()
+        return self._org_manager
+
+    def _get_org_rag(self):
+        """获取组织知识库 RAG 实例（懒加载）"""
+        if not hasattr(self, '_org_rag'):
+            from knowledge.rag import KnowledgeRAG
+            org_mgr = self._get_org_manager()
+            self._org_rag = KnowledgeRAG(
+                kb_dir=org_mgr._knowledge_dir
+            )
+            self._org_rag.build_index()
+        return self._org_rag
+
+    def _get_agent_knowledge_dir(self, agent_path: str) -> Path:
+        """获取 Agent 的知识库目录"""
+        return self._agent_dir(agent_path) / "knowledge"
+
+    def _get_agent_rag(self, agent_path: str):
+        """获取 Agent 知识库 RAG 实例"""
+        if not hasattr(self, '_agent_rags'):
+            self._agent_rags = {}
+        if agent_path not in self._agent_rags:
+            from knowledge.rag import KnowledgeRAG
+            kb_dir = self._get_agent_knowledge_dir(agent_path)
+            kb_dir.mkdir(parents=True, exist_ok=True)
+            rag = KnowledgeRAG(kb_dir=kb_dir)
+            rag.build_index()
+            self._agent_rags[agent_path] = rag
+        return self._agent_rags[agent_path]
+
+    def _check_org_admin(self, agent_path: str = "") -> bool:
+        """检查 agent 是否是组织知识库管理员"""
+        org_cfg = self.core.config.organization
+        admin = org_cfg.knowledge_admin or "default"
+        return agent_path == admin
+
+    async def handle_get_organization(self, request):
+        """GET /api/organization - 获取组织配置和组织信息"""
+        org_cfg = self.core.config.organization
+        org_mgr = self._get_org_manager()
+        org_info = org_mgr.get_org_info()
+        return web.json_response({
+            "enabled": org_cfg.enabled,
+            "knowledge_admin": org_cfg.knowledge_admin,
+            "info": org_info,
+        })
+
+    async def handle_update_organization(self, request):
+        """PUT /api/organization - 更新组织配置"""
+        data = await request.json()
+        cfg_path = self.core.config_mgr._config_file
+        cfg_data = json.loads(cfg_path.read_text()) if cfg_path.exists() else {}
+        org = cfg_data.setdefault("organization", {})
+        if "enabled" in data:
+            org["enabled"] = bool(data["enabled"])
+        if "knowledge_admin" in data:
+            org["knowledge_admin"] = str(data["knowledge_admin"])
+        cfg_path.write_text(json.dumps(cfg_data, indent=2, ensure_ascii=False))
+        # 热更新内存配置
+        self.core.config.organization.enabled = org.get("enabled", False)
+        self.core.config.organization.knowledge_admin = org.get("knowledge_admin", "")
+        logger.info(f"组织配置已更新: enabled={org.get('enabled')}, admin={org.get('knowledge_admin')}")
+        return web.json_response({"ok": True})
+
+    async def handle_get_org_info(self, request):
+        """GET /api/organization/info - 获取组织信息"""
+        org_mgr = self._get_org_manager()
+        content = org_mgr.get_org_info()
+        return web.json_response({"content": content})
+
+    async def handle_update_org_info(self, request):
+        """PUT /api/organization/info - 更新组织信息"""
+        data = await request.json()
+        content = data.get("content", "")
+        org_mgr = self._get_org_manager()
+        ok = org_mgr.update_org_info(content)
+        if ok:
+            return web.json_response({"ok": True})
+        return web.json_response({"ok": False, "error": "更新失败"}, status=500)
+
+    async def handle_list_org_knowledge(self, request):
+        """GET /api/organization/knowledge - 列出组织知识库文件"""
+        org_mgr = self._get_org_manager()
+        files = org_mgr.list_knowledge_files()
+        return web.json_response(files)
+
+    async def handle_upload_org_knowledge(self, request):
+        """POST /api/organization/knowledge/upload - 上传文件到组织知识库"""
+        # 权限检查
+        agent = request.query.get("agent", "default")
+        if not self._check_org_admin(agent):
+            return web.json_response(
+                {"ok": False, "error": "权限不足：只有知识库管理员才能上传"},
+                status=403,
+            )
+
+        data = await request.json()
+        # 支持单个文件或批量文件
+        files = data.get("files", [])
+        if not files:
+            # 兼容单文件格式
+            filename = data.get("filename", data.get("name", ""))
+            content = data.get("content", "")
+            if not filename or content is None:
+                return web.json_response({"ok": False, "error": "缺少 filename 或 content"}, status=400)
+            files = [{"name": filename, "content": content}]
+
+        org_mgr = self._get_org_manager()
+        results = []
+        for f in files:
+            name = f.get("name", "")
+            content = f.get("content", "")
+            result = org_mgr.upload_file(name, content, uploaded_by=agent)
+            results.append(result)
+
+        # 刷新 RAG 索引
+        if hasattr(self, '_org_rag'):
+            self._org_rag.build_index()
+
+        return web.json_response({"ok": True, "results": results})
+
+    async def handle_delete_org_knowledge(self, request):
+        """DELETE /api/organization/knowledge?path=xxx - 删除组织知识库文件"""
+        # 权限检查
+        agent = request.query.get("agent", "default")
+        if not self._check_org_admin(agent):
+            return web.json_response(
+                {"ok": False, "error": "权限不足：只有知识库管理员才能删除"},
+                status=403,
+            )
+
+        file_path = request.query.get("path", "").strip()
+        if not file_path:
+            return web.json_response({"ok": False, "error": "缺少 path 参数"}, status=400)
+
+        org_mgr = self._get_org_manager()
+        result = org_mgr.delete_file(file_path)
+
+        # 刷新 RAG 索引
+        if result.get("ok") and hasattr(self, '_org_rag'):
+            self._org_rag.build_index()
+
+        return web.json_response(result)
+
+    # ── Agent 知识库 ──
+
+    async def handle_list_agent_knowledge(self, request):
+        """GET /api/agents/{name}/knowledge - 列出 Agent 个人知识库文件"""
+        agent_path = request.match_info["name"]
+        kb_dir = self._get_agent_knowledge_dir(agent_path)
+        if not kb_dir.exists():
+            return web.json_response([])
+        files = []
+        for item in sorted(kb_dir.iterdir()):
+            if item.is_file():
+                try:
+                    stat = item.stat()
+                    files.append({
+                        "name": item.name,
+                        "path": item.name,
+                        "type": "file",
+                        "size": stat.st_size,
+                    })
+                except OSError:
+                    pass
+            elif item.is_dir():
+                sub_files = [f for f in item.iterdir() if f.is_file()]
+                files.append({
+                    "name": item.name,
+                    "path": item.name,
+                    "type": "dir",
+                    "size": 0,
+                    "file_count": len(sub_files),
+                })
+        return web.json_response(files)
+
+    async def handle_upload_agent_knowledge(self, request):
+        """POST /api/agents/{name}/knowledge/upload - 上传到 Agent 知识库"""
+        agent_path = request.match_info["name"]
+        data = await request.json()
+        files = data.get("files", [])
+        if not files:
+            filename = data.get("filename", data.get("name", ""))
+            content = data.get("content", "")
+            if not filename or content is None:
+                return web.json_response({"ok": False, "error": "缺少 filename 或 content"}, status=400)
+            files = [{"name": filename, "content": content}]
+
+        kb_dir = self._get_agent_knowledge_dir(agent_path)
+        kb_dir.mkdir(parents=True, exist_ok=True)
+        results = []
+        for f in files:
+            name = f.get("name", "")
+            content = f.get("content", "")
+            # 安全校验
+            safe_name = Path(name).name
+            if ".." in name or name.startswith("/"):
+                results.append({"ok": False, "message": "非法文件名"})
+                continue
+            if "/" in name:
+                parts = name.split("/")
+                parent = kb_dir / "/".join(parts[:-1])
+                parent.mkdir(parents=True, exist_ok=True)
+                target = parent / parts[-1]
+            else:
+                target = kb_dir / safe_name
+            try:
+                target.write_text(content, encoding="utf-8")
+                results.append({"ok": True, "path": name})
+            except Exception as e:
+                results.append({"ok": False, "message": str(e)})
+
+        # 刷新 RAG 索引
+        if hasattr(self, '_agent_rags') and agent_path in self._agent_rags:
+            self._agent_rags[agent_path].build_index()
+
+        return web.json_response({"ok": True, "results": results})
+
+    async def handle_delete_agent_knowledge(self, request):
+        """DELETE /api/agents/{name}/knowledge?path=xxx - 删除 Agent 知识库文件"""
+        agent_path = request.match_info["name"]
+        file_path = request.query.get("path", "").strip()
+        if not file_path:
+            return web.json_response({"ok": False, "error": "缺少 path 参数"}, status=400)
+
+        kb_dir = self._get_agent_knowledge_dir(agent_path)
+        target = kb_dir / file_path
+
+        if ".." in file_path or file_path.startswith("/"):
+            return web.json_response({"ok": False, "error": "非法路径"}, status=400)
+
+        if not target.exists():
+            return web.json_response({"ok": False, "error": "文件不存在"}, status=404)
+
+        try:
+            if target.is_dir():
+                shutil.rmtree(target)
+            else:
+                target.unlink()
+        except Exception as e:
+            return web.json_response({"ok": False, "message": str(e)})
+
+        # 刷新 RAG 索引
+        if hasattr(self, '_agent_rags') and agent_path in self._agent_rags:
+            self._agent_rags[agent_path].build_index()
+
+        return web.json_response({"ok": True, "message": "已删除"})
+
+    # ── 知识库 RAG 搜索 ──
+
+    async def handle_knowledge_search(self, request):
+        """POST /api/knowledge/search - RAG 知识搜索
+
+        请求体:
+        {
+            "query": "搜索关键词",
+            "scope": "org",           # "org" 或 "agent:{path}"
+            "top_k": 5
+        }
+        """
+        data = await request.json()
+        query = data.get("query", "").strip()
+        if not query:
+            return web.json_response({"error": "query 不能为空"}, status=400)
+
+        scope = data.get("scope", "org")
+        top_k = int(data.get("top_k", 5))
+
+        try:
+            if scope.startswith("agent:"):
+                agent_path = scope[6:]
+                rag = self._get_agent_rag(agent_path)
+            else:
+                rag = self._get_org_rag()
+
+            results = rag.search(query, top_k=top_k)
+            return web.json_response({
+                "query": query,
+                "scope": scope,
+                "total_chunks": rag.total_chunks,
+                "results": [r.to_dict() for r in results],
+            })
+        except Exception as e:
+            logger.error(f"知识库搜索失败: {e}", exc_info=True)
+            return web.json_response({"error": str(e)}, status=500)
+
+    # ── 群聊管理 ──
+    async def handle_list_groups(self, request):
+        """GET /api/groups - 列出所有群"""
+        mgr = self._get_group_manager()
+        groups = [g.to_dict() for g in mgr.list_groups()]
+        return web.json_response(groups)
+
+    async def handle_create_group(self, request):
+        """POST /api/groups - 创建群"""
+        data = await request.json()
+        name = data.get("name", "").strip()
+        if not name:
+            return web.json_response({"error": "群名不能为空"}, status=400)
+        owner = data.get("owner", "default")
+        description = data.get("description", "")
+        avatar_emoji = data.get("avatar_emoji", "👥")
+        avatar_color = data.get("avatar_color", "")
+        member_paths = data.get("members", [])
+        mgr = self._get_group_manager()
+        group = mgr.create_group(
+            name=name, owner=owner, description=description,
+            avatar_emoji=avatar_emoji, avatar_color=avatar_color,
+            member_paths=member_paths,
+        )
+        return web.json_response({"ok": True, "group": group.to_dict()})
+
+    async def handle_get_group(self, request):
+        """GET /api/groups/{gid} - 获取群详情"""
+        gid = request.match_info["gid"]
+        mgr = self._get_group_manager()
+        group = mgr.get_group(gid)
+        if not group:
+            return web.json_response({"error": "群不存在"}, status=404)
+        return web.json_response(group.to_dict())
+
+    async def handle_update_group(self, request):
+        """PUT /api/groups/{gid} - 更新群信息"""
+        gid = request.match_info["gid"]
+        data = await request.json()
+        mgr = self._get_group_manager()
+        group = mgr.update_group(
+            gid,
+            name=data.get("name", ""),
+            description=data.get("description", ""),
+            avatar_emoji=data.get("avatar_emoji", ""),
+            avatar_color=data.get("avatar_color", ""),
+        )
+        if not group:
+            return web.json_response({"error": "群不存在"}, status=404)
+        return web.json_response({"ok": True, "group": group.to_dict()})
+
+    async def handle_delete_group(self, request):
+        """DELETE /api/groups/{gid} - 解散群"""
+        gid = request.match_info["gid"]
+        data = {}
+        try:
+            data = await request.json()
+        except Exception:
+            pass
+        operator = data.get("operator", "")
+        mgr = self._get_group_manager()
+        ok = mgr.delete_group(gid, operator=operator)
+        if not ok:
+            return web.json_response({"error": "解散失败（群不存在或权限不足）"}, status=400)
+        return web.json_response({"ok": True})
+
+    async def handle_group_stats(self, request):
+        """GET /api/groups/{gid}/stats - 获取群统计"""
+        gid = request.match_info["gid"]
+        mgr = self._get_group_manager()
+        stats = mgr.get_group_stats(gid)
+        if not stats:
+            return web.json_response({"error": "群不存在"}, status=404)
+        return web.json_response(stats)
+
+    # ── 群成员管理 ──
+    async def handle_add_member(self, request):
+        """POST /api/groups/{gid}/members - 添加成员"""
+        gid = request.match_info["gid"]
+        data = await request.json()
+        agent_path = data.get("agent_path", "").strip()
+        if not agent_path:
+            return web.json_response({"error": "agent_path 不能为空"}, status=400)
+        role = data.get("role", "member")
+        nickname = data.get("nickname", "")
+        operator = data.get("operator", "")
+        mgr = self._get_group_manager()
+        group = mgr.add_member(gid, agent_path, role=role, nickname=nickname, operator=operator)
+        if not group:
+            return web.json_response({"error": "添加失败（群不存在、已存在或权限不足）"}, status=400)
+        return web.json_response({"ok": True, "group": group.to_dict()})
+
+    async def handle_remove_member(self, request):
+        """DELETE /api/groups/{gid}/members/{agent_path} - 移除成员"""
+        gid = request.match_info["gid"]
+        agent_path = request.match_info["agent_path"]
+        data = {}
+        try:
+            data = await request.json()
+        except Exception:
+            pass
+        operator = data.get("operator", "")
+        mgr = self._get_group_manager()
+        group = mgr.remove_member(gid, agent_path, operator=operator)
+        if not group:
+            return web.json_response({"error": "移除失败"}, status=400)
+        return web.json_response({"ok": True, "group": group.to_dict()})
+
+    async def handle_set_member_role(self, request):
+        """PUT /api/groups/{gid}/members/{agent_path}/role - 设置成员角色"""
+        gid = request.match_info["gid"]
+        agent_path = request.match_info["agent_path"]
+        data = await request.json()
+        role = data.get("role", "member")
+        operator = data.get("operator", "")
+        mgr = self._get_group_manager()
+        group = mgr.set_member_role(gid, agent_path, role=role, operator=operator)
+        if not group:
+            return web.json_response({"error": "设置失败（群不存在、无权限或目标不存在）"}, status=400)
+        return web.json_response({"ok": True, "group": group.to_dict()})
+
+    async def handle_set_member_muted(self, request):
+        """PUT /api/groups/{gid}/members/{agent_path}/mute - 设置禁言"""
+        gid = request.match_info["gid"]
+        agent_path = request.match_info["agent_path"]
+        data = await request.json()
+        muted = data.get("muted", False)
+        operator = data.get("operator", "")
+        mgr = self._get_group_manager()
+        group = mgr.set_member_muted(gid, agent_path, muted=muted, operator=operator)
+        if not group:
+            return web.json_response({"error": "设置失败"}, status=400)
+        return web.json_response({"ok": True, "group": group.to_dict()})
+
+    # ── 群消息 ──
+    async def handle_get_group_messages(self, request):
+        """GET /api/groups/{gid}/messages - 获取群消息"""
+        gid = request.match_info["gid"]
+        mgr = self._get_group_manager()
+        limit = int(request.query.get("limit", "100"))
+        before = float(request.query.get("before", "0"))
+        messages = mgr.get_messages(gid, limit=limit, before=before)
+        return web.json_response([m.to_dict() for m in messages])
+
+    async def handle_send_group_message(self, request):
+        """POST /api/groups/{gid}/messages - 发送群消息（广播到所有成员agent）"""
+        gid = request.match_info["gid"]
+        data = await request.json()
+        content = data.get("message", "").strip()
+        if not content:
+            return web.json_response({"error": "消息不能为空"}, status=400)
+
+        mgr = self._get_group_manager()
+        group = mgr.get_group(gid)
+        if not group:
+            return web.json_response({"error": "群不存在"}, status=404)
+
+        # 1. 保存用户消息
+        from groups.manager import GroupMessage
+        user_msg = GroupMessage(
+            group_id=gid,
+            sender="user",
+            sender_name="用户",
+            sender_avatar="👤",
+            content=content,
+        )
+        mgr.add_message(user_msg)
+
+        # 2. 广播到所有非禁言成员agent，并行处理
+        responses = []
+        active_members = [m for m in group.members if not m.muted]
+
+        import asyncio
+        async def process_agent_member(member):
+            try:
+                agent_path = member.agent_path
+                agent_cfg = self._read_agent_config(agent_path)
+                model_chain = self._build_model_chain(agent_cfg, agent_path)
+                session_id = f"group_{gid}_{agent_path}"
+
+                if model_chain and self.core.llm:
+                    response = await self._try_model_chain(model_chain, content, session_id)
+                else:
+                    response = await self.core.process_message(content, session_id)
+
+                # 获取agent的显示信息
+                avatar = "🤖"
+                display_name = agent_path
+                if agent_cfg:
+                    avatar = agent_cfg.get("avatar_emoji", "🤖") or "🤖"
+                    display_name = agent_cfg.get("name", agent_path)
+
+                # 保存agent回复到群消息
+                agent_msg = GroupMessage(
+                    group_id=gid,
+                    sender="agent",
+                    sender_name=display_name,
+                    sender_avatar=avatar,
+                    content=response,
+                    agent_path=agent_path,
+                )
+                mgr.add_message(agent_msg)
+
+                return {
+                    "ok": True,
+                    "agent_path": agent_path,
+                    "name": display_name,
+                    "avatar": avatar,
+                    "response": response,
+                }
+            except Exception as e:
+                logger.error(f"群消息处理失败 ({member.agent_path}): {e}")
+                return {
+                    "ok": False,
+                    "agent_path": member.agent_path,
+                    "name": member.agent_path,
+                    "avatar": "❌",
+                    "response": f"处理失败: {str(e)}",
+                }
+
+        # 并行调用所有成员agent
+        tasks = [process_agent_member(m) for m in active_members]
+        responses = await asyncio.gather(*tasks, return_exceptions=True)
+
+        # 处理异常结果
+        final_responses = []
+        for r in responses:
+            if isinstance(r, Exception):
+                final_responses.append({
+                    "ok": False, "agent_path": "unknown",
+                    "name": "unknown", "avatar": "❌",
+                    "response": f"异常: {str(r)}",
+                })
+            else:
+                final_responses.append(r)
+
+        return web.json_response({
+            "ok": True,
+            "group_id": gid,
+            "user_message": user_msg.to_dict(),
+            "responses": final_responses,
+        })
+
+    async def handle_clear_group_messages(self, request):
+        """DELETE /api/groups/{gid}/messages - 清空群消息"""
+        gid = request.match_info["gid"]
+        mgr = self._get_group_manager()
+        ok = mgr.clear_messages(gid)
+        return web.json_response({"ok": ok})
+
+    async def start(self, port: int = 8765):
+        self._runner = web.AppRunner(self.app)
+        await self._runner.setup()
+        site = web.TCPSite(self._runner, "127.0.0.1", port)
+        await site.start()
+        logger.info(f"管理后台: http://127.0.0.1:{port}/ui/")
+
+    async def stop(self):
+        if self._runner: await self._runner.cleanup()