终端里的雌小鬼，陪你写代码。
A little attitude for your Zsh.
Zako 是一个用 Rust 编写的轻量 Zsh 雌小鬼终端搭档：启动时打个招呼，命令完成时偶尔点评，连续失败时会越来越不客气，并为 gti、git comit 这类拼写错误提供纠错建议。
它依附于你现有的 Zsh，通过 Hook 接收命令事件；命令执行、补全和作业控制都由 Zsh 负责。当前为 0.1.0 早期版本，角色台词支持简体中文。
在已安装 Git 的环境中，输入 gti status 后，可以通过 zako fix 查看建议：
❯ gti status
zsh: command not found: gti
连命令都能打错？杂鱼，运行 `zako fix`，自己确认候选再输入。
❯ zako fix
建议：git status
原因：命令名可能是 git
请手动确认并输入；Zako 不会自动执行。你决定是否采用建议，再自行输入命令。下一条普通命令开始、切换目录或关闭 Zako 后，旧建议会失效。
默认强度为 3，称呼是“杂鱼”。例如，连续输错三次：
❯ false
这都能失败？杂鱼，先别乱按，看看错误输出。
❯ false
❯ false
连续失败 3 次了。杂鱼，承认需要本小姐提醒了吧？先看错误输出。第二次反馈受默认 20 秒冷却限制，第三次连续失败会提醒一次。成功了也别指望她坦率夸你，以下是其他场景的台词片段：
| 场景 | 台词（强度 3） |
|---|---|
| 打开终端 | ♡ 嘿，杂鱼，今天也别把代码写坏了哦？ |
| 普通命令成功 | 哼，杂鱼，勉强算你做对了，别以为本小姐会一直夸你。 |
| 测试或提交成功 | 居然成功了？杂鱼，别得意，本小姐只是刚好在看。 |
| 连续成功 5 次 | 成就解锁：连胜小天才（连续成功 5 次）。杂鱼，别误会，本小姐只是替你记着，才没有偷偷鼓掌。 |
| 60 秒内失败 5 次 | 60 秒内已有 5 次失败。杂鱼，失败预算都刷光了，还想抽成功保底？先停下来排查。 |
事件台词受互动档位、成功反馈概率和冷却限制；每条命令最多一条反馈，纠错优先。成就与失败预算的触发规则见角色反馈。
同样是第一次失败，五档强度的区别是：
| 强度 | 台词（persona.style = "brat"） |
|---|---|
| 1 · 轻逗 | 杂鱼，这次没成功，看看错误输出吧。 |
| 2 · 嘴硬 | 哼，杂鱼，命令没有成功，检查一下输入。 |
| 3 · 挑衅 | 这都能失败？杂鱼，先别乱按，看看错误输出。 |
| 4 · 奚落 | 杂鱼，这就翻车了？手速挺快，检查输入的速度跟上了吗？ |
| 5 · 火力全开 | 噗，杂鱼，回车的气势倒是满分，结果就这？先把错误输出读明白。 |
想让她更不客气，或换个称呼：
zako config set persona.intensity 5
zako config set persona.nickname "小菜鸡"新开终端后，问候就会变成：
♡ 来了呀，小菜鸡？键盘都准备好了，就等你贡献笑话了。
- 雌小鬼式陪伴：嘴硬、挑衅、偶尔夸你，但命令失败时仍会给出有用的下一步。
- 可调的强度：
persona.intensity支持 1–5 级；失败升级、命令类型点评和会话统计都能单独开关。 - 会话战报与成就：查看失败类型排行、连续成功纪录，解锁嘴硬式夸奖；失败预算耗尽时提醒你停下来排查。
- 可调节的互动：默认普通成功反馈概率为 35%，普通台词间隔至少 20 秒；互动频率与语气分别配置。
- 保守的纠错：识别少量简单命令名和固定 Git 子命令拼写，最多展示三条候选及原因。
- 保留输入习惯：沿用现有主题、Tab 补全和快捷键；右侧 Prompt 空闲时显示角色状态。
- 本地离线运行：无需账号、API Key 或网络服务，无遥测、命令历史持久化或常驻进程。
- 随时开关：
zako off立即停用；配置或 Core 出错时自动停用集成，保留原生 Shell。
需要 Rust stable 与 Cargo、Git，以及 Zsh 5.9+。已验证环境为 macOS Apple Silicon，完整支持范围见兼容性。
git clone https://github.com/JiyuShao/zakosh.git
cd zakosh
cargo install --locked --path .安装后确认可执行文件已在 PATH 中：
zako --versionCargo 默认将它安装到 ~/.cargo/bin/zako。如果提示找不到命令，可先运行 source "$HOME/.cargo/env"，并确认新终端也能访问 Cargo 的 bin 目录。
在 ${ZDOTDIR:-$HOME}/.zshrc 末尾加入以下内容，放在主题和插件初始化之后：
# Zako Shell Companion
if (( $+commands[zako] )); then
eval "$(zako init zsh)"
fiZako 自身不会修改启动文件。若已配置过初始化，保留一处即可。
在新的交互式 Zsh 中运行：
zako status
zako doctor无需创建配置文件即可使用。Oh My Zsh、fzf 和其他插件均为可选组件。
| 命令 | 作用 |
|---|---|
zako fix |
查看当前待纠错命令的候选与原因 |
zako on |
开启当前 Shell 会话中的 Zako |
zako off |
立即关闭，并清除待纠错建议和自动 Prompt 装饰 |
zako status |
查看当前会话的开关、角色状态与连续失败次数 |
zako stats |
查看当前 Shell 的结果统计、失败类型排行、成就与连胜纪录 |
zako stats reset |
清零当前 Shell 的临时统计 |
zako config init |
生成带注释的配置，已有文件不会覆盖 |
zako config set persona.intensity 5 |
调整语气强度，校验后保存 |
zako config show / path |
查看完整有效配置或文件位置 |
zako doctor |
检查配置、Hook 和 Prompt 接入情况 |
zako --help |
查看 CLI 帮助 |
fix/on/off/status/stats 需先加载 Zsh 集成；config 可直接使用。开关只影响当前 Shell；长期默认关闭可设置 general.enabled = false。
默认在空闲的右侧 Prompt 显示简短 ASCII 表情，例如 :3、:) 和 :/。设置 prompt.ascii_fallback = false 后，可显示 ♡ (¬_¬) 等 Unicode 表情。
成功命令会打断连续失败计数；Ctrl+C 和能明确识别的正常非零结果（例如简单 grep 无匹配、diff 有差异）也会重置计数。第三次连续失败可触发一次提醒，之后普通反馈继续受冷却限制。默认 60 秒内累计 5 次失败会触发失败预算提醒，每个窗口最多一次，仍受冷却限制；不会阻止命令执行。纠错提示优先，主动执行 zako fix 不受限流。
默认连续成功 5 次解锁“连胜小天才”，累计失败 10 次解锁“不服输的杂鱼”，每种成就每会话只解锁一次。zako stats 可查看已解锁成就和 Git/Cargo/Docker/rm/sudo/other 失败排行；中性结果与中断单列，不算失败。成就台词也受静默与冷却限制，已解锁状态仍可在统计里查看。关闭 Zako 期间不统计，zako stats reset 清零战报、成就和失败预算；不同终端互相独立。
目前覆盖 gti status → git status、git comit → git commit 等简单拼写场景。带引号、管道、重定向、展开或复杂 Shell 语法的输入，以及删除、提权、强推等高风险场景，不生成改写建议。
Zako 不注册 Tab、Alt+Z 或其他 ZLE 快捷键，也不会把建议写入编辑缓冲区或执行它。
默认配置文件为 ~/.config/zako/config.toml。可以直接用命令配置，无需手改 TOML：
zako config init # 可选：生成完整带注释配置，不覆盖已有文件
zako config set persona.intensity 5 # 1 轻逗 / 2 嘴硬 / 3 挑衅 / 4 奚落 / 5 火力全开
zako config set persona.nickname "小菜鸡"
zako config set interaction.profile chatty
zako config set interaction.cooldown_seconds 5
zako config set interaction.failure_budget false
zako config set session.achievements false
zako config set session.enabled false # 关闭会话统计与成就
zako config show
zako config pathset 保留配置注释，拒绝无效键和值，校验失败时文件不变。配置是符号链接时请直接编辑目标文件。上述修改在新开终端后生效，现有会话继续使用原配置。完整注释见 config.example.toml。
也支持只填写需要修改的字段，例如：
[interaction]
profile = "quiet"
[prompt]
ascii_fallback = falsequiet 关闭主动事件台词，仍保留可用的角色状态和 zako fix。如需关闭启动问候，另设 startup_greeting = false。
展开完整默认配置
# Zako 雌小鬼终端搭档。修改后新开终端生效。
# 也可以使用：zako config set persona.intensity 5
[general]
enabled = true
language = "zh-CN"
[interaction]
profile = "active" # quiet | active | chatty
success_probability = 0.35 # 0.0–1.0；chatty 忽略此概率
cooldown_seconds = 20 # 普通反馈最小间隔，0–86400
startup_greeting = true
consecutive_failure_tip = true # 第三次连续失败时提醒一次
failure_escalation = true # 失败次数越多，语气越强
command_commentary = true # Git/Cargo/Docker/rm/sudo 点评
failure_budget = true # 时间窗口内失败过多时提醒
failure_budget_count = 5 # 2–100
failure_window_seconds = 60 # 1–3600；预算提醒仍受冷却限制
[persona]
style = "brat" # gentle | normal | brat；兼容旧 spicy
nickname = "杂鱼" # 对用户的称呼，最多 64 字
intensity = 3 # 1 轻逗、2 嘴硬、3 挑衅、4 奚落、5 火力全开
[session]
enabled = true # 会话统计；false 时也关闭成就
achievements = true # 每种成就每次会话/清零后只解锁一次
success_streak_goal = 5 # 2–1000；连续成功成就
failure_milestone = 10 # 2–1000；累计失败成就
[prompt]
mode = "auto" # auto | off
ascii_fallback = true
[correction]
enabled = true
max_suggestions = 3 # 1–3
[privacy]
persist_command_history = false
telemetry = false
capture_command_output = false当前版本要求三个隐私选项均为 false，未知配置键会报错。统计只保存在当前 Shell 内存中，不写入文件；关闭终端即丢弃。style 决定风格，intensity 调整 brat 的五档语气；旧 spicy 按 brat 处理。
配置路径按以下优先级查找：
$ZAKO_CONFIG_DIR/config.toml$XDG_CONFIG_HOME/zako/config.toml~/.config/zako/config.toml
配置在新开 Shell 时读取；zako on/off 则立即生效。配置损坏时，集成只提示一次并停用；修复后打开新终端即可重新加载。
| 环境 | 当前状态 |
|---|---|
| macOS Apple Silicon + Zsh 5.9 | 已通过真实终端端到端测试 |
| Oh My Zsh + robbyrussell | 已验证 Prompt 和 Hook 共存 |
| git、z、zsh-autosuggestions、fzf、zsh-syntax-highlighting 组合 | 已验证两种加载顺序及真实输入行为 |
| Linux、其他架构、Starship、Powerlevel10k | 尚未验证 |
| Bash、Fish | 当前未提供集成 |
已有主题或用户占用 RPROMPT 时，Zako 会让出右侧 Prompt，其他反馈与纠错功能仍可使用。可用 zako doctor 查看降级原因。
在 macOS arm64 / Zsh 5.9 的本机验收中，干净 Zsh 与目标插件组合共 8 组场景，每组预热 30 次、采样 500 对，新增耗时 p95 均低于 10ms，最慢一组为 5.71ms。当前角色与会话功能均已纳入测量，详见验收记录。
测量覆盖从输入到下一提示符的完整往返，与无集成会话配对比较，包括 Hook、Core 启动及响应处理；启动时间单列，保留慢样本。该结果反映上述机器与配置，可用性能脚本在自己的环境中复测。
- 找不到
zako：确认~/.cargo/bin在PATH中，并且zako --version可用。 zako fix提示先加载集成：确认初始化位于交互式 Zsh 的.zshrc中，随后打开新终端。- 没有右侧表情：运行
zako doctor，检查prompt.mode和主题是否已占用右侧 Prompt。 - 配置错误或集成自动停用：运行
zako doctor查看原因，修复后打开新终端。
临时停用：
zako off永久停用时删除 .zshrc 中的 Zako 初始化块，并打开新终端。卸载可执行文件：
cargo uninstall zakoCargo 包名和命令名均为 zako。旧版独立 Shell 用户可参考迁移说明。
欢迎通过 Issues 提交可复现的问题或功能建议，也欢迎提交 Pull Request。报告兼容性问题时，请附上系统架构、Zsh 版本、相关插件与最小复现步骤。
本地开发可先运行：
cargo fmt --check
cargo test --locked
cargo clippy --locked --all-targets --all-features -- -D warnings
cargo build --locked --release
zsh -n integrations/zako.zsh
bash tests/zsh_integration.sh target/release/zako需要 Python 3 的统一验收入口：
python3 scripts/verify_m1.py --baseline
python3 scripts/verify_m1.py --full完整验收包括真实 CLI、PTY、目标插件组合、性能与隔离安装/移除。它使用离线锁定依赖，需要先准备 Cargo 缓存；插件场景还依赖本地 Oh My Zsh、autosuggestions、syntax-highlighting 和 fzf，缺少依赖会明确失败。日志和 JSON 结果写入 target/m1-validation/。
模块边界与事件协议见架构说明。扩展功能时，请保留 Zsh 对命令执行与编辑的控制权，以及本地运行、建议手动采用的约定。
MIT © Jiyu Shao