Airboss：个人开发者的AI工作站实现思路（macOs-app+git开源）

Airboss

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

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

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

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

截图来自脱敏的演示实例：项目路径、任务、运行记录、密钥和 MCP 配置都是示例数据，不是真实账号。

为什么做这个

同时用 Codex、Claude Code、OpenCode 这类 CLI agent 时，麻烦通常不在模型本身，而在外围：

• 工具太多：每个 agent 有自己的命令、配置、会话目录和模型设置，切换成本高。
• 线路太散：官方 API、国内兼容端点、中转服务和本地 LM Studio 混在一起，容易记错密钥和模型名。
• 任务会断档：换一个 agent 继续同一件事时，目标、计划、交接信息容易丢。
• 运行不可见：启动了哪个项目、用了哪条线路、跑了多久、改了什么，缺少统一记录。
• 数据要留在本地：代码、提示词、密钥和运行账本都不应该上传到第三方控制台。

Airboss 的做法是把这些收进一个本地控制台：配置写在磁盘上的 JSON / Markdown 里，运行数据留在仓库目录，控制台只监听127.0.0.1，不需要数据库、云端服务和前端构建。

目录导航

本文档较长，为方便快速跳转，这里提供一份自动生成的目录导航。CSDN 编辑器支持在正文中插入目录锚点，读者点击即可定位到对应章节。

• 为什么做这个
• 功能总览
• 功能详解
  • 启动器
  • 任务中心
  • 项目
  • 运行账本
  • 工具
  • 能力 MCP 与 Skills
  • 模型与线路
  • 设置与外观
  • 原生 App 与 PWA
  • 命令行 ai
• 工作原理
• 安装
  • 环境要求
  • 快速开始
  • 下载 DMG 安装（不想用终端）
  • 原生 App
• 配置
  • 核心概念
  • 配置密钥
  • 环境变量
• 常用命令
  • 日常
  • 模型与供应商
  • 任务
  • 同步与维护
  • 快捷键
• 数据与安全
• 开发与测试
• 常见问题
• 当前限制
• 文档索引
• 贡献
• 许可

提示：CSDN 编辑器会根据正文中的##/###标题自动生成锚点，上面的链接与标题一一对应；若后续增删章节，记得同步更新这份目录。

功能总览

功能详解

启动器

首页就是一个启动器：输入项目名或直接粘贴绝对路径，选 agent 和线路，回车启动。它解决的是「每天要重复选项目、选工具、选线路」的问题。

• 搜索即启动：⌘K聚焦搜索框，Enter直接启动；也可以粘贴任意绝对路径，不在项目根目录里也能启动。
• 项目 × 工具线路记忆：每个项目对 codex / claude 的线路选择写在state/project-routes.json，下次打开自动沿用。
• 最近组合：最近 4 个「项目 × 工具 × 线路」组合显示成 chip，数字键1–4可直接复跑。
• 线路兜底：默认线路健康状态为err时，自动切到同一工具下可用的其它来源，并给出提示；显式指定--provider时不兜底（可用AI_NO_FALLBACK=1全局关闭）。
• 两种启动方式：首页 / 项目页「启动 →」打开 Terminal 前台运行，保留 CLI 的交互 TUI；任务页「启动 →」走后台 headless 执行。
• 继续会话：勾选「继续上次会话」等价于ai <agent> --continue（codex 使用resume --last）。

任务中心

任务不是 Todo，而是「交给 agent 干活的最小上下文包」，同时记录目标、计划和交接信息，避免换 agent 后从头解释。

• 三段式文档：每个任务对应tasks/<id>/下的TASK.md（目标 / 验收标准 / 约束）、PLAN.md（计划 / 进度 / 决策）、HANDOFF.md（已完成 / 未完成 / 下一步 / 坑）。
• 状态流转：todo → running → review → done。后台执行成功自动进入「待验收」，失败或取消退回「待处理」，手动改过的状态不会被覆盖。
• 新建任务：标题 + 项目 + agent + 验收标准（每行一条），文件骨架自动生成。
• 按任务启动：填写项目路径和提示词后后台执行，服务端提供任务文档与真实目录，运行与任务双向关联；结束弹出结果弹窗（运行期间变化 + 日志尾部），运行失败/超时可中止。
• 超时保护：默认 30 分钟，先SIGTERM再按宽限期SIGKILL，可用AI_TASK_TIMEOUT_MS/AI_TASK_KILL_GRACE_MS调整。
• 完成通知：成功 / 失败发送 macOS 通知（主动取消不打扰）。

项目

项目页把「本机有哪些仓库、它们现在什么状态、最近用哪个线路跑过」放在一屏里。

• 扫描范围：读取agents/project-roots.json（首次用设置页添加），子目录即项目；runs.jsonl里出现过、但不在扫描根里的目录也会合并进来。
• Git 状态：当前分支和脏文件数来自本地git status/git branch。
• 收藏与搜索：收藏项目置顶，支持按名称 / 路径搜索。
• 线路记忆：详情面板直接显示该项目在 codex / claude 上记住的来源与模型，可一键启动。
• 最近运行：项目维度的运行历史和状态，点任务运行可查看结果与改动。
• 快捷操作：启动、打开目录、复制路径。

运行账本

每次从控制台发起的启动都会写入runs.jsonl，一行一次运行，跑完自动收尾。它回答「昨天那个改动是哪个 agent、哪条线路、跑了多久改的」。

• 记录内容：启动时间、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*；只复制活动文件会遗漏历史。旧版本不会读取归档，降级前需保留完整备份。

注意：只在控制台发起的运行会进账本，直接敲ai cx/ai exec不会写runs.jsonl。

工具

工具页管理 agent CLI 与应用本体：装没装、什么版本、有没有更新、当前默认线路是什么。

• 定义在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是唯一事实源。

• 支持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/<name>/SKILL.md是定义源，skills/registry.json是期望启用状态。

• SKILL.md使用 frontmatter 声明name/description，控制台可新建、编辑、删除（删除会移入archive/skills/）。
• 启用状态会物化成三个工具全局 skills 目录里的软链；「同步 SKILLS」修复缺失、断链和残留，只管理指向本仓库的链接，外部同名目录/链接会跳过。
• 支持按 agent 批量启用 / 停用，显示「启用 N · 实际 N」和格式校验结果。
• 技能市场目前只接 SkillHub：可搜索、安装、检查更新；每个技能只保留一个来源，更新必须从安装时的同一来源进行。
• 搜索结果默认按下载量做受欢迎排序，也可切回最相关；点击技能名会打开对应的 SkillHub 详情页。
• 更新检查是自动的，应用更新需要手动确认；本地内容有修改时会先阻断，确认后才归档旧目录并覆盖。
• 下载由服务端通过固定 API 源发起，默认请求api.skillhub.cn；安装包限制大小、文件数，并拒绝路径穿越、符号链接和根目录缺少SKILL.md的包。
• 公开仓库默认只带skills/README.md和skills/registry.example.json，第三方技能请自行确认许可后再添加。

模型与线路

模型页管理的是「这台机器可以用哪些模型来源、它们的密钥和健康状态、每个工具当前生效哪一条」。

• 供应商定义在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 使用自己的模型配置。

「配置 → 应用生效」会写入routes.json；如果是 Codex，还会写入~/.codex/config.toml的# >>> airboss managed块并备份旧配置，所以终端里直接敲codex也会用这条线路。

设置与外观

设置页放低频但重要的东西：外观、个人信息、路径、项目根目录、同步状态和安全边界。

• 主题 / 字体 / 字号：石墨、深海、日光三套主题；等宽、系统无衬线、衬线三种字体；紧凑 / 标准 / 舒适三档字号，改完立即生效并记住。
• 背景图：上传 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 别名、线路解析、密钥注入和任务命令。控制台的大部分能力都能在终端里用。

ai# 列出所有 agent 与安装状态ai cx / ai cl / ai oc / ai dsh# 启动对应 agentai cx--provider<id>--model<model># 临时指定线路（不落盘）ai cx--profilelocal# 使用 profiles/local 启动配方ai cx--continue# 继续该项目最近一次会话aiexeccodex"任务描述"# 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 同步到各工具。

┌─────────────────────────────────────────────────────────────┐ │ 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/<run-id>.command→open -a Terminal执行bin/ai→ 解析 agent 与线路 → 注入密钥 → 启动 agent。
2. 后台任务链路：控制台 →POST /api/task→ 服务端spawn(bin/ai exec ...)→ stdout / stderr 写入logs/tasks/<run-id>.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/。

仓库结构：

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。

安装

环境要求

• macOS 13 或更高版本
• Node.js >= 20（开发环境使用 Node 24）
• jq、git、curl、lsof
• 可选：Xcode Command Line Tools（构建原生 App 和.icns时需要）
• 可选：至少安装一个受支持的 agent

使用 Homebrew 时可以先安装基础依赖：

brewinstallnodejq

安装 agent 的常见方式：

npmi-g@openai/codexnpmi-g@anthropic-ai/claude-codenpmi-g@opencode/cli

DeepSeek Harness 使用其 macOS App；路径见agents/registry.json。Linux 未做完整验证。

快速开始

gitclone https://gitee.com/oneto7/airboss.git ~/airbosscd~/airboss# 1. 准备密钥文件（权限 600，已被 .gitignore 忽略）cpproviders/providers.example.json providers/providers.jsoncpproviders/routes.example.json providers/routes.jsoncpsecrets.env.example secrets.envchmod600secrets.env${EDITOR:-vi}secrets.env# 2. 把 ai 放进 PATH（建议写进 ~/.zshrc）exportPATH="$HOME/airboss/bin:$PATH"# 3. 自检并启动控制台ai doctor aisync# 首次使用 agent CLI 时同步协作规则（可选）ai serve

打开 http://127.0.0.1:4317 即可。ai doctor会检查 Node 版本、依赖、secrets.env/runs.jsonl权限、线路协议和端口。

公开仓库默认不包含本机供应商目录、默认线路、项目根目录和 MCP 配置。供应商模板不预选模型或线路；填密钥后拉取/添加账号可用模型，再选择默认线路。CLI / Web 在本机供应商文件不存在时只读回退到模板，写入时使用本机文件。需要项目根与 MCP 时复制示例：

使用 Git 从旧版升级前，先在仓库外备份providers/providers.json和providers/routes.json：旧版跟踪这两个文件，拉取移除跟踪的提交时 Git 可能删除它们。升级后恢复备份；DMG 升级会保留已有配置。

cpagents/project-roots.example.json agents/project-roots.jsoncpmcp/servers.example.json mcp/servers.json

下载 DMG 安装（不想用终端）

当前最新版本：v1.1.0（macOS 13+，需要先安装 Node.js 20+ 和 jq）。

• 安装包：Airboss-1.1.0.dmg
• 校验值：Airboss-1.1.0.dmg.sha256，下载后建议先核对：

shasum-a256Airboss-1.1.0.dmg# 输出应与 Release 附件中的 .sha256 内容一致

安装步骤：

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。

维护者打包用bin/build-dmg，版本号、DMG 内容和发布流程见 docs/RELEASE.md；发版时记得同步更新本节和顶部的版本号。

原生 App

bin/build-app--open# 构建并安装到 /Applications/Airboss.appai app# 已安装则打开 App，否则用浏览器打开

ai app在控制台没启动时会自动拉起服务；需要开机自启可以用：

bin/autostartinstall# 安装 LaunchAgent，登录后自动启动控制台bin/autostart status

配置

所有配置都是仓库目录里的文件，可以直接编辑，也可以走控制台：

核心概念

配置密钥

所有密钥只放在仓库根目录的secrets.env，变量名要与providers/providers.json里的auth_env对应：

AI_KEY_DEEPSEEK_CODEX= AI_KEY_DEEPSEEK_CLAUDE= AI_KEY_GLM= AI_KEY_KIMI= AI_KEY_MINIMAX=

编辑后运行：

ai providers# 查看密钥是否已配置（不显示明文）ai models# 查看可用模型ai use codex deepseek-codex deepseek-flash# 修改默认线路ai doctor# 检查线路协议与密钥

新增供应商：在providers/providers.json加条目 → 在secrets.env加对应AI_KEY_*→ai providers验证 → 在「模型」页测试并应用生效。

环境变量

完整字段和改法见 docs/CONFIGURATION.md。

常用命令

日常

ai# 列出 agent 与安装状态ai cx / ai cl / ai oc / ai dsh aiexeccodex"任务描述"ai status[--json]ai doctor ai serve# 前台启动控制台并打开浏览器ai restart# 重启后台控制台服务（加载最新代码）ai app ai log[n]ai path ai completioninstall# 安装 zsh 补全

模型与供应商

ai providers# 供应商与密钥状态（不显示明文）ai models[provider]# 可用模型ai use<agent><provider>[model]# 修改默认线路ai cx--provider<id>--model<m># 单次临时线路

任务

ai task new"标题"--repo<path>[--agent<a>][--accept<标准>]ai task list ai task show<id>[task|plan|handoff]ai task start<id>[--project<path>][--agent<a>][--prompt<text>]ai task status<id>[状态]ai taskdone<id>ai task handoff<id>

同步与维护

aisync# 把 AGENTS.md 同步到各工具aisync--check# 只检查漂移aisync--skills# 同步 Skills 软链aisync--skills--checkbin/check# JavaScript / Shell 语法与 whitespace 检查bin/test# 全部 webapp/test/*.mjsbin/check-public--refHEAD# 检查待发布提交的文件快照bin/build-app--openbin/autostart status

完整参数以ai --help为准。

快捷键

数据与安全

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。

开发与测试

没有package.json、前端构建步骤或第三方 lint 配置；bin/check用 Node / Bash 自带语法检查与 Git whitespace 检查，不替代语义审查。无.git的安装目录改为检查bin/、app/、webapp/的源码语法与行尾空白，不扫描本机任务、技能和运行数据。服务端和测试只使用 Node 标准库，前端是服务端直接返回的静态文件。

bin/check# 语法与 whitespace 静态检查bin/test# 全部 webapp/test/*.mjsbin/check-public--refHEAD# 发布快照检查，不输出命中值bin/check-public--refHEAD--history# 检查该引用可达历史，可能因旧私人数据失败node--test--test-name-pattern"路径穿越"webapp/test/smoke.mjsnode--checkwebapp/server.mjsnode--checkwebapp/public/app.jsAI_SERVE_PORT=4399nodewebapp/server.mjs bin/build-app --no-install# 只构建原生 Appbin/build-dmg# 构建 DMG 安装包到 dist/（见 docs/RELEASE.md）

测试会启动真实服务（默认端口 4399 / 4398），需要允许本机监听。受限沙箱内可能因EPERM失败，应在普通终端运行。

提交前至少运行：

bin/testnode--checkwebapp/server.mjsnode--checkwebapp/public/app.js

改动流程和代码约定见 AGENTS.md / CLAUDE.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 提 Issue 或 Pull Request。提交前请阅读 CONTRIBUTING.md，并确认没有提交密钥、个人路径、真实数据库地址或未授权的第三方内容。

适合上手的方向：文档与示例补全、UI 细节与可访问性、测试覆盖、Linux 兼容性验证。

许可

本项目使用 MIT License，详见 LICENSE。skills/下的部分技能来自第三方，不自动适用根许可证；分发前请逐个确认，详见 THIRD_PARTY_NOTICES.md。