我不太喜欢那种拿到一个项目代号就开始猜谜的协作方式，但前阵子我确实接手了一个内部工具，代号就三个字符：cua。没有文档，没有设计稿，连一句话需求都没写。和人对齐之后才发现，这个 cua 并不是某个现成英文缩写的标准解，团队想表达的是 Command-line Universal Assistant，也就是把日常所有重复性操作收敛成一条命令的轻量执行器。
当时我第一反应是：市面上不是有 Makefile、npm scripts、GitHub Actions 吗？为什么还要自己做一个？等我把实际场景捋顺之后，想法变了。很多项目里的重复操作根本不在同一个工具链里，有可能上午是前端构建，中午是数据库备份，下午是登录跳板机排查日志，它们分散在多个目录、多套命令甚至多台机器之间，Makefile 管不住，npm scripts 只管得了前端，alias 又只能解决单机单目录的问题。我需要的是一个能定义任务、组合任务、带参数透传和依赖关系的统一入口，于是 cua 就从代号变成了一个真正落地的命令行工具。
这篇就把我从零开始设计、编码、踩坑到日常使用的全过程写出来。里面没有高深算法，绝大部分代码都非常直白，但有不少细节是你自己动手时容易忽略的。如果你也有同样的“重复操作太多、记不住命令”的困扰，或者你正准备给自己的团队做一个内部小工具，这篇文章应该能帮你少走不少弯路。
1. cua 的定位：不是又一个脚手架，而是把零散命令变成团队共识
刚开始设计 cua 的时候，最容易被带偏的方向是“做一个万能的自动化框架”。我当时也差点走进这个死胡同，想着把任务编排、并行执行、远程分发、权限控制全部做进去。幸好先冷静下来，回到最根本的问题：cua 到底要解决谁的什么痛苦？
1.1 核心价值是把“人的记忆”替换成“文件约定”
我见过太多真实场景：发布前要跑三条命令，第一条是前端构建，第二条是后端打包，第三条是把产物传到某个服务器。这中间还夹杂着各种环境变量，比如 NODE_ENV、BUILD_NUMBER、DEPLOY_TARGET。每个人都在自己的终端里手输这几条，有一个人忘设环境变量，产物就带错配置，排查半小时才发现。
cua 要做的第一件事，就是把这一串动作写进一个 YAML 文件里，命名成一个任务叫 release。以后不管是老员工还是实习生，只需要执行cua run release就能得到一致的结果。人的记忆会出错，但文件约定不会。这是整个工具最核心的价值。
1.2 和 Makefile、npm scripts 相比，cua 更关注跨项目的统一体验
做开发的人第一个会问：Makefile 不够吗？npm scripts 不够吗？Windows 批处理不够吗？我在确定方案之前，专门列过一个对比表，把几个常见方案的真实限制摆在了桌面上。
| 方案 | 擅长场景 | 明显短板 |
|---|---|---|
| Makefile | C/C++ 项目里的编译链路 | 语法难懂，Windows 环境需要额外模拟层，编写复杂任务时像在写上古代码 |
| npm scripts | Node 项目内的构建命令 | 绑定 package.json，离开 Node 项目就没法用，跨语言场景很别扭 |
| shell 函数/alias | 单个用户自己的快捷指令 | 无法共享给团队，换台机器就没了，没有参数校验 |
| CI/CD 平台流水线 | 提交代码后的自动化流程 | 本地开发时执行成本高，不适合短平快的日常操作 |
| cua | 本地日常重复操作的统一入口 | 需要自己维护，初期需要一点投入成本 |
我没有否定上面的工具，它们在各自领域都很成熟。但 cua 的目标场景比较特殊：它希望成为团队成员之间一种约定，把发布、备份、检查、清理这些动作都收拢到同一套体系里。它不是要取代 CI/CD，而是把 CI/CD 管不到的那些手工动作管理起来。
1.3 适合谁来用：运维、全栈开发和小团队长期维护者
如果你是一个大团队里的 Java 开发，代码提交之后有专门的发布平台，那 cua 对你的价值确实有限。但如果你是运维、全栈开发，或者一个十人左右技术小组里的核心维护者，你会经常发现自己成了“人肉操作手册”。每次同事问“这个服务怎么重启”“测试环境怎么构建”“数据库备份脚本在哪”，你都得重复回答一遍。
cua 适合你的理由很简单：把答案写进项目目录下的配置文件里，问的人自己看文件就能解决大部分问题。你只需要偶尔 Review 一下任务定义是否合理。这篇文章后面的实现，主要也是围绕这种“小工具解决大重复”的思路展开的。
2. 需求拆解：动手写代码之前，我先逼自己回答了五个问题
很多命令行工具做出来不好用，不是代码写得烂，而是需求没理清。我在正式实现 cua 之前，花了两个晚上把下面的问题写在了纸上，每一题都落到具体场景，才开始动键盘。
2.1 第一个问题：任务的输入输出边界到底在哪
一个任务可能会被多次执行，每次执行时参数可能不一样。比如备份数据库，今天要备份订单库，明天要备份用户库，数据库名就是输入参数。又比如发布到测试环境还是预发环境，环境名也是输入参数。
所以 cua 的第一版必须支持参数透传，而且参数要在任务定义里显式声明，不能隐式依赖 shell 的全局变量。我当时的做法是：定义任务时用{db_name}这种占位符，执行命令时通过cua run backup --db-name orders这样的方式传入，由 cua 负责替换。
还有一个边界问题：任务执行之后会产生什么输出？是日志、是产物文件，还是退出码？我的决定是，cua 只保证“命令以正确的目录、正确的环境变量被启动，并正确传递退出码”，至于命令本身输出什么，原样透传到当前终端。这样一来，cua 不需要强行解析每个工具的日志格式，保持简单。
2.2 第二个问题：任务之间需不需要依赖关系
很多重复操作是有顺序的。部署必须先构建再上传，构建又可能依赖依赖安装步骤。我当时想过引入有向无环图做拓扑排序，让任务可以声明依赖多个前置任务，cua 自动决定执行顺序。
后来我克制住了。第一版我只需要“按声明顺序串行执行”和“显示标注 dependencies 的先后执行”就够了。拓扑排序虽然听起来漂亮，但会带来循环依赖检测、并行执行日志交错等一系列复杂度。对一个团队内部工具来说，不是每一层复杂度都有价值。最终 cua 采用了串行依赖池：一个任务可以声明依赖哪些前置任务，cua 会深度优先执行完所有依赖，再执行当前任务，如果发现循环依赖就直接报错。
2.3 第三个问题：跨平台还是只跑一种系统
这个问题很现实。团队里有人用 macOS，有人用 Windows，有人用 Linux。如果 cua 只能在 macOS 上跑，Windows 用户就等于被抛弃了。我最初的方案是选择 Python 作为运行语言，这是跨平台支持最省心的选择之一。Python 3.8 以上版本基本可以无缝跑在三种主流系统上，而 Typer 这个命令行框架又能帮我把参数解析做得非常舒服。
但跨平台不等于命令本身跨平台。YAML 里写的命令如果用了rsync，Windows 上可能就没有；如果用了bash -c，cmd 和 PowerShell 环境又不一样。所以我在 cua 里做了一个命令解释器选择：允许每个任务声明自己用什么 shell 来执行，默认在 Linux/macOS 上用/bin/sh，在 Windows 上用cmd.exe。对于实在跨不了平台的任务，配置里可以标注platforms字段，cua 会检测当前系统，不匹配就跳过并提示。
2.4 第四个问题：失败之后怎么处理
任务执行不可能永远成功。我见过很多脚本失败之后还继续往下走的，最后生成一个半成品当成成功产物，问题排查起来特别痛苦。cua 在这块的原则非常明确：任何一条命令退出码非零，立即中止整条任务链，并把错误码原样返回给用户。同时，日志里会标注当前执行的是哪个任务、哪条命令、在哪个目录下。
为了避免出现“命令死了但 cua 还挂着”的假象，我设置了默认超时时间，单个任务最长执行 30 分钟，超过自动杀掉。这个值可以在任务定义里按需覆盖。这么做不是为了给用户找麻烦，是为了让失败尽量早地暴露出来。
2.5 第五个问题：配置文件放在哪里，谁来维护
cua 的定位是“项目级工具”，所以配置文件默认放在项目根目录下，命名为.cua.yaml。团队成员只需要 clone 代码，就能看到这个文件，不需要额外初始化。但有的配置属于用户个人习惯，比如某些私有环境变量、本地路径差异，不能写进公共仓库。为此 cua 支持两个层级的配置合并：项目级.cua.yaml和用户级~/.cua/config.yaml，用户级配置里的同名任务会覆盖项目级定义。
这个设计解决了一个很实际的痛点：团队可以维护一份标准的任务模板，而个人可以在自己电脑上对某些细节做微调，且不会污染公共配置。
3. 核心实现：任务编排、变量替换与命令执行
理清需求之后，实现就变得顺理成章了。这一节我会把 cua 最核心的代码逻辑拆开来讲，重点不在一行行贴完整代码，而是把几个容易设计错的地方交代清楚。
3.1 配置文件的数据结构：先定义 YAML 的规范
一个工具的配置文件格式，决定了它用起来顺不顺手。我设计的.cua.yaml核心结构如下：
version: 1 vars: registry: registry.internal.lan namespace: web tasks: build: desc: 构建前端静态资源 cmd: npm run build cwd: ./frontend env: NODE_ENV: production timeout: 600 backup: desc: 备份 mysql 数据库到本地 backup 目录 cmd: mysqldump -u root -p"{{password}}" "{{db_name}}" > "backup/{{db_name}}-{{timestamp}}.sql" timeout: 1800 deploy: desc: 构建并部署到测试环境 cwd: . env: DEPLOY_ENV: testing depends: - build cmd: rsync -az --delete ./frontend/dist/ deploy@test-host:/data/app/dist/我解释一下关键字段：
vars是全局变量，可以用{{var_name}}的形式被各任务引用。tasks是任务字典，任务名建议用短横线命名，比如start-dev、build-prod。cmd是实际要执行的命令，支持换行，支持管道和重定向。cwd是执行命令时的工作目录，相对路径基于配置文件所在的目录。env是任务级环境变量，会合并进当前进程环境变量后再传给子命令。depends声明依赖任务数组。timeout是超时秒数，不写默认 1800 秒。
3.2 任务执行器：subprocess 的高阶用法，没有想的那么简单
如果只是用 Python 的os.system(cmd)，功能确实能跑，但会有两个问题：拿不到实时输出、没法超时控制。所以我选择了subprocess.Popen，并且做了下面这几件事：
import shlex import subprocess from typing import Optional def run_command(cmd: str, cwd: Optional[str], env: Optional[dict], timeout: int): full_env = {**os.environ, **(env or {})} proc = subprocess.Popen( cmd, shell=True, cwd=cwd, env=full_env, text=True, bufsize=1, ) try: return_code = proc.wait(timeout=timeout) except subprocess.TimeoutExpired: proc.kill() raise RuntimeError(f"命令执行超时，已强制终止：{cmd}") return return_code这里有一个很多人会犯迷糊的点：shell=True和shlex.split之间的关系。如果你的命令里包含管道、通配符、重定向，就必须shell=True，因为这些都是 shell 语法，单纯用Popen加参数列表没法表达。如果你的命令完全是单条可执行文件加参数，且没有任何 shell 语法，那用shlex.split(cmd)拆成列表再shell=False更安全。
我在 cua 里做了一个折中：默认shell=True，因为任务定义里的命令就是要尽量让用户自由地写 shell 命令。但我在文档里明确标注了一条安全建议：千万不要把未经校验的外部输入直接拼接进命令字符串，尤其是从网络请求拿到的参数。
3.3 变量替换机制：模板语法和转义问题
变量替换看起来简单，但实际写起来有个细节特别容易踩坑：如果{{db_name}}里的值包含单引号或分号，直接拼进命令字符串会破坏原有命令结构，甚至引发意外执行。虽然 cua 这种内部工具主要面向可信用户，我依然建议做一层转义。
我的处理逻辑是：对于包裹在双引号里的{{var}}，替换时只做整体替换，不做二次解释；对于裸替换{{var_raw}}，替换前先对单引号、双引号、反引号、$ 和分号做转义。同时，替换发生在命令解析之前，也就是说：先解析出模板占位符，替换成最终字符串，再交给 subprocess 执行。伪代码如下：
import re from datetime import datetime def render_template(cmd: str, variables: dict) -> str: def replace(match): key = match.group(1).strip() value = variables.get(key, "") if match.group(2) == "raw": return shlex.quote(str(value)) return str(value).replace('"', '\\"').replace("$", "\\$") return re.sub(r"\{\{\s*(\w+)\s*(?::raw)?\}\}", replace, cmd)内置变量timestamp会在每次执行时生成，格式类似20250612_143005，方便做备份目录。另一个内置变量date是YYYY-MM-DD。这两个内置变量虽然不起眼，但备份类任务天天都会用到。
3.4 任务依赖链：深度优先，串行执行，循环检测
任务依赖的实现，我选择了一个经典但足够简单的递归方式：
visited = {"_running": set(), "done": set()} def execute_task(name, task, config, cli_params): if name in visited["done"]: return if name in visited["_running"]: raise RuntimeError(f"检测到循环依赖：{name}") visited["_running"].add(name) for dep_name in task.get("depends", []): dep = config["tasks"].get(dep_name) if not dep: raise RuntimeError(f"任务 {name} 依赖了不存在的任务 {dep_name}") execute_task(dep_name, dep, config, cli_params) visited["_running"].remove(name) visited["done"].add(name) do_execute(name, task, cli_params)这个实现的好处是代码量少，逻辑直观，团队里其他人看一遍就能理解。代价就是没办法做并行执行，但对大部分内部维护场景来说，串行已经足够。如果你真的需要并行，建议不要在这里打补丁，而是引入真正的任务队列系统，语义会更清晰。
3.5 CLI 参数透传：用 Typer 快速搭出称手的人机交互
Typer 是 Python 生态里我非常喜欢的一个命令行库，它基于 Click，但代码风格比 Click 现代不少。用它定义 cua 的子命令只需要这样：
import typer from typing import Optional app = typer.Typer() @app.command() def run(task: str, **kwargs): """执行指定任务""" ...但参数的透传有个坑：任务参数不是固定命名的，不同任务需要不同参数。Typer 适合定义静态参数，对于“任意动态参数”这种场景并不合适。我的解决方式是：run命令接收一个标准参数--set key=value，可以重复传入多次，由 cua 内部统一解析。例如：
cua run backup --set db_name=orders --set output_dir=/data/backup这样既绕开了 Typer 对参数列表的限制，又保持了命令行的可读性，同时便于未来扩展成从环境变量文件读取参数。界面交给 Typer 处理，业务逻辑完全集中在我自己的渲染函数里，维护起来很清爽。
4. 四个在真实使用中差点让我崩溃的坑
这一节没有鸡汤，全是实战换来的血泪教训。每一个坑都伴随一个真实场景，如果你准备自己写类似工具，强烈建议直接跳到对应小节看。
4.1 YAML 解析的布尔陷阱：on 被转成了 True
第一次写测试任务时，我给某个命令加了一个环境变量VERBOSE: on，想表达“开启详细日志”。结果跑到任务里，子进程收到的环境变量是字符串"True"，不是"on"。原因很简单，YAML 1.1 规范会把on、off、yes、no都解析成布尔值，而 Python 的yaml.safe_load就遵循这个规范。
这个问题在复制粘贴别人的 YAML 配置时尤其隐蔽，因为你在env下面写DEBUG: off，做出来的效果可能会完全相反。我的解决办法是：加载配置时对布尔值做检测，如果是布尔类型就转换成对应的字符串"true"/"false"，同时在 cua 的文档里约定了统一写法：严格使用true和false，不要使用on/off/yes/no。0和1的问题同理，显式转字符串。
4.2 工作目录的坑：cwd 相对路径飘忽不定
cua 的设计是允许用户在任意路径下执行cua run xxx，比如在项目根目录的子目录里执行。第一版我没有对 cwd 做归一化，结果任务的相对路径全乱套了。例如任务定义中写cwd: ./frontend，用户在project/packages/app下执行时，实际工作目录就变成了project/packages/app/frontend，而大概率这个目录不存在。
正确的做法是：所有相对路径都相对于配置文件所在位置，先解析成绝对路径，再传给 subprocess。cua 在加载配置文件时，会先把config_root计算出来，然后依次拼接cwd和需要引用的路径，最终得到一个绝对路径。示例逻辑如下：
from pathlib import Path config_root = Path(config_file).resolve().parent task_cwd = Path(task.get("cwd", ".")) if not task_cwd.is_absolute(): task_cwd = config_root / task_cwd exec_cwd = str(task_cwd.resolve())这样无论用户从哪个目录进入，任务的工作目录都能保持稳定。这个改动看起来很小，但对于所有依赖相对路径的命令，比如读取配置文件、生成产物目录等，都是决定性的。
4.3 跨平台命令差异：rsync 在 Windows 上就是跑不了
我们的团队里有一个 Windows 用户，他在本地跑cua run build时一切正常，到了cua run deploy就直接报“rsync 不是内部或外部命令”。这个问题不是 cua 能靠代码解决的，因为命令本身依赖了非跨平台工具。
我给 cua 加了一个platforms字段，任务定义里可以写：
tasks: deploy-linux: platforms: [linux, macos] cmd: rsync -az --delete ./dist/ user@test-host:/data/app/dist/ deploy-win: platforms: [windows] cmd: PowerShell -Command "Copy-Item -Recurse -Force dist\\* \\\\nas\\share\\dist\\"cua 在执行任务前会依据sys.platform判断当前平台是否匹配，不匹配就给出明确提示：当前平台不支持此任务，请切换到支持的环境。这个机制能避免很多无意义的报错排查，让用户第一眼就知道问题不在命令本身，而在平台限制。
4.4 退出码没有透传：CI 里出了绿，本地却看不到错误
这是最隐蔽的一个坑。cua 内部把任务包装成 try-except，第一版我在执行器里捕获异常后只打印了一段“任务失败”的提示，然后进程直接退出，退出码固定为 0。结果如果别人把cua run test接到 CI 流水线里，就算测试命令返回了非零退出码，CI 也会认为整个步骤通过了。
这个问题的严重性不用我多说。修复方式就是保证 cua 进程的最终退出码与最近一次失败任务完全一致。具体来说，无论哪一层抛异常，都要在最外层捕获后调用raise typer.Exit(code=return_code)，把非零状态真正传导给操作系统。改完之后，cua 在 CI 里才算是一个合格的命令执行器。
5. 让 cua 真正好用起来：配置分层、日志体验与自动补全
功能能跑只是第一步，工具好不好用，全看细节。cua 真正变得“顺手”，是在我补完下面几个能力之后。推荐文章里写功能时大多一笔带过，实际体验差距巨大。
5.1 配置分层：项目级、用户级、环境变量，三层各有各的用途
我在前面提到了项目级.cua.yaml和用户级~/.cua/config.yaml，但三层里还有一层容易被忽略：环境变量。cua 在解析配置时，支持在变量值里嵌入${ENV_VAR}语法，比如：
vars: registry: "${REGISTRY_ADDR:-registry.internal.lan}"这里:-后的内容表示默认值。也就是说，如果系统环境变量里没有REGISTRY_ADDR，就使用默认地址。这个能力让同一个配置文件能同时适用于开发环境和 CI 环境，不需要维护两份文件。合并顺序很有讲究：系统环境变量优先级最高，其次是命令行--set参数，然后是用户级配置，最后是项目级配置。我在加载时会严格按这个顺序覆盖，避免出现“明明改了配置却生效不了”的问题。
5.2 日志输出：把每一步都变成一眼能看懂的进度
命令行工具的日志对用户体验的影响，比很多开发者想象得大。如果只把原生命的 stdout 和 stderr 原样打出来，任务一多就会非常乱。我在 cua 里做了三重增强。
首先，每个任务开始前打印一行结构化信息：任务名、描述、工作目录、执行模式。任务结束后打印耗时和状态。其次，对输出做了颜色区分：普通输出保持原样，stderr 用红色标出，warning 用黄色，成功用绿色。最后，支持--quiet参数，在 CI 环境或脚本嵌套时可以只输出最终状态和错误信息，避免日志刷屏。
这里有一个细节：颜色输出在终端里能用，但如果接入了 CI 日志系统，ANSI 颜色码会变成一堆乱码。cua 的做法是检测环境变量NO_COLOR和CI，只要检测到就自动关闭颜色，保留纯文本输出。这个约定在外开源工具里已经很常见，但是自己实现时特别容易忽视。
5.3 shell 自动补全：省掉记忆负担的最后一块拼图
命令多了以后，总要记住任务名。如果团队有二十多个任务，靠脑子记确实费劲。Typer 内置了自动补全支持，实现起来非常顺滑：
cua --install-completion bash cua --install-completion zsh cua --install-completion fish安装之后，输入cua run再按两次 Tab，cua 会自动列出当前项目所有可用的任务名。这个能力让新成员上手成本进一步降低，他们不需要打开 YAML 文件就能知道有哪些任务可用。我把这一步写进了 README 的快速开始部分，并建议每个使用者在开发环境初始化时执行一次。
5.4 任务清单和预览：执行之前先看清楚会发生什么
一个容易被低估的功能是cua list和cua preview。前者会列出所有任务名、描述和是否支持当前平台；后者则会展示某条任务最终将被执行的命令渲染结果，但不真正执行。
cua preview对不熟悉模板替换的用户非常友好，比如cua run backup --set db_name=orders之后，先执行cua preview backup --set db_name=orders，就能看到mysqldump -u root -p"..." "orders" > "backup/orders-20250612_143005.sql"这样的完整命令。这样在真正执行之前，就能确保变量替换正确，避免搞掉一份重要数据。这个功能实现起来很简单，就是把渲染函数单独拆出来复用，但它对降低操作风险的作用非常大。
6. 实测场景：三个我每天都在用的 cua 任务
普通的示例任务大家都会写，真实生产环境里天天跑的才有参考价值。下面分享三个我自己在日常工作中固定使用 cua 执行的场景，代码直接可用，你可以照着改。
6.1 场景一：规范发布，避免“漏提交”和“提交信息乱写”
每次发布前我都要做三件事：查看 git status 确认没有多余文件、按规范写提交信息、打 tag 并推远端。这些动作没有技术难度，但很容易忘，尤其是超过一周没发布的时候。我把它们聚合成了两个任务。
tasks: check-clean: desc: 检查工作区是否干净 cmd: | set -e if [ -n "$(git status --porcelain)" ]; then echo "工作区有未提交变更，请先提交：" git status --short exit 1 fi echo "工作区是干净的" tag-release: desc: 打版本 tag 并推送远端 cmd: | set -e if git rev-parse "v{{version}}" >/dev/null 2>&1; then echo "tag v{{version}} 已存在，请检查版本号" exit 1 fi git tag -a "v{{version}}" -m "release: v{{version}}" git push origin "v{{version}}" echo "已推送 tag v{{version}}"通过cua run check-clean && cua run tag-release --set version=1.4.2，整个过程被压缩成了两条命令，而且失败即停止，不会出现“tag 打了但代码没推全”的尴尬情况。
6.2 场景二：本地构建并同步到局域网测试服务器
我们有个内部工具，前端是静态资源，后端是 Node 服务。以前每次联调都要手动构建前端，再 scp 到指定测试机，还要远程重启服务。写成 cua 任务后：
tasks: dev-sync: desc: 构建前端并同步到局域网测试机 cwd: . cmd: | set -e npm run build rsync -az --delete ./dist/ dev@192.168.1.20:/opt/myapp/dist/ ssh dev@192.168.1.20 "sudo systemctl restart myapp-web" timeout: 300这条任务看起来简单，但它把“本地构建 + 网络传输 + 远程操作”完整串了起来。只要开发机上配置了 SSH 免密登录，执行起来非常顺滑。这里我特别注意了set -e，因为整条命令是用&&或换行拼接的，任何一个环节失败，后续都不应该继续。
6.3 场景三：数据库备份，自动保留最近 N 份
备份脚本的需求是：每天备份多个数据库，保留最近 7 份，旧的自动清理。过去这个功能放在 crontab 里，写死路径和密码，换人维护基本就失效了。改成 cua 任务后，我可以手动触发，也可以配合系统定时任务调用。
tasks: backup-db: desc: 备份多个数据库，保留最近 7 份 cmd: | set -e db_list="{{db_list}}" backup_dir="{{backup_dir}}/{{date}}" mkdir -p "$backup_dir" for db in $db_list; do mysqldump -u backup -p"{{db_password}}" "$db" | gzip > "$backup_dir/$db.gz" echo "已备份：$db" done ls -dt {{backup_dir}}/2* | tail -n +8 | xargs rm -rf echo "备份完成，目录：$backup_dir" timeout: 3600用法是cua run backup-db --set db_list="orders users" --set backup_dir=/data/backup。数据库密码建议放在用户级配置里，不要写进项目公共文件。这里有一个小细节：清理命令只保留最近 7 份，我是按目录名排序，格式里的{{date}}正好是YYYY-MM-DD，字典序即时间顺序，所以tail -n +8表示从第 8 个开始删除，准确且安全。
7. 扩展方向：让 cua 从一个工具变成一套习惯
cua 做到这个程度，已经能解决我 80% 的重复操作问题了。剩下 20% 的需求，我在日常使用中逐渐整理出了几个值得继续扩展的方向。
第一个是加密变量的支持。随着用户级配置里的密码和 token 越来越多，纯文本存放会越来越让人不安。我计划的方案是引入一个cua secret set key命令，把敏感信息用本机密钥加密后存到~/.cua/secrets.json，在执行任务时，只有被{{secret:key}}语法引用的变量才允许解密并注入子进程。这个方案能兼顾团队共享配置与个人私密信息的安全隔离。
第二个是预置模板库。很多任务在多个项目里长得非常像，比如“构建前端”“备份数据库”“检查工作区”。如果 cua 能支持从远程仓库拉取预置任务模板，新项目初始化时就只需要cua init --template node-rsync这样的命令，会大幅降低上手门槛。目前我用的是项目内复制粘贴的方式，语义上还差一点，但已经能解决实际问题。
第三个是与 CI 流水线的更深集成。现在 cua 只保证退出码正确，未来还可以把任务执行的结构化日志导出成 JSON，方便 CI 平台解析。比如cua run release --format json，输出里包含每个任务的状态、耗时、错误信息，GitLab CI 或 Jenkins 可以直接把这段 JSON 作为流水线报告的一部分。
不过我并不打算在短时间内全部实现。命令行工具一旦做得太重，反而会失去“随手一敲”的轻快感。保持核心稳定，把常用功能做好，然后在需要的时候才慢慢加扩展，是我接下来会坚持的节奏。
根据我自己的使用体会，这类内部工具最怕的不是功能少，而是做成了没人敢碰的“大怪兽”。cua 能每天都在我的终端里被调用，正是因为它的边界很清晰：只负责把零散的 shell 命令组织成可复用、可分享的任务，其余事情全部交给系统工具和用户自己去组合。如果你也想做类似的东西，我建议第一版务必克制，先跑通三个真实任务，再考虑更复杂的编排能力。工具的价值不是代码量，而是它让团队少踩了多少重复的坑。
