用途
PixelRAG 技能用于操作 StarTrail-org/PixelRAG，完成基于截图的视觉检索：把页面或文档渲染为图像切片，对视觉内容进行分块与嵌入，构建搜索索引并提供查询服务。技能本身定位为“操作者”，强调在动工前确认来源、选择检索方式并分阶段验证。
主要能力与管线
- 来源校验：在 jeo-skills 根目录运行
python3 .agent-skills/pixelrag/scripts/preflight.py --repo /absolute/upstream --json；在已安装的技能根目录运行scripts/preflight.py。不提供--repo时仅做清单检查。哈希覆盖所选源文件，不覆盖 Git HEAD、完整目录树、包安装、模型下载或运行时状态。 - 本地管线映射：将 pixelshot 截图与 pixelrag 各阶段（chunk、embed、build-index、index、serve）区分开，检查
pixelrag.yaml、源连接器、嵌入模型与设备、输出/索引目录以及服务绑定。PixelRAG 属于多模态视觉检索，不是知识图谱或本体。 - 分阶段验证：获得批准后查看
pixelrag <stage> --help，先用小型授权样本运行，核对渲染切片及其源映射、索引输出与查询结果。preflight 仅做离线来源校验，并不表示渲染、模型加载、索引构建、API 部署或搜索测试成功。
使用方式（示例）
仅做来源校验（绝对路径、非符号链接检出）：
python3 .agent-skills/pixelrag/scripts/preflight.py --repo /work/PixelRAG --json
仅在包、模型、来源与索引均获批后：
pip install 'pixelrag[index]'
运行管线前创建并检查 pixelrag.yaml，然后：
pixelrag index build
pixelrag serve --index-dir ./my_index --port 30001
适用场景与操作要求
适用于需要对视觉文档或页面做截图式检索、并希望在本地可控管线中构建索引与查询服务的场景。操作前需明确选择本地或托管检索：上游 README 同时记载了托管 API 与预构建的多 TB 级索引下载，不得默认切换至任一外部接口，须先确认数据传输、提供方、费用、账号与目的地。以下操作须先获批准：安装额外/原生包；下载模型权重或数据集；采集私有或第三方 URL；发送内容或查询到托管 API 或付费提供方；写入、重建或删除切片、嵌入、索引及目标数据；启动服务或公开绑定。不得将凭据放入命令行参数或报告。
限制与注意事项
- 固定的
pyproject.toml要求 Python >=3.12，尽管某处 README 示例写作 3.10+；应以包元数据为准并测试确切环境。 - README 描述了 Linux CUDA 与 macOS Apple Silicon/MPS 路径，使用
device: auto；CPU 回退与可选 extra 在成本与性能上不同。PDF 渲染需要 PDF extra 与 Poppler，选择管线前须确认硬件与系统包。 pixelrag[index]会拉取索引/嵌入依赖，模型权重可能较大；文档中的预构建索引基础子集约 217 GB，未经明确批准并检查存储前不要下载。pixelrag serve会启动服务，须检查实际绑定默认值，除非明确批准并加固公网暴露，否则限制为回环地址。- 基准或托管语料结果仅限其确切数据集、模型与硬件，不得套用于用户自有语料。
- 助手脚本支持 POSIX Linux/macOS/WSL2 上的 Python 3.10+，在无法进行安全目录遍历时失效关闭，包括不受支持的原生 Windows。
- 各阶段的具体参数、配置字段默认值、托管 API 的价格与账号要求、模型权重大小细节，资料中暂未提供。