# 服务子系统设计 — 总览

> **所属项目**: free-code .NET 10 重写
> **文档类型**: 模块索引
> **对应源码**: `../../src/services/oauth/`, `../../src/utils/memory/`, `../../src/voice/`
> **配套文档**: [总体概述](../总体概述与技术选型/总体概述与技术选型.md) | [核心模块设计](../核心模块设计/核心模块设计.md) | [基础设施设计](../基础设施设计/基础设施设计.md)

---

## 概述

服务子系统层封装了 free-code 运行时所需的各类横切关注点，包括身份认证、会话记忆、语音输入、通知推送、速率限制跟踪和同伴系统。这一层不直接参与 LLM 查询主路径，而是为核心模块和 UI 层提供基础能力。

原始 TypeScript 实现中，这些服务分散于 `../../src/services/oauth/`、`../../src/utils/memory/`、`../../src/voice/`、`../../src/buddy/` 等多个目录。.NET 10 重写将其整理为三个职责清晰的文档，每个服务通过接口向上层暴露，内部实现完全封装。

---

## 架构概览

```
服务子系统
    │
    ├── IAuthService                认证与 OAuth（Anthropic + Codex）
    │       └── ISecureTokenStorage   Keychain / 跨平台安全存储
    │
    ├── ISessionMemoryService       会话记忆提取（阈值触发）
    │       └── IAutoDreamService     后台记忆合并（24h / 会话数触发）
    │               └── ITeamMemorySyncService  团队记忆 Git 同步
    │
    └── 其他服务
            ├── IRemoteSessionManager  远程会话管理
            ├── IVoiceService          语音输入（push-to-talk）
            ├── INotificationService   终端通知（iTerm2 / Kitty / Ghostty）
            ├── IRateLimitService      API 速率限制跟踪
            └── ICompanionService      同伴系统（确定性 ASCII 宠物）
```

---

## 子模块列表

### [认证与 OAuth](服务子系统设计-认证与OAuth.md)

覆盖 `IAuthService` 接口、`AuthService` 实现（Anthropic 和 Codex OAuth 流程），以及 `ISecureTokenStorage` 与 macOS Keychain 的集成。

- 原始源码: `../../src/services/oauth/`
- 核心类型: `IAuthService`、`AuthService`、`ISecureTokenStorage`、`KeychainTokenStorage`

---

### [会话记忆与上下文](服务子系统设计-会话记忆与上下文.md)

覆盖 `ISessionMemoryService` 的阈值触发提取机制、`IAutoDreamService` 的后台记忆合并循环，以及 `ITeamMemorySyncService` 的 Git 推拉与秘密扫描流程。

- 原始源码: `../../src/utils/memory/`
- 核心类型: `ISessionMemoryService`、`SessionMemoryService`、`IAutoDreamService`、`AutoDreamService`、`ITeamMemorySyncService`、`TeamMemorySyncService`

---

### [其他服务子系统](服务子系统设计-其他服务子系统.md)

覆盖远程会话、语音输入、终端通知、API 速率限制跟踪和同伴（Buddy）系统的完整接口与实现设计。

- 原始源码: `../../src/voice/`、`../../src/buddy/`、notification 系统、rate limit 头解析
- 核心类型: `IRemoteSessionManager`、`IVoiceService`、`INotificationService`、`IRateLimitService`、`ICompanionService`

---

## 关键设计决策

**接口驱动的安全存储**

原始 TypeScript 代码直接调用 Keychain 命令行工具，与平台深度耦合。.NET 重写通过 `ISecureTokenStorage` 接口隔离平台细节，macOS 使用 `KeychainTokenStorage`，其他平台可替换为 DPAPI 或 Secret Service 实现，不影响上层逻辑。

**记忆提取采用轻量模型**

`SessionMemoryService` 和 `AutoDreamService` 均使用 `claude-haiku-4-5` 执行提取和合并，而非主会话使用的 Opus/Sonnet 模型。这样既控制了成本，又不阻塞主查询路径（记忆操作在后台异步完成）。

**团队记忆的秘密扫描门控**

`TeamMemorySyncService.PushAsync` 在提交到 Git 之前强制扫描变更内容，任何检测到 API key 或密码模式的内容都会中止推送并抛出异常，防止意外泄露敏感信息。

**同伴生成的确定性保证**

`CompanionService` 使用 `HashString(userId + "friend-2026-401")` 作为种子，通过 Mulberry32 PRNG 生成同伴属性。相同的 userId 永远产生相同的同伴，确保用户在不同设备或重装后看到同一只宠物。

---

## 参考资料

- [原始代码映射 — 服务子系统](reference/原始代码映射-服务子系统.md)
- [核心模块设计 — 查询引擎](../核心模块设计/核心模块设计-查询引擎-QueryEngine.md)
- [基础设施设计 — 后台任务管理](../基础设施设计/基础设施设计-后台任务管理.md)