# Storage Backend Configuration

> Install-time configuration detail. The canonical installation entry is `INSTALL.md`; do not duplicate these variables inside stage workflow files.

## Purpose

`ip-licensing-skills` 不绑定任何本地目录、共享盘或特定系统。所有“项目资料库 / 归档区 / 案例库 / 公开素材库”都通过安装时配置注入。

## Required Concepts

| Logical variable | Purpose | Required |
|---|---|---|
| `IP_LICENSING_STORAGE_BACKEND` | 存储实现类型：`filesystem`、`shared-drive`、`object-storage`、`mcp`、`custom` | yes |
| `IP_LICENSING_PROJECT_ROOT` | 当前项目资料根位置，用于阶段资料和交付包 | yes |
| `IP_LICENSING_CASE_LIBRARY_ROOT` | 可选外部案例库根位置，用于只读案例参考；未配置则跳过案例库步骤 | no |
| `IP_LICENSING_PUBLIC_ASSET_ROOT` | 可选公开素材或统一素材库位置，如 Logo 模板等 | no |
| `IP_LICENSING_REFERENCE_ASSET_ROOT` | 可选外部图库风格参考库；未配置则跳过参考库步骤 | no |
| `IP_LICENSING_CONTACT_QR_ASSET` | 授权咨询二维码素材；默认可使用包内 `assets/contact/ip-licensing-contact-qr.png` | no |
| `IP_LICENSING_RESOURCE_LIBRARY_MCP_SERVER` | 默认公共资源库 MCP server 名称；本团队默认固定为 `studio_resource_library` | no |
| `IP_LICENSING_RESOURCE_LIBRARY_MCP_URL` | 默认公共资源库 MCP endpoint；本团队默认 `http://100.113.171.115:18871/mcp` | no |
| `IP_LICENSING_RESOURCE_LIBRARY_DEFAULT_DOMAIN` | 默认公共资源域；当前为 `authorization` | no |
| `IP_LICENSING_RESOURCE_LIBRARY_DEFAULT_LIBRARY_ID` | 默认公共资源库；当前为 `ip-product-reference-library` | no |
| `IP_LICENSING_STORAGE_MCP_SERVER` | 当项目存储 backend=`mcp` 时使用的 MCP server 名称 | conditional |
| `IP_LICENSING_STORAGE_MCP_NAMESPACE` | 当项目存储 backend=`mcp` 时使用的命名空间、bucket、collection 或 workspace | conditional |

## Backend Contract

无论底层是文件系统、共享盘、对象存储还是 MCP，都必须提供以下能力：

1. **read**：读取项目资料、案例资料、模板和 manifest。
2. **write-new**：创建新的项目文件、阶段 README、manifest、最终交付记录。
3. **list**：列出项目目录、阶段目录和候选素材。
4. **copy/import**：把用户提供或生成的素材纳入项目工作区。
5. **status/metadata**：记录文件状态、确认时间、来源和是否可用于最终材料。
6. **safe-write policy**：覆盖、删除、移动、合并必须由外层流程确认，不由 Skill 静默执行。

## Resource Library MCP Default

本团队默认参考素材 / 公共素材检索固定使用当前 Studio 通用资源库 MCP：

```text
server: studio_resource_library
url: http://100.113.171.115:18871/mcp
default_domain: authorization
default_library_id: ip-product-reference-library
```

该 MCP 是只读资源检索入口，推荐用于阶段二图库风格参考、阶段三产品示意图参考、阶段四授权介绍素材回查。调用顺序：先 `list_domains` / `list_libraries`，再 `search_assets`，最后按需 `get_asset` 或 `get_rag_chunk`。

不要把它当作项目资料写入 / 归档 / 覆盖删除后端；项目写入仍由 `IP_LICENSING_STORAGE_BACKEND` 和项目工作区配置决定。

## MCP Compatibility

当项目存储优化为 MCP 时，Skill 不关心具体路径，只调用逻辑对象：

```text
project://<project-id>/00-context/PROJECT_CONTEXT.md
project://<project-id>/01-source/source_index.md
project://<project-id>/03-gallery/final_selected_single_images/
project://<project-id>/04-product/selected_single_images/
project://<project-id>/06-delivery/final_delivery_readme.md
case-library://<case-id>/...
public-assets://contact-qr/current
```

MCP server 应把这些逻辑 URI 映射到真实存储。Skill 文档只写逻辑 URI 和变量名，不写本地绝对路径。

## Installation Checklist

- [ ] 选择 storage backend。
- [ ] 配置 `IP_LICENSING_PROJECT_ROOT` 或 MCP server/namespace。
- [ ] 如需案例参考，配置 `IP_LICENSING_CASE_LIBRARY_ROOT` 或 MCP `case-library://...`；不配置则跳过案例库步骤。
- [ ] 确认 `IP_LICENSING_CONTACT_QR_ASSET`：默认可使用包内二维码，也可替换为项目专用联系方式。
- [ ] 如需其他公共素材，默认使用 `studio_resource_library` MCP；只有需要改到其他库时才覆盖 `IP_LICENSING_PUBLIC_ASSET_ROOT`。
- [ ] 如需阶段二图库风格参考，默认使用 `studio_resource_library` MCP 的 `authorization / ip-product-reference-library`；只有项目有专用参考库时才覆盖 `IP_LICENSING_REFERENCE_ASSET_ROOT`。
- [ ] 运行 `scripts/check_skillpack.py` 验证结构。
- [ ] 用一个空项目 dry-run：创建 PROJECT_CONTEXT、source_index、asset_status_manifest、final_delivery_qa。


## Optional Publish Skill

公开链接生成不由本 Skill Pack 内置实现。安装方可配置独立发布 Skill：

| Variable | Purpose | Required |
|---|---|---|
| `IP_LICENSING_PUBLISH_SKILL` | 用于生成公开 HTML / 在线交付链接的外部 Skill 名称 | no |
| `IP_LICENSING_PUBLISH_PROFILE` | 可选发布环境、域名、profile 或 namespace 标识 | no |

规则：

1. 配置了 `IP_LICENSING_PUBLISH_SKILL` 时，最终介绍阶段可调用该 Skill 生成公开链接。
2. 未配置时，本 Skill Pack 只要求生成可交付文件包，不强制公开链接。
3. 发布 Skill 的认证、域名、上传和托管细节不写入本 Skill Pack。
4. 交付 QA 只检查“如已生成公开链接，链接可访问且内容为最终版”。


## External Image Generation Skill

阶段二图库和阶段三产品示意图不在本包内实现图像生成能力。本 Skill Pack 只定义方向、提示词、候选选择、确认与 QA；实际生图/改图/Mockup 调用外部通用技能。

| Variable | Purpose | Default |
|---|---|---|
| `IP_LICENSING_IMAGE_SKILL` | 图库与产品示意图生成使用的外部 Skill 名称 | `MXAI` |
| `IP_LICENSING_GALLERY_IMAGE_SKILL` | 可选：阶段二图库专用外部 Skill | fallback to `IP_LICENSING_IMAGE_SKILL` |
| `IP_LICENSING_PRODUCT_IMAGE_SKILL` | 可选：阶段三产品示意图专用外部 Skill | fallback to `IP_LICENSING_IMAGE_SKILL` |

规则：

1. 本包通过引用关系说明调用外部 `MXAI` Skill，不复制或重写其实现。
2. 如果安装方把图像能力迁移到其他 Skill，只需改变量，不改 SOP。
3. 未配置或外部 Skill 不可用时，本包仍可输出提示词、方向矩阵、制作清单和 QA 表。