# 术语与标识符指南

> 核验版本：1.1.0；通道：stable；文档 ID：reference.glossary

命令要求名称、slug、ID 或 token 时，可在这里核对含义。看起来相似的值不能互换，人类可读标签不证明身份或权限。完整运行模型见[核心概念](../overview/concepts.md)。

## 对象与生命周期

| 术语 | 含义 | 不要混淆为 |
| --- | --- | --- |
| 实例 | Viat 部署及其平台状态，多个服务进程可以共享数据库。 | 项目，或桌面应用本地保存的实例条目。 |
| 项目 | 资产、协作者及公开 API 的命名空间。 | 独立服务进程或业务终端用户账号。 |
| Slug | 项目 URL 身份，例如 `hello-lab`。 | 显示名称、UUID 或访问凭据。 |
| 平台数据库 | 保存 Viat 平台状态的 PostgreSQL。 | 项目中保存业务数据的 PostgreSQL/SQLite 资源。 |
| 资源 | 可复用连接、配置或能力，带公开配置和类型特定秘密。 | 已自动创建的远端数据库、运行中的触发器或已发布端点。 |
| 脚本 | 有名称、语言、元数据和推导/声明契约的源码或可执行产物。 | 无需发布就自动开放的 HTTP 路由。 |
| 工作流 | 使用实际支持步骤类型的命名编排定义。 | 持久外部任务引擎、审批队列或端点目录。 |
| 端点树 | 带挂载和继承设置的命名路由层次。 | 文件系统目录树或工作流图。 |
| 端点节点 | 目录或可调用节点，带路径片段、方法/目标和契约。 | 脚本名或已发布快照 ID。 |
| 草稿 | 当前可编辑状态，由适用的测试/直接运行路径使用。 | 对调用者生效的已发布契约。 |
| 快照 | 对外分发选择的端点/目标捕获状态。 | 所有资源凭据、导入或外部数据的备份。 |
| 发布 revision | 将变更成组记录的项目发布历史。 | 单个端点快照或脚本源码版本。 |
| Build / 环境 | 准备依赖或编译产物。 | 发布成功或业务执行成功的证明。 |
| 触发器 | HTTP 请求或已配置的调度、文件、聊天、队列、WS 事件源，调用支持的目标。 | 每个资源自动附带的运行属性。 |
| 异步 run | 有状态和 run ID 的平台执行。 | 外部调度器 job ID，或请求被接受就证明完成。 |
| 执行记录 | 请求/结果元数据，适用时包括拒绝和缓存命中。 | 工作进程确实运行过的证明。 |
| 行日志 | 关联执行的 stdout/stderr/结构化输出。 | 永久审计或备份存储。 |
| 业务审计 | 已配置业务数据操作的变更证据。 | 任意外部工具进行的每一次数据库写入。 |
| 响应缓存 | 按端点 key/策略保存的 HTTP 响应。 | 脚本依赖缓存或必然最新的数据库状态。 |
| `uses:` | Python/TypeScript 源码依赖声明。 | 安装包 requirements 或资源声明。 |
| `(live)` | 显式实时依赖行为；没有此标记时，普通已发布脚本依赖图可以冻结。 | 所有工作流步骤导入都会冻结的保证；步骤仍有实时解析例外。 |

## 身份与角色

| 术语 | 作用域与用途 |
| --- | --- |
| 平台用户 | 登录控制台、CLI、原生管理应用；平台角色控制平台管理。 |
| 项目协作者 | 平台用户在某个项目中的独立成员身份，角色为 owner/admin/developer/operator。 |
| Editor / publisher | 文档中的能力简称：editor 通常指项目 owner/admin/developer，publisher 指 owner/admin；各 API 的例外仍需单独遵守。 |
| 项目终端用户（`p-user`） | 业务 API 消费者身份，创建后不会获得控制台访问权。 |
| 项目角色（`viat role`） | 业务身份/授权角色，不是 `viat project member` 分配的协作者角色。 |
| Authorizer / 认证器 | 端点接受的调用者认证方式，最近一层显式列表替换祖先列表。 |
| 授权门禁（`authz_gates`） | 端点的 subject 级门禁，祖先累积，直到 override 停止向上遍历。 |
| Authz type/action/rule | 门禁和对象/行检查使用的业务授权模型词汇，不能任意替代平台成员关系。 |
| Principal | 执行所关联的身份，不等于编辑该脚本的操作人员。 |
| PAT（`vis_pat_`） | 平台个人访问凭据，有独立 scope、到期、撤销规则；不是 MFA 登记 ticket。 |
| API key（`vsk_`） | 与适用认证器共同使用的项目调用凭据；短 key ID 不是一次性完整秘密。 |
| Overview token（`vso_`） | 按登录签发、只读、单一路由的概览凭据，不是通用项目 API token。 |
| MFA ticket | 登录/登记的短期续接凭据，属于秘密，不代表已经完成登录。 |

## 命令到底要求哪种标识？

| 标识 | 获取与使用 |
| --- | --- |
| Folder/name | 脚本/资源/工作流的资产身份，保留文件夹，例如 `shared/lookup`；API folder query 编码与 CLI 限定名不同。 |
| 端点节点 UUID | 从创建/list/show 得到，用于 update/publish/unpublish/delete，不是端点路径。 |
| Request ID | 关联执行/请求与日志查询。文档占位 UUID 语法有效，但不指向真实执行。 |
| Execution log ID | 执行记录的数据库/API 身份，仅用于明确要求它的入口，不能悄悄替换为 request ID。 |
| Snapshot ID/version | 端点发布版本身份，不能用于要求项目 publish revision 的位置。 |
| Run ID | 平台异步运行标识，只通过对应 run API 轮询/取消。 |
| External job ID | 上游集群/服务返回的标识，需持久化，并用于上游自己的状态/取消 API。 |
| File ID | 受管存储元数据身份，不必等于文件系统路径、对象 key 或下载授权。 |

只从正确实例和项目复制 ID，并为临时示例保留对象归属清单。清理目标应是自己实际创建的对象，不是文档中打印的合成 UUID。

## 相近词，不同保证

- **Test：** 可能是本地夹具验证、真实草稿执行或资源连接探针，执行前核对副作用。
- **Success：** 可能表示传输接受、构建接受、运行成功、提供商接受或设备送达，见[错误与结果](errors.md)。
- **Rollback：** 恢复特定版本化对象，不恢复迁移或外部副作用。
- **Cancel：** 请求停止 Viat 执行，不自动取消已投递外部任务。
- **Delete：** 按依赖检查移除目标平台对象，不撤销所有外部凭据，也不抹除已发消息。
- **Stable：** 指目标已发布能力；**preview：** 可以指未发布能力或尚未完成的手册验收。判断可用性前阅读[版本说明](versions.md)。

查阅本术语表无需账号，也不产生网络请求。字段、权限和操作专属恢复方式应看对应功能/CLI 参考，不要把定义当作执行授权。