artrig-storage-example

如何写一个服务于 ArtRig 的 Skill

本目录存放可直接粘贴 / 导入 ArtRig 的 Skill 正文（Markdown）。本文件是写作规范：讲清 Skill 是什么、注入后长什么样、正文该怎么写、哪些坑必须避开。

---

1. Skill 是什么（和风格的区别）

	风格（Style）	Skill
管什么	长什么样：配色、线条、材质、光影等视觉规范	怎么干活：出图流程、质量线、提示词结构、输出格式、何时停下确认
存什么	结构化字段（fields[]），渲染成 name: value 行	自由 Markdown 正文（body）
作用域	仅项目级	项目级 + 全局级
注入头部	[ARTRIG <slug> @style-<id>/v<n>]	项目 [ARTRIG <slug> @skill-<id>/v<n>]；全局 [ARTRIG @global-skill-<id>/v<n>]

一句话：风格定义画风，Skill 定义工作流。两者可以并行注入，正文里不要重复风格已声明的内容。

参考示例：游戏美术.md（跨项目通用的游戏美术出图流程）。

---

2. 存储与文件形态

Git 落位（远端 Gogs）：

projects/<slug>/skills/
├── index.json          ← 元数据（不含 body）
├── k1.md               ← 纯 Markdown 正文
└── k2.md

_global/skills/
├── index.json
└── k1.md

• 一个 Skill = 一个 .md 文件，正文就是文件原文：无 frontmatter、无 JSON 转义、无额外包裹。
• 元数据（id / name / description / version）只存在 index.json，不要写进 .md。
• id 形如 k1、k2…，作用域内唯一且稳定（重命名不变）；id 即文件名，因此必须是文件名安全字符。
• 删除以 index.json 为准：从 index 移除即可，孤儿 .md 不会被加载。

本地缓存与 Git 布局不同（整条含 body 单块 JSON），写 Skill 时无需关心。

---

3. 注入后长什么样

调用 buildSkillPack()（src/core/context-pack.ts）渲染：

[ARTRIG zombie-street @skill-k1/v2]
三视图出图流程
<body 正文原样粘贴>

• 头行 + name + body；
• description 不注入（仅用于面板列表辨识）；
• 头行由扩展自动生成——正文里不要手写 [ARTRIG ...] 行；
• body 紧跟在 name 后面，中间没有任何框架说明。正文第一段必须自我定义：说明「以下就是本次对话的工作流规范」。ChatGPT 网页端没有「Skill」这个概念，不定义就会出现指代歧义（详见 §4.2 第 1 条）；
• 注入通过 MSG.INJECT_CONTEXT 追加到当前对话（空则写、非空追加），一次会话只点一次即可。

---

4. 正文写作规范

4.1 结构

• 用 ## 分节、### 分子节，条目用有序 / 无序列表或表格；避免超过三层的嵌套。
• 结论先行：把「边界 / 不变量 / 红线」放在最前，细则往后排。
• 表格用于「触发条件 → 动作 → 交付物」这类映射，比长段落更易被模型执行。
• 开篇必须先定义自己（见 §4.2 第 1 条）：不要一上来就写「本 Skill 管什么」——读者（模型）还不知道「本 Skill」指什么。

4.2 必须写清楚的几件事

1. 自我定义：正文第一段用一句 blockquote 钉住自指——「以下文本是本次对话必须遵守的工作流规范（下称『本 Skill』）」。ChatGPT 网页端没有 Skill 概念，不定义就可能被误读成工具、插件、上传文件或上一轮内容。
2. 主语明确：条目写「本 Skill 管 / 本 Skill 不管」，不要只写「管 / 不管」。
3. 占位符说明：<id>、<n> 这类尖括号会被模型照抄，必须在正文里点明「均为占位符，实际引用时替换为注入头部出现过真实值」。能直接给具体示例（如 @style-s1/v3）就少用占位符。
4. 边界：本 Skill 管什么、不管什么。画风一律交给 @style，不要在这里定义配色/题材/比例。
5. 优先级：用户当前指令 > 已注入风格 > 本 Skill，冲突时如何处置。
6. 标签规则：只能引用注入头部真实存在的标签（@style-<id>/v<n>、@skill-<id>/v<n>），禁止自造 id / 版本号；不确定就先问。
7. 流程回边：某阶段不满足条件时回到哪一步（不要只写前进方向）。
8. 停下确认的时机：哪些情况必须先问再动手。

4.3 不要做的

• ❌ 不要重复风格内容（配色、线条、材质规范由 @style 负责）。
• ❌ 不要在正文里写 index.json 的字段、version、id 等元数据。
• ❌ 不要写死具体项目的 slug、资产名、风格 id（跨项目通用 Skill 尤其注意）。
• ❌ 不要用未经定义的「本 Skill」自指（如开篇第一行就写「本 Skill 的边界」）。
• ❌ 不要省略主语（「管：…」→ 应为「本 Skill 管：…」）。
• ❌ 不要不加说明地使用 <id> / <n> 等占位符。
• ❌ 不要复述本 Skill 全文或整段 @style；引用标签即可。
• ❌ 不要加 YAML frontmatter（扩展按纯文本处理，不做解析）。

4.4 与 ArtRig 数据模型对齐

若 Skill 涉及回填资产库，正文里的字段名要直接沿用 ArtRig schema（src/core/schema.ts）：

• 资产字段：name / description / keyFeatures / palette / variants / refs / tags
• 版本操作 operation：generate / inpaint / cutout / split / slice / layer
• 资产版本号形如 vN（^v\d+$），final 是打在某个 vN 上的 tag，不覆盖历史。

4.5 长度

头行 + 正文会整体注入对话，越长越占上下文、越容易被模型忽略尾部。建议：

• 目标 100–300 行；
• 表格 / 清单优先，少用长自然段；
• 能不写的解释就不写，把「必须遵守的规则」和「可选的说明」分开。

---

5. 版本契约

操作	version 变化
新建 / 复制	1
修改 body 或 description	+1
重命名（name）	不变
选中 / 注入	不变

即：内容（正文/描述）变才升版本，标识级可追溯，不存内容快照。

---

6. 命名与元数据填写

字段	规范
name	中文短名，trim 后非空；描述功能不描述画风，如「三视图出图流程」
description	一句话，说明适用场景；仅列表可见，不注入
body	本规范第 4 节所述的 Markdown 正文；可为空但不推荐
id	系统生成 k1、k2…；不要手动指定
作用域	只服务单个项目 → 项目级；跨项目复用 → 全局级（_global/skills）

---

7. 提交前自检清单

• 正文没有手写 [ARTRIG ...] 头行，也没有 frontmatter / JSON 转义。
• 第一段已自我定义「本 Skill」（用的是定义句，而非「本 Skill 的边界」）。
• 条目都有明确主语（「本 Skill 管 / 不管」）。
• 占位符 <id> / <n> 都已说明含义，或已换成具体示例。
• 明确写了「管什么 / 不管什么」，画风类内容已交给 @style。
• 写了优先级与冲突处置方式。
• 所有标签引用都来自注入头部，没有自造 id / 版本号。
• 流程有回边，不只写前进。
• 若涉及回填，字段名与 ArtRig schema 一致（keyFeatures / palette / variants / refs / tags / operation）。
• 长度合理（约 100–300 行），表格/清单为主。
• 通读一遍：不依赖任何具体项目上下文也能执行。