QoderWake的自动化任务最大的特点是无人值守，任务到了设定的时间点就会自己跑起来，没有人守在旁边补一句“这个字段是什么含义”或者“输出格式参照上周那份报告”。这种工作模式下，任务完成质量几乎完全取决于创建时挂载的参考资料是否够用。参考资料本质上是你提前写给未来某次执行的一份说明书，它决定了AI在脱离实时对话的情况下，对项目背景、执行边界和输出要求的理解深度。不少任务跑出来的结果偏离预期，复盘时发现并不是模型能力不足，而是资料没挂对、没写清。这篇文章把参考资料的作用机制、添加步骤、组织技巧和常见问题一次性讲透。
参考资料在任务执行链路中扮演什么角色
先厘清一个容易混淆的概念：QoderWake任务里的参考资料，和日常对话中随手引用一个文件，不是一回事。对话里的上下文是临时的，聊完就散；而参考资料是任务配置的一部分，跟着任务走，每次触发执行时都会被重新加载进上下文。换句话说，你今天挂上去的文档，下周三凌晨两点任务自动运行时依然生效，这就是两者最本质的区别。
从执行链路看，任务触发后，QoderWake会先组装上下文：任务描述、参考资料、以及执行过程中主动读取的文件，三者共同构成模型看到的世界。任务描述通常只能写清楚“做什么”，而“为什么这么做、做到什么程度、哪些红线不能碰”这类背景信息，就要靠参考资料来补。比如一个每日依赖漏洞巡检任务，任务描述写“检查依赖漏洞并输出报告”，参考资料则负责告诉它：项目用的技术栈版本、哪些是自研内部包出了问题该找谁、报告要按什么格式输出、不确定的信息如何标注。没有这些，AI只能按通用常识自由发挥，结果自然飘忽不定。
适合放进参考资料的内容大致有几类：项目背景与技术栈说明、编码规范和命名约定、接口文档或数据字典、历史执行结论的沉淀、输出格式模板、以及明确的禁止事项。判断一条信息该不该进参考资料，有个简单的标准：如果下次执行时AI不知道这件事就可能做错，那就值得写进去；如果只是锦上添花的细节，可以先不放，避免资料膨胀稀释重点。
添加参考资料的具体操作步骤
添加入口在任务的编辑界面里。打开QoderWake面板，如果是新建任务，在任务创建表单中找到参考资料区域；如果任务已经存在，先在任务列表中选中目标任务，进入编辑模式后再操作。参考资料区域一般提供两种来源：从工作区选择文件，以及直接粘贴文本内容。两种方式没有优劣之分，看资料本身存在哪里，已经整理成文档的自然选文件，临时性的一段说明直接粘贴更省事。
从工作区选择文件时，建议把参考资料集中放在固定目录下管理，而不是散落在项目各处。一个实践上比较好维护的结构类似这样：
docs/
wake-tasks/
daily-scan.md 每日依赖漏洞巡检的参考资料
weekly-report.md 周报自动整理的参考资料
release-checklist.md 发版前检查任务的参考资料
集中存放的好处是后续维护成本极低。任务跑了一段时间后，你会发现参考资料需要迭代，补充新的约定、删掉过时的规则，这时候只需要打开对应的那一份文档改完保存，不用在项目里翻找半天。另外，文件形式的参考资料跟着仓库走版本管理，团队里其他人也能看到和复用，粘贴文本则做不到这一点。
粘贴文本方式适合轻量场景，比如给任务补充一段“本次巡检重点关注支付模块”的临时说明。需要注意的是，粘贴的内容不会随任何文件更新而更新，属于一次性快照，重要且长期有效的信息不建议用这种方式维护，否则容易出现文件里改了、任务里还是旧内容的分裂情况。
无论哪种方式，挂载完成后建议做一次验证：手动触发一次任务执行，观察输出结果是否体现了参考资料里的要求。比如资料里写了报告必须包含严重程度排序，就看这次输出有没有这一项。验证通过，资料挂载才算真正完成。
参考资料的编写与组织技巧
资料不是越多越好。上下文窗口再大，塞进一堆无关内容也会稀释关键信息的权重，AI反而更容易漏掉重点。实践中一份好用的参考资料，控制在几百行以内比较合适，超过这个规模就该考虑拆分或者裁剪了。写法上推荐用清晰的层级结构组织，让每一类信息都有明确的归属位置，模型定位起来也更准确。
下面是一份经过实践检验的参考资料模板，可以直接套用到自己的任务上：
# 每日依赖漏洞巡检任务参考资料 ## 项目背景 订单中台服务，生产环境运行 Java 17 与 Spring Boot 3.2， 构建工具为 Maven，多模块工程。 ## 依赖范围说明 - 只关注 cn.shop 命名空间下的内部依赖 - 以下为自研基础库，出现告警时标注联系平台组处理： - shop-core - shop-rpc-client ## 输出要求 1. 按严重程度从高到低排序 2. 每条结论附上对应的 CVE 编号 3. 无法确认的信息标注待确认，禁止自行猜测补全 4. 报告结尾给出建议处理优先级
这份模板里有几个值得注意的设计。第一，背景部分只写和任务相关的信息，技术栈版本之所以要写，是因为漏洞影响范围判断依赖版本号；第二，依赖范围划了明确的边界，告诉AI哪些管、哪些不管，避免报告里混入大量无关告警；第三，输出要求写成可核对的条目而不是一段散文，AI对照清单执行的准确率明显高于自由发挥。尤其是“禁止自行猜测补全”这一条，在无人值守场景下特别重要，它决定了报告里出现的内容是可信的还是编造的。
另一个技巧是在任务描述里显式引用参考资料。任务描述和参考资料是两个独立字段，AI不一定会主动把两者关联起来，在任务描述里写明“请按照参考资料中的输出要求执行”，能显著提高资料的利用率。写法类似这样：
请按照参考资料《发版前检查清单》逐项核对当前分支： 1. 对照清单第 1 节，确认版本号与变更日志已同步更新 2. 对照清单第 2 节，执行完整构建与测试 3. 发现不符合项时只记录到报告，不要直接修改代码 最终输出检查报告，格式参照参考资料中的报告模板。
显式引用还有一个隐性好处：当任务出现偏差时，排查方向会非常清晰，要么资料内容有问题，要么AI没按资料执行，二选一，定位起来比笼统地怀疑“模型不行”高效得多。
常见问题与排查思路
最常见的问题是资料挂了但输出没体现。先检查引用方式，确认任务描述里有没有显式提到参考资料；再检查资料本身的长度，如果一份资料长到几千行，关键要求可能被淹没，试着裁剪到核心内容再跑一次；最后看资料结构，无层级的纯文本段落不如带标题分节的内容容易被准确利用。三步排查下来，绝大多数“资料不生效”都能定位到原因。
第二类问题是文件路径变动导致的失效。参考资料以文件形式挂载时，绑定的是路径，文件一旦被移动、重命名或者删除，任务就会失去这份资料。这也是前面建议集中存放的原因之一：目录结构稳定，路径变动的概率大幅降低。如果团队里有人负责重构目录结构，约定好docs下的参考资料目录不参与调整，能省掉不少隐性故障。
第三类问题是资料内容过时引发的错误输出。资料里写的技术栈版本、负责人信息、接口约定都可能随时间失效，而AI不会质疑资料内容，它默认资料是权威的。所以参考资料需要纳入常规维护节奏，比较稳妥的做法是把资料检查也做成一条低频的自动化任务，比如每两周让AI对照仓库实际情况核对一遍参考资料里的关键声明，发现不一致就输出提醒。用自动化来守护自动化，这个闭环一旦跑起来，维护负担会小很多。
最后补充一点关于多任务复用的经验。如果几个任务共享同一批基础资料，比如编码规范、技术栈说明，可以把公共部分抽成独立文档分别挂载，任务专属的规则单独一份。这样公共资料只需维护一处，改一次全部任务同步生效，比在每个任务的资料里各复制一份要可靠得多。