AI 实战文档

Appearance

怎么写 llms.txt ​

Step 1：先选"必读页面" ​

不要一上来全量导出，先挑最能代表站点能力的页面。

建议分三层：

  • P0：新用户必须读。
  • P1：任务执行会用到。
  • P2：背景与扩展材料。

页面分级示例 ​

yaml
# 页面优先级配置
pages:
  P0_must_read:
    - /docs/getting-started
    - /docs/installation
    - /docs/quickstart
    - /docs/configuration

  P1_task_execution:
    - /docs/api/authentication
    - /docs/api/endpoints
    - /docs/tools/index
    - /docs/troubleshooting

  P2_background:
    - /docs/architecture
    - /docs/design-decisions
    - /docs/changelog
    - /docs/faq

Step 2：按任务组织，不按团队组织 ​

错误做法是按部门分组（后端组、前端组）。

正确做法是按任务分组（快速上手、API 接入、故障排查、安全治理）。

任务分组示例 ​

markdown
## 快速上手

> 新用户 5 分钟内完成首次使用

- [安装指南](https://example.com/docs/install)
- [快速开始](https://example.com/docs/quickstart)
- [第一个任务](https://example.com/docs/first-task)

## API 接入

> 开发者集成指南

- [认证方式](https://example.com/docs/api/auth)
- [端点列表](https://example.com/docs/api/endpoints)
- [错误处理](https://example.com/docs/api/errors)
- [速率限制](https://example.com/docs/api/rate-limits)

## 故障排查

> 常见问题解决方案

- [常见问题](https://example.com/docs/faq)
- [错误代码](https://example.com/docs/error-codes)
- [日志查看](https://example.com/docs/logs)
- [性能调优](https://example.com/docs/performance)

## 安全治理

> 安全最佳实践

- [安全模型](https://example.com/docs/security)
- [权限配置](https://example.com/docs/permissions)
- [审计日志](https://example.com/docs/audit)

Step 3：添加最小元信息 ​

建议至少包含：

  • 更新时间。
  • 文档语言。
  • 适用范围（对内/对外、版本）。

元信息示例 ​

markdown
---
title: Project Docs for LLMs
last_updated: 2026-03-08
language: zh-CN
version: 1.2.0
scope: public
contact: docs@example.com
---

Step 4：准备 llms-full.txt ​

当站点信息密集时，建议提供完整版纯文本，便于模型一次性读取。

结构建议 ​

txt
# llms-full.txt 结构

1. 项目概述（500 tokens 以内）
2. 核心概念解释（2000 tokens 以内）
3. API 参考（按功能模块分组）
4. 配置选项（完整配置项列表）
5. 常见问题（FAQ 汇总）
6. 示例代码（关键场景代码片段）

生成脚本示例 ​

bash
#!/bin/bash
# generate-llms-full.sh

# 合并所有文档
cat > public/llms-full.txt << EOF
# Project Documentation (Full)

> Generated: $(date +%Y-%m-%d)
> Version: $(git describe --tags)

EOF

# 添加目录
echo -e "\n## Table of Contents\n" >> public/llms-full.txt
find docs -name "*.md" -type f | sort | while read file; do
  title=$(grep -m 1 "^# " "$file" | sed 's/^# //')
  echo "- [$title]($file)" >> public/llms-full.txt
done

# 添加内容
find docs -name "*.md" -type f | sort | while read file; do
  echo -e "\n---\n" >> public/llms-full.txt
  echo "# Source: $file" >> public/llms-full.txt
  cat "$file" >> public/llms-full.txt
done

echo "Generated llms-full.txt ($(wc -l < public/llms-full.txt) lines)"

Step 5：建立自动化校验 ​

  • 链接可达性检查。
  • 更新时间检测。
  • 关键页缺失检测。

校验脚本示例 ​

bash
#!/bin/bash
# validate-llms-txt.sh

LLMS_FILE="public/llms.txt"
ERRORS=0

echo "Validating $LLMS_FILE..."

# 提取所有 URL
URLS=$(grep -oE 'https?://[^)]+' "$LLMS_FILE")

# 检查链接可达性
echo "Checking link accessibility..."
for url in $URLS; do
  status=$(curl -s -o /dev/null -w "%{http_code}" "$url")
  if [ "$status" != "200" ]; then
    echo "ERROR: $url returned $status"
    ((ERRORS++))
  fi
done

# 检查更新时间
echo "Checking last_updated..."
if grep -q "last_updated" "$LLMS_FILE"; then
  last_updated=$(grep "last_updated" "$LLMS_FILE" | head -1 | awk '{print $NF}')
  days_since=$(( ($(date +%s) - $(date -j -f "%Y-%m-%d" "$last_updated" +%s)) / 86400 ))
  if [ $days_since -gt 30 ]; then
    echo "WARNING: llms.txt not updated in $days_since days"
  fi
fi

# 检查必需章节
echo "Checking required sections..."
REQUIRED_SECTIONS=("Start Here" "API" "Troubleshooting")
for section in "${REQUIRED_SECTIONS[@]}"; do
  if ! grep -q "## $section" "$LLMS_FILE"; then
    echo "ERROR: Missing required section: $section"
    ((ERRORS++))
  fi
done

if [ $ERRORS -eq 0 ]; then
  echo "✅ Validation passed"
else
  echo "❌ Validation failed with $ERRORS errors"
  exit 1
fi

CI 配置示例 ​

yaml
# .github/workflows/validate-llms.yml
name: Validate llms.txt

on:
  push:
    paths:
      - public/llms.txt
      - 'docs/**'
  pull_request:
    paths:
      - public/llms.txt
      - 'docs/**'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Validate llms.txt
        run: |
          chmod +x scripts/validate-llms-txt.sh
          ./scripts/validate-llms-txt.sh

      - name: Check llms-full.txt size
        run: |
          if [ -f public/llms-full.txt ]; then
            size=$(wc -c < public/llms-full.txt)
            if [ $size -gt 1000000 ]; then
              echo "WARNING: llms-full.txt exceeds 1MB (current: $size bytes)"
            fi
          fi

开发者与产品经理分工 ​

职责开发者产品经理
格式与发布主责知情
校验自动化主责-
优先级定义建议主责
阅读路径设计建议主责
内容完整性建议主责
更新频率执行定义

维护建议 ​

更新频率 ​

  • 小改动：随时更新 llms.txt
  • 大改动：同时更新 llms-full.txt
  • 定期检查：每周校验链接可达性

版本管理 ​

markdown
# llms.txt 版本历史

## v1.2.0 (2026-03-08)

- 新增故障排查章节
- 更新 API 端点列表
- 修复失效链接

## v1.1.0 (2026-02-15)

- 新增安全治理章节
- 添加元信息字段

## v1.0.0 (2026-01-01)

- 初始版本