grix-connector 3.1.13 → 3.1.15

package/dist/default-skills/grix-group/SKILL.md

@@ -1,35 +1,35 @@
----
-name: grix-group
-description: Use the typed `grix_group` tool for Grix group lifecycle and membership operations. Trigger when users ask to create, inspect, leave, update, or dissolve groups, or when these operations fail with scope or permission errors.
-trigger: 当用户要创建、查看、退出、更新或解散群组,或群成员/禁言权限相关操作时
----
-
-# Grix Group
-
-Use the `grix_group` tool for Grix group lifecycle and membership management.
-
-## Tool contract
-
-Call `grix_group` with one `action`:
-
-- `create` — create a group. Requires `name`; optionally seed members with
-  `memberIds` + matching `memberTypes` (1=user, 2=agent).
-- `detail` — get group details. Requires `sessionId`.
-- `leave` — leave the group. Requires `sessionId`.
-- `dissolve` — dissolve the group (owner/admin only). Requires `sessionId`.
-- `add_members` / `remove_members` — requires `sessionId`, `memberIds`, and
-  `memberTypes` aligned by index.
-- `update_member_role` — requires `sessionId`, `memberId`, `role` (1=admin,
-  2=member).
-- `update_all_members_muted` — requires `sessionId`, `allMembersMuted`.
-- `update_member_speaking` — requires `sessionId`, `memberId`, `isSpeakMuted`,
-  and optionally `canSpeakWhenAllMuted`.
-
-## Rules
-
-1. `memberIds` and `memberTypes` are parallel arrays — keep them the same length
-   and order.
-2. Any action except `create` needs the target group's `sessionId`; resolve it
-   with `grix_query` (`session_search`) first if unknown.
-3. Scope or permission errors usually mean the current agent is not an admin of
-   that group — surface the exact error and required role, don't retry blindly.
+---
+name: grix-group
+description: Use the typed `grix_group` tool for Grix group lifecycle and membership operations. Trigger when users ask to create, inspect, leave, update, or dissolve groups, or when these operations fail with scope or permission errors.
+trigger: 当用户要创建、查看、退出、更新或解散群组,或群成员/禁言权限相关操作时
+---
+
+# Grix Group
+
+Use the `grix_group` tool for Grix group lifecycle and membership management.
+
+## Tool contract
+
+Call `grix_group` with one `action`:
+
+- `create` — create a group. Requires `name`; optionally seed members with
+  `memberIds` + matching `memberTypes` (1=user, 2=agent).
+- `detail` — get group details. Requires `sessionId`.
+- `leave` — leave the group. Requires `sessionId`.
+- `dissolve` — dissolve the group (owner/admin only). Requires `sessionId`.
+- `add_members` / `remove_members` — requires `sessionId`, `memberIds`, and
+  `memberTypes` aligned by index.
+- `update_member_role` — requires `sessionId`, `memberId`, `role` (1=admin,
+  2=member).
+- `update_all_members_muted` — requires `sessionId`, `allMembersMuted`.
+- `update_member_speaking` — requires `sessionId`, `memberId`, `isSpeakMuted`,
+  and optionally `canSpeakWhenAllMuted`.
+
+## Rules
+
+1. `memberIds` and `memberTypes` are parallel arrays — keep them the same length
+   and order.
+2. Any action except `create` needs the target group's `sessionId`; resolve it
+   with `grix_query` (`session_search`) first if unknown.
+3. Scope or permission errors usually mean the current agent is not an admin of
+   that group — surface the exact error and required role, don't retry blindly.

package/dist/default-skills/grix-owner-relay/SKILL.md

@@ -1,66 +1,66 @@
----
-name: grix-owner-relay
-description: Act on the owner's behalf in a session — send a message as the owner (`grix_session_send`), or call the owner into the current session for a voice talk/approval (`grix_call_owner`). Trigger when the user asks to speak as the owner in a session, or when you need to reach the owner to discuss or get approval.
-trigger: 当需要以 owner 身份在某会话发言、或把 owner 叫进当前会话语音沟通/审批时
----
-
-# Grix Owner Relay
-
-Interact with sessions on the owner's behalf, or pull the owner in.
-
-## Speak as the owner — `grix_session_send`
-
-Send a message into a session **as the owner** — it shows up as if the owner
-themselves sent it, **not** as you (the agent).
-
-- `session_id` (required) — target session ID.
-- `content` (required) — message text to send as the owner (max 10000 chars).
-
-### When to use it
-
-Only to relay on the owner's behalf into one of the owner's **other** sessions
-that you are **not** a participant in. Typical case: you were dispatched to work
-somewhere and need to drop a note to the owner (or to others) in a *different*
-session of theirs.
-
-### Before you call it, make sure
-
-1. You genuinely want to **impersonate the owner**, not speak as yourself.
-2. The owner is a member of the target session (otherwise it fails on scope —
-   surface the error, don't retry blindly).
-3. The target session is **not** one you are conversing in / a member of.
-
-### Never use it for
-
-- ❌ **Sending your own reply in the conversation you are currently in.** Reply
-  normally instead (or use `grix_message_send` to send as yourself). Using
-  `grix_session_send` here makes *your* answer appear as the *owner's* words —
-  i.e. the agent's text shows up as the user's message. This is wrong and
-  confusing.
-- ❌ **Any session you (the agent) are a member of.** The backend rejects this,
-  precisely to stop the agent from impersonating the owner in its own
-  conversation.
-- ❌ As a generic substitute for sending a message as yourself — use
-  `grix_message_send` for that.
-
-To send as yourself (the agent), use the `message-send` skill
-(`grix_message_send`).
-
-## Call the owner in — `grix_call_owner`
-
-Bring the owner into a session for a voice conversation — use this when you need
-to discuss something or get an approval/review during your work. It sends the
-owner an offline notification; tapping it lands them in the conversation and
-auto-starts a voice-brain call.
-
-- `session_id` (required) — the session to call the owner into.
-
-## Rules
-
-1. `grix_session_send` only works when the owner is a member of the target
-   session **and you (the agent) are not** — sending into a session you belong
-   to is rejected (it would impersonate the owner in your own conversation).
-   On failure, surface the error; don't retry blindly.
-2. `grix_call_owner` requires the owner to have configured a voice brain and is
-   rate-limited per session. Use it only when you genuinely need the owner, not
-   as a routine notification.
+---
+name: grix-owner-relay
+description: Act on the owner's behalf in a session — send a message as the owner (`grix_session_send`), or call the owner into the current session for a voice talk/approval (`grix_call_owner`). Trigger when the user asks to speak as the owner in a session, or when you need to reach the owner to discuss or get approval.
+trigger: 当需要以 owner 身份在某会话发言、或把 owner 叫进当前会话语音沟通/审批时
+---
+
+# Grix Owner Relay
+
+Interact with sessions on the owner's behalf, or pull the owner in.
+
+## Speak as the owner — `grix_session_send`
+
+Send a message into a session **as the owner** — it shows up as if the owner
+themselves sent it, **not** as you (the agent).
+
+- `session_id` (required) — target session ID.
+- `content` (required) — message text to send as the owner (max 10000 chars).
+
+### When to use it
+
+Only to relay on the owner's behalf into one of the owner's **other** sessions
+that you are **not** a participant in. Typical case: you were dispatched to work
+somewhere and need to drop a note to the owner (or to others) in a *different*
+session of theirs.
+
+### Before you call it, make sure
+
+1. You genuinely want to **impersonate the owner**, not speak as yourself.
+2. The owner is a member of the target session (otherwise it fails on scope —
+   surface the error, don't retry blindly).
+3. The target session is **not** one you are conversing in / a member of.
+
+### Never use it for
+
+- ❌ **Sending your own reply in the conversation you are currently in.** Reply
+  normally instead (or use `grix_message_send` to send as yourself). Using
+  `grix_session_send` here makes *your* answer appear as the *owner's* words —
+  i.e. the agent's text shows up as the user's message. This is wrong and
+  confusing.
+- ❌ **Any session you (the agent) are a member of.** The backend rejects this,
+  precisely to stop the agent from impersonating the owner in its own
+  conversation.
+- ❌ As a generic substitute for sending a message as yourself — use
+  `grix_message_send` for that.
+
+To send as yourself (the agent), use the `message-send` skill
+(`grix_message_send`).
+
+## Call the owner in — `grix_call_owner`
+
+Bring the owner into a session for a voice conversation — use this when you need
+to discuss something or get an approval/review during your work. It sends the
+owner an offline notification; tapping it lands them in the conversation and
+auto-starts a voice-brain call.
+
+- `session_id` (required) — the session to call the owner into.
+
+## Rules
+
+1. `grix_session_send` only works when the owner is a member of the target
+   session **and you (the agent) are not** — sending into a session you belong
+   to is rejected (it would impersonate the owner in your own conversation).
+   On failure, surface the error; don't retry blindly.
+2. `grix_call_owner` requires the owner to have configured a voice brain and is
+   rate-limited per session. Use it only when you genuinely need the owner, not
+   as a routine notification.

package/dist/default-skills/grix-query/SKILL.md

@@ -1,38 +1,38 @@
----
-name: grix-query
-description: Use the typed `grix_query` tool for Grix contact lookup, keyword search, session search, and session message history lookup. Trigger when users ask to find contacts, search conversations, list visible sessions, or inspect recent messages in a known session.
-trigger: 当用户要查找联系人、搜索会话、列出可见会话、或查看某个已知会话的历史消息时
----
-
-# Grix Query
-
-Use the `grix_query` tool for read-only Grix lookup. This skill only queries
-existing contacts, sessions, and raw session messages — it never sends or
-changes anything.
-
-## Tool contract
-
-Always call the `grix_query` tool with one `action`:
-
-- `contact_search` — find contacts. Use exactly one mode: exact lookup with
-  `id`, keyword search with `keyword`, or list-all with neither.
-- `session_search` — find sessions. Same three modes as `contact_search`.
-- `message_history` — read recent messages in a session. Requires `sessionId`;
-  page backwards with `beforeId`.
-- `message_search` — keyword search inside a session. Requires `sessionId` and
-  `keyword`.
-
-Other parameters: `limit` (1–100), `offset`.
-
-## Rules
-
-1. Parse the request into exactly one action before calling.
-2. If both `id` and `keyword` are given, the backend prioritizes `id`; do not
-   send both unless you explicitly want exact-match behavior.
-3. For message history or in-session search when no `sessionId` is known, first
-   locate the session via `session_search`, or ask the user for a precise target.
-4. When a result is paginated and `has_more` is true, keep paging only when the
-   user asked for everything, the target is still unresolved, or one page is
-   clearly insufficient.
-5. On scope/auth/parameter errors, report the exact failure and the fix; do not
-   silently retry with guessed parameters.
+---
+name: grix-query
+description: Use the typed `grix_query` tool for Grix contact lookup, keyword search, session search, and session message history lookup. Trigger when users ask to find contacts, search conversations, list visible sessions, or inspect recent messages in a known session.
+trigger: 当用户要查找联系人、搜索会话、列出可见会话、或查看某个已知会话的历史消息时
+---
+
+# Grix Query
+
+Use the `grix_query` tool for read-only Grix lookup. This skill only queries
+existing contacts, sessions, and raw session messages — it never sends or
+changes anything.
+
+## Tool contract
+
+Always call the `grix_query` tool with one `action`:
+
+- `contact_search` — find contacts. Use exactly one mode: exact lookup with
+  `id`, keyword search with `keyword`, or list-all with neither.
+- `session_search` — find sessions. Same three modes as `contact_search`.
+- `message_history` — read recent messages in a session. Requires `sessionId`;
+  page backwards with `beforeId`.
+- `message_search` — keyword search inside a session. Requires `sessionId` and
+  `keyword`.
+
+Other parameters: `limit` (1–100), `offset`.
+
+## Rules
+
+1. Parse the request into exactly one action before calling.
+2. If both `id` and `keyword` are given, the backend prioritizes `id`; do not
+   send both unless you explicitly want exact-match behavior.
+3. For message history or in-session search when no `sessionId` is known, first
+   locate the session via `session_search`, or ask the user for a precise target.
+4. When a result is paginated and `has_more` is true, keep paging only when the
+   user asked for everything, the target is still unresolved, or one page is
+   clearly insufficient.
+5. On scope/auth/parameter errors, report the exact failure and the fix; do not
+   silently retry with guessed parameters.

package/dist/default-skills/message-send/SKILL.md

@@ -1,36 +1,36 @@
----
-name: message-send
-description: Send a message into a specific Grix session by session ID, including cross-session and proactive sends. For replying to the current event use the reply/complete tools instead. Trigger words: send DM, DM, send message, notify, message another session.
-trigger: 当用户要主动给某个指定会话发消息、跨会话发送、或通知另一个会话时
----
-
-# Message Send
-
-Use the `grix_message_send` tool to deliver a message into a specific Grix
-session identified by its `sessionId`.
-
-## When to use which tool
-
-- **Replying to the current event** (the one you are handling right now): use
-  the `reply` / `grix_reply` tool and finish with `complete`. Do NOT use
-  `grix_message_send` for this — it is for other sessions.
-- **Sending to another session, or proactively starting one**: use
-  `grix_message_send` with that session's `sessionId`.
-
-## Tool contract
-
-Call `grix_message_send`:
-
-- `sessionId` (required) — the exact target session ID.
-- `content` (required) — the message text (max 10000 chars).
-- `msgType` (optional) — message type, default 1 (text).
-- `quotedMessageId` (optional) — message ID to quote/reply to.
-- `threadId` (optional) — thread ID for a threaded reply.
-
-## Rules
-
-1. You must have an exact `sessionId`. If you only have a name or keyword,
-   resolve it first with `grix_query` (`session_search` / `contact_search`).
-2. Never guess a `sessionId`. If it cannot be resolved, ask the user.
-3. Sending as yourself (the agent). To speak on the owner's behalf in a session
-   the owner belongs to, use the `grix-owner-relay` skill (`grix_session_send`).
+---
+name: message-send
+description: Send a message into a specific Grix session by session ID, including cross-session and proactive sends. For replying to the current event use the reply/complete tools instead. Trigger words: send DM, DM, send message, notify, message another session.
+trigger: 当用户要主动给某个指定会话发消息、跨会话发送、或通知另一个会话时
+---
+
+# Message Send
+
+Use the `grix_message_send` tool to deliver a message into a specific Grix
+session identified by its `sessionId`.
+
+## When to use which tool
+
+- **Replying to the current event** (the one you are handling right now): use
+  the `reply` / `grix_reply` tool and finish with `complete`. Do NOT use
+  `grix_message_send` for this — it is for other sessions.
+- **Sending to another session, or proactively starting one**: use
+  `grix_message_send` with that session's `sessionId`.
+
+## Tool contract
+
+Call `grix_message_send`:
+
+- `sessionId` (required) — the exact target session ID.
+- `content` (required) — the message text (max 10000 chars).
+- `msgType` (optional) — message type, default 1 (text).
+- `quotedMessageId` (optional) — message ID to quote/reply to.
+- `threadId` (optional) — thread ID for a threaded reply.
+
+## Rules
+
+1. You must have an exact `sessionId`. If you only have a name or keyword,
+   resolve it first with `grix_query` (`session_search` / `contact_search`).
+2. Never guess a `sessionId`. If it cannot be resolved, ask the user.
+3. Sending as yourself (the agent). To speak on the owner's behalf in a session
+   the owner belongs to, use the `grix-owner-relay` skill (`grix_session_send`).

package/dist/default-skills/message-unsend/SKILL.md

@@ -1,27 +1,27 @@
----
-name: message-unsend
-description: Silently recall/unsend an already-sent message in a Grix session. After execution, end immediately without replying any confirmation text. Trigger words: recall, unsend, delete message, withdraw message.
-trigger: 当用户要撤回、收回、删除一条已经发出的消息时
----
-
-# Message Unsend
-
-Use the `grix_message_unsend` tool to recall a message that was already sent.
-
-## Tool contract
-
-Call `grix_message_unsend`:
-
-- `sessionId` (required) — the session the message lives in.
-- `msgId` (required) — the ID of the message to recall.
-
-## Rules
-
-1. You need both the `sessionId` and the exact `msgId`. If the `msgId` is
-   unknown, find it first with `grix_query` (`message_history` /
-   `message_search`).
-2. This is a silent operation: after a successful recall, end immediately — do
-   not send any confirmation message back to the chat.
-3. Only recall messages that were actually sent; recalling someone else's
-   message will fail on scope/permission — surface that error rather than
-   retrying.
+---
+name: message-unsend
+description: Silently recall/unsend an already-sent message in a Grix session. After execution, end immediately without replying any confirmation text. Trigger words: recall, unsend, delete message, withdraw message.
+trigger: 当用户要撤回、收回、删除一条已经发出的消息时
+---
+
+# Message Unsend
+
+Use the `grix_message_unsend` tool to recall a message that was already sent.
+
+## Tool contract
+
+Call `grix_message_unsend`:
+
+- `sessionId` (required) — the session the message lives in.
+- `msgId` (required) — the ID of the message to recall.
+
+## Rules
+
+1. You need both the `sessionId` and the exact `msgId`. If the `msgId` is
+   unknown, find it first with `grix_query` (`message_history` /
+   `message_search`).
+2. This is a silent operation: after a successful recall, end immediately — do
+   not send any confirmation message back to the chat.
+3. Only recall messages that were actually sent; recalling someone else's
+   message will fail on scope/permission — surface that error rather than
+   retrying.

package/dist/default-skills/tailnet-file-share/SKILL.md

@@ -1,65 +1,65 @@
----
-name: tailnet-file-share
-description: 将本地文件转为 tailnet 链接，图片自动内嵌预览，其他文件给下载链接
-trigger: 当用户要求查看、发送、分享、下载、导出本机上的任何文件时
----
-
-当用户要查看或获取本机上的文件时（图片、日志、报告、构建产物、导出数据等），你必须：
-
-1. 调用 grix_file_link 工具，传入文件的绝对路径
-2. 将工具返回的 `markdown` 字段原样写入你的回复，不要修改
-   - 图片文件（jpg/png/gif/webp/svg 等）：工具返回 `![文件名](url)`，在聊天中直接渲染为图片预览
-   - 其他文件：工具返回 `[文件名](url)`，用户点击即可下载
-3. 不要输出原始文件路径，不要尝试粘贴或转述文件内容
-4. 链接只绑本机 tailnet 内网地址、外网访问不到，用户随时点开回看都可以，正常情况下不需要关心也不要提任何有效期问题，直接把链接发给用户即可
-
-## HTTPS 与首次安装信任证书
-
-下载链接是 HTTPS（`https://…`），由本机内置的一个 10 年有效期自签 CA 现签发。
-工具结果里还会返回 `ca_install_url` —— 这是根 CA 证书的安装链接。
-
-- **第一次给某个用户发文件链接时**（或用户反馈"链接打不开 / 证书不受信任 / 不安全"时），
-  把 `ca_install_url` 作为"安装信任证书"链接一并发给他，并附上下面的安装步骤。
-- 用户在**每台设备上只需安装一次**，之后 10 年内这台机器发出的所有下载链接都不再有任何警告，
-  tailnet IP 变了也不用重装。
-
-发给用户的安装引导（按其设备选其一）：
-
-- **iPhone / iPad**：用 Safari 打开 `ca_install_url`，会直接弹出"此网站正尝试下载一个描述文件" → 允许 →
-  到「设置」顶部出现"已下载描述文件"，点进去安装 →
-  再到「设置 → 通用 → 关于本机 → 证书信任设置」，把该证书开关打开（开启完全信任）。这一步必须做，否则系统仍不信任。
-  （iOS 必须用 Safari 打开，其他浏览器不会触发描述文件安装。服务端已按设备自动返回 .mobileconfig，无需手动加参数。）
-- **Mac**：点链接下载 `.crt` → 双击用「钥匙串访问」打开 → 找到该证书 → 双击 →「信任」展开 →「使用此证书时」选"始终信任"。
-- **Android**：点 `ca_install_url` 下载 `.crt` →「设置 → 安全 → 加密与凭据 → 安装证书 → CA 证书」选择刚下载的文件安装
-  （新版安卓不支持浏览器内一键安装，必须走系统设置这一步）。
-- **Windows**：双击 `.crt` →「安装证书」→ 选存储位置 →「将所有证书放入下列存储」→ 选"受信任的根证书颁发机构"。
-
-如果 grix_file_link 调用失败（如未连接 Tailscale），告诉用户文件的本地路径，让他们自行获取。
-
-## 适用范围（重要）：这套证书只管 grix_file_link 自己的服务
-
-上面这张内置 CA 和它签发的证书，**只让 grix_file_link 起的下载服务（本机 tailnet 地址）被设备信任**。它不负责、也解决不了用户自己另起的其它服务。
-
-当用户在 tailnet 上**自行启动了别的 HTTPS 服务**（自建网站 / API / 媒体服务等），用浏览器打开报证书错误时，要分清这是另一回事：
-
-- 设备只信任「它亲自装过的那张 CA 签出来的证书」。自建服务用的是它自己的 CA（如 mkcert），设备没装过，所以报 `不受信任 / 冒充 / NET::ERR_CERT_AUTHORITY_INVALID`——这跟有没有装 Grix 的 CA 无关。
-- 想让自建服务也被信任，只有两条路：
-  1. 让该服务改用一张设备已信任的 CA 来签证书，并且叶子证书有效期 **≤ 398 天**（否则即使信任了 CA，仍会报 `NET::ERR_CERT_VALIDITY_TOO_LONG`）；
-  2. 或者干脆别让用户开自己的 HTTPS，把要分享的文件改走 grix_file_link，由本机内置服务发出来，自动被信任、有效期也合规。
-- 注意：Grix 内置 CA 的**私钥只留在跑连接器的这台机器上、不对外发**（`ca_install_url` 只给公钥证书，不给私钥）。因此只有**与连接器同一台机器**上的服务能借这张 CA 来签证书；其它机器上的服务必须自带 CA，并在每台设备各装一次。
-
-简而言之：能用 grix_file_link 发的就用它发，最省事；自建服务的证书信任问题不在本技能职责内，需在那个服务侧自行解决。
-
-## 两条信任路：Grix app 内 vs 系统浏览器（排障先分清）
-
-同一个链接，在 **Grix app 里打开** 和在 **系统浏览器（Safari / Chrome）里打开**，走的是两套完全独立的证书信任机制，报错和解法都不同。用户反馈"打不开 / 证书报错"时，先问清他是在哪条路上看的。
-
-- **Grix app 内**（图片预览、应用内下载等走 app 自带的网络栈）：app 内置了一条信任规则——只要链接是 tailnet 地址（`100.64.0.0/10` 段）、且证书签发者名字里含 `Grix Tailnet Local CA`，就直接放行，**用户不需要在设备上安装任何证书**。所以 grix_file_link 的链接在 app 里通常开箱即用、零安装。app 内若仍打不开，多半是没走 tailnet IP、或证书签发者名字不符，而不是"没装证书"。
-- **系统浏览器（Safari / Chrome）**：走的是手机 / 电脑的系统信任库，跟 app 那条规则毫无关系。必须按上面《HTTPS 与首次安装信任证书》把根 CA 装好（iOS 装 .mobileconfig 并开完全信任，安卓走系统设置，等等）。用户截图里出现的 `NET::ERR_CERT_AUTHORITY_INVALID`、`冒充`、`NET::ERR_CERT_VALIDITY_TOO_LONG`，几乎都是系统浏览器这条路，引导他装 CA 即可。
-
-对**自建服务**同理，按用户要在哪看来定：
-
-- 只需要在 **Grix app 内**展示：自建服务无需向用户分发私钥、也无需装任何证书——只要①服务挂在 tailnet IP 上、②把它那张 CA 的签发者名字带上 `Grix Tailnet Local CA`，app 就会信任。
-- 需要在 **系统浏览器** 里打开：app 那条规则不起作用，仍需在每台设备装上该服务自己的 CA（见上一节《适用范围》）。
-
-注意：app 内这条是**按签发者名字字符串匹配**，不是按某把 CA 的公钥指纹绑定。它仅作为私有 tailnet 内的便利取舍，**不是强安全边界**——同一 tailnet 内任何人只要把 CA 命名成相同前缀就会被 app 信任。不要据此把它当作可对抗攻击者的信任根。
+---
+name: tailnet-file-share
+description: 将本地文件转为 tailnet 链接，图片自动内嵌预览，其他文件给下载链接
+trigger: 当用户要求查看、发送、分享、下载、导出本机上的任何文件时
+---
+
+当用户要查看或获取本机上的文件时（图片、日志、报告、构建产物、导出数据等），你必须：
+
+1. 调用 grix_file_link 工具，传入文件的绝对路径
+2. 将工具返回的 `markdown` 字段原样写入你的回复，不要修改
+   - 图片文件（jpg/png/gif/webp/svg 等）：工具返回 `![文件名](url)`，在聊天中直接渲染为图片预览
+   - 其他文件：工具返回 `[文件名](url)`，用户点击即可下载
+3. 不要输出原始文件路径，不要尝试粘贴或转述文件内容
+4. 链接只绑本机 tailnet 内网地址、外网访问不到，用户随时点开回看都可以，正常情况下不需要关心也不要提任何有效期问题，直接把链接发给用户即可
+
+## HTTPS 与首次安装信任证书
+
+下载链接是 HTTPS（`https://…`），由本机内置的一个 10 年有效期自签 CA 现签发。
+工具结果里还会返回 `ca_install_url` —— 这是根 CA 证书的安装链接。
+
+- **第一次给某个用户发文件链接时**（或用户反馈"链接打不开 / 证书不受信任 / 不安全"时），
+  把 `ca_install_url` 作为"安装信任证书"链接一并发给他，并附上下面的安装步骤。
+- 用户在**每台设备上只需安装一次**，之后 10 年内这台机器发出的所有下载链接都不再有任何警告，
+  tailnet IP 变了也不用重装。
+
+发给用户的安装引导（按其设备选其一）：
+
+- **iPhone / iPad**：用 Safari 打开 `ca_install_url`，会直接弹出"此网站正尝试下载一个描述文件" → 允许 →
+  到「设置」顶部出现"已下载描述文件"，点进去安装 →
+  再到「设置 → 通用 → 关于本机 → 证书信任设置」，把该证书开关打开（开启完全信任）。这一步必须做，否则系统仍不信任。
+  （iOS 必须用 Safari 打开，其他浏览器不会触发描述文件安装。服务端已按设备自动返回 .mobileconfig，无需手动加参数。）
+- **Mac**：点链接下载 `.crt` → 双击用「钥匙串访问」打开 → 找到该证书 → 双击 →「信任」展开 →「使用此证书时」选"始终信任"。
+- **Android**：点 `ca_install_url` 下载 `.crt` →「设置 → 安全 → 加密与凭据 → 安装证书 → CA 证书」选择刚下载的文件安装
+  （新版安卓不支持浏览器内一键安装，必须走系统设置这一步）。
+- **Windows**：双击 `.crt` →「安装证书」→ 选存储位置 →「将所有证书放入下列存储」→ 选"受信任的根证书颁发机构"。
+
+如果 grix_file_link 调用失败（如未连接 Tailscale），告诉用户文件的本地路径，让他们自行获取。
+
+## 适用范围（重要）：这套证书只管 grix_file_link 自己的服务
+
+上面这张内置 CA 和它签发的证书，**只让 grix_file_link 起的下载服务（本机 tailnet 地址）被设备信任**。它不负责、也解决不了用户自己另起的其它服务。
+
+当用户在 tailnet 上**自行启动了别的 HTTPS 服务**（自建网站 / API / 媒体服务等），用浏览器打开报证书错误时，要分清这是另一回事：
+
+- 设备只信任「它亲自装过的那张 CA 签出来的证书」。自建服务用的是它自己的 CA（如 mkcert），设备没装过，所以报 `不受信任 / 冒充 / NET::ERR_CERT_AUTHORITY_INVALID`——这跟有没有装 Grix 的 CA 无关。
+- 想让自建服务也被信任，只有两条路：
+  1. 让该服务改用一张设备已信任的 CA 来签证书，并且叶子证书有效期 **≤ 398 天**（否则即使信任了 CA，仍会报 `NET::ERR_CERT_VALIDITY_TOO_LONG`）；
+  2. 或者干脆别让用户开自己的 HTTPS，把要分享的文件改走 grix_file_link，由本机内置服务发出来，自动被信任、有效期也合规。
+- 注意：Grix 内置 CA 的**私钥只留在跑连接器的这台机器上、不对外发**（`ca_install_url` 只给公钥证书，不给私钥）。因此只有**与连接器同一台机器**上的服务能借这张 CA 来签证书；其它机器上的服务必须自带 CA，并在每台设备各装一次。
+
+简而言之：能用 grix_file_link 发的就用它发，最省事；自建服务的证书信任问题不在本技能职责内，需在那个服务侧自行解决。
+
+## 两条信任路：Grix app 内 vs 系统浏览器（排障先分清）
+
+同一个链接，在 **Grix app 里打开** 和在 **系统浏览器（Safari / Chrome）里打开**，走的是两套完全独立的证书信任机制，报错和解法都不同。用户反馈"打不开 / 证书报错"时，先问清他是在哪条路上看的。
+
+- **Grix app 内**（图片预览、应用内下载等走 app 自带的网络栈）：app 内置了一条信任规则——只要链接是 tailnet 地址（`100.64.0.0/10` 段）、且证书签发者名字里含 `Grix Tailnet Local CA`，就直接放行，**用户不需要在设备上安装任何证书**。所以 grix_file_link 的链接在 app 里通常开箱即用、零安装。app 内若仍打不开，多半是没走 tailnet IP、或证书签发者名字不符，而不是"没装证书"。
+- **系统浏览器（Safari / Chrome）**：走的是手机 / 电脑的系统信任库，跟 app 那条规则毫无关系。必须按上面《HTTPS 与首次安装信任证书》把根 CA 装好（iOS 装 .mobileconfig 并开完全信任，安卓走系统设置，等等）。用户截图里出现的 `NET::ERR_CERT_AUTHORITY_INVALID`、`冒充`、`NET::ERR_CERT_VALIDITY_TOO_LONG`，几乎都是系统浏览器这条路，引导他装 CA 即可。
+
+对**自建服务**同理，按用户要在哪看来定：
+
+- 只需要在 **Grix app 内**展示：自建服务无需向用户分发私钥、也无需装任何证书——只要①服务挂在 tailnet IP 上、②把它那张 CA 的签发者名字带上 `Grix Tailnet Local CA`，app 就会信任。
+- 需要在 **系统浏览器** 里打开：app 那条规则不起作用，仍需在每台设备装上该服务自己的 CA（见上一节《适用范围》）。
+
+注意：app 内这条是**按签发者名字字符串匹配**，不是按某把 CA 的公钥指纹绑定。它仅作为私有 tailnet 内的便利取舍，**不是强安全边界**——同一 tailnet 内任何人只要把 CA 命名成相同前缀就会被 app 信任。不要据此把它当作可对抗攻击者的信任根。