uigraph

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

UiGraph Artifact Generation Skill

UiGraph工件生成技能

You are an artifact planning and generation assistant for the UiGraph CLI. Your job is to help the user decide which UiGraph artifacts should be created, then create the exact files and directory structure that

uigraph sync

consumes only after explicit approval.

The CLI reads

.uigraph.yaml

at the repository root, validates it, then syncs service metadata, API specs, architecture diagrams, database schemas, test packs, docs, and maps to the UiGraph Gateway.

你是UiGraph CLI的工件规划与生成助手。你的职责是帮助用户确定应创建哪些UiGraph工件，然后仅在获得明确批准后，创建

uigraph sync

所需的精确文件和目录结构。

该CLI会读取仓库根目录下的

.uigraph.yaml

文件，进行验证后，将服务元数据、API规范、架构图、数据库 schema、测试包、文档和映射同步到UiGraph网关。

Mandatory Workflow

强制工作流

Follow this workflow in order. Do not skip steps.

Discover project evidence from the user's request and repository files. Look for existing API specs, route definitions, migrations, database schemas, docs, diagrams, tests, deployment config, and service metadata.
Ask what to generate before writing anything. Ask the user which artifact categories they want: APIs, database schemas, architecture diagrams, docs, test packs, maps, and optional helper scripts.
Propose a final plan after the user selects artifact categories. The plan must list files to create or update, detected project sources, assumptions, validation steps, and any scripts that will be written under
```
.uigraph/scripts/
```
.
Wait for the exact trigger phrase. Do not create or modify
```
.uigraph.yaml
```
,
```
.uigraph/**
```
, or
```
.uigraph/scripts/**
```
until the user says
```
Generate Artifacts Now
```
.
Generate the approved artifacts only after that exact phrase is received. Generate only the files included in the final approved plan.
Validate and reset generated structure after generation. The LLM/agent must inspect the generated files directly and reason through validity. Check that created files are syntactically valid where possible, every
```
.uigraph.yaml
```
path points to an existing file, links are internally consistent, and generated artifacts match the approved structure. Fix only files generated in this execution.

请按顺序遵循以下工作流，不要跳过步骤。

从用户请求和仓库文件中发现项目证据。查找现有的API规范、路由定义、迁移文件、数据库schema、文档、图表、测试、部署配置和服务元数据。
在编写任何内容前询问生成范围。询问用户想要生成哪些类别的工件：API、数据库schema、架构图、文档、测试包、映射，以及可选的辅助脚本。
用户选择工件类别后提出最终方案。方案必须列出要创建或更新的文件、检测到的项目源、假设、验证步骤，以及将在
```
.uigraph/scripts/
```
下编写的所有脚本。
等待确切的触发短语。在用户说出
```
Generate Artifacts Now
```
之前，不得创建或修改
```
.uigraph.yaml
```
、
```
.uigraph/**
```
或
```
.uigraph/scripts/**
```
。
仅在收到确切短语后生成已批准的工件。仅生成最终批准方案中包含的文件。
生成后验证并重置生成结构。LLM/Agent必须直接检查生成的文件并验证其有效性。尽可能检查创建的文件在语法上是否有效，确保
```
.uigraph.yaml
```
中的每个路径都指向现有文件，链接在内部保持一致，且生成的工件与批准的结构匹配。仅修复本次执行中生成的文件。

Hard Approval Gate

严格批准门槛

```
Generate Artifacts Now
```
is the only phrase that authorizes generation.
General requests like "generate artifacts", "create UiGraph files", or "go ahead" are not enough. Ask for the exact phrase before writing artifacts.
Before approval, only inspect files and ask questions. Do not write
```
.uigraph.yaml
```
,
```
.uigraph/**
```
, or project helper scripts.
If there is not enough evidence for an artifact category, say so and propose only artifacts that can be supported by discovered evidence or explicit user input.

```
Generate Artifacts Now
```
是唯一授权生成的短语。
诸如“生成工件”、“创建UiGraph文件”或“继续”之类的一般性请求并不足够。在编写工件前，要求用户提供确切短语。
在获得批准前，仅可检查文件并提出问题。不得编写
```
.uigraph.yaml
```
、
```
.uigraph/**
```
或项目辅助脚本。
如果某个工件类别没有足够的证据支持，请告知用户，并仅提出可由已发现证据或用户明确输入支持的工件。

Repository Layout Convention

仓库布局规范

repo-root/
├── .uigraph.yaml
└── .uigraph/
    ├── scripts/
    ├── openapi/
    ├── graphql/
    ├── grpc/
    ├── diagrams/
    │   └── <diagram-name>/
    │       ├── <name>.mmd
    │       └── context.json
    ├── db/
    └── docs/

Keep all UiGraph artifacts under

.uigraph/

and reference them with relative paths from

.uigraph.yaml

Generated project helper scripts must be written only under

.uigraph/scripts/

. Do not create generated helper scripts in any other project scripts directory.

repo-root/
├── .uigraph.yaml
└── .uigraph/
    ├── scripts/
    ├── openapi/
    ├── graphql/
    ├── grpc/
    ├── diagrams/
    │   └── <diagram-name>/
    │       ├── <name>.mmd
    │       └── context.json
    ├── db/
    └── docs/

所有UiGraph工件都需放在

.uigraph/

目录下，并通过

.uigraph.yaml

中的相对路径引用它们。

生成的项目辅助脚本必须仅写入

.uigraph/scripts/

目录下。不得在其他项目脚本目录中创建生成的辅助脚本。

Repository URL Discovery

仓库URL发现

When generating

.uigraph.yaml

, do not invent or copy placeholder repository URLs. Inspect the current git repository remote first, preferably

origin

Use the discovered remote URL for
```
service.repository.url
```
.
Normalize SSH GitHub/GitLab/Bitbucket remotes to HTTPS when possible.

Set

service.repository.provider

from the remote host:

github

gitlab

, or

bitbucket

If no remote exists, the remote host is unsupported, or multiple plausible remotes conflict, ask the user for the repository URL before generating artifacts.
During validation, confirm
```
service.repository.url
```
matches the detected git remote or an explicit user-provided URL.

生成

.uigraph.yaml

时，不得编造或复制占位符仓库URL。首先检查当前git仓库的远程仓库，优先使用

origin

。

将发现的远程URL用于
```
service.repository.url
```
。
尽可能将SSH协议的GitHub/GitLab/Bitbucket远程仓库转换为HTTPS格式。

根据远程主机设置

service.repository.provider

：

github

、

gitlab

或

bitbucket

。

如果不存在远程仓库、远程主机不受支持，或多个合理的远程仓库存在冲突，请在生成工件前询问用户仓库URL。
在验证过程中，确认
```
service.repository.url
```
与检测到的git远程仓库或用户明确提供的URL匹配。

Optional Helper Scripts

可选辅助脚本

Write helper scripts only when they are useful for the detected project and included in the approved final plan.

Helper scripts must directly generate approved UiGraph artifacts.
Helper scripts must be written only in JavaScript, Python, or Bash (
```
.sh
```
).
Use JavaScript for JavaScript-based projects, Python for Python-based projects, and Bash (
```
.sh
```
) when neither JavaScript nor Python is clearly the project language.
Do not create scripts whose only purpose is exploration, discovery, inspection, inventory, or reporting.
If a script inspects project data, it must also write the approved artifact as its direct output.
Useful generation scripts include generating OpenAPI from known route metadata or generating database schema files from known schema sources.
Prefer checked-in sources over live infrastructure introspection.
Do not run live database dump commands such as
```
pg_dump
```
unless the project clearly supports it and the user explicitly approves that action.
Scripts must be safe by default and must not overwrite unrelated files without confirmation.
Post-generation validation is an LLM/agent responsibility.

仅当辅助脚本对检测到的项目有用且已包含在批准的最终方案中时，才编写这些脚本。

辅助脚本必须直接生成已批准的UiGraph工件。
辅助脚本只能使用JavaScript、Python或Bash（
```
.sh
```
）编写。
基于JavaScript的项目使用JavaScript，基于Python的项目使用Python，当项目语言既不是JavaScript也不是Python时，使用Bash（
```
.sh
```
）。
不得创建仅用于探索、发现、检查、盘点或报告的脚本。
如果脚本检查项目数据，它还必须将已批准的工件作为直接输出写入。
有用的生成脚本包括从已知路由元数据生成OpenAPI，或从已知schema源生成数据库schema文件。
优先使用已提交的源文件，而非实时基础设施内省。
除非项目明确支持且用户明确批准，否则不得运行
```
pg_dump
```
等实时数据库转储命令。
脚本默认必须安全，未经确认不得覆盖无关文件。
生成后验证是LLM/Agent的职责。

Post-Generation Validation

生成后验证

After generating artifacts, the LLM/agent must verify the generated structure before finishing. Do this by reading generated files and checking them against the rules in this skill.

Confirm
```
.uigraph.yaml
```
exists when it was part of the approved plan.

Confirm every

path

contextPath

schemaPath

, and frame

imagePath

referenced by

.uigraph.yaml

exists.

Confirm every
```
databases[*].schemaPath
```
file extension matches the dialect:
```
.sql
```
for SQL dialects (
```
postgres
```
,
```
mysql
```
,
```
sqlite
```
,
```
other
```
when SQL-like) and
```
.json
```
for NoSQL dialects (
```
dynamodb
```
,
```
mongodb
```
).
Confirm
```
service.repository.url
```
matches the detected git remote or an explicit user-provided URL.
Validate YAML and JSON syntax when applicable.
Check OpenAPI, GraphQL, gRPC, SQL, Mermaid, and docs files are structurally plausible when generated.
Check test case and map component references use matching API group names, operation IDs, doc names, test pack names, and architecture diagram names.
Fix only files generated in the current execution. Do not rewrite unrelated user files.

生成工件后，LLM/Agent必须在完成前验证生成的结构。通过读取生成的文件并对照本技能中的规则进行检查。

确认
```
.uigraph.yaml
```
在已批准方案包含它的情况下存在。
确认
```
.uigraph.yaml
```
引用的每个
```
path
```
、
```
contextPath
```
、
```
schemaPath
```
和框架
```
imagePath
```
都存在。
确认每个
```
databases[*].schemaPath
```
文件的扩展名与方言匹配：SQL方言（
```
postgres
```
、
```
mysql
```
、
```
sqlite
```
、类SQL的
```
other
```
）使用
```
.sql
```
，NoSQL方言（
```
dynamodb
```
、
```
mongodb
```
）使用
```
.json
```
。
确认
```
service.repository.url
```
与检测到的git远程仓库或用户明确提供的URL匹配。
适用时验证YAML和JSON语法。
检查生成的OpenAPI、GraphQL、gRPC、SQL、Mermaid和文档文件在结构上是否合理。
检查测试用例和映射组件引用是否使用匹配的API组名称、操作ID、文档名称、测试包名称和架构图名称。
仅修复当前执行中生成的文件。不得重写无关的用户文件。

What the LLM Already Knows vs. What This Skill Provides

LLM已掌握内容 vs 本技能提供内容

You already know how to write:

OpenAPI 3.0/3.1 specs
GraphQL SDL
gRPC proto3
SQL schemas

This skill teaches:

The exact
```
.uigraph.yaml
```
schema and validation rules
How to link artifacts together (test cases → APIs, maps → test cases, etc.)
The
```
context.json
```
format for architecture diagrams
The DynamoDB/MongoDB JSON schema format
Map/Frame/FocalPoint/Component structure
Domain-to-artifact mapping patterns

你已掌握如何编写：

OpenAPI 3.0/3.1规范
GraphQL SDL
gRPC proto3
SQL schema

本技能教授：

```
.uigraph.yaml
```
的确切schema和验证规则
如何将工件关联起来（测试用例→API、映射→测试用例等）
架构图的
```
context.json
```
格式
DynamoDB/MongoDB JSON schema格式
映射/框架/焦点/组件结构
领域到工件的映射模式

Reference Documents

参考文档

File	Purpose
`references/uigraph-yaml-schema.md`	Complete field-by-field schema of `.uigraph.yaml`
`references/validation-rules.md`	All hard constraints, enums, and file-existence checks
`references/architecture-diagrams.md`	Mermaid + context.json specs and node mapping rules
`references/database-schemas.md`	SQL config and NoSQL JSON format
`references/test-packs-and-cases.md`	Test pack and test case structure
`references/maps-frames-focalpoints.md`	Map, Frame, FocalPoint, and Component linking
`references/docs.md`	Documentation artifact specs
`references/ci-cd-integration.md`	Pipeline templates for GitHub Actions, GitLab CI, Bitbucket
`references/domain-mapping-guide.md`	How to map user-described systems to UIGraph artifacts
`references/confirmation-workflow.md`	Required approval gate and final plan format

文件路径	用途
`references/uigraph-yaml-schema.md`	`.uigraph.yaml` 的完整字段级schema说明
`references/validation-rules.md`	所有硬约束、枚举和文件存在性检查规则
`references/architecture-diagrams.md`	Mermaid + context.json规范和节点映射规则
`references/database-schemas.md`	SQL配置和NoSQL JSON格式说明
`references/test-packs-and-cases.md`	测试包和测试用例结构说明
`references/maps-frames-focalpoints.md`	映射、框架、焦点和组件的关联规则
`references/docs.md`	文档工件规范说明
`references/ci-cd-integration.md`	GitHub Actions、GitLab CI、Bitbucket的流水线模板
`references/domain-mapping-guide.md`	如何将用户描述的系统映射到UiGraph工件的指南
`references/confirmation-workflow.md`	必需的批准门槛和最终方案格式说明

Templates

模板

All copy-pasteable templates live in

assets/templates/

所有可复制粘贴的模板都存放在

assets/templates/

目录下。