CLI 和 REPL 工作流
完成 quickstart 后，下一步最好先学会如何在终端运行、检查和调试 AgentScript 程序。
这篇教程使用两个小文件：
1. 查看帮助
先看内置帮助：
agentscript --help
如果你在仓库里工作，可以用：
npm run agentscript -- --help
2. 带输入运行
tutorials/cli.as 需要 name 和 request：
import llm Qwen from "ollama://localhost:11434/qwen3.6"
main agent {
model Qwen
role "CLI Assistant"
description "Answer a short request from a command-line user."
main func(input {
name: string
request: string
}) {
use input.name
use input.request
generate({ input: "Reply to the CLI user by name", max_output: 300 }) -> {
ok: boolean
message
}
}
}
用 mock 输出运行：
agentscript tutorials/cli.as --mock --input '{"name":"Rong","request":"Say hello"}'
开发时优先使用 --mock。它会检查程序形状，但不会调用真实模型。
3. 只打印最终值
如果只想要最终 value，不想要外层 trace wrapper，可以使用 --quiet：
agentscript tutorials/cli.as --mock --quiet --input '{"name":"Rong","request":"Say hello"}'
当另一个脚本要消费 JSON 时，这很有用。
4. Check 和 Parse
运行前可以先检查程序：
agentscript tutorials/cli.as --check
也可以查看解析后的 AST：
agentscript tutorials/cli.as --parse
大多数时候你会更常用 --check。--parse 主要用于调试语法或工具链。
5. 用 Dry Run 检查 Prompt
--dry-run 会构造 prompt 和输出形状，但不调用模型：
agentscript tutorials/cli.as --dry-run --trace --input '{"name":"Rong","request":"Say hello"}'
当你想检查哪些 context 会发送给模型时，用它很合适。
6. Trace 和 Trace File
打印可读 trace：
agentscript tutorials/cli.as --mock --trace --input '{"name":"Rong","request":"Say hello"}'
把原始 trace 写入文件：
agentscript tutorials/cli.as --mock --trace-file /tmp/agentscript-trace.json --input '{"name":"Rong","request":"Say hello"}'
trace 是调试 context boundary 的最好工具之一。它会显示每次 generate 能看到哪些 use。
7. 使用输入文件
输入较大时，可以把 JSON 写入文件：
{
"name": "Rong",
"request": "Say hello"
}
然后运行：
agentscript tutorials/cli.as --mock --input-file input.json
8. 启动 REPL
不传文件直接启动 AgentScript：
agentscript
在 REPL 中加载文件：
:load tutorials/repl.as
检查：
:check
运行：
:run {}
退出：
:exit
当你想快速草拟一个小 agent，或不想频繁切换文件来检查语法时，REPL 很方便。
9. 推荐工作流
开发一个新 agent 时：
- 编写或加载
.as文件。 - 运行
--check。 - 用
--mock运行。 - 用
--trace或--dry-run --trace检查。 - 确认形状没问题后，再切换到真实模型。