MAWflow Host Base 用户手册

MAWflow Host Base 是 MAWflow 的本机技术运行底座，也是 Lite、Studio、Enterprise 共用的本机安装基础。它安装在你的电脑上，通过 @mawflow/cli 提供全局 mawflow 命令，负责安装与升级 Python 核心包 mawflow-host、启动本机控制台、保存本机登录激活状态、开放内置指令、基础功能模块和插件能力，并把本地项目能力和 MAWflow Account 连接起来。

安装与升级通道

Host Base 0.2.21

核验有效

Python Host Base 0.2.21 与 npm CLI 0.4.3 来自统一 Product Facts。软件包发布、Host Program 下发与重启保持独立生命周期。

当前稳定版

Python 0.2.21 / npm 0.4.3

核验状态

核验有效 · 2026年10月26日

运行兼容

Node >=18 · Python >=3.11

事实来源

构建时快照

部分事实已超过核验周期，当前展示最后一次可信快照。

查看运行边界

• 软件包发布不代表既有 Host Program 已自动升级或重启。
• CLI 发布不代表既有 Host Program 已自动升级或重启。

Host Base 在本机运行，敏感操作需要本机确认。AI Credits 平台的供应商密钥不下发到本机；你自己管理的受支持凭证，可以按授权上传到私有云端凭证库，再由获授权的设备同步使用。

MAWflow Host Base 提供 MAWflow 在本机环境中的安装、升级和运行能力，统一承载 CLI、本机控制台、插件机制以及本地能力连接。

Seed 为项目提供规范、声明和 AI 工作入口；Host Base 负责安装、升级、登录激活及本机服务；本地产品工作台把项目配置、文档和 AI 成果转为可阅读、可维护、可审阅的界面。你选择的 AI 工具仍在同一项目目录中工作，任务与节点能力按需启用。

Host Base 负责什么

能力	说明
mawflow CLI	提供全局 mawflow 入口，承接项目初始化、本机底座和后续插件命令。
本机运行环境	创建或复用 Host Base 专用 Python 虚拟环境，安装 mawflow-host。
安装升级	管理 Host Base 包升级、npm launcher 更新和本机环境修复。
登录激活	连接 MAWflow Account、设备登录记录、登录授权码和本机状态缓存。
插件能力	按权益开放本地项目空间、Local MCP、AI Credits 入口、Prompt Hub 或企业策略插件。
本机能力连接	连接本地产品工作台、项目和用户自有本机资源，默认不上传完整源码。

基础流程

1. 按下方本地工作台安装入口选择桌面 Host 档案。@mawflow/cli 0.4 系列默认准备 Seed CLI；要安装本地工作台，须显式选择 desktop-host。桌面安装器准备 Host Base 专用环境，并注册只监听本机的连接服务。
2. 打开本地产品工作台，按页面指引登录；也可执行 mawflow login 绑定当前账号。新账号默认使用 Lite。
3. 创建 Seed 项目或连接已有目录，在“项目概览”和“可视化配置”核对项目身份、定义及本轮需要的运行条件。
4. 用自己选择的 AI 工具打开同一目录，按项目入口和 Seed 规范开发并保存成果、验证记录与证据。
5. 在“文档中心”阅读项目正文，在“成果中心”核对来源和版本、记录审阅意见；已有资料的阅读不要求先启用节点或连接模型服务。
6. 需要工作台托管执行时，再到“本机 AI 环境”配置 AI 连接和节点并启动运行环境；需要团队或跨设备协作时再使用云端项目和分享。
7. 遇到安装或连接问题时，使用 mawflow status、mawflow host status 和 mawflow host doctor 核对实际状态。

本机连接服务与项目执行运行环境各自独立。停止执行运行环境后，仍可通过本地产品工作台读取允许访问的项目资料；具体页面、写入权限和离线边界见本地产品工作台快速开始。

无浏览器环境可以在 个人空间 生成“登录授权码”。0.2.3 及后续版本支持从标准输入或指定环境变量读取，避免授权码进入 shell history；登录授权码不是模型接口密钥，一个码只能使用一次，成功后会绑定首次登录的设备。

前置环境

项目	要求
操作系统	Windows 10 / 11、macOS 或主流 Linux 发行版。
Node.js / npm	用于安装 @mawflow/cli 全局入口。
Python	CLI 会复用 Python 3.11+ 且可导入 sqlite3、ssl、venv 的完整解释器；没有时准备受校验的托管 Python。
pip / venv	@mawflow/cli 创建或复用 Host Base 专用 Python 虚拟环境，不安装到系统 Python、发行版 Python 或 uv 管理的全局 Python。
网络	能访问 https://mawflow.com/npm/、https://mawflow.com/packages/simple、https://pypi.org/simple 和 https://mawflow.com。
登录	登录 个人空间 后可管理设备登录、生成登录授权码和强制下线设备。
后台运行依赖	0.2.3 起不再依赖 tmux；安装器按系统配置用户级 systemd、launchd 或 Windows 计划任务，失败时回退为受管后台进程。
网络代理	支持 HTTPS_PROXY、HTTP_PROXY、ALL_PROXY 与 NO_PROXY；preflight 只报告变量名，不输出代理凭据。
本机端口	默认只允许 127.0.0.1、localhost 或 ::1，不会终止占用端口的其它进程。

Windows PowerShell 如果首次执行虚拟环境激活脚本被拦截，可以只对当前窗口放行：

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

安装步骤

本次重构的公开发行版本

本地工作台重构已发布 Host 0.2.18rc8 与 CLI 0.4.0-rc.9，并在 macOS 正式安装验证。版本仍保留 RC 标识；Ubuntu、Windows 实机和真人使用验收分别记录，不代表已经通过。需要使用这次重构时，可显式选择以下版本与桌面档案：

MAWFLOW_INSTALL_PROFILE=desktop-host npm install -g @mawflow/cli@0.4.0-rc.9 --registry=https://mawflow.com/npm/
mawflow preflight --scenario reuse

Windows PowerShell 中，先设置 $env:MAWFLOW_INSTALL_PROFILE = "desktop-host"，再执行同一条 npm install。安装完成后清除本次设置的环境变量。已有安装应先核对当前任务状态，按安装器提示处理正在运行的服务；出现阻塞时不要强制终止任务。

稳定发行通道

安装全局 mawflow 入口：

npm install -g @mawflow/cli@0.4.3 --registry=https://mawflow.com/npm/
mawflow --help

显式 npm 安装会检查完整 Python 3.11+，必要时准备受固定版本和 SHA 校验保护的托管 Python，创建或复用 ~/.mawflow/venvs/host-base，再从官网 Python 包源安装 mawflow-host 0.2.21。Windows 默认使用 %USERPROFILE%\.mawflow\venvs\host-base。0.2.3 起，默认桌面安装还会执行受控初始化并注册本机连接服务；普通 mawflow 命令仍只检查运行时，不会静默修复或升级。修复应显式重装 npm 包；不要在任意目录直接运行裸 npm run bootstrap。

无头服务器若只需要 CLI/Python 运行时、不需要桌面 Host Agent，可显式选择：

MAWFLOW_INSTALL_PROFILE=workspace-server npm install -g @mawflow/cli@0.4.3 --registry=https://mawflow.com/npm/
mawflow --help

确认命令可用：

mawflow --help
mawflow host status

安装结束后，产品工作台应能探测 127.0.0.1:8765。host status 会分别显示 agent（本机连接）和 runtime（项目执行运行环境），两者不是同一个生命周期。

Python 兜底安装或故障修复时，可以显式检查并初始化：

mawflow host install
mawflow host doctor

稳定版：先检查，再初始化

以下步骤适用于上方稳定安装入口；核验日期和当前状态见本页安装与升级通道。

mawflow preflight --bind-host 127.0.0.1 --port 8765
mawflow host install --plan
mawflow host install --execute
mawflow host doctor

preflight 和 --plan 都是只读动作。端口被占用、路径不可写、Python 过旧或非 loopback 绑定会返回结构化 blocker 和修复建议；检查不会创建安装目录。0.2.3 起，host install --execute 会注册并启动本机连接服务，但不会登录账号、写入登录授权码或启动项目执行运行时。已有 manifest 无效时必须先审阅，再使用 --repair --execute；执行前会备份旧 manifest，保留已有项目事实。

Python 兜底安装

如果当前环境不能使用 npm 全局安装，可以手动创建 Host Base 专用 Python 虚拟环境，再直接安装 mawflow-host。

Windows PowerShell：

py -3.11 -m venv "$env:USERPROFILE\.mawflow\venvs\host-base"
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
& "$env:USERPROFILE\.mawflow\venvs\host-base\Scripts\Activate.ps1"
python -m pip install --upgrade pip
python -m pip install --index-url https://mawflow.com/packages/simple --extra-index-url https://pypi.org/simple mawflow-host

macOS / Linux：

python3 -m venv "$HOME/.mawflow/venvs/host-base"
. "$HOME/.mawflow/venvs/host-base/bin/activate"
python -m pip install --upgrade pip
python -m pip install --index-url https://mawflow.com/packages/simple --extra-index-url https://pypi.org/simple mawflow-host

如果安装时报 externally-managed-environment，说明你正在改全局 Python。请回到专用虚拟环境安装，不要使用 --break-system-packages。

本机连接、运行环境与登录

显式安装后，本机连接服务已经在线；以下命令分别查看连接与运行环境状态：

mawflow agent status
mawflow host status
mawflow host doctor

默认本机控制台地址为 http://127.0.0.1:8765。运行环境可以优先在产品工作台“宿主机与节点”页启动，也可从 CLI 启动：

mawflow host start

mawflow host stop 只停止运行环境，不停止本机连接服务。只有卸载或高级维护时才使用 mawflow agent stop；停止连接服务后，产品工作台将无法探测本机。

登录 Host Base：

mawflow login --service-url https://mawflow.com

命令会返回并尝试打开一个登录 URL。登录个人空间后确认本机设备，CLI 会自动完成登录，并把这台安装了 MAWflow 环境的设备绑定为账号宿主机。Lite 是登录账号的默认档位，不以 Host 登录为开通条件；Studio 和 Enterprise 仍按产品内指引升级。

无浏览器环境优先使用标准输入，授权码不会出现在进程参数和 shell history：

printf '%s\n' "$ONE_TIME_MAWFLOW_CODE" | mawflow login --code-stdin --service-url https://mawflow.com

也可以只传入环境变量的名字：

MAWFLOW_LOGIN_CODE='<一次性授权码>' mawflow login --code-env MAWFLOW_LOGIN_CODE --service-url https://mawflow.com

0.2.3 及后续版本支持 --code-stdin 和 --code-env 安全输入；固定旧版 0.1.4 仅保留为回滚参考，其旧 --code 参数会进入进程参数和 shell history，不应继续作为默认登录方式。登录授权码在个人空间生成，明文只在生成时返回一次。不要把登录授权码写入仓库、持久脚本、日志或截图。

查看状态：

mawflow status
mawflow plugins list

退出本机登录：

mawflow logout

也可以在个人空间的设备登录记录里对指定设备执行强制下线。

安装后快速进入 mawflow 环境

使用 npm 全局入口安装后，新终端可以直接运行：

mawflow --help
mawflow status

如果你走的是 Python 兜底安装，先激活虚拟环境，当前终端就可以直接使用 mawflow。

Windows PowerShell：

& "$env:USERPROFILE\.mawflow\venvs\host-base\Scripts\Activate.ps1"
mawflow --help
mawflow status

macOS / Linux：

. "$HOME/.mawflow/venvs/host-base/bin/activate"
mawflow --help
mawflow status

如果希望 Python 兜底路径的新终端也能直接输入 mawflow，可以把 Host Base 虚拟环境的命令目录加入当前用户 PATH。mawflow host install --execute 会按当前用户配置本机连接自启动，但不会写入登录授权码，也不会把项目执行运行时设为不可控的系统常驻服务。

自启动边界

从 0.2.3 起，安装器自动维护本机连接服务：Linux 使用 systemd user service，macOS 使用 LaunchAgent，Windows 使用当前用户计划任务；服务只监听 loopback，不向局域网开放管理端口。项目执行运行环境保持独立，可由产品工作台或 mawflow host start|stop|restart 控制。平台整包 Host Program 继续使用其原生 Supervisor 服务，不由 CLI 覆盖。

升级与停止

升级默认只生成计划。先记录计划里的精确目标版本、checksum 和确认字符串；以下占位项需要替换为实际计划返回值：

mawflow upgrade
mawflow upgrade --target-version <计划中的版本> --target-sha256 <官网公布的 sha256>

审阅后使用计划返回的确认字符串执行：

mawflow upgrade --target-version <计划中的版本> --target-sha256 <官网公布的 sha256> --execute --confirm UPGRADE:<计划中的版本>

执行前会下载当前版本备份和精确目标 artifact；checksum 不一致时不会调用安装。成功后结果包含 transaction ID、验证后的版本和 rollback 命令。0.2.3 起，升级成功会安排本机连接服务刷新并自动重连产品工作台；它不会登录账号、写入登录授权码或替用户启动已停止的项目运行环境。

需要回滚时也先查看计划，再精确确认：

mawflow upgrade --rollback <transaction-id>
mawflow upgrade --rollback <transaction-id> --execute --confirm ROLLBACK:<transaction-id>

需要切换项目运行环境状态时，可在产品工作台操作，也可使用：

mawflow host restart

更新 npm launcher 本身使用 npm：

npm update -g @mawflow/cli --registry=https://mawflow.com/npm/

当前稳定安装入口使用上方计划、checksum 与确认合同；固定旧版 0.1.4 和中间版本仅保留为回滚参考。若 pip 在 Windows 上提示临时目录被占用，先关闭正在使用该虚拟环境的终端或服务，再重新执行经过审阅的计划，不要使用 --break-system-packages。

卸载 Python 包不会自动删除你的本机配置、登录状态缓存或项目资料。需要清理本机数据时，请先确认备份和团队策略，再按产品内指引操作。

插件与权益

Host Base 内置插件按当前账号权益判断是否可用：

插件	Lite	Studio	Enterprise
节点管理	可用	可用	可用
本地账号池	可用	可用	可用
本地项目空间	可用	可用	可用
Local MCP	可用	可用	可用
AI Credits	查看入口	可用	可用
Prompt Hub	需开通	可用	可用
企业策略	需开通	需开通	可用

AI Credits 是远程执行额度，不是共享账号池。Host Base 不出租账号、不共享供应商密钥，也不会把第三方模型接口密钥下发给本地项目。

插件命令同样先计划、再确认。计划会显示权益 blocker、Host 版本兼容性、builtin 完整性摘要和 filesystem/network 权限：

mawflow plugins enable project-space-local
mawflow plugins enable project-space-local --execute --confirm ENABLE:project-space-local
mawflow plugins disable project-space-local
mawflow plugins disable project-space-local --execute --confirm DISABLE:project-space-local

未满足权益、Host 版本不兼容或完整性未验证时，启用会被阻止；不会用伪造的 mock checksum 或 mock signature 冒充已验证插件。

安全边界

• 显式安装会注册并启动仅监听 loopback 的本机连接服务；不会自动登录账号、写登录授权码、启动项目运行环境或上传项目源码。
• @mawflow/cli 只准备或修复 Host Base 专用 Python 环境、维护本机连接并转发 mawflow 命令，不自动切换到历史项目，不上传项目数据。
• 本机连接服务与项目运行环境分离；mawflow host stop 不会让账号宿主机从网页消失，mawflow agent stop 仅供卸载和高级维护。
• 登录授权码只用于无浏览器环境登录 Host Base，不是模型接口密钥，一个码只能使用一次。
• 每次 Host Base 登录都会在个人空间留下设备登录记录。
• 个人空间可对指定设备强制下线；下线后本机下一次刷新会看到 revoked / logged_out 状态。
• Host Base 本地 cache 不包含供应商密钥、支付信息、账号密码、登录授权码明文或项目源码片段。
• mawflow status、preflight、doctor 和 CLI JSON 会脱敏 home 路径、用户选择的绝对路径、URL 凭据、令牌、密码、敏感值、授权码和 API key。
• mawflow host doctor 只有在显式传入 --export <path> 时才写支持包；支持包继续使用相同脱敏规则。

常见问题

问题	处理
mawflow 找不到	先激活 Host Base 虚拟环境，或把虚拟环境命令目录加入 PATH。
mawflow login 打不开浏览器	复制命令输出的 URL 到浏览器打开，或使用个人空间生成的登录授权码。
无浏览器机器怎么登录	在另一台有浏览器的机器进入个人空间生成一次性授权码；0.2.3 及后续版本优先通过 --code-stdin 或 --code-env 读取。固定旧版 0.1.4 仅作为回滚参考，若临时使用旧 --code 必须清理 shell history。
preflight 报端口占用	选择其它 1024–65535 的本机端口；Host Base 不会结束占用该端口的进程。
doctor 显示 blocked	按 installation_manifest、service_process、local_health、plugin_integrity 的 remediation 逐项处理；不要把“有 PID”当成服务健康。
需要发支持包	执行 mawflow host doctor --export ./host-doctor.json；先人工复核，再发送给支持人员。
设备丢失或离职交接	在个人空间找到对应设备登录记录并强制下线。
插件显示 locked	当前账号权益不足，按 Lite / Studio / Enterprise 的产品内指引开通。
安装、账号、授权码或产品使用问题	产品支持：support@mawflow.com。

下一步

• Lite 安装与开通
• Project Init
• 本地产品工作台