@hsu-react/ui 2.4.9 → 2.5.1

package/es/components/Form/DrawerForm/index.js

@@ -20,6 +20,7 @@ import React, { useEffect } from "react";
 import Icon from "../../Icon";
 import classNames from "classnames";
 import styles from "./index.module.scss";
+import { formItemKeys } from "../_utils/formItemKey";
 import useLabelWidth from "../../../hooks/useLabelWidth";
 import usePermissions from "../../../hooks/usePermissions";
 import { mergeSemantic } from "../../../utils/semantic";
@@ -87,13 +88,13 @@ var DrawerForm = function DrawerForm(props) {
     children: [/*#__PURE__*/_jsxs(Form, {
       form: form,
       className: styles.form,
-      children: [formItems === null || formItems === void 0 ? void 0 : formItems.map(function (item) {
+      children: [formItems === null || formItems === void 0 ? void 0 : formItems.map(function (item, idx) {
         var _item$name;
         return /*#__PURE__*/_jsx(FormItem, _objectSpread({
           requiredMsg: (_item$name = item.name) !== null && _item$name !== void 0 && _item$name.endsWith("En") ? "".concat(PlaceholderDictEn[item.type], " ").concat(item.name) : "".concat(PlaceholderDict[item.type]).concat(item.label),
           labelWidth: item.layout === "horizontal" ? labelWidth : undefined,
           className: classNames(styles.formItem, item.className)
-        }, item), item.name);
+        }, item), formItemKeys(formItems)[idx]);
       }), extraFormItems === null || extraFormItems === void 0 ? void 0 : extraFormItems.map(function (item) {
         item = _objectSpread(_objectSpread({}, item), {}, {
           key: item.props.name,

package/es/components/Form/ImportForm/index.js

@@ -22,6 +22,7 @@ import { downloadFile } from "hsu-utils";
 import { get } from "../../../request";
 import { observer } from "mobx-react-lite";
 import styles from "./index.module.scss";
+import { formItemKeys } from "../_utils/formItemKey";
 import useLabelWidth from "../../../hooks/useLabelWidth";
 import usePermissions from "../../../hooks/usePermissions";
 import Modal from "../../Modal";
@@ -101,13 +102,13 @@ var ImportForm = observer(function (props) {
   }, modalConfig), {}, {
     children: /*#__PURE__*/_jsx(Form, {
       className: "".concat(styles.form, " ").concat(formClassName !== null && formClassName !== void 0 ? formClassName : ""),
-      children: formItems === null || formItems === void 0 ? void 0 : formItems.map(function (item) {
+      children: formItems === null || formItems === void 0 ? void 0 : formItems.map(function (item, idx) {
         var _item$requiredMsg, _item$name;
         return /*#__PURE__*/_jsx(FormItem, _objectSpread({
           requiredMsg: (_item$requiredMsg = item.requiredMsg) !== null && _item$requiredMsg !== void 0 ? _item$requiredMsg : (_item$name = item.name) !== null && _item$name !== void 0 && _item$name.endsWith("En") ? "".concat(PlaceholderDictEn[item.type], " ").concat(item.name) : "".concat(PlaceholderDict[item.type]).concat(item.label),
           labelWidth: labelWidth,
           className: "".concat(formItemClassName, " ").concat(item.className)
-        }, item), item.name);
+        }, item), formItemKeys(formItems)[idx]);
       })
     })
   }));

package/es/components/Form/ModalForm/index.js

@@ -19,6 +19,7 @@ import Modal from "../../Modal";
 import FormItem, { PlaceholderDict, PlaceholderDictEn } from "../../FormItem";
 import React, { useEffect, useRef } from "react";
 import styles from "./index.module.scss";
+import { formItemKeys } from "../_utils/formItemKey";
 import usePermissions from "../../../hooks/usePermissions";
 import { useFormItems } from "./_hooks/useFormItems";
 import { mergeSemantic } from "../../../utils/semantic";
@@ -86,6 +87,10 @@ var ModalForm = function ModalForm(props) {
   };
   var adaptiveColumnNum = useAdaptiveColumnNum(formContainer, columnNum, true, 1, undefined, 1200, !!open);
   var _formItems = useFormItems(formItems, layout, adaptiveColumnNum);
+  /* `extraFormItems` 是 JSX 形态的表单项，同样可能重名（互斥字段） */
+  var extraKeys = formItemKeys(extraFormItems === null || extraFormItems === void 0 ? void 0 : extraFormItems.map(function (i) {
+    return i.props;
+  }));
   if (!permitted) {
     return null;
   }
@@ -132,6 +137,8 @@ var ModalForm = function ModalForm(props) {
         onValuesChange: onValuesChange,
         children: [(_Object$keys = Object.keys(_formItems !== null && _formItems !== void 0 ? _formItems : {})) === null || _Object$keys === void 0 ? void 0 : _Object$keys.map(function (key) {
           var _formItems$key;
+          /* key 一次算完（重名的第二条起加 `#n`），别在 map 体里每项重算 */
+          var itemKeys = formItemKeys(_formItems === null || _formItems === void 0 ? void 0 : _formItems[key]);
           return /*#__PURE__*/_jsxs("div", {
             className: "".concat(styles.formItemGroup, " ").concat(formItemGroupClassName !== null && formItemGroupClassName !== void 0 ? formItemGroupClassName : ""),
             id: key,
@@ -143,7 +150,7 @@ var ModalForm = function ModalForm(props) {
               style: {
                 paddingLeft: !key ? 0 : undefined
               },
-              children: _formItems === null || _formItems === void 0 || (_formItems$key = _formItems[key]) === null || _formItems$key === void 0 ? void 0 : _formItems$key.map(function (item) {
+              children: _formItems === null || _formItems === void 0 || (_formItems$key = _formItems[key]) === null || _formItems$key === void 0 ? void 0 : _formItems$key.map(function (item, idx) {
                 var _item$requiredMsg, _item$name;
                 return /*#__PURE__*/_jsx(FormItem, _objectSpread({
                   requiredMsg: (_item$requiredMsg = item.requiredMsg) !== null && _item$requiredMsg !== void 0 ? _item$requiredMsg : (_item$name = item.name) !== null && _item$name !== void 0 && _item$name.endsWith("En") ? "".concat(PlaceholderDictEn[item.type], " ").concat(item.name) : "".concat(PlaceholderDict[item.type]).concat(item.label),
@@ -151,14 +158,16 @@ var ModalForm = function ModalForm(props) {
                   disabled: disabled,
                   required: disabled ? false : item.required,
                   layout: formItemLayout
-                }, item), item.name);
+                }, item), itemKeys[idx]);
               })
             })]
           }, key);
-        }), extraFormItems === null || extraFormItems === void 0 ? void 0 : extraFormItems.map(function (item) {
+        }), extraFormItems === null || extraFormItems === void 0 ? void 0 : extraFormItems.map(function (item, idx) {
           var _item$props$requiredM, _item$props$name;
           item = _objectSpread(_objectSpread({}, item), {}, {
-            key: item.props.name,
+            /* 与上面那组同一套 key 规则：重名的第二条起加 `#n`，
+               按声明顺序编号（见 formItemKeys 的说明） */
+            key: extraKeys[idx],
             props: _objectSpread({
               requiredMsg: (_item$props$requiredM = item.props.requiredMsg) !== null && _item$props$requiredM !== void 0 ? _item$props$requiredM : item.props.type && ((_item$props$name = item.props.name) !== null && _item$props$name !== void 0 && _item$props$name.endsWith("En") ? "".concat(PlaceholderDictEn[item.props.type], " ").concat(item.props.name) : "".concat(PlaceholderDict[item.props.type]).concat(item.props.label)),
               className: "".concat(formItemClassName, " ").concat(item.props.className, " ").concat(styles.formItem),

package/es/components/Form/_utils/formItemKey.d.ts

@@ -0,0 +1,29 @@
+import { FormItemProps } from "../../FormItem";
+/**
+ * 表单项的 React key。
+ *
+ * 原来直接用 `item.name`，而**一个表单有两个互斥、同名的字段是合法的** ——
+ * 消费方真实写法：Bearer Token 用 `PASSWORD`、自定义请求头用 `TEXTAREA`，
+ * 两条都叫 `authValue`，靠 `visible` 互斥。`FormItemProps` 是按 `type` 判别的
+ * 联合类型，把 `type` 写成三元表达式会让 `componentProps` 退化成所有形态的
+ * 交集、编译期就通不过，所以拆成两条是**故意的**，不是写错。
+ *
+ * 于是控制台常年三条
+ * `Encountered two children with the same key, 'authValue'`。
+ * 目前行为无害（两条永远只渲染一个，另一个 return null），但 React 明说
+ * 重复 key 的行为不受支持、将来可能改。
+ *
+ * 修法是重名的第二条起加后缀，而不是改成按下标 —— 按下标会让
+ * 「条件性地从数组里删掉某一项」的表单在删除时整片重挂。
+ *
+ * ⚠️ **按声明数组编号，不能按「可见的那部分」编号。**互斥字段两条都在数组里，
+ * 只是其中一条渲染成 null。若先 `filter(visible)` 再编号，切换的瞬间剩下那条的
+ * key 会从 `authValue#1` 变成 `authValue` —— **key 一变就是重挂**，用户正在输入的
+ * 内容和焦点当场丢，比原来那条警告严重得多。数组是静态写死的，
+ * 按声明顺序编号则天然稳定，切 `visible` 不动 key。
+ *
+ * @param items 声明顺序的表单项数组（**不要预先过滤**）
+ * @returns 与入参等长、下标一一对应的 key 数组
+ */
+export declare const formItemKeys: (items?: FormItemProps[]) => string[];
+export default formItemKeys;

package/es/components/Form/_utils/formItemKey.js

@@ -0,0 +1,38 @@
+/**
+ * 表单项的 React key。
+ *
+ * 原来直接用 `item.name`，而**一个表单有两个互斥、同名的字段是合法的** ——
+ * 消费方真实写法：Bearer Token 用 `PASSWORD`、自定义请求头用 `TEXTAREA`，
+ * 两条都叫 `authValue`，靠 `visible` 互斥。`FormItemProps` 是按 `type` 判别的
+ * 联合类型，把 `type` 写成三元表达式会让 `componentProps` 退化成所有形态的
+ * 交集、编译期就通不过，所以拆成两条是**故意的**，不是写错。
+ *
+ * 于是控制台常年三条
+ * `Encountered two children with the same key, 'authValue'`。
+ * 目前行为无害（两条永远只渲染一个，另一个 return null），但 React 明说
+ * 重复 key 的行为不受支持、将来可能改。
+ *
+ * 修法是重名的第二条起加后缀，而不是改成按下标 —— 按下标会让
+ * 「条件性地从数组里删掉某一项」的表单在删除时整片重挂。
+ *
+ * ⚠️ **按声明数组编号，不能按「可见的那部分」编号。**互斥字段两条都在数组里，
+ * 只是其中一条渲染成 null。若先 `filter(visible)` 再编号，切换的瞬间剩下那条的
+ * key 会从 `authValue#1` 变成 `authValue` —— **key 一变就是重挂**，用户正在输入的
+ * 内容和焦点当场丢，比原来那条警告严重得多。数组是静态写死的，
+ * 按声明顺序编号则天然稳定，切 `visible` 不动 key。
+ *
+ * @param items 声明顺序的表单项数组（**不要预先过滤**）
+ * @returns 与入参等长、下标一一对应的 key 数组
+ */
+export var formItemKeys = function formItemKeys(items) {
+  var used = {};
+  return (items !== null && items !== void 0 ? items : []).map(function (item, idx) {
+    var _used$name;
+    // name 缺省时退回下标：没有名字的项本来就互不相同，用下标不会撞
+    var name = (item === null || item === void 0 ? void 0 : item.name) == null ? "#".concat(idx) : String(item.name);
+    var seen = (_used$name = used[name]) !== null && _used$name !== void 0 ? _used$name : 0;
+    used[name] = seen + 1;
+    return seen === 0 ? name : "".concat(name, "#").concat(seen);
+  });
+};
+export default formItemKeys;

package/es/components/FormItem/FormInput/FormInputNumber/index.d.ts

@@ -2,7 +2,23 @@ import { ItemContainerProps } from "../../ItemContainer";
 import { InputNumberProps } from "../../../Input/Number";
 import React from "react";
 export interface FormInputNumberProps extends ItemContainerProps {
-    componentProps?: InputNumberProps;
+    /**
+     * `onChange` 的签名比基础组件宽：作为**表单字段**，默认交出的是
+     * `number | null`（见 Bridge 的注释）。写这个回调的人拿到的与表单拿到的
+     * 是同一个值。
+     */
+    componentProps?: Omit<InputNumberProps, "onChange"> & {
+        onChange?: (value: string | number | null) => void;
+    };
+    /**
+     * 交给表单的是字符串而不是数字。默认 `false`。
+     *
+     * 只有真的要处理**超出 IEEE754 安全范围的大数**（订单号、雪花 ID）时才打开
+     * —— 那种值转成 number 会丢精度，必须一路以字符串传递。
+     *
+     * 2.5.0 之前没有这个开关，行为固定等同于 `stringMode`（见下方 Bridge 注释）。
+     */
+    stringMode?: boolean;
 }
 declare const FormInputNumber: React.FC<FormInputNumberProps>;
 export default FormInputNumber;

package/es/components/FormItem/FormInput/FormInputNumber/index.js

@@ -1,6 +1,7 @@
 function _typeof(o) { "@babel/helpers - typeof"; return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (o) { return typeof o; } : function (o) { return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o; }, _typeof(o); }
-var _excluded = ["componentProps", "className", "disabled"],
-  _excluded2 = ["placeholder"];
+var _excluded = ["value", "onChange", "componentOnChange", "stringMode"],
+  _excluded2 = ["componentProps", "className", "disabled", "stringMode"],
+  _excluded3 = ["placeholder", "onChange"];
 function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
 function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
 function _defineProperty(obj, key, value) { key = _toPropertyKey(key); if (key in obj) { Object.defineProperty(obj, key, { value: value, enumerable: true, configurable: true, writable: true }); } else { obj[key] = value; } return obj; }
@@ -11,19 +12,77 @@ function _objectWithoutPropertiesLoose(source, excluded) { if (source == null) r
 import ItemContainer from "../../ItemContainer";
 import Input from "../../../Input";
 import React from "react";
+
+// value / onChange 要重新声明：`InputNumberProps` 上那两个是**基础组件**的
+// 契约（字符串进、字符串出），而这里收的是**表单值**，可以是数字或 null
 import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * 夹在 `Form.Item` 与 `Input.Number` 之间，**把字符串换成数字再交给表单**。
+ *
+ * 为什么需要它：`Input.Number` 内部以字符串保存（底层 `stringMode`，为的是不
+ * 丢大数精度），`onChange` 交出的也是字符串。这对一个**基础输入组件**是合理
+ * 的，但对一个叫 INPUTNUMBER 的**表单字段**不合理 —— 表单收上去的值会直接
+ * 进请求体，而后端字段多半是整数：
+ *
+ * ```
+ * 422  invalid type: string "2", expected i32
+ * ```
+ *
+ * 这个坑平时看不见：没动过的字段，值来自详情接口、本来就是数字，原样发回去
+ * 没事；**只有用户真的改了那一格**才会变成字符串。现象是「我明明只改了个
+ * 数字却保存失败」，而且报错在服务端，前端一行日志都没有。
+ *
+ * 转换只在**往上交**的方向做；`Input.Number` 内部仍然是字符串，所以正在敲的
+ * "1." / "1.50" 不会被改写（配套改动见 `Input/Number` 里的 sameNumber 判断）。
+ */
+var Bridge = function Bridge(props) {
+  var value = props.value,
+    onChange = props.onChange,
+    componentOnChange = props.componentOnChange,
+    stringMode = props.stringMode,
+    rest = _objectWithoutProperties(props, _excluded);
+  var emit = function emit(next) {
+    onChange === null || onChange === void 0 || onChange(next);
+    componentOnChange === null || componentOnChange === void 0 || componentOnChange(next);
+  };
+  return /*#__PURE__*/_jsx(Input.Number, _objectSpread(_objectSpread({}, rest), {}, {
+    value: value,
+    onChange: function onChange(text) {
+      if (stringMode) {
+        emit(text);
+        return;
+      }
+
+      // 空 → null 而不是 ""：语义是「没填」，不是「填了个空字符串」。
+      // 后端 `Option<i32>` 收得下 null，收不下 ""
+      if (text === "" || text === null || text === undefined) {
+        emit(null);
+        return;
+      }
+      var num = Number(text);
+      // 转不动就原样交出去（用户可能正敲到 "-" 或 "1e" 这种中间态）。
+      // 硬转成 NaN 会让表单里躺着一个既非数字也非空的值
+      emit(Number.isFinite(num) ? num : text);
+    }
+  }));
+};
 var FormInputNumber = function FormInputNumber(props) {
   var _inputConfig$disabled;
   var _props$componentProps = props.componentProps,
     componentProps = _props$componentProps === void 0 ? {} : _props$componentProps,
     itemClassName = props.className,
     disabled = props.disabled,
-    formItemProps = _objectWithoutProperties(props, _excluded);
+    stringMode = props.stringMode,
+    formItemProps = _objectWithoutProperties(props, _excluded2);
+  // onChange 必须摘出来，理由见 BridgeProps.componentOnChange
   var placeholder = componentProps.placeholder,
-    inputConfig = _objectWithoutProperties(componentProps, _excluded2);
+    componentOnChange = componentProps.onChange,
+    inputConfig = _objectWithoutProperties(componentProps, _excluded3);
   return /*#__PURE__*/_jsx(ItemContainer, _objectSpread(_objectSpread({}, formItemProps), {}, {
     className: "".concat(itemClassName !== null && itemClassName !== void 0 ? itemClassName : ""),
-    children: /*#__PURE__*/_jsx(Input.Number, _objectSpread(_objectSpread({}, inputConfig), {}, {
+    children: /*#__PURE__*/_jsx(Bridge, _objectSpread(_objectSpread({}, inputConfig), {}, {
+      componentOnChange: componentOnChange,
+      stringMode: stringMode,
       disabled: (_inputConfig$disabled = inputConfig.disabled) !== null && _inputConfig$disabled !== void 0 ? _inputConfig$disabled : disabled,
       placeholder: placeholder !== null && placeholder !== void 0 ? placeholder : "请输入"
     }))

package/es/components/Input/Number/index.d.ts

@@ -3,7 +3,11 @@ import React from "react";
 export interface InputNumberProps extends Omit<AntdInputNumberProps, "ref" | "onChange" | "value"> {
     getRef?: (ref: HTMLInputElement | null) => void;
     onChange?: (value: string) => void;
-    value?: string;
+    /**
+     * 受控值。本组件内部**始终以字符串保存**（底层开了 antd 的 `stringMode`，
+     * 为的是不丢大数精度），但外部传数字进来也接得住。
+     */
+    value?: string | number | null;
     allowClear?: boolean;
     wrapperClassName?: string;
 }

package/es/components/Input/Number/index.js

@@ -64,16 +64,33 @@ var InputNumber = function InputNumber(props) {
     // Update internal state only when the external value prop actually changes
     if (prevValueRef.current !== value) {
       prevValueRef.current = value;
-      if (value !== undefined) {
+
+      // 数值相等就不要回写文本。
+      //
+      // 上游把值转成数字之后（`FormItem` 的 INPUTNUMBER 默认就会转），一个
+      // 回环会打回来：输入 "1." → onChange → 表单存 1 → value={1} 传回来。
+      // 若照单全收地写成 "1"，用户刚敲的小数点当场消失、光标还会跳到末尾，
+      // "1.50" 也会被改写成 "1.5"。
+      //
+      // 判据用**数值相等**而不是字符串相等：这几种写法（"1." / "1.50" / "+1"）
+      // 表示的是同一个数，此时以用户正在敲的那份文本为准。
+      var sameNumber = value !== undefined && value !== null && _value !== "" && Number(value) === Number(_value);
+      if (sameNumber) {
+        // 只同步「已提交值」，不动正在编辑的文本
+        setLastValue(_value);
+      } else if (value !== undefined && value !== null) {
         var newValue = typeof value === "number" ? "".concat(value) : value === null || value === void 0 ? void 0 : value.toString();
         setValue(newValue);
         setLastValue(newValue);
       } else {
-        // Clear only on initialization or when explicitly set to undefined externally
+        // Clear only on initialization or when explicitly set to undefined/null externally
         setValue("");
         setLastValue("");
       }
     }
+    // `_value` 是刻意不进依赖的：这个 effect 只该在**外部** value 变化时跑，
+    // 把它加进来会让每次键入都重跑一遍，等于绕过上面那个 prevValueRef 判断
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [value]);
   useEffect(function () {
     getRef === null || getRef === void 0 || getRef(ref.current);

package/es/components/Markdown/Views/index.js

@@ -12,6 +12,7 @@ import React, { createContext, useContext, useId } from "react";
 import ReactMarkdown from "react-markdown";
 import rehypeHighlight from "rehype-highlight";
 import rehypeKatex from "rehype-katex";
+import remarkCjkFriendly from "remark-cjk-friendly";
 import remarkGfm from "remark-gfm";
 import remarkMath from "remark-math";
 import classNames from "classnames";
@@ -134,8 +135,14 @@ var MarkdownViews = function MarkdownViews(props) {
     _jsx(CopyPropsContext.Provider, {
       value: copyProps,
       children: /*#__PURE__*/_jsx(ReactMarkdown, _objectSpread(_objectSpread({}, props), {}, {
-        rehypePlugins: [rehypeHighlight, rehypeKatex],
-        remarkPlugins: [remarkGfm, remarkMath],
+        rehypePlugins: [rehypeHighlight, rehypeKatex]
+        /* `remarkCjkFriendly` 修的是中文里最常见的一处 markdown 失效：
+           `我得先知道**「这件事」是什么**` —— 开头那对 `**` 后面跟着 `「`
+           （标点）、前面是 `道`（非空白非标点），按 CommonMark 的 flanking 规则
+           它不是左侧定界符，于是整段**原样显示两个星号**。
+           而中文里「**「…」**」「**《…》**」这种写法极常见，模型输出里到处都是。
+           这个插件按 CJK 友好规则重判 flanking，是这条规则的通行修法。 */,
+        remarkPlugins: [remarkCjkFriendly, remarkGfm, remarkMath],
         className: classNames(styles.MarkdownViews, className, "markdown-body"),
         components: _objectSpread({
           code: CodeBlock,

package/lib/components/Form/DrawerForm/index.js

@@ -11,6 +11,7 @@ var _react = _interopRequireWildcard(require("react"));
 var _Icon = _interopRequireDefault(require("../../Icon"));
 var _classnames = _interopRequireDefault(require("classnames"));
 var _indexModule = _interopRequireDefault(require("./index.module.scss"));
+var _formItemKey = require("../_utils/formItemKey");
 var _useLabelWidth = _interopRequireDefault(require("../../../hooks/useLabelWidth"));
 var _usePermissions = _interopRequireDefault(require("../../../hooks/usePermissions"));
 var _semantic = require("../../../utils/semantic");
@@ -77,12 +78,12 @@ const DrawerForm = props => {
     children: [/*#__PURE__*/(0, _jsxRuntime.jsxs)(_antd.Form, {
       form: form,
       className: _indexModule.default.form,
-      children: [formItems?.map(item => /*#__PURE__*/(0, _jsxRuntime.jsx)(_FormItem.default, {
+      children: [formItems?.map((item, idx) => /*#__PURE__*/(0, _jsxRuntime.jsx)(_FormItem.default, {
         requiredMsg: item.name?.endsWith("En") ? `${_FormItem.PlaceholderDictEn[item.type]} ${item.name}` : `${_FormItem.PlaceholderDict[item.type]}${item.label}`,
         labelWidth: item.layout === "horizontal" ? labelWidth : undefined,
         className: (0, _classnames.default)(_indexModule.default.formItem, item.className),
         ...item
-      }, item.name)), extraFormItems?.map(item => {
+      }, (0, _formItemKey.formItemKeys)(formItems)[idx])), extraFormItems?.map(item => {
         item = {
           ...item,
           key: item.props.name,

package/lib/components/Form/ImportForm/index.js

@@ -13,6 +13,7 @@ var _hsuUtils = require("hsu-utils");
 var _request = require("../../../request");
 var _mobxReactLite = require("mobx-react-lite");
 var _indexModule = _interopRequireDefault(require("./index.module.scss"));
+var _formItemKey = require("../_utils/formItemKey");
 var _useLabelWidth = _interopRequireDefault(require("../../../hooks/useLabelWidth"));
 var _usePermissions = _interopRequireDefault(require("../../../hooks/usePermissions"));
 var _Modal = _interopRequireDefault(require("../../Modal"));
@@ -93,12 +94,12 @@ const ImportForm = (0, _mobxReactLite.observer)(props => {
     ...modalConfig,
     children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_antd.Form, {
       className: `${_indexModule.default.form} ${formClassName ?? ""}`,
-      children: formItems?.map(item => /*#__PURE__*/(0, _jsxRuntime.jsx)(_FormItem.default, {
+      children: formItems?.map((item, idx) => /*#__PURE__*/(0, _jsxRuntime.jsx)(_FormItem.default, {
         requiredMsg: item.requiredMsg ?? (item.name?.endsWith("En") ? `${_FormItem.PlaceholderDictEn[item.type]} ${item.name}` : `${_FormItem.PlaceholderDict[item.type]}${item.label}`),
         labelWidth: labelWidth,
         className: `${formItemClassName} ${item.className}`,
         ...item
-      }, item.name))
+      }, (0, _formItemKey.formItemKeys)(formItems)[idx]))
     })
   });
 });

package/lib/components/Form/ModalForm/index.js

@@ -10,6 +10,7 @@ var _Modal = _interopRequireDefault(require("../../Modal"));
 var _FormItem = _interopRequireWildcard(require("../../FormItem"));
 var _react = _interopRequireWildcard(require("react"));
 var _indexModule = _interopRequireDefault(require("./index.module.scss"));
+var _formItemKey = require("../_utils/formItemKey");
 var _usePermissions = _interopRequireDefault(require("../../../hooks/usePermissions"));
 var _useFormItems = require("./_hooks/useFormItems");
 var _semantic = require("../../../utils/semantic");
@@ -73,6 +74,8 @@ const ModalForm = props => {
   };
   const adaptiveColumnNum = (0, _useAdaptiveColumnNum.useAdaptiveColumnNum)(formContainer, columnNum, true, 1, undefined, 1200, !!open);
   const _formItems = (0, _useFormItems.useFormItems)(formItems, layout, adaptiveColumnNum);
+  /* `extraFormItems` 是 JSX 形态的表单项，同样可能重名（互斥字段） */
+  const extraKeys = (0, _formItemKey.formItemKeys)(extraFormItems?.map(i => i.props));
   if (!permitted) {
     return null;
   }
@@ -107,30 +110,36 @@ const ModalForm = props => {
           "--column-num": adaptiveColumnNum
         },
         onValuesChange: onValuesChange,
-        children: [Object.keys(_formItems ?? {})?.map(key => /*#__PURE__*/(0, _jsxRuntime.jsxs)("div", {
-          className: `${_indexModule.default.formItemGroup} ${formItemGroupClassName ?? ""}`,
-          id: key,
-          children: [key && /*#__PURE__*/(0, _jsxRuntime.jsx)("div", {
-            className: `${_indexModule.default.formItemTitle} ${formItemGroupTitleClassName ?? ""}`,
-            children: key
-          }), /*#__PURE__*/(0, _jsxRuntime.jsx)("div", {
-            className: _indexModule.default.formItemGroupContent,
-            style: {
-              paddingLeft: !key ? 0 : undefined
-            },
-            children: _formItems?.[key]?.map(item => /*#__PURE__*/(0, _jsxRuntime.jsx)(_FormItem.default, {
-              requiredMsg: item.requiredMsg ?? (item.name?.endsWith("En") ? `${_FormItem.PlaceholderDictEn[item.type]} ${item.name}` : `${_FormItem.PlaceholderDict[item.type]}${item.label}`),
-              className: `${formItemClassName} ${item.className} ${_indexModule.default.formItem}`,
-              disabled: disabled,
-              required: disabled ? false : item.required,
-              layout: formItemLayout,
-              ...item
-            }, item.name))
-          })]
-        }, key)), extraFormItems?.map(item => {
+        children: [Object.keys(_formItems ?? {})?.map(key => {
+          /* key 一次算完（重名的第二条起加 `#n`），别在 map 体里每项重算 */
+          const itemKeys = (0, _formItemKey.formItemKeys)(_formItems?.[key]);
+          return /*#__PURE__*/(0, _jsxRuntime.jsxs)("div", {
+            className: `${_indexModule.default.formItemGroup} ${formItemGroupClassName ?? ""}`,
+            id: key,
+            children: [key && /*#__PURE__*/(0, _jsxRuntime.jsx)("div", {
+              className: `${_indexModule.default.formItemTitle} ${formItemGroupTitleClassName ?? ""}`,
+              children: key
+            }), /*#__PURE__*/(0, _jsxRuntime.jsx)("div", {
+              className: _indexModule.default.formItemGroupContent,
+              style: {
+                paddingLeft: !key ? 0 : undefined
+              },
+              children: _formItems?.[key]?.map((item, idx) => /*#__PURE__*/(0, _jsxRuntime.jsx)(_FormItem.default, {
+                requiredMsg: item.requiredMsg ?? (item.name?.endsWith("En") ? `${_FormItem.PlaceholderDictEn[item.type]} ${item.name}` : `${_FormItem.PlaceholderDict[item.type]}${item.label}`),
+                className: `${formItemClassName} ${item.className} ${_indexModule.default.formItem}`,
+                disabled: disabled,
+                required: disabled ? false : item.required,
+                layout: formItemLayout,
+                ...item
+              }, itemKeys[idx]))
+            })]
+          }, key);
+        }), extraFormItems?.map((item, idx) => {
           item = {
             ...item,
-            key: item.props.name,
+            /* 与上面那组同一套 key 规则：重名的第二条起加 `#n`，
+               按声明顺序编号（见 formItemKeys 的说明） */
+            key: extraKeys[idx],
             props: {
               requiredMsg: item.props.requiredMsg ?? (item.props.type && (item.props.name?.endsWith("En") ? `${_FormItem.PlaceholderDictEn[item.props.type]} ${item.props.name}` : `${_FormItem.PlaceholderDict[item.props.type]}${item.props.label}`)),
               className: `${formItemClassName} ${item.props.className} ${_indexModule.default.formItem}`,

package/lib/components/Form/_utils/formItemKey.d.ts

@@ -0,0 +1,29 @@
+import { FormItemProps } from "../../FormItem";
+/**
+ * 表单项的 React key。
+ *
+ * 原来直接用 `item.name`，而**一个表单有两个互斥、同名的字段是合法的** ——
+ * 消费方真实写法：Bearer Token 用 `PASSWORD`、自定义请求头用 `TEXTAREA`，
+ * 两条都叫 `authValue`，靠 `visible` 互斥。`FormItemProps` 是按 `type` 判别的
+ * 联合类型，把 `type` 写成三元表达式会让 `componentProps` 退化成所有形态的
+ * 交集、编译期就通不过，所以拆成两条是**故意的**，不是写错。
+ *
+ * 于是控制台常年三条
+ * `Encountered two children with the same key, 'authValue'`。
+ * 目前行为无害（两条永远只渲染一个，另一个 return null），但 React 明说
+ * 重复 key 的行为不受支持、将来可能改。
+ *
+ * 修法是重名的第二条起加后缀，而不是改成按下标 —— 按下标会让
+ * 「条件性地从数组里删掉某一项」的表单在删除时整片重挂。
+ *
+ * ⚠️ **按声明数组编号，不能按「可见的那部分」编号。**互斥字段两条都在数组里，
+ * 只是其中一条渲染成 null。若先 `filter(visible)` 再编号，切换的瞬间剩下那条的
+ * key 会从 `authValue#1` 变成 `authValue` —— **key 一变就是重挂**，用户正在输入的
+ * 内容和焦点当场丢，比原来那条警告严重得多。数组是静态写死的，
+ * 按声明顺序编号则天然稳定，切 `visible` 不动 key。
+ *
+ * @param items 声明顺序的表单项数组（**不要预先过滤**）
+ * @returns 与入参等长、下标一一对应的 key 数组
+ */
+export declare const formItemKeys: (items?: FormItemProps[]) => string[];
+export default formItemKeys;

package/lib/components/Form/_utils/formItemKey.js

@@ -0,0 +1,44 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.formItemKeys = exports.default = void 0;
+/**
+ * 表单项的 React key。
+ *
+ * 原来直接用 `item.name`，而**一个表单有两个互斥、同名的字段是合法的** ——
+ * 消费方真实写法：Bearer Token 用 `PASSWORD`、自定义请求头用 `TEXTAREA`，
+ * 两条都叫 `authValue`，靠 `visible` 互斥。`FormItemProps` 是按 `type` 判别的
+ * 联合类型，把 `type` 写成三元表达式会让 `componentProps` 退化成所有形态的
+ * 交集、编译期就通不过，所以拆成两条是**故意的**，不是写错。
+ *
+ * 于是控制台常年三条
+ * `Encountered two children with the same key, 'authValue'`。
+ * 目前行为无害（两条永远只渲染一个，另一个 return null），但 React 明说
+ * 重复 key 的行为不受支持、将来可能改。
+ *
+ * 修法是重名的第二条起加后缀，而不是改成按下标 —— 按下标会让
+ * 「条件性地从数组里删掉某一项」的表单在删除时整片重挂。
+ *
+ * ⚠️ **按声明数组编号，不能按「可见的那部分」编号。**互斥字段两条都在数组里，
+ * 只是其中一条渲染成 null。若先 `filter(visible)` 再编号，切换的瞬间剩下那条的
+ * key 会从 `authValue#1` 变成 `authValue` —— **key 一变就是重挂**，用户正在输入的
+ * 内容和焦点当场丢，比原来那条警告严重得多。数组是静态写死的，
+ * 按声明顺序编号则天然稳定，切 `visible` 不动 key。
+ *
+ * @param items 声明顺序的表单项数组（**不要预先过滤**）
+ * @returns 与入参等长、下标一一对应的 key 数组
+ */
+const formItemKeys = items => {
+  const used = {};
+  return (items ?? []).map((item, idx) => {
+    // name 缺省时退回下标：没有名字的项本来就互不相同，用下标不会撞
+    const name = item?.name == null ? `#${idx}` : String(item.name);
+    const seen = used[name] ?? 0;
+    used[name] = seen + 1;
+    return seen === 0 ? name : `${name}#${seen}`;
+  });
+};
+exports.formItemKeys = formItemKeys;
+var _default = exports.default = formItemKeys;

package/lib/components/FormItem/FormInput/FormInputNumber/index.d.ts

@@ -2,7 +2,23 @@ import { ItemContainerProps } from "../../ItemContainer";
 import { InputNumberProps } from "../../../Input/Number";
 import React from "react";
 export interface FormInputNumberProps extends ItemContainerProps {
-    componentProps?: InputNumberProps;
+    /**
+     * `onChange` 的签名比基础组件宽：作为**表单字段**，默认交出的是
+     * `number | null`（见 Bridge 的注释）。写这个回调的人拿到的与表单拿到的
+     * 是同一个值。
+     */
+    componentProps?: Omit<InputNumberProps, "onChange"> & {
+        onChange?: (value: string | number | null) => void;
+    };
+    /**
+     * 交给表单的是字符串而不是数字。默认 `false`。
+     *
+     * 只有真的要处理**超出 IEEE754 安全范围的大数**（订单号、雪花 ID）时才打开
+     * —— 那种值转成 number 会丢精度，必须一路以字符串传递。
+     *
+     * 2.5.0 之前没有这个开关，行为固定等同于 `stringMode`（见下方 Bridge 注释）。
+     */
+    stringMode?: boolean;
 }
 declare const FormInputNumber: React.FC<FormInputNumberProps>;
 export default FormInputNumber;

package/lib/components/FormItem/FormInput/FormInputNumber/index.js

@@ -9,22 +9,83 @@ var _Input = _interopRequireDefault(require("../../../Input"));
 var _react = _interopRequireDefault(require("react"));
 var _jsxRuntime = require("react/jsx-runtime");
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+// value / onChange 要重新声明：`InputNumberProps` 上那两个是**基础组件**的
+// 契约（字符串进、字符串出），而这里收的是**表单值**，可以是数字或 null
+
+/**
+ * 夹在 `Form.Item` 与 `Input.Number` 之间，**把字符串换成数字再交给表单**。
+ *
+ * 为什么需要它：`Input.Number` 内部以字符串保存（底层 `stringMode`，为的是不
+ * 丢大数精度），`onChange` 交出的也是字符串。这对一个**基础输入组件**是合理
+ * 的，但对一个叫 INPUTNUMBER 的**表单字段**不合理 —— 表单收上去的值会直接
+ * 进请求体，而后端字段多半是整数：
+ *
+ * ```
+ * 422  invalid type: string "2", expected i32
+ * ```
+ *
+ * 这个坑平时看不见：没动过的字段，值来自详情接口、本来就是数字，原样发回去
+ * 没事；**只有用户真的改了那一格**才会变成字符串。现象是「我明明只改了个
+ * 数字却保存失败」，而且报错在服务端，前端一行日志都没有。
+ *
+ * 转换只在**往上交**的方向做；`Input.Number` 内部仍然是字符串，所以正在敲的
+ * "1." / "1.50" 不会被改写（配套改动见 `Input/Number` 里的 sameNumber 判断）。
+ */
+const Bridge = props => {
+  const {
+    value,
+    onChange,
+    componentOnChange,
+    stringMode,
+    ...rest
+  } = props;
+  const emit = next => {
+    onChange?.(next);
+    componentOnChange?.(next);
+  };
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_Input.default.Number, {
+    ...rest,
+    value: value,
+    onChange: text => {
+      if (stringMode) {
+        emit(text);
+        return;
+      }
+
+      // 空 → null 而不是 ""：语义是「没填」，不是「填了个空字符串」。
+      // 后端 `Option<i32>` 收得下 null，收不下 ""
+      if (text === "" || text === null || text === undefined) {
+        emit(null);
+        return;
+      }
+      const num = Number(text);
+      // 转不动就原样交出去（用户可能正敲到 "-" 或 "1e" 这种中间态）。
+      // 硬转成 NaN 会让表单里躺着一个既非数字也非空的值
+      emit(Number.isFinite(num) ? num : text);
+    }
+  });
+};
 const FormInputNumber = props => {
   const {
     componentProps = {},
     className: itemClassName,
     disabled,
+    stringMode,
     ...formItemProps
   } = props;
+  // onChange 必须摘出来，理由见 BridgeProps.componentOnChange
   const {
     placeholder,
+    onChange: componentOnChange,
     ...inputConfig
   } = componentProps;
   return /*#__PURE__*/(0, _jsxRuntime.jsx)(_ItemContainer.default, {
     ...formItemProps,
     className: `${itemClassName ?? ""}`,
-    children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_Input.default.Number, {
+    children: /*#__PURE__*/(0, _jsxRuntime.jsx)(Bridge, {
       ...inputConfig,
+      componentOnChange: componentOnChange,
+      stringMode: stringMode,
       disabled: inputConfig.disabled ?? disabled,
       placeholder: placeholder ?? "请输入"
     })

package/lib/components/Input/Number/index.d.ts

@@ -3,7 +3,11 @@ import React from "react";
 export interface InputNumberProps extends Omit<AntdInputNumberProps, "ref" | "onChange" | "value"> {
     getRef?: (ref: HTMLInputElement | null) => void;
     onChange?: (value: string) => void;
-    value?: string;
+    /**
+     * 受控值。本组件内部**始终以字符串保存**（底层开了 antd 的 `stringMode`，
+     * 为的是不丢大数精度），但外部传数字进来也接得住。
+     */
+    value?: string | number | null;
     allowClear?: boolean;
     wrapperClassName?: string;
 }

package/lib/components/Input/Number/index.js

@@ -50,16 +50,33 @@ const InputNumber = props => {
     // Update internal state only when the external value prop actually changes
     if (prevValueRef.current !== value) {
       prevValueRef.current = value;
-      if (value !== undefined) {
+
+      // 数值相等就不要回写文本。
+      //
+      // 上游把值转成数字之后（`FormItem` 的 INPUTNUMBER 默认就会转），一个
+      // 回环会打回来：输入 "1." → onChange → 表单存 1 → value={1} 传回来。
+      // 若照单全收地写成 "1"，用户刚敲的小数点当场消失、光标还会跳到末尾，
+      // "1.50" 也会被改写成 "1.5"。
+      //
+      // 判据用**数值相等**而不是字符串相等：这几种写法（"1." / "1.50" / "+1"）
+      // 表示的是同一个数，此时以用户正在敲的那份文本为准。
+      const sameNumber = value !== undefined && value !== null && _value !== "" && Number(value) === Number(_value);
+      if (sameNumber) {
+        // 只同步「已提交值」，不动正在编辑的文本
+        setLastValue(_value);
+      } else if (value !== undefined && value !== null) {
         const newValue = typeof value === "number" ? `${value}` : value?.toString();
         setValue(newValue);
         setLastValue(newValue);
       } else {
-        // Clear only on initialization or when explicitly set to undefined externally
+        // Clear only on initialization or when explicitly set to undefined/null externally
         setValue("");
         setLastValue("");
       }
     }
+    // `_value` 是刻意不进依赖的：这个 effect 只该在**外部** value 变化时跑，
+    // 把它加进来会让每次键入都重跑一遍，等于绕过上面那个 prevValueRef 判断
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [value]);
   (0, _react.useEffect)(() => {
     getRef?.(ref.current);

package/lib/components/Markdown/Views/index.js

@@ -8,6 +8,7 @@ var _react = _interopRequireWildcard(require("react"));
 var _reactMarkdown = _interopRequireDefault(require("react-markdown"));
 var _rehypeHighlight = _interopRequireDefault(require("rehype-highlight"));
 var _rehypeKatex = _interopRequireDefault(require("rehype-katex"));
+var _remarkCjkFriendly = _interopRequireDefault(require("remark-cjk-friendly"));
 var _remarkGfm = _interopRequireDefault(require("remark-gfm"));
 var _remarkMath = _interopRequireDefault(require("remark-math"));
 var _classnames = _interopRequireDefault(require("classnames"));
@@ -137,8 +138,14 @@ const MarkdownViews = props => {
       value: copyProps,
       children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactMarkdown.default, {
         ...props,
-        rehypePlugins: [_rehypeHighlight.default, _rehypeKatex.default],
-        remarkPlugins: [_remarkGfm.default, _remarkMath.default],
+        rehypePlugins: [_rehypeHighlight.default, _rehypeKatex.default]
+        /* `remarkCjkFriendly` 修的是中文里最常见的一处 markdown 失效：
+           `我得先知道**「这件事」是什么**` —— 开头那对 `**` 后面跟着 `「`
+           （标点）、前面是 `道`（非空白非标点），按 CommonMark 的 flanking 规则
+           它不是左侧定界符，于是整段**原样显示两个星号**。
+           而中文里「**「…」**」「**《…》**」这种写法极常见，模型输出里到处都是。
+           这个插件按 CJK 友好规则重判 flanking，是这条规则的通行修法。 */,
+        remarkPlugins: [_remarkCjkFriendly.default, _remarkGfm.default, _remarkMath.default],
         className: (0, _classnames.default)(_indexModule.default.MarkdownViews, className, "markdown-body"),
         components: {
           code: CodeBlock,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hsu-react/ui",
-  "version": "2.4.9",
+  "version": "2.5.1",
   "description": "一套基于 React + Ant Design 的中后台业务组件库",
   "license": "MIT",
   "type": "module",
@@ -93,6 +93,7 @@
     "react-markdown-editor-lite": "^1.3.4",
     "rehype-highlight": "^7.0.2",
     "rehype-katex": "^7.0.1",
+    "remark-cjk-friendly": "2.3.1",
     "remark-gfm": "^4.0.1",
     "remark-math": "^6.0.0",
     "turndown": "^7.2.0",

package/src/components/Form/DrawerForm/index.tsx

@@ -11,6 +11,7 @@ import Icon from "../../Icon";
 import { ItemContainerProps } from "../../FormItem/ItemContainer";
 import classNames from "classnames";
 import styles from "./index.module.scss";
+import { formItemKeys } from "../_utils/formItemKey";
 import useLabelWidth from "../../../hooks/useLabelWidth";
 import usePermissions from "../../../hooks/usePermissions";
 import { mergeSemantic } from "../../../utils/semantic";
@@ -89,9 +90,9 @@ const DrawerForm: React.FC<DrawerFormProps> = (props) => {
       {...drawerConfig}
     >
       <Form form={form} className={styles.form}>
-        {formItems?.map((item) => (
+        {formItems?.map((item, idx) => (
           <FormItem
-            key={item.name}
+            key={formItemKeys(formItems)[idx]}
             requiredMsg={
               (item.name as string)?.endsWith("En")
                 ? `${PlaceholderDictEn[item.type]} ${item.name}`

package/src/components/Form/ImportForm/index.tsx

@@ -13,6 +13,7 @@ import { downloadFile } from "hsu-utils";
 import { get } from "../../../request";
 import { observer } from "mobx-react-lite";
 import styles from "./index.module.scss";
+import { formItemKeys } from "../_utils/formItemKey";
 import useLabelWidth from "../../../hooks/useLabelWidth";
 import usePermissions from "../../../hooks/usePermissions";
 import Modal, { ModalProps } from "../../Modal";
@@ -106,9 +107,9 @@ const ImportForm: React.FC<ImportFormProps> = observer((props) => {
       {...modalConfig}
     >
       <Form className={`${styles.form} ${formClassName ?? ""}`}>
-        {formItems?.map((item) => (
+        {formItems?.map((item, idx) => (
           <FormItem
-            key={item.name}
+            key={formItemKeys(formItems)[idx]}
             requiredMsg={
               item.requiredMsg ??
               ((item.name as string)?.endsWith("En")

package/src/components/Form/ModalForm/index.tsx

@@ -10,6 +10,7 @@ import React, { useEffect, useRef } from "react";
 
 import { ItemContainerProps } from "../../FormItem/ItemContainer";
 import styles from "./index.module.scss";
+import { formItemKeys } from "../_utils/formItemKey";
 import usePermissions from "../../../hooks/usePermissions";
 import { useFormItems } from "./_hooks/useFormItems";
 import type { FormRef } from "../../../types/antd";
@@ -110,6 +111,10 @@ const ModalForm: React.FC<ModalFormProps> = (props) => {
   );
 
   const _formItems = useFormItems(formItems, layout, adaptiveColumnNum);
+  /* `extraFormItems` 是 JSX 形态的表单项，同样可能重名（互斥字段） */
+  const extraKeys = formItemKeys(
+    extraFormItems?.map((i) => i.props as FormItemProps),
+  );
 
   if (!permitted) {
     return null;
@@ -147,7 +152,11 @@ const ModalForm: React.FC<ModalFormProps> = (props) => {
           style={{ "--column-num": adaptiveColumnNum } as React.CSSProperties}
           onValuesChange={onValuesChange}
         >
-          {Object.keys(_formItems ?? {})?.map((key) => (
+          {Object.keys(_formItems ?? {})?.map((key) => {
+            /* key 一次算完（重名的第二条起加 `#n`），别在 map 体里每项重算 */
+            const itemKeys = formItemKeys(_formItems?.[key]);
+
+            return (
             <div
               className={`${styles.formItemGroup} ${
                 formItemGroupClassName ?? ""
@@ -168,9 +177,9 @@ const ModalForm: React.FC<ModalFormProps> = (props) => {
                 className={styles.formItemGroupContent}
                 style={{ paddingLeft: !key ? 0 : undefined }}
               >
-                {_formItems?.[key]?.map((item) => (
+                {_formItems?.[key]?.map((item, idx) => (
                   <FormItem
-                    key={item.name}
+                    key={itemKeys[idx]}
                     requiredMsg={
                       item.requiredMsg ??
                       ((item.name as string)?.endsWith("En")
@@ -186,11 +195,14 @@ const ModalForm: React.FC<ModalFormProps> = (props) => {
                 ))}
               </div>
             </div>
-          ))}
-          {extraFormItems?.map((item) => {
+            );
+          })}
+          {extraFormItems?.map((item, idx) => {
             item = {
               ...item,
-              key: item.props.name,
+              /* 与上面那组同一套 key 规则：重名的第二条起加 `#n`，
+                 按声明顺序编号（见 formItemKeys 的说明） */
+              key: extraKeys[idx],
               props: {
                 requiredMsg:
                   item.props.requiredMsg ??

package/src/components/Form/_utils/formItemKey.ts

@@ -0,0 +1,42 @@
+import { FormItemProps } from "../../FormItem";
+
+/**
+ * 表单项的 React key。
+ *
+ * 原来直接用 `item.name`，而**一个表单有两个互斥、同名的字段是合法的** ——
+ * 消费方真实写法：Bearer Token 用 `PASSWORD`、自定义请求头用 `TEXTAREA`，
+ * 两条都叫 `authValue`，靠 `visible` 互斥。`FormItemProps` 是按 `type` 判别的
+ * 联合类型，把 `type` 写成三元表达式会让 `componentProps` 退化成所有形态的
+ * 交集、编译期就通不过，所以拆成两条是**故意的**，不是写错。
+ *
+ * 于是控制台常年三条
+ * `Encountered two children with the same key, 'authValue'`。
+ * 目前行为无害（两条永远只渲染一个，另一个 return null），但 React 明说
+ * 重复 key 的行为不受支持、将来可能改。
+ *
+ * 修法是重名的第二条起加后缀，而不是改成按下标 —— 按下标会让
+ * 「条件性地从数组里删掉某一项」的表单在删除时整片重挂。
+ *
+ * ⚠️ **按声明数组编号，不能按「可见的那部分」编号。**互斥字段两条都在数组里，
+ * 只是其中一条渲染成 null。若先 `filter(visible)` 再编号，切换的瞬间剩下那条的
+ * key 会从 `authValue#1` 变成 `authValue` —— **key 一变就是重挂**，用户正在输入的
+ * 内容和焦点当场丢，比原来那条警告严重得多。数组是静态写死的，
+ * 按声明顺序编号则天然稳定，切 `visible` 不动 key。
+ *
+ * @param items 声明顺序的表单项数组（**不要预先过滤**）
+ * @returns 与入参等长、下标一一对应的 key 数组
+ */
+export const formItemKeys = (items?: FormItemProps[]): string[] => {
+  const used: Record<string, number> = {};
+
+  return (items ?? []).map((item, idx) => {
+    // name 缺省时退回下标：没有名字的项本来就互不相同，用下标不会撞
+    const name = item?.name == null ? `#${idx}` : String(item.name);
+    const seen = used[name] ?? 0;
+    used[name] = seen + 1;
+
+    return seen === 0 ? name : `${name}#${seen}`;
+  });
+};
+
+export default formItemKeys;

package/src/components/FormItem/FormInput/FormInputNumber/index.tsx

@@ -5,22 +5,114 @@ import { InputNumberProps } from "../../../Input/Number";
 import React from "react";
 
 export interface FormInputNumberProps extends ItemContainerProps {
-  componentProps?: InputNumberProps;
+  /**
+   * `onChange` 的签名比基础组件宽：作为**表单字段**，默认交出的是
+   * `number | null`（见 Bridge 的注释）。写这个回调的人拿到的与表单拿到的
+   * 是同一个值。
+   */
+  componentProps?: Omit<InputNumberProps, "onChange"> & {
+    onChange?: (value: string | number | null) => void;
+  };
+  /**
+   * 交给表单的是字符串而不是数字。默认 `false`。
+   *
+   * 只有真的要处理**超出 IEEE754 安全范围的大数**（订单号、雪花 ID）时才打开
+   * —— 那种值转成 number 会丢精度，必须一路以字符串传递。
+   *
+   * 2.5.0 之前没有这个开关，行为固定等同于 `stringMode`（见下方 Bridge 注释）。
+   */
+  stringMode?: boolean;
 }
 
+// value / onChange 要重新声明：`InputNumberProps` 上那两个是**基础组件**的
+// 契约（字符串进、字符串出），而这里收的是**表单值**，可以是数字或 null
+type BridgeProps = Omit<InputNumberProps, "value" | "onChange"> & {
+  /** antd Form.Item 注入 */
+  value?: string | number | null;
+  /** antd Form.Item 注入 */
+  onChange?: (value: string | number | null) => void;
+  /**
+   * 使用方写在 `componentProps.onChange` 里的那个回调。
+   *
+   * 单独接出来、不跟着 `componentProps` 一起展开：展开的话它会盖掉
+   * Form.Item 注入的那个 onChange，字段值就再也传不到表单里了。
+   * 它拿到的与表单拿到的**是同一个值**（默认已转成数字）。
+   */
+  componentOnChange?: (value: string | number | null) => void;
+  stringMode?: boolean;
+};
+
+/**
+ * 夹在 `Form.Item` 与 `Input.Number` 之间，**把字符串换成数字再交给表单**。
+ *
+ * 为什么需要它：`Input.Number` 内部以字符串保存（底层 `stringMode`，为的是不
+ * 丢大数精度），`onChange` 交出的也是字符串。这对一个**基础输入组件**是合理
+ * 的，但对一个叫 INPUTNUMBER 的**表单字段**不合理 —— 表单收上去的值会直接
+ * 进请求体，而后端字段多半是整数：
+ *
+ * ```
+ * 422  invalid type: string "2", expected i32
+ * ```
+ *
+ * 这个坑平时看不见：没动过的字段，值来自详情接口、本来就是数字，原样发回去
+ * 没事；**只有用户真的改了那一格**才会变成字符串。现象是「我明明只改了个
+ * 数字却保存失败」，而且报错在服务端，前端一行日志都没有。
+ *
+ * 转换只在**往上交**的方向做；`Input.Number` 内部仍然是字符串，所以正在敲的
+ * "1." / "1.50" 不会被改写（配套改动见 `Input/Number` 里的 sameNumber 判断）。
+ */
+const Bridge: React.FC<BridgeProps> = (props) => {
+  const { value, onChange, componentOnChange, stringMode, ...rest } = props;
+
+  const emit = (next: string | number | null) => {
+    onChange?.(next);
+    componentOnChange?.(next);
+  };
+
+  return (
+    <Input.Number
+      {...rest}
+      value={value}
+      onChange={(text) => {
+        if (stringMode) {
+          emit(text);
+          return;
+        }
+
+        // 空 → null 而不是 ""：语义是「没填」，不是「填了个空字符串」。
+        // 后端 `Option<i32>` 收得下 null，收不下 ""
+        if (text === "" || text === null || text === undefined) {
+          emit(null);
+          return;
+        }
+
+        const num = Number(text);
+        // 转不动就原样交出去（用户可能正敲到 "-" 或 "1e" 这种中间态）。
+        // 硬转成 NaN 会让表单里躺着一个既非数字也非空的值
+        emit(Number.isFinite(num) ? num : text);
+      }}
+    />
+  );
+};
+
 const FormInputNumber: React.FC<FormInputNumberProps> = (props) => {
   const {
     componentProps = {},
     className: itemClassName,
     disabled,
+    stringMode,
     ...formItemProps
   } = props;
-  const { placeholder, ...inputConfig } = componentProps;
+  // onChange 必须摘出来，理由见 BridgeProps.componentOnChange
+  const { placeholder, onChange: componentOnChange, ...inputConfig } =
+    componentProps;
 
   return (
     <ItemContainer {...formItemProps} className={`${itemClassName ?? ""}`}>
-      <Input.Number
+      <Bridge
         {...inputConfig}
+        componentOnChange={componentOnChange}
+        stringMode={stringMode}
         disabled={inputConfig.disabled ?? disabled}
         placeholder={placeholder ?? "请输入"}
       />

package/src/components/FormItem/index.md

@@ -93,6 +93,22 @@ export default () => (
 );
 ```
 
+> **`2.5.0` 起，`INPUTNUMBER` 交给表单的是 `number | null`**（此前是字符串）。
+>
+> 表单值往往原样进请求体，而后端字段多半是整数，交字符串上去会被强类型服务端
+> 拒掉（Rust/serde 会回 `invalid type: string "2", expected i32`）。这个问题
+> 平时看不见：**没动过的字段**值来自详情接口、本来就是数字，只有用户真的改了
+> 那一格才会变成字符串 —— 现象是「我只改了个数字却保存失败」。
+>
+> - 空值交出的是 `null`（「没填」），不是 `""`。
+> - 敲到一半的中间态（`-`、`1e`）原样交出，不会变成 `NaN`。
+> - 正在输入的文本不会被回写打断，`1.` / `1.50` 都保得住。
+> - 确实需要字符串（大数不丢精度）时，加 `stringMode`：
+>
+> ```tsx
+> <FormItem type="INPUTNUMBER" name="orderNo" label="订单号" stringMode />
+> ```
+
 ## 范围输入
 
 ```tsx

package/src/components/Input/Number/index.tsx

@@ -17,7 +17,11 @@ export interface InputNumberProps extends Omit<
 > {
   getRef?: (ref: HTMLInputElement | null) => void;
   onChange?: (value: string) => void;
-  value?: string;
+  /**
+   * 受控值。本组件内部**始终以字符串保存**（底层开了 antd 的 `stringMode`，
+   * 为的是不丢大数精度），但外部传数字进来也接得住。
+   */
+  value?: string | number | null;
   allowClear?: boolean;
   wrapperClassName?: string;
 }
@@ -76,17 +80,38 @@ const InputNumber: React.FC<InputNumberProps> = (props) => {
     if (prevValueRef.current !== value) {
       prevValueRef.current = value;
 
-      if (value !== undefined) {
+      // 数值相等就不要回写文本。
+      //
+      // 上游把值转成数字之后（`FormItem` 的 INPUTNUMBER 默认就会转），一个
+      // 回环会打回来：输入 "1." → onChange → 表单存 1 → value={1} 传回来。
+      // 若照单全收地写成 "1"，用户刚敲的小数点当场消失、光标还会跳到末尾，
+      // "1.50" 也会被改写成 "1.5"。
+      //
+      // 判据用**数值相等**而不是字符串相等：这几种写法（"1." / "1.50" / "+1"）
+      // 表示的是同一个数，此时以用户正在敲的那份文本为准。
+      const sameNumber =
+        value !== undefined &&
+        value !== null &&
+        _value !== "" &&
+        Number(value) === Number(_value);
+
+      if (sameNumber) {
+        // 只同步「已提交值」，不动正在编辑的文本
+        setLastValue(_value);
+      } else if (value !== undefined && value !== null) {
         const newValue =
           typeof value === "number" ? `${value}` : value?.toString();
         setValue(newValue);
         setLastValue(newValue);
       } else {
-        // Clear only on initialization or when explicitly set to undefined externally
+        // Clear only on initialization or when explicitly set to undefined/null externally
         setValue("");
         setLastValue("");
       }
     }
+    // `_value` 是刻意不进依赖的：这个 effect 只该在**外部** value 变化时跑，
+    // 把它加进来会让每次键入都重跑一遍，等于绕过上面那个 prevValueRef 判断
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [value]);
 
   useEffect(() => {

package/src/components/Input/index.md

@@ -36,7 +36,15 @@ export default () => {
 
 ## 数字输入框
 
-数字输入框，`onChange` 返回字符串，内置 `allowClear`、`controls={false}` 与 `stringMode`。
+数字输入框，`onChange` 返回**字符串**，内置 `allowClear`、`controls={false}` 与 `stringMode`。
+
+返回字符串是刻意的：`stringMode` 让超出 IEEE754 安全范围的大数（订单号、雪花 ID）
+不丢精度，而转成 `number` 就丢了。
+
+> **注意**：作为**表单字段**用时（`FormItem type="INPUTNUMBER"`）行为不同 ——
+> 自 `2.5.0` 起它交给表单的是 `number | null`。表单值通常会直接进请求体，
+> 而后端字段多半是整数，交字符串上去会被强类型服务端拒掉。
+> 详见 [FormItem 的 INPUTNUMBER](/components/form-item)。
 
 ```tsx
 import React from "react";

package/src/components/Markdown/Views/index.tsx

@@ -5,6 +5,7 @@ import ReactMarkdown, {
 } from "react-markdown";
 import rehypeHighlight from "rehype-highlight";
 import rehypeKatex from "rehype-katex";
+import remarkCjkFriendly from "remark-cjk-friendly";
 import remarkGfm from "remark-gfm";
 import remarkMath from "remark-math";
 import classNames from "classnames";
@@ -125,7 +126,13 @@ const MarkdownViews: React.FC<MarkdownViewsProps> = (props) => {
       <ReactMarkdown
         {...props}
         rehypePlugins={[rehypeHighlight, rehypeKatex]}
-        remarkPlugins={[remarkGfm, remarkMath]}
+        /* `remarkCjkFriendly` 修的是中文里最常见的一处 markdown 失效：
+           `我得先知道**「这件事」是什么**` —— 开头那对 `**` 后面跟着 `「`
+           （标点）、前面是 `道`（非空白非标点），按 CommonMark 的 flanking 规则
+           它不是左侧定界符，于是整段**原样显示两个星号**。
+           而中文里「**「…」**」「**《…》**」这种写法极常见，模型输出里到处都是。
+           这个插件按 CJK 友好规则重判 flanking，是这条规则的通行修法。 */
+        remarkPlugins={[remarkCjkFriendly, remarkGfm, remarkMath]}
         className={classNames(styles.MarkdownViews, className, "markdown-body")}
         components={{
           code: CodeBlock,