# 划词侠 — AI Text Actions for MioIsland

Quick AI actions on any clipboard or selected text. Translate,
summarize, rewrite tone, or draft an email reply — all powered by
DeepSeek with streaming output for instant feedback.

## Features

- **One-shot actions** — 翻译(中/英/日) / 总结 / 改语气(正式/口语/友好/严谨) / 邮件回复.
- **Streaming output** — typewriter effect via Server-Sent Events.
  Long replies start showing within ~600ms instead of after the
  full completion lands.
- **Two text sources** — clipboard (works without permissions) or
  selected text via NSAccessibility (requires the user to grant
  Accessibility permission). Falls back gracefully with a banner
  explaining the System Settings → Privacy step.
- **History** — last 20 actions persisted in UserDefaults; tap to
  re-copy the result without re-running the model.
- **Five-state UI** — idle, input, loading (cancellable), result,
  missing-config. Each transition is animated.

## Configuration

Drop your DeepSeek API key into
`~/.config/codeisland/clipper-config.json`:

```json
{
  "deepseek_api_key": "sk-...",
  "default_translate_target": "zh"
}
```

Get a key at https://platform.deepseek.com/ — DeepSeek's pricing is
roughly **¥0.001/1k tokens for input, ¥0.002/1k for output** (~1/100
of GPT-4), so a typical 划词侠 session costs less than a fraction of
a cent.

Without the file, the panel shows a friendly missing-config state
with the file path one click away on the clipboard.

## Requirements

- macOS 15.0+
- MioIsland v2.2.0+
- DeepSeek API key (for actual AI calls; UI works without it)
- Optional: Accessibility permission (for selected-text source)

## Building from source

```bash
./build.sh           # produce build/clipper.bundle + build/clipper.zip
./build.sh install   # build + copy to ~/.config/codeisland/plugins/
```

Restart MioIsland (Cmd+Q + reopen) to load the new build.

## Structure

```
Sources/
├── MioPlugin.swift              # protocol (verbatim from host)
├── ClipperPlugin.swift          # principal class
├── ui/
│   ├── ExpandedView.swift       # 380×520 panel, state machine
│   ├── ActionGrid.swift         # 2×2 action buttons + sub-options
│   ├── SourcePreview.swift      # truncated input preview
│   ├── ResultView.swift         # scrollable streaming output
│   ├── PermissionBanner.swift   # AX permission hint
│   └── Theme.swift              # design tokens
├── data/
│   ├── DeepSeekClient.swift     # actor + URLSession + SSE streaming
│   ├── TextSource.swift         # clipboard / selection providers
│   └── ClipperConfig.swift      # config loader
└── engine/
    ├── ClipperStore.swift       # @MainActor state machine + history
    ├── HistoryStore.swift       # UserDefaults, last 20 actions
    └── ClipperDebugLog.swift    # /tmp/clipper-plugin.log
```

## License

MIT — see [LICENSE](LICENSE).