academic-army 0.1.0

package/metaskills/academic-army-coding-style/METASKILL.md

@@ -0,0 +1,292 @@
+这个skill是通用代码质量与框架整理skill，不再负责初始化模板代码库；初始化模板代码库由另一个专门skill完成。
+这个skill的核心功能是让agent在写代码、改代码、补功能、重构代码、实现harness/test、接入method、接入baseline、整理repo结构或维护实验系统时，产出简洁、规整、可读性强、易维护、低耦合、易扩展的代码。
+这个skill会在多种任务中被调用；不管上游任务是什么，只要涉及写代码、改代码、移动模块、拆分文件、补测试、实现harness、接入method、改结果导出或整理framework，就应遵循这个skill。
+上游任务决定“要实现什么功能”；本skill决定“怎么写得简洁、规整、可读、低耦合、可维护”。
+
+本skill不输出“初始化仓库模板”，不从空目录生成完整项目骨架，不重新定义仓库根结构，不替代初始化模板skill。
+本skill在已有代码库、已有框架或当前任务上下文中，指导agent如何写出清晰代码、整理局部结构、拆分模块、维护harness/test、更新文档和保持framework一致性。
+本skill可以在已有代码库基础上继续拆分子文件夹、移动局部模块、补充局部结构和整理framework，但这些操作应服务于当前功能的清晰实现，而不是重新生成整套模板仓库。
+所有新增或修改都应发生在当前任务允许的已有repo范围内；不应在repo外创建、修改或引用项目文件。
+当前目录中的无关文件、历史草稿、日志、旧运行结果和其他噪声不应进入代码设计。
+
+## 和初始化仓库skill的边界
+
+初始化模板代码库skill负责从零创建基础repo结构、固定目录、初始文档和基础框架。
+本skill负责在已有repo上持续保证代码质量、可读性、模块粒度、change locality、harness/test局部结构和framework文档一致性。
+本skill不应包含“创建初始模板仓库”的流程，不应假设自己要从空目录生成完整项目骨架。
+本skill可以创建新文件、新模块或新子文件夹，但前提是当前代码修改、功能实现、harness/test组织或framework整理确实需要。
+本skill创建的文件夹应来自当前功能的自然模块边界，而不是来自预设模板。
+如果已有初始化skill已经创建了`data/`、`output/`、`results/`、`harness/`、`README.md`、`FRAMEWORK.md`和`FRAMEWORK.zh-CN.md`，本skill应在这些既有约定上继续工作，而不是重新定义仓库根结构。
+`data/`、`output/`、`results/`和`harness/`仍然作为固定实验目录保留；测试文件的物理路径不固定，应遵守初始化模板代码库或已有repo中已经采用的测试组织方式。
+如果当前repo已有自己的结构，本skill应尊重既有结构和项目惯例；只有当现有结构影响可读性、局部修改能力或harness/test组织时，才做局部整理。
+如果已有repo没有某个初始化模板约定，本skill不应为了补齐模板而强行创建；只有当前任务需要该结构时才新增。
+
+## 通用代码写作原则
+
+agent写代码时应优先保证代码清晰、直接、可读，而不是为了显得“工程化”引入不必要抽象。
+代码应短、直、少层级；能内联就内联，能简化就简化，能直接传递就不要转换，能删除无意义helper就删除无意义helper。
+代码应让数据流一眼可见：输入从哪里来，如何被处理，传给哪里，输出什么，应尽量顺着代码结构直接读出来。
+代码不应比必要更复杂；如果一个实现已经能清楚表达需求，不应再包装一层来制造架构感。
+代码应使用语义明确的命名，使函数、模块、变量、harness、test、artifact和配置项的用途尽量从名称中直接看出来。
+每个函数、类、模块或文件应有清晰职责；如果一个单元同时承担多个不相关职责，应拆分。
+复杂逻辑应拆成可理解的子功能，子功能之间通过明确输入输出连接。
+不应生成过长、过重、职责混杂的文件；如果一个文件包含多个变化原因、多个抽象层级或多个执行流程，应拆成更小的语义模块。
+拆分模块的目标是提升可读性和change locality，不是制造大量空壳文件、薄wrapper或纯转发层。
+如果一个抽象只让调用方代码更长、更绕、更难测，就应简化或取消。
+如果某段代码会让其他地方为了调用它而写大量样板代码，应重新设计接口，使调用方更短、更自然。
+代码应尽量减少全局状态、隐藏路径假设、隐式副作用和跨模块耦合。
+稳定上下文可以收敛到清晰的数据结构、config object、run context或显式参数中，但不要因此引入过重框架。
+代码应避免把论文图表转换、临时实验脚本、核心系统逻辑、harness逻辑和功能测试逻辑混在一起。
+代码应贴近当前repo已有模式，但不要复制已有代码中的坏抽象、坏命名和历史包袱。
+遇到复杂代码时，优先判断哪些结构可以删除、内联、移动到使用点、重新命名或拆成更自然的子模块。
+
+## 抽象与接口
+
+抽象必须有真实语义价值；没有复用价值、边界价值、不变量价值或测试价值的抽象应删除。
+只有真正复用、表达稳定不变量、定义清晰边界、隔离变化点或显著提升局部可读性时，才抽成独立helper、接口、adapter、registry或runner。
+不要创建只负责转手、改名、包装、拆包或重新组装数据的helper。
+不要创建“拆开又合上”的中间结构；如果数据最终仍作为整体使用，应保留直接的数据流。
+不要为了未来可能扩展而提前引入复杂结构；当前简单结构能表达清楚时，就保持简单。
+条件分支只保留真实必要的业务分支，不为想象中的未来情况提前增加分支。
+技术债清理应优先删除不必要结构，而不是再加一层适配器。
+对每个核心抽象，例如registry、adapter、factory、config object、runner、pipeline、plugin interface，skill应评估它带来的收益和代价：是否减少重复实现，是否缩短调用方代码，是否让method替换更清晰，是否让harness更容易运行，是否让测试更简单。
+如果某个抽象会导致大量样板代码，例如每新增一个method都要改多个注册点、写多个配置块、补多个wrapper，skill应考虑更直接的设计。
+如果某个接口设计会让所有调用方都需要传入过多参数，skill应考虑把稳定上下文收敛到配置对象、run context或明确的数据结构中，但不要因此引入过重框架。
+如果某个配置系统会让简单实验必须写大量配置文件，skill应考虑更轻量的默认值、局部覆盖或命令行参数语义。
+如果某个模块拆分会导致大量跨模块转发函数、薄wrapper或只调用一次的抽象层，skill应合并或简化这些模块。
+如果某个设计会让test脚本和harness脚本为了调用核心逻辑而写大量准备代码，skill应改进入口和接口，使测试和harness能够直接表达目标。
+
+## Change locality和高内聚低耦合
+
+这个skill应重点检查每个新增或修改的具体功能是否能限定在一个小范围内完成。
+每次写代码前，agent应根据当前任务判断：这个功能主要应该落在哪个模块、哪个子文件夹、哪个extension point、哪个harness或哪个test范围内。
+如果一个功能需要同时修改多个无关区域，agent应优先调整模块边界，而不是直接把改动散落到各处。
+需要一起变化的代码应放近；不因同一原因变化的代码应分开。
+模块之间应通过稳定接口、明确数据结构或显式契约协作，避免调用方依赖被调用方内部实现。
+封装应保护协作者不受内部实现变化影响，从而支持松耦合和模块化；封装不应变成隐藏复杂性和增加跳转成本的借口。
+新增一个method应尽量只影响method相关接口、实现和必要注册逻辑。
+新增一个baseline应尽量只影响baseline相关实现和必要比较逻辑。
+新增一个metric应尽量只影响metric定义、metric计算和对应测试。
+新增一个harness应尽量只影响`harness/`下该harness自己的子文件夹和必要共享接口。
+新增一种test应放在当前repo测试体系中对应的自然位置，并尽量局部化到对应测试类别、测试区域和必要fixture。
+新增或修改result artifact应尽量局部影响结果schema、exporter和对应测试，不应牵动核心method实现。
+如果某个模块因为method、dataset、metric、harness、result export等多种互不相关原因频繁变化，应拆分职责。
+如果某个共享工具层开始混入项目特定业务逻辑，应把业务逻辑移回更具体的功能模块。
+如果当前功能无法局部实现，agent应说明这是framework边界或耦合风险，并优先做最小必要的局部重构。
+
+## 文件长度 / 模块粒度 / 子功能拆分
+
+文件是否过长是设计信号，不是简单行数问题；skill不应写死固定最大行数。
+具体文件长度应结合目标语言、框架生态、已有repo风格、deepresearch到的高质量公开库风格和当前功能复杂度判断。
+每个文件应有清晰的单一主题，例如一个文件主要承载一个接口、一类adapter、一类metric、一段数据处理逻辑、一个harness入口、一个测试类别或一个结果artifact定义。
+如果某个文件同时包含配置解析、数据处理、method实现、metric计算、harness运行和结果导出，应拆成多个更小的逻辑文件或模块。
+复杂功能应先拆成子功能，再决定文件组织；例如先识别输入解析、核心处理、外部调用、结果计算、artifact导出、错误处理和测试支持等子职责，再把相关内容放入合适模块。
+skill应避免生成或保留“god file”“mega runner”“all-in-one utils”“misc helpers”这类低内聚文件。
+通用工具文件只应包含稳定、窄职责、确实被多处复用的代码。
+如果某个工具文件开始承载多个不相关helper，应按语义拆成更具体的模块，而不是继续堆在同一个文件里。
+如果一个文件的修改会频繁影响多个无关功能，skill应重新审视文件边界，并优先拆分为更高内聚的文件。
+如果多个文件之间出现大量薄wrapper、纯转发函数或为了拆分而拆分的间接层，skill应合并或简化；拆分的目标是提升内聚和局部修改能力，不是制造更多文件。
+外部复制或改写来的代码如果本身过长或职责混杂，skill应在license允许的前提下做适配性拆分，并在注释或第三方说明中记录来源和主要改动。
+
+## 既有repo中的子文件夹整理
+
+虽然本skill不负责初始化仓库，但它仍应在已有repo中根据功能边界进一步拆分子文件夹。
+子文件夹拆分应来自当前任务和现有framework的真实需要，例如某个harness变复杂、某类test需要独立fixtures、某类method需要多个变体、某个export pipeline需要独立schema。
+子文件夹命名应语义化，直接表达功能目的，不使用`c1/c2/c3/b1/b2/b3`这类抽象编号。
+如果复杂功能已经挤在一个文件或一个目录中，agent应考虑把它拆成更清楚的子模块和子目录。
+如果拆分会导致路径变复杂、调用链变长或引入大量样板代码，agent应选择更简单的局部结构。
+子文件夹整理应保持与已有repo风格一致，不应强行引入另一套目录哲学。
+本skill应关注“已有框架内的局部整理”，而不是“重新设计整个仓库”。
+公共层只放真正公共、稳定、跨多个地方共享的内容。
+只在局部使用的helper、数据结构、配置、状态或特殊逻辑应放在使用点附近。
+共享基础结构只承载所有使用方共同需要的能力，不承载少数使用方的特殊逻辑。
+特殊case应尽量留在特殊case的使用位置，不要为了少数情况污染公共层。
+
+## Harness和test
+
+Framework方面的内容不能丢；本skill仍应维护harness结构、testing结构和它们在framework中的位置。
+harness用于论文目标、性能指标、method筛选、模块优化和实验评估；test用于功能正确性、接口契约、数据格式和基础行为验证。
+`data/`固定用于输入数据或样例数据；`output/`固定用于程序运行产生的输出artifact；`results/`固定用于实验结果记录；`harness/`固定用于所有harness相关内容。
+每一种harness仍应在`harness/`下有独立子文件夹，用于放置该harness相关入口、配置、说明、schema、样例输入或支持代码。
+harness目录固定，是因为harness直接服务论文目标、实验评估和method优化循环；测试目录不固定，是因为测试组织往往受语言生态、框架、模板和已有repo风格影响。
+测试文件的物理路径不固定；skill应遵守初始化模板代码库或已有repo中已经采用的测试组织方式。
+skill不应强制创建顶层`test/`目录，也不应把所有测试都迁移到固定测试目录下。
+如果初始化模板或已有repo已经定义了测试目录、测试命名规则、fixtures位置、mock data位置或测试框架配置，skill应沿用这些约定。
+如果当前repo尚未体现测试放置规则，skill应先根据已有模板文档、`FRAMEWORK.md`、项目配置和相邻测试文件推断测试组织方式；只有在确实没有约定时，才根据目标生态和deepresearch结果选择合适测试结构。
+testing structure仍然必须被规划和维护，但testing structure描述的是“测试覆盖哪些功能、如何验证、如何组织测试类别”，不是固定测试文件路径。
+写harness代码时，应让harness目标清楚、入口清楚、输入输出清楚、metric清楚、raw artifact清楚。
+写test代码时，应让每个测试验证一个明确功能行为，有清晰pass/fail标准，并尽量使用小型fixture、toy input或mock data。
+harness代码不应承担功能测试职责，test代码不应承担论文性能评估职责。
+harness如果变复杂，应在`harness/`下对应harness子文件夹内拆成清楚的支持模块；test如果变复杂，应在现有测试体系内进一步拆分子文件夹或支持模块，并遵守repo已有风格。
+新增harness或test时，应同步检查它是否与现有framework文档、命名、artifact schema和模块边界一致。
+新增测试时，应优先放在现有测试体系中最自然的位置，使测试与被测功能、fixtures和现有测试风格保持一致。
+测试命名应语义化，表达被测功能或行为，例如数据读取、method接口、metric计算、结果导出、CLI行为等；具体文件名和路径由repo模板和已有风格决定。
+harness应支持“修改模块 -> 运行harness -> 读取结果 -> 再修改”的循环，因此需要稳定入口语义、固定输入协议、可解析输出格式和清晰metric定义。
+harness输出应优先记录原始、低加工的artifact，例如per-example prediction、raw score、timing trace、resource usage、intermediate decision、error case、log metadata、config snapshot、seed、split和metric values。
+harness不应把面向论文图表的数据聚合和转换写进核心逻辑；聚合、绘图和论文表格生成应由后续分析、绘图或论文写作skill基于原始artifact完成。
+test应覆盖数据读取、配置解析、method接口、baseline接口、metric计算、结果导出、CLI入口和核心模块交互等功能正确性问题；具体覆盖范围由当前任务和上游plan决定。
+testing输出主要服务debug和开发反馈，应和论文实验结果artifact分开管理。
+如果已有repo使用`test/`作为测试布局，本skill应把它当作已有repo约定维护；如果已有repo使用别的测试布局，本skill应尊重目标生态和repo已有测试结构。
+
+## Framework文档
+
+本skill应维护`FRAMEWORK.md`和`FRAMEWORK.zh-CN.md`，即使它不再负责初始化repo。
+`FRAMEWORK.md`和`FRAMEWORK.zh-CN.md`应描述当前已有代码框架，而不是描述模板初始化流程。
+每次重要代码结构、模块边界、harness/test组织、extension point或artifact schema发生变化时，应同步更新`FRAMEWORK.md`和`FRAMEWORK.zh-CN.md`。
+`FRAMEWORK.md`使用英文，`FRAMEWORK.zh-CN.md`使用中文；中文版可以自然保留英文模块名、harness名、test名、method名、metric、命令、配置项和代码标识符。
+文档应说明当前framework如何支持后续功能局部修改，而不是只列目录树。
+文档应根据当前任务和上游plan分析：后续可能还需要做哪些修改、这些修改应在哪里做、能否限定在小范围内、有没有做到高内聚低耦合。
+文档可以包含“Change Map”或类似内容，用自然名称说明主要变化点、对应模块、相关接口、harness/test覆盖和修改范围。
+文档应说明哪些接口是稳定边界，哪些模块是扩展点，哪些位置是后续实现点。
+`FRAMEWORK.md`和`FRAMEWORK.zh-CN.md`应说明固定实验目录的含义，包括`data/`、`output/`、`results/`和`harness/`，并说明测试文件遵循当前模板或已有repo的测试布局。
+`FRAMEWORK.md`和`FRAMEWORK.zh-CN.md`应记录当前repo实际采用的测试组织方式，而不是假设测试一定在`test/`下。
+文档应说明复杂功能如何被拆成子功能模块，以及这种拆分如何支持高内聚、低耦合和后续局部修改。
+文档应说明harness结构：每种harness服务什么论文目标、修改哪个逻辑模块、如何运行、关注哪些metric、输出哪些raw artifact。
+文档应说明testing结构：每类test验证什么功能目标、使用什么最小输入、期望什么行为、测试文件或测试说明位于已有repo的哪个测试区域。
+文档应说明结果导出思路：系统应优先导出原始、低加工artifact，后续绘图和论文写作skill再从这些artifact转换出图表、统计结果和论文表格。
+如果某个后续修改目前无法限定在小范围内，文档应说明这是framework设计风险，并提示后续实现时优先整理该边界。
+文档中解释结构时，应优先用模块名、harness名、test名、method名或自然简称指代内容，而不是依赖抽象编号互相引用。
+文档不应解释skill内部流程、工具调用、沙盒问题、文件读取方式或runtime workaround。
+
+## 命名、顺序和边界
+
+命名必须精确反映真实含义，不使用泛化、含糊、历史残留或与数据形态不一致的名称。
+名称应来自论文领域契约、experiment plan、coding plan、用户输入和当前代码语义，而不是来自临时实现细节。
+名称应尽量短而语义完整，删除不增加信息量的前缀、后缀和包装词。
+同一个概念在接口、配置、类型、文案、文档、调用点和输出artifact中应使用一致名称。
+改名时必须全链路同步，避免旧概念残留在变量、接口、配置、提示文本、文档或报告中。
+名称后缀应反映真实数据形态；表示引用、路径、内容、状态、结果、配置的名称不能混用。
+如果一个名称暗示它是引用或外部资源，它就不应承载已经读取后的内容。
+如果一个名称表示内容本身，就不应继续保留引用式或路径式命名。
+已由论文蓝图、experiment plan、coding plan或用户输入形成契约的术语、拼写和领域词应保持一致，不应擅自改写。
+代码排列顺序应帮助读者理解流程；执行顺序明确的逻辑，应让代码顺序尽量反映执行顺序。
+输入、校验、构造、调用、输出等步骤应按自然阅读顺序组织。
+语义对应的结构应尽量保持字段顺序、参数顺序和定义顺序一致，减少读者在多个结构之间反复做脑内映射。
+相关代码应靠近放置，减少跨文件、跨模块、跨层级跳转。
+结构本身应表达意图，而不是依赖大量注释解释绕来绕去的数据流。
+
+## 状态、内容和引用
+
+每个变量、状态、配置和数据结构都应属于真实拥有它的层级。
+局部流程中产生的内容应留在局部，不要提升成公共状态或共享输入。
+只有长期稳定、跨边界仍有语义的数据才进入共享结构。
+临时状态不应被建模成长期状态；中断、重启、重跑后语义不稳定的概念不应成为核心模型。
+单次流程中的中间内容应优先作为值直接传递，不要为了保存而改变数据模型。
+上层派生并只由上层使用的内容应留在上层，不应伪装成下层模块的输入。
+如果某个数据只服务于编排、保存或展示，不应污染业务模块的接口。
+层级边界应清楚：谁负责生成、谁负责处理、谁负责保存、谁负责暴露，都应在代码结构中直接体现。
+代码应清楚区分“内容本身”和“对内容的引用”。
+如果传递的是内容，就使用内容语义的命名；如果传递的是引用，就使用引用语义的命名。
+不要让一个变量名暗示它是引用，但实际承载内容。
+不要让一个变量名暗示它是内容，但实际承载外部位置、句柄或标识。
+内容和引用的边界应通过命名、接口和数据流直接体现；内容和引用的边界不清会污染接口，应优先通过命名和数据流修正。
+当外层负责保存、归档或落盘时，内层不应同时承担同一写入责任。
+写入、保存、导出、返回等责任应单一，避免多个层级同时声称负责同一个产物。
+
+## Prompt和注释
+
+如果repo中包含prompt、任务说明、内嵌文案或给agent的指令文本，这些文本也应遵守代码风格。
+内嵌任务说明应直接描述任务，不使用角色扮演式开头。
+输入说明应清楚区分外部引用和直接内容。
+输出说明应明确谁负责生成内容、谁负责保存内容，避免让执行者误解写入责任。
+不要在内嵌文本中使用没有上下文的裸文件名、伪路径或模糊指代。
+如果一段文案会误导执行者产生错误行为，应改成直接描述真实责任。
+Prompt文本应短、明确、任务导向，不展示skill内部流程，也不解释为什么采用某个模板。
+注释只用于解释非显然决策、约束、来源或特殊原因。
+如果代码可以通过简化变得自解释，应优先简化代码，而不是添加注释。
+不要用注释解释本可以通过命名、结构或边界表达清楚的内容。
+不要把风格分析、实现过程、调试过程或skill规则写进代码注释。
+注释应服务后续维护者理解代码，不服务展示生成过程。
+
+## Open-source reuse
+
+当当前任务需要实现已有成熟功能时，skill应优先判断能否合法、合适、低维护成本地复用现有实现。
+复用方式优先级是直接依赖、适配调用、小范围复制或改写、自己重写；越靠后的方式越需要明确理由、license检查和维护成本判断。
+packaging良好且接口稳定的工具优先作为依赖安装调用。
+可复用但不适合作为依赖的代码可以在license允许的前提下小范围复制、改写或移植。
+不适合复用的代码只作为设计参考。
+skill应判断一个开源工具是“适合直接依赖调用”还是“只适合参考或复制片段”：判断依据包括packaging质量、API稳定性、维护状态、依赖复杂度、license兼容性、与当前框架的耦合成本和后续维护成本。
+能合法、合适、低维护成本复用现有实现时，skill应优先复用成熟代码，不要为了“从零生成”而重复实现已有可靠功能。
+复制或改写开源代码时，应只复制当前功能真正需要的小范围代码片段，不应把整个无关项目塞进已有repo。
+复制或改写代码前，skill应检查源代码license；没有明确license或license不兼容的代码，只作为阅读参考，不作为可复制代码来源。
+license决定代码能否被使用、修改、复制、分发和再授权；公开仓库只有在license允许他人使用、修改和分发代码时，才真正具备可复用的open source语义。
+复制或改写代码时，应保留原license要求的copyright notice、license notice或其他必要声明。
+抄来的代码、改写的代码或从外部实现移植的代码，都应在相关代码注释中标注来源。
+来源标注应尽量包含原项目名、原仓库URL、原文件或模块、原license、参考的commit/tag/version、复用方式和本项目做了哪些修改。
+如果代码是改写而不是原样复制，注释中应说明“adapted from”“inspired by”或“ported from”，并简要说明主要改动，例如接口适配、依赖移除、数据结构修改、错误处理修改、metric逻辑修改或与本框架harness对接。
+如果某段代码只是借鉴设计思路，没有复制具体表达，可以在`FRAMEWORK.md`或developer notes中说明参考来源和设计影响，而不必把它写成逐行代码来源注释。
+如果复制或改写了多个外部来源的代码，repo中应创建或维护`THIRD_PARTY.md`或等价文档，用于集中记录外部代码来源、license和修改概况。
+复用代码应让当前框架更规整、更可靠、更快落地，而不是带来额外配置、过度封装或调用方负担。
+复制或适配的代码应放在语义明确的小范围内，后续修改某个功能时不应牵动多个无关区域。
+
+## Deepresearch和外部参考
+
+当当前任务涉及不熟悉的语言生态、框架习惯、代码组织方式、harness/test实践、开源复用或可读性约定时，应使用`academic_army_mcp_tools`里的deepresearch现场调研。
+deepresearch应用于学习目标生态的高质量代码风格、模块粒度、测试组织、harness组织、framework文档方式和可复用开源实现。
+deepresearch结果应服务当前代码可读性和framework一致性，不应机械照搬公开库结构。
+这个skill不应在tips里写死具体language、具体framework、具体目录模板、具体包管理器或具体测试框架；这些由用户输入、已有repo和deepresearch共同决定。
+如果已有repo已经确立了某种语言和框架风格，agent应优先遵守现有风格，并只在确有必要时做局部改进。
+参考代码来源可以包括高质量公开库、论文官方代码、benchmark实现、harness实现、实验框架、工具库、工程化模板和目标生态中的成熟项目；具体参考对象由deepresearch现场决定。
+skill应优先参考维护良好、工程化程度高、license明确、结构清晰、与当前任务或当前论文实验系统接近的公开代码库。
+skill下载或参考开源代码时，也应分析其文件粒度：如果参考库把复杂逻辑拆得清楚，可以学习其拆分方式；如果参考库存在过长文件或历史包袱，不应机械复制。
+
+## Readability audit
+
+每次写完或修改代码后，agent应做一次readability audit。
+readability audit应检查命名是否清楚、函数是否过长、文件是否过重、模块职责是否单一、调用链是否过绕、抽象是否必要。
+readability audit应检查是否存在大量样板代码、重复注册点、薄wrapper、过度拆分、隐藏全局状态或复杂配置负担。
+readability audit应检查新增代码是否符合已有repo风格，是否能被后续agent快速理解和修改。
+readability audit应检查当前功能是否主要限定在语义明确的小范围内。
+readability audit应检查harness/test职责是否分离，artifact schema、exporter和测试是否保持一致。
+readability audit和framework audit应检查新增测试是否符合现有测试布局，而不是检查是否放在固定`test/`目录下。
+readability audit应检查`FRAMEWORK.md`和`FRAMEWORK.zh-CN.md`是否需要随结构变化更新。
+readability audit应检查外部代码来源标注是否完整：复制或改写代码是否有注释来源，第三方说明文件是否记录license和修改，文档是否解释复用决策。
+readability audit应检查是否有未标注来源的外部代码片段、疑似无license来源代码或大段无关复制代码；如果有，应补充来源说明、移除不必要代码或改成从依赖调用。
+readability audit应检查是否存在职责过多的文件、过长的runner、过大的utils、混杂的harness/test文件、重复样板代码或明显应该拆分的子功能。
+readability audit应同时检查反方向问题：是否存在过度拆分、空壳文件、薄wrapper、只被调用一次的抽象层或让调用链变长的碎片化模块。
+如果发现代码能工作但不够清楚，应优先重构到更清晰的形式，而不是把复杂性留给后续任务。
+如果发现为了“可扩展”而加入了当前任务不需要的抽象，应删除或简化。
+如果发现某个函数、文件或模块的名称不能解释其用途，应重新命名或重新拆分。
+如果需要运行安装、测试、harness或实验，应交给后续代码实现、测试执行或实验执行skill；本skill关注静态代码质量和framework一致性。
+
+## 代码审阅
+
+审阅代码时优先检查是否存在无意义抽象、过度函数化、错误层级归属、命名不精确、状态不稳定、顺序不一致、数据流不清晰、文件过重、模块边界混乱和change locality差。
+审阅建议应优先指向删除、内联、移动到使用点、统一命名、对齐顺序、拆分职责和澄清边界。
+不默认建议增加更多抽象、更多配置层、更多wrapper或更多defensive处理。
+如果代码已经足够直接，审阅应避免提出“为了整洁再抽一层”的建议。
+如果发现变量属于错误层级，应建议把它移回真实拥有者所在层，而不是通过新类型或适配函数绕过去。
+如果内容和引用混用，应要求通过命名和数据流区分真实语义。
+如果临时状态被写进长期模型，应要求改成稳定概念或移回局部流程。
+如果旧概念残留在名称、文案、配置或接口中，应要求清理残留并统一契约。
+如果某个功能修改牵动多个无关模块，应指出耦合风险，并建议更清楚的局部边界。
+
+## 和其他skill协作
+
+这个skill可以被写代码skill、harness实现skill、test实现skill、实验执行skill、代码重构skill、论文实验系统维护skill等多种任务调用。
+初始化模板skill决定初始repo骨架；本skill在这个骨架上持续维护代码质量和framework清晰度。
+当上游任务只要求一个小功能时，本skill不应扩大任务范围重构整个repo；它应在小范围内保持代码清楚。
+当上游任务暴露出明显framework边界问题时，本skill可以做必要的局部重构，并同步更新framework文档。
+当上游任务需要新增目录、模块或文件时，本skill应确保新增结构符合已有framework、命名清楚、职责单一、不会制造不必要配置成本。
+如果上游任务和本skill发生边界冲突，应优先完成用户当前任务，并把代码质量整理限定在必要范围内。
+
+## 输出要求
+
+输出应聚焦代码修改本身和必要说明。
+不输出skill内部流程、模板选择、风格分析过程或工具使用细节。
+不把“我是根据某条skill规则这样写的”这类元信息写给用户。
+不在代码注释中解释风格规则。
+修改说明应短，直接说明改了什么、为什么这样改，以及是否还有与代码本身相关的注意点。
+不写过多背景解释，不把简单修改包装成复杂设计说明。
+
+**General clean-code skill原则**：这个skill是通用代码质量层；任何任务只要涉及写代码、改代码、补功能、实现harness/test或整理模块，都应使用它来保证代码简洁、规整、可读、低耦合、易维护。
+**No initialization responsibility原则**：这个skill不负责初始化模板repo，不生成通用仓库骨架；它在已有repo和当前任务范围内维护代码质量、局部结构和framework文档一致性。
+**Existing framework preservation原则**：已有framework不能丢；新增或修改代码时，应继续维护模块边界、harness/test组织、extension point、artifact schema、`FRAMEWORK.md`和`FRAMEWORK.zh-CN.md`。
+**Template-aligned testing layout原则**：测试文件路径不由本skill固定；本skill应遵守初始化模板或已有repo的测试布局，只维护测试目标、测试覆盖、测试可读性和局部修改能力。`data/`、`output/`、`results/`和`harness/`仍作为固定实验目录保留。
+**Readable implementation over clever abstraction原则**：代码应优先让后续agent和人类读者容易理解；抽象只有在能减少重复、缩短调用方代码、隔离变化点或提升测试性时才引入。
+**Local change principle原则**：每个具体功能都应尽量只在自己的小范围内实现和修改；如果做不到，应先分析模块边界和耦合关系，再决定是否做局部重构。
+**File granularity原则**：优秀代码应避免长文件和职责混杂文件；复杂功能先拆成清晰子功能，再映射到文件和模块，使每个文件主题明确、变化原因清晰、后续修改局部化。
+**Balanced modularity原则**：拆分应服务高内聚、低耦合和change locality；既不要把多个复杂职责塞进一个文件，也不要为了形式化模块化制造大量薄wrapper和碎片化文件。
+**Open-source reuse原则**：能合法、合适、低维护成本复用的成熟实现应优先复用，复用方式优先选择直接依赖或适配调用，其次才是license允许的小范围复制或改写；所有复制、改写或移植的代码都必须在代码注释和第三方说明中标注来源、license和修改内容。
+**Framework consistency原则**：代码结构、harness/test组织、artifact schema、配置入口和文档说明应互相对齐，使后续修改者能从framework文档直接找到正确修改位置。
+**总原则**：本skill负责在任何代码写作任务中持续维护简洁、规整、可读、低耦合、易扩展的代码质量和framework一致性；它不初始化模板repo，而是在已有repo和当前任务范围内让代码更清楚、边界更稳定、修改更局部。

package/metaskills/academic-army-experiment-plan/ENVOLVETASK.md

@@ -0,0 +1 @@
+Create an experiment plan based on the paper blueprint in output/paper_blueprint.md.

package/metaskills/academic-army-experiment-plan/METASKILL.md

@@ -0,0 +1,82 @@
+这个skill属于一套基于Codex的autoresearch工具链，当前要编写的是为论文制定实验方案的`academic-army-experiment-plan` skill。
+skill应生成战略层面的experiment plan，而不是直接执行实验、写代码、跑实验、生成最终图表或替代后续更具体的实验执行skill。
+skill只定义experiment plan生成所需的学术任务逻辑、文件输出边界、语言要求、解释要求、deepresearch学术调研要求和质量标准；文件访问、工具选择、沙盒权限、命令执行、fallback策略等运行机制由外层agent环境负责，不写入skill正文，也不进入`experiment_plan.md`或`experiment_plan.explain.md`。
+
+编写skill时应使用`academic_army_mcp_tools.deepresearch`进行调研；该工具本质是把prompt通过OpenAI API转发给带web search能力的GPT-5.5，因此现场能搜索到的信息不需要硬编码保存在skill里。
+deepresearch调研不应只限于相关autoresearch工具，也可以包括autoresearch论文、open-source code、paper-writing agent、scientific discovery agent、experiment automation workflow、benchmark、prompt template和其他任何对skill设计有启发的资料。
+编写skill时也应通过deepresearch现场分析“一个优秀的experiment plan skill应该怎么写”。
+
+skill应明确使用来自`academic_army_mcp_tools`的deepresearch工具；这个工具本质是把prompt通过OpenAI API转发给带web search能力的GPT-5.5，因此目标venue、高引论文、近期写作风格、autoresearch工具现状等动态信息应现场检索，不必硬编码进skill。
+skill应使用此deepresearch工具调研SIGGRAPH、CVPR、SIGCOMM、NSDI等顶级会议上的高引或高影响论文，分析这些论文为什么优秀，并提炼其中对实验规划有用的模式。
+分析目标venue和相关领域高引论文时，应重点看这些论文的experiment为什么有说服力、methods/datasets/baselines/metrics/result presentation如何支撑论文论点，以及这些模式如何影响当前experiment plan取舍。
+调研experiment设计时使用的论文应尽量新，以代表当前审稿人对methods、数据集、baseline、实验结果展示等方面的偏好。
+skill在搜索现有资料时，应特别关注与当前方法和实验部分相关性高的论文，分析它们做了什么实验、展示了什么实验结果、如何让实验结果直观易懂。
+对已有论文实验设计的借鉴应服务当前论文：确定需要做什么实验、测什么数据、这些数据适合展示成什么样的图表，但不要把某篇论文的实验模板机械搬过来。
+
+experiment plan应与论文蓝图中的storytelling匹配，实验不是孤立列表，而是服务论文中不同论点、不同叙事阶段和不同读者认知需求的证据安排。
+experiment plan应区分不同实验在论文中的地位：有些实验用于提供insight和motivation，可能放在motivation章节或method开头；有些实验用于验证最终效果，可能放在论文后部的experiment章节。
+规划每个experiment时，应明确其实验目标、支撑的论文论点、在论文叙事中的位置、预期结果会服务哪个部分，以及它与论文蓝图核心storytelling的关系。
+
+experiment plan应偏向目标导向：以support论文中的各种论点为总目标，将论文论点分解成多个experiment目标，再围绕这些目标组织实验方案。
+experiment plan解释文件应说明每个实验目标背后的思想、实验目标之间的联系，以及实验安排如何帮助论文达成蓝图中的核心目标。
+skill在遇到可选实验方案、展示方式、实验放置位置或证据功能时，应先进行面向论文目标的综合评判，再决定是否需要保留为开放验证项；评判维度应由当前论文、目标venue、论文蓝图、实验目标和deepresearch结果共同决定，不应在skill中写死固定维度。
+如果用户已明确的内容、论文蓝图中的storytelling、核心claim、用户指定约束或`academic_army_mcp_tools.deepresearch`的现场调研结果已经足以推出对论文明显更优的选择，skill应把该选择视为已确定设计，直接写入`experiment_plan.md`，而不是把它转嫁给用户二选一或多选一。
+skill做出的关键选择应在`experiment_plan.explain.md`中用中文解释理由，说明该选择如何来自用户已明确内容、论文蓝图、目标venue偏好、相关论文实验模式和当前论文的核心论点，并解释它如何服务论文目标。
+如果deepresearch发现当前venue或相关高质量论文中存在清晰主流做法，且该做法与当前论文目标一致，skill应优先把它作为默认选择，并在解释文件中说明采用该做法的理由。
+如果deepresearch发现主流做法不适合当前论文，skill应说明为什么当前experiment plan选择了不同方案，并解释这种偏离如何更好地服务当前论文的核心论点。
+
+在experiment plan阶段还没有真正进行实验，后续还会基于论文蓝图和experiment plan运行写代码、做实验、内容编排、绘图规划等更具体的skill。
+后续skill会有不同专业能力，并倾向于执行更具体的任务；experiment plan应为这些后续skill提供核心实验信息，而不是提前安排具体实现细节。
+后续论文内容编排、绘图规划、实际做实验等skill的结果可能会反馈到experiment plan中，experiment plan应支持后续迭代修改。
+
+experiment plan需要明确实验的内容和展示方式，但这里的“展示方式”应偏战略层面，说明实验结果适合如何被读者理解，而不是提前完成具体figure设计。
+experiment plan应明确哪些实验结果应作为motivation证据，哪些应作为method insight，哪些应作为最终效果验证，哪些应作为支撑性或补充性证据。
+experiment plan应明确每个实验要验证或展示的核心信息，例如缺陷、可行性、效果、对比、机制、消融、效率、泛化、鲁棒性或其他与当前论文相关的实验目标；具体类别应由当前论文和现场调研决定。
+experiment plan应明确每个实验与论文claim之间的关系，使后续执行skill知道该实验为什么存在、要产出什么证据、证据应如何支撑论文叙事。
+experiment plan应明确每个实验需要测量的数据类型和结果形式，但不要过早规定具体代码实现、运行脚本、参数配置或工程细节。
+experiment plan应明确实验结果的预期阅读方式，即读者看到该实验后应该理解哪个intuition、相信哪个论点、排除哪个疑虑。
+experiment plan和解释文件中的“降级路径”应谨慎处理，避免让输出默认围绕实验失败展开。
+对于工科论文，experiment plan不应默认假设实验效果不佳，也不应把“降级路径”写成主要内容；实验规划应围绕直觉上成立的核心思想如何被清楚展示和验证来组织。
+如果需要表达实验风险或可变因素，应把它们组织成实验设计中的依赖关系、开放变量或后续迭代信息，而不是把重点放在失败预案上。
+motivation实验的设计思想应是在真实系统完整搭建前，对现有系统的缺陷进行验证，或展示method中核心思想的可行性。
+motivation实验的结果展示应尽量一目了然，让读者直观相信论文依赖的intuition成立。
+experiment plan主要是给AI看的，不是主要给人看的；它只需要客观描述实验方案本身，不应包含面向用户的提醒、建议、免责声明或待办式内容。
+experiment plan中不应出现`Assumptions to validate`、`Artifact cautions`、`Do not assume reviewers will run code`这类面向用户的部分。
+如果确实存在不确定信息，应将其表达为实验方案中的开放变量、依赖条件或后续规划需要继承的信息，而不是写成用户提醒。
+
+
+`experiment_plan.md`和`experiment_plan.explain.md`都应为Markdown格式。
+`experiment_plan.md`固定只放experiment plan本身，且使用英文输出。
+`experiment_plan.explain.md`固定只放experiment plan解释和思考流程，且使用中文输出。
+skill中应明确两个文件的内容边界，避免experiment plan中混入解释，也避免解释文件中混入skill内部流程说明或模板说明。
+
+experiment plan解释文件的功能是让用户确认`experiment_plan.md`中的项目是否合理，而不是单纯解释字段含义。
+experiment plan解释文件应让用户理解整个论文的核心出发点，也就是“为什么要这么设计实验”。
+experiment plan解释文件应说明experiment plan中的每个重要细节如何从论文核心出发点、论文蓝图、目标venue偏好和实验目标推导出来。
+用户发现experiment plan中某个实验不合理时，应能通过解释文件判断是哪个核心出发点有问题，还是从核心出发点推导到具体实验安排的中间环节有问题。
+experiment plan解释文件应展示experiment plan中每条重要内容与其他内容的关系，避免让用户自己猜实验安排之间的逻辑。
+experiment plan解释中可以把experiment plan中的每一条重要内容拿出来解释，说明它与核心思想、论文蓝图、其他实验或论文叙事位置的关联。
+
+用编号解释experiment plan对人不友好时，应改用更自然的写法；experiment plan本身不必须使用复杂编号，每个部分可以有自己的局部1、2、3。
+experiment plan和解释文件都应避免`c1/c2/c3/b1/b2/b3`这类需要反复跳转理解的编号系统。
+experiment plan解释应优先用section标题、实验名称、实验目标或自然简称来指代内容，而不是依赖抽象编号互相引用。
+
+experiment plan解释文件开头应记录“用户已经明确的内容”，但这部分不需要放进`experiment_plan.md`。
+“用户已经明确的内容”可以包括论文蓝图中已确定的信息、用户指定的实验偏好、目标venue、领域、方法方向、数据集、baseline、限制条件、展示偏好等。
+后续用户使用该skill修改experiment plan时，“用户已经明确的内容”应逐步累积，并作为新的实验规划约束。
+“你需要验证的问题”应与“用户已经明确的内容”、论文蓝图和deepresearch结果联动；如果某个问题已经由用户指定、论文蓝图明确，或能够通过deepresearch和论文目标综合判断出明显最优选择，就不应再次要求验证。
+skill应先尝试做出对论文最有利的选择，再判断是否需要开放验证；开放验证项只保留那些既无法由已有信息合理推出、又会显著影响experiment plan合理性的未知信息。
+skill应减少不必要的“开放验证项”：开放验证项应是真正需要额外事实才能决定的问题，而不是skill为了谨慎而生成的泛化问题、模板问题或已能推理解决的问题。
+随着用户明确内容、论文蓝图信息和deepresearch调研结果的增加，experiment plan和解释文件中的“你需要验证的问题”应越来越少；skill不应因为追求稳妥而持续输出大量待用户判断的问题。
+只有当某个选择无法从已有信息和deepresearch中可靠判断，且会显著影响experiment plan合理性时，才应保留为开放验证项。
+如果多个方案都可行但没有明显最优项，skill可以在解释文件中简要说明主要权衡，并把需要用户或后续实验反馈决定的部分保留为开放验证项。
+对于保留的开放验证项，`experiment_plan.explain.md`应说明为什么当前信息不足以判断，以及该问题会影响experiment plan中的哪些安排。
+对于experiment plan中的实验内容、结果展示方式、实验放置位置和证据功能，如果已有信息足以判断出合理安排，skill应直接给出安排，并在解释文件中说明推导链路。
+解释文件中的选择理由应面向用户确认experiment plan是否合理：用户应能看出skill为什么选择这个实验、为什么采用这种展示方式、为什么把结果放在这个论文位置，以及这个选择服务哪个核心论点。
+
+skill应避免过度defensive；编写prompt时应优先使用正向语言明确skill要做什么、输出服务什么目标、内容边界在哪里。
+反向限制只在必要时保留；大多数约束应改写为目标导向的正向要求，例如“experiment plan以论文实验方案为对象，使用客观陈述描述实验目标、证据功能和展示意图”。
+skill不应把自己能够根据用户输入、论文蓝图和deepresearch合理判断的问题转嫁给用户；这也符合prompt设计中明确上下文、期望结果和输出格式的原则，避免输出被过多不必要分支稀释。
+这一原则应与paper blueprint skill保持一致：如果用户已明确内容和deepresearch足以推出明显最优的论文定位、claim组织、贡献边界或证据策略，相关skill应直接写入对应蓝图文件，并在解释文件中说明理由，而不是生成不必要的开放验证项。
+中文解释和中英混排应自然：中文为主体，必要的英文论文标题、会议名、数据集、benchmark、method name和技术术语可以保留英文，术语表达应一致。
+编写skill时应确保：experiment plan偏战略，后续skill补战术；experiment plan给AI继承，explain给用户确认；实验设计服务论文storytelling，解释文件说明实验方案为什么这样设计。

package/metaskills/academic-army-experiment-plan/envolve.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+npm run evolve-skill -- \
+  --config agent-forge.yaml \
+  --skill-path skills/academic-army-experiment-plan \
+  --artifact-path output/evolve-academic-army-experiment-plan \
+  --metaskill-path metaskills/academic-army-experiment-plan/METASKILL.md \
+  --task-path metaskills/academic-army-experiment-plan/ENVOLVETASK.md

package/metaskills/academic-army-repo-scaffold/ENVOLVETASK.md

@@ -0,0 +1 @@
+Create a scaffold-only research code repository according to `output/paper_blueprint.md`, `output/experiment_plan.md`, and `output/coding_plan.md`.