把 Academic Research Skills 接进已有 Agent 工作流后任务跑不完时先别动提示词。多数情况下失败点不在“模型不会写”而在某一层的输入契约没对齐技能没被加载、材料被截断、输出格式没被约束、落盘路径写不进去。可行的做法是把链路拆成层用日志和最小任务逐层确认把“没反应”变成“某一层失败了”。判断方向技能接入后的报错通常按“调用入口 → 技能加载 → 输入材料 → 模型输出 → 结果落盘”五层定位而不是整体重写提示词。适用场景是你已有能跑通的 Agent 工作流只是新增了科研技能。操作动作先画层、再跑一个最小任务、用日志确认停在哪层、单变量替换验证。验证方式每层留一条可观察的通过标准。边界具体的字段名、接口名取决于你自己的实现下面给的是骨架不是某个产品的官方接口。画出工作流的层调用入口、技能加载、输入材料、模型输出、结果落盘画层的目的很实际报错信息只告诉你“失败了”不告诉你失败在哪一环。先按这五层各写清输入、输出和失败时的可见现象后面排查才有落点。调用入口。输入命令或触发参数、任务描述文件。输出一次运行记录run id、开始时间。失败现象命令直接退出、没有任何日志文件生成。技能加载。输入技能目录或技能清单。输出加载成功提示、可用技能列表。失败现象任务开始后模型像“不认识这个技能”输出泛泛而谈日志里没有加载记录。输入材料。输入论文、笔记、数据集等原始文件。输出解析后的文本或结构化条目。失败现象解析报编码错、材料为空、条目数明显偏少。模型输出。输入拼好的提示与材料。输出模型返回的文本或结构化结果。失败现象输出被截断、格式不是约定的 JSON、字段缺失。结果落盘。输入待写入的结果对象与目标路径。输出磁盘上真实存在的文件。失败现象目录不存在、无写权限、文件名冲突被覆盖。这五层不绑定任何具体产品接口不同实现里叫法可能不同但只要能对应上“加载、解析、生成、写入”四个动作就够了。写一份最小配置骨架并只跑一个最小任务确认链路本身通不通用一个最小任务即可一篇短文、一个输出字段。目录可以长这样workflow/ skills/research-lite/ skill.yaml prompt.md inputs/ paper.md task.yaml schemas/ result.json runs/run-001/ logs/配置字段名按你自己的实现替换下面是骨架而非官方字段workflow: research-lite # 本次工作流名称用于日志前缀 task_file: inputs/task.yaml # 任务描述文件路径 skills: - name: research-lite # 技能标识需与目录一致 path: skills/research-lite enable: true # 关掉可快速验证“是不是技能没加载” input: source: inputs/paper.md # 待解析材料 encoding: utf-8 # 解析用的编码按文件实际情况定 model: prompt_file: skills/research-lite/prompt.md # provider、model 等按你的接入方式填写 output: format: json # 期望的输出格式 schema: schemas/result.json path: runs/run-001/output.json log: level: info path: logs/run-001.log逐个字段看含义task_file决定入口读什么skills[].path决定加载哪一层input.source决定材料从哪来prompt_file决定提示模板output.schema决定输出被怎么校验log.path决定你后面能看什么。第一次运行只保留一个技能、一份材料、一个输出字段避免多因素同时出问题。从运行日志确认任务停在哪一层日志的作用是把“没反应”翻译成层级。运行时重点看四个位置入口打印的运行记录、技能加载段的输出、输入解析段的结果、以及模型返回与写盘接缝处。看有没有加载成功提示例如带技能名的 loaded / registered 字样关键字以你的实现为准。没有问题在加载层。看输入解析结果读到的字符数或条目数、是否有编码或解析异常。数字明显偏小多半是材料被截断或路径写错。看模型调用前后的分界请求是否发出、响应是否完整结束、有没有超时或截断标记。看写盘那几行目标路径、是否创建目录、是否写入成功。路径打印出来但文件不存在问题在落盘层。出现异常栈时看栈顶第一行和它所在的模块名通常直接对应上面某一层。分层替换变量输入材料、提示、输出格式各改一次找到大致层级后别一次改三样。单变量对照每次只改一项跑完记录现象差异再决定下一次改什么。建议按“输入材料 → 提示 → 输出格式”的顺序因为前面错会影响后面表现。第一轮只换输入材料换成一篇更短、结构更规整的文件其余不动。第二轮只改提示同一份材料把任务描述改得更具体输出格式约束不变。第三轮只改输出格式或 schema收紧字段约束材料和提示都不动。每轮记录下面这些字段几次之后就能看出哪一层一直在拖后腿序号改动层输入材料 / 提示 / 输出格式变量名与改动前取值、改动后取值改动前现象、改动后现象是否复现初步指向的失败层如果只改一项就复现消失基本可以锁定那一层如果怎么改都一样问题更可能在加载层或调用入口。每层各留一条通过标准给每层定一条能自动判断的标准下次运行不用靠感觉。标准要能通过日志或文件直接看到调用入口日志文件生成且带本次 run 标识。技能加载日志出现加载成功提示技能列表里能看到目标技能名。输入材料解析结果非空字符数或条目数与源文件量级一致。模型输出返回内容完整结束若约定 JSON则能被 schema 校验通过。结果落盘目标路径下文件存在且必需字段齐全、可被重新读取。其中“量级一致”“字段齐全”这类判断需要结合你自己的材料规模确认阈值建议先按当前正常运行的结果作为基线再对比异常运行。把这些标准写进运行后的检查脚本或清单里比反复重写提示词更能减少排查时间。