Skip to content

Latest commit

 

History

History
282 lines (207 loc) · 25.3 KB

agent.md

File metadata and controls

282 lines (207 loc) · 25.3 KB

Agent 智能体

Agent 位于 VSRenderer.exe 左侧导航栏的“Agent 智能体”页面:左侧管理对话,中间显示回复,底部输入区集中放置来源、模型、设置、工具和子任务入口。 播放器单文件版没有此页面。Agent 需要可访问的模型端点;本地工具沿用 Renderer 已有组件及其运行要求。

首次连接与 3FUI 导入

  1. 打开“Agent 智能体”,点击输入区上方工具行的“来源设置”,在独立窗口点击“导入 3FUI 配置…”。
  2. 选择当前使用的 3FUI 程序目录中的 Settings.json,不用复制或粘贴密钥。
  3. 导入会读取自定义端点、API Key、模型 ID 和推理级别;原来的 3FUI 文件不会被修改。
  4. 点击“应用”保存,或“确定”保存并关闭,检查输入区下方的来源与模型。
  5. 输入“先读取当前工作区,再列出可用滤镜”,点击发送箭头或按 Enter;工具参数与结果可展开查看。

导入对应字段为 AgentEndPoint、AgentApiKey、AgentModelId、Agent推理级别。 3FUI 的 SP 专属来源、附加请求头和附加请求 Body 当前不导入。

来源窗口左侧列出连接,右侧编辑名称、端点、密钥、默认模型、推理级别和 Token 预算;“添加来源”创建新连接。 “取消”放弃尚未应用的修改;此前已经应用的设置会保留。 端点可填 https://api.deepseek.com/v1 这类版本地址,或完整的 /chat/completions 地址;根域名自动使用 /v1/chat/completions。

多来源与模型

发送按钮左侧依次为来源、模型、思考强度;同一对话可以在两次请求之间切换来源和模型,上下文会保留。 三个选择入口使用带标题、说明和选中标记的浮层,支持鼠标与键盘选择;长名称省略显示,悬停可查看完整值。 模型列表合并端点返回的模型与本地记录,也可填写模型 ID。 切换来源或模型时重新探测能力;思考菜单优先采用 API 元数据,官方端点使用已核实规则,未知兼容端点只提供自动模式。 当前 DeepSeek 元数据提供低、高、最高,默认高;关闭思考使用独立参数。自动模式跟随端点默认,模型要求关闭思考才能调用工具时自动使用兼容设置。 仅支持 Responses 工具调用、未提供 Chat Completions 工具能力的模型会明确提示;本软件当前不转换为 Responses 协议。

上下文上限默认 131072 tokens,是可编辑的本地预算,不代表所选模型的官方容量,请按服务配置调整。 最大输出设为 0 / 端点默认 时不发送输出长度限制;正数作为 max_tokens 发送,实际支持范围以端点为准。

运行期间不能切换来源、模型或当前对话。点击“停止”后再调整。 切换来源后,后续请求会把当前对话上下文发送到新来源。

来源窗口支持导入本软件的来源 JSON,以及导出全部来源,导出文件省略 API Key。 导入相同端点和模型会更新对应来源;无密钥的导入记录会保留已保存的同来源密钥。 在其他机器导入分享文件后,需要自行填写密钥。

对话与软件操作

左侧可以新建、选择、删除对话;点击“新对话”立即显示一条空白会话,连续点击复用,删除后不自动补出记录;右键会话可重命名或选择已有分组、输入新分组,点击分组标题可折叠。分组由用户指定,与环境访问的工作目录无关。已有消息的对话在本轮结束后自动保存。 输入框中 Enter 发送,Ctrl+Enter 换行,也可以点击发送箭头;中文输入法选词确认不会误发送。 点击输入框右上角“预览”可在编辑原文的同时查看 Markdown。正文支持标题、列表、表格、引用、链接、代码块和行内代码;不执行原始 HTML。 你的消息显示在右侧圆角气泡,保留 Markdown 与文字选择;AI 最终回复位于正文区域。工具调用、中间进度和子智能体通知默认收进本轮“执行过程”,展开可看过程摘要,再按需查看参数与结果;执行失败会在概要中提示。 模型运行中可继续发送,补充内容进入待接收队列,在当前工具调用完整结束后接收;不会取消正在执行的请求或工具。 “停止”暂停待接收队列并保留内容,点击待接收入口或使用 /resume 继续;可将待发内容取回编辑或删除。导入的待发内容默认暂停。 停止按钮仅在执行时显示;输入区横向使用可用空间,缩窄窗口时仍保留来源、模型与思考选择。 左侧“导出”保存当前对话 JSON;“导入”恢复消息、工具结果与有效摘要检查点,并创建独立本地记录。 会话导入只接受 user、assistant 和已正确配对的 tool 消息,不接受外部系统提示词。

可以直接描述任务,例如:

  • “查询 resize 的参数,向当前时间组添加 1920×1080 缩放。”
  • “新建从第 60 秒开始的时间组,再添加降噪滤镜。”
  • “把当前项目保存到指定的新 .vsr.json 文件,并导出 VPY 预设。”
  • “读取当前处理路状态,生成脚本检查错误,然后请求渲染预览。”

内置工具支持滤镜增删、顺序、开关与参数,时间组和最多三条处理路,项目与 VPY 预设交换、脚本检查、渲染请求、编码入队与停止、源播放控制、图像比对导入、页面切换及本地目录查询。 工具索引从 0 开始;不熟悉的滤镜应先让 Agent 调用 list_filters 查询真实 ID、参数与范围。 项目和预设导出、编码输出需要新的绝对文件路径,现有目标会被拒绝。

视频画质初检

模型列表及当前模型按钮显示“支持图像 / 不支持图像 / 视觉未确认”;判断来自当前端点的模型元数据,读取失败时标注缓存。不同渠道的同名模型可以不同,例如 Harness 的 mimo-v2.6-flash-free 声明支持图像,而 amd/MiMo-V2.6-Flash 声明仅文字;不能仅凭 MiMo 名称或来源名称判断。切换后等待能力读取完成再发送。

兼容 DeepSeek Harness / Our Free Model 网关返回的 input: ["text", "image"] 模型能力声明;选择视觉模型后自动开放取帧工具。仅有模型名称或文字能力不会启用看图。本地网关需保持运行,API Key 仍通过 Windows DPAPI 保存;Our Free Model 报缺少 Bun 时需补齐其运行依赖。

选择明确声明支持图像输入和工具调用的模型,导入视频后可直接要求:“检查第 60 秒、第 300 秒和第 600 秒的原片,先汇报色带、噪点、色块、振铃、锯齿、模糊及压缩痕迹,说明位置、程度和置信度,先不要加滤镜。”

inspect_video_frame 从 VapourSynth 直接读取画面,支持 seconds 或从 0 开始的 frame(二选一),target 选择 source 原片或 processed 当前完整 VS 链,默认原片。处理后帧号和时间属于处理链输出时间轴,补帧、裁切后可能不同于原片。工具在“软件内操作”模式可用,不改变当前预览、播放位置和滤镜。

发现细微缺陷后可要求:“读取第 1440 帧左上角 x=400、y=200、宽 512、高 512 的局部,复核色带。”局部坐标基于所选 VS 节点的原始尺寸。默认发送完整源帧的原始分辨率,与预览窗口的缩放、平移和可见区域无关;只有显式 crop 才裁剪。图像采用无损 16-bit PNG,每张编码后上限64 MiB、每组最多4张;超限明确报错,不再静默缩小。

报告只覆盖实际抽样。单帧不能证明时间性闪烁、鬼影或整片没有瑕疵;这些问题需相邻帧或多时段复核。取帧成功只说明图像已发送,识别能力取决于所选视觉模型。RGB转换及模型服务端的内部预处理也可能影响观察,缺少YUV矩阵时按HD BT.709/SD BT.601转换;HDR和宽色域帧要求先显式转换为SDR,工具会拒绝不适合直接观察的输入。

工具结果不保存临时截图到用户目录。所取画面会随本轮消息交给选择的模型端点,并保存在会话历史中;停止会取消本轮图片提交。

软件内操作与环境完全访问

运行中可以新建、切换或导入会话,原会话继续后台执行,侧栏标记运行状态;流式内容、待接收消息、停止操作及子任务队列各归原会话。导出是当时的记录快照,未完成工具结果明确标为未知。各会话仍共享当前 Renderer 视频与滤镜工作区,关闭 Renderer 会停止全部会话并保存已有结果。

输入区左下角显示当前访问模式,点击选择“软件内操作”或“环境完全访问”;完整访问以橙色标识。模式会保存,执行期间先停止当前轮次再切换。

  • 软件内操作:提供 Renderer 的操作工具及指令/会话功能;关闭模型对通用文件、命令和外部 MCP 环境工具的调用。你主动通过 @file 附加的文字仍可用作任务资料。
  • 环境完全访问:以当前 Windows 账户权限读取、搜索和修改本机路径,执行本机命令并调用已连接的 MCP 工具。路径可在工作目录之外,工具结果会交给当前选择的模型端点。

这是一组模型工具权限选择;Renderer 自身的媒体导入、VPY 和编码继续按软件功能运行。输入区上方“目录”可选择默认工作目录,绝对路径直接使用,相对路径及命令默认以该目录为基准;每个子智能体保留自己的目录。

本地基础操作对应 DSH 的文件、搜索、Shell、工作目录与图像工具,使用原生 Qt 实现:

能力 工具
环境与目录 get_environment、set_working_directory
文本与目录读取 read_file、list_directory、file_info
查找文件和内容 glob、grep / search_files
创建、精确编辑和补丁 write_file、edit_file、apply_patch
文件整理 copy_file、move_file、delete_file、create_directory
命令及长进程 exec_command、write_stdin、list_processes、terminate_process
视觉图像附件 read_image / view_image,仅对已确认支持图像输入的模型开放

可以直接说“读取指定目录的文件,搜索配置项,修改后运行校验”,无需先将全部正文复制进聊天。文件读取有分页,搜索与输出有预算及明确截断标记;二进制文件使用相应工具或命令处理。grep 使用 Qt 正则表达式,也支持字面量搜索。 文本写入支持新建与明确覆盖,精确替换默认要求唯一匹配;apply_patch 支持 Codex 的 Add / Update / Delete / Move 格式,整批验证、暂存后提交,失败会报告回滚或部分影响。delete_file 删除单个文件或链接;目录整理可使用命令工具。

命令默认使用 PowerShell,也可指定其他已安装 Shell,或以可执行文件和参数列表直接启动。支持环境变量、工作目录、退出码、标准输入输出、超时和后台进程;长任务返回 session_id 后可用 write_stdin 继续输入或查询,terminate_process 结束指定进程树。进程归各自会话所有,导入历史不会恢复旧进程。 命令优先使用用户配置和本机 PATH,再补充 Full 自带的 Node/npm/npx、Python 和 FFmpeg 入口;配套 Python 是媒体运行时,额外模块仍以所用 Python 环境为准。命令使用管道输入输出。停止会取消前台命令,显式后台任务可单独终止;降为软件模式或关闭程序会清理所属后台进程,新建/切换会话保留原会话后台任务。已完成的文件修改不会因停止而自动撤销。

图像工具真实解码并发送模型可接收的图像内容块,工具摘要只含路径、尺寸等元数据。附件保留完整图像的原始分辨率,无损PNG发送,原件不改;每张编码后上限64 MiB、每组最多4张,超限明确报错,不缩小或改用有损编码。模型未声明视觉能力时不开放此工具,当前来源能否看图与本地访问权限是两项能力。 图像在本地历史及导出中保留,会话导入上限272 MiB;摘要仅使用文字与图像元数据;图像上下文按每张4096 tokens作预算估算,实际用量以端点返回为准。

Token 用量与上下文整理

输入区下方显示估算上下文百分比与累计 Token,点击打开“上下文与 Token 用量”。 详情包括累计输入、输出、总量、缓存命中、推理用量、最近请求的输入输出,以及已整理次数。 累计用量来自端点返回的 usage;端点未提供的字段不能当作实际账单。缓存与推理是输入、输出的细分,累计总量不会再重复加一次。

当前上下文为估算值,包含系统提示词、消息与工具定义,与会话累计花费是不同指标。 主会话与队列子任务分别记账,子任务用量不会并入主会话。队列 Token 列及 read_agent_task 返回的 usage 可查看任务用量。

空闲时点击“整理上下文”可让模型生成历史摘要;估算请求超过所配置上下文上限的 85% 时,也会尝试自动整理。 整理需要足够的可压缩历史;单条超长输入或过大的系统提示词仍需自行缩短。 成功后,后续请求使用“摘要 + 保留的近期消息”,原始消息继续留在本地记录和会话导出中。 摘要失败或被取消时,保留原始记录与此前有效的摘要,不把失败结果当作已完成整理。

Skills 与独立全局 AGENTS.md

打开“功能设置”→“Skills / 全局 AGENTS”,可以导入单个 Markdown,或包含 SKILL.md 的完整文件夹。 文件夹导入保留 references/、scripts/、assets/ 等资源;需要相对路径资料的技能应使用文件夹导入。 勾选启用、取消勾选停用;删除时只删除本软件中的副本,原始导入文件保留。

每轮只载入启用技能的名称与说明,正文由 Agent 在任务需要时通过 read_skill 读取。 先读取 SKILL.md,再按相对路径读取包内 UTF-8 资料;停用技能、越界路径、链接和二进制不能经此接口读取。 导入包最多 1024 项、32 MiB,单个文本读取上限为 512 KiB;技能中的脚本不会因导入而自动执行。

“全局 AGENTS.md”编辑的是 本软件应用数据目录的 agent/AGENTS.md,不读写 Codex 的指令文件,也不修改项目中的同名文件。 点击“保存并应用全局指令”后用于后续请求和新建子智能体;“重新读取”加载本地修改。 技能提供操作指引,实际能力由软件工具和已连接的 MCP 工具决定。

工具管理与自定义组合

底部“工具”列出当前功能,取消勾选即可禁止调用,禁用状态会保存。 组合工具每一步也会检查对应内置工具是否启用,不能绕过禁用设置。 “导入工具组合…”读取 JSON 并添加组合;“导出工具组合…”导出全部自定义组合,内置工具无需随文件复制。

下面是完整示例,保存为 resize-tools.json 后导入。随后可以说“调用 custom_resize,宽度 1920、高度 1080”。

{
  "schemaVersion": 1,
  "tools": [
    {
      "name": "custom_resize",
      "description": "向当前时间组添加指定宽高的缩放滤镜",
      "parameters": {
        "type": "object",
        "properties": {
          "width": { "type": "integer", "minimum": 16, "maximum": 16384 },
          "height": { "type": "integer", "minimum": 16, "maximum": 16384 }
        },
        "required": ["width", "height"],
        "additionalProperties": false
      },
      "steps": [
        {
          "tool": "add_filter",
          "arguments": {
            "id": "resize",
            "parameters": { "width": "$width", "height": "$height" }
          }
        }
      ]
    }
  ]
}

$width 这种占位符必须占满整个字符串;替换时保留数字、布尔、对象和数组的原始类型,并递归处理嵌套参数。"宽度 $width" 会作为普通文本保留。 步骤按顺序执行,遇到错误停止;已成功执行的步骤不会回滚。缺少引用参数时不会开始执行步骤。

每个组合最多 32 步,最多保存 64 个组合;不能覆盖同名工具、调用其他组合或递归调用自己。 导入前会检查整份文件,有错误时不添加其中任何组合。重复导入同名组合会拒绝,需要修改名称后添加。 参数支持基本 JSON 类型、对象属性与必填项、枚举、数值范围,以及数组和字符串长度;不支持的 schema 关键字会明确报错。

自定义组合不会委派到子会话,子智能体仍可使用允许的直接软件工具;查询子任务也会继承父会话对这些工具的禁用状态。

MCP 连接与 npm 组件

打开“功能设置”→“MCP / npm 组件”,查看组件状态、MCP 来源及该来源的工具列表。 支持 stdio 和 Streamable HTTP 的实际连接、工具发现与调用;连接成功后,工具加入 Agent 的可用列表。

缺少组件时点击“安装 / 修复 npm 组件”。基础运行时位于程序的 runtime/agent/,包含 Node、npm 和锁定的 MCP 客户端组件。 完整分发会准备这套运行时;源码开发使用 stage-agent-runtime.ps1 准备。版本与许可见运行目录的 components.json、COMPONENTS.md、licenses/ 及 第三方声明。 修复安装需要可用的 Node/npm 和 npm 网络访问,安装的是项目锁定的组件,不会自动安装所有外部 MCP 服务。

新增来源按服务类型填写:

  • stdio:可执行文件、JSON 字符串参数数组、工作目录及 JSON 环境变量。连接会运行指定程序;node、npm、npx 可使用配套 Node/npm。
  • Streamable HTTP:服务提供的 MCP URL 和 JSON 请求头;模型的 Chat Completions 地址仍在“来源设置”中。

选择来源点击“连接”,成功后查看工具列表;“刷新工具”重新发现,“断开”停止连接。 “启动时自动连接此来源”控制后续启动行为;新增或编辑后勾选并保存也会连接。 导入支持常见 mcpServers 对象或本软件 servers 数组,导入来源保持断开,之后由用户连接。

MCP 导出省略环境变量和请求头,迁移后按需重新填写;命令、参数和 URL 仍在导出文件中。 当前没有 OAuth 登录界面;需要登录授权的服务须使用它支持的其他配置方式。旧式独立 SSE MCP 端点的兼容性不作保证。 外部服务的功能、凭证要求及运行依赖由该服务决定。

/ 命令与 @ 引用

输入 / 显示本地命令与已启用技能,输入 @ 选择资料;上下键选择,Enter 或 Tab 插入,Escape 关闭。输入 // 可发送以斜杠开头的普通文本。

写法 功能
/new、/status、/compact 新建会话、查看 Token、整理上下文
/model 模型ID、/reasoning 级别 切换模型与受支持的思考选项
/skills、/mcp、/agents 打开技能、插件或自动队列窗口
/技能名 任务、/skills 技能名 任务 将已启用技能用于任务
/agent 任务 要求 AI 实际创建并协调子智能体
/stop、/resume 停止本轮并保留待发输入、继续待发输入
@workspace 引用当前工作区状态
@skill:名称、@agent:任务ID、@mcp:来源ID 引用技能、子会话或插件工具信息
@file:"绝对路径" 引用 UTF-8 或带 BOM 的 UTF-16 文本;补全可打开文件选择器

文件引用单项不超过128 KiB,每次最多16项,正文与引用合计不超过256 KiB;不自动扫描目录。代码块、行内代码和转义的 \@ 按原文处理。 显示与导出的用户原文保留,实际引用资料附加到模型上下文;文件中的文字作为资料,不提升为系统指令。

子 Agent 队列

直接告诉主 Agent“使用子智能体完成这项任务”,或输入 /agent 任务。AI 使用 spawn_agent 自行分工,自动继承当前来源;无需填写子任务配置表单。 AI 可通过 send_agent_message 向子会话补充要求,子智能体也能向父会话或已有任务交流。完成结果自动回到父会话;wait_agent_tasks 可等待结果,不会重复投递。 超长结果的自动汇报会明确标为节选,完整输出仍保存在子会话,可通过 read_agent_task 或队列查看器读取。

查询任务最多并行 2 个,更多任务排队;允许修改的任务在队列中独占执行,前面的查询结束后才开始,其他任务等待。 查询子任务只开放查询类直接软件工具,不开放外部 MCP;允许修改的子任务可使用已连接的 MCP 工具。 在完整访问模式下,只读子任务还可读文件、搜索与使用受支持的图像工具,不能写文件或执行 Shell;允许修改的子任务可使用文件和命令工具。两类子任务均继承父访问模式和工具禁用设置,MCP 重连也不能绕过父禁用;父降权会取消现有子任务。 每个子任务使用新鲜独立会话,启动时采用全局指令与启用技能索引,不继承主聊天,也不能递归创建子任务。

底部“自动队列”显示等待、运行、完成、失败、取消或待手动恢复等状态,选中可查看真实子会话、流式回复、待接收消息和错误,也可直接发送补充内容。 任务表初次按内容安排列宽,列间分隔线可拖动调整,刷新不会重置手工调整的宽度;长文本悬停显示完整内容。 “取消选中”或“取消全部”停止相应排队或运行任务,已完成的软件修改不会自动撤销。 “恢复 / 重试”使用当前来源继续已保存的子会话,保留历史;未完成的工具结果会标记为未知,不假定已执行成功。 “清理已结束”移除非等待、非运行任务;“导入队列”和“导出队列”交换任务记录及已有结果。 导入或重启恢复后,原排队、运行任务变为待手动恢复,不会自动发起模型请求;需要执行时选择任务并点击运行。 队列导出不含来源 API Key,任务用量与主会话分别保存。

预览、编码与停止

滤镜配置成功不会自动渲染;render_preview 返回 requested 表示已请求加载,随后应读取 get_state 的 previewReady 并检查界面错误。 更改处理链后,旧预览画面不能作为新处理链已成功的依据。 enqueue_export 返回 queued 表示任务已入队;get_state.encoding 表示队列忙碌,不能单凭变为 false 判断编码成功。get_state.exports 列出每个任务的输出路径、状态及大小,completed 表示成功,failed 表示失败。

输入区的停止按钮中止主会话本轮请求和后续调用;子任务在队列中单独取消。 已完成的软件修改不会撤销,已经启动的编码任务应在导出窗口停止,或明确要求调用 stop_exports。

页面背景

进入“设置”→“多页面背景主题…”,在 VSR-Agent 行选择背景图片、底色、透明度和亮度,然后保存。 背景设置会即时应用,也可随现有主题库导入、导出。配置保存在程序旁的 themes.ini;主题包操作见 Renderer 指南。

数据与兼容边界

Agent 数据位于 Windows 应用数据目录下的 VSRenderer/VS Renderer/agent/,通常为 %APPDATA%\VSRenderer\VS Renderer\agent\。

文件或目录 内容
providers.json 来源和模型;API Key 使用当前 Windows 用户的 DPAPI 加密
mcp.json MCP 来源;环境变量与请求头使用 DPAPI 加密
AGENTS.md、skills/、skills.json 本软件全局指令、完整技能包与启用状态
conversations/ 原始对话、有效摘要检查点与主会话用量
tools.json、conversation-tasks/<会话ID>.json 自定义组合、各会话独立的子任务队列与用量;旧 tasks.json 首次迁移时保留备份

来源选择、模型记录、最近对话、禁用工具、访问模式和工作目录使用 Renderer 的 QSettings;背景在程序旁,MCP 运行时在程序的 runtime/agent/。

通过页面导出的来源文件不含密钥;会话、组合和队列导出也不会自动附带来源密钥。 用户主动写入正文、工具参数或结果的敏感内容仍会随相应记录保存与导出。DPAPI 配置迁移到其他 Windows 用户后可能需要重新填写凭证。

当前支持兼容 OpenAI Chat Completions 的流式文本和 function tools;模型必须具备工具调用能力。 Anthropic 原生协议不支持;本地命令和文件工具使用完整访问模式,外部 MCP 可继续扩展能力,自定义组合用于现有同步软件工具。 预览、滤镜及编码能力仍受本机 VapourSynth、Native、插件和 FFmpeg 组件是否可用的限制。

交互与连接方式参考 FFmpegFreeUI / 3FUI,参考提交为 787fb527b2a1e4cd247899e3f295b6b2a4e836cc;本页使用 Renderer 的 Qt 界面和独立实现。 技能按需加载、指令与子任务设计参考 DeepSeek Harness,固定提交 fcc0ad462172522aaf5c93a7b2e01f6b9f0b0159。