spherse-guide

Spherse 使用指南

Spherse 是一个本地运行、开箱即用的个人 Agent 运行时。一个普通文件夹就是一个项目，多个拥有独立提示词、工具、Skill、MCP、自动化和会话的 Agent 围绕同一份用户文件协作。Agent 还可以生成 HTML 页面，并通过 UI SDK 把文件、会话和数据能力组合成可交互的 Workspace。

核心概念

项目

项目就是用户磁盘上的普通文件夹：

project-root/
├── AGENTS.md
├── CHANGELOG.md
├── 用户文件...
└── .spherse/
    ├── project.yaml
    ├── theme.css
    ├── skills/
    └── agents/

• 普通文件是项目主体，可继续使用外部编辑器和版本控制管理。
• AGENTS.md 是所有 Agent 共享的项目指令。
• CHANGELOG.md 可由启用了 append_changelog 的 Agent 追加记录。
• .spherse 保存项目 ID、Agent、会话、主题、Skill、MCP、触发器等平台元数据。
• 桌面端可以同时打开多个项目，并从左侧项目头像切换。

Agent

每个 Agent 都有独立的：

• 名称、别名和 system prompt
• 启用的工具
• 预加载上下文文件
• 会话历史
• 聊天主题
• MCP 连接器
• 触发器
• 私有 Skill 和记忆数据

Agent 创建界面可配置 Prompt、工具、上下文文件、时间感知、聊天主题和 YOLO 模式。工具必须显式启用；未启用的工具不会交给模型。

新建项目会自带一个预设 Agent「小助手」：通用型助手，默认开启除 run_command 外的全部工具，可随时在界面中修改或删除。

会话

同一个 Agent 可以拥有多个互相独立的会话。用户可以：

• 新建、打开、重命名、删除和导出会话
• 查看流式回复、工具调用、文件 diff、命令输出和 token 使用
• 中止正在生成的回复或重试失败的回复
• 回答 Agent 的问题，批准或拒绝危险操作
• 在桌面端将一个会话浮动为可拖拽窗口
• 在文档中划选文字，附带来源发送给现有会话或新 Agent

切换页面不会终止后台运行。一个会话同一时间只能执行一个 turn；忙碌时不会排队第二条消息。

功能地图

项目文件与内容浏览

桌面端 Files 区域支持浏览、新建、编辑、保存、删除文件和目录，也可以复制项目相对路径或将文件打开为多个浮窗。

Content Browser 支持：

• Markdown 与 YAML frontmatter
• HTML 预览和源码切换
• 图片预览
• 普通文本编辑与搜索
• 外部文件变化自动刷新
• 二进制文件交给系统默认应用打开

用户可在 Files 区域配置“AI 读取限制”，禁止 Agent 读取和写入指定项目路径。该策略不限制 run_command 启动的子进程。

项目欢迎页

项目根路由可以展示一个自定义 HTML 页面或图片（html、png、webp、svg 等常见格式），适合作为项目首页、导航入口、仪表盘或世界观导览。

配置方式：左侧活动栏右键当前项目头像 →「设置 → 欢迎页」→ 填写项目内相对路径，或者由启用了 manage_project_config 工具的 Agent 在对话中设置（路径会经过校验）。清空配置可恢复默认；未显式配置时自动尝试项目根目录的 index.html。欢迎页文件或 project.yaml 配置被修改后会自动刷新；文件缺失或加载失败时回退到默认空状态。

工具与审批

常见工具类别：

目的	工具
文件读取	read_file、list_files、search_content
文件修改	write_file、edit_file、move_file、copy_file
结构化数据	read_data、query_data、mutate_data
交互与展示	ask_user、render_card、generate_image
项目协作	append_changelog、load_skill、emit_trigger_event
记忆	memory_save、memory_recall
高级操作	run_command、manage_agent、manage_trigger、manage_project_config（Agent 配置界面中三个 manage_* 合并为单一「管理项目」选项，勾选即同时启用）