\r \r

ht-skills 灏天文库管理（客户端）\r

\r 通过服务端 API 调用，需配置 config.json 中的token（个人 API Token）。\r \r ---\r \r

客户端注意事项（必须遵守）\r

\r

• 查询文集列表：无 --limit、--offset。\r
• 查询文档列表：必须带 --collection-id（文集 ID）；若没有文集 ID，需先 list_collections.py --name "文集名称" 查询，或向用户询问目标文集名称。\r
• 查询文档列表：无 --limit、--offset。\r
• 更新文档：author 字段不可更新，只能更新 name、content、sort、parent。\r
• 修改文档归属：需有目标文集权限；文档属于多个文集时需指定 --from-collection-id。\r
• 图片上传：需本地可读图片路径；大文件上传耗时较长。上传成功后响应中的 file_url 可直接用于正文插图。\r
• 图片分组：使用 --group-id 前可用 list_image_groups.py 查询分组 ID；分组必须属于当前用户。\r \r ---\r \r

智能体执行规范（必须遵守）\r

\r

规范一：修改特定文档\r

\r

1. 先查询：使用 list_documents.py --collection-id \x3C文集ID> --name "关键词" 或 get_document.py --id \x3CID> 定位要修改的文档，确认文档 ID。\r
2. 再修改：使用 update_document.py --id \x3CID> 修改标题、正文。\r \r

规范二：添加特定文档\r

\r

1. 文集必填：用户必须提供目标文集。若用户未提供或只说「随便加」「你决定」等，必须主动询问：「请告知要将文档添加到的文集名称」。\r
2. 查询文集 ID：用户给出文集名称后，用 list_collections.py --name "文集名称" 查询文集 ID；若不存在则询问是否新建。\r
3. 添加文档：使用 add_document.py --collection-id \x3CID> --name "标题" [--content 内容] [--content-file 文件路径]。\r \r

规范三：添加文集\r

\r

1. 用户确认：新建文集前必须让用户确认要创建的文集名称，例如：「将创建文集「xxx」，请确认名称是否正确？」。\r
2. 确认后再执行：用户确认后再执行 create_collection.py --name "文集名称"。若使用 --get-if-exists 则同名已存在时直接返回已有 ID，不重复创建。\r \r

规范四：修改文档归属\r

\r

1. 先定位文档：用 list_documents.py --collection-id \x3C文集ID> --name "关键词" 或 get_document.py --id \x3CID> 确认文档 ID。\r
2. 确认目标文集：用户需提供目标文集名称或 ID；若无则 list_collections.py --name "关键词" 查询。\r
3. 执行移动：使用 move_document.py --id \x3C文档ID> --collection-id \x3C目标文集ID>；文档属于多个文集时需加 --from-collection-id \x3C原文集ID>。\r \r

规范五：上传图片并用于文档\r

\r

1. 可选分组：若用户要归类图片，先 list_image_groups.py 或 create_image_group.py --name "分组名" 取得 group_id。\r
2. 检查额度（可选）：get_image_limits_usage.py 确认 can_upload。\r
3. 上传：upload_image.py --file "路径" [--remark "说明"] [--group-id N]。\r
4. 使用链接：从返回 JSON 的 data.file_url（或 data.file_path 自行拼域名）插入文档 Markdown/HTML；勿猜测 URL。\r \r ---\r \r

前置条件\r

\r

1. config.json：在 client 目录配置 config.json，填写token。\r
2. 环境变量（可选）：HT_SKILL_SERVER_URL、HT_SKILL_TOKEN 优先级高于 config.json。\r
3. 依赖：pip install requests\r \r

脚本目录\r

\r 所有脚本位于 scripts/，在 client 根目录执行。\r \r

功能一：新建文集（支持有则用、无则建）\r

\r

python scripts/create_collection.py --name "文集名称" [--description "50字内简介"] [--brief "500字以上详细介绍"]\r
python scripts/create_collection.py --name "文集名称" --get-if-exists\r
```\r
\r
## 功能二：新建文档到指定文集\r
\r
```bash\r
python scripts/add_document.py --collection-id 123 --name "文档标题" [--content "正文"] [--content-file 路径] [--parent 0]\r
```\r
\r
## 功能三：查询文集列表\r
\r
```bash\r
python scripts/list_collections.py [--name "关键词"]\r
```\r
\r
## 功能四：查询文集详情\r
\r
```bash\r
python scripts/get_collection.py --id 123 [--include-docs]\r
```\r
\r
## 功能五：查询文档列表\r
\r
```bash\r
python scripts/list_documents.py --collection-id 123 [--name "关键词"]\r
# collection-id 必填。若无文集 ID，需先 list_collections 查询或向用户询问\r
```\r
\r
## 功能六：查询文档详情\r
\r
```bash\r
python scripts/get_document.py --id 456\r
```\r
\r
## 功能七：更新文档（修订已发文章）\r
\r
```bash\r
python scripts/update_document.py --id 456 --name "新标题"\r
python scripts/update_document.py --id 456 --content "新正文"\r
python scripts/update_document.py --id 456 --content-file 文件路径\r
python scripts/update_document.py --id 456 --sort 50\r
python scripts/update_document.py --id 456 --parent 0\r
```\r
\r
## 功能八：修改文档归属（移动到目标文集）\r
\r
```bash\r
# 将文档移动到目标文集\r
python scripts/move_document.py --id 456 --collection-id 789\r
\r
# 文档属于多个文集时，需指定原文集 ID\r
python scripts/move_document.py --id 456 --collection-id 789 --from-collection-id 123\r
```\r
\r
- `--id`：文档 ID（必填）\r
- `--collection-id`：目标文集 ID（必填）\r
- `--from-collection-id`：原文集 ID；文档只属于一个文集可不填，属于多个文集则必填\r
\r
## 功能九：设置文档父级（文集内层级）\r
\r
```bash\r
python scripts/set_document_parent.py --collection-id 123 --document-id 456 --parent 0 [--sort 1]\r
```\r
\r
- `parent=0` 表示根文档；同级别 `sort` 越小越靠前\r
\r
## 功能十：查询当前用户个人花园限制与用量\r
\r
```bash\r
python scripts/get_garden_limits_usage.py\r
```\r
\r
- 无参数，返回当前用户的花园限制与占用情况\r
- 占用字段使用更直观的 `已用/上限` 结构（如 `3/10`、`18/100`）\r
\r
## 功能十一：图片分组\r
\r
```bash\r
python scripts/create_image_group.py --name "分组名称"\r
python scripts/list_image_groups.py [--limit 100] [--offset 0]\r
python scripts/update_image_group.py --id \x3C分组ID> --name "新名称"\r
```\r
\r
## 功能十二：图片上传与查询\r
\r
```bash\r
python scripts/get_image_limits_usage.py\r
python scripts/upload_image.py --file "图片路径" [--remark "备注"] [--group-id N]\r
python scripts/list_images.py [--group-id N] [--name "文件名关键词"] [--limit 50] [--offset 0]\r
python scripts/get_image.py --id \x3C图片ID>\r
```\r
\r
- 上传成功后的 `data.file_url` 为可访问地址（依赖服务端 `cos.public_base_url` 或 `cos.domain` 配置）\r
- `list_images.py` 的 `--name` 对应服务端查询参数 `file_name`（文件名模糊匹配）\r