CLI Guide

CLI 指引

Minimal Formal LoopCLI 已经能完成登录、云端注册、本地路径登记、直接执行、机器绑定，以及当前机器上的 Local Agent 轮询与执行。

网页入口更适合先感知单文件接入；CLI 更适合单文件或目录批量登记、本机路径登记和本地执行桥接。

execfabric-cli 是 ExecFabric 当前面向个人开发者、交付实施和本地执行场景的命令行入口。重点不是“做一个命令行皮肤”，而是把 本地脚本目录、本地运行环境和平台控制面 接成一条今天已经能用的桥。

CLI 这条线承接的是平台外部控制面与本地环境之间的桥接，用来把本地脚本、执行环境和平台治理链路接起来。

loginregisterlist / runagent bind / describe / start

EXECFABRIC // CLI BRIDGEDOC 07

const accountFlow = ['login', 'bind_machine', 'config']const workspaceFlow = ['manifest', 'metadata', 'upload_or_local_register']const executionFlow = ['run', 'agent_describe', 'agent_start']

LOCAL WORKSPACE / PLATFORM CONTROL

Implemented

当前已实现

login
register
list
run
agent describe、agent bind、agent start
sidecar JSON 覆盖，以及注释 / docstring / 文件名元数据提取
.execfabric-manifest.json 生成
register --execution-mode cloud 调用后端 upload-register，完成 Python / Shell 云端注册
register --execution-mode local-agent 调用后端 local-register，完成单文件或目录的本机路径登记
agent start 会在当前机器轮询、领取、执行并回传 Local Agent 作业

Not Yet

当前未实现

pull / publish / doctor
agent heartbeat / agent status / agent run
更通用的 Agent 在线治理、更多控制面和更细粒度多机调度
更多非 Python / Shell 资源类型的云端上传注册

Positioning

它在平台里的角色

个人开发者和技术用户更深一层的本地接入入口
项目交付时整理脚本目录、生成 manifest 的工具
平台控制面和本地运行环境之间的第一层桥接接口
当前最小正式 Local Agent 闭环，而不是已经做完的通用 Agent 产品

Public Onboarding

CLI 和公开入口的关系

陌生用户还是应该先从 Web 免登录体验页感受执行链路，再决定是否继续注册 / 登录。
CLI 是更深一层的本地接入入口，不替代 /experience 这条公开体验路径。
适合已经明确要把本地脚本、本地环境或内网资源接到平台控制面的人继续往下走。

Web Entry

CLI 与 Web 入口如何配合

网页端已经提供 /experience、/login、/register 三个正式入口。
注册成功当前会先进入 /register/result 结果页，再回到登录与个人主链路。
体验页用于先感受执行链路；当前左侧是 Python 示例 task_brief_demo.py，右侧是 Shell 示例 clean_log_demo.sh。
网页端上传注册已经支持 .py、.sh、.bash。
网页入口更适合可见的单文件接入；CLI 负责可重复的单文件 / 目录登记、本机路径登记和 Local Agent 执行桥接。

CLI In Path

CLI 在四层路径里更偏哪一层

路径	CLI 的角色	该怎么理解
免费线	不是默认入口	第一次接触平台的人应先走 Web 体验和注册流程，而不是一上来就使用 CLI。
本地脚本位增购	个人持续使用的本地桥接工具	适合已经在个人空间持续接脚本的人继续整理目录、生成 manifest，或者让脚本保留在本机但由平台派发回当前机器执行。
标准团队版	辅助接入和补充本地执行能力	团队版主入口仍是正式租户前端，CLI 更像桥接工具，不是正式团队入口本身。
企业交付	本地环境 / 内网资源桥接层	当项目涉及本地环境、内网资源或混合执行时，CLI / Local Agent 路线会更关键。

Cloud Mode

`cloud` 模式当前做什么

CLI 会扫描目录、提取元数据、生成 .execfabric-manifest.json，然后调用后端 upload-register
Python 和 Shell 脚本当前已经走真实的云端上传注册链路
如果目录里还有 bat、node 之类脚本类型，这条路径暂时还不会完整云端上传
这是把脚本内容进入平台注册中心的主路径

Local-Agent Mode

`local-agent` 模式当前做什么

CLI 会调用后端 local-register，登记本机路径而不是上传源码
同一条命令既支持整个目录，也支持单个脚本文件
Python、Shell、Bat、Node 的本地路径当前都可以登记到这条模式
当前机器的 machine_id、machine_name、agent_name 会一并登记，用于后续作业路由

Quick Start

快速开始

1. 安装到当前环境

cd execfabric-cli
python -m pip install -e .
execfabric-cli --help

这是当前最适合开发、自测和交付联调的安装方式。对外标准命令是 execfabric-cli。

2. 保存登录配置

execfabric-cli login \
  --token YOUR_API_TOKEN \
  --api-base http://tenant1000.localhost:6089 \
  --web-base http://localhost:81

默认配置文件是 ~/.execfabric/config.json。免费开发者默认应指向个人免费版域名；企业客户则指向各自租户域名。public 不是普通 CLI 用户的默认入口。

3. 以云端模式登记脚本目录

execfabric-cli register ./examples/scripts

命令会扫描目录、生成 .execfabric-manifest.json，并调用后端 upload-register。Python 和 Shell 当前已经走真实的云端注册链路。

4. 登记本地脚本并启动 Local Agent

execfabric-cli register ./examples/scripts --execution-mode local-agent
execfabric-cli register ./examples/scripts/backup.py --execution-mode local-agent
execfabric-cli agent start

这条路径会保留源码在当前机器，只登记目录或单文件路径，并让当前机器领取并执行被派发回来的 Local Agent 作业。

Common Commands

常用命令

只检查扫描结果，不写文件

execfabric-cli register ./examples/scripts --dry-run --print-json

适合先确认提取出来的 Skill 元数据是否符合预期。

只生成 manifest

execfabric-cli register ./examples/scripts --manifest-only

如果你暂时不想请求后端接口，可以先只生成本地 manifest。

查看 manifest 摘要

execfabric-cli list ./examples/scripts

list 当前必须显式传入 workspace，而且该目录下需要已存在 .execfabric-manifest.json。

直接触发 Skill 执行

execfabric-cli run backup_local \
  --request-text "CLI 手动执行备份" \
  --input-json '{"sourcePath":"/tmp/demo"}'

如果登录时保存了 --web-base，CLI 会额外输出可打开的 Web 链接。

查看或绑定当前机器

execfabric-cli agent describe
execfabric-cli agent bind \
  --machine-name "Alice MacBook" \
  --agent-name "alice-local-agent"

agent bind 用来持久化稳定的机器身份，供后续本地登记和 Local Agent 路由使用。如果不手工绑定，登录和 Local Agent 命令也会自动补齐默认值。

只跑一次 Local Agent 队列

execfabric-cli agent start --once

这是最直接的手动测试方式：最多领取一个作业、在当前机器执行，并把完成结果回传到平台。

Metadata

元数据和 sidecar 文件怎么协作

sidecar 命名

backup.py
backup.execfabric-skill.json
.execfabric-manifest.json

标准 sidecar 文件名是 <script_stem>.execfabric-skill.json，目录 manifest 是 .execfabric-manifest.json。

提取规则

CLI 会先从注释、docstring 和文件名提取元数据，再应用显式 sidecar 覆盖，最后把目录级摘要写进 manifest。

这也是为什么它既能做注册工具，也能做轻量的本地交付整理工具。

Path & Machine Rules

本地路径和机器绑定，当前按什么规则用

路径不要求统一

客户不需要把所有脚本放到固定盘符或固定父目录。
同一个用户的不同脚本，可以分别登记不同绝对路径。
Windows、macOS、Linux 的路径可以完全不同。
网页更适合单文件路径登记；CLI 更适合目录和批量登记。

机器绑定要收口

同一个 Skill 当前不能同时绑定多台机器，后端会直接拦住。
如果你有多台机器，应按“每台机器各自登记自己的脚本 / Skill”来用。
agent bind 和本地登记会把 machine_id / machine_name / agent_name 一并写入平台。
平台派发本地作业时，会按登记时绑定的机器路由回对应设备。

场景	当前做法	为什么这样做
只有一个本地脚本	可直接登记单文件路径	适合先把本机执行链路跑通，不必先整理整仓目录。
脚本依赖模板和同目录工具模块	登记实际入口文件，并保留同目录结构	Local Agent 执行时会在脚本所在目录启动，便于相对路径依赖生效。
本地和线上都存在同一能力	当前运行时优先走本地脚本	先满足客户本机环境、内网资源和本地数据依赖。

Current Boundary

CLI 当前已经证明什么

CLI 已经不只是本地 manifest 生成器，而是会真实调用后端注册与执行接口。
当前最小正式本地闭环已经成立：本地脚本可以登记、被派发回同一台机器、在本机执行，并把结果完成回写到平台。
Local Agent 执行中会持续回传 stdout / stderr 进度；如果脚本通过 __EXECFABRIC_RESULT__=JSON 声明结果产物，CLI 还会自动上传结果文件并回写下载信息。
网页入口仍更适合可见的单文件接入；CLI 更适合重复登记、目录接入和本机路径调度。
当同一能力同时存在本地脚本和线上脚本时，当前运行时优先走本地脚本。

Later Boundary

哪些还属于后续增强

heartbeat、status、更丰富的 Agent 控制面和在线治理
更细粒度的多机 / 多 Agent 调度与更完整的治理策略
除了当前 Python / Shell 主线之外，更完整的多类型云端注册路径

Next Read