# airboss **Repository Path**: oneto7/airboss ## Basic Information - **Project Name**: airboss - **Description**: Airboss：个人开发者的AI工作站实现思路（macOs-app+git开源） - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2026-10-18 - **Last Updated**: 2026-10-20 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README

Airboss

macOS 本地 AI 工作站控制台：一条 ai 命令 + 一个零依赖 Web 控制台。

选 agent、注入模型线路、建任务、看运行记录，并把 MCP / Skills 同步到 Codex、Claude Code、OpenCode 和 DeepSeek Harness。

Gitee · 发行版 · 架构 · 配置 · 安全 · 贡献

v1.0.0 · macOS 13+ · Node.js ≥ 20 · 零第三方运行时依赖 · MIT

![Airboss 控制台首页](docs/screenshots/home.png) > 截图来自脱敏的演示实例：项目路径、任务、运行记录、密钥和 MCP 配置都是示例数据，不是真实账号。 ## 目录 - [为什么做这个](#为什么做这个) - [功能总览](#功能总览) - [功能详解](#功能详解) - [启动器](#启动器) - [任务中心](#任务中心) - [项目](#项目) - [运行账本](#运行账本) - [工具](#工具) - [能力 MCP 与 Skills](#能力-mcp-与-skills) - [模型与线路](#模型与线路) - [设置与外观](#设置与外观) - [原生 App 与 PWA](#原生-app-与-pwa) - [命令行 ai](#命令行-ai) - [工作原理](#工作原理) - [安装](#安装) - [配置](#配置) - [常用命令](#常用命令) - [数据与安全](#数据与安全) - [开发与测试](#开发与测试) - [常见问题](#常见问题) - [当前限制](#当前限制) - [文档索引](#文档索引) - [贡献](#贡献) - [许可](#许可) ## 为什么做这个同时用 Codex、Claude Code、OpenCode 这类 CLI agent 时，麻烦通常不在模型本身，而在外围： - **工具太多**：每个 agent 有自己的命令、配置、会话目录和模型设置，切换成本高。 - **线路太散**：官方 API、国内兼容端点、中转服务和本地 LM Studio 混在一起，容易记错密钥和模型名。 - **任务会断档**：换一个 agent 继续同一件事时，目标、计划、交接信息容易丢。 - **运行不可见**：启动了哪个项目、用了哪条线路、跑了多久、改了什么，缺少统一记录。 - **数据要留在本地**：代码、提示词、密钥和运行账本都不应该上传到第三方控制台。 Airboss 的做法是把这些收进一个本地控制台：配置写在磁盘上的 JSON / Markdown 里，运行数据留在仓库目录，控制台只监听 `127.0.0.1`，不需要数据库、云端服务和前端构建。 ## 功能总览 | 模块 | 一句话说明 | |---|---| | [启动器](#启动器) | 搜索项目、选工具与线路，一条命令在 Terminal 里启动任意 agent | | [任务中心](#任务中心) | `TASK.md` / `PLAN.md` / `HANDOFF.md` 三段式任务，支持后台 headless 执行 | | [项目](#项目) | 扫描项目根目录，查看 Git 分支、脏文件、线路记忆和最近运行 | | [运行账本](#运行账本) | 每次启动写入 `runs.jsonl`：状态、耗时、退出码、日志和 `git diff` 摘要 | | [工具](#工具) | Codex / Claude Code / OpenCode / DeepSeek Harness 的安装、版本、更新和卸载 | | [能力](#能力-mcp-与-skills) | 以 `mcp/servers.json` 和 `skills/` 为单一事实源，同步到各工具的全局配置 | | [模型与线路](#模型与线路) | 管理供应商、端点、密钥、健康探测和每个工具的默认线路与兜底 | | [设置与外观](#设置与外观) | 主题 / 字体 / 字号 / 背景、中英双语、项目根目录、漂移检测与安全边界 | | [原生 App](#原生-app-与-pwa) | Swift + WKWebView 原生壳，也可直接浏览器访问或安装为 PWA | | [命令行](#命令行-ai) | `ai` 一条命令完成启动、线路、任务、自检和同步 | ## 功能详解 ### 启动器首页就是一个启动器：输入项目名或直接粘贴绝对路径，选 agent 和线路，回车启动。它解决的是「每天要重复选项目、选工具、选线路」的问题。 ![启动器](docs/screenshots/launcher.png) - **搜索即启动**：`⌘K` 聚焦搜索框，`Enter` 直接启动；也可以粘贴任意绝对路径，不在项目根目录里也能启动。 - **项目 × 工具线路记忆**：每个项目对 codex / claude 的线路选择写在 `state/project-routes.json`，下次打开自动沿用。 - **最近组合**：最近 4 个「项目 × 工具 × 线路」组合显示成 chip，数字键 `1`–`4` 可直接复跑。 - **线路兜底**：默认线路健康状态为 `err` 时，自动切到同一工具下可用的其它来源，并给出提示；显式指定 `--provider` 时不兜底（可用 `AI_NO_FALLBACK=1` 全局关闭）。 - **两种启动方式**：首页 / 项目页「启动 →」打开 Terminal 前台运行，保留 CLI 的交互 TUI；任务页「启动 →」走后台 headless 执行。 - **继续会话**：勾选「继续上次会话」等价于 `ai --continue`（codex 使用 `resume --last`）。 ### 任务中心任务不是 Todo，而是「交给 agent 干活的最小上下文包」，同时记录目标、计划和交接信息，避免换 agent 后从头解释。 ![任务中心](docs/screenshots/tasks.png) - **三段式文档**：每个任务对应 `tasks//` 下的 `TASK.md`（目标 / 验收标准 / 约束）、`PLAN.md`（计划 / 进度 / 决策）、`HANDOFF.md`（已完成 / 未完成 / 下一步 / 坑）。 - **状态流转**：`todo → running → review → done`。后台执行成功自动进入「待验收」，失败或取消退回「待处理」，手动改过的状态不会被覆盖。 - **新建任务**：标题 + 项目 + agent + 验收标准（每行一条），文件骨架自动生成。 - **按任务启动**：填写项目路径和提示词后后台执行，服务端提供任务文档与真实目录，运行与任务双向关联；结束弹出结果弹窗（运行期间变化 + 日志尾部），运行失败/超时可中止。 - **超时保护**：默认 30 分钟，先 `SIGTERM` 再按宽限期 `SIGKILL`，可用 `AI_TASK_TIMEOUT_MS` / `AI_TASK_KILL_GRACE_MS` 调整。 - **完成通知**：成功 / 失败发送 macOS 通知（主动取消不打扰）。 ### 项目项目页把「本机有哪些仓库、它们现在什么状态、最近用哪个线路跑过」放在一屏里。 ![项目](docs/screenshots/projects.png) - **扫描范围**：读取 `agents/project-roots.json`（首次用设置页添加），子目录即项目；`runs.jsonl` 里出现过、但不在扫描根里的目录也会合并进来。 - **Git 状态**：当前分支和脏文件数来自本地 `git status` / `git branch`。 - **收藏与搜索**：收藏项目置顶，支持按名称 / 路径搜索。 - **线路记忆**：详情面板直接显示该项目在 codex / claude 上记住的来源与模型，可一键启动。 - **最近运行**：项目维度的运行历史和状态，点任务运行可查看结果与改动。 - **快捷操作**：启动、打开目录、复制路径。 ### 运行账本每次从控制台发起的启动都会写入 `runs.jsonl`，一行一次运行，跑完自动收尾。它回答「昨天那个改动是哪个 agent、哪条线路、跑了多久改的」。 ![运行记录](docs/screenshots/runs.png) - **记录内容**：启动时间、agent、项目路径、provider / model、模式（交互 / 后台）、状态、退出码、耗时、日志路径、提示词和 `git diff` 摘要。 - **自动收尾**：交互启动通过 Terminal 启动脚本的 `trap` 回调结束状态；后台任务由服务端等待进程退出后写入。异常退出（进程已死但没回调）由 `janitor` 每 60 秒兜底标记为「已取消」。 - **筛选**：按项目 / agent / 状态过滤，右上角显示当前条数。 - **结果弹窗**：后台任务点「结果」查看工作区文件、`+/-` 行数和日志尾部；快照包含运行前已有改动与暂存改动，运行中可中止。 - **手动兜底**：状态卡在「进行中」时可手动标记成功 / 失败。 - **写入安全**：所有对 `runs.jsonl` 的修改都经过 `withRunsLock`，并用临时文件 + rename 原子替换，避免并发读写丢数据。 - **历史账本**：活动文件超过 1000 条或 8 MiB 后，在下次追加时将较旧的完成记录分段归档到 `archive/runs/`，保留最近 200 条完成记录、进行中记录和异常行。分段有可重建的字节索引；详情与更新不重写所有历史，运行页可继续加载更早记录。 - **恢复与备份**：归档通过事务日志恢复中断，不删除历史。备份账本时停止服务，并一起复制 `runs.jsonl`、`archive/runs/` 和 `state/run-rotation*`；只复制活动文件会遗漏历史。旧版本不会读取归档，降级前需保留完整备份。 ![运行结果（演示数据）](docs/screenshots/run-result.png) > 注意：只在控制台发起的运行会进账本，直接敲 `ai cx` / `ai exec` 不会写 `runs.jsonl`。 ### 工具工具页管理 agent CLI 与应用本体：装没装、什么版本、有没有更新、当前默认线路是什么。 ![工具](docs/screenshots/tools.png) - **定义在 `agents/tools.json`**：CLI 类（npm / brew 安装）和 App 类（如 DeepSeek Harness）分开处理。 - **版本与更新**：读取 `--version`，通过 npm registry 检查最新版本；支持单个更新、全部更新和「检查更新」预检。 - **安装 / 卸载**：未安装可一键安装；卸载需要二次确认，可勾选同时删除配置目录（会话会一并丢失）。 - **命令白名单**：安装 / 更新 / 卸载只允许 `npm`、`brew`、`rm`，执行前支持 `dry_run` 预演命令。 - **线路入口**：每个 agent 卡片显示当前生效线路，可直接用该 agent 启动。 ### 能力 MCP 与 Skills MCP 和 Skills 都只维护一份本机清单，再由控制台同步到各工具的全局配置，避免三个工具各写一份、互相覆盖。 **MCP**：`mcp/servers.json` 是唯一事实源。 ![能力 · MCP](docs/screenshots/capabilities-mcp.png) - 支持 `stdio` / `http` / `sse` 三种传输方式；密钥用 `${VAR}` 占位，明文只放在 `secrets.env`，`bin/mcp-run` 启动时展开。 - 每个服务器用 `apps` 数组声明启用范围，界面就是启用矩阵（Codex / Claude / OpenCode）。 - 同步只替换 Airboss 托管的条目：Codex 写 `~/.codex/config.toml` 的托管块，Claude / OpenCode 读写 JSON，手工条目保留；同步前自动备份。 - 状态卡会显示每个工具与 `servers.json` 是否一致（`OK` / 待同步），并统计缺失密钥、未同步工具。 - 删除服务器会留下托管标记（墓碑），下次同步时清理旧条目。 **Skills**：`skills//SKILL.md` 是定义源，`skills/registry.json` 是期望启用状态。 ![能力 · Skills](docs/screenshots/capabilities-skills.png) - `SKILL.md` 使用 frontmatter 声明 `name` / `description`，控制台可新建、编辑、删除（删除会移入 `archive/skills/`）。 - 启用状态会物化成三个工具全局 skills 目录里的软链；「同步 SKILLS」修复缺失、断链和残留，只管理指向本仓库的链接，外部同名目录/链接会跳过。 - 支持按 agent 批量启用 / 停用，显示「启用 N · 实际 N」和格式校验结果。 - 公开仓库默认只带 `skills/README.md` 和 `skills/registry.example.json`，第三方技能请自行确认许可后再添加。 ### 模型与线路模型页管理的是「这台机器可以用哪些模型来源、它们的密钥和健康状态、每个工具当前生效哪一条」。 ![模型](docs/screenshots/models.png) - **供应商定义在 `providers/providers.json`**：端点、协议（`wire_api`）、密钥变量名、模型列表、默认模型、厂商分组和备注。 - **生效线路在 `providers/routes.json`**：每个工具一条默认线路，启动器在项目没有记忆时使用它。 - **健康探测**：请求 `/models` 验证连通性和密钥（8 秒超时）；Claude 类端点没有 `/models` 时，用一次 `max_tokens=1` 的 Messages 请求验证鉴权（消耗约 1 token）。结果写入 `state/provider-health.json`，启动时自动探测一次，10 分钟内不重复。 - **密钥只进 `secrets.env`**：接口只返回是否已配置和掩码，写入后文件权限固定 `600`；key 不会出现在页面、日志或接口响应里。 - **模型管理**：可从端点拉取模型、手动添加模型名、删除自定义模型；删除后会自动修正 `routes.json` 和 codex 托管配置，避免线路指向不存在的模型。 - **「测试 / 配置 / 密钥」**：测试连通性、把某个来源设为该工具的生效线路、修改密钥。 - **协议约束**：Codex 线路必须是 `responses`，Claude 线路必须是 `anthropic`，OpenCode 使用自己的模型配置。 ![生效配置（演示数据）](docs/screenshots/models-apply.png) 「配置 → 应用生效」会写入 `routes.json`；如果是 Codex，还会写入 `~/.codex/config.toml` 的 `# >>> airboss managed` 块并备份旧配置，所以终端里直接敲 `codex` 也会用这条线路。 ### 设置与外观设置页放低频但重要的东西：外观、个人信息、路径、项目根目录、同步状态和安全边界。 ![设置](docs/screenshots/settings.png) - **主题 / 字体 / 字号**：石墨、深海、日光三套主题；等宽、系统无衬线、衬线三种字体；紧凑 / 标准 / 舒适三档字号，改完立即生效并记住。 - **背景图**：上传 PNG / JPEG / WebP，本机压缩到 1000px 内，可调透明度。 - **中英双语**：中文和 English 一键切换，偏好只存在本机。 - **我的信息**：署名、欢迎语和休息提醒只用于侧边栏和首页问候，保存在浏览器本地。 - **路径速查**：`AI_HOME`、`providers.json`、`routes.json`、`secrets.env`、`runs.jsonl` 等一行直达。 - **项目根目录**：只接受已存在目录，保存到 `agents/project-roots.json`。 - **同步与备份**：检测 `AGENTS.md` 到各工具的漂移，一键运行 `ai sync`；设置页可选择并确认恢复 Codex / Claude / OpenCode 的配置备份，恢复前自动保存当前文件供撤回。备份位于 `state/config-backups/`，归档的技能位于 `archive/skills/`。 - **安全边界**：把「本地 API 无身份认证」「密钥只注入 agent 进程」等取舍直接写在页面上。 ### 原生 App 与 PWA 控制台本身就是网页，可以三种方式使用：浏览器、安装为 PWA、或构建 macOS 原生壳。 - **原生 App**：`app/main.swift` 是 Swift + WKWebView 壳，负责窗口、菜单、页面导航回传和断线重试；菜单里 `⌘1`–`⌘8` 直接切页面。 - **构建**：`bin/build-app` 用 `swiftc` 编译，生成 `.icns`，ad-hoc 签名后安装到 `/Applications`（不可写时装到 `~/Applications`）。 - **PWA**：Safari「文件 → 添加到程序坞」或 Chrome「安装页面为应用」，窗口和图标与 App 类似。 - **热更新**：前端是静态文件，改完刷新即可；只有改 `main.swift` 才需要重新 `bin/build-app`。 ### 命令行 ai `bin/ai` 是 bash 分发器，负责 agent 别名、线路解析、密钥注入和任务命令。控制台的大部分能力都能在终端里用。 ```bash ai # 列出所有 agent 与安装状态 ai cx / ai cl / ai oc / ai dsh # 启动对应 agent ai cx --provider --model # 临时指定线路（不落盘） ai cx --profile local # 使用 profiles/local 启动配方 ai cx --continue # 继续该项目最近一次会话 ai exec codex "任务描述" # headless 非交互执行 ``` 线路解析顺序：显式 `--provider/--model` → 项目记忆 `state/project-routes.json` → 默认线路 `providers/routes.json`。默认线路不可用时自动兜底（`AI_NO_FALLBACK=1` 关闭）。密钥按行解析 `secrets.env` 后只注入子进程，不进入全局 shell；Codex 通过 `-c model_provider=...` 参数注入，Claude 通过 `ANTHROPIC_*` 环境变量注入。 ## 工作原理 Airboss 是「本地单用户 AI 工作站」的编排层，不实现模型能力。它负责选择 agent、注入线路、管理任务、记录运行，并把 MCP / Skills 同步到各工具。 ```text ┌─────────────────────────────────────────────────────────────┐ │ macOS / Terminal │ │ │ │ ai / bin/ai ───────────────┐ │ │ ├──> Codex CLI │ │ webapp/server.mjs ─────────┤ Claude Code │ │ │ ├──> OpenCode │ │ │ └──> DeepSeek Harness │ │ │ │ │ ├── webapp/public/ (no-build frontend) │ │ └── app/main.swift (Swift + WKWebView shell) │ │ │ │ config : providers/ agents/ mcp/ skills/ profiles/ │ │ runtime: runs.jsonl state/ logs/ tmp/ archive/ │ └─────────────────────────────────────────────────────────────┘ ``` 上半部分是入口（`bin/ai`、Web 控制台、原生壳），中间是它驱动的 agent，下半部分是配置真源与运行数据。三条主要链路： 1. **启动链路**：控制台 → `POST /api/launch` → 生成 `tmp/.command` → `open -a Terminal` 执行 `bin/ai` → 解析 agent 与线路 → 注入密钥 → 启动 agent。 2. **后台任务链路**：控制台 → `POST /api/task` → 服务端 `spawn(bin/ai exec ...)` → stdout / stderr 写入 `logs/tasks/.log` → 结束后写回 `runs.jsonl` 和任务状态。 3. **同步链路**：`mcp/servers.json` + `skills/registry.json` → 各工具全局配置（Codex 托管块、Claude / OpenCode JSON、skills 软链）→ 漂移检测。 Web 控制台是单文件、零依赖的 `node:http` 服务，所有 API 和业务逻辑都在 `webapp/server.mjs`。请求进入路由前依次经过 Host 白名单、Origin 校验和 JSON Content-Type 校验；静态文件限制在 `webapp/public/`。仓库结构： ```text airboss/ ├── bin/ ai 入口、sync、autostart、build-app、mcp-run、test ├── webapp/ │ ├── server.mjs 单文件 HTTP 服务 + 全部 API │ ├── public/ 无框架前端（index.html / app.js / styles.css / i18n.js） │ └── test/ smoke 测试（node:test） ├── app/ Swift + WKWebView 原生壳 ├── providers/ providers.json / routes.json ├── agents/ registry.json / tools.json / project-roots.example.json ├── profiles/ 启动配方（default / local / deep） ├── mcp/ servers.example.json ├── skills/ README.md / registry.example.json（第三方技能默认忽略） ├── tasks/ _TEMPLATE/（本机任务默认忽略） ├── docs/ 架构、配置、开源检查清单、截图 ├── runs.jsonl 运行账本（gitignore） ├── secrets.env 密钥（gitignore） └── state/ logs/ tmp/ archive/ 运行时数据（gitignore） ``` 更细的分层、请求管线、运行生命周期和关键不变量见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。 ## 安装 ### 环境要求 - macOS 13 或更高版本 - Node.js >= 20（开发环境使用 Node 24） - `jq`、`git`、`curl`、`lsof` - 可选：Xcode Command Line Tools（构建原生 App 和 `.icns` 时需要） - 可选：至少安装一个受支持的 agent 使用 Homebrew 时可以先安装基础依赖： ```bash brew install node jq ``` 安装 agent 的常见方式： ```bash npm i -g @openai/codex npm i -g @anthropic-ai/claude-code npm i -g @opencode/cli ``` DeepSeek Harness 使用其 macOS App；路径见 `agents/registry.json`。Linux 未做完整验证。 ### 快速开始 ```bash git clone https://gitee.com/oneto7/airboss.git ~/airboss cd ~/airboss # 1. 准备密钥文件（权限 600，已被 .gitignore 忽略） cp providers/providers.example.json providers/providers.json cp providers/routes.example.json providers/routes.json cp secrets.env.example secrets.env chmod 600 secrets.env ${EDITOR:-vi} secrets.env # 2. 把 ai 放进 PATH（建议写进 ~/.zshrc） export PATH="$HOME/airboss/bin:$PATH" # 3. 自检并启动控制台 ai doctor ai sync # 首次使用 agent CLI 时同步协作规则（可选） ai serve ``` 打开即可。`ai doctor` 会检查 Node 版本、依赖、`secrets.env` / `runs.jsonl` 权限、线路协议和端口。公开仓库默认不包含本机供应商目录、默认线路、项目根目录和 MCP 配置。供应商模板不预选模型或线路；填密钥后拉取/添加账号可用模型，再选择默认线路。CLI / Web 在本机供应商文件不存在时只读回退到模板，写入时使用本机文件。需要项目根与 MCP 时复制示例：使用 Git 从旧版升级前，先在仓库外备份 `providers/providers.json` 和 `providers/routes.json`：旧版跟踪这两个文件，拉取移除跟踪的提交时 Git 可能删除它们。升级后恢复备份；DMG 升级会保留已有配置。 ```bash cp agents/project-roots.example.json agents/project-roots.json cp mcp/servers.example.json mcp/servers.json ``` ### 下载 DMG 安装（不想用终端）当前最新版本：**[v1.0.0](https://gitee.com/oneto7/airboss/releases/tag/v1.0.0)**（macOS 13+，需要先安装 Node.js 20+ 和 jq）。 - 安装包：[Airboss-1.0.0.dmg](https://gitee.com/oneto7/airboss/releases/download/v1.0.0/Airboss-1.0.0.dmg)（2.8 MB） - 校验值：[Airboss-1.0.0.dmg.sha256](https://gitee.com/oneto7/airboss/releases/download/v1.0.0/Airboss-1.0.0.dmg.sha256)，下载后建议先核对： ```bash shasum -a 256 Airboss-1.0.0.dmg # 1e943b63f708699dd13c16584083907c25bcfbc0c31fab0b783e8e832ef0ebd6 ``` 安装步骤： 1. 先装依赖：`brew install node jq`； 2. 打开 DMG，双击「安装 Airboss.command」； 3. 安装器会检查 Node.js，把程序安装到 `~/airboss`、初始化 `secrets.env`、把 `ai` 加入 PATH，并可选安装登录自启； 4. 按提示编辑 `~/airboss/secrets.env` 填入 API Key，再打开「应用程序 → Airboss」。首次使用 agent CLI 前可运行 `ai sync` 同步协作规则；尚未同步会由 `ai doctor` 提示，但不会阻止启动控制台。安装包没有做 Apple 公证：首次打开 App 如果提示「无法验证开发者」，在「应用程序」里右键 Airboss →「打开」，或在「系统设置 → 隐私与安全性」里放行。升级时重新下载新版本 DMG 运行安装器即可，`secrets.env`、`runs.jsonl`、`state/` 等运行数据会保留；卸载在 DMG 里运行「卸载 Airboss.command」。历史版本和更新说明见 [Releases](https://gitee.com/oneto7/airboss/releases)。 > 维护者打包用 `bin/build-dmg`，版本号、DMG 内容和发布流程见 [docs/RELEASE.md](docs/RELEASE.md)；发版时记得同步更新本节和顶部的版本号。 ### 原生 App ```bash bin/build-app --open # 构建并安装到 /Applications/Airboss.app ai app # 已安装则打开 App，否则用浏览器打开 ``` `ai app` 在控制台没启动时会自动拉起服务；需要开机自启可以用： ```bash bin/autostart install # 安装 LaunchAgent，登录后自动启动控制台 bin/autostart status ``` ## 配置所有配置都是仓库目录里的文件，可以直接编辑，也可以走控制台： | 文件 | 作用 | |---|---| | `secrets.env` | 所有密钥；600 权限、gitignore、接口不返回明文 | | `providers/providers.json` | 供应商、端点、协议、密钥变量名、模型列表 | | `providers/routes.json` | 每个 agent 的默认 provider / model | | `agents/registry.json` | agent 命令、别名、headless 参数、会话目录 | | `agents/tools.json` | 「工具」页的安装 / 更新 / 卸载定义 | | `agents/project-roots.json` | 项目页扫描根目录（本机数据，默认忽略） | | `mcp/servers.json` | MCP 服务器清单和启用范围（本机数据，默认忽略） | | `skills/registry.json` | Skills 期望启用状态（本机数据，默认忽略） | | `profiles//` | 启动配方：`env.env` + `.args` | | `AGENTS.md` | agent 协作规则，也是 `ai sync` 的规则源 | ### 核心概念 | 概念 | 位置 | 说明 | |---|---|---| | Agent | `agents/registry.json` | Codex / Claude Code / OpenCode / DeepSeek Harness 的启动命令和别名 | | Provider | `providers/providers.json` | 供应商、端点、协议、密钥变量和模型列表 | | Route | `providers/routes.json` | 每个 agent 的默认 provider 和 model | | Profile | `profiles//` | 启动参数和环境变量配方，如 `default` / `local` / `deep` | | Task | `tasks//` | 目标、计划、交接和任务元数据 | | Run | `runs.jsonl` | 运行账本，记录启动、结束、耗时和改动摘要 | | MCP | `mcp/servers.json` | MCP 服务器清单和启用范围 | | Skill | `skills//SKILL.md` | 技能定义；`skills/registry.json` 记录启用状态 | ### 配置密钥所有密钥只放在仓库根目录的 `secrets.env`，变量名要与 `providers/providers.json` 里的 `auth_env` 对应： ```dotenv AI_KEY_DEEPSEEK_CODEX= AI_KEY_DEEPSEEK_CLAUDE= AI_KEY_GLM= AI_KEY_KIMI= AI_KEY_MINIMAX= ``` 编辑后运行： ```bash ai providers # 查看密钥是否已配置（不显示明文） ai models # 查看可用模型 ai use codex deepseek-codex deepseek-flash # 修改默认线路 ai doctor # 检查线路协议与密钥 ``` 新增供应商：在 `providers/providers.json` 加条目 → 在 `secrets.env` 加对应 `AI_KEY_*` → `ai providers` 验证 → 在「模型」页测试并应用生效。 ### 环境变量 | 变量 | 作用 | 默认 | |---|---|---| | `AI_HOME` | 工作站根目录 | 仓库根目录 | | `AI_SERVE_PORT` | 控制台端口 | `4317` | | `AI_HOME_NOTIFY` | 设为 `0` 关闭 macOS 完成通知 | 开启 | | `AI_ALLOW_DANGEROUS_PERMISSIONS` | 设为 `1` 时 Claude headless 使用 `--dangerously-skip-permissions` | 关闭 | | `AI_NO_FALLBACK` | 设为 `1` 关闭线路兜底 | 开启兜底 | | `AI_TASK_TIMEOUT_MS` | 后台任务超时 | `1800000`（30 分钟） | | `AI_TASK_KILL_GRACE_MS` | `SIGTERM` 后宽限期 | `5000` | | `AI_PROFILE` | 默认启动 profile | `default` | | `AI_APP_DIR` | 原生 App 安装目录 | `/Applications` | 完整字段和改法见 [docs/CONFIGURATION.md](docs/CONFIGURATION.md)。 ## 常用命令 ### 日常 ```bash ai # 列出 agent 与安装状态 ai cx / ai cl / ai oc / ai dsh ai exec codex "任务描述" ai status [--json] ai doctor ai serve # 前台启动控制台并打开浏览器 ai restart # 重启后台控制台服务（加载最新代码） ai app ai log [n] ai path ai completion install # 安装 zsh 补全 ``` ### 模型与供应商 ```bash ai providers # 供应商与密钥状态（不显示明文） ai models [provider] # 可用模型 ai use [model] # 修改默认线路 ai cx --provider --model # 单次临时线路 ``` ### 任务 ```bash ai task new "标题" --repo [--agent ] [--accept <标准>] ai task list ai task show [task|plan|handoff] ai task start [--project ] [--agent ] [--prompt ] ai task status [状态] ai task done ai task handoff ``` ### 同步与维护 ```bash ai sync # 把 AGENTS.md 同步到各工具 ai sync --check # 只检查漂移 ai sync --skills # 同步 Skills 软链 ai sync --skills --check bin/check # JavaScript / Shell 语法与 whitespace 检查 bin/test # 全部 webapp/test/*.mjs bin/check-public --ref HEAD # 检查待发布提交的文件快照 bin/build-app --open bin/autostart status ``` 完整参数以 `ai --help` 为准。 ### 快捷键 | 快捷键 | 作用 | |---|---| | `⌘K` | 聚焦启动器搜索框 | | `/` | 聚焦当前页面的搜索 / 筛选 | | `Enter` | 在启动器中直接启动 | | `1`–`4` | 启动最近组合（首页） | | `g` 然后 `h` / `a` / `p` / `r` / `t` / `c` / `m` / `s` | 跳转到首页 / 任务 / 项目 / 运行 / 工具 / 能力 / 模型 / 设置 | | `⌘1`–`⌘8` | 切换页面（仅原生 App 的菜单快捷键） | | `?` | 打开快速上手 | | `Esc` | 关闭弹层 | ## 数据与安全 Airboss 按「单用户、本机运行」设计： - 控制台只监听 `127.0.0.1`，默认端口 `4317`。 - Host 白名单用于阻断 DNS rebinding；带 `Origin` 的请求必须同源；写请求必须是 `application/json`。 - 静态文件限制在 `webapp/public/`；`/api/open` 有目录白名单和敏感目录黑名单。 - 工具安装 / 更新 / 卸载的命令白名单只有 `npm`、`brew`、`rm`，卸载需要二次确认。 - `secrets.env`、`runs.jsonl` 和工具配置权限为 `600`；`state/`、`logs/` 建议 `700`（`ai doctor` 会检查）。 - 密钥只注入 agent 子进程，不进入全局 shell；接口永不返回明文。 - 本地 API 没有身份认证。**不要把端口转发到局域网或公网，也不要让多用户共用同一个实例。** - `runs.jsonl` 会记录项目路径、提示词和改动摘要，分享日志前先脱敏。更完整的边界和取舍见 [SECURITY.md](SECURITY.md)。 ## 开发与测试没有 `package.json`、前端构建步骤或第三方 lint 配置；`bin/check` 用 Node / Bash 自带语法检查与 Git whitespace 检查，不替代语义审查。无 `.git` 的安装目录改为检查 `bin/`、`app/`、`webapp/` 的源码语法与行尾空白，不扫描本机任务、技能和运行数据。服务端和测试只使用 Node 标准库，前端是服务端直接返回的静态文件。 ```bash bin/check # 语法与 whitespace 静态检查 bin/test # 全部 webapp/test/*.mjs bin/check-public --ref HEAD # 发布快照检查，不输出命中值 bin/check-public --ref HEAD --history # 检查该引用可达历史，可能因旧私人数据失败 node --test --test-name-pattern "路径穿越" webapp/test/smoke.mjs node --check webapp/server.mjs node --check webapp/public/app.js AI_SERVE_PORT=4399 node webapp/server.mjs bin/build-app --no-install # 只构建原生 App bin/build-dmg # 构建 DMG 安装包到 dist/（见 docs/RELEASE.md） ``` 测试会启动真实服务（默认端口 4399 / 4398），需要允许本机监听。受限沙箱内可能因 `EPERM` 失败，应在普通终端运行。提交前至少运行： ```bash bin/test node --check webapp/server.mjs node --check webapp/public/app.js ``` 改动流程和代码约定见 [AGENTS.md](AGENTS.md) / [CLAUDE.md](CLAUDE.md)；开源发布前先完成 [docs/OPEN_SOURCE_CHECKLIST.md](docs/OPEN_SOURCE_CHECKLIST.md) 的检查。 ## 常见问题 **端口被占用怎么办？** `4317` 被占用时用 `AI_SERVE_PORT=4399 ai serve` 换端口。控制台已在运行时 `ai serve` 会直接复用现有实例，`ai restart` 用于加载最新代码。 **`ai doctor` 报缺少密钥或线路不兼容？** 先看 `ai providers` 的密钥状态，再确认 `providers/routes.json` 里的线路与协议匹配：Codex 必须是 `responses`，Claude 必须是 `anthropic`。 **应用 / 浏览器打开是空白页？** 先确认服务在运行（`curl 127.0.0.1:4317/api/status`）。原生 App 断线时会显示重试界面，也可以用 `ai restart` 重启服务后刷新。 **为什么运行页看不到我在终端里跑的 agent？** 目前只有控制台发起的运行会写入 `runs.jsonl`；直接执行 `ai cx` / `ai exec` 不记录。见[当前限制](#当前限制)。 **公开仓库为什么没有我本机的 Skills / MCP / 任务？** `tasks/*`、`mcp/servers.json`、`agents/project-roots.json`、`skills/*` 都是本机数据，已被 `.gitignore` 忽略；公开仓库只保留示例和模板。第三方技能还需要逐个确认许可。 **页面上的截图和我的界面不一样？** 截图来自演示实例，字体渲染、主题和演示数据会与实际使用不同；功能入口是一致的。 ## 当前限制 - MCP 与 Skills 只做全局层，尚无项目级覆盖。 - 技能启停以软链为准；手工移动或删除链接后，需要运行 `ai sync --skills` 或在能力页同步。 - 直接运行 `ai cx` / `ai exec` 暂不写入 `runs.jsonl`，控制台只能看到控制台发起的运行。 - 账本归档限制常见写入成本；活动记录和单条超大记录仍可能扩大文件，历史检索需扫描分段索引，尚无数据库式全局索引。 - `state/project-routes.json` 只记录项目 + agent 的线路，不记录任务级偏好。 - 原生 App、LaunchAgent、Terminal 启动和 macOS 通知都是 macOS 专属实现；Linux 未做完整验证。 - 公开仓库默认只带 `skills/README.md` 和 `skills/registry.example.json`；第三方技能目录需要自行添加并确认许可。 - `agents/project-roots.json`、`mcp/servers.json`、`tasks/*` 和 `skills/*` 是本机数据，默认被 `.gitignore` 忽略。 ## 文档索引 | 文档 | 内容 | |---|---| | [Gitee Releases](https://gitee.com/oneto7/airboss/releases) | DMG 安装包下载、版本历史与发行说明 | | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | 分层架构、请求管线、运行生命周期、关键不变量 | | [docs/CONFIGURATION.md](docs/CONFIGURATION.md) | 各配置文件的字段、示例和常用改法 | | [docs/OPEN_SOURCE_CHECKLIST.md](docs/OPEN_SOURCE_CHECKLIST.md) | 开源发布前的隐私、许可和历史清理检查 | | [docs/RELEASE.md](docs/RELEASE.md) | 版本号、DMG 构建、Gitee Releases 发布与校验流程 | | [AGENTS.md](AGENTS.md) | agent 协作规则，也是 `ai sync` 的规则源 | | [CLAUDE.md](CLAUDE.md) | Claude Code 的仓库入口说明 | | [CONTRIBUTING.md](CONTRIBUTING.md) | Gitee 贡献流程和提交规范 | | [SECURITY.md](SECURITY.md) | 安全模型和漏洞报告方式 | | [skills/README.md](skills/README.md) | 技能库约定、来源和许可说明 | | [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) | 第三方技能、素材的来源和许可说明 | | [docs/screenshots/](docs/screenshots/) | README 使用的界面截图（演示数据） | ## 贡献欢迎在 Gitee 提 Issue 或 Pull Request。提交前请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)，并确认没有提交密钥、个人路径、真实数据库地址或未授权的第三方内容。适合上手的方向：文档与示例补全、UI 细节与可访问性、测试覆盖、Linux 兼容性验证。 ## 许可本项目使用 MIT License，详见 [LICENSE](LICENSE)。`skills/` 下的部分技能来自第三方，不自动适用根许可证；分发前请逐个确认，详见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。