AirbossmacOS 本地 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 编辑器会根据正文中的##/###标题自动生成锚点上面的链接与标题一一对应若后续增删章节记得同步更新这份目录。功能总览模块一句话说明启动器搜索项目、选工具与线路一条命令在 Terminal 里启动任意 agent任务中心TASK.md/PLAN.md/HANDOFF.md三段式任务支持后台 headless 执行项目扫描项目根目录查看 Git 分支、脏文件、线路记忆和最近运行运行账本每次启动写入runs.jsonl状态、耗时、退出码、日志和git diff摘要工具Codex / Claude Code / OpenCode / DeepSeek Harness 的安装、版本、更新和卸载能力以mcp/servers.json和skills/为单一事实源同步到各工具的全局配置模型与线路管理供应商、端点、密钥、健康探测和每个工具的默认线路与兜底设置与外观主题 / 字体 / 字号 / 背景、中英双语、项目根目录、漂移检测与安全边界原生 AppSwift WKWebView 原生壳也可直接浏览器访问或安装为 PWA命令行ai一条命令完成启动、线路、任务、自检和同步功能详解启动器首页就是一个启动器输入项目名或直接粘贴绝对路径选 agent 和线路回车启动。它解决的是「每天要重复选项目、选工具、选线路」的问题。搜索即启动⌘K聚焦搜索框Enter直接启动也可以粘贴任意绝对路径不在项目根目录里也能启动。项目 × 工具线路记忆每个项目对 codex / claude 的线路选择写在state/project-routes.json下次打开自动沿用。最近组合最近 4 个「项目 × 工具 × 线路」组合显示成 chip数字键1–4可直接复跑。线路兜底默认线路健康状态为err时自动切到同一工具下可用的其它来源并给出提示显式指定--provider时不兜底可用AI_NO_FALLBACK1全局关闭。两种启动方式首页 / 项目页「启动 →」打开 Terminal 前台运行保留 CLI 的交互 TUI任务页「启动 →」走后台 headless 执行。继续会话勾选「继续上次会话」等价于ai agent --continuecodex 使用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.jsonCLI 类npm / brew 安装和 App 类如 DeepSeek Harness分开处理。版本与更新读取--version通过 npm registry 检查最新版本支持单个更新、全部更新和「检查更新」预检。安装 / 卸载未安装可一键安装卸载需要二次确认可勾选同时删除配置目录会话会一并丢失。命令白名单安装 / 更新 / 卸载只允许npm、brew、rm执行前支持dry_run预演命令。线路入口每个 agent 卡片显示当前生效线路可直接用该 agent 启动。能力 MCP 与 SkillsMCP 和 Skills 都只维护一份本机清单再由控制台同步到各工具的全局配置避免三个工具各写一份、互相覆盖。MCPmcp/servers.json是唯一事实源。支持stdio/http/sse三种传输方式密钥用${VAR}占位明文只放在secrets.envbin/mcp-run启动时展开。每个服务器用apps数组声明启用范围界面就是启用矩阵Codex / Claude / OpenCode。同步只替换 Airboss 托管的条目Codex 写~/.codex/config.toml的托管块Claude / OpenCode 读写 JSON手工条目保留同步前自动备份。状态卡会显示每个工具与servers.json是否一致OK/ 待同步并统计缺失密钥、未同步工具。删除服务器会留下托管标记墓碑下次同步时清理旧条目。Skillsskills/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_tokens1的 Messages 请求验证鉴权消耗约 1 token。结果写入state/provider-health.json启动时自动探测一次10 分钟内不重复。密钥只进secrets.env接口只返回是否已配置和掩码写入后文件权限固定600key 不会出现在页面、日志或接口响应里。模型管理可从端点拉取模型、手动添加模型名、删除自定义模型删除后会自动修正routes.json和 codex 托管配置避免线路指向不存在的模型。「测试 / 配置 / 密钥」测试连通性、把某个来源设为该工具的生效线路、修改密钥。协议约束Codex 线路必须是responsesClaude 线路必须是anthropicOpenCode 使用自己的模型配置。「配置 → 应用生效」会写入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 原生壳。原生 Appapp/main.swift是 Swift WKWebView 壳负责窗口、菜单、页面导航回传和断线重试菜单里⌘1–⌘8直接切页面。构建bin/build-app用swiftc编译生成.icnsad-hoc 签名后安装到/Applications不可写时装到~/Applications。PWASafari「文件 → 添加到程序坞」或 Chrome「安装页面为应用」窗口和图标与 App 类似。热更新前端是静态文件改完刷新即可只有改main.swift才需要重新bin/build-app。命令行 aibin/ai是 bash 分发器负责 agent 别名、线路解析、密钥注入和任务命令。控制台的大部分能力都能在终端里用。ai# 列出所有 agent 与安装状态ai cx / ai cl / ai oc / ai dsh# 启动对应 agentai cx--providerid--modelmodel# 临时指定线路不落盘ai cx--profilelocal# 使用 profiles/local 启动配方ai cx--continue# 继续该项目最近一次会话aiexeccodex任务描述# headless 非交互执行线路解析顺序显式--provider/--model→ 项目记忆state/project-routes.json→ 默认线路providers/routes.json。默认线路不可用时自动兜底AI_NO_FALLBACK1关闭。密钥按行解析secrets.env后只注入子进程不进入全局 shellCodex 通过-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下半部分是配置真源与运行数据。三条主要链路启动链路控制台 →POST /api/launch→ 生成tmp/run-id.command→open -a Terminal执行bin/ai→ 解析 agent 与线路 → 注入密钥 → 启动 agent。后台任务链路控制台 →POST /api/task→ 服务端spawn(bin/ai exec ...)→ stdout / stderr 写入logs/tasks/run-id.log→ 结束后写回runs.jsonl和任务状态。同步链路mcp/servers.jsonskills/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 24jq、git、curl、lsof可选Xcode Command Line Tools构建原生 App 和.icns时需要可选至少安装一个受支持的 agent使用 Homebrew 时可以先安装基础依赖brewinstallnodejq安装 agent 的常见方式npmi-gopenai/codexnpmi-ganthropic-ai/claude-codenpmi-gopencode/cliDeepSeek 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建议写进 ~/.zshrcexportPATH$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.0macOS 13需要先安装 Node.js 20 和 jq。安装包Airboss-1.1.0.dmg校验值Airboss-1.1.0.dmg.sha256下载后建议先核对shasum-a256Airboss-1.1.0.dmg# 输出应与 Release 附件中的 .sha256 内容一致安装步骤先装依赖brew install node jq打开 DMG双击「安装 Airboss.command」安装器会检查 Node.js把程序安装到~/airboss、初始化secrets.env、把ai加入 PATH并可选安装登录自启按提示编辑~/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发版时记得同步更新本节和顶部的版本号。原生 Appbin/build-app--open# 构建并安装到 /Applications/Airboss.appai app# 已安装则打开 App否则用浏览器打开ai app在控制台没启动时会自动拉起服务需要开机自启可以用bin/autostartinstall# 安装 LaunchAgent登录后自动启动控制台bin/autostart status配置所有配置都是仓库目录里的文件可以直接编辑也可以走控制台文件作用secrets.env所有密钥600 权限、gitignore、接口不返回明文providers/providers.json供应商、端点、协议、密钥变量名、模型列表providers/routes.json每个 agent 的默认 provider / modelagents/registry.jsonagent 命令、别名、headless 参数、会话目录agents/tools.json「工具」页的安装 / 更新 / 卸载定义agents/project-roots.json项目页扫描根目录本机数据默认忽略mcp/servers.jsonMCP 服务器清单和启用范围本机数据默认忽略skills/registry.jsonSkills 期望启用状态本机数据默认忽略profiles/name/启动配方env.envagent.argsAGENTS.mdagent 协作规则也是ai sync的规则源核心概念概念位置说明Agentagents/registry.jsonCodex / Claude Code / OpenCode / DeepSeek Harness 的启动命令和别名Providerproviders/providers.json供应商、端点、协议、密钥变量和模型列表Routeproviders/routes.json每个 agent 的默认 provider 和 modelProfileprofiles/name/启动参数和环境变量配方如default/local/deepTasktasks/id/目标、计划、交接和任务元数据Runruns.jsonl运行账本记录启动、结束、耗时和改动摘要MCPmcp/servers.jsonMCP 服务器清单和启用范围Skillskills/name/SKILL.md技能定义skills/registry.json记录启用状态配置密钥所有密钥只放在仓库根目录的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验证 → 在「模型」页测试并应用生效。环境变量变量作用默认AI_HOME工作站根目录仓库根目录AI_SERVE_PORT控制台端口4317AI_HOME_NOTIFY设为0关闭 macOS 完成通知开启AI_ALLOW_DANGEROUS_PERMISSIONS设为1时 Claude headless 使用--dangerously-skip-permissions关闭AI_NO_FALLBACK设为1关闭线路兜底开启兜底AI_TASK_TIMEOUT_MS后台任务超时180000030 分钟AI_TASK_KILL_GRACE_MSSIGTERM后宽限期5000AI_PROFILE默认启动 profiledefaultAI_APP_DIR原生 App 安装目录/Applications完整字段和改法见 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 useagentprovider[model]# 修改默认线路ai cx--providerid--modelm# 单次临时线路任务ai task new标题--repopath[--agenta][--accept标准]ai task list ai task showid[task|plan|handoff]ai task startid[--projectpath][--agenta][--prompttext]ai task statusid[状态]ai taskdoneidai task handoffid同步与维护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为准。快捷键快捷键作用⌘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和工具配置权限为600state/、logs/建议700ai 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_PORT4399nodewebapp/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_PORT4399 ai serve换端口。控制台已在运行时ai serve会直接复用现有实例ai restart用于加载最新代码。ai doctor报缺少密钥或线路不兼容先看ai providers的密钥状态再确认providers/routes.json里的线路与协议匹配Codex 必须是responsesClaude 必须是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 ReleasesDMG 安装包下载、版本历史与发行说明docs/ARCHITECTURE.md分层架构、请求管线、运行生命周期、关键不变量docs/CONFIGURATION.md各配置文件的字段、示例和常用改法docs/OPEN_SOURCE_CHECKLIST.md开源发布前的隐私、许可和历史清理检查docs/RELEASE.md版本号、DMG 构建、Gitee Releases 发布与校验流程AGENTS.mdagent 协作规则也是ai sync的规则源CLAUDE.mdClaude Code 的仓库入口说明CONTRIBUTING.mdGitee 贡献流程和提交规范SECURITY.md安全模型和漏洞报告方式skills/README.md技能库约定、来源和许可说明THIRD_PARTY_NOTICES.md第三方技能、素材的来源和许可说明docs/screenshots/README 使用的界面截图演示数据贡献欢迎在 Gitee 提 Issue 或 Pull Request。提交前请阅读 CONTRIBUTING.md并确认没有提交密钥、个人路径、真实数据库地址或未授权的第三方内容。适合上手的方向文档与示例补全、UI 细节与可访问性、测试覆盖、Linux 兼容性验证。许可本项目使用 MIT License详见 LICENSE。skills/下的部分技能来自第三方不自动适用根许可证分发前请逐个确认详见 THIRD_PARTY_NOTICES.md。 
长河君 · 2026/11/2 6:30:07 · 阅读 1.2k Airboss：个人开发者的AI工作站实现思路（macOs-app+git开源）
AirbossmacOS 本地 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 编辑器会根据正文中的##/###标题自动生成锚点上面的链接与标题一一对应若后续增删章节记得同步更新这份目录。功能总览模块一句话说明启动器搜索项目、选工具与线路一条命令在 Terminal 里启动任意 agent任务中心TASK.md/PLAN.md/HANDOFF.md三段式任务支持后台 headless 执行项目扫描项目根目录查看 Git 分支、脏文件、线路记忆和最近运行运行账本每次启动写入runs.jsonl状态、耗时、退出码、日志和git diff摘要工具Codex / Claude Code / OpenCode / DeepSeek Harness 的安装、版本、更新和卸载能力以mcp/servers.json和skills/为单一事实源同步到各工具的全局配置模型与线路管理供应商、端点、密钥、健康探测和每个工具的默认线路与兜底设置与外观主题 / 字体 / 字号 / 背景、中英双语、项目根目录、漂移检测与安全边界原生 AppSwift WKWebView 原生壳也可直接浏览器访问或安装为 PWA命令行ai一条命令完成启动、线路、任务、自检和同步功能详解启动器首页就是一个启动器输入项目名或直接粘贴绝对路径选 agent 和线路回车启动。它解决的是「每天要重复选项目、选工具、选线路」的问题。搜索即启动⌘K聚焦搜索框Enter直接启动也可以粘贴任意绝对路径不在项目根目录里也能启动。项目 × 工具线路记忆每个项目对 codex / claude 的线路选择写在state/project-routes.json下次打开自动沿用。最近组合最近 4 个「项目 × 工具 × 线路」组合显示成 chip数字键1–4可直接复跑。线路兜底默认线路健康状态为err时自动切到同一工具下可用的其它来源并给出提示显式指定--provider时不兜底可用AI_NO_FALLBACK1全局关闭。两种启动方式首页 / 项目页「启动 →」打开 Terminal 前台运行保留 CLI 的交互 TUI任务页「启动 →」走后台 headless 执行。继续会话勾选「继续上次会话」等价于ai agent --continuecodex 使用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.jsonCLI 类npm / brew 安装和 App 类如 DeepSeek Harness分开处理。版本与更新读取--version通过 npm registry 检查最新版本支持单个更新、全部更新和「检查更新」预检。安装 / 卸载未安装可一键安装卸载需要二次确认可勾选同时删除配置目录会话会一并丢失。命令白名单安装 / 更新 / 卸载只允许npm、brew、rm执行前支持dry_run预演命令。线路入口每个 agent 卡片显示当前生效线路可直接用该 agent 启动。能力 MCP 与 SkillsMCP 和 Skills 都只维护一份本机清单再由控制台同步到各工具的全局配置避免三个工具各写一份、互相覆盖。MCPmcp/servers.json是唯一事实源。支持stdio/http/sse三种传输方式密钥用${VAR}占位明文只放在secrets.envbin/mcp-run启动时展开。每个服务器用apps数组声明启用范围界面就是启用矩阵Codex / Claude / OpenCode。同步只替换 Airboss 托管的条目Codex 写~/.codex/config.toml的托管块Claude / OpenCode 读写 JSON手工条目保留同步前自动备份。状态卡会显示每个工具与servers.json是否一致OK/ 待同步并统计缺失密钥、未同步工具。删除服务器会留下托管标记墓碑下次同步时清理旧条目。Skillsskills/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_tokens1的 Messages 请求验证鉴权消耗约 1 token。结果写入state/provider-health.json启动时自动探测一次10 分钟内不重复。密钥只进secrets.env接口只返回是否已配置和掩码写入后文件权限固定600key 不会出现在页面、日志或接口响应里。模型管理可从端点拉取模型、手动添加模型名、删除自定义模型删除后会自动修正routes.json和 codex 托管配置避免线路指向不存在的模型。「测试 / 配置 / 密钥」测试连通性、把某个来源设为该工具的生效线路、修改密钥。协议约束Codex 线路必须是responsesClaude 线路必须是anthropicOpenCode 使用自己的模型配置。「配置 → 应用生效」会写入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 原生壳。原生 Appapp/main.swift是 Swift WKWebView 壳负责窗口、菜单、页面导航回传和断线重试菜单里⌘1–⌘8直接切页面。构建bin/build-app用swiftc编译生成.icnsad-hoc 签名后安装到/Applications不可写时装到~/Applications。PWASafari「文件 → 添加到程序坞」或 Chrome「安装页面为应用」窗口和图标与 App 类似。热更新前端是静态文件改完刷新即可只有改main.swift才需要重新bin/build-app。命令行 aibin/ai是 bash 分发器负责 agent 别名、线路解析、密钥注入和任务命令。控制台的大部分能力都能在终端里用。ai# 列出所有 agent 与安装状态ai cx / ai cl / ai oc / ai dsh# 启动对应 agentai cx--providerid--modelmodel# 临时指定线路不落盘ai cx--profilelocal# 使用 profiles/local 启动配方ai cx--continue# 继续该项目最近一次会话aiexeccodex任务描述# headless 非交互执行线路解析顺序显式--provider/--model→ 项目记忆state/project-routes.json→ 默认线路providers/routes.json。默认线路不可用时自动兜底AI_NO_FALLBACK1关闭。密钥按行解析secrets.env后只注入子进程不进入全局 shellCodex 通过-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下半部分是配置真源与运行数据。三条主要链路启动链路控制台 →POST /api/launch→ 生成tmp/run-id.command→open -a Terminal执行bin/ai→ 解析 agent 与线路 → 注入密钥 → 启动 agent。后台任务链路控制台 →POST /api/task→ 服务端spawn(bin/ai exec ...)→ stdout / stderr 写入logs/tasks/run-id.log→ 结束后写回runs.jsonl和任务状态。同步链路mcp/servers.jsonskills/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 24jq、git、curl、lsof可选Xcode Command Line Tools构建原生 App 和.icns时需要可选至少安装一个受支持的 agent使用 Homebrew 时可以先安装基础依赖brewinstallnodejq安装 agent 的常见方式npmi-gopenai/codexnpmi-ganthropic-ai/claude-codenpmi-gopencode/cliDeepSeek 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建议写进 ~/.zshrcexportPATH$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.0macOS 13需要先安装 Node.js 20 和 jq。安装包Airboss-1.1.0.dmg校验值Airboss-1.1.0.dmg.sha256下载后建议先核对shasum-a256Airboss-1.1.0.dmg# 输出应与 Release 附件中的 .sha256 内容一致安装步骤先装依赖brew install node jq打开 DMG双击「安装 Airboss.command」安装器会检查 Node.js把程序安装到~/airboss、初始化secrets.env、把ai加入 PATH并可选安装登录自启按提示编辑~/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发版时记得同步更新本节和顶部的版本号。原生 Appbin/build-app--open# 构建并安装到 /Applications/Airboss.appai app# 已安装则打开 App否则用浏览器打开ai app在控制台没启动时会自动拉起服务需要开机自启可以用bin/autostartinstall# 安装 LaunchAgent登录后自动启动控制台bin/autostart status配置所有配置都是仓库目录里的文件可以直接编辑也可以走控制台文件作用secrets.env所有密钥600 权限、gitignore、接口不返回明文providers/providers.json供应商、端点、协议、密钥变量名、模型列表providers/routes.json每个 agent 的默认 provider / modelagents/registry.jsonagent 命令、别名、headless 参数、会话目录agents/tools.json「工具」页的安装 / 更新 / 卸载定义agents/project-roots.json项目页扫描根目录本机数据默认忽略mcp/servers.jsonMCP 服务器清单和启用范围本机数据默认忽略skills/registry.jsonSkills 期望启用状态本机数据默认忽略profiles/name/启动配方env.envagent.argsAGENTS.mdagent 协作规则也是ai sync的规则源核心概念概念位置说明Agentagents/registry.jsonCodex / Claude Code / OpenCode / DeepSeek Harness 的启动命令和别名Providerproviders/providers.json供应商、端点、协议、密钥变量和模型列表Routeproviders/routes.json每个 agent 的默认 provider 和 modelProfileprofiles/name/启动参数和环境变量配方如default/local/deepTasktasks/id/目标、计划、交接和任务元数据Runruns.jsonl运行账本记录启动、结束、耗时和改动摘要MCPmcp/servers.jsonMCP 服务器清单和启用范围Skillskills/name/SKILL.md技能定义skills/registry.json记录启用状态配置密钥所有密钥只放在仓库根目录的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验证 → 在「模型」页测试并应用生效。环境变量变量作用默认AI_HOME工作站根目录仓库根目录AI_SERVE_PORT控制台端口4317AI_HOME_NOTIFY设为0关闭 macOS 完成通知开启AI_ALLOW_DANGEROUS_PERMISSIONS设为1时 Claude headless 使用--dangerously-skip-permissions关闭AI_NO_FALLBACK设为1关闭线路兜底开启兜底AI_TASK_TIMEOUT_MS后台任务超时180000030 分钟AI_TASK_KILL_GRACE_MSSIGTERM后宽限期5000AI_PROFILE默认启动 profiledefaultAI_APP_DIR原生 App 安装目录/Applications完整字段和改法见 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 useagentprovider[model]# 修改默认线路ai cx--providerid--modelm# 单次临时线路任务ai task new标题--repopath[--agenta][--accept标准]ai task list ai task showid[task|plan|handoff]ai task startid[--projectpath][--agenta][--prompttext]ai task statusid[状态]ai taskdoneidai task handoffid同步与维护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为准。快捷键快捷键作用⌘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和工具配置权限为600state/、logs/建议700ai 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_PORT4399nodewebapp/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_PORT4399 ai serve换端口。控制台已在运行时ai serve会直接复用现有实例ai restart用于加载最新代码。ai doctor报缺少密钥或线路不兼容先看ai providers的密钥状态再确认providers/routes.json里的线路与协议匹配Codex 必须是responsesClaude 必须是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 ReleasesDMG 安装包下载、版本历史与发行说明docs/ARCHITECTURE.md分层架构、请求管线、运行生命周期、关键不变量docs/CONFIGURATION.md各配置文件的字段、示例和常用改法docs/OPEN_SOURCE_CHECKLIST.md开源发布前的隐私、许可和历史清理检查docs/RELEASE.md版本号、DMG 构建、Gitee Releases 发布与校验流程AGENTS.mdagent 协作规则也是ai sync的规则源CLAUDE.mdClaude Code 的仓库入口说明CONTRIBUTING.mdGitee 贡献流程和提交规范SECURITY.md安全模型和漏洞报告方式skills/README.md技能库约定、来源和许可说明THIRD_PARTY_NOTICES.md第三方技能、素材的来源和许可说明docs/screenshots/README 使用的界面截图演示数据贡献欢迎在 Gitee 提 Issue 或 Pull Request。提交前请阅读 CONTRIBUTING.md并确认没有提交密钥、个人路径、真实数据库地址或未授权的第三方内容。适合上手的方向文档与示例补全、UI 细节与可访问性、测试覆盖、Linux 兼容性验证。许可本项目使用 MIT License详见 LICENSE。skills/下的部分技能来自第三方不自动适用根许可证分发前请逐个确认详见 THIRD_PARTY_NOTICES.md。