Ran — kiến trúc

Ran là agent chạy trên máy của bạn: nó nghe tài khoản Zalo cá nhân và trả lời những người, những group mà bạn chọn, mỗi nơi theo một cách riêng.

Ran không thuộc nhóm năm site Cloudflare và không đi qua api.conan1.com. Nó là công cụ cá nhân chạy local, giữ phiên Zalo và API key trên máy bạn. Mã nguồn nằm ở ran/.

zca-js listener ──message──▶ agent.onMessage
                                │ ghi lịch sử  data/threads/<id>.json
                                │ lọc: target? enabled? paused? bạn vừa tự nhắn? mode?
                                ▼
                       chờ replyDelaySec (gom tin)
                                ▼
          system = persona chung + persona riêng + bối cảnh + hồ sơ tự học
          messages = historyLimit tin gần nhất (người kia = user, bạn = assistant)
                                ▼
                         llm.complete()  ──▶  "<SKIP>"  → im lặng
                                ▼
               mode=draft → nháp chờ duyệt  ·  còn lại → sendMessage

Target

Mỗi cuộc trò chuyện 1-1 hoặc group mà Ran theo dõi là một target, có "model" riêng của nó.

Thuộc tính	Ghi chú
threadId, type	Id Zalo; user hoặc group
enabled	Tắt thì Ran vẫn ghi lịch sử nhưng không trả lời
mode	auto: trả lời mọi tin. mention: chỉ khi bạn bị @ hoặc tin chứa keywords. draft: soạn nháp để bạn duyệt. Group mặc định là mention
providerId, model, temperature	Để trống thì dùng giá trị mặc định
persona	Cách trả lời ở nơi này, được thêm vào sau persona chung
context	Bạn tự ghi: người này là ai, group này để làm gì

Hồ sơ tự học

Thuộc tính	Ghi chú
Khi nào	Cứ mỗi profileEvery tin mới, hoặc khi bạn bấm "Học lại từ lịch sử"
Nội dung	Quan hệ, cách xưng hô, giọng điệu, chủ đề, việc đang dở. Với group: mục đích, thành viên chính, quy ước
Cách làm	Model đọc hồ sơ cũ cùng tối đa 150 tin gần nhất rồi viết lại hồ sơ
Sửa tay	Được: hồ sơ là văn bản trong giao diện

An toàn hành vi

Cơ chế	Ghi chú
Bạn tự nhắn thì Ran nhường	Thấy tin isSelf không phải do Ran gửi, Ran ngừng trả lời ở thread đó takeoverMinutes phút
Gom tin	Đợi replyDelaySec giây sau tin cuối rồi mới trả lời một lần
Im lặng	Model trả <SKIP> khi tin không cần trả lời
Tạm dừng toàn bộ	Công tắc trên giao diện (paused)
Chỉ local	Server chỉ lắng nghe 127.0.0.1, giao diện không có mật khẩu

Chưa làm

Danh sách đầy đủ những việc Ran chưa làm nằm ở ran/BACKLOG.md và hiện trong giao diện Ran ở tab Chưa làm. Những thiếu sót chính: chưa từng chạy với Zalo và Claude thật, chỉ đọc và gửi chữ, không bù tin bị lỡ, không nhập lịch sử cũ, chỉ một tài khoản Zalo, chưa giới hạn tốc độ gửi, chưa có tool, API key và phiên Zalo chưa được mã hoá.

Dữ liệu

File	Nội dung
data/config.json	Provider (có API key), mặc định, target
data/credentials.json	Phiên Zalo. Ai có file này là đăng nhập được Zalo của bạn
data/threads/<id>.json	Tối đa 500 tin gần nhất và hồ sơ tự học

REST API của giao diện và schema đầy đủ có trong /zalo/index.json.