SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场aif-reference

aif-reference

智能体与模型

查看项目

更新于 10-16 09:21

技能介绍

用途

aif-reference 用于从外部来源创建结构化的知识参考，并将其存储到配置的 references 目录中，以便其他 AI Factory 技能后续复用。它适合以下场景：AI 需要其未训练过或仅部分了解的文档；希望基于特定文档、规范或内部文件获得有依据的回答；希望为 /aif-plan、/aif-implement、/aif-explore 或 /aif-grounded 提供可复用的领域上下文；希望获得持久的知识产物而非一次性的对话上下文。

主要能力

  • 从 URL 抓取网页内容，提取主题与目的、关键概念与术语定义、代码示例与模式、API 方法/参数/返回类型与签名、配置选项及默认值、最佳实践与建议、错误处理与边界情况、版本信息与兼容性说明，以及关键子页面链接。必要时会抓取关键子页面（每个来源 URL 最多额外 8 个页面），并可运行 1-2 次针对性搜索填补明显缺口。
  • 处理本地文件，支持读取文件及其引用的其他本地文件（最多 5 层包含），自动识别 markdown、HTML、JSON、YAML、纯文本等格式并相应提取。
  • 将收集到的材料综合为结构化参考文档，包含 Overview、Core Concepts、API / Interface、Usage Patterns、Configuration、Best Practices、Common Pitfalls、Version Notes 等章节。
  • 按命名约定保存参考文件（小写、连字符、.md 后缀），并登记到 INDEX.md 索引中。
  • 支持更新模式（--update），重新抓取来源并仅更新变化的部分，保留 Created 日期并更新 Updated 日期。
  • 支持 list、show <name>、delete <name> 等管理操作。

使用方式

该技能通过参数识别工作模式：包含 --update 进入更新模式；包含 URL（http/https）进入 URL 模式；包含文件路径进入文件模式；"list" 列出已有参考；"show <name>" 显示参考内容；"delete <name>" 删除参考（需确认）；参数为空则进入交互模式。

执行前会先读取 .ai-factory/config.yaml（若存在）以解析 paths.references、paths.rules_file、language.ui、language.artifacts、language.technical_terms 等配置。若配置文件不存在，则使用默认值：references 目录为 .ai-factory/references/，RULES.md 为 .ai-factory/RULES.md，ui_language 为 en，artifact_language 为 en，technical_terms_policy 为 keep。

若存在 .ai-factory/skill-context/aif-reference/SKILL.md，则必须读取，其中的项目级规则会覆盖本技能的通用规则，并适用于本技能的所有输出，包括生成的参考文件。

工作流程包括：确保 references 目录存在并检查已有参考以避免重复；收集来源；综合生成参考文档；命名并保存；登记到 INDEX.md；向用户报告参考名称与路径、行数、包含章节、使用的来源以及如何在后续 AI Factory 工作流中使用。

适用场景

  • 为 AI 智能体构建可复用的领域知识库。
  • 基于特定文档、规范或内部文件提供有依据的回答。
  • 为规划、实现、探索、有依据回答等技能提供上下文或证据来源。
  • 需要持久知识产物而非一次性对话上下文的场合。

限制

  • 单个参考建议不超过 1000 行；若超出则拆分为多个文件，并在 references 目录内创建带 INDEX.md 的子目录。
  • 创建新参考前需检查已有参考，避免重复。
  • 参考必须包含来源，以便刷新，避免数据过时。
  • 参考应反映来源而非个人偏好，不包含主观意见。
  • 若 URL 需要认证或加载失败，应报告该情况而非猜测。
  • 生成内容不得虚构，只能包含实际找到的信息；代码示例必须逐字保留。
  • 生成参考文件与 INDEX.md 必须使用 artifact_language 书写；UI 提示、进度更新、摘要与下一步指引必须使用 ui_language。
  • 技术术语策略仅接受 keep、translate、mixed，其他值按 keep 处理；english 等旧值也按 keep 处理。
  • 保留源引用、源标题、URL、本地路径、代码示例、API 签名、命令名、配置键、包名、版本字符串、原始错误与链接目标不变。

与其他技能的集成

references 目录中的参考可供所有 AI Factory 技能使用：/aif-plan 与 /aif-implement 可读取作为领域上下文；/aif-grounded 可作为证据来源；/aif-explore 可在研究时引用。若要让某技能感知特定参考，可在解析后的 RULES.md 中提及，例如在 References 章节下写明：For <topic> details, see <resolved references dir>/<name>.md。

产物归属

主要归属：解析后的 references 目录（默认 .ai-factory/references/）。共享归属：该目录内的 INDEX.md 索引文件。只读：其他所有 .ai-factory/ 文件。配置策略：感知配置，使用 paths.references 作为存储路径，paths.rules_file 用于指向其他技能，language.ui 用于提示与摘要，language.artifacts 用于生成的参考产物，language.technical_terms 用于人类可读术语策略。