flowchart TB
    subgraph A["① LLM 决策层"]
        P[planner 规划] --> E[executor 执行]
        E --> R[reviewer 三层质检]
        R -->|不通过| RP[repairer 修复]
        RP --> E
        R -->|通过| END([交付])
    end
    subgraph B["② MCP 协议层"]
        MC[mcp_client.py<br/>手写 JSON-RPC 2.0 over stdio]
        TA[tools_adapter.py<br/>JSON Schema → Pydantic 动态桥接]
    end
    subgraph C["③ 工具执行层"]
        OFF[officecli<br/>Office 文档操作]
        CON[mcp_servers.py<br/>通讯录查询]
    end
    subgraph D["④ 服务层"]
        API[FastAPI<br/>/batch · /tasks · /traces]
        WEB[Web 控制台 index.html]
    end
    A --> B
    B -->|stdio 子进程| C
    D --> A
    D -.-> WEB

sequenceDiagram
    participant C as MCPClient (手写)
    participant S as MCPServer (officecli / 通讯录)
    C->>S: initialize
    S-->>C: server_info + capabilities
    C->>S: notifications/initialized
    C->>S: tools/list
    S-->>C: 工具清单 (name/description/inputSchema)
    C->>S: tools/call
    S-->>C: 执行结果

mcp_servers:
  - name: my_tool          # ← 新增
    command: python
    args: ["my_server.py"]

flowchart LR
    PL[planner<br/>拆任务为步骤清单] --> EX[executor<br/>ReAct 循环执行<br/>+ 残缺 JSON 闭合补全]
    EX --> RV[reviewer 三层质检<br/>① 工具错误前置判定<br/>② 写操作痕迹程序化检查<br/>③ LLM-as-Judge 带 rubric]
    RV -->|通过| OK([END])
    RV -->|不通过| RP[repairer<br/>带错误上下文重试<br/>retry≥3 强制结束]
    RP --> EX

git clone <your-repo-url> ai-office-assistant
cd ai-office-assistant

# 1. 建环境装依赖
python -m venv venv
venv\Scripts\python.exe -m pip install -r requirements.txt   # Windows
# source venv/bin/activate && pip install -r requirements.txt  # Linux/Mac

# 2. 配 API key（Windows 设完要重开终端）
set DASHSCOPE_API_KEY=sk-xxxx        # Linux/Mac: export DASHSCOPE_API_KEY=sk-xxxx

# 3. 启动服务
venv\Scripts\python.exe -m uvicorn api:app --port 8000

curl -X POST http://localhost:8000/batch -H "Content-Type: application/json" -d ^
  "{\"xlsx_path\": \"D:\\\\绝对路径\\\\employees.xlsx\", \"task_template\": \"为{name}生成一份劳动合同，保存到 outputs/contract_{name}.docx\"}"
# → {"task_id": "xxxxxxxx"}
curl http://localhost:8000/tasks/xxxxxxxx    # 轮询进度
curl http://localhost:8000/traces/xxxxxxxx-张三   # 节点耗时时间线

docker compose up --build

mcp_servers:
  - name: my_search
    command: python              # 自动映射为当前解释器
    args: ["my_search_server.py"]  # 相对项目根解析