aif-reference

参考资料创建器

从外部来源创建结构化知识参考资料，并将其存储在已配置的参考资料目录中，以便其他 AI Factory 技能之后重复使用。

步骤 0：加载配置

首先： 如果 .ai-factory/config.yaml 存在，请读取它以确定：

• 路径： paths.references 和 paths.rules_file
• 语言： 用于提示词和摘要的 language.ui、用于生成参考资料的 language.artifacts，以及参考资料中面向用户的技术术语所用的 language.technical_terms

如果 config.yaml 不存在，请使用默认值：

• references/：.ai-factory/references/
• RULES.md：.ai-factory/RULES.md
• ui_language：en
• artifact_language：en
• technical_terms_policy：keep

解析后的语言值：

• ui_language = language.ui || "en"
• artifact_language = language.artifacts || language.ui || "en"
• technical_terms_policy = language.technical_terms || "keep"

如果 technical_terms_policy 不是 keep、translate 或 mixed 之一，则按 keep 处理。english 等旧值也按 keep 处理。

所有 AskUserQuestion 提示、进度更新、摘要和后续步骤指引都必须使用 ui_language 编写。

生成的参考资料文件和参考资料 INDEX.md 必须使用 artifact_language 编写。

模板和示例用于定义结构，而非固定的英文输出。如果 artifact_language 不是 en，保存前请翻译面向用户的标题、标签、摘要、概念说明、最佳实践说明、注意事项和索引描述。保留来源引文、来源标题、URL、本地路径、代码示例、API 签名、命令名称、配置键、软件包名称、版本字符串、原始错误和链接目标，不作更改。对其他面向用户的术语应用 technical_terms_policy。

项目上下文

读取 .ai-factory/skill-context/aif-reference/SKILL.md——如果该文件存在，则必须读取。

此文件包含 /aif-evolve 根据补丁、代码库规范和技术栈分析积累的项目专属规则。这些规则针对当前项目进行了定制。

如何应用 skill-context 规则：

• 将其视为对本技能通用说明的项目级覆盖规则
• 当 skill-context 规则与本 SKILL.md 中的通用规则冲突时，以 skill-context 规则为准
• 若无冲突，则两者都适用
• 重要：skill-context 规则适用于本技能的所有输出，包括生成的参考资料文件。如果 skill-context 规则要求“参考资料必须包含 X”，则必须遵守。

**执行要求：**生成任何输出文件后，都要根据所有 skill-context 规则进行检查。如果发现违反规则，则在向用户展示前修正输出。

适用场景

• AI 需要其训练数据中没有或可能只部分掌握的文档
• 你希望根据特定文档、规范或内部文件获得有依据的回答
• 你希望为 /aif-plan、/aif-implement、/aif-explore 或 /aif-grounded 提供可重复使用的领域上下文
• 你希望创建持久的知识文件，而非一次性对话上下文

参数检测

Check $ARGUMENTS:
- Contains "--update"        -> Update Mode: refresh existing reference
- Contains URLs (http/https) -> URL Mode: fetch and process web sources
- Contains file paths        -> File Mode: process local documents
- "list"                     -> List existing references
- "show <name>"              -> Show reference content
- "delete <name>"            -> Delete a reference (with confirmation)
- Empty                      -> Interactive mode

工作流

步骤 0.1：设置

确保已解析的参考资料目录存在：

mkdir -p <resolved references dir>

检查是否已有参考资料，以避免重复：

ls <resolved references dir>

如果提供了 --name <ref-name>，则将其用作参考资料名称。 如果提供了 --update，则查找并更新现有参考资料，而不是创建新的参考资料。

步骤 1：收集来源

对于 URL：

对于每个 URL：

1. 使用 WebFetch 获取页面并提取：
   • 主要主题和用途
   • 关键概念、术语和定义
   • 代码示例和模式
   • API 方法、参数、返回类型和签名
   • 带默认值的配置选项
   • 最佳实践和建议
   • 错误处理和边界情况
   • 版本信息和兼容性说明
   • 指向关键子页面的链接
2. 如果引用了关键子页面，也获取这些页面（每个来源 URL 最多额外获取 8 个页面）。
3. 如果仍有明显的信息缺口，运行 1-2 次有针对性的 WebSearch 查询来补充。

对于本地文件：

1. 使用 Read 读取每个文件
2. 如果文件引用了其他本地文件，也读取这些文件（最多递归包含 5 层）
3. 检测文件格式（markdown、HTML、JSON、YAML、纯文本）并据此提取内容

对于交互模式：

询问用户：

1. 此参考文档应涵盖什么主题或技术？
2. 他们是否有 URL 或本地文件，还是需要你进行搜索？
3. 对他们的使用场景来说，哪些方面最重要？

步骤 2：综合整理参考文档

将收集的材料整理为结构化参考文档。

参考文件格式：

保存前，使用 artifact_language 呈现此结构。以下标题是规范结构标签，不是固定的英文输出。

# <Topic> Reference

> Source: <list of source URLs or file paths>
> Created: YYYY-MM-DD
> Updated: YYYY-MM-DD

## Overview

<1-3 paragraph summary>

## Core Concepts

<Concept 1>: <clear explanation>
<Concept 2>: <clear explanation>

## API / Interface

<Only if applicable. Preserve exact signatures and types from source docs.>

## Usage Patterns

<Practical code examples organized by use case.>

## Configuration

<Options, defaults, valid values. Table format preferred.>

## Best Practices

<Numbered list with reasoning>

## Common Pitfalls

<What goes wrong and how to avoid it>

## Version Notes

<Only if relevant. Breaking changes, migration notes, deprecations.>

质量规则：

• 不编造 - 仅包含实际查找到的内容
• 原样保留代码 - 文档中的示例必须保持原样
• 注重可操作性，而非学术性 - 优先提供便于查阅的信息
• 内容精炼 - 尽可能提高每行的信息量
• 完整签名 - API 需包含完整参数、类型和返回值
• 注明来源 - 始终包含来源 URL 或路径

步骤 3：命名并保存

命名约定：

• 根据主题确定名称：react-hooks.md、fastapi-endpoints.md、docker-compose.md
• 使用小写字母、连字符和 .md
• 如果提供了 --name，则使用该名称（若缺少 .md，则添加）
• 避免使用 reference.md 等通用名称

保存到： <resolved references dir>/<name>.md

步骤 4：在索引中注册

检查 <resolved references dir>/INDEX.md 是否存在。创建或更新该文件：

使用 artifact_language 编写易读的索引标题、主题说明和来源摘要；文件名、链接、URL 和日期保持不变。

# References Index

Available knowledge references for AI agents.

| Reference | Topic | Sources | Updated |
|-----------|-------|---------|---------|
| [react-hooks](react-hooks.md) | React Hooks API and patterns | react.dev | 2026-03-20 |
| [docker-compose](docker-compose.md) | Docker Compose configuration | docs.docker.com | 2026-03-20 |

步骤 5：报告

向用户显示：

• 参考文档名称和路径
• 大小（行数）
• 包含的章节
• 使用的来源 URL 或文件路径
• 如何在后续 AI Factory 工作流中使用该文档

更新模式（--update）

启用 --update 时：

1. 根据 --name 或匹配的来源查找现有参考文档
2. 重新获取标头中列出的来源
3. 将新材料与现有内容进行比较，并仅更新有变化的章节
4. 保留 Created:，更新 Updated:
5. 报告变更内容

列出 / 显示 / 删除

• /aif-reference list - 读取并显示 <resolved references dir>/INDEX.md，或列出目录中的文件
• /aif-reference show <name> - 读取并显示参考文档内容（.md 可省略）
• /aif-reference delete <name> - 请求确认，删除文件并更新 INDEX.md

与其他技能集成

已解析的参考文档目录中的参考文档可供所有 AI Factory 技能使用：

• /aif-plan 和 /aif-implement 可读取这些文档以获取领域背景
• /aif-grounded 可将其用作证据来源
• /aif-explore 可在研究过程中引用这些文档

如需让某项技能识别特定参考文档，请在已解析的 RULES.md 文件中提及该文档：

## References
- For <topic> details, see `<resolved references dir>/<name>.md`

Artifact 归属

• 主要归属： 解析后的参考资料目录（默认：.ai-factory/references/）
• 共同归属： 解析后的参考资料索引文件（该目录中的 INDEX.md）
• 只读： 其他所有 .ai-factory/ 文件
• 配置策略： 根据配置进行处理。使用 paths.references 指定存储位置，使用 paths.rules_file 在将其他技能指向已保存的参考资料时指定路径，使用 language.ui 编写提示词和摘要，使用 language.artifacts 生成参考资料，使用 language.technical_terms 制定面向用户的术语规范。

防护规则

• 参考资料长度上限： 尽量将每份参考资料控制在 1000 行以内。若更长，则拆分为多个文件，并在解析后的参考资料目录中创建一个目录，且在其中放置 INDEX.md
• 避免重复： 创建新参考资料前，先检查现有资料
• 避免数据过时： 始终包含来源，以便刷新参考资料
• 不加入个人观点： 参考资料应反映来源内容，而非个人偏好
• 遵守访问限制： 如果 URL 需要身份验证或无法加载，应如实说明，不要猜测