docs(agents): 修正 /api/item 示例(嵌套形状)+ 补 /api/item/delete(DELETE + body)

实测发现手册里两处错误(部署 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 或源码里的处理函数。
This commit is contained in:
HomeDash Bot
2026-09-12 11:46:28 +08:00
parent 890af22b95
commit e0e79c98da

View File

@ -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"