LLMs.txt 最佳实践指南与自动化部署方案

# Northwind 账单结算引擎

> Northwind 是面向订阅制软件团队的企业级计费与发票 API，提供自动化续费与跨国合规处理能力。

服务提供标准化 REST 接口与 Webhook 实时回调系统。
Base URL: https://api.northwind.example/v2
鉴权方式: HTTP Header 中附带 Bearer API Key

## 快速入门
- [新手入门指南](https://docs.northwind.example/quickstart): 账号认证、首笔扣款发起，耗时 5分钟
- [核心概念解析](https://docs.northwind.example/concepts): 客户模型、订阅周期与账单状态机流转

## API 接口参考
- [客户接口](https://docs.northwind.example/api/customers): 客户增删改查及默认付款方式管理
- [订阅生命周期](https://docs.northwind.example/api/subscriptions): 升级降级、按比例计费与退订接口
- [Webhook 回调](https://docs.northwind.example/webhooks): 事件类型定义、重试机制与 HMAC 验签流程

## 客户端 SDK
- [Python SDK](https://docs.northwind.example/sdk/python): 适配 Python 3.9+，支持异步并发请求
- [TypeScript SDK](https://docs.northwind.example/sdk/typescript): 支持 Node.js 与边缘运行时的全类型定义

## 限制与配额
- [调用速率限制](https://docs.northwind.example/limits): 按 Key 分层限流阈值与 429 退避策略

## Optional
- [更新日志](https://northwind.example/changelog): 版本升级历史与破坏性改动说明
- [系统状态监控](https://status.northwind.example): 实时节点可用性与服务故障通告

import fs from 'fs';
import path from 'path';
import matter from 'gray-matter';

interface DocItem {
  title: string;
  description: string;
  category: string;
  url: string;
  order: number;
}

const DOCS_DIR = path.join(process.cwd(), 'docs');
const OUTPUT_PATH = path.join(process.cwd(), 'public/llms.txt');
const DOMAIN = 'https://docs.example.com';

function scanFiles(dir: string): string[] {
  let results: string[] = [];
  const list = fs.readdirSync(dir);
  for (const item of list) {
    const fullPath = path.join(dir, item);
    const stat = fs.statSync(fullPath);
    if (stat && stat.isDirectory()) {
      results = results.concat(scanFiles(fullPath));
    } else if (item.endsWith('.md') || item.endsWith('.mdx')) {
      results.push(fullPath);
    }
  }
  return results;
}

function buildLlmsTxt(): void {
  const files = scanFiles(DOCS_DIR);
  const categoryMap: Map<string, DocItem[]> = new Map();

  for (const file of files) {
    const content = fs.readFileSync(file, 'utf8');
    const { data } = matter(content);
    
    // 忽略未发布的草稿
    if (data.draft) continue;

    const relative = path.relative(DOCS_DIR, file);
    const route = relative.replace(/\.(md|mdx)$/, '').replace(/\\/g, '/');
    const category = data.category || '核心参考';

    const docItem: DocItem = {
      title: data.title || route,
      description: data.description || '技术文档参考说明',
      category,
      url: `${DOMAIN}/${route}`,
      order: data.order ?? 100
    };

    if (!categoryMap.has(category)) {
      categoryMap.set(category, []);
    }
    categoryMap.get(category)!.push(docItem);
  }

  let output = '# 官方开发文档导航\n\n';
  output += '> 提供高吞吐架构与分布式微服务接入指南。\n\n';
  output += `Base URL: ${DOMAIN}\n\n`;

  for (const [category, items] of categoryMap.entries()) {
    output += `## ${category}\n`;
    items.sort((a, b) => a.order - b.order);
    for (const item of items) {
      output += `- [${item.title}](${item.url}): ${item.description}\n`;
    }
    output += '\n';
  }

  fs.writeFileSync(OUTPUT_PATH, output.trim() + '\n', 'utf8');
  console.log(`[Build] 成功生成 /llms.txt，共收录 ${files.length} 个技术页面。`);
}

buildLlmsTxt();

开发者指令: "使用 Python 编写自动化扣费与错误退避脚本"
                 │
                 ▼
AI 辅助引擎 (Claude Desktop / Cursor / 自定义 Agent)
                 │
                 ├─► [1] 发起 GET /llms.txt (读取轻量路由清单)
                 │
                 ├─► [2] 定位目标: [调用速率限制] 与 [Python SDK]
                 │
                 ├─► [3] 按需请求具体两个页面正文 (跳过无关的其余页面)
                 │
                 ▼
生成高准确度代码 (全程仅花费极少 Token，杜绝接口参数幻觉)