20: 对于 AI 代理

Phlo 的构建旨在由 AI 代理驱动，而不仅仅是被它们读取。每个应用程序都暴露出三个 CLI 层，让代理在没有先前代码库知识的情况下工作：reflect:: 用于理解代码，phlo_eval 用于执行代码，build:: 用于转译和验证。这三者都需要 build: true，并且绝不能在生产环境中运行。

如果你是一个正在接手 Phlo 应用的代理，从这里开始。

20.1: 三位一体：理解、执行、构建

三个层次，三个平面。按此顺序访问它们。

层	平面	用于
`reflect::`	静态	在不运行任何内容的情况下理解结构：routes、views、解析的 AST、搜索、依赖图。安全、只读，即使在运行时损坏时也能工作。
`phlo_eval`	运行时	在实时应用中执行一串 Phlo：读取记录、调用方法、渲染视图、重现错误。强大且有副作用。
`build::`	转换	将 `.phlo` 源代码构建为 PHP，并在编辑前后对结果进行 lint。

reflect:: 和 build:: 在应用外部运行（仅源代码，无需启动），这就是它们快速且无副作用的原因。phlo_eval 在启动的应用内部运行，这就是它可以接触实时数据的原因，以及它带来真实风险的原因。

20.2: 推荐的工作流程

定位。 reflect::context 用于一次性快照：身份、路由/视图计数、加载的包、最近的错误。然后 reflect::compactRoutes。
探索。 reflect::find <type>、reflect::search <query>、reflect::nodeBody <name>、reflect::fileContent <relPath>。
执行。 使用 phlo_eval '<phlo>' 检查实时数据和行为：计数、记录、方法的实际输出、渲染的视图。
阅读。 在编辑之前阅读实际的 .phlo 源代码。
编辑。 仅限 .phlo、data/app.json 和入口点。绝不要编辑生成的 PHP。
构建和检查。 build::run，然后 build::lint（空数组 = 干净；如果不是，请修复源代码并重复）。
记录。 更新 data/app.md，包括结构更改、新路由、已解决的 TODO 和剩余工作。

20.3: 反射:: 在实践中

php www/app.php reflect::context                     # orient
php www/app.php reflect::compactRoutes               # route map
php www/app.php reflect::search "createRecord" all   # find usage
php www/app.php reflect::nodeBody home               # one method's body
php www/app.php reflect::objectIndex                 # resources, methods, props

输出为 JSON。 reflect::context 读取 data/app.md，这是一个由人类和代理编写的草稿，帮助您了解意图和状态。有关完整命令参考，请参见 Tooling 章节。

20.4: phlo_eval in practice

phlo_eval '<phlo source>' transpiles a string of Phlo statements and runs them in the live app. It is the runtime complement to reflection: where reflect:: reads the static source, phlo_eval executes against real data, resources and views.

php www/app.php phlo_eval "user::recordCount()"                 # 38, no return keyword
php www/app.php phlo_eval "%app->title"                         # "App"
php www/app.php phlo_eval "echo '<strong>boom</strong>'"        # <strong>boom</strong>

A single expression needs no return: it auto-returns like a => arrow body. Reach for return only inside a multiline block, where it is required:

php www/app.php phlo_eval '$pro = array_filter(user::records(), fn($u) => $u->tier === "pro")
return array_values(array_column($pro, "email"))'

Rules:

Auto-return. A single line auto-returns, exactly like a => arrow body, unless it starts with return/apply/echo/unset/yield. A multiline block needs its own return.
Output. return <expr> prints the value as JSON: type-safe, non-scalar-capable, and errors come back as {"error": ...}. echo <expr> prints raw to stdout, for viewing rendered HTML/markup as-is.
Scope. %resource refs resolve as normal. The app is constructed but its app-controller (router/init) is skipped, like any CLI callback; resource controllers do run, so the database and resources are live.
Errors are readable. A failing call returns a structured {"error": ...} with type, message and source, so you can iterate: one run teaches you that user::records() returns objects, the next uses ->tier instead of ["tier"].

20.5: 权力与危险

phlo_eval 以完整的应用权限在实时应用中运行任意代码。在一次调用中，它可以读取密码哈希、API 密钥和个人数据，而在另一次调用中，它可以变更或删除数据（%db->exec(...)）。没有沙箱。

这正是它受到限制的原因：

仅限 CLI。 即使连接到路由，它也拒绝在 HTTP 请求期间运行。它永远不能成为一个可通过网络访问的 eval 端点。
仅限构建。 只有在 build: true 时它才存在。它从未被构建到发布或生产应用中；在那里调用它只是一个未定义的函数。
仅限开发者编写。 将其输入视为 eval() 本身：自己编写，绝不要传递不受信任或用户提供的输入。

在这些限制内，它是一个精确、诚实的工具：它向你展示应用实际执行的内容，而不是源代码所暗示的内容。

20.6: build:: 在实践中

php www/app.php build::run      # transpile changed .phlo to PHP
php www/app.php build::lint     # [] means clean; otherwise fix the .phlo source
php www/app.php build::release  # build the release when stage/prod output changes

Lint 报告在 transpiled PHP 中存在解析错误。始终修复 .phlo 源文件并重新构建；绝不要修补生成的 PHP。有关完整命令参考，请参见工具章节。

最近更新于 2026年8月7日