AI 使用手册

给指挥 AI 用 Aimanong 的人看的实操指南。

这不是 API 文档（那是 API 参考），而是一份经验总结： 基于 5 轮 AI 实测 + 1 轮真实业务场景验证，记录 AI 在哪里容易出错、怎么避免。

如果你自己就是 AI Agent，请直接读 llms.txt， 那份文件是为你优化的（token 更省、契约更紧凑）。

---

一、先建立正确预期

AI 能做到什么

任务	实测表现
从数据库表生成完整后台	✅ 一次成功率 1.0（连续三轮）
发现框架能力（不说 API 名，只说业务需求）	✅ 三项新能力全部自主发现
真实电商场景（三表、16 字段、状态机）	✅ 19 项需求中 17 项直接支持

AI 做到不什么（当前版本）

限制	说明
前端拖拽	draggable() 声明会被编译，但前端 UI 未实现
导出 Excel	仅支持 CSV（Excel 能打开，但不是 .xlsx）
复杂自定义页面	超出声明式 DSL 范围时需手写代码

把限制提前告诉 AI，比让它撞墙再返工更省时间。

---

二、三个必做动作

动作 1：让它先"查能力"，再动手

错误做法：直接说"帮我做个商品管理"。

正确做法：

先调用 list-resources 和 search-docs 了解框架有什么能力，
再开始写代码。

为什么：AI 会凭训练数据里的 Laravel 经验猜写法。 实测中 AI 曾因照搬常规框架写法而失败（框架铁律：三个方法必须 static、无 $model 属性）。

动作 2：必须传 requirements

这是最重要的一条。

{
  "resource": "App\\Aimanong\\OrderResource",
  "requirements": {
    "searchable": "order_no,customer_name",
    "sortable": "amount,paid_at",
    "required": "order_no",
    "per_page": 30
  }
}

为什么：validate-declaration 默认只检查语法合法性，不检查是否满足你的需求。

实测中最严重的一次事故：AI 生成的代码缺了 3 条需求， 而校验器返回「✅ 语法校验通过」——AI 会误判成功并交付残次品。

不传 requirements 就验收，等于没验收。

动作 3：让它验证"真的生效了"

AI 容易相信"声明了就等于生效了"。要求它做运行时验证：

不要只看 validate-declaration 的全绿。
请实际请求一次 API，确认返回的数据符合预期。

实测中 AI 自己总结出了更好的做法——负向对照：

用只存在于「非搜索列」的关键词去搜，必须返回 0 行， 才能证明搜索真的按声明列过滤。

---

三、AI 最容易踩的 6 个坑

来自 5 轮实测的真实记录。

坑 1：照搬其他框架的写法

现象：写 public string $model = User::class;（实例属性 + 非静态方法）

后果：框架的三个方法必须是 static，且没有 $model 属性 —— 代码跑不起来。

预防：让它读 llms.txt 的「最短可用示例」并照抄，而不是凭记忆写。

坑 2：把 validate-declaration 的全绿当成交付标准

现象：AI 看到「✅ 语法校验通过」就认为任务完成。

后果：实测中曾交付缺 3 条需求的代码。

预防：强制要求传 requirements（见动作 2）。

坑 3：参数名靠猜

现象：排序方向用了 order=desc（正确是 direction=desc）。

后果：不报错，静默返回未排序结果 —— 这是最危险的一类失败。

预防：

• 框架已加未知参数警告（响应带 warnings.UNKNOWN_QUERY_PARAM）
• 但仍建议让 AI 先看 /__ai/openapi.json 确认参数名

坑 4：引用不存在的模型

现象：生成了 use App\Models\Product，但该模型不存在。

后果：页面报错。

预防：aimanong:make-resource 命令现在会主动提示模型缺失；如果 AI 手动写代码，提醒它确认模型存在。

坑 5：拼错列名却不自知

现象：写了 customer_nmae。

后果：早期版本静默忽略该列，AI 拿不到任何反馈。

预防：框架现在会拦截并给出建议：

[GHOST_COLUMN] 声明了不存在的列/字段: column:customer_nmae
   是否想用: customer_name
   提示: 可用列: id, order_no, customer_name, ...

坑 6：宣布任务完成，但功能实际没生效

现象：AI 说"已开启导出"，但实际没调用 $grid->export()。

后果：导出接口返回 403。

预防：要求 AI 实际调用一次接口验证，而不是只检查代码。

---

四、不同场景的实操建议

场景 A：从已有数据库表建后台

最省事的路径——让 AI 用代码生成器：

请用 php artisan aimanong:make-resource {表名} --label=中文名 --register
生成 Resource，然后用 validate-declaration 校验。

生成器会自动做语义推断：

列名特征	自动生成
status / type / priority	select + badge 展示
price / amount / fee	money() 金额格式
is_* / enabled / published	switch + bool() 标签
*_at	dateTime()
email / phone / *_url	对应的字段类型

场景 B：真实业务需求（字段多、有关联）

建议把需求拆成可验收的条目给 AI，而不是一段笼统描述。

实测对比：

需求描述方式	结果
"做个商品管理"	AI 靠猜，容易漏需求
"列表要显示分类名（不是 ID）、库存少于 10 要标红、要能导出"	19 项中 17 项直接支持

经验：用业务语言描述，不要指定 API 名 —— 实测中 AI 能自己找到 tree() / $grid->export() / $form->step() 这些能力。

但验收标准必须明确，否则它也不知道做到什么程度算完成。

场景 C：关联数据展示

// 点号命名自动识别为关联列，框架自动预加载（无 N+1）
$grid->column('category.name', '所属分类');
$grid->column('product.name', '商品');

场景 D：条件样式（阈值告警）

$grid->column('stock', '库存')->dangerBelow(10);      // 少于 10 标红
$grid->column('sold_count', '销量')->warningAbove(100); // 多于 100 标橙

设计说明：条件用「运算符 + 阈值」而非闭包， 是为了保证可序列化、AI 可读、无隐式魔法。

---

五、接入方式选择

方式一：MCP（推荐）

php artisan mcp:start aimanong

适合 Claude Desktop / Cursor / Cline 等支持 MCP 的客户端。 AI 可主动调用工具查询能力，不需要你把文档塞进上下文。

方式二：把 llms.txt 给 AI

适合任何 AI 工具（ChatGPT 网页版等）。

llms.txt 已按 token 经济性优化——只包含开始工作所需的最小契约。

方式三：自省接口

curl http://localhost:8000/__ai/capabilities.json

适合你自己写脚本集成。

安全：默认仅 local / debug 开启；生产需配置 AIMANONG_AI_TOKEN。

---

六、给 AI 的提示词模板

复制即用。

模板 1：新建模块

请为数据库表 {表名} 创建后台管理 Resource。

要求：
1. Resource 类名 {Name}Resource，uri 用 {uri}，中文名「{中文}」
2. {字段A} 和 {字段B} 可搜索
3. {字段C} 可排序
4. {字段D} 必填
5. 每页 {N} 条
6. 在 app/Providers/AimanongResourceProvider.php 注册

重要：
- 先用 list-resources 和 search-docs 了解框架能力，**不要凭记忆写**
- 完成后必须调用 validate-declaration 并传 requirements 参数核对上述要求
- 如果生成失败，读错误信息里的 did_you_mean 改一次再试，不要重写整个文件

模板 2：修改现有模块

请先调用 describe-resource 确认 {uri} 的现有字段，然后：
{具体修改需求}

改完后：
1. 运行 php artisan aimanong:schema 重新生成产物
2. 调用 validate-declaration（带 requirements）
3. 实际请求一次 API 确认修改生效

模板 3：真实业务需求

我们的业务需求如下（请自行判断用框架的哪些能力实现）：

{用业务语言描述，例如：分类是树形的要能看层级；
 商品列表要能导出给运营；库存少的要能一眼看出来}

验收标准：
1. {可验证的条目}
2. {可验证的条目}

约束：
- 三个方法必须 static，无 $model 属性
- 不嵌套闭包
- 字段必须是数据库真实列

完成后请报告：哪些需求框架支持良好、哪些很别扭、哪些做不到。

最后一句很重要 —— 实测中 AI 报告"哪些很别扭"的部分， 帮我们发现了两个真实短板（关联列、条件样式）。

---

七、如何判断 AI 的产出可信

**不要只看它说"完成了"。**三层验证：

层	方法	能发现什么
1	validate-declaration + requirements	需求是否达标
2	读 resources/aimanong/schema.json	声明是否真的编译进去了
3	实际请求 API / 打开页面	是否真的生效

实测教训：第 1 层全绿不代表任务完成（校验器只查语法）； 第 2 层通过不代表功能生效（曾出现"声明了但 API 不用"的假阳性）。

只有第 3 层能证明功能真的可用。

---

八、这份手册怎么来的

• 5 轮 AI 实测：完全不了解框架的 AI，只给文档和 MCP，不给任何提示
• 1 轮真实业务场景：三表电商后台（16 字段、状态机、外键关联）
• 累计修复 21 个真实缺陷

实测数据全部公开，包括失败的轮次：

	一	二	三	四	五
一次成功率	0.5	0.5	1.0	1.0	1.0
是否读源码	读了	读了	没读	没读	没读

📖 完整实测报告

如果你发现新的坑，欢迎提 Issue —— 这类经验比功能请求更有价值。