Giải thích Manifest

manifest.yaml là contract khai báo giữa app và SotaAgents: app là gì, đóng góp gì, backend ở đâu, native module nào được load và hỗ trợ platform version nào. Server luôn validate lại; manifest từ client không phải authority. Property lạ bị từ chối thẳng — chạy sota manifest schema để đọc đúng JSON Schema và sota manifest explain contributes.tools để giải thích một field.

Năm field gốc manifestSchemaVersion, appId, version, publisher và contributes là bắt buộc. Còn lại đều tùy chọn.

manifestSchemaVersion: 3
appId: my-first-project-demo
version: 1.0.0
displayName: "My First Project Demo"
description: "SotaAgent app."
publisher:
  id: local-dev
  displayName: "Local Dev"
  contact: dev@local-dev.example

contributes:
  skills:
    - name: example
      description: Example content-backed skill.
      appendsTo: system
      content: src/skills/example
      timeoutMs: 3000
      failure_mode: skip
  tools:
    - name: example
      description: Example tool that echoes its input and verified tenant context.
      route: POST /tools/example
      inputSchema: src/schemas/tool-input.schema.json
      outputSchema: src/schemas/tool-output.schema.json
      timeoutMs: 15000
      failure_mode: abort
  ui:
    - id: admin-screen
      kind: nativeModule
      surface: page
      slot: admin.workspace.tab
      sectionId: my-first-project-demo
      label: Admin screen
      route: /admin/*
      module:
        entry: dist/ui/app.js
        export: AdminScreen
        styles: dist/ui/app.css

service:
  baseUrl: https://my-first-project-demo.example.com
health:
  url: https://my-first-project-demo.example.com/health
  intervalSeconds: 60
platform: ^1.2.0
locales:
  default: en
  files:
    en: src/locales/en.json

• Identity ổn định; coi appId là public identifier vĩnh viễn.
• Version bất biến theo artifact; đổi bytes sau deploy phải tăng version.
• Contributions là toàn bộ surface nền tảng được phép expose.
• Environment overlay là override tùy chọn mang đúng tên local, stg hoặc prod. Root service là hosted default; local dành cho sota dev. Global --origin chọn deployment SotaAgents, còn -e ở từng command chọn profile/overlay tương ứng.

Mỗi native UI surface và public runtime API được hướng dẫn trên một trang riêng sau phần manifest này.

service:
  baseUrl: https://my-app.example.com
health:
  url: https://my-app.example.com/health
  intervalSeconds: 60

environments:
  local:
    service:
      baseUrl: http://127.0.0.1:8787
    health:
      url: http://127.0.0.1:8787/health
  stg:
    service:
      baseUrl: https://stg.my-app.example.com
  prod:
    service:
      baseUrl: https://my-app.example.com

Khai báo một tool#

Tool là cách trợ lý chạm tới backend của bạn. Bạn khai báo nó một lần dưới contributes.tools; nền tảng suy ra mọi thứ còn lại từ khai báo đó — model được mời gọi gì, request route ra sao, authenticate thế nào, và được phép chạy bao lâu. Schema là schema đóng, nên một key không khai báo sẽ fail validation.

File schema mà khai báo trỏ tới là JSON Schema bình thường. Compiler resolve và inline chúng vào artifact, nên file được tham chiếu phải tồn tại trước khi build hay deploy, kể cả khi route đó không được gọi lúc test local.

// src/schemas/tool-input.schema.json
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "message": {
      "type": "string",
      "minLength": 1,
      "maxLength": 4000,
      "description": "Message for the example tool to echo."
    }
  },
  "required": ["message"]
}

Khai báo bất kỳ tool nào cũng khiến service trở thành bắt buộc — nền tảng phải biết gửi request đi đâu. Tên tool phải duy nhất trong một manifest, và UI contribution có surface: tool-view phải liệt kê trong toolNames những tên thực sự tồn tại trong contributes.tools; validator từ chối renderer gắn với tool bạn chưa khai báo. Hai app đã cài không được cùng giành một tên tool cho renderer — app vào sau mất các tên bị tranh chấp.

Về những gì nền tảng làm tiếp với khai báo này — tên model nhìn thấy, signed request, contract của response — xem Triết lý kiến trúc.