agentstudio 0.2.9 → 0.3.1

package/backend/docs/command-detection-logic.md

@@ -0,0 +1,306 @@
+# 后端从会话历史消息中识别自定义命令的逻辑分析
+
+## 概述
+
+本文档详细描述了后端系统如何从Claude历史会话消息中识别和提取自定义命令的完整逻辑流程。
+
+## 核心组件
+
+### 1. 数据结构
+
+#### ClaudeHistoryMessage
+```typescript
+interface ClaudeHistoryMessage {
+  type: 'summary' | 'user' | 'text' | 'assistant' | 'message' | 'thinking' | 'tool_use' | 'tool_result';
+  uuid: string;
+  timestamp: string;
+  sessionId: string;
+  message?: ClaudeMessage;
+  parentUuid?: string | null;
+  // ... 其他字段
+}
+```
+
+#### SlashCommand
+```typescript
+interface SlashCommand {
+  id: string;
+  name: string;
+  description: string;
+  content: string;
+  scope: 'project' | 'user';
+  namespace?: string;
+  argumentHint?: string;
+  allowedTools?: string[];
+  model?: string;
+  createdAt: Date;
+  updatedAt: Date;
+}
+```
+
+### 2. 主要函数
+
+#### readClaudeHistorySessions()
+- **位置**: `backend/src/routes/agents.ts:30`
+- **功能**: 读取并解析Claude历史会话文件
+- **输入**: `projectPath: string`
+- **输出**: `ClaudeHistorySession[]`
+
+#### extractContentFromClaudeMessage()
+- **位置**: `backend/src/routes/agents.ts:226`
+- **功能**: 从Claude消息中提取内容，特别处理命令格式
+- **关键逻辑**: 识别 `<command-message>` 和 `<command-name>` 标签
+
+#### convertClaudeMessageToMessageParts()
+- **位置**: `backend/src/routes/agents.ts:248`
+- **功能**: 将Claude消息转换为系统内部格式
+- **关键逻辑**: 识别命令格式并创建特殊的 `command` 类型消息部分
+
+## 命令识别逻辑
+
+### 1. 命令标识符检测
+
+系统通过正则表达式检测消息中的命令格式：
+
+```javascript
+const commandMatch = msg.message.content.match(
+  /<command-message>.*?<\/command-message>\s*<command-name>(.+?)<\/command-name>/
+);
+```
+
+**匹配模式**:
+- `<command-message>` 标签：包含命令的描述信息
+- `<command-name>` 标签：包含实际的命令名称
+
+### 2. 消息过滤规则
+
+#### 2.1 基本过滤条件
+```javascript
+const conversationMessages = messages.filter(msg => {
+  // 排除特定类型的消息
+  if (['summary', 'thinking'].includes(msg.type)) return false;
+  
+  // 排除某些工具输出消息
+  if (msg.type === 'tool_result' && 
+      msg.message?.content?.includes('<local-command-stdout></local-command-stdout>') && 
+      msg.parentUuid) {
+    // 检查父消息是否为 /clear 命令
+    const parentMsg = messages.find(m => m.uuid === msg.parentUuid);
+    if (parentMsg && parentMsg.message?.content?.includes('<command-name>/clear</command-name>')) {
+      return false;
+    }
+  }
+  
+  // 处理 assistant 类型消息
+  if (msg.type === 'assistant') return true;
+  
+  // 处理 user 类型消息
+  if (msg.type === 'user') {
+    if (msg.message?.content && Array.isArray(msg.message.content)) {
+      const hasNonToolResult = msg.message.content.some(block => block.type !== 'tool_result');
+      return hasNonToolResult;
+    }
+    return typeof msg.message?.content === 'string' || !msg.message?.content;
+  }
+  
+  return false;
+});
+```
+
+#### 2.2 特殊命令处理
+- **清理命令**: 系统特别处理 `/clear` 命令，会过滤掉其相关的输出消息
+- **工具结果**: 过滤掉纯工具结果消息，只保留包含用户内容的消息
+
+### 3. 消息转换流程
+
+#### 3.1 内容提取
+```javascript
+function extractContentFromClaudeMessage(msg) {
+  if (typeof msg.message.content === 'string') {
+    const commandMatch = msg.message.content.match(
+      /<command-message>.*?<\/command-message>\s*<command-name>(.+?)<\/command-name>/
+    );
+    if (commandMatch) {
+      return commandMatch[1]; // 返回命令名称
+    }
+    return msg.message.content;
+  }
+  
+  if (Array.isArray(msg.message.content)) {
+    return msg.message.content
+      .filter(block => block.type === 'text')
+      .map(block => block.text)
+      .join('');
+  }
+}
+```
+
+#### 3.2 消息部分创建
+```javascript
+function convertClaudeMessageToMessageParts(msg) {
+  if (typeof msg.message.content === 'string') {
+    // 检测命令格式
+    const commandMatch = msg.message.content.match(
+      /<command-message>.*?<\/command-message>\s*<command-name>(.+?)<\/command-name>/
+    );
+    
+    if (commandMatch) {
+      return [{
+        id: `part_0_${msg.uuid}`,
+        type: 'command',
+        content: commandMatch[1], // 命令名称
+        originalContent: msg.message.content, // 保留原始内容
+        order: 0
+      }];
+    }
+    
+    // 普通文本消息
+    return [{
+      id: `part_0_${msg.uuid}`,
+      type: 'text',
+      content: msg.message.content,
+      order: 0
+    }];
+  }
+  
+  // 处理数组内容（工具使用、图片等）
+  if (Array.isArray(msg.message.content)) {
+    return msg.message.content.map((block, index) => {
+      if (block.type === 'text') {
+        return {
+          id: `part_${index}_${msg.uuid}`,
+          type: 'text',
+          content: block.text,
+          order: index
+        };
+      } else if (block.type === 'tool_use') {
+        return {
+          id: `part_${index}_${msg.uuid}`,
+          type: 'tool',
+          toolData: {
+            claudeId: block.id,
+            toolName: block.name,
+            toolInput: block.input || {},
+            toolResult: '',
+            isExecuting: false,
+            isError: false
+          },
+          order: index
+        };
+      }
+      // ... 处理其他类型
+    }).filter(part => part !== null);
+  }
+}
+```
+
+## 自定义命令管理
+
+### 1. 命令存储结构
+
+#### 项目命令
+- **路径**: `{projectPath}/.ai-commands/`
+- **范围**: 项目级别，与团队共享
+
+#### 用户命令
+- **路径**: `~/.ai-commands/`
+- **范围**: 用户级别，个人使用
+
+### 2. 命令文件格式
+
+```markdown
+---
+description: "命令描述"
+argument-hint: "参数提示"
+allowed-tools: "Read,Write,Edit"
+model: "sonnet"
+---
+
+命令的具体内容...
+```
+
+### 3. 命令扫描逻辑
+
+```javascript
+async function scanCommands(dirPath, scope) {
+  const commands = [];
+  
+  async function scanDirectory(currentDir, namespace) {
+    const items = await readdir(currentDir, { withFileTypes: true });
+    
+    for (const item of items) {
+      if (item.isDirectory()) {
+        const subNamespace = namespace ? `${namespace}/${item.name}` : item.name;
+        await scanDirectory(path.join(currentDir, item.name), subNamespace);
+      } else if (item.name.endsWith('.md')) {
+        const commandName = item.name.replace('.md', '');
+        const content = await readFile(path.join(currentDir, item.name), 'utf-8');
+        const parsed = parseCommandContent(content);
+        
+        commands.push({
+          id: `${scope}:${namespace ? namespace + '/' : ''}${commandName}`,
+          name: commandName,
+          description: parsed.frontmatter.description || '',
+          content: parsed.body,
+          scope,
+          namespace,
+          // ... 其他属性
+        });
+      }
+    }
+  }
+  
+  await scanDirectory(dirPath);
+  return commands;
+}
+```
+
+## 关键技术点
+
+### 1. 正则表达式模式
+- **命令识别**: `/<command-message>.*?<\/command-message>\s*<command-name>(.+?)<\/command-name>/`
+- **非贪婪匹配**: 使用 `.*?` 避免跨命令匹配
+- **命名捕获**: 提取 `<command-name>` 标签内的内容
+
+### 2. 消息层次结构
+- **父子关系**: 通过 `parentUuid` 建立消息间的层次关系
+- **工具链**: 工具使用和工具结果的关联处理
+- **会话隔离**: 按 `sessionId` 组织消息
+
+### 3. 内容类型处理
+- **字符串内容**: 直接处理文本消息
+- **数组内容**: 处理包含多种类型（文本、工具、图片）的复合消息
+- **工具消息**: 特殊处理工具使用和结果消息
+
+### 4. 错误处理
+- **文件不存在**: 优雅处理命令文件缺失
+- **解析错误**: 容错处理格式错误的命令文件
+- **权限问题**: 处理文件系统访问权限
+
+## 性能优化
+
+### 1. 缓存策略
+- 避免重复扫描命令目录
+- 使用文件修改时间检测变更
+
+### 2. 内存管理
+- 流式处理大型历史文件
+- 及时释放不需要的消息数据
+
+### 3. 并发处理
+- 并行扫描多个命令目录
+- 异步文件操作
+
+## 安全考虑
+
+### 1. 路径安全
+- 验证命令文件路径，防止目录遍历攻击
+- 限制命令文件的访问范围
+
+### 2. 内容验证
+- 验证命令内容的格式和语法
+- 过滤恶意代码和脚本
+
+### 3. 权限控制
+- 区分项目级和用户级命令权限
+- 验证用户对命令的访问权限

package/backend/docs/command-detection-sequence.md

@@ -0,0 +1,186 @@
+# 命令识别逻辑时序图
+
+```mermaid
+sequenceDiagram
+    participant Client as 前端客户端
+    participant AgentRoute as agents.ts 路由
+    participant FileSystem as 文件系统
+    participant CommandParser as 命令解析器
+    participant MessageConverter as 消息转换器
+
+    Note over Client, MessageConverter: 会话历史读取和命令识别流程
+
+    Client->>AgentRoute: GET /api/agents/history/sessions?projectPath={path}
+    
+    AgentRoute->>FileSystem: 读取 Claude 历史目录
+    Note right of FileSystem: ~/.claude/projects/.../*.jsonl
+    
+    FileSystem-->>AgentRoute: 返回历史文件列表
+    
+    loop 遍历每个历史文件
+        AgentRoute->>FileSystem: readFile(historyFile)
+        FileSystem-->>AgentRoute: 原始 JSON 行数据
+        
+        AgentRoute->>AgentRoute: 解析 JSON 行数据
+        Note right of AgentRoute: 过滤无效消息
+        
+        loop 遍历每条消息
+            AgentRoute->>MessageConverter: 消息过滤检查
+            
+            alt 消息类型为 summary 或 thinking
+                MessageConverter-->>AgentRoute: 跳过消息
+            else 消息类型为 tool_result 且包含 local-command-stdout
+                MessageConverter->>MessageConverter: 检查父消息是否为 /clear 命令
+                alt 父消息是 /clear 命令
+                    MessageConverter-->>AgentRoute: 跳过消息
+                else 父消息不是 /clear 命令
+                    MessageConverter-->>AgentRoute: 保留消息
+                end
+            else 消息类型为 user
+                MessageConverter->>MessageConverter: 检查是否只包含 tool_result
+                alt 只包含 tool_result
+                    MessageConverter-->>AgentRoute: 跳过消息
+                else 包含其他内容
+                    MessageConverter-->>AgentRoute: 保留消息
+                end
+            else 消息类型为 assistant
+                MessageConverter-->>AgentRoute: 保留消息
+            end
+        end
+        
+        loop 处理保留的消息
+            AgentRoute->>MessageConverter: extractContentFromClaudeMessage(msg)
+            
+            MessageConverter->>MessageConverter: 检查消息内容类型
+            
+            alt 内容为字符串
+                MessageConverter->>CommandParser: 正则匹配命令格式
+                Note right of CommandParser: /<command-message>.*?<\/command-message>\s*<command-name>(.+?)<\/command-name>/
+                
+                alt 匹配到命令格式
+                    CommandParser-->>MessageConverter: 返回命令名称
+                    MessageConverter-->>AgentRoute: 返回命令名称
+                else 未匹配命令格式
+                    CommandParser-->>MessageConverter: 返回原始内容
+                    MessageConverter-->>AgentRoute: 返回原始内容
+                end
+                
+            else 内容为数组
+                MessageConverter->>MessageConverter: 过滤 text 类型块
+                MessageConverter->>MessageConverter: 拼接文本内容
+                MessageConverter-->>AgentRoute: 返回拼接后的内容
+            end
+            
+            AgentRoute->>MessageConverter: convertClaudeMessageToMessageParts(msg)
+            
+            alt 内容为字符串且匹配命令格式
+                MessageConverter->>MessageConverter: 创建 command 类型部分
+                Note right of MessageConverter: type: 'command', content: 命令名称
+                MessageConverter-->>AgentRoute: 返回命令消息部分
+            else 内容为字符串但非命令格式
+                MessageConverter->>MessageConverter: 创建 text 类型部分
+                MessageConverter-->>AgentRoute: 返回文本消息部分
+            else 内容为数组
+                loop 遍历内容块
+                    alt 块类型为 text
+                        MessageConverter->>MessageConverter: 创建 text 部分
+                    else 块类型为 tool_use
+                        MessageConverter->>MessageConverter: 创建 tool 部分
+                        Note right of MessageConverter: 包含工具名称、输入、结果等
+                    else 块类型为 tool_result
+                        MessageConverter->>MessageConverter: 跳过（将合并到 tool_use）
+                    else 块类型为 image
+                        MessageConverter->>MessageConverter: 创建 image 部分
+                    else 其他类型
+                        MessageConverter->>MessageConverter: 创建 unknown 部分
+                    end
+                end
+                MessageConverter-->>AgentRoute: 返回消息部分数组
+            end
+        end
+        
+        AgentRoute->>AgentRoute: 合并连续的 assistant 消息
+        Note right of AgentRoute: 优化对话展示
+        
+        AgentRoute->>AgentRoute: 构建会话对象
+        Note right of AgentRoute: 包含会话元数据和处理后的消息
+    end
+    
+    AgentRoute-->>Client: 返回处理后的会话历史
+    Note left of Client: 包含识别出的命令和其他消息类型
+
+    Note over Client, MessageConverter: 命令文件扫描和管理流程（独立流程）
+
+    Client->>AgentRoute: GET /api/commands?projectPath={path}
+    
+    AgentRoute->>FileSystem: 扫描项目命令目录
+    Note right of FileSystem: {projectPath}/.ai-commands/
+    
+    AgentRoute->>FileSystem: 扫描用户命令目录  
+    Note right of FileSystem: ~/.ai-commands/
+    
+    loop 遍历命令目录
+        FileSystem->>FileSystem: 递归扫描子目录
+        
+        loop 遍历 .md 文件
+            FileSystem->>CommandParser: readFile(commandFile)
+            CommandParser->>CommandParser: parseCommandContent()
+            Note right of CommandParser: 解析 frontmatter 和内容
+            
+            CommandParser->>CommandParser: 构建命令对象
+            Note right of CommandParser: 包含 id, name, description, scope 等
+            
+            CommandParser-->>FileSystem: 返回解析后的命令
+        end
+        
+        FileSystem-->>AgentRoute: 返回目录下所有命令
+    end
+    
+    AgentRoute-->>Client: 返回所有可用命令列表
+```
+
+## 关键流程说明
+
+### 1. 消息过滤阶段
+- **目的**: 从原始 Claude 历史中筛选出有价值的对话消息
+- **规则**: 
+  - 排除 `summary` 和 `thinking` 类型消息
+  - 排除纯工具结果消息（除非包含用户内容）
+  - 特殊处理 `/clear` 命令的输出消息
+
+### 2. 命令识别阶段
+- **触发条件**: 消息内容包含特定的 XML 标签格式
+- **识别模式**: `<command-message>` + `<command-name>` 标签组合
+- **结果**: 提取出实际的命令名称，创建 `command` 类型的消息部分
+
+### 3. 消息转换阶段
+- **目的**: 将 Claude 原始消息格式转换为系统内部格式
+- **处理类型**:
+  - 文本消息 → `text` 部分
+  - 命令消息 → `command` 部分  
+  - 工具使用 → `tool` 部分
+  - 图片内容 → `image` 部分
+
+### 4. 会话重构阶段
+- **消息合并**: 合并连续的 assistant 消息以优化展示
+- **层次建立**: 基于 `parentUuid` 建立消息间的父子关系
+- **会话组织**: 按 `sessionId` 组织完整的对话会话
+
+### 5. 命令管理阶段（独立流程）
+- **文件扫描**: 递归扫描项目和用户命令目录
+- **内容解析**: 解析 Markdown 文件的 frontmatter 和内容
+- **命令构建**: 创建完整的命令对象，包含元数据和权限信息
+
+## 性能优化点
+
+1. **异步处理**: 所有文件操作都采用异步方式
+2. **并行扫描**: 同时扫描多个命令目录
+3. **增量解析**: 只处理发生变化的历史文件
+4. **内存管理**: 及时释放大型历史文件的内存占用
+
+## 错误处理机制
+
+1. **文件不存在**: 优雅降级，返回空结果
+2. **格式错误**: 跳过格式错误的消息，继续处理其他消息
+3. **权限问题**: 记录错误日志，但不中断整个流程
+4. **解析异常**: 使用默认值填充缺失的字段

package/backend/eslint.config.js

@@ -0,0 +1,25 @@
+import js from '@eslint/js'
+import globals from 'globals'
+import tseslint from 'typescript-eslint'
+
+export default tseslint.config([
+  {
+    ignores: ['dist/**', 'node_modules/**', 'coverage/**']
+  },
+  {
+    files: ['**/*.{ts,js,mjs}'],
+    extends: [
+      js.configs.recommended,
+      tseslint.configs.recommended,
+    ],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.node,
+    },
+    rules: {
+      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+      '@typescript-eslint/no-explicit-any': 'warn',
+      'no-console': 'off', // Allow console.log in backend
+    }
+  },
+])

package/backend/package.json

@@ -0,0 +1,103 @@
+{
+  "name": "agentstudio-backend",
+  "version": "0.3.1",
+  "description": "Backend API for AgentStudio - AI-powered presentation editor with Claude integration",
+  "main": "dist/index.js",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "bin": {
+    "agentstudio": "dist/bin/agentstudio.js"
+  },
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "cli": "tsx src/bin/agentstudio.ts",
+    "type-check": "tsc --noEmit",
+    "lint": "eslint . --fix",
+    "migrate-projects": "node scripts/migrate-projects.js",
+    "upgrade-agents": "node scripts/upgrade-agents.js",
+    "restore-agents": "node scripts/restore-agents.js",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "test:run": "vitest run",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@a2a-js/sdk": "^0.2.5",
+    "@ai-sdk/anthropic": "^1.0.5",
+    "@ai-sdk/openai": "^1.0.7",
+    "@anthropic-ai/claude-agent-sdk": "^0.1.62",
+    "@types/js-yaml": "^4.0.9",
+    "ai": "^5.0.22",
+    "bcryptjs": "^2.4.3",
+    "commander": "^11.1.0",
+    "cors": "^2.8.5",
+    "dotenv": "^16.3.1",
+    "eventsource": "^4.0.0",
+    "express": "^4.18.2",
+    "express-rate-limit": "^6.11.2",
+    "fs-extra": "^11.1.1",
+    "gray-matter": "^4.0.3",
+    "helmet": "^7.0.0",
+    "js-yaml": "^4.1.0",
+    "jsonwebtoken": "^9.0.2",
+    "node-cron": "^4.2.1",
+    "posthog-node": "^5.21.1",
+    "proper-lockfile": "^4.1.2",
+    "tunely": "^0.2.1",
+    "undici": "^7.16.0",
+    "zod": "^3.22.2"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.37.0",
+    "@types/bcryptjs": "^2.4.6",
+    "@types/cors": "^2.8.13",
+    "@types/express": "^4.17.17",
+    "@types/fs-extra": "^11.0.1",
+    "@types/jsonwebtoken": "^9.0.10",
+    "@types/node": "^20.5.0",
+    "@types/node-cron": "^3.0.11",
+    "@types/proper-lockfile": "^4.1.4",
+    "@types/supertest": "^6.0.3",
+    "@types/uuid": "^9.0.7",
+    "@vitest/coverage-v8": "^2.1.0",
+    "@vitest/ui": "^2.1.0",
+    "eslint": "^9.37.0",
+    "globals": "^16.4.0",
+    "supertest": "^7.1.4",
+    "ts-node": "^10.9.2",
+    "tsx": "^4.20.6",
+    "typescript": "^5.1.6",
+    "typescript-eslint": "^8.46.1",
+    "uuid": "^9.0.1",
+    "vitest": "^2.1.0"
+  },
+  "author": "okguitar <okguitar@gmail.com>",
+  "license": "GPL-3.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/okguitar/agentstudio.git"
+  },
+  "homepage": "https://github.com/okguitar/agentstudio#readme",
+  "bugs": {
+    "url": "https://github.com/okguitar/agentstudio/issues"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "studio",
+    "editor",
+    "presentation",
+    "claude",
+    "react",
+    "typescript",
+    "api"
+  ],
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "LICENSE"
+  ]
+}