1. 项目概述：RexCLI，一个为AI编码代理注入记忆与协作能力的本地优先工作流引擎
如果你和我一样，日常重度依赖codex-cli、Claude Code、Gemini CLI这类AI编码工具来辅助开发、调试甚至重构代码，那你一定遇到过这样的困境：每次开启一个新的对话，AI都像一张白纸，完全不记得我们之前在这个项目里讨论过什么、改过哪些文件、遇到过哪些坑。你不得不一遍又一遍地粘贴上下文，解释项目结构，复述之前失败的原因。更别提当你需要在多个AI代理（比如让Codex写前端，Claude写后端）之间协作时，它们之间完全是信息孤岛，无法共享任务状态和知识。
RexCLI 就是为了解决这个核心痛点而生的。它不是一个全新的AI代理，而是一个本地优先的“记忆系统”与“编排层”。你可以把它想象成给你现有的AI编码工具装上一个“外置大脑”和一个“指挥中心”。这个大脑（ContextDB）会忠实地记录你在每个项目、每个会话中的所有交互、决策和代码变更，形成可追溯、可查询的记忆。而这个指挥中心（Orchestrate & Team Runtimes）则能让你像管理一个团队一样，规划任务、分派给不同的AI代理（子代理），并协调它们的工作。
简单来说，RexCLI 让你从“每次和AI聊天都像初次见面”的原始状态，进化到拥有一个具备持久化记忆、支持多智能体协作的自动化工作流。这对于处理复杂、长期的项目任务（比如重构一个大型模块、从零搭建一个微服务、或者系统性地修复技术债）来说，效率的提升是指数级的。
2. 核心架构与设计哲学：为什么是“本地优先”与“非侵入式集成”
在深入实操之前，理解 RexCLI 的设计哲学至关重要，这决定了它的使用边界和优势。它的核心设计可以概括为两点：本地优先和非侵入式集成。
2.1 本地优先：数据主权与隐私保障
所有由 RexCLI 产生的数据——会话记录、事件日志、检查点、上下文包——都存储在你的本地磁盘上，具体是在每个Git项目的memory/context-db/目录下。这意味着：
- 完全的数据控制：你的项目历史、与AI的对话、甚至潜在的敏感代码片段，都不会离开你的机器。这对于企业开发或处理私有代码库至关重要。
- 离线可用：一旦安装配置完成，核心的记忆和编排功能完全离线工作，不依赖任何外部服务（除了你原本就需要调用的AI API）。
- 可移植与可审计：整个
memory/目录可以像普通文件一样备份、迁移或纳入版本控制（虽然通常被.gitignore忽略）。你可以随时查看原始的JSONL日志，了解AI决策的完整链条。
这个理念也体现在其“隐私守卫”（Privacy Guard）功能上。在读取可能包含敏感信息的配置文件（如~/.ssh/config,~/.npmrc）时，RexCLI 会默认启用严格的脱敏策略，防止意外泄露。你可以通过aios privacy status查看状态，或使用aios privacy read --file <path>安全地读取文件。
2.2 非侵入式集成：透明包装与原有工作流无损
RexCLI 没有尝试重新发明轮子去替代codex、claude这些成熟的CLI工具。相反，它通过巧妙的Shell 包装（Shell Wrapping）来实现集成。
其原理是，在你的 Shell 配置文件（如~/.zshrc）中，它重新定义了codex、claude、gemini这些命令。当你调用这些命令时，实际执行的是一个包装函数。这个函数会先拦截调用，执行以下操作：
- 初始化/恢复会话：检查当前Git仓库，初始化或连接到对应的ContextDB会话。
- 打包上下文：根据会话历史，智能地打包一份浓缩的上下文（
context:pack），作为本次对话的“前置记忆”。 - 注入并执行：将打包好的上下文作为初始提示，连同你的原始指令，一并传递给真正的原生CLI工具。
对于你来说，命令行用法没有任何改变。你依然输入codex “帮我修复这个bug”，但AI收到的提示里已经包含了它在这个项目里的“前世今生”。这是一种无缝的、近乎隐形的增强。
2.3 架构全景图与数据流
为了更清晰地理解，我们可以看下从你输入命令到AI响应的完整数据流：
用户终端 | | 输入 `codex “实现登录功能”` v Shell 包装层 (contextdb-shell.zsh) | - 识别当前Git工作区 | - 决定是包装执行还是直通（对于`codex mcp`等管理命令） v 桥接脚本 (contextdb-shell-bridge.mjs) | - 核心决策点：是否启用ContextDB包装？ | - 是：调用 `ctx-agent.mjs` v 统一运行器 (ctx-agent.mjs) | - 调用 ContextDB CLI: `init` (如果需要) | - 调用 ContextDB CLI: `session:latest` (恢复最近会话) 或 `session:new` | - 调用 ContextDB CLI: `event:add` 记录本次用户指令 | - 调用 ContextDB CLI: `context:pack` 生成上下文摘要 | - 启动原生 `codex` / `claude` / `gemini` 进程，并注入打包好的上下文 v 原生AI CLI + 注入的上下文 | | - AI基于“记忆上下文”+“新指令”生成响应 v 响应返回用户，同时 `ctx-agent.mjs` 可能记录AI响应为事件关键目录解析：
mcp-server/： 这是核心服务端，实现了ContextDB的CLI和Playwright浏览器自动化MCP服务。scripts/： 包含所有包装脚本、桥接逻辑和工具脚本。memory/context-db/：每个项目的记忆库。里面按会话（Session）组织，包含元数据、L0摘要、L1检查点、L2详细事件。skill-sources/与agent-sources/： 分别存放可安装的“技能”（Skills）和“编排器代理”（Orchestrator Agents）的源代码。它们是RexCLI扩展能力的模块。
3. 从零开始：详细安装、配置与初体验
理论讲完，我们动手安装。RexCLI 提供了极其友好的TUI（终端用户界面）引导安装，这是最推荐的方式。
3.1 一步到位的安装与初始化
打开你的终端，执行以下命令。这将下载安装脚本并执行：
curl -fsSL https://github.com/rexleimo/rex-cli/releases/latest/download/aios-install.sh | bash安装完成后，务必重新加载你的Shell配置，以使包装命令生效：
source ~/.zshrc # 如果你使用Zsh # 或 source ~/.bashrc # 如果你使用Bash现在，输入aios命令，你将进入全屏的TUI主菜单。对于首次使用，请遵循以下路径：
- 启动与设置：在TUI主菜单中，使用方向键选择
Setup，然后按回车。 - 选择组件：你会看到一个组件选择列表。对于想体验全部功能的新用户，直接选择
all。如果你只想先试试核心的记忆和技能功能，可以选择shell,skills,superpowers。如果仅需要浏览器自动化能力，则选browser。 - 运行健康检查：安装完成后，不要急着退出TUI。在主菜单中找到并运行
Doctor。这个命令会全面检查你的环境、依赖和配置是否正确，并给出修复建议。这是避免后续各种诡异问题的关键一步。 - 技能安装（可选但推荐）：在安装过程中，如果选择了包含
skills的组件，TUI会弹出技能选择器。这里我强烈建议勾选debug技能。它包含一个本地NDJSON日志收集器，当你的AI代理行为异常时，它能提供第一手的、结构化的调试信息，远比看杂乱的终端输出高效。
实操心得：安装后第一次运行
codex或claude时，可能会感觉启动稍慢一点。这是因为它在后台初始化当前项目的ContextDB数据库。这是正常现象，后续调用会快很多。如果遇到better-sqlite3的Node ABI不匹配错误，别慌。脚本通常会尝试自动重建。如果失败，手动进入$REXCLI_ROOT/mcp-server目录执行npm rebuild better-sqlite3即可。
3.2 核心概念上手：你的第一个有记忆的会话
安装配置妥当后，让我们进入一个真实的Git项目目录，开始第一次体验。
cd ~/your-awesome-project codex你会发现，与你平时直接运行codex不同，启动后AI的第一句话可能就包含了对你项目的引用，比如“正在继续我们之前关于XXX的讨论...”。这是因为RexCLI自动执行了“首次任务引导”（Auto Bootstrap）。
首次任务引导机制： 当你在一个全新的工作区（或tasks/.current-task为空且tasks/pending/无任务）首次运行AI命令时，RexCLI会自动创建一个轻量级的引导任务。它会生成：
tasks/pending/task_<时间戳>_bootstrap_guidelines/task.json： 任务定义文件。tasks/pending/task_<时间戳>_bootstrap_guidelines/prd.md： 产品需求文档草稿。tasks/.current-task： 指向当前活动任务的符号链接。
这个机制的目的是帮你快速建立一个任务跟踪的起点，而不是在真空中开始。如果你不喜欢这个行为，可以通过设置环境变量export AIOS_BOOTSTRAP_AUTO=0全局禁用，或在单次命令后加--no-bootstrap参数。
与AI进行几次对话后，你可以探索你的记忆库：
# 进入ContextDB目录查看 ls -la memory/context-db/ # 查看最新的上下文导出（这是AI每次对话前收到的“记忆”） cat memory/context-db/exports/latest-codex-context.md这个latest-*-context.md文件就是context:pack命令的产出，是经过提炼的、适合喂给AI的会话摘要。理解它的内容，你就理解了RexCLI是如何为AI提供上下文的。
3.3 范围控制与技能管理：避免污染你的所有项目
你可能不希望RexCLI在你所有的Git项目里都自动启用。RexCLI 提供了精细的范围控制。
包装范围控制： 通过环境变量CTXDB_WRAP_MODE来控制包装器在哪些目录生效。
repo-only(默认)：仅在RexCLI自身的仓库目录内启用。这是最安全、最推荐的方式。opt-in：仅在包含.contextdb-enable标记文件的Git仓库中启用。这给了你按项目启用的灵活性。off：完全禁用包装（回退到原生CLI）。
你可以在~/.zshrc中设置。例如，设置为opt-in模式：
export CTXDB_WRAP_MODE=opt-in然后，在你想要启用RexCLI的特定项目根目录下，创建一个标记文件：
touch .contextdb-enable注意事项：在
opt-in模式下，包装器启动时默认会自动创建这个标记文件。如果你想要严格的手动控制，可以设置export CTXDB_AUTO_CREATE_MARKER=0来关闭自动创建。
技能管理： 技能（Skills）是扩展AI代理能力的插件，比如debug（调试）、find-skills（查找技能）、verification-loop（验证循环）等。RexCLI 通过一个中央技能目录 (config/skills-catalog.json) 来管理。
技能的安装分为两种作用域：
- 全局作用域 (
--scope global)： 技能安装到你的用户目录下（如~/.codex/skills/），对所有项目生效。 - 项目作用域 (
--scope project)： 技能安装到当前项目的特定目录下（如./.codex/skills/），仅对该项目生效。
安装示例：
# 为Codex全局安装 debug 和 verification-loop 技能 node scripts/aios.mjs setup --components skills --client codex --scope global --skills debug,verification-loop # 为当前项目安装特定的工作流技能（如小红书运营方法） node scripts/aios.mjs setup --components skills --client codex --scope project --skills xhs-ops-methods重要提醒：避免安装与RexCLI内置技能同名的第三方技能，否则
doctor会报告冲突。对于业务特定的技能，建议使用项目作用域，以免污染全局环境。
4. 进阶能力解析：多代理协作、质量门禁与事故恢复
当基础的单代理记忆工作流满足不了你时，RexCLI 更强大的编排和协作能力就派上用场了。
4.1 团队运行时：让多个AI代理协同工作
aios team命令是进行多代理协作的核心。你可以像指挥一个团队一样，将任务分解，并发地分配给多个AI代理实例。
基本团队操作：
# 启动一个由3个Codex子代理组成的团队来处理任务“实现用户仪表盘” aios team 3:codex "实现用户仪表盘" # 启动一个由2个Claude子代理组成的团队，并进行干跑（预览计划而不执行） aios team 2:claude "重构认证模块" --dry-run # 恢复一个已有的会话，并重试其中被阻塞的任务 aios team --resume <session-id> --retry-blocked --provider codex --workers 2在这个模式下，RexCLI 的编排器（Orchestrator）会充当“项目经理”，它将一个宏观任务分解成多个子任务（或阶段），并分配给不同的“工程师”（子代理）去执行。这些子代理共享同一个ContextDB会话，因此它们能看到彼此的工作进展和产出。
手动编排与执行： 如果你需要更精细的控制，可以使用orchestrate命令族。
# 预览一个“功能开发”蓝图会生成怎样的任务计划 aios orchestrate feature --task "开发用户登录API" # 为一个会话生成本地分发计划（不调用AI，不执行） aios orchestrate --session <session-id> --dispatch local --execute none --format json # 在本地模拟执行（仍不调用AI，但执行所有支持的本地动作，如运行脚本） aios orchestrate --session <session-id> --preflight auto --format json # 一键开启真实的AI执行（会产生API调用费用） export AIOS_EXECUTE_LIVE=1 export AIOS_SUBAGENT_CLIENT=codex-cli export AIOS_SUBAGENT_CONCURRENCY=2 # 控制并发数 aios orchestrate --session <session-id> --dispatch local --execute live --format json4.2 质量门禁：守护仓库健康与上下文一致性
在自动化程度很高的协作中，确保代码质量和上下文记忆的可靠性至关重要。aios quality-gate就是你的自动化守门员。
# 运行完整的质量门禁检查 aios quality-gate full # 运行更严格的、适合提交PR前的检查 aios quality-gate pre-pr --profile strict # 禁用特定的检查项（例如，跳过上下文数据库的回归测试） AIOS_DISABLED_GATES=quality:contextdb aios quality-gate pre-pr质量门禁通常会检查：
- 代码质量：基本的语法、格式检查。
- 上下文数据库回归：确保ContextDB的索引和查询功能正常，记忆没有被破坏。
- 技能同步状态：检查项目技能与源目录是否同步。
- 原生增强同步：检查各客户端的本地配置文件是否与源头一致。
定期运行质量门禁，尤其是在进行重要变更或准备发布前，可以提前发现许多隐蔽的问题。
4.3 事故恢复：当AI“闯祸”后的回滚利器
即使有再好的规划和约束，AI代理在自动执行代码修改时也可能产生意外的、破坏性的变更。RexCLI 提供了基于快照的事故恢复机制，这是我认为最值得称道的“安全网”功能。
启用预突变快照： 在开始任何有风险的自动化任务（尤其是--execute live）之前，务必启用此功能。
export AIOS_SUBAGENT_PRE_MUTATION_SNAPSHOT=1这个环境变量会告诉RexCLI，在子代理执行任何可能修改文件系统的操作之前，先对相关文件路径创建快照。
执行回滚： 当发现AI的修改不符合预期时，你可以快速回滚。
# 首先，预览回滚操作会影响到哪些文件（强烈推荐先预览！） aios snapshot-rollback --session <session-id> --job phase.implement --dry-run # 确认无误后，执行回滚 aios snapshot-rollback --session <session-id> --job phase.implement # 你也可以基于一个明确的快照清单文件进行回滚 aios snapshot-rollback --manifest memory/context-db/sessions/<session-id>/artifacts/pre-mutation-<stamp>-phase_implement/manifest.json回滚后，建议立即运行git status查看文件状态变化，并运行你的测试套件或再次执行aios orchestrate --session <session-id> --preflight auto进行验证。
踩坑经验：这个快照功能不是万能的。它只捕获在RexCLI管理下的、通过子代理执行的文件变更。如果你手动修改了文件，或者AI的操作绕过了快照机制（例如直接执行了Shell命令删除文件），则无法恢复。因此，始终将重要的代码仓库置于Git管理之下，结合
git commit提供另一层保障，是最佳实践。
5. 运维、监控与故障排查实战指南
将RexCLI集成到日常开发流后，掌握一些运维和监控技巧能让你事半功倍。
5.1 监控会话状态：HUD与团队状态
RexCLI 提供了直观的工具来监控正在进行的自动化任务。
抬头显示器：aios hud命令就像一个实时仪表盘。
# 查看指定AI提供商（如codex）的当前会话概览 aios hud --provider codex # 以JSON格式输出特定会话的详细信息，便于脚本处理 aios hud --session <session-id> --json # 开启监视模式，实时刷新显示（类似`top`命令） aios hud --watch --preset full团队操作状态：
# 查看当前团队运行状态，并实时刷新 aios team status --provider codex --watch # 查看团队任务历史记录 aios team history --provider codex --limit 205.2 上下文打包的“故障开放”策略
默认情况下，ctx-agent在调用contextdb context:pack失败时，会发出警告并继续执行（即不注入上下文，直接运行原生CLI）。这保证了你的交互式会话不会因为临时的上下文打包问题而完全卡死。
如果你希望上下文打包失败时直接报错中止（例如在严格的自动化流水线中），可以设置：
export CTXDB_PACK_STRICT=1需要注意的是，即使设置了CTXDB_PACK_STRICT=1，Shell包装器（codex/claude/gemini）默认仍采用“故障开放”策略，以防止交互式会话被“砖化”。如果要对包装器也强制执行严格模式，需要额外设置：
export CTXDB_PACK_STRICT_INTERACTIVE=15.3 常见问题与排查清单
在实际使用中，你可能会遇到以下问题。这里提供一个快速排查指南：
| 问题现象 | 可能原因 | 排查步骤与解决方案 |
|---|---|---|
运行codex命令无反应或报错command not found | Shell包装器未正确安装或Shell配置未重载。 | 1. 检查~/.zshrc或~/.bashrc中是否存在# >>> contextdb-shell >>>区块。2. 执行 source ~/.zshrc。3. 运行 aiosTUI，进入Setup重新安装shell组件。 |
启动AI CLI时出现better_sqlite3.nodeNode版本不匹配错误 | 系统中Node版本与mcp-server目录下编译的better-sqlite3原生模块版本不兼容。 | 1. 进入RexCLI项目目录：cd /path/to/rex-cli/mcp-server。2. 运行 npm rebuild better-sqlite3。3. 如果不行，尝试 rm -rf node_modules && npm install重新安装。 |
aios doctor报告大量错误 | 环境依赖缺失或配置不一致。 | 1. 确保已安装Node.js 22 LTS和 Git。 2. 在TUI中运行 Doctor并启用Auto-fix native选项。3. 查看Doctor输出的具体错误信息，按指引手动修复。 |
| AI代理似乎没有“记忆” | ContextDB未在该工作区初始化，或包装模式 (CTXDB_WRAP_MODE) 设置不正确。 | 1. 确认当前目录是一个Git仓库。 2. 运行 ls -la memory/context-db/看目录是否存在。3. 检查环境变量 CTXDB_WRAP_MODE。在目标项目根目录运行echo $CTXDB_WRAP_MODE。4. 如果是 opt-in模式，确认存在.contextdb-enable文件。 |
团队任务 (aios team) 卡住或不执行 | 任务规划阶段出错，或子代理客户端配置有误。 | 1. 使用aios hud --watch查看会话状态。2. 使用 --dry-run参数先预览任务计划：aios team 2:codex “任务” --dry-run。3. 检查环境变量 AIOS_SUBAGENT_CLIENT是否设置正确（应为codex-cli,claude-code,gemini-cli之一）。4. 查看 memory/context-db/sessions/<session-id>/下的日志文件。 |
隐私守卫 (privacy) 阻止读取必要文件 | 隐私守卫的规则过于严格。 | 1. 使用aios privacy read --file <文件路径>安全地查看文件内容。2. 检查 ~/.rexcil/privacy-guard.json配置，调整规则或临时禁用：aios privacy disable。 |
5.4 版本管理与升级
RexCLI 项目自身使用语义化版本。你可以通过以下命令管理版本：
# 查看当前版本 cat VERSION # 预览版本升级（不实际修改文件） scripts/release-version.sh --dry-run minor "feat: 新增XX功能" # 实际执行版本升级（例如打补丁） scripts/release-version.sh patch "fix: 修复上下文打包性能问题" # 创建并发布稳定的GitHub Release标签 scripts/release-stable.sh对于使用者来说，升级通常只需要重新运行安装脚本，或者通过TUI中的Update功能来完成。
6. 设计技能实战：在没有设计稿的情况下产出高质量UI
RexCLI 生态中一个非常实用的技能组合是关于UI开发的。很多开发者不擅长设计，也没有现成的设计稿（Design Handoff）。RexCLI 通过awesome-design-md和frontend-design这两个技能的配合，提供了一个高效的解决方案。
核心工作流：
- 锁定风格：首先，使用
awesome-design-md技能，基于一个预设的设计系统（如linear,framer,mintlify）生成或应用一个DESIGN.md文件。这个文件定义了颜色、字体、间距、组件样式等设计令牌（Design Tokens），相当于一份风格契约。 - 实现页面：然后，使用
frontend-design技能，基于DESIGN.md的约束和你的功能描述，来具体实现前端页面。这个技能会确保产出的UI组件严格遵守之前定义的设计系统。
一键安装与使用： 在你的项目根目录下，执行：
# 安装设计相关技能（推荐使用项目作用域） node scripts/aios.mjs setup --components skills --client codex --scope project --skills awesome-design-md,frontend-design # 生成一个设计基线（例如，选择Linear风格，适用于SaaS后台） npx --yes getdesign@latest add linear --force这会在你的项目根目录生成一个DESIGN.md文件。之后，当你给AI（如Codex）下达前端任务时，可以使用固定的指令模板：
首先，请基于项目根目录的 DESIGN.md 文件锁定整体风格。然后，使用 frontend-design 技能来实现 [你的页面描述，例如：一个用户仪表盘，包含数据概览卡片和最近活动列表]。即使你的需求描述很模糊（例如“美化这个页面”、“做一个类似Stripe的登录页”），这个流程也能通过先强制锁定风格，极大地减少AI产出“通用模板”式代码的概率，保证UI的一致性和专业性。
个人体会：这套“设计先行”的流程，本质上是在用机器可读的契约（
DESIGN.md）来替代人类设计师的视觉稿。它虽然不能解决所有设计问题，但对于快速构建内部工具、原型或者需要保持统一风格的系列页面来说，是一个效率利器。它把UI开发从“拍脑袋”和“反复调提示词”变成了一个更可控、可重复的工程化过程。
经过上面几个章节的拆解，你应该对RexCLI从安装、配置、核心概念到进阶应用和故障排查有了全面的认识。它不是一个简单的工具，而是一套旨在提升AI辅助开发范式的系统。真正发挥其威力的关键，在于将其记忆、协作、自动化检查的能力，有机地融入到你的日常开发习惯中。开始时可能会觉得有些复杂，但一旦跑通几个任务，你会发现自己再也回不去那个“健忘”的原始AI工作模式了。
