From e0e79c98da9d6f2d34acd4d2691b091e6ec136ec Mon Sep 17 00:00:00 2001
From: HomeDash Bot <bot@jianfgit.xyz>
Date: Sat, 12 Sep 2026 11:46:28 +0800
Subject: [PATCH] =?UTF-8?q?docs(agents):=20=E4=BF=AE=E6=AD=A3=20/api/item?=
 =?UTF-8?q?=20=E7=A4=BA=E4=BE=8B=EF=BC=88=E5=B5=8C=E5=A5=97=E5=BD=A2?=
 =?UTF-8?q?=E7=8A=B6=EF=BC=89+=20=E8=A1=A5=20/api/item/delete=EF=BC=88DELE?=
 =?UTF-8?q?TE=20+=20body=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

实测发现手册里两处错误（部署 it-tools 时踩到）：
1. /api/item 是嵌套形状 {"sectionIndex":N,"item":{...}}，
   扁平 {"name","url"} 会被拒绝并返回 "title and url required"
2. /api/item/delete 要求 **DELETE** 且 body 带 {"sectionIndex","itemIndex"}，
   用 POST 会得到 "method not allowed"

同时补上"分组下标怎么取"的可执行片段，并写明：文档里的示例必须实测过，形状
不确定时先读 /api/schema 或源码里的处理函数。
---
 AGENTS.md | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/AGENTS.md b/AGENTS.md
index d45a80c..e9a7986 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -180,8 +180,19 @@ curl -s -X POST -H "Authorization: Bearer $TOK" "$A/gateway/apply"
 # 导航分组 / 条目
 curl -s -X POST -H "Authorization: Bearer $TOK" -H 'Content-Type: application/json' \
   -d '{"name":"常用服务"}' "$A/section"
+# 导航条目是**嵌套形状**（实测：扁平 {"name","url"} 会返回 "title and url required"）：
+#   先查分组下标，再提交 {"sectionIndex":N,"item":{...}}
+IDX=$(curl -s -H "Authorization: Bearer $TOK" "$A/sections" | \
+      python3 -c 'import sys,json;d=json.load(sys.stdin);print([i for i,s in enumerate(d) if s["name"]=="常用服务"][0])')
 curl -s -X POST -H "Authorization: Bearer $TOK" -H 'Content-Type: application/json' \
-  -d '{"name":"我的应用","url":"https://app.example.com","section":"常用服务","icon":"auto"}' "$A/item"
+  -d "{\"sectionIndex\":$IDX,\"item\":{\"title\":\"我的应用\",\"url\":\"https://app.example.com\",\"icon\":\"auto\",\"description\":\"说明\"}}" "$A/item"
+
+# 删除条目：**DELETE + JSON body**（POST 会返回 method not allowed），下标从 /sections 里数
+curl -s -X DELETE -H "Authorization: Bearer $TOK" -H 'Content-Type: application/json' \
+  -d '{"sectionIndex":0,"itemIndex":4}' "$A/item/delete"
+
+> 形状不确定时先取 `GET /api/schema`（§4.1）或读 `admin-server/main.go` 里的处理函数：
+> 本手册初版就把 `/api/item` 写成了扁平形状，实测被拒——**文档里的示例必须实测过**。
 
 # 壁纸 / 门户口令 / 历史
 curl -s -X POST -H "Authorization: Bearer $TOK" -H 'Content-Type: application/json' -d '{"url":"https://x/bg.jpg"}' "$A/wallpaper"