iamb-matrix-cli

Matrix CLI operations for iamb including account registration, token retrieval, and Space management.

SKILL.md

GitHub

iamb Matrix CLI Operations

Description

面向 ulyssa/iamb 的 Matrix 运维技能:补齐 iamb 原生命令之外的账户注册与 token 获取流程,并提供 Space ID 获取与空间关系维护操作。

Activation Keywords

  • iamb
  • matrix cli
  • matrix 注册
  • 用户注册
  • 获取 token
  • access token
  • space id
  • spaces id
  • iamb space

Tools Used

  • exec: 运行 iamb 与 Python 辅助脚本
  • read: 读取 config.toml / session.json / 输出文件
  • write: 生成或更新临时配置、结果文档

Installation

Prerequisites

# 1) 安装 iamb
cargo install --locked iamb

# 2) Python 3.9+
python3 --version

Optional

# 如果你更偏好 requests,可自行安装
uv pip install requests

Usage Patterns

1) 通过 Matrix API 注册用户

python collection/skills/iamb-matrix-cli/scripts/matrix_iamb_helper.py register \
  --homeserver https://matrix.example.com \
  --username alice \
  --password 'StrongPass123!'

2) 获取用户 access token(登录)

python collection/skills/iamb-matrix-cli/scripts/matrix_iamb_helper.py login \
  --homeserver https://matrix.example.com \
  --user '@alice:matrix.example.com' \
  --password 'StrongPass123!'

3) 从 iamb 会话文件提取 token

python collection/skills/iamb-matrix-cli/scripts/matrix_iamb_helper.py extract-token \
  --session-json ~/.local/share/iamb/profiles/<profile>/session.json

4) 获取 Space ID 列表

python collection/skills/iamb-matrix-cli/scripts/matrix_iamb_helper.py space-ids \
  --homeserver https://matrix.example.com \
  --access-token '<TOKEN>'

5) 在 iamb 中查看/维护 Space

:spaces
:room id show
:space child set !room_id:example.com ++suggested
:space child remove

Instructions for Agents

Step 1: 先判断 iamb 原生能力边界

  • iamb 支持登录(password/SSO)与会话恢复。
  • iamb 支持 :spaces、:room id show、:space child set/remove。
  • iamb 不提供显式“注册新用户”命令,应走 Matrix Client-Server API。

Step 2: 处理用户注册

  • 调用 matrix_iamb_helper.py register。
  • 若 homeserver 禁止 m.login.dummy 注册,提示管理员策略限制并转登录流程。

Step 3: 获取 token

优先顺序:

  1. 已登录 iamb:extract-token 读取 session.json。
  2. 未登录:login 调 Matrix API 获取 token。

Step 4: 获取 Space ID

  • 先通过 joined-rooms 获取已加入 room 列表。
  • 对每个 room 调 m.room.create 状态事件。
  • 过滤 type == "m.space" 的 room,输出 Space IDs。

Step 5: 回到 iamb 执行空间操作

  • 用 :spaces 导航。
  • 在目标空间内使用 :space child set/remove 维护子房间。
  • 需要定位当前窗口 room id 时执行 :room id show。

Error Handling

注册失败(401/403)

  • 检查 homeserver 是否允许公开注册。
  • 检查是否需要 CAPTCHA / email / token-based 注册流程。
  • 无法自动化时,提示改为管理员代注册或 web 注册。

token 无效(M_UNKNOWN_TOKEN)

  • 重新登录获取新 token。
  • 检查是否被服务端吊销会话。

Space 查询为空

  • 可能尚未加入任何 space。
  • 先在 iamb 中 :join <space_alias_or_id>,再重新查询。

Limitations

  • 不同 homeserver 的注册策略差异较大,dummy auth 不一定可用。
  • 脚本仅覆盖常见 Matrix v3 流程,不覆盖全部 UIA 交互分支。

Best Practices

  1. 优先从 session.json 读取 token,避免重复登录。
  2. 所有输出尽量使用 JSON,便于后续 agent 自动处理。
  3. 不在日志或聊天中明文回显密码。

Examples

Example: 注册 + 登录 + Space ID

  1. 注册:register
  2. 登录:login
  3. 查询 Space:space-ids
  4. 在 iamb 中执行 :spaces 和 :space child set ...

Resources

Related Skills

  • chat-history-lancedb: 保存本次排障上下文
  • skill-rag-indexer: 将 Matrix 结果索引到可检索知识库
  • skill-extractor: 将重复 CLI 流程沉淀为可复用模式