---
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 直接操作数据库;执行、重试、幂等全部走上述接口。