区域与站点
在使用前，你需要明确区域，以确保正确的提供服务；
海外
当确认海外区域时，你后续调用服务端时，请留意：
国内
当确认国内区域时，你后续调用服务端时，请留意：
cms 优先策略
- 优先使用 CMS：CMS 接口无需 cookie，且数据与主站一致；后续接口介绍环节，都会告知对应接口在 cms 是否支持
- 所有 API 均为 POST 请求，返回 JSON
- 在 cms 不支持的场景下，需使用对应的主站 API
- 并非所有时候 cms 都会正确返回，cms 仅在部分内部网络时可用，因此，在使用 cms api 时，如果超过 5s 未返回数据，你可以认为 cms 不可达，转而使用主站 API 进行请求
自动推断区域逻辑
- 你需要根据线索自动判断用户预期访问的区域
- 通常用户在连续的和你对话过程中，不会在两个区域来回切换，所以一旦你识别了区域，在连续对话中，具有稳定性
- 在用户有和你发送链接的场景下，你可以从链接上很容易识别出区域，比如链接上有 I18N 的代表海外，有 CN 的代表国内
- 如果用户在对话中提及了关键词例如小云雀代表国内，而 pippit 代表海外
- 如果实在无法推断，比如用户说生成一个小红帽和大灰狼的视频，你很难判断是海外还是国内，此时，你可以看看
本文件同目录下的 xyq.config.json 的配置文件中，海外的还是国内的相关配置是完整的，优先用完整的；
- 如果以上都无法判断，你可以主动询问用户是想访问海外站点，还是国内站点
秘钥的管理
- 访问 API 所需的秘钥们，保存在
本文件同目录下的 xyq.config.json 下，他们的更新周期长，他们都衍生自用户浏览器上的 cookie，换言之，当用户提供了关键的 cookie，即 本文件同目录下的 xyq.config.json 中的 oversea.sid_tt 或 domestic.sessionid_pippitcn_web 后，其他信息都可以通过相应的接口请求获取到
- 后续提到 config、config.json，默认都是指的
本文件同目录下的 xyq.config.json
- 如果
本文件同目录下的 xyq.config.json 路径不存在，说明是初始化场景，你需要帮我创建出来，该 config 文件的初始态如下：
{
"oversea": {
"sid_tt": "",
"uid": "",
"workspace_id": "",
"space_id": ""
},
"domestic": {
"sessionid_pippitcn_web": "",
"uid": "",
"workspace_id": "",
"space_id": ""
}
}
- 当遇到 401 错误、用户未登录、用户不存在、无权限等，需提醒用户重新获取 cookie：
- 当你收到用户给你的 cookie，你需要更新到
本文件同目录下的 xyq.config.json 中，在 本文件同目录下的 xyq.config.json 里路径分为：
- 海外：
oversea.sid_tt
- 国内：
domestic.sessionid_pippitcn_web
生成历史链接解析
有时候，用户会分享给你一个生成历史的链接，其 url 种包含 /generate-history，如下：
https://pippit-cms.bytedance.net/#/generate-history?generate_id=xxx®ion=I18N&user_id=xxx
虽然它域名是 bytedance.net，但它并不是上文提及的 cms api，但是它是一个 cms 管理后台的链接;
用户发送这个链接，通常是想指代一次生成任务，你只需要提取其中的关键信息
- generate_id = thread_id
- region 指的是区域
你可以通过 API /v1/agent/get_thread 来获取本 thread 的详情，然后回答用户的问题
用户生成要求
生图生视频
当用户向你发出一个生图或者生视频的要求时，比如用户说 “帮我生成一张豆浆的图片”，此时你应该：
- 如果用户的指令里，没有很明确的意图是要生成图片还是视频，你需要询问用户
- 通过 /v1/agent/submit_run 的方式提交用户的请求，提交内容最好能明显识别出来是要生图还是生视频
- 检查提交结果，如果有异常，告诉用户
- 如果提交成功，则启动一个 subagent (spawn 一个新 session) 去查询生成结果，因为结果需要轮询，且视频场景通常很慢；
- 轮询结果的方式是使用 /v1/agent/get_thread api 来查询；所查询的 thread 即你刚才 submit_run 时的 thread；
- 在每次轮询回来的数据里，你需要留意的是刚才 submit_run 对应的 run_id 的数据，判断 run 是否达到终结态，否则需要一直轮询 (当然，最多 10 分钟没结果就算了)，轮询频次可以是 20s 这样的间隔
- 当达到终结态时，你需要把对应 run 的 assistant 消息里的信息或者生成产物(asset_id 和下载链接) 告诉用户
- 如果达到终结态，如果没有结果，而是返回了别的信息，比如 questionaire 等，你也需要告知用户
- 由于这些轮询行为你会扔个一个 subagent 来处理，请记住告诉它充足的信息，比如如何请求接口，建议当达成终结态后，让 subagent 返回完整的 thread 数据给你，以便你做出准确的响应
当用户要延续之前某次 thread 继续对话时，你只需 /v1/agent/submit_run 在延续之前的 thread_id，其他逻辑和上述要求一样。
记住如果用户有生图生视频指令，无论成功与否，你都要回复用户，给用户通知；通知用户时，如果有产物链接，请以 markdown 格式回复给用户
API 接口
获取 uid workspace_id space_id 等信息
注：并非所有 API 调用场景都需要 uid workspace_id space_id，你只需遵循 API 要求，按需获取这些信息。
当需要这些信息事，你可以：
- 可以先判断
本文件同目录下的 xyq.config.json 中是否有 uid、workspace_id、space_id 等信息，如果有，直接使用；如果没有，需要先获取一次，然后保存到 本文件同目录下的 xyq.config.json 中；
- 注意，oversea 和 domestic 是不一样的，他们在
本文件同目录下的 xyq.config.json 中的存放位置也不一样
当 本文件同目录下的 xyq.config.json 中没有相关信息，或者你使用接口明确这些信息不可用时候，你可以通过以下方式来获取/更新它们：
国内获取 uid workspace_id space_id 等信息的流程
- uid 获取：通过 post
https://xyq.jianying.com/commerce/v1/subscription/user_info，携带 sessionid_pippitcn_web cookie，另外 body 里放入 "aid" : 795647，然后从返回的数据中获取 uid
- workspace_id 和 space_id 获取：通过 post
https://xyq.jianying.com/api/web/v1/workspace/get_user_workspace，body 里放入 {uid}，以及 header 携带 sessionid_pippitcn_web cookie，然后从返回的数据中获取 workspace_id 和 space_id
海外获取 uid workspace_id space_id 等信息的流程
- uid 获取：通过 get
https://www.pippit.ai/home，一定要注意的是，get 的时候，headers 的 cookie 里一定要携带 sid_tt 这个 cookie，从你获得的 html 数据中，找到 __userInfoStringify 字符串，这个字符串内部，有 user_id (即为 uid)、workspace_id、space_id 等信息 (由于这个 html 有 200k 字符，建议你启一个 subagent 专门获取)
/v1/agent/get_thread
- 作用：查询 thread_id 详情
- cms 支持
- 参数：
- scopes:
["run_list.entry_list"]（固定）
- thread_id: 必填，未提供则询问用户
- 返回关注：data.thread.run_list 内的数据
关于 /v1/agent/get_thread 返回数据的详述
当你获得了 /v1/agent/get_thread 的返回的 json 数据后，你可以按以下方式，了解其中的信息：
- 名词解释：所谓 thread 即在一个对话窗口里的一轮或多轮对话，而每一轮对话，为一个 run
- 拿到数据后，你首先你需要进入 data.thread.run_list 里，所有的 run 数据都在这里了，所以这是最关键的数据
- log_id：从返回数据中，找到最后一条 execute_log_id，即为 log_id，其实每一轮 run 都有个 log_id，如果没特殊指明，默认取最后一条 run 的 log_id
- 每个 run 里，有多个 message，其中 role 代表消息的发送者，user 代表用户，assistant 代表助手，而 tool 则是中间调用的工具；
- 每个 run 都有个 state，state 的取值为 1、2、3、4、5，分别表示 run 的状态：
- 1: Submitted（已提交）
- 2: Working（正在处理中）
- 3: Completed（[终态]已完成）
- 4: Failed（[终态]已完成但失败）
- 5: Canceled（[终态]在完成前被取消）
- 通常，你只需要关心最后一个 run 的状态，因为前序 run 通常是终结态，因为不终结，无法启动后续的 run
- message 中，有很多 part，生成的视频、图片产物也在这些 part 里，如 biz/x_data_video、biz/x_data_image 等，你需要关注其中的 asset_id 和 download_url；asset_id 是视频、图片的唯一标识，download_url 是下载视频、图片的 url；
/v1/agent/submit_run
- 作用：向 agent 提交消息/请求，通常用于生成图片、视频
- 前置依赖：uid、workspace_id、space_id，请先确保获取了
- cms 不可用
当你明确要提交的消息后，可以调用本文件同级 scripts/generate_submit_run_body.sh 脚本，生成提交的请求体，然后发送即可；注意，该脚本执行时，-r domestic 表示国内站 -r oversea 表示海外站，-p 是要提交的消息
关于 thread_id 如何获取：如果你是要在之前已经存在的对话中，继续提交内容，则要延续之前的 thread_id，在 scripts/generate_submit_run_body.sh 时，可额外提供 -t 参数提供你要延续的 thread_id；但如果是新对话场景，则无需提供
agent 生成的内容，并不会在 post 请求后返回，因为是一个异步的过程；例如，生成视频可能需要几分钟，而生成图片可能需要几十秒；所以，如果你需要获取内容，则要通过 /v1/agent/get_thread 接口查询；记住，你需要记得刚才的 thread_id 是啥，因为查询时，你需要提供 thread_id，才能获取到对应的内容
这个接口查询到的数据，自然包含你刚才提交的 message;
