@rong/agentscript 0.1.0

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

@@ -0,0 +1,323 @@
+# AgentScript V1 Design
+
+V1 的目标不是把 AgentScript 扩展成通用工作流语言，而是在 V0 的小语言面上支持更多常见 Agent 模式。设计原则仍然是少关键词、强作用域、显式上下文。
+
+V1 应优先增强普通数据、Agent 组合、工具能力和文件组织，而不是增加 `planner`、`executor`、`verifier`、`rollback`、`parallel` 这类模式专用关键词。
+
+`use`、作用域和 prompt context 的基础语义见 [`Context Engineering`](../cn/context-engineering.md)。V1 的新能力必须保持这些核心语义，不应把 AgentScript 误扩展成会隐式捕获上下文的通用编程语言。
+
+## 目标
+
+V1 支持的核心模式：
+
+- ReAct：V0 已支持，V1 保持兼容。
+- Plan-and-Execute：生成结构化计划，逐步执行，校验并按需重规划。
+- Reflection / Self-improve：用短 insight 改进下一次尝试。
+- Evaluator-Optimizer：生成候选结果，由 evaluator 校验，再改进。
+- Multi-agent composition：不同 Agent 拆分职责，调用边界天然隔离上下文。
+
+V1 不追求：
+
+- 通用事务系统。
+- 通用并行编排。
+- Durable workflow。
+- 完整类型系统。
+- 内建 eval/harness DSL。
+- 默认自动 repair。
+
+## 语言面收紧
+
+V1 尽量不新增模式关键词。
+
+继续保持：
+
+- `planner`、`executor`、`verifier`、`controller` 都是普通 Agent 或普通函数名。
+- `plan`、`step`、`status`、`result` 都是普通 JSON/list 数据。
+- `rollback` 不作为关键词。
+- `parallel` 不作为 V1 核心关键词。
+
+V1 可考虑新增的语言能力只有两类：
+
+- 更自然的 list 遍历。
+- 跨文件 import。
+
+## Plan-and-Execute
+
+Plan-and-Execute 可以用普通 Agent 表达：
+
+```agentscript
+import agent Planner  from "./planner.as"
+import agent Executor from "./executor.as"
+import agent Verifier from "./verifier.as"
+
+main agent PlanAndExecute {
+    main func(input {
+        goal string
+    }) {
+        plan = Planner(input)
+        results = []
+
+        for step in plan.steps < 12 {
+            result = Executor({
+                goal: input.goal
+                step: step
+                previous: results.summary
+            })
+
+            verdict = Verifier({
+                goal: input.goal
+                step: step
+                result: result
+            })
+
+            if verdict.ok {
+                results.add({
+                    step: step.id
+                    result: result
+                })
+            } else {
+                plan = Planner({
+                    goal: input.goal
+                    previous: results.summary
+                    problem: verdict.reason
+                })
+            }
+        }
+
+        return {
+            ok: true
+            results: results
+        }
+    }
+}
+```
+
+这里新增的核心语法只有：
+
+```agentscript
+for item in list < n {
+    ...
+}
+```
+
+规则：
+
+- `for` 每次迭代创建子作用域。
+- `< n` 是硬上限。
+- list 在循环开始时求值一次。
+- 循环体内新建变量不会泄漏到外层。
+- 外层已存在变量可以被更新，例如 `results.add(...)` 或 `plan = ...`。
+
+## Plan 数据约定
+
+V1 不需要专门的 `plan` 类型。推荐结构：
+
+```agentscript
+return generate({ input: "Create a short executable plan" }) {
+    return {
+        steps list[json]
+    }
+}
+```
+
+每个 step 推荐包含：
+
+```json
+{
+  "id": "step-1",
+  "task": "Search for current docs",
+  "kind": "search",
+  "status": "pending"
+}
+```
+
+`kind`、`status` 只是字符串，不需要枚举类型。
+
+## 回滚与补偿
+
+V1 不引入 `rollback` 关键词。
+
+原因：Agent 的副作用通常来自工具，例如写文件、执行 shell、调用 API。语言层无法保证这些副作用都能严格回滚。V1 采用 effect record + compensation 的设计。
+
+有副作用的工具应返回 effect 信息：
+
+```json
+{
+  "ok": true,
+  "value": "...",
+  "effects": [
+    {
+      "id": "effect-123",
+      "tool": "File",
+      "undoable": true
+    }
+  ]
+}
+```
+
+Agent 用普通函数处理补偿：
+
+```agentscript
+func compensate(result) {
+    if result.effects {
+        return File.undo(result.effects)
+    }
+
+    return {
+        ok: true
+    }
+}
+```
+
+Controller 逻辑也用普通函数表达：
+
+```agentscript
+if not verdict.ok {
+    compensate(result)
+    plan = revise(goal, plan, results, verdict)
+}
+```
+
+这不是严格事务，而是可审计的补偿动作。
+
+## 并行
+
+V1 核心不引入并行语法。
+
+原因：
+
+- 并行会影响 trace 顺序。
+- 并行会放大工具副作用风险。
+- 并行需要 rate limit、错误聚合和预算控制。
+- 当前 V0/V1 的作用域模型以顺序执行为基础，容易审计。
+
+V1 可以在 runtime 实验层支持并行工具或并行 Agent 调用，但不进入核心语法。正式并行语法应等 Plan-and-Execute 顺序模型稳定后再设计。
+
+## Tool URI Scheme
+
+V1 的 `import tool` 不应绑定到单一协议。MCP 可以作为一种工具来源，但 shell/io/http 这类常见能力不需要强行放进 `mcp://...`。
+
+推荐规则：
+
+- `mcp://...` 表示外部 MCP 工具。
+- `sh://...` 表示 host runtime 提供的具体 shell 命令。
+- `file://...` 表示 host runtime 提供的文件能力。
+- `env://...` 表示 host runtime 提供的环境变量读取能力。
+- `http://...` / `https://...` 表示 HTTP 工具或远端服务。
+- 自定义 runtime 可以注册更多 scheme。
+
+URI scheme 只决定绑定到哪个 provider；具体方法仍通过普通成员调用表达。
+
+## 常用 Shell / IO 工具
+
+V1 可以定义一组推荐 host tools，而不是把 shell/io 做成语言关键词，也不要求它们经过 MCP。
+
+推荐工具 import：
+
+```agentscript
+import tool Find from "sh://find"
+import tool Grep from "sh://grep"
+import tool Sed  from "sh://sed"
+import tool File from "file://workspace"
+import tool Env  from "env://process"
+import tool Http from "https://api.example.com"
+```
+
+推荐能力：
+
+- `Find.run({ path, name, type, max })`
+- `Grep.run({ path, pattern, include, max })`
+- `Sed.run({ path, start, max })`
+- `File.read({ path })`
+- `File.write({ path, content })`
+- `File.patch({ path, search, replace })`
+- `File.list({ path })`
+- `File.undo(effects)`
+- `Env.get({ name })`
+- `Http.get({ url, headers })`
+- `Http.post({ url, headers, body })`
+
+示例：
+
+```agentscript
+files = Find.run({
+    path: "."
+    name: "*.ts"
+    max: 50
+})
+
+matches = Grep.run({
+    path: "src"
+    pattern: "generate"
+    include: "*.ts"
+    max: 100
+})
+```
+
+安全规则应由 host runtime 执行：
+
+- `sh://...` 工具必须绑定到具体命令。
+- 禁止 `sh://sh`、`sh://bash`、`sh://zsh`、`sh://fish` 这类通用 shell。
+- 禁止通过 `sh://...` 传入任意命令字符串；参数必须是结构化字段。
+- shell 工具默认需要工作目录、超时和输出上限。
+- 文件工具默认限制在 workspace 内。
+- 写文件工具必须返回 effect record。
+- 网络工具可由 host 配置允许或禁止。
+
+## 文件引用
+
+V1 增加文件资源 import：
+
+```agentscript
+import file Requirements from "./requirements.md"
+import file ApiSpec      from "./openapi.json"
+```
+
+文件资源是只读上下文资源。使用方式：
+
+```agentscript
+func answer(input) {
+    use Requirements < 4k
+    use input.question
+
+    return generate({ input: "Answer from the referenced file" }) {
+        return {
+            ok boolean
+            text string
+        }
+    }
+}
+```
+
+规则：
+
+- `file` 只在 `import file` 中作为资源类别。
+- 文件内容默认不进入 prompt，必须 `use`。
+- `use Requirements < 4k` 应用上下文预算。
+- JSON 文件可以作为 json 读取；文本文件作为 string 读取。
+- 文件路径相对当前 `.as` 文件解析。
+
+## 跨文件 Agent Import
+
+V1 增加 Agent import：
+
+```agentscript
+import agent Planner  from "./agents/planner.as"
+import agent Executor from "./agents/executor.as"
+import agent Verifier from "./agents/verifier.as"
+```
+
+规则：
+
+- 被 import 的文件可以包含一个或多个 Agent。
+- `import agent Name from "./x.as"` 导入文件中名为 `Name` 的 Agent。
+- 导入的 Agent 不自动成为入口。
+- 当前程序仍然只能有一个 `main agent`。
+- `Planner(input)` 调用 `Planner` 的 `main func`。
+- `Planner.make(input)` 调用指定函数 `make`。
+- 跨文件 Agent 调用保持独立函数作用域和嵌套 trace。
+
+开放问题：
+
+- 是否允许 `import agent * from "./agents.as"`。V1 初期建议不支持。
+- 是否允许 import alias。可用 `import agent Planner as PlanMaker from ...`，但这会增加语法，V1 初期建议不支持。

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

@@ -0,0 +1,267 @@
+# AgentScript V1 实施计划
+
+本文档描述 V1 的分阶段实施方案。V1 设计见 `v1-design.md`。
+
+V1 的实现目标是支持更多 Agent 模式，尤其是 Plan-and-Execute、Evaluator-Optimizer 和多 Agent 组合，同时保持语言小而清晰。
+
+## 原则
+
+- 先实现普通数据和模块能力，再考虑新控制流。
+- 不引入模式专用关键词。
+- 不实现通用并行语法。
+- 不实现通用事务系统。
+- Shell / IO 工具必须具体、可审计、可授权。
+
+## 阶段 1：Plan-and-Execute 示例
+
+状态：已完成。
+
+目标：先用 V0 现有能力写出 Plan-and-Execute 示例，确认真实痛点。
+
+产物：
+
+- `tutorials/plan-execute.as`
+- Planner、Executor、Verifier 作为普通 Agent 或普通函数。
+- 顺序执行 plan steps。
+- verifier 失败时调用 planner 重新规划。
+
+验收：
+
+- 示例能 parse/check/execute。
+- trace 能看出 plan、step、verify、replan 的执行边界。
+
+## 阶段 2：List 遍历
+
+状态：已完成。
+
+新增语法：
+
+```agentscript
+for item in list < n {
+    ...
+}
+```
+
+实现项：
+
+- AST 增加 `ForInStmt`。
+- parser 支持 `for item in expr < n { ... }`。
+- semantic analyzer 检查 item 作用域和 iterable 表达式。
+- runtime 校验 iterable 是 list，顺序遍历，`< n` 作为硬上限。
+- trace 可选记录 iteration。
+
+约束：
+
+- `for` 每次迭代创建子作用域。
+- list 在循环开始时求值一次。
+- 外层已存在变量可以被更新。
+
+## 阶段 3：List / JSON 能力增强
+
+状态：已完成。
+
+补齐 Plan-and-Execute 后续可能需要的集合能力。当前已支持 `list.length`、`list.add(value)`、`list.summary` 和 `for item in list < n`。
+
+新增语法：
+
+```agentscript
+item = list[0]
+value = list[index].field
+```
+
+实现项：
+
+- parser 支持 `expr[expr]` postfix 表达式。
+- semantic analyzer 检查 list 和 index 两侧表达式。
+- runtime 支持 list item 读取。
+- 越界读取抛出运行时错误。
+- 非 list 或非非负整数 index 报运行时错误。
+
+约束：
+
+- 只支持读取，不支持 `list[0] = value`。
+- 不支持切片。
+- 不新增专用 JSON 操作关键词。
+
+## 阶段 4：File Import
+
+状态：已完成。
+
+新增资源类型：
+
+```agentscript
+import file Requirements from "./requirements.md"
+import file ApiSpec      from "./openapi.json"
+```
+
+实现项：
+
+- AST 扩展 `ImportResourceKind` 支持 `file`。
+- parser 支持 `import file`。
+- semantic analyzer 把 file 作为资源绑定。
+- runtime 加载相对当前 `.as` 文件的文件内容。
+- `use FileName < n` 将文件内容加入 context。
+
+约束：
+
+- 文件默认不进入 prompt，必须显式 `use`。
+- 文本文件作为 string。
+- JSON 文件可作为 json。
+- 路径解析和访问范围由 host runtime 控制。
+- CLI 执行时相对路径基于当前 `.as` 文件目录解析。
+- REPL 中相对路径基于当前工作目录解析。
+
+## 阶段 5：Agent Import
+
+状态：已完成。
+
+新增资源类型：
+
+```agentscript
+import agent Planner from "./agents/planner.as"
+```
+
+实现项：
+
+- parser 支持 `import agent`。
+- loader 解析跨文件依赖图。
+- semantic analyzer 合并导入 Agent 的符号。
+- runtime 允许调用导入 Agent。
+- trace 继续嵌套跨 Agent 调用。
+
+约束：
+
+- `import agent Name from "./x.as"` 只导入文件中名为 `Name` 的 Agent。
+- 导入 Agent 不自动成为入口。
+- 当前程序仍然只能有一个 `main agent`。
+- V1 初期不支持 wildcard import 和 alias。
+- CLI 使用 loader 执行、检查和解析入口文件。
+
+## 阶段 6：Tool URI Provider
+
+状态：已完成。
+
+扩展 tool provider 分发：
+
+- `mcp://...`
+- `sh://具体命令`
+- `file://workspace`
+- `env://process`
+- `http://...`
+- `https://...`
+
+实现项：
+
+- 根据 URI scheme 选择 provider。
+- `ToolProvider` 可拆分为 registry。
+- trace 记录 provider scheme。
+- 错误消息包含 tool 名称、method 和 URI。
+
+约束：
+
+- 本阶段只实现分发框架，不实现具体 shell/io/http 工具。
+- 未注册 scheme 默认进入 fallback provider。
+
+## 阶段 7：具体 Shell / IO 工具
+
+状态：已完成。
+
+推荐先实现：
+
+- `sh://find`
+- `sh://grep`
+- `sh://sed`
+- `file://workspace`
+- `env://process`
+
+已实现：
+
+- `Find.run({ path, name, type, max })`
+- `Grep.run({ path, pattern, include, max })`
+- `Sed.run({ path, start, max })`
+- `File.read({ path })`
+- `File.list({ path })`
+- `File.write({ path, content })`
+- `File.undo(effects)`
+- `Env.get({ name })`
+- `Http.get({ url, headers, timeout })`
+- `Http.post({ url, headers, body, timeout })`
+
+禁止：
+
+- `sh://sh`
+- `sh://bash`
+- `sh://zsh`
+- `sh://fish`
+- 任意命令字符串入口。
+
+约束：
+
+- 参数必须是结构化 JSON。
+- 每个工具必须有超时和输出上限。
+- 文件写入必须限制在 workspace。
+- 有副作用的工具必须返回 effect record。
+- `sh://sh`、`sh://bash` 等通用 shell 入口在 host provider 中被拒绝。
+
+## 阶段 8：Effect Record 和 Compensation
+
+状态：已完成。
+
+目标：支持可审计补偿，不做语言级 rollback。
+
+推荐 effect record：
+
+```json
+{
+  "id": "effect-123",
+  "tool": "File",
+  "action": "write",
+  "undoable": true
+}
+```
+
+实现项：
+
+- File write/patch 返回 effects。
+- 允许 `File.undo(effects)`。
+- trace 记录 effects。
+- 示例中用普通函数 `compensate(result)` 表达补偿。
+
+约束：
+
+- 语言不新增 `rollback` 关键词。
+- effect record 是普通 JSON，由工具返回。
+- compensation 是普通函数调用，例如 `File.undo(result.effects)`。
+
+## 阶段 9：Trace 增强
+
+状态：已完成。
+
+增强内容：
+
+- for iteration。
+- step id。
+- agent call tree。
+- tool effects。
+- replan 原因。
+
+已实现：
+
+- agent call tree。
+- for iteration。
+- tool scheme、URI 和 effects。
+
+要求：
+
+- trace 不进入 prompt。
+- pretty trace 保持可读。
+- JSON trace 保持可机器处理。
+
+## V1 完成标准
+
+- 能用多个文件组织 Planner、Executor、Verifier。
+- 能引用本地文件作为受预算控制的上下文。
+- 能用具体 `sh://...`、File、Env、Http 工具完成有限任务。
+- 能用 effect record + compensation 表达可审计补偿。
+- 能用 `for item in list < n` 顺序执行 plan steps。
+- 不引入 `planner`、`executor`、`verifier`、`rollback`、`parallel` 等模式关键词。