@rong/agentscript 0.1.1 → 0.1.3

package/docs/cn/final-expression-return.md

@@ -0,0 +1,215 @@
+# AgentScript 隐式返回规范草案
+
+本文档描述 AgentScript 函数的隐式返回规则草案。
+
+## 1. 基本规则
+
+函数体最后一个顶层表达式可以作为函数返回值。
+
+```agentscript
+func answer(input) {
+    use input.question
+
+    generate({ input: "Answer the question" }) -> {
+        ok boolean
+        answer string
+    }
+}
+```
+
+等价于：
+
+```agentscript
+func answer(input) {
+    use input.question
+
+    return generate({ input: "Answer the question" }) -> {
+        ok boolean
+        answer string
+    }
+}
+```
+
+这个规则称为：
+
+```text
+final expression return
+```
+
+## 2. 可隐式返回的表达式
+
+允许最后一行隐式返回以下表达式形式：
+
+```text
+generate(...) -> shape
+普通函数调用
+agent 调用
+变量引用
+字段访问
+索引访问
+object literal
+list literal
+```
+
+例如：
+
+```agentscript
+func run(input) {
+    Worker(input)
+}
+```
+
+这条规则适用于所有表达式形式，包括调用表达式。被调用者解析为本地函数还是 agent 调用，都不影响 final expression return。例如，直接用 agent 名称调用另一个 agent 时，会调用该 agent 的 `main func`，其结果会被隐式返回：
+
+```agentscript
+agent Planner {
+    main func(input) {
+        generate({ input: "Create a plan" }) -> {
+            steps list[string]
+        }
+    }
+}
+
+agent Controller {
+    func run(input) {
+        Planner(input)
+    }
+}
+```
+
+```agentscript
+func get_result(result) {
+    result.value
+}
+```
+
+```agentscript
+func observe(action) {
+    {
+        facts: [action.summary],
+        source: action.source
+    }
+}
+```
+
+## 3. 不可隐式返回的语句
+
+下面这些不是表达式，不参与隐式返回：
+
+```text
+use 声明
+赋值语句
+import
+loop
+repeat
+for
+if/else，早期版本可先不表达式化
+```
+
+例如：
+
+```agentscript
+func bad(input) {
+    use input.question
+}
+```
+
+这里没有返回表达式，函数返回 `none`，或由 semantic analyzer 给出 warning。
+
+赋值也不返回：
+
+```agentscript
+func f() {
+    x = answer()
+}
+```
+
+如果要返回，需要写：
+
+```agentscript
+func f() {
+    x = answer()
+    x
+}
+```
+
+## 4. 显式 `return` 优先
+
+显式 `return` 仍然合法，并且在复杂控制流中推荐使用。
+
+```agentscript
+func answer(input) {
+    if input.dry_run {
+        return {
+            ok: false,
+            answer: "dry run"
+        }
+    }
+
+    generate({ input: "Answer" }) -> {
+        ok boolean
+        answer string
+    }
+}
+```
+
+## 5. 无返回值
+
+如果函数没有显式 `return`，最后一行也不是可返回表达式，则返回：
+
+```agentscript
+none
+```
+
+可以显式写：
+
+```agentscript
+return none
+```
+
+用于表达“此函数只产生副作用”。
+
+## 6. 推荐风格
+
+对于典型 LLM 调用，推荐省略 `return`：
+
+```agentscript
+func summarize(content) {
+    use content < 8k
+
+    generate({
+        input: "Summarize the content"
+        limit: 1000
+    }) -> {
+        title string
+        summary string
+        key_points list[string]
+    }
+}
+```
+
+对于分支、提前退出、错误处理，推荐使用显式 `return`：
+
+```agentscript
+func answer(input) {
+    if not input.question {
+        return {
+            ok: false,
+            answer: ""
+        }
+    }
+
+    use input.question
+
+    generate({ input: "Answer the question" }) -> {
+        ok boolean
+        answer string
+    }
+}
+```
+
+## 一句话定义
+
+```text
+A function returns the value of its final top-level expression when no explicit return is reached.
+```

package/docs/cn/language.md

@@ -27,7 +27,7 @@ main agent Assistant {
         question string
     }) {
         use input.question
-        return generate({ input: "Answer the question" }) -> {
+        generate({ input: "Answer the question" }) -> {
             ok boolean
             answer string
         }
@@ -138,7 +138,7 @@ func careful(input) {
 Shape 用于输入校验和 `generate` 输出校验：
 
 ```agentscript
-return generate({ input: "Extract facts" }) -> {
+generate({ input: "Extract facts" }) -> {
     ok boolean
     title string
     items list[json]
@@ -158,6 +158,8 @@ Shape 不是完整的静态类型系统。
 use input.question
 use Requirements < 4k
 use past_lessons < 2k
+use input.question as user
+use docs.summary < 4k as evidence
 ```
 
 ### 规则
@@ -167,17 +169,31 @@ use past_lessons < 2k
 - Memory 查询结果不会自动进入 prompt。
 - Trace 事件不会自动进入 prompt。
 - `use value < n` 应用上下文预算。
+- `use value as label` 为选中的 context source 附加字面标签。
+- `use value < n as label` 先应用预算，再附加标签。
 - `llm`、`tool`、`agent`、`memory` 绑定不能被 `use`。
 - 函数绑定不能被 `use`。
 - `use` 声明被子作用域继承。
 
+### Context label
+
+`as` 后面的 label 是字面标签文本，不是表达式，不会求值，也不会读取作用域中的变量。
+
+```agentscript
+use docs as evidence
+use docs.summary < 4k as retrieved evidence
+use input.question as user
+```
+
+即使当前作用域中存在名为 `evidence` 的变量，`as evidence` 也只是把 context section 标记为 `evidence`。Label 用于组织 prompt section 和 trace 输出；它不会改变 `system`、`user`、`assistant` 等 provider message role。
+
 ### 延迟求值
 
 `use expr < budget` 声明的是 context source，而不是当前值的快照。当 `generate` 构建 prompt 时，表达式会被重新求值。这意味着在 `use` 之后、`generate` 之前对变量的修改在生成时刻是可见的。
 
 ## Generate
 
-`generate` 调用当前模型，需要 `input` 指令和返回 shape。
+`generate` 调用当前模型，需要 `input` 指令。返回 shape 是可选的。
 
 ```agentscript
 answer = generate({
@@ -198,7 +214,8 @@ answer = generate({
 - `limit`：生成预算（数字或 `2k` 格式）。可选。
 - `attempts`：JSON 解析失败或 shape 不匹配时的重试次数。可选，默认 1。
 - `debug`：将完整 prompt 打印到 stderr。可选，默认 false。
-- `-> { ... }` 块声明期望的输出 shape。
+- 可选的 `-> { ... }` 块声明期望的输出 shape。
+- 不写 `-> { ... }` 时，`generate` 输出无约束：AgentScript 不会在 prompt 中加入返回 schema，不会要求 provider 使用结构化输出，也不会对返回值做类型强制转换或 shape 校验。
 - Provider 错误（认证、网络、超时、模型不存在）直接失败，不做重试。
 - Shape 校验包含类型强制转换（如 `"true"` -> `true`，`"42"` -> `42`）。
 
@@ -365,7 +382,7 @@ import file Config from "./config.json"
 func answer(input) {
     use Requirements < 4k
     use Config
-    return generate({ input: "Answer from the referenced file." }) -> {
+    generate({ input: "Answer from the referenced file." }) -> {
         ok boolean
         answer string
     }
@@ -417,7 +434,7 @@ main agent Controller {
             result = Executor({ goal: input.goal, step: step })
             results.add(result)
         }
-        return results.summary
+        results.summary
     }
 }
 ```