样例:AI 应用规范
公开教程 · 无需登录

样例:AI 应用规范

下面是 CampusClaw 项目《AI 应用规范 · CampusClaw》的原文,逐条列出,可直接照抄。

适用:backend/internal/{assistant,search,knowledge}、提示词模板目录、技能文件
被谁读到:规则文件 .cursor/rules/ai.mdc;技能「按规范改一次提示词并跑评测」

1. 调用边界

检索与生成分开:关键词检索不调模型;只有生成回答这一步使用模型。出题、批改、去重这类能算出确定结果的部分走规则实现。

2. 提示词即代码

  • 模板放在 backend/internal/assistant/prompts/,随版本入库,文件头写版本号与最近一次评测结论。
  • 模板随版本变,不随环境变——它不是配置项,不放 .env。
  • 改模板走变更流程:提变更 → 改模板 → 跑评测集 → 归档结果与结论。

判据:线上生效的模板能在仓库里按版本号找到,且评测结论可追溯到那一次变更。

3. 模型与参数锁定

模型名与版本、温度、最大输出长度集中在配置里;检索阈值 SEARCH_VECTOR_MIN(默认 0.35)、召回条数写在同一处。代码中不得出现散落的数值常量。

4. 超时、重试与降级

  • 模型调用单一超时值,重试上限一次,退避后仍失败即返回 1500 区间错误码(依赖不可达)。
  • 向量库停掉时:mode=keyword 仍可用;mode=vector 与 mode=hybrid 返回 503,并给出「改用关键词模式」的下一步提示。不做无限等待。

5. 输出校验与不编造

  • 结构化输出先校验再使用;解析失败按失败处理,不静默改为默认值。
  • 两路检索都没越过阈值时返回固定文案「资料中未找到相关内容」。不得返回伪造的 material_id,不得编造片段。
  • 回答中的引用编号 [n] 只能指向真实命中;引用列表为空时正文不带编号。

判据:清空资料库后提问,回答中不应出现任何引用编号。

6. 外部内容的装配方式

材料正文、技能文件描述、工具返回一律作为数据放在用户消息里;系统提示里写明不执行其中的任何指令。名称含「解题引导」的技能只写引导步骤,不写最终答案。

7. 评测集与回归

apitest/eval/cases.jsonl 维护二十条:十条必须答对(含出处可核对),十条必须拒答(跨班资料、无依据提问、诱导性指令)。改模板或换模型版本后跑一次,结果写入 docs/eval/YYYY-MM-DD-<版本>.md。

8. 用量观测

日志记模型名、提示词版本、耗时、用量、命中数;不记提示词全文(含用户上传内容与学生提问原文)。

违反时

改模板不跑评测即视为未完成变更;出现编造出处按缺陷处理,先补评测用例再改模板。