# ip-licensing-skills Installation Checklist

本文件是 `ip-licensing-skills` 的安装 / 初始化配置入口。所有存储、外部 Skill、MCP、素材库、发布和凭据 profile 都应在安装时一次性配置完成。安装完成后，阶段 workflow 不再逐层询问这些配置，只读取安装时注入的变量或逻辑 URI。

## 1. Install-time Principle

安装时做三件事：

1. **收集配置**：项目存储、案例库、参考图库、发布 Skill、图像 Skill、联系二维码、凭据 profile。
2. **验证可用性**：检查必需后端、外部 Skill 和凭据是否可访问；可选能力缺失则记录降级策略。
3. **写入安装配置**：生成环境变量、JSON 配置或 MCP namespace 映射；运行阶段只读取这些配置。

运行时不应在每个阶段重复出现配置清单。阶段 workflow 只说“读取已安装配置”或“调用已配置的外部 Skill”。

## 2. Required Installation Questions

安装者必须一次性回答以下问题。

### 2.1 Project storage

| Item | Required | Meaning |
|---|---:|---|
| `IP_LICENSING_STORAGE_BACKEND` | yes | 存储实现类型：`filesystem`、`shared-drive`、`object-storage`、`mcp`、`custom` |
| `IP_LICENSING_PROJECT_ROOT` | yes unless MCP maps `project://` | 当前项目资料根位置或逻辑根 |
| `IP_LICENSING_STORAGE_MCP_SERVER` | if backend=`mcp` | MCP 存储 server 名称 |
| `IP_LICENSING_STORAGE_MCP_NAMESPACE` | if backend=`mcp` | MCP workspace / namespace / bucket / collection |

Required capability contract:

- read
- write-new
- list
- copy/import
- status/metadata
- safe-write policy for overwrite/delete/move/merge

### 2.2 Optional external libraries

| Item | Required | Meaning | Default / Runtime fallback |
|---|---:|---|---|
| `IP_LICENSING_CASE_LIBRARY_ROOT` | no | 外部案例库，只读参考 | 跳过案例库，继续按公开资料和项目输入执行 |
| `IP_LICENSING_REFERENCE_ASSET_ROOT` | no | 外部图库风格参考库 | default: `studio-resource-library://authorization/ip-product-reference-library` |
| `IP_LICENSING_PUBLIC_ASSET_ROOT` | no | 公共素材库 | default: `studio-resource-library://authorization/ip-product-reference-library` |
| `IP_LICENSING_RESOURCE_LIBRARY_MCP_SERVER` | no | 默认公共资源库 MCP server 名称 | `studio_resource_library` |
| `IP_LICENSING_RESOURCE_LIBRARY_MCP_URL` | no | 默认公共资源库 MCP endpoint | `http://100.113.171.115:18871/mcp` |
| `IP_LICENSING_RESOURCE_LIBRARY_DEFAULT_DOMAIN` | no | 默认资源域 | `authorization` |
| `IP_LICENSING_RESOURCE_LIBRARY_DEFAULT_LIBRARY_ID` | no | 默认资源库 | `ip-product-reference-library` |

默认公共资源库已经固定为当前 Studio 通用资源库 MCP：`studio_resource_library`。它用于只读检索授权参考图、产品示意图和可复用素材，不承担当前项目资料写入、归档、覆盖或删除职责。

MCP implementations may expose equivalent logical URI roots:

```text
case-library://...
reference-assets://...
public-assets://...
```

### 2.3 Contact QR asset

| Item | Required | Meaning | Default |
|---|---:|---|---|
| `IP_LICENSING_CONTACT_QR_ASSET` | no | 授权咨询二维码素材 | `assets/contact/ip-licensing-contact-qr.png` |

If a project-specific contact QR is provided, configure this variable during installation or project initialization. Do not hardcode contact asset paths inside stage workflow files.

### 2.4 Image generation / editing Skill

| Item | Required | Meaning | Default / fallback |
|---|---:|---|---|
| `IP_LICENSING_IMAGE_SKILL` | yes for image-producing runs | 通用图像生成 / 改图 Skill | `MXAI` |
| `IP_LICENSING_GALLERY_IMAGE_SKILL` | no | 阶段二图库专用图像 Skill | fallback to `IP_LICENSING_IMAGE_SKILL` |
| `IP_LICENSING_PRODUCT_IMAGE_SKILL` | no | 阶段三产品示意图专用图像 Skill | fallback to `IP_LICENSING_IMAGE_SKILL` |
| image credential profile | if image Skill requires it | 由外部图像 Skill 自己定义，例如 API key、profile 或 provider config | 若缺失，只输出提示词、方向矩阵和制作清单 |

This Skill Pack only references the image Skill. It does not copy the implementation of MXAI or store image provider secrets.

### 2.5 Publishing Skill

| Item | Required | Meaning | Runtime fallback |
|---|---:|---|---|
| `IP_LICENSING_PUBLISH_SKILL` | no | 生成公开 HTML / 在线交付链接的外部 Skill 名称 | 不生成公开链接，只交付文件包 |
| `IP_LICENSING_PUBLISH_PROFILE` | no | 发布环境、域名、profile 或 namespace 标识 | 使用发布 Skill 默认配置 |
| publish credential profile | if publish Skill requires it | 由外部发布 Skill 自己定义，例如 deploy key、token、profile | 只输出本地 / 当前项目交付包 |

This Skill Pack does not store domains, upload tokens, deploy keys, or hosting details. It only calls the configured publish Skill when available.

## 3. Missing Configuration Behavior

During installation:

1. If a required item is missing, ask the installer for it immediately.
2. If an optional item is missing, record the fallback behavior.
3. If an external Skill is named but not available, ask whether to:
   - install / enable that Skill;
   - change the configured Skill name;
   - disable that capability and use fallback.
4. If credentials are required, ask for a credential profile or secure local secret setup method, not the raw secret value in documentation.

During normal execution:

- Do not ask for all configuration again.
- Do not list installation variables inside each stage.
- Read the installed config and proceed.
- If a required installed config becomes unavailable, stop at the capability boundary and ask only for the missing item.

## 4. Suggested env file

Create a local env file from:

```text
templates/ip-licensing.env.example
```

Do not commit real private paths, tokens, API keys, deploy keys, or private profile identifiers.

## 5. Suggested JSON config

For MCP or custom storage/reference backends, start from:

```text
templates/storage-config.example.json
```

The packaged default already points reference/public asset lookup to the current Studio resource-library MCP:

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

Use logical URI roots so the Skill Pack can remain portable:

```text
project://...
case-library://...
reference-assets://...
public-assets://...
publish://...
```

## 6. Post-install smoke test

After installation, run a dry project smoke test:

1. Create a dummy project context.
2. Write and read a test `project://.../PROJECT_CONTEXT.md` object or equivalent file.
3. If image Skill is configured, verify it can be resolved without running a paid or irreversible generation unless explicitly allowed.
4. If publish Skill is configured, verify it can produce or simulate a publish target without exposing secrets.
5. Verify contact QR asset resolves to either the packaged default or configured override.
6. Run:

```bash
python3 scripts/check_skillpack.py
```

## 7. Runtime contract

After installation, internal workflows assume:

```text
installed_config.storage
installed_config.case_library_optional
installed_config.reference_assets_optional
installed_config.contact_qr
installed_config.image_skill
installed_config.publish_skill_optional
installed_config.credential_profiles
```

Workflow files should refer to these logical capabilities, not repeat installation variable tables.