【中国域名 .cn】Agnes AI 接入 WorkBuddy · 零基础向导（生图 + 生视频）
> 节点标签：中国域名 .cn 节点（国内站） · 文本生图 / 文生视频 / 图生视频
> 给谁用：零基础 AI 爱好者，一步步把 Agnes AI 接进 WorkBuddy，既能生图、又能生视频。
> 🔒 安全承诺：本技能包不含任何 API 密钥。密钥由你自己去官网创建，只在你本机 ~/.workbuddy/.apikeys.env 里保存。
> 同系列：国际站（.com）是另一个独立包 yrns-agnes-gen-com，密钥平台（platform.agnes-ai.com）与 API 主机（api.agnes-ai.com / apihub.agnes-ai.com）都不同，两个包用各自的 AGNES_* / AGNES_COM_* 变量，互不干扰。
一、它能做什么
Agnes AI 国内站（.cn）接入后，你可在 WorkBuddy 里：
- 写文案 / 推理：文本模型 agnes-2.5-flash
- 文本生图 / 图生图：agnes-image-2.1-flash
- 文生视频 / 图生视频：agnes-video-v2.0（异步任务，自动轮询）
> 官方文档：https://agnes-ai.cn/zh-Hans/docs/ ｜ 国内 API 平台：https://platform.agnes-ai.cn
> ⚠️ 域名/节点提醒（最容易踩坑，先读完）：Agnes 国内存在多个 API 节点，且 Key 与节点是绑定的，用错节点必然 401（如 api.agnes-ai.cn 与 apihub.agnes-ai.cn）。但你不用自己选——本技能的接线脚本会自动探测你这把 Key 属于哪个节点并写入配置。
二、零基础第一步：打开官网，自己创建 API 密钥
- 打开官方 API 平台：👉
https://platform.agnes-ai.cn→ 注册 / 登录。 - 进入「API Key 管理」→ 点「创建 API Key」。
- 立即复制 ⚠️：密钥以
sk-开头，只显示一次，关掉页面就只能重新生成。先存进记事本备用。
> 🔒 安全提醒：密钥是你的私人凭证，不要发到聊天框或公开仓库。接线后它会写进你本机两处：~/.workbuddy/.apikeys.env（仅存密钥）与 ~/.workbuddy/models.json（WorkBuddy 调用模型所必需，含明文 key）。两处文件接线脚本都会收紧为仅当前用户可读写；请勿把 models.json 分享或提交到仓库。
三、零基础第二步：让技能帮你接进 WorkBuddy
python "C:\Users\Administrator\.workbuddy\skills\yrns-agnes-gen\scripts\wire_agnes.py"
运行后会让你粘贴密钥（输入时不显示）；或避免进命令行历史：
python "C:\Users\Administrator\.workbuddy\skills\yrns-agnes-gen\scripts\wire_agnes.py" --key-file "C:\Users\Administrator\Desktop\agnes_key.txt"
脚本自动完成（你什么都不用管）：
1. 逐个探测候选节点（/models 看谁返回 200），选中你 Key 所属的正确节点——避免 401。
2. 写 ~/.workbuddy/.apikeys.env → AGNES_API_KEY=sk_... + AGNES_BASE_URL=<探测到的节点>
3. 写 ~/.workbuddy/models.json → 新增/更新 agnes-2.5-flash 文本模型（聊天框下拉可选）
4. 联网验证，只打印 HTTP 状态与尾号指纹，绝不回显完整密钥
看到 [完成] Agnes AI 已接入 WorkBuddy 即成功。
四、零基础第三步：生图 / 生视频
生图（文生图，可下载到本地）：
python "C:\Users\Administrator\.workbuddy\skills\yrns-agnes-gen\scripts\generate_image.py" ^
--prompt "一座赛博朋克风格的城市夜景，霓虹灯闪烁，雨水反射蓝紫光影" ^
--size 1024x1024 --download --output "C:\Users\Administrator\Desktop\agnes_img.png"
生视频（文生视频 / 图生视频，异步轮询 + 可下载）：
python "C:\Users\Administrator\.workbuddy\skills\yrns-agnes-gen\scripts\generate_video.py" ^
--prompt "一只猫在夕阳下的海滩上散步，海浪轻拍，暖金色光线" ^
--width 1152 --height 768 --num-frames 121 --frame-rate 24 --download ^
--output "C:\Users\Administrator\Desktop\agnes_video.mp4"
- 图生视频：在上面的命令里加
--image <公开可访问的图片 URL>。 - 生图/生视频模型的精确名字（拼错会 503）：生图
agnes-image-2.1-flash、生视频agnes-video-v2.0。
五、故障排查（速查）
| 现象 | 根因 | 处理 |
|---|---|---|
| 新 Key 报 401，但 Key 确实有效 | 节点用错（Key 与节点绑定） | 重跑带自动探测的 wire_agnes.py；或显式 --base-url https://api.agnes-ai.cn/v1 |
| 脚本报"未找到 API Key" | .apikeys.env 未写 / wire 没跑 |
重跑 wire_agnes.py 写入 AGNES_API_KEY |
| 生图模型 503 | 模型名拼错（多加后缀） | 用精确名 agnes-image-2.1-flash，或换 agnes-image-2.0-flash |
国内 .cn 生视频偶发 403/503 |
国内节点视频不稳定 | 重试；或直接在网页版 agnes-ai.cn 做视频 |
六、接口要点（给想深入了解的人）
| 能力 | 方法 / 路径 | 关键参数 |
|---|---|---|
| 生图 | POST {base}/images/generations |
model, prompt, size, n；返回 data[].url |
| 创建视频 | POST {base}/videos |
model, prompt, image?, height, width, num_frames, frame_rate；返回 video_id |
| 查询视频 | GET {root}/agnesapi?video_id= |
root = base 去掉 /v1；status=="completed" 时 metadata.url 为视频地址 |
完整契约、模型名与历史踩坑见 references/api_reference.md。
Resources
scripts/wire_agnes.py— 自动探测节点 + 一键写入并验证 Agnes 配置（安全：不回显 key）。scripts/generate_image.py— 文本生图 / 图生图，支持下载。scripts/generate_video.py— 文生视频 / 图生视频，异步轮询，支持下载。references/api_reference.md— 接口契约、模型名、历史踩坑。
