adfd7024df
- Restructure §8 from "文档沉淀规则" to "文档管理规则" with 4 subsections - Add docs/ structure with features/ and knowledge-base/ directories - Add feature documentation template with 7 sections (概述/设计初衷/技术设计/预期作用/实际效果/演化路线/头脑风暴) - Add feature update trigger matrix (新增/修改/完成/问题/反馈) - Add documentation quality checklist - Add §16
290 lines
9.0 KiB
Markdown
290 lines
9.0 KiB
Markdown
# ZCLAW 项目功能全景分析与头脑风暴计划
|
||
|
||
> **目标**: 对 ZCLAW 项目进行全面深度分析，记录所有功能点的设计初衷、预期作用和实际效果，最后进行头脑风暴。
|
||
|
||
---
|
||
|
||
## 一、背景与目的
|
||
|
||
### 1.1 项目现状
|
||
- 项目开发工作已基本收尾
|
||
- 317 个测试全部通过
|
||
- 四阶段 Agent 智能演化已全部完成
|
||
- 需要对项目进行系统性的梳理和记录
|
||
|
||
### 1.2 分析目标
|
||
1. **记录**: 将所有功能点一一记录，形成完整的功能档案
|
||
2. **分析**: 分析每个功能的设计初衷、预期作用、实际效果
|
||
3. **评估**: 评估功能的完成度和价值
|
||
4. **头脑风暴**: 基于分析结果进行创意探索
|
||
|
||
---
|
||
|
||
## 二、功能模块总览
|
||
|
||
### 2.1 架构层 (Architecture)
|
||
| 模块 | 核心文件 | 功能描述 |
|
||
|------|---------|---------|
|
||
| 通信层 | `gateway-client.ts` | WebSocket/REST 双协议，Ed25519+JWT 认证 |
|
||
| 状态管理 | `store/*.ts` | 7 个 Zustand Store，持久化支持 |
|
||
| 安全认证 | `secure-storage.ts` | OS Keyring 集成，设备密钥管理 |
|
||
| 配置系统 | `toml-utils.ts`, `config-parser.ts` | TOML 解析，环境变量插值 |
|
||
|
||
### 2.2 核心功能 (Core Features)
|
||
| 模块 | 核心组件 | 功能描述 |
|
||
|------|---------|---------|
|
||
| 聊天界面 | `ChatArea.tsx` | 流式响应，Markdown 渲染，模型选择 |
|
||
| Agent 分身 | `CloneManager.tsx` | 创建/编辑/删除 Agent 人格 |
|
||
| Hands 系统 | `HandList.tsx`, `HandTaskPanel.tsx` | 7 个自主能力包触发和管理 |
|
||
| 工作流引擎 | `SchedulerPanel.tsx` | 多步骤任务编排和调度 |
|
||
| 团队协作 | `TeamCollaborationView.tsx` | Dev↔QA 循环，角色分工 |
|
||
| 多 Agent 协作 | `SwarmDashboard.tsx` | Sequential/Parallel/Debate 协作模式 |
|
||
|
||
### 2.3 智能层 (L4 Self-Evolution)
|
||
| 模块 | 核心文件 | 功能描述 |
|
||
|------|---------|---------|
|
||
| Agent 记忆 | `agent-memory.ts` | 跨会话持久记忆，5 种类型 |
|
||
| 身份演化 | `agent-identity.ts` | SOUL/AGENTS/USER 动态更新 |
|
||
| 上下文压缩 | `context-compactor.ts` | Token 优化，记忆冲刷 |
|
||
| 自我反思 | `reflection-engine.ts` | 行为分析，改进建议 |
|
||
| 心跳巡检 | `heartbeat-engine.ts` | 主动智能，L2→L3 跃迁 |
|
||
| 自主授权 | `autonomy-manager.ts` | Supervised/Assisted/Autonomous |
|
||
|
||
### 2.4 上下文数据库
|
||
| 模块 | 核心文件 | 功能描述 |
|
||
|------|---------|---------|
|
||
| OpenViking 集成 | `viking-client.ts` | 本地/远程/存储三种模式 |
|
||
| 向量记忆 | `vector-memory.ts` | 语义搜索，相关性排序 |
|
||
| 会话持久化 | `session-persistence.ts` | 自动保存，崩溃恢复 |
|
||
| 记忆提取 | `memory-extractor.ts` | LLM/规则双模式提取 |
|
||
|
||
### 2.5 Skills 生态
|
||
| 类别 | 数量 | 代表技能 |
|
||
|------|------|---------|
|
||
| 开发工程 | 15+ | ai-engineer, senior-developer, backend-architect |
|
||
| 协调管理 | 8+ | agents-orchestrator, project-shepherd |
|
||
| 测试质量 | 6+ | code-reviewer, reality-checker, evidence-collector |
|
||
| 设计体验 | 8+ | ux-architect, brand-guardian, ui-designer |
|
||
| 数据分析 | 5+ | analytics-reporter, performance-benchmarker |
|
||
| 社媒营销 | 12+ | twitter-engager, xiaohongshu-specialist |
|
||
| 中文平台 | 5+ | chinese-writing, feishu-docs, wechat-oa |
|
||
| XR/空间 | 4+ | visionos-spatial-engineer, xr-immersive-dev |
|
||
|
||
### 2.6 Hands 系统 (7 个)
|
||
| Hand | 类型 | 触发方式 | 需审批 |
|
||
|------|------|---------|-------|
|
||
| researcher | research | 手动/事件 | 否 |
|
||
| browser | automation | 手动/Webhook | 是 |
|
||
| lead | automation | 定时/手动 | 是 |
|
||
| clip | automation | 手动/定时 | 否 |
|
||
| collector | data | 定时/事件/手动 | 否 |
|
||
| predictor | data | 手动/定时 | 否 |
|
||
| twitter | communication | 定时/事件 | 是 |
|
||
|
||
### 2.7 Tauri 后端 (Rust)
|
||
| 模块 | 文件 | 功能 |
|
||
|------|------|------|
|
||
| OpenFang 集成 | `lib.rs` (1043行) | 运行时管理，TOML 配置 |
|
||
| OpenViking 集成 | `viking_commands.rs` | CLI sidecar，服务器管理 |
|
||
| LLM 记忆提取 | `memory/extractor.rs` | 多提供商支持 |
|
||
| 安全存储 | `secure_storage.rs` | OS Keyring 封装 |
|
||
|
||
---
|
||
|
||
## 三、实施计划
|
||
|
||
### 3.1 阶段一：创建功能文档结构 (30 分钟)
|
||
|
||
创建目录结构：
|
||
```
|
||
docs/features/
|
||
├── README.md # 功能索引
|
||
├── 00-architecture/ # 架构层
|
||
│ ├── 01-communication-layer.md
|
||
│ ├── 02-state-management.md
|
||
│ └── 03-security-auth.md
|
||
├── 01-core-features/ # 核心功能
|
||
│ ├── 00-chat-interface.md
|
||
│ ├── 01-agent-clones.md
|
||
│ ├── 02-hands-system.md
|
||
│ ├── 03-workflow-engine.md
|
||
│ ├── 04-team-collaboration.md
|
||
│ └── 05-swarm-coordination.md
|
||
├── 02-intelligence-layer/ # 智能层
|
||
│ ├── 00-agent-memory.md
|
||
│ ├── 01-identity-evolution.md
|
||
│ ├── 02-context-compaction.md
|
||
│ ├── 03-reflection-engine.md
|
||
│ ├── 04-heartbeat-proactive.md
|
||
│ └── 05-autonomy-manager.md
|
||
├── 03-context-database/ # 上下文数据库
|
||
│ ├── 00-openviking-integration.md
|
||
│ ├── 01-vector-memory.md
|
||
│ ├── 02-session-persistence.md
|
||
│ └── 03-memory-extraction.md
|
||
├── 04-skills-ecosystem/ # Skills 生态
|
||
│ ├── 00-skill-system.md
|
||
│ ├── 01-builtin-skills.md
|
||
│ └── 02-skill-discovery.md
|
||
├── 05-hands-system/ # Hands 系统
|
||
│ └── 00-hands-overview.md
|
||
└── 06-tauri-backend/ # Tauri 后端
|
||
├── 00-openfang-integration.md
|
||
├── 01-secure-storage.md
|
||
└── 02-local-gateway.md
|
||
```
|
||
|
||
### 3.2 阶段二：编写功能文档 (2-3 小时)
|
||
|
||
每个功能文档包含以下章节：
|
||
|
||
```markdown
|
||
# [功能名称]
|
||
|
||
## 一、功能概述
|
||
- 基本信息：分类、优先级、成熟度、依赖
|
||
- 相关文件：核心实现、类型定义、测试、UI 组件
|
||
|
||
## 二、设计初衷
|
||
### 2.1 问题背景
|
||
- 用户痛点
|
||
- 系统缺失能力
|
||
- 为什么需要
|
||
|
||
### 2.2 设计目标
|
||
- SMART 原则目标
|
||
|
||
### 2.3 竞品参考
|
||
- OpenClaw / NanoClaw / ZeroClaw 对比
|
||
|
||
### 2.4 设计约束
|
||
- 技术/资源/时间/兼容性约束
|
||
|
||
## 三、技术设计
|
||
### 3.1 核心接口
|
||
### 3.2 数据流
|
||
### 3.3 状态管理
|
||
### 3.4 关键算法
|
||
|
||
## 四、预期作用
|
||
### 4.1 用户价值
|
||
- 效率提升、体验改善、能力扩展
|
||
|
||
### 4.2 系统价值
|
||
- 架构收益、可维护性、可扩展性
|
||
|
||
### 4.3 成功指标
|
||
| 指标 | 基线 | 目标 | 当前 |
|
||
|
||
## 五、实际效果
|
||
### 5.1 已实现功能
|
||
- [x] 已完成 / [ ] 待实现
|
||
|
||
### 5.2 测试覆盖
|
||
- 单元测试、集成测试、覆盖率
|
||
|
||
### 5.3 已知问题
|
||
| 问题 | 严重程度 | 状态 | 计划解决 |
|
||
|
||
### 5.4 用户反馈
|
||
|
||
## 六、演化路线
|
||
- 短期/中期/长期计划
|
||
|
||
## 七、头脑风暴笔记
|
||
### 7.1 待讨论问题
|
||
### 7.2 创意想法
|
||
### 7.3 风险与挑战
|
||
```
|
||
|
||
### 3.3 阶段三：功能优先级矩阵 (30 分钟)
|
||
|
||
创建 ICE 评分表：
|
||
|
||
| 功能 | Impact (10) | Confidence (10) | Ease (10) | ICE 分 |
|
||
|------|-------------|-----------------|-----------|--------|
|
||
| Agent 记忆 | 10 | 9 | 7 | 630 |
|
||
| 身份演化 | 8 | 9 | 9 | 648 |
|
||
| 上下文压缩 | 9 | 8 | 6 | 432 |
|
||
| Heartbeat | 9 | 8 | 6 | 432 |
|
||
| 多 Agent 协作 | 9 | 6 | 4 | 216 |
|
||
|
||
### 3.4 阶段四：头脑风暴 (1 小时)
|
||
|
||
基于分析结果，探索以下方向：
|
||
|
||
1. **功能增强方向**
|
||
- 哪些功能可以进一步深化？
|
||
- 哪些功能组合可以产生新价值？
|
||
|
||
2. **用户体验优化**
|
||
- 哪些交互可以更流畅？
|
||
- 哪些反馈可以更及时？
|
||
|
||
3. **技术架构演进**
|
||
- 哪些模块可以重构？
|
||
- 哪些依赖可以升级？
|
||
|
||
4. **商业化可能性**
|
||
- 哪些功能可以作为差异化卖点？
|
||
- 哪些能力可以产品化？
|
||
|
||
---
|
||
|
||
## 四、关键文件参考
|
||
|
||
| 文件 | 用途 |
|
||
|------|------|
|
||
| `docs/ZCLAW_AGENT_INTELLIGENCE_EVOLUTION.md` | 智能演化完整设计 |
|
||
| `docs/knowledge-base/openfang-technical-reference.md` | OpenFang 技术参考 (969行) |
|
||
| `desktop/src/lib/gateway-client.ts` | 通信层核心实现 |
|
||
| `desktop/src/store/index.ts` | Store 协调器 |
|
||
| `desktop/src-tauri/src/lib.rs` | Tauri 后端核心 |
|
||
| `skills/.playbooks/README.md` | Playbooks 系统设计 |
|
||
|
||
---
|
||
|
||
## 五、交付物
|
||
|
||
1. **功能文档目录** (`docs/features/`)
|
||
- 约 25 个功能文档
|
||
- 统一的文档模板
|
||
- 完整的功能索引
|
||
|
||
2. **功能优先级矩阵** (`docs/features/README.md`)
|
||
- ICE 评分表
|
||
- 成熟度评估
|
||
|
||
3. **头脑风暴记录** (`docs/features/brainstorming-notes.md`)
|
||
- 待讨论问题
|
||
- 创意想法
|
||
- 风险与挑战
|
||
|
||
---
|
||
|
||
## 六、验证方法
|
||
|
||
1. **文档完整性检查**
|
||
- 所有模块都有对应文档
|
||
- 每个文档包含完整章节
|
||
|
||
2. **一致性检查**
|
||
- 文件路径引用正确
|
||
- 技术术语统一
|
||
|
||
3. **价值评估**
|
||
- 每个功能的设计初衷清晰
|
||
- 实际效果与预期对比明确
|
||
|
||
---
|
||
|
||
## 七、时间估算
|
||
|
||
| 阶段 | 估算时间 |
|
||
|------|---------|
|
||
| 创建文档结构 | 30 分钟 |
|
||
| 编写功能文档 | 2-3 小时 |
|
||
| 功能优先级矩阵 | 30 分钟 |
|
||
| 头脑风暴 | 1 小时 |
|
||
| **总计** | **4-5 小时** |
|