OpenCode 入門實作課

# 用 winget 安裝 Node.js LTS
winget install OpenJS.NodeJS.LTS

# 裝完務必關掉終端機再重開，PATH 才會生效

brew install node

# 或者只裝 Node 24
brew install node@24

# 1. 安裝 fnm
winget install Schniz.fnm        # Windows
brew install fnm                  # macOS

# 2. 讓「以後開的每個終端機」都會自動載入 fnm（只做一次）
#    PowerShell：建立 profile，再把啟動指令寫進去
if (-not (Test-Path $profile)) { New-Item $profile -Force }
Add-Content $profile 'fnm env --use-on-cd --shell powershell | Out-String | Invoke-Expression'

#    bash / zsh：把下面這行加進 ~/.zshrc 或 ~/.bashrc
#    eval "$(fnm env --use-on-cd --shell zsh)"

# 3. 重開終端機，安裝並啟用 Node 24 LTS
fnm use --install-if-missing 24
node -v

node -v
npm -v
npm config get prefix

v22.20.0
10.9.3
C:\Users\你的帳號\AppData\Roaming\npm

npm install -g @opencode/cli

curl -fsSL https://opencode.ai/v2/install | bash

# macOS
brew install anomalyco/tap/opencode-v2

# Windows 沒有套件管理器支援時，下載獨立執行檔：
# https://opencode.ai/update/api/latest/cli/opencode/opencode-windows-x64.zip
# 解壓後把 opencode.exe 放到 PATH 內的資料夾（例如 %LOCALAPPDATA%\opencode）

opencode --version
opencode debug paths

mkdir my-agent-lab
cd my-agent-lab
opencode

# 在輸入框打斜線就會出現指令清單
/connect

# 選你的供應商（OpenCode Console、Anthropic、OpenAI…）完成登入
# 想不起來有哪些指令？直接打「/」看完整清單

opencode service status     # 看服務活著沒
opencode service restart    # 卡住就先重啟
opencode api get /api/info  # 真的打得通 API 嗎
opencode --standalone       # 用私有 server 開，隔離問題

cd my-agent-lab
opencode run "用三句話解釋什麼是 prompt cache"

幫我看 @hello.js，指出可以改進的地方，先不要改檔案

opencode service status
opencode api get /api/info

{
  "$schema": "https://opencode.ai/config.json",
  "skills": [
    "./team-skills",
    "~/shared/opencode-skills"
  ]
}

---
name: Git Release
description: 準備 release notes、版號升級與 GitHub release
---

## 流程

1. 讀 `references/release-policy.md`。
2. 整理上一個 tag 之後合併的變更。
3. 先提出建議版號，使用者同意後才動檔案。
4. 使用者核可版號後才執行 `scripts/changelog.ts`。

{
  "permissions": [
    { "action": "skill", "resource": "*", "effect": "allow" },
    { "action": "skill", "resource": "internal-*", "effect": "deny" }
  ]
}

# 專案內（跟同學共用）
mkdir -p .opencode/skills/dice-roll/scripts

# 或全域（自己每個專案都能用）
# Windows PowerShell
mkdir "$env:USERPROFILE\.config\opencode\skills\dice-roll\scripts"
# macOS / Linux
mkdir -p ~/.config/opencode/skills/dice-roll/scripts

---
name: dice-roll
description: |
  擲骰子：用系統級隨機源擲出 XdY±Z 形式的骰子，回報每顆骰子的點數、加總與範圍。
  觸發時機：使用者說「擲骰」「骰一下」「丟個 d20」「roll 3d6」「幫我隨機決定」，
  或出現 d4/d6/d8/d10/d12/d20/d100、骰子、dice、roll 字樣的場合。
  不要觸發：寫程式需要的亂數／UUID、統計模擬、樂透或賭博程式開發、資料抽樣。
---

# 擲骰子

## 一句話原則

**數字只能來自腳本，你不能自己生成。** 你的工作是解析使用者要什麼骰子、
執行腳本、把結果講清楚。

## 怎麼跑

```bash
python "<skill-dir>/scripts/roll.py" 3d6+2
python "<skill-dir>/scripts/roll.py" d20 --pretty
```

- `<skill-dir>` 就是這個 SKILL.md 所在的資料夾。
- 一次要多組獨立結果時用 `--times N`，不要呼叫腳本 N 次。
- 輸出是 JSON：`dice[].rolls` 是每顆骰子點數、`total` 是最終值、`min`/`max` 是理論範圍。

## 使用者沒講清楚時

| 使用者說 | 怎麼處理 |
| --- | --- |
| 「骰一下」 | 用 1d6，並說明「用 d6，要換別顆跟我說」 |
| 「骰個數字決定」 | 用 1d6 或 1d100，把點數對應到什麼講出來 |
| 「幫我檢定」 | 追問是哪個系統的哪顆骰（D&D 是 d20，CoC 是 d100），別猜 |

## 輸出格式

先給數據，再給一句描述：

```
🎲 3d6+2 → **12**
`3, 3, 4` +2
```

- 一定要列出**每一顆**骰子的點數，不能只給總和。
- 修正值跟骰子分開列，別把 +2 混進骰子點數裡。

## 不可以做的事

- **不要重擲**：結果不理想是結果的一部分。
- **不要挑結果**：不能骰完看到 3 就假裝沒看到。
- **不要微調**：不能把 12 寫成 13 讓它「剛好過關」。
- **腳本失敗就直說**，不要改用自行生成的數字充數。

#!/usr/bin/env python3
"""擲骰子：XdY±Z，用 secrets 取無偏隨機數。預設輸出 JSON，--pretty 給人看。"""
import argparse, json, re, secrets

TERM = re.compile(r"([+-]?)(?:(\d*)d(\d+)|(\d+))")

def roll(expr):
    e = re.sub(r"\s+", "", expr).lower()
    dice, mod, pos = [], 0, 0
    for m in TERM.finditer(e):
        if m.start() != pos:                       # 中間有看不懂的字元
            raise ValueError("cannot parse: " + e[pos:m.start()])
        pos = m.end()
        sign = -1 if m.group(1) == "-" else 1
        if m.group(3):                             # 骰子項，例如 3d6
            n = int(m.group(2) or 1)
            sides = int(m.group(3))
            if sides < 2:
                raise ValueError("dice needs at least 2 sides")
            rolls = [secrets.randbelow(sides) + 1 for _ in range(n)]
            dice.append({"count": n, "sides": sides, "sign": sign,
                         "rolls": rolls, "subtotal": sum(rolls) * sign})
        else:                                      # 修正值，例如 +2
            mod += sign * int(m.group(4))
    if pos != len(e):
        raise ValueError("cannot parse: " + e[pos:])
    total = sum(d["subtotal"] for d in dice) + mod
    low = sum((d["count"] if d["sign"] > 0 else -d["count"] * d["sides"]) for d in dice) + mod
    high = sum((d["count"] * d["sides"] if d["sign"] > 0 else -d["count"]) for d in dice) + mod
    return {"expression": e, "dice": dice, "modifier": mod,
            "total": total, "min": low, "max": high}

def pretty(r):
    lines = ["ROLL " + r["expression"]]
    for d in r["dice"]:
        sign = "-" if d["sign"] < 0 else ""
        faces = ", ".join(str(x) for x in d["rolls"])
        lines.append("  %s%dd%d -> %s = %d" % (sign, d["count"], d["sides"], faces, d["subtotal"]))
    if r["modifier"]:
        lines.append("  modifier %+d" % r["modifier"])
    lines.append("  total %d  (range %d..%d)" % (r["total"], r["min"], r["max"]))
    return "\n".join(lines)

if __name__ == "__main__":
    p = argparse.ArgumentParser(description="roll XdY+Z dice")
    p.add_argument("expression", help="e.g. 3d6+2, d20, 2d6+1d8-1")
    p.add_argument("--times", type=int, default=1, help="repeat N times (default 1)")
    p.add_argument("--pretty", action="store_true", help="human-readable output")
    a = p.parse_args()
    try:
        results = [roll(a.expression) for _ in range(a.times)]
    except ValueError as exc:
        raise SystemExit("error: %s" % exc)
    if a.pretty:
        print("\n\n".join(pretty(r) for r in results))
    elif a.times == 1:
        print(json.dumps(results[0], ensure_ascii=False))
    else:
        print(json.dumps(results, ensure_ascii=False))

python .opencode/skills/dice-roll/scripts/roll.py 3d6+2
# {"expression": "3d6+2", "dice": [{"count": 3, "sides": 6, "sign": 1,
#  "rolls": [4, 2, 6], "subtotal": 12}], "modifier": 2, "total": 14}

python .opencode/skills/dice-roll/scripts/roll.py 2d6+1d8-1 --times 3

幫我骰 3d6+2
# 或手動指定，確認它真的載入
@dice-roll 骰個 d20

🎲 3d6+2 → 14
`4, 2, 6` +2

命中率 = cache.read ÷ (cache.read + input + cache.write)

{
  "id": "ses_ea8e8727affeopFLqDCKlY4QTa",
  "title": "設定排程查詢台中天氣並於1分鐘後通知",
  "model": { "id": "deepseek-v4.1-flash-free", "providerID": "opencode" },
  "tokens": {
    "input": 76101,
    "output": 5586,
    "reasoning": 8800,
    "cache": { "read": 578816, "write": 0 }
  },
  "location": { "directory": "C:\\Users\\dpes8" }
}

mkdir -p .opencode/skills/cache-stats/scripts

---
name: cache-stats
description: 查詢 OpenCode 的 LLM prompt cache 命中率與 token 用量。當使用者問
  「快取命中率多少」「查快取」「cache hit rate」「這個對話省了多少 token」
  「哪個 session 快取效率差」，都用這個 skill 跑腳本拿真實數字，不要憑印象估算。
---

# 查快取命中率

## 一句話原則

**數字只能來自腳本。** 你的工作是把數據講清楚，不是心算或憑印象給一個「大概九成」。

## 怎麼跑

```bash
python "<skill-dir>/scripts/cache_stats.py"
```

- 這支腳本只接受這一個用法，不要自己發明參數。
- 想看更多工作階段、指定 session、輸出 JSON，屬於進階練習（見課程最後的挑戰）。

## 數字怎麼解讀

- 命中率 = cache read ÷ (cache read + input + cache write)
- `cache write = 0` 是正常的：這個 provider 走隱式快取，不另外回報寫入量
- 單一請求通常很高（98–99%）；整場被拉低幾乎都是一次性內容造成的：
  剛貼的圖片、大量 log、整份檔案、`openapi.json` 這種大 dump
- 命中率 < 80% 時可以補一句可能原因，**不要編造成本數字**

## 回覆格式

先給整體命中率，需要時再附表格：

```
**整體命中率 88.4%**（cache read 578,816 / prompt 654,917 tokens）
```

- 百分比取一位小數，token 加千分位
- 只有一個工作階段時不要硬做表格，一行講完就好

## 出錯時

照實說，不要改用猜的數字：

- 找不到 CLI → 確認 `opencode` 在 PATH，或設定 `OPENCODE_BIN`
- `opencode api` 逾時 → 背景服務可能卡住，建議 `opencode service restart`
- 沒有任何 session → 直接說目前沒有資料

#!/usr/bin/env python3
"""列出各工作階段的 prompt cache 命中率。"""
import json, shutil, subprocess, sys

def cli():
    """Windows 上 opencode 常是 .ps1 / .cmd，Python 直接呼叫會找不到。"""
    exe = shutil.which("opencode") or "opencode"
    low = exe.lower()
    if low.endswith(".ps1"):
        return ["powershell", "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", exe]
    if low.endswith((".cmd", ".bat")):
        return ["cmd", "/c", exe]
    return [exe]

def api_get(path):
    out = subprocess.run(cli() + ["api", "get", path], capture_output=True)
    if out.returncode != 0:
        msg = out.stderr.decode("utf-8", "replace") or out.stdout.decode("utf-8", "replace")
        sys.exit("opencode api failed:\n" + msg[:300] + "\ntry: opencode service restart")
    return json.loads(out.stdout.decode("utf-8-sig"))

def nums(s):
    t = s.get("tokens") or {}
    c = t.get("cache") or {}
    return int(t.get("input") or 0), int(c.get("read") or 0), int(c.get("write") or 0)

def pct(r):
    return "—" if r is None else "%.1f%%" % (r * 100)

sessions = api_get("/api/session").get("data") or []
if not sessions:
    sys.exit("目前沒有任何工作階段。")

sessions.sort(key=lambda s: (s.get("time") or {}).get("updated") or 0, reverse=True)

print("| 工作階段 | 模型 | 命中率 | cache read | 未命中 input |")
print("|---|---|---:|---:|---:|")
tr = ti = tw = 0
for s in sessions[:10]:
    i, r, w = nums(s)
    tr += r
    ti += i
    tw += w
    total = i + r + w
    model = (s.get("model") or {}).get("id") or "—"
    print("| %s | %s | %s | %s | %s |" % (
        s.get("title") or "(untitled)", model, pct(r / total if total else None),
        format(r, ","), format(i, ",")))

total = tr + ti + tw
print("\n**整體命中率 %s**（cache read %s / prompt %s tokens）" % (
    pct(tr / total if total else None), format(tr, ","), format(total, ",")))

python .opencode/skills/cache-stats/scripts/cache_stats.py

# Windows 若中文變亂碼，加上 UTF-8 環境變數再跑一次：
# $env:PYTHONIOENCODING='utf-8'; python .opencode/skills/cache-stats/scripts/cache_stats.py

| 工作階段 | 模型 | 命中率 | cache read | 未命中 input |
|---|---|---:|---:|---:|
| 設定排程查詢台中天氣並於1分鐘後通知 | deepseek-v4.1-flash-free | 88.4% | 578,816 | 76,101 |
| Greeting | deepseek-v4.1-flash-free | 65.5% | 32,256 | 16,971 |

**整體命中率 86.9%**（cache read 611,072 / prompt 703,978 tokens）

這個對話的快取命中率多少？