AltoRank

AltoRank：开源、可自托管的 AI SEO 内容撰写工具（Outrank 替代方案）

Outrank 和 Jasper 的开源替代方案。 AltoRank 会研究关键词、撰写文章、评分并核查事实：它会在引用的页面上查找文章中的数据，并将没有来源的数据标记出来，供审核者检查。每篇草稿都可以复制为 Markdown（包括 front matter）或 HTML，也可以下载为 .md 文件，方便你粘贴到发布平台。批准后，粘贴文章，然后点击 标记为已发布，记录线上 URL，之后便会持续追踪文章的收录和排名。

未经具名人员记录批准，AltoRank 绝不会向你的网站发布内容。你可以手动批准每篇草稿，也可以设置规则：若你未在保留期内拦截草稿，则自动批准（该规则通过 CMS 连接发布；功能已构建，但尚未完成端到端验证；请参阅状态）。 Agent 可以通过 MCP 服务和 Agent API 进行研究并撰写草稿。两者都不能批准内容，也不能发布任何未经人员批准的内容（唯一的发布端调用会重试发布已批准文章时失败的操作）。

根据 AGPL-3.0 免费自托管，或使用托管应用 app.altorank.co。整个产品均为开源。没有按功能划分的付费层级，也没有 ee/ 目录。

---

状态

托管应用 app.altorank.co 就是此代码仓库，部署自 main （docs/deploy.md）。自托管安装使用相同代码，但连接你自己的 Supabase 和 API 密钥。研究、起草、评分、事实核查、审计、排名追踪以及 Search Console / Bing 同步目前均可使用；详情见下表。尚未完成的事项：

• 没有付费客户，也没有案例研究。 此处没有任何增长数据，这正是我们有意为之。
• CMS 发布功能已构建，但尚未完成端到端验证。 十三个适配器位于 apps/web/lib/cms/，连接表单也涵盖了所有适配器，但尚未观察到任何一个适配器向线上网站发布内容，因此 /connect 上的平台卡片会让你申请集成，而不是提供连接选项。目前，每篇草稿都可以复制为 Markdown 或 HTML。详情见目前可用的功能。
• AI 可见度追踪功能已构建，但尚未启用。 探测器、每周 cron 和 /geo 页面都已存在，但应用中尚无功能可为工作区启用追踪或添加待测提示词，因此侧边栏将其标记为“即将推出”（apps/web/lib/constants.ts）。
• CLI 可供发布，但尚未发布到 npm。 packages/altorank-cli 会将 apps/web/scripts/cli.ts 打包为 altorank 二进制文件（发布后可运行 npx altorank auth whoami）；在此之前，可以在 apps/web 中通过检出代码运行 npm run cli，使用相同的 Agent API。skills/altorank/SKILL.md 是编码 Agent 读取的技能文件，并且支持通过 npx 安装；详见下文。

无论你是想了解其工作原理、亲自运行，还是提交补丁，所有内容都在这里。

发布决策

一道关卡，两种通过方式。lib/publishing/core.ts 会拒绝任何状态不是 approved 或 scheduled，或未设置 approved_by 的文章。只有服务端可以写入这些列：已登录用户自己的数据库客户端无法将文章设为已批准、已排期或已上线（迁移 109），而对已批准文本的编辑会使其退回审核。可以写入批准信息的方式：

• 由人员在编辑器中执行（approveArticle），并记录为 approved_by。此按钮会检查是否有有效套餐，并拒绝不带来源的单独数字。
• 由账户组中一名具名成员设定的规则（auto_approve，迁移 079）：发布定时任务执行的检查比“批准”按钮更严格——有效套餐、有发布去处、没有不带来源的数字、没有仍待指定审核人签字确认的事项、没有未通过的审计项、SEO 分数不低于下限——并且会等待一段保留期（默认 24 小时），期间草拟的邮件会附带一个“暂缓”链接。approved_by 记录的是启用该规则的人；approval_kind 标记为 auto。暂缓的草稿会在其自身记录中保留原因。参见 lib/publishing/auto-approve.ts。

文章获批并发布后，会被标记为 live；对已批准文章执行 “标记为已发布” 也会将其标记为 live。此外还有一种非发布操作会写入 live：每晚执行的站点发现检查（lib/found-on-site/detect.ts）会在客户自有网站上已存在文章内容时，将草稿标记为 live。这只记录了 AltoRank 之外已完成的操作，不会向 CMS 发送任何内容，也不代表文章已获批准，并且可以在编辑器中撤销。

Agent 无法写入批准信息：没有任何 MCP 工具或 Agent API 调用会批准文章或发布草稿——这不是功能被禁用，而是根本不存在。唯一与发布相关的调用是 altorank_retry_publish（POST /articles/{id}/retry-publish），它会重新执行一篇已由人员批准、但发布失败的文章；其他任何情况都会被拒绝。所有 MCP 工具都在 apps/web/lib/mcp/server.ts 中注册，其中的服务端指令也会向 Agent 说明这一点。

其他工具把“由你掌控”当作宣传文案。这里的区别可以核实：每条 live 记录对应的都是已批准文章（由人员点击批准或通过规则批准），或已在客户自有网站上发布的文章。

当前可用功能

关键词研究 + SERP 分析	DataForSEO
域名审计	9 项就绪度检查、抓取、PageSpeed
文章生成	研究 → 草稿 → 评分 → 事实核查
品牌语气	每个工作区各自的语气配置
发布	每篇草稿均可导出为 Markdown 和 HTML；13 个适配器（见下文），已构建，但尚未完成端到端验证
本地化	35 种（apps/web/lib/seo/locales.ts）
排名跟踪	定时 SERP 检查
搜索分析	Google Search Console；Bing Webmaster Tools（每日点击量和展示量）
AI 可见度	尚未启用：功能已构建（lib/geo/、每周运行的 /api/cron/geo、/geo 页面），用于记录 AI 答案是否提及你，以及转而提及了谁，但目前应用中还没有任何功能可以为工作区启用它

发布目标（apps/web/lib/cms/adapter.ts）——覆盖十个 CMS 平台的 13 个适配器；WordPress 有两种接入方式，而 git 和 webhook 是发布目标，并非 CMS。Framer、Ghost、git、HubSpot、Magento、Notion、Shopify、Webflow、webhook、Wix、WooCommerce、WordPress，以及 WordPress 插件——这是另一种推荐的 WordPress 接入方式，会安装一个插件，并使用每个站点各自的令牌，而非应用密码（apps/web/lib/cms/wordpress-plugin.ts），因此 WordPress 会出现两次。

目前这 13 个适配器均尚未在真实站点上完成端到端验证，因此 apps/web/lib/cms/connectable.ts 中的 CONNECTABLE_CMS 特意保持为空，/connect 上的每个 CMS 磁贴都会显示“申请集成”，而非“连接”；向该集合添加一个 id 即可恢复对应磁贴上的“连接”按钮。连接表单本身没有变化，仍涵盖全部 13 个适配器：页面上的“新建连接”按钮、草稿的发布面板以及 /connect?connect=<id> 都会打开该表单。没有连接时，编辑器会将任意草稿复制为 Markdown（包括 front matter）或 HTML，也可以将其下载为 .md 文件。

安装插件

Claude Code。在终端中运行：

claude plugin marketplace add AltoRank/altorank
claude plugin install altorank@altorank

或者在 Claude Code 会话中运行：/plugin marketplace add AltoRank/altorank，然后运行 /plugin install altorank@altorank。

plugins/altorank/ 将托管的 MCP 服务（https://app.altorank.co/api/mcp，使用 OAuth，无需复制 API 密钥）与为这些工具编写的技能打包在一起。同一文件夹还包含 ChatGPT 和 Codex 可读取的便携版 plugin.json + mcp.json，而 .agents/plugins/marketplace.json 则为它们列出了该插件。

安装技能

npx skills add AltoRank/altorank

这会将 skills/altorank/SKILL.md 放置到 Claude Code、Cursor、Codex、Copilot、Windsurf、Gemini CLI、Cline 以及其他由 skills CLI 支持的 Agent 可以读取的位置。该技能会教 Agent 如何调用 Agent API（/api/agent/v1）：预检密钥、检查站点就绪度、列出或推荐关键词、生成草稿并放入人工审核队列、通过查找和替换来编辑草稿、调整内容计划。它绝不会批准、删除或发布草稿；API 没有此类调用。唯一与发布相关的调用，是重试发布一篇已由人工批准但发布失败的文章。

它需要一个 API 密钥，该密钥在控制面板的 /settings/api-keys 中创建，并导出为 ALTORANK_API_KEY。可自托管的安装还需要设置 ALTORANK_BASE_URL。skills/altorank/commands/ 中包含 5 个用于常见调用的简易斜杠命令；skills CLI 不会注册斜杠命令，因此如果需要，请将它们复制到 .claude/commands/（Claude Code）或对应 Agent 的同等目录中。

运行

需要 Node 22+ 和一个 Supabase 项目（通过 Docker 在本地运行，或使用托管项目）。 完整的部署说明（涵盖托管和自托管）见 docs/deploy.md；Cloudflare 评估见 docs/deploy-cloudflare.md。

npm install
cp docker/.env.example apps/web/.env.local   # every variable, with what each one enables
npm run dev

要让自托管安装完整运行，必须先准备好：

• 你的 Supabase URL、anon key 和 SUPABASE_SERVICE_ROLE_KEY
• NEXT_PUBLIC_APP_URL，即用户打开应用时使用的地址。所有邮件链接（注册确认、邀请、密码重置）均根据它生成，而且 Docker 构建会将它写入镜像，因此请在运行 docker compose up --build 前设置；未设置时，compose 会拒绝构建。
• ANTHROPIC_API_KEY
• ENCRYPTION_KEY 和 CRON_SECRET（分别运行 openssl rand -hex 32 生成）。 未设置 CRON_SECRET 时，docker compose 会拒绝启动，也不会运行任何 定时任务。
• RESEND_API_KEY 和 RESEND_FROM_EMAIL（发件地址必须属于你在 Resend 账户中验证过的域名）。注册需要通过邮件确认，因此未设置这些变量时，无人可以创建账户或重置密码。

添加 DATAFORSEO_LOGIN / DATAFORSEO_PASSWORD，以启用关键词搜索量和排名 跟踪；未设置时会跳过这些步骤，而不会报错。示例文件中的其他变量均为可选项，每个变量只会禁用一项功能。文件中有说明。产品分析（两个 NEXT_PUBLIC_POSTHOG_* 变量，即 项目令牌和主机）也为可选项：未设置时，浏览器控制台会提示分析功能已关闭，其他一切不变。

其他入口：

npm run test     # vitest, unit tier: mocks only, needs no services
npm run test:db  # vitest, db tier: *.db.test.ts against the local Supabase only
npm run smoke    # research → prompt → model → fact check, against real APIs

以及在 apps/web 中：

npm run mcp                  # MCP server over stdio, for driving the engine from an AI assistant
npm run cli -- --help        # the agent API from a shell; auth with ALTORANK_API_KEY
npm run readiness -- <domain>  # the agent-readiness checks on their own

托管 MCP 端点

运行中的应用也会通过 /api/mcp（Streamable HTTP）提供相同的工具，因此 MCP 客户端只需添加一个 URL 作为连接器，无需运行 stdio 服务端：托管安装使用 https://app.altorank.co/api/mcp，自托管时则使用你自己的源站。身份验证使用 bearer token，可以是 /settings/api-keys 中的 API 密钥，也可以是内置 OAuth 流程签发的令牌：

• 在 /.well-known/oauth-authorization-server 和 /.well-known/oauth-protected-resource/api/mcp 进行发现
• 在 /api/oauth/register 动态注册客户端（仅限公开客户端，且仅支持 PKCE S256）
• 在 /oauth/authorize 获取授权；仅限所有者或管理员，可选择启用写入范围
• 在 /api/oauth/token 获取令牌，使用授权码授权，不提供刷新令牌

连接器收到的令牌对应一条 api_keys 记录（迁移 080），因此它会像其他密钥一样列出、过期，并可在 /settings/api-keys 撤销。 Claude Code 使用以下命令注册： claude mcp add --transport http altorank https://app.altorank.co/api/mcp； ChatGPT 和 Claude.ai 则将同一 URL 用作自定义连接器。

CLI 和 MCP 服务端都无法批准文章或删除任何内容——这不是配置限制，而是因为 Agent API 没有这类调用，也完全没有 DELETE 处理器。二者也都无法发布文章：唯一能访问 CMS 的端点是 POST /articles/{id}/retry-publish，它会重新执行此前已由人工批准但后来失败的发布操作。草稿或待审核文章会被拒绝，并提示调用方交由人工处理 （apps/web/app/api/agent/v1/articles/[id]/retry-publish/route.ts:13-35）。

数据库

apps/web/supabase/ 包含一个 config.toml 和按编号排列的迁移文件，这些文件会依次应用。使用 Supabase CLI：

cd apps/web
supabase start      # local Postgres + auth; applies the migrations, prints the URL and keys for .env.local

首次启动时，supabase start 会将所有迁移应用到本地数据库（supabase db reset 会从头重新应用这些迁移）。不要对本地堆栈运行 supabase db push：它的目标是已关联的远程项目。对于托管项目，请先运行 supabase link --project-ref <ref>，然后再运行 supabase db push。缺少迁移时，应用将无法正常运行：所有查询都针对这些迁移所创建的表。

如果你不想直接运行 Node，docker/ 中提供了容器配置。

目录结构

apps/web/               the engine and dashboard (Next.js)
  app/(dashboard)/      dashboard routes
  lib/audit/            domain analysis, readiness checks
  lib/seo/              recommendations, scoring, locales, topical profile
  lib/content/          generation (one implementation, shared by route + cron)
  lib/ai/               fact checking
  lib/cms/              13 publishing adapters
  lib/geo/              AI-answer visibility
  scripts/mcp.ts        MCP server
  scripts/cli.ts        CLI over /api/agent/v1
plugins/altorank/       Claude / ChatGPT / Codex plugin: hosted MCP server + skill
skills/altorank/        the skill file a coding agent reads (`npx skills add AltoRank/altorank`)
packages/altorank-cli/  npm package `altorank`: bundles scripts/cli.ts into a bin
docker/                 container setup for self-hosting
tools/agent-readiness/  standalone agent-readiness scanner

许可

GNU AGPL-3.0-only。 完整文本见 LICENSE。

实际来说：你可以自托管、为自己的客户运行，也可以用于商业用途，无需支付任何费用，也无需发布任何内容。唯一的义务仅适用于重新构建产品的人。如果你修改源代码，并通过网络向他人提供修改后的版本，就必须以相同的许可协议分享你的修改。

在此基础上运行账户免费且不受限制。将修改后的副本重新发布为封闭的竞争服务则不行。

贡献

欢迎提交问题和拉取请求。有两种情况，无论代码质量多好，补丁都会被拒绝：

• 添加无法归因于某个人的发布方式——无论是点击操作，还是由具名成员设定且可否决的规则。由 Agent 触发发布就是典型示例。
• 添加仓库无法证实的声明。如果 grep 找不到某项功能，README 就不能提及它。

审阅补丁时所依据的代码规范，以及此仓库与营销网站的关系，请见 CONTRIBUTING.md。