qoderwake脚本需严格遵循五项规范：一、三层函数封装（main/handle_xxx/util_xxx）；二、变量前缀规则（cfg_/l_/p_/g_）；三、日志绑定三重上下文标签；四、配置外置yaml并校验；五、单元测试全覆盖且100%函数级覆盖率。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您正在编写QoderWake脚本，但发现代码重复率高、模块边界模糊、变量命名混乱，则可能导致后期维护耗时剧增。以下是实现规范化代码结构的具体操作步骤：
一、强制采用三层函数封装结构
所有业务逻辑必须拆分为入口函数、处理函数、工具函数三层，避免单个函数超过30行或承担多于一种职责，确保调用链清晰可追溯。
1、在脚本顶部声明入口函数，函数名统一为main()，仅包含参数解析与核心流程调度。
2、为每类业务动作单独定义处理函数，命名格式为handle_XXX()，例如handle_file_upload()，内部不执行I/O以外的副作用操作。
3、将字符串拼接、时间戳转换、路径拼接等通用操作抽离为工具函数，命名格式为util_XXX()，例如util_normalize_path()，且每个工具函数必须有类型注释。
二、变量与常量命名严格执行前缀规则
通过命名前缀明确标识作用域与生命周期，杜绝全局变量隐式污染，降低跨模块理解成本。
1、所有常量必须大写并加CFG_前缀，例如CFG_TIMEOUT_MS = 5000。
2、模块内局部变量使用l_前缀，例如l_retry_count = 0。
3、函数参数统一加p_前缀，例如def handle_log(p_level, p_message):。
4、全局状态变量必须以g_开头且仅允许在__init__.py中初始化，例如g_session_cache = {}。
三、日志输出强制绑定上下文标签
每条日志必须携带模块名、函数名、执行阶段三重标签，禁止使用裸print()或无上下文的logging.info()。
代码编辑 CLI 工具集合：Cursor CLI（agent）和 Qoder CLI（qodercli），用于代码修改、重构、Code Review 及自动化代码任务。
1、在每个处理函数起始处定义上下文标签，格式为ctx = "[MODULE:xxx][FUNC:yyy][STAGE:zzz]"。
2、所有日志调用必须将ctx作为首参数传入封装后的log_emit()函数。
3、log_emit()内部自动注入当前毫秒级时间戳与线程ID，并写入固定路径的qoderwake_runtime.log。
四、配置项与硬编码零容忍策略
任何IP、端口、路径、超时值、密钥字面量均禁止出现在源码中，全部迁移至外部YAML配置文件并做运行时校验。
1、创建config/default.yaml，按层级组织字段，例如network: {host: "127.0.0.1", port: 8080}。
2、在入口函数中调用load_config("default.yaml")，该函数自动校验必填字段是否存在且类型合法。
3、访问配置时统一使用点号路径语法，例如cfg.network.host，禁止使用字典get()或下标访问。
五、单元测试覆盖率强制绑定函数粒度
每个处理函数和工具函数必须对应一个同名测试函数，位于test/目录下相同路径结构中，未覆盖函数禁止合并进主干分支。
1、测试函数名格式为test_handle_XXX()或test_util_XXX()，与被测函数一一映射。
2、每个测试函数必须包含至少三个断言：正常输入、边界值输入、异常输入触发的错误类型。
3、运行pytest --cov=qoderwake后，覆盖率报告中单个函数未达100%则构建失败，CI流水线将直接拒绝提交。
