Skip to content

Commit 0e9606b

Browse files
cursoragentxxg1413
andcommitted
docs: record the FP-414 Skill packaging evaluation and close FP-332/FP-335
Keep the single website-hosted Skill instead of per-course skills. The reference validator (skills-ref 0.1.1) flags two spec violations in the live Skill, and its uv run advice for pandas courses contradicts the course setup; both are website-side fixes. Mark FP-332 and FP-335 done now that llms.txt and the README calls to action are fixed. Co-authored-by: P小二 <xxg1413@gmail.com>
1 parent f1d65ed commit 0e9606b

2 files changed

Lines changed: 70 additions & 15 deletions

File tree

‎docs/repo-plan-0.0.3.md‎

Lines changed: 10 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,8 @@
1313
当前产品形态。本文件按所有者决策以中文保留。
1414
关联:flypython.com `docs/product-and-growth-plan-0.0.3.md`
1515

16-
状态:已基本实现(2026-10-11 核对)。§8 中 FP-326、FP-332、FP-335 仍有
17-
未完成部分,见各项备注;其余各项已在仓库中落地。本计划遵守 `AGENTS.md` 的
16+
状态:已基本实现(2026-10-11 核对)。§8 中只有 FP-326 仍有未完成部分
17+
(旗舰课的授课式实机走查),见该项备注;其余各项已在仓库中落地。本计划遵守 `AGENTS.md` 的
1818
仓库边界:本仓库负责已审核内容、可运行证据与稳定 JSON 契约;网站负责展示与
1919
转化。所有新内容中英文同步产出。
2020

@@ -168,22 +168,21 @@ risk: "…"
168168
`export_catalog.py --check --target both` 通过)
169169
- [x] FP-331 `tools/radar_scan.py` 合入:限速与"不生成描述"有测试保证。
170170
(核对:`tests/test_radar_scan.py` 含每来源上限与“候选不带结论字段”测试)
171-
- [ ] FP-332 llms.txt / llms-full.txt 增加 courses+radar 区块;深链有效
171+
- [x] FP-332 llms.txt / llms-full.txt 增加 courses+radar 区块;深链有效
172172
(pin 更新后网站侧 llms-links 测试保持绿)。(核对:`llms.txt` 已有
173-
courses 与 radar 区块;`llms-full.txt` 由网站提供,本仓库只引用。**课程
174-
列表已过时**:只列 8 门,缺 `hands-on-with-cursor`、
175-
`hands-on-with-deepseek-harness`、`hands-on-with-kimi-code`、
176-
`hands-on-with-zcode`,且 `courses/hands-on-with-openai-codex-cli/` 深链
177-
失效,实际目录为 `courses/hands-on-with-openai-codex/`)
173+
courses 与 radar 区块;`llms-full.txt` 由网站提供,本仓库只引用。
174+
2026-10-11 补齐此前缺的 4 门工具课,修正失效的 Codex 课程深链,并新增
175+
`tests/test_llms_txt.py`:列出的路径必须存在,每门课都必须列出)
178176
- [x] FP-333 `CURATION_POLICY.md` scope + `ai_familiarity` 分级规则;
179177
`course-feedback.yml` issue 模板。(核对:两者均已在仓库中)
180178
- [x] FP-334 仓库描述/topics/关键词;第一个 GitHub Release。(核对:仓库
181179
描述与 10 个 topics 已设置;`v0.1.0` 标签于 2026-09-12 打在 `e420fca`,
182180
首个 GitHub Release 为 `v0.1.1`,2026-09-14)
183-
- [ ] FP-335 README/README_cn 横幅 + 各文档情境化文末链接,以线上
181+
- [x] FP-335 README/README_cn 横幅 + 各文档情境化文末链接,以线上
184182
`/from-github` 验证为前置。(核对:guides / playbooks / examples 的
185-
文末情境化链接已全部加上;README 横幅链网站根域,**未切到 `/from-github`**。
186-
该路由已上线,`docs/REPO_TO_WEBSITE.md` 允许两种链法,是否切换待所有者决定)
183+
文末情境化链接已全部加上。2026-10-11 确认 `/from-github` 返回 200 后,
184+
英文 README 的两处“继续前往”链接改为 `/from-github`;该页暂无中文版,
185+
中文 README 仍链根域,规则记录在 `docs/REPO_TO_WEBSITE.md`)
187186
- [x] FP-344 双许可 LICENSE 就位(MIT 代码 / CC BY 4.0 内容,两仓库同)——
188187
课程文件夹分发与 FP-326 的前置。(核对:本仓库 `LICENSE` 已是双许可;
189188
网站仓库未在此核实)

‎docs/repo-plan-0.0.4.md‎

Lines changed: 60 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,12 +9,12 @@
99
更新日期:2026-09-12(第 3 版——挑战模型定稿 + A/B 阶段拆分;状态说明核对于 2026-10-11)
1010
关联:flypython.com `docs/product-and-growth-plan-0.0.4.md`
1111

12-
状态(2026-10-11 核对):除 FP-414 外本计划已实现。之后 2026-09-16 的
12+
状态(2026-10-11 核对):本计划已实现,FP-414 评估记录见 §9。之后 2026-09-16 的
1313
learner verifier v2 把认领入口从 `progress --json` 换成 `check --json` +
1414
`--attest`,`progress --json` 只保留给旧版签名回执(见 CHANGELOG)。真实
1515
Agent 可解性试跑已于 2026-09-13 完成(Devin, SWE-2 Max,当时全部 8 门课,
16-
挑战模式实测记录见各课 `REVIEW.md`)。仍未完成两项:FP-414(SKILL.md 打包
17-
评估);授课式实机走查,目前 9 门课的 `REVIEW.md` 仍列为 Pending,属于发布
16+
挑战模式实测记录见各课 `REVIEW.md`)。仍未完成的是授课式实机走查:目前
17+
9 门课的 `REVIEW.md` 仍列为 Pending,需要维护者在各目标工具里实跑,属于发布
1818
证据,不阻塞内容。`AGENTS.md` 的仓库边界不变:
1919
本仓库拥有经审核的内容、可运行的证据与稳定的 JSON 契约;网站拥有呈现、
2020
账号体系与转化。所有新内容中英同一次变更交付。
@@ -136,7 +136,9 @@ Agent 可解性试跑已于 2026-09-13 完成(Devin, SWE-2 Max,当时全部
136136
- [x] FP-413 供网站渲染的结构化徽章元数据。(本地 2026-09-12:全部
137137
8 门课 `COURSE.md`/`COURSE_cn.md` frontmatter 增加 `badge`(id、
138138
name_en、name_zh、requires)与 `course_id`)
139-
- [ ] FP-414 SKILL.md 打包评估,附书面记录。
139+
- [x] FP-414 SKILL.md 打包评估,附书面记录。(2026-10-11:见 §9。结论是
140+
不按课程打包,保留网站单一平台 Skill;线上 Skill 有两项规范不合规和一条
141+
依赖安装说明需网站侧修正)
140142
- [x] FP-415 `verify_courses.py` 认领码覆盖进 CI。(本地 2026-09-12:
141143
进度契约检查——双运行确定性、JSON 结构、5 检查点、码格式——已入
142144
验证器并随 `make check`/validate.yml 执行)
@@ -248,3 +250,57 @@ FP-409 渲染消费,网站侧不手抄定义。
248250
3. `paths/foundation/`(复用现有课,最快可见)
249251
4. `da-eda` / `da-visualization` / `da-report` 新课 + `paths/data-analysis/`
250252
+ M0 入门模块
253+
254+
## 9. FP-414 评估记录:把课程打包为 SKILL.md skill(2026-10-11)
255+
256+
起草:Cursor Cloud Agent。结论由所有者合并本节时确认。原计划提到的
257+
OpenMAIC 本次未评估。
258+
259+
### 9.1 现状
260+
261+
- 网站已发布一个覆盖全部课程的平台级 Skill:
262+
`https://flypython.com/skills/flypython/SKILL.md`(`name:
263+
flypython-challenges`,0.1.0,2026-09-14)。它负责一次性授权链接、按课程
264+
拉取文件清单、先读 `TASK.md`、人在回路关卡、`python verify.py` 与
265+
`--attest`、批量提交认领码。0.0.8 起它是课程主入口,0.0.9 起工具课第 1 课
266+
把安装它列为可选但推荐。
267+
- 课程文件夹本身已能单独运行(0.0.8 FP-821:单个文件夹取出即可
268+
`python verify.py`)。
269+
- 格式依据:Agent Skills 规范 <https://agentskills.io/specification>。
270+
271+
### 9.2 方案对比
272+
273+
| 方案 | 做法 | 判断 |
274+
| --- | --- | --- |
275+
| A. 每门课一个 skill | 12 个 `SKILL.md`,把 `COURSE.md` / `TASK.md` 写进正文或 `references/` | 不做。与课程文件重复且要中英两份同步;12 个几乎相同的 `description` 在 Agent 启动时都会加载(规范的渐进加载第 1 层),容易触发错课;若把 `starter/` / `solution/` 一起打包,等于把答案交给 Agent |
276+
| B. 单一平台 Skill(现状) | 网站一个 Skill,课程文件按固定提交从 API 拉取 | 保留。一处维护,课程契约仍只在本仓库 |
277+
| C. 本仓库另做离线 skill | 无账号、无认领,只读 clone 下来的文件夹并跑 `verify.py` | 不做。README 与 `COURSE.md` 已能让 Agent 直接开跑,多一个入口只会分流和漂移 |
278+
279+
### 9.3 试点记录
280+
281+
- 用规范的参考校验器 `skills-ref` 0.1.1(`agentskills validate`)校验线上
282+
Skill,两项不合规:
283+
1. frontmatter 含规范外字段 `version`、`updated`。规范只允许 `name`、
284+
`description`、`license`、`compatibility`、`metadata`、`allowed-tools`,
285+
版本信息应放进 `metadata`。
286+
2. `name: flypython-challenges` 与 Skill 自己给 Claude Code 的安装目录
287+
`.claude/skills/flypython/` 不一致;规范要求 `name` 与父目录同名。
288+
- Skill 的 Environment notes 建议 pandas / matplotlib 课程用
289+
`uv run python verify.py`。课程文件夹没有 `pyproject.toml`,这条命令不会安装
290+
`requirements.txt` 中的依赖,与本仓库 2026-10-04 对 `da-eda` /
291+
`da-visualization` 的修正(改为 venv + `pip install -r requirements.txt`)不一致。
292+
- Skill 的 Cursor 安装行把它写成规则文件 `.cursor/rules/flypython.mdc`,
293+
而不是 skill 目录;需要网站侧按 Cursor 当前文档核实应放在哪里。
294+
- Skill 描述的课程侧契约(`TASK.md`、`python verify.py`、`--attest ID`、
295+
`check --json`、旧版 `progress --json` 只用于签名回执)与本仓库 learner
296+
verifier v2 一致。
297+
- 未做:没有在 Claude Code、Codex 等外部工具里实际安装 Skill 并跑完一门课
298+
(本次环境没有这些工具)。以上结论基于规范、校验器和线上文件。
299+
300+
### 9.4 结论
301+
302+
- 不按课程打包 skill,也不在本仓库另做离线 skill;保持网站单一平台 Skill。
303+
- Skill 归网站仓库,需在网站侧修正:把 `version` / `updated` 移进
304+
`metadata`;统一 `name` 与安装目录;pandas / matplotlib 课程的运行说明改成
305+
与课程 `requirements.txt` 一致的 venv + pip;核实 Cursor 安装位置。
306+
- 本仓库无需为 FP-414 增加文件。

0 commit comments

Comments
 (0)