Metadata-Version: 2.4
Name: suken-cite
Version: 0.1.19
Summary: Trả lời bằng tuyến truyện vẽ trên khung UI, mỗi ô có ảnh chụp nguồn khoanh đỏ kèm dòng dịch (web, email, PDF, Word, Excel, PowerPoint, CSV, ảnh) và thẻ giải thích code.
Author: suken
License-Expression: MIT
Keywords: citation,screenshot,highlight,annotation,llm,claude-code
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Environment :: Console
Classifier: Topic :: Text Processing
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
Dynamic: license-file

# suken-cite

Mỗi khẳng định đều kèm ảnh chụp nguồn của nó. `suken-cite` giúp một LLM agent (như Claude Code) trả
lời bằng **một tuyến truyện vẽ trên khung UI có sẵn**: trục thời gian hoặc chuỗi nhân quả, cùng các
khung so sánh, so số liệu, mâu thuẫn, trạng thái, chỗ hổng, phễu… thay cho đoạn văn. Người đọc nhận
**một link** và đi từng bước bằng ◀ ▶; ô nào cũng có 📷 mở ảnh chụp nguồn:

- **Trường hợp chung** (trang web — kể cả email, chat phải đăng nhập —, PDF, Word, Excel, PowerPoint,
  CSV, ảnh): agent mở nguồn trên Chrome, chụp màn hình và chỉ vùng cần trích; suken-cite **khoanh đỏ** vùng
  đó ngay trên ảnh, kèm một dòng dịch. File code, file chữ thì hiện như trình soạn thảo.
- **Giải thích code:** **thẻ giải thích** gom vị trí trong flow, class, hàm, thư viện, biến và giá trị
  thật lúc chạy, thể hiện bằng màu, icon và sơ đồ thay cho chữ. Một flow qua nhiều module cũng được kể
  thành tuyến truyện trên khung UI, mỗi bước một thẻ.

Agent chụp ảnh bằng chrome-devtools. Người đọc chỉ cần bấm link.

## Dùng thế nào

Cài gói, rồi bảo agent đọc hướng dẫn và làm theo:

```bash
pip install suken-cite
suken-cite usage        # hướng dẫn chung: tuyến truyện + trích dẫn khoanh đỏ
suken-cite usage code   # hướng dẫn giải thích code: 1 thẻ cho 1 đoạn code, tuyến truyện khung UI cho cả flow
```

Hai hướng dẫn viết cho LLM agent, cùng một khung: luật vàng, checklist, review. `suken-cite --help` chỉ
agent chọn đúng hướng dẫn. Agent tự cài reviewer, tự dựng trích dẫn, tự chụp ảnh, và chỉ giao kết quả
khi reviewer chấm **ĐẠT**.

## Các lệnh

| Lệnh | Làm gì |
| --- | --- |
| `suken-cite usage [code\|renderer]` | in hướng dẫn: chung / giải thích code / tự làm renderer cho loại file khác |
| `suken-cite install-agent` | cài 2 subagent reviewer vào `.claude/agents/`: `suken-story-review` (truyện chung) và `suken-code-review` (truyện giải thích code) |
| `suken-cite init --dir ./cites` | tạo thư mục dự án trích dẫn |
| `suken-cite serve --dir ./cites` | bật server để xem ảnh (mặc định cổng 8123) |
| `suken-cite snapshot <url> --id <id>` | cách cũ, giữ để tương thích: lưu bản sao trang web (`--tab` lưu đúng tab đang mở) |
| `suken-cite register --id <id> --file … --url …` | ghi nguồn gốc của file (SharePoint, email đính kèm…); từ chối file chữ chép từ trang web — trang web phải chụp màn hình |
| `suken-cite text --file … \| --doc …` | in chữ của nguồn (pdf, docx, xlsx, pptx) để đọc nhanh và tìm đúng trang trước khi chụp |
| `suken-cite skeleton --file … --lines …` | thẻ giải thích code: in khung JSON đã điền sẵn class, hàm kèm tham số, biến của các dòng code (Python); agent chỉ điền ý nghĩa và giá trị |
| `suken-cite add …` | thêm trích dẫn: ảnh chụp `--image` + `--box` (mọi nguồn trừ code), `--lines` (code, file chữ), hoặc thẻ code `--explain <json>` — thẻ code còn thiếu mục nào thì `add` từ chối và nói rõ thiếu gì |
| `suken-cite story --template timeline\|argument` | in khung truyện trống; điền xong thì `story --id … --json …` kiểm và lưu — còn thiếu trường hay chữ quá dài thì từ chối và nói rõ ô nào |
| `suken-cite urls` | in link trang cần chụp và link cho người đọc |
| `suken-cite check` | kiểm mọi trích dẫn, mọi truyện và báo ảnh còn thiếu |

Ví dụ một trích dẫn:

```bash
suken-cite init --dir ./cites
suken-cite serve --dir ./cites &
# agent mở nguồn trên Chrome, chụp màn hình vào ./cites/shots/price.png, rồi chỉ vùng cần khoanh:
suken-cite add --dir ./cites --id price --image ./cites/shots/price.png --box 120,340,860,372 \
  --quote "Pears 2.40/kg" --section "prices.pdf · trang 3" --vi "Lê giá 2,40 mỗi kg."
# link cho người đọc : http://127.0.0.1:8123/c.html?id=price
```

## Yêu cầu

- Python 3.9+ (không cần thư viện Python nào khác; phần chạy trên trình duyệt đã đóng gói sẵn).
- Chrome, và Claude Code có MCP server **chrome-devtools** để chụp ảnh.
- Nguồn phải đăng nhập (email, chat…): đăng nhập sẵn trên chính Chrome mà chrome-devtools điều khiển.
- Linux hoặc macOS.

## Giấy phép

MIT. Các thư viện trình duyệt đi kèm và giấy phép của chúng nằm trong `THIRD_PARTY_NOTICES.md`.
