文档 — vzhan

§1 CLI 命令参考

所有命令支持 --json 输出，统一信封格式： {"exit_code":<int>,"data":<object|null>,"error":<object|null>}。 Agent 优先使用 --json 解析结果。

1.1 网络命令

swarm — P2P 节点管理

命令	功能	状态
`swarm peers`	列出已连接的对等节点	stable
`swarm id`	查看本节点标识（NodeId + PeerId）	stable
`swarm addrs`	列出已知节点的网络地址	stable
`swarm connect`	手动连接到指定地址的节点	stable
`swarm disconnect`	断开与指定地址的连接	stable
`swarm filters`	管理地址过滤器	stable
`swarm local`	查看本地网络地址	stable

# 查看对等节点
Leither swarm peers --json

# 查看本节点标识
Leither swarm id

dht — 分布式哈希表

命令	功能	状态
`dht netsize`	DHT 网络节点总数	stable
`dht show`	DHT 路由表详情（LAN/WAN 分表）	stable
`dht get`	从 DHT 读取键值	stable
`dht put`	向 DHT 写入键值	stable
`dht findpeer`	在 DHT 中查找指定 Peer	stable

1.2 文件命令

files — MFS 文件系统

命令	功能	状态
`files ls`	列出 MFS 目录内容	stable
`files stat`	显示文件/目录状态信息	stable
`files cp`	复制文件或目录	stable
`files mv`	移动文件或重命名	stable
`files rm`	删除文件	stable
`files mkdir`	创建目录	stable
`files flush`	将路径数据刷写到磁盘	stable
`files check`	检查哪些文件本地不可用	stable

1.3 应用命令

lapp — MApp 管理

命令	功能	状态
`lapp uploadapp`	上传并部署 MApp 到当前节点	stable
`lapp showapp`	列出所有已部署的 MApp 及详情	stable
`lapp release`	发布 MApp 到 P2P 网络	stable
`lapp backup`	备份应用数据	stable
`lapp restore`	从备份恢复应用	stable
`lapp delver`	删除指定版本	stable
`lapp uploadfile`	上传文件到应用	stable
`lapp setdomain`	设置应用域名	stable
`lapp resetref`	重置应用引用	stable

lpki runapp — 运行 MApp

命令	功能	状态
`lpki runapp --id <id>`	通过容器 ID 运行 MApp	stable
`lpki runapp --local <path>`	从本地路径开发调试运行	stable
`lpki runscript`	在容器中运行脚本	stable

MApp 部署后自动注册 HTTP 路由。Agent 通常直接通过 curl http://127.0.0.1:4800/entry?aid=<id>&ver=cur 调用 MApp，无需 runapp 子命令。

1.4 身份命令

lpki — PKI 密码学体系

命令	功能	状态
`lpki genkey`	生成密钥对	stable
`lpki genpk`	从私钥导出公钥	stable
`lpki gencert`	生成证书（CA 签名）	stable
`lpki genpkcert`	生成公钥证书	stable
`lpki gensid`	生成会话 ID	stable
`lpki signppt`	对 PPT 令牌签名	stable
`lpki verifyppt`	验证 PPT 令牌签名	stable
`lpki addkey`	将密钥添加到节点	stable
`lpki id`	显示节点 ID	stable
`lpki show`	显示对象信息	stable
`lpki grantservice`	向目标节点授权服务	stable
`lpki reqservice`	从节点请求服务授权	stable
`lpki shell`	启动交互式 Shell	stable

# 生成密钥和证书
Leither lpki genkey -o user.key
Leither lpki genca -k user.key -m "name=user" -o user.ca

# 上传 MApp（需作者密钥签名）
Leither lapp uploadapp ./myapp -k user.key

1.5 存储命令

mimei — MiMei 去中心化存储

命令	功能	状态
`mimei create`	创建新的 MiMei 数据对象	stable
`mimei add`	添加文件或目录到 MiMei	stable
`mimei get`	读取 MiMei 内容	stable
`mimei ls`	列出 MiMei 目录内容	stable
`mimei show`	显示 MiMei 详情	stable
`mimei sync`	跨节点同步 MiMei 数据	stable
`mimei backup`	备份当前版本到上一版本	stable
`mimei restore`	从备份恢复数据	stable
`mimei diagnose`	对 MiMei 数据库运行健康检查	stable
`mimei repair`	修复 MiMei 数据库（MAC 重建等）	stable
`mimei rebackup`	修复备份错误	stable
`mimei publish`	发布 MiMei 到 P2P 网络	stable
`mimei findprovs`	查找提供此 MiMei 的节点	stable
`mimei provide`	宣告本节点提供此 MiMei	stable
`mimei setright`	设置 MiMei 权限	stable
`mimei setdomain`	设置 MiMei 域名	stable

# 诊断 MiMei 健康状态
Leither mimei diagnose <mid>

# 跨节点对比（远程诊断）
Leither mimei diagnose <mid> -n <node>

# 修复 MAC 不一致
Leither mimei repair <mid>

# 从对端同步数据
Leither mimei sync <mid>

1.6 系统命令

命令	功能	状态
`run`	启动 Leither 服务（`-d` 后台运行）	stable
`stop`	停止 Leither 服务	stable
`version`	显示版本、架构、API 版本	stable
`getvar`	查询系统变量（如 `getvar ver`）	stable
`update`	更新 Leither 到最新版本	stable
`stat ledger`	查询用户账本统计	stable
`stat mimei`	查询 MiMei 统计	stable
`stat user`	查询用户统计	stable
`notify`	发送邮件通知	stable
`init`	初始化 Leither 服务配置	stable
`mcp`	MCP 协议工具集	beta

§2 MApp 开发规范

MApp（MiMei Application）是 vzhan 容器中的可执行应用，支持 Go 和 JavaScript 语言。应用通过解释执行（不编译为原生二进制），自动注册 HTTP 路由。

2.1 应用结构

myapp/
├── main.go          # 主程序（Go MApp 入口）
├── utils.go         # 工具函数
├── config.json      # 配置文件
└── .manifest        # 清单文件（自动生成）

2.2 Go MApp — RunMApp 模式（推荐）

实现 RunMApp 函数，通过 Entry 参数路由到不同处理逻辑。

package main

import (
    "fmt"
    "github.com/3and4/Leither/lapi"
)

func RunMApp(Entry string, Request map[string]string, args []any, wr io.Writer) (any, error) {
    lapi := lapi.GetLApi()

    switch Entry {
    case "test":
        return "Hello from test entry", nil
    case "process":
        return processData(Request, args)
    default:
        return fmt.Sprintf("Entry: %s", Entry), nil
    }
}

2.3 Go MApp — main 函数模式

func main() {
    lapi := lapi.GetLApi()
    request := lapi.GetRequest()
    args := lapi.GetArgs()

    // 处理逻辑
    fmt.Fprintln(lapi.GetWriter(), "Hello from main")
}

2.4 JavaScript MApp

JS 文件作为独立入口点，通过 entry 参数指定。每个 .js 文件对应一个入口名。

# JS MApp 可用入口示例（来自 testjs 应用）
runmapp, testlog, testtx, testw

# 通过 entry 参数调用
curl "http://127.0.0.1:4800/entry?aid=<id>&ver=cur&entry=runmapp"

2.5 部署命令

# 1. 生成密钥
Leither lpki genkey -o user.key

# 2. 上传应用（部署到当前节点）
Leither lapp uploadapp ./myapp -k user.key

# 3. 发布到 P2P 网络（其他节点自动同步）
Leither lapp release -a myapp

# 4. 本地开发调试
Leither lpki runapp --local ./myapp test_entry -r "param1=value1" -a user.key

2.6 关键约束

MApp 由 Leither 解释执行，不编译为独立可执行文件。用 go build 检查语法，不用 go run
Go MApp 导入路径为 github.com/3and4/Leither/lapi
部署后自动注册 HTTP 路由：http://127.0.0.1:4800/entry?aid=<id>&ver=cur
应用代码和资源存储在 MiMei（IPFS 兼容的内容寻址存储）中，通过 P2P 网络自动同步

§3 HTTP API 参考

Leither 节点通过 HTTP 接口对外提供服务。MApp 部署后自动注册路由，Agent 可直接通过 HTTP 调用。

3.1 系统端点

端点	方法	功能	状态
`/getvar?name=<key>`	GET	查询系统变量（ver、ServicePort 等）	stable
`/entry`	GET	MApp 执行入口——核心路由参数：aid, mid, ver, entry, nid	stable
`/api/v0/version`	POST	IPFS 组件版本（非 Leither 整体状态）	stable

3.2 /entry — MApp 执行端点

MApp 的核心调用入口。部署后每个应用自动获得此路由。

参数	必需	说明
`aid`	是	应用 ID（从 `lapp showapp` 获取）
`ver`	推荐	版本号（`cur` 或数字）。默认最新
`entry`		入口名（对应 RunMApp 的 Entry 参数或 JS 文件名）
`mid`		MiMei ID（指定数据源）
`nid`		远程节点 ID（跨节点 RPC 调用）

# 基础调用
curl "http://127.0.0.1:4800/entry?aid=1ZLw8a9HvMnlnDzvo9JtktjW_3j&ver=cur"

# 指定入口
curl "http://127.0.0.1:4800/entry?aid=<id>&ver=cur&entry=whoami"

# 跨节点调用
curl "http://127.0.0.1:4800/entry?aid=<id>&nid=<peer-id>"

3.3 lapi — MApp 内可用接口

MApp 代码中通过 lapi.GetLApi() 获取的 API 实例，提供以下能力：

接口	方法示例	功能
`IBackEnd`	`GetLApi()`, `GetArgs()`, `GetRequest()`	获取 API 实例和请求上下文
`ISession`	会话状态读写	跨请求持久化
`IBEAppData`	`MMOpenAppData()`	打开应用专属 MiMei 数据库
`ILog`	`Debug()`, `Info()`, `Warn()`, `Error()`	分级日志输出
`IAuth`	身份验证操作	签名、验证
`IVarAct`	`GetVar()`, `SetVar()`	键值存储（读写系统/应用变量）
`IMiMei`	`MiMeiSync()`	MiMei 数据操作和同步
`INet`	`SwarmPeers()`, `SwarmConnect()`	P2P 网络操作

MApp 只能访问 lapi 公开层接口。内部 API（api.LApi）包含更多方法（ITunnel、IDNS、INode、IIpfs、ISystem 等），仅供 Leither 内部使用。详见 MApp 容器架构文档。

3.4 HTTP 响应格式

MApp 的返回值通过 io.Writer 输出。返回类型决定响应格式：

字符串 / 数字 → 直接写入响应体
HTML 模板 → 自动渲染（模板引擎使用 Go text/template）
复杂对象 → 通过 fmt.Fprintln(wr, obj) 输出
错误 → 返回 HTML 错误页面：<html><title>Error</title><body>Error:...</body></html>