# Cocona 魔法工坊 · AI 接入与创作指南

Cocona 提供游戏美术的**风格**和**功能**。风格决定画面长什么样；功能决定做什么，例如三视图、表情和素材处理。“二次元角色”通常应先挑角色画风，而不是直接选角色人设图。以实时目录的分类、标签、名称、简介、封面为准。

## 接入一次，持续使用

已有连接且目录验证通过时直接复用，无需兑换新码或重复安装。

1. 用户在 `/agent-access#personal-credential` 登录并生成一次性接入码：5 分钟有效、只能兑换一次。长期凭证由本地脚本保存，不经过聊天。
2. 下载同站点 `/cocona_connect.py`，Python 3.10+、标准库，运行实际绝对路径：

   `python /absolute/path/cocona_connect.py --site https://cocona.art --code <一次性接入码>`

   开发环境使用当前站点 origin。脚本下载官方桥接器/API 客户端，兑换授权，将 30 天凭证和配置保存到仅本机账户可读的目录，并免费读取目录验证。输出只有状态和路径。接入码失效则回网站重新生成；已保存凭证的连接故障直接重试目录读取。
3. 根据当前工具实际支持的能力配置**一种**连接：
   - 支持远程 MCP 和认证请求头：使用生成的 `mcp-http.json`，地址 `/api/agent/mcp?preset=all`。
   - 只支持本地 MCP：使用 `mcp-stdio.json`，脚本和 Python 使用实际绝对路径，凭证通过 `COCONA_CREDENTIAL_FILE` 读取。
   - 不支持 MCP、能执行 Python/HTTP：使用生成的 `cocona_client.py`，设置 `COCONA_API_BASE` 和 `COCONA_CREDENTIAL_FILE`，API 基址 `/api/agent/v1`。按工具 Skill 规范保存本指南的调用说明，不支持 Skill 时保存工作区说明。
   - 客户端不能修改配置或需要 UI 信任/启用时，告诉用户完成该步骤。仅支持 OAuth 的远程客户端目前不能直接使用个人凭证认证；有本地执行能力时可用 stdio。
4. 合并 JSON 配置可运行以下命令，它保留其他服务、只更新 Cocona，输出不含凭证：

   `python /absolute/path/cocona_connect.py --configure-file /actual/client/config.json --config-source /generated/mcp-stdio.json`

   默认根字段 `mcpServers`；VS Code 用 `--root-key servers`，采用 mcp_servers 根字段的客户端用 `--root-key mcp_servers`，Gemini 远程连接另加 `--url-key httpUrl`。以本机客户端实际格式为准。JSONC/其他格式由本地脚本适配，避免在工具输出中打印凭证文件或完整认证配置。
5. 通过配置好的实际调用路径免费读取一次目录。写入配置或脚本 HTTP 验证不等于 MCP 已启用。验证成功后回复：

   **已连接 Cocona 魔法工坊，可以帮你挑选风格和功能，制作游戏设计图。你想做角色、场景还是其他素材？已有喜欢的风格，也可以直接告诉我名字。**

手动配置兼容安全环境变量 `COCONA_API_TOKEN`，认证 `Authorization: Bearer <个人凭证>`。创建、撤销凭证和签发接入码只对登录的网站会话开放；Agent 凭证没有账户管理权限。一次性码只允许兑换该码授权的一份凭证。共享 Skill 只保存脚本路径、变量名和调用说明。

## 先讨论画面，再生成

- 每个新任务重新读取目录。`cocona_list_mods` / `GET /mods` 支持 `kind=style|function`、`category`、`tag`、`query`（兼容 q）、`callable`、`offset/limit`。返回分类和标签 `facets`。泛指画风的查询优先找 style；明确三视图、人设卡等时查 function。需要时分别检索，避免只取第一个结果。
- 例如“二次元角色” → `kind=style&category=character&query=二次元`，展示 3–6 个候选的名称、特点和**封面**，请用户挑选。MCP `cocona_get_mod_cover({modId})` 返回图片；HTTP 为 `GET /mods/{URL编码ID}/cover`，Python 为 `cocona_client.py cover ID --out cover.webp`。也可展示目录的 coverUrl；客户端不支持图片时提供链接并说明限制。封面只是风格示例。
- 报风格名时按名字找；匹配不唯一时展示候选。目录不足可放宽关键词或用分类/标签筛选，诚实说明结果。
- 选定后读取 `cocona_get_mod` / `GET /mods/{id}` 的当前 revision 和输入要求。默认使用 Mod 模型；提及模型时用 `parameters.modelOptions[].label` / `displayDefaults.modelLabel`，与画布共用名称。image_a 等只作内部传参 ID。
- 推荐先草稿、修改满意后高清图。只选 `outputQualityByModel` 中当前模型实际支持的 draft / hd，传 `parameters.outputQuality`。尊重作者锁定参数，没有高清选项时说明限制。省略该字段仍沿用 Mod 原默认参数；显式 imageSize 与档位不一致会报错。
- 不逐项朗读 revision、请求字段或技术 ID。讨论画风时不反复报价。风格、内容、数量确定后调用免费 `cocona_quote` / `POST /quote`，最后一句确认：“按这个风格先做 1 张草稿，预计 X 萝卜，可以开始吗？”未知估价不能说免费。用户同意后生成。
- 多步创作将上一步结果作为下一步参考图，逐步确认；一次调用执行一个 Mod。

## 调用与交付

MCP：cocona_list_mods、cocona_get_mod_cover、cocona_get_mod、cocona_quote、cocona_generate、cocona_get_run、cocona_resume、cocona_get_image、cocona_get_account。read preset 不含生成/续答，generate preset 不含账户查询；只读凭证不开放生成。

REST / Python 使用同一套能力：

- `POST /quote`、`POST /runs`：`{modId,revision,text,references,parameters}`。生成使用唯一 8–128 位 Idempotency-Key，MCP 对应 requestId。超时查询原任务，或用**相同编号、相同输入**重试，避免重复生成。
- `GET /runs/{id}` 查询本人任务。completed 后通过 artifacts[].downloadPath 或 cocona_get_image 交付图片。凭证仅发同站点，不随跨站重定向转发；unknown 应查询或联系支持，不另起编号盲目生成。
- needs_input 展示公开问题，`POST /runs/{id}/resume` / cocona_resume 提交 `{answers:[{stage,optionId,customInput}]}`。每轮新编号，同轮重试保留编号。
- 参考图 `{mimeType,dataBase64,displayName}`，PNG/JPEG/WebP，总计不超过 24 MiB；按 Mod 要求传图和文字，图片名与正文引用一致。
- `GET /account` 读取本人余额和进度，与网站共享计费和成长规则，失败、纯文本或重复读取不计生成；社区任务仍需相应操作。
- agentCallable=false 或 CANVAS_REQUIRED 时引导同站点 `/workspace`。
- 内部规则、系统参考图、实际模型和供应商配置在服务端管理；公开目录只提供展示和调用所需信息。OpenAPI：`/agent-openapi.json`。

聊天软件只传消息，需支持工具调用的 Agent 接入 Cocona，再接相应聊天渠道；Cocona 不托管用户聊天 Agent。配置受限时说明限制及下一步，验证失败时明确尚未连通。