AI辅助的
代码编辑器

1.1 XteVision Coder 是什么？

XteVision Coder 是一款 AI 辅助的代码编辑器和网页端 IDE，面向希望借助集成 AI 支持来创建、编辑和管理项目的开发者。它提供专业的三面板工作站布局，包含文件浏览器、代码编辑器、AI 聊天、实时预览和终端访问——全部在本地运行，并支持多种 AI 模型。

1.2 核心能力

• 多根工作区管理，支持拖放式文件操作
• 专业代码编辑，由 Monaco Editor（与 VS Code 相同的引擎）驱动
• AI 辅助编程，支持流式响应和自主智能体模式
• 持久化的认证会话，具备独立登录/注册和基于 PostgreSQL 的会话存储
• 保存的 AI 对话，带有标题、重命名/搜索/收藏控制，以及自动恢复上一次会话
• 工作区状态恢复，可恢复活动工作区根目录、已开标签页、活动标签页和未保存的编辑器缓冲区
• 实时预览，针对 HTML/CSS/JS 项目采用沙箱化的 iframe 渲染
• 集成终端，带命令白名单以保证安全执行
• 多模型支持，覆盖 MLX、Ollama、LMStudio、GitHub Copilot 和 OpenRouter
• 智能代码合并，基于 diff 的编辑应用和可视化 diff 预览

1.3 目标用户

• 使用本地 AI 模型的开发者
• 需要轻量级自托管 IDE 的团队
• 借助 AI 辅助来编程教学的教师
• 希望获得浏览器中类 VS Code 体验的任何用户

2.1 高层架构

┌──────────────────────────────────────────────────────────┐
│                      浏览器 (客户端)                     │
│  ┌────────────────────────────────────────────────────┐  │
│  │               前端 (原生 JavaScript)                 │  │
│  │  ┌────────┐ ┌────────┐ ┌──────┐ ┌────────┐       │  │
│  │  │ 文件   │ │ Monaco │ │  AI  │ │ 实时   │       │  │
│  │  │浏览器 │ │ 编辑器 │ │ 聊天 │ │预览 │       │  │
│  │  └────────┘ └────────┘ └──────┘ └────────┘       │  │
│  └────────────────────────────────────────────────────┘  │
└──────────────────────┬───────────────────────────────────┘
                       │ HTTP/REST API (localhost:5004)
┌──────────────────────┴───────────────────────────────────┐
│                  Python 后端服务器                    │
│  ┌──────────┐ ┌────────┐ ┌────────┐ ┌──────────┐ ┌──────────┐ │
│  │ 文件 I/O │ │ Shell  │ │AI 代理│ │工作区 │ │认证/聊天 │ │
│  └──────────┘ └────────┘ └────────┘ └──────────┘ └──────────┘ │
└──────────────────────┬───────────────────────────────────┘
         ┌───────────┬───────────┬───────────┐
         │           │           │           │
     ┌─────▼──────┐ ┌──▼────────┐ ┌▼──────────┐
     │  文件      │ │PostgreSQL │ │ AI 模型  │
     │  系统      │ │用户 +     │ │  服务器   │
     │            │ │会话       │ │           │
     └────────────┘ └───────────┘ └───────────┘

2.2 通信流程

1. 前端 → 后端：针对文件操作、shell 命令和 AI 代理的 RESTful HTTP 请求
2. 后端 → AI 模型：向本地或远程模型服务器发起 OpenAI 兼容 API 调用
3. 后端 → 前端：通过 SSE 返回包含文件内容、执行结果或流式 AI 响应的 JSON 响应
4. 前端 → 用户：UI 更新、编辑器变更、聊天响应和终端输出

2.3 部署模型

XteVision Coder 面向 本地优先开发 设计：

• 完全运行在用户机器上
• 无云依赖（除可选的 AI 模型代理外）
• 后端托管静态前端文件
• 所有数据保留在本地文件系统上

4.1 前置条件

• Python 3.8+（用于后端服务器）
• 现代浏览器（推荐 Chrome/Edge）
• AI 模型服务器（可选，用于 AI 功能）

4.2 安装步骤

步骤 1：下载

cd /path/to/mlx_coder

步骤 2：安装 Monaco Editor（可选）

bash download-monaco.sh

步骤 3：配置 AI 服务器（可选）

mlx_lm.server --model <your-model-path> --port 5010

步骤 4：安装 Python 依赖

pip3 install -r requirements.txt

步骤 5：启动 XteVision Coder

# 默认配置
python3 server.py

# 自定义端口
PORT=8080 python3 server.py

# 使用基于 PostgreSQL 的认证
XTEVISION_DB_HOST=192.168.1.4 \
XTEVISION_DB_PORT=5432 \
XTEVISION_DB_NAME=codebase \
XTEVISION_DB_USER=postgres \
XTEVISION_DB_PASSWORD=your-db-password \
python3 server.py

步骤 6：访问应用

http://localhost:5004

4.3 首次设置

1. 创建账号：使用登录/注册浮层创建首个独立的 Coder 用户
2. 打开工作区：点击“打开文件夹”选择项目目录
3. 配置 AI：打开设置（齿轮图标）并保存你偏好的 AI 后端
4. 开始会话：使用会话工具栏创建、命名和收藏持久化的 AI 对话

4.4 认证设置

XteVision Coder 现在基于 cookie 认证，并由 PostgreSQL 支撑。每个用户只能看到自己的已保存聊天会话和工作区恢复数据。

• XTEVISION_AUTH_COOKIE_NAME：会话 cookie 名称，默认为 xtevision_session
• XTEVISION_AUTH_SESSION_DAYS：cookie 有效期（天数），默认为 14
• XTEVISION_AUTH_ALLOW_REGISTRATION：启用/禁用本地注册
• XTEVISION_PRODIGY_SHARED_SECRET：可选的共享密钥，用于将来可信的 Prodigy 启动交接

4.5 OpenRouter 设置

将 OpenRouter 作为 AI 后端使用：

1. 在右侧边栏打开 设置
2. 在 AI 服务器 下拉框中选择 OpenRouter
3. 将 API URL 设置为 https://openrouter.ai/api/v1/chat/completions
4. 选择一个 OpenRouter 模型 ID，例如 qwen/qwen3.6-plus-preview

当选中 OpenRouter 时，XteVision Coder 会附加以下请求头：

• Authorization: Bearer <OPENROUTER_API_KEY>
• HTTP-Referer: <配置的网站 URL>
• X-OpenRouter-Title: <配置的网站标题>

5.1 目录布局

mlx_coder/
├── index.html                      # 主 HTML 入口
├── style.css                       # 应用样式
├── script.js                       # Bootstrap 与模块加载器
├── server.py                       # Python HTTP 后端
├── .mlx.json                       # 项目状态
├── js/
│   ├── modules/                    # 前端 ES6 模块
│   │   ├── state.js                # 全局状态管理
│   │   ├── config.js               # AI 配置与各供应商特定设置
│   │   ├── utils.js                # 工具函数
│   │   ├── filesystem.js           # 文件 I/O 与工作区
│   │   ├── editor.js               # Monaco Editor 初始化
│   │   ├── chat.js                 # AI 聊天与流式传输
│   │   ├── agent.js                # 智能体循环与函数调用
│   │   ├── auth.js                 # 登录/注册/登出引导
│   │   ├── sessionPersistence.js   # 聊天会话自动保存与恢复
│   │   ├── tools.js                # 工具定义
│   │   ├── diff.js                 # 基于 diff 的编辑
│   │   ├── preview.js              # 实时预览与 PDF 导出
│   │   └── ui.js                   # UI 渲染与交互
│   ├── marked.min.js               # Markdown 解析器
│   ├── prism.min.js                # 语法高亮器
│   └── html2pdf.bundle.min.js      # PDF 生成
├── fontawesome-free-web/           # FontAwesome 图标
├── requirements.txt                # Python 认证/数据库依赖
├── projects/                       # 用户项目文件
└── logs/app.log                    # 应用日志

5.2 状态管理

export const state = {
    editor: null,               // Monaco Editor 实例
    files: {},                  // 文件内容缓存
    openTabs: [],               // 已开编辑器标签页
    activeTabPath: null,        // 活动标签页路径
    tabDirty: {},               // 各标签页的未保存状态
    messageHistory: [],         // 当前聊天消息历史
    chatSessionId: null,        // 当前已保存聊天会话 ID
    chatSessions: [],           // 可用的已保存聊天会话
    workspaceFolders: new Map() // 已打开的工作区文件夹
};

智能体模式详情

7.1 核心模块

7.2 事件系统

// 用于设置变更的自定义事件
window.dispatchEvent(new CustomEvent('xtevision-settings-changed'));

// 监听事件
window.addEventListener('xtevision-settings-changed', () => {
  // 对设置变更做出反应
});

7.3 错误处理

// 异步初始化的全局错误边界
try {
  await checkServerAvailability();
  await connectToServerWorkspace();
} catch (error) {
  logToTerminal(`初始化错误: ${error.message}`, 'error');
}

8.1 服务器配置

PORT = int(os.environ.get('PORT', 5004))
PROJECTS_DIR = os.path.join(os.getcwd(), 'projects')
AI_PROXY_TIMEOUT_SEC = 3660
AUTH_COOKIE_NAME = os.environ.get('XTEVISION_AUTH_COOKIE_NAME', 'xtevision_session')
AUTH_DB_HOST = os.environ.get('XTEVISION_DB_HOST', '192.168.1.4')
AUTH_DB_NAME = os.environ.get('XTEVISION_DB_NAME', 'codebase')
PRODIGY_JWT_SECRET = os.environ.get('XTEVISION_PRODIGY_SHARED_SECRET', '')

8.2 线程安全

_current_dir_lock = threading.Lock()
_current_dir = os.getcwd()

def get_current_dir():
    with _current_dir_lock:
        return _current_dir

8.3 认证与会话存储

后端会初始化一个包含以下内容的 coder PostgreSQL 模式：

• users：用于本地和将来 Prodigy 关联的身份
• auth_sessions：用于安全的会话 cookie 登录状态
• auth_launch_tokens：一次性签名启动交接
• chat_sessions：用于保存的聊天、标题、收藏和 UI 恢复负载

8.4 请求处理器

class CustomHandler(http.server.SimpleHTTPRequestHandler):
    def do_GET(self): # 处理 GET
    def do_POST(self): # 处理 POST
    def do_OPTIONS(self): # CORS 预检
    def end_headers(self): # 添加 CORS 头

8.5 AI 代理行为

后端提供两个 AI 相关的代理端点：

• /api/proxy：用于模型发现等轻量 JSON 抓取
• /api/ai-proxy：用于向 OpenAI 兼容的聊天端点转发完整请求

对于 OpenRouter，两个端点都会转发供应商请求头，并在代理白名单中允许 openrouter.ai，从而让经过后端回退路径的认证模型发现和聊天补全正常工作。

9.1 支持的 AI 服务器

9.2 OpenAI 兼容协议

端点： /v1/chat/completions

{
  "model": "your-model-name",
  "messages": [
    {"role": "system", "content": "你是一个编程助手..."},
    {"role": "user", "content": "写一个函数来..."}
  ],
  "stream": true,
  "tools": [{"type":"function","function":{"name":"read_file","parameters":{"file_path":"string"}}}]
}

9.3 流式响应格式

服务器推送事件（SSE）：

data: {"choices": [{"delta": {"content": "你好"}}]}
data: {"choices": [{"delta": {"content": "世界"}}]}
data: [DONE]

9.4 函数调用

工具解析（3 种格式）：

1. Gemma 风格： call:read_file{"file_path": "test.js"}
2. 结构化 JSON： {"name": "read_file", "arguments": {...}}
3. 标记格式：