課前準備

先確認一件事：你會用終端機嗎

這場工作坊全程在終端機裡進行。如果你平常只在 VS Code 按執行鍵、 或只用過 Google Colab，先跟著下面的操作認識它。

你需要安裝兩個東西

安裝

Windows

Windows 11 內建了一個叫 winget 的套件管理員（跟系統一起出貨的 App Installer），所以你什麼都不用先裝。 開啟 PowerShell（開始選單搜尋「PowerShell」），貼上這兩行：

winget install SST.opencode --accept-source-agreements --accept-package-agreements
winget install astral-sh.uv --accept-source-agreements --accept-package-agreements

macOS

macOS 內建 curl，直接開「終端機」貼這兩行：

curl -fsSL https://opencode.ai/install | bash
curl -LsSf https://astral.sh/uv/install.sh | sh

（macOS 請依官方安裝說明操作，課前完成同一份自測；需要協助時提早聯絡講師。）

Linux / WSL

這裡要多一個步驟。下載工具 curl 不一定裝在你的系統裡， Ubuntu 的基本安裝並不包含它。真正一定有的是套件管理員 apt， 所以先用它把 curl 補上：

sudo apt update && sudo apt install -y curl ca-certificates

（ca-certificates 是驗證 HTTPS 憑證用的，少了它 curl 會連不上。 如果這兩個本來就有，這行也只會告訴你「已經是最新版」，不會弄壞任何東西。）

接著才裝 opencode 與 uv：

curl -fsSL https://opencode.ai/install | bash
curl -LsSf https://astral.sh/uv/install.sh | sh

裝完後關掉終端機重開，或執行 source ~/.bashrc。

確認裝好了

opencode --version
uv --version

兩個指令都應印出版本號；記下來，之後求助時可以一起提供。

建立工作坊專案

mkdir ai-math-lab
cd ai-math-lab
mkdir notes
mkdir figs

[project]
name = "ai-math-lab"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = [
    "numpy>=1.26",
    "scipy>=1.11",
    "matplotlib>=3.8",
    "scikit-learn>=1.4",
    "networkx>=3.2",
]

{
  "$schema": "https://opencode.ai/config.json",
  "model": "opencode/big-pickle",
  "permission": {
    "bash": "ask",
    "edit": "ask",
    "webfetch": "ask"
  },
  "instructions": ["AGENTS.md"]
}

# AI-Math 工作坊　專案規則

## 語言
一律使用台灣繁體中文回答。程式碼、變數名稱、套件名稱保留英文。

## 執行環境
本專案用 uv 管理環境。執行 Python 一律用：`uv run python <檔案>`
不要用 `python`、`python3`、`pip install`。要加套件用 `uv add <套件>`。

## 數學程式的規矩
1. 可重現：用到隨機性的地方一律設 `random_state=0` 或 `np.random.seed(0)`。
2. 先說數學，再寫程式：動手前先用兩三句話說明你要用的公式或步驟。
3. 自己驗證：寫完數值方法必須附驗證程式碼，實際執行並印出比對結果。
   不可以只說「應該正確」。
4. 不要偷懶：如果我要求「手刻」某個方法，就不可以直接呼叫 sklearn 的
   對應實作來充數。sklearn 只能當對照組。

## 圖檔
所有圖存到 `figs/`，用 `savefig()`，不要用 `plt.show()`（無視窗環境無效）。

## 筆記
數學筆記寫在 `notes/` 底下的 .md 檔，數學式用 $...$ 與 $$...$$。

## 不要做的事
- 不要 git commit 或 git push，除非我明講。
- 不要刪除 `figs/` 或 `notes/` 裡既有的檔案。

uv sync

綠燈自測

下面三個測試全部通過，你就準備好了。

測試一：Python 環境

uv run python -c "import numpy, scipy, sklearn, matplotlib, networkx; print('環境 OK')"

應該印出 環境 OK。

測試二：agent 會回話

opencode run "用一句話說明什麼是主成分分析"

應該得到一段繁體中文的回答。

測試三：agent 真的會動手（最重要的一關）

opencode run --auto "建立一個 hello.py，內容是印出 1 到 10 的平方，然後執行它"

! permission requested: edit (hello.py); auto-rejecting
✗ Write hello.py failed
Error: The user rejected permission to use this specific tool call.

看到 Read、Write、$ 這三種箭頭，代表 agent 的三種能力 （讀檔、寫檔、執行指令）都正常。而且它讀了 AGENTS.md、用了 uv run， 表示你的專案規則有生效。

• opencode --version 印出版本號
• uv --version 印出版本號
• 專案資料夾裡有 pyproject.toml、opencode.json、AGENTS.md
• uv sync 跑完，沒有紅色錯誤
• 測試一印出「環境 OK」
• 測試二得到繁體中文回答
• 測試三真的產生了 hello.py 並印出平方數

卡住了？

最後提醒