DEVELOPERS

让 AI Agent 替你写稿、选媒体、投放

企业账号可创建 API 令牌，通过 MCP（Cursor、Claude 等）或 REST 调用与网页端相同的能力。扣积分的操作必须先报价、再由你确认。

1. 创建令牌

登录后进入企业资料 → API 接入，新建令牌并勾选权限。令牌只显示一次，请存进密码管理器或环境变量 XINYUAN_TOKEN，不要写进代码仓库。

权限	能做什么
`account:read`	查看账户：积分余额、账号名称
`articles:read`	读取稿件：列出和查看自己的稿件
`articles:write`	写稿 / AI 成文：保存草稿、调用 AI 生成初稿（与网页共用每小时 5 次）
`media:read`	选媒体：按稿件推荐媒体、搜索媒体库
`orders:write`	报价与下单（扣积分）：必须先报价、再凭确认码下单，受每日与单笔上限约束

2. 接入 MCP

服务地址 https://xn--geo-rm0et61l.com/api/mcp，传输方式 Streamable HTTP，鉴权头 Authorization: Bearer 令牌。

Cursor：在项目的 .cursor/mcp.json（或全局 ~/.cursor/mcp.json）中加入：

{
  "mcpServers": {
    "geo-xinyuan": {
      "url": "https://xn--geo-rm0et61l.com/api/mcp",
      "headers": { "Authorization": "Bearer ${env:XINYUAN_TOKEN}" }
    }
  }
}

Claude Code：

claude mcp add --transport http geo-xinyuan https://xn--geo-rm0et61l.com/api/mcp \
  --header "Authorization: Bearer $XINYUAN_TOKEN"

Claude Desktop 等只支持本地进程的客户端，用 mcp-remote 桥接：

{
  "mcpServers": {
    "geo-xinyuan": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://xn--geo-rm0et61l.com/api/mcp", "--header", "Authorization: Bearer ${XINYUAN_TOKEN}"],
      "env": { "XINYUAN_TOKEN": "xy_pat_..." }
    }
  }
}

工具	作用
`get_account`	积分余额、令牌权限与今日下单额度
`draft_article`	按选题 AI 联网成文（每小时 5 次，与网页端共用）
`save_article / get_article / list_articles`	保存、读取、列出稿件
`check_article_quality`	违禁词、广告法、结构完整性质检
`recommend_media`	按稿件内容推荐媒体并给出理由
`search_media`	按名称、分类、地区筛选媒体库
`quote_order`	报价（不扣费），返回 10 分钟有效的确认码
`place_order`	凭确认码下单扣积分
`list_orders / get_order`	订单进度与发布链接

另提供提示模板 publish_article：给一个选题，Agent 按「成文 → 质检 → 选媒体 → 报价 → 等你确认 → 下单」走完整流程。

3. REST API

基础路径 https://xn--geo-rm0et61l.com/api/agent/v1，完整定义见 OpenAPI 文档。

curl -s https://xn--geo-rm0et61l.com/api/agent/v1/me -H "Authorization: Bearer $XINYUAN_TOKEN"

curl -s -X POST https://xn--geo-rm0et61l.com/api/agent/v1/orders/quote \
  -H "Authorization: Bearer $XINYUAN_TOKEN" -H "Content-Type: application/json" \
  -d '{"articleIds":["A..."],"mediaIds":["M..."]}'

错误统一为 {"error":{"code","message","retryable"}}；retryable 为 true 时可稍后重试。

4. 扣费安全

下单权限默认关闭，开启时必须设置单笔上限和每日上限。
先报价、后下单：确认码绑定稿件、媒体、日期和总价，金额有任何变化都会拒绝下单。
同一确认码重复提交不会重复扣费。
每次 API 下单都会发站内通知并记入审计日志；发现异常可随时吊销令牌，立即生效。

给 Agent 的规则

不编造数据和案例；调用 place_order 前必须把报价 summary 告诉用户并得到明确同意。这两条已写进 MCP 服务说明与官方 Skill。