root/geo

Files

T

root 15a820712e docs: update MCP agent publishing PRD

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

2026-07-03 20:55:33 +08:00

81 KiB

Raw Permalink Blame History

GEO SaaS MCP Agent Publishing PRD V1

1. 文档信息

项目	内容
文档名称	GEO SaaS MCP Agent Publishing PRD V1
文档版本	V1.2
文档状态	待评审
创建日期	2026-06-09
最近修订	2026-07-02
适用阶段	MCP 智能体接入 / 企业内容生成 / 多平台发布 / AI 可见度监测 / 桌面端采集
关联文档	`docs/geo-platform-prd-v1.md`
关联文档	`docs/qdrant-rag-architecture-v1.md`
关联文档	`docs/superpowers/specs/2026-04-18-electron-desktop-client-design.md`
关联文档	`docs/enterprise-site-publisher-v1.md`
关联文档	`docs/ai-brand-monitoring-tech-design-v5.md`
关联文档	`docs/worklogs/2026-04-20-legacy-plugin-design-status.md`

1.0 修订记录

V1.0 → V1.1

修订点	V1.0	V1.1
发布平台范围	P0 仅搜狐号 `sohuhao`	P0 覆盖桌面端已上线的全部 13 个媒体平台，MCP 协议层平台无关，平台可用性由平台目录与适配器就绪度决定
AI 平台范围	未涉及	P0 覆盖客户端已绑定的全部 6 个 AI 监测平台（DeepSeek、豆包、Kimi、通义千问、文心一言、元宝）
能力暴露范围	仅发布闭环	以"SaaS 与客户端已有能力基本全量暴露"为原则，新增 AI 监测、企业站点发布、定时发布、发布记录、配额积分、合规预检等能力域
会话状态模型	自定义 live/captcha/risk 枚举	对齐桌面端真实枚举 `active / expiring_soon / challenge_required / expired / revoked / unknown`，客户端离线时禁止下结论
发布模型	单文章单账号	对齐现有 PublishBatch 模型，支持一篇文章多账号多平台批量分发与部分成功状态
错误模型	含搜狐专用错误码	平台无关错误码，新增配额、限流、平台能力不支持、站点发布、监测采集等错误码
工具与提示词命名	含 sohu 专用命名	全部平台参数化命名

V1.1 → V1.2（评审修订，对齐代码实态与协议缺口）

修订点	V1.1	V1.2
批次部分成功口径	引用 `partial_failed`	对齐代码实际枚举 `partial_success`
监测调度通道	HIGH/NORMAL/LOW	对齐实际通道 `high` / `normal`（重试走独立 `retry` 通道），无 `low`
定时发布语义	笼统"复用 schedules"	拆分为一次性定时发布（桌面复用发布任务 `scheduled_at`；企业站点为新增服务端延迟执行）与循环定时生成计划（ScheduleTask，daily/weekly）两条链路，新增 `schedule_plan_create` / `schedule_cancel`
长任务模型	generate 同步描述与"一律可轮询"矛盾	统一异步口径，新增 `run_status` 统一轮询工具，逐工具标注同步/异步
用户选择恢复	状态机有挂起态但无恢复入口	新增 `agent_run_continue`（P0），定义挂起 TTL 与过期语义；resume 自 P1 提前
Confirmation token	绑定单一 version + hash	升级为逐目标 (platform, account/site, version, content hash) 元组，覆盖多平台变体
工具命名	`geo.` 点号前缀	去点号改下划线命名（主流 LLM API 工具名约束 `[a-zA-Z0-9_-]` 不含点号）；本地桥工具改 `local_` 前缀
幂等性	仅发布 version+target dedup	创建型工具统一支持 `idempotency_key`，站点发布强制
信任边界与数据披露	未写明	§17 新增 agent 代述确认信任边界、可选带外强确认、按 scope 数据外发披露
限流与配额	共享 token bucket 一句话	§16 增加保活保底/collect-now 上限仲裁规则；§11 定义中途配额耗尽行为
部署与会话	未涉及多副本	§2 补 `Mcp-Session-Id` 会话亲和、elicitation 超时回退
错误码	—	新增 `article_not_found` / `article_version_stale` / `site_not_found` / `agent_run_not_found` / `agent_run_expired` / `idempotency_conflict`；message 统一中文
交付计划	10 项无排序	补第 11 项租户后台 Agent 集成管理页；标注内部交付顺序（P0 范围不变）
指标	仅可靠性指标	§22 补采用度指标与网关非功能指标

1.1 文档目标

本文档定义 GEO SaaS 面向外部智能体（小龙虾、Hermes 等）的 MCP 能力规划，使智能体可以通过标准工具调用完成以下闭环：

理解用户自然语言需求。
读取当前租户、品牌、知识库、图片素材、媒体账号、AI 监测账号与桌面客户端状态。
基于企业知识库生成企业软文等内容。
在需要时像 Claude Code 一样提出选项并等待用户确认。
在用户授权范围内复用本地桌面客户端的媒体平台登录态，将文章发布到用户绑定的任意媒体平台（一次可分发多个账号、多个平台）。
通过服务端 CMS 适配器将文章发布到企业自建站点（WordPress、PBootCMS）。
创建与管理定时发布计划。
复用客户端绑定的 AI 平台账号执行品牌可见度监测（GEO 排名/提及/引用源），并读取监测看板数据。
复用同一套本地 session 执行发布状态检查与平台数据采集。
查询 AI 积分配额与用量，理解每次调用的成本。

1.2 背景判断

现有平台已经具备内容生成、知识库 RAG、媒体账号管理、桌面客户端发布与监测任务、13 个媒体平台适配器、6 个 AI 平台监测适配器、企业站点发布、定时发布、发布记录与合规拦截等基础能力。MCP 不是重做一套内容平台，而是在现有 SaaS 能力上增加一层智能体可发现、可调用、可审计的操作协议。

核心原则：凡是用户在 Web 后台或桌面客户端已经能做的常规操作，智能体在授权范围内也应能做；凡是用户已绑定且健康的账号（媒体账号与 AI 账号），MCP 都能发现并使用。 MCP 层不为任何单一平台特化。

1.3 MCP 接入原则

MCP 的三个能力边界按以下方式落地：

MCP 能力	本产品中的用途
Tools	暴露可执行动作，如查询工作区、搜索知识库、生成文章、检查本地 session、批量发布、定时发布、站点发布、触发监测采集、读取监测数据
Resources	暴露可读取上下文，如品牌资料、知识库分组、图片素材、平台能力目录、媒体账号、AI 账号、文章草稿、发布记录、监测概览、配额用量
Prompts	暴露可复用工作流模板，如企业软文生成、引导式多平台发文、平台风格改写、监测解读

MCP 客户端可以决定如何展示资源和提示词，但服务端必须保证租户隔离、权限校验、审计追踪和敏感信息不外泄。

Problem Statement

品牌运营用户现在想通过智能体直接完成内容运营任务，例如一句话说：

帮我把这篇企业软文发到搜狐号和百家号。这周豆包和 DeepSeek 上我们品牌的提及情况怎么样？给我们的官网和头条号各发一篇关于新品发布的文章，官网立刻发，头条号明早 9 点发。

但当前 SaaS 主要面向 Web 后台操作，智能体无法稳定、标准化地完成以下动作：

无法发现当前租户下有哪些品牌、知识库分组、图片素材、可发布的媒体账号、可用的 AI 监测账号和企业站点。
无法自动判断用户是想"自由发挥直接发"，还是希望先给选题、标题、文章结构等建议后再确认。
无法以可审计方式调用企业知识库生成软文。
无法知道本机桌面客户端是否在线，目标平台账号 session 是否过期。
无法复用本地 session 直接发文、监测或采集数据。
无法把一篇文章一次性分发到多个平台账号，或创建定时发布计划。
无法在发布前后获得统一的任务状态、失败原因、外部链接和可重试建议。
无法读取 AI 品牌监测结果（提及率、排名、引用源），也无法触发一次即时采集。
无法了解 AI 积分余量，导致自动化任务可能在配额耗尽时静默失败。

从用户视角看，他们不想在 Web 后台、知识库、图片库、媒体管理、监测看板、桌面客户端之间来回切换；他们希望把"企业知识 + 文章生成 + 图片选择 + 多平台发布 + 监测回看"交给可信智能体完成。

Solution

建设 GEO MCP Agent Gateway，为小龙虾、Hermes 等智能体提供标准 MCP 接入。P0 即按平台无关架构交付，覆盖用户绑定的全部媒体平台与 AI 平台，不做单平台特化版本。

能力域总览

MCP 暴露的能力域与现有系统能力的对应关系（这是"全量暴露"原则的落地清单）：

能力域	现有系统能力	MCP 暴露方式	优先级
工作区上下文	workspace overview / quota	Tools + Resources	P0
品牌资产	品牌、关键词、问题、竞品	Resources（读）	P0
知识库	分组、条目、RAG 检索、高精事实	Tools（检索）+ Resources（读）；写入条目 P1	P0
图片素材	图片库、文件夹、引用关系	Tools（选图排序）+ Resources（读）；上传 P1	P0
文章与生成	提示词规则生成、模板生成、仿写、重新生成、版本	Tools + Resources	P0
多平台发布	13 个桌面端平台适配器、PublishBatch、发布记录、重试	Tools + Resources	P0
定时发布	一次性定时（桌面复用发布任务 `scheduled_at`；站点延迟执行为新增）+ 循环定时生成计划（ScheduleTask，daily/weekly）	Tools + Resources	P0
企业站点发布	WordPress / PBootCMS 服务端适配器	Tools + Resources	P0
账号健康	桌面端保活探测、健康上报	Tools（session check）+ Resources	P0
AI 品牌监测	6 个 AI 平台适配器、监测任务、看板、引用源	Tools（读 + collect-now）+ Resources	P0
合规	发布前合规 gate、ack 流程	Tools（预检、ack）	P0
配额与积分	AI points、quota reservation、用量日志	Resources（读）	P0
审计	agent run / tool call 记录	Resources（读）	P0
桌面深度采集	内容列表对账、平台指标、账号资料刷新	Tools	P1
本地 MCP Bridge	同机智能体直连客户端	独立本地 server	P1
KOL 市场	套餐订阅、KOL 提示词	不暴露（涉及跨租户交易）	P2

用户可见的工作流

用户可以在智能体中输入自然语言任务，智能体通过 MCP 工具完成：

读取当前工作区、品牌、知识库、图片素材、全部已绑定媒体账号（含平台与健康状态）、AI 监测账号、企业站点和桌面客户端在线状态。
解析用户需求，判断是否信息足够；解析目标平台（一个或多个）与发布时间要求（立即/定时/草稿）。
信息不足时返回 2 到 4 个关键选项供用户选择，例如品牌、目标平台与账号组合、选题方向、文章风格、是否直接发布。
信息足够时调用知识库检索与文章生成，生成企业软文草稿；需要时按目标平台风格改写出平台变体。
自动选择或建议封面图、正文图，并校验目标平台的图片要求（由平台能力目录给出）。
发布前对每个目标账号调用本地 session 检查，确认账号处于可发布状态。
在用户确认或授权策略允许时创建发布任务：桌面平台走 PublishBatch + 桌面任务；企业站点走服务端 CMS 适配器；定时需求走一次性定时或循环生成计划两条链路（见 §13）。
桌面客户端复用本地平台 session 执行图片上传、正文提交和结果回写；多个目标账号并行分发。
智能体返回每个目标的发布状态、外部文章 ID、管理链接、公开链接、失败原因或下一步建议；批量发布支持部分成功。
需要监测时，智能体读取监测看板（提及率、排名、引用源），或触发一次 collect-now 即时采集，由客户端绑定的 AI 账号执行。

首版能力分为两种使用模式：

模式	说明	适用场景
引导模式	智能体先给建议、标题、结构、平台组合或图片候选，用户确认后继续	新用户、重要文章、高风险发布、多平台分发
自动模式	智能体基于默认品牌、默认知识库和默认账号直接生成并进入发布确认或自动发布	明确授权的重复运营任务

无论哪种模式，服务端都不保存任何媒体平台或 AI 平台的 cookie。平台 session 仍由桌面客户端本地加密保存和复用；企业站点凭证按现有密文存储方案管理。

User Stories

内容生成与发布（品牌运营）

As a brand operator, I want to ask an agent to publish an article to any of my bound platforms in natural language, so that I do not need to manually switch between SaaS pages.
As a brand operator, I want to publish one article to multiple platforms and accounts in one request, so that multi-channel distribution does not require repeated operations.
As a brand operator, I want the agent to infer the relevant brand and target platforms from my request, so that common publishing tasks require fewer inputs.
As a brand operator, I want the agent to ask follow-up questions only when needed, so that simple tasks remain fast.
As a brand operator, I want the agent to offer several article angles, so that I can choose the most suitable soft article direction.
As a brand operator, I want the agent to generate titles before writing the full article, so that I can guide the content tone early.
As a brand operator, I want the agent to use enterprise knowledge, so that the article reflects accurate company information.
As a brand operator, I want the agent to cite which knowledge groups were used internally, so that I can trust the generated article.
As a brand operator, I want the agent to avoid inventing company facts, so that brand risk is reduced.
As a brand operator, I want the agent to preserve high precision facts from the knowledge base, so that addresses, contact information and product parameters remain accurate.
As a brand operator, I want the agent to select a cover image that satisfies each target platform's image requirements, so that the article is publish-ready everywhere I send it.
As a brand operator, I want the agent to recommend image candidates when there are multiple suitable images, so that I can choose without opening the image library.
As a brand operator, I want the agent to explain when no suitable image is available, so that I can upload or approve a text-only draft where the platform allows it.
As a brand operator, I want the agent to save generated content as a SaaS article, so that the draft can be reviewed in the normal article workflow.
As a brand operator, I want the agent to support draft-only generation, so that I can review before publishing.
As a brand operator, I want the agent to support direct publish when I explicitly say so, so that routine tasks can be automated.
As a brand operator, I want a publish preview listing every target account and platform before irreversible publication, so that accidental publishing is avoided.
As a brand operator, I want workspace policy to decide whether trusted agents can auto-publish, so that each company can balance speed and control.
As a brand operator, I want to schedule a publish for a future time through the agent, so that time-sensitive campaigns use the normal scheduler.
As a brand operator, I want to publish to my company website (WordPress / PBootCMS) through the agent, so that owned media is covered without desktop dependency.

账号与会话（品牌运营）

As a brand operator, I want the agent to check whether each target account session is valid before publishing, so that failed publish attempts are reduced.
As a brand operator, I want the agent to reuse the local desktop client session, so that I do not need to share platform credentials with the cloud.
As a brand operator, I want the agent to tell me when the desktop client is offline, so that I know why publishing cannot proceed.
As a brand operator, I want the agent to tell me which specific account session has expired or needs human verification, so that I can fix exactly that account in the desktop client.
As a brand operator, I want expired-session recovery instructions to be specific per platform, so that I can fix the issue quickly.
As a brand operator, I want session states reported from the last verified probe with timestamps, so that I am not misled by stale or offline data.

发布任务与结果（品牌运营 / 内容编辑）

As a brand operator, I want the agent to create publish tasks instead of controlling platforms blindly, so that the SaaS can track status and retries.
As a brand operator, I want the agent to return batch and per-target task IDs and status, so that long-running publish tasks can be followed up.
As a brand operator, I want per-target results including management URL and public URL, so that I can inspect and share each published article.
As a brand operator, I want partial success to be reported clearly when publishing to multiple targets, so that I can retry only the failed ones.
As a brand operator, I want publish failures to include platform-specific reasons, so that I can decide whether to retry or manually intervene.
As a brand operator, I want duplicate publish protection per article version and target account, so that the same article is not posted twice to the same account.
As a brand operator, I want the agent to retry a failed publish target through the existing retry flow, so that recovery does not require the Web console.
As a content editor, I want to regenerate the article from the same brief, so that I can compare versions.
As a content editor, I want to ask the agent to rewrite the article for a target platform's style, so that one article can fan out to platforms with different tones.
As a content editor, I want to ask the agent for title options only, so that I can choose the direction before generating.
As a content editor, I want to ask the agent to use a specified knowledge group, so that the article focuses on a product line or campaign.
As a content editor, I want to ask the agent to avoid specific topics, so that the article respects campaign constraints.
As a content editor, I want the agent to reuse current article drafts, so that I can publish edited content rather than generating again.
As a content editor, I want the agent to collect post-publish status, so that I can see whether the article is accepted by the platform.

AI 可见度监测（品牌运营 / 内容编辑）

As a brand operator, I want to ask the agent how my brand appears across all bound AI platforms (DeepSeek, Doubao, Kimi, Qwen, Wenxin, Yuanbao), so that I can see GEO performance without opening the dashboard.
As a brand operator, I want the agent to report mention rate, mention position and first-recommended status per AI platform, so that I can compare platforms.
As a brand operator, I want the agent to show which URLs the AI platforms cited, so that I know which published content is driving visibility.
As a brand operator, I want to trigger an immediate collection for a brand question through the agent, so that I can verify the effect of recent publishing.
As a brand operator, I want collection to use my bound AI accounts on my desktop client, so that no AI platform credentials ever reach the cloud.
As a brand operator, I want the agent to tell me when an AI account is unavailable for collection, so that I can fix the account or choose another platform.
As a content editor, I want to correlate published articles with citation facts, so that I can report content ROI.

租户管理（tenant admin）

As a tenant admin, I want to decide which agents can connect to my workspace, so that external automation is controlled.
As a tenant admin, I want to assign MCP scopes to each agent, so that one agent can generate drafts while another can publish or collect.
As a tenant admin, I want to disable auto-publish for all agents, so that publication always requires human confirmation.
As a tenant admin, I want audit logs for every MCP tool call, so that I can trace who caused each generated article, publish task and collection run.
As a tenant admin, I want sensitive platform sessions to remain local, so that SaaS security posture remains unchanged.
As a tenant admin, I want to revoke an agent token, so that compromised integrations stop working immediately.
As a tenant admin, I want per-agent rate limits, so that runaway agents cannot burn quota or spam media platforms.
As a tenant admin, I want MCP access to follow tenant and workspace isolation, so that agents cannot read another workspace.
As a tenant admin, I want to see AI point consumption per agent, so that automation cost is attributable.

平台运营（platform operator）

As a platform operator, I want to see MCP tool run health, so that support can diagnose integration failures.
As a platform operator, I want failed MCP tool calls to include normalized error codes, so that support can route issues correctly.
As a platform operator, I want MCP usage to consume or reserve AI points through the existing quota reservation flow, so that billing remains consistent.
As a platform operator, I want agent-generated articles to pass compliance checks before publishing, so that policy enforcement is unchanged.
As a platform operator, I want MCP publish tasks to reuse the existing desktop publish queue and PublishBatch model, so that operational visibility is centralized.
As a platform operator, I want publish status to reconcile into existing publish records, so that dashboards do not fork.
As a platform operator, I want local data collection to use desktop task leases, so that collection jobs can recover from client crashes.
As a platform operator, I want uncertain publish submissions to remain manually reconcilable, so that retry does not duplicate non-idempotent posts.
As a platform operator, I want new platform adapters to become MCP-available through the platform catalog without MCP protocol changes, so that platform expansion stays cheap.

外部智能体（external agent）

As an external agent, I want to discover available tools, resources and prompts, so that I can know what actions the workspace supports.
As an external agent, I want a platform capability catalog, so that I can adapt my plan to each platform's draft support, image requirements and scheduling support.
As an external agent, I want structured tool outputs, so that I can explain next steps to the user.
As an external agent, I want a single orchestration tool for common publish tasks, so that simple user requests can be fulfilled with fewer calls.
As an external agent, I want lower-level tools for search, generate, rewrite, check session, publish, schedule and collect, so that advanced workflows can be composed.
As an external agent, I want confirmation-required responses to be machine-readable, so that I can ask the user for the exact missing decision.
As an external agent, I want publish confirmations to be bound to a content hash and the full target set, so that approval cannot be reused for different content or different targets.
As an external agent, I want session check responses to distinguish active, expiring_soon, challenge_required, expired, revoked, unknown and client-offline, so that I can give precise guidance.
As an external agent, I want quota errors to be explicit, so that I can stop long workflows early and tell the user to top up.

桌面客户端用户

As a desktop client user, I want the local client to execute publish and collection tasks only for my bound workspace, so that local sessions are not misused.
As a desktop client user, I want the client to receive MCP-originated tasks in the same task center, so that I can monitor them normally.
As a desktop client user, I want the client to show when an agent is using a local session, so that local automation is visible.
As a desktop client user, I want to pause local agent execution, so that I can stop automation during sensitive work.
As a desktop client user, I want the local client to expose a loopback MCP bridge only after pairing, so that local agents cannot access sessions silently.
As a desktop client user, I want local bridge actions to sync back to SaaS audit records, so that direct local operations remain traceable.
As a desktop client user, I want local collection jobs to reuse the same platform login state, so that repeated login is unnecessary.

合规与支持

As a compliance reviewer, I want MCP-generated content to go through the same compliance gate as web-generated content, so that policy is consistent.
As a compliance reviewer, I want agent publish approvals to be logged with the article version, so that later review can see the exact approved text.
As a support user, I want to inspect an MCP run timeline, so that I can see whether the failure happened at knowledge retrieval, generation, session check, publish, scheduling, or collection.

Implementation Decisions

1. Product Scope

P0 delivers the platform-agnostic closed loop:

User asks agent -> Agent reads workspace context (brands, knowledge, images,
all bound media accounts, AI accounts, sites, desktop status)
-> Agent generates article (and platform-style variants when needed)
-> Agent checks sessions for every target account -> Agent obtains confirmation if required
-> SaaS creates publish batch / schedule / site publish -> Desktop client or CMS adapter publishes
-> Agent returns per-target results
-> Agent reads monitoring dashboards or triggers collect-now on bound AI accounts

P0 platform coverage:

渠道类型	P0 覆盖	说明
桌面端媒体平台	`toutiaohao` 头条号、`baijiahao` 百家号、`sohuhao` 搜狐号、`qiehao` 企鹅号、`wangyihao` 网易号、`weixin_gzh` 微信公众号、`jianshu` 简书、`juejin` 掘金、`bilibili` 哔哩哔哩、`zhihu` 知乎、`smzdm` 什么值得买、`zol` 中关村在线、`dongchedi` 懂车帝	复用既有桌面适配器与 PublishBatch 发布链路
企业站点	`wordpress`、`pbootcms`	服务端 CMS 适配器，不依赖桌面客户端在线；DedeCMS / PHPCMS 待适配器就绪后进入
AI 监测平台	`deepseek`、`doubao`、`kimi`、`qwen`、`wenxin`、`yuanbao`	复用既有 monitor 任务链路与桌面 AI 适配器

平台可用性规则：

MCP 协议层（工具、资源、提示词、错误码）必须平台无关；任何 sohu、baijia 等平台专名不得出现在工具名、提示词名与错误码中。
单个平台是否可发布由两个条件共同决定：平台目录（media_platforms）中该平台启用，且该工作区存在健康的已绑定账号。
新平台适配器上线后，仅需在平台目录登记能力元数据，MCP 自动继承，无协议层改动。
单个平台适配器的发布稳定性问题（如某平台风控变更）只降级该平台，不影响 MCP 整体可用性。

2. MCP Deployment Model

The product will support two MCP entry points:

Entry point	Priority	Description
SaaS MCP Gateway	P0	Remote MCP server owned by SaaS. External agents connect with scoped workspace credentials. Gateway orchestrates SaaS APIs and dispatches publish or collect tasks to desktop clients.
Desktop Local MCP Bridge	P1	Optional local loopback MCP server hosted by the desktop client. Local agents on the same machine can pair with the client and directly ask it to check sessions, publish and collect data. Results still sync to SaaS.

部署形态：

Gateway 以独立进程 server/cmd/mcp-gateway 交付，与 tenant-api 同 Go module、复用 internal/tenant 应用服务，独立部署独立扩缩容（沿用 ops-api 的同模块独立部署先例）。
传输协议采用 MCP Streamable HTTP。多副本扩缩容下 Mcp-Session-Id 采用网关层会话亲和（按 session ID 哈希路由）；业务状态全部落库、MCP 会话本身不承载业务数据，副本失联时客户端按协议重建会话即可，不丢任务。
长任务（生成、编排、发布执行、采集）一律异步：返回可轮询的 run/batch ID（经 run_status / publish_status 跟进），不依赖长连接存活；同步/异步口径逐工具标注，见 §6。
用户选择决策优先使用 MCP elicitation 能力（客户端支持时），否则回退为本文档定义的机器可读 needs_user_choice 结构化输出。elicitation 等待设超时（默认 120 秒），超时同样回退为挂起 run。两条路径必须语义等价：同一 decisions schema，统一经 agent_run_continue 恢复（见 §7）。

P0 chooses SaaS MCP Gateway first because the existing SaaS already owns tenant auth, knowledge retrieval, article generation, compliance, publish job creation, audit logs and desktop dispatch. The desktop bridge is a controlled extension for "agent directly operates local client" scenarios.

3. Agent Authentication and Authorization

MCP connections must be bound to:

tenant_id
workspace_id
delegated user_id or service account
agent client name, such as xiaolongxia or hermes
scopes

Recommended scopes:

Scope	Capability
`workspace:read`	Read workspace overview, brands, knowledge groups, media/AI accounts, sites, desktop status, quota summary, platform catalog
`knowledge:read`	Search enterprise knowledge and read selected snippets
`knowledge:write`	Add knowledge items (text / URL) — P1
`image:read`	List and select image assets
`image:write`	Import images — P1
`article:write`	Generate, rewrite and save article drafts
`article:publish`	Create publish batches / site publishes / schedules after confirmation
`article:publish:auto`	Publish without per-run human confirmation when workspace policy allows
`schedule:write`	Create, update and cancel scheduled publishes
`site:publish`	Publish to enterprise sites（包含于 `article:publish` 时可合并授权，单列便于最小权限）
`desktop:session:check`	Check local account session state（媒体账号与 AI 账号）
`monitoring:read`	Read monitoring dashboards, question details and citation facts
`monitoring:collect`	Trigger collect-now monitoring runs on bound AI accounts
`data:collect`	Run local platform data collection（content list / metrics / profile）— P1
`audit:read`	Read MCP run history and task status

Agent credentials must be revocable, rate limited and visible in platform audit logs. SaaS user web JWT must not be reused as a long-lived agent credential. P0 采用平台签发的 agent token（哈希入库、可吊销、带 scope 与过期时间）；OAuth 2.1 动态注册为 P1。

Agent token 的签发、scope 勾选、限流配置与吊销通过租户后台 Agent 集成管理页自助完成（P0 交付项 11，见 Further Notes）；授权页按 scope 展示数据外发披露（见 §17）。每个 agent 有默认限流基线：工具调用 QPS、生成类每日次数、collect-now 每小时次数三档（默认值由运营配置、租户可下调），超限返回 rate_limited。

4. MCP Resources

Resources expose read-only context. They must never expose platform cookies, local browser storage, raw desktop vault contents, model API keys, CMS credentials or internal secrets.

Resources 定位原则：部分 MCP 宿主对 Resources 支持较弱，P0 的关键上下文与状态读取必须同时有工具可达（workspace_context、publish_status、run_status 与监测读工具），Resources 作为增强镜像供支持良好的宿主使用。geo://images 中的预览 URL 为短时效签名 URL。

Initial resource set:

Resource URI	Description
`geo://workspace/current`	Current tenant, workspace, user delegation and policy summary
`geo://platforms`	平台能力目录：platform_key、名称、分类、绑定方式、是否支持草稿、封面要求、定时支持、发布通道（desktop/server）、适配器就绪度
`geo://brands`	Brand list available to the agent
`geo://brands/{brand_id}`	Brand profile, keywords, questions, competitors and default generation context
`geo://knowledge-groups`	Knowledge group tree and searchable status
`geo://knowledge-groups/{group_id}`	Group metadata and retrieval readiness
`geo://images`	Image asset list with metadata and expiring preview URLs
`geo://media-accounts`	All bound media accounts across platforms: platform key, health (`auth_state`), owning desktop client, last verified time
`geo://ai-accounts`	All bound AI platform accounts with health and collection availability
`geo://enterprise-sites`	Enterprise site connections, CMS type, connectivity status and categories
`geo://desktop-clients`	Desktop client online state and task capacity summary
`geo://articles/{article_id}`	Article draft, version metadata and publish readiness
`geo://publish-batches/{batch_id}`	Publish batch status with per-target records, external IDs/URLs and errors
`geo://publish-records`	Tenant-level publish record query (recent, by article, by platform)
`geo://schedules`	Scheduled publish list and status
`geo://monitoring/overview`	Monitoring composite dashboard: mention rate, rank, coverage by AI platform
`geo://monitoring/citations`	Citation summary correlating cited URLs with own published articles
`geo://quota/summary`	AI points balance, monthly window usage, per-usage-type breakdown
`geo://agent-runs/{run_id}`	MCP orchestration timeline

5. MCP Prompts

Initial prompt templates（全部平台参数化，不为单一平台命名）：

Prompt	Purpose
`enterprise_soft_article`	Generate an enterprise soft article from brand and knowledge context
`guided_publish`	Step-by-step publishing workflow with platform/account choices and confirmation, parameterized by target platforms
`direct_publish`	Fast path for explicit "generate and publish" requests
`rewrite_for_platform`	Rewrite an existing draft for a target platform's style (tone, length, structure constraints from platform catalog)
`schedule_publish`	Plan a future publish using the scheduler
`collect_platform_data`	Collect publish status or platform data using local session
`monitoring_report`	Summarize brand visibility across bound AI platforms with citations

Prompt output must treat knowledge snippets as reference material, not as higher-priority instructions. This protects against prompt injection inside uploaded enterprise documents.

6. MCP Tools

命名规则：工具名与提示词名仅使用小写字母、数字与下划线（[a-z0-9_]），不使用点号——主流 LLM API 的工具名约束为 [a-zA-Z0-9_-]，点号会在部分 MCP 宿主把工具映射进模型工具列表时被改写或拒绝；MCP server 本身即命名空间，无需 geo. 前缀。每个工具的 description 必须写明"何时调用"，宿主模型据此选择工具。

同步/异步口径：读类与轻量校验工具同步返回；生成、编排、发布执行、采集一律异步（返回可轮询 ID，经 run_status / publish_status 跟进），不受宿主工具调用超时（普遍 60 秒量级）限制。创建型工具统一接受可选 idempotency_key：同 key 重放返回首次创建的资源、不重复创建；同 key 不同请求体返回 idempotency_conflict。

P0 tools（按能力域分组）：

上下文与资产

Tool	Purpose	Notes
`workspace_context`	Return workspace, default brand, knowledge groups, image summary, all bound media/AI accounts with health, enterprise sites, desktop status, quota snapshot	Used at the start of most agent workflows
`knowledge_search`	Search selected knowledge groups using a user brief or generated query	Wraps existing knowledge RAG, returns structured snippets with precise facts
`image_select`	Select or rank image assets for cover and inline usage, validated against each target platform's image requirements	P0 ranks existing assets; generated images are P1

生成

Tool	Purpose	Notes
`article_plan`	Produce title, angle and outline options without generating full article	异步：复用模板 title/outline 任务链路，返回 run ID 经 `run_status` 轮询
`article_generate`	Generate and save an article draft using brand, knowledge, image and user constraints	异步：创建生成 run 返回 run ID（草稿就绪目标 90 秒中位数，超出宿主同步等待预算，必须异步）；完成后经 `run_status` 提供 article ID、version ID、预览与缺失决策。收敛到现有生成入口（prompt rule / template / imitation）。接受 `idempotency_key`
`article_rewrite`	Rewrite a saved draft for a target platform or target reader	异步。多平台分发的平台变体生成，产生新文章版本；P0。接受 `idempotency_key`

发布与调度

Tool	Purpose	Notes
`desktop_session_check`	Check selected local account health through desktop runtime（媒体账号与 AI 账号通用）	同步。返回 §14 的标准状态；客户端离线时只返回 last-known + stale 标记
`article_publish`	Create a publish batch to 1..N target accounts across 1..N platforms, per-target article version binding	异步：创建 batch 返回 batch ID。Requires confirmation token unless auto-publish is authorized; maps to existing PublishBatch。多平台变体时逐目标绑定版本与哈希（见 §10/§11）；version+target dedup 天然幂等
`site_publish`	Publish an article to an enterprise site (WordPress / PBootCMS) with category mapping	异步。Server-side adapter; no desktop dependency。必须携带 `idempotency_key`：CMS API 非幂等，超时重试会产生第二篇文章
`schedule_publish`	Create a one-shot scheduled publish of an existing article version to desktop/site targets at a future time	同步创建。桌面目标复用发布任务 `scheduled_at` 延迟派发（既有链路）；企业站点一次性定时为 P0 新增的服务端延迟执行链路（见 §13/§18）。接受 `idempotency_key`
`schedule_plan_create`	Create a recurring generation + publish plan (daily / weekly) bound to brand and prompt rules	同步创建。映射既有 ScheduleTask（定时生成 + 可选自动发布）；与一次性定时是两条不同链路，语义不可混用
`schedule_cancel`	Cancel a pending one-shot scheduled publish or a recurring plan	同步。落实 `schedule:write` scope 承诺的 cancel 能力
`publish_status`	Read publish batch / per-target record / schedule / site publish status; supports query by batch ID, article ID or time window	同步读。发布域跟进入口；生成/编排/采集 run 的轮询走 `run_status`
`publish_retry`	Retry failed targets of a batch through the existing retry flow	同步受理。Only for failed targets; never retries `unknown` submissions

监测

Tool	Purpose	Notes
`monitoring_overview`	Read composite dashboard: mention rate, mention position, first-recommended, coverage, by AI platform and time range	Wraps existing dashboard composite API
`monitoring_question_detail`	Read per-question monitoring detail including answers and matched brand terms
`monitoring_citations`	Read citation facts and correlate cited URLs with own publish records
`monitoring_collect_now`	Trigger an immediate collection run for brand questions on selected AI platforms	异步：创建标准 `monitor` 桌面任务（`high` 调度通道），返回 collect run ID 经 `run_status` 轮询；respects account rate budget（仲裁规则见 §16）

合规与编排

Tool	Purpose	Notes
`compliance_precheck`	Run compliance check on a draft before publish	同步（LLM 判定超出同步预算时转异步返回 run ID）。复用现有 compliance check
`compliance_ack`	Acknowledge a `needs_ack` compliance result, bound to article version + content hash + policy fingerprint	同步。必须由用户显式确认后调用（信任边界见 §17）
`agent_publish_campaign`	High-level orchestration tool for one natural-language request	异步：创建 agent run 返回 run ID。Calls planning, generation, rewrite, session check, publish/schedule internally
`run_status`	Poll any agent run or async operation: campaign run, generation run, collect-now run	同步读。统一长任务轮询入口，返回 §7 状态 + 时间线摘要 + 挂起时的待决策项；发布批次细节仍走 `publish_status`
`agent_run_continue`	Resume a run suspended in `needs_user_choice` / `awaiting_publish_confirmation` with the user's decisions	同步受理。携带 run ID + decisions[]（品牌 / 平台账号集 / 标题 / 图片 / 发布时间 / confirmation token / 合规 ack 等）；elicitation 与结构化输出两条路径的用户决策统一汇入此入口。权限沿用被恢复 run 所需 scopes

P1 tools:

Tool	Purpose
`desktop_data_collect`	Create and dispatch deep data collection tasks（content list 对账、平台指标、账号资料刷新）using local session
`knowledge_item_add`	Add text / URL knowledge items into a group
`image_import`	Import an image asset by URL
`agent_run_cancel`	Cancel a waiting or queued agent run
`local_bridge_pair`	Pair a local desktop MCP bridge with the SaaS workspace

7. Orchestration State Machine

Every high-level agent workflow creates an agent run with the following states:

State	Meaning
`received`	MCP request accepted and authenticated
`context_loaded`	Workspace, brand, knowledge, image and account context loaded
`needs_user_choice`	Agent needs brand, platform/account set, angle, title, image, schedule or publish mode selection
`generating`	Article generation or platform-variant rewrite in progress
`draft_ready`	Article saved and preview available
`session_checking`	Desktop account session checks in progress (per target account)
`awaiting_publish_confirmation`	Irreversible publish requires approval
`publishing_queued`	Publish batch / schedule / site publish created
`publishing`	Desktop client leased and executing, or CMS adapter submitting
`collecting`	Monitoring collection or post-publish collection in progress
`succeeded`	Workflow completed; all targets succeeded
`partially_succeeded`	Batch finished with some targets failed（对齐 PublishBatch 实际枚举 `partial_success`）
`failed`	Workflow failed with normalized error
`canceled`	User or agent canceled before completion

The run timeline must record tool name, input summary, output summary, error code, article ID, publish batch ID, schedule ID, desktop client ID, target platform keys and target account IDs where applicable. Input/output summary 遵守 §21 审计脱敏规范。

挂起与恢复：

needs_user_choice 与 awaiting_publish_confirmation 是挂起态：run 与已产出资产（草稿、版本、候选项、confirmation 请求）在服务端持久化，通过 agent_run_continue 携带用户决策恢复执行。没有恢复入口的状态机是空转的，此工具为 P0 必备。
挂起有 TTL（默认 24 小时，工作区可配）；过期转 canceled，释放预留配额，已产出草稿保留。过期后调用 continue 返回 agent_run_expired。
客户端支持 MCP elicitation 时，同一决策集可在工具调用期间即时收集（超时回退为挂起，见 §2）；两条路径的 decisions schema 完全一致。

8. Guided Mode

Guided mode is required when:

The user request does not specify a brand and no workspace default brand exists.
Multiple brands match the request with similar confidence.
目标平台未指定且无默认发布组合；或指定平台下存在多个账号且无默认账号。
用户要求的平台没有健康账号，但存在可替代平台账号时（给出替代选项）。
No suitable image is found and any target platform requires a cover.
Compliance check returns needs_ack.
Workspace policy requires approval for agent publishing.
The agent confidence is below the configured threshold.

Guided responses should be concise and machine-readable. Typical decisions:

Brand selection.
Target platform and account set selection（多选）.
Article angle selection.
Title selection.
Knowledge group selection.
Cover image selection.
Publish timing: draft / immediate / scheduled time.
Confirm final content and full target list before publish.

9. Automatic Mode

Automatic mode may proceed without additional user choices only when all conditions are true:

Request contains explicit intent, such as "直接发" or the agent run is started under an auto-publish workflow.
Agent token has article:publish:auto.
Workspace policy allows trusted agent auto-publish.
Default brand and a default target account set are configured.
Knowledge retrieval succeeds or the workflow explicitly allows brand-profile-only generation.
Desktop client is online and every target account is active（企业站点目标要求站点连接状态正常）.
Compliance gate passes without acknowledgement.
Generated article satisfies minimum quality checks.
Quota check passes（AI 积分足够完成本次工作流）.

Even in automatic mode, the publish tool must be idempotent and tied to article ID, the full target set and per-target article version + content hash（多平台变体时逐目标绑定，见 §10）.

10. Confirmation Token

Publishing is irreversible. When confirmation is required, article_generate or agent_publish_campaign returns a confirmation request with:

article ID
逐目标条目（per-target entries）：每项绑定 (platform_key, account_id 或 site_id+category, article_version_id, content_hash, publish_type, scheduled_at?)——多平台变体（§11）下不同目标对应不同文章版本与内容哈希，token 必须逐目标锁定各自版本；单一 version + hash 无法覆盖变体场景
全量目标集摘要哈希（防止确认后增删目标）
preview summary（按目标或共享）
expiration time

article_publish / site_publish / schedule_publish must reject confirmation tokens that are expired, consumed, bound to a different target set or bound to a different publish type；任一目标条目的 article version 或 content hash 与实际待发内容不符时整体拒绝（publish_confirmation_invalid；确认后草稿被编辑的场景返回 article_version_stale，引导重新确认）。部分成功后的重试不得复用原 token 之外新增目标。

11. Knowledge and Content Generation

The MCP generation path must reuse the existing article generation and knowledge services instead of introducing a separate agent-only generator.

Decisions:

article_generate 收敛到现有三类生成入口：提示词规则生成、模板生成、仿写生成；由编排器根据用户意图选择入口，不新建第四条生成管线。
生成所用 LLM 模型由服务端生成栈配置决定（与现状一致），MCP 不暴露模型选择；用量日志记录实际模型。客户端绑定的 AI 平台账号仅用于监测采集，与服务端生成模型解耦。
Knowledge retrieval uses current tenant and selected knowledge groups.
Generated articles are saved as normal SaaS articles and versions.
Knowledge snippets and high precision facts are attached to the generation record for traceability.
The generation prompt must separate user brief, brand profile, knowledge snippets and platform requirements.
The agent may generate an article plan before full generation（复用模板 title/outline 任务）。
Soft article defaults include title, summary, section headings, body, CTA and optional image placement suggestions.
The final draft must be valid rich-text or Markdown convertible to each target platform's article format（HTML 转换由各桌面适配器完成，与现状一致）。
多平台分发时，平台变体通过 article_rewrite 产生新文章版本，发布时逐目标绑定对应版本。
生成、改写、合规 LLM 判定全部走现有 quota reservation + AI point usage 流程，失败退款逻辑不变。
campaign 等多步工作流按整体预估一次性预留配额（生成 + 平台变体改写 + 合规 LLM 判定）；若预估偏差导致中途耗尽，保留已产出草稿与版本，run 以 quota_exhausted 失败，配额补充后可基于已有资产续接，不重复扣费、不静默丢弃。

12. Image Handling

P0 supports selection from existing SaaS image assets:

cover image
inline article images
images referenced by existing article drafts
images linked from knowledge items where available and authorized

The agent should rank images by brand, campaign, recency, title, tags and semantic match to the brief. 选图必须结合平台能力目录校验：封面是否必需、尺寸/数量约束。If no image is available, the tool returns image_missing with choices:

continue without image for target platforms that allow text-only
drop the platforms that require a cover from the target set (with user confirmation)
ask user to upload image
save draft only
generate image in P1 if enabled

P1 can add AI image generation, image import and image editing, but that is outside P0.

13. Publish Path

发布按目标渠道分两条既有链路，MCP 不新建发布通道：

桌面平台（13 个平台 key）

MCP Gateway resolves target article version and target account set.
Gateway checks per-account health and desktop availability.
Gateway runs compliance gate through the same publish path used by Web.
Gateway creates a publish batch and per-target desktop publish tasks（复用 PublishBatch + desktop task 模型）.
Desktop client leases tasks（lease + lease_token + extend，与现状一致）.
Desktop client reuses the local platform session partition per account.
Desktop platform adapter checks login state just-in-time.
Desktop platform adapter uploads images per platform requirements.
Desktop platform adapter submits article as draft or publish（平台支持度由能力目录声明）.
Desktop client reports progress and final result per task（succeeded / failed / unknown）.
SaaS syncs publish records and batch status（含 partial_success）.
MCP tool returns per-target results or a pollable batch ID.

企业站点（wordpress / pbootcms）

Gateway validates site connection (ping) and category mapping.
Gateway runs the same compliance gate.
Server-side CMS adapter publishes via site API with stored encrypted credentials.
Result returns article ID and edit URL; failures normalized to site_publish_failed.

约束：

The SaaS service must not call media platform APIs directly with server-side cookies（企业站点 CMS API 除外，凭证走既有密文存储）。
MCP Gateway 不得包含任何平台专用逻辑；平台差异 100% 留在桌面适配器、CMS 适配器与平台目录。
定时发布是两条链路，语义不可混用：一次性定时发布（已有文章版本 + 目标集 + 未来时间）——桌面目标复用发布任务 scheduled_at 延迟派发（既有能力）；企业站点一次性定时为 P0 新增的服务端延迟执行。循环定时生成计划（daily / weekly）——映射既有 ScheduleTask（定时生成 + 可选自动发布，绑定提示词规则）。到点后均进入与上面相同的发布链路。
创建型发布入口（publish batch / site publish / schedule）支持 idempotency_key 去重；站点发布强制携带（CMS API 非幂等，重复提交产生重复文章）。

14. Local Session Check and Reuse

会话状态对齐桌面端真实健康模型（authState），不另造枚举：

State	Meaning	Agent behavior
`active`	Local session verified usable	Continue publish or collection
`expiring_soon`	Session likely to expire soon	Continue but surface a renewal hint
`challenge_required`	Platform requires human verification（验证码 / 风控拦截，`reason` 区分 `captcha_gate` / `risk_control`）	Ask user to complete verification in desktop client; stop automation on `risk_control`
`expired`	Login expired or account not detected	Ask user to re-login in desktop client
`revoked`	Account unbound or revoked	Remove from target set; suggest rebinding
`unknown`	Health cannot be determined	Offer retry or manual inspection

正交维度：desktop_online（客户端在线状态）。判定纪律：

客户端离线时禁止下任何会话结论，session check 返回 last-known state + stale: true + verified_at 时间戳，并引导用户启动客户端。
challenge_required 仅以厂商验证组件、弹层、拦截页三类证据判定（与桌面端现行判定纪律一致），避免瞬态加载误报。
For publish and data collection, the desktop runtime must always perform a just-in-time session check before executing platform actions（现状已如此）。
同一工具同时服务媒体账号与 AI 账号的健康检查。

15. Desktop Local MCP Bridge

P1 adds a local bridge for agents running on the same machine as the desktop client.

Local bridge decisions:

Bind to loopback only.
Disabled by default.
Requires explicit pairing from desktop UI or SaaS.
Pairing token is short-lived.
Exposes only local-safe tools unless SaaS authorization is present.
Never exposes raw cookies or vault contents.
Every local tool run syncs an audit event to SaaS when the client is online.
If SaaS is offline, local bridge may queue audit events but must show local visibility to the user.

Initial local bridge tools:

Tool	Purpose
`local_session_check`	Check local account health（媒体与 AI 账号）
`local_publish_article`	Execute a SaaS-authorized publish task or local approved draft
`local_collect_data`	Collect platform-side data using local session
`local_open_account_console`	Open the platform console for human login or verification

本地桥工具以 local_ 前缀命名，与 SaaS 网关工具区分，避免宿主同时连接两个 MCP server 时产生工具名歧义。

16. Monitoring and Data Collection

AI 品牌监测（P0，读 + collect-now）

监测复用既有体系：monitor 类型桌面任务、6 个 AI 平台适配器、high / normal 双调度通道（重试任务走独立 retry 通道，无 low 通道）、监测结果与引用源数据模型。MCP 暴露：

读看板：composite dashboard、question detail、citation summary（纯读，零新增采集链路）。
collect-now：等价于现有"立即采集"入口，创建 high 通道的 monitor 任务，由客户端绑定 AI 账号执行，返回 collect run ID 供 run_status 轮询。速率预算仲裁：与保活探测、常规监测共享账号级 token bucket，其中保活探测享有保底预算、不可被 collect-now 挤占（保活是账号健康的生命线）；collect-now 另设独立上限（每账号每小时 + 每工作区每日双阈值，运营可配），超限返回 rate_limited 并附下次可用时间。MCP 不得绕过。
采集结果字段沿用现有 payload：answer、citations、search_results、brand_mentioned、brand_mention_position、first_recommended、sentiment_label、matched_brand_terms。
AI 账号不可用（expired / challenge_required / 客户端离线）时返回对应标准错误，引导用户修复，不静默跳过。

深度数据采集（P1）

P1 collection targets（新增任务种类，复用 lease/恢复模型）：

Collection type	Description
`publish_status`	Check whether a submitted article is draft, published, pending review or failed
`article_metrics`	Collect reads, comments, likes, shares if the platform exposes them
`content_list`	Reconcile recent platform backend content with SaaS publish records
`account_profile`	Refresh nickname, avatar, account ID and account status
`diagnostic_snapshot`	Capture non-sensitive debugging signals for failed tasks

Collection tasks should use the same desktop task lease and recovery model as publish tasks. If the local client crashes mid-collection, the task can be retried because collection is read-only. If a publish task crashes after submit begins, it must remain unknown until reconciled to avoid duplicate posts.

17. Compliance, Risk and Safety

Agent publishing must follow existing compliance policy:

MCP generation does not bypass article compliance checks.
MCP publish (desktop platforms, sites, schedules) does not bypass publish gate checks.
Compliance block stops publish.
Compliance needs_ack requires an acknowledgement flow（compliance_ack，需用户显式确认）.
The acknowledgement must bind to article version, content hash and policy fingerprint.
MCP runs must store actor information and agent client information.

Additional safety rules:

Do not publish if generated content is empty or below minimum length.
Do not publish if required brand facts are missing.
Do not publish to any target whose account is not active at publish time.
Do not retry non-idempotent publish after the irreversible submit phase without manual reconciliation（unknown 状态目标禁止自动重试）.
Do not expose hidden system prompts, credentials, cookies, CMS credentials or platform request headers to the agent.
collect-now 频率受账号级与 agent 级双重限流，防止智能体高频采集触发平台风控。

信任边界与数据外发：

Agent 代述确认是显式接受的残余风险：confirmation token 与 compliance ack 的"用户已确认"由 agent 转述，平台无法直接验证终端用户的真实操作；一个失控的持权 agent 可以自问自答。租户为 agent 授予 article:publish 即表示信任其如实转述用户决策；此项写入威胁模型，以 scope 最小化、完整审计时间线与即时吊销兜底。
工作区策略可选带外强确认（默认关闭）：开启后正式发布（非草稿）须经 Web 后台或桌面客户端的推送确认，confirmation token 仅在带外确认完成后生效；草稿与定时草稿豁免。供高敏租户选择。
数据外发披露：Agent 授权页必须按 scope 展示该 agent 可读取的数据类别（知识库片段、品牌资料、监测数据、账号与站点元数据），并明示知识库内容将流向 agent 厂商服务器；geo://images 预览 URL 为短时效签名 URL。

18. Data Model Additions

Reuse existing domain tables for articles, article versions, knowledge, platform accounts, desktop clients, desktop tasks, publish batches, publish records, schedules, enterprise site connections, monitoring tasks/runs and citation facts.

Add MCP-specific records:

Model	Purpose
Agent integration	Stores connected agent client, scopes, status and revocation metadata
Agent token	Stores token hash, expiry and binding
Agent run	Stores one high-level orchestration workflow
Agent tool call	Stores individual MCP tool calls, status, input summary and output summary
Agent confirmation	Stores publish confirmation tokens bound to per-target (platform, account/site, article version, content hash) tuples and the full target set
Agent run event	Stores timeline events for streaming and support diagnosis
Agent idempotency record	Stores idempotency keys of create-type tool calls with the created resource ID, for replay-safe retries

平台目录补充（非新表，扩展 media_platforms 元数据）：为每个平台登记 MCP 所需能力字段——是否支持草稿、封面是否必需、图片数量约束、是否支持定时、发布通道（desktop/server）、绑定方式（cookie/oauth/api）、适配器就绪度。注意：现有 media_platforms 仅有展示元数据，能力字段为实打实的新增工作（13 平台 + 2 CMS 的数据梳理量需计入排期）。

企业站点一次性定时发布：扩展站点发布记录，增加 scheduled_at 与待执行状态，由服务端延迟执行（P0 新增能力，见 §13；桌面侧无需新增，复用发布任务 scheduled_at）。

No MCP table should store local platform cookies, desktop vault contents or CMS credentials.

19. API and Service Boundaries

Service boundaries:

Boundary	Responsibility
MCP Gateway (`cmd/mcp-gateway`)	MCP protocol, tool/resource/prompt discovery, schema validation, agent auth, rate limiting
Agent Orchestrator	High-level workflow state machine and guided/automatic mode decisions
Workspace Context Service	Brand, knowledge, image, media/AI account, site and desktop context aggregation
Article Generation Service	Generate and persist drafts using existing generation stack (prompt rule / template / imitation)
Knowledge Service	Resolve RAG context and render traceable knowledge snippets
Publish Job Service	Compliance, dedup, publish batch creation, task dispatch, retry
Schedule Service	一次性定时发布（桌面复用发布任务 `scheduled_at`；企业站点为新增服务端延迟执行）与循环定时生成计划（复用既有 ScheduleTask 调度器）
Enterprise Site Publisher	CMS adapter publish (WordPress / PBootCMS)
Monitoring Service	Dashboard reads, collect-now task creation, citation correlation
Desktop Runtime	Local session check, task lease, adapter execution, progress and result callback
Data Collection Service	Create collection tasks, normalize collected platform data（P1 扩展）
Audit Service	Store MCP runs, tool calls and sensitive-action logs

MCP Gateway must not contain platform-specific logic for any platform. Platform specifics remain in desktop adapters, CMS adapters and the platform catalog.

20. Error Model

MCP tool errors should be normalized for agents（平台无关；platform 作为字段而非错误码前缀）：

Error code	Meaning
`agent_unauthorized`	Agent token missing, revoked or out of scope
`rate_limited`	Agent or account rate budget exceeded
`quota_exhausted`	AI points or generation quota insufficient
`workspace_context_missing`	No tenant or workspace context
`brand_not_found`	Requested brand is not available
`article_not_found`	Article or article version not found in this workspace
`article_version_stale`	Article was edited after confirmation; content hash no longer matches the confirmed version
`platform_not_supported`	Platform key not enabled in catalog or no adapter readiness
`platform_capability_unsupported`	Requested capability (e.g. draft, schedule, text-only) not supported by target platform
`account_not_found`	Target account not bound in this workspace
`knowledge_unavailable`	Knowledge service or retrieval provider unavailable
`knowledge_insufficient`	Not enough knowledge for requested article
`image_missing`	No suitable image found
`article_generation_failed`	Generation failed
`publish_confirmation_required`	Publish requires human confirmation
`publish_confirmation_invalid`	Confirmation token expired or mismatched
`desktop_client_offline`	Owning desktop client is unavailable
`desktop_account_expired`	Local platform session expired
`desktop_account_challenge_required`	Captcha or risk verification required（`reason`: `captcha_gate` / `risk_control`）
`desktop_account_revoked`	Account unbound or revoked
`publish_compliance_blocked`	Compliance blocked publication
`publish_compliance_needs_ack`	Compliance requires acknowledgement
`publish_duplicate`	Same article version already submitted to same target account
`platform_publish_failed`	Desktop adapter submission failed（携带 platform key 与平台原始原因）
`publish_result_unknown`	Submission started but final state unknown; manual reconciliation required
`site_not_found`	Enterprise site connection not found in this workspace
`site_unreachable`	Enterprise site ping failed
`site_publish_failed`	CMS adapter submission failed
`schedule_invalid`	Scheduled time invalid or scheduler rejected
`agent_run_not_found`	Agent run not found or not visible to this agent
`agent_run_expired`	Suspended run expired (TTL) before user decisions arrived
`idempotency_conflict`	Same idempotency key reused with a different request payload
`monitoring_no_account`	No healthy AI account for requested platform
`monitoring_collect_failed`	Collection run failed
`data_collection_failed`	Deep data collection failed（P1）

Every error should include:

human-readable message（中文文案，面向最终用户可直接展示；程序分支只依赖 code，不解析 message）
retryable boolean
suggested next action
related resource IDs and platform key where safe

21. Observability

Required logs and metrics:

MCP connection count by agent.
Tool call count, latency and error rate, by tool and by agent.
Article generation success rate.
Knowledge retrieval success and empty-result rate.
Session check states by platform（媒体与 AI 平台分开）.
Publish batch queue latency and per-platform publish success/failure/challenge rates（13 平台 + 站点分列）.
Desktop task lease latency.
Schedule dispatch punctuality.
Site publish success rate by CMS type.
Monitoring collect-now volume, success rate and lane saturation.
Confirmation required and confirmation accepted rates.
Auto-publish usage by workspace and agent.
AI point consumption by agent and usage type.
Data collection success and stale rate（P1）.
Gateway 非功能观测：并发 MCP 会话数、工具调用 P95/P99 延迟、elicitation 使用率与回退率、挂起 run 恢复率与过期率、幂等重放命中数。

Support must be able to inspect a single agent run timeline without reading raw private article content unless the support role is authorized.

审计脱敏规范：agent tool call 的 input/output summary 不得包含知识库片段原文或文章正文全文，仅记录资源 ID、内容哈希、长度与白名单字段（标题、平台 key、账号 ID、错误码）；正文可读性由支持角色授权单独控制（上一条）。

22. Product Metrics

P0 success metrics:

Agent article generation success rate >= 90%.
Live-session publish batch creation success rate >= 95%.
Desktop publish execution success rate >= 85%（按平台分列观测，任一平台连续低于 70% 触发该平台降级评审）.
Enterprise site publish success rate >= 95%.
Duplicate publish incident count = 0.
Median time from user request to draft ready <= 90 seconds.
Median time from publish confirmation to desktop task queued <= 5 seconds.
Monitoring collect-now median completion <= 5 minutes when client online.
MCP tool calls with complete audit trail = 100%.
Cloud-stored platform cookie count = 0（媒体平台与 AI 平台均为 0）.

P0 adoption metrics（采用度，回答"有没有人用"）:

接入至少 1 个 agent 并完成首次 MCP 发布的工作区数（周观测）。
周活跃 agent run 数；MCP 渠道发布量占总发布量比例。
needs_user_choice 平均决策轮数 <= 2（引导效率）；挂起 run 恢复率 >= 70%。

Gateway non-functional targets:

Gateway 可用性 >= 99.9%（月度）。
工具调用 P95 延迟 <= 800ms（不含异步任务执行时间）。

P1 success metrics:

Local bridge paired successfully on first attempt >= 90%.
Deep data collection task success rate >= 85%.
Session check false-active rate <= 3%.

Testing Decisions

Testing should focus on external behavior and workflow boundaries rather than internal implementation details.

1. Confirmed Test Seams

Use the following highest-level seams:

Seam	What to verify
MCP Gateway contract	Tool/resource/prompt discovery, schema validation, auth scope enforcement, structured errors
Agent Orchestrator	Guided vs automatic decisions, confirmation state, multi-target fanout, run timeline
Workspace Context aggregation	Correct brand, knowledge, image, media/AI account, site and desktop status under tenant/workspace isolation
Platform capability catalog	Capability flags gate tool behavior (draft, cover, schedule, text-only) per platform
Article generation boundary	Given a brief and knowledge groups, creates a normal article draft with traceable knowledge metadata via existing entries
Publish job boundary	Compliance gate, account health check, dedup, batch creation, partial failure, retry, event dispatch
Schedule boundary	Scheduled publish creation, dispatch at time, cancellation
Enterprise site boundary	Site ping, category mapping, publish, credential redaction
Desktop runtime boundary	Session check, task lease, progress reporting, success/failure/unknown callback
Platform adapter conformance	同一套契约测试参数化跑全部 13 个适配器：login detection, image upload, submit, error normalization, progress stages
Monitoring boundary	Dashboard reads, collect-now task creation on the `high` dispatch lane, AI account health gating, citation correlation
Audit boundary	Every MCP run and tool call produces a traceable audit event

2. MCP Contract Tests

Add contract tests with a fake MCP client:

Lists expected tools, resources and prompts.
Rejects unknown tools.
Rejects invalid input schema.
Rejects insufficient scopes（含新增 monitoring/schedule/site scopes）.
Redacts secrets in tool output（cookies、CMS 凭证、内部 token）.
Returns confirmation-required responses for publish when policy requires.
Returns pollable IDs for long-running operations.
Returns quota_exhausted / rate_limited 标准错误。
Same idempotency_key replay returns the original resource without duplicate creation; same key with a different payload returns idempotency_conflict.
Elicitation-capable 与不支持 elicitation 的客户端获得语义等价的决策流（同一 decisions schema；elicitation 超时回退为挂起 run，经 agent_run_continue 恢复）。
工具名与提示词名全部符合 [a-z0-9_] 命名约束（宿主兼容性检查）。

3. Orchestration Tests

Use service-level tests with fake dependencies:

"帮我给搜狐号发企业软文" with one brand, one active account and auto-publish disabled returns a draft and confirmation request.
"发到搜狐号和百家号" creates one batch with two targets; one target failing yields partially_succeeded and retry guidance.
Same request with auto-publish enabled creates a publish batch.
Multiple matching brands returns needs_user_choice.
指定平台无健康账号时返回替代平台选项而不是直接失败。
Multiple accounts on one platform returns account choices.
No image: target platform requires cover → returns image_missing choices; target platform allows text-only → can continue.
Expired account stops that target before batch creation; other targets proceed with user confirmation.
Offline desktop client stops desktop targets; enterprise site targets still proceed.
"明早 9 点发" creates a one-shot scheduled publish instead of an immediate batch（桌面目标绑定 scheduled_at；企业站点目标走服务端延迟执行）。
"每周一早上自动写一篇发布" creates a recurring ScheduleTask plan（daily/weekly）；一次性定时与循环生成计划不得混淆。
Compliance block stops publish; needs_ack returns acknowledgement requirement; ack 后可继续。
Quota exhausted before generation returns quota_exhausted without creating generation task.
Campaign 中途配额耗尽：保留已产出草稿与版本，run 以 quota_exhausted 结束；补充配额后可基于已有资产续接且不重复扣费。
needs_user_choice 挂起后经 agent_run_continue 携带 decisions 恢复执行；挂起过期转 canceled 并释放预留配额，此后 continue 返回 agent_run_expired。
Monitoring: "豆包上我们品牌表现如何" reads dashboard without creating tasks; "现在采集一次" creates high-lane monitor tasks only for healthy AI accounts.

4. Article Generation Tests

Use existing generation seams:

Knowledge group IDs are passed through.
High precision facts are preserved in the prompt context.
Generated draft stores article, article version and generation metadata.
Prompt injection inside knowledge snippets does not override system instructions.
Empty or too-short generated content is rejected before publish.
Platform-variant rewrite creates a new version bound to the right target.
Quota reservation/refund flows are triggered exactly as web-generated articles.

5. Publish Job Tests

Cover:

Target accounts must belong to the same workspace.
Target desktop client must be available for desktop targets.
Non-active account cannot be included as a publish target.
Dedup prevents same article version + target account duplicate publish.
Existing batch is returned instead of creating a duplicate.
Publish record syncs from desktop task completion; batch reflects partial_success.
Unknown publish state is retained after possible submit-start failure; publish_retry refuses unknown targets.
Confirmation token bound to target set rejects any target-set mutation.
逐目标版本绑定：token 内任一目标的 article version 或 content hash 与实际待发内容不符时整体拒绝；确认后草稿被编辑的场景返回 article_version_stale。
Site publish idempotency：same idempotency_key 重放不产生第二篇 CMS 文章。

6. Desktop and Adapter Tests

Cover with mocked session HTTP, parameterized across all 13 platform adapters:

Account info detection succeeds.
Missing account info returns expired session.
Image upload failures are reported clearly.
Article submit success returns external article ID and management URL.
Captcha/risk responses become challenge_required with correct reason.
Publish type draft and publish follow the platform capability matrix.
Adapter progress stages are emitted in order.

Manual smoke tests with real test accounts remain required before release for each platform enabled in the catalog, because platform behavior can change.

7. Monitoring and Collection Tests

Dashboard reads respect tenant/workspace isolation and time-range filters.
collect-now creates monitor tasks only for selected platforms with healthy accounts; unhealthy ones return monitoring_no_account.
collect-now respects account-level rate budget; exceeding returns rate_limited；且不得挤占保活探测的保底预算（预算仲裁规则见 §16）。
Collection results flow into existing monitoring projections; citation facts correlate publish records.
客户端离线时 collect-now 返回 desktop_client_offline 并保留任务可选项（排队 vs 取消）。
P1: deep collection task is read-only and retryable; expired session returns session error, not collection success; local bridge collection creates SaaS audit events.

8. Security Tests