Familiar v3.0.0

Familiar v3.0.0

中文 | English

中文

主要功能与修复

• 新增创意工坊独立窗口，可从设置页侧边栏或素材包管理区打开。支持新建素材包、编辑自定义包，以及复制内置包后改编。
• 可为各状态选择或拖入 PNG、APNG、GIF、WebP、SVG 图片；点击状态行即可预览，预览保持原始宽高比。只有名称和 idle 图片为必填项，素材包标识符由应用自动生成。
• 保存前校验图片和素材包大小、格式与路径；编辑已有自定义包时保留本地备份。保存后刷新素材列表和正在使用的桌宠。支持删除自定义包及导出已保存作品为 .fpack。
• 切换素材包或关闭有未保存改动的工坊窗口时，在窗口内确认，避免阻塞其他窗口。补齐中英文界面文案，并使工坊配色与设置面板一致。

兼容性与配置迁移

• 版本元数据升级至 3.0.0。现有素材包仍使用 pack.json Format Version 1 和 .fpack 格式，无需迁移；现有配置和 Hook 安装不需要更改。
• 内置素材包仍可直接使用，但须复制为自定义包后才能在工坊修改。

隐私影响

• 工坊在本机读取、保存和导出图片，不上传素材，也不新增遥测或远程服务。

支持的平台与架构

• macOS Apple Silicon（arm64）与 Intel（x86_64）桌面包。
• Linux x86_64 deb 与 AppImage；桌面运行需要发行版提供 Tauri/WebKitGTK 依赖。
• Windows x86_64 NSIS 安装包。
• familiar-cli serve 可在上述平台运行。

签名与公证状态

• macOS 使用 CI 配置的 ad-hoc 签名标识，不提供 Apple Developer ID 签名或公证；Gatekeeper 可能要求首次手动允许。
• Windows 安装包未配置代码签名；SmartScreen 可能要求首次安装手动确认。
• Linux deb/AppImage 未由发行版渠道签名。

性能数据

本版本未建立新的可复现端到端性能基线，不宣称量化性能变化。

---

English

Major features and fixes

• Add a separate Creative Workshop window, accessible from the settings sidebar and pack management area. Create packs, edit custom packs, or make an editable copy of a built-in pack.
• Choose or drop PNG, APNG, GIF, WebP, and SVG images for each state. Click a state to preview it at its original aspect ratio. Only the name and idle image are required; the app generates pack identifiers.
• Validate image and pack sizes, formats, and paths before saving. Keep a local backup when editing a custom pack. Saving refreshes the pack list and active desktop pet. Custom packs can be deleted, and saved work can be exported as .fpack.
• Confirm unsaved changes inside the workshop window when switching packs or closing it, without blocking other windows. Add Chinese and English UI text and align workshop colors with the settings panel.

Compatibility and configuration migration

• Version metadata is upgraded to 3.0.0. Existing packs still use pack.json Format Version 1 and the .fpack format; no migration is needed. Existing configuration and Hook installations do not need changes.
• Built-in packs remain usable as before, but must be copied before editing in the workshop.

Privacy impact

• The workshop reads, saves, and exports images locally. It adds no asset uploads, telemetry, or remote service.

Supported platforms and architectures

• macOS desktop bundles for Apple Silicon (arm64) and Intel (x86_64).
• Linux x86_64 deb and AppImage packages; the desktop requires the distribution's Tauri/WebKitGTK dependencies.
• Windows x86_64 NSIS installer.
• familiar-cli serve can run on the platforms above.

Signing and notarization status

• macOS uses the ad-hoc signing identity configured in CI and is not signed with an Apple Developer ID or notarized; Gatekeeper may require manual approval on first launch.
• The Windows installer is not code-signed; SmartScreen may require manual confirmation on first install.
• Linux deb/AppImage artifacts are not signed by a distribution channel.

Performance data

No new reproducible end-to-end performance baseline was established for this release, and no quantified performance change is claimed.

Familiar v2.4.1

Multi-platform bundles generated from v2.4.1. Review platform signing status and checksums before publishing this draft.

Familiar v2.4.0

Familiar v2.4.0

中文 | English

中文

主要功能与修复

• 新增不可见的 SessionStarted 内部事件：各 Agent 的 SessionStart 不再创建或刷新可见 Agent、宠物状态、气泡或图标。
• 将用户提交消息作为可感知生命周期的起点：UserPromptSubmit 之后继续展示思考、工作、等待、完成或失败状态。
• 新增 Agent Hook → 宠物状态 → 气泡状态矩阵文档，覆盖 Claude Code、Codex、Antigravity、Qoder 和 DeepSeek Harness。
• Hook 面板预览与后端行为保持一致，SessionStart 显示为“保持当前气泡和图标”。

兼容性与配置迁移

• 版本元数据升级至 2.4.0。
• 不新增或修改用户配置字段，无需手动迁移配置。
• 现有 Agent Hook 配置结构保持兼容；SessionStart 仍会被接收，但仅作为不可见的会话初始化信号处理。
• 现有 event_status_map 配置保持兼容；SessionStarted 不作为可配置的可见状态，用户提交消息仍使用 AgentStarted 的原有映射。

隐私影响

• 不新增遥测、网络上报或远程数据采集。
• SessionStart 不再把会话初始化信息提升为可见 Agent 或气泡，减少本地 UI 暴露的非必要会话信息。

支持的平台与架构

• macOS Apple Silicon（arm64）与 Intel（x86_64）桌面包。
• Linux x86_64 deb 与 AppImage；桌面运行需要发行版提供 Tauri/WebKitGTK 依赖。
• Windows x86_64 NSIS 安装包。
• familiar-cli serve 可在上述平台运行。

签名与公证状态

• macOS 使用 CI 配置的 ad-hoc 签名标识，不提供 Apple Developer ID 签名或公证；Gatekeeper 可能要求首次手动允许。
• Windows 安装包未配置代码签名；SmartScreen 可能要求首次安装手动确认。
• Linux deb/AppImage 未由发行版渠道签名。

性能数据

本版本未建立新的可复现端到端性能基线，不宣称量化性能变化。

---

English

Major features and fixes

• Added an invisible SessionStarted internal event: an Agent SessionStart no longer creates or refreshes a visible Agent, desktop-pet state, bubble, or icon.
• Made the user's submitted message the start of the observable lifecycle: after UserPromptSubmit, thinking, working, waiting, completion, and failure states continue to be shown as before.
• Added an Agent Hook → pet state → bubble state matrix covering Claude Code, Codex, Antigravity, Qoder, and DeepSeek Harness.
• Aligned the Hook panel preview with backend behavior; SessionStart is shown as “Keep current bubble and icon”.

Compatibility and configuration migration

• Version metadata is upgraded to 2.4.0.
• No user configuration fields are added or changed, so no manual migration is required.
• Existing Agent Hook configuration structures remain compatible; SessionStart is still accepted but is handled only as an invisible session-initialization signal.
• Existing event_status_map configuration remains compatible; SessionStarted is not exposed as a configurable visible state, while user prompts continue to use the existing AgentStarted mapping.

Privacy impact

• No telemetry, network reporting, or remote data collection is added.
• SessionStart no longer promotes session initialization into a visible Agent or bubble, reducing unnecessary session information exposed in the local UI.

Supported platforms and architectures

• macOS desktop bundles for Apple Silicon (arm64) and Intel (x86_64).
• Linux x86_64 deb and AppImage packages; the desktop requires the distribution's Tauri/WebKitGTK dependencies.
• Windows x86_64 NSIS installer.
• familiar-cli serve can run on the platforms above.

Signing and notarization status

• macOS uses the ad-hoc signing identity configured in CI and is not signed with an Apple Developer ID or notarized; Gatekeeper may require manual approval on first launch.
• The Windows installer is not code-signed; SmartScreen may require manual confirmation on first install.
• Linux deb/AppImage artifacts are not signed by a distribution channel.

Performance data

No new reproducible end-to-end performance baseline was established for this release, and no quantified performance change is claimed.

Familiar v2.3.0

Multi-platform bundles generated from v2.3.0. Review platform signing status and checksums before publishing this draft.

Familiar v2.2.2

Multi-platform bundles generated from v2.2.2. Review platform signing status and checksums before publishing this draft.

Familiar v2.2.1

Familiar v2.2.1

中文 | English

中文

主要功能与修复

• 修复 macOS 创建的 .fpack 包含 __MACOSX 元数据目录时无法导入的问题，并拒绝含多个素材清单的歧义压缩包。
• 修复用户导入素材与内置素材 ID 相同时错误使用内置版本的问题；用户素材现在按设计优先，并通过资源修订号及时失效 WebView 缓存。
• 启用 Tauri 本地素材 asset protocol，仅授权 Familiar 的用户素材目录，修复花卷、豆花等自定义素材图片无法加载的问题。
• 覆盖导入当前正在使用的素材包后，桌宠会立即重新加载，无需切换素材或重启。
• 素材管理新增用户导入素材删除功能：内置素材不可删除，当前使用的素材需先切换，删除采用两次点击确认并带路径穿越防护。
• 移除内置豆花素材，使用新版花卷图片替换内置花卷并同步更新分发用 .fpack。
• 精简素材卡片文案和操作：移除冗长描述后缀，“使用此素材包”简化为“使用”，预览动作改为图标按钮。

兼容性与配置迁移

• 不新增或修改用户配置字段，无需手动迁移配置。
• 如果现有配置选择了已移除的内置豆花且用户目录也没有豆花包，应用会沿用现有素材缺失回退逻辑选择可用内置素材。
• 用户导入素材仍存放在平台约定的 Familiar 素材目录；macOS/Linux 为 ~/.config/familiar/sprites，Windows 为应用数据目录下的 familiar/sprites。
• 自定义素材删除仅允许单层素材 ID，不能访问素材目录之外的路径。

隐私影响

• 不新增遥测、网络上报或数据采集。
• Tauri asset protocol 仅允许 WebView 读取 Familiar 用户素材目录，不开放 Home、文档或其他个人目录。
• 素材导入、缓存修订、刷新和删除均在本地完成。

支持的平台与架构

• macOS Apple Silicon（arm64）与 Intel（x86_64）桌面包。
• Linux x86_64 deb 与 AppImage；桌面运行需要发行版提供 Tauri/WebKitGTK 依赖。
• Windows x86_64 NSIS 安装包；Windows 本地 Hook 使用 loopback TCP。
• familiar-cli serve 可在上述平台运行。

签名与公证状态

• macOS 使用 CI 配置的 ad-hoc 签名标识，不提供 Apple Developer ID 签名或公证；Gatekeeper 可能要求首次手动允许。
• Windows 安装包未配置代码签名；SmartScreen 可能要求首次安装手动确认。
• Linux deb/AppImage 未由发行版渠道签名。

性能数据

本版本未建立新的可复现端到端性能基线，不宣称量化性能变化。

---

English

Major features and fixes

• Fixed imports of .fpack archives created on macOS when they contain a __MACOSX metadata directory, and reject ambiguous archives containing multiple pack manifests.
• Fixed user-imported packs being shadowed by bundled packs with the same ID. User packs now take precedence as designed, with asset revisions invalidating stale WebView caches.
• Enabled Tauri's local asset protocol with a narrow scope limited to Familiar's user sprite directories, fixing failed custom images such as Huajuan and Douhua.
• Re-importing the currently active pack now reloads the desktop pet immediately without switching packs or restarting.
• Added deletion for user-imported packs. Bundled packs cannot be deleted, active packs must be switched first, deletion uses two-click confirmation, and path traversal is rejected.
• Removed the bundled Douhua pack, replaced bundled Huajuan artwork with the new version, and synchronized the distributable .fpack archive.
• Simplified pack-card copy and controls by removing the verbose description suffix, shortening the use action, and making preview an icon-only button.

Compatibility and configuration migration

• No user configuration fields are added or changed; no manual configuration migration is required.
• If an existing configuration selects the removed bundled Douhua pack and no user-imported Douhua pack exists, the existing missing-pack fallback selects an available bundled pack.
• Imported packs remain under Familiar's platform-specific sprite directory: ~/.config/familiar/sprites on macOS/Linux and familiar/sprites under the application data directory on Windows.
• Custom-pack deletion only accepts a single pack ID and cannot access paths outside the sprite directory.

Privacy impact

• No telemetry, network reporting, or data collection is added.
• Tauri's asset protocol only allows the WebView to read Familiar's user sprite directory; Home, Documents, and other personal directories are not exposed.
• Pack import, cache revision, reload, and deletion all run locally.

Supported platforms and architectures

• macOS desktop bundles for Apple Silicon (arm64) and Intel (x86_64).
• Linux x86_64 deb and AppImage packages; the desktop requires the distribution's Tauri/WebKitGTK dependencies.
• Windows x86_64 NSIS installer; Windows local Hook ingest uses loopback TCP.
• familiar-cli serve can run on the platforms above.

Signing and notarization status

• macOS uses the ad-hoc signing identity configured in CI and is not signed with an Apple Developer ID or notarized; Gatekeeper may require manual approval on first launch.
• The Windows installer is not code-signed; SmartScreen may require manual confirmation on first install.
• Linux deb/AppImage artifacts are not signed by a distribution channel.

Performance data

No new reproducible end-to-end performance baseline was established for this release, and no quantified performance change is claimed.

Familiar v2.2.0

Familiar v2.2.0

中文 | English

中文

主要功能与修复

• 重构 macOS 桌宠鼠标穿透：左键可操作后方窗口，开启穿透时仍可通过右键打开桌宠菜单，并可直接在菜单中切换穿透状态。
• 新增悬停透明度、屏幕边缘吸附和拖拽可见区域约束；桌宠位置按显示器工作区比例保存，在分辨率、显示器或内容尺寸变化后保持稳定。
• 加固右键菜单布局：靠近屏幕边缘时自动扩展透明窗口并限制在工作区内，空闲 5 秒后自动关闭。
• 新增本地与远程两种首次启动引导路径，改进连接反馈、输入焦点和 Hook 设置状态展示。
• 更新中英文 README 与官网，展示不同编码 Agent 驱动桌宠状态变化的工作方式。
• 新增 scripts/install-macos.sh，支持从 origin/main 更新安装，或使用 --local 构建、安装并启动当前工作区版本。

兼容性与配置迁移

• 新增 renderer.desktop-pet.hover_opacity，旧配置缺失时默认使用 0.35。
• 新增 renderer.desktop-pet.snap_to_corner 与 snap_threshold，旧配置缺失时分别默认使用 true 和 60.0。
• 桌宠拖拽位置会逐步保存为 rel:rx,ry；原有命名锚点和绝对像素位置仍可读取，无需手动迁移。
• macOS 桌宠新增 block 依赖；Windows 和 Linux 保留原有鼠标事件处理路径。
• 未改变 Hook 协议、远程订阅协议或默认本地运行模式。

隐私影响

• 不新增遥测、远程上报或用户数据采集。
• 鼠标位置检测、窗口吸附、位置保存和右键菜单处理均在本地完成，不会发送指针位置、窗口内容、提示词或 Hook 数据。
• 官网素材与引导页更新不改变运行时网络行为。

支持的平台与架构

• macOS Apple Silicon（arm64）与 Intel（x86_64）桌面包。
• Linux x86_64 deb 与 AppImage；桌面运行需要发行版提供 Tauri/WebKitGTK 依赖。
• Windows x86_64 NSIS 安装包；Windows 本地 Hook 使用 loopback TCP。
• familiar-cli serve 可在上述平台运行。

签名与公证状态

• macOS 使用 CI 配置的 ad-hoc 签名标识，不提供 Apple Developer ID 签名或公证；Gatekeeper 可能要求首次手动允许。
• Windows 安装包未配置代码签名；SmartScreen 可能要求首次安装手动确认。
• Linux deb/AppImage 未由发行版渠道签名。

性能数据

本版本未建立新的可复现端到端性能基线，不宣称量化性能变化。

---

English

Major features and fixes

• Reworked macOS desktop-pet click-through so left clicks reach windows behind the pet while right-click still opens the pet menu; click-through can also be toggled directly from that menu.
• Added hover opacity, screen-edge snapping, and visible-work-area drag constraints. Pet positions are persisted relative to the monitor work area so they remain stable across resolution, monitor, and content-size changes.
• Hardened context-menu layout by expanding the transparent window near screen edges, clamping the menu to the work area, and closing it after five idle seconds.
• Added separate local and remote onboarding paths with clearer connection feedback, input focus, and Hook setup status.
• Refreshed the English and Chinese READMEs and website to demonstrate how different coding agents drive pet states.
• Added scripts/install-macos.sh for updating from origin/main, or building, installing, and launching the current workspace with --local.

Compatibility and configuration migration

• Added renderer.desktop-pet.hover_opacity, defaulting to 0.35 when absent from older configurations.
• Added renderer.desktop-pet.snap_to_corner and snap_threshold, defaulting to true and 60.0 respectively when absent.
• Dragged pet positions are progressively stored as rel:rx,ry; existing named anchors and absolute pixel positions remain readable, so no manual migration is required.
• The macOS desktop app adds the block dependency; Windows and Linux retain their existing mouse-event paths.
• Hook protocols, the remote subscription protocol, and the default local runtime mode are unchanged.

Privacy impact

• No telemetry, remote reporting, or user-data collection is added.
• Pointer detection, window snapping, position persistence, and context-menu handling run locally and do not transmit pointer positions, window contents, prompts, or Hook payloads.
• Website assets and onboarding updates do not change runtime network behavior.

Supported platforms and architectures

• macOS desktop bundles for Apple Silicon (arm64) and Intel (x86_64).
• Linux x86_64 deb and AppImage packages; the desktop requires the distribution's Tauri/WebKitGTK dependencies.
• Windows x86_64 NSIS installer; Windows local Hook ingest uses loopback TCP.
• familiar-cli serve can run on the platforms above.

Signing and notarization status

• macOS uses the ad-hoc signing identity configured in CI and is not signed with an Apple Developer ID or notarized; Gatekeeper may require manual approval on first launch.
• The Windows installer is not code-signed; SmartScreen may require manual confirmation on first install.
• Linux deb/AppImage artifacts are not signed by a distribution channel.

Performance data

No new reproducible end-to-end performance baseline was established for this release, and no quantified performance change is claimed.

Familiar v2.1.1

Familiar v2.1.1

中文 | English

中文

主要更新

• 将默认的 AgentStarted 行为映射为 Idle（空闲），避免 Agent 刚启动时直接显示为工作中。
• 同步更新设置页事件映射表和 Hook 预览面板中的默认状态说明。

合并自 v2.1.0 的更新

• 新增「悬停时隐藏」设置，可在鼠标进入整个桌宠窗口时暂时隐藏窗口内容。
• 悬停隐藏覆盖桌宠、气泡、状态面板和远程模式标识，不改变窗口位置或尺寸。
• 设置项支持自动保存，并增加鼠标穿透依赖提示。
• 新增 renderer.desktop-pet.hide_on_hover 配置字段。

兼容性与配置迁移

• 仅调整未配置 event_status_map.AgentStarted 时的内置默认行为。
• 如果用户已在配置中显式设置 AgentStarted，该设置保持不变。
• 旧配置缺少 hide_on_hover 时默认值为 false，无需手动迁移。
• 要使用悬停隐藏，必须关闭「鼠标穿透」；鼠标穿透开启时系统不会向窗口发送悬停事件。
• 本版本不改变配置格式、远程订阅协议或默认部署模式。

隐私影响

• 不新增遥测、网络上报或数据采集行为。
• 该变更仅影响本地状态机和界面状态展示。
• 悬停检测与隐藏均在本地桌面端完成，不发送鼠标位置或窗口状态。

平台与架构

• macOS Apple Silicon（arm64）与 Intel（x86_64）桌面包。
• Linux x86_64 deb 与 AppImage；桌面运行需要发行版提供 Tauri/WebKitGTK 依赖。
• Windows x86_64 NSIS 安装包；Windows 本地 Hook 使用 loopback TCP。
• familiar-cli serve 可在上述平台运行。

签名与公证状态

• macOS 使用 CI 配置的 ad-hoc 签名标识，不提供 Apple Developer ID 签名或公证；Gatekeeper 可能要求首次手动允许。
• Windows 安装包未配置代码签名；SmartScreen 可能要求首次安装手动确认。
• Linux deb/AppImage 未由发行版渠道签名。

性能数据

本版本未建立新的可复现端到端性能基线，不宣称量化性能变化。

---

English

Highlights

• Changed the built-in default for AgentStarted to Idle, so a newly started Agent is not shown as working before activity begins.
• Synchronized the default status shown in the Settings event mapping table and Hook preview panel.

Updates merged from v2.1.0

• Added a Hide on Hover setting that temporarily hides the entire desktop window content when the pointer enters it.
• Hover hiding covers the pet, bubbles, statistics panel, and remote-mode indicator without changing the window position or size.
• Added auto-save support for the setting and a concise Click-Through dependency hint.
• Added the renderer.desktop-pet.hide_on_hover configuration field.

Compatibility and configuration migration

• Only the built-in behavior is changed when event_status_map.AgentStarted is not configured.
• An explicit user mapping for AgentStarted remains unchanged.
• Older configurations missing hide_on_hover default to false; no manual migration is required.
• Click-Through must be disabled for hover hiding because the operating system does not deliver hover events to an ignored window.
• This release does not change the configuration format, remote subscription protocol, or default deployment mode.

Privacy impact

• No telemetry, network reporting, or data collection behavior is added.
• The change only affects the local state machine and UI status presentation.
• Hover detection and hiding run entirely in the local desktop client; pointer coordinates and window state are not transmitted.

Platforms and architectures

• macOS desktop bundles for Apple Silicon (arm64) and Intel (x86_64).
• Linux x86_64 deb and AppImage packages; the desktop requires the distribution's Tauri/WebKitGTK dependencies.
• Windows x86_64 NSIS installer; Windows local Hook ingest uses loopback TCP.
• familiar-cli serve can run on the platforms above.

Signing and notarization status

• macOS uses the ad-hoc signing identity configured in CI and is not signed with an Apple Developer ID or notarized; Gatekeeper may require manual approval on first launch.
• The Windows installer is not code-signed; SmartScreen may require manual confirmation on first install.
• Linux deb/AppImage artifacts are not signed by a distribution channel.

Performance data

No new reproducible end-to-end performance baseline was established for this release, and no quantified performance change is claimed.

Familiar v2.0.1

Familiar v2.0.1

中文 | English

中文

本版本修复

• 修复 macOS Intel（x86_64）桌面包构建失败的问题：调用 Cocoa setFrame:display: 时使用平台正确的 Objective-C BOOL 常量。
• 版本号统一升级至 2.0.1。

自 v2.0.0 起的主要更新

• 本地一体化与远程订阅双模式：默认继续本地运行，也可以通过 [runtime].mode = "remote" 让桌面端只订阅远程服务端状态。
• State Stream：新增版本化 WebSocket 状态流，使用完整快照、latest-only 合并、初始快照、心跳、限频和断线重连。
• 职责分离：Tauri 本地端与 familiar-cli serve 共用 Hook ingest、事件解析和状态模型。
• 服务端能力：新增 familiar-cli serve --config、--bind，支持可配置 HTTP/HTTPS、状态摘要脱敏和优雅退出。
• 会话身份稳定性：事件 ID 与会话 ID 解耦，非 UUID 的 Agent conversation ID 也能稳定聚合。
• 桌面端提示：远程模式增加连接状态标识，并同步用户输入摘要、活动摘要、统计和来源信息。

兼容性与配置迁移

• 旧配置缺少 [runtime] 时仍默认为 local，无需迁移即可启动。
• headless CLI 子命令不再保留兼容别名；服务端统一使用 familiar-cli serve。
• Hook ingest 默认使用 19527，HTTP/WebSocket State Stream 默认使用 19528，避免端口职责冲突。
• 服务端可使用 familiar-cli serve --config /path/server.toml，Hook CLI 进程可通过 FAMILIAR_CONFIG 指定同一配置文件。
• 远程模式的 TLS、端点、重连和摘要长度配置位于 [remote]；服务端证书配置位于 [server.tls]。
• 本版本不改变配置格式、远程订阅协议或默认部署模式，无需额外迁移配置。

隐私影响

• 不新增遥测或默认外部上报。
• 原始 Hook payload、命令、文件内容和完整转录仍只在产生它们的服务端处理；State Stream 只发送版本化状态和经过长度限制的摘要。
• 远程模式下 Agent 统计来自服务端；CPU、内存和磁盘仪表仍读取本地桌面机器。
• TLS 和远程认证均由用户配置控制；本版本不包含设备身份、Token 轮换或凭证库集成。

平台与架构

• macOS Apple Silicon（arm64）与 Intel（x86_64）桌面包。
• Linux x86_64 deb 与 AppImage；桌面运行需要发行版提供 Tauri/WebKitGTK 依赖。
• Windows x86_64 NSIS 安装包；Windows 本地 Hook 仅使用 loopback TCP，不使用 Unix Domain Socket。
• familiar-cli serve 可在上述平台运行；TLS 构建仍应在目标平台 CI 上验证系统工具链和证书路径。

签名与公证状态

• macOS 使用 CI 配置的 ad-hoc 签名标识，不提供 Apple Developer ID 签名或公证；Gatekeeper 可能要求首次手动允许。
• Windows 安装包未配置代码签名；SmartScreen 可能要求首次安装手动确认。
• Linux deb/AppImage 未由发行版渠道签名。

性能数据

本版本主要为 macOS 构建兼容性修复，未建立新的可复现端到端性能基线，也不宣称量化性能变化。

---

English

Fixes in v2.0.1

• Fixed macOS Intel (x86_64) desktop bundle builds by passing Cocoa's platform-correct Objective-C BOOL constant to setFrame:display:.
• Unified the release version at 2.0.1.

Highlights since v2.0.0

• Local integrated and remote subscription modes: local mode remains the default, while [runtime].mode = "remote" lets the desktop shell subscribe to a remote server.
• State Stream: added a versioned WebSocket stream with complete snapshots, latest-only coalescing, an initial snapshot, heartbeat, rate limiting, and reconnect backoff.
• Separated responsibilities: the Tauri desktop and familiar-cli serve share Hook ingest, event parsing, and the state model.
• Server operation: added familiar-cli serve --config and --bind, configurable HTTP/HTTPS, sanitized state summaries, and graceful shutdown.
• Stable session identity: event IDs are separated from session IDs, so non-UUID Agent conversation IDs are still grouped consistently.
• Desktop status: remote mode shows connection status and synchronizes user-input summaries, activity summaries, statistics, and source counts.

Compatibility and configuration migration

• Missing [runtime] in an older configuration still defaults to local; no migration is required.
• The headless CLI command no longer has a compatibility alias; use familiar-cli serve for the server.
• Hook ingest defaults to 19527, while the HTTP/WebSocket State Stream defaults to 19528.
• Use familiar-cli serve --config /path/server.toml for an explicit server configuration; set FAMILIAR_CONFIG for Hook CLI processes that must use the same file.
• Remote TLS, endpoint, reconnect, and summary limits are configured under [remote]; server certificates are configured under [server.tls].
• This release does not change the configuration format, remote subscription protocol, or default deployment mode; no additional migration is required.

Privacy impact

• No telemetry or default external reporting is added.
• Raw Hook payloads, commands, file contents, and full transcripts remain processed only on the service that receives them; the State Stream sends versioned state and length-limited summaries.
• Agent statistics in remote mode come from the server; CPU, memory, and disk gauges continue to describe the local desktop machine.
• TLS and remote authentication remain user-configurable; device identity, token rotation, and credential-store integration are not included.

Platforms and architectures

• macOS desktop bundles for Apple Silicon (arm64) and Intel (x86_64).
• Linux x86_64 deb and AppImage packages; the desktop requires the distribution's Tauri/WebKitGTK dependencies.
• Windows x86_64 NSIS installer; Windows local Hook ingest uses loopback TCP and does not use Unix Domain Sockets.
• familiar-cli serve is intended to run on these platforms; TLS builds still require target-platform CI validation of the system toolchain and certificate paths.

Signing and notarization status

• macOS uses the ad-hoc signing identity configured in CI and is not signed with an Apple Developer ID or notarized; Gatekeeper may require manual approval on first launch.
• The Windows installer is not code-signed; SmartScreen may require manual confirmation on first install.
• Linux deb/AppImage artifacts are not signed by a distribution channel.

Performance data

This release is primarily a macOS build-compatibility fix. No new reproducible end-to-end performance baseline was established, and no quantified performance change is claimed.

Familiar v1.2.1

Familiar v1.2.1

中文 | English

中文

主要更新

• 气泡向上堆叠且宠物位置保持不变：桌面窗口调整尺寸时固定底边与水平中心，新增或移除任务气泡不再把宠物向下挤；macOS 使用原子窗口 Frame 更新，其他平台保留等价的锚定回退逻辑。
• 完整 Clippy 校验恢复通过：将 hooks trait 的测试模块移到生产代码之后，消除 items_after_test_module 告警；不改变运行时行为。
• 本地配置忽略规则：.gemini/ 加入 Git 忽略列表，避免本机 Agent 配置被误提交。

配置兼容性

• 无配置结构或序列化格式变更，现有配置文件与精灵包可直接沿用。
• 无需执行配置迁移；升级并重启 Familiar 即可生效。

隐私

本版本没有新增遥测、远程数据上报或外部服务。Prompt、转录、文件内容与 hook 载荷继续仅在本机采集、处理和显示。

平台与制品

• macOS Apple Silicon（arm64）DMG。
• Windows x86_64 NSIS 安装包。
• Linux x86_64 deb 与 AppImage。
• 本版本不提供 macOS Intel（x64）DMG：该构建在 CI 中发现平台绑定类型不兼容，因此未将失败或未经验证的产物纳入正式发布。
• 各制品的 SHA-256 校验和见 Release 附件 SHA256SUMS。

签名状态

• macOS 应用仅使用 ad-hoc 签名，未进行 Apple Developer ID 签名或公证；Gatekeeper 可能要求首次启动时手动允许。
• Windows 安装包未做代码签名，SmartScreen 可能要求首次安装时手动确认。
• Linux 安装包未经分发渠道签名。

性能数据

本版本修复窗口定位并整理测试模块，没有引入可量化的运行时性能目标，因此未声明性能提升。

---

English

Highlights

• Bubbles now stack upward without moving the pet: window resizing keeps the bottom edge and horizontal center fixed, so adding or removing task bubbles no longer pushes the pet downward. macOS applies the frame change atomically; other platforms retain an equivalent anchored fallback.
• Full Clippy validation restored: moved the hook trait test module after production items to eliminate the items_after_test_module warning, with no runtime behavior change.
• Local configuration ignore rule: added .gemini/ to Git ignores to prevent local agent configuration from being committed accidentally.

Configuration compatibility

• No configuration schema or serialization changes; existing configuration files and sprite packs remain compatible.
• No migration is required. Upgrade and restart Familiar to apply the fix.

Privacy

This release adds no telemetry, remote reporting, or external services. Prompts, transcripts, file contents, and hook payloads continue to be collected, processed, and displayed locally only.

Platforms and artifacts

• macOS DMG for Apple Silicon (arm64).
• Windows x86_64 NSIS installer.
• Linux x86_64 deb and AppImage.
• No macOS Intel (x64) DMG is included in this release: CI exposed a platform-binding type incompatibility, so a failed or unverified artifact is not being shipped.
• SHA-256 checksums for every artifact are available in the SHA256SUMS Release asset.

Signing status

• The macOS application is ad-hoc signed and is not signed with an Apple Developer ID or notarized. Gatekeeper may require manual approval on first launch.
• The Windows installer is not code-signed; SmartScreen may require manual confirmation on first install.
• The Linux packages are not signed by a distribution channel.

Performance data

This release fixes window positioning and reorganizes a test module. It has no quantified runtime performance target, so no performance improvement is claimed.