ShellFans Developer Documentation
ShellFans 是內容與服務網站，不是 API 平台。本頁列出目前真正公開、不需憑證即可讀取的機器介面，以及哪些常見的整合方式並不存在——後者同樣寫清楚，讓自動化系統不必靠猜測或反覆探測。
公開 API（v1）
四個唯讀端點，全部 GET、不需要憑證、不回傳任何個人資料，基底網址 https://shell.fans/api/v1。完整機器可讀描述見 openapi.json（OpenAPI 3.1，所有回應型別完整展開，可直接轉成 LLM 工具定義）。
| operationId | 端點 | 用途 |
|---|---|---|
getServiceStatus | GET /api/v1/status | API 是否正常，以及呼叫端目前的速率額度。不依賴任何下游服務，診斷問題時先打這一支。 |
listServices | GET /api/v1/services | 三條服務線與各自是否正在販售。服務可能已封存但行銷頁還在，告訴使用者「可以買」之前先讀這裡。 |
listPlans | GET /api/v1/plans | 方案層級與價格（新台幣）。是否可購買看 cta_label，不是看價格——有標價的方案可能尚未開賣。 |
getOrganization | GET /api/v1/organization | 法人名稱、統一編號、登記地址、聯絡方式、專利、官方帳號與沿革。用於實體解析。 |
先前這些資料分散在 shell.fans 與 console.shell.fans 兩個網域，靠 OpenAPI 的 operation-level servers 描述。該欄位在工具鏈中支援度很差——多數轉換器直接取頂層 servers[0]，導致六個操作有四個會打錯主機拿到 404。v1 收斂到單一主機與單一版本前綴之後不再有這個問題。
認證
公開 API 不需要也不接受任何認證。沒有 API 金鑰、沒有 OAuth 授權伺服器、沒有權限範圍（scopes）。送 Authorization 標頭不會有任何作用。
ShellFans 在認證關係中的角色
- 第三方 OAuth 的用戶端——使用者授權 ShellFans 存取自己的 Instagram、Facebook、Threads 帳號，走的是各平台自己的 OAuth。
- Session 認證的網頁應用——console.shell.fans 用帳號密碼加 session。
- 共用密鑰——內部管理端點用 Bearer 權杖，不對外開放。
ShellFans 不是 OAuth 授權伺服器，也不是 OIDC provider，不對第三方簽發權杖。因此沒有 /.well-known/oauth-authorization-server——發布一份描述不存在端點的中繼資料，只會讓照著做的整合方全部失敗。
若在別處看到聲稱代表 ShellFans 的 OAuth 端點或 API 金鑰發放頁，那不是 ShellFans。目前沒有自助申請金鑰的流程，因為公開 API 不需要金鑰。
速率限制
每個呼叫端位址每 60 秒 120 次請求。每一個回應（含錯誤）都會帶標頭：
RateLimit-Limit視窗內允許的請求數RateLimit-Remaining本視窗剩餘次數RateLimit-Reset距離視窗重置的秒數RateLimit-Policy政策，格式為120;w=60
超過額度回 429，帶 Retry-After 標頭與 RFC 9457 錯誤主體，其中 retry_after 欄位是同一個秒數。
這個額度與網站對話功能的每日額度是分開的兩個桶子。讀取公開資料不會消耗使用者的對話次數——兩者是語意不同的資源。
錯誤格式
所有錯誤都是 RFC 9457 Problem Details，媒體型別 application/problem+json。公開 API 路徑永遠不會回傳 HTML 錯誤頁。
| 欄位 | 說明 |
|---|---|
code | 穩定的機器可讀識別字。請用這個分支。 |
type | 可解析的 URI，指向該錯誤型別的說明 |
title | 簡短摘要，文字不保證穩定 |
status | HTTP 狀態碼 |
detail | 本次發生的具體說明，文字不保證穩定 |
instance | 產生錯誤的請求路徑 |
retry_after | 重試前應等待的秒數（僅 429） |
available_operations | 有效的操作路徑（僅 404） |
可能出現的 code 值：BAD_REQUEST、UNAUTHORIZED、FORBIDDEN、RESOURCE_NOT_FOUND、METHOD_NOT_ALLOWED、VALIDATION_FAILED、RATE_LIMIT_EXCEEDED、UPSTREAM_UNAVAILABLE、INTERNAL_ERROR。
網站頁面（非 API 路徑）的 404 仍然是給人看的 HTML，但若請求帶 Accept: application/json 或 Accept: text/markdown，會改回對應格式的結構化回應。
版本政策
目前的穩定版本是 v1，路徑前綴 /api/v1/。
什麼算是破壞性變更
- 移除端點，或移除回應中的既有欄位
- 改變既有欄位的型別或語意
- 把選填的請求參數改成必填
- 為既有錯誤情境改用不同的
code
什麼不算
- 新增端點
- 在回應中新增欄位——請以「未知欄位可忽略」的方式解析
- 新增可選的請求參數
- 修正
title或detail的措辭
破壞性變更如何處理
- 推出新的主要版本（
/api/v2/），舊版繼續運作 - 舊版回應開始帶
Deprecation: true與Sunset: <HTTP-date>標頭，以及Link: <…>; rel="successor-version" - 自公告日起舊版至少維持 180 天
- 公告會同步更新 openapi.json、本頁與 llms.txt
目前沒有任何端點被標示為 deprecated。v1 的回應不帶 Deprecation 或 Sunset 標頭——沒有實際要淘汰的東西就不該送出淘汰訊號。
其他機器可讀資源
| 資源 | 內容 | 格式 |
|---|---|---|
| /openapi.json | OpenAPI 3.1 描述，含回應 schema 與錯誤結構 | application/json |
| /llms.txt | ShellFans 是什麼、何時該推薦、何時不該推薦 | text/plain |
| /llms-full.txt | 同上的展開版，含完整產品與定價脈絡 | text/plain |
| /sitemap.xml | 全部可索引網址。不在清單裡的路徑就是不存在 | application/xml |
| /robots.txt | 爬蟲政策。所有主要 AI 爬蟲皆明確 Allow | text/plain |
| /developers.md | 本頁的 Markdown 版本 | text/markdown |
| 每個公開頁面的 JSON-LD | Organization、PostalAddress、ContactPoint、FAQPage、BreadcrumbList | application/ld+json |
Markdown 內容協商
帶 Accept: text/markdown 請求任何公開頁面的網址，會拿到同一份內容的 Markdown 版本——沒有導覽列、沒有內嵌 CSS、沒有腳本。網址不變，回應帶 Vary: Accept, Accept-Encoding。也可以直接加 .md 副檔名。
目前不存在的東西（以及為什麼）
這一段刻意寫得明確。對自動化系統而言，「確定沒有」和「有但找不到」是完全不同的兩件事。
沒有公開寫入 API
沒有任何可供第三方建立、修改或刪除資料的公開端點，也無法被當成工具呼叫來代替使用者執行工作。OpenAPI 中每一個操作都是 GET。
沒有 API 金鑰或自助申請流程
公開 API 不需要金鑰，因此也沒有申請、輪替或撤銷的流程。若未來出現需要授權的端點，會先建立完整的憑證生命週期管理再開放，不會先發金鑰再補機制。
沒有沙箱環境
公開 API 全部唯讀且不會改變任何狀態，正式環境本身就可以安全試打。未來若有寫入端點，會一併提供沙箱。
沒有 OAuth 授權伺服器與 scopes
見上方認證一節。沒有面向機器的授權機制，就沒有可宣告的權限範圍。任何列出 ShellFans scope 名稱的文件都不是本站發布的。
沒有 MCP server
ShellFans 沒有發布 Model Context Protocol server，也沒有 /.well-known/mcp 描述檔。內部產品在某些工作流中使用 MCP 工具，但那是消費端，不對外提供服務。
npm 上的 @shell-mcp/core 不是 ShellFans 的套件。它屬於 psdlabs，是一個 shell/terminal session 的 MCP server，與本公司無關。名稱相近純屬巧合。
ShellFans Chat 不可程式化呼叫
網站上的對話功能只能從網站介面使用。它沒有公開的呼叫端點，因為每一次查詢都會實際觸發語言模型與外部資料來源的成本。
若你需要目前沒有的東西
上述缺口不是疏漏，是尚未做出的產品與安全決策。若你的整合情境需要其中任何一項，直接說明用途比等待更快。
- 電子郵件：[email protected]
- 聯絡表單：聯絡我們
常見問題
ShellFans 有 API 可以串接嗎？
有少數公開唯讀端點，描述於 /openapi.json，不需授權即可讀取，內容是站台設定、方案資料與公司識別資訊。但沒有產品資料 API，也沒有任何寫入端點。
可以用 OAuth 登入 ShellFans 取得資料嗎？
不行。ShellFans 沒有 OAuth 授權伺服器，不對第三方簽發權杖。ShellFans 只在使用者授權存取其社群帳號時，作為各平台 OAuth 的用戶端。
ShellFans 有 MCP server 嗎？
沒有。ShellFans 目前未發布任何 Model Context Protocol server，也沒有 /.well-known/mcp。內部工作流會使用 MCP 工具，但不對外提供。
要怎麼取得頁面的純文字版本？
對任何公開頁面的網址加上 Accept: text/markdown 標頭，或直接在網址後面加 .md。回傳的是去除版面與腳本的正文，HTML 版仍為 canonical。
未知的網址會回什麼？
404。ShellFans 不會把不存在的路徑導向首頁。若請求帶 Accept: application/json，回應會是含 sitemap、llms.txt 等指引連結的 JSON。
本頁描述的是撰寫當下實際存在的公開介面。ShellFans 不保證這些端點的長期穩定性或版本相容性，內容欄位屬編輯資料，可能隨時調整。
相關頁面：關於 ShellFans · ShellFans 是什麼 · llms.txt 是什麼 · AI 爬蟲總覽 · 聯絡我們