asco-includes

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 之类的直接依赖。