creating-taubyte-resources

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Creating Taubyte Resources

创建Taubyte资源

When to use

使用场景

"Add a domain / website / library / function / database / storage / messaging / service"
"Create an application for app-scoped resources"
Building out a project after
```
bootstrapping-taubyte-projects
```
Reviewing or scripting non-interactive resource creation

"添加域名/网站/库/函数/数据库/存储/消息服务/服务"
"为应用范围的资源创建应用"
在
```
bootstrapping-taubyte-projects
```
（初始化Taubyte项目）之后构建项目
审阅或编写非交互式资源创建脚本

Intent-first resource planning (agent behavior)

基于意图的资源规划（代理行为）

When a user asks to "create an app" (not just a resource), first infer the minimum Taubyte resource set required to make that app real, then create those resources with correct scope + wiring.

General heuristics:

Web app UI → create a website (project-scoped if needed or mentioned) + a domain (project-scoped if mentioned) and attach the site to the domain and path(s).
Persistent data → create a database (application-scoped if needed). create storage if needed ; choose only when implied by the intent.
UI ↔ data/API glue → create at least one HTTP function that reads/writes the database and returns JSON for the website to consume. Attach the function to the same domain when a same-origin
```
/api/...
```
pattern is implied.

Rules while doing this:

Prefer the fewest resources that satisfy the intent, but do not omit the glue (e.g. database without a function is usually not an "app").
Keep scopes correct: database/storage/messaging/service are application-scoped if needed or mentioned; website/domain are project-scoped if needed or mentioned.
Use match strings as stable wiring keys (database
```
match
```
, messaging channel, service protocol) and keep them consistent with Go calls and triggers (see enforcing-taubyte-constraints rule 16).

当用户要求“创建应用”（而非仅单个资源）时，首先推断让该应用可用所需的最小Taubyte资源集合，然后以正确的范围和关联方式创建这些资源。

通用启发式规则：

Web应用UI → 创建网站（若有需要或提及则设为项目范围）+ 域名（若提及则设为项目范围），并将网站关联到域名及对应路径。
持久化数据 → 创建数据库（若有需要则设为应用范围）。若有需要则创建存储；仅当意图明确暗示时才选择创建。
UI ↔ 数据/API衔接层 → 至少创建一个HTTP函数，用于读写数据库并返回JSON供网站调用。当暗示同源
```
/api/...
```
模式时，将函数关联到同一域名。

执行时需遵循的规则：

优先选择能满足意图的最少资源，但不可省略衔接层（例如，仅创建数据库通常不能构成一个“应用”）。
保持范围正确：数据库/存储/消息服务/服务若有需要或提及则为应用范围；网站/域名若有需要或提及则为项目范围。
使用匹配字符串作为稳定的关联键（数据库
```
match
```
、消息通道、服务协议），并确保其与Go调用和触发器一致（参见enforcing-taubyte-constraints规则16）。

Preconditions

前置条件

```
tau --defaults --yes json current
```
shows the correct Project (and the right Application, or none, depending on scope) — see selecting-taubyte-context.
Project has been created/imported — see bootstrapping-taubyte-projects.

```
tau --defaults --yes json current
```
显示正确的项目（以及对应的应用，或无应用，取决于范围）——参见selecting-taubyte-context。
项目已创建/导入——参见bootstrapping-taubyte-projects。

Scope rule (project vs application)

范围规则（项目 vs 应用）

Resource	Scope
`domain`	Project
`website`	Project
`library`	Project
`function` (HTTP)	Project (default) or Application
`application`	Project (creates the application)
`database`	Application
`storage`	Application
`messaging`	Application
`service`	Application

For app-scoped resources:

tau --defaults --yes select application --name <app>

first; for project-scoped, ensure no application is selected (

tau --defaults --yes clear application

资源	范围
`domain`	项目
`website`	项目
`library`	项目
`function` （HTTP）	项目（默认）或应用
`application`	项目（用于创建应用）
`database`	应用
`storage`	应用
`messaging`	应用
`service`	应用

对于应用范围的资源：先执行

tau --defaults --yes select application --name <app>

；对于项目范围的资源，确保未选择任何应用（执行

tau --defaults --yes clear application

）。

Domains

域名

Generated FQDN (Dream / quick demos)

生成FQDN（Dream/快速演示）

bash

tau --defaults --yes new domain <domain_name> \
  --generated-fqdn \
  --type auto \
  --description "<desc>"

Result: a random FQDN of the form

<random>.<universe>.localtau

bash

tau --defaults --yes new domain <domain_name> \
  --generated-fqdn \
  --type auto \
  --description "<desc>"

结果：生成一个格式为

<random>.<universe>.localtau

的随机FQDN。

Custom FQDN (remote, controlled hostname)

自定义FQDN（远程、可控主机名）

bash

tau --defaults --yes new domain <domain_name> \
  --fqdn <fqdn> \
  --type auto \
  --description "<desc>"

bash

tau --defaults --yes new domain <domain_name> \
  --fqdn <fqdn> \
  --type auto \
  --description "<desc>"

Some remotes:

*.gen.<cloud_fqdn>

and the project CID suffix

部分远程主机：

*.gen.<cloud_fqdn>

与项目CID后缀

Host policy can require that a generated-style hostname under *.gen.<cloud>
embed the last eight characters of the project’s canonical CID from tau query project <name> --json
→ id
. Compute:

python3 -c "s='<cid>'; print(s[-8:])"

. Omitting this substring breaks config-compile with errors like does not contain last 8 of project id
. When replacing a domain for this reason, reuse the same logical domain resource name (e.g.

generated

) if you can — so domains:
on websites/functions stay valid without mass YAML edits.

主机策略可能要求**

*.gen.<cloud>

下的生成式主机名必须嵌入项目规范CID的最后8个字符，该CID可通过
tau query project <name> --json
中的

id

字段获取。计算方式：
python3 -c "s='<cid>'; print(s[-8:])"
。若省略该子串，会导致配置编译失败，错误信息类似

does not contain last 8 of project id

。若因此需要替换域名，尽可能复用相同的逻辑域名资源名称**（例如

generated

）——这样网站/函数上的**

domains:

**配置无需大量YAML编辑即可保持有效。

Forbidden flag

禁用标志

Never pass

--generated-fqdn-prefix

(or

--g-prefix

) — it's not supported by policy. Use

--generated-fqdn

alone or use

--fqdn

with a controlled hostname.

切勿传递

--generated-fqdn-prefix

（或

--g-prefix

）——该参数不受策略支持。仅使用

--generated-fqdn

或搭配可控主机名使用

--fqdn

。

Websites

网站

bash

tau --defaults --yes new website <site_name> \
  --domains <domain_name> \
  --paths / \
  --template empty \
  --generate-repository \
  --repository-name tb_code_<project>_<site_name> \
  --private \
  --no-embed-token \
  --branch main

tau --defaults --yes import website <site_name>
tau --defaults --yes list websites

Notes:

```
--generate-repository
```
creates a separate GitHub repo for the website; pair with a deterministic
```
--repository-name
```
(recommended:
```
tb_code_<project>_<site>
```
).
After creation, run
```
import website
```
so the local clone appears under
```
<project>/websites/<repo>/
```
.
Author build content under
```
.taubyte/build.sh
```
writing to
```
/out
```
— see building-taubyte-websites.

To attach an existing website repo instead of generating one, use

--repository-name <fullname>

--repository-id <id>

and drop

--generate-repository

bash

tau --defaults --yes new website <site_name> \
  --domains <domain_name> \
  --paths / \
  --template empty \
  --generate-repository \
  --repository-name tb_code_<project>_<site_name> \
  --private \
  --no-embed-token \
  --branch main

tau --defaults --yes import website <site_name>
tau --defaults --yes list websites

注意事项：

```
--generate-repository
```
会为网站创建一个独立的GitHub仓库；建议搭配确定性的
```
--repository-name
```
（推荐格式：
```
tb_code_<project>_<site>
```
）。
创建完成后，运行
```
import website
```
使本地克隆出现在
```
<project>/websites/<repo>/
```
目录下。
在
```
.taubyte/build.sh
```
中编写构建内容并输出到
```
/out
```
目录——参见building-taubyte-websites。

若要关联现有网站仓库而非生成新仓库，使用

--repository-name <fullname>

或

--repository-id <id>

并移除

--generate-repository

参数。

Libraries

库

bash

tau --defaults --yes new library <lib_name> \
  --path /libraries/<lib_name> \
  --template empty \
  --generate-repository \
  --repository-name tb_code_<project>_<lib_name> \
  --private \
  --no-embed-token \
  --branch main

tau --defaults --yes import library <lib_name>
tau --defaults --yes list libraries

--path

is the path inside the library repo where sources live; it must match the actual layout in the cloned repo.

bash

tau --defaults --yes new library <lib_name> \
  --path /libraries/<lib_name> \
  --template empty \
  --generate-repository \
  --repository-name tb_code_<project>_<lib_name> \
  --private \
  --no-embed-token \
  --branch main

tau --defaults --yes import library <lib_name>
tau --defaults --yes list libraries

--path

是库仓库内部存放源码的路径；必须与克隆后仓库的实际布局一致。

HTTP functions

HTTP函数

bash

tau --defaults --yes new function <fn_name> \
  --type http \
  --method GET \
  --paths /<path> \
  --domains <domain_name> \
  --language Go \
  --source . \
  --memory 64MB \
  --timeout 30s \
  --call <ExportedHandler> \
  --template empty

Or use a known-good ping_pong template:

bash

tau --defaults --yes new function ping \
  --type http --method GET --paths /ping \
  --generate-domain \
  --language Go --source . \
  --memory 64MB --timeout 1s \
  --call ping \
  --template ping_pong --use-template

Function rules:

One function per (path, method) — never comma-separated methods.
```
--call
```
must equal a
```
//export <name>
```
symbol in the source.
For Go, edit the function root
```
empty.go
```
(next to
```
go.mod
```
) — never create a
```
lib/
```
tree or hand-author
```
main.go
```
.

bash

tau --defaults --yes new function <fn_name> \
  --type http \
  --method GET \
  --paths /<path> \
  --domains <domain_name> \
  --language Go \
  --source . \
  --memory 64MB \
  --timeout 30s \
  --call <ExportedHandler> \
  --template empty

或使用经过验证的ping_pong模板：

bash

tau --defaults --yes new function ping \
  --type http --method GET --paths /ping \
  --generate-domain \
  --language Go --source . \
  --memory 64MB --timeout 1s \
  --call ping \
  --template ping_pong --use-template

函数规则：

每个（路径、方法）对应一个函数——切勿使用逗号分隔多个方法。
```
--call
```
必须与源码中的
```
//export <name>
```
符号一致。
对于Go语言，编辑函数根目录下的
```
empty.go
```
（与
```
go.mod
```
同级）——切勿创建
```
lib/
```
目录或手动编写
```
main.go
```
。

Applications

应用

bash

tau --defaults --yes new application <app_name> \
  --description "<desc>"
tau --defaults --yes select application --name <app_name>
tau --defaults --yes list applications

bash

tau --defaults --yes new application <app_name> \
  --description "<desc>"
tau --defaults --yes select application --name <app_name>
tau --defaults --yes list applications

Databases (application-scoped)

数据库（应用范围）

bash

tau --defaults --yes new database <db_name> \
  --match <matcher> \
  --min 1 --max 2 \
  --size 1GB

Constraint observed:

--min 1 --max 1

fails with

min(1) cannot be greater than max(1)

. Use

--min 1 --max 2

(or higher max).

The

--match

value is the runtime key: Go code must call

database.New("<matcher>")

with the identical string (including any leading

bash

tau --defaults --yes new database <db_name> \
  --match <matcher> \
  --min 1 --max 2 \
  --size 1GB

需遵守的约束：

--min 1 --max 1

会失败，错误信息为

min(1) cannot be greater than max(1)

。请使用

--min 1 --max 2

（或更大的max值）。

--match

的值是运行时键：Go代码必须使用完全相同的字符串（包括前导

）调用

database.New("<matcher>")

。

Storage (application-scoped)

存储（应用范围）

bash

tau --defaults --yes new storage <storage_name> \
  --match <matcher> \
  --size 1GB \
  --bucket Object \
  --public

bash

tau --defaults --yes new storage <storage_name> \
  --match <matcher> \
  --size 1GB \
  --bucket Object \
  --public

Messaging (application-scoped)

消息服务（应用范围）

bash

tau --defaults --yes new messaging <msg_name> \
  --match <channel_match> \
  --mqtt --ws

The

<channel_match>

is the channel string. Producers in Go call

pubsub/node

Channel("<channel_match>")

, and PubSub-triggered functions set

trigger.channel: <channel_match>

bash

tau --defaults --yes new messaging <msg_name> \
  --match <channel_match> \
  --mqtt --ws

<channel_match>

是通道字符串。Go中的生产者调用

pubsub/node

的

Channel("<channel_match>")

，而PubSub触发的函数需设置

trigger.channel: <channel_match>

。

Services (application-scoped)

服务（应用范围）

bash

tau --defaults --yes new service <svc_name> \
  --protocol /api

On Git Bash / MSYS, prefix path-like flags with

MSYS_NO_PATHCONV=1

to avoid path mangling.

bash

tau --defaults --yes new service <svc_name> \
  --protocol /api

在Git Bash/MSYS中，需为类路径的标志添加前缀

MSYS_NO_PATHCONV=1

以避免路径被篡改。

Workflow checklist for a typical project

典型项目的工作流检查清单

Resource creation progress:
- [ ] Verify selection (tau --json current)
- [ ] Create domain (project scope)
- [ ] Create website + import (project scope)
- [ ] Create library + import (project scope)
- [ ] Create application
- [ ] Select application
- [ ] Create database / storage / messaging / service
- [ ] Create functions (HTTP at project scope, others at app scope as needed)
- [ ] tau clear application
- [ ] tau push project --config-only --message "..."
- [ ] Wait for config build success before pushing website/library code

资源创建进度：
- [ ] 验证当前选择（tau --json current）
- [ ] 创建域名（项目范围）
- [ ] 创建网站并导入（项目范围）
- [ ] 创建库并导入（项目范围）
- [ ] 创建应用
- [ ] 选择应用
- [ ] 创建数据库/存储/消息服务/服务
- [ ] 创建函数（HTTP函数设为项目范围，其他函数按需设为应用范围）
- [ ] 执行tau clear application
- [ ] 执行tau push project --config-only --message "..."
- [ ] 等待配置构建成功后再推送网站/库代码

Gotchas

常见陷阱

Dream vs CLI vs remote WASM paths:
```
tau new function ... --source .
```
with an application selected may scaffold under code/applications/<app>/functions/<fn>/
in your clone, while Dream or remote builders often expect code/<app>/functions/<fn>/
(no
```
applications/
```
segment). A remote job may fail with couldn't find
.taubyte
under
```
.../<app>/functions/<fn>
```
while your tree still has
```
.../applications/<app>/functions/<fn>
```
. Treat the path in the first failing build log as ground truth and move the function directory (and fix any relative references) so
```
.taubyte/
```
sits where the builder looks — do not guess a different layout.
Application bleed: forgetting
```
tau clear application
```
causes later
```
tau new domain|website|library
```
to land in the app instead of project scope.
Matcher = runtime string:
```
match
```
in YAML must equal the literal Go calls (
```
database.New("...")
```
,
```
pubsubnode.Channel("...")
```
,
```
trigger.channel
```
). Mismatched leading
```
/
```
is a frequent cause of "open failed" / silent producers.
Repo strategy must be explicit for websites/libraries — either
```
--generate-repository
```
with a deterministic
```
--repository-name
```
, or
```
--repository-name
```
/
```
--repository-id
```
for an existing repo.

Don't hand-edit domain YAML. Always use

tau new domain

tau delete domain

tau query domain

Min/max on database:
```
--min
```
must be strictly less than
```
--max
```
.

Dream vs CLI vs 远程WASM路径差异：当已选择应用时，执行
```
tau new function ... --source .
```
可能会在克隆仓库的**
```
code/applications/<app>/functions/<fn>/
```
目录下生成脚手架，而Dream或远程构建器通常期望路径为
```
code/<app>/functions/<fn>/
```
（无
applications/
目录）。远程任务可能会失败，错误信息为couldn't find
```
.taubyte
```
** under
```
.../<app>/functions/<fn>
```
，而本地目录结构仍为
```
.../applications/<app>/functions/<fn>
```
。请以首次构建失败日志中的路径为准，移动函数目录（并修复所有相对引用），使
```
.taubyte/
```
位于构建器期望的位置——切勿猜测其他目录结构。
应用范围泄漏：忘记执行
```
tau clear application
```
会导致后续的
```
tau new domain|website|library
```
命令将资源创建在应用范围内而非项目范围内。
匹配符 = 运行时字符串：YAML中的
```
match
```
必须与Go调用中的字面字符串完全一致（
```
database.New("...")
```
、
```
pubsubnode.Channel("...")
```
、
```
trigger.channel
```
）。前导
```
/
```
不匹配是导致“打开失败”/生产者静默失败的常见原因。
网站/库的仓库策略必须明确——要么使用
```
--generate-repository
```
搭配确定性的
```
--repository-name
```
，要么使用
```
--repository-name
```
/
```
--repository-id
```
关联现有仓库。
请勿手动编辑域名YAML。请始终使用
```
tau new domain
```
/
```
tau delete domain
```
/
```
tau query domain
```
进行操作。
数据库的min/max约束：
```
--min
```
必须严格小于
```
--max
```
。

creating-taubyte-resources

Original

Translation

Creating Taubyte Resources

创建Taubyte资源

When to use

使用场景

Intent-first resource planning (agent behavior)

基于意图的资源规划（代理行为）

Preconditions

前置条件

Scope rule (project vs application)

范围规则（项目 vs 应用）

Domains

域名

Generated FQDN (Dream / quick demos)

生成FQDN（Dream/快速演示）

Custom FQDN (remote, controlled hostname)

自定义FQDN（远程、可控主机名）

Some remotes: *.gen.<cloud_fqdn> and the project CID suffix

部分远程主机：*.gen.<cloud_fqdn>与项目CID后缀

Forbidden flag

禁用标志

Websites

网站

Libraries

库

HTTP functions

HTTP函数

Applications

应用

Databases (application-scoped)

数据库（应用范围）

Storage (application-scoped)

存储（应用范围）

Messaging (application-scoped)

消息服务（应用范围）

Services (application-scoped)

服务（应用范围）

Workflow checklist for a typical project

典型项目的工作流检查清单

Gotchas

常见陷阱

Related skills

相关技能

Some remotes:
`*.gen.<cloud_fqdn>`
and the project CID suffix

部分远程主机：
`*.gen.<cloud_fqdn>`
与项目CID后缀