09：工程复盘：RunLens 做到了什么，还准备继续解决什么

前面九篇从项目立意一路走到插件扩展，RunLens 的主要运行机制已经完整展开。

这篇回到整个项目，做一次工程收束：当前版本已经闭合了哪些能力，测试怎样证明这些链路可以运行，项目在哪些地方保持了明确范围，后续又可以从哪里继续推进。

RunLens 当前的目标很清楚：在本地、同步、单 Agent 的范围内，跑通一条可执行、可限制、可恢复、可验证、可解释的任务链路。

一条完整闭环决定了项目价值，孤立模块需要回到运行链路中发挥作用。

从反馈分析任务到 Agent Runtime

RunLens 的起点是一条 Feedback Analysis 业务链。

它需要：

• 读取用户反馈 CSV。
• 形成结构化分析。
• 整理产品优先级。
• 生成面向产品负责人的报告。
• 保留原始 Evidence。

实现过程中，项目逐渐补上模型外面的工程能力：

业务输入契约
→ Skill 和能力解析
→ Prompt 和 Plan
→ AgentLoop
→ ToolExecutor
→ Permission 和 Workspace
→ Recovery 和 Termination
→ Artifact Validation
→ Events、Metrics 和 Manifest

第二个 File Summary Plugin 进一步验证了这套能力可以服务不同业务。

项目名称也从 FeedbackLens AI 调整为 RunLens，让名称覆盖整个 Runtime，而 FeedbackLens 继续保留为反馈分析插件。

当前版本已经闭合的运行链路

RunLens 目前已经把一次 Agent Run 的主要环节连在一起。

1. 业务通过契约进入系统

BusinessPlugin 声明输入、工具、Prompt、Plan、Skill、产物和 Hook。

API 选择插件后，Runtime 可以使用统一入口执行任务。

2. 每次 Run 生成能力快照

Plugin 和 Skill 解析出实际工具、权限和产物，再写入 resolved_config.json。

Prompt、LLM Tool Specs 和 PermissionPolicy 使用同一能力来源。

3. 模型和工具形成闭环

AgentLoop 把 ToolResult 作为 observation 放回模型消息。成功结果提供新事实，失败结果提供修正线索。

4. 动作经过确定性管线

ToolCall 依次经过 Schema、Permission、Pre Hook、Handler、Output Schema 和 Post Hook。

5. 失败拥有恢复预算

Provider 临时错误进入重试，工具参数错误进入模型自纠正。重复调用、重复失败和超时负责结束低收益循环。

6. 最终结果接受质量检查

Plan Success Criteria 和 Stop Hooks 检查文件、JSON、Markdown 和 Evidence。

7. 运行过程留下统一证据

Events 记录生命周期，Metrics 从事件聚合，Manifest 控制公开文档。

这些环节共同构成 RunLens 当前的 Agent Runtime 闭环。

177 个测试在验证什么

在本次系列写作所基于的版本中，后端测试结果为：

177 passed

测试数量只是一个快照，覆盖层次更能说明项目质量。

API 和路径安全

测试覆盖：

• Health Check。
• Plugin Metadata。
• Run 创建和检查。
• Documents API。
• CORS。
• Path Traversal。
• Windows 绝对路径。
• 私有 Runtime 文件访问。
• Manifest Allowlist。

Runtime 正常与失败链路

测试覆盖：

• Happy Path。
• 缺失必需产物。
• 最大 Iterations。
• 工具参数错误后恢复。
• 重复调用。
• 重复工具失败。
• Provider 初始化失败。

Tool 和 Permission

测试覆盖：

• Tool Registry 重复名称。
• Input/Output Schema。
• Nested Object、Enum 和 Range。
• Permission 发生在 Hook 和 Handler 前。
• .env 和其他 Run 拒绝。
• 写入大小限制。
• 日志脱敏和长文本截断。

Skill 和 Plan

测试覆盖：

• Skill 发现和加载。
• 显式选择和默认 Skill。
• Plugin 兼容性。
• 所需 Tool、Input 和 Output。
• Resource Path Escape。
• Skill Permission 收窄。
• Plan Step Allowed Tools。
• Todo 与 Plan 同步。

Recovery 和 Termination

测试覆盖：

• Provider 临时错误重试。
• 永久错误直接失败。
• 指数退避。
• Remaining Deadline。
• Max Tool Calls。
• Prompt Character Limit。
• Timeout Decision。

Artifact 和 Evidence

测试覆盖：

• 缺失文件。
• JSON Required Fields。
• Markdown Headings。
• 未知 feedback_id。
• 内部自洽的虚构 Evidence。
• Evidence Text 与源文本不匹配。
• Stop Failure 后 Plan 和 Todo 失败状态。

Observability

测试覆盖：

• Event Contract。
• Sequence 连续性。
• Event Store 重开。
• Observer Error Isolation。
• Event API Filter 和 Pagination。
• Metrics 聚合。
• Legacy Projection。
• Run State 和 Event 集成。

这些测试共同验证完整运行链路，同时也覆盖关键函数的返回结果。

架构约束为什么也要写进测试

随着项目演进，单靠目录结构很难持续保证依赖方向。

RunLens 增加了源码级架构测试：

• Agent Runtime 不导入具体业务插件。
• Tool Layer 不导入 LLM Provider。
• API 不直接调用 Tool Handler。
• Provider 不导入业务模型。
• Skill 模块不执行 Handler。
• 生产 Provider Factory 不注册 ScriptedLLM。
• 旧 appv1 和旧目录保持移除状态。

这类测试保护的是设计意图。

例如一次快速需求可能会诱使开发者在 API 中直接读取 CSV。功能测试可能仍然通过，架构测试会指出调用层级发生了变化。

当项目强调 Plugin/Runtime 分层时，这些约束值得和业务测试一起维护。

测试替身让 Agent 链路可以稳定验证

真实 LLM 输出存在波动，网络和 API Key 也会影响测试稳定性。

RunLens 在 tests/fakes/ 中提供 ScriptedLLM。

它可以：

• 按队列返回预设 LLMResponse。
• 生成确定 ToolCalls。
• 模拟参数错误。
• 省略某个产物。
• 返回 final answer。

测试仍然经过真实 Runtime、ToolExecutor、Permission、Plan、Hook 和 EventStore，只替换模型决策来源。

这样既能验证完整因果链，也能保持自动化测试确定性。

本地开发和验证流程

后端本地启动：

python -m pip install -r requirements.txt
Copy-Item .env.example .env
python -m uvicorn app.main:app --host 127.0.0.1 --port 8080

前端启动：

Set-Location frontend
npm ci
npm run dev

统一验证脚本：

.\scripts\verify.ps1

依赖已经安装时：

.\scripts\verify.ps1 -SkipInstall

脚本会依次运行：

1. Python Compile Check。
2. Pytest。
3. Frontend Tests。
4. TypeScript Check。
5. Frontend Build。

场景脚本还可以单独运行 Happy Path、Permission Denied、Artifact Missing 和 Provider Recovery。

Docker 部署怎样组织

后端 Dockerfile 使用 Python 3.12 Slim：

安装 requirements
→ 复制 app 和 data
→ Uvicorn 监听 8080

Docker Compose 启动两个服务：

Service	作用
backend	FastAPI 和 Agent Runtime
frontend	构建后的 React 页面

运行目录挂载：

./runs → /app/runs

数据目录使用只读挂载：

./data → /app/data:ro

这种设置符合当前权限模型：源数据由 Runtime 读取，业务产物写入独立 runs 目录。

Backend Health Check 通过后，Frontend 再启动服务。

当前版本主动保留的边界

RunLens 当前聚焦本地、同步、单 Agent 运行。

同步 HTTP Run

POST /api/runs 会等待任务结束。它让调用链和测试保持直接，长任务吞吐仍然受 HTTP 生命周期影响。

单进程执行

EventStore 使用进程内 Lock，Tool Handler 也在当前进程同步运行。这符合本地 Runtime 目标。

本地文件工作区

Run、Events、Metrics 和 Artifacts 都保存在文件系统。它提供了很强的可读性，也缺少数据库索引、事务和集中归档。

服务入口面向可信本地环境

Documents API 根据 Manifest 控制文件范围，服务入口仍面向可信本地环境。

任务执行保持同步模式

Runtime 能控制模型循环 timeout，已进入 Handler 的阻塞函数仍需要 Handler 自己结束。

每次 Run 保持独立上下文

一次 Run 只使用本次输入、Skill、Prompt 和工具观察。任务隔离清楚，跨 Run 经验仍由业务侧管理。

这些范围让当前版本能够专注 Agent Runtime 主链路。

哪些地方还值得继续增强

异步 Run

将创建和查看分离：

POST /runs → queued/running
GET /runs/{id} → current status

配合后台队列、取消和实时事件流，可以支持更长任务。

更严格的 Artifact Schema

将轻量 required fields 和 enum rules 升级为完整 JSON Schema 或 Pydantic Models。

更细的文档公开策略

Manifest 可以只公开用户产物和少量运行摘要，将 Prompt、Request 和 Evidence Index 留在内部接口。

生产级 Event Store

将 JSONL 抽象为可替换存储，支持数据库、对象存储、Retention 和查询索引。

Auth 和多租户

为 Run、Source Data 和 Artifacts 增加 Owner、Tenant 和权限过滤。

Plugin SDK

提供脚手架、版本兼容检查和测试套件，再结合沙箱支持更开放的插件生态。

Tool Executor 隔离

耗时 Handler 可以迁移到子进程或外部 Worker，获得更明确的 timeout 和取消能力。

Multi-Agent

在单 Agent 状态、工具、权限和观测稳定后，再增加 Planner、Worker 或 Reviewer 等子任务编排。

这些方向都可以复用当前契约和事件设计继续演进。

这个项目带来的工程认识

模型能力需要运行环境承接

Tool Calling 让模型可以表达动作，Runtime 决定这些动作怎样安全落地。

成功条件适合写成系统契约

Prompt 告诉模型目标，Plan 和 Stop Hook 负责检查完成条件。

失败也是运行证据

参数错误、权限拒绝、Provider 异常和缺失产物都会改变下一轮判断，也会进入 Event Timeline。

可观察性需要和主链路一起设计

Events 在 Run 创建时就开始记录，Metrics 和 Trace 才能覆盖完整过程。

扩展性来自边界清楚

Plugin 声明业务，Runtime 提供执行。第二个插件能够复用完整底座，说明这条边界已经产生实际价值。

系列收束

这个系列从“为什么做 RunLens”开始，依次拆解了架构、Run 链路、Skill、Prompt、Plan、Tool、Permission、Recovery、Artifact Validation、Observability 和 Plugin Extension。

把它们重新放在一起，RunLens 的主线是：

业务声明
→ 能力解析
→ 模型循环
→ 工具执行
→ 权限控制
→ 失败恢复
→ 结果验证
→ 事件记录
→ 文档交付

RunLens 想解决的是怎样把模型放进一条可执行、可限制、可恢复、可验证、可解释的业务运行链路。

当前版本完成了本地单 Agent Runtime 的主闭环。后续增强可以继续围绕异步执行、严格 Schema、事件存储、插件安全和多 Agent 展开。