# Flexlb Development

> FlexLB 开发、缺陷修复、重构和代码审核规范。适用于 RTP-LLM 的 rtp_llm/flexlb 及其调用方，重点约束类流程说明、成员组织、请求与资源生命周期、修改范围、验证及提交；不用于无关的模型推理代码或线上运维。

- Skill: `alibaba/flexlb-development` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx get-skill add alibaba/flexlb-development`
- Raw SKILL.md: https://api.skillmd.com/api/skills/alibaba/flexlb-development/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: alibaba (https://skillmd.com/u/alibaba)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/alibaba/flexlb-development

---


# FlexLB 开发规范

让了解业务但首次接触该类的人，能从代码和相邻注释直接读懂流程、状态及清理责任。
以真实代码和用户当前要求为依据；简单修改直接落实，不为套流程扩大任务。

## 统一术语与命名

新增、修改或审核类名、方法名、字段名、状态名及架构说明时，读取
[FlexLB 开发术语与命名约定](references/terminology.md)，按业务含义选择术语。
重点区分调度、选址、路由发布、交付、抢占、取消、资源释放和请求清理，不能互相替代。
同一个概念使用同一个词；不同含义使用不同名称，不用 `Placement` 等宽泛词统称多个步骤。
术语表中的现有类名是定位示例，不是新增抽象的要求；旧名迁移只处理当前授权范围，
不能机械替换无关的缓存淘汰、外部协议字段、配置键或监控指标。

## 开始修改前

本技能及相关开发技能统一维护在 FlexLB 的 `skills/`，以仓库版本为准。
仓库根目录的 `.agents/skills/flexlb-development` 通过相对符号链接指向本技能，
让仓库根目录、`rtp_llm` 和 `rtp_llm/flexlb` 下的 Codex 都能发现同一入口。

- 从当前工作区定位 `rtp_llm/flexlb`，阅读适用的 `AGENTS.md` 和相关模块说明。
  这些文件是仓库约定的来源；本技能不固化会随重构变化的类名、配置项或模块职责。
- 查看工作区和暂存区，区分用户既有改动与本次任务。不能通过恢复文件、整文件覆盖或
  全量暂存清理别人的改动；基于当前代码修改，不假设工作区等于 HEAD。
- 阅读实际入口、关键调用方、被改类及相关测试。架构问题按需阅读
  `docs/architecture/` 和当前适用的设计说明，区分设计目标、历史提案和已实现行为。
- 先明确要改变的行为与必须保持的语义。用户只要求解释、评审或方案时不直接改逻辑；
  只要求命名、排序或排版时不顺带修改生命周期、重试或同步策略。
- 跨模块职责调整按需读取 [workflow-first-design](../workflow-first-design/SKILL.md)，
  局部实现按需读取 [evidence-first-implementation](../evidence-first-implementation/SKILL.md)；
  不把小修改强制升级成架构设计。

## 由 AI 理解流程，再组织代码

创建或修改任何具名类（包括有独立职责的内部类）时，先判断是否需要类说明，再改成员或实现。
这也适用于旧类和仅调整成员顺序的修改，不限于新增类或实质重构：

1. 旧类先读实现和调用方，为需要说明的类补齐缺失注释，修正已经过时或过长的说明；
   原说明准确且简洁时保留，不为走流程重写。
2. 新流程类先写清职责和预期主流程，再实现。类说明只概括本类负责的业务，不代替设计材料。
3. 依据确认后的流程组织成员并实施本次修改，完成后再核对说明与代码一致。
   发现旧注释和实现矛盾时先查明实际契约，不能为迎合注释擅自改变现有行为。

流程类通过实现和调用方确认以下问题，但不要将这份检查清单全部抄进类注释：

- 类负责的业务对象及边界，哪些独立入口会触发它。
- 从进入、处理、等待到结束的主要步骤；在哪个线程执行，哪里会异步交接。
- 关键状态代表什么，谁修改，何时失效；失败和取消后谁继续清理。
- `start`、`stop`、`close` 的真实效果：启动什么、停止接纳还是停止执行、是否等待、
  最终释放哪些资源。不能只看名字假设生命周期。

类 Javadoc 默认只写 1–3 句话，通常是职责、主流程、一个确有必要的关键边界。
使用简洁的多行格式；不要罗列全部方法、字段、状态、异常分支或调用链，不逐行翻译实现，
也不堆叠“本类不负责什么”。命名和字段已自解释、没有自定义行为的简单 record、DTO 和枚举
可以没有类注释，不为了满足形式重复代码。有单位、特殊取值、身份约束、校验、资源或生命周期
语义时需要说明；局部约束优先放在相应字段或方法旁。不为数据类编造启动、停止流程。
有必要的局部细节放在对应代码附近，避免类注释盖过主体逻辑。
流程变化时同步修改说明；本次未涉及的类不顺手批量添加模板注释。

例如，只有在实现确实满足时才这样说明：

```java
/**
 * 执行请求任务：接收并处理请求，停止接收后等待已有工作结束，再释放执行资源。
 * 用户响应回调在请求锁外执行。
 */
```

### 成员顺序与人类阅读顺序

- 字段及初始化块在前，构造器随后，方法按
  `public → protected → 包级 → private` 分组，内部类型放在方法之后并递归整理。
- 各可见性组内，按类的真实流程放置业务入口及相关方法。多个独立入口的顺序由 AI
  结合类流程说明判断，不能用字母顺序、方法长度或调用次数代替业务判断。
- 字段优先呈现常量、核心依赖与配置，再呈现运行状态、索引与缓存、诊断信息；
  相关成员成组留白。但同类初始化操作的相对顺序、实例字段顺序和 Lombok
  构造器参数顺序必须保持。受到这些约束时用空行或简短分组说明改善阅读。
- 方法名、变量名直接说明保存的数据或实际动作。避免用模糊的 ownership、terminal、
  settlement 等词统称不同职责；已有领域术语需要准确指向具体对象或行为。
- 将用户已确认的流程顺序作为修改依据；不要让自动排序反复打乱人工安排。

### 排序脚本的真实边界

使用前检查仓库内 `tools/order_java_members.py --help` 和实现，避免依赖过期能力描述。
现有版本按成员类型、可见性和源码调用关系排序；不理解业务重要性，也不解析自然语言
流程或 `MemberOrder` 声明。类注释由 AI 理解后写，当前不能声称脚本会按该注释排序。

若要让脚本执行类注释中的流程，需在用户授权的工具改动范围内实现明确的声明格式、
方法签名匹配、缺失或歧义诊断和测试；不能仅写入注释就宣称能力完成。
排序前先预览影响范围，特别检查重载、回调、递归调用与多个独立入口。

## 功能与并发修改

- 一个状态表达一件事。引擎正在执行、占用本地容量、已收到完成反馈、Future 已完成、
  请求已清理归档是不同事实；不能以其中之一替代其他事实。
- 保留请求、一次尝试、Endpoint generation 和资源句柄的准确身份约束。
  旧回调不能修改新尝试，释放操作不能指向被替换的资源记录。
- 明确每次资源获取、物理发布、执行器接纳和清理的责任交接点。
  提交成功不等于发送成功，取消发出不等于资源释放，完成响应不等于全部清理结束。
- 不在请求锁内执行用户回调、网络等待或昂贵计算。涉及锁覆盖与交接时，
  沿真实路径核对锁顺序、异常分支和回调重入，不能仅凭“有锁”宣称安全。
- 执行器负责它实际接纳的任务。优先复用标准执行器、Future、现有队列及线程归属，
  避免再手工维护一套重复的全局任务计数或集合。确有必要新增跟踪时先解释其覆盖的
  独有事实，以及登记、交接、拒绝、合并和释放如何集中管理。
- 队列为空、线程处于 WAITING 或某个瞬间 activeCount 为零，都不能独立证明清理结束。
  关闭方案必须覆盖同步调用方、已接纳工作、后续任务和晚到回调；关闭执行器前确认
  谁还会提交任务。不能用固定睡眠、过早 shutdown 或忽略拒绝来掩盖交接问题。
- 保持当前契约中的策略选择、等待条件、重试预算及超时语义。标准机制不能直接替换时，
  解释具体阻碍；不能为删除计数或减少类数偷偷改变业务行为。
- 同步清理被替代的入口、包装、字段和测试夹具；不保留两套互相竞争的状态来源。

## 验证与交付

按改动风险验证，使用当前模块配置中的真实类名和测试工具：

- 提交 FlexLB 改动前必须执行并通过仓库的 pre-commit；不能用单独运行格式脚本代替。
  从仓库根目录运行 `python3 -m pre_commit run --hook-stage pre-commit`，检查本次暂存内容。
  每个 checkout 首次使用时安装 pre-commit 并设置 `git config --local core.hooksPath .githooks`，
  让普通 `git commit` 自动执行相同检查。不得用 `--no-verify`、`SKIP` 或停用钩子绕过失败。
- FlexLB Java 钩子检查输入文件的成员顺序及本次新增、修改类的 Javadoc 是否存在、
  有用途或流程摘要并采用多行格式。无自定义行为的简单 record、纯字段 DTO 和简单枚举
  免于强制类注释；结构简单不保证语义自解释，隐含约束仍须审核。未触及的旧类不追溯补齐。Spotless 对整个
  Maven reactor 做只读校验。钩子在隔离的 Python 环境安装解析器，不依赖个人目录。
- 类说明是否准确、是否简短、是否覆盖真实流程仍须 AI 和人工审核；不能声称
  pre-commit 可以理解业务语义或完全阻止绕过本地 Git 钩子的提交。

- 命名、注释、排序等低风险修改不机械新增行为测试。成员移动应核对方法体、注解、
  注释归属、初始化操作和 Lombok 参数顺序；语法树检查不等于完整行为等价证明。
- 审核本次触及的类是否已有准确、简短的类说明，成员组织是否对应说明中的流程；
  删除复述实现或与其他说明重复的长段文字，不能以增加注释行数代替可读性改善。
- 并发或清理修改覆盖接纳与关闭竞争、后续工作交接、提交拒绝、重复通知、取消、
  晚到回调和部分失败。优先用锁存器或屏障构造交错，不靠随机等待碰运气。
- 从 `rtp_llm/flexlb` 使用 Maven Wrapper。针对受影响模块和测试执行验证，例如：

  ```bash
  ./mvnw -pl flexlb-sync -am test -Dtest=<实际测试类> -Dsurefire.failIfNoSpecifiedTests=false
  ./mvnw spotless:check -Pspotless-check
  ```

- 代码修改完成前按仓库要求运行整个 Maven reactor 的 Spotless 检查，不能拿模块检查
  冒充全量通过。成员排序还应运行脚本的检查模式；改脚本时运行其真实回归测试。
  脚本依赖和命令以仓库 README、requirements 和 `--help` 为准。
- 格式化只处理授权范围，遵守当前会话的文本补丁工具要求。全量检查遇到无关改动时，
  查明原因并如实报告，不为让检查变绿覆盖用户工作或无边界扩展格式化范围。
- 架构或行为改变时更新相关现有架构说明；局部改名和排版不新建大篇设计材料。
- 用户要求单独提交纯格式改动时，不能整文件暂存夹带已有功能改动。必要时在隔离工作树
  基于提交基线重现格式转换，审核实际提交树，再保留原工作区的功能修改。
  不未经授权改写历史、清空暂存区、推送或创建额外提交。
- 交付说明具体改动、执行过的验证、失败或未完成项。将“读过源码”“测试通过”与
  “真实环境验证”分开；不要把脚本能力、设计方案或局部测试描述成已经全面落地。

