@rong/agentscript 0.1.3 → 0.1.5

package/docs/cn/language.md

@@ -150,16 +150,18 @@ generate({ input: "Extract facts" }) -> {
 
 Shape 不是完整的静态类型系统。
 
+对象字面量使用 JSON-like 语法：字段写作 `key: value`，多字段之间必须用逗号分隔。
+
 ## 显式上下文（`use`）
 
 `use` 选择在当前作用域及其子作用域中，后续 `generate` 可以包含哪些变量的值。
 
 ```agentscript
 use input.question
-use Requirements < 4k
-use past_lessons < 2k
+use Requirements max 4k
+use past_lessons max 2k
 use input.question as user
-use docs.summary < 4k as evidence
+use docs.summary max 4k as evidence
 ```
 
 ### 规则
@@ -168,9 +170,9 @@ use docs.summary < 4k as evidence
 - 工具输出不会自动进入 prompt。
 - Memory 查询结果不会自动进入 prompt。
 - Trace 事件不会自动进入 prompt。
-- `use value < n` 应用上下文预算。
+- `use value max n` 应用上下文预算。
 - `use value as label` 为选中的 context source 附加字面标签。
-- `use value < n as label` 先应用预算，再附加标签。
+- `use value max n as label` 先应用预算，再附加标签。
 - `llm`、`tool`、`agent`、`memory` 绑定不能被 `use`。
 - 函数绑定不能被 `use`。
 - `use` 声明被子作用域继承。
@@ -181,7 +183,7 @@ use docs.summary < 4k as evidence
 
 ```agentscript
 use docs as evidence
-use docs.summary < 4k as retrieved evidence
+use docs.summary max 4k as retrieved evidence
 use input.question as user
 ```
 
@@ -189,7 +191,9 @@ use input.question as user
 
 ### 延迟求值
 
-`use expr < budget` 声明的是 context source，而不是当前值的快照。当 `generate` 构建 prompt 时，表达式会被重新求值。这意味着在 `use` 之后、`generate` 之前对变量的修改在生成时刻是可见的。
+`use expr max budget` 声明的是 context source，而不是当前值的快照。当 `generate` 构建 prompt 时，表达式会被重新求值。这意味着在 `use` 之后、`generate` 之前对变量的修改在生成时刻是可见的。
+
+完整设计语义见 [`use ... as ...`](./use-as.md)。
 
 ## Generate
 
@@ -197,9 +201,9 @@ use input.question as user
 
 ```agentscript
 answer = generate({
-    input: "Answer using the selected context."
-    limit: 800
-    attempts: 3
+    input: "Answer using the selected context.",
+    max_output: 800,
+    attempts: 3,
     debug: true
 }) -> {
     ok boolean
@@ -211,14 +215,19 @@ answer = generate({
 ### 语义
 
 - `input`：每次生成的指令。必填。
-- `limit`：生成预算（数字或 `2k` 格式）。可选。
-- `attempts`：JSON 解析失败或 shape 不匹配时的重试次数。可选，默认 1。
+- `max_output`：输出生成预算（数字或 `2k` 格式）。可选。
+- `attempts`：JSON 解析失败或 shape 不匹配时的尝试次数。它是包含第一次调用在内的最大总尝试次数。可选，默认 1。
+- `temperature`：provider sampling hint。可选。不支持的 provider hint 默认在 debug mode 下 warn，否则 ignore。
+- `think`：provider/model reasoning hint。可选。不支持的 provider hint 默认在 debug mode 下 warn，否则 ignore。
+- `strict`：控制 shape validation 是否严格。可选，默认 false。
 - `debug`：将完整 prompt 打印到 stderr。可选，默认 false。
 - 可选的 `-> { ... }` 块声明期望的输出 shape。
-- 不写 `-> { ... }` 时，`generate` 输出无约束：AgentScript 不会在 prompt 中加入返回 schema，不会要求 provider 使用结构化输出，也不会对返回值做类型强制转换或 shape 校验。
+- 不写 `-> { ... }` 时，`generate` 输出无约束：AgentScript 不会在 prompt 中加入返回 schema，不会要求 provider 使用结构化输出，也不会对返回值做类型强制转换或 shape 校验。自由形式的 `generate` 是允许的，但不推荐用于 agent workflow。
 - Provider 错误（认证、网络、超时、模型不存在）直接失败，不做重试。
 - Shape 校验包含类型强制转换（如 `"true"` -> `true`，`"42"` -> `42`）。
 
+Prompt 构造、identity、retry 和 trace 语义见 [`generate`](./generate.md)。
+
 ## 控制流
 
 ### If / else
@@ -231,14 +240,14 @@ if answer.ok and not input.dry_run {
 }
 ```
 
-支持的运算符：`==`、`!=`、`and`、`or`、`not`。`<` 不是通用比较运算符——它只能用于预算和循环上限。
+支持的运算符：`==`、`!=`、`<`、`and`、`or`、`not`。Context budget 和循环上限使用 `max`，因此 `<` 恢复为类似 `==` 的普通比较运算符。
 
 ### Loop until
 
 ```agentscript
 done = false
 
-loop until done < 6 {
+loop until done max 6 {
     observation = observe(input)
     done = observation.ok
 }
@@ -262,7 +271,7 @@ repeat * 3 {
 ### For in
 
 ```agentscript
-for step in plan.steps < 12 {
+for step in plan.steps max 12 {
     result = Executor(step)
     results.add(result)
 }
@@ -282,7 +291,7 @@ summary = items.summary
 - `list[index]` 只读。index 必须是非负整数。
 - `list.add(value)` 修改原列表。恰好接受一个参数。
 - `.length` 返回列表长度。
-- `.summary` 返回列表的 JSON-safe 运行时视图。它不是 LLM 生成的摘要，也不是语义压缩；如果需要控制 prompt 大小，应通过 `use scratch.summary < 2k` 这类显式 context budget 裁剪。
+- `.summary` 返回列表的 JSON-safe 运行时视图。它不是 LLM 生成的摘要，也不是语义压缩；如果需要控制 prompt 大小，应通过 `use scratch.summary max 2k` 这类显式 context budget 裁剪。
 
 ## 工具
 
@@ -300,9 +309,9 @@ import tool Http from "https://api.example.com"
 
 ```agentscript
 files = Find.run({
-    path: "."
-    name: "*.ts"
-    type: "file"
+    path: ".",
+    name: "*.ts",
+    type: "file",
     max: 50
 })
 ```
@@ -311,9 +320,9 @@ files = Find.run({
 
 ```agentscript
 matches = Grep.run({
-    path: "src"
-    pattern: "TODO"
-    include: "*.ts"
+    path: "src",
+    pattern: "TODO",
+    include: "*.ts",
     max: 100
 })
 ```
@@ -322,8 +331,8 @@ matches = Grep.run({
 
 ```agentscript
 lines = Sed.run({
-    path: "src/main.as"
-    start: 1
+    path: "src/main.as",
+    start: 1,
     max: 20
 })
 ```
@@ -331,10 +340,21 @@ lines = Sed.run({
 ### File
 
 ```agentscript
-content = File.read({ path: "README.md" })
-entries = File.list({ path: "src" })
-result = File.write({ path: "output.md", content: "# Result" })
-result = File.patch({ path: "file.as", search: "old", replace: "new" })
+content = File.read({
+    path: "README.md"
+})
+entries = File.list({
+    path: "src"
+})
+result = File.write({
+    path: "output.md",
+    content: "# Result"
+})
+result = File.patch({
+    path: "file.as",
+    search: "old",
+    replace: "new"
+})
 result = File.undo(effects)
 ```
 
@@ -343,14 +363,24 @@ result = File.undo(effects)
 ### Env
 
 ```agentscript
-home = Env.get({ name: "HOME" })
+home = Env.get({
+    name: "HOME"
+})
 ```
 
 ### Http
 
 ```agentscript
-response = Http.get({ url: "/api/data", headers: { Authorization: "Bearer ..." }, timeout: 10000 })
-response = Http.post({ url: "/api/submit", body: { key: "value" }, timeout: 10000 })
+response = Http.get({
+    url: "/api/data",
+    headers: { Authorization: "Bearer ..." },
+    timeout: 10000
+})
+response = Http.post({
+    url: "/api/submit",
+    body: { key: "value" },
+    timeout: 10000
+})
 ```
 
 HTTP 请求限制在 import URI 的 origin 内。
@@ -380,7 +410,7 @@ import file Requirements from "./requirements.md"
 import file Config from "./config.json"
 
 func answer(input) {
-    use Requirements < 4k
+    use Requirements max 4k
     use Config
     generate({ input: "Answer from the referenced file." }) -> {
         ok boolean
@@ -395,18 +425,18 @@ func answer(input) {
 
 ```agentscript
 Lessons.add({
-    kind: "lesson"
-    text: reflection.insight
+    kind: "lesson",
+    text: reflection.insight,
     goal: input.goal
 })
 
 past = Lessons.query({
-    kind: "lesson"
-    text: input.goal
+    kind: "lesson",
+    text: input.goal,
     limit: 5
 })
 
-use past < 2k
+use past max 2k
 ```
 
 ### 规则
@@ -430,8 +460,11 @@ main agent Controller {
     main func(input) {
         plan = Planner(input)
         results = []
-        for step in plan.steps < 10 {
-            result = Executor({ goal: input.goal, step: step })
+        for step in plan.steps max 10 {
+            result = Executor({
+                goal: input.goal,
+                step: step
+            })
             results.add(result)
         }
         results.summary

package/docs/cn/use-as.md

@@ -0,0 +1,225 @@
+# `use ... as ...`
+
+本文档定义 AgentScript 中 `use` 如何选择 prompt context，包括 context label、budget、scope 可见性、延迟求值和 trace 要求。
+
+整体模型见 [Context Engineering](./context-engineering.md)。Prompt 构造和输出契约见 [`generate`](./generate.md)。
+
+## 目的
+
+`use` 不是变量读取、赋值或命名空间导入。它声明一个 prompt context source。
+
+```agentscript
+use input.question as user question
+use scratch.summary max 2k as observations
+```
+
+含义是：
+
+```text
+让这个 source 对当前作用域及子作用域中后续的 generate 可见
+```
+
+没有被 `use` 选择的局部变量不会进入 prompt。
+
+## 语法
+
+```agentscript
+use expr
+use expr max budget
+use expr as label
+use expr max budget as label
+```
+
+固定顺序是：
+
+```text
+选择什么 -> 限制多少 -> 作为何种上下文
+```
+
+示例：
+
+```agentscript
+use input.question as user question
+use docs.summary max 4k as retrieved evidence
+use scratch.summary max 2k as observations
+```
+
+## Context label
+
+`as` 后面的 label 是字面标签文本，不是表达式，不会求值，也不会读取作用域中的变量。
+
+```agentscript
+use docs as evidence
+use docs.summary max 4k as retrieved evidence
+use input.question as user
+```
+
+即使当前作用域中存在名为 `evidence` 的变量，`as evidence` 也只是把 context section 标记为 `evidence`。
+
+Label 影响：
+
+- prompt section label
+- trace display
+- context organization
+- debug 和 audit 可读性
+
+Label 不影响：
+
+- agent identity
+- provider message role
+- tool 权限
+- system/user/assistant 权限
+
+## Provider role 不是 context label
+
+`system`、`user`、`assistant`、`tool` 等 provider role 是 LLM API 的传输协议细节。AgentScript context label 是 prompt 内部组织标签。
+
+为避免和 provider role 混淆，以下 label 保留：
+
+```text
+system
+assistant
+tool
+developer
+```
+
+`user` 允许作为 context label，因为它常用于表达“这段 context 是用户输入”。它仍然不会创建单独的 provider `user` message。
+
+## 延迟求值
+
+`use expr` 声明的是 source，不是快照。表达式会在可见的 `generate` 构建 prompt 时求值。
+
+```agentscript
+main func(input) {
+    scratch = []
+    use scratch.summary max 2k as observations
+
+    scratch.add({ fact: "A" })
+    scratch.add({ fact: "B" })
+
+    generate({ input: "Answer from observations" }) -> {
+        text string
+    }
+}
+```
+
+该 `generate` 能看到两个 fact。
+
+这让 `use` 保持为 context contract，而不是一次值复制。
+
+## Scope 可见性
+
+`use` 声明对同一作用域和子作用域中后续的 `generate` 可见。
+
+```agentscript
+use input.question as user question
+
+if input.needs_detail {
+    use input.detail as detail
+    generate({ input: "Answer with detail" }) -> {
+        text string
+    }
+}
+```
+
+内部 `generate` 可以看到 `user question` 和 `detail`。`detail` context 不会泄漏到 block 外部。
+
+Function 和 Agent 调用形成独立 context boundary。Callee 不会自动继承 caller 选择的 context。
+
+## 不能 use 什么
+
+Runtime capability 不能进入 prompt context：
+
+- imported tool
+- imported LLM/model binding
+- imported agent binding
+- memory handle
+- function binding
+- provider URI 和 workspace/runtime 配置
+
+非法示例：
+
+```agentscript
+use Search
+use Qwen
+use Worker
+use helper
+```
+
+应改为使用这些 capability 返回的数据：
+
+```agentscript
+results = Search.search(input.question)
+use results max 4k as search results
+```
+
+## Budget 语义
+
+`use expr max budget` 是 context item budget，限制该 source 渲染进 prompt 的大小。
+
+```agentscript
+use docs.summary max 4k as evidence
+```
+
+这不同于 `generate({ max_output: ... })` 的 output generation budget。详见 [`generate`](./generate.md)。
+
+## Prompt 渲染
+
+带 label 的 context item 渲染为 context section：
+
+```text
+Context:
+[user question]
+source: input.question
+What is AgentScript?
+
+[observations]
+source: scratch.summary
+[
+  { "fact": "..." }
+]
+```
+
+如果没有 label，renderer 可以使用数字 context index，并单独显示 source expression。
+
+## Trace 要求
+
+`use` trace event 记录声明信息：
+
+```json
+{
+  "kind": "use",
+  "data": {
+    "source": "scratch.summary",
+    "label": "observations",
+    "budget": { "amount": 2, "unit": "k" }
+  }
+}
+```
+
+`generate` 的 built context item 记录解析后的值和渲染元数据：
+
+```json
+{
+  "index": 0,
+  "source": "scratch.summary",
+  "label": "observations",
+  "value": [{ "fact": "A" }],
+  "text": "[...]",
+  "budget": { "amount": 2, "unit": "k" },
+  "clipped": false
+}
+```
+
+Trace 必须让 source、label、budget、clipping 状态和 resolved value 可审计。
+
+## 设计检查清单
+
+修改 `use` 前，应检查：
+
+- 未使用的数据是否仍然不会进入 prompt？
+- source 是否仍在 `generate` 时求值？
+- label 是否仍是字面文本，而不是表达式？
+- provider role 是否仍与 context label 分离？
+- budget 是否仍附着在 context item 上，而不是整个 generation 上？
+- function 和 Agent boundary 是否仍能阻止 context 泄漏？