omo/lazycodex 常量文件拆分实战：delegate-task constants.ts 重构执行计划深度解析

omo/lazycodex 常量文件拆分实战delegate-task constants.ts 重构执行计划深度解析【免费下载链接】oh-my-openagentomo/lazycodex: The coding agent for tokenmaxxers;the one and only agent harness for complex codebases. For your Codex, for your OpenCode项目地址: https://gitcode.com/gh_mirrors/oh/oh-my-openagent在 omo/lazycodexoh-my-openagent这个由大量 TypeScript 包组成的 agent harness 中task委托工具的constants.ts曾是一个 654 行、身兼 6 种职责的上帝常量文件。本文基于仓库中一份真实的重构执行计划execution-plan完整还原如何安全拆分一个被 10 处内部/外部模块重度依赖的常量文件的全流程从预检分析、职责盘点、导入依赖映射到逐文件拆分、桶barrel重导出与零消费者变更的提交策略并结合当前仓库源码验证该计划的实际落地形态。读完本文你能掌握一套可迁移到任何中大型 TypeScript 项目的零消费者破坏模块拆分方法论。一、计划背景为什么要拆 constants.ts执行计划的 Context 部分给出了触发拆分的三个硬事实src/tools/delegate-task/constants.ts当时为654 行承载6 种不同职责违反了项目的200 LOC 模块代码约束规则modular-code-enforcement其中被普遍引用的CATEGORY_MODEL_REQUIREMENTS实际并不在constants.ts中而是在src/shared/model-requirements.ts当时 311 行同样违反 200 LOC 规则因此本次重构是双文件拆分拆分constants.ts本体同时把CATEGORY_MODEL_REQUIREMENTS从model-requirements.ts中剥离。这个文件之所以危险是因为它集中了task委托工具的全部静态知识内置分类的默认配置、分类描述、分类专属 prompt 附加段、plan 智能体的系统提示词与身份判定逻辑。任何一个拼写错误或误删导出都会波及整个委托执行链路。二、预检分析职责盘点与 LOC 核算执行计划的第一步不是动手而是把两个文件的所有职责逐项列出并估算行数constants.ts 的 6 项职责#职责内容规模1Category prompt appends8 个模板字符串常量约 274 行 prompt 文本2DEFAULT_CATEGORIESRecordstring, CategoryConfig约 10 行3CATEGORY_PROMPT_APPENDS分类 → prompt 映射约 10 行4CATEGORY_DESCRIPTIONS分类 → 描述映射约 10 行5Plan agent prompts2 个模板字符串 4 个构建函数约 250 行 prompt 文本6Plan agent identity utilsisPlanAgent、isPlanFamily约 30 行model-requirements.ts 的 3 项职责类型定义FallbackEntry、ModelRequirementAGENT_MODEL_REQUIREMENTS约 146 行CATEGORY_MODEL_REQUIREMENTS约 148 行。值得注意prompt 文本类代码虽然行数巨大但在 modular-code-enforcement 规则下豁免 200 LOC 限制——这一点在计划中针对 2c约 280 行与 2d约 270 行两个新文件被明确标注。也就是说拆分目标不是机械地把行数砍到 200 以下而是按职责边界切分prompt 文本天然聚类的文件允许超限。三、导入依赖映射拆分安全性的前提计划的核心洞察是只要保留桶文件barrel重导出所有消费者就一行都不用改。但前提是先把依赖面摸清楚。计划列出了三类消费者内部消费者delegate-task/ 目录内文件导入符号categories.tsDEFAULT_CATEGORIES、CATEGORY_PROMPT_APPENDStools.tsCATEGORY_DESCRIPTIONStools.test.tsDEFAULT_CATEGORIES、CATEGORY_PROMPT_APPENDS、CATEGORY_DESCRIPTIONS、isPlanAgent、PLAN_AGENT_NAMES、isPlanFamily、PLAN_FAMILY_NAMESprompt-builder.tsbuildPlanAgentSystemPrepend、isPlanAgentsubagent-resolver.tsisPlanFamilysync-continuation.tsisPlanFamilysync-prompt-sender.tsisPlanFamilyindex.tsexport * from ./constants桶文件外部消费者import from../../tools/delegate-task/constants文件导入符号agents/atlas/prompt-section-builder.tsCATEGORY_DESCRIPTIONSagents/builtin-agents.tsCATEGORY_DESCRIPTIONSplugin/available-categories.tsCATEGORY_DESCRIPTIONSplugin-handlers/category-config-resolver.tsDEFAULT_CATEGORIESshared/merge-categories.tsDEFAULT_CATEGORIESshared/merge-categories.test.tsDEFAULT_CATEGORIESCATEGORY_MODEL_REQUIREMENTS 的消费者文件导入路径tools/delegate-task/categories.ts../../shared/model-requirements这些依赖在当前仓库中依然可以逐一验证说明该计划的预检映射是准确的prompt-builder.ts 中import { buildPlanAgentSystemPrepend, isPlanAgent } from ./constants并在 prompt 组装时以isPlanAgent(agentName)为开关注入 plan 系统提示词sync-continuation.ts 与 sync-prompt-sender.ts 都从./constants引入isPlanFamily分别用于恢复会话时是否允许 task 工具const allowTask isPlanFamily(resumeAgent)和同步 prompt 路由时是否放行 task外部消费者 builtin-agents.ts、available-categories.ts、atlas/prompt-section-builder.ts 至今仍从../tools/delegate-task/constants导入CATEGORY_DESCRIPTIONScategory-config-resolver.ts 导入DEFAULT_CATEGORIES并实现用户自定义分类优先、内置分类兜底userCategories?.[categoryName] ?? DEFAULT_CATEGORIES[categoryName]。依赖图还揭示了一个跨层语义isPlanFamily不只是提示词注入开关它同时控制互斥委托阻断与task 工具权限——plan 家族plan prometheus是编排者可以下发task调用这正是后续 constants.ts 中PLAN_FAMILY_NAMES [plan, prometheus]与COORDINATOR_AGENT_NAMES守卫存在的根源。四、分步执行从建分支到提 PRStep 1创建分支git checkout -b refactor/split-category-constants dev分支命名直接体现重构意图与目标refactor/split-*基线为dev。Step 2把 constants.ts 拆分为 5 个职责单一的文件2a.default-categories.ts移入DEFAULT_CATEGORIESrecord从 config schema 导入CategoryConfig类型约 15 行。2b.category-descriptions.ts移入CATEGORY_DESCRIPTIONSrecord无依赖约 12 行。2c.category-prompt-appends.ts移入全部 8 个*_CATEGORY_PROMPT_APPEND模板字符串常量移入CATEGORY_PROMPT_APPENDS映射 record无依赖全部是自带上下文、自包含的模板字符串约 280 行以 prompt 文本为主豁免 200 LOC 限制。2d.plan-agent-prompt.ts移入PLAN_AGENT_SYSTEM_PREPEND_STATIC_BEFORE_SKILLS移入PLAN_AGENT_SYSTEM_PREPEND_STATIC_AFTER_SKILLS移入renderPlanAgentCategoryRows()、renderPlanAgentSkillRows()移入buildPlanAgentSkillsSection()、buildPlanAgentSystemPrepend()依赖来自 agents 的AvailableCategory、AvailableSkill类型来自 shared 的truncateDescription约 270 行以 prompt 文本为主豁免。2e.plan-agent-identity.ts移入PLAN_AGENT_NAMES、isPlanAgent()移入PLAN_FAMILY_NAMES、isPlanFamily()无依赖约 35 行。拆分顺序暗含依赖考量2a–2c、2e 完全无依赖、可独立验证2d 是唯一带跨模块类型依赖的文件因此放在最后且计划中显式标注了它需要导入的类型来源。Step 3把 constants.ts 改写为桶重导出文件原文件全部内容替换为对 5 个新文件的 re-export。这一步是整个计划的枢纽它让所有既有导入者保持 100% 向后兼容——内部消费者、外部消费者、桶文件index.ts的export *全部照常工作。Step 4拆分 model-requirements.ts4a. 新建src/shared/category-model-requirements.ts移入CATEGORY_MODEL_REQUIREMENTSrecord从./model-requirements导入ModelRequirement类型约 150 行。4b. 更新src/shared/model-requirements.ts删除CATEGORY_MODEL_REQUIREMENTS增加重导出export { CATEGORY_MODEL_REQUIREMENTS } from ./category-model-requirements保留类型FallbackEntry、ModelRequirement与AGENT_MODEL_REQUIREMENTS收敛到约 165 行低于 200 行红线。Step 5验证导入无破坏bun run typecheck—— 确认所有 import 可解析bun test—— 确认无行为回归bun run build—— 确认构建成功。Step 6LSP 诊断检查对所有新建与修改文件检查lsp_diagnostics是否为空。这一条把验证从编译器/测试通过进一步收紧到无诊断告警防止死代码、未使用导出等隐性问题进入主干。Step 7提交并创建 PR单个原子提交refactor: split delegate-task constants and category model requirements into focused modules附 PR 描述。原子提交保证 code review 时 diff 只有移动 重导出没有任何行为混入reviewer 可以确信这是一次纯结构性重构。五、文件变更清单与零消费者变更原则文件动作src/tools/delegate-task/constants.ts改写为桶重导出src/tools/delegate-task/default-categories.ts新增src/tools/delegate-task/category-descriptions.ts新增src/tools/delegate-task/category-prompt-appends.ts新增src/tools/delegate-task/plan-agent-prompt.ts新增src/tools/delegate-task/plan-agent-identity.ts新增src/shared/model-requirements.ts删除 CATEGORY_MODEL_REQUIREMENTS增加重导出src/shared/category-model-requirements.ts新增对任何消费者文件零修改。全部既有导入经由桶重导出继续生效。这是本文最值得内化的一条原则重构的安全边界不靠小心修改消费者来维持而靠重导出契约来维持——消费者越多这一原则的价值越大。六、当前仓库验证计划的实际落地形态从源码结构看该执行计划在 omo/lazycodex 仓库中已被部分落地且实际演化与计划同构但略有差异这本身就是计划驱动重构 后续持续演化的真实样本分类 record 已迁出 constants.ts。当前 constants.ts 只有 414 行从 654 行收敛其开头就是标准的桶重导出export { BUILTIN_CATEGORY_REQUIRES_MODEL, CATEGORY_DESCRIPTIONS, CATEGORY_PROMPT_APPENDS, CATEGORY_PROMPT_APPEND_RESOLVERS, DEFAULT_CATEGORIES, } from ./builtin-categoriesDEFAULT_CATEGORIES、CATEGORY_PROMPT_APPENDS、CATEGORY_DESCRIPTIONS等 record 已迁入 builtin-categories.ts。值得注意的是实际实现没有把三份 record 机械拆成三个文件而是收敛为一份BUILTIN_CATEGORY_DEFINITION[]按 Google/OpenAI/Anthropic/Kimi 分组再通过统一的buildCategoryRecord()工厂派生出各 record——从源码结构看这是比计划更进一步的单一数据源设计消除了计划中三份 record 各自维护的潜在漂移风险。constants.ts 保留了计划 2d/2e 对应的职责PLAN_AGENT_SYSTEM_PREPEND_STATIC_BEFORE_SKILLS/AFTER_SKILLS两大模板字符串、renderPlanAgentCategoryRows、renderPlanAgentSkillRows、buildPlanAgentSkillsSection、buildPlanAgentSystemPrepend以及PLAN_AGENT_NAMES、isPlanAgent、PLAN_FAMILY_NAMES、isPlanFamily等身份工具仍留在该文件中。plan agent 的系统提示词本身就是先派发 explore/librarian 智能体收集上下文、再输出依赖图 并行执行波次 分类/技能推荐的强制协议——这也解释了为什么这类 prompt 文本天然豁免 200 LOC 限制。model-requirements 拆分已完成并进一步下沉到共享包。当前 shared/model-requirements.ts 已是一个仅 5 行的重导出垫片shim把FallbackEntry、ModelRequirement类型与AGENT_MODEL_REQUIREMENTS、CATEGORY_MODEL_REQUIREMENTS全部转发到oh-my-opencode/model-core。而 packages/model-core/src/category-model-requirements.ts131 行正是计划 Step 4a 所描述的新家CATEGORY_MODEL_REQUIREMENTSrecord 按分类提供fallbackChain例如visual-engineering分类的降级链为claude-opus-5(max)→kimi-k3(max)→glm-5.2(max)→gpt-5.6-sol(medium)每项都带 providers 白名单与推理档位variant。类型定义则落在 model-requirement-types.ts。消费端 categories.ts 仍然按计划中的路径../../shared/model-requirements导入CATEGORY_MODEL_REQUIREMENTS并在分类解析时查表const categoryReq CATEGORY_MODEL_REQUIREMENTS[categoryName]——消费者零变更原则在真实代码中得到兑现。委托链文档与计划相互印证。delegate-task 目录的 AGENTS.md 描述了该目录的双执行模式background/sync、同步执行链sync-task.ts → sync-session-creator.ts → sync-prompt-sender.ts → sync-session-poller.ts → sync-result-fetcher.ts与分类解析流程用户自定义分类优先回退到内置分类。计划中依赖映射涉及的sync-prompt-sender.ts、sync-continuation.ts、categories.ts都是这条链上的一环说明拆分所触及的正是委托执行链的核心静态层。七、方法论提炼如何安全拆分一个上帝常量文件把这份执行计划抽象成可复用流程共五步先盘点职责再动手为源文件逐条列出职责与行数明确哪些内容豁免行数规则如 prompt 文本避免按行数机械切分导致语义割裂画完整导入依赖图区分内部消费者、外部消费者、桶文件三类按符号粒度记录哪个文件 import 了哪些导出。这一步决定了桶文件必须保留哪些重导出按职责建文件无依赖者优先无外部依赖的 record/常量先拆可独立验证带跨模块类型依赖的模块最后拆并在计划中显式列出依赖来源桶重导出兜底源文件改写为 re-export 层实现消费者零变更被拆分出的大块如CATEGORY_MODEL_REQUIREMENTS同样在新家加类型导入、在旧位置加重导出三层验证 LSP 诊断typecheck导入可解析→test行为无回归→build构建成功→lsp_diagnostics无隐性问题全部通过后再以单个原子提交 PR 描述收尾。这套流程在 omo/lazycodex 的实际演化中经受住了检验即使后续架构调整内置分类改为按 provider 分组的定义数组、模型需求下沉到 model-core 共享包偏离了原计划的文件名与文件数重导出契约始终保护着所有消费者——这正是以文档为计划、以源码为契约的重构工程实践。【免费下载链接】oh-my-openagentomo/lazycodex: The coding agent for tokenmaxxers;the one and only agent harness for complex codebases. For your Codex, for your OpenCode项目地址: https://gitcode.com/gh_mirrors/oh/oh-my-openagent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考