@tcos/broker-parser 0.1.0

package/.claude/skills/parse-statement/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: parse-statement
+description: 解析券商 PDF 结单文件，提取交易记录、持仓和资产汇总为结构化 JSON
+---
+
+## 触发条件
+
+以下情况触发此 Skill：
+
+- 用户提供 PDF 文件，要求解析/读取/提取数据
+- 用户提到「结单」、「月结单」、「交易结单」、「对账单」、「持仓报告」、「brokerage statement」
+- 用户要求将 PDF 转为 JSON、提取交易记录、查看持仓
+- 关键词：辉立证券、Phillip Securities、结单解析、parse statement
+
+## Setup
+
+运行以下 setup 脚本确保环境就绪：
+
+```bash
+#!/usr/bin/env bash
+set -e
+
+# 1. 检查并安装 CLI
+if ! command -v tcos-parse &>/dev/null; then
+  echo "Installing tcos-parse..."
+  npm install -g @tcos/broker-parser
+fi
+
+# 2. 检查 Python 3
+if ! command -v python3 &>/dev/null; then
+  if command -v brew &>/dev/null; then
+    brew install python3
+  elif command -v apt-get &>/dev/null; then
+    sudo apt-get install -y python3 python3-pip
+  else
+    echo "ERROR: Cannot install Python automatically. Please install Python 3 manually."
+    exit 1
+  fi
+fi
+
+# 3. 检查并安装 pdfplumber
+if ! python3 -c "import pdfplumber" 2>/dev/null; then
+  pip3 install pdfplumber
+fi
+
+# 4. 检查 poppler（pdfplumber 底层依赖）
+if ! command -v pdftotext &>/dev/null; then
+  if command -v brew &>/dev/null; then
+    brew install poppler
+  elif command -v apt-get &>/dev/null; then
+    sudo apt-get install -y poppler-utils
+  fi
+fi
+
+echo "tcos-parse setup complete"
+tcos-parse --version
+```
+
+## 使用方式
+
+```bash
+# 基础解析
+tcos-parse <pdf>                    # 解析并输出 JSON 到 stdout
+tcos-parse <pdf> -o out.json        # 输出到文件
+
+# 指定券商（跳过自动检测）
+tcos-parse -b phillip <pdf>         # 指定券商为 phillip
+
+# 阶段控制
+tcos-parse <pdf> --raw              # 只输出 Stage1 原始提取数据
+tcos-parse <pdf> --no-clean         # 跳过 Stage3 清理步骤
+
+# 检测与查询
+tcos-parse --detect <pdf>           # 检测 PDF 所属券商
+tcos-parse --list-parsers           # 列出支持的券商解析器
+
+# 输出控制
+tcos-parse <pdf> -v                 # 显示各阶段耗时（输出到 stderr）
+tcos-parse <pdf> -q                 # 静默模式，只输出 JSON（无额外提示信息）
+```
+
+### 选项说明
+
+| 选项             | 说明                                   |
+| ---------------- | -------------------------------------- |
+| `-o, --output`   | 输出到文件而非 stdout                  |
+| `-b, --broker`   | 指定券商名称，跳过自动检测             |
+| `--raw`          | 只输出 Stage1 原始表格数据，不做格式化 |
+| `--no-clean`     | 跳过 Stage3 数据清理步骤               |
+| `--detect`       | 检测 PDF 所属券商及置信度              |
+| `--list-parsers` | 列出所有可用的券商解析器               |
+| `-v, --verbose`  | 显示各阶段耗时详情（输出到 stderr）    |
+| `-q, --quiet`    | 静默模式，仅输出纯 JSON                |
+
+## 输出格式
+
+完整解析结果（StatementData）：
+
+```json
+{
+  "broker": "phillip",
+  "accountCode": "M000001",
+  "statementDate": "2024-01-31",
+  "transactions": [
+    {
+      "date": "2024-01-15",
+      "ticker": "00700",
+      "name": "TENCENT",
+      "type": "BUY",
+      "quantity": 100,
+      "price": 298.4,
+      "amount": 29840.0,
+      "fee": 50.0,
+      "currency": "HKD"
+    }
+  ],
+  "holdings": [
+    {
+      "ticker": "00700",
+      "name": "TENCENT",
+      "quantity": 100,
+      "avgCost": 298.4,
+      "marketValue": 30000.0,
+      "currency": "HKD"
+    }
+  ],
+  "assets": {
+    "totalAssets": 150000.0,
+    "cashBalance": 120000.0,
+    "marketValue": 30000.0,
+    "currency": "HKD"
+  }
+}
+```

package/.claude/skills/parse-statement/examples.md

@@ -0,0 +1,257 @@
+# parse-statement 使用示例
+
+## 示例 1：基础解析 — 查看交易记录
+
+**用户说**：帮我解析这份辉立的结单
+
+**操作过程**：
+
+1. 运行 setup 安装环境（首次使用）
+2. 执行解析命令
+
+```bash
+tcos-parse /path/to/statement_202401.pdf
+```
+
+**输出**：
+
+```json
+{
+  "broker": "phillip",
+  "accountCode": "M000001",
+  "statementDate": "2024-01-31",
+  "transactions": [
+    {
+      "date": "2024-01-10",
+      "ticker": "00700",
+      "name": "TENCENT",
+      "type": "BUY",
+      "quantity": 100,
+      "price": 298.4,
+      "amount": 29840.0,
+      "fee": 50.0,
+      "currency": "HKD"
+    },
+    {
+      "date": "2024-01-22",
+      "ticker": "09988",
+      "name": "BABA-SW",
+      "type": "SELL",
+      "quantity": 200,
+      "price": 72.5,
+      "amount": 14500.0,
+      "fee": 30.0,
+      "currency": "HKD"
+    }
+  ],
+  "holdings": [
+    {
+      "ticker": "00700",
+      "name": "TENCENT",
+      "quantity": 100,
+      "avgCost": 298.4,
+      "marketValue": 30000.0,
+      "currency": "HKD"
+    }
+  ],
+  "assets": {
+    "totalAssets": 150000.0,
+    "cashBalance": 120000.0,
+    "marketValue": 30000.0,
+    "currency": "HKD"
+  }
+}
+```
+
+---
+
+## 示例 2：输出到文件
+
+**用户说**：解析后保存到文件，方便我后续导入系统
+
+```bash
+tcos-parse /path/to/statement_202401.pdf -o result.json
+```
+
+**输出（stderr）**：
+
+```
+Written to result.json
+```
+
+解析结果已写入 `result.json`，不会输出到终端。
+
+---
+
+## 示例 3：调试 — 查看原始提取数据
+
+**用户说**：解析结果不对，我想看看 PDF 里原始提取出了什么
+
+使用 `--raw` 选项只执行 Stage1（pdfplumber 提取），跳过格式化和清理：
+
+```bash
+tcos-parse /path/to/statement_202401.pdf --raw
+```
+
+**输出**：
+
+```json
+{
+  "pages": [
+    {
+      "pageNumber": 1,
+      "tables": [
+        [
+          ["Date", "Stock Code", "Description", "Buy/Sell", "Qty", "Price", "Amount"],
+          ["10/01/2024", "00700", "TENCENT", "B", "100", "298.40", "29,840.00"]
+        ]
+      ]
+    }
+  ]
+}
+```
+
+---
+
+## 示例 4：调试 — 查看各阶段耗时
+
+**用户说**：解析好慢，想看看慢在哪一步
+
+使用 `-v` 查看各阶段耗时（耗时输出到 stderr，不污染 JSON）：
+
+```bash
+tcos-parse /path/to/statement_202401.pdf -v
+```
+
+**stderr 输出**：
+
+```
+[timing] detect=120ms stage1=850ms stage2=30ms clean=15ms total=1015ms
+```
+
+**stdout 输出**：正常的 JSON 解析结果。
+
+可以配合重定向只看耗时：
+
+```bash
+tcos-parse /path/to/statement_202401.pdf -v > /dev/null
+```
+
+---
+
+## 示例 5：检测 PDF 所属券商
+
+**用户说**：这个 PDF 是哪家券商的结单？
+
+```bash
+tcos-parse --detect /path/to/unknown_statement.pdf
+```
+
+**输出**：
+
+```
+Detected broker: phillip (confidence: 0.95)
+```
+
+静默模式只输出券商名称：
+
+```bash
+tcos-parse --detect /path/to/unknown_statement.pdf -q
+```
+
+**输出**：
+
+```
+phillip
+```
+
+---
+
+## 示例 6：列出支持的券商
+
+**用户说**：目前支持解析哪些券商的结单？
+
+```bash
+tcos-parse --list-parsers
+```
+
+**输出**：
+
+```
+Available parsers:
+  phillip — Phillip Securities (辉立证券)
+```
+
+---
+
+## 示例 7：指定券商跳过自动检测
+
+**用户说**：我知道这是辉立的结单，不需要自动检测
+
+使用 `-b` 直接指定券商，省去检测步骤：
+
+```bash
+tcos-parse -b phillip /path/to/statement_202401.pdf
+```
+
+---
+
+## 示例 8：管道处理 — 用 jq 过滤特定交易
+
+**用户说**：我只想看买入交易
+
+```bash
+tcos-parse /path/to/statement_202401.pdf -q | jq '.transactions[] | select(.type == "BUY")'
+```
+
+**输出**：
+
+```json
+{
+  "date": "2024-01-10",
+  "ticker": "00700",
+  "name": "TENCENT",
+  "type": "BUY",
+  "quantity": 100,
+  "price": 298.4,
+  "amount": 29840.0,
+  "fee": 50.0,
+  "currency": "HKD"
+}
+```
+
+统计交易笔数：
+
+```bash
+tcos-parse /path/to/statement_202401.pdf -q | jq '.transactions | length'
+```
+
+---
+
+## 示例 9：批量解析多份结单
+
+**用户说**：我有几个月的结单，想一起解析
+
+用 shell 循环批量处理，每份结单输出到独立文件：
+
+```bash
+for pdf in /path/to/statements/*.pdf; do
+  name=$(basename "$pdf" .pdf)
+  tcos-parse "$pdf" -q -o "${name}.json"
+  echo "Done: $pdf -> ${name}.json"
+done
+```
+
+---
+
+## 示例 10：跳过清理步骤
+
+**用户说**：Stage3 清理把我的某些数据删了，我想跳过清理
+
+使用 `--no-clean` 跳过 Stage3 数据清理：
+
+```bash
+tcos-parse /path/to/statement_202401.pdf --no-clean
+```
+
+解析管道只执行 Stage1（提取）和 Stage2（格式化），不做去重和清洗。

package/.claude/skills/parse-statement/trigger-tests/cases.yaml

@@ -0,0 +1,133 @@
+# promptfoo Skill 触发率评估用例
+# 正例（22 个）：应触发 parse-statement skill
+# 负例（12 个）：不应触发
+
+version: 1
+testCases:
+  # ── 正例（positive）──────────────────────────────────────────────
+
+  # 直接要求解析（中英文）
+  - description: 中文直接要求解析 PDF 结单
+    input: '帮我解析这个 PDF 结单'
+    expected: triggered
+  - description: 英文要求解析券商结单
+    input: 'Parse this brokerage statement for me'
+    expected: triggered
+  - description: 英文解析 PDF 月结单
+    input: 'Can you parse my monthly PDF statement?'
+    expected: triggered
+
+  # 各种"结单"同义词
+  - description: 月结单
+    input: '这是我上个月的月结单，帮我分析一下'
+    expected: triggered
+  - description: 交易结单
+    input: '我有一份交易结单需要解析'
+    expected: triggered
+  - description: 对账单
+    input: '我的对账单来了，帮我解析'
+    expected: triggered
+  - description: 持仓报告（PDF）
+    input: '帮我读取这份 PDF 持仓报告'
+    expected: triggered
+
+  # 不同券商关键词
+  - description: 辉立关键词
+    input: '我有一份辉立的月结单'
+    expected: triggered
+  - description: Phillip 关键词
+    input: 'I have a Phillip Securities statement PDF'
+    expected: triggered
+  - description: 辉立证券全称
+    input: '帮我解析辉立证券的这份结单 PDF'
+    expected: triggered
+
+  # 不同动词
+  - description: 动词"读取"
+    input: '帮我读取这个 PDF 里的交易数据'
+    expected: triggered
+  - description: 动词"提取"
+    input: '从这个 PDF 里提取所有交易记录'
+    expected: triggered
+  - description: 动词"转换"
+    input: '把这个 PDF 转成 JSON 格式'
+    expected: triggered
+  - description: 动词"分析"
+    input: '分析一下这份结单 PDF'
+    expected: triggered
+  - description: 关键词"结单解析"
+    input: '能帮我做结单解析吗'
+    expected: triggered
+
+  # 用户描述场景
+  - description: 收到结单的场景
+    input: '我收到了券商发来的结单，帮我看看里面的交易'
+    expected: triggered
+  - description: 用户提供 PDF 路径
+    input: '帮我看看这个 PDF /tmp/statement_202401.pdf'
+    expected: triggered
+  - description: 帮我看看这个 PDF
+    input: '帮我看看这个 PDF 文件里有什么交易'
+    expected: triggered
+
+  # 组合场景
+  - description: 查看交易记录
+    input: '帮我从结单里查看我的交易记录'
+    expected: triggered
+  - description: 查看持仓情况
+    input: '帮我看看这份结单里的持仓情况'
+    expected: triggered
+  - description: 查看资产汇总
+    input: '解析一下这份 PDF，我想看资产汇总'
+    expected: triggered
+  - description: 批量解析
+    input: '我有几份 PDF 结单，能一起解析吗'
+    expected: triggered
+
+  # ── 负例（negative）──────────────────────────────────────────────
+
+  # 一般股市问题（无结单/PDF 语境）
+  - description: 一般股市行情问题
+    input: '帮我分析一下股市行情'
+    expected: not_triggered
+  - description: 股票推荐
+    input: '你觉得腾讯的股票值得买吗'
+    expected: not_triggered
+  - description: 港股交易时间
+    input: '港股的交易时间是什么时候'
+    expected: not_triggered
+
+  # 其他文档格式
+  - description: Excel 表格
+    input: '帮我解析这个 Excel 表格'
+    expected: not_triggered
+  - description: Word 文档
+    input: '帮我读取这份 Word 文档'
+    expected: not_triggered
+  - description: CSV 文件
+    input: '帮我导入这个 CSV 交易数据'
+    expected: not_triggered
+
+  # 一般财务问题（不涉及解析）
+  - description: 税务计算问题
+    input: '我今年的股票收益要交多少税'
+    expected: not_triggered
+  - description: 开户咨询
+    input: '怎么在辉立证券开户'
+    expected: not_triggered
+
+  # PDF 但不是结单
+  - description: 合同 PDF
+    input: '帮我看看这份 PDF 合同'
+    expected: not_triggered
+  - description: 招股说明书
+    input: '帮我读取这份 PDF 招股说明书'
+    expected: not_triggered
+
+  # IPO 相关但不涉及解析
+  - description: IPO 概念问题
+    input: '什么是 IPO？'
+    expected: not_triggered
+  - description: 申购操作问题
+    input: '怎么在手机上申购新股'
+    expected: not_triggered

package/README.md

@@ -0,0 +1,153 @@
+# @tcos/broker-parser
+
+> Parse brokerage PDF statements into structured JSON
+
+[![CI](https://github.com/biggersun/broker-parser/actions/workflows/ci.yml/badge.svg)](https://github.com/biggersun/broker-parser/actions)
+[![npm](https://img.shields.io/npm/v/@tcos/broker-parser)](https://www.npmjs.com/package/@tcos/broker-parser)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
+## Supported Brokers
+
+| Broker                        | Status    |
+| ----------------------------- | --------- |
+| Phillip Securities (辉立证券) | Supported |
+
+## Quick Start
+
+### Option 1: CLI
+
+```bash
+# Install
+npm install -g @tcos/broker-parser
+
+# Parse a PDF statement
+tcos-parse statement.pdf
+
+# Output to file
+tcos-parse statement.pdf -o result.json
+```
+
+### Option 2: As an npm Package
+
+```typescript
+import { ParsePipeline, PluginRegistry, PhillipPlugin } from '@tcos/broker-parser';
+
+const registry = new PluginRegistry();
+registry.register(new PhillipPlugin());
+const pipeline = new ParsePipeline(registry);
+
+const result = await pipeline.parse('./statement.pdf');
+console.log(result.data);
+```
+
+### Option 3: Claude Code Skill (Recommended for Non-Technical Users)
+
+After installing, tell Claude: "Help me parse this PDF statement"
+
+## Prerequisites
+
+- Node.js 18+
+- Python 3.8+ with `pdfplumber` (`pip install pdfplumber`)
+- poppler
+  - macOS: `brew install poppler`
+  - Ubuntu: `apt-get install poppler-utils`
+
+## CLI Reference
+
+| Command                        | Description                          |
+| ------------------------------ | ------------------------------------ |
+| `tcos-parse <pdf>`             | Parse PDF, output JSON to stdout     |
+| `tcos-parse <pdf> -o out.json` | Output to file                       |
+| `tcos-parse <pdf> --raw`       | Output Stage1 raw data only          |
+| `tcos-parse <pdf> --no-clean`  | Skip Stage3 cleaning step            |
+| `tcos-parse <pdf> -b phillip`  | Specify broker (skip auto-detect)    |
+| `tcos-parse --detect <pdf>`    | Detect which broker a PDF belongs to |
+| `tcos-parse --list-parsers`    | List available broker parsers        |
+| `tcos-parse <pdf> -v`          | Show stage timing to stderr          |
+| `tcos-parse <pdf> -q`          | Quiet mode, output JSON only         |
+
+## Pipeline Architecture
+
+```
+PDF File
+    |
+  Stage1: Extract (pdfplumber)
+    |  -> RawTableData
+    |
+  Stage2: Format (rule engine)
+    |  -> StatementData
+    |
+  Stage3: Clean (dedup, normalize)
+    |  -> StatementData (cleaned)
+    v
+  JSON Output
+```
+
+## Output Format
+
+```json
+{
+  "accountCode": "M000001",
+  "clientName": "USER A",
+  "statementDate": "2024-01-31",
+  "transactions": [
+    {
+      "transactionDate": "2024-01-15",
+      "stockCode": "1234",
+      "stockName": "EXAMPLE CO",
+      "transactionType": "BUY",
+      "quantity": 1000,
+      "price": 12.34,
+      "amount": -12340.0,
+      "currency": "HKD"
+    }
+  ],
+  "ipo": [],
+  "snapshots": [
+    {
+      "symbol": "HKD",
+      "assetCategory": "Cash",
+      "quantity": 50000.0,
+      "currency": "HKD"
+    }
+  ]
+}
+```
+
+Key type definitions:
+
+- **`StatementData`** — Full parsed statement (account info, transactions, IPO records, holdings snapshots)
+- **`TradeData`** — Individual trade record (BUY, SELL, DIVIDEND, FEE, etc.)
+- **`IPOData`** — IPO subscription/allotment record
+- **`SnapshotData`** — Holdings snapshot (cash balances, stock positions)
+
+## Adding a New Broker
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for the guide on implementing a new broker plugin.
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run CI tests (Stage2 + CLI, no PDF dependency)
+npm test
+
+# Run all tests including Stage1 (requires local PDFs)
+npm run test:local
+
+# Lint & format
+npm run lint
+npm run format:check
+
+# Type check
+npm run typecheck
+
+# Build
+npm run build
+```
+
+## License
+
+MIT

package/dist/cli/index.d.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * CLI 入口 — tcos-parse 命令
+ *
+ * 用法：
+ *   tcos-parse <pdf>              # 解析并输出 JSON 到 stdout
+ *   tcos-parse <pdf> -o out.json  # 输出到文件
+ *   tcos-parse <pdf> --raw        # 只输出 Stage1 原始数据
+ *   tcos-parse <pdf> --no-clean   # 跳过 Stage3 清理
+ *   tcos-parse -b phillip <pdf>   # 指定券商
+ *   tcos-parse --detect <pdf>     # 检测 PDF 所属券商
+ *   tcos-parse --list-parsers     # 列出支持的券商
+ *   tcos-parse -v <pdf>           # 显示各阶段耗时
+ *   tcos-parse -q <pdf>           # 静默模式，只输出 JSON
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;GAaG"}