iamb-matrix-cli
Matrix CLI operations for iamb including account registration, token retrieval, and Space management.
SKILL.mdcollection/skills/other/iamb-matrix-cli/SKILL.md
GitHubiamb 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
优先顺序:
- 已登录 iamb:
extract-token读取session.json。 - 未登录:
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
- 优先从
session.json读取 token,避免重复登录。 - 所有输出尽量使用 JSON,便于后续 agent 自动处理。
- 不在日志或聊天中明文回显密码。
Examples
Example: 注册 + 登录 + Space ID
- 注册:
register - 登录:
login - 查询 Space:
space-ids - 在 iamb 中执行
:spaces和:space child set ...
Resources
- iamb Repo: https://github.com/ulyssa/iamb
- Matrix Client-Server API: https://spec.matrix.org/latest/client-server-api/
- iamb docs: https://iamb.chat
Related Skills
chat-history-lancedb: 保存本次排障上下文skill-rag-indexer: 将 Matrix 结果索引到可检索知识库skill-extractor: 将重复 CLI 流程沉淀为可复用模式