taiwan-invoice-skill 2.6.4 → 2.7.1

package/README.md

@@ -3,14 +3,14 @@
 <h3 align="center">台灣電子發票 AI 開發技能包</h3>
 
 <p align="center">
-  <strong>支援 ECPay 綠界 · SmilePay 速買配 · Amego 光貿</strong>
+  <strong>支援 ECPay 綠界 · SmilePay 速買配 · Amego 光貿 · ezPay 簡單付 · PayNow 立吉富</strong>
 </p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/taiwan-invoice-skill"><img src="https://img.shields.io/npm/v/taiwan-invoice-skill?style=flat-square&logo=npm" alt="npm version"></a>
   <a href="https://www.npmjs.com/package/taiwan-invoice-skill"><img src="https://img.shields.io/npm/dm/taiwan-invoice-skill?style=flat-square&label=downloads" alt="npm downloads"></a>
-  <img src="https://img.shields.io/badge/node-%3E%3D18-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node.js">
-  <img src="https://img.shields.io/badge/platforms-14-blue?style=flat-square" alt="14 Platforms">
+  <img src="https://img.shields.io/badge/providers-5-success?style=flat-square" alt="5 Providers">
+  <img src="https://img.shields.io/badge/AI%20platforms-14-blue?style=flat-square" alt="14 AI Platforms">
   <a href="https://github.com/Moksa1123/taiwan-ecommerce-toolkit/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Moksa1123/taiwan-ecommerce-toolkit?style=flat-square" alt="License"></a>
 </p>
 
@@ -26,117 +26,80 @@
 npm install -g taiwan-invoice-skill
 ```
 
----
-
-## 使用方式
+## 快速開始
 
 ```bash
-# 進入專案目錄
 cd /path/to/your/project
 
-# 選擇你的 AI 助手
+taiwan-invoice init                    # 互動式選擇 AI 助手
 taiwan-invoice init --ai claude        # Claude Code
 taiwan-invoice init --ai cursor        # Cursor
 taiwan-invoice init --ai windsurf      # Windsurf
-taiwan-invoice init --ai copilot       # GitHub Copilot
-taiwan-invoice init --ai antigravity   # Antigravity
 taiwan-invoice init --ai all           # 全部安裝
 ```
 
-<details>
-<summary>完整平台列表</summary>
+安裝完後，直接在 AI 助手用自然語言：
 
-```bash
-taiwan-invoice init --ai kiro          # Kiro (AWS)
-taiwan-invoice init --ai codex         # Codex CLI (OpenAI)
-taiwan-invoice init --ai qoder         # Qoder
-taiwan-invoice init --ai roocode       # Roo Code
-taiwan-invoice init --ai gemini        # Gemini CLI
-taiwan-invoice init --ai trae          # Trae (ByteDance)
-taiwan-invoice init --ai opencode      # OpenCode
-taiwan-invoice init --ai continue      # Continue
-taiwan-invoice init --ai codebuddy     # CodeBuddy (Tencent)
 ```
-
-</details>
+使用 ECPay 測試環境開立 B2C 發票，金額 1050 元
+建立 ezPay B2B 發票，買方統編 12345678，未稅 1000、稅 50
+為 PayNow POS 機批次取 100 個發票號碼
+```
 
 ---
 
-## 其他指令
+## 5 家發票服務商
 
-```bash
-taiwan-invoice list         # 列出支援平台
-taiwan-invoice info         # 顯示技能資訊
-taiwan-invoice versions     # 列出可用版本
-taiwan-invoice update       # 檢查更新
-```
+| 服務商 | 加密 / 認證 | 適用場景 |
+|---|---|---|
+| **ECPay 綠界** | AES-128-CBC + HashKey/HashIV | 市佔率最高、SDK 完整、傳統電商首選 |
+| **SmilePay 速買配** | Grvc + Verify_key | 老牌穩定、整合最簡單、無 AES 門檻 |
+| **Amego 光貿** | MD5 簽章 + App Key | MIG 4.0 標準、現代 RESTful |
+| **ezPay 簡單付** | AES-256-CBC + 32 碼 HashKey + SHA256 | 藍新金流集團小型品牌、字軌管理、批次開立 |
+| **PayNow 立吉富** | JWT Bearer Token | 金物流發票一站式、POS 機批次取號流程 |
 
-### 選項
+每家附完整 Python 範例（B2C / B2B / 作廢 / 折讓）+ 反推的加密實作 + 測試帳號。
 
-```bash
-taiwan-invoice init --force     # 覆蓋現有檔案
-taiwan-invoice init --global    # 安裝到全域目錄（所有專案共用）
-```
+## 技能包內容
 
-### 全域安裝
+```
+taiwan-invoice/
+├── SKILL.md                          # AI 技能主文檔
+├── EXAMPLES.md                       # 完整範例集
+├── references/                       # 5 份 API 規格
+│   ├── ECPAY_API_REFERENCE.md
+│   ├── SMILEPAY_API_REFERENCE.md
+│   ├── AMEGO_API_REFERENCE.md
+│   ├── EZPAY_API_REFERENCE.md       # ezPay 5 本 PDF 蒸餾 1,084 行
+│   └── PAYNOW_API_REFERENCE.md      # PayNow JWT + POS 流程
+├── examples/                         # 5 個生產級 Python 範例
+└── data/                             # 7 份 CSV 資料
+    ├── providers.csv                # 5 服務商
+    ├── operations.csv               # 11 個 API 操作
+    ├── error-codes.csv              # 80+ 錯誤碼
+    └── ...
+```
 
-使用 `--global` 可將技能安裝到使用者目錄，讓所有專案都能使用：
+## CLI 指令
 
 ```bash
-taiwan-invoice init --ai cursor --global       # ~/.cursor/skills/taiwan-invoice/
-taiwan-invoice init --ai claude --global       # ~/.claude/skills/taiwan-invoice/
-taiwan-invoice init --ai antigravity --global  # ~/.gemini/antigravity/global_skills/taiwan-invoice/
+taiwan-invoice list                # 列出 AI 平台
+taiwan-invoice info                # 技能資訊
+taiwan-invoice update              # 檢查更新
+taiwan-invoice init --force        # 覆蓋安裝
+taiwan-invoice init --global       # 全域安裝
 ```
 
----
-
-## 支援平台
-
-| 平台 | 說明 | 啟動方式 |
-|------|------|----------|
-| **Claude Code** | Anthropic 官方 CLI | `/taiwan-invoice` |
-| **Cursor** | AI 程式編輯器 | `/taiwan-invoice` |
-| **Windsurf** | Codeium 編輯器 | 自動 |
-| **Copilot** | GitHub Copilot | `/taiwan-invoice` |
-| **Antigravity** | Google AI 助手 | `/taiwan-invoice` |
-| **Kiro** | AWS AI 助手 | `/taiwan-invoice` |
-| **Codex** | OpenAI CLI | 自動 |
-| **Qoder** | Qodo AI 助手 | 自動 |
-| **RooCode** | VSCode 擴充 | `/taiwan-invoice` |
-| **Gemini CLI** | Google Gemini | 自動 |
-| **Trae** | ByteDance AI | 自動 |
-| **OpenCode** | 開源 AI 助手 | 自動 |
-| **Continue** | 開源 AI 助手 | 自動 |
-| **CodeBuddy** | Tencent AI | 自動 |
-
----
-
-## 加值中心
-
-| 加值中心 | 驗證方式 | 特點 |
-|----------|----------|------|
-| **ECPay 綠界** | AES-128-CBC 加密 | 市佔率高，文件完整 |
-| **SmilePay 速買配** | URL 參數簽章 | 雙協定支援，整合簡單 |
-| **Amego 光貿** | MD5 簽章 (MIG 4.0) | API 設計乾淨 |
-
----
-
-## 智能工具
-
-安裝後包含以下 Python 工具（純 Python，無需外部依賴）：
+## 14 個 AI 平台支援
 
-```bash
-# BM25 搜索引擎 - 搜索錯誤碼、欄位映射、稅務規則
-python scripts/search.py "10000016" --domain error
+Claude Code · Cursor · Windsurf · Antigravity · GitHub Copilot · Kiro · Codex · Qoder · Roo Code · Gemini · Trae · OpenCode · Continue · CodeBuddy
 
-# 加值中心推薦系統 - 根據需求推薦服務商
-python scripts/recommend.py "電商 高交易量 穩定"
+## 相關套件
 
-# 代碼生成器 - 生成 TypeScript/Python 服務模組
-python scripts/generate-invoice-service.py ECPay --output ts
-```
+本套件是 **[Taiwan E-Commerce Toolkit](https://github.com/Moksa1123/taiwan-ecommerce-toolkit)** 的一部分：
 
----
+- [taiwan-payment-skill](https://www.npmjs.com/package/taiwan-payment-skill) — 10 家金流（ECPay / NewebPay / PAYUNi / SmilePay / PChomePay / ezPay / PayNow / Shopline / LINE Pay / TapPay）
+- [taiwan-logistics-skill](https://www.npmjs.com/package/taiwan-logistics-skill) — 7 家物流（含 HCT 新竹物流直連）
 
 ## 授權
 

package/assets/taiwan-invoice/CLAUDE.md

@@ -1,108 +1,108 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Project Overview
-
-Taiwan Invoice Skill is an AI-powered toolkit for Taiwan E-Invoice integration, providing API documentation, code examples, and scripts for major invoice platforms (ECPay, SmilePay, Amego). It works as a skill/workflow for AI coding assistants (Claude Code, Windsurf, Cursor, etc.).
-
-## Available Scripts
-
-```bash
-# Test API connectivity
-python3 taiwan-invoice/scripts/test_connection.py <platform>
-
-# Validate invoice data
-python3 taiwan-invoice/scripts/validate_invoice.py <json_file>
-
-# Generate invoice code
-python3 taiwan-invoice/scripts/generate_code.py <platform> <language>
-```
-
-**Supported Platforms:** `ecpay`, `smilepay`, `amego`
-
-## Architecture
-
-```
-taiwan-invoice/                     # Source of Truth
-├── SKILL.md                        # Main skill documentation
-├── EXAMPLES.md                     # Code examples and patterns
-├── references/                     # API documentation
-│   ├── ecpay-api.md
-│   ├── smilepay-api.md
-│   └── amego-api.md
-└── scripts/                        # Utility scripts
-    ├── test_connection.py
-    ├── validate_invoice.py
-    └── generate_code.py
-
-cli/                                # CLI installer (taiwan-invoice-skill on npm)
-├── src/
-│   ├── commands/init.ts            # Install command with template generation
-│   ├── utils/template.ts           # Template rendering engine
-│   ├── utils/github.ts             # GitHub release downloads
-│   └── utils/extract.ts            # ZIP extraction utilities
-└── assets/                         # Bundled assets
-    ├── taiwan-invoice/             # Copy of taiwan-invoice/
-    └── templates/
-        ├── base/                   # Base templates (skill-content.md)
-        └── platforms/              # Platform configs (14 platforms)
-
-.claude/skills/taiwan-invoice/      # Claude Code skill (generated by CLI)
-```
-
-## Sync Rules
-
-**Source of Truth:** `taiwan-invoice/`
-
-When modifying files:
-
-1. **Skill Content** - Edit in `taiwan-invoice/`:
-   - `SKILL.md` - Main documentation
-   - `EXAMPLES.md` - Code examples
-   - `references/*.md` - API documentation
-   - `scripts/*.py` - Utility scripts
-
-2. **Templates** - Edit in `cli/assets/templates/`:
-   - `base/skill-content.md` - Common skill content
-   - `platforms/*.json` - Platform-specific configs (14 platforms)
-
-3. **CLI Assets** - Run sync before publishing:
-   ```bash
-   cp -r taiwan-invoice/* cli/assets/taiwan-invoice/
-   ```
-
-4. **Reference Folders** - No manual sync needed. The CLI generates these from templates during `taiwan-invoice init`.
-
-## Supported AI Platforms
-
-| Platform     | Folder      | Install Type |
-|-------------|-------------|--------------|
-| Claude Code | `.claude`   | full         |
-| Cursor      | `.cursor`   | full         |
-| Windsurf    | `.windsurf` | full         |
-| Antigravity | `.agent`    | full         |
-| Copilot     | `.github`   | full         |
-| Kiro        | `.kiro`     | full         |
-| Codex       | `.codex`    | full         |
-| Qoder       | `.qoder`    | full         |
-| Roo Code    | `.roo`      | full         |
-| Gemini      | `.gemini`   | full         |
-| Trae        | `.trae`     | full         |
-| OpenCode    | `.opencode` | full         |
-| Continue    | `.continue` | full         |
-| CodeBuddy   | `.codebuddy`| full         |
-
-## Prerequisites
-
-- Node.js 18+ (for CLI)
-- Python 3.x (for scripts, no external dependencies)
-
-## Git Workflow
-
-Never push directly to `main`. Always:
-
-1. Create a new branch: `git checkout -b feat/...` or `fix/...`
-2. Commit changes
-3. Push branch: `git push -u origin <branch>`
-4. Create PR: `gh pr create`
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Taiwan Invoice Skill is an AI-powered toolkit for Taiwan E-Invoice integration, providing API documentation, code examples, and scripts for major invoice platforms (ECPay, SmilePay, Amego). It works as a skill/workflow for AI coding assistants (Claude Code, Windsurf, Cursor, etc.).
+
+## Available Scripts
+
+```bash
+# Test API connectivity
+python3 taiwan-invoice/scripts/test_connection.py <platform>
+
+# Validate invoice data
+python3 taiwan-invoice/scripts/validate_invoice.py <json_file>
+
+# Generate invoice code
+python3 taiwan-invoice/scripts/generate_code.py <platform> <language>
+```
+
+**Supported Platforms:** `ecpay`, `smilepay`, `amego`
+
+## Architecture
+
+```
+taiwan-invoice/                     # Source of Truth
+├── SKILL.md                        # Main skill documentation
+├── EXAMPLES.md                     # Code examples and patterns
+├── references/                     # API documentation
+│   ├── ecpay-api.md
+│   ├── smilepay-api.md
+│   └── amego-api.md
+└── scripts/                        # Utility scripts
+    ├── test_connection.py
+    ├── validate_invoice.py
+    └── generate_code.py
+
+cli/                                # CLI installer (taiwan-invoice-skill on npm)
+├── src/
+│   ├── commands/init.ts            # Install command with template generation
+│   ├── utils/template.ts           # Template rendering engine
+│   ├── utils/github.ts             # GitHub release downloads
+│   └── utils/extract.ts            # ZIP extraction utilities
+└── assets/                         # Bundled assets
+    ├── taiwan-invoice/             # Copy of taiwan-invoice/
+    └── templates/
+        ├── base/                   # Base templates (skill-content.md)
+        └── platforms/              # Platform configs (14 platforms)
+
+.claude/skills/taiwan-invoice/      # Claude Code skill (generated by CLI)
+```
+
+## Sync Rules
+
+**Source of Truth:** `taiwan-invoice/`
+
+When modifying files:
+
+1. **Skill Content** - Edit in `taiwan-invoice/`:
+   - `SKILL.md` - Main documentation
+   - `EXAMPLES.md` - Code examples
+   - `references/*.md` - API documentation
+   - `scripts/*.py` - Utility scripts
+
+2. **Templates** - Edit in `cli/assets/templates/`:
+   - `base/skill-content.md` - Common skill content
+   - `platforms/*.json` - Platform-specific configs (14 platforms)
+
+3. **CLI Assets** - Run sync before publishing:
+   ```bash
+   cp -r taiwan-invoice/* cli/assets/taiwan-invoice/
+   ```
+
+4. **Reference Folders** - No manual sync needed. The CLI generates these from templates during `taiwan-invoice init`.
+
+## Supported AI Platforms
+
+| Platform     | Folder      | Install Type |
+|-------------|-------------|--------------|
+| Claude Code | `.claude`   | full         |
+| Cursor      | `.cursor`   | full         |
+| Windsurf    | `.windsurf` | full         |
+| Antigravity | `.agent`    | full         |
+| Copilot     | `.github`   | full         |
+| Kiro        | `.kiro`     | full         |
+| Codex       | `.codex`    | full         |
+| Qoder       | `.qoder`    | full         |
+| Roo Code    | `.roo`      | full         |
+| Gemini      | `.gemini`   | full         |
+| Trae        | `.trae`     | full         |
+| OpenCode    | `.opencode` | full         |
+| Continue    | `.continue` | full         |
+| CodeBuddy   | `.codebuddy`| full         |
+
+## Prerequisites
+
+- Node.js 18+ (for CLI)
+- Python 3.x (for scripts, no external dependencies)
+
+## Git Workflow
+
+Never push directly to `main`. Always:
+
+1. Create a new branch: `git checkout -b feat/...` or `fix/...`
+2. Commit changes
+3. Push branch: `git push -u origin <branch>`
+4. Create PR: `gh pr create`