From b3b4a22e5a6aa69b999365bf117c636d874cd855 Mon Sep 17 00:00:00 2001 From: milome Date: Wed, 22 Apr 2026 14:48:12 +0800 Subject: [PATCH] docs: add bilingual README (Chinese + English) Rewrite README.md with improved structure (feature overview, tables, testing section) Add README.en.md as the English version Cross-link between the two versions Made-with: Cursor --- README.en.md | 119 +++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 76 +++++++++++++++++++++----------- 2 files changed, 170 insertions(+), 25 deletions(-) create mode 100644 README.en.md diff --git a/README.en.md b/README.en.md new file mode 100644 index 0000000..8fb9a9a --- /dev/null +++ b/README.en.md @@ -0,0 +1,119 @@ +# ClawScope + +**Memory Made Visible, Evolution Enabled** · [中文](README.md) + +An OpenClaw memory and evolution management tool — a cross-platform desktop app built with Tauri 2 + Rust. + +**Codename:** Both the repository and executable use **ClawScope** as the project codename. + +## Feature Overview + +- **Memory Management** — Browse, search, and archive OpenClaw memory entries with semantic search and knowledge graph support +- **Evolution Tracking** — Review and trace OpenClaw evolution history, generate audit reports +- **Configuration Management** — Centrally manage OpenClaw node configurations and state +- **Cross-Platform** — Native desktop app for Windows / macOS / Linux + +## Quick Start + +```bash +npm install +npm run tauri dev +``` + +## Build + +```bash +npm run tauri build +``` + +Notes: + +- Local `tauri build` only produces installers for the current host platform. +- Running on Windows yields Windows artifacts only (e.g., `msi` / `nsis`). +- For the canonical cross-platform release matrix, see the GitHub Actions release workflow documented below under "Release Platforms". + +## Testing + +```bash +# Run all tests +npm test + +# Run type checking +npm run lint +``` + +## Visual Regression + +This repository includes a Playwright-based light/dark theme screenshot regression workflow that captures baselines for the four main pages: `Profile`, `Memory`, `Config`, and `Evolution`. + +With an existing preview server: + +```bash +npm run build +npm run preview -- --host 127.0.0.1 --port 4173 +npm run visual:baseline +``` + +One-command local / CI: + +```bash +npm run visual:ci +``` + +Environment variables: + +| Variable | Description | +|---|---| +| `VISUAL_BASELINE_NAME` | Output directory name; defaults to the current date or `ci-baseline` in CI | +| `VISUAL_BASE_URL` | Specify an existing preview URL | +| `VISUAL_PORT` / `VISUAL_HOST` | Host/port for the preview server started by `visual:ci` | + +Screenshots are output to `artifacts/visual-regression//`. See [`artifacts/visual-regression/README.md`](artifacts/visual-regression/README.md) for directory conventions and manual review instructions. + +## Tech Stack + +| Layer | Technology | +|---|---| +| Frontend | React 18 + TypeScript + Vite | +| UI | Radix UI + Tailwind CSS 4 + shadcn/ui | +| Desktop | Tauri 2 + Rust | +| Charts | Recharts | +| Testing | Vitest + Playwright | + +## Prerequisites + +- **Windows:** Install [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) with the "Desktop development with C++" workload, or a full Visual Studio installation +- **Rust:** `rustup default stable-msvc` (MSVC toolchain recommended on Windows) + +If you encounter `dlltool.exe: program not found` during build, install the toolchain above. + +## Release Platforms + +ClawScope targets the following platforms for open-source releases: + +| Platform | Artifact Formats | +|---|---| +| Windows x64 | NSIS `setup.exe` / `MSI` | +| macOS Apple Silicon | `.app` / `.dmg` | +| macOS Intel | `.app` / `.dmg` | +| Linux x64 | `AppImage` / `deb` / `rpm` | + +A cross-platform release workflow is included in the repository: + +- [`.github/workflows/release.yml`](.github/workflows/release.yml) + +For additional details and the release matrix, see: + +- [`docs/release/platform-support.md`](docs/release/platform-support.md) + +## Documentation + +If you use the BMAD workflow locally, planning artifacts reside in `_bmad-output/` (not tracked by `.gitignore` in this repo; clone and generate or obtain from your team). + +- PRD: `_bmad-output/planning-artifacts/main/prd.md` +- Project setup: `_bmad-output/planning-artifacts/main/PROJECT_SETUP.md` +- Help: [`docs/help/choose-extra-paths-or-knowledge-injection.md`](docs/help/choose-extra-paths-or-knowledge-injection.md) + +## License + +[MIT](LICENSE) \ No newline at end of file diff --git a/README.md b/README.md index f64d17f..04dc6eb 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,17 @@ # ClawScope -**记忆可见，进化可期** +**记忆可见，进化可期** · [English](README.en.md) -OpenClaw 记忆与进化管理工具 — Tauri 2 + Rust 桌面应用。 +OpenClaw 记忆与进化管理工具 — 基于 Tauri 2 + Rust 构建的跨平台桌面应用。 -**命名：** 本仓库与可执行侧为 **代号 ClawScope**。 +**代号：** 本仓库与可执行文件均使用 **ClawScope** 作为项目代号。 + +## 功能概览 + +- **记忆管理** — 查看、搜索、归档 OpenClaw 记忆条目，支持语义搜索与知识图谱 +- **进化追踪** — 审视与回溯 OpenClaw 进化历史，生成审计报告 +- **配置管理** — 集中管理 OpenClaw 节点配置与状态 +- **跨平台** — Windows / macOS / Linux 原生桌面应用 ## 快速开始 @@ -23,7 +30,17 @@ npm run tauri build - 本地 `tauri build` 只会产出当前宿主平台的安装包。 - 在 Windows 本机执行时，默认只会得到 Windows 产物（如 `msi` / `nsis`）。 -- 标准开源发布矩阵以 GitHub Actions 的跨平台 release workflow 为准，见下文“发布平台”。 +- 标准开源发布矩阵以 GitHub Actions 的跨平台 release workflow 为准，见下文"发布平台"。 + +## 测试 + +```bash +# 运行所有测试 +npm test + +# 运行类型检查 +npm run lint +``` ## Visual Regression @@ -45,29 +62,28 @@ npm run visual:ci 可选环境变量： -- `VISUAL_BASELINE_NAME`：指定输出目录名，默认取当天日期或 CI 中的 `ci-baseline` -- `VISUAL_BASE_URL`：指定已有预览地址 -- `VISUAL_PORT` / `VISUAL_HOST`：用于 `visual:ci` 自动拉起预览服务时指定监听地址 +| 变量 | 说明 | +|---|---| +| `VISUAL_BASELINE_NAME` | 指定输出目录名，默认取当天日期或 CI 中的 `ci-baseline` | +| `VISUAL_BASE_URL` | 指定已有预览地址 | +| `VISUAL_PORT` / `VISUAL_HOST` | 用于 `visual:ci` 自动拉起预览服务时指定监听地址 | -截图产物默认输出到 `artifacts/visual-regression//`，目录规范与人工审查方式见 [artifacts/visual-regression/README.md](artifacts/visual-regression/README.md)。 +截图产物默认输出到 `artifacts/visual-regression//`，目录规范与人工审查方式见 [`artifacts/visual-regression/README.md`](artifacts/visual-regression/README.md)。 ## 技术栈 -- **前端:** React + TypeScript + Vite -- **桌面:** Tauri 2 + Rust - -## 相关文档 - -若本地使用 BMAD 工作流，规划产物在 `_bmad-output/`（本仓库 `.gitignore` 不跟踪；克隆后需自行生成或从团队渠道获取）。 - -- PRD: `_bmad-output/planning-artifacts/main/prd.md` -- 项目设置: `_bmad-output/planning-artifacts/main/PROJECT_SETUP.md` -- 帮助文档: [`docs/help/choose-extra-paths-or-knowledge-injection.md`](docs/help/choose-extra-paths-or-knowledge-injection.md) +| 层 | 技术 | +|---|---| +| 前端 | React 18 + TypeScript + Vite | +| UI | Radix UI + Tailwind CSS 4 + shadcn/ui | +| 桌面 | Tauri 2 + Rust | +| 图表 | Recharts | +| 测试 | Vitest + Playwright | ## 环境要求 -- **Windows:** 需安装 [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/)（含「使用 C++ 的桌面开发」工作负载）或完整 Visual Studio -- **Rust:** `rustup default stable-msvc`（Windows 上建议使用 MSVC 工具链） +- **Windows：** 需安装 [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/)（含「使用 C++ 的桌面开发」工作负载）或完整 Visual Studio +- **Rust：** `rustup default stable-msvc`（Windows 上建议使用 MSVC 工具链） 若构建报错 `dlltool.exe: program not found`，请安装上述工具链。 @@ -75,10 +91,12 @@ npm run visual:ci 面向开源发布时，ClawScope 目标对齐以下平台： -- Windows x64：`NSIS setup.exe` / `MSI` -- macOS Apple Silicon：`.app` / `.dmg` -- macOS Intel：`.app` / `.dmg` -- Linux x64：`AppImage` / `deb` / `rpm` +| 平台 | 产物格式 | +|---|---| +| Windows x64 | NSIS `setup.exe` / `MSI` | +| macOS Apple Silicon | `.app` / `.dmg` | +| macOS Intel | `.app` / `.dmg` | +| Linux x64 | `AppImage` / `deb` / `rpm` | 仓库内已提供跨平台发布工作流： @@ -88,6 +106,14 @@ npm run visual:ci - [`docs/release/platform-support.md`](docs/release/platform-support.md) +## 相关文档 + +若本地使用 BMAD 工作流，规划产物在 `_bmad-output/`（本仓库 `.gitignore` 不跟踪；克隆后需自行生成或从团队渠道获取）。 + +- PRD: `_bmad-output/planning-artifacts/main/prd.md` +- 项目设置: `_bmad-output/planning-artifacts/main/PROJECT_SETUP.md` +- 帮助文档: [`docs/help/choose-extra-paths-or-knowledge-injection.md`](docs/help/choose-extra-paths-or-knowledge-injection.md) + ## License -MIT +[MIT](LICENSE) \ No newline at end of file