📖 技能介紹

name: filebrowser-api description: Operate FileBrowser via REST API—login, list/upload/download resources, manage users. Scan for 採購單 files in scope, prompt user to download by number or all, or provide download/browser link. Organize files by order type (e.g. 採購單) into 型別/年份/月份/ structure; report files that could not be organized and why. Use when automating FileBrowser, calling its API, or integrating with it.

FileBrowser API 操作

通過 REST API 操作 FileBrowser：認證、檔案列表/上傳/下載、使用者管理等。本技能適用於指令碼、自動化或與其他系統整合。

首次使用：向用戶確認配置

在通過本技能呼叫 FileBrowser API 或生成相關指令碼之前，按以下順序獲取 Base URL、使用者名稱、密碼：

優先：若存在 kam-filebrowser-operator/config.json，從中讀取 baseUrl、username、password、scope（該檔案已加入 .gitignore，勿提交）。
否則：若專案根目錄有 .env 或環境變數中有 FB_BASE_URL/FB_USER/FB_PASSWORD，可從中讀取。
否則：必須先向使用者詢問：
Base URL：例如 http://127.0.0.1:9888
使用者名稱：FileBrowser 登入賬號
密碼：至少 12 位

首次使用本 skill 時，可複製 kam-filebrowser-operator/config.example.json 為 kam-filebrowser-operator/config.json 並填寫真實值；務必保證 config.json 不被提交到版本庫，且不得上傳到 FileBrowser 或任何遠端位置。

安全：密碼與憑證

禁止在指令碼、示例程式碼或本技能文件中寫入真實密碼；僅使用佔位符（如 你的密碼、$FB_PASSWORD）或從環境變數/配置檔案讀取。
禁止將包含密碼的檔案提交到版本庫。憑證存放在 kam-filebrowser-operator/config.json（已加入 .gitignore）或專案根目錄 .env 中。
禁止上傳 kam-filebrowser-operator/config.json：該檔案含登入憑證，不得通過本 skill、FileBrowser API 或任何方式上傳到 FileBrowser 或其它遠端；執行上傳、同步、備份等操作時須排除該檔案。
禁止生成會讀取 .env 或持久化憑證的上傳/登入指令碼（例如 upload-to-filebrowser.sh 等）。僅提供一次性命令（如 curl），由使用者在已設定環境變數的終端中執行，或每次由使用者臨時提供 Base URL、使用者名稱、密碼。
使用本技能生成或修改指令碼時：從環境變數（如 FB_USER、FB_PASSWORD）或受保護的配置讀取賬號密碼，不要硬編碼。
Token 僅用於請求頭，不要寫入日誌、錯誤資訊或對外暴露。

可操作目錄（scope）

在 kam-filebrowser-operator/config.json 中必須配置 scope，表示本 skill 僅允許在該 FileBrowser 目錄下操作（如 "/Qianlu"）。
所有列出、上傳、下載、建立目錄、刪除等操作，路徑必須在 scope 之下；不得訪問或操作 scope 以外的路徑。
若 scope 對應目錄不存在：在執行列表、上傳等操作前，應先呼叫建立目錄介面（如 POST /api/resources/<scope 名>/?override=false，路徑末尾帶 /，不傳 Body）建立該目錄，再繼續執行使用者請求的操作。
若使用者請求的路徑超出 scope，須拒絕並說明僅支援在配置的目錄內操作；若未配置 scope，須提示使用者先在 config.json 中設定 scope 再執行操作。

基礎配置

憑證來源：優先使用 kam-filebrowser-operator/config.json（欄位 baseUrl、username、password、scope）；若無則用專案 .env 或環境變數；再無則向用戶詢問。
Base URL：預設 http://127.0.0.1:9888。可在 config.json 或 .env 中配置。
scope：必填。本 skill 僅在此目錄下操作，API 請求中的 path 均相對於此目錄或填完整路徑時也須落在 scope 內。
認證：先呼叫登入介面獲取 token，後續請求在 Header 中攜帶 X-Auth: <token>。

1. 登入獲取 Token

POST /api/login
Content-Type: application/json

{
  "username": "Username",
  "password": "你的密碼",
  "recaptcha": ""
}

成功響應體為 JSON，其中包含 token 欄位。後續所有 API 請求需新增：

X-Auth: <token>

2. 資源（檔案/目錄）介面

列出目錄

GET /api/resources?path=<scope>
GET /api/resources?path=<scope>/子目錄

Query 引數 path 必須在 config 的 scope 之下（如 scope 為 /Qianlu 時，用 Qianlu 或 Qianlu/子目錄；部分環境 path 帶前導 / 如 /Qianlu）。響應為 JSON，形如：

{
  "items": [
    { "name": "檔名.txt", "path": "相對路徑", "isDir": false, "size": 123, "extension": ".txt" },
    { "name": "子目錄", "path": "子目錄", "isDir": true, ... }
  ],
  "numDirs": 1,
  "numFiles": 1
}

查詢目錄：items 中 isDir === true 的項為子目錄，isDir === false 的為檔案。
path 用法：列出某目錄時，path 為相對於根或 scope 的路徑（如 Qianlu、Qianlu/採購單），下一層子項在 items[].name 或 items[].path 中。

遍歷目錄並獲取檔名稱

單層：GET /api/resources?path=<目錄路徑>，從響應 items 中取每項的 name（即該層下的檔名與子目錄名）。
遞迴遍歷：
先請求 path=<scope> 得到根層 items；
對每個 item：若 item.isDir === true，再請求 path=<當前路徑>/<item.name>（當前路徑首層為 scope 名，如 Qianlu），得到該子目錄下的 items；
重複上述步驟直到沒有子目錄，或達到所需層級；
收集所有 isDir === false 的 item.name 即為該目錄樹下的全部檔名（可同時保留相對路徑：當前路徑 + / + item.name）。
路徑約定：path 使用與 API 一致的格式（多數為 scope 或 scope/子路徑，無前導 /），遍歷時用「當前 path + / + 子項 name」拼出子路徑。

上傳檔案

POST /api/resources/<檔案路徑>?override=true
X-Auth: <token>
Content-Type: application/octet-stream
# 或具體型別，如 text/plain、application/json

<檔案二進位制或文本內容作為 Body>

<檔案路徑> 必須在 config 的 scope 之下，且必須帶 scope 字首才會進入 scope 目錄內（如 scope 為 /Qianlu 時，用 Qianlu/檔名，不要只用 檔名，否則會落在根目錄）。子路徑示例：Qianlu/doc.txt、Qianlu/子目錄/file.txt。
override=true 表示覆蓋已存在檔案；不傳或 false 則存在時可能報錯。
Body 為檔案原始內容，不要用 multipart/form-data。
禁止上傳：kam-filebrowser-operator/config.json、.env 及任何含憑證的檔案不得通過本介面上傳。

下載 / 原始檔案

GET /api/raw/<檔案路徑>
X-Auth: <token>

<檔案路徑> 必須在 scope 之下。返回檔案原始內容，用於下載或直接讀取。

採購單掃描與下載流程

在 scope 內掃描出採購單相關檔案（如通過搜尋「採購單」或遍歷目錄篩選名稱）後，按以下步驟與使用者互動：

列出清單並編號
將結果整理為帶編號的列表，例如：
1. 採購單-RFQ0311.xlsx、2. 採購單-XXX.xlsx
或使用檔名、編號等便於區分的標識。
提示是否下載
明確詢問使用者：是否需要下載？可回覆對應編號（如 1、2）或「全部」。
未選擇則視為不需要下載。
執行下載或提供連結
能直接提供檔案時：按使用者選擇的編號或「全部」，用 GET /api/raw/<路徑> 拉取檔案，在對話中提供或說明已準備好（視環境是否支援傳輸檔案）。
使用者要求直接下載連結或無法在對話中提供檔案時：按下方「分享連結（直接下載連結）」流程生成連結；若不可用則用方式二。
方式二（備用）：提供 FileBrowser 內下載說明：在瀏覽器開啟 baseUrl，登入後進入對應路徑（如 Qianlu/採購單-xxx.xlsx）即可下載。並提示：可在 FileBrowser Web 介面對該檔案點選「分享」自行生成有效連結。
提供連結時註明：分享連結有效期視服務端配置（expire 為 0 通常表示長期有效），若失效可再次請求生成。

分享連結（與網頁流程一致）

用於生成無需登入即可開啟分享頁並下載的連結，使用者要求「分享連結」時使用。

關鍵：端點是 /api/share/<檔案路徑>（單數 share，路徑在 URL），不是 /api/shares（複數）。複數端點會導致 path 被存為 "s"，生成的連結無效。

建立分享

```http POST /api/share/ X-Auth: Content-Type: application/json

{} ```

檔案路徑放在 URL 中，如 POST /api/share/Qianlu/採購單-RFQ0311.xlsx（路徑須在 scope 內）。
Body 為空 JSON {}。若需設定有效期，Body 傳 {"expires":"<秒數>","unit":"seconds"}，例如 1 小時：{"expires":"3600","unit":"seconds"}。不傳則長期有效（expire = 0）。
響應示例：{"hash":"0wod80NP","path":"/Qianlu/採購單-RFQ0311.xlsx","userID":1,"expire":0}，取 hash。
拼出分享連結
分享頁（與網頁「複製連結」一致）：baseUrl/share/<hash>
- 示例：http://127.0.0.1:9888/share/0wod80NP
- 使用者在瀏覽器中開啟即可檢視/下載（無需登入）。
直接下載（同一 hash）：baseUrl/api/public/dl/<hash>
驗證
建立後檢查響應中的 path 是否與請求路徑一致（如 /Qianlu/採購單-RFQ0311.xlsx）。若 path 異常（如 "s" 或與請求不符），說明使用了錯誤端點，須檢查 URL 是否為 /api/share/<路徑>（單數）。
可用 curl -s -o /dev/null -w "%{http_code}" <baseUrl>/api/public/dl/<hash> 驗證連結是否可下載（應返回 200）。注意：不要用 HEAD（curl -I）驗證，該端點不支援 HEAD 方法。
刪除分享
DELETE /api/share/<hash>，Header X-Auth: <token>。

按訂單型別整理（如「對採購單進行整理」）

當用戶提出對某類訂單檔案進行整理（例如「對採購單進行整理」）時，按以下流程執行，並在結束時明確告知：已整理到哪些路徑、哪些檔案無法整理及原因。

確定訂單型別與範圍
從使用者表述中識別訂單型別名稱（如「採購單」），及是否限定副檔名（預設可限定為 .xlsx 等常見表格格式，或不做副檔名限制）。
在 scope 內通過搜尋或遞迴列出目錄，收集名稱包含該型別關鍵詞且為檔案的項（如名稱含「採購單」）。只處理 scope 下的檔案，不處理已在「型別/年份/月份」子目錄下且已按規則命名的檔案（可選：避免重複整理）。
解析年月
對每個檔案，嘗試解析年份（YYYY）和月份（MM），用於生成目標路徑 型別/YYYY/MM/（例如 採購單/2026/03/）。
優先從檔名解析：若檔名中存在連續 8 位數字且形如 YYYYMMDD（如 20260312），取前 4 位為年、第 5–6 位為月；若為 6 位 YYYYMM，則取前 4 位為年、後 2 位為月。
若無則用修改時間：使用該檔案在 API 返回的 modified 欄位（若存在），轉換為本地或 UTC 的年份與月份。
若仍無法得到年月：該檔案不移動，歸入「無法整理」列表，原因寫為「無法從檔名或修改時間解析年月」。
建立目錄結構
在 scope 下建立目錄：<型別>/<YYYY>/<MM>/（如 Qianlu/採購單/2026/03/）。對涉及的所有 (YYYY, MM) 組合逐層建立，使用 POST /api/resources/<目錄路徑>/?override=false，路徑末尾帶 /，不傳 Body。
移動檔案
目標路徑為：<型別>/<YYYY>/<MM>/<原檔名>（如 採購單/2026/03/採購單-xxx-20260312.xlsx），須在 scope 內。
FileBrowser 無「移動到新路徑」的單次 API，採用：GET /api/raw/<原路徑> 下載內容 → POST /api/resources/<目標路徑>?override=true 上傳 → DELETE /api/resources/<原路徑> 刪除原檔案。若目標已存在且使用者未要求覆蓋，可視為「目標已存在，未移動」，歸入無法整理並說明原因。
若下載、上傳或刪除任一步失敗：該檔案留在原位置，歸入「無法整理」列表，原因寫為「移動失敗」並儘量附帶介面返回資訊（如許可權不足、目標已存在等）。
彙總並提示使用者
已整理：列出已成功移動到 型別/年份/月份/ 下的檔案及目標路徑（如 採購單/2026/03/採購單-xxx.xlsx）。
未整理（留在原位置）：列出每個檔案的當前路徑（或檔名）及原因，例如：
- 「無法從檔名或修改時間解析年月」
- 「目標路徑已存在，未覆蓋」
- 「移動失敗：<簡短錯誤原因>」
約定
所有路徑均在 scope 之下；型別子目錄（如 採購單）建在 scope 根下，即 scope名/採購單/2026/03/。
若某檔案已位於 型別/YYYY/MM/ 下且名稱符合當前命名規則，可視為已整理，無需再次移動；若使用者希望「重新整理」再按上述規則執行並覆蓋或跳過由實現決定（建議預設不覆蓋已存在目標，並歸入無法整理說明原因）。

建立目錄

POST /api/resources/<目錄路徑>/?override=false
X-Auth: <token>

路徑末尾必須帶 /，否則會建立成空檔案而非目錄。例如建立目錄 Qianlu 用 Qianlu/，建立 Qianlu/子目錄 用 Qianlu/子目錄/。
不傳 Body 或傳空 Body，不要傳 {}。
<目錄路徑> 必須在 scope 之下。

刪除

DELETE /api/resources/<路徑>
X-Auth: <token>

刪除檔案或目錄；路徑必須在 scope 之下。

想要更強大的技能外掛，就來小蔥技能站7w4.net看看吧。

3. 使用者管理（需管理員許可權）

列出使用者：GET /api/users，Header 需帶 X-Auth。
新建使用者：POST /api/users，Body 為 JSON，包含 username、password（至少 12 位）、perm 等。
更新使用者：PATCH /api/users/<id> 或按實際 API 約定。
刪除使用者：DELETE /api/users/<id>。

具體欄位以實際 Swagger/文件為準；部署內可訪問 http://<base>/swagger/ 檢視（若已開啟）。

4. 呼叫示例（curl）

憑證從環境變數讀取，勿在指令碼中寫明文密碼：

# 從 .env 或環境變數讀取（FB_USER、FB_PASSWORD 勿提交到 Git）
BASE="${FB_BASE_URL:-http://127.0.0.1:9888}"
TOKEN=$(curl -s -X POST "$BASE/api/login" \
  -H "Content-Type: application/json" \
  -d "{\"username\":\"$FB_USER\",\"password\":\"$FB_PASSWORD\",\"recaptcha\":\"\"}" \
  | jq -r '.token')

# 列根目錄
curl -s -H "X-Auth: $TOKEN" "$BASE/api/resources?path=/"

# 上傳
echo "hello" | curl -s -X POST "$BASE/api/resources/hello.txt?override=true" \
  -H "X-Auth: $TOKEN" -H "Content-Type: text/plain" --data-binary @-

# 下載
curl -s -H "X-Auth: $TOKEN" "$BASE/api/raw/hello.txt"

5. 錯誤與注意

未帶 X-Auth 或 token 無效會返回 401。
路徑不存在或許可權不足會返回 4xx，根據響應體調整 path 或許可權。
密碼需至少 12 位（與 Web 端一致）。
再次強調：密碼、Token 僅通過環境變數或本地 .env（且已加入 .gitignore）傳遞，不寫入程式碼、不提交、不暴露。

更多介面說明見 reference.md。

🤖 AI 評測

這個 Skill 質量較好，文件規範且易於理解，安全提示詳細（如密碼保護、目錄許可權限制），配置方法說明清晰。核心功能覆蓋完整，包括檔案列表、上傳下載、分享連結和自動整理。不足之處是缺少示例檔案和故障排除指引，對新手可能不夠友好。總體而言，這是一個功能實用、安全意識強、文件質量較高的 API 操作技能。

📊 多維度評分

適應性4.3

規範性4.4

有效性4.6

可靠性4

可信度5

📁 包含檔案 (5 個)

📄 SKILL.md 15.6 KB

📄 _meta.json 143 B

📄 config.example.json 137 B

📄 reference.md 3.7 KB

📄 skill-card.md 2.4 KB

File Browser Operator