# hive-mp-publish — 一键安装

## 安装步骤（中文）

复制以下命令喂给你的 AI Agent（Codex / Claude Code / Cursor / OpenClaw 等）：

> 帮我安装 hive-mp-publish：https://www.resopod.cn/install/hive-mp-publish.md

Agent 会读取本指南完成 CLI 和配套 skill pack 安装，并跑通 `hive-mp-publish doctor`。这个工具用于把本地 Markdown 渲染为微信公众号图文草稿；远程发布需要 Gateway URL、Gateway API key，以及用户本机保存的微信公众号 AppID/AppSecret。

### Agent 执行细节

边界：
- 不要使用 `sudo`，除非用户明确授权。
- 不要把微信公众号 appSecret、Gateway API key 或 access_token 写入日志。
- Node.js 需要 `>=22.19`；Gateway/server 模式推荐 Node.js 24。

步骤：

```bash
node --version
npm --version
npm install -g "https://www.resopod.cn/packages/hive-mp-publish/latest/hive-mp-publish-0.1.2.tgz" --registry=https://registry.npmmirror.com
hive-mp-publish doctor
```

如果 Marketplace tarball 暂时不可用，可以从 npm registry 安装同版本：

```bash
npm install -g hive-mp-publish@0.1.2 --registry=https://registry.npmmirror.com
hive-mp-publish doctor
```

默认安装配套 skill pack。Codex 默认目录如下；如果用户使用 Claude Code、Cursor 或其他 Agent，请把 `SKILLS_DIR` 改成对应工具的 skills 根目录。

```bash
SKILLS_DIR="${CODEX_HOME:-$HOME/.codex}/skills"
mkdir -p "$SKILLS_DIR"
curl -L "https://www.resopod.cn/skills/hive-mp-publish-skills.tar.gz" | tar -xz -C "$SKILLS_DIR"
```

首次配置公众号凭据：

```bash
hive-mp-publish credential --set
hive-mp-publish doctor
```

通过 Gateway 发布：

```bash
hive-mp-publish publish -f article.md \
  --app-id "<local-alias-or-appid>" \
  --server "https://mp-gateway.example.com" \
  --api-key "hmp_live_xxx"
```

Gateway 运维侧常用命令：

```bash
hive-mp-publish key issue --name "<customer-name>"
hive-mp-publish serve --port 3000
```

排障：
- 如果 `hive-mp-publish` 不在 PATH 中，让用户重开 shell，或用 `npx hive-mp-publish@0.1.2 doctor` 临时验证。
- 如果 `doctor` 提示凭据未配置，引导用户运行 `hive-mp-publish credential --set`。
- 如果微信返回 IP 白名单错误，确认添加的是 Gateway 固定公网 IP。
- 远程 Gateway 必须使用 HTTPS；只有 localhost 联调才使用 HTTP。

---

## Install Steps (English)

Copy the line below to your AI Agent (Codex / Claude Code / Cursor / OpenClaw / etc.):

> Install hive-mp-publish for me: https://www.resopod.cn/install/hive-mp-publish.md

The agent will read this guide, install the CLI and companion skill pack, and pass `hive-mp-publish doctor`. This tool renders local Markdown into WeChat Official Account drafts. Remote publishing requires a Gateway URL, Gateway API key, and locally stored WeChat AppID/AppSecret.

### Agent Execution Details

Boundaries:
- Do not use `sudo` unless the user explicitly approves it.
- Do not log WeChat appSecret, Gateway API keys, or access tokens.
- Node.js must be `>=22.19`; Node.js 24 is recommended for Gateway/server mode.

Steps:

```bash
node --version
npm --version
npm install -g "https://www.resopod.cn/packages/hive-mp-publish/latest/hive-mp-publish-0.1.2.tgz" --registry=https://registry.npmmirror.com
hive-mp-publish doctor
```

If the Marketplace tarball is temporarily unavailable, install the same version from the npm registry:

```bash
npm install -g hive-mp-publish@0.1.2 --registry=https://registry.npmmirror.com
hive-mp-publish doctor
```

Install the companion skill pack by default. Codex uses the directory below; for Claude Code, Cursor, or another agent, change `SKILLS_DIR` to that tool's skills root.

```bash
SKILLS_DIR="${CODEX_HOME:-$HOME/.codex}/skills"
mkdir -p "$SKILLS_DIR"
curl -L "https://www.resopod.cn/skills/hive-mp-publish-skills.tar.gz" | tar -xz -C "$SKILLS_DIR"
```

First-time WeChat credential setup:

```bash
hive-mp-publish credential --set
hive-mp-publish doctor
```

Publish through a Gateway:

```bash
hive-mp-publish publish -f article.md \
  --app-id "<local-alias-or-appid>" \
  --server "https://mp-gateway.example.com" \
  --api-key "hmp_live_xxx"
```

Gateway operator commands:

```bash
hive-mp-publish key issue --name "<customer-name>"
hive-mp-publish serve --port 3000
```

Troubleshooting:
- If `hive-mp-publish` is not on PATH, ask the user to open a new shell, or temporarily verify with `npx hive-mp-publish@0.1.2 doctor`.
- If `doctor` reports missing credentials, guide the user through `hive-mp-publish credential --set`.
- If WeChat reports an IP allowlist error, confirm that the Gateway fixed public IP was added.
- Remote Gateway URLs must use HTTPS; HTTP is only for localhost development.