add-concept

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Add a concept to the graph

向概念图添加概念

Each node is one YAML file in

plugins/runpod/skills/runpod-usage/concepts/

(called

concepts/

below). The format, kinds, relation types and writing style are defined in

concepts/README.md

. Read it before writing; this skill is the procedure, not the format.

Every file is public-facing. Everything in it must be safe to show a customer and backed by a public source. The validator enforces this.

每个节点对应

plugins/runpod/skills/runpod-usage/concepts/

目录下的一个YAML文件（下文简称

concepts/

）。文件格式、节点类型、关系类型和写作风格均在

concepts/README.md

中定义。编写前请先阅读该文档；本技能仅说明操作流程，不涉及格式规范。

所有文件均面向公众。文件中的所有内容都必须可安全向客户展示，并有公开来源支持。验证器会强制执行此要求。

1. Check it doesn't already exist

1. 检查概念是否已存在

Search ids, names and aliases before creating anything:

bash

grep -ril "<term>" plugins/runpod/skills/runpod-usage/concepts/
cd ontology/tools && pnpm build:sqlite && pnpm query concept "<term>"   # resolves names and aliases
pnpm query search "<term>"                                     # finds rules that mention it

If the idea is a fact about an existing concept, add a rule to that file instead of a new node.
If it is a new field or state of an existing resource, add it to that file's
```
fields
```
or
```
states
```
.
Create a new file only for a thing a customer or agent names on its own, or for a flow that spans concepts.

创建任何内容前，请先搜索id、名称和别名：

bash

grep -ril "<term>" plugins/runpod/skills/runpod-usage/concepts/
cd ontology/tools && pnpm build:sqlite && pnpm query concept "<term>"   # resolves names and aliases
pnpm query search "<term>"                                     # finds rules that mention it

如果该内容是关于现有概念的一个事实，请在对应文件中添加一条规则，而非创建新节点。
如果是现有资源的新字段或状态，请将其添加到该文件的
```
fields
```
或
```
states
```
中。
仅当内容是客户或Agent独立提及的事物，或是跨概念的流程时，才创建新文件。

2. Pick the kind

2. 选择节点类型

If it is…	kind	Example
Something with its own id and CRUD in the API	`resource`	pod, template
Part of a resource with no CRUD of its own	`component`	worker, container-disk
Read-only reference data	`catalog`	gpu-type, data-center
Something you do with a resource	`capability`	pod-ssh-access
Runpod hardware a resource runs on	`infrastructure`	machine
Charges or credit	`billing`	pod-billing
A cap or quota	`limit`	api-rate-limit
A Runpod SDK or CLI	`tool`	flash
Something Runpod references but doesn't own	`external`	container-image
How something works, in order, across concepts	`process`	pod-deployment

Set

is_a

for a kind-of parent (

cpu-pod

is_a

pod

). Set

part_of

for the whole it belongs to (

worker

part_of

serverless-endpoint

). Top-level resources, catalogs, billing roots, tools and limits sit

part_of: runpod-platform

若内容是…	类型（kind）	示例
在API中拥有独立id和CRUD的事物	`resource`	pod、template
资源的组成部分，自身无独立CRUD	`component`	worker、container-disk
只读参考数据	`catalog`	gpu-type、data-center
可对资源执行的操作	`capability`	pod-ssh-access
资源运行所依赖的Runpod硬件	`infrastructure`	machine
费用或额度	`billing`	pod-billing
上限或配额	`limit`	api-rate-limit
Runpod SDK或CLI	`tool`	flash
Runpod引用但不拥有的事物	`external`	container-image
跨概念的事物运作流程	`process`	pod-deployment

为父类设置

is_a

关系（例如

cpu-pod

is_a

pod

）。为所属的整体设置

part_of

关系（例如

worker

part_of

serverless-endpoint

）。顶级资源、目录、计费根节点、工具和限制的

part_of

均设为

runpod-platform

。

3. Find public sources first

3. 优先查找公开来源

Write only what a public source supports:

Source	Where	Cite as
REST v2 spec	`testdata/runpod-migrate/v2-openapi.json`	`source: rest-v2-spec` , `ref: Schema.field`
Public docs	the `runpod/docs` repo, or docs.runpod.io	`source: public-docs` , `url: https://docs.runpod.io/<path>`
Skills in this repo	`plugins/runpod/skills/`	`source: skill` , `path: plugins/runpod/skills/...`
A read-only request you ran	the live API	`source: live-probe` , `ref:` the request, `seen:` the date

If no public source supports a claim, leave it out. Don't cite internal documents, internal ids or private repositories. Don't create billable resources to verify a claim without asking first.

仅编写有公开来源支持的内容：

来源	位置	引用格式
REST v2 规范	`testdata/runpod-migrate/v2-openapi.json`	`source: rest-v2-spec` 、 `ref: Schema.field`
公开文档	`runpod/docs` 仓库，或 docs.runpod.io	`source: public-docs` 、 `url: https://docs.runpod.io/<path>`
本仓库中的Skill	`plugins/runpod/skills/`	`source: skill` 、 `path: plugins/runpod/skills/...`
执行的只读请求	线上API	`source: live-probe` 、 `ref:` 对应请求、 `seen:` 日期

如果没有公开来源支持某项表述，请省略该内容。不得引用内部文档、内部id或私有仓库。未经许可，不得创建付费资源来验证表述。

4. Write the file

4. 编写文件

Copy the shape of a similar file (

pod.yaml

for a resource,

machine.yaml

for infrastructure,

pod-deployment.yaml

for a process) and fill in:

```
id
```
(kebab-case; the file is
```
<id>.yaml
```
),
```
name
```
,
```
kind
```
,
```
summary
```
(one or two customer-facing sentences),
```
product
```
,
```
is_a
```
,
```
part_of
```
,
```
aliases
```
.
```
surfaces
```
: the REST v2 schema and paths, GraphQL names from the public reference, MCP tools,
```
runpodctl
```
commands, console page.
```
fields
```
and
```
states
```
if the concept has them. With a REST v2 schema, every field must exist on that schema or its create/update request.
```
relations
```
, from the closed set in
```
concepts/README.md
```
.
```
rules
```
: one fact per rule, with an id of
```
<concept-id>.<slug>
```
. Write one to three sentences an agent can act on. Point
```
applies_to
```
at the fields, states or actions the rule constrains. Put related rules on other concepts in
```
see:
```
instead of restating them.

For a process, add

steps

in order. Each step has an

id

title

description

, the

concepts

it involves and the

rules

that govern it. Steps link to rules that already exist on the concepts. Put only the facts that belong to the flow as a whole on the process itself, such as

pod-deployment.stock-is-not-your-machine

Style: plain present tense, code identifiers in backticks, "Runpod" spelled correctly, and no words like "currently" or "not yet". The full list is in

concepts/README.md

under "Writing style".

Don't use

comments:

pnpm format

rewrites the file from its data and refuses a file with a comment, since it would drop it. Put the context in a

note

on the evidence instead.

参考同类文件的结构（资源类参考

pod.yaml

，基础设施类参考

machine.yaml

，流程类参考

pod-deployment.yaml

），填写以下内容：

```
id
```
（短横线命名法（kebab-case）；文件名为
```
<id>.yaml
```
）、
```
name
```
、
```
kind
```
、
```
summary
```
（一到两句面向客户的描述）、
```
product
```
、
```
is_a
```
、
```
part_of
```
、
```
aliases
```
。
```
surfaces
```
：REST v2 schema和路径、公开参考文档中的GraphQL名称、MCP工具、
```
runpodctl
```
命令、控制台页面。
若概念有
```
fields
```
和
```
states
```
，则填写。如果存在REST v2 schema，每个字段都必须在该schema或其创建/更新请求中存在。
```
relations
```
：从
```
concepts/README.md
```
中的封闭关系集合中选取。
```
rules
```
：每条规则对应一个事实，id格式为
```
<concept-id>.<slug>
```
。编写一到三句Agent可执行的描述。将
```
applies_to
```
指向规则约束的字段、状态或操作。其他概念上的相关规则请通过
```
see:
```
引用，不要重复表述。

对于**流程（process）**类型的节点，需按顺序添加

steps

。每个步骤包含

id

、

title

、

description

、涉及的

concepts

以及约束该步骤的

rules

。步骤链接到概念上已存在的规则。仅将属于整个流程的事实放在流程节点本身中，例如

pod-deployment.stock-is-not-your-machine

。

写作风格：使用一般现在时，代码标识符用反引号包裹，"Runpod"拼写正确，不要使用“currently（目前）”或“not yet（尚未）”这类词汇。完整列表见

concepts/README.md

中的“Writing style”部分。

不要使用

注释：

pnpm format

会根据数据重写文件，并且会拒绝包含注释的文件，因为注释会被丢弃。请将上下文信息放在证据的

note

字段中。

5. Validate and look at it

5. 验证并查看结果

bash

cd ontology/tools
pnpm format              # canonical style; CI runs format:check
pnpm validate --strict   # must report 0 errors and 0 warnings
pnpm test
pnpm build:graph         # open ../build/graph.html

Common validator errors:

Error	Fix
`... is not a concept`	A relation, `is_a` , `part_of` , field `ref` or step names a missing id.
`applies_to field:x, which ... does not declare`	Add the field, or point at one that exists.
`mentions an internal ...`	Restate the rule from a public source, or delete it.
`is time-bound`	Say what holds, and put the date in evidence as `seen` .
`YAML does not parse`	Quote any item inside `[ ]` or `{ }` that contains a comma, `[]` , `{}` , `:` or `#` .

In the graph, find the node, check that its links make sense, and read its panel once as a customer would.

bash

cd ontology/tools
pnpm format              # canonical style; CI runs format:check
pnpm validate --strict   # must report 0 errors and 0 warnings
pnpm test
pnpm build:graph         # open ../build/graph.html

常见验证器错误：

错误信息	修复方法
`... is not a concept`	关系、 `is_a` 、 `part_of` 、字段 `ref` 或步骤引用了不存在的id。
`applies_to field:x, which ... does not declare`	添加该字段，或指向已存在的字段。
`mentions an internal ...`	用公开来源重新表述规则，或删除该规则。
`is time-bound`	说明适用的内容，并将日期以 `seen` 字段添加到证据中。
`YAML does not parse`	为 `[ ]` 或 `{ }` 内包含逗号、 `[]` 、 `{}` 、 `:` 或 `#` 的内容添加引号。

在概念图中找到该节点，检查其链接是否合理，并站在客户的角度通读一遍节点面板内容。

6. Link a guide

6. 关联指南

Every concept must be covered by at least one skill, reference doc or golden path;

pnpm check:guides

fails otherwise. Follow the

write-guide

skill (

.claude/skills/write-guide/SKILL.md

) to extend an existing doc or write a new one, and to check that the docs already covering the concept still agree with its rules.

每个概念都必须至少有一个Skill、参考文档或黄金路径覆盖；否则

pnpm check:guides

会执行失败。请按照

write-guide

技能（路径：

.claude/skills/write-guide/SKILL.md

）扩展现有文档或编写新文档，并检查已覆盖该概念的文档是否仍与其规则一致。

7. Commit

7. 提交

Commit the concept file, plus any other files you linked from or to, with a Conventional Commits message that says what the node explains, for example

docs(concepts): explain why a stopped pod may not restart

提交概念文件，以及所有你关联的其他文件，使用Conventional Commits格式的提交信息，说明节点解释的内容，例如

docs(concepts): explain why a stopped pod may not restart

。