99 lines
5.7 KiB
Markdown
99 lines
5.7 KiB
Markdown
---
|
|
name: profilemax-publishing
|
|
description: ProfileMax「发布」能力的外部 Agent 操作手册:导入站点、学习站点并生成/复用 Schema 发布脚本、生成文章、创建发布作业、诊断失败并提交修复、验证已发布链接。所有操作经 ProfileMax MCP 工具或 /api/publishing REST 完成;ProfileMax 只负责确定性执行、持久化与校验,不运行大模型。
|
|
---
|
|
|
|
# ProfileMax 发布(Publishing)Agent 操作手册
|
|
|
|
适用场景:在已授权或允许投稿的第三方网站发布含目标外链的文章(外链建设/内容分发)。
|
|
执行链路:你(外部 Agent)负责学习站点、写/修脚本、生成内容;ProfileMax 负责调度执行、
|
|
幂等防重、持久化、失败记录与链接检查。
|
|
|
|
## 0. 前置与鉴权
|
|
|
|
- MCP:Bearer 用户 API Token(与 MCP Token 同值);先 `whoami` 核对身份与权限(需 publishing)。
|
|
- 核心工具:`publishing_import_sites` / `publishing_save_article` / `publishing_create_job` /
|
|
`publishing_get_job` / `publishing_verify_job` / `publishing_get_repair_context`;
|
|
站点与脚本管理复用 `list_profiles` / `create_script` / `update_script` / `run_script` / `get_script_run`。
|
|
- 项目列表经 REST `GET /api/publishing/projects`(无专用 MCP 工具)。
|
|
|
|
## 1. 导入站点
|
|
|
|
1. `publishing_import_sites { projectId, csv | items }` 批量导入(项目内按 URL 去重,重复跳过)。
|
|
2. 对每个站点:从返回列表/`GET /api/publishing/sites?projectId=` 取 id;
|
|
`PATCH /api/publishing/sites/:id` 关联:
|
|
- `profileId`:该站点获授权的发布账号 Profile(必须已有登录态,见 Profile Cookie 能力);
|
|
- `scriptId`:发布脚本(见 §2;阶段 A 仅接受 Schema 编排脚本);
|
|
- `platform` / `tags` 按实际填写(业务标签用于筛选,与页面 Tabs 无关)。
|
|
|
|
## 2. 学习站点与发布脚本
|
|
|
|
1. **学习**:用现有浏览器能力学习站点(`start_browser` + `execute_js` / `fetch_url`),
|
|
弄清登录态、发帖入口、表单字段、富文本编辑器行为、防 Bot 措施。
|
|
2. **脚本形态**:发布脚本必须是 **Schema 编排(kind=schema)**,其中至少一个
|
|
`script.run` 步骤承载主流程。运行时 ProfileMax 把本次文章参数注入该步骤的
|
|
`ctx.vars.publish`(标准 I/O):
|
|
|
|
```typescript
|
|
interface PublishInput {
|
|
siteId: string;
|
|
article: { title: string; html: string; markdown?: string; images?: string[] };
|
|
targetLinks: Array<{ url: string; anchor: string }>;
|
|
mode: "draft" | "publish";
|
|
}
|
|
interface PublishResult {
|
|
status: "draft" | "published" | "failed" | "unknown";
|
|
articleUrl?: string; // 发布后的文章 URL(验证与评分依赖它)
|
|
externalId?: string; // 站点侧文章 ID
|
|
errorCode?: string; // 稳定错误码(如 LOGIN_EXPIRED / CAPTCHA / SELECTOR_MISS)
|
|
message?: string;
|
|
}
|
|
```
|
|
|
|
脚本末尾 `return { status, articleUrl, ... }`;ProfileMax 据此把执行终态映射为业务状态。
|
|
**不要**在脚本里硬编码文章内容;**不要**写死 Selector 之外的 URL。
|
|
3. **测试**:开发期用 `run_script { profileRefs:[指纹] }` 直接试跑(可先给样例 vars 手动验证),
|
|
或先建一篇文章走一次完整 `publishing_create_job`。
|
|
4. **提交候选**:脚本改动用 `update_script` 保存(不要覆盖正在运行的版本时再改;先在测试号验证)。
|
|
5. **安全红线**:节点侧 `code` 以 `new Function` 执行、无沙箱;脚本内容要像对待生产代码一样审查,
|
|
不得引入抓取密钥、横向访问内网等行为。Agent 生成的代码在审查通过前不得进入生产站点脚本。
|
|
|
|
## 3. 生成文章
|
|
|
|
1. 结合项目 config(关键词/语言/内容规则,见 `GET /api/publishing/projects`)生成有实际价值的文章,
|
|
自然植入目标外链(targetLinks 的 anchor 与上下文匹配)。
|
|
2. `publishing_save_article { projectId, title, markdown|html, targetLinks, status }`;
|
|
内部审阅通过后置 `status=ready`。内容更新走同一工具带 `articleId`(版本自动自增)。
|
|
|
|
## 4. 创建发布作业与跟进
|
|
|
|
1. `publishing_create_job { articleId, siteId, mode }`(站点须已绑定脚本+Profile;
|
|
同文章/站点/模式有在途作业会 409;同 Profile 串行执行)。
|
|
2. 轮询 `publishing_get_job { id }`:
|
|
- `published`(附 articleUrl)/`draft` → 完成,转 §6;
|
|
- `unknown`(超时)→ **先 `publishing_verify_job`(或人工核对 URL)确认是否已发布,再决定重试**,
|
|
避免重复提交;
|
|
- `failed` / `needs_repair` → 转 §5;
|
|
- 幂等:作业的 `idempotencyKey` 全程不变;`retry` 会复用它,不会产生重复发布记录。
|
|
|
|
## 5. 失败诊断与修复
|
|
|
|
1. `publishing_get_repair_context { id }` 领取:返回脱敏错误、执行步骤/日志、站点信息、
|
|
当前脚本 Schema 与本次 PublishInput;failed/unknown 作业同时标记 `needs_repair`。
|
|
2. 依据 errorCode 与步骤日志定位(常见:LOGIN_EXPIRED → 提示用户续 Cookie;SELECTOR_MISS →
|
|
站点改版,重新学习页面;CAPTCHA → 建议站点脚本接入挑战开关)。
|
|
3. 修改脚本 → `update_script` 提交 → 用测试 Profile `run_script` 验证 → 对该作业 `POST
|
|
/api/publishing/jobs/:id/retry`(或重跑 `publishing_create_job`)。
|
|
|
|
## 6. 发布后验证
|
|
|
|
- `publishing_verify_job { id }`:HTTP 拉取 articleUrl,记录页面状态码、目标链接存在性与
|
|
rel 属性(nofollow/sponsored 会体现在检查记录),结果进入质量评分。
|
|
- 需要登录/JS 渲染才能核验的页面,用 Profile `fetch_url`(browser 运行时)人工复核,阶段 C 将自动化。
|
|
|
|
## 7. 约束
|
|
|
|
- 只发布有授权或允许投稿的站点,遵守站点规则与频率限制;
|
|
- Profile/脚本/作业均有归属与权限校验,越权请求直接 403/404;
|
|
- 不要绕过 ProfileMax 直接操作数据库;执行、重试、幂等全部走上述接口。
|