create-yss-spec 2.1.15 → 2.2.1

package/template/.qoder/skills/formily-mode-slot-detail/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: formily-mode-slot-detail
+description: 指导 YFormily 新增、编辑、查看三态与插槽渲染；当配置 mode 0/1/2、查看态只读、详情页 Descriptions 展示、detail-options、Schema Slot 或详情字段插槽时使用。
+---
+
+# Formily Mode Slot Detail Skill
+
+## 触发条件
+
+- 需要 `mode: 0/1/2` 的新增、编辑、查看三态切换。
+- 查看态需要 Descriptions 响应式渲染或 `detail-*` 字段插槽。
+- 同一字段在编辑态使用 Schema Slot、查看态使用 detail slot。
+
+## 不适用场景
+
+- 基础表单骨架：使用 `../formily-foundation/SKILL.md`。
+- 复杂联动与副作用：使用 `../formily-linkage-effects/SKILL.md`。
+- 分步流程：使用 `../formily-step-flow/SKILL.md`。
+
+## 文档检索
+
+1. 当前会话可用 yss-ui MCP 时，先用 `get_component_docs` 查询 `YFormily` 的 `mode`、`detail-options`、Slots 和 Methods；实现三态、详情插槽或 Schema Slot 时，再用 `get_demo` 获取 `formily/modes`、`formily/group`、`formily/slot` 等官方 Demo。
+2. MCP 查询未命中时先用 `search_docs/list_components` 校正名称；MCP 不可用、调用失败或校正后仍无结果时，才读取最新 `llms-full.txt`。若文档与当前项目依赖版本不一致，用当前源码和导出核验。
+
+## 硬约束（禁止/必须）
+
+- mode 语义固定：`0=新增`、`1=编辑`、`2=查看`；默认值为 `0`。
+- `mode=2` 直接进入 Descriptions 查看态并强制 readPretty；源码没有 `detail-as` 等额外详情开关，禁止生成旧式 prop。
+- 描述列表配置使用 `:detail-options`。默认 `responsive=true`，此时 `columns` 被忽略；响应式列数使用 `maxColumns`、`minColumns`、`minWidth`，固定列数才组合 `responsive: false` 与 `columns`。
+- 查看态插槽命名固定为 `#detail-<path>`，字段路径中的 `.` 替换为 `-`；作用域为 `{ value, item, values }`。
+- 编辑态插槽使用 `x-component: 'Slot'` 与 `x-component-props.name`；`value/onChange` 默认提供，仅在需要 `field` 或整表数据时配置 `params`。
+- 运行时切换 mode 时加 `:key="mode"`，确保当前实现重新创建 form/schema 上下文并避免状态残留。
+- 查看态不会发送 `update:modelValue`；回填优先在渲染前准备好 `v-model`/`initial-values`，或通过已公开的 `setValues` 更新。
+- 只使用公开实例方法：`getValues`、`setValues`、`submit`、`setFieldState`、`toggle/expand/collapse`；禁止编造 `validate/reset/clearValidate`。
+- 加载详情的 Orval API 错误已由 `mutator.ts` 统一 `message.error` 并 reject，业务 `else`/`catch` 禁止重复提示。
+- 分步需求默认走 `formily-step-flow`，不在本 skill 中给 `FormStep` 默认方案。
+
+## 标准代码骨架
+
+```vue
+<script setup lang="ts">
+import { YMonaco, YFormily, type ISchema } from '@yss-ui/components';
+import { ref } from 'vue';
+
+/** YFormily 业务模式。 */
+type FormMode = 0 | 1 | 2;
+
+/** 当前表单模式。 */
+const mode = ref<FormMode>(0);
+
+/** 编辑和查看回填值。 */
+const initialValues = {
+  user: { email: 'user@example.com' },
+  sql: 'select * from users',
+};
+
+/** 编辑与详情共用的 Schema。 */
+const schema: ISchema = {
+  type: 'object',
+  properties: {
+    layout: {
+      type: 'void',
+      'x-component': 'FormLayout',
+      'x-component-props': { layout: 'horizontal', labelWidth: 120, labelAlign: 'right' },
+      properties: {
+        grid: {
+          type: 'void',
+          'x-component': 'FormGrid',
+          'x-component-props': { maxColumns: 2, minColumns: 1, minWidth: 320 },
+          properties: {
+            user: {
+              type: 'object',
+              properties: {
+                email: {
+                  type: 'string',
+                  title: '邮箱',
+                  'x-decorator': 'FormItem',
+                  'x-component': 'Input',
+                },
+              },
+            },
+            sql: {
+              type: 'string',
+              title: 'SQL',
+              'x-decorator': 'FormItem',
+              'x-decorator-props': { gridSpan: 2 },
+              'x-component': 'Slot',
+              'x-component-props': { name: 'sql' },
+            },
+          },
+        },
+      },
+    },
+  },
+};
+</script>
+
+<template>
+  <YFormily
+    :key="mode"
+    :schema="schema"
+    :initial-values="initialValues"
+    :mode="mode"
+    :detail-options="{ bordered: true, maxColumns: 3, minColumns: 1, minWidth: 260 }"
+  >
+    <template #sql="{ value, onChange }">
+      <YMonaco :model-value="value" language="sql" @change="onChange" />
+    </template>
+
+    <template #detail-user-email="{ value }">
+      <a :href="`mailto:${value}`">{{ value }}</a>
+    </template>
+
+    <template #detail-sql="{ value }">
+      <YMonaco :model-value="value" language="sql" readonly />
+    </template>
+  </YFormily>
+</template>
+```
+
+## 交付检查清单
+
+- [ ] mode 语义和默认值正确，运行时切换配置了 `:key="mode"`。
+- [ ] 未生成 `detail-as`、旧式详情开关或虚构实例方法。
+- [ ] `detail-options` 已区分响应式 `maxColumns` 与固定列 `columns`。
+- [ ] 查看态插槽路径映射正确，作用域只使用 `{ value, item, values }`。
+- [ ] 编辑 Slot 名称与模板插槽一致，只在需要时声明 `params`。
+- [ ] 查看回填在进入 `mode=2` 前准备完毕，未依赖查看态 v-model 回写。
+- [ ] API 失败只由 `mutator.ts` 统一提示，业务 `else`/`catch` 未重复 `message.error`。
+- [ ] 无分步 `FormStep` 默认实现。
+
+## 失败兜底策略
+
+- 查看态插槽不生效时，先按详情收集后的数据路径核对 `detail-<path>`，不要把 `FormLayout/FormGrid` 容器名拼入路径。
+- 编辑态插槽不生效时，核对 `x-component-props.name` 与模板名；需要整表值时再加入 `params: ['$values']`。
+- 模式切换错乱时先确认 `:key="mode"`，再检查回填数据是否在新实例挂载前准备好。
+- API 调用 reject 时只恢复 loading 或保留原数据，不重复弹出错误提示。

package/template/.qoder/skills/formily-step-flow/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: formily-step-flow
+description: 指导 YSS UI 分步表单与流程录入；当需要 Ant Design Vue Steps、多 YFormily 独立校验、跨步数据保留、确认预览或最终聚合提交时使用。
+---
+
+# Formily Step Flow Skill
+
+## 触发条件
+
+- 需求是分步表单（Step Form）或流程化录入。
+- 每一步需要独立校验与前进/后退控制。
+- 需要跨步数据聚合、确认预览和最终提交编排。
+
+## 不适用场景
+
+- 普通单页表单：使用 `../formily-foundation/SKILL.md`。
+- 仅字段联动：使用 `../formily-linkage-effects/SKILL.md`。
+- 仅查看态插槽：使用 `../formily-mode-slot-detail/SKILL.md`。
+
+## 文档检索
+
+1. 当前会话可用 yss-ui MCP 时，先用 `get_component_docs` 查询 `YFormily` 的 `submit()`、`mode`、`v-model` 和回填边界，再用 `get_demo` 获取 `formily/steps` 官方 Demo；`Steps` 的属性以当前 `ant-design-vue` 依赖和类型为准。
+2. MCP 查询未命中时先用 `search_docs/list_components` 校正名称；MCP 不可用、调用失败或校正后仍无结果时，才读取最新 `llms-full.txt`。若文档与当前项目依赖版本不一致，用当前源码和导出核验。
+
+## 硬约束（禁止/必须）
+
+- 默认方案使用 `ant-design-vue` 的 `Steps` + 多 schema / 多 `YFormily`；组件库没有 `YSteps`，禁止编造。
+- 业务层禁止把 `@formily/antdv FormStep` 作为默认方案；只有维护旧代码或用户明确指定时才可使用。
+- 每次前进前对当前 YFormily 实例执行 `submit()`；该方法校验成功后 resolve，失败时 reject，不返回布尔值，禁止写 `ok !== false`。
+- 每步使用独立 `v-model` 数据，并以单一 `reactive` 对象聚合；`v-if` 卸载实例后仍由该数据源保留回填值。
+- 确认步骤用前面步骤的聚合数据作为 `initial-values`/`v-model`，禁止绑定一个空的第三步对象导致详情无数据。
+- 最终 API 提交只聚合业务步骤，禁止把纯确认步骤当作新数据源。
+- Orval API 的网络错误及 `success === false` 业务错误已由 `mutator.ts` 统一 `message.error` 并 reject；最终提交的 `else`/`catch` 禁止重复提示，loading 放在 `finally` 恢复。
+
+## 标准代码骨架
+
+```vue
+<script setup lang="ts">
+import { YButton, YFormily, type ISchema } from '@yss-ui/components';
+import { Steps as ASteps } from 'ant-design-vue';
+import { computed, reactive, ref } from 'vue';
+
+/** YFormily 对外提交能力。 */
+interface YssFormilyExpose {
+  submit: () => Promise<Record<string, any>>;
+}
+
+/** 分步表单数据。 */
+interface StepFormData {
+  step1: { name: string };
+  step2: { level: string };
+}
+
+/** 分步表单提交回调 Props。 */
+interface StepFlowProps {
+  onSubmit: (values: StepFormData) => Promise<void>;
+}
+
+/** 分步表单提交回调。 */
+const props = defineProps<StepFlowProps>();
+/** 当前步骤，从 0 开始。 */
+const currentStep = ref(0);
+/** 最终提交状态。 */
+const submitting = ref(false);
+/** 第一步表单实例。 */
+const step1Ref = ref<YssFormilyExpose>();
+/** 第二步表单实例。 */
+const step2Ref = ref<YssFormilyExpose>();
+/** 步骤导航配置。 */
+const stepItems = [{ title: '基础信息' }, { title: '策略配置' }, { title: '确认提交' }];
+/** 跨步唯一数据源。 */
+const formData = reactive<StepFormData>({
+  step1: { name: '' },
+  step2: { level: 'normal' },
+});
+
+/** 创建符合业务三层布局约定的步骤 Schema。 */
+const createStepSchema = (properties: Record<string, ISchema>): ISchema => ({
+  type: 'object',
+  properties: {
+    layout: {
+      type: 'void',
+      'x-component': 'FormLayout',
+      'x-component-props': { layout: 'horizontal', labelWidth: 120, labelAlign: 'right' },
+      properties: {
+        grid: {
+          type: 'void',
+          'x-component': 'FormGrid',
+          'x-component-props': { maxColumns: 2, minColumns: 1, minWidth: 320 },
+          properties,
+        },
+      },
+    },
+  },
+});
+
+/** 第一步 Schema。 */
+const step1Schema = createStepSchema({
+  name: {
+    type: 'string',
+    title: '任务名称',
+    required: true,
+    'x-decorator': 'FormItem',
+    'x-component': 'Input',
+  },
+});
+/** 第二步 Schema。 */
+const step2Schema = createStepSchema({
+  level: {
+    type: 'string',
+    title: '策略等级',
+    required: true,
+    enum: [
+      { label: '普通', value: 'normal' },
+      { label: '严格', value: 'strict' },
+    ],
+    'x-decorator': 'FormItem',
+    'x-component': 'Select',
+  },
+});
+/** 确认步骤 Schema。 */
+const confirmSchema = createStepSchema({
+  name: { type: 'string', title: '任务名称', 'x-decorator': 'FormItem', 'x-component': 'Input' },
+  level: { type: 'string', title: '策略等级', 'x-decorator': 'FormItem', 'x-component': 'Input' },
+});
+/** 确认步骤展示数据。 */
+const confirmValues = computed(() => ({ name: formData.step1.name, level: formData.step2.level }));
+
+/** 校验当前步骤，成功后前进。 */
+const next = async () => {
+  const currentRef = currentStep.value === 0 ? step1Ref.value : step2Ref.value;
+  if (!currentRef) return;
+  try {
+    await currentRef.submit();
+    currentStep.value += 1;
+  } catch {
+    return;
+  }
+};
+
+/** 返回上一步。 */
+const back = () => {
+  currentStep.value = Math.max(0, currentStep.value - 1);
+};
+
+/** 提交全部步骤数据。 */
+const submitAll = async () => {
+  submitting.value = true;
+  try {
+    await props.onSubmit({ step1: { ...formData.step1 }, step2: { ...formData.step2 } });
+  } finally {
+    submitting.value = false;
+  }
+};
+</script>
+
+<template>
+  <ASteps :current="currentStep" :items="stepItems" />
+
+  <YFormily v-if="currentStep === 0" ref="step1Ref" v-model="formData.step1" :schema="step1Schema" />
+  <YFormily v-else-if="currentStep === 1" ref="step2Ref" v-model="formData.step2" :schema="step2Schema" />
+  <YFormily
+    v-else
+    :schema="confirmSchema"
+    :initial-values="confirmValues"
+    :mode="2"
+    :detail-options="{ bordered: true, maxColumns: 2, minColumns: 1, minWidth: 320 }"
+  />
+
+  <YButton :disabled="currentStep === 0" @click="back">上一步</YButton>
+  <YButton v-if="currentStep < 2" type="primary" @click="next">下一步</YButton>
+  <YButton v-else type="primary" :loading="submitting" @click="submitAll">提交</YButton>
+</template>
+```
+
+复杂页面把 schema、类型与步骤 hook 分别拆到 `constant.ts`、`hooks/useStepFlow.ts`，保持 `index.vue` 在 150 行以内。
+
+## 交付检查清单
+
+- [ ] 使用 `ASteps + 多 YFormily`，组件来源明确且未编造 `YSteps`。
+- [ ] 每步前进前 await 当前实例 `submit()`，校验 reject 时不会前进。
+- [ ] 未使用 `ok !== false` 判断 `submit()` 结果。
+- [ ] 步骤切换后数据可保留和回显，确认页直接读取前序聚合数据。
+- [ ] 最终提交只聚合真实业务步骤，未把确认页空对象混入 payload。
+- [ ] API 失败只由 `mutator.ts` 统一提示，业务 `else`/`catch` 未重复 `message.error`。
+- [ ] 业务层未使用 `@formily/antdv FormStep` 作为默认实现。
+
+## 失败兜底策略
+
+- 下一步无校验时确认 ref 指向当前已挂载实例，并直接观察 `submit()` 是否 reject。
+- 状态串联错误时先收敛为单一 `reactive` 数据源，再检查每步 `v-model` 路径。
+- 确认页为空时检查是否错误绑定了独立 `step3`，应改为前序数据的 `computed` 聚合。
+- API 调用 reject 时只在 `finally` 恢复 loading，不重复弹出错误提示。
+- 步骤过多或主组件超过 150 行时，按阶段拆子组件和 `useStepXxx` hook。

package/template/.qoder/skills/frontend-commit/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: frontend-commit
+description: 分析并提交 Vue、React、TypeScript、JavaScript、Vite、微前端和前端 monorepo 项目的 Git 改动；当用户要求生成 commit message、检查提交规范、拆分原子提交、暂存并执行 git commit，或修复 commitlint 与 commit-msg hook 拒绝时使用。读取仓库实际规则和 diff，选择业务 scope，生成英文 type/scope 与中文标题和正文，并安全验证提交。
+---
+
+# 前端规范提交
+
+## 触发条件
+
+- 用户要求为前端项目生成 commit message、检查提交规范或执行 `git commit`。
+- 需要将混合改动拆分为原子提交，或评估当前暂存区是否可以安全提交。
+- commitlint、`commit-msg` 或 `pre-commit` hook 拒绝提交，需要按规则修复。
+- 适用于 Vue、React、TypeScript、JavaScript、Vite、微前端和前端 monorepo 仓库。
+
+## 不适用场景
+
+- yss-ui 组件库仓库自身的提交与发版：使用 `../commit-linting/SKILL.md`。
+- Java、Spring Boot、Maven、Gradle 后端仓库：使用 `../java-backend-commit/SKILL.md`。
+- 仅请求代码实现，不涉及提交信息或 `git commit` 操作。
+- 无代码改动，或改动内容与提交请求不匹配。
+- 合并提交、发布提交和自动依赖机器人提交：遵循仓库专用流程，不套用本技能的常规消息模板。
+
+## 硬约束（禁止/必须）
+
+- 必须把仓库规则视为最高优先级：依次遵循 `AGENTS.md`、`CONTRIBUTING.md`、Git hooks、解析后的 commitlint 配置、本地配置和近期历史；通用规则只作回退。
+- 只在用户明确要求提交时执行暂存和 `git commit`；若仅要求提交信息或审查，只输出候选消息与依据。
+- 必须保留用户和他人的既有改动。禁止默认使用 `git add -A`、`git add .`、`git commit -a`、`--no-verify`，也不要自动 amend、rebase、push 或改写已发布历史。
+- 提交必须是单一逻辑变更。不要用提交信息掩盖混杂的功能、修复、格式化或临时文件。
+- 遇到密钥、令牌、私钥、证书、`.env` 实值、账号数据或意外大文件时停止提交并报告具体路径，不要在输出中泄露内容。
+- 已有暂存内容视为用户选择，除非用户授权，不要擅自取消暂存或混入其他文件。
+- `fixup!` 只用于用户明确要求的评审或 autosquash 工作流，不能作为最终历史的默认提交。
+- revert 优先使用 Git 生成的回滚信息并保留被回滚 SHA，再根据仓库规范校验；不要把普通反向修改伪装成 revert。
+
+## 工作流
+
+### 1. 建立仓库契约
+
+1. 确认仓库根目录、当前分支和工作树状态。
+2. 搜索并读取仓库级说明、贡献指南、提交模板、commitlint 配置和 `commit-msg`、`pre-commit` hooks。
+3. 检测 `package.json`、lockfile、workspace 配置和前端应用或包边界。
+4. 如果仓库使用 commitlint，优先使用本地依赖按包管理器读取解析后的配置，例如 `pnpm exec commitlint --print-config json`；不要为了校验联网安装依赖。
+5. 查看相关路径近期的非 merge 提交，了解仓库已经形成的 scope 和语言习惯，但不要复制历史中的明显错误。
+
+### 2. 审查真实改动
+
+至少检查：
+
+```bash
+git status --short --branch
+git diff --cached --name-status
+git diff --cached
+git diff --name-status
+git diff
+git ls-files --others --exclude-standard
+```
+
+- 同时理解暂存区、未暂存区和未跟踪文件；不要只依据文件名生成消息。
+- 将改动按用户可理解的行为和因果关系分组。功能实现、配套测试和为该功能必需的最小配置可以属于同一原子提交。
+- lockfile 必须与对应 manifest 一起提交。只提交项目本来就跟踪且由本次意图产生的生成代码；排除构建产物、缓存和临时文件。
+- 若无改动、改动与请求不符、多个逻辑变更无法安全拆分，先说明并停止。需要逐行拆分同一文件时，不要靠猜测改写暂存区。
+
+### 3. 选择 type、scope 与正文
+
+先读取 `./references/scope-and-examples.md`，再按「标准代码骨架」的格式生成。
+
+- type 默认从 `feat/fix/docs/style/refactor/perf/test/chore/revert/build/ci` 中选择，但仓库枚举优先。
+- scope 优先级为：仓库枚举 → monorepo 包或应用 → 业务模块 → 共享能力。使用小写 kebab-case；不要机械地以 `views`、`hooks` 或文件名作为 scope。
+- 标题使用英文 type/scope、ASCII `:` 和中文摘要；描述行为或价值，不写“修改文件”“更新代码”或单个文件名。
+- 默认将完整 header 控制在 72 个字符内；仓库存在更严格限制时服从仓库。标题末尾不加句号，不用 emoji 或全角冒号。
+- 简单单文件变更可以没有 body；多文件、非显然修复、重要功能或行为变化使用 body 解释做了什么、为什么以及如何验证。
+- 仅对真实不兼容变更使用 `!` 和 `BREAKING CHANGE:`；仅在已知编号或仓库要求时加入工单、DCO、`Signed-off-by` 等 footer，禁止编造。
+
+### 4. 验证并提交
+
+1. 根据变更范围运行仓库已有的最小充分检查，例如相关单元测试、类型检查、lint 和构建检查；优先使用仓库脚本与当前包管理器。
+2. 通过 stdin 校验完整候选消息，而不只校验 header。使用仓库本地 commitlint 命令；退出码为 0 才继续。
+3. 仅暂存属于当前原子提交的明确路径或安全 hunks，再重新检查 `git diff --cached --check`、`--name-status` 和完整 staged diff。
+4. 执行正常 `git commit`，允许 hooks 运行。
+5. hook 若格式化或修改文件，重新检查 staged 与 working tree，确认实际提交内容没有漂移。
+6. 提交成功后检查 `git show --stat --oneline --decorate HEAD` 和 `git status --short`，向用户报告 commit hash、消息、已运行检查以及剩余未提交改动。
+
+## 标准代码骨架
+
+```text
+type(scope)!: 中文行为摘要
+
+- 说明关键行为或原因
+- 说明兼容性、测试或必要约束
+
+BREAKING CHANGE: 说明不兼容影响和迁移方式
+Refs: 已知工单号
+```
+
+示例：
+
+```text
+feat(data-push): 优化推送任务数据源与调度规则展示
+
+- 将英文星期转换为中文调度描述
+- 按数据源目录映射业务名称并补充单元测试
+```
+
+## 交付检查清单
+
+- [ ] type 与 scope 通过仓库 resolved commitlint 校验，完整消息经 stdin 校验退出码为 0。
+- [ ] scope 来自仓库枚举、包名或业务模块，未使用 `views`、`hooks`、`utils` 或文件名兜底。
+- [ ] 标题为英文 type/scope + ASCII 冒号 + 中文摘要，完整 header 不超过 72 字符。
+- [ ] 暂存区只包含当前原子提交的文件；lockfile 与对应 manifest 同提交。
+- [ ] 已运行与变更范围匹配的最小充分检查（相关测试、类型检查、lint）。
+- [ ] 提交后已核对 `git show --stat` 与 `git status --short`，并向用户报告 hash 与剩余改动。
+
+## 失败兜底策略
+
+- 无法区分 `feat`、`fix`、`refactor` 时继续检查需求和行为；仍有高影响歧义则询问用户，不自动降级为 `chore`。
+- hook 拒绝时按输出中的规则修正并重新校验，绝不使用 `--no-verify`。
+- 仓库 parser 或 hook 不支持标准破坏性标记时，不要绕过校验或静默删掉标记；报告规则冲突，并采用仓库明确批准的兼容方案。
+- 多个逻辑变更无法安全拆分时，先给出拆分方案并停止，不强行生成“大杂烩”提交。
+- 发现密钥或意外大文件时停止提交，报告具体路径并等待用户处理。

package/template/.qoder/skills/frontend-commit/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "前端规范提交"
+  short_description: "分析真实改动并生成、校验前端项目的规范化 Git 提交"
+  default_prompt: "使用 $frontend-commit 检查当前前端改动并创建一条规范、原子的 Git 提交。"
+
+policy:
+  allow_implicit_invocation: true

package/template/.qoder/skills/frontend-commit/references/scope-and-examples.md

@@ -0,0 +1,111 @@
+# 前端 Type、Scope 与示例
+
+## 目录
+
+- [规则优先级](#规则优先级)
+- [Type 选择](#type-选择)
+- [Scope 选择](#scope-选择)
+- [原子提交边界](#原子提交边界)
+- [消息示例](#消息示例)
+- [前端验证](#前端验证)
+- [规范依据](#规范依据)
+
+## 规则优先级
+
+1. 仓库 commitlint 的 resolved config 和 hooks。
+2. 仓库 `AGENTS.md`、`CONTRIBUTING.md`、提交模板及明确文档。
+3. 当前 monorepo 的包或应用名称，以及目标路径近期的有效提交。
+4. 本参考的通用回退规则。
+
+仓库允许空 scope 时仍优先使用能帮助团队定位业务影响的 scope；跨全仓且没有清晰主域时可以省略。只有 commitlint 明确支持且团队历史稳定使用时才采用多 scope。
+
+## Type 选择
+
+| Type | 使用条件 | 不要用于 |
+|---|---|---|
+| `feat` | 增加用户、调用方或运维人员可感知的能力 | 纯重构或依赖升级 |
+| `fix` | 修复错误、回归、异常状态或不符合预期的行为 | 仅格式化代码 |
+| `docs` | 只修改文档 | 代码行为变化 |
+| `style` | 仅空格、格式、分号等，不改变语义 | UI 样式或视觉功能变更 |
+| `refactor` | 不增功能、不修 bug 的结构调整 | 性能优化或行为修复 |
+| `perf` | 有明确性能收益的代码变化 | 无证据的“优化”措辞 |
+| `test` | 只增加或修正测试 | 功能代码及其配套测试 |
+| `build` | 构建系统、外部依赖、打包或编译配置 | 一般业务配置 |
+| `ci` | CI/CD 配置和流水线脚本 | 本地构建配置 |
+| `chore` | 其他不改变产品行为的维护工作 | 无法理解改动时的兜底 |
+| `revert` | 明确回滚一个或多个既有提交 | 普通修复 |
+
+## Scope 选择
+
+按以下顺序选择首个清晰候选：
+
+1. **仓库限定值**：若 `scope-enum` 生效，只能使用允许值或按规则省略。
+2. **monorepo 包或应用**：`apps/admin-portal` 使用 `admin-portal`；`packages/design-system` 使用 `design-system`。
+3. **业务模块**：`views/DataPush`、相关 API、hook 和测试共同实现推送任务时使用 `data-push`，不使用 `views`。
+4. **共享能力**：确实跨业务复用时使用 `auth`、`router`、`store`、`i18n`、`api-client`、`design-system` 等已有名称。
+5. **工程边界**：依赖升级可用 `deps`，构建和 CI 可用 `build`、`ci`；scope 不应重复无意义信息。
+
+命名使用小写 kebab-case。优先采用仓库或产品已有术语，不自行翻译稳定模块名。`components`、`hooks`、`utils`、`views`、`index` 和具体文件名通常信息不足，只有它们本身就是对外包或仓库既定 scope 时才使用。
+
+## 原子提交边界
+
+- 同一功能的页面、API 适配、状态逻辑、测试和最小测试配置可以同提交。
+- `package.json` 与对应 lockfile 必须同提交；与业务功能无关的批量依赖升级单独使用 `build(deps)`。
+- 生成 API 客户端和消费端若共同实现同一契约能力，可按业务域提交；无关的大规模重新生成必须拆分。
+- 顺手格式化、调试日志、个人 IDE 配置和无关文件不要混入。
+- 两个独立业务模块或不同发布风险的改动应拆分；同一文件内无法安全分离时先请求用户决定。
+
+## 消息示例
+
+```text
+feat(data-push): 优化推送任务数据源与调度规则展示
+
+- 将英文星期转换为中文调度描述
+- 按数据源目录映射业务名称并补充单元测试
+```
+
+```text
+fix(auth): 修复令牌刷新并发请求重复跳转登录的问题
+
+- 复用进行中的刷新请求，避免多个失败响应重复触发跳转
+- 保持刷新失败后的退出流程不变
+```
+
+```text
+build(deps): 升级 Vue 与类型检查工具链
+```
+
+```text
+feat(api-client)!: 统一分页响应字段命名
+
+- 将列表响应统一为 items 和 total
+- 更新调用方与契约测试
+
+BREAKING CHANGE: 原 records 字段改为 items，所有自定义适配器需同步迁移
+```
+
+错误与修正：
+
+| 错误 | 修正方向 |
+|---|---|
+| `fix：修复问题` | 使用 ASCII 冒号并说明具体行为 |
+| `fixL 新增下载` | 选择合法 type，例如 `feat(download): 支持导出任务文件` |
+| `fix: useDataPushTasks.ts` | 描述修复结果，而不是文件名 |
+| `feat(views): 新增用户管理` | 优先使用 `feat(user-management): ...` |
+| `chore: 修改代码` | 先理解真实意图，再选择准确 type 和摘要 |
+
+## 前端验证
+
+- 根据 lockfile 选择 `pnpm`、`npm`、`yarn` 或 `bun`，优先运行 `package.json` 已有脚本。
+- 功能或修复至少运行相关测试；类型相关变更运行 type-check；lint、format 只使用不会意外重写无关文件的检查模式。
+- monorepo 优先运行受影响包的过滤命令，除非仓库要求全量检查。
+- 不把“hook 会跑”当作跳过必要验证的理由；也不要编造不存在的脚本。
+
+## 规范依据
+
+- [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/)
+- [commitlint：AI Agents](https://commitlint.js.org/guides/ai-agents.html)
+- [commitlint 官方 committing-with-commitlint skill](https://github.com/conventional-changelog/commitlint/tree/master/skills/committing-with-commitlint)
+- [Angular Commit Message Guidelines](https://github.com/angular/angular/blob/main/contributing-docs/commit-message-guidelines.md)
+- [Git SubmittingPatches](https://git-scm.com/docs/SubmittingPatches)
+

package/template/.qoder/skills/implementation-repo-onboarding/SKILL.md

@@ -18,11 +18,11 @@ description: Use when connecting an existing frontend, backend, fullstack, or ot
 
 1. 确认当前仓库是 Harness 仓库，读取 `docs/process/implementation-repo-integration.md`。
 2. 如果输入是本地路径，只读检查 Git remote、当前分支、目录结构、构建文件和测试脚本。
-3. 如果输入是远端 URL，优先使用只读 Git 查询；需要 clone 时只能 clone 到临时目录，不能 clone 到 Harness 仓库内。
+3. 如果输入是远端 URL，优先使用只读 Git 查询。需要完整工作树时：`external-repository` 只能 clone 到临时目录；`git-submodule` 只能通过 `git submodule add` / `git submodule update --init` 在已批准的 `apps/backend/<project>/` 或 `apps/frontend/<project>/` gitlink 挂载点检出，禁止普通 clone 或复制源码进 Harness。
 4. 识别技术栈、包管理器、CI、测试命令、构建命令、OpenAPI 接入和设计 token 接入。
-5. 判定实现位置：Harness 内只能使用 `apps/backend/<project>/` 或 `apps/frontend/<project>/`；`apps/backend/`、`apps/frontend/` 仅为容器，`app/backend/`、`app/frontend/` 及其子路径必须标记为阻断。外部实现仓库记录真实项目根路径，不套用 Harness 占位路径。
-6. 按 `docs/templates/implementation-repo-registry-template.md` 输出实现仓库登记内容。
-7. 列出 `known_gaps`、人审点、fresh verification 命令和需要回写到 Harness change / Issue / checkpoint 的信息。
+5. 判定实现位置与 `repository_scope`：`external-repository` 记录真实项目根；`harness-apps` 与 `git-submodule` 只能使用 `apps/backend/<project>/` 或 `apps/frontend/<project>/`。`apps/backend/`、`apps/frontend/` 仅为容器，`app/backend/`、`app/frontend/` 及其子路径必须标记为阻断。gitlink（mode `160000`）必须登记为 `git-submodule` 和 `layout_policy: git-submodule-harness-apps`，不得写成 `harness-apps`。必须对照工作树：`git ls-files --stage`、`.gitmodules` 与声明 scope 不一致时阻断；缺少 `git_entry_mode: 160000` 不得把挂载点当普通目录。
+6. 按 `docs/templates/implementation-repo-registry-template.md` 输出实现仓库登记内容。`git-submodule` 必填 `gitmodules_name`、`gitlink_path`、`git_entry_mode`、`superproject_git_url` 和 `checkout_state`。`harness-apps` / `external-repository` 这些字段填 `不适用`。
+7. 列出 `known_gaps`、人审点、fresh verification 命令和需要回写到 Harness change / Issue / checkpoint 的信息。空 gitlink、detached HEAD、`--force` 覆盖挂载点或缺少递归检出凭据时标记阻断。写入前必须看 `inspectWorkingTreeScope` / `implementationWriteViolation`：只接受对象结果且 `.writable === true` 才可写；字符串、`null` 或 `.writable !== true` 一律不可写。即使已正确登记为 `git-submodule`，空 gitlink 或 detached HEAD 也必须 `.writable === false`，不得当普通目录写文件或脚手架。
 
 ## Baseline Checks
 
@@ -36,7 +36,7 @@ description: Use when connecting an existing frontend, backend, fullstack, or ot
 ## Boundaries
 
 - 不直接提交、推送、创建 MR / PR 或修改实现仓库。
-- 不把实现仓库源码复制进 Harness 仓库。
+- 不把实现仓库源码复制进 Harness 仓库；`git-submodule` 只能形成 gitlink，不能 copy / subtree 冒充。
 - 不把缺失命令编造为已存在；找不到时标记 `unknown` 或 `需人工确认`。
 - 不得把 `app/backend/`、`app/frontend/` 或 `apps/backend/`、`apps/frontend/` 容器根登记为可生成项目根。
 - 触碰认证、授权、SQL、迁移、加密、公共基础库 API 时标记 `TODO-HUMAN-REVIEW`。