| name | asco-includes |
| description | 为 ASCO 仓库清理头文件依赖与 include 顺序。用于删除多余 include、补齐缺失的直接依赖，并按项目既有顺序规范整理 include 块；未指定范围时默认处理用户当前打开的 C++ 源文件，默认只做局部诊断，不主动构建或跑测试。 |
| argument-hint | 说明要清理的范围（默认是用户当前打开的 C++ 源文件），是否只清理头文件，还是同时清理对应实现文件的 include，是否只分析不改动 |
清理 ASCO 头文件依赖与 include 顺序
何时使用
- 需要删除多余的 include。
- 需要补齐当前文件直接使用、但只是靠传递包含碰巧可见的声明或定义。
- 需要整理 ASCO 仓库中的 include 顺序与分组。
- 需要回答“这个文件缺哪些 direct include”或“哪些 include 可以安全删除”。
目标产出
- 针对指定范围内的文件，删除未直接使用的 include。
- 为直接使用的类型、函数、模板、宏、常量和标准库符号补上显式依赖。
- 不因为别的头碰巧传递包含了某个依赖，就把当前文件对该依赖的 direct include 误判为冗余。
- 让 include 顺序符合当前仓库的既有模式，而不是临时发明一套新规则。
- 在用户没有明确要求时，不主动运行构建、测试或大范围验证命令。
输入信息
开始前先确认这些信息；如果它们会影响当前任务但缺失，再向用户确认：
- 清理范围是当前打开的 C++ 源文件、单目录，还是整个模块。
- 只清理头文件，还是同步清理对应
.cpp / 平台实现文件。
- 用户是要实际改动，还是只要分析和建议。
- 是否需要遵守当前仓库已有的 include 顺序规范，而不是只做最小依赖修补。
如果用户没有明确指定范围，默认把“用户当前打开的 C++ 源文件”当作起点，而不是默认扩大到整个目录或整个模块。
如果用户明确点名了某个文件，默认只清理那个文件本身；除非用户明确要求，或该文件的局部验证必须借助最近消费者/对应实现文件做消歧，否则不要自动扩到相邻文件。
仓库事实
- 公开 API 头文件位于
asco/ 下，运行时内部实现主要位于 asco/core/。
asco/core/ 下的改动属于运行时语义附近的改动；即使只是 include hygiene，也不要让修改越过当前问题范围。.clang-format 目前配置了 IncludeBlocks: Preserve 和 SortIncludes: true。- 从当前仓库已有文件可观察到的 include 组织方式是：
.h 文件通常先放标准库头；如果存在第三方库头，则放在标准库头和系统头之后、项目内头之前；最后再放项目内头。.cpp 文件通常先放对应的主头，再空一行，再放标准库头；如果存在系统头，则放在标准库头之后；如果存在第三方库头，则放在标准库头和系统头之后、项目内头之前；最后再放项目内头。- 若只有一组 include，则保持单组，不强行制造空行。
- 不要修改
build/ 下的生成文件。
决策规则
1. 先从最近的锚点开始
- 优先从用户当前打开的 C++ 源文件开始；如果用户明确点名了别的文件，则改用用户指定文件，并默认只处理该文件本身。
- 若当前打开文件不是 C++ 源文件，再退回到用户当前文件、明确点名的文件、或最邻近的实现/声明对。
- 不要先做全仓扫描再决定；先在局部找出一个可证伪的 include 问题再动手。
2. 只按“直接使用”判断依赖
- 只要当前文件直接写到了某个符号，就应优先让它显式包含该符号所需的头。
- 不要因为“别的头也会带进来”就省略 direct include。
- 如果当前文件直接使用了某个符号，即使另一个已包含的头也会把该符号顺带带进来，这个 direct include 仍然不是冗余。
- 只有当当前文件没有直接用到某个头提供的任何符号时，才应优先考虑删除它。
3. 头文件和实现文件分开处理
.h 里优先关注对外暴露的成员类型、返回值、参数、基类、模板约束、内联实现和标准库成员。.cpp 里优先关注实现体直接调用的函数、异常类型、std::move / std::forward / placement new 之类常见漏项。- 不要把“头文件补 direct include”和“实现文件移除冗余 include”混成一次大范围改动；按文件或小片段分批做。
4. include 顺序必须跟仓库现状一致
- 对
.cpp：对应主头优先放第一位。
- 然后是标准库头。
- 若文件需要平台或系统头，例如
windows.h、pthread.h、sched.h、ncurses.h 这类头，则单独作为一组，放在标准库头之后。
- 若文件需要第三方库头，则单独作为一组，放在标准库头和系统头之后、项目内头之前。
- 最后是项目内头。
- 对
.h：标准库头在前；若有系统头和第三方库头，则第三方库头位于标准库头和系统头之后、项目头之前；项目内头仍在最后。
- 各组内遵循当前仓库已有排序习惯；不要引入和现有文件风格冲突的分组规则。
5. 验证默认保持局部、低成本
- 默认先做文件级诊断或最邻近消费者诊断。
- 如果用户没有明确要求，不主动跑全量构建、测试或格式化。
- 当单文件诊断被 PCH、平台专属文件或已知噪音污染时，改用最近的消费文件做消歧检查。
执行流程
1. 锁定一个小范围目标
- 默认先读取用户当前打开的 C++ 源文件和最多一两个紧邻文件。
- 如果用户明确点名了某个文件，默认先只读取该文件；只有在局部验证或依赖判断确实需要时，才补读最多一两个紧邻文件。
- 只有当用户明确要求目录级或模块级清理时，才从单文件扩到更大范围。
- 先说清楚当前的局部判断：
- 哪个 include 像是冗余。
- 哪个符号像是缺 direct include。
- 下一步用什么最低成本检查来证伪。
2. 先做最小改动
- 优先先补 direct include，因为这类修改最不容易改变行为。
- 删除 include 时，只删当前文件中确实没有直接用途、并且不是仅靠传递包含“误看起来可删”的那条。
- 一次只改一小批高度相关的文件。
3. 立即做局部验证
- 每次 substantive edit 后，先做一次最近范围的诊断检查。
- 如果诊断直接指出“新加的头未使用”，先撤回那一条，再复查。
- 如果诊断被缓存、PCH 或平台噪音污染，不要扩大范围；改查最近消费者或同一实现面上的邻近文件。
4. 处理平台和环境噪音
- 在 Windows 环境下看到 Linux 专属源文件报找不到
pthread.h、sched.h 之类问题时，视为平台噪音，不把它误判成这次 include 改动引入的问题。
- 同理，如果某个头的单文件诊断持续报缓存或 PCH 问题，应改用其最近消费者验证，而不是继续在该头上盲目来回修改。
5. 完成一轮后再扩范围
- 只有当前这一轮文件级修改和局部验证都闭环后，才扩到相邻目录或相邻模块。
- 推荐的扩展顺序是：当前文件 -> 同目录同抽象层 -> 最近消费者/实现文件 -> 相邻模块。
完成标准
满足以下条件才算完成：
- 指定范围内新增的 include 都是当前文件直接使用所需。
- 当前文件中每一个直接使用的符号，都能在当前文件的 include 列表里找到对应的 direct include，而不是只依赖传递包含。
- 删除的 include 都能用局部阅读和局部诊断自洽解释，并且不会删除那些只是被其它头“碰巧带进来”后看起来可删、但实际上仍承载 direct dependency 的 include。
- include 顺序符合当前仓库实际使用的分组方式：
.cpp 对应头优先、标准库其次、系统头位于标准库头之后、第三方库头位于标准库头和系统头之后且项目头之前、项目头最后；.h 先放标准库头，再按需要放系统头和第三方库头，项目头仍在最后。
- 没有顺手修 unrelated 的语义问题或大规模重排。
- 已提醒用户不要盲目相信结果，尤其是
asco/core、并发、取消、生命周期和资源释放路径附近的改动。
常见分支
用户只要分析，不要改动
- 只指出冗余 include、缺失 direct include 和顺序问题。
- 不实际编辑文件。
用户只说“继续”或没有给范围
- 默认继续清理用户当前打开的 C++ 源文件。
- 只有当前文件已经闭环，或用户明确要求扩范围时，才扩到相邻实现文件、同目录或相邻模块。
用户明确点名某个文件
- 默认只清理这个文件。
- 不要自动顺手清理对应
.cpp、对应头文件、同目录文件或相邻模块。
- 只有当缺失 direct include 的判断或局部验证无法在单文件内完成时，才临时读取最近邻文件做消歧；读完后仍然只修改用户点名的文件，除非用户明确要求扩范围。
用户只要清理头文件
- 先处理
.h 文件。
- 只有当头文件清理暴露出某个
.cpp 正在依赖传递包含时，才补对应 .cpp 的 direct include。
单文件诊断结果不可信
- 优先检查最近消费者或对应实现文件。
- 明确标注这是 PCH / 平台 / Problems 面板噪音，不把它当成新增回归。
目录级批量清理
- 仍然按文件分批推进。
- 每一小批改动后都做局部诊断，不要一口气扫完整个仓库再统一收尾。
风险提醒
- 即使只是 include hygiene，
asco/core、调度、取消、生命周期、并发和资源释放路径附近的修改也必须由用户自行核对语义、边界条件和失败路径。
- 不要因为“只是删 include”就假设绝对安全；特别要警惕内联实现、模板约束、平台专属文件和协程相关声明的依赖边界。
推荐提示词
- 清理我当前打开的 C++ 源文件，删掉多余 include，补齐缺失的 direct include，并保持 ASCO 的 include 顺序。
- 只分析这个目录里哪些头在依赖传递包含，不要实际改动。
- 继续按前面的方式清理
asco/core/task，每次只做一小批并先做局部诊断。
- 帮我把这个
.cpp 的 include 顺序整理成项目现有规范，并补齐 std::move、异常类型、placement new 之类的直接依赖。
