简介

ecode 是一个开源的终端 AI 编程智能体，类似于 Claude Code / Cursor / Aider，但完全可控 -- 你可以接入任何 OpenAI 兼容的 LLM（DeepSeek、通义千问、OpenAI 等），数据不离开本地环境。

功能特性

快速开始

安装

pip install ecode-agent

首次运行

cd your-project
ecode

首次运行自动弹出初始化向导，选择 LLM 提供商、输入 API Key 即可开始。

手动配置

方式一：config.yaml

# .ecode/config.yaml
llm:
  active: "deepseek"
  configs:
    deepseek:
      provider: openai
      model: deepseek-chat
      api_key_env: DEEPSEEK
      base_url: https://api.deepseek.com/v1
      temperature: 0
      streaming: true
      stream_usage: true

方式二：环境变量

export ECODE_API_KEY="your-api-key"
export ECODE_MODEL="deepseek-chat"
export ECODE_BASE_URL="https://api.deepseek.com/v1"

使用方法

CLI 交互

ecode

直接用自然语言对话：

> 帮我看看 src/ 下有哪些文件
> 把 main.py 里的 print 改成 logging
> 运行 pytest 并告诉我结果
> 分析一下这个项目的架构，写到 docs/ 里

斜杠命令

权限模式

API 服务

python main.py

支持的 LLM

ecode 通过 OpenAI 兼容接口连接 LLM，接入任何兼容服务商只需改配置：

项目结构

ecode/
├── agent.py                    # 核心 LangGraph 状态机
├── main.py                     # FastAPI 服务入口
├── model.py                    # LLM 工厂，配置加载
├── session.py                  # 会话管理（内存 / MySQL）
├── context_manager.py          # 5 层上下文压缩
├── settings.py                 # 多层级设置合并
├── project_context.py          # .ecode.md 项目上下文
├── schemas.py                  # Pydantic 数据模型
│
├── cli/                        # CLI 终端界面
│   ├── chat.py                 #   主循环、斜杠命令、审批
│   ├── display.py              #   Rich 渲染引擎
│   ├── approval.py             #   审批详情（diff / 预览）
│   ├── interactions.py         #   输入、菜单、粘贴处理
│   └── live_status.py          #   实时状态指示器
│
├── tools/                      # 工具集（27 个工具）
│   ├── file_tools.py           #   文件操作
│   ├── search_tools.py         #   搜索与浏览
│   ├── command_tools.py        #   Shell 命令
│   ├── git_tools.py            #   Git 操作
│   ├── agent_tool.py           #   子智能体
│   ├── memory_tools.py         #   记忆存取
│   ├── task_plan_tools.py      #   任务规划
│   ├── tool_executor.py        #   并行执行引擎
│   └── tool_index.py           #   工具索引表
│
├── permissions/                # 权限系统
│   ├── modes.py                #   4 种权限模式
│   └── rules.py                #   规则引擎
│
├── hooks/                      # Hook 系统
│   ├── executor.py             #   Hook 执行引擎
│   └── types.py                #   事件类型定义
│
├── memory/                     # 记忆系统
│   ├── loader.py               #   记忆加载
│   ├── writer.py               #   记忆写入
│   └── extractor.py            #   LLM 记忆提取
│
├── context/                    # Token 计数
│   └── token_counter.py
│
├── tasks/                      # 后台任务管理
├── utils/                      # 工具函数
│
├── tests/                      # 测试
│   ├── test_cli.py             #   CLI 渲染测试
│   ├── test_e2e.py             #   端到端演示
│   └── test_stream.py          #   流式输出测试
│
├── scripts/                    # 开发脚本
│   └── debug/                  #   调试工具
│
├── docs/                       # 文档
│   └── architecture.md         #   架构设计文档
│
├── config.yaml.example         # 配置文件模板
├── pyproject.toml              # 项目元数据与构建配置
├── requirements.txt            # Python 依赖
└── LICENSE                     # MIT 许可证

配置参考

# API 服务
backend:
  url: "http://127.0.0.1:8000"
  timeout: 30000

# 数据库（可选，持久化会话）
database:
  host: localhost
  port: 3306
  user: root
  password_env: ECODE_DB_PASSWORD
  database: ecode

# LLM 模型
llm:
  active: "model-name"
  configs:
    model-name:
      provider: openai
      model: deepseek-chat
      api_key_env: API_KEY
      base_url: https://...
      temperature: 0
      streaming: true
      stream_usage: true

{
  "permissions": [
    {"tool": "run_command", "pattern": "git commit*", "behavior": "allow"},
    {"tool": "edit_file", "pattern": "*.test.py", "behavior": "allow"}
  ],
  "hooks": [
    {
      "event": "PreToolUse",
      "type": "shell",
      "command": "echo 'Calling ${ECODE_TOOL_NAME}'",
      "matcher": "run_command"
    }
  ]
}

# 项目说明

这是一个 Python Web 项目，使用 FastAPI + SQLAlchemy。

## 编码规范
- 使用 type hints
- 函数命名用 snake_case
- 测试文件放在 tests/ 目录

架构文档

详细的系统架构、模块设计、数据流分析请参阅 docs/architecture.md。

开发

# 安装依赖
pip install -e .

# 运行 CLI
ecode

# 运行 API 服务
python main.py

# 运行测试
python -m tests.test_cli

License

MIT