RunLens
一个可验证、可观测、可扩展的本地 Agent Runtime，让 AI 任务从模型回答走向受控执行、结果验收和过程追踪。
RunLens 是我独立设计和实现的本地 Agent Runtime。它解决的核心问题是：当大模型需要读取真实文件、调用工具、生成多个产物时，怎样让任务执行过程可控制、失败可恢复、结果可验证，并且能够回看每一步发生了什么。
项目使用 FastAPI 和 React 构建，支持 DeepSeek、OpenAI 等真实模型 Provider，包含完整的 Agent Loop、插件系统、工具权限、运行状态、失败恢复、产物校验和可观测能力。
一句话概括：RunLens 把“调用一次大模型”升级为“一次可以执行、限制、验收和复盘的 Agent Run”。
项目概览
| 项目 | 内容 |
|---|---|
| 项目定位 | 可验证、可观测、插件化的本地 Agent Runtime |
| 我的职责 | 架构设计、后端 Runtime、业务插件、前端运行视图、测试和部署流程 |
| 技术栈 | FastAPI、React、Python、TypeScript、LLM Tool Calling、pytest、Docker |
| 核心能力 | Agent Loop、Skill、Plan、工具权限、失败恢复、产物验证、Events / Trace / Metrics |
| 示例业务 | 用户反馈分析、文件摘要 |
| 项目地址 | GitHub：RunLens |
为什么做这个项目
项目最早来自一个用户反馈分析需求：读取 CSV，将真实反馈整理成分析结果、产品待办和洞察报告。
如果只让模型返回一段文字，很难确认它是否真的读取了文件、引用的反馈是否存在、多个产物是否完整，以及任务失败在模型、工具还是权限环节。
因此我把重点从 Prompt 调整到了完整运行链路：
接收任务
→ 选择业务插件与 Skill
→ 生成 Plan 和工具白名单
→ 模型循环调用工具
→ Runtime 校验参数与权限
→ 记录状态、事件和失败原因
→ 验证最终产物
→ 输出可检查的结果我完成的主要工作
1. 抽象通用 Agent Runtime
我将模型循环、工具执行、权限、状态机、恢复、Hook 和产物校验从反馈分析业务中拆出，形成通用 Runtime。业务插件只负责声明输入、Prompt、Skill、Plan、工具和交付产物。
当前项目内置两个插件：
feedbacklens：读取用户反馈 CSV，生成分析、产品待办和洞察报告。file_summary：读取本地文本，生成结构分析和摘要。
两个业务使用同一套 Runtime，同时保持工具、权限和产物互相隔离，验证了架构具备扩展新业务的能力。
2. 实现完整 Agent Loop
Runtime 负责组装 Prompt、调用模型、接收 ToolCall、执行工具、回写 Observation，并持续推进任务。
我增加了最大迭代、工具调用预算、重复调用检测、Provider 重试和失败恢复机制。模型返回最终回答后，系统还会进入验证阶段，只有交付条件全部通过，Run 才会标记为完成。
3. 建立工具执行与权限边界
模型只能提出动作，真实操作由 Runtime 执行。每次 ToolCall 都需要经过：
工具查询 → 参数 Schema 校验 → 权限检查 → Hook → Handler → 返回值校验文件读取限制在允许目录，产物只能写入当前 Run 工作区。参数错误会形成结构化结果交回模型，路径越界和未授权工具则会在执行前被拦截。
4. 让生成结果可以验收
项目使用产物契约声明必需文件、JSON 结构、Markdown 章节和证据字段。
在反馈分析插件中，系统会根据源 CSV 生成 Evidence Index。最终报告引用的反馈 ID 和原文必须能够回溯到真实输入，避免模型生成格式正确但证据不存在的内容。
5. 构建运行可观测能力
每次 Run 都会记录状态变化、模型请求、工具调用、权限结果、Hook、失败恢复和产物验证事件，并进一步生成：
- Events：完整事件时间线。
- Trace：适合排查问题的执行链路。
- Metrics：模型调用、工具执行、失败和耗时统计。
- Manifest：允许前端展示的产物清单。
前端提供 Run Launcher、Run Viewer 和 Artifact Inspector，可以查看任务状态、Plan、Todo、事件、指标和最终产物。
项目亮点
- 真实执行链路：必需产物必须由工具创建，系统不会用模拟结果假装任务成功。
- 业务与 Runtime 解耦：新增业务通过插件声明能力，无需复制 Agent Loop 和工具执行器。
- 确定性质量门：模型结束不等于任务完成，最终结果还要经过结构和证据校验。
- 失败过程可解释：Provider、工具、权限、重复调用和验证失败都有明确状态与事件记录。
- 具备工程复现能力：提供自动化测试、统一验证脚本、Docker Compose 和可重复演示流程。
当前边界
RunLens 当前定位为同步、单进程、本地文件型 Runtime，主要用于展示 Agent 工程主链和验证架构设计。项目暂未实现异步任务队列、多租户、长期 Memory、第三方插件沙箱和多 Agent 协作，也不将当前版本描述为生产级高可用平台。
这些边界是有意保留的：当前阶段优先把能力声明、动作控制、失败恢复、结果验收和过程解释做成一条完整、可运行、可测试的闭环。