From a41f61bcf6658160000dc037f34baeba6c152151 Mon Sep 17 00:00:00 2001 From: qihongkun Date: Fri, 22 May 2026 15:49:59 +0800 Subject: [PATCH] =?UTF-8?q?=E9=87=8D=E5=91=BD=E5=90=8D=E9=A1=B9=E7=9B=AE?= =?UTF-8?q?=E4=B8=BA=20quality-inspection-platform?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 将仓库目录从 ai_auto_test 迁至 quality-inspection-platform，统一质量检测平台命名；MCP 环境变量新增 QIP_* 并兼容 AI_TEST_*。 Co-authored-by: Cursor --- README.md | 7 ++-- app/main.py | 4 +-- app/services/loki.py | 2 +- docs/mcp_install.md | 32 +++++++++---------- docs/mcp_quickstart.md | 2 +- docs/mcp_tools_for_ai.md | 10 +++--- frontend-admin/package-lock.json | 4 +-- frontend-admin/package.json | 2 +- frontend-admin/src/auth/session.js | 4 +-- .../src/components/ProfileApiKeyPanel.vue | 2 +- mcp_bridge.py | 12 ++++--- 11 files changed, 43 insertions(+), 38 deletions(-) diff --git a/README.md b/README.md index 9083fb1..b3c1cef 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -# 质量检测平台 +# 质量检测平台（quality-inspection-platform） -一个基于 `FastAPI` 的质量检测平台，提供三类能力： +仓库目录名：`quality-inspection-platform`。一个基于 `FastAPI` 的质量检测平台，提供三类能力： - 接口定义管理 - Mock 数据管理 @@ -83,7 +83,8 @@ python3 mcp_bridge.py 桥接默认读取环境变量： -- `AI_TEST_BASE_URL`，默认值是 `http://127.0.0.1:8000` +- `QIP_BASE_URL`，默认值是 `http://127.0.0.1:8000`（兼容旧名 `AI_TEST_BASE_URL`） +- `QIP_API_KEY`：`sto-` 开头的 API Key（兼容 `AI_TEST_API_KEY`） 完整配置见： diff --git a/app/main.py b/app/main.py index 545cd85..760cfe6 100644 --- a/app/main.py +++ b/app/main.py @@ -168,7 +168,7 @@ def _make_user_out(user: User) -> CurrentUserOut: def _issue_auth_token(user: User) -> str: - secret = os.getenv("AUTH_TOKEN_SECRET", "ai-auto-test-dev-secret") + secret = os.getenv("AUTH_TOKEN_SECRET", "quality-inspection-dev-secret") nonce = secrets.token_hex(8) raw = f"{user.id}:{user.username}:{user.role}:{nonce}" signature = hmac.new(secret.encode("utf-8"), raw.encode("utf-8"), hashlib.sha256).hexdigest() @@ -176,7 +176,7 @@ def _issue_auth_token(user: User) -> str: def _resolve_user_by_token(token: str, db: Session) -> User | None: - secret = os.getenv("AUTH_TOKEN_SECRET", "ai-auto-test-dev-secret") + secret = os.getenv("AUTH_TOKEN_SECRET", "quality-inspection-dev-secret") parts = (token or "").split(":") if len(parts) != 5: return None diff --git a/app/services/loki.py b/app/services/loki.py index d8b3f29..4d38832 100644 --- a/app/services/loki.py +++ b/app/services/loki.py @@ -59,7 +59,7 @@ def _build_logql(method: str, url_path: str) -> str: base = service_label else: service_key = os.getenv("LOKI_SERVICE_LABEL", "app").strip() or "app" - service_value = os.getenv("LOKI_SERVICE_VALUE", "").strip() or "ai-auto-test" + service_value = os.getenv("LOKI_SERVICE_VALUE", "").strip() or "quality-inspection-platform" base = f'{{{service_key}="{service_value}"}}' filters: list[str] = [base] diff --git a/docs/mcp_install.md b/docs/mcp_install.md index 8e686cd..983eed1 100644 --- a/docs/mcp_install.md +++ b/docs/mcp_install.md @@ -11,7 +11,7 @@ ## 1. 启动平台后端 ```bash -cd /Users/qihongkun/work/My_app/ai_auto_test +cd /Users/qihongkun/work/My_app/quality-inspection-platform # 可选：生产/共享环境建议开启，所有 MCP 调用必须带 API Key # export MCP_REQUIRE_API_KEY=true uvicorn app.main:app --host 127.0.0.1 --port 8000 @@ -32,18 +32,18 @@ uvicorn app.main:app --host 127.0.0.1 --port 8000 "mcpServers": { "quality-inspection-platform": { "command": "python3", - "args": ["/Users/qihongkun/work/My_app/ai_auto_test/mcp_bridge.py"], + "args": ["/Users/qihongkun/work/My_app/quality-inspection-platform/mcp_bridge.py"], "env": { - "AI_TEST_BASE_URL": "http://127.0.0.1:8000", - "AI_TEST_API_KEY": "sto-你的API密钥" + "QIP_BASE_URL": "http://127.0.0.1:8000", + "QIP_API_KEY": "sto-你的API密钥" } } } } ``` -- `AI_TEST_BASE_URL`：平台后端地址。 -- `AI_TEST_API_KEY`：**必须配置**。写操作与执行类工具（`workflow_run`、`workflow_batch_run`、`ssh_script_run` 等）无 Key 将返回 401；桥接会把 Key 放到 `Authorization: Bearer` 与 invoke body 的 `api_key` 字段。 +- `QIP_BASE_URL`：平台后端地址（兼容旧环境变量 `AI_TEST_BASE_URL`）。 +- `QIP_API_KEY`：**必须配置**（兼容旧名 `AI_TEST_API_KEY`）。写操作与执行类工具（`workflow_run`、`workflow_batch_run`、`ssh_script_run` 等）无 Key 将返回 401；桥接会把 Key 放到 `Authorization: Bearer` 与 invoke body 的 `api_key` 字段。 - 后端可选 `MCP_REQUIRE_API_KEY=true`：所有 MCP 工具（含只读、`GET /mcp/tools`）均要求 Key。 在平台 Web 端右上角「个人中心」生成 `sto-` 开头的 API Key。 @@ -61,10 +61,10 @@ uvicorn app.main:app --host 127.0.0.1 --port 8000 "mcpServers": { "quality-inspection-platform": { "command": "python3", - "args": ["/Users/qihongkun/work/My_app/ai_auto_test/mcp_bridge.py"], + "args": ["/Users/qihongkun/work/My_app/quality-inspection-platform/mcp_bridge.py"], "env": { - "AI_TEST_BASE_URL": "http://127.0.0.1:8000", - "AI_TEST_API_KEY": "sto-你的API密钥" + "QIP_BASE_URL": "http://127.0.0.1:8000", + "QIP_API_KEY": "sto-你的API密钥" } } } @@ -78,9 +78,9 @@ uvicorn app.main:app --host 127.0.0.1 --port 8000 ```bash codex mcp add quality-inspection-platform \ --command python3 \ - --args /Users/qihongkun/work/My_app/ai_auto_test/mcp_bridge.py \ - --env AI_TEST_BASE_URL=http://127.0.0.1:8000 \ - --env AI_TEST_API_KEY=sto-你的API密钥 + --args /Users/qihongkun/work/My_app/quality-inspection-platform/mcp_bridge.py \ + --env QIP_BASE_URL=http://127.0.0.1:8000 \ + --env QIP_API_KEY=sto-你的API密钥 ``` 或在 `~/.codex/config.toml` 中： @@ -88,11 +88,11 @@ codex mcp add quality-inspection-platform \ ```toml [mcp.servers.quality-inspection-platform] command = "python3" -args = ["/Users/qihongkun/work/My_app/ai_auto_test/mcp_bridge.py"] +args = ["/Users/qihongkun/work/My_app/quality-inspection-platform/mcp_bridge.py"] [mcp.servers.quality-inspection-platform.env] -AI_TEST_BASE_URL = "http://127.0.0.1:8000" -AI_TEST_API_KEY = "sto-你的API密钥" +QIP_BASE_URL = "http://127.0.0.1:8000" +QIP_API_KEY = "sto-你的API密钥" ``` --- @@ -104,7 +104,7 @@ printf '%s\n' \ '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \ '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \ '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"catalog_snapshot","arguments":{}}}' \ - | AI_TEST_API_KEY=sto-你的API密钥 python3 mcp_bridge.py + | QIP_API_KEY=sto-你的API密钥 python3 mcp_bridge.py ``` 预期： diff --git a/docs/mcp_quickstart.md b/docs/mcp_quickstart.md index 599de56..1ab7ac3 100644 --- a/docs/mcp_quickstart.md +++ b/docs/mcp_quickstart.md @@ -21,7 +21,7 @@ - 工具发现：`GET /mcp/tools` - 单次调用：`POST /mcp/invoke` - 批量调用：`POST /mcp/invoke-batch` -- MCP 鉴权：在平台右上角「个人中心」生成 `sto-` 开头的 API Key，配置到 MCP Bridge 环境变量 `AI_TEST_API_KEY`，或在请求头使用 `Authorization: Bearer ` / `X-API-Key: `。 +- MCP 鉴权：在平台右上角「个人中心」生成 `sto-` 开头的 API Key，配置到 MCP Bridge 环境变量 `QIP_API_KEY`（兼容 `AI_TEST_API_KEY`），或在请求头使用 `Authorization: Bearer ` / `X-API-Key: `。 - **写操作**（创建/更新资源）与 **执行类操作**（跑工作流、批跑、单节点、SSH 执行、重放）**必须**带有效 Key，禁止无 Key 回落为 superadmin。 - 可选 **`MCP_REQUIRE_API_KEY=true`**（后端环境变量）：所有 MCP 工具（含只读）均要求 Key；`GET /mcp/tools` 同样校验。 diff --git a/docs/mcp_tools_for_ai.md b/docs/mcp_tools_for_ai.md index 490d48f..2b75894 100644 --- a/docs/mcp_tools_for_ai.md +++ b/docs/mcp_tools_for_ai.md @@ -10,7 +10,7 @@ ## 0. Agent 必读（30 秒） 1. **先** `catalog_snapshot` 了解现有 apis / workflows / workflow_batches / mocks / folders / ssh_tree，避免重复创建。 -2. **写操作与执行**必须带 `sto-` API Key（`Authorization: Bearer` 或桥接环境变量 `AI_TEST_API_KEY`）。 +2. **写操作与执行**必须带 `sto-` API Key（`Authorization: Bearer` 或桥接环境变量 `QIP_API_KEY`，兼容 `AI_TEST_API_KEY`）。 3. **接口**用 `api_upsert`；**流程**用 `workflow_upsert` 或 `workflow_patch_json`；**跑批**固定三步：`workflow_batch_create` → `workflow_batch_update` → `workflow_batch_run`。 4. **排障**：`workflow_run_get` 看 request/response → `workflow_run_loki_link` 查日志。 5. 如果当前客户端没有显示某个工具，先确认平台 `GET /mcp/tools` 是否包含该工具，再刷新或重启 MCP 客户端。 @@ -19,7 +19,7 @@ ### 0.1 工具来源与客户端刷新 - 权威工具清单来自后端 `app/main.py` 的 `MCP_TOOL_SPECS`，平台通过 `GET /mcp/tools` 对外暴露。 -- `mcp_bridge.py` 启动后会从 `AI_TEST_BASE_URL/mcp/tools` 拉取工具并转换为 MCP `tools/list`。 +- `mcp_bridge.py` 启动后会从 `QIP_BASE_URL`（或兼容 `AI_TEST_BASE_URL`）的 `/mcp/tools` 拉取工具并转换为 MCP `tools/list`。 - Codex / Cursor / Claude 等客户端可能在会话启动时缓存工具列表；平台新增工具后，通常需要重启 MCP 客户端或重启会话。 - 如果客户端只显示部分工具，不代表平台没有该能力。先用 `/mcp/tools` 或本文档核对，再决定是否降级。 - Agent 更新本文档时，应以源码和 `/mcp/tools` 为准，不以单个客户端当前暴露的工具子集为准。 @@ -48,8 +48,8 @@ MCP Bridge 通过环境变量访问平台： | 环境变量 | 含义 | 示例 | |----------|------|------| -| `AI_TEST_BASE_URL` | 质量检测平台后端地址 | `http://127.0.0.1:8000` | -| `AI_TEST_API_KEY` | `sto-` 开头的 API Key | `sto-...` | +| `QIP_BASE_URL` | 质量检测平台后端地址（兼容 `AI_TEST_BASE_URL`） | `http://127.0.0.1:8000` | +| `QIP_API_KEY` | `sto-` 开头的 API Key（兼容 `AI_TEST_API_KEY`） | `sto-...` | Agent 通过 MCP 工具访问平台，不需要在业务项目中启动平台服务；平台进程由质量检测平台项目本身或共享服务负责。 @@ -334,7 +334,7 @@ workflow_analyze_last_run → workflow_patch_json(只改变量/单节点 data) | error / 现象 | 处理 | |--------------|------| -| 401 MCP requires API Key | 配置 `AI_TEST_API_KEY` 或请求头 Bearer | +| 401 MCP requires API Key | 配置 `QIP_API_KEY`（或 `AI_TEST_API_KEY`）或请求头 Bearer | | workflow folder not registered | 先 `folder_ensure` workflows | | 仅 draft 批次可执行 | 已对 running/success 的 batch 再 run | | unknown mcp tool | `GET /mcp/tools` 刷新名称 | diff --git a/frontend-admin/package-lock.json b/frontend-admin/package-lock.json index e7259f6..809c5f4 100644 --- a/frontend-admin/package-lock.json +++ b/frontend-admin/package-lock.json @@ -1,11 +1,11 @@ { - "name": "ai-auto-test-admin", + "name": "quality-inspection-admin", "version": "0.0.1", "lockfileVersion": 3, "requires": true, "packages": { "": { - "name": "ai-auto-test-admin", + "name": "quality-inspection-admin", "version": "0.0.1", "dependencies": { "@codemirror/lang-json": "^6.0.2", diff --git a/frontend-admin/package.json b/frontend-admin/package.json index 84ed0d5..36dcdb8 100644 --- a/frontend-admin/package.json +++ b/frontend-admin/package.json @@ -1,5 +1,5 @@ { - "name": "ai-auto-test-admin", + "name": "quality-inspection-admin", "private": true, "version": "0.0.1", "type": "module", diff --git a/frontend-admin/src/auth/session.js b/frontend-admin/src/auth/session.js index 933a0da..eb2467c 100644 --- a/frontend-admin/src/auth/session.js +++ b/frontend-admin/src/auth/session.js @@ -1,7 +1,7 @@ import { reactive } from "vue"; -const TOKEN_KEY = "ai-auto-test-token"; -const USER_KEY = "ai-auto-test-user"; +const TOKEN_KEY = "quality-inspection-token"; +const USER_KEY = "quality-inspection-user"; function loadUser() { const raw = window.localStorage.getItem(USER_KEY); diff --git a/frontend-admin/src/components/ProfileApiKeyPanel.vue b/frontend-admin/src/components/ProfileApiKeyPanel.vue index 0ff2c67..3ea3991 100644 --- a/frontend-admin/src/components/ProfileApiKeyPanel.vue +++ b/frontend-admin/src/components/ProfileApiKeyPanel.vue @@ -111,7 +111,7 @@ onMounted(() => { :closable="false" show-icon title="MCP 连接说明" - description="在 Cursor / MCP 配置中设置环境变量 AI_TEST_API_KEY，或在请求头携带 Authorization: Bearer 。Key 以 sto- 开头。" + description="在 Cursor / MCP 配置中设置环境变量 QIP_API_KEY（或兼容旧名 AI_TEST_API_KEY），或在请求头携带 Authorization: Bearer 。Key 以 sto- 开头。" />
diff --git a/mcp_bridge.py b/mcp_bridge.py index b3c41fd..e72ecb2 100644 --- a/mcp_bridge.py +++ b/mcp_bridge.py @@ -24,8 +24,12 @@ from typing import Any import httpx -BASE_URL = os.environ.get("AI_TEST_BASE_URL", "http://127.0.0.1:8000").rstrip("/") -API_KEY = os.environ.get("AI_TEST_API_KEY", "").strip() +def _env(primary: str, legacy: str, default: str = "") -> str: + return (os.environ.get(primary) or os.environ.get(legacy) or default).strip() + + +BASE_URL = _env("QIP_BASE_URL", "AI_TEST_BASE_URL", "http://127.0.0.1:8000").rstrip("/") +API_KEY = _env("QIP_API_KEY", "AI_TEST_API_KEY", "") SERVER_NAME = "quality-inspection-platform" SERVER_VERSION = "0.1.0" PROTOCOL_VERSION = "2024-11-05" @@ -103,11 +107,11 @@ def handle_initialize(req_id: Any, _: dict[str, Any]) -> dict[str, Any]: "capabilities": {"tools": {"listChanged": False}}, "serverInfo": {"name": SERVER_NAME, "version": SERVER_VERSION}, "instructions": ( - "AI Auto API Test platform. Before complex tasks, read project file " + "Quality inspection platform (质量检测平台). Before complex tasks, read project file " "docs/mcp_tools_for_ai.md (tool picker, auth, recipes). " "Typical start: catalog_snapshot. " "Batch runs: workflow_batch_create → workflow_batch_update → workflow_batch_run. " - "Writes and execution require sto- API Key (AI_TEST_API_KEY)." + "Writes and execution require sto- API Key (AI_TEST_API_KEY or QIP_API_KEY)." ), }, )