@symerian/symi 3.0.21 → 3.0.22

package/docs/zh-CN/experiments/research/memory.md

@@ -1,235 +0,0 @@
----
-read_when:
-  - 设计超越每日 Markdown 日志的工作区记忆（~/.symi/workspace）
-  - Deciding: standalone CLI vs deep Symi integration
-  - 添加离线回忆 + 反思（retain/recall/reflect）
-summary: 研究笔记：Symi 工作区的离线记忆系统（Markdown 作为数据源 + 派生索引）
-title: 工作区记忆研究
-x-i18n:
-  generated_at: "2026-02-03T10:06:14Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: 1753c8ee6284999fab4a94ff5fae7421c85233699c9d3088453d0c2133ac0feb
-  source_path: experiments/research/memory.md
-  workflow: 15
----
-
-# 工作区记忆 v2（离线）：研究笔记
-
-目标：Symi 风格的工作区（`agents.defaults.workspace`，默认 `~/.symi/workspace`），其中"记忆"以每天一个 Markdown 文件（`memory/YYYY-MM-DD.md`）加上一小组稳定文件（例如 `memory.md`、`SYMICORE.md`）的形式存储。
-
-本文档提出一种**离线优先**的记忆架构，保持 Markdown 作为规范的、可审查的数据源，但通过派生索引添加**结构化回忆**（搜索、实体摘要、置信度更新）。
-
-## 为什么要改变？
-
-当前设置（每天一个文件）非常适合：
-
-- "仅追加"式日志记录
-- 人工编辑
-- git 支持的持久性 + 可审计性
-- 低摩擦捕获（"直接写下来"）
-
-但它在以下方面较弱：
-
-- 高召回率检索（"我们对 X 做了什么决定？"、"上次我们尝试 Y 时？"）
-- 以实体为中心的答案（"告诉我关于 Alice / The Castle / warelay 的信息"）而无需重读多个文件
-- 观点/偏好稳定性（以及变化时的证据）
-- 时间约束（"2025 年 11 月期间什么是真实的？"）和冲突解决
-
-## 设计目标
-
-- **离线**：无需网络即可工作；可在笔记本电脑/Castle 上运行；无云依赖。
-- **可解释**：检索的项目应该可归因（文件 + 位置）并与推理分离。
-- **低仪式感**：每日日志保持 Markdown，无需繁重的 schema 工作。
-- **增量式**：v1 仅使用 FTS 就很有用；语义/向量和图是可选升级。
-- **对智能体友好**：使"在 token 预算内回忆"变得简单（返回小型事实包）。
-
-## 北极星模型（Hindsight × Letta）
-
-需要融合两个部分：
-
-1. **Letta/MemGPT 风格的控制循环**
-
-- 保持一个小的"核心"始终在上下文中（角色 + 关键用户事实）
-- 其他所有内容都在上下文之外，通过工具检索
-- 记忆写入是显式的工具调用（append/replace/insert），持久化后在下一轮重新注入
-
-2. **Hindsight 风格的记忆基底**
-
-- 分离观察到的、相信的和总结的内容
-- 支持 retain/recall/reflect
-- 带有置信度的观点可以随证据演变
-- 实体感知检索 + 时间查询（即使没有完整的知识图谱）
-
-## 提议的架构（Markdown 数据源 + 派生索引）
-
-### 规范存储（git 友好）
-
-保持 `~/.symi/workspace` 作为规范的人类可读记忆。
-
-建议的工作区布局：
-
-```
-~/.symi/workspace/
-  memory.md                    # 小型：持久事实 + 偏好（类似核心）
-  memory/
-    YYYY-MM-DD.md              # 每日日志（追加；叙事）
-  bank/                        # "类型化"记忆页面（稳定、可审查）
-    world.md                   # 关于世界的客观事实
-    experience.md              # 智能体做了什么（第一人称）
-    opinions.md                # 主观偏好/判断 + 置信度 + 证据指针
-    entities/
-      Peter.md
-      The-Castle.md
-      warelay.md
-      ...
-```
-
-注意：
-
-- **每日日志保持为每日日志**。无需将其转换为 JSON。
-- `bank/` 文件是**经过整理的**，由反思任务生成，仍可手动编辑。
-- `memory.md` 保持"小型 + 类似核心"：你希望 Symi 每次会话都能看到的内容。
-
-### 派生存储（机器回忆）
-
-在工作区下添加派生索引（不一定需要 git 跟踪）：
-
-```
-~/.symi/workspace/.memory/index.sqlite
-```
-
-后端支持：
-
-- 用于事实 + 实体链接 + 观点元数据的 SQLite schema
-- SQLite **FTS5** 用于词法回忆（快速、小巧、离线）
-- 可选的嵌入表用于语义回忆（仍然离线）
-
-索引始终**可从 Markdown 重建**。
-
-## Retain / Recall / Reflect（操作循环）
-
-### Retain：将每日日志规范化为"事实"
-
-Hindsight 在这里重要的关键洞察：存储**叙事性、自包含的事实**，而不是微小的片段。
-
-`memory/YYYY-MM-DD.md` 的实用规则：
-
-- 在一天结束时（或期间），添加一个 `## Retain` 部分，包含 2-5 个要点：
-  - 叙事性（保留跨轮上下文）
-  - 自包含（独立时也有意义）
-  - 标记类型 + 实体提及
-
-示例：
-
-```
-## Retain
-- W @Peter: Currently in Marrakech (Nov 27–Dec 1, 2025) for Andy's birthday.
-- B @warelay: I fixed the Baileys WS crash by wrapping connection.update handlers in try/catch (see memory/2025-11-27.md).
-- O(c=0.95) @Peter: Prefers concise replies (<1500 chars) on WhatsApp; long content goes into files.
-```
-
-最小化解析：
-
-- 类型前缀：`W`（世界）、`B`（经历/传记）、`O`（观点）、`S`（观察/摘要；通常是生成的）
-- 实体：`@Peter`、`@warelay` 等（slug 映射到 `bank/entities/*.md`）
-- 观点置信度：`O(c=0.0..1.0)` 可选
-
-如果你不想让作者考虑这些：反思任务可以从日志的其余部分推断这些要点，但有一个显式的 `## Retain` 部分是最简单的"质量杠杆"。
-
-### Recall：对派生索引的查询
-
-Recall 应支持：
-
-- **词法**："查找精确的术语/名称/命令"（FTS5）
-- **实体**："告诉我关于 X 的信息"（实体页面 + 实体链接的事实）
-- **时间**："11 月 27 日前后发生了什么"/"自上周以来"
-- **观点**："Peter 偏好什么？"（带置信度 + 证据）
-
-返回格式应对智能体友好并引用来源：
-
-- `kind`（`world|experience|opinion|observation`）
-- `timestamp`（来源日期，或如果存在则提取的时间范围）
-- `entities`（`["Peter","warelay"]`）
-- `content`（叙事性事实）
-- `source`（`memory/2025-11-27.md#L12` 等）
-
-### Reflect：生成稳定页面 + 更新信念
-
-反思是一个定时任务（每日或心跳 `ultrathink`），它：
-
-- 根据最近的事实更新 `bank/entities/*.md`（实体摘要）
-- 根据强化/矛盾更新 `bank/opinions.md` 置信度
-- 可选地提议对 `memory.md`（"类似核心"的持久事实）的编辑
-
-观点演变（简单、可解释）：
-
-- 每个观点有：
-  - 陈述
-  - 置信度 `c ∈ [0,1]`
-  - last_updated
-  - 证据链接（支持 + 矛盾的事实 ID）
-- 当新事实到达时：
-  - 通过实体重叠 + 相似性找到候选观点（先 FTS，后嵌入）
-  - 通过小幅增量更新置信度；大幅跳跃需要强矛盾 + 重复证据
-
-## CLI 集成：独立 vs 深度集成
-
-建议：**深度集成到 Symi**，但保持可分离的核心库。
-
-### 为什么要集成到 Symi？
-
-- Symi 已经知道：
-  - 工作区路径（`agents.defaults.workspace`）
-  - 会话模型 + 心跳
-  - 日志记录 + 故障排除模式
-- 你希望智能体自己调用工具：
-  - `symi memory recall "…" --k 25 --since 30d`
-  - `symi memory reflect --since 7d`
-
-### 为什么仍要分离库？
-
-- 保持记忆逻辑可测试，无需 Gateway 网关/运行时
-- 可从其他上下文重用（本地脚本、未来的桌面应用等）
-
-形态：
-记忆工具预计是一个小型 CLI + 库层，但这仅是探索性的。
-
-## "S-Collide" / SuCo：何时使用（研究）
-
-如果"S-Collide"指的是 **SuCo（Subspace Collision）**：这是一种 ANN 检索方法，通过在子空间中使用学习/结构化碰撞来实现强召回/延迟权衡（论文：arXiv 2411.14754，2024）。
-
-对于 `~/.symi/workspace` 的务实观点：
-
-- **不要从** SuCo 开始。
-- 从 SQLite FTS +（可选的）简单嵌入开始；你会立即获得大部分 UX 收益。
-- 仅在以下情况下考虑 SuCo/HNSW/ScaNN 级别的解决方案：
-  - 语料库很大（数万/数十万个块）
-  - 暴力嵌入搜索变得太慢
-  - 召回质量明显受到词法搜索的瓶颈限制
-
-离线友好的替代方案（按复杂性递增）：
-
-- SQLite FTS5 + 元数据过滤（零 ML）
-- 嵌入 + 暴力搜索（如果块数量低，效果出奇地好）
-- HNSW 索引（常见、稳健；需要库绑定）
-- SuCo（研究级；如果有可嵌入的可靠实现则很有吸引力）
-
-开放问题：
-
-- 对于你的机器（笔记本 + 台式机）上的"个人助理记忆"，**最佳**的离线嵌入模型是什么？
-  - 如果你已经有 Ollama：使用本地模型嵌入；否则在工具链中附带一个小型嵌入模型。
-
-## 最小可用试点
-
-如果你想要一个最小但仍有用的版本：
-
-- 添加 `bank/` 实体页面和每日日志中的 `## Retain` 部分。
-- 使用 SQLite FTS 进行带引用的回忆（路径 + 行号）。
-- 仅在召回质量或规模需要时添加嵌入。
-
-## 参考资料
-
-- Letta / MemGPT 概念："核心记忆块" + "档案记忆" + 工具驱动的自编辑记忆。
-- Hindsight 技术报告："retain / recall / reflect"，四网络记忆，叙事性事实提取，观点置信度演变。
-- SuCo：arXiv 2411.14754（2024）："Subspace Collision"近似最近邻检索。

package/docs/zh-CN/gateway/authentication.md

@@ -1,142 +0,0 @@
----
-read_when:
-  - 调试模型认证或 OAuth 过期
-  - 记录认证或凭证存储
-summary: 模型认证：OAuth、API 密钥和 setup-token
-title: 认证
-x-i18n:
-  generated_at: "2026-02-03T07:47:32Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: 66fa2c64ff374c9cfcdb4e7a951b0d164d512295e65513eb682f12191b75e557
-  source_path: gateway/authentication.md
-  workflow: 15
----
-
-# 认证
-
-Symi 支持模型提供商的 OAuth 和 API 密钥。对于 Anthropic 账户，我们推荐使用 **API 密钥**。对于 Claude 订阅访问，使用 `claude setup-token` 创建的长期令牌。
-
-参阅 [/concepts/oauth](/concepts/oauth) 了解完整的 OAuth 流程和存储布局。
-
-## 推荐的 Anthropic 设置（API 密钥）
-
-如果你直接使用 Anthropic，请使用 API 密钥。
-
-1. 在 Anthropic 控制台创建 API 密钥。
-2. 将其放在 **Gateway 网关主机**（运行 `symi gateway` 的机器）上。
-
-```bash
-export ANTHROPIC_API_KEY="..."
-symi models status
-```
-
-3. 如果 Gateway 网关在 systemd/launchd 下运行，最好将密钥放在 `~/.symi/.env` 中以便守护进程可以读取：
-
-```bash
-cat >> ~/.symi/.env <<'EOF'
-ANTHROPIC_API_KEY=...
-EOF
-```
-
-然后重启守护进程（或重启你的 Gateway 网关进程）并重新检查：
-
-```bash
-symi models status
-symi doctor
-```
-
-如果你不想自己管理环境变量，新手引导向导可以为守护进程使用存储 API 密钥：`symi onboard`。
-
-参阅[帮助](/help)了解环境变量继承的详情（`env.shellEnv`、`~/.symi/.env`、systemd/launchd）。
-
-## Anthropic：setup-token（订阅认证）
-
-对于 Anthropic，推荐的路径是 **API 密钥**。如果你使用 Claude 订阅，也支持 setup-token 流程。在 **Gateway 网关主机**上运行：
-
-```bash
-claude setup-token
-```
-
-然后将其粘贴到 Symi：
-
-```bash
-symi models auth setup-token --provider anthropic
-```
-
-如果令牌是在另一台机器上创建的，手动粘贴：
-
-```bash
-symi models auth paste-token --provider anthropic
-```
-
-如果你看到类似这样的 Anthropic 错误：
-
-```
-This credential is only authorized for use with Claude Code and cannot be used for other API requests.
-```
-
-…请改用 Anthropic API 密钥。
-
-手动令牌输入（任何提供商；写入 `auth-profiles.json` + 更新配置）：
-
-```bash
-symi models auth paste-token --provider anthropic
-symi models auth paste-token --provider openrouter
-```
-
-自动化友好检查（过期/缺失时退出 `1`，即将过期时退出 `2`）：
-
-```bash
-symi models status --check
-```
-
-可选的运维脚本（systemd/Termux）在此处记录：[/automation/auth-monitoring](/automation/auth-monitoring)
-
-> `claude setup-token` 需要交互式 TTY。
-
-## 检查模型认证状态
-
-```bash
-symi models status
-symi doctor
-```
-
-## 控制使用哪个凭证
-
-### 每会话（聊天命令）
-
-使用 `/model <alias-or-id>@<profileId>` 为当前会话固定特定的提供商凭证（示例配置文件 ID：`anthropic:default`、`anthropic:work`）。
-
-使用 `/model`（或 `/model list`）获取紧凑的选择器；使用 `/model status` 获取完整视图（候选项 + 下一个认证配置文件，以及配置时的提供商端点详情）。
-
-### 每智能体（CLI 覆盖）
-
-为智能体设置显式的认证配置文件顺序覆盖（存储在该智能体的 `auth-profiles.json` 中）：
-
-```bash
-symi models auth order get --provider anthropic
-symi models auth order set --provider anthropic anthropic:default
-symi models auth order clear --provider anthropic
-```
-
-使用 `--agent <id>` 指定特定智能体；省略它则使用配置的默认智能体。
-
-## 故障排除
-
-### "No credentials found"
-
-如果 Anthropic 令牌配置文件缺失，在 **Gateway 网关主机**上运行 `claude setup-token`，然后重新检查：
-
-```bash
-symi models status
-```
-
-### 令牌即将过期/已过期
-
-运行 `symi models status` 确认哪个配置文件即将过期。如果配置文件缺失，重新运行 `claude setup-token` 并再次粘贴令牌。
-
-## 要求
-
-- Claude Max 或 Pro 订阅（用于 `claude setup-token`）
-- 已安装 Claude Code CLI（`claude` 命令可用）

package/docs/zh-CN/gateway/background-process.md

@@ -1,100 +0,0 @@
----
-read_when:
-  - 添加或修改后台 exec 行为
-  - 调试长时间运行的 exec 任务
-summary: 后台 exec 执行和进程管理
-title: 后台 Exec 和 Process 工具
-x-i18n:
-  generated_at: "2026-02-03T10:05:51Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: e11a7d74a75000d6882f703693c2c49a2ecd3e730b6ec2b475ac402abde9e465
-  source_path: gateway/background-process.md
-  workflow: 15
----
-
-# 后台 Exec + Process 工具
-
-Symi 通过 `exec` 工具运行 shell 命令，并将长时间运行的任务保存在内存中。`process` 工具管理这些后台会话。
-
-## exec 工具
-
-关键参数：
-
-- `command`（必填）
-- `yieldMs`（默认 10000）：在此延迟后自动转为后台运行
-- `background`（布尔值）：立即转为后台运行
-- `timeout`（秒，默认 1800）：在此超时后终止进程
-- `elevated`（布尔值）：如果启用/允许提权模式，则在宿主机上运行
-- 需要真实 TTY？设置 `pty: true`。
-- `workdir`、`env`
-
-行为：
-
-- 前台运行直接返回输出。
-- 当转为后台运行（显式或超时）时，工具返回 `status: "running"` + `sessionId` 和一小段尾部输出。
-- 输出保存在内存中，直到会话被轮询或清除。
-- 如果 `process` 工具被禁用，`exec` 将同步运行并忽略 `yieldMs`/`background`。
-
-## 子进程桥接
-
-当在 exec/process 工具之外生成长时间运行的子进程时（例如 CLI 重新生成或 Gateway 网关辅助程序），请附加子进程桥接辅助程序，以便终止信号被转发，监听器在退出/错误时被分离。这可以避免在 systemd 上产生孤立进程，并保持跨平台的关闭行为一致。
-
-环境变量覆盖：
-
-- `PI_BASH_YIELD_MS`：默认 yield 时间（毫秒）
-- `PI_BASH_MAX_OUTPUT_CHARS`：内存输出上限（字符）
-- `SYMI_BASH_PENDING_MAX_OUTPUT_CHARS`：每个流的待处理 stdout/stderr 上限（字符）
-- `PI_BASH_JOB_TTL_MS`：已完成会话的 TTL（毫秒，限制在 1 分钟至 3 小时之间）
-
-配置（推荐）：
-
-- `tools.exec.backgroundMs`（默认 10000）
-- `tools.exec.timeoutSec`（默认 1800）
-- `tools.exec.cleanupMs`（默认 1800000）
-- `tools.exec.notifyOnExit`（默认 true）：当后台 exec 退出时，将系统事件加入队列并请求心跳。
-
-## process 工具
-
-操作：
-
-- `list`：正在运行和已完成的会话
-- `poll`：获取会话的新输出（同时报告退出状态）
-- `log`：读取聚合输出（支持 `offset` + `limit`）
-- `write`：发送 stdin（`data`，可选 `eof`）
-- `kill`：终止后台会话
-- `clear`：从内存中移除已完成的会话
-- `remove`：如果正在运行则终止，否则清除已完成的会话
-
-注意事项：
-
-- 只有后台会话会在内存中列出/保留。
-- 会话在进程重启时会丢失（无磁盘持久化）。
-- 会话日志只有在你运行 `process poll/log` 且工具结果被记录时才会保存到聊天历史。
-- `process` 按智能体隔离；它只能看到该智能体启动的会话。
-- `process list` 包含派生的 `name`（命令动词 + 目标）以便快速浏览。
-- `process log` 使用基于行的 `offset`/`limit`（省略 `offset` 以获取最后 N 行）。
-
-## 示例
-
-运行长时间任务并稍后轮询：
-
-```json
-{ "tool": "exec", "command": "sleep 5 && echo done", "yieldMs": 1000 }
-```
-
-```json
-{ "tool": "process", "action": "poll", "sessionId": "<id>" }
-```
-
-立即在后台启动：
-
-```json
-{ "tool": "exec", "command": "npm run build", "background": true }
-```
-
-发送 stdin：
-
-```json
-{ "tool": "process", "action": "write", "sessionId": "<id>", "data": "y\n" }
-```

package/docs/zh-CN/gateway/bonjour.md

@@ -1,174 +0,0 @@
----
-read_when:
-  - 在 macOS/iOS 上调试 Bonjour 设备发现问题时
-  - 更改 mDNS 服务类型、TXT 记录或设备发现用户体验时
-summary: Bonjour/mDNS 设备发现 + 调试（Gateway 网关信标、客户端和常见故障模式）
-title: Bonjour 设备发现
-x-i18n:
-  generated_at: "2026-02-03T07:47:48Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: 47569da55f0c0523bd5ff05275dc95ccb52f75638193cfbdb4eaaa162aadf08c
-  source_path: gateway/bonjour.md
-  workflow: 15
----
-
-# Bonjour / mDNS 设备发现
-
-Symi 使用 Bonjour（mDNS / DNS‑SD）作为**仅限局域网的便捷方式**来发现
-活跃的 Gateway 网关（WebSocket 端点）。这是尽力而为的，**不能**替代 SSH 或
-基于 Tailnet 的连接。
-
-## 通过 Tailscale 的广域 Bonjour（单播 DNS‑SD）
-
-如果节点和 Gateway 网关在不同的网络上，多播 mDNS 无法跨越
-边界。你可以通过切换到基于 Tailscale 的**单播 DNS‑SD**
-（"广域 Bonjour"）来保持相同的设备发现用户体验。
-
-概要步骤：
-
-1. 在 Gateway 网关主机上运行 DNS 服务器（可通过 Tailnet 访问）。
-2. 在专用区域下发布 `_symi-gw._tcp` 的 DNS‑SD 记录
-   （示例：`symi.internal.`）。
-3. 配置 Tailscale **分割 DNS**，使你选择的域名通过该
-   DNS 服务器为客户端（包括 iOS）解析。
-
-Symi 支持任何发现域名；`symi.internal.` 只是一个示例。
-iOS/Android 节点同时浏览 `local.` 和你配置的广域域名。
-
-### Gateway 网关配置（推荐）
-
-```json5
-{
-  gateway: { bind: "tailnet" }, // 仅 tailnet（推荐）
-  discovery: { wideArea: { enabled: true } }, // 启用广域 DNS-SD 发布
-}
-```
-
-### 一次性 DNS 服务器设置（Gateway 网关主机）
-
-```bash
-symi dns setup --apply
-```
-
-这会安装 CoreDNS 并配置它：
-
-- 仅在 Gateway 网关的 Tailscale 接口上监听 53 端口
-- 从 `~/.symi/dns/<domain>.db` 提供你选择的域名服务（示例：`symi.internal.`）
-
-从 Tailnet 连接的机器上验证：
-
-```bash
-dns-sd -B _symi-gw._tcp symi.internal.
-dig @<TAILNET_IPV4> -p 53 _symi-gw._tcp.symi.internal PTR +short
-```
-
-### Tailscale DNS 设置
-
-在 Tailscale 管理控制台中：
-
-- 添加指向 Gateway 网关 Tailnet IP 的名称服务器（UDP/TCP 53）。
-- 添加分割 DNS，使你的发现域名使用该名称服务器。
-
-一旦客户端接受 Tailnet DNS，iOS 节点就可以在
-你的发现域名中浏览 `_symi-gw._tcp`，无需多播。
-
-### Gateway 网关监听器安全（推荐）
-
-Gateway 网关 WS 端口（默认 `18789`）默认绑定到 loopback。对于局域网/Tailnet
-访问，请明确绑定并保持认证启用。
-
-对于仅 Tailnet 的设置：
-
-- 在 `~/.symi/symi.json` 中设置 `gateway.bind: "tailnet"`。
-- 重启 Gateway 网关（或重启 macOS 菜单栏应用）。
-
-## 什么在广播
-
-只有 Gateway 网关广播 `_symi-gw._tcp`。
-
-## 服务类型
-
-- `_symi-gw._tcp` — Gateway 网关传输信标（被 macOS/iOS/Android 节点使用）。
-
-## TXT 键（非机密提示）
-
-Gateway 网关广播小型非机密提示以方便 UI 流程：
-
-- `role=gateway`
-- `displayName=<友好名称>`
-- `lanHost=<hostname>.local`
-- `gatewayPort=<port>`（Gateway 网关 WS + HTTP）
-- `gatewayTls=1`（仅当 TLS 启用时）
-- `gatewayTlsSha256=<sha256>`（仅当 TLS 启用且指纹可用时）
-- `canvasPort=<port>`（仅当画布主机启用时；默认 `18793`）
-- `sshPort=<port>`（未覆盖时默认为 22）
-- `transport=gateway`
-- `cliPath=<path>`（可选；可运行的 `symi` 入口点的绝对路径）
-- `tailnetDns=<magicdns>`（当 Tailnet 可用时的可选提示）
-
-## 在 macOS 上调试
-
-有用的内置工具：
-
-- 浏览实例：
-  ```bash
-  dns-sd -B _symi-gw._tcp local.
-  ```
-- 解析单个实例（替换 `<instance>`）：
-  ```bash
-  dns-sd -L "<instance>" _symi-gw._tcp local.
-  ```
-
-如果浏览有效但解析失败，你通常遇到的是局域网策略或
-mDNS 解析器问题。
-
-## 在 Gateway 网关日志中调试
-
-Gateway 网关会写入滚动日志文件（启动时打印为
-`gateway log file: ...`）。查找 `bonjour:` 行，特别是：
-
-- `bonjour: advertise failed ...`
-- `bonjour: ... name conflict resolved` / `hostname conflict resolved`
-- `bonjour: watchdog detected non-announced service ...`
-
-## 在 iOS 节点上调试
-
-iOS 节点使用 `NWBrowser` 来发现 `_symi-gw._tcp`。
-
-要捕获日志：
-
-- 设置 → Gateway 网关 → 高级 → **Discovery Debug Logs**
-- 设置 → Gateway 网关 → 高级 → **Discovery Logs** → 复现 → **Copy**
-
-日志包括浏览器状态转换和结果集变化。
-
-## 常见故障模式
-
-- **Bonjour 不能跨网络**：使用 Tailnet 或 SSH。
-- **多播被阻止**：某些 Wi‑Fi 网络禁用 mDNS。
-- **休眠 / 接口变动**：macOS 可能暂时丢弃 mDNS 结果；重试。
-- **浏览有效但解析失败**：保持机器名称简单（避免表情符号或
-  标点符号），然后重启 Gateway 网关。服务实例名称源自
-  主机名，因此过于复杂的名称可能会混淆某些解析器。
-
-## 转义的实例名称（`\032`）
-
-Bonjour/DNS‑SD 经常将服务实例名称中的字节转义为十进制 `\DDD`
-序列（例如空格变成 `\032`）。
-
-- 这在协议级别是正常的。
-- UI 应该解码以进行显示（iOS 使用 `BonjourEscapes.decode`）。
-
-## 禁用 / 配置
-
-- `SYMI_DISABLE_BONJOUR=1` 禁用广播（旧版：`SYMI_DISABLE_BONJOUR`）。
-- `~/.symi/symi.json` 中的 `gateway.bind` 控制 Gateway 网关绑定模式。
-- `SYMI_SSH_PORT` 覆盖 TXT 中广播的 SSH 端口（旧版：`SYMI_SSH_PORT`）。
-- `SYMI_TAILNET_DNS` 在 TXT 中发布 MagicDNS 提示（旧版：`SYMI_TAILNET_DNS`）。
-- `SYMI_CLI_PATH` 覆盖广播的 CLI 路径（旧版：`SYMI_CLI_PATH`）。
-
-## 相关文档
-
-- 设备发现策略和传输选择：[设备发现](/gateway/discovery)
-- 节点配对 + 批准：[Gateway 网关配对](/gateway/pairing)