03：Agent 怎样工作：Skill、Prompt、Plan 和 Tool 如何配合

上一篇沿一次 Run 看到了完整时间线。用户提交目标后，Runtime 会加载 Skill、生成能力快照、组装 Prompt、创建 Plan，再把工具交给模型。

这些名字很容易混在一起。它们都影响 Agent 的行动，却分别解决不同问题。

这篇把范围放在模型开始行动前的准备阶段：一句用户目标怎样被整理成模型能够理解、Runtime 能够执行的工作台。

Skill 提供任务方法，Prompt 提供本轮信息，Plan 提供推进顺序，Tool 提供真实动作。

用户目标还只是一个方向

用户提交的目标可能是：

找出反馈中最影响用户体验的问题，并整理一份有证据的优先级待办。

这句话表达了业务方向，完整执行细节还需要 Runtime 继续补齐。

模型还需要知道：

• 数据从哪里读取。
• 当前能使用哪些工具。
• 文件可以写到哪里。
• 任务分成哪些步骤。
• 产物路径和格式是什么。
• 什么样的结果才能通过验证。

把所有信息堆进一段 Prompt，短期可以运行，长期维护会变得困难。工具、权限和产物变化以后，Prompt 也容易与实际能力产生偏差。

RunLens 先解析本次 Run 的能力，再由能力快照分别驱动 Prompt、Plan、工具和权限。

Skill 给出任务方法和能力边界

Feedback Analysis 的默认 Skill 位于：

app/plugins/feedbacklens/skills/feedback_analysis/
├─ skill.json
└─ SKILL.md

skill.json 负责结构化声明：

• Skill 名称和版本。
• 兼容插件。
• 所需工具。
• 所需输入。
• 所需产物。
• 读写权限。
• 可选资源。

SKILL.md 负责自然语言任务方法：

• 先读取源反馈。
• 洞察和 Backlog 引用真实 feedback_id。
• 通过工具创建规定产物。
• 所有必需文件完成后再结束任务。

这两部分结合起来，既方便 Runtime 校验，也方便模型理解任务。

Skill 怎样被选择

RunLens 的 Skill 匹配有三层优先级：

1. 用户显式指定 Skill。
2. Plugin 声明默认 Skill。
3. 根据 goal 中的 trigger 匹配。

显式选择适合需要精确控制的 API 调用，默认 Skill 适合稳定业务入口，trigger 匹配则适合一个插件支持多类任务时使用。

Skill 怎样收窄能力

Feedback Analysis Plugin 定义了六个工具。Skill 的 required_tools 再次声明当前任务所需的集合。

权限也会进一步收窄：

read:  data/、当前 Run
write: 当前 Run 的 artifacts/

Runtime 会验证这些声明位于全局允许边界内。Skill 负责选择和收窄，Runtime 负责最终裁决。

能力快照把分散声明汇合起来

Plugin 和 Skill 中都有工具、权限和产物信息。RunLens 使用 ResolvedRunCapabilities 把它们汇合成单次 Run 的能力快照。

快照包含：

内容	来源
Plugin 名称和版本	BusinessPlugin
Skill 名称和版本	Skill Manifest
Allowed Tools	Plugin Tools 与 Skill Required Tools 的交集
Read/Write Roots	默认策略经过 Skill 收窄后的结果
Artifacts	Plugin 的 ArtifactContract

这份快照同时用于：

• System Prompt 中的 Available Tools。
• Provider 收到的 Function Tool Specs。
• PermissionPolicy 的工具白名单。
• resolved_config.json 运行记录。

同一事实来源可以减少配置漂移。

例如 Skill 移除了某个工具后：

• 模型看不到该工具。
• ToolExecutor 的 PermissionPolicy 同样使用更新后的工具白名单。
• resolved config 会记录实际工具集合。

Prompt 把本轮工作台交给模型

RunLens 的 System Prompt 由多个部分组装。

# Local Agent Runtime
Business plugin
Current goal

## Business Prompt Fragments
## Run Input
## Available Tools
## Permission Boundaries
## Required Outputs
## Skills

Business Prompt Fragments

Feedback Analysis Plugin 提供六类业务片段：

• Agent 角色。
• 报告受众。
• Evidence 要求。
• sentiment 和 severity 分类词表。
• 三个必需产物。
• 工具使用规则。

片段带有顺序，Prompt Assembler 会稳定排序后拼接。

Run Input

本次请求的 product_name 和 csv_path 以 JSON 形式放进 Prompt。模型可以看到当前任务具体处理哪个产品和文件。

Available Tools

这里来自 ResolvedRunCapabilities。每个工具包含名称和说明，Provider 还会收到对应输入 Schema。

Permission Boundaries

Prompt 会告诉模型可读写目录。它帮助模型主动选择合理路径，最终路径裁决由 PermissionGuard 完成。

Required Outputs

ArtifactContract 中的必需产物会进入 Prompt，让模型知道交付目标。

Skill Instructions

Skill Markdown 和资源文件放在最后，提供具体执行方法。

组装完成的 Prompt 会写入：

runtime/system_prompt.md

这份快照让后续排查可以准确看到模型当时收到的系统信息。

Plan 把目标拆成可检查步骤

Feedback Analysis Plugin 声明四个 PlanStepTemplate。

Step	Objective	Success Criteria
读取反馈	得到规范化 rows	tool_succeeded:read_feedback_csv
创建分析	写结构化分析文件	artifact_exists:artifacts/feedback_analysis.json
创建 Backlog	写产品待办文件	artifact_exists:artifacts/product_backlog.json
创建报告	写 Markdown 报告	artifact_exists:artifacts/insight_report.md

Plan 会写入 agent_plan.json，TodoList 再把每一步投影为前端和 API 可查看的 Todo。

Plan 参与工具执行

PlanProgress 同时注册为 PreToolUse 和 PostToolUse Hook。

工具调用前：

• 找到第一个未完成步骤。
• 检查当前工具是否在该步骤白名单中。
• 把步骤标记为 in_progress。

工具调用后：

• 成功时记录工具名称。
• 根据成功条件判断步骤是否完成。
• 失败时把当前步骤标记为 failed。

因此 Plan 既是展示状态，也是 Runtime 的执行约束。

Tool 让模型接触真实环境

模型本身只能输出内容。Tool 把它的判断转成真实动作。

Feedback Analysis 提供六个工具：

工具	作用
read_feedback_csv	读取并规范化 CSV，建立 Evidence Index
summarize_analysis_counts	统计 sentiment、category、severity 和 pain points
extract_feedback_evidence	按 ID 提取原始反馈
write_json_file	写入 JSON 产物
write_markdown_file	写入 Markdown 产物
list_run_documents	查看当前 Run 已有文件

每个 ToolDefinition 包含：

• 给模型看的名称和描述。
• Python Handler。
• Input Schema。
• Output Schema。
• Permission Requirements。

模型选择工具以后，Runtime 会在下一篇介绍的执行管线中处理它。

四个部分怎样在一轮调用中汇合

以第一次模型调用为例。

Skill 提供方法

模型知道第一步要读取源 CSV，再基于真实 feedback_id 形成结论。

Prompt 提供现场

模型看到当前 goal、sample_feedback.csv、工具清单、权限和必需产物。

Plan 提供当前步骤

Step 1 的允许工具只有 read_feedback_csv。

Tool 提供动作

模型生成：

{
  "name": "read_feedback_csv",
  "arguments": {}
}

ToolExecutor 执行完成后，rows 和 row_count 作为 observation 回到模型。Plan Step 1 变为 completed，下一轮进入结构化分析步骤。

这就是 RunLens 中 Agent 行动形成的过程：任务方法、当前信息、步骤状态和真实动作在同一轮汇合。

Prompt 规则和 Runtime 规则怎样分工

同一个要求有时会出现在多个地方。

例如“每条洞察引用 feedback_id”：

• Skill 和 Prompt 告诉模型怎样生成结果。
• Evidence Index 保存真实 ID 和原文。
• Stop Hook 检查引用是否存在。

再例如“只写当前 artifacts 目录”：

• Prompt 展示 Permission Boundaries。
• Tool PermissionRequirement 解析目标路径。
• PermissionGuard 执行最终检查。

这种分层让模型更容易主动遵守，也让系统拥有稳定兜底。

小结

Skill、Prompt、Plan 和 Tool 共同把用户目标变成可执行任务。

Skill 提供任务方法和能力边界，能力快照统一工具、权限和产物，Prompt 组装本轮工作台，Plan 维护步骤和成功条件，Tool 负责真实环境交互。

下一篇继续沿 ToolCall 往下走：模型提出动作以后，Runtime 怎样依次完成 Schema、Permission、Hook、Handler 和 Observation。