# Skill API

`api.skill` 管理本地知识包，包括导入、文件编辑、作用域和导出。知识包与脚本的编写方法见 [Skill](../Agent/Skill.md)。

## 入口

```js
await (window.__TAURITAVERN__?.ready ?? window.__TAURITAVERN_MAIN_READY__);
const skill = window.__TAURITAVERN__.api.skill;
const installed = await skill.list();
```

## 管理与文件

| 方法 | 行为 |
| --- | --- |
| `list({ scope? }?)` | 返回 Skill 列表；`all` 表示所有用户安装的 Skill，内置包须用 `builtin` 筛选 |
| `listFiles({ scope?, name })` | 列出包内文件 |
| `readFile({ scope?, name, path, startLine?, lineCount? })` | 读取 UTF-8 文件，支持 1-based 行范围 |
| `writeFile({ scope?, name, path, content, expectedSha256? })` | 写入文件，可按读取到的 SHA 检查并发修改 |
| `move({ name, fromScope, toScope, conflictStrategy? })` | 移动到另一个作用域 |
| `export({ scope?, name })` | 返回 `{ fileName, contentBase64, sha256 }`，内容为 ZIP |
| `delete({ scope?, name })` | 删除安装索引与包目录 |

作用域有 `global`、`preset`、`profile`、`character` 和 `builtin`，省略作用域时按全局处理。`builtin` 随应用分发，只提供列表与读取，不支持安装、写入、移动、改作用域、删除或导出；通过 `list({ scope: { kind: 'builtin' } })` 单独列出。完整结构见 [src/types.d.ts](../../src/types.d.ts) 的 `TauriTavernSkillScope`。

文件路径相对于 Skill 包。`readFile` 返回原文与原始 SHA，不展开宏；省略范围时读取全文，较长内容返回行预览和 `nextStartLine`。`writeFile` 的 SHA 不匹配时返回错误。

## 选择导入来源

| 方法 | 返回内容 |
| --- | --- |
| `acquireImport()` | 同步取得本页导入准入，返回 `release(): Promise<void>`；占用时抛出 `skill.import_busy` |
| `pickImportArchive()` | 单个归档输入，取消时为 `null` |
| `pickImportArchives()` | 选择一个或多个归档来源，取消时为 `null` |
| `isDirectoryImportAvailable()` | 当前宿主能否选择目录来源（目前仅桌面） |
| `pickImportDirectories()` | 选择一个或多个目录来源，取消时为 `null`；不可用时抛错 |
| `discoverImports({ input })` | 递归展开目录或归档中的 Skill；其他输入返回单个候选 |
| `downloadImport({ url })` | 下载 HTTPS raw `SKILL.md`，返回单文件导入输入 |
| `discardPickedImport(input?)` | 释放指定来源的临时资源；无参数时释放整批来源 |

导入输入有三种形式：

```ts
type SkillImportInput =
  | { kind: 'directory'; path: string; source?: unknown }
  | { kind: 'archiveFile'; path: string; skillRoot?: string; source?: unknown }
  | {
      kind: 'inlineFiles';
      files: Array<{
        path: string;
        content: string;
        encoding?: 'utf8' | 'utf-8' | 'base64';
        mediaType?: string;
        sizeBytes?: number;
        sha256?: string;
      }>;
      source?: unknown;
    };
```

`skillRoot` 是归档内的 Skill 根路径；发现过程遇到 `SKILL.md` 后不再深入该目录。`source` 记录来源关系，角色卡和预设用它关联嵌入的 Skill。ZIP 和历史 `.ttskill` 归档都可导入，导出统一使用 ZIP。

## 预览与安装

选取来源后调用 `discoverImports({ input })`，对返回的候选逐项调用 `previewImport({ input, targetScope? })` 查看内容和同名冲突，再调用 `installImport({ input, targetScope?, conflictStrategy? })`。

| `conflict.kind` | 含义 | 安装方式 |
| --- | --- | --- |
| `new` | 同名包不存在 | 安装 |
| `same` | 同名且内容相同 | 合并来源，保留已有内容 |
| `different` | 同名但内容不同 | 指定 `skip` 或 `replace` |

安装结果的 `action` 为 `installed`、`replaced`、`already_installed` 或 `skipped`。多个来源逐项预览和安装，每项单独提交并返回结果；已完成的安装会保留。

助手与 Skill Manager 在选取或下载来源前取得导入准入，并持有至预览、安装结束。整批完成或取消后，须等待在途请求结束，再 await `release()`；它清理临时来源后释放准入，可重复调用。单项安装不会释放来源。

Agent 通过只读 `skills/<name>/` 视图和 `workspace.shell` 使用安装包，见 [Skill](../Agent/Skill.md)。