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` 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 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.