docs: 重构项目规则与技能文档结构并更新开发指南

.trae/skills/ulthon-page-api-dual-mode/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: "ulthon-page-api-dual-mode"
+description: "指导控制器实现“页面/接口同体”。需要同一路由同时返回 HTML 与 JSON 时调用。"
+---
+
+# 页面 / 接口同体（Controller Dual Mode）
+
+## 何时调用
+
+- 希望同一个控制器方法既能渲染页面（HTML），也能作为接口返回 JSON。
+- 需要让现有页面接口在移动端/脚本调用时返回结构化数据。
+
+## 触发与认证
+
+- 触发：请求头 `Accept` 包含 `application/json`。
+- 认证：Header 传 `Authorization: Bearer <tokenContent>`。
+
+## 实现要点
+
+- 控制器方法必须调用 `$this->fetch()`，不要使用 `View::fetch()`。
+- 无论使用 `$this->assign()` 还是 `View::assign()`，其数据都会被转换为 JSON 返回。
+- 若不希望某个 assign 字段出现在 JSON 中，可使用：
+
+```php
+$this->assign('name', 'value', -1);
+```
+
+## 特殊行为
+
+- `index` 方法 GET 默认返回分页数据；如果需要返回 assign 数据，URL 增加参数 `get_page_data=1`。
+- 仅在控制器模式（Controller Mode）生效；路由模式（Route Mode）不生效。
+