matrix-openapi-skill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Matrix Client-Server API Skill

Matrix客户端-服务器API技能

Use this skill to run Matrix Client-Server operations through

uxc

+ OpenAPI.

Reuse the

uxc

skill for shared execution, auth, and error-handling guidance.

使用此技能可通过

uxc

+ OpenAPI执行Matrix客户端-服务器操作。

复用

uxc

技能以实现共享执行、认证和错误处理指导。

Prerequisites

前提条件

```
uxc
```
is installed and available in
```
PATH
```
.
Network access to your Matrix homeserver's client-server base URL, usually
```
https://<homeserver>/_matrix/client/v3
```
.

Access to the curated OpenAPI schema URL:

https://raw.githubusercontent.com/holon-run/uxc/main/skills/matrix-openapi-skill/references/matrix-client-server.openapi.json

A Matrix access token for the target homeserver.

已安装
```
uxc
```
且其可在
```
PATH
```
中访问。
能够访问Matrix家庭服务器的客户端-服务器基础URL，通常为
```
https://<homeserver>/_matrix/client/v3
```
。

能够访问精心整理的OpenAPI架构URL：

https://raw.githubusercontent.com/holon-run/uxc/main/skills/matrix-openapi-skill/references/matrix-client-server.openapi.json

目标家庭服务器的Matrix访问令牌。

Scope

适用范围

This skill covers a practical request/response Matrix surface:

token owner lookup
joined room discovery
room state lookup
```
/sync
```
polling reads, including daemon-backed poll subscribe
user profile and presence lookup
room message sends

This skill does not cover:

login, SSO, device registration, or generic token acquisition flows
appservice, federation, or bot framework abstractions
webhook or long-running event receiver runtime
full Matrix spec coverage

此技能涵盖Matrix实用的请求/响应场景：

令牌所有者查询
已加入房间发现
房间状态查询
```
/sync
```
轮询读取，包括守护进程支持的轮询订阅
用户资料与在线状态查询
房间消息发送

此技能不涵盖：

登录、SSO、设备注册或通用令牌获取流程
应用服务、联邦或机器人框架抽象
Webhook或长期运行的事件接收器运行时
完整的Matrix规范覆盖

Homeserver Base URL

家庭服务器基础URL

Matrix is homeserver-specific. The endpoint you link must include the Matrix client-server base path:

typical form:
```
https://<homeserver>/_matrix/client/v3
```
example form:
```
https://matrix.org/_matrix/client/v3
```

Do not link only the homeserver origin without

/_matrix/client/v3

Matrix是特定于家庭服务器的。你链接的端点必须包含Matrix客户端-服务器基础路径：

典型格式：
```
https://<homeserver>/_matrix/client/v3
```
示例格式：
```
https://matrix.org/_matrix/client/v3
```

请勿仅链接家庭服务器源而不包含

/_matrix/client/v3

。

Authentication

认证

Matrix Client-Server API uses

Authorization: Bearer <access_token>

Preferred path for OAuth-aware homeservers:

bash

uxc auth oauth start matrix-oauth \
  --endpoint https://matrix.org/_matrix/client/v3 \
  --redirect-uri http://127.0.0.1:8788/callback \
  --client-id <client_id>

uxc auth oauth complete matrix-oauth \
  --session-id <session_id> \
  --authorization-response 'http://127.0.0.1:8788/callback?code=...'

uxc auth binding add \
  --id matrix-oauth \
  --host matrix.org \
  --path-prefix /_matrix/client/v3 \
  --scheme https \
  --credential matrix-oauth \
  --priority 100

Fallback path when you already have an access token:

bash

uxc auth credential set matrix-access \
  --auth-type bearer \
  --secret-env MATRIX_ACCESS_TOKEN

uxc auth binding add \
  --id matrix-access \
  --host matrix.org \
  --path-prefix /_matrix/client/v3 \
  --scheme https \
  --credential matrix-access \
  --priority 100

If your homeserver is not

matrix.org

, replace the host while keeping the same path prefix. Validate the active mapping when auth looks wrong:

bash

uxc auth binding match https://matrix.org/_matrix/client/v3

Notes:

```
uxc auth oauth
```
works only for homeservers that expose Matrix OAuth metadata.
Prefer a loopback redirect URI on an uncommon high port, such as
```
http://127.0.0.1:8788/callback
```
, to avoid conflicts with local services on common ports.
Legacy Matrix login and SSO fallback flows are not covered by this skill yet.

Matrix客户端-服务器API使用

Authorization: Bearer <access_token>

。

支持OAuth的家庭服务器的首选方式：

bash

uxc auth oauth start matrix-oauth \
  --endpoint https://matrix.org/_matrix/client/v3 \
  --redirect-uri http://127.0.0.1:8788/callback \
  --client-id <client_id>

uxc auth oauth complete matrix-oauth \
  --session-id <session_id> \
  --authorization-response 'http://127.0.0.1:8788/callback?code=...'

uxc auth binding add \
  --id matrix-oauth \
  --host matrix.org \
  --path-prefix /_matrix/client/v3 \
  --scheme https \
  --credential matrix-oauth \
  --priority 100

当你已拥有访问令牌时的备用方式：

bash

uxc auth credential set matrix-access \
  --auth-type bearer \
  --secret-env MATRIX_ACCESS_TOKEN

uxc auth binding add \
  --id matrix-access \
  --host matrix.org \
  --path-prefix /_matrix/client/v3 \
  --scheme https \
  --credential matrix-access \
  --priority 100

如果你的家庭服务器不是

matrix.org

，请替换主机名并保持相同的路径前缀。当认证出现问题时，验证当前的映射：

bash

uxc auth binding match https://matrix.org/_matrix/client/v3

注意事项：

```
uxc auth oauth
```
仅适用于暴露Matrix OAuth元数据的家庭服务器。
优先使用非通用高端口的环回重定向URI，例如
```
http://127.0.0.1:8788/callback
```
，以避免与通用端口上的本地服务冲突。
旧版Matrix登录和SSO备用流程尚未被此技能覆盖。

Core Workflow

核心工作流程

Use the fixed link command by default:

```
command -v matrix-openapi-cli
```

If missing, create it:

uxc link matrix-openapi-cli https://matrix.org/_matrix/client/v3 --schema-url https://raw.githubusercontent.com/holon-run/uxc/main/skills/matrix-openapi-skill/references/matrix-client-server.openapi.json

```
matrix-openapi-cli -h
```

Inspect operation schema first:

matrix-openapi-cli get:/account/whoami -h

```
matrix-openapi-cli get:/sync -h
```

matrix-openapi-cli put:/rooms/{roomId}/send/{eventType}/{txnId} -h

Prefer read validation before writes:

```
matrix-openapi-cli get:/account/whoami
```
```
matrix-openapi-cli get:/joined_rooms
```

matrix-openapi-cli get:/rooms/{roomId}/state roomId=!abc123:example.org

Execute with key/value or positional JSON:

key/value:

matrix-openapi-cli get:/sync timeout=30000 filter={"room":{"timeline":{"limit":10}}}

positional JSON:

matrix-openapi-cli put:/rooms/{roomId}/send/{eventType}/{txnId} '{"roomId":"!abc123:example.org","eventType":"m.room.message","txnId":"uxc-001","msgtype":"m.text","body":"Hello from UXC"}'

For background

/sync

polling, call

uxc subscribe start

directly against the homeserver base URL:

uxc subscribe start https://matrix.org/_matrix/client/v3 get:/sync --auth matrix-oauth --mode poll --poll-config '{"interval_secs":2,"extract_items_pointer":"/rooms/join/!abc123:example.org/timeline/events","missing_extract_items_pointer_as_empty":true,"request_cursor_arg":"since","response_cursor_pointer":"/next_batch","checkpoint_strategy":{"type":"cursor_only"}}' --sink file:$HOME/.uxc/subscriptions/matrix-sync.ndjson timeout=1000 'filter={"room":{"rooms":["!abc123:example.org"],"timeline":{"limit":5}}}'

默认使用固定链接命令：

```
command -v matrix-openapi-cli
```

如果缺失，创建它：

uxc link matrix-openapi-cli https://matrix.org/_matrix/client/v3 --schema-url https://raw.githubusercontent.com/holon-run/uxc/main/skills/matrix-openapi-skill/references/matrix-client-server.openapi.json

```
matrix-openapi-cli -h
```

先检查操作架构：

matrix-openapi-cli get:/account/whoami -h

```
matrix-openapi-cli get:/sync -h
```

matrix-openapi-cli put:/rooms/{roomId}/send/{eventType}/{txnId} -h

优先在写入前进行读取验证：

```
matrix-openapi-cli get:/account/whoami
```
```
matrix-openapi-cli get:/joined_rooms
```

matrix-openapi-cli get:/rooms/{roomId}/state roomId=!abc123:example.org

使用键值对或位置JSON执行：

键值对：

matrix-openapi-cli get:/sync timeout=30000 filter={"room":{"timeline":{"limit":10}}}

位置JSON：

matrix-openapi-cli put:/rooms/{roomId}/send/{eventType}/{txnId} '{"roomId":"!abc123:example.org","eventType":"m.room.message","txnId":"uxc-001","msgtype":"m.text","body":"Hello from UXC"}'

对于后台

/sync

轮询，直接针对家庭服务器基础URL调用

uxc subscribe start

：

uxc subscribe start https://matrix.org/_matrix/client/v3 get:/sync --auth matrix-oauth --mode poll --poll-config '{"interval_secs":2,"extract_items_pointer":"/rooms/join/!abc123:example.org/timeline/events","missing_extract_items_pointer_as_empty":true,"request_cursor_arg":"since","response_cursor_pointer":"/next_batch","checkpoint_strategy":{"type":"cursor_only"}}' --sink file:$HOME/.uxc/subscriptions/matrix-sync.ndjson timeout=1000 'filter={"room":{"rooms":["!abc123:example.org"],"timeline":{"limit":5}}}'

Operation Groups

操作分组

Session / Discovery

会话/发现

```
get:/account/whoami
```
```
get:/joined_rooms
```
```
get:/sync
```

```
get:/account/whoami
```
```
get:/joined_rooms
```
```
get:/sync
```

Room Reads

房间读取

```
get:/rooms/{roomId}/state
```

get:/rooms/{roomId}/state/{eventType}/{stateKey}

```
get:/rooms/{roomId}/state
```

get:/rooms/{roomId}/state/{eventType}/{stateKey}

User Reads

用户读取

```
get:/profile/{userId}
```
```
get:/presence/{userId}/status
```

```
get:/profile/{userId}
```
```
get:/presence/{userId}/status
```

Messaging

消息发送

put:/rooms/{roomId}/send/{eventType}/{txnId}

put:/rooms/{roomId}/send/{eventType}/{txnId}

Guardrails

防护机制

Keep automation on the JSON output envelope; do not use
```
--text
```
.
Parse stable fields first:
```
ok
```
,
```
kind
```
,
```
protocol
```
,
```
data
```
,
```
error
```
.
```
get:/sync
```
works both as a normal polling/read call and as a validated daemon-backed poll subscription when invoked through
```
uxc subscribe start
```
.
For room-scoped
```
/sync
```
subscriptions, set
```
missing_extract_items_pointer_as_empty=true
```
so sparse responses without new room timeline events are treated as an empty batch instead of a fatal error.
```
put:/rooms/{roomId}/send/{eventType}/{txnId}
```
is high-risk and should default to
```
m.room.message
```
text sends unless the user explicitly asks for another event type.
Reuse a unique
```
txnId
```
per send attempt to avoid accidental duplicates.
Many homeservers restrict presence visibility and room state/event access based on membership and server policy; auth success does not imply every room or profile read will succeed.

matrix-openapi-cli <operation> ...

is equivalent to

uxc <homeserver_client_base> --schema-url <matrix_openapi_schema> <operation> ...

自动化操作基于JSON输出包；请勿使用
```
--text
```
。
优先解析稳定字段：
```
ok
```
、
```
kind
```
、
```
protocol
```
、
```
data
```
、
```
error
```
。
```
get:/sync
```
既可以作为普通轮询/读取调用，也可以在通过
```
uxc subscribe start
```
调用时作为经过验证的守护进程支持的轮询订阅。
对于房间范围的
```
/sync
```
订阅，设置
```
missing_extract_items_pointer_as_empty=true
```
，这样没有新房间时间线事件的稀疏响应会被视为空批次而非致命错误。
```
put:/rooms/{roomId}/send/{eventType}/{txnId}
```
属于高风险操作，默认应使用
```
m.room.message
```
文本发送，除非用户明确要求其他事件类型。
每次发送尝试使用唯一的
```
txnId
```
以避免意外重复。
许多家庭服务器会根据成员身份和服务器策略限制在线状态可见性以及房间状态/事件访问权限；认证成功并不意味着所有房间或资料读取都会成功。

matrix-openapi-cli <operation> ...

等同于

uxc <homeserver_client_base> --schema-url <matrix_openapi_schema> <operation> ...

。

References

参考资料

Usage patterns:
```
references/usage-patterns.md
```

Curated OpenAPI schema:

references/matrix-client-server.openapi.json

Matrix Client-Server API: https://spec.matrix.org/latest/client-server-api/
Matrix spec source: https://github.com/matrix-org/matrix-spec/tree/main/data/api/client-server

使用模式：
```
references/usage-patterns.md
```

精心整理的OpenAPI架构：

references/matrix-client-server.openapi.json

Matrix客户端-服务器API：https://spec.matrix.org/latest/client-server-api/
Matrix规范源码：https://github.com/matrix-org/matrix-spec/tree/main/data/api/client-server