KeepBash

帮助用户在终端沉淀 Bash 经验（快捷方式 & 工作流）的 Python CLI 工具箱。

• 命令：单命令 kb + 子命令（list/run/save/edit 为 P0，gen/transplant/recap/search 自 P1 起，peek/config 自 P2 起）
• 交互：fzf 选择/预览、vim 编辑、管道组合；无常驻 TUI
• AI：默认本地优先（Ollama），可选云端 OpenAI 兼容端点；AI 输出只作草稿，写入权在用户
• 数据：~/.keepbash/ 纯文本工作流（.wf），KEEBASH_PATH 目录叠加，禁止数据库

文档

文档	说明
架构设计 v0.1	唯一设计基线（E-R → 数据结构 → 算法 → 流程）
基础名词字典 v0.1	统一语义定义（规范形态/边界/禁用形态；机械化门禁语义基线）
项目领域约束	领域约束与明确不做
开发模式	issue 状态机与实施流程
场景设计	场景输入（事实来源）
P0 验证证据	P0 闭环验收口径与可复核运行证据
P1 验证证据	P1 AI 闭环（gen/transplant/recap/search）验收口径与可复核运行证据
P2 验证证据	P2 教学层 kb peek 命令拆解（静态不执行）验收口径与可复核运行证据
P2 帮助引导证据	P2 kb 帮助典型用法引导（命令族逐条示例）验收口径与可复核运行证据
P2 AI 配置子命令证据	P2 kb config（show/check/向导）验收口径与可复核运行证据

用法（P0 四命令）

提示：kb（无参数）或 kb -h 的帮助自带命令族典型用法引导（P2 起，设计 §3.4「帮助引导」），新用户无需外部文档即可上手。

# 沉淀：vim 预填模板编辑后保存（--type stable|expedition，探险自动带 # EXPIRE 7 天）
kb save deploy_k8s --type stable

# 搜索：fzf 选择/预览 + 处方三色灯（fzf 缺失降级为编号列表）
kb list

# 执行：处方体检（绿→执行 / 黄→警告后执行 / 红→拒绝，--force 老鸟后门）
kb run deploy_k8s

# 编辑：vim 打开工作流（按名称或路径）
kb edit deploy_k8s

• 工作流为纯文本 .wf（赋值 NAME=value / 命令 / 注释 + 头部 # ENV_PRESCRIPTION: 处方），可直接 cat/grep/git diff。
• 搜索叠加 KEEBASH_PATH（个人 ~/.keepbash/ 恒在前，同名遮蔽共享库）；写入只进个人目录。
• 执行器遇错即停；赋值经环境文件显式传递（失败时打印路径供 cat 调试）；嵌套 kb run ./sub.wf 继承父环境。
• 本地优先：零运行时第三方依赖，离线完全可用。

用法（P1 AI 命令）

# AI 生成草稿（意图 → 草稿 → 确认 y/e/n → 保存为工作流）
kb gen 部署 k8s

# AI 移植补丁（处方红灯或显式指定 → 最小改动 → 确认 → xxx_local.wf 静态分叉）
kb transplant deploy_k8s

# AI 复盘脱敏执行历史（graveyard/ → 去具体化 → draft_*.wf 到 drafts/）
kb recap -n 20

# 联网搜索（默认关闭，须显式配置 OPENCODE_GO_API_KEY；结果只作草稿缓存 web_cache/）
kb search 北京天气

• AI 默认本地 Ollama（OLLAMA_HOST/OLLAMA_MODEL）；云端 OpenAI 兼容端点须显式配置（OPENCODE_GO_API_KEY，OPENAI_BASE_URL/OPENAI_MODEL 可选）。
• AI 输出必经草稿 + 用户确认；执行历史默认脱敏记录（KEEBASH_HISTORY=off 关闭）。
• 详细设计见 架构设计 v0.1 §3.4/§3.5/§4.3/§4.4。

用法（P2 AI 配置管理）

# 展示生效配置（密钥掩码 + 来源 env/默认）
kb config show

# 诊断三色灯（连通/模型/密钥/超时，只读无副作用；全绿 exit 0，有红 exit 1）
kb config check

# 交互向导：模式 → 密钥（getpass 隐藏，仅内存验证）/端点/模型 → export 引导 → 自动 check
kb config

• 纯环境变量载体，不引入配置文件；密钥不得落盘/回显（字典 #22 边界），向导只打印 export 引导行（密钥位占位符）供自行写入 ~/.bashrc。
• 详细设计见 架构设计 v0.1 §3.6。

用法（P2 教学命令）

# 命令拆解（教学层：静态拆解为原子步骤+进程树，绝不执行；无 AI、无网络）
kb peek "kubectl get pods | jq '.items[].name' | sort -u"

• 拆解输出：步骤编号 + 连接符教学标注（管道/与/或/分号/后台）+ 进程树；子 shell 与命令替换标注不深递归。
• 绝不执行：拆解含副作用命令（touch/重定向）不产生任何副作用文件（领域不变量）。
• 详细设计见 架构设计 v0.1 §5.5。

开发

python -m venv .venv && source .venv/bin/activate
pip install -e .
pytest
kb --version

前置工具：fzf（kb list/kb run 选择与预览）、vim（kb edit）。