@loviusc/sa-spec 0.2.5 → 0.2.7

package/templates/readme.md

@@ -32,6 +32,7 @@ sa-spec init --full
 - `spec:propose` (`scp`) $\to$ **AI 自動建立 feature 分支與草稿目錄**（零手動指令）
 - `spec:analyze` (`sca`) $\to$ AI 衝突檢查並產出規格文件草稿
 - `spec:commit` (`scc`) $\to$ **AI 自動向主分支領取新號並自動合併回主分支！**
+- `spec:pdf` (`spd`) $\to$ **一鍵將單一 `.md` 或整個需求規格書轉為高品質 PDF！**
 
 👉 **Language Guides: [English](./README.en.md) | [繁體中文](./README.zh-TW.md) | [简体中文](./README.zh-CN.md) | [日本語](./README.ja.md) | [한국어](./README.ko.md)**
 
@@ -39,7 +40,7 @@ sa-spec init --full
 
 `sa-spec` 是一個輕量的系統分析文件工作台，用固定流程把需求想法整理成可確認、可歸檔、可檢查的文件。
 
-AI 工作流只使用四個指令，並支援簡寫別名（兩者等價）：
+AI 工作流使用五個指令，並支援簡寫別名（兩者等價）：
 
 | 標準指令 | 簡寫 | 說明 |
 |---|---|---|
@@ -47,6 +48,7 @@ AI 工作流只使用四個指令，並支援簡寫別名（兩者等價）：
 | `spec:propose` | `scp` | 提出需求並整理摘要 |
 | `spec:analyze` | `sca` | 衝突檢查與規格起草 |
 | `spec:commit` | `scc` | 確認歸檔並建立 Git commit |
+| `spec:pdf` | `spd` | 將指定 `.md` 或需求目錄匯出為 PDF |
 
 每個需求歸檔後固定包含：
 
@@ -96,6 +98,25 @@ npm --version
 git --version
 ```
 
+## 一鍵腳本管理（安裝 / 更新 / 解除安裝）
+
+專案內建獨立的跨平台腳本，直接執行對應檔案即可完成安裝、更新或解除安裝：
+
+### macOS / Linux (`.sh`)
+```bash
+./install.sh      # 安裝 sa-spec
+./update.sh       # 更新 sa-spec 至最新版本
+./uninstall.sh    # 解除安裝 sa-spec
+```
+
+### Windows (`.bat`)
+可直接雙擊執行，或在 CMD / PowerShell 輸入：
+```bat
+install.bat       &:: 安裝 sa-spec
+update.bat        &:: 更新 sa-spec 至最新版本
+uninstall.bat     &:: 解除安裝 sa-spec
+```
+
 ## macOS 安裝
 
 使用 npm 安裝：
@@ -275,6 +296,7 @@ sa-spec init --full
 | `sa-spec init [--full] [--lang zh-TW|en|zh-CN|ja|ko]` | 建立文件骨架與規則文件（支援 5 種語言，預設 `zh-TW`）。 |
 | `sa-spec new [--id REQ-001] --name login [--branch]` | 建立需求資料夾與空白文件模板（未帶 `--id` 時啟用多人草稿模式，可選 `--branch` 自動建立並切換至 `feat/<name>` 分支）。 |
 | `sa-spec finalize --name login` | 將草稿需求定號歸檔為最新序號（自動計算最新號碼、重命名目錄、批次置換 `{{REQ_ID}}` 並重建索引）。 |
+| `sa-spec pdf <target> [--split] [--output out.pdf]` | 將指定 `.md` 轉為同名 `.pdf`，或將需求編號/目錄（如 `REQ-001`）整包合併匯出成一份完整規格書 PDF（加 `--split` 則各檔獨立轉出，`--all` 匯出全專案）。 |
 | `sa-spec reindex` | 掃描 `project/REQ-*` 目錄，依序號重新生成乾淨無衝突的 `project/index.md`。 |
 | `sa-spec check` | 檢查基本文件是否存在。 |
 | `sa-spec status` | 顯示系統規格與需求索引狀態。 |
@@ -324,6 +346,7 @@ Markdown、PlantUML、YAML、GitLens 這類套件可以提升閱讀與檢查體
 | AI 工作流程 | `spec:propose` / `scp` | VS Code AI 對話側邊欄 | 整理使用者提出的需求。 |
 | AI 工作流程 | `spec:analyze` / `sca` | VS Code AI 對話側邊欄 | 檢查衝突並產出待確認草稿。 |
 | AI 工作流程 | `spec:commit` / `scc` | VS Code AI 對話側邊欄 | 歸檔已確認版本並建立本機 Git commit。 |
+| AI 工作流程 | `spec:pdf` / `spd` | VS Code AI 對話側邊欄 | 將指定 `.md` 或需求目錄匯出為 PDF 規格書。 |
 
 建議操作順序：
 
@@ -353,6 +376,7 @@ spec:commit  # 或簡寫 scc
 | `spec:propose` | `scp` | 使用者提出需求後，整理需求摘要、目標、初步流程與待確認事項。 |
 | `spec:analyze` | `sca` | 檢查是否與既有需求衝突；無衝突才產出 SRS、UML、OpenAPI、DB Schema 草稿。 |
 | `spec:commit` | `scc` | 使用者確認無衝突版本後，將版本歸檔到 `project/`，並建立本機 Git commit。 |
+| `spec:pdf` | `spd` | 將指定的 `.md` 檔或需求（如 `REQ-001`）匯出為高品質 PDF。 |
 
 狀態機：
 
@@ -385,7 +409,7 @@ commit (scc) -> 歸檔 -> 本機 Git commit
 docs(REQ-001): 番茄時鐘 - 新增專注與休息計時需求
 ```
 
-只有在使用者明確要求推送 remote，或專案設定啟用 auto-push 時，才會執行 `git push`。如果 push 失敗，只回報認證或網路問題，不會回滾已完成的文件歸檔與本機 commit。
+**鐵律**：只要 Git repository 有設定 remote（例如 `origin`），在 `scp` 建立分支與 `scc` 歸檔合併時，都會**自動執行 `git push` 推送至 remote**。如果 push 失敗，只回報認證或網路問題，不會回滾已完成的文件歸檔與本機 commit。
 
 ## 多人協作解決方案（Git-Flow 與延遲綁定 ID）
 
@@ -397,12 +421,12 @@ docs(REQ-001): 番茄時鐘 - 新增專注與休息計時需求
 
 ```mermaid
 flowchart TD
-    A["開新需求: scp 或 sa-spec new --branch"] --> B["建立並切換至 feat/cart 分支<br/>以 project/cart/ 建立草稿目錄"]
+    A["開新需求: scp 或 sa-spec new --branch"] --> B["建立並切換至 feat/cart 分支<br/>若有 remote 自動推分支至遠端<br/>以 project/cart/ 建立草稿目錄"]
     B --> C["AI 分析與起草: sca<br/>內部使用 {{REQ_ID}} 佔位<br/>自動同步 master 規格防護"]
     C --> D{"使用者確認通過<br/>執行 scc 或 finalize"}
-    D --> E["自動查詢主分支最新序號 N"]
+    D --> E["先推分支至 remote 並同步遠端狀態<br/>再查詢主分支最新序號 N"]
     E --> F["自動定號為 project/REQ-N+1-cart/<br/>批次置換 {{REQ_ID}} 並建立 commit"]
-    F --> G["自動合併至 master 主分支<br/>動態重新生成 project/index.md"]
+    F --> G["自動合併至 master 主分支並推上 remote<br/>動態重新生成 project/index.md"]
     G --> H["完成閉環：零衝突、序號永遠連續！"]
 ```
 
@@ -415,7 +439,7 @@ flowchart TD
   ```text
   scp 購物車結帳需求
   ```
-  AI 收到後，會**自動在背景執行 `git checkout -b feat/cart-checkout` 建立並切換分支**，並在 `project/cart-checkout/` 建立草稿目錄！
+  AI 收到後，會**自動在背景執行 `git checkout -b feat/cart-checkout` 建立並切換分支**，檢查若有設定 Git remote 則自動將分支推上遠端（`git push -u origin feat/cart-checkout`），並在 `project/cart-checkout/` 建立草稿目錄！
 * **方式 B（CLI 終端指令）**：
   ```bash
   sa-spec new --name cart-checkout --branch
@@ -425,7 +449,7 @@ flowchart TD
 #### 2. 分析與衝突檢查（規格基線同步）
 在分支上執行 `spec:analyze`（或 `sca`）前，工具會確認已取得 `master`（或 `origin/master`）的最新規格，確保是以全專案最新基準進行影響評估，避免因分支落後而漏檢權限、API 或資料表衝突。
 
-#### 3. 確認歸檔與延遲定號（自動領號 + 自動合併回主分支）
+#### 3. 確認歸檔與延遲定號（先推分支 + 自動領號 + 自動合併並推上 Remote）
 當需求規格經使用者確認無誤，準備歸檔時：
 
 * **方式 A（純 AI 自動化，最推薦）**：在 AI 側邊欄直接輸入：
@@ -433,15 +457,16 @@ flowchart TD
   scc
   ```
   AI 收到後會自動完成全自動 Git-Flow 閉環作業：
-  1. **自動向主分支查詢並取得新號**：查詢 master/main 目前最大序號（例如最大是 `REQ-005`，自動領取最新號 `REQ-006`），避免號碼競爭。
-  2. **自動定名更名**：使用 `git mv` 將目錄重命名為 `project/REQ-006-cart-checkout`，並將目錄內所有檔案的 `{{REQ_ID}}` 批次置換為 `REQ-006`。
-  3. **自動建立本機提交**：在 feature 分支自動建立 commit `docs(REQ-006): cart-checkout - 規格確認歸檔`。
-  4. **自動合併至主分支**：自動切換至主分支（`git checkout master`），將 feature 分支自動合併回主分支（`git merge feat/cart-checkout`），並重新生成主分支的 `project/index.md`，保證主分支規格最新且永遠不衝突！
+  1. **先推分支至 Remote 並同步遠端**：若 Git 有設定 remote，先將目前分支推送至遠端並執行 `git fetch` 同步最新狀態。
+  2. **自動向主分支查詢並取得新號**：查詢 master/main（含遠端主分支）目前最大序號（例如最大是 `REQ-005`，自動領取最新號 `REQ-006`），避免號碼競爭。
+  3. **自動定名更名**：使用 `git mv` 將目錄重命名為 `project/REQ-006-cart-checkout`，並將目錄內所有檔案的 `{{REQ_ID}}` 批次置換為 `REQ-006`。
+  4. **自動建立提交並推送分支**：在 feature 分支自動建立 commit `docs(REQ-006): cart-checkout - 規格確認歸檔`，若有 remote 則同步推送至遠端。
+  5. **自動合併至主分支並推送至 Remote**：自動切換至主分支（`git checkout master`），將 feature 分支自動合併回主分支（`git merge feat/cart-checkout`），重新生成主分支的 `project/index.md`，若有 remote 則自動將主分支推送至遠端（`git push origin master`），保證主分支規格最新且永遠不衝突！
 * **方式 B（CLI 終端指令）**：
   ```bash
   sa-spec finalize --name cart-checkout
   ```
-  CLI 同樣會自動查詢主分支最新序號定號、置換佔位符、完成提交並自動合併回 master！若想保留在當前分支手動處理，可加上 `--no-merge` 參數。
+  CLI 同樣會先推分支至 remote、查詢主分支最新序號定號、置換佔位符、完成提交、自動合併回 master 並推送至 remote！若想保留在當前分支手動處理，可加上 `--no-merge` 參數。
 
 #### 4. 消除索引合併衝突（`sa-spec reindex`）
 `project/index.md` 改為由目錄動態生成的「衍生清單」，不再依賴脆弱的手動 append：
@@ -702,7 +727,7 @@ git status
 git log -1 --oneline
 ```
 
-若要推送到 remote，需要明確要求 AI 執行 push，或自行執行：
+若 Git 有設定 remote，AI 與 CLI 會在建立分支與歸檔合併時自動執行 `git push` 推送至遠端；若當時尚未設定 remote，事後也可手動執行：
 
 ```bash
 git push origin main
@@ -719,11 +744,21 @@ git push origin master
 - 未經使用者確認，不得標示為 `已審核`。
 - `spec:analyze` 發現衝突時不得產出最終文件，也不得修改既有需求文件。
 - `project/system-spec.md` 只能在 `spec:commit` 依使用者確認內容更新。
-- `spec:commit` 會自動建立本機 Git commit；remote push 需使用者明確要求或啟用 auto-push。
+- **鐵律**：只要 Git 有設定 remote，`scp` 與 `scc` 都會自動將分支與主分支推送至 remote。
 - 一次最多問 3 個待確認問題，優先詢問會影響範圍、資料、權限、API、DB 或驗收的問題。
 
 ## 更新紀錄
 
+### v0.2.7
+- **新增 Markdown 轉 PDF 指令（`spec:pdf` / `spd` / `sa-spec pdf`）與跨平台獨立安裝腳本**：
+  - **Markdown 轉 PDF 支援**：新增 AI 指令 `spec:pdf`（簡寫 `spd`）與 CLI 指令 `sa-spec pdf <target> [--split] [--output out.pdf]`（及 `--all`），支援單一 `.md` 轉換、需求目錄整包合併匯出成一份完整規格書 PDF，或加 `--split` 各檔獨立匯出。
+  - **跨平台獨立管理腳本**：新增 macOS / Linux（`install.sh`、`update.sh`、`uninstall.sh`）與 Windows（`install.bat`、`update.bat`、`uninstall.bat`）6 個獨立執行腳本，一鍵完成安裝、更新與解除安裝。
+
+### v0.2.6
+- **Git Remote 自動推送鐵律（Remote Auto-Push）**：
+  - **`scp` 建立分支自動推上遠端**：執行 `spec:propose`（`scp`）或 `sa-spec new --branch` 建立 feature 分支後，自動偵測是否有設定 Git remote；若有則立即將新分支推送至遠端（`git push -u <remote> feat/<name>`）。
+  - **`scc` 先推分支再領號與主分支自動推送**：執行 `spec:commit`（`scc`）或 `sa-spec finalize` 時，若有設定 Git remote，會**先將目前分支推送至 remote 並同步遠端狀態**，接著才查詢主分支（`master`/`main`）最新可用序號定號，完成 feature 分支提交與推送、自動合併回主分支後，**自動將主分支推送至 remote**。
+
 ### v0.2.5
 - **支援前端 UI 線框圖（PlantUML Salt Code-as-Wireframe）**：
   - **純文字代碼化線框圖**：在 `uml/` 目錄新增標準 `uml/wireframe.puml`，使用 PlantUML Salt 語法（`@startsalt ... @endsalt`）以純文字定義頁面排版、輸入欄位、選項與按鈕，可直接在 VS Code 渲染預覽，並可納入 Git 版本追蹤。

package/templates/skills/system-analysis/SKILL.md

@@ -16,14 +16,15 @@ description: 用 init、propose、analyze、commit 四段流程整理需求，
 
 ## 指令流程
 
-使用四個核心指令，並支援簡寫別名（兩者等價）：
+使用五個核心指令，並支援簡寫別名（兩者等價）：
 
 | 指令 | 簡寫 | 用途 | 執行規則 |
 |---|---|---|---|
 | `spec:init` | `sci` | 初始化 | 載入並遵守 `AGENTS.md`、本 skill 與必要規則，確認 `project/` 結構是否存在。 |
-| `spec:propose` | `scp` | 提出需求 | 使用者提出需求後，自動依需求名稱建立並切換至專屬 feature 分支（`feat/<name>`，若已在 feature branch 則沿用），建立草稿目錄（內部使用 `{{REQ_ID}}` 佔位），整理需求摘要、目標、初步流程與待確認事項；不歸檔、不修改既有需求。 |
+| `spec:propose` | `scp` | 提出需求 | 使用者提出需求後，自動依需求名稱建立並切換至專屬 feature 分支（`feat/<name>`，若已在 feature branch 則沿用），檢查是否有設定 Git remote，若有則自動將分支推上 remote（`git push -u <remote> feat/<name>`），並建立草稿目錄（內部使用 `{{REQ_ID}}` 佔位），整理需求摘要、目標、初步流程與待確認事項；不歸檔、不修改既有需求。 |
 | `spec:analyze` | `sca` | 分析與起草 | 先檢查新需求是否與 `project/` 內所有既有需求衝突；無衝突才產出 SRS、UML、OpenAPI、DB Schema 草稿；有衝突則只列出衝突與待釐清問題，待使用者釐清後再次執行 `spec:analyze`（或 `sca`）。 |
-| `spec:commit` | `scc` | 確認歸檔 | 只把使用者已確認的版本歸檔到該需求資料夾，自動向主分支確認最新可用序號定號（`REQ-xxx`）、替換佔位符，更新 `project/index.md`、`project/system-spec.md` 與 `history.md`，建立本機 Git commit 後，自動切換回主分支並完成合併。 |
+| `spec:commit` | `scc` | 確認歸檔 | 只把使用者已確認的版本歸檔到該需求資料夾；若有 Git remote 則先將目前分支推上 remote 並同步遠端狀態，接著才查詢主分支（`master`/`main`）最新可用序號定號（`REQ-xxx`）、替換佔位符，更新 `project/index.md`、`project/system-spec.md` 與 `history.md`，建立 Git commit（若有 remote 則推送分支），再自動切換回主分支完成合併並推送到 remote。 |
+| `spec:pdf` | `spd` | 匯出 PDF | 呼叫 `sa-spec pdf <target> [--split] [--output <path>]`（或 `--all`），將指定的單一 `.md` 檔轉為同名 `.pdf`，或將指定需求目錄/編號（如 `REQ-001`）整包合併匯出成一份完整規格書 PDF（加 `--split` 則各別轉為獨立 PDF）。 |
 
 ## 硬性限制
 
@@ -46,10 +47,14 @@ description: 用 init、propose、analyze、commit 四段流程整理需求，
 - `spec:commit` 只能套用已由 `spec:analyze` 產出的、且使用者已確認的無衝突版本。
 - `handoff.md` 只能根據已確認的 SRS、UML、OpenAPI、DB Schema 與限制整理，不得新增未確認的開發假設。
 - 交給 OpenSpec 或其他 AI 開發工具時，必須指定它先閱讀 `handoff.md`，並以 `handoff.md` 作為開發入口與限制摘要；其他規格文件作為詳細來源。
+- **鐵律（Git Remote 自動推送強制規範）**：只要 Git repository 有設定 remote（例如 `origin`），所有分支建立與提交變更**都必須自動推送（`git push`）到 remote**，無需等待使用者額外指示；若 push 失敗時只回報認證或網路問題，不得回滾已完成的文件歸檔與本機 commit。
 - `spec:commit` 完成文件歸檔後，必須自動建立本機 Git commit；commit message 以需求編號與需求名稱為主，並加上簡短需求說明，格式為 `docs(REQ-001): 需求名稱 - 簡短需求說明`。
-- `spec:commit` 自動合併到主分支（Git-Flow 閉環）：完成 feature 分支 commit 後，若目前處於 feature 分支（`feat/<name>`），AI 必須自動切換回主分支（優先偵測 `main` 或 `master`），拉取/檢查最新狀態並自動合併該 feature 分支 (`git checkout master && git merge feat/<name>`)，隨後在主分支重新生成 `project/index.md` 索引，確保主分支規格清單完整且無衝突。
-- `spec:commit` 只有在使用者明確要求推送 remote，或專案設定啟用 auto-push 時，才可執行 `git push`；push 失敗時只回報認證或網路問題，不得回滾已完成的文件歸檔與本機 commit。
-- 多人協作與 Git-Flow 模式（延遲綁定序號與自動合併）：支援多人平行開發。執行 `spec:propose`（或 `scp`）時，若目前處於 master/main 分支，AI 必須自動依需求名稱建立並切換至專屬 feature branch（如 `feat/<name>`），並在 `project/<name>/` 建立草稿目錄，內部使用 `{{REQ_ID}}` 佔位，無需使用者手動敲 CLI；執行 `spec:analyze` 前應先確保取得 master 最新規格以防漏檢衝突；執行 `spec:commit` 歸檔時自動向 master 確認最新可用序號定號，自動將目錄定名為正式 `REQ-xxx`、替換內部佔位符、完成提交並自動合併回 master，避免多人合併時的序號競爭與索引衝突。
+- `spec:commit` 歸檔與自動合併閉環流程（含 Remote 同步順序）：
+  1. **先推分支至 Remote**：執行 `spec:commit`（或 `scc`）時，若檢查到 Git 有設定 remote，必須**先將目前分支推送至 remote**（`git push -u <remote> <branch>`）並同步遠端最新狀態（`git fetch <remote>`）。
+  2. **再查主分支最新版號**：接著才向主分支（`main` / `master` 及遠端主分支）查詢最新已使用序號，決定下一個可用序號（`REQ-xxx`）。
+  3. **定號歸檔與提交**：將草稿目錄重命名為正式 `project/REQ-xxx-<name>`、替換內部 `{{REQ_ID}}` 佔位符、更新索引與規格後，在 feature 分支建立 commit；若有 remote 則同步推送該 feature 分支至 remote。
+  4. **自動合併回主分支並推送**：若目前處於 feature 分支（`feat/<name>`），AI 必須自動切換回主分支（優先偵測 `main` 或 `master`），拉取/檢查最新狀態並自動合併該 feature 分支 (`git checkout master && git merge feat/<name>`)，隨後在主分支重新生成 `project/index.md` 索引；若有設定 remote，**必須自動將主分支推送至 remote**（`git push <remote> <mainBranch>`）。
+- 多人協作與 Git-Flow 模式（延遲綁定序號與自動合併）：支援多人平行開發。執行 `spec:propose`（或 `scp`）時，若目前處於 master/main 分支，AI 必須自動依需求名稱建立並切換至專屬 feature branch（如 `feat/<name>`），檢查若有設定 Git remote 則立即將新分支推上 remote（`git push -u <remote> feat/<name>`），並在 `project/<name>/` 建立草稿目錄，內部使用 `{{REQ_ID}}` 佔位，無需使用者手動敲 CLI；執行 `spec:analyze` 前應先確保取得 master 最新規格以防漏檢衝突；執行 `spec:commit` 歸檔時先推分支到 remote，再向 master 確認最新可用序號定號，自動將目錄定名為正式 `REQ-xxx`、替換內部佔位符、完成提交、自動合併回 master 並推上 remote，避免多人合併時的序號競爭與索引衝突。
 - 文件未經使用者確認，不得標示為 `已審核`。
 - `uml/` 內的 UML 圖不限單一 UML 圖型；`spec:analyze` 必須依需求選擇最能說明流程、互動、狀態、資料關係或介面佈局的圖表，例如活動圖、循序圖、使用案例圖、狀態圖、類別圖；**若需求涉及前端 UI 或使用者操作畫面，必須在 `uml/wireframe.puml` 產出線框圖（使用 PlantUML Salt 語法：`@startsalt ... @endsalt`）**；純後端需求則在 `handoff.md` 明確標記「無 UI 介面需求」。**嚴禁將多張圖混在同一個檔案中**，必須在需求資料夾下的 `uml/` 目錄拆分成獨立的 `.puml` 檔案（例如 `uml/main.puml`、`uml/sequence.puml`、`uml/wireframe.puml`），且每個檔案只能包含一組 `@start...` 與 `@end...`，以避免 PlantUML 渲染或預覽失敗。
 - 一次最多問 3 個待確認問題，優先詢問會影響範圍、資料、權限、API、DB 或驗收的問題。
@@ -137,15 +142,15 @@ project/
 docs(REQ-001): 需求名稱 - 簡短需求說明
 ```
 
-只有在使用者明確要求推送 remote，或專案設定啟用 auto-push 時，才可執行 `git push`。若 push 失敗，只回報認證或網路問題，不得回滾已完成的文件歸檔與本機 commit。
+只要 Git repository 有設定 remote（例如 `origin`），在 `spec:commit` 歸檔時必須先將目前分支推送至 remote 並同步遠端狀態，接著查詢主分支最新版號、完成定號歸檔與 commit、合併回主分支後，自動將主分支推送至 remote。若 push 失敗，只回報認證或網路問題，不得回滾已完成的文件歸檔與本機 commit。
 
 ## 狀態機
 
 ```text
-init (sci) -> propose (scp) -> analyze (sca)
+init (sci) -> propose (scp, 建分支並推至 remote) -> analyze (sca)
 
 analyze 無衝突 -> 產出待確認版本 -> commit (scc)
 analyze 有衝突 -> 釐清問題 -> analyze (sca)
 
-commit (scc) -> 自動拿新號定號 -> feature commit -> 自動合併至主分支 (master/main)
+commit (scc) -> 先推分支至 remote -> 查 master 最新版號定號 -> feature commit -> 自動合併至主分支並推至 remote
 ```

package/uninstall.bat

@@ -0,0 +1,22 @@
+@echo off
+setlocal EnableDelayedExpansion
+chcp 65001 >nul 2>&1
+
+set "PACKAGE_NAME=@loviusc/sa-spec"
+set "SCRIPT_DIR=%~dp0"
+
+echo [sa-spec] 開始解除安裝 (Windows)...
+
+if exist "%SCRIPT_DIR%package.json" (
+    findstr /C:"@loviusc/sa-spec" "%SCRIPT_DIR%package.json" >nul 2>&1
+    if !errorlevel! equ 0 (
+        pushd "%SCRIPT_DIR%"
+        call npm unlink -g >nul 2>&1
+        popd
+    )
+)
+
+call npm uninstall -g %PACKAGE_NAME%
+
+echo [完成] 已解除安裝 sa-spec！
+pause

package/uninstall.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+set -e
+
+PACKAGE_NAME="@loviusc/sa-spec"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+echo "[sa-spec] 開始解除安裝 (${OSTYPE:-macOS/Linux})..."
+
+if [ -f "${SCRIPT_DIR}/package.json" ] && grep -q '"@loviusc/sa-spec"' "${SCRIPT_DIR}/package.json" 2>/dev/null; then
+  (cd "${SCRIPT_DIR}" && npm unlink -g 2>/dev/null) || true
+fi
+
+npm uninstall -g "${PACKAGE_NAME}" || true
+
+echo "[完成] 已解除安裝 sa-spec！"

package/update.bat

@@ -0,0 +1,43 @@
+@echo off
+setlocal EnableDelayedExpansion
+chcp 65001 >nul 2>&1
+
+set "PACKAGE_NAME=@loviusc/sa-spec"
+set "SCRIPT_DIR=%~dp0"
+
+echo [sa-spec] 開始更新 (Windows)...
+
+where node >nul 2>&1
+if %errorlevel% neq 0 (
+    echo [錯誤] 未偵測到 Node.js，請先執行 install.bat。
+    pause
+    exit /b 1
+)
+
+set "IS_SOURCE=0"
+if exist "%SCRIPT_DIR%package.json" (
+    findstr /C:"@loviusc/sa-spec" "%SCRIPT_DIR%package.json" >nul 2>&1
+    if !errorlevel! equ 0 set "IS_SOURCE=1"
+)
+
+if "%IS_SOURCE%"=="1" (
+    echo [更新] 偵測到 sa-spec 原始碼目錄...
+    pushd "%SCRIPT_DIR%"
+    if exist ".git" (
+        where git >nul 2>&1
+        if !errorlevel! equ 0 (
+            echo [Git] 正在拉取最新原始碼 ^(git pull --ff-only^)...
+            git pull --ff-only
+        )
+    )
+    call npm install
+    call npm link
+    popd
+) else (
+    echo [更新] 從 npm 更新 %PACKAGE_NAME%@latest...
+    call npm install -g %PACKAGE_NAME%@latest
+)
+
+echo [完成] sa-spec 已更新至最新版本！
+call sa-spec --version 2>nul
+pause

package/update.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+set -e
+
+PACKAGE_NAME="@loviusc/sa-spec"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+echo "[sa-spec] 開始更新 (${OSTYPE:-macOS/Linux})..."
+
+if ! command -v node >/dev/null 2>&1 || ! command -v npm >/dev/null 2>&1; then
+  echo "[錯誤] 未偵測到 Node.js 或 npm，請先執行 ./install.sh。"
+  exit 1
+fi
+
+if [ -f "${SCRIPT_DIR}/package.json" ] && grep -q '"@loviusc/sa-spec"' "${SCRIPT_DIR}/package.json" 2>/dev/null; then
+  echo "[更新] 偵測到 sa-spec 原始碼目錄 (${SCRIPT_DIR})..."
+  if [ -d "${SCRIPT_DIR}/.git" ] && command -v git >/dev/null 2>&1; then
+    if (cd "${SCRIPT_DIR}" && git remote | grep -q .); then
+      echo "[Git] 拉取最新原始碼 (git pull --ff-only)..."
+      (cd "${SCRIPT_DIR}" && git pull --ff-only) || echo "[提示] git pull 略過，請確認本地是否有未提交修改。"
+    fi
+  fi
+  cd "${SCRIPT_DIR}"
+  npm install
+  npm link
+else
+  echo "[更新] 從 npm 更新 ${PACKAGE_NAME}@latest..."
+  npm install -g "${PACKAGE_NAME}@latest"
+fi
+
+echo "[完成] sa-spec 已更新至最新版本: $(sa-spec --version 2>/dev/null || echo '未知')"