create-yss-spec 1.0.0

package/template/.codex/skills/yss-design-system/references/design-system.md

@@ -0,0 +1,225 @@
+# YSS 设计系统执行规范
+
+本文件是 `docs/design/design.md` 的 skill 侧执行清单。项目文档面向团队阅读并作为唯一规范来源，本文件面向 Agent 执行、设计评审和前端实现，不单独承载新的 token 决策。
+
+权威资料：
+
+- 团队规范：`docs/design/design.md`
+- Token 快照：`docs/design/tokens/*`
+- Skill 入口：`.codex/skills/yss-design-system/SKILL.md`
+
+## 设计定位
+
+本项目 UI 默认采用 Ant Design 企业级中后台风格，而不是营销站、品牌官网或概念展示风格。
+
+关键词：
+
+- 数据密集
+- 表单密集
+- 流程密集
+- 可扫描
+- 状态确定
+- 低装饰
+- 组件一致
+
+页面首屏应优先呈现实际业务界面。除非需求明确要求 Landing Page，不要创建营销式 hero、过度装饰、全屏宣传页或卡片堆叠式介绍页。
+
+## 设计原则
+
+| 原则 | 执行要求 |
+| --- | --- |
+| Natural | 使用熟悉的中后台模式，如筛选区、表格、详情抽屉、Modal、Tabs、左树右表 |
+| Certain | 每个操作都有明确状态反馈，加载、错误、权限、只读、冲突不靠猜 |
+| Meaningful | 视觉强调只服务于主操作、状态和层级，不做无意义装饰 |
+| Growing | 支持从简单表单扩展到复杂表格、审批流、控制台和多模块页面 |
+
+## Token 基线
+
+### 颜色
+
+| Token | 值 | 用途 |
+| --- | --- | --- |
+| `colorPrimary` | `#1677ff` | 主操作、链接、焦点、选中态 |
+| `colorPrimaryHover` | `#4096ff` | 主色 hover |
+| `colorPrimaryActive` | `#0958d9` | 主色 active |
+| `colorSuccess` | `#52c41a` | 成功状态 |
+| `colorWarning` | `#faad14` | 警告状态 |
+| `colorError` | `#ff4d4f` | 错误状态 |
+| `colorInfo` | `#1677ff` | 信息提示 |
+| `colorBgLayout` | `#f5f5f5` | 页面背景 |
+| `colorBgContainer` | `#ffffff` | 内容容器 |
+| `colorBgElevated` | `#ffffff` | 浮层容器 |
+| `colorText` | `#2e2e2e` | 主文本 |
+| `colorTextSecondary` | `#646464` | 次级文本 |
+| `colorTextTertiary` | `#949494` | 弱说明 |
+| `colorTextQuaternary` | `#c4c4c4` | placeholder / disabled |
+| `colorBorder` | `#dbdbdb` | 主边框 |
+| `colorBorderSecondary` | `#f1f1f1` | 次级分割线 |
+
+颜色规则：
+
+- 主色只用于主操作、链接、焦点、选中态和激活导航。
+- `success`、`warning`、`error`、`info` 只表达功能状态。
+- 预设色板只用于 Tag、图表、分类可视化，不用于重新定义主操作。
+- 不硬编码白色、灰色、状态色；优先引用 token、CSS variables 或 Ant Design theme。
+
+### 排版
+
+| 层级 | 字号 | 字重 | 用途 |
+| --- | --- | --- | --- |
+| Heading 1 | 38 | 600 | 大标题，慎用 |
+| Heading 2 | 32 | 600 | 页面级标题 |
+| Heading 3 | 26 | 600 | 重要分区 |
+| Heading 4 | 22 | 600 | 分区标题 |
+| Heading 5 | 18 | 600 | 卡片 / 面板标题 |
+| Body | 14 | 400 | 默认正文、控件、表格 |
+| Small | 12 | 400 | 辅助信息、Tag |
+
+排版规则：
+
+- UI 默认正文 14px。
+- UI 字重优先 400 / 600。
+- 不用 700+ 粗体表达选中或激活状态。
+- 选中状态优先使用颜色、边框、下划线、背景表达。
+
+### 间距、尺寸、圆角
+
+| 类型 | 基线 |
+| --- | --- |
+| 间距网格 | 4px |
+| 默认控件高度 | 32px |
+| 小控件高度 | 24px |
+| 大控件高度 | 40px |
+| 默认字号 | 14px |
+| 当前品牌默认圆角 | 8px |
+| 大容器 / 浮层圆角 | 10px |
+
+执行规则：
+
+- 间距使用 4 / 8 / 12 / 16 / 20 / 24 / 32 / 48。
+- 表单、筛选区、工具栏、表格、详情页使用密集但有节奏的布局。
+- 控件圆角不得明显大于容器圆角。
+- 不使用任意 magic number；确需新增尺寸时，先说明为什么 token 不够。
+
+### 动效
+
+| Token | 值 | 用途 |
+| --- | --- | --- |
+| `motionDurationFast` | `0.1s` | hover、focus、press |
+| `motionDurationMid` | `0.2s` | 折叠、淡入淡出、控件内部状态 |
+| `motionDurationSlow` | `0.3s` | Modal、Drawer、页面级浮层 |
+
+动效只服务于状态反馈、层级变化和空间关系。不自造 easing。
+
+## 组件规则
+
+| 组件 | 规则 |
+| --- | --- |
+| Button Primary | 每个决策区域只保留一个主按钮 |
+| Button Default | 次级动作默认使用默认按钮或描边按钮 |
+| Input / Select | 默认高度 32px，focus 可见 |
+| Card | 只用于真实内容容器，不做卡片套卡片 |
+| Modal | 用于阻断式决策和关键表单 |
+| Drawer | 用于详情、编辑、辅助流程，不打断主列表上下文 |
+| Menu | 选中态使用淡蓝背景和主色文本 |
+| Tabs | 激活态使用主色文本和下划线，不加背景块 |
+| Table | 表头浅表面色 + 600 字重；hover 再强调行 |
+| Tag | 表达分类，不表达关键阻断状态 |
+| Alert | 表达成功、警告、错误、信息等语义反馈 |
+| Badge | 只做紧凑状态提示，不能替代文本 |
+| Tooltip | 只提供补充解释，不承载关键业务信息 |
+
+## 页面规则
+
+- 后台页面优先使用：Header / 查询区 / 工具栏 / 表格 / 详情抽屉 / 弹窗。
+- 主从关系优先使用：左树右表、列表 + 详情、Tabs + 分区。
+- 表格密集场景优先保证列可读、操作稳定、横向滚动受控。
+- 筛选区要支持重置、提交、默认值和窄屏重排。
+- 空态要说明下一步，不只显示“暂无数据”。
+- 无权限态要说明权限缺失，不假装是空数据。
+
+## 状态矩阵
+
+设计、原型或实现至少考虑：
+
+- loading
+- empty
+- error
+- readonly
+- disabled
+- no-permission
+- conflict
+- dirty / unsaved
+- success
+
+关键业务流还要补充：
+
+- optimistic update
+- idempotency
+- concurrent modification
+- partial success
+- retryable failure
+- audit-visible action
+
+## 响应式验收
+
+核心视口：
+
+| 名称 | 尺寸 |
+| --- | --- |
+| mobile compact | 360 × 800 |
+| mobile standard | 390 × 844 |
+| mobile large | 430 × 932 |
+| foldable / small tablet | 600 × 960 |
+| tablet portrait | 820 × 1180 |
+| tablet landscape | 1024 × 768 |
+| laptop | 1366 × 768 |
+| desktop | 1440 × 900 |
+| wide desktop | 1920 × 1080 |
+
+验收规则：
+
+- 页面整体不出现意外横向滚动。
+- 表格横向滚动必须限定在表格容器内。
+- 工具栏、筛选区、批量操作区在窄屏下重排或折叠。
+- 长文本、按钮、标签、表头、弹窗内容不得溢出。
+- 移动端表格需要说明替代形态，如卡片列表、关键列优先或详情抽屉。
+
+## 前端落地
+
+React + Ant Design：
+
+- 使用 `ConfigProvider` 注入主题。
+- 优先通过 token、component token、CSS variables、theme algorithm 实现样式。
+- 静态反馈 API 使用 `App`、hook API 或 context holder，避免主题上下文丢失。
+- 暗色模式使用 `darkAlgorithm` 或 `variables.dark.css`。
+- 紧凑模式使用 `compactAlgorithm` 或 `tokens.compact.json`。
+
+YSS UI / Vue：
+
+- 业务页面优先走 `yss-ui` 和 `yss-page-module-development`。
+- 表单使用 `YssFormily` schema。
+- 表格使用 `YTable`，列定义使用项目约定字段。
+- 高度自适应使用 `useTableHeight` / `useTreeHeight`。
+- 请求、分页、筛选参数下沉到 Hook。
+
+## 评审清单
+
+设计评审时检查：
+
+- 是否引用 `docs/design/design.md`。
+- 是否符合中后台定位。
+- 页面清单、主路径、异常路径是否清楚。
+- 状态矩阵是否完整。
+- 组件选择是否复用 YSS UI / Ant Design。
+- API 反推字段、筛选、分页、动作、错误、权限是否完整。
+- 主操作是否唯一，次级操作是否降级。
+- 响应式断点和窄屏替代形态是否清楚。
+
+实现评审时检查：
+
+- 是否消费 token，而不是硬编码颜色和尺寸。
+- 是否保持默认 14px 正文、32px 控件、4px 间距网格。
+- 是否保留 hover、focus、active、disabled、loading、empty、error 状态。
+- 是否存在卡片套卡片、营销式 hero、装饰性渐变或无意义插画。
+- 是否存在横向溢出、文本遮挡或按钮文字溢出。

package/template/.codex/skills/yss-design-system/scripts/validate-frontmatter.py

@@ -0,0 +1,50 @@
+#!/usr/bin/env python3
+"""Validate the yss-design-system skill frontmatter without third-party deps."""
+
+from pathlib import Path
+import re
+import sys
+
+
+ROOT = Path(__file__).resolve().parents[1]
+SKILL = ROOT / "SKILL.md"
+
+
+def main() -> int:
+    text = SKILL.read_text(encoding="utf-8")
+    match = re.match(r"^---\n(.*?)\n---", text, re.DOTALL)
+    if not match:
+        print("Invalid SKILL.md frontmatter block", file=sys.stderr)
+        return 1
+
+    fields: dict[str, str] = {}
+    for line in match.group(1).splitlines():
+        if not line.strip():
+            continue
+        key, sep, value = line.partition(":")
+        if not sep:
+            print(f"Invalid frontmatter line: {line}", file=sys.stderr)
+            return 1
+        fields[key.strip()] = value.strip()
+
+    expected = {"name", "description"}
+    if set(fields) != expected:
+        print(f"Expected keys {sorted(expected)}, got {sorted(fields)}", file=sys.stderr)
+        return 1
+
+    name = fields["name"]
+    if not re.match(r"^[a-z0-9-]+$", name):
+        print(f"Invalid skill name: {name}", file=sys.stderr)
+        return 1
+
+    description = fields["description"]
+    if not description or len(description) > 1024:
+        print("Description must be present and <= 1024 chars", file=sys.stderr)
+        return 1
+
+    print(f"{name} frontmatter ok")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/template/.codex/skills/yss-dictionary/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: yss-dictionary
+description: 用于 YSS 字典组件接入、字典缓存、字典管理接口、字典 Feign 客户端和 EnableDicManage 排障。当用户提到字典、Dic、DicCache、YssDicFeign、EnableDicManage、字典导入模板或字典不刷新时调用。
+---
+
+# yss-dictionary
+
+Use this skill for YSS 字典组件. Keep implementation grounded in the local project and resolvable YSS backend component source.
+
+中文说明：本技能用于 YSS 字典组件。执行时优先读取源码索引，避免凭记忆猜类名、配置项或接入方式。
+
+## Source Index First
+
+- Backend source location is environment-specific; resolve it with `yss-source-index/references/source-location.md`.
+- Generated index: `references/source-index.md`
+- Component path hints: `yss-microservice-components/yss-component-dictionary-parent`
+
+Read `references/source-index.md` as a path-hint index whenever the task depends on exact modules, annotations, auto configuration, properties, controllers, clients, repositories, DTOs, handlers, or troubleshooting.
+
+## Workflow
+
+1. Identify whether the task is dictionary management, query/cache usage, Feign client integration, import/export template, or cache refresh troubleshooting.
+2. Read `references/source-index.md`, then inspect the matching module: dictionary, client, feign, or starter.
+3. For management endpoints, start with `DicController`, `DicQueryController`, `DicService`, and repositories.
+4. For consumers, prefer `YssDicFeign`, `DicCacheHolder`, and `DicCacheAutoConfiguration` instead of duplicating dictionary queries.
+5. For service-side enablement, check `EnableDicManage`, `EnableDicManageImportSelector`, and `DefaultDicConfiguration`.
+6. For import/export tasks, inspect `DicExcelTemplate` and `DicExcelImportTemplate`.
+
+## Capability Split
+
+- `yss-component-dictionary`: controllers, services, gateways, repositories, entities.
+- `yss-component-dictionary-client`: command/query DTOs and VO contracts.
+- `yss-component-dictionary-feign`: Feign client, cache holder, cache scheduler, service-name properties.
+- `yss-component-dictionary-starter`: `EnableDicManage` and default configuration.
+
+## Checklist
+
+- Required dependency or starter module is present.
+- Management service has `EnableDicManage` where required.
+- Consumer service points to the correct dictionary service name.
+- Cache refresh/scheduler behavior is checked when values are stale.
+- DTO/VO contracts from client module are reused.
+- Import/export template changes preserve existing Excel field mapping.
+
+## Do Not
+
+- Do not invent class names or configuration keys without checking the source index.
+- Do not replace component extension points with business-local framework code.
+- Do not broaden the task into unrelated YSS components unless the user asks.

package/template/.codex/skills/yss-dictionary/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "yss-dictionary"
+  short_description: "YSS component skill for yss-dictionary"
+  default_prompt: "Use yss-dictionary for this YSS backend component task."

package/template/.codex/skills/yss-dictionary/references/source-index.md

@@ -0,0 +1,78 @@
+# yss-dictionary Source Index
+
+Generated: 2026-06-29T16:11:14+00:00
+Indexed source root: resolved at refresh time; set `YSS_SOURCE_ROOT` to reproduce or refresh.
+
+This file is generated by `yss-source-index/scripts/refresh-yss-skill-index.py`. Do not hand-edit generated sections.
+
+Paths below are source path hints captured at refresh time. If they do not exist in the current workspace, locate sources using `YSS_SOURCE_ROOT`, CodeGraph, package/class names, Maven artifact names, or repository search before assuming the source is unavailable.
+
+## Component Path Hints
+
+- `yss-microservice-components/yss-component-dictionary-parent` (existed when indexed)
+
+## Documentation Files
+
+- No component documentation files found.
+
+## Maven Modules
+
+- `yss-microservice-components/yss-component-dictionary-parent`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary-client`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary-feign`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary-starter`
+
+## Key Java Entry Points
+
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/config/DicExcelImportTemplate.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/config/DicExcelTemplate.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/config/MybatisDicConfiguration.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/controller/DicController.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/controller/DicQueryController.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/convertor/Audit2AddMapping.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/convertor/Audit2EditMapping.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/convertor/DicBasicConvertor.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/convertor/DicClassConvertor.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/entity/AuditableEntity.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/entity/DicBasicEntity.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/entity/DicClassEntity.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/entity/DicSystemEntity.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/gateway/DicQueryGateway.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/gateway/impl/DicQueryGatewayImpl.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/repository/DicBasicRepository.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/repository/DicClassRepository.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/repository/DicSystemRepository.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/scheduler/DicCacheScheduler.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/service/DicService.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/service/impl/DicServiceImpl.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary-client/src/main/java/com/yss/cloud/dic/dto/cmd/DicAddCmd.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary-client/src/main/java/com/yss/cloud/dic/dto/cmd/DicBasicAddCmd.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary-client/src/main/java/com/yss/cloud/dic/dto/cmd/DicClassAddCmd.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary-client/src/main/java/com/yss/cloud/dic/dto/cmd/DicClassEditCmd.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary-client/src/main/java/com/yss/cloud/dic/dto/cmd/DicEditCmd.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary-client/src/main/java/com/yss/cloud/dic/dto/cmd/DicExportCmd.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary-client/src/main/java/com/yss/cloud/dic/dto/cmd/DicSystemAddCmd.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary-client/src/main/java/com/yss/cloud/dic/dto/cmd/DicSystemEditCmd.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary-client/src/main/java/com/yss/cloud/dic/dto/query/ClassInfoQuery.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary-client/src/main/java/com/yss/cloud/dic/dto/query/DicBasicQuery.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary-client/src/main/java/com/yss/cloud/dic/dto/query/DicClassQuery.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary-client/src/main/java/com/yss/cloud/dic/vo/DicBasicVO.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary-client/src/main/java/com/yss/cloud/dic/vo/DicClassInfoVO.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary-client/src/main/java/com/yss/cloud/dic/vo/DicClassVO.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary-client/src/main/java/com/yss/cloud/dic/vo/DicDetailVO.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary-client/src/main/java/com/yss/cloud/dic/vo/DicSystemVO.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary-feign/src/main/java/com/yss/cloud/dic/DicAppServiceNameProperties.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary-feign/src/main/java/com/yss/cloud/dic/DicCacheAutoConfiguration.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary-feign/src/main/java/com/yss/cloud/dic/DicCacheHolder.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary-feign/src/main/java/com/yss/cloud/dic/feign/YssDicFeign.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary-feign/src/main/java/com/yss/cloud/dic/scheduler/DicCacheScheduler.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary-starter/src/main/java/com/yss/cloud/dic/EnableDicManage.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary-starter/src/main/java/com/yss/cloud/dic/EnableDicManageImportSelector.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary-starter/src/main/java/com/yss/cloud/dic/config/DefaultDicConfiguration.java`
+
+## Recommended Next Reads
+
+- Start with the documentation files above when learning component usage.
+- Search the key Java entry points for annotations, auto configuration, properties, aspects, interceptors, handlers, and result objects before changing application code.
+- Prefer existing component extension points over rewriting framework logic in business modules.

package/template/.codex/skills/yss-dir/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: yss-dir
+description: 用于 YSS 目录/标准目录组件接入、目录树、目录资源、EnableDirManage、StandardDir、StandardDirResource、目录权限或目录缓存排障。
+---
+
+# yss-dir
+
+Use this skill for YSS 目录组件. Keep implementation grounded in the local project and resolvable YSS backend component source.
+
+中文说明：本技能用于 YSS 目录组件。执行时优先读取源码索引，避免凭记忆猜类名、配置项或接入方式。
+
+## Source Index First
+
+- Backend source location is environment-specific; resolve it with `yss-source-index/references/source-location.md`.
+- Generated index: `references/source-index.md`
+- Component path hints: `yss-microservice-components/yss-component-dir-parent`
+
+Read `references/source-index.md` as a path-hint index whenever the task depends on exact modules, annotations, auto configuration, properties, controllers, clients, repositories, DTOs, handlers, or troubleshooting.
+
+## Workflow
+
+1. Identify whether the task is standard directory CRUD, directory tree query, resource binding, repeat-checking, starter enablement, or permission/context troubleshooting.
+2. Read `references/source-index.md`, then inspect `StandardTreeDirController`, `StandardDirService`, `StandardDirResourceService`, and repositories.
+3. For model changes, separate `StandardDir` from `StandardDirResource`; resource binding should not be collapsed into directory metadata.
+4. For integration enablement, check `EnableDirManage`, `DefaultDirConfiguration`, and `DefaultDirProperties`.
+5. For client contracts, reuse `StandardDirAddCmd`, `StandardDirUpdateCmd`, `StandardDirResourceAddCmd`, `StandardDirQuery`, and VO classes.
+
+## Capability Split
+
+- `yss-component-dir`: service/controller/repository implementation for standard directory and resource relation.
+- `yss-component-dir-client`: command/query DTOs and VO contracts.
+- `yss-component-dir-common`: shared enums/tree utilities such as `DmStatus` and `LoginUtil`.
+- `yss-component-dir-starter`: `EnableDirManage` and default configuration/properties.
+
+## Checklist
+
+- Required dependency or starter module is present.
+- Directory tree and resource relation are handled through the correct service.
+- Repeat checks use existing query/logic instead of ad-hoc duplicate detection.
+- Auto ID behavior is checked before adding manual ID assignment.
+- Status handling follows the common enum/model already present.
+- Starter properties match the target service name and deployment.
+
+## Do Not
+
+- Do not invent class names or configuration keys without checking the source index.
+- Do not replace component extension points with business-local framework code.
+- Do not broaden the task into unrelated YSS components unless the user asks.

package/template/.codex/skills/yss-dir/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "yss-dir"
+  short_description: "YSS component skill for yss-dir"
+  default_prompt: "Use yss-dir for this YSS backend component task."

package/template/.codex/skills/yss-dir/references/source-index.md

@@ -0,0 +1,64 @@
+# yss-dir Source Index
+
+Generated: 2026-06-29T16:11:14+00:00
+Indexed source root: resolved at refresh time; set `YSS_SOURCE_ROOT` to reproduce or refresh.
+
+This file is generated by `yss-source-index/scripts/refresh-yss-skill-index.py`. Do not hand-edit generated sections.
+
+Paths below are source path hints captured at refresh time. If they do not exist in the current workspace, locate sources using `YSS_SOURCE_ROOT`, CodeGraph, package/class names, Maven artifact names, or repository search before assuming the source is unavailable.
+
+## Component Path Hints
+
+- `yss-microservice-components/yss-component-dir-parent` (existed when indexed)
+
+## Documentation Files
+
+- No component documentation files found.
+
+## Maven Modules
+
+- `yss-microservice-components/yss-component-dir-parent`
+- `yss-microservice-components/yss-component-dir-parent/yss-component-dir`
+- `yss-microservice-components/yss-component-dir-parent/yss-component-dir-client`
+- `yss-microservice-components/yss-component-dir-parent/yss-component-dir-common`
+- `yss-microservice-components/yss-component-dir-parent/yss-component-dir-starter`
+
+## Key Java Entry Points
+
+- `yss-microservice-components/yss-component-dir-parent/yss-component-dir/src/main/java/com/yss/cloud/dir/config/DirAppServiceNameProperties.java`
+- `yss-microservice-components/yss-component-dir-parent/yss-component-dir/src/main/java/com/yss/cloud/dir/config/MybatisDirConfiguration.java`
+- `yss-microservice-components/yss-component-dir-parent/yss-component-dir/src/main/java/com/yss/cloud/dir/convertor/Audit2AddMapping.java`
+- `yss-microservice-components/yss-component-dir-parent/yss-component-dir/src/main/java/com/yss/cloud/dir/convertor/Audit2EditMapping.java`
+- `yss-microservice-components/yss-component-dir-parent/yss-component-dir/src/main/java/com/yss/cloud/dir/convertor/StandardDirConvertor.java`
+- `yss-microservice-components/yss-component-dir-parent/yss-component-dir/src/main/java/com/yss/cloud/dir/convertor/StandardDirResourceConvertor.java`
+- `yss-microservice-components/yss-component-dir-parent/yss-component-dir/src/main/java/com/yss/cloud/dir/entity/AuditableEntity.java`
+- `yss-microservice-components/yss-component-dir-parent/yss-component-dir/src/main/java/com/yss/cloud/dir/entity/StandardDir.java`
+- `yss-microservice-components/yss-component-dir-parent/yss-component-dir/src/main/java/com/yss/cloud/dir/entity/StandardDirResource.java`
+- `yss-microservice-components/yss-component-dir-parent/yss-component-dir/src/main/java/com/yss/cloud/dir/repository/StandardDirRepository.java`
+- `yss-microservice-components/yss-component-dir-parent/yss-component-dir/src/main/java/com/yss/cloud/dir/repository/StandardDirResourceRepository.java`
+- `yss-microservice-components/yss-component-dir-parent/yss-component-dir/src/main/java/com/yss/cloud/dir/rest/StandardTreeDirController.java`
+- `yss-microservice-components/yss-component-dir-parent/yss-component-dir/src/main/java/com/yss/cloud/dir/service/StandardDirResourceService.java`
+- `yss-microservice-components/yss-component-dir-parent/yss-component-dir/src/main/java/com/yss/cloud/dir/service/StandardDirService.java`
+- `yss-microservice-components/yss-component-dir-parent/yss-component-dir/src/main/java/com/yss/cloud/dir/service/impl/StandardDirResourceServiceImpl.java`
+- `yss-microservice-components/yss-component-dir-parent/yss-component-dir/src/main/java/com/yss/cloud/dir/service/impl/StandardDirServiceImpl.java`
+- `yss-microservice-components/yss-component-dir-parent/yss-component-dir/src/main/java/com/yss/cloud/dir/util/AutoIdUtil.java`
+- `yss-microservice-components/yss-component-dir-parent/yss-component-dir-client/src/main/java/com/yss/cloud/dir/dto/cmd/StandardDirAddCmd.java`
+- `yss-microservice-components/yss-component-dir-parent/yss-component-dir-client/src/main/java/com/yss/cloud/dir/dto/cmd/StandardDirResourceAddCmd.java`
+- `yss-microservice-components/yss-component-dir-parent/yss-component-dir-client/src/main/java/com/yss/cloud/dir/dto/cmd/StandardDirResourceDelCmd.java`
+- `yss-microservice-components/yss-component-dir-parent/yss-component-dir-client/src/main/java/com/yss/cloud/dir/dto/cmd/StandardDirUpdateCmd.java`
+- `yss-microservice-components/yss-component-dir-parent/yss-component-dir-client/src/main/java/com/yss/cloud/dir/dto/query/StandardDirQuery.java`
+- `yss-microservice-components/yss-component-dir-parent/yss-component-dir-client/src/main/java/com/yss/cloud/dir/dto/query/StandardDirRepeatQuery.java`
+- `yss-microservice-components/yss-component-dir-parent/yss-component-dir-client/src/main/java/com/yss/cloud/dir/vo/StandardDirResourceVO.java`
+- `yss-microservice-components/yss-component-dir-parent/yss-component-dir-client/src/main/java/com/yss/cloud/dir/vo/StandardDirVO.java`
+- `yss-microservice-components/yss-component-dir-parent/yss-component-dir-common/src/main/java/com/yss/cloud/dir/enums/DmStatus.java`
+- `yss-microservice-components/yss-component-dir-parent/yss-component-dir-common/src/main/java/com/yss/cloud/dir/tree/LoginUtil.java`
+- `yss-microservice-components/yss-component-dir-parent/yss-component-dir-starter/src/main/java/com/yss/cloud/dir/EnableDirManage.java`
+- `yss-microservice-components/yss-component-dir-parent/yss-component-dir-starter/src/main/java/com/yss/cloud/dir/EnableDirManageImportSelector.java`
+- `yss-microservice-components/yss-component-dir-parent/yss-component-dir-starter/src/main/java/com/yss/cloud/dir/config/DefaultDirConfiguration.java`
+- `yss-microservice-components/yss-component-dir-parent/yss-component-dir-starter/src/main/java/com/yss/cloud/dir/config/DefaultDirProperties.java`
+
+## Recommended Next Reads
+
+- Start with the documentation files above when learning component usage.
+- Search the key Java entry points for annotations, auto configuration, properties, aspects, interceptors, handlers, and result objects before changing application code.
+- Prefer existing component extension points over rewriting framework logic in business modules.

package/template/.codex/skills/yss-distributed-id/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: yss-distributed-id
+description: 用于 YSS 分布式 ID 组件的接入与排障。当用户提到 Leaf、CosId、号段模式、雪花算法、AutoIdInterceptor、MyBatis 自动注入 ID 或主键生成策略时调用。
+---
+
+# yss-distributed-id
+
+用于处理 `yss-component-distributed-id` 的配置、接入和问题定位。
+
+## 何时使用
+
+- 用户要启用分布式 ID。
+- 用户提到 Leaf Segment、Snowflake、CosId、UUID。
+- 用户反馈批量插入未自动注入 ID、ID 冲突、ID 类型不匹配。
+
+## 工作方式
+
+1. 先识别项目用的是哪种 ID 策略。
+2. 涉及真实类名、配置项、Leaf 服务或批量插入排障时，先读 `references/source-index.md`，再定位源码或文档。
+3. 再看实体注解、拦截器配置和底层表或注册中心依赖是否齐全。
+4. 修改时优先保持现有策略，不轻易切换算法。
+
+## 源码索引
+
+- 源码位置不要假设固定目录；先按 `yss-source-index/references/source-location.md` 定位。
+- 当前技能索引：`references/source-index.md`
+- 重点源码入口通常包括 `EnableDistributedId`、`AutoIdInterceptor`、Leaf 配置、Leaf REST/Feign/gRPC 模块、ID 策略相关类。
+
+当组件源码变化后，用 `yss-source-index` 刷新索引；刷新或读取前先按源码定位策略确认真实位置。
+
+## 检查清单
+
+- 启动类是否启用了分布式 ID 能力。
+- 当前策略是否与部署条件匹配。
+- 批量插入链路是否会经过拦截器。
+- 实体主键类型与生成策略是否兼容。
+- Leaf Segment 场景下 `leaf_alloc` 是否已初始化。
+- MyBatis/MyBatis-Plus 的插入方法是否绕过了自动 ID 拦截逻辑。
+- 多服务共享号段时，业务 tag/key 是否唯一且稳定。
+
+## 策略建议
+
+- 追求稳定和趋势递增时，优先 Leaf Segment。
+- 依赖 ZooKeeper 且要求高吞吐时，可考虑 Snowflake。
+- 若项目已有 CosId 统一方案，沿用现有生态。
+- 除非业务明确允许，否则不要把 Long 主键切到 String UUID。
+
+## 修改约束
+
+- 不要混用多种主键生成策略而不说明边界。
+- 不要仅改实体注解而忽略底层配置和依赖。
+- 如果用户只是在做普通 MyBatis-Plus 主键配置，不要过度引入新组件。
+- 不要在已有 Long 主键生态里随意改成 String UUID，除非调用方和数据库约束都确认兼容。
+
+## 排障顺序
+
+1. 确认启用注解和 starter 依赖。
+2. 确认实体主键类型、注解和插入方法。
+3. 确认拦截器是否参与 MyBatis 调用链。
+4. Leaf 场景确认服务、号段表和业务 key。
+5. Snowflake/CosId 场景确认机器号、时钟、注册中心或 worker 分配。
+6. 批量插入失败时确认是否调用了项目推荐批量方法。
+
+## 按需读取
+
+- 源码索引：`references/source-index.md`
+- 拦截器与自动注入：`assets/AutoIdInterceptor.java`
+- 启用注解：`assets/EnableDistributedId.java`
+- Leaf 配置相关：`assets/LeafConf.java`

package/template/.codex/skills/yss-distributed-id/agents/openai.yaml

@@ -0,0 +1,5 @@
+version: 1
+interface:
+  display_name: "YSS Distributed ID"
+  short_description: "Leaf、CosId 与分布式 ID 接入与配置规范"
+  default_prompt: "Use $yss-distributed-id to configure or debug distributed ID generation, Leaf, CosId, and MyBatis ID injection."