# KJMAX Skill 安装说明

本页供能够访问网络、读写本机文件并运行终端命令的 AI 助手执行。用户要求安装的范围：VOC 买家洞察。

安装只下载技能文件、准备 Python 依赖并运行本地检查。不要在安装阶段充值、采集数据、生图、连接店铺、创建商品或发送消息。无需让用户在对话中提供 Token 或店铺密钥。安装免费；后续在线服务按当前报价和用户授权使用。

## 1. 确定当前宿主和安装目录

安装到**正在与用户对话的 AI 工具**，不要仅因本机存在其他工具的目录就安装到那里。

| 当前 AI 工具 | 用户级技能目录 | 安装器参数 |
| --- | --- | --- |
| WorkBuddy | `~/.workbuddy/skills/` | `--host workbuddy` |
| Claude Code | `~/.claude/skills/` | `--host claude` |
| Codex | 优先当前配置；新版默认 `~/.agents/skills/` | `--host codex` |
| Cursor | `~/.cursor/skills/` | `--host cursor` |

若宿主明确提供其他技能目录或内置安装入口，优先按实际设置安装，安装器可用 `--skills-dir "实际 skills 目录"`。不要修改或覆盖 HOME、CODEX_HOME 等现有环境变量。其他宿主先查其技能安装方式；无法识别时再向用户确认。只有网页聊天、没有本机文件或终端权限的环境不能直接完成本机安装，应引导用户把安装提示词粘贴到上述本地 AI 工具。

Codex 安装器优先使用已有 `CODEX_HOME/skills` 设置；未设置时，若新版目录尚不存在而本机已有 `~/.codex/skills/`，则复用该旧版目录。其他情况采用[当前官方目录](https://learn.chatgpt.com/docs/build-skills) `~/.agents/skills/`。实际宿主的显式配置始终优先，可通过 `--skills-dir` 指定。

## 2. 下载并安装技能文件

1. 确认 Python 3.10+，记录解释器绝对路径；Windows 可先检查 `py -3`，macOS/Linux 可检查 `python3`。未安装时说明缺少的环境，不假报完成。
2. 下载 [Python 安装器](https://kjds.flowriv.top/skills/install.py) 到临时目录，读取其内容后使用同一解释器执行。脚本仅依赖 Python 标准库；请用当前宿主对应的 `--host` 参数替换下面示例。

```text
"<Python绝对路径>" "<临时目录>/kjmax-install.py" --base-url "https://kjds.flowriv.top" --skill kjds-voc-insight --host workbuddy
```

Windows PowerShell 执行已加引号的程序路径时，在这一行前加 `&`。临时目录、解释器和宿主参数均替换为本机实际值。

安装器读取 [下载清单](https://kjds.flowriv.top/skills/manifest.json)，下载指定公共包并校验 SHA256，移除 ZIP 内的 `skills/` 外层后放到目标技能目录；已有 `config.json` 保留。更新时保留原目录中的用户文件、虚拟环境和业务输出，不删除旧安装。

也可直接下载以下文件手动完成相同操作。先校验 SHA256，只提取 `skills/<技能名>/` 内的普通文件，拒绝越界路径和符号链接，保留本机已有 `config.json`。最终必须直接存在 `<技能目录>/<技能名>/SKILL.md`，不能多套一层 `skills/`。


### VOC 买家洞察 · `kjds-voc-insight`

- 技能包：[kjds-voc-insight.zip](https://kjds.flowriv.top/skills/files/kjds-voc-insight.zip)
- 校验文件：[SHA256](https://kjds.flowriv.top/skills/files/kjds-voc-insight.zip.sha256)
- 本页版本 SHA256：`fc95e87d1ad523d5ff152bac6600b15441230b255a623905a633572cbeb1684a`


若校验失败，停止安装并重新获取本页和下载清单，不跳过校验或关闭 HTTPS 证书验证。

## 3. 准备依赖并做本地检查

逐个阅读已安装技能的 `SKILL.md`，使用同一 Python 3.10+ 解释器。推荐在各技能目录建立 `.venv`，通过其中 Python 的绝对路径执行 `-m pip install -r "<技能目录>/requirements.txt"`，随后所有技能命令都使用该解释器；不要向系统 Python 强行安装。

- VOC、BI 的 `requirements.txt` 用于 Excel 处理；TikTok 达人技能的 `requirements.txt` 是其必需依赖，应安装。Shopify 商品草稿使用标准库，没有 `requirements.txt`。
- BI 的 `requirements-feishu.txt` 是飞书功能可选依赖，安装本技能时无需连接或授权飞书，使用时再按说明准备。
- 依赖安装失败时准确报告“技能文件已安装，依赖未就绪”及修复方法；不要宣称全部可用。
- 对每个技能运行 `"<所选Python绝对路径>" "<技能绝对路径>/scripts/client.py" --help`。这是本地检查，不调用收费服务。记录实际命令、退出码与安装绝对路径，不打印私人配置或凭证。

## 4. 加载并告诉用户如何开始

请宿主重新扫描技能或开启新会话；未出现时再重启宿主。文件安装、本地检查通过和宿主已识别是不同状态；没有观察到技能列表或真实调用时，不声称宿主已经识别或业务验收通过。

向用户简要报告已安装的技能、绝对路径、Python/依赖与本地检查结果，说明需要重新加载（如适用），并给出第一句使用示例：

- **VOC 买家洞察**：帮我分析这份评论表，找出用户最在意的问题。


需要账户、店铺或飞书授权时，按技能本身的使用说明在本机完成配置；这不属于本次安装操作。