taiwan-logistics-skill 1.2.2 → 1.3.0

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.
Files changed (46) hide show
  1. package/README.md +132 -132
  2. package/assets/taiwan-logistics/CLAUDE.md +147 -137
  3. package/assets/taiwan-logistics/EXAMPLES.md +3258 -3258
  4. package/assets/taiwan-logistics/README.md +132 -132
  5. package/assets/taiwan-logistics/SKILL.md +845 -845
  6. package/assets/taiwan-logistics/data/field-mappings.csv +23 -27
  7. package/assets/taiwan-logistics/data/logistics-types.csv +29 -25
  8. package/assets/taiwan-logistics/data/operations.csv +32 -32
  9. package/assets/taiwan-logistics/data/providers.csv +20 -15
  10. package/assets/taiwan-logistics/data/status-codes.csv +89 -35
  11. package/assets/taiwan-logistics/examples/ecpay-logistics-cvs-example.py +175 -175
  12. package/assets/taiwan-logistics/examples/newebpay-logistics-cvs-example.py +524 -524
  13. package/assets/taiwan-logistics/examples/payuni-logistics-cvs-example.py +605 -605
  14. package/assets/taiwan-logistics/examples/store-map-integration-example.html +573 -573
  15. package/assets/taiwan-logistics/references/NEWEBPAY_LOGISTICS_REFERENCE.md +774 -774
  16. package/assets/taiwan-logistics/references/carrier-direct-access.md +134 -0
  17. package/assets/taiwan-logistics/references/ecpay-logistics-api.md +536 -536
  18. package/assets/taiwan-logistics/references/ezship-logistics-api.md +103 -0
  19. package/assets/taiwan-logistics/references/hct-logistics-api.md +1102 -1102
  20. package/assets/taiwan-logistics/references/lalamove-logistics-api.md +138 -0
  21. package/assets/taiwan-logistics/references/paynow-logistics-api.md +1670 -1670
  22. package/assets/taiwan-logistics/references/payuni-logistics-api.md +712 -712
  23. package/assets/taiwan-logistics/references/pchomepay-logistics-api.md +1154 -1154
  24. package/assets/taiwan-logistics/references/smilepay-logistics-api.md +1332 -1332
  25. package/assets/taiwan-logistics/scripts/core.py +276 -276
  26. package/assets/taiwan-logistics/scripts/generate-logistics-service.py +1248 -1248
  27. package/assets/taiwan-logistics/scripts/recommend.py +370 -364
  28. package/assets/taiwan-logistics/scripts/search.py +127 -127
  29. package/assets/taiwan-logistics/scripts/test_logistics.py +300 -300
  30. package/assets/templates/base/quick-reference.md +74 -74
  31. package/assets/templates/base/skill-content.md +845 -845
  32. package/assets/templates/platforms/agent.json +26 -26
  33. package/assets/templates/platforms/claude.json +26 -26
  34. package/assets/templates/platforms/codebuddy.json +25 -25
  35. package/assets/templates/platforms/codex.json +26 -26
  36. package/assets/templates/platforms/continue.json +25 -25
  37. package/assets/templates/platforms/copilot.json +25 -25
  38. package/assets/templates/platforms/cursor.json +26 -26
  39. package/assets/templates/platforms/gemini.json +25 -25
  40. package/assets/templates/platforms/kiro.json +25 -25
  41. package/assets/templates/platforms/opencode.json +25 -25
  42. package/assets/templates/platforms/qoder.json +25 -25
  43. package/assets/templates/platforms/roocode.json +25 -25
  44. package/assets/templates/platforms/trae.json +25 -25
  45. package/assets/templates/platforms/windsurf.json +25 -25
  46. package/package.json +65 -65
@@ -1,364 +1,370 @@
1
- #!/usr/bin/env python3
2
- """
3
- Taiwan Logistics Skill - 物流服務商推薦系統
4
-
5
- 基於 BM25 算法的智能推薦引擎
6
- 根據使用者需求自動推薦最適合的物流服務商
7
-
8
- 使用方式:
9
- python recommend.py "超商取貨 冷凍配送 高交易量"
10
- python recommend.py "7-11 B2C 穩定" --format json
11
- python recommend.py "生鮮電商 溫控" --format simple
12
-
13
- 作者: Taiwan E-Commerce Toolkit
14
- 版本: 1.0.0
15
- """
16
-
17
- import sys
18
- import csv
19
- import json
20
- import math
21
- import argparse
22
- from pathlib import Path
23
- from typing import List, Dict, Tuple
24
- from dataclasses import dataclass
25
-
26
-
27
- @dataclass
28
- class LogisticsProvider:
29
- """物流服務商資料"""
30
- provider: str
31
- display_name: str
32
- auth_method: str
33
- encryption: str
34
- test_url: str
35
- prod_url: str
36
- content_type: str
37
- features: List[str]
38
- market_share: str
39
- api_style: str
40
- logistics_types: List[str]
41
-
42
-
43
- @dataclass
44
- class RecommendResult:
45
- """推薦結果"""
46
- provider: str
47
- display_name: str
48
- score: float
49
- match_reasons: List[str]
50
- features: List[str]
51
- warnings: List[str]
52
-
53
-
54
- class BM25:
55
- """BM25 搜尋算法"""
56
-
57
- def __init__(self, k1: float = 1.5, b: float = 0.75):
58
- self.k1 = k1
59
- self.b = b
60
-
61
- def score(self, query_terms: List[str], doc_terms: List[str],
62
- avg_doc_len: float, doc_len: int, total_docs: int,
63
- doc_freq: Dict[str, int]) -> float:
64
- """計算 BM25 分數"""
65
- score = 0.0
66
-
67
- for term in query_terms:
68
- if term not in doc_terms:
69
- continue
70
-
71
- tf = doc_terms.count(term)
72
- df = doc_freq.get(term, 0)
73
-
74
- if df == 0:
75
- continue
76
-
77
- idf = math.log((total_docs - df + 0.5) / (df + 0.5) + 1)
78
- score += idf * (tf * (self.k1 + 1)) / \
79
- (tf + self.k1 * (1 - self.b + self.b * (doc_len / avg_doc_len)))
80
-
81
- return score
82
-
83
-
84
- class LogisticsRecommender:
85
- """物流服務商推薦引擎"""
86
-
87
- # 關鍵字權重
88
- KEYWORD_WEIGHTS = {
89
- # ECPay 綠界
90
- 'ecpay': 3.0, '綠界': 3.0, '穩定': 2.5, '市佔': 2.0, '高交易量': 2.0,
91
- '電商': 1.8, '文檔': 2.0, 'sdk': 2.0, '完整': 1.5, '超商': 1.5,
92
- '7-11': 1.5, '全家': 1.5, '萊爾富': 1.5, 'ok': 1.5, '黑貓': 1.5,
93
- '宅配': 1.5, 'c2c': 1.5, 'b2c': 1.5, '取貨付款': 1.5,
94
-
95
- # NewebPay 藍新
96
- 'newebpay': 3.0, '藍新': 3.0, '多元': 2.0, '會員': 1.8, '整合': 2.0,
97
- '記憶': 1.5, '便利': 1.5, '簡單': 1.8, '快速': 1.8, '小型': 1.5,
98
-
99
- # PAYUNi 統一
100
- 'payuni': 3.0, '統一': 3.0, '溫控': 3.5, '冷凍': 3.0, '冷藏': 3.0,
101
- '生鮮': 3.0, 'api': 2.0, 'json': 2.0, 'restful': 2.0, '新創': 1.8,
102
- '現代': 1.5, '設計': 1.5,
103
-
104
- # 通用關鍵字
105
- '物流': 1.0, '配送': 1.0, '取貨': 1.0, '超商': 1.2, '宅配': 1.2,
106
- }
107
-
108
- # 反模式 (不建議使用的場景)
109
- ANTI_PATTERNS = {
110
- 'ecpay': ['無技術資源', '極簡需求', 'api優先', '現代化'],
111
- 'newebpay': ['簡單api', '單一支付', '極簡', '最小化'],
112
- 'payuni': ['大型專案', '完整文檔', '傳統', 'php']
113
- }
114
-
115
- def __init__(self, data_dir: Path = None):
116
- """初始化推薦引擎"""
117
- if data_dir is None:
118
- data_dir = Path(__file__).parent.parent / 'data'
119
-
120
- self.data_dir = data_dir
121
- self.providers: List[LogisticsProvider] = []
122
- self.bm25 = BM25(k1=1.5, b=0.75)
123
- self.load_data()
124
-
125
- def load_data(self):
126
- """載入服務商資料"""
127
- providers_file = self.data_dir / 'providers.csv'
128
-
129
- if not providers_file.exists():
130
- raise FileNotFoundError(f"找不到資料檔案: {providers_file}")
131
-
132
- with open(providers_file, 'r', encoding='utf-8') as f:
133
- reader = csv.DictReader(f)
134
- for row in reader:
135
- self.providers.append(
136
- LogisticsProvider(
137
- provider=row['provider'],
138
- display_name=row['display_name'],
139
- auth_method=row['auth_method'],
140
- encryption=row['encryption'],
141
- test_url=row['test_url'],
142
- prod_url=row['prod_url'],
143
- content_type=row['content_type'],
144
- features=row['features'].split(' | '),
145
- market_share=row['market_share'],
146
- api_style=row['api_style'],
147
- logistics_types=row['logistics_types'].split(' | ')
148
- )
149
- )
150
-
151
- def tokenize(self, text: str) -> List[str]:
152
- """分詞"""
153
- text = text.lower()
154
- return text.split()
155
-
156
- def build_document(self, provider: LogisticsProvider) -> str:
157
- """建立服務商文件 (用於搜尋)"""
158
- parts = [
159
- provider.provider,
160
- provider.display_name,
161
- provider.auth_method,
162
- provider.api_style,
163
- provider.market_share,
164
- ' '.join(provider.features),
165
- ' '.join(provider.logistics_types)
166
- ]
167
- return ' '.join(parts)
168
-
169
- def calculate_weighted_score(self, query: str, provider: LogisticsProvider) -> Tuple[float, List[str]]:
170
- """計算加權分數"""
171
- query_terms = self.tokenize(query)
172
- doc_text = self.build_document(provider)
173
- doc_terms = self.tokenize(doc_text)
174
-
175
- # 計算 BM25 基礎分數
176
- total_docs = len(self.providers)
177
- avg_doc_len = sum(len(self.tokenize(self.build_document(p))) for p in self.providers) / total_docs
178
- doc_len = len(doc_terms)
179
-
180
- doc_freq = {}
181
- for term in set(query_terms):
182
- doc_freq[term] = sum(1 for p in self.providers if term in self.tokenize(self.build_document(p)))
183
-
184
- base_score = self.bm25.score(query_terms, doc_terms, avg_doc_len, doc_len, total_docs, doc_freq)
185
-
186
- # 應用關鍵字權重
187
- weighted_score = base_score
188
- match_reasons = []
189
-
190
- for term in query_terms:
191
- if term in doc_terms:
192
- weight = self.KEYWORD_WEIGHTS.get(term, 1.0)
193
- if weight > 1.0:
194
- weighted_score += base_score * (weight - 1.0) * 0.1
195
- match_reasons.append(f"關鍵字匹配: {term} (權重 {weight:.1f})")
196
-
197
- return weighted_score, match_reasons
198
-
199
- def check_anti_patterns(self, query: str, provider_key: str) -> List[str]:
200
- """檢查反模式"""
201
- warnings = []
202
- query_lower = query.lower()
203
-
204
- if provider_key in self.ANTI_PATTERNS:
205
- for pattern in self.ANTI_PATTERNS[provider_key]:
206
- if pattern in query_lower:
207
- warnings.append(f"注意: {provider_key.upper()} 可能不適合「{pattern}」場景")
208
-
209
- return warnings
210
-
211
- def recommend(self, query: str, top_k: int = 3) -> List[RecommendResult]:
212
- """
213
- 推薦物流服務商
214
-
215
- Args:
216
- query: 需求描述
217
- top_k: 回傳前 K 個推薦結果
218
-
219
- Returns:
220
- 推薦結果清單
221
- """
222
- results = []
223
-
224
- for provider in self.providers:
225
- score, match_reasons = self.calculate_weighted_score(query, provider)
226
- warnings = self.check_anti_patterns(query, provider.provider.lower())
227
-
228
- results.append(
229
- RecommendResult(
230
- provider=provider.provider,
231
- display_name=provider.display_name,
232
- score=score,
233
- match_reasons=match_reasons,
234
- features=provider.features,
235
- warnings=warnings
236
- )
237
- )
238
-
239
- # 依分數排序
240
- results.sort(key=lambda x: x.score, reverse=True)
241
-
242
- return results[:top_k]
243
-
244
- def format_output(self, results: List[RecommendResult], format_type: str = 'detailed') -> str:
245
- """
246
- 格式化輸出
247
-
248
- Args:
249
- results: 推薦結果
250
- format_type: 輸出格式 ('detailed', 'simple', 'json')
251
-
252
- Returns:
253
- 格式化的推薦結果
254
- """
255
- if format_type == 'json':
256
- return json.dumps(
257
- [
258
- {
259
- 'provider': r.provider,
260
- 'display_name': r.display_name,
261
- 'score': round(r.score, 2),
262
- 'match_reasons': r.match_reasons,
263
- 'features': r.features,
264
- 'warnings': r.warnings
265
- }
266
- for r in results
267
- ],
268
- ensure_ascii=False,
269
- indent=2
270
- )
271
-
272
- elif format_type == 'simple':
273
- lines = []
274
- for i, result in enumerate(results, 1):
275
- lines.append(f"{i}. {result.display_name} ({result.provider.upper()}) - 分數: {result.score:.2f}")
276
- return '\n'.join(lines)
277
-
278
- else: # detailed
279
- lines = []
280
- lines.append("=" * 70)
281
- lines.append("物流服務商推薦結果")
282
- lines.append("=" * 70)
283
- lines.append("")
284
-
285
- for i, result in enumerate(results, 1):
286
- lines.append(f"推薦 #{i}: {result.display_name} ({result.provider.upper()})")
287
- lines.append(f" 匹配分數: {result.score:.2f}")
288
- lines.append("")
289
- lines.append(" 特色功能:")
290
- for feature in result.features:
291
- lines.append(f" • {feature}")
292
- lines.append("")
293
-
294
- if result.match_reasons:
295
- lines.append(" 匹配原因:")
296
- for reason in result.match_reasons[:5]: # 只顯示前 5 個
297
- lines.append(f" • {reason}")
298
- lines.append("")
299
-
300
- if result.warnings:
301
- lines.append(" ⚠️ 注意事項:")
302
- for warning in result.warnings:
303
- lines.append(f" • {warning}")
304
- lines.append("")
305
-
306
- lines.append("-" * 70)
307
- lines.append("")
308
-
309
- return '\n'.join(lines)
310
-
311
-
312
- # ============================================================================
313
- # CLI 介面
314
- # ============================================================================
315
-
316
- def main():
317
- parser = argparse.ArgumentParser(
318
- description='Taiwan Logistics Skill - 物流服務商推薦系統',
319
- formatter_class=argparse.RawDescriptionHelpFormatter,
320
- epilog="""
321
- 範例:
322
- python recommend.py "超商取貨 冷凍配送"
323
- python recommend.py "7-11 B2C 大量訂單" --format json
324
- python recommend.py "生鮮電商 溫控 穩定" --format simple
325
- python recommend.py "新創公司 API 設計" --top 2
326
-
327
- 關鍵字建議:
328
- ECPay: 穩定、市佔、高交易量、電商、文檔、SDK、超商、宅配
329
- NewebPay: 多元、會員、整合、簡單、快速、便利
330
- PAYUNi: 溫控、冷凍、冷藏、生鮮、API、JSON、RESTful、新創
331
- """
332
- )
333
-
334
- parser.add_argument('query', type=str, help='需求描述 (關鍵字以空格分隔)')
335
- parser.add_argument('--format', type=str, choices=['detailed', 'simple', 'json'],
336
- default='detailed', help='輸出格式 (預設: detailed)')
337
- parser.add_argument('--top', type=int, default=3, help='回傳前 K 個推薦 (預設: 3)')
338
-
339
- args = parser.parse_args()
340
-
341
- try:
342
- # 初始化推薦引擎
343
- recommender = LogisticsRecommender()
344
-
345
- # 執行推薦
346
- results = recommender.recommend(args.query, top_k=args.top)
347
-
348
- # 輸出結果
349
- output = recommender.format_output(results, format_type=args.format)
350
- print(output)
351
-
352
- return 0
353
-
354
- except FileNotFoundError as e:
355
- print(f"錯誤: {e}", file=sys.stderr)
356
- return 1
357
-
358
- except Exception as e:
359
- print(f"執行錯誤: {e}", file=sys.stderr)
360
- return 1
361
-
362
-
363
- if __name__ == '__main__':
364
- sys.exit(main())
1
+ #!/usr/bin/env python3
2
+ """
3
+ Taiwan Logistics Skill - 物流服務商推薦系統
4
+
5
+ 基於 BM25 算法的智能推薦引擎
6
+ 根據使用者需求自動推薦最適合的物流服務商
7
+
8
+ 使用方式:
9
+ python recommend.py "超商取貨 冷凍配送 高交易量"
10
+ python recommend.py "7-11 B2C 穩定" --format json
11
+ python recommend.py "生鮮電商 溫控" --format simple
12
+
13
+ 作者: Taiwan E-Commerce Toolkit
14
+ 版本: 1.0.0
15
+ """
16
+
17
+ import sys
18
+ import csv
19
+ import json
20
+ import math
21
+ import re
22
+ import argparse
23
+ from pathlib import Path
24
+ from typing import List, Dict, Tuple
25
+ from dataclasses import dataclass
26
+
27
+ sys.path.insert(0, str(Path(__file__).parent))
28
+ from core import tokenize as core_tokenize
29
+
30
+
31
+ @dataclass
32
+ class LogisticsProvider:
33
+ """物流服務商資料"""
34
+ provider: str
35
+ display_name: str
36
+ auth_method: str
37
+ encryption: str
38
+ test_url: str
39
+ prod_url: str
40
+ content_type: str
41
+ features: List[str]
42
+ market_share: str
43
+ api_style: str
44
+ logistics_types: List[str]
45
+
46
+
47
+ @dataclass
48
+ class RecommendResult:
49
+ """推薦結果"""
50
+ provider: str
51
+ display_name: str
52
+ score: float
53
+ match_reasons: List[str]
54
+ features: List[str]
55
+ warnings: List[str]
56
+
57
+
58
+ class BM25:
59
+ """BM25 搜尋算法"""
60
+
61
+ def __init__(self, k1: float = 1.5, b: float = 0.75):
62
+ self.k1 = k1
63
+ self.b = b
64
+
65
+ def score(self, query_terms: List[str], doc_terms: List[str],
66
+ avg_doc_len: float, doc_len: int, total_docs: int,
67
+ doc_freq: Dict[str, int]) -> float:
68
+ """計算 BM25 分數"""
69
+ score = 0.0
70
+
71
+ for term in query_terms:
72
+ if term not in doc_terms:
73
+ continue
74
+
75
+ tf = doc_terms.count(term)
76
+ df = doc_freq.get(term, 0)
77
+
78
+ if df == 0:
79
+ continue
80
+
81
+ idf = math.log((total_docs - df + 0.5) / (df + 0.5) + 1)
82
+ score += idf * (tf * (self.k1 + 1)) / \
83
+ (tf + self.k1 * (1 - self.b + self.b * (doc_len / avg_doc_len)))
84
+
85
+ return score
86
+
87
+
88
+ class LogisticsRecommender:
89
+ """物流服務商推薦引擎"""
90
+
91
+ # 關鍵字權重
92
+ KEYWORD_WEIGHTS = {
93
+ # ECPay 綠界
94
+ 'ecpay': 3.0, '綠界': 3.0, '穩定': 2.5, '市佔': 2.0, '高交易量': 2.0,
95
+ '電商': 1.8, '文檔': 2.0, 'sdk': 2.0, '完整': 1.5, '超商': 1.5,
96
+ '7-11': 1.5, '全家': 1.5, '萊爾富': 1.5, 'ok': 1.5, '黑貓': 1.5,
97
+ '宅配': 1.5, 'c2c': 1.5, 'b2c': 1.5, '取貨付款': 1.5,
98
+
99
+ # NewebPay 藍新
100
+ 'newebpay': 3.0, '藍新': 3.0, '多元': 2.0, '會員': 1.8, '整合': 2.0,
101
+ '記憶': 1.5, '便利': 1.5, '簡單': 1.8, '快速': 1.8, '小型': 1.5,
102
+
103
+ # PAYUNi 統一
104
+ 'payuni': 3.0, '統一': 3.0, '溫控': 3.5, '冷凍': 3.0, '冷藏': 3.0,
105
+ '生鮮': 3.0, 'api': 2.0, 'json': 2.0, 'restful': 2.0, '新創': 1.8,
106
+ '現代': 1.5, '設計': 1.5,
107
+
108
+ # 通用關鍵字
109
+ '物流': 1.0, '配送': 1.0, '取貨': 1.0, '超商': 1.2, '宅配': 1.2,
110
+ }
111
+
112
+ # 反模式 (不建議使用的場景)
113
+ ANTI_PATTERNS = {
114
+ 'ecpay': ['無技術資源', '極簡需求', 'api優先', '現代化'],
115
+ 'newebpay': ['簡單api', '單一支付', '極簡', '最小化'],
116
+ 'payuni': ['大型專案', '完整文檔', '傳統', 'php']
117
+ }
118
+
119
+ def __init__(self, data_dir: Path = None):
120
+ """初始化推薦引擎"""
121
+ if data_dir is None:
122
+ data_dir = Path(__file__).parent.parent / 'data'
123
+
124
+ self.data_dir = data_dir
125
+ self.providers: List[LogisticsProvider] = []
126
+ self.bm25 = BM25(k1=1.5, b=0.75)
127
+ self.load_data()
128
+
129
+ def load_data(self):
130
+ """載入服務商資料"""
131
+ providers_file = self.data_dir / 'providers.csv'
132
+
133
+ if not providers_file.exists():
134
+ raise FileNotFoundError(f"找不到資料檔案: {providers_file}")
135
+
136
+ with open(providers_file, 'r', encoding='utf-8') as f:
137
+ reader = csv.DictReader(f)
138
+ for row in reader:
139
+ # providers.csv 的實際欄位為 name_zh/type/coverage/doc_access…
140
+ # 這裡做寬鬆對應,缺欄位時以合理預設值代替,避免 KeyError
141
+ features = [s for s in re.split(r'\s*[|,]\s*', row.get('features', '')) if s]
142
+ self.providers.append(
143
+ LogisticsProvider(
144
+ provider=row['provider'],
145
+ display_name=row.get('display_name') or row.get('name_zh') or row['provider'],
146
+ auth_method=row.get('auth_method', ''),
147
+ encryption=row.get('encryption', ''),
148
+ test_url=row.get('test_url', ''),
149
+ prod_url=row.get('prod_url', ''),
150
+ content_type=row.get('content_type', ''),
151
+ features=features,
152
+ market_share=row.get('market_share') or row.get('coverage', ''),
153
+ api_style=row.get('api_style') or row.get('type', ''),
154
+ logistics_types=features,
155
+ )
156
+ )
157
+
158
+ def tokenize(self, text: str) -> List[str]:
159
+ """分詞(沿用 core.py 的中英混合分詞,避免中文查詢整段當成單一 token)"""
160
+ return core_tokenize(text)
161
+
162
+ def build_document(self, provider: LogisticsProvider) -> str:
163
+ """建立服務商文件 (用於搜尋)"""
164
+ parts = [
165
+ provider.provider,
166
+ provider.display_name,
167
+ provider.auth_method,
168
+ provider.api_style,
169
+ provider.market_share,
170
+ ' '.join(provider.features),
171
+ ' '.join(provider.logistics_types)
172
+ ]
173
+ return ' '.join(parts)
174
+
175
+ def calculate_weighted_score(self, query: str, provider: LogisticsProvider) -> Tuple[float, List[str]]:
176
+ """計算加權分數"""
177
+ query_terms = self.tokenize(query)
178
+ doc_text = self.build_document(provider)
179
+ doc_terms = self.tokenize(doc_text)
180
+
181
+ # 計算 BM25 基礎分數
182
+ total_docs = len(self.providers)
183
+ avg_doc_len = sum(len(self.tokenize(self.build_document(p))) for p in self.providers) / total_docs
184
+ doc_len = len(doc_terms)
185
+
186
+ doc_freq = {}
187
+ for term in set(query_terms):
188
+ doc_freq[term] = sum(1 for p in self.providers if term in self.tokenize(self.build_document(p)))
189
+
190
+ base_score = self.bm25.score(query_terms, doc_terms, avg_doc_len, doc_len, total_docs, doc_freq)
191
+
192
+ # 應用關鍵字權重
193
+ weighted_score = base_score
194
+ match_reasons = []
195
+
196
+ for term in query_terms:
197
+ if term in doc_terms:
198
+ weight = self.KEYWORD_WEIGHTS.get(term, 1.0)
199
+ if weight > 1.0:
200
+ weighted_score += base_score * (weight - 1.0) * 0.1
201
+ match_reasons.append(f"關鍵字匹配: {term} (權重 {weight:.1f})")
202
+
203
+ return weighted_score, match_reasons
204
+
205
+ def check_anti_patterns(self, query: str, provider_key: str) -> List[str]:
206
+ """檢查反模式"""
207
+ warnings = []
208
+ query_lower = query.lower()
209
+
210
+ if provider_key in self.ANTI_PATTERNS:
211
+ for pattern in self.ANTI_PATTERNS[provider_key]:
212
+ if pattern in query_lower:
213
+ warnings.append(f"注意: {provider_key.upper()} 可能不適合「{pattern}」場景")
214
+
215
+ return warnings
216
+
217
+ def recommend(self, query: str, top_k: int = 3) -> List[RecommendResult]:
218
+ """
219
+ 推薦物流服務商
220
+
221
+ Args:
222
+ query: 需求描述
223
+ top_k: 回傳前 K 個推薦結果
224
+
225
+ Returns:
226
+ 推薦結果清單
227
+ """
228
+ results = []
229
+
230
+ for provider in self.providers:
231
+ score, match_reasons = self.calculate_weighted_score(query, provider)
232
+ warnings = self.check_anti_patterns(query, provider.provider.lower())
233
+
234
+ results.append(
235
+ RecommendResult(
236
+ provider=provider.provider,
237
+ display_name=provider.display_name,
238
+ score=score,
239
+ match_reasons=match_reasons,
240
+ features=provider.features,
241
+ warnings=warnings
242
+ )
243
+ )
244
+
245
+ # 依分數排序
246
+ results.sort(key=lambda x: x.score, reverse=True)
247
+
248
+ return results[:top_k]
249
+
250
+ def format_output(self, results: List[RecommendResult], format_type: str = 'detailed') -> str:
251
+ """
252
+ 格式化輸出
253
+
254
+ Args:
255
+ results: 推薦結果
256
+ format_type: 輸出格式 ('detailed', 'simple', 'json')
257
+
258
+ Returns:
259
+ 格式化的推薦結果
260
+ """
261
+ if format_type == 'json':
262
+ return json.dumps(
263
+ [
264
+ {
265
+ 'provider': r.provider,
266
+ 'display_name': r.display_name,
267
+ 'score': round(r.score, 2),
268
+ 'match_reasons': r.match_reasons,
269
+ 'features': r.features,
270
+ 'warnings': r.warnings
271
+ }
272
+ for r in results
273
+ ],
274
+ ensure_ascii=False,
275
+ indent=2
276
+ )
277
+
278
+ elif format_type == 'simple':
279
+ lines = []
280
+ for i, result in enumerate(results, 1):
281
+ lines.append(f"{i}. {result.display_name} ({result.provider.upper()}) - 分數: {result.score:.2f}")
282
+ return '\n'.join(lines)
283
+
284
+ else: # detailed
285
+ lines = []
286
+ lines.append("=" * 70)
287
+ lines.append("物流服務商推薦結果")
288
+ lines.append("=" * 70)
289
+ lines.append("")
290
+
291
+ for i, result in enumerate(results, 1):
292
+ lines.append(f"推薦 #{i}: {result.display_name} ({result.provider.upper()})")
293
+ lines.append(f" 匹配分數: {result.score:.2f}")
294
+ lines.append("")
295
+ lines.append(" 特色功能:")
296
+ for feature in result.features:
297
+ lines.append(f" • {feature}")
298
+ lines.append("")
299
+
300
+ if result.match_reasons:
301
+ lines.append(" 匹配原因:")
302
+ for reason in result.match_reasons[:5]: # 只顯示前 5 個
303
+ lines.append(f" • {reason}")
304
+ lines.append("")
305
+
306
+ if result.warnings:
307
+ lines.append(" ⚠️ 注意事項:")
308
+ for warning in result.warnings:
309
+ lines.append(f" • {warning}")
310
+ lines.append("")
311
+
312
+ lines.append("-" * 70)
313
+ lines.append("")
314
+
315
+ return '\n'.join(lines)
316
+
317
+
318
+ # ============================================================================
319
+ # CLI 介面
320
+ # ============================================================================
321
+
322
+ def main():
323
+ parser = argparse.ArgumentParser(
324
+ description='Taiwan Logistics Skill - 物流服務商推薦系統',
325
+ formatter_class=argparse.RawDescriptionHelpFormatter,
326
+ epilog="""
327
+ 範例:
328
+ python recommend.py "超商取貨 冷凍配送"
329
+ python recommend.py "7-11 B2C 大量訂單" --format json
330
+ python recommend.py "生鮮電商 溫控 穩定" --format simple
331
+ python recommend.py "新創公司 API 設計" --top 2
332
+
333
+ 關鍵字建議:
334
+ ECPay: 穩定、市佔、高交易量、電商、文檔、SDK、超商、宅配
335
+ NewebPay: 多元、會員、整合、簡單、快速、便利
336
+ PAYUNi: 溫控、冷凍、冷藏、生鮮、API、JSON、RESTful、新創
337
+ """
338
+ )
339
+
340
+ parser.add_argument('query', type=str, help='需求描述 (關鍵字以空格分隔)')
341
+ parser.add_argument('--format', type=str, choices=['detailed', 'simple', 'json'],
342
+ default='detailed', help='輸出格式 (預設: detailed)')
343
+ parser.add_argument('--top', type=int, default=3, help='回傳前 K 個推薦 (預設: 3)')
344
+
345
+ args = parser.parse_args()
346
+
347
+ try:
348
+ # 初始化推薦引擎
349
+ recommender = LogisticsRecommender()
350
+
351
+ # 執行推薦
352
+ results = recommender.recommend(args.query, top_k=args.top)
353
+
354
+ # 輸出結果
355
+ output = recommender.format_output(results, format_type=args.format)
356
+ print(output)
357
+
358
+ return 0
359
+
360
+ except FileNotFoundError as e:
361
+ print(f"錯誤: {e}", file=sys.stderr)
362
+ return 1
363
+
364
+ except Exception as e:
365
+ print(f"執行錯誤: {e}", file=sys.stderr)
366
+ return 1
367
+
368
+
369
+ if __name__ == '__main__':
370
+ sys.exit(main())