OpenSEO 项目初始化技能解析一次访谈把项目记忆写入共享上下文【免费下载链接】open-seoOpen source alternative to Semrush and Ahrefs项目地址: https://gitcode.com/GitHub_Trending/op/open-seo本文以 OpenSEO 仓库中的 SEO 项目初始化技能文档 SKILL.md 为主体完整还原seo-project-setup技能的工作流程如何验证 MCP 连接、如何逐项收集网站范围、目标、定位、竞品与关键页面以及如何用get_project_context/update_project_context两个免费 MCP 工具把访谈结果持久化到项目共享上下文中。读完本文你可以理解这套技能“问什么、写哪里、怎么校验”的完整闭环并在 OpenSEO 中实际执行一次项目记忆初始化。1. 技能定位这是上下文初始化流程不是完整审计文档开篇就明确了技能的边界Goal 一节技能只做一次访谈针对一个网站或一个 SEO 项目用结构化提问收集信息收集到的答案通过update_project_context存入该项目的共享上下文这份上下文会被所有其他技能、应用内的 SAM 助手以及用户在项目的 Context 设置页读到——因此它可以跨越新会话、新机器、新 Agent 存活它是上下文搭建流程不是完整审计。这一点在规格文档 specs/0010-project-memory.md 中可以得到印证该规格说明项目记忆project memory的目标就是让 SAM、MCP 客户端和设置 UI 读写同一份记录解决“每个界面各自重复访谈用户、付费研究被重复购买、用户无法查看和纠正 AI 对项目认知”的问题。seo-project-setup被指定为规范的填充流程canonical populate flow访谈得到的站点范围、目标、定位、竞品、关键资产最终以update_project_context写入而不是写入本地README.md。技能同时定义了语气要求Tone 一节友好、务实、结构化小批量提问只在有用时解释每项为何重要不要用行话压垮新手。2. 答案写到哪里两个免费的 MCP 工具文档Where the answers go 一节指出所有写入都由两个项目上下文 MCP 工具完成且两者都不消耗积分get_project_context(projectId)返回项目已知的全部内容外加一个missingSections缺失清单update_project_context(projectId, updates)接受一个 patch ops 列表本技能用到的操作有Patch 操作结构说明设置类型化章节{ section: business_overview \| current_goal \| positioning \| writing_preferences, content }覆盖对应章节的正文添加竞品{ addCompetitors: [{ domain, name?, notes? }] }按 domain 去重 upsert添加关键页面{ addKeyPages: [{ url, role: hub \| spoke \| money \| other, topic?, notes? }] }按 url 去重 upsert自定义章节{ customSection: slug, title?, content }存放装不进类型化章节的内容追加研究日志{ appendResearchLog: { summary } }当本次会话花了积分时记录供其他技能去重文档还给出两条关键写作准则边访谈边批量写入——不要把所有答案攒到最后一次性写章节是散文而非转录稿——每个章节上限约 4000 字符写几段精炼的段落即可。2.1 源码中的校验细节上述 patch ops 的“线格式wire shape”在仓库中只定义了一次src/types/schemas/projectContext.ts。MCP 工具、server functions 和设置页 UI 都对照这份 Zod schema 校验。几个与文档口径一一对应的实现细节类型化章节键固定为business_overview、current_goal、positioning、writing_preferences四个PROJECT_CONTEXT_SECTION_KEYSsrc/types/schemas/projectContext.ts#L7-L12与文档第 3–5 步的写入目标完全一致每个散文章节的上限PROSE_MAX_CHARS 4000src/types/schemas/projectContext.ts#L30-L31对应文档“~4,000 characters each”的说法关键页面的role枚举正是文档列出的hub | spoke | money | othersrc/types/schemas/projectContext.ts#L33-L35addCompetitors/addKeyPages每次最多 100 条、updates每批最多 50 个操作src/types/schemas/projectContext.ts#L85-L117自定义章节的 slug 必须是形如launch-plan的小写字母数字短横线串最长 60 字符src/types/schemas/projectContext.ts#L41-L49patch op 使用z.strictObject构造键互斥——比如把content误写成contents会直接校验失败而不是静默落入另一个分支。一个值得注意的设计addKeyPages里的role在 schema 中是可选的源码注释解释得很清楚——省略 role 时保留已存的分类这样 Agent 重新添加一个已知 URL 时不会覆盖用户手工设置的标签src/types/schemas/projectContext.ts#L59-L66。2.2 工具实现读回即确认工具定义在 src/server/mcp/tools/project-context.tsget_project_context的readOnlyHint: trueupdate_project_context则标注destructiveHint: true因为 union 中包含章节/竞品/页面/日志的删除操作两个工具都走withMcpProjectAuth做项目级鉴权再进入ProjectContextService写入的返回值会完整回显整个上下文的 markdown 摘要——源码注释指出这份回显既是确认也是调用方的下一次读取因此不存在“patch ops 的说明与实际行为漂移”的第二套描述。服务层 src/server/features/project-context/services/ProjectContextService.ts 补充了两个文档未展开、但影响实操的机制整批原子写入applyContextUpdates先解析、先校验整批操作任何一个操作触碰上限整批一条都不写避免项目停留在“半更新”状态实际落库通过runBatchD1 batch / Postgres 事务一次性提交src/server/features/project-context/services/ProjectContextService.ts#L118-L146。这意味着技能“边访谈边批量写入”是安全的——失败可以整批重试研究日志自带清理appendResearchLog时服务端自动打日期戳YYYY-MM-DD调用方无法指定并在同批内把超过 90 天的条目剪掉RESEARCH_LOG_RETENTION_DAYS 90读取时最多返回最近 20 条src/server/features/project-context/services/ProjectContextService.ts#L17-L18。这正对应文档 Guardrails 中“如果某步花了积分追加一条研究日志让其他技能不会重复购买”的去重语义。get_project_context返回的missingSections也是代码里显式计算的类型化章节中没有任何存储记录的那些键会被列出src/server/features/project-context/services/ProjectContextService.ts#L88-L92并在 markdown 摘要末尾以Missing sections: ...形式渲染——这是其他技能判断“该建议用户跑一遍 seo-project-setup”的信号。3. 完整检查清单从验证连接到推荐下一步技能主体是一个 10 步检查清单Checklist 一节。下面按原顺序完整还原每步要做什么并补充源码可查证的实现依据。3.1 第 1 步验证 OpenSEO MCP 并解析项目写入需要projectId所以第一步永远是最先做的如果可用先用whoami用list_projects确认用户能访问项目把项目匹配到用户想要排名的网站/域名项目列表有歧义时问用户该用哪个项目没有匹配的项目时主动提议用create_project建一个MCP 不可用时告诉用户先连接 OpenSEO MCP——没有它什么都存不了。文档特别强调不要为了测试连通性而运行研究类工具whoami和list_projects足够了。这两个工具在源码中同样被标注为免费、只读whoami 返回认证用户、组织、hosted/self-hosted 模式、token scopes 和剩余积分readOnlyHint: true不调用 DataForSEOlist_projects 返回组织内所有项目的{id, name, domain, locationCode, languageCode, url}并说明locationCode/languageCode是项目的默认市场后续工具在省略 location/language 参数时会回退到它。建项目工具有对应的 create-project.ts 与测试 create-project.test.ts。3.2 第 2 步先读已有内容调用get_project_context向用户简短展示 OpenSEO 已经知道什么、缺什么missingSections。原则是确认或修正已有条目而不是重复提问已经回答过的问题——因为这个技能经常在其他技能已经填了一部分上下文之后被重新运行。这一点与规格文档中的设计一致每个 SEO 技能都有标准“Project context”前奏先读上下文、必要时做最小补充而完整访谈留给付给seo-project-setup建议specs/0010-project-memory.md “Skills”一节。3.3 第 3 步收集网站范围向用户询问主网站/域名其他域名或子域名重要的产品、服务、分类或页面目标国家/语言网站处于什么阶段新建、成熟、迁移中还是从流量下跌中恢复如相关CMS 或发布工作流。把持久性信息写入business_overview业务做什么、面向谁、目标市场/语言环境、站点当前阶段。3.4 第 4 步捕获目标问用户对 SEO 的期望更多合格线索、更多注册/试用、更多电商收入、更多订阅者/受众增长、更多品牌/品类认知、流量损失恢复或特定页面的排名提升。接着问成功指标和时间框架。如果目标含糊帮用户把它们变成可度量的目标例如“提升非品牌词的自然流量注册”或“让 20 个购买意图词进入前 10”。结果连同指标和时间框架一起写入current_goal。3.5 第 5 步捕获定位与策略背景先问用户对公司、产品、受众、竞品已经做过哪些研究请他们提供能分享的笔记、文档、客户访谈、定位文档、pitch deck、落地页或战略备忘录。需要探明的点Probe for 清单逐条保留产品或网站面向谁解决什么痛点用户为什么选它而不是替代品竞品与替代品强烈的观点或定位声明最好的客户和最不匹配的客户已经能转化的既有内容不想覆盖的主题。如果用户还没做过这些研究可以主动提议用公司网站、竞品页面、评论、论坛和网络搜索来协助定位研究。写入规则是positioning受众、问题、差异化点以及用户想要捍卫的声明writing_preferences语气、禁用词/短语、要回避的主题——内容起草类工作流会读这一节规格文档中内容起草流程将writing_preferences列为必需章节。3.6 第 6 步保存竞品把第 5 步得到的竞品与替代品转成addCompetitors条目一个域名一行附一句简短的notes说明它为什么重要例如“直接竞品占着比较页面”。如果用户不确定搜索里谁是对手可以对几个种子关键词跑find_serp_competitors该工具在 src/server/mcp/tools/dataforseo-research-tools.ts 中实现把它们点名——保存前必须与用户确认列表并记录花费即执行appendResearchLog。文档还点明了这些竞品的下游用途保存在这里的竞品会被competitive-landscape、competitor-analysis和link-prospecting三个技能复用。规格文档也给出了各技能的必需章节映射competitive-landscape / competitor-analysis 需要competitorslink-prospecting 需要positioning competitors。3.7 第 7 步盘点关键资产请用户提供或协助发现站点地图或重要 URL 列表现有博客/资源/内容库产品/分类/功能页面已有关键词列表当前排名追踪器反向链接或 PR 资产可链接资产如研究报告、模板、工具、数据集、计算器或原创观点。用addKeyPages保存真正重要的页面——money pages、主题 hub、可链接资产。文档特别强调这是策展后的短名单不是站点全量清单10–30 个 URL 是正常的每个页面给出role已知的话再给topic。这与规格文档的口径一致project_key_pages是 curated shortlist站点全量清单在最新审计的audit_pages和 GSC 中不重复存储。3.8 第 8 步连接 Google Search ConsoleGSC 是最丰富的第一方信号现有展现量、接近排名的词、内容蚕食、已有搜索需求的页面。文档给出两条路径首选hosted原生连接。在项目 Integrations 页连接 Google Search Console之后用get_search_console_performance拉实时数据。连接之后Agent 在keyword-research和keyword-clustering中直接读取它——无需维护手工文件。兜底self-hosted或用户偏好文件请用户从 Search Console 导出 CSV 到本地工作文件夹见第 9 步。推荐的导出项Queries近 3 个月条件允许时近 16 个月Pages近 3 个月条件允许时近 16 个月可能的话Query Page 组合如相关按国家/设备拆分。请用户把文件放进gsc/命名如gsc/queries-last-3-months.csv gsc/pages-last-3-months.csv gsc/queries-last-16-months.csv gsc/pages-last-16-months.csv关于“是否真的已连接”源码给出了可验证的事实search-console-tools.ts 中未连接的项目调用 GSC 工具时会直接返回 “Search Console is not connected for this project.”src/server/mcp/tools/search-console-tools.ts#L105。这就是文档 Guardrails 里“get_search_console_performance没有确认前不得声称已连接”的依据。3.9 第 9 步仅为文件工作建本地文件夹文档明确项目知识住在 OpenSEO 里不在磁盘上。本地文件夹只对真正是文件的东西有用GSC CSV 导出、抓取结果、草稿、brief、报告。如果用户想要建议~/SEO/company-or-site/或网站/内容仓库旁边的文件夹结构如seo-workspace/ gsc/ drafts/ reports/两条纪律用户没要求就不要创建文件夹不要把 goals、positioning、competitors 复制成本地文件——那正是项目上下文存在的意义。3.10 第 10 步推荐第一个后续工作流访谈结束后按用户情境推荐一个下一步 OpenSEO 工作流seo-audit站点已存在、用户想知道先修什么/先做什么尤其是 SEO 新手keyword-research用户需要从种子主题出发找想法keyword-clustering用户已有关键词或 GSC 数据需要映射到页面competitive-landscape市场格局不清楚competitor-analysis用户已经知道要研究哪个竞品link-prospecting用户已有可链接资产或目标页面。这些技能在仓库中都有对应的 SKILL 文件如 plugins/openseo/skills/seo-audit/SKILL.md、plugins/openseo/skills/keyword-research/SKILL.md、plugins/openseo/skills/link-prospecting/SKILL.md 等与本文技能一并通过插件分发plugins/openseo/skills/seo-project-setup/SKILL.md 是同一技能的插件副本。4. 输出格式状态表 摘要技能要求以带状态的检查表呈现进度StepStatusNotesNext action随后给出摘要逐项覆盖OpenSEO MCP / 项目状态范围内的站点目标已知定位已保存的竞品已保存的关键页面Search Console 状态与任何本地文件项目上下文中仍缺失的章节推荐的下一步工作流。最后要告诉用户所有在这里保存的内容都可以、也应该在项目的 Context 设置页上读取和编辑。工具返回的 meta 中也内嵌了指向该页的深链接/p/projectId/settings/context见 src/server/mcp/tools/project-context.ts#L29。5. 护栏写什么、不写什么文档 Guardrails 一节给出五条边界逐条值得遵守保持轻量。用户应该感到被引导而不是被布置作业写入前先与用户确认事实。从站点推断出来的东西可以提出但存进去的必须是“达成一致的答复”不是猜测不要谎报状态。看不到 GSC CSV 就不要声称它已上传get_search_console_performance没有确认前就不要声称 Search Console 已连接未连接时该工具会返回 not connected 消息见 search-console-tools.ts聚焦设置本身除非用户要求实时研究。某一步若花了积分追加一条研究日志让其他技能不再重复购买区分证据与推断。若用网页搜索或抓取做定位研究明确区分来源证据与推断。另有一条隐含在机制里的重要规则文档末行覆盖一个章节就是替换它。上下文已有内容时要把新答案合并进既有散文而不是丢弃原有内容。这与update_project_context的语义一致——{ section, content }是整段覆盖空字符串表示清空所以“先get_project_context读全文、再合并、最后整段写回”是唯一安全的更新方式而竞品和关键页面因为按 domain/url 做 upsert追加式写入则天然幂等。6. 小结seo-project-setup的价值可以用一句话概括它把“Agent 对一个 SEO 项目的认知”从会话级的对话记录升级为服务端持久化、带来源标记user / sam / mcp、用户可编辑、且被所有后续技能共享的结构化记忆。技能本身是一份严谨的操作手册——10 步检查清单、固定的输出格式、清晰的护栏而仓库中的 项目记忆规格、共享 Zod schema、MCP 工具实现 与 服务层实现 则共同保证了文档中的每一条约定免费、4000 字符章节上限、原子批写、90 天研究日志窗口、missingSections信号都有代码级的落地。按照这份技能执行一遍你的 OpenSEO 项目就拥有了后续所有 SEO 工作流共用的“事实底座”。【免费下载链接】open-seoOpen source alternative to Semrush and Ahrefs项目地址: https://gitcode.com/GitHub_Trending/op/open-seo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考