PT 资源管理统一入口。你只需要用自然语言告诉助手要做什么，从找片、下载到自动整理、辅种、跨下载器转移，一个技能全搞定，不需要记任何命令。
| 你想做的事 | 直接对助手说 |
|---|---|
| 🔍 找片 | “帮我搜一下《沙丘2》”“搜 XX，只要免费的”“搜 XX，只看 4K” |
| ⬇️ 下载 | “下载第 3 个”“下载到电影盘”“先下载，先别开始” |
| 📂 自动整理 | “整理 /media/xxx 这个路径”“先预览一下 /media/xxx 会怎么整理” |
| 🔄 跨盘转移 | “触发一轮转移” |
| 🌱 辅种 | “触发一轮辅种”“辅种失败的记录有哪些”“重试第 2 条辅种” |
| 📁 下载路径 | “把下载路径都列出来”“默认下载路径改成 2”“清除默认下载路径” |
| 🏷️ 站点（索引器） | “接入一个新站点 XX”“测试一下 XX 站点通不通” |
| 📊 账号/统计 | “看看我的账号数据”“下载器现在什么状态” |
| 🛠️ 部署/配置/排障 | “帮我部署 ptpilot”“检查一下健康状态”“为什么下载失败了” |
你：搜一下“捕风追影”
助手：找到 209 个结果，展示前 5 个……（回复“下载第 N 个 / 只看免费 / 按做种排序”）
你：从结果里筛选 CHD 的
你：按大小排序
你：下载第 1 个
要点：
- 搜索结果会自动缓存，后续“筛选/排序/只看免费/看更多”都基于缓存，不会重复请求站点，放心反复折腾。
- 想指定站点搜：
搜 XX，只搜 M-Team；只看免费：只要免费的；优先免费：优先免费的。 - 下载时如果没有默认路径，助手会列出已保存的路径让你选；有默认路径则直接下载。
- 想下载到指定位置：
下载第 2 个到路径 3。
你：先预览一下 /media/downloads/xxx 会整理到哪里
助手：展示每条资源的目标路径（此时不落盘）
你：确认，执行整理
助手：执行并汇报结果
整理是移动/重命名文件的动作，助手永远先预览再等你确认，不会直接动手。除非你明确说“直接整理”。
你：触发一轮辅种
你：辅种记录里失败的有哪些
你：重试第 1 条失败的
你：我想接入一个新站点，叫 XXX
助手：找到匹配的索引器，展示需要填的字段
你：凭据用环境变量 XXX 引用 / 交互输入
助手：添加 → 测试连通 → 提示同步辅种白名单（重启生效）
凭据（cookie / passkey / API key / token / 密码）不要直接粘贴到聊天里。优先用环境变量引用或交互输入，助手不会要求你把密钥贴出来。
如果还没部署/接入过，直接说“帮我部署 ptpilot”或“首次配置”，助手会分阶段引导：环境检测 → Jackett 接入 → 部署方式 → 生成配置 → 健康检查 → 索引器 → 全链路验证。
也可以随时说“检查一下健康状态”确认 ptpilot 与 Jackett 都连通。
路径是“保存到哪里”的注册表，可配置多个：
你：配置下载路径 /media/media3/Downloads，名字叫“电影”，分类 movie
你：把默认下载路径设为 2
你：清除默认下载路径 （之后每次下载都会让你选）
你：删除路径 2 （破坏性，助手会先确认）
已接入的站点列表、某站点参数、测试连通性，都可以直接问/要求助手操作。
- 结果展示：列表类输出最多展示 5 条，编号排列，末尾会提示下一步可以说的话（如“下载第 1 个”）。
- 敏感信息：token / cookie / 密钥一律打码展示，绝不回显。
- 破坏性操作：删除整理产物、删除历史/辅种记录、移除索引器、删除路径等，助手会先说明影响范围并等你确认再执行。
- 失败自愈：整理失败项会在下一轮轮询自动重试，不用反复手动催。
| 现象 | 怎么办 |
|---|---|
| 搜索报“Tracker is not configured” | 该站点还没接入，让助手“接入站点 XX” |
| 下载没让你选路径 | 之前设过默认路径，可让助手“清除默认下载路径” |
| 整理报“源路径不存在” | 确认路径是不是容器内路径，换个路径重试 |
| 连接失败 / 服务没反应 | 让助手“检查健康状态”，未部署则走首次配置引导 |
| 想了解某个接口怎么用 | 直接问“XX 接口怎么用”，助手现场演示，不用翻文档 |
- 密钥不经过聊天：优先
env://引用或交互输入。 - 本地连接配置存于
config.json（chmod 600，已被 .gitignore 排除）。 - 所有删除类操作执行前必确认。
- 保持 TLS 校验，不绕过证书错误。
ptpilot-agent/
├── SKILL.md # 技能主文档（入口路由 / 展示契约 / 安全边界）
├── DESIGN.md # 设计文档
├── scripts/
│ ├── ptpilot_agent.py # 统一 CLI（唯一执行入口，由助手调用）
│ └── validate_skill.py # 自校验脚本
├── references/
│ ├── deployment.md # 部署引导（Docker/裸机/升级/迁移）
│ ├── configuration.md # config.yaml 字段详解
│ ├── api-reference.md # ptpilot API 权威清单
│ ├── workflows.md # 端到端场景手册与故障排查
│ ├── interaction-design.md # 展示契约/错误恢复
│ └── agent-contract.md # 命令清单/退出码/透传规则
└── config.json # 本地连接配置（600，不提交）
命令级细节（退出码、CLI 参数、API 路径）请查阅
references/，那是给助手和开发者的实现契约。