geo/docs/mcp-agent-publishing-prd-v1.md

# GEO SaaS MCP Agent Publishing PRD V1

## 1. 文档信息

| 项目 | 内容 |
| --- | --- |
| 文档名称 | GEO SaaS MCP Agent Publishing PRD V1 |
| 文档版本 | V1.1 |
| 文档状态 | 待评审 |
| 创建日期 | 2026-06-09 |
| 最近修订 | 2026-06-10 |
| 适用阶段 | 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 专用命名 | 全部平台参数化命名 |

### 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 |
| 定时发布 | schedules + 调度器 | 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 工具完成：

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

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

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

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

## User Stories

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

1. 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.
2. 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.
3. 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.
4. As a brand operator, I want the agent to ask follow-up questions only when needed, so that simple tasks remain fast.
5. As a brand operator, I want the agent to offer several article angles, so that I can choose the most suitable soft article direction.
6. 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.
7. As a brand operator, I want the agent to use enterprise knowledge, so that the article reflects accurate company information.
8. As a brand operator, I want the agent to cite which knowledge groups were used internally, so that I can trust the generated article.
9. As a brand operator, I want the agent to avoid inventing company facts, so that brand risk is reduced.
10. 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.
11. 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.
12. 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.
13. 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.
14. 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.
15. As a brand operator, I want the agent to support draft-only generation, so that I can review before publishing.
16. As a brand operator, I want the agent to support direct publish when I explicitly say so, so that routine tasks can be automated.
17. As a brand operator, I want a publish preview listing every target account and platform before irreversible publication, so that accidental publishing is avoided.
18. 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.
19. 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.
20. 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.

### 账号与会话（品牌运营）

1. 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.
2. 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.
3. 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.
4. 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.
5. As a brand operator, I want expired-session recovery instructions to be specific per platform, so that I can fix the issue quickly.
6. 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.

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

1. 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.
2. 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.
3. 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.
4. 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.
5. As a brand operator, I want publish failures to include platform-specific reasons, so that I can decide whether to retry or manually intervene.
6. 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.
7. 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.
8. As a content editor, I want to regenerate the article from the same brief, so that I can compare versions.
9. 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.
10. As a content editor, I want to ask the agent for title options only, so that I can choose the direction before generating.
11. 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.
12. As a content editor, I want to ask the agent to avoid specific topics, so that the article respects campaign constraints.
13. As a content editor, I want the agent to reuse current article drafts, so that I can publish edited content rather than generating again.
14. 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 可见度监测（品牌运营 / 内容编辑）

1. 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.
2. 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.
3. 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.
4. 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.
5. 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.
6. 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.
7. As a content editor, I want to correlate published articles with citation facts, so that I can report content ROI.

### 租户管理（tenant admin）

1. As a tenant admin, I want to decide which agents can connect to my workspace, so that external automation is controlled.
2. 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.
3. As a tenant admin, I want to disable auto-publish for all agents, so that publication always requires human confirmation.
4. 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.
5. As a tenant admin, I want sensitive platform sessions to remain local, so that SaaS security posture remains unchanged.
6. As a tenant admin, I want to revoke an agent token, so that compromised integrations stop working immediately.
7. As a tenant admin, I want per-agent rate limits, so that runaway agents cannot burn quota or spam media platforms.
8. As a tenant admin, I want MCP access to follow tenant and workspace isolation, so that agents cannot read another workspace.
9. As a tenant admin, I want to see AI point consumption per agent, so that automation cost is attributable.

### 平台运营（platform operator）

1. As a platform operator, I want to see MCP tool run health, so that support can diagnose integration failures.
2. As a platform operator, I want failed MCP tool calls to include normalized error codes, so that support can route issues correctly.
3. 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.
4. As a platform operator, I want agent-generated articles to pass compliance checks before publishing, so that policy enforcement is unchanged.
5. 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.
6. As a platform operator, I want publish status to reconcile into existing publish records, so that dashboards do not fork.
7. As a platform operator, I want local data collection to use desktop task leases, so that collection jobs can recover from client crashes.
8. As a platform operator, I want uncertain publish submissions to remain manually reconcilable, so that retry does not duplicate non-idempotent posts.
9. 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）

1. As an external agent, I want to discover available tools, resources and prompts, so that I can know what actions the workspace supports.
2. 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.
3. As an external agent, I want structured tool outputs, so that I can explain next steps to the user.
4. 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.
5. 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.
6. 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.
7. 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.
8. 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.
9. 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.

### 桌面客户端用户

1. 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.
2. 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.
3. 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.
4. As a desktop client user, I want to pause local agent execution, so that I can stop automation during sensitive work.
5. 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.
6. As a desktop client user, I want local bridge actions to sync back to SaaS audit records, so that direct local operations remain traceable.
7. As a desktop client user, I want local collection jobs to reuse the same platform login state, so that repeated login is unnecessary.

### 合规与支持

1. 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.
2. 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.
3. 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:

```text
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；长任务（生成、发布、采集）一律返回可轮询的 run/task ID，不依赖长连接存活。
- 用户选择决策优先使用 MCP elicitation 能力（客户端支持时），否则回退为本文档定义的机器可读 `needs_user_choice` 结构化输出。两条路径必须语义等价。

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。

### 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.

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

P0 tools（按能力域分组）：

#### 上下文与资产

| Tool | Purpose | Notes |
| --- | --- | --- |
| `geo.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 |
| `geo.knowledge_search` | Search selected knowledge groups using a user brief or generated query | Wraps existing knowledge RAG, returns structured snippets with precise facts |
| `geo.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 |
| --- | --- | --- |
| `geo.article_plan` | Produce title, angle and outline options without generating full article | 复用模板 title/outline 任务链路 |
| `geo.article_generate` | Generate and save an article draft using brand, knowledge, image and user constraints | 收敛到现有生成入口（prompt rule / template / imitation），返回 article ID、version ID、预览与缺失决策 |
| `geo.article_rewrite` | Rewrite a saved draft for a target platform or target reader | 多平台分发的平台变体生成；P0 |

#### 发布与调度

| Tool | Purpose | Notes |
| --- | --- | --- |
| `geo.desktop_session_check` | Check selected local account health through desktop runtime（媒体账号与 AI 账号通用） | 返回 §14 的标准状态；客户端离线时只返回 last-known + stale 标记 |
| `geo.article_publish` | Create a publish batch for one article version to 1..N target accounts across 1..N platforms | Requires confirmation token unless auto-publish is authorized; maps to existing PublishBatch |
| `geo.site_publish` | Publish an article to an enterprise site (WordPress / PBootCMS) with category mapping | Server-side adapter; no desktop dependency |
| `geo.schedule_publish` | Create a scheduled publish (desktop platforms or sites) | Reuses existing schedules + dispatch worker |
| `geo.publish_status` | Read publish batch / per-target record / schedule / site publish status | Used for long-running follow-up |
| `geo.publish_retry` | Retry failed targets of a batch through the existing retry flow | Only for failed targets; never retries `unknown` submissions |

#### 监测

| Tool | Purpose | Notes |
| --- | --- | --- |
| `geo.monitoring_overview` | Read composite dashboard: mention rate, mention position, first-recommended, coverage, by AI platform and time range | Wraps existing dashboard composite API |
| `geo.monitoring_question_detail` | Read per-question monitoring detail including answers and matched brand terms | |
| `geo.monitoring_citations` | Read citation facts and correlate cited URLs with own publish records | |
| `geo.monitoring_collect_now` | Trigger an immediate collection run for brand questions on selected AI platforms | Creates standard `monitor` desktop tasks on HIGH priority lane; respects account rate budget |

#### 合规与编排

| Tool | Purpose | Notes |
| --- | --- | --- |
| `geo.compliance_precheck` | Run compliance check on a draft before publish | 复用现有 compliance check |
| `geo.compliance_ack` | Acknowledge a `needs_ack` compliance result, bound to article version + content hash + policy fingerprint | 必须由用户显式确认后调用 |
| `geo.agent_publish_campaign` | High-level orchestration tool for one natural-language request | Calls planning, generation, rewrite, session check, publish/schedule internally |

P1 tools:

| Tool | Purpose |
| --- | --- |
| `geo.desktop_data_collect` | Create and dispatch deep data collection tasks（content list 对账、平台指标、账号资料刷新）using local session |
| `geo.knowledge_item_add` | Add text / URL knowledge items into a group |
| `geo.image_import` | Import an image asset by URL |
| `geo.agent_run_cancel` | Cancel a waiting or queued agent run |
| `geo.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_failed`） |
| `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.

### 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, article version ID, the full target set and content hash.

### 10. Confirmation Token

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

- article ID
- article version ID
- content hash
- target set: list of (platform key, account ID) and/or (site ID, category), and/or schedule time
- publish type (draft / publish / scheduled)
- preview summary
- expiration time

`geo.article_publish` / `geo.site_publish` / `geo.schedule_publish` must reject confirmation tokens that are expired, consumed, bound to different content, bound to a different target set or bound to a different publish type. 部分成功后的重试不得复用原 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:

- `geo.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 转换由各桌面适配器完成，与现状一致）。
- 多平台分发时，平台变体通过 `geo.article_rewrite` 产生新文章版本，发布时逐目标绑定对应版本。
- 生成、改写、合规 LLM 判定全部走现有 quota reservation + AI point usage 流程，失败退款逻辑不变。

### 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）

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

#### 企业站点（wordpress / pbootcms）

1. Gateway validates site connection (ping) and category mapping.
2. Gateway runs the same compliance gate.
3. Server-side CMS adapter publishes via site API with stored encrypted credentials.
4. 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 适配器与平台目录。
- 定时发布走既有 schedules + 调度器；到点后进入与上面相同的发布链路。

### 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 |
| --- | --- |
| `desktop.session_check` | Check local account health（媒体与 AI 账号） |
| `desktop.publish_article` | Execute a SaaS-authorized publish task or local approved draft |
| `desktop.collect_data` | Collect platform-side data using local session |
| `desktop.open_account_console` | Open the platform console for human login or verification |

### 16. Monitoring and Data Collection

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

监测复用既有体系：`monitor` 类型桌面任务、6 个 AI 平台适配器、HIGH/NORMAL/LOW 优先级通道、监测结果与引用源数据模型。MCP 暴露：

- 读看板：composite dashboard、question detail、citation summary（纯读，零新增采集链路）。
- collect-now：等价于现有"立即采集"入口，创建 HIGH lane 的 monitor 任务，由客户端绑定 AI 账号执行。必须遵守账号级速率预算（与保活、常规监测共享 token bucket），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（`geo.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 级双重限流，防止智能体高频采集触发平台风控。

### 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 article content and full target set |
| Agent run event | Stores timeline events for streaming and support diagnosis |

平台目录补充（非新表，扩展 `media_platforms` 元数据）：为每个平台登记 MCP 所需能力字段——是否支持草稿、封面是否必需、图片数量约束、是否支持定时、发布通道（desktop/server）、绑定方式（cookie/oauth/api）、适配器就绪度。

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 publish creation and dispatch（复用现有 scheduler） |
| 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 |
| `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_unreachable` | Enterprise site ping failed |
| `site_publish_failed` | CMS adapter submission failed |
| `schedule_invalid` | Scheduled time invalid or scheduler rejected |
| `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
- 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）.

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

### 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）.

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 HIGH 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` 标准错误。

### 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 schedule instead of immediate batch.
- Compliance `block` stops publish; `needs_ack` returns acknowledgement requirement; ack 后可继续。
- Quota exhausted before generation returns `quota_exhausted` without creating generation task.
- 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_failed`.
- Unknown publish state is retained after possible submit-start failure; `geo.publish_retry` refuses `unknown` targets.
- Confirmation token bound to target set rejects any target-set mutation.

### 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`.
- 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

Cover:

- Agent cannot read another workspace.
- Agent cannot publish without `article:publish`; cannot schedule without `schedule:write`; cannot collect without `monitoring:collect`.
- Agent cannot auto-publish without `article:publish:auto` and workspace policy.
- Resource responses do not include cookies, vault data, CMS credentials, passwords or internal tokens.
- Confirmation token cannot be replayed against modified content or modified target set.
- Revoked agent token stops all tool calls.
- Local bridge cannot bind to public network interfaces.
- collect-now cannot exceed account rate budget even with valid scopes.

## Out of Scope

The following are out of scope for P0:

- Server-side storage of any media or AI platform cookies, or direct cloud login to those platforms.
- Fully autonomous publishing without workspace policy and agent scopes.
- AI image generation or image editing.
- Deep BI dashboards beyond existing monitoring projections.
- Cross-tenant shared media account pool.
- KOL marketplace operations (subscription, package management).
- Replacing the existing Web article editor.
- Replacing the existing desktop publish queue.
- New platform adapters not yet in the platform catalog（DedeCMS / PHPCMS 等待适配器就绪后通过目录接入，不改 MCP 层）.
- Bypassing platform review, captcha, risk control or terms of service limitations.
- General-purpose browser automation unrelated to approved SaaS tasks.
- Deep data collection（content list 对账、平台指标、账号资料刷新）— P1.
- Desktop local MCP bridge — P1.

## Further Notes

### P0 Delivery Plan

1. MCP Gateway skeleton（`cmd/mcp-gateway`）with agent auth, scopes, tool discovery, rate limiting and audit.
2. Platform capability catalog 扩展（`media_platforms` 元数据补齐 13 平台 + 2 CMS）。
3. Workspace context, knowledge search, image select 与全量资源（含 AI 账号、站点、配额）。
4. Article plan / generate / rewrite tools 收敛到现有生成入口，接入 quota reservation。
5. Guided mode、confirmation token（目标集绑定）与 compliance precheck/ack。
6. Session check through desktop runtime（媒体 + AI 账号，对齐 authState）。
7. Publish batch（多平台多账号）、publish status、publish retry、schedule publish。
8. Enterprise site publish（WordPress / PBootCMS）。
9. Monitoring overview / question detail / citations / collect-now。
10. Ops visibility for MCP run timelines, per-platform publish health and failures.

### P1 Delivery Plan

1. Desktop local MCP bridge with explicit pairing.
2. Deep data collection tasks（publish_status 回查、content_list 对账、article_metrics、account_profile）。
3. Knowledge item add / image import write tools.
4. Image ranking improvements and optional image generation.
5. Agent run cancel and resume; OAuth 2.1 agent onboarding.
6. DedeCMS / PHPCMS site adapters via catalog.

### Default Assumptions

- "小龙虾"和 "Hermes" are external MCP-compatible agents or agent hosts.
- P0 covers all media platforms with desktop adapters in the catalog and both enterprise CMS adapters; per-platform availability is data-driven, not code-gated in MCP.
- The first content type is enterprise soft article; platform variants derive from it.
- Default safe behavior is guided mode with publish confirmation.
- Auto-publish is allowed only after explicit workspace policy and scoped agent authorization.
- Desktop client remains the only runtime that owns media/AI platform login state; enterprise site credentials remain server-side encrypted.
- Generation LLM selection stays a server-side concern; bound AI accounts are for monitoring collection only.

### Example User Flows

#### 多平台发布

```text
帮我写一篇关于今年企业服务优势的软文，发到搜狐号和百家号，公众号存草稿。
```

Agent expected behavior:

1. Calls `geo.workspace_context`；发现默认品牌、知识分组、图片、3 个目标平台各自的健康账号。
2. Calls `geo.article_plan`（引导模式）→ 用户选定标题与角度。
3. Calls `geo.knowledge_search` + `geo.article_generate`；按平台目录校验百家号封面要求，调用 `geo.image_select`。
4. Calls `geo.article_rewrite` 生成公众号风格变体（如需要）。
5. Calls `geo.desktop_session_check` 覆盖 3 个账号；全部 `active`。
6. 返回预览与完整目标清单："发布到搜狐号账号 A、百家号账号 B（正式发布），公众号账号 C（草稿）？"
7. After user confirms, calls `geo.article_publish`（一个 batch，3 个目标）。
8. Polls `geo.publish_status`；百家号失败时报告 `partially_succeeded`，给出 `geo.publish_retry` 选项。
9. Returns per-target管理链接与公开链接。

#### AI 可见度监测

```text
这周豆包和 DeepSeek 上我们品牌的提及怎么样？再立刻采集一次看看最新效果。
```

Agent expected behavior:

1. Calls `geo.monitoring_overview`（platforms=doubao,deepseek, range=7d）→ 返回提及率、平均提及位次、首推率。
2. Calls `geo.monitoring_citations` → 引用源 Top 列表，标记命中自有发布记录的 URL。
3. Calls `geo.monitoring_collect_now`（HIGH lane）→ 豆包账号 `active` 创建任务；DeepSeek 账号 `challenge_required` 返回修复引导。
4. Polls `geo.publish_status`（run 维度）→ 汇总新一轮采集结果并对比上周。