# 选择、重构与扩展 BLOGE 能力

## When to use

选择表达、减少嵌套条件、提取复用、增加函数或 Operator 时使用。先读[实践参考](/agent/zh-CN/v/0.9.9-RC1/reference/coding-practices.md)，选择适用 BP 条目。

## Inspect first

- 确认有效 BLOGE 版本、实际 function registry/catalog、Operator 注册、约定和测试。
- 列出事实、认可答案、输出消费者、外部动作和失败边界。
- 检查 null、类型、顺序、数值、locale、时间和 ID。同名能力不等于语义吻合。
- 实例函数支持外部读取；优先 Operator 的依据是独立控制需求，而不是语法禁止。

## Required inputs

明确目标行为、输入输出合同、effect、确定性、规模/成本、复用消费者、维护者和授权范围。政策变更需要认可答案；缺失时报告缺口，不从当前候选实现生成。

## Implementation path

1. 字段读取优先 binding，通用轻量计算先查既有函数，多字段投影再用 transform（BP-01）。
2. 有界计算先提取 helper；graph 作者需要调用时再注册 typed function，保留显式参数和合同（BP-02）。
3. 需要独立 retry、timeout、替换、观测或容量时优先 Operator；多步能力用 graph/subgraph 组合（BP-03、BP-12）。
4. 多事实交互时评估决策表，branch 消费结果；明确优先、互斥、同输出重叠或累积语义（BP-06、BP-07）。
5. 分开选择项目、团队库、可选模块或 core。公共提案需跨业务同一语义、组合缺口、边界合同、成本、维护者和兼容方案（BP-04、BP-05）。
6. 保留输出、依赖、业务身份、降级、恢复和资源边界；协调重试责任，避免叠加放大（BP-08—BP-13）。
7. 核对固定答案及前后完整输出，分别观察未选路径与禁止 effect，再注入可揭示错误的变异（BP-14）。
8. 公共扩展交付具体提案；应用重构不自动授权修改 BLOGE 核心或发布连接器。

## MUST / SHOULD / MAY

- **MUST**：检查实际注册，不发明函数、Operator 或 DSL 字段。
- **MUST**：报告表达、执行责任、维护范围和否决方案。
- **MUST**：保留优先级、schema、业务身份和外部未知结果；元数据声明不证明行为。
- **MUST**：使用独立标准答案验证路径与 effect，不用当前输出生成 expected。
- **SHOULD**：超过 3 个独立条件时评估决策表，不自动迁移，也不写成强制 lint。
- **SHOULD**：有独立控制需求的 I/O 或昂贵纯计算优先考虑 Operator。
- **MAY**：保留清晰领域方法，或求值与一致性边界适合且已说明的外部读取函数。

## Failure patterns

- 高分黑名单申请被批准：检查 first 顺序；unique 冲突不等价于业务拒绝。
- collect 总有正常说明：当前 otherwise 无条件追加。
- 同键仍重复产生 effect：检查提供方/应用去重，EffectPort 的键声明不抑制调用。
- helper 被过早纳入 core：先给出不同消费者、共享语义和明确组合缺口。
- 万能 Operator 有多个无关 mode：区分接线、供应商适配和不同业务保证。

## Validation

运行[工作坊 Maven 工程](/assets/v/0.9.9-RC1/chapters/34-labs/assets/coding-practices/README.md)。12 个固定 Case 比较七个风险字段、全部八个审核表单字段、路径和模拟动作计数；另有规则顺序、Oracle 替换、unique、collect、typed function、EffectPort 六项测试。

四项资金测试覆盖显式信用查询、响应丢失重试、超时对账、键/金额冲突，以及隐藏读取与叠加重试的配对重构。对照重构前 9 次调用与重构后 3 次调用，两者保留同一项已提交 effect。一项恢复测试连续创建三个 manager：次数保留为 1、2、3，新 round 提交后才归零。工作坊预期 23 项通过、无跳过，不证明生产容量或真实提供方行为。

同目录的 `run-runtime-seams.sh` 执行恢复进展、租约权限、旧 checkpoint 写入拒绝与实际 worker 容量四组套件，要求目标报告非零执行、无跳过和失败。

在目标应用另验 port contract、恢复与依赖。输出文件变更、理由、实际命令/数量及未验证范围，不把工作坊结果当成目标项目已经执行的证据。

## Evidence

- [编码实践手册](/zh-CN/v/0.9.9-RC1/appendix-j-coding-practices)。
- [综合工作坊](/zh-CN/v/0.9.9-RC1/34-labs)。
- [项目函数](/assets/v/0.9.9-RC1/chapters/34-labs/assets/coding-practices/src/main/java/com/leanowtech/bloge/book/practices/LoanTextFunctions.java)。
- [重构后 DSL](/assets/v/0.9.9-RC1/chapters/34-labs/assets/coding-practices/src/main/resources/loan-after.bloge)。
- [固定答案](/assets/v/0.9.9-RC1/chapters/34-labs/assets/coding-practices/src/main/resources/oracles.csv)。
- [可执行测试](/assets/v/0.9.9-RC1/chapters/34-labs/assets/coding-practices/src/test/java/com/leanowtech/bloge/book/practices/CodingPracticesTest.java)。