@symerian/symi 3.0.20 → 3.0.22

package/docs/zh-CN/reference/RELEASING.md

@@ -1,122 +0,0 @@
----
-read_when:
-  - 发布新的 npm 版本
-  - 发布新的 macOS 应用版本
-  - 发布前验证元数据
-summary: npm + macOS 应用的逐步发布清单
-x-i18n:
-  generated_at: "2026-02-03T10:09:28Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: 1a684bc26665966eb3c9c816d58d18eead008fd710041181ece38c21c5ff1c62
-  source_path: reference/RELEASING.md
-  workflow: 15
----
-
-# 发布清单（npm + macOS）
-
-从仓库根目录使用 `pnpm`（Node 22+）。在打标签/发布前保持工作树干净。
-
-## 操作员触发
-
-当操作员说"release"时，立即执行此预检（除非遇到阻碍否则不要额外提问）：
-
-- 阅读本文档和 `docs/platforms/mac/release.md`。
-- 从 `~/.profile` 加载环境变量并确认 `SPARKLE_PRIVATE_KEY_FILE` + App Store Connect 变量已设置（SPARKLE_PRIVATE_KEY_FILE 应位于 `~/.profile` 中）。
-- 如需要，使用 `~/Library/CloudStorage/Dropbox/Backup/Sparkle` 中的 Sparkle 密钥。
-
-1. **版本和元数据**
-
-- [ ] 更新 `package.json` 版本（例如 `2026.1.29`）。
-- [ ] 运行 `pnpm plugins:sync` 以对齐扩展包版本和变更日志。
-- [ ] 更新 CLI/版本字符串：[`src/cli/program.ts`](https://github.com/symi/symi/blob/main/src/cli/program.ts) 和 [`src/provider-web.ts`](https://github.com/symi/symi/blob/main/src/provider-web.ts) 中的 Baileys user agent。
-- [ ] 确认包元数据（name、description、repository、keywords、license）以及 `bin` 映射指向 [`symi.mjs`](https://github.com/symi/symi/blob/main/symi.mjs) 作为 `symi`。
-- [ ] 如果依赖项有变化，运行 `pnpm install` 确保 `pnpm-lock.yaml` 是最新的。
-
-2. **构建和产物**
-
-- [ ] 如果 A2UI 输入有变化，运行 `pnpm canvas:a2ui:bundle` 并提交更新后的 [`src/canvas-host/a2ui/a2ui.bundle.js`](https://github.com/symi/symi/blob/main/src/canvas-host/a2ui/a2ui.bundle.js)。
-- [ ] `pnpm run build`（重新生成 `dist/`）。
-- [ ] 验证 npm 包的 `files` 包含所有必需的 `dist/*` 文件夹（特别是用于 headless node + ACP CLI 的 `dist/node-host/**` 和 `dist/acp/**`）。
-- [ ] 确认 `dist/build-info.json` 存在并包含预期的 `commit` 哈希（CLI 横幅在 npm 安装时使用此信息）。
-- [ ] 可选：构建后运行 `npm pack --pack-destination /tmp`；检查 tarball 内容并保留以备 GitHub 发布使用（**不要**提交它）。
-
-3. **变更日志和文档**
-
-- [ ] 更新 `CHANGELOG.md`，添加面向用户的亮点（如果文件不存在则创建）；按版本严格降序排列条目。
-- [ ] 确保 README 示例/标志与当前 CLI 行为匹配（特别是新命令或选项）。
-
-4. **验证**
-
-- [ ] `pnpm build`
-- [ ] `pnpm check`
-- [ ] `pnpm test`（如需覆盖率输出则使用 `pnpm test:coverage`）
-- [ ] `pnpm release:check`（验证 npm pack 内容）
-- [ ] `SYMI_INSTALL_SMOKE_SKIP_NONROOT=1 pnpm test:install:smoke`（Docker 安装冒烟测试，快速路径；发布前必需）
-  - 如果已知上一个 npm 发布版本有问题，为预安装步骤设置 `SYMI_INSTALL_SMOKE_PREVIOUS=<last-good-version>` 或 `SYMI_INSTALL_SMOKE_SKIP_PREVIOUS=1`。
-- [ ]（可选）完整安装程序冒烟测试（添加非 root + CLI 覆盖）：`pnpm test:install:smoke`
-- [ ]（可选）安装程序 E2E（Docker，运行 `curl -fsSL https://jaysteelmind.github.io/getsymi/install.sh | bash`，新手引导，然后运行真实工具调用）：
-  - `pnpm test:install:e2e:openai`（需要 `OPENAI_API_KEY`）
-  - `pnpm test:install:e2e:anthropic`（需要 `ANTHROPIC_API_KEY`）
-  - `pnpm test:install:e2e`（需要两个密钥；运行两个提供商）
-- [ ]（可选）如果你的更改影响发送/接收路径，抽查 Web Gateway 网关。
-
-5. **macOS 应用（Sparkle）**
-
-- [ ] 构建并签名 macOS 应用，然后压缩以供分发。
-- [ ] 生成 Sparkle appcast（通过 [`scripts/make_appcast.sh`](https://github.com/symi/symi/blob/main/scripts/make_appcast.sh) 生成 HTML 注释）并更新 `appcast.xml`。
-- [ ] 保留应用 zip（和可选的 dSYM zip）以便附加到 GitHub 发布。
-- [ ] 按照 [macOS 发布](/platforms/mac/release) 获取确切命令和所需环境变量。
-  - `APP_BUILD` 必须是数字且单调递增（不带 `-beta`），以便 Sparkle 正确比较版本。
-  - 如果进行公证，使用从 App Store Connect API 环境变量创建的 `symi-notary` 钥匙串配置文件（参见 [macOS 发布](/platforms/mac/release)）。
-
-6. **发布（npm）**
-
-- [ ] 确认 git 状态干净；根据需要提交并推送。
-- [ ] 如需要，`npm login`（验证 2FA）。
-- [ ] `npm publish --access public`（预发布版本使用 `--tag beta`）。
-- [ ] 验证注册表：`npm view symi version`、`npm view symi dist-tags` 和 `npx -y symi@X.Y.Z --version`（或 `--help`）。
-
-### 故障排除（来自 2.0.0-beta2 发布的笔记）
-
-- **npm pack/publish 挂起或产生巨大 tarball**：`dist/Symi.app` 中的 macOS 应用包（和发布 zip）被扫入包中。通过 `package.json` 的 `files` 白名单发布内容来修复（包含 dist 子目录、docs、skills；排除应用包）。用 `npm pack --dry-run` 确认 `dist/Symi.app` 未列出。
-- **npm auth dist-tags 的 Web 循环**：使用旧版认证以获取 OTP 提示：
-  - `NPM_CONFIG_AUTH_TYPE=legacy npm dist-tag add symi@X.Y.Z latest`
-- **`npx` 验证失败并显示 `ECOMPROMISED: Lock compromised`**：使用新缓存重试：
-  - `NPM_CONFIG_CACHE=/tmp/npm-cache-$(date +%s) npx -y symi@X.Y.Z --version`
-- **延迟修复后需要重新指向标签**：强制更新并推送标签，然后确保 GitHub 发布资产仍然匹配：
-  - `git tag -f vX.Y.Z && git push -f origin vX.Y.Z`
-
-7. **GitHub 发布 + appcast**
-
-- [ ] 打标签并推送：`git tag vX.Y.Z && git push origin vX.Y.Z`（或 `git push --tags`）。
-- [ ] 为 `vX.Y.Z` 创建/刷新 GitHub 发布，**标题为 `symi X.Y.Z`**（不仅仅是标签）；正文应包含该版本的**完整**变更日志部分（亮点 + 更改 + 修复），内联显示（无裸链接），且**不得在正文中重复标题**。
-- [ ] 附加产物：`npm pack` tarball（可选）、`Symi-X.Y.Z.zip` 和 `Symi-X.Y.Z.dSYM.zip`（如果生成）。
-- [ ] 提交更新后的 `appcast.xml` 并推送（Sparkle 从 main 获取源）。
-- [ ] 从干净的临时目录（无 `package.json`），运行 `npx -y symi@X.Y.Z send --help` 确认安装/CLI 入口点正常工作。
-- [ ] 宣布/分享发布说明。
-
-## 插件发布范围（npm）
-
-我们只发布 `@symi/*` 范围下的**现有 npm 插件**。不在 npm 上的内置插件保持**仅磁盘树**（仍在 `extensions/**` 中发布）。
-
-获取列表的流程：
-
-1. `npm search @symi --json` 并捕获包名。
-2. 与 `extensions/*/package.json` 名称比较。
-3. 只发布**交集**（已在 npm 上）。
-
-当前 npm 插件列表（根据需要更新）：
-
-- @symi/bluebubbles
-- @symi/diagnostics-otel
-- @symi/pipeline
-- @symi/matrix
-- @symi/msteams
-- @symi/nextcloud-talk
-- @symi/nostr
-- @symi/voice-call
-- @symi/zalo
-- @symi/zalouser
-
-发布说明还必须标注**默认未启用**的**新可选内置插件**（例如：`tlon`）。

package/docs/zh-CN/reference/api-usage-costs.md

@@ -1,136 +0,0 @@
----
-read_when:
-  - 你想了解哪些功能可能调用付费 API
-  - 你需要审核密钥、费用和用量可见性
-  - 你正在解释 /status 或 /usage 的费用报告
-summary: 审核哪些功能会产生费用、使用了哪些密钥以及如何查看用量
-title: API 用量与费用
-x-i18n:
-  generated_at: "2026-02-01T21:37:08Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: 807d0d88801e919a8246517820644db1e6271d165fa376b2e637f05a9121d8b1
-  source_path: reference/api-usage-costs.md
-  workflow: 15
----
-
-# API 用量与费用
-
-本文档列出了**可能调用 API 密钥的功能**及其费用的显示位置。重点介绍 Symi 中可能产生提供商用量或付费 API 调用的功能。
-
-## 费用显示位置（聊天 + CLI）
-
-**每会话费用快照**
-
-- `/status` 显示当前会话模型、上下文用量和上次响应的 token 数。
-- 如果模型使用 **API 密钥认证**，`/status` 还会显示上次回复的**预估费用**。
-
-**每条消息费用页脚**
-
-- `/usage full` 在每条回复后附加用量页脚，包括**预估费用**（仅限 API 密钥）。
-- `/usage tokens` 仅显示 token 数；OAuth 流程会隐藏美元费用。
-
-**CLI 用量窗口（提供商配额）**
-
-- `symi status --usage` 和 `symi channels list` 显示提供商**用量窗口**（配额快照，非每条消息的费用）。
-
-详情和示例请参阅 [Token 用量与费用](/reference/token-use)。
-
-## 密钥的发现方式
-
-Symi 可以从以下来源获取凭据：
-
-- **认证配置文件**（按智能体配置，存储在 `auth-profiles.json` 中）。
-- **环境变量**（例如 `OPENAI_API_KEY`、`BRAVE_API_KEY`、`FIRECRAWL_API_KEY`）。
-- **配置文件**（`models.providers.*.apiKey`、`tools.web.search.*`、`tools.web.fetch.firecrawl.*`、`memorySearch.*`、`talk.apiKey`）。
-- **Skills**（`skills.entries.<name>.apiKey`），可能会将密钥导出到 Skills 进程的环境变量中。
-
-## 可能消耗密钥的功能
-
-### 1）核心模型响应（聊天 + 工具）
-
-每次回复或工具调用都使用**当前模型提供商**（OpenAI、Anthropic 等）。这是用量和费用的主要来源。
-
-定价配置请参阅[模型](/providers/models)，显示方式请参阅 [Token 用量与费用](/reference/token-use)。
-
-### 2）媒体理解（音频/图像/视频）
-
-入站媒体可以在回复生成前进行摘要/转录。这会使用模型/提供商 API。
-
-- 音频：OpenAI / Groq / Deepgram（当密钥存在时**自动启用**）。
-- 图像：OpenAI / Anthropic / Google。
-- 视频：Google。
-
-请参阅[媒体理解](/nodes/media-understanding)。
-
-### 3）记忆嵌入 + 语义搜索
-
-语义记忆搜索在配置为远程提供商时使用**嵌入 API**：
-
-- `memorySearch.provider = "openai"` → OpenAI 嵌入
-- `memorySearch.provider = "gemini"` → Gemini 嵌入
-- 本地嵌入失败时可选回退到 OpenAI
-
-你可以使用 `memorySearch.provider = "local"` 保持本地运行（无 API 用量）。
-
-请参阅[记忆](/concepts/memory)。
-
-### 4）网页搜索工具（Brave / 通过 OpenRouter 使用 Perplexity）
-
-`web_search` 使用 API 密钥，可能产生使用费用：
-
-- **Brave Search API**：`BRAVE_API_KEY` 或 `tools.web.search.apiKey`
-- **Perplexity**（通过 OpenRouter）：`PERPLEXITY_API_KEY` 或 `OPENROUTER_API_KEY`
-
-**Brave 免费套餐（额度充裕）：**
-
-- **每月 2,000 次请求**
-- **每秒 1 次请求**
-- **需要信用卡**进行验证（除非升级否则不会收费）
-
-请参阅[网页工具](/tools/web)。
-
-### 5）网页抓取工具（Firecrawl）
-
-`web_fetch` 在存在 API 密钥时可以调用 **Firecrawl**：
-
-- `FIRECRAWL_API_KEY` 或 `tools.web.fetch.firecrawl.apiKey`
-
-如果未配置 Firecrawl，该工具会回退到直接抓取 + 可读性提取（无付费 API）。
-
-请参阅[网页工具](/tools/web)。
-
-### 6）提供商用量快照（状态/健康检查）
-
-某些状态命令会调用**提供商用量端点**以显示配额窗口或认证健康状态。这些通常是低频调用，但仍会访问提供商 API：
-
-- `symi status --usage`
-- `symi models status --json`
-
-请参阅[模型 CLI](/cli/models)。
-
-### 7）压缩保护摘要
-
-压缩保护功能可以使用**当前模型**对会话历史进行摘要，运行时会调用提供商 API。
-
-请参阅[会话管理 + 压缩](/reference/session-management-compaction)。
-
-### 8）模型扫描/探测
-
-`symi models scan` 可以探测 OpenRouter 模型，启用探测时会使用 `OPENROUTER_API_KEY`。
-
-请参阅[模型 CLI](/cli/models)。
-
-### 9）语音对话（Talk）
-
-语音对话模式在配置后可以调用 **ElevenLabs**：
-
-- `ELEVENLABS_API_KEY` 或 `talk.apiKey`
-
-请参阅[语音对话模式](/nodes/talk)。
-
-### 10）Skills（第三方 API）
-
-Skills 可以在 `skills.entries.<name>.apiKey` 中存储 `apiKey`。如果 Skills 使用该密钥调用外部 API，则会根据 Skills 的提供商产生费用。
-
-请参阅[Skills](/tools/skills)。

package/docs/zh-CN/reference/credits.md

@@ -1,34 +0,0 @@
----
-read_when:
-  - 你想了解项目背景故事或贡献者致谢信息
-summary: 项目起源、贡献者和许可证。
-title: 致谢
-x-i18n:
-  generated_at: "2026-02-04T17:53:19Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: d55e520313e131025b22cb20b3d2fbd44619e1668d09b5bd9d56d7df019bc46c
-  source_path: reference/credits.md
-  workflow: 15
----
-
-## 名称由来
-
-Symi = SHELL + TARDIS，因为每只太空龙虾都需要一台时空机器。
-
-## 致谢
-
-- **Peter Steinberger** ([@steipete](https://x.com/steipete)) - 创建者，龙虾语者
-- **Mario Zechner** ([@badlogicc](https://x.com/badlogicgames)) - Pi 创建者，安全渗透测试员
-- **Symi** - 那只要求取个更好名字的太空龙虾
-
-## 核心贡献者
-
-- **Maxim Vovshin** (@Hyaxia, 36747317+Hyaxia@users.noreply.github.com) - Blogwatcher skill
-- **Nacho Iacovino** (@nachoiacovino, nacho.iacovino@gmail.com) - 位置解析（Telegram 和 WhatsApp）
-
-## 许可证
-
-MIT - 像海洋中的龙虾一样自由。
-
-> "我们都只是在玩自己的提示词而已。"（某个 AI，大概是 token 吸多了）

package/docs/zh-CN/reference/device-models.md

@@ -1,54 +0,0 @@
----
-read_when:
-  - 更新设备型号标识符映射或 NOTICE/许可证文件
-  - 更改实例 UI 中设备名称的显示方式
-summary: Symi 如何内置 Apple 设备型号标识符以在 macOS 应用中显示友好名称。
-title: 设备型号数据库
-x-i18n:
-  generated_at: "2026-02-01T21:37:07Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: 1d99c2538a0d8fdd80fa468fa402f63479ef2522e83745a0a46527a86238aeb2
-  source_path: reference/device-models.md
-  workflow: 15
----
-
-# 设备型号数据库（友好名称）
-
-macOS 配套应用通过将 Apple 型号标识符（例如 `iPad16,6`、`Mac16,6`）映射为人类可读的名称，在**实例** UI 中显示友好的 Apple 设备型号名称。
-
-该映射以 JSON 形式内置于：
-
-- `apps/macos/Sources/Symi/Resources/DeviceModels/`
-
-## 数据来源
-
-我们目前内置的映射来自 MIT 许可的仓库：
-
-- `kyle-seongwoo-jun/apple-device-identifiers`
-
-为保持构建的确定性，JSON 文件固定到特定的上游提交（记录在 `apps/macos/Sources/Symi/Resources/DeviceModels/NOTICE.md` 中）。
-
-## 更新数据库
-
-1. 选择要固定的上游提交（iOS 和 macOS 各一个）。
-2. 更新 `apps/macos/Sources/Symi/Resources/DeviceModels/NOTICE.md` 中的提交哈希。
-3. 重新下载固定到这些提交的 JSON 文件：
-
-```bash
-IOS_COMMIT="<commit sha for ios-device-identifiers.json>"
-MAC_COMMIT="<commit sha for mac-device-identifiers.json>"
-
-curl -fsSL "https://raw.githubusercontent.com/kyle-seongwoo-jun/apple-device-identifiers/${IOS_COMMIT}/ios-device-identifiers.json" \
-  -o apps/macos/Sources/Symi/Resources/DeviceModels/ios-device-identifiers.json
-
-curl -fsSL "https://raw.githubusercontent.com/kyle-seongwoo-jun/apple-device-identifiers/${MAC_COMMIT}/mac-device-identifiers.json" \
-  -o apps/macos/Sources/Symi/Resources/DeviceModels/mac-device-identifiers.json
-```
-
-4. 确保 `apps/macos/Sources/Symi/Resources/DeviceModels/LICENSE.apple-device-identifiers.txt` 仍与上游一致（如果上游许可证发生变更，请替换该文件）。
-5. 验证 macOS 应用能够正常构建（无警告）：
-
-```bash
-swift build --package-path apps/macos
-```

package/docs/zh-CN/reference/rpc.md

@@ -1,48 +0,0 @@
----
-read_when:
-  - 添加或更改外部 CLI 集成
-  - 调试 RPC 适配器（signal-cli、imsg）
-summary: 外部 CLI（signal-cli、imsg）的 RPC 适配器和 Gateway 网关模式
-title: RPC 适配器
-x-i18n:
-  generated_at: "2026-02-03T07:53:44Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: c04edc952390304a22a3a4763aca00a0311b38d390477ec0be5fe485ec257fa7
-  source_path: reference/rpc.md
-  workflow: 15
----
-
-# RPC 适配器
-
-Symi 通过 JSON-RPC 集成外部 CLI。目前使用两种模式。
-
-## 模式 A：HTTP 守护进程（signal-cli）
-
-- `signal-cli` 作为守护进程运行，通过 HTTP 使用 JSON-RPC。
-- 事件流是 SSE（`/api/v1/events`）。
-- 健康探测：`/api/v1/check`。
-- 当 `channels.signal.autoStart=true` 时，Symi 负责生命周期管理。
-
-设置和端点参见 [Signal](/channels/signal)。
-
-## 模式 B：stdio 子进程（imsg）
-
-- Symi 将 `imsg rpc` 作为子进程生成。
-- JSON-RPC 是通过 stdin/stdout 的行分隔格式（每行一个 JSON 对象）。
-- 无需 TCP 端口，无需守护进程。
-
-使用的核心方法：
-
-- `watch.subscribe` → 通知（`method: "message"`）
-- `watch.unsubscribe`
-- `send`
-- `chats.list`（探测/诊断）
-
-设置和寻址（首选 `chat_id`）参见 [iMessage](/channels/imessage)。
-
-## 适配器指南
-
-- Gateway 网关负责进程（启动/停止与提供商生命周期绑定）。
-- 保持 RPC 客户端弹性：超时、退出时重启。
-- 优先使用稳定 ID（例如 `chat_id`）而非显示字符串。

package/docs/zh-CN/reference/session-management-compaction.md

@@ -1,286 +0,0 @@
----
-read_when:
-  - 你需要调试会话 ID、记录 JSONL 或 sessions.json 字段
-  - 你正在更改自动压缩行为或添加"压缩前"内务处理
-  - 你想实现记忆刷新或静默系统回合
-summary: 深入了解：会话存储 + 记录、生命周期和（自动）压缩内部机制
-title: 会话管理深入了解
-x-i18n:
-  generated_at: "2026-02-03T07:54:38Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: bf3715770ba634363933f6038117b6a91af11c62f5191aaaf97e6bce099bc120
-  source_path: reference/session-management-compaction.md
-  workflow: 15
----
-
-# 会话管理与压缩（深入了解）
-
-本文档解释 Symi 如何端到端管理会话：
-
-- **会话路由**（入站消息如何映射到 `sessionKey`）
-- **会话存储**（`sessions.json`）及其跟踪的内容
-- **记录持久化**（`*.jsonl`）及其结构
-- **记录清理**（运行前的提供商特定修复）
-- **上下文限制**（上下文窗口 vs 跟踪的 token 数）
-- **压缩**（手动 + 自动压缩）以及在何处挂接压缩前工作
-- **静默内务处理**（例如不应产生用户可见输出的记忆写入）
-
-如果你想先了解更高层次的概述，请从以下内容开始：
-
-- [/concepts/session](/concepts/session)
-- [/concepts/compaction](/concepts/compaction)
-- [/concepts/session-pruning](/concepts/session-pruning)
-- [/reference/transcript-hygiene](/reference/transcript-hygiene)
-
----
-
-## 事实来源：Gateway 网关
-
-Symi 围绕一个拥有会话状态的单一 **Gateway 网关进程**设计。
-
-- UI（macOS 应用、web 控制 UI、TUI）应该向 Gateway 网关查询会话列表和 token 计数。
-- 在远程模式下，会话文件在远程主机上；"检查你的本地 Mac 文件"不会反映 Gateway 网关正在使用的内容。
-
----
-
-## 两个持久化层
-
-Symi 在两个层中持久化会话：
-
-1. **会话存储（`sessions.json`）**
-   - 键/值映射：`sessionKey -> SessionEntry`
-   - 小型、可变、可安全编辑（或删除条目）
-   - 跟踪会话元数据（当前会话 ID、最后活动时间、开关、token 计数器等）
-
-2. **记录（`<sessionId>.jsonl`）**
-   - 具有树形结构的仅追加记录（条目有 `id` + `parentId`）
-   - 存储实际对话 + 工具调用 + 压缩摘要
-   - 用于为后续回合重建模型上下文
-
----
-
-## 磁盘上的位置
-
-在 Gateway 网关主机上，每个智能体：
-
-- 存储：`~/.symi/agents/<agentId>/sessions/sessions.json`
-- 记录：`~/.symi/agents/<agentId>/sessions/<sessionId>.jsonl`
-  - Telegram 话题会话：`.../<sessionId>-topic-<threadId>.jsonl`
-
-Symi 通过 `src/config/sessions.ts` 解析这些位置。
-
----
-
-## 会话键（`sessionKey`）
-
-`sessionKey` 标识你所在的*哪个对话桶*（路由 + 隔离）。
-
-常见模式：
-
-- 主要/直接聊天（每个智能体）：`agent:<agentId>:<mainKey>`（默认 `main`）
-- 群组：`agent:<agentId>:<channel>:group:<id>`
-- 定时任务：`cron:<job.id>`
-- Webhook：`hook:<uuid>`（除非被覆盖）
-
-规范规则记录在 [/concepts/session](/concepts/session)。
-
----
-
-## 会话 ID（`sessionId`）
-
-每个 `sessionKey` 指向一个当前的 `sessionId`（继续对话的记录文件）。
-
-经验法则：
-
-- **重置**（`/new`、`/reset`）为该 `sessionKey` 创建一个新的 `sessionId`。
-- **每日重置**（默认 Gateway 网关主机本地时间凌晨 4:00）在重置边界后的下一条消息时创建一个新的 `sessionId`。
-- **空闲过期**（`session.reset.idleMinutes` 或旧版 `session.idleMinutes`）当消息在空闲窗口后到达时创建一个新的 `sessionId`。当同时配置了每日和空闲时，以先过期者为准。
-
-实现细节：决策发生在 `src/auto-reply/reply/session.ts` 的 `initSessionState()` 中。
-
----
-
-## 会话存储模式（`sessions.json`）
-
-存储的值类型是 `src/config/sessions.ts` 中的 `SessionEntry`。
-
-关键字段（不完整）：
-
-- `sessionId`：当前记录 ID（文件名从此派生，除非设置了 `sessionFile`）
-- `updatedAt`：最后活动时间戳
-- `sessionFile`：可选的显式记录路径覆盖
-- `chatType`：`direct | group | room`（帮助 UI 和发送策略）
-- `provider`、`subject`、`room`、`space`、`displayName`：群组/频道标签的元数据
-- 开关：
-  - `thinkingLevel`、`verboseLevel`、`reasoningLevel`、`elevatedLevel`
-  - `sendPolicy`（每会话覆盖）
-- 模型选择：
-  - `providerOverride`、`modelOverride`、`authProfileOverride`
-- Token 计数器（尽力而为/依赖提供商）：
-  - `inputTokens`、`outputTokens`、`totalTokens`、`contextTokens`
-- `compactionCount`：此会话键完成自动压缩的次数
-- `memoryFlushAt`：最后一次压缩前记忆刷新的时间戳
-- `memoryFlushCompactionCount`：最后一次刷新运行时的压缩计数
-
-存储可以安全编辑，但 Gateway 网关是权威：它可能会在会话运行时重写或重新水合条目。
-
----
-
-## 记录结构（`*.jsonl`）
-
-记录由 `@mariozechner/pi-coding-agent` 的 `SessionManager` 管理。
-
-文件是 JSONL 格式：
-
-- 第一行：会话头（`type: "session"`，包括 `id`、`cwd`、`timestamp`、可选的 `parentSession`）
-- 然后：带有 `id` + `parentId` 的会话条目（树形结构）
-
-值得注意的条目类型：
-
-- `message`：用户/助手/工具结果消息
-- `custom_message`：扩展注入的消息，*确实*进入模型上下文（可以从 UI 隐藏）
-- `custom`：*不*进入模型上下文的扩展状态
-- `compaction`：持久化的压缩摘要，带有 `firstKeptEntryId` 和 `tokensBefore`
-- `branch_summary`：导航树分支时的持久化摘要
-
-Symi 有意**不**"修复"记录；Gateway 网关使用 `SessionManager` 来读/写它们。
-
----
-
-## 上下文窗口 vs 跟踪的 token
-
-两个不同的概念很重要：
-
-1. **模型上下文窗口**：每个模型的硬上限（模型可见的 token）
-2. **会话存储计数器**：写入 `sessions.json` 的滚动统计（用于 /status 和仪表板）
-
-如果你在调整限制：
-
-- 上下文窗口来自模型目录（可以通过配置覆盖）。
-- 存储中的 `contextTokens` 是运行时估计/报告值；不要将其视为严格保证。
-
-更多信息，参见 [/token-use](/reference/token-use)。
-
----
-
-## 压缩：它是什么
-
-压缩将较旧的对话总结为记录中的持久化 `compaction` 条目，并保持最近的消息不变。
-
-压缩后，未来的回合会看到：
-
-- 压缩摘要
-- `firstKeptEntryId` 之后的消息
-
-压缩是**持久化的**（与会话修剪不同）。参见 [/concepts/session-pruning](/concepts/session-pruning)。
-
----
-
-## 自动压缩何时发生（Pi 运行时）
-
-在嵌入式 Pi 智能体中，自动压缩在两种情况下触发：
-
-1. **溢出恢复**：模型返回上下文溢出错误 → 压缩 → 重试。
-2. **阈值维护**：在成功的回合后，当：
-
-`contextTokens > contextWindow - reserveTokens`
-
-其中：
-
-- `contextWindow` 是模型的上下文窗口
-- `reserveTokens` 是为提示 + 下一个模型输出保留的空间
-
-这些是 Pi 运行时语义（Symi 消费事件，但 Pi 决定何时压缩）。
-
----
-
-## 压缩设置（`reserveTokens`、`keepRecentTokens`）
-
-Pi 的压缩设置位于 Pi 设置中：
-
-```json5
-{
-  compaction: {
-    enabled: true,
-    reserveTokens: 16384,
-    keepRecentTokens: 20000,
-  },
-}
-```
-
-Symi 还为嵌入式运行强制执行安全下限：
-
-- 如果 `compaction.reserveTokens < reserveTokensFloor`，Symi 会提升它。
-- 默认下限是 `20000` 个 token。
-- 设置 `agents.defaults.compaction.reserveTokensFloor: 0` 以禁用下限。
-- 如果它已经更高，Symi 不会改变它。
-
-原因：为压缩变得不可避免之前的多回合"内务处理"（如记忆写入）留出足够的空间。
-
-实现：`src/agents/pi-settings.ts` 中的 `ensurePiCompactionReserveTokens()`（从 `src/agents/pi-embedded-runner.ts` 调用）。
-
----
-
-## 用户可见的界面
-
-你可以通过以下方式观察压缩和会话状态：
-
-- `/status`（在任何聊天会话中）
-- `symi status`（CLI）
-- `symi sessions` / `sessions --json`
-- 详细模式：`🧹 Auto-compaction complete` + 压缩计数
-
----
-
-## 静默内务处理（`NO_REPLY`）
-
-Symi 支持用于后台任务的"静默"回合，用户不应该看到中间输出。
-
-约定：
-
-- 助手以 `NO_REPLY` 开始其输出，表示"不要向用户发送回复"。
-- Symi 在投递层剥离/抑制此内容。
-
-从 `2026.1.10` 开始，当部分块以 `NO_REPLY` 开头时，Symi 还会抑制**草稿/打字流式输出**，因此静默操作不会在回合中途泄漏部分输出。
-
----
-
-## 压缩前"记忆刷新"（已实现）
-
-目标：在自动压缩发生之前，运行一个静默的智能体回合，将持久状态写入磁盘（例如智能体工作空间中的 `memory/YYYY-MM-DD.md`），这样压缩就不会擦除关键上下文。
-
-Symi 使用**预阈值刷新**方法：
-
-1. 监控会话上下文使用情况。
-2. 当它越过"软阈值"（低于 Pi 的压缩阈值）时，向智能体运行一个静默的"现在写入记忆"指令。
-3. 使用 `NO_REPLY` 以便用户看不到任何内容。
-
-配置（`agents.defaults.compaction.memoryFlush`）：
-
-- `enabled`（默认：`true`）
-- `softThresholdTokens`（默认：`4000`）
-- `prompt`（刷新回合的用户消息）
-- `systemPrompt`（为刷新回合附加的额外系统提示）
-
-说明：
-
-- 默认的提示/系统提示包含 `NO_REPLY` 提示以抑制投递。
-- 刷新每个压缩周期运行一次（在 `sessions.json` 中跟踪）。
-- 刷新仅对嵌入式 Pi 会话运行（CLI 后端跳过它）。
-- 当会话工作空间是只读时（`workspaceAccess: "ro"` 或 `"none"`），刷新会被跳过。
-- 参见[记忆](/concepts/memory)了解工作空间文件布局和写入模式。
-
-Pi 还在扩展 API 中公开了 `session_before_compact` 钩子，但 Symi 的刷新逻辑目前位于 Gateway 网关端。
-
----
-
-## 故障排除检查清单
-
-- 会话键错误？从 [/concepts/session](/concepts/session) 开始，并在 `/status` 中确认 `sessionKey`。
-- 存储 vs 记录不匹配？从 `symi status` 确认 Gateway 网关主机和存储路径。
-- 压缩过于频繁？检查：
-  - 模型上下文窗口（太小）
-  - 压缩设置（`reserveTokens` 对于模型窗口来说太高会导致更早的压缩）
-  - 工具结果膨胀：启用/调整会话修剪
-- 静默回合泄漏？确认回复以 `NO_REPLY`（精确 token）开头，并且你使用的构建版本包含流式输出抑制修复。