6.8 KiB
常用标准库真实签名
下列签名随 skill 版本维护，参数按位置传入；括号里的输出名也是类型化多输出/Worker/wire 合同的一部分。这里只列常用子集，不复制完整语言手册。每段 signatures 对应同名官方 library 包，维护者用根 test/skill_examples.py 核对公开声明。
文本与数字
text.trim(value: Text) (result: Text)
text.lower(value: Text) (result: Text)
text.upper(value: Text) (result: Text)
text.at(value: Text, index: Int) (result: Text?)
text.slice(value: Text, start: Int, end: Int) (result: Text?)
text.contains(value: Text, pattern: Text) (result: Bool)
text.starts_with(value: Text, prefix: Text) (result: Bool)
text.ends_with(value: Text, suffix: Text) (result: Bool)
text.split(value: Text, separator: Text) (result: List<Text>)
text.replace(value: Text, pattern: Text, replacement: Text) (result: Text)
text.join(values: List<Text>, separator: Text) (result: Text)
int.parse(value: Text) (result: Int?)
int.to_text(value: Int) (result: Text)
decimal.parse(value: Text) (result: Decimal?)
decimal.round(value: Decimal, places: Int) (result: Decimal)
decimal.from_int(value: Int) (result: Decimal)
decimal.to_text(value: Decimal) (result: Text)
float.parse(value: Text) (result: Float?)
float.from_int(value: Int) (result: Float)
uuid.parse(value: Text) (result: Uuid?)
uuid.to_text(value: Uuid) (result: Text)
dever.id.from_text(text: Text) (id: Id)
dever.id.to_text(id: Id) (text: Text)
Int/Decimal/Float/Uuid parse 失败返回 null，必须用互斥分句处理；不要假定解析失败是 0，也不要把 Uuid、Id 和各 Model 的名义 id 混用。Text 索引按 Unicode 标量值；slice 为起点含、终点不含。
Bytes、时间与密码
dever.bytes.from_text(text: Text) (bytes: Bytes)
dever.bytes.to_text(bytes: Bytes) (text: Text)
dever.bytes.from_ints(values: List<Int>) (bytes: Bytes)
dever.bytes.length(bytes: Bytes) (length: Int)
dever.bytes.at(bytes: Bytes, index: Int) (value: Int?)
dever.bytes.slice(bytes: Bytes, start: Int, end: Int) (result: Bytes)
dever.bytes.concat(left: Bytes, right: Bytes) (bytes: Bytes)
dever.time.now() (output: DateTime)
dever.time.parse_datetime(text: Text) (output: DateTime) pure
dever.time.format_datetime(value: DateTime) (output: Text) pure
dever.time.parse_date(text: Text) (output: Date) pure
dever.time.format_date(value: Date) (output: Text) pure
dever.time.duration(millis: Int) (output: Duration) pure
dever.time.add(value: DateTime, duration: Duration) (output: DateTime) pure
dever.time.subtract(value: DateTime, duration: Duration) (output: DateTime) pure
dever.time.difference(later: DateTime, earlier: DateTime) (output: Duration) pure
dever.crypto.password_hash(password: Secret) (value: Text)
dever.crypto.password_verify(password: Secret, hash: Text) (value: Bool)
dever.crypto.token(bytes: Int) (value: Secret)
dever.crypto.sha256(bytes: Bytes) (value: Bytes) pure
dever.crypto.hmac_sha256(key: Secret, bytes: Bytes) (value: Bytes) pure
dever.crypto.constant_time_eq(left: Bytes, right: Bytes) (equal: Bool) pure
与数字 parse 不同，时间 parse 直接返回 DateTime/Date，非法输入传播对应 DateTimeResult.Failed / DateResult.Failed；format 失败属于 TextResult。Bytes.to_text 的非法 UTF-8 传播 DecodeResult.Failed；from_ints/slice 传播 BufferResult.Failed。密码调用分别传播 HashResult/VerifyResult，token 传播 TokenResult；这些 choice 位于调用所在标准包，完整捕获使用 result(call) 和成功/失败分句。不要用普通 Text 打印 Secret。密码 hash/verify 在 blocking(...) 中执行且不能处于数据库事务内；真正写入放显式短 transaction 并重验状态。
JSON、HTTP 与日志
dever.json.parse(source: Text) (document: dever.json.value.Document)
dever.json.stringify(document: dever.json.value.Document) (text: Text)
dever.json.node(document: dever.json.value.Document, id: Int) (result: dever.json.value.Value?)
dever.json.property(document: dever.json.value.Document, id: Int, name: Text) (result: Int?)
dever.http.default_limits() (result: Limits)
dever.http.send(address: Text, port: Int, request: Request, limits: Limits) (response: Response)
dever.log.info(message: Text, fields: Map<Text, Text>) ()
dever.log.warn(message: Text, fields: Map<Text, Text>) ()
dever.log.error(message: Text, fields: Map<Text, Text>) ()
HTTP 签名的 Limits/Request/Response 是 dever.http 包类型。Request 字段为 method: Text、target: Text、headers: List<dever.http.Header>、body: Bytes；Header 为 name: Text、value: Bytes；Response 为 status: Int、headers、body。send 返回成功 Response，失败传播 ResponseResult.Failed；它是 Adapter 内的外部 I/O，不是 App 内直接请求外网的入口。自动 HTTP API 使用 App 的 wire 合同，无需拼 Request/Response。JSON parse 返回的 Document 是带 root/nodes 的类型化树，不是任意 Map；普通 API/CMD 直接使用自动 codec。
日志是同步阻塞能力；已推断为挂起的数据库 App/Job 内通过 blocking(dever.log.info(...)) 调用，示例见 Job 的 store。不要将编译器要求的边界改成吞掉日志或数据库错误。
请求与权限
dever.api.request_id() (id: Text)
dever.api.header(name: Text) (value: Text?)
dever.api.set_header(name: Text, value: Text) ()
dever.auth.id() (value: Text)
dever.auth.session() (value: Text)
dever.auth.permissions() (values: List<Permission>)
dever.auth.save_role(id: Text, name: Text, all_permissions: Bool, permission_keys: List<Text>) ()
dever.auth.disable_role(role_id: Text) ()
dever.auth.issue_cookie(subject: Text, session: Text, tenant: Text?) ()
dever.auth.clear_cookie() ()
dever.site.key() (value: Text)
Permission 是 dever.auth.Permission，字段 key/component/domain/site/action/method 均为 Text。身份读取、权限管理、请求 Header/Cookie 的入口限制仍适用，签名存在不代表任意角色可调用。敏感 Header 不能经普通 header 当 Text 读取。
以下是编译器专有操作，不按普通 library 声明中的 Int 适配桩推断业务类型：dever.auth.user_id() / tenant_id() 的结果分别是 verify Identity 对应的名义 Model ID 可空值；grant_role(user_id, role_id) / revoke_role(user_id, role_id) 的 user_id 必须是该站点的 User Model ID。不要为通过类型检查转换成裸 Int。
dever.job.enqueue(job.name, payload, key) 返回 Id，key 为 Text；零 payload Job 为 enqueue(job.name, key)。enqueue_at 在末尾增加 DateTime。普通测试中的 dever.test.drain_jobs(limit: Int) 返回 Int，advance_clock(millis: Int) 无输出；完整声明与调用见 Job 项目。这些静态操作不需要 import，也不能用动态字符串替代 Job 目标。