add-resource

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Add Resource

添加资源

Always use the skill

load-plain-reference

to retrieve the ***plain syntax rules — but only if you haven't done so yet.

Linked resources are external files referenced from within a

.plain

spec using markdown link syntax. The file contents are passed to the renderer alongside the spec, providing additional context for code generation.

请务必使用技能

load-plain-reference

来获取***plain语法规则——但仅在你尚未获取的情况下使用。

链接资源是指在

.plain

规范中使用Markdown链接语法引用的外部文件。文件内容会与规范一起传递给渲染器，为代码生成提供额外上下文。

Workflow

工作流程

Identify or create the resource file. It should be in the
```
resources/
```
directory or in the same folder (or a subfolder) as the
```
.plain
```
file.
Add the markdown link at the appropriate place in the spec.
Verify the file path is relative to the
```
.plain
```
file location.
Read the file back to confirm correct link syntax and path.

识别或创建资源文件。文件应位于
```
resources/
```
目录中，或与
```
.plain
```
文件处于同一文件夹（或其子文件夹）。
在规范的适当位置添加Markdown链接。
验证文件路径是否相对于
```
.plain
```
文件的位置。
重新读取文件以确认链接语法和路径正确。

Format

格式

Use standard markdown link syntax inside any spec section:

plain

***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 defined in
  [backup_transform.jolt](resources/backup_transform.jolt).

***functional specs***
- The system should expose an API conforming to the
  [API specification](resources/api_spec.yaml).

在规范的任意部分内使用标准Markdown链接语法：

plain

***definitions***
- :AuthData: 是认证数据结构。其格式定义在
  [auth schema](resources/auth_schema.json)中。

***implementation reqs***
- 转换:BackupData:时，请使用[backup_transform.jolt](resources/backup_transform.jolt)中定义的JOLT转换规则。

***functional specs***
- 系统应暴露符合[API specification](resources/api_spec.yaml)的API。

Path Rules

路径规则

Paths are resolved relative to the
.plain
file location.
Only files in the same folder or subfolders are supported.
No external URLs — only local file references.
No absolute paths.

路径会相对于
.plain
文件的位置解析。
仅支持同一文件夹或子文件夹中的文件。
不支持外部URL——仅允许本地文件引用。
不允许使用绝对路径。

Common Resource Types

常见资源类型

Type	Typical location	Use case
JSON Schema	`resources/*.json`	Defining data structure contracts
OpenAPI / Swagger spec	`resources/*.yaml`	API endpoint definitions
Data transforms	`resources/*.jolt`	Data transformation rules
Test fixtures	`resources/.json` , `resources/.csv`	Sample data for tests
Configuration examples	`resources/*.yaml`	Reference configurations

类型	典型位置	使用场景
JSON Schema	`resources/*.json`	定义数据结构契约
OpenAPI / Swagger spec	`resources/*.yaml`	API端点定义
数据转换规则	`resources/*.jolt`	数据转换规则
测试夹具	`resources/.json` , `resources/.csv`	测试用示例数据
配置示例	`resources/*.yaml`	参考配置

When to Use Resources

何时使用资源

The information is too detailed or structured to express inline in the spec (e.g., a full JSON schema).
The same data is referenced by multiple specs or sections.
The resource is an industry-standard format (OpenAPI, JSON Schema) that the renderer can interpret directly.

信息过于详细或结构化，无法在规范中内联表达（例如完整的JSON Schema）。
同一数据被多个规范或章节引用。
资源是渲染器可直接解析的行业标准格式（如OpenAPI、JSON Schema）。

When NOT to Use Resources

何时不使用资源

The information is short enough to include inline in the spec text.
The file is generated code (those belong in
```
plain_modules/
```
, not
```
resources/
```
).

信息足够简短，可以直接包含在规范文本中。
文件是生成的代码（这类文件应放在
```
plain_modules/
```
中，而非
```
resources/
```
）。

Validation Checklist

验证检查清单

Resource file exists at the specified path
Path is relative to the
```
.plain
```
file, not absolute
File is in the same folder or a subfolder (no
```
../
```
references)
Markdown link syntax is correct:
```
[display text](relative/path)
```
Resource content is relevant and adds value beyond what the spec text says
No external URLs used

资源文件存在于指定路径
路径相对于
```
.plain
```
文件，而非绝对路径
文件位于同一文件夹或子文件夹中（无
```
../
```
引用）
Markdown链接语法正确：
```
[显示文本](相对路径)
```
资源内容相关且为规范文本提供额外价值
未使用外部URL