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

07 / Công ty và mục tiêu

Làm một màn hình cho Nest

Thêm một màn hình vào Nest mà không phát hành lại Nest: Soot tự viết, hoặc pack mang tới; người vận hành quyết gì; giới hạn và an toàn.

Nest là một super app: mọi màn hình trong nó là một mảnh (piece) đặt vào một chỗ (slot). Ngoài các mảnh Nest dựng sẵn, có hai cách đưa thêm màn hình vào mà không phải phát hành lại Nest: một Soot hay một đội tự viết màn hình của mình, hoặc một pack mang màn hình tới cùng tool của nó. Trang này dẫn từng bước cho cả hai, và cho người vận hành biết mình có quyền gì với các màn hình đó.

Bạn làBạn muốnĐọc
Một Soot, hay Đầu mối của một độiMột màn hình để người làm việc cùng dùng dữ liệu, công cụ của mình và hỏi mìnhĐường 1
Người viết packMột màn hình dùng lại được ở nhiều nơi, có tool riêngĐường 2
Người vận hành NestĐặt, xếp, quay lại, gỡ màn hìnhNgười vận hành quyết gì

Chọn đường

Soot hay đội tự viếtPack
Ai viếtChính Soot: ghi file ở scratch rồi storage pushNgười viết pack
Nằm ở đâuui/<id>/ trong file của Soot hay độiinterface.pieces trong pack.json
Đọc dữ liệuTruy vấn có tên trên việc, bảng, file, việc cần người, kết quả, trí nhớ của chính chủ, hoặc một công cụ đọc chủ tự viếtMột tool đọc của pack, trả về gì cũng được
Làm việcGọi công cụ hay ghi bảng của chủ ngay, không qua model; hoặc hỏi Soot chủ và nhận câu trả lờiMột tool ghi của pack
Gọi dịch vụ ngoàiCông cụ tự viết: khai một request HTTPS, khóa do người nhập trong NestTool của pack, chạy chương trình riêng
Lên NestLần đầu hỏi người một lần (màn hình và công cụ trong một thẻ), các bản sau tự lênSoot chọn pack là có
Phát hànhKhôngPack, qua Forge hoặc thư mục pack của bạn

Chọn tự viết khi màn hình cần thứ Soot đã đọc được, cộng tối đa vài lời gọi tới một dịch vụ ngoài: đây là đường rẻ nhất, một Soot làm xong trong một lượt chạy. Chọn pack khi cần chương trình chạy trên máy chủ (logic không gói được trong một request), hoặc muốn nhiều workspace dùng chung.

Hai đường dùng chung mọi thứ còn lại: cùng các chỗ đặt, cùng bộ kit, cùng khung sandbox, cùng cách Nest giữ cho màn hình nhẹ.

Chỗ (slot)Hiện ở đâuTự viếtPack
homeMột phần của Hộp việccócó
railMột khu riêng trên thanh bêncócó
project.tabMột tab của dự án đang chọn (cần tab {id, label})cócó
data.tabMột tab trong Dữ liệucócó
settingsMột mục Cài đặtkhôngcó

Đường 1: Soot hay đội tự viết

_[0.19.0]_ Công cụ tự viết, hành động có tên, ask và kit mức 2 (soot.run, soot.ask, soot.asks) có trong runtime và Nest từ 0.19.0. Nest 0.18.0 chỉ có truy vấn và soot.action.

Một màn hình tự viết gồm hai nửa, cả hai là file Soot ghi ở scratch của nó rồi đẩy bằng storage push vào level của chính nó (soot:<id>; của đội thì team:<id>, chỉ Đầu mối đẩy):

  • Nửa sau là công cụ: tools/<id>/tool.json khai một request HTTPS tới một host có tên. Nó là khai báo, không phải code: không có gì Soot viết chạy trong runtime. Host gửi request, chèn khóa ngay trước khi gửi, rồi xoá khóa khỏi câu trả lời.
  • Nửa trước là mảnh: ui/<id>/ với index.html, script, và piece.json ghi sau cùng. Mọi logic của màn hình nằm trong JavaScript của nó, chạy trong khung sandbox của Nest.

Màn hình không có quyền riêng. Nó đọc qua các truy vấn có tên, làm việc qua các hành động có tên, và hỏi Soot chủ qua ask, đúng những gì piece.json khai và người đã duyệt. Mọi thứ chạy bằng quyền của chủ.

Ví dụ: màn hình dịch

Người nhắn Soot writer: "Làm cho tôi một màn hình dịch". Soot đề xuất một dịch vụ dịch và nói nó cần một khóa API mà người sẽ nhập trên thẻ duyệt trong Nest, không gửi trong chat. Rồi Soot ghi năm thứ theo thứ tự này:

Văn bản mẫu · không phải lệnh
data: create_table glossary   bảng thuật ngữ mà màn hình đọc và ghi
tools/translate/tool.json     công cụ: một request tới dịch vụ dịch
ui/translate/index.html       màn hình, link _kit/piece.css và _kit/piece.js
ui/translate/app.js           soot.run("translate"), soot.view("terms"), soot.ask(...)
ui/translate/piece.json       khai báo, ghi sau cùng: đây là lần lưu

Dịch vụ trong ví dụ ở api.example.com là giả định; thay bằng dịch vụ bạn dùng thật thì đổi url, header, body và output.pick theo tài liệu của nó. TestTranslateGuideExample chạy đúng các file dưới đây với một API giả.

Công cụ

tools/translate/tool.json:

Mẫu JSON · không phải lệnh
{
  "id": "translate",
  "label": {"vi": "Dịch văn bản", "en": "Translate text"},
  "description": "Gửi đoạn chữ và ngôn ngữ đích tới dịch vụ dịch ở api.example.com, nhận về bản dịch.",
  "mode": "read",
  "input": {
    "type": "object",
    "required": ["text", "target"],
    "properties": {
      "text": {"type": "string", "minLength": 1, "maxLength": 5000, "description": "The text to translate."},
      "target": {"type": "string", "enum": ["EN", "VI", "JA"], "description": "The language to translate into."}
    }
  },
  "run": {"http": {
    "method": "POST",
    "url": "https://api.example.com/v2/translate",
    "headers": {"Authorization": "Bearer {{cred:TRANSLATE_KEY}}"},
    "body": {"text": ["{{input.text}}"], "target_lang": "{{input.target}}"},
    "timeout": "20s"
  }},
  "output": {"pick": "/translations/0"},
  "needs": {
    "hosts": ["api.example.com"],
    "credentials": {
      "TRANSLATE_KEY": {
        "title": {"vi": "Khóa dịch vụ dịch", "en": "Translation service key"},
        "description": "Tạo khóa ở trang tài khoản của dịch vụ dịch, mục Khóa API.",
        "url": "https://example.com/account/keys"
      }
    }
  }
}

  • description và label hiện trên thẻ duyệt cho người đọc, và là mô tả model đọc khi Soot tự gọi công cụ: viết bằng ngôn ngữ của người, nói gửi gì tới đâu. Mỗi chữ nằm trên một dòng, không có ký tự điều khiển hay ký tự đổi hướng chữ (lưu sẽ bị từ chối).
  • mode là read khi request không đổi gì ở dịch vụ (dịch chỉ trả bản dịch), write khi nó tạo, sửa, xoá hay gửi thứ gì đi. read chỉ đi với GET và POST; PUT, PATCH, DELETE luôn là write (lưu read với chúng bị từ chối method_needs_write). Header X-HTTP-Method-Override, X-Method-Override và X-HTTP-Method bị từ chối ở mọi công cụ. Với POST, read là lời Soot cam kết, nên thẻ ghi rõ phương thức và việc dữ liệu được gửi tới host. Công cụ write đi qua effect journal và chính sách duyệt của host.
  • Truy vấn {source: "tool"} (đọc khi mở màn hình) chỉ gắn được công cụ GET. Công cụ POST như ví dụ này gắn làm hành động có tên và gọi bằng soot.run.
  • input là một JSON Schema nhỏ: object của string, number, integer, boolean (có enum, giới hạn độ dài và giá trị) hoặc mảng của chúng. Host kiểm mọi lời gọi.
  • {{input.<trường>}} đặt được trong đường dẫn, giá trị query, header và chuỗi của body; một chuỗi chỉ gồm đúng một chỗ giữ thì nhận nguyên giá trị có kiểu. {{cred:<TÊN>}} chỉ đặt được trong header hay giá trị query. Scheme, host và tên header luôn là chữ viết sẵn.
  • needs là thứ người duyệt: các host (tên miền, không IP, không cổng) và các khóa. Mỗi khóa có title, description và url để người biết lấy khóa ở đâu; thẻ hiện link "Lấy khóa ở đâu" khi có cả description lẫn url.

Dịch vụ giả định trả {"translations": [{"text": "…", "detected_source_language": "EN"}]}; output.pick lấy phần tử đầu, nên màn hình nhận {text, detected_source_language}.

Ghi tool.json là lưu công cụ. Kết quả của lệnh ghi có một note:

Mẫu JSON · không phải lệnh
{"tool": "soot:writer:translate", "saved": true, "revision": "…", "state": "proposed", "credentials_missing": ["TRANSLATE_KEY"],
 "message": "proposed: the person is asked once to approve it (with the screen that uses it, when a proposed screen binds it); until then it cannot be called. The person enters TRANSLATE_KEY in Nest; never ask for a key in chat"}

Bảng thuật ngữ

Màn hình đọc và ghi bảng glossary của Soot. Bảng phải có trước khi lưu piece.json (lúc lưu runtime chạy thử truy vấn). Soot tạo nó bằng tool data:

Mẫu JSON · không phải lệnh
{"op": "create_table", "scope": "soot:writer", "table": "glossary", "description": "Terms the translate screen keeps.",
 "columns": [{"name": "term", "type": "text", "required": true}, {"name": "meaning", "type": "text", "required": true}]}

Màn hình

ui/translate/index.html. CSP của bundle chặn script và style viết thẳng trong HTML, nên script là file riêng. Không dùng <form>: khung chỉ có allow-scripts, sự kiện submit không bao giờ tới; nút là type="button" có click handler.

Văn bản mẫu · không phải lệnh
<!doctype html>
<html lang="vi">
<meta charset="utf-8">
<title>Dịch</title>
<link rel="stylesheet" href="_kit/piece.css">
<h1>Dịch</h1>
<p id="state" class="muted"></p>
<section class="card stack">
  <textarea id="text" rows="4" maxlength="5000" aria-label="Chữ cần dịch" placeholder="Dán chữ cần dịch"></textarea>
  <div class="row">
    <select id="target" aria-label="Dịch sang">
      <option value="EN">Tiếng Anh</option>
      <option value="VI">Tiếng Việt</option>
      <option value="JA">Tiếng Nhật</option>
    </select>
    <button id="go" type="button" class="primary">Dịch</button>
  </div>
  <p id="result" class="muted">Bản dịch hiện ở đây.</p>
</section>
<section class="card stack">
  <h2>Hỏi Soot</h2>
  <div class="row">
    <input id="question" class="grow" maxlength="4000" aria-label="Câu hỏi" placeholder="Bản dịch này đã tự nhiên chưa?">
    <button id="ask" type="button">Hỏi</button>
  </div>
  <p id="answer" class="muted"></p>
</section>
<section class="card stack">
  <h2>Thuật ngữ</h2>
  <ul id="terms" class="list"></ul>
  <div class="row">
    <input id="term" aria-label="Thuật ngữ" placeholder="Thuật ngữ">
    <input id="meaning" class="grow" aria-label="Nghĩa" placeholder="Nghĩa">
    <button id="add" type="button">Lưu</button>
  </div>
</section>
<script src="_kit/piece.js"></script>
<script src="app.js"></script>
</html>

ui/translate/app.js:

Văn bản mẫu · không phải lệnh
const $ = id => document.getElementById(id);
const say = (el, text, cls = "muted") => { el.textContent = text; el.className = cls; };
let last = null; // the last translation, sent along with a question

async function translate() {
  const text = $("text").value.trim(), target = $("target").value;
  if (!text) return say($("result"), "Nhập chữ cần dịch.", "error");
  $("go").disabled = true;
  say($("result"), "Đang dịch…");
  try {
    const { output } = await soot.run("translate", { text, target });
    last = { text, target, translation: output.text };
    say($("result"), output.text, "");
  } catch (err) {
    // Nest itself says a key is missing, with its "Mở Kho khóa" button; do not repeat it.
    say($("result"), err.code === "credential_missing" ? "Chưa dịch được: thiếu khóa." : "Chưa dịch được: " + err.message, "error");
  } finally {
    $("go").disabled = false;
  }
}

function showAsk(s) {
  if (s.state === "done") {
    const better = s.reply.data && s.reply.data.translation;
    say($("answer"), s.reply.text + (better ? " Gợi ý: " + better : ""), "");
  } else if (s.state === "waiting") say($("answer"), "Soot cần bạn trả lời trong cuộc trò chuyện.");
  else if (s.state === "failed") say($("answer"), "Soot chưa trả lời được câu này.", "error");
  else say($("answer"), "Soot đang trả lời…");
}

async function ask() {
  const text = $("question").value.trim();
  if (!text) return;
  $("ask").disabled = true;
  try {
    const s = await soot.ask(last ? { text, data: last } : { text }, { onState: showAsk });
    showAsk(s);
    if (s.state === "done") $("question").value = ""; // asked and answered: the box is empty for the next one; a failed question stays to retry
  } catch (err) {
    say($("answer"), "Chưa hỏi được: " + err.message, "error");
  } finally {
    $("ask").disabled = false;
  }
}

function drawTerms(out) {
  $("terms").replaceChildren(...out.rows.map(row => soot.el("li", { class: "row" },
    soot.el("strong", {}, row.term), soot.el("span", { class: "grow muted" }, row.meaning))));
  if (!out.total) $("terms").replaceChildren(soot.el("li", { class: "empty" }, "Chưa có thuật ngữ nào."));
}

async function addTerm() {
  const term = $("term").value.trim(), meaning = $("meaning").value.trim();
  if (!term || !meaning) return;
  $("add").disabled = true;
  try {
    await soot.run("add_term", { rows: [{ term, meaning }] });
    $("term").value = $("meaning").value = "";
    drawTerms(await soot.view("terms"));
  } catch (err) {
    say($("state"), "Chưa lưu được thuật ngữ: " + err.message, "error");
  } finally {
    $("add").disabled = false;
  }
}

soot.ready(async () => {
  if (soot.level < 2) {
    say($("state"), "Màn hình này cần Nest mới hơn. Cập nhật Nest rồi mở lại.", "error");
    document.querySelectorAll("button").forEach(b => { b.disabled = true; });
    return;
  }
  $("go").addEventListener("click", translate);
  $("ask").addEventListener("click", ask);
  $("add").addEventListener("click", addTerm);
  const kept = soot.cached("terms");
  if (kept) drawTerms(kept);
  soot.live(async () => {
    try { drawTerms(await soot.view("terms")); } catch (err) { say($("state"), "Chưa đọc được thuật ngữ: " + err.message, "error"); }
    // The newest question and its answer, also when the screen is opened again.
    try { const prev = (await soot.asks()).asks[0]; if (prev) showAsk(prev); } catch (err) { /* nothing asked yet */ }
  });
});

  • soot.run(name, input) chạy hành động có tên name, runtime làm ngay, không có lượt model. Mỗi lần gọi một request_id mới; gửi lại đúng request_id cũ chỉ đọc lại kết quả, không gọi lần hai.
  • soot.ask(input, {onState}) gửi câu hỏi vào cuộc trò chuyện riêng của người xem với Soot chủ. Promise trả trạng thái done có reply {text, data?}, bị từ chối với ask_failed khi run hỏng. soot.asks() cho các câu đã hỏi, mới nhất trước, nên mở lại màn hình là thấy câu trả lời; soot.live đọc lại khi cuộc trò chuyện đổi.
  • Nest chỉ chuyển soot.run, soot.action và soot.ask khi người vừa bấm hay gõ trong màn hình; gọi chúng lúc màn hình vừa mở hay từ hẹn giờ bị từ chối với gesture_required. soot.view và soot.asks thì không cần, và theo lại một câu đã hỏi (cùng request_id, sau khi tải lại) cũng không cần.
  • Khóa thiếu, khóa sai hay dịch vụ lỗi đều đến dưới dạng một lỗi có code và message người đọc được. Khi thiếu khóa (credential_missing), Nest tự báo ở đầu màn hình kèm nút "Mở Kho khóa", nên màn hình chỉ nói ngắn là chưa làm được; lỗi khác thì màn hình hiện err.message.

Khai báo

ui/translate/piece.json, ghi sau cùng:

Mẫu JSON · không phải lệnh
{
  "id": "translate",
  "slot": "rail",
  "label": {"vi": "Dịch", "en": "Translate"},
  "icon": "globe",
  "order": 300,
  "access": "operator",
  "data": {
    "queries": {
      "terms": {"source": "table", "table": "glossary", "order": "term", "limit": 100}
    },
    "actions": {
      "translate": {"tool": "translate"},
      "add_term": {"table": "glossary", "op": "insert"}
    },
    "ask": true
  }
}

  • queries là các lần đọc có tên (task, table, file, need, outcome, memory, hoặc {source: "tool", tool} cho một công cụ read dùng GET của chủ). Tối đa 8.
  • actions là các hành động có tên: {tool} gọi công cụ của chủ, {table, op: "insert" | "update" | "delete"} ghi bảng trong quyền ghi của chủ. Tối đa 8. insert nhận {rows: [{cột: giá trị}]} và trả {ids}.
  • ask: true cho màn hình hỏi Soot chủ. Mặc định tắt.
  • Công cụ phải được ghi trước piece.json: một hành động trỏ tới công cụ chưa có thì lưu bị từ chối với tool_unknown.

Kết quả của lệnh ghi có note {"screen": "soot:writer:translate", "saved": true, "state": "proposed", …}.

Người duyệt một lần

Lần lưu đầu tạo một việc trong Cần bạn cho cả màn hình lẫn công cụ nó dùng. Thẻ cho người thấy: màn hình nằm ở đâu, ai thấy, đọc gì, có nút gì; với mỗi công cụ: làm gì (chỉ đọc, hay gửi đi và thay đổi dữ liệu), phương thức và host nó gửi tới, cần khóa nào (tên và mã khóa), khóa đó "Đã có" hay "Chưa có". Khóa đã có mà bản này sẽ gửi tới một host mới thì thẻ báo ngay trên nút duyệt; host mà ô nhập đã ghi khi người nhập khóa không tính là mới. Khóa chưa có thì thẻ có một ô nhập kín và link "Lấy khóa ở đâu", link này hỏi người xác nhận host trước khi mở. Người nhập khóa, bấm "Lưu khóa" (giá trị đi thẳng tới runtime, ô tự xoá), rồi "Duyệt và đặt vào Nest": màn hình hiện ở thanh bên, công cụ chạy được.

Soot không bao giờ thấy khóa và không bao giờ hỏi khóa trong chat. Thiếu khóa vẫn duyệt được; khi đó lần dịch đầu báo thiếu khóa và Nest đưa người tới Kho khóa.

Sau khi đặt, Soot sửa giao diện thoải mái và các bản mới lên ngay. Nhưng thêm host, thêm khóa, đổi phương thức, đổi read sang write, thêm hành động trỏ tới đích mới, đổi chữ tìm (search) của truy vấn trí nhớ, bật ask hay đổi chỗ đặt và người thấy đều bị từ chối (approval_needed); muốn với xa hơn thì lưu dưới id mới để người được hỏi lại.

Trả lời câu hỏi từ màn hình

Một câu hỏi tới Soot như một tin nhắn trong cuộc trò chuyện riêng của người xem: dòng đầu là Hỏi từ màn hình “Dịch”, rồi câu hỏi, rồi data của màn hình trong một khối JSON. Soot trả lời như mọi tin nhắn: tin nhắn cuối của nó là reply.text. Run này có thêm tool piece_reply; Soot gọi nó với data là một giá trị JSON (viết thành chuỗi, tối đa 16 KiB) để màn hình nhận dữ liệu có cấu trúc, ở ví dụ là {"translation": "…"}. Người mở được cuộc trò chuyện đó từ đầu màn hình ("Mở cuộc trò chuyện") và gõ tiếp ở đó.

Câu hỏi của người vận hành chạy trong workspace của chủ, nên Soot dùng được công cụ của mình (tool_translate) và bảng thuật ngữ. Câu hỏi của một thành viên chạy trong chỗ của thành viên: không có công cụ hay khóa của chủ.

Thử

  1. Cho Soot chọn pack soot-nest (đi kèm runtime): skill nest-pieces dạy đúng các bước trên. Soot có read thì đã có tool storage và data.
  2. Nhắn Soot điều bạn cần. Soot ghi file và nói việc đang chờ ở Cần bạn.
  3. Mở thẻ, xem trước màn hình, nhập khóa, duyệt. Mở "Dịch" ở thanh bên, dịch một câu, hỏi Soot một câu.
  4. Không có Nest thì mở http://<runtime>/v1/pieces/soot:writer:translate/ trong trình duyệt để xem màn hình; vỏ này ở mức cầu 1, nên soot.run và soot.ask chỉ chạy trong Nest.

Hướng dẫn đầy đủ cho mảnh tự viết (mọi nguồn truy vấn, vòng đời, bộ kit): Màn hình Soot tự làm.

Đường 2: pack mang màn hình tới

Ví dụ dưới là một pack tối thiểu, hello-board: một phần "Bảng tin" ở Hộp việc, đọc bằng một tool, ghim một dòng bằng tool thứ hai. soot init-pack hello-board --with tool tạo khung thư mục; bốn file dưới đây là toàn bộ phần còn lại.

Văn bản mẫu · không phải lệnh
hello-board/pack.json
hello-board/tools/board.mjs
hello-board/ui/board/index.html
hello-board/ui/board/app.js

Khai báo

pack.json. Mảnh nằm trong interface.pieces; data.view_tool và data.action_tool là tên hai tool của chính pack này.

Mẫu JSON · không phải lệnh
{
  "name": {"vi": "Bảng tin", "en": "Board"},
  "description": "A first piece: one section of the inbox, served by two tools.",
  "tools": [
    {
      "name": "board_view",
      "description": "List the board's lines, optionally filtered by q.",
      "parameters": {"type": "object", "properties": {"q": {"type": "string"}}},
      "run": {"program": "node", "args": ["tools/board.mjs", "view"], "stdin": "context", "mode": "read"}
    },
    {
      "name": "board_pin",
      "description": "Pin one line of the board.",
      "parameters": {"type": "object", "properties": {"pin": {"type": "string"}}, "required": ["pin"]},
      "run": {"program": "node", "args": ["tools/board.mjs", "pin"], "stdin": "context", "mode": "write"}
    }
  ],
  "interface": {
    "pieces": [
      {
        "id": "board",
        "slot": "home",
        "label": {"vi": "Bảng tin", "en": "Board"},
        "icon": "pin",
        "order": 200,
        "access": "operator",
        "bundle": "ui/board/",
        "data": {"view_tool": "board_view", "action_tool": "board_pin"}
      }
    ]
  }
}

  • id của mảnh là tiếng Anh, chữ thường, gạch nối, duy nhất trong pack. Một pack khai 1 đến 8 mảnh.
  • access là operator (chỉ người vận hành) hoặc member (cả thành viên vào được Soot phục vụ mảnh).
  • bundle là một thư mục trong pack, có index.html, không quá 5 MiB.
  • Tool đọc phải có run.mode: "read"; cả hai tool nhận run.stdin: "context". Tool cần người duyệt (approval) không dùng được làm tool của mảnh: màn hình không vẽ bước duyệt.
  • Trường lạ là lỗi. interface.pages là tên cũ: pack mới khai nó bị từ chối khi cài, lỗi nói cách chuyển sang pieces. Pack đã cài từ trước vẫn chạy công cụ và kỹ năng, chỉ không hiện màn hình cho tới khi được cập nhật.

Tool đọc và tool làm

Runtime chạy tool với một object JSON trên stdin và đọc một object JSON trên stdout. Ngoài input do màn hình gửi, tool nhận piece (Soot đang phục vụ, id mảnh, mode là view hay action) và viewer (ai đang xem).

tools/board.mjs:

Văn bản mẫu · không phải lệnh
import { readFileSync } from "node:fs";

// stdin: {piece: {soot, piece, mode}, input, viewer: {kind, id}, ...}
const ctx = JSON.parse(readFileSync(0, "utf8"));
const input = ctx.input ?? {};
const LINES = [
  { id: "release", text: "Phát hành bản 1.4 vào thứ Sáu" },
  { id: "interview", text: "Phỏng vấn ứng viên hỗ trợ lúc 14:00" },
];
const reply = value => console.log(JSON.stringify(value));

if (process.argv[2] === "view") {
  const q = String(input.q ?? "").toLowerCase();
  const lines = LINES.filter(line => line.text.toLowerCase().includes(q));
  reply({ lines, total: lines.length });
} else if (LINES.some(line => line.id === input.pin)) {
  reply({ pinned: input.pin });
} else {
  reply({ error: "no such line", reason: "invalid_input" });
  process.exit(1);
}

  • Coi input là dữ liệu chưa đáng tin: nó đến từ một trang trong sandbox, kiểm như kiểm mọi đầu vào.
  • Tool chạy dưới tên Soot phục vụ mảnh, với đúng quyền và credential như khi Soot đó tự gọi tool. Màn hình không thêm quyền nào.
  • Một hành động chạy đúng một lần cho mỗi request_id. Gửi lại cùng id thì nhận lại kết quả cũ, tool không chạy lần hai.
  • Đừng trả bí mật trong kết quả đọc: Nest giữ kết quả lần trước trên máy người xem để mở lại là thấy ngay.

Bundle

Bundle là một trang web thường. Hai link _kit/piece.css và _kit/piece.js do runtime phục vụ trong mọi phiên: kit lo cầu nối với Nest, màu và chữ theo Nest, sáng và tối. CSP của bundle chặn script và style viết thẳng trong trang, nên script là file riêng.

ui/board/index.html:

Văn bản mẫu · không phải lệnh
<!doctype html>
<html lang="vi">
<meta charset="utf-8">
<title>Bảng tin</title>
<link rel="stylesheet" href="_kit/piece.css">
<p id="state" class="muted">Đang tải…</p>
<ul id="lines" class="list"></ul>
<script src="_kit/piece.js"></script>
<script src="app.js"></script>
</html>

ui/board/app.js:

Văn bản mẫu · không phải lệnh
const state = document.getElementById("state");
const list = document.getElementById("lines");

function draw(out) {
  list.replaceChildren(...out.lines.map(line => soot.el("li", { class: "row" },
    soot.el("span", { class: "grow" }, line.text),
    soot.el("button", { type: "button", onclick: event => pin(event.target, line) }, "Ghim"))));
  state.textContent = out.total ? out.total + " dòng" : "Chưa có dòng nào.";
}

async function pin(button, line) {
  button.disabled = true;
  try {
    await soot.action({ pin: line.id });
    button.textContent = "Đã ghim";
  } catch (err) {
    button.disabled = false;
    state.textContent = "Chưa ghim được: " + err.message;
  }
}

// Mở lại thì vẽ ngay kết quả lần trước, rồi đọc số mới.
soot.ready(() => { const last = soot.cached({}); if (last) draw(last); });
// Tự đọc lại khi có thay đổi, khi hiện lại, và mỗi phút khi đang hiện; khuất thì nghỉ.
soot.live(async () => {
  try { draw(await soot.view({})); } catch (err) { state.textContent = "Chưa đọc được: " + err.message; }
});

Mảnh của pack gọi soot.view(input) và soot.cached(input) không có tên; mảnh Soot tự viết gọi theo tên truy vấn. Phần còn lại của kit giống nhau, xem bộ kit.

Thử

  1. Đặt thư mục pack vào packs_dir của workspace và cho một Soot chọn nó: {"packs": ["hello-board"]}.
  2. soot check --show nạp pack như runtime sẽ nạp. Khai báo mảnh sai thì báo piece_invalid kèm tên mảnh và lý do (tool_missing, view_not_read, stdin_not_context, bundle_missing, bundle_too_large, tab_required, unknown_slot…).
  3. Chạy tool bằng tay với đúng thứ runtime sẽ gửi (lệnh ở dưới); nó phải in ra một object JSON.
  4. Chạy runtime và mở Nest: mảnh có ngay ở Hộp việc, không hỏi ai, vì người vận hành đã chọn pack. Không có Nest thì mở http://<runtime>/v1/pieces/pack:hello-board:board/ trong trình duyệt: đó là một trang vỏ dựng đúng khung và cầu như Nest, hỏi key vận hành một lần (origin của runtime phải có trong server.browser_origins).
  5. Sửa bundle rồi mở lại màn hình. Một khung đang mở giữ bản cũ tối đa 10 phút (tuổi của một phiên).
Terminal · kiểm tra trước khi chạy
echo '{"piece":{"soot":"helper","piece":"board","mode":"view"},"input":{"q":"bản"},"viewer":{"kind":"operator","id":"operator"}}' | node tools/board.mjs view

Phát hành pack như mọi pack khác; xem Agent, nhóm, pack, Forge.

Người vận hành quyết gì

Màn hình của người khác chạy trong Nest của bạn, nên quyền cuối cùng ở bạn.

  • Màn hình Soot tự làm phải được bạn đặt. Lần đầu, nó là một việc trong Cần bạn: bạn xem trước, thấy nó sẽ nằm ở đâu, ai thấy, đọc những gì, có gửi hành động không, rồi đặt hoặc từ chối. Từ chối thì Soot được báo và không hỏi lại cho tới khi nó đổi nội dung.
  • Đã đặt thì không tự với xa hơn. Soot sửa giao diện và cách lọc thoải mái, nhưng không tự đổi được chỗ đặt, người thấy, quyền gửi hành động hay nguồn dữ liệu của màn hình bạn đã duyệt.
  • Quay lại và gỡ. Mỗi màn hình tự viết có lịch sử bản; bạn quay về bản trước hoặc gỡ hẳn khỏi Nest ngay trên màn hình đó. Bản mới mà hỏng hai lần tải trên máy bạn, chưa từng tải được, thì runtime tự quay về bản tốt gần nhất.
  • Màn hình của pack đi theo pack. Soot chọn pack thì có, bỏ chọn thì mất. Chọn pack là việc của bạn, nên Nest không hỏi thêm.
  • Bố cục là của bạn. Cài đặt › Màn hình cho xếp thứ tự và ẩn từng màn hình; bố cục nằm trên máy bạn. Một Soot chỉ đề xuất được bố cục, bạn áp dụng hoặc từ chối.
  • Công cụ và khóa do bạn duyệt. _[0.19.0]_ Màn hình dùng công cụ Soot tự viết thì thẻ duyệt ghi rõ từng công cụ làm gì (chỉ đọc hay gửi đi), gửi bằng phương thức nào tới host nào và cần khóa nào, đã có hay chưa. Khóa chưa có thì nhập ngay trên thẻ, hoặc để sau và bấm "Mở Kho khóa" khi màn hình báo thiếu. Thiếu khóa vẫn duyệt được; công cụ chỉ chạy khi đã có khóa.
  • Thấy cái nào nặng. Cũng ở Cài đặt › Màn hình: mỗi màn hình mở mất bao lâu trên máy này, bao nhiêu lần không mở kịp, lần đọc nào quá lớn.

Giới hạn và an toàn

  • Khung sandbox. Mỗi màn hình chạy trong một khung riêng, không có credential, không gọi mạng được (connect-src 'none'), không gửi form. Nó chỉ nói chuyện với Nest qua cầu postMessage, và Nest chỉ chuyển lời gọi tới chính mảnh đó.
  • Điều khung vẫn làm được. CSP không chặn được một trang tự chuyển hướng chính nó. Khi khung rời bundle, Nest đóng nó và tính là một lần tải hỏng, nhưng địa chỉ nó chuyển tới đã được gọi. Vì vậy hãy coi dữ liệu màn hình đọc được là dữ liệu tác giả của nó đọc được: chỉ đặt màn hình của Soot và pack bạn tin, như khi cấp quyền cho chính chúng.
  • Không cấp quyền. Mức truy cập của chủ là trần, kiểm lúc lưu và kiểm lại mỗi lần gọi. Màn hình không tự cấp được quyền nào, không đọc được khóa, và chỉ biết thiếu khóa khi runtime trả lời một lần gọi.
  • Mở link. soot.open và thẻ <a> nhờ Nest mở link. Nest chỉ nhận khi màn hình đang hiện, nhiều nhất một lần mỗi giây, và không mở khung trình duyệt của Nest theo lời một màn hình.
  • Con số. Bundle ≤ 5 MiB; ở home, script và style ≤ 512 KiB. Gọi soot.ready() trong 1 giây (quá 5 giây là một lần tải hỏng). Mỗi lần đọc trả về dưới 256 KiB. Cùng một lần đọc tới runtime nhiều nhất một lần mỗi giây khi hiện, mười giây khi khuất; sau một hành động hoặc khi runtime báo có thay đổi thì lần đọc kế tiếp luôn tới runtime. Mảnh tự viết: tối đa 8 mảnh mỗi chủ, 8 truy vấn mỗi mảnh, 10 hành động mỗi phút. _[0.19.0]_ Hành động và câu hỏi tính chung: 10 mỗi phút cho mỗi người xem, 30 cho cả mảnh; đầu vào của soot.run và soot.ask tối đa 8 KiB, chữ hỏi 4000 ký tự. Công cụ tự viết: tối đa 16 mỗi chủ, 30 lời gọi mỗi phút mỗi công cụ, câu trả lời tối đa 256 KiB, chờ tối đa 60 giây (mặc định 20).
  • Nhẹ là mặc định. Nest chỉ mở khung khi nó sắp vào màn hình, nhiều nhất 4 khung cùng lúc; khuất thì không hẹn giờ, không hỏi runtime. Dùng soot.live thay cho tự hẹn giờ.

Khi Soot và Nest lên bản mới

Màn hình bạn làm hôm nay vẫn chạy ở các bản sau. Bốn điều cần biết:

  • `kit`. Manifest có thể ghi "kit": 1: bản bộ kit mà bundle được viết cho. Bỏ trống cũng là 1, và mặc định đó không bao giờ đổi. Runtime gặp bản nó không phục vụ thì từ chối với kit_unsupported và nói nó phục vụ bản nào.
  • Tính năng thêm sau. Cầu giữa khung và Nest có một mức (soot.level). Nest 0.18.0 có mức 1; mức 2 thêm soot.run, soot.ask và soot.asks. Tính năng thêm sau này mang mức cao hơn. Màn hình muốn dùng thì kiểm soot.level trước, nên vẫn chạy được trên Nest cũ: ở mức 1, kit từ chối ba lời gọi đó với unsupported và không gửi gì.
  • Tin Nest gửi có thể có thêm trường. Nest được thêm trường vào một tin (init, result…) mà không đổi mức. Màn hình dùng kit thì không phải làm gì: kit chỉ đọc trường nó cần. Bundle tự nói chuyện qua cầu thì phải bỏ qua trường và loại tin nó không biết, đừng so tin với một danh sách trường cố định: làm thế thì màn hình hỏng ở lần Nest thêm trường tiếp theo.
  • Thay đổi phá vỡ. Luôn mang số kit mới và đi qua hai bản phát hành: bản đầu phục vụ cả kit cũ lẫn mới, bản sau mới bỏ kit cũ. Trong lúc đó runtime báo cho Soot chủ để nó viết lại màn hình; pack thì ra bản mới trên Forge.

Quy tắc đầy đủ ở Mảnh: chuẩn mở rộng Nest.

Khi có lỗi

Thấy gìVì saoLàm gì
Lệnh ghi piece.json trả saved: falsereason nói lỗi gì, message nói cách sửaSửa rồi ghi lại piece.json
approval_neededMàn hình đã đặt đang với xa hơn bản người duyệtGiữ nguyên tầm với, hoặc lưu dưới id mới
kit_unsupportedManifest ghi bản kit mà runtime này không phục vụBỏ kit hoặc ghi bản runtime nêu trong lỗi; nếu màn hình cần kit mới hơn thì cập nhật Soot
soot check báo piece_invalidKhai báo mảnh của pack saiXem reason và con trỏ tới trường sai
retired_field ở /interface/pagesPack còn dùng tên cũChuyển sang interface.pieces theo gợi ý của lỗi
Khung trắng, rồi "không mở kịp"Trang không gọi ready trong 5 giây, thường do script viết thẳng trong HTML bị CSP chặnĐưa script ra file, link _kit/piece.js trước
tool_refused với approval_requiredTool của mảnh cần người duyệtDùng tool không cần duyệt cho màn hình
429 busyMọi mảnh dùng chung 8 lượt toolNest tự thử lại; giữ tool đọc nhanh (dưới 500 ms)
rate_limitedQuá 10 hành động mỗi phút trên một mảnh tự viếtChờ theo retry_after
owner_unavailableChủ màn hình chưa nhận việc lúc nàyChưa có gì được gửi: cho người bấm thử lại sau
ask luôn trả owner_unavailableSoot chủ chỉ là thành viên của một đội, không phải Soot mở được cuộc trò chuyện trực tiếpCho Soot đó đứng một mình hoặc làm một cửa vào (entries) của đội; hoặc để Đầu mối viết màn hình ở level của đội
gesture_required _[0.19.0]_Màn hình gọi soot.run hay soot.ask lúc tải hay từ hẹn giờ, không phải ngay sau một cú bấm hay phím của ngườiChỉ gọi hai lệnh đó trong click handler; đọc khi tải bằng soot.view và soot.asks
Bấm nút trong một <form> không có gì xảy raKhung chỉ có allow-scripts, không allow-forms: sự kiện submit không bao giờ tớiBỏ <form>, dùng button type="button" với click handler
Bundle tự nói cầu hỏng sau khi Nest cập nhậtMàn hình so tin của Nest với một danh sách trường cố địnhBỏ qua trường và loại tin không biết; hoặc dùng kit
"Mở cuộc trò chuyện" không tới đúng chỗMàn hình ghép link từ run_id hay id khácHội thoại của câu hỏi là conversation_id trong kết quả (32 ký tự hex): soot.open("nest://conversation/<conversation_id>")
credential_missing _[0.19.0]_Khóa của công cụ chưa được nhậpNgười nhập khóa trên thẻ hoặc ở Kho khóa ("Mở Kho khóa" hiện trên màn hình); không bao giờ gửi khóa trong chat
credential_rejected _[0.19.0]_Dịch vụ trả 401 hay 403: khóa sai hoặc hết hạnNgười thay khóa ở Kho khóa
upstream_error, timeout, request_failed _[0.19.0]_Dịch vụ trả lỗi, chậm quá timeout, hoặc không tới đượcXem status và body (đã che khóa); kiểm url, body theo tài liệu của dịch vụ
Lưu tool.json bị từ chối _[0.19.0]_reason nói lỗi gì: run_invalid, method_needs_write, host_not_declared, credential_not_declared, input_invalid, manifest_invalid, approval_needed…Sửa đúng trường message nêu, ghi lại tool.json
Lưu piece.json trả tool_unknown _[0.19.0]_Hành động hay truy vấn trỏ tới công cụ chưa ghi, đã gỡ, hoặc truy vấn đọc một công cụ không dùng GET (write, hay read dùng POST)Ghi tools/<id>/tool.json trước, rồi ghi lại piece.json
Màn hình không đổi sau khi sửaKhung đang mở giữ phiên cũĐóng mở lại màn hình

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