zero-workspace 0.0.2

package/dist/utils/validation.js

@@ -0,0 +1,88 @@
+// src/utils/validation.ts
+import * as path from "node:path";
+import * as fs from "node:fs";
+import { ZeroError } from "../types/errors.js";
+/**
+ * 禁止在名称中使用的字符
+ */
+const INVALID_CHARS = /[/\\:*?"<>|]/;
+/**
+ * 验证工作区名称
+ * @throws ZeroError 如果名称不合法
+ */
+export function validateWorkspaceName(name) {
+    if (!name || name.trim().length === 0) {
+        throw new ZeroError("INVALID_NAME", "工作区名称不能为空");
+    }
+    if (INVALID_CHARS.test(name)) {
+        throw new ZeroError("INVALID_NAME", "工作区名称不能包含特殊字符: / \\ : * ? \" < > |");
+    }
+}
+/**
+ * 验证节点标题
+ * @throws ZeroError 如果标题不合法
+ */
+export function validateNodeTitle(title) {
+    if (!title || title.trim().length === 0) {
+        throw new ZeroError("INVALID_TITLE", "节点标题不能为空");
+    }
+    if (INVALID_CHARS.test(title)) {
+        throw new ZeroError("INVALID_TITLE", "节点标题不能包含特殊字符: / \\ : * ? \" < > |");
+    }
+}
+/**
+ * 验证 ID 是否为空
+ */
+export function validateId(id, type) {
+    if (!id || id.trim().length === 0) {
+        if (type === "workspace") {
+            throw new ZeroError("WORKSPACE_NOT_FOUND", "工作区 ID 不能为空");
+        }
+        else {
+            throw new ZeroError("NODE_NOT_FOUND", "节点 ID 不能为空");
+        }
+    }
+}
+/**
+ * 验证并规范化项目根目录路径
+ * @param inputPath 用户输入的路径
+ * @param basePath 基准路径（默认为 cwd），用于解析相对路径
+ * @returns 规范化后的绝对路径
+ * @throws ZeroError 如果路径不安全或不存在
+ */
+export function validateProjectRoot(inputPath, basePath = process.cwd()) {
+    // 1. 检查输入是否为空
+    if (!inputPath || inputPath.trim().length === 0) {
+        throw new ZeroError("INVALID_PATH", "项目路径不能为空");
+    }
+    // 2. 检查是否包含危险的路径穿越模式
+    // 注意：需要在 resolve 之前检查原始输入
+    const normalizedInput = inputPath.replace(/\\/g, "/");
+    if (normalizedInput.includes("/../") ||
+        normalizedInput.startsWith("../") ||
+        normalizedInput.endsWith("/..") ||
+        normalizedInput === "..") {
+        throw new ZeroError("INVALID_PATH", "项目路径不能包含目录穿越 (..)");
+    }
+    // 3. 解析为绝对路径
+    const resolvedPath = path.resolve(basePath, inputPath);
+    // 4. 再次验证解析后的路径不会逃逸到意外位置
+    // 确保解析后的路径在用户主目录或 basePath 下
+    const homeDir = process.env.HOME || process.env.USERPROFILE || "/";
+    const isUnderHome = resolvedPath.startsWith(homeDir);
+    const isUnderBase = resolvedPath.startsWith(basePath);
+    if (!isUnderHome && !isUnderBase) {
+        throw new ZeroError("INVALID_PATH", `项目路径必须在用户主目录或当前目录下: ${resolvedPath}`);
+    }
+    // 5. 验证目录存在
+    if (!fs.existsSync(resolvedPath)) {
+        throw new ZeroError("INVALID_PATH", `项目目录不存在: ${resolvedPath}`);
+    }
+    // 6. 验证是目录而非文件
+    const stat = fs.statSync(resolvedPath);
+    if (!stat.isDirectory()) {
+        throw new ZeroError("INVALID_PATH", `路径不是目录: ${resolvedPath}`);
+    }
+    return resolvedPath;
+}
+//# sourceMappingURL=validation.js.map

package/dist/utils/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/utils/validation.ts"],"names":[],"mappings":"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"}

package/docs//346/227/245/345/277/227/347/263/273/347/273/237.md

@@ -0,0 +1,389 @@
+# 日志系统
+
+> ZeroWorkspace 统一日志记录方案
+
+---
+
+## 概述
+
+ZeroWorkspace 日志系统提供统一的日志记录能力，支持：
+
+- **后端系统日志**：记录 MCP 调用、系统事件等
+- **前端错误上报**：捕获 Vue 错误、JS 异常、Promise rejection、API 错误
+- **可配置日志级别**：支持 debug/info/warn/error 四级过滤
+
+所有日志统一写入 `~/.zero-workspace/logs/system.log`，采用 JSON Lines 格式便于解析。
+
+---
+
+## 架构
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                          前端 (Vue)                              │
+├─────────────────────────────────────────────────────────────────┤
+│  Vue errorHandler  │  window.onerror  │  onunhandledrejection   │
+│                    │                  │                          │
+│  axios interceptor (API 错误)                                    │
+└───────────────────────────┬─────────────────────────────────────┘
+                            │ POST /api/logs/client
+                            ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                          后端 (Node.js)                          │
+├─────────────────────────────────────────────────────────────────┤
+│  log.ts 路由           │  sessionLogger (MCP 调用)               │
+│       │                │         │                               │
+│       └────────────────┴─────────┘                               │
+│                        │                                         │
+│                        ▼                                         │
+│              ┌─────────────────┐                                 │
+│              │  Logger 单例     │ ◄── 读取 config.json logLevel  │
+│              │  (级别过滤)      │                                 │
+│              └────────┬────────┘                                 │
+│                       │                                          │
+│                       ▼                                          │
+│              ┌─────────────────┐                                 │
+│              │  异步写入队列    │                                 │
+│              └────────┬────────┘                                 │
+│                       │                                          │
+│                       ▼                                          │
+│              ~/.zero-workspace/logs/system.log                  │
+│              (JSON Lines, 10MB 轮转, 最多 10 个文件)             │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 日志存储
+
+### 文件位置
+
+| 环境 | 路径 |
+|------|------|
+| 生产 | `~/.zero-workspace/logs/system.log` |
+| 开发 | `~/.zero-workspace-dev/logs/system.log` |
+
+### 日志格式 (JSON Lines)
+
+每行是一个独立的 JSON 对象：
+
+```json
+{"ts":"2024-01-15T10:30:45.123Z","level":"info","source":"mcp","event":"start","tool":"node_create","sessionId":"abc123"}
+{"ts":"2024-01-15T10:30:45.456Z","level":"error","source":"client","type":"vue","message":"Cannot read property 'x' of undefined","component":"NodeTree"}
+```
+
+### 日志字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `ts` | string | ISO 8601 时间戳 |
+| `level` | string | 日志级别：debug/info/warn/error |
+| `source` | string | 来源标识：mcp/client/system |
+| `...` | any | 其他动态字段，取决于日志类型 |
+
+### 日志轮转
+
+- **触发条件**：单个日志文件达到 10MB
+- **保留数量**：最多 10 个文件
+- **文件命名**：
+  - `system.log` - 当前日志
+  - `system.1.log` - 上一个
+  - `system.2.log` ~ `system.9.log` - 更早的日志
+
+轮转时，最旧的 `system.9.log` 被删除，其余文件依次重命名。
+
+---
+
+## 日志级别
+
+### 级别优先级
+
+| 级别 | 优先级 | 说明 |
+|------|--------|------|
+| `debug` | 0 | 调试信息，最详细 |
+| `info` | 1 | 常规信息（默认级别） |
+| `warn` | 2 | 警告信息 |
+| `error` | 3 | 错误信息 |
+
+### 过滤规则
+
+配置的日志级别决定最低记录级别。例如：
+
+- 配置 `logLevel: "info"`：记录 info、warn、error，忽略 debug
+- 配置 `logLevel: "warn"`：记录 warn、error，忽略 debug、info
+- 配置 `logLevel: "debug"`：记录所有级别
+
+### 配置方法
+
+编辑 `~/.zero-workspace/config.json`：
+
+```json
+{
+  "version": "1.0",
+  "defaultDispatchMode": "none",
+  "logLevel": "debug"
+}
+```
+
+或使用 MCP 工具：
+
+```typescript
+config_set({ logLevel: "debug" })
+```
+
+---
+
+## 后端日志
+
+### Logger API
+
+```typescript
+import { logger } from './utils/logger.js';
+
+// 调试日志
+logger.debug('source', { key: 'value' });
+
+// 信息日志
+logger.info('source', { key: 'value' });
+
+// 警告日志
+logger.warn('source', { key: 'value' });
+
+// 错误日志
+logger.error('source', { key: 'value' });
+```
+
+### MCP 调用日志
+
+`sessionLogger` 自动记录所有 MCP 工具调用：
+
+```typescript
+// 调用开始
+logMcpStart('node_create', { workspaceId: 'ws-xxx', title: '新任务' });
+
+// 调用结束
+logMcpEnd('node_create', true, { nodeId: 'node-xxx' }, 123);
+
+// 调用错误
+logMcpError('node_create', new Error('创建失败'));
+```
+
+生成的日志：
+
+```json
+{"ts":"...","level":"info","source":"mcp","event":"start","tool":"node_create","sessionId":"...","params":{...}}
+{"ts":"...","level":"info","source":"mcp","event":"end","tool":"node_create","sessionId":"...","success":true,"result":"...","durationMs":123}
+```
+
+---
+
+## 前端错误上报
+
+### 错误类型
+
+| 类型 | 说明 | 触发场景 |
+|------|------|----------|
+| `vue` | Vue 组件错误 | 组件渲染/生命周期异常 |
+| `js` | JavaScript 错误 | 运行时异常 |
+| `promise` | Promise rejection | 未处理的 Promise 拒绝 |
+| `api` | API 请求错误 | HTTP 请求失败 |
+
+### 自动捕获
+
+前端已注册全局错误处理器，无需手动调用：
+
+```typescript
+// main.ts 中已配置
+
+// 1. Vue 组件错误
+app.config.errorHandler = (err, vm, info) => {
+  reportError({ type: 'vue', message: err.message, ... });
+}
+
+// 2. 全局 JS 错误
+window.onerror = (message, filename, lineno, colno, error) => {
+  reportError({ type: 'js', message, ... });
+}
+
+// 3. 未处理 Promise rejection
+window.onunhandledrejection = (event) => {
+  reportError({ type: 'promise', message: event.reason, ... });
+}
+
+// 4. API 错误（axios 拦截器）
+// client.ts 中已配置
+```
+
+### 手动上报
+
+```typescript
+import { reportError } from '@/utils/errorReporter';
+
+reportError({
+  type: 'js',
+  message: '自定义错误信息',
+  stack: error.stack,
+  extra: { userId: '123' }
+});
+```
+
+### 上报数据结构
+
+```typescript
+interface ErrorReport {
+  type: 'vue' | 'js' | 'promise' | 'api';  // 错误类型
+  message: string;                          // 错误消息
+  stack?: string;                           // 堆栈信息
+  component?: string;                       // Vue 组件名（仅 vue 类型）
+  url?: string;                             // 页面 URL（自动填充）
+  extra?: Record<string, unknown>;          // 额外信息
+}
+```
+
+### 后端接收端点
+
+`POST /api/logs/client`
+
+请求体：
+
+```json
+{
+  "type": "vue",
+  "message": "Cannot read property 'x' of undefined",
+  "stack": "Error: ...\n    at ...",
+  "component": "NodeTree",
+  "url": "http://localhost:5173/workspace/ws-xxx"
+}
+```
+
+响应：
+
+```json
+{ "success": true }
+```
+
+---
+
+## 查看日志
+
+### 命令行查看
+
+```bash
+# 查看最新日志
+tail -f ~/.zero-workspace/logs/system.log
+
+# 格式化查看（需要 jq）
+tail -f ~/.zero-workspace/logs/system.log | jq .
+
+# 过滤错误日志
+cat ~/.zero-workspace/logs/system.log | jq 'select(.level == "error")'
+
+# 过滤前端错误
+cat ~/.zero-workspace/logs/system.log | jq 'select(.source == "client")'
+
+# 过滤特定 MCP 工具
+cat ~/.zero-workspace/logs/system.log | jq 'select(.tool == "node_create")'
+```
+
+### 常用过滤
+
+```bash
+# 最近 10 条错误
+cat ~/.zero-workspace/logs/system.log | jq 'select(.level == "error")' | tail -10
+
+# 统计各级别日志数量
+cat ~/.zero-workspace/logs/system.log | jq -r '.level' | sort | uniq -c
+
+# 统计各来源日志数量
+cat ~/.zero-workspace/logs/system.log | jq -r '.source' | sort | uniq -c
+
+# 查看某时间段的日志
+cat ~/.zero-workspace/logs/system.log | jq 'select(.ts >= "2024-01-15T10:00:00" and .ts <= "2024-01-15T11:00:00")'
+```
+
+---
+
+## 故障排查
+
+### 常见问题
+
+**Q: 日志文件不存在？**
+
+A: 日志目录和文件在首次写入时自动创建。检查：
+- 是否有写入权限：`ls -la ~/.zero-workspace/`
+- 开发环境路径不同：`~/.zero-workspace-dev/logs/`
+
+**Q: 日志级别配置不生效？**
+
+A:
+1. 检查配置文件格式是否正确
+2. 日志级别在模块加载时读取，修改后需重启服务
+3. 无效的级别值会回退到默认值 `info`
+
+**Q: 前端错误没有上报？**
+
+A:
+1. 检查网络请求是否发出（DevTools Network）
+2. 上报失败时静默处理，不会影响用户体验
+3. 确认后端服务正常运行
+
+### 日志文件过大
+
+如果磁盘空间不足，可手动清理：
+
+```bash
+# 删除所有轮转日志，保留当前日志
+rm ~/.zero-workspace/logs/system.*.log
+
+# 清空当前日志
+> ~/.zero-workspace/logs/system.log
+```
+
+---
+
+## 最佳实践
+
+### 后端日志
+
+1. **选择合适的来源标识**
+   - `mcp`：MCP 工具调用
+   - `system`：系统内部事件
+   - `http`：HTTP 请求/响应
+
+2. **包含必要上下文**
+   ```typescript
+   logger.info('mcp', {
+     tool: 'node_create',
+     workspaceId: 'ws-xxx',
+     params: { title: '...' }
+   });
+   ```
+
+3. **错误日志包含堆栈**
+   ```typescript
+   logger.error('system', {
+     message: error.message,
+     stack: error.stack
+   });
+   ```
+
+### 前端错误
+
+1. **使用 extra 字段补充上下文**
+   ```typescript
+   reportError({
+     type: 'js',
+     message: '操作失败',
+     extra: {
+       userId: currentUser.id,
+       action: 'saveDocument'
+     }
+   });
+   ```
+
+2. **不要过度上报**
+   - 避免在循环中上报
+   - 考虑防抖/节流
+
+3. **敏感信息脱敏**
+   - 不要上报密码、token 等敏感数据