Soot DocsSoot được thiết kế thế nàoMarkdown ↗

01 / Surfaces

Surfaces: nơi con người gặp Soot

Founder, thành viên và khách gặp Soot ở đâu, mỗi người dùng credential gì, và khi nào Soot chờ người quyết.

Một Soot không có giao diện riêng. Con người gặp nó qua các surface: Nest, CLI, coding agent (MCP), SDK và widget trên website, và ứng dụng chat như Telegram. Tài liệu này nói ai dùng surface nào, họ thấy gì, project nối vào Soot ra sao, và vì sao mọi surface cùng một bộ luật. Nếu mỗi nơi tự quyết "ai được trả lời, ai được duyệt, khách thấy gì" thì quyền sẽ lệch nhau và lộ dữ liệu mỗi khi thêm một kênh.

Mô hình: một kernel, một bộ luật

Runtime là kernel. Nó giữ hội thoại, run, mục cần người (attention item), danh tính và mọi quyết định "ai được làm gì". Surface chỉ làm ba việc: hiển thị phần runtime chiếu ra cho nơi đó, nhận lại điều người ta quyết, và gắn đúng người nói vào từng tin. Nó không suy quyền từ loại kênh và không giữ bản luật thứ hai.

Văn bản mẫu · không phải lệnh
 Chủ (operator)        Thành viên          Khách / visitor
 Nest · CLI · MCP     Nest · chat DM       website · app · chat công khai
        │                   │                       │
        ▼                   ▼                       ▼
 ┌─ surface: chiếu dữ liệu, gắn người nói, nhận quyết định ─────────┐
 │  Runtime (kernel)                                                │
 │  hội thoại theo nơi · run · attention item · Authorize()         │
 │  Soot tự quyết trong quyền của nó; hỏi người khi cần             │
 └──────────────────────────────────────────────────────────────────┘

Hai hệ quả. Một câu hỏi hay một yêu cầu duyệt ở Nest và ở Telegram là cùng một mục với một câu trả lời; ai trả lời trước thì nơi kia thấy "đã xử lý". Và Soot làm được gì không phụ thuộc người đang nói với nó: công cụ, credential và danh sách việc chờ duyệt nằm trong cấu hình Soot và host. Surface chỉ quyết ai được nói và ai được xử lý một mục.

Ba nhóm người và credential

NhómLà aiCredentialThấy gì
Chủ (owner)Founder, người vận hành runtimeOperator token (Nest, CLI); token sop_ có phạm vi (coding agent)Mọi thứ trên runtime, mọi yêu cầu duyệt
Thành viênNhân viên của chủMember key (fixed-user key có conversations:read_team, control...), hoặc tài khoản chat đã liên kếtPhần việc của họ; approver còn duyệt được việc của các Soot được cấp
KháchNgười dùng cuối của projectTrusted backend (conversation_clients) đặt X-Soot-User; hoặc spk_ cộng visitor svs_ cho người ẩn danhChỉ hội thoại của chính họ, ở dạng chiếu công khai

Mỗi loại credential đi qua một cổng riêng và không loại nào thay được loại khác: operator token không xuống browser; key của người dùng gọi route quản trị nhận 403 (chỉ token chưa từng phát hành hoặc đã thu hồi nhận 401); backend tự xác thực user rồi đặt identity, browser không gửi được header đó. spk_ là khóa công khai chọn một client policy, không chứng minh ai là nhân viên hay khách hàng, nên quyền riêng tư theo tổ chức phải đi qua backend của project. Hội thoại thuộc tenant/user/Soot; biết ID không cấp quyền sang tenant khác. Operator connection cố ý không mở sang tenant của khách: chủ nhận mục cần xử lý, không đọc transcript của khách. Đổi cấu hình client chỉ có hiệu lực sau khi activate (saved chưa phải active). Khai báo client: soot schema deployment; cấp và thu hồi key: soot auth --help.

Ghép máy: muốn mở Nest của một người trên máy khác, chủ phát một mã dùng một lần; Nest ở máy kia đổi mã đó (/pair, /v1/pair/claim) lấy device key riêng, thu hồi được từng máy. Bước đổi mã không cần credential nào khác vì mã chính là credential. Chỉ chủ mới phát mã và thu hồi máy.

Hai loại kênh

Kênh của chủ và đội (Nest, CLI, MCP, Telegram hoặc Discord nội bộ) nói với Lead hoặc Đầu mối, nhận mục cần chủ và trả lời tại chỗ theo vai trò. Kênh của khách (widget, app channel, bot công khai) nói với Soot phục vụ khách do đội gắn vào; mục cần chủ không bao giờ mang nội dung tới đó, khách chỉ thấy một con trỏ không có chữ của host.

Mỗi bot chat thuộc một đội (hoặc một Soot) và chỉ trả lời bằng đội đó. Bot nội bộ chỉ cho người đã liên kết nói chuyện. Bot ngoài cho khách nói, có giới hạn, và không bao giờ là kênh chat của chủ. Lead nằm trong Nest và không thuộc đội nào, nên không bao giờ là đích của bot; binding của đội chưa có Đầu mối thì chưa có đích. Gắn bot không đổi công cụ, pack, credential hay vai trò của Soot. Xem places-settings.

Các surface

SurfaceDành choCổng vàoMã nguồn
NestChủ, thành viênOperator connection, hoặc kết nối thành viêndesktop/
CLI sootChủ, script, CIOperator tokencmd/soot/
Coding agent (MCP)Chủ, qua Claude Code, Codex, CursorToken sop_, stdio hoặc /v1/mcpcmd/soot/mcp.go, internal/feature/mcpserver/
Chat channel (Telegram, Discord)Chủ, thành viên, khách/v1/channel/* với credential sca_internal/core/channel/, adapter ở Soot Forge packs/chat-channels
App channel / bridgeBackend của project, khách trong app: hội thoại riêng của từng người và nơi chung nhiều người cùng đọc (channel-adapter §12)SDK @tofound/soot-sdkcontrib/sdk/typescript/src/{channel,livechat}
Browser SDK và widgetVisitor trên website/public/v1/* với spk_, svs_contrib/sdk/typescript/src/browser.ts, internal/core/transport/httpapi/public*.go

Một nền tảng mới là một adapter nói contract channel-adapter, không phải thay đổi trong core (extensions.md).

Nhiều kênh, một bộ luật

Thêm một kênh chat không thêm luật nào, vì mỗi tầng chỉ biết một thứ:

  1. Adapter biết giao thức của nền tảng. Nó dịch mỗi tin về một hình chung: ai nói, ở nơi nào, có gọi Soot không, trả lời tin nào. Nó không quyết ai được nói, không tự trả lời và không viết chữ cho người dùng.
  2. Runtime biết danh tính và nơi chốn. Nó ghép binding, nơi và người nói thành một hội thoại, quyết ai được nói, và nhớ câu trả lời của hội thoại đó đi đâu (Ai nói, ở đâu, ai xử lý).
  3. Soot chỉ thấy một hội thoại có tin nhắn. Nó trả lời, không chọn kênh hay nơi gửi.
  4. Đường ra đi ngược lại: runtime gắn địa chỉ vào câu trả lời, adapter vẽ nó theo kiểu của nền tảng (trích tin, con trỏ sang DM).

Quyền đi theo người sở hữu hội thoại (chủ, thành viên, khách), không theo loại kênh, nên kênh mới dùng lại bộ luật chung.

Mã của adapter chạy ở ba nơi có mức tin cậy khác nhau, nên có ba dạng đóng gói. Ba dạng này không gộp được thành một gói; thứ chúng dùng chung là luật của host và từ vựng của hai hợp đồng.

Mã chạy ở đâuDạngDùng choHợp đồng, credential
Cạnh runtime, do deployment khởi độngTiến trình soot-channel trong pack chat-channels (Soot Forge)Nền tảng có API bot công khai: Telegram, Discord. Người vận hành chỉ nhập token của bot, không viết mãchannel-adapter, sca_
Trong backend của projectThư viện: SDK channelChat của chính app. Chỉ backend của project biết user đã đăng nhập là ai, và tin nằm trong kho của nóchannel-adapter (binding từ xa), khóa binding
Trong trình duyệt của kháchWidget, hoặc SDK browserKhách vãng lai trên website. Trình duyệt không giữ được bí mật của serverlive-chat-attention, /public/v1/*, spk_ và svs_

SDK live-chat là dạng thứ hai cho project đã có hệ thống chat riêng: một cầu inbox/outbox bền chạy trong backend của project.

Đường đi đầu tiên

Có ba cách bắt đầu, cùng một runtime. Cá nhân: cài app Nest (đóng gói sẵn runtime) hoặc soot nest, chọn nhà cung cấp AI, chat với Lead. Terminal: soot spawn <dir> tạo workspace và khởi động runtime, soot check --show xem quyền đã resolve, soot run "..." giao việc. Project: soot spawn --project <dir> ghi scaffold (Soot support, quyền công cụ rỗng, AI scripted offline, docs/soot.md cho coding agent), soot serve, thêm kết nối trong Nest, backend gọi bằng SDK.

Model scripted chỉ thử hành vi local; chỉ một lượt chat thật mới chứng minh AI sẵn sàng (/readyz và soot check thì không). Provider key nằm ở vault của host, Soot không đọc .env.

Nest

Nest là app Tauri (có bản chạy trong trình duyệt) viết bằng React. Mọi quyết định nằm ở runtime; Nest chiếu và gửi lại.

Cấu trúc trang

Rail là danh sách module trong một registry (desktop/src/app/registry/areas.ts). Rail, bảng lệnh ⌘K, link nest:// và phím tắt đều sinh từ cùng mảng đó, nên thêm một trang là thêm một dòng (nest-registry).

Khu vựcViệc của nó
Hộp việcCửa sổ rộng (trên 760 px) luôn có danh sách việc bên trái (một nav): dòng Lead ở đầu, rồi ba nhóm cố định Cần bạn, Đang chạy, Xong, và nút soạn việc mới. Mỗi việc một dòng và một luồng; mở một dòng là mở luồng của nó ở bên phải, kể cả thẻ của một việc cần bạn. Chưa chọn dòng nào thì bên phải là trang bắt đầu: ô "Gửi tới" (mặc định Lead, @đội hay @Soot gửi thẳng), thẻ "Bước tiếp" cho việc cần bạn đầu tiên, số đếm bấm được, mảnh home; các dòng không vẽ hai lần. Cửa sổ hẹp (760 px trở xuống) hiện một khung một lúc, có nút quay lại, và trang bắt đầu tự mang ba nhóm. Mỗi nhóm có giới hạn rồi "Xem cả N …"; việc không ai sẽ chạy là một dòng Cần bạn "N việc chưa có ai làm"; nhóm còn khung xám tới khi mọi lượt đọc đã trả lời. Mảnh home nằm dưới ba nhóm; mảnh project.tab là tab của sản phẩm đang xem (Mục tiêu và việc, Hỗ trợ…). Thay Tổng quan và Cuộc trò chuyện; từ cũ và link cũ mở Hộp việc
Đội Soot, Sản phẩmSoot, nhóm, quyền, kênh của từng đội; gom Soot theo sản phẩm
Dữ liệuBảng, trí nhớ, tệp, tài liệu (data.md)
Kết quảViệc đã xong, chi phí, tự cải thiện (evolution.md)
Trang của SootTrang do pack khai báo, runtime phục vụ (pieces)
Cài đặtChung, Máy chủ, Thành viên (kể cả ai được duyệt), Màn hình, Kho khóa (mọi khóa ở một chỗ, runtime.md), AI, Quyền (công cụ nào chờ duyệt), Kênh (bot chat, website, SDK và kết nối coding agent), Trình duyệt, Kiến thức công khai, Cập nhật

Nest hiện dần: nhóm "Quản lý" chỉ hiện khi có từ hai Soot, có trang dữ liệu, hoặc chủ tự bật; ẩn thì vẫn mở được bằng ⌘K và link. Người mới thấy một đường chính: nói với Lead. Việc quen thuộc của người quản lý không rành kỹ thuật: xem đội làm gì và duyệt ở Hộp việc › Cần bạn; giao việc trong ô "Gửi tới" của Hộp việc, tạo Soot, lập đội, đặt lịch bằng cách nhắn Lead; nhận khách khó qua mục chuyển giao; đặt chat lên website ở Đội Soot › đội › Kênh.

Lead và Đầu mối

Lead là trợ lý của chủ trong Nest. Mỗi server có một Lead, tên luôn là "Lead", nằm ngoài mọi đội. Chỉ Lead có công cụ quản trị (nest-lead_manage): tạo Soot, lập đội, đặt lịch, đổi model, cấp quyền dữ liệu. Các thao tác đi qua cùng management action với màn hình thủ công, cùng revision và receipt, nên không có bản cấu hình thứ hai trong prompt. Việc đảo ngược được thì Lead làm ngay rồi báo kèm link; xóa, nới quyền, tăng ngân sách vào Cần bạn. Lead không bao giờ nói là "đã tạo" khi chưa có receipt. Màn hình thủ công vẫn còn, là đường dự phòng.

Mỗi đội có một Đầu mối: Soot nhận việc đầu tiên của đội, chạy lịch của đội và trả lời bot của đội. Đầu mối không có quyền quản trị. Xem agents.md và contracts/lead.md.

Nhiều runtime trong một Nest

Một Nest nối được nhiều runtime (máy local, server, VM). Soot, đội và việc được gộp từ mọi kết nối; khái niệm máy chủ chỉ lộ khi hai Soot trùng tên hoặc khi chủ chọn lọc theo máy ở thanh cửa sổ. Mỗi kết nối có operator key và định danh riêng.

Nest tin từng server riêng (Cài đặt › Máy chủ). GET /v1/runtime trả runtime_id bền; đổi định danh thì Nest hủy phiên và xóa cache. Khóa operator ở bản đóng gói nằm trong kho riêng của app, ở bản trình duyệt chỉ nằm trong bộ nhớ trang, không bao giờ ở URL hay web storage. Browser gọi thẳng server cần HTTPS và browser_origins (soot schema deployment). Các lần đọc một màn hình hỏi cùng lúc đi chung một GET /v1/reads (mỗi lần đọc vẫn qua đúng quyền của khóa; work-reads §4), nên kết nối lần đầu tới máy chủ ở xa tốn hai lượt đi về: GET /v1/runtime rồi một lô.

Ngắt kết nối chỉ ngừng quan sát, không dừng hay hoàn tác việc trên server.

Thêm server bằng link ghép máy (Cài đặt › Máy chủ › Thêm máy chủ). Cài đặt › Thành viên gộp người theo mã người trên mọi server: một người, nhiều thiết bị, quyền theo đội và Soot; quản trị không phải chọn server. Một đội đổi server bằng ⋯ › Chuyển sang máy chủ khác… (runtime.md).

Cài đặt: lưu, áp dụng, thử

Cấu hình thuộc server đang chạy runtime, không thuộc Nest. Nest hiển thị bản đã lưu và bản đang chạy riêng vì chúng có thể khác nhau.

Bốn bước: kiểm tra (chỉ hỏi host, không lưu, không gọi model), lưu (một revision), áp dụng (host chuyển sang revision đó, có thể chờ việc đang chạy; chỉ nhãn "Đã áp dụng" xác nhận bản đang chạy) và thử (một lượt chat thật, chỉ khi bản lưu trùng bản chạy).

Ghi đi kèm expected_revision và request_id ổn định. Xung đột (409) giữ bản nháp để người đọc bản mới rồi gửi lại. Mất phản hồi thì Nest hỏi lại receipt bằng GET, không POST lặp. Bí mật chỉ nhập ở Nest hoặc CLI trên host, không dán vào chat vì hội thoại được ghi lại; khi cần, Lead mở một form an toàn.

Cần bạn: nơi con người quyết định

Sự chú ý của chủ là thứ khan hiếm nhất. Soot tự quyết mọi thứ trong thẩm quyền và chỉ tìm người khi: host chọn chặn hành động (tiền, đăng công khai, xóa); chỉ người làm được (đăng nhập, cắm credential); ngoài thẩm quyền (giá, ngày, lời hứa); hoặc không ai biết điều gì đã xảy ra (lệnh ghi hết thời gian chờ). "Muốn có ý kiến thứ hai" không phải lý do. Mỗi lần hỏi là một quyết định: một dòng nói cần gì và vì sao, các lựa chọn với đề xuất của Soot, việc Soot đã làm, và link tới đối tượng. Người chọn một nút hoặc viết một dòng.

Nest có một nơi duy nhất cho việc này, Hộp việc › Cần bạn, một danh sách và một số đếm dùng chung cho huy hiệu rail và tiêu đề cửa sổ. Mỗi mục mang một trong ba động từ: Trả lời (câu hỏi, chuyển giao), Duyệt (quyết định, cấp quyền, mục mà một need view vẽ như màn hình hay bố cục Soot đề xuất), Sửa (lỗi).

Mục (kind)Do đâu mà cóNgười trả lời bằng
Duyệt (approval)Soot gọi công cụ mà host chặnDuyệt và chạy, hoặc Từ chối kèm lý do Soot đọc được
Quyết định (decision)report_blocker có lựa chọnChọn nút, hoặc một dòng chỉ dẫn. if_unanswered cho phép im lặng thì chọn mặc định, chỉ với lựa chọn đảo ngược được
Chuyển giao (handoff)report_blocker không có lựa chọnTự làm rồi bấm "Đã xử lý"
Cấp quyền (grant)Soot xin kho dữ liệu hoặc pack chưa cóCấp và tiếp tục, hoặc Từ chối
Cấp dòng hợp đồng (need, id contract-grant:<id>, action contract.grant)Soot đội A bị từ chối khi đọc bảng hay ghi hàng đợi của đội B, rồi xin bằng report_blocker grant kind contract; mọi lượt xin cùng một dòng là một mụcCấp và tiếp tục, hoặc Từ chối kèm lý do (POST /v1/settings/contract-grants/{id}, soot teams grant / decline; workspace.md)
Câu hỏi (question)ask trong hội thoại tương tácTrả lời
Kết quả chưa rõ (unknown_outcome)Lệnh ghi không biết thành hay bạiKiểm tra đích rồi chốt
Lỗi, lịch, credential thiếu, ngân sách token, đề xuất cải thiện, kiến thức lỗi thờiRuntime phát hiệnSửa nguyên nhân, chạy lại, bỏ qua, áp dụng hoặc bỏ
Thẻ (card)Một bước của lịch trả raise, không tốn modelChọn nút. id chỉ lập một lần, nên công cụ nêu lại thẻ mỗi nhịp mà không giữ trạng thái
Việc gửi đi vòng lại (mail_loop)Việc gửi qua lại giữa các đội quá mail.max_hops lầnBắt đầu tay, hoặc bỏ
Việc gửi chưa chạy (mail_held)Việc gửi tới một đội chưa có Đầu mối (team_needs_coordinator), đội chỉ nhận việc đã duyệt (inbox_hold), bắt đầu lỗi (start_failed), hoặc đội gửi đã đủ số việc trong ngày (mail_rate_limited); payload.code nói lý doChọn Đầu mối ngay trong Hộp việc (việc tự chạy), hoặc bắt đầu tay
Việc chưa tới (mail_undelivered)Việc gửi cho đội ở runtime khác chưa tới sau 30 phút, hoặc bị từ chối hẳn (mail_not_granted, mail_unsupported, …)Thử lại ngay (POST /v1/workspace/mail/sync), hoặc sửa quyền ở runtime kia
Việc chờ bạn (task_waiting, id task-waiting:<task>)Một việc đang mở bị chặn, chờ duyệt, là việc của chính bạn, hoặc lần chạy cuối dừng chờ người hay lỗi (payload.state: waiting, blocked, failed); không có mục này khi một mục khác đã đứng cho cùng việc (need của luồng việc, thẻ thư, thẻ lịch)Mở luồng việc rồi trả lời, gỡ chặn hoặc chạy lại
Việc chưa có ai làm (tasks_unowned, id tasks-unowned[:<sản phẩm>])Việc todo chưa giao ai hoặc chưa ai bấm Bắt đầu, không phải thư; một mục cho mỗi sản phẩm, payload.count và tối đa 20 việc mẫu (payload.sample), phần còn lại đọc qua danh sách việcGiao cho một đội hay Soot rồi bắt đầu, hoặc đóng lại
Khách chờ bạn trả lời (live_chat_handoff, id live-chat:<phiên>:<lượt>)Soot chuyển cho người một chat của khách (app, website, kênh) bằng report_blocker không có lựa chọn; mục ở tenant của khách (live-chat-attention)Trả lời khách ngay trong Cần bạn rồi trả lại Soot (POST /v1/sessions/{id}/member-messages, /control; chỉ chủ, không qua token có phạm vi)

Mỗi mục có severity (error, warning, info); nhóm theo mức này chứ không theo kind. Việc do eval tạo ra bị loại khỏi danh sách trừ khi hỏi rõ. Danh sách: soot attention list; trả lời: soot attention answer. Số đếm là số mục runtime trả về: Nest không tự đếm thêm từ danh sách việc, nên huy hiệu rail, tiêu đề cửa sổ, đầu nhóm Cần bạn và soot attention list nói cùng một số.

Gửi việc cho một đội (workspace.md) là soot tasks send --to team:<id> "…" hoặc POST /v1/workspace/tasks với deliver: true; Lead gửi bằng send trong công cụ workspace. Việc có trường mail (đường đi, trạng thái, reply); các mốc là sự kiện mail_delivered, mail_held, mail_reply. Trong Nest, ô "Gửi tới" của Hộp việc gửi việc theo đúng đường này; gửi cho Lead vẫn là một cuộc trò chuyện (mail_for_lead). Việc gửi đi là một dòng ở Đang chạy, kể cả khi chưa tới nơi; một mã từ chối thành một câu và một nút sửa (retarget, reconnect, coordinator, budget, start, sync).

Pack khai báo mặc định "approval": "operator" cho một công cụ, an toàn cho host lạ. Host sở hữu quyết định thật qua grants.approvals trong deployment, ghi đè pack cả hai chiều; chỉ deployment của host mới nới được. Nest hiện mọi công cụ bị chặn trong Cài đặt › Quyền với 30 ngày quyết định, và gợi ý "Để Soot tự chạy" cho công cụ đã duyệt nhiều lần mà chưa từng bị từ chối: quyền tự chủ tăng theo điều chủ đã chứng tỏ chấp nhận. Thông báo hệ điều hành theo cùng danh sách: duyệt và kết quả chưa rõ báo ngay, mục khác báo một lần hoặc gộp.

Cùng các mục đó đến DM đã liên kết của chủ trong Telegram hoặc Discord, kèm nút cho lựa chọn trả lời tại chỗ; việc nút không giải quyết được thì có link về Nest.

Bộ luật chung cho mọi surface

Các luật này nằm trong code (internal/core/authz, internal/core/channel, internal/core/conversation/attention.go) và được contract kiểm bằng fixture.

LuậtNội dung
Một mục, một câu trả lờiGiải quyết ở đâu thì mọi nơi khác thấy đã xử lý
Hỏi ở nơi việc phát sinhChỉ question (và decision cho người hỏi đã liên kết) xuất hiện ở nơi chung
Danh sách đóngLoại mục khác chỉ đến nơi của chủ; loại mới mặc định cần quyền own
Chỉ người hỏi trả lờiNgười khác, kể cả chủ, nhận 403 not_asker
Con trỏ, không nội dungMục chỉ dành cho chủ gặp khách hoặc nơi chung chỉ để lại tối đa một dòng cố định
Riêng tưBí mật chỉ ở Nest. Nơi chung và live chat nhận bản chiếu công khai. Dữ liệu theo người được tra từ nơi hội thoại, không từ chữ trong tin
Chữ do ai viếtHost viết câu cho người dùng Nest và chat. Với khách, runtime chỉ gửi mã; client viết chữ
Soot là ranh giới quyềnCông cụ, phạm vi credential, cấu hình duyệt và grant quyết định run làm được gì, giống nhau ở mọi surface
Ai cũng được nóiLiên kết không phải cổng; lạm dụng xử lý bằng giới hạn và danh sách chặn

Ai nói, ở đâu, ai xử lý

Mỗi tin đến từ một người nói (speaker) có id ổn định, không lộ handle nền tảng. Hội thoại khóa theo nơi, không theo người: một DM, một nhóm hay thread, một thread của bridge, một phiên widget. Mọi người trong nơi đó thấy trả lời của Soot, nên transcript là chung và gắn tên người nói. Khi một run đang chạy, tin mới của cùng người nói được hấp thụ vào run đó (lái run); tin của người khác xếp thành run riêng. Câu hỏi mở thuộc về người hỏi: tin người khác không trả lời và không đóng nó. Luật này nằm ở internal/core/conversation/steer.go, nên chat host, bridge và widget cư xử như nhau.

Liên kết thay cho ghép cặp: ai trong nơi chung cũng nói chuyện được với Soot, không phải làm gì trước. Liên kết (mã dùng một lần từ Nest, gửi cho bot) chỉ nói "tài khoản chat này là người Nest kia", để DM của họ nhận mục của chủ và nút bấm mang đúng vai trò. Người chưa liên kết bị giới hạn theo người và theo pool của binding (pool 0 nghĩa là chỉ người đã liên kết nói được), cộng danh sách chặn; vượt giới hạn thì nhận một thông báo rồi im lặng. Số mặc định: internal/core/channel/places.go, internal/core/config/channels.go.

Một hàm Authorize(principal, place, action, item) (internal/core/authz/authorize.go) trả lời cho mọi surface, chạy lại ở mỗi lần bấm và không cache vai trò.

Vai tròAiPhạm vi
ownerOperator connection, tài khoản chat của chủTất cả
approverThành viên chủ cấp (mọi Soot hoặc vài Soot)handle và approve cho Soot được cấp
memberKhóa có read_team và controlhandle việc chuyển giao của các Soot trong khóa
anyoneNgười chưa liên kết, khách, visitorChỉ nói, và trả lời câu hỏi của chính mình

handle là việc của đội (chuyển giao, quyết định, tiếp quản live chat). approve là duyệt công cụ và chốt kết quả chưa rõ. own là mọi thứ còn lại của chủ: cấp quyền, ngân sách, kênh, vai trò. Quyền thành viên không rộng hơn khóa của họ.

NơiMục chỉ dành cho chủ
NestCó, theo vai trò
DM của người đã liên kếtCó, nếu vai trò xử lý được
owner_chat (nhóm chat chủ chỉ định bằng mã /owner)Có, thay DM của chủ. Ai cũng thấy tiêu đề và lựa chọn; bí mật và diff ở Nest. Ai không đủ quyền bấm nhận 403 not_authorized
Nơi chung, live chatKhông bao giờ; tối đa một con trỏ

Project nối vào Soot (SDK)

Project dùng @tofound/soot-sdk (contrib/sdk/typescript/; cách dùng ở README của nó) để nối vào cùng runtime. Các đường chính:

MuốnDùngCredential
Backend chat với Soot thay cho user đã đăng nhậpConversation API, SDK clientconversation_clients
Hệ thống ngoài báo việc (alert, webhook)POST /v1/events qua adapter của bạnoperator token, chỉ ở backend
Giao một việc nền, nhận kết quả có cấu trúc/v1/jobs, SDK jobs, soot jobsoperator hoặc sop_ scope jobs
Khách vãng lai chat trên websiteWidget hoặc SDK browserspk_ và svs_
Chat của chính app là giao diệnSDK channel hoặc live-chatkhóa binding
Tool của Soot gọi API của bạn, cần biết ai đang nóiPrincipal tokenJWKS của host

Các khái niệm cần nắm:

  • Run. Gửi tin tạo run queued, rồi running, rồi completed, failed hoặc stopped; waiting_input là Soot hỏi lại người dùng và đã dừng thực thi, câu trả lời là một message mới. Khi POST mất phản hồi, giữ conversation ID, request ID và run ID rồi đối soát bằng GET; gửi lại như một run mới sẽ bỏ qua trạng thái chưa rõ. Lỗi run có mã ổn định, không lộ lỗi thô của provider.
  • Event. (soot, source, subject) xác định hội thoại; id là khóa retry. Core không có receiver riêng cho từng vendor: adapter của bạn xác thực webhook rồi chuẩn hóa. Phản hồi 202 là đã nhận bền vững, chưa phải đã xong. Core không có case hay takeover cho event; việc đó thuộc pack. text tối đa 64 KiB UTF-8 và Soot đọc trọn; dài hơn bị từ chối 400 kèm giới hạn.
  • Job. Một lần chạy nền của Soot hoặc đội, có idempotency_key, kết quả JSON và callback ký JWS (xác minh bằng JWKS của host). Job chỉ là cổng vào; theo dõi nội bộ thuộc workspace.md. Hợp đồng: jobs. task, input và output_schema tới model trọn vẹn, ngay trong run (tối đa 60 KiB văn bản run); vượt thì bị từ chối invalid_job kèm giới hạn, không bị cắt.
  • Public web. Khách chat ngay trên website, không qua backend của bạn: spk_ cộng challenge đổi lấy phiên svs_ ngắn hạn. Vì khóa công khai, khách bị chặn bởi ngân sách và chính sách của client, và các Soot được lộ ra chỉ được dùng công cụ đọc. Widget (nguồn ở Soot Forge packs/live-chat/widget/, được runtime phục vụ ở /public/widget/*) giữ credential ngoài trang chủ trong iframe; adopter muốn UI riêng dùng SDK browser, cùng mô hình.
  • Kênh của app. SDK channel là adapter chế độ server của channel-adapter: host giữ gộp tin, lượt và owner, SDK không tự trả lời, và chỉ ack sau khi đã ghi vào store của bạn. SDK live-chat là cầu inbox/outbox bền: gửi lỗi thành uncertain, không bao giờ tự gửi lại.
  • Principal token. Một JWS ngắn hạn cho mỗi lần gọi tool, để API của bạn biết người trong hội thoại mà model không chọn hay thấy: principal-token.

Live chat và khách

Khách chỉ trả lời được câu hỏi của chính họ. Câu hỏi hiện thành thẻ có nút, hiện một lần, và đóng lại với kết quả đã chọn. Việc cần chủ (duyệt, chuyển giao, quyết định) không đến khách; khách nhận một con trỏ chỉ có mã (team, approval, not_ready, unavailable) và client tự viết chữ, hoặc không hiện gì nếu Soot đã tự trả lời. Runtime không viết chữ cho khách.

Các quyết định thiết kế đáng nhớ: đây là hợp đồng anh em của channel-adapter (cùng từ vựng mục, hai ranh giới tin cậy khác nhau, vì khách không phải người dùng Nest); quyền của người hỏi do runtime ép, không do client; và widget không có luật riêng, mọi trạng thái attention nằm trong SDK browser để đổi luật chỉ cần nâng runtime.

Khi cần người thật, thành viên có read_team và control thấy hội thoại live chat trong Nest, tiếp quản, trả lời công khai dưới tên mình, hoặc nhắn riêng cho Soot (khách không thấy). Trong lúc người giữ hội thoại, tin mới của khách vẫn được lưu và hiện cho thành viên, Soot không tự chạy.

Trạng thái hiện tại: runtime đã chiếu thẻ câu hỏi, kết quả và con trỏ (internal/core/conversation/attention.go, sự kiện attention.pointer, khả năng live-chat-attention-v1). Hợp đồng live-chat-attention và places-settings đã chuyển sang dự án soot-cs-engine (internal/test/guard/cs_allowlist.txt giữ bản sao ở đây cho tới khi gỡ); đừng sửa bản sao. Phần chăm sóc khách (console, chính sách chuyển giao) là extension, không thuộc core: extensions.md. Bridge cs/ cũ đã bị xóa; project production dùng app channel của SDK.

CLI và coding agent

soot là surface cho script, CI và người ưa terminal; mọi thao tác quản trị là cùng management action với Nest. soot --help liệt kê lệnh.

Chủ cũng điều khiển Soot từ Claude Code, Codex hay Cursor. soot mcp (stdio, máy local) hoặc <server>/v1/mcp (HTTP, server từ xa) sinh công cụ từ cùng registry hành động với CLI. Token sop_ có phạm vi (read, jobs, manage, data) tạo ở Cài đặt › Kênh › Kết nối coding agent hoặc soot tokens, chỉ hiện một lần, và là credential riêng (SOOT_MCP_TOKEN), không phải operator token. Con người vẫn giữ quyết định: duyệt, cấp quyền, nhả mục bị giữ và tạo hay thu hồi token không có trong MCP và bị từ chối với token có phạm vi (approval_needs_person). Coding agent của bạn không tự cho Soot support quyền sửa file hay chạy shell. Hợp đồng: mcp-operator.

Việc gửi đi qua các surface

Ai được giao việc cho đội tùy vào hội thoại thuộc về ai, không tùy loại kênh. Hội thoại nằm trong không gian của chủ (tenant operator và không phải live chat) thì Soot có công cụ task ghi được và có send. Đó là chat trong Nest, DM của chủ với bot đã ghép trên Telegram hay Discord, và chat của chủ qua coding agent. Run chỉ đọc không gửi được: eval, dry run và bản tin của Lead. Khách, thành viên và app nối bằng SDK không bao giờ gửi việc vào không gian của chủ. Cả ba chỗ đều đọc một hàm conversation.InOwnerWorkspace (internal/core/conversation/reach.go).

Việc Soot gửi từ chat của chủ là thư của Soot, không phải của người. Vì vậy mọi giới hạn vẫn áp: số bước trong một chuỗi, giới hạn mỗi ngày, đội đang giữ hộp nhận.

Câu trả lời quay về nơi người đã hỏi. Khi Soot gửi hoặc bắt đầu việc từ một chat ngoài Nest (DM đã ghép), lúc đội trả lời xong Soot được chạy thêm một lượt trong chat đó để báo cho người, như khi Soot tự chọn wait. Mỗi câu trả lời chỉ đánh thức một lần. Không áp dụng khi Soot đang làm cho đồng đội, và câu trả lời needs_person không đánh thức. Hàm: conversation.AnswersOutsideNest.

Trong lúc chờ, người ở surface nào cũng không bị mù. Khi việc dừng vì chờ một người ở đâu đó trong chuỗi (kể cả ở máy chủ khác), khi quá due, hay khi chạy lâu (báo lại thưa dần), host đưa một dòng cho phía người gửi. Chat của khách qua intake nhận một lượt để nói với khách việc đang ở đâu. Soot đã gửi với wait nhận một lượt trong thread đó. Nest đọc trên nhật ký việc (mail_progress). Dòng đó chỉ nói việc đang ở đâu, không lộ đội hay người. Luật chung ở work-mail D6.

Coding agent có cùng một cửa gửi việc: công cụ MCP task_send (cùng phạm vi với task_start) gọi đúng hàm gửi mà POST /v1/workspace/tasks với deliver: true và soot tasks send gọi. Người gửi ghi là mcp:<token>.

Với khóa thành viên, Hộp việc là các hội thoại do chính khóa đó mở (GET /v1/workspace/inbox). Thành viên không thấy task, không thấy việc của chủ, của thành viên khác hay của khách, kể cả qua GET /v1/reads. "Gửi tới" chỉ có những Soot và đội mà khóa được nói chuyện, và gửi là mở một hội thoại với Soot đó. Mọi route /v1/workspace/* khác vẫn chỉ của chủ; thành viên gọi POST /v1/workspace/tasks nhận 403.

Từ khách tới việc là do người làm. Thẻ chuyển giao của khách ở Cần bạn có nút "Giao cho đội". Nút mở ô giao việc của Hộp việc, điền sẵn câu Soot tóm tắt điều nó cần (Soot không tóm tắt thì là một tiêu đề chung) và một dòng nói việc đến từ chat của khách, kèm nơi khách viết. Nest không chép tin nhắn của khách, kể cả câu đầu tiên của họ, và không mang mã hội thoại. Chủ đọc, chọn "Gửi tới" rồi tự gửi; thẻ vẫn ở Cần bạn.

Chủ cũng có thể mở sẵn một cửa cho một loại báo cáo: intake (contract intake). Trong deployment, chủ khai các trường của báo cáo, Soot nào được nhận và đội nào trên runtime này xử lý. Soot đó có thêm công cụ file_report. Đây không phải send: khách vẫn không gửi được việc, chỉ đi qua cửa chủ đã mở, tới đúng đội chủ đã chọn. Thư tới đội chỉ có nội dung: các trường, lời tóm tắt của Soot, câu người báo viết nếu có, và số người đã báo. Runtime giữ chỗ trả lời từng người báo cùng với việc, không đặt vào thư. Đội nhận không bao giờ biết báo cáo đến từ đâu: không mã hội thoại, không tên, không kênh. Báo trùng chủ đề thì gộp vào việc đang mở. Khi việc xong, lỗi hay bị chặn, runtime đánh thức Soot đã nhận báo cáo trong từng hội thoại có người báo, mỗi hội thoại một lượt. Ai được trả lời ở đâu xem Ai nói, ở đâu, ai xử lý; phần việc của runtime, adapter và pack xem Ranh giới: ai sở hữu gì.

Khi thêm một surface mới:

  1. Hội thoại của nó thuộc tenant nào? Chỉ chủ là operator; người khác ở tenant của họ.
  2. Không thêm luật theo Source.Kind: quyền gửi việc đọc InOwnerWorkspace, câu trả lời về chat đọc AnswersOutsideNest.
  3. Mọi cửa gửi việc gọi hàm gửi của engine (SendTask, StartTask), không viết đường gửi thứ hai.
  4. Thêm hàng cho surface đó vào TestOpSendOnlyInWorkspaceRuns, và một test đọc với khóa không phải của chủ.

Ranh giới: ai sở hữu gì

Runtime (core) giữ quyền, danh tính, chọn nơi gửi và giới hạn. Adapter (Soot Forge, hoặc tự viết bằng SDK channel) giữ giao thức nền tảng, định dạng tin và dedup. Client (widget, SDK, app của project) viết chữ cho khách. Pack (extension) giữ hành vi chăm sóc khách và chính sách chuyển giao. Cấu hình host và Soot quyết công cụ nào chờ duyệt và credential nào chạm công cụ nào. Nest chỉ hiển thị, soạn nháp và giữ thay đổi chưa lưu.

Surface cố ý không làm: quyết định ai được trả lời; suy quyền từ loại kênh; giữ cấu hình thứ hai trong UI hay prompt; đưa bí mật qua chat; mở operator connection sang transcript của khách.

Chưa có

Adapter Messenger, Zalo, email. Lead chỉ ở Nest, không phải đích của bot. Duyệt bằng nút ở nơi chung cố ý không làm.

Nội dung được xem lại: 12.11.2026