MAWflow Host Base 用户手册

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

安装与升级通道

Host Base 0.2.5

等待复核

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

当前稳定版

Python 0.2.5 / npm 0.3.12

核验状态

已过核验周期

运行兼容

Node >=18 · Python >=3.11

事实来源

构建时快照

查看运行边界

• 软件包发布不代表既有 Host Program 已自动升级或重启。
• CLI 发布不代表既有 Host Program 已自动升级或重启。
• 部分事实已超过核验周期，当前展示最后一次可信快照。

Host Base 不是共享账号池，也不是远程接管工具。它只在你本机运行，敏感操作需要本机确认，真实供应商密钥不会下发到本机。

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

Seed 解决代码仓库如何建立 AI 项目导航体系；Host Base 解决开发环境如何安装、升级、登录激活、启动本机控制台并开放插件能力；Project Space 解决真实项目如何持续推进和验收。三者不是替代关系，而是同一条 AI 项目执行路径上的不同底座。

Host Base 负责什么

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

基础流程

1. 注册并登录 MAWflow Account；新账号默认使用 Lite。
2. 在目标电脑安装 @mawflow/cli。从 0.2.3 起，安装会自动初始化本机环境，并注册只监听 127.0.0.1 的用户级连接服务。
3. 回到产品工作台“宿主机与节点”页确认“本机连接在线”。未登录本机账号时，页面仍能识别 CLI，但不会读取账号宿主机和节点。
4. 执行 mawflow login 绑定当前账号；页面随后显示这台宿主机及主脑、验收、执行三个默认节点。
5. 在页面启动或停止运行环境；连接服务保持在线，因此运行环境停止后仍能从网页重新启动、检查版本或升级。
6. 创建或进入项目并选择可用节点。Seed 是项目协作规范，不是 Lite 或 MAWflow 产品的启动条件。
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	Python 3.11 或更新版本。
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

安装步骤

安装全局 mawflow 入口：

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

显式 npm 安装会检查 Python 3.11+，创建或复用 ~/.mawflow/venvs/host-base，从官网 Python 包源安装 mawflow-host。Windows 默认使用 %USERPROFILE%\.mawflow\venvs\host-base。0.2.3 起，显式安装还会执行受控初始化并注册本机连接服务；普通 mawflow 命令仍只检查运行时，不会静默修复或升级，修复必须通过用户显式 npm 安装或 bootstrap 动作。

确认命令可用：

mawflow --help
mawflow host status

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

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

mawflow host install
mawflow host doctor

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

以下合同已随稳定版 0.2.3 发布并完成外部包源验证：

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 覆盖。

升级与停止

稳定版 0.2.3 的升级默认只生成计划。先记录计划里的精确目标版本、checksum 和确认字符串：

mawflow upgrade
mawflow upgrade --target-version 0.2.3 --target-sha256 <官网公布的 sha256>

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

mawflow upgrade --target-version 0.2.4 --target-sha256 <官网公布的 sha256> --execute --confirm UPGRADE:0.2.4

执行前会下载当前版本备份和精确目标 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/

当前稳定版 0.2.3 使用上方计划、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 不出租账号、不共享供应商密钥，也不会把第三方模型接口密钥下发给本地项目。

稳定版 0.2.3 的插件命令同样先计划、再确认。计划会显示权益 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
• 本地产品工作台