RunLens

一个可观察、可验证、可扩展的本地 Agent Runtime。

RunLens 关注的不是“让模型调用几个工具”，而是如何把一次 Agent 任务变成一条可以检查、解释和验收的工程链路：目标如何转化为计划，模型可以使用哪些能力，工具调用是否越权，失败能否恢复，最终文件是否真实存在，以及报告中的结论能否回溯到原始证据。

项目提供 FastAPI 后端、React Runtime Inspector、本地文件工作区和两个示例插件，适合用于 Agent 工程学习、架构展示、运行机制实验和作品集演示。

项目解决什么问题

常见 Agent Demo 往往只展示“输入问题—模型调用工具—返回答案”。RunLens 将模型之外的关键工程问题纳入同一条运行链：

• 用 Plugin、Skill 和 Tool Schema 明确本次 Run 的能力边界。
• 用 Plan、Todo 和终止策略约束任务推进，而不是只依赖模型口头声明完成。
• 在工具执行前完成参数校验、路径权限检查和 Hook 检查。
• 用统一事件流记录模型、工具、权限、恢复、产物和状态变化。
• 用 Artifact Contract 验证必需文件、JSON 结构、Markdown 标题和证据引用。
• 将每次运行保存为独立工作区，支持前端检查、API 查询和事后复盘。

核心创新点

1. 能力先解析，再执行：Plugin 与 Skill 会被解析为不可变的运行能力快照，Prompt、工具白名单、权限和产物要求使用同一份事实来源。
2. 产物驱动的完成判定：模型说“完成”并不代表 Run 成功；只有必需产物通过契约和证据校验后，状态才会进入 completed。
3. 证据可回溯：FeedbackLens 会为 CSV 原始反馈建立证据索引，分析、待办和报告中的引用必须能够映射回输入数据。
4. 统一可观察时间线：LLM、Tool、Permission、Hook、Recovery 和 Artifact 事件进入有序事件流，可由 Runtime Inspector 还原运行过程。
5. 插件与 Runtime 解耦：业务插件声明输入、工具、计划、Skill 和产物，通用 Runtime 负责执行；仓库中的两个插件共享同一套引擎。

完整设计说明见架构与创新。

内置示例

插件	输入	输出	展示重点
feedbacklens	CSV 用户反馈	反馈分析、产品待办、洞察报告	结构化产物、跨文件证据引用、质量门禁
file_summary	Markdown 或文本文件	文档结构、摘要	最小插件、能力隔离、Runtime 复用

一次 Run 如何执行

创建 Run
  -> 解析 Plugin 与输入
  -> 激活 Skill
  -> 生成能力快照、Prompt、Plan 和 Todo
  -> 调用真实 LLM Provider
  -> 校验 Tool Schema、Permission 与 Hook
  -> 执行工具并记录 Observation
  -> 恢复可纠正错误
  -> 验证 Artifact 与 Evidence
  -> 写入状态、事件、指标和 Manifest
  -> 在 Runtime Inspector 中展示

快速启动

方式一：Docker Compose

Copy-Item .env.example .env
# 编辑 .env，至少配置一个 Provider API Key
docker compose up --build

• 前端：http://127.0.0.1:5173
• API：http://127.0.0.1:8080
• Swagger：http://127.0.0.1:8080/docs

方式二：本地启动

python -m pip install -r requirements.txt
Copy-Item .env.example .env

Set-Location frontend
npm ci
Set-Location ..

.\scripts\start-dev.ps1

生产运行只使用真实 Provider。支持 DeepSeek、OpenAI 和自动选择模式；没有配置 API Key 时服务可以启动，但创建真实 Run 会返回清晰的配置错误。

更完整的环境配置、请求示例和故障排查见快速启动与使用。

运行演示

启动服务后，在前端选择插件、填写输入并创建 Run。推荐按以下顺序展示：

1. 使用 feedbacklens 创建成功 Run。
2. 查看 Plan、Todo 和事件时间线。
3. 打开产物与 manifest.json。
4. 展示 CSV 证据如何进入分析、Backlog 和报告。
5. 运行权限拒绝、参数纠正或产物缺失场景，观察系统如何明确失败或恢复。

无需 API Key 的确定性演示场景：

.\scripts\run-demo.ps1
.\scripts\run-demo.ps1 -Scenario permission-denied

详细讲解顺序见演示指南。

项目结构

app/
├── agent_engine/        # Runtime、工具、权限、Skill、Hook、计划与可观察性
├── api/                 # Run、Plugin、事件、指标和文档 API
├── capabilities/        # LLM Provider 与通用工具能力
└── plugins/             # feedbacklens、file_summary 与插件注册
frontend/                # Run Launcher、Runtime Inspector、Artifact Viewer
runs/                    # 每次运行的独立工作区
data/                    # 示例输入数据
demo/                    # 可重复演示场景
scripts/                 # 启动、验证和演示脚本
tests/                   # 单元、集成、架构约束和场景测试
docs/                    # 面向读者的项目文档

验证

.\scripts\verify.ps1

依赖已安装时：

.\scripts\verify.ps1 -SkipInstall

验证包含 Python 编译、后端测试、前端测试、TypeScript 检查和生产构建。自动化测试使用 tests/fakes/ScriptedLLM，不会访问真实模型服务。

文档

• 项目概览：定位、使用场景、核心对象与目录说明。
• 架构与创新：执行链路、能力模型、证据校验和可观察性。
• 快速启动与使用：配置、启动、API、工作区和验证命令。
• 演示指南：成功链路、失败链路和展示话术。
• 边界与路线图：当前限制、适用范围和后续方向。

当前边界

RunLens 当前定位为本地、单进程、同步执行的 Agent Runtime，不提供生产级队列、调度、长期记忆、多 Agent 协作或租户鉴权。它强调运行机制的完整性和可解释性，不宣称已经具备生产级高可用。

更多说明见边界与路线图。