From a8a0751005a8d1188851f65723561aaa6987c4d4 Mon Sep 17 00:00:00 2001 From: iven Date: Wed, 15 Apr 2026 00:40:05 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20wiki=20=E4=B8=89=E7=AB=AF=E8=81=94?= =?UTF-8?q?=E8=B0=83V2=E7=BB=93=E6=9E=9C=20+=20=E8=B0=83=E8=AF=95=E7=8E=AF?= =?UTF-8?q?=E5=A2=83=E4=BF=A1=E6=81=AF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - known-issues: 新增V2联调测试（17项通过 + 3项待处理 + SSE token修复） - development: 新增完整调试环境文档（Windows/PostgreSQL/端口/账号/启动顺序） - log: 追加V2联调记录 --- wiki/development.md | 85 +++++++++++++++++++++++++++++++++++++++++++- wiki/known-issues.md | 41 ++++++++++++++++++++- wiki/log.md | 10 +++++- 3 files changed, 133 insertions(+), 3 deletions(-) diff --git a/wiki/development.md b/wiki/development.md index e31c2bd..7e26ea2 100644 --- a/wiki/development.md +++ b/wiki/development.md @@ -1,6 +1,6 @@ --- title: 开发规范 -updated: 2026-04-14 +updated: 2026-04-15 status: active tags: [development, conventions] --- @@ -106,6 +106,89 @@ pnpm start:dev 前提: Chrome 146+ + `chrome://flags/#enable-webmcp-testing` +## 调试环境（Windows） + +> 新会话联调必读。ZCLAW 在 Windows 本地开发，不使用 Docker。 + +### 环境要求 + +| 依赖 | 说明 | 验证命令 | +|------|------|----------| +| PostgreSQL 18 | Windows 服务，端口 5432 | `powershell -c "Get-Service postgresql-x64-18"` | +| Node.js + pnpm | 前端开发 | `pnpm --version` | +| Rust nightly | 后端编译 | `cargo --version` | +| Tauri CLI | 桌面端开发 | `pnpm tauri --version` | + +### 数据库 + +```bash +# 连接信息 +Host: localhost:5432 +Database: zclaw +User: postgres +Password: 123123 + +# 完整 URL +postgresql://postgres:123123@localhost:5432/zclaw +``` + +### SaaS 后端启动 + +```bash +# 设置环境变量（必须） +export ZCLAW_SAAS_DEV=true +export DB_PASSWORD=123123 +export ZCLAW_SAAS_JWT_SECRET="zclaw-dev-jwt-secret-for-testing-only-32chars" +export ZCLAW_TOTP_ENCRYPTION_KEY="0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" +export ZCLAW_ADMIN_USERNAME="admin" +export ZCLAW_ADMIN_PASSWORD="admin123" + +# 启动 +cargo run -p zclaw-saas + +# 验证（注意：health 端点是 /api/health，不是 /api/v1/health） +curl http://localhost:8080/api/health +``` + +### 默认账号 + +| 用途 | 用户名 | 密码 | 说明 | +|------|--------|------|------| +| 管理员 | admin | admin123 | super_admin 角色 | +| SaaS 管理员 | admin | admin123 | Tauri 桌面端 + Admin V2 共用 | +| Admin V2 | admin | admin123 | http://localhost:5173 | + +### 端口分配 + +| 服务 | 端口 | URL | +|------|------|-----| +| SaaS 后端 | 8080 | http://localhost:8080 | +| Admin V2 | 5173 | http://localhost:5173 | +| 桌面端 Vite | 1420 | http://localhost:1420（Tauri 内嵌） | + +### 启动顺序 + +1. 确保 PostgreSQL 运行（Windows 服务自动启动） +2. 启动 SaaS 后端：`cargo run -p zclaw-saas`（需设置环境变量） +3. 启动桌面端：`pnpm desktop` 或 `pnpm start:dev` +4. Admin V2：桌面端启动后自动可用，或单独 `cd admin-v2 && pnpm dev` + +### 调试工具 + +| 工具 | 用途 | 说明 | +|------|------|------| +| Tauri MCP | 桌面端内部状态 | `mcp__tauri-mcp__*` 系列工具 | +| Chrome DevTools MCP | Admin V2 页面调试 | `mcp__chrome-devtools__*` 系列工具 | +| WebMCP | 桌面端结构化调试 | 需 Chrome 146+，优先使用 | +| curl | SaaS API 快速验证 | 注意 admin token 通过 `/api/v1/auth/login` 获取 | + +### 注意事项 + +- **Health 端点**: `/api/health`（非 `/api/v1/health`） +- **SaaS 登录**: `POST /api/v1/auth/login`，返回 `token` 字段 +- **模型 API Key**: Provider 需在 Admin V2 模型服务页配置并启用 Key，否则聊天 404 +- **中转任务清理**: Provider Key 禁用后，已创建的中转任务会卡在 "processing" + ## Wiki 维护（收尾步骤） 完成工作后，检查 wiki/ 是否需要更新： diff --git a/wiki/known-issues.md b/wiki/known-issues.md index 1a57e3c..79d8871 100644 --- a/wiki/known-issues.md +++ b/wiki/known-issues.md @@ -1,6 +1,6 @@ --- title: 已知问题 -updated: 2026-04-14 +updated: 2026-04-15 status: active tags: [issues, bugs] --- @@ -38,6 +38,45 @@ tags: [issues, bugs] | V13-GAP-05 | Structured Data Source 无 Admin UI | ✅ Admin Knowledge 新增"结构化数据"Tab | | V13-GAP-06 | PersistentMemoryStore 遗留模块 | ✅ 全量移除 — persistent.rs 611→57 行 | +## 三端联调测试 V2 (2026-04-15) + +通过 Chrome DevTools MCP + Tauri MCP 实际界面操作验证。 + +### 已修复 + +| 问题 | 级别 | 修复 | +|------|------|------| +| SSE 中转任务 Token (入/出) 全部为 0 | P2 | ✅ SseUsageCapture 增加 stream_done 标志 + 前缀兼容 | + +### 已验证通过 + +| 功能 | 状态 | 验证方式 | +|------|------|----------| +| 桌面端登录 (SaaS 模式) | ✅ | Tauri MCP 实际登录 | +| 聊天流 (kimi-for-coding) | ✅ | 发送消息并收到流式回复 | +| 模型切换 | ✅ | 切换 deepseek → kimi | +| 智能体面板 | ✅ | 显示"默认助手" | +| 设置 20 个选项卡 | ✅ | 逐页检查：用量统计/模型/记忆/SaaS平台 | +| 语义记忆搜索 | ✅ | 100 条记忆，FTS5 + TF-IDF | +| Admin V2 仪表盘 | ✅ | Chrome DevTools: 30 账号/3 服务商/17 请求 | +| Admin V2 账号管理 | ✅ | 30 用户正常展示 | +| Admin V2 模型服务 | ✅ | DeepSeek/Kimi/zhipu 3 个 Provider | +| Admin V2 API 密钥 | ✅ | 不再崩溃（上次修复验证） | +| Admin V2 知识库 | ✅ | 6 条目 + 5 个 Tab | +| Admin V2 行业配置 | ✅ | 4 个内置行业 | +| Admin V2 计费管理 | ✅ | 团队版 570/20000 中转请求 | +| Admin V2 角色权限 | ✅ | 3 角色（超管/管理/用户） | +| Admin V2 操作日志 | ✅ | 2088 条记录 | +| Admin V2 Agent 模板 | ✅ | 10 模板（3 内置 + 7 自定义） | + +### 待处理 / 观察项 + +| 问题 | 级别 | 说明 | +|------|------|------| +| Admin 用量统计 0/0 | P2 | 用量统计页显示请求=0/Token=0，但仪表盘显示 17 请求/6304 Token。数据来源不同 | +| Deepseek 中转任务卡 processing | P3 | Provider Key 禁用后已有任务不会自动清理，需手动处理 | +| 桌面端 Token 统计为 0 | P2 | 用量统计页 Token 输入/输出=0，但图表显示 ~3.6M，数据不一致 | + ## 三端联调测试 (2026-04-14) 30+ API / 16 Admin / 8 Tauri 全量测试结果： diff --git a/wiki/log.md b/wiki/log.md index 1bbdcb7..067d767 100644 --- a/wiki/log.md +++ b/wiki/log.md @@ -1,6 +1,6 @@ --- title: 变更日志 -updated: 2026-04-14 +updated: 2026-04-15 status: active tags: [log, history] --- @@ -9,6 +9,14 @@ tags: [log, history] > Append-only 操作记录。格式: `## [日期] 类型 | 描述` +## 2026-04-15 fix | 三端联调 V2 — SSE Token 捕获修复 + 调试环境文档 + +- **fix(saas)**: SseUsageCapture 增加 `stream_done` 标志，修复 SSE 路径 Token 始终为 0 的根因 +- **fix(saas)**: `parse_sse_line` 兼容 `data:` 和 `data: ` 两种前缀 + `total_tokens` 兜底 +- **docs(wiki)**: development.md 新增完整调试环境信息（Windows 环境要求/数据库/端口/账号/启动顺序） +- **docs(wiki)**: known-issues.md 新增 V2 联调测试结果（17 项通过 + 3 项待处理） +- 验证方式: Chrome DevTools MCP + Tauri MCP 实际界面操作 + ## [2026-04-14] docs | Wiki 全量更新 — 2026-04-14 代码验证驱动 - 全部 12 个 wiki 页面基于最新代码扫描验证更新