# 便便 · 开放游戏素材库

便便是一个免登录、免注册的游戏素材与世界观资料库。它适合人类创作者和 agents：先从稳定编号的角色、怪兽、物品设定里挑选一组，再把 JSON 和已有图片接进自己的游戏原型。

## 站点地址

- 规范站点：`https://bianbian.co`
- Agent 说明：`https://bianbian.co/llms.txt`
- MCP 使用页：`https://bianbian.co/mcp.html`
- 公开 API 基地址：`https://bianbian.co/api`

## 基本规则

- 所有公开接口都在 `https://bianbian.co` 下；请求时使用 `https://bianbian.co` 作为 `BASE_URL`。
- 公开 GET 接口不需要认证，不要索取或猜测 token。
- 数据记录使用稳定 id：角色 `C001`…，怪兽 `M001`…，道具 `I001`…。
- `/admin-poo/` 是人类维护用的后台入口，不是公开素材 API；agents 不要依赖它，也不要把它推荐给最终用户。
- 只把接口返回的 `output_path`、`thumbnail_path` 或明确存在的图片 URL 当作可下载资产，不要猜测文件名。

## 先选什么

1. 先问清楚游戏题材、时代、视角和玩法；若用户没有偏好，优先选择资料完整、`usage` 清楚且 `era` 与题材一致的角色。
2. 从 `GET https://bianbian.co/api/characters` 读取完整角色字段，用 `identity`、`personality`、`skills`、`era`、`usage` 进行筛选。年龄、性别、脸型、眼型和面部辨识点可用来避免队伍同质化。
3. 用 `GET https://bianbian.co/api/monsters` 选冲突：`type` 和 `habitat` 贴合世界观，`danger` 贴合关卡强度，`abilities` 与 `weakness` 能形成可玩的对策。
4. 用 `GET https://bianbian.co/api/items` 补 3–6 件道具：优先匹配 `category`、`type`、`era`、`scene` 和 `effect`，让道具服务于玩法，而不是只做装饰。
5. 默认输出一组清晰的开局组合：1 个主角、1 个伙伴或对手、1 个怪兽、3 件道具，并保留每条记录的 id 方便后续复现。

## 公开接口

- `GET https://bianbian.co/api/gallery`：角色的轻量列表、图片路径、状态和素材完善度。优先用它做角色卡片和有图筛选。
- `GET https://bianbian.co/api/characters`：全部角色的完整设定字段。
- `GET https://bianbian.co/api/characters/{id}`：单个角色的完整设定和 `images` 图片任务列表，例如 `https://bianbian.co/api/characters/C001`。
- `GET https://bianbian.co/api/monsters`：全部怪兽的类型、时代、栖息地、危险度、能力和弱点。
- `GET https://bianbian.co/api/items`：全部物品的分类、类型、品相、时代、效果、限制和适用场景。
- `GET https://bianbian.co/api/search?q=关键词&library=all`：跨角色、怪兽、物品的相关性检索，支持 `page`、`limit`、`sort` 和结构化筛选。
- `GET https://bianbian.co/api/search/facets?library=all`：读取可用的筛选值。
- `GET https://bianbian.co/api/library/{library}/{id}`：统一格式读取单条资料，例如 `/api/library/items/I001`。
- `GET https://bianbian.co/api/health`：服务状态；素材挑选失败时先检查这个接口。

### 检索建议

优先使用 `/api/search`，不要为了寻找单条资料下载三份完整列表。`library` 可取 `characters`、`monsters`、`items` 或 `all`；`q` 会搜索名称、编号和设定文本，多个空格分隔的词需要同时命中。角色常用筛选是 `era`、`gender`、`identity`，怪兽常用筛选是 `type`、`habitat`、`danger`，物品常用筛选是 `category`、`type`、`rarity`、`scene`。结果中的 `matchedFields` 说明命中的字段，`matchScore` 只用于排序，不代表质量评分。

## 下载素材

1. 先读取 `https://bianbian.co/api/gallery`，选择 `imagePath` 或 `thumbnailPath` 非空的角色。
2. 要拿完整设定图，请读取 `https://bianbian.co/api/characters/{id}` 的 `images`，优先使用 `status=succeeded` 的 `output_path`；预览可用 `thumbnail_path`。
3. 优先直接使用接口返回的图片 URL；它可能是站点相对路径，也可能在配置 CDN 后是完整 CDN URL，并且会带 `v` 版本参数。不要删除或修改该参数。
4. 直接下载即可：`curl -L -o c001.png https://bianbian.co/generated/c001.png`。JSON 设定也可直接保存：`curl -L -o c001.json https://bianbian.co/api/characters/C001`。
5. 怪兽目前主要提供结构化设定；只有明确返回的 `/images/monster-samples/...` 样张才可视为现成图片。物品以结构化资料为主，若需要图片请在用户确认后自行生成并标注来源。

## 给用户的输出格式

推荐返回：游戏一句话概念、选中的记录（id + 名称 + 选择理由）、玩法冲突、道具用途，以及每个可下载文件的完整 URL。不要只返回名字，也不要把未成功的任务当成已有图片。

## 生产新图

`POST /api/tasks` 和队列设置属于维护流程。除非用户明确要求生成或维护素材，否则 agents 只读公开 GET 接口，避免重复创建任务。