94 lines
4.6 KiB
Markdown
94 lines
4.6 KiB
Markdown
# 服务子系统设计 — 总览
|
||
|
||
> **所属项目**: 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)
|