{"_id":"@allenreder/tmh","_rev":"3-6c0f045d00c230976ef5aaf2298ed291","name":"@allenreder/tmh","dist-tags":{"latest":"0.2.1"},"versions":{"0.1.2":{"name":"@allenreder/tmh","version":"0.1.2","keywords":["cli","terminal","shell","zsh","openai"],"author":{"name":"Wenyou Yi"},"license":"MIT","_id":"@allenreder/tmh@0.1.2","maintainers":[{"name":"allenreder","email":"yiwenyou_allen@outlook.com"}],"homepage":"https://github.com/AllenReder/tmh#readme","bugs":{"url":"https://github.com/AllenReder/tmh/issues"},"bin":{"tmh":"bin/tmh.mjs","tmha":"bin/tmha.mjs"},"dist":{"shasum":"7e3dd465bdf6da28b32d99f14b41a80a98f2753f","tarball":"https://registry.npmjs.org/@allenreder/tmh/-/tmh-0.1.2.tgz","fileCount":13,"integrity":"sha512-XrXhoQ96KGhuoeZLLWY+HFV0yBQWDRc59BE0ypw26GZRQdGFJSj8KTdWs8GCHjTW7pCPy8oOzKMxtHFrm/Y60Q==","signatures":[{"sig":"MEYCIQDWup3SAVV+0hejTTOJ9gStcHGL8Jlr93bcRvO5gHk6owIhAML0ZYlGh7g4cGN0uGgzAN9wsWk+up2L6zGaeNAQS/xK","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@allenreder%2ftmh@0.1.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":26002791},"type":"module","_from":"file:package-release/allenreder-tmh-0.1.2.tgz","engines":{"node":">=22"},"scripts":{"test":"node --test"},"_npmUser":{"name":"allenreder","email":"yiwenyou_allen@outlook.com"},"_resolved":"/home/runner/work/tmh/tmh/package-release/allenreder-tmh-0.1.2.tgz","_integrity":"sha512-XrXhoQ96KGhuoeZLLWY+HFV0yBQWDRc59BE0ypw26GZRQdGFJSj8KTdWs8GCHjTW7pCPy8oOzKMxtHFrm/Y60Q==","repository":{"url":"git+https://github.com/AllenReder/tmh.git","type":"git"},"_npmVersion":"11.18.0","description":"Turn natural language into a terminal command you can review before running.","directories":{},"_nodeVersion":"24.18.0","publishConfig":{"access":"public","registry":"https://registry.npmjs.org/","provenance":true},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/tmh_0.1.2_1784038042786_0.9793812787863532","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@allenreder/tmh","version":"0.2.0","keywords":["cli","terminal","shell","zsh","bash","fish","openai"],"author":{"name":"Wenyou Yi"},"license":"MIT","_id":"@allenreder/tmh@0.2.0","maintainers":[{"name":"allenreder","email":"yiwenyou_allen@outlook.com"}],"homepage":"https://github.com/AllenReder/tmh#readme","bugs":{"url":"https://github.com/AllenReder/tmh/issues"},"bin":{"tmh":"bin/tmh.mjs"},"dist":{"shasum":"5cff9d2348905742518e5e9747e5f28e81be5c7e","tarball":"https://registry.npmjs.org/@allenreder/tmh/-/tmh-0.2.0.tgz","fileCount":11,"integrity":"sha512-lMJ7WOiEJ4iSPCD/C31l1YkFu+EWkewC/KpJhVdC9I1oUgvgJq+9u7fQ+Od2pnnC5979ZeIK/GKIF1ftwTtMfw==","signatures":[{"sig":"MEYCIQCQSbQrxNX8Qbs5n+pM1e2kDLeQ4dMvp/Opj+WqfkeWNgIhAOaOCs/Cpwwo8AB5RInJhZSB633vkckoc0RkJQ5uFKpb","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@allenreder%2ftmh@0.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":27857041},"type":"module","_from":"file:package-release/allenreder-tmh-0.2.0.tgz","engines":{"node":">=22"},"scripts":{"test":"node --test"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:0dec3d44-f6c3-46ec-a695-f9f38098b1be"}},"_resolved":"/home/runner/work/tmh/tmh/package-release/allenreder-tmh-0.2.0.tgz","_integrity":"sha512-lMJ7WOiEJ4iSPCD/C31l1YkFu+EWkewC/KpJhVdC9I1oUgvgJq+9u7fQ+Od2pnnC5979ZeIK/GKIF1ftwTtMfw==","repository":{"url":"git+https://github.com/AllenReder/tmh.git","type":"git"},"_npmVersion":"11.18.0","description":"Turn natural language into a terminal command you can review before running.","directories":{},"_nodeVersion":"24.18.0","publishConfig":{"access":"public","registry":"https://registry.npmjs.org/","provenance":true},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/tmh_0.2.0_1784189987769_0.5319625835593871","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"@allenreder/tmh","version":"0.2.1","description":"Turn natural language into a terminal command you can review before running.","type":"module","license":"MIT","author":{"name":"Wenyou Yi"},"homepage":"https://github.com/AllenReder/tmh#readme","bugs":{"url":"https://github.com/AllenReder/tmh/issues"},"repository":{"type":"git","url":"git+https://github.com/AllenReder/tmh.git"},"keywords":["cli","terminal","shell","zsh","bash","fish","openai"],"bin":{"tmh":"bin/tmh.mjs"},"scripts":{"test":"node --test"},"engines":{"node":">=22"},"publishConfig":{"access":"public","provenance":true,"registry":"https://registry.npmjs.org/"},"_id":"@allenreder/tmh@0.2.1","_integrity":"sha512-vf/NJFxxfZvYkbFvrmUq/Zz1q5Myc2rHooRXHL3SecA9rz/mnQyJwlFiEYmnepzELmSz42pAdKGbuFM8i4i0Mg==","_resolved":"/home/runner/work/tmh/tmh/package-release/allenreder-tmh-0.2.1.tgz","_from":"file:package-release/allenreder-tmh-0.2.1.tgz","_nodeVersion":"24.18.0","_npmVersion":"11.18.0","dist":{"integrity":"sha512-vf/NJFxxfZvYkbFvrmUq/Zz1q5Myc2rHooRXHL3SecA9rz/mnQyJwlFiEYmnepzELmSz42pAdKGbuFM8i4i0Mg==","shasum":"7384510b2445b66711f9750570fce7dca9241e4c","tarball":"https://registry.npmjs.org/@allenreder/tmh/-/tmh-0.2.1.tgz","fileCount":11,"unpackedSize":27857414,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@allenreder%2ftmh@0.2.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCi3m9fRJlGuGoMObCfOUvHzBuX/s0Jo9SleizvhqQrdgIhAPKd0P3Fcbt97xWa6AHgvelAdJkgN2N8aPXn+5sR9WKg"}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:0dec3d44-f6c3-46ec-a695-f9f38098b1be"}},"directories":{},"maintainers":[{"name":"allenreder","email":"yiwenyou_allen@outlook.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/tmh_0.2.1_1784276861994_0.7938606108543746"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-14T14:07:22.678Z","modified":"2026-07-17T08:27:42.613Z","0.1.2":"2026-07-14T14:07:23.096Z","0.2.0":"2026-07-16T08:19:48.080Z","0.2.1":"2026-07-17T08:27:42.304Z"},"bugs":{"url":"https://github.com/AllenReder/tmh/issues"},"author":{"name":"Wenyou Yi"},"license":"MIT","homepage":"https://github.com/AllenReder/tmh#readme","keywords":["cli","terminal","shell","zsh","bash","fish","openai"],"repository":{"type":"git","url":"git+https://github.com/AllenReder/tmh.git"},"description":"Turn natural language into a terminal command you can review before running.","maintainers":[{"name":"allenreder","email":"yiwenyou_allen@outlook.com"}],"readme":"<div align=\"center\">\n\n# tmh — tell me how\n\n将自然语言转换为一条可检查、再决定是否运行的终端命令。\n\n[![CI](https://github.com/AllenReder/tmh/actions/workflows/ci.yml/badge.svg)](https://github.com/AllenReder/tmh/actions/workflows/ci.yml)\n[![Release](https://img.shields.io/github/v/release/AllenReder/tmh)](https://github.com/AllenReder/tmh/releases)\n[![npm](https://img.shields.io/npm/v/%40allenreder%2Ftmh)](https://www.npmjs.com/package/@allenreder/tmh)\n[![License](https://img.shields.io/github/license/AllenReder/tmh)](LICENSE)\n\n[English](README.md) · [简体中文](README.zh-CN.md)\n\n</div>\n\n```text\n$ tmh 找出当前目录下最大的十个文件\nExplanation: 查找普通文件并按大小排序。\n\nfind . -type f -exec du -h {} + | sort -hr | head -n 10\n```\n\n解释写入 stderr，stdout 只包含最终生成的一条命令；tmh 不会执行这条\n最终命令。\n\n## 特点\n\n- 生成一条可编辑、可检查的 Zsh、Bash 或 Fish 命令。\n- 同时提供快速生成模式和有明确边界的上下文 Agent 模式。\n- 除非用户对本次 Agent 调用显式授权，否则模型完全看不到命令执行\n  Tool。\n- 使用与生成目标相同的 Shell 在本地校验语法，并提示高风险行为。\n- 支持 OpenAI-compatible Chat Completions 接口。\n- stdout 只输出最终命令，解释、警告和审计事件写入 stderr。\n\n## 安装\n\nmacOS 和 Linux 推荐使用 Homebrew：\n\n```sh\nbrew install AllenReder/tap/tmh\n```\n\n如果已经安装 Node.js 22 或更高版本，也可以使用 npm：\n\n```sh\nnpm install -g @allenreder/tmh\n```\n\n也可以使用独立安装脚本：\n\n```sh\ncurl -fsSL https://raw.githubusercontent.com/AllenReder/tmh/main/install.sh | sh\n```\n\n安装指定的稳定版本：\n\n```sh\ncurl -fsSL https://raw.githubusercontent.com/AllenReder/tmh/main/install.sh | TMH_VERSION=v0.2.0 sh\n```\n\n独立安装器只会把 `tmh` 安装到 `~/.local/bin`。写入受管理的 Zsh、\nBash 或 Fish 集成配置前，默认会先询问用户。非交互场景可使用\n`TMH_INSTALL_SHELL=ask|none|auto|zsh|bash|fish`：\n\n```sh\ncurl -fsSL https://raw.githubusercontent.com/AllenReder/tmh/main/install.sh |\n  TMH_INSTALL_SHELL=fish sh\n```\n\nHomebrew 和 npm 不会修改 Shell 启动文件。\n\n### Shell 集成\n\n在对应的启动文件中加入：\n\n```sh\n# Zsh：~/.zshrc\neval \"$(tmh shell init zsh)\"\n\n# Bash：~/.bashrc；macOS 通常为 ~/.bash_profile\neval \"$(tmh shell init bash)\"\n\n# Fish：~/.config/fish/conf.d/tmh.fish\ntmh shell init fish | source\n```\n\n集成脚本已嵌入 `tmh` 二进制，不再安装独立 Shell 脚本。\n\n- `Ctrl-X Ctrl-G`：把当前输入缓冲区替换为普通模式生成的命令。\n- `Ctrl-X Ctrl-A`：通过 Agent 模式完成相同操作。\n- 默认保留已有快捷键；`--force-bind` 会显式覆盖，\n  `--no-bind` 只注册函数和 Widget，不绑定快捷键。\n- Zsh 继续支持普通 `tmh ...` 回车后通过 `print -z` 把结果放入下一条\n  提示符。\n- Bash 4 及以上支持 readline Widget。macOS 自带的 Bash 3.2 仍支持\n  命令生成、目标 Shell 校验和 stdout 输出，但不支持替换输入缓冲区。\n\n不启用 Shell 集成时，所有模式仍会把最终命令输出到 stdout。\n\n从源码构建：\n\n```sh\ngit clone https://github.com/AllenReder/tmh.git\ncd tmh\nmake build\n```\n\n## 配置\n\nstandalone installer 会在配置不存在时自动创建\n`~/.config/tmh/config.toml`，或 `$XDG_CONFIG_HOME/tmh/config.toml`。已有的\n配置文件或符号链接不会被覆盖。通过 Homebrew、npm 或源码安装时，可按以下\n模板手动创建：\n\n```toml\nbase_url = \"https://api.openai.com/v1\"\nmodel = \"your-model-name\"\nshell = \"auto\"\ngenerate_timeout_seconds = 30\nagent_timeout_seconds = 90\n```\n\n接口需要认证时设置 `TMH_API_KEY`；未设置时会使用\n`OPENAI_API_KEY`。\n\n```sh\ntmh config show\ntmh config test\n```\n\n目标 Shell 的选择优先级为：\n\n1. `--shell auto|zsh|bash|fish`\n2. `TMH_SHELL`\n3. 配置文件中的 `shell`\n4. 根据 `$SHELL` 自动检测\n\n无法识别时会明确报错，不会静默回退到 Zsh。`tmh config show` 会显示\n配置来源，以及 `auto` 最终解析出的具体 Shell。Shell 可执行文件必须来自\n标准系统或包管理器路径，或 `~/.local/bin`、`~/bin`、asdf、mise、Nix\nprofile 等受支持的用户路径；任意 `PATH` 目录及逃逸这些目录的符号链接会被\n拒绝。\n\nv0.2 的配置是有意设计的破坏性变更。旧字段\n`tmh_timeout_seconds` 和 `tmha_timeout_seconds` 会作为未知字段被拒绝。\n\n## 使用\n\n### 生成命令\n\n```sh\ntmh 找出今天修改过的文件\ntmh 查看哪个进程占用了 8080 端口\nprintf '%s' '按占用空间从大到小排序' | tmh\n```\n\n`tmh <请求>` 是最短入口。请求以保留子命令开头时，使用显式入口\n`tmh generate <请求>`：\n\n```sh\ntmh generate 找出当前目录下的 config 文件\n```\n\n### Agent 模式\n\n命令依赖本地上下文时，Agent 可以列出目录并在预算范围内读取普通\n文本文件：\n\n```sh\ntmh agent 启动当前项目\ntmh agent --allow-path /var/log 生成检查这些日志的命令\n```\n\n默认只能访问当前目录；额外路径必须显式授权。v0.1 的 `tmha` 可执行\n文件和 `tmh --agent` 参数已经删除，请统一使用 `tmh agent`。\n\n### Inspection 命令 Tool\n\n默认不会向模型提供 `run_command`。仅对当前这次 Agent 调用启用：\n\n```sh\ntmh agent --exec=inspection 判断哪些文件发生了变化，并建议相关测试命令\n```\n\nInspection 模式只能自动运行通过策略检查的只读\n`git status`、`git diff`、`git log`、`git show`、`git rev-parse`、\n`git ls-files` 和 `rg` 操作。请求使用“程序 + 参数数组”的结构化形式，\n直接执行，不经过 Shell。未知程序、子命令、参数、脚本、管道、重定向、\n解释器、网络访问和任何修改行为都会在启动进程前被拒绝。\n\n`--allow-path` 会同时扩展文件 Tool 和 Inspection 命令的可读根目录。\nAgent 最终生成的命令仍只会返回给用户检查，不会执行。\n\n### 常用参数\n\n| 参数 | 作用 |\n| --- | --- |\n| `--shell auto|zsh|bash|fish` | 选择最终命令使用的 Shell。 |\n| `--allow-path PATH` | 仅在 Agent 模式增加可读根目录，可重复使用。 |\n| `--exec=inspection` | 仅在 Agent 模式为本次调用提供沙箱化的只读命令 Tool。 |\n| `--base-url URL` | 临时覆盖接口地址。 |\n| `--model MODEL` | 临时覆盖模型。 |\n| `--timeout DURATION` | 临时覆盖请求超时。 |\n| `--debug` | 向 stderr 输出脱敏诊断信息。 |\n\n## 安全\n\n- tmh 永远不会执行最终生成的命令。\n- 文件和命令 Tool 都受路径与预算约束，并把结果视为不可信数据，而非\n  新指令。\n- 敏感路径、二进制文件、超大读取、符号链接越界和授权根目录外路径\n  会被拒绝。\n- Inspection 必须逐次显式启用，只允许白名单内的 `git`/`rg` 形式，\n  不提供 stdin 或 TTY。\n- 子进程环境会移除 API Key、凭据、代理设置、认证 socket、动态加载\n  设置、pager 和用户 Git 配置。\n- 命令输出有大小限制；即使截断仍会持续 drain 以避免死锁，随后清理\n  终端控制序列、修复 UTF-8 并脱敏，再发送给模型。\n- 模型轮次、Tool 次数、命令次数、执行时间和输出总量均有固定上限。\n- 模型输出必须是目标 Shell 中一条合法的物理单行命令。风险提示是\n  辅助信息，是否运行始终由用户决定。\n\n### Inspection 沙箱与威胁模型\n\n无法证明平台沙箱有效时，Inspection 会 fail closed：\n\n- Linux 要求 Landlock ABI v3 或更高版本，以覆盖 truncate 等写入行为，\n  并使用 seccomp-BPF 拒绝网络相关系统调用。不满足要求时，普通生成和\n  仅文件 Tool 的 Agent 模式仍可使用，但 `--exec=inspection` 不可用。\n- macOS 使用操作系统中已被标记为 deprecated 的\n  `/usr/bin/sandbox-exec` Seatbelt 接口，应用 deny-default、只读且\n  无网络的 profile。该程序缺失或 canary 验证失败时，Inspection 不会\n  降级运行。\n\n这个边界用于阻止模型误操作和常见 Prompt Injection 把“检查”升级为\n修改或数据外传；它不用于抵抗以同一用户权限并发运行的恶意本地进程。\n请保护主机账户，并始终检查最终生成的命令。\n\n请求、基础运行环境以及 Tool 选取的 Agent 上下文会发送给配置的模型\n接口，请勿输入秘密信息。\n\n## 当前支持\n\n- macOS、Linux；amd64、arm64。\n- Zsh、Bash 3.2 及以上、Fish 3.6 及以上。\n- Bash 输入缓冲区 Widget 要求 Bash 4 及以上。\n- Inspection 还要求上述平台沙箱可正常使用。\n- 暂不支持 Windows、PowerShell 和终端模拟器专用适配器。\n\n## 开发\n\n```sh\nmake build\nmake test\nmake check\n```\n\n`make check` 覆盖 Go 测试与静态检查、Zsh/Bash/Fish 集成脚本语法、\n安装与发布流程、包验证、漏洞扫描和 workflow 校验。CI 会在 macOS 和\nLinux 上安装 Fish，确保 Fish 检查不会走本地可选跳过分支。\n\n欢迎提交范围明确的 Issue 和 Pull Request。安全漏洞请通过\n[GitHub 私有安全公告](https://github.com/AllenReder/tmh/security/advisories/new)报告。\n\n## 许可证\n\n[MIT](LICENSE)。捆绑依赖的许可证信息见\n[第三方声明](THIRD_PARTY_NOTICES.md)。\n","readmeFilename":"README.zh-CN.md"}