项目定位与目标

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

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 纪律集合，社区文档中明确披露的纪律包括：

完整 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

定位与整体职责

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

与上层模块的协作

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

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<T>、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。

请求生命周期

flowchart LR
  UI[React 组件] -->|调用领域函数| Domain[领域文件<br/>dashboard/missions/eval/telemetry]
  Domain -->|拼装 path + payload| Client[client.ts<br/>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.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/<feature>.ts；③ 复用 apiClient；④ 在 client.ts 仅当引入新的传输语义（如 WebSocket）时才修改。这样可保证模块保持"薄而扁平"，避免随版本演进退化为耦合单体 资料来源：ui/src/api/client.ts:1-30 资料来源：ui/src/api/missions.ts:1-30。

模块定位与职责

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。

graph TD
  A[app.tsx] --> B[ThemeProvider<br/>theme-provider.tsx]
  B --> C[theme-toggle.tsx]
  A --> D[ViewController<br/>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 模块通过"容器—主题—视图"的三段式组织，把 TITAN 的可靠性、过程纪律与用户体验整洁地装在一个可维护的边界之内，是后续扩展（例如多会话、历史回放、计划视图）必须依托的前置组件。

Pitfall Log / 踩坑日志

项目：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