taiwan-logistics-skill 1.4.11 → 1.4.12
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +139 -142
- package/assets/taiwan-logistics/CLAUDE.md +150 -150
- package/assets/taiwan-logistics/EXAMPLES.md +2638 -2627
- package/assets/taiwan-logistics/README.md +139 -142
- package/assets/taiwan-logistics/README.zh-TW.md +139 -0
- package/assets/taiwan-logistics/SKILL.md +146 -145
- package/assets/taiwan-logistics/data/field-mappings.csv +23 -23
- package/assets/taiwan-logistics/data/logistics-types.csv +58 -57
- package/assets/taiwan-logistics/data/operations.csv +53 -51
- package/assets/taiwan-logistics/data/pending.csv +34 -6
- package/assets/taiwan-logistics/data/providers.csv +21 -21
- package/assets/taiwan-logistics/data/status-codes.csv +976 -964
- package/assets/taiwan-logistics/evals/RESULTS.md +32 -32
- package/assets/taiwan-logistics/evals/cases.json +158 -158
- package/assets/taiwan-logistics/evals/grade.py +121 -121
- package/assets/taiwan-logistics/examples/ecpay-logistics-cvs-example.py +220 -221
- package/assets/taiwan-logistics/examples/ezship-logistics-example.py +395 -395
- package/assets/taiwan-logistics/examples/hct-logistics-example.py +302 -285
- package/assets/taiwan-logistics/examples/newebpay-logistics-cvs-example.py +525 -538
- package/assets/taiwan-logistics/examples/paynow-logistics-cvs-example.py +243 -243
- package/assets/taiwan-logistics/examples/payuni-logistics-cvs-example.py +251 -251
- package/assets/taiwan-logistics/examples/pchomepay-logistics-cvs-example.py +254 -254
- package/assets/taiwan-logistics/examples/smilepay-logistics-cvs-example.py +332 -297
- package/assets/taiwan-logistics/examples/store-map-integration-example.html +566 -573
- package/assets/taiwan-logistics/references/NEWEBPAY_LOGISTICS_REFERENCE.md +808 -771
- package/assets/taiwan-logistics/references/audit-20261117.md +241 -0
- package/assets/taiwan-logistics/references/carrier-direct-access.md +137 -133
- package/assets/taiwan-logistics/references/ecpay-logistics-api.md +622 -567
- package/assets/taiwan-logistics/references/ezship-logistics-api.md +387 -387
- package/assets/taiwan-logistics/references/hct-logistics-api.md +1112 -1099
- package/assets/taiwan-logistics/references/implementation-guide.md +667 -667
- package/assets/taiwan-logistics/references/lalamove-logistics-api.md +177 -140
- package/assets/taiwan-logistics/references/ondemand-delivery.md +195 -183
- package/assets/taiwan-logistics/references/paynow-logistics-api.md +1719 -1672
- package/assets/taiwan-logistics/references/payuni-logistics-api.md +304 -296
- package/assets/taiwan-logistics/references/pchomepay-logistics-api.md +1155 -1151
- package/assets/taiwan-logistics/references/smilepay-logistics-api.md +1381 -1370
- package/assets/taiwan-logistics/requirements.txt +4 -4
- package/assets/taiwan-logistics/scripts/check_numbers.py +226 -166
- package/assets/taiwan-logistics/scripts/core.py +295 -295
- package/assets/taiwan-logistics/scripts/generate-logistics-service.py +87 -87
- package/assets/taiwan-logistics/scripts/recommend.py +370 -370
- package/assets/taiwan-logistics/scripts/search.py +142 -142
- package/assets/taiwan-logistics/scripts/test_logistics.py +154 -154
- package/assets/taiwan-logistics/scripts/test_skill.py +202 -202
- package/assets/templates/base/quick-reference.md +82 -82
- package/assets/templates/base/skill-content.md +142 -141
- package/assets/templates/platforms/agent.json +26 -26
- package/assets/templates/platforms/claude.json +26 -26
- package/assets/templates/platforms/cline.json +26 -26
- package/assets/templates/platforms/codebuddy.json +25 -25
- package/assets/templates/platforms/codex.json +26 -26
- package/assets/templates/platforms/continue.json +25 -25
- package/assets/templates/platforms/copilot.json +25 -25
- package/assets/templates/platforms/cursor.json +26 -26
- package/assets/templates/platforms/gemini.json +25 -25
- package/assets/templates/platforms/kiro.json +25 -25
- package/assets/templates/platforms/opencode.json +25 -25
- package/assets/templates/platforms/qoder.json +25 -25
- package/assets/templates/platforms/trae.json +25 -25
- package/assets/templates/platforms/windsurf.json +25 -25
- package/dist/index.js +1 -1
- package/package.json +65 -65
package/README.md
CHANGED
|
@@ -1,142 +1,139 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
```
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
<sub>Made by <strong>Moksa</strong></sub><br>
|
|
141
|
-
<sub>service@moksaweb.com</sub>
|
|
142
|
-
</p>
|
|
1
|
+
# taiwan-logistics
|
|
2
|
+
|
|
3
|
+
A Claude skill for integrating Taiwan logistics APIs: convenience-store pickup, home delivery, store-map selection, cash on delivery and shipment tracking, based on each provider's official documentation.
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/taiwan-logistics-skill)
|
|
6
|
+
[](https://github.com/Moksa1123/taiwan-ecommerce-toolkit/blob/main/LICENSE)
|
|
7
|
+
|
|
8
|
+
English | [繁體中文](https://github.com/Moksa1123/taiwan-ecommerce-toolkit/blob/main/taiwan-logistics/README.zh-TW.md)
|
|
9
|
+
|
|
10
|
+
This is an unofficial project. It is not affiliated with or endorsed by ECPay, NewebPay, PAYUNi, SmilePay, PChomePay, PayNow, ezShip, HCT, Lalamove, pandago, the convenience-store chains or any other company named here. Brand names are written the way each company writes them and belong to their owners.
|
|
11
|
+
|
|
12
|
+
## What it does
|
|
13
|
+
|
|
14
|
+
- Covers 7 aggregators with a logistics API (ECPay, NewebPay, PAYUNi, SmilePay, PChomePay, PayNow, ezShip), the HCT direct carrier API, and on-demand delivery (Lalamove, pandago).
|
|
15
|
+
- Gives Claude each provider's signing and encryption rules (MD5 CheckMacValue, AES-256-CBC, AES-256-GCM, 3DES) with runnable Python examples.
|
|
16
|
+
- Searches 1126 rows of data offline with `scripts/search.py`: providers, API operations, logistics types, field mappings and shipment status codes.
|
|
17
|
+
- Generates a service module for a provider (`scripts/generate-logistics-service.py`) and suggests a provider from plain-language requirements (`scripts/recommend.py`).
|
|
18
|
+
- Covers convenience-store pickup (7-ELEVEN, FamilyMart, Hi-Life, OK mart), home delivery, cold chain, store-map selectors, cash on delivery and tracking.
|
|
19
|
+
|
|
20
|
+
## When to use
|
|
21
|
+
|
|
22
|
+
Use it when you are:
|
|
23
|
+
|
|
24
|
+
- building a shipping flow with convenience-store pickup or home delivery;
|
|
25
|
+
- adding a store-map selector to a checkout;
|
|
26
|
+
- creating shipments, printing labels or reading status callbacks;
|
|
27
|
+
- looking up what a logistics status code means, or choosing a provider.
|
|
28
|
+
|
|
29
|
+
Use something else for:
|
|
30
|
+
|
|
31
|
+
- collecting payment, including the payment side of ECPay, NewebPay or PAYUNi: use [taiwan-payment](https://github.com/Moksa1123/taiwan-ecommerce-toolkit/tree/main/taiwan-payment);
|
|
32
|
+
- issuing e-invoices: use [taiwan-invoice](https://github.com/Moksa1123/taiwan-ecommerce-toolkit/tree/main/taiwan-invoice);
|
|
33
|
+
- shipping outside Taiwan, or a carrier contract that has no public API: not covered (the skill says so instead of guessing).
|
|
34
|
+
|
|
35
|
+
## Install
|
|
36
|
+
|
|
37
|
+
Requirements: Python 3 for the scripts, which use only the standard library. The files in `examples/` and the network options of `scripts/test_logistics.py` also need `pycryptodome` (AES, 3DES) and `requests`; install them with `pip install -r requirements.txt`. Node.js 18 or later is needed only for the npx installer. Works on Windows, macOS and Linux.
|
|
38
|
+
|
|
39
|
+
Claude Code plugin (installs all three Taiwan skills: invoice, payment, logistics):
|
|
40
|
+
|
|
41
|
+
```text
|
|
42
|
+
/plugin marketplace add Moksa1123/taiwan-ecommerce-toolkit
|
|
43
|
+
/plugin install taiwan-ecommerce@taiwan-ecommerce-toolkit
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
npx (copies the skill into the current project; `--ai` also accepts other agents such as `cursor` or `codex`, `--global` installs into your home directory):
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
npx taiwan-logistics-skill@1.4.12 init --ai claude
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Manual copy:
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
git clone https://github.com/Moksa1123/taiwan-ecommerce-toolkit.git
|
|
56
|
+
cp -r taiwan-ecommerce-toolkit/taiwan-logistics ~/.claude/skills/
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
## Quick start
|
|
60
|
+
|
|
61
|
+
Ask Claude, for example:
|
|
62
|
+
|
|
63
|
+
- "Add ECPay convenience-store pickup with a store map to my checkout, in Python."
|
|
64
|
+
- "Create a PAYUNi home-delivery shipment and download the label."
|
|
65
|
+
- "What does ECPay logistics status 2073 mean?"
|
|
66
|
+
|
|
67
|
+
Or search the data yourself from the skill folder:
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
python3 scripts/search.py "2073" --domain status --max 1
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Expected output (shortened):
|
|
74
|
+
|
|
75
|
+
```text
|
|
76
|
+
搜索查詢: '2073' (域: status)
|
|
77
|
+
[1] 分數: 7.62 | 域: status
|
|
78
|
+
provider: ecpay
|
|
79
|
+
code: 2073
|
|
80
|
+
status_zh: 包裹配達取件門市
|
|
81
|
+
category: at_store
|
|
82
|
+
description: 物流商:UNIMART、UNIMARTC2C、HILIFE、HILIFEC2C
|
|
83
|
+
doc_url: https://developers.ecpay.com.tw/7380/
|
|
84
|
+
trust: 官方文件
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
## Trigger phrases
|
|
88
|
+
|
|
89
|
+
English: Taiwan logistics, CVS pickup, convenience-store pickup, store-to-store shipping, store map, home delivery, cold chain, cash on delivery, shipment tracking, logistics status code, HCT, Lalamove, on-demand delivery.
|
|
90
|
+
|
|
91
|
+
中文:物流串接、超商取貨、店到店、大宗寄倉、取貨付款、電子地圖選店、宅配、冷凍、物流狀態碼、托運單、新竹物流、即時配送。
|
|
92
|
+
|
|
93
|
+
## What it runs and connects to
|
|
94
|
+
|
|
95
|
+
The skill is Markdown documentation, CSV data and local Python scripts. It never sends data anywhere on its own. Network calls happen only when you run a connectivity option of the test script or run an example file.
|
|
96
|
+
|
|
97
|
+
| Script | What it does | Network | Files written |
|
|
98
|
+
|---|---|---|---|
|
|
99
|
+
| `scripts/search.py` | Searches `data/*.csv` | None | None |
|
|
100
|
+
| `scripts/recommend.py` | Suggests a provider from `data/*.csv` | None | None |
|
|
101
|
+
| `scripts/generate-logistics-service.py` | Prints a Python or TypeScript module for a provider | None | None (writes to standard output) |
|
|
102
|
+
| `scripts/test_logistics.py` | Known-answer test of ECPay signing; offline by default | `--live`: HEAD request to the sandbox of ECPay (`logistics-stage.ecpay.com.tw`), NewebPay (`ccore.newebpay.com`) and PAYUNi (`sandbox-api.payuni.com.tw`). `--create` and `--query`: POST to the ECPay logistics sandbox | None |
|
|
103
|
+
| `scripts/check_numbers.py` | Checks that every number in `SKILL.md` and these READMEs matches the data | None | With `--fix`, those three files |
|
|
104
|
+
| `scripts/test_skill.py` | Self-test; runs the checks above offline | None | None |
|
|
105
|
+
| `examples/*.py` | Reference clients for each provider | When run directly, calls the sandbox or production host defined at the top of that file | None |
|
|
106
|
+
| `examples/store-map-integration-example.html` | Store-map sample page and server code | None by itself; callback URLs are placeholders | None |
|
|
107
|
+
|
|
108
|
+
Credentials (merchant ID, HashKey and HashIV, API keys and secrets, carrier account numbers) are supplied by you in your own code or configuration, for example environment variables. The repository stores no real credentials. Test values that appear in the docs and scripts are the providers' published sandbox values.
|
|
109
|
+
|
|
110
|
+
## How it's verified
|
|
111
|
+
|
|
112
|
+
- Data source: official provider API documentation, PDF specifications and SDKs. Every source is registered in [`sources/official-sources.json`](https://github.com/Moksa1123/taiwan-ecommerce-toolkit/blob/main/sources/official-sources.json), and each data row carries `doc_url` and `trust`.
|
|
113
|
+
- Self-test: `python3 scripts/test_skill.py` runs 42 checks, 0 failures (run on 2026-11-17).
|
|
114
|
+
- Evals: on the 11 scored questions, Claude answered 11 correctly with the skill and 0 without it. See [`evals/RESULTS.md`](https://github.com/Moksa1123/taiwan-ecommerce-toolkit/blob/main/taiwan-logistics/evals/RESULTS.md).
|
|
115
|
+
- CI runs `scripts/verify-examples.py`, which compares the example code byte for byte with expected values produced by the providers' own SDKs and spec samples ([`tests/vectors/`](https://github.com/Moksa1123/taiwan-ecommerce-toolkit/tree/main/tests/vectors)).
|
|
116
|
+
|
|
117
|
+
## Limits
|
|
118
|
+
|
|
119
|
+
- Convenience-store chains, T-cat, Chunghwa Post and other carriers without a public API are listed only so Claude can say so; reach them through an aggregator.
|
|
120
|
+
- Lalamove and pandago have references but no runnable example. HCT documentation is available only after applying to HCT.
|
|
121
|
+
- `test_logistics.py --create` and `--query` work with ECPay only; NewebPay and PAYUNi need your own merchant account.
|
|
122
|
+
- Known gaps are tracked in [`data/pending.csv`](https://github.com/Moksa1123/taiwan-ecommerce-toolkit/blob/main/taiwan-logistics/data/pending.csv).
|
|
123
|
+
|
|
124
|
+
## Repo layout
|
|
125
|
+
|
|
126
|
+
```text
|
|
127
|
+
taiwan-logistics/
|
|
128
|
+
├── SKILL.md # instructions Claude reads
|
|
129
|
+
├── EXAMPLES.md # longer code examples
|
|
130
|
+
├── references/ # one API reference per provider, on-demand overview
|
|
131
|
+
├── examples/ # runnable Python clients and a store-map page
|
|
132
|
+
├── data/ # CSV data for search.py and recommend.py; pending.csv
|
|
133
|
+
├── scripts/ # search, recommend, generator, tests, number check
|
|
134
|
+
└── evals/ # eval questions, grader and results
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
## License & author
|
|
138
|
+
|
|
139
|
+
MIT License. Made by Moksa ([moksaweb.com](https://moksaweb.com)). Part of [Taiwan E-commerce Toolkit](https://github.com/Moksa1123/taiwan-ecommerce-toolkit).
|
|
@@ -1,150 +1,150 @@
|
|
|
1
|
-
# CLAUDE.md
|
|
2
|
-
|
|
3
|
-
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
4
|
-
|
|
5
|
-
## Project Overview
|
|
6
|
-
|
|
7
|
-
Taiwan Logistics Skill is an AI-powered toolkit for Taiwan logistics integration, providing API documentation, code examples, and scripts for major logistics platforms. It works as a skill/workflow for AI coding assistants (Claude Code, Windsurf, Cursor, etc.).
|
|
8
|
-
|
|
9
|
-
**Supported Providers:** `ecpay`, `newebpay`, `payuni`, `smilepay`, `pchomepay`, `paynow`, `ezship`, `lalamove`, `pandago`, `hct_direct`
|
|
10
|
-
|
|
11
|
-
**即時/同城配送(`ondemand`):** `lalamove`、`pandago` 兩家。此分類與批次物流(超取/宅配)的資料模型不同——報價有效期短、以「趟」為單位、司機有即時座標。見 `references/ondemand-delivery.md`。
|
|
12
|
-
|
|
13
|
-
**No public API(僅列於 providers.csv 供查詢,`api_available=false`):** 黑貓 t-cat、嘉里大榮、宅配通、中華郵政、7-11 交貨便/賣貨便、全家好賣+、萊爾富、OK、蝦皮店到店。原因與替代路徑見 `references/carrier-direct-access.md`。
|
|
14
|
-
|
|
15
|
-
## Available Scripts
|
|
16
|
-
|
|
17
|
-
```bash
|
|
18
|
-
# Search API documentation (BM25)
|
|
19
|
-
python3 taiwan-logistics/scripts/search.py "<query>" [--domain <domain>]
|
|
20
|
-
|
|
21
|
-
# Recommend logistics provider
|
|
22
|
-
python3 taiwan-logistics/scripts/recommend.py "<requirements>"
|
|
23
|
-
|
|
24
|
-
# 簽章已知答案 + 測試環境連線(ecpay 另可 --create / --query)
|
|
25
|
-
python3 taiwan-logistics/scripts/test_logistics.py [ecpay|newebpay|payuni]
|
|
26
|
-
|
|
27
|
-
# 輸出已驗證的服務實作(py:examples/;ts:EXAMPLES.md 的 verify 片段)
|
|
28
|
-
python3 taiwan-logistics/scripts/generate-logistics-service.py <Provider> --output <ts|py>
|
|
29
|
-
```
|
|
30
|
-
|
|
31
|
-
## Architecture
|
|
32
|
-
|
|
33
|
-
```
|
|
34
|
-
taiwan-logistics/ # Source of Truth
|
|
35
|
-
├── SKILL.md # Main skill documentation
|
|
36
|
-
├── EXAMPLES.md # Code examples and patterns
|
|
37
|
-
├── references/ # API documentation
|
|
38
|
-
│ ├── ecpay-logistics-api.md
|
|
39
|
-
│ ├── NEWEBPAY_LOGISTICS_REFERENCE.md
|
|
40
|
-
│ ├── payuni-logistics-api.md
|
|
41
|
-
│ ├── smilepay-logistics-api.md # Pay_zg matrix
|
|
42
|
-
│ ├── pchomepay-logistics-api.md # 金物流二合一
|
|
43
|
-
│ ├── paynow-logistics-api.md # Logistic_service 產品線, 3DES/ECB
|
|
44
|
-
│ ├── ezship-logistics-api.md
|
|
45
|
-
│ ├── hct-logistics-api.md # HCT 直連 carrier API
|
|
46
|
-
│ ├── lalamove-logistics-api.md
|
|
47
|
-
│ ├── ondemand-delivery.md
|
|
48
|
-
│ └── carrier-direct-access.md # 無公開 API 的物流業者
|
|
49
|
-
├── examples/ # 可執行範例(CI 以官方測試向量驗證)
|
|
50
|
-
└── data/ # Data-driven CSVs
|
|
51
|
-
├── providers.csv # 10 可串接 + 10 僅供查詢(含 doc_access 分級)
|
|
52
|
-
├── operations.csv # cross-provider API operations
|
|
53
|
-
├── logistics-types.csv # 各家實際參數值(子類型/溫層/代收上限)
|
|
54
|
-
├── status-codes.csv # vendor-specific status codes
|
|
55
|
-
└── field-mappings.csv # 跨 provider 欄位對照(含即時配送)
|
|
56
|
-
|
|
57
|
-
logistics-cli/ # CLI installer (taiwan-logistics-skill on npm)
|
|
58
|
-
├── src/
|
|
59
|
-
│ ├── commands/init.ts # Install command with template generation
|
|
60
|
-
│ └── utils/template.ts # Template rendering engine
|
|
61
|
-
└── assets/ # Bundled assets
|
|
62
|
-
├── taiwan-logistics/ # Copy of taiwan-logistics/
|
|
63
|
-
└── templates/
|
|
64
|
-
├── base/ # Base templates (skill-content.md, quick-reference.md)
|
|
65
|
-
└── platforms/ # Platform configs (14 platforms)
|
|
66
|
-
|
|
67
|
-
.claude/skills/taiwan-logistics/ # Claude Code skill (generated by CLI)
|
|
68
|
-
```
|
|
69
|
-
|
|
70
|
-
## Sync Rules
|
|
71
|
-
|
|
72
|
-
**Source of Truth:** `taiwan-logistics/`
|
|
73
|
-
|
|
74
|
-
When modifying files:
|
|
75
|
-
|
|
76
|
-
1. **Skill Content** - Edit in `taiwan-logistics/`:
|
|
77
|
-
- `SKILL.md` - Main documentation
|
|
78
|
-
- `EXAMPLES.md` - Code examples
|
|
79
|
-
- `references/*.md` - API documentation
|
|
80
|
-
- `scripts/*.py` - Utility scripts
|
|
81
|
-
- `data/*.csv` - Data files
|
|
82
|
-
|
|
83
|
-
2. **Templates** - Edit in `logistics-cli/assets/templates/`:
|
|
84
|
-
- `base/skill-content.md` - Common skill content
|
|
85
|
-
- `base/quick-reference.md` - Quick reference (Claude only)
|
|
86
|
-
- `platforms/*.json` - Platform-specific configs (14 platforms)
|
|
87
|
-
|
|
88
|
-
3. **CLI Assets** - 自動同步,無需手動複製:
|
|
89
|
-
- `<cli>/scripts/build.js` 會在打包前呼叫 `scripts/sync-assets.mjs`,
|
|
90
|
-
因此 `npm run build` 與 `npm publish`(透過 prepublishOnly)都會自動帶到最新內容
|
|
91
|
-
- 發布流程另以 `node scripts/sync-assets.mjs --check` 驗證,落差會擋下發布
|
|
92
|
-
|
|
93
|
-
```bash
|
|
94
|
-
node scripts/sync-assets.mjs # 手動同步全部
|
|
95
|
-
node scripts/sync-assets.mjs --check # 只檢查,有落差 exit 1
|
|
96
|
-
```
|
|
97
|
-
|
|
98
|
-
> assets 會隨 npm publish 一起發布(package.json 的 `files` 含 `assets`),
|
|
99
|
-
> 過去忘記同步會靜默發出過期的 skill 內容,因此改為自動化。
|
|
100
|
-
|
|
101
|
-
## Supported AI Platforms
|
|
102
|
-
|
|
103
|
-
| Platform | Folder | Install Type |
|
|
104
|
-
|-------------|-------------|--------------|
|
|
105
|
-
| Claude Code | `.claude` | full |
|
|
106
|
-
| Cursor | `.cursor` | full |
|
|
107
|
-
| Windsurf | `.windsurf` | full |
|
|
108
|
-
| Antigravity | `.agents` | full |
|
|
109
|
-
| Copilot | `.github` | full |
|
|
110
|
-
| Kiro | `.kiro` | full |
|
|
111
|
-
| Codex | `.agents` | full |
|
|
112
|
-
| Qoder | `.qoder` | full |
|
|
113
|
-
| Cline | `.cline` | full |
|
|
114
|
-
| Gemini | `.gemini` | full |
|
|
115
|
-
| Trae | `.trae` | full |
|
|
116
|
-
| OpenCode | `.opencode` | full |
|
|
117
|
-
| Continue | `.continue` | full |
|
|
118
|
-
| CodeBuddy | `.codebuddy`| full |
|
|
119
|
-
|
|
120
|
-
## Prerequisites
|
|
121
|
-
|
|
122
|
-
- Node.js 18+ (for CLI)
|
|
123
|
-
- Python 3.x (for scripts, no external dependencies)
|
|
124
|
-
|
|
125
|
-
## Encryption Methods
|
|
126
|
-
|
|
127
|
-
| Provider | Encryption | Notes |
|
|
128
|
-
|---|---|---|
|
|
129
|
-
| ECPay 綠界 | MD5 CheckMacValue | Sort params + HashKey/HashIV |
|
|
130
|
-
| NewebPay 藍新 | AES-256-CBC + SHA256 | HashData = SHA256(`HashKey=..&EncryptData&HashIV=..`);送出欄位帶 `_`,回應不帶 |
|
|
131
|
-
| PAYUNi 統一 | AES-256-GCM + SHA256 | EncryptInfo = hex(base64(密文) + `:::` + base64(tag));HashInfo = SHA256(HashKey + EncryptInfo + HashIV) |
|
|
132
|
-
| SmilePay 速買配 | Verify_key + Mid_smilepay 加權檢核碼 | No AES; shared secret |
|
|
133
|
-
| PChomePay
|
|
134
|
-
| PayNow 立吉富 | **3DES (TripleDES) / ECB / Zero-Padding → Base64** | Key = `1234567890` + Password + `123456`(24 bytes);ECB 不使用 IV;PassCode = SHA1;**不同於金流端的動態 AES-256** |
|
|
135
|
-
| HCT 直連 | 自訂加密(金鑰申請後提供) | C# sample code only |
|
|
136
|
-
|
|
137
|
-
## Git Workflow
|
|
138
|
-
|
|
139
|
-
Never push directly to `main`. Always:
|
|
140
|
-
|
|
141
|
-
1. Create a new branch: `git checkout -b feat/...` or `fix/...`
|
|
142
|
-
2. Commit changes
|
|
143
|
-
3. Push branch: `git push -u origin <branch>`
|
|
144
|
-
4. Create PR: `gh pr create`
|
|
145
|
-
|
|
146
|
-
## Related Projects
|
|
147
|
-
|
|
148
|
-
- **Taiwan Invoice Skill** - E-Invoice integration (ECPay, SmilePay, Amego, ezPay, PayNow, O'Pay, SunPay)
|
|
149
|
-
- **Taiwan Payment Skill** - Payment integration (14 providers: ECPay, NewebPay, PAYUNi, SmilePay, PChomePay, ezPay, PayNow, Shopline, LINE Pay, TapPay, O'Pay, JKOPAY, SunPay, GoMyPay)
|
|
150
|
-
|
|
1
|
+
# CLAUDE.md
|
|
2
|
+
|
|
3
|
+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
4
|
+
|
|
5
|
+
## Project Overview
|
|
6
|
+
|
|
7
|
+
Taiwan Logistics Skill is an AI-powered toolkit for Taiwan logistics integration, providing API documentation, code examples, and scripts for major logistics platforms. It works as a skill/workflow for AI coding assistants (Claude Code, Windsurf, Cursor, etc.).
|
|
8
|
+
|
|
9
|
+
**Supported Providers:** `ecpay`, `newebpay`, `payuni`, `smilepay`, `pchomepay`, `paynow`, `ezship`, `lalamove`, `pandago`, `hct_direct`
|
|
10
|
+
|
|
11
|
+
**即時/同城配送(`ondemand`):** `lalamove`、`pandago` 兩家。此分類與批次物流(超取/宅配)的資料模型不同——報價有效期短、以「趟」為單位、司機有即時座標。見 `references/ondemand-delivery.md`。
|
|
12
|
+
|
|
13
|
+
**No public API(僅列於 providers.csv 供查詢,`api_available=false`):** 黑貓 t-cat、嘉里大榮、宅配通、中華郵政、7-11 交貨便/賣貨便、全家好賣+、萊爾富、OK、蝦皮店到店。原因與替代路徑見 `references/carrier-direct-access.md`。
|
|
14
|
+
|
|
15
|
+
## Available Scripts
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
# Search API documentation (BM25)
|
|
19
|
+
python3 taiwan-logistics/scripts/search.py "<query>" [--domain <domain>]
|
|
20
|
+
|
|
21
|
+
# Recommend logistics provider
|
|
22
|
+
python3 taiwan-logistics/scripts/recommend.py "<requirements>"
|
|
23
|
+
|
|
24
|
+
# 簽章已知答案 + 測試環境連線(ecpay 另可 --create / --query)
|
|
25
|
+
python3 taiwan-logistics/scripts/test_logistics.py [ecpay|newebpay|payuni]
|
|
26
|
+
|
|
27
|
+
# 輸出已驗證的服務實作(py:examples/;ts:EXAMPLES.md 的 verify 片段)
|
|
28
|
+
python3 taiwan-logistics/scripts/generate-logistics-service.py <Provider> --output <ts|py>
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
## Architecture
|
|
32
|
+
|
|
33
|
+
```
|
|
34
|
+
taiwan-logistics/ # Source of Truth
|
|
35
|
+
├── SKILL.md # Main skill documentation
|
|
36
|
+
├── EXAMPLES.md # Code examples and patterns
|
|
37
|
+
├── references/ # API documentation
|
|
38
|
+
│ ├── ecpay-logistics-api.md
|
|
39
|
+
│ ├── NEWEBPAY_LOGISTICS_REFERENCE.md
|
|
40
|
+
│ ├── payuni-logistics-api.md
|
|
41
|
+
│ ├── smilepay-logistics-api.md # Pay_zg matrix
|
|
42
|
+
│ ├── pchomepay-logistics-api.md # 金物流二合一
|
|
43
|
+
│ ├── paynow-logistics-api.md # Logistic_service 產品線, 3DES/ECB
|
|
44
|
+
│ ├── ezship-logistics-api.md
|
|
45
|
+
│ ├── hct-logistics-api.md # HCT 直連 carrier API
|
|
46
|
+
│ ├── lalamove-logistics-api.md
|
|
47
|
+
│ ├── ondemand-delivery.md
|
|
48
|
+
│ └── carrier-direct-access.md # 無公開 API 的物流業者
|
|
49
|
+
├── examples/ # 可執行範例(CI 以官方測試向量驗證)
|
|
50
|
+
└── data/ # Data-driven CSVs
|
|
51
|
+
├── providers.csv # 10 可串接 + 10 僅供查詢(含 doc_access 分級)
|
|
52
|
+
├── operations.csv # cross-provider API operations
|
|
53
|
+
├── logistics-types.csv # 各家實際參數值(子類型/溫層/代收上限)
|
|
54
|
+
├── status-codes.csv # vendor-specific status codes
|
|
55
|
+
└── field-mappings.csv # 跨 provider 欄位對照(含即時配送)
|
|
56
|
+
|
|
57
|
+
logistics-cli/ # CLI installer (taiwan-logistics-skill on npm)
|
|
58
|
+
├── src/
|
|
59
|
+
│ ├── commands/init.ts # Install command with template generation
|
|
60
|
+
│ └── utils/template.ts # Template rendering engine
|
|
61
|
+
└── assets/ # Bundled assets
|
|
62
|
+
├── taiwan-logistics/ # Copy of taiwan-logistics/
|
|
63
|
+
└── templates/
|
|
64
|
+
├── base/ # Base templates (skill-content.md, quick-reference.md)
|
|
65
|
+
└── platforms/ # Platform configs (14 platforms)
|
|
66
|
+
|
|
67
|
+
.claude/skills/taiwan-logistics/ # Claude Code skill (generated by CLI)
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
## Sync Rules
|
|
71
|
+
|
|
72
|
+
**Source of Truth:** `taiwan-logistics/`
|
|
73
|
+
|
|
74
|
+
When modifying files:
|
|
75
|
+
|
|
76
|
+
1. **Skill Content** - Edit in `taiwan-logistics/`:
|
|
77
|
+
- `SKILL.md` - Main documentation
|
|
78
|
+
- `EXAMPLES.md` - Code examples
|
|
79
|
+
- `references/*.md` - API documentation
|
|
80
|
+
- `scripts/*.py` - Utility scripts
|
|
81
|
+
- `data/*.csv` - Data files
|
|
82
|
+
|
|
83
|
+
2. **Templates** - Edit in `logistics-cli/assets/templates/`:
|
|
84
|
+
- `base/skill-content.md` - Common skill content
|
|
85
|
+
- `base/quick-reference.md` - Quick reference (Claude only)
|
|
86
|
+
- `platforms/*.json` - Platform-specific configs (14 platforms)
|
|
87
|
+
|
|
88
|
+
3. **CLI Assets** - 自動同步,無需手動複製:
|
|
89
|
+
- `<cli>/scripts/build.js` 會在打包前呼叫 `scripts/sync-assets.mjs`,
|
|
90
|
+
因此 `npm run build` 與 `npm publish`(透過 prepublishOnly)都會自動帶到最新內容
|
|
91
|
+
- 發布流程另以 `node scripts/sync-assets.mjs --check` 驗證,落差會擋下發布
|
|
92
|
+
|
|
93
|
+
```bash
|
|
94
|
+
node scripts/sync-assets.mjs # 手動同步全部
|
|
95
|
+
node scripts/sync-assets.mjs --check # 只檢查,有落差 exit 1
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
> assets 會隨 npm publish 一起發布(package.json 的 `files` 含 `assets`),
|
|
99
|
+
> 過去忘記同步會靜默發出過期的 skill 內容,因此改為自動化。
|
|
100
|
+
|
|
101
|
+
## Supported AI Platforms
|
|
102
|
+
|
|
103
|
+
| Platform | Folder | Install Type |
|
|
104
|
+
|-------------|-------------|--------------|
|
|
105
|
+
| Claude Code | `.claude` | full |
|
|
106
|
+
| Cursor | `.cursor` | full |
|
|
107
|
+
| Windsurf | `.windsurf` | full |
|
|
108
|
+
| Antigravity | `.agents` | full |
|
|
109
|
+
| Copilot | `.github` | full |
|
|
110
|
+
| Kiro | `.kiro` | full |
|
|
111
|
+
| Codex | `.agents` | full |
|
|
112
|
+
| Qoder | `.qoder` | full |
|
|
113
|
+
| Cline | `.cline` | full |
|
|
114
|
+
| Gemini | `.gemini` | full |
|
|
115
|
+
| Trae | `.trae` | full |
|
|
116
|
+
| OpenCode | `.opencode` | full |
|
|
117
|
+
| Continue | `.continue` | full |
|
|
118
|
+
| CodeBuddy | `.codebuddy`| full |
|
|
119
|
+
|
|
120
|
+
## Prerequisites
|
|
121
|
+
|
|
122
|
+
- Node.js 18+ (for CLI)
|
|
123
|
+
- Python 3.x (for scripts, no external dependencies)
|
|
124
|
+
|
|
125
|
+
## Encryption Methods
|
|
126
|
+
|
|
127
|
+
| Provider | Encryption | Notes |
|
|
128
|
+
|---|---|---|
|
|
129
|
+
| ECPay 綠界 | MD5 CheckMacValue | Sort params + HashKey/HashIV |
|
|
130
|
+
| NewebPay 藍新 | AES-256-CBC + SHA256 | HashData = SHA256(`HashKey=..&EncryptData&HashIV=..`);送出欄位帶 `_`,回應不帶 |
|
|
131
|
+
| PAYUNi 統一 | AES-256-GCM + SHA256 | EncryptInfo = hex(base64(密文) + `:::` + base64(tag));HashInfo = SHA256(HashKey + EncryptInfo + HashIV) |
|
|
132
|
+
| SmilePay 速買配 | Verify_key + Mid_smilepay 加權檢核碼 | No AES; shared secret |
|
|
133
|
+
| PChomePay支付連 | HTTP Basic Auth → 8h pcpay-token;Notify 須 3 秒內回 `success` | Same as payment side |
|
|
134
|
+
| PayNow 立吉富 | **3DES (TripleDES) / ECB / Zero-Padding → Base64** | Key = `1234567890` + Password + `123456`(24 bytes);ECB 不使用 IV;PassCode = SHA1;**不同於金流端的動態 AES-256** |
|
|
135
|
+
| HCT 直連 | 自訂加密(金鑰申請後提供) | C# sample code only |
|
|
136
|
+
|
|
137
|
+
## Git Workflow
|
|
138
|
+
|
|
139
|
+
Never push directly to `main`. Always:
|
|
140
|
+
|
|
141
|
+
1. Create a new branch: `git checkout -b feat/...` or `fix/...`
|
|
142
|
+
2. Commit changes
|
|
143
|
+
3. Push branch: `git push -u origin <branch>`
|
|
144
|
+
4. Create PR: `gh pr create`
|
|
145
|
+
|
|
146
|
+
## Related Projects
|
|
147
|
+
|
|
148
|
+
- **Taiwan Invoice Skill** - E-Invoice integration (ECPay, SmilePay, Amego, ezPay, PayNow, O'Pay, SunPay)
|
|
149
|
+
- **Taiwan Payment Skill** - Payment integration (14 providers: ECPay, NewebPay, PAYUNi, SmilePay, PChomePay, ezPay, PayNow, Shopline, LINE Pay, TapPay, O'Pay, JKOPAY, SunPay, GoMyPay)
|
|
150
|
+
|