企业官网建设流程全解析

• 开发工具
• CLI

aws-shell 是一个基于 Python 构建的交互式命令行外壳，用于提升 AWS CLI 的日常使用效率：它接受与 AWS CLI 完全相同的命令（无需aws前缀），并提供逐字键入时的命令/选项自动补全、服务端资源补全、模糊搜索、内联文档与命令历史等能力。本文将以仓库 README.rst 为主线，结合 awsshell 包内的源码实现与测试用例，系统讲解安装配置、基本用法、核心功能与点命令（dot command），帮助读者把 aws-shell 真正用起来并理解其背后原理。

安装与升级

aws-shell 依赖 Python 与pip进行安装。安装方式与绝大多数 Python 工具一致：

$ pip install aws-shell

如果当前环境没有使用 virtualenv 等虚拟环境，则可能需要以管理员权限安装：

$ sudo pip install aws-shell

Mac OS X（10.11 El Capitan）用户注意：系统自带的 Python 及其依赖包存在已知兼容性问题。作为临时解决办法，可执行如下命令完成安装：

sudo pip install aws-shell --upgrade --ignore-installed six

安装完成后，直接运行即可进入交互式外壳：

$ aws-shell

要退出外壳，按下Ctrl-D（与 F10 等效，见下文"工具栏选项"）。

升级到最新版本

当需要升级 aws-shell 时，执行：

$ pip install --upgrade aws-shell

README 特别强调：每当 AWS CLI 发布新版本、新增服务或 API 更新时，都建议执行上述升级命令，升级后即可在 aws-shell 中使用这些新服务与新的 API 命令。

支持的 Python 版本

aws-shell 支持与 AWS CLI 相同范围的 Python 版本：

• 2.6.5 及以上
• 2.7.x 及以上
• 3.3.x 及以上
• 3.4.x 及以上

从仓库的依赖声明 setup.py 可以看到，当前版本对运行环境的依赖为：awscli>=1.16.10,<2.0.0、prompt-toolkit>=1.0.0,<1.1.0、boto3>=1.9.0,<2.0.0、configobj>=5.0.6,<6.0.0以及Pygments>=2.1.3,<3.0.0。其中 awscli 是命令执行后端，boto3 用于服务端资源补全（详见下文），prompt_toolkit 提供交互式 UI 基础设施，configobj 负责读写配置文件，Pygments 负责语法高亮与配色主题。

配置：与 AWS CLI 共用一套配置

aws-shell 使用与 AWS CLI 完全相同的配置体系。如果你此前从未配置过 AWS CLI，最快捷的方式是在 aws-shell 内直接运行configure命令：

$ aws-shell aws> configure AWS Access Key ID [None]: your-access-key-id AWS Secret Access Key [None]: your-secret-access-key Default region name [None]: region-to-use (e.g us-west-2, us-west-1, etc). Default output format [None]: aws>

按提示依次输入访问密钥、区域（如us-west-2、us-west-1）与默认输出格式即可。更完整的 configure 设置说明可参见 AWS CLI 官方入门指南。

在源码层面，awsshell/app.py 的load_config()通过 awsshell/config.py 中的Config类加载配置：程序启动时会读取包内自带的awsshellrc模板，若用户目录下不存在配置文件则自动复制模板生成，之后再以用户配置覆盖模板默认值，从而保证"首次运行即有一份可编辑的默认配置"。

基本用法：去掉 aws 前缀的完整 CLI

aws-shell 接受与 AWS CLI 相同的命令，唯一区别是不需要再输入aws前缀。例如：

$ aws-shell aws> ec2 describe-regions { "Regions": [ { "Endpoint": "ec2.eu-west-1.amazonaws.com", "RegionName": "eu-west-1" }, ... aws> s3 ls 2015-12-07 15:03:34 bucket1 2015-12-07 15:03:34 bucket2 aws> dynamodb list-tables --output text TABLENAMES First TABLENAMES Second TABLENAMES Third

从源码看，awsshell/app.py 中AWSShell.run()的事件循环在收到用户输入后，会为普通命令自动拼接'aws '前缀再交给子进程执行（popen调用），同时把完整命令写入内存历史；因此你在 aws-shell 中输入的内容与直接敲aws命令是等价的，--output text等全局选项也原样生效。

使用 Profile：启动参数与 .profile 点命令

aws-shell 完整支持 AWS CLI 的 profile 机制，并提供两种使用方式。

方式一：启动时指定 profile

$ aws-shell --profile prod aws>

启动后，所有服务端补全以及实际执行的 CLI 命令都会自动使用prodprofile。对应参数解析位于 awsshell/init.py 的main()入口（-p/--profile选项），启动时会把 profile 写入AWSShell.profile。

方式二：会话内切换 profile

$ aws-shell aws> .profile demo Current shell profile changed to: demo

也可以随时查看当前 profile：

aws> .profile Current shell profile: demo

切换 profile 后，后续的服务端补全与 CLI 命令会自动改用新 profile。其底层实现在 awsshell/app.py：profile属性 setter 会同步做两件事——把 profile 名称写入环境变量AWS_DEFAULT_PROFILE，并调用 completer 的change_profile()让服务端补全改用新的会话（见 awsshell/shellcomplete.py）。

核心功能详解

命令与选项自动补全

aws-shell 提供输入即补全的命令与选项自动补全：输入时，服务名、子命令、--选项都会动态给出候选。补全数据并非临时解析，而是基于按 AWS CLI 版本生成的 JSON 索引。

从源码结构看，自动补全分两层：

• 低层的 awsshell/autocomplete.py 中AWSCLIModelCompleter消费按版本生成的补全索引（commands、arguments、argument_metadata、children等结构），根据当前输入位置决定补全子命令还是参数；
• 高层的 awsshell/shellcomplete.py 中AWSShellCompleter将其适配为 prompt_toolkit 的Completion对象，并为--选项附加内联元数据（类型名、是否必需、简短文档等）。

索引的生成与缓存则由 awsshell/index/completion.py 的CompletionIndex与 awsshell/makeindex.py 的write_index()负责。索引文件按completions-<AWS CLI 版本>.json命名，缓存在~/.aws/shell/cache目录下，因此升级 AWS CLI 后需要重建索引才能补全新增命令——这也正是 README 建议"每次 AWS CLI 发布新版本后执行升级"的原因。

Shorthand 语法自动补全

许多 AWS CLI 参数支持 shorthand（简写语法），aws-shell 能够在你输入这类参数后自动给出一个示例值。其实现依赖 awsshell/makeindex.py：建索引时调用ParamShorthandDocGen.generate_shorthand_example()为支持 shorthand 的参数生成示例，并存入argument_metadata[arg]['example']；运行时 awsshell/autocomplete.py 在用户输入带 shorthand 示例的参数后直接建议该示例。

服务端资源自动补全（Server Side Auto Completion）

除了本地命令补全，aws-shell 还通过 boto3（AWS SDK for Python）对服务端资源做自动补全，例如：

• Amazon EC2 实例 ID
• Amazon DynamoDB 表名
• AWS IAM 用户名
• Amazon S3 存储桶名

该功能处于活跃开发中，受支持资源的清单仍在持续扩充。仓库awsshell/data/目录下按服务与 API 版本存放了各服务的completions-1.json（例如 awsshell/data/ec2/2015-04-15/completions-1.json），其中以operations -> 参数 -> 资源名/标识符的形式记录了"哪个 API 参数对应哪个资源"。核心实现集中在 awsshell/resource/index.py：

• CompleterDescriber根据 service/operation/param 查表，给出完成补全所需的 API 调用与 JMESPath 提取路径；
• ServerSideCompleter.retrieve_candidate_values()实际创建 boto3 客户端发起调用（如 EC2describe-instances、IAMlist-users），再通过 JMESPath 表达式从响应中提取候选值返回。

触发时机在 awsshell/shellcomplete.py：当本地模型补全找不到任何候选、且当前输入处于某个 CLI 选项（如--instance-ids）时，才向服务端补全器发起请求，并用模糊搜索对结果做二次过滤。

模糊搜索（Fuzzy Searching）

所有自动补全候选都支持模糊搜索，让你用更少的按键输入命令、选项与取值。官方给出的典型用法：

• 输入每个子词的首字母：ec2 describe-reserved-instances-offerings→ 只需输入ec2 drio
• 每个词输入一部分：ec2 describe-instances→ 输入ec2 descinst
• 输入命令的任意片段：dynamodb table→ 列出所有包含子序列table的命令

算法实现位于 awsshell/fuzzy.py。fuzzy_search()对语料中的每个词调用calculate_score()打分（0 到 1），并按得分降序返回候选。打分策略的几个核心启发式（源码 docstring 中有详细说明）：

• 落在词边界（例如-之后）的子序列获得更高权重，因此drio匹配describe-reserved-instances-offerings的得分高于create-spot-datafeed-subscription；
• 匹配完整度越高得分越高：给定describe-instance时，describe-instances的排名会高于describe-instance-attribute；
• 与第 1 点类似，rinstance匹配run-instances会排在describe-instances之前，因为r恰好处在词边界。

这些行为都有对应的参数化测试佐证，见 tests/unit/test_fuzzy.py。

内联文档（Inline Documentation）

aws-shell 会在键入命令的同时自动拉取文档：

• 输入 CLI 选项时，补全菜单中内联显示该选项的简短说明；
• 界面下方有独立的文档面板，实时显示当前正在输入的命令或选项的完整文档。

按下F9可以在输入区与文档面板之间切换焦点，之后即可用你当前选定的键位绑定（Vi 或 Emacs）在文档中滚动浏览。

文档数据的生成在 awsshell/makeindex.py：启动时（或首次运行后台线程中）遍历 AWS CLI 的全部命令树，将每条命令的 help 输出从 RST 转换为纯文本，以aws.<service>.<operation>作为键写入 DBM 文档索引；运行期由 awsshell/docs.py 的DocRetriever按当前命令/选项实时抽取描述与参数说明。文档面板的展示逻辑在 awsshell/app.py 的on_input_timeout()中实现，输入停顿时自动更新。

Fish 风格自动建议（Auto Suggestions）

aws-shell 支持类似 fish shell 的自动建议：当历史记录中存在与你当前输入匹配的完整命令时，会在光标后以淡色提示完整命令，按右方向键即可一键采纳建议。底层来自 prompt_toolkit 的AutoSuggestFromHistory，相关配置见 awsshell/app.py 的create_buffer()。

命令历史

aws-shell 会记录你运行过的所有命令，并写入~/.aws/shell/history文件；在会话内可使用上、下方向键在历史中滚动浏览。从源码看，awsshell/app.py 同时维护了内存历史（InMemoryHistory，供.edit点命令与自动建议使用）与文件历史（FileHistory，路径由 awsshell/utils.py 的build_config_file_path('history')计算，即~/.aws/shell/history）。

工具栏选项（Toolbar Options）

awsshell 底部有一条工具栏，集中了多项运行时开关：

• F2：在模糊匹配与子串匹配之间切换
• F3：在 Vi 与 Emacs 键位绑定之间切换
• F4：在单列与多列自动补全菜单之间切换
• F5：显示/隐藏帮助文档面板
• F9：在 CLI 输入区与文档面板之间切换焦点
• F10或Ctrl-D：退出 aws-shell

工具栏上会实时显示当前各开关的状态（如Fuzzy: ON/OFF、Keys: Vi/Emacs、Single/Multi Column、Help: ON/OFF），实现见 awsshell/toolbar.py。

每当你在工具栏切换选项，偏好设置都会持久化到~/.aws/shell/awsshellrc文件，下次启动 aws-shell 时自动恢复。该文件的结构由仓库内的模板 awsshell/awsshellrc 定义：

[aws-shell] # fuzzy or substring match. match_fuzzy = True # vi or emacs key bindings. enable_vi_bindings = False # multi or single column completion menu. show_completion_columns = False # show or hide the help pane. show_help = True # visual theme. possible values: manni, igor, xcode, vim, # autumn,vs, rrt, native, perldoc, borland, tango, emacs, # friendly, monokai, paraiso-dark, colorful, murphy, bw, # pastie, paraiso-light, trac, default, fruity. # to disable themes, set theme = none theme = vim

各键位绑定的实现位于 awsshell/keys.py：F2直接翻转模糊匹配开关；F3/F4/F5在翻转开关后调用stop_input_and_refresh_cli()强制重建 CLI（因为键位、补全列数与帮助面板的改动需要重新布局）；F9在DEFAULT_BUFFER与clidocs两个缓冲区间切换焦点；F10直接请求退出。这些键位行为在 tests/integration/test_keys.py 中有完整的集成测试覆盖。配置的读写（含首次运行时从模板复制生成用户配置文件）见 awsshell/config.py。

Dot 命令：aws-shell 专有命令

除了 AWS CLI 命令，aws-shell 还提供一批外壳自身专有的命令，使用.前缀加以区分。点命令的分发由 awsshell/app.py 的DotCommandHandler负责，其注册表包含edit、profile、cd、exit、quit五类。

退出外壳：.exit / .quit

运行.exit或.quit即可退出外壳（等效于F10/Ctrl-D）。两者在源码中共享同一个ExitHandler（awsshell/app.py），处理结果会触发事件循环退出（EXIT_REQUESTED）。

用 .edit 生成 Shell 脚本

有时你想把 aws-shell 中连续执行的一串命令整理成 shell 脚本。除了持久化到 history 文件的历史记录，aws-shell 还会在内存中记录本次会话启动以来运行过的所有命令。运行.edit会把这些命令全部写入临时文件并打开编辑器：

aws> ec2 describe-instances aws> dynamodb list-tables aws> .edit

编辑器选择遵循EDITOR环境变量，未设置时默认 Windows 使用notepad、其他平台使用vi（见 awsshell/compat.py）。底层实现在 awsshell/app.py 的EditHandler：它会过滤掉以.或!开头的非 AWS CLI 命令，仅保留普通 AWS 命令拼接为文本，再调用编辑器打开临时文件；若编辑器启动失败，会提示你通过导出EDITOR环境变量来指定编辑器。相关行为在 tests/unit/test_app.py 中有测试验证。

切换 Profile：.profile

.profile点命令用于查看或切换当前 AWS CLI profile：无参数时打印当前配置的 profile；带一个参数时切换 profile（见上文"使用 Profile"一节）。用法示例：

aws> .profile demo Current shell profile changed to: demo aws> .profile Current shell profile: demo

ProfileHandler的实现与参数校验见 awsshell/app.py，参数个数非法时会向 stderr 输出用法说明。

切换工作目录：.cd

.cd命令用于改变 aws-shell 的当前工作目录：

aws> !pwd /usr aws> .cd /tmp aws> !pwd /tmp

ChangeDirHandler（awsshell/app.py）要求命令恰好带一个目录参数，且会先对路径做expandvars/expanduser展开（支持$VAR与~），切换失败时打印cd: <错误信息>。

与系统 Shell 的集成

aws-shell 以多种方式与外部命令协同工作。

管道与重定向：AWS CLI 命令的输出可以管道给其他进程，也可以重定向到文件：

aws> dynamodb list-tables --output text | head -n 1 TABLENAMES First aws> dynamodb list-tables --output text > /tmp/foo.txt

直接执行 Shell 命令：若想运行普通 shell 命令而非 AWS CLI 命令，给命令加上!前缀即可：

aws> !ls /tmp/ foo.txt bar.txt

这两类命令的执行都发生在 awsshell/app.py：以!开头的输入去掉前缀后原样交给 shell 执行；普通输入则补上aws前缀执行。注意只有普通 AWS 命令会进入历史与.edit的脚本候选，以.或!开头的命令会被过滤（见 awsshell/app.py）。

开发者预览状态

aws-shell 当前处于开发者预览（developer preview）阶段。项目欢迎功能建议、需求与 bug 报告；同时，为了持续响应社区反馈，未来版本可能会引入不向后兼容的变更。

更多参考资源

若想进一步深入，仓库内可直接查阅的素材包括：

• README.rst：本文所依据的官方 README 原文；
• awsshell/app.py：外壳主程序，点命令、事件循环、配置读写均在此；
• awsshell/autocomplete.py 与 awsshell/shellcomplete.py：两层自动补全的核心实现；
• awsshell/fuzzy.py 与 awsshell/substring.py：模糊/子串匹配算法；
• awsshell/resource/index.py：服务端资源补全的实现；
• awsshell/makeindex.py 与 awsshell/index/completion.py：补全索引与文档索引的生成、缓存机制；
• awsshell/awsshellrc：默认配置模板（F2~F5 开关的持久化结构）；
• tests/unit 与 tests/integration：涵盖模糊搜索、点命令、键位绑定、工具栏等行为的测试用例，是理解各功能预期行为的直接参考。

结合官方 README 的指引与仓库源码，你可以从"安装 → 配置 → 日常命令 → 补全与点命令 → 与 shell 集成"这条路径逐步上手 aws-shell，并借助源码理解其补全索引、模糊打分与服务端补全的底层机制。

• 开发工具
• CLI