# Bash Context Transaction Skill

## 目标

生成 Bash 工具脚本时，把复杂 Bash 流程拆成多个可以独立调试、灵活组合的步骤。

## 核心设计原则

### 1. 当函数参数需要传入 Bash 数组时，优先传入“数组变量名”，并在函数内部使用 `local -n` 创建引用。

### 2. 所有返回值都通过 local -n 来返回，并且变量名前缀加上ret_ 函数签名返回值写在前面，  Bash 函数的 return 只用于返回整数状态码

### 3. 使用fast fail 模式， 不要带病运行

### 4. 所有运行状态放进 ctx 关联数组， 固定，禁止对外输出全局变量

### 5. 函数api采用下面的设计模式 （基于 关联数组 CTX的 灵活可组合模式）

declare -Ag CTX=()
创建上下文关联数组。

init_${整体功能名称}_env CTX ...
固定模式。
初始化当前整体功能的运行环境。
写入 ctx，并创建后续 step_xxx 需要使用的副作用资源。

step_${功能名称} CTX ...
灵活模式。
执行具体业务步骤。
step 可以有自己的参数。
多个 step 可以单独调试，也可以自由组合成完整流程。

clear_${整体功能名称}_env CTX ...
固定模式。
清除 init_${整体功能名称}_env 创建的副作用。
必须可重复调用。
不得误删外部原本存在的资源。
### 6. 写几个test 测试主流程的函数（不要太多）， 里面要按照5的模式调用，给出详细中文注释， 每一个都可独立执行

### 7. 文件拆分 基础拆成三个部分

第一个 base_${整体功能名称}.bash 存放公共工具函数
第二个 function_${整体功能名称}.bash 存放符合5模式的函数  注意不要画蛇添足添加别的模式
第三个 test_${整体功能名称}.bash   存放符合6模式的函数  注意详细中文注释
三个文件有  三包含二包含一的include 关系
### 8. 日志，注释 都采用中文
