feat: add machine-readable llms.txt, structured-pipeline example, and uv modernization

Author: xxg1413

.github/workflows/validate.yml

@@ -5,6 +5,7 @@ on:
   push:
     branches:
       - master
+      - main
 
 permissions:
   contents: read
@@ -16,19 +17,27 @@ concurrency:
 jobs:
   validate:
     runs-on: ubuntu-latest
-    timeout-minutes: 20
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    timeout-minutes: 15
     steps:
       - name: Check out repository
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        uses: actions/checkout@v4
 
-      - name: Set up Python
-        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
         with:
-          python-version-file: ".python-version"
-          cache: pip
+          enable-cache: true
 
-      - name: Install Python dependencies
-        run: python -m pip install --disable-pip-version-check -r requirements-dev.lock.txt
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies and dev tools
+        run: uv pip install --system -r requirements-dev.lock.txt ruff
+
+      - name: Lint with ruff
+        run: ruff check .
 
       - name: Run tests
         run: python -m pytest

.python-version

@@ -1 +1 @@
-3.12.13
+3.12

README.md

@@ -28,8 +28,8 @@ python examples/product-slug/verify.py solution
 ```
 
 You just reproduced a bug and verified its fixed behavior. Now give the
-[task contract](examples/product-slug/TASK.md) to a coding agent and make the
-starter pass without copying the solution.
+[task contract](examples/product-slug/TASK.md) and [agent rules](templates/AGENT_RULES.example.md)
+to a coding agent (Cursor, Windsurf, Claude Code, Copilot) and make the starter pass without copying the solution.
 
 ## Choose what you need to accomplish
 
@@ -38,8 +38,8 @@ starter pass without copying the solution.
 | Write and change Python safely | [AI Coding workflow](guides/ai-coding/workflow.md) | A bounded change with explicit context and evidence |
 | Turn Python into a reliable product | [Product quality guide](guides/python-engineering/product-quality.md) | A tested, observable, reversible product path |
 | Finish a recurring engineering task | [Playbooks](playbooks/README.md) | A bug fix, API change, integration, dependency upgrade, or release |
-| Practice instead of only reading | [Runnable examples](examples/README.md) | A small local project with a failing starter and verified solution |
-| Give an agent better instructions | [Templates](templates/README.md) | A task contract, plan, review, and verification record |
+| Practice instead of only reading | [Runnable examples](examples/README.md) | Local testable projects with failing starters and verified solutions |
+| Give an agent better instructions | [Templates](templates/README.md) | Task contracts, plans, reviews, IDE rules, and verification records |
 | Build agents, Skills, MCP, APIs, or automation | [Reviewed source catalog](#browse-the-reviewed-source-catalog) | A primary-source path selected for your use case |
 | Find current Python projects | [Project Radar review queue](catalog/projects/README.md) | An evidence-backed shortlist after maintainer review |
 
@@ -52,6 +52,14 @@ Prefer a guided reading path and ongoing updates? Continue on
 [flypython.com](https://flypython.com/). The repository remains the inspectable
 source; the website helps you choose the next useful step.
 
+## For AI Agents and LLMs
+
+If you are an LLM agent or coding assistant (Cursor, Windsurf, Claude Code, Copilot, Perplexity):
+- Ingest repository index: [`llms.txt`](llms.txt) or [`catalog.json`](catalog.json)
+- Universal IDE rules template: [`templates/AGENT_RULES.example.md`](templates/AGENT_RULES.example.md)
+- Machine-readable manifest: [`content-manifest.json`](content-manifest.json)
+- Official web knowledge dump: `https://flypython.com/llms-full.txt`
+
 ## Browse the reviewed source catalog
 
 Choose a learning path below and open the official source that matches your
@@ -190,9 +198,16 @@ Use the Python version declared in `.python-version`, then install the locked
 development dependencies:
 
 ```bash
+# Fast setup using uv (recommended):
+uv venv
+uv pip install -r requirements-dev.lock.txt
+uv run pytest
+
+# Or using standard pip:
 python -m venv .venv
-. .venv/bin/activate
+source .venv/bin/activate
 python -m pip install -r requirements-dev.lock.txt
+pytest
 ```
 
 Run the deterministic checks:

README_cn.md

@@ -26,7 +26,8 @@ python examples/product-slug/verify.py solution
 ```
 
 你刚刚复现了一个 Bug，并验证了修复后的行为。接下来把[任务契约](examples/product-slug/TASK_cn.md)
-交给 coding agent，让 starter 通过测试，但先不要复制 solution。
+与 [Agent 规则模板](templates/AGENT_RULES.example_cn.md) 提供给 Coding Agent（如 Cursor、Windsurf、Claude Code、Copilot），
+让 starter 通过测试，但先不要复制 solution。
 
 ## 选择你现在要完成的事
 
@@ -35,8 +36,8 @@ python examples/product-slug/verify.py solution
 | 安全地编写和修改 Python | [AI Coding 工作方法](guides/ai-coding/workflow_cn.md) | 上下文明确、有证据的边界修改 |
 | 把 Python 变成可靠产品 | [产品质量指南](guides/python-engineering/product-quality_cn.md) | 可测试、可观测、可回退的产品路径 |
 | 完成反复出现的工程任务 | [Playbook](playbooks/README_cn.md) | Bug 修复、API 修改、外部集成、依赖升级或发布 |
-| 动手练习而不只是阅读 | [可运行示例](examples/README_cn.md) | 有失败 starter 和验证后 solution 的本地小项目 |
-| 给 agent 更好的任务信息 | [模板](templates/README.md) | 任务契约、计划、Review 与验证记录 |
+| 动手练习而不只是阅读 | [可运行示例](examples/README_cn.md) | 包含失败 starter 与验证通过 solution 的本地实战项目 |
+| 给 Agent 更好的上下文与指令 | [模板](templates/README_cn.md) | 任务契约、计划、IDE 规则、Review 与验证记录 |
 | 构建 Agent、Skill、MCP、API 或自动化 | [已审核资料目录](#浏览经过审核的一手资料) | 适合当前用途的一手资料路径 |
 | 发现近期值得关注的 Python 项目 | [Project Radar 审核队列](catalog/projects/README.md) | 经维护者审核、带证据的项目短名单 |
 
@@ -46,6 +47,14 @@ python examples/product-slug/verify.py solution
 希望按路径阅读并持续获得更新，可以继续前往
 [flypython.com](https://flypython.com/)。仓库仍然是可检查的源内容，网站帮助你选择下一步。
 
+## 面向 AI 智能体与 LLM
+
+如果你是 LLM 智能体或 AI 编程助手（Cursor、Windsurf、Claude Code、Copilot、Perplexity）：
+- 快速读取结构化仓库索引：[`llms.txt`](llms.txt) 或 [`catalog.json`](catalog.json)
+- 通用 IDE 行为守则模板：[`templates/AGENT_RULES.example_cn.md`](templates/AGENT_RULES.example_cn.md)
+- 机器可读内容清单：[`content-manifest.json`](content-manifest.json)
+- 官网无噪纯文本知识汇总：`https://flypython.com/llms-full.txt`
+
 ## 浏览经过审核的一手资料
 
 先选择一条学习路径，再打开符合当前目标的官方资料。目录会说明每项资源为什么被收录、
@@ -179,9 +188,16 @@ https://raw.githubusercontent.com/flypythoncom/python/<full-commit-sha>/catalog.
 使用 `.python-version` 指定的 Python，并安装锁定的开发依赖：
 
 ```bash
+# 推荐：使用 uv 极速安装与测试
+uv venv
+uv pip install -r requirements-dev.lock.txt
+uv run pytest
+
+# 或使用标准 pip：
 python -m venv .venv
-. .venv/bin/activate
+source .venv/bin/activate
 python -m pip install -r requirements-dev.lock.txt
+pytest
 ```
 
 运行与 CI 相同的确定性校验：

content-manifest.json

@@ -346,6 +346,29 @@
         }
       ]
     },
+    {
+      "id": "structured-pipeline-example",
+      "type": "example",
+      "content_version": 1,
+      "status": "reviewed",
+      "reviewed_on": "2026-09-02",
+      "locales": [
+        {
+          "lang": "en-US",
+          "path": "examples/structured-pipeline/README.md",
+          "title": "Resilient batch data pipeline",
+          "summary": "Build an isolated, bounded data batch processing pipeline with error recovery using the standard library.",
+          "sha256": "366cb8a04f17b1f5f80d49889cc4268b7a941e31d789f784b0c5f0b54eb158dd"
+        },
+        {
+          "lang": "zh-CN",
+          "path": "examples/structured-pipeline/README_cn.md",
+          "title": "鲁棒批处理数据流水线",
+          "summary": "使用标准库实现具备错误隔离、类型校验与批处理统计的鲁棒数据流水线。",
+          "sha256": "21b24d351993b947cde9a36c147a4111690204de858cb07f25436d57853f3dd8"
+        }
+      ]
+    },
     {
       "id": "upgrade-python-dependencies",
       "type": "playbook",

examples/README.md

@@ -8,5 +8,6 @@ loop without trusting generated code on sight.
 - [Untrusted payload validation](pydantic-validation/README.md): handle messy camelCase and snake_case inputs, dirty amount strings, and structured error responses.
 - [MCP tool server](mcp-server/README.md): build a standard JSON-RPC 2.0 Model Context Protocol tool server with schema validation and isolated runtime errors.
 - [Async batch fetcher](async-fetcher/README.md): control concurrency with Semaphore, back off and retry transient HTTP failures, and collect structured results.
+- [Resilient batch pipeline](structured-pipeline/README.md): process semi-structured data safely with batch error isolation and field validation using the standard library.
 
 [中文索引](README_cn.md)

examples/README_cn.md

@@ -7,5 +7,6 @@
 - [不可信数据清洗校验](pydantic-validation/README_cn.md)：处理驼峰与下划线混杂入参、带符号金额清洗与结构化错误响应。
 - [MCP 工具服务](mcp-server/README_cn.md)：构建符合规范的 JSON-RPC 2.0 Model Context Protocol 服务端，包含参数模式校验与错误隔离。
 - [受控并发异步抓取器](async-fetcher/README_cn.md)：使用 Semaphore 限制最大并发，对瞬时网络故障进行指数退避重试并聚合结构化结果。
+- [鲁棒批处理数据流水线](structured-pipeline/README_cn.md)：使用标准库实现具备错误隔离、字段校验与统计汇总的安全批处理流水线。
 
 [English index](README.md)

examples/async-fetcher/solution/fetcher.py

@@ -3,7 +3,8 @@
 from __future__ import annotations
 
 import asyncio
-from typing import Any, Awaitable, Callable
+from collections.abc import Awaitable, Callable
+from typing import Any
 
 RETRYABLE_STATUSES = {429, 500, 502, 503, 504}
 

examples/async-fetcher/starter/fetcher.py

@@ -3,7 +3,8 @@
 from __future__ import annotations
 
 import asyncio
-from typing import Any, Awaitable, Callable
+from collections.abc import Awaitable, Callable
+from typing import Any
 
 
 async def async_batch_fetch(
@@ -17,7 +18,7 @@ async def async_batch_fetch(
     responses = await asyncio.gather(*tasks)
 
     results = []
-    for item, resp in zip(items, responses):
+    for item, resp in zip(items, responses, strict=False):
         results.append({
             "item": item,
             "success": resp.get("status_code") == 200,

examples/async-fetcher/tests/test_fetcher.py

@@ -2,6 +2,7 @@
 
 import asyncio
 import unittest
+
 from fetcher import async_batch_fetch