Skip to content

Latest commit

 

History

History
357 lines (296 loc) · 10.1 KB

README.md

File metadata and controls

357 lines (296 loc) · 10.1 KB

AI写作助手

本文档由 AI 助手（Claude）基于项目开发记录生成和整理，主要面向初次使用本项目的用户和开发者。

License: MIT

🚀 快速开始

项目简介

这是一个基于大语言模型的写作辅助工具，专注于提升文字编辑和内容创作的效率。它提供了可视化的提示词编辑系统，让你能够轻松地优化和改进文章。

支持的大语言模型

目前支持以下模型：

  1. 通义千问（默认）

  2. DeepSeek

    • DeepSeek-V3：适合通用对话和写作场景
    • DeepSeek-R1：专注于推理和分析能力
    • 需要在DeepSeek 开放平台获取 API Key

  3. Ollama 本地模型

    • 支持在本地运行开源大语言模型
    • 无需 API Key，完全离线运行
    • 支持 Llama2、Mistral、Qwen 等多种模型
    • 需要安装 Ollama

  4. 自定义模型

    • 支持配置任何兼容 OpenAI API 格式的模型
    • 可自定义 Base URL、API Key 和模型名称
    • 适合接入私有部署的模型或其他云服务商的模型

初次使用步骤

  1. 安装必要环境

  2. 配置 API Key（仅在线API模式需要）

    • 复制 config.example.js 为 config.js
    • 配置至少一个在线模型的 API Key

  3. 启动项目

    Linux/macOS:

    # 添加脚本执行权限
chmod +x start.sh

# 运行启动脚本
./start.sh

    Windows:

    # 使用Git Bash
sh start.sh

# 或使用 PowerShell/CMD
bash start.sh

    提示：Windows用户如果遇到无法运行脚本的情况，可以：

    1. 使用 Git Bash（推荐，下载地址：Git for Windows）
    2. 使用 WSL（Windows Subsystem for Linux）
    3. 直接使用手动启动步骤（见下方"手动启动步骤"部分）

    启动脚本会自动：

    • 检查环境依赖
    • 安装所需包
    • 启动服务器

  4. 选择启动模式并访问

    • 完整模式（选项1）：支持所有功能

      • 访问地址：http://localhost:3000
      • 使用 localhost 以支持完整的服务器功能
      • 适用于：需要使用在线API或本地模型的场景
      • 需要：如使用在线API，需配置相应的API Key

    • 本地模式（选项2）：使用Ollama本地模型

      • 访问地址：http://127.0.0.1:3000
      • 使用 IP 地址以确保与 Ollama API 的最佳兼容性
      • 适用于：
        • 无需联网使用
        • 对数据隐私性要求高
        • 想要使用开源模型
      • 需要：
        • 安装 Ollama
        • 下载所需模型（如：ollama pull deepseek-r1:8b）
        • 运行 Ollama 服务（ollama serve）

技术说明：虽然 localhost 和 127.0.0.1 都指向本机，但我们在不同模式下使用不同的地址是为了：

  1. 确保完整模式下的服务器功能正常运行
  2. 保持与 Ollama 本地API（使用 127.0.0.1:11434）的一致性
  3. 避免在本地模式下不必要的 DNS 解析

功能预览

  • ✨ 可视化提示词系统
  • 📝 Markdown 导入导出
  • 🎯 智能写作优化
  • 🔗 文本块自由连接

立即尝试

我们提供了《端午的鸭蛋》这篇课文的 markdown 版本，你可以用它来体验所有功能。

💡 核心功能

  • 提示词编辑系统
    • 创建和编辑提示词卡片
    • 预设优化模板
    • 变量系统支持
  • 文本编辑功能
    • Markdown 格式支持
    • 自由拖拽排布
    • 可视化连接
  • 智能优化
    • 段落规范化
    • 文本衔接优化
    • 内容整体优化

想了解更多？请继续阅读下面的详细说明。

🎨 设计文档

设计理念

本项目采用类似苹果设计风格的界面，追求简洁、优雅且易用的用户体验。整个界面采用左右两栏布局：

  • 左侧：提示词编辑区，包含可复用的提示词卡片
  • 右侧：文档编辑区，支持自由拖拽排布文本块
  • 中间：通过可视化连接线建立关联

界面设计要点

  1. 卡片式布局

    • 提示词卡片：浅色背景，渐变文本预览
    • 文本卡片：支持拖拽和大小调整
    • 统一的圆角和阴影效果

  2. 交互设计

    • 卡片悬停显示操作按钮
    • 拖拽时的半透明效果
    • 连接端口动画反馈
    • 清晰的按钮状态

  3. 色彩系统

    • 主色调：#007aff（按钮、重要操作）
    • 危险色：#ff3b30（删除操作）
    • 警告色：#F5B400（警告提示）
    • 成功色：#00b894（成功状态）
    • 中性色：文本、边框和背景

样式系统

为保持界面一致性和可维护性，我们建立了完整的样式系统：

  1. 基础样式
:root {
  --color-primary: #007aff;    /* 主色调 */
  --spacing-sm: 8px;           /* 基础间距 */
  --radius-lg: 8px;            /* 卡片圆角 */
  --shadow-sm: 0 2px 8px rgba(0, 0, 0, 0.1); /* 基础阴影 */
}
  1. 布局系统
    • Flexbox 布局
    • 左侧边栏固定 300px
    • 右侧内容区自适应
    • 统一的间距变量

文件结构

styles/
├── base.css          # 基础样式
│   ├── 变量定义
│   ├── 重置样式
│   └── 通用样式
│
├── layout.css        # 布局样式
│   ├── 主容器
│   ├── 侧边栏
│   └── 内容区
│
└── components/       # 组件样式
    ├── buttons.css   # 按钮样式
    ├── cards.css     # 卡片样式
    ├── dialogs.css   # 对话框样式
    └── ports.css     # 连接样式

开发者指南

  1. 样式修改

    • 主题修改：编辑 base.css 中的变量
    • 布局调整：修改 layout.css
    • 组件更新：修改 components 下对应文件

  2. 依赖说明

    • axios: 1.7.9
    • cors: 2.8.5
    • express: 4.21.2
    • live-server: 1.2.2

  3. API 配置

    • 所有前端文件在根目录
    • server.js 处理 API 代理
    • API 密钥配置在 script.js

功能特点

  • 可视化的提示词编辑系统
    • 支持创建和编辑提示词卡片
    • 提供预设的写作优化提示词模板
    • 支持提示词的变量系统，可灵活替换内容
  • 文本编辑功能
    • 支持 Markdown 格式文件的导入导出
    • 支持文本块的自由拖拽排布
    • 文本块与提示词的可视化连接
  • 智能写作优化
    • 支持文章段落的规范化处理
    • 支持文本衔接优化
    • 支持内容整体性优化

📖 使用指南

环境要求

  • Node.js: 20.17.0 或更高版本

手动启动步骤

如果你不想使用启动脚本，可以手动执行：

# 安装依赖
npm install

# 启动完整模式
npm start

# 或启动本地模式（使用 Ollama）
npm run dev

使用 Ollama 本地模型

  1. 安装 Ollama

    • Mac：brew install ollama
    • 其他系统：访问 ollama.ai 下载

  2. 启动 Ollama 服务

    ollama serve

  3. 下载模型

    # 下载 Llama2
ollama pull deepseek-r1:8b

# 或下载其他模型

  4. 在应用中使用

    • 启动应用后，点击模型选择器
    • 选择"本地模型（借助Ollama）"
    • 在弹出的对话框中选择要使用的模型

常见问题解决

  1. 依赖安装失败
npm cache clean --force
npm install

  1. 端口被占用 修改 server.js 中的端口号

  2. 重启服务

# 停止服务
Ctrl + C

# 重新启动
npm start

本地模式

使用本地模式：

npm run dev  # 启动本地模式，支持 Ollama 本地模型

注意：本地模式下在线 API 不可用

项目文件结构

样式文件组织

项目采用模块化的CSS文件组织方式，所有样式文件位于 styles/ 目录下：

styles/
├── base.css          # 基础样式
│   ├── CSS变量定义（颜色、间距、圆角、阴影等）
│   ├── 重置样式
│   ├── 基础样式
│   └── 通用滚动条样式
│
├── layout.css        # 布局样式
│   ├── 主容器布局
│   ├── 侧边栏布局
│   ├── 主内容区布局
│   └── 输出容器布局
│
└── components/       # 组件样式
    ├── buttons.css   # 按钮样式
    │   ├── 基础按钮
    │   ├── 图标按钮
    │   ├── 警告按钮
    │   └── 浮动按钮
    │
    ├── cards.css     # 卡片样式
    │   ├── 提示词卡片
    │   ├── 段落卡片
    │   └── 卡片操作按钮
    │
    ├── dialogs.css   # 对话框样式
    │   ├── 编辑对话框
    │   └── 文件输入包装器
    │
    └── ports.css     # 连接相关样式
        ├── 端口容器
        ├── 连接端口
        ├── 连接线
        └── 端口标签

样式设计原则

  1. 变量统一管理

    • 颜色系统：主色调、警告色、危险色等
    • 间距系统：从xs到xxl的统一间距
    • 圆角和阴影：统一的圆角和阴影定义

  2. 模块化组织

    • 每个文件职责单一
    • 相关样式集中管理
    • 便于维护和扩展

  3. 命名规范

    • 使用语义化的类名
    • 采用BEM命名方式
    • 避免样式冲突

  4. 响应式设计

    • 使用相对单位
    • 灵活的布局方案
    • 优雅的降级处理

样式使用说明

  1. 所有样式文件都在 index.html 中按顺序引入
  2. base.css 必须最先引入，它包含了基础变量定义
  3. 组件样式可以根据需要按需引入
  4. 修改主题色等全局样式只需修改 base.css 中的变量

📄 许可证

本项目采用 MIT 许可证。你可以自由地使用、修改和分发本项目，但需要保留原始许可证和版权信息。