diff --git a/CHANGELOG.internal.md b/CHANGELOG.internal.md index 266fb6b..a0bb2ea 100644 --- a/CHANGELOG.internal.md +++ b/CHANGELOG.internal.md @@ -2,6 +2,166 @@ > 本文档记录所有技术细节，包括代码重构、构建优化等内部改动 +## [0.5.0] - 2026-05-01 (fs-only-v3) + +### Wails v3 迁移 🏗️ + +#### 框架升级 +- **Wails v2.12 → v3 alpha.80**: 全面迁移至 Wails v3 架构 +- **入口重构**: `main.go` 使用 `application.New()` + `application.WebviewWindowOptions` +- **Asset Server**: 从 v2 的 embed.FS 直接服务改为 v3 的 `application.AssetFileServerFS(assets)` + Middleware 模式 +- **Bindings**: 手动维护的 `wailsjs/wailsjs/`（v2 runtime）→ 自动生成的 `v3-bindings/` + `bindings/` + +#### main.go 关键变更 +```go +// 新增: AssetOptions Middleware 解决 custom.js 404 +Assets: application.AssetOptions{ + Handler: application.AssetFileServerFS(assets), + Middleware: func(next http.Handler) http.Handler { + return http.HandlerFunc(func(rw http.ResponseWriter, req *http.Request) { + if req.URL.Path == "/wails/custom.js" { + rw.Header().Set("Content-Type", "application/javascript") + rw.WriteHeader(200) + return + } + next.ServeHTTP(rw, req) + }) + }, +}, + +// 新增: 延迟 DevTools 启动（production+devtools build tag） +go func() { + time.Sleep(2 * time.Second) + _ = window.OpenDevTools() +}() +``` + +#### 窗口配置 +- Frameless 模式 + Windows 11 CustomTheme（圆角 + Aero 阴影） +- 亮/暗模式标题栏颜色独立配置：`titleBarLight=0xF0F0F0`, `titleBarDark=0x2D2D2D` +- MinWidth/MinHeight: 1000×600 + +--- + +### 构建系统重构 🔨 + +#### Taskfile.yml 对齐官方模板 +``` +executes: + - task: common:install:frontend:deps # once + - task: common:dev:frontend # background (Vite) + - task: build # blocking (Go compile) + - task: run # primary (run exe) +``` + +**旧方案问题**: 使用自定义 `dev.ps1` 脚本，无法正确处理 Vite proxy 502 错误 + +**新方案收益**: +- ✅ 官方标准流水线，502 问题消除（production build mode 服务嵌入 dist） +- ✅ 自动依赖安装、自动 bindings 生成 +- ✅ 跨平台构建模板（Android/iOS/Linux/macOS/Docker） + +#### Build Tags 策略 +| Tag | 用途 | +|-----|------| +| `production` | 使用嵌入 FS，不启动 Vite dev server | +| `devtools` | 编译保留 DevTools/OpenDevTools API | +| `windows && (!production \|\| devtools)` | DevTools 条件编译 | + +**关键**: `build/windows/Taskfile.yml` BUILD_FLAGS 硬编码 `,devtools`： +```yaml +BUILD_FLAGS: '{{if eq .DEV "true"}}...{{else}}-tags production,devtools ...{{end}}' +``` + +--- + +### 前端目录规范化 📁 + +#### web/ → frontend/ +- Wails v3 标准目录名为 `frontend/` +- git rename 78 个文件保持历史连续性 +- 删除旧的 `web/vite.config.js`、`web/package-lock.json` + +#### 新增文件 +| 文件 | 说明 | +|------|------| +| `frontend/vite.config.js` | v3 格式，port 9245 | +| `frontend/src/types/window.d.ts` | v3 window API 类型声明 | +| `frontend/src/api/wails-transport.ts` | v3 transport 层 | +| `frontend/src/wailsjs/v3-bindings/` | 自动生成绑定 | +| `frontend/bindings/` | TypeScript 绑定输出 | + +--- + +### Sidebar 滚动架构优化 🎨 + +#### 问题 +旧结构：`.sidebar { overflow-y: auto }` 整体滚动，收藏多了把帮助区块推到窗口外 + +#### 方案：三段式 Flex 布局 +```css +.sidebar { + display: flex; + flex-direction: column; + overflow: hidden; /* 不再整体滚动 */ +} + +/* 收藏夹内容区 — 内部独立滚动 */ +.section-content:not(.help-content) { + flex: 1; + min-height: 0; + overflow-y: auto; /* 收藏列表内部滚动 */ +} + +/* 帮助区块 — 固定底部 */ +.sidebar-section:last-child { + flex-shrink: 0; /* 不被压缩 */ +} +``` + +#### 折叠状态管理 +- `favCollapsed = ref(false)` — 默认展开 +- `helpCollapsed = ref(false)` — 默认展开（用户要求可见） +- 折叠动画：`max-height` + `opacity` CSS transition（非 Vue Transition，更轻量） + +--- + +### Bug 修复 🐛 + +#### longPressTimer TypeError (`useFavorites.ts:168`) +```diff +- const longPressTimer = ref | null>(null) ++ let longPressTimer = ref | null>(null) +``` +原因：`const` 声明后 `onLongPressStart` 中 `longPressTimer = setTimeout(...)` 重复赋值 + +#### Arco Tabs padding-top (`App.vue`) +```css +.arco-tabs-content { padding-top: 0; } +``` +Arco Design 默认 16px padding 导致内容偏移 + +--- + +### 核心文件变更 + +| 文件 | 类型 | 说明 | +|------|------|------| +| `main.go` | 重构 | +11 行，Middleware + DevTools | +| `build/config.yml` | 重构 | executes 流水线对齐官方模板 | +| `build/windows/Taskfile.yml` | 修改 | BUILD_FLAGS 加 devtools tag | +| `Taskfile.yml` | 新增 | 根级 dev 任务 | +| `frontend/src/components/Sidebar.vue` | 修改 | 折叠架构 + 内部滚动 | +| `frontend/src/composables/useFavorites.ts` | 修复 | const→let | +| `frontend/src/App.vue` | 修改 | Tabs padding 覆盖 | + +### 归档清理 +移动到 `.archive/` 目录（不删除）： +- `u-desk.exe`、`frontend.bak/`、`web-old/`、`greetservice.go` +- clipboard png、`package.json.md5`、v2 wailsjs bindings + +--- + ## [0.3.3] - 2026-04-13 ### 架构新增 🏗️ diff --git a/CHANGELOG.md b/CHANGELOG.md index 71449cb..71cc37a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,31 @@ # 更新日志 +## [0.5.0] - 2026-05-01 (fs-only-v3) + +### 重构 🔧 +- **Wails v3 迁移**: 从 Wails v2 升级至 v3 alpha.80，全面重构项目架构 +- **前端目录规范化**: `web/` → `frontend/`，对齐 Wails v3 标准目录结构 +- **跨平台构建配置**: 新增 Android/iOS/Linux/macOS/Docker 构建模板（Taskfile.yml） +- **v3 Bindings**: 自动生成的 TypeScript 绑定替代手动维护的 wailsjs + +### 新增 ✨ +- **Sidebar 折叠架构**: 收藏夹和帮助文档独立区块，各自支持折叠/展开 +- **帮助文档区块**: 静态快捷键参考面板，默认展示 +- **收藏夹内部滚动**: 收藏内容多时列表区域独立滚动，帮助区块固定底部不溢出 + +### 修复 🐛 +- **custom.js 404**: AssetOptions Middleware 拦截返回空响应，消除控制台报错 +- **longPressTimer TypeError**: `const` → `let` 修复重复赋值错误 +- **Arco Tabs padding**: 覆盖默认 16px padding-top +- **DevTools 可用性**: production 构建带 devtools tag + 延迟 OpenDevTools() 调用 + +### 变更说明 +- 分支: `feature/fs-only` → `fs-only-v3` +- 入口: main.go 新增 Middleware 中间件模式 +- build/config.yml executes 流水线对齐官方模板（once → background → blocking → primary） + +--- + ## [0.4.0] - 2026-04-25 ### 重构 🔧 diff --git a/README.md b/README.md index ad12c3f..1150ecb 100644 --- a/README.md +++ b/README.md @@ -1,59 +1,74 @@ -# Welcome to Your New Wails3 Project! +# U-Desk -Congratulations on generating your Wails3 application! This README will guide you through the next steps to get your project up and running. +桌面文件管理器，基于 [Wails v3](https://v3.wails.io/) (Go + Vue 3)。 -## Getting Started +## 功能 -1. Navigate to your project directory in the terminal. +- 文件浏览 / 编辑 / 预览（文本、Markdown、图片、Office、PDF） +- 收藏夹管理（折叠/展开、拖拽排序、置顶） +- Markdown 编辑器（实时预览、语法高亮、Mermaid 图表） +- 远程文件服务器连接 +- 主题切换（亮色/暗色） +- 版本更新检查 -2. To run your application in development mode, use the following command: +## 技术栈 - ``` - wails3 dev - ``` +| 层 | 技术 | +|---|------| +| 桌面框架 | Wails v3 (alpha.80) | +| 后端 | Go 1.22+ | +| 前端 | Vue 3 + TypeScript | +| UI 组件库 | Arco Design Vue | +| 编辑器 | CodeMirror 6 | +| 构建 | Vite 7 + Taskfile | - This will start your application and enable hot-reloading for both frontend and backend changes. +## 项目结构 -3. To build your application for production, use: +``` +├── main.go # 入口：窗口配置、中间件、DevTools +├── app.go # 应用逻辑：文件系统、更新检查等 +├── internal/ # 内部模块 +│ ├── filesystem/ # 文件操作、锁、预览服务 +│ └── api/ # API 处理器 +├── frontend/ # 前端代码 (Vue 3) +│ ├── src/ +│ │ ├── components/FileSystem/ # 文件管理主组件 +│ │ ├── stores/ # Pinia 状态管理 +│ │ ├── api/ # 后端调用封装 +│ │ └── utils/ # 工具函数 +│ └── vite.config.js +├── build/ # 构建配置（跨平台） +│ ├── config.yml # Wails 项目配置 +│ └── windows/ # Windows 构建脚本 +└── configs/ # 运行时配置 +``` - ``` - wails3 build - ``` +## 开发 - This will create a production-ready executable in the `build` directory. +```bash +# 安装依赖 +wails3 task common:install:frontend:deps -## Exploring Wails3 Features +# 启动开发模式（热重载） +wails3 dev -Now that you have your project set up, it's time to explore the features that Wails3 offers: +# 生产构建 +wails3 build +``` -1. **Check out the examples**: The best way to learn is by example. Visit the `examples` directory in the `v3/examples` directory to see various sample applications. +### 构建标签 -2. **Run an example**: To run any of the examples, navigate to the example's directory and use: +- `production` — 生产模式，使用嵌入的 frontend dist +- `devtools` — 在生产构建中保留 DevTools（F12） - ``` - go run . - ``` +## 快捷键 - Note: Some examples may be under development during the alpha phase. +| 快捷键 | 功能 | +|--------|------| +| Ctrl+B | 切换侧边栏 | +| Ctrl+H | 历史记录 | +| Ctrl+F | 聚焦搜索 | -3. **Explore the documentation**: Visit the [Wails3 documentation](https://v3.wails.io/) for in-depth guides and API references. +## 版本历史 -4. **Join the community**: Have questions or want to share your progress? Join the [Wails Discord](https://discord.gg/JDdSxwjhGf) or visit the [Wails discussions on GitHub](https://github.com/wailsapp/wails/discussions). - -## Project Structure - -Take a moment to familiarize yourself with your project structure: - -- `frontend/`: Contains your frontend code (HTML, CSS, JavaScript/TypeScript) -- `main.go`: The entry point of your Go backend -- `app.go`: Define your application structure and methods here -- `wails.json`: Configuration file for your Wails project - -## Next Steps - -1. Modify the frontend in the `frontend/` directory to create your desired UI. -2. Add backend functionality in `main.go`. -3. Use `wails3 dev` to see your changes in real-time. -4. When ready, build your application with `wails3 build`. - -Happy coding with Wails3! If you encounter any issues or have questions, don't hesitate to consult the documentation or reach out to the Wails community. +详见 [CHANGELOG.md](./CHANGELOG.md) diff --git a/build/publish/last-version.json b/build/publish/last-version.json deleted file mode 100644 index 37afd4a..0000000 --- a/build/publish/last-version.json +++ /dev/null @@ -1 +0,0 @@ -{"version": "0.4.0", "download_url": "https://c.1216.top/download/u-desk-0.4.0.exe", "changelog": "### 重构 🔧\n- 移除数据库客户端模块：删除全部 MySQL/Redis/MongoDB 相关代码（-17,885 行），应用专注文件管理\n- 清理依赖：移除 mysql/redis/mongo 驱动依赖\n- 构建体积优化：原始 exe 26MB，UPX 压缩后 7.5MB（压缩率 28.8%）\n\n### 变更说明\n- 顶部 Tab 仅保留「文件管理」，移除数据库入口\n- Markdown 编辑器、版本历史、系统信息、更新检查等模块不受影响", "force_update": false, "release_date": "2026-04-25", "file_size": 7766016} \ No newline at end of file diff --git a/build/publish/versions.json b/build/publish/versions.json deleted file mode 100644 index 3f4cc6d..0000000 --- a/build/publish/versions.json +++ /dev/null @@ -1 +0,0 @@ -{"updated_at": "2026-04-25T23:58:00+08:00", "versions": [{"version": "0.4.0", "release_date": "2026-04-25", "changelog": "### 重构 🔧\n- **移除数据库客户端模块**: 删除全部 MySQL/Redis/MongoDB 相关代码（-17,885 行），应用专注文件管理\n- **清理依赖**: 移除 go-sql-driver/mysql、go-redis/v9、mongo-driver/v2、gorm.io/driver/mysql 等驱动依赖\n- **构建体积优化**: 原始 exe 从 36MB 降至 26MB，UPX 压缩后仅 7.5MB（压缩率 28.8%）\n\n### 变更说明\n- 顶部 Tab 仅保留「文件管理」，移除数据库入口\n- Markdown 编辑器、版本历史、系统信息、更新检查等模块不受影响\n- 本地 SQLite 配置存储（AppConfig）保留不变", "download_url": "https://c.1216.top/download/u-desk-0.4.0.exe", "file_size": 7766016, "sha256": "532c30bdc57ea0ff5bc71756714b7ca18388ad3e09b2c4eefcdb6816349c7dda"}, {"version": "0.3.3", "release_date": "2026-04-13", "changelog": "### 新增 ✨\n- **Markdown 编辑器**: 独立编辑页面、实时预览、字符/行数统计、Ctrl+S 保存、自动保存\n- **Markdown 文件页面**: 独立的 Markdown 文件查看与编辑界面\n- **PDF 导出**: 浏览器打印 + 后端 gofpdf/chromedp 多种导出方式\n- **窗口置顶**: 支持窗口始终置顶\n- **收藏夹置顶**: 收藏项支持置顶排序\n- **文件预览**: Excel/Word 文件预览支持\n- **数据库 UI 大幅改进**: 查询历史面板、查询模板面板、SQL 工具栏、结果导出(CSV)、SQL 格式化器\n- **数据库可见性过滤**: 连接管理增强、ConnectionForm 重写、统一错误处理模块\n\n### 优化 🚀\n- MySQL 动态连接池重构 — 健康检查、性能权重、自适应扩缩容\n- SQL 查询优化器 — 查询缓存、慢查询日志 (762 行)\n- Redis Pipeline — 批量命令、事务 MULTI/EXEC 支持\n- Wails 框架升级 + Mermaid 主题切换 + 代码高亮修复\n- FileListPanel 重写 (+511 行) — 删除 FileItemRow，统一列表渲染逻辑\n- CSV 编辑模式优化 + PDF 导出重构\n- 拷贝功能优化 — 新增 ClipboardCopy composable\n\n### 修复 🐛\n- Office 文件预览：修复类型检测与二进制误判\n- 本地文件服务器 CORS 跨域问题\n- 大文件点击卡死问题\n- 收藏夹 bug 修复\n\n### 安全修复 🔒\n- XSS 防护（PdfExportButton、MarkdownPreview HTML 消毒）\n- PDF 导出路径穿越防护\n- PDF 导出标题 HTML 注入防护\n\n### 重构 🔧\n- CodeMirror 架构优化 — 统一导出避免多实例问题\n- 消除代码重复 — storage/connection_service 重构\n- **大规模死代码清理 (-1306 行)**: 删除废弃 storage 层、audit_log、file_lock、recycle_bin、useFileEdit.js(-369行)、useFilePreview.js(-603行) 等\n- 配置加载超时保护、正则表达式预编译、禁止 Ctrl+滚轮缩放", "download_url": "https://c.1216.top/download/u-desk-0.3.3.exe", "file_size": 9801728, "sha256": "829c79a91c10277011159749110f4ebee5e3638a078e86850c03b1c9f09e184c"}, {"version": "0.3.2", "release_date": "2026-02-05", "changelog": "### 重构 🔧\n- CodeMirror 架构优化 - 统一导出避免多实例问题\n- 语言加载器优化 - 从动态 import 改为静态导入\n- 动态主题切换 - 使用 Compartment 实现无损切换\n\n### 优化 🚀\n- 编辑器性能 - 添加内容更新防抖\n- 亮色主题 - 改进代码编辑器亮色模式样式", "download_url": "", "file_size": 0, "sha256": ""}, {"version": "0.3.0", "release_date": "2026-02-04", "changelog": "### 新增 ✨\n- Markdown 图表支持 - Mermaid 流程图、时序图、类图等\n- 代码语法高亮 - 支持 20+ 种常用编程语言\n- 文件列表优化 - 文件夹优先显示，同类型按名称排序", "download_url": "", "file_size": 0, "sha256": ""}, {"version": "0.2.0", "release_date": "2026-01-28", "changelog": "### 新增 ✨\n- 应用配置管理 - 全新设置面板，支持自定义显示模块和默认启动页\n- 智能更新提醒 - 新增版本更新通知组件\n- 模块重命名 - 应用更名为 u-desk", "download_url": "", "file_size": 0, "sha256": ""}, {"version": "0.1.5", "release_date": "2026-01-22", "changelog": "### 新增 ✨\n- 文件管理模块 - 文件浏览、编辑、操作功能\n- 版本更新管理 - 自动检查和下载更新\n- 系统信息查询 - CPU、内存、磁盘等硬件信息", "download_url": "", "file_size": 0, "sha256": ""}, {"version": "0.1.0", "release_date": "2026-01-18", "changelog": "### 新增 ✨\n- 数据库管理 - 支持多种数据库连接和查询功能", "download_url": "", "file_size": 0, "sha256": ""}]} \ No newline at end of file diff --git a/docs/01-技术文档/CodeMirror/CodeEditor-优化报告.md b/docs/01-技术文档/CodeMirror/CodeEditor-优化报告.md new file mode 100644 index 0000000..ac5aa1f --- /dev/null +++ b/docs/01-技术文档/CodeMirror/CodeEditor-优化报告.md @@ -0,0 +1,234 @@ +# CodeEditor 优化完成报告 + +> **日期**: 2026-02-05 +> **组件**: CodeEditor.vue +> **优化内容**: 性能、用户体验、代码质量 + +--- + +## ✅ 完成的优化 + +### 1. 🔴 使用 Compartment 重构主题切换（P0） + +**问题**：之前每次切换主题都重建整个编辑器，导致闪烁和状态丢失 + +**解决方案**： +```javascript +import { Compartment } from '@codemirror/state' + +const themeCompartment = new Compartment() +const languageCompartment = new Compartment() + +// 动态切换主题（不丢失状态） +watch(isDark, () => { + view.dispatch({ + effects: themeCompartment.reconfigure(getThemeExtension()) + }) +}) +``` + +**效果**： +- ✅ 主题切换流畅，无闪烁 +- ✅ 保留滚动位置和光标位置 +- ✅ CodeEditor.js 从 6.24 kB 减小到 2.94 kB（减小 53%） + +--- + +### 2. 🟡 修复 TypeScript 语言配置（P1） + +**问题**：TypeScript 文件使用 `{ jsx: true }` 而非 `{ typescript: true }` + +**修复**： +```javascript +// 修复前 +typescript: ['@codemirror/lang-javascript', 'javascript', { jsx: true }] + +// 修复后 +typescript: ['@codemirror/lang-javascript', 'javascript', { + typescript: true, + jsx: true +}] +``` + +**效果**： +- ✅ TypeScript 语法高亮正确 +- ✅ TSX 文件也支持 + +--- + +### 3. 🟡 添加常用语言预加载（P1） + +**实现**：在 App.vue 的 onMounted 中调用 +```javascript +import { preloadCommonLanguages } from './utils/codeMirrorLoader' + +onMounted(() => { + preloadCommonLanguages() // 预加载 js, json, md, python, sql +}) +``` + +**效果**： +- ✅ 打开常用文件（js、json、md）时瞬间加载 +- ✅ 提升用户体验 + +--- + +### 4. 🟡 添加内容更新防抖（P2） + +**问题**：每次输入都触发 emit，可能影响性能 + +**解决方案**： +```javascript +let emitTimeout = null +const debouncedEmit = (value) => { + if (emitTimeout) clearTimeout(emitTimeout) + emitTimeout = setTimeout(() => { + emit('update:modelValue', value) + }, 150) // 150ms 防抖 +} +``` + +**效果**： +- ✅ 减少不必要的更新 +- ✅ 提升打字性能 + +--- + +### 5. 🟢 补充语法标签（P3） + +**新增标签**： +```javascript +{ tag: tags.definition(tags.name), color: '#22863a' }, +{ tag: tags.typeName, color: '#22863a' }, +{ tag: tags.self, color: '#005cc5' }, +{ tag: tags.special(tags.variableName), color: '#005cc5' }, +{ tag: tags.modifier, color: '#d73a49' }, +{ tag: tags.regexp, color: '#032f62' } +``` + +**效果**： +- ✅ 高亮更完整 +- ✅ 支持更多语法结构 + +--- + +### 6. 🟢 改进错误处理（P3） + +**实现**： +```javascript +try { + const langExtension = await loadLanguageExtension(language) + if (langExtension) { + view.dispatch({ + effects: languageCompartment.reconfigure(langExtension) + }) + } +} catch (error) { + console.warn(`[CodeEditor] 加载语言包失败: ${language}`, error) +} +``` + +**效果**： +- ✅ 语言加载失败时不影响编辑器使用 +- ✅ 降级到纯文本模式 + +--- + +## 📊 性能对比 + +| 指标 | 优化前 | 优化后 | 改进 | +|------|--------|--------|------| +| CodeEditor.js 大小 | 6.24 kB | 2.94 kB | **↓ 53%** | +| 主题切换时间 | 100ms+ (重建) | ~10ms (reconfigure) | **↑ 10倍** | +| 首次语言加载 | 同步加载 | 异步预加载 | **瞬间** | +| 输入防抖 | 无 | 150ms | **性能提升** | + +--- + +## 🏗️ 架构改进 + +### 代码组织 + +**优化前**： +```javascript +// 混乱的监听器 +watch([isDark, () => props.fileExtension], async () => { + await nextTick() + await recreateEditor() // 重建整个编辑器 +}) +``` + +**优化后**： +```javascript +// 清晰的职责分离 +const themeCompartment = new Compartment() // 主题隔离 +const languageCompartment = new Compartment() // 语言隔离 + +// 独立的监听器 +watch(isDark, () => { /* 只切换主题 */ }) +watch(() => props.fileExtension, () => { /* 只加载语言 */ }) +``` + +--- + +## 📝 代码注释 + +添加了清晰的分段注释： +```javascript +// ==================== 主题定义 ==================== +// ==================== Props & Emits ==================== +// ==================== 状态管理 ==================== +// ==================== 防抖处理 ==================== +// ==================== 扩展配置 ==================== +// ==================== 编辑器创建 ==================== +// ==================== 语言管理 ==================== +// ==================== 生命周期 ==================== +// ==================== 监听器 ==================== +``` + +--- + +## 🎯 符合最佳实践 + +根据 [CodeMirror 6 文档](./CodeMirror-6-编辑器文档.md)： + +✅ **使用 Compartment 动态切换** - 避免重建编辑器 +✅ **异步加载语言包** - 按需加载，减少初始体积 +✅ **语言缓存机制** - 避免重复加载 +✅ **防抖更新** - 提升性能 +✅ **完整的语法标签** - 更好的高亮效果 +✅ **错误边界** - 优雅降级 + +--- + +## 🔄 后续建议 + +### 短期（可选） +- [ ] 添加代码折叠功能 +- [ ] 添加括号匹配高亮 +- [ ] 支持多光标编辑 + +### 中期（可选） +- [ ] 集成 LSP（语言服务器协议） +- [ ] 添加自动补全 +- [ ] 添加代码片段支持 + +### 长期（可选） +- [ ] 支持协同编辑 +- [ ] 添加 diff 模式 +- [ ] 支持 Vim 模式 + +--- + +## 📚 相关文件 + +- `frontend/src/components/CodeEditor.vue` - 主编辑器组件 +- `frontend/src/utils/codeMirrorLoader.js` - 语言包加载器 +- `frontend/src/App.vue` - 添加预加载调用 +- `docs/CodeMirror-6-编辑器文档.md` - 完整技术文档 + +--- + +**优化完成时间**: 2026-02-05 +**构建状态**: ✅ 成功 +**测试状态**: 待测试 diff --git a/docs/01-技术文档/CodeMirror/CodeMirror-6-编辑器文档.md b/docs/01-技术文档/CodeMirror/CodeMirror-6-编辑器文档.md new file mode 100644 index 0000000..8d9ec06 --- /dev/null +++ b/docs/01-技术文档/CodeMirror/CodeMirror-6-编辑器文档.md @@ -0,0 +1,687 @@ +# CodeMirror 6 编辑器文档 + +> **项目**: U-Desk +> **组件**: CodeEditor.vue +> **更新日期**: 2026-02-05 +> **维护者**: 开发团队 + +--- + +## 📚 目录 + +- [简介](#简介) +- [版本信息](#版本信息) +- [核心架构](#核心架构) +- [主题系统](#主题系统) +- [语言支持](#语言支持) +- [API 参考](#api-参考) +- [最佳实践](#最佳实践) +- [常见问题](#常见问题) +- [升级指南](#升级指南) +- [参考资料](#参考资料) + +--- + +## 简介 + +### 什么是 CodeMirror 6？ + +CodeMirror 6 是一个**基于 TypeScript 重写的现代代码编辑器**，采用模块化架构，提供： + +- 🚀 **高性能**: 比 v5 快 40%，内存少 35% +- 📦 **模块化**: 只加载需要的功能 +- 🎨 **可定制**: 灵活的主题和扩展系统 +- 🔍 **准确**: 基于 Lezer 的语法解析 +- 💪 **类型安全**: 完整的 TypeScript 支持 + +### 为什么选择 CodeMirror 6？ + +| 特性 | CodeMirror 6 | Monaco (VS Code) | Ace | +|------|--------------|------------------|-----| +| 包体积 | ~50KB (gzip) | ~2MB | ~300KB | +| TypeScript | ✅ 原生支持 | ✅ 支持 | ⚠️ 部分 | +| 模块化 | ✅ 高度模块化 | ❌ 单体 | ⚠️ 中等 | +| 性能 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ | +| 移动端 | ✅ 良好支持 | ⚠️ 一般 | ⚠️ 一般 | + +--- + +## 版本信息 + +### 当前使用的版本 + +```json +{ + "@codemirror/view": "6.39.8", + "@codemirror/state": "6.5.3", + "@codemirror/language": "6.12.1", + "@codemirror/commands": "6.10.1", + "@codemirror/highlight": "0.19.8", + "@codemirror/theme-one-dark": "6.1.3", + "@codemirror/lang-javascript": "6.2.4", + "@codemirror/lang-python": "6.2.1", + "@codemirror/lang-go": "6.0.1", + "@codemirror/lang-json": "6.0.2", + "@codemirror/legacy-modes": "6.5.2" +} +``` + +### 最新版本（2026-02） + +- **@codemirror/view**: 6.39.12 (2026-01-30) +- **@codemirror/state**: 6.5.3 (当前版本) +- **@codemirror/language**: 6.12.1 (当前版本) + +> 注：我们的版本略旧但稳定，建议在下次迭代时更新 + +--- + +## 核心架构 + +### 包结构 + +``` +@codemirror/ +├── view/ # 编辑器视图和 DOM 交互 +├── state/ # 编辑器状态和事务 +├── language/ # 语言支持和高亮 +├── commands/ # 内置命令 +├── search/ # 搜索和替换 +├── autocomplete/ # 自动补全 +├── lint/ # 代码检查 +├── lang-*/ # 语言包 +└── legacy-modes/ # 旧版语言模式 +``` + +### 核心概念 + +#### 1. EditorState（状态） + +编辑器的不可变状态，包含文档内容： + +```javascript +import { EditorState } from '@codemirror/state' + +const state = EditorState.create({ + doc: 'console.log("Hello, World!")', + extensions: [/* ... */] +}) +``` + +#### 2. EditorView（视图） + +编辑器的 UI 表示： + +```javascript +import { EditorView } from '@codemirror/view' + +const view = new EditorView({ + state: state, + parent: document.body +}) +``` + +#### 3. Extensions（扩展） + +配置编辑器功能的核心机制： + +```javascript +const extensions = [ + lineNumbers(), // 显示行号 + highlightActiveLine(), // 高亮当前行 + history(), // 撤销/重做 + keymap.of(defaultKeymap) // 键盘映射 +] +``` + +--- + +## 主题系统 + +### 主题构成 + +CodeMirror 6 的主题由两部分组成： + +1. **基础样式** (`EditorView.theme`) - UI 元素样式 +2. **高亮样式** (`HighlightStyle.define`) - 语法高亮颜色 + +### 暗色主题（One Dark） + +```javascript +import { oneDark } from '@codemirror/theme-one-dark' + +// 直接使用 +extensions.push(oneDark) +``` + +### 亮色主题（自定义） + +```javascript +import { HighlightStyle } from '@codemirror/language' +import { tags } from '@lezer/highlight' + +// 1. 定义语法高亮样式 +const lightHighlightStyle = HighlightStyle.define([ + { tag: tags.keyword, color: '#d73a49', fontWeight: 'bold' }, + { tag: tags.string, color: '#032f62' }, + { tag: tags.number, color: '#005cc5' }, + { tag: tags.comment, color: '#6a737d', fontStyle: 'italic' }, + { tag: tags.function(tags.variableName), color: '#6f42c1' }, + { tag: tags.className, color: '#22863a' }, + { tag: tags.propertyName, color: '#e36209' }, + { tag: tags.variableName, color: '#005cc5' } +]) + +// 2. 定义基础主题样式 +const lightTheme = EditorView.theme({ + '&': { backgroundColor: '#ffffff' }, + '.cm-gutters': { backgroundColor: '#f7f7f7', color: '#999' }, + '.cm-line': { caretColor: '#000' }, + '.cm-selection': { backgroundColor: '#d9d9d9' } +}) + +// 3. 应用主题 +extensions.push(lightTheme, lightHighlightStyle) +``` + +### 主题切换 + +```javascript +import { Compartment } from '@codemirror/state' + +// 创建主题隔离区 +const themeCompartment = new Compartment() + +// 初始化 +const view = new EditorView({ + extensions: [ + themeCompartment.of(oneDark) // 初始主题 + ] +}) + +// 切换主题 +function switchTheme(isDark) { + view.dispatch({ + effects: themeCompartment.reconfigure( + isDark ? oneDark : lightTheme + ) + }) +} +``` + +### 可用的标签（Tags） + +```javascript +import { tags } from '@lezer/highlight' + +// 基础标签 +tags.keyword // 关键字 (const, var, function) +tags.string // 字符串 +tags.number // 数字 +tags.comment // 注释 +tags.variableName // 变量名 +tags.function // 函数 +tags.className // 类名 +tags.propertyName // 属性名 +tags.operator // 操作符 +tags.tagName // HTML/XML 标签 +tags.attributeName // 属性名 +tags.bool // 布尔值 +tags.null // null 值 + +// 组合标签 +tags.function(tags.variableName) // 函数调用的变量名 +tags.definition(tags.name) // 定义时的名称 +``` + +--- + +## 语言支持 + +### 现代语言包 + +支持 30+ 编程语言，动态加载： + +```javascript +// JavaScript/TypeScript +import { javascript } from '@codemirror/lang-javascript' +javascript({ jsx: true, typescript: true }) + +// Python +import { python } from '@codemirror/lang-python' +python() + +// Go +import { go } from '@codemirror/lang-go' +go() + +// JSON +import { json } from '@codemirror/lang-json' +json() + +// Markdown +import { markdown } from '@codemirror/lang-markdown' +markdown({ codeLanguages: languages }) +``` + +### Legacy 语言包 + +通过 StreamLanguage 包装旧模式： + +```javascript +import { StreamLanguage } from '@codemirror/language' +import { ruby } from '@codemirror/legacy-modes/mode/ruby' + +StreamLanguage.define(ruby) +``` + +### 文件扩展名映射 + +```javascript +const langMap = { + // JavaScript/TypeScript + 'js': 'javascript', 'jsx': 'javascript', + 'ts': 'typescript', 'tsx': 'typescript', + + // 样式 + 'css': 'css', 'scss': 'css', 'less': 'css', + + // 数据 + 'json': 'json', 'yaml': 'yaml', 'xml': 'xml', + + // 脚本 + 'py': 'python', 'rb': 'ruby', 'sh': 'shell', + + // 编译型 + 'go': 'go', 'rs': 'rust', 'cpp': 'cpp' +} +``` + +### 动态加载语言 + +我们的实现使用缓存和动态导入： + +```javascript +// 1. 语言缓存 +const languageCache = new Map() + +// 2. 动态导入 +export async function loadLanguageExtension(language) { + if (languageCache.has(language)) { + return languageCache.get(language) + } + + try { + // 动态导入语言包 + const mod = await import(`@codemirror/lang-${language}`) + const extension = mod[language]() + + languageCache.set(language, extension) + return extension + } catch (error) { + console.error(`加载语言包失败: ${language}`, error) + return null + } +} +``` + +--- + +## API 参考 + +### 核心属性 + +```javascript +const props = { + modelValue: String, // 编辑器内容 (v-model) + fileExtension: String // 文件扩展名 (如 'js', 'py') +} +``` + +### 核心事件 + +```javascript +const emit = { + 'update:modelValue': String // 内容变化时触发 +} +``` + +### 主要方法 + +#### createEditor(docContent) + +创建编辑器实例： + +```javascript +const createEditor = async (docContent = '') => { + const extensions = await createExtensions() + const state = EditorState.create({ + doc: docContent, + extensions + }) + view = new EditorView({ state, parent: editorContainer.value }) +} +``` + +#### recreateEditor() + +重建编辑器（切换主题/语言时）： + +```javascript +const recreateEditor = async () => { + if (!view) return + const currentDoc = view.state.doc.toString() + view.destroy() + await createEditor(currentDoc) +} +``` + +#### createExtensions() + +构建扩展配置： + +```javascript +const createExtensions = async () => { + const extensions = [ + // 基础功能 + lineNumbers(), + highlightActiveLineGutter(), + history(), + keymap.of(defaultKeymap), + bracketMatching(), + + // 事件监听 + EditorView.updateListener.of((update) => { + if (update.docChanged) { + emit('update:modelValue', update.state.doc.toString()) + } + }), + + // 自定义样式 + EditorView.theme({ /* ... */ }) + ] + + // 主题 + if (themeStore.isDark) { + extensions.push(oneDark) + } else { + extensions.push(lightTheme, lightHighlightStyle) + } + + // 语言支持 + const language = getLanguageFromExtension(props.fileExtension) + if (language !== 'text') { + const langExtension = await loadLanguageExtension(language) + if (langExtension) { + extensions.push(langExtension) + } + } + + return extensions +} +``` + +--- + +## 最佳实践 + +### 1. 使用 Compartment 动态切换 + +❌ **不好的做法**：重建整个编辑器 + +```javascript +// 每次切换都重建，性能差 +watch(language, () => { + view.destroy() + view = new EditorView({ /* ... */ }) +}) +``` + +✅ **推荐做法**：使用 Compartment + +```javascript +const languageCompartment = new Compartment() + +watch(language, async (newLang) => { + const lang = await loadLanguageExtension(newLang) + view.dispatch({ + effects: languageCompartment.reconfigure(lang) + }) +}) +``` + +### 2. 异步加载语言包 + +```javascript +// 预加载常用语言 +export async function preloadCommonLanguages() { + await Promise.all([ + 'javascript', + 'json', + 'markdown', + 'python', + 'sql' + ].map(loadLanguageExtension)) +} + +// 在应用启动时调用 +onMounted(() => { + preloadCommonLanguages() +}) +``` + +### 3. 防抖更新 + +```javascript +import { debounce } from 'lodash-es' + +const debouncedUpdate = debounce((value) => { + emit('update:modelValue', value) +}, 300) + +EditorView.updateListener.of((update) => { + if (update.docChanged) { + debouncedUpdate(update.state.doc.toString()) + } +}) +``` + +### 4. 内存管理 + +```javascript +onBeforeUnmount(() => { + // 务必销毁编辑器 + view?.destroy() + view = null +}) +``` + +### 5. 主题持久化 + +```javascript +// 从 localStorage 读取 +const savedTheme = localStorage.getItem('editor-theme') || 'dark' + +// 保存主题变化 +watch(theme, (newTheme) => { + localStorage.setItem('editor-theme', newTheme) +}) +``` + +--- + +## 常见问题 + +### Q1: 语法高亮不显示？ + +**可能原因**： +1. 语言扩展未正确加载 +2. 主题样式未配置 +3. 文件扩展名映射错误 + +**解决方案**： +```javascript +// 检查语言是否加载 +console.log('Language:', language, 'Extension:', langExtension) + +// 确保主题包含高亮样式 +extensions.push(lightHighlightStyle) +``` + +### Q2: 切换主题时编辑器闪烁？ + +**原因**：重建整个编辑器导致 + +**解决方案**：使用 Compartment +```javascript +const themeCompartment = new Compartment() + +view.dispatch({ + effects: themeCompartment.reconfigure(newTheme) +}) +``` + +### Q3: 大文件性能差？ + +**优化方案**： +```javascript +// 虚拟滚动已内置，但可以调整 +const virtualScroll = new Compartment() + +extensions.push( + virtualScroll.of({ + // 调整渲染窗口 + viewportMargin: 1000 + }) +) +``` + +### Q4: 如何添加自定义语言？ + +```javascript +// 1. 使用 Lezer 定义语法 +import { parser } from '@lezer/generator' + +// 2. 创建语言包 +import { LanguageSupport } from '@codemirror/language' + +const myLanguage = new LanguageSupport(parser) + +// 3. 使用 +extensions.push(myLanguage) +``` + +--- + +## 升级指南 + +### 从 v5 升级到 v6 + +主要变化： + +| v5 | v6 | +|----|----| +| `CodeMirror(document)` | `new EditorView({ state })` | +| `{line, ch}` 位置 | 数字偏移量 | +| `getValue()` / `setValue()` | `state.doc.toString()` / `dispatch()` | +| `setOption()` | 使用 `Compartment.reconfigure()` | + +完整迁移指南：https://codemirror.net/docs/migration/ + +### 升级步骤 + +1. **更新依赖** +```bash +npm install @codemirror/view@latest @codemirror/state@latest +``` + +2. **调整 API 调用** +```javascript +// v5 +editor.setValue('new content') + +// v6 +view.dispatch({ + changes: { + from: 0, + to: view.state.doc.length, + insert: 'new content' + } +}) +``` + +3. **更新主题系统** +```javascript +// v5: 使用 CSS 类 +editor.setOption('theme', 'my-theme') + +// v6: 使用扩展 +extensions.push(EditorView.theme({ /* ... */ })) +``` + +--- + +## 参考资料 + +### 官方文档 + +- [📖 CodeMirror 文档首页](https://codemirror.net/docs/) +- [📚 参考手册](https://codemirror.net/docs/ref/) +- [🎨 示例：样式定制](https://codemirror.net/examples/styling/) +- [⚙️ 示例：配置](https://codemirror.net/examples/config/) +- [📝 变更日志](https://www.codemirror.net/docs/changelog/) + +### 社区资源 + +- [CodeMirror 6 快速入门](https://discuss.codemirror.net/t/codemirror-6-quickstart-and-learn-by-examples/5375) +- [构建代码编辑器教程](https://davidmyers.dev/blog/how-to-build-a-code-editor-with-codemirror-6-and-typescript/introduction) +- [Material UI 集成](https://www.bayanbennett.com/posts/styling-codemirror-v6-with-material-ui-devlog-005/) +- [中文入门教程](https://segmentfault.com/a/1190000043463221) + +### 相关包 + +- [@codemirror/language-data](https://github.com/codemirror/language-data) - 文件类型检测 +- [@uiw/react-codemirror](https://www.npmjs.com/package/@uiw/react-codemirror) - React 封装 + +### 论坛讨论 + +- [优雅支持多种语言](https://discuss.codemirror.net/t/elegant-way-to-support-a-ton-of-languages/3600) +- [动态加载语法高亮](https://codemirror.net/docs/ref/#lang.StreamLanguage) +- [主题系统设计讨论](https://discuss.codemirror.net/t/styling-and-theming-design-discussion/2958) + +--- + +## 维护日志 + +### 2026-02-05 +- ✅ 修复亮色主题语法高亮问题 +- ✅ 添加自定义亮色主题支持 +- ✅ 创建完整的技术文档 + +### 未来计划 +- [ ] 升级到最新版本（6.39.12） +- [ ] 添加更多主题选项 +- [ ] 支持自定义快捷键 +- [ ] 添加代码折叠功能 +- [ ] 集成 LSP（语言服务器协议） +- [ ] 性能优化（大文件处理） + +--- + +## 相关文件 + +``` +frontend/src/ +├── components/ +│ └── CodeEditor.vue # 主编辑器组件 +├── utils/ +│ └── codeMirrorLoader.js # 语言包动态加载 +└── stores/ + └── theme.js # 主题状态管理 +``` + +--- + +**文档维护**: 开发团队 +**最后更新**: 2026-02-05 +**版本**: 1.0.0 diff --git a/docs/01-技术文档/CodeMirror/CodeMirror-修复状态报告.md b/docs/01-技术文档/CodeMirror/CodeMirror-修复状态报告.md new file mode 100644 index 0000000..527b583 --- /dev/null +++ b/docs/01-技术文档/CodeMirror/CodeMirror-修复状态报告.md @@ -0,0 +1,213 @@ +# CodeMirror 多实例问题 - 当前状态 + +**日期**: 2026-02-05 +**状态**: ✅ 已修复 + +--- + +## 🎉 修复成功 + +经过 10 次探索，**问题已成功解决**！ + +**最终方案**: 统一使用 `defaultHighlightStyle`，移除自定义高亮样式 + +--- + +## 📊 问题摘要 + +**错误**: `Unrecognized extension value in extension set` - CodeMirror 6 多实例错误 + +**影响**: 代码编辑器无法加载，语法高亮失效 + +--- + +## 🔧 已尝试的解决方案 + +| # | 方案 | 结果 | 详情 | +|---|------|------|------| +| 1 | 统一导出文件 | ❌ | codemirrorExports.js | +| 2 | manualChunks 合并 | ❌ | 反而可能导致问题 | +| 3 | 移除旧包 | ❌ | 版本不是问题 | +| 4 | 修复返回格式 | ❌ | 不是根本原因 | +| 5 | resolve.alias | ❌ | Windows 路径问题 | +| 6 | dedupe + exclude | ❌ | 主要影响开发模式 | +| 7 | 移除 manualChunks | ❌ | 即使单文件打包仍失败 | +| 8 | 深入分析错误 | ✅ | 找到真正原因 | +| 9 | **统一使用默认样式** | ✅ | **成功** | + +--- + +## ✅ 最终解决方案 + +### 方案：使用 `defaultHighlightStyle` + +**文件修改**: + +1. **CodeEditor.vue** (frontend/src/components/CodeEditor.vue) + - 移除 `HighlightStyle` 和 `tags` 导入 + - 添加 `defaultHighlightStyle` 和 `syntaxHighlighting` 导入 + - 删除 `lightHighlightStyle` 定义（22 行代码） + - 修改 `getThemeExtension()` 使用 `syntaxHighlighting(defaultHighlightStyle)` + +2. **codemirrorExports.js** (frontend/src/utils/codemirrorExports.js) + - 移除 `HighlightStyle` 和 `tags` 的导出 + +### 验证结果 + +- ✅ 生产环境构建成功（无错误） +- ✅ 开发服务器启动成功 +- ✅ 与 SqlEditor 等其他组件保持一致 + +### vite.config.js + +```javascript +export default defineConfig({ + resolve: { + alias: { '@': resolve(__dirname, 'src') }, + // 强制去重 CodeMirror 包 + dedupe: [ + '@codemirror/state', + '@codemirror/view', + '@codemirror/language', + // ... 所有 CodeMirror 和 Lezer 包 + ] + }, + build: { + rollupOptions: { + output: { + // 移除 manualChunks，让 Rollup 自动处理 + chunkFileNames: 'assets/js/[name]-[hash].js', + entryFileNames: 'assets/js/[name]-[hash].js', + assetFileNames: 'assets/[ext]/[name]-[hash].[ext]' + } + } + }, + optimizeDeps: { + include: ['vue', 'pinia', '@arco-design/web-vue', 'marked', 'highlight.js'], + // 排除 CodeMirror，避免预构建多实例 + exclude: [ + '@codemirror/state', + // ... 所有 CodeMirror 包 + ] + } +}) +``` + +### 构建结果 + +- **主包**: `index-CB_oYaZz.js` (2.5 MB) - 包含所有代码 +- **无单独的 CodeMirror chunk** - 所有 CodeMirror 代码在同一 bundle 中 + +--- + +## 📝 技术原理 + +### 真正原因 + +**之前的假设**: 多个 `@codemirror/state` 实例导致 instanceof 检查失败 + +**实际原因**: `HighlightStyle.define()` 创建的扩展对象与 `defaultHighlightStyle` 使用了不同的 `@lezer/highlight` 实例 + +### 为什么之前的方案都失败了 + +1. **统一导出文件** - 无法解决预构建阶段的多实例 +2. **manualChunks 合并** - 即使打包到单个文件仍失败 +3. **resolve.alias** - Windows 路径问题，且不能解决 `@lezer/highlight` 实例问题 +4. **移除 manualChunks** - 代码在同一 bundle 中，但 `HighlightStyle.define()` 内部使用了不同的实例 + +### 为什么最终方案成功 + +- **SqlEditor.vue** 使用 `defaultHighlightStyle` 一直正常工作 +- **CodeEditor.vue** 改用 `defaultHighlightStyle` 后也正常了 +- 官方提供的 `defaultHighlightStyle` 内部处理了实例一致性问题 + +--- + +## 📝 关于自定义样式 + +**问题**: 自定义样式不能用吗？ + +**答案**: 可以用，但需要确保实例一致性。 + +### 方案 1：使用 CSS 覆盖（推荐） + +基于默认高亮样式，通过 CSS 修改颜色： + +```css +/* 在组件的 +``` + +--- + +## 🎨 视觉层次 + +### 信息优先级 +``` +1. 操作按钮（最重要） + └> 主题色背景，白色文字 + +2. 强制更新提示（次重要） + └> 左侧橙色边框 + +3. 版本信息（一般） + └> 纯文字，左侧对齐 + +4. 更新日志（辅助） + └> 小字，灰色 +``` + +### 留白策略 +``` +区块间距：16px +元素间距：8px +文字内边距：4px + +整体感觉：紧凑但不拥挤 +``` + +--- + +## ✨ 核心价值 + +### 极简而不简陋 +- ✅ 保留所有必要信息 +- ✅ 去掉所有装饰元素 +- ✅ 专注功能本身 + +### 协调而非突出 +- ✅ 使用系统主题变量 +- ✅ 与整体风格一致 +- ✅ 不抢眼但实用 + +### 快速而非拖沓 +- ✅ 更快的动画（0.15s） +- ✅ 更小的位移（8px） +- ✅ 更紧凑的布局 + +--- + +## 📋 使用方式 + +### 立即可用 +```bash +# 前端已构建成功 +wails dev +``` + +### 预期效果 +- 应用启动后 5 秒自动检查更新 +- 发现新版本显示简约弹窗 +- 点击"立即更新"自动下载和安装 +- 安装完成后应用自动重启 + +--- + +## 🎯 最终目标达成 + +### 从"丰富"到"必要" +``` +优化前：图标+卡片+装饰+说明 +优化后：文字+按钮+功能 +``` + +### 从"突出"到"融入" +``` +优化前：鲜艳的颜色，大的间距 +优化后：系统变量，紧凑布局 +``` + +### 从"复杂"到"简单" +``` +优化前：卡片式操作区域 +优化后：标准按钮 +``` + +--- + +## 📊 简化数据 + +| 指标 | 简化前 | 简化后 | 减少 | +|------|--------|--------|------| +| 图标数量 | 6+ 个 | 1 个 | ⬇️ 83% | +| 卡片数量 | 4 个 | 1 个 | ⬇️ 75% | +| 代码行数 | 750 行 | 535 行 | ⬇️ 28% | +| 样式类数 | 20+ 个 | 10 个 | ⬇️ 50% | +| 动画时长 | 0.2s | 0.15s | ⬇️ 25% | +| 弹窗宽度 | 580px | 480px | ⬇️ 17% | + +--- + +## 🎉 总结 + +### 设计哲学 +> **Less is More** - 少即是多 + +### 核心原则 +1. **功能优先** - 保留核心功能 +2. **装饰最小化** - 去掉不必要元素 +3. **布局紧凑化** - 减少空间浪费 +4. **风格统一化** - 与系统协调 + +### 最终效果 +- ✅ 简约而不简陋 +- ✅ 紧凑而不拥挤 +- ✅ 快速而不突兀 +- ✅ 实用而不花哨 + +--- + +**简约设计完成！极简、协调、实用！** ✨ diff --git a/docs/07-项目管理/项目规划/work-plan.md b/docs/07-项目管理/项目规划/work-plan.md new file mode 100644 index 0000000..575f2c6 --- /dev/null +++ b/docs/07-项目管理/项目规划/work-plan.md @@ -0,0 +1,422 @@ +# Go Desk 项目 - 多角度审视与工作计划 + +**生成时间**: 2026-01-26 +**项目状态**: 功能开发阶段，存在技术债务 +**当前代码量**: 2590 行（重复率 59.7%） + +--- + +## 🎭 各角色角度审视 + +### 1️⃣ UX设计师视角 + +#### ✅ 做得好的地方 +- **紧凑工具栏设计**：48px高度，功能集中，符合Fitts定律 +- **渐进式披露**：收藏夹、历史记录按需显示 +- **视觉一致性**：统一的间距、字体、圆角规范 +- **交互反馈**：拖拽时有清晰的视觉提示（hover、cursor变化） + +#### ❌ 存在的问题 +1. **交互模式不一致** + - DeviceTest.vue：使用 a-card + a-row 布局（旧设计） + - FileSystem.vue：使用自定义工具栏 + 侧边栏（新设计） + - **用户困惑**：两个"文件管理"功能，操作方式完全不同 + +2. **功能发现率低** + - 侧边栏默认隐藏，用户可能不知道有收藏功能 + - 没有视觉提示引导用户发现高级功能 + +3. **缺少空状态引导** + - 首次使用时没有引导流程 + - 空文件夹的提示不够友好 + +#### 💡 UX改进建议 +- [ ] **统一交互模式**：将 FileSystem.vue 的新设计应用到 DeviceTest.vue +- [ ] **添加首次引导**：简单的tooltip或empty state引导 +- [ ] **侧边栏记忆**：记住用户是否打开了侧边栏 +- [ ] **统一操作反馈**：所有成功操作使用一致的动画效果 + +--- + +### 2️⃣ CTO视角 + +#### ❌ 技术债务问题（严重） +1. **代码重复率 59.7%** + - 439 行重复代码 + - 违反DRY原则，维护成本x2 + +2. **缺少架构分层** + - 没有统一的业务逻辑层 + - 组件直接调用API，缺少抽象 + - 状态管理散乱（localStorage到处都是） + +3. **可测试性差** + - 没有单元测试 + - 业务逻辑耦合在组件中，无法单独测试 + - 缺少类型定义，运行时错误风险高 + +4. **过度设计** + - FileSystem.vue（1374行）职责过多 + - 媒体预览功能可以独立成服务 + - 拖拽逻辑应该抽象为通用composable + +#### ✅ 技术亮点 +- API调用方式统一（有良好的基础） +- 错误处理模式一致 +- 使用了现代Vue3 Composition API + +#### 💡 架构改进建议 +- [ ] **紧急**：建立composables抽象层（减少60%重复代码） +- [ ] **本周**：统一localStorage键名管理 +- [ ] **本月**：引入TypeScript类型定义 +- [ ] **下月**：建立单元测试体系（目标70%覆盖率） + +--- + +### 3️⃣ 程序员视角 + +#### 😵 当前的痛点 +1. **改一个功能要改两个地方** + ```javascript + // 例如：修改收藏功能 + DeviceTest.vue: toggleFavorite() // 要改这里 + FileSystem.vue: toggleFavorite() // 还要改这里 + ``` + +2. **FileSystem.vue太复杂** + - 1374行，34个函数 + - 状态变量15+个，难以追踪 + - 添加新功能时容易引入bug + +3. **缺少类型提示** + - `fileList.value` 的数据结构不明确 + - 函数参数没有类型检查 + - 只能靠运行时测试发现错误 + +4. **调试困难** + - 没有日志系统 + - 错误堆栈难以追踪 + - localStorage操作失败时静默失败 + +#### 💡 开发体验改进 +- [ ] **立即**：抽取公共composables（useFileOperations, useFavoriteFiles） +- [ ] **本周**：添加ESLint规则，强制统一代码风格 +- [ ] **本月**：引入Vitest + TypeScript +- [ ] **长期**：建立错误监控和日志系统 + +--- + +### 4️⃣ 用户视角 + +#### ✅ 功能完整性 +- ✅ 历史记录（方便回溯） +- ✅ 收藏夹（快速访问） +- ✅ 拖拽调整（灵活布局） +- ✅ 文件预览（图片、视频、PDF） +- ✅ 点击即打开（流畅操作） + +#### ⚠️ 用户困惑点 +1. **两个入口做什么？** + - "文件管理"和"设备调用测试"都能操作文件 + - 功能重复，不知道该用哪个 + +2. **收藏的文件在哪里？** + - 侧边栏默认隐藏 + - 没有明确提示 + +3. **为什么有些操作不一样？** + - DeviceTest.vue：列出目录后要手动点文件名 + - FileSystem.vue：点击即打开 + +#### 💡 用户价值优化 +- [ ] **合并入口**：只保留一个"文件管理"入口 +- [ ] **简化操作**：统一"点击即打开"的交互模式 +- [ ] **功能提示**：首次使用时显示功能引导 +- [ ] **键盘快捷键**：常用操作添加快捷键支持 + +--- + +### 5️⃣ 产品经理视角 + +#### 📊 当前状态评估 +- **功能完成度**: 90% （核心功能都有） +- **用户体验**: 70% （有用但不精致） +- **技术健康度**: 50% （存在严重技术债务） +- **市场竞争力**: 65% （功能完整但体验一般） + +#### 💰 成本分析 +- **重复功能开发成本**: 高（两个相似的文件管理页面） +- **维护成本**: 高（改一个功能要改两个地方） +- **bug率**: 中等（代码重复导致同步问题） +- **新增功能成本**: 高（缺少公共抽象，每次都从零开始） + +#### 🎯 产品策略建议 +- [ ] **短期**：合并重复功能，统一用户体验 +- [ ] **中期**：偿还技术债务，提升开发效率 +- [ ] **长期**：建立差异化功能（如：批量操作、文件搜索、同步功能） + +--- + +## 📋 综合工作计划 + +基于以上分析，制定以下分阶段工作计划： + +--- + +## 🚀 第一阶段：偿还技术债务（Week 1-2） + +**优先级**: 🔴 紧急 +**目标**: 减少代码重复，建立公共抽象层 + +### Week 1: 创建公共 Composables + +#### Day 1-2: 核心 Composables +```bash +src/composables/ +├── useFileOperations.js # 文件操作逻辑（2h） +├── useFavoriteFiles.js # 收藏功能（1.5h） +├── usePathHistory.js # 历史记录（1h） +└── useLocalStorage.js # localStorage封装（1.5h) +``` + +**验收标准**: +- [ ] Composables有完整的TypeScript类型定义 +- [ ] 单元测试覆盖率>80% +- [ ] DeviceTest和FileSystem都使用这些composables + +#### Day 3-4: 工具函数和常量 +```bash +src/utils/ +├── fileUtils.js # formatBytes, getFileIcon等（1h） +└── constants.js # STORAGE_KEYS, FILE_EXTENSIONS（1h） + +src/composables/ +└── useResizable.js # 拖拽调整逻辑（1h） +``` + +**验收标准**: +- [ ] 所有常量统一管理 +- [ ] 文件类型判断逻辑只有一处 +- [ ] 工具函数有单元测试 + +### Week 2: 重构组件 + +#### Day 1-2: 重构 DeviceTest.vue +- [ ] 使用新的composables替换内联逻辑 +- [ ] 简化模板代码 +- [ ] 保持功能不变 + +**预期效果**: 738行 → 300行（减少59%） + +#### Day 3-4: 重构 FileSystem.vue +- [ ] 使用新的composables +- [ ] 抽取FilePreviewer组件 +- [ ] 简化媒体预览逻辑 + +**预期效果**: 1374行 → 500行（减少64%） + +#### Day 5: 回归测试 +- [ ] 手动测试所有功能 +- [ ] 修复重构引入的bug +- [ ] 更新文档 + +--- + +## 🎨 第二阶段：统一用户体验（Week 3-4） + +**优先级**: 🟡 高 +**目标**: 统一交互模式，提升用户体验 + +### Week 3: 统一交互设计 + +#### Day 1-2: 统一布局结构 +- [ ] DeviceTest.vue采用FileSystem.vue的工具栏设计 +- [ ] 两个页面使用相同的文件列表组件 +- [ ] 统一拖拽交互 + +#### Day 3-4: 优化用户体验 +- [ ] 添加首次使用引导 +- [ ] 优化空状态提示 +- [ ] 添加loading骨架屏 +- [ ] 统一成功/失败提示 + +### Week 4: 功能整合 + +#### Day 1-2: 合并重复入口 +- [ ] 讨论：是否合并"文件管理"和"设备调用测试" +- [ ] 如果合并：决定保留哪个，迁移功能 +- [ ] 如果不合并：明确两者定位差异 + +#### Day 3-4: 功能增强 +- [ ] 添加键盘快捷键 +- [ ] 批量操作功能 +- [ ] 文件搜索功能 +- [ ] 操作历史撤销/重做 + +--- + +## 🧪 第三阶段：质量保障（Week 5-6） + +**优先级**: 🟢 中 +**目标**: 建立测试体系，提升代码质量 + +### Week 5: 单元测试 + +#### Day 1-2: Composables测试 +```bash +tests/composables/ +├── useFileOperations.spec.js +├── useFavoriteFiles.spec.js +├── usePathHistory.spec.js +└── useLocalStorage.spec.js +``` + +**目标**: 覆盖率>80% + +#### Day 3-4: 工具函数测试 +```bash +tests/utils/ +├── fileUtils.spec.js +└── constants.spec.js +``` + +### Week 6: 集成测试和文档 + +#### Day 1-2: 组件测试 +- [ ] DeviceTest.vue快照测试 +- [ ] FileSystem.vue快照测试 +- [ ] 公共组件测试 + +#### Day 3-4: 文档和指南 +- [ ] 组件使用文档 +- [ ] Composables API文档 +- [ ] 贡献指南 + +--- + +## 🔮 第四阶段：性能优化（Week 7-8） + +**优先级**: 🟢 中 +**目标**: 优化性能，提升响应速度 + +### Week 7: 性能优化 + +#### Day 1-2: 虚拟滚动 +- [ ] 大文件列表使用虚拟滚动 +- [ ] 图片懒加载 + +#### Day 3-4: 缓存优化 +- [ ] 文件列表缓存 +- [ ] 预览内容缓存 +- [ ] 路径解析缓存 + +### Week 8: 高级功能 + +#### Day 1-2: 批量操作 +- [ ] 多选文件 +- [ ] 批量删除 +- [ ] 批量下载 + +#### Day 3-4: 搜索和过滤 +- [ ] 文件名搜索 +- [ ] 文件类型过滤 +- [ ] 大小过滤 +- [ ] 时间过滤 + +--- + +## 📊 优先级矩阵 + +根据**影响力**和**紧急程度**排序： + +| 任务 | 影响力 | 紧急度 | 优先级 | 预计工时 | +|------|--------|--------|--------|----------| +| 抽取Composables | 高 | 高 | 🔴 P0 | 16h | +| 统一常量管理 | 高 | 高 | 🔴 P0 | 4h | +| 重构DeviceTest.vue | 高 | 高 | 🔴 P0 | 8h | +| 重构FileSystem.vue | 高 | 高 | 🔴 P0 | 12h | +| 统一交互模式 | 中 | 高 | 🟡 P1 | 16h | +| 单元测试 | 中 | 中 | 🟡 P1 | 16h | +| TypeScript迁移 | 高 | 低 | 🟢 P2 | 40h | +| 性能优化 | 中 | 低 | 🟢 P2 | 16h | +| 高级功能 | 中 | 低 | 🟢 P2 | 24h | + +--- + +## 🎯 成功指标 + +### 技术指标 +- [ ] **代码复用率**: 40% → 80% +- [ ] **代码行数**: 2590 → 1500（减少42%） +- [ ] **单元测试覆盖率**: 0% → 70% +- [ ] **TypeScript覆盖率**: 0% → 100% +- [ ] **代码重复率**: 59.7% → <10% + +### 用户体验指标 +- [ ] **交互一致性**: 两个页面操作方式100%一致 +- [ ] **功能发现率**: 核心功能发现率>90% +- [ ] **首屏加载**: <1s +- [ ] **操作响应**: <200ms + +### 开发效率指标 +- [ ] **新增功能时间**: 减少60% +- [ ] **Bug修复时间**: 减少50% +- [ ] **代码审查时间**: 减少40% + +--- + +## 💡 立即行动（今天/明天） + +### 今天可以做的（2-3小时） +1. ✅ **创建 `src/utils/constants.js`**（30min） + - 统一STORAGE_KEYS管理 + - 统一FILE_EXTENSIONS定义 + +2. ✅ **创建 `src/utils/fileUtils.js`**（1h） + - formatBytes + - getFileName + - getFileIcon（简化版） + +3. ✅ **重构DeviceTest.vue使用新工具函数**（1h） + - 导入新的utils + - 删除重复代码 + - 测试功能 + +### 明天可以做的（4-6小时） +1. ✅ **创建 `src/composables/useLocalStorage.js`**（1.5h） + - 封装localStorage操作 + - 添加类型定义 + +2. ✅ **创建 `src/composables/useFileOperations.js`**（2.5h） + - 封装文件操作逻辑 + - 添加错误处理 + +3. ✅ **重构DeviceTest.vue使用composables**（2h） + - 替换内联逻辑 + - 测试功能 + +--- + +## 📝 总结 + +### 当前问题 +1. ❌ 代码重复率59.7% +2. ❌ 缺少公共抽象 +3. ❌ 交互模式不一致 +4. ❌ 缺少类型和测试 + +### 改进方向 +1. ✅ 建立composables抽象层 +2. ✅ 统一用户体验 +3. ✅ 建立测试体系 +4. ✅ 引入TypeScript + +### 预期收益 +- 代码减少42% +- 开发效率提升60% +- 维护成本降低50% +- 用户满意度提升30% + +--- + +**下一步**: 从"立即行动"开始，今天就迈出第一步！💪 diff --git a/docs/08-用户指南/GLM4.7-配置指南.md b/docs/08-用户指南/GLM4.7-配置指南.md new file mode 100644 index 0000000..f0ae7c1 --- /dev/null +++ b/docs/08-用户指南/GLM4.7-配置指南.md @@ -0,0 +1,308 @@ +# Clawdbot + GLM-4.7 快速配置 + +> **你的配置**：国内用户 + GLM Coding Plan 套餐（GLM-4.7） +> +> **通信方式**：Web 控制面板 +> +> **目标**：5 分钟完成配置 + +--- + +## 🚀 快速配置（WSL2） + +### 第 1 步：进入 WSL2 + +在 Windows PowerShell 中运行： + +```powershell +wsl +``` + +### 第 2 步：配置 GLM-4.7 + +在 WSL2 Ubuntu 终端中运行（一键复制）： + +```bash +# 配置 GLM-4.7（替换你的 API KEY） +echo 'export OPENAI_BASE_URL="https://open.bigmodel.cn/api/paas/v4/"' >> ~/.bashrc && \ +echo 'export OPENAI_API_KEY="你的GLM_API_KEY"' >> ~/.bashrc && \ +echo 'export MODEL_NAME="glm-4-plus"' >> ~/.bashrc && \ +source ~/.bashrc && \ +echo "✅ 配置完成！验证如下：" && \ +echo "BASE_URL: $OPENAI_BASE_URL" && \ +echo "API_KEY: ${OPENAI_API_KEY:0:15}..." && \ +echo "MODEL: $MODEL_NAME" +``` + +**重要**： +- 使用 `glm-4-plus` 作为模型名称（GLM-4.7 的别名） +- 如果套餐中指定了其他模型名称，按套餐说明修改 + +### 第 3 步：验证 API 连接 + +```bash +# 测试 GLM-4.7 API +curl -X POST $OPENAI_BASE_URL/chat/completions \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "glm-4-plus", + "messages": [{"role": "user", "content": "你好，请用中文回复"}] + }' +``` + +如果返回 JSON 响应包含 AI 回复，说明配置成功！✅ + +### 第 4 步：安装并启动 Clawdbot + +```bash +# 安装 Clawdbot（如果还没安装） +npm install -g clawdbot@latest + +# 启动网关（前台运行，测试用） +clawdbot gateway --port 18789 --verbose +``` + +### 第 5 步：访问 Web 界面 + +在浏览器中打开： + +``` +http://localhost:18789/ +``` + +**如果无法访问**： + +```bash +# 在 PowerShell（管理员）中运行，配置端口转发 +# 先获取 WSL2 IP +wsl hostname -I + +# 然后配置端口转发（假设 WSL2 IP 是 172.x.x.x） +netsh interface portproxy add v4tov4 listenport=18789 listenaddress=0.0.0.0 connectport=18789 connectaddress=172.x.x.x +``` + +现在访问 `http://localhost:18789/` 应该可以打开控制面板了！ + +--- + +## 🎯 GLM-4.7 套餐模型说明 + +### GLM Coding Plan 支持的模型 + +根据你的套餐类型，可以使用以下模型： + +| 模型名称 | 说明 | 适用场景 | +|---------|------|----------| +| `glm-4-plus` | GLM-4.7 旗舰版 | 复杂推理、代码生成、多模态 | +| `glm-4-flash` | 快速响应版 | 日常对话、简单任务 | +| `glm-4-air` | 高性价比版 | 生产环境 | +| `glm-4-0520` | 代码专用版 | 编程辅助 | + +**推荐配置**： +- 如果你有 **Pro/Max 套餐**：使用 `glm-4-plus` +- 如果你有 **Lite 套餐**：使用 `glm-4-flash` 或 `glm-4-air` + +### 修改模型 + +如果需要切换模型： + +```bash +# 编辑配置 +vim ~/.bashrc + +# 修改 MODEL_NAME +export MODEL_NAME="glm-4-plus" # 或其他模型 + +# 重新加载 +source ~/.bashrc + +# 重启 Clawdbot +# Ctrl+C 停止，然后重新运行 +clawdbot gateway --port 18789 +``` + +--- + +## ⚠️ GLM 套餐验证 + +### 验证是否使用套餐额度 + +**方法 1：查看控制台** + +1. 访问 [智谱AI控制台 - 套餐使用](https://open.bigmodel.cn/usercenter/billing) +2. 发送几条测试消息 +3. 查看"套餐使用情况"是否减少 + +**方法 2：使用 curl 测试** + +```bash +# 发送测试请求 +curl -X POST $OPENAI_BASE_URL/chat/completions \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "glm-4-plus", + "messages": [{"role": "user", "content": "测试"}] + }' -v + +# 查看返回的速率限制头部 +# 如果显示套餐相关的限制信息，说明使用了套餐 +``` + +### 如果消耗账户余额而非套餐 + +**原因**：Clawdbot 不在 GLM 官方支持列表中 + +**解决方案**：使用 One-API 中转 + +```bash +# 安装 One-API +docker run -d --name one-api -p 3000:3000 \ + -e TZ=Asia/Shanghai \ + -v /root/data/one-api:/data \ + ghcr.io/songquanpeng/one-api:latest + +# 访问 http://localhost:3000 +# 配置 GLM 套餐渠道 + +# 修改 Clawdbot 配置使用 One-API +export OPENAI_BASE_URL="http://localhost:3000/v1" +export OPENAI_API_KEY="sk-one-api-token" + +# 重启 Clawdbot +``` + +--- + +## 📊 GLM-4.7 性能特点 + +GLM-4.7 是智谱AI 2025 年 12 月发布的最新旗舰模型： + +- ✅ **Vibe Coding 能力**：编程能力全球开源第一 +- ✅ **200K 长上下文**：支持长文本处理 +- ✅ **多模态支持**：文本、图像、代码 +- ✅ **复杂推理**：数学、科学、逻辑问题 +- ✅ **工具调用**：Function Calling、思考模式 + +### 在 Clawdbot 中的使用场景 + +1. **代码生成**：`请帮我写一个 Python 快速排序` +2. **长文本分析**：`分析这个 100 页的 PDF 文档` +3. **复杂推理**：`如何优化这个算法的时间复杂度？` +4. **多轮对话**：保持上下文的深度讨论 +5. **工具调用**：让 AI 调用外部 API 完成任务 + +--- + +## 🔧 常用命令 + +```bash +# 启动 Clawdbot（前台） +clawdbot gateway --port 18789 --verbose + +# 启动 Clawdbot（后台） +nohup clawdbot gateway --port 18789 > ~/clawdbot.log 2>&1 & + +# 查看日志 +tail -f ~/clawdbot.log + +# 停止服务 +ps aux | grep clawdbot +kill <进程ID> + +# 查看配置 +echo $OPENAI_BASE_URL +echo $OPENAI_API_KEY +echo $MODEL_NAME + +# 测试 API +curl -X POST $OPENAI_BASE_URL/chat/completions \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"model":"glm-4-plus","messages":[{"role":"user","content":"测试"}]}' +``` + +--- + +## ❓ 常见问题 + +### Q1: 如何确认使用的是 GLM-4.7？ + +**A**: 查看日志或测试响应： + +```bash +# 启动时添加详细日志 +clawdbot gateway --port 18789 --verbose + +# 在日志中查找模型信息 +grep -i "model\|glm" ~/clawdbot.log +``` + +### Q2: 套餐额度不够用怎么办？ + +**A**: 有三个选择： + +1. **等待 5 小时**：套餐额度会自动刷新 +2. **升级套餐**：Lite → Pro → Max +3. **多账号轮换**：使用 One-API 配置多个账号 + +### Q3: GLM-4.7 和其他模型的区别？ + +**A**: + +| 特性 | GLM-4-Flash | GLM-4-Air | GLM-4-Plus (GLM-4.7) | +|------|-------------|-----------|---------------------| +| 速度 | 最快 | 快 | 中等 | +| 质量 | 基础 | 良好 | 最佳 | +| 成本 | 免费 | 低 | 中等 | +| 适用 | 测试 | 生产 | 复杂任务 | + +### Q4: Web 界面访问不了？ + +**A**: 检查防火墙和端口： + +```bash +# 检查端口是否监听 +netstat -tlnp | grep 18789 + +# 检查防火墙 +sudo ufw status + +# 如果防火墙开启，允许端口 +sudo ufw allow 18789 + +# Windows 防火墙（PowerShell 管理员） +New-NetFirewallRule -DisplayName "Clawdbot" -Direction Inbound -LocalPort 18789 -Protocol TCP -Action Allow +``` + +### Q5: 如何设置开机自启？ + +**A**: 使用 systemd 服务（前面已有完整配置） + +--- + +## 🎉 完成！ + +现在你已经成功配置了： + +- ✅ Clawdbot（在 WSL2 中运行） +- ✅ GLM-4.7（使用你的套餐） +- ✅ Web 控制面板（浏览器访问） + +**访问地址**：http://localhost:18789/ + +**开始使用**：在 Web 界面中与 GLM-4.7 对话！ + +--- + +## 📚 下一步 + +1. **测试对话**：在 Web 界面发送"你好" +2. **尝试功能**：让 AI 帮你写代码、分析文档 +3. **配置自动化**：设置定时任务、消息推送 +4. **探索高级功能**：浏览器操作、文件管理等 + +祝使用愉快！🚀 + +有问题随时问我！ diff --git a/docs/08-用户指南/README.md b/docs/08-用户指南/README.md new file mode 100644 index 0000000..f98a1f9 --- /dev/null +++ b/docs/08-用户指南/README.md @@ -0,0 +1,22 @@ +# 用户指南 + +本目录包含面向最终用户的使用文档和配置指南。 + +## 📖 文档列表 + +### 使用手册 +- [user-manual.md](./user-manual.md) - U-Desk 用户使用手册 + +### AI 配置指南 +- [GLM4.7-配置指南.md](./GLM4.7-配置指南.md) - GLM4.7 模型配置详细指南 +- [Windows-GLM4.7-配置.md](./Windows-GLM4.7-配置.md) - Windows 环境专用配置指南 +- [clawdbot安装使用.md](./clawdbot安装使用.md) - Clawdbot 安装和使用说明 +- [clawdbot国内用户配置方案.md](./clawdbot国内用户配置方案.md) - 国内用户网络配置方案 + +## 💡 使用建议 + +1. **新用户**：先阅读 [user-manual.md](./user-manual.md) 了解基本功能 +2. **配置 AI**：根据您的环境选择对应的配置指南 + - 国内用户 → [clawdbot国内用户配置方案.md](./clawdbot国内用户配置方案.md) + - Windows 用户 → [Windows-GLM4.7-配置.md](./Windows-GLM4.7-配置.md) +3. **遇到问题**：查阅对应模块的文档或提交问题 diff --git a/docs/08-用户指南/Windows-GLM4.7-配置.md b/docs/08-用户指南/Windows-GLM4.7-配置.md new file mode 100644 index 0000000..be97dcc --- /dev/null +++ b/docs/08-用户指南/Windows-GLM4.7-配置.md @@ -0,0 +1,356 @@ +# Windows + Clawdbot + GLM-4.7 配置指南 + +> **准确步骤**：从零开始，10 分钟完成配置 +> +> **你的环境**：Windows + WSL2 + GLM Coding Plan (GLM-4.7) + +--- + +## 第一步：打开 WSL2 Ubuntu + +在 Windows 中，按 `Win + R`，输入： +``` +wsl +``` + +**或者**：打开 PowerShell，输入 `wsl` 回车 + +--- + +## 第二步：配置 GLM-4.7（在 WSL2 中执行） + +### 复制以下命令，粘贴到 WSL2 终端 + +```bash +echo 'export OPENAI_BASE_URL="https://open.bigmodel.cn/api/paas/v4/"' >> ~/.bashrc && \ +echo 'export OPENAI_API_KEY="你的GLM_API_KEY"' >> ~/.bashrc && \ +echo 'export MODEL_NAME="glm-4-plus"' >> ~/.bashrc && \ +source ~/.bashrc +``` + +**重要**： +- 将 `你的GLM_API_KEY` 替换为你的真实 API Key +- 不要删除引号 + +### 验证配置 + +```bash +echo $OPENAI_BASE_URL +echo $OPENAI_API_KEY +echo $MODEL_NAME +``` + +应该显示： +- `https://open.bigmodel.cn/api/paas/v4/` +- 你的 API Key +- `glm-4-plus` + +--- + +## 第三步：安装 Node.js 22（如果还没安装） + +在 WSL2 中执行： + +```bash +curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - +sudo apt-get install -y nodejs +``` + +验证安装： +```bash +node --version +``` +应该显示：`v22.x.x` + +--- + +## 第四步：安装 Clawdbot + +在 WSL2 中执行： + +```bash +npm install -g clawdbot@latest +``` + +验证安装： +```bash +clawdbot --version +``` + +--- + +## 第五步：启动 Clawdbot + +在 WSL2 中执行： + +```bash +clawdbot gateway --port 18789 +``` + +**看到以下输出说明成功**： +``` +[INFO] Gateway starting on port 18789 +[INFO] Ready +``` + +--- + +## 第六步：访问 Web 界面 + +### 在 Windows 浏览器中打开 + +``` +http://localhost:18789/ +``` + +### 如果访问不了 + +**在 PowerShell（管理员）中执行**： + +```powershell +# 1. 获取 WSL2 IP +wsl hostname -I + +# 2. 配置端口转发（替换下面的 IP 地址） +netsh interface portproxy add v4tov4 listenport=18789 listenaddress=0.0.0.0 connectport=18789 connectaddress=172.x.x.x +``` + +再次访问 `http://localhost:18789/` + +--- + +## 第七步：测试对话 + +在 Web 界面中输入： +``` +你好 +``` + +如果收到回复，配置成功！✅ + +--- + +## 完整配置命令（复制即用） + +### 在 WSL2 中一次性执行： + +```bash +# 1. 配置 GLM-4.7（替换你的 API KEY） +echo 'export OPENAI_BASE_URL="https://open.bigmodel.cn/api/paas/v4/"' >> ~/.bashrc && \ +echo 'export OPENAI_API_KEY="你的GLM_API_KEY"' >> ~/.bashrc && \ +echo 'export MODEL_NAME="glm-4-plus"' >> ~/.bashrc && \ +source ~/.bashrc && \ + +# 2. 安装 Node.js 22（如果需要） +curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - && \ +sudo apt-get install -y nodejs && \ + +# 3. 安装 Clawdbot +npm install -g clawdbot@latest && \ + +# 4. 启动服务 +clawdbot gateway --port 18789 +``` + +--- + +## 常用操作 + +### 查看 Clawdbot 日志 + +启动时添加 `--verbose`： +```bash +clawdbot gateway --port 18789 --verbose +``` + +### 后台运行 + +```bash +nohup clawdbot gateway --port 18789 > ~/clawdbot.log 2>&1 & +``` + +查看日志： +```bash +tail -f ~/clawdbot.log +``` + +### 停止服务 + +```bash +ps aux | grep clawdbot +kill <进程ID> +``` + +### 重启服务 + +```bash +# 停止 +ps aux | grep clawdbot +kill <进程ID> + +# 启动 +clawdbot gateway --port 18789 +``` + +--- + +## 验证 GLM-4.7 连接 + +在 WSL2 中执行： + +```bash +curl -X POST https://open.bigmodel.cn/api/paas/v4/chat/completions \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "glm-4-plus", + "messages": [{"role": "user", "content": "你好"}] + }' +``` + +如果返回 JSON 包含 AI 回复，说明 API 连接正常。 + +--- + +## 配置文件位置 + +``` +~/.bashrc # 环境变量配置 +~/.clawdbot/ # Clawdbot 配置目录 + ├── config.json # 主配置文件 + └── workspace/ # 工作空间 +``` + +--- + +## 故障排查 + +### 问题 1：`node: command not found` + +**解决**：安装 Node.js 22 +```bash +curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - +sudo apt-get install -y nodejs +``` + +### 问题 2：`clawdbot: command not found` + +**解决**：安装 Clawdbot +```bash +npm install -g clawdbot@latest +``` + +### 问题 3：浏览器访问不了 `localhost:18789` + +**解决**：检查服务是否启动 +```bash +ps aux | grep clawdbot +``` + +如果没有运行，重新启动： +```bash +clawdbot gateway --port 18789 +``` + +### 问题 4：配置没生效 + +**解决**：重新加载环境变量 +```bash +source ~/.bashrc +``` + +验证配置： +```bash +echo $OPENAI_BASE_URL +echo $OPENAI_API_KEY +echo $MODEL_NAME +``` + +### 问题 5：API 返回错误 + +**检查**： +1. API Key 是否正确 +2. 网络是否正常 +3. 套餐是否有效 + +测试网络： +```bash +curl -I https://open.bigmodel.cn +``` + +--- + +## 快速检查清单 + +配置完成后，逐项检查： + +- [ ] WSL2 可以正常使用 +- [ ] `node --version` 显示 v22.x.x +- [ ] `clawdbot --version` 显示版本号 +- [ ] `echo $OPENAI_API_KEY` 显示你的 API Key +- [ ] `echo $MODEL_NAME` 显示 `glm-4-plus` +- [ ] `curl` 测试 API 返回正常 +- [ ] `clawdbot gateway` 启动成功 +- [ ] 浏览器可以访问 `http://localhost:18789/` +- [ ] Web 界面可以发送消息并收到回复 + +全部勾选 ✅ = 配置成功！ + +--- + +## 下一步 + +配置成功后，你可以： + +1. **开始对话**：在 Web 界面与 GLM-4.7 对话 +2. **尝试功能**：让 AI 帮你写代码、分析文档 +3. **设置自启**：配置开机自动启动（见下方） + +--- + +## 开机自动启动（可选） + +在 WSL2 中执行： + +```bash +# 创建 systemd 服务 +sudo cat > /etc/systemd/system/clawdbot.service << 'EOF' +[Unit] +Description=Clawdbot AI Assistant +After=network.target + +[Service] +Type=simple +User=$USER +WorkingDirectory=/home/$USER +Environment="OPENAI_BASE_URL=https://open.bigmodel.cn/api/paas/v4/" +Environment="OPENAI_API_KEY=$OPENAI_API_KEY" +Environment="MODEL_NAME=glm-4-plus" +ExecStart=/usr/bin/clawdbot gateway --port 18789 +Restart=always + +[Install] +WantedBy=multi-user.target +EOF + +# 启动服务 +sudo systemctl daemon-reload +sudo systemctl enable clawdbot +sudo systemctl start clawdbot + +# 查看状态 +sudo systemctl status clawdbot +``` + +--- + +## 完成！ + +现在你的 Windows 电脑上已经运行着： +- ✅ Clawdbot（24/7 AI 助手） +- ✅ GLM-4.7（最新旗舰模型） +- ✅ Web 界面（浏览器访问） + +**访问地址**：http://localhost:18789/ + +**开始使用吧！** 🚀 diff --git a/docs/08-用户指南/clawdbot国内用户配置方案.md b/docs/08-用户指南/clawdbot国内用户配置方案.md new file mode 100644 index 0000000..5c315b3 --- /dev/null +++ b/docs/08-用户指南/clawdbot国内用户配置方案.md @@ -0,0 +1,395 @@ +# Clawdbot 国内用户通信方案 + +> **你的情况**：国内用户 + GLM 套餐 +> +> **限制**：无法使用 WhatsApp/Telegram +> +> **解决方案**：使用 Web 界面或其他国内平台 + +--- + +## 🎯 推荐方案（按优先级） + +### 方案 1：Web 控制面板 ⭐ 最简单 + +**优点**： +- ✅ 无需额外配置 +- ✅ 直接在浏览器使用 +- ✅ 功能完整 +- ✅ 无需翻墙 + +**使用方法**： + +1. 启动 Clawdbot 网关 + ```bash + # WSL2 中运行 + clawdbot gateway --port 18789 --verbose + ``` + +2. 浏览器访问 + ``` + http://localhost:18789/ + ``` + +3. 如果配置了 Token，粘贴 Token 到设置中 + +4. 开始对话！ + +**适用场景**： +- 本地开发测试 +- 个人使用 +- 不需要移动端访问 + +--- + +### 方案 2：钉钉机器人 + +**优点**： +- ✅ 国内可用 +- ✅ 支持消息推送 +- ✅ 支持群聊和私聊 +- ✅ 企业友好 + +**配置步骤**： + +#### 1. 创建钉钉机器人 + +1. 打开钉钉电脑版 +2. 进入某个群聊 +3. 点击右上角"群设置" → "智能群助手" +4. 点击"添加机器人" → "自定义" +5. 机器人名称：`Clawdbot` +6. 安全设置：选择"自定义关键词"，输入 `AI` +7. 创建后获取 **Webhook URL** + +#### 2. 创建中转服务 + +由于 Clawdbot 原生不支持钉钉，需要创建一个简单的中转服务： + +```bash +# 创建项目目录 +mkdir ~/clawdbot-dingtalk +cd ~/clawdbot-dingtalk + +# 创建中转脚本 +cat > dingtalk-bridge.py << 'EOF' +from flask import Flask, request, jsonify +import requests +import os + +app = Flask(__name__) + +CLAWDBOT_API = os.getenv("CLAWDBOT_API", "http://localhost:18789") +WEBHOOK_URL = os.getenv("DINGTALK_WEBHOOK") + +@app.route('/dingtalk/webhook', methods=['POST']) +def dingtalk_webhook(): + data = request.json + content = data.get('text', {}).get('content', '') + + # 发送到 Clawdbot + response = requests.post(f"{CLAWDBOT_API}/api/message", json={ + "message": content + }) + + # 获取回复并发送到钉钉 + if response.status_code == 200: + reply = response.json().get('reply', '处理中...') + requests.post(WEBHOOK_URL, json={"msgtype": "text", "text": {"content": reply}}) + + return jsonify({"status": "ok"}) + +if __name__ == '__main__': + app.run(port=5000) +EOF + +# 安装依赖 +pip install flask requests + +# 配置环境变量 +echo 'export DINGTALK_WEBHOOK="你的钉钉Webhook URL"' >> ~/.bashrc +echo 'export CLAWDBOT_API="http://localhost:18789"' >> ~/.bashrc +source ~/.bashrc + +# 启动中转服务 +python dingtalk-bridge.py +``` + +#### 3. 配置钉钉机器人 Webhook + +在钉钉机器人设置中，将 Webhook URL 设置为： +``` +http://你的服务器IP:5000/dingtalk/webhook +``` + +**使用**： +在钉钉群聊中发送：`AI 你好` + +--- + +### 方案 3：飞书机器人 + +**优点**： +- ✅ 国内可用 +- ✅ 功能强大 +- ✅ 支持富文本 +- ✅ 开发友好 + +**配置步骤**： + +#### 1. 创建飞书应用 + +1. 访问 [飞书开放平台](https://open.feishu.cn/) +2. 创建企业自建应用 +3. 获取 App ID 和 App Secret +4. 启用机器人能力 + +#### 2. 配置事件订阅 + +类似于钉钉方案，需要创建中转服务接收飞书事件并转发到 Clawdbot。 + +**详细文档**：[飞书机器人开发指南](https://open.feishu.cn/document/ukTMukTMukTM/uUTNz4SN1MjL1UzM) + +--- + +### 方案 4：企业微信机器人 + +**优点**： +- ✅ 国内可用 +- ✅ 企业级 +- ✅ 安全稳定 + +**配置步骤**： + +1. 在企业微信群聊中添加机器人 +2. 获取 Webhook URL +3. 参考钉钉方案创建中转服务 + +--- + +### 方案 5：微信公众号（高级） + +**优点**： +- ✅ 随时随地使用 +- ✅ 无需翻墙 +- ✅ 用户友好 + +**缺点**： +- 需要服务器域名备案 +- 配置复杂 + +**适用场景**：需要公开服务或团队使用 + +--- + +### 方案 6：命令行 + 定时推送 + +**优点**： +- ✅ 最简单 +- ✅ 无需额外配置 +- ✅ 适合开发者 + +**使用方法**： + +```bash +# 发送消息给 Clawdbot +clawdbot message send --message "帮我分析这段代码" + +# 查看回复 +clawdbot message list +``` + +**结合定时任务**： + +```bash +# 创建定时任务脚本 +cat > ~/daily-ai-report.sh << 'EOF' +#!/bin/bash +# 每天早上 9 点生成 AI 报告 +clawdbot message send --message "生成今日工作计划" +EOF + +chmod +x ~/daily-ai-report.sh + +# 添加到 crontab +crontab -e +# 添加：0 9 * * * ~/daily-ai-report.sh +``` + +--- + +### 方案 7：浏览器扩展 + 本地服务 + +**优点**： +- ✅ 在浏览器中使用 +- ✅ 支持所有网页 +- ✅ 可视化好 + +**实现方式**： + +1. Clawdbot 提供 Web API +2. 开发简单的浏览器扩展 +3. 在任意网页上与 AI 对话 + +--- + +## 🎯 推荐配置组合 + +### 个人开发 +- **Web 控制面板**（主要） +- **命令行**（辅助） + +### 小团队 +- **Web 控制面板** +- **钉钉机器人**（团队协作） + +### 企业使用 +- **企业微信机器人** +- **飞书应用** +- **Web 控制面板**（备用） + +--- + +## 🚀 快速开始（Web 控制面板） + +这是最简单的方式，无需额外配置： + +### 第 1 步：安装 Clawdbot（WSL2） + +```bash +# 打开 WSL2 +wsl + +# 安装 Node.js 22 +curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - +sudo apt-get install -y nodejs + +# 安装 Clawdbot +npm install -g clawdbot@latest +``` + +### 第 2 步：配置 GLM + +```bash +# 配置环境变量 +echo 'export OPENAI_BASE_URL="https://open.bigmodel.cn/api/paas/v4/"' >> ~/.bashrc +echo 'export OPENAI_API_KEY="你的GLM_API_KEY"' >> ~/.bashrc +echo 'export MODEL_NAME="glm-4-flash"' >> ~/.bashrc +source ~/.bashrc +``` + +### 第 3 步：启动网关 + +```bash +# 前台运行（测试） +clawdbot gateway --port 18789 --verbose + +# 或后台运行 +nohup clawdbot gateway --port 18789 > ~/clawdbot.log 2>&1 & +``` + +### 第 4 步：访问 Web 界面 + +在浏览器中打开： + +``` +http://localhost:18789/ +``` + +**如果访问不了**： + +```bash +# 检查 WSL2 IP +ip addr show eth0 + +# 或者使用 localhost 端口转发 +# 在 PowerShell（管理员）中运行： +netsh interface portproxy add v4tov4 listenport=18789 listenaddress=0.0.0.0 connectport=18789 connectaddress=$(wsl hostname -I) +``` + +### 第 5 步：开始对话 + +在 Web 界面中输入消息，开始与 AI 对话！ + +--- + +## 💡 进阶配置 + +### 允许局域网访问 + +如果你想在手机或其他设备上访问： + +```bash +# 启动时绑定所有网卡 +clawdbot gateway --port 18789 --host 0.0.0.0 --verbose + +# 查看你的 WSL2 IP +ip addr show eth0 | grep inet +# 假设显示：inet 172.x.x.x + +# 在手机浏览器访问 +# http://172.x.x.x:18789/ +``` + +### 设置开机自启 + +```bash +# 创建 systemd 服务 +sudo cat > /etc/systemd/system/clawdbot.service << 'EOF' +[Unit] +Description=Clawdbot AI Assistant +After=network.target + +[Service] +Type=simple +User=你的用户名 +WorkingDirectory=/home/你的用户名 +Environment="OPENAI_BASE_URL=https://open.bigmodel.cn/api/paas/v4/" +Environment="OPENAI_API_KEY=你的GLM_API_KEY" +Environment="MODEL_NAME=glm-4-flash" +ExecStart=/usr/bin/clawdbot gateway --port 18789 +Restart=always + +[Install] +WantedBy=multi-user.target +EOF + +# 启动服务 +sudo systemctl daemon-reload +sudo systemctl enable clawdbot +sudo systemctl start clawdbot + +# 查看状态 +sudo systemctl status clawdbot +``` + +--- + +## 🎉 总结 + +作为国内用户，最佳方案是： + +1. **主要使用**：Web 控制面板（http://localhost:18789） +2. **团队协作**：钉钉/飞书机器人 +3. **开发者**：命令行 + Web 界面 + +**快速开始（3 分钟）**： + +```bash +# 1. 进入 WSL2 +wsl + +# 2. 配置 GLM-4.7 +echo 'export OPENAI_BASE_URL="https://open.bigmodel.cn/api/paas/v4/"' >> ~/.bashrc +echo 'export OPENAI_API_KEY="你的GLM_API_KEY"' >> ~/.bashrc +echo 'export MODEL_NAME="glm-4-plus"' >> ~/.bashrc +source ~/.bashrc + +# 3. 启动服务 +clawdbot gateway --port 18789 + +# 4. 浏览器访问 +# http://localhost:18789/ +``` + +就这么简单！有任何问题随时问我 🚀 diff --git a/docs/08-用户指南/clawdbot安装使用.md b/docs/08-用户指南/clawdbot安装使用.md new file mode 100644 index 0000000..5c94fb6 --- /dev/null +++ b/docs/08-用户指南/clawdbot安装使用.md @@ -0,0 +1,620 @@ +# Clawdbot 快速上手指南 + +> **你现在的状态**：新用户 + 已有 GLM 套餐账号 +> +> **目标**：10 分钟内完成 Clawdbot 安装并配置 GLM 套餐 + +--- + +## 📦 什么是 Clawdbot？ + +**Clawdbot** 是一个 24/7 运行的个人 AI 助手，可以： +- ✅ 在 WhatsApp、Telegram、Discord 等平台与你对话 +- ✅ 操作你的电脑（浏览器、文件系统） +- ✅ 执行任务（写代码、查资料、自动化） +- ✅ 主动给你发消息（不是被动响应） + +**简单理解**：一个长在你电脑上的 AI 助理，类似"贾维斯"。 + +--- + +## 🚀 快速安装（Windows + WSL2） + +### 步骤 1：安装 WSL2（5 分钟） + +打开 PowerShell（管理员），运行： + +```powershell +wsl --install +``` + +重启电脑，完成 Ubuntu 初始化设置。 + +### 步骤 2：安装 Node.js 22+（2 分钟） + +在 WSL2 Ubuntu 终端运行： + +```bash +curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - +sudo apt-get install -y nodejs + +# 验证 +node --version +``` + +### 步骤 3：安装 Clawdbot（1 分钟） + +```bash +# 一键安装 +curl -fsSL https://clawd.bot/install.sh | bash + +# 或使用 npm +npm install -g clawdbot@latest +``` + +### 步骤 4：配置 GLM 套餐（2 分钟） + +#### 获取你的 GLM API Key + +1. 登录 [智谱AI开放平台](https://open.bigmodel.cn/) +2. 进入控制台 → API Keys +3. 复制你的 API Key + +#### 配置环境变量 + +编辑 `~/.bashrc`： + +```bash +vim ~/.bashrc +``` + +添加以下内容： + +```bash +# GLM Coding Plan 配置 +export OPENAI_BASE_URL="https://open.bigmodel.cn/api/paas/v4/" +export OPENAI_API_KEY="你的GLM_API_KEY" +export MODEL_NAME="glm-4-flash" +``` + +保存后执行： + +```bash +source ~/.bashrc +``` + +### 步骤 5：运行向导（可选） + +```bash +clawdbot onboard --install-daemon +``` + +向导会帮你配置： +- 通信渠道（WhatsApp、Telegram 等） +- 后台服务 +- 其他设置 + +**如果你有 GLM 套餐**，向导中的认证配置可以选择跳过或手动配置。 + +--- + +## 🔥 使用 GLM 套餐的注意事项 + +### ⚠️ 重要提醒 + +**Clawdbot 不在 GLM 官方支持的工具列表中**，这意味着： + +1. **可能被识别为普通 API 调用**，消耗账户余额而非套餐额度 +2. **需要验证配置**是否正确使用套餐 + +### 验证是否使用套餐额度 + +**方法 1：查看控制台** + +1. 访问 [智谱AI控制台 - 套餐使用](https://open.bigmodel.cn/usercenter/billing) +2. 发送几条测试消息 +3. 查看"套餐使用情况"是否减少 +4. 如果"账户余额"减少，说明被识别为普通调用 + +**方法 2：使用 One-API 中转（推荐）** + +```bash +# 安装 One-API +docker run -d --name one-api -p 3000:3000 \ + -e TZ=Asia/Shanghai \ + -v /root/data/one-api:/data \ + ghcr.io/songquanpeng/one-api:latest + +# 访问 http://localhost:3000 +# 配置 GLM 套餐渠道 +# 在 Clawdbot 中使用： +export OPENAI_BASE_URL="http://localhost:3000/v1" +export OPENAI_API_KEY="sk-one-api-token" +``` + +### 套餐并发限制 + +- **Lite**：并发数 2 +- **Pro**：并发数 5 +- **Max**：并发数 7 + +如果遇到并发错误，调整配置或升级套餐。 + +--- + +## ▶️ 启动 Clawdbot + +### 方法 1：前台运行（测试用） + +```bash +clawdbot gateway --port 18789 --verbose +``` + +### 方法 2：后台服务（推荐） + +```bash +# 安装服务（如果向导中已安装可跳过） +clawdbot onboard --install-daemon + +# 启动服务 +sudo systemctl start clawdbot + +# 查看状态 +sudo systemctl status clawdbot + +# 查看日志 +journalctl -u clawdbot -f +``` + +--- + +## 🎯 开始使用 + +### 配置通信渠道 + +#### WhatsApp（推荐） + +1. 在手机上打开 WhatsApp +2. 设置 → 关联设备 +3. 扫描二维码完成登录 + +#### Telegram + +1. 在 Telegram 中搜索 [@BotFather](https://t.me/BotFather) +2. 发送 `/newbot` 创建机器人 +3. 获取 Bot Token +4. 在 Clawdbot 中配置 + +### 首次配对 + +第一条消息会收到配对代码，需要批准： + +```bash +# 批准 WhatsApp 配对 +clawdbot pairing approve whatsapp <配对代码> + +# 批准 Telegram 配对 +clawdbot pairing approve telegram <配对代码> +``` + +### 发送测试消息 + +在 WhatsApp/Telegram 中发送： + +``` +你好 +``` + +如果收到回复，配置成功！🎉 + +--- + +## 🔧 常用命令 + +```bash +# 查看状态 +clawdbot status + +# 健康检查 +clawdbot health + +# 重启服务 +sudo systemctl restart clawdbot + +# 停止服务 +sudo systemctl stop clawdbot + +# 查看完整状态 +clawdbot status --all +``` + +--- + +## ❓ 常见问题 + +### Q1: 安装失败怎么办？ + +**A**: 检查 Node.js 版本： + +```bash +node --version # 必须 >= 22 +``` + +如果版本过低，重新安装 Node.js 22。 + +### Q2: GLM 套餐不生效？ + +**A**: 按以下步骤排查： + +```bash +# 1. 检查配置 +echo $OPENAI_BASE_URL +echo $OPENAI_API_KEY +echo $MODEL_NAME + +# 2. 测试 API 连接 +curl -X POST https://open.bigmodel.cn/api/paas/v4/chat/completions \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{"model":"glm-4-flash","messages":[{"role":"user","content":"测试"}]}' + +# 3. 检查日志 +journalctl -u clawdbot -n 50 +``` + +### Q3: 服务启动失败？ + +**A**: 查看错误日志： + +```bash +journalctl -u clawdbot -n 100 +``` + +常见问题： +- 端口被占用：修改端口号 `--port 18790` +- 配置文件错误：检查 `~/.clawdbot/config.json` +- API Key 无效：重新获取并配置 + +### Q4: 如何更新 Clawdbot？ + +```bash +npm update -g clawdbot@latest +``` + +### Q5: 如何卸载？ + +```bash +# 停止服务 +sudo systemctl stop clawdbot + +# 卸载 +npm uninstall -g clawdbot + +# 删除配置 +rm -rf ~/.clawdbot +``` + +--- + +## 📚 下一步 + +### 基础使用 + +1. **对话**：在 WhatsApp/Telegram 中直接对话 +2. **任务**：让 AI 帮你写代码、查资料、分析日志 +3. **自动化**：配置定时任务、消息转发等 + +### 高级功能 + +1. **浏览器操作**：让 AI 操作浏览器完成任务 +2. **文件操作**：读取、编辑、管理文件 +3. **工具集成**：接入搜索引擎、API 等 +4. **多智能体**：配置多个 AI 代理协同工作 + +### 学习资源 + +- [Clawdbot GitHub](https://github.com/clawdbot/clawdbot) +- [官方文档](https://docs.clawd.bot/) +- [社区讨论](https://github.com/clawdbot/clawdbot/discussions) + +--- + +## 💡 使用技巧 + +### 技巧 1：高效提示词 + +❌ 坏："帮我看看这个" +✅ 好："审查这段代码的性能问题，重点关注内存泄漏和循环效率" + +### 技巧 2：利用文件系统能力 + +"读取 /var/log/app.log，分析过去 1 小时的错误模式" + +### 技巧 3：多轮对话 + +保持上下文，可以持续追问： + +``` +你：解释一下 React hooks +AI：[解释] +你：给我一个 useEffect 的例子 +AI：[代码示例] +你：这个例子中依赖数组的作用是什么？ +AI：[详细说明] +``` + +--- + +## 🎉 恭喜！ + +你已经成功安装并配置了 Clawdbot + GLM 套餐！ + +**现在可以**： +- ✅ 在 WhatsApp/Telegram 中与 AI 对话 +- ✅ 让 AI 帮你处理任务 +- ✅ 享受 GLM 套餐的高性价比 + +**下一步**： +- 探索更多功能 +- 配置自动化任务 +- 优化使用体验 + +--- + +## 📝 快速参考 + +### 配置文件位置 + +``` +~/.clawdbot/ +├── config.json # 主配置 +├── credentials/ # 凭据 +└── workspace/ # 工作空间 +``` + +### 服务管理 + +```bash +# 启动 +sudo systemctl start clawdbot + +# 停止 +sudo systemctl stop clawdbot + +# 重启 +sudo systemctl restart clawdbot + +# 状态 +sudo systemctl status clawdbot + +# 日志 +journalctl -u clawdbot -f +``` + +### GLM 套餐配置 + +```bash +# 环境变量 +export OPENAI_BASE_URL="https://open.bigmodel.cn/api/paas/v4/" +export OPENAI_API_KEY="你的API_KEY" +export MODEL_NAME="glm-4-flash" + +# 验证 +curl -X POST $OPENAI_BASE_URL/chat/completions \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{"model":"glm-4-flash","messages":[{"role":"user","content":"测试"}]}' +``` + +--- + +**祝使用愉快！** 🚀 + +有问题？查看 [常见问题](#-常见问题) 或访问 [GitHub Issues](https://github.com/clawdbot/clawdbot/issues) + +--- + +## 📌 本机配置记录 + +> **最后更新**: 2026-01-28 +> **配置环境**: Windows 11 +> **Clawdbot 版本**: 2026.1.24-3 + +### ✅ 当前运行状态 + +| 项目 | 状态 | 详情 | +|------|------|------| +| **网关状态** | 🟢 运行中 | 端口 18789 (127.0.0.1) | +| **默认模型** | GLM-4.7 | `zai/glm-4.7` | +| **工作空间** | `C:\Users\23780\clawd` | | +| **进程 PID** | 20992 | | + +### 📁 配置文件路径 + +#### 主配置目录 +``` +C:\Users\23780\.clawdbot\ +├── clawdbot.json # 主配置文件 ⭐ +├── agents\ +│ └── main\ +│ ├── agent\ +│ │ └── auth-profiles.json # 认证配置 +│ └── sessions\ +│ └── sessions.json # 会话存储 +├── credentials\ # OAuth 凭证 +├── cron\jobs.json # 定时任务 +└── devices\ # 设备配对 +``` + +#### 工作空间 +``` +C:\Users\23780\clawd\ +├── canvas\ # Canvas 文件 +├── AGENTS.md # Agent 文档 +├── BOOTSTRAP.md # 启动文档 +├── HEARTBEAT.md # 心跳任务 +├── SOUL.md # 系统提示 +├── TOOLS.md # 工具文档 +└── USER.md # 用户信息 +``` + +### 🔑 GLM-4.7 模型配置 + +#### 配置文件: `C:\Users\23780\.clawdbot\clawdbot.json` + +```json +{ + "gateway": { + "mode": "local" + }, + "env": { + "ZAI_API_KEY": "7f83dc939a60488b8cf48a2ee1c8150e.NY3aOR0qlVS8m37a" + }, + "agents": { + "defaults": { + "workspace": "C:\\Users\\23780\\clawd", + "model": { + "primary": "zai/glm-4.7" + }, + "models": { + "zai/glm-4.7": { + "alias": "GLM" + } + } + } + } +} +``` + +#### GLM 模型信息 + +| 配置项 | 值 | +|--------|-----| +| **Provider** | Z.AI (智谱) | +| **Model ID** | `zai/glm-4.7` | +| **别名** | `GLM` | +| **API Key** | `7f83dc939a60488b8cf48a2ee1c8150e.NY3aOR0qlVS8m37a` | +| **环境变量** | `ZAI_API_KEY` | +| **通用端点** | `https://api.z.ai/api/paas/v4` | +| **编程端点** | `https://api.z.ai/api/coding/paas/v4` | + +### 🚀 本机常用命令 + +#### 网关管理 +```bash +# 启动网关 +clawdbot gateway --port 18789 + +# 查看网关健康状态 +clawdbot health + +# 查看网关日志 +clawdbot logs + +# 重启网关 (Windows) +taskkill //F //PID && clawdbot gateway --port 18789 +``` + +#### 模型管理 +```bash +# 查看模型状态 +clawdbot models status + +# 列出可用模型 +clawdbot models list + +# 设置默认模型 +clawdbot models set zai/glm-4.7 +``` + +#### 诊断命令 +```bash +# 运行完整诊断 +clawdbot doctor + +# 自动修复问题 +clawdbot doctor --fix + +# 查看频道状态 +clawdbot status +``` + +#### 控制面板 +```bash +# 打开 Web 控制面板 +clawdbot dashboard +``` + +#### Agent 交互 +```bash +# 运行 Agent (本地模式) +clawdbot agent --local --message "你好" + +# 发送消息到会话 +clawdbot message send --target --message "测试消息" + +# 查看会话列表 +clawdbot sessions list +``` + +### 🛠️ 故障排查 + +#### 网关无法启动 +```bash +# 检查端口占用 +netstat -ano | grep 18789 + +# 终止占用进程 (Windows) +taskkill //F //PID + +# 查看错误日志 +clawdbot logs | tail -50 +``` + +#### 模型认证失败 +```bash +# 检查 API Key 配置 +clawdbot models status + +# 验证环境变量 +echo $ZAI_API_KEY + +# 重新配置 +clawdbot configure +``` + +### 📊 配置验证 + +```bash +# 验证模型配置 +clawdbot models status + +# 输出应包含： +# Default : zai/glm-4.7 +# Aliases (1) : GLM -> zai/glm-4.7 +# Auth overview : zai effective=env:7f83dc93...lVS8m37a + +# 验证网关健康 +clawdbot health + +# 输出应包含： +# Agents: main (default) +# Heartbeat interval: 30m (main) +``` + +### 📚 参考资源 + +#### 官方文档 +- [Configuration - Clawdbot](https://docs.clawd.bot/gateway/configuration) +- [Clawdbot GitHub](https://github.com/clawdbot/clawdbot) + +#### 中文指南 +- [主权个人必看的Clawdbot 模型配置完全指南（2026版）](https://brave2049.com/groups/artificial-intelligence-learning/forum/discussion/zhu-quan-ge-ren-bi-kan-de-clawdbot-mo-xing-pei-zhi-wan-quan-zhi-nan-2026-ban/) +- [Clawdbot 完整配置指南](https://zhuanlan.zhihu.com/p/1999437992549447616) + +#### 模型提供商 +- [Z.AI (智谱AI)](https://open.bigmodel.cn/) +- [GLM-4.7 文档](https://open.bigmodel.cn/dev/howuse/model) + +--- + +**提示**: 本节记录了本机 Clawdbot 的实际配置，定期更新以保持同步。 diff --git a/docs/08-用户指南/clipboard_20260413_234653.png b/docs/08-用户指南/clipboard_20260413_234653.png new file mode 100644 index 0000000..e2d96c9 Binary files /dev/null and b/docs/08-用户指南/clipboard_20260413_234653.png differ diff --git a/docs/08-用户指南/clipboard_20260413_235902.png b/docs/08-用户指南/clipboard_20260413_235902.png new file mode 100644 index 0000000..7281e03 Binary files /dev/null and b/docs/08-用户指南/clipboard_20260413_235902.png differ diff --git a/docs/08-用户指南/clipboard_20260414_000648.png b/docs/08-用户指南/clipboard_20260414_000648.png new file mode 100644 index 0000000..dcaec0f Binary files /dev/null and b/docs/08-用户指南/clipboard_20260414_000648.png differ diff --git a/docs/08-用户指南/clipboard_20260414_004920.png b/docs/08-用户指南/clipboard_20260414_004920.png new file mode 100644 index 0000000..3d4e38e Binary files /dev/null and b/docs/08-用户指南/clipboard_20260414_004920.png differ diff --git a/docs/08-用户指南/clipboard_20260414_010212.png b/docs/08-用户指南/clipboard_20260414_010212.png new file mode 100644 index 0000000..58a6e39 Binary files /dev/null and b/docs/08-用户指南/clipboard_20260414_010212.png differ diff --git a/docs/08-用户指南/user-manual.md b/docs/08-用户指南/user-manual.md new file mode 100644 index 0000000..9c75a99 --- /dev/null +++ b/docs/08-用户指南/user-manual.md @@ -0,0 +1,292 @@ +# U-Desk 使用手册 + +> 轻量级桌面工具集 - 数据库管理 | 文件管理 | 设备测试 + +--- + +## 📖 快速开始 + +| 操作 | 说明 | +|------|------| +| **启动应用** | 双击 `u-desk.exe` | +| **默认界面** | 数据库、文件管理、设备调用测试 | +| **打开设置** | 点击右上角 ⚙️ 按钮 | +| **拖动窗口** | 按住标题栏 "U-Desk" 文字区域 | + +--- + +## 💾 数据库管理 + +### 界面布局 + +``` +┌──────────────┬──────────────────────────────┐ +│ 连接树 │ SQL 编辑器 │ +│ │ ───────────── │ +│ ▼ 连接1 │ SELECT * FROM users... │ +│ 📋 表1 │ │ +│ 📋 表2 │ ───────────── │ +│ │ 结果区域 │ +│ ▼ 连接2 │ ┌───┬────┬────┐ │ +│ │ │id │name│ age│ │ +│ │ ├───┼────┼────┤ │ +│ │ │ 1 │Tom │ 20 │ │ +│ │ └───┴────┴────┘ │ +└──────────────┴──────────────────────────────┘ +``` + +### 常用操作 + +#### 添加数据库连接 + +1. 点击连接树顶部的 **+ 新建连接** +2. 填写连接信息 + +| 字段 | 说明 | +|------|------| +| 类型 | MySQL / PostgreSQL / SQLite / MongoDB / Redis | +| 主机 | `localhost` 或服务器 IP | +| 端口 | MySQL 默认 `3306`，PostgreSQL 默认 `5432` | +| 用户名/密码 | 数据库登录信息 | +| 数据库名 | SQLite 填文件路径 | + +3. 点击 **测试连接** 验证 +4. 点击 **保存** + +#### 查询数据 + +``` +展开连接 → 点击表名 → 自动生成SQL → 执行（Ctrl + Enter） +``` + +#### 查看表结构 + +``` +右键表名 → 查看结构 → 切换到"结构"标签页 +``` + +#### 修改表结构 + +``` +编辑模式 → 修改字段/索引 → 保存 → 预览SQL → 确认执行 +``` + +#### 查看历史 + +``` +点击"历史"标签页 → 查看所有执行过的SQL +``` + +--- + +## 📁 文件管理 + +### 界面布局 + +``` +┌─────────────────────────────────────────┐ +│ 路径框 [快捷访问▼] [历史▼] [刷新] [☰] │ +├──────┬────────────┬────────────────────┤ +│收藏夹│ 文件列表 │ 文件内容 │ +└──────┴────────────┴────────────────────┘ +``` + +### 导航操作 + +| 方式 | 操作 | +|------|------| +| **输入路径** | 在路径框输入（如 `C:\Users\Documents`），按回车 | +| **快捷访问** | 点击按钮选择：桌面、文档、下载、图片 | +| **历史记录** | 查看最近访问的 10 个路径 | + +### 文件操作 + +| 操作 | 方法 | +|------|------| +| **查看文件** | 单击文件 | +| **打开文件** | 双击文件（预览/编辑） | +| **进入目录** | 双击文件夹 | +| **收藏文件** | 点击 ⭐ 按钮，添加到左侧收藏夹 | +| **重命名** | 右键 → 重命名 → 按回车确认 | + +### 文件预览支持 + +| 类型 | 扩展名 | 功能 | +|------|--------|------| +| **图片** | `.jpg`, `.png`, `.gif`, `.svg`, `.webp` | 预览 | +| **视频** | `.mp4`, `.webm`, `.ogg` | 播放器 | +| **音频** | `.mp3`, `.wav`, `.ogg` | 播放器 | +| **PDF** | `.pdf` | 预览 | +| **HTML** | `.html`, `.htm` | 预览 ↔ 编辑切换 | +| **Markdown** | `.md` | 渲染 ↔ 编辑切换 | +| **代码** | `.js`, `.py`, `.go`, `.java`, `.sql`, `.json` 等 | 语法高亮 | + +### ZIP 文件浏览 + +``` +双击 .zip 文件 → 进入浏览模式 → 查看文件列表 → 双击预览 → 退出 ZIP +``` + +### 面板调整 + +| 操作 | 方法 | +|------|------| +| **调整宽度** | 拖动文件列表和内容区之间的分隔条 | +| **显示收藏夹** | 点击顶部 ☰ 按钮 | + +--- + +## 🔧 设备调用测试 + +### 系统信息 + +点击 **刷新系统信息** 获取： + +| 类别 | 显示内容 | +|------|----------| +| **CPU** | 核心数、型号、使用率 | +| **内存** | 总内存、已用、可用、使用率 | +| **系统** | 操作系统、架构、主机名、平台 | +| **磁盘** | 所有分区和使用情况 | + +### 文件系统操作 + +``` +输入路径 → 列出目录 → 查看文件列表 → 预览内容 +``` + +--- + +## ⚙️ 设置 + +### Tab 配置 + +| 功能 | 操作 | +|------|------| +| **调整顺序** | 拖拽 ⋮⋮ 图标 | +| **显示/隐藏** | 勾选/取消勾选（至少保留一个） | +| **设置默认** | 点击 ○ 默认 单选按钮 | +| **保存** | 点击 **保存配置** 按钮 | +| **重置** | 点击 **重置** 恢复上次保存的状态 | + +### 版本更新 + +``` +切换到"版本更新"标签页 → 检查更新 → 下载并安装 +``` + +--- + +## ❓ 常见问题 + +### 应用启动慢？ + +**原因**：启用了所有模块 + +**解决**：设置中取消勾选不用的模块，只保留需要的 + +--- + +### 数据库连接失败？ + +**检查清单**： + +- [ ] 主机、端口、用户名、密码是否正确 +- [ ] 数据库服务器是否已启动 +- [ ] 点击 **测试连接** 验证配置 + +--- + +### 文件预览乱码？ + +**原因**：文件编码不是 UTF-8 + +**解决**：使用专业编辑器（VS Code、Notepad++）查看 + +--- + +### 编辑器无法保存？ + +**说明**：编辑器当前为只读模式 + +**替代**：复制内容到外部编辑器保存 + +--- + +### 如何重置配置？ + +| 系统 | 操作 | +|------|------| +| **Windows** | 删除 `%LOCALAPPDATA%\u-desk\` 文件夹内容 | +| **macOS** | 删除 `~/Library/Application Support/u-desk/` 文件夹 | +| **Linux** | 删除 `~/.config/u-desk/` 文件夹 | + +删除后重启应用，自动恢复默认配置 + +--- + +### ZIP 文件无法修改？ + +**说明**：ZIP 浏览模式为只读 + +**解决**：使用专业压缩软件（WinRAR、7-Zip）修改 + +--- + +## 📂 配置文件位置 + +| 系统 | 路径 | +|------|------| +| **Windows** | `%LOCALAPPDATA%\u-desk\` | +| **macOS** | `~/Library/Application Support/u-desk/` | +| **Linux** | `~/.config/u-desk/` | + +--- + +## ⌨️ 快捷键 + +### 数据库模块 + +| 快捷键 | 功能 | +|--------|------| +| `F5` | 执行 SQL | +| `Ctrl + Enter` | 执行选中的 SQL | + +### 文件管理模块 + +| 快捷键 | 功能 | +|--------|------| +| `Ctrl + N` | 新建文件 | +| `Ctrl + Shift + N` | 新建文件夹 | +| `F2` | 重命名选中文件 | +| `Del` | 删除选中文件 | +| `Ctrl + B` | 显示/隐藏收藏夹侧边栏 | +| `Ctrl + ←` | 后退到上一个目录 | +| `Ctrl + →` | 前进到下一个目录 | +| `Ctrl + Shift + C` | 快速打开 C 盘 | +| `Ctrl + Shift + D` | 快速打开 D 盘 | +| `Ctrl + Shift + E` | 快速打开 E 盘 | +| `Enter` | 确认（编辑文件名时） | +| `Esc` | 取消（编辑文件名时） | + +### 通用快捷键 + +| 快捷键 | 功能 | +|--------|------| +| `F5` | 刷新当前视图 | + +--- + +## 🎯 窗口控制 + +| 按钮 | 功能 | +|------|------| +| `-` | 最小化到任务栏 | +| `□` | 最大化/还原 | +| `×` | 关闭窗口 | + +**拖动窗口**：按住标题栏 "U-Desk" 文字区域或标签页空白区域 + +--- + +**版本**：1.0.0 | **更新日期**：2026-01-28 diff --git a/docs/INDEX.md b/docs/INDEX.md new file mode 100644 index 0000000..a9d210f --- /dev/null +++ b/docs/INDEX.md @@ -0,0 +1,120 @@ +# U-Desk 文档索引 + +> 更新日期：2026-05-01 +> 分支: `fs-only-v3` (Wails v3) +> 参考 [wk-flux/docs](../../wk-flux/docs) 目录结构 + +--- + +## 目录结构 + +``` +docs/ +├── INDEX.md # 本文件 +├── 01-技术文档/ # 技术文档和专题研究 +│ ├── CodeMirror/ # CodeMirror 6 编辑器系列（6篇） +│ └── 数据库优化/ # 数据库连接池、缓存优化（2篇） +├── 02-架构设计/ # 架构设计、改进方案、迁移记录 +│ ├── OOP架构/ # OOP vs Composables 架构对比（6篇） +│ ├── Pinia迁移/ # Pinia 状态管理迁移（5篇） +│ └── 插件系统方案.md +├── 03-模块文档/ # 各功能模块实现文档 +│ ├── 文件系统/ # 文件管理模块（14篇） +│ ├── 更新通知/ # 更新通知模块（10篇） +│ ├── 设置功能/ # 设置模块（4篇） +│ ├── 文件内容/ # 文件内容模块（2篇） +│ └── 启动优化/ # 启动优化模块（3篇） +├── 04-功能迭代/ # 历史功能迭代文档 +│ ├── GO-DESK-1.尝试/ # 应用初始化阶段 +│ ├── GO-DESK-2.数据库客户端/ # 数据库客户端（39篇，已移除） +│ ├── GO-DESK-3.文件系统/ # 文件系统管理 +│ ├── GO-DESK-4.AI工作台/ # AI 工作台 +│ ├── GO-DESK-6.文件操作增强/ # 文件操作增强 +│ └── GO-DESK-7.u-fs-agent远程文件服务/ # 远程文件服务 +├── 05-代码审查/ # 代码审查、走查报告、重构记录 +│ ├── 审查报告/ # 各期代码审查报告 +│ ├── 代码质量/ # 代码质量优化（3篇） +│ └── 分析报告/ # 各类分析报告（6篇） +├── 06-前端开发/ # 前端分析与优化 +│ ├── 布局分析/ +│ ├── 代码分割/ +│ ├── 组件分析/ +│ └── 编译器未发现的初始化问题.md +├── 07-项目管理/ # 项目规划与版本管理 +│ ├── 项目规划/ # PROJECT_STATUS、work-plan +│ ├── 功能清单/ # 功能清单与核对报告 +│ └── 版本管理/ # changelog、版本发布手册 +├── 08-用户指南/ # 用户手册和配置指南 +│ ├── u-desk-site/ # 官网（单页设计，部署至 /var/www/u-desk-site/） +│ │ ├── index.html # 首页（Hero + 功能 + 文档 + 下载） +│ │ ├── changelog.html # 版本历史记录页（时间线样式，7个版本完整日志） +│ │ ├── docs.html # 详细文档页 +│ │ ├── privacy.html # 隐私声明 +│ │ └── download/ # 安装包（Windows exe / Linux） +``` + +--- + +## 快速导航 + +| 分类 | 入口 | 说明 | +|------|------|------| +| 技术文档 | [01-技术文档/](./01-技术文档/) | CodeMirror、数据库优化等专题 | +| 架构设计 | [02-架构设计/](./02-架构设计/) | 架构方案、迁移记录、设计决策 | +| 模块文档 | [03-模块文档/](./03-模块文档/) | 各功能模块的实现和优化记录 | +| 功能迭代 | [04-功能迭代/](./04-功能迭代/) | 历史功能开发过程文档 | +| 代码审查 | [05-代码审查/](./05-代码审查/) | 审查报告、走查报告、重构记录 | +| 前端开发 | [06-前端开发/](./06-前端开发/) | 前端分析、优化、问题排查 | +| 项目管理 | [07-项目管理/](./07-项目管理/) | 项目状态、功能清单、版本管理 | +| 用户指南 | [08-用户指南/](./08-用户指南/) | 用户手册、配置指南 | + +--- + +## 新文档放置规则 + +| 文档类型 | 放置位置 | +|----------|----------| +| 技术专题研究 | `01-技术文档/<专题名>/` | +| 架构设计/改进方案 | `02-架构设计/` | +| 功能模块实现文档 | `03-模块文档/<模块名>/` | +| 功能开发过程记录 | `04-功能迭代/GO-DESK-N.<模块>/` | +| 代码审查/走查报告 | `05-代码审查/审查报告/` | +| 前端优化分析 | `06-前端开发/` | +| 项目状态/功能清单 | `07-项目管理/` | +| 用户手册/配置指南 | `08-用户指南/` | + +--- + +## 技术栈 + +- **后端**: Go 1.26 + Wails v3 (alpha.80) +- **前端**: Vue 3 + TypeScript + Arco Design Vue + Pinia +- **编辑器**: CodeMirror 6 +- **构建**: Vite 7 + Taskfile +- **桌面端**: 原生窗口（macOS/Windows/Linux） +- **数据库**: SQLite（本地配置存储） +- **当前版本**: 0.5.0 + +> 注：v0.4.0 起已移除 MySQL/Redis/MongoDB 数据库客户端模块，专注文件管理功能。 + +## 项目结构（当前） + +``` +u-desk/ +├── main.go # 入口：窗口配置、中间件、DevTools +├── app.go # 应用逻辑：文件系统、更新检查等 +├── wails.json # Wails 项目配置 +├── internal/ # 内部模块 +│ ├── filesystem/ # 文件操作、锁、预览服务 +│ └── agent/ # 远程文件服务 Agent +├── frontend/ # 前端代码 (Vue 3) ← 原 web/ +│ ├── src/ +│ │ ├── components/FileSystem/ # 文件管理主组件 +│ │ ├── stores/ # Pinia 状态管理 +│ │ ├── api/ # 后端调用封装（Transport 抽象） +│ │ └── utils/ # 工具函数 +│ └── vite.config.js +├── build/ # 构建配置（跨平台） +├── cmd/ # 命令行入口 +└── configs/ # 运行时配置 +``` diff --git a/docs/clipboard_20260411_222023.png b/docs/clipboard_20260411_222023.png new file mode 100644 index 0000000..d405ede Binary files /dev/null and b/docs/clipboard_20260411_222023.png differ diff --git a/docs/clipboard_20260413_231715.png b/docs/clipboard_20260413_231715.png new file mode 100644 index 0000000..c0224d0 Binary files /dev/null and b/docs/clipboard_20260413_231715.png differ diff --git a/docs/clipboard_20260413_232441.png b/docs/clipboard_20260413_232441.png new file mode 100644 index 0000000..02f6966 Binary files /dev/null and b/docs/clipboard_20260413_232441.png differ diff --git a/docs/clipboard_20260414_001501.png b/docs/clipboard_20260414_001501.png new file mode 100644 index 0000000..0574610 Binary files /dev/null and b/docs/clipboard_20260414_001501.png differ diff --git a/docs/clipboard_20260414_001830.png b/docs/clipboard_20260414_001830.png new file mode 100644 index 0000000..105375b Binary files /dev/null and b/docs/clipboard_20260414_001830.png differ diff --git a/docs/clipboard_20260414_002525.png b/docs/clipboard_20260414_002525.png new file mode 100644 index 0000000..4079487 Binary files /dev/null and b/docs/clipboard_20260414_002525.png differ diff --git a/docs/clipboard_20260430_165143.png b/docs/clipboard_20260430_165143.png new file mode 100644 index 0000000..3c97965 Binary files /dev/null and b/docs/clipboard_20260430_165143.png differ diff --git a/docs/pic.jsonx b/docs/pic.jsonx new file mode 100644 index 0000000..f6dcef6 --- /dev/null +++ b/docs/pic.jsonx @@ -0,0 +1,3 @@ +{ + sd +} \ No newline at end of file diff --git a/docs/推广方案.md b/docs/推广方案.md new file mode 100644 index 0000000..27dfe6e --- /dev/null +++ b/docs/推广方案.md @@ -0,0 +1,227 @@ +# U-Desk 推广方案 + +> 版本: v1.0 | 制定日期: 2026-04-26 | 状态: 待执行 + +--- + +## 1. 现状分析 + +### 1.1 产品概况 + +| 项目 | 内容 | +|------|------| +| 名称 | U-Desk | +| 当前版本 | v0.4.0 (2026-04-25 发布) | +| 技术栈 | Go 1.25 + Wails v2 + Vue 3 + Arco Design | +| 定位 | 轻量级 Windows 桌面文件管理工具 | +| 包大小 | 7.5MB (UPX 压缩)，单文件免安装 | +| 开源协议 | 免费（未明确声明） | +| 官网 | https://c.1216.top/ | + +### 1.2 核心功能 + +- 本地文件浏览、搜索、排序、批量操作 +- CodeMirror 6 编辑器（20+ 语言高亮、搜索替换） +- 多格式预览（图片/视频/音频/PDF/Office/HTML/Markdown/ZIP） +- Markdown 编辑器（Mermaid 图表渲染、PDF 导出） +- 剪贴板截图一键保存为文件 +- 收藏夹 / 快捷键驱动 / 暗色主题 +- 自动更新（SHA256 校验） + +### 1.3 用户现状（NG 日志统计，截至 4/26） + +**累计独立 IP：8 个 → 归并后 ~5-6 人** + +| 用户组 | IP | 地区 | 运营商 | 请求次数 | 活跃周期 | 推测身份 | +|--------|-----|------|--------|---------|---------|---------| +| A | 111.60.82.184 | 武汉 湖北 | 移动 | 2356 | 4/13 ~ 4/21 | 核心用户（自己） | +| A' | 111.60.82.152 | 武汉 湖北 | 移动 | 9 | 4/21 ~ 4/24 | 同上（同网段） | +| B | 61.242.135.x | 湖北→北京 | 联通 | 149 | 4/21 ~ 至今 | 测试/同事（跨省） | +| C | 223.76.193.223 | 武汉 湖北 | 移动 | 129 | 4/21 ~ 4/24 | 熟人 | +| D | 183.95.249.165 | 武汉 湖北 | 联通 | 41 | 仅 4/23 当天 | 尝鲜流失 | +| E | 221.193.54.209 | 承德 河北 | 联通 | 29 | 仅 4/17~18 | 外地早期用户 | + +**注意**：现有用户集中在湖北/武汉，这是样本偏差（均为熟人），不代表目标市场有地域特征。产品面向全国 Windows 用户。 + +### 1.4 存在问题 + +| 维度 | 现状 | 问题等级 | +|------|------|----------| +| 网站 | 显示 v0.3.3，仍宣传已删除的数据库功能 | **严重** | +| SEO | 无 OG 标签、无结构化数据、无 sitemap | **严重** | +| 社交 | 零社交账号、零社区、零讨论渠道 | **严重** | +| 分析 | 无任何流量/用户统计 | **严重** | +| 托管 | 仅自建 Gitea，无公开仓库 | 高 | +| 素材 | 无截图、无演示视频、无 GIF | 高 | +| 下载 | 链接指向错误文件名 | 中 | + +--- + +## 2. 推广目标 + +| 时间节点 | 日活设备数 | 网站日访客 | GitHub Stars | 下载总量 | +|---------|-----------|-----------|-------------|---------| +| 当前 | ~1 | 未知 | 0 | 未知 | +| 1 个月后 | 10 | 100/天 | 30 | 200 | +| 3 个月后 | 50 | 500/天 | 100 | 1000 | + +--- + +## 3. 推广策略 + +**核心策略：技术社区 + 熟人圈双线并行** + +- 技术社区路线：GitHub + 掘金/V2EX/CSDN，吸引开发者用户 +- 熟人圈路线：微信群/朋友圈扩散，积累种子用户 + +--- + +## 4. 第一阶段：基础夯实（第 1 周） + +### 4.1 网站内容同步 v0.4.0 + +| 任务 | 文件 | 改动内容 | +|------|------|----------| +| 更新版本号 | `u-desk-site/index.html` | v0.3.3 → v0.4.0 | +| 重写 Slogan | `index.html` | 去掉"数据库管理"，聚焦"本地文件浏览编辑" | +| 删除过时功能卡 | `index.html` | 移除数据库管理卡片，补充文件管理亮点 | +| 更新文档 | `docs.html` | 删除数据库章节，更新安装说明 | +| 修复下载链接 | `index.html` | `/download/u-desk.exe` → `/download/u-desk-0.4.0.exe` | + +### 4.2 SEO 基础建设 + +| 任务 | 说明 | +|------|------| +| Open Graph / Twitter Card | 微信/QQ 分享显示预览卡片（标题/描述/封面图） | +| JSON-LD 结构化数据 | SoftwareApplication schema，搜索富摘要 | +| sitemap.xml + robots.txt | 引导搜索引擎收录 | +| favicon | 网站图标（可用应用 logo） | +| 百度统计 | 流量可见性（国内首选） | + +### 4.3 产品素材补全 + +| 任务 | 说明 | +|------|------| +| 应用截图 3-5 张 | 首页文件列表、代码编辑器、文件预览、设置面板、暗色模式 | +| GIF 动图演示 | 核心操作流程（15 秒内） | +| README 配图 | GitHub/Gitee 首屏展示用 | + +--- + +## 5. 第二阶段：渠道铺设（第 2 周） + +### 5.1 开源策略 + +**定位：源码可见（Source Available），非开放协作** + +| 维度 | 策略 | +|------|------| +| 开源目的 | 让用户审查代码、确认无后门/隐私风险、建立信任 | +| 仓库状态 | Public（可 clone / 可阅读） | +| PR 策略 | **不接受** — 仅作者本人提交 | +| Issue 策略 | **开放** — 接受 Bug 反馈和功能建议 | +| License | 建议使用 MIT 或 Apache 2.0（声明"仅供参考学习，不接受贡献"） | +| README 声明 | 明确标注："本项目为个人项目，源码开放供审计参考，暂不接受外部 PR" | + +**为什么这样做：** +- 用户对桌面工具最大的顾虑是安全和隐私 → 源码开放直接消除疑虑 +- 不接受 PR 避免维护负担和代码质量管控成本 +- Issue 开放保持与用户的沟通渠道 +- 这是很多个人项目的常见做法（如部分独立开发者的工具项目） + +### 5.2 代码托管平台 + +| 平台 | 优先级 | 行动项 | +|------|--------|--------| +| **GitHub** | P0 | 创建公开仓库，README + 截图 + Releases + CI | +| **Gitee** | P1 | 镜像同步，覆盖国内开发者 | +| V2EX | P1 | 发布"分享创造"帖子，Wails + Go 技术栈有话题度 | + +### 5.3 上架前检查清单 + +- [ ] 清理代码中的硬编码密钥 / 内网地址 / 调试信息 +- [ ] `.gitignore` 完善（排除 `app.db`、`logs/`、`.aes-key`、`*.exe`） +- [ ] `README.md` 写好：产品介绍、截图、功能列表、下载链接、License 声明 +- [ ] 仓库 Description 简洁有力（如 "轻量级 Windows 文件管理桌面工具 | Go + Wails v2 + Vue 3"） +- [ ] 创建 GitHub Release 附带 v0.4.0 exe + SHA256 + +### 5.2 内容营销 + +| 渠道 | 内容形式 | 建议标题/关键词 | +|------|---------|----------------| +| 掘金 | 技术深度文 | "用 Go+Wails v2 写了一个替代 Windows 资源管理器的桌面工具" | +| 知乎 | 回答/文章 | "有什么好用的 Windows 文件管理工具？" "Go 语言能写 GUI 吗？" | +| CSDN | 教程文 | "u-desk 使用指南：一款轻量级本地文件管理工具" | +| 即刻/X | 短动态 | 开发日常截图、功能亮点、性能对比 | +| 个人公众号 | 正式推文 | 产品介绍 + 下载链接（如有） | + +### 5.3 下载渠道扩展 + +| 渠道 | 说明 | +|------|------| +| GitHub Releases | 自动托管 exe，自带下载统计 | +| Gitee Releases | 国内镜像加速下载 | + +--- + +## 6. 第三阶段：用户增长（第 3-8 周） + +### 6.1 社区运营 + +| 行动 | 说明 | +|------|------| +| 建 QQ群/微信群 | 用户反馈收集 + 新功能投票 | +| GitHub Issues | 开放 issue，接受 feature request + bug report | +| CHANGELOG 持续更新 | 每次发布写清楚改了什么、为什么改 | + +### 6.2 口碑机制 + +| 行动 | 说明 | +|------|------| +| 匿名活跃统计 | 版本检查请求加设备指纹 hash，仅计数不追踪（不改隐私政策） | +| "推荐给朋友"按钮 | 一键复制下载链接到剪贴板 | +| 用户评价展示 | 收集反馈后放在官网 | + +### 6.3 持续内容输出（每两周一篇） + +建议选题： +- Wails v2 实战踩坑系列（Frameless window、菜单、打包） +- Go 桌面开发 vs Electron 性能对比实测 +- u-desk 架构设计思路（为什么砍掉数据库模块） +- 功能开发日志（Markdown 编辑器、PDF 导出等） + +--- + +## 7. 不做的事（资源边界） + +| 不做 | 原因 | +|------|------| +| 付费广告 | 现阶段 ROI 太低，先靠内容获客 | +| macOS/Linux 版本 | 先把 Windows 体验做扎实 | +| 用户系统/登录 | 违背隐私优先原则，增加使用门槛 | +| 多语言 | 专注中文市场，团队精力有限 | +| 应用商店上架 | Microsoft Store 审核周期长，后期考虑 | +| 接受外部 PR | 个人项目，维护成本高；源码开放仅供审计参考 | + +--- + +## 8. 执行检查清单 + +### P0 — 本周必做 + +- [ ] 网站同步 v0.4.0（去数据库描述、更新版本号、修下载链接） +- [ ] 补充产品截图（3-5 张） +- [ ] **开源准备**：清理敏感信息、完善 .gitignore、写 README（含开源声明） +- [ ] 上架 GitHub（公开仓库 + README + Releases，源码可见不接受 PR） + +### P1 — 两周内 + +- [ ] SEO 基础（OG 标签、结构化数据、sitemap、favicon） +- [ ] 掘金/V2EX 各发一篇技术文章 +- [ ] 接入百度统计 + +### P2 — 一个月内 + +- [ ] 建用户交流群 +- [ ] 版本检查加匿名设备计数 +- [ ] 每两周一篇内容输出节奏建立