Metadata-Version: 2.4
Name: suken-cite-guide
Version: 0.1.12
Summary: Giải thích có bằng chứng (ảnh nguồn khoanh đỏ kèm dòng dịch, tuyến truyện trên khung UI, thẻ giải thích code) và cầm tay chỉ việc trên trình duyệt; 5 chế độ bật bằng từ khoá qua hook Claude 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-guide

Giúp một LLM agent (như Claude Code) **giải thích có bằng chứng** và **cầm tay chỉ việc** cho người dùng.
Mỗi khẳng định kèm ảnh chụp nguồn khoanh đỏ đoạn trích và một dòng dịch; mỗi việc cần làm trên trình duyệt
thì agent vẽ vòng đỏ ngay trên màn hình để người dùng tự bấm. Gói có 10 chế độ, người dùng gõ từ khoá trong
chat để bật đúng chế độ cần:

| Từ khoá | Chế độ | Người đọc nhận |
| --- | --- | --- |
| `suken-Story` | cốt truyện giải thích | **một link** tuyến truyện vẽ trên khung UI (trục thời gian, chuỗi nhân quả, so sánh, so số liệu, mâu thuẫn, chỗ hổng…), đi từng bước bằng ◀ ▶, ô nào cũng có 📷 mở ảnh nguồn |
| `suken-Cite` | trích dẫn đơn lẻ | câu trả lời ngắn, mỗi ý kèm một link ảnh nguồn khoanh đỏ |
| `suken-CodeStory` | cốt truyện code | một flow qua nhiều module kể thành tuyến truyện, mỗi bước một thẻ giải thích code |
| `suken-Code` | thẻ code | một thẻ gom vị trí trong flow, class, hàm, thư viện, biến và giá trị thật lúc chạy, bằng màu, icon, sơ đồ |
| `suken-Guide` / `suken-non_Guide` | cầm tay chỉ việc | vòng đỏ, mũi tên, 📋 dán, ⏎, 🔗 vẽ trên chính tab của mình; tự bấm từng bước, bấm sai thì bị chặn và agent tự thức dậy dẫn lại. Hết kịch bản, bấm ⏺ rồi tự khám phá: các bước và ảnh màn hình được ghi lại, gửi kèm tin nhắn kế tiếp |
| `suken-Record` / `suken-non_Record` | ghi thao tác | gắn bộ ghi vào một tab (tự theo sang tab mới mở từ đó, đóng thì quay về); mỗi lần nhắn tin, agent nhận kèm các bước vừa làm để hỏi bất cứ lúc nào |
| `suken-Mark` | khoanh sẵn | agent mở tab rồi khoanh đỏ mọi chỗ cần xem bằng một lệnh (cả trong khung nhúng, dòng code, nút chỉ có icon); chỗ ngoài màn hình có mũi tên chỉ hướng cuộn |
| `suken-Doc1` | bôi cụm khó | sub-agent đóng vai người ngoài dự án tìm các cụm khó hiểu, agent bôi tím ngay trên tab |
| `suken-Doc2` | xếp loại cụm | cụm khó thành xanh lá (kiến thức IT) hoặc cam (ngữ cảnh dự án) |
| `suken-Doc3` | giải thích một cụm | kịch bản vòng đỏ kèm khung 💡 dẫn người dùng tới chỗ thấy tận mắt câu trả lời; đường đi do sub-agent tự tìm như người mới; kịch bản lồng nhau, tab Cây kịch bản để chuyển qua lại |

Nguồn có thể là trang web (kể cả email, chat phải đăng nhập), PDF, Word, Excel, PowerPoint, CSV, ảnh, file
code và file chữ (mở trong VS Code chạy trên trình duyệt).

## Dùng thế nào

Cài gói, rồi cài hook một lần trong thư mục mở Claude Code:

```bash
pip install suken-cite-guide
suken-cite-guide setup        # cài hook, 2 reviewer, code-server; kiểm chrome-devtools
```

Từ đó, gõ từ khoá kèm yêu cầu trong chat, ví dụ `suken-Story vì sao run B chậm hơn run A?`. Hook đưa
nguyên hướng dẫn của chế độ đó cho agent ngay trong lượt chat, agent không phải tự nhớ đọc. Riêng
`suken-Guide` giữ tới khi gõ `suken-non_Guide`: trong lúc bật, hook chặn agent tự bấm, gõ, mở, đóng tab
trên trình duyệt, chỉ người dùng tắt được.

Không dùng hook (agent khác Claude Code): bảo agent chạy `suken-cite-guide usage` để chọn chế độ và đọc
hướng dẫn. Mỗi hướng dẫn cùng một khung: luật vàng, checklist, review; agent chỉ giao kết quả khi reviewer
chấm **ĐẠT**.

## Các lệnh

| Lệnh | Làm gì |
| --- | --- |
| `suken-cite-guide setup [--remove]` | cài hook cho các từ khoá và hook đánh thức của suken-Guide (`.claude/settings.local.json`, giữ nguyên hook khác), 2 subagent reviewer (`.claude/agents/`), code-server (~220 MB vào cache); kiểm MCP chrome-devtools và cổng Chrome DevTools rồi báo thiếu gì. `--remove` gỡ hook và reviewer |
| `suken-cite-guide usage [story\|cite\|codestory\|code\|guide\|record\|mark\|doc1\|doc2\|doc3\|renderer]` | in hướng dẫn của một chế độ (không kèm: in danh sách chế độ) |
| `suken-cite-guide init --dir ./cites` | tạo thư mục dự án trích dẫn |
| `suken-cite-guide serve --dir ./cites` | bật server xem ảnh, xem file (mặc định cổng 8123); `render/pdf.html?file=…&page=` và `render/open.html?file=…` mở thẳng PDF, Word, Excel, PowerPoint, CSV |
| `suken-cite-guide text --file … \| --doc …` | in chữ của nguồn (pdf, docx, xlsx, pptx) để đọc nhanh trước khi chụp |
| `suken-cite-guide add …` | thêm trích dẫn: ảnh chụp `--image` + `--box`, hoặc thẻ code `--explain <json>` — thiếu mục nào thì từ chối và nói rõ |
| `suken-cite-guide skeleton --file … --lines …` | thẻ code: in khung JSON điền sẵn class, hàm, biến của các dòng code (Python) |
| `suken-cite-guide story --template timeline\|argument` | in khung truyện; điền xong thì `story --id … --json …` kiểm và lưu |
| `suken-cite-guide editor --folder …` | mở VS Code chạy trên trình duyệt (code-server); lần đầu tự tải ~220 MB vào cache |
| `suken-cite-guide guide template` | in khung kịch bản cầm tay chỉ việc |
| `suken-cite-guide guide run <kịch bản\|->` | kiểm kịch bản rồi chạy nền bộ vẽ vòng đỏ trên tab người dùng (thay lần chạy cũ của phiên); mỗi lần cần agent (xong, lạc, bấm sai, tunnel…) hook tự đánh thức agent kèm lý do, thứ bị bấm hay che đích và snapshot quanh chỗ lệch. `--foreground`: chạy ngay, in mỗi lần đánh thức một dòng JSON (dùng với Monitor khi không có hook) |
| `suken-cite-guide guide reattach [địa chỉ]` | gắn bộ điều khiển đang chạy vào kết nối Chrome mới (sau khi người dùng mở lại tunnel) |
| `suken-cite-guide mark <đoạn địa chỉ> '<danh sách chỗ khoanh>'` | khoanh sẵn những chỗ cần xem trên một tab đang mở, in một dòng: chỗ nào đã khoanh, chỗ nào cần cuộn, chỗ nào không thấy |
| `suken-cite-guide record start <đoạn địa chỉ>` / `record stop` | gắn bộ ghi thao tác vào một tab (hoặc chuyển sang tab đó) / tắt bộ ghi |
| `suken-cite-guide doc paint <đoạn địa chỉ> '<cụm và loại>'` | bôi màu các cụm chữ trên tab (tím: chưa xếp loại, xanh lá, cam) |
| `suken-cite-guide doc start\|push <kịch bản\|->` | chạy kịch bản Doc3 (push: lồng vào kịch bản đang chạy); tự bật bộ điều phối và tab Cây kịch bản. Kèm `doc status`, `go`, `restart`, `stop` |
| `suken-cite-guide register`, `snapshot`, `urls` | ghi nguồn gốc file; lưu bản sao trang web (cách cũ); in link |
| `suken-cite-guide check` | kiểm mọi trích dẫn và mọi truyện |

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

```bash
suken-cite-guide init --dir ./cites
suken-cite-guide 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-guide 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**; cầm tay chỉ việc dùng chung cổng DevTools đó
  (mặc định `http://127.0.0.1:9222`).
- Hook và từ khoá: Claude Code.
- 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`.
