@agentgo-tw/app-sdk 0.0.0-stage → 2.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +552 -2
- package/dist/browser.cjs +335 -0
- package/dist/browser.d.cts +22 -0
- package/dist/browser.d.ts +22 -0
- package/dist/browser.js +66 -0
- package/dist/chunk-4KBWZDXW.js +208 -0
- package/dist/chunk-VCZOS6GJ.js +61 -0
- package/dist/client.cjs +283 -0
- package/dist/client.d.cts +76 -0
- package/dist/client.d.ts +76 -0
- package/dist/client.js +205 -0
- package/dist/index.cjs +634 -0
- package/dist/index.d.cts +145 -0
- package/dist/index.d.ts +145 -0
- package/dist/index.js +364 -0
- package/dist/od-BVdmZf1t.d.cts +2331 -0
- package/dist/od-sGQixHat.d.ts +2331 -0
- package/dist/version-ClrVQNzw.d.cts +214 -0
- package/dist/version-ClrVQNzw.d.ts +214 -0
- package/package.json +67 -4
package/README.md
CHANGED
|
@@ -1,3 +1,553 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @agentgo-tw/app-sdk
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
AI 研究所(agentgo.tw)上架 App 的平台 SDK。在 App 裡取得會員身分,使用平台 AI、房市資料、工作憑證和點數查詢;費用從會員的月點數扣,你不必自備 AI 金鑰。
|
|
4
|
+
|
|
5
|
+
- 伺服器端:`@agentgo-tw/app-sdk`(Node ≥ 20;Express、Next.js、任何以 fetch `Request` 為主的框架)
|
|
6
|
+
- 瀏覽器端:`@agentgo-tw/app-sdk/browser`(純前端 App 不必自己寫後端)
|
|
7
|
+
- 沒有執行期依賴;ESM 與 CommonJS 都可以用
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm install @agentgo-tw/app-sdk
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
> 平台規格:AI 研究所 spec 16〈AI 小工具上架與訂閱〉。協定版本 `CONTRACT_VERSION = 1`,SDK 主版號跟著協定走。
|
|
14
|
+
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
## 1. 環境變數
|
|
18
|
+
|
|
19
|
+
**平台會自動注入**(教官不用設,也不能自己設任何 `ACADEMY_` 開頭的變數):
|
|
20
|
+
|
|
21
|
+
| 變數 | 內容 |
|
|
22
|
+
|---|---|
|
|
23
|
+
| `ACADEMY_APP_UUID` | 這個 App 的編號 |
|
|
24
|
+
| `ACADEMY_APP_TOKEN` | App 呼叫平台用的金鑰(在上架頁換發後要重啟才生效) |
|
|
25
|
+
| `ACADEMY_BASE_URL` | 平台網址,例如 `https://agentgo.tw` |
|
|
26
|
+
| `ACADEMY_ENV` | `test`(測試環境)或 `production`(正式環境) |
|
|
27
|
+
|
|
28
|
+
**只在你自己的電腦上設**(本機開發模式,見第 10 節):`ACADEMY_DEV_MODE=1`、`ACADEMY_DEV_KEY`(在上架頁產生的個人開發金鑰)、`ACADEMY_DEV_USER`(假身分,可省略)、`ACADEMY_DEV_SERVICE`(把請求當成來自某個服務,可省略)、`ACADEMY_BASE_URL=https://agentgo.tw`。
|
|
29
|
+
|
|
30
|
+
## 2. 伺服器端:取得會員身分
|
|
31
|
+
|
|
32
|
+
### Express
|
|
33
|
+
|
|
34
|
+
```js
|
|
35
|
+
import express from 'express';
|
|
36
|
+
import { createAcademy } from '@agentgo-tw/app-sdk';
|
|
37
|
+
|
|
38
|
+
const academy = createAcademy(); // 讀平台注入的環境變數
|
|
39
|
+
const app = express();
|
|
40
|
+
app.use(express.json());
|
|
41
|
+
app.use(academy.express()); // 驗身分掛到 req.academy;自動回應上架自檢 /__academy/selfcheck
|
|
42
|
+
|
|
43
|
+
app.get('/api/me', (req, res) => {
|
|
44
|
+
if (!req.academy) return res.status(401).json({ message: '請從 AI 研究所開啟' });
|
|
45
|
+
const { user, entitlement, env } = req.academy;
|
|
46
|
+
res.json({ user, entitlement, env }); // user: { uuid, name, email }
|
|
47
|
+
});
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
`req.academy` 是 `null` 的情況:公開路徑(上架時設定、不經入口關卡的路徑),以及**尚未按「啟用」的正式環境**。
|
|
51
|
+
|
|
52
|
+
### Next.js(App Router)與其他 fetch 框架
|
|
53
|
+
|
|
54
|
+
```ts
|
|
55
|
+
// app/api/chat/route.ts
|
|
56
|
+
import { createAcademy } from '@agentgo-tw/app-sdk';
|
|
57
|
+
const academy = createAcademy();
|
|
58
|
+
|
|
59
|
+
export async function POST(request: Request) {
|
|
60
|
+
const ctx = await academy.fromRequest(request); // 沒有身分回 null
|
|
61
|
+
if (!ctx) return Response.json({ message: '請從 AI 研究所開啟' }, { status: 401 });
|
|
62
|
+
const r = await academy.ai(ctx).chat.completions.create({ model: 'smart', messages: await request.json() });
|
|
63
|
+
return Response.json(r);
|
|
64
|
+
}
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
上架自檢要放在 `middleware.ts`(`app/` 底下以底線開頭的資料夾不會成為路由,`/__academy/selfcheck` 沒辦法寫成 Route Handler):
|
|
68
|
+
|
|
69
|
+
```ts
|
|
70
|
+
// middleware.ts
|
|
71
|
+
import { createAcademy } from '@agentgo-tw/app-sdk';
|
|
72
|
+
const academy = createAcademy();
|
|
73
|
+
export async function middleware(request: Request) {
|
|
74
|
+
return (await academy.handleSelfcheck(request)) ?? undefined;
|
|
75
|
+
}
|
|
76
|
+
export const config = { matcher: '/__academy/selfcheck' };
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
### 身分 `entitlement.kind`
|
|
80
|
+
|
|
81
|
+
| 值 | 意思 |
|
|
82
|
+
|---|---|
|
|
83
|
+
| `SUBSCRIBED` | 訂閱制工具的有效訂閱者 |
|
|
84
|
+
| `OPEN` | 免費工具的會員 |
|
|
85
|
+
| `OWNER` | 你自己(正式環境) |
|
|
86
|
+
| `OWNER_TEST` | 測試環境(你自己、指定測試帳號、管理員) |
|
|
87
|
+
| `STAFF` | 平台管理員 |
|
|
88
|
+
|
|
89
|
+
日後可能新增其他值,**不認得的值請當成「可以使用」**。`entitlement.tier`(會員等級)只供顯示,不要用來擋人。
|
|
90
|
+
|
|
91
|
+
## 3. 平台 AI
|
|
92
|
+
|
|
93
|
+
```js
|
|
94
|
+
const ai = academy.ai(req); // 綁定這次請求的會員;瀏覽器端用 academyBrowser.ai()
|
|
95
|
+
|
|
96
|
+
const r = await ai.chat.completions.create({ model: 'smart', messages: [{ role: 'user', content: '你好' }], max_tokens: 400 });
|
|
97
|
+
console.log(r.choices[0].message.content);
|
|
98
|
+
|
|
99
|
+
// 串流
|
|
100
|
+
for await (const chunk of await ai.chat.completions.create({ model: 'fast', stream: true, messages })) {
|
|
101
|
+
process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
const img = await ai.images.generate({ model: 'image', prompt: '簡約房子圖示', n: 1 }); // data[0].b64_json
|
|
105
|
+
const tts = await ai.audio.speech.create({ model: 'tts', input: '歡迎光臨', voice: 'female-shaonv' }); // audio_url(限時網址,要保存請自行下載)
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
- **`model` 填平台別名,不是模型名**:`fast`(快速對話)、`smart`(進階對話)、`image`(圖片生成)、`tts`(語音合成)。填錯會收到 `MODEL_NOT_ALLOWED`,`err.details.allowed` 列出可用的別名。別名背後的模型由平台維護、有多段備援,模型退場時你不用改程式。
|
|
109
|
+
- 請求與回應形狀與 OpenAI 相容(對話、圖片);SDK 不改寫內容,只補認證、改打平台、把錯誤轉成 `AcademyError`。
|
|
110
|
+
- `max_tokens` 沒帶時平台以 4,096 計算預佔;**帶上合理的上限可以少佔點數**。單次呼叫上限 200 點。
|
|
111
|
+
- 圖片只提供生成(一次最多 4 張),不提供修改。語音 `input` 最多 5,000 字,`voice` 不帶用平台預設的中文女聲;瀏覽器端不提供語音。
|
|
112
|
+
- 固定格式輸出(`response_format`)不保證可用;請在提示詞要求 JSON 並自行解析。
|
|
113
|
+
- 扣點:依實際成本換算(`點數 = ceil(美元成本 × 匯率 × 1.3)`,最少 1 點)。被內容審查擋下、上游失敗都不扣點。
|
|
114
|
+
|
|
115
|
+
## 4. 房市資料
|
|
116
|
+
|
|
117
|
+
```js
|
|
118
|
+
const od = academy.od(req);
|
|
119
|
+
await od.lvr.deals({ city: '臺北市', district: '大安區', limit: 10 }); // 實價登錄逐筆成交
|
|
120
|
+
await od.lvr.marketContext({ city: '臺北市', district: '大安區' }); // 區域行情:中位數、p25/p75、逐月趨勢
|
|
121
|
+
await od.nearby.deals({ address: '臺北市大安區敦化南路二段 1 號' }); // 周邊近期成交
|
|
122
|
+
await od.nearby.amenities({ lat: 25.0263, lng: 121.5434 }); // 生活機能(含公車路線)與嫌惡設施
|
|
123
|
+
await od.nearby.comparables({ address: '…', building_type: '住宅大樓', area_min: 25, area_max: 35 }); // 同類型比較案例(坪)
|
|
124
|
+
await od.address.convert({ address: '…' }); // 地址正規化、地址與座標互轉
|
|
125
|
+
await od.address.convert({ city: '彰化縣', district: '社頭鄉', section: '湳西段', land_no: '652' }); // 地號查位置座標
|
|
126
|
+
await od.area.profile({ city: '臺北市', district: '大安區' }); // 人口、所得、全國新承做房貸利率與核貸成數
|
|
127
|
+
const risk = await od.hazards({ lat: 25.0263, lng: 121.5434 }); // 五類災害潛勢(查無不等於無風險)
|
|
128
|
+
risk.zoning; // 同一次查詢附帶的土地使用分區
|
|
129
|
+
await od.marketBriefs({ period_type: 'weekly' }); // 市場快訊
|
|
130
|
+
await od.tax.houseRates({ city: '臺北市' }); // 非自住住家用房屋稅率級距
|
|
131
|
+
const found = await od.judgments.search({ q: '漏水', final_only: true }); // 不動產判決(去識別化)
|
|
132
|
+
await od.judgments.get(found.items[0].id); // 單筆全文與上下級審
|
|
133
|
+
await od.judgments.meta(); // 糾紛類型等代碼表與收錄範圍(做搜尋表單用)
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
社區、學校、人口與村里統計、門牌建議(2.1.0 起;參數與回應都有具名的 TypeScript 型別):
|
|
137
|
+
|
|
138
|
+
```js
|
|
139
|
+
// 社區
|
|
140
|
+
const hits = await od.communities.suggest({ keyword: '惠宇', city: '臺中市' }); // 名稱自動完成(最多 20 筆)
|
|
141
|
+
const m = await od.communities.match({ name: '惠宇天青', city: '臺中市' }); // 名稱比對;m.reliable 為 false 時不可當正解
|
|
142
|
+
await od.communities.nearby({ address: '臺中市南屯區惠文路 1 號', radius: 500 }); // 周邊社區,附 distance_m(公尺)
|
|
143
|
+
await od.communities.inBounds({ sw_lat: 24.14, sw_lng: 120.63, ne_lat: 24.16, ne_lng: 120.65 }); // 地圖視窗內的社區
|
|
144
|
+
await od.communities.byArea({ city: '臺中市', district: '北屯區' }); // 行政區的社區名稱與別名
|
|
145
|
+
const c = await od.communities.get(hits.items[0].id); // 詳情;查無時 c.item 是 null
|
|
146
|
+
c.item?.price.avg_price_wan_per_ping; // 萬元/坪;沒有價格時是 null,原因看 price.status
|
|
147
|
+
|
|
148
|
+
// 學校(校地位置,不是學區劃分)
|
|
149
|
+
const s = await od.schools.nearby({ address: '…', level: ['elementary', 'junior_high'] }); // 落在校地內回該校,否則 2 公里內最近 5 所
|
|
150
|
+
s.disclaimer; // 「這是鄰近學校,不是學區劃分…」請顯示給使用者
|
|
151
|
+
await od.schools.search({ keyword: '惠文', city: '臺中市' }); // 校名搜尋(最多 50 所)
|
|
152
|
+
await od.schools.nearbyBatch([{ lat: 25.03, lng: 121.56 }, { lat: 24.15, lng: 120.64 }]); // 最多 20 個座標,整次算一次查詢
|
|
153
|
+
|
|
154
|
+
// 人口與村里統計
|
|
155
|
+
const pop = await od.population.village({ lat: 24.1538, lng: 120.641 }); // 所在村里最新一期人口
|
|
156
|
+
await od.stats.villages({ codes: [pop.village.code], items: ['population', 'income'] }); // 以村里代碼批次查(最多 500 個)
|
|
157
|
+
await od.area.series({ city: '臺北市', district: '中正區', items: ['population'], months: 24 }); // 歷史序列(由舊到新)
|
|
158
|
+
|
|
159
|
+
// 門牌建議
|
|
160
|
+
await od.address.suggest({ q: '松山區長春路42', limit: 5 }); // 依地址開頭給門牌候選,附座標
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
實價登錄的單筆詳情與統計(2.2.0 起;具名型別):
|
|
164
|
+
|
|
165
|
+
```js
|
|
166
|
+
const sim = await od.lvr.similar({ city: '臺北市', district: '大安區', building_type: '住宅大樓', months: 12, limit: 10 }); // 同區近期買賣,附成交 id
|
|
167
|
+
const d = await od.lvr.deal(sim.items[0].id); // 單筆完整登錄內容;查無時 d.item 是 null
|
|
168
|
+
d.item?.unit_price_wan_per_ping; // 車位拆算後單價(萬元/坪);d.item.unit_price_note 有值時要一併顯示
|
|
169
|
+
const sum = await od.lvr.summary({ city: '新北市', district: '板橋區', area_min: 25, area_max: 40 }); // 完整筆數與平均值(沒帶日期=近 12 個月)
|
|
170
|
+
sum.count; sum.stats?.avg_unit_price_wan_per_ping;
|
|
171
|
+
await od.lvr.statsByArea({ city: '臺北市' }); // 各行政區平均單價排行與前期漲跌幅
|
|
172
|
+
const t = await od.lvr.monthlyTrend({ city: '臺北市', district: '信義區', months: 24 }); // 逐月平均單價;is_partial 的月份請弱化
|
|
173
|
+
await od.lvr.rentalStats({ city: '新北市', district: '板橋區' }); // 租金行情:平均月租與每坪月租
|
|
174
|
+
await od.lvr.monthlyByRegion({ date_start: '2026-01-01', date_end: '2026-06-30', city: '臺北市' }); // 各行政區逐月件數與總金額
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
政策公告、期別摘要、新聞分析報告、市場快訊清單、物價與市場指標(2.3.0 起;具名型別):
|
|
178
|
+
|
|
179
|
+
```js
|
|
180
|
+
// 政策公告與媒體報導(依授權裁切,見下方說明)
|
|
181
|
+
const b = await od.bulletins.list({ category: 'credit', from: '2026-09-01', limit: 20 }); // 清單(新到舊,不含全文)
|
|
182
|
+
await od.bulletins.list({ city: '臺北市', kind: 'gov_bulletin' }); // city=發布機關所在縣市;mentions=中央條目提及的縣市
|
|
183
|
+
const one = await od.bulletins.get(b.items[0].id); // 單則;政府公告有 body 與 attachments,查無時 one.item 是 null
|
|
184
|
+
if (one.item?.content_withheld) one.item.usage_policy; // 「媒體報導:依授權只提供標題…」——請引導使用者點 url 看原文
|
|
185
|
+
await od.bulletins.documents(b.items[0].id); // 附件 PDF 逐頁原文(只有政府公告)
|
|
186
|
+
|
|
187
|
+
// 期別結構化摘要(程式整理的事實,沒有 AI 判斷)
|
|
188
|
+
const brief = await od.briefs.latest({ period_type: 'daily', city: '臺北市' }); // 不給 city=全國;brief.available 為 false=還沒產出
|
|
189
|
+
brief.bulletins?.top; // 重點條目(已依授權裁切)
|
|
190
|
+
brief.indicators?.[0]?.prev?.reason_code; // 'comparable' 才可寫成漲跌
|
|
191
|
+
await od.briefs.get({ period_type: 'weekly', period_key: '2026-W39' }); // 指定期別(日 2026-09-28/週 2026-W39/月 2026-09)
|
|
192
|
+
await od.briefs.list({ period_type: 'monthly', limit: 12 }); // 已產出的期別
|
|
193
|
+
await od.briefs.coverage(); // 各視角的來源取得狀況(平台資料狀況,不是公告內容)
|
|
194
|
+
|
|
195
|
+
// 新聞分析報告(AI 整理)與議題
|
|
196
|
+
const r = await od.newsReports.latest({ city: '臺中市' }); // 章節、逐則事件(事實附原文引文)、來源
|
|
197
|
+
r.ai_notice; // 「影響與建議是判斷、不是價格預測…」請原文顯示
|
|
198
|
+
await od.newsReports.get({ period_type: 'daily', period_key: '2026-09-28' });
|
|
199
|
+
await od.newsReports.list({ period_type: 'weekly' });
|
|
200
|
+
await od.newsReports.topics({ city: '臺北市' }); // 進行中的議題與時間軸
|
|
201
|
+
|
|
202
|
+
// 市場快訊的期別清單(既有的 od.marketBriefs(q) 呼叫方式不變)
|
|
203
|
+
await od.marketBriefs.list({ period_type: 'daily', limit: 7 });
|
|
204
|
+
|
|
205
|
+
// 物價與市場指標
|
|
206
|
+
const cpi = await od.stats.cpi({ roc_year: 90, month: 10 }); // 消費者物價總指數(稅務專用)
|
|
207
|
+
cpi.base_period; // 🔴 目前的基期(最新月份=100),請一併保存
|
|
208
|
+
await od.stats.market({ items: ['transfer_count', 'new_housing_loan_rate'], periods: 24 }); // 市場指標序列(由舊到新)
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
地圖類與空間查詢(2.4.0 起;具名型別,GeoJSON 用簡化的 `OdFeatureCollection`):
|
|
212
|
+
|
|
213
|
+
```js
|
|
214
|
+
// 空間查詢:多邊形給 [緯度, 經度](緯度在前!)或 { lat, lng } 的陣列,首尾不同會自動閉合
|
|
215
|
+
const area = [[24.145, 120.630], [24.145, 120.652], [24.163, 120.652], [24.163, 120.630]];
|
|
216
|
+
const s = await od.spatial.lvrSummary({ polygon: area, months: 12 }); // 範圍內實登件數、單價平均/中位數(萬元/坪)、總價(萬元)
|
|
217
|
+
await od.spatial.companies({ polygon: area, include_items: true, limit: 20 }); // 範圍內新設公司家數與資本額(萬元)
|
|
218
|
+
const v = await od.spatial.villages({ polygon: area }); // 範圍涵蓋的村里(代表點落在範圍內才算)
|
|
219
|
+
await od.stats.villages({ codes: v.codes, items: ['population', 'income'] }); // 接著查這些村里的人口與所得
|
|
220
|
+
const g = await od.spatial.villageGeometry({ codes: v.codes }); // 反過來:村里代碼 → 連成一片的範圍多邊形
|
|
221
|
+
await od.spatial.lvrSummary({ polygon: g.polygon }); // g.polygon 可直接再當 polygon 用(頂點 ≤ 300 時)
|
|
222
|
+
const view = { sw_lat: 25.02, sw_lng: 121.50, ne_lat: 25.06, ne_lng: 121.56, zoom: 15 }; // 地圖目前的範圍與縮放
|
|
223
|
+
await od.spatial.boundaries({ ...view, level: 'village' }); // 村里界線 GeoJSON(地圖底層)
|
|
224
|
+
const loc = await od.spatial.lookup({ level: 'area', names: [{ city: '臺北市', district: '信義區' }] });
|
|
225
|
+
map.fitBounds([[loc.items[0].bbox.south, loc.items[0].bbox.west], [loc.items[0].bbox.north, loc.items[0].bbox.east]]); // 只用來移鏡頭
|
|
226
|
+
|
|
227
|
+
// 土地使用分區(單點請用 od.hazards() 的 zoning)
|
|
228
|
+
await od.zoning.batch([{ lat: 25.048, lng: 121.534 }, { lat: 23.588365, lng: 119.582011 }]); // 最多 20 個座標,整次算一次
|
|
229
|
+
await od.zoning.geojson({ ...view, zoom: 16 }); // 分區多邊形(zoom ≥ 13、範圍 ≤ 0.01 平方度)
|
|
230
|
+
const zt = await od.zoning.tiles(); // 非都市土地分區的官方 WMTS 圖磚
|
|
231
|
+
|
|
232
|
+
// 地籍(只回位置、面積、地段地號;地號定位請用 od.address.convert())
|
|
233
|
+
await od.cadastre.sections({ city: '臺中市', keyword: '繼光' }); // 地段清單與段名搜尋
|
|
234
|
+
const sec = await od.cadastre.reversePoint({ lat: 24.153282, lng: 120.634413 }); // 座標 → 縣市、鄉鎮、村里、地段
|
|
235
|
+
await od.cadastre.landInfo({ section_code: sec.section_code, land_no: '123-4' }); // 多數回 available: false(只讀已累積的資料)
|
|
236
|
+
await od.cadastre.locateSources(); // 已同步縣市宗地資料的縣市
|
|
237
|
+
const ct = await od.cadastre.tiles(); // 電子地圖、航照、地段界線圖磚
|
|
238
|
+
|
|
239
|
+
// 地圖圖層(熱力與 POI 要 zoom ≥ 10、範圍 ≤ 1 平方度)
|
|
240
|
+
const h = await od.layers.heat.deals({ ...view, mode: 'unit_price' }); // 成交點;h.value_unit='萬元/坪'、h.weight 說明權重
|
|
241
|
+
await od.layers.heat.amenities({ ...view, types: ['convenience_store', 'clinic'] });
|
|
242
|
+
await od.layers.heat.transport({ ...view, types: ['metro'] });
|
|
243
|
+
await od.layers.heat.population({ ...view, mode: 'density_km' }); // 村里人口密度(人/平方公里)
|
|
244
|
+
await od.layers.heat.hazards({ ...view, type: 'flood' }); // 潛勢代表點,權重是風險等級 1~4
|
|
245
|
+
await od.layers.hazardZones({ ...view, types: ['flood', 'liquefaction'] }); // 潛勢範圍 GeoJSON
|
|
246
|
+
await od.layers.poi({ ...view, types: ['convenience_store'], limit: 300 }); // marker 用的點位(名稱、地址)
|
|
247
|
+
await od.layers.choropleth({ ...view, zoom: 14, metric: 'elder_pct' }); // 面量圖 GeoJSON(zoom ≥ 8)
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
同業裁罰、登記工廠、政府機關辦公日曆(2.5.0 起;具名型別):
|
|
251
|
+
|
|
252
|
+
```js
|
|
253
|
+
// 同業裁罰名單(臺中市;受處分人已由來源遮罩,見下方「個資使用限制」)
|
|
254
|
+
const pen = await od.licenses.penalties({ q: '第29條' }); // 新到舊,關鍵字比對受處分人或法條
|
|
255
|
+
pen.privacy_notice; // 🔴 個資使用限制,請顯示給使用者
|
|
256
|
+
|
|
257
|
+
// 登記工廠(嫌惡設施參考;查無不代表附近沒有工廠)
|
|
258
|
+
const f = await od.factories.nearby({ address: '臺中市南屯區惠文路1號', radius: 2000 }); // 半徑內最多 100 家,附 distance_m
|
|
259
|
+
f.center_city_covered; // false=這個縣市的工廠座標還沒建檔,查無幾乎沒有參考價值
|
|
260
|
+
await od.factories.search({ tax_id: '16785180' }); // 名錄查詢(沒有座標的工廠也查得到)
|
|
261
|
+
|
|
262
|
+
// 政府行政機關辦公日曆
|
|
263
|
+
const cal = await od.calendar.holidays({ from: '2026-01-01', to: '2026-12-31' }); // 最長 366 天(含頭尾)
|
|
264
|
+
cal.days.filter((d) => d.is_national_holiday).map((d) => `${d.date} ${d.holiday_name}`); // 國定假日(is_day_off 含一般週末)
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
地址查座標(2.6.0 起;具名型別):
|
|
268
|
+
|
|
269
|
+
```js
|
|
270
|
+
// 先用 convert()(只查官方門牌、不花平台費用),找不到再用 geocode()(查不到門牌時改查付費圖資)
|
|
271
|
+
const g = await od.address.geocode({ address: '臺中市西屯區至善路96號之3五樓' });
|
|
272
|
+
if (g.found) {
|
|
273
|
+
g.lat; g.lng;
|
|
274
|
+
g.is_exact_doorplate; // false=內插、路段中心或精度不明:只適合顯示
|
|
275
|
+
g.precision; // 「門牌」「門牌內插」「路段中心」…
|
|
276
|
+
}
|
|
277
|
+
g.status_code; // found/no_result(明確查無)/low_quality(只到行政區,不給座標)
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
- 🔴 **同業名冊不提供,裁罰名單有個資使用限制**(`licenses.penalties()`):政府的同業名冊(經紀業、地政士、租賃住宅服務業、估價師)含**未遮罩**的自然人資料——經紀業與租賃住宅服務業的負責人、地政士姓名,可用姓名搜尋並取得事務所地址,所以平台不開放名冊查詢(沒有 `licenses.search()`)。裁罰名單照常提供:
|
|
281
|
+
- 只有臺中市,受處分人姓名由來源遮罩(例如「鄭O昀」),**不要嘗試還原或與其他資料比對出本人**。查無不代表沒有受過裁罰。
|
|
282
|
+
- **只能用於查核同業等正當目的**;不得蒐集、建檔、比對歸戶、轉售或另作行銷使用,並依《個人資料保護法》處理。每個回應都有 `privacy_notice`,請顯示給使用者。
|
|
283
|
+
- **地址查座標會花平台費用**(`address.geocode()`):先查官方門牌,查不到才以平台額度查商用圖資。請先用 `address.convert()`(只查官方門牌),找不到再用 `geocode()`;**不要對同一個地址重複呼叫**,查過的結果請自行保存。
|
|
284
|
+
- `precision_code` 不是 `doorplate`(`interpolated` 門牌內插、`road` 路段中心、`unknown` 精度不明)時座標只是近似位置,只適合在地圖上顯示,不要拿來算距離或判斷地號、學區;`is_exact_doorplate` 為 `true` 才是精確門牌。
|
|
285
|
+
- `status_code`:`found` 有座標;`no_result` 是明確查無(短期內重查結果相同);`low_quality` 是只能定位到行政區或縣市中心,**不給座標**。三種都是成功查詢、照常扣點;上游暫時失敗丟 `DATA_UNAVAILABLE`(503,不扣點),稍後再試。
|
|
286
|
+
- `source_code`:`official_doorplate`(官方門牌)、`external_map`(外部圖資)、`legacy_cache`(舊快取);外部圖資的座標不是政府開放資料,`attribution` 會說明。
|
|
287
|
+
- **登記工廠的座標覆蓋有限**(`factories.*`):座標由門牌比對產生,只有 `coverage.geocoded_cities` 的縣市有系統性的座標(也不是 100%,看 `coverage.by_city`),其他縣市的工廠在名錄查得到但多半沒有座標。**`factories.nearby()` 查無僅代表圖資未收錄,不等於附近沒有工廠**——`disclaimer` 請顯示給使用者,不要寫成「附近沒有工廠」。這是經濟部登記工廠名錄,和 `nearby.amenities()` 嫌惡設施裡的「工廠」(商用圖資點位)不同源,兩者不要合併計數。
|
|
288
|
+
- **辦公日曆**(`calendar.holidays()`):`is_day_off` 是「放假」(**含一般週末**);國定假日、補假、調整放假看 `is_national_holiday` 或 `holiday_name`;`is_makeup_workday` 是補行上班日(週末但要上班)。這是行政機關的日曆,民間企業依各自規定。次年度的日曆通常前一年 6~7 月才公告,還沒公告的年度列在 `missing_years`;有些年度沒有補班日是正常的。
|
|
289
|
+
- 🔴 **版權裁切(政策公告、期別摘要、新聞分析報告都適用)**:每則公告或報導有 `usage_policy_code`,平台依來源授權裁掉內容,**App 不要自己補**:
|
|
290
|
+
- `open`(政府資料):標題、摘要、內文(`body`,≤ 6,000 字)、內文節錄(`body_excerpt`)、附件都有。
|
|
291
|
+
- `summary`(住展、鉅亨、ETtoday、壹蘋等媒體):只有標題與來源摘要(`summary`);沒有內文與附件。
|
|
292
|
+
- `title_only`(經濟日報、中央社、自由時報、同業公會等):**只有標題、機關、日期、連結**;`summary` 是 `null`。
|
|
293
|
+
- 來源回報的授權方式認不得時,一律以最嚴的 `title_only` 處理。
|
|
294
|
+
- `content_withheld: true` 表示有內容因授權沒有提供,`usage_policy` 是給人看的中文原因;請顯示原文連結(`url`),不要拿標題請 AI 編寫內文。`bulletins.documents()` 對非政府公告一律回空陣列。
|
|
295
|
+
- 新聞分析報告的事實附原文逐字引文(`events[].facts[].quotes`):出自不能提供的內容時 `quote` 是 `null`、`quote_withheld: true`,只顯示來源與連結即可;`extraction` 標明引文出處,「附件(掃描頁經 AI 辨識,可能看錯)」的數字請以原始檔案為準。
|
|
296
|
+
- **查無與還沒產出是成功查詢**:`briefs.latest()`、`briefs.get()`、`newsReports.latest()`、`newsReports.get()` 在當期還沒產出或期別不存在時回 `available: false`(附 `message`,照常扣點);`bulletins.get()` 查無時 `item` 是 `null`。期別鍵格式和 `period_type` 不符時丟 `INVALID_REQUEST`(不扣點)。
|
|
297
|
+
- **期別摘要不是 AI 分析**:`briefs` 只做分類、排序、計數與指標比較;`period_key` 是涵蓋期,以「首次收錄時間」切窗(不是發布日)。指標的 `prev`/`yoy` 只有 `reason_code` 為 `comparable` 時可寫成漲跌,`level_only`(利率、比率)只看百分點差,其他都不可寫成漲跌。`coverage.status_code` 不是 `complete` 時,「沒有公告」可能是來源缺漏。
|
|
298
|
+
- **新聞分析報告是 AI 整理**:影響與建議是判斷、不是價格預測,`ai_notice` 請原文顯示。`generation_state_code` 為 `rules_only` 時 AI 還沒分析完、只列公告標題;`partial` 表示部分新聞只有標題;`confidence_code` 為 `degraded` 表示本期部分來源沒有取得。要連同期別摘要快照與議題一次拿,用 `od.marketBriefs()`。
|
|
299
|
+
- `bulletins.list()` 預設不含回填的舊條目(查歷史帶 `include_backfill: true`);`city` 是發布機關所在縣市,`mentions` 與回應的 `mentioned_cities` 只代表內文提及、不代表適用。
|
|
300
|
+
- **物價指數的基期每月改變**:`stats.cpi()` 是主計總處「各年月為基期」的稅務專用指數,`base_period`(最新月份)恆為 100,其他月份是「從該月到基期」的物價漲幅;每發布一個新月份整張表重算,同一個月份不同時間查到的值會不同,保存數字時請一併保存 `base_period`。期別是民國年(`period: '090-10'`)。
|
|
301
|
+
- **市場指標**:`stats.market()` 的期別是西元(月 `YYYY-MM`、季 `YYYY-Qn`);`level_only: true` 的指標(利率、比率、景氣分數)不可套成長率;`points[].provisional: true` 是初值(預售屋備查戶數的近三個月),不可寫成漲跌。不帶 `city` 是全國;帶 `city` 時只有分縣市的指標有數字(`regions` 標明有哪些地區,住宅價格指數只有全國與六都),其餘回空序列並附 `message`。
|
|
302
|
+
- **實價登錄**的金額欄位名都帶單位:`*_wan`=萬元、`*_wan_per_ping`=萬元/坪、`*_ping`=坪、`*_twd`=元。每個回應都有 `unit_price_basis`(單價口徑)與 `notice`(口徑與限制的說明),轉述數字時請一併帶出。
|
|
303
|
+
- **單價是車位拆算後的值**:`unit_price_note` 是「車位價推估」表示車位價以同區同年行情推估扣除;是「含車位未拆算」表示無法拆算、主值就是政府原始值。統計類回應的 `parking_estimated_count`(推估筆數)與 `parking_unpriced_count`(無法拆算、不計入單價的筆數)請顯示出來。
|
|
304
|
+
- **租賃不是房價**:`transaction_type: 'rent'` 時金額是月租金(`monthly_rent_twd`、`avg_monthly_rent_twd`,元),單價是每坪月租(`*_rent_per_ping_month_twd`,元/坪/月),回應不會有 `total_price_wan`、`unit_price_wan_per_ping` 這類欄位。
|
|
305
|
+
- `lvr.deal(id)` 的 id 目前只有 `lvr.similar()` 的結果會給;`lvr.deals()`、`nearby.deals()` 的逐筆結果沒有 id。
|
|
306
|
+
- `lvr.summary()`、`lvr.statsByArea()`、`lvr.monthlyTrend()` 給的是**平均值**,會受極端值影響;要中位數與 p25~p75 價格帶用 `lvr.marketContext()`。同一個條件下各方法的件數口徑不同(`summary().count` 是全樣本,`statsByArea()`、`monthlyTrend()` 的 `transaction_count` 只算有拆算單價的成交),不要互相對帳。
|
|
307
|
+
- `lvr.summary()` 不提供屋齡篩選(上游帶屋齡條件時平均值不正確);總價的篩選參數是 `total_price_min_wan`/`total_price_max_wan`(**萬元**,和 `lvr.deals()` 的 `total_price_min`〔元〕不同)。`keyword` 沒有搭配 `district` 時期間最長 24 個月,超過會自動縮短(`period.clamped`)。
|
|
308
|
+
- `lvr.statsByArea()`、`lvr.rentalStats()` 的 `building_type` 要寫**政府登錄的全名**(例如 `'住宅大樓(11層含以上有電梯)'`),只寫「住宅大樓」會查無資料;其他方法的 `building_type` 是關鍵字、可逗號複選。`statsByArea()` 有帶 `building_type` 時不提供漲跌幅(`price_change_pct` 一律 `null`)。
|
|
309
|
+
- `lvr.monthlyTrend()` 的 `is_partial: true` 表示該月件數明顯偏少(實價登錄揭露有 1~2 個月的時間差),畫圖時請用虛線或註記,不要解讀成行情大漲大跌。
|
|
310
|
+
- `lvr.rentalStats()` 的每坪月租是「月租金 ÷ 建物面積」,**沒有車位拆算**,和 `lvr.deal()`、`lvr.summary()` 租賃的拆算後每坪月租不能直接比。
|
|
311
|
+
- `lvr.monthlyByRegion()` 是預先算好的彙總(`computed_at` 是計算時間),**不分交易標的**(土地、車位的成交也算在內),件數和其他方法對不起來;不帶 `city` 時回全國每個行政區,期間最長 24 個月(帶 `city` 最長 120 個月)。彙總還沒建立時會丟 `DATA_UNAVAILABLE`。
|
|
312
|
+
- **多邊形怎麼給**(`spatial.*`):頂點是 `[緯度, 經度]`(**緯度在前**,和 GeoJSON 的 `[經度, 緯度]` 相反)或 `{ lat, lng }`,SDK 會轉成 `polygon=緯度,經度;…` 一個查詢參數;也可以直接給這個字串。3~300 個頂點、要在台灣範圍、邊不可交叉、面積上限 5,000 平方公里,不合規定丟 `INVALID_REQUEST`(不扣點)。
|
|
313
|
+
- 要「以某個點為中心、半徑 N 公尺」的範圍,請自己算出圓的近似多邊形再傳,例如 32 個頂點:`Array.from({ length: 32 }, (_, i) => { const t = (2 * Math.PI * i) / 32; return [lat + (r / 111320) * Math.sin(t), lng + (r / (111320 * Math.cos((lat * Math.PI) / 180))) * Math.cos(t)]; })`(`r` 是公尺)。
|
|
314
|
+
- 從地圖套件畫出來的 GeoJSON 要先把每個 `[經度, 緯度]` 對調成 `[緯度, 經度]`;頂點太多時先簡化(例如 turf 的 `simplify`)。
|
|
315
|
+
- `spatial.villageGeometry()` 所選的里沒有連成一片、代碼查無或範圍過於複雜時丟 `INVALID_REQUEST`,`err.message` 是給使用者的修正指引(例如「所選的里沒有連成一整片(分成 2 塊:…)」),請原樣顯示。
|
|
316
|
+
- **地圖類回應是 GeoJSON**(`spatial.boundaries()`、`zoning.geojson()`、`layers.hazardZones()`、`layers.choropleth()`):`type: 'FeatureCollection'`,座標是 `[經度, 緯度]`、精度和上游相同,可以直接丟給 Leaflet/Mapbox/Google 地圖;`properties` 只留畫圖需要的欄位。`truncated: true` 表示超過上限已截斷,請提示使用者放大地圖。幾何已依 zoom 簡化,只適合畫圖,不可用來判定地界。
|
|
317
|
+
- **地圖範圍防護**:每個方法都要 `sw_lat`、`sw_lng`、`ne_lat`、`ne_lng`、`zoom`;東北角要大於西南角。熱力、災害面、POI 要 zoom ≥ 10、範圍 ≤ 1 平方度;面量圖 zoom ≥ 8、≤ 1 平方度;分區向量 zoom ≥ 13、≤ 0.01 平方度;行政區界線依層級(村里 1、鄉鎮市區 4、縣市 25 平方度)。不合規定丟 `INVALID_REQUEST`(不扣點)。
|
|
318
|
+
- **熱力點**(`layers.heat.*`)是原始點,沒有抽樣也沒有正規化(最多 20,000 點,`truncated` 標明是否達上限);色階請依 `value` 自己正規化。`value_unit` 是單位(成交單價:萬元/坪,租賃為元/坪/月;總價:萬元,租賃為元/月;人口:人/平方公里或人;災害:風險等級 1~4),`weight` 是權重的中文說明,請寫在圖例;密度類的 `value` 是 `null`、每點權重相同。
|
|
319
|
+
- **面量圖**的 `value` 是中性數值:請用單色系連續色階(不要用紅綠對比)、分段建議用分位數;`null` 請畫「無資料」,不可內插或用鄰區補。`unit`、`level`(村里或鄉鎮市區,由 zoom 決定;實價登錄兩項固定鄉鎮級)、`period` 請照實標在圖例。
|
|
320
|
+
- **類型代碼**(`types`):交通 `metro`、`train`、`hsr`、`bus_stop`、`youbike`(`layers.heat.transport()`);其餘 POI(`layers.heat.amenities()`、`layers.poi()`)是 `nearby.amenities()` 用的同一組代碼,例如 `convenience_store`、`supermarket`、`hospital`、`clinic`、`park`、`bank`、`gas_station`、`temple`;回應的 `category`/`types` 是中文名稱。
|
|
321
|
+
- **圖磚**(`zoning.tiles()`、`cadastre.tiles()`)是內政部國土測繪中心的公開 WMTS(`{z}/{y}/{x}`,GoogleMapsCompatible),App 直接向國土測繪中心取圖、不經過平台也不計點;畫面上**必須顯示 `attribution`**,並自行遵守國土測繪中心的圖資使用規定(不得大量下載、批次抓取或轉存)。需授權的圖層(例如含地號的地籍圖)只列在 `unavailable`、不給網址,請不要自行開啟。
|
|
322
|
+
- **分區批次與分區向量**:都市計畫分區只有臺北、新北、高雄;`status_code` 不是 `covered` 或 `features` 是空的都代表查不到,**查不到不等於沒有使用限制**;`approximate: true` 是取最近的分區,不是確定值。建蔽率/容積率沒有就是 `null`,請顯示「—」。`disclaimer` 請顯示給使用者。
|
|
323
|
+
- **地籍**:`cadastre.landInfo()` 只讀平台已累積的宗地資料,多數地號回 `available: false`(照常扣點、不代表地號不存在);要即時以地號定位用 `address.convert()`。`cadastre.sections()` 的地段主檔尚未涵蓋全部縣市;`cadastre.reversePoint()` 即時查國土測繪中心,忙碌時丟 `DATA_UNAVAILABLE`(不扣點)。地籍只回位置、面積、地段地號,沒有任何權屬資料。
|
|
324
|
+
- **行政區定位**(`spatial.lookup()`)回的 `point`/`bbox` 只能拿來移動地圖鏡頭,**不是資料篩選**:矩形會包到鄰近行政區、也會切掉邊角,查資料請仍用行政區條件。名稱對到不只一個(例如中正區在臺北市與基隆市都有)時列在 `unresolved`(`reason_code: 'ambiguous'`),不會猜。
|
|
325
|
+
- **土地使用分區**(`hazards()` 回應的 `zoning`)不是全國都有圖資:`zoning.status` 是 `covered` 才有分區名;`urban_not_covered`、`no_data`、`unavailable` 都代表查不到,**查不到不等於沒有使用限制**。`zoning.approximate` 為 `true` 表示取最近的分區,不是確定值。
|
|
326
|
+
- **地號定位**只收錄部分縣市的地籍資料,查無時回應的 `parcel` 是 `null`(不是錯誤);只回位置與面積,沒有任何權屬資料。
|
|
327
|
+
- **比較案例**不提供門牌,只代表周邊條件相近,不代表同一社區。
|
|
328
|
+
- **房屋稅率**只有「非自住住家用房屋」一類;`rows` 是空陣列表示查無該縣市,不要拿其他縣市的數字代替。
|
|
329
|
+
- **社區**的名單不完整(來自預售成交聚合、公寓大廈報備清冊與民間社區清單,老社區可能沒有收錄):查不到不代表社區不存在,請做成「建議」而不是封閉選單。
|
|
330
|
+
- **價格可能沒有**:`price` 是該建案「預售成交歷史」的統計(已扣車位、萬元/坪),不是目前的中古行情,也不能和含車位的開價直接比。`price.status_code` 是 `available` 才有數字;樣本少於 5 筆(`insufficient_sample`)或清冊建檔的社區(`no_data`)價格是 `null`,把 `price.status` 的中文說明顯示出來即可。
|
|
331
|
+
- `communities.match()` 的 `level_code` 是 `fuzzy`(`reliable: false`)時,**結果不可當成正確答案**——模糊比對對中文名稱幾乎是隨機的;請讓使用者自己確認,或改用 `suggest()`。`match()` 不含價格,要價格以 `id` 查 `get()`。
|
|
332
|
+
- `total_units`、`builder`、`build_year_range` 為 `null` 表示「未查得」,不要用其他欄位推算;`estimated_build_year` 是民間清單屋齡的推估值,不可和 `build_year_range`(官方紀錄)混用。
|
|
333
|
+
- `get()` 回的 `is_active: false` 表示來源最新一期沒有收錄(歷史資料),不是社區不存在。`public_profile` 裡 `building` 是整個社區的數字、`use_permits` 是逐張使用執照自己的數字(一張使照的戶數不等於社區總戶數)。
|
|
334
|
+
- **學校不是學區**:資料是學校的校地位置,不是學區劃分範圍,**不能用來回答「這個地址讀哪一所學校」**。每個回應都有 `disclaimer`(「這是鄰近學校,不是學區劃分;實際學區以各縣市教育局公告為準」),請顯示給使用者。
|
|
335
|
+
- `schools.nearby()` 的 `match_code`:`on_campus`=位置落在校地內、`nearest`=2 公里內最近的學校(最多 5 所,`distance_m` 是直線距離)、`none`=2 公里內沒有。座標要在台灣範圍內。
|
|
336
|
+
- `schools.nearbyBatch()` 只判斷座標是否**落在校地內**,不會找附近的學校——一般住宅的座標結果會是空的;要找附近的學校請逐點用 `nearby()`。
|
|
337
|
+
- `levels`(國小/國中/高中職)是依校名判斷的;`search()` 查不到校地位置尚未建檔的學校。
|
|
338
|
+
- **人口與村里統計**:`population.village()` 的 `elder_pct` 是老年人口占比(65 歲以上 ÷ 總人口);`stats.villages()` 與 `area.series()` 的 `aging_index` 是老化指數(老年 ÷ 幼年 × 100),兩者不同。
|
|
339
|
+
- 所得單位是**千元/年**(欄位名以 `_thousand_twd` 結尾,與 `area.profile()` 相同);年度是**民國年字串**(例如 `'111'`),月份是西元 `YYYY-MM`。
|
|
340
|
+
- `area.series()` 給座標或地址時以**村里**為單位,給 `city`+`district` 時以**鄉鎮市區**為單位(`level` 會標明);鄉鎮市區層級的所得是「各村里中位數的中位數」,不要寫成家庭所得中位數。`net_migration_estimated` 是估算值,呈現時要標「估算」。序列的 `truncated` 為 `true` 表示實際期數超過這次回傳的上限。
|
|
341
|
+
- **門牌建議**是地址**開頭**比對,不是關鍵字搜尋(要從縣市或行政區打起)。門牌資料只收錄部分縣市(回應的 `covered_cities`),未收錄縣市查不到**不代表地址不存在**,不要因此擋下使用者的輸入。
|
|
342
|
+
- 需要位置的方法都可以給 `address`(完整門牌)或 `lat`+`lng`;門牌未涵蓋的縣市或查無門牌時會丟 `INVALID_REQUEST`(不扣點),請改帶座標。
|
|
343
|
+
- **判決**一律是去識別化版本(當事人以甲、乙代稱);`city` 是審理法院所在縣市,不是不動產所在地。回應的 `disclaimer` 請顯示給使用者,引用時標示法院與案號。
|
|
344
|
+
|
|
345
|
+
- 參數一律用**中文縣市名**(台/臺皆可)、價格用**萬元/坪**、面積用**坪**。單價一律是車位拆算後的值(推估的會註記;`lvr.rentalStats()` 的每坪月租例外,見上)。與 AI 研究所 MCP 共通的資源,參數與 MCP 的開放資料工具相同。
|
|
346
|
+
- **查無資料是成功查詢**(回空陣列或 `null`,`message` 說明原因,照常扣點),不會丟錯。
|
|
347
|
+
- 每次查詢扣 1 點(翻頁每頁各算一次),失敗不扣。
|
|
348
|
+
- 每位會員每分鐘最多 10 次(跨 App 合計)、每個 App 每分鐘最多 60 次;超過回 `DATA_UNAVAILABLE`,`err.retryAfterSeconds` 是建議等待秒數。
|
|
349
|
+
- 上架時要勾選「使用平台房市資料」才能用。
|
|
350
|
+
|
|
351
|
+
## 5. 工作憑證(背景工作)
|
|
352
|
+
|
|
353
|
+
會員離開頁面後還要繼續跑的工作(產生報告、批次處理),在會員在場時先開一個工作,預佔點數換一張憑證;背景工作憑它在預佔額度內使用平台 AI 與房市資料。
|
|
354
|
+
|
|
355
|
+
```js
|
|
356
|
+
// 會員在場時(有 req.academy)
|
|
357
|
+
const job = await academy.jobs.open(req, { maxPoints: 80, ttlSeconds: 1200, purpose: '月報生成' });
|
|
358
|
+
await db.save({ jobToken: job.token }); // 憑證可以存進資料庫
|
|
359
|
+
|
|
360
|
+
// 背景工作
|
|
361
|
+
const j = academy.jobs.resume(token);
|
|
362
|
+
const r = await academy.ai(j).chat.completions.create({ model: 'smart', messages });
|
|
363
|
+
await academy.od(j).lvr.marketContext({ city: '臺北市' });
|
|
364
|
+
await j.close(); // 實扣用掉的、釋放其餘;沒關也會在到期時自動結清
|
|
365
|
+
```
|
|
366
|
+
|
|
367
|
+
- `maxPoints` 上限 500、`ttlSeconds` 上限 1,800;每位會員在同一個 App 同時最多 2 個進行中的工作(超過回 `JOB_LIMIT_EXCEEDED`)。
|
|
368
|
+
- 預佔期間這些點數不能做別的用途,會員在「我的點數」看得到「處理中預佔:工具名:用途」。
|
|
369
|
+
- 用完預佔額度回 `JOB_BUDGET_EXCEEDED`;過期或已結束回 `JOB_EXPIRED`。
|
|
370
|
+
- 沒有會員在場啟動的排程工作(例如每天自動產生內容)**不能**用平台 AI,只能用你自備的金鑰。
|
|
371
|
+
|
|
372
|
+
## 6. 點數與網址
|
|
373
|
+
|
|
374
|
+
```js
|
|
375
|
+
await academy.getQuota(req);
|
|
376
|
+
// { tier, points_remaining, points_held, reset_at, dev_quota_remaining? } dev_quota_remaining 只在測試環境與開發模式回傳
|
|
377
|
+
|
|
378
|
+
academy.urls.upgrade // 方案頁(點數不足時帶會員去這裡)
|
|
379
|
+
academy.urls.points // 我的點數
|
|
380
|
+
academy.urls.subscribe // 我的訂閱
|
|
381
|
+
academy.urls.logout // 登出這個 App(同網域相對路徑)
|
|
382
|
+
```
|
|
383
|
+
|
|
384
|
+
## 7. 瀏覽器端(純前端 App)
|
|
385
|
+
|
|
386
|
+
```js
|
|
387
|
+
import { academyBrowser, AcademyError } from '@agentgo-tw/app-sdk/browser';
|
|
388
|
+
|
|
389
|
+
const me = await academyBrowser.me(); // 打同網域 /__academy/me,同時向平台握手(純前端 App 的上架自檢以此為準)
|
|
390
|
+
if (me === null) {
|
|
391
|
+
// 尚未啟用入口關卡(例如還沒按「啟用」的正式環境):維持原本的行為
|
|
392
|
+
}
|
|
393
|
+
|
|
394
|
+
const ai = academyBrowser.ai(); // 對話(含串流)、圖片
|
|
395
|
+
const od = academyBrowser.od(); // 房市資料
|
|
396
|
+
|
|
397
|
+
try {
|
|
398
|
+
await ai.chat.completions.create({ model: 'fast', messages });
|
|
399
|
+
} catch (e) {
|
|
400
|
+
if (!academyBrowser.redirectFor(e)) alert(e.message); // 未登入、沒有訂閱、點數不足 → 導到平台頁面
|
|
401
|
+
}
|
|
402
|
+
```
|
|
403
|
+
|
|
404
|
+
瀏覽器端以 App cookie 驗身分,請求一律同網域;平台另做來源檢查,別的網站拿不到會員的點數。
|
|
405
|
+
|
|
406
|
+
## 8. 擴充功能、桌面與手機程式(會員委任憑證)
|
|
407
|
+
|
|
408
|
+
不是「會員在瀏覽器開 App 網頁」的程式(Chrome 擴充功能、桌面或手機程式)要代表會員呼叫你的 App 時,**不要自己發憑證,也不要把那些路徑登記成公開路徑**。在上架頁的「程式用戶端」宣告一個會員用戶端(代號、種類、轉址網址、用途),用戶端就能經平台授權拿到憑證,之後的請求照樣經入口關卡——訂閱、暫停、撤回同意都由平台把關,你的後端一樣從 `req.academy` 取得身分。
|
|
409
|
+
|
|
410
|
+
**用戶端(以 Chrome 擴充功能的背景程式為例)**
|
|
411
|
+
|
|
412
|
+
```ts
|
|
413
|
+
import { createAcademyClient } from '@agentgo-tw/app-sdk/client';
|
|
414
|
+
|
|
415
|
+
const academy = createAcademyClient({
|
|
416
|
+
appUrl: 'https://my-tool.app.agentgo.tw', // 測試環境:https://my-tool.test.app.agentgo.tw
|
|
417
|
+
client: 'ext', // 上架頁宣告的用戶端代號
|
|
418
|
+
redirectUri: chrome.identity.getRedirectURL('academy'), // 要與上架頁登記的轉址網址完全相同
|
|
419
|
+
storage: {
|
|
420
|
+
get: async (k) => (await chrome.storage.local.get(k))[k] ?? null,
|
|
421
|
+
set: (k, v) => chrome.storage.local.set({ [k]: v }),
|
|
422
|
+
remove: (k) => chrome.storage.local.remove(k),
|
|
423
|
+
},
|
|
424
|
+
});
|
|
425
|
+
|
|
426
|
+
// 連結帳號:開平台的授權頁,會員按「允許」後換取憑證
|
|
427
|
+
async function connect() {
|
|
428
|
+
const url = await academy.authorizeUrl();
|
|
429
|
+
const back = await chrome.identity.launchWebAuthFlow({ url, interactive: true });
|
|
430
|
+
await academy.handleRedirect(back);
|
|
431
|
+
}
|
|
432
|
+
|
|
433
|
+
// 呼叫自己的 App:自動帶憑證,快過期時自動更新
|
|
434
|
+
const res = await academy.fetch('/api/ext/posts');
|
|
435
|
+
```
|
|
436
|
+
|
|
437
|
+
- `academy.fetch()` 丟出 `AcademyError`(`code: 'TOKEN_INVALID'`)代表尚未連結或授權已失效(會員移除了裝置、撤回同意、30 天沒用),請再呼叫一次 `connect()`。
|
|
438
|
+
- 回應是 403 時看 body 的 `code`:`SUBSCRIPTION_REQUIRED`(附 `subscribe_url`,請會員去訂閱;續訂後不必重新連結)或 `APP_UNAVAILABLE`。
|
|
439
|
+
- 請求要從**背景程式**發出,並在 `manifest.json` 的 `host_permissions` 加上 App 的網域;入口關卡不處理跨來源預檢,內容腳本直接發出的請求會被瀏覽器擋下。
|
|
440
|
+
- 存取憑證 1 小時、自動更新;連續 30 天沒有使用要重新連結。`academy.signOut()` 會向平台撤銷這個裝置。
|
|
441
|
+
- 桌面程式的轉址網址用 `http://127.0.0.1:<埠>/…`,手機程式用自訂 scheme(例如 `tw.agentgo.mytool://callback`)。
|
|
442
|
+
|
|
443
|
+
**你的後端**不必為用戶端另寫驗證,路徑也不用登記成公開路徑:
|
|
444
|
+
|
|
445
|
+
```ts
|
|
446
|
+
app.get('/api/ext/posts', (req, res) => {
|
|
447
|
+
if (!req.academy) return res.status(401).json({ code: 'LOGIN_REQUIRED' });
|
|
448
|
+
const { user, client } = req.academy; // client:{ key: 'ext', kind: 'BROWSER_EXTENSION', grant } ;網頁進來的請求為 null
|
|
449
|
+
res.json(listPosts(user.uuid));
|
|
450
|
+
});
|
|
451
|
+
```
|
|
452
|
+
|
|
453
|
+
## 9. 自己的外部主機(服務憑證與會員權益查詢)
|
|
454
|
+
|
|
455
|
+
你自己的其他主機(另一個雲端服務、背景工作主機)要呼叫 App 時用**服務憑證**:在上架頁宣告服務(名稱、用途、資料送往哪裡),再替它建立憑證(`aca_svc_…`,只顯示一次)。外部主機帶 `Authorization: Bearer aca_svc_…` 呼叫 App 的網址即可,入口關卡驗過才會放行。
|
|
456
|
+
|
|
457
|
+
服務憑證的請求**沒有會員身分**:`req.academy` 是 null,服務身分在 `req.academyService`。請求內容若帶了會員編號,處理那位會員的資料之前,先向平台確認他現在能不能使用:
|
|
458
|
+
|
|
459
|
+
```ts
|
|
460
|
+
app.post('/api/sso/:tenant/check', async (req, res) => {
|
|
461
|
+
const service = req.academyService; // { key, name, tokenId, env };不是服務憑證的請求為 null
|
|
462
|
+
if (service?.key !== 'sso-check') return res.status(403).end();
|
|
463
|
+
|
|
464
|
+
const m = await academy.members.entitlement(req.body.userUuid);
|
|
465
|
+
if (!m.active) return res.json({ allowed: false, reason: m.reason }); // NOT_FOUND | SUBSCRIPTION_REQUIRED | APP_UNAVAILABLE
|
|
466
|
+
res.json({ allowed: true, name: m.user.name });
|
|
467
|
+
});
|
|
468
|
+
```
|
|
469
|
+
|
|
470
|
+
- `members.entitlement()` 對查無此人、帳號停用、沒有同意過這個工具的會員一律回 `NOT_FOUND`,不會透露會員是否存在。
|
|
471
|
+
- 服務憑證可以在上架頁限定路徑前綴、設定到期日,並隨時作廢(最長 60 秒內生效)。工具被暫停或下架時,服務憑證的請求同樣被擋下。
|
|
472
|
+
- 服務憑證的請求不能直接使用平台 AI 與房市資料。要在背景工作裡代表會員使用,請在會員在場時開**工作憑證**(第 5 節),把 `job.token` 存進工作資料交給背景主機。
|
|
473
|
+
- Next.js 與其他 fetch 框架用 `await academy.serviceFromRequest(request)`。
|
|
474
|
+
|
|
475
|
+
## 10. 本機開發模式
|
|
476
|
+
|
|
477
|
+
在自己電腦上設:
|
|
478
|
+
|
|
479
|
+
```bash
|
|
480
|
+
ACADEMY_DEV_MODE=1
|
|
481
|
+
ACADEMY_DEV_KEY=adk_… # 在上架頁「個人開發金鑰」產生
|
|
482
|
+
ACADEMY_BASE_URL=https://agentgo.tw
|
|
483
|
+
ACADEMY_DEV_USER=me@example.com # 可省略
|
|
484
|
+
```
|
|
485
|
+
|
|
486
|
+
- SDK 不驗章,`req.academy` 一律是假身分(`env: 'test'`、`entitlement.kind: 'OWNER_TEST'`)。
|
|
487
|
+
- 平台 AI、房市資料與工作憑證改帶開發金鑰,先扣你的**開發額度**(每月 200 點),用完扣你本人的月點數。
|
|
488
|
+
- **防呆**:跑在平台上(有 `ACADEMY_ENV`)時,SDK 一律忽略 `ACADEMY_DEV_MODE` 並在啟動時印出警告;不會因為你把開發設定一起部署上去就繞過驗證。
|
|
489
|
+
|
|
490
|
+
要在本機測試服務憑證的路徑:設 `ACADEMY_DEV_SERVICE=<服務代號>`(每個請求都當成來自這個服務,`req.academy` 為 null),或只在單一請求帶標頭 `x-academy-dev-service: <服務代號>`。`academy.members.entitlement()` 在開發模式只能查你自己。
|
|
491
|
+
|
|
492
|
+
## 11. 錯誤
|
|
493
|
+
|
|
494
|
+
所有平台錯誤都是 `AcademyError`:`code`、`status`、`message`、`details`(附帶欄位),另有捷徑 `loginUrl`、`subscribeUrl`、`upgradeUrl`、`retryAfterSeconds`、`reason`。**請看 `code`,不要只看 HTTP 狀態**(暫停、下架與沒有訂閱都是 403)。
|
|
495
|
+
|
|
496
|
+
| `code` | HTTP | 情況 | 附帶欄位 |
|
|
497
|
+
|---|---|---|---|
|
|
498
|
+
| `LOGIN_REQUIRED` | 401 | 未登入或 App 登入失效 | `login_url` |
|
|
499
|
+
| `SUBSCRIPTION_REQUIRED` | 403 | 訂閱制工具沒有有效訂閱 | `subscribe_url` |
|
|
500
|
+
| `APP_UNAVAILABLE` | 403 | 工具暫停、已下架,或非放行帳號進測試環境 | `status`:`SUSPENDED`/`DELISTED`/`TEST_ONLY` |
|
|
501
|
+
| `ORIGIN_NOT_ALLOWED` | 403 | 瀏覽器端來源檢查不通過 | — |
|
|
502
|
+
| `TOKEN_INVALID` | 401 | 會員委任憑證或服務憑證無效、過期、已撤銷(第 8、9 節) | 會員用戶端附 `authorize_url` |
|
|
503
|
+
| `RATE_LIMITED` | 429 | 服務憑證、憑證更新或會員權益查詢超過每分鐘上限 | `retry_after_seconds` |
|
|
504
|
+
| `ACCESS_DENIED` | — | 用戶端模組:會員在授權頁按了取消 | — |
|
|
505
|
+
| `IDENTITY_EXPIRED` | 401 | 沒有會員身分或身分已過期 | — |
|
|
506
|
+
| `INSUFFICIENT_POINTS` | 402 | 點數不足 | `upgrade_url`、`reset_at` |
|
|
507
|
+
| `MODEL_NOT_ALLOWED` | 400 | `model` 不是可用的平台別名 | `allowed` |
|
|
508
|
+
| `AI_LIMIT_EXCEEDED` | 429 | 超過上限 | `reason`:`PER_CALL`/`USER_RATE`(附 `retry_after_seconds`)/`APP_DAILY_COST` |
|
|
509
|
+
| `AI_UNAVAILABLE` | 503 | 上游失敗或平台 AI 暫停 | — |
|
|
510
|
+
| `CONTENT_FLAGGED` | 400 | 內容審查擋下(不扣點) | — |
|
|
511
|
+
| `INVALID_REQUEST` | 400 | 請求格式不正確(不扣點) | `message` 說明哪個欄位 |
|
|
512
|
+
| `DATA_UNAVAILABLE` | 429/503 | 房市資料暫時無法提供(不扣點) | `reason`、`retry_after_seconds` |
|
|
513
|
+
| `JOB_EXPIRED` | 401 | 工作憑證過期或已結束 | — |
|
|
514
|
+
| `JOB_BUDGET_EXCEEDED` | 402 | 工作憑證的預佔額度用完 | `max_points`、`used_points` |
|
|
515
|
+
| `JOB_LIMIT_EXCEEDED` | 409 | 進行中的工作已達上限 | `max_concurrent` |
|
|
516
|
+
|
|
517
|
+
日後可能新增錯誤碼;不認得的 `code` 也會包成 `AcademyError`,不會讓你的程式崩潰。
|
|
518
|
+
|
|
519
|
+
## 12. 從 Google AI Studio 匯出的專案改寫
|
|
520
|
+
|
|
521
|
+
SDK **不提供** `@google/genai` 相容層,也不會自動對照 Gemini 模型名。請把呼叫改成下面的形狀:
|
|
522
|
+
|
|
523
|
+
| 原本(`@google/genai`) | 改成(本 SDK) |
|
|
524
|
+
|---|---|
|
|
525
|
+
| `new GoogleGenAI({ apiKey })` | 伺服器端 `createAcademy()`;瀏覽器端 `academyBrowser.ai()` |
|
|
526
|
+
| `ai.models.generateContent({ model: 'gemini-2.5-flash', contents })` | `ai.chat.completions.create({ model: 'fast', messages: [{ role: 'user', content }] })` |
|
|
527
|
+
| `response.text` | `response.choices[0].message.content` |
|
|
528
|
+
| `config.systemInstruction` | `messages` 第一則 `{ role: 'system', content }` |
|
|
529
|
+
| `generateContentStream(...)`、`chunk.text` | `create({ ..., stream: true })`、`chunk.choices[0].delta.content` |
|
|
530
|
+
| `ai.models.generateImages({ model: 'imagen-…', prompt })` | `ai.images.generate({ model: 'image', prompt })`,結果在 `data[0].b64_json` |
|
|
531
|
+
| 多輪對話 `ai.chats.create()` | 自己保存 `messages` 陣列,每次整串送出 |
|
|
532
|
+
| `config.responseMimeType: 'application/json'` | 在提示詞要求 JSON 並自行 `JSON.parse` |
|
|
533
|
+
|
|
534
|
+
不改寫的部分可以繼續用你自備的金鑰直連,只是那部分的 AI 費用不能用會員點數支付。function calling、檔案上傳、Live API 目前不支援。
|
|
535
|
+
|
|
536
|
+
## 13. 過渡期:保留原本的登入
|
|
537
|
+
|
|
538
|
+
上架前或還沒按「啟用」時,正式環境沒有入口關卡,`req.academy` 是 `null`。App 可以這樣同時支援兩種登入:
|
|
539
|
+
|
|
540
|
+
```js
|
|
541
|
+
app.use(academy.express());
|
|
542
|
+
app.use((req, res, next) => {
|
|
543
|
+
if (req.academy) { req.currentUser = { id: req.academy.user.uuid, name: req.academy.user.name }; return next(); }
|
|
544
|
+
return yourOwnLogin(req, res, next); // 原本的登入
|
|
545
|
+
});
|
|
546
|
+
```
|
|
547
|
+
|
|
548
|
+
同一位會員在每個 App 的 `user.uuid` 都相同,可以用 email 對應到你原本的使用者資料。
|
|
549
|
+
|
|
550
|
+
## 14. 範例
|
|
551
|
+
|
|
552
|
+
- [`examples/express-subscription`](examples/express-subscription):有伺服器端的訂閱制 App(身分、對話、房市資料、點數、工作憑證背景報告)
|
|
553
|
+
- [`examples/frontend-free`](examples/frontend-free):純前端免費 App(AI Studio 匯出的 Vite 專案改寫:串流文案、圖片、災害潛勢)
|