@loviusc/sa-spec 0.2.6 → 0.2.7

package/README.en.md

@@ -22,7 +22,7 @@
 
 Before code-generation AI tools (OpenSpec, Claude Code, OpenAI Codex, Gemini CLI, Cursor) start implementation, `sa-spec` clarifies scopes, boundaries, data schemas, API contracts, permission matrices, and acceptance criteria to ensure that subsequent coding proceeds within safe, well-defined boundaries.
 
-The AI workflow operates on four standard commands (with shorthand aliases):
+The AI workflow operates on five standard commands (with shorthand aliases):
 
 | Command | Alias | Purpose | Description |
 |---|---|---|---|
@@ -30,6 +30,7 @@ The AI workflow operates on four standard commands (with shorthand aliases):
 | `spec:propose` | `scp` | Propose | Summarizes objectives, user stories, workflows, and open items without altering existing requirements. |
 | `spec:analyze` | `sca` | Analyze & Draft | Checks for conflicts against existing requirements, APIs, and DB schemas; drafts SRS, UML, OpenAPI, and DB schema. |
 | `spec:commit` | `scc` | Commit & Archive | Archives the user-verified version, assigns sequential ID, updates indexes, and generates a local Git commit. |
+| `spec:pdf` | `spd` | Export PDF | Exports a single `.md` file or an entire requirement folder (`REQ-001`) into a print-ready PDF specification. |
 
 Each finalized requirement produces a standardized, self-contained directory:
 
@@ -66,6 +67,20 @@ sa-spec defines what to build and its constraints; AI code tools build it right.
 - npm
 - Git
 
+### Cross-Platform Standalone Scripts (`.sh` / `.bat`)
+
+```bash
+# macOS / Linux
+./install.sh          # Install sa-spec
+./update.sh           # Update sa-spec to latest version
+./uninstall.sh        # Uninstall sa-spec
+
+# Windows (double-click or run via CMD / PowerShell)
+install.bat
+update.bat
+uninstall.bat
+```
+
 ### Global Installation via npm
 
 ```bash
@@ -88,6 +103,7 @@ sa-spec --version
 | `sa-spec init [--full] [--lang <lang>]` | Scaffolds the workspace skeleton (Supports `zh-TW`, `en`, `zh-CN`, `ja`, `ko`). |
 | `sa-spec new [--id REQ-001] --name login [--branch]` | Creates a requirement folder template. Omitting `--id` starts a draft in a feature branch (`feat/<name>`). |
 | `sa-spec finalize --name login` | Assigns the latest available sequential ID to a draft requirement, renames directory, substitutes `{{REQ_ID}}`, and regenerates index. |
+| `sa-spec pdf <target> [--split] [--output out.pdf]` | Converts a `.md` file or requirement (`REQ-001`) to a merged or split PDF (`--all` exports all). |
 | `sa-spec reindex` | Scans `project/REQ-*` directories and dynamically rebuilds `project/index.md` sorted by numerical ID. |
 | `sa-spec check` | Validates required project files and system spec status. |
 | `sa-spec status` | Displays overview status of requirements and specs. |

package/README.ja.md

@@ -22,7 +22,7 @@
 
 OpenSpec、Claude Code、OpenAI Codex、Gemini CLI などの AI 開発ツールがコード実装を始める前に、要件のスコープ、境界線、データモデル、API 規約、権限マトリクス、受入条件を事前に明確化し、安全で堅牢な開発境界を定義します。
 
-AI ワークフローは 4 つの標準コマンド（エイリアス対応）で動作します：
+AI ワークフローは 5 つの標準コマンド（エイリアス対応）で動作します：
 
 | コマンド | エイリアス | 目的 | 説明 |
 |---|---|---|---|
@@ -30,6 +30,7 @@ AI ワークフローは 4 つの標準コマンド（エイリアス対応）
 | `spec:propose` | `scp` | 要件提案 | 既存の仕様を変更せず、目的・概要・初期フロー・確認事項を整理します。 |
 | `spec:analyze` | `sca` | 分析と起草 | 既存の要件、API、DB スキーマとの競合をチェックし、問題がなければ SRS、UML、OpenAPI、DB スキーマのドラフトを作成します。 |
 | `spec:commit` | `scc` | 確認と保存 | ユーザーが承認したバージョンを正式に採番・保存し、インデックスを更新して Git コミットを作成します。 |
+| `spec:pdf` | `spd` | PDF 出力 | 指定した `.md` ファイルまたは要件ディレクトリ（`REQ-001` など）を PDF 仕様書として出力します。 |
 
 各要件フォルダーには以下の標準成果物が生成されます：
 
@@ -66,6 +67,20 @@ sa-spec が仕様と境界を明確にし、AI 開発ツールが正しく実装
 - npm
 - Git
 
+### クロスプラットフォーム独立スクリプト (`.sh` / `.bat`)
+
+```bash
+# macOS / Linux
+./install.sh          # インストール
+./update.sh           # 最新版へアップデート
+./uninstall.sh        # アンインストール
+
+# Windows（ダブルクリック、または CMD / PowerShell で実行）
+install.bat
+update.bat
+uninstall.bat
+```
+
 ### グローバルインストール
 
 ```bash
@@ -88,6 +103,7 @@ sa-spec --version
 | `sa-spec init [--full] [--lang <lang>]` | ワークスペースの骨格を初期化します（`zh-TW`、`en`、`zh-CN`、`ja`、`ko` に対応）。 |
 | `sa-spec new [--id REQ-001] --name login [--branch]` | 要件テンプレートを作成します。`--id` を省略すると、Git 分岐を活用したドラフトモード（`feat/<name>`）で開始します。 |
 | `sa-spec finalize --name login` | ドラフト要件に最新の連続番号を割り当て、フォルダー名を変更し、`{{REQ_ID}}` を置換してインデックスを再生成します。 |
+| `sa-spec pdf <target> [--split] [--output out.pdf]` | 指定した `.md` または要件（`REQ-001`）を統合または個別 PDF として出力します（`--all` で全件出力）。 |
 | `sa-spec reindex` | `project/REQ-*` ディレクトリをスキャンし、数値順にソートされた `project/index.md` を自動再構築します。 |
 | `sa-spec check` | 必須ファイルとシステム仕様の状態を検証します。 |
 | `sa-spec status` | 要件とシステム仕様の概要ステータスを表示します。 |

package/README.ko.md

@@ -22,7 +22,7 @@
 
 OpenSpec, Claude Code, OpenAI Codex, Gemini CLI 등 코드 생성 AI 도구가 구현을 시작하기 전에, 요구사항의 범위, 경계, 데이터 모델, API 인터페이스, 권한 매트릭스, 인수 조건을 사전에 명확히 정의하여 후속 개발이 안전하고 명확한 경계 내에서 진행되도록 보장합니다.
 
-AI 워크플로는 4가지 표준 명령어(별칭 지원)를 기반으로 동작합니다:
+AI 워크플로는 5가지 표준 명령어(별칭 지원)를 기반으로 동작합니다:
 
 | 표준 명령어 | 별칭 | 단계 | 설명 |
 |---|---|---|---|
@@ -30,6 +30,7 @@ AI 워크플로는 4가지 표준 명령어(별칭 지원)를 기반으로 동
 | `spec:propose` | `scp` | 요구사항 제안 | 기존 사양을 변경하지 않고 목표, 요약, 초기 흐름 및 미확인 사항을 정리합니다. |
 | `spec:analyze` | `sca` | 분석 및 초안 작성 | 기존 요구사항, API, DB와의 충돌 여부를 검사하고, 문제가 없을 때만 SRS, UML, OpenAPI, DB Schema 초안을 작성합니다. |
 | `spec:commit` | `scc` | 확인 및 보관 | 사용자가 승인한 버전을 정식 번호로 보관하고, 인덱스를 갱신하며 로컬 Git 커밋을 생성합니다. |
+| `spec:pdf` | `spd` | PDF 내보내기 | 지정한 `.md` 파일이나 요구사항 폴더(`REQ-001` 등)를 PDF 사양서로 변환합니다. |
 
 보관된 각 요구사항은 독립적이고 완전한 폴더로 구성됩니다:
 
@@ -66,6 +67,20 @@ sa-spec이 요구사항과 경계를 명확히 정의하고, AI 개발 도구가
 - npm
 - Git
 
+### 크로스 플랫폼 독립 스크립트 (`.sh` / `.bat`)
+
+```bash
+# macOS / Linux
+./install.sh          # 설치 (install)
+./update.sh           # 최신 버전 업데이트 (update)
+./uninstall.sh        # 제거 (uninstall)
+
+# Windows (더블클릭 또는 CMD / PowerShell 실행)
+install.bat
+update.bat
+uninstall.bat
+```
+
 ### npm 글로벌 설치
 
 ```bash
@@ -88,6 +103,7 @@ sa-spec --version
 | `sa-spec init [--full] [--lang <lang>]` | 워크스페이스 골격을 생성합니다 (`zh-TW`, `en`, `zh-CN`, `ja`, `ko` 지원, 기본값 `zh-TW`). |
 | `sa-spec new [--id REQ-001] --name login [--branch]` | 요구사항 템플릿 폴더를 생성합니다. `--id` 생략 시 다중 사용자 초안 브랜치(`feat/<name>`)로 생성됩니다. |
 | `sa-spec finalize --name login` | 초안 요구사항에 최신 연속 번호를 할당하고 폴더명 변경, `{{REQ_ID}}` 치환 및 인덱스를 자동 재구축합니다. |
+| `sa-spec pdf <target> [--split] [--output out.pdf]` | 지정한 `.md` 파일 또는 요구사항(`REQ-001`)을 통합 또는 개별 PDF로 변환합니다 (`--all` 전체 내보내기). |
 | `sa-spec reindex` | `project/REQ-*` 디렉토리를 스캔하여 번호순으로 정렬된 `project/index.md`를 동적으로 재생성합니다. |
 | `sa-spec check` | 필수 파일과 시스템 사양 상태를 검증합니다. |
 | `sa-spec status` | 요구사항 및 시스템 사양 현황을 확인합니다. |

package/README.zh-CN.md

@@ -22,7 +22,7 @@
 
 在 OpenSpec、Claude Code、OpenAI Codex、Gemini CLI 等代码生成工具介入之前，`sa-spec` 先行厘清需求边界、业务规则、数据模型、API 契约、权限矩阵与验收条件，避免 AI 编码时随心所欲破坏系统架构。
 
-AI 工作流使用四个标准指令（支持简写别名）：
+AI 工作流使用五个标准指令（支持简写别名）：
 
 | 标准指令 | 简写 | 阶段 | 说明 |
 |---|---|---|---|
@@ -30,6 +30,7 @@ AI 工作流使用四个标准指令（支持简写别名）：
 | `spec:propose` | `scp` | 提出需求 | 整理需求摘要、目标、初步流程与待确认事项，不修改已有规格。 |
 | `spec:analyze` | `sca` | 分析与起草 | 检查新需求是否与既有需求、API、DB 发生冲突；无冲突才产出 SRS、UML、OpenAPI 与 DB Schema 草案。 |
 | `spec:commit` | `scc` | 确认归档 | 用户确认后正式定号归档，更新索引与系统总表，并自动创建本地 Git commit。 |
+| `spec:pdf` | `spd` | 导出 PDF | 将指定的 `.md` 文件或需求目录（如 `REQ-001`）一键导出为 PDF 规格说明书。 |
 
 每个归档的需求固定包含一个独立完整的文件夹：
 
@@ -66,6 +67,20 @@ sa-spec 先把需求说清楚、定好边界；AI 代码工具再把需求实现
 - npm
 - Git
 
+### 跨平台独立脚本 (`.sh` / `.bat`)
+
+```bash
+# macOS / Linux
+./install.sh          # 安装 sa-spec
+./update.sh           # 更新 sa-spec 至最新版本
+./uninstall.sh        # 卸载 sa-spec
+
+# Windows（直接双击或在 CMD / PowerShell 执行）
+install.bat
+update.bat
+uninstall.bat
+```
+
 ### 全局安装
 
 ```bash
@@ -88,6 +103,7 @@ sa-spec --version
 | `sa-spec init [--full] [--lang <lang>]` | 初始化工作台骨架（支持 `zh-TW`、`en`、`zh-CN`、`ja`、`ko`，默认 `zh-TW`）。 |
 | `sa-spec new [--id REQ-001] --name login [--branch]` | 创建需求模板文件夹。省略 `--id` 时自动切入多人协作草稿分支（`feat/<name>`）。 |
 | `sa-spec finalize --name login` | 将草稿需求正式定号归档为最新序号，自动重命名目录、替换 `{{REQ_ID}}` 并重构索引。 |
+| `sa-spec pdf <target> [--split] [--output out.pdf]` | 将指定 `.md` 或需求（如 `REQ-001`）合并或拆分导出为 PDF（`--all` 导出全项目）。 |
 | `sa-spec reindex` | 扫描 `project/REQ-*` 目录，按序数字顺序动态重新生成 `project/index.md`。 |
 | `sa-spec check` | 检查项目必要文件与规格完整性。 |
 | `sa-spec status` | 查看系统规格与需求总览状态。 |

package/README.zh-TW.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。 |
 
 狀態機：
 
@@ -725,6 +749,11 @@ git push origin master
 
 ## 更新紀錄
 
+### 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>`）。

package/install.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，請先安裝 Node.js 18 或以上版本: https://nodejs.org/
+    pause
+    exit /b 1
+)
+
+where npm >nul 2>&1
+if %errorlevel% neq 0 (
+    echo [錯誤] 未偵測到 npm，請確認 Node.js 安裝是否完整。
+    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 原始碼目錄，執行 npm install 與 npm link...
+    pushd "%SCRIPT_DIR%"
+    call npm install
+    call npm link
+    popd
+) else (
+    echo [安裝] 從 npm 全域安裝 %PACKAGE_NAME%...
+    call npm install -g %PACKAGE_NAME%
+)
+
+echo [完成] sa-spec 安裝完成！
+call sa-spec --version 2>nul
+pause

package/install.sh

@@ -0,0 +1,43 @@
+#!/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; then
+  echo "[錯誤] 未偵測到 Node.js，請先安裝 Node.js 18 或以上版本: https://nodejs.org/"
+  exit 1
+fi
+
+if ! command -v npm >/dev/null 2>&1; then
+  echo "[錯誤] 未偵測到 npm，請確認 Node.js 與 npm 是否安裝完整。"
+  exit 1
+fi
+
+# 若全域目錄無寫入權限，自動切換至 ~/.npm-global 避免 sudo 權限問題
+NPM_PREFIX="$(npm prefix -g 2>/dev/null || echo "")"
+if [ -n "${NPM_PREFIX}" ] && [ ! -w "${NPM_PREFIX}" ] && [ ! -w "${NPM_PREFIX}/lib" ]; then
+  echo "[權限設定] 偵測到全域目錄 (${NPM_PREFIX}) 無寫入權限，自動設定 ~/.npm-global..."
+  mkdir -p "${HOME}/.npm-global"
+  npm config set prefix "${HOME}/.npm-global"
+  export PATH="${HOME}/.npm-global/bin:${PATH}"
+  for rc in "${HOME}/.zshrc" "${HOME}/.bashrc"; do
+    if [ -f "${rc}" ] && ! grep -q '.npm-global/bin' "${rc}" 2>/dev/null; then
+      echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> "${rc}"
+    fi
+  done
+fi
+
+if [ -f "${SCRIPT_DIR}/package.json" ] && grep -q '"@loviusc/sa-spec"' "${SCRIPT_DIR}/package.json" 2>/dev/null; then
+  echo "[安裝] 偵測到 sa-spec 原始碼目錄，執行 npm install 與 npm link..."
+  cd "${SCRIPT_DIR}"
+  npm install
+  npm link
+else
+  echo "[安裝] 從 npm 全域安裝 ${PACKAGE_NAME}..."
+  npm install -g "${PACKAGE_NAME}"
+fi
+
+echo "[完成] sa-spec 安裝成功！目前版本: $(sa-spec --version 2>/dev/null || echo '請重開終端機以套用 PATH')"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loviusc/sa-spec",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "Personal system analysis documentation workspace CLI",
   "publishConfig": {
     "access": "public",
@@ -21,11 +21,17 @@
     "bin/",
     "src/",
     "templates/",
+    "install.sh",
+    "update.sh",
+    "uninstall.sh",
+    "install.bat",
+    "update.bat",
+    "uninstall.bat",
     "readme.md",
     "README*.md"
   ],
   "scripts": {
-    "check": "node --check src/cli.js && node --check bin/sa-spec.js"
+    "check": "node --check src/cli.js && node --check src/pdf.js && node --check bin/sa-spec.js"
   },
   "keywords": [
     "system-analysis",

package/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。 |
 
 狀態機：
 
@@ -725,6 +749,11 @@ git push origin master
 
 ## 更新紀錄
 
+### 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>`）。

package/src/cli.js

@@ -1,6 +1,12 @@
 const fs = require("fs");
 const path = require("path");
 const { spawnSync } = require("child_process");
+const {
+  buildHtmlDocument,
+  convertMarkdownFileToPdf,
+  buildMergedRequirementMarkdown,
+  renderHtmlToPdf
+} = require("./pdf");
 
 const cwd = process.cwd();
 const rootDir = path.resolve(__dirname, "..");
@@ -38,6 +44,9 @@ function main() {
     case "template":
       runTemplate(args.slice(1));
       return;
+    case "pdf":
+      runPdf(args.slice(1));
+      return;
     case "version":
     case "--version":
     case "-v":
@@ -1021,6 +1030,171 @@ function printResultList(label, results) {
   }
 }
 
+function resolveReqTargetDir(target) {
+  const directAbs = path.resolve(cwd, target);
+  if (fs.existsSync(directAbs) && fs.statSync(directAbs).isDirectory()) {
+    return directAbs;
+  }
+
+  const projectDir = path.join(cwd, "project");
+  if (!fs.existsSync(projectDir)) return null;
+
+  const inProjectAbs = path.join(projectDir, target);
+  if (fs.existsSync(inProjectAbs) && fs.statSync(inProjectAbs).isDirectory()) {
+    return inProjectAbs;
+  }
+
+  const norm = target.toLowerCase().trim();
+  const entries = fs.readdirSync(projectDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const nameLower = entry.name.toLowerCase();
+    if (
+      nameLower === norm ||
+      nameLower.startsWith(`${norm}-`) ||
+      nameLower.endsWith(`-${slugify(target)}`)
+    ) {
+      return path.join(projectDir, entry.name);
+    }
+  }
+  return null;
+}
+
+function exportReqDirToPdf(reqAbsDir, options = {}) {
+  const { split = false, output = null, browser = null } = options;
+  const relDir = path.relative(cwd, reqAbsDir) || path.basename(reqAbsDir);
+  const results = [];
+
+  if (split) {
+    const entries = fs.readdirSync(reqAbsDir, { withFileTypes: true });
+    const mdFiles = entries
+      .filter((e) => e.isFile() && e.name.toLowerCase().endsWith(".md"))
+      .map((e) => path.join(reqAbsDir, e.name));
+
+    for (const mdFile of mdFiles) {
+      const res = convertMarkdownFileToPdf(mdFile, null, browser);
+      const relPdf = path.relative(cwd, mdFile.replace(/\.md$/i, ".pdf"));
+      if (res.ok) {
+        results.push({ action: "create", target: relPdf, message: `由 ${path.relative(cwd, mdFile)} 轉換 (${res.engine})` });
+      } else {
+        results.push({ action: "warn", target: relPdf, message: res.error });
+      }
+    }
+    return results;
+  }
+
+  const merged = buildMergedRequirementMarkdown(reqAbsDir);
+  if (!merged.markdown.trim()) {
+    results.push({ action: "warn", target: relDir, message: "目錄內無可匯出的規格文件內容" });
+    return results;
+  }
+
+  const defaultPdfPath = path.join(reqAbsDir, `${path.basename(reqAbsDir)}.pdf`);
+  const targetPdfPath = output ? path.resolve(cwd, output) : defaultPdfPath;
+  const html = buildHtmlDocument(merged.title, merged.markdown);
+  const res = renderHtmlToPdf(html, targetPdfPath, browser);
+  const relPdf = path.relative(cwd, targetPdfPath);
+
+  if (res.ok) {
+    results.push({
+      action: "create",
+      target: relPdf,
+      message: `已整包合併匯出完整需求規格書 PDF (${res.engine})`
+    });
+  } else {
+    results.push({ action: "warn", target: relPdf, message: res.error });
+  }
+  return results;
+}
+
+function runPdf(args = []) {
+  const split = args.includes("--split");
+  const all = args.includes("--all");
+  const output = getOption(args, "--output") || getOption(args, "-o");
+  const browser = getOption(args, "--browser");
+
+  const positional = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--output" || a === "-o" || a === "--browser" || a === "--name" || a === "--target") {
+      i++;
+      continue;
+    }
+    if (a.startsWith("-")) continue;
+    positional.push(a);
+  }
+
+  const target = getOption(args, "--name") || getOption(args, "--target") || positional[0];
+
+  if (!target && !all) {
+    fail(
+      "Usage:\n  sa-spec pdf <file.md> [--output out.pdf]\n  sa-spec pdf <REQ-001|name|dir> [--split] [--output out.pdf]\n  sa-spec pdf --all [--split]"
+    );
+    return;
+  }
+
+  const results = [];
+
+  if (all) {
+    const projectDir = path.join(cwd, "project");
+    if (!fs.existsSync(projectDir)) {
+      fail("找不到 project/ 目錄。");
+      return;
+    }
+    for (const rootMd of ["system-spec.md", "index.md"]) {
+      const mdPath = path.join(projectDir, rootMd);
+      if (fs.existsSync(mdPath)) {
+        const res = convertMarkdownFileToPdf(mdPath, null, browser);
+        const relPdf = path.relative(cwd, mdPath.replace(/\.md$/i, ".pdf"));
+        results.push(
+          res.ok
+            ? { action: "create", target: relPdf, message: `已轉換 (${res.engine})` }
+            : { action: "warn", target: relPdf, message: res.error }
+        );
+      }
+    }
+    const entries = fs.readdirSync(projectDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        const reqDir = path.join(projectDir, entry.name);
+        results.push(...exportReqDirToPdf(reqDir, { split, browser }));
+      }
+    }
+    printResultList("pdf", results);
+    return;
+  }
+
+  // 1. Check if target is a single .md file
+  const directFileAbs = path.resolve(cwd, target);
+  if (fs.existsSync(directFileAbs) && fs.statSync(directFileAbs).isFile()) {
+    const res = convertMarkdownFileToPdf(directFileAbs, output, browser);
+    const targetPdf = output
+      ? path.relative(cwd, path.resolve(cwd, output))
+      : path.relative(cwd, directFileAbs.replace(/\.[^.]+$/, ".pdf"));
+    if (res.ok) {
+      results.push({ action: "create", target: targetPdf, message: `單檔轉換完成 (${res.engine})` });
+    } else {
+      results.push({ action: "warn", target: targetPdf, message: res.error });
+      process.exitCode = 1;
+    }
+    printResultList("pdf", results);
+    return;
+  }
+
+  // 2. Check if target resolves to a requirement directory
+  const reqDirAbs = resolveReqTargetDir(target);
+  if (reqDirAbs) {
+    results.push(...exportReqDirToPdf(reqDirAbs, { split, output, browser }));
+    if (results.some((r) => r.action === "warn")) {
+      process.exitCode = 1;
+    }
+    printResultList("pdf", results);
+    return;
+  }
+
+  fail(`找不到指定的 Markdown 檔案或需求目錄: ${target}`);
+}
+
 function showHelp() {
   console.log(`sa-spec
 
@@ -1028,6 +1202,8 @@ Usage:
   sa-spec init [--full] [--lang zh-TW|en|zh-CN|ja|ko]
   sa-spec new [--id REQ-001] --name login [--branch]
   sa-spec finalize --name login [--no-merge]
+  sa-spec pdf <file.md|REQ-001|name> [--split] [--output out.pdf]
+  sa-spec pdf --all [--split]
   sa-spec reindex
   sa-spec check
   sa-spec upgrade [--dry-run]