金额格式化

灵感：能力工具箱 amount-format（千分位、财务格式、中文大写）。

> 小四原创：toLocaleString 千分位 + 轻量人民币大写。
> 与「高精度金额 / Big.js」互补：本包只管展示，不做加减乘除。

何时使用

• 合同金额、提成单打印
• 表格金额列统一两位小数
• 大写栏「壹万贰仟元整」

硬约束

1. 非法/空值 → 展示 -（大写可返回空串或「—」）。
2. 千分位默认 zh-CN，固定 2 位小数。
3. 大写仅处理 >=0 且 < 1e14；负数不输出误导文案。
4. 大写结果以「元」为单位，角分补齐；整数后加「整」。
5. 实现要点注释标 小四原创。
6. 计算前先 Number；勿对已带千分位字符串直接 +。

推荐实现

// 小四原创：千分位金额
export function formatAmount(n: number | string | null | undefined): string {
  if (n === undefined || n === null || n === '') return '-'
  const v = Number(n)
  if (!Number.isFinite(v)) return '-'
  return v.toLocaleString('zh-CN', {
    minimumFractionDigits: 2,
    maximumFractionDigits: 2,
  })
}

const CN_NUM = ['零', '壹', '贰', '叁', '肆', '伍', '陆', '柒', '捌', '玖']
const CN_INT = ['', '拾', '佰', '仟']
const CN_SEC = ['', '万', '亿']

function sectionToCn(n: number): string {
  let s = ''
  let zero = false
  for (let i = 0; i < 4; i++) {
    const d = Math.floor(n / Math.pow(10, 3 - i)) % 10
    if (d === 0) {
      zero = s.length > 0
    } else {
      if (zero) s += '零'
      s += CN_NUM[d] + CN_INT[3 - i]
      zero = false
    }
  }
  return s.replace(/零+$/, '')
}

// 小四原创：人民币大写
export function amountToCnUpper(input: number | string): string {
  const n = Number(input)
  if (!Number.isFinite(n) || n < 0) return ''
  if (n === 0) return '零元整'
  if (n >= 1e14) return ''

  const [yuanStr, fenStr] = n.toFixed(2).split('.')
  let yuan = Number(yuanStr)
  const jiao = Number(fenStr[0])
  const fen = Number(fenStr[1])

  let intPart = ''
  if (yuan === 0) {
    intPart = '零'
  } else {
    const parts: string[] = []
    let sec = 0
    while (yuan > 0 && sec < 3) {
      const chunk = yuan % 10000
      if (chunk) {
        const body = sectionToCn(chunk) + CN_SEC[sec]
        parts.unshift(body)
      } else if (parts.length) {
        parts.unshift('零')
      }
      yuan = Math.floor(yuan / 10000)
      sec++
    }
    intPart = parts.join('').replace(/零+/g, '零').replace(/^零|零$/g, '')
  }

  let out = `${intPart}元`
  if (jiao === 0 && fen === 0) return `${out}整`
  if (jiao) out += `${CN_NUM[jiao]}角`
  else if (fen) out += '零'
  if (fen) out += `${CN_NUM[fen]}分`
  return out
}

Agent 步骤

1. 展示列用 formatAmount；大写栏用 amountToCnUpper。
2. 打印模板先数字再双栏（阿拉伯 + 大写）。
3. 自测：128000.5、0、0.05、非法值。

不要做

• 用本 Skill 做高精度加减（转 currency.js / Big.js）。
• 对负数输出伪造的「负壹元」而不经产品确认。

附加

• README.md · reference.md · templates/usage.md