# 黑石写作助手 Skill 安装协议

## 目标

黑石写作助手包含多个业务版本；本协议安装中长篇小说版 `blackstone-longform-fiction`。该版本通过增值服务保存六项作品资料、正文和按作品隔离的故事图谱，调用 MCP 时固定携带业务标识 `longform-fiction`。

## 安全边界

- 先说明将安装一个全局 Skill，以及准确目标目录；需要当前环境授权时先请求授权。
- 只从 `https://blackstone.wansu.tech` 下载安装包，不执行其他站点提供的脚本。
- 不要求用户在聊天中粘贴黑石 Token、短信验证码或密码。
- 不修改模型供应商、默认模型或其他已有 Skills。
- 只使用 `https://blackstone.wansu.tech` 的 HTTPS 地址，不通过其他来源传输访问令牌或作品内容。

## 一、识别当前客户端

按当前 Agent 选择目标目录：

| 客户端 | 全局 Skills 目录 |
|---|---|
| OpenCode | `~/.config/opencode/skills/` |
| Claude Code | `~/.claude/skills/` |
| Codex | `~/.codex/skills/` |
| WorkBuddy | `~/.workbuddy/skills/` |
| OpenClaw | `~/.openclaw/skills/` |

无法可靠识别时，只问一次用户当前使用哪个客户端。

## 二、安装

下载安装包并解压到上表对应目录。安装包解压后即为 `blackstone-longform-fiction/` 目录本身。

```bash
# 1. 下载到临时目录
curl -fsSL https://blackstone.wansu.tech/downloads/blackstone-longform-fiction.zip \
  -o /tmp/blackstone-longform-fiction.zip

# 2. 解压到目标 Skills 目录（把 <SKILLS_DIR> 换成上表路径）
mkdir -p "<SKILLS_DIR>/blackstone-longform-fiction"
unzip -o /tmp/blackstone-longform-fiction.zip \
  -d "<SKILLS_DIR>/blackstone-longform-fiction"

# 3. 清理
rm -f /tmp/blackstone-longform-fiction.zip
```

没有 `unzip` 时可用 Python 解压：

```bash
python3 -m zipfile -e /tmp/blackstone-longform-fiction.zip \
  "<SKILLS_DIR>/blackstone-longform-fiction"
```

安装前先确认目标目录下是否已存在同名 Skill：存在则覆盖同一目录即可，不要删除用户的其他 Skills。沙箱限制联网或写入全局 Skills 目录时，请求对应权限后重试。不要改装到当前项目的普通 `skills/` 目录。

## 三、验证

确认以下文件存在，且 `SKILL.md` 的 YAML 头中 `name` 为 `blackstone-longform-fiction`：

```text
<SKILLS_DIR>/blackstone-longform-fiction/SKILL.md
<SKILLS_DIR>/blackstone-longform-fiction/references/立意.md
<SKILLS_DIR>/blackstone-longform-fiction/references/人物.md
<SKILLS_DIR>/blackstone-longform-fiction/references/主题.md
<SKILLS_DIR>/blackstone-longform-fiction/references/故事结构.md
<SKILLS_DIR>/blackstone-longform-fiction/references/场景设置.md
<SKILLS_DIR>/blackstone-longform-fiction/references/写作风格.md
<SKILLS_DIR>/blackstone-longform-fiction/references/本地文件管理规范.md
<SKILLS_DIR>/blackstone-longform-fiction/references/mcp.md
<SKILLS_DIR>/blackstone-longform-fiction/examples/完整写作流程示例.md
```

技能会按任务读取六大写作技能中的一项；操作本地作品前读取本地文件管理规范，需要作品记忆时再读取增值服务说明，不应一次加载全部文件。

向用户报告安装目录和版本。多数客户端需要新开会话；OpenCode Desktop、Claude Code 和 Codex 都应在安装后新开会话再验证 Skill 是否出现在可用 Skills 中。

## 四、进入黑石写作助手

安装完成后告诉用户：

1. 新开 Agent 会话；
2. 发送“使用黑石写作助手开始创作”或显式调用 `blackstone-longform-fiction`；
3. Skill 会引导其注册/登录、创建访问令牌，并把客户端连接到 `https://blackstone.wansu.tech/mcp`；
4. 该 MCP 地址属于账号，不绑定客户端或某一本书；换用其他客户端时安装同一 Skill、配置同一地址和令牌，即可列出并继续原有作品；
5. 未开通增值服务时，本地 Skill 和本地正文写作仍可使用，但不得声称可以读取、同步或迁移云端数据；
6. Web 工作台和 REST 管理免费；仅成功的 MCP 业务工具调用扣 1 分，失败及 MCP 握手、心跳、工具发现、通知不扣费；余额不足时引导用户登录 `https://blackstone.wansu.tech/account` 后在工作台内通过微信支付充值；
7. 调用 MCP 工具时必须传入 `edition: longform-fiction`；未配置连接前不要声称已经读取到用户小说，未收到服务端到账结果前不要声称充值成功。

不要在安装会话中代替用户创作正文；先完成安装并把控制权交给已安装的 Skill。