08：扩展新业务：同一套 Runtime 怎样运行不同插件

上一篇介绍了 RunLens 怎样记录一次 Run。无论业务插件处理 CSV 还是文本，Events、Metrics、Plan 和 Manifest 都使用同一套运行语义。

这种一致性来自项目最早的分层选择：业务通过 Plugin 声明，执行由 Runtime 统一完成。

Feedback Analysis 跑通以后，我增加了 File Summary 插件。它的规模很小，却验证了 Runtime 是否真的具有业务复用能力。

新业务接入 RunLens 时，重点是声明自己的能力和交付契约，已有执行链路继续复用。

第二个插件用来验证什么

如果 Runtime 只运行一类业务，很难判断通用能力是否已经独立。

Feedback Analysis 的特点很鲜明：

• 输入是结构化 CSV。
• 需要反馈 ID 和原文证据。
• 产物包含分析、Backlog 和报告。
• 最终验证带 Evidence Index。

File Summary 换成另一类任务：

• 输入是 Markdown 或普通文本。
• 工具读取全文并分析标题结构。
• 产物是文档分析 JSON 和摘要 Markdown。
• 最终验证关注文件和报告标题。

如果这两个插件能够使用同一 AgentLoop、ToolExecutor、Permission、Plan 和 Events，业务与 Runtime 的边界就具有实际意义。

Feedback Analysis 声明了哪些业务能力

app/plugins/feedbacklens/plugin.py 返回一个完整 BusinessPlugin。

它包含：

Input Schema

product_name
csv_path

Tools

read_feedback_csv
summarize_analysis_counts
extract_feedback_evidence
write_json_file
write_markdown_file
list_run_documents

Plan

读取反馈
→ 创建分析
→ 创建 Backlog
→ 创建报告

Artifacts

feedback_analysis.json
product_backlog.json
insight_report.md

Skill

feedback_analysis

Business Hook

严格 Evidence Validation，回查 feedback_id 和 evidence_text。

这些内容构成 Feedback Analysis 的业务身份。

File Summary 怎样复用同一套 Runtime

File Summary Plugin 位于：

app/plugins/file_summary/
├─ plugin.py
└─ skills/document_summary/
   ├─ skill.json
   └─ SKILL.md

它声明四个工具：

read_text_document

读取 data/ 下 UTF-8 文本，返回内容和字符数。

analyze_document_structure

统计行数，并提取 Markdown 标题。

write_json_artifact

写入 document_analysis.json。

write_markdown_artifact

写入 summary.md。

对应 Plan 是：

Read document
→ Analyze structure
→ Write summary

ArtifactContract 要求：

artifacts/document_analysis.json
artifacts/summary.md

摘要还要包含：

# Document Summary
## Key Points

Plugin 定义完成后，API、Runtime 和前端 Run Inspector 都可以直接处理它。

两个插件共享什么

Runtime 能力	Feedback Analysis	File Summary
RunWorkspace	共享	共享
Skill Loader	共享	共享
Prompt Assembler	共享	共享
AgentLoop	共享	共享
Provider Factory	共享	共享
ToolExecutor	共享	共享
PermissionGuard	共享	共享
PlanProgress	共享	共享
Stop Hooks	共享	共享
Events 和 Metrics	共享	共享
Manifest 和 Documents API	共享	共享

共享 Runtime 带来的效果很直接：

• 两个插件的 Run Status 结构一致。
• 前端使用同一个时间线组件。
• Tool 和 Permission 事件使用同一 Schema。
• Plan 和 Todo API 保持一致。
• 失败恢复和终止规则保持一致。
• Manifest 可以用统一格式展示产物。

两个插件分别保留什么

共享执行链会保留清晰的业务差异。

每个 Plugin 独立拥有：

• Input Schema。
• Tool Handler。
• Prompt Fragments。
• Plan Template。
• Skill。
• Artifact Contracts。
• Hook Config。

Feedback Analysis 的 Evidence Index 属于业务逻辑。File Summary 的校验范围集中在文本结构和标题，因此使用更轻量的产物契约。

Runtime 提供校验框架，Plugin 选择需要启用的业务规则。

BusinessPlugin 是一组可执行契约

BusinessPlugin 可以理解成一次业务任务的总装配。

BusinessPlugin
├─ Input Contract
├─ Tool Contracts
├─ Prompt Fragments
├─ Plan Template
├─ Skill Roots
├─ Artifact Contracts
└─ Hook Config

这些契约分别进入 Runtime：

Plugin 声明	Runtime 使用位置
Input Schema	创建 Run 前校验业务输入
Tool Definitions	ToolRegistry 和 LLM Tool Specs
Prompt Fragments	System Prompt
Plan Template	AgentPlan 和 Todo
Skill Roots	Skill Discovery 和 Matching
Artifact Contracts	Stop Validation 和 Manifest
Hook Config	自定义业务校验

Plugin 自己不维护运行循环。它把契约交给 run_agent()，Runtime 按统一流程执行。

Skill 让插件支持更细的任务方法

一个 Plugin 可以拥有多个 Skill。

Skill 适合表达：

• 不同任务方法。
• 不同工具子集。
• 不同必需输入和产物。
• 更窄的权限。
• 专门的操作说明和资源。

当前 Feedback Analysis 和 File Summary 都只声明一个默认 Skill，结构已经支持后续扩展。

例如 Feedback Plugin 后续可以增加：

• feedback_triage：只做快速分类。
• backlog_generation：从已有分析生成 Backlog。
• executive_report：只生成面向管理层的报告。

每个 Skill 可以选择不同工具和产物，同时继续使用同一个 Plugin 和 Runtime。

新插件接入需要完成哪些步骤

1. 定义 Input Schema

明确用户必须提供哪些业务输入，以及字段类型和默认值。

2. 定义 ToolDefinition

为每个动作提供：

• 清晰名称和说明。
• 确定 Handler。
• Input/Output Schema。
• Permission Requirements。

3. 定义 Prompt Fragments

描述角色、任务规则、受众、业务词表和产物要求。

4. 定义 Plan Template

把任务拆成有顺序的步骤，并为每一步声明 allowed tools 和 success criteria。

5. 定义 ArtifactContract

声明产物路径、说明、受众、必需结构和 Evidence Fields。

6. 创建 Skill

提供 Manifest、Markdown 指令和可选资源。

7. 配置业务 Hook

选择文件、JSON、Markdown、Evidence 或自定义 Validator。

8. 显式注册插件

在 app/plugins/builtins.py 中添加 Plugin Factory。

9. 增加测试

覆盖：

• Plugin Metadata。
• Tool Schema 和权限。
• Happy Path。
• 缺失产物。
• Skill 兼容性。
• 插件隔离。

这九步共同保证契约完整。Runtime 已经具备执行能力，新插件负责把业务说清楚。

为什么当前只支持可信内置插件

RunLens 的 Plugin 中包含 Python Handler。允许任意外部目录注册插件，相当于允许执行任意 Python 代码。

安全的第三方插件体系还需要：

• 包来源验证。
• 依赖隔离。
• 进程或容器沙箱。
• 网络权限。
• 资源限制。
• 版本和兼容性管理。
• 审核和签名。

当前版本选择中心注册表显式启用插件，适合本地项目和可信代码仓库。

这种边界也让 Runtime 的安全语义更清楚：PermissionGuard 管理工具声明的文件行为，Plugin 来源由代码注册表管理。

插件架构的收益和代价

收益

1. 业务接入路径清楚。 输入、工具、Plan、Skill 和产物集中在插件中。
2. Runtime 行为一致。 不同业务共享状态、恢复、验证和事件。
3. 前端可以通用。 插件元数据驱动输入表单，Manifest 驱动产物展示。
4. 测试可以复用。 同一组 Runtime 场景可用于不同插件。
5. 能力边界可审计。 resolved config 记录本次实际工具和权限。

代价

1. Plugin Contract 需要持续维护。
2. Tool、Skill、Plan 和 Artifact 变化要保持一致。
3. 轻量任务也会经过完整 Runtime 初始化。
4. 第三方插件仍需要新的安全模型。

当前项目更看重边界清晰和运行一致性，因此这套取舍符合阶段目标。

小结

Feedback Analysis 和 File Summary 拥有不同输入、工具、Plan、Skill 和产物，同时共享 RunLens 的完整执行底座。

BusinessPlugin 把业务任务整理成一组可执行契约。Runtime 读取这些契约，完成能力解析、模型循环、工具执行、权限、恢复、验证和观测。

下一篇是系列收束。我会回到整个项目，复盘 RunLens 当前已经闭合的工程链路、177 个测试覆盖的内容、部署方式、明确边界和后续方向。