Home
Softono
y

yaojingang

Professional software vendor delivering innovative solutions on the Softono platform. Specialized in both open-source and proprietary software development.

Visit Website
Total Products
3

Software by yaojingang

yao-geo-skills
Open Source

yao-geo-skills

# Yao GEO Skills 面向 `GEO`（`Generative Engine Optimization`）工作流的开源 Skill 仓库。 英文说明文档： [英文版 README](docs/README.en.md) 可视化导航页： [index.html](index.html) 说明： 本仓库里的 `GEO` 指生成式引擎优化，不是地理信息或地图相关工具。 ## 当前状态 当前仓库包含 `17` 个 GEO 相关 skill，覆盖战略诊断、页面技术、内容生产、知识资产、监测归因、研究拓词和 GEOFlow 运营。 | 分类 | 数量 | 代表场景 | |---|---:|---| | `geo-operations` | 3 | GEOFlow CLI 操作、模板映射、Laravel Blade 主题编辑 | | `geo-strategy` | 2 | GEO 全景诊断、30/60/90 天执行路线图 | | `geo-page-technical` | 2 | 页面 GEO 诊断、GEO 友好页面蓝图 | | `geo-content-production` | 5 | 标题、科普、对比、旧文改造、榜单评测 | | `geo-knowledge-assets` | 2 | 品牌知识图谱、品牌知识库和事实卡 | | `geo-measurement` | 2 | GEO 归因追踪、AI 答案监测月报 | | `geo-research` | 1 | AI 搜索问题集、意图簇和监测 Prompt | 每个正式 skill 至少包含： - `SKILL.md`：Agent 调用入口和执行边界 - `manifest.json`：公开元信息 - `templates/brief-template.md`：输入简报模板 - `evals/trigger_cases.json` 与 `evals/expected_artifacts.json`：触发和产物校验 - `docs/skills/<skill-id>.md`：适合 GitHub 用户阅读的说明页 可运行仓库校验： ```bash python3 scripts/validate_repository.py ``` ## 仓库定位与背景 `yao-geo-skills` 用来沉淀一批可复用、可验证、可开源分享的 GEO Skill。 这里关注的不是零散 prompt，而是完整的执行资产： - 有清晰边界的 `SKILL.md` - 有稳定接口的 `agents/interface.yaml` - 有参考方法、样例、脚本和 eval 的完整包 - 有公开可复用的示例输入、输出和截图 这个仓库适合沉淀以下类型的能力： - GEO 运营流程 - GEO 效果追踪与归因 - GEO 研究与证据扫描 - GEO 相关的共享模板、schema、rubric 和交付规则 如果一句话概括，这个仓库的目标是： 把 GEO 相关的重复工作，整理成团队可以长期复用的 Skill 包。 ## 仓库特点 - 强调可复用：每个 skill 都应该能在相似任务里重复使用，而不是一次性 prompt。 - 强调可验证：仓库和 skill 都有结构校验，不鼓励“能跑就行”的散装内容。 - 强调边界：明确什么时候该用、什么时候不该用，避免 skill 泛化成空话。 - 强调开源安全：公开案例必须去隐私、去内网依赖、去私有系统绑定。 - 强调交付：不少 skill 不只输出文字，还会生成 HTML、DOCX 等可直接交付的产物。 - 强调方法沉淀：复杂方法会拆到 `references/`、`scripts/`、`evals/` 中，而不是堆在一个超长 prompt 里。 ## 适用范围 适合： - 想复用 GEO 相关方法，而不是每次重写 prompt - 想把 GEO 任务做成标准化 skill 包 - 想公开分享 GEO 工作流，同时控制质量和隐私 - 想沉淀可阅读、可验证、可演示的 GEO 样例 不适合： - 只想存放一批零散 prompt - 只想记录临时脑暴，不关心复用与维护 - 需要私有系统、私有文档、私有 API 才能运行的内容 - 与 GEO 无关的通用型 skill 仓库 ## 仓库逻辑 本仓库的组织逻辑很简单： 1. 一个 skill 解决一个明确工作。 2. `skills/` 存技能包本体。 3. `docs/skills/` 存更适合人读的说明页。 4. `registry/skills.json` 记录仓库内 skill 清单。 5. `shared/` 存共享模板、schema、约定。 6. `scripts/validate_repository.py` 负责做仓库级结构校验。 对外展示时，这个仓库优先传达三件事： - 这个 skill 是干什么的 - 这个 skill 怎么保证质量 - 这个 skill 有没有公开可看的示例 ## 下载方式 ### 下载整个仓库 #### 方式 1：`git clone` ```bash git clone https://github.com/yaojingang/yao-geo-skills.git cd yao-geo-skills ``` #### 方式 2：GitHub 页面下载 ZIP 在 GitHub 仓库页面点击： `Code` -> `Download ZIP` ### 只拉取某个 skill #### 方式 1：Sparse Checkout ```bash git clone --filter=blob:none --no-checkout https://github.com/yaojingang/yao-geo-skills.git cd yao-geo-skills git sparse-checkout init --cone git sparse-checkout set skills/yao-geo-tracking docs/skills/yao-geo-tracking.md git checkout main ``` #### 方式 2：手动下载 直接打开对应 skill 目录，在 GitHub 页面按需下载文件： - [skills/yao-geo-tracking](skills/yao-geo-tracking) - [skills/yao-geo-effect-monitor](skills/yao-geo-effect-monitor) - [skills/yao-geo-panorama-audit](skills/yao-geo-panorama-audit) - [skills/yao-geo-page-audit](skills/yao-geo-page-audit) - [skills/yao-geo-ranking-article-builder](skills/yao-geo-ranking-article-builder) - [skills/yao-geo-explainer-builder](skills/yao-geo-explainer-builder) - [skills/yao-geo-content-refiner](skills/yao-geo-content-refiner) - [skills/yao-geo-title-optimizer](skills/yao-geo-title-optimizer) - [skills/yao-geo-comparison-builder](skills/yao-geo-comparison-builder) - [skills/yao-geo-execution-roadmap](skills/yao-geo-execution-roadmap) - [skills/yao-geo-page-blueprint](skills/yao-geo-page-blueprint) - [skills/yao-geo-brand-graph](skills/yao-geo-brand-graph) - [skills/yao-geo-knowledge-base-builder](skills/yao-geo-knowledge-base-builder) - [skills/yao-geo-intent-miner](skills/yao-geo-intent-miner) - [skills/yao-geoflow-cli](skills/yao-geoflow-cli) - [skills/yao-geoflow-template](skills/yao-geoflow-template) - [skills/yao-geoflow-design](skills/yao-geoflow-design) ## Skills 导航 当前 catalog 按工作类型分成 `operations / strategy / page-technical / content-production / knowledge-assets / measurement / research`，方便快速判断一个 skill 是偏执行、偏战略诊断、偏页面技术、偏内容生产、偏知识资产、偏监测，还是偏研究。 ### `operations` <table> <tr> <td valign="top" width="100%"> <strong><code>yao-geoflow-cli</code></strong><br> 作用：通过本地 <code>geoflow</code> CLI 或 Laravel <code>/api/v1</code> fallback 操作已有的 GEOFlow 系统，用于目录查询、任务管理、文章上传、审核与发布。<br><br> 适合：已经有 GEOFlow 系统，需要通过 CLI/API 做运营动作、批量处理、Docker 部署预检或自动化编排。<br><br> 相关入口：<br> <a href="docs/skills/yao-geoflow-cli.md">说明页</a> · <a href="skills/yao-geoflow-cli">Skill 包</a> · <a href="https://github.com/yaojingang/GEOFlow">GEOFlow 项目</a> </td> </tr> <tr> <td valign="top" width="100%"> <strong><code>yao-geoflow-template</code></strong><br> 作用：把参考网址的前台视觉风格映射成 GEOFlow 兼容的主题包方案，输出模块映射、设计 token 和 preview-first 模板结构。<br><br> 适合：GEOFlow 前台模板复刻、参考站样式映射、主题包规划、模板预览与启用前的前置准备。<br><br> 相关入口：<br> <a href="docs/skills/yao-geoflow-template.md">说明页</a> · <a href="docs/skills/yao-geoflow-template.en.md">English Guide</a> · <a href="skills/yao-geoflow-template">Skill 包</a> · <a href="https://github.com/yaojingang/GEOFlow">GEOFlow 项目</a> </td> </tr> <tr> <td valign="top" width="100%"> <strong><code>yao-geoflow-design</code></strong><br> 作用：识别 GEOFlow 当前 Laravel Blade 主题，指定目标主题进入 preview-first 编辑会话，并完成模板复刻、现有模板优化与局部样式调整。<br><br> 适合：GEOFlow 当前主题迭代、指定模板改版、预览态样式优化、参考站风格映射后落地，以及在不破坏 SEO/schema、Markdown 渲染和主题 fallback 契约的前提下新增或替换模板。<br><br> 相关入口：<br> <a href="docs/skills/yao-geoflow-design.md">说明页</a> · <a href="docs/skills/yao-geoflow-design.en.md">English Guide</a> · <a href="skills/yao-geoflow-design">Skill 包</a> · <a href="https://github.com/yaojingang/GEOFlow">GEOFlow 项目</a> </td> </tr> </table> ### `strategy` <table> <tr> <td valign="top" width="100%"> <strong><code>yao-geo-panorama-audit</code></strong><br> 作用：建立品牌 GEO 全景基线，面向 DeepSeek、豆包、千问、Kimi、元宝诊断 AI 答案可见性、竞品差距、内容页面缺口、官网证据和外部信源，并输出机会地图与 P0/P1 优先级。<br><br> 适合：项目启动、季度复盘、竞品追赶、投放前评估，以及需要先判断 GEO 机会和资源优先级的战略诊断。<br><br> 合成示例：<br> <a href="skills/yao-geo-panorama-audit/examples/lingxu-synthetic-panorama/lingxu-panorama-audit.md">Markdown</a> · <a href="skills/yao-geo-panorama-audit/examples/lingxu-synthetic-panorama/lingxu-panorama-audit.html">HTML</a> · <a href="skills/yao-geo-panorama-audit/examples/lingxu-synthetic-panorama/lingxu-panorama-audit.docx">Word</a> · <a href="skills/yao-geo-panorama-audit/examples/lingxu-synthetic-panorama/lingxu-panorama-audit.pdf">PDF</a><br><br> 相关入口：<br> <a href="docs/skills/yao-geo-panorama-audit.md">说明页</a> · <a href="skills/yao-geo-panorama-audit">Skill 包</a> </td> </tr> <tr> <td valign="top" width="100%"> <strong><code>yao-geo-execution-roadmap</code></strong><br> 作用：把 GEO 全景诊断、机会地图和平台采样结论转成系统、详细、完整的 30/60/90 天执行路线图，覆盖真实数据采集计划、来源新鲜度、分析完整性矩阵、证据成熟度、资源预算、治理节奏、六个项目包、国内平台适配和 kami 风格四格式交付。<br><br> 适合：诊断完成后，需要面向 CEO、市场、增长、内容、技术和客户交付团队拆项目包、责任分工、验收指标、预算优先级和风险预案。<br><br> 公开示例：<br> <a href="skills/yao-geo-execution-roadmap/examples/lingxu-demo/report_input.json">输入</a> · <a href="skills/yao-geo-execution-roadmap/examples/lingxu-demo/lingxu-cn-yao-geo-execution-roadmap.md">Markdown</a> · <a href="skills/yao-geo-execution-roadmap/examples/lingxu-demo/lingxu-cn-yao-geo-execution-roadmap.html">HTML</a> · <a href="skills/yao-geo-execution-roadmap/examples/lingxu-demo/lingxu-cn-yao-geo-execution-roadmap.docx">Word</a> · <a href="skills/yao-geo-execution-roadmap/examples/lingxu-demo/lingxu-cn-yao-geo-execution-roadmap.pdf">PDF</a><br><br> 相关入口：<br> <a href="docs/skills/yao-geo-execution-roadmap.md">说明页</a> · <a href="skills/yao-geo-execution-roadmap">Skill 包</a> </td> </tr> </table> ### `page-technical` <table> <tr> <td valign="top" width="100%"> <strong><code>yao-geo-page-audit</code></strong><br> 作用：输入网址后诊断首页、代表性一级页和二级页的可抓取性、结构规范性、内容信号、权威证据和 AI 可抽取性，输出代码层与内容层修复清单、Schema/HTML 建议和固定目录 HTML 报告。<br><br> 适合：官网首页、栏目页、产品页、文章页、帮助中心、文档页、案例页和落地页的 GEO Page Audit，以及需要 Word/PDF/HTML/Markdown 四件套报告的页面诊断交付。<br><br> 公开示例：<br> <a href="skills/yao-geo-page-audit/examples/example-site-demo/example-site-geo-page-audit.md">Markdown</a> · <a href="skills/yao-geo-page-audit/examples/example-site-demo/example-site-geo-page-audit.html">HTML</a> · <a href="skills/yao-geo-page-audit/examples/example-site-demo/example-site-geo-page-audit.docx">Word</a> · <a href="skills/yao-geo-page-audit/examples/example-site-demo/example-site-geo-page-audit.pdf">PDF</a><br><br> 相关入口：<br> <a href="docs/skills/yao-geo-page-audit.md">说明页</a> · <a href="skills/yao-geo-page-audit">Skill 包</a> </td> </tr> <tr> <td valign="top" width="100%"> <strong><code>yao-geo-page-blueprint</code></strong><br> 作用：生成 GEO 友好页面的信息架构、真实数据核验计划、AI 可抽取模块、用户转化模块、HTML 语义结构、Schema 建议、CMS 字段清单，以及 Word/PDF/HTML/Markdown 四格式页面蓝图报告。<br><br> 适合：官网产品页、专题页、文章页、榜单页、对比页、FAQ页、知识库页和案例页设计，尤其是需要同时服务国内 AI 平台抽取和真实用户转化的页面技术场景。<br><br> 公开示例：<br> <a href="skills/yao-geo-page-blueprint/examples/demo/report_input.json">输入</a> · <a href="skills/yao-geo-page-blueprint/examples/demo/lingxu-yao-geo-page-blueprint-demo.md">Markdown</a> · <a href="skills/yao-geo-page-blueprint/examples/demo/lingxu-yao-geo-page-blueprint-demo.html">HTML</a> · <a href="skills/yao-geo-page-blueprint/examples/demo/lingxu-yao-geo-page-blueprint-demo.docx">Word</a> · <a href="skills/yao-geo-page-blueprint/examples/demo/lingxu-yao-geo-page-blueprint-demo.pdf">PDF</a><br><br> 相关入口：<br> <a href="docs/skills/yao-geo-page-blueprint.md">说明页</a> · <a href="skills/yao-geo-page-blueprint">Skill 包</a> </td> </tr> </table> ### `content-production` <table> <tr> <td valign="top" width="100%"> <strong><code>yao-geo-title-optimizer</code></strong><br> 作用：为文章、页面、FAQ 和专题生成 GEO 标题候选库，覆盖国内 AI 平台适配、品牌隔离、公开证据快照、分析维度、合规过滤、标题评分和文章结构映射。<br><br> 适合：内容矩阵标题库、选题命名、标题候选评审、标题到文章结构映射，以及需要 Word/PDF/HTML/Markdown 四格式交付的标题系统。<br><br> 相关入口：<br> <a href="docs/skills/yao-geo-title-optimizer.md">说明页</a> · <a href="skills/yao-geo-title-optimizer">Skill 包</a> </td> </tr> <tr> <td valign="top" width="100%"> <strong><code>yao-geo-comparison-builder</code></strong><br> 作用：生成目标品牌与竞品、同类方案、传统方案或自建方案的 GEO 对比内容，覆盖真实数据获取、来源访问验证、同口径维度、证据锚点、场景选择、FAQ、风险治理和国内 AI 平台适配。<br><br> 适合：品牌替代方案、选型页、竞品对比页、FAQ 页、商业决策类内容，以及需要 Word/PDF/HTML/Markdown 四格式交付的对比内容生产。<br><br> HubSpot 示例：<br> <a href="skills/yao-geo-comparison-builder/examples/hubspot-cn-demo/hubspot-cn-comparison-report.md">Markdown</a> · <a href="skills/yao-geo-comparison-builder/examples/hubspot-cn-demo/hubspot-cn-comparison-report.html">HTML</a> · <a href="skills/yao-geo-comparison-builder/examples/hubspot-cn-demo/hubspot-cn-comparison-report.docx">Word</a> · <a href="skills/yao-geo-comparison-builder/examples/hubspot-cn-demo/hubspot-cn-comparison-report.pdf">PDF</a> · <a href="skills/yao-geo-comparison-builder/examples/hubspot-cn-demo/quality-report.json">质量报告</a><br><br> 相关入口：<br> <a href="docs/skills/yao-geo-comparison-builder.md">说明页</a> · <a href="skills/yao-geo-comparison-builder">Skill 包</a> </td> </tr> <tr> <td valign="top" width="100%"> <strong><code>yao-geo-ranking-article-builder</code></strong><br> 作用：基于品牌 Brief、选题 JSON、竞品库和可信来源生成 GEO 榜单评测文章，覆盖真实数据边界、来源可达审计、分析完整性、评选方法、核心对比表、榜单正文、适合人群、FAQ 和来源表。<br><br> 适合：best、top、alternatives、vs、人群和场景类榜单内容生产，以及需要 Word/PDF/HTML/Markdown 四格式文章包的投放和代理商交付。<br><br> 公开示例：<br> <a href="skills/yao-geo-ranking-article-builder/examples/synthetic-demo/demo-geo-ranking-article.md">Markdown</a> · <a href="skills/yao-geo-ranking-article-builder/examples/synthetic-demo/demo-geo-ranking-article.html">HTML</a> · <a href="skills/yao-geo-ranking-article-builder/examples/synthetic-demo/demo-geo-ranking-article.docx">Word</a> · <a href="skills/yao-geo-ranking-article-builder/examples/synthetic-demo/demo-geo-ranking-article.pdf">PDF</a><br><br> 相关入口：<br> <a href="docs/skills/yao-geo-ranking-article-builder.md">说明页</a> · <a href="skills/yao-geo-ranking-article-builder">Skill 包</a> </td> </tr> <tr> <td valign="top" width="100%"> <strong><code>yao-geo-explainer-builder</code></strong><br> 作用：生成可发布的完整 GEO 科普文章，并附带 How-to 教程、概念解释、怎么选、避坑指南、FAQ、术语表、真实数据接入状态、事实核验矩阵和品牌自然植入建议。<br><br> 适合：品牌教育、行业知识、购买前科普、公众号教程、AI 搜索问答素材，以及需要 kami 版式 Word/PDF/HTML/Markdown 四格式交付的内容生产。<br><br> 公开示例：<br> <a href="skills/yao-geo-explainer-builder/examples/acme-sleep-demo/rendered/deliverables/acme-sleep-geo-explainer.md">Markdown</a> · <a href="skills/yao-geo-explainer-builder/examples/acme-sleep-demo/rendered/deliverables/html-package/index.html">HTML</a> · <a href="skills/yao-geo-explainer-builder/examples/acme-sleep-demo/rendered/deliverables/acme-sleep-geo-explainer.docx">Word</a> · <a href="skills/yao-geo-explainer-builder/examples/acme-sleep-demo/rendered/deliverables/acme-sleep-geo-explainer.pdf">PDF</a> · <a href="skills/yao-geo-explainer-builder/examples/acme-sleep-demo/rendered/quality-report.json">质量报告</a><br><br> 相关入口：<br> <a href="docs/skills/yao-geo-explainer-builder.md">说明页</a> · <a href="skills/yao-geo-explainer-builder">Skill 包</a> </td> </tr> <tr> <td valign="top" width="100%"> <strong><code>yao-geo-content-refiner</code></strong><br> 作用：把已有 SEO 文章、公众号文章、官网文章、白皮书和产品页文案改造成结构化、可信、可引用、可抽取的 GEO 内容。<br><br> 适合：旧文 GEO 改造、AI 可引用内容修复、FAQ、原子事实、真实数据核验、语义实体、平台适配、证据强度、CMS 发布建议，以及带 sticky HTML 菜单和 Kami 编辑排版的 Word/PDF/HTML/Markdown 四格式交付。<br><br> HubSpot 国内 AI 平台测试示例：<br> <a href="skills/yao-geo-content-refiner/examples/hubspot-cn-demo/hubspot-cn-geo-content-refiner-report.md">Markdown</a> · <a href="skills/yao-geo-content-refiner/examples/hubspot-cn-demo/hubspot-cn-geo-content-refiner-report.html">HTML</a> · <a href="skills/yao-geo-content-refiner/examples/hubspot-cn-demo/hubspot-cn-geo-content-refiner-report.docx">Word</a> · <a href="skills/yao-geo-content-refiner/examples/hubspot-cn-demo/hubspot-cn-geo-content-refiner-report.pdf">PDF</a> · <a href="skills/yao-geo-content-refiner/examples/hubspot-cn-demo/quality-report.json">质量报告</a><br><br> 相关入口：<br> <a href="docs/skills/yao-geo-content-refiner.md">说明页</a> · <a href="skills/yao-geo-content-refiner">Skill 包</a> </td> </tr> </table> ### `knowledge-assets` <table> <tr> <td valign="top" width="100%"> <strong><code>yao-geo-brand-graph</code></strong><br> 作用：把企业信息转成品牌、产品、人物、地点、案例、证据和场景之间的实体关系图，输出来源核验、实体清单、关系清单、可信等级、Mermaid、JSON-LD、三元组和图谱补强建议。<br><br> 适合：知识库升级、页面结构设计、监测纠偏、品牌百科化和 AI 内容一致性治理，尤其是需要解决品牌错指、简称歧义、产品关系不清和证据链缺失的场景。<br><br> 公开示例： <a href="skills/yao-geo-brand-graph/examples/hubspot-domestic-ai-test/report_input.json">输入</a> · <a href="skills/yao-geo-brand-graph/examples/hubspot-domestic-ai-test/hubspot-domestic-ai-yao-geo-brand-graph.md">Markdown</a> · <a href="skills/yao-geo-brand-graph/examples/hubspot-domestic-ai-test/hubspot-domestic-ai-yao-geo-brand-graph.html">HTML</a> · <a href="skills/yao-geo-brand-graph/examples/hubspot-domestic-ai-test/hubspot-domestic-ai-yao-geo-brand-graph.docx">Word</a> · <a href="skills/yao-geo-brand-graph/examples/hubspot-domestic-ai-test/hubspot-domestic-ai-yao-geo-brand-graph.pdf">PDF</a><br><br> 相关入口：<br> <a href="docs/skills/yao-geo-brand-graph.md">说明页</a> · <a href="skills/yao-geo-brand-graph">Skill 包</a> </td> </tr> <tr> <td valign="top" width="100%"> <strong><code>yao-geo-knowledge-base-builder</code></strong><br> 作用：基于官网、产品页、帮助中心、白皮书、销售材料、媒体稿和资质文件生成系统化 GEO 品牌知识库、完整实体清单、真实数据获取边界、事实卡、FAQ、禁用表达、Prompt 输入包和来源索引。<br><br> 适合：内容生成、内容改造、页面设计、监测和客服问答前置准备，尤其是面向 Kimi、千问、DeepSeek、豆包、元宝复用结构化品牌事实的知识资产场景。<br><br> 公开示例： <a href="skills/yao-geo-knowledge-base-builder/examples/hubspot-demo/report_input.json">输入</a> · <a href="skills/yao-geo-knowledge-base-builder/examples/hubspot-demo/deliverables/hubspot-demo-geo-knowledge-base.html">HTML</a> · <a href="skills/yao-geo-knowledge-base-builder/examples/hubspot-demo/deliverables/hubspot-demo-geo-knowledge-base.md">Markdown</a> · <a href="skills/yao-geo-knowledge-base-builder/examples/hubspot-demo/deliverables/hubspot-demo-geo-knowledge-base.docx">Word</a> · <a href="skills/yao-geo-knowledge-base-builder/examples/hubspot-demo/deliverables/hubspot-demo-geo-knowledge-base.pdf">PDF</a><br><br> 相关入口：<br> <a href="docs/skills/yao-geo-knowledge-base-builder.md">说明页</a> · <a href="skills/yao-geo-knowledge-base-builder">Skill 包</a> </td> </tr> </table> ### `measurement` <table> <tr> <td valign="top" width="100%"> <strong><code>yao-geo-tracking</code></strong><br> 作用：输入公司名称和辅助信息，基于官网与官方资产生成 GEO 后端效果追踪方案，显式区分国内 / 海外 / 混合 GEO 的不同监测逻辑。<br><br> 适合：官网优先检索、业务识别、直接与间接效果设计、可视化 HTML 报告、DOCX 交付。<br><br> 公开示例：<br> 海外示例：<a href="skills/yao-geo-tracking/examples/hubspot-demo/report_input.json">HubSpot 输入</a> · <a href="skills/yao-geo-tracking/examples/hubspot-demo/hubspot-yao-geo-tracking.html">HTML</a> · <a href="skills/yao-geo-tracking/examples/hubspot-demo/hubspot-yao-geo-tracking.docx">DOCX</a><br> 国内合成示例：<a href="skills/yao-geo-tracking/examples/lingxu-demo/report_input.json">岭序商机云输入</a> · <a href="skills/yao-geo-tracking/examples/lingxu-demo/lingxu-cn-yao-geo-tracking.html">HTML</a> · <a href="skills/yao-geo-tracking/examples/lingxu-demo/lingxu-cn-yao-geo-tracking.docx">DOCX</a><br><br> 相关入口：<br> <a href="docs/skills/yao-geo-tracking.md">说明页</a> · <a href="skills/yao-geo-tracking">Skill 包</a> · <a href="skills/yao-geo-tracking/assets/screenshots/hubspot-yao-geo-tracking.png">海外截图</a> · <a href="skills/yao-geo-tracking/assets/screenshots/lingxu-cn-yao-geo-tracking.png">国内截图</a> </td> </tr> <tr> <td valign="top" width="100%"> <strong><code>yao-geo-effect-monitor</code></strong><br> 作用：设计 GEO Signal Monitor，面向 DeepSeek、豆包、千问、Kimi、元宝建立 AI 答案监测、引用追踪、真实数据获取、报告完整性模型、品牌事实纠偏、月报告警和谨慎归因闭环。<br><br> 适合：GEO 长期运营、客户月报、内容迭代、页面优化、外部信源建设、品牌事实纠偏和看板/API 字段规划。<br><br> 示例报告：<a href="skills/yao-geo-effect-monitor/examples/synthetic-demo/xinglan-effect-monitor-demo.md">Markdown</a> · <a href="skills/yao-geo-effect-monitor/examples/synthetic-demo/xinglan-effect-monitor-demo.html">HTML</a> · <a href="skills/yao-geo-effect-monitor/examples/synthetic-demo/xinglan-effect-monitor-demo.docx">Word</a> · <a href="skills/yao-geo-effect-monitor/examples/synthetic-demo/xinglan-effect-monitor-demo.pdf">PDF</a><br><br> 相关入口：<br> <a href="docs/skills/yao-geo-effect-monitor.md">说明页</a> · <a href="skills/yao-geo-effect-monitor">Skill 包</a> </td> </tr> </table> ### `research` <table> <tr> <td valign="top" width="100%"> <strong><code>yao-geo-intent-miner</code></strong><br> 作用：把种子词、品牌、产品、竞品、区域、人群和业务材料扩展成 AI 搜索问题集、意图簇、追问链路、查询重写、内容选题、FAQ 题库、知识库条目计划、证据缺口和监测 Prompt 库。<br><br> 适合：内容生产前建立问题底座，尤其是需要面向 DeepSeek、豆包、千问、Kimi、元宝适配国内平台问法，并输出 Word/PDF/HTML/Markdown 四格式交付的意图拓词场景。<br><br> 公开示例：<br> <a href="skills/yao-geo-intent-miner/examples/hubspot-cn-demo/input/report_input.json">示例输入</a> · <a href="skills/yao-geo-intent-miner/examples/hubspot-cn-demo/expected-output/hubspot-cn-ai-intent-miner-demo.html">HTML</a> · <a href="skills/yao-geo-intent-miner/examples/hubspot-cn-demo/expected-output/hubspot-cn-ai-intent-miner-demo.docx">Word</a> · <a href="skills/yao-geo-intent-miner/examples/hubspot-cn-demo/expected-output/hubspot-cn-ai-intent-miner-demo.pdf">PDF</a> · <a href="skills/yao-geo-intent-miner/examples/hubspot-cn-demo/expected-output/hubspot-cn-ai-intent-miner-demo.md">Markdown</a> · <a href="skills/yao-geo-intent-miner/examples/hubspot-cn-demo/expected-output/quality-report.json">质量报告</a><br><br> 相关入口：<br> <a href="docs/skills/yao-geo-intent-miner.md">说明页</a> · <a href="skills/yao-geo-intent-miner">Skill 包</a> </td> </tr> </table> ## 相关示例 仓库内已包含多组公开或合成示例，重点用于展示输入结构、方法链路、四格式交付和质量门： - `yao-geo-tracking`：海外公开公司示例 HubSpot、国内公开合成示例岭序商机云 - `yao-geo-panorama-audit`：岭序商机云 GEO 全景诊断合成示例、HubSpot 国内 AI 平台测试示例 - `yao-geo-page-audit`：示例云服页面 GEO 诊断合成示例、HubSpot 页面诊断示例 - `yao-geo-page-blueprint`：页面蓝图示例和 HubSpot 中文页面蓝图示例 - `yao-geo-ranking-article-builder`：榜单评测文章合成示例和 HubSpot 示例 - `yao-geo-comparison-builder`：HubSpot 中文对比报告示例 - `yao-geo-content-refiner`：HubSpot 旧文 GEO 改造示例 - `yao-geo-explainer-builder`：Acme Sleep 科普文章、真实数据核验和 kami 四格式报告示例 - `yao-geo-brand-graph`：HubSpot 国内 AI 平台品牌图谱示例 - `yao-geo-knowledge-base-builder`：HubSpot 品牌知识库示例 - `yao-geo-intent-miner`：HubSpot 中文 AI 意图拓词示例 - 示例输出形态：`Markdown`、`HTML`、`Word`、`PDF`、`report_input.json`、`quality-report.json`、截图或预览图（视 skill 类型而定） 这些示例的作用不是给出“真实经营结论”，而是展示： - 方法论如何落到结构化输入 - Skill 如何把方法渲染成可视化交付物 - 国内与海外 GEO 的监测逻辑有什么不同 ## 目录导航 ```text yao-geo-skills/ ├── index.html ├── README.md ├── LICENSE ├── .github/ ├── docs/ │ ├── README.en.md │ ├── repository-design.md │ ├── input-output-contract.md │ ├── naming-conventions.md │ ├── eval-policy.md │ ├── publishing-rules.md │ └── skills/ ├── registry/ ├── scripts/ ├── shared/ └── skills/ ``` 常用目录说明： - [skills/](skills)：Skill 包本体 - [docs/skills/](docs/skills)：适合直接阅读的 skill 说明文档 - [registry/skills.json](registry/skills.json)：仓库 skill 清单 - [scripts/validate_repository.py](scripts/validate_repository.py)：仓库级校验脚本 - [docs/](docs)：仓库规则、契约、命名和发布说明 ## 仓库文档 - [英文首页说明](docs/README.en.md) - [更新日志](docs/CHANGELOG.md) - [仓库设计](docs/repository-design.md) - [输入输出契约](docs/input-output-contract.md) - [命名规范](docs/naming-conventions.md) - [评测策略](docs/eval-policy.md) - [发布规则](docs/publishing-rules.md) ## 设计原则 - 一个 skill 只做一件明确的事 - 优先公开可验证资料，不鼓励事实型 skill 依赖未授权信息 - 输出既要人能读，也要机器能校验 - 公开示例必须去隐私、去内网依赖、去私有客户数据 - eval 和结构检查是默认要求，不是可选项 - 与其堆提示词，不如沉淀长期可维护的技能包 ## 贡献与发布流程 1. 在 `skills/<skill-id>/` 下新增或更新 skill。 2. 在 `docs/skills/` 下补充对应说明页。 3. 在 [`registry/skills.json`](registry/skills.json) 中登记 skill。 4. 运行仓库校验： ```bash python3 scripts/validate_repository.py ``` 5. 自查 diff，确认没有私有数据、临时文件或错误示例。 6. 提交并推送。 7. 非小改动建议通过 PR 方式合并。 更细的发布规则见： [docs/publishing-rules.md](docs/publishing-rules.md)

AI Agents Workflow Automation
412 Github Stars
yao-meta-skill
Open Source

yao-meta-skill

# Yao Meta Skill [![CI](https://github.com/yaojingang/yao-meta-skill/actions/workflows/test.yml/badge.svg)](https://github.com/yaojingang/yao-meta-skill/actions/workflows/test.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-black.svg)](LICENSE) [![English](https://img.shields.io/badge/Docs-English-black)](README.md) [![中文](https://img.shields.io/badge/Docs-%E4%B8%AD%E6%96%87-red)](docs/README.zh-CN.md) [![日本語](https://img.shields.io/badge/Docs-%E6%97%A5%E6%9C%AC%E8%AA%9E-blue)](docs/README.ja-JP.md) [![Français](https://img.shields.io/badge/Docs-Fran%C3%A7ais-green)](docs/README.fr-FR.md) [![Русский](https://img.shields.io/badge/Docs-%D0%A0%D1%83%D1%81%D1%81%D0%BA%D0%B8%D0%B9-purple)](docs/README.ru-RU.md) `YAO` stands for `Yielding AI Outcomes` — the goal is not to generate more prompt text, but to produce reusable AI assets and real operational outcomes. `yao-meta-skill` is a lightweight but rigorous system for creating, evaluating, packaging, and governing reusable agent skills. [Quick Start](#quick-start) · [Examples](examples/README.md) · [Evals](evals/README.md) · [Failure Library](failures/README.md) · [Method Doctrine](#method-doctrine) It turns rough workflows, transcripts, prompts, notes, and runbooks into reusable skill packages with: - a clear trigger surface - a lean `SKILL.md` - optional references, scripts, and evals - a front-loaded intent dialogue with an intent confidence gate, so the system keeps clarifying when the true job, outputs, exclusions, or standards are still fuzzy - a silent-by-default GitHub benchmark scan plus reference synthesis that studies top public repositories and world-class pattern tracks, then surfaces only real conflicts or uncertainty to the user - a generated visual HTML overview for each newly initialized skill - a side-by-side HTML review studio for first-pass human review - an artifact design profile that defines visual direction, layout patterns, and quality gates for reports, tutorials, dashboards, screenshots, and review pages - a prompt quality profile that abstracts need modeling, RTF mapping, complexity, and quality checks into reviewer-visible evidence instead of bloating `SKILL.md` - a systems-thinking model that maps boundaries, feedback loops, drift risks, recurring failure patterns, and highest-leverage quality moves - three high-value next iteration directions after the first package is created - a lightweight feedback log that does not require a full promotion cycle - a baseline compare report for with-skill vs baseline review - a conversation-style, archetype-aware quickstart that steers new packages toward scaffold, production, library, or governed fits - neutral source metadata plus client-specific adapters - governance, promotion, and portability checks built into the default flow ## Architecture Hero view: turn messy operational input into a governed, reusable skill package through one compact flow. ```mermaid flowchart LR A["Inputs<br/>workflow / prompt / transcript / docs / notes"] --> B["Route<br/>SKILL.md"] B --> C["Design<br/>method + gates"] C --> D["Run<br/>create / validate / eval / promote"] D --> E["Outputs<br/>skill package + reports + adapters"] ``` Read it in 10 seconds: - **Inputs**: start from rough operational material. - **Route**: define boundary and trigger in a lean `SKILL.md`. - **Design**: choose the right archetype, gates, and resource split. - **Run**: use the unified CLI to build, validate, optimize, and promote. - **Outputs**: ship a reusable skill plus evidence, governance signals, and portability artifacts. ## Weighted Quality Benchmark This benchmark is a project-level engineering review, scored from `0-10` per dimension and weighted to `100`. GitHub stars are intentionally excluded because they measure ecosystem heat, not meta-skill engineering quality. Weighted score formula: `sum(score / 10 * weight)`. | Meta Skill | Method Depth 15 | Context Discipline 10 | Toolchain 15 | Eval/Test Rigor 20 | Governance 15 | Portability 10 | Onboarding/Review 5 | Local Reliability 10 | Weighted Score | | --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | | Yao Meta Skill | 9.5 | 8.0 | 9.5 | 9.5 | 9.5 | 9.0 | 6.5 | 9.5 | 91.5 | | Anthropic Skill Creator | 9.0 | 6.5 | 8.5 | 7.5 | 4.0 | 5.0 | 7.5 | 5.0 | 67.5 | | OpenAI Skill Creator | 8.5 | 9.5 | 5.0 | 2.0 | 3.0 | 4.0 | 8.5 | 4.0 | 50.5 | | Rank | Meta Skill | Score | Core Positioning | | ---: | --- | ---: | --- | | 1 | Yao Meta Skill | 91.5 | A complete engineering, evaluation, governance, and portability system for reusable skills. | | 2 | Anthropic Skill Creator | 67.5 | Strong methodology and iteration loop, with weaker local execution reliability and governance coverage. | | 3 | OpenAI Skill Creator | 50.5 | Best treated as a concise skill-writing method guide rather than a full engineering system. | ## Best-Fit Scenarios - Choose **Yao Meta Skill** when the target is a reusable team asset with explicit boundaries, trigger evaluation, governance, packaging, portability, and local execution checks. - Choose **Anthropic Skill Creator** when the target is a conversation-first creation loop and the priority is human-guided iteration over repository-level governance. - Choose **OpenAI Skill Creator** when the target is a compact reference for writing lean skill instructions and keeping context small. - A practical hybrid pattern is still useful: draft conversationally, then use `yao-meta-skill` to harden the package, add evidence, and make it team-ready. ## Quick Start 1. Describe the workflow, prompt set, or repeated task you want to turn into a skill. 2. Start with a short, human intent dialogue so the real job, outputs, exclusions, constraints, and standards are explicit. 3. Let `quickstart` clarify intent first, then run silent benchmark scan and reference synthesis; it only surfaces explicit questions when intent is still unclear or when there is a real design conflict. 4. Use the archetype-aware `quickstart` or the full authoring flow to generate or improve the package in scaffold, production, library, or governed mode. 5. Review the generated `reports/intent-dialogue.md`, `reports/intent-confidence.md`, `reports/reference-synthesis.md`, `reports/artifact-design-profile.md`, `reports/prompt-quality-profile.md`, `reports/system-model.md`, `reports/skill-overview.html`, and `reports/iteration-directions.md` before adding more structure. Or use the unified authoring CLI: ```bash python3 scripts/yao.py quickstart --output-dir . python3 scripts/yao.py github-benchmark-scan my-skill --query "release workflow portability" python3 scripts/yao.py reference-scan my-skill \ --external-reference "World Class Method::method::Borrow a tight evaluation loop.::Do not copy heavy process." \ --user-reference "A product or repo I admire::taste::Learn the clarity and operating standard.::Do not copy wording." \ --local-constraint "Current Library Naming::structure::Keep naming aligned with the local skill library.::Do not inherit private references." python3 scripts/yao.py review-viewer my-skill python3 scripts/yao.py artifact-design-profile my-skill python3 scripts/yao.py prompt-quality-profile my-skill python3 scripts/yao.py system-model my-skill python3 scripts/yao.py feedback my-skill --note "Tighten exclusions before adding scripts." --rating 4 --category boundary python3 scripts/yao.py baseline-compare python3 scripts/yao.py check-update python3 scripts/yao.py package . --platform generic --output-dir dist ``` ## 5-Minute Workflow 1. Start from a raw workflow note. 2. Turn it into a skill package with `SKILL.md`, `agents/interface.yaml`, and only the folders the workflow actually needs. 3. Validate the trigger description with `evals/trigger_cases.json`. 4. Export compatibility artifacts for the clients you care about. 5. Compare the result against the examples in `examples/`. Minimum commands: ```bash python3 scripts/trigger_eval.py --description-file evals/improved_description.txt --cases evals/trigger_cases.json python3 scripts/run_description_optimization_suite.py python3 scripts/judge_blind_eval.py --description-file SKILL.md --cases evals/blind_holdout/trigger_cases.json --semantic-config evals/semantic_config.json python3 scripts/context_sizer.py . python3 scripts/resource_boundary_check.py . python3 scripts/governance_check.py . --require-manifest python3 scripts/cross_packager.py . --platform openai --platform claude --platform generic --expectations evals/packaging_expectations.json --zip python3 tests/verify_packager_failures.py ``` Or run everything together: ```bash make test ``` Unified authoring flow: ```bash python3 scripts/yao.py init my-skill --description "Describe what the skill does." python3 scripts/yao.py validate my-skill python3 scripts/yao.py workspace-flow --target root --label first-pass python3 scripts/yao.py review-viewer my-skill python3 scripts/yao.py review --target root python3 scripts/yao.py release-snapshot --target root --label release-candidate python3 scripts/yao.py package . --platform openai --platform claude --platform generic --output-dir dist --zip python3 scripts/yao.py test ``` ## Results The homepage panel below is generated from the current eval suite so the family-level outcome is visible without opening raw JSON. <!-- BEGIN:EVAL_RESULTS --> - regression corpus: `66` prompts across `21` families - aggregate result: `0` false positives, `0` false negatives, average precision `1.0`, average recall `1.0` - suite status: | Suite | Cases | FP | FN | Precision | Recall | | --- | ---: | ---: | ---: | ---: | ---: | | train | 31 | 0 | 0 | 1.0 | 1.0 | | dev | 22 | 0 | 0 | 1.0 | 1.0 | | holdout | 13 | 0 | 0 | 1.0 | 1.0 | | Family | Cases | Pass Rate | | --- | ---: | ---: | | `brainstorm_only` | 2 | 1.0 | | `brainstorm_vs_build` | 1 | 1.0 | | `complex_multi_asset` | 3 | 1.0 | | `document_export_vs_agent_skill` | 4 | 1.0 | | `document_only` | 3 | 1.0 | | `explain_not_package` | 1 | 1.0 | | `explain_only` | 5 | 1.0 | | `future_outline_vs_build` | 4 | 1.0 | | `iterate_existing_skill` | 5 | 1.0 | | `long_context_document_only` | 3 | 1.0 | | `long_context_near_neighbor` | 3 | 1.0 | | `long_context_summary_only` | 2 | 1.0 | | `long_context_trigger` | 4 | 1.0 | | `meta_skill_creation` | 1 | 1.0 | | `one_off_vs_reusable` | 2 | 1.0 | | `package_for_team` | 2 | 1.0 | | `paraphrase_trigger` | 5 | 1.0 | | `partial_scaffold_not_full_skill` | 4 | 1.0 | | `summary_only` | 3 | 1.0 | | `translate_only` | 4 | 1.0 | | `workflow_to_skill` | 5 | 1.0 | Full reports: [reports/eval_suite.json](reports/eval_suite.json) and [reports/family_summary.md](reports/family_summary.md) <!-- END:EVAL_RESULTS --> - packaging validation: `openai`, `claude`, and `generic` targets pass contract checks - portability score: `100/100` with neutral activation, execution, trust, and degradation metadata preserved across all exported targets - description optimization suite: root, team frontend review, and governed incident command pass blind and adversarial holdout gates; governed incident command still carries one visible holdout miss, and adversarial calibration plus family drift are now tracked separately - judge-backed blind eval: root, team frontend review, and governed incident command now pass an independent rubric judge on blind holdout prompts - packaging failure fixtures: invalid metadata, invalid YAML, and unsupported targets fail as expected - failure library regressions: anti-pattern families pass automated checks - governance and resource-boundary checks are part of the default test path - root governance maturity score: `90/100`; governed benchmark example: `95/100` - CJK-aware trigger matching is now covered by explicit Chinese build, packaging, eval, and near-neighbor cases - context budgets: root `994/1000`, complex benchmark `790/1000`, governed benchmark `760/1000` - quality density: root `130.8`, complex benchmark `164.6`, governed benchmark `171.1` - regression milestones are tracked in [reports/regression_history.md](reports/regression_history.md) - description drift history is tracked in [reports/description_drift_history.md](reports/description_drift_history.md) - route confusion is tracked in [reports/route_scorecard.md](reports/route_scorecard.md) - promotion evidence is summarized in [reports/iteration_ledger.md](reports/iteration_ledger.md) - promotion decisions are published in [reports/promotion_decisions.md](reports/promotion_decisions.md) - candidate lifecycle states are published in [reports/candidate_registry.md](reports/candidate_registry.md) - lightweight with-skill vs baseline comparison is published in [reports/baseline-compare.md](reports/baseline-compare.md) - context budget summaries are tracked in [reports/context_budget.md](reports/context_budget.md) - portability status is tracked in [reports/portability_score.md](reports/portability_score.md) ## Current Strengths The latest weighted review puts Yao at `91.5/100`. The strongest dimensions are the ones that matter most when skills become long-lived team assets: - **Method depth `9.5`**: formal skill engineering doctrine, archetypes, gate selection, non-skill decisions, lifecycle governance, and resource boundaries. - **Toolchain completeness `9.5`**: authoring, validation, benchmark scan, description optimization, report generation, promotion checks, packaging, CI, and portability checks are wired into one operational flow. - **Eval and test rigor `9.5`**: trigger quality is checked with train/dev/holdout, blind holdout, adversarial holdout, judge-backed blind eval, route confusion, drift history, and promotion gates. - **Governance and lifecycle `9.5`**: important skills can carry owner, lifecycle state, review cadence, maturity score, trust boundaries, promotion decisions, and regression history. - **Local execution reliability `9.5`**: the repository is executable locally through `make test`, `make ci-test`, and the unified `scripts/yao.py` authoring CLI. - **Portability and distribution `9.0`**: neutral source metadata, client adapters, degradation rules, packaging contracts, and portability scoring preserve reusable semantics across target environments. - **Systems stability**: generated skills now include a system model that turns boundary discipline, feedback loops, drift watch, and leverage-point analysis into reviewer-visible evidence. - **Context discipline `8.0`**: the entrypoint is still held under budget, but this is tracked as a live constraint because the system now carries more reports, examples, benchmark assets, and generated evidence. - **Onboarding and review experience `6.5`**: quickstart, HTML overview, side-by-side review viewer, and feedback logs have improved the first-run experience, but this remains the clearest UX improvement area. The current direction is deliberate: keep the entrypoint light, make evaluation hard to fake, make governance visible, and continue reducing the friction of first-time creation and review. ## Why Yao - **Lightweight**: the entrypoint stays compact, context budgets are explicit, and extra structure is added only when it pays for itself. - **Rigorous**: trigger quality is checked with family regressions, blind holdout, adversarial holdout, route confusion, judge-backed blind eval, and promotion gates. - **Governed**: important skills are treated as maintainable assets with lifecycle state, maturity expectations, ownership, and review cadence. - **Portable**: source metadata stays neutral while adapters, degradation rules, and packaging contracts preserve reusable semantics across environments. ## What It Does This project helps you create, refactor, evaluate, and package skills as durable capability bundles rather than one-off prompts. The design logic is simple: 1. Capture the real recurring job behind the user's request. 2. Set a clean skill boundary so one package does one coherent job. 3. Optimize the trigger description before over-writing the body. 4. Keep the main skill file small and move details into references or scripts. 5. Add quality gates only when they pay for themselves. 6. Export compatibility artifacts only for the clients you actually need. ## Method Doctrine The repository now treats method as a first-class asset instead of scattered guidance. - [Skill Engineering Method](references/skill-engineering-method.md) - [Intent Dialogue](references/intent-dialogue.md) - [Reference Scan Strategy](references/reference-scan.md) - [Pattern Extraction Doctrine](references/pattern-extraction-doctrine.md) - [Output Quality Risk](references/output-quality-risk.md) - [Authoring Discipline](references/authoring-discipline.md) - [Skill Archetypes](references/skill-archetypes.md) - [Gate Selection](references/gate-selection.md) - [Iteration Philosophy](references/iteration-philosophy.md) - [Non-Skill Decision Tree](references/non-skill-decision-tree.md) - [Regression Cause Taxonomy](references/regression-cause-taxonomy.md) - [Human Review Template](references/human-review-template.md) ## Why It Exists Most teams keep valuable operating knowledge scattered across chats, personal prompts, oral habits, and undocumented workflows. This project converts that hidden process knowledge into: - discoverable skill packages - repeatable execution flows - lower-context instructions - reusable team assets - compatibility-ready distributions ## Repository Structure ```text yao-meta-skill/ ├── SKILL.md ├── README.md ├── VERSION ├── LICENSE ├── .gitignore ├── agents/ │ └── interface.yaml ├── evals/ ├── examples/ ├── references/ ├── scripts/ └── templates/ ``` ## Core Components ### `SKILL.md` The main skill entrypoint. It defines the trigger surface, operating modes, compact workflow, and output contract. ### `agents/interface.yaml` The neutral metadata source of truth. It stores display and compatibility metadata without locking the source tree to one vendor-specific path. ### `references/` Long-form material that should not bloat the main skill file. This includes design rules, evaluation guidance, compatibility strategy, and quality rubrics. ### `scripts/` Utility scripts that make the meta-skill operational: - `trigger_eval.py`: evaluates trigger descriptions with semantic intent concepts, explicit exclusions, and near-neighbor prompts - `run_eval_suite.py`: runs train/dev/holdout trigger suites, reports family-level regressions, and fails if aggregate regressions appear - `optimize_description.py`: generates candidate descriptions, scores them on dev, visible holdout, blind holdout, and adversarial holdout suites, then reports calibration and family health - `judge_blind_eval.py`: applies an independent rubric judge to blind-holdout prompts so blind acceptance is not backed only by the main threshold scorer - `run_description_optimization_suite.py`: runs description optimization across the root skill and governed examples, then writes reusable reports and optional drift snapshots with calibration and family summaries - `promotion_checker.py`: applies promotion policy to current description candidates, writes promotion decisions, builds candidate registries, and emits iteration bundles with review stubs - `create_iteration_snapshot.py`: freezes the current promotion decision into a versioned release snapshot with review, route, and context evidence - `yao.py`: unified authoring CLI that exposes init, validate, optimize-description, promote-check, review, release-snapshot, workspace-flow, report, package, and test as one entrypoint - `render_description_drift_history.py`: turns description-optimization snapshots into a readable drift-history report - `build_confusion_matrix.py`: scores route confusion across tracked sibling skills and `no_route` cases, then writes a route scorecard and optional milestone snapshot - `render_iteration_ledger.py`: compresses regression milestones, description optimization drift, and route scorecards into one iteration-facing ledger - `context_sizer.py`: estimates context weight and warns when the initial load gets too large - `resource_boundary_check.py`: audits whether detail is split across `SKILL.md`, `references/`, `scripts/`, `assets/`, and `evals/` appropriately - `governance_check.py`: validates owner, review cadence, lifecycle stage, and maturity metadata - `render_context_reports.py`: generates root and example context-budget reports plus a shared context summary - `render_regression_history.py`: turns milestone snapshots into a readable regression history report - `cross_packager.py`: builds client-specific export artifacts with explicit platform contracts and validation - `render_portability_report.py`: scores cross-environment portability from neutral metadata, degradation rules, and consumer validation coverage - `init_skill.py`, `lint_skill.py`, `validate_skill.py`, `diff_eval.py`: minimal authoring toolchain - `check_update.py`: checks GitHub for a newer `VERSION` or remote manifest version and reports a reinstall hint without modifying local files - `render_output_risk_profile.py`: predicts output-specific failure modes such as generic headings, citation clutter, screenshot mistakes, weak Markdown tables, and missing execution assumptions ### `evals/` Reusable trigger and packaging checks, including baseline and improved descriptions for comparison plus the root semantic configuration that drives description optimization. This directory also contains route confusion fixtures and promotion policy rules for deciding when a route is promotable. ### `examples/` End-to-end examples showing raw workflow input, design summary, final generated skill shape, and targeted description-optimization packs where route wording is tuned against example-specific dev and holdout cases. ### `.github/workflows/test.yml` Continuous integration entrypoint that runs the full local regression suite on push and pull request. ## Validation Notes - Trigger evaluation now uses a local semantic-intent model with explicit positive concepts, exclusion concepts, and boundary-case reporting. - The sample trigger report now covers a larger positive, negative, and near-neighbor set rather than a tiny demo set. - Train/dev/holdout trigger suites now separate iterative tuning from final verification. - Description optimization now uses dev for ranking, visible holdout for non-regression, blind holdout for acceptance, and adversarial holdout for harder route-collision checks without feeding the ranking loop. - Judge-backed blind eval now adds a rubric-based second opinion for blind prompts, so blind acceptance is not decided by one scorer alone. - Description drift history now records adversarial calibration gaps and family coverage, so routing changes can be judged on confidence and family stability rather than raw error counts alone. - Route confusion is now tracked explicitly across the root meta-skill, frontend review skill, governed incident skill, and `no_route` cases, so route theft is visible instead of implicit. - Promotion policy now requires visible holdout, blind holdout, adversarial holdout, and route confusion to stay clean before a description should be considered promotable. - Promotion checking now emits explicit decisions, candidate lifecycle states, iteration bundles, and human-review stubs rather than leaving promotion as a prose-only step. - Promotion decisions now distinguish “no candidate beat current” from “current still has residual route risk,” so iteration can be audited without forcing every issue into a false block. - Packaging validation now uses explicit contracts and YAML parsing, but it is still a lightweight local validation layer rather than a full platform integration suite. - `evals/failure-cases.md` captures known weak spots that should remain part of regression checks. - `failures/` captures reusable anti-pattern writeups and machine-runnable failure cases for routing, packaging, and authoring failures. - `tests/verify_packager_failures.py` checks that invalid metadata, invalid YAML, and unsupported targets fail clearly. - Governance metadata and resource-boundary rules now have runnable checks instead of staying as prose only. - Governance checks now emit a maturity score so governed assets can be compared instead of only pass/fail checked. - Description optimization drift history is now versioned separately from the main trigger regression history so routing improvements are visible over time. - Iteration evidence now records why a candidate was kept, blocked, or promotable via a shared regression-cause taxonomy and bundle artifacts. - Declared maturity tiers are checked against recommended minimum governance scores, so `production`, `library`, and `governed` assets can be compared without forcing every strong example into the same label. - Context budgets are now tiered and explicit, so a governed skill can still choose a stricter `production`-sized initial-load budget. - Resource-boundary checks now detect decorative directories and compute a local quality-density signal instead of only checking raw token counts. ### `templates/` Starter templates for simple and more advanced skill packages. ## How To Use ### 1. Use the skill directly Invoke `yao-meta-skill` when you want to: - create a new skill - improve an existing skill - add evals to a skill - convert a workflow into a reusable package - prepare a skill for wider team adoption ### 2. Generate a new skill package The typical flow is: 1. describe the workflow or capability 2. identify trigger phrases and outputs 3. choose scaffold, production, or library mode 4. generate the package 5. run the sizing and trigger checks if needed 6. export target-specific compatibility artifacts ### 3. Export compatibility artifacts Examples: ```bash python3 scripts/cross_packager.py ./yao-meta-skill --platform openai --platform claude --expectations evals/packaging_expectations.json --zip python3 scripts/context_sizer.py ./yao-meta-skill python3 scripts/resource_boundary_check.py ./yao-meta-skill python3 scripts/governance_check.py ./yao-meta-skill --require-manifest python3 scripts/trigger_eval.py --description-file evals/improved_description.txt --cases evals/trigger_cases.json --baseline-description-file evals/baseline_description.txt ``` ## Advantages - **Method-first, not prompt-first**: skill creation is treated as a formal engineering workflow with archetypes, gate selection, and non-skill decisions. - **Trigger-aware by design**: descriptions are optimized with route confusion, blind holdout, adversarial families, and promotion policy instead of one-shot intuition. - **Lightweight at the entrypoint**: `SKILL.md` stays compact while references, scripts, and evals are only added when they pay for themselves. - **Toolchain-backed**: initialization, validation, optimization, reporting, packaging, and testing are available through one unified CLI and CI path. - **Governed as an asset**: important skills can carry ownership, lifecycle state, maturity expectations, and review cadence. - **Portable by default**: source metadata stays neutral while adapters and degradation rules preserve compatibility across target environments. - **Evidence-rich**: route scorecards, regression history, context budgets, portability scores, and promotion decisions are published as artifacts instead of hidden implementation detail. ## Best Fit This project is best for: - agent builders - internal tooling teams - prompt engineers moving toward structured skills - organizations building reusable skill libraries ## Documentation | Language | Entry | | --- | --- | | English | [README.md](README.md) | | 中文 | [docs/README.zh-CN.md](docs/README.zh-CN.md) | | 日本語 | [docs/README.ja-JP.md](docs/README.ja-JP.md) | | Français | [docs/README.fr-FR.md](docs/README.fr-FR.md) | | Русский | [docs/README.ru-RU.md](docs/README.ru-RU.md) | ## Examples And Evals - Examples: [examples/README.md](examples/README.md) - Evals: [evals/README.md](evals/README.md) - Failure library: [failures/README.md](failures/README.md) - Failure regression check: [verify_failure_regressions.py](tests/verify_failure_regressions.py) - Regression history: [reports/regression_history.md](reports/regression_history.md) - Root governance score: [reports/governance_score.json](reports/governance_score.json) - Packaging contracts: [references/packaging-contracts.md](references/packaging-contracts.md) - Governance model: [references/governance.md](references/governance.md) - Resource boundary spec: [references/resource-boundaries.md](references/resource-boundaries.md) - Platform capability matrix: [references/platform-capability-matrix.md](references/platform-capability-matrix.md) - Failure fixtures: [tests/fixtures](tests/fixtures) - Adapter snapshots: [tests/snapshots](tests/snapshots) - Evolution example: [examples/evolution-frontend-review/README.md](examples/evolution-frontend-review/README.md) - Governed example: [examples/governed-incident-command/design-summary.md](examples/governed-incident-command/design-summary.md) - Governed example score: [examples/governed-incident-command/generated-skill/reports/governance_score.json](examples/governed-incident-command/generated-skill/reports/governance_score.json) ## License MIT. See [LICENSE](LICENSE).

Productivity AI Tools AI Agents
428 Github Stars
GEOFlow
Open Source

GEOFlow

# GEOFlow > Languages: [简体中文](README.md) | [English](docs/readme/README_en.md) | [日本語](docs/readme/README_ja.md) | [Español](docs/readme/README_es.md) | [Русский](docs/readme/README_ru.md) | [Português (BR)](docs/readme/README_pt_BR.md) > GEOFlow 是一套专门面向 GEO（生成式引擎优化）的开源智能内容工程与多站点分发系统。它把知识库、素材库、提示词、AI 生成任务、审核发布、数据分析、GEOFlow Agent 目标站点包、WordPress REST 渠道、通用 HTTP API 渠道和远端静态页面分发串联为一条可持续运营的工作链路，目标是帮助团队把可信资料沉淀为可管理、可发布、可追踪、可同步到多端的 GEO 内容资产。 [![PHP](https://img.shields.io/badge/PHP-8.2%2B-blue)](https://www.php.net/) [![PostgreSQL](https://img.shields.io/badge/Database-PostgreSQL-336791)](https://www.postgresql.org/) [![Docker](https://img.shields.io/badge/Docker-Compose-blue)](https://docs.docker.com/compose/) [![License](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE) [![GitHub stars](https://img.shields.io/github/stars/yaojingang/GEOFlow?style=social)](https://github.com/yaojingang/GEOFlow/stargazers) [![GitHub forks](https://img.shields.io/github/forks/yaojingang/GEOFlow?style=social)](https://github.com/yaojingang/GEOFlow/network/members) [![GitHub issues](https://img.shields.io/github/issues/yaojingang/GEOFlow)](https://github.com/yaojingang/GEOFlow/issues) GEOFlow 以 [Apache License 2.0](LICENSE) 开源发布。你可以自由使用、复制、修改和分发本项目，包括商业使用；请保留版权声明和许可证文本，并遵守 Apache-2.0 的专利授权、商标与免责声明条款。 --- ## ✨ 你可以用它做什么 | 特性 | 说明 | |------|------| | 🤖 多模型内容生成 | 兼容 OpenAI 风格接口和 Gemini 原生接口，支持 chat / embedding 模型、Provider URL 自动适配、智能模型切换、失败重试和调用统计 | | 🧠 知识库与 RAG | 知识库上传后支持结构化规则切片、可选 LLM 语义规划和稳定回退；配置 embedding 模型后写入向量，在文章生成时召回相关资料 | | 🗂 素材与提示词体系 | 标题库、关键词库、图片库、作者库、知识库、正文提示词、特殊提示词集中管理 | | 📦 任务自动化 | 支持任务创建、生成数量、草稿池、审核开关、发布节奏、队列执行、失败重试、发布范围控制和任务文章筛选 | | 📋 审核与文章管理 | 草稿、审核、发布、回收站、作者、分类、SEO 字段和任务来源统一管理 | | 📡 多站点分发管理 | 支持 GEOFlow Agent、WordPress REST 与通用 HTTP API 渠道、密钥管理、目标站点包、静态模式、伪静态规则、远端文章编辑/删除和队列日志 | | 🧾 目标站点包 | 为每个渠道生成预配置 PHP Agent 包，内置首页、详情页、静态资源、sitemap、`llms.txt` / TXT 地图和 Schema | | 📊 数据分析 | 集中展示系统总览、单站内容运营、多站分发、访问日志、Top 内容、AI 爬虫识别和趋势图 | | 🔍 SEO 与 LLM 抓取友好输出 | 文章 SEO 元信息、Open Graph、Schema、GFM Markdown、独立 CSS、图片同步、sitemap 和 TXT 地图 | | 🎨 前台与主题 | 默认主题、主题包、预览路径、后台主题切换；GEOFlow Agent 渠道可同步站点标题、版权、主题和分类设置 | | 🌍 后台多语言 | 后台支持中文、英文、日语、西班牙语、俄语、葡萄牙语（巴西）切换，并覆盖 2.0 新模块 | | 🔔 版本提醒 | 后台可按 `version.json` 检查 GitHub 新版本，并在有新版本时提醒管理员 | | 🐳 可直接部署 | **Docker Compose** 一键拉起 PostgreSQL（pgvector）、Redis、应用、队列、调度、Reverb 和生产 Nginx/php-fpm | --- ## 🖼 界面预览 <table> <tr> <td width="34%" rowspan="3"><img src="docs/images/screenshots/analytics.png" alt="GEOFlow 中文数据分析" /><br /><sub>数据分析</sub></td> <td width="33%" rowspan="2"><img src="docs/images/screenshots/site-settings.png" alt="GEOFlow 中文网站设置" /><br /><sub>网站设置</sub></td> <td width="33%"><img src="docs/images/screenshots/home.png" alt="GEOFlow 中文后台首页" /><br /><sub>后台首页</sub></td> </tr> <tr> <td width="33%"><img src="docs/images/screenshots/task-management.png" alt="GEOFlow 中文任务管理" /><br /><sub>任务管理</sub></td> </tr> <tr> <td width="33%"><img src="docs/images/screenshots/ai-config.png" alt="GEOFlow 中文 AI 模型配置" /><br /><sub>AI 模型配置</sub></td> <td width="33%"><img src="docs/images/screenshots/materials.png" alt="GEOFlow 中文素材管理" /><br /><sub>素材管理</sub></td> </tr> </table> 上述页面覆盖后台首页、数据分析、任务调度、素材库、模型配置与网站设置等主链路；更多后台说明见 `docs/`。 --- ## 🆕 新版本重点 GEOFlow 2.0 重点变化包括： - **后台首页改为运营导航**：保留三步上手引导，并按单站点运营、多站点分发和配套 skill 资源组织入口。 - **Gemini 与 OpenAI-compatible 接入更完整**：AI 模型配置同时覆盖 OpenAI 风格 Provider 与 Gemini 原生 chat / embedding 路径。 - **知识库支持语义切片规划**：提供结构化规则切片、自动策略和可选 LLM 语义规划，LLM 只规划边界，最终切片仍从原文稳定重建。 - **数据分析独立成页**：系统总览、内容运营、任务健康、素材健康、分发状态、访问日志和 AI 爬虫趋势集中到 `/admin/analytics`。 - **分发管理进入可运行闭环**：支持 GEOFlow Agent、WordPress REST 和通用 HTTP API 渠道新建、密钥管理、测试连接、目标站点包下载、静态/伪静态模式、远端设置同步、队列、日志、远端文章编辑与删除。 - **任务发布范围更清晰**：任务可选择“本地和渠道站点同时发布”“仅发布到渠道站点”“仅发布到本站”，仅本站模式会禁用渠道选择并避免进入远程分发队列。 - **目标渠道站点支持静态页面**：文章分发后生成远端首页、详情页、sitemap、TXT 地图和 `llms.txt`，并同步图片与独立 CSS。 - **素材与 RAG 更完整**：知识库切片、向量化状态、标题库、关键词库、图片库、作者和提示词体系形成任务生产输入。 - **部署与安全增强**：生产 Docker 使用 Nginx + PHP-FPM，默认管理员 seed 不覆盖已有账号，Docker 镜像和 Composer 镜像可配置。 - **多语言覆盖补齐**：后台语言包覆盖 2.0 新增模块，减少界面中出现裸翻译 key 或英文兜底。 --- ## 🏗 运行结构 ``` 后台管理页面 ↓ AI 配置 / 素材库 / 提示词 / 任务配置 ↓ 调度器 / 队列 / Worker 执行 AI 生成 ↓ 草稿 / 审核 / 发布 ↓ 本地前台文章与 SEO 页面 ↓ 分发队列 / 目标站点 Agent ↓ 远端静态首页、详情页、sitemap、TXT 地图与 llms.txt ``` --- ## 🧱 系统架构 | 层级 | 说明 | |------|------| | Web / Admin | **Laravel** 路由与控制器；前台文章站点、**Blade** 后台、数据分析、分发管理、素材与任务入口 | | API / Agent | 本地 API 与目标站点 PHP Agent；负责分发健康检查、文章接收、远端设置同步和静态文件生成 | | Scheduler / Queue / Reverb | **Laravel Scheduler** 扫描与入队；**`queue:work` / Horizon** 消费生成与分发任务；**Reverb** 按需启用 | | Domain & Jobs | `app/Services`、`app/Jobs`、`app/Http/Controllers` 等承载 AI 生成、RAG、发布、分发和日志分析规则 | | Persistence | **PostgreSQL**（推荐 **pgvector** 镜像与线上实例一致）+ **Redis**（队列/缓存等）+ 目标站点本地 JSON/静态文件 | 核心链路： 1. 在后台配置模型、提示词与素材库 2. 准备知识库、标题库、关键词库、图片库和作者库，按需要选择知识库切片策略 3. 创建任务并进入调度与队列 4. Worker（队列进程）调用模型生成正文与元数据 5. 文章进入草稿、审核、发布链路 6. 本地前台输出文章与 SEO 页面 7. 如选择分发渠道，文章进入分发队列并同步到 GEOFlow Agent 或 WordPress 目标站点 8. 数据分析页持续查看内容生产、分发状态、访问日志和 AI 爬虫趋势 --- ## ⚡ 后台三步上手 登录后台后，建议按仪表盘里的「快速开始」完成第一轮验证： 1. **配置 API**：至少添加一个可用 chat 模型；如果需要知识库 RAG 召回，再添加一个 embedding 模型，并选择适合的知识库切片策略。 2. **配置素材库**：准备知识库、标题库、关键词库、图片库和作者。知识库建议先用真实、可验证的业务资料。 3. **新建任务**：选择标题库、素材、模型、生成数量、发布频率和发布范围，先让文章进入草稿或审核流程，再逐步开启自动发布与多站点分发。 --- ## 🎯 适用场景与目标收益 GEOFlow 适合这些真实且可落地的场景： - **独立 GEO 官网** 把官网内容、产品资料、FAQ、案例和品牌知识组织成一个可持续更新的内容系统。目标是提升 AI 搜索可见度、品牌信源覆盖和内容运营效率，而不是堆砌低质量页面。 - **官网中的 GEO 子频道** 在现有官网下搭建一个独立的资讯、知识或解决方案频道。目标是让品牌内容更结构化、更适合搜索引用，也方便不同团队协同更新。 - **独立 GEO 信源站点** 面向某个行业、主题或问题域，持续沉淀高质量文章、榜单、解读、指南和资料。目标是构建稳定可信的外部内容资产，而不是做信息污染。 - **GEO 内容管理系统** 作为内部内容生产后台，统一管理模型、素材、标题、图片、知识库、审核和发布。目标是提升团队提效、降低重复劳动、减少分散工具切换。 - **GEO 多站点 / 多栏目部署** 用同一套系统管理多个站点、多个栏目或多个主题模板。目标是让内容生产、模板切换、分发和维护更标准化。 - **自动化信源管理与内容分发** 对知识库、专题内容、资讯更新和内容分发流程进行工程化管理。目标是让真正有价值的信息更稳定地被用户和 AI 理解、引用和检索。 这套系统的收益，应该建立在**真实、优质、持续维护的知识库**之上。 我们不鼓励利用系统制造信息噪音、批量污染互联网或堆积虚假内容。GEOFlow 的本质是帮助团队更高效地管理、生产和分发可信内容，提升 AI 营销效率和 GEO 运营效率，而不是替代事实、替代判断或替代内容质量本身。 --- ## 🧭 场景对应的部署与使用方式 不同场景下，建议这样使用 GEOFlow： - **作为独立 GEO 官网运行** 直接部署完整前台与后台，围绕官网栏目、产品页延展内容、FAQ、案例和专题进行运营。适合希望把官网做成 AI 搜索友好型内容资产的团队。 - **作为官网中的 GEO 子频道运行** 将 GEOFlow 作为一个相对独立的内容频道部署，再通过导航、子域名或目录与主站打通。适合不想重构主站、但需要快速上线内容频道的团队。 - **作为 GEO 信源站运行** 单独维护一个面向特定主题的内容站点，把知识库和资料建设放在首位，再通过任务系统做稳定更新。适合想做行业型、专题型或问题导向型内容资产的团队。 - **作为内部 GEO 内容管理后台运行** 把前台弱化，重点使用后台的模型配置、素材库、任务调度、审核发布与 API 能力。适合内容团队、增长团队、品牌团队做内部生产系统。 - **作为多站点 / 多频道系统运行** 使用不同模板、栏目、域名或部署实例，管理多个内容出口。适合需要同时维护多个品牌频道、多个主题站或多个实验站点的团队。 - **作为自动化信源管理系统运行** 重点建设知识库、标题库、图片库和提示词体系，把系统当作一个内容工程与分发操作台。适合希望长期沉淀可信知识资产、再逐步扩展自动化能力的团队。 建议的使用顺序是： 1. 先确定真实的业务目标和目标读者 2. 先建设知识库，再建设自动化流程 3. 先确保内容真实、可核验、可维护 4. 再用模型、任务和模板能力去提效 如果知识库本身不真实、不完整、不稳定，再强的自动化也只会放大噪音。 所以在 GEOFlow 里，**知识库建设应该始终排在最前面**。 --- ## 🚀 快速开始 ### 方式一：Docker（开发 / 演示） ```bash # 1. 克隆仓库 git clone https://github.com/yaojingang/GEOFlow.git cd GEOFlow # 2. 复制环境变量 cp .env.example .env # 3. 按需编辑 .env（数据库、Redis、APP_URL、ADMIN_BASE_PATH、REVERB_* 等） vi .env # 4. 构建并启动（含 postgres、redis、init、app、queue、scheduler、reverb） docker compose build docker compose up -d ``` - 前台默认访问：`http://localhost:18080`（端口由环境变量 **`APP_PORT`** 控制，默认 `18080`） - 后台登录：`http://localhost:18080/geo_admin/login`（前缀由 **`ADMIN_BASE_PATH`** 控制，默认 `geo_admin`） 首次启动会运行 **`init`** 容器：在数据库就绪后执行首次迁移与种子（默认管理员见下文「默认管理员」）。 ### 方式一补充：Docker（生产） 生产环境建议使用 **`docker-compose.prod.yml`**，改为 **`Nginx + php-fpm`**，而不是 `php artisan serve`。 如果希望在常见云服务器上自动完成环境自检、Docker 检测、`.env.prod` 生成、容器部署和部署后健康检查，可以使用参考部署脚本： ```bash curl -fsSL https://raw.githubusercontent.com/yaojingang/GEOFlow/main/deploy-scripts/geoflow-docker-deploy.sh -o geoflow-docker-deploy.sh bash geoflow-docker-deploy.sh ``` 脚本说明见 [`deploy-scripts/README.md`](deploy-scripts/README.md)。 ```bash cp .env.prod.example .env.prod vi .env.prod docker compose --env-file .env.prod -f docker-compose.prod.yml build docker compose --env-file .env.prod -f docker-compose.prod.yml up -d postgres redis docker compose --env-file .env.prod -f docker-compose.prod.yml up -d init docker compose --env-file .env.prod -f docker-compose.prod.yml up -d app web queue scheduler reverb ``` - 前台 / 后台统一经 `web`（Nginx）访问 - PHP 由 `app`（php-fpm）解析 - **默认管理员**：生产 `init` 服务会在迁移后执行一次 `db:seed`，只在目标用户名不存在时写入默认后台账号；重复执行不会覆盖已有账号或密码 - 详细说明见 `docs/deployment/DEPLOYMENT.md` ### 方式二：本地 PHP 服务器 **前置要求：** PHP **8.2+**，启用 `pdo_pgsql`、`redis` 等 Laravel 常用扩展；本机已安装 **PostgreSQL** 与 **Redis**；已安装 **Composer 2.x**。 ```bash # 1. 克隆仓库 git clone https://github.com/yaojingang/GEOFlow.git cd GEOFlow # 2. 环境与依赖 cp .env.example .env # 编辑 .env：将 DB_HOST/DB_* 指向本机 Postgres，REDIS_* 指向本机 Redis，QUEUE_CONNECTION=redis 等 composer install --no-interaction --prefer-dist php artisan key:generate # 3. 数据库与存储 php artisan migrate --force php artisan db:seed --force # 可选：写入默认管理员等 php artisan storage:link # 4. 开发用 HTTP（仅本地调试；生产请用 Nginx + PHP-FPM，站点根目录 public/） php artisan serve --host=127.0.0.1 --port=8080 ``` 另开终端启动常驻进程（与 Docker 中 `queue` / `scheduler` / `reverb` 对应）： ```bash php artisan queue:work redis --queue=geoflow,distribution,default --sleep=1 --tries=1 --timeout=300 php artisan schedule:work php artisan reverb:start ``` - 后台：`http://127.0.0.1:8080/geo_admin/login`（若修改了 `ADMIN_BASE_PATH` 请替换路径） - 生产可用 `php artisan horizon` 替代 `queue:work`（需按项目配置托管进程） --- ## 环境要求（部署检查清单） | 组件 | 说明 | |------|------| | PHP | **8.2+**（Docker 镜像可为 8.4） | | 扩展 | Laravel 常规扩展；PostgreSQL 需 `pdo_pgsql`；Redis 队列需 `redis` | | Composer | 2.x | | 数据库 | **PostgreSQL**（推荐 **pgvector**，与 `docker-compose.yml` 中镜像一致） | | Redis | 队列、缓存等（本地极简调试可将 `QUEUE_CONNECTION` 改为 `sync`，生产不推荐） | --- ## 源码部署补充说明 **目录权限（Linux / macOS 常见）：** ```bash chmod -R ug+rwx storage bootstrap/cache ``` **默认管理员（执行 `php artisan db:seed` 后，以 `Database\\Seeders\\AdminUserSeeder` 为准）：** | 字段 | 值 | |------|-----| | 用户名 | `GEOFLOW_ADMIN_USERNAME`，默认 `admin` | | 密码 | 本地开发默认 `password`；生产环境请设置 `GEOFLOW_ADMIN_PASSWORD`。若生产环境留空且账号尚不存在，seed 会生成一次性随机密码并输出到初始化日志 | 补充规则：`AdminUserSeeder` 只在目标用户名不存在时创建账号；重复执行不会覆盖已有用户名、邮箱或密码。若账号已存在，即使生产环境 `GEOFLOW_ADMIN_PASSWORD` 为空，也不会重新生成或打印密码。 ### 管理员登录失败锁定与手动解锁 - 后台账号连续登录失败 **5 次** 会自动锁定（`status=locked`）。 - 被锁定账号无法继续登录，需管理员手动解锁。 - 解锁命令： ```bash php artisan geoflow:admin-unlock <username> ``` 例如： ```bash php artisan geoflow:admin-unlock admin ``` **生产环境 Web：** 使用 Nginx / Apache + **PHP-FPM**，网站根目录指向项目 **`public/`**，勿将仓库根目录直接暴露为文档根。 --- ## Docker 部署补充说明 ### 开发 Compose 服务一览 | 服务 | 作用 | |------|------| | `postgres` | PostgreSQL 16 + pgvector | | `redis` | Redis 7 | | `init` | 一次性初始化（`restart: "no"`） | | `app` | `php artisan serve`，映射 **`${APP_PORT:-18080}:8080`** | | `queue` | `queue:work redis` | | `scheduler` | `schedule:work` | | `reverb` | WebSocket，映射 **`${REVERB_EXPOSE_PORT:-18081}:8080`** | 宿主机仅绑定 **127.0.0.1** 暴露数据库 / Redis 端口时，见 `docker-compose.yml` 中的 `DB_EXPOSE_PORT`、`REDIS_EXPOSE_PORT`。 ### 入口脚本（`docker/entrypoint.sh`）常用变量 | 变量 | 默认 | 含义 | |------|------|------| | `COMPOSER_ON_START` | `true` | 容器启动时执行 `composer install` | | `AUTO_MIGRATE` | `true` | 每次启动执行 `php artisan migrate --force` | | `AUTO_INIT_ONCE` | 仅 `init` 为 `true` | 新库时执行一次 `migrate` + `db:seed` | | `AUTO_GENERATE_APP_KEY` | `init` 内为 `true` | 无有效 `APP_KEY` 时自动生成 | | `AUTO_SEED` | `false` | 为 `true` 时**每次**启动都 `db:seed`（慎用） | Compose 将 **`./storage`** 与 **`./.env`** 挂载进容器；应用代码在镜像内。若要用于正式生产，请改用仓库新增的 **`docker-compose.prod.yml`**（`Nginx + php-fpm`），并参见 `docs/deployment/DEPLOYMENT.md`。 **升级建议：** `git pull` → `docker compose build` → `docker compose up -d`。 --- ## 开发与测试 ```bash composer test ./vendor/bin/pint ``` --- ## 🌍 多语言文档 - [English README](docs/readme/README_en.md) - [日本語 README](docs/readme/README_ja.md) - [Español README](docs/readme/README_es.md) - [Русский README](docs/readme/README_ru.md) --- ## 📄 开源协议 本项目采用 [Apache License 2.0](LICENSE)。该协议允许个人和企业在遵守许可证声明、版权保留、修改说明、专利授权和免责声明等条款的前提下使用、修改、分发和商用 GEOFlow。 --- ## ⭐ Star 趋势 [![Star History Chart](https://api.star-history.com/svg?repos=yaojingang/GEOFlow&type=Date)](https://star-history.com/#yaojingang/GEOFlow&Date)

Web Development AI Tools SEO Tools
2.5K Github Stars