CodingClaw Agent 学习笔记

项目概述

CodingClaw Agent 是一个用 Python 开发的个人编程助手（Personal Coding Agent），专注于本地编码工作流程。它是一个单智能体系统，支持通过命令行界面（CLI）和 JSON-RPC 与 AI 模型交互。

核心特性

特性	说明
单智能体编码工作流	集成的 AI 助手，帮助完成编程任务
OpenAI 兼容模型网关	支持任何 OpenAI 兼容的 API（默认 Kimi K2.5）
本地 JSONL 会话和日志	所有数据以 JSONL 格式本地存储
双接口支持	CLI 交互模式 + JSON-RPC over stdin/stdout
MCP 客户端	支持连接 MCP（Model Context Protocol）服务器
Python 技能加载器	支持带提示模板的技能系统

项目结构

codingclaw-agent/
├── app/                          # 主应用代码
│   ├── config.py                 # 配置管理
│   ├── types.py                  # 数据类型定义
│   ├── agent/                    # 智能体核心
│   │   ├── runner.py             # 主运行器（核心协调器）
│   │   ├── context.py            # 上下文管理
│   │   └── compactor.py          # 上下文压缩
│   ├── interfaces/               # 接口层
│   │   ├── cli/main.py           # CLI 入口
│   │   └── rpc.py                # JSON-RPC 接口
│   ├── mcp/                      # MCP 客户端
│   │   └── client.py             # MCP 服务器连接管理
│   ├── models/                   # 模型层
│   │   ├── base.py               # 基础模型接口
│   │   ├── openai_compatible.py  # OpenAI 兼容实现
│   │   └── registry.py           # 模型注册表
│   ├── skills/                   # 技能系统
│   │   └── loader.py             # 技能加载器
│   ├── storage/                  # 存储层
│   │   ├── artifacts.py          # 工件存储
│   │   ├── logs.py               # 日志写入
│   │   └── sessions.py           # 会话存储
│   └── tools/                    # 工具系统
│       ├── builtins.py           # 内置工具
│       └── permissions.py        # 权限管理
├── .codingclaw/                  # 本地数据目录
│   ├── config.json               # 配置文件
│   ├── logs/                     # 日志文件
│   └── sessions/                 # 会话数据
├── example.config.json           # 配置示例
└── pyproject.toml                # Python 项目配置

核心入口文件

1. CLI 主入口

文件: app/interfaces/cli/main.py

参数解析（argparse）
命令分发（models, tools, skills, sessions）
交互式会话循环
RPC 模式启动

def main() -> None:
    parser = build_parser()
    args = parser.parse_args()
    raise SystemExit(asyncio.run(_run(args)))

2. 核心协调器

文件: app/agent/runner.py

AgentRunner 类协调所有组件：

初始化子系统（模型、存储、工具、技能、MCP）
管理会话生命周期
处理用户提示的完整流程
协调工具调用和权限确认

3. RPC 服务器

文件: app/interfaces/rpc.py

提供 JSON-RPC 接口，支持方法：

start_session - 创建会话
send_message - 发送消息
list_sessions - 列出会话
list_tools - 列出工具
list_models - 列出模型
list_skills - 列出技能

4. 配置系统

文件: app/config.py

def load_config(config_path=None, workspace=None) -> AgentConfig:
    # 加载 ~/.codingclaw/config.json
    # 支持环境变量覆盖
    # 初始化目录结构

核心组件详解

AgentRunner（智能体运行器）

class AgentRunner:
    def __init__(self, config: AgentConfig, approval_callback):
        self.registry = ModelRegistry()          # 模型注册表
        self.provider = self.registry.create(...) # AI 模型提供者
        self.context_manager = ContextManager(...) # 上下文管理
        self.compactor = Compactor()             # 上下文压缩
        self.session_store = SessionStore(...)   # 会话存储
        self.tool_runtime = ToolRuntime(...)     # 工具运行时
        self.skill_loader = SkillLoader(...)     # 技能加载器
        self.permission_policy = PermissionPolicy(...) # 权限策略

核心方法: prompt(session_id, user_prompt, mcp_tools)

处理流程：

加载会话历史消息
添加系统提示和上下文
激活匹配的技能
添加用户消息
压缩上下文（如果超过阈值）
调用模型 API
处理工具调用（循环）
保存会话状态

内置工具（ToolRuntime）

工具名	功能	需要确认
`list_files`	列出目录文件	否
`read_file`	读取文件内容	否
`grep_search`	搜索文本	否
`write_file`	写入文件	是
`edit_file`	编辑文件（替换文本）	是
`run_shell`	执行 shell 命令	是
`export_markdown`	导出 Markdown	是

MCP 客户端（MCPClientManager）

连接外部 MCP 服务器获取额外工具：

class MCPClientManager:
    async def connect_all(self) -> None:
        # 启动 MCP 服务器子进程
        
    async def list_tools(self) -> list[ToolSpec]:
        # 获取 MCP 工具列表
        
    async def call_tool(self, server, tool, args) -> dict:
        # 调用 MCP 工具

数据类型定义

# 核心数据类型
@dataclass
class Message:
    role: Role              # system | user | assistant | tool
    content: str
    name: str | None        # 工具名
    tool_call_id: str | None
    timestamp: float

@dataclass
class ToolSpec:
    name: str
    description: str
    input_schema: dict
    requires_confirmation: bool
    handler: Callable

@dataclass
class SessionEvent:
    type: EventType         # message | tool_call | tool_result | ...
    payload: dict
    timestamp: float
    id: str

配置说明

配置文件位置

~/.codingclaw/config.json

配置示例

{
  "provider_name": "openai-compatible",
  "model_id": "kimi-k2.5",
  "base_url": "https://api.moonshot.cn/v1",
  "api_key_env": "CODINGCLAW_API_KEY",
  "supports_tools": true,
  "supports_reasoning": false,
  "compat_flags": {
    "supports_developer_role": false,
    "supports_reasoning_effort": false
  },
  "mcp_servers": [
    {
      "name": "filesystem",
      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/path/to/workspace"],
      "enabled": true
    }
  ]
}

环境变量

变量名	说明
`CODINGCLAW_API_KEY`	API 密钥
`CODINGCLAW_MODEL`	模型 ID（覆盖配置）
`CODINGCLAW_BASE_URL`	API 基础 URL（覆盖配置）
`CODINGCLAW_HOME`	数据目录（默认 `~/.codingclaw`）

使用方式

安装

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e .

CLI 命令

# 启动交互式会话
codingclaw

# 单次提问
codingclaw --prompt "分析项目结构"

# 指定工作目录
codingclaw --workspace /path/to/project

# 查看支持的模型
codingclaw models

# 查看可用工具
codingclaw tools

# 查看技能列表
codingclaw skills

# 查看会话列表
codingclaw sessions

# 继续指定会话
codingclaw --session <session_id>

# JSON-RPC 模式
codingclaw --mode rpc

交互式命令

在交互式会话中可用：

/exit 或 /quit - 退出会话

数据流向

用户输入
    │
    ▼
┌─────────────────┐
│  CLI / RPC 接口  │
└─────────────────┘
    │
    ▼
┌─────────────────┐
│  AgentRunner    │
│  - 加载会话      │
│  - 激活技能      │
│  - 压缩上下文    │
└─────────────────┘
    │
    ▼
┌─────────────────┐
│  Model Provider │
│  (OpenAI API)   │
└─────────────────┘
    │
    ▼
┌─────────────────┐
│  处理响应        │
│  - 直接回复      │
│  - 工具调用      │
└─────────────────┘
    │
    ├──────────────┬──────────────┐
    ▼              ▼              ▼
内置工具      MCP 工具       保存结果
    │              │              │
    └──────────────┴──────────────┘
                   │
                   ▼
            返回给用户

技术栈

组件	用途
Python 3.9+	编程语言
httpx	异步 HTTP 客户端
PyYAML	YAML 解析
asyncio	异步编程
subprocess	MCP 服务器进程管理
argparse	命令行参数解析
dataclasses	数据模型定义

设计亮点

模块化架构 - 清晰的层次划分（接口、智能体、模型、工具、存储）
本地优先 - 所有数据本地存储（JSONL 格式），保护隐私
双模式支持 - CLI 交互模式和 JSON-RPC 模式，灵活集成
工具安全 - 敏感操作（写文件、执行命令）需要用户确认
上下文管理 - 自动压缩历史消息，控制 token 消耗
技能系统 - 基于触发词自动加载提示模板
MCP 扩展 - 通过 Model Context Protocol 连接外部工具生态
OpenAI 兼容 - 支持任何 OpenAI 兼容的 API 提供商

学习要点

1. 智能体设计模式

协调器模式（AgentRunner 协调多个子系统）
工具注册和发现机制
权限控制策略

2. 异步编程实践

asyncio 用于并发操作
异步 HTTP 请求（httpx）
异步子进程管理（MCP）

3. 数据持久化

JSONL 格式用于追加写入
会话数据的读写模式
日志和事件的分离存储

4. 协议实现

JSON-RPC 2.0 协议
MCP（Model Context Protocol）
OpenAI API 兼容层

5. 安全考虑

路径逃逸检查（workspace 限制）
命令执行超时控制
敏感操作的用户确认

扩展方向

添加新工具 - 在 app/tools/builtins.py 中定义
添加新模型 - 在 app/models/ 中实现 BaseProvider
添加新技能 - 在 skills 目录创建 YAML 定义
集成 MCP 服务器 - 在配置中添加 mcp_servers

笔记创建时间: 2024 项目版本: 0.1.0

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

CodingClaw Agent 学习笔记

项目概述

核心特性

项目结构

核心入口文件

1. CLI 主入口

2. 核心协调器

3. RPC 服务器

4. 配置系统

核心组件详解

AgentRunner（智能体运行器）

内置工具（ToolRuntime）

MCP 客户端（MCPClientManager）

数据类型定义

配置说明

配置文件位置

配置示例

环境变量

使用方式

安装

CLI 命令

交互式命令

数据流向

技术栈

设计亮点

学习要点

1. 智能体设计模式

2. 异步编程实践

3. 数据持久化

4. 协议实现

5. 安全考虑

扩展方向

FilesExpand file tree

overview.md

Latest commit

History

overview.md

File metadata and controls

CodingClaw Agent 学习笔记

项目概述

核心特性

项目结构

核心入口文件

1. CLI 主入口

2. 核心协调器

3. RPC 服务器

4. 配置系统

核心组件详解

AgentRunner（智能体运行器）

内置工具（ToolRuntime）

MCP 客户端（MCPClientManager）

数据类型定义

配置说明

配置文件位置

配置示例

环境变量

使用方式

安装

CLI 命令

交互式命令

数据流向

技术栈

设计亮点

学习要点

1. 智能体设计模式

2. 异步编程实践

3. 数据持久化

4. 协议实现

5. 安全考虑

扩展方向