# Role、Skill 與允許清單端點

Role、skill，以及 skill 與工具允許清單的端點。

## Role 與 Skill

| Method | 路徑 | 說明 |
|---|---|---|
| `GET` | `/v1/roles` | **local** — 列出存放於 `prompts/` 的 `.md` session prompt role（`name`、`size`、`updated_at`），放在 `roles` 下回傳，並為舊版 client 在 `rules` 下再附同一份清單 |
| `GET` | `/v1/role/*name` | **local** — 讀取單一 role |
| `POST` `PATCH` `DELETE` | `/v1/role` | **local** — 建立 / 更新（可選 `rename`）/ 刪除 role |
| `GET` | `/v1/skills` | **local** — 列出已安裝的 skill |
| `GET` | `/v1/skill/*name` | **local** — 讀取單一已安裝 skill：`name`、`description`、`path`、`source`、`content`、`deletable`，另加 `files` —— 該 skill 的 `scripts/`／`references/`／`assets/` 底下所有 UTF-8 檔案，以 `{path, content}` 依路徑排序回傳，跳過隱藏檔、超過 256 KiB 者略過（v1.0.2）|
| `DELETE` | `/v1/skill` | **local** — 移除單一已安裝 skill |

Rule 已於 v1.1.0 更名為 role。`/v1/rules`、`/v1/rule/*name` 與 `/v1/rule` 仍保留為 role handler 的別名，舊版 client 可繼續使用。

操作者筆記已於 v1.0.23 移除：`/v1/notes`、`/v1/note/*name` 與 `/v1/note`（原 `/v1/knowledge*`）皆不再存在。常駐指示請改放在 role 或 skill。

## 允許清單

| Method | 路徑 | 說明 |
|---|---|---|
| `GET` `POST` | `/v1/allowlist` | **local** — 兩份允許清單合成一個物件：`skill` 與 `tool`。`GET` 對 skill 區塊讀 `?scope=global\|project`（`project` 需帶 `?work_dir=`），對 tool 區塊以 `?prefix=` 縮限。`POST` 接受 `{skill: {name, scope?, work_dir?}}` 切換單一 skill，以及 / 或 `{tool: {prefix, entries}}` 只替換該 prefix 的自動核准條目（與 TUI `/mcp` → permission 同一支呼叫），其他規則保持不變；每個條目都必須以 `prefix` 開頭，`prefix*` 會收斂其餘條目。未帶到的區塊不動 |