@rong/agentscript 0.1.2 → 0.1.4

package/docs/cn/context-engineering.md

@@ -1,146 +1,69 @@
 # AgentScript Context Engineering
 
-本文档说明 AgentScript 中 `use`、作用域和 `generate` 的核心设计含义。这个概念不属于某个特定版本，而是 AgentScript 区别于普通编程语言的基础语义。
+本文档是 AgentScript context engineering 的总纲。它说明 AgentScript 为什么存在、必须维护哪些边界，以及 `use ... as ...` 和 `generate` 两篇细化文档如何配合。
 
-AgentScript 表面上有变量、函数、循环和 Agent 调用，但它的主要目标不是成为通用编程语言，而是提供一种可审计、可组合、显式的 prompt context engineering DSL。
+AgentScript 有变量、函数、循环、工具、memory 和 Agent 调用，但它的目标不是成为通用编程语言，而是让 prompt context 显式、作用域化、类型化、可追踪、可审计。
 
-后续开发涉及 `use`、scope、context builder、trace 或 prompt 结构时，应优先参考本文档。若实现细节与本文不一致，应先判断是实现尚未跟上设计，还是本文需要更新。
+## 文档结构
 
-## 核心定位
+Context engineering 设计拆成三篇：
 
-AgentScript 的控制流服务于 prompt context 构建。
-
-普通语句负责组织数据、调用工具、调用 Agent 和更新中间状态。LLM 调用只能通过 `generate(...) -> { ... }` 发生，而 `generate` 能看到的上下文必须由 `use` 显式声明。
-
-AgentScript 的核心对象是：
-
-- `Data`：普通变量、JSON、list、file import、tool observation 和 Agent 返回值。
-- `Context Source`：由 `use expr < budget` 声明的 prompt context 来源。
-- `Generation Site`：由 `generate({ input, limit, attempts, debug }) -> shape` 声明的一次 LLM 调用。
-- `Boundary`：由 Agent、function 和 block scope 形成的 context 可见性边界。
-
-## `use` 的语义
-
-`use` 不是普通编程语言中的变量读取，也不是把变量导入某个命名空间。`use` 的含义是：
-
-> 在当前作用域声明一个 prompt context source，使后续在该作用域内可见的 `generate` 可以把该 source 的值放入 prompt context。
-
-例如：
-
-```agentscript
-func answer(question, scratch) {
-    use question
-    use scratch.summary < 2k
-
-    generate({
-        input: "Answer the question using collected facts"
-        limit: 800
-    }) -> {
-        ok boolean
-        text string
-        error string
-    }
-}
-```
-
-这里 `question` 和 `scratch.summary` 是本次 `generate` 的显式 context source。没有被 `use` 的局部变量不应自动进入 prompt。
-
-## `use` 应是延迟求值的 context source
-
-目标语义是：
-
-> `use expr < budget` 声明的是 `expr` 这个 context source，而不是立即复制 `expr` 的当前值。真正构建 prompt 时，应在 `generate` 执行点解析该 source 的当前值。
-
-因此，下面的程序应让 `generate` 看到更新后的 `scratch.summary`：
-
-```agentscript
-main func(input) {
-    scratch = []
-    use scratch.summary < 2k
-
-    scratch.add({ fact: "A" })
-    scratch.add({ fact: "B" })
-
-    generate({ input: "Answer from scratch" }) -> {
-        text string
-    }
-}
-```
-
-设计理由：
-
-- `use` 表达的是 context contract，而不是一次普通赋值。
-- Agent 常见模式会持续更新 scratch、plan、observations。
-- 如果 `use` 是快照，用户必须在每个 `generate` 前重复声明，容易造成陈旧 context。
-- 延迟求值更符合 context engineering 中“声明可见源，在调用点构建 prompt”的直觉。
+- **Context Engineering**：本文，总览核心模型和不变量。
+- **[`use ... as ...`](./use-as.md)**：说明如何选择数据作为 prompt context，label 如何工作，budget 如何应用，以及 scope 如何影响可见性。
+- **[`generate`](./generate.md)**：说明 generation site、prompt 构造、agent identity、输出契约、预算、重试和 trace。
 
-实现上可以把 `use` 存为 `expr + declaring scope + budget`，在 `generate` 构建 context 时再求值。
+语言参考仍然是紧凑语法说明；这些设计文档定义语义边界。
 
-## `use` 与 prompt 暴露边界
+## 核心模型
 
-默认情况下，LLM 不应看到当前函数内的全部变量。
-
-以下内容只有被显式 `use` 后才可进入 prompt context：
-
-- 用户输入。
-- 中间结果。
-- scratch 或 memory-like 数据。
-- 工具 observation。
-- imported file 的内容。
-- 其他 Agent 的返回值。
+AgentScript 的控制流服务于 prompt context 构建。
 
-以下 runtime capability 不应作为 prompt context：
+普通语句负责组织数据、调用工具、调用 Agent、查询 memory 和更新中间状态。LLM 调用只能通过 `generate(...) -> { ... }` 发生。一次 `generate` 只能看到由 `use` 显式声明、且在作用域中可见的 context source。
 
-- imported tool。
-- imported llm/model。
-- imported agent binding。
-- function binding。
-- provider URI、workspace path 等执行配置。
+AgentScript 的核心对象是：
 
-例如，下面应被语义分析禁止：
+- **Data**：普通值，例如 input、JSON、list、文件内容、工具 observation、memory 查询结果和 Agent 返回值。
+- **Context source**：通过 `use expr` 选择进入 prompt context 的数据，可带 budget 和 label。
+- **Generation site**：一次由 `generate({ input, max_output, attempts, temperature, think, strict, debug }) -> shape` 表示的 LLM 调用。
+- **Boundary**：由 Agent、function 或 block scope 形成的可见性边界。
+- **Trace**：解释哪些 source 被选择、prompt context 如何构建、每次 generation 返回了什么的审计记录。
 
-```agentscript
-use Search
-use Qwen
-use Worker
-use helper
-```
+## 核心不变量
 
-这条规则的目的不是类型洁癖，而是防止把执行能力或 runtime 配置误当作数据暴露给 LLM。
+AgentScript 应维护这些不变量：
 
-## Scope 是 context boundary
+- **不隐式捕获**：局部变量、工具输出、memory 记录和 trace 事件不会自动进入 prompt，除非被 `use` 选择。
+- **作用域可见性**：context 可见性遵循 scope。子作用域可继承父作用域 context；function 和 Agent 调用创建独立 context boundary。
+- **能力隔离**：imported tool、model、agent、memory handle、function、provider URI 和 runtime 配置是能力，不是 prompt data。
+- **延迟解析 context**：`use expr` 声明 source，值在可见的 `generate` 构建 prompt 时解析。
+- **prompt 分层**：prompt 区分 agent identity、selected context、instruction 和 output contract。
+- **trace 可审计**：trace 必须解释 LLM 调用实际看到了什么，包括 source expression、label、budget、clipping 和结果。
 
-AgentScript 中的作用域不仅是变量可见性规则，也是 prompt context 可见性规则。
+## 边界模型
 
 ### Function boundary
 
-函数调用应创建独立 context boundary。
+每次函数调用都有自己的 context boundary。callee 不会自动继承 caller 已选择的 context。数据必须作为参数传入，并在 callee 需要放进自己的 prompt 时再次 `use`。
 
 ```agentscript
 func caller(input) {
-    use input.goal
+    use input.goal as goal
     helper(input)
 }
 
 func helper(input) {
-    use input.detail
+    use input.detail as detail
     generate({ input: "Work on detail" }) -> {
         ok boolean
     }
 }
 ```
 
-`helper` 内部的 `generate` 不应自动继承 `caller` 的 `use input.goal`，除非该数据作为参数传入并在 `helper` 内显式 `use`。
-
-推荐原则：
-
-- function 的 prompt context 由 function 自己声明。
-- function 返回值不携带 prompt context。
-- caller 的 `use` 不应隐式污染 callee。
+`helper` 内的 `generate` 看到的是 `input.detail`，不是 `caller` 的 `input.goal`。
 
 ### Agent boundary
 
-Agent 调用是更强的 context boundary。
+Agent 调用形成更强的边界。被调用 Agent 不会看到 caller 的 prompt context，只会看到输入值和它自己的函数显式选择的 context。
 
 ```agentscript
 result = Worker({
@@ -149,229 +72,33 @@ result = Worker({
 })
 ```
 
-`Worker` 不应自动看到 Controller 的 context。Controller 必须通过参数显式传入必要数据，Worker 再用自己的 `use` 声明 prompt context。
-
-这保证：
-
-- 每个 Agent 的 prompt contract 独立可审计。
-- 多 Agent 组合不会发生隐式 context 泄露。
-- 子 Agent 只看到调用者明确传入的数据。
+这让 multi-agent 组合保持可审计：每个 Agent 都有自己的 prompt contract。
 
 ### Block boundary
 
-`if`、`repeat`、`loop`、`for` 等 block 可以创建子作用域。子作用域内声明的 `use` 只应影响该子作用域内可见的 `generate`。
-
-```agentscript
-if condition {
-    temp = compute(input)
-    use temp
-    result = generate({ input: "Use temp" }) -> {
-        ok boolean
-    }
-}
-```
-
-`temp` 和 `use temp` 不应泄漏到外层作用域。
-
-### Parent context visibility
-
-如果一个 block 内的 `generate` 处在某个父作用域之下，它可以看到父作用域声明的 context source。可见顺序应从外到内稳定排列，便于 trace 和 prompt 审计。
-
-## Context 构建模型
-
-一次 `generate` 的 prompt 应由四层组成。
-
-### System
-
-System 层描述 Agent identity 和稳定行为约束，例如：
-
-- Agent name。
-- `role`。
-- `description`。
-
-System 层不应包含 provider URI、workspace path、tool implementation detail 或其它执行配置。
-
-### Context
-
-Context 层来自当前 `generate` 可见的 `use` 声明。
-
-每个 context item 应包含：
-
-- source expression，例如 `scratch.summary`。
-- resolved value。
-- rendered text。
-- budget。
-- clipping status。
-
-推荐 prompt 形态：
-
-```text
-Context:
-[0] question:
-What is AgentScript?
-
-[1] scratch.summary:
-[
-  { "fact": "..." }
-]
-```
-
-source label 有助于模型理解 context，也有助于人类审计。
-
-### Instruction
-
-Instruction 层来自 `generate(...)` 参数对象中的 `input` 字段。
-
-```agentscript
-generate({ input: "Answer the question using only collected facts" }) -> {
-    ok boolean
-    text string
-}
-```
-
-Instruction 是本次 LLM 调用的局部任务，不应混入长期 context。
-
-`limit`、`attempts` 和 `debug` 是 `generate` 的局部配置，不属于 prompt context。只有当上一次输出不是 JSON 或不满足 shape 时，runtime 才会在下一次尝试中把错误反馈附加到 instruction。
-
-### Output contract
-
-Output contract 来自 `generate` 表达式上可选的 `-> { ... }` shape。
-
-```agentscript
-generate({ input: "Answer" }) -> {
-    ok boolean
-    text string
-    error string
-}
-```
-
-LLM provider 和 runtime 应尽可能强制输出满足该 shape。
-
-## Budget 语义
-
-`use expr < budget` 是 context item budget。
-
-```agentscript
-use scratch.summary < 2k
-```
-
-它限制的是该 context source 渲染进 prompt 的大小，不是整个 LLM 调用的输出预算。
-
-`generate({ limit: budget }) { ... }` 是 generation budget。
-
-```agentscript
-generate({
-    input: "Summarize"
-    limit: 500
-}) -> {
-    text string
-}
-```
-
-它限制的是本次生成的输出规模或 provider token limit。
-
-两者语义不同，不应混用。
-
-可以先用字符数近似 context budget，但文档和 trace 必须明确实际裁剪策略。若未来切换到 token budget，不应改变 `use` 的抽象含义。
-
-## Clipping 策略
-
-Context clipping 不应只做简单字符串截断，因为这会破坏 JSON/list 结构。
-
-推荐策略：
-
-- string 可以按字符截断。
-- list 应优先保留完整 item。
-- object 应优先保留完整字段。
-- 超限时 trace 应记录原始大小、裁剪后大小和裁剪策略。
-
-如果暂时使用简单字符串截断，必须在 trace 中标记 `clipped: true`，并在文档中说明这是早期实现策略。
-
-## Trace 要求
-
-Trace 是 context engineering DSL 的核心调试接口。
-
-`use` trace 应记录声明信息：
-
-```json
-{
-  "kind": "use",
-  "data": {
-    "source": "scratch.summary",
-    "budget": { "amount": 2, "unit": "k" }
-  }
-}
-```
-
-`generate` trace 应记录实际构建出的 context：
-
-```json
-{
-  "kind": "generate",
-  "data": {
-    "instruction": "Answer from scratch",
-    "context": {
-      "items": [
-        {
-          "source": "scratch.summary",
-          "value": [{ "fact": "A" }],
-          "text": "[...]",
-          "budget": { "amount": 2, "unit": "k" },
-          "clipped": false
-        }
-      ]
-    }
-  }
-}
-```
-
-这使开发者可以回答：
-
-- 本次 LLM 调用到底看到了什么？
-- 哪些 context source 被声明但没有进入当前 generate？
-- 哪些 context 被裁剪？
-- context 是从哪个表达式解析出来的？
-- caller 和 callee 的 context 是否发生了意外污染？
-
-## `summary` view 的含义
-
-`scratch.summary` 是 AgentScript 中常见的 context engineering 写法。
-
-```agentscript
-scratch = []
-scratch.add(observation)
-use scratch.summary < 2k
-```
-
-它表达的是“把 scratch 的 prompt-friendly view 放入 context”。如果实现中 `summary` 只是 JSON-safe list view，而不是真正的 LLM 摘要，应在文档和 trace 中明确。
-
-推荐长期方向：
+`if`、`repeat`、`loop`、`for` 等 block 创建子作用域。block 内声明的 context 影响 block 内的 `generate`，不会向外泄漏。
 
-- `summary` 表示适合 prompt 的紧凑视图。
-- `summary` 不应暴露 runtime resource binding。
-- `summary` 可以结合 clipping 策略保留最有用的完整 item。
+## Prompt 层次
 
-## 实现约束
+一次 `generate` 的 prompt 由四个概念层组成：
 
-为了避免把 AgentScript 误实现成普通编程语言，后续改动应遵守以下约束：
+1. **Agent identity**：当前 Agent 的 `role`、`description` 和稳定身份。
+2. **Selected context**：可见的 `use` 声明，渲染时带 source、label、value 和 budget 信息。
+3. **Instruction**：来自 `generate({ input: ... })` 的本次任务。
+4. **Output contract**：可选的 `-> { ... }` shape。
 
-- `generate` 不自动捕获局部变量。
-- `use` 是 context declaration，不是普通赋值。
-- `use` 的值应在 `generate` 构建 prompt 时解析。
-- function 和 Agent 调用应形成 context boundary。
-- runtime capability 不应进入 prompt context。
-- prompt 中应区分 system、context、instruction 和 output contract。
-- trace 必须能解释每次 `generate` 的实际 context。
+详细构造规则见 [`generate`](./generate.md)。
 
 ## 设计检查清单
 
-修改 `use`、scope、context builder、trace 或 LLM provider 前，应检查：
+修改 `use`、scope、context builder、trace 或 LLM provider 行为前，应检查：
 
-- 这个改动是否让未 `use` 的数据进入了 prompt？
-- 这个改动是否让 caller context 隐式污染 callee？
-- 这个改动是否把 tool/model/agent/function binding 当作数据暴露给 LLM？
-- 这个改动是否保留了 context source 的可审计信息？
-- 这个改动是否让 `use` 退化成普通变量快照？
-- 这个改动是否混淆了 context budget 和 generation budget？
+- 是否让未 `use` 的数据进入 prompt？
+- 是否让 caller context 污染 callee？
+- 是否把 tool/model/agent/function binding 当作 prompt data 暴露？
+- 是否保留 source、label、budget 和 clipping 信息用于审计？
+- 是否把 `use` 退化成快照赋值，而不是延迟 context source？
+- 是否混淆 context budget 和 generation budget？
+- 是否混淆 AgentScript context label 和 provider message role？
 
-AgentScript 的核心价值不是多一种控制流语法，而是让 prompt context 的来源、范围、预算和最终形态都变得显式、稳定、可审计。
+AgentScript 的核心价值不是多一种控制流语法，而是让 prompt context 的来源、范围、预算、身份和最终 prompt 形态显式且稳定。

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

@@ -59,6 +59,24 @@ func run(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
@@ -161,7 +179,7 @@ func summarize(content) {
 
     generate({
         input: "Summarize the content"
-        limit: 1000
+        max_output: 1000
     }) -> {
         title string
         summary string