YSK 自家產品 · MIT 開源 · npm · v1.0.1
合約先行
@ysk-kit/contracts 是 enum、DTO、error code 與 ts-rest 路由的唯一來源。不用 TypeScript enum。
MIT v1.0.1開源自用
6 種 Flavorsaas · desktop · gateway …
16 項能力auth · jobs · billing …
10 個範例診所 · CRM · 工單 …
第一天寫業務規則，不要重砌骨架
本倉是可運行的 saas flavor。身分、檔案、通知、工作、郵件、API 金鑰、加密、即時通訊已經接上。產品業務 domain 不寫入 kit。
- 產生
pnpm create @ysk-kit/app - 資料庫migrate · seed
- 模組
ysk-kit add module - 驗證
pnpm layers· test - 開發API :3001 · Web :5173
apps/web ──► @ysk-kit/web-sdk ──► @ysk-kit/contracts
▲
apps/api（HTTP adapter）──────────────┤
│ │
▼ │
application / use-cases ─────────────┤
│ │
▼ │
domain（entities, ports）────────────┘
▲
│ implements
infra（prisma, redis, s3, mail）
Hexagonal API
業務核心不知道 Express、Prisma 或 React。Domain 與 application 只依 ports。pnpm layers 強制。
同一 HTTP 表面
瀏覽器、手機、合作夥伴與 agent 共用 REST + OpenAPI。客戶端只經 @ysk-kit/sdk 呼叫。
可選能力
Auth、jobs、billing 不是每個產品都要。Thin 預設剝走 llm／billing／組織／push，需要時再加。
| 功能 | 說明 |
|---|---|
| 產生器 | pnpm create @ysk-kit/app；本倉 pnpm --filter @ysk-kit/create-app start |
| Flavor | saas、desktop、gateway、php-bridge、trading、static-web3 |
| Preset | 預設 thin；full 保留本倉示範 |
| 資料庫 | Prisma 7，預設 MySQL；--db postgresql|sqlite |
| HTTP | Express 5 預設；HTTP_ADAPTER=fastify |
| Envelope | { ok, data }／{ ok, error }；四個已文件化例外 |
| 客戶端 | Vite 8 + React 19；Expo 57；Electron 44 |
| 命令列 | ysk-kit／yskk：add module、add capability、upgrade、check agent |
| 範例 | 十個 overlay：診所、CRM、庫存、工單… |
| 護欄 | ysk-kit upgrade 更新法律／skills／TypeScript／Biome；check agent 標記 enum、客戶端 Prisma、raw fetch |
| 預設埠 | API 3001 · Web 5173 · Admin 5174 · OpenAPI /docs |
| 運維 | Compose + PM2；可選 Jaeger／Prometheus／Grafana |
Flavor 決定複製哪些應用
--flavor 選 apps；--preset 再削可選能力。php-bridge 與 static-web3 不理 preset。
| Flavor | 得到甚麼 |
|---|---|
saas | API + web + admin + 可選 mobile |
desktop | API + Electron |
gateway | API + admin（機器 API 金鑰 ysk_live_…） |
php-bridge | OpenAPI + TypeScript／PHP 客戶端，沒有 Node 應用 |
trading | API + web + worker |
static-web3 | 只有 Vite web |
saas
- 公開 web、營運 admin、可選 Expo、同一 API
--no-admin／--no-mobile生效；--preset與--db生效- 預設 flavor
desktop
- Electron 經
@ysk-kit/sdk（platform: desktop）呼叫同一 API - Prisma 留在 API 行程，包括本機 SQLite
- 權杖可用 Electron
safeStorage
gateway
- 機器客戶端 + 營運主控台；admin 一定複製
- 鑄造金鑰：
POST /v1/me/api-keys，然後Authorization: Bearer ysk_live_… - 寫入
GATEWAY.md
php-bridge
- 不複製本 monorepo。產出 OpenAPI 與 envelope 感知的 TypeScript／PHP 客戶端
- 指向既有 Kit API。其餘路徑用通用
request() - 不理 preset 與資料庫旗標
trading
- API + web + 既有 BullMQ worker
- 行情與交易所連接器留在產品倉
- 寫入
TRADING.md
static-web3
- 只有 Vite web 與
@ysk-kit/*客戶端庫。沒有 Prisma、DATABASE_URL - UI 若要 API，把
API_PUBLIC_URL指向遠端 - 錢包庫屬產品。寫入
WEB3.md
能力是平台功能；模組是業務切片
ysk-kit add <name> 合併一項已編目能力。ysk-kit add module 寫一個 hexagonal HTTP 切片。兩者不要混。
Thin 之後仍在
- 身分（註冊、登入、OTP、refresh、用戶）
- 檔案／儲存、通知、工作 + 郵件
- API 金鑰 + 加密、即時通訊（Socket.IO）
- Thin 剝走：
llm、team（組織）、billing、push（裝置） - 還原：
pnpm ysk-kit add llm|team|billing|push。billing要先有team
能力目錄
| 名稱 | 加入甚麼 |
|---|---|
auth | Session／OTP Prisma、JWT、OTP TTL、可選 Twilio |
rbac | 權限已在 ROLE_PERMISSIONS |
audit-log | 審計 Prisma 片段 |
storage | FileObject、S3_*、@ysk-kit/storage |
i18n | 預設語系 zh-HK |
jobs | Redis + BullMQ；未設 REDIS_URL 則記憶體佇列 |
mail | SMTP；空則 log adapter |
notifications | 站內通知路由 |
llm | Chat Completions；複製原始碼樹 |
websocket | Socket.IO realtime |
push | 裝置 + Expo／FCM |
mobile | 指向 Expo 模板 |
team | Organization + Membership（別名 org） |
apikey | ApiKey 片段 |
crypto | AES-256-GCM，CRYPTO_MASTER_KEY |
billing | Stripe Checkout；需先有 Organization |
ysk-kit add module
- 名稱
^[a-z][a-z0-9-]*$。URL/v1/<name> --prisma合併 title／body／authorId 模型- 寫入 contracts DTO + ts-rest、domain port、application、infra（記憶體 + Prisma）、SDK、web-sdk、Vite 頁
- 第二次對同一名稱是 no-op
- 之後改 Prisma 欄位、把規則放進
application/，再pnpm db:migrate && pnpm gen:openapi
合約、層與信封
人類與 AI agent 走同一條路：scaffold thin、加模組、填 application/ 與 Prisma，再用 pnpm layers 驗證。
JSON envelope
- 成功
{ ok: true, data }；失敗{ ok: false, error }。分頁在data內 - 錯誤
code在 contracts（VALIDATION_FAILED、UNAUTHENTICATED、NOT_FOUND…） - 四個例外：
POST /v1/llm/streamSSE；發票 PDF HTTP 302；GET /docsHTML；GET /openapi.json
預設棧
| 層 | 預設 |
|---|---|
| Monorepo | pnpm 12.8.1 + Turborepo 2 |
| 語言 | TypeScript 6 strict + exactOptionalPropertyTypes |
| Web／Admin | Vite 8 + React 19 + TanStack Router／Query + Tailwind 4 |
| Mobile | Expo 57 |
| Desktop | Electron 44 |
| HTTP | Express 5；Fastify 5 可選 |
| 合約 | ts-rest + Zod 4 |
| 資料庫 | Prisma 7（MySQL 預設） |
| Auth | JWT + refresh；電郵／密碼與 +852 OTP |
| 觀測 | Prometheus GET /metrics；可選 OTLP／Jaeger／Grafana |
@ysk-kit 套件
contracts·domain-kernel·applicationapi-http·api-express·api-fastifysdk·web-sdk·ui·ui-logicauth·apikey·cryptojobs·mail·storage·i18nllm·push·realtime- 產品日常路徑是複製本樹 +
ysk-kit upgrade，不是把 registry 的@ysk-kit/*裝進目的地產品
不可違反
- 客戶端不可 import Prisma、Express、Fastify、
@ysk-kit/auth、jobs、mail、push 或 AWS SDK - API 不可 import React 或
@ysk-kit/ui - CI 用記憶體 ports，不啟動 Redis、Stripe、Twilio、FCM、Jaeger、Grafana
- Hono、Nest、Next、Drizzle、tRPC、GraphQL 不是預設
產生器與護欄
從 npm：pnpm create @ysk-kit/app。從本倉：pnpm --filter @ysk-kit/create-app start。環境變數 YSK_ROOT 指定要修補的產品根。
create-ysk-app
- 旗標：
--preset thin|full、--db mysql|postgresql|sqlite、--flavor、--no-admin、--no-mobile、--yes - TTY 會提示未給的選項；CI／pipe 永不提示
- 從 npm 下載
yanshekki/ysk-kit的v{version}標籤
ysk-kit／yskk
add module <kebab> [--prisma] [--web]add <capability>generate openapi（等同pnpm gen:openapi）upgrade [--dry-run]：複製允許清單上的法律、skills、TypeScript／Biome、pnpm layerscheck agent：標記 TypeScript enum、客戶端 Prisma、rawfetch(
十個完成範例
clinic-booking·crm-contacts·inventory-stock·helpdesk-tickets·membership-clubcourse-enrollment·invoice-quotes·event-rsvp·job-board·field-work-orders- 套用：
pnpm --filter @ysk-kit/examples start apply clinic-booking --yes - overlay 套到新產品目錄，不掛進本倉
驗證一次改動
pnpm layers && pnpm typecheck && pnpm test && pnpm gen:openapi && pnpm ysk-kit check agent- 種子帳號：
[email protected]／ysk-admin-dev（見.env.example）
診所預約範例截圖與快速安裝
以下五張是 clinic-booking 完成系統的真實介面（1280×800），不是虛構管理台。概念圖另標示。
02
空列表
模組頁：list + create，同一 Zod schema。真實截圖。
03
驗證
重疊的 SCHEDULED 時段會被拒絕。真實截圖。
04
已建立
信封內的一列預約。真實截圖。
05
OpenAPI
GET /docs Scalar UI。真實截圖。
06
模組扣合
能力與 flavor 像六角磚互鎖。概念圖。
07
分層
合約、應用、infra 分層。概念圖。
08
多端
Web、手機、桌面、閘道共用合約。概念圖。
快速指令
- 產生產品（thin · MySQL · saas）
- 安裝 · 環境 · 資料庫
- 產生／遷移／種子
- 加模組 →
pnpm dev
pnpm create @ysk-kit/app my-product --preset thin --db mysql --flavor saas
cd my-product
pnpm install
cp .env.example .env
docker compose up -d mysql
pnpm db:generate && pnpm db:migrate && pnpm db:seed
pnpm ysk-kit add module appointment --prisma --web
pnpm gen:openapi
pnpm dev
# API http://127.0.0.1:3001 · Web :5173 · Admin :5174需要代為 scaffold、白標或訂造再開發？見 商務合作 — 此頁不標價。
開源自用，企業可代為 scaffold 或訂造
YSK Kit 以 MIT 授權公開。YSK Limited 可代為產生產品、加模組與能力、白標 AppShell，或以 kit 為基底訂造再開發——不向開源使用收費，訂造按範圍書面報價。
開源自用
適合自行 scaffold、內部試用與開源貢獻。
- 合約先行 monorepo + CLI
pnpm create @ysk-kit/app自行安裝- 不向開源使用收費
YSK 代為 scaffold／訂造
適合要選定 flavor、白標、上線或接既有 PHP 的團隊。
- 主機仍是您的，不是多租戶雲端 SaaS
- 香港公司簽約；需要時另附保密協議
- 此頁不標訂造價，報價以書面為準
要十五分鐘開新產品
選 flavor 與資料庫，產出可跑的 API／web／admin。
已有 PHP 或 OpenAPI 客戶端
php-bridge 產出 envelope 感知的 TypeScript／PHP 客戶端。
要 Web + 手機 + 桌面
同一套合約，Vite、Expo、Electron 各走 @ysk-kit/sdk。
要上線到您的主機
Compose + PM2；需要時可裝在 YSK Server 上。
| 可訂造範圍 | 說明 |
|---|---|
| 代為 scaffold | Node 24、pnpm 12、flavor／preset／資料庫、首次 migrate／seed、pnpm dev |
| 模組與能力 | add module、llm／team／billing／push、欄位與業務規則 |
| 白標 | AppShell 名稱、標誌、預設語系 zh-HK／en |
| Flavor 裁剪 | gateway 金鑰、desktop Electron、php-bridge、trading worker、static-web3 |
| 上線 | Compose、PM2、反向代理、可選裝在 YSK Server |
| 培訓 | 合約先行、envelope、pnpm layers、agent skills |
| 交付後 | 文件、遠端培訓、約定期保固。小改動可走開發者外判月費技術票 |
合作流程
由查詢到保固，每一步都有書面範圍。開源下載與代為 scaffold／訂造分開計算。
- 查詢WhatsApp 或電郵：要做的產品、flavor、資料庫、是否要手機／桌面
- 發現遠端對談：合規、白標、既有系統、是否要 php-bridge
- 方案範圍、工期、交付物（scaffold vs 訂造模組）；書面報價
- 合約香港公司簽約；需要時另附保密協議
- scaffold／訂造以 YSK Kit 為基底；分階段演示
- 驗收API 可呼叫、web／admin 可登入、文件、培訓
- 保固約定期內修正；其後可轉維護或掛入外判月費
交付物（按合約）
- 可運行的產品樹（您的主機或交付的倉）
- 部署與操作文件；遠端培訓
- 約定期內缺陷修正
- 開源核心維持 MIT；訂造模組知識產權以合約為準
誠實邊界：YSK Kit 不是多租戶 SaaS。YSK 不把您的產品變成 YSK 雲。行業 domain 留在產品倉。CI 預設不啟動 Redis／Stripe／Twilio。不代申請雲帳號。
商務常見問題
是。MIT 開源，可自行安裝。YSK 不向開源使用收費。代為 scaffold 與訂造才按範圍報價。
選 flavor、加模組、白標與上線的範圍差很大，報價以書面方案為準。小改動可走現有開發者外判月費技術票；大改走專案。
不會。產品仍裝在您擁有或合約指定的主機。YSK 不做多租戶雲端版 YSK Kit。
常見問題 (FAQ)
直接答案：是。MIT 開源，可自行安裝使用。代為 scaffold 或訂造見商務合作，此頁不標價。
直接答案：Omni 是本機模型閘道。Server 是單機 Linux 控制平面。Kit 是開新產品用的合約先行全端平台。
直接答案：Node.js 24 與 pnpm 12。預設 API 埠 3001、Web 5173、Admin 5174。
直接答案：預設 thin 剝走 llm、billing、organizations 與 push。full 保留完整示範。還原用 pnpm ysk-kit add。
直接答案：不要。行業 domain 留在產品倉。十個範例是 overlay，套用到新目錄。
直接答案：不會。產品仍裝在您擁有或合約指定的主機。YSK 不做多租戶雲端版 YSK Kit。