@rong/agentscript 0.1.0 → 0.1.2

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

@@ -0,0 +1,197 @@
+# 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)
+}
+```
+
+```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

@@ -1,6 +1,6 @@
 # AgentScript 语言参考
 
-本文档描述 AgentScript v1.0.0 的当前语言规范。
+本文档描述 AgentScript v0.1.x 的当前语言规范。
 
 ## 设计原则
 
@@ -27,11 +27,9 @@ main agent Assistant {
         question string
     }) {
         use input.question
-        return generate({ input: "Answer the question" }) {
-            return {
-                ok boolean
-                answer string
-            }
+        generate({ input: "Answer the question" }) -> {
+            ok boolean
+            answer string
         }
     }
 }
@@ -140,13 +138,11 @@ func careful(input) {
 Shape 用于输入校验和 `generate` 输出校验：
 
 ```agentscript
-return generate({ input: "Extract facts" }) {
-    return {
-        ok boolean
-        title string
-        items list[json]
-        meta json
-    }
+generate({ input: "Extract facts" }) -> {
+    ok boolean
+    title string
+    items list[json]
+    meta json
 }
 ```
 
@@ -181,7 +177,7 @@ use past_lessons < 2k
 
 ## Generate
 
-`generate` 调用当前模型，需要 `input` 指令和返回 shape。
+`generate` 调用当前模型，需要 `input` 指令。返回 shape 是可选的。
 
 ```agentscript
 answer = generate({
@@ -189,12 +185,10 @@ answer = generate({
     limit: 800
     attempts: 3
     debug: true
-}) {
-    return {
-        ok boolean
-        answer string
-        reason string
-    }
+}) -> {
+    ok boolean
+    answer string
+    reason string
 }
 ```
 
@@ -204,7 +198,8 @@ answer = generate({
 - `limit`：生成预算（数字或 `2k` 格式）。可选。
 - `attempts`：JSON 解析失败或 shape 不匹配时的重试次数。可选，默认 1。
 - `debug`：将完整 prompt 打印到 stderr。可选，默认 false。
-- `return { ... }` 块声明期望的输出 shape。
+- 可选的 `-> { ... }` 块声明期望的输出 shape。
+- 不写 `-> { ... }` 时，`generate` 输出无约束：AgentScript 不会在 prompt 中加入返回 schema，不会要求 provider 使用结构化输出，也不会对返回值做类型强制转换或 shape 校验。
 - Provider 错误（认证、网络、超时、模型不存在）直接失败，不做重试。
 - Shape 校验包含类型强制转换（如 `"true"` -> `true`，`"42"` -> `42`）。
 
@@ -371,11 +366,9 @@ import file Config from "./config.json"
 func answer(input) {
     use Requirements < 4k
     use Config
-    return generate({ input: "Answer from the referenced file." }) {
-        return {
-            ok boolean
-            answer string
-        }
+    generate({ input: "Answer from the referenced file." }) -> {
+        ok boolean
+        answer string
     }
 }
 ```
@@ -425,7 +418,7 @@ main agent Controller {
             result = Executor({ goal: input.goal, step: step })
             results.add(result)
         }
-        return results.summary
+        results.summary
     }
 }
 ```
@@ -466,7 +459,7 @@ main agent Controller {
 
 ## 非目标
 
-AgentScript v1.0.0 不包含：
+AgentScript v0.1.x 不包含：
 
 - 通用工作流引擎。
 - 通用并行执行语法。

package/docs/design-history/v0-design.md

@@ -20,7 +20,7 @@ V0 支持：
 - Agent 内函数、变量赋值、对象/列表字面量、成员访问、函数调用。
 - `model`、`role`、`description` 作用域配置。
 - `use` 上下文声明和 `< n` 上下文预算。
-- `generate({ input, limit, attempts, debug }) { return { ... } }` LLM 调用。
+- `generate({ input, limit, attempts, debug }) -> { ... }` LLM 调用。
 - `if` / `else`，`==`、`!=`、`and`、`or`、`not`。
 - `loop until condition < n` 有上限循环。
 - `repeat * n` 有上限重复执行。
@@ -50,17 +50,15 @@ main agent ResearchAgent {
         question string
     }) {
         use input.question
-        return answer(input.question)
+        answer(input.question)
     }
 
     func answer(question) {
         use question
 
-        return generate({ input: "Answer the question" }) {
-            return {
-                ok boolean
-                text string
-            }
+        generate({ input: "Answer the question" }) -> {
+            ok boolean
+            text string
         }
     }
 }
@@ -105,10 +103,8 @@ agent A {
         model Strong
         description "Use a stronger model for this function."
 
-        return generate({ input: "Answer carefully" }) {
-            return {
-                text string
-            }
+        generate({ input: "Answer carefully" }) -> {
+            text string
         }
     }
 }
@@ -134,13 +130,11 @@ V0 运行时数据以 JSON 为核心：
 `generate` 返回 shape 使用轻量标注：
 
 ```agentscript
-return generate({ input: "Extract facts" }) {
-    return {
-        facts list[string]
-        source string
-        meta json
-        ok boolean
-    }
+generate({ input: "Extract facts" }) -> {
+    facts list[string]
+    source string
+    meta json
+    ok boolean
 }
 ```
 
@@ -155,11 +149,9 @@ func compose(question, scratch) {
     use question
     use scratch.summary < 2k
 
-    return generate({ input: "Answer using only the context" }) {
-        return {
-            ok boolean
-            text string
-        }
+    generate({ input: "Answer using only the context" }) -> {
+        ok boolean
+        text string
     }
 }
 ```
@@ -175,19 +167,17 @@ func compose(question, scratch) {
 
 ## Generate
 
-`generate({ input, limit, attempts, debug }) { return { ... } }` 表示一次 LLM call。`input` 是本次 call 的最后用户指令，可以是字符串、对象或其它 JSON 值。`limit`、`attempts`、`debug` 都是可选参数。
+`generate({ input, limit, attempts, debug }) -> { ... }` 表示一次 LLM call。`input` 是本次 call 的最后用户指令，可以是字符串、对象或其它 JSON 值。`limit`、`attempts`、`debug` 都是可选参数。
 
 ```agentscript
 answer = generate({
     input: "Answer using collected facts"
     limit: 800
     attempts: 3
-}) {
-    return {
-        ok boolean
-        text string
-        error string
-    }
+}) -> {
+    ok boolean
+    text string
+    error string
 }
 ```
 
@@ -198,7 +188,7 @@ answer = generate({
 - `limit` 是本次 LLM call 的预算，支持 `800` 或 `2k` 这类 budget 字面量。
 - `attempts` 表示最多生成次数；它不是额外重试次数。
 - `debug` 是 boolean，缺省值为 `false`；为 `true` 时 runtime 将完整 prompt 打印到 stderr。
-- 块内 `return { ... }` 描述 LLM 输出 JSON shape，不会从外层函数返回。
+- `-> { ... }` 描述 LLM 输出 JSON shape，不会从外层函数返回。
 - LLM 输出会先按 shape 做有限容错转换。
 - 当输出不是 JSON 或转换后仍不符合 shape，且 `attempts > 1` 时，下一次调用会把上一次输出和错误信息附加到 `input` 后，请模型 repair。
 - provider 网络、认证、超时、模型不存在等基础设施错误不会被 repair 重试。

package/docs/design-history/v0-implement.md

@@ -1,6 +1,6 @@
 # AgentScript V0 Implement
 
-本文档是 V0 阶段的历史实现快照。语言设计见 `v0-design.md`。当前 v1.0.0 的实现入口和模块概览见 `../en/language.md` 与 `../cn/language.md`。
+本文档是 V0 阶段的历史实现快照。语言设计见 `v0-design.md`。当前 v0.1.x 的实现入口和模块概览见 `../en/language.md` 与 `../cn/language.md`。
 
 ## 执行管线
 
@@ -92,7 +92,7 @@ V0 AST 节点：
 - `main agent { ... }` 映射为匿名入口 Agent，内部名 `__main_agent`。
 - `main func(input) { ... }` 映射为匿名入口函数，内部名 `__main`。
 - `AgentName(input)` 是普通 `CallExpr`，语义和运行时把它解析为目标 Agent 的 `main func` 调用。
-- `generate({ input: "...", limit: 500 }) { return { ... } }` 把生成预算保存在 `GenerateExpr` options 中。
+- `generate({ input: "...", limit: 500 }) -> { ... }` 把生成预算保存在 `GenerateExpr` options 中。
 - `use value < 2k` 的预算在 `UseStmt` 上。
 - `loop until done < 6` 的 `< 6` 是循环上限，不是比较表达式。
 
@@ -198,7 +198,7 @@ V0 的预算裁剪按字符数实现：`2k` 约等于 2000 字符。这是当前
 
 ```ts
 interface ToolProvider {
-  call(request: ToolCallRequest): Promise<RuntimeValue>;
+    call(request: ToolCallRequest): Promise<RuntimeValue>;
 }
 ```
 

package/docs/design-history/v1-design.md

@@ -113,10 +113,8 @@ for item in list < n {
 V1 不需要专门的 `plan` 类型。推荐结构：
 
 ```agentscript
-return generate({ input: "Create a short executable plan" }) {
-    return {
-        steps list[json]
-    }
+generate({ input: "Create a short executable plan" }) -> {
+    steps list[json]
 }
 ```
 
@@ -280,11 +278,9 @@ func answer(input) {
     use Requirements < 4k
     use input.question
 
-    return generate({ input: "Answer from the referenced file" }) {
-        return {
-            ok boolean
-            text string
-        }
+    generate({ input: "Answer from the referenced file" }) -> {
+        ok boolean
+        text string
     }
 }
 ```

package/docs/design-history/v2-design.md

@@ -210,15 +210,13 @@ agent Reflector {
     main func(input) {
         use input
 
-        return generate({
+        generate({
             input: "Extract one reusable lesson from this run.",
             attempts: 3
-        }) {
-            return {
-                insight string
-                mistake string
-                next_rule string
-            }
+        }) -> {
+            insight string
+            mistake string
+            next_rule string
         }
     }
 }
@@ -270,12 +268,10 @@ main agent Learner {
         result = generate({
             input: "Answer the goal using relevant past lessons.",
             attempts: 3
-        }) {
-            return {
-                ok boolean
-                answer string
-                reason string
-            }
+        }) -> {
+            ok boolean
+            answer string
+            reason string
         }
 
         reflection = reflect({
@@ -290,19 +286,17 @@ main agent Learner {
             ok: result.ok
         })
 
-        return result
+        result
     }
 
     func reflect(run) {
         use run
 
-        return generate({
+        generate({
             input: "Extract one reusable lesson from this run.",
             attempts: 3
-        }) {
-            return {
-                insight string
-            }
+        }) -> {
+            insight string
         }
     }
 }

package/docs/en/context-engineering.md

@@ -8,13 +8,13 @@ AgentScript has variables, functions, loops, and agent calls, but its primary pu
 
 AgentScript's control flow serves prompt context construction.
 
-Ordinary statements organize data, call tools, call agents, and update intermediate state. LLM calls happen only through `generate(...) { return ... }`, and the context visible to `generate` must be declared explicitly with `use`.
+Ordinary statements organize data, call tools, call agents, and update intermediate state. LLM calls happen only through `generate(...) -> { ... }`, and the context visible to `generate` must be declared explicitly with `use`.
 
 The core objects are:
 
 - **Data**: ordinary variables, JSON values, lists, file imports, tool observations, agent return values.
 - **Context Source**: a prompt context origin declared by `use expr < budget`.
-- **Generation Site**: an LLM call declared by `generate({ input, limit, attempts, debug }) { return shape }`.
+- **Generation Site**: an LLM call declared by `generate({ input, limit, attempts, debug }) -> shape`.
 - **Boundary**: context visibility boundaries formed by agent, function, and block scopes.
 
 ## Semantics of `use`
@@ -30,15 +30,13 @@ func answer(question, scratch) {
     use question
     use scratch.summary < 2k
 
-    return generate({
+    generate({
         input: "Answer the question using collected facts"
         limit: 800
-    }) {
-        return {
-            ok boolean
-            text string
-            error string
-        }
+    }) -> {
+        ok boolean
+        text string
+        error string
     }
 }
 ```
@@ -57,10 +55,8 @@ main func(input) {
     scratch.add({ fact: "A" })
     scratch.add({ fact: "B" })
 
-    return generate({ input: "Answer from scratch" }) {
-        return {
-            text string
-        }
+    generate({ input: "Answer from scratch" }) -> {
+        text string
     }
 }
 ```
@@ -103,15 +99,13 @@ Each function call creates an independent context boundary.
 ```agentscript
 func caller(input) {
     use input.goal
-    return helper(input)
+    helper(input)
 }
 
 func helper(input) {
     use input.detail
-    return generate({ input: "Work on detail" }) {
-        return {
-            ok boolean
-        }
+    generate({ input: "Work on detail" }) -> {
+        ok boolean
     }
 }
 ```
@@ -145,10 +139,8 @@ Blocks (`if`, `repeat`, `loop`, `for`) create child scopes. `use` declarations i
 if condition {
     temp = compute(input)
     use temp
-    result = generate({ input: "Use temp" }) {
-        return {
-            ok boolean
-        }
+    result = generate({ input: "Use temp" }) -> {
+        ok boolean
     }
 }
 ```
@@ -205,11 +197,9 @@ Source labels help models understand context and help humans audit prompts.
 Comes from the `input` field of `generate(...)` options.
 
 ```agentscript
-generate({ input: "Answer the question using only collected facts" }) {
-    return {
-        ok boolean
-        text string
-    }
+generate({ input: "Answer the question using only collected facts" }) -> {
+    ok boolean
+    text string
 }
 ```
 
@@ -217,10 +207,10 @@ The instruction is the per-call task. `limit`, `attempts`, and `debug` are local
 
 ### Output contract
 
-Comes from `return { ... }` shape.
+Comes from the optional `-> { ... }` shape on a `generate` expression.
 
 ```agentscript
-return {
+generate({ input: "Answer" }) -> {
     ok boolean
     text string
     error string