# 核心概念

HakoRun 以「路徑」識別函式、以時間戳區分版本，並提供已儲存與即時兩種執行方式。

## 函式路徑

- 每個函式以上傳時的 `path` 字串識別（例：`math/add`），呼叫時對應 `/run/<path>`。
- `path` 含 `..` 時上傳被拒（HTTP 400）。
- 儲存 key 取 `path` 的 MD5，不直接使用原字串，見 [儲存後端](/zh/storage)。
- 同一路徑重新上傳時，語言以最後一次上傳為準。

## 版本

| 行為 | 說明 |
|------|------|
| 版本號 | 上傳當下的 Unix 秒數，`/upload` 回應的 `version` |
| 預設執行 | `/run/<path>` 不帶 `version` 時執行最新版本 |
| 釘選版本 | `/run/<path>?version=<timestamp>`；版本不存在回 404 |
| 非整數 `version` | 視為未指定，執行最新版本 |
| 同秒上傳 | 同一路徑一秒內上傳兩次會得到相同版本號，後者覆蓋前者的程式碼 |

## 已儲存執行與即時執行

| 模式 | 端點 | 程式碼來源 | 語言檢查 |
|------|------|------------|----------|
| 已儲存執行 | `POST /run/*path` | 儲存後端（body 的 `code`／`language` 會被覆蓋） | 上傳時檢查 |
| 即時執行 | `POST /run-now` | 請求 body，不寫入儲存 | 每次請求檢查；`code` 不可為空白 |

兩種模式取得程式碼後走同一條執行路徑：

```mermaid
graph LR
    Body[getRunBody 限制 CODE_MAX_SIZE] --> Run[run]
    Run -->|stream=false| Once[runScript]
    Run -->|stream=true| SSE[runScriptWithSSE]
    Once --> Cmd[sandbox.SandboxCommand]
    SSE --> Cmd
    Cmd --> Wrapper[wrapper 讀 stdin]
```

## 執行生命週期

- 每次請求都啟動新的沙箱子行程，執行完即結束，不共用狀態。
- 截止時間為 `TIMEOUT_SCRIPT` 加 5 秒；逾時即終止行程。
- 非串流模式在行程結束後一次回傳；串流模式邊執行邊推送，細節見 [回應與 SSE](/zh/responses)。

## 相關頁面

- [腳本執行環境](/zh/script-runtime)
- [儲存後端](/zh/storage)
- [資源上限](/zh/resource-limits)