docs(pkg): 同步文件與參考資料

What：更新 README、AGENTS.md、templates 與 references，讓文件敘述與實際行為一致。

Why：稽核發現多處文件與程式行為分歧，違反「每個意義只有單一真實來源」。

How：以實際程式行為為準改寫敘述，重複的規則收成單一來源並以一行指引指過去。

Who：jsc-meta:skill-check 例行稽核（2026-08-25）。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

README.md

@@ -20,11 +20,36 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安
 
 ## 工具
 
-| 工具 | 用途 |
+五支工具都靠 python3 解析或改寫檔案。少了 python3，每一支都回報「需要的指令不存在」，不會裝成查無套件。
-| --- | --- |
+
-| `tools/list-packages.sh` | 偵測專案類型並列出所有外部套件與目前版本（TSV：ecosystem / name / current） |
+| 工具 | 用途 | 需要的指令 |
-| `tools/latest-version.sh` | `latest-version.sh <ecosystem> <name>` 查最新穩定版（npm / pypi / nuget），查無 exit 4 |
+| --- | --- | --- |
-| `tools/apply-version.sh` | `apply-version.sh <ecosystem> <project dir> <name> <version>` 改寫版本來源檔案，把套件釘選到指定版本 |
+| `tools/list-packages.sh` | `list-packages.sh [專案目錄]` 偵測專案類型並列出所有外部套件與目前版本（TSV：ecosystem / name / current） | python3 |
+| `tools/latest-version.sh` | `latest-version.sh <ecosystem> <name>` 查最新穩定版（npm / pypi / nuget） | curl、python3 |
+| `tools/apply-version.sh` | `apply-version.sh <ecosystem> <project dir> <name> <version>` 改寫版本來源檔案，把套件釘選到指定版本 | python3 |
+| `tools/install-deps.sh` | `install-deps.sh <ecosystem> <project dir>` 重新解析並安裝相依套件（npm install、pip install、dotnet restore） | npm、pip、dotnet |
+| `tools/build-test.sh` | `build-test.sh <ecosystem> <project dir>` 偵測並執行建置與測試 | npm、python3、pytest、dotnet |
+
+### 結束碼總表
+
+一個數字只有一個意思，五支工具共用。新增工具請沿用這張表，不要自己編號。
+
+| 碼 | 意思 | 呼叫方的動作 |
+| --- | --- | --- |
+| 0 | 成功 | 繼續 |
+| 1 | 參數個數不對 | 停手 |
+| 2 | ecosystem 不認識 | 停手 |
+| 3 | 該 ecosystem 沒有來源檔案 | 跳過這個 ecosystem 或套件 |
+| 4 | 依工具而定：`list-packages.sh`、`build-test.sh`、`install-deps.sh` 是指令不存在（停手）；`latest-version.sh`、`apply-version.sh` 是查不到該套件（跳過） | 見左欄 |
+| 5 | 依工具而定：`latest-version.sh`、`apply-version.sh` 是指令不存在（停手）；`build-test.sh` 是推不出建置或測試指令（改問使用者） | 見左欄 |
+| 6 | 找不到專案目錄 | 停手 |
+| 其他 | 底層指令的結束碼 | 只有 `install-deps.sh`、`build-test.sh` 會走還原 |
+
+6 不與 3 合併：找不到專案目錄是輸入壞了，併進 3 會被當成跳過藏起來。`latest-version.sh` 不收專案目錄，所以沒有 6。
+
+4 與 5 在各工具間意思不同，是為了保住既有的跳過路由；新增工具請優先用 4 表示指令不存在。
+
+回 1、回 2、回 6 與回「指令不存在」時，技能只回報並停手，不還原工作樹——工具鏈壞了不是套件壞了，還原只會白白刪掉檔案。
 
 ## Skills 目錄