Metadata-Version: 2.4
Name: suken-cite
Version: 0.1.7
Summary: Trả lời bằng tuyến truyện có trích dẫn: ảnh chụp nguồn khoanh đỏ kèm dòng dịch (web, PDF, Word, CSV) 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 ngắn**, trong đó mỗi bước có một link 📷 dẫn tới ảnh chụp nguồn:

- **Trường hợp chung** (trang web, PDF, Word `.docx`, CSV, file chữ): nguồn được hiện giống bản gốc,
  **đoạn trích khoanh đỏ**, bên dưới là một dòng dịch.
- **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ữ. Nhiều hàm gọi nhau thì đi từng bước
  bằng ◀ ▶.

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 dòng code, tuyến truyện + thẻ 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>` | lưu bản sao trang web, dùng Chrome đã đăng nhập |
| `suken-cite register --id <id> --file … --url …` | ghi nguồn gốc của file (SharePoint, email đính kèm…) |
| `suken-cite text --file … \| --doc …` | in chữ của nguồn để chép đoạn trích nguyên văn |
| `suken-cite add …` | thêm trích dẫn: `--lines` / `--rows` / `--page` + `--quote` / `--doc`, hoặc thẻ code `--explain <json>` (`--explain-of <id> --step N` cho từng bước) |
| `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 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 &
suken-cite add --dir ./cites --id price --file prices.csv --rows 3 --vi "Lê giá 2,40 mỗi kg."
# trang cần chụp     : http://127.0.0.1:8123/render/csv.html?cite=price
# lưu ảnh vào        : ./cites/shots/price.png
# 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.
- Trang web: Chrome đó phải mở cổng DevTools; SingleFile CLI được tự tải ở lần dùng đầu.
- 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`.
