Files

iven adfd7024df docs(claude): restructure documentation management and add feedback system

- 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

2026-03-16 13:54:03 +08:00

5.3 KiB

Raw Blame History

ZCLAW 工作总结 - 2026-03-16

完成的工作

1. OpenViking 本地服务器管理（隐私优先部署）

问题：用户可能有隐私顾虑，会话数据不能上传到远程服务器。

解决方案：实现本地 OpenViking 服务器管理功能。

新增文件

文件	功能
`desktop/src-tauri/src/viking_server.rs`	Rust 后端服务器管理（启动/停止/状态）
`desktop/src/lib/viking-server-manager.ts`	TypeScript 服务器管理客户端
`desktop/src/lib/viking-adapter.ts`	更新为多模式适配器（local/sidecar/remote）

功能特性

自动模式检测：优先尝试本地服务器 → sidecar → remote
隐私保证：所有数据存储在 ~/.openviking/，服务器只监听 127.0.0.1
优雅降级：当本地服务器不可用时自动回退

Tauri 命令

viking_server_status()   // 获取服务器状态
viking_server_start()    // 启动本地服务器
viking_server_stop()     // 停止服务器
viking_server_restart()  // 重启服务器

2. 文档整理与归档

之前：文档散落在多个位置，文件名混乱（如 greedy-prancing-cocke.md）

之后：规范化文档结构

docs/
├── DEVELOPMENT.md                    # 开发指南
├── OPENVIKING_INTEGRATION.md         # OpenViking 集成文档（已更新）
├── USER_MANUAL.md                    # 用户手册
├── ZCLAW_AGENT_INTELLIGENCE_EVOLUTION.md  # Agent 进化计划
├── archive/                          # 归档文档
│   ├── completed-plans/              # 已完成的计划
│   ├── research-reports/             # 研究报告
│   └── openclaw-legacy/              # OpenClaw 遗留文档
├── knowledge-base/                   # 技术知识库
│   ├── openfang-technical-reference.md
│   ├── openfang-websocket-protocol.md
│   └── ...
├── plans/                            # 执行计划
└── test-reports/                     # 测试报告

3. 测试验证

测试类型	结果
TypeScript 编译	✅ 无错误
Viking Adapter 测试	✅ 21 passed
Rust 测试	✅ 10 passed
Cargo Build	✅ 成功
OpenViking 服务器启动	✅ 成功（端口 1933）
API 健康检查	✅ `/health` 返回 `{"status":"ok"}`
会话创建	✅ 成功
消息添加	✅ 成功

提交记录

c8202d0 feat(viking): add local server management for privacy-first deployment

当前项目状态

已完成

Agent 智能层 Phase 1-3（274 passing tests）
OpenViking 本地服务器管理
文档结构整理
Python 3.12 安装（通过 winget）
OpenViking pip 安装成功（v0.2.6）
火山引擎 API 密钥配置
OpenViking 服务器启动验证
基础 API 测试（健康检查、会话创建、消息添加）
火山引擎 Embedding 模型激活 (ep-20260316102010-cq422)
向量搜索功能验证 ✅

进行中

多 Agent 协作 UI 产品化

待办

RuntimeAdapter 接口抽象
领域模型标准化

OpenViking 集成状态

已验证功能

功能	状态	说明
服务器启动	✅	`http://127.0.0.1:1933`
健康检查	✅	`GET /health` → `{"status":"ok"}`
系统状态	✅	`GET /api/v1/system/status`
会话创建	✅	`POST /api/v1/sessions`
消息添加	✅	`POST /api/v1/sessions/{id}/messages`
向量搜索	⚠️	需要激活 Embedding 模型

✅ 已解决：火山引擎 Embedding 模型激活

Endpoint ID: ep-20260316102010-cq422

配置文件 (~/.openviking/ov.conf)：

{
  "embedding": {
    "dense": {
      "api_base": "https://ark.cn-beijing.volces.com/api/v3",
      "api_key": "3739b6b2-2bff-4a13-9f82-c0674dd4a05e",
      "provider": "volcengine",
      "model": "ep-20260316102010-cq422",
      "dimension": 1024
    }
  }
}

验证结果：

向量搜索 API: ✅ 正常
会话创建: ✅ 正常
消息添加: ✅ 正常
TypeScript 测试: ✅ 21 passed

备选方案：使用 OpenAI Embedding

如果不想激活火山引擎 Embedding，可以改用 OpenAI：

{
  "embedding": {
    "dense": {
      "api_base": "https://api.openai.com/v1",
      "api_key": "${OPENAI_API_KEY}",
      "provider": "openai",
      "model": "text-embedding-3-small",
      "dimension": 1536
    }
  }
}

配置文件

当前配置 (~/.openviking/ov.conf)：

{
  "storage": {
    "workspace": "C:/Users/szend/.openviking/workspace",
    "vectordb": { "name": "context", "backend": "local" },
    "agfs": { "port": 1833, "log_level": "warn", "backend": "local" }
  },
  "embedding": {
    "dense": {
      "api_base": "https://ark.cn-beijing.volces.com/api/v3",
      "api_key": "3739b6b2-2bff-4a13-9f82-c0674dd4a05e",
      "provider": "volcengine",
      "dimension": 1024,
      "model": "doubao-embedding"
    }
  },
  "server": { "host": "127.0.0.1", "port": 1933 }
}

文件变更统计

新增文件：4 个
修改文件：3 个
归档文件：10+ 个
文档更新：2 个

下一步工作

完成 Embedding 模型激活（阻塞项）
验证向量搜索功能
测试 ZCLAW 记忆面板集成
提交完整集成代码

5.3 KiB Raw Blame History Unescape Escape