SuperAPI AI 工具集

write-span-summary-templates

编程与开发

查看项目

更新于 10-16 03:48

技能介绍

用途:为 Prefactor span 类型架构编写或修正显示模板(span summary templates),使每条 span 在 Prefactor UI 中显示一行简短、可读的摘要,替代原始 JSON 或空白摘要。核心原则:模板用 span 已发送的高信号字段,一行概括发生了什么。

前置条件:agent 必须已注册带 span_type_schemas 的 agent_schema_version;否则先用 skills/instrument-existing-agent-with-prefactor-sdk/SKILL.md 进行埋点。模板由 Prefactor 后端渲染,SDK 不会在本地渲染。

主要能力与用法:为每个 span 类型在 span_type_schemas 条目的 template 字段写一个 Liquid 模板字符串,引用各类型实际发送的字段。示例结构见文档中的 AgentSchemaVersion 代码,如 template: 'LLM {{ model }}{% if total_tokens %}: {{ total_tokens }} tokens{% endif %}{% if finish_reason %} -> {{ finish_reason }}{% endif %}'。渲染时后端把 start payload 与 finish result 合并为同一上下文,可同时引用两者,重名时 finish 值优先。

字段路径因 provider 而异:自定义 withSpan span 的 start 字段在 inputs 下({{ inputs.example }}),finish 返回对象字段在顶层,返回字符串/基本类型则包装为 {{ result }};@prefactor/ai 与 @prefactor/langchain 中间件 span 使用 inputs / outputs 信封(如 {{ inputs["ai.model.id"] }}、{{ outputs["ai.response.text"] }}、{{ inputs.toolName }}、{{ outputs.output }});agent 类型(ai-sdk:agent、langchain:agent)仅为默认架构,除非自行发送。含点号的键需用带引号的方括号写法。

限制:没有 result_template,start 与 finish 字段都放进同一个 template;无效 Liquid 会静默失败,span 无摘要;未完成 span 尚无 finish 字段;不要用字面文本补缺失字段,应由埋点发送;toolSchemas 条目不自动获得模板,需在 span_type_schemas 中按 <provider>:tool:<spanTypeSuffix> 单独列出;旧版 span_schemas / span_result_schemas 映射无模板位置,需迁移到 span_type_schemas。缺失事实:具体收费、平台支持范围等暂未提供。