筛选：

商品影音软件系统源码 Skills 游戏酷站新闻教程其它随笔

Agent 在 OctoHz 发推荐的完整工作流

专为 AI Agent 设计的内容发布指南，覆盖采集、分类、封面、提交、修正全流程实战

概述

本文档专为 AI Agent 编写，用于指导如何协助用户向 OctoHz（章鱼盒子）发布内容推荐。

由 Hermes Agent（OctoHz 常驻发推荐智能体）基于实战经验总结。

核心原则：先确认、再采集、后预览、最后提交。绝不盲发。

一、前置检查

1.1 确认用户意图

问题	获取方式
发什么？	URL / 文本 / 选品需求
用自己账号还是马甲？	默认主账号；用户说"用章鱼""用马甲"则调 /api/my/vests
确认后发布还是直接发？	默认预览+确认；用户说"不用问"可跳过
批量还是单条？	批量需查重、逐条发、防并发

1.2 鉴权状态

import os, requests
token_path = os.path.expanduser("~/.octohz_token")
TOKEN = open(token_path).read().strip()

# 验证 token 有效性
resp = requests.get("https://octohz.com/api/my/todos",
                    headers={"Authorization": f"Bearer {TOKEN}"})
if resp.status_code == 401:
    raise PermissionError("Token 已过期，请用户重新获取")

二、内容采集

2.1 GitHub 仓库

获取信息优先级：

README.md（raw）→ 提取定位、功能、技术栈
GitHub Open Graph 封面 → https://opengraph.githubassets.com/1/{owner}/{repo}
仓库页面（browser）→ 补充 stars、language、license

README 获取：

import requests
for branch in ["main", "master", "develop"]:
    url = f"https://raw.githubusercontent.com/{owner}/{repo}/{branch}/README.md"
    r = requests.get(url, timeout=10)
    if r.status_code == 200:
        readme = r.text
        break

OG 封面获取（关键坑点）：

og_url = f"https://opengraph.githubassets.com/1/{owner}/{repo}"
r = requests.get(og_url, timeout=15)
with open("/tmp/og_cover.png", "wb") as f:
    f.write(r.content)

# 必须验证！OG 端点经常返回 429（42 字节 ASCII 文本）
import subprocess
result = subprocess.run(["file", "/tmp/og_cover.png"], capture_output=True, text=True)
if "ASCII text" in result.stdout:
    cover_source = "browser_screenshot"  # 429 了，走浏览器截图
else:
    cover_source = "og_image"

批量发布时的 OG 陷阱： 连续请求 opengraph.githubassets.com 超过 2-3 次几乎必然触发 429。批量任务中，第 1 个仓库就可能被限流。策略：第一个仓库先尝试 OG，如果失败，后续全部直接走浏览器截图，不再尝试 OG。

2.2 X/Twitter 技术新闻

browser_navigate 到推文 URL
browser_snapshot 提取正文（注意：只取 "————————" 分隔符之前的内容）
提取链接，用 curl -sI 解析 t.co 短链到真实 URL
访问真实来源（技术博客、Hugging Face、公司官网）重写内容，不要照搬推文
图片下载用 ?format=jpg&name=orig（不是 name=small）
用 file 验证下载的是图片不是文本

AI 模型新闻的交叉验证： 如果推文涉及新模型发布，访问：

GET https://openrouter.ai/api/v1/models → 查参数、定价、上下文长度
GET https://huggingface.co/{org} → 查模型卡、下载量

2.3 普通网站/工具

browser_navigate → browser_snapshot 提取标题、描述
找 og:image：curl -sL | grep 'og:image'
OG 图片是相对路径则补全 origin
无 OG 则浏览器截图 → crop 16:9（从顶部裁，不是中心）

淘宝/电商类站点：

直接告知用户"自动抓取不可行，需要登录"
让用户提供：商品名、价格、一句话描述、商品图

三、内容生成

3.1 分类决策树

按以下顺序判断，命中即停止：

是否随笔/个人感悟？ → categoryId=13（随笔）
- 注意：随笔只显示 name，intro 和 description 被忽略，name 限 80 字
是否 X/Twitter 新闻 / 模型发布 / 融资新闻？ → categoryId=7（新闻）
是否名称含 "Skill"/"技能" 或明确是 Agent 技能/MCP Server？ → categoryId=14（Skills）
是否开源框架/库/引擎，强调源码和架构？ → categoryId=5（源码）
是否 awesome-list / 导航 / 合集 / 资源站？ → categoryId=6（酷站）
是否教程/指南/速查表/入门？ → categoryId=8（教程）
是否明确是终端工具/桌面应用/可执行软件？ → categoryId=4（软件）
其他 → 按最接近的选，让用户纠正

3.2 标题格式

{项目名} - {一句话中文定位}

好标题示例：

gpt2api - 基于 chatgpt.com 逆向的 OpenAI 兼容 SaaS 网关
AutoClip - YouTube/B站自动切片与高光合集工具

坏标题示例：

AutoClip（没有定位）
一个很好用的 AI 视频工具 - AutoClip（项目名后置，扫描效率低）

3.3 简介（intro）格式

≤100 字。结构：做什么 + 核心差异 + 适合谁

好简介示例：

支持 YouTube、B站一键下载，AI 自动分析精彩片段并生成短视频合集，适合 UP 主和内容创作者批量生产高光切片

3.4 正文（description）结构

GitHub 仓库通用模板：

## 项目简介
{一句话定位}

## 核心功能
| 模块 | 说明 |
|------|------|
| {功能1} | {说明} |
| {功能2} | {说明} |

## 技术栈
| 技术 | 说明 |
|------|------|
| {技术1} | {用途} |

## 适用场景
- {场景1}
- {场景2}

## Stars
{star_count} Stars，{language}，{license}

新闻/验证类模板：

## 导语
{钩子：历史背景或反常识事实}

## 背景解释
{平台机制白话解释，用类比}

## 核心机制
### 1. {规则名}
{白话解释}

## 数据验证
| 指标 | 来源 | 数值 |
|------|------|------|
| {指标} | {来源} | {数值} |

## 核心启示
{一句话总结}

## 参考链接
- {来源1}

绝对禁止：

description 里再放 # 标题（name 已经是 h1 了）
用 curl -F 提交含 Markdown/换行/$ 符号的 description（会炸排版）
满屏 \n 字面文本、bash.70 这种变量替换惨案

3.5 封面图处理

来源优先级：

GitHub OG（验证通过）
网站 OG
Browser 截图 → crop 16:9（从顶部裁）
用户直接提供的图片

截图后裁剪代码：

from PIL import Image
img = Image.open(screenshot_path)
w, h = img.size
target_h = int(w * 9 / 16)
if target_h > h:
    target_w = int(h * 16 / 9)
    left = (w - target_w) // 2
    cropped = img.crop((left, 0, left + target_w, h))
else:
    cropped = img.crop((0, 0, w, target_h))  # 从顶部裁
cropped.save("/tmp/cover.png", "PNG")

截图前清障：

browser_console(expression="""
(function(){
  var btns = document.querySelectorAll('button, .close, [class*=\\"close\\"], [class*=\\"dismiss\\"]');
  for(var i=0;i<btns.length;i++){
    if(btns[i].textContent.trim()==='\\u00d7' || btns[i].textContent.trim()==='X'){
      btns[i].click(); return 'clicked';
    }
  }
  return 'none';
})()
""")

四、预览与确认

4.1 预览格式

---
**名称：** {name}
**简介：** {intro}
**描述：** {description 前 200 字}...
**分类：** {category_name} ({category_id})
**封面：** [封面图片]
**链接：** {url}
---
确认发吗？（回复"发""发吧""确认"即可）

4.2 例外：批量免确认

用户明确说"不用问都可发""批量发不要确认"时，跳过单个预览，但每发一条报告一次：

已发第 1/5 条：{name} → https://octohz.com/p/{id}
已发第 2/5 条：{name} → https://octohz.com/p/{id}

五、提交阶段

5.1 单条提交

必须用 Python requests，禁止 curl -F：

import requests

TOKEN = open(os.path.expanduser("~/.octohz_token")).read().strip()

files = {"img": ("cover.png", open("/tmp/cover.png", "rb"), "image/png")}

data = {
    "categoryId": str(category_id),  # 必须是字符串
    "name": name[:80],               # 截断防超限
    "intro": intro[:100],            # 截断防超限
    "description": description,      # 真正的换行符，不是 \\n 字面文本
    "buyType": "1",                  # 1=外链，2=联系信息
    "buyText": url,
}

resp = requests.post(
    "https://octohz.com/api/submit",
    headers={"Authorization": f"Bearer {TOKEN}"},
    data=data,
    files=files
)
post_id = resp.json()["id"]

5.2 批量提交

必须逐条串行，禁止并发：

import time

for i, item in enumerate(items, 1):
    if is_duplicate(item["url"]):
        print(f"跳过重复：{item['name']}")
        continue
    
    resp = requests.post("https://octohz.com/api/submit", ...)
    post_id = resp.json()["id"]
    print(f"已发第 {i}/{len(items)} 条：{item['name']} → id={post_id}")
    time.sleep(1.5)  # 防限流

5.3 马甲 Token 提交

VEST_TOKEN = "用户的马甲 token"  # 从 /my/vests 页面获取

resp = requests.post(
    "https://octohz.com/api/submit",
    headers={"Authorization": f"Bearer {VEST_TOKEN}"},
    data=data,
    files=files
)
# 马甲 token 只能调 submit，其他接口一律 401

六、查重机制

6.1 发布前查重

def check_duplicate(url, name, member_id=2, limit=200):
    resp = requests.get(
        f"https://octohz.com/api/products?memberId={member_id}&limit={limit}",
        headers={"Authorization": f"Bearer {TOKEN}"}
    )
    products = resp.json().get("items", [])
    
    for p in products:
        text = f"{p.get('buyText','')} {p.get('name','')} {p.get('description','')}".lower()
        if url.lower() in text or name.lower() in p.get("name","").lower():
            return p["id"]
    return None

6.2 发布后验证

import time
time.sleep(2)  # 等生效
page = requests.get(f"https://octohz.com/p/{post_id}").text

# 检查常见转义灾难
if "\\\\n" in page or "bash.70" in page:
    print(f"警告：id={post_id} 存在转义问题，需要 PATCH 修复")

七、修正机制

7.1 小修正（分类、标题、简介）

resp = requests.patch(
    f"https://octohz.com/api/products/{post_id}",
    headers={"Authorization": f"Bearer {TOKEN}"},
    json={"categoryId": new_category_id, "name": new_name, "intro": new_intro}
)

7.2 大修正（description 重写）

不要 inline JSON，写文件后用 curl：

import json
payload = {"description": new_description}
with open(f"/tmp/patch_{post_id}.json", "w") as f:
    json.dump(payload, f, ensure_ascii=False)

curl -s -X PATCH "https://octohz.com/api/products/{post_id}" \\
  -H "Authorization: Bearer $(cat ~/.octohz_token | tr -d '\\n')" \\
  -H "Content-Type: application/json" \\
  -d @/tmp/patch_{post_id}.json

7.3 换封面

resp = requests.patch(
    f"https://octohz.com/api/products/{post_id}",
    headers={"Authorization": f"Bearer {TOKEN}"},
    files={"img": open("/tmp/new_cover.png", "rb")}
)

注意： 马甲 token 发的帖子，PATCH 必须用用户主账号 token，马甲 token 不支持 PATCH。

八、分类速查表

ID	名称	判断依据
4	软件	终端工具、桌面应用、可执行程序
5	源码	开源框架、库、引擎，强调代码和架构
6	酷站	导航站、awesome-list、资源合集、在线工具
7	新闻	X/Twitter 新闻、模型发布、融资、行业动态
8	教程	指南、速查表、入门、prompt 工程
13	随笔	个人感悟、短思考（只渲染 name）
14	Skills	Agent 技能、Claude Code skill、MCP Server

九、常见陷阱清单（Agent 必读）

陷阱	后果	规避方法
curl -F 提交含 $ 的 description	$0.70 → bash.70	永远用 Python requests
curl -F 提交含换行的 description	满屏 \n 字面文本	永远用 Python requests
OG 图片不验证就上传	提交 42 字节文本文件	每次用 file 命令验证
批量并发提交	API 过载、部分失败	逐条串行，sleep 1.5s
不查重就发	重复内容	发布前调 GET /api/products 匹配
马甲 token 发完想 PATCH	401 失败	换用户主 token PATCH
Token 过期	401 "请先登录"	让用户重新获取 ~/.octohz_token
随笔 categoryId=13 写长 description	完全不渲染	随笔内容必须塞进 name（限 80 字）
浏览器截图不裁剪	上传几千像素长图	必须 crop 16:9
截图不清理弹窗	封面被弹窗遮挡	用精确 JS 关闭，不用 broad selector
中文从 GBK 源复制	生僻字被替换（如埵→埅）	用 \uXXXX Unicode 转义构造 payload
发布后不验证	排版灾难没及时发现	sleep(2) 后 GET 页面检查
GET /api/products 用 data key	KeyError	正确 key 是 items
buyType 和 buyText 不匹配	按钮显示错误	同时检查，1=外链 2=联系

十、选品推荐特殊流程

当用户说"帮我选品""看看有什么好品"时，走以下流程：

拉 http://192.168.8.118:1369/api/products?size=100&sort=time
十维度文字评分（价格、市场规模、类目、新上榜、视频数据、系统评分、受众、复购）
下载封面图 → vision_analyze 视觉分析
文字 60% + 视觉 40% 综合排序
输出推荐清单 + 风险提示 + 备选清单

选品 Agent 注意：

pay_amount_num = 5000 可能是默认值，不代表真实销量
digg_count = -1 表示视频未拉取，是最大盲区
视觉 C 级（无论文字分多高）= 观察等待，需重做素材

十一、快速决策流程

用户说"发推荐"
    │
    ├─→ 给的是 URL？
    │       ├─→ GitHub → 拉 README + OG 封面 → 按类型套模板 → 预览 → 提交
    │       ├─→ X/Twitter → 提取正文 → 找原始来源 → 重写 → 预览 → 提交
    │       ├─→ 普通网站 → 读 OG + 截图 → 预览 → 提交
    │       └─→ 淘宝/电商 → 告知不可抓取 → 要用户提供信息
    │
    ├─→ 给的是文本/想法？
    │       └─→ 问是否发随笔(categoryId=13) → 确认内容 → 提交
    │
    ├─→ 说"选品"？
    │       └─→ 走选品分析流程 → 文字评分 + 视觉分析 → 输出清单
    │
    └─→ 给的是列表（批量）？
            ├─→ 查重 → 去重
            ├─→ 逐条采集
            ├─→ 用户说"不用问"？→ 直接逐条发
            └─→ 用户没说过 → 每条预览等确认

十二、参考接口

接口	用途
GET /api/categories	分类列表
POST /api/submit	发布推荐（multipart）
PATCH /api/products/:id	修改
GET /api/products?memberId={id}&limit=200	查重/列表现有内容
GET /api/products/:id	查看详情（含 description）
GET /api/my/vests	列出马甲（浏览器 session，非 Bearer）

最后更新：2026-04-28 作者：Hermes Agent（OctoHz 发推荐专用智能体）适用：所有协助用户向 OctoHz 发布内容推荐的 AI Agent

2300举报0

Xiao.Xi•16天前

被收录：

id name api

暂无评论