SuperAPI AI 工具集

writing-docs

写作与研究

查看项目

更新于 10-18 04:31

技能介绍

用途:该技能针对 c15t 文档仓库的写作与审查工作,适用于修订 docs/**/*.mdx 中的页面、框架指南、样式配方、演示以及随包发布的 Markdown。技能说明要求对文字应用 unslop,并在改动 MDX 组件或生成逻辑前先阅读 leadtype 技能。

写作前的准备:先确定读者要完成的任务、使用的框架、路由方式和部署形态。Next.js App Router、Pages Router 与静态导出需要不同的说明;Vue 与 Nuxt、Svelte 与 SvelteKit 也各有独立的配置路径。应核对当前包的导出、实现和相关测试;origin/main 与 c15t.com 只用于发现遗漏主题,不能用来确认 v3 API。示例可能滞后于源码,复用前要验证其导入。

页面内容要求:写清结果、前置条件、默认值和失败情形,使读者无需猜测缺失文件即可实现并验证任务。优先选择已有的规范页面,或为不同任务新建页面;共享说明放在 docs/ 中,通过 leadtype include 或链接复用,不要复制 React 指南只替换框架名。页面开头先给出答案与部署约束,使用常见导航标签,如各框架的 Quickstart;标题与描述为必填 frontmatter,seoTitle 与 seoDescription 为可选,仅在搜索用词与导航标签不同时添加,并须与页面及源码实际相符。

代码来源:接入 c15t 的设置代码应来自经 CI 构建或类型检查的示例应用中的标记区域,不要在 MDX 中手写 provider、布局、路由处理器或配置文件。快速开始或渲染页面中的设置代码取自 examples/<framework> 下的 starter;回调、IAB、GPP、无头 UI、嵌入、自托管路由、渲染变体等功能代码取自 internals/doc-snippets/<framework>。internals/fixtures/* 为测试应用,不发布内容;internals/next-compat/* 仍发布其路由契约。这些目录均发布到 docs/shared/examples/<name>/,区域名必须全局唯一。新文件须先被跟踪或执行 git add -N,再运行 bun scripts/sync-example-docs.ts 同步,并在页面中 include 对应片段。刻意作为片段使用的代码块需在上一行标注 {/* example: fragment */}。

面向人与智能体的写作:每个解释应可独立理解,明确 API、框架和条件,不写“如上所述”;记录类型无法表达的调用顺序、副作用和失败行为。保留便于人类发现的精简 API 参考表。快速开始应以 Inth 托管式同意管理为主,包括静态站点;自托管和纯浏览器模式作为有意选择的替代方案。需要后端 URL 的页面使用 https://your-project.inth.app 并提示读者替换;v2 的 *.c15t.dev 地址仅在迁移示例中展示;自托管示例使用自有源,如 https://app.example.com/api/c15t。优先给出单一可行路径,再链接替代方案。

权限与安装:区分有效权限、显式选择、通知关闭和隐私信号;不得从 useConsent() 推断已记录的授权,也不得把 hydration 视为访客操作;不得声称横幅会自动阻止已有脚本。安装以 c15t 包为主,使用真实导出:c15t/react、c15t/next、c15t/vue、c15t/tanstack-start、c15t/astro 以及无头引擎 c15t。仅对导出映射中不存在的适配器和附加组件使用独立包;Svelte 目前需要 @c15t/svelte,HTML script 标签使用 @c15t/browser。安装命令使用不带 dist-tag 的裸 c15t 包名,并由 scripts/docs-validation.test.ts 强制执行。迁移页面仅在明确标注的 before 示例中展示旧 API。

后端与路由说明:区分后端归属、策略获取和同意记录传输。路由设置指南开头应先说明 Inth 托管、自托管和离线三种选择,再给出推荐的 Inth 步骤。后端端点是公开配置,不应描述为密钥。选择 Next.js 方案前须解释 SSR、流式和浏览器初始化。保留 c15t.config.ts 用于共享配置;当前 API 需要显式 manifest URL,不得记录尚不存在的自动默认值。ConsentRoot 作为 Next.js 组件页面标题,并说明它已包裹 ConsentProvider,其 props 是 state 与 config。同源 rewrite 是可选性能优化而非必需设置,选用时使用 /api/c15t,说明其避免的是浏览器到后端的独立 DNS/TLS 连接,而非消除所有 DNS 或使第三方请求变为第一方。静态导出需要托管层代理或直接公开 URL,因为 Next.js rewrite 需要服务器。

定制与演示:按改动类型选择 API:文案或语言用 i18n 配置;形状、位置、操作布局或阻断用呈现与组件 props;品牌色、字体、圆角、间距或动效用主题 token;特定组件部件用适配器当前 slot API;不同标记用复合组件;完全自定义 UI 与行为用无头 API。各适配器契约不可假设通用。视觉配方需配对确切配置与可见结果说明;截图须为所记录版本的真实组件,不得用生成图作为行为证据。交互演示应使用隔离、可重置且不含生产分析的实例,展示源码、直接演示链接和 iframe 外预期行为,为 iframe 设置描述性标题、懒加载和预留空间,并测试键盘访问、移动布局与重置操作。

发现与发布:为每个公开页面更新 docs/docs.config.ts,框架变体嵌套在 frameworks 导航组下,各框架侧边栏使用相同分组顺序,并确认宿主的框架列表包含每个变体。集成项归入统一 integrations 导航组,其子项为服务类型。每个导出的厂商辅助函数都需要可发现的指南,重写时保留旧路由并与现有集成清单比对。共享集成与嵌入标签页顺序须与框架选择器一致:Next.js、TanStack Start、React、Nuxt、Vue、Astro、Svelte、SvelteKit、HTML、JavaScript,docs.config.ts 与框架索引也须保持该顺序。不得从类别或无 cookie 品牌推断零请求保证,须在源码中核对 alwaysLoad、同意回调及撤销后的持久化。页面移动时配置重定向并更新内部链接,删除旧路由前记录已停用 URL 及替代地址,并写入 v3-route-moves.md。llms.txt、页面 Markdown 与包内捆绑内容面向智能体,不承诺搜索排名或引用;HTML 索引、规范 URL、重定向、站点地图、robots 规则和结构化数据需由文档宿主另行验证。

验证:运行 bun run lint:docs 与 bun run fmt:docs,并检查差异是否含无关改动;运行 leadtype lint --src docs 检查链接、元数据和 Markdown 转换;运行 bun run test:scripts scripts/docs-validation.test.ts 仓库检查;用 bun run generate:package-docs 重新生成捆绑内容,不得编辑生成的 packages/*/docs、AGENTS.md 或 SKILL.md。阅读生成的快速开始、样式配方和含视觉内容的页面,确认导入、前置条件、链接和演示说明均保留。尽可能在实际适配器上运行可复制配方,并记录哪些示例经过编译、在浏览器中执行或仅对照源码检查。文档站发布时检查渲染页面和生成产物;若私有宿主不可用,应如实报告该限制。最终以具体任务评估可用性,如 Pages Router SSR、静态导出、纯 Vue 安装、SvelteKit hydration、调整横幅圆角而不使用无头模式、在同意前阻止厂商请求;lint 分数不能证明智能体能完成这些任务。