fangcloud-api skills
by @jiema123
Automation skill for fangcloud-api skills.
clawhub install fangcloud-ai📖 About This Skill
name: fangcloud-ai description: 亿方云 (Fangcloud) AI 能力集成 Skill。支持文件管理（列表、上传、下载、分享）、协作邀请、知识库对话 (DeepSeek) 以及智能体交互。当用户需要操作亿方云文件、查询最近文档或创建分享链接时，使用此 Skill。
Fangcloud AI Skill
此 Skill 允许通过亿方云开放平台 API 执行各类操作。
配置说明
Skill 自动从环境变量获取 Token：
FANGCLOUD_ADMIN_TOKEN: 用于 URL 中包含 admin 的企业级接口。FANGCLOUD_USER_TOKEN: 用于普通用户级接口。运行环境要求
cli/ 目录中，避免影响 skill 本身目录结构。FANGCLOUD_USER_TOKEN
- FANGCLOUD_ADMIN_TOKEN，仅当访问 admin URL 时需要
cli/release/ 目录中的对应平台原始二进制文件。环境与二进制对应关系
arm64 机器上优先发 amd64 版本。https://app.fangcloud.com/sync/vv25/knowclaw/release/平台选择
amd64:https://app.fangcloud.com/sync/vv25/knowclaw/release/fangcloud-windows-amd64.exe
arm64:https://app.fangcloud.com/sync/vv25/knowclaw/release/fangcloud-windows-arm64.exe
amd64:https://app.fangcloud.com/sync/vv25/knowclaw/release/fangcloud-macos-amd64.zip
arm64:https://app.fangcloud.com/sync/vv25/knowclaw/release/fangcloud-macos-arm64.zip
amd64:https://app.fangcloud.com/sync/vv25/knowclaw/release/fangcloud-linux-amd64.zip
arm64:https://app.fangcloud.com/sync/vv25/knowclaw/release/fangcloud-linux-arm64.zip如何判断环境
$env:PROCESSOR_ARCHITECTURE
- 常见结果：AMD64、ARM64
uname -m
- 常见结果：x86_64、arm64
uname -m
- 常见结果：x86_64、aarch64使用规则
fangcloud-macos-arm64，不要默认发 Intel 版。.exe 文件。amd64；如果确认是 ARM 设备，再切到 arm64。自动识别并下载
./cli/scripts/download_release_binary.sh
- Windows PowerShell: .\cli\scripts\download_release_binary.ps1
zip 保存到 cli/release/
- 解压后的二进制保存到 cli/bin/
.exe 保存到 cli/release/
bash）:os="$(uname -s)"; arch="$(uname -m)"; base="https://app.fangcloud.com/sync/vv25/knowclaw/release"; case "$os" in Darwin) [ "$arch" = "arm64" ] && file="fangcloud-macos-arm64.zip" || file="fangcloud-macos-amd64.zip" ;; Linux) [ "$arch" = "aarch64" ] && file="fangcloud-linux-arm64.zip" || file="fangcloud-linux-amd64.zip" ;; *) echo "unsupported os: $os"; exit 1 ;; esac; curl -fL "$base/$file" -o "$file"
$base="https://app.fangcloud.com/sync/vv25/knowclaw/release"; $arch=$env:PROCESSOR_ARCHITECTURE; if ($arch -eq "ARM64") { $file="fangcloud-windows-arm64.exe" } else { $file="fangcloud-windows-amd64.exe" }; Invoke-WebRequest "$base/$file" -OutFile "$file"Go 版 CLI
fangcloud api [DATA_JSON]
- fangcloud chat [--agent-id ID] [--type TYPE] [--libs LIBS] [--no-stream]
- fangcloud organize [--folder-id ID | --folder-url URL] [--mode move|copy] [--dry-run]
- fangcloud upload [--remote-root PATH | --remote-parent-id ID] [--conflict-strategy overwrite|rename] [--include-hidden] [--dry-run] 核心功能与接口参考
详细接口定义请参考 references/openapi.md。
1. 最近使用的文件
GET /v2/file/recent_itemslimit 参数，否则接口可能返回 500 错误。 例如：/v2/file/recent_items?limit=20。2. 搜索文件
GET /v2/item/searchquery_words, sort_by=modified_at, sort_direction=desc。3. 获取用户信息
GET /v2/user/info4. 创建分享链接
POST /v2/share_link/create5. 预览与在线编辑 (URL 构造)
https://v2.fangcloud.com/desktop/files/recent?preview={file_id}https://v2.fangcloud.com/desktop/files/recent?preview={file_id}&fv=1&online=16. 知识库与智能体 (DeepSeek)
POST /v2/kbase/chatStream (支持 gptType: "deepseek")POST /v2/kbase/create_libraryPOST /v2/kbase/create_documentPOST /v2/kbase/list_libraryPOST /v2/kbase/list_documentPOST /v2/kbase/upload_file（先拿上传地址并完成文件上传）POST /v2/kbase/publish_file（library_id + files，其中 files[*].document_id 与 files[*].book_id 必填）POST /v2/knowledge/chatStreamGET /v2/knowledge/list安全要求（知识库 / 智能体返回内容）
常用工作流
查找并处理文件
1. 调用 GET https://open.fangcloud.com/api/v2/item/search 搜索文件。
2. 根据返回的 id 构造预览或编辑 URL。
实用场景 (Practical Scenarios)
1. 文件搜索下载
目标: 根据用户关键词查找文件，并将其下载到本地。 执行流程:
1. 调用 GET /v2/item/search（参数 query_words=<关键词>）查询目标文件的 file_id。
2. 调用 GET /v2/file/{file_id}/download_v2 或相应下载接口获取文件的真实下载链接。
3. （可选）使用本地工具将获取到的链接内容下载并保存为本地文件。
2. 文件夹创建及文件上传到个人空间
目标: 在个人空间创建专属文件夹，并将本地文件上传至该目录。 执行流程:
1. 调用 GET /v2/folder/personal_items 获取个人空间的目录信息，确认目标父文件夹 ID（通常根目录为 0 或根据接口返回判断）。
2. 调用 POST /v2/folder/create（参数 name=<文件夹名>, parent_id=<个人空间ID>）创建目标文件夹，并记录返回的 id。
3. 调用上传接口（如 POST /v2/file/upload_v2 或 POST /v2/file/upload_by_path），将本地文件上传到刚创建的文件夹下。
3. 文件搜索，创建分享
目标: 查找指定文件，并为该文件生成对外分享链接。 执行流程:
1. 调用 GET /v2/item/search 搜索并获取目标文件的 file_id。
2. 调用 POST /v2/share_link/create，传入对应的 file_id。可根据需求设置必要的权限参数（如提取码、有效期限等）。
3. 提取接口返回的分享 url 和密码，并呈现给用户。
4. 文件夹搜索创建收集场景 (没有就补全)
目标: 查找是否存在指定名称的“收集文件夹”，如果存在则使用该文件夹创建收集任务，如果不存在则自动创建文件夹后再创建收集任务。 执行流程:
1. 调用 GET /v2/item/search（设置 type=folder，传入名称）搜索目标文件夹。
2. 若找到目标文件夹，提取其 folder_id；若未找到，调用 POST /v2/folder/create（在个人空间或指定目录）创建该文件夹并获取 folder_id。
3. 调用 POST /v2/collection/create（传入 target_folder_id、name 等参数）为该文件夹创建公网收集任务。
4. 提取接口返回的收集任务链接（如提取接口返回的收集 URL 或其他标识），提供给用户用于文件收集。后续可通过 GET /v2/collection/get_files_info 查询收集状态。
5. 云盘文件自动分类与整理 (NEW)
目标: 自动识别指定目录中的文件类型，创建分类目录并将文件移动或复制到对应目录中。 执行流程:
1. 获取 ID: 从用户提供的 URL（如 preview={id}）或直接提供的 ID 中提取目标文件夹 ID。
2. 读取列表: 调用 GET /v2/folder/{id}/children 获取目录下所有文件列表。
3. 智能分类: 分析文件后缀或名称（如 .pdf、.docx、.xlsx、.jpg），制定分类方案（如“文档”、“图片”、“表格”）。
4. 用户确认: 向用户展示分类建议，并询问是执行“移动 (Move)”还是“复制 (Copy)”。
5. 执行整理:
- 调用 POST /v2/folder/create 创建分类子文件夹。
- 遍历文件，根据用户选择调用 POST /v2/file/{id}/move 或 POST /v2/file/{id}/copy 将其分配到对应目录。
6. 结果反馈: 整理完成后通知用户结果。
6. 云盘使用周报自动生成 (NEW)
目标: 通过分析最近操作的文件，生成用户的使用周报，并提供优化建议。 执行流程:
1. 获取数据: 调用 GET /v2/file/recent_items?limit=50 获取最近操作的文件列表（尽可能多抓取）。
2. 时间筛选: 根据当前时间戳，统计本周（通常为过去 7 天）操作过的文件。
3. 内容分析:
- 提取文件名、类型、修改时间。
- 使用 AI 总结本周的工作重心（如：“本周主要在处理产研相关的 Excel 文档”）。
- 统计文件分布（如：修改了 5 个表格，创建了 2 个 PDF）。
4. 生成周报:
- 本周回顾: 总结操作的文件类型、项目相关性。
- 工作重心: 自动识别最常操作的文件所属项目。
- 使用建议: 根据使用习惯提供建议（如：“建议将本周频繁修改的文档归档到特定项目文件夹”）。
5. 呈现报告: 将汇总结果以 Markdown 格式呈现。
7. 知识库文件入库（新建库 / 已有库）
目标: 将本地文件上传到知识库指定目录，兼容“新建知识库”和“上传到已有知识库”两种流程。 执行流程:
1. 新建知识库标准流程:
- 调用 POST /v2/kbase/create_library 创建知识库，拿到 library_id。
- 调用 POST /v2/kbase/create_document（library_id + parent_document_id=0 + name）创建知识目录，拿到 document_id。
- 调用 POST /v2/kbase/upload_file（library_id + document_id + file_name + file_size）获取上传地址，按返回地址真正上传文件（header 带 x-file-name）。
- 从上传阶段结果中提取 book_id，调用 POST /v2/kbase/publish_file 发布文件。发布请求体中 files[*].document_id 和 files[*].book_id 必填。
2. 上传到已有知识库流程:
- 先调用 POST /v2/kbase/list_library 查询并定位目标知识库 library_id（按名称或业务标识筛选）。
- 再调用 POST /v2/kbase/list_document（传 library_id 和目标父级 document_id，根目录传 0）查询目标知识目录列表，定位 document_id。
- 若目录不存在，可补调 POST /v2/kbase/create_document 创建后再上传。
- 调用 POST /v2/kbase/upload_file 上传文件，拿到并记录 book_id。
- 调用 POST /v2/kbase/publish_file 完成发布。
3. 发布请求体最小示例:
- POST /v2/kbase/publish_file
- body:
{
"library_id": "21b9c123e95200691bd6d4a73a9994f",
"files": [
{
"document_id": "1221900719926288472",
"book_id": "1221904085922373661"
}
]
}
执行工具
优先使用下载后的 Go 二进制，按环境匹配后直接运行。
./cli/scripts/download_release_binary.sh
- 二进制会落到 cli/bin/
- 之后直接运行 ./cli/bin/fangcloud-macos-arm64 ... 或 ./cli/bin/fangcloud-linux-amd64 ...
- 如需直接输入命令名，可执行 export PATH="$(pwd)/cli/bin:$PATH"
.\cli\scripts\run_release_binary.ps1 ...
- Windows 保持脚本入口方式，不改成 bin 目录直跑客户使用方式
./cli/scripts/download_release_binary.sh
- ./cli/bin/fangcloud-macos-arm64 api GET /v2/user/info
- 或先执行 export PATH="$(pwd)/cli/bin:$PATH"，再运行 fangcloud-macos-arm64 api GET /v2/user/info
.\cli\scripts\run_release_binary.ps1 api GET /v2/user/infoCLI 子命令
api [DATA_JSON] ./cli/bin/fangcloud-macos-arm64 api GET /v2/user/info
- 示例(macOS/Linux): fangcloud-linux-amd64 api POST /v2/share_link/create "{\"file_id\":123}"
- 示例(Windows): .\cli\scripts\run_release_binary.ps1 api GET /v2/user/info
- URL 支持完整地址，也支持仅传 /v2/... 或 v2/...，默认会补成 https://open.fangcloud.com/api
chat "你的问题" [--agent-id ID] [--type TYPE] [--libs LIBS] fangcloud-macos-arm64 chat "你好" --agent-id 3776
- 示例(macOS/Linux): fangcloud-linux-amd64 chat "帮我总结文档" --type AI_LIBRARY --libs 123,456
organize [--folder-id ID | --folder-url URL] [--mode move|copy] [--dry-run] fangcloud-macos-arm64 organize --folder-id 501007507161 --mode move
upload [--remote-root PATH | --remote-parent-id ID] [--conflict-strategy overwrite|rename] [--include-hidden] [--dry-run] fangcloud-linux-amd64 upload ~/dev/workspace/file-check-workspace --dry-run兼容说明
分发方式
cli/release/ 中对应平台的原始二进制文件。