add-resource

添加资源

请先加载规则。 在读取、编辑或写入任何 .plain 文件之前，请调用 load-plain-reference 技能，并阅读它指引你查看的规则文件。仅当本次对话中已经运行过 load-plain-reference 时，才可跳过此步骤。

链接资源是指在 .plain 规范中通过 Markdown 链接语法引用的外部文件。文件内容会与规范一同传递给渲染器，为代码生成提供额外上下文。

工作流

1. 识别或创建资源文件。 将其保存在项目内——通常放在 resources/ 目录；不必与 .plain 文件放在同一目录。
2. 在规范中的适当位置添加 Markdown 链接。
3. 确认文件路径相对于 .plain 文件所在的位置。
4. 重新读取文件，确认链接语法和路径正确。

格式

在规范的任意章节中使用标准 Markdown 链接语法：

***definitions***
- :AuthData: is the authentication data structure.
  - Its format is defined in the [auth schema](resources/auth_schema.json).

***implementation reqs***
- When transforming :BackupData:, use the JOLT transform.
  - The transform is defined in [backup_transform.jolt](resources/backup_transform.jolt).

***functional specs***

# expose-api
An API conforming to the [API specification](resources/api_spec.yaml) is exposed.

路径规则

• 路径以传递给渲染器的 .plain 文件所在目录为基准解析，而非渲染器的运行目录。
• 导入和必需模块中的链接也遵循此规则——它们同样以该目录为基准解析，而非以导入模块所在目录为基准。
• 如果路径在该目录下无法解析，接下来会在 template-dir 目录（如已配置）中查找，最后才会在渲染器内置的模板库中查找。
• 相对路径可以向上遍历父目录——只要能解析为磁盘上的真实文本文件，[resource](../../resources/resource.md) 这样的路径就是有效的。
• 禁止使用外部 URL——只能引用本地文件。
• 禁止使用目录路径——目标必须是文件，而非目录。
• 仅支持基于文本的文件。

链接资源必须是磁盘上存在的单个文本文件

链接资源始终是你所引用路径下磁盘上存在的单个文件，并且该文件的内容必须是文本格式。渲染器会读取链接文件的字节，并将其与规范一并提供给模型；目录、远程 URL 或二进制数据块都会破坏这一约定。在编写 .plain 文件时，这是最具破坏性的错误之一——规范看起来有效，但渲染器可能会静默忽略链接、读取失败，或者让模型的上下文窗口浪费在无法解读的字节上。

链接资源不能是以下三种内容：

1. 文件夹／目录。 [integrations](src/integrations/)、[schemas](resources/schemas/)、[host project](../host_project/) 都无效——渲染器无法读取目录。如果整个目录中的内容都与规范相关，请从中选出最具代表性的单个文件（例如 README.md、示例源文件或目录根目录下的清单），并链接到该文件。
2. URL／外部位置。 [Stripe docs](https://stripe.com/docs/api)、[OpenAPI spec](https://example.com/openapi.json)，以及任何 http://／https://／ftp://／git://／s3://／gs:// 目标。链接资源只能是本地文件。如果 URL 中的内容对规范至关重要，请获取一次其内容，将响应保存到 resources/ 下的文本文件中（例如 resources/stripe-docs-snapshot.md、resources/example-openapi.yaml），并链接到该文件。
3. 二进制文件。 PNG、JPG、JPEG、GIF、BMP、TIFF、WebP、ICO、PDF、DOCX、XLSX、PPTX、ZIP、TAR、GZ、MP3、MP4、WAV、编译后的二进制文件（.exe、.so、.dylib、.class、.wasm），以及其他任何原始形式下无法供人阅读的内容。渲染器无法有效处理二进制内容；链接截图、PDF 规范或打包产物，只会徒增上下文负担。如果二进制资源中的信息至关重要，请先将其转录为文本格式——将 UI 截图转换为 Markdown 描述或 resources/ 下的结构化 YAML 线框图；将 PDF 规范转换为 Markdown 摘录，或其底层 JSON Schema／OpenAPI；将架构图转换为 Markdown 文件中的 Mermaid 块。

如果 Markdown 链接目标以 / 结尾、包含 ://、指向解析后为目录的路径，或指向二进制扩展名的文件（见上方列表），请停止——它不能作为链接资源。请先将其转换为 resources/ 下的文本文件，再链接到转换后的文件。

.plain 内容中绝不能提及 URL 或文件夹路径

上述限制不只是针对 Markdown 链接语法。URL（任何 http://、https://、ftp://、git://、s3:// 等字符串）和文件夹路径（src/integrations/、../host_project/、任何以 / 结尾或解析后指向目录的内容）绝不能出现在 .plain 内容中的任何位置——无论是作为链接目标、概念正文、功能规格文本，还是实现要求。提及正文中的 URL 或文件夹是一个关键且常见的错误，原因如下：

• 渲染器无法跟踪 URL 或打开文件夹。正文中的 URL 或文件夹引用是一个虚构依赖：它在人类读者看来很有意义，却对代码生成毫无帮助。更糟的是，下游读者（以及未来的你）会以为渲染器使用了所引用的内容，导致规格偏离实际情况。
• 修复方法始终相同：如果外部内容很重要，就将其获取下来（或者从目录中选取一个规范文件），保存为 resources/ 下的文本文件，并通过常规的链接资源引用它。概念或规格应通过链接文件指明内容，而不是在字符串中写出 URL 或文件夹路径。

唯一的例外是生成的软件在运行时实际使用的 URL 和路径值（例如集成调用的基础 URL、数据库连接路径、CLI 参数值）。这些是配置值，而不是外部引用，因此应写入规格，因为生成的代码需要它们。一个实用的判断方法是：“渲染器读取此 URL／文件夹中的内容会有帮助吗？”如果有，就将其保存为文本文件并链接该文件。如果没有（它是运行时值），就可以保留在规格的纯文本中。

链接资源可以是什么

• 项目中的单个文件，可通过相对于 .plain 文件的路径访问——允许使用上级目录遍历（../）（resources/ 是惯用存放位置）。
• 渲染器可以从头到尾读取的基于文本的文件：JSON、YAML、XML、HTML、Markdown、纯文本、CSV、TSV、任何语言的源代码（.py、.js、.ts、.go、.java、.rb、.rs、.kt、.swift、.c、.cpp、.cs 等）、shell 脚本、SQL、JSON Schema、OpenAPI、AsyncAPI、Protobuf .proto、GraphQL SDL、.jolt、.env.example、.toml、.ini、.proto、Dockerfile 等。

常见资源类型

类型	典型位置	用途
JSON Schema	resources/*.json	定义数据结构契约
OpenAPI / Swagger 规格	resources/*.yaml	API 端点定义
数据转换	resources/*.jolt	数据转换规则
测试样例	resources/*.json、resources/*.csv	测试用样例数据
配置示例	resources/*.yaml	参考配置

何时使用资源

• 信息过于详细或结构复杂，不适合直接写在规格中（例如完整的 JSON Schema）。
• 多个规格或章节会引用同一份数据。
• 资源采用渲染器可以直接解析的行业标准格式（OpenAPI、JSON Schema）。

何时不使用资源

• 信息足够简短，可以直接写入规格文本。
• 文件是生成的代码（这些文件应放在 plain_modules/ 中，而不是 resources/）。

验证清单

• 资源文件存在于指定路径
• 目标是磁盘上的文件，而不是目录（路径不以 / 结尾，且解析后不是文件夹）
• 目标是本地路径，而不是 URL（目标中任何位置都不含 ://：例如没有 http://、https://、ftp://、git://、s3://、gs:// 等）
• 目标是基于文本的文件（不能是二进制扩展名：.png、.jpg、.jpeg、.gif、.bmp、.tiff、.webp、.ico、.pdf、.docx、.xlsx、.pptx、.zip、.tar、.gz、.mp3、.mp4、.wav、.exe、.so、.dylib、.class、.wasm、……）
• 周围的 .plain 内容中任何位置都不能包含 URL 或文件夹路径（无论是链接目标还是正文内容），唯一例外是生成的软件本身会使用的运行时 URL／路径值
• 路径相对于 .plain 文件，而不是绝对路径
• 相对于 .plain 文件，路径解析后指向磁盘上的真实文本文件（允许使用 ../ 路径遍历）
• Markdown 链接语法正确：[显示文本](relative/path)
• 资源内容与主题相关，且能提供超出规范文本本身的信息价值