@rong/agentscript 0.1.0

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

@@ -0,0 +1,387 @@
+# AgentScript V2 Design
+
+V2 的目标是引入可持久化、可审计、显式使用的 Agent Memory，使 reflection、self-improvement 和更谨慎的 self-evolution 模式可以用普通 AgentScript 组合出来。
+
+V2 不把 `reflect`、`improve`、`evolve` 做成关键词。它们应继续是普通函数名、Agent 名或业务模式。语言层面只提供必要的 memory 原语。
+
+`use`、作用域和 prompt context 的基础语义见 [`Context Engineering`](../cn/context-engineering.md)。Memory 必须遵守同一原则：memory 不会自动进入 prompt，只有查询结果被赋值为普通数据并显式 `use` 后，才会进入后续 `generate`。
+
+## 目标
+
+V2 支持的核心能力：
+
+- `import memory` 声明外部记忆体。
+- file JSONL memory backend。
+- sqlite memory backend。
+- 最小 memory 操作：`add` 和 `query`。
+- memory 操作写入 trace，便于审计。
+- reflection / self-improvement 通过普通 Agent、函数和 memory 组合表达。
+
+V2 不追求：
+
+- 向量数据库。
+- 任意 SQL 执行。
+- 自动长期记忆。
+- 自动记录所有 trace 到 memory。
+- 自动修改 `.as` 源码。
+- 通用 eval/harness DSL。
+- 通用事务、回滚或并行 workflow。
+
+## Memory 定位
+
+Memory 是跨运行持久化的上下文资产。
+
+它不同于 tool：
+
+- tool 表示外部动作能力。
+- memory 表示可读写的持久化数据源。
+
+它也不同于 file import：
+
+- file import 是静态或半静态输入。
+- memory 会被 AgentScript 显式写入，并影响未来运行。
+
+```agentscript
+import memory Lessons from "file://./.agentscript/lessons.jsonl"
+import memory Runs    from "sqlite://./.agentscript/memory.db#runs"
+```
+
+Memory binding 是 runtime capability，不能直接进入 prompt：
+
+```agentscript
+use Lessons // invalid
+```
+
+必须先查询，得到普通 JSON/list 数据：
+
+```agentscript
+past = Lessons.query({
+    text: input.goal
+    limit: 5
+})
+
+use past < 2k
+```
+
+## 最小 API
+
+V2 memory 先只定义两个操作。
+
+### add
+
+```agentscript
+Lessons.add({
+    kind: "lesson"
+    text: reflection.insight
+    goal: input.goal
+    ok: result.ok
+})
+```
+
+语义：
+
+- 追加一条记录。
+- 参数必须是 JSON object。
+- runtime 自动补充 `id`、`created_at` 和 `updated_at`。
+- 返回写入后的记录 envelope。
+- 写入 trace，但不自动进入 prompt。
+
+推荐返回结构：
+
+```json
+{
+  "id": "...",
+  "created_at": "...",
+  "updated_at": "...",
+  "record": {
+    "kind": "lesson",
+    "text": "...",
+    "goal": "..."
+  }
+}
+```
+
+### query
+
+```agentscript
+past = Lessons.query({
+    text: input.goal
+    kind: "lesson"
+    limit: 5
+})
+```
+
+语义：
+
+- 返回 list。
+- `limit` 可选，缺省值由 runtime 设定。
+- `text` 可选，表示文本相关查询。
+- `kind` 可选，表示记录类型过滤。
+- `where` 可选，表示顶层字段精确匹配。
+- 结果默认按最近写入优先。
+
+推荐查询参数：
+
+```agentscript
+{
+    text: string
+    kind: string
+    where: json
+    limit: number
+}
+```
+
+V2 的 `text` 查询不承诺语义向量检索。file backend 可以先做大小写不敏感字符串匹配；sqlite backend 可以先做 `LIKE`，之后再升级 FTS5。
+
+## File Memory
+
+file memory 使用 JSONL：
+
+```agentscript
+import memory Lessons from "file://./.agentscript/lessons.jsonl"
+```
+
+每一行是一条 envelope：
+
+```json
+{"id":"...","created_at":"...","updated_at":"...","record":{"kind":"lesson","text":"..."}}
+```
+
+规则：
+
+- 文件不存在时可自动创建。
+- 父目录不存在时可自动创建。
+- 每次 `add` 追加一行 JSON。
+- `query` 读取文件并过滤。
+- 损坏 JSONL 行应报错，不静默跳过。
+- 相对路径基于入口 `.as` 文件目录解析；REPL 中基于当前工作目录。
+
+file memory 的价值是透明、易调试、适合早期 self-improvement。
+
+## SQLite Memory
+
+sqlite memory 使用固定 schema：
+
+```agentscript
+import memory Lessons from "sqlite://./.agentscript/memory.db#lessons"
+```
+
+URI 语义：
+
+- path 指向 sqlite 数据库文件。
+- fragment 指向 memory namespace 或 table 名。
+- fragment 为空时使用默认 namespace `memory`。
+
+推荐 schema：
+
+```sql
+CREATE TABLE IF NOT EXISTS memory_records (
+  namespace TEXT NOT NULL,
+  id TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  kind TEXT,
+  text TEXT,
+  record_json TEXT NOT NULL,
+  PRIMARY KEY (namespace, id)
+);
+```
+
+实现规则：
+
+- AgentScript 不暴露任意 SQL。
+- `add(record)` 写入 `record_json`，并从 record 顶层提取 `kind` 和 `text`。
+- `query({ kind, text, where, limit })` 在固定 schema 上查询。
+- `where` 只做 record 顶层字段精确匹配。
+- 第一版可以用 `LIKE` 做 text 查询；FTS5 可作为后续增强。
+
+SQLite backend 的价值是稳定、可扩展、适合长期运行。
+
+## Reflection 模式
+
+Reflection 不需要新关键词。
+
+```agentscript
+agent Reflector {
+    model Qwen
+    role "Reflector"
+    description "Extract reusable lessons from execution results."
+
+    main func(input) {
+        use input
+
+        return generate({
+            input: "Extract one reusable lesson from this run.",
+            attempts: 3
+        }) {
+            return {
+                insight string
+                mistake string
+                next_rule string
+            }
+        }
+    }
+}
+```
+
+调用方决定是否写入 memory：
+
+```agentscript
+reflection = Reflector({
+    goal: input.goal
+    result: result
+})
+
+Lessons.add({
+    kind: "lesson"
+    text: reflection.insight
+    goal: input.goal
+    next_rule: reflection.next_rule
+})
+```
+
+## Self-Improvement 模式
+
+Self-improvement 的 V2 定义是：
+
+> Agent 显式读取过去 lesson，把相关 lesson 放入当前 prompt，并在运行结束后显式写入新的 lesson。
+
+```agentscript
+import llm Qwen from "ollama://localhost:11434/qwen3.6"
+import memory Lessons from "file://./.agentscript/lessons.jsonl"
+
+main agent Learner {
+    model Qwen
+    role "Learning Agent"
+    description "Use durable lessons to improve future answers."
+
+    main func(input {
+        goal string
+    }) {
+        past = Lessons.query({
+            text: input.goal
+            kind: "lesson"
+            limit: 5
+        })
+
+        use input.goal
+        use past < 2k
+
+        result = generate({
+            input: "Answer the goal using relevant past lessons.",
+            attempts: 3
+        }) {
+            return {
+                ok boolean
+                answer string
+                reason string
+            }
+        }
+
+        reflection = reflect({
+            goal: input.goal
+            result: result
+        })
+
+        Lessons.add({
+            kind: "lesson"
+            text: reflection.insight
+            goal: input.goal
+            ok: result.ok
+        })
+
+        return result
+    }
+
+    func reflect(run) {
+        use run
+
+        return generate({
+            input: "Extract one reusable lesson from this run.",
+            attempts: 3
+        }) {
+            return {
+                insight string
+            }
+        }
+    }
+}
+```
+
+这里的改进来自 memory，而不是隐式上下文膨胀。
+
+## Self-Evolution 边界
+
+V2 只支持保守的 self-evolution：
+
+- 生成 rule、preference、lesson、profile 等可持久化数据。
+- 下一次运行通过 memory 查询和 `use` 显式影响行为。
+- 可以生成 patch proposal，但不自动修改源代码。
+
+V2 不支持：
+
+- Agent 自动改写自己的 `.as` 文件。
+- 自动安装工具或依赖。
+- 自动改变 import URI。
+- 绕过 host 授权写入任意路径。
+
+原因：
+
+- 代码自修改需要更强的权限模型、审计和回滚。
+- memory 更新已经足够覆盖大多数 self-improvement 场景。
+- AgentScript 的核心仍是 context engineering，而不是 autonomous code mutation。
+
+## Trace
+
+Memory 操作必须写入 trace：
+
+```json
+{
+  "kind": "memory",
+  "data": {
+    "memory": "Lessons",
+    "operation": "query",
+    "uri": "file://./.agentscript/lessons.jsonl",
+    "args": { "kind": "lesson", "limit": 5 },
+    "count": 3
+  }
+}
+```
+
+写入 trace：
+
+```json
+{
+  "kind": "memory",
+  "data": {
+    "memory": "Lessons",
+    "operation": "add",
+    "id": "...",
+    "record": { "kind": "lesson", "text": "..." }
+  }
+}
+```
+
+trace 是审计产物，不会自动进入 prompt。
+
+## 安全边界
+
+V2 memory 需要 host runtime 控制：
+
+- file/sqlite 路径必须限制在 workspace 或明确授权目录内。
+- `file://` memory 只能写 JSONL。
+- `sqlite://` memory 只能操作固定 schema。
+- 不支持 `sqlite://...` 任意 SQL。
+- memory binding 不能被 `use`。
+- memory 查询结果是普通数据，可以被 `use`。
+
+## 与 V1 的关系
+
+V1 的 Plan-and-Execute、Evaluator-Optimizer 和 Multi-agent composition 可以直接叠加 V2 memory：
+
+- Planner 查询过去 plan 失败经验。
+- Executor 查询工具调用注意事项。
+- Verifier 写入失败样本。
+- Controller 写入 run summary。
+
+V2 不改变 V1 控制流，也不增加模式专用关键词。