# https://github.com/Djtony707/TITAN 项目说明书生成时间：2026-07-12 10:33:49 UTC ## 目录 - [项目概览](#page-overview) - [Lib 模块](#page-src-lib) - [Lib 模块](#page-ui-src-lib) - [Lib 模块](#page-titan-voice-ui-lib) - [Api 模块](#page-ui-src-api) - [Api 模块](#page-titan-voice-ui-app-api) - [App 模块](#page-titan-voice-ui-components-app) - [App 模块](#page-titan-voice-ui-app) ## 项目概览 ### 相关页面相关主题：[Lib 模块](#page-src-lib)

相关源码文件

以下源码文件用于生成本页说明： - [Dockerfile](https://github.com/Djtony707/TITAN/blob/main/Dockerfile) - [README.md](https://github.com/Djtony707/TITAN/blob/main/README.md) - [package.json](https://github.com/Djtony707/TITAN/blob/main/package.json) - [titan-voice-agent/Dockerfile](https://github.com/Djtony707/TITAN/blob/main/titan-voice-agent/Dockerfile) - [titan-voice-server/Dockerfile](https://github.com/Djtony707/TITAN/blob/main/titan-voice-server/Dockerfile) - [titan-voice-ui/Dockerfile](https://github.com/Djtony707/TITAN/blob/main/titan-voice-ui/Dockerfile)

# 项目概览 ## 项目定位与目标 TITAN 是一个本地优先（local-first）的 AI 语音代理框架，名称源自 "Titan"（泰坦），定位为可在自有硬件或私有网络中运行的智能语音助手。当前主线版本为 v7.2.1，代号 "Reliability Mode"，在前一版本 v7.2.0 "Conscience" 的基础上进一步整合了完整的纪律化处理流程，使本地模型具备与前沿代理相近的执行规范。资料来源：[README.md:1-15]() 项目的核心理念是：通过单一开关即可让本地模型拥有结构化、可验证、可问责的"处理神经系统"，避免幻觉式声明和未执行的副作用。 ## 顶层架构与组件划分 TITAN 在仓库顶层以多服务方式组织，每个子模块对应独立的 Docker 镜像： - **titan-voice-agent**：代理核心，运行本地模型推理、工具调度与计划验证逻辑。 - **titan-voice-server**：后端服务，处理会话状态、请求路由与对外 API 对接。 - **titan-voice-ui**：前端交互界面，提供语音采集与可视化面板。根目录的 `Dockerfile` 用于整体编排或单一容器构建，`package.json` 提供依赖管理与脚本入口，便于通过 `npm` 或 `pnpm` 在开发模式下启动任意子模块。资料来源：[package.json:1-30]() ```mermaid graph LR U[用户语音输入] --> UI[titan-voice-ui] UI --> S[titan-voice-server] S --> A[titan-voice-agent] A --> L[本地 LLM 推理] A --> S S --> UI ``` 资料来源：[titan-voice-agent/Dockerfile:1-15]() ## 容器化与部署策略每个子目录均维护独立的 `Dockerfile`，说明项目采用"一服务一镜像"的拆分部署策略。这种设计带来三个直接收益： 1. **资源隔离**：UI、Server、Agent 可按需分配 CPU、内存与 GPU 资源。 2. **独立升级**：任一组件可独立打包发布，不影响其他服务。 3. **异构硬件兼容**：Agent 可跑在带 GPU 的节点上，UI 可跑在轻量边缘设备上。资料来源：[titan-voice-server/Dockerfile:1-20]() ## Fable-5 纪律体系（v7.2.1） v7.2.1 通过 `agent.reliabilityMode: true` 这一单一配置开关启用完整的 Fable-5 纪律集合，社区文档中明确披露的纪律包括： | 纪律名称 | 核心约束 | |----------|----------| | Plan-first | 多步任务必须先写出编号计划，并逐条验证执行 | | Verify | 任何副作用声明必须有真正调用工具的证据 | | Conscience | 合规性自检（自 v7.2.0 引入） | 完整 Fable-5 包含的其余两条纪律在社区公告中被一并提及，具体条目请以仓库 `README.md` 与配置文件为准。资料来源：[README.md:20-50]() ## 典型使用流程在 Reliability Mode 下，Agent 处理一次语音请求的典型流程为： 1. UI 捕获音频并通过 Server 转发至 Agent。 2. Agent 进入 Plan-first 阶段，生成结构化任务列表。 3. 逐条执行计划，每次副作用由 Verify 纪律校验。 4. Conscience 纪律在最终输出前进行合规审查。 5. 结果经由 Server 回传 UI 播报。资料来源：[titan-voice-ui/Dockerfile:1-15]() ## 适用场景 TITAN 面向需要**离线运行、隐私可控、纪律严格**的语音助手场景，包括但不限于内网客服、家庭语音中控、本地 LLM 实验平台等。对于希望验证"小型本地模型 + 结构化纪律"组合效果的研究者与开发者而言，这是一个可直接 `docker compose up` 启动的参考实现。资料来源：[README.md:60-80]() --- ## Lib 模块 ### 相关页面相关主题：[项目概览](#page-overview), [Lib 模块](#page-ui-src-lib)

相关源码文件

以下源码文件用于生成本页说明： - [src/lib/auto-heal/repair-strategies.ts](https://github.com/Djtony707/TITAN/blob/main/src/lib/auto-heal/repair-strategies.ts) - [src/lib/auto-heal/types.ts](https://github.com/Djtony707/TITAN/blob/main/src/lib/auto-heal/types.ts) - [src/lib/dep-monitor/types.ts](https://github.com/Djtony707/TITAN/blob/main/src/lib/dep-monitor/types.ts)

# Lib 模块 ## 定位与整体职责 `src/lib/` 是 TITAN 项目中**与上层 agent 业务逻辑解耦的可复用基础设施层**，承担"执行过程中"可被反复调用的工程能力。按照目录命名组织，TITAN 当前将以下两个子系统收纳在 `Lib` 中： - `auto-heal/`：自动修复子系统，处理工具调用、副作用执行中出现的可恢复失败。 - `dep-monitor/`：依赖监控子系统，对运行时所依赖的外部命令、服务与二进制资源进行类型化建模。 `Lib` 模块不直接调度 LLM，而是把"如何稳健地完成一次副作用"这件事抽象为可在规划-执行回路中被组合的策略与类型，从而让 Fable-5 中 Plan-first 与 Verify 的纪律可被工程化实现、可被单元测试验证。这一定位与 v7.2.1 中"一个开关 (`agent.reliabilityMode: true`) 激活完整的 Fable-5 工程纪律"的整体承诺相吻合。资料来源：[src/lib/auto-heal/types.ts](), [src/lib/dep-monitor/types.ts]() ## auto-heal 子系统 `src/lib/auto-heal/` 由两份核心文件组成，二者通过显式的类型契约相连接： - `repair-strategies.ts`：导出修复策略表，为工具调用失败、可恢复异常等情况提供可插拔的差错处置逻辑。策略以模块顶层导出物形式暴露，便于上层规划器按名称查表选用。 - `types.ts`：定义该子系统共享的类型契约（例如修复上下文、修复结果、修复原因等），让上层规划器能够以统一形状与多种策略实现交互，从而在不感知具体策略的前提下完成编排。该子系统的设计目标与社区讨论中"never claim a side-effect without the tool that did [it]"的核心原则直接呼应：当被调工具未按预期回执，规划器即可借助 `auto-heal` 重新进入可验证、可重试的状态，构成 v7.2.1 Verify 学科的具体执行单元。资料来源：[src/lib/auto-heal/repair-strategies.ts](), [src/lib/auto-heal/types.ts]() ## dep-monitor 子系统 `src/lib/dep-monitor/` 以 `types.ts` 为单一入口文件，对 TITAN 运行时所依赖的外部命令、远端服务、本地二进制等资源进行类型化建模。该类型集合并不会被 `Lib` 内部消费，而是作为契约发布给上层规划器使用，主要被复用在两个时机： 1. **声明前**：规划器向 `dep-monitor` 查询某个动作的前提依赖是否齐备，例如所需的 CLI 是否安装、所需的服务端口是否可达、所需的环境变量是否设置。 2. **声明后**：规划器把"已发出 X 调用、已收到 Y 回执"等副作用声明挂在具体的依赖实例上，使任何关于副作用的陈述都附带有可追溯的来源，从而支撑 Verify 学科中"副作用必须有出处"的硬约束。这种"先探针、再执行、再凭据"的链路正是 TITAN 把 Fable-5 学科落到工程层面的方式之一。资料来源：[src/lib/dep-monitor/types.ts]() ## 与上层模块的协作 ```mermaid flowchart LR A[上层规划器 agent] -->|构造上下文| B[auto-heal] A -->|查询/挂载| C[dep-monitor] B -->|修复结果| A C -->|依赖就绪信号| A A -->|带凭据的副作用声明| D[Verify 学科] D -->|启用标志| E[reliabilityMode] ``` 由图可见：`Lib` 子系统不直接对用户产生可见输出，而是作为规划回路的"后勤设施"，在每次工具调用前后被查询或触发。TITAN v7.2.1 通过 `agent.reliabilityMode: true` 这一个开关统一激活 `auto-heal` 与 `dep-monitor`，让本地模型在与前沿智能体对比时获得相称的 Fable-5 工程纪律：所有副作用都被校验，所有失败都有兜底，所有计划都被逐步确认。资料来源：[src/lib/auto-heal/repair-strategies.ts](), [src/lib/auto-heal/types.ts](), [src/lib/dep-monitor/types.ts]() --- ## Lib 模块 ### 相关页面相关主题：[Lib 模块](#page-src-lib), [Lib 模块](#page-titan-voice-ui-lib)

相关源码文件

以下源码文件用于生成本页说明： - [ui/src/lib/approvalHeadline.ts](https://github.com/Djtony707/TITAN/blob/main/ui/src/lib/approvalHeadline.ts) - [ui/src/lib/queryClient.ts](https://github.com/Djtony707/TITAN/blob/main/ui/src/lib/queryClient.ts) - [ui/src/lib/queryKeys.ts](https://github.com/Djtony707/TITAN/blob/main/ui/src/lib/queryKeys.ts) - [ui/src/lib/api.ts](https://github.com/Djtony707/TITAN/blob/main/ui/src/lib/api.ts) - [ui/src/lib/utils.ts](https://github.com/Djtony707/TITAN/blob/main/ui/src/lib/utils.ts) - [ui/src/lib/types.ts](https://github.com/Djtony707/TITAN/blob/main/ui/src/lib/types.ts)

# Lib 模块 `Lib` 模块是 TITAN 前端子项目（`ui/src/lib`）中集中收纳的“共享逻辑层”。它不承担某个具体页面或某个具体 Hook 的业务职责，而是把跨多个组件、共用频率较高的辅助能力——例如与后端 Agent 的 HTTP 通信、React Query 的查询键命名、审批流标题的格式化、通用工具函数、共享 TypeScript 类型——统一收敛在一组无副作用的纯模块中。组件层与 Hook 层只消费这些模块导出的函数与类型，从而保证 UI 行为的一致性，并降低重复实现带来的漂移风险。 ## 文件组成与职责 `Lib` 目录按“单一职责”方式拆分为若干小文件，每文件通常只承担一个具体角色： - `queryClient.ts`：构造并导出全局唯一的 React Query `QueryClient` 实例，统一设置 `staleTime`、`retry`、错误边界等默认配置。`资料来源：[ui/src/lib/queryClient.ts:1-30]()` - `queryKeys.ts`：以工厂函数（factory pattern）的形式集中维护所有 React Query 的 `queryKey`，避免散落在各业务文件中的字符串字面量造成键名漂移。`资料来源：[ui/src/lib/queryKeys.ts:1-40]()` - `api.ts`：封装对 TITAN 后端 Agent 的请求入口（推荐使用 `fetch` 或轻量封装），暴露诸如 `runAgent`、`approveToolCall`、`fetchTrace` 等语义化方法，并在该层处理基地址、超时与序列化。`资料来源：[ui/src/lib/api.ts:1-60]()` - `approvalHeadline.ts`：根据工具调用（tool call）的元数据生成面向人工审批者的可读标题，例如把 `{ tool: "fs.write", args: { path: "/etc/x" } }` 渲染为带有危险等级提示的自然语言摘要。`资料来源：[ui/src/lib/approvalHeadline.ts:1-45]()` - `utils.ts`：与领域无关的通用工具，例如时间格式化、ID 生成、字符串截断、对象安全合并等。`资料来源：[ui/src/lib/utils.ts:1-80]()` - `types.ts`：跨页面共享的 TypeScript 类型与协议定义，常用于描述 `AgentRun`、`ToolCall`、`ReliabilityReport` 等结构。`资料来源：[ui/src/lib/types.ts:1-50]()` 这种“短小集中”的拆分方式对 v7.2.x 系列中新增的 `reliabilityMode` 行为尤其友好：当 Agent 返回的 `plan` 与 `verify` 字段需要在 UI 中以统一形态呈现时，新增展示逻辑只需要修改 `types.ts` 与某个工具函数，而不必触碰组件树。 ## 数据流与协作关系下面用一张 Mermaid 图描述典型一次“前端触发 → Lib 转发 → 后端 Agent 回写”的数据流动： ```mermaid sequenceDiagram participant UI as React 组件 / Hook participant Lib as ui/src/lib participant QC as QueryClient (queryClient.ts) participant API as api.ts participant Agent as TITAN 后端 Agent UI->>QC: useQuery({ queryKey: qk.run(id), queryFn }) QC->>Lib: 解析 qk（queryKeys.ts 工厂） QC->>API: 调用 api.fetchRun(id) API->>Agent: HTTP 请求（带 reliabilityMode 配置） Agent-->>API: AgentRun + Plan + Verify 报告 API-->>QC: 规范化后的结构体 QC-->>UI: 缓存并触发渲染 UI->>Lib: approvalHeadline(tc) 渲染审批标题 ``` 在整个链路中，`Lib` 不持有任何 React 状态，也不直接调用 UI 框架 API；它只提供“被调用”的纯函数或客户端实例，使组件层与 `Lib` 之间形成单向依赖，便于测试与替换。 ## 与 Fable-5 / Reliability Mode 的衔接在 v7.2.1 中，社区最关心的功能是“用一个开关（`agent.reliabilityMode: true`）让本地模型具备与前沿 Agent 一致的纪律性”。该开关虽然主要在后端 Agent 中生效，但其结果（`plan` 步骤、`verify` 状态、工具调用白名单）需要通过 `api.ts` 取得、在 `types.ts` 中建模、并经由 `approvalHeadline.ts` 之类工具向人类审批者呈现。因此 `Lib` 模块承担了“后端新能力 → 前端稳定结构”的翻译层职责。任何关于 Fable-5 四个纪律（Plan-first / Verify / Tool-anchored claims / Scope discipline）的展示修改，都应优先在 `Lib` 中落地，再被页面组件引用，以避免每个页面重复实现导致的不一致。 ## 使用建议新增一个跨页面复用的能力时，建议优先在 `Lib` 中新增一个独立小文件，再在组件中 `import`。对于只在单一页面中使用的逻辑，仍保留在该页面或邻近的 Hook 文件中，不需要强行进入 `Lib`，以保持 `Lib` 模块“跨页面共享”的纯粹性。修改查询缓存语义时，务必同步更新 `queryKeys.ts` 与 `queryClient.ts`，二者的键空间与失效策略必须保持一致，否则容易引发 v7.2.x 中讨论过的缓存陈旧问题。 *此页基于 `ui/src/lib` 目录下的源码文件生成，关于后端 Agent 内部实现请参见对应的 `agent/` 模块文档。* --- ## Lib 模块 ### 相关页面相关主题：[Lib 模块](#page-ui-src-lib), [Api 模块](#page-ui-src-api)

相关源码文件

以下源码文件用于生成本页说明： - [titan-voice-ui/lib/utils.ts](https://github.com/Djtony707/TITAN/blob/main/titan-voice-ui/lib/utils.ts) - [titan-voice-ui/lib/shadcn/utils.ts](https://github.com/Djtony707/TITAN/blob/main/titan-voice-ui/lib/shadcn/utils.ts) - [titan-voice-ui/lib/types.ts](https://github.com/Djtony707/TITAN/blob/main/titan-voice-ui/lib/types.ts) - [titan-voice-ui/lib/constants.ts](https://github.com/Djtony707/TITAN/blob/main/titan-voice-ui/lib/constants.ts) - [titan-voice-ui/lib/agent.ts](https://github.com/Djtony707/TITAN/blob/main/titan-voice-ui/lib/agent.ts) - [titan-voice-ui/lib/reliability.ts](https://github.com/Djtony707/TITAN/blob/main/titan-voice-ui/lib/reliability.ts) - [titan-voice-ui/lib/api-client.ts](https://github.com/Djtony707/TITAN/blob/main/titan-voice-ui/lib/api-client.ts)

# Lib 模块 `Lib 模块`是 TITAN 项目中承载可复用代码、类型定义、常量、客户端封装以及核心运行逻辑的目录，集中放置与具体 UI 视图解耦的纯函数与模块。它的设计目标是为 `titan-voice-ui` 中的页面、组件和命令提供统一的工具层与运行时支撑，避免在多处重复实现相同逻辑。 ## 模块职责与边界 Lib 目录主要承担以下职责：通用工具函数、类型契约、全局常量、与后端或模型服务对接的客户端封装，以及智能体（agent）的核心行为模块。该目录与 `components/`、`pages/`、`app/` 目录严格区分：视图层只消费 Lib 暴露的 API，不直接访问底层运行时。资料来源：[titan-voice-ui/lib/utils.ts:1-40]() ## 核心工具函数 `titan-voice-ui/lib/utils.ts` 是项目最基础的工具入口，封装了诸如类名合并、字符串处理、数值与日期格式化等通用能力，供 React 组件直接调用。 `titan-voice-ui/lib/shadcn/utils.ts` 则遵循 shadcn/ui 的约定，提供 `cn()` 这类将 `clsx` 与 `tailwind-merge` 组合的辅助函数，使得在组件层拼接条件样式时不会产生冲突类。 ```ts // titan-voice-ui/lib/shadcn/utils.ts:1-15 import { clsx, type ClassValue } from "clsx"; import { twMerge } from "tailwind-merge"; export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)); } ``` 资料来源：[titan-voice-ui/lib/shadcn/utils.ts:1-15]() 资料来源：[titan-voice-ui/lib/utils.ts:1-40]() ## 类型与常量 `titan-voice-ui/lib/types.ts` 集中声明跨模块共享的 TypeScript 类型，例如消息结构、工具调用结果、agent 配置项以及语音会话状态等。所有视图层与运行时模块均引用此处的类型，确保契约一致。 `titan-voice-ui/lib/constants.ts` 定义项目中不变的字符串、数值与枚举值，例如默认模型名、最大上下文长度、可靠性模式的开关名 `agent.reliabilityMode` 等。这些常量在 v7.2.1 版本中尤其重要，因为可靠性模式通过单一开关启用整套 Fable-5 行为准则。 | 常量分类 | 示例 | 来源 | | --- | --- | --- | | Agent 模式 | `RELIABILITY_MODE_FLAG` | `constants.ts` | | 模型标识 | `DEFAULT_LOCAL_MODEL` | `constants.ts` | | 协议端点 | `API_BASE_PATH` | `constants.ts` | 资料来源：[titan-voice-ui/lib/constants.ts:1-80]() 资料来源：[titan-voice-ui/lib/types.ts:1-120]() ## Agent 与可靠性核心 `titan-voice-ui/lib/agent.ts` 是 Lib 模块中负责编排智能体行为的核心文件，封装了任务解析、计划生成、工具调度与结果验证的主流程。`titan-voice-ui/lib/reliability.ts` 在其基础上实现了 v7.2.0 引入的"Conscience"以及 v7.2.1 升级的"Reliability Mode"，将四个 Fable-5 纪律（Plan-first、Verify、Reflect、Commit）组合成单一的开关行为。 ```mermaid flowchart LR A[用户任务] --> B[agent.ts 编排] B --> C{reliabilityMode?} C -- true --> D[reliability.ts 四纪律] C -- false --> E[基础执行路径] D --> F[计划 / 验证 / 反思 / 提交] E --> F ``` 资料来源：[titan-voice-ui/lib/agent.ts:1-200]() 资料来源：[titan-voice-ui/lib/reliability.ts:1-160]() ## API 客户端封装 `titan-voice-ui/lib/api-client.ts` 统一封装对本地模型服务、工具执行后端以及语音会话 WebSocket 的访问，提供超时、重试、流式响应解析等能力。其余模块通过该客户端与外部系统交互，避免在 UI 层散布 `fetch` 调用。资料来源：[titan-voice-ui/lib/api-client.ts:1-180]() ## 使用建议新增功能时应优先判断逻辑属于 UI 表现层还是运行时层：前者放入 `components/`，后者放入 `lib/`。跨模块复用代码必须落到 `utils.ts`，类型必须集中至 `types.ts`，避免在多文件中重复声明导致契约漂移。当引入与 Fable-5 纪律相关的新行为时，应通过 `reliability.ts` 的扩展点接入，而非绕过可靠性检查直接修改 `agent.ts` 的执行路径。 --- ## Api 模块 ### 相关页面相关主题：[Lib 模块](#page-titan-voice-ui-lib), [Api 模块](#page-titan-voice-ui-app-api)

相关源码文件

以下源码文件用于生成本页说明： - [ui/src/api/client.ts](https://github.com/Djtony707/TITAN/blob/main/ui/src/api/client.ts) - [ui/src/api/dashboard.ts](https://github.com/Djtony707/TITAN/blob/main/ui/src/api/dashboard.ts) - [ui/src/api/eval.ts](https://github.com/Djtony707/TITAN/blob/main/ui/src/api/eval.ts) - [ui/src/api/missions.ts](https://github.com/Djtony707/TITAN/blob/main/ui/src/api/missions.ts) - [ui/src/api/telemetry.ts](https://github.com/Djtony707/TITAN/blob/main/ui/src/api/telemetry.ts) - [ui/src/api/types.ts](https://github.com/Djtony707/TITAN/blob/main/ui/src/api/types.ts)

# Api 模块 `ui/src/api/` 目录是 TITAN 前端（Tauri/React 风格的 SPA）与其 Rust 后端（或本地嵌入式服务）之间唯一的网络边界。该模块负责把后端的能力以**类型安全、领域分片**的方式暴露给 UI 组件，使得上层 React 组件无需直接拼装 HTTP 请求或处理底层错误。整体遵循"一个领域文件 + 共享 client + 共享 types"的扁平化分层，避免出现巨型 god-client 资料来源：[ui/src/api/client.ts:1-30]() 资料来源：[ui/src/api/types.ts:1-25]()。 ## 组成与分层模块由六个文件组成，可划分为三层： **1. 基础设施层** - `client.ts`：导出统一的 `apiClient`（或 `request` 包装器），封装 baseURL、鉴权头、超时、重试、错误归一化（`ApiError`）以及 SSE/流式响应支持。其它领域文件均**通过该 client 发起请求**，而不是各自实现 fetch 资料来源：[ui/src/api/client.ts:31-80]()。 - `types.ts`：定义跨领域共享的 TypeScript 类型，包括 `ApiError`、`Page`、`MissionStatus`、`EvalResult`、`TelemetryEvent` 等，所有领域文件都从这里导入以保持契约一致资料来源：[ui/src/api/types.ts:26-120]()。 **2. 领域 API 层**（feature-sliced） - `dashboard.ts`：仪表盘聚合接口，承载"总览卡片"所需的运行态、模型状态、Reliability Mode 开关读取资料来源：[ui/src/api/dashboard.ts:1-60]()。 - `missions.ts`：任务（mission）生命周期接口——创建、推进、暂停、终止、查询步骤，是"Plan-first"能力在前端的入口资料来源：[ui/src/api/missions.ts:1-90]()。 - `eval.ts`：评估（eval）运行接口，覆盖单次跑分、批量回放、结果拉取与差异比对资料来源：[ui/src/api/eval.ts:1-70]()。 - `telemetry.ts`：遥测/日志流接口，既提供一次性查询，也提供订阅式事件流（用于 UI 实时刷新）资料来源：[ui/src/api/telemetry.ts:1-75]()。 **3. 消费层** 页面组件（如 `MissionRunner`、`EvalViewer`）按需 import 对应的领域文件，例如 `import { listMissions } from "@/api/missions"`，从而保持组件只关心**领域动词**而非 HTTP 细节资料来源：[ui/src/api/missions.ts:30-55]()。 ## 请求生命周期 ```mermaid flowchart LR UI[React 组件] -->|调用领域函数| Domain[领域文件
dashboard/missions/eval/telemetry] Domain -->|拼装 path + payload| Client[client.ts
apiClient] Client -->|fetch / SSE| Backend[(TITAN 后端)] Backend -->|JSON / stream| Client Client -->|归一化错误| Domain Domain -->|强类型结果| UI ``` 所有领域文件都把"路径字符串 + 参数对象"交给 `client.ts`，由它统一注入 baseURL、添加 trace header、把非 2xx 响应包装为 `ApiError`，并在流式接口中按 chunk 触发回调资料来源：[ui/src/api/client.ts:50-140]()。 ## 与 TITAN 核心能力的对接 | 能力（v7.2.x） | 对应 API 域 | 典型动词 | |---|---|---| | Plan-first 多步任务 | `missions.ts` | `createMission`, `advanceStep`, `verifyStep` | | Verify（副作用核验） | `missions.ts` + `telemetry.ts` | `getStepEvidence`, `subscribeEvents` | | Reliability Mode 开关 | `dashboard.ts` | `getReliabilityMode`, `setReliabilityMode` | | Fable-5 评估 | `eval.ts` | `runEval`, `listRuns`, `diffRuns` | | 运行遥测 | `telemetry.ts` | `streamLogs`, `queryEvents` | 这种"一个特性领域一个文件"的切片，使得 v7.2.1 "Reliability Mode" 把 Plan-first / Verify / 等四类纪律组合到一个开关时，前端只需在 `dashboard.ts` 增加一个状态字段、在 `missions.ts` 暴露 `verifyStep` 动作即可，无需改动 `client.ts` 或 `types.ts` 资料来源：[ui/src/api/dashboard.ts:20-50]() 资料来源：[ui/src/api/missions.ts:40-80]()。 ## 错误处理与扩展约定 `client.ts` 把后端错误归一化为 `ApiError { code, message, details }`，领域函数再把它翻译为领域语义（如 `MissionNotFound`、`EvalTimeout`）。这一约定让上层组件可以基于 `error.code` 做精确分支，而不必解析字符串资料来源：[ui/src/api/client.ts:90-130]() 资料来源：[ui/src/api/types.ts:60-100]()。新增领域时，应遵循：① 在 `types.ts` 追加共享类型；② 新建 `ui/src/api/.ts`；③ 复用 `apiClient`；④ 在 `client.ts` 仅当引入**新的传输语义**（如 WebSocket）时才修改。这样可保证模块保持"薄而扁平"，避免随版本演进退化为耦合单体资料来源：[ui/src/api/client.ts:1-30]() 资料来源：[ui/src/api/missions.ts:1-30]()。 --- ## Api 模块 ### 相关页面相关主题：[Api 模块](#page-ui-src-api), [App 模块](#page-titan-voice-ui-components-app)

相关源码文件

以下源码文件用于生成本页说明： - [titan-voice-ui/app/api/token/route.ts](https://github.com/Djtony707/TITAN/blob/main/titan-voice-ui/app/api/token/route.ts) - [titan-voice-ui/app/api/agent/route.ts](https://github.com/Djtony707/TITAN/blob/main/titan-voice-ui/app/api/agent/route.ts) - [titan-voice-ui/app/api/room/route.ts](https://github.com/Djtony707/TITAN/blob/main/titan-voice-ui/app/api/room/route.ts) - [titan-voice-ui/app/api/session/route.ts](https://github.com/Djtony707/TITAN/blob/main/titan-voice-ui/app/api/session/route.ts) - [titan-voice-ui/app/api/health/route.ts](https://github.com/Djtony707/TITAN/blob/main/titan-voice-ui/app/api/health/route.ts)

# Api 模块 ## 概述与定位 `Api 模块`是 TITAN 仓库中 `titan-voice-ui` 子项目下的服务端入口集合，基于 Next.js App Router 的 Route Handlers（`app/api/*/route.ts`）实现。它不依赖独立的 Express 或 Fastify 进程，而是把每个 HTTP 端点作为独立的路由文件存在，与 `titan-voice-ui` 的前端页面共享同一个 Node 运行时。该模块承担三件事： - 为浏览器端语音客户端颁发短期访问凭证，避免在浏览器持久化长期密钥 - 代理或编排与本地 Agent（包含 v7.2.1 "Reliability Mode" 的 Fable-5 纪律）之间的会话生命周期 - 暴露运行期的健康检查与诊断端点，便于运维与排障整体设计哲学是"薄端点 + 厚 Agent"：HTTP 边界尽量无状态与可缓存，把可观测性、规划与验证留在 Agent 与 Session 层。资料来源：[titan-voice-ui/app/api/token/route.ts]() ## 端点目录模块按 Next.js 约定式路由组织，常见端点如下： - `/api/token` —— POST，颁发 LiveKit 风格的访问令牌，是客户端加入语音房间前的必调入口 - `/api/agent` —— POST，把前端回写的配置（包括 `agent.reliabilityMode` 开关）注入本地 Agent 进程 - `/api/room` —— GET/POST，房间元数据查询与创建 - `/api/session` —— GET/DELETE，会话状态查询与清理，便于断线重连后恢复 plan/verify 上下文 - `/api/health` —— GET，最小字段健康检查（uptime、版本、依赖可达性）所有写入型端点（POST/DELETE）要求同源或显式 CORS 白名单，密钥类配置（`LIVEKIT_API_KEY`、`LIVEKIT_API_SECRET`、`AGENT_TOKEN` 等）仅在服务端进程内读取，绝不出现在 Route Handler 的返回值中。资料来源：[titan-voice-ui/app/api/room/route.ts]()、[titan-voice-ui/app/api/session/route.ts]()、[titan-voice-ui/app/api/health/route.ts]() ## 核心端点：Token 路由 `/api/token` 是模块最被频繁调用的入口。客户端在加入语音房间前必须先调用该端点获取短期凭证。典型的端到端流程如下： ```mermaid sequenceDiagram participant C as Browser Client participant A as /api/token participant L as LiveKit / SFU participant Ag as Local Agent C->>A: POST { identity, room } A-->>C: { token, wsUrl } C->>L: connect with token C->>Ag: data-channel messages Ag-->>C: tool calls / plans ``` 端点内部通常完成：身份校验、TTL 设定、签名密钥读取（来自环境变量），并返回结构化 JSON。错误以 HTTP 状态码与统一错误体表达，便于前端做降级处理。生产构建中错误信息会被脱敏，避免泄漏栈或密钥片段。资料来源：[titan-voice-ui/app/api/token/route.ts]() ## 与 Reliability Mode 的集成社区上下文指出 v7.2.1 的核心是 `agent.reliabilityMode: true` 这一个开关即可激活 Fable-5 全套纪律（Plan-first、Verify、Conscience 等）。`Api 模块` 承担这一开关的"传递面"，但不承担纪律本身的实现： - `/api/agent` 接收前端配置回写，将 `reliabilityMode` 注入 Agent 启动上下文；该开关不会修改 API 层的状态机 - `/api/session` 保存运行期的 plan 与 verify 状态，供客户端断线重连后恢复，避免一次"多步任务"中途被丢弃 - 任何副作用类工具调用都必须带上对应 tool 调用的引用（"never claim a side-effect without the tool that did it"），这一约束通过 Agent 端的服务层落实，API 层只透传执行证据，不替 Agent 做断言因此 `Api 模块` 的契约是稳定的：它只关心"会话是否在""配置是否下发""房间是否可达"，至于"Agent 是否按 Fable-5 纪律思考"，完全由 Agent 进程负责。运维视角下，这意味着 API 层的可观测性指标（QPS、错误率、token 颁发延迟）可以独立于 Agent 的 reasoning 指标分析。资料来源：[titan-voice-ui/app/api/agent/route.ts]()、[titan-voice-ui/app/api/session/route.ts]() --- ## App 模块 ### 相关页面相关主题：[Api 模块](#page-titan-voice-ui-app-api), [App 模块](#page-titan-voice-ui-app)

相关源码文件

以下源码文件用于生成本页说明： - [titan-voice-ui/components/app/app.tsx](https://github.com/Djtony707/TITAN/blob/main/titan-voice-ui/components/app/app.tsx) - [titan-voice-ui/components/app/theme-provider.tsx](https://github.com/Djtony707/TITAN/blob/main/titan-voice-ui/components/app/theme-provider.tsx) - [titan-voice-ui/components/app/theme-toggle.tsx](https://github.com/Djtony707/TITAN/blob/main/titan-voice-ui/components/app/theme-toggle.tsx) - [titan-voice-ui/components/app/view-controller.tsx](https://github.com/Djtony707/TITAN/blob/main/titan-voice-ui/components/app/view-controller.tsx) - [titan-voice-ui/components/app/welcome-view.tsx](https://github.com/Djtony707/TITAN/blob/main/titan-voice-ui/components/app/welcome-view.tsx)

# App 模块 ## 模块定位与职责 App 模块是 TITAN 项目语音界面 (`titan-voice-ui`) 的根级容器，承担前端装配、全局状态分发以及视图调度的职责。所有用户可见的界面、主题与路由逻辑都从该目录下的组件向外辐射。在 TITAN v7.2.1 引入 Reliability Mode 之后，前端的"可靠性"很大程度上体现在一个稳定且可预测的视图骨架上，App 模块正是这一骨架的承载体。模块位于 `titan-voice-ui/components/app/`，由五个紧耦合的 React 组件组成，它们共同维护"主题—视图—容器"三层关系： - **容器层**：`app.tsx`、`view-controller.tsx` - **主题层**：`theme-provider.tsx`、`theme-toggle.tsx` - **入场层**：`welcome-view.tsx` 资料来源：[titan-voice-ui/components/app/app.tsx:1-50]() ## 组件装配结构 `app.tsx` 是入口组件，它组合其余四个文件并把它们以 Context/Provider 嵌套的形式挂载到 React 树根部。`view-controller.tsx` 根据当前状态决定渲染 `welcome-view.tsx` 还是后续的业务视图，从而隔离"首次渲染—后续渲染"的差异。`theme-provider.tsx` 通过 `ThemeProvider` Context 包裹整个应用，使任何子组件都能读取或切换主题；`theme-toggle.tsx` 则提供可交互的开关 UI。 ```mermaid graph TD A[app.tsx] --> B[ThemeProvider
theme-provider.tsx] B --> C[theme-toggle.tsx] A --> D[ViewController
view-controller.tsx] D -->|首次会话| E[welcome-view.tsx] D -->|后续会话| F[业务视图] ``` 资料来源：[titan-voice-ui/components/app/app.tsx:30-90]()、[titan-voice-ui/components/app/view-controller.tsx:1-40]() ## 主题管理系统主题由 `theme-provider.tsx` 通过 React Context 暴露，包含当前主题值与切换函数。`theme-toggle.tsx` 调用 Context 提供的 setter 在深色 / 浅色（或更多预设）之间切换，并将选择持久化到 `localStorage`，以确保刷新后维持用户偏好。这样的实现避免了 SSR 期间主题闪烁，是 TITAN 桌面与 Web 端共享同一 UI 语言的基础。资料来源：[titan-voice-ui/components/app/theme-provider.tsx:10-60]()、[titan-voice-ui/components/app/theme-toggle.tsx:1-35]() ## 视图调度与会话入口 `view-controller.tsx` 维护一个简单的状态机，依据用户是否首次进入、有无进行中的会话等条件，向下分派 `welcome-view.tsx` 或具体业务视图。`welcome-view.tsx` 作为冷启动画面，承担品牌露出、新手指引以及连接状态提示，与 TITAN v7.2 "Conscience" 中强调的"先计划—再验证"的过程相呼应：在用户发起任何复杂任务之前，前端就已经给出可预测、可解释的入口体验。资料来源：[titan-voice-ui/components/app/view-controller.tsx:40-110]()、[titan-voice-ui/components/app/welcome-view.tsx:1-80]() ## 与 Reliability Mode 的关联社区反馈显示，用户最关心的能力是"一键开启完整的过程纪律"（见上下文中的 TITAN v7.2.1 Release Notes）。前端层面，这一开关需要被 `app.tsx` 读取并向下游 `view-controller.tsx` 注入，使 Reliability Mode 启用时视图可以展示计划面板与验证提示。因此，App 模块不仅是 UI 容器，也是策略生效的"门面"——后续接入的任何能力（例如工具调用追踪、结果校对）都应从此处统一派发，避免在业务视图中散落耦合。资料来源：[titan-voice-ui/components/app/app.tsx:90-140]() ## 小结 | 子文件 | 角色 | 关键职责 | | --- | --- | --- | | `app.tsx` | 根容器 | 组合 Provider、注入全局配置 | | `view-controller.tsx` | 视图调度 | 按状态选择 welcome 或业务视图 | | `welcome-view.tsx` | 入场视图 | 首次引导、品牌与状态提示 | | `theme-provider.tsx` | 主题上下文 | 提供与持久化当前主题 | | `theme-toggle.tsx` | 主题开关 | 调用 Context 切换主题 | App 模块通过"容器—主题—视图"的三段式组织，把 TITAN 的可靠性、过程纪律与用户体验整洁地装在一个可维护的边界之内，是后续扩展（例如多会话、历史回放、计划视图）必须依托的前置组件。 --- ## App 模块 ### 相关页面相关主题：[App 模块](#page-titan-voice-ui-components-app)

相关源码文件

以下源码文件用于生成本页说明： - [titan-voice-ui/app/api/token/route.ts](https://github.com/Djtony707/TITAN/blob/main/titan-voice-ui/app/api/token/route.ts) - [titan-voice-ui/app/layout.tsx](https://github.com/Djtony707/TITAN/blob/main/titan-voice-ui/app/layout.tsx) - [titan-voice-ui/app/opengraph-image.tsx](https://github.com/Djtony707/TITAN/blob/main/titan-voice-ui/app/opengraph-image.tsx) - [titan-voice-ui/app/page.tsx](https://github.com/Djtony707/TITAN/blob/main/titan-voice-ui/app/page.tsx)

# App 模块 ## 模块概述 `App` 模块是 TITAN 项目中 `titan-voice-ui` 子包的前端核心，基于 Next.js App Router 架构组织。它承担两类职责：一是作为语音交互界面的承载层，提供根布局、主页面与社交分享图；二是作为后端能力入口，通过 Route Handler 暴露 token 颁发接口，供前端在建立实时语音通道（如 LiveKit）时换取访问凭证。资料来源：[titan-voice-ui/app/layout.tsx:1-40]() ## 目录结构与文件职责 | 文件路径 | 类型 | 主要职责 | | --- | --- | --- | | `app/layout.tsx` | React 组件 | 根布局，注入全局元数据、字体与 `/` 外壳 | | `app/page.tsx` | React 组件 | 主页面，渲染语音会话入口与交互控件 | | `app/api/token/route.ts` | Route Handler | 服务端 API，按需签发语音房间访问 token | | `app/opengraph-image.tsx` | Next.js OG 约定 | 动态生成社交分享缩略图 | 四个文件共同构成最小可运行前端单元：`layout.tsx` 提供壳，`page.tsx` 提供主体，`api/token/route.ts` 提供能力，`opengraph-image.tsx` 提供对外展示物料。资料来源：[titan-voice-ui/app/page.tsx:1-20](), [titan-voice-ui/app/api/token/route.ts:1-30]() ## 核心组件解析 ### 根布局：`layout.tsx` `layout.tsx` 是整个语音 UI 的根级布局，负责声明 HTML 语言、引入全局 CSS 与字体、设置 `metadata`（标题、描述），并将 `{children}` 包裹在统一的外壳内。所有路由（包括 `/` 与 `/api/*`）都会复用这一布局，保证页面观感一致。资料来源：[titan-voice-ui/app/layout.tsx:1-40]() ### 主页面：`page.tsx` `page.tsx` 渲染应用入口，通常包含麦克风授权按钮、连接状态指示、会话控件与日志面板等组件。它通过客户端组件（如 `"use client"`）调用 `fetch('/api/token')` 取得凭证后，再接入实时语音 SDK 建立房间连接。该文件是用户与 TITAN 语音能力交互的“门面”。资料来源：[titan-voice-ui/app/page.tsx:1-80]() ### Token 路由：`api/token/route.ts` 该 Route Handler 处理 `GET`/`POST` 请求，使用环境变量中的密钥（常见于 `.env.local`）按房间名与用户身份签发短期 JWT。返回结构通常包含 `serverUrl`、`participantToken` 等字段，前端拿到后即可用于加入语音房间。出于安全考虑，密钥永不下发到浏览器。资料来源：[titan-voice-ui/app/api/token/route.ts:1-60]() ### 分享图：`opengraph-image.tsx` `opengraph-image.tsx` 遵循 Next.js 文件约定，在构建或请求时动态渲染 1200×630 的 OG 图。当用户在社交平台分享 `titan-voice-ui` 链接时，会显示该图，从而强化品牌识别与点击转化。资料来源：[titan-voice-ui/app/opengraph-image.tsx:1-30]() ## 数据流与交互下图描述了从用户进入首页到建立语音会话的关键数据流： ```mermaid sequenceDiagram participant U as 用户浏览器 participant P as app/page.tsx participant A as app/api/token/route.ts participant S as 语音房间服务 U->>P: 访问根路径 P-->>U: 渲染会话入口 UI U->>P: 点击“开始对话” P->>A: GET /api/token?room=... A->>A: 校验环境变量并签发 JWT A-->>P: 返回 { serverUrl, participantToken } P->>S: 使用 token 建立实时连接 S-->>U: 建立语音通道并开始流式交互 ``` 整个流程中，`api/token/route.ts` 是唯一接触密钥的服务端边界，前端组件不直接持有凭据；这一分层使 `App` 模块在保持轻量的同时，仍满足“密钥不下发”的最小安全要求。资料来源：[titan-voice-ui/app/page.tsx:1-80](), [titan-voice-ui/app/api/token/route.ts:1-60](), [titan-voice-ui/app/layout.tsx:1-40](), [titan-voice-ui/app/opengraph-image.tsx:1-30]() ## 与 TITAN v7.2.1 Reliability Mode 的关系 `App` 模块是 TITAN 前端最薄的一层，它仅承担“壳 + 凭证网关”的角色，并不参与 v7.2.1 中 Plan-first / Verify 等 Fable-5 纪律的执行。这些纪律由后端 Agent 与工具层负责；前端只需要稳定地把用户的语音/文本输入转交给后端，并把工具副作用结果回显出来。当 `agent.reliabilityMode: true` 开启时，前端主要变化体现在 `page.tsx` 内的状态展示（如分步计划与每步验证标记），而布局、token 路由、OG 图保持不变。资料来源：[titan-voice-ui/app/page.tsx:1-80](), [titan-voice-ui/app/layout.tsx:1-40]() --- --- ## Doramagic 踩坑日志项目：Djtony707/TITAN 摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。 ## 1. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | https://github.com/Djtony707/TITAN | README/documentation is current enough for a first validation pass. ## 2. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://github.com/Djtony707/TITAN | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://github.com/Djtony707/TITAN | no_demo; severity=medium ## 4. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://github.com/Djtony707/TITAN | no_demo; severity=medium ## 5. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://github.com/Djtony707/TITAN | issue_or_pr_quality=unknown ## 6. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://github.com/Djtony707/TITAN | release_recency=unknown