add-concept

向图谱添加概念

每个节点都是 plugins/runpod/skills/runpod-usage/concepts/ 中的一个 YAML 文件 （下文称为 concepts/）。格式、类型、关系类型和写作风格均在 concepts/README.md 中定义。编写前请先阅读；此技能说明的是流程，而非格式。

每个文件都会面向公众。文件中的所有内容都必须适合向客户展示，并有公开来源作为依据。验证器会对此进行检查。

1. 检查概念是否已存在

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

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. 选择类型

如果是……	类型	示例
在 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）。顶级资源、目录、计费根节点、工具和限制均属于 runpod-platform，即设置 part_of: runpod-platform。

3. 先查找公开来源

只写公开来源能够支持的内容：

来源	位置	引用方式
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>
此仓库中的技能	plugins/runpod/skills/	source: skill、path: plugins/runpod/skills/...
你执行的只读请求	实时 API	source: live-probe、ref: 请求内容、seen: 日期

如果没有公开来源支持某项说法，就不要写入。不要引用内部文档、内部 ID 或私有仓库。未经事先许可，不要创建计费资源来验证说法。

4. 编写文件

参考类似文件的结构（资源使用 pod.yaml，基础设施使用 machine.yaml，流程使用 pod-deployment.yaml），并填写：

1. id（kebab-case；文件名为 <id>.yaml）、name、kind、summary（一到两句面向客户的描述）、product、is_a、part_of、aliases。
2. surfaces：REST v2 架构和路径、公共参考中的 GraphQL 名称、MCP 工具、runpodctl 命令、控制台页面。
3. 如果这个概念有 fields 和 states，则添加它们。对于 REST v2 架构，每个字段都必须存在于该架构或其创建／更新请求中。
4. relations，从 concepts/README.md 中的有限集合里选择。
5. rules：每条规则只陈述一个事实，id 格式为 <concept-id>.<slug>。写一到三句可供 Agent 执行的描述。将 applies_to 指向规则所约束的字段、状态或操作。将相关规则放在其他概念的 see: 中，不要重复陈述。

对于流程，按顺序添加 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. 验证并查看

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. 链接指南

每个概念都必须至少由一项 skill、参考文档或黄金路径涵盖；否则 pnpm check:guides 会失败。按照 write-guide skill （.claude/skills/write-guide/SKILL.md）扩展现有文档或编写新文档，并检查已经涵盖该概念的文档是否仍与其规则一致。

7. 提交

提交概念文件以及你链接到或从其链接的其他文件，并使用说明该节点内容的 Conventional Commits 消息，例如 docs(concepts): explain why a stopped pod may not restart。