本地AI代理系统Cassius：零依赖架构与五层代理梯队设计详解

1. 项目概述：一个完全本地的零依赖AI代理系统

如果你和我一样，对把代码、文档甚至思考过程都交给云端AI服务这件事，心里总有点不踏实，同时又厌倦了每次都要手动切换不同模型、复制粘贴上下文，那么Cassius这个项目可能会让你眼前一亮。简单来说，Cassius是一个运行在你本地电脑上的AI代理“调度中心”。它不是一个单一的聊天机器人，而是一个由21个不同“专长”的AI代理组成的团队，你可以通过一个简单的命令行指令，把任务丢给它，它会自动判断该由团队里的哪位“专家”来处理，甚至可以让多个代理接力完成一个复杂任务。整个过程，数据不出你的电脑，不需要任何API密钥，也无需订阅付费服务，完全依赖本地运行的Ollama和开源大语言模型。

我第一次接触这类多代理系统时，感觉它们要么配置极其复杂，依赖一大堆外部库，要么就是逻辑黑盒，你根本不知道AI们内部是怎么“商量”的。Cassius的设计哲学直接击中了这些痛点：零外部依赖（只用Python标准库）、治理优先（用可读的Markdown文件定义AI的行为准则）、以及透明的记忆系统。这意味着你可以完全掌控、审计并调整整个系统的运作逻辑。它把原本需要复杂编排的AI工作流，简化成了一个cassius “你的任务”这样的命令，这对于开发者、技术写作者或者任何需要频繁借助AI处理复杂事务的人来说，是一个极具吸引力的自动化方案。

2. 核心架构与设计哲学拆解

2.1 为什么是“零依赖”架构？

在Python生态里，构建一个应用动不动就pip install几十个包是常态。但依赖越多，环境配置就越脆弱，跨平台部署也越头疼。Cassius反其道而行之，严格限定只使用Python标准库（如urllib,json,os,pathlib等）。这个决定背后有深刻的考量：

首先，是极致的可移植性和部署简便性。你只需要有Python 3.11+和Ollama，把项目文件拷过去就能运行。没有版本冲突，没有虚拟环境隔离的烦恼，在Windows PowerShell、macOS终端或Linux Bash下行为一致。这对于需要在内网、无外网环境或对安全有严格要求的场景下使用AI能力，是至关重要的。

其次，是降低理解和调试的门槛。所有代码逻辑都是“裸”的Python，没有引入像LangChain这样的重型框架。这意味着当你需要定制代理行为、修改路由逻辑或调试一个诡异的问题时，你面对的代码库是清晰、直接的。你不会被框架抽象的层层接口所迷惑，可以直接看到HTTP请求是如何发送给Ollama，记忆是如何被存储和检索的。这种透明性对于深入使用和二次开发至关重要。

实操心得：坚持零依赖初期会带来一些开发上的不便，比如需要自己写HTTP客户端、管理文件I/O。但长远看，它迫使架构保持精简和模块化。每个.py文件职责都非常单一（如dispatcher.py只管调度，memory_manager.py只管记忆），这反而提升了代码的可维护性。

2.2 五层代理梯队系统的设计逻辑

Cassius最核心的设计之一是它的五层代理梯队系统。这可不是为了听起来酷，而是一种精密的资源分配与任务路由策略。AI模型的能力和消耗的计算资源（时间、内存）差异巨大。用一个70B参数的模型去回答“今天天气如何”，就像用高射炮打蚊子，既浪费又慢。

这个梯队系统本质上是一个成本控制与质量保证的自动化漏斗。用户发起任务后，分类器（或默认规则）会先尝试用低梯队代理处理。如果输出的质量经“百夫长”（Tribune）评审后不达标，则会自动“升级”到更高梯队重试。这样，既保证了简单任务的效率，又为复杂问题保留了强大的后备力量。

2.3 治理文档：用Markdown给AI“立法”

多代理系统最大的风险是“失控”——AI们可能会产生你不期望的行为，或者输出风格不一致。Cassius的创新在于，它用一组纯文本的Markdown文件来定义整个系统的“宪法”和“企业文化”，我称之为治理文档。这些文件会在每次向AI发送请求时，作为系统提示词的一部分自动注入。

• SOUL.md：定义核心身份、价值观和道德准则。例如，“你是一个注重效率、准确性和安全性的辅助工具”、“不得生成有害或违法内容”。这是AI行为的“灵魂”。
• USER.md：描述用户偏好和工作风格。比如，“我喜欢详细的解释，附上代码示例”、“优先使用Python而非JavaScript”。这让AI的输出更个性化。
• BOOTSTRAP.md：规定技术性约束，如输出必须用特定格式（JSON、Markdown）、日志记录规则、令牌长度限制等。这是“操作手册”。
• IDENTITY.md：定义每个代理的“人设”和说话口吻。例如，“Smith代理应像一个经验丰富的工程师，回答务实、简洁”。
• MEMORY.md：存储持久的“真理”和学到的经验教训。例如，“项目X的API密钥格式是…”、“用户曾指出Y方法存在性能问题，应避免使用”。这是系统的长期记忆。

这种设计的巨大优势在于可读性和可维护性。你不需要去修改复杂的Python代码来调整AI的行为，只需用文本编辑器打开对应的.md文件进行编辑。例如，如果你希望所有代码生成都加上注释，只需在USER.md里加一条。这大大降低了管理和定制AI系统的门槛。

3. 从零开始部署与深度配置指南

3.1 基础环境搭建与模型准备

部署Cassius的第一步是确保基础环境就绪。这里不仅包括安装，还包括一些优化设置。

1. 安装Ollama并配置模型库：Ollama是运行本地模型的核心。从官网下载安装后，建议首先配置其模型存储路径（如果默认C盘空间不足）：

# Linux/macOS: 设置环境变量 export OLLAMA_MODELS=/path/to/your/large/disk/models # Windows: 在系统环境变量中新增 OLLAMA_MODELS，值为目标路径，然后重启Ollama服务。

然后，拉取Cassius推荐的核心模型。不建议一次性拉取全部21个模型，这需要极大的磁盘空间（超过100GB）。应采用渐进策略：

# 阶段一：最小可行系统 (约10GB) ollama pull qwen3:4b ollama pull qwen3:8b ollama pull qwen3:14b # 此时，Goblin, Soldier, Centurion三个梯队已可运作。 # 阶段二：增强代码能力 (额外约20GB) ollama pull qwen2.5-coder:7b # 给smith代理，用于代码生成 ollama pull phi4:latest # 给praetor代理，用于复杂规划 # 阶段三：按需扩充 # 根据你常处理的任务类型（如视觉、数学推理），再拉取对应的vl或math专用模型。

2. 获取与部署Cassius项目：克隆项目后，关键的部署步骤是建立其工作空间和配置文件。

git clone https://github.com/Lion55heart55/cassius.git cd cassius # 创建核心工作目录 mkdir -p ~/.openclaw/workspace/cassius_orchestrator mkdir -p ~/.openclaw/workspace/memory # 复制核心文件 cp cassius_orchestrator/*.py ~/.openclaw/workspace/cassius_orchestrator/ cp governance/*.md ~/.openclaw/workspace/ cp openclaw.json ~/.openclaw/

这里有个关键细节：~/.openclaw目录是Cassius的“大脑”所在。所有配置、记忆、任务队列都存储于此。确保该目录所在磁盘有足够空间，并且路径没有中文或特殊字符，以避免潜在的编码问题。

3. CLI集成与路径配置：为了让cassius命令在任意终端窗口可用，需要将其脚本加入系统PATH。

• Windows (推荐使用PowerShell):

  # 假设你把cassius克隆到了 D:\Projects\ copy .\cassius.ps1 C:\Users\YourName\bin\ # 然后将 C:\Users\YourName\bin 添加到系统的PATH环境变量中。

• macOS/Linux:

  chmod +x cassius.sh sudo cp cassius.sh /usr/local/bin/cassius # 需要sudo权限 # 或者仅对当前用户生效： cp cassius.sh ~/.local/bin/cassius

配置完成后，新开一个终端，输入cassius --status，如果能看到Ollama状态和代理列表，说明安装成功。

3.2 深度定制治理文档

安装只是开始，让Cassius真正贴合你的工作习惯，需要精心雕琢治理文档。这些文件位于~/.openclaw/workspace/下。

SOUL.md- 塑造系统品格：这是最重要的文件。不要只写“你要有帮助的”。要具体、可操作。例如：

# Cassius 核心灵魂 - **首要原则：安全与可靠。** 绝不生成或执行可能破坏系统、泄露隐私、或具有误导性的代码或建议。 - **沟通风格：专业且清晰。** 解释概念时，假设对方是聪明的同行，但可能不熟悉该特定领域。使用恰当的术语，但随时准备提供更简单的类比。 - **输出质量：追求精确。** 代码应可运行，解释应有据可查。如果对某个信息不确定，应明确声明“基于我的知识...”，而不是猜测。 - **工作边界：知晓局限。** 你是一个基于文本的AI，无法直接操作图形界面、执行系统命令或访问实时网络信息（除非通过用户提供的文件）。

USER.md- 定义你的偏好：这里是你个性化AI的舞台。越详细，输出越合你心意。

# 用户偏好档案 - **代码风格：** 偏好Python，使用4个空格缩进。所有函数和类必须包含docstring。变量命名使用snake_case。 - **文档需求：** 在提供解决方案时，请先给出一个简洁的“执行摘要”，再展开详细步骤。喜欢使用Markdown表格来对比不同方案。 - **沟通偏好：** 直接回答核心问题，避免冗长的寒暄。在技术分析中，优先考虑可维护性和性能。 - **项目上下文：** 当前主要工作涉及Web后端开发（FastAPI）和数据分析（Pandas）。对前端（React）了解较少。

MEMORY.md- 积累组织知识：这个文件会随着使用而增长。初期可以放一些固定信息，后期可以通过Cassius的--recall功能总结会话后手动添加，或者未来通过脚本自动化。

# 持久记忆与经验教训 - **技术栈决策：** 本项目后端已确定使用FastAPI而非Flask，因其异步支持和自动API文档。 - **已验证的解决方案：** 对于处理大型CSV文件，已确认使用`pandas.read_csv` with `chunksize`参数是内存最优解。 - **需要避免的坑：** 在模块`utils/helpers.py`中，`calculate_metrics`函数在输入为空列表时会抛出异常，需调用前检查。

注意事项：修改治理文档后，无需重启任何服务。因为Cassius在每次任务分发时都会重新读取这些文件。这是其动态性的体现。但要注意，过于冗长的治理文档会挤占每次请求的上下文窗口，可能影响模型处理核心任务的能力。建议定期回顾并精简。

4. 核心工作流与高级功能实战

4.1 单次任务分发与文件分析

最基本的用法是让Cassius处理一个单一任务。其内部流程如下：

1. 解析命令：CLI解析你的指令、选项（如-t指定梯队）和附带的文件。
2. 构建上下文：调度器（dispatcher.py）会加载治理文档、从记忆库中检索相关会话，并读取你通过--file指定的文件内容。
3. 组装提示词：将以上所有信息，加上代理自身的身份指令（来自IDENTITY.md），组合成一个完整的系统提示词。
4. 调用Ollama：通过HTTP POST请求发送到localhost:11434的Ollama API。
5. 评审与响应：获取响应后，交由评审器（reviewer.py）检查。默认会由Tribune（百夫长）代理进行LLM评审，确保质量合格后才输出给你。

文件分析功能是其实用性的一个飞跃。你不再需要手动复制代码到聊天窗口。

# 分析单个文件中的潜在bug cassius "Review this Python script for potential bugs, security issues, and style violations." --file ~/projects/my_app/api.py # 分析整个目录下的特定文件（使用glob模式） cassius "Summarize the purpose and public interface of all model classes." --file ~/projects/my_app/models/*.py # 对比两个版本的差异 cassius "Compare old.py and new.py, highlighting the functional changes and assessing if the refactoring improved readability." --file old.py new.py

内部机制：当使用--file时，Cassius会读取文件内容，并智能地截断（如果文件过大），然后以清晰的格式（如注明文件名和行号）嵌入到给AI的提示词中。这意味着代理是在完整的代码上下文中进行分析的。

4.2 代理链：构建AI流水线

对于复杂任务，单个代理可能力有不逮。Cassius的代理链功能允许你将任务像流水线一样传递给多个代理。

手动链：你明确指定代理的执行顺序。

cassius "Design a simple user authentication module with login and logout endpoints." --chain "smith>tribune"

这个命令会：

1. 首先将任务交给smith代理（擅长代码生成）。
2. 将smith生成的代码和原始任务，一起交给tribune代理（擅长评审）。
3. 最终将tribune的评审意见和（可能修改后的）代码输出给你。 这实现了一种“编写-审查”的微型工作流，能显著提升输出代码的质量。

自动链：你只需一个--chain标志，将规划权交给Tribune。

cassius "Create a project plan for a personal budget tracking web app, including tech stack selection, database schema, and a week-long development timeline." --chain

此时，Tribune会扮演“项目经理”的角色：

1. 任务分解：Tribune首先会分析这个宏大任务，将其拆解成如“市场调研”、“技术选型”、“数据库设计”、“API设计”、“前端原型”、“部署计划”等子任务。
2. 代理分配：根据openclaw.json中定义的代理能力，Tribune为每个子任务分配合适的代理。例如，“技术选型”可能交给oracle（擅长分析），“数据库设计”交给architect。
3. 串行执行：Cassius会按顺序执行这条链，上一个代理的输出会成为下一个代理的输入上下文的一部分。
4. 汇总输出：通常由最后一个代理或Tribune本身生成一份汇总报告。

实操心得：自动链非常强大，但也更不可预测。任务的拆解质量完全取决于Tribune（qwen3:14b）的理解和规划能力。对于非常新颖或模糊的任务，拆解结果可能不尽人意。我的经验是，在启动一个重要的自动链任务前，可以先手动用cassius “如何拆解XX任务” -a tribune来让Tribune给出一个计划预览，满意后再执行--chain。

4.3 记忆系统：让AI拥有“过去”

Cassius的记忆系统分为两部分：会话日志和持久记忆。

• 会话日志：每次任务执行后，完整的交互记录（你的指令、AI的响应、使用的代理、时间戳等）都会以Markdown格式自动保存到~/.openclaw/workspace/memory/目录下，按日期组织。这相当于系统的“短期记忆”或“工作日志”。
• 持久记忆（MEMORY.md）：这是一个需要手动或半手动维护的文件，存储最重要的、需要长期记住的“真理”和“经验”。

记忆系统的威力体现在上下文注入。当你发起一个新任务时，memory_manager.py会自动执行以下操作：

1. 检索相关记忆：它并非简单加载最近几条记录，而是根据你当前任务的关键词，去搜索过去所有会话日志，找出语义上相关的历史对话。
2. 构建记忆上下文：将检索到的相关历史片段，连同MEMORY.md中的内容，一起打包到本次请求的提示词中。
3. 实现连续对话：因此，AI可以“记得”昨天你们讨论过的关于API设计的决定，或者上周你纠正过的一个错误，从而保持对话的一致性和知识的累积性。

使用--recall命令可以主动查询这个记忆库：

# 模糊搜索过去的对话 cassius --recall "authentication" # 这可能返回所有讨论过登录、OAuth、JWT等话题的会话摘要。 # 搜索特定项目或代号 cassius --recall "ORION"

4.4 任务队列与无人值守运行

这是将Cassius从交互式工具升级为自动化助手的关键。你可以将耗时长的任务加入队列，让它在后台（比如夜间）自动运行。

# 将重构CSS的任务加入队列，并设为高优先级 cassius "Refactor all CSS files to use CSS variables for theming and improve mobile responsiveness." --queue --priority high # 加入一个文档生成任务 cassius "Generate README.md for the project in the current directory, covering setup, usage, and API overview." --queue

任务会被添加到~/.openclaw/workspace/task-queue.json文件中。

如何触发队列执行？

1. 手动触发：直接运行python ~/.openclaw/workspace/cassius_orchestrator/cron_runner.py。这个脚本会按优先级顺序处理队列中的所有任务。
2. 自动调度（推荐）：
   • Linux/macOS：利用cron。编辑crontab (crontab -e)，添加一行，例如每天凌晨2点运行：

     0 2 * * * cd /path/to/cassius && /usr/bin/python3 ~/.openclaw/workspace/cassius_orchestrator/cron_runner.py >> ~/.openclaw/cron.log 2>&1

   • Windows：使用任务计划程序。创建一个新任务，触发器设为每日特定时间，操作为启动程序，程序/脚本填写python.exe，参数填写C:\Users\YourName\.openclaw\workspace\cassius_orchestrator\cron_runner.py的完整路径。

队列中的任务执行时，同样会经过完整的代理调度、评审和记忆保存流程。第二天早上，你就能在记忆目录下看到一系列完成的任务报告。

5. 故障排除、性能调优与高级技巧

5.1 常见问题与解决方案

即使设计精巧，在实际运行中也可能遇到问题。以下是一些典型场景及排查思路：

问题1：执行cassius命令后无响应或报连接错误。

• 检查Ollama服务：首先运行ollama serve确保Ollama在后台运行，并且默认端口(11434)未被占用。可以通过curl http://localhost:11434/api/tags测试API是否可达。
• 检查模型是否已加载：cassius --models会列出Cassius识别的模型。如果列表为空或不全，而ollama list里有模型，可能是openclaw.json中的模型名称与本地拉取的名称不完全匹配。需要仔细核对并修改json文件。
• 查看详细日志：Cassius的CLI脚本通常有日志输出。在命令后添加--verbose（如果支持）或直接运行底层的Python脚本python cassius_cli.py “你的任务”来查看更详细的错误信息。

问题2：代理输出质量不稳定，或经常被评审器（Tribune）驳回。

• 调整治理文档：输出质量差往往与提示词不清晰有关。检查SOUL.md和IDENTITY.md，确保对代理的职责和输出格式要求描述得足够明确、具体。例如，为“smith”代理增加“生成的代码必须包含错误处理”的指令。
• 检查记忆注入：过多的、不相关的历史记忆可能会干扰当前任务。可以临时清空memory/目录下的日志文件（但保留MEMORY.md）进行测试。或者，在memory_manager.py中调整检索相关记忆的数量上限。
• 手动指定更高梯队：如果某个任务在低梯队（如Soldier）反复失败，可以尝试直接用-t Centurion或-a tribune指定由能力更强的代理处理，以判断是任务本身过难，还是路由逻辑有问题。

问题3：处理大文件时速度慢或出错。

• 文件截断逻辑：Cassius内置了文件内容截断机制以防止超出模型上下文长度。但如果文件极大，读取和预处理仍会耗时。考虑将大任务拆分成针对多个小文件的多次调用。
• 模型自身限制：即使是14B或32B模型，其上下文窗口也是有限的（通常8K-128K令牌）。对于超长代码文件，AI可能无法看到全部内容。需要人工进行模块化拆分后再提交分析。

问题4：任务队列cron_runner.py执行失败。

• 路径问题：计划任务（cron或Task Scheduler）执行时的当前工作目录与环境变量可能与终端中不同。确保在脚本中使用绝对路径来引用~/.openclaw目录和其他资源。可以在cron_runner.py开头添加os.chdir(os.path.expanduser(‘~/.openclaw’))。
• Python环境问题：确保计划任务使用的Python解释器与终端中使用的相同，并且具有执行脚本的所有权限。

5.2 性能调优与实践建议

要让Cassius运行得更快、更稳、更省资源，可以考虑以下调优点：

1. 模型加载策略：Ollama默认会在首次使用某个模型时加载它到GPU/内存，并在闲置一段时间后卸载。频繁在大小模型间切换会导致加载延迟。对于你最常用梯队的模型（比如Soldier层的qwen3:8b），可以设置Ollama让它常驻内存：

# 在Ollama的config文件（通常位于~/.ollama/config.json）中可尝试配置，但Ollama本身管理机制已较智能。 # 更实用的方法是：在启动Cassius进行长时间工作前，手动用ollama run预热模型。 ollama run qwen3:8b “hello” # 先加载模型 # 之后Cassius调用该模型时就会快很多。

2. 优化提示词长度：治理文档和记忆注入是双刃剑，它们提供了上下文，但也消耗了宝贵的令牌数。定期审视你的SOUL.md、USER.md，删除冗余、模糊的表述，力求精炼。对于MEMORY.md，只保留真正普适、重要的经验，将具体会话细节留给自动检索的日志。

3. 阶梯式使用策略：遵循Cassius的设计初衷，养成“从小开始”的习惯。先尝试用-t Goblin或默认的Soldier层处理任务。只有在其输出被评审驳回或明显不满意时，才考虑手动升级。避免所有任务都直奔Sovereign层，这将极大增加响应时间和资源消耗。

4. 利用好--no-review标志：对于非常简单、结果对错立判的任务（如“将这段JSON格式化”），可以添加--no-review跳过Tribune的LLM评审环节，直接输出结果，能节省近一半的时间（因为少了一次模型调用）。

5.3 扩展与自定义代理

Cassius的代理注册表在~/.openclaw/openclaw.json。你可以修改这个文件来增删改代理。

添加一个自定义代理：假设你想添加一个专门用于编写Shell脚本的代理，名为shellwright，使用qwen3:8b模型，并属于Soldier梯队。

1. 在openclaw.json的"agents"列表中添加一个新对象：

   { "name": "shellwright", "model": "qwen3:8b", "tier": 1, "description": "Specialist in writing robust, portable shell scripts (bash, zsh). Focuses on error handling and clarity.", "tags": ["code", "shell", "automation"] }

2. 在~/.openclaw/workspace/IDENTITY.md中，为这个新代理添加身份描述：

   ## shellwright You are an expert in shell scripting across Unix-like environments (Linux, macOS). Your primary goal is to write scripts that are clear, robust, and portable. You always include proper error checking (set -euo pipefail), informative comments, and consider edge cases. You prefer using built-in commands over external tools when possible for better compatibility.

3. 现在你就可以通过cassius -a shellwright “Write a script to backup my documents folder”来调用这个专属代理了。

修改代理路由规则：默认的路由逻辑在classifier.py和orchestrator.py中。如果你想改变“什么任务去哪层”的规则，例如将所有包含“安全审计”关键词的任务直接路由给Centurion层的tribune，你需要修改classifier.py中的任务分类逻辑。这需要一定的Python编程能力，但得益于项目零依赖和清晰的代码结构，这个修改过程比在大型框架中要直观得多。

Cassius展现了一种构建本地化、可控、复合型AI应用的优雅范式。它不追求大而全的通用性，而是通过清晰的架构、可读的配置和模块化的设计，将多个专用AI模型组织成一个高效的“数字团队”。从简单的代码评审到复杂的项目规划，这个团队都能在你的指挥下协同工作，并且所有对话与产出都牢牢留在你的本地硬盘上。