@huicai/cli 2026.714.0 → 2026.721.0

package/skills/file-ingest/scripts/file_toolkit.py

@@ -0,0 +1,404 @@
+# -*- coding: utf-8 -*-
+"""通用文件读取工具箱：read_any(path) 把「任意办公文件」变成可用文本+元信息，本地全类型分发、优雅降级。
+
+经 run_python 使用（pandas/openpyxl/xlrd/pypdf/python-docx/python-pptx 已随托管运行时就绪）。
+覆盖：Excel(xlsx/xlsm/xls)、CSV/TSV、PDF、Word(docx/旧版 doc)、PPT(pptx)、OFD(电子发票/公文)、
+ZIP、HTML/MHTML、RTF、图片(png/jpg 尺寸元信息)、纯文本。绝不抛裸异常——不支持/加密/损坏都回可读原因。
+
+    r = read_any('attachments/某文件.pdf')
+    if r['ok']: print(r['meta']); print(r['text'][:2000])
+    else:       print('无法直接读取：', r['reason'])   # 例如扫描件需 OCR、旧 .doc 需转档
+"""
+from __future__ import annotations
+import os, re, io, zipfile, warnings
+warnings.simplefilter('ignore')
+
+TEXT_CAP = 200_000  # 单文件返回文本上限，避免超大文件撑爆
+
+
+def _result(kind, ok, text='', meta='', reason=''):
+    return {'kind': kind, 'ok': bool(ok), 'text': (text or '')[:TEXT_CAP], 'meta': meta, 'reason': reason}
+
+
+def _ext(p):
+    b = os.path.basename(p); i = b.rfind('.')
+    return b[i:].lower() if i > 0 else ''
+
+
+def _sniff(path):
+    """按**内容**判类（治扩展名错配：.doc 实为 rtf、.rtf 实为 ole2、.xls 实为 html 等常见乱象）。"""
+    try:
+        n = os.path.getsize(path)
+    except OSError:
+        return 'missing'
+    if n == 0:
+        return 'empty'
+    with open(path, 'rb') as fh:
+        h = fh.read(16)
+    if h[:4] == b'PK\x03\x04':
+        return 'zip'
+    if h[:4] == b'\xd0\xcf\x11\xe0':
+        return 'ole2'
+    if h[:8] == b'\x89PNG\r\n\x1a\n':
+        return 'png'
+    if h[:3] == b'\xff\xd8\xff':
+        return 'jpeg'
+    if h[:5] == b'%PDF-':
+        return 'pdf'
+    lead = h.lstrip(b'\xef\xbb\xbf \t\r\n').lower()  # 去 BOM/空白后看文本签名
+    if lead[:5] == b'{\\rtf':
+        return 'rtf'
+    if lead[:5] in (b'<html', b'<!doc') or lead[:6] == b'<table' or lead[:5] == b'<?xml':
+        return 'html'
+    return 'other'
+
+
+# ── 各类型处理器 ─────────────────────────────────────────────────────────────
+def _read_excel(path):
+    import pandas as pd
+    engines = {'ole2': ['xlrd', None], 'zip': ['openpyxl', None]}.get(_sniff(path), [None, 'openpyxl', 'xlrd'])
+    xf, last = None, ''
+    for eng in engines:
+        try:
+            xf = pd.ExcelFile(path) if eng is None else pd.ExcelFile(path, engine=eng); break
+        except Exception as ex:
+            last = f'{type(ex).__name__}: {str(ex)[:80]}'
+    if xf is None:
+        if 'Content_Types' in last:
+            return _result('excel', False, reason='xlsx 压缩包损坏（缺 [Content_Types].xml），请重新导出')
+        if any(k in last.lower() for k in ('ole2', 'encrypt', 'workbook')):
+            return _result('excel', False, reason='疑似加密或损坏的旧格式（.xls），需密码或另存为 .xlsx')
+        return _result('excel', False, reason=last or '无法识别的表格格式')
+    parts = []
+    for s in xf.sheet_names[:12]:
+        try:
+            raw = xf.parse(s, header=None, nrows=6, dtype=object)
+            parts.append(f'# 工作表 {s}（约 {xf.parse(s, header=None).shape[0]} 行）\n'
+                         + raw.dropna(how='all').head(5).to_string(index=False, header=False))
+        except Exception as ex:
+            parts.append(f'# 工作表 {s} 读取失败：{type(ex).__name__}')
+    return _result('excel', True, '\n\n'.join(parts), meta=f'{len(xf.sheet_names)} 个工作表')
+
+
+def _read_csv(path):
+    import pandas as pd
+    for enc in ('utf-8', 'gbk', 'utf-8-sig', 'latin-1'):
+        try:
+            df = pd.read_csv(path, nrows=200, encoding=enc)
+            return _result('csv', True, df.head(30).to_string(index=False), meta=f'{df.shape[1]} 列（前 200 行采样，{enc}）')
+        except UnicodeDecodeError:
+            continue
+        except Exception as ex:
+            return _result('csv', False, reason=f'{type(ex).__name__}: {str(ex)[:80]}')
+    return _result('csv', False, reason='无法识别 CSV 编码（试过 utf-8/gbk/latin-1）')
+
+
+def _read_pdf(path):
+    import pypdf
+    try:
+        r = pypdf.PdfReader(path)
+        if r.is_encrypted:
+            try:
+                r.decrypt('')
+            except Exception:
+                return _result('pdf', False, meta=f'{len(r.pages)} 页', reason='PDF 已加密，需要密码')
+        txt = []
+        for pg in r.pages:
+            txt.append(pg.extract_text() or '')
+            if sum(len(t) for t in txt) > TEXT_CAP:
+                break
+        body = '\n'.join(txt).strip()
+        if body:
+            return _result('pdf', True, body, meta=f'{len(r.pages)} 页')
+        return _result('pdf', False, meta=f'{len(r.pages)} 页', reason='扫描件/无文本层——需 OCR 或走视觉模型识别')
+    except Exception as ex:
+        return _result('pdf', False, reason=f'{type(ex).__name__}: {str(ex)[:80]}')
+
+
+def _read_docx(path):
+    import docx
+    d = docx.Document(path)
+    paras = [p.text for p in d.paragraphs if p.text.strip()]
+    for tb in d.tables:
+        for row in tb.rows:
+            paras.append(' | '.join(c.text for c in row.cells))
+    body = '\n'.join(paras)
+    return _result('word', bool(body.strip()), body, meta=f'{len(d.paragraphs)} 段 {len(d.tables)} 表',
+                   reason='' if body.strip() else '文档为空或仅含图片')
+
+
+def _read_doc(path):
+    """真·旧版 .doc（OLE2 二进制）。本地无 antiword/olefile 难可靠解析（勉强解出的多是乱码，
+    宁可不出也不给假文本）——诚实给转档建议，需要正文走平台 read_document（已支持 .doc）。"""
+    return _result('word', False, reason='旧版 .doc 二进制（OLE2），本地难可靠解析；请转存 .docx，或用平台 read_document 解析')
+
+
+def _read_pptx(path):
+    import pptx
+    pr = pptx.Presentation(path)
+    out = []
+    for i, sl in enumerate(pr.slides, 1):
+        buf = [f'--- 幻灯片 {i} ---']
+        for sh in sl.shapes:
+            if sh.has_text_frame:
+                for para in sh.text_frame.paragraphs:
+                    t = ''.join(run.text for run in para.runs)
+                    if t.strip():
+                        buf.append(t)
+        out.append('\n'.join(buf))
+    body = '\n'.join(out)
+    return _result('ppt', len(pr.slides) > 0, body, meta=f'{len(pr.slides)} 页幻灯片')
+
+
+def _read_ofd(path):
+    """OFD（国产电子发票/公文）本质是 zip+XML 容器：抽各 Content/Document XML 里的 TextCode 文本。"""
+    try:
+        z = zipfile.ZipFile(path)
+    except Exception as ex:
+        return _result('ofd', False, reason=f'OFD 容器损坏：{type(ex).__name__}')
+    xmls = [n for n in z.namelist() if n.lower().endswith('.xml')]
+    chunks = []
+    for n in xmls:
+        try:
+            data = z.read(n).decode('utf-8', 'ignore')
+        except Exception:
+            continue
+        # OFD 文本承载在 <ofd:TextCode>…</ofd:TextCode>（命名空间前缀可能不同）
+        codes = re.findall(r'<(?:\w+:)?TextCode[^>]*>([^<]+)</(?:\w+:)?TextCode>', data)
+        chunks += [c for c in codes if c.strip()]
+    body = '\n'.join(chunks)
+    if body.strip():
+        return _result('ofd', True, body, meta=f'{len(xmls)} 个 XML，{len(chunks)} 段文本')
+    return _result('ofd', False, meta=f'{len(xmls)} 个 XML', reason='OFD 未提取到文本（可能纯图形/签章），可走视觉模型')
+
+
+def _read_zip(path):
+    try:
+        z = zipfile.ZipFile(path)
+    except Exception as ex:
+        return _result('zip', False, reason=f'不是有效的 zip 或已损坏：{type(ex).__name__}')
+    names = z.namelist()
+    listing = '\n'.join(names[:200]) + ('' if len(names) <= 200 else f'\n…（共 {len(names)} 项）')
+    return _result('zip', True, listing, meta=f'{len(names)} 个条目')
+
+
+# RTF 里不是正文的「目的组」（字体/颜色/样式/信息/图片等），整组跳过
+_RTF_SKIP = frozenset(('fonttbl', 'colortbl', 'stylesheet', 'info', 'pict', 'object', 'themedata',
+                       'colorschememapping', 'latentstyles', 'datastore', 'generator', 'operator',
+                       'listtable', 'listoverridetable', 'rsidtbl', 'mmath', 'wgrffmtfilter'))
+_RTF_BREAK = {'par': '\n', 'sect': '\n', 'page': '\n', 'line': '\n', 'tab': '\t',
+              'emdash': '—', 'endash': '–', 'lquote': '‘', 'rquote': '’',
+              'ldblquote': '“', 'rdblquote': '”', 'bullet': '•'}
+_RTF_TOK = re.compile(r"\\([a-z]{1,32})(-?\d{1,10})?[ ]?|\\'([0-9a-fA-F]{2})|\\([^a-z])|([{}])|[\r\n]+|([^\\{}\r\n]+)", re.I)
+
+
+def _rtf_to_text(rtf, cp='gbk'):
+    """轻量 RTF→文本：跳过字体/样式等目的组，\\'XX 十六进制按代码页缓冲解码（中文 RTF 多为 GBK），
+    \\uN Unicode、\\par 换行；其余控制字丢弃。对付「.doc 其实是 RTF」这类中文公文/回执足够。"""
+    out, stack, buf = [], [], bytearray()
+    ignorable, ucskip, curskip = False, 1, 0
+
+    def flush():
+        if buf:
+            out.append(bytes(buf).decode(cp, 'ignore'))
+            buf.clear()
+
+    for m in _RTF_TOK.finditer(rtf):
+        word, arg, hexv, ctrl, brace, text = m.groups()
+        if brace == '{':
+            flush(); stack.append((ignorable, ucskip)); curskip = 0
+        elif brace == '}':
+            flush()
+            if stack:
+                ignorable, ucskip = stack.pop()
+            curskip = 0
+        elif ctrl:
+            flush(); curskip = 0
+            if ctrl == '*':
+                ignorable = True
+            elif not ignorable and ctrl in '{}\\':
+                out.append(ctrl)
+            elif not ignorable and ctrl == '~':
+                out.append(' ')
+        elif hexv is not None:
+            if curskip > 0:
+                curskip -= 1
+            elif not ignorable:
+                buf.append(int(hexv, 16))     # 缓冲字节，遇非 hex token 再整体按 cp 解码
+        elif word is not None:
+            flush()
+            if word in _RTF_SKIP:
+                ignorable = True
+            elif word == 'ansicpg' and arg:
+                cp = 'cp' + arg               # \ansicpg936 → GBK
+            elif word == 'uc' and arg:
+                ucskip = int(arg)
+            elif word == 'u' and arg:
+                if not ignorable:
+                    out.append(chr(int(arg) % 0x10000))
+                curskip = ucskip
+            elif not ignorable and word in _RTF_BREAK:
+                out.append(_RTF_BREAK[word])
+            else:
+                curskip = 0
+        elif text is not None:
+            flush()
+            if curskip > 0:
+                curskip -= len(text)
+            elif not ignorable:
+                out.append(text)
+    flush()
+    return re.sub(r'\n{3,}', '\n\n', ''.join(out)).strip()
+
+
+def _strip_markup(path, kind):
+    raw = open(path, 'rb').read()
+    if kind == 'rtf':
+        s = _rtf_to_text(raw.decode('latin-1', 'ignore'))
+    else:  # html / mhtml
+        for enc in ('utf-8', 'gbk', 'latin-1'):
+            try:
+                s = raw.decode(enc); break
+            except UnicodeDecodeError:
+                s = raw.decode('utf-8', 'ignore')
+        s = re.sub(r'(?is)<(script|style).*?</\1>', ' ', s)
+        s = re.sub(r'(?s)<[^>]+>', ' ', s)
+        s = re.sub(r'[ \t\r\f]{2,}', ' ', re.sub(r'\n{3,}', '\n\n', s)).strip()
+    return _result(kind, bool(s), s, meta=f'{len(s)} 字')
+
+
+def _read_html_or_table(path):
+    """HTML/MHTML：很多"Excel"其实是 HTML 表格（税务/银行导出常见）。先用 read_html 抽结构化表，抽不到再剥标签取文本。"""
+    import pandas as pd
+    for enc in ('utf-8', 'gbk', 'utf-8-sig'):
+        try:
+            tables = pd.read_html(path, encoding=enc)
+            if tables:
+                body = '\n\n'.join(f'# 表 {i+1}（{t.shape[0]}×{t.shape[1]}）\n{t.head(20).to_string(index=False)}'
+                                   for i, t in enumerate(tables[:6]))
+                return _result('html-table', True, body, meta=f'{len(tables)} 张表')
+        except (ValueError, UnicodeDecodeError):
+            continue
+        except Exception:
+            break
+    return _strip_markup(path, 'html')
+
+
+def _read_image(path):
+    raw = open(path, 'rb').read(64)
+    dim = ''
+    if raw[:8] == b'\x89PNG\r\n\x1a\n':
+        w = int.from_bytes(raw[16:20], 'big'); h = int.from_bytes(raw[20:24], 'big'); dim = f'{w}x{h}'
+    return _result('image', False, meta=dim or '图片', reason='图片文件——本地无 OCR，请走视觉模型识别其内容')
+
+
+def _read_text(path):
+    raw = open(path, 'rb').read()
+    for enc in ('utf-8', 'gbk', 'utf-8-sig'):
+        try:
+            s = raw.decode(enc)
+            printable = sum(c.isprintable() or c in '\n\t ' for c in s[:2000])
+            if printable / max(1, len(s[:2000])) > 0.85:
+                return _result('text', True, s, meta=f'{len(s)} 字（{enc}）')
+        except UnicodeDecodeError:
+            continue
+    return _result('unknown', False, reason='二进制或未知格式，无法作为文本读取')
+
+
+# ── 主入口：按内容嗅探 + 扩展名分发 ──────────────────────────────────────────
+def read_any(path):
+    """任意文件 → {kind, ok, text, meta, reason}。绝不抛异常，不支持/加密/损坏均以 ok=False + reason 返回。"""
+    if not os.path.exists(path):
+        return _result('missing', False, reason='文件不存在')
+    sniff = _sniff(path)
+    if sniff == 'empty':
+        return _result('empty', False, reason='空文件（0 字节）')
+    e = _ext(path)
+    try:
+        # ① 内容签名优先（扩展名错配时以真实内容为准）
+        if sniff == 'pdf':
+            return _read_pdf(path)
+        if sniff in ('png', 'jpeg'):
+            return _read_image(path)
+        if sniff == 'rtf':                       # .doc 常是伪装的 rtf
+            return _strip_markup(path, 'rtf')
+        if sniff == 'html':                      # .xls 常是伪装的 html 表格
+            return _read_html_or_table(path)
+        if sniff == 'zip':                       # 真 zip 容器 → 按扩展名细分
+            if e in ('.xlsx', '.xlsm'):
+                return _read_excel(path)
+            if e == '.docx':
+                return _read_docx(path)
+            if e == '.pptx':
+                return _read_pptx(path)
+            if e == '.ofd':
+                return _read_ofd(path)
+            return _read_zip(path)
+        if sniff == 'ole2':                      # 真 OLE2 二进制 → 按扩展名细分
+            if e in ('.xls', '.xlsm'):
+                return _read_excel(path)
+            if e == '.doc':
+                return _read_doc(path)
+            r = _read_excel(path)                # 未知 OLE2：先当表格，失败再当 doc
+            return r if r['ok'] else _read_doc(path)
+        # ② 内容无明确签名 → 回退扩展名
+        if e in ('.png', '.jpg', '.jpeg', '.gif', '.bmp', '.webp'):
+            return _read_image(path)
+        if e in ('.xlsx', '.xlsm', '.xls'):
+            return _read_excel(path)
+        if e in ('.csv', '.tsv'):
+            return _read_csv(path)
+        if e == '.docx':
+            return _read_docx(path)
+        if e == '.doc':
+            return _read_doc(path)
+        if e == '.pptx':
+            return _read_pptx(path)
+        if e == '.ofd':
+            return _read_ofd(path)
+        if e in ('.html', '.htm', '.mhtml'):
+            return _read_html_or_table(path)
+        if e == '.rtf':
+            return _strip_markup(path, 'rtf')
+        return _read_text(path)
+    except Exception as ex:  # 兜底：任何未预料异常都转成可读原因，绝不抛给调用方
+        return _result(e or sniff, False, reason=f'读取失败 {type(ex).__name__}: {str(ex)[:100]}')
+
+
+def _selftest():
+    import sys, tempfile, zipfile as zf
+    d = tempfile.mkdtemp()
+    j = lambda n: os.path.join(d, n)
+    # csv
+    open(j('a.csv'), 'w', encoding='utf-8').write('月份,金额\n2026-01,1000\n2026-02,2000\n')
+    assert read_any(j('a.csv'))['ok']
+    # rtf（GBK 十六进制转义）——宋 = \'cb\'ce 在此用 ASCII 验证控制字/组跳过与正文提取
+    open(j('b.rtf'), 'w', encoding='latin-1').write(r'{\rtf1\ansi{\fonttbl{\f0 Arial;}}\f0 Hello \b World\b0 \par End}')
+    rt = read_any(j('b.rtf'))
+    assert rt['ok'] and 'Hello' in rt['text'] and 'World' in rt['text'] and 'fonttbl' not in rt['text'], rt
+    # html 表格
+    open(j('c.html'), 'w', encoding='utf-8').write('<html><body><table><tr><td>甲</td><td>乙</td></tr><tr><td>1</td><td>2</td></tr></table></body></html>')
+    assert read_any(j('c.html'))['ok']
+    # zip
+    with zf.ZipFile(j('d.zip'), 'w') as z:
+        z.writestr('inner.txt', 'x')
+    assert read_any(j('d.zip'))['ok']
+    # 扩展名错配：.doc 内容其实是 rtf → 按内容仍识别为 rtf 并读出正文（中文经 GBK 十六进制转义）
+    open(j('e.doc'), 'wb').write(rb"{\rtf1\ansi\ansicpg936 \'b1\'a8\'cf\'fa\'b5\'a5\par}")  # \'b1..=“报销单”GBK
+    ed = read_any(j('e.doc'))
+    assert ed['kind'] == 'rtf' and '报销单' in ed['text'], ed
+    # 空文件 / 缺失 → 优雅 ok=False
+    open(j('f.xlsx'), 'wb').close()
+    assert not read_any(j('f.xlsx'))['ok']
+    assert not read_any(j('zzz.pdf'))['ok']
+    print('✅ file_toolkit 自测通过')
+
+
+if __name__ == '__main__':
+    import sys
+    if len(sys.argv) < 2:
+        _selftest()
+    else:
+        r = read_any(sys.argv[1])
+        print('kind=%s ok=%s meta=%s' % (r['kind'], r['ok'], r['meta']))
+        print('reason:', r['reason']) if not r['ok'] else print(r['text'][:800])

package/skills/finance-analysis/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: finance-analysis
+description: 财务分析（三表勾稽、比率体系、杜邦分解、现金流质量、财务预警、财务月报/年报解读）。当用户给出资产负债表/利润表/现金流量表或说"财务分析/财报解读/经营分析/预算执行"时使用。
+version: 1.0.0
+---
+
+# 财务分析（经 run_python；先勾稽后分析，无勾稽不出结论）
+
+## 工作流程（强制）
+
+1. **取数与口径**：确认报表口径（合并/母公司、审计/未审、单位、期间）；多期数据整成
+   「科目 × 期间」长表。缺口径先问，不猜。
+2. **勾稽校验（第一道闸）**：`read_skill_file` 读 `scripts/fin_ratios.py`，跑 `check_articulation()`——
+   资产=负债+所有者权益；三表间：净利润(利润表) ↔ 现金流量表补充资料起点、
+   现金及等价物净增加 ↔ 资产负债表货币资金变动（允差内）。**勾稽不过=数据有问题，
+   停下来报告差异，绝不带病分析**。
+3. **比率体系**：`compute_ratios()` 一键产出四维比率（見 `references/ratios.md` 指标字典与参考区间）：
+   偿债（流动/速动/资产负债率/利息保障）、营运（应收/存货/总资产周转）、
+   盈利（毛利率/净利率/ROE/ROA）、成长（收入/净利/资产增速）。多期自动算趋势。
+4. **杜邦分解**：`dupont()` 把 ROE 拆为 净利率 × 总资产周转 × 权益乘数，逐期对比定位驱动因子——
+   「ROE 降是赚钱能力降、效率降还是杠杆降」必须给出定量答案。
+5. **现金流质量**：净利润现金含量（经营现金流/净利润）、收现比（销售收现/营收）；
+   连续两期 <0.8 必须专段分析（应收积压/存货积压/激进确认）。
+6. **预警**：`altman_z()`（制造业口径 Z-score，非制造业如实注明不适用）+ 规则预警
+   （资产负债率>70%、速动<1、应收周转天数同比+30% 等,阈值见字典,行业不同要调）。
+7. **成稿**：Excel 结果簿（原数/勾稽/比率/杜邦/预警 各一 Sheet,xlsx-analysis 样式）+
+   Word 分析报告（docx-author:结论先行→分维度论证→风险与建议,每个判断带数字）+ 趋势图（data-analysis）。
+
+## 领域要点（写进结论前自查）
+
+- 比率**孤立无意义**：必须给对比锚（上期/同业/预算），无锚就向用户要或明示局限;
+- 一次性损益（资产处置/政府补助）要剔除后看经常性盈利能力;
+- 应收与收入背离（收入+20%、应收+60%）是最经典的质量红旗;
+- 存贷双高（大额货币资金 + 大额有息负债并存）要点名存疑;
+- 负数/零分母（权益为负、EBIT<0）时比率如实标注"不适用"而非硬算。
+
+## 长任务作业法
+
+年报级分析（多年多主体）按阶段推进：取数标准化 → 勾稽 → 单期比率 → 多期趋势 → 专题
+（现金流/减值/关联交易）→ 成稿;每阶段中间表落盘,todo_write 跟踪。
+
+## 边界
+
+- 你做的是**分析**不是审计鉴证：结论措辞用"数据显示/存在迹象",不用"证实/查实";
+- 估值类诉求转 securities-research;造假核查类转 audit-assist 的程序思路并声明局限。
+
+## 验收自查
+
+- [ ] 勾稽校验通过或差异已如实报告
+- [ ] 每个比率结论都有对比锚与数字
+- [ ] 杜邦分解定位到了驱动因子
+- [ ] 一次性损益已识别剔除；不适用指标已标注
+- [ ] Excel 结果簿 + Word 报告 + 图三件套齐且同源
+
+## 附件
+
+- `scripts/fin_ratios.py` — 勾稽校验/四维比率/杜邦/Z-score/预警，输入「科目×期间」表；可直接执行自测
+- `references/ratios.md` — 指标字典：公式、口径陷阱、常用参考区间与红旗信号
+
+> 本技能属**财务技能链**——岗位路由与端到端工作流（月结 · 审计 · 资金 · 投资）见 `finance-chain`。

package/skills/finance-analysis/references/ratios.md

@@ -0,0 +1,54 @@
+# 财务指标字典（公式 · 口径陷阱 · 通用参考区间 · 红旗信号）
+
+> 参考区间为跨行业通用经验值，**结论前必须按行业校准**（重资产/贸易/软件差异巨大）；
+> 有同业或上期数据时，永远优先用相对比较而非绝对区间。
+
+## 偿债能力
+
+| 指标 | 公式 | 通用参考 | 口径陷阱 |
+|---|---|---|---|
+| 流动比率 | 流动资产/流动负债 | 1.5–2.5 | 含大额存货/一年内到期非流动负债时失真 |
+| 速动比率 | (流动资产-存货)/流动负债 | ≥1 | 预付款项大的企业建议一并剔除 |
+| 资产负债率 | 负债/资产 | 40%–70%（行业差异极大） | 含大额预收（合同负债）的要拆看：经营性负债≠债务压力 |
+| 利息保障倍数 | EBIT/利息费用 | ≥3 | 利息费用取"费用化利息"，财务费用含汇兑/手续费要拆 |
+
+## 营运能力
+
+| 指标 | 公式 | 红旗 |
+|---|---|---|
+| 应收周转天数 | 应收账款×365/营业收入 | 同比 +30% 以上；显著慢于同业 |
+| 存货周转天数 | 存货×365/营业成本 | 持续走高 + 毛利率反常稳定（跌价准备计提不足嫌疑） |
+| 总资产周转率 | 营业收入/总资产 | 骤降=资产虚增或收入失速，两头都要查 |
+
+严谨口径用**平均余额**（期初+期末)/2；快速分析用期末口径务必注明。
+
+## 盈利能力
+
+| 指标 | 公式 | 陷阱 |
+|---|---|---|
+| 毛利率 | (收入-成本)/收入 | 骤升要查成本资本化/存货跌价转回；显著高于同业要有解释 |
+| 净利率 | 净利润/收入 | 剔除一次性损益看经常性净利率 |
+| ROE | 净利润/所有者权益 | 权益为负不适用；高 ROE 先看杜邦是不是纯靠杠杆 |
+| 净利润现金含量 | 经营现金净流/净利润 | <0.8 连续两期=盈利质量红旗；>1.5 也要看是否压占上游 |
+| 收现比 | 销售商品收到的现金/营业收入 | 长期 <1（含税口径应 >1）= 收入确认激进或回款差 |
+
+## 成长与结构
+
+- 收入增速 vs 应收增速：应收增速 > 收入增速 × 1.5 → 红旗;
+- 收入增速 vs 经营现金流增速长期背离 → 红旗;
+- 存贷双高：货币资金与有息负债同时高企 → 资金真实性/受限情况必查;
+- 商誉/总资产 > 30% → 减值风险专段;
+- 其他应收款异常大 → 资金占用嫌疑。
+
+## 预警模型
+
+- **Altman Z**（制造业）：1.2×营运资本/总资产 + 1.4×留存收益/总资产 + 3.3×EBIT/总资产
+  + 0.6×权益市值/总负债 + 1.0×收入/总资产；<1.8 危险、1.8–2.99 灰色、>2.99 安全。
+  非上市用账面权益近似并注明;非制造业用修正版或声明不适用。
+- **Beneish M-score 思路**（造假倾向,做提示不做定论）：重点看 DSRI(应收/收入指数)、
+  GMI(毛利指数)、AQI(资产质量)、SGI(收入增长)——多项同时异常时提示深查,措辞用"存在特征"。
+
+## 报告措辞规范
+
+- 数据显示/呈现/存在…迹象（✓）；证实/查实/确定造假（✗——那是审计与监管的事）
+- 每个判断句式：结论 + 数字 + 对比锚（上期/同业/预算）

package/skills/finance-analysis/scripts/fin_ratios.py

@@ -0,0 +1,132 @@
+# 财务分析计算件（经 run_python 执行）：勾稽校验 / 四维比率 / 杜邦分解 / Altman Z / 规则预警。
+# 输入约定：DataFrame，行=科目（中文标准名），列=期间（如 2024/2025），单位自定但需一致。
+# 直接执行本文件 = 自测：内置两期样例三表全流程跑通并断言。
+import pandas as pd
+import numpy as np
+
+TOL = 0.01  # 勾稽允差（同单位）
+
+
+def g(df, item, period):
+    """取数（缺科目返回 NaN 而非报错，由调用侧决定如何处理）。"""
+    try:
+        return float(df.loc[item, period])
+    except KeyError:
+        return np.nan
+
+
+def check_articulation(bs, is_, cf, period):
+    """三表勾稽：资产=负债+权益；现金净增加=期末-期初货币资金。返回 [(项目, 差额, 是否通过)]。"""
+    out = []
+    a = g(bs, '资产总计', period)
+    le = g(bs, '负债合计', period) + g(bs, '所有者权益合计', period)
+    out.append(('资产=负债+权益', a - le, abs(a - le) <= max(TOL, abs(a) * 1e-4)))
+    dcash = g(cf, '现金及现金等价物净增加额', period)
+    bs_d = g(bs, '货币资金', period) - g(bs, '货币资金_期初', period)
+    if not np.isnan(dcash) and not np.isnan(bs_d):
+        out.append(('现金净增加↔货币资金变动', dcash - bs_d, abs(dcash - bs_d) <= max(TOL, abs(dcash) * 0.01)))
+    for name, gap, ok in out:
+        print(f"[勾稽] {name}: 差额 {gap:,.2f} {'✓' if ok else '✗ 不通过'}")
+    return out
+
+
+def compute_ratios(bs, is_, cf, periods):
+    """四维比率表（行=指标，列=期间）。分母≤0 一律 NaN（如实不适用）。"""
+    rows = {}
+    for p in periods:
+        rev = g(is_, '营业收入', p)
+        ni = g(is_, '净利润', p)
+        assets = g(bs, '资产总计', p)
+        equity = g(bs, '所有者权益合计', p)
+        cur_a, cur_l = g(bs, '流动资产合计', p), g(bs, '流动负债合计', p)
+        inv, ar = g(bs, '存货', p), g(bs, '应收账款', p)
+        ocf = g(cf, '经营活动产生的现金流量净额', p)
+        d = lambda x, y: (x / y) if (y and not np.isnan(y) and y > 0) else np.nan
+        rows.setdefault('流动比率', {})[p] = d(cur_a, cur_l)
+        rows.setdefault('速动比率', {})[p] = d(cur_a - (inv if not np.isnan(inv) else 0), cur_l)
+        rows.setdefault('资产负债率%', {})[p] = d(g(bs, '负债合计', p), assets) * 100 if assets else np.nan
+        rows.setdefault('应收周转天数', {})[p] = d(ar * 365, rev)
+        rows.setdefault('存货周转天数', {})[p] = d(inv * 365, g(is_, '营业成本', p))
+        rows.setdefault('总资产周转率', {})[p] = d(rev, assets)
+        rows.setdefault('毛利率%', {})[p] = d(rev - g(is_, '营业成本', p), rev) * 100 if rev else np.nan
+        rows.setdefault('净利率%', {})[p] = d(ni, rev) * 100 if rev else np.nan
+        rows.setdefault('ROE%', {})[p] = d(ni, equity) * 100 if equity else np.nan
+        rows.setdefault('ROA%', {})[p] = d(ni, assets) * 100 if assets else np.nan
+        rows.setdefault('净利润现金含量', {})[p] = d(ocf, ni) if (ni and ni > 0) else np.nan
+    out = pd.DataFrame(rows).T[periods].round(2)
+    print('[比率]\n' + out.to_markdown())
+    return out
+
+
+def dupont(bs, is_, periods):
+    """杜邦：ROE = 净利率 × 总资产周转 × 权益乘数（期末口径，简化版——严谨场合用平均余额并注明）。"""
+    rows = []
+    for p in periods:
+        rev, ni = g(is_, '营业收入', p), g(is_, '净利润', p)
+        assets, eq = g(bs, '资产总计', p), g(bs, '所有者权益合计', p)
+        npm = ni / rev if rev else np.nan
+        tat = rev / assets if assets else np.nan
+        em = assets / eq if eq and eq > 0 else np.nan
+        rows.append({'期间': p, '净利率': round(npm, 4), '总资产周转': round(tat, 4),
+                     '权益乘数': round(em, 4), 'ROE(重构)': round(npm * tat * em, 4)})
+    out = pd.DataFrame(rows)
+    print('[杜邦]\n' + out.to_markdown(index=False))
+    return out
+
+
+def altman_z(bs, is_, period, market_cap=None):
+    """Altman Z（制造业原始口径）。market_cap 缺省用账面权益近似并注明。Z<1.8 危险 / >2.99 安全。"""
+    ta = g(bs, '资产总计', period)
+    wc = g(bs, '流动资产合计', period) - g(bs, '流动负债合计', period)
+    re = g(bs, '未分配利润', period)
+    ebit = g(is_, '利润总额', period) + g(is_, '财务费用', period)
+    tl = g(bs, '负债合计', period)
+    mv = market_cap if market_cap else g(bs, '所有者权益合计', period)
+    z = 1.2 * wc / ta + 1.4 * re / ta + 3.3 * ebit / ta + 0.6 * mv / tl + 1.0 * g(is_, '营业收入', period) / ta
+    tag = '危险区' if z < 1.8 else ('灰色区' if z < 2.99 else '安全区')
+    print(f"[Z-score] {period}: {z:.2f}（{tag}{'，市值用账面权益近似' if not market_cap else ''}）")
+    return z
+
+
+def rule_alerts(ratios, prev=None, cur=None):
+    """规则预警（阈值为通用参考，行业不同需调整——见 references/ratios.md）。"""
+    alerts = []
+    p = cur or ratios.columns[-1]
+    v = lambda k: ratios.loc[k, p] if k in ratios.index else np.nan
+    if v('资产负债率%') > 70: alerts.append(f"资产负债率 {v('资产负债率%')}% > 70%")
+    if v('速动比率') < 1: alerts.append(f"速动比率 {v('速动比率')} < 1")
+    if v('净利润现金含量') < 0.8: alerts.append(f"净利润现金含量 {v('净利润现金含量')} < 0.8（盈利质量存疑）")
+    if prev and '应收周转天数' in ratios.index:
+        a, b = ratios.loc['应收周转天数', prev], ratios.loc['应收周转天数', p]
+        if b > a * 1.3: alerts.append(f'应收周转天数 {a}→{b}（+{(b / a - 1) * 100:.0f}%，回款恶化）')
+    for x in alerts:
+        print('[预警] ' + x)
+    if not alerts:
+        print('[预警] 无触发（阈值为通用参考）')
+    return alerts
+
+
+if __name__ == '__main__':
+    P = ['2024', '2025']
+    bs = pd.DataFrame({
+        '2024': [1000, 520, 480, 600, 300, 150, 180, 120, 200],
+        '2025': [1300, 700, 600, 780, 430, 260, 240, 160, 150],
+    }, index=['资产总计', '负债合计', '所有者权益合计', '流动资产合计', '流动负债合计',
+              '存货', '应收账款', '未分配利润', '货币资金'])
+    bs.loc['货币资金_期初'] = [180, 200]
+    is_ = pd.DataFrame({
+        '2024': [900, 600, 90, 110, 12],
+        '2025': [1100, 760, 96, 120, 18],
+    }, index=['营业收入', '营业成本', '净利润', '利润总额', '财务费用'])
+    cf = pd.DataFrame({'2024': [70, 20], '2025': [60, -50]},
+                      index=['经营活动产生的现金流量净额', '现金及现金等价物净增加额'])
+    art = check_articulation(bs, is_, cf, '2025')
+    assert all(ok for _, _, ok in art), '样例勾稽应全过'
+    r = compute_ratios(bs, is_, cf, P)
+    assert abs(r.loc['ROE%', '2025'] - 16.0) < 0.1
+    dp = dupont(bs, is_, P)
+    assert abs(dp.iloc[-1]['ROE(重构)'] - 0.16) < 0.001
+    altman_z(bs, is_, '2025')
+    al = rule_alerts(r, prev='2024', cur='2025')
+    assert any('净利润现金含量' in x for x in al)  # 60/96=0.63 应触发
+    print('OK fin_ratios.py')