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: 推荐的工作流程

  1. 定位。 reflect::context 用于一次性快照:身份、路由/视图计数、加载的包、最近的错误。然后 reflect::compactRoutes。
  2. 探索。 reflect::find <type>、reflect::search <query>、reflect::nodeBody <name>、reflect::fileContent <relPath>。
  3. 执行。 使用 phlo_eval '<phlo>' 检查实时数据和行为:计数、记录、方法的实际输出、渲染的视图。
  4. 阅读。 在编辑之前阅读实际的 .phlo 源代码。
  5. 编辑。 仅限 .phlo、data/app.json 和入口点。绝不要编辑生成的 PHP。
  6. 构建和检查。 build::run,然后 build::lint(空数组 = 干净;如果不是,请修复源代码并重复)。
  7. 记录。 更新 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:

20.5: 权力与危险

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

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

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

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。有关完整命令参考,请参见工具章节。

20.7: Your app as a tool for agents

Enable the mcp resource and name what an agent may reach:

prop %mcp.models = ['order' => 'Orders of the shop']

POST /mcp then speaks the Model Context Protocol. Each model gets list, get, create, change and delete tools with schemas from its fields, and every call goes through the same rules as a form: the scope, canChange, objRefusal, field rules and hooks. mcp: false on a field keeps it out; a password has that by itself. A client signs in with a bearer token from the [mcp] section of creds, and prop %mcp.canUse takes over for a token per user. With CSRF enabled, add mcp to %CSRF.except.

最近更新于 2026年11月4日

我们使用必要的cookie来使该网站正常工作。在您的许可下,我们还使用分析工具来改善网站。