Skip to content

CUSTOM_MODE_DOCUMENTATION.md

Latest commit

 

History

History
146 lines (112 loc) · 4.01 KB

CUSTOM_MODE_DOCUMENTATION.md

File metadata and controls

146 lines (112 loc) · 4.01 KB
Raw

自定义模式完整文档

概述

自定义模式是 AI Terminal v4.5.0 引入的重要功能，允许用户通过 @文件引用 的方式让 Claude 读取指定文件并根据用户需求生成多种格式的文件。

核心功能

1. 文件引用机制

  • 语法: @文件名 或 @分类/文件名
  • 支持类型: 文本、图片、文档等所有素材类型
  • 智能匹配: 自动搜索并匹配最相关的文件

2. 渐进式文件生成

  • 实时检测: 生成第一个文件即可显示
  • 刷新机制: 用户可手动刷新获取新生成的文件
  • 多格式支持: 支持生成任意格式文件（.md, .html, .json, .txt等）

3. 文件预览与管理

  • Markdown预览: 内置Markdown渲染器，支持语法高亮
  • 文件操作: 查看、下载、刷新文件列表
  • 智能分类: 根据文件类型自动分类展示

技术实现

前端组件

  1. CustomModeToggle.vue - 自定义模式切换组件
  2. AssetReferencePicker.vue - 素材引用选择器
  3. MarkdownPreview.vue - 文件预览组件
  4. useAssetCache.js - 素材缓存管理
  5. referenceParser.js - 引用解析工具

后端服务

  1. referenceConverter.js - 引用转换服务
  2. cardAsync.js - 异步生成处理
  3. cardQuery.js - 文件查询接口

API 接口

1. 异步生成接口

POST /api/generate/card/async
{
  "topic": "用户输入内容（包含@引用）",
  "mode": "custom",
  "references": [
    {
      "type": "asset",
      "category": "分类名",
      "filename": "文件名"
    }
  ]
}

2. 文件刷新接口

GET /api/generate/card/async/refresh/:folderName

响应包含生成的文件列表和状态信息。

3. 文件查询接口

GET /api/generate/card/query/:folderName

获取生成的所有文件内容，支持所有文件类型。

使用流程

  1. 启用自定义模式

    • 点击输入框上方的"自定义"切换按钮

  2. 输入引用

    • 输入 @ 触发素材选择器
    • 选择需要引用的文件
    • 添加任务描述

  3. 发送生成

    • 点击发送按钮开始生成
    • 系统自动将引用转换为文件路径

  4. 查看结果

    • 生成的文件会实时显示
    • 点击"查看"预览文件内容
    • 点击"下载"保存文件
    • 点击"刷新"检查新文件

实施历程

阶段一：设计与规划（2025-09-04）

  • 确定自定义模式核心功能
  • 设计文件引用机制
  • 规划渐进式生成方案

阶段二：核心实现（2025-09-04）

  • 实现素材引用选择器
  • 开发引用转换服务
  • 完成异步生成流程

阶段三：优化与完善（2025-09-05）

  • 添加Markdown预览组件
  • 优化文件操作体验
  • 修复URL编码问题
  • 扩展文件类型支持

关键技术决策

  1. 不创建新接口：复用现有异步生成接口，通过mode参数区分
  2. 渐进式显示：第一个文件生成即显示，提升用户体验
  3. 通配符支持：模板注册表支持*通配符，灵活处理各种文件类型
  4. 路径转换：前端@引用自动转换为后端可识别的文件路径

已知问题与解决方案

问题1：URL编码

  • 问题：中文文件名导致404错误
  • 解决：移除手动编码，让axios自动处理

问题2：路径拼接

  • 问题：后端路径缺少斜杠
  • 解决：确保路径末尾添加斜杠

问题3：变量作用域

  • 问题：templatePath未定义错误
  • 解决：提前声明变量，扩大作用域

版本记录

v4.5.0 (2025-09-05)

  • ✨ 实现自定义模式完整功能
  • 📄 添加Markdown预览组件
  • 🔧 修复各种技术问题
  • 📱 优化移动端体验

未来规划

  1. 批量操作：支持批量下载生成的文件
  2. 模板保存：将常用的自定义提示保存为模板
  3. 预设引用：预定义常用文件组合
  4. 实时协作：多人协同编辑和生成

本文档整合了所有自定义模式相关文档，作为功能的权威参考。