CLAII (Agencyswarm)

   ██████╗ ██╗      █████╗ ██╗██╗
  ██╔════╝ ██║     ██╔══██╗██║██║
  ██║      ██║     ███████║██║██║
  ██║      ██║     ██╔══██║██║██║
  ╚██████╗ ███████╗██║  ██║██║██║
   ╚═════╝ ╚══════╝╚═╝  ╚═╝╚═╝╚═╝   
   (CLAII)

CLAII–CLI第一个AI编码代理

CLAII（发音为“clay”）是一种 命令行–第一个AI编码代理 这可以：

• 检查和浏览您的项目文件
• 读取文件内容
• 写入/覆盖文件
• 在沙盒工作目录中执行Python代码
• 使用工具调用（函数调用）在代理循环中迭代，直到任务完成
• 使用本地知识库和轻量级内存来保持上下文感知

它被设计成一个小的、可黑客攻击的核心，随着时间的推移，你可以用更多的工具、提供者和代理行为来扩展它。

______________________________________________________________________

✨ 功能（当前）

🧠 代理循环

CLAII在循环中调用LLM，规划工具逐步调用，直到它可以给出最终答案或完成一系列编辑/测试。

📁 文件系统工具（范围）

• get_files_info –列出文件和目录的大小和 is_dir
• get_file_content –使用最大长度保护读取文件内容(MAX_FILE_CHARS)
• write_file –写入/覆盖文件（在允许的工作目录内）
• run_python_file –执行带有超时和输出捕获的Python脚本

🔐 有护栏的工作区

所有工具都限制在配置的工作目录中（默认情况下 ./calculator)以避免代理在您的机器上徘徊。

📚 知识库集成+@提及

• kb/ 工作目录下的文件夹
• `@kb/

` –将知识库内容直接内联到提示中

• `@file:

–提示CLAII通过以下方式检查特定的项目文件 get_file_content`

🧠 轻量级的可选内存

• 将压缩的对话历史记录存储在 .claii_memory.json 每个项目
• 可以禁用 --no-memory
• 历史修剪可以通过以下方式切换 --no-prune

🧮 计算器演示项目

一个小型计算器应用程序(calculator/)CLAII可以读取、修改和运行，用作自动修复错误和重构的测试平台。

🖥️ CLI入口点+ASCII徽标

跑 claii "your prompt here" 在代理旋转之前，会收到CLAII横幅的问候。

______________________________________________________________________

🧭 路线图/计划功能

AgencySwarm/CLAII扩展版本的预期方向：

🔀 可插拔的AI提供商和模型

通过简单的config/CLI开关支持多个后端（例如Google Gemini、OpenAI、Anthropic、本地LLM），并向代理提供统一的工具调用接口。

🧠 更丰富的项目内存

• 存储每个项目的摘要、决策和架构注释
• 提供明确检查/修剪/清除内存的命令

🧰 可扩展工具和MCP集成

• 注册新工具（例如通过MCP、HTTP API、git操作的Neo4j）
• 通过简单的 functions/ 约定和模式声明

🕸️ 多代理Swarms和并行工作流

• 专业代理：bug修复器、重构器、文档编写器、测试运行器等。
• 使用协调层对不同文件/目录进行并行操作

📚 更深入的知识库工作流程

• 知识库意识规划（“先阅读设计文档，然后重构”）
• 结构化知识库摘要和基于嵌入的检索

🎨 改进了CLI用户体验

• 颜色编码的输入/输出和工具痕迹
• 修改文件时可选的差异预览
• “安静”和“调试”模式，用于不同级别的冗长程度

______________________________________________________________________

🧱 架构概述

当前高层布局：

claii/
  __init__.py
  cli.py          # CLI entrypoint (prints logo, parses args, calls run_agent)
  agent.py        # Core agent loop + function dispatch + memory + @mentions
  memory.py       # Load/save compressed conversation history
  config.py       # Provider config (CLAII_PROVIDER, CLAII_MODEL)
  providers.py    # GeminiProvider and future multi-provider abstractions

functions/
  __init__.py
  config.py             # e.g. MAX_FILE_CHARS / function-level config
  get_files_info.py     # get_files_info(...) + schema_get_files_info
  get_file_content.py   # get_file_content(...) + schema_get_file_content
  write_file.py         # write_file(...) + schema_write_file
  run_python.py         # run_python_file(...) + schema_run_python_file
  get_kb_file.py        # get_kb_file(...) + schema_get_kb_file

calculator/
  __init__.py
  main.py         # Calculator CLI app (demo project)
  tests.py        # Unit tests for calculator
  main.txt        # Example text file
  README.md
  pkg/
    __init__.py
    calculator.py
    render.py
    morelorem.txt

pyproject.toml
README.md
.env.example        # Example environment file (optional)
.claii_memory.json  # Created at runtime (per-project memory)

______________________________________________________________________

🧠 代理行为与系统提示

在高层，代理人被指示如下：

能力

• 列出文件和目录
• 读取文件内容
• 使用可选参数执行Python文件
• 写入或覆盖文件

必须始终

• 保持相对于工作目录的路径
• 使用工具而不是猜测文件内容
• 在做出改变之前制定一个计划
• 在可用时通过运行测试来验证更改

重构/修复错误工作流

1. 使用 get_files_info 查找相关文件
2. 使用 get_file_content 检查代码
3. 用自然语言描述一个简短的计划
4. 使用 write_file 应用重点更改
5. 使用 run_python_file 运行测试或脚本进行验证

知识库使用

• `@kb/

→ 被视为参考 kb/ ` 在工作目录下

• `@file:

→ 被视为通过以下方式检查该项目文件的提示 get_file_content`

代理循环不断调用提供者的 generate(...) 方法直到：

• 不再请求工具调用，以及
• 模型返回非空的最终文本。

______________________________________________________________________

📦 安装

需要 Python 3.11+.

# Clone the repo
git clone git@github.com:agencyswarm/CLAII.git
cd CLAII

# Create & activate a virtualenv (recommended)
python -m venv .venv
source .venv/bin/activate  # on Windows: .venv\Scriptsctivate

# Install in editable/dev mode
pip install -e .

# Run once to verify the CLI is installed
claii --help  # (future: help text; for now, just try a prompt)

依赖项

核心依赖关系（声明于 pyproject.toml):

• google-genai –Gemini API客户
• python-dotenv –负载 GEMINI_API_KEY 以及其他环境变量

______________________________________________________________________

🔧 配置

创建一个 .env 项目根目录中的文件至少包含：

GEMINI_API_KEY=your_gemini_api_key_here

当前提供者抽象存在于 claii/providers.py:

• GeminiProvider 包裹 google-genai 手柄：

- API密钥加载(dotenv) - 型号选择(gemini-2.0-flash-001 默认情况下）

可选的未来配置（已通过脚手架搭建 claii/config.py):

CLAII_PROVIDER=google-genai
CLAII_MODEL=gemini-2.0-flash-001

目前， get_provider() 简单地返回a GeminiProvider，但配置类已经到位，以后可以添加更多提供程序。

______________________________________________________________________

🚀 用法

安装后（您的venv处于活动状态）：

1.基本调用

claii "explain how the calculator works"

您应该看到：

• CLAII ASCII标志
• 工具调用线（例如。 Calling function: get_files_info({...}))
• 最后的解释

2.旗帜

当前的CLI是这样连接的：

claii "
" [--verbose] [--no-memory] [--no-prune]

• --verbose\

打印工具调用参数和原始工具结果（对调试有用）。

• --no-memory\

禁用加载/保存 .claii_memory.json 对于当前的项目。\ 代理仅在本次运行中的当前提示+步骤上工作。

• --no-prune\

禁用保存前修剪消息历史记录。\ 默认情况下，只有最后一个 MAX_MEMORY_MESSAGES （例如200）被保留。

示例

# Normal run, memory enabled and pruned
claii "fix the bug where 3 + 7 * 2 returns 20 instead of 17"

# Debug everything, but do not persist history
claii "run the calculator tests" --verbose --no-memory

# Long-running debugging session, keep full history
claii "help me refactor calculator/pkg/calculator.py" --no-prune

3.知识库和@提及

在工作目录下（默认 calculator/)，您可以创建：

calculator/
  kb/
    design.md
    architecture/decisions.md
    lang/agent-architecture.md

在以下提示中使用它们：

# Inline KB context from kb/design.md
claii "Using @kb/design.md, refactor the calculator to follow the design guidelines."

# Hint to a specific project file
claii "Based on @kb/lang/agent-architecture.md, review @file:calculator/pkg/calculator.py and suggest improvements."

行为

• `@kb/

`

- 火柴 KB_PATTERN = r"@kb/([^\s]+)"

- CLAII将其扩展为内联文本：

    Below is the content of knowledge base file "kb/
":
    --- KB START [
] ---
    ... file contents (truncated if very long) ...
    --- KB END [
] ---

• `@file:

`

- 火柴 FILE_PATTERN = r"@file:([^\s]+)"

- CLAII不会自动加载文件，但会将其重写为提示：

    "
" (project file reference; use get_file_content with file_path="
")

其他用途 @ （电子邮件、社交句柄、普通文本）不会被触碰，因为只有这些特定的模式才能被识别。

4.示例提示

列出目录内容：

claii "what files are in the root of the calculator project?" --verbose

读取文件：

claii "read the contents of calculator/main.py"

写一个文件（在工作目录中）：

claii "create a new file calculator/notes.txt summarising what the calculator does"

运行测试：

claii "run the calculator tests in calculator/tests.py"

经典错误修复演示：

claii "fix the bug where '3 + 7 * 2' evaluates to 20 instead of 17 in the calculator"

______________________________________________________________________

🧠 内存模型

内存在中实现 claii/memory.py 作为一个简单的JSON日志：

• 文件： .claii_memory.json 在项目根中
• 架构：列表 { "role": "...", "text": "..." } 记录
• 仅保留角色和连接的文本部分以保持其紧凑性

启动时：

如果内存已启用（默认），CLAII将调用：

messages = load_memory(project_root)

然后，它会附加当前（可能已扩展）的用户提示：

messages.append(
    types.Content(role="user", parts=[types.Part(text=expanded_prompt)])
)

关机时：

如果启用了内存，它可以选择通过以下方式修剪消息 _prune_messages 然后：

save_memory(project_root, messages)

您始终可以禁用内存以进行跑步 --no-memory，或防止修剪 --no-prune.

______________________________________________________________________

🔌 提供商

提供者抽象存在于 claii/providers.py:

class GeminiProvider:
    def __init__(self, model_name: str = "gemini-2.0-flash-001") -> None:
        load_dotenv()
        api_key = os.getenv("GEMINI_API_KEY")
        ...
        self.client = genai.Client(api_key=api_key)
        self.model_name = model_name

    def generate(self, *, messages, tools, system_prompt):
        return self.client.models.generate_content(
            model=self.model_name,
            contents=messages,
            config=types.GenerateContentConfig(
                tools=tools,
                system_instruction=system_prompt,
            ),
        )

代理人只打电话：

provider = get_provider()
response = provider.generate(
    messages=messages,
    tools=[tools],
    system_prompt=system_prompt,
)

未来补充：

• OpenAIProvider
• AnthropicProvider
• LocalProvider （例如vLLM、LM Studio等）

每个只需要实现相同的 generate(...) 签名。

______________________________________________________________________

🧩 扩展CLAII

您可以采取以下项目方向：

1.更多工具

在下面添加模块 functions/ 并将其注册到 agent.py:

• functions/git_tools.py
• functions/http_request.py
• functions/test_runner.py

每个人都应该出口：

• your_tool(...) –纯Python字符串输入/字符串输出
• schema_your_tool – types.FunctionDeclaration 描述其参数

然后将它们纳入：

• _build_tools() –添加到 function_declarations=[...]
• _call_function() –延伸 fn_map = { ... }

2.多代理编排

构建一个更高级别的控制器，该控制器：

• 生成多个 run_agent 具有不同系统提示/角色的调用
• 共享公共内存文件或在代理之间传递摘要

编排思路：

• 规划师→ 实施者→ 测试员→ 审稿人
• 长时间运行的重构管道

3.更好的用户体验

• 使用颜色输出 rich 或 colorama
• 添加一个 --diff 在以下情况下打印最小差异的标志 write_file 更改文件
• 添加 --plan-only 代理仅检查并提出计划而不写入文件的模式

______________________________________________________________________

📝 许可证

版权所有（C）Swarmic LLC。保留所有权利。