diff --git a/README.en.md b/README.en.md index dbbaf9b..3918068 100644 --- a/README.en.md +++ b/README.en.md @@ -1,68 +1,140 @@ +# PChome 24h - Command Line Interface +

- pchome-cli + pchome-cli

-# pchome-cli - -`pchome` is a Go CLI for searching PChome 24h products, viewing product details, comparing products, and getting recommendations. +Fast, script-friendly CLI for searching PChome 24h products, viewing product details, comparing products, and getting recommendations. JSON-first output, human-friendly tables, and a normalized schema built in. -The CLI is optimized for two modes: +## Features -- Human-friendly text output for browsing and decision-making. -- Agent-friendly `json` and `ndjson` output with a normalized schema (`v1`). - -The default human-facing language is Traditional Chinese (Taiwan). To switch the app to English, set `i18n.language = "en"` in `~/.pchome/config.toml`. +- **Search** - search products with filters for brand, price range, rating, stock status, 24h arrival, sorting, and custom column output +- **View** - display detailed product information including specs, images, and warnings +- **Recommend** - get product recommendations based on a reference product, with optional reasoning +- **Compare** - compare multiple products side-by-side with customizable columns +- **Suggest** - get autocomplete suggestions for search queries +- **Multi-format output** - human-friendly text tables, JSON, and NDJSON for scripting and agent integrations +- **Normalized schema** - stable English schema keys (`v1`) regardless of locale, so agent integrations do not break +- **i18n** - Traditional Chinese (default) and English interface +- **Flexible product input** - accepts raw IDs (`DRAA5K-A900JOK9O`), suffixed IDs (`DRAA5K-A900JOK9O-000`), or full PChome URLs +- **Configurable** - per-command defaults, column ordering, and output preferences via `~/.pchome/config.toml` ## Installation +### Homebrew + ```bash -go install github.com/oliy/pchome-cli/cmd/pchome@latest +brew install oliyy/tap/pchome-cli +``` + +### Scoop (Windows) + +```powershell +scoop bucket add oliyy https://github.com/oliyy/scoop-bucket.git +scoop install oliyy/pchome-cli ``` -Prebuilt binaries are also published on [GitHub Releases](https://github.com/oliy/pchome-cli/releases). Download the archive for your platform, extract it, and place `pchome` in your `PATH`. +### Prebuilt Binaries -Homebrew (tap): +Download the archive for your platform from [GitHub Releases](https://github.com/oliy/pchome-cli/releases), extract it, and place `pchome` in your `PATH`. + +### Build from Source ```bash -brew tap oliyy/tap -brew install pchome-cli +git clone https://github.com/oliy/pchome-cli.git +cd pchome-cli +make build ``` -Scoop: +Run: -```powershell -scoop bucket add oliyy https://github.com/oliyy/scoop-bucket.git -scoop install oliyy/pchome-cli +```bash +./bin/pchome --help ``` -## Quickstart +Or install globally: ```bash -# Search -go run ./cmd/pchome search "掃地機器人" --min-price 5000 --max-price 15000 --in-stock +go install github.com/oliy/pchome-cli/cmd/pchome@latest +``` + +Help: + +- `pchome --help` shows top-level command groups. +- You can get help for a specific command with `pchome --help`. + +## Quick Start + +```bash +# Search for products +pchome search "掃地機器人" --min-price 5000 --max-price 15000 --in-stock # View a product -go run ./cmd/pchome view DRAA5K-A900JOK9O +pchome view DRAA5K-A900JOK9O -# Recommendations -go run ./cmd/pchome recommend DMBL53-A900JDNJS --top 8 --why +# Get recommendations +pchome recommend DMBL53-A900JDNJS --top 8 # Compare products -go run ./cmd/pchome compare DRAA5K-A900JOK9O DMBL53-A900JDNJS +pchome compare DRAA5K-A900JOK9O DMBL53-A900JDNJS -# Suggestions -go run ./cmd/pchome suggest "掃地機" +# Autocomplete suggestions +pchome suggest "掃地機" ``` -## Command Model +## Commands -The command surface is intentionally task-oriented: +### Search -- `search QUERY` -- `view PRODUCT` -- `recommend PRODUCT` -- `compare PRODUCT [PRODUCT...]` -- `suggest QUERY` +```bash +# Basic search +pchome search "掃地機器人" + +# Price range and stock filter +pchome search "掃地機器人" --min-price 5000 --max-price 15000 --in-stock + +# Brand and rating filter +pchome search "掃地機器人" --brand Roborock --min-rating 4.8 + +# 24h arrival only, sorted by price +pchome search "掃地機器人" --arrival-24h --sort price-asc + +# Custom text columns +pchome search "掃地機器人" \ + --columns "#,name,price,rating,reviews,24h,brand,qty,url" +``` + +### View + +```bash +pchome view DRAA5K-A900JOK9O +pchome view DRAA5K-A900JOK9O --format json +pchome view https://24h.pchome.com.tw/prod/DRAA5K-A900JOK9O +``` + +### Recommend + +```bash +# Basic recommendations +pchome recommend DMBL53-A900JDNJS --top 8 + +# Explain why each item was recommended +pchome recommend DMAB3X-A900EVNNM --top 10 --why +``` + +### Compare + +```bash +pchome compare DRAA5K-A900JOK9O DMBL53-A900JDNJS +``` + +### Suggest + +```bash +pchome suggest "掃地機" +``` + +### Product Input `PRODUCT` can be: @@ -70,21 +142,43 @@ The command surface is intentionally task-oriented: - A suffixed product ID like `DRAA5K-A900JOK9O-000` - A full PChome product URL like `https://24h.pchome.com.tw/prod/DRAA5K-A900JOK9O` -## Repository Layout +## Output Formats + +### Text + +Human-readable output with compact tables (default): + +```bash +pchome search "掃地機器人" --limit 3 +``` + +### JSON -The source tree now follows a more typical open-source Go CLI structure: +Machine-readable output for scripting and automation: -- `cmd/`: Cobra command layer and text rendering -- `cmd/pchome/`: binary entrypoint -- `pkg/catalog/`: normalized product models and aggregate service -- `pkg/config/`: config loading and validation -- `pkg/i18n/`: language handling and translation catalog -- `pkg/output/`: shared table rendering -- `pkg/pchome/`: upstream PChome API clients -- `cmd/testdata/`: golden fixtures for CLI help and text output -- `pkg/*/testdata/`: package-level test fixtures +```bash +pchome search "掃地機器人" --limit 3 --format json +pchome view DRAA5K-A900JOK9O --format json +``` + +### NDJSON -## Config +Line-delimited items for streaming and agent integrations: + +```bash +pchome search "掃地機器人" --limit 5 --format ndjson +pchome recommend DMBL53-A900JDNJS --top 5 --format ndjson +``` + +`ndjson` is supported on `search`, `recommend`, `compare`, and `suggest`. + +Data goes to stdout, errors and progress to stderr for clean piping: + +```bash +pchome search "掃地機器人" --format json | jq '.products[] | select(.price < 10000)' +``` + +## Configuration On startup, `pchome` ensures a config file exists at: @@ -94,11 +188,11 @@ On startup, `pchome` ensures a config file exists at: If the file is missing, it is created automatically with the full default configuration. -Config precedence is: +Config precedence: -- CLI flags -- `~/.pchome/config.toml` -- Built-in defaults +1. CLI flags +2. `~/.pchome/config.toml` +3. Built-in defaults Example: @@ -142,99 +236,46 @@ token = "" Notes: -- `columns = []` means “use the built-in default column order for that command”. +- `columns = []` means "use the built-in default column order for that command". - If you set `columns`, that list becomes the default column order for the command. - `i18n.language` currently supports `zh-TW` and `en`. - The config loader rejects unknown keys so typos do not silently get ignored. -## Output Modes +## Examples -### Text - -Human-oriented output with compact tables for list commands and a structured detail view for `view`. - -### JSON - -Normalized machine-readable output: +### Search and filter products ```bash -go run ./cmd/pchome search "掃地機器人" --limit 3 --format json -go run ./cmd/pchome view DRAA5K-A900JOK9O --format json -``` +# Search with price range +pchome search "掃地機器人" --min-price 5000 --max-price 15000 --in-stock -### NDJSON - -Line-delimited items for list-oriented commands: - -```bash -go run ./cmd/pchome search "掃地機器人" --limit 5 --format ndjson -go run ./cmd/pchome recommend DMBL53-A900JDNJS --top 5 --format ndjson -``` - -`ndjson` is supported on `search`, `recommend`, `compare`, and `suggest`. +# Filter by brand and rating +pchome search "掃地機器人" --brand Roborock --min-rating 4.8 -## Search Examples - -```bash -# Brand and rating filter -go run ./cmd/pchome search "掃地機器人" --brand Roborock --min-rating 4.8 - -# 24h only, sorted by price -go run ./cmd/pchome search "掃地機器人" --arrival-24h --sort price-asc - -# Custom text columns -go run ./cmd/pchome search "掃地機器人" \ - --columns "#,name,price,rating,reviews,24h,brand,qty,url" +# 24h delivery only, sorted by price +pchome search "掃地機器人" --arrival-24h --sort price-asc ``` -## Recommendation Example +### Get recommendations with reasoning ```bash -# Explain why each item was recommended -go run ./cmd/pchome recommend DMAB3X-A900EVNNM --top 10 --why +pchome recommend DMAB3X-A900EVNNM --top 10 --why ``` -## Notes - -- Recommendation token precedence is `hermes.token` -> `PCHOME_HERMES_TOKEN` -> bundled fallback token. -- Machine-readable output keeps stable English schema keys regardless of locale, so agent integrations do not break. -- The current schema version is `--schema-version v1`. -- Run `go test ./...` to execute the current unit tests. - -## Build And Release - -Recommended maintainer workflow: +### Pipe JSON output to jq ```bash -# Fast local build for the current platform -make build - -# Unit tests + GoReleaser config validation -make verify - -# Simulate a full release locally into ./dist -make release-snapshot +# Extract product names under a price threshold +pchome search "掃地機器人" --format json | jq '.products[] | select(.price < 10000) | .name' ``` -On first run, `make verify` and `make release-snapshot` automatically download and cache the pinned GoReleaser version. - -For an actual release: +### Stream results with NDJSON ```bash -git tag -a v0.1.0 -m "v0.1.0" -git push origin v0.1.0 +pchome search "掃地機器人" --limit 20 --format ndjson | while read -r line; do + echo "$line" | jq -r '.name' +done ``` -After a `v*` tag is pushed, GitHub Actions runs the release workflow and GoReleaser publishes macOS, Linux, and Windows archives for `amd64` and `arm64`, plus `checksums.txt`, to GitHub Releases. - -Homebrew / Scoop also require a small amount of one-time setup: - -- Create an `oliyy/homebrew-tap` repository for `Formula/pchome-cli.rb` -- Create an `oliyy/scoop-bucket` repository for `pchome-cli.json` -- Add a `PACKAGE_REPOS_TOKEN` GitHub Actions secret to `pchome-cli` -- That token needs write access to both repositories - -Notes: +## -- The Homebrew path here is a personal tap, not `homebrew/core` -- GoReleaser updates the tap and bucket on normal release tags; prerelease tags are skipped automatically diff --git a/README.md b/README.md index ca173c6..0e05f01 100644 --- a/README.md +++ b/README.md @@ -1,106 +1,198 @@ +# PChome 24h 命令列工具 (CLI) +

- pchome-cli + pchome-cli

-# pchome-cli +快速、易於整合腳本的 PChome 24h 購物命令列工具。支援商品搜尋、檢視商品詳情、比較多項商品以及取得商品推薦。內建 JSON 優先輸出、適合人類閱讀的表格格式,以及標準化的資料結構(Schema)。 -`pchome` 是一個以 Go 撰寫的 PChome 24h CLI,可用來搜尋商品、檢視商品詳情、比較商品,以及取得推薦結果。 +## 功能特色 -CLI 針對兩種使用方式設計: +- **搜尋 (Search)** - 支援透過關鍵字搜尋商品,並可依照品牌、價格區間、評價、庫存狀態、24h 到貨、排序方式進行篩選,同時支援自訂輸出欄位 +- **檢視 (View)** - 顯示詳細的商品資訊,包含規格、圖片以及相關警告提示 +- **推薦 (Recommend)** - 根據指定商品取得相關的推薦商品,並可選擇顯示推薦原因 +- **比較 (Compare)** - 並排比較多項商品,支援自訂顯示欄位 +- **建議 (Suggest)** - 提供搜尋關鍵字的自動補全與建議 +- **多種輸出格式** - 支援適合閱讀的文字表格格式、供腳本使用的 JSON 格式,以及適合串流或 AI 代理程式(Agent)整合的 NDJSON 格式 +- **標準化資料結構 (Schema)** - 無論語系為何,皆維持穩定的英文欄位鍵值(`v1`),確保 AI 代理程式或腳本整合不會因語系切換而失效 +- **多國語系 (i18n)** - 支援繁體中文(預設)與英文介面 +- **彈性的商品輸入格式** - 支援直接輸入商品編號(例如 `DRAA5K-A900JOK9O`)、帶有後綴的編號(例如 `DRAA5K-A900JOK9O-000`),或是完整的 PChome 商品網址 +- **高度可設定** - 可透過 `~/.pchome/config.toml` 設定各指令的預設值、欄位排序以及輸出偏好 -- 適合人類閱讀的文字輸出,方便瀏覽與決策。 -- 適合 AI agent 與程式整合的 `json` / `ndjson` 輸出,並提供穩定的標準化 schema(`v1`)。 +## 安裝方式 -預設的人類介面語言為繁體中文(台灣)。如果想改成英文,可在 `~/.pchome/config.toml` 設定 `i18n.language = "en"`。 +### Homebrew -英文版文件請參考 [README.en.md](./README.en.md)。 +```bash +brew install oliyy/tap/pchome-cli +``` -## 安裝 +### Scoop (Windows) -```bash -go install github.com/oliy/pchome-cli/cmd/pchome@latest +```powershell +scoop bucket add oliyy https://github.com/oliyy/scoop-bucket.git +scoop install oliyy/pchome-cli ``` -也可以從 [GitHub Releases](https://github.com/oliy/pchome-cli/releases) 下載對應平台的預編譯 binary,解壓後把 `pchome` 放進你的 `PATH`。 +### 預先編譯的二進位檔 (Prebuilt Binaries) + +您可以從 [GitHub Releases](https://github.com/oliy/pchome-cli/releases) 下載符合您作業系統的壓縮檔,解壓縮後將 `pchome` 放置於系統的 `PATH` 路徑下。 -Homebrew(tap): +### 從原始碼編譯 ```bash -brew tap oliyy/tap -brew install pchome-cli +git clone https://github.com/oliy/pchome-cli.git +cd pchome-cli +make build ``` -Scoop: +執行: -```powershell -scoop bucket add oliyy https://github.com/oliyy/scoop-bucket.git -scoop install oliyy/pchome-cli +```bash +./bin/pchome --help +``` + +或全域安裝: + +```bash +go install github.com/oliy/pchome-cli/cmd/pchome@latest ``` +取得協助: + +- `pchome --help` 會顯示最上層的指令群組。 +- 若要查看特定指令的說明,可使用 `pchome --help`。 + ## 快速開始 ```bash # 搜尋商品 -go run ./cmd/pchome search "掃地機器人" --min-price 5000 --max-price 15000 --in-stock +pchome search "掃地機器人" --min-price 5000 --max-price 15000 --in-stock + +# 檢視商品詳情 +pchome view DRAA5K-A900JOK9O + +# 取得商品推薦 +pchome recommend DMBL53-A900JDNJS --top 8 + +# 比較多項商品 +pchome compare DRAA5K-A900JOK9O DMBL53-A900JDNJS + +# 取得搜尋關鍵字建議 +pchome suggest "掃地機" +``` + +## 指令說明 + +### 搜尋 (Search) + +```bash +# 基本搜尋 +pchome search "掃地機器人" + +# 價格區間與庫存篩選 +pchome search "掃地機器人" --min-price 5000 --max-price 15000 --in-stock + +# 品牌與評價篩選 +pchome search "掃地機器人" --brand Roborock --min-rating 4.8 + +# 僅限 24h 到貨,並依價格由低至高排序 +pchome search "掃地機器人" --arrival-24h --sort price-asc + +# 自訂文字輸出欄位 +pchome search "掃地機器人" \ + --columns "#,name,price,rating,reviews,24h,brand,qty,url" +``` + +### 檢視 (View) + +```bash +pchome view DRAA5K-A900JOK9O +pchome view DRAA5K-A900JOK9O --format json +pchome view https://24h.pchome.com.tw/prod/DRAA5K-A900JOK9O +``` + +### 推薦 (Recommend) + +```bash +# 基本推薦 +pchome recommend DMBL53-A900JDNJS --top 8 + +# 顯示每項商品的推薦原因 +pchome recommend DMAB3X-A900EVNNM --top 10 --why +``` + +### 比較 (Compare) + +```bash +pchome compare DRAA5K-A900JOK9O DMBL53-A900JDNJS +``` + +### 建議 (Suggest) + +```bash +pchome suggest "掃地機" +``` -# 檢視商品 -go run ./cmd/pchome view DRAA5K-A900JOK9O +### 商品輸入格式 -# 查看推薦 -go run ./cmd/pchome recommend DMBL53-A900JDNJS --top 8 --why +`PRODUCT` 參數支援以下格式: -# 比較商品 -go run ./cmd/pchome compare DRAA5K-A900JOK9O DMBL53-A900JDNJS +- 原始商品編號:`DRAA5K-A900JOK9O` +- 帶後綴的商品編號:`DRAA5K-A900JOK9O-000` +- 完整的 PChome 商品網址:`https://24h.pchome.com.tw/prod/DRAA5K-A900JOK9O` -# 搜尋詞建議 -go run ./cmd/pchome suggest "掃地機" +## 輸出格式 + +### 文字 (Text) + +預設選項,以簡潔的表格呈現適合人類閱讀的格式: + +```bash +pchome search "掃地機器人" --limit 3 ``` -## 指令模型 +### JSON + +適合腳本與自動化流程的機器可讀格式: -CLI 採用以任務為中心的指令設計: +```bash +pchome search "掃地機器人" --limit 3 --format json +pchome view DRAA5K-A900JOK9O --format json +``` -- `search QUERY` -- `view PRODUCT` -- `recommend PRODUCT` -- `compare PRODUCT [PRODUCT...]` -- `suggest QUERY` +### NDJSON -`PRODUCT` 可以是: +每行一個 JSON 物件,非常適合串流處理與 AI 代理程式整合: -- 原始商品 ID,例如 `DRAA5K-A900JOK9O` -- 帶尾碼的商品 ID,例如 `DRAA5K-A900JOK9O-000` -- 完整的 PChome 商品網址,例如 `https://24h.pchome.com.tw/prod/DRAA5K-A900JOK9O` +```bash +pchome search "掃地機器人" --limit 5 --format ndjson +pchome recommend DMBL53-A900JDNJS --top 5 --format ndjson +``` -## 專案結構 +`ndjson` 格式支援 `search`、`recommend`、`compare` 與 `suggest` 指令。 -目前的原始碼佈局更接近常見的 Go 開源 CLI 專案: +資料輸出至 stdout,錯誤訊息與進度則輸出至 stderr,方便您進行管線(Piping)處理: -- `cmd/`: Cobra 指令層與文字輸出邏輯 -- `cmd/pchome/`: 真正的 binary entrypoint -- `pkg/catalog/`: 標準化商品模型與聚合 service -- `pkg/config/`: 設定檔讀取與驗證 -- `pkg/i18n/`: 介面語言與翻譯字典 -- `pkg/output/`: 共用表格輸出 -- `pkg/pchome/`: 與 PChome 上游 API 溝通的 client -- `cmd/testdata/`: CLI 幫助文字與輸出 golden fixtures -- `pkg/*/testdata/`: 套件層級的測試 fixtures +```bash +pchome search "掃地機器人" --format json | jq '.products[] | select(.price < 10000)' +``` -## 設定檔 +## 設定與組態 -啟動時,`pchome` 會先確認以下檔案是否存在: +在啟動時,`pchome` 會確認以下路徑的設定檔是否存在: ```bash ~/.pchome/config.toml ``` -如果不存在,CLI 會自動建立完整的預設設定檔。 +若檔案不存在,系統會自動建立並填入所有預設設定。 設定優先順序: -- CLI flags -- `~/.pchome/config.toml` -- 內建預設值 +1. CLI 指令選項(Flags) +2. `~/.pchome/config.toml` 設定檔 +3. 內建預設值 範例: @@ -142,101 +234,45 @@ limit = 10 token = "" ``` -補充: +備註: -- `columns = []` 代表「使用該指令的內建預設欄位順序」。 -- 若設定 `columns`,該欄位清單就會成為此指令的預設文字欄位順序。 +- `columns = []` 代表「使用該指令的內建預設欄位排序」。 +- 若您設定了 `columns`,該列表將會成為該指令的預設顯示欄位。 - `i18n.language` 目前支援 `zh-TW` 與 `en`。 -- 設定檔解析器會拒絕未知欄位,避免拼字錯誤被悄悄忽略。 - -## 輸出模式 - -### Text - -適合人類閱讀的輸出格式。清單型指令會顯示表格,`view` 則會顯示結構化的商品詳情。 - -### JSON +- 設定載入器會拒絕未知的鍵值,以防止拼寫錯誤被靜默忽略。 -標準化的機器可讀輸出: +## 實際應用範例 -```bash -go run ./cmd/pchome search "掃地機器人" --limit 3 --format json -go run ./cmd/pchome view DRAA5K-A900JOK9O --format json -``` - -### NDJSON - -適合串流或逐行處理的清單輸出: - -```bash -go run ./cmd/pchome search "掃地機器人" --limit 5 --format ndjson -go run ./cmd/pchome recommend DMBL53-A900JDNJS --top 5 --format ndjson -``` - -`ndjson` 支援 `search`、`recommend`、`compare`、`suggest`。 - -## 搜尋範例 +### 搜尋並篩選商品 ```bash -# 品牌與評價篩選 -go run ./cmd/pchome search "掃地機器人" --brand Roborock --min-rating 4.8 +# 帶有價格區間與庫存篩選的搜尋 +pchome search "掃地機器人" --min-price 5000 --max-price 15000 --in-stock -# 只看 24h,到貨依價格排序 -go run ./cmd/pchome search "掃地機器人" --arrival-24h --sort price-asc +# 依照品牌與最低評價進行篩選 +pchome search "掃地機器人" --brand Roborock --min-rating 4.8 -# 自訂文字欄位 -go run ./cmd/pchome search "掃地機器人" \ - --columns "#,name,price,rating,reviews,24h,brand,qty,url" +# 僅限 24h 到貨,並依價格由低至高排序 +pchome search "掃地機器人" --arrival-24h --sort price-asc ``` -## 推薦範例 +### 取得附帶原因的推薦商品 ```bash -# 顯示每個推薦項目的推薦原因 -go run ./cmd/pchome recommend DMAB3X-A900EVNNM --top 10 --why +pchome recommend DMAB3X-A900EVNNM --top 10 --why ``` -## 備註 - -- 推薦 API 的 token 讀取順序為 `hermes.token` -> `PCHOME_HERMES_TOKEN` -> 內建 fallback token。 -- 機器可讀輸出一律維持英文 schema key,避免 locale 變動破壞 agent 整合。 -- 目前 schema 版本為 `--schema-version v1`。 -- 執行 `go test ./...` 可跑目前的單元測試。 - -## 建置與釋出 - -維護者日常建議流程: +### 將 JSON 輸出管線連接至 jq ```bash -# 目前平台快速建置 -make build - -# 單元測試 + 檢查 GoReleaser 設定 -make verify - -# 模擬一次完整 release,產物會出現在 ./dist -make release-snapshot +# 擷取低於特定價格門檻的商品名稱 +pchome search "掃地機器人" --format json | jq '.products[] | select(.price < 10000) | .name' ``` -`make verify` / `make release-snapshot` 第一次執行時會自動下載並快取固定版本的 GoReleaser。 - -正式釋出流程: +### 使用 NDJSON 進行串流處理 ```bash -git tag -a v0.1.0 -m "v0.1.0" -git push origin v0.1.0 +pchome search "掃地機器人" --limit 20 --format ndjson | while read -r line; do + echo "$line" | jq -r '.name' +done ``` - -推上 `v*` tag 之後,GitHub Actions 會執行 release workflow,使用 GoReleaser 建立 macOS、Linux、Windows 的 `amd64` / `arm64` binary archive,並附上 `checksums.txt` 到 GitHub Releases。 - -Homebrew / Scoop 另外需要先準備: - -- 建立 `oliyy/homebrew-tap` repository,讓 GoReleaser 更新 `Formula/pchome-cli.rb` -- 建立 `oliyy/scoop-bucket` repository,讓 GoReleaser 更新 `pchome-cli.json` -- 在 `pchome-cli` repository 的 GitHub Actions secrets 加上 `PACKAGE_REPOS_TOKEN` -- `PACKAGE_REPOS_TOKEN` 需要能寫入上述兩個 repository - -補充: - -- 目前 Homebrew 走的是「自有 tap」路線,不是 `homebrew/core` -- GoReleaser 會在正式 release tag 時更新 tap / bucket;prerelease tag 會自動略過 diff --git a/banner.png b/banner.png deleted file mode 100644 index 7e5fa31..0000000 Binary files a/banner.png and /dev/null differ diff --git a/cmd/testdata/help/root_zh_tw.golden b/cmd/testdata/help/root_zh_tw.golden index b4db593..8aa27a9 100644 --- a/cmd/testdata/help/root_zh_tw.golden +++ b/cmd/testdata/help/root_zh_tw.golden @@ -1,6 +1,6 @@ 搜尋、檢視、比較與推薦 PChome 24h 商品。 -範例: +範例: pchome search "掃地機器人" --min-price 5000 --max-price 15000 pchome view DMBL53-A900JDNJS pchome recommend https://24h.pchome.com.tw/prod/DMBL53-A900JDNJS --why @@ -11,20 +11,20 @@ 可用指令: - compare 比較多個商品 + compare 比較多項商品 completion 產生指定 shell 的自動補全腳本 - help 顯示任一指令的說明 - recommend 取得商品推薦 + help 顯示指令的說明 + recommend 取得推薦商品 search 搜尋商品 - suggest 提供可能的搜尋關鍵字 + suggest 提供搜尋建議 view 檢視商品詳情 -旗標: +選項: --format string 輸出格式:text|json|ndjson (default "text") -h, --help 顯示 pchome 的說明 - --name-width int 文字輸出中的商品名稱欄寬 (default 30) + --name-width int 文字輸出時的商品名稱欄位寬度 (default 30) --schema-version string 機器可讀輸出的 schema 版本 (default "v1") - --timeout duration 請求逾時時間 (default 20s) + --timeout duration API 請求逾時時間 (default 20s) -v, --version 顯示 pchome 的版本資訊 -使用 "pchome [command] --help" 取得指令的更多資訊。 +使用 "pchome [command] --help" 取得指令的詳細資訊。 diff --git a/cmd/testdata/render/product_detail_zh_tw.golden b/cmd/testdata/render/product_detail_zh_tw.golden index 1f546fa..7ede70f 100644 --- a/cmd/testdata/render/product_detail_zh_tw.golden +++ b/cmd/testdata/render/product_detail_zh_tw.golden @@ -1,12 +1,12 @@ Micron Crucial X10 -商品 ID: DRAA5K-A900JOK9O +商品編號: DRAA5K-A900JOK9O 網址: https://24h.pchome.com.tw/prod/DRAA5K-A900JOK9O 品牌: Micron -銷售名稱: Crucial X10 1TB -價格: 4,340 -定價: 5,999 +商品名稱: Crucial X10 1TB +網路價: 4,340 +市價: 5,999 折扣: 28% 評價: 5(4 則評價) -供貨資訊: 庫存=9 | 24h=Y | 出貨=Consign +供貨狀態: 庫存=9 | 24h=Y | 出貨=Consign 品牌別名: Micron, 美光 -主要圖片: https://example.com/image.jpg +主圖: https://example.com/image.jpg diff --git a/cmd/testdata/render/search_zh_tw.golden b/cmd/testdata/render/search_zh_tw.golden index b034031..597f701 100644 --- a/cmd/testdata/render/search_zh_tw.golden +++ b/cmd/testdata/render/search_zh_tw.golden @@ -1,4 +1,4 @@ -搜尋 "掃地機器人" | 顯示 1 / 100 筆 | 第 1 頁 | 已掃描 1 頁 | 排序=relevance - # | 價格 | 評價 | 評價數 | 24h | 數量 | 品牌 | 名稱 | 商品 ID - ---|-------|------|--------|-----|------|--------|---------------------------|------------------ - 1 | 6,999 | 4.9 | 33 | Y | 20 | Xiaomi | 小米 Xiaomi 掃拖機器人H40 | DMBL53-A900JDNJS +搜尋 "掃地機器人" | 傳回 1 筆(共 100 筆)| 第 1 頁 | 已掃描 1 頁 | 排序=relevance + # | 網路價 | 評價 | 評價數 | 24h | 庫存 | 品牌 | 商品名稱 | 商品編號 + ---|--------|------|--------|-----|------|--------|---------------------------|------------------ + 1 | 6,999 | 4.9 | 33 | Y | 20 | Xiaomi | 小米 Xiaomi 掃拖機器人H40 | DMBL53-A900JDNJS diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 0000000..7d2ea55 --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,67 @@ +# Contributing & Releasing + +## Repository Layout + +``` +cmd/ Cobra command layer and text rendering +cmd/pchome/ Binary entrypoint +cmd/testdata/ Golden fixtures for CLI help and text output +pkg/catalog/ Normalized product models and aggregate service +pkg/config/ Config loading and validation +pkg/i18n/ Language handling and translation catalog +pkg/output/ Shared table rendering +pkg/pchome/ Upstream PChome API clients +pkg/*/testdata/ Package-level test fixtures +``` + +## Development + +```bash +# Fast local build for the current platform +make build + +# Unit tests + GoReleaser config validation +make verify + +# Simulate a full release locally into ./dist +make release-snapshot +``` + +On first run, `make verify` and `make release-snapshot` automatically download and cache the pinned GoReleaser version. + +Run unit tests directly: + +```bash +go test ./... +``` + +## Build and Release + +Recommended maintainer workflow: + +```bash +git tag -a v0.1.0 -m "v0.1.0" +git push origin v0.1.0 +``` + +After a `v*` tag is pushed, GitHub Actions runs the release workflow and GoReleaser publishes macOS, Linux, and Windows archives for `amd64` and `arm64`, plus `checksums.txt`, to GitHub Releases. + +### Homebrew / Scoop Setup + +One-time setup for package manager distribution: + +- Create an `oliyy/homebrew-tap` repository for `Formula/pchome-cli.rb` +- Create an `oliyy/scoop-bucket` repository for `pchome-cli.json` +- Add a `PACKAGE_REPOS_TOKEN` GitHub Actions secret to `pchome-cli` +- That token needs write access to both repositories + +Notes: + +- The Homebrew path here is a personal tap, not `homebrew/core` +- GoReleaser updates the tap and bucket on normal release tags; prerelease tags are skipped automatically + +## Notes + +- Recommendation token precedence is `hermes.token` -> `PCHOME_HERMES_TOKEN` -> bundled fallback token. +- Machine-readable output keeps stable English schema keys regardless of locale, so agent integrations do not break. +- The current schema version is `--schema-version v1`. diff --git a/LANGUAGE_REVIEW.md b/docs/LANGUAGE_REVIEW.md similarity index 100% rename from LANGUAGE_REVIEW.md rename to docs/LANGUAGE_REVIEW.md diff --git a/docs/banner.png b/docs/banner.png new file mode 100644 index 0000000..8b9ed49 Binary files /dev/null and b/docs/banner.png differ diff --git a/pkg/i18n/i18n.go b/pkg/i18n/i18n.go index 455f66d..331b9b0 100644 --- a/pkg/i18n/i18n.go +++ b/pkg/i18n/i18n.go @@ -198,148 +198,147 @@ func SupportedLanguages() []Language { var translations = map[Language]map[Key]string{ LangZHTW: { - RootShort: "搜尋、檢視、比較與推薦 PChome 24h 商品", - RootLong: `搜尋、檢視、比較與推薦 PChome 24h 商品。 + RootShort: "搜尋、檢視、比較與推薦 PChome 24h 商品", + RootLong: `搜尋、檢視、比較與推薦 PChome 24h 商品。 -範例: +範例: pchome search "掃地機器人" --min-price 5000 --max-price 15000 pchome view DMBL53-A900JDNJS pchome recommend https://24h.pchome.com.tw/prod/DMBL53-A900JDNJS --why pchome compare DMBL53-A900JDNJS DMBL1C-A900JA04J`, - GroupShopping: "購物指令", - GroupDiscovery: "探索指令", - - HelpHeadingUsage: "使用方式:", - HelpHeadingAliases: "別名:", - HelpHeadingExamples: "範例:", - HelpHeadingAvailableCommands: "可用指令:", - HelpHeadingAdditionalCommands: "其他指令:", - HelpHeadingFlags: "旗標:", - HelpHeadingGlobalFlags: "全域旗標:", - HelpHeadingAdditionalTopics: "其他說明主題:", - HelpMoreInfo: "使用 \"%s [command] --help\" 取得指令的更多資訊。", - HelpFlagForCommand: "顯示 %s 的說明", - HelpFlagForThisCommand: "顯示此指令的說明", - VersionFlagForCommand: "顯示 %s 的版本資訊", - VersionFlagForThisCommand: "顯示此指令的版本資訊", - HelpCommandShort: "顯示任一指令的說明", - HelpCommandLong: "顯示應用程式中任一指令的說明。\n只要輸入 `%s help [指令路徑]` 即可查看完整內容。", - CompletionCommandShort: "產生指定 shell 的自動補全腳本", - - RootFlagFormat: "輸出格式:text|json|ndjson", - RootFlagSchemaVersion: "機器可讀輸出的 schema 版本", - RootFlagTimeout: "請求逾時時間", - RootFlagNameWidth: "文字輸出中的商品名稱欄寬", - - SearchShort: "搜尋商品", - SearchExample: " pchome search \"掃地機器人\" --min-price 5000 --max-price 15000 --in-stock", - SearchFlagCategory: "分類 ID", - SearchFlagBrand: "品牌篩選(子字串比對)", - SearchFlagSort: "排序方式:relevance|price-asc|price-desc|newest|best-selling", - SearchFlagPage: "起始頁碼", - SearchFlagPageSize: "每次上游請求的頁面大小", - SearchFlagLimit: "最多回傳幾筆商品", - SearchFlagMinPrice: "最低價格", - SearchFlagMaxPrice: "最高價格", - SearchFlagMinRating: "最低評價", - SearchFlagInStock: "只顯示有庫存的商品", - SearchFlagArrival24h: "只顯示支援 24h 到貨的商品", - SearchFlagColumns: "逗號分隔的文字欄位 (#,price,list,discount,rating,reviews,24h,qty,stock,brand,name,id,url,desc)", - SearchFlagShowURL: "在文字輸出中包含商品網址", - SearchFlagCompact: "在文字輸出中使用較窄的名稱欄", - SearchFlagWide: "在文字輸出中使用較寬的名稱欄", - - ViewShort: "檢視商品詳情", - ViewExample: " pchome view https://24h.pchome.com.tw/prod/DRAA5K-A900JOK9O", - ViewErrNDJSONUnsupported: "view 不支援 ndjson,請改用 --format json 或 text", - - RecommendShort: "取得商品推薦", - RecommendExample: " pchome recommend DMBL53-A900JDNJS --top 8 --why", - RecommendFlagTop: "最多回傳幾筆推薦商品", - RecommendFlagColumns: "逗號分隔的文字欄位 (#,score,price,list,discount,rating,reviews,24h,qty,stock,brand,name,id,url,why)", - RecommendFlagShowURL: "在文字輸出中包含商品網址", - RecommendFlagShowWhy: "在文字輸出中顯示推薦原因", - RecommendFlagCompact: "在文字輸出中使用較窄的名稱欄", - RecommendFlagWide: "在文字輸出中使用較寬的名稱欄", - - CompareShort: "比較多個商品", - CompareExample: " pchome compare DMBL53-A900JDNJS DMBL1C-A900JA04J", - CompareFlagColumns: "逗號分隔的文字欄位 (#,price,list,discount,rating,reviews,24h,qty,stock,brand,name,id,url)", - CompareFlagShowURL: "在文字輸出中包含商品網址", - CompareFlagCompact: "在文字輸出中使用較窄的名稱欄", - CompareFlagWide: "在文字輸出中使用較寬的名稱欄", - - SuggestShort: "提供可能的搜尋關鍵字", - SuggestExample: " pchome suggest \"掃地機\"", - SuggestFlagLimit: "最多回傳幾筆建議", - - RenderSearchSummary: "搜尋 %q | 顯示 %d / %d 筆 | 第 %d 頁 | 已掃描 %d 頁 | 排序=%s\n", - RenderFilters: "篩選條件:%s\n", - RenderRecommendSummary: "商品 %s 的推薦結果 | 共 %d 筆 | 耗時 %.0fms\n", - RenderCompareSummary: "比較 %d 項商品\n", - RenderSuggestSummary: "%q 的搜尋建議 | 共 %d 筆\n", - RenderWarning: "警告:%s\n", - - FieldID: "商品 ID", - FieldURL: "網址", - FieldBrand: "品牌", - FieldSalesName: "銷售名稱", - FieldNick: "別名", - FieldTagline: "標語", - FieldDescription: "描述", - FieldPrice: "價格", - FieldListPrice: "定價", - FieldLowestObserved: "最低觀察價", - FieldDiscount: "折扣", - FieldRating: "評價", - FieldAvailability: "供貨資訊", - FieldFlags: "標記", - FieldCategories: "分類", - FieldBrandAliases: "品牌別名", - FieldPrimaryImage: "主要圖片", - FieldImages: "圖片", - FieldMoreImages: "更多圖片", - FieldNotAvailable: "無", - - AvailabilitySummary: "%s=%s | 24h=%s | %s=%s\n", - AvailabilityStock: "庫存", - AvailabilityShip: "出貨", - FlagsSummary: "%s=%s | %s=%s\n", - FlagPrimeOnly: "Prime 限定", - FlagOrderDiscount: "訂單折扣", - RatingWithReviews: "(%s 則評價)", - - FilterCategory: "分類", - FilterBrand: "品牌", - FilterMinPrice: "最低價", - FilterMaxPrice: "最高價", - FilterMinRating: "最低評價", - FilterInStock: "有庫存", - FilterArrival24h: "24h 到貨", - - HeaderIndex: "#", - HeaderPrice: "價格", - HeaderList: "定價", - HeaderDiscount: "折扣%", - HeaderRating: "評價", - HeaderReviews: "評價數", - Header24h: "24h", - HeaderQty: "數量", - HeaderBrand: "品牌", - HeaderName: "名稱", - HeaderProductID: "商品 ID", - HeaderURL: "網址", - HeaderDescription: "描述", - HeaderScore: "分數", - HeaderWhy: "原因", - HeaderSuggestion: "建議", - - ErrInvalidFormat: "不支援的輸出格式 %q(請使用 text、json 或 ndjson)", - ErrInvalidSchemaVersion: "不支援的 schema 版本 %q(請使用 %s)", - ErrUnknownColumn: "未知欄位 %q", - }, - LangEN: { + GroupShopping: "購物指令", + GroupDiscovery: "探索指令", + + HelpHeadingUsage: "使用方式:", + HelpHeadingAliases: "別名:", + HelpHeadingExamples: "範例:", + HelpHeadingAvailableCommands: "可用指令:", + HelpHeadingAdditionalCommands: "其他指令:", + HelpHeadingFlags: "選項:", + HelpHeadingGlobalFlags: "全域選項:", + HelpHeadingAdditionalTopics: "其他說明主題:", + HelpMoreInfo: "使用 \"%s [command] --help\" 取得指令的詳細資訊。", + HelpFlagForCommand: "顯示 %s 的說明", + HelpFlagForThisCommand: "顯示此指令的說明", + VersionFlagForCommand: "顯示 %s 的版本資訊", + VersionFlagForThisCommand: "顯示此指令的版本資訊", + HelpCommandShort: "顯示指令的說明", + HelpCommandLong: "顯示應用程式中任何指令的說明。\n輸入 `%s help [指令名稱]` 即可查看完整內容。", + CompletionCommandShort: "產生指定 shell 的自動補全腳本", + + RootFlagFormat: "輸出格式:text|json|ndjson", + RootFlagSchemaVersion: "機器可讀輸出的 schema 版本", + RootFlagTimeout: "API 請求逾時時間", + RootFlagNameWidth: "文字輸出時的商品名稱欄位寬度", + + SearchShort: "搜尋商品", + SearchExample: " pchome search \"掃地機器人\" --min-price 5000 --max-price 15000 --in-stock", + SearchFlagCategory: "分類編號", + SearchFlagBrand: "品牌篩選(部分符合即可)", + SearchFlagSort: "排序方式:relevance(相關度)|price-asc(價格低至高)|price-desc(價格高至低)|newest(最新上架)|best-selling(最暢銷)", + SearchFlagPage: "起始頁碼", + SearchFlagPageSize: "每次 API 請求的資料筆數", + SearchFlagLimit: "最多顯示幾筆商品", + SearchFlagMinPrice: "最低價格", + SearchFlagMaxPrice: "最高價格", + SearchFlagMinRating: "最低評價", + SearchFlagInStock: "只顯示有庫存的商品", + SearchFlagArrival24h: "只顯示支援 24h 到貨的商品", + SearchFlagColumns: "以逗號分隔的顯示欄位 (#,price,list,discount,rating,reviews,24h,qty,stock,brand,name,id,url,desc)", + SearchFlagShowURL: "在文字輸出中包含商品網址", + SearchFlagCompact: "在文字輸出中縮減商品名稱欄位寬度", + SearchFlagWide: "在文字輸出中增加商品名稱欄位寬度", + + ViewShort: "檢視商品詳情", + ViewExample: " pchome view https://24h.pchome.com.tw/prod/DRAA5K-A900JOK9O", + ViewErrNDJSONUnsupported: "view 指令不支援 ndjson 格式,請改用 --format json 或 text", + + RecommendShort: "取得推薦商品", + RecommendExample: " pchome recommend DMBL53-A900JDNJS --top 8 --why", + RecommendFlagTop: "最多顯示幾筆推薦商品", + RecommendFlagColumns: "以逗號分隔的顯示欄位 (#,score,price,list,discount,rating,reviews,24h,qty,stock,brand,name,id,url,why)", + RecommendFlagShowURL: "在文字輸出中包含商品網址", + RecommendFlagShowWhy: "在文字輸出中顯示推薦原因", + RecommendFlagCompact: "在文字輸出中縮減商品名稱欄位寬度", + RecommendFlagWide: "在文字輸出中增加商品名稱欄位寬度", + + CompareShort: "比較多項商品", + CompareExample: " pchome compare DMBL53-A900JDNJS DMBL1C-A900JA04J", + CompareFlagColumns: "以逗號分隔的顯示欄位 (#,price,list,discount,rating,reviews,24h,qty,stock,brand,name,id,url)", + CompareFlagShowURL: "在文字輸出中包含商品網址", + CompareFlagCompact: "在文字輸出中縮減商品名稱欄位寬度", + CompareFlagWide: "在文字輸出中增加商品名稱欄位寬度", + + SuggestShort: "提供搜尋建議", + SuggestExample: " pchome suggest \"掃地機\"", + SuggestFlagLimit: "最多顯示幾筆搜尋建議", + + RenderSearchSummary: "搜尋 %q | 傳回 %d 筆(共 %d 筆)| 第 %d 頁 | 已掃描 %d 頁 | 排序=%s\n", + RenderFilters: "篩選條件:%s\n", + RenderRecommendSummary: "商品 %s 的推薦結果 | 傳回 %d 筆 | 耗時 %.0f 毫秒\n", + RenderCompareSummary: "比較 %d 項商品\n", + RenderSuggestSummary: "%q 的搜尋建議 | 傳回 %d 筆\n", + RenderWarning: "警告:%s\n", + + FieldID: "商品編號", + FieldURL: "網址", + FieldBrand: "品牌", + FieldSalesName: "商品名稱", + FieldNick: "簡稱", + FieldTagline: "促銷標語", + FieldDescription: "商品特色", + FieldPrice: "網路價", + FieldListPrice: "市價", + FieldLowestObserved: "歷史低價", + FieldDiscount: "折扣", + FieldRating: "評價", + FieldAvailability: "供貨狀態", + FieldFlags: "活動標籤", + FieldCategories: "分類", + FieldBrandAliases: "品牌別名", + FieldPrimaryImage: "主圖", + FieldImages: "商品圖片", + FieldMoreImages: "更多圖片", + FieldNotAvailable: "無", + + AvailabilitySummary: "%s=%s | 24h=%s | %s=%s\n", + AvailabilityStock: "庫存", + AvailabilityShip: "出貨", + FlagsSummary: "%s=%s | %s=%s\n", + FlagPrimeOnly: "Prime 限定", + FlagOrderDiscount: "結帳折扣", + RatingWithReviews: "(%s 則評價)", + + FilterCategory: "分類", + FilterBrand: "品牌", + FilterMinPrice: "最低價", + FilterMaxPrice: "最高價", + FilterMinRating: "最低評價", + FilterInStock: "有庫存", + FilterArrival24h: "24h 到貨", + + HeaderIndex: "#", + HeaderPrice: "網路價", + HeaderList: "市價", + HeaderDiscount: "折扣%", + HeaderRating: "評價", + HeaderReviews: "評價數", + Header24h: "24h", + HeaderQty: "庫存", + HeaderBrand: "品牌", + HeaderName: "商品名稱", + HeaderProductID: "商品編號", + HeaderURL: "網址", + HeaderDescription: "商品特色", + HeaderScore: "相關度", + HeaderWhy: "推薦原因", + HeaderSuggestion: "搜尋建議", + + ErrInvalidFormat: "不支援的輸出格式 %q(請使用 text、json 或 ndjson)", + ErrInvalidSchemaVersion: "不支援的 schema 版本 %q(請使用 %s)", + ErrUnknownColumn: "未知欄位 %q", + }, LangEN: { RootShort: "Search, inspect, compare, and recommend PChome 24h products", RootLong: `Search, inspect, compare, and recommend PChome 24h products.