（开源项目）x-claw(总)

xsun_chat -- 智能任务自动化执行引擎

git仓库地址

xsun_chat

基于 自然语言指令 驱动的桌面端 AI 助手。你只需要用中文描述目标，The Doer 自动完成文件操作、命令执行、网页抓取等任务，并通过独立的 Reviewer 模型审核结果------自己做事、自己检查、自己纠正。

项目运行预览：

核心特性

• 自然语言驱动 --- 说人话就行。例如："帮我把下载文件夹里的图片按月份整理到对应文件夹"
• 双层 Maker/Reviewer 架构 --- Maker（执行层）调用工具完成操作；Reviewer（审核层）用不同的模型独立验证结果，避免"自己审自己"的盲点
• Spec 模式 --- 复杂任务自动生成执行规格文档 (Spec)，经用户确认后拆解为可追踪的 Loop 步骤逐步执行，每步独立验证
• 多工作区支持 --- 侧边栏管理多个工作区，每个工作区独立的会话数据和配置，一键切换
• 安全沙盒 --- Windows 路径白名单 + Shell 命令过滤 + 高危操作确认，防止误操作
• 流式 SSE 事件 --- 实时显示执行阶段、工具调用、审核进度、Spec 生成与 Loop 执行
• CoT 思考链 --- LLM 推理过程流式实时展示，可点击展开/折叠；重启应用后思考链仍能从历史消息中恢复
• 多供应商 LLM --- 支持 DeepSeek / OpenAI / 通义千问等任意 OpenAI 兼容 API，Maker 和 Reviewer 可分别配置不同供应商
• 图片消息（多模态） --- 支持选择 / 拖拽 / 粘贴图片附件，视觉模型自动识别图片内容（单张 ≤8MB，视觉传递 ≤4MB）；AI 输出的图片显示缩略图，历史图片重启后仍可预览
• 渐进审核 --- 简单对话跳过审核；复杂任务触发 Reviewer 验证；不通过则自动修正重试
• 自进化能力 --- AI 发现工具缺失时可自建技能（create_skill），经安全扫描与用户审批后热加载，同一会话立即可用、永久保留；modify_skill 可持续改进技能（自动版本备份与回滚），全程记录进化日志
• SkillHub 技能市场 --- 外挂式技能体系，支持从 SkillHub（GitHub 静态托管 / 自建服务 / 本地目录）搜索、下载、一键安装技能包，无需修改源码即可扩展能力；同时可浏览 ClawHub（OpenClaw 官方仓库）
• 技能协作路由 --- 创建或批量创建技能后自动解析技能间协作路由（解析 main.py 代码引用 / description 关系词 / SKILL.md 依赖字段，LLM 仅兜底），AI 可自动串联多个技能完成复合任务
• 定时任务 --- 自然语言创建 cron 定时任务（"周一到周五每天 17:00 梳理当日 git 提交并填写 jira"），应用后台运行期间到点自动无头执行，结果保存为新会话，支持手动补跑与启停
• Tauri 桌面原生 --- Tauri 2.x 桌面壳，Rust 层自动管理 Python 后端子进程生命周期，异常退出后重启自动清理残留进程
• MCP 工具集成 --- 支持 Model Context Protocol（MCP）远程服务器，工作区级别管理外部工具，自动刷新工具列表，与内置工具对 Maker 透明
• Jira 集成 --- 内置 Jira 工具：查看未完成 Issue、工作日志、记录工时，支持企业项目管理流程
• 输出文件追踪 --- Skill/Shell 命令生成的文件自动登记到右上角输出面板；工作区快照差异检测（execute_shell/run_python）确保产物不漏登
• 上下文完整性保护 --- 会话异常中断后自动修复残缺的 tool_calls ↔ tool 配对，注入占位消息，确保任务可继续（不再出现 OpenAI 400 错误）
• 会话导出 --- 一键将会话导出为结构化 Markdown（含思考链、工具调用、审核卡片），Tauri 下弹系统保存对话框，浏览器下直接下载；支持单会话与批量导出

快速开始

前置条件

要求	版本
Python	>= 3.11
Node.js	>= 18
至少一个 LLM API Key	DeepSeek / OpenAI / Qwen 等

方式 A：前后端分离开发模式

# 终端 1：启动后端
cd backend
pip install -e .
uvicorn app.main:app --host 127.0.0.1 --port 8787 --reload

# 终端 2：启动前端
cd frontend
npm install
npm run dev

后端运行在 http://127.0.0.1:8787，前端运行在 http://localhost:5173，Vite 自动代理 /api 到后端。

方式 B：Tauri 桌面开发模式

cd frontend
npm install
npm run tauri:dev

Tauri 自动：启动 Vite 开发服务器 -> 检测系统 Python -> spawn 后端进程 -> 打开桌面窗口。窗口关闭时自动终止后端。

首次配置

首次打开时进入设置向导：

1. 选择 Maker（执行）的 LLM 供应商（推荐 DeepSeek）
2. 选择 Reviewer（审核）的 LLM 供应商（推荐与 Maker 不同，如 OpenAI）
3. 填入 API Key 并测试连接
4. 开始对话

配置保存在应用数据目录 data/config.json（开发模式为 backend/data/，打包安装版为 <安装目录>/data/；旧版 ~/.xsun_chat 数据首次启动自动迁移），可随时在设置中修改。

架构概览

┌───────────────────────────────────────────────────┐
│  Tauri Desktop Shell (Rust)                       │
│  · 自动 spawn Python 后端  · 窗口管理  · 进程生命周期 │
│  ┌──────────────────────────────────────────────┐ │
│  │  Vue 3 Frontend (Agentic UI)                 │ │
│  │  · 会话管理  · 对话流  · Spec 卡片  · 审核结果 │ │
│  │  · 思考链  · 任务流卡片  · Loop 进度可视化    │ │
│  └──────────────────┬───────────────────────────┘ │
│                     │ HTTP/SSE                     │
│  ┌──────────────────▼───────────────────────────┐ │
│  │  Python FastAPI Backend (端口 8787)           │ │
│  │                                               │ │
│  │  ┌──────────────────────────────────────┐    │ │
│  │  │  Orchestrator (Chat 模式编排器)        │    │ │
│  │  │  ┌──────────┐    ┌──────────────┐    │    │ │
│  │  │  │  Maker    │───>│  Reviewer    │    │    │ │
│  │  │  │  执行循环   │<───│  独立审核     │    │    │ │
│  │  │  │  Model A  │    │  Model B     │    │    │ │
│  │  │  └──────────┘    └──────────────┘    │    │ │
│  │  └──────────────────────────────────────┘    │ │
│  │                                               │ │
│  │  ┌──────────────────────────────────────┐    │ │
│  │  │  SpecOrchestrator (Spec 模式编排器)    │    │ │
│  │  │  SpecGenerator -> LoopEngineer        │    │ │
│  │  │  -> Maker (逐步执行) -> Harness (逐步验证)│   │ │
│  │  └──────────────────────────────────────┘    │ │
│  │                                               │ │
│  │  ┌──────────────────────────────────────┐    │ │
│  │  │  Harness 层: LLM 网关  · 工具注册      │    │ │
│  │  │  · 记忆管理  · 安全沙盒  · 上下文管理   │    │ │
│  │  └──────────────────────────────────────┘    │ │
│  │                                               │ │
│  │  SQLite (WAL 模式)                            │ │
│  └───────────────────────────────────────────────┘ │
└───────────────────────────────────────────────────┘

Chat 模式工作流 (Maker/Reviewer)

用户输入 "整理下载文件夹的图片"
  │
  ▼
Orchestrator 判断审核需求
  ├─ always -> 始终审核
  ├─ never  -> 跳过审核
  └─ complex_only -> 执行后判断（命中关键词 或 实际调用写文件类工具）
  │
  ▼
Maker 执行循环（Model A，最多 30 轮）
  ├─ ContextManager 构建上下文（系统提示词[含工作区路径] + 历史 + 用户消息）
  ├─   上下文完整性校验：修复中断导致的 tool_calls 配对损坏
  ├─ LLM 流式调用（streaming + function calling）
  ├─ 调用 list_directory  扫描下载文件夹
  ├─ 调用 execute_shell   创建月份文件夹
  ├─ 调用 execute_shell   移动文件
  │   └─ 工作区快照差异检测：自动登记新增文件到输出面板
  └─ 生成最终回复
  │
  ▼
Reviewer 独立审核（Model B，低 temperature）
  ├─ 接收：用户目标 + 完整执行轨迹 + 最终输出
  ├─ 检查：目标是否达成？步骤是否正确？安全隐患？
  └─ 输出：评分 + 问题列表 + 通过/不通过
  │
  ▼
通过 -> 持久化审核结果 -> 返回用户
不通过 -> 注入反馈 -> Maker 修正重试（最多 1 轮）
  └─ 仍不通过 -> 持久化审核结果 + 附审核意见返回

Spec 模式工作流

用户输入复杂任务
  │
  ▼
Phase 1: SpecGenerator 生成执行规格文档（SSE 流式输出）
  ├─ LLM 生成结构化 Markdown 文档
  ├─ 保存到数据库，创建 spec_card 消息
  └─ 发送 spec_ready 事件 -> 前端展示 Spec 卡片，等待用户确认
  │
  ▼ (用户确认后)
Phase 2: LoopEngineer 拆解 Spec 为 Loop 步骤
  ├─ 优先结构化解析 Markdown（正则匹配步骤格式）
  └─ 降级方案：LLM 拆解
  │
  ▼
Phase 3: 逐步执行 Loop（每步：Maker + Harness 验证）
  ├─ LoopStep 1: Maker 执行 -> Harness 验证
  │   └─ 不通过 -> 注入反馈 -> 重试（最多 2 次）
  ├─ LoopStep 2: Maker 执行 -> Harness 验证
  ├─ LoopStep N: ...
  └─ Loop 完成 -> loop_complete 事件
  │
  ▼
返回执行摘要（完成数 / 失败数）

目录结构

xsun_chat/
├── README.md
├── docs/
│   ├── ARCHITECTURE.md    # 架构设计文档
│   ├── USAGE.md           # 使用文档
│   └── DEPLOY.md          # 部署文档
├── backend/               # Python FastAPI 后端
│   ├── pyproject.toml
│   ├── run_backend.py     # Tauri sidecar 入口
│   ├── build_exe.py       # PyInstaller 打包脚本
│   └── app/
│       ├── main.py        # FastAPI 入口 + CORS + 生命周期
│       ├── config.py      # Pydantic Settings 配置管理
│       ├── api/           # REST API 层
│       │   ├── chat.py    # SSE 流式对话 + Spec 模式路由
│       │   ├── sessions.py  # 会话 CRUD
│       │   ├── settings.py  # 配置管理 + 工作区设置
│       │   ├── spec.py      # Spec 确认 + 继续执行
│       │   ├── skills.py    # 技能管理 API
│       │   ├── scheduler.py # 定时任务管理 API
│       │   ├── mcp.py       # MCP 服务器管理 API
│       │   ├── router.py    # API 路由统一注册
│       │   └── workspaces.py  # 多工作区注册与管理
│       ├── core/          # 核心编排层
│       │   ├── orchestrator.py      # Chat 模式编排器
│       │   ├── spec_orchestrator.py # Spec 模式编排器
│       │   ├── maker.py             # Maker 执行 Agent（含工作区快照差异检测）
│       │   ├── reviewer.py          # Reviewer 审核 Agent
│       │   ├── harness.py           # Harness 单步验证器
│       │   ├── spec_generator.py    # Spec 文档生成器
│       │   ├── loop_engineer.py     # Loop 步骤拆解器
│       │   ├── context_manager.py   # 上下文窗口管理 + 工具调用配对修复
│       │   └── prompt_builder.py    # 系统提示词构建（含工作区路径注入）
│       ├── utils/         # 通用工具模块
│       │   └── export.py  # 会话导出渲染（全量消息 → 结构化 Markdown）
│       ├── harness/       # 基础设施层
│       │   ├── llm_gateway.py    # 多供应商 LLM 网关
│       │   ├── tool_registry.py  # 工具注册中心
│       │   ├── sandbox.py        # Windows 安全沙盒
│       │   └── memory.py         # 会话记忆管理
│       ├── tools/         # 内置工具（50+）
│       │   ├── registry.py    # 统一注册入口 + 工具分类
│       │   ├── common.py      # 路径校验 + 输出文件追踪（OUTPUT_TOOLS 白名单 + output_file 通用约定）
│       │   ├── file_ops.py    # read_file / write_file / list_directory
│       │   ├── file_manager.py  # copy / move / delete / mkdir / search / info / append
│       │   ├── text_tools.py  # search_in_files / replace_in_file / diff_files
│       │   ├── documents.py   # Excel / Word / CSV / PDF / PPT 读写
│       │   ├── image_tools.py # convert_image / image_info
│       │   ├── archive_tools.py  # zip / unzip
│       │   ├── code_tools.py  # run_python / git_operation
│       │   ├── git_tools.py   # git_commits（提交历史查询）
│       │   ├── shell.py       # execute_shell (PowerShell)
│       │   ├── web.py         # web_fetch
│       │   ├── web_tools.py   # web_search / download_file
│       │   ├── jira_tools.py  # jira_unfinished_issues / jira_worklogs / jira_log_work
│       │   └── system_tools.py  # calculator / datetime / clipboard / system_info
│       ├── skills/        # 外挂技能系统（自进化 + SkillHub 市场）
│       │   ├── manager.py    # 技能生命周期管理
│       │   ├── hub_client.py # SkillHub / ClawHub 客户端
│       │   ├── security.py   # AST 安全扫描
│       │   ├── self_mod.py   # 自修改引擎
│       │   ├── loader.py     # 动态加载（热重载）
│       │   ├── builtin_tools.py  # Agent 技能管理工具
│       │   ├── auto_route.py  # 技能协作路由解析（解析式优先 + LLM 兜底）
│       │   └── models.py     # SkillMeta 数据模型
│       ├── scheduler/     # 定时任务系统（cron 调度）
│       │   ├── engine.py     # 后台 asyncio 循环（15s tick）
│       │   ├── cron.py       # 5 段 cron 解析器
│       │   ├── store.py      # JSON 持久化 + 运行结果记录
│       │   ├── builtin_tools.py  # Agent 定时任务工具
│       │   └── models.py     # ScheduledTask 数据模型
│       ├── mcp/           # MCP 工具集成（Model Context Protocol）
│       │   ├── manager.py    # MCP 服务器生命周期管理（注册/刷新/工作区切换）
│       │   ├── client.py     # MCP JSON-RPC 客户端
│       │   └── config.py     # MCP 服务器配置
│       ├── models/        # Pydantic Schema + ORM 实体
│       └── db/            # SQLite (aiosqlite) 数据库 + Repository + 中央注册表
├── frontend/              # Vue 3 + TypeScript 前端
│   ├── package.json
│   ├── vite.config.ts
│   ├── src-tauri/         # Tauri 2.x Rust 源码
│   │   ├── Cargo.toml
│   │   ├── tauri.conf.json
│   │   ├── capabilities/
│   │   └── src/
│   │       ├── main.rs    # Rust 入口
│   │       └── lib.rs     # 后端进程管理 + Tauri setup
│   └── src/
│       ├── App.vue
│       ├── main.ts
│       ├── router/        # Vue Router 路由
│       ├── stores/        # Pinia 状态管理
│       │   ├── chat.ts    # 对话状态 + SSE 事件处理 + 工具调用元信息重建
│       │   ├── session.ts # 会话管理
│       │   ├── spec.ts    # Spec 模式状态
│       │   ├── workspace.ts  # 多工作区状态
│       │   ├── settings.ts   # 配置状态
│       │   ├── skills.ts     # 技能系统状态
│       │   ├── scheduler.ts  # 定时任务状态
│       │   ├── mcp.ts        # MCP 工具状态
│       │   └── taskflow.ts   # 任务流可视化
│       ├── components/    # Vue 组件
│       │   ├── chat/      # ChatView, InputBox, MarkdownRenderer, MessageBubble, ToolResultCard
│       │   ├── layout/    # AppLayout, Sidebar, ContextPanel
│       │   ├── spec/      # SpecCard, SpecViewer
│       │   ├── taskflow/  # TaskFlowCard, ThinkingChain, ToolCallLog, ReviewResultCard
│       │   ├── common/    # AppIcon, ConfirmDialog, FileRefCard, OutputPanel, StatusBadge, PathAccessDialog, OpenFileAuthDialog, LoadingPulse
│       │   ├── tools/     # ToolsPanel（工具箱面板）
│       │   ├── skills/    # SkillsPanel（技能中心：市场 + 管理 + 进化日志）
│       │   ├── scheduler/ # SchedulerPanel（定时任务管理）
│       │   └── mcp/       # McpPanel（MCP 服务器管理）
│       ├── composables/   # useAPI / useSSE 工具函数
│       ├── types/         # TypeScript 类型定义
│       ├── utils/         # 工具函数
│       │   ├── toolIcons.ts  # 工具图标映射
│       │   ├── export.ts     # 会话导出（Tauri 保存对话框 / 浏览器下载）
│       │   ├── upload.ts     # 图片上传工具
│       │   └── secretMask.ts # 密钥脱敏
│       └── assets/        # CSS 样式 (玻璃拟态暗色主题)
└── hub/                   # 示例 SkillHub（本地静态技能市场）
    ├── index.json         # 技能索引
    ├── build_hub.py       # 索引构建脚本
    └── skills/            # 示例技能包

可用工具

内置 50+ 个工具，覆盖日常办公、代码开发、项目管理等场景。另有 SkillHub 技能市场和 MCP 远程工具动态扩展能力。高危操作（删除、移动、覆盖、Git 写操作、高危 Shell 命令）执行前会弹窗请求用户确认。

文件管理（10）

read_file 读取文件 · write_file 写入文件 · append_file 追加内容 · list_directory 列目录 · copy_file 复制 · move_file 移动/重命名（需确认） · delete_file 删除（需确认） · create_directory 建目录 · search_files 按文件名搜索 · file_info 文件信息

文本处理（3）

search_in_files 文件内容正则搜索（grep） · replace_in_file 查找替换（需确认） · diff_files 文件差异对比

办公文档（9）

read_excel / write_excel Excel 读写（openpyxl） · read_word / write_word Word 读写（python-docx） · read_csv / write_csv CSV 读写 · read_pdf PDF 文本提取（pypdf） · create_pdf PDF 生成（fpdf2） · create_ppt PPT 生成（python-pptx）

图片处理（2）

convert_image 格式转换/缩放/压缩（Pillow） · image_info 图片信息

压缩解压（2）

zip_files 打包 ZIP · unzip_file 解压（防路径穿越）

代码开发（4）

execute_shell PowerShell 命令（高危拦截+确认） · run_python 执行 Python 脚本 · git_operation Git status/log/diff/add/commit · git_commits Git 提交历史查询

网络（3）

web_fetch 抓取网页 · web_search DuckDuckGo 搜索（免 Key） · download_file 下载文件

系统辅助（4）

calculator 安全数学计算 · get_datetime 日期时间 · clipboard 剪贴板读写 · system_info 系统信息

项目管理（3）

jira_unfinished_issues 查看未完成 Issue · jira_worklogs 查询工作日志 · jira_log_work 记录工时

技能管理（6）

create_skill AI 自建技能（需确认） · modify_skill 修改技能代码（需确认） · delete_skill 卸载技能 · list_skills 列出已安装技能 · search_skill_hub 搜索 SkillHub 技能市场 · install_skill_from_hub 从 Hub 安装技能（需确认）

定时任务（4）

create_scheduled_task 创建 cron 定时任务（需确认） · list_scheduled_tasks 列出任务 · delete_scheduled_task 删除任务（需确认） · run_scheduled_task_now 立即试跑（需确认）

MCP 工具（动态）

通过 Model Context Protocol 连接远程工具服务器，工作区级别管理，自动发现并注册工具。工具以 mcp_ 前缀标识，对 Maker 完全透明。

前端侧边栏对面的「工具箱」按钮可查看全部工具（分类展示 + 搜索）；工具箱内「定时」按钮管理定时任务（卡片展示下次触发/最近状态/启停/补跑），「技能」按钮打开技能中心（技能市场 / 我的技能 / 进化日志），「MCP」按钮管理外部工具服务器。

外挂技能系统

除内置工具外，xsun_chat 支持外挂式技能包 （skill.json + main.py，实现同一 Tool 协议），存放于应用数据目录 data/skills/installed/（旧版 ~/.xsun_chat/skills/ 首次启动自动迁移），启动时自动加载：

• SkillHub 安装 ：在技能中心搜索并一键安装，或将 skill_hub_url 指向任意兼容 Hub（GitHub Raw / 静态服务器 / 本地目录）。项目内 hub/ 是示例 Hub，运行 python hub/build_hub.py 即可打包生成索引。
• AI 自进化 ：对话中工具不够用时，AI 会主动 search_skill_hub 找现成技能，找不到就 create_skill 自己写一个------经 AST 安全扫描（禁 subprocess/eval 等）与用户审批后热加载，当前会话立即可用；modify_skill 修改失败自动回滚，所有变更记录于进化日志。

技术栈

层级	技术
桌面壳	Tauri 2.x (Rust)
前端	Vue 3 + TypeScript + Pinia + Vue Router
UI 主题	自定义 CSS Variables 玻璃拟态暗色主题
Markdown	markdown-it + highlight.js + KaTeX (数学公式)
后端	FastAPI + Uvicorn (ASGI)
LLM	OpenAI 兼容 SDK (AsyncOpenAI)，多供应商通过不同 base_url
数据库	SQLite + aiosqlite (WAL 模式，支持并发读)
HTTP	httpx (异步) + SSE (Server-Sent Events) 流式推送