From b60b96225d55ae1ade40f4a4405ac5bad405b1e5 Mon Sep 17 00:00:00 2001 From: iven Date: Fri, 24 Apr 2026 08:54:48 +0800 Subject: [PATCH] =?UTF-8?q?docs(wiki):=20Hermes=20Phase=201-4=20wiki=20?= =?UTF-8?q?=E5=90=8C=E6=AD=A5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - hands-skills: 新增 concurrency() 声明要求不变量 - log: 追加 Hermes Phase 1-4 变更记录 - index: 更新日期 --- wiki/hands-skills.md | 13 +++++++++++++ wiki/index.md | 26 ++++++++++++++------------ wiki/log.md | 9 +++++++++ 3 files changed, 36 insertions(+), 12 deletions(-) diff --git a/wiki/hands-skills.md b/wiki/hands-skills.md index 134de62..8d945b3 100644 --- a/wiki/hands-skills.md +++ b/wiki/hands-skills.md @@ -133,6 +133,18 @@ skills/ -> SkillRegistry 加载 -> SkillIndexMiddleware@200 注入系统提示 - MCP 限定名 `service_name.tool_name` 避免与内置工具冲突 - 已删除空壳 Hands (04-17): Whiteboard/Slideshow/Speech，净减 ~5400 行 +### ⚡ 新增工具/技能必须声明 concurrency 级别 + +`Tool` trait 的 `concurrency()` 方法决定并行执行策略 (04-24 Hermes Phase 2A): + +| 级别 | 含义 | 适用场景 | +|------|------|---------| +| `ReadOnly` (默认) | 只读，始终可并行 | file_read, web_search, calculator | +| `Exclusive` | 有副作用，必须串行 | file_write, shell_exec, send_message, execute_skill, task | +| `Interactive` | 需要用户交互，永不并行 | ask_clarification | + +**新增工具时**：在 `impl Tool for YourTool` 中覆盖 `concurrency()` 方法。默认 `ReadOnly`，如果有写操作/副作用必须返回 `ToolConcurrency::Exclusive`。未正确声明会导致并行执行时产生竞态条件。 + ## 4. 活跃问题 + 陷阱 ### 活跃 @@ -155,6 +167,7 @@ skills/ -> SkillRegistry 加载 -> SkillIndexMiddleware@200 注入系统提示 | 日期 | 变更 | 关联 | |------|------|------| +| 2026-04-24 | Hermes Phase 2A: ToolConcurrency 枚举 + 并行执行 + concurrency() 声明要求 | commit 9060935 | | 2026-04-22 | Wiki 5-section 重构: 281->~195 行，语义路由细节引用 [[butler]] | wiki/ | | 2026-04-22 | Researcher 搜索修复: schema 扁平化 + 空参数回退 + 排版修复 | commit 5816f56+81005c3 | | 2026-04-17 | 空壳 Hand 清理: Whiteboard/Slideshow/Speech 删除，净减 ~5400 行 | Phase 5 清理 | diff --git a/wiki/index.md b/wiki/index.md index cb9d91a..3987465 100644 --- a/wiki/index.md +++ b/wiki/index.md @@ -1,6 +1,6 @@ --- title: ZCLAW 项目知识库 -updated: 2026-04-22 +updated: 2026-04-24 status: active --- @@ -8,29 +8,29 @@ status: active > 面向中文用户的 AI Agent 桌面客户端。管家模式 + 多模型 + 7 自主能力 + 75 技能。 > **使用方式**: 找到你要处理的模块，读对应页面，直接开始工作。 -> **数据来源**: 2026-04-22 代码全量扫描验证，非文档推测。 +> **数据来源**: 2026-04-23 代码全量扫描验证，非文档推测。 ## 项目画像 | 维度 | 值 | |------|-----| | 定位 | AI Agent 桌面客户端 (Tauri 2.x) | -| 技术栈 | Rust 10 crates + src-tauri (~102K行, 357 .rs) + React 19 + TypeScript + PostgreSQL | +| 技术栈 | Rust 10 crates + src-tauri (~148K行, 384 .rs) + React 19 + TypeScript + PostgreSQL | | 阶段 | 发布前稳定化，功能冻结中 | -## 关键数字（2026-04-22 代码验证） +## 关键数字（2026-04-23 代码验证） | 指标 | 值 | |------|-----| | Rust Crates | 10 + src-tauri | -| Rust 代码 | 101,967 行 (357 .rs文件) | -| Rust 测试 | 987 定义 / 797 通过 | -| Tauri 命令 | 190 定义 / 97 @reserved / 104 invoke | +| Rust 代码 | 148,185 行 (384 .rs文件) | +| Rust 测试 | 997 定义 (619 #[test] + 378 #[tokio::test]) | +| Tauri 命令 | 193 定义 / 104 invoke | | SaaS API | 137 .route() / 16 模块 / 38 SQL 迁移 / 42 表 | | 中间件 | 14 层 runtime + 10 层 SaaS HTTP | | SKILL / HAND | 75 技能目录 / 7 注册 Hand (6 TOML + _reminder) | | Pipeline | 18 YAML 模板 (8 目录) | -| 前端 | 25 Store / 102 组件 / 75 lib / 17 Admin 页面 | +| 前端 | 25 Store / 103 组件 / 78 lib / 17 Admin 页面 | | Intelligence | 16 .rs 文件 | | 质量指标 | 0 cargo warnings / 2 TODO/FIXME / 0 dead_code | @@ -38,13 +38,13 @@ status: active | 类别 | 功能 | 入口 | Wiki | |------|------|------|------| -| 对话 | 发消息、流式响应、多模型切换 | 聊天面板 | [[chat]] | -| 分身 | 创建/切换/配置 Agent | 侧边栏 Agent 列表 | [[chat]] | +| 对话 | 发消息、流式响应、多模型切换、LLM 动态建议 | 聊天面板 | [[chat]] | +| 分身 | 创建/切换/配置 Agent、跨会话身份记忆 (soul.md) | 侧边栏 Agent 列表 | [[chat]] | | 自主 | 触发 Browser/Collector/Twitter 等 | 自动化面板 | [[hands-skills]] | -| 记忆 | 搜索历史、自动注入上下文 | 设置 > 语义记忆 | [[memory]] | +| 记忆 | 搜索历史、自动注入上下文、身份信号提取 | 设置 > 语义记忆 | [[memory]] | | 配置 | 模型/API/工作区/安全存储 | 设置面板 (19 页) | [[development]] | | SaaS | 登录注册、订阅计费、Admin 管理 | SaaS 平台 / Admin 后台 | [[saas]] | -| 管家 | 痛点积累、行业配置、简洁/专业模式 | 聊天面板 (默认模式) | [[butler]] | +| 管家 | 痛点积累、行业配置、简洁/专业模式、跨会话身份、动态建议 | 聊天面板 (默认模式) | [[butler]] | | Pipeline | YAML 模板选择、配置、DAG 执行 | 工作流面板 | [[pipeline]] | | 安全 | JWT 认证、TOTP 2FA、操作审计 | 设置 > 安全存储 | [[security]] | | 数据 | PostgreSQL (42表) + SQLite/FTS5 (本地记忆) | — | [[data-model]] | @@ -97,5 +97,7 @@ ZCLAW | Agent 创建失败 | [[chat]] | [[saas]] | 权限或持久化问题 | | Pipeline 执行卡住 | [[pipeline]] | [[middleware]] | DAG 循环 / 依赖缺失 | | Admin 页面 403 | [[saas]] | [[security]] | JWT 过期 / admin_guard 拦截 | +| Agent 名字不记住 | [[butler]] | [[memory]] | soul.md 写入失败 / identity signal 未提取 | +| 建议不个性化 | [[chat]] | [[butler]] | 4路上下文超时 / ExperienceExtractor 未初始化 | > 数字真相源: `docs/TRUTH.md` — 如有冲突以代码实际为准 diff --git a/wiki/log.md b/wiki/log.md index a39b93a..8a6c13c 100644 --- a/wiki/log.md +++ b/wiki/log.md @@ -9,6 +9,15 @@ tags: [log, history] > Append-only 操作记录。格式: `## [日期] 类型 | 描述` +## [2026-04-24] perf | Hermes 高价值设计实施 Phase 1-4 +- **Phase 1**: Anthropic prompt caching — cache_control ephemeral + cache token tracking (CompletionResponse + StreamChunk) +- **Phase 2A**: 并行工具执行 — ToolConcurrency 枚举 (ReadOnly/Exclusive/Interactive) + JoinSet + Semaphore(3) + AtomicU32 +- **Phase 2B**: 工具输出修剪 — prune_tool_outputs() (2000→500 chars) + 集成到 CompactionMiddleware +- **Phase 3**: 错误分类+智能重试 — LlmErrorKind + ClassifiedLlmError + RetryDriver (jittered backoff) + CONTEXT_OVERFLOW recovery +- **Phase 4**: 异步压缩+迭代摘要 — 30s 防抖 + cached fallback + previous_summary 迭代累积 +- **新增文件**: error_classifier.rs, retry_driver.rs +- **验证**: 997 workspace tests PASS + ## [2026-04-23] perf | 回复效率+建议生成并行化优化 (三部分) - **perf(src-tauri)**: identity prompt 缓存 (`LazyLock>`) + `pre_conversation_hook` 并行化 (`tokio::join!`) - **perf(runtime)**: middleware `before_completion` 分波并行 — `parallel_safe()` trait + wave detection + `tokio::spawn`，5 层 safe 中间件可并行