代码标签扫描与任务创建技能Skill：把散落在代码里的 FIX、NOTE、TODO 一键变成可执行任务
- 一句话定位：
skill-learn是一个在代码库中扫描FIX:、NOTE:、TODO:三类嵌入标签，并通过交互式选择把它们转成结构化任务的 AI 技能，由/learn命令直接调用。 - 核心机制：先扫描、先展示、后创建——用户在任何任务被创建之前，一定先看到完整的标签扫描结果，再通过交互式提示决定创建哪些任务。
- 三种任务类型：修复任务（合并 FIX:/NOTE: 标签）、学习任务（依据 NOTE: 标签更新上下文）、TODO 任务（按 TODO: 项逐条或分组创建）。
- 智能分组：当选中的 TODO 项多于 1 个时，技能会按共享关键术语、文件路径分区与操作类型自动聚类，并让你选择「按主题分组 / 各自独立 / 合并为一个」。
- 落地方式：生成的任务会写入
specs/TODO.md与specs/state.json，并自动执行一次 Git 提交，形成可追踪的任务链路。
1. 该技能叫什么？如何一键安装 AI 技能提升开发效率？
这个技能的中文名是 代码标签扫描与任务创建技能Skill，英文名是 skill-learn，技能 ID 为 12891。它对外暴露的调用入口是 /learn 命令。
它要解决的问题非常具体：开发过程中，我们习惯在代码里随手留下 -- TODO: 待优化、<!-- FIX: 更新文档 -->、# NOTE: 这里依赖旧接口 之类的注释，但这类"埋在代码里的待办"往往永远躺在文件里，既不会被任务系统收走，也不会被排期。skill-learn 做的事情就是把这些嵌入式标签统一扫描出来、结构化展示、并转换成带编号、带语言标记、带工作量估算、可被后续流程消费的任务条目。
「一键安装」的思路在于：AI 技能本质上是"一段可被 AI 客户端识别并调用的能力包"，安装动作通常只需要把技能放入客户端的技能目录或通过技能市场/插件入口启用，而不需要你为项目写配置、装依赖、搭服务。通用步骤建议如下（具体命令与入口以官方说明为准）：
- 确认前置环境：你已经在一个支持 AI 技能（Skill）的客户端中工作；项目是一个 Git 仓库；项目内存在或允许创建
specs/TODO.md与specs/state.json这两个上下文文件（技能会引用它们，但不会在扫描阶段强制加载）。 - 安装技能：通过客户端的技能市场搜索技能英文名
skill-learn，或在技能库中导入技能包，将其启用。安装后该技能会声明自己可用的工具集（Bash、Grep、Read、Write、Edit、AskUserQuestion），这正是它能"扫描 + 交互 + 写文件"的基础。 - 验证是否生效：在对话中输入
/learn并回车。如果技能生效，你会看到两类正常反馈：- 若当前目录下有标签，会出现「标签扫描结果」摘要（扫描的文件、找到的标签总数，以及 FIX:/NOTE:/TODO: 三类的明细）；
- 若没有标签，会出现「未找到标签」的提示并优雅退出，这同样说明技能已被正确加载。
- 小范围试跑：第一次使用时可以指定一个子目录（技能支持从命令参数中解析路径，未指定则默认项目根目录），确认扫描范围与结果符合预期后，再对全仓库执行。
需要注意的是，该技能不再支持 --dry-run 标志，因为它的交互式流程本身就是"先预览再创建"——你永远先看到发现，再决定创建。
2. 该技能的主要功能和特点
- 多语言、按文件类型定制扫描模式：不是无脑 grep 全库，而是按文件类型匹配对应注释语法——Lua 用
-- FIX:、LaTeX 用% FIX:、Markdown 用<!-- FIX:、Python/Shell/YAML 用# FIX:，这三套模式同样适用于NOTE:与TODO:，避免把普通文本误判成标签。 - 结果结构化解析：每条匹配都会被拆解为「文件路径 + 行号 + 标签类型 + 标签内容」，并分别归入
fix_tags[]、note_tags[]、todo_tags[]三个数组，为后续交互提供干净的数据基底。 - 强制先看结果的交互设计：扫描完成后先输出「标签扫描结果」摘要，再进入选择环节。这一点和普通脚本最大的区别是：它把"确认"内建在流程里，而不是事后撤销。
- 按存在性动态生成选项：只有 FIX: 或 NOTE: 存在时才提供「修复任务」；只有 NOTE: 存在时才提供「学习任务」；只有 TODO: 存在时才提供「TODO任务」。没有的选项不会出现在菜单里，减少误选。
- TODO 项的主题聚类：从 TODO 内容中抽取关键术语（忽略停用词），结合文件路径前缀与操作类型（添加/实现 → 实现任务、修复/处理 → 修复任务、文档/更新 → 文档任务、测试/验证 → 测试任务、重构/优化 → 改进任务），按"共享 2 个及以上关键术语"或"共享文件分区 + 操作类型"进行聚类，自动生成主题标签。
- 三种分组策略可选：
grouped（接受建议的主题组，一组一个任务）、separate（每个 TODO 一个任务）、combined（合并成一个任务），由你决定粒度。 - 依赖感知的创建顺序：当 NOTE: 标签存在且你同时勾选了修复任务与学习任务时，技能会先创建学习任务，再创建修复任务并把学习任务编号写入其
dependencies字段，保证"先更新上下文、再动手修"的执行顺序。 - 工作量自动估算：单条 TODO 默认 1 小时；分组/合并模式下按
1 小时 + 30 分钟 × (项目数 - 1)缩放，2 项 1.5 小时、3 项 2 小时，以此类推。修复任务 2-4 小时，学习任务 1-2 小时。 - 语言自动识别：任务会带上语言标记，如
neovim（.lua）、latex（.tex）、markdown（.md）、meta（.claude/* 与学习任务）、general（.py/.sh）。修复任务则按"多数标签来源文件"判断主语言。 - 状态原子更新 + 自动提交：任务编号取自
specs/state.json的next_project_number并递增，TODO.md中新任务插在顶部，最后对这两个文件执行一次 Git 提交，提交信息里带上会话 ID，便于回溯这一批任务的来源。 - 大量 TODO 的批量选择：当 TODO 项超过 20 个时，选项顶部会追加「选择所有（N 项）」，避免你在长列表里逐条勾选。
- 完整的异常兜底：路径无效仅告警并继续；无标签不算错误；
state.json更新失败会尝试两步 jq 模式重试；TODO.md格式损坏则跳过其更新但保留 state 更新；Git 提交失败不阻塞任务创建。
和普通工具相比强在哪？普通的 TODO 高亮插件只能"看见"，不能"收编"；手写 Issue 需要你复制粘贴、补上下文、再手动排期。skill-learn 把「发现 → 归类 → 估时 → 编号 → 写入任务系统 → 提交」串成了一条链，中间只留一个交互确认点。
3. 如何使用该技能？
第一步：准备上下文文件
在项目根目录准备两个文件（技能会引用它们）：
specs/TODO.md：当前任务列表，新任务会插在## 任务区段之前（即列表顶部）；specs/state.json：机器状态，技能需要从中读取next_project_number作为下一个任务编号。
第二步：调用技能并指定扫描范围
直接用 /learn 调用，默认扫描项目根目录；也可以带上路径参数把范围收窄：
/learn # 扫描项目根目录（未指定路径时默认为 "."）
/learn src/ # 只扫描 src 目录
/learn src docs/ # 指定多个路径
技能会解析命令输入中的路径参数，同时在内部生成一个会话 ID（形如 sess_<时间戳>_<随机串>）用于跟踪本次操作。
第三步：阅读标签扫描结果
扫描完成后你会看到类似这样的摘要：
## 标签扫描结果
**扫描的文件**: src/
**找到的标签**: 3
### FIX:标签 (1)
- `docs/KEYMAPS.md:89` - 更新快捷键表，补充新增绑定
### NOTE:标签 (1)
- `src/config/loader.py:12` - 该配置项依赖旧版接口
### TODO:标签 (1)
- `nvim/lua/plugins/telescope.lua:67` - 为工作树添加自定义选择器
如果是空结果，会明确告诉你「未检测到 FIX:、NOTE: 或 TODO: 标签」并退出，不会创建任何东西。
第四步：选择任务类型（多选）
技能会弹出一个多选提示，问题为「应该创建哪些任务类型？」，选项只会出现实际存在的那几种：
- 修复任务：将 N 个 FIX:/NOTE: 标签合并为单个任务；
- 学习任务：根据 N 个 NOTE: 标签更新上下文；
- TODO任务：为 N 个 TODO: 项创建任务。
如果你什么都没选就关闭提示，技能会输出「未选择任务类型。未创建任务。」并优雅退出。
第五步：挑选 TODO 项并决定分组方式
若勾选了「TODO任务」，会进入 TODO 选择环节：每个选项的标签是截断到 50 字符的 TODO 内容，描述是 文件:行号，支持多选；超过 20 项时顶部会出现「选择所有（N 项）」。
选中 2 个及以上 TODO 后，技能会自动聚类主题并再问你一次：
- 接受建议的主题组：例如「创建 2 个分组任务：Telescope 工作树（2 项）、配置优化（1 项）」；
- 保持为单独任务：每个 TODO 一个任务；
- 创建单个合并任务：所有选中项合成一个任务。
第六步：确认创建结果
创建完成后会输出一张汇总表，形如：
| # | 类型 | 标题 | 语言 |
|---|---|---|---|
| 12 | 修复 | 修复来自FIX:/NOTE:标签的问题 | general |
| 13 | 学习 | 根据NOTE:标签更新上下文文件 | meta |
| 14 | TODO | Telescope 工作树: 2个TODO项 | neovim |
随后提示后续动作：在 TODO.md 中审查任务、运行 /research {first_task} 开始，再按 /research -> /plan -> /implement 循环推进。
第七步：理解写入了什么
specs/state.json：新增任务条目（含project_number、project_name（由标题生成的 slug）、status: not_started、language，必要时含dependencies），并递增next_project_number；specs/TODO.md：新任务以### {N}. {标题}形式插入，附带努力、状态、语言、开始时间戳与描述；有依赖的修复任务会额外列出「依赖: 学习任务编号」；- Git：对上述两个文件执行一次提交，提交信息包含创建任务数与会话 ID。
还有一个容易被忽略的细节：生成的修复任务描述里会明确要求——执行修复时，从源文件中移除 FIX: 和 NOTE: 标签，但保留 TODO: 标签（它们由 TODO 任务单独处理）。这让"标签清理"成为任务的一部分，而不是靠人记。
4. 同类型竞品对比分析
| 方案名称 | 定位 | 核心功能 | 安装/使用门槛 | 适用场景 | 优势与不足 |
|---|---|---|---|---|---|
| skill-learn（代码标签扫描与任务创建技能） | 把代码内嵌标签转成结构化任务的 AI 技能 | 多语法标签扫描、交互式任务类型选择、TODO 主题聚类、三种分组模式、依赖感知创建、自动写 state/TODO 并提交 | 需支持 AI 技能（Skill）的客户端；需准备 specs/state.json 与 specs/TODO.md；通过 /learn 调用 |
已有 FIX:/NOTE:/TODO: 注释习惯的工程仓库、个人或小团队的项目治理 |
优势：发现到创建一条链、估时与编号自动化、分组智能；不足：依赖特定客户端与目录约定，外部依赖（TODO 任务依赖既有任务）尚未实现，且不提供可视化 |
| 编辑器 TODO 高亮插件（如 TODO Tree 一类） | 编辑器内的标签聚合与导航 | 高亮、侧边栏树状汇总、快速跳转 | 在编辑器中安装插件即可，几乎零门槛 | 个人阅读代码时快速定位待办 | 优势：轻量、即时；不足：只"看得见"不"收得走"，不生成任务、不估时、不排序，也没有交互式确认流程 |
| GitHub Issues / Jira 等任务系统 | 团队级任务与进度管理 | 工单、看板、指派、里程碑、报表 | 需要账号、项目空间与流程约定，团队协作成本较高 | 多人协作、需要对外可见的排期 | 优势：协作能力强、可追溯；不足：代码里的标签不会自动流入，需人工复制粘贴补上下文，标签与工单长期"两张皮" |
| 自写 grep 脚本 + 手工建任务 | 最朴素的自建方案 | 正则匹配、输出文本 | 需要自己写脚本、自己维护正则与路径 | 一次性排查、临时清点 | 优势：完全可控、无额外依赖；不足：无交互、无分组、无估时、无状态文件更新，格式一变就失效，长期维护成本高 |
如何选？如果你只是想在编辑器里"看见"待办，插件足够；如果团队需要正式工单与排期，任务系统仍是主战场。而 skill-learn 的价值在两者之间——它把代码里的隐性待办低成本地转成任务系统能消费的显性条目，并且整个过程只需要一次交互确认。
5. 该技能的典型应用场景与实际体验情况
场景一：长期维护的配置仓库（Neovim / dotfiles）
角色：个人开发者。痛点：nvim/lua/ 下堆着各种 -- TODO: 加个预览窗口、-- FIX: 处理边界，几个月后再看已经想不起上下文。使用方式：在仓库根目录执行 /learn nvim/，技能会按 Lua 的 -- TODO: 模式精确匹配，展示所有条目，然后勾选「TODO任务」，技能把同一插件目录下、共享"工作树""telescope"等术语的条目聚成「Telescope 工作树」组，一次生成一个 1.5 小时估算的任务。实际体验：识别准确率高，因为按注释语法匹配，几乎不会误抓代码字符串；分组结果通常比人工归类更整齐。
场景二：论文 / LaTeX 项目的修改清单
角色：学术写作者。痛点：审稿意见散落在 % FIX: 和 % NOTE: 注释里，容易漏改。使用方式：/learn paper/，FIX: 与 NOTE: 会被合并成一个「修复任务」（2-4 小时），同时因为存在 NOTE:，学习任务 选项会出现，勾选后技能先创建学习任务，再让修复任务依赖它。实际体验：这种"先学习、后修复"的顺序对论文类项目特别契合——先更新上下文，再动笔修改，避免改完发现理解偏了。注意点：任务描述里会要求处理时移除 FIX:/NOTE: 标签，如果你希望保留审稿痕迹，需要在执行阶段自行调整。
场景三：多人仓库的 TODO 清点与排期
角色：技术负责人。痛点：想快速知道仓库里还有多少待办、分别落在哪些模块。使用方式：/learn 全库扫描，先看「标签扫描结果」的三段统计，再决定是否创建。若 TODO 超过 20 项，用「选择所有」一次性纳入，然后选择「创建单个合并任务」或「接受建议的主题组」。实际体验：摘要本身就是一份轻量的仓库健康度快照；创建后 TODO.md 顶部会多出带编号的新条目，state.json 的 next_project_number 同步递增，接着靠 Git 提交留痕，回溯"这批任务是哪次扫描产生的"非常方便，因为提交信息里带了会话 ID。
场景四：基于 NOTE: 标签的知识沉淀
角色：接手他人项目的开发者。痛点：代码里很多 # NOTE: 记录了"这里为什么这么写"，但这些知识没有沉淀到上下文文档。使用方式：只勾选「学习任务」，技能会生成「根据 NOTE: 标签更新上下文文件」的任务，语言标记为 meta，估算 1-2 小时。实际体验：这是该技能比较独特的一条路径——它把注释当成知识源而不是待办源。注意点：学习任务的前提是 NOTE: 标签存在，没有 NOTE: 时该选项根本不会出现。
整体上手难度与注意事项：上手难度低，核心就一个 /learn，剩下的都是选择题。需要留意三点：一是 specs/state.json 与 specs/TODO.md 的约定要提前满足，否则任务编号读取或写入可能失败（技能会报告部分成功）；二是无标签时它会静默退出，这是设计而非故障；三是 --dry-run 已不再支持，预览能力由交互流程本身承担。
6. 该技能能为用户带来的价值
- 把"隐性待办"变成"显性资产"：代码里的
FIX:/NOTE:/TODO:标签从"作者自己知道"变成带编号、带文件行号引用的任务条目，团队任何人打开TODO.md都能看到全貌。 - 省掉一轮机械劳动：过去把标签转成任务是"grep → 复制 → 粘贴 → 补上下文 → 编号 → 填估时"五六步手工操作，现在压缩成一次
/learn加几个选择。按每个标签节省 2-3 分钟计算，一个 30 条标签的中型仓库，单次清点就能省下 1 小时左右的纯手工整理时间。 - 降低任务管理门槛：不需要学任务系统的字段规范，工作量估算（1 小时基线 + 每多一项加 30 分钟）、语言标记、依赖关系都由技能按规则生成，小团队和个人项目也能拥有接近正规流程的任务结构。
- 提升执行顺序的正确性：NOTE: 依赖机制让"先更新上下文、再动手修"成为默认路径，减少"理解错了返工"的概率——这是纯工具类方案给不了的收益。
- 让清理有始有终：修复任务的描述里明确要求处理完移除
FIX:/NOTE:标签，标签不会越积越多，代码库的"注释债务"是可控的。 - 可追溯、可协作：每次创建都伴随一次 Git 提交，会话 ID 写进提交信息，配合
/research -> /plan -> /implement的后续循环，任务从"被记下来"到"被做完"形成闭环。
7. 常见问题 FAQ
Q1：这个技能怎么安装、怎么调用？
安装方式取决于你使用的 AI 客户端，通常是通过技能市场搜索英文名 skill-learn 启用，或把技能包导入技能目录，具体命令与入口以官方说明为准。调用入口是 /learn，可以不带参数（默认扫描项目根目录），也可以带路径参数（如 /learn src/）收窄范围。
Q2：这个技能收费吗？
技能本身是否收费取决于你获取它的渠道与客户端授权，以官方说明为准。它不需要你额外部署服务或购买第三方依赖，运行时会调用你本地已有的工具（Bash、Grep、Read、Write、Edit）以及客户端的交互式提问能力。
Q3：适合谁用？
适合三类人：一是有在代码里写 FIX:/NOTE:/TODO: 注释习惯的个人开发者，尤其是配置仓库、脚本库、论文 LaTeX 项目的维护者；二是需要快速清点仓库待办的技术负责人；三是接手他人项目、想把 NOTE: 里的知识沉淀成上下文文档的开发者。如果你从不写这类标签，它扫描不到东西，价值有限。
Q4：它会直接改我的代码、删掉我的标签吗？
不会。扫描阶段它只读文件；创建阶段它只写 specs/state.json、specs/TODO.md 并做一次 Git 提交。标签的移除是写进修复任务描述里的执行要求（处理时移除 FIX:/NOTE:、保留 TODO:），由后续执行任务的流程来完成，而不是技能在扫描时动手。
Q5：和编辑器里的 TODO 高亮插件怎么选？
如果你只需要"看见"和跳转，插件更轻；如果你需要把标签变成带编号、带估时、带依赖关系的任务条目，并自动同步到任务清单和 Git 历史，skill-learn 更合适。两者并不冲突：日常阅读用插件，阶段性清点与排期用 /learn。需要注意它对仓库结构有约定（specs/state.json、specs/TODO.md），且暂未实现 TODO 任务对既有任务的外部依赖，也未提供可视化视图。