项目定位与目标

Eling Agent 是一个面向开发者的个人自主代理 CLI 工具，运行于本地终端，提供持续可用的记忆、技能库与模型调用能力。它旨在让单一用户在本地终端内即可完成"对话—检索—执行—沉淀"的完整闭环，避免在不同工具间来回切换。 资料来源：README.md:1-40

项目自 v0.1.0 首发以来，经过多轮迭代（v0.1.0 → v0.2.3），逐步形成了以"本地优先 + 可扩展"为核心的架构，社区关注点集中于：记忆持久化、技能自学习、MCP 工具接入、TUI 主题化以及自动化测试/检查回路。

核心能力概览

Eling Agent 的能力可分为五大支柱，可对照 README 与架构文档进行映射：

资料来源：docs/architecture.md:1-60 资料来源：README.md:20-80

安装与首次启动

环境要求

• Python ≥ 3.10（参考 pyproject.toml 中的构建配置）
• 终端需支持 ANSI 颜色与 Unicode（Banner 中的 ⏱、🤖 等符号依赖此能力）
• 推荐使用本地 Ollama 或 OpenAI 兼容 API 作为模型后端

基础安装步骤

`` git clone https://github.com/PatrickNoFilter/eling-agent.git cd eling-agent ``

`` pip install -e . ``

`` eling setup ` 在 eling setup` 中可选择主题（10 种配色：blue、pink、green、yellow、red、white、ocean、twilight、pastel、cobalt），这一入口在 v0.2.0 中正式加入。 资料来源：docs/configuration.md:1-40

`` eling `` 启动后会显示带 ⏱ 计时的 Banner、🤖 模型名，以及模型推理的暗色面板。

1. 克隆仓库并进入目录：
2. 安装依赖（以 pip 为例）：
3. 准备配置文件：复制 config.example.json 为本地 config.json，填入模型 API Key、工作区路径等字段。 资料来源：config.example.json:1-40
4. 首次启动并进入引导式配置：
5. 启动 TUI 会话：

常用命令与配置要点

CLI 入口 src/eling_agent/cli.py 负责解析子命令与参数，常用命令包括：

• eling —— 启动富 TUI 主会话
• eling setup —— 引导式首次配置（含主题选择）
• /new —— 清屏并重启当前会话（v0.1.5 引入）
• compact 模式 —— 非 TUI 启动时执行清屏（v0.1.5 修复）

配置文件 config.example.json 暴露若干关键键值，例如：

• verbose_tool_output：切换是否在 TUI 中显示完整工具参数与结果（v0.2.3 新增）
• theme：控制 TUI 配色方案（v0.2.0 新增）
• 模型、记忆、MCP 服务器等条目按子对象组织

资料来源：src/eling_agent/cli.py:1-80 资料来源：config.example.json:1-80

自动化工作回路（v0.2.3）

最新版本引入了三层自动化回路，可在配置中启用：

1. Auto-pytest —— 每轮工具调用结束后，自动对被修改的测试文件运行 pytest，并把失败结果回灌给模型，让其修复。
2. Auto-fix lint —— 使用 Ruff 自动修复安全级别的风格问题，再次检查后报告剩余不可自动修复项。
3. Verbose tool output —— 在 TUI 中显示工具的完整参数与返回值，便于调试与审计。

社区用户普遍关注"自动测试回路是否会拖慢首字延迟"，因此建议在调试会话中关闭 verbose 输出，仅在排障时启用。

快速体验路径

对于初次使用者，推荐按以下顺序体验：

1. 运行 eling setup 完成模型与工作区配置，选择一个主题。
2. 输入一句简短任务（如"帮我看看当前目录的 Python 文件结构"），观察 Banner、计时与思考面板。
3. 触发一次工具调用，验证 MCP 或本地工具是否正常返回。
4. 连续进行多轮对话，验证 continue 指令与历史记忆（v0.1.1 起的会话历史能力）。 资料来源：docs/index.md:1-40
5. 查看 docs/memory.md 与 docs/plugins.md，按需启用 8 层记忆或编写自定义插件。

完成以上步骤后，即可在日常开发中把 Eling Agent 作为常驻终端代理使用，并根据团队需要逐步引入 MCP 服务器、技能沉淀与自动化测试回路。 资料来源：README.md:60-120

概述

eling-agent 的「记忆与技能系统」由两条互补的子系统组成：负责跨会话持久化与检索的记忆层 (Memory)，以及负责自动抽取与复用模式的技能库 (Skills)。记忆系统提供原始事实与上下文的存取能力，技能系统则把这些经验固化为可复用的工作流，二者共同支撑 Agent 在多轮交互中的连续性与自学习能力。资料来源：memory.py:1-80，skills.py:1-60。

记忆系统

分层架构

记忆系统采用「分层 (Layer)」抽象，把不同来源、不同结构的存储介质统一为可检索的记忆单元。自 v0.1.2 起内置 8 层记忆，每层都是 MemoryLayer 接口的实现。资料来源：src/eling/layers/builtin.py:1-120。

本地检索管线

本地优先的记忆查询走 BM25 与余弦相似度混合打分，由 textsim.py 提供向量与词面相似度的融合实现，memory.py 负责包装索引、查询与回填流程。资料来源：memory.py:80-180，textsim.py:1-90。

内容去重

v0.2.0 引入了基于 SHA-256 的内容哈希去重，避免相同片段被反复入库导致检索噪声与存储膨胀。资料来源：memory.py:180-240。

Blackbox 黑匣子

Blackbox 既是记忆的第 1 层，也是独立的「飞行记录器」，对每个回合记录完整上下文事件，并由 score.py 用 11 项指标对上下文效率打分，便于事后回溯与提示调优。资料来源：src/eling/blackbox/core.py:1-150，src/eling/blackbox/score.py:1-120。

flowchart LR
    U[用户输入] --> A[Agent 推理]
    A --> M{memory.py 查询}
    M --> BM[BM25 索引]
    M --> CS[余弦相似度]
    BM --> R[融合排序]
    CS --> R
    R --> Ctx[注入上下文]
    A --> S{skills.py 匹配}
    S --> Sk[技能库]
    Sk --> Ctx
    Ctx --> BB[Blackbox 记录]
    BB --> Sc[score.py 打分]
    Sc --> Persist[(持久化层)]

技能系统

自动学习

skills.py 在每个回合结束后，根据对话轨迹与示例提示自动抽取可复用模式（例：live-elapsed-timer、system-health-check），并把候选技能写入技能库。v0.2.2 改用「示例驱动」的 system prompt 以提高抽取相关性。资料来源：skills.py:60-180。

质量门控

v0.2.2 新增质量门控，拒绝低于 50 字符的正文以及通用名（如 fix、debug、help），防止低质量条目污染技能库。资料来源：skills.py:180-260。

自动遗忘

v0.2.2 引入「零使用」剪枝策略：使用次数为 0 的技能在指定周期后自动从库中剔除，使技能库随时间收敛于真正有价值的模式。资料来源：skills.py:260-340。

协同工作流

记忆层负责「事实」——发生了什么、查到了什么、上下文是什么；技能层负责「方法」——面对相似情境该用怎样的工具组合与步骤。两者通过 memory.py 与 skills.py 的查询接口在每个回合的提示构造阶段被共同调用，并由 Blackbox 同步落盘以便事后审计。资料来源：memory.py:240-320，skills.py:340-420，src/eling/blackbox/core.py:150-260。

关键配置与开关

• verbose_tool_output：v0.2.3 引入，控制 TUI 是否完整展示工具参数与返回结果，影响技能复用时的可见性。资料来源：skills.py:420-460。
• 内容去重开关：默认启用 SHA-256 去重，可通过记忆层参数调整粒度。资料来源：memory.py:320-360。
• Blackbox 打分阈值：score.py 中的 11 项指标可独立加权。资料来源：src/eling/blackbox/score.py:120-220。

概述

Eling Agent 通过 MCP（Model Context Protocol） 把外部工具、数据源和子系统暴露给语言模型，使模型能够在不修改主循环的前提下获得"调用文件系统、抓取网页、查询知识库"等能力。与之并行的插件系统则提供 @tool 装饰器，让用户在内置插件目录中以 Python 函数的形式直接贡献新工具。

资料来源：src/eling/mcp/client.py:1-40

两套机制的关系可以概括为：MCP 是进程外扩展（外部 stdio/SSE 服务器），插件是进程内扩展（同一解释器中注册的 Python 函数）。模型侧看到的都是统一的"工具 schema"——名称、参数 JSON-Schema、返回值类型——因此调度逻辑无需区分来源。

整体架构

flowchart LR
    A[Agent 主循环] --> B[工具路由器]
    B --> C[MCP 客户端]
    B --> D[插件注册表]
    C --> E[as_brain]
    C --> F[blackbox]
    C --> G[continuum]
    C --> H[markdownify]
    D --> I[用户 @tool 插件]
    D --> J[内置插件]
    E --> K[(知识库 / 记录)]
    F --> L[(飞行记录)]
    G --> M[(持续记忆)]
    H --> N[(文档转换)]

启动时，MCP 客户端读取用户配置中的服务器列表并完成握手；插件注册表扫描插件目录，把所有带 @tool 装饰的函数纳入字典。两边的结果合并后，作为工具列表一次性发给模型。

资料来源：src/eling/mcp/client.py:42-88

MCP 客户端与内置服务器

MCP 客户端负责连接 4 个官方服务器（v0.1.2 起整合到仓库内）：

每个 mcp_server.py 都遵循同一模板：声明 mcp = FastMCP("name")，用 @mcp.tool() 装饰若干函数，再以 mcp.run() 暴露 stdio 入口。客户端侧通过 stdio_client 建立子进程并调用 list_tools / call_tool。

资料来源：src/eling/as_brain/mcp_server.py:1-30 资料来源：src/eling/blackbox/mcp_server.py:15-55

插件系统与 `@tool` 装饰器

v0.2.3 引入的 @tool 装饰器（src/eling/plugins/decorator.py）让贡献工具的步骤从"改 YAML + 重启"压缩为"写一个函数"：

from eling.plugins import tool

@tool(name="web_fetch", description="抓取 URL 并返回正文 Markdown")
def web_fetch(url: str) -> str:
    ...

PluginRegistry 在启动时扫描 ~/.eling/plugins/，反射读取函数签名生成 JSON-Schema，并把函数对象存进 self._tools[name]。模型请求 call_tool 时，路由器先查注册表，未命中再转发给 MCP 客户端，从而保证内置优先级最高且同名工具去重。

资料来源：src/eling/plugins/decorator.py:10-45 资料来源：src/eling/plugins/registry.py:20-70

配置与扩展指南

MCP 服务器在用户配置文件中以列表形式声明，每项包含 name、command（stdio 模式）或 url（SSE 模式）以及可选 env：

mcp_servers:
  - name: filesystem
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
  - name: firecrawl
    url: http://localhost:3000/sse

新增插件只需把带 @tool 的 .py 文件放到 ~/.eling/plugins/，下次启动即可热加载。常见问题——例如某个 MCP 服务器启动后模型"看不到工具"——多由 stdio 握手超时或 list_tools 返回为空导致，可通过 verbose_tool_output 配置（v0.2.3）观察完整参数与返回值来排查。

资料来源：docs/mcp.md:1-60

概述

eling-agent 的终端界面、主题系统与配置层共同构成 CLI 中"看得见、改得动"的全部用户表面。TUI 基于 Rich 库渲染横幅、思考旋转器、计划面板、Markdown 与推理面板等元素；主题系统通过 10 套内置配色统一边框、面板、工具栏等视觉风格；配置体系则将模型、记忆、工具行为等参数持久化为 JSON，并通过 eling setup 向导进行交互式维护。三者围绕 config.json 解耦，运行时由 src/eling/__main__.py 串接。资料来源：src/eling/cli.py:1-60

1. 终端用户界面 (TUI)

TUI 由 tui.py 实现，关键组件包括：

• 横幅 (Banner)：启动时展示，含 agent 名称与当前模型（带 🤖 图标），自 v0.1.1 起引入。资料来源：v0.1.1 release notes
• 会话计时器：⏱ 计数器在每个回合（横幅、用户输入、助手面板）刷新；v0.1.5 修复了启动横幅上 0 秒的显示问题。资料来源：v0.1.5 release notes
• 思考旋转器 (Spinner)：模型推理期间显示，渲染样式受当前主题控制。资料来源：tui.py:140-200
• 计划面板 (Plan Panel)：展示即将执行的工具调用步骤。资料来源：tui.py:200-260
• 推理面板 (Reasoning Panel)：以紧凑、低亮度样式呈现模型的思维链（chain-of-thought）。资料来源：tui.py:260-320

v0.1.5 还修复了 TUI 中缺失的 threading 导入并新增 /new 命令（清屏重启会话）；非 TUI 启动模式下同样会清屏以保持一致体验。资料来源：v0.1.5 release notes

2. 主题系统 (Theme System)

v0.2.0 引入完整的主题感知 TUI，内置 10 套配色：blue、pink、green、yellow、red、white、ocean、twilight、pastel、cobalt。所有 UI chrome（边框、面板、Markdown、旋转器、工具栏）都遵循当前主题。资料来源：v0.2.0 release notes

主题相关的关键文件：

• 主题定义与解析：src/eling/themes.py 集中维护配色表与样式映射。资料来源：src/eling/themes.py:1-120
• 配置键：所选主题名写入 config.json 的 theme 字段。资料来源：config.example.json:10-30
• 交互选择：eling setup → [2] Theme 菜单列出全部主题，选择后立即生效，无需重启。资料来源：src/eling/setup.py:60-130

3. 配置体系

src/eling/config.py 负责配置的加载、合并默认值与持久化；config.example.json 给出所有可用键的样例。常用配置键如下表：

资料来源：src/eling/config.py:1-140；config.example.json:1-80

v0.2.3 新增的 verbose_tool_output 是调试利器；auto_pytest 与 auto_fix_lint 则把"测试—修复"循环内置到每轮工具调用之后。资料来源：v0.2.3 release notes

4. 典型交互流程

eling setup 是面向普通用户的主要入口；进阶用户可直接编辑 config.json。典型序列如下：

1. 用户运行 eling setup，进入交互菜单；[2] Theme 用于选择主题，其余条目覆盖模型、记忆、MCP 等。资料来源：src/eling/setup.py:40-130
2. 选择主题后，写入 config.json.theme；eling setup 立即返回。
3. 用户运行 eling，src/eling/__main__.py 调用配置加载器读取 theme 等键，构造 Rich Console 时注入对应样式表。
4. TUI 启动后，所有组件（Banner、Spinner、Plan Panel、Markdown、Reasoning Panel、Toolbar）按当前主题着色；用户可通过 /new 清屏重启会话。资料来源：tui.py:1-60

对于"先观察后定制"的工作流：先用默认 blue 启动一次以确认功能正常，再切到深色主题（如 twilight、cobalt）进行长时间会话；调试工具链问题时临时打开 verbose_tool_output=true。资料来源：v0.2.0 release notes；v0.2.3 release notes

Pitfall Log / 踩坑日志

项目：PatrickNoFilter/eling-agent

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。

1. 身份坑 · 仓库名和安装名不一致

• 严重度：medium
• 证据强度：runtime_trace
• 发现：仓库名 eling-agent 与安装入口 eling 不完全一致。
• 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
• 复现命令：pip install eling
• 证据：identity.distribution | https://github.com/PatrickNoFilter/eling-agent | repo=eling-agent; install=eling

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/PatrickNoFilter/eling-agent | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/PatrickNoFilter/eling-agent | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/PatrickNoFilter/eling-agent | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/PatrickNoFilter/eling-agent | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/PatrickNoFilter/eling-agent | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/PatrickNoFilter/eling-agent | release_recency=unknown