Skip to content

repo-plan-0.0.3.md

Latest commit

 

History

History
206 lines (176 loc) · 11.2 KB

repo-plan-0.0.3.md

File metadata and controls

206 lines (176 loc) · 11.2 KB
Raw

FlyPython 仓库 0.0.3 更新计划

历史版本记录：本文件保留当时的范围与假设，正文不再随仓库更新。§8 TODO 的 勾选状态已于 2026-10-11 对照仓库核对；当前发布状态以 CHANGELOG.md 与 docs/REPO_TO_WEBSITE.md 为准，网站固定的提交记录在网站仓库 src/data/content-pin.json。

版本：0.0.3（规划稿） 更新：2026-09-11（TODO 勾选状态核对于 2026-10-11）

历史边界说明：本文记录 0.0.3 的内容模型和实施计划。当前挑战叙事、认领码、 徽章与公开学习路线已经由 0.0.4 计划接续，本文中的“Agent 授课”叙事不代表 当前产品形态。本文件按所有者决策以中文保留。 关联：flypython.com docs/product-and-growth-plan-0.0.3.md

状态：已基本实现（2026-10-11 核对）。§8 中 FP-326、FP-332、FP-335 仍有 未完成部分，见各项备注；其余各项已在仓库中落地。本计划遵守 AGENTS.md 的 仓库边界：本仓库负责已审核内容、可运行证据与稳定 JSON 契约；网站负责展示与 转化。所有新内容中英文同步产出。

1. 网站 0.0.3 方向对本仓库的要求

网站规划把"agent 自授课课程"定为主产品线、新增 Project Radar 周报， 并把本仓库（4.1k star）作为顶层流量渠道。这需要仓库侧五项能力：

  1. courses/ 内容类型：可被 agent 授课、带客观验证的文件夹。
  2. 结构化的 Project Radar 数据源（每项目一 YAML，不再用 README 表）。
  3. 只产出候选、不生成描述的发现工具。
  4. 契约更新：content-manifest、catalog 导出、schema、llms 文件。
  5. 按 docs/REPO_TO_WEBSITE.md 对 README/README_cn 做导流改造。

2. courses/ 规范（新增顶层目录）

每门课一个文件夹，尽可能由现有 guides/playbooks/examples 装配：

courses/<slug>/
  COURSE.md            # 元信息 + 授课契约（agent 首先读取）：
                       # 受众、前提、工具与版本、课程顺序、授课风格规则、
                       # 何时停止、如何使用 verify.py、本课不覆盖什么
  lessons/
    L01.md  L01_cn.md  # 目标、练习、检查点、预期证据
    ...
  scenario/            # 场景皮数据文件（同一技能、贴近领域）
  TASK.md              # 任务契约（复用 templates/TASK_CONTRACT.md）
  starter/  solution/  # 可运行的一对
  verify.py            # 客观通过/失败；尽量只用标准库
  REVIEW.md            # 维护者跟课记录：日期、工具、版本、授课漂移观察

规则（将写入 AGENTS.md 编辑标准）：

  • agent 依据这些文件授课；不依赖网站、账户或视频。verify.py 是结业证据。
  • 双语：每个英文 lesson 必须有同提交的 *_cn.md；双语齐备才算完成。
  • COURSE.md 必须注明跟课所用的具体工具与版本（如 "Claude Code 2.x"） 及 reviewed_on；工具大版本发布触发复查。
  • REVIEW.md 人工跟课在可行时录屏：录像同时作为网站演示视频素材 （见网站规划 §4.5）。
  • 不虚构成果、薪资或"保证学会"式承诺。

首批（装配而非新写）：C1 Claude Code × Python 实战（旗舰，3 个场景皮： Excel/报表自动化、数据监控、API 小工具）；C2 Codex CLI；C3 AGENTS.md 一份事实源；C4 AI 生成代码的验证与交付；C5 用 MCP 给 agent 接工具。 见网站规划 §2.2。

3. Project Radar 数据模型

把 catalog/projects/README.md 的表格改为每项目一 YAML（与 catalog/resources/ 同一套创作模型）：

id: marimo
repo: marimo-team/marimo
url: https://github.com/marimo-team/marimo
category: notebooks          # 受控列表，有意扩展
status: rising               # new|rising|stable|major-update|experimental|archived
first_seen: 2026-09-02
reviewed_on: 2026-09-02
license: Apache-2.0
evidence:
  last_release: "…"
  release_cadence: "…"
  maintenance: "…"
ai_familiarity: low          # low|medium|high：主流模型训练数据是否覆盖
                             # （AI 时代的差异化字段）
alternatives: [jupyter, quarto]
when_not_to_use: "…"
rationale: "…"               # 人工撰写，遵守策展政策
risk: "…"
  • tools/render_readmes.py 从 YAML 重新生成 Radar 表（沿用 catalog 索引的 生成块约定）。
  • 新增确定性导出 radar.json + schema/radar-v1.schema.json，不扩 catalog-v1（它已被消费方固定）。同样按版本管理；网站消费方固定完整 commit。
  • 迁移现有 7 条作为种子集。

4. tools/radar_scan.py（只做候选发现）

  • 输入：GitHub Search API（近 30 天 language:Python star 增速）、 catalog 内项目的 PyPI 发布、HN/r/Python 高票帖。
  • 输出：catalog/projects/candidates.json——repo 地址、star、最近发布、 license、首次发现日期。不写描述、不定状态。 理由/风险/状态由人工 撰写与选择，遵守 AGENTS.md 与 CURATION_POLICY.md。
  • 只读、限速、不触达私有端点（与 check_links.py 同一约束）。

5. 契约与工具更新

  • schema/content-manifest-v1.schema.json：type 增加 "course" （schema 变更须与 manifest 重新生成、网站 pin 更新在同一次刻意操作中完成）。
  • tools/build_content_manifest.py：像 guides/playbooks 一样遍历 courses/；每个语言文件各算 sha256。
  • 新增 tools/verify_courses.py（对照 verify_examples.py）：检查文件夹 契约——COURSE.md 存在、EN/CN lesson 成对、verify.py 对 starter 预期失败、 对 solution 预期通过。
  • llms.txt / llms-full.txt：增加 courses 与 radar 区块，深链到课程 文件夹与 radar.json。
  • docs/CURATION_POLICY.md：scope 扩展至课程与 radar 条目；写清 ai_familiarity 分级规则。
  • .github/ISSUE_TEMPLATE/：新增 course-feedback.yml（报告授课漂移/ 课节不清/verify 不符），与 project-proposal 并列。
  • GitHub 维护项：仓库描述与 topics 加关键词；发布第一个带版本号的 Release（让 watcher 收到通知，配合网站内容节奏）。

6. 导流改造（按 docs/REPO_TO_WEBSITE.md）

  • README/README_cn 顶部横幅 → https://flypython.com/from-github （只有该路由上线并验证后才切换；之前链根域，遵守该文档自己的规则）。
  • 每个 guide/playbook/example 文末一条情境化链接到对应站内页——延续当前 任务，不做通用横幅。
  • 仓库描述按新定位改写（"AI writes Python; we make it verifiable and deliverable"，最终措辞实施时定）。

7. 执行顺序

  1. courses/ 规范 + verify_courses.py + C1 文件夹（EN+CN）→ manifest/ schema 更新同一次完成。
  2. Radar YAML 迁移 + radar.json 导出 + schema + README 渲染。
  3. radar_scan.py + 第一批候选。
  4. llms 文件、策展政策、issue 模板、仓库描述/topics。
  5. /from-github 线上验证后做 README 导流改造。
  6. 首个课程落地时开始 Releases/tagging 节奏。

8. TODO（编号续接网站规划）

勾选状态于 2026-10-11 对照仓库核对。网站侧的部分（pin、llms-links 测试） 不在本仓库，无法从这里核实，备注中单独说明。

  • FP-325 courses/ 规范写入 AGENTS.md；COURSE.md 授课契约经评审。 （核对：AGENTS.md 内容规则含完整课程文件夹规范；12 门课均有 COURSE.md 与 REVIEW.md）
  • FP-326 C1 课程文件夹完成（3 个场景皮、verify.py 双向、EN+CN、 真实跟课的 REVIEW.md）。（核对：3 个场景皮 api-tool / data-monitor / excel-report、verify.py 双向、EN+CN 均已完成，挑战模式可解性实测已录 REVIEW.md；授课式实机走查仍待做，见该课 REVIEW.md 的 Pending 一节）
  • FP-327 manifest type: "course" + schema + build_content_manifest.py 遍历；网站 pin 更新同一次刻意完成（FP-224 规则）。（核对：manifest schema 含 course 与 path，build_content_manifest.py --check 通过；网站 pin 在网站仓库 src/data/content-pin.json）
  • FP-328 verify_courses.py 进入验证工作流与 Makefile。（核对： make check 执行，CI 的 Validate 即 make check）
  • FP-329 catalog/projects/ 迁为 per-project YAML（迁移 7 条种子）+ render_readmes.py 重生成验证。（核对：7 个 *.yml， render_readmes.py --check 通过）
  • FP-330 radar.json 导出 + schema/radar-v1.schema.json + export_catalog.py 扩展；--check 全绿。（核对： export_catalog.py --check --target both 通过）
  • FP-331 tools/radar_scan.py 合入：限速与"不生成描述"有测试保证。 （核对：tests/test_radar_scan.py 含每来源上限与“候选不带结论字段”测试）
  • FP-332 llms.txt / llms-full.txt 增加 courses+radar 区块；深链有效 （pin 更新后网站侧 llms-links 测试保持绿）。（核对：llms.txt 已有 courses 与 radar 区块；llms-full.txt 由网站提供，本仓库只引用。课程 列表已过时：只列 8 门，缺 hands-on-with-cursor、 hands-on-with-deepseek-harness、hands-on-with-kimi-code、 hands-on-with-zcode，且 courses/hands-on-with-openai-codex-cli/ 深链 失效，实际目录为 courses/hands-on-with-openai-codex/）
  • FP-333 CURATION_POLICY.md scope + ai_familiarity 分级规则； course-feedback.yml issue 模板。（核对：两者均已在仓库中）
  • FP-334 仓库描述/topics/关键词；第一个 GitHub Release。（核对：仓库 描述与 10 个 topics 已设置；v0.1.0 标签于 2026-09-12 打在 e420fca， 首个 GitHub Release 为 v0.1.1，2026-09-14）
  • FP-335 README/README_cn 横幅 + 各文档情境化文末链接，以线上 /from-github 验证为前置。（核对：guides / playbooks / examples 的 文末情境化链接已全部加上；README 横幅链网站根域，未切到 /from-github。 该路由已上线，docs/REPO_TO_WEBSITE.md 允许两种链法，是否切换待所有者决定）
  • FP-344 双许可 LICENSE 就位（MIT 代码 / CC BY 4.0 内容，两仓库同）—— 课程文件夹分发与 FP-326 的前置。（核对：本仓库 LICENSE 已是双许可； 网站仓库未在此核实）
  • FP-350 校验器与 schema 追上政策：validate_catalog.py 与 catalog-v1/radar-v1 支持 Radar 生命周期状态与 ai_familiarity； manifest schema 增加 type: "course"；首个 Release（FP-334）时把 CHANGELOG [Unreleased] 切入 0.1.0 段。（核对：radar-v1 schema 与 tools/catalog.py 校验 6 种生命周期状态与 ai_familiarity，由 export_catalog.py --check 执行；CHANGELOG 已有 [0.1.0] - 2026-09-12）

9. 非目标与风险

  • 本仓库仍是内容/证据源：不做网站功能、不放付费内容、不接分析、 密钥不入库。
  • 课程质量风险：agent 会偏离 COURSE.md——用 verify.py + 有记录的人工 跟课（REVIEW.md）兜底，不用承诺兜底。
  • Radar 产能风险：候选很便宜，审核条目很贵——人工审核是有意保留的 瓶颈，不能省。
  • Pin 纪律：每次 schema/manifest 变更都搭配一次刻意的网站 pin 更新； 永不依赖移动分支。