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

06 / Extension

Core và extension: mở rộng Soot và Nest

Cái gì thuộc core, cái gì là extension; hợp đồng tool; mở rộng Nest; nhu cầu mới đặt ở lớp nào.

Soot là một runtime cố định. Việc mới của sản phẩm (hỗ trợ khách, đăng bài, đối soát đơn, duyệt hợp đồng) không đi vào binary mà đi vào config, skill, tool và pack. Tài liệu này nói ranh giới giữa core và extension nằm ở đâu, thứ mới nên đặt ở lớp nào, và những gì không bao giờ được thêm vào core.

Tài liệu dành cho người thêm tính năng cho Soot, Nest hoặc viết pack. Quy tắc gốc nằm trong AGENTS.md (Hard constraints); đây là phần giải thích vì sao và cách áp dụng.

Mô hình

Văn bản mẫu · không phải lệnh
            ┌────────────────────── EXTENSION (không cần build lại binary) ──────────────────────┐
            │  pack = skills + tools (+ interface, pieces, storage, programs, platforms)          │
            │  adapter / ingress (process riêng, deployment khởi động)                           │
            │  Soot definition + deployment.json (config)                                         │
            └───────────────▲──────────────────────────────▲─────────────────────▲───────────────┘
                 soot/v1 envelope (stdin)        channel-adapter.v1 (HTTP)    pack.json (đọc, hiển thị)
            ┌───────────────┴──────────────────────────────┴─────────────────────┴───────────────┐
            │ CORE (internal/core): AgentCore host, store, auth/grants, credentials vault,       │
            │       management, channel host, piece host, workspace, transport/httpapi           │
            │ FEATURE (internal/feature, cắm qua hook): traces, monitoring, train, improve,      │
            │       jobs, mcpserver, autoupdate, browserinstall, adapter                         │
            │ COMPOSE (internal/compose): app, scaffold, features; nơi link feature vào binary   │
            └───────────────▲─────────────────────────────────────────────────────────────────────┘
                            │ HTTP /v1/* + registry
            ┌───────────────┴────────────────────────────────────────────────────────────────────┐
            │ NEST: shell + registry (rail, Settings, Dữ liệu, renderer). Hiển thị, không cấp quyền│
            └────────────────────────────────────────────────────────────────────────────────────┘

Ba nguyên tắc cùng một ý:

  1. Việc vào Soot trước: event, rồi Soot, rồi (tùy chọn) tool. Không có bộ điều phối nào đứng trước Soot.
  2. Workload là config, skill và tool. Thêm một workload không cần build lại binary.
  3. Core không import contrib hay pack. Extension cắm vào core qua hợp đồng hẹp, không qua code.

Khái niệm

Thuật ngữNghĩa
CorePhần mọi triển khai đều cần và không đổi theo sản phẩm: vòng chạy agent (qua AgentCore), lưu hội thoại, xác thực, cấp quyền, vault, quản lý cấu hình, host cho kênh chat và cho mảnh của Nest.
FeaturePackage Go dưới internal/feature/, không nằm trong core: traces, monitoring, train, improve, jobs, mcpserver, autoupdate, selfupdate, browserinstall, adapter, evalcase. Cắm vào core qua hook, link bằng blank import.
ComposeLớp ghép dưới internal/compose/: app, scaffold và features. Được import cả core lẫn feature; feature được link vào binary ở đây. Không core hay feature nào import lớp này.
ExtensionThứ chạy hoặc được đọc mà không build lại binary: pack, tool, skill, adapter, mảnh (piece), renderer.
PackGói phân phối skills và tools. Soot chọn cả pack. Cài không phải cấp. Mô hình pack và cách chọn: agents.md.
ToolExecutable khai trong pack.json với run: {program, args, ...}. Nói chuyện với host bằng envelope soot/v1.
AdapterProcess riêng nói giao thức một nền tảng (Telegram, Discord, trình duyệt). Deployment khởi động, không phải pack install.
Mảnh (piece)Bundle HTML nhỏ do pack gửi, đặt vào một slot của Nest (rail, home, project.tab, data.tab, settings). Chỉ là giao diện.
Registry của NestDanh sách khu (area), slot, mảnh, Settings section, Dữ liệu tab, renderer mà Nest dựng rail và palette từ đó.

Core gồm những gì

Ranh giới nằm ngay trong đường dẫn: mọi package dưới internal/ thuộc đúng một trong bốn thư mục.

Thư mụcChứa gìLuật import
internal/core/Phần mọi triển khai cần: config, configstate, sqlstore, authz, access, credentials, conversation, channel, workspace, operations, management, pieces, principal, runtime (engine), firstrun, ledger, transport, cùng các thư viện chúng dùng (hostio, providers, toolrun...). Package contract ở gốc module cũng là core.Chỉ import core (trừ hai cạnh allow); không import compose/ hay test/
internal/feature/train, improve, monitoring, traces, adapter, browserinstall, autoupdate, selfupdate, jobs, mcpserver, evalcaseImport core và feature khác
internal/compose/Lớp ghép: app, scaffold và features (danh sách blank import)Import core và feature
internal/test/guard, testutil, scenarioe2e, projecte2e, storebenchChỉ test dùng

contracts/core-layering/layers.json khai bốn nhóm này và các cạnh core → feature còn được dung thứ. Hiện có hai cạnh: core/conversation → feature/monitoring và core/conversation → feature/traces (chờ tách conversation). Danh sách allow chỉ được co lại.

TestCoreLayering kiểm import trực tiếp của từng package core, kiểm toàn bộ closure của core/config, và fail khi một package dưới internal/ không thuộc nhóm nào hoặc thuộc hai nhóm. Core và feature không được import compose/... hay test/... (import production); core không build cùng lớp ghép.

Các test khác giữ ranh giới:

TestGiữ gì
TestCoreLayering (internal/compose/app/layering_test.go)Core không import feature, compose/ hay test/; feature không import compose/ hay test/; mọi package dưới internal/ thuộc đúng một lớp.
TestDependencyDirection, TestCoreDoesNotLinkContrib (internal/compose/app/architecture_test.go)domain không biết os hay HTTP; runtime không biết module, provider, transport; không package core nào import contrib/.
TestCoreIsCSFree (internal/test/guard/)Core, contract, docs/contracts/ và desktop/src/ không chứa từ vựng của một ngành cụ thể. Danh sách ngoại lệ chỉ được co lại.
TestCoreIsGoalFree (internal/test/guard/)File không phải test dưới internal/core/ và contract/ không nhắc tới lớp mục tiêu (bảng, section workspace.goals, thẻ, route, scope của tính năng workspace). Danh sách ngoại lệ goal_allowlist.txt chỉ được co lại.
desktop/tests/pack-names-guard.test.mjsKhông file Nest nào so sánh hay liệt kê id pack, id nền tảng hay kind giao diện cụ thể. Danh sách ngoại lệ bắt đầu rỗng và nên giữ rỗng.
desktop/tests/core-words-guard.test.mjsdesktop/src/app/ và desktop/src/lib/ không gọi tên pack, loại dự án, tab, mục đích của đội hay khái niệm công ty (mục tiêu, sản phẩm, chiến dịch), bằng tiếng Anh lẫn tiếng Việt, dù là định danh hay chuỗi. Chỗ còn gọi tên là một dòng trong core-words-guard.allow.json (file, số dòng, lý do), và danh sách chỉ được co lại.

Hook: feature cắm vào core thế nào

Hook do core giữ; feature gọi Register* từ init() của chính package đó. Mọi Register* panic nếu trùng.

HookCắm cái gìCode
config.RegisterSectionMột khối config top-level của feature (traces, monitoring, train...)internal/core/config/sections.go
config.RegisterMemoryLevelMột mức memory (workspace, team, soot, user)internal/core/config/memlevels.go
sqlstore.RegisterTenantBảng và migration của feature trong cùng SQLiteinternal/core/sqlstore/tenants.go
management Register(ActionSpec)Một hành động cấu hình (soot.create...), vừa là lệnh soot manage, vừa là tool MCP, vừa là nút trong Nest, có undointernal/core/management
httpapi.RegisterRoutesRoute /v1/... của feature, mount sau route core, trong ranh operatorinternal/core/transport/httpapi/routes.go
httpapi.RegisterAttentionMục trong GET /v1/settings/attentioncùng file
httpapi.RegisterHostAttention, RegisterCardKindMục attention của host (gom theo nhóm) và loại thẻ theo tiền tố id, kèm mức độinternal/core/transport/httpapi/extend.go
httpapi.RegisterViewFieldThêm một khóa vào view của core (GET /v1/workspace/summary), ghi sau các khóa riêng của viewcùng file
httpapi.RegisterProjectSourceNguồn dự án của GET /v1/projects: loại, tên, logo. Core tự tính đội nào thuộc dự án nào. Không có nguồn thì danh sách rỗnginternal/core/transport/httpapi/projects.go
workspace.RegisterMigration, RegisterPortableBảng của feature trong kho workspace (SQLite và PostgreSQL) và các dòng của nó khi chuyển độiinternal/core/workspace/extend.go
workspace.RegisterTool, config.RegisterHostToolMột tool cho model mà feature cung cấp, ngoài các tool Soot tự chọninternal/core/workspace/extend.go, internal/core/config/host_tools.go
workspace.RegisterLinkCheckKiểm tra giá trị liên kết của task (trường goal); không có thì core giữ nguyên giá trịinternal/core/workspace/extend.go
config.RegisterSection với tên có dấu chấmMột khối con trong khối của core (workspace.goals): đọc strict, cùng khóa JSON, vẫn có trong schemainternal/core/config/sections.go
conversation.Service.RunBlockKhối ngữ cảnh host gửi kèm một lượt chạy; compose gáninternal/core/conversation/service.go
principal.RegisterEraserXóa dữ liệu của một người khi có yêu cầu erasure hoặc hết retentioninternal/core/principal/registry.go
ledger.Traces, ledger.Jobs, ledger.MonitorKho trace, job, monitoring mà engine ghi và đọc. Compose gắn kho vào runtime.Engine; slot rỗng nghĩa là engine bỏ qua việc kho đó làminternal/core/ledger
configstate.RegisterBundleAdmission, RegisterGeneralOpenerNhận bundle deploy và mở bản General của Forge cho management; scaffold đăng ký. Không có hook thì deployment bị từ chối (bundle_admission_unavailable) và bản General lỗi ErrNoGeneralOpenerinternal/core/configstate/host_hooks.go

Link thật nằm ở internal/compose/features/features.go: cmd/soot và test end-to-end blank-import package này một lần. internal/compose/app không import nó. Binary hay test không link internal/compose/features sẽ không có section, route hay action của feature, và khóa đó trong deployment thành "unknown field".

Quy tắc đi kèm: kiểu dữ liệu dùng chung giữa core và feature thì nằm ở core ("types move down"). Ví dụ adapter.Overlay chuyển xuống config.

internal/core/principal/registry.go là ví dụ nhỏ nhất của kiểu hook này. File chỉ import context, sort, sync. Mỗi kho có dữ liệu về một người (packstore, piecereceipts, kênh chat) đăng ký một Eraser; route erasure chạy hết, mỗi eraser idempotent. Core không cần biết có những kho nào.

Tool: hợp đồng executable

Tool là cách mở rộng thường dùng nhất. Hợp đồng công khai là package contract/ (contract/contract.go), không phụ thuộc runtime. Tool không cần SDK Go: đọc JSON từ stdin, ghi text ra stdout/stderr. SDK TypeScript (@tofound/soot-sdk, contrib/sdk/typescript/) có sẵn types và codec nếu muốn dùng. Kiểu Go của envelope nằm ở contract/; schema của pack.json xem bằng soot schema pack, khung pack mới bằng soot init-pack.

Văn bản mẫu · không phải lệnh
// packs/research/pack.json: tên thư mục là id của pack
{ "tools": [ { "name": "inspect",
    "run": { "program": "tools/inspect.sh", "stdin": "context", "timeout": "30s" } } ],
  "needs": { "env": ["HOME"] } }
// Operation ID luôn là <pack>_<tool>: "research_inspect"

Model gọi tool bằng chính id của nó (research_inspect); tool không khai báo parameters thì nhận {}. Với run.stdin: "context", host gửi một object JSON, newline, rồi EOF:

Mẫu JSON · không phải lệnh
{ "api_version": "soot/v1", "hook": "tool.call", "soot": "assistant", "root": "assistant",
  "operation": "research_inspect",
  "event": { "id": "1", "source": "conversation", "subject": "...", "text": "..." },
  "input": { "query": "..." } }

Ngoài các field trên, host có thể thêm project, team, principal + principal_token (chữ ký 60 giây, xem principal-token), piece + viewer (khi tool được gọi từ một mảnh của Nest), approval, read_only. Tool phải chấp nhận field lạ trong v1, từ chối api_version hoặc hook không hỗ trợ, và coi toàn bộ event và input là dữ liệu chưa đáng tin. tool.preflight là hook thứ hai, hỏi tool có chạy được lời gọi này không trước khi xin người duyệt; hook này không được thay đổi gì.

Muốn model nhìn thấy một ảnh tool vừa ghi vào workspace (ảnh chụp trình duyệt, biểu đồ), tool in ra JSON có thêm "show": ["tmp/shot.png"] ở cấp ngoài cùng. Host đọc từng đường dẫn trong workspace của cuộc trò chuyện rồi gắn ảnh vào chính kết quả đó. Như vậy model không mất thêm một lượt read. Host chỉ gắn file PNG, JPEG, GIF hoặc WebP, mỗi ảnh không quá 16 MB. Số ảnh không bị giới hạn (provider quyết định model đọc bao nhiêu), chỉ tổng dung lượng ảnh của một lời gọi không quá 64 MB; ảnh vượt quá được ghi tên trong kết quả. Đường dẫn tuyệt đối, .. và symlink ra ngoài workspace đều bị bỏ qua. Ảnh bị bỏ qua được ghi tên kèm lý do, còn lời gọi vẫn tính là thành công. Khi run_js gọi tool, chúng chỉ nhận lại phần text (internal/core/operations/show.go).

Phân giải đường dẫn và quyền

ĐiềuQuy tắc
run.program tương đốiPhân giải từ thư mục của pack khai báo; không thoát được bằng ..
Tên trần (bun, node)Tìm trong PATH của operator, chỉ cho operation đã được cấp. Pack chưa chọn không đòi dependency
Đường dẫn tuyệt đốiLà binding có chủ đích của operator, giảm tính portable
argv, thư mục chạy, environmentLấy từ config đã xác thực. Model không đổi được; stdin là kênh duy nhất cho input của model, và input không vào đường dẫn, argv hay env
Secret và envChỉ host cấp. Pack khai needs, host cấp bằng grants.packs. Tool không được đặt run.env (pack_tool_env)

Thứ tool không bao giờ nhận: prompt, lịch sử hội thoại, cấu hình provider và khóa API của model, nội dung database của Soot. Muốn gọi ngược runtime thì pack khai needs.runtime và nhận token hẹp (runtime của chính nó, không phải runtime khác). Muốn lưu dữ liệu thì dùng pack storage bên dưới.

Hiệu ứng: exit 0 là thành công. Lỗi, timeout hay kết quả không rõ được ghi vào effect journal. Cùng operation và input trong một run được replay từ receipt, không chạy lại. Kết quả không rõ giữ resource fence qua restart, operator kiểm tra trước khi thử lại. Đổi tên operation để né fence là sai. Tool chạy lâu khai run.background: true để dùng job của AgentCore (runtime.md). Receipt của job chưa phải kết quả: agent lấy kết quả bằng tool job (op wait hoặc status), và output tool stream ra khi chạy nền thành output trực tiếp của job. Subagent chỉ nhận năng lực mà AgentCore cho phép, không tự mở rộng quyền host đã cấp.

_[0.19.0]_ run.http là cách chạy thứ hai, cho công cụ do Soot hay đội tự viết (tools/<id>/tool.json) và cho tool trong pack.json. Nó không chạy chương trình nào: host gửi đúng một request HTTPS tới host viết sẵn trong URL và khai trong needs.hosts (không IP, không cổng, không đi theo redirect, qua client có guard của 2ai), chèn input vào chỗ đã đánh dấu và khóa ({{cred:NAME}}, chỉ trong header hay query) ngay trước khi gửi, rồi xoá khóa khỏi câu trả lời và lỗi trước khi ghi lại. Khóa của công cụ tự viết nằm trong vault theo (chủ, tên), tách khỏi khóa của pack; người nhập trong Nest, không ai đọc lại được. Công cụ write đi qua effect journal và chính sách duyệt như tool của pack. Trong pack.json, tool khai run: {http: {...}, mode} thay cho program, parameters là input schema, output.pick tùy chọn; pack khai host một lần trong needs.hosts, và khóa là khóa của pack như mọi tool khác (needs.credentials, nhập trong Kho khóa hay cấp qua grants.packs). mode: read chỉ là GET hay POST. Mảnh của pack gọi các tool này theo tên (data.queries, data.actions) và hỏi Soot phục vụ mảnh (data.ask). Hợp đồng: nest-extensions §14.

read_only: true nghĩa là host chỉ cho lượt chạy này đọc (ví dụ bản tin sáng của Lead), nên tool phải từ chối mọi thay đổi. case_id là field cũ, tùy chọn; core không tạo hay cấp case. Pack casework là ví dụ một workload dùng hợp đồng này mà không thêm vòng chạy hay kho case nào vào core.

Pack: những gì một pack mang theo

Pack khai báo thứ nó cung cấp và thứ nó cần. Nó không khai danh tính, prompt, route, trigger, lịch hay credential (mấy thứ này thuộc Soot definition và deployment; xem agents.md).

Phần trong pack.jsonTác dụngLớp
skills/<name>/SKILL.md, toolsKiến thức và hành động cho agent; skill mang tên trong frontmatter, không thêm tiền tố packcấp quyền theo pack
needsCredential, env, runtime mà tool đọchost cấp qua grants.packs
name, keywordsTên và từ khóa cho Nest. Id của pack là tên thư mụcchỉ hiển thị
interface.tool_areas, renderersNest vẽ vùng làm việc cho tool đã cấp (trình duyệt, canvas)chỉ hiển thị, không cấp thêm tool
interface.piecesMảnh HTML đặt vào slot của Nestchỉ hiển thị
interface.subjectThẻ "người này là ai" cho hội thoại kênhchỉ hiển thị
storageBảng riêng của packhost cấp phát và scope
programsChương trình pack cần cài trên máy (Chromium...)qua check_op/install_op
channel.platformsNền tảng chat mà binding có thể dùng, kèm form cài đặtchỉ hiển thị

Contract chi tiết: pack-manifest-ui, pieces, pack-storage.

Pack storage

Pack khai bảng riêng trong storage. Runtime tạo bảng khi một Soot chọn pack, và mỗi lần gọi tool cấp một token chỉ dùng cho lần đó, buộc vào (pack, soot, workspace): tool không tự chọn scope. Chỉ cho đổi cộng thêm; đổi phá bị từ chối và bản pack cũ vẫn chạy. Cột principal tự vào erasure. Pack không khai được trigger, view hay SQL thô, nên không mở rộng core sang schema của nó. Gỡ pack thì bảng bị ẩn 30 ngày rồi xóa.

Chia sẻ pack

Pack là thư mục tự chứa (không trỏ ra sibling, không symlink), cài bằng soot add từ Git hoặc archive có checksum. Cài không cấp quyền và không tự cập nhật. Pack dùng chung đi qua pull request vào Soot Forge, nơi release có checksum là nguồn cài mặc định của soot spawn. Pack có logic ở service riêng khai program: "soot" với soot tool-forward, để chạy được trên VM chỉ có binary soot; xem soot tool-forward --help.

Adapter và kênh chat

Adapter là process nói giao thức của một nền tảng. Ba điều giữ nó ngoài core:

  • Ingress thuộc về nền tảng. Deployment khởi động và gắn tài khoản. Cài hay chọn pack không bao giờ khởi động ingress.
  • Không có registry hay lớp phân phối adapter trong core, và không có dispatcher thứ hai.
  • Adapter là ống dẫn bền và ngu. Danh tính, admission, ghép đôi (pairing), ánh xạ hội thoại, nội dung gửi đi và mọi câu chữ người dùng thấy đều do host giữ.

Với kênh chat, hợp đồng là channel-adapter (channel-adapter.v1, các revision cộng thêm 1.1 đến 1.3). Binding khai trong deployment; runtime chạy adapter như process con có giám sát (argv cố định từ deployment, không từ pack hay model), cấp một token sca_ chỉ có hiệu lực trên /v1/channel/* của binding đó, và chỉ chuyển môi trường tối thiểu (không có khóa provider hay token operator). Adapter từ xa dựng bằng SDK TypeScript (./channel) nói cùng hợp đồng. Pack chỉ khai nền tảng nào có thể gắn (channel.platforms) và form cài đặt hiển thị trong Nest; secret nhập qua secret sheet vào vault, không vào pack.json. Mã host nằm ở internal/core/channel/.

Nest: mở rộng bằng registry

Nest là một super app: giao diện của nó là các mảnh ghép. Nest giữ khung: mảnh được đặt ở đâu, xếp thế nào, được đọc gì. Phần bên trong khung là mảnh, và mảnh có thể đến từ chính Nest, từ pack, hoặc từ một Soot hay một đội tự viết ra. Một màn hình có sẵn hôm nay chuyển được sang pack, và Soot thêm hay sửa được màn hình cho người nó làm việc cùng mà không cần phát hành Nest: nó ghi vài file, người đồng ý một lần, màn hình hiện. Người vận hành giữ quyền cuối: đặt, xếp, quay lại bản trước, gỡ. Nest chỉ mở khung khi sắp được nhìn thấy và cho nó nghỉ khi khuất, nên thêm mảnh không làm Nest nặng lên. Hướng dẫn từng bước cho từng loại tác giả là build-a-piece; chuẩn chung cho mọi loại mảnh (tên gọi, manifest, giao diện, cấu trúc, cách kiểm) là pieces; hợp đồng là nest-extensions.

Nest dựng rail, command palette (⌘K), Settings và Dữ liệu từ các registry trong desktop/src/app/registry/ (nest-registry v2). Không có chỗ nào trong Nest rẽ nhánh theo tên pack.

Màn hình riêng của Nest cũng là mảnh, khai qua cùng một manifest. Mỗi extension dựng sẵn nằm trong desktop/src/extensions/<id>/ và đăng ký một lần ở src/extensions/index.ts: inbox (Hộp việc: khu mở đầu trên rail, nơi vẽ slot home), workspace (tab mục tiêu, trình quản lý sản phẩm, Kết quả của một dự án) và support (tab Hỗ trợ). Shell không xử lý riêng id nào. Mảnh nào giữ slot home thì mảnh đó là vùng mở đầu.

Nest là SPA React + TypeScript + Vite trong Tauri 2 (desktop/), dùng @tofound/ui. Mỗi vùng chức năng là một thư mục src/modules/<feature>/; src/lib/ không import module hay UI; src/app/ ghép shell và registry. Dữ liệu từ runtime đi qua một adapter duy nhất, SootClient (src/lib/api/client.ts): TanStack Query cho phần đọc từ host, store kết nối cho hội thoại và SSE. Ở Tauri, Rust giữ credential và chuyển tiếp HTTP đã xác thực; webview không thấy token và không có proxy URL tùy ý. Phần đọc cấu hình, hiển thị và hành vi của pack đến từ catalog của runtime, không có bản sao quyền hay mặc định trong Nest.

Muốn thêmLàm gìCó đổi Nest không
Vùng chức năng lõi mới của NestThêm một AreaManifest (id, nhãn, icon, lazy loader, group)Có, đây là thay đổi core của Nest
Một màn hình trong rail, trang chủ, Dữ liệu hoặc Settings cho một nghiệp vụPack khai interface.pieces với slot rail, home, data.tab hoặc settingsKhông. Runtime liệt kê nó trong GET /v1/pieces với ref pack:<pack>:<id>
Một tab trong dự án (Hỗ trợ, Marketing, Nội dung)Mảnh slot: "project.tab" kèm tab {id, label} và teamsKhông. provides: ["flow-<id>"] cũ bị từ chối; link cũ flow-<id> mở tab <id>
Một màn hình Soot hay đội tự làm cho người nó làm việc cùngSoot ghi ui/<id>/index.html rồi ui/<id>/piece.json trong file của chính nó (written-pieces)Không. Lần đầu người được hỏi một lần; các bản sau tự lên, quay lại được
Một màn hình dựng sẵn của NestMảnh builtin trong một extension ở desktop/src/extensions/Có, nhưng chỉ ở extension đó; src/app/ không đổi
Cách vẽ một loại giao diện mớiPack khai renderers với bundle, Nest đóng khungKhông
Form cài đặt một nền tảng chatPack khai channel.platforms[].uiKhông
Nút cài chương trìnhPack khai programsKhông

Quy tắc của registry:

  • Rail, palette, deep link, lazy load và quyền xem được tính từ AreaManifest[]; Settings từ SettingsSection[]. presence: false nghĩa là không tab, không dòng palette, không link.
  • Entry của registry không cấp quyền. Nó vẽ những gì catalog và grants của host đã cho phép.
  • Mỗi mảnh của pack chỉ xuất hiện một lần trên mỗi runtime. Runtime chọn Soot phục vụ (served_by): Soot Lead nếu nó được cấp view tool của mảnh, không thì Soot đầu tiên theo id trong số Soot người xem vào được. teams là các đội có Soot chọn pack đó. Member chỉ thấy mảnh access: "member"; danh sách invalid (mảnh không Soot nào phục vụ được) chỉ operator thấy.
  • Nest đọc GET /v1/pieces trên mọi kết nối và gộp lại thành một danh sách theo thứ tự slot (order, rồi chủ mảnh, rồi id). Một mảnh là piece:<kết nối>:<ref>, nên cùng một ref trên hai máy chủ là hai mảnh, và trên rail là hai dòng, mỗi dòng ghi tên máy chủ.
  • Dự án lấy từ GET /v1/projects ({kind, items}), gộp theo id trên mọi kết nối. Tên gọi trên bộ chọn là kind.label, không có thì là "Dự án". Nếu runtime trả kind: null, danh sách rỗng, 404 hay 405, Nest coi như không có nguồn dự án: không bộ chọn, và các tab project.tab của runtime là tab chung của cả workspace. Nest không tự dựng dự án từ nhãn Soot hay từ GET /v1/workspace/summary.
  • Tab của một dự án là các mảnh project.tab (dựng sẵn lẫn runtime), gom theo tab.id, tên lấy từ mảnh đầu tiên. Mảnh của runtime là tab của dự án khi một trong các teams của nó là đội của dự án trên cùng kết nối. Một Soot làm cho dự án khi nó thuộc một đội của dự án, hoặc nhãn dữ liệu của nó trùng id dự án.
  • Shell Tauri chỉ gọi runtime qua runtime_request, với một allow-list khai báo trong desktop/src-tauri/src/runtime_routes.rs. Route ngoài danh sách bị chặn trước khi rời máy.

Mảnh và renderer

Mảnh chạy trong khung sandbox, CSP chặn gọi mạng và form, không có credential. (CSP chưa chặn được khung tự điều hướng; Nest đóng khung đã rời bundle, xem pieces.) Nó chỉ chạm runtime qua cầu postMessage v2: gửi call (mode view hoặc action), Nest chuyển thành POST /v1/pieces/{ref}/call và trả result. Phiên mở bằng POST /v1/pieces/{ref}/session, bundle tải từ GET /v1/pieces/{ref}/s/{pvs}/…. Nest bỏ message lạ và chỉ gửi call cho đúng ref của khung. Message init mang viewer {kind} và project (thay project/projects của v1).

  • view đọc; action ghi, cần request_id, gọi lại cùng id trả receipt chứ không chạy lại.
  • Tool chạy dưới tên Soot phục vụ, nhận piece {soot, piece, mode} và viewer trong envelope, với đúng grants và credential như mọi lần gọi khác của pack.
  • Tool cần duyệt bị từ chối trên mảnh (422 tool_refused, reason: "approval_required"), vì mảnh không có bước duyệt. Mảnh operator không hiện cho member.

Renderer của pack dùng cùng cầu và CSP. Với tool area cần stream (trình duyệt), host proxy khung hình qua runtime, không nhúng cửa sổ thật: nhúng không đi qua runtime từ xa (cách phần lớn Nest nối với Soot), macOS không có API nhúng cửa sổ process khác và Wayland cấm. Endpoint riêng của trình duyệt (cổng CDP, token, đường dẫn profile) không bao giờ tới client.

Bề mặt vận hành: MCP và REST

Operator MCP (mcp-operator) là một cách mở rộng khác: để agent ngoài (coding agent, một Soot khác) điều khiển Soot. Điểm cần nhớ:

  • Tool MCP được sinh từ registry ActionSpec và các read view, cộng tool view/action của mỗi mảnh (piece__<pack>__<id>__view). Không viết tay endpoint cho từng thứ.
  • Xác thực bằng token có scope (sop_, hiện một lần). Token host không dùng cho /v1/mcp.
  • Hành động chỉ người làm được (duyệt) gắn cờ PersonOnly trên route; token có scope luôn nhận 403. Mọi lời gọi đều vào audit.

Nghĩa là thêm một ActionSpec hoặc read view là tự động có mặt ở soot manage, trong Nest và trong MCP, cùng một transaction và cùng undo.

Không bao giờ đưa vào core

Đừng làmVì saoLàm gì thay
Endpoint riêng cho một workload (/v1/refunds/...)Mỗi workload trở thành API cố định, phải build lại, lệch khỏi nguyên tắc workload là configSkill + tool đã có (có thể qua builtin/toolbox), hoặc pack mới
Registry hay lớp phân phối adapterIngress thuộc nền tảng; core mà biết adapter nào thì thành người điều phốiProcess adapter do deployment khởi động, nói channel-adapter
Dispatcher thứ hai (hàng đợi task/case riêng)Hai bộ điều phối nghĩa là hai nguồn sự thật về ai làm gìViệc vào Soot trước; job và subagent dùng AgentCore
Cho "case", ticket hay worker thành điểm vào bắt buộcCase là bản ghi tùy chọn, bị động, không chặn event hay tự kích agentSoot nhận event; pack casework chỉ là tool để ghi
Vòng lặp, compactor, reviewer hay job manager riêngChỉ có một runtime agent, thuộc AgentCoreDùng AgentCore
import từ contrib/ hay pack trong code coreCore phải chạy khi không có workload nàoPack và repo sản phẩm giữ kiến thức ngành
Rẽ nhánh theo tên pack hoặc nền tảng trong core hay NestMỗi nhánh là một lần build lại cho mỗi pack mớiKhai trong pack.json (name, renderers, platforms)
Từ vựng ngành trong internal/, contract/, desktop/src/TestCoreIsCSFree chặn; core phục vụ nhiều loại công tyĐể trong pack
Nest chạy việc thay runtimeNest không làm việc của runtimeSửa runtime đích; xem runtime.md
Cấp quyền từ interfacetool_area, mảnh, renderer chỉ là hiển thịHost cấp bằng grants.packs

Hướng dẫn quyết định

Đi từ trên xuống, dừng ở dòng đầu tiên khớp.

Tôi muốn...Đặt ởGhi chú
Agent biết thêm một quy trình, chính sách, giọng điệuSkill (trong pack, hoặc SOUL.md/MISSION.md nếu là danh tính)Không code. description nói khi nào đọc
Agent làm được một việc có hiệu ứng (gọi API, ghi file, đăng bài)Tool trong packExecutable soot/v1, tên operation <pack>_<tool>, khai needs
Cùng skill và tool dùng cho nhiều Soot, bật/tắt một lầnPackPack là đơn vị chọn và cấp quyền
Pack cần nhớ dữ liệu riêngstorage của packKhông tự mở DB; không trigger, view, SQL
Nhận tin từ một nền tảng mớiAdapter (process), binding trong deploymentNói channel-adapter; pack chỉ khai channel.platforms
Người dùng cần màn hình xem hoặc thao tác dữ liệu của pack trong NestMảnh (interface.pieces)data.view_tool đọc, data.action_tool ghi, mọi quyền qua tool
Canvas hay giao diện sống cho một tool arearenderers của packChức năng stream/input theo capabilities, không theo kind
Chạy theo lịch, theo mục tiêu, giao việcConfig (schedule, task, goal)Thuộc deployment và workspace.md, không thuộc pack
Cho công cụ ngoài điều khiển SootMCP / REST với token scope; thêm ActionSpec nếu cần hành động mớiKhông viết endpoint tay
Tính năng Go dùng chung nhưng không bắt buộc (một kho dữ liệu, một route, một khối config)Feature package + hook Register* + dòng trong internal/compose/featuresĐặt package dưới internal/feature/; không cần sửa layers.json
Vùng chức năng lõi mới của NestAreaManifest mới trong registryKhông rẽ nhánh theo pack
Đổi vòng chạy agent, lưu hội thoại, xác thực, vaultCore changeĐi qua AgentCore trước; xem runtime.md

Nếu không dòng nào khớp mà bạn đang nghĩ đến "thêm endpoint" hay "thêm một dispatcher", dừng lại và hỏi lại: gần như chắc chắn đó là skill cộng tool.

Ví dụ: đối soát đơn hàng

Yêu cầu: một Soot đối soát đơn của cửa hàng với bảng sao kê ngân hàng, báo lệch trong Nest, và đăng cảnh báo lên Telegram.

  1. Kiến thức đối soát (quy tắc làm tròn, khi nào coi là lệch): skill reconcile.md trong pack reconcile.
  2. Đọc sao kê và đơn: hai tool fetch_orders, fetch_statements (run.mode: read), khai needs.credentials cho khóa API cửa hàng. Host cấp bằng soot grant reconcile.
  3. Ghi kết quả lệch: tool record_mismatch (mode: write) lưu vào storage của pack, bảng mismatches với cột order_id, delta, status (cột chữ có search: true).
  4. Xem trong Nest: interface.pieces có một mảnh slot: "data.tab", access: "operator", data.view_tool đọc mismatches, data.action_tool đánh dấu đã xử lý (có request_id). Không sửa dòng nào trong desktop/.
  5. Chạy hằng ngày: schedule trong deployment.json, trỏ vào Soot. Không worker mới.
  6. Cảnh báo Telegram: binding Telegram trong deployment; pack chat-channels đã có adapter. Pack reconcile không đụng đến nền tảng.
  7. Kiểm: soot check --show; test tool riêng với input đúng và sai; eval trong evals/ của Soot.

Số dòng Go thêm vào core: 0. Không build lại binary. Nếu sau này cần một mức quyền chưa có (ví dụ token MCP chỉ đọc bảng mismatches), đó mới là thay đổi core, và nó đi vào ActionSpec hoặc scope chứ không vào endpoint riêng.

Giới hạn và chưa có

  • conversation → monitoring/traces còn là hai cạnh core → feature được dung thứ, chờ tách conversation.
  • Không còn cạnh core → compose hay feature → compose: TestCoreLayering từ chối cả hai. core/runtime chạm kho trace, job và monitoring qua interface của core/ledger; core/management chạm bước nhận bundle và bước mở bản General của Forge qua hook trong core/configstate (scaffold đăng ký). Bản build không link internal/compose/scaffold từ chối deployment (bundle_admission_unavailable) và bản General (ErrNoGeneralOpener) thay vì bỏ qua kiểm tra; engine chưa gắn kho nào thì bỏ qua việc kho đó làm, như khi kho là nil.
  • Cơ chế mảnh ghép của nest-extensions chạy ở cả hai phía cho cả bốn loại chủ: mảnh dựng sẵn, mảnh của pack, mảnh Soot và đội tự viết (đề xuất có xem trước, lịch sử bản, quay lại, báo kết quả tải), cùng bố cục riêng của từng người. Còn thiếu: bố cục chưa đi theo người sang máy khác; mảnh tool-area chưa thay renderer; khung tự điều hướng chưa bị chặn từ gốc; tác giả chưa có lệnh kiểm và xem trước riêng. Danh sách đầy đủ ở pieces.
  • Chưa có SDK Go chính thức cho MCP; transport thuộc core và SDK, khi thêm, nằm sau cùng giao diện đó.
  • SDK TypeScript hiện lo envelope tool và client hội thoại; messaging và storage phía SDK còn dự kiến.
  • Một vài chỗ trong tài liệu cũ vẫn nhắc capabilities.<name> (như builtin/README.md); cấu hình hiện tại là phẳng, không còn capabilities.

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