企业官网建设流程全解析

把 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 校验通过。
• 结果落盘：目标路径下文件存在，且必需字段齐全、可被重新读取。

其中“量级一致”“字段齐全”这类判断需要结合你自己的材料规模确认阈值，建议先按当前正常运行的结果作为基线，再对比异常运行。把这些标准写进运行后的检查脚本或清单里，比反复重写提示词更能减少排查时间。