默认中文 / English version: README_EN.md

AgentOS 是一个面向本地项目与长期任务的桌面 Agent 工作台。它不是把大模型包装成一个聊天窗口，而是把「项目文件夹」变成 Agent 的运行空间：对话、技能、可视化卡片、任务编排、项目记忆和本地文件上下文，都围绕同一个文件夹组织起来。

项目的后台运行层由 Electron 主进程中的 Claude Agent SDK 驱动，负责会话流式输出、会话恢复、权限请求、工具调用和任务执行；前端只负责呈现和交互。

我们的愿景是让每个项目都拥有自己的 Agent 操作系统。用户不需要先理解复杂的 Agent 框架，也不需要把项目资料搬到云端；只要选择一个本地文件夹，AgentOS 就可以围绕这个文件夹建立上下文、沉淀记忆、运行 Skills、展示数据面板，并逐步形成一个可以长期协作的智能工作区。

• 项目愿景
• 项目分支
• 项目特点
• 当前功能
• 下载安装
• 开发运行
• 项目约定
• 作者
• 联系方式

AgentOS 想解决的问题是：Agent 不应该只存在于一次性的聊天里。

真正有用的 Agent 需要知道它正在服务哪个项目，需要记得项目里的约定，需要能把运行结果变成可读、可点、可继续操作的界面，也需要能把多个技能按顺序或按时间执行。AgentOS 因此把 Agent 的边界放回到用户最熟悉的地方：文件夹。

在 AgentOS 里，一个文件夹可以逐渐长出自己的指令、记忆、技能、任务卡片、数据卡片和会话历史。你可以把它当作一个个人工作台，也可以把它当作开发自己 Agent 产品的框架基础。

这个项目有三个定位不同的分支：

如果你只是想使用产品，请优先下载 main 分支发布的 Release。
如果你想研究代码或做自己的产品，请从 AgentOS-Framework 开始。
如果你想看最新想法和不稳定实验，可以关注 AgentOS-Experimental。

AgentOS 的核心不是「新建一个机器人」，而是「选择一个项目文件夹」。项目文件夹里的 AGENT.md、SOUL.md、MEMORY.md、memory/、.agents/skills/、.agents/home-plugins/ 等内容，会共同构成这个 Agent 的身份、长期记忆、技能和可视化界面。

这意味着 Agent 不再是孤立的对话窗口，而是和你的项目文件、项目规则、历史记录、任务计划绑定在一起。

在 AgentOS 里，Agent 不只是会回复文字：

• Chat：通过对话理解需求、执行任务、解释过程。
• 数据可视化：通过 Home Plugin 和 A2UI 卡片展示项目状态、数据结果、任务进度和自定义面板。
• 可交互内容：卡片可以带按钮、状态、刷新、打开文件、执行任务等交互。
• 记忆：通过项目级指令、记忆文件和每日记忆目录，让 Agent 逐渐理解项目背景和协作方式。

这也是 AgentOS 与普通聊天工具最大的区别：它关心 Agent 如何长期住在一个项目里，而不只是完成一次问答。

• 支持添加多个本地项目文件夹，每个文件夹都可以成为独立 Agent 工作区。
• 支持每个项目下创建多个会话线程。
• 支持会话置顶、归档、排序和持久化。
• 支持恢复 Claude Agent SDK 的会话 sessionId，应用重启后可以继续上下文。
• 侧边栏会按项目组织会话，并可显示项目级 Skills。

• 支持扫描项目中的 .agents/skills/、.claude/skills/ 等 Skill 目录。
• 支持在侧边栏直接运行项目 Skill。
• 支持通过任务卡片选择「基于当前 Agent.md 运行」或「编排多个 Skills」。
• Skill 编排可以重复运行，当前支持最多 100 次。
• 支持定时执行和循环执行，间隔包含 1 小时、2 小时、3 小时、6 小时、12 小时和 1 天。
• 任务运行会映射到独立会话线程，并可以在运行中停止。

说明：当前定时任务依赖 Electron 进程存活，不是系统级后台守护进程。

• 项目首页支持 Home Plugin 卡片系统。
• 支持数据卡片和任务卡片两类卡片。
• 卡片输出使用 A2UI v0.9，可展示结构化、可交互的内容。
• 支持 small / medium / large 三种卡片尺寸。
• 支持卡片排序、尺寸调整、刷新和单卡片编辑。
• 支持从卡片动作打开项目文件、刷新内容、执行任务或停止任务。

• 可为项目自动生成或补齐 CLAUDE.md、AGENT.md、SOUL.md、MEMORY.md、memory/。
• 可开启 TODO 模式，生成并维护 TODO.md。
• 支持在设置中编辑项目级 USER / IDENTITY 文案，让 Agent 更明确地理解用户和自身角色。
• Agent Mode 的上下文会被注入到 Agent 运行环境中。

• 支持选择本地项目目录。
• 支持项目文件树浏览、展开、刷新和文件预览。
• 支持预览 Markdown、JSON、普通文本和图片。
• 输入框支持 @ 搜索并引用项目文件、文件夹或子 Agent。
• 输入框支持添加文本附件和图片附件，图片能力会根据当前模型配置判断是否可用。

• 输入 / 可以唤起内置命令、项目 Skills、项目 Commands。
• 支持全局和项目级上下文来源，包括 .claude、.agent、.agents、.cursor。
• 支持读取 AGENT.md / AGENTS.md 作为项目指令。
• 支持发现子 Agent 定义，并在输入框中通过 @ 引用。

• 对话时间线会展示模型响应、工具调用、thinking、活动状态和运行耗时。
• 支持权限模式选择，包括 Plan、Auto、Default、Accept Edits、Bypass Permissions。
• Agent 需要用户确认或补充信息时，会在界面中弹出交互式确认。
• 支持展示文件变更 diff，并提供文件回滚入口。

• 支持多模型提供商配置，可在设置页维护 API Key、Base URL、模型和模型档位映射。
• 支持通过聊天输入框旁的模型菜单切换当前对话使用的配置。
• 支持中文 / English 双语界面，默认中文。
• 支持 macOS 隐藏标题栏、侧栏 vibrancy、托盘菜单、关闭到托盘和开机启动偏好。
• 支持 GitHub Releases 应用内更新检查、下载和安装。

1. 打开 AgentOS Releases。
2. 下载适合你系统的安装包：
   • macOS：AgentOS-Mac-x.y.z-Installer.dmg
   • Windows：AgentOS-Windows-x.y.z-Setup.exe
   • Linux：AgentOS-Linux-x.y.z.AppImage，如果当前 Release 提供该文件
3. 安装并启动 AgentOS。
4. 在设置页配置模型服务，或使用默认环境配置。
5. 选择一个本地项目文件夹，开始创建会话、运行 Skill 或添加 Agent 卡片。

如果你想基于 AgentOS 框架开发自己的产品，建议使用 AgentOS-Framework 分支：

git clone https://github.com/xue160709/AgentOS.git
cd AgentOS
git checkout AgentOS-Framework
npm install
npm run dev

如果你想体验产品分支：

git checkout main
npm install
npm run dev

如果你想查看实验分支：

git checkout AgentOS-Experimental
npm install
npm run dev

• Node.js 18+
• npm

开发模式下可以复制 .env.example：

cp .env.example .env.local

常见变量：

已安装应用的普通用户也可以直接在「设置」里维护模型配置。

AgentOS 会围绕项目目录读取和生成上下文。一个典型项目可以长这样：

your-project/
├── CLAUDE.md                 # Claude 原生入口，指向 AgentOS 上下文
├── AGENT.md                  # 项目 Agent 指令
├── SOUL.md                   # 项目愿景、价值观、长期身份
├── MEMORY.md                 # 项目级记忆
├── TODO.md                   # TODO 模式任务文件
├── memory/                   # 每日记忆
├── .agents/
│   ├── skills/               # 项目 Skills
│   ├── agents/               # 项目子 Agent
│   └── home-plugins/         # 项目首页卡片
├── .claude/                  # Claude 原生上下文，可选
└── .cursor/                  # Cursor 规则或兼容上下文，可选

其中 .agents/home-plugins/ 是项目首页卡片系统的核心目录。每张卡片可以读取项目文件、生成 A2UI 输出，并在 AgentOS 首页渲染为数据卡片或任务卡片。

• Electron
• React
• TypeScript
• Vite
• Claude Agent SDK
• A2UI
• electron-builder
• marked + DOMPurify

• 自动生成 SKILL 和 Agent。
• 预置更多模型厂商数据。

• 融入记忆模块。
• 加强 Chat 和数据卡片的关联。
• 自主优化 SKILL。

• 将所有 UI 组件重构，支持意图理解。

• 作者：xuezhirong
• 邮箱：xue160709@gmail.com
• GitHub：@xue160709
• 微信：xuezhirong233

如果想交流想法、反馈问题或参与共创，可以通过上方作者信息联系，或加微信：xuezhirong233。

• 感谢 Anthropic 提供 Claude Code 的二进制文件，不然这个项目很难把本地 Agent 运行层真正落到桌面工作台里。
• 感谢 歸藏 分享 chat 里交互式 UI 的技术方案，https://x.com/op7418/status/2033113845120807170，不然我们很难把对话里的互动体验做得这么顺。
• 感谢 OpenClaw 提供 SOUL.md、USER.md、Identify.md 的灵感，https://openclaw.ai/，不然我们很难把项目的身份、用户和边界梳理得这么清楚。
• 感谢 Codex APP 在 UI 框架设计上给了很多参考和启发，让这个桌面壳的布局、层级和交互更顺手。

MIT