docs(guide): rewrite CLAUDE.md with ZCLAW-first perspective

Major changes:
- Shift from "OpenFang desktop client" to "independent AI Agent desktop app"
- Add decision principle: "Is this useful for ZCLAW? Does it affect ZCLAW?"
- Simplify project structure and tech stack sections
- Replace OpenClaw vs OpenFang comparison with unified backend approach
- Consolidate troubleshooting from scattered sections into organized FAQ
- Update Hands system documentation with 8 capabilities and status
- Stream

docs/features/README.md

@@ -72,7 +72,7 @@
 
 | 文档 | 功能 | 成熟度 | 测试覆盖 |
 |------|------|--------|---------|
-| [00-openfang-integration.md](06-tauri-backend/00-openfang-integration.md) | OpenFang 集成 | L4 | 高 |
+| [00-backend-integration.md](06-tauri-backend/00-backend-integration.md) | 后端集成 | L4 | 高 |
 | [01-secure-storage.md](06-tauri-backend/01-secure-storage.md) | 安全存储 | L4 | 高 |
 | [02-local-gateway.md](06-tauri-backend/02-local-gateway.md) | 本地 Gateway | L4 | 高 |
 

docs/knowledge-base/README.md

@@ -7,25 +7,26 @@
 ```
 knowledge-base/
 ├── README.md                    # 本文件 - 索引
-├── openfang-websocket-protocol.md   # OpenFang WebSocket 协议实际实现
+├── zclaw-technical-reference.md # ZCLAW 技术参考
+├── websocket-protocol.md        # WebSocket 协议文档
+├── configuration.md             # 配置系统文档
 ├── troubleshooting.md           # 常见问题排查
 ├── frontend-integration.md      # 前端集成模式
 ├── agent-provider-config.md     # Agent 和 LLM 提供商配置
-├── tauri-desktop.md            # Tauri 桌面端开发笔记
-├── feature-checklist.md        # 功能清单和验证状态
+├── tauri-desktop.md             # Tauri 桌面端开发笔记
+├── feature-checklist.md         # 功能清单和验证状态
 └── hands-integration-lessons.md # Hands 集成经验总结
 ```
 
-> **系统分析**: 完整的系统偏离分析和演化路线图见 [../SYSTEM_ANALYSIS.md](../SYSTEM_ANALYSIS.md)
-
 ## 快速索引
 
 ### 协议与通信
 
 | 主题 | 文件 | 关键词 |
 |------|------|--------|
-| WebSocket 流式聊天 | [openfang-websocket-protocol.md](./openfang-websocket-protocol.md) | 流式响应, 事件类型, 消息格式 |
-| REST API | [openfang-websocket-protocol.md](./openfang-websocket-protocol.md#rest-api) | Agent, Hands, Health |
+| WebSocket 流式聊天 | [websocket-protocol.md](./websocket-protocol.md) | 流式响应, 事件类型, 消息格式 |
+| REST API | [zclaw-technical-reference.md](./zclaw-technical-reference.md) | Agent, Hands, Health |
+| 配置系统 | [configuration.md](./configuration.md) | TOML, 环境变量 |
 
 ### 故障排查
 
@@ -49,8 +50,9 @@ knowledge-base/
 
 | 日期 | 版本 | 变更 |
 |------|------|------|
+| 2026-03-19 | v2.0 | 重构为 ZCLAW 独立产品文档 |
 | 2026-03-14 | v1.1 | 添加 Hands 集成经验总结、功能清单 |
-| 2026-03-14 | v1.0 | 初始创建，记录 OpenFang WebSocket 协议发现 |
+| 2026-03-14 | v1.0 | 初始创建 |
 
 ---
 

docs/knowledge-base/team-feature-notes.md

@@ -0,0 +1,138 @@
+# 团队功能开发笔记
+
+**完成日期**: 2026-03-19
+**任务**: 修复团队功能页面空白问题
+
+---
+
+## 一、问题描述
+
+点击"团队"导航后，页面显示空白，控制台报错 `teams.map is not a function`。
+
+## 二、根因分析
+
+### 2.1 数据格式冲突
+
+Zustand 的 `persist` 中间件存储格式为：
+```json
+{
+  "state": { "teams": [...], "activeTeam": ... },
+  "version": 0
+}
+```
+
+但 `loadTeams` 函数期望的是直接的数组格式 `Team[]`。
+
+### 2.2 类型安全问题
+
+TeamList 组件中的 `availableAgents` 变量使用了条件表达式，返回类型不一致：
+- `clones` 是 `Clone[]` 类型
+- `agents.map(...)` 返回的是 `{ id, name, role }[]` 类型
+
+TypeScript 无法推断统一类型，运行时可能导致错误。
+
+## 三、解决方案
+
+### 3.1 修复 loadTeams 函数
+
+```typescript
+loadTeams: async () => {
+  set({ isLoading: true, error: null });
+  try {
+    const stored = localStorage.getItem('zclaw-teams');
+    let teams: Team[] = [];
+
+    if (stored) {
+      const parsed = JSON.parse(stored);
+      // 处理 persist 中间件格式
+      if (parsed?.state?.teams && Array.isArray(parsed.state.teams)) {
+        teams = parsed.state.teams;
+      } else if (Array.isArray(parsed)) {
+        teams = parsed;
+      }
+    }
+
+    set({ teams, isLoading: false });
+  } catch (error) {
+    set({ teams: [], isLoading: false });
+  }
+},
+```
+
+### 3.2 修复 availableAgents 类型
+
+```typescript
+const availableAgents: Array<{ id: string; name: string; role?: string }> =
+  (clones && clones.length > 0)
+    ? clones.map(c => ({ id: c.id, name: c.name, role: c.role }))
+    : (agents && agents.length > 0)
+      ? agents.map(a => ({ id: a.id, name: a.name, role: '默认助手' }))
+      : [];
+```
+
+### 3.3 添加防御性检查
+
+```typescript
+// TeamList.tsx
+{!Array.isArray(teams) || teams.length === 0 ? (
+  <EmptyState ... />
+) : (
+  teams.map(...)
+)}
+```
+
+## 四、相关文件
+
+| 文件 | 修改内容 |
+|------|----------|
+| `store/teamStore.ts` | loadTeams 函数处理 persist 格式 |
+| `components/TeamList.tsx` | 类型修复、防御性检查、中文化 |
+| `components/ui/EmptyState.tsx` | CSS 修复 (flex-1 → h-full) |
+| `App.tsx` | motion.main 添加 flex flex-col |
+
+## 五、经验教训
+
+1. **persist 中间件存储格式**: Zustand persist 存储的是 `{ state, version }` 结构，不是直接的状态值
+2. **条件表达式类型一致性**: 三元表达式的两个分支必须返回相同类型
+3. **防御性编程**: 对从 store 获取的数据进行 Array.isArray 检查
+
+---
+
+*文档创建: 2026-03-19*
+
+---
+
+## 六、协作功能修复 (2026-03-19)
+
+### 6.1 问题描述
+
+1. **UI 颜色不一致**: SwarmDashboard 使用蓝色(blue-500)作为主色调，与系统的橙色/灰色风格不匹配
+2. **内容重复渲染**: 左侧边栏和主内容区同时渲染 SwarmDashboard，导致内容重复
+
+### 6.2 解决方案
+
+**问题 1: 内容重复**
+- 从 `Sidebar.tsx` 移除 `{activeTab === 'swarm' && <SwarmDashboard />}` 渲染
+- 只保留 `App.tsx` 中的主内容区渲染
+- 移除未使用的 `import { SwarmDashboard }` 语句
+
+**问题 2: 颜色一致性**
+修改 `SwarmDashboard.tsx` 中的配色：
+- 主色调: `blue-500` → `orange-500`
+- 按钮背景: `bg-blue-500` → `bg-orange-500`
+- Filter tabs: `bg-blue-100` → `bg-orange-100`
+- 选中边框: `border-blue-500` → `border-orange-500`
+- Focus ring: `ring-blue-500` → `ring-orange-500`
+- 保留执行状态(`executing`/`running`)的蓝色作为状态指示色
+
+### 6.3 相关文件
+
+| 文件 | 修改内容 |
+|------|----------|
+| `components/Sidebar.tsx` | 移除 SwarmDashboard 渲染和 import |
+| `components/SwarmDashboard.tsx` | 配色从蓝色改为橙色 |
+
+### 6.4 设计原则
+
+1. **单一渲染原则**: 每个视图组件只在唯一位置渲染，避免多处同时显示
+2. **颜色一致性**: 交互元素使用系统主色调(橙色)，状态指示可保留语义色(蓝色=执行中，绿色=完成，红色=失败)

docs/knowledge-base/troubleshooting.md

@@ -729,7 +729,81 @@ ctx.fillStyle = '#f9fafb'; // gray-50 (浅色)
 
 ---
 
-## 8. 相关文档
+## 8. 端口配置问题
+
+### 8.1 OpenFang 端口不匹配导致 Network Error
+
+**症状**: 创建 Agent 或其他 API 操作时报错 `Failed to create agent: Network Error`，控制台显示 `POST http://localhost:1420/api/agents net::ERR_CONNECTION_REFUSED`
+
+**根本原因**: `runtime-manifest.json` 声明端口 4200，但实际 OpenFang 运行在 **50051** 端口
+
+**正确配置**:
+
+| 配置位置 | 正确端口 |
+|---------|----------|
+| `runtime-manifest.json` | 4200 (声明，但实际不使用) |
+| **实际运行端口** | **50051** |
+| `vite.config.ts` 代理 | **50051** |
+| `gateway-client.ts` | **50051** |
+
+**解决方案**:
+
+1. 更新 `vite.config.ts`:
+```typescript
+proxy: {
+  '/api': {
+    target: 'http://127.0.0.1:50051',  // 使用实际运行端口
+    // ...
+  },
+}
+```
+
+2. 更新 `gateway-client.ts`:
+```typescript
+export const DEFAULT_GATEWAY_URL = `${DEFAULT_WS_PROTOCOL}127.0.0.1:50051/ws`;
+export const FALLBACK_GATEWAY_URLS = [
+  DEFAULT_GATEWAY_URL,
+  `${DEFAULT_WS_PROTOCOL}127.0.0.1:4200/ws`,  // 保留作为备选
+];
+```
+
+**验证端口**:
+```bash
+# 检查实际运行的端口
+netstat -ano | findstr "50051"
+netstat -ano | findstr "4200"
+```
+
+**注意**: `runtime-manifest.json` 中的端口声明与实际运行端口不一致，以实际监听端口为准。
+
+**涉及文件**:
+- `desktop/vite.config.ts` - Vite 代理配置
+- `desktop/src/lib/gateway-client.ts` - WebSocket 客户端默认 URL
+- `desktop/src/components/Settings/General.tsx` - 设置页面显示地址
+- `desktop/src/components/Settings/ModelsAPI.tsx` - 模型 API 重连逻辑
+
+**排查流程**:
+1. 先用 `netstat` 确认实际监听端口
+2. 对比 `runtime-manifest.json` 声明端口与实际端口
+3. 确保所有前端配置使用**实际监听端口**
+4. 重启 Vite 开发服务器
+
+**验证修复**:
+```bash
+# 检查端口监听
+netstat -ano | findstr "50051"
+# 应显示 LISTENING
+
+# 重启 Vite 后测试
+curl http://localhost:1420/api/agents
+# 应返回 JSON 数组而非 404/502
+```
+
+**文件**: 多个配置文件
+
+---
+
+## 9. 相关文档
 
 - [OpenFang 配置指南](./openfang-configuration.md) - 配置文件位置、格式和最佳实践
 - [Agent 和 LLM 提供商配置](./agent-provider-config.md) - Agent 管理和 Provider 配置
@@ -741,6 +815,7 @@ ctx.fillStyle = '#f9fafb'; // gray-50 (浅色)
 
 | 日期 | 变更 |
 |------|------|
+| 2026-03-20 | 添加端口配置问题：runtime-manifest.json 声明 4200 但实际运行 50051 |
 | 2026-03-18 | 添加记忆提取和图谱 UI 问题 |
 | 2026-03-18 | 添加刷新后对话丢失问题和 ChatArea 布局问题 |
 | 2026-03-17 | 添加首次使用引导流程 |