# https://github.com/PatrickNoFilter/eling-agent 项目说明书

生成时间：2026-07-21 16:05:55 UTC

## 目录

- [项目概览与快速开始](#page-1)
- [记忆与技能系统](#page-2)
- [MCP 工具与插件扩展](#page-3)
- [终端界面、主题与配置](#page-4)

<a id='page-1'></a>

## 项目概览与快速开始

### 相关页面

相关主题：[终端界面、主题与配置](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/PatrickNoFilter/eling-agent/blob/main/README.md)
- [agent.py](https://github.com/PatrickNoFilter/eling-agent/blob/main/agent.py)
- [src/eling_agent/cli.py](https://github.com/PatrickNoFilter/eling-agent/blob/main/src/eling_agent/cli.py)
- [config.example.json](https://github.com/PatrickNoFilter/eling-agent/blob/main/config.example.json)
- [docs/index.md](https://github.com/PatrickNoFilter/eling-agent/blob/main/docs/index.md)
- [docs/configuration.md](https://github.com/PatrickNoFilter/eling-agent/blob/main/docs/configuration.md)
- [docs/architecture.md](https://github.com/PatrickNoFilter/eling-agent/blob/main/docs/architecture.md)
- [pyproject.toml](https://github.com/PatrickNoFilter/eling-agent/blob/main/pyproject.toml)
</details>

# 项目概览与快速开始

## 项目定位与目标

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

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

## 核心能力概览

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

| 能力 | 说明 | 关键版本/特性 |
|------|------|---------------|
| 本地记忆 | BM25 + 余弦相似度混合检索，支持去重与上下文效率评分 | v0.1.0 起，v0.2.0 加入 SHA-256 去重 |
| 技能库 | 自动从历史交互中提炼可复用模式，含质量门禁与自动遗忘 | v0.1.0 起，v0.2.2 强化 |
| MCP 工具 | 可接入任意 MCP 服务器（as_brain、blackbox、continuum、markdownify 等） | v0.1.2 起，4 个官方服务器 |
| 富 TUI | Banner、思考旋转器、计划面板、Markdown 渲染、10 套主题 | v0.1.0 起，v0.2.0 加入主题系统 |
| 插件系统 | 通过装饰器与清单机制扩展能力 | v0.1.0 起，v0.2.3 强化 `@tool` 装饰器 |

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

## 安装与首次启动

### 环境要求

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

### 基础安装步骤

1. 克隆仓库并进入目录：
   ```
   git clone https://github.com/PatrickNoFilter/eling-agent.git
   cd eling-agent
   ```
2. 安装依赖（以 pip 为例）：
   ```
   pip install -e .
   ```
3. 准备配置文件：复制 `config.example.json` 为本地 `config.json`，填入模型 API Key、工作区路径等字段。 资料来源：[config.example.json:1-40]()
4. 首次启动并进入引导式配置：
   ```
   eling setup
   ```
   在 `eling setup` 中可选择主题（10 种配色：blue、pink、green、yellow、red、white、ocean、twilight、pastel、cobalt），这一入口在 v0.2.0 中正式加入。 资料来源：[docs/configuration.md:1-40]()
5. 启动 TUI 会话：
   ```
   eling
   ```
   启动后会显示带 ⏱ 计时的 Banner、🤖 模型名，以及模型推理的暗色面板。

## 常用命令与配置要点

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]()

---

<a id='page-2'></a>

## 记忆与技能系统

### 相关页面

相关主题：[MCP 工具与插件扩展](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [memory.py](https://github.com/PatrickNoFilter/eling-agent/blob/main/memory.py)
- [skills.py](https://github.com/PatrickNoFilter/eling-agent/blob/main/skills.py)
- [textsim.py](https://github.com/PatrickNoFilter/eling-agent/blob/main/textsim.py)
- [src/eling/layers/builtin.py](https://github.com/PatrickNoFilter/eling-agent/blob/main/src/eling/layers/builtin.py)
- [src/eling/blackbox/core.py](https://github.com/PatrickNoFilter/eling-agent/blob/main/src/eling/blackbox/core.py)
- [src/eling/blackbox/score.py](https://github.com/PatrickNoFilter/eling-agent/blob/main/src/eling/blackbox/score.py)
</details>

# 记忆与技能系统

## 概述

`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]()。

| 层级 | 名称 | 用途 | 后端 |
|------|------|------|------|
| 0 | Builtin | 基础键值与会话状态 | 内存 / 字典 |
| 1 | Blackbox | 飞行记录器 (flight recorder) | 文件日志 |
| 2 | Facts/HRR | 事实三元组与 Holographic Reduced Representation | 向量 |
| 3 | Code (AST) | 代码抽象语法树节点 | SQLite |
| 4 | KB (FTS5) | 全文检索知识库 | SQLite FTS5 |
| 5 | Notion | Notion 远程文档 | Notion API |
| 6 | Continuum | 时序连续上下文 | 流式文件 |
| 7 | Markdownify | 把任意内容转为 Markdown 后入库 | 解析器 |

### 本地检索管线

本地优先的记忆查询走 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]()。

```mermaid
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]()。

---

<a id='page-3'></a>

## MCP 工具与插件扩展

### 相关页面

相关主题：[记忆与技能系统](#page-2), [终端界面、主题与配置](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/eling/mcp/client.py](https://github.com/PatrickNoFilter/eling-agent/blob/main/src/eling/mcp/client.py)
- [src/eling/plugins/registry.py](https://github.com/PatrickNoFilter/eling-agent/blob/main/src/eling/plugins/registry.py)
- [src/eling/plugins/decorator.py](https://github.com/PatrickNoFilter/eling-agent/blob/main/src/eling/plugins/decorator.py)
- [src/eling/as_brain/mcp_server.py](https://github.com/PatrickNoFilter/eling-agent/blob/main/src/eling/as_brain/mcp_server.py)
- [src/eling/blackbox/mcp_server.py](https://github.com/PatrickNoFilter/eling-agent/blob/main/src/eling/blackbox/mcp_server.py)
- [src/eling/continuum/mcp_server.py](https://github.com/PatrickNoFilter/eling-agent/blob/main/src/eling/continuum/mcp_server.py)
- [src/eling/markdownify/mcp_server.py](https://github.com/PatrickNoFilter/eling-agent/blob/main/src/eling/markdownify/mcp_server.py)
- [docs/mcp.md](https://github.com/PatrickNoFilter/eling-agent/blob/main/docs/mcp.md)
</details>

# MCP 工具与插件扩展

## 概述

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

`资料来源：[src/eling/mcp/client.py:1-40]()`

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

## 整体架构

```mermaid
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 起整合到仓库内）：

| 服务器 | 主要能力 | 入口模块 |
| --- | --- | --- |
| `as_brain` | 8 层记忆检索（Builtin / Blackbox / Facts / Code / KB / Notion / Continuum / Markdownify） | `src/eling/as_brain/mcp_server.py` |
| `blackbox` | 飞行记录与 11 项上下文效率评分 | `src/eling/blackbox/mcp_server.py` |
| `continuum` | 跨会话持续记忆与回溯 | `src/eling/continuum/mcp_server.py` |
| `markdownify` | 把任意文档转写为 Markdown | `src/eling/markdownify/mcp_server.py` |

每个 `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 + 重启"压缩为"写一个函数"：

```python
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`：

```yaml
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]()`

---

<a id='page-4'></a>

## 终端界面、主题与配置

### 相关页面

相关主题：[项目概览与快速开始](#page-1), [MCP 工具与插件扩展](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [tui.py](https://github.com/PatrickNoFilter/eling-agent/blob/main/tui.py)
- [src/eling/cli.py](https://github.com/PatrickNoFilter/eling-agent/blob/main/src/eling/cli.py)
- [src/eling/config.py](https://github.com/PatrickNoFilter/eling-agent/blob/main/src/eling/config.py)
- [src/eling/setup.py](https://github.com/PatrickNoFilter/eling-agent/blob/main/src/eling/setup.py)
- [config.example.json](https://github.com/PatrickNoFilter/eling-agent/blob/main/config.example.json)
- [src/eling/themes.py](https://github.com/PatrickNoFilter/eling-agent/blob/main/src/eling/themes.py)
- [src/eling/__main__.py](https://github.com/PatrickNoFilter/eling-agent/blob/main/src/eling/__main__.py)
</details>

# 终端界面、主题与配置

## 概述

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

## 1. 终端用户界面 (TUI)

TUI 由 [tui.py](tui.py) 实现，关键组件包括：

- **横幅 (Banner)**：启动时展示，含 agent 名称与当前模型（带 🤖 图标），自 v0.1.1 起引入。资料来源：[v0.1.1 release notes](https://github.com/PatrickNoFilter/eling-agent/releases/tag/v0.1.1)
- **会话计时器**：⏱ 计数器在每个回合（横幅、用户输入、助手面板）刷新；v0.1.5 修复了启动横幅上 0 秒的显示问题。资料来源：[v0.1.5 release notes](https://github.com/PatrickNoFilter/eling-agent/releases/tag/v0.1.5)
- **思考旋转器 (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](https://github.com/PatrickNoFilter/eling-agent/releases/tag/v0.1.5)

## 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](https://github.com/PatrickNoFilter/eling-agent/releases/tag/v0.2.0)

主题相关的关键文件：

- **主题定义与解析**：[src/eling/themes.py](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](src/eling/config.py) 负责配置的加载、合并默认值与持久化；[config.example.json](config.example.json) 给出所有可用键的样例。常用配置键如下表：

| 配置键 | 用途 | 引入版本 |
|---|---|---|
| `theme` | TUI 主题名称（如 `blue`、`twilight`） | v0.2.0 |
| `model` | 默认模型标识 | v0.1.0 |
| `verbose_tool_output` | 在 TUI 中显示工具完整参数与结果 | v0.2.3 |
| `auto_pytest` | 每轮工具调用后自动对受影响的测试文件运行 pytest | v0.2.3 |
| `auto_fix_lint` | 自动运行 Ruff --fix，剩余问题反馈给模型 | v0.2.3 |
| `memory.*` | 记忆层开关与去重、剪枝参数 | v0.2.0 起增强 |

资料来源：[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](https://github.com/PatrickNoFilter/eling-agent/releases/tag/v0.2.3)

## 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](https://github.com/PatrickNoFilter/eling-agent/releases/tag/v0.2.0)；[v0.2.3 release notes](https://github.com/PatrickNoFilter/eling-agent/releases/tag/v0.2.3)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：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

<!-- canonical_name: PatrickNoFilter/eling-agent; human_manual_source: deepwiki_human_wiki -->