@ai0x0/utils 0.0.26 → 0.0.27

package/eslint-rules/index.js

@@ -0,0 +1,40 @@
+/**
+ * 本地 ESLint plugin：封装项目自定义规则。
+ */
+import requireSectionDivider from "./require-section-divider.js";
+import noHardcodedStyle from "./no-hardcoded-style.js";
+import requireUseForm from "./require-use-form.js";
+import requireFormConvention from "./require-form-convention.js";
+import requireProComponents from "./require-pro-components.js";
+import noAntdSpace from "./no-antd-space.js";
+import noUseRequestRun from "./no-use-request-run.js";
+import noThen from "./no-then.js";
+import noOneLetterVars from "./no-one-letter-vars.js";
+import noConsecutiveSetState from "./no-consecutive-setstate.js";
+
+const rules = {
+  "require-section-divider": requireSectionDivider,
+  "no-hardcoded-style": noHardcodedStyle,
+  "require-use-form": requireUseForm,
+  "require-form-convention": requireFormConvention,
+  "require-pro-components": requireProComponents,
+  "no-antd-space": noAntdSpace,
+  "no-use-request-run": noUseRequestRun,
+  "no-then": noThen,
+  "no-one-letter-vars": noOneLetterVars,
+  "no-consecutive-setstate": noConsecutiveSetState,
+};
+
+const plugin = {
+  rules,
+  configs: {
+    recommended: {
+      plugins: { local: { rules } },
+      rules: Object.fromEntries(
+        Object.keys(rules).map((name) => [`local/${name}`, "error"]),
+      ),
+    },
+  },
+};
+
+export default plugin;

package/eslint-rules/no-antd-space.js

@@ -0,0 +1,63 @@
+/**
+ * no-antd-space
+ * -------------
+ * 禁止使用 antd <Space>，用 antd <Flex> 代替。
+ *
+ * 映射参考：
+ * - <Space direction="vertical"> → <Flex vertical>
+ * - <Space size={N}> → <Flex gap={N}>
+ * - <Space wrap> → <Flex wrap="wrap">
+ * - Space.Compact → 用 Flex 自行实现紧凑排列
+ *
+ * 本规则只负责检测，不负责自动修复。
+ */
+
+/** @type {import('eslint').Rule.RuleModule} */
+const rule = {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "禁止使用 antd <Space>，请使用 antd <Flex> 代替。",
+    },
+    schema: [],
+    messages: {
+      useFlexInstead:
+        "禁止使用 antd <Space>，请使用 antd <Flex> 代替。<Space> 的 props 到 <Flex> 的映射：direction={vertical} → vertical, wrap → wrap='wrap', size={N} → gap={N}。",
+      useFlexInsteadCompact:
+        "禁止使用 antd <Space.Compact>，请使用 <Flex> 自行实现紧凑排列。",
+    },
+  },
+  create(context) {
+    const getTagName = (name) => {
+      if (name.type === "JSXIdentifier") return name.name;
+      if (
+        name.type === "JSXMemberExpression" &&
+        name.object.type === "JSXIdentifier" &&
+        name.property.type === "JSXIdentifier"
+      ) {
+        return `${name.object.name}.${name.property.name}`;
+      }
+      return "";
+    };
+
+    return {
+      JSXOpeningElement(node) {
+        const tagName = getTagName(node.name);
+        if (tagName === "Space") {
+          context.report({
+            node: node,
+            messageId: "useFlexInstead",
+          });
+        }
+        if (tagName === "Space.Compact") {
+          context.report({
+            node: node,
+            messageId: "useFlexInsteadCompact",
+          });
+        }
+      },
+    };
+  },
+};
+
+export default rule;

package/eslint-rules/no-consecutive-setstate.js

@@ -0,0 +1,87 @@
+/**
+ * no-consecutive-setstate
+ * ------------------------
+ * 禁止在同一个块中连续调用多个 setState()。
+ * ahooks useSetState 的 setState 会合并状态，连续多次调用应该合并为一次。
+ *
+ * 误：
+ *   setState({ a: 1 });
+ *   setState({ b: 2 });
+ *
+ * 正：
+ *   setState({ a: 1, b: 2 });
+ */
+
+/** @type {import('eslint').Rule.RuleModule} */
+const rule = {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "禁止连续调用多个 setState()，应合并为一次。",
+    },
+    schema: [],
+    messages: {
+      merge:
+        "连续多个 setState() 应合并为一次：将 {{prevField}} 和 {{currField}} 合并到一个 setState 中",
+    },
+  },
+  create(context) {
+    return {
+      BlockStatement(node) {
+        const body = node.body;
+        for (let i = 0; i + 1 < body.length; i++) {
+          const curr = body[i];
+          const next = body[i + 1];
+
+          if (
+            curr.type !== "ExpressionStatement" ||
+            next.type !== "ExpressionStatement"
+          )
+            continue;
+
+          const currExpr = curr.expression;
+          const nextExpr = next.expression;
+
+          const isCurrSetState =
+            currExpr.type === "CallExpression" &&
+            currExpr.callee.type === "Identifier" &&
+            currExpr.callee.name === "setState" &&
+            currExpr.arguments.length === 1 &&
+            currExpr.arguments[0].type === "ObjectExpression";
+
+          const isNextSetState =
+            nextExpr.type === "CallExpression" &&
+            nextExpr.callee.type === "Identifier" &&
+            nextExpr.callee.name === "setState" &&
+            nextExpr.arguments.length === 1 &&
+            nextExpr.arguments[0].type === "ObjectExpression";
+
+          if (!isCurrSetState || !isNextSetState) continue;
+
+          const prevField = currExpr.arguments[0];
+          const currField = nextExpr.arguments[0];
+          const sourceCode = context.sourceCode ?? context.getSourceCode();
+          const prevFieldText = sourceCode
+            .getText(prevField)
+            .slice(1, -1)
+            .trim();
+          const currFieldText = sourceCode
+            .getText(currField)
+            .slice(1, -1)
+            .trim();
+
+          context.report({
+            node: next,
+            messageId: "merge",
+            data: {
+              prevField: prevFieldText,
+              currField: currFieldText,
+            },
+          });
+        }
+      },
+    };
+  },
+};
+
+export default rule;

package/eslint-rules/no-hardcoded-style.js

@@ -0,0 +1,437 @@
+/**
+ * no-hardcoded-style
+ * ------------------
+ * 禁止在 JSX style / createStyles / css`` 中直接写死样式值。
+ * 强制使用 antd token（theme.useToken() 或 createStyles(({token}) => ...)）。
+ *
+ * 白名单：
+ *   - token.xxx / token() / calc(...) 表达式
+ *   - 0 值
+ *   - CSS 功能性关键字（auto, none, hidden, pointer 等）
+ *   - 百分比 / 带单位字符串
+ *   - 条件/逻辑/变量/函数调用（无法静态判断）
+ *   - css\`...\` 中的 \${token.xxx} 插值
+ */
+
+// ==============================================================================
+// 白名单
+// ==============================================================================
+
+const ALLOWED_LITERALS = new Set([
+  "auto",
+  "none",
+  "hidden",
+  "visible",
+  "pre-wrap",
+  "pre",
+  "normal",
+  "pointer",
+  "default",
+  "move",
+  "not-allowed",
+  "grab",
+  "grabbing",
+  "center",
+  "flex-start",
+  "flex-end",
+  "space-between",
+  "space-around",
+  "left",
+  "right",
+  "top",
+  "bottom",
+  "start",
+  "end",
+  "solid",
+  "dashed",
+  "dotted",
+  "double",
+  "groove",
+  "ridge",
+  "inset",
+  "outset",
+  "block",
+  "inline-block",
+  "inline",
+  "flex",
+  "grid",
+  "contents",
+  "row",
+  "column",
+  "row-reverse",
+  "column-reverse",
+  "wrap",
+  "nowrap",
+  "wrap-reverse",
+  "relative",
+  "absolute",
+  "fixed",
+  "sticky",
+  "static",
+  "bold",
+  "bolder",
+  "lighter",
+  "100",
+  "200",
+  "300",
+  "400",
+  "500",
+  "600",
+  "700",
+  "800",
+  "900",
+  "italic",
+  "oblique",
+  "uppercase",
+  "lowercase",
+  "capitalize",
+  "underline",
+  "overline",
+  "line-through",
+  "blink",
+  "collapse",
+  "separate",
+  "border-box",
+  "content-box",
+  "padding-box",
+  "contain",
+  "cover",
+  "fill",
+  "scale-down",
+]);
+
+const TOKEN_KEYS = new Set([
+  "margin",
+  "marginTop",
+  "marginBottom",
+  "marginLeft",
+  "marginRight",
+  "marginInline",
+  "marginInlineStart",
+  "marginInlineEnd",
+  "marginBlock",
+  "marginBlockStart",
+  "marginBlockEnd",
+  "padding",
+  "paddingTop",
+  "paddingBottom",
+  "paddingLeft",
+  "paddingRight",
+  "paddingInline",
+  "paddingInlineStart",
+  "paddingInlineEnd",
+  "paddingBlock",
+  "paddingBlockStart",
+  "paddingBlockEnd",
+  "gap",
+  "rowGap",
+  "columnGap",
+  "color",
+  "background",
+  "backgroundColor",
+  "borderColor",
+  "borderTopColor",
+  "borderBottomColor",
+  "borderLeftColor",
+  "borderRightColor",
+  "outlineColor",
+  "border",
+  "borderTop",
+  "borderBottom",
+  "borderLeft",
+  "borderRight",
+  "borderWidth",
+  "borderTopWidth",
+  "borderBottomWidth",
+  "borderLeftWidth",
+  "borderRightWidth",
+  "borderStyle",
+  "borderTopStyle",
+  "borderBottomStyle",
+  "borderLeftStyle",
+  "borderRightStyle",
+  "borderRadius",
+  "borderTopLeftRadius",
+  "borderTopRightRadius",
+  "borderBottomLeftRadius",
+  "borderBottomRightRadius",
+  "fontSize",
+  "fontWeight",
+  "lineHeight",
+  "letterSpacing",
+  "boxShadow",
+  "textShadow",
+  "opacity",
+  "zIndex",
+  "width",
+  "height",
+  "minWidth",
+  "minHeight",
+  "maxWidth",
+  "maxHeight",
+  "top",
+  "bottom",
+  "left",
+  "right",
+]);
+
+// ==============================================================================
+// Token 属性 / 检查逻辑
+// ==============================================================================
+
+/** kebab-case → camelCase 映射（用于 css`` 模板字符串） */
+const KEBAB_TO_CAMEL = {};
+for (const key of TOKEN_KEYS) {
+  const kebab = key.replace(/([A-Z])/g, "-$1").toLowerCase();
+  KEBAB_TO_CAMEL[kebab] = key;
+}
+
+function isTokenExpr(node) {
+  if (!node) return false;
+  if (
+    node.type === "MemberExpression" &&
+    node.object.type === "Identifier" &&
+    node.object.name === "token"
+  )
+    return true;
+  if (
+    node.type === "CallExpression" &&
+    node.callee.type === "Identifier" &&
+    ["token", "calc", "max", "min", "clamp"].includes(node.callee.name)
+  )
+    return true;
+  return false;
+}
+
+function isAllowedValue(node) {
+  if (!node) return true;
+  if (isTokenExpr(node)) return true;
+  if (node.type === "Literal" && (node.value === 0 || node.value === "0"))
+    return true;
+  if (
+    node.type === "Literal" &&
+    typeof node.value === "string" &&
+    ALLOWED_LITERALS.has(node.value)
+  )
+    return true;
+  if (
+    node.type === "Literal" &&
+    typeof node.value === "string" &&
+    /^(\d+(\.\d+)?(px|em|rem|%|vh|vw|vmin|vmax|ex|ch|cm|mm|in|pt|pc)|\d+(\.\d+)?\s+(px|em|rem)\s+(solid|dashed|dotted)|\d+\.?\d*%)$/.test(
+      node.value,
+    )
+  )
+    return true;
+  if (
+    [
+      "ConditionalExpression",
+      "LogicalExpression",
+      "BinaryExpression",
+      "UnaryExpression",
+      "TemplateLiteral",
+      "CallExpression",
+      "Identifier",
+      "SpreadElement",
+    ].includes(node.type)
+  )
+    return true;
+  if (node.type === "ObjectExpression" || node.type === "ArrayExpression")
+    return true;
+  return false;
+}
+
+function checkStyleObject(context, objExpr) {
+  for (const prop of objExpr.properties) {
+    if (prop.type !== "Property") continue;
+    const key =
+      prop.key.type === "Identifier"
+        ? prop.key.name
+        : prop.key.type === "Literal"
+          ? prop.key.value
+          : null;
+    if (!key || !TOKEN_KEYS.has(key)) continue;
+    const val = prop.value;
+    if (isAllowedValue(val)) continue;
+    const valText = context.getSourceCode().getText(val);
+    context.report({
+      node: prop,
+      messageId: "noHardcoded",
+      data: { key, value: valText },
+    });
+  }
+}
+
+function checkCssTemplate(context, node) {
+  const template = node.quasi;
+  const quasis = template.quasis;
+  const expressions = template.expressions;
+
+  // 构建完整 CSS 文本，用占位符标记插值位置
+  let fullText = "";
+  for (let i = 0; i < quasis.length; i++) {
+    fullText += quasis[i].value.raw;
+    if (i < expressions.length) fullText += "${EXPR}";
+  }
+
+  // 按行分割，逐行检查
+  const lines = fullText.split(/\n/);
+  for (const line of lines) {
+    // 简单解析：找冒号分割的 property: value
+    const colonIdx = line.indexOf(":");
+    if (colonIdx === -1) continue;
+
+    const rawProp = line.slice(0, colonIdx).trim();
+    const rawVal = line
+      .slice(colonIdx + 1)
+      .trim()
+      .replace(/;$/, "")
+      .trim();
+
+    // 忽略 css 嵌套规则、@media 等
+    if (
+      rawProp.startsWith("&") ||
+      rawProp.startsWith("@") ||
+      rawProp.startsWith("//")
+    )
+      continue;
+
+    // 匹配 camelCase 或 kebab-case 属性
+    const camelProp = TOKEN_KEYS.has(rawProp)
+      ? rawProp
+      : KEBAB_TO_CAMEL[rawProp];
+    if (!camelProp) continue;
+
+    // 值包含 ${EXPR} → 被插值打断或完全由表达式提供 → 跳过
+    if (rawVal.includes("${EXPR}")) continue;
+
+    // 0 值
+    if (rawVal === "0" || rawVal === "0px") continue;
+
+    // CSS 关键字白名单
+    if (ALLOWED_LITERALS.has(rawVal)) continue;
+
+    // 纯百分比 → 允许（布局常用）
+    if (/^\d+\.?\d*%$/.test(rawVal)) continue;
+
+    // 100vh / 100vw → 允许（全屏布局）
+    if (/^100(vh|vw)$/.test(rawVal)) continue;
+
+    // 百分比 / 带单位字符串 → 硬编码（token 体系也有 sizeStep/sizeUnit）
+    if (
+      /^(\d+(\.\d+)?(px|em|rem|%|vh|vw|vmin|vmax|ex|ch|cm|mm|in|pt|pc)|\d+\.?\d*%)$/.test(
+        rawVal,
+      )
+    ) {
+      context.report({
+        node: template,
+        messageId: "noHardcoded",
+        data: { key: rawProp, value: rawVal },
+      });
+      continue;
+    }
+
+    // 剩余 → 硬编码
+    context.report({
+      node: template,
+      messageId: "noHardcoded",
+      data: { key: rawProp, value: rawVal },
+    });
+  }
+}
+
+/** @type {import('eslint').Rule.RuleModule} */
+const rule = {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "禁止在 style / createStyles / css`` 中硬编码样式值，强制使用 antd token。",
+    },
+    schema: [],
+    messages: {
+      noHardcoded:
+        "禁止硬编码 `{{ {{key}}: {{value}} }}`。请使用 antd token（如 `token.marginSM`、`token.colorPrimary`）。可参考 .codex/skills/ant-design/SKILL.md 了解 token 体系。",
+    },
+  },
+  create(context) {
+    return {
+      JSXAttribute(node) {
+        if (node.name.name !== "style") return;
+        const expr = node.value?.expression;
+        if (!expr || expr.type !== "ObjectExpression") return;
+        checkStyleObject(context, expr);
+      },
+
+      TaggedTemplateExpression(node) {
+        if (node.tag.type === "Identifier" && node.tag.name === "css") {
+          checkCssTemplate(context, node);
+        }
+      },
+
+      CallExpression(node) {
+        if (
+          node.callee.type !== "Identifier" ||
+          node.callee.name !== "createStyles"
+        )
+          return;
+        const arg = node.arguments[0];
+        if (!arg) return;
+
+        if (arg.type === "ObjectExpression") {
+          for (const prop of arg.properties) {
+            if (prop.type !== "Property") continue;
+            if (prop.value.type === "ObjectExpression")
+              checkStyleObject(context, prop.value);
+            else if (
+              prop.value.type === "TaggedTemplateExpression" &&
+              prop.value.tag.name === "css"
+            )
+              checkCssTemplate(context, prop.value);
+          }
+          return;
+        }
+
+        let body = null;
+        if (arg.type === "ArrowFunctionExpression") body = arg.body;
+        else if (arg.type === "FunctionExpression") body = arg.body;
+        if (!body) return;
+
+        if (body.type === "ObjectExpression") {
+          for (const prop of body.properties) {
+            if (prop.type !== "Property") continue;
+            if (prop.value.type === "ObjectExpression")
+              checkStyleObject(context, prop.value);
+            else if (
+              prop.value.type === "TaggedTemplateExpression" &&
+              prop.value.tag.name === "css"
+            )
+              checkCssTemplate(context, prop.value);
+          }
+          return;
+        }
+
+        if (body.type === "BlockStatement") {
+          for (const stmt of body.body) {
+            if (
+              stmt.type === "ReturnStatement" &&
+              stmt.argument?.type === "ObjectExpression"
+            ) {
+              for (const prop of stmt.argument.properties) {
+                if (prop.type !== "Property") continue;
+                if (prop.value.type === "ObjectExpression")
+                  checkStyleObject(context, prop.value);
+                else if (
+                  prop.value.type === "TaggedTemplateExpression" &&
+                  prop.value.tag.name === "css"
+                )
+                  checkCssTemplate(context, prop.value);
+              }
+            }
+          }
+        }
+      },
+    };
+  },
+};
+
+export default rule;

package/eslint-rules/no-one-letter-vars.js

@@ -0,0 +1,111 @@
+/**
+ * no-one-letter-vars
+ * ------------------
+ * 禁止单字母变量名（如 `e`、`i`、`g`、`x` 等），要求使用有意义的命名。
+ *
+ * 例外：
+ *   - `_` 常用于未使用变量
+ *   - for 循环的声名部分（for (let i = 0; ...)）— 惯用用法
+ *   - 泛型类型参数如 `<T>`
+ */
+
+/** @type {import('eslint').Rule.RuleModule} */
+const rule = {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "禁止使用单字母变量，要求有意义的命名。",
+    },
+    schema: [],
+    messages: {
+      noOneLetter: "禁止使用单字母变量名 '{{ name }}'，请使用有意义的名称。",
+    },
+  },
+  create(context) {
+    // Track function scopes to know if we're at the top level
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    let scopeStack = 0;
+
+    return {
+      // --- 变量声名 ---
+      VariableDeclarator(node) {
+        if (!node.id || node.id.type !== "Identifier") return;
+        const name = node.id.name;
+        if (name.length !== 1 || !/^[a-z]$/.test(name)) return;
+
+        // Skip `_`
+        if (name === "_") return;
+
+        // Skip if inside for loop (for (let i = 0..))
+        let parent = node.parent;
+        while (parent) {
+          if (
+            parent.type === "ForStatement" ||
+            parent.type === "ForInStatement" ||
+            parent.type === "ForOfStatement"
+          ) {
+            return;
+          }
+          parent = parent.parent;
+        }
+
+        context.report({
+          node: node.id,
+          messageId: "noOneLetter",
+          data: { name },
+        });
+      },
+
+      // --- 函数/箭头函数参数 ---
+      ":function"(node) {
+        scopeStack++;
+        for (const param of node.params) {
+          if (param.type === "Identifier") {
+            const name = param.name;
+            if (name.length === 1 && /^[a-z]$/.test(name) && name !== "_") {
+              context.report({
+                node: param,
+                messageId: "noOneLetter",
+                data: { name },
+              });
+            }
+          } else if (
+            param.type === "ObjectPattern" ||
+            param.type === "ArrayPattern"
+          ) {
+            // Check nested patterns
+            checkPattern(param, context);
+          }
+        }
+      },
+      ":function:exit"() {
+        scopeStack--;
+      },
+    };
+
+    function checkPattern(pattern, ctx) {
+      for (const prop of pattern.properties || pattern.elements || []) {
+        if (!prop) continue;
+        const value =
+          prop.type === "RestElement" ? prop.argument : prop.value || prop;
+        if (value.type === "Identifier") {
+          const name = value.name;
+          if (name.length === 1 && /^[a-z]$/.test(name) && name !== "_") {
+            ctx.report({
+              node: value,
+              messageId: "noOneLetter",
+              data: { name },
+            });
+          }
+        } else if (
+          value.type === "ObjectPattern" ||
+          value.type === "ArrayPattern"
+        ) {
+          checkPattern(value, ctx);
+        }
+      }
+    }
+  },
+};
+
+export default rule;

package/eslint-rules/no-then.js

@@ -0,0 +1,40 @@
+/**
+ * no-then
+ * -------
+ * 禁止使用 .then()，强制使用 async/await。
+ *
+ * 例外（不检测）：
+ *   - 文件和 /apis/generator/ 下的代码（已有独立 override）
+ */
+
+/** @type {import('eslint').Rule.RuleModule} */
+const rule = {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "禁止使用 .then()，必须使用 async/await。",
+    },
+    schema: [],
+    messages: {
+      noThen: "禁止使用 .then()，请使用 async/await 替代。",
+    },
+  },
+  create(context) {
+    return {
+      CallExpression(node) {
+        if (
+          node.callee.type === "MemberExpression" &&
+          node.callee.property.type === "Identifier" &&
+          node.callee.property.name === "then"
+        ) {
+          context.report({
+            node: node.callee.property,
+            messageId: "noThen",
+          });
+        }
+      },
+    };
+  },
+};
+
+export default rule;

package/eslint-rules/no-use-request-run.js

@@ -0,0 +1,54 @@
+/**
+ * no-use-request-run
+ * -------------------
+ * 禁止在 useRequest 解构中使用 `run`（包括 `run: alias` 和 `run`）。
+ * 必须使用 `runAsync` 并配合 `await` 在调用处等待。
+ */
+
+/** @type {import('eslint').Rule.RuleModule} */
+const rule = {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "禁止使用 useRequest 的 run，必须使用 runAsync + await。",
+    },
+    schema: [],
+    messages: {
+      useRunAsync:
+        "禁止使用 useRequest 的 run/run:xxx，请使用 runAsync/runAsync:xxx + await。",
+    },
+  },
+  create(context) {
+    return {
+      VariableDeclarator(node) {
+        if (
+          node.init &&
+          node.init.type === "CallExpression" &&
+          node.init.callee.type === "Identifier" &&
+          node.init.callee.name === "useRequest"
+        ) {
+          if (node.id.type === "ObjectPattern") {
+            for (const prop of node.id.properties) {
+              if (prop.type !== "Property") continue;
+              const key = prop.key;
+              if (
+                key.type === "Identifier" &&
+                (key.name === "run" || key.name === "runAsync")
+              ) {
+                // Only report for `run` / `run: foo`, not for `runAsync`
+                if (key.name === "run") {
+                  context.report({
+                    node: prop,
+                    messageId: "useRunAsync",
+                  });
+                }
+              }
+            }
+          }
+        }
+      },
+    };
+  },
+};
+
+export default rule;

package/eslint-rules/require-form-convention.js

@@ -0,0 +1,200 @@
+/**
+ * require-form-convention
+ * -----------------------
+ * 约束表单组件必须遵守以下规范：
+ *
+ * 1. <Form> 必须使用 onFinish 提交
+ * 2. <Form.Item> 必须使用 rules 进行表单校验
+ * 3. 禁止在 useRequest 中使用 message.error 报错
+ * 4. Modal + Form 组合时，禁止用 Modal.onOk 提交
+ *
+ * 例外通过文件路径 overrides 处理（utils、hooks、theme 等已豁免）。
+ */
+
+/** @type {import('eslint').Rule.RuleModule} */
+
+// ==============================================================================
+// 规则实现
+// ==============================================================================
+
+const rule = {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "表单组件必须使用 Form.onFinish，Form.Item 必须使用 rules，禁止 useRequest 内 message.error，禁止 Modal.onOk 提交表单。",
+    },
+    schema: [],
+    messages: {
+      needOnFinish:
+        "<Form> 必须使用 onFinish 属性提交表单，禁止用 form.validateFields() 或 Modal.onOk 手动提交。",
+      needItemRules:
+        "<Form.Item> 必须设置 rules 进行校验。如果确实不需要校验，请用 // eslint-disable-next-line 注明原因。",
+      noMessageError:
+        "禁止在 useRequest 的 onSuccess/onError 回调中使用 message.error。错误提示应通过 antd Form.Item 的 rules 或 Form onFinish 的错误处理来展示。",
+      noModalOnOk:
+        "Modal + Form 组合时，禁止使用 Modal.onOk 提交。请使用 Form.onFinish。",
+      noMessageErrorAny:
+        "禁止使用 app?.message.error 报错，请求拦截器已统一处理。请移除该行。",
+    },
+  },
+  create(context) {
+    const sourceCode = context.getSourceCode();
+
+    let hasFormTag = false;
+    let hasFormOnFinish = false;
+    const formItemNoRules = [];
+    const useRequestCalls = [];
+    const modalOnOkAttrs = [];
+    const validateFieldsCalls = [];
+
+    const getTagName = (name) => {
+      if (name.type === "JSXIdentifier") return name.name;
+      if (
+        name.type === "JSXMemberExpression" &&
+        name.object.type === "JSXIdentifier" &&
+        name.property.type === "JSXIdentifier"
+      ) {
+        return `${name.object.name}.${name.property.name}`;
+      }
+      return "";
+    };
+
+    return {
+      JSXOpeningElement(node) {
+        const tagName = getTagName(node.name);
+
+        // <Form>
+        if (tagName === "Form") {
+          hasFormTag = true;
+          for (const attr of node.attributes) {
+            if (attr.type !== "JSXAttribute" || !attr.name) continue;
+            if (attr.name.name === "onFinish") {
+              hasFormOnFinish = true;
+            }
+          }
+          if (!hasFormOnFinish) {
+            context.report({
+              node: node,
+              messageId: "needOnFinish",
+            });
+          }
+        }
+
+        // <Form.Item>
+        if (tagName === "Form.Item") {
+          let hasRules = false;
+          let isNoStyle = false;
+          let hasName = false;
+          for (const attr of node.attributes) {
+            if (attr.type !== "JSXAttribute" || !attr.name) continue;
+            if (attr.name.name === "rules") hasRules = true;
+            if (attr.name.name === "noStyle") isNoStyle = true;
+            if (attr.name.name === "name") hasName = true;
+          }
+          // noStyle 或 <Form.List> 内的 Item 不需要 rules
+          if (!hasRules && !isNoStyle && hasName) {
+            formItemNoRules.push(node);
+          }
+        }
+
+        // <Modal onOk={...}>
+        if (tagName === "Modal") {
+          for (const attr of node.attributes) {
+            if (attr.type !== "JSXAttribute" || !attr.name) continue;
+            if (attr.name.name === "onOk") {
+              modalOnOkAttrs.push(attr);
+            }
+          }
+        }
+      },
+
+      CallExpression(node) {
+        // app?.message.error() — 请求拦截器已统一处理，禁止手动调用
+        // app?.message.error() — 请求拦截器已统一处理，禁止手动调用
+        const callText = sourceCode.getText(node);
+        if (
+          callText.includes("message.error") &&
+          callText.startsWith("app") &&
+          callText.includes(".error(")
+        ) {
+          context.report({
+            node: node,
+            messageId: "noMessageErrorAny",
+          });
+          return;
+        }
+        // useRequest()
+        if (
+          node.callee.type === "Identifier" &&
+          node.callee.name === "useRequest"
+        ) {
+          useRequestCalls.push(node);
+        }
+
+        // .validateFields()
+        if (
+          node.callee.type === "MemberExpression" &&
+          node.callee.property.type === "Identifier" &&
+          node.callee.property.name === "validateFields"
+        ) {
+          validateFieldsCalls.push(node);
+        }
+      },
+
+      "Program:exit"() {
+        // 1. Form.Item without rules
+        for (const item of formItemNoRules) {
+          context.report({
+            node: item,
+            messageId: "needItemRules",
+          });
+        }
+
+        // 2. message.error in useRequest callbacks
+        for (const call of useRequestCalls) {
+          const options = call.arguments[1];
+          if (!options || options.type !== "ObjectExpression") continue;
+          for (const prop of options.properties) {
+            if (prop.type !== "Property") continue;
+            const key = prop.key;
+            if (
+              key.type !== "Identifier" ||
+              (key.name !== "onSuccess" &&
+                key.name !== "onError" &&
+                key.name !== "onFinally")
+            )
+              continue;
+            const text = sourceCode.getText(prop.value);
+            if (text.includes("message.error")) {
+              context.report({
+                node: prop,
+                messageId: "noMessageError",
+              });
+            }
+          }
+        }
+
+        // 3. Modal.onOk
+        for (const attr of modalOnOkAttrs) {
+          context.report({
+            node: attr,
+            messageId: "noModalOnOk",
+          });
+        }
+
+        // 4. form.validateFields()
+        if (hasFormTag && !hasFormOnFinish) {
+          for (const call of validateFieldsCalls) {
+            context.report({
+              node: call,
+              messageId: "needOnFinish",
+            });
+          }
+        }
+      },
+    };
+  },
+};
+
+export default rule;

package/eslint-rules/require-pro-components.js

@@ -0,0 +1,131 @@
+/**
+ * require-pro-components
+ * ----------------------
+ * 约束前端业务代码：
+ * 1. 禁止直接使用 antd <Modal>，必须用 @ant-design/pro-components 的 <ModalForm>
+ * 2. 禁止直接使用 <Form.Item>，必须用 @ant-design/pro-components 的 ProForm* 组件
+ * 3. ProForm* 组件必须设置 rules 进行校验，否则需要 eslint-disable 注明原因
+ *
+ * 例外场景：
+ * - noStyle 的 Form.Item（仅作布局容器）
+ * - ProForm 容器本身（不是字段组件）
+ * - ProFormDependency、ProFormFieldSet、ProFormList 等非字段组件
+ */
+
+const PROFORM_CONTAINER_COMPONENTS = new Set([
+  "ProForm",
+  "ProFormDependency",
+  "ProFormFieldSet",
+  "ProFormList",
+  "ProFormGrid",
+  "ProFormGroup",
+]);
+
+/** @type {import('eslint').Rule.RuleModule} */
+const rule = {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "禁止直接使用 antd <Modal>（用 ModalForm 代替），禁止直接使用 <Form.Item>（用 ProForm* 代替），ProForm* 必须设置 rules",
+    },
+    schema: [],
+    messages: {
+      useModalForm:
+        "禁止直接使用 antd <Modal>，请使用 @ant-design/pro-components 的 <ModalForm> 代替。",
+      useProFormItem:
+        "禁止直接使用 <Form.Item>，请使用 @ant-design/pro-components 的 ProFormText / ProFormSelect / ProFormItem 等组件代替。",
+      needProFormRules:
+        "<{{tag}}> 必须设置 rules 进行校验。如果确实不需要校验，请用 // eslint-disable-next-line 注明原因。",
+      noSubmitHtmlType:
+        '禁止使用 <Button htmlType="submit">，请使用 ProForm 的 submitter 属性提交表单。',
+    },
+  },
+  create(context) {
+    const getTagName = (name) => {
+      if (name.type === "JSXIdentifier") return name.name;
+      if (
+        name.type === "JSXMemberExpression" &&
+        name.object.type === "JSXIdentifier" &&
+        name.property.type === "JSXIdentifier"
+      ) {
+        return `${name.object.name}.${name.property.name}`;
+      }
+      return "";
+    };
+
+    return {
+      JSXOpeningElement(node) {
+        const tagName = getTagName(node.name);
+
+        // <Modal>
+        if (tagName === "Modal") {
+          context.report({
+            node: node,
+            messageId: "useModalForm",
+          });
+        }
+
+        // <Form.Item>
+        if (tagName === "Form.Item") {
+          let isNoStyle = false;
+          for (const attr of node.attributes) {
+            if (attr.type !== "JSXAttribute" || !attr.name) continue;
+            if (attr.name.name === "noStyle") {
+              isNoStyle = true;
+              break;
+            }
+          }
+          if (!isNoStyle) {
+            context.report({
+              node: node,
+              messageId: "useProFormItem",
+            });
+          }
+        }
+
+        // <Button htmlType="submit">
+        if (tagName === "Button") {
+          for (const attr of node.attributes) {
+            if (attr.type !== "JSXAttribute" || !attr.name) continue;
+            if (
+              attr.name.name === "htmlType" &&
+              attr.value &&
+              attr.value.type === "Literal" &&
+              attr.value.value === "submit"
+            ) {
+              context.report({
+                node: attr,
+                messageId: "noSubmitHtmlType",
+              });
+            }
+          }
+        }
+
+        // ProForm* field components must have rules
+        if (
+          tagName.startsWith("ProForm") &&
+          !PROFORM_CONTAINER_COMPONENTS.has(tagName)
+        ) {
+          let hasRules = false;
+          for (const attr of node.attributes) {
+            if (attr.type !== "JSXAttribute" || !attr.name) continue;
+            if (attr.name.name === "rules") {
+              hasRules = true;
+              break;
+            }
+          }
+          if (!hasRules) {
+            context.report({
+              node: node,
+              messageId: "needProFormRules",
+              data: { tag: tagName },
+            });
+          }
+        }
+      },
+    };
+  },
+};
+
+export default rule;

package/eslint-rules/require-section-divider.js

@@ -0,0 +1,116 @@
+/**
+ * require-section-divider
+ * ------------------------
+ * 约束：大文件必须在顶层用 `=====` 等号注释块做分区。
+ *
+ * 分区要求（按行数）：
+ *   - 150 ~ 349 行：至少 1 个分区块
+ *   - 350 ~ 549 行：至少 2 个分区块
+ *   - 550 ~ 749 行：至少 3 个分区块
+ *   以此类推，每 200 行增加 1 个分区块。
+ *
+ * 分隔注释块格式（见 .agents/skills/dev-style/SKILL.md）：
+ *
+ *   // ==============================================================================
+ *   // <中文标题>
+ *   // ==============================================================================
+ *
+ * 本规则检查文件中所有 ==== 三行注释块的数量是否达到要求。
+ */
+
+const DIVIDER_EQ = /^\s*={4,}\s*$/;
+
+/** 相邻两行注释 + 之间中间一行文字：判定一个三行注释块为分隔块。 */
+function isDividerBlock(commentA, commentB, commentC) {
+  if (!commentA || !commentB || !commentC) return false;
+  if (
+    commentA.type !== "Line" ||
+    commentB.type !== "Line" ||
+    commentC.type !== "Line"
+  )
+    return false;
+  if (!DIVIDER_EQ.test(commentA.value)) return false;
+  if (!DIVIDER_EQ.test(commentC.value)) return false;
+  if (!commentB.value.trim()) return false;
+  if (commentA.loc.end.line + 1 !== commentB.loc.start.line) return false;
+  if (commentB.loc.end.line + 1 !== commentC.loc.start.line) return false;
+  return true;
+}
+
+/** 计算文件需要多少个分区块（每 150 行 1 个，从 150 行起）。 */
+function requiredDividers(totalLines, minLines) {
+  if (totalLines < minLines) return 0;
+  // 150-299: 1个, 300-449: 2个, 依此类推
+  return Math.floor(totalLines / minLines);
+}
+
+/** @type {import('eslint').Rule.RuleModule} */
+const rule = {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "大文件（≥ 150 行）必须按行数用适当数量的 `===` 等号注释块分区。",
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          minLines: { type: "number" },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      missing:
+        "大文件需要更多 `===` 等号注释块分区。当前需要 {{required}} 个，实际只有 {{actual}} 个。每约 150 行至少应有一个分区块。",
+    },
+  },
+  create(context) {
+    const options = context.options[0] || {};
+    const minLines = options.minLines ?? 150;
+    const sourceCode = context.sourceCode ?? context.getSourceCode();
+
+    return {
+      Program(program) {
+        const totalLines = program.loc.end.line;
+        if (totalLines < minLines) return;
+
+        const required = requiredDividers(totalLines, minLines);
+        if (required <= 0) return;
+
+        const allComments = sourceCode.getAllComments();
+
+        let dividerCount = 0;
+        for (let i = 0; i + 2 < allComments.length; i += 1) {
+          if (
+            isDividerBlock(
+              allComments[i],
+              allComments[i + 1],
+              allComments[i + 2],
+            )
+          ) {
+            dividerCount += 1;
+            i += 2;
+          }
+        }
+
+        if (dividerCount < required) {
+          context.report({
+            loc: {
+              start: { line: 1, column: 0 },
+              end: { line: 1, column: 0 },
+            },
+            messageId: "missing",
+            data: {
+              required: String(required),
+              actual: String(dividerCount),
+            },
+          });
+        }
+      },
+    };
+  },
+};
+
+export default rule;

package/eslint-rules/require-use-form.js

@@ -0,0 +1,77 @@
+/**
+ * require-use-form
+ * ----------------
+ * 约束：前端业务代码中，表单组件禁止用 useState/useSetState 管理字段值。
+ * 必须使用 Form.useForm() 或 rc-field-form 的 useForm。
+ *
+ * 检测方式：
+ *   - 文件中出现 JSX 元素且同时包含 value 和 onChange props
+ *   - 同时该文件在顶层使用了 useState 或 useSetState
+ *   → 报错提示改用 useForm
+ *
+ * 例外通过文件路径 overrides 处理（utils、hooks、theme 等已豁免）。
+ */
+
+/** @type {import('eslint').Rule.RuleModule} */
+const rule = {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "表单组件必须使用 Form.useForm() 或 rc-field-form useForm 管理状态，禁止用 useState/useSetState 管理字段值。",
+    },
+    schema: [],
+    messages: {
+      useFormRequired:
+        "检测到表单场景使用了 useState/useSetState 管理字段值。请改用 Form.useForm() 或 rc-field-form 的 useForm。详见 .agents/skills/form-convention/SKILL.md。",
+    },
+  },
+  create(context) {
+    // sourceCode available via context if needed for future enhancement
+
+    // 1. 检测 JSX 元素是否同时包含 value 和 onChange props → 认为是表单组件
+    let hasFormPattern = false;
+
+    // 2. 检测是否有 useState / useSetState 调用
+    let hasStateHook = false;
+
+    const stateHooks = new Set(["useState", "useSetState"]);
+
+    return {
+      JSXOpeningElement(node) {
+        if (hasFormPattern) return;
+
+        let hasValue = false;
+        let hasOnChange = false;
+
+        for (const attr of node.attributes) {
+          if (attr.type !== "JSXAttribute" || !attr.name) continue;
+          const attrName = attr.name.name;
+          if (attrName === "value") hasValue = true;
+          else if (attrName === "onChange") hasOnChange = true;
+
+          if (hasValue && hasOnChange) {
+            hasFormPattern = true;
+            break;
+          }
+        }
+      },
+      CallExpression(node) {
+        const callee = node.callee;
+        if (callee.type === "Identifier" && stateHooks.has(callee.name)) {
+          hasStateHook = true;
+        }
+      },
+      "Program:exit"() {
+        if (hasFormPattern && hasStateHook) {
+          context.report({
+            loc: { line: 1, column: 0 },
+            messageId: "useFormRequired",
+          });
+        }
+      },
+    };
+  },
+};
+
+export default rule;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai0x0/utils",
-  "version": "0.0.26",
+  "version": "0.0.27",
   "description": "AI0x0 utils",
   "keywords": [
     "ai0x0"
@@ -20,6 +20,7 @@
   "module": "./es/index.js",
   "types": "./lib/index.d.ts",
   "files": [
+    "eslint-rules",
     "lib",
     "es",
     "SKILL.md"