无论哪种模式，服务端都不保存任何媒体平台或 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.
| 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. |
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`
| `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。
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.
| `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.
| `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 |
| `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` |
| `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 |
| `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） |
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）.
`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 之外新增目标。
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 模型）.
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.
| Agent confirmation | Stores publish confirmation tokens bound to per-target (platform, account/site, article version, content hash) tuples and the full target set |
| 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 generation boundary | Given a brief and knowledge groups, creates a normal article draft with traceable knowledge metadata via existing entries |
- Same `idempotency_key` replay returns the original resource without duplicate creation; same key with a different payload returns `idempotency_conflict`.
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`.
- 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.
- "小龙虾"和 "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.
