命令参考

wopal 是 WopalSpace 的确定性操作入口。下面按功能域列出全部命令。版本可能演进，运行 wopal <command> --help 可查看该命令权威、最新的参数与默认值。

全局约定

  • --space <name>：显式指定目标空间（仅本次生效，不持久化）；否则按当前工作目录自动解析所属空间。
  • --json --api-version <major>：需要被脚本 / 引擎稳定消费的能力，以版本化 JSON 契约输出（人类默认读 Markdown）。
  • 变更类命令默认 dry-run：space update、ontology update / contribute / reconcile / promote 等会先展示将要发生的 diff / merge 预测，加 --confirm 才真正执行。
  • --help / -h、--version / -v 对所有命令可用。

安装与首次编排

wopal setup

首次环境编排向导（Inspect → Configure → Execute）。准备 WOPAL_HOME、拉取本体、安装 ellamaka 引擎、物化基础能力、初始化并注册第一个空间，并在 Configure 阶段收集 AI provider 凭证。

wopal setup
wopal setup --remove     # 反安装向导：只清理 WOPAL_HOME，保留所有空间与项目

wopal doctor

只读诊断，检查 Git / 网络 / 目录权限 / 引擎 / 本体状态并给出修复建议。

wopal update

升级 wopal 命令本身（self-update）。

空间管理：wopal space

命令作用
wopal space list列出已注册空间
wopal space projects list发现空间内的 Git 项目目录
wopal space directories search <q>按名称搜索空间内子目录
wopal space init [name] [path]创建新空间（含本体 worktree 与运行态骨架）
wopal space scan只读扫描空间配置漂移（--json 输出 wopal.space.scan.v1）
wopal space status查看空间 ↔ 所属类型的双向同步状态
wopal space update从所属类型同步到当前空间（默认 dry-run，--confirm 执行）
wopal space contribute将空间变更贡献回所属类型（--confirm 执行）

wopal space init

wopal space init my-api ~/code/my-api
wopal space init my-api --type coding      # 选择类型分支
wopal space init my-api --fork             # 以 fork 模式创建本体 worktree
  • --type：common（默认，映射 main）/ coding / content / finance。
  • 幂等：已存在的目录补齐缺失项，已存在的文件保留原内容。
  • 首次会渲染 AGENTS.md、.gitignore、STRUCTURE.md、REGULATIONS.md、memory/USER.md、memory/MEMORY.md。

本体管理：wopal ontology

在 $WOPAL_HOME/ontologies/<source> 上操作。

命令方向作用
wopal ontology install [url]—安装本体 source（clone 或 fork）
wopal ontology list—列出已安装的本体 source
wopal ontology status—查看各类型与上游的同步状态
wopal ontology update下行从上游同步到本地（top-down，默认 dry-run，--confirm 执行）
wopal ontology reconcile↓选择性 merge，保留 type 专属文件（--confirm）
wopal ontology contribute --type <type>上行从 fork 向 upstream 发 PR（--confirm，支持 --resume / --abort）
wopal ontology promote↑将 type 的通用变更回流到 main（--include/--exclude glob，--confirm）

本体的能力流动：上游 release → 你 update 拉取；你在 fork 上改 → contribute 发 PR 回流；通用能力通过 promote 回到 main。自主发版（release）与更完整的协作能力在持续演进中。

技能管理：wopal skills

管理外部技能（本体内置技能由引擎直接加载，不走这些命令）。

命令作用
wopal skills find搜索外部技能
wopal skills download下载技能到 INBOX/
wopal skills scan扫描技能安全性
wopal skills check检查技能内容
wopal skills install <url|path>安装技能到空间或全局（需先经 INBOX 与扫描）
wopal skills remove移除已安装技能
wopal skills list列出已安装技能
wopal skills merge合并技能到当前空间
wopal skills inbox管理 INBOX/ 暂存区
wopal skills update-scanner更新安全扫描器规则

合法技能必须包含 SKILL.md；远程源安装必须先进入 INBOX/ 并通过安全扫描，锁文件记录来源、hash 与时间戳。

引擎：wopal ellamaka / start / stop / status

wopal ellamaka

命令作用
wopal ellamaka install下载、校验并安装 ellamaka 引擎（默认 latest stable）
wopal ellamaka auth login配置 AI provider 凭证（代理到引擎）
wopal ellamaka auth status查看凭证状态
wopal ellamaka auth logout退出凭证

wopal start / stop / status

日常高频的引擎进程管理：

wopal start                 # 启动引擎并在浏览器打开 Web Workbench
wopal stop                  # 安全终止引擎进程
wopal status                # 报告引擎安装与运行状态

wopal start 选项：

选项说明
--port <n>端口（默认 4096）
--password绑定 0.0.0.0 并启用 LAN 访问（设置访问密码）
--debug [modules] / --trace [modules]调试 / 追踪日志
--no-open只输出 URL，不打开浏览器
--no-space-mode不以 --wopal-space 模式启动

在远端 SSH 会话中 wopal start 会自动只输出 URL，不尝试打开浏览器。

退出码

退出码含义
0成功
1通用错误
2参数错误
其他视命令而定；CLI 使用稳定错误码 + 人类可读描述 + 修复建议