Project Atlas · Source-led Edition

AI CLI Kickstarter 项目全景学习地图

面向完全不懂计算机的人，用不到 750 行代码完成“选择 AI CLI → 安装 → 验证 → 把后续指导交给 AI”的跨平台闭环。本页从产品意图、源码结构、状态机、安全边界、测试到学习路线，逐层拆开。

先抓住本质：它不是“安装器大全”

它是一座很短的桥：前半段降低安装门槛，后半段把电脑治理的主导权交给刚装好的 AI。

用户问题

新手知道 AI CLI 有用，却卡在终端、脚本、环境变量、权限与“装完以后做什么”。

项目解法

用双击入口 + 中英状态机，逐步显示选择、来源、确认、安装、验证与下一步。

产品闭环

安装不是终点。最后生成一段带安全规则的交接 Prompt，让 AI 成为长期电脑助手。

“一次性脚本”被设计成“人类把控制权安全地交给 AI 的仪式”。

11跟踪文件

739总行数（含 README / CI / 测试）

14提交，均在 2026-07-18

3×33 款 CLI × 3 个操作系统

2镜像状态机：Bash / PowerShell

结构极简，职责分层清楚

没有框架、数据库、包管理器和构建步骤。三个薄入口把用户导向两份核心脚本；测试用 curl 替身隔离真实网络。

ENTRY / 入口

Start-* 文件

适配双击或系统终端，定位脚本目录，然后把控制权交给对应状态机。

→

ENGINE / 引擎

Bash + PowerShell

语言、网络探测、供应商选择、确认、安装、验证、错误恢复与 AI 交接。

→

EXTERNAL / 外部

三家官方安装脚本

下载到内存后执行；真正的软件安装行为由供应商脚本决定。

ai-cli-kickstarter/
├── README.md
├── Start-macOS.command ─┐
├── Start-Linux.sh ──────┴─→ kickstarter.sh
├── Start-Windows.cmd ─────→ kickstarter.ps1
├── tests/
│   ├── run-tests.sh
│   └── stubs/curl
├── .github/workflows/ci.yml
├── .gitignore
└── LICENSE

README.md产品说明、使用方式、信任模型、开发命令与 10 个后续 Mission Prompt。

kickstarter.shmacOS/Linux 主逻辑，184 行；检查 OS 与 curl，并通过 bash -c 执行下载内容。

kickstarter.ps1Windows 镜像实现，209 行；要求 PowerShell 5+，用 Invoke-Expression 执行下载内容。

Start-*每个仅 3 行。macOS/Linux 用 exec bash；Windows 使用 NoProfile + ExecutionPolicy Bypass。

tests/真实驱动 Bash 状态机，但把 HOME、PATH、curl 和 stdin 都置于可控环境。

ci.ymlShellCheck、Ubuntu/macOS 冒烟测试、Windows PSScriptAnalyzer 三路质量门禁。

为什么这套结构适合新手

入口文件不用解释复杂命令；状态机一次只问一个问题；失败后提供“重试 / 换工具 / 退出”三条明确路径。

维护成本藏在哪里

Bash 与 PowerShell、中文与英文文案都写在代码里。新增状态、供应商或语言时，需要人工同步多个位置。

主角是状态机，不是 Shell 命令

每一屏对应一个状态。用户选择和外部结果只负责改变 STATE，随后进入下一轮循环，这让流程可解释、可恢复、也容易测试。

LANGUAGE

PROBE

SELECT

PRECHECK

CONFIRM

INSTALL

VERIFY

HANDOFF

README 展示上面 8 个主状态；源码实际还包含 ERROR 与 DONE。

LANGUAGE选择中文或 English；非法输入留在原状态，输入流关闭则安全退出。

PROBE请求 Google 204 探针，得到 reachable / unreachable / unknown；仅提示，不作为门禁。

SELECT默认 Qwen，也可选 Kimi 或 CodeBuddy；生成展示名、命令名、安装 URL 三元组。

PRECHECKBash 检查 Darwin/Linux 与 curl；PowerShell 只在脚本开头检查版本，状态本身直接通过。

CONFIRM明示供应商、Google 状态和来源 URL；回车即同意，拒绝则进入 DONE，不返回选择页。

INSTALL下载到内存并动态执行。下载为空、网络错误或安装器非零退出都会进入 ERROR。

VERIFY刷新当前会话 PATH，运行 <command> --version；找不到命令只提示重开终端，仍继续交接。

HANDOFF输出安全约束 Prompt；用户可立即启动新 CLI，也可结束。

ERROR 分支

重试 → PRECHECK
换工具 → SELECT
退出 → DONE

三个容易忽略的设计事实

网络探测结果不阻止安装。
验证失败不等于安装失败。
关闭 stdin 不会被当成默认同意。

核心数据
Version      0.1.0
State        当前流程状态
Language     zh / en
GoogleStatus 三值网络提示
ProviderName UI 展示名
CommandName  验证与启动命令
InstallUrl   官方脚本地址
LastError    错误说明

同一产品逻辑，两套平台语言

Bash 与 PowerShell 互为镜像，但不是逐字翻译：系统能力、下载 API、PATH 模型和进程启动方式不同。

环节	macOS / Linux	Windows	理解重点
用户入口	`Start-macOS.command` / `Start-Linux.sh`	`Start-Windows.cmd`	先切到文件所在目录，避免从别处启动时找不到主脚本。
最低环境	Bash + curl；OS 必须是 Darwin/Linux	PowerShell 5+	不安装项目自身依赖，依赖系统自带能力。
环境隔离	当前 Shell，`set -u`	`-NoProfile`，减少用户 Profile 干扰	两边都显式处理输入/网络失败，而不是依赖全局“遇错即停”。
网络探测	curl：连接 4 秒，总计 7 秒	Invoke-WebRequest：7 秒	204=可达，无响应=不可达，其他 HTTP=不确定。
安装下载	curl：连接 10 秒，总计 60 秒	Invoke-WebRequest：60 秒	内容保存在内存变量，不落临时文件。
动态执行	`bash -c "$installer"`	`Invoke-Expression $installer`	简单，但把供应链信任直接扩展到远端脚本。
PATH 刷新	补入 local/npm/bun/cargo 常见目录	合并进程 + Machine + User PATH，并补 CodeBuddy	只刷新当前会话，帮助马上识别新命令。
立即启动	`exec` 替换当前进程	`& $CommandName` 调用后返回	Unix 成功启动后不会再回到 DONE；Windows 会。

三家供应商映射

选择	定位	命令	macOS / Linux 来源	Windows 来源
1 · 默认	Qwen Code 大陆友好；独立安装器	`qwen`	`qwen-code-assets…/install-qwen-standalone.sh`	`qwen-code-assets…/install-qwen-standalone.ps1`
2	Kimi Code 首次启动后输入 `/login`	`kimi`	`https://code.kimi.com/install.sh`	`https://code.kimi.com/install.ps1`
3	CodeBuddy CLI 腾讯生态；官方文档标为 Beta	`codebuddy`	`https://www.codebuddy.cn/cli/install.sh`	`https://www.codebuddy.cn/cli/install.ps1`

源码导览：先读函数，再读循环

推荐顺序不是从第 1 行读到最后，而是先认清“功能积木”，再看状态循环怎样拼装它们。

① 国际化字典

Shell 18–73 · PowerShell 18–51

t/T 根据当前语言返回界面文案。优点是单文件可运行；代价是新增语言时源码膨胀，并且两种实现都要同步。

② 网络探针

Shell 77–84 · PowerShell 60–70

固定访问 google.com/generate_204，把复杂网络现象压缩成三值提示。结果与安装选择解耦。

③ 供应商选择

Shell 86–92 · PowerShell 76–82

一个数字映射为 ProviderName + CommandName + InstallUrl。这三个字段贯穿确认、下载、验证与启动。

④ PATH 同步

Shell 94–97 · PowerShell 84–90

安装器可能刚把命令放到新目录；当前终端不会自动刷新，所以项目主动补齐常见路径再验证。

⑤ AI 交接 Prompt

Shell 99–129 · PowerShell 92–122

不是帮助文本，而是下一阶段的“行为合同”：解释、备份、先问、验证、单独测网络、避免过载。

⑥ 状态分派循环

Shell 131–184 · PowerShell 124–209

每轮只执行一个状态分支，再更新状态。逻辑集中、跳转显式，因此可以用脚本化 stdin 驱动真实流程。

一条关键工程纪律

kickstarter.sh 与 kickstarter.ps1 顶部都写明彼此镜像；README 也要求修改状态或文案时同步两份。这是当前架构最重要的维护约束。

安全模型：确认来源，不验证内容

项目没有隐藏这一点：它把三家官方远程脚本下载到内存后直接执行。用户确认的是 URL 和供应商信任，不是某个经过固定校验的脚本版本。

本仓库可控边界

选择、提示、确认、状态恢复

来源 URL 固定在源码
执行前展示并等待确认
没有主动 sudo / UAC 逻辑
失败可重试、换工具或退出

下载 →
结果 ←

外部信任边界

供应商远程安装脚本

内容随供应商服务器变化
可能安装依赖、改 PATH 或请求权限
项目不审阅、缓存或固定内容
真正的安装副作用在此发生

已有保护 · 明示 URL用户在 CONFIRM 页面能看到将要访问的地址和供应商。

已有保护 · 明确同意核心 read/Read-Host 失败不会默认为同意；拒绝时跳过安装。

待增强 · 无哈希/签名没有 checksum、代码签名或公钥验证，无法证明下载内容与已审版本一致。

待增强 · 无版本固定URL 指向当前安装器，而非不可变版本；今天与明天下载的内容可能不同。

待增强 · 无内容预览脚本保存在内存后立即动态执行，用户无法先保存、检查再继续。

待增强 · 无真实供应链测试离线测试故意不访问网络，因此无法发现供应商 URL 或安装协议变化。

语义提醒 · “直连”并不严格curl / Invoke-WebRequest 默认可能服从环境或系统代理；探针证明的是当前进程可达，不一定是无代理直连。

语义提醒 · 重定向后的来源下载客户端允许跟随跳转，最终执行内容的实际主机可能不同于确认页展示的初始 URL。

正确心智模型

“官方域名”降低了误下载风险，但不等同于“内容已被本项目验证”。把它当作透明的引导器，而不是安全沙箱。

真正的产品亮点：安装后的 AI 交接

项目把“安装成功”改写成“能力交接”：先给 AI 一套行为边界，再通过 Mission Prompt 把模糊愿望变成可完成任务。

第 0 个任务 · 交接 Prompt

执行前用通俗语言解释。
改配置前先备份。
管理员权限、删除、覆盖、付费、隐私先询问。
每完成一步都验证。
每个在线服务分别实测。
只在必要时教学，避免一次塞太多。

首问：检查当前电脑，并告诉我下一步最值得做什么。

起步 · Mission 1–2

初始化电脑 / AI 工作站

建立必要工具链，并围绕编程、写作、研究、终端、浏览器与 Agent 选择能力。

体检 · Mission 3–6

硬件、终端、软件、存储

先盘点和出方案，再逐项确认；清理明确要求未经确认不删除，并优先可恢复方式。

网络 · Mission 7–8

局域网 / 跨地点私网

局域网审计保持只读；跨地点网络先比较架构，选定后再逐步实施。

进阶 · Mission 9–10

自动化 / 长期 IT 工程师

先识别值得自动化的重复工作；长期模式强调最简单可靠方案和渐进式教学。

Prompt 的写法为什么有效

每个 Mission 都包含目标、范围、权限边界和交付顺序，减少 AI 自作主张；“先列清单、经确认再修复”是最常见控制结构。

可迁移到你自己项目的公式

角色 + 用户水平 + 目标 + 范围 + 禁区 + 验证 + 下一步。这比一句“帮我优化电脑”稳定得多。

测试策略：隔离副作用，驱动真实状态机

测试不调用任何真实供应商。它通过脚本化输入、临时 HOME、最小 PATH 和 curl 替身，让真实 Bash 逻辑在安全环境中跑完整分支。

脚本化 stdin

精确模拟选择、确认、退出和 EOF。

隔离 HOME / PATH

避免读取真实配置或找到已安装的 CLI。

curl stub

网络探针固定 204；安装下载可成功或失败。

验证退出码 / 输出

15 秒超时捕捉无限循环回归。

场景	断言	它防住什么
一开始 stdin 关闭	非零退出；不运行安装器	无输入时死循环或误装。
选语言后 EOF	非零退出；不运行安装器	把 EOF 当成默认选择或默认同意。
下载失败	显示失败与下载原因；不进 VERIFY；可退出	空脚本被当作成功、错误状态不可恢复。
模拟安装成功	执行桩；进入 VERIFY；提示命令未出现；正常退出	状态链断裂、验证失败导致异常退出。
确认页拒绝	不运行安装器；正常退出	用户拒绝后仍执行外部脚本。

未全覆盖

测试覆盖范围

项目测试未覆盖 ShellCheck、PSScriptAnalyzer 和 Windows 功能流程；CI 配置包含前两项，但 PowerShell 目前仍只有静态 lint。

不要把 exit 0 当成“安装已成功”

VERIFY 找不到命令时只显示提示，随后仍进入 HANDOFF，用户也可以正常退出。因此退出码代表启动器流程结束，不证明新 CLI 已可用；旧的同名命令还可能造成验证假阳性。

CI 的三条跑道

LinuxShellCheck：主脚本、入口、测试与 stub

Linux + macOS真实驱动 Bash 状态机的离线冒烟测试

WindowsPSScriptAnalyzer；排除 Write-Host / Invoke-Expression 规则

14 次提交讲清了作者最在意什么

所有提交发生在 2026-07-18。演进顺序不是堆功能，而是连续修正失败、授权、PATH、跨平台一致性、测试与文档。

6e7c0db初始导入导入 v0.1.0 的完整跨平台启动器。

24526aa错误处理Bash 把下载失败明确转为 ERROR。

230fa86授权安全stdin 关闭时退出，不再无限循环或推定同意。

0afce62简化去除无用变量、复用同意判断、报告启动失败。

24aac32Windows保留会话 PATH，并验证下载内容非空。

adfcc59一致性增加 PowerShell 版本门禁，对齐网络探测与同意语义。

f98cf16入口稳健切换脚本目录失败时立即退出。

12a2324测试加入 Bash 状态机离线冒烟测试。

85a7213自动化加入 Linux/macOS/Windows 三路 CI。

353d846开放许可加入 MIT License。

3418633透明度补 SmartScreen、信任模型、开发流程和许可证说明。

45a4ef1命名把 Windows PATH 函数改名为更准确的 Sync-SessionPath。

f3ef5b6产品闭环加入安装后的 Mission Prompt 库。

9370aef兼容性clear_screen 改用显式 if，成为本报告快照提交。

建议这样学：6 个回合，从产品到源码

不要急着逐行背 Shell。每一回合只回答一个问题，并留下一个可以复述或验证的结果。

先跑脑内流程只读 README 1–40 与状态机 142–164，画出用户从双击到 HANDOFF 的路径。

能用 60 秒解释“项目为谁解决什么问题”。

读三个入口理解脚本目录、exec、NoProfile、ExecutionPolicy Bypass 的局部含义。

能解释为什么入口文件都只有 3 行。

先函数后循环按网络探针 → 供应商映射 → PATH → handoff 顺序读函数，再读状态循环。

能追踪选择“2”以后三个核心变量如何变化。

比较 Bash 与 PowerShell沿同一个状态横向对照两份实现，找出系统 API 不同与产品语义相同的地方。

能说出至少 4 个平台差异。

读测试理解安全先看 curl stub，再看 run_kickstarter 如何隔离 HOME/PATH、注入 stdin、捕捉超时。

能解释为什么测试不会真的安装软件。

做一次小改动演练在副本中新增一条纯文案，不碰安装 URL；同步中英与双脚本，并跑离线测试。

理解“镜像维护”成本，而不是只看见 739 行很少。

核心术语词典

CLI: 命令行界面；通过文字命令与软件交互。
状态机: 把流程拆成有限状态，每次根据输入跳到下一状态。
stdin: 标准输入；这里就是用户在终端里键入的回答。
PATH: 系统寻找命令的目录清单；新安装命令常因 PATH 未刷新而暂时不可见。
stub / 测试替身: 用可控小程序代替真实 curl，避免网络与安装副作用。
动态执行: 把下载到的文本当代码运行；方便但需要高度信任来源。
CI: 每次推送或 PR 自动运行检查，防止回归进入主分支。
smoke test: 覆盖关键路径的快速测试，不等同于完整测试。
handoff: 把后续任务、规则和上下文交给另一个执行者；这里是交给 AI CLI。

常见误解，一次澄清

问题	准确答案
它内置了 AI 吗？	没有。它安装外部 AI CLI，并输出后续交接 Prompt。
会把三款工具都装上吗？	不会。一次只选择一款，回车默认 Qwen。
Google 不通就不能继续？	不会拦截。探针只是提示，三家服务仍需分别测试。
只想看看，确认页按回车安全吗？	确认页的空输入等于 Yes；只参观应明确输入 `n`。
启动器会审查远端脚本吗？	不会。它展示初始 URL，但不做内容预览、版本固定、哈希或签名校验。
VERIFY 失败等于安装失败？	不一定，可能只是 PATH 尚未刷新；项目会继续显示 handoff。
测试会真的联网安装吗？	Bash 冒烟测试不会；curl 已被本地 stub 替换。
这是成熟大型工程吗？	不是。它是同日快速加固的小型 v0.1.0，适合学习清晰产品闭环与状态机。

评审结论：小而完整，但“远程脚本即信任”是天花板

以下把源码事实与评审建议分开：左边是已经做好的工程选择，右边是若继续演进最值得优先投入的方向。

已经做得好的

✓

目标用户与流程高度一致一次一问、默认选择、失败恢复、双击入口都服务于“完全新手”。

✓

授权语义被认真修过EOF 不被当成默认同意；确认页展示具体来源；拒绝后不安装。

✓

无框架、无构建、可读性高核心逻辑都在两份脚本内，适合学习状态机和跨平台差异。

✓

离线测试真正驱动主逻辑不是复制逻辑到测试里，而是通过 stdin 和 curl stub 运行真实脚本。

✓

安装后有明确产品闭环交接 Prompt 与 Mission 库把一次安装转化为长期 AI 使用路径。

若继续演进，优先级建议

建立可验证供应链固定发布版本；提供 checksum / 签名；支持“先下载并查看，再执行”。

给 PowerShell 增加功能测试目前 Windows 只有静态 lint，没有像 Bash 那样驱动状态机的离线分支测试。

扩展网络三值与三供应商测试覆盖 unreachable/unknown、各选项映射、重试与换工具路径。

减少镜像漂移把状态/文案/供应商元数据抽为单一规范，并自动生成或比对两端实现。

加上可观察性与失败指导为常见代理、TLS、权限、PATH 问题提供可复制诊断信息，同时避免泄露隐私。

最值得带走的一课

这个项目的价值不在技术复杂度，而在“把用户从未知状态安全地推进到可自助状态”。结构、状态机、测试和 Prompt 都围绕同一个用户旅程，没有多余层。

↗

证据索引与核对范围

报告基于 main 分支提交 9370aef 的只读快照，并与 GitHub 仓库页交叉核对。没有运行任何真实安装器。

README.md: 1–33目标用户、支持范围、三平台用法。
README.md: 35–140通用前置与 10 个 Mission Prompt。
README.md: 142–171状态机、网络探测、信任模型、开发流程。
kickstarter.sh: 1–184Bash 完整实现；核心状态循环为 131–184。
kickstarter.ps1: 1–209PowerShell 完整实现；核心状态循环为 124–209。
tests/run-tests.sh: 1–96隔离策略、五场景、14 个断言与超时机制。
tests/stubs/curl: 1–12Google 204、下载成功/失败模拟。
ci.yml: 1–32三路 CI 与 PowerShell lint 排除项。
git log: 14 commits2026-07-18 的演进顺序与修复意图。
GitHub 原仓库官方 README、文件列表、提交与许可证入口。