# Portable Skill Package + Gitea Publishing Notes (2026-05)

## What was packaged

A portable archive was created for sharing the local `xianyu-hunter-monitor` workflow with other Hermes installations. The useful package shape is:

```text
xianyu-hunter-hermes-skill/
  README.md
  install.sh
  skill/xianyu-hunter-monitor/
  project/xianyu-hunter/
```

Recommended optional repo/release shape when publishing to a Git service:

```text
README.md
install.sh
skill/xianyu-hunter-monitor/
project/xianyu-hunter/
releases/
  xianyu-hunter-hermes-skill.zip
  xianyu-hunter-hermes-skill.tar.gz
  SHA256SUMS.txt
```

## Exclude from the package

Do **not** include local runtime or sensitive state:

- `browser-data/` — Goofish/Taobao login profile and cookies.
- `node_modules/`.
- `.git/`.
- `.runtime/`.
- `reports/`.
- `xianyu-server.log` and other logs.
- `data/tasks.json`.
- `data/config.json`.
- real `data/notify-config.json` because it can contain delivery targets or tokens.

It is safe to include an example notification config:

```json
{
  "enabled": false,
  "notifyOnlyGood": true,
  "minScore": 75,
  "channels": []
}
```

## Minimal README contents

The README should explain:

1. Purpose: Hermes Skill + local Web/CLI 闲鱼采集助手.
2. Default safety mode: only collect/filter/analyze; no seller contact, no purchase, no payment.
3. Requirements: Hermes Agent, Node.js >= 18, npm, network access to `https://www.goofish.com/`.
4. Install:
   ```bash
   bash install.sh
   ```
5. Default install destinations:
   ```text
   ~/.hermes/skills/social-media/xianyu-hunter-monitor/
   ~/xianyu-hunter/
   ```
6. Optional project destination:
   ```bash
   XIANHU_INSTALL_DIR="$HOME/apps/xianyu-hunter" bash install.sh
   ```
7. Start dashboard:
   ```bash
   cd ~/xianyu-hunter
   node tools/xianyu_ops.mjs start --port 3000
   ```
8. Login flow: Web UI → `账号登录 / Cookie` → get QR → scan → refresh status.
9. Example monitoring command via CLI and natural-language Hermes prompt.
10. Troubleshooting: login wall, captcha, port conflict, skill not found.

## install.sh pattern

Use a script that installs the skill and project without requiring many decisions:

```bash
#!/usr/bin/env bash
set -euo pipefail
ROOT="$(cd "$(dirname "$0")" && pwd)"
HERMES_HOME="${HERMES_HOME:-$HOME/.hermes}"
SKILL_DEST="$HERMES_HOME/skills/social-media/xianyu-hunter-monitor"
PROJECT_DEST="${XIANHU_INSTALL_DIR:-$HOME/xianyu-hunter}"

mkdir -p "$(dirname "$SKILL_DEST")"
rm -rf "$SKILL_DEST"
cp -R "$ROOT/skill/xianyu-hunter-monitor" "$SKILL_DEST"

if [ -e "$PROJECT_DEST" ]; then
  backup="$PROJECT_DEST.backup.$(date +%Y%m%d-%H%M%S)"
  mv "$PROJECT_DEST" "$backup"
fi
cp -R "$ROOT/project/xianyu-hunter" "$PROJECT_DEST"
cd "$PROJECT_DEST"
npm install
npx playwright install chromium
```

## Verification before sharing

Run these checks before delivering archives:

```bash
OUT=/path/to/xianyu-hunter-hermes-skill
for bad in \
  'project/xianyu-hunter/browser-data' \
  'project/xianyu-hunter/node_modules' \
  'project/xianyu-hunter/.git' \
  'project/xianyu-hunter/reports' \
  'project/xianyu-hunter/data/tasks.json' \
  'project/xianyu-hunter/data/config.json' \
  'project/xianyu-hunter/data/notify-config.json'; do
  test ! -e "$OUT/$bad" || { echo "BAD_INCLUDED $bad"; exit 2; }
done
```

Also scan for common secret patterns (`sk-...`, `OPENAI_API_KEY=`, `access_token`) while excluding explanatory docs if needed.

Generate both formats and hashes:

```bash
tar -czf xianyu-hunter-hermes-skill.tar.gz xianyu-hunter-hermes-skill
zip -qr xianyu-hunter-hermes-skill.zip xianyu-hunter-hermes-skill
shasum -a 256 xianyu-hunter-hermes-skill.tar.gz xianyu-hunter-hermes-skill.zip > SHA256SUMS.txt
```

## Publishing to self-hosted Gitea

Ask the user for these details:

```text
Gitea 地址：
仓库归属：用户或组织名
仓库名：
是否新建仓库：是/否
公开/私有：public/private
认证方式：Personal Access Token / SSH / 已配置 HTTPS 凭据
Token（如需 API 建仓或 HTTPS push）：
```

If token is provided, prefer a short-lived token with repo create/read/write permission and remind the user they can revoke it after upload.

For an existing repo, a clone URL plus working SSH/HTTPS credentials is enough. For a new repo, create via Gitea API or ask the user to create it, then push:

```bash
git init
git add .
git commit -m "Initial xianyu-hunter Hermes skill package"
git branch -M main
git remote add origin <gitea-clone-url>
git push -u origin main
```

Avoid committing generated runtime state even if the project directory contains it locally.