小狐狸事務所

菁菁 MAZDA MX5 車險續約

2026-05-04T21:42:00.002+08:00

菁菁的小跑車 MX5 車險 5/8 日到期, 那天剛好從沖繩回來, 無法處理續約, 所以提前今天上網續保, 今年是第二年, 參考去年保險內容 :

今年強制+任意險比去年稍微便宜 :

機票英文名字拼錯問題

2026-05-04T21:05:00.003+08:00

今天做行前檢查, 發現早上水某寄的登機證中, 爸的英文名字拼音與護照有一個字母不正確, 原因是水某訂機票時我傳遞的資料打錯了, 趕緊撥打華航客服 02-4129000, 告知有此情況, 客服先叫我到華航網站先取消爸的報到單, 然後寄一封確認信給我, 要求填寫錯誤拚寫與正確拼寫, 並附上護照內頁照片佐證, 叮囑我若一小時後仍未收到已更正回函, 要再次撥打客服催促, 因客服員有限, 務必在線等候直到有人接聽.

# 華航客服 FAQ

# 華航網路報到網頁

到中午還沒收到完成回覆, 我再次打電話去詢問處理進度, 這回真的等了十分鐘才輪到, 客服表示已要求加速進行, 終於在下午三點收到更正回函, 上官網輸入機票號碼與正確姓名拼字, 果然就能進入機票與登機資訊網頁, 但無法線上寄發新的登機證, 說 "說請洽機場櫃檯領取登機證", 所以明天要早一點到櫃檯報到, 說明有更正姓名拼寫錯誤, 請其人工列印新登機證. 所以出國旅行前務必檢查旅行文件, 最好是列印出來做為備份, 也較能檢查出錯誤, 不要小看一個字母之差, 這可能會讓旅伴到機場才發現無法同行. 即使旅伴不是親人, 最好也能互相檢查一下較妥當.

2026 年第 17 周記事

2026-05-03T23:23:00.005+08:00

本周五勞動節連假只上四天班, 我週三沒有回鄉下, 因為周四下班就要回去了. 以往勞動節都去加班, 今年不加了, 即使可加也不想去了, 邁入耳順之年後更想要的是放假. 周六老同學大帥與仲仔, 風大師來訪, 因為之前我都下廚在加吃便飯, 坐下來聊天時間不甚多, 這回剛好峰大師四月底退休, 預定了菸樓坊一桌請大伙去吃飯, 但到了餐廳才發現遊覽車一車車進來, 不知要等多久才有空位, 大帥建議取消, 去人少的地方, 我想起鎮上的八分飽, 到餐廳時下車問還好有空桌, 於是便在此用餐. 我看以後還是自己下廚吧, 外面餐廳假日都是人.

連假三天我都在家測試程式, 一口氣把 Plotly 與 Bokeh 畫 K 線圖的方法搞定. 雖然 AI 時代漸漸都不自己寫程式了, 小白或非科班就算呃, 但做為工程師還是得看得懂 AI 在寫甚麼吧?

週五舅媽叫小舅帶來涼麵與木瓜粄, 加上峰大師周六帶來一隻烤雞, 所以連假三天都在消耗這些糧食, 甚至今天周日我也沒上市場買菜, 因為下周要去沖繩, 食材放太久也不行.

下午要去菜園移植韭菜時, 經過車庫看見毛小妹與它的一隻小貓躺在一起睡覺, 看似小貓吃完奶就地睡著了, 那畫面看來好幸福, 趕緊進屋拿手機拍了下來 :

但晚上爸在曬穀場騎腳踏車時, 一隻小貓跑到路對面去, 在橫越馬路跑回來時被一台機車撞到, 那人也沒停下來逕自騎走了, 爸把小貓報進來, 我看口鼻皆流血已無呼吸, 因它們四兄妹毛色很像, 不確定是否為下午那隻. 我家緊鄰馬路邊, 路雖不大但為交通要道, 來往車子都開太快, 打算買一個太陽能警示燈安裝在路旁電線桿, 希望提醒減速慢行.

Python 學習筆記 : 用 bokeh 繪製 K 線圖 (二)

2026-05-03T13:43:00.004+08:00

Bokeh 的優點是高自由度與高效能, 但其 API 較低階, 故並未內建像 Plotly 的 CandleStick 那樣的類別, 本篇旨在為 Bokey 山寨一個 CandleStick 來簡化 K 線圖的繪製. 為了讓程式碼不至於過度複雜, 以下測試不處理非交易日 K 棒空缺問題.

本系列全部測試文章索引參考 :

# Python 資料視覺化學習筆記索引

4. 用封裝的類別繪製 K 線圖 :

下面範例改寫自前一篇測試的 bokeh_candlestick_3.py, 將繪製 K 線圖的邏輯封裝在自訂的 BokehChart 類別裡, 只要呼叫其建構式並傳入 title/width/height 參數建立物件, 然後在主程式中呼叫 add_candlestick(df) 即可繪製 K 線圖, 程式碼如下 :

# bokeh_candlestick_class_1.py

import yfinance as yf

import pandas as pd

from bokeh.plotting import figure, show

from bokeh.models import ColumnDataSource, HoverTool, CrosshairTool, Span

class BokehChart:

"""封裝 Bokeh K線圖與技術分析工具的繪圖類別"""

def __init__(self, title="K線圖", width=800, height=400):

# 建立並初始化畫布

self.fig=figure(

x_axis_type='datetime',

title=title,

width=width,

height=height,

tools='xpan, xwheel_zoom, box_zoom, reset, save'

)

self.fig.grid.grid_line_alpha=0.3

# 初始化虛線十字游標

self._add_crosshair()

def _add_crosshair(self):

"""內部方法：加入虛線十字游標"""

w_span=Span(dimension="width", line_dash="dashed", line_color="gray", line_alpha=0.6, line_width=1)

h_span=Span(dimension="height", line_dash="dashed", line_color="gray", line_alpha=0.6, line_width=1)

self.fig.add_tools(CrosshairTool(overlay=[w_span, h_span]))

def add_candlestick(self, df, date_col='Date', open_col='Open', high_col='High', low_col='Low', close_col='Close', vol_col='Volume'):

"""對外介面：加入 K 線圖與懸停工具"""

# 複製資料以避免修改到原始 DataFrame

data=df.copy()

# 定義漲跌顏色 (紅漲綠跌)

data['color']=['#ff0000' if c >= o else '#00aa00' for o, c in zip(data[open_col], data[close_col])]

# 建立資料來源

source=ColumnDataSource(data)

# 繪製上下影線

self.fig.segment(date_col, high_col, date_col, low_col, color="black", source=source)

# 繪製 K 棒 (12 小時寬度)

width_ms=12 * 60 * 60 * 1000

self.fig.vbar(date_col, width_ms, open_col, close_col,

fill_color='color', line_color='black', source=source)

# 加入互動式懸停工具 (HoverTool)

hover=HoverTool(

tooltips=[

("日期", f"@{date_col}{{%F}}"),

("開盤", f"@{open_col}{{0.00}}"),

("收盤", f"@{close_col}{{0.00}}"),

("最高", f"@{high_col}{{0.00}}"),

("最低", f"@{low_col}{{0.00}}"),

("成交量", f"@{vol_col}{{0,0}}")

formatters={f'@{date_col}': 'datetime'}

)

self.fig.add_tools(hover)

def show(self):

"""顯示圖表"""

show(self.fig)

# ==========================================

# 主程式：使用類別繪圖 (如同 Plotly 般簡潔)

# ==========================================

if __name__ == "__main__":

# 1. 下載真實 OHLCV 資料

df=yf.download('0050.tw', start='2026-03-01', end='2026-04-30', auto_adjust=True)

df.columns=df.columns.map(lambda x: x[0])

df=df.reset_index()

# 2. 實例化畫布並繪圖

chart=BokehChart(title='0050.TW 台灣50 ETF K線圖 (2026-03 ~ 2026-04)', width=800, height=400)

chart.add_candlestick(df)

# 3. 顯示圖表

chart.show()

結果如下 :

5. 用封裝的類別繪製 K 線圖 + 成交量副圖 :

如果要同時繪製 K 線圖與成交量副圖, 則須匯入 bokeh.layouts.column() 函式進行垂直布局, 讓主圖 (fig_k) 與副圖能共用 X 軸並連動. 程式碼改寫如下 :

# bokeh_candlestick_class_2.py

import yfinance as yf

import pandas as pd

from bokeh.plotting import figure, show

from bokeh.models import ColumnDataSource, HoverTool, CrosshairTool, Span, CustomJSTickFormatter

from bokeh.layouts import column # 引入垂直佈局工具

class BokehChart:

"""封裝 Bokeh K線圖與成交量子圖的繪圖類別"""

# 稍微調整初始化參數，允許分別設定主圖與副圖的高度

def __init__(self, title="K線圖", width=800, height_k=400, height_v=150):

# 1. 建立主圖 (K線圖)

self.fig_k=figure(

title=title,

width=width, height=height_k,

tools='xpan, xwheel_zoom, box_zoom, reset, save'

)

self.fig_k.grid.grid_line_alpha=0.3

self.fig_k.xaxis.visible=False # 隱藏主圖的 X 軸，讓畫面更緊湊

# 2. 建立副圖 (成交量圖)

self.fig_v=figure(

width=width, height=height_v,

x_range=self.fig_k.x_range, # 【關鍵連動】將副圖的 X 軸範圍綁定為主圖的 X 軸

tools='xpan, xwheel_zoom, reset'

)

self.fig_v.grid.grid_line_alpha=0.3

self.fig_v.y_range.start=0 # 確保成交量 Y 軸從 0 開始

# 3. 組合為垂直佈局

self.layout=column(self.fig_k, self.fig_v)

# 4. 初始化虛線十字游標 (加在兩張圖上)

self._add_crosshair(self.fig_k)

self._add_crosshair(self.fig_v)

def _add_crosshair(self, fig):

"""內部方法：為指定的畫布加入虛線十字游標"""

w_span=Span(dimension="width", line_dash="dashed", line_color="gray", line_alpha=0.6, line_width=1)

h_span=Span(dimension="height", line_dash="dashed", line_color="gray", line_alpha=0.6, line_width=1)

fig.add_tools(CrosshairTool(overlay=[w_span, h_span]))

def add_candlestick(self, df, date_col='Date', open_col='Open', high_col='High', low_col='Low', close_col='Close', vol_col='Volume'):

"""對外介面：處理資料並繪製 K 線與成交量"""

data=df.copy()

# 建立連續整數序列 (消除假日空缺)

data['seq']=range(len(data))

# 定義漲跌顏色

data['color']=['#ff0000' if c >= o else '#00aa00' for o, c in zip(data[open_col], data[close_col])]

# 用 Python 預先處理好 Bokeh 風格的日期字串

date_map={}

prev_year=None

for i, d in enumerate(data[date_col]):

label=f"{d.strftime('%b')} {d.day}"

if i == 0 or d.year != prev_year:

label += f"\n{d.year}"

date_map[str(i)]=label

prev_year=d.year

source=ColumnDataSource(data)

width_val=0.8 # 因為 X 軸變成了連續整數，寬度直接用比例 0.8

# --- 繪製主圖 (K線) ---

self.fig_k.segment('seq', high_col, 'seq', low_col, color="black", source=source)

self.fig_k.vbar('seq', width_val, open_col, close_col, fill_color='color', line_color='black', source=source)

# --- 繪製副圖 (成交量) ---

# 使用 vbar，top 參數指定為成交量欄位

self.fig_v.vbar('seq', width_val, top=vol_col, fill_color='color', line_color='black', source=source)

# --- 設定副圖的 X 軸日期標籤 ---

js_code="""

var idx=Math.round(tick).toString();

if (date_map[idx] !== undefined) {

return date_map[idx];

} else {

return "";

}

"""

self.fig_v.xaxis.formatter=CustomJSTickFormatter(code=js_code, args={'date_map': date_map})

self.fig_v.xaxis.major_label_orientation=0

self.fig_v.xaxis.major_label_standoff=15

# --- 加入互動式懸停工具 ---

hover=HoverTool(

tooltips=[

("日期", f"@{date_col}{{%F}}"),

("開盤", f"@{open_col}{{0.00}}"),

("收盤", f"@{close_col}{{0.00}}"),

("最高", f"@{high_col}{{0.00}}"),

("最低", f"@{low_col}{{0.00}}"),

("成交量", f"@{vol_col}{{0,0}}")

formatters={f'@{date_col}': 'datetime'},

mode='vline' # 【推薦】改為 vline 模式，滑鼠對齊同一個垂直線就會觸發

)

self.fig_k.add_tools(hover)

self.fig_v.add_tools(hover)

def show(self):

"""顯示圖表佈局"""

show(self.layout) # 【修改】現在是顯示整個 layout 而不是單一 fig

# ==========================================

# 主程式

# ==========================================

if __name__ == "__main__":

# 1. 下載實盤 OHLCV 資料

df=yf.download('0050.tw', start='2026-03-01', end='2026-04-30', auto_adjust=True)

df.columns=df.columns.map(lambda x: x[0])

df=df.reset_index()

# 2. 建立畫布並繪圖

chart=BokehChart(title='0050.TW 台灣50 ETF (含同步成交量)')

chart.add_candlestick(df)

# 3. 顯示圖表

chart.show()

注意, 此例之 BokehChart 類別還封裝了處理非交易日空缺的邏輯, 這讓整個畫布上的 K 棒看起來是連續無空缺的, 結果如下 :

6. 用封裝的類別繪製 K 線圖 + 成交量 + 技術指標副圖 :

上面範例中的 BokehChart 類別把主圖與副圖邏輯都寫在類別裡, 每次要添加技術指標副圖都要去改類別並不符合軟工原則, 若要讓程式碼具有擴充性, 必須對架構做一次重構, 要建立一個動態串列 self.figures = [] 的來儲存所有畫布, 並增加通用副圖方法, 例如 add_bar_subplot() (畫成交量, MACD柱狀圖) 與 add_line_subplot() (畫 RSI, 均線).

程式碼如下 :

# bokeh_candlestick_class_3.py

import yfinance as yf

import pandas as pd

import pandas_ta as ta #

from bokeh.plotting import figure

from bokeh.io import show as show_bokeh # 避免名稱衝突

from bokeh.models import ColumnDataSource, HoverTool, CrosshairTool, Span, CustomJSTickFormatter

from bokeh.layouts import column

class BokehChart:

"""高擴充性 Bokeh 繪圖類別，支援動態疊加無限多個副圖"""

def __init__(self, title="K線圖", width=800, main_height=400):

self.width=width

self.title=title

self.main_height=main_height

# 動態儲存所有畫布的清單 (主圖會在 index 0)

self.figures=[]

self.source=None

self.date_map={}

self.fig_k=None # 參照主圖，用來同步 x_range

def _add_crosshair(self, fig):

"""內部方法：加入虛線十字游標"""

w_span=Span(dimension="width", line_dash="dashed", line_color="gray", line_alpha=0.6, line_width=1)

h_span=Span(dimension="height", line_dash="dashed", line_color="gray", line_alpha=0.6, line_width=1)

fig.add_tools(CrosshairTool(overlay=[w_span, h_span]))

def add_candlestick(self, df, date_col='Date', open_col='Open', high_col='High', low_col='Low', close_col='Close'):

"""【步驟 1】：初始化主圖與共用資料源"""

data=df.copy()

# 建立連續整數序列 (消除假日空缺)

data['seq']=range(len(data))

data['color']=['#ff0000' if c >= o else '#00aa00' for o, c in zip(data[open_col], data[close_col])]

# 製作日期對照表

self.date_map={}

prev_year=None

for i, d in enumerate(data[date_col]):

label=f"{d.strftime('%b')} {d.day}"

if i == 0 or d.year != prev_year:

label += f"\n{d.year}"

self.date_map[str(i)]=label

prev_year=d.year

# 建立全局共用的資料源 (此時 df 裡面已經包含外部算好的 RSI 等指標)

self.source=ColumnDataSource(data)

# 建立主畫布

self.fig_k=figure(title=self.title, width=self.width, height=self.main_height, tools='xpan, xwheel_zoom, box_zoom, reset, save')

self.fig_k.grid.grid_line_alpha=0.3

# 繪製 K 線

self.fig_k.segment('seq', high_col, 'seq', low_col, color="black", source=self.source)

self.fig_k.vbar('seq', 0.8, open_col, close_col, fill_color='color', line_color='black', source=self.source)

# 設定主圖 Hover

hover=HoverTool(

tooltips=[("日期", f"@{date_col}{{%F}}"), ("開盤", f"@{open_col}{{0.00}}"), ("收盤", f"@{close_col}{{0.00}}")],

formatters={f'@{date_col}': 'datetime'}, mode='vline'

)

self.fig_k.add_tools(hover)

self._add_crosshair(self.fig_k)

# 加入畫布清單

self.figures.append(self.fig_k)

def add_bar_subplot(self, col_name, title="", color_col=None, color='blue', height=150):

"""通用介面：新增柱狀圖副圖 (例如：成交量、MACD柱)"""

fig=figure(width=self.width, height=height, x_range=self.fig_k.x_range, tools='xpan, xwheel_zoom, reset')

fig.grid.grid_line_alpha=0.3

fig.y_range.start=0

# 若有指定顏色欄位 (如成交量的紅綠色)，則使用該欄位；否則使用單一顏色

fill_c=color_col if color_col else color

fig.vbar('seq', 0.8, top=col_name, fill_color=fill_c, line_color='black', source=self.source)

# 專屬 Hover

hover=HoverTool(tooltips=[("日期", "@Date{%F}"), (title or col_name, f"@{col_name}{{0,0}}")], formatters={'@Date': 'datetime'}, mode='vline')

fig.add_tools(hover)

self._add_crosshair(fig)

self.figures.append(fig)

def add_line_subplot(self, col_name, title="", color='blue', height=150, hlines=None):

"""通用介面：新增折線圖副圖 (例如：RSI、均線、KD)"""

fig=figure(width=self.width, height=height, x_range=self.fig_k.x_range, tools='xpan, xwheel_zoom, reset')

fig.grid.grid_line_alpha=0.3

fig.line('seq', col_name, color=color, line_width=1.5, source=self.source)

# 支援加入水平參考線 (例如 RSI 的 30, 70 超買超賣線)

if hlines:

for y_val in hlines:

line=Span(location=y_val, dimension='width', line_color='gray', line_dash='dashed', line_alpha=0.5)

fig.add_layout(line)

# 專屬 Hover

hover=HoverTool(tooltips=[("日期", "@Date{%F}"), (title or col_name, f"@{col_name}{{0.00}}")], formatters={'@Date': 'datetime'}, mode='vline')

fig.add_tools(hover)

self._add_crosshair(fig)

self.figures.append(fig)

def show(self):

"""渲染圖表：隱藏除最後一張圖外的 X 軸，並套用自訂日期標籤"""

for i, fig in enumerate(self.figures):

# 不是最後一張圖，隱藏 X 軸

if i < len(self.figures) - 1:

fig.xaxis.visible=False

# 是最後一張圖，掛上 JavaScript 日期查表邏輯

else:

js_code="""

var idx=Math.round(tick).toString();

if (date_map[idx] !== undefined) {

return date_map[idx];

}

else {

return "";

}

"""

fig.xaxis.formatter=CustomJSTickFormatter(code=js_code, args={'date_map': self.date_map})

fig.xaxis.major_label_orientation=0

fig.xaxis.major_label_standoff=15

# 垂直疊加所有被加入的圖表

layout=column(*self.figures)

show_bokeh(layout)

# ==========================================

# 主程式：展現架構擴充性的時刻

# ==========================================

if __name__ == "__main__":

# 1. 獲取資料

df=yf.download('0050.tw', start='2025-10-01', end='2026-04-30', auto_adjust=True)

df.columns=df.columns.map(lambda x: x[0])

df=df.reset_index()

# 2. 在外部計算所有技術指標 (類別完全不需要知道 RSI 怎麼算的)

df['RSI']=ta.rsi(df['Close'], length=14)

# 3. 開始繪圖 (如堆積木般直覺)

chart=BokehChart(title='0050.TW 台灣50 ETF (整合 RSI 指標)')

# 初始化主圖與資料源

chart.add_candlestick(df)

# 呼叫通用介面新增成交量 (使用 color 欄位決定紅綠)

chart.add_bar_subplot('Volume', title='成交量', color_col='color', height=100)

# 呼叫通用介面新增 RSI (自訂顏色，並加上 30/70 水平參考線)

chart.add_line_subplot('RSI', title='RSI(14)', color='purple', height=150, hlines=[30, 70])

# 顯示成果

chart.show()

此例使用 pandas_ta 套件計算 RSI 指標值, 結果放進 df['RSI'] 欄位, 結果如下 :

7. 獨立的 Bokeh K 線圖模組 :

我們可以將上面範例的 BokehChart 類別寫在一個獨立的模組檔案例如 bokeh_chart.py 中, 再用 import 方式匯入 BokehChart 類別來繪製 K 線圖, 這樣主程式檔就會較簡潔了.

模組檔案 bokeh_chart.py 內容如下 :

# bokeh_chart.py

import pandas as pd

from bokeh.plotting import figure

from bokeh.io import show as show_bokeh

from bokeh.models import ColumnDataSource, HoverTool, CrosshairTool, Span, CustomJSTickFormatter

from bokeh.layouts import column

class BokehChart:

"""高擴充性 Bokeh 繪圖類別，支援動態疊加無限多個副圖"""

def __init__(self, title='K線圖', width=800, main_height=400):

self.width=width

self.title=title

self.main_height=main_height

self.figures=[]

self.source=None

self.date_map={}

self.fig_k=None

def _add_crosshair(self, fig):

"""加入虛線十字游標"""

w_span=Span(dimension='width', line_dash='dashed', line_color="gray", line_alpha=0.6, line_width=1)

h_span=Span(dimension='height', line_dash='dashed', line_color="gray", line_alpha=0.6, line_width=1)

fig.add_tools(CrosshairTool(overlay=[w_span, h_span]))

def add_candlestick(self, df, date_col='Date', open_col='Open', high_col='High', low_col='Low', close_col='Close'):

"""初始化主圖與共用資料源"""

data=df.copy()

# 建立連續整數序列與漲跌顏色

data['seq']=range(len(data))

data['color']=['#ff0000' if c >= o else '#00aa00' for o, c in zip(data[open_col], data[close_col])]

# 製作日期對照表

self.date_map={}

prev_year=None

for i, d in enumerate(data[date_col]):

label=f"{d.strftime('%b')} {d.day}"

if i == 0 or d.year != prev_year:

label += f"\n{d.year}"

self.date_map[str(i)]=label

prev_year=d.year

self.source=ColumnDataSource(data)

self.fig_k=figure(title=self.title, width=self.width, height=self.main_height, tools='xpan, xwheel_zoom, box_zoom, reset, save')

self.fig_k.grid.grid_line_alpha=0.3

self.fig_k.segment('seq', high_col, 'seq', low_col, color="black", source=self.source)

self.fig_k.vbar('seq', 0.8, open_col, close_col, fill_color='color', line_color='black', source=self.source)

hover=HoverTool(

tooltips=[("日期", f"@{date_col}{{%F}}"), ("開盤", f"@{open_col}{{0.00}}"), ("收盤", f"@{close_col}{{0.00}}")],

formatters={f'@{date_col}': 'datetime'}, mode='vline'

)

self.fig_k.add_tools(hover)

self._add_crosshair(self.fig_k)

self.figures.append(self.fig_k)

def add_bar_subplot(self, col_name, title="", color_col=None, color='blue', height=150, on_fig=None, y_min_zero=False):

"""新增柱狀圖副圖 (支援傳入畫布疊加到現有畫布)"""

# 如果有指定 on_fig，就用現成的畫布；否則建立新畫布

if on_fig:

fig=on_fig

else:

fig=figure(width=self.width, height=height, x_range=self.fig_k.x_range, tools='xpan, xwheel_zoom, reset')

fig.grid.grid_line_alpha=0.3

self.figures.append(fig) # 只有新畫布才需要加入清單

self._add_crosshair(fig) # 只有新畫布才需要加十字線

# 只有成交量這類數值絕對為正的圖表，才需要強制 Y 軸從 0 開始

if y_min_zero:

fig.y_range.start=0

fill_c=color_col if color_col else color

fig.vbar('seq', 0.8, top=col_name, fill_color=fill_c, line_color='black', source=self.source)

# 專屬 Hover

hover=HoverTool(tooltips=[("日期", "@Date{%F}"), (title or col_name, f"@{col_name}{{0.00}}")], formatters={'@Date': 'datetime'}, mode='vline')

fig.add_tools(hover)

return fig # 回傳畫布讓後續的線可以畫在它上面

def add_line_subplot(self, col_name, title="", color='blue', height=150, hlines=None, on_fig=None):

"""新增折線圖副圖 (支援疊加到現有畫布)"""

# 如果有指定 on_fig，就用現成的畫布；否則建立新畫布

if on_fig:

fig = on_fig

else:

fig = figure(width=self.width, height=height, x_range=self.fig_k.x_range, tools='xpan, xwheel_zoom, reset')

fig.grid.grid_line_alpha = 0.3

self.figures.append(fig)

self._add_crosshair(fig)

fig.line('seq', col_name, color=color, line_width=1.5, source=self.source)

if hlines:

for y_val in hlines:

line = Span(location=y_val, dimension='width', line_color='gray', line_dash='dashed', line_alpha=0.5)

fig.add_layout(line)

hover = HoverTool(tooltips=[("日期", "@Date{%F}"), (title or col_name, f"@{col_name}{{0.00}}")], formatters={'@Date': 'datetime'}, mode='vline')

fig.add_tools(hover)

return fig # 回傳畫布讓後續的線可以畫在它上面

def show(self):

"""渲染圖表"""

for i, fig in enumerate(self.figures):

if i < len(self.figures) - 1:

fig.xaxis.visible=False

else:

js_code="""

var idx=Math.round(tick).toString();

if (date_map[idx] !== undefined) {

return date_map[idx];

} else {

return "";

}

"""

fig.xaxis.formatter=CustomJSTickFormatter(code=js_code, args={'date_map': self.date_map})

fig.xaxis.major_label_orientation=0

fig.xaxis.major_label_standoff=15

layout=column(*self.figures)

show_bokeh(layout)

欲繪製 K 線圖+成交量+技術指標時, 主程式檔只要先從 bokeh_chart.py 匯入 BokehChart 類別並建立 BokehChart 物件後, 呼叫 add_candlestick() 繪製主圖 (K 線圖), 呼叫 add_bar_subplot() 或 add_line_subplot() 添加副圖 (成交量 & 技術指標), 下面範例添加了 RSI 與 MACD 副圖 :

# bokeh_candlestick_class_4.py

import yfinance as yf

import pandas as pd

import pandas_ta as ta

from bokeh_chart import BokehChart

if __name__ == "__main__":

# 1. 獲取資料

df=yf.download('0050.tw', start='2025-10-01', end='2026-04-30', auto_adjust=True)

df.columns=df.columns.map(lambda x: x[0])

df=df.reset_index()

# 2. 計算技術指標

# RSI

df['RSI']=ta.rsi(df['Close'], length=14)

# MACD (將計算結果合併回原本的 df)

macd_df=ta.macd(df['Close'])

df=pd.concat([df, macd_df], axis=1)

# 計算 MACD 柱狀圖的顏色 (大於等於 0 紅色，小於 0 綠色)

df['macd_color']=['#ff0000' if m >= 0 else '#00aa00' for m in df['MACDh_12_26_9']]

# 3. 畫圖

# 畫主圖 : K 線圖

chart=BokehChart(title='0050.TW 台灣50 ETF (整合 MACD)')

chart.add_candlestick(df)

# 畫成交量副圖 (加上 y_min_zero=True，避免長條圖懸空)

chart.add_bar_subplot('Volume', title='成交量', color_col='color', height=100, y_min_zero=True)

# ==========================================

# 繪製 MACD 複合副圖

# ==========================================

# 第一步：先畫 MACD 柱狀圖，並用變數 macd_fig 把畫布接住

macd_fig=chart.add_bar_subplot('MACDh_12_26_9', title='MACD柱', color_col='macd_color', height=150)

# 第二步：把 MACD 線畫在 macd_fig 身上

chart.add_line_subplot('MACD_12_26_9', title='MACD線', color='blue', on_fig=macd_fig)

# 第三步：把 Signal 線也畫在 macd_fig 身上

chart.add_line_subplot('MACDs_12_26_9', title='Signal線', color='orange', on_fig=macd_fig)

# ==========================================

chart.show()

注意, 此處 MACD 指標因為含有快線, 慢線, 與柱狀圖三個圖形, 通常都是疊在一個畫布上, 所以要分成三個步驟把三個圖層疊上去, 首先繪製柱狀圖, 然後將傳回的畫布物件 macd_fig 在後續繪製快線與慢線時傳給 on_fonfig 參數, 這樣三張圖就會疊在同一張畫布上了.

結果如下 :

可見將繪圖類別獨立出去後, 主程式結構就清爽易讀多了.

Python 學習筆記 : 用 bokeh 繪製 K 線圖 (一)

2026-05-03T07:42:00.007+08:00

Bokeh 不像 Plotly 那樣有內建專門繪製 K 線圖的 CandleStick 類別, 它需透過 bokeh.models 模組中的 Segment 物件 (用來繪製上下影線) 與 Vbar 物件 (用來繪製實體紅黑棒) 來達成, 方法雖然較低階, 但卻比 Plotly 擁有更高的自由度與效能, 尤其是要在瀏覽器中渲染數萬根 K 線時, Bokeh 的 WebGL 渲染模式通常比 Plotly 更為輕快, 且保持流暢的縮放和平移效果.

本系列全部測試文章索引參考 :

# Python 資料視覺化學習筆記索引

首先匯入繪圖用的函式 figure() 與 show() :

>>> from bokeh.plotting import figure, show

然後從元件模組 bokeh.models 中匯入匯入用來繪製 K 棒的 ColumnDataSource 類別, 以及繪製互動效果的懸停工具類別 HoverTool :

>>> from bokeh.models import ColumnDataSource, HoverTool

接著匯入 Pandas 來處理 OHLC 資料 :

>>> import pandas as pd

>>> data={

'date': pd.to_datetime(['2026-05-01', '2026-05-02', '2026-05-03', '2026-05-04']),

'open': [100, 110, 105, 120],

'high': [115, 120, 110, 130],

'low': [95, 105, 100, 115],

'close': [110, 105, 108, 125]

}

>>> df=pd.DataFrame(data)

在 df 中添加一個 color 欄位來記錄漲跌顏色 (紅漲綠跌) :

>>> df['color']=['#ff0000' if c >= o else '#00aa00' for o, c in zip(df.open, df.close)]

呼叫 ColumnDataSource 類別的建構式 ColumnDataSource() 並傳入 df 建立 ColumnDataSource 物件 :

>>> source=ColumnDataSource(df)

>>> type(source)

呼叫 figure() 函式建立畫布物件 :

>>> fig=figure(

x_axis_type='datetime',

title='Bokeh K線圖',

width=800,

height=400

)

呼叫 segment() 函式繪製上下影線 :

>>> fig.segment('date', 'high', 'date', 'low', color='black', source=source)

GlyphRenderer(id='p1138', ...)

呼叫 Figure 物件的 vbar() 方法繪製 K 棒 :

>>> fig.vbar('date', pd.Timedelta(hours=12), 'open', 'close',

fill_color='color', line_color='black', source=source)

GlyphRenderer(id='p1147', ...)

呼叫 HoverTool 類別的建構式建立懸停工具物件 :

>>> hover=HoverTool(

tooltips=[

("日期", "@date{%F}"),

("開盤", "@open"),

("收盤", "@close"),

("最高", "@high"),

("最低", "@low")

formatters={'@date': 'datetime'}

)

呼叫 Figure 物件的 add_tool() 方法將懸停工具物件加入畫布中 :

>>> fig.add_tools(hover)

這樣便可呼叫 show() 函式來顯示畫布了 :

>>> show(fig)

Bokeh 會自動開啟瀏覽器顯示網頁來呈現畫布內容 :

完整程式碼如下 :

# bokeh_candlestick_1.py

import pandas as pd

from bokeh.plotting import figure, show

from bokeh.models import ColumnDataSource, HoverTool

# OHLC 資料 :

data={

'date': pd.to_datetime(['2026-05-01', '2026-05-02', '2026-05-03', '2026-05-04']),

'open': [100, 110, 105, 120],

'high': [115, 120, 110, 130],

'low': [95, 105, 100, 115],

'close': [110, 105, 108, 125]

}

df=pd.DataFrame(data)

# 定義漲跌顏色

df['color']=['#ff0000' if c >= o else '#00aa00' for o, c in zip(df.open, df.close)]

source=ColumnDataSource(df)

# 建立畫布

fig=figure(

x_axis_type='datetime',

title='Bokeh K線圖',

width=800,

height=400,

#tools='pan, wheel_zoom, box_zoom, reset, save'

)

# 繪製上下影線 (Segment 物件)

fig.segment('date', 'high', 'date', 'low', color="black", source=source)

# 繪製 K 棒 (Vbar 物件)

# width 設定為 12 小時 (以毫秒計算) 以確保條形之間有間隔

fig.vbar('date', pd.Timedelta(hours=12), 'open', 'close',

fill_color='color', line_color='black', source=source)

# 加入互動式懸停工具 (HoverTool)

hover=HoverTool(

tooltips=[

("日期", "@date{%F}"),

("開盤", "@open"),

("收盤", "@close"),

("最高", "@high"),

("最低", "@low")

formatters={'@date': 'datetime'}

)

fig.add_tools(hover)

# 輸出與顯示

#output_file("candlestick.html")

show(fig)

1. 繪製從 yfinance 下載的實盤 K 線圖 :

下面範例改從 yfinance 抓取實盤 OHLC 資料來繪製 K 線圖, 程式碼如下 :

# bokeh_candlestick_2.py

import yfinance as yf

import pandas as pd

from bokeh.plotting import figure, show

from bokeh.models import ColumnDataSource, HoverTool

# 1. 下載真實 OHLCV 資料

df=yf.download('0050.tw', start='2026-03-01', end='2026-04-30', auto_adjust=True)

# 攤平 yfinance 最新版本回傳的 MultiIndex 欄位

df.columns=df.columns.map(lambda x: x[0])

# yfinance 的日期會被設為索引, 重設為一般欄位以利 ColumnDataSource 讀取

df=df.reset_index()

# 2. 定義漲跌顏色 (紅漲綠跌)

df['color']=['#ff0000' if c >= o else '#00aa00' for o, c in zip(df['Open'], df['Close'])]

# 3. 建立資料來源

source=ColumnDataSource(df)

# 4. 建立畫布

fig=figure(

x_axis_type='datetime',

title='0050.TW 台灣50 ETF K線圖 (2026-03 ~ 2026-04)',

width=800,

height=400,

# 加入十字游標 (crosshair) 與鎖定 X 軸縮放(xwheel_zoom) 以利看盤

tools='xpan, xwheel_zoom, box_zoom, crosshair, reset, save'

)

# 讓網格線淡一點，視覺更聚焦在 K 棒上

fig.grid.grid_line_alpha=0.3

# 5. 繪製上下影線

fig.segment('Date', 'High', 'Date', 'Low', color="black", source=source)

# 6. 繪製 K 棒

# Bokeh 處理時間軸時寬度用毫秒計算最為精準與穩定。12小時=12 * 60 * 60 * 1000 毫秒

width_ms=12 * 60 * 60 * 1000

fig.vbar('Date', width_ms, 'Open', 'Close',

fill_color='color', line_color='black', source=source)

# 7. 加入互動式懸停工具 (HoverTool)

# 加上了數值格式化 {0.00} 讓小數點對齊並順手加入成交量 (Volume)

hover=HoverTool(

tooltips=[

("日期", "@Date{%F}"),

("開盤", "@Open{0.00}"),

("收盤", "@Close{0.00}"),

("最高", "@High{0.00}"),

("最低", "@Low{0.00}"),

("成交量", "@Volume{0,0}")

formatters={'@Date': 'datetime'}

)

fig.add_tools(hover)

# 8. 輸出與顯示

show(fig)

此例的關鍵之處是 yf 下載的 df 日期欄位會被設為索引, 所以必須呼叫 df.reset_index() 將日期欄位重設為一般欄位, 這樣 ColumnDataSource 物件才能讀得到, 另外, 懸停工具則添加了 yf 取得的成交量資訊, 結果如下 :

可見十字線會隨著滑鼠在畫布中移動, 當指向 K 棒時會出現懸停提示, 顯示 OHLCV 數據.

2. 客製化的虛線十字輔助線 :

預設的十字線是實線, 如果要改為虛線須取消 tools 參數中的 crosshair, 然後匯入 CrosshairTool, Span 這兩個類別 :

from bokeh.models import ColumnDataSource, HoverTool, CrosshairTool, Span

其中 CrosshairTool 用來建立客製化十字輔助線, 而 Span 則用來建立具有 line_dash 屬性的 Span (跨距線) 物件, 然後把這些線覆蓋 (overlay) 到 CrosshairTool 物件上, 程式改寫如下 :

# bokeh_candlestick_3.py

import yfinance as yf

import pandas as pd

from bokeh.plotting import figure, show

from bokeh.models import ColumnDataSource, HoverTool, CrosshairTool, Span

# 1. 下載真實 OHLCV 資料

df=yf.download('0050.tw', start='2026-03-01', end='2026-04-30', auto_adjust=True)

# 攤平 yfinance 最新版本回傳的 MultiIndex 欄位

df.columns=df.columns.map(lambda x: x[0])

# yfinance 的日期會被設為索引, 重設為一般欄位以利 ColumnDataSource 讀取

df=df.reset_index()

# 2. 定義漲跌顏色 (紅漲綠跌)

df['color']=['#ff0000' if c >= o else '#00aa00' for o, c in zip(df['Open'], df['Close'])]

# 3. 建立資料來源

source=ColumnDataSource(df)

# 4. 建立畫布

fig=figure(

x_axis_type='datetime',

title='0050.TW 台灣50 ETF K線圖 (2026-03 ~ 2026-04)',

width=800,

height=400,

# 鎖定 X 軸縮放(xwheel_zoom) 以利看盤 (取消 crosshair)

tools='xpan, xwheel_zoom, box_zoom, , reset, save'

)

# 讓網格線淡一點，視覺更聚焦在 K 棒上

fig.grid.grid_line_alpha=0.3

# 5. 繪製上下影線

fig.segment('Date', 'High', 'Date', 'Low', color="black", source=source)

# 6. 繪製 K 棒

# Bokeh 處理時間軸時寬度用毫秒計算最為精準與穩定。12小時=12 * 60 * 60 * 1000 毫秒

width_ms=12 * 60 * 60 * 1000

fig.vbar('Date', width_ms, 'Open', 'Close',

fill_color='color', line_color='black', source=source)

# 7. 加入互動式懸停工具 (HoverTool)

# 加上了數值格式化 {0.00} 讓小數點對齊並順手加入成交量 (Volume)

hover=HoverTool(

tooltips=[

("日期", "@Date{%F}"),

("開盤", "@Open{0.00}"),

("收盤", "@Close{0.00}"),

("最高", "@High{0.00}"),

("最低", "@Low{0.00}"),

("成交量", "@Volume{0,0}")

formatters={'@Date': 'datetime'}

)

fig.add_tools(hover)

# 8. 加入虛線十字游標 (建立水平與垂直方向的 Span 物件, 設定為 dashed 虛線)

w_span=Span(dimension="width", line_dash="dashed", line_color="gray", line_alpha=0.6, line_width=1)

h_span=Span(dimension="height", line_dash="dashed", line_color="gray", line_alpha=0.6, line_width=1)

fig.add_tools(CrosshairTool(overlay=[w_span, h_span]))

# 9. 輸出與顯示

show(fig)

結果如下 :

可見十字輔助線已經變成虛線了.

3. 消除非交日空缺 :

與 Plotly 一樣, Bokeh 在繪製 K 線圖時會自動把 yfinance 下載的 OHLCV 資料 X 軸的日期序列補齊, 使得 K 棒在非交易日無 K 棒出現不連續的空缺. Plotly 的 Figure 物件有內建的 rangebreaks 參數可用來隱藏這些空缺, 但 Bokeh 並沒有.

在 Bokeh 中可以用 Index Mapping 來解決此問題. 概念是不要把 X 軸當成時間, 而是把它當成連續的整數數列 (0, 1, 2, 3...), 然後透過一個標籤轉換器騙過使用者的眼睛, 讓 X 軸的數字顯示成對應的日期. 具體而言是透過 CustomJSTickFormatter 來實現, 但如果要維持原本 Bokeh 的 X 軸標籤顯示風格, 必須修改 Javascript 程式碼, 例如 :

# bokeh_candlestick_4.py

import yfinance as yf

import pandas as pd

from bokeh.plotting import figure, show

from bokeh.models import ColumnDataSource, HoverTool, CrosshairTool, Span, CustomJSTickFormatter

# 1. 下載真實 OHLCV 資料

df=yf.download('0050.tw', start='2026-03-01', end='2026-04-30', auto_adjust=True)

df.columns=df.columns.map(lambda x: x[0])

df=df.reset_index()

# 2. 建立連續整數序列

df['seq']=range(len(df))

# 用 Python 預先將日期轉為 Bokeh 風格的 "Apr 1" 格式

date_map={}

prev_year=None

for i, d in enumerate(df['Date']):

# 取得月份縮寫與日期 (例如 "Apr 1")

# strftime('%b') 會輸出英文月份縮寫，d.day 會輸出不補零的日期

label=f"{d.strftime('%b')} {d.day}"

# 如果是圖表的第一根 K 棒，或者是跨年的第一根 K 棒，在底下加上年份

# 使用 \n 來讓 Bokeh 產生換行效果

if i == 0 or d.year != prev_year:

label += f"\n{d.year}"

date_map[str(i)]=label

prev_year=d.year

# 3. 定義漲跌顏色

df['color']=['#ff0000' if c >= o else '#00aa00' for o, c in zip(df['Open'], df['Close'])]

# 4. 建立資料來源

source=ColumnDataSource(df)

# 5. 建立畫布

fig=figure(

title='0050.TW 台灣50 ETF K線圖 (完美日期標籤版)',

width=800,

height=400,

tools='xpan, xwheel_zoom, box_zoom, reset, save'

)

fig.grid.grid_line_alpha=0.3

# 6. 使用 JavaScript 取出排版好的字串

js_code="""

var idx=Math.round(tick).toString();

if (date_map[idx] !== undefined) {

return date_map[idx];

} else {

return "";

}

"""

fig.xaxis.formatter=CustomJSTickFormatter(code=js_code, args={'date_map': date_map})

# 把傾斜拿掉 (設為 0) 讓標籤恢復水平，這樣帶有 \n 年份的文字才會對齊

fig.xaxis.major_label_orientation=0

# 拉開標籤與 X 軸的間距 (預設通常是 5)

fig.xaxis.major_label_standoff=15

# 7. 繪製上下影線

fig.segment('seq', 'High', 'seq', 'Low', color="black", source=source)

# 8. 繪製 K 棒

width_val=0.8

fig.vbar('seq', width_val, 'Open', 'Close',

fill_color='color', line_color='black', source=source)

# 9. 加入互動式懸停工具

hover=HoverTool(

tooltips=[

("日期", "@Date{%F}"),

("開盤", "@Open{0.00}"),

("收盤", "@Close{0.00}"),

("最高", "@High{0.00}"),

("最低", "@Low{0.00}"),

("成交量", "@Volume{0,0}")

formatters={'@Date': 'datetime'}

)

fig.add_tools(hover)

# 10. 加入虛線十字游標

w_span=Span(dimension="width", line_dash="dashed", line_color="gray", line_alpha=0.6, line_width=1)

h_span=Span(dimension="height", line_dash="dashed", line_color="gray", line_alpha=0.6, line_width=1)

fig.add_tools(CrosshairTool(overlay=[w_span, h_span]))

# 11. 輸出與顯示

show(fig)

結果如下 :

不過這樣的程式碼看起來就有點複雜了.

Python 學習筆記 : 利用語言模型計算技術指標 (二)

2026-05-02T22:04:00.003+08:00

在前一篇測試中, 我們透過串接 LLM 模型 (OpenAI & Gemini) 要求 AI 生成計算技術指標的程式碼在本機執行運算, 毋須使用例如 Ta-Lib 或 ta, pandas-ta 等技術指標函式庫. 本篇旨在前一篇的基礎上取得 AI 生成的程式碼後算出技術指標 (MACD) 數據, 並繪製 K 線圖.

本系列全部測試文章索引參考 :

# Python 量化投資筆記索引

關於 MACD 技術指標計算, 參考 :

# Python 學習筆記 : 技術分析套件 pandas-ta 用法 (四)

1. 用 pandas_ta 套件計算 MACD 指標 :

MACD 由快線 (DIF), 慢線 (DEA) 和柱狀圖 (Histogram) 三部分組成, 當快速線向上突破訊號線時為買進訊號; 快速線向下跌破訊號線時為賣出訊號. 柱狀圖用來觀察市場動能強弱, 柱狀圖由負轉正表示多方動能變強; 柱狀圖由正轉負表示空方動能變強. 訊號線則是 MACD 快速線的平滑化版本, 用來確認趨勢是否開始反轉.

MACD 指標預設參數通常是快線 12 日, 慢線 26 日, 信號線 9 日, 以 pandas_ta 套件來說, 呼叫 df.ta.macd() 或 ta.macd() 即可計算這三組 MACD 指標數值. 注意, 在之前測試中呼叫 df.ta.macd() 時傳入 append=True, 這樣 pandas_ta 會將計算出來的 MACD 指標值自動插入 df 的新增欄位中, 預設欄位名稱依序是 MACD_12_26_9 (MACD 線), MACDh_12_26_9 (MACD 柱狀圖), 與 MACDs_12_26_9 (MACD 信號線), 為了後續繪製 K 線圖方便, 這次不使用 append=True 參數, 而是在 df 手動指定傳回的三個 Series 的欄位名稱 :

df[['MACD_line', 'MACD_histogram', 'MACD_signal']]=df.ta.macd(close='Close')

程式碼如下 :

# ai_stock_test_5.py

import yfinance as yf

import pandas as pd

import pandas_ta as ta

from kbar import KBar

if __name__ == "__main__":

df=yf.download('0050.tw', start='2024-11-06', end='2025-01-09', auto_adjust=True)

df.columns=df.columns.map(lambda x: x[0])

df[['MACD_line', 'MACD_histogram', 'MACD_signal']]=df.ta.macd(close='Close')

print(df.tail())

macd_line_name='MACD_line' # MACD 線

macd_signal_name='MACD_signal' # MACD 訊號線

macd_histogram_name='MACD_histogram' # MACD 柱狀圖

kb=KBar(df)

histogram_colors=['g' if v >= 0 else 'r' for v in df[macd_histogram_name]]

macd_panel=2

kb.addplot(

df[macd_histogram_name],

panel=macd_panel,

type='bar',

color=histogram_colors,

alpha=0.4,

ylabel='MACD' # 設定此副圖的 Y 軸標籤

)

kb.addplot(

df[macd_line_name],

panel=macd_panel, # 必須使用與柱狀圖相同的 Panel

color='fuchsia', # MACD 線顏色

width=1.0

)

kb.addplot(

df[macd_signal_name],

panel=macd_panel, # 必須使用與柱狀圖相同的 Panel

color='blue', # 信號線顏色

width=1.0

)

kb.plot(

volume=True, # 顯示成交量副圖 (Panel 1)

mav=(5, 10), # K 線圖上疊加 5 日和 10 日均線

title='K 線圖與 MACD 指標'

)

結果如下 :

>>> %Run ai_stock_test_5.py

[*********************100%***********************] 1 of 1 completed

Close High ... MACD_histogram MACD_signal

Date ...

2025-01-02 46.854988 47.241319 ... -0.011482 0.202802

2025-01-03 47.325832 47.555217 ... -0.023311 0.196974

2025-01-06 48.810799 48.847020 ... 0.063469 0.212842

2025-01-07 49.354084 49.740419 ... 0.147264 0.249658

2025-01-08 48.617638 49.100554 ... 0.142791 0.285355

[5 rows x 8 columns]

設定字型為: Microsoft JhengHei

使用指定字型: Microsoft JhengHei

字型候選清單: ['Microsoft JhengHei', 'DejaVu Sans', 'Arial']

2. 串接 OpenAI API 計算 SMA 指標 :

下面範例是用提示詞要求 LLM 提供 MACD 指標計算函式, 讓本地程式呼叫 exce() 來執行 MACD 計算函式, 最後用 kbar 套件繪製 K 線圖, 提示詞要明確給 LLM 計算 MACD 所需參數, 即快慢線與信號線週期, 另外, 為了後面用 kbar 繪製 K 線圖時取值與運算方便, 還需明確指定 MACD 傳回計算結果時的欄位名稱 :

計算 MACD 指標, 參數 : fast=12 日, slow=26 日, signal=9 日。

計算結果的欄位名稱 : MACD_line, MACD_signal, MACD_histogram。

請注意：務必在 ewm() 函式中設定 min_periods 參數（例如 slow 設為 min_periods=26），

以確保前期資料不足天數時，算出的結果必須是 NaN。

程式碼如下 :

# ai_stock_test_6.py

from openai import OpenAI, APIError

import yfinance as yf

import pandas as pd

import pandas_ta as ta

from dotenv import dotenv_values

from kbar import KBar

def ask_gpt(

messages: list[dict[str, str]],

model: str='gpt-3.5-turbo'

) -> str:

try:

reply=client.chat.completions.create(

model=model,

messages=messages

)

return reply.choices[0].message.content or ''

except APIError as e:

return e.message

def ai_helper(df, user_msg):

role=f'''

作為一個專業的程式碼生成機器人，

我需要您的協助來根據特定的用戶需求生成 Python 程式碼。

為了進行下去，我將提供給您一個遵循格式 {list(df.columns)} 的 DataFrame（df）。

您的任務是仔細分析用戶的需求並相應地生成 Python 程式碼。

請注意，您的回應須僅包含代碼本身，並且不應包含任何額外的資訊。

'''

# 把 user_msg 加入到 task 的敘述中，讓 AI 知道要算什麼

task=f'''

您的任務是開發一個名為 'calculate(df)' 的 Python 函式。

這個函式應接受一個 DataFrame 作為其參數。確保您僅使用資料集中存在的欄，

特別是 {list(df.columns)}。

用戶的具體運算需求為：【 {user_msg} 】

處理後，該函式應返回處理過的 DataFrame。

您的回應應嚴格包含 'calculate(df)' 函式的 Python 程式碼，

並排除任何無關的內容。

'''

msg=[{"role": "system", "content": role},

{"role": "user", "content": task}]

reply_data=ask_gpt(msg)

# 清理 markdown 語法

cleaned_code=reply_data.replace("```", "")

cleaned_code=cleaned_code.replace("python", "")

cleaned_code=cleaned_code.strip() # 建議加上 strip() 去除頭尾多餘的空白或換行

# 傳回程式碼

return cleaned_code

if __name__ == "__main__":

config=dotenv_values('.env')

openai_api_key=config.get('OPENAI_API_KEY')

client=OpenAI(api_key=openai_api_key)

df=yf.download('0050.tw', start='2024-11-06', end='2025-01-09', auto_adjust=True)

df.columns=df.columns.map(lambda x: x[0])

prompt='''

計算 MACD 指標, 參數 : fast=12 日, slow=26 日, signal=9 日。

計算結果的欄位名稱 : MACD_line, MACD_signal, MACD_histogram。

請注意：務必在 ewm() 函式中設定 min_periods 參數（例如 slow 設為 min_periods=26），

以確保前期資料不足天數時，算出的結果必須是 NaN。

'''

code_str=ai_helper(df, prompt)

print(code_str)

exec(code_str)

df=calculate(df)

print(df.tail())

macd_line_name='MACD_line' # 快速線

macd_signal_name='MACD_signal' # 訊號線

macd_histogram_name='MACD_histogram' # 柱狀圖

kb=KBar(df)

histogram_colors=['g' if v >= 0 else 'r' for v in df[macd_histogram_name]]

macd_panel=2

kb.addplot(

df[macd_histogram_name],

panel=macd_panel,

type='bar',

color=histogram_colors,

alpha=0.4,

ylabel='MACD' # 設定此副圖的 Y 軸標籤

)

kb.addplot(

df[macd_line_name],

panel=macd_panel, # 必須使用與柱狀圖相同的 Panel

color='fuchsia', # MACD 線顏色

width=1.0

)

kb.addplot(

df[macd_signal_name],

panel=macd_panel, # 必須使用與柱狀圖相同的 Panel

color='blue', # 信號線顏色

width=1.0

)

kb.plot(

volume=True, # 顯示成交量副圖 (Panel 1)

mav=(5, 10), # K 線圖上疊加 5 日和 10 日均線

title='K 線圖與 MACD 指標'

)

執行結果如下 :

>>> %Run ai_stock_test_6.py

[*********************100%***********************] 1 of 1 completed

def calculate(df):

fast = 12

slow = 26

signal = 9

ema_fast = df['Close'].ewm(span=fast, min_periods=fast).mean()

ema_slow = df['Close'].ewm(span=slow, min_periods=slow).mean()

macd_line = ema_fast - ema_slow

signal_line = macd_line.ewm(span=signal, min_periods=signal).mean()

macd_histogram = macd_line - signal_line

df['MACD_line'] = macd_line

df['MACD_signal'] = signal_line

df['MACD_histogram'] = macd_histogram

return df

Close High ... MACD_signal MACD_histogram

Date ...

2025-01-02 46.854992 47.241323 ... 0.237614 -0.050295

2025-01-03 47.325832 47.555217 ... 0.223323 -0.055554

2025-01-06 48.810799 48.847020 ... 0.231812 0.033190

2025-01-07 49.354080 49.740415 ... 0.261899 0.118182

2025-01-08 48.617638 49.100554 ... 0.291621 0.117175

[5 rows x 8 columns]

設定字型為: Microsoft JhengHei

使用指定字型: Microsoft JhengHei

字型候選清單: ['Microsoft JhengHei', 'DejaVu Sans', 'Arial']

但是, 這結果與上面用 pandas_ta 計算出來的有些出入, 圖形大致是一致, 但仔細看 MACD 數據有些誤差, 我詢問 AI 這個 LLM 生成的 calculate() 算法是否正確, 結論是 : 讓 LLM 生成以 Pandas 為基礎的函式, 會與專業金融套件例如 pandas_ta 計算的結果有些出入, 因為它們在底層實作指數移動平均 (EMA) 遞迴公式時, 對第一天的 EMA 該怎麼決定有所分歧, Pandas 會直接拿資料陣列中的第一筆收盤價當作 EMA 的初始種子, 然後從第二天開始套用 EMA 公式; 而 pandas_ta 在計算 12 日 EMA 時會先精準計算前 12 天的簡單移動平均 (SMA)作為第 12 天的 EMA 初始種子, 然後從第 13 天開始才套用 EMA 公式.

在前一篇 SMA 測試不會出現因計算細節分岐產生的錯誤 (因為 SMA 沒有遞迴依賴, 也不需要初始種子), 只要指標名稱裡帶有 "E" (Exponential 指數型, 例如 EMA, MACD) 或者是 "S" / "W" (Smoothed / Weighted 平滑加權型, 例如 RSI, WMA), 在跨套件核對時往往就需要特別去確認底層對第一筆初始值的實作邏輯.

從以上測試得到一個教訓 : 金融計算應該用專業套件自行編碼, 不要靠提示詞叫 AI 生成, 如果直接執行這些未經審查的程式碼, 那麼計算出來的金融資料可能是錯誤的. 如果用 pandas_ta 一行指令就能搞定的事, 為何要用附帶許多注意事項的提示詞來要求 AI 生成可能計算出錯誤結果的程式碼? 本系列測試將到此為止, 量化投資程式在計算金融資訊部分還是要用專業套件去計算, 不要透過 AI.

Python 學習筆記 : 用 plotly 繪製 K 線圖 (二)

2026-05-01T23:17:00.014+08:00

在前一篇測試中已對 Plotly 的 K 線圖類別 plotly.graph_objects.CandleStick 的用法有了基本了解, 本篇旨在利用 Figure 物件的 add_trace() 方法在畫布上添加子圖 (例如成交量或 RSI 等技術指標), 同時透過 plotly.subplots.make_subplot() 函式來規劃畫布上的子圖佈局.

本系列測試文章索引參考 :

# Python 資料視覺化學習筆記索引

4. 添加成交量子圖 :

要在畫布上繪製子圖有兩種方式, 第一種是使用較低階的絕對領域 (Domain) 劃分法, 此方法須手動切割 Y 軸空間自行布局, 好處是可以客製化布局, 缺點是維護難度較高, 調整彈性較差, 在 "最強 AI 投資分析" 這本書的第四章就是採用此方法, 參考 :

# https://www.flag.com.tw/bk/t/f3933

第二種方式是使用 plotly.subplots.make_subplot() 函式, 這是採用網格系統來進行排版的高階 API, 只要指定子圖的列 (row) 與欄 (col), Plotly 會在底層自動計算所有圖表的高度, 對齊與間距, 是一種較簡易的低耦合設計.

首先匯入子圖布局函式 make_subplots() :

from plotly.subplots import make_subplots

make_subplots() 的參數說明如下表 :

參數名稱	說明
rows	子圖的列數（預設為 1）
cols	子圖的欄數（預設為 1）
shared_xaxes	是否共用 X 軸（True / False / 'all' / 'rows' / 'columns'）
shared_yaxes	是否共用 Y 軸（True / False / 'all' / 'rows' / 'columns'）
start_cell	子圖起始位置（'top-left' 或 'bottom-left'）
subplot_titles	每個子圖的標題（list）
specs	自訂每個子圖的型態與配置（例如 type='xy', 'domain', 'scene' 等）
row_heights	各列高度比例（list，例如 [0.7, 0.3]）
column_widths	各欄寬度比例（list，例如 [0.6, 0.4]）
horizontal_spacing	子圖之間的水平間距（0~1）
vertical_spacing	子圖之間的垂直間距（0~1）
insets	設定內嵌子圖（inset charts）的位置與大小
column_titles	每一欄的標題（list）
row_titles	每一列的標題（list）
x_title	整體 X 軸標題
y_title	整體 Y 軸標題
figure	將子圖加入既有的 Figure 物件

其中最常用的參數是 rows, cols, shared_xaxes, vertical_spacing, 與 row_heights 等.

下列程式將畫布做 2 列 1 欄布局, 第一列高度占 70% 放 K 線圖 trace; 第二列高度占 30% 放成交量長條圖 (有做漲紅跌綠顏色設定) :

# plotly_candlestick_5.py

import yfinance as yf

import plotly.graph_objects as go

import pandas as pd

from plotly.subplots import make_subplots

if __name__ == "__main__":

df=yf.download('0050.tw', start='2026-03-01', end='2026-04-30', auto_adjust=True)

df.columns=df.columns.map(lambda x: x[0])

# === 建立子圖 (2 rows: 上列放 K 線圖，下列放成交量) ===

fig=make_subplots(

rows=2,

cols=1,

shared_xaxes=True,

vertical_spacing=0.03,

row_heights=[0.7, 0.3] # 列高度占比

)

# === K 線圖 ===

price=go.Candlestick(

x=df.index,

open=df['Open'],

high=df['High'],

low=df['Low'],

close=df['Close'],

increasing_line_color='red',

decreasing_line_color='green',

name='Price'

)

fig.add_trace(price, row=1, col=1) # K 線圖放 row 1

# === 成交量顏色（漲紅跌綠） ===

colors=['red' if c >= o else 'green' for c, o in zip(df['Close'], df['Open'])]

volume=go.Bar(

x=df.index,

y=df['Volume'],

marker_color=colors,

name='Volume'

)

fig.add_trace(volume, row=2, col=1) # 成交量放 row 2

# === 移除非交易日 ===

date_range=pd.date_range(start=df.index.min(), end=df.index.max())

breaks=date_range[~date_range.isin(df.index)]

breaks_list=breaks.tolist()

fig.update_xaxes(

rangebreaks=[{'values': breaks_list}],

showspikes=True,

spikethickness=1,

spikecolor='blue',

spikedash='dot',

spikemode='across'

)

# === Y 軸 spike（兩個子圖都套用）===

fig.update_yaxes(

showspikes=True,

spikethickness=1,

spikecolor='blue',

spikedash='dot',

spikemode='across'

)

# === Layout ===

fig.update_layout(

title='台灣五十 (0050) K線 + 成交量',

width=800,

height=700,

xaxis_rangeslider_visible=False,

hovermode='x unified' # 很重要：跨子圖同步 hover

)

fig.show()

注意, 之前沒有子圖時是呼叫 fig=go.Figure() 建立 Figure 物件, 但此處是用 make_subplots() 來建立. 其次, 有子圖的情況時, hovermode 參數務必要設為 'x unified', 否則會有多個 tooltip 分散, 以及子圖之間不同步問題 (無子圖時因所有 trace 都在同一個座標系故不會有這些問題).

結果如下 :

5. 添加技術指標子圖 :

接下來要在成交量下面添加 MACD 指標, 使用 pandas-ta 套件計算, 參考 :

# Python 學習筆記 : 技術分析套件 pandas-ta 用法 (四)

這樣畫布上總共有三個子圖 : K 線圖, 成交量, 與 MACD.

程式碼如下 :

# plotly_candlestick_6.py

import yfinance as yf

import plotly.graph_objects as go

import pandas as pd

import pandas_ta as ta

from plotly.subplots import make_subplots

if __name__ == "__main__":

# === 下載資料 ===

df=yf.download('0050.tw', start='2026-03-01', end='2026-04-30', auto_adjust=True)

df.columns=df.columns.map(lambda x: x[0])

# === 計算 MACD（pandas-ta）===

macd=ta.macd(df['Close'], fast=12, slow=26, signal=9)

# pandas-ta 會回傳三欄 :contentReference[oaicite:0]{index=0}

df['MACD']=macd['MACD_12_26_9']

df['MACDs']=macd['MACDs_12_26_9'] # signal

df['MACDh']=macd['MACDh_12_26_9'] # histogram

# === 建立子圖 ===

fig=make_subplots(

rows=3,

cols=1,

shared_xaxes=True,

vertical_spacing=0.02,

row_heights=[0.5, 0.2, 0.3]

)

# =====================

# 1. K線圖

# =====================

fig.add_trace(

go.Candlestick(

x=df.index,

open=df['Open'],

high=df['High'],

low=df['Low'],

close=df['Close'],

increasing_line_color='red',

decreasing_line_color='green',

name='Price'

row=1, col=1

)

# =====================

# 2. 成交量

# =====================

vol_colors=['red' if c >= o else 'green'

for c, o in zip(df['Close'], df['Open'])]

fig.add_trace(

go.Bar(

x=df.index,

y=df['Volume'],

marker_color=vol_colors,

name='Volume'

row=2, col=1

)

# =====================

# 3. MACD

# =====================

# Histogram（紅綠柱）

macd_colors=['red' if v >= 0 else 'green' for v in df['MACDh']]

fig.add_trace(

go.Bar(

x=df.index,

y=df['MACDh'],

marker_color=macd_colors,

name='MACD Hist'

row=3, col=1

)

# MACD 線

fig.add_trace(

go.Scatter(

x=df.index,

y=df['MACD'],

line=dict(color='blue'),

name='MACD'

row=3, col=1

)

# Signal 線

fig.add_trace(

go.Scatter(

x=df.index,

y=df['MACDs'],

line=dict(color='orange'),

name='Signal'

row=3, col=1

)

# =====================

# 移除非交易日

# =====================

date_range=pd.date_range(start=df.index.min(), end=df.index.max())

breaks=date_range[~date_range.isin(df.index)]

fig.update_xaxes(

rangebreaks=[{'values': breaks.tolist()}],

showspikes=True,

spikethickness=1,

spikecolor='blue',

spikedash='dot',

spikemode='across'

)

fig.update_yaxes(

showspikes=True,

spikethickness=1,

spikecolor='blue',

spikedash='dot',

spikemode='across'

)

# =====================

# Layout

# =====================

fig.update_layout(

title='0050 台灣五十 - K線 + 成交量 + MACD',

width=900,

height=800,

xaxis_rangeslider_visible=False,

hovermode='x unified'

)

fig.show()

注意, MACD 的紅綠柱, MACD 線與信號線都是要畫在 row=3 子圖疊在一起, 結果如下 :

Python 學習筆記 : 用 plotly 繪製 K 線圖 (一)

2026-05-01T14:18:00.011+08:00

雖然 mplfinance 套件可以繪製精美的 K 線圖, 但那是沒有互動效果的靜態圖表, 也無法直接佈署在網頁應用中. 繪製互動式 K 線圖可以使用 plotly 套件的低階繪圖模組 graph_objects (注意, plotly.express 模組沒有繪製 K 線圖功能, 它主要用來快速繪製常見統計圖表).

本系列測試文章索引參考 :

# Python 資料視覺化學習筆記索引

關於 plotly.graph_objects 用法參考 :

# Python 學習筆記 : 用 plotly 繪製互動式圖表 (一)

1. 新版 (v4.0+) Plotly 的輸出方式 :

Plotly 的繪圖輸出方式已與以往不同, v4.0 之前的 Plotly 主要商業模式是線上繪圖, 預設會將圖表上傳到他們的雲端伺服器 (Chart Studio), 如果要離線繪圖必須明確呼叫 plotly.offline 模組; 然而 Plotly v4 對原本分散的繪圖方式 (離線 vs 雲端) 進行重整, 採取了離線優先原則, 繪製圖表時不需要再區分線上或離線 (原本的雲端功能被拆分出去變成一個獨立的套件 chart-studio), 改為直接呼叫 Figure 物件的方法來處理 :

fig.show() : 用於開發過程中的快速預覽 (依據環境自動選擇方式)
fig.write_html() : 用於產生最終的報告檔案 (於網頁中繪製圖表)

當呼叫 fig.show() 時, Plotly 會自動偵測程式是在 VS Code, Jupyter Notebook, Google Colab 還是純 Python 腳本中執行, 並選擇最適合的方式來顯示圖表. plotly.offline 的功能已經被 fig.write_html() 取代了, 但為了向下相容, Plotly 官方目前仍保留對 plotly.offline.plot() 的支援.

注意, fig.write_html() 只是單純輸出 HTML 檔, 不會自動開啟瀏覽器顯示繪圖結果, 如果希望在存檔後順便開啟瀏覽器展示繪製結果, 可以傳入 auto_open=True 參數 (預設 False), 例如 :

fig.write_html("plot.html", auto_open=True)

或者先呼叫 write_html() 再呼叫 show() :

fig.write_html("plot.html")

fig.show()

除此之外, Plotly v4.0 也把以前的獨立套件 plotly_express 納入主套件中成為 plotly.express 模組, 確立了 Plotly 未來高階 API 使用 plotly.express; 低階 API 使用 plotly. graph_objects 的雙軌應用模式.

2. 建立 CandleStick 物件繪製 K 線圖 :

首先匯入 plotly.graph_objects 模組, 通常取簡名為 go :

import plotly.graph_objects as go

plotly.graph_objects 模組中有一個 Candlestick 用來繪製 K 線圖 :

>>> import plotly.graph_objects as go

>>> dir(go)

['AngularAxis', 'Annotation', 'Annotations', 'Bar', 'Barpolar', 'Box', 'Candlestick', 'Carpet', 'Choropleth', 'Choroplethmap', 'Choroplethmapbox', 'ColorBar', 'Cone', 'Contour', 'Contourcarpet', 'Contours', 'Data', 'Densitymap', 'Densitymapbox', 'ErrorX', 'ErrorY', 'ErrorZ', 'Figure', 'FigureWidget', 'Font', 'Frame', 'Frames', 'Funnel', 'Funnelarea', 'Heatmap', 'Histogram', 'Histogram2d', 'Histogram2dContour', 'Histogram2dcontour', 'Icicle', 'Image', 'Indicator', 'Isosurface', 'Layout', 'Legend', 'Line', 'Margin', 'Marker', 'Mesh3d', 'Ohlc', 'Parcats', 'Parcoords', 'Pie', 'RadialAxis', 'Sankey', 'Scatter', 'Scatter3d', 'Scattercarpet', 'Scattergeo', 'Scattergl', 'Scattermap', 'Scattermapbox', 'Scatterpolar', 'Scatterpolargl', 'Scattersmith', 'Scatterternary', 'Scene', 'Splom', 'Stream', 'Streamtube', 'Sunburst', 'Surface', 'Table', 'Trace', 'Treemap', 'Violin', 'Volume', 'Waterfall', 'XAxis', 'XBins', 'YAxis', 'YBins', 'ZAxis', 'bar', 'barpolar', 'box', 'candlestick', 'carpet', 'choropleth', 'choroplethmap', 'choroplethmapbox', 'cone', 'contour', 'contourcarpet', 'densitymap', 'densitymapbox', 'funnel', 'funnelarea', 'heatmap', 'histogram', 'histogram2d', 'histogram2dcontour', 'icicle', 'image', 'indicator', 'isosurface', 'layout', 'mesh3d', 'ohlc', 'parcats', 'parcoords', 'pie', 'sankey', 'scatter', 'scatter3d', 'scattercarpet', 'scattergeo', 'scattergl', 'scattermap', 'scattermapbox', 'scatterpolar', 'scatterpolargl', 'scattersmith', 'scatterternary', 'splom', 'streamtube', 'sunburst', 'surface', 'table', 'treemap', 'violin', 'volume', 'waterfall']

呼叫 Candlestick 類別的建構式 Candlestick() 會建立一個 Candlestick 物件, 這在 Plotly 文件中被稱為 Trace 物件 (畫布上的數據內容, 例如一組 K 線). 一個完整的 Plotly 圖表 (Figure) 是由 data 和 layout 兩大部分組成的, 而 Candlestick 物件就是放在 data 清單中的一個成員.

Candlestick() 建構式的參數如下表 :

參數名稱	說明
x	時間序列數據（通常為日期字串或 datetime 物件）。
open	開盤價序列 (Open prices)。
high	最高價序列 (High prices)。
low	最低價序列 (Low prices)。
close	收盤價序列 (Close prices)。
increasing_line_color	上漲時 K 線外框與影線的顏色（例：'red'）。
decreasing_line_color	下跌時 K 線外框與影線的顏色（例：'green'）。
name	此數據序列在圖例中顯示的名稱。
text	滑鼠懸停時顯示的額外文字內容。
hoverinfo	設定懸停顯示的資訊內容（如 'all', 'x+y' 等）。
opacity	設定 K 線圖層的透明度（0.0 到 1.0）。
whiskerwidth	設定上下影線相對於 K 線實體寬度的比例。

其中前 7 個參數 x, open, high, low, close, 以及 increasing_line_color 與 decreasing_line_color (漲跌顏色, 漲紅跌綠) 最常用, 例如 :

>>> price=go.Candlestick(

x=['2026-05-01', '2026-05-02'],

open=[100, 110],

high=[115, 120],

low=[95, 105],

close=[110, 105],

increasing_line_color='red',

decreasing_line_color='green'

)

>>> type(price)

這樣就建立了一個 CandleStick 物件了. 接下來只要將此 trace 放入串列, 傳給 go.Figure() 的 data 參數即可建立 Figure 畫布物件 :

>>> fig=go.Figure(data=[price])

>>> type(fig)

最後呼叫 fig.show() 即可展示所繪製之圖表 :

>>> fig.show()

fig.show() 會開啟一個 127.0.0.1:port 的網頁來繪製圖表 :

可見當滑鼠移到 K 棒上時就會動態地彈出其 OHLC 價格資訊. 注意, Plotly 預設會在 K 線圖底下開啟一個範圍滑桿 (RangeSlider 物件), 可透過滑動或縮放來觀察不同時段的價格細節. 若想取消此預設之範圍滑桿, 可呼叫 fig.update_layout() 並傳入 xaxis_rangeslider_visible=False 參數 :

>>> fig.update_layout(xaxis_rangeslider_visible=False)

Figure({

'data': [{'close': [110, 105],

'decreasing': {'line': {'color': 'green'}},

'high': [115, 120],

'increasing': {'line': {'color': 'red'}},

'low': [95, 105],

'open': [100, 110],

'type': 'candlestick',

'x': [2026-05-01, 2026-05-02]}],

'layout': {'template': '...', 'xaxis': {'rangeslider': {'visible': False}}}

})

>>> fig.show()

fig.update_layout() 是 Plotly 中最核心的佈局控制方法, 它負責處理圖表內除了數據本身以外的所有視覺元素, 例如標題, 座標軸, 圖例及畫布大小等, 常用參數如下 :

參數名稱	說明
title	圖表標題。可傳入字串或 dict（包含 text, font, x, y 等屬性）。預設為 None。
width / height	設定畫布的寬度與高度（像素）。預設通常隨容器自動縮放。
xaxis / yaxis	設定座標軸屬性（如標題、範圍、網格）。例如 xaxis_title='時間'。
xaxis_rangeslider_visible	設定 X 軸下方的範圍滑桿是否顯示。預設值 True。
showlegend	是否顯示圖例。預設值：當有多組數據序列時為 True。
legend	設定圖例的位置與外觀（如 x, y 位置、orientation 'h' 或 'v'）。
margin	設定圖表與邊界的距離。傳入 dict(l, r, t, b) 分別代表左、右、上、下邊距。
template	設定圖表主題（如 'plotly_dark', 'ggplot2', 'seaborn' 等）。預設為 'plotly'。
hovermode	設定懸停資訊的觸發模式（'x', 'y', 'closest', False）。預設為 'closest'。
font	設定圖表全域字體（family, size, color）。預設字體依環境而定。
paper_bgcolor	設定整張畫布（紙張）的背景顏色。預設為 '#fff'。
plot_bgcolor	設定繪圖區域（座標軸內）的背景顏色。預設為 '#E5ECF6'。

這些參數中以 title, width, heigh, 與 showlegend 等最常用.

下面範例從 yfinance 取得股價資料後用 plotly 繪製 K 線圖 :

# plotly_candlestick_1.py

import yfinance as yf

import plotly.graph_objects as go

if __name__ == "__main__":

df=yf.download('0050.tw', start='2026-03-01', end='2026-04-30', auto_adjust=True)

df.columns=df.columns.map(lambda x: x[0])

price=go.Candlestick(

x=df.index,

open=df['Open'],

high=df['High'],

low=df['Low'],

close=df['Close'],

increasing_line_color='red',

decreasing_line_color='green'

)

fig=go.Figure(data=[price])

fig.update_layout(

title='台灣五十股價',

width=800,

height=600,

xaxis_rangeslider_visible=False

)

fig.show()

此處以 width 與 height 參數設定畫布尺寸, 以 title 設定圖表標題, 結果如下 :

3. 移除 K 線圖中的非交易日空格 :

仔細看上面範例中的 K 線圖, 會發現例假日股市休息, 從 yfinance 取得的收盤資料都會跳過這些日期, 只傳回交易日之資料, 但 Plotly 在繪製 K 線圖時會自動把 X 軸的日期序列補齊, 但因為無 OHLC 欄位值, 所以 K 棒為空格, 看起來不連續, 這可以透過呼叫 fig.update_xaxes() 方法, 並傳入rangebreaks 參數來移除, 其值為一個非交易日的日期串列的字典 (鍵為 values), 例如 :

# plotly_candlestick_2.py

import yfinance as yf

import plotly.graph_objects as go

import pandas as pd

if __name__ == "__main__":

df=yf.download('0050.tw', start='2026-03-01', end='2026-04-30', auto_adjust=True)

df.columns=df.columns.map(lambda x: x[0])

price=go.Candlestick(

x=df.index,

open=df['Open'],

high=df['High'],

low=df['Low'],

close=df['Close'],

increasing_line_color='red',

decreasing_line_color='green'

)

fig=go.Figure(data=[price])

# 移除 X 軸的非交易日

date_range=pd.date_range(start=df.index.min(), end=df.index.max())

breaks=date_range[~date_range.isin(df.index)] # 取出 df 空缺之日期

breaks_list=breaks.tolist() # 轉成串列

fig.update_xaxes(rangebreaks=[{'values': breaks_list}]) # 移除非交易日空缺

fig.update_layout(

title='台灣五十股價',

width=800,

height=600,

xaxis_rangeslider_visible=False

)

fig.show()

此處使用 Pandas 的 date_range() 函式取得 df 起迄日期間的所有連續日期序列, 然後用串列運算與 df 比對抓出 df 中空缺之日期即為非交易日, 轉成串列後做為字典 values 鍵之值. 結果如下 :

可見非交易日的空 K 棒已消失, 整個 K 線圖 X 軸看起來是連續無空缺了.

fig.update_xaxes() 常用參數如下表 :

參數名稱	說明
title	X 軸標題。可傳入字串或 dict(text='...', font=...)。
type	座標軸類型：'linear' (數值), 'date' (時間), 'category' (類別), 'log' (對數)。
range	設定顯示範圍 [min, max]，對於時間軸 ['2026-01-01', '2026-05-01']。
rangebreaks	隱藏特定時間區段（如週末或收盤時段）。常用於金融圖表。
rangeslider_visible	是否顯示底部的時間範圍滑桿（True/False）。
showgrid	是否顯示垂直網格線（True/False）。預設為 True。
gridcolor / gridwidth	設定網格線的顏色與寬度。
tickformat	設定刻度文字格式（如 '%Y-%m-%d' 顯示日期，'.2f' 顯示兩位小數）。
tickangle	刻度文字的旋轉角度（例如 -45 代表順時針旋轉 45 度）。
side	X 軸的位置。可設定為 'bottom' (預設) 或 'top'。
nticks	設定刻度的最大數量（Plotly 會嘗試在此範圍內自動分配）。
fixedrange	是否鎖定縮放（True 代表禁止使用者縮放該軸）。
showspikes	是否顯示 Y 軸輔助線。預設 False (不顯示)。
spikemode	X 軸輔助線模式 : 'toaxis' (預設指向坐標軸)、'across' (橫跨整個繪圖區)。
spikecolor	X 軸輔助線顏色 : 顏色名稱或色碼 (預設 None 視資料點自動指配)。
spikethickness	X 軸輔助線厚度 : 預設 3px。
spikedash	X 軸輔助線樣式 : 'dash' (預設), 'dot', 'solid'。

除了有 X 軸設定方法 fig.update_xaxes() 外, 還有 Y 軸設定方法 fig.update_yaxes(), 參數結構類似 :

參數名稱	說明
title	Y 軸標題。可設定為字串或 dict(text='...', font=...)。
type	座標軸類型：'linear' (預設)、'log' (對數軸)、'date'。
range	設定 Y 軸顯示數值範圍。例如 [0, 1000]。
autorange	是否自動縮放範圍：True, False 或 'reversed'（數值由大到小反轉）。
showgrid	是否顯示水平網格線（True/False）。
zeroline	是否加粗顯示數值為 0 的那條基準線。預設為 True。
tickformat	刻度數值格式。例如 ',d' (千分位整數)、'.2f' (兩位小數)、'%' (百分比)。
tickprefix / ticksuffix	在刻度數值前後加上符號（如 tickprefix='$' 或 ticksuffix='元'）。
side	Y 軸的位置。可設定為 'left' (預設) 或 'right' (常見於雙 Y 軸設計)。
secondary_y	多軸圖表中指定此資料是否為第二個 Y 軸（配合 make_subplots 使用）。
fixedrange	是否固定 Y 軸。設為 True 時，使用者無法透過滑鼠縮放 Y 軸方向。
showspikes	是否顯示 Y 軸輔助線。預設 False (不顯示)。
spikemode	Y 軸輔助線模式 : 'toaxis' (預設指向坐標軸)、'across' (橫跨整個繪圖區)。
spikecolor	Y 軸輔助線顏色 : 顏色名稱或色碼 (預設 None 視資料點自動指配)。
spikethickness	Y 軸輔助線厚度 : 預設 3px。
spikedash	Y 軸輔助線樣式 : 'dash' (預設), 'dot', 'solid'。

4. 添加輔助十字線 :

輔助十字線是當滑鼠在畫布上移動時會出現一個平行於 X 與 Y 軸十字線的互動效果, 開啟輔助十字線顯示需要將 fig.update_xaxes() 與 fig.update_yaxes() 的 showspike 參數設為 True. 例如 :

# plotly_candlestick_3.py

import yfinance as yf

import plotly.graph_objects as go

import pandas as pd

if __name__ == "__main__":

df=yf.download('0050.tw', start='2026-03-01', end='2026-04-30', auto_adjust=True)

df.columns=df.columns.map(lambda x: x[0])

price=go.Candlestick(

x=df.index,

open=df['Open'],

high=df['High'],

low=df['Low'],

close=df['Close'],

increasing_line_color='red',

decreasing_line_color='green'

)

fig=go.Figure(data=[price])

# 移除 X 軸的非交易日

date_range=pd.date_range(start=df.index.min(), end=df.index.max())

breaks=date_range[~date_range.isin(df.index)] # 取出 df 空缺之日期

breaks_list=breaks.tolist() # 轉成串列

fig.update_xaxes(rangebreaks=[{'values': breaks_list}],

showspikes=True)

fig.update_yaxes(showspikes=True)

fig.update_layout(

title='台灣五十股價',

width=800,

height=600,

xaxis_rangeslider_visible=False

)

fig.show()

此處將 X/Y 軸設定參數 showspikes 設為 True 後, 當滑鼠移到 K 棒上面時就會顯示指向座標軸的輔助線, 由於 spikemode 預設 'toaxis', 故輔助線是指向坐標軸, 而非貫穿繪圖區的十字線; 由於 spikecolor 預設為 None, 所以滑鼠移到紅 K 棒時輔助線為紅色, 移到綠 K 棒時輔助線為綠色 :

下面是傳入全部輔助線參數的範例 :

# plotly_candlestick_4.py

import yfinance as yf

import plotly.graph_objects as go

import pandas as pd

if __name__ == "__main__":

df=yf.download('0050.tw', start='2026-03-01', end='2026-04-30', auto_adjust=True)

df.columns=df.columns.map(lambda x: x[0])

price=go.Candlestick(

x=df.index,

open=df['Open'],

high=df['High'],

low=df['Low'],

close=df['Close'],

increasing_line_color='red',

decreasing_line_color='green'

)

fig=go.Figure(data=[price])

# 移除 X 軸的非交易日

date_range=pd.date_range(start=df.index.min(), end=df.index.max())

breaks=date_range[~date_range.isin(df.index)] # 取出 df 空缺之日期

breaks_list=breaks.tolist() # 轉成串列

fig.update_xaxes(rangebreaks=[{'values': breaks_list}],

showspikes=True,

spikethickness=1,

spikecolor='blue',

spikedash='dot',

spikemode='across')

fig.update_yaxes(showspikes=True,

spikethickness=1,

spikecolor='blue',

spikedash='dot',

spikemode='across')

fig.update_layout(

title='台灣五十股價',

width=800,

height=600,

xaxis_rangeslider_visible=False,

#hovermode='x'

)

fig.show()

此例傳入輔助線參數更改預設值, 結果如下 :

可見 spikethickness=1 讓輔助線變細了, spikecolor='blue' 則使其顏色不論紅 K 或綠 K 都顯示藍色; 而 spikemode='across' 則使輔助線貫穿整個畫布成為名符其實的十字線. 注意, 預設須當滑鼠移到 K 棒上時才會顯示輔助線, 如果要讓滑鼠在畫布任何位置都顯示輔助線, 則在呼叫 fig.update_layout() 要傳入 hovermode='x' 參數, 因為 K 線圖是按時間 (X 軸) 排列的, 每一格時間通常都有資料, 所以滑鼠左右移動時, 輔助線會非常流暢地跟隨.

momo 購買泰達椅 Pro

2026-05-01T00:38:00.001+08:00

因下周要帶爸與岳父母去沖繩旅遊, 為了在排隊時沒椅子坐, 上 momo 買了僅 1 kg 的泰達椅 Pro :

滿一件折 350, 還另送 350 元 momo 幣 :

實付 2630 元, 送 momo 幣 350 元, 實際上只花 2280 元.

momo 購買小米 20000 mAh 行動電源

2026-04-30T11:53:00.005+08:00

因下周要帶爸與岳父母去沖繩玩, 今天上網買了一顆小米行動電源 :

# 小米官方旗艦館 PB2020MI 自帶線行動電源 20000 22.5W 2孔輸出(USB-A/USB-C 可充/自帶線/74Wh) $599

100Wh 以下可帶上飛機

用掉 74 元 momo 幣實付 525 元.

(補記) 購買 HiSKIO 課程 : Claude Code 深度應用

2026-04-30T11:42:00.001+08:00

我可能線上課程買太多買到頭昏了, 最近在臉書看到一門 Claude Code 課程 56 折即將結束, 趁中午截止前上網想先買下 (雖然可能要半年後才會開啟 Claude Code 付費) :

# https://hiskio.com/courses/2475

沒想到登入 HiSKIO 赫然看到網站提醒 : 你已購買本課程! 蝦米? 查了訂購記錄, 這門課我今年 2/6 就買了, 當時可能一忙忘了記下來. 這就像我存摺有很多本 (但也不至於到 100 本啦) 藏錢都藏到忘記自己很有錢了. 補記一下免得又忘記了 :

我在 HiSKIO 目前就只有林彥文老師的 "Vibe Coding 全能實戰課" (已上完, 要複習) 與這堂 Claude Code 課, 等沖繩回來要開始上課了 (還有 TibaMe 與 Hahow 的呵呵).

Python 學習筆記 : 用 plotly 繪製互動式圖表 (三)

2026-04-30T10:07:00.005+08:00

本篇旨在測試 Plotly 的圖表匯出功能.

本系列之前的測試文章參考 :

# Python 學習筆記 : 用 plotly 繪製互動式圖表 (一)

# Python 學習筆記 : 用 plotly 繪製互動式圖表 (二)

更多 Python 資料視覺化學習筆記參考 :

# Python 資料視覺化學習筆記索引

Plotly 支援多種檔案類型匯出, 可呼叫下表中 Figure 物件的方法匯出 :

Figure 物件的檔案匯出方法	說明
fig.write_image(file, **kwargs)	匯出為靜態圖片（PNG、JPEG、SVG、PDF 等），需安裝 `kaleido`
fig.write_html(file, **kwargs)	匯出為互動式 HTML 檔，可直接用瀏覽器開啟
fig.to_html(full_html=True, include_plotlyjs='cdn')	將圖表轉為 HTML 字串（用於網頁內嵌或 API 回傳）
fig.to_json()	將圖表轉為 JSON 格式（適合儲存、API 傳遞、版本控管）
fig.write_json(file)	將圖表 JSON 結構直接寫入檔案
fig.to_dict()	將圖表轉為 Python 字典格式，可進一步程式操作

注意, fig.write_image() 方法須依賴 kaleido 模組, 這是 Plotly 官方推出的匯圖引擎模組, 用來將 Plotly 圖表儲存為靜態圖片.

1. 匯出圖檔 :

呼叫 Figure 物件的 write_image() 方法可將繪製的圖表匯出成圖片檔 (支援 PNG, JPG, SVG, PDF 等檔案類型), 其參數結構如下 :

fig.write_image(

file, # 必填，檔案路徑字串或類似檔案的物件

format=None, # 圖片格式，如 'png'、'jpeg'、'svg'、'pdf'，若省略會自動從副檔名判斷

width=None, # 圖片寬度（像素），預設為圖表原始寬度

height=None, # 圖片高度（像素），預設為圖表原始高度

scale=1, # 圖片縮放倍數（例如 2 表示解析度加倍）

validate=True, # 是否檢查圖表是否有效（預設 True）

engine='kaleido' # 使用的圖像引擎，預設為 'kaleido'

)

不過使用此方法之前須先安裝 Plotly 的 kaleido 模組, 而且 plotly 也要提升至最新版 :

pip install kaleido

pip install plotly -U

在前一篇測試中使用了 plotly.express 來繪製長條圖, 下列沿用此範例來匯出所繪製的圖檔 :

# plotly_chart_export_1.py

import plotly.express as px

import pandas as pd

import os

# 1. 資料來源

data={

'月份': ['一月', '二月', '三月', '四月', '五月'],

'營收': [120000, 135000, 99000, 150000, 170000]

}

# 2. 建立 Figure 圖表物件

# 注意：這裡設定了 width 和 height，匯出圖片時會以此為基準

fig=px.bar(data, x='月份', y='營收', width=800, height=600, title="月營收統計圖")

# 3. 顯示圖表 (選用)

fig.show()

# 4. 匯出圖檔

# 建立儲存目錄（選用，避免檔案雜亂）

if not os.path.exists("output"):

os.mkdir("output")

# 匯出為 PNG

fig.write_image("output/revenue_report.png", scale=2)

# 匯出為 JPG

fig.write_image("output/revenue_report.jpg", scale=2)

print("圖檔已匯出至 output 資料夾中。")

執行結果除了 fig.show() 會開啟瀏覽器顯示長條圖外, 也會在目前工作目錄下建立 output 子目錄存放匯出的兩個圖檔 :

>>> %Run plotly_chart_export_1.py

圖檔已匯出至 output 資料夾中。

2. 匯出網頁 :

呼叫 fig.write_html() 可將繪製之圖表匯出為 HTML 檔, 若傳入 include_plotlyjs='cdn' 參數會使用 CDN 的 plotly 函式庫, 這樣匯出的 HTML 檔較小但須連網才能看到互動圖表; 否則會將 plotly 函式庫一同匯出, 檔案較大些 (約 4MB) 但不須連網, 離線開啟網頁即可看到互動圖表.

程式碼如下 :

# plotly_chart_export_2.py

import plotly.express as px

import pandas as pd

import os

# 1. 資料來源

data={

'月份': ['一月', '二月', '三月', '四月', '五月'],

'營收': [120000, 135000, 99000, 150000, 170000]

}

# 2. 建立 Figure 圖表物件

fig=px.bar(data, x='月份', y='營收', width=800, height=600, title="月營收統計圖 (互動式 HTML)")

# 3. 建立儲存目錄

output_dir="output"

if not os.path.exists(output_dir):

os.makedirs(output_dir)

# --- 匯出 HTML ---

# 方式 A：標準匯出 (將 Plotly.js 核心程式碼打包進去，檔案約 4 MB，可離線開啟)

fig.write_html(os.path.join(output_dir, "report_full.html"))

# 方式 B：輕量化匯出 (使用 CDN 連結，檔案僅約 50KB，開啟時需連網載入 JS)

fig.write_html(

os.path.join(output_dir, "report_cdn.html"),

include_plotlyjs='cdn'

)

print(f"✅ HTML 檔案已匯出至 {output_dir} 資料夾。")

print("- report_full.html (可離線檢視)")

print("- report_cdn.html (體積小，需連網)")

# 顯示圖表

fig.show()

執行結果如下 :

>>> %Run plotly_chart_export_2.py

✅ HTML 檔案已匯出至 output 資料夾。

- report_full.html (可離線檢視)

- report_cdn.html (體積小，需連網)

開啟 output 資料夾下的網頁檔即可看到長條圖 :

Python 學習筆記 : 利用語言模型計算技術指標 (一)

2026-04-29T23:44:00.012+08:00

最近重讀旗標出版的 "最強 AI 投資分析" 這本書, 此書於 2023 年底買來看了前幾章便擱下, 也沒時間做測試, 今天重讀第四章後, 決定動手來測試看看, 因為去年 10/7 儲值 5 美元的 OpenAI API Key 目前只用了 0.01 美元, 只剩半年就要被清零了, 得在這之前趕快用掉 (在 Vibe coding 時代親自寫程式已淪落為純興趣了).

# https://platform.openai.com/settings/organization/billing/overview

書中範例程式碼下載網址 :

# https://www.flag.com.tw/bk/t/f3933

1. 利用 pandas_ta 計算 SMA 指標 :

首先用 pandas_ta 來計算移動平均指標 SMA8 與 SMA13 暖暖身, 畢竟已有近半年沒接觸了, 關於 pandas_ta 套件用法參考 :

# Python 量化投資筆記索引

下列程式使用 yfinance 取得收盤資料, 然後用 pandas_ta 套件的擴展屬性用法呼叫 df.ta.ma() 計算 SMA 指標, 結果會自動放入 df 的指定欄位, 最後用 kbar 套件繪製 K 線圖, 關於 kbar 套件用法參考 :

# https://github.com/tony1966/kbar

# ai_stock_test_1.py

import yfinance as yf

import pandas as pd

import pandas_ta as ta

from kbar import KBar

if __name__ == "__main__":

df=yf.download('0050.tw', start='2024-07-01', end='2024-08-21', auto_adjust=True)

df.columns=df.columns.map(lambda x: x[0])

df['SMA_8']=df.ta.sma(length=8)

df['SMA_13']=df.ta.sma(length=13)

print(df.tail())

kb=KBar(df)

kb.addplot(df['SMA_8'], panel=2, ylabel='SMA_8')

kb.addplot(df['SMA_13'], panel=2, ylabel='SMA_13')

kb.plot(volume=True, mav=[8, 13])

此處除了在 panel 2 上繪製 SMA8 與 SMA13 指標外, 同時也在 plot() 方法中指定 mav=[8, 13] 繪製 K 線圖之疊圖 (預設 panel=0), 結果如下 :

>>> %Run ai_stock_test_1.py

[*********************100%***********************] 1 of 1 completed

Close High Low ... Volume SMA_8 SMA_13

Date ...

2024-08-14 43.643597 43.909202 43.450429 ... 74857276 41.775311 42.438161

2024-08-15 43.305553 43.703958 43.233115 ... 45926588 42.397066 42.414943

2024-08-16 44.283455 44.343819 44.029927 ... 52823660 42.876964 42.466949

2024-08-19 44.343822 44.597354 44.223093 ... 37122372 43.163695 42.518955

2024-08-20 44.367966 44.718080 44.355892 ... 43139504 43.562101 42.514312

[5 rows x 7 columns]

設定字型為: Microsoft JhengHei

使用指定字型: Microsoft JhengHei

字型候選清單: ['Microsoft JhengHei', 'DejaVu Sans', 'Arial']

2. 串接 OpenAI API 計算 SMA 指標 :

接下來要串接 OpenAI API, 讓 LLM 模型來生成計算技術指標的程式碼後, 用 exec() 執行該程式碼計算技術指標, 好處是毋須去熟悉例如 pandas_ta, ta, 或 Ta-Lib 套件之函式呼叫介面, 直接用自然語言來指揮 LLM 傳回技術指標計算式, 做法參考書中 ˋ4-1 的範例 :

# 讓 AI 自動生成技術指標的程式碼

原程式碼的提示詞使用英文, 作者說經測試使用英文較能得到穩定之回應, 但現在 LLM 日新月異, 對中文的理解能力已非常精準, 因此我將其改寫為中文提示詞, 程式碼如下 :

# ai_stock_test_2.py

from openai import OpenAI, APIError

import yfinance as yf

import pandas as pd

from dotenv import dotenv_values

from kbar import KBar

def ask_gpt(

messages: list[dict[str, str]],

model: str='gpt-3.5-turbo'

) -> str:

try:

reply=client.chat.completions.create(

model=model,

messages=messages

)

return reply.choices[0].message.content or ''

except APIError as e:

return e.message

def ai_helper(df, user_msg):

role=f'''

作為一個專業的程式碼生成機器人，

我需要您的協助來根據特定的用戶需求生成 Python 程式碼。

為了進行下去，我將提供給您一個遵循格式 {list(df.columns)} 的 DataFrame（df）。

您的任務是仔細分析用戶的需求並相應地生成 Python 程式碼。

請注意，您的回應須僅包含代碼本身，並且不應包含任何額外的資訊。

'''

# 把 user_msg 加入到 task 的敘述中，讓 AI 知道要算什麼

task=f'''

您的任務是開發一個名為 'calculate(df)' 的 Python 函式。

這個函式應接受一個 DataFrame 作為其參數。確保您僅使用資料集中存在的欄，

特別是 {list(df.columns)}。

用戶的具體運算需求為：【 {user_msg} 】

處理後，該函式應返回處理過的 DataFrame。

您的回應應嚴格包含 'calculate(df)' 函式的 Python 程式碼，

並排除任何無關的內容。

'''

msg=[{"role": "system", "content": role},

{"role": "user", "content": task}]

reply_data=ask_gpt(msg)

# 清理 markdown 語法

cleaned_code=reply_data.replace("```", "")

cleaned_code=cleaned_code.replace("python", "")

cleaned_code=cleaned_code.strip() # 建議加上 strip() 去除頭尾多餘的空白或換行

# 傳回程式碼

return cleaned_code

if __name__ == "__main__":

config=dotenv_values('.env')

openai_api_key=config.get('OPENAI_API_KEY')

client=OpenAI(api_key=openai_api_key)

df=yf.download('0050.tw', start='2024-07-01', end='2024-08-21', auto_adjust=True)

df.columns=df.columns.map(lambda x: x[0])

code_str=ai_helper(df, "計算 8 日 MA (欄名 SMA_8) 與 13 日 MA (欄名 SMA_13)")

print(code_str)

exec(code_str)

new_df=calculate(df)

print(new_df.tail())

kb=KBar(new_df)

kb.addplot(new_df['SMA_8'], panel=2, ylabel='SMA_8')

kb.addplot(new_df['SMA_13'], panel=2, ylabel='SMA_13')

kb.plot(volume=True, mav=[8, 13])

此程式的 ask_gpt() 函式負責向 GPT 提問並取得回應, 注意, ask_gpt() 的傳入參數都使用了類型提示語法以增加程式碼可讀性. 例如 ask_gpt() 中的 messages: list[dict[str, str]] 意思是 :

messages 是一個串列, 裡面的每個元素都是字典.
字典的鍵與值都是字串, 例如 {"role": "user", "content": "hello"}

參考 :

# AI 應用程式專案 (一) : 新聞稿生成器

而 ai_helper() 函式則負責組裝提示詞 (字典串列) 並呼叫 ask_gpt(), 取得回應的指標計算程式碼後進行清理, 傳回純淨之 Python 程式碼給主函式以 exec() 執行, 結果如下 :

>>> %Run ai_stock_test_2.py

[*********************100%***********************] 1 of 1 completed

def calculate(df):

df['SMA_8'] = df['Close'].rolling(window=8).mean()

df['SMA_13'] = df['Close'].rolling(window=13).mean()

return df

Close High Low ... Volume SMA_8 SMA_13

Date ...

2024-08-14 43.643597 43.909202 43.450429 ... 74857276 41.775311 42.438161

2024-08-15 43.305553 43.703958 43.233115 ... 45926588 42.397066 42.414943

2024-08-16 44.283455 44.343819 44.029927 ... 52823660 42.876964 42.466949

2024-08-19 44.343822 44.597354 44.223093 ... 37122372 43.163695 42.518955

2024-08-20 44.367966 44.718080 44.355892 ... 43139504 43.562101 42.514312

[5 rows x 7 columns]

設定字型為: Microsoft JhengHei

使用指定字型: Microsoft JhengHei

字型候選清單: ['Microsoft JhengHei', 'DejaVu Sans', 'Arial']

計算出來的 SMA 數值與用 pandas_ta 計算的結果相同, 可見即使沒學過技術指標套件, 也可以利用 LLM 來進行技術指標的量化分析.

3. 串接 Gemini API 計算 SMA 指標 :

Gemini 版本的函式要改成 ask_gemini(), 而 ai_helper() 函式基本不變, 只有提示詞類型不同, OpenAI 的提示詞為字典字串, 而 Gemini 則是純字串. 程式碼如下 :

# ai_stock_test_3.py

from google import genai

from google.genai.errors import APIError

import yfinance as yf

import pandas as pd

from dotenv import dotenv_values

from kbar import KBar

def ask_gemini(messages: str, model: str='gemini-2.5-flash') -> str:

try:

reply=client.models.generate_content(

model=model,

contents=messages

)

return reply.text or ''

except APIError as e:

return e.message

def ai_helper(df, user_msg):

role=f'''

作為一個專業的程式碼生成機器人，

我需要您的協助來根據特定的用戶需求生成 Python 程式碼。

為了進行下去，我將提供給您一個遵循格式 {list(df.columns)} 的 DataFrame（df）。

您的任務是仔細分析用戶的需求並相應地生成 Python 程式碼。

請注意，您的回應須僅包含代碼本身，並且不應包含任何額外的資訊。

'''

task=f'''

您的任務是開發一個名為 'calculate(df)' 的 Python 函式。

這個函式應接受一個 DataFrame 作為其參數。確保您僅使用資料集中存在的欄，

特別是 {list(df.columns)}。

用戶的具體運算需求為：【 {user_msg} 】

處理後，該函式應返回處理過的 DataFrame。

您的回應應嚴格包含 'calculate(df)' 函式的 Python 程式碼，

並排除任何無關的內容。

'''

# Gemini 的提示詞為字串型態 : 將系統設定與任務直接合併成一段完整的字串

msg=f"{role}\n\n{task}"

# 呼叫 ask_gemini

reply_data=ask_gemini(msg)

# 清理傳回 markdown 語法

cleaned_code=reply_data.replace("```", "")

cleaned_code=cleaned_code.replace("python", "")

cleaned_code=cleaned_code.strip() # 去除頭尾多餘的空白或換行

# 傳回程式碼

return cleaned_code

if __name__ == "__main__":

config=dotenv_values('.env')

gemini_api_key=config.get('GEMINI_API_KEY')

client=genai.Client(api_key=gemini_api_key)

df=yf.download('0050.tw', start='2024-07-01', end='2024-08-21', auto_adjust=True)

df.columns=df.columns.map(lambda x: x[0])

code_str=ai_helper(df, "計算 8 日 MA (欄名 SMA_8) 與 13 日 MA (欄名 SMA_13)")

print(code_str)

exec(code_str)

new_df=calculate(df)

print(new_df.tail())

kb=KBar(new_df)

kb.addplot(new_df['SMA_8'], panel=2, ylabel='SMA_8')

kb.addplot(new_df['SMA_13'], panel=2, ylabel='SMA_13')

kb.plot(volume=True, mav=[8, 13])

結果與上面是一樣的 :

>>> %Run ai_stock_test_3.py

[*********************100%***********************] 1 of 1 completed

import pandas as pd

def calculate(df):

"""

計算 8 日 MA (欄名 SMA_8) 與 13 日 MA (欄名 SMA_13)。

Args:

df (pd.DataFrame): 包含 'Close', 'High', 'Low', 'Open', 'Volume' 欄位的 DataFrame。

Returns:

pd.DataFrame: 處理後包含 'SMA_8' 和 'SMA_13' 欄位的 DataFrame。

"""

df['SMA_8'] = df['Close'].rolling(window=8).mean()

df['SMA_13'] = df['Close'].rolling(window=13).mean()

return df

Close High Low ... Volume SMA_8 SMA_13

Date ...

2024-08-14 43.643597 43.909202 43.450429 ... 74857276 41.775310 42.438160

2024-08-15 43.305553 43.703958 43.233115 ... 45926588 42.397066 42.414943

2024-08-16 44.283459 44.343823 44.029930 ... 52823660 42.876964 42.466949

2024-08-19 44.343822 44.597354 44.223093 ... 37122372 43.163696 42.518955

2024-08-20 44.367966 44.718080 44.355892 ... 43139504 43.562102 42.514312

[5 rows x 7 columns]

設定字型為: Microsoft JhengHei

使用指定字型: Microsoft JhengHei

字型候選清單: ['Microsoft JhengHei', 'DejaVu Sans', 'Arial']

市圖還書兩本 (React)

2026-04-28T10:30:00.007+08:00

前陣子因為在 Vibe Coding 開發中, 發現 AI 經常使用 React 作為前端框架, 於是興起一股學學看的念頭, 從市圖借來幾本 React 的書, 沒有打算深入研究, 只想對核心運作有個基本認識. 不過還沒開卷呢, 下面兩本已被預約須還 :

No.1 作者是 ReacJS 新聞站長, 此書雖較舊了, 但前半部有豐富的 ES6 語法介紹; No.2 書況極新 (2024 年出版), 內容也更豐富, 包含伺服端 React, 與 Next.js 框架等, 下次再回借.

2026 年第 16 周記事

2026-04-26T22:51:00.009+08:00

週五天氣轉陰, 下班時差點淋到雨, 傍晚回鄉下時開始下起小雨, 整個晚上都在下, 甚至連周六也是下整天, 雨天無訪客剛好在家趕 SDD 線上課程的作業, 花了整整一天終於在周六晚上午夜關檔前完成作業上傳, 好險! 45 個學員也只有 9 個趕上截止期限 (我是最後一個哈哈).

幸好今天出太陽, 趕緊將沙發罩洗好拿去曬, 因下周大帥與仲仔要造訪鄉下家, 得事先整理一下客廳. 下午把馬路邊的三棵芒果樹都套袋完畢, 約莫 60 顆左右, 樹梢還有很多太高無法套袋, 下周要去小漢買網子攤開綁在樹下, 這樣等自然熟掉下來時才不會摔壞.

由於雨季即將來臨, 蔥價會攀高, 早上跑了一趟種子行買了 20 株青蔥苗+一株九層塔+六株皇宮菜, 年初種了一盆香菜長不好, 傍晚全部拔掉改種青蔥, 九層塔也是盆栽, 皇宮菜則暫時放著澆水, 小舅五月初要叫小耕耘機把菜園的土翻一遍, 說之後保留兩畦給他秋天時種小番茄, 其餘我要種菜或種果樹均好, 因為他家那邊也有一個菜園要顧 (去年他朋友借他使用). 菜園南側因為較遠, 種菜澆水較不便, 打算再種兩棵芭樂樹與木瓜樹.

毛小妹第二胎 (也是四隻) 小貓現在都在室外了, 這梯都很怕人不親, 我一靠近就跑掉. 上一梯的四隻目前只剩小黑與吉哇哇在家, 小乖與哇哇吉都離家超過一個月不回來了. 毛小妹的妹妹捲尾阿姨我也一周未見她出現, 恐怕也不回來了. 雖說不回來, 其實我認為它們應該都是遇險 (中毒/車禍) 回不來.

車庫雜物實在太多了, 等沖繩回來得來個斷捨離大清理了.

Gemini CLI 學習筆記 : OpenSpec 初體驗 (三)

2026-04-25T22:17:00.007+08:00

離作業交卷只剩 2.5 小時, 刻不容緩繼續進行第三次迭代.

本系列全部測試文章參考 :

# Gemini CLI 學習筆記索引

第三次迭代要在前次基礎上添加對數與三角函數科學計算功能, 同樣使用逐步推進模式, 工作流所需指令如下 :

/opsx:new <iteration_name> (建立迭代之專屬的工作區)
/opsx:propose <requirements> (依需求起草提案書, 規格定義書, 架構設計書, 與任務清單)
/opsx:apply <iteration_name> (依照 tasks.md 中的任務清單逐一實作此迭代功能)
/opsx:archive (迭代完成歸檔)

廢話不多說以免誤了軍期, 馬上開工.

1. 建立迭代之專屬工作區 :

第三次迭代工作區取名為 calc-scientific :

> /opsx:new calc-scientific

... (略) ...

2. 根據需求填寫提案書 :

> /opsx:propose "在現有計算器專案上擴充科學計算功能, 包含三角函數 (sin, cos, tan) 與對數 (以 10 為底的 log, 以及自然對數 ln), 請務必處理以下邊界與轉換邏輯：1. 三角函數的輸入值預設為「角度 (Degree)」, 後端需自行轉換為弧度進行計算, 2. 處理 tan(90) 等無效角度的防呆機制, 3. 對數運算需阻擋小於或等於 0 的無效輸入, 並回傳明確的 HTTP 錯誤, 4. 前端介面需優雅地加入這些新按鈕. "

... (略) ...

3. 依據任務清單實作程式碼 :

> /opsx:apply calc-scientific

... (略) ...

完成專案實作馬上作人工測試, 開啟 127.0.0.1:5000 網頁果然多了很多科學計算按鈕 :

輸入 30 或 390 按 sin 都會得到正確結果 0.5 :

輸入 -30 按 sin 也得到正確結果 -0.5 :

接下來做 cos 的精度測試, 輸入 90 按 cos 得到一個接近 0 的極小值而非 0, 這是因為我們忘了要 AI 做微小誤差抹零處理之故, 可以在後續迭代中處理掉. 做對數測試, 輸入 1 按 log 得到正確 0, 輸入 0 按 log 則得到 Error (無限大) :

4. 歸檔結案 :

> /opsx: archive

... (略) ...

第三次迭代歸檔完畢, 終於搞定了, 趕緊來去交作業啦!

5. 打包專案上傳 GitHub :

作業繳交要求將專案上傳 GitHub, 然後將 repo 網址填入 Google 試算表內.

(1). 將所有變更加入暫存區 (打包) :

D:\gemini\calculator-project>git add .

warning: in the working copy of '.gemini/commands/opsx/apply.toml', LF will be replaced by CRLF the next time Git touches it

warning: in the working copy of '.gemini/commands/opsx/archive.toml', LF will be replaced by CRLF the next time Git touches it

warning: in the working copy of '.gemini/commands/opsx/explore.toml', LF will be replaced by CRLF the next time Git touches it

warning: in the working copy of '.gemini/commands/opsx/propose.toml', LF will be replaced by CRLF the next time Git touches it

warning: in the working copy of '.gemini/skills/openspec-apply-change/SKILL.md', LF will be replaced by CRLF the next time Git touches it

warning: in the working copy of '.gemini/skills/openspec-archive-change/SKILL.md', LF will be replaced by CRLF the next time Git touches it

warning: in the working copy of '.gemini/skills/openspec-explore/SKILL.md', LF will be replaced by CRLF the next time Git touches it

warning: in the working copy of '.gemini/skills/openspec-propose/SKILL.md', LF will be replaced by CRLF the next time Git touches it

warning: in the working copy of '.gitignore', LF will be replaced by CRLF the next time Git touches it

warning: in the working copy of '.python-version', LF will be replaced by CRLF the next time Git touches it

warning: in the working copy of 'main.py', LF will be replaced by CRLF the next time Git touches it

warning: in the working copy of 'openspec/changes/archive/2026-04-25-calc-basic/.openspec.yaml', LF will be replaced by CRLF the next time Git touches it

warning: in the working copy of 'openspec/changes/archive/2026-04-25-calc-power-root/.openspec.yaml', LF will be replaced by CRLF the next time Git touches it

warning: in the working copy of 'openspec/changes/archive/2026-04-25-calc-scientific/.openspec.yaml', LF will be replaced by CRLF the next time Git touches it

warning: in the working copy of 'openspec/config.yaml', LF will be replaced by CRLF the next time Git touches it

warning: in the working copy of 'pyproject.toml', LF will be replaced by CRLF the next time Git touches it

warning: in the working copy of 'uv.lock', LF will be replaced by CRLF the next time Git touches it

出現的這些 warning 是在 Windows 環境下執行 Git 時常見的警告, 它完全不影響程式碼功能或 GitHub 的上傳結果, 這只是 Git 在提醒換行符號的格式要統一, 因為 OpenSpec 工具或 AI 產生的檔案可能預設使用了 Unix 格式的換行字符 LF, 在 Windows 的命令提示字元下操作時 Git 偵測到這種不一致, 所以主動告知它會自動把這些檔案轉換成 Windows 標準的 CRLF, 因此毋須理會.

(2). 設定使用者名稱與 Email :

D:\gemini\calculator-project>git config --global user.name "Tony"

D:\gemini\calculator-project>git config --global user.email "blablabla@ms5.hinet.net"

(3). 提交變更 (貼標籤/存檔) :

D:\gemini\calculator-project>git commit -m "feat: 完成計算機專案 (基礎運算、次方根號、科學計算)"

[master (root-commit) 17a5d99] feat: 完成計算機專案 (基礎運算、次方根號、科學計算)

44 files changed, 2523 insertions(+)

create mode 100644 .gemini/commands/opsx/apply.toml

create mode 100644 .gemini/commands/opsx/archive.toml

create mode 100644 .gemini/commands/opsx/explore.toml

create mode 100644 .gemini/commands/opsx/propose.toml

create mode 100644 .gemini/skills/openspec-apply-change/SKILL.md

create mode 100644 .gemini/skills/openspec-archive-change/SKILL.md

create mode 100644 .gemini/skills/openspec-explore/SKILL.md

create mode 100644 .gemini/skills/openspec-propose/SKILL.md

create mode 100644 .gitignore

create mode 100644 .python-version

create mode 100644 GEMINI.md

create mode 100644 README.md

create mode 100644 calculator/__init__.py

create mode 100644 calculator/logic.py

create mode 100644 main.py

create mode 100644 openspec/changes/archive/2026-04-25-calc-basic/.openspec.yaml

create mode 100644 openspec/changes/archive/2026-04-25-calc-basic/design.md

create mode 100644 openspec/changes/archive/2026-04-25-calc-basic/proposal.md

create mode 100644 openspec/changes/archive/2026-04-25-calc-basic/specs/arithmetic-api/spec.md

create mode 100644 openspec/changes/archive/2026-04-25-calc-basic/specs/calculator-ui/spec.md

create mode 100644 openspec/changes/archive/2026-04-25-calc-basic/tasks.md

create mode 100644 openspec/changes/archive/2026-04-25-calc-power-root/.openspec.yaml

create mode 100644 openspec/changes/archive/2026-04-25-calc-power-root/design.md

create mode 100644 openspec/changes/archive/2026-04-25-calc-power-root/proposal.md

create mode 100644 openspec/changes/archive/2026-04-25-calc-power-root/specs/advanced-arithmetic/spec.md

create mode 100644 openspec/changes/archive/2026-04-25-calc-power-root/specs/calculator-ui/spec.md

create mode 100644 openspec/changes/archive/2026-04-25-calc-power-root/tasks.md

create mode 100644 openspec/changes/archive/2026-04-25-calc-scientific/.openspec.yaml

create mode 100644 openspec/changes/archive/2026-04-25-calc-scientific/design.md

create mode 100644 openspec/changes/archive/2026-04-25-calc-scientific/proposal.md

create mode 100644 openspec/changes/archive/2026-04-25-calc-scientific/specs/calculator-ui/spec.md

create mode 100644 openspec/changes/archive/2026-04-25-calc-scientific/specs/scientific-functions/spec.md

create mode 100644 openspec/changes/archive/2026-04-25-calc-scientific/tasks.md

create mode 100644 openspec/config.yaml

create mode 100644 openspec/specs/advanced-arithmetic/spec.md

create mode 100644 openspec/specs/arithmetic-api/spec.md

create mode 100644 openspec/specs/calculator-ui/spec.md

create mode 100644 openspec/specs/scientific-functions/spec.md

create mode 100644 pyproject.toml

create mode 100644 static/index.html

create mode 100644 static/script.js

create mode 100644 static/style.css

create mode 100644 test_api.py

create mode 100644 uv.lock

(4). 在 GitHub 建立空的儲存庫 (Repository) :

建立一個空專案 (剛好 calculator-project 可用), 注意, 因為在本機已經有 README.md 與 .gitignore 檔案了, 不要勾選 "Add a README" 或 "Add .gitignore" 這兩項, 保持預設的空專案即可, 點擊 Create repository 新增 repo.

# https://github.com/tony1966/calculator-project

(5). 綁定並推上雲端 :

告訴本機 Git 這個專案要連線到哪個 GitHub 網址 :

D:\gemini\calculator-project>git remote add origin https://github.com/tony1966/calculator-project.git

把專案推上雲端 :

D:\gemini\calculator-project>git push -u origin main

Enumerating objects: 67, done.

Counting objects: 100% (67/67), done.

Delta compression using up to 16 threads

Compressing objects: 100% (51/51), done.

Writing objects: 100% (67/67), 39.46 KiB | 3.04 MiB/s, done.

Total 67 (delta 3), reused 0 (delta 0), pack-reused 0 (from 0)

remote: Resolving deltas: 100% (3/3), done.

To https://github.com/tony1966/calculator-project.git

* [new branch] main -> main

branch 'main' set up to track 'origin/main'.

此指令會出現詢問視窗, 用預設 manager 按 Select 鈕即可, 然後登入 GitHub 帳號即可上傳. 成功後到 Google sheet 登錄專案 repo 的 GitHub 網址即完成作業繳交啦! 我原以為時間太趕只能聽完課程, 沒想到忙了一整天居然搞定作業了, 哈哈.

心得 : 親自動手做一遍才能真正學會.

6. 跳出 Gemini CLI :

專案結束, 輸入 exit 離開專案 :

used 從 2% 到 10%, 用掉了 8% 資源. 連續按兩次 Ctrl+C 即可跳出 Gemini CLI 回到 PS 視窗.

Gemini CLI 學習筆記 : OpenSpec 初體驗 (二)

2026-04-25T21:24:00.001+08:00

白天完成初次迭代後, 傍晚快馬加鞭進行第二次迭代.

本系列全部測試文章參考 :

# Gemini CLI 學習筆記索引

前一篇的初次迭代由於功能較簡單, 我們使用了 /opsx:ff 快轉指令一鍵生成模式, 快速地完成了從規劃到程式碼生成與測試驗證的工作流. 本篇將在初次碟待的基礎上為基本的四則運算計算器添加次方與根號功能.

此二次迭代將改用逐步推進模式, 舊版 OpenSec 原本的的工作流需要依序執行下列指令 :

/opsx:new <iteration_name> (建立迭代之專屬的工作區)
/opsx:propose <requirements> (依需求起草提案書)
/opsx:continue (完成規格定義書 spec.md)
/opsx:continue (完成架構設計書 design.md)
/opsx:continue (完成任務清單 tasks.md)
/opsx:apply (依照 tasks.md 中的任務清單逐一實作功能)
/opsx:verify (驗證程式碼與規格完整性, 正確性, 一致性)
/opsx:archive (迭代完成歸檔)

執行 /opsx:propose 後, AI 只會生成第一份文件 proposal.md (提案書) 並把控制權交還給我們來審查功能描述是否與需求符合. 審查通過後就可執行三個連續的 /opsx:continue 指令, 一次只產出一份文件, 審查通過後再執行下一個 continue 指令.

第一個 /opsx:continue 指令, 它會生成規格定義書 spec.md, 注意, 這個檔案可能不只一個, 因為在模組化的軟體架構中, 功能會被解耦分拆在不同資料夾, 例如 :

openspec/changes/calc-power-root/specs/arithmetic-api/spec.md

openspec/changes/calc-power-root/specs/calculator-ui/spec.md

每一個功能都會有一個 spec.md 檔, 這些分散的規格定義書共同構成了這次迭代的完整規格.

第二個 /opsx:continue 指令會產生架構設計書 design.md, 主要是描述內部程式碼要怎麼實作, 審查重點在於有沒有過度設計 (Over-engineering), 例如明明 math 套件能做到的功能卻使用 numpy, 這實要將其改為 "使用 Python 內建 math 即可".

第三個 (也是最後一個) /opsx:continue 指令會生成任務清單 (施工單) tasks.md 檔, 這份文件是設計階段與實作階段之間的最後一座橋樑, 也是 AI 執行 /opsx:apply 時唯一的行動指南, 它只關注具體要做哪些動作. 審查時要檢查施工順序是否合理, 若無問題就可以下達 /opsx:apply 指令叫 AI 依照清單逐一實作程式碼, 完成驗證後即可歸檔.

但新版的 OpenSec 已經把三次 /opsx: continue 指令整合進 /opsx:propose 裡面了, 所以新版的工作流指令序列改為 :

/opsx:new <iteration_name> (建立迭代之專屬的工作區)
/opsx:propose <requirements> (依需求起草提案書, 規格定義書, 架構設計書, 與任務清單)
/opsx:apply <iteration_name> (依照 tasks.md 中的任務清單逐一實作此迭代功能)
/opsx:archive (迭代完成歸檔)

填寫四大核心工件的步驟其實都整合到 /opsx:propose 指令裡了.

1. 建立迭代之專屬工作區 :

第二次迭代的目標是要為四則運算計算器添加次方與開根號功能, 因此迭代名稱可取為 calc-power-root :

> /opsx:new calc-power-root

同樣地會有一連串的授權詢問, 一律選擇預設的 Allow once 觀察每一步在做甚麼 :

... (略) ...

可見 /opsx: new 指令主要是生成四個核心工件 (artifacts) 的待填空模板, 其中的 spec.md 是每個功能會有一個, 放在各自功能的資料夾下面.

2. 根據需求填寫提案書 :

有了核心工件的空模板後, 接下來要用 /opsx: propose 指令注入需求, 讓 AI 協助填寫提案書 :

> /opsx:propose "在現有的基礎四則運算計算器專案上, 加上次方與開根號功能. 請確保處理好基礎的邊界條件與防呆機制 (例如對負數開偶數根的錯誤處理) 等. "

這時 OpenSpec 偵測到這個需求的主題跟上面剛剛用 /opsx:new calc-power-root 建好的 calc-power-root 工作區完全契合, 詢問是否要把這份提案放進剛才那個工作區? 那是當然的, 選 1. 繼續使用 calc-power-root :

... (略) ...

可見四大核心工件檔案的填寫都已完成, 開啟這些檔案審查若不需要修改就可以下 /opsx:apply 指令來實作程式碼了.

3. 依據任務清單實作程式碼 :

用 /opsx: apply 指令並指定迭代工作區名稱 (防呆防猜測) :

> /opsx:apply calc-power-root

此指令將依照任務清單 tasks.md 內容依序實作程式碼, 同樣地會有一連串的授權詢問, 一律選擇預設的 Allow once 觀察每一步在做甚麼 :

... (略) ...

這樣就完成專案實作了 (咦, 這次沒跟我說要開啟 127.0.0.1:5000 來測試?), 我前次迭代執行的 uv rum main.py 沒關掉, 馬上測試 2 的 3 次方得到正確結果 8 :

按 C 鍵清除輸入 49 按開根號也正確得到 7 :

原先的基本四則運算功能維持一樣沒被改壞, 二次迭代終於完成了.

4. 歸檔結案 :

下 /opsx: archive 指令歸檔 :

> /opsx: archive

... (略) ...

終於完成二次迭代了.

Gemini CLI 學習筆記 : OpenSpec 初體驗 (一)

2026-04-25T17:37:00.011+08:00

最近幾天上完 TibaMe 的規格驅動開發 (SDD) 課程, 準備找一個小專案 (計算器) 用 Gemini CLI 來跑一下 OpenSpec 交作業.

本系列全部測試文章參考 :

# Gemini CLI 學習筆記索引

關於 SDD 我已看完高見龍老師的部落格文章, 摘要整理在這篇 :

# 好站 : 高見龍老師的部落格 (SDD 規格驅動開發)

1. Gemini CLI 升版 :

距離上次測試已經過了快三個月了, Gemini CLI 版本應該也演進了不少, 所以先來升版. 開啟 PS 視窗, 輸入下列指令查詢目前本機版本 :

PS D:\gemini> gemini --version

0.26.0

用下列指令升到最新版 :

PS D:\gemini> npm install -g @google/gemini-cli@latest

added 1 package, removed 609 packages, and changed 6 packages in 3m

npm notice

npm notice New minor version of npm available! 11.6.2 -> 11.13.0

npm notice Changelog: https://github.com/npm/cli/releases/tag/v11.13.0

npm notice To update run: npm install -g npm@11.13.0

npm notice

PS D:\gemini> gemini --version

0.39.1

哇, 一季不見已從 0.26.0 跳到 0.39.1 版. npm 也有新版, 順便也升版 :

PS D:\gemini> npm install -g npm@11.13.0

removed 60 packages, and changed 90 packages in 9s

PS D:\gemini> npm --version

11.13.0

2. 安裝 OpenSpec :

OpenSpec 是一款由 Fission AI 研發的開源輕量級規格驅動開發 (SDD) 工具, 是一套讓 AI 程式助理 (coding agents) 遵循規格的工作流程與 CLI 工具, 目前支援 20 種以上 AI 工具, 它的目標是讓工程師與 AI 在開發軟體之前先對規格達成共識, 減少 vibe coding 常見的偏題與反覆修改弊病, 並且能留下規格紀錄與決策脈絡備查, 提高軟體可維護性.

安裝 OpenSpec 須有 Node v20.19.0 以上執行環境, 先檢視 Node 版本 :

PS D:\gemini> node --version

v25.2.1

我的 Node 是利用 Scoop 安裝 Node 的, 可管理多版本的 Node, 參考 :

# 在 Windows 上安裝原生版 Claude Code

# 在 Windows 上安裝 Gemini CLI

這樣就可以在 PS 視窗安裝 OpenSpec 了 :

PS D:\gemini> npm -g install @fission-ai/openspec@latest

added 74 packages in 34s

這樣就完成 OpenSpec 安裝了.

3. 用 uv 建立專案目錄 & 加入版控 :

由於作業要求用 OpenSpe 做三次迭代, 我打算用 OpenSpec 來實作一個網頁計算器專案, 第一次迭代要實作基本的四則運算計算機, 第二次迭代添加次方與開根號功能; 第三次迭代則添加對數, 指數, 與三角函數.

首先用 uv init 指令建立一個專案目錄 :

PS D:\gemini> uv init calculator-project

Initialized project `calculator-project` at `D:\gemini\calculator-project`

然後切換到專案目錄下 :

PS D:\gemini> cd calculator-project

對此專案進行版本控制, 先檢視 Git 是否已安裝 :

PS D:\gemini\calculator-project> git --version

git version 2.52.0.windows.1

關於 Git 安裝與用法參考 :

# Git 學習筆記索引

在專案目錄下用 git init 初始化版控 :

PS D:\gemini\calculator-project> git init

Reinitialized existing Git repository in D:/gemini/calculator-project/.git/

版控資訊會儲存在隱藏目錄 .git 底下.

4. 初始化 OpenSpec :

接著用 openspec init 指令為此專案做 OpenSpec 的初始化 :

PS D:\gemini\calculator-project> openspec init

這時會出現 OpenSpec 歡迎畫面 :

按 Enter 會出現 AI 程式代理工具選單, 可以按上下鍵移動指標來選擇要用的 AI 工具, 按 Space 鍵選擇要使用的代理工具 (可複選, 目前已支援 28 種 AI 程式代理工具), 此處我只選 Gemini CLI :

選定的工具名稱會被列在上方的 Selected : 後面

選完後按 Enter 退出 OpenSpec 初始化畫面回到 PS 終端機, 可見已為 Gemini CLI 程式代理建立了 4 個技能 (skills) 與 OpenSpeck 相關之命令 :

Note: OpenSpec collects anonymous usage stats. Opt out: OPENSPEC_TELEMETRY=0

√ Select tools to set up (28 available) Gemini CLI

▌ OpenSpec structure created

√ Setup complete for Gemini CLI

OpenSpec Setup Complete

Created: Gemini CLI

4 skills and 4 commands in .gemini/

Config: openspec/config.yaml (schema: spec-driven)

Getting started:

Start your first change: /opsx:propose "your idea"

Learn more: https://github.com/Fission-AI/OpenSpec

Feedback: https://github.com/Fission-AI/OpenSpec/issues

Restart your IDE for slash commands to take effect.

做完上面初始化後, 用 tree /f 指令檢視專案目錄 :

PS D:\gemini\calculator-project> tree /f

列出磁碟區新增磁碟區的資料夾 PATH

磁碟區序號為 1258-16B8

D:.

│ .gitignore

│ .python-version

│ main.py

│ pyproject.toml

│ README.md

│

├─.gemini

│ ├─commands

│ │ └─opsx

│ │ apply.toml

│ │ archive.toml

│ │ explore.toml

│ │ propose.toml

│ │

│ └─skills

│ ├─openspec-apply-change

│ │ SKILL.md

│ │

│ ├─openspec-archive-change

│ │ SKILL.md

│ │

│ ├─openspec-explore

│ │ SKILL.md

│ │

│ └─openspec-propose

│ SKILL.md

│

└─openspec

│ config.yaml

│

├─changes

│ └─archive

└─specs

可見 OpenSec 初始化時已在

5. 安裝專案所需套件 :

雖然對一個計算器專案來說, 只需要純前端 (HTML/CSS/JavaScript) 技術就能完成所有功能, 但為了模擬真實軟體架構常見的前後端搭配組態, 我打算將計算功能邏輯交給後端 Flask 框架來完成, 所以必須先用 uv 工具安裝 Flask, 這樣當 AI 生成程式碼後就可以叫 Gemini CLI 用 uv run 執行專案與驗證結果, 不需要再跳出來處理環境問題. 其次, 在使用 /opsx:verify 進行自動化檢查或測試時, 系統會依賴現有的虛擬環境, 如果環境未就緒 (例如缺少 Flask 套件), 驗證步驟可能會出錯.

PS D:\gemini\calculator-project> uv add flask

Using CPython 3.12.1 interpreter at: C:\Users\tony1\AppData\Local\Programs\Python\Python312\python.exe

Creating virtual environment at: .venv

Resolved 9 packages in 758ms

Prepared 7 packages in 466ms

░░░░░░░░░░░░░░░░░░░░ [0/8] Installing wheels... warning: Failed to hardlink files; falling back to full copy. This may lead to degraded performance.

If the cache and target directories are on different filesystems, hardlinking may not be supported.

If this is intentional, set `export UV_LINK_MODE=copy` or use `--link-mode=copy` to suppress this warning.

Installed 8 packages in 98ms

+ blinker==1.9.0

+ click==8.3.3

+ colorama==0.4.6

+ flask==3.1.3

+ itsdangerous==2.2.0

+ jinja2==3.1.6

+ markupsafe==3.0.3

+ werkzeug==3.1.8

安裝完後用 tree /f 檢視專案目錄, 會多出一個 .venv 隱藏子目錄, 裡面有包含 Flask 與所依賴的 Jinjia 等套件 :

├─.venv

│ │ .gitignore

│ │ .lock

│ │ CACHEDIR.TAG

│ │ pyvenv.cfg

│ │

│ ├─Lib

│ │ └─site-packages

│ │ │ _virtualenv.pth

│ │ │ _virtualenv.py

│ │ │

│ │ ├─blinker

│ │ │ base.py

│ │ │ py.typed

│ │ │ _utilities.py

│ │ │ __init__.py

... (略) ...

│ │ ├─flask

│ │ │ │ app.py

│ │ │ │ blueprints.py

│ │ │ │ cli.py

│ │ │ │ config.py

│ │ │ │ ctx.py

│ │ │ │ debughelpers.py

│ │ │ │ globals.py

│ │ │ │ helpers.py

│ │ │ │ logging.py

│ │ │ │ py.typed

│ │ │ │ sessions.py

│ │ │ │ signals.py

│ │ │ │ templating.py

│ │ │ │ testing.py

│ │ │ │ typing.py

│ │ │ │ views.py

│ │ │ │ wrappers.py

│ │ │ │ __init__.py

│ │ │ │ __main__.py

... (略) ...

6. 編輯專案語境檔 GEMINI.md :

在之前使用 Vibe coding 的進階方式開發時, 我們透過事先編輯好的專案語境檔 GEMINI.md 一次將專案需求與結構, 程式風格, 任務模板, 限制和偏好等資訊一口氣描述好, 當啟動 Gemini CLI 時它便能了解專案內容, 從而減少來回問答的次數. 這種語境檔因為要交待較多訊息, 所以內容比較冗長, 參考 :

# Gemini CLI 學習筆記 : 專案語境檔 GEMINI.md

如果使用 OpenSpec 做 SDD 開發, GEMINI.md 就會比較簡短, 例如下面的通用模板 :

# Project Global Guidelines (GEMINI.md)

## 1. AI 角色設定 (通用)

你是一位資深的 [Python 後端與全端] 開發專家，精通 [Flask 框架與現代前端技術]，並具備極高的軟體工程素養。

## 2. 技術棧與環境配置 (專案特製)

* 核心語言：Python 3.12+ (嚴格使用 `uv` 進行依賴與環境管理)

* 後端框架：[Flask]

* 前端技術：[Vanilla JS, HTML5, CSS3]

* 其他工具：[若無則免，例如 SQLite, 特定硬體 SDK 等]

## 3. 開發流程與規格遵循 (通用，針對 OpenSpec 用戶)

* 本專案嚴格遵循 Fission AI 的 OpenSpec 工作流 (`/opsx` 指令集)。

* 你的所有實作必須以 `specs/` 目錄下的文件與 `tasks.md` 為「唯一真相來源 (Single Source of Truth)」。

* 絕對禁止在未經使用者同意且未更新 Spec 的情況下，自行發明、擴充或竄改 API 規格與業務邏輯。

## 4. 程式碼風格守則 (通用，Python 標準)

* 必須包含 Type Hints (型別提示) 與清楚的 Docstrings。

* 遵守 PEP 8 命名規範 (變數與函式使用 `snake_case`，類別使用 `PascalCase`)。

* 保持模組化，避免單一檔案過於龐大。

其中專案特製部分視專案而異, 括號 [] 內容需要手動修改, 其他通用部分則適用於任何用 OpenSpec 開發的專案. GEMINI.md 的角色是專案的憲法, 負責告訴 AI 我們這個專案要用甚麼 approach 來做 (How), 而專案的需求 (what) 會放在 /opsx: propose 指令來交待.

在 PS 視窗的專案目錄下輸入 notepad GEMINI.md :

PS D:\gemini\calculator-project> notepad GEMINI.md

這時 PS 發現專案目錄下並無 GEMINI.md 檔, 就彈出詢問是否新建此檔, 按是就會開啟記事本 :

複製上面的語境檔通用範本貼到 GEMINI.md 後存檔 (此處我將 ## 2 的其他工具內容改為 [無]) :

再次用 tree /s 檢視專案目錄下已有此 GEMINI.md 檔了 :

PS D:\gemini\calculator-project> tree /f

列出磁碟區新增磁碟區的資料夾 PATH

磁碟區序號為 1258-16B8

D:.

│ .gitignore

│ .python-version

│ GEMINI.md

│ main.py

│ pyproject.toml

│ README.md

│ uv.lock

│

├─.gemini

│ ├─commands

│ │ └─opsx

│ │ apply.toml

│ │ archive.toml

│ │ explore.toml

│ │ propose.toml

│ │

│ └─skills

... (略) ...

7. 啟動 Gemini CLI 進行初次迭代 :

完成上面準備工作後, 終於要開啟 Gemini CLI 開始用 OpenSpec 幹活了. 在專案目錄下輸入 gemini 指令 :

PS D:\gemini\calculator-project> gemini

詢問是否信任此目錄, 當然要選 1. Trust folder (calculator-project) 才會進入 Gemini CLI 介面 :

出現 > 提示號表示 AI 已經讀取了 GEMINI.md 內容知道自己是誰, 也知道這個資料夾裡有 OpenSpec 環境, 這樣就可以開始用 OpenSpec 的斜線指令集 /opsx 進行 SDD 開發了.

如上所述, 這個專案作業要求至少進行三次開發迭代, 第一次迭代是要做出一個基本的四則運算計算器, 由於較簡單, 此處會使用快轉模式, 直接用 /opsx: ff 指令一鍵生成完成專案規劃與程式碼生成與測試, 整個工作流只需要的指令如下 (依序) :

/opsx:new <iteration_name> (建立迭代之專屬的工作區)
/opsx:ff <requirements> (依需求快轉生成設計文件與程式碼並完成測試)
/opsx:archive (迭代完成歸檔)

其中 iteration_name 是自訂的, 為了專案的易讀性以及讓 AI 能隱約猜到任務方向, 通常會遵循以下命名最佳實踐來取名 :

使用 Kebab-case (連字號命名法) :
全小寫英文, 單字之間用連字號 - 隔開, 避免使用空格, 大寫或特殊符號.
具備語意 (Semantic) : 名稱要能直接反映這次迭代的核心目的.

初次迭代我選用 cals-basic 作為工作區名稱.

(1). 建立迭代之專屬工作區 :

這會在專案目錄下建立此次迭代之專屬工作區, 例如迭代名稱是 calc-basic 的話就建立對應的資料夾 specs/changes/calc-basic/ 來收納這次迭代的所有相關討論與設計文件.

系統會自動生成標準 SDD 流程所需的空文件或帶有基礎標題的模板, 例如空的 proposal.md, spec.md, design.md 以及 tasks.md, 此階段相當於是買了一本有分類索引標籤 (提案, 規格, 設計, 任務) 的空白筆記本, 以便在後續工作流中依需求來填空或修改.

輸入下列指令並於一連串授權詢問時一律選擇預設的 Allow once :

> /opsx:new calc-basic

... (略) ...

工作區建完後, 專案所需的 OpenSpec 模板文件也都已建好, 但它們目前只是空洞的骨架而已, 接下來的工作流 (/opsx:ff 或 /opsx:continue) 就會根據需求來填寫這些標準 SSD 流程的四份核心文件模板 (proposal.md, spec.md, design.md 以及 tasks.md), 如果需求較複雜, 可能也會生成額外的 spec-xxx.md 文件, 相當於是在骨架中進行靈魂注入.

(2). 依需求快轉 (ff) 生成設計文件與程式碼 :

此階段 OpenSpec 會根據我們提供的專案需求, 透過 AI 去修改或填空上一個指令 (/opsx: new) 生出的四份核心文件 proposal.md (提案), spec.md (介面規格), design.md (架構設計) 與 tasks.md (任務清單), 並且據此生成程式碼同時完成測試, 可說是集成了 /opsx:propose, /opsx:continue, /opsx: apply, 以及 /opsx: verify 這四個指令的功能於一身, 一氣呵成完成專案實作.

輸入如下指令來進行快轉 :

> /opsx:ff "請幫我規劃一個基礎四則運算計算機軟體, 後端使用 Flask 提供 POST API, 前端使用純 HTML/JS, 並提供基本的使用者介面."

... (略) ...

同樣地, 在它修改生成檔案與依此生成整個專案程式碼過程中會不斷要求授權, 我都選預設的 Allow once, 這樣可以一步步觀察 OpenSpec 做了哪些事, 過程中會顯示生成的程式碼與單元測試檔, 完成後結果如下 :

這時可以另開一個命令提示字元或 PS 視窗, 切到專案目錄下, 用 python main.py 或 uv run main.py 執行此專案, 然後開啟瀏覽器訪問 http://127.0.0.1:5000 :

PS D:\gemini> cd calculator-project

PS D:\gemini\calculator-project> uv run main.py

* Serving Flask app 'main'

* Debug mode: on

WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead.

* Running on http://127.0.0.1:5000

Press CTRL+C to quit

* Restarting with stat

* Debugger is active!

* Debugger PIN: 125-928-819

127.0.0.1 - - [25/Apr/2026 16:44:54] "GET / HTTP/1.1" 200 -

127.0.0.1 - - [25/Apr/2026 16:44:54] "GET /static/style.css HTTP/1.1" 200 -

127.0.0.1 - - [25/Apr/2026 16:44:54] "GET /static/script.js HTTP/1.1" 200 -

127.0.0.1 - - [25/Apr/2026 16:44:54] "GET /favicon.ico HTTP/1.1" 404 -

127.0.0.1 - - [25/Apr/2026 16:45:11] "POST /api/multiply HTTP/1.1" 200 -

127.0.0.1 - - [25/Apr/2026 16:45:23] "POST /api/divide HTTP/1.1" 400 -

果然顯示了四則運算計算器頁面, 測試計算功能正常 (7 * 8=56, 1 除以 0 顯示 Error ) :

(3). 歸檔結案 :

完成以上功能驗證後, 就可以用 /opsx: archive 指令檢查所有的 Artifacts 是否齊全, 是的話將此次迭代的所有紀錄, 文件, 與過程收整, 並移動到 archive 資料夾收存 :

> /opsx:archive

同樣地會有一連串的授權請求, 一律選擇預設的 Allow once :

... (略) ...

可見所有此次迭代的紀錄文件都已歸檔於 openspec/changes/archive/2026-04-25-calc-basic/ 資料夾底下, 這些都是未來維護軟體的重要資料. 好啦! 終於完成初次迭代.

Python 學習筆記 : 市圖借書與預約爬蟲程式架構

2026-04-23T09:55:00.010+08:00

這兩天完成市圖爬蟲改版 (v13), 由於此爬蟲機制較複雜, 由地端與雲端程式共同運作來維護佈署於 Render 的 Serverless 平台上的資料庫 (kmsl_books 資料表), 這與 v10 版之前的系統完全由地端爬蟲程式一手包辦爬取與傳訊完全不同. 爬蟲任務主要由放在高雄家的樹莓派主機負責, 目前主要是市圖借書與預約狀況與母校圖書館自動續借兩個任務而已, 今天抽空畫了一張架構圖以資備忘.

Pi 3B 對接 render.com 上的 5e6i 這個端點 :

Pi 3A+ 則對接 render.com 上的 fdof 這個端點 :

佈署於樹莓派上的市圖爬蟲程式 ksml_lib_13.py 負責每小時爬取網頁擷取借書與預約狀態後, 呼叫佈署於 render.com 的 serverless 平台函式 update_ksml_books.py, 將資訊儲存在 kmsl_books 資料表裡, 結果如下 :

另外一支本地程式 get_books_messages.py 透過 crontab 驅動定時呼叫 serverless 平台函式 send_books_messages.py 讀取 kmsl_books 資料表, 然後由發送到 Telegram, 參考最近三版異動 :

# Python 學習筆記 : 市圖借書與預約爬蟲程式改版 v11

# Python 學習筆記 : 市圖借書與預約爬蟲程式改版 v12 (於 Pi 400)

# Python 學習筆記 : 市圖借書與預約爬蟲程式改版 v13

母校圖書館爬蟲 nkust_lib_11.py 的任務相對簡單, 只是登入網站後按全部續借鈕, 然後瀏覽借書頁面, 擷取已被預約的書目後用 Telegram 傳送通知訊息而已, 參考 :

# Python 學習筆記 : 母校圖書館借書與預約爬蟲程式改版 v11

至於 Pi 400 上佈署的爬蟲與 Pi 3B 的相同 (對接 5e6i), 但正常情況會關掉 crontab 內的 ksml_lib_13.py (不執行), 僅執行 get_books_messages.py 與 nkust_lib_11.py, 若 Pi 3 主機出問題再開啟 Pi 400 的市圖爬蟲.

沖繩之旅行程規劃 : 5/5~5/8

2026-04-21T11:06:00.015+08:00

年初時原本打算入春後帶爸坐郵輪遊沖繩, 但想到上回搭麗星郵輪去香港 (原本是石垣島+沖繩, 因颱風改走香港) 的經驗, 在海上時無法上網形同斷訊, 在船上日吃五餐會變胖, 於是打消了遊輪計畫, 改為搭飛機自助遊, 原本想說嘗試在沖繩自駕, 但又對右駕系統沒自信能駕馭, 那就包車吧! 我跟水某與菁菁加上爸四個人包一台車即可, 不過後來加入岳父母, 小姨子, 與剛高中畢業的外甥, 團員來到 8 人, 所以必須包 10 人座的小巴啦 (Toyota Hiace)!

今天用 Gemini 規劃這四天三夜親子沖繩旅遊行程如下 :

Day 1 : 5/5 (週一) 抵達那霸入住國際通嘉新酒店

時間軸	行程說明
15:55 - 18:45	搭乘華航 CI132 抵達那霸機場，可預約 10人座單程接機直達飯店。
20:30 -	Check-in國際通嘉新酒店。
21:00 -	晚餐：國際通島唄與地料理 Tubaraama 餐廳。

PS :

晚餐請包車業者沖繩行腳代訂島唄與地料理 Tubaraama 餐廳 21:00 用餐.

Day 2 : 5/6 (週二) 北部遠征（水族館＋古宇利島）

時間軸	行程說明
09:00 -	出發 (建議包車 10 小時)：往返北部車程長，包車可在車上補眠。
10:40 -	古宇利島：欣賞跨海大橋美景，推薦搭乘古宇利海洋塔的電動導覽車。
12:00 -	午餐：北部景觀餐廳（如：百年古家大家）。
14:00 -	沖繩美麗海水族館：觀看黑潮之海大水槽與鯨鯊。
17:00 -	啟程返回那霸返回那霸晚餐 (那霸的許田交流道常塞車須提早返航)。

Day 3 : 5/7 (週三) 景觀與購物（瀨長島＋永旺來客夢）

時間軸	行程說明
09:00 -	出發 (包車 10 小時，今天景點較多且分散，包車最省體力。)
09:40 -	知念岬公園：欣賞 270 度無敵海景，這裡步道平緩，停留約 40 分鐘。
11:00 -	瀨長島 Umikaji Terrace：午餐推薦幸福鬆餅/天使鬆餅 Happy Pancake。
13:30 -	美國村：異國風情街區散步，拍拍彩色房子。
15:30 -	永旺來客夢 (AEON Mall Rycom)：直衝寶可夢中心，晚餐：永旺美食街
18:15 -	回國際通：回飯店後可進行採買 (傍晚從中部回國際通可能有車潮)。

註 : 瀨長島午餐人潮多，長輩在白色階梯區步行較費力，建議司機停在最上層或最下層。

Day 4 : 5/8 (週四) 神社祈福・悠閒歸途

時間軸	行程說明
09:00 -	波上宮：到琉球第一神社祈福。
12:00 -	午餐：國際通周邊（如：第一牧志公設市場吃海鮮或道地阿古豬）。
15:30 -	啟程前往機場：長輩搭計程車，其他往縣廳站坐單軌 (13-16 分鐘)。
18:30 - 19:15	搭乘華航 CI2133 返回高雄小港。

💡 行程建議：

知念岬 vs 美國村：
知念岬在東南角，美國村與永旺在中部。這天行程景點多，需要 10 人座包車接送。
關於「天使鬆餅」：
瀨長島的幸福鬆餅（Happy Pancake）極熱門，建議事先網路預約，否則現場排隊會很久。
寶可夢中心：
永旺來客夢的寶可夢中心很大可以慢慢逛，長輩可以帶到商場中間的大型水族箱區坐著休息。

💡 關於美麗海水族館 :

黑潮之海 (The Kuroshio Sea)：
這是水族館的靈魂。巨大的壓克力水槽中，數隻巨大的鯨鯊與鬼蝠魟在藍色海水中緩緩游動。
海豚秀 (Okichan Theater)：
位於水族館主體建築外的海邊。看表演時可以吹海風、看海景。提醒：海豚表演場地離水族館出口有一小段路，建議推輪椅前往較輕鬆。
觸摸池：
可以嘗試觸摸海星和海參，是很有趣的互動。
水族館的「鯨鯊餵食秀」：
通常在下午 15:00 和 17:00 各有一場。鯨鯊會直立起來進食，非常震撼，建議將行程調整在下午抵達，看完餵食秀再離開。
輪椅借用：
美麗海水族館的入口處提供免費輪椅借用。即便長輩平時行走自如，但水族館園區很大，強烈建議借一台預備，當長輩逛到一半疲累時可以推著他們走，確保行程愉快不掃興。
避開正午陽光：
5 月的沖繩陽光已很強。建議中午在古宇利島附近的景觀餐廳用餐（吹冷氣看海），下午最熱的時候留在水族館室內，這對長輩的體力保持最有幫助。

💡 古宇利島 (Kouri Island) :

古宇利島被稱為「神之島」或「戀之島」，從本島開車經過古宇利大橋時，兩側的翡翠綠海色被譽為「古宇利藍」，是沖繩最美的公路景觀之一。

古宇利大橋：
長約 2 公里。建議請包車司機在過橋時放慢車速，這段路不用走路，坐在車內就能欣賞絕佳海景。
古宇利海洋塔 (Kouri Ocean Tower)：
這裡有自動駕駛的無人導覽小車，會載著全家人緩緩繞行山坡抵達塔頂。沿途會播放語音介紹，並能從高處俯瞰整座大橋，風景極其壯觀。
心形岩 (Heart Rock)：
這位於島的另一端海灘。注意：前往沙灘的路徑較不平坦且多沙，長輩可在車上休息或在岸邊咖啡廳喝茶看海。

💡知念岬公園 (Cape Chinen Park) :

位於沖繩本島東南部的南城市，是一個非常純粹、能讓人感受到大自然震撼的美麗景點。沿著公園的紅色扶手步道往下走一點點，可以拍到步道延伸進大海的感覺。建議停留 30 到 45 分鐘。這裡適合安靜地看海，當作早上的第一個景點，呼吸一下新鮮空氣。知念岬的風有時會比較大，即便 5 月天氣轉熱，建議帶件輕薄的防風外套。

270 度的無敵海景 :
知念岬三面環海，視野極其開闊。從展望台望出去，可以看到湛藍的太平洋（天氣好時呈現漸層的藍色），還能遠眺被琉球人視為聖島的「久高島」。這裡與其他懸崖景點不同，從停車場到主要的景觀台和草地步道都非常平緩，推輪椅或讓長輩慢慢散步都非常輕鬆。即使長輩不想走太遠，只要下車站在入口附近的涼亭，就能看到極佳的海景，不需要長途跋涉。
滑翔傘愛好者的天堂 :
這裡因為地形關係，常能看到彩色滑翔傘在空中飛翔，看著滑翔傘配上背景的海景，拍照也非常漂亮。
緊鄰「齋場御嶽」:
知念岬公園就在琉球王國第一聖地「齋場御嶽」附近（走路約 5-10 分鐘）。對文化感興趣，可以順便去走走；但要注意「齋場御嶽」內有很多崎嶇的石頭路，對長輩來說比較吃力，建議留在知念岬公園看海、吹風即可。

💡瀨長島 :

瀨長島位於那霸機場南端，從那霸市區（嘉新酒店）往南開到瀨長島只要約 20 分鐘，接著再往北去美國村和永旺來客夢百貨，動線非常順。雖然它是一座島，但開車過橋只需要 1 分鐘，完全沒有「搭船」的負擔。因為離機場極近，這裡是看飛機起降的絕佳地點。瀨長島的白色建築是依山坡而建，樓梯較多。建議包車司機直接載到最上層放人，由上往下逛會輕鬆很多。

Umikaji Terrace (瀨長島陽台) :
這是像希臘聖托里尼一樣的純白色建築群，有非常多靠海的露天咖啡廳，可以坐在遮陽傘下吹著海風、看著藍色海洋和飛機。不需要爬高爬低，非常放鬆。也有很多文創小店和網美下午茶店（例如幸福鬆餅），非常適合拍照打卡。
足湯體驗：
島上有免費的足湯（靠近琉球溫泉瀨長島飯店），如果走累了，在那裡泡腳看飛機也是一種享受。

💡美國村（American Village）:

位於沖繩本島中部的北谷町，是一個將美式西海岸風情與沖繩海島氛圍完美融合的綜合型景區。這裡曾經是美軍基地，後來改建為商圈，是沖繩最具異國風情的地方，非常適合下午短暫停留。美國村範圍很大，建議請包車司機載到最靠近海邊的「Depot Island Seaside」區下車。那裡是最精華、色彩最鮮艷的區域 (寶可夢迷會發現建築的牆面上隱藏了很多「皮卡丘」彩繪)，也是步道起點，從那裡沿著海岸步道往南逛，走到落日海灘 (Sunset Beach) 大約只需 10-15 分鐘，那裡有一間 Aeon 北谷店（超市），可以買點當地零食或飲料，司機可以約在 Aeon 門口接。美國村離永旺來客夢百貨（AEON Mall Rycom）車程只需約 15-20 分鐘，建議下午在美國村拍照散步，傍晚再前往永旺吃晚餐與購物。

獨特的建築與視覺（拍照聖地）:
這裡的建築色彩鮮艷，牆面充滿了各種美式風格的塗鴉與裝飾，隨處都能拍出極具風格的照片。
海濱步道：
美國村緊鄰著北谷公園的落日海灘。這裡有一條非常平緩的海濱步道，可以一邊吹著海風，一邊散步看海，完全沒有階梯負擔。
美式潮流文創 :
這裡有很多美式古著店、潮流服飾以及好拍的文創商店。此外，這裡也常能看到大型的模型或獨特的車輛裝飾。也有非常多舒適的戶外咖啡廳（如著名的 Pokébowls 或 ZHYVAGO COFFEE），走累了可以坐在靠海的位子看著來往的各國遊客與美軍家庭，也是一種很不一樣的觀察體驗。
落日夕陽：
美國村的夕陽是全沖繩前三名的美景。在傍晚時分坐在岸邊看夕陽是非常浪漫的。傍晚在 Depot Island 的紅磚區有時會有街頭魔術表演。

💡永旺來客夢 (AEON Mall Rycom) :

永旺夢樂城來客夢（AEON Mall Okinawa Rycom）是沖繩規模最大、設施最完善的購物中心，對您的家庭成員來說，這裡不僅是購物點，更是一個全齡化的休閒空間。從美國村到永旺來客夢約 20 分鐘車程.

震撼的入口大水族箱（Rycom Aquarium）:
一進大門，一樓大廳就有一個巨大的水族箱。雖然比不上美麗海水族館，但裡面有近千條色彩繽紛的熱帶魚和小型鯊魚。
寶可夢中心 (Pokémon Center)：
位於四樓，是沖繩唯一的官方專賣店，有許多沖繩限定（如穿著花襯衫的皮卡丘）的商品。
潮流品牌：
這裡聚集了 Uniqlo, GU, H&M, Old Navy 等各大品牌，還有日本當地的文創小物，非常適合年輕人。
AEON Style：
二樓有大型超市和藥妝區，可以在這裡一次買齊要帶回台灣的沖繩零食、泡麵或是藥妝，不用在國際通辛苦提貨。
Rycom Sky Diner :
五樓有非常多美食餐廳，從傳統琉球料理、日式豬排、壽司到美式牛排都有。五樓的戶外露台可以俯瞰中部的海景。如果天氣好，在這裡吃午餐或晚餐視野極佳。
美食街：
三樓、四樓的美食廣場設有寬敞的無障礙座位區。

💡包車資訊 :

5/6 與 5/7 日兩天需包車, 8 個人需 10 人座的車.

# 沖繩行腳

先掃 LINE 官方帳號 QR 碼 :

然後簡述包車日期與行程概要, 請其報價 :

您好，我打算與親友去沖繩旅行，需要中文司機包車兩天，每天10小時，麻煩您報價，謝謝您。行程大致如下：

沖繩

1.乘客人數：8

2.行李件數：4

3.包車日期：5/6~5/7

4.行程規劃：5/6 古宇利島，水族館；5/7 知念岬公園，瀬長島，美國村，永旺來客夢

5.出發地點：國際通嘉新酒店

6.結束地點：國際通嘉新酒店

HDD/SSD 健康狀態檢測軟體 CrystalDiskInfo

2026-04-20T16:26:00.003+08:00

昨天成功地用 chdisk 救回 WD 5TB 硬碟後, 用 CrystalDiskInfo (CDI) 檢查了硬碟健康狀況為優良, 詢問 Gemini 得知它不僅能檢測硬碟, 還能檢測 SDD, 目前幾乎所有電腦都改用 SDD, 這種儲存跟汽車電瓶一樣, 接近壽命終點時說掛就掛, 而且內容就不回來, 所以要經常查看 SDD 健康狀態, 低於 50% 壽命時就要考慮更換或提高備份頻率, 以免後悔不及.

以下是 Gemini 對 CDI 的說明與建議 :

===========================================================

對現代電腦來說，用 CDI 監測 SSD 的健康狀況甚至比 HDD 更重要，因為 SSD 有明確的**「寫入壽命限制」**。

不過，看 SSD 的報告時，重點指標與你剛才看那顆 5TB HDD 的邏輯不太一樣：

1. SSD 檢測的黃金指標：剩餘壽命

在 SSD 的報告中，最上方大大的「健康狀態」通常會直接顯示一個百分比，例如 「良好 98%」。

這是什麼： 這是根據 SSD 廠商定義的 TBW (Total Bytes Written，總寫入量) 估算出來的。
怎麼看： * 100% - 90%： 像新的一樣。
- 低於 50%： 雖然還能用，但建議開始尋找下一顆硬碟。
- 低於 10% 或 0%： 隨時可能進入「唯讀模式」或直接掛掉，必須立刻更換。

2. 重點關注項目（對比 HDD）

打開 CDI 看你的 SSD 時，請盯住這兩項：

03 剩餘壽命 (Percentage Used)： 顯示已消耗的設計壽命。
F1 總計主機寫入量 (Total Host Writes)： 這告訴你這顆 SSD 自出廠以來到底寫入了多少資料（通常以 GB 或 TB 為單位）。對於開發者來說，如果你頻繁編譯大型專案或跑大量 Log，這個數字會跳很快。
01 介面 CRC 錯誤計數： 如果這個數值不是 0，通常代表你的 SATA 線或是 M.2 插槽接觸不良，而不是 SSD 本身壞了。

3. SSD 與 HDD 在 CDI 中的差異

項目	HDD (傳統硬碟)	SSD (固態硬碟)
主要風險	物理壞軌、機械磨損	閃存顆粒寫入次數耗盡
關鍵指標	05 (重定位磁區)、C5 (等候重定)	03 (剩餘壽命百分比)
溫度	建議 50°C 以下	較高，NVMe 飆到 60-70°C 算常見
異常徵兆	異音、讀取極慢、chkdsk 噴錯誤	突然偵測不到、檔案消失、藍屏

4. 檢查建議

切換到你的 C 槽（通常是 SSD） 看一下：

檢查百分比： 確認你的系統碟還有多少壽命。
檢查傳輸模式： 確認它是否跑在 PCIe 4.0 x4 或是你主機板支援的最高速度（如果你是用高效能 NVMe SSD）。

特別提醒：

SSD 如果顯示「黃燈（警告）」，通常不像 HDD 那樣還能透過 chkdsk 救回「邏輯損壞」。SSD 一旦顆粒老化出現錯誤，通常是不可逆的，**「備份」**是唯一的救贖。

下面是我的 LG Gram 筆電兩顆 SSD 檢測結果 :

一. C 碟 : 三星 1TB Samsung PM9A1 (MZVL21T0HCLR)

Gemini 的 SSD 健康檢查報告分析：

1. 核心健康指標

健康狀態：良好 98%。
- 對於已經使用 5323 小時（約 7 個多月不間斷運作）的系統碟來說，只消耗了 2% 的壽命，這代表它的耐用度非常高。依照這個速度，這顆 SSD 要達到壽命臨界值可能還需要十年以上。
SSD 總寫入量：29,768 GB (約 29 TB)。
- 這反映了你作為軟體工程師的工作量。頻繁的編譯、下載與檔案操作都會累積寫入量。29 TB 雖然聽起來很多，但這顆 SSD 的設計寫入壽命通常在 600 TBW 以上，目前僅用了不到 5%。

2. 值得注意的細節

傳輸模式：PCIe 4.0 x4 | PCIe 4.0 x4。
- 這代表你的硬碟正確地運行在最高頻寬下，沒有因為插槽或設定問題被降速。
溫度：39°C。
- 對於 NVMe SSD 來說，這個溫度非常低且理想。這說明 LG Gram 的內部散熱設計（或這顆 Samsung SSD 的發熱控制）做得很好，在高負載運作時也不容易發生因過熱而降速（Thermal Throttling）的情況。
不安全關機次數：33 次 (0x21)。
- 這通常發生在電腦當機、強制長按電源鍵關機，或是電池完全沒電自動關機時。雖然次數不多，但 SSD 對斷電比 HDD 敏感，建議盡量避免在檔案寫入時強制關機。

3. 對於這顆 SSD 的維護建議

注意, SSD 維護上做法與 HDD 完全相反：

絕對不要執行「磁碟重組」： SSD 內部有自己的「磨損均衡 (Wear Leveling)」機制，會自動安排資料存放位置以延長壽命。手動重組只會白白浪費寫入次數，對速度毫無幫助。
確保開啟 TRIM 指令： Windows 10/11 預設會開啟。它會告訴 SSD 哪些區塊的資料已刪除可以回收。
保留 15% 以上空間： 雖然 1TB 很大，但 SSD 如果塞得太滿（超過 90%），寫入放大效應會增加，導致壽命消耗變快且速度變慢。建議 C 碟隨時保留約 150GB 左右的空閒空間。
定期用 CDI 檢查「03 可用備用 (Available Spare)」： 如果這個數值（目前是 100%）開始下降，才代表 SSD 真的開始出現損壞的記憶體顆粒。

總結： 這是一顆頂級的系統碟，目前正處於巔峰狀態，無需任何特殊整理。你那顆 WD 5TB HDD 比較需要關注「整理」，而這顆 Samsung SSD 只要維持正常使用、不要塞太滿即可。

二. D 碟 WD Blue SN570 (1TB) :

Gemini 的 SSD 健康檢查報告分析：

這顆 WD Blue SN570 簡直就是「新車剛過磨合期」的狀態！雖然你是後來擴充的，但從數據上看，這顆硬碟幾乎沒怎麼被「操」到。

以下是針對這顆擴充碟的分析：

1. 核心健康指標

健康狀態：良好 100%。
- 這非常罕見，代表這顆 SSD 的設計壽命完全還沒被消耗。
已用時間總計：82 小時。
- 這真的非常新！對比你 C 碟的 5323 小時，這顆 D 碟基本上才剛開始運作不久。
SSD 總寫入量：137 GB。
- 這個寫入量極低。以 SN570 1TB 版本高達 600 TBW 的耐用度來看，你目前只用了 $0.02\%$ 的壽命。

2. 性能與規格分析

傳輸模式：PCIe 3.0 x4。
- 這是正確的。SN570 本身就是 PCIe 3.0 的規格，所以它跑在 3.0 x4 是發揮全速。雖然你的筆電插槽可能支援到 4.0（如 C 碟那顆），但這顆 D 碟會穩定運行在 3.0 的最高速。
溫度：33°C。
- 比 C 碟還要低，這是一個非常涼爽的操作溫度，對電子零件的長壽非常有幫助。

3. 為什麼這顆硬碟特別適合當「資料存放區」？

SN570 是屬於「無快取 (DRAM-less)」但性能平衡的 SSD。這類硬碟的特性是：

省電： 對於 LG Gram 這種強調續航的筆電非常友善。
發熱低： 很適合放在筆電的第二個擴充槽。
穩定： 非常適合作為存放專案代碼、文件或照片的副碟。

4. 給 Tony 的維護建議

這顆硬碟目前完全不需要任何維護。但既然它是 D 碟，我建議你可以利用它來分擔 C 碟的壓力：

存放開發專案： 既然你的工作涉及 Python 和金融資料分析（kbar 庫等），可以把這些專案放在 D 碟。
虛擬機或 Docker： 如果有使用這些工具，將它們的映像檔放在 D 碟，可以避免 C 碟過快消耗壽命，且這顆 SN570 的速度對於這類應用綽綽有餘。

總結

你這台 LG Gram 的硬碟配置非常健康：

C 碟 (Samsung)： 強大的系統碟，負責作業系統與軟體運行。
D 碟 (WD Blue)： 極新的擴充碟，適合存放長期資料與專案。

WD 5TB 隨身硬碟無法讀取問題

2026-04-20T10:57:00.000+08:00

週六下午在上緯育的 SSD (OpenSec) 線上課程時, 插在 USB 的 WD 5TB 隨身硬碟突然擱登兩聲離線, 我以為是碰到插頭接觸不良而已. 週日晚上要複製檔案時接上 USB, 有讀到驅動 G 碟, 但無法讀取檔案目錄結構 :

週日晚上回到高雄後, 拿另外一條 USB 線連接筆電還是一樣, 於是問 Gemini 該怎麼辦, 它建議我先以管理員身分開啟命令提示字元視窗, 然後用 chdisk 檢查修復檔案目錄連結 :

C:\Users\tony1>chkdsk G: /f

檔案系統的類型是 NTFS。

磁碟區標籤為 Elements。

階段 1: 正在檢查基本檔案系統結構...

已經處理 249088 個檔案記錄。

檔案驗證完成。

階段期間 (檔案記錄驗證): 22.14 秒。

已經處理 47 個大型檔案記錄。

階段期間 (孤立檔案記錄修復): 0.52 毫秒。

已經處理 0 個損毀的檔案記錄。

階段期間 (不正確檔案記錄檢查): 0.98 毫秒。

階段 2: 正在檢查檔案名稱連結...

正在修正檔案 5 中索引 $I30 的錯誤。

CHKDSK 在檔案 5 之索引 $I30 的點陣圖中發現可用空間被標示為已配置。

正在為檔案 5 中的索引 $I30 進行排序。

已經處理 2386 個重新分析記錄。

已經處理 276974 個索引項目。

索引驗證完成。

階段期間 (索引驗證): 3.86 分鐘。

CHKDSK 正在掃描未編製索引的檔案以重新連線到其原始目錄。

正在將孤立的檔案 $MFT (0) 復原成目錄檔案 5。

正在將孤立的檔案 $MFTMirr (1) 復原成目錄檔案 5。

正在將孤立的檔案 $LogFile (2) 復原成目錄檔案 5。

正在將孤立的檔案 $Volume (3) 復原成目錄檔案 5。

正在將孤立的檔案 $AttrDef (4) 復原成目錄檔案 5。

正在將孤立的檔案 . (5) 復原成目錄檔案 5。

正在將孤立的檔案 $Bitmap (6) 復原成目錄檔案 5。

正在將孤立的檔案 $Boot (7) 復原成目錄檔案 5。

正在將孤立的檔案 $BadClus (8) 復原成目錄檔案 5。

正在將孤立的檔案 $Secure (9) 復原成目錄檔案 5。

正在略過關於復原孤立項的後續訊息。

已經掃描 51 個未編製索引的檔案。

51 個未編製索引的檔案已復原到原始目錄。

階段期間 (孤立重新連接): 2.44 秒。

0 個未編製索引的檔案已復原到 [Lost and Found]。

階段期間 (孤兒復原丟失與發現): 36.93 毫秒。

已經處理 2386 個重新分析記錄。

階段期間 (重新剖析點與物件識別碼驗證): 14.32 毫秒。

階段 3: 正在檢查安全性描述元...

安全性描述元驗證完成。

階段期間 (安全性描述項驗證): 50.83 毫秒。

已經處理 13943 個資料檔案。

階段期間 (資料屬性驗證): 1.80 毫秒。

正在修正主檔案表格 (MFT) 鏡像的錯誤。

正在修正磁碟區點陣圖的錯誤。

Windows 已修正檔案系統。

不需要進一步的動作。

磁碟空間總計 4769272 MB。

234806 個檔案共 4371444 MB。

13945 個索引共 71928 KB。

損壞的磁區共 0 KB。

系統使用空間 464123 KB。

記錄檔共佔用 65536 KB。

磁碟可用空間 406840116 KB。

每個配置單位有 4096 個位元組。

磁碟上共有 1220933887 個配置單位。

磁碟上有 101710029 個可用的配置單位。

總持續時間: 4.28 分鐘 (256882 毫秒)。

----------------------------------------

我把以上結果貼給 Gemini 評估, 結果如下 :

-----------------------------------------------------------

這代表你的 5TB 硬碟硬體暫時看起來是健康的，這次純粹是軟體層面的「索引混亂」。

從你的 Log 來看，這次修復了幾個關鍵問題：

1. 修復了什麼？

索引點陣圖 (Bitmap) 錯誤：這就像是圖書館的目錄說某個位置是空的，但實際上那裡放了書。chkdsk 重新校正了這些空間分配。
孤立檔案 (Orphaned Files) 復原：這部分最關鍵。你的 $MFT（主檔案表格）等系統檔案一度失去了連結，導致 Windows 看不到目錄。chkdsk 把這些「走丟」的系統檔案重新接回了目錄樹（檔案 5）。
MFT 鏡像修正：主檔案表格的備份也被同步修正了，確保下次讀取穩定。

2. 後續建議 (SOP)

雖然現在讀得到了，但身為開發者，我們都知道「事出必有因」。為了確保這顆 5TB 隨身硬碟之後不再搞事，建議你做以下幾件事：

立刻檢查 S.M.A.R.T. 資訊： 雖然 chkdsk 顯示 0 壞軌，但那是「邏輯層面」。建議用 CrystalDiskInfo 看一下 05 (重新分配磁區數) 和 C5 (等候重映射的磁區數) 是否為 0。如果這兩個數值不是 0，代表硬碟物理壽命快到頭了，趕快趁現在備份。
養成「安全移除」的習慣： 這次的錯誤（索引與點陣圖不符）最常發生在資料寫入中途拔掉 USB，或是 USB 供電不穩（例如插在前端 USB 孔或 Hub 上）。下次拔除前，務必點選右下角的「安全移除硬體」。
停用「快速啟動」或檢查寫入快取： 如果你常用這顆硬碟，可以在「裝置管理員」>「磁碟機」>「WD Elements」內容中，確認「原則」設定。如果追求安全，可以選擇「快速移除」（停用寫入快取）。

3. 關於資料安全

這顆硬碟已經 4.3TB 滿載（剩下約 400GB），這對 5TB 硬碟來說負擔不小，且檔案系統毀損過一次後，穩定性會略微下降。

建議下一步： 既然現在恢復了，趁這幾天趕快把裡面最不可取代的資料（例如你的 e-book 草稿、kbar 原始碼等）同步到雲端或另一顆實體硬碟上。

-----------------------------------------------------

做完 chdisk 果然就恢復正常了, 還好能修復連結, 否則裡面去年以來的上課資料毀壞那就虧大了. 接下來我按照其建議去下載安裝 CrystalDiskInfo 來檢測硬碟狀況, 此軟體是日本人開發的, 體積很小直接到微軟 Store 下載安裝 (網路上的免安裝版我用 VirusTotal 掃描幾乎都有夾帶木馬) :

# https://apps.microsoft.com/detail/xp8k4rgx25g3gm?hl=zh-TW&gl=TW

檢測結果如下 :

貼給 Gemini 分析結果如下 :

這份健康報告非常漂亮，這顆 WD 5TB 隨身硬碟目前的硬體狀態非常健康。

以下是針對這張截圖的幾個核心分析：

1. 關鍵健康指標 (核心數據)

健康狀態：良好。這是最直觀的結果。
05 (重定位磁區計數)： 原始值為 0。這代表硬碟沒有任何物理壞軌被替換掉，碟盤表面狀況良好。
C5 (等候重定的磁區計數)： 原始值為 0。這代表沒有任何疑似壞軌在排隊。
C6 (無法校正的磁區計數)： 原始值為 0。再次確認磁區資料讀寫穩定。

2. 使用記錄

已用時間總計：3931 小時。這顆硬碟大約已經服役了 5 個多月（如果是 24 小時不關機計算），對於一顆隨身硬碟來說，正處於「壯年期」。
已用次數總計：578 次。平均每次開機使用約 6.8 小時。
轉速：4800 RPM。這是典型的 2.5 吋節能/高容量硬碟規格，發熱量會比較低，目前的 37°C 非常理想。

3. 為什麼會發生「檔案目錄毀損」？

既然硬體沒問題，那為什麼會噴錯誤？最可能的兇手有三個：

異常拔除： 在 Windows 還在寫入快取資料時，就直接拔掉 USB 線，導致 NTFS 的 MFT (Master File Table) 沒寫完。
供電瞬間不穩： 5TB 的碟盤密度很高，對電流波動敏感。如果插在不穩的 USB 插座，讀寫中途掉電也會導致邏輯錯誤。
磁碟已滿的副作用： 你的硬碟已經用了 4.3TB 以上，當空間極度剩餘不足時，NTFS 的碎片整理或元數據更新會變得很頻繁，這時候若發生中斷，毀損機率會變高。

4. 維護建議

繼續使用： 沒問題，它不是快掛了，只是「軟體感冒」剛修好。
安全退出： 之後請務必點選 Windows 右下角的「安全移除硬體」。
避免前端插槽： 建議優先插在電腦機殼後方的 USB 孔（或供電足夠的電競筆電插孔），穩定電壓是 5TB 硬碟的長壽關鍵。

------------------------------------------------

這顆硬碟就回來了真是好佳在啊! 趕緊開啟 MIS 桌機, 把內容複製到 18TB 大硬碟裡備份. 這顆也快裝滿了, 也準備要換新的一顆來用了.

2026 年第 15 周記事

2026-04-19T17:44:00.001+08:00

又過了一周了, 四月下旬天氣變得熱起來, 今年的芒果樹結果不多, 菜園的只有兩棵樹有結果, 另外路邊的只有零星結一些, 我今天下午拿去年剩餘的袋子去套袋, 只完成菜園的那兩棵樹, 路邊的等下周再套. 套袋時在儲水池旁的芒果樹上發現一個鳥巢, 裡面有孵化的雛鳥兩隻 :

我傳給 Gemini 辨認, 說是白頭翁的雛鳥 :

這幾天回頭整理我的 5 台 Linux 主機, 其中三台樹莓派是我的主要爬蟲主機, 前陣子不明原因當機, 直到前幾天才有時間重灌, 順便把爬蟲程式升版. 接下來要做的有下列三件 :

Serverless 平台加入 API Key
高雄光世代固定 IP & 全屋通路由器設定
Mapleboard 外接 USB 儲存設定
鄉下的 Pi 3 主機升版為 Bulleye

鄉下的 Pi 3 主機目前跑的是 Stretch, 這根本是老古董了, 今天已備份 SD 卡內資料, 準備買一張 32 GB 卡來升版為 Bulleye.

Python 學習筆記 : 市圖借書與預約爬蟲程式改版 v13

2026-04-18T23:32:00.007+08:00

將母校圖書館爬蟲升版後打鐵趁熱, 今天順便將此次優化 Selenium 爬蟲的技巧也套用在市圖爬蟲程式上, 可同時於 Pi 400, Pi 3B, 與 Pi 3A+ 上執行.

本系列全部測試文章索引參考 :

# Python 網頁爬蟲筆記索引

新版 v13 程式碼如下 :

# ksml_lib_13.py

from selenium import webdriver

from selenium.webdriver.common.by import By

from selenium.webdriver.chrome.options import Options

from selenium.webdriver.chrome.service import Service

import re

from datetime import datetime

import time

import requests

import sys

from dotenv import dotenv_values

import os

import socket

async def telegram_send_text(text):

bot=Bot(token=TELEGRAM_TOKEN)

try:

await bot.send_message(

chat_id=TELEGRAM_ID,

text=text

)

return True

except Exception as e:

print(f'Error sending text: {e}')

return False

def get_books(account, password):

browser=None

result=(None, None) # 預設回傳值

try:

# 登入我的書房

# 設定一個在 SD 卡上的暫存目錄 (for Trixie)

chrome_tmp_path=os.path.expanduser('~/chrome_tmp')

if not os.path.exists(chrome_tmp_path):

os.makedirs(chrome_tmp_path)

options=Options()

options.add_argument("--headless=new") # 新版無頭擬真瀏覽器

options.add_argument("--no-sandbox") # Trixie 必加

options.add_argument("--disable-dev-shm-usage") # 避免擠爆 /dev/shm

options.add_argument('--disable-gpu') # 避免 GPU 驅動崩潰

# 強迫使用 SD 卡空間 (特別是 Trixie 必須)

options.add_argument(f'--user-data-dir={chrome_tmp_path}')

# 限制快取大小為 100MB (防止 chrome_tmp 資料夾隨著時間變得巨大)

options.add_argument('--disk-cache-size=104857600')

options.binary_location='/usr/bin/chromium'

service=Service('/usr/bin/chromedriver')

browser=webdriver.Chrome(service=service, options=options)

browser.implicitly_wait(60)

browser.set_window_size(1920, 1080)

# 載入網頁

browser.get('https://webpacx.ksml.edu.tw/personal/')

loginid=browser.find_element(By.ID, 'logxinid')

loginid.send_keys(account)

pincode=browser.find_element(By.ID, 'pincode')

pincode.send_keys(password)

div_btn_grp=browser.find_element(By.CLASS_NAME, 'btn_grp')

login_btn=div_btn_grp.find_element(By.TAG_NAME, 'input')

login_btn.click()

# 擷取借閱紀錄

div_redblock=browser.find_element(By.CLASS_NAME, 'redblock')

div_redblock.click()

books=browser.find_elements(By.CLASS_NAME, 'bookdata')

borrow_books=[]

for book in books:

item=dict()

book_name=book.find_element(By.XPATH, './h2/a').text

item['book_name']=book_name.replace('/', '').strip()

book_site=book.find_element(By.XPATH, './ul[3]/li[1]').text

reg=r'典藏地：(\S+)'

item['book_site']=re.findall(reg, book_site)[0]

reg=r'\d{4}-\d{2}-\d{2}'

due_date=book.find_element(By.XPATH, './ul[4]/li[2]').text

item['due_date']=re.findall(reg, due_date)[0]

due_times=book.find_element(By.XPATH, './ul[5]/li[1]').text

item['due_times']=re.findall(r'\d{1}', due_times)[0]

try:

state=book.find_element(By.XPATH, './ul[6]/li[1]').text

except:

state=''

finally:

if '有人預約' in state:

item['state']=', 有人預約'

else:

item['state']=''

borrow_books.append(item)

print('擷取借閱紀錄 ... OK')

browser.back() # 回上一頁

# 擷取預約紀錄

div_blueblock=browser.find_element(By.CLASS_NAME, 'blueblock')

div_blueblock.click()

books=browser.find_elements(By.CLASS_NAME, 'bookdata')

reserve_books=[]

for book in books:

item=dict()

book_name=book.find_element(By.XPATH, './h2/a').text

item['book_name']=book_name.replace('/', '').strip()

sequence=book.find_element(By.XPATH, './ul[7]/li[1]').text

if '預約待取' in sequence: # 已到館

item['ready_for_pickup']=True

reg=r'\d{4}-\d{2}-\d{2}'

item['expiration']=re.findall(reg, sequence)[0]

item['sequence']='0'

else: # 預約中

item['ready_for_pickup']=False

item['expiration']=''

item['sequence']=re.findall(r'\d+', sequence)[0]

reserve_books.append(item)

print('擷取預約紀錄 ... OK')

result=(borrow_books, reserve_books)

except Exception as e:

print(f'發生錯誤 : {e}')

finally:

if browser:

try:

browser.quit() # 釋放記憶體

print('資源已釋放')

except:

pass

return result

if __name__ == '__main__':

start=time.time()

config=dotenv_values('.env')

TELEGRAM_TOKEN=config.get('TELEGRAM_TOKEN')

TELEGRAM_ID=config.get('TELEGRAM_ID')

#print(TELEGRAM_TOKEN)

#print(TELEGRAM_ID)

host_name=socket.gethostname()

print(f'主機 : {host_name}')

if len(sys.argv) != 3:

print(f'用法: {sys.argv[0]} 帳號密碼')

sys.exit(1)

# 取得傳入的帳密參數

account=sys.argv[1]

password=sys.argv[2]

# 呼叫 get_books() 取得借書與預約書

borrow_books, reserve_books=get_books(account, password)

b_msg='' # 借書資訊字串初始值

r_msg='' # 預約資訊字串初始值

# 處理借書

if borrow_books:

borrow=[]

for book in borrow_books:

book_name=book['book_name']

book_site=book['book_site']

due_times=book['due_times']

due_date=book['due_date']

state=book['state']

due_date=datetime.strptime(due_date, '%Y-%m-%d') # 到期日

today_str=datetime.today().strftime('%Y-%m-%d')

today=datetime.strptime(today_str, "%Y-%m-%d")

delta=(due_date-today).days # 計算離到期日還有幾天

if delta < 0: # 負數=已逾期

msg=f'🅧 {book_name} (逾期 {abs(delta)} 天{state}, {book_site})'

borrow.append(msg)

elif delta == 0: # 0=今天到期

msg=f'⓿ {book_name} (今日到期, 續借次數 {due_times}{state}, {book_site})'

borrow.append(msg)

elif delta == 1: # 1=明天到期

msg=f'❶ {book_name} (明日到期, 續借次數 {due_times}{state}, {book_site})'

borrow.append(msg)

elif delta == 2: # 2=後天到期

msg=f'❷ {book_name} (後天到期, 續借次數 {due_times}{state}, {book_site})'

borrow.append(msg)

elif 2 < delta < 8: # 3 天以上一周內到期

msg=f'✦ {book_name} ({book["due_date"]} 到期, '\

f'續借次數 {due_times}{state}, {book_site})'

borrow.append(msg)

# 製作借書到期摘要字串

if len(borrow) != 0:

borrow.insert(0, f'\n❖ {account} 的借閱 :')

b_msg='\n'.join(borrow) # 更新借書資訊字串

print('產生借書到期摘要 ... OK')

# 處理預約書

if reserve_books:

reserve=[]

i=0

j=['①', '②', '③', '④', '⑤']

k=['❶', '❷', '❸', '❹', '❺']

# 預約狀態

for book in reserve_books:

book_name=book['book_name']

sequence=book['sequence']

ready_for_pickup=book['ready_for_pickup'] # 已到館

expiration=book['expiration'] # 取書截止日

if ready_for_pickup:

msg=f'{k[i]} {book_name} (已到館, 保留期限 {expiration})'

else:

msg=f'{j[i]} {book_name} (順位 {sequence})'

reserve.append(msg)

i += 1

# 製作預約書摘要字串

if len(reserve) != 0:

reserve.insert(0, f'\n❖ {account} 的預約 :')

r_msg='\n'.join(reserve) # 更新資訊字串

print('產生預約書摘要 ... OK')

if b_msg or r_msg: # 任一不為空字串就更新資料表

url="https://serverless-5e6i.onrender.com/function/update_ksml_books"

payload={

"account": account,

"borrow_books": b_msg,

"reserve_books": r_msg

}

res=requests.post(url, json=payload)

print(res.json())

end=time.time()

print(f'執行時間:{end-start}')

此次改版也修正了 try-except-finally 結構, 把 browser.close() 改成 browser.quit(), 前者雖然會把視窗關掉, 但背景的 chromedriver 可能還在跑繼續吃 RAM, 導致背景殘留了一堆 chromedriver 的殭屍進程. 此優化版程式在 Pi 3B, 3A+ 與 Pi 400 均可順利執行.

執行結果如下 :

pi@kaopi3:~ $ python ksml_lib_12.py faxxxxxx 123456

擷取借閱紀錄 ... OK

擷取預約紀錄 ... OK

產生借書到期摘要 ... OK

產生預約書摘要 ... OK

{'message': 'faxxxxxx 的資料已更新', 'status': 'success'}

執行時間:667.9564106464386

pi@pi3aplus:~ $ python ksml_lib_12.py faxxxxxx 123456

主機 : pi3aplus

擷取借閱紀錄 ... OK

擷取預約紀錄 ... OK

資源已釋放

產生借書到期摘要 ... OK

產生預約書摘要 ... OK

{'message': 'faxxxxxx 的資料已更新', 'status': 'success'}

執行時間:675.6979095935822

(myenv313) pi@pi400:~ $ python ksml_lib_12.py faxxxxxx 123456

主機 : pi400

擷取借閱紀錄 ... OK

擷取預約紀錄 ... OK

資源已釋放

產生借書到期摘要 ... OK

產生預約書摘要 ... OK

{'message': 'faxxxxxx 的資料已更新', 'status': 'success'}

執行時間:573.2406423091888

可見 Pi 3B 與 3A+ 速度差不多, 但 Pi 400 就快了 100 秒.

注意, 此處呼叫的後端端點有兩個, 都是建置在 Render 平台上的 serverless 服務, 目前我有兩個端點, 分配如下 :

kaopi3 : https://serverless-5e6i.onrender.com/function/send_books_messages
pi3aplus : https://serverless-fdof.onrender.com/function/send_books_messages
pi400 : https://serverless-fdof.onrender.com/function/send_books_messages (備用)

擷取並傳送借書資訊的程式 get_ksml_books_messages.py 也是要設定對應端點, 例如 kaopi3 :

# get_ksml_books_messages.py

import requests

import socket

host_name=socket.gethostname()

print(f'主機 : {host_name}')

params={'crawler': f'{host_name}'}

url='https://serverless-5e6i.onrender.com/function/send_books_messages'

res=requests.get(url, params=params)

print(res)

此爬蟲程式會呼叫 serverless 平台上的 send_books_messages.py 函式讀取 serverless.db 上記錄的借書與預約資訊, 並送出 Telegram 訊息. send_books_messages.py 函式內容如下 :

# send_ksml_books_messages.py

import asyncio

import sqlite3

from telegram import Bot

async def telegram_send_text(token, chat_id, text):

"""非同步傳送 Telegram 訊息"""

try:

bot=Bot(token=token)

await bot.send_message(chat_id=chat_id, text=text)

return True

except Exception as e:

print(f"傳送失敗: {e}")

return False

def main(request, **kwargs):

DB_PATH='./serverless.db'

config=kwargs.get('config', {})

telegram_token=config.get('TELEGRAM_TOKEN')

telegram_id=config.get('TELEGRAM_ID')

if not telegram_token or not telegram_id:

return '未設定 TELEGRAM_TOKEN 或 TELEGRAM_ID'

try: # 連線資料庫

conn=sqlite3.connect(DB_PATH)

cur=conn.cursor()

cur.execute("SELECT borrow_books, reserve_books FROM ksml_books;")

rows=cur.fetchall()

conn.close()

except Exception as e:

return f'資料庫讀取失敗: {e}'

if not rows:

return '沒有任何資料可傳送'

# 傳送訊息

success_count=0

fail_count=0

for borrow_books, reserve_books in rows:

for msg in [borrow_books, reserve_books]:

if msg and msg.strip():

ok=asyncio.run(telegram_send_text(telegram_token, telegram_id, msg))

if ok:

success_count += 1

else:

fail_count += 1

return f'傳送完成：成功 {success_count} 筆，失敗 {fail_count} 筆'

市圖爬蟲架構較複雜, 得畫一張圖來備忘才行.

Python 學習筆記 : 母校圖書館借書與預約爬蟲程式改版 v11

2026-04-18T00:51:00.006+08:00

之前版本的爬蟲我都把帳號密碼金鑰等等都寫在程式碼裡, 這實在不是好的做法, 今天將爬蟲進行改版, 將帳密金鑰都存放在隱藏檔 .env 中, 於程式裡利用 dotenv 從 .env 檔讀取出來. 關於 dotenv 用法參考 :

# Python 學習筆記 : 如何隱藏 API 金鑰或權杖

# Python 學習筆記 : dotenv 取值的另類用法

本系列全部文章索引參考 :

# Python 網頁爬蟲筆記索引

先將目前的第 10 版爬蟲複製一份到第 11 版 :

pi@kaopi3:~ $ cp nkust_lib_10.py nkust_lib_11.py

用 nano 編輯程式碼 :

pi@kaopi3:~ $ nano nkust_lib_11.py

修改為如下 :

# nkust_lib_11.py

from selenium import webdriver

from selenium.webdriver.common.by import By

from selenium.webdriver.common.action_chains import ActionChains

from selenium.webdriver.chrome.options import Options

from selenium.webdriver.chrome.service import Service

import time

import requests

from datetime import datetime

import asyncio

from telegram import Bot

import re

from dotenv import dotenv_values

async def telegram_send_text(text):

bot=Bot(token=TELEGRAM_TOKEN)

try:

await bot.send_message(

chat_id=TELEGRAM_ID,

text=text

)

return True

except Exception as e:

print(f'Error sending text: {e}')

return False

def get_nkust_lib():

browser=None

msg="無法取得資料" # ✅ 防止未賦值

try:

options=Options()

options.add_argument("--headless=new")

options.add_argument("--no-sandbox")

options.add_argument("--disable-dev-shm-usage")

options.binary_location="/usr/bin/chromium"

service=Service("/usr/bin/chromedriver")

browser=webdriver.Chrome(service=service, options=options)

browser.implicitly_wait(60)

browser.set_window_size(1920, 1080)

url=(

'https://nkust.primo.exlibrisgroup.com/discovery/login?'

'vid=886NKUST_INST:86NKUST&lang=zh-tw'

)

browser.get(url)

# 按其他讀者

md_list=browser.find_elements(By.TAG_NAME, 'md-list-item')

if len(md_list) > 1:

md_list[1].click()

print('按其他讀者 ... OK')

# 登入系統

login_user_name=browser.find_element(By.ID, 'LoginUserName')

login_user_name.send_keys(NKUST_LIB_ID)

login_password=browser.find_element(By.ID, 'LoginPassword')

login_password.send_keys(NKUST_LIB_PWD)

login_btn=browser.find_element(By.CLASS_NAME, 'button-large')

login_btn.click()

print('登入系統 ... OK')

# 按名字顯現選單

user_btn=browser.find_element(By.CLASS_NAME, 'user-button')

actions=ActionChains(browser)

actions.move_to_element(user_btn)

actions.click(user_btn)

actions.perform()

print('按名字顯現選單 ... OK')

# 按我的借閱鈕

xpath='/html/body/div[3]/md-menu-content/md-menu-item[3]/button'

my_borrow=browser.find_element(By.XPATH, xpath)

actions.move_to_element(my_borrow)

actions.click(my_borrow)

actions.perform()

print('按我的借閱 ... OK')

# 按全部續借

xpath=(

'/html/body/primo-explore/div/prm-account/md-content'

'/div[2]/prm-account-overview/md-content/md-tabs/'

'md-tabs-content-wrapper/md-tab-content[2]/div/'

'div/prm-loans/div[1]/div[2]/div[2]/button'

)

all_borrow=browser.find_element(By.XPATH, xpath)

actions.move_to_element(all_borrow)

actions.click(all_borrow)

actions.perform()

print('按全部續借 ... OK')

# 檢查續借結果

xpath=(

'/html/body/primo-explore/div/prm-account/md-content'

'/div[2]/prm-account-overview/md-content/md-tabs'

'/md-tabs-content-wrapper/md-tab-content[2]/div/div'

'/prm-loans/div[2]/prm-alert-bar/div/div/span'

)

alert_span=browser.find_element(By.XPATH, xpath)

if '所有借閱資料已成功續借' in alert_span.text:

msg='❖ 所有借閱資料已成功續借'

else:

msg='❖ 只有部分借閱資料已成功續借'

# 檢查是否有 "載入更多結果" 按鈕

for i in range(3): # 最多 3 頁

load_more=browser.find_elements(By.CLASS_NAME, 'button-confirm')

if not load_more:

break

load_more[0].click()

time.sleep(2)

# 抓取所有借閱書目

loan_items=browser.find_elements(By.TAG_NAME, 'md-list-item')

unrenew_books=[]

for item in loan_items:

try:

# ✅ 1. 必須有書名才是書

title_elem=item.find_elements(By.CSS_SELECTOR, "h3 a")

if not title_elem:

continue

title=title_elem[0].text.strip()

item_text=item.text.strip()

# ✅ 2. 取得到期日

due_text=''

due_elem=item.find_elements(By.XPATH, './/p[@data-qa="automation_mlc_record_date"]')

if due_elem:

m=re.search(r'\d{2}/\d{2}/\d{4}', due_elem[0].text)

if m:

due_text=m.group(0)

# ✅ 3. 只收真正「被預約 / 無法續借」

if any(k in item_text for k in ["被預約", "無法續借", "recall"]):

unrenew_books.append((title, due_text))

except Exception:

continue

if unrenew_books:

msg="被預約的書：\n" + "\n".join(

[f"{i+1:>2}. {t[0]}　到期日: {t[1]}" for i, t in enumerate(unrenew_books)]

)

else:

msg="全部書籍皆已續借"

print('搜尋被預約書籍 ... OK')

except Exception as e:

print(e)

finally:

if browser:

browser.quit() # ✅ 防呆

return msg # ✅ msg 一定有值

if __name__ == '__main__':

start=time.time()

config=dotenv_values('.env')

NKUST_LIB_ID=config.get('NKUST_LIB_ID')

NKUST_LIB_PWD=config.get('NKUST_LIB_PWD')

TELEGRAM_TOKEN=config.get('TELEGRAM_TOKEN')

TELEGRAM_ID=config.get('TELEGRAM_ID')

#print(NKUST_LIB_ID)

#print(NKUST_LIB_PWD)

#print(TELEGRAM_TOKEN)

#print(TELEGRAM_ID)

msg=get_nkust_lib()

if msg:

now=datetime.now().strftime('%Y-%m-%d %H:%M:%S')

msg='\n' + now + '\n' + msg

if asyncio.run(telegram_send_text(msg)):

print('訊息傳送成功!')

else:

print('訊息傳送失敗!')

print(msg)

end=time.time()

print(f'執行時間:{end-start}')

黃底高亮者為修改或添加的部分, 執行結果如下 :

pi@kaopi3:~ $ python nkust_lib_11.py

按其他讀者 ... OK

登入系統 ... OK

按名字顯現選單 ... OK

按我的借閱 ... OK

按全部續借 ... OK

訊息傳送成功!

2026-04-18 00:37:52

❖ 所有借閱資料已成功續借

執行時間:81.74577593803406

2026-04-18 補充 :

早上又對程式碼進行局部微調, 版本號仍維持 v11, 主要修改如下 :

1. 添加主機名稱訊息 :
利用 socket.gethostname() 即可得到主機名稱. 這樣收到 Telegram 才知道是哪台主機的爬蟲完成的.

2. 使用 SD 卡儲存 Chrome/Chromium 暫存資料 :

由於 Pi 400 的 Trixie 仍然開發演進中, 最新版本改用 Chrome 而非 Chromium, 跑 Selenium 爬蟲時使用 DRAM 來暫存資料, 可能導致 DRAM 塞滿而使瀏覽器閃退, 於是改為強制將暫存資料放在 chrome_tmp 資料夾下, 瀏覽器設定修改為 :

# 設定一個在 SD 卡上的暫存目錄 (for Trixie)

chrome_tmp_path=os.path.expanduser('~/chrome_tmp')

if not os.path.exists(chrome_tmp_path):

os.makedirs(chrome_tmp_path)

options=Options()

options.add_argument("--headless=new") # 新版無頭擬真瀏覽器

options.add_argument("--no-sandbox") # Trixie 必加

options.add_argument("--disable-dev-shm-usage") # 避免擠爆 /dev/shm

options.add_argument('--disable-gpu') # 避免 GPU 驅動崩潰

# 強迫使用 SD 卡空間 (特別是 Trixie 必須)

options.add_argument(f'--user-data-dir={chrome_tmp_path}')

# 限制快取大小為 100MB (防止 chrome_tmp 資料夾隨著時間變得巨大)

options.add_argument('--disk-cache-size=104857600')

以上設定雖然是針對 Trixie, 但在 Bulleye (Pi 3 & Pi 3A+) 上跑也是可以的. 完整程式碼如下 :

# nkust_lib_11.py

from selenium import webdriver

from selenium.webdriver.common.by import By

from selenium.webdriver.common.action_chains import ActionChains

from selenium.webdriver.chrome.options import Options

from selenium.webdriver.chrome.service import Service

import time

import requests

from datetime import datetime

import asyncio

from telegram import Bot

import re

from dotenv import dotenv_values

import os

import socket

async def telegram_send_text(text):

bot=Bot(token=TELEGRAM_TOKEN)

try:

await bot.send_message(

chat_id=TELEGRAM_ID,

text=text

)

return True

except Exception as e:

print(f'Error sending text: {e}')

return False

def get_nkust_lib():

browser=None

msg="無法取得資料" # ✅ 防止未賦值

try:

# 設定一個在 SD 卡上的暫存目錄 (for Trixie)

chrome_tmp_path=os.path.expanduser('~/chrome_tmp')

if not os.path.exists(chrome_tmp_path):

os.makedirs(chrome_tmp_path)

options=Options()

options.add_argument("--headless=new") # 新版無頭擬真瀏覽器

options.add_argument("--no-sandbox") # Trixie 必加

options.add_argument("--disable-dev-shm-usage") # 避免擠爆 /dev/shm

options.add_argument('--disable-gpu') # 避免 GPU 驅動崩潰

# 強迫使用 SD 卡空間 (特別是 Trixie 必須)

options.add_argument(f'--user-data-dir={chrome_tmp_path}')

# 限制快取大小為 100MB (防止 chrome_tmp 資料夾隨著時間變得巨大)

options.add_argument('--disk-cache-size=104857600')

options.binary_location="/usr/bin/chromium"

service=Service("/usr/bin/chromedriver")

browser=webdriver.Chrome(service=service, options=options)

browser.implicitly_wait(60)

browser.set_window_size(1920, 1080)

url=(

'https://nkust.primo.exlibrisgroup.com/discovery/login?'

'vid=886NKUST_INST:86NKUST&lang=zh-tw'

)

browser.get(url)

# 按其他讀者

md_list=browser.find_elements(By.TAG_NAME, 'md-list-item')

if len(md_list) > 1:

md_list[1].click()

print('按其他讀者 ... OK')

# 登入系統

login_user_name=browser.find_element(By.ID, 'LoginUserName')

login_user_name.send_keys(NKUST_LIB_ID)

login_password=browser.find_element(By.ID, 'LoginPassword')

login_password.send_keys(NKUST_LIB_PWD)

login_btn=browser.find_element(By.CLASS_NAME, 'button-large')

login_btn.click()

print('登入系統 ... OK')

# 按名字顯現選單

user_btn=browser.find_element(By.CLASS_NAME, 'user-button')

actions=ActionChains(browser)

actions.move_to_element(user_btn)

actions.click(user_btn)

actions.perform()

print('按名字顯現選單 ... OK')

# 按我的借閱鈕

xpath='/html/body/div[3]/md-menu-content/md-menu-item[3]/button'

my_borrow=browser.find_element(By.XPATH, xpath)

actions.move_to_element(my_borrow)

actions.click(my_borrow)

actions.perform()

print('按我的借閱 ... OK')

# 按全部續借

xpath=(

'/html/body/primo-explore/div/prm-account/md-content'

'/div[2]/prm-account-overview/md-content/md-tabs/'

'md-tabs-content-wrapper/md-tab-content[2]/div/'

'div/prm-loans/div[1]/div[2]/div[2]/button'

)

all_borrow=browser.find_element(By.XPATH, xpath)

actions.move_to_element(all_borrow)

actions.click(all_borrow)

actions.perform()

print('按全部續借 ... OK')

# 檢查續借結果

xpath=(

'/html/body/primo-explore/div/prm-account/md-content'

'/div[2]/prm-account-overview/md-content/md-tabs'

'/md-tabs-content-wrapper/md-tab-content[2]/div/div'

'/prm-loans/div[2]/prm-alert-bar/div/div/span'

)

alert_span=browser.find_element(By.XPATH, xpath)

if '所有借閱資料已成功續借' in alert_span.text:

msg='❖ 所有借閱資料已成功續借'

else:

msg='❖ 只有部分借閱資料已成功續借'

# 檢查是否有 "載入更多結果" 按鈕

for i in range(3): # 最多 3 頁

load_more=browser.find_elements(By.CLASS_NAME, 'button-confirm')

if not load_more:

break

load_more[0].click()

time.sleep(2)

# 抓取所有借閱書目

loan_items=browser.find_elements(By.TAG_NAME, 'md-list-item')

unrenew_books=[]

for item in loan_items:

try:

# ✅ 1. 必須有書名才是書

title_elem=item.find_elements(By.CSS_SELECTOR, "h3 a")

if not title_elem:

continue

title=title_elem[0].text.strip()

item_text=item.text.strip()

# ✅ 2. 取得到期日

due_text=''

due_elem=item.find_elements(By.XPATH, './/p[@data-qa="automation_mlc_record_date"]')

if due_elem:

m=re.search(r'\d{2}/\d{2}/\d{4}', due_elem[0].text)

if m:

due_text=m.group(0)

# ✅ 3. 只收真正「被預約 / 無法續借」

if any(k in item_text for k in ["被預約", "無法續借", "recall"]):

unrenew_books.append((title, due_text))

except Exception:

continue

if unrenew_books:

msg="被預約的書：\n" + "\n".join(

[f"{i+1:>2}. {t[0]}　到期日: {t[1]}" for i, t in enumerate(unrenew_books)]

)

else:

msg="全部書籍皆已續借"

print('搜尋被預約書籍 ... OK')

except Exception as e:

print(e)

finally:

if browser:

browser.quit() # ✅ 防呆

return msg # ✅ msg 一定有值

if __name__ == '__main__':

start=time.time()

config=dotenv_values('.env')

NKUST_LIB_ID=config.get('NKUST_LIB_ID')

NKUST_LIB_PWD=config.get('NKUST_LIB_PWD')

TELEGRAM_TOKEN=config.get('TELEGRAM_TOKEN')

TELEGRAM_ID=config.get('TELEGRAM_ID')

#print(NKUST_LIB_ID)

#print(NKUST_LIB_PWD)

#print(TELEGRAM_TOKEN)

#print(TELEGRAM_ID)

host_name=socket.gethostname()

print(f'主機 : {host_name}')

msg=get_nkust_lib()

if msg:

now=datetime.now().strftime('%Y-%m-%d %H:%M:%S')

msg='\n' + now + '\n' + msg + '\n' + f'(host_name)'

if asyncio.run(telegram_send_text(msg)):

print('訊息傳送成功!')

else:

print('訊息傳送失敗!')

print(msg)

end=time.time()

print(f'執行時間:{end-start}')

執行結果 :

pi@kaopi3:~ $ python nkust_lib_11.py

主機 : kaopi3

按其他讀者 ... OK

登入系統 ... OK

按名字顯現選單 ... OK

按我的借閱 ... OK

按全部續借 ... OK

搜尋被預約書籍 ... OK

訊息傳送成功!

2026-04-18 11:14:19

全部書籍皆已續借

(kaopi3)

執行時間:358.6611738204956