@unscientificjszhai/howto 1.0.1 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (60) hide show
  1. package/README.md +127 -31
  2. package/README.zh-hans-cn.md +331 -0
  3. package/THIRD_PARTY_NOTICES.md +2 -0
  4. package/dist/ai/chatgpt-models.js +148 -0
  5. package/dist/ai/chatgpt.js +495 -0
  6. package/dist/ai/command-schema.js +15 -1
  7. package/dist/ai/errors.js +6 -0
  8. package/dist/ai/gemini.js +117 -4
  9. package/dist/ai/index.js +4 -1
  10. package/dist/ai/openai.js +105 -2
  11. package/dist/ai/usage-session.js +144 -0
  12. package/dist/auth/chatgpt/commands.js +90 -0
  13. package/dist/auth/chatgpt/errors.js +85 -0
  14. package/dist/auth/chatgpt/http.js +97 -0
  15. package/dist/auth/chatgpt/index.js +229 -0
  16. package/dist/auth/chatgpt/instructions.js +22 -0
  17. package/dist/auth/chatgpt/oauth.js +320 -0
  18. package/dist/auth/chatgpt/storage.js +366 -0
  19. package/dist/auth/chatgpt/types.js +1 -0
  20. package/dist/cli.js +77 -16
  21. package/dist/config-file.js +2 -0
  22. package/dist/config.js +11 -4
  23. package/dist/errors.js +6 -1
  24. package/dist/execute.js +4 -13
  25. package/dist/index.js +32 -12
  26. package/dist/init/ChatGptInitializationStep.js +223 -0
  27. package/dist/init/InitializationApp.js +74 -38
  28. package/dist/init/index.js +24 -5
  29. package/dist/init/state.js +14 -3
  30. package/dist/prompt.js +56 -10
  31. package/dist/safety/command-risk.js +11 -0
  32. package/dist/safety/dangerous-command.js +209 -0
  33. package/dist/shell/command-analysis.js +25 -5
  34. package/dist/shell/execution-environment.js +25 -0
  35. package/dist/shell/runtime-environment.js +61 -0
  36. package/dist/ui/App.js +104 -15
  37. package/dist/ui/ConfirmView.js +8 -41
  38. package/dist/ui/InteractiveSessionProvider.js +7 -8
  39. package/dist/ui/ResolvePlaceholdersView.js +8 -3
  40. package/dist/ui/SelectCommandView.js +2 -2
  41. package/dist/ui/UsageApprovalView.js +320 -0
  42. package/dist/ui/interactive-session.js +243 -33
  43. package/dist/ui/keyboard-framing.js +102 -0
  44. package/dist/ui/paste-framing.js +69 -32
  45. package/dist/ui/resize-safe-output.js +2 -2
  46. package/dist/ui/run-interactive-command.js +2 -2
  47. package/dist/ui/text-input.js +4 -1
  48. package/dist/ui/use-keyboard-input.js +17 -2
  49. package/dist/ui/use-paste-aware-input.js +12 -3
  50. package/dist/usage/arguments.js +61 -0
  51. package/dist/usage/generate.js +156 -0
  52. package/dist/usage/output.js +216 -0
  53. package/dist/usage/risk.js +17 -0
  54. package/dist/usage/runner.js +238 -0
  55. package/dist/usage/types.js +1 -0
  56. package/dist/validation/ai-response.js +24 -3
  57. package/dist/validation/command-tool.js +7 -6
  58. package/dist/validation/usage-response.js +39 -0
  59. package/package.json +31 -17
  60. package/README.CN.md +0 -235
package/README.CN.md DELETED
@@ -1,235 +0,0 @@
1
- # howto
2
-
3
- _在终端中用 AI 快速找到可执行命令。_
4
-
5
- [![npm version](https://img.shields.io/npm/v/@unscientificjszhai/howto/latest)](https://www.npmjs.com/package/@unscientificjszhai/howto)
6
- [![GitHub Actions Test Status](https://github.com/UnscientificJsZhai/HowTo/actions/workflows/test.yml/badge.svg?branch=master)](https://github.com/UnscientificJsZhai/HowTo/actions)
7
- [![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier)
8
- [![License](https://img.shields.io/github/license/UnscientificJsZhai/HowTo)](LICENSE)
9
-
10
- [English](README.md) | 简体中文
11
-
12
- [功能](#功能) • [安装](#安装) • [使用](#使用) • [配置](#配置) • [开发](#开发) • [故障排查](#故障排查)
13
-
14
- `howto` 是一个 TypeScript CLI工具,使用自然语言向它提问,它会给你候选命令供你选择。它不会直接运行 AI 输出:你需要在终端中选择候选命令,填写占位符(如有),检查最终命令,然后确认执行。
15
-
16
- > [!IMPORTANT]
17
- > `howto` 是命令生成助手,不是沙箱。执行前请检查每一条命令,尤其是会修改文件、安装包、变更权限或使用提权操作的命令。
18
-
19
- ## 功能
20
-
21
- - **自然语言生成命令** - 描述任务后获得简洁的 shell 命令候选项。
22
- - **指定工具模式** - 使用 `howto use <command>` 要求候选项围绕某个 CLI 工具生成。
23
- - **交互式确认流程** - 选择候选项、填写占位符,并在执行前确认最终命令。
24
- - **非交互打印模式** - 使用 `--print` 输出候选命令,不进入 TTY 交互,也不执行命令。
25
- - **支持 OpenAI 和 Gemini** - 可通过 CLI 参数、环境变量或 `~/.howto/config.json` 配置 provider。
26
- - **本地优先校验** - 本地校验 AI JSON 输出、占位符引用、`use <command>` 候选项以及明显危险命令。
27
-
28
- ## 安装
29
-
30
- 全局安装 CLI 包:
31
-
32
- ```bash
33
- npm install -g @unscientificjszhai/howto
34
- ```
35
-
36
- 也可以从克隆的仓库中运行:
37
-
38
- ```bash
39
- npm install
40
- npm run build
41
- npm link
42
- ```
43
-
44
- 之后即可使用 `howto` 命令。
45
-
46
- ## 快速开始
47
-
48
- 初始化 AI provider 配置:
49
-
50
- ```bash
51
- howto --init
52
- ```
53
-
54
- 初始化程序会把用户级配置写入 `~/.howto/config.json`。
55
-
56
- 初始化和占位符输入支持按完整字符退格,包括 emoji 和组合字符;Alt/Meta 快捷键不会作为文本写入配置字段。
57
- 按键释放事件不会触发确认、取消、导航或再次删除;一次 Enter 的按下和释放不能跳过最终确认。
58
- 终端将键盘文本与 Enter 合并送达时,输入仍按顺序处理;当前步骤结束后,同批剩余按键不能跳过下一页确认。粘贴中的换行保留为数据。
59
-
60
- > [!NOTE]
61
- > OpenAI API key 可以为空,以支持本地 OpenAI 兼容服务。Gemini 必须提供非空 API key。
62
-
63
- 询问一个命令:
64
-
65
- ```bash
66
- howto 找到最近7天修改的文件 .
67
- ```
68
-
69
- 限制候选项必须使用某个工具:
70
-
71
- ```bash
72
- howto use git 看看上周的提交
73
- ```
74
-
75
- `use` 会在处理环境变量赋值及已支持的 `sudo`/`env` 选项后,精确核对首个实际工具。例如 `sudo -u root git status` 符合 `use git`,`sudo -u git id` 则不符合。`sudo`/`env` 的未知选项或缺少选项参数、动态执行前缀及复杂 shell 结构会被拒绝。这个约束只针对首段的工具,不限制后续命令段。
76
-
77
- 已声明的占位符可以出现在首工具之后,例如 `git log -n {{count}}`;工具名及其之前的前缀必须能在填写占位符前确定。模板分析不会修改最终命令原文。
78
-
79
- 不进入交互 UI,只打印候选命令:
80
-
81
- ```bash
82
- howto --print 列出最大的文件 /var/log
83
- ```
84
-
85
- ## 使用
86
-
87
- ```text
88
- howto [options] [use <command>] <question> [<argument>...]
89
- howto --init
90
- howto --version
91
- ```
92
-
93
- 示例:
94
-
95
- ```bash
96
- howto 找到当前目录的package.json
97
- howto use find 寻找特定文件名的文件 package.json
98
- howto 解释这个命令 -- --force
99
- howto --ai-provider openai --print 列出监听的端口
100
- ```
101
-
102
- 参数:
103
-
104
- - `--init` - 启动交互式 provider 配置,并保存 `~/.howto/config.json`。
105
- - `--version` - 单独使用,输出当前包版本号并成功退出;无需配置或 TTY,不调用 AI。
106
- - `--print` - 打印已校验的命令候选项并退出,不执行命令。
107
- - `--ai-provider <openai|gemini>` - 选择 AI provider。
108
- - `--gemini-api-key <key>` - 提供 Gemini API key。
109
- - `--gemini-model <model>` - 覆盖 Gemini 模型。
110
- - `--openai-api-url <url>` - 使用自定义 OpenAI 兼容 base URL。
111
- - `--openai-api-key <key>` - 提供 OpenAI API key。
112
- - `--openai-model <model>` - 覆盖 OpenAI 模型。
113
- - `--structured-output <true|false>` - 启用 SDK 级 schema 结构化输出;默认 `true`。
114
-
115
- ### 参数解析
116
-
117
- `question` 是一个 shell 参数。包含空格时需要加引号:
118
-
119
- ```bash
120
- howto "find recently changed files" /tmp
121
- ```
122
-
123
- `question` 后面的内容会作为 `argument[]` 传给 AI。如果参数以 `--` 开头,请使用 `--` 结束 option 解析:
124
-
125
- ```bash
126
- howto "explain this flag" -- --force
127
- ```
128
-
129
- ## 配置
130
-
131
- 配置按以下优先级解析:
132
-
133
- 1. CLI 参数
134
- 2. 环境变量
135
- 3. `~/.howto/config.json`
136
- 4. 内置默认值
137
-
138
- 配置路径使用绝对路径形式的 `HOME`。`HOME` 缺失或为空白时,howto 从系统用户信息查询主目录;非空相对 `HOME` 或系统查询失败会在创建文件前返回配置错误。
139
-
140
- 对每个配置项,优先级中第一个已配置的来源生效:
141
-
142
- - `--ai-provider` / `HOWTO_AI_PROVIDER` / `aiProvider` - `openai` 或 `gemini`;无默认值。
143
- - `--gemini-api-key` / `HOWTO_GEMINI_API_KEY` / `geminiApiKey` - Gemini API key;Gemini 必填。
144
- - `--gemini-model` / `HOWTO_GEMINI_MODEL` / `geminiModel` - Gemini 模型;默认 `gemini-3.1-flash-lite`。
145
- - `--openai-api-url` / `HOWTO_OPENAI_API_URL` / `openaiApiUrl` - OpenAI 兼容 base URL;默认 `https://api.openai.com/v1`。
146
- - `--openai-api-key` / `HOWTO_OPENAI_API_KEY` / `openaiApiKey` - OpenAI API key;默认为空字符串以支持本地服务。
147
- - `--openai-model` / `HOWTO_OPENAI_MODEL` / `openaiModel` - OpenAI 模型;默认 `gpt-5.4-mini`。
148
- - `--structured-output` / `HOWTO_STRUCTURED_OUTPUT` / `structuredOutput` - 使用 provider schema 结构化输出;默认 `true`。
149
-
150
- 请求地址和 Gemini API 模式由 howto 显式设置。`OPENAI_BASE_URL`、`GOOGLE_GEMINI_BASE_URL`、`GOOGLE_VERTEX_BASE_URL` 及 Google SDK 的 Vertex/Enterprise 模式环境开关不会改写它们。Gemini 使用官方 `generativelanguage.googleapis.com` 的 `v1beta` API;自定义 OpenAI 地址请使用上述 HOWTO 配置项。
151
-
152
- OpenAI 的 Authorization 使用 howto 配置的 key,空白 key 时不发送该请求头;`OPENAI_CUSTOM_HEADERS` 中的 Authorization 不会覆盖此选择。交互模式收到 OpenAI 限流或临时服务错误时直接报错,不自动重试,以保证取消后能及时退出;`--print` 保留 SDK 默认重试行为。
153
-
154
- 示例:
155
-
156
- ```bash
157
- HOWTO_AI_PROVIDER=openai \
158
- HOWTO_OPENAI_MODEL=gpt-5.4-mini \
159
- howto --print "show current branch"
160
- ```
161
-
162
- ## 安全模型
163
-
164
- `howto` 将 AI 输出视为不可信数据。在进入执行前,CLI 会检查:
165
-
166
- - AI 响应是符合命令 schema 的有效 JSON;
167
- - 响应包含一到三个候选项;
168
- - 所有占位符使用 `{{name}}` 语法,并且声明与引用一致;同一候选中名称只声明一次,多处引用共用一次输入;
169
- - `use <command>` 候选项在保守处理前缀后,明确以指定工具开头;
170
- - 明显危险的命令需要输入 `EXECUTE` 才能继续执行;大小写不敏感。
171
-
172
- 危险命令检测当前覆盖递归破坏性 `rm`、磁盘和文件系统操作、大范围递归权限变更、下载脚本后直接交给 shell 执行、高影响包管理器操作以及服务变更等高风险模式。
173
-
174
- 本地分析会处理字面引号、绝对命令路径及已支持的 `sudo`/`env` 选项,并检查各命令段。遇到未知 wrapper 选项、动态执行前缀或超出解析范围的 shell 语法时,也会要求输入 `EXECUTE`,避免把无法判断的命令直接视为安全。
175
-
176
- 数字文件描述符中的续行因 shell 方言差异要求额外确认,并被 `use` 校验拒绝。风险分析会识别 `./../important` 和 `///dev/disk2` 等含冗余 `.` 或斜杠的高风险路径,不折叠 `..`,也不修改实际执行命令。
177
-
178
- `env` 赋值中的数字开头、连字符或点名称也会正确识别,继续检查后面的实际命令。npm 全局安装/卸载的正式别名(如 `i`、`add`、`un`、`unlink`)使用同样的危险确认;不能确定的等价缩写也要求额外确认。
179
- 前导 `NAME+=value` 因 shell 方言差异要求额外确认,并被 `use` 校验拒绝;未受单引号或反斜杠保护的美元表达式保守按动态值判断。npm 的 `install-test`、`installTest`、`it` 复合安装及其缩写也纳入全局安装确认。
180
-
181
- Homebrew 的 `rm/uninstal` 卸载别名,以及 yum/dnf 的 `update/erase` 升级或卸载入口,也使用相同的危险确认。各工具的动作分别识别,`apt update`、`brew update/up` 的索引更新不按系统软件升级处理。
182
-
183
- 一次交互调用中只要识别到 bracketed paste(包括自动初始化阶段),本次调用就永久改为输出最终命令供手动运行。最终确认页按 Enter 只输出命令,终端会显示说明;返回候选选择或调整终端大小都不会恢复执行权限。全程键盘输入仍使用原有的 Enter 或 `EXECUTE` 确认。
184
-
185
- 跨越终端视图隐藏阶段的粘贴会整块丢弃。这些规则针对已识别的 bracketed-paste 输入;终端协议无法认证任意粘贴按键或内容中的结束标记。执行限制针对 howto 自身启动候选命令的行为。
186
-
187
- > [!WARNING]
188
- > 未被标记为危险并不表示命令一定安全。本地检查会对已知高风险模式及无法分析的语法增加确认步骤,并不能证明命令安全。
189
-
190
- ## 开发
191
-
192
- 本项目使用 TypeScript、React、Ink、OpenAI SDK、Gemini GenAI SDK 和 Node 内置测试运行器构建。
193
-
194
- ```bash
195
- npm install
196
- npm run build
197
- npm test
198
- npm run lint
199
- npm run format:check
200
- ```
201
-
202
- 常用路径:
203
-
204
- - `src/index.tsx` - CLI 编排和执行流程。
205
- - `src/cli.ts` - 参数解析。
206
- - `src/config.ts` - 配置合并和 provider 校验。
207
- - `src/prompt.ts` - prompt 和 AI 输出契约。
208
- - `src/validation/` - AI 响应和命令工具校验。
209
- - `src/safety/` - 危险命令规则。
210
- - `src/ui/` - 基于 Ink 的终端 UI。
211
- - `tests/unit/` - CLI、配置、校验、执行、UI 和安全逻辑的单元测试。
212
-
213
- ## 故障排查
214
-
215
- ### AI provider 未配置
216
-
217
- 运行:
218
-
219
- ```bash
220
- howto --init
221
- ```
222
-
223
- `--print` 会有意跳过初始化流程。请先配置 provider,或传入对应 CLI 参数/环境变量。
224
-
225
- ### 非交互终端错误
226
-
227
- 默认模式需要交互式 TTY 来选择和确认命令。在脚本或 CI 中请使用 `--print`:
228
-
229
- ```bash
230
- howto --print "show disk usage"
231
- ```
232
-
233
- ### Gemini key 必填
234
-
235
- Gemini 不能在没有 API key 的情况下运行。请设置 `HOWTO_GEMINI_API_KEY`,传入 `--gemini-api-key`,或重新运行 `howto --init`。