README.md

@@ -22,16 +22,17 @@ teai 是 Gitea 的命令列（CLI）工具，以更完整、更可靠的方式
 自 v0.1.0 起 module 已發佈 tag，可直接以版本安裝（二元檔裝進 `GOBIN`，預設 `~/go/bin`）：
 
 ```sh
-go install gitea.alterminal.com/alterminal/teai/cmd/teai@latest    # 最新 tag
-go install gitea.alterminal.com/alterminal/teai/cmd/teai@v0.1.0    # 指定版本
-teai version                                                       # 驗證：teai version v0.1.0
+go install gitea.alterminal.com/alterminal/teai/cmd/teai@latest    # 最新 tag（亦可 @v<版本> 指定）
+teai version                                                       # 驗證：顯示安裝的 tag 版本（見下方說明）
 ```
 
 本 module 為公開倉庫，預設 `GOPROXY`／`GOSUMDB` 即可解析（已於乾淨環境驗證）。
 若所在網路環境無法經公用 proxy 抓取，可改設 `GOPRIVATE=gitea.alterminal.com`
 （略過 proxy 與 checksum database，直接從 Gitea 抓取）。
 
-`teai version` 會顯示建入的 module 版本（tag 安裝為 `v0.1.0`；clone 建置為開發版 `0.1.0-dev`）。
+`teai version` 顯示建入的 module 版本，即安裝指定的 tag（如 `v0.1.1`）。
+注意：讀 build info 顯示安裝版本的支援，自包含該變更的 tag 起（v0.1.1）才生效——
+v0.1.0 早於此變更，以 `@v0.1.0` 安裝（或此變更前的 `@latest`）仍顯示舊行為 `0.1.0-dev`。
 
 ### 從原始碼建置（開發用）
 
@@ -42,7 +43,7 @@ git clone https://gitea.alterminal.com/alterminal/teai.git
 cd teai
 go build -o teai ./cmd/teai
 install -Dm755 teai ~/.local/bin/teai   # 或複製到任何 PATH 內目錄
-teai version                             # 驗證：teai version 0.1.0-dev
+teai version                             # 驗證：teai version v0.1.1-0.<時間戳>-<commit>（見下方說明）
 ```
 
 也可以在 clone 目錄內直接裝進 `GOBIN`：
@@ -51,6 +52,11 @@ teai version                             # 驗證：teai version 0.1.0-dev
 go install ./cmd/teai
 ```
 
+clone 建置時 Go 會把 VCS 狀態寫進 build info：位於 tag 上顯示該 tag、
+其後的 commit 顯示 pseudo-version（如 `v0.1.1-0.20260912160956-5a48fdd590b2`）、
+工作樹有修改再附加 `+dirty`；無 VCS 資訊（如從 tarball 解壓建置）時
+`Main.Version` 為 `(devel)`，此時退回開發版本號 `0.1.0-dev`。
+
 ### 登入設定（首次使用）
 
 teai 與 `tea` 共用同一份組態檔；若 `tea whoami` 已可正常輸出，可跳過本節。

internal/cli/cli.go

@@ -29,8 +29,10 @@ import (
 var Version = "0.1.0-dev"
 
 // buildVersion 回傳應顯示的版本字串。go install pkg@tag 建置的二元檔
-// 會在 Main.Version 帶入 tag（如 v0.1.0）；本機 go build 則為 "(devel)" 或空，
-// 此時退回開發版本號 Version。
+// 會在 Main.Version 帶入 tag（如 v0.1.0）；clone 目錄內本機建置則帶
+// pseudo-version（如 v0.1.1-0.<時間戳>-<commit>，工作樹有修改時再附加
+// "+dirty"），同樣直接顯示。Main.Version 為 "(devel)" 或空（go test 環境、
+// 無 VCS 資訊的 tarball 建置）時，才退回開發版本號 Version。
 func buildVersion() string {
 	if info, ok := debug.ReadBuildInfo(); ok {
 		if v := info.Main.Version; v != "" && v != "(devel)" {

internal/cli/version_test.go

@@ -1,5 +1,6 @@
 // version_test.go 驗證版本字串解析：go test 環境 Main.Version 為 "(devel)"
-// 時應退回開發版本號；-ldflags 覆寫測試 tag 行為則由建置驗證涵蓋。
+// 時應退回開發版本號；tag 與 pseudo-version 行為由建置驗證涵蓋
+// （go install pkg@tag 顯示 tag；clone 建置顯示 pseudo-version）。
 package cli
 
 import (