SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场write-docs-integration-guide

write-docs-integration-guide

写作与研究

查看项目

更新于 10-16 07:31

技能介绍

用途

write-docs-integration-guide 用于为 Tiger Data Docs 文档站点撰写集成指南。当需要记录如何将第三方工具（例如数据库相关工具、BI/可视化、数据工程与 ETL、可观测性与告警、工作流编排等）连接到 Tiger Data 产品时使用本技能。

产出的最终状态为：位于 src/content/docs/integrate/<category>/<slug>.mdx 的 .mdx 文件、astro.config.ts 中的侧边栏条目，以及可选的 logo 资源。

主要能力

  • 按站点既有规范生成集成指南页面骨架或完整草稿。
  • 支持两种运行模式：
    • Scaffold（脚手架）：用户已知集成步骤，希望预处理模板——解析 frontmatter、铺设结构、留下待填占位符。
    • Full draft（完整草稿）：代理根据源 URL（厂商文档、GitHub 示例、博客文章）或通用产品知识撰写正文内容。
  • 处理产品名称规范化与 kebab-case slug 推导。
  • 确认部署范围（Tiger Cloud、自托管、两者），并据此决定 frontmatter、前置条件 partial、标题模式、正文常量以及是否使用 <Tabs>。
  • 管理 logo 与图片资源（明暗变体、仅亮色、暂缺文件）。

使用方式

开始写作前需先阅读两个文件：

  1. src/content/docs/integrate/_template-integration.mdx —— 复制所用的规范骨架，也是脚手架模式下占位符措辞的事实来源。
  2. 同类别中一个已有页面作为语气/深度参考：
    • BI/visualization → bi-vizualization/tableau.mdx
    • Data engineering/ETL → data-engineering-etl/apache-kafka.mdx（长、多部分）或 debezium.mdx（短、两部分）
    • Observability/alerting → observability-alerting/grafana.mdx
    • Workflow orchestration → data-engineering-etl/apache-airflow.mdx

需匹配同类别已有页面的深度与语气，不要自创结构。

先确定产品的规范名称与 kebab-case slug。若以参数传入产品名，则规范化（kafka → Apache Kafka，slug 为 apache-kafka）并通过 AskUserQuestion 确认；否则询问规范产品名并推导 slug（小写，空格和 / → -，去掉标点）。记录：产品名称（厂商偏好的大小写，用于正文、标题、侧边栏标签、成功行）、产品 slug（kebab-case，用于文件路径、logo 文件名、RelatedContentCard href）、厂商 URL（用于一句话简介）。

随后通过 AskUserQuestion 确认模式、部署范围、云平台、logo 情况等。

页面结构

页面自上而下包括：介绍段落、可选的 scope Callout（variant="note"）、"In this integration guide, you:" 要点列表、<Prerequisites context="integration">、一个或多个部分（bilateral parts）、## Verify the integration、成功行、可选的 Troubleshooting / Limitations / Next steps。

大多数集成分成两部分（第三方侧与数据库侧），标题命名结果而非 ## Step 1:。若存在独立数据移动步骤，则成为第三部分。

写作规则

  • 标题使用句子大小写（专有名词和缩写除外）。
  • 不使用 ## Step N: 前缀，编号由 NumberedList 处理。
  • 不使用 --- 水平分隔线。
  • 不使用拉丁缩写（用 "for example" 而非 "e.g."，"that is" 而非 "i.e."，"and so on" 而非 "etc."，"versus" 而非 "vs."）。
  • 除非要求，否则不使用 emoji。
  • 每个代码块都需上下文（在哪运行、做什么、预期结果）。
  • 大量交叉链接。
  • 删除不适用的可选部分。
  • 不使用已废弃的压缩 API（TimescaleDB 2.18.0 将压缩 API 重命名为 columnstore/hypercore）。

目录分类

文件位于 src/content/docs/integrate/<category>/<slug>.mdx，<category> 可选：bi-vizualization、code、configuration-deployment、connectors、data-engineering-etl、data-ingestion-streaming、observability-alerting、query-administration、secure-connectivity。若没有合适的类别，需先询问再新建文件夹。

限制

  • frontmatter 中 integrationPlatforms 为严格枚举（aws, azure, self-hosted），由 src/content.config.ts 校验。
  • integrationIndustry 为自由文本，2–3 个真实垂直行业，不要凑数。
  • keywords 为读者实际会搜索的 4–7 个短语。
  • 只导入实际使用的组件，构建会标记未使用的导入。
  • 正文中当存在常量时绝不硬编码产品或品牌名。