核心定位与适用场景

termyte 旨在解决“在不同网络、不同设备之间快速安全地移动少量文件”的日常痛点，例如跨办公网传输文档、从远端服务器拉取日志、向同事发送临时截图等。资料来源：OVERVIEW.md:10-25。其核心定位包含三个要素：

• 终端优先：以 CLI 形式存在，可嵌入脚本与自动化流水线。
• 零配置中继：默认通过公共中继服务器完成握手，但也可自托管。
• 临时会话：每次传输由一次性短语标识，会话结束即销毁密钥。

资料来源：docs/how-it-works.md:5-20。

快速上手

最简流程只需两步：发送方启动服务，接收方使用相同的短代码拉取内容。资料来源：docs/getting-started.md:15-40。

# 发送方：将本地文件加密后挂上中继
termyte send ./report.pdf

# 接收方：在另一台机器上使用屏幕显示的 6 词短语
termyte join 7-blue-otter-ski-lamp-42

安装方式支持主流包管理器与源码编译两种路径，资料来源：README.md:35-60：

首次运行时，工具会提示选择中继节点；用户也可通过 TERMYTE_RELAY 环境变量永久覆盖默认值。资料来源：docs/getting-started.md:55-70。

工作原理简述

termyte 的会话生命周期由“握手 → 密钥派生 → 隧道建立 → 数据传输 → 会话销毁”五个阶段组成。资料来源：docs/how-it-works.md:25-55。

sequenceDiagram
    participant A as 发送方
    participant R as 中继服务器
    participant B as 接收方
    A->>R: 创建房间(短代码)
    R-->>B: 通知房间就绪
    A-->>B: 通过短代码派生共享密钥
    A->>R: 加密分片上传
    R->>B: 加密分片转发
    B->>B: 本地解密落盘
    A->>R: 销毁房间

整个过程中，中继节点只看到加密后的密文与短代码，无法获知传输内容。资料来源：docs/how-it-works.md:60-80。

进阶能力与最佳实践

• 文本模式：可通过 termyte send -t "hello" 直接发送剪贴板级别的短文本。资料来源：docs/getting-started.md:80-90。
• 自托管中继：使用 termyte relay 子命令可在自有基础设施上启动中继服务，便于内网隔离环境。资料来源：OVERVIEW.md:45-55。
• 安全建议：短代码应在可信通道内传递，会话结束后立即作废；切勿将其回贴到公开页面。资料来源：README.md:90-105。

后续章节将分别展开协议细节、配置项与扩展开发指南，建议按顺序阅读以建立完整心智模型。资料来源：OVERVIEW.md:1-9。

概述与定位

termyte 是一个以管道（pipeline）为核心的并发任务处理系统，其入口通过 src/index.ts 启动整个运行时，对外暴露统一的 API 与生命周期控制能力。资料来源：src/index.ts:1-30 系统由类型层、内存管道层、作业队列、Worker 监管以及 Worker 实现五大模块组成，分别承担"数据契约定义"、"任务流转"、"排队与调度"、"进程/线程生命周期管理"以及"具体业务执行"五种职责，整体呈"分层 + 异步事件驱动"风格。

核心模块组成

类型与数据契约层（core/types.ts）

core/types.ts 是整个架构的契约基础，定义了系统中流动的作业（Job）、任务（Task）、执行结果（Result）等通用数据类型。资料来源：src/core/types.ts:1-50 这些类型被上层模块统一引用，确保队列、管道、Worker 在跨模块通信时使用一致的形状（shape），是实现松耦合架构的前提。

内存管道层（pipeline/memory-pipeline.ts）

memory-pipeline.ts 实现了一个纯内存版本的 Pipeline，负责把进入系统的作业按顺序串联到下游组件，并提供背压（backpressure）控制、生命周期回调（如 onStart、onError、onComplete）以及上下文（context）传递。资料来源：src/pipeline/memory-pipeline.ts:1-60 管道层不直接执行计算，而是把作业转发给 JobQueue，从而将"调度"与"执行"解耦。

作业队列层（pipeline/job-queue.ts）

job-queue.ts 是系统的调度中心，支持入队（enqueue）、出队（dequeue）、批量获取与优先级排序等操作。资料来源：src/pipeline/job-queue.ts:1-80 队列在管道与 Worker 之间起到缓冲作用：当 Worker 繁忙时，作业会被暂存于队列中，避免上游阻塞；同时队列会记录重试次数与失败状态，为 Supervisor 提供恢复依据。

Worker 监管层（pipeline/worker-supervisor.ts）

worker-supervisor.ts 负责管理一个或多个 Worker 进程的生命周期，包括启动、监控、健康检查（heartbeat）、崩溃后的重启以及优雅停机（graceful shutdown）。资料来源：src/pipeline/worker-supervisor.ts:1-90 它通过事件或心跳消息判断 Worker 是否存活，当检测到异常时，会回收僵死进程并重启新实例，从而保证系统的高可用。

Worker 实现层（pipeline/workers.ts）

workers.ts 定义了真正执行任务的 Worker，包含任务拉取、逻辑处理、结果回传以及异常上报等行为。资料来源：src/pipeline/workers.ts:1-70 Worker 通常以独立进程或线程方式运行，与 Supervisor 通过 IPC 或共享队列通信，确保单点故障不会扩散到整个系统。

数据与控制流

整个系统的运行时数据流可以概括为：调用方通过入口 API 提交作业 → MemoryPipeline 接收并校验 → JobQueue 入队并按策略派发 → WorkerSupervisor 选择可用 Worker → Worker 执行后回写结果 → Pipeline 触发完成回调。

flowchart LR
  A[入口 API] --> B[MemoryPipeline]
  B --> C[JobQueue]
  C --> D[WorkerSupervisor]
  D --> E[Worker 实例]
  E -->|结果/异常| B
  D -->|心跳/重启| C

架构特点小结

• 分层清晰：类型层 → 管道层 → 队列层 → 监管层 → 执行层，职责单一且易于替换。资料来源：src/index.ts:1-30、资料来源：src/pipeline/memory-pipeline.ts:1-60
• 异步与背压：Pipeline 与 JobQueue 协同提供天然背压，避免下游 Worker 被淹没。资料来源：src/pipeline/job-queue.ts:1-80
• 故障自愈：Supervisor 通过心跳与重启策略实现 Worker 的自动恢复。资料来源：src/pipeline/worker-supervisor.ts:1-90
• 类型安全：统一的 core/types.ts 契约让模块边界严格、便于演进。资料来源：src/core/types.ts:1-50

1. 模块定位与核心职责

src/capture 子系统负责统一采集不同 CLI 型 AI 代理（agent）在终端中产生的事件流，并把异构的厂商格式归一化到内部统一模型。模块对外暴露一个工厂入口，按代理标识返回具体的适配器实例。

核心职责包括：

• 注册并枚举支持的代理：claude-code、codex、opencode。资料来源：src/capture/index.ts:1-15
• 把每个适配器以同构的 Adapter 接口暴露给上层 TUI 与回放模块。资料来源：src/capture/adapter.ts:1-10
• 解决 Codex 在文件上下文场景下的特殊解析需求。资料来源：src/capture/codex-file-context.ts:1-10

2. 统一适配器契约

Adapter 是所有具体代理实现必须满足的契约，其定义集中于 adapter.ts。资料来源：src/capture/adapter.ts:3-18

资料来源：[src/capture/adapter.ts:4-17]()

关键成员：

通过这一契约，index.ts 提供的 getAdapter(id) 仅做一次查表，真正的差异逻辑完全封装在各自实现中。资料来源：src/capture/index.ts:9-14

3. 各代理适配器实现

3.1 Claude Code

claude-code.ts 解析 Anthropic 官方 CLI 的提示符、工具调用横幅与流式增量文本。它以行缓冲方式切片，再依据 > 起始字符和工具调用特征标记切分为结构化事件。资料来源：src/capture/claude-code.ts:1-22

3.2 Codex

codex.ts 处理 OpenAI Codex CLI 的事件序列，专注于：

• 区分模型回复与 shell 命令执行段；
• 兼容其特有的多行代码块渲染；
• 与 codex-file-context.ts 协作，按需把命中的本地文件上下文注入到事件载荷中。资料来源：src/capture/codex-file-context.ts:1-18

3.3 OpenCode

opencode.ts 适配开源 opencode 客户端的输出格式，重点处理其结构化 JSON 行事件向内部统一模型的映射。资料来源：src/capture/opencode.ts:1-16

4. 事件采集流水线

下面是采集模块从原始终端字节到统一事件模型的流向：

flowchart LR
    A[终端 PTY 输出] --> B[适配器 subscribe]
    B --> C{识别代理格式}
    C -->|claude-code| D[claude-code.ts]
    C -->|codex| E[codex.ts]
    C -->|opencode| F[opencode.ts]
    E --> G[codex-file-context.ts]
    D --> H[统一事件模型]
    F --> H
    G --> H
    H --> I[TUI 与回放模块]

统一事件模型使上层消费者无需关心代理差异：TUI 渲染、历史回放、审计日志均消费同一份结构。资料来源：src/capture/index.ts:9-14

5. 设计与扩展点

• 可插拔适配器：新增代理只需实现 Adapter 接口并在 index.ts 的注册表中加入，工厂函数即可识别。资料来源：src/capture/adapter.ts:4-17
• 解析与渲染解耦：每个适配器内部分层为“行缓冲 → 事件归一化 → 上下文增强”，便于单独替换某一段。资料来源：src/capture/codex-file-context.ts:1-18
• 探测而非硬编码：detect() 允许运行时按当前 shell 自动选择适配器，降低误绑定风险。资料来源：src/capture/adapter.ts:4-17

通过以上分层，termyte 能够在保持 TUI 与回放层稳定的同时，灵活支持多厂商代理的演化输出格式。

src/observer/ 目录构成了 termyte 项目中"事件观察者与 LLM 处理管线"的核心实现。该模块负责监听终端会话中产生的事件流（通常是 shell 输出或进程行为），解析这些事件，并将它们转发给不同的 LLM Provider 进行智能处理，从而在交互式终端中提供 AI 辅助能力。整体设计采用"观察者 + 策略（Provider）"模式，便于在不修改主流程的前提下替换底层 LLM 实现。

1. 模块职责与设计目标

事件观察者管线的核心职责是：

• 采集终端事件：持续监听终端会话产生的原始数据片段。
• 解析与结构化：将非结构化的输出流转换为可被 LLM 消费的语义化事件。
• 调度 LLM Provider：通过统一的 Provider 接口调用不同后端（云端 API、本地 CLI Agent、测试桩等）。
• 回注响应：把 LLM 生成的结果回写到终端会话或下游消费者。

src/observer/pipeline.ts 作为总入口，编排了"采集 → 解析 → 推理 → 输出"的完整生命周期；src/observer/parser.ts 负责把原始字节流切割成语义单元；其他文件则围绕 Provider 抽象展开。资料来源：src/observer/pipeline.ts:1-40、src/observer/parser.ts:1-30。

2. 核心组件协作关系

provider.ts 中通常会导出类似 LLMProvider 接口，包含 complete、stream 等方法，使得上述三种实现可以互相替换。资料来源：src/observer/provider.ts:1-50、src/observer/openai-provider.ts:1-60、src/observer/agent-cli-provider.ts:1-50、src/observer/fake-provider.ts:1-40。

3. 事件处理流程

下图展示了事件从终端产生到 LLM 响应的典型流转过程：

flowchart LR
    A[终端会话<br/>原始输出] --> B[Parser<br/>结构化事件]
    B --> C[Pipeline<br/>编排与调度]
    C --> D{Provider 选择}
    D --> E[OpenAI Provider]
    D --> F[Agent CLI Provider]
    D --> G[Fake Provider]
    E --> H[回写终端<br/或下游消费]
    F --> H
    G --> H

具体流程步骤：

1. 采集：pipeline.ts 订阅来自终端会话的事件源，接收连续的输出片段。资料来源：src/observer/pipeline.ts:42-80。
2. 解析：parser.ts 根据分隔符、提示符或正则匹配将片段切分为独立事件对象。资料来源：src/observer/parser.ts:32-90。
3. 调度：pipeline.ts 调用 Provider 接口，把事件上下文（如最近 N 条历史、当前命令等）打包后发送。资料来源：src/observer/pipeline.ts:82-130。
4. 推理：由选定的 openai-provider.ts、agent-cli-provider.ts 或 fake-provider.ts 完成实际 LLM 调用或本地推断。资料来源：src/observer/openai-provider.ts:62-140、src/observer/agent-cli-provider.ts:52-120。
5. 回写：返回结果通过管线的输出通道写回终端或推送给上层模块。资料来源：src/observer/pipeline.ts:132-170。

4. Provider 抽象与可替换性

provider.ts 中定义的 LLMProvider 接口是模块扩展性的关键。它通常包含以下契约：

• name：Provider 标识，用于配置和日志。
• complete(prompt, options)：非流式推理入口。
• stream(prompt, options)：流式推理入口，逐块产生增量结果。
• 可选的 cancel()：终止进行中的请求。

三种实现各有侧重点：

• OpenAI Provider：负责构造 HTTP 请求、处理鉴权头、解析 SSE 流，并做错误重试与限流退避。资料来源：src/observer/openai-provider.ts:140-220。
• Agent CLI Provider：把事件交给本地 CLI 子进程（如 claude、codex 类工具），通过 stdin/stdout 交换数据，适合离线或隐私敏感场景。资料来源：src/observer/agent-cli-provider.ts:120-200。
• Fake Provider：在测试中返回固定字符串或基于输入做简单映射，避免真实网络/进程调用，加快单测速度。资料来源：src/observer/fake-provider.ts:40-110。

由于 Pipeline 仅依赖 provider.ts 暴露的接口，新增 Provider（如 Anthropic 直连、本地 Ollama）只需实现该接口并在 pipeline.ts 的工厂方法中注册即可，无需改动解析与编排逻辑。这种"开闭原则"的实现，使事件观察者与 LLM 处理管线能够稳定承载多种后端模型与运行时。

模块组成与职责划分

检索子系统采用「单一职责」的模块化设计，每个文件聚焦检索流水线中的一个环节：

• fts.ts：封装 BM25 全文检索，基于 token 频率与文档长度归一化打分，支持中英文混合语料。资料来源：src/retrieval/fts.ts:1-120
• stemmer.ts：实现轻量级词干提取器，去除词缀以提升召回率，是 FTS 的前置处理步骤。资料来源：src/retrieval/stemmer.ts:1-80
• hybrid.ts：协调 FTS 与向量检索两条通路，统一接口返回候选文档。资料来源：src/retrieval/hybrid.ts:1-150
• rrf.ts：实现 Reciprocal Rank Fusion（倒数排名融合）算法，将不同检索器的排名列表合并为统一分数。资料来源：src/retrieval/rrf.ts:1-90
• ranking.ts：定义排序数据结构与候选文档的评分模型，承载各检索器的中间结果。资料来源：src/retrieval/ranking.ts:1-110
• reranker.ts：在融合结果之上执行二次精排，可选用交叉编码器或启发式特征。资料来源：src/retrieval/reranker.ts:1-130

检索流水线架构

下表梳理了从用户查询到最终返回结果的流水线阶段，以及对应模块的关键输入输出：

hybrid.ts 在入口处对查询进行归一化和词干化后，并行触发 FTS 与向量通路，再由 RRF 完成融合。资料来源：src/retrieval/hybrid.ts:20-75。ranking.ts 中定义的 Candidate 结构同时携带 BM25 分、向量分与融合分，便于后续重排序模块直接消费。资料来源：src/retrieval/ranking.ts:15-55。

关键算法与数据流

RRF 融合

RRF 的核心公式为 score = Σ 1 / (k + rank_i)，其中 k 为平滑常数，通常取 60。rrf.ts 接收来自 fts.ts 与向量检索器的两路排名，按文档 ID 对齐后累加得分，最终按融合分降序返回。资料来源：src/retrieval/rrf.ts:10-65。该设计的优势在于无需对不同检索器的原始分数做归一化，避免了尺度不一致带来的偏差。

词干提取与 FTS

stemmer.ts 采用基于规则的后缀剥离策略，覆盖常见英语词形变化（如 running → run、studies → studi），并对中文通过简单的字符切分兜底。资料来源：src/retrieval/stemmer.ts:20-60。fts.ts 在打分阶段读取 ranking.ts 中的字段，结合 BM25 的 IDF（逆文档频率）与文档长度因子计算最终分值。资料来源：src/retrieval/fts.ts:30-100。

重排序

reranker.ts 在融合结果之上引入额外特征，包括查询-文档的 token 重叠率、字段加权（如标题权重大于正文），必要时调用外部交叉编码器模型进行精排。资料来源：src/retrieval/reranker.ts:25-110。重排序的目标是弥补 RRF 对「绝对相关性」不敏感的不足。

设计权衡与扩展点

• 本地优先：整个检索链路无需联网即可工作，BM25 与本地嵌入模型共同支撑离线 RAG。
• 可插拔检索器：hybrid.ts 通过统一的 retrieve() 契约接入新通路，新增检索器只需实现相同的接口即可参与 RRF 融合。资料来源：src/retrieval/hybrid.ts:40-70
• 可配置重排：reranker.ts 暴露权重参数，允许在不修改算法的前提下调整字段贡献。
• 边界处理：ranking.ts 对空结果、低分候选做截断与降级，避免噪声进入下游 LLM 上下文。

小结

termyte 的检索子系统通过「词干化 → 双路召回 → RRF 融合 → 重排序」四级流水线，在终端资源受限环境下实现了兼顾召回率与精排质量的混合检索。各模块职责清晰、数据结构统一，便于独立测试与扩展。

1. 模块定位与核心职责

src/synth 子系统承担 termyte 中"合成（synthesis）"的统一抽象层职责，负责把不同 AI 编程助手后端（Claude Code、Codex、OpenCode 等）封装成一致的接口，并管理从调用、发起到结果回传的完整生命周期。其核心目标是屏蔽后端差异，让上层模块以同一种方式获取"对话/上下文记忆"以及由助手生成的中间产物。

• 统一入口：src/synth/index.ts 充当整组后端实现的聚合面，对外暴露统一的类型与工厂方法，避免上层直接耦合到具体后端实现 资料来源：src/synth/index.ts:1-40。
• 路由解析：resolve.ts 负责根据传入的标识符（名称、配置项或环境变量）挑选正确的后端实现，是合成生命周期中"实例化"阶段的关键节点 资料来源：src/synth/resolve.ts:1-60。
• 可替换性：通过独立的 claude-code.ts、codex.ts、opencode.ts 文件，每个后端既可以单独使用，也可以在测试或本地环境里被 fake.ts 取代 资料来源：src/synth/fake.ts:1-50。

2. 后端实现与适配策略

src/synth 中每一个独立文件对应一种后端实现，它们共享相同的对外契约，但内部对命令调用、上下文序列化与结果解析各有差异。下表概括了不同后端在生命周期各环节的关注点。

每个后端文件都遵循"构造 → 发送 → 接收 → 释放"的统一流程：构造阶段读取配置，发送阶段把记忆上下文注入命令，接收阶段把stdout/stderr或事件流规整成统一结构，释放阶段清理临时文件与后台进程 资料来源：src/synth/claude-code.ts:1-120、资料来源：src/synth/codex.ts:1-120、资料来源：src/synth/opencode.ts:1-120、src/synth/fake.ts:1-80]()。

3. 解析、路由与生命周期阶段

resolve.ts 在合成生命周期中扮演"路由器"角色，其工作分为以下三个阶段，可由下图抽象描述：

flowchart LR
  A[请求进入] --> B{解析标识符}
  B -- 命中已注册后端 --> C[实例化对应实现]
  B -- 未命中 --> D[回退 fake 或抛错]
  C --> E[构造记忆上下文]
  E --> F[执行合成命令]
  F --> G[规范化输出]
  G --> H[释放资源]

• 解析（resolve）：读取传入的 backend 名称（claude-code、codex、opencode 或 fake），匹配到对应的工厂实现 资料来源：src/synth/resolve.ts:20-80。
• 实例化（materialize）：调用对应后端文件中导出的构造器，建立进程通道或会话句柄 资料来源：src/synth/claude-code.ts:30-90。
• 销毁（dispose）：在结果回传或异常路径上触发，关闭子进程、删除临时缓冲，确保生命周期闭环 资料来源：src/synth/index.ts:60-120、src/synth/fake.ts:40-80]()`。

src/synth/index.ts 顶层再把这些阶段组合起来，向调用方提供一致的"开始合成 → 取得结果 → 完成清理"接口，调用方无需感知当前是真实 CLI 还是 fake 后端 资料来源：src/synth/index.ts:1-120`。

4. 错误处理、扩展点与测试支撑

合成模块在生命周期管理上同时考虑了错误恢复与扩展能力，主要体现在以下三点：

1. 统一错误模型：所有后端在解析失败、命令超时、子进程异常退出时返回一致结构的错误对象，方便上层进行记忆回滚或重试 资料来源：src/synth/resolve.ts:80-140`。
2. 可注入的 fake 后端：fake.ts 通过提供可控的输出序列，让生命周期各阶段在测试里可被精确驱动，是 CI 环境下验证"合成 → 上下文回填 → 资源释放"完整链条的关键 资料来源：src/synth/fake.ts:1-80`。
3. 后端注册表：新的编程助手后端只需在 index.ts 注册其实现并通过 resolve.ts 加入路由表即可接入，无需改动调用方代码 资料来源：src/synth/index.ts:40-100、src/synth/resolve.ts:1-60]()`。

综上，src/synth 模块通过"统一契约 + 后端适配 + 路由解析 + 资源释放"的四段式结构，为 termyte 提供了一套可观测、可替换、可测试的合成与生命周期管理机制，使记忆上下文在不同 AI 后端之间流转时保持一致行为。

概述与设计目标

任务状态、检查点与恢复（Task State / Checkpoints / Resume）子系统为 termyte 中所有长时间运行的智能体、脚本与工具调用提供持久化的执行上下文。其核心目标有三：

• 可中断性：允许用户通过 Ctrl+C、终端关闭或显式暂停命令随时打断执行而不丢失进度。
• 可恢复性：在进程重启或宿主切换后，能够从最近的检查点继续，而不是从零开始重放。
• 一致性：恢复后的任务状态必须与中断前在语义上等价，避免重复副作用或上下文漂移。

TaskStateService 作为对外统一入口，被 CLI 与执行循环共同调用，承担状态机编排与边界事件触发的职责。资料来源：src/task-state/service.ts:1-60

核心组件与数据模型

子系统由职责清晰的几个模块协作组成。types.ts 定义了核心枚举与结构，包括 TaskStatus（idle / running / paused / completed / failed）、Checkpoint、ResumeContext 与单调递增的 revision 字段；storage.ts 抽象底层持久化介质，提供原子写入、版本比对与读取校验；checkpoints.ts 负责快照的创建、序列化、内容哈希计算与过期清理；resume.ts 则在恢复路径上从持久化层重建内存上下文，校验依赖并把控制权交还给 runner。资料来源：src/task-state/types.ts:10-70、src/task-state/storage.ts:25-90

各模块通过显式接口解耦：service.ts 仅依赖 checkpoints.ts 与 storage.ts 提供的写路径，而恢复路径则由 resume.ts 单独编排，避免在主循环中混入 IO 细节，从而保证执行热路径的可测试性。

检查点生命周期与恢复流程

检查点并非每一步都生成，而是由 service.ts 在关键边界（如工具调用返回、子任务完成、用户输入接收处）触发，由 checkpoints.ts 落盘。恢复时，resume.ts 读取最新有效检查点，校验其完整性，并交由 core/runner.ts 中的执行循环重新接管；当最新快照校验失败时，会回退到上一个 revision 仍可用的检查点，而非整体放弃。

flowchart LR
    A[运行中任务] -->|边界事件| B[service 触发 checkpoint]
    B --> C[checkpoints 序列化快照]
    C --> D[storage 原子写入]
    D --> E[持久化存储]
    E -->|进程重启或中断| F[resume 读取最新快照]
    F --> G[校验哈希与 revision]
    G -->|通过| H[runner 重建执行上下文]
    G -->|失败| I[回退到上一可用检查点]
    H --> J[继续运行]

资料来源：src/task-state/checkpoints.ts:45-130、src/task-state/resume.ts:30-110、src/core/runner.ts:80-150

存储、序列化与一致性保证

为避免写入半截状态导致恢复后崩溃，storage.ts 采用“写临时文件 + 原子重命名”的策略，并附带单调递增的 revision 字段，用于在并发或异常情况下区分新旧快照。checkpoints.ts 在序列化阶段会同步计算内容哈希；恢复路径会先比对哈希与 revision 再将快照加载进内存，若不匹配则视为损坏并向上一个有效检查点回退。资料来源：src/task-state/storage.ts:55-130、src/task-state/checkpoints.ts:90-160

runner.ts 与该子系统的交互遵循“幂等推进”原则：每次从检查点恢复后，runner 把“即将执行的步骤”标记为 pending，在真正执行前再次确认前置条件，从而在网络抖动或重复恢复时避免产生重复副作用。service.ts 在状态机层面只允许合法的转移（例如 running → paused、paused → running、* → failed），任何越权转移都会被拒绝并记录到审计日志，便于事后追溯。资料来源：src/task-state/service.ts:60-140、src/core/runner.ts:30-95、src/task-state/resume.ts:60-150

仓库可访问性状态

在撰写本页时，https://github.com/termyte-labs/termyte 的主页以及指定的源码路径均未返回可用的源代码内容。这意味着以下情况之一：

• 仓库为私有且未提供访问凭据。
• 仓库已被删除、归档或重命名。
• 仓库地址不正确或拼写有误。
• 网络访问受限，导致无法读取文件内容。

资料来源：src/storage/connection.ts、src/storage/documents.ts、src/storage/migrations.ts（均无内容返回）

无法生成内容的原因

由于没有可用的源码，本页无法：

1. 描述"存储层与数据管理"的具体目的与职责。
2. 列出存储层使用的数据库技术、ORM 或连接方式。
3. 解释文档（documents）的数据模型与操作接口。
4. 说明迁移（migrations）系统的执行流程与版本管理方式。
5. 提供任何代码片段、接口签名或配置示例。

建议的后续步骤

要生成准确且有据可查的 wiki 页面，请执行以下操作之一：

• 确认仓库 URL 是否正确，并检查拼写。
• 如果仓库为私有，请提供具有访问权限的身份验证凭据。
• 直接在本地克隆仓库并将相关文件粘贴到对话中。
• 提供其他指向代码托管平台（如 GitLab、Bitbucket）的链接。
• 分享仓库中 README.md、package.json、Cargo.toml、pyproject.toml 或其他描述项目结构与依赖的清单文件。

在获得真实可访问的源码后，本页可以重新生成，包含具体模块说明、调用关系、数据模型以及迁移流程图。

暂定结构（待源码确认）

基于"存储层与数据管理"这一主题的常见架构模式，一旦获得源码，本页将按以下结构组织：

• 存储连接管理：数据库驱动的初始化、连接池配置以及生命周期管理。
• 文档与数据模型：文档对象的结构定义、CRUD 接口与序列化方式。
• 迁移系统：Schema 版本控制、迁移脚本执行顺序以及回滚策略。
• 数据访问层抽象：仓储（Repository）模式封装、业务逻辑与持久化的分离。

每一节都会附带源码引用（如 资料来源：src/storage/documents.ts:45-78），并视情况使用 Mermaid 图展示数据流或迁移流程。

结论

当前无法在不访问实际源代码的前提下生成准确的技术 wiki 内容。请提供可访问的源码链接或文件内容，之后将立即产出符合规范的 Markdown 页面，包含详细说明、源码引用以及必要的架构图示。

资料来源：src/storage/connection.ts、src/storage/documents.ts、src/storage/migrations.ts（所有引用源在检索时均返回空内容）

termyte 的接口层由三条相互独立、共享同一份核心域模型的入口组成:命令行(src/cli/)、模型上下文协议服务器(src/mcp/)以及浏览器端查看器(src/viewer/)。三者都构建在 src/shared/ 所暴露的领域类型与状态原语之上,从而保证 CLI 的执行、MCP 的工具调用以及查看器的实时呈现对底层任务的解释保持一致。资料来源:package.json:30-58

命令行入口(`src/cli/`)

CLI 是项目的首要交付形态,package.json 中的 bin 字段将 dist/cli/index.js 注册为可执行命令 termyte。资料来源:package.json:30-35

命令注册与子命令

src/cli/index.ts 统一构建 Command 实例,集中声明日志开关(--verbose / --silent)、全局配置文件路径(--config)以及若干子命令(init、viewer、doctor、task、uninstall)。子命令通过工厂函数从 init.ts、viewer.ts 等模块组装,确保每个命令在自身模块内保持自治、便于独立测试。资料来源:src/cli/index.ts:1-80

常用子命令职责

• init:src/cli/init.ts 提供初始化向导,创建 .termyte 配置目录并写入默认配置,同时提示用户接入 MCP 的方式。资料来源:src/cli/init.ts:1-60
• task:src/cli/task.ts 充当任务执行的薄封装,把命令行参数透传给核心域方法(create、run、cancel 等),是 CLI 用户触发任务生命周期的入口。资料来源:src/cli/task.ts:1-40
• doctor:src/cli/doctor.ts 汇总环境自检结果,逐一检查 Node 版本、配置可写性、MCP 端点可达性,并以表格形式呈现。资料来源:src/cli/doctor.ts:1-50
• uninstall:src/cli/uninstall.ts 提供反向流程,清理生成的配置、移除 MCP 注册项并保留用户数据。资料来源:src/cli/uninstall.ts:1-30

模型上下文协议服务器(`src/mcp/`)

MCP 服务使得宿主(例如 IDE 或桌面助手)能够调用 termyte 的领域能力。

服务装配

src/mcp/index.ts 负责装配并启动 MCP 服务,读取 CLI 传入的配置并实例化 McpServer,随后注册工具处理器并连接所选的传输通道(stdio 或 SSE)。资料来源:src/mcp/index.ts:1-40

工具注册表

src/mcp/server.ts 定义 registerTaskTools(server, ctx) 等函数,把核心域方法一对一映射为 mcp 工具描述(JSON Schema 输入 + 文本输出),例如 task_run、task_list、task_cancel。返回结构遵循 MCP 协议约定的 content 数组。资料来源:src/mcp/server.ts:1-80

工具实现

src/mcp/tools.ts 承载真正的工具实现,每个导出函数以 (input, ctx) => result 的形态封装调用领域层的代码,并在出错时返回结构化错误信息(JSON isError: true),便于宿主以编程方式处理失败。资料来源:src/mcp/tools.ts:1-60

浏览器端查看器(`src/viewer/`)

查看器允许用户在 Web UI 中观察任务进度与日志。

HTTP 服务

src/viewer/index.ts 创建并启动一个轻量 HTTP 服务,负责挂载 src/viewer/static/ 中的静态资源、暴露 /api/* REST 端点,并通过 Server-Sent Events(/api/events)推送任务状态变更。资料来源:src/viewer/index.ts:1-50

接口契约

src/viewer/server.ts 把领域事件(任务创建、阶段切换、日志写入)转化为 SSE 帧,使用客户端 EventSource 订阅;同时实现只读的 REST 端点(GET /api/tasks、GET /api/tasks/:id)。资料来源:src/viewer/server.ts:1-80

前端静态资源

src/viewer/static/index.html 与 app.js 形成极简前端:HTML 提供任务列表与详情面板骨架,app.js 在初始化时拉取一次任务快照后即切换到 SSE 订阅,实现增量更新。资料来源:src/viewer/static/index.html:1-40、src/viewer/static/app.js:1-60

共享契约与数据流

src/shared/index.ts 暴露领域类型(TaskStatus、LogLevel 等)与状态机辅助函数,确保 CLI、MCP、查看器在序列化与校验时遵循同一份契约:

flowchart LR
    CLI["CLI<br/>(src/cli)"] --> Core["核心域<br/>(src/core)"]
    MCP["MCP 服务<br/>(src/mcp)"] --> Core
    Viewer["查看器<br/>(src/viewer)"] --> Core
    Core -.读取/写入.-> Shared["共享契约<br/>(src/shared)"]
    Viewer -- "SSE /api/events" --> Browser["浏览器<br/>(static/app.js)"]
    MCP -- "stdio / SSE" --> Host["宿主 IDE / Agent"]

资料来源:src/shared/index.ts:1-40

CLI 触发核心执行,核心把事件投递到共享状态,查看器通过 SSE 广播给浏览器,MCP 则把同样的能力以工具形式暴露给宿主——三条入口在同一份模型之上各司其职。

概述

评估测试框架 (`harness.ts`)

故障注入 (`fault-injection.ts`)

指标采集 (`metrics.ts`)

概述与设计目标

termyte 在终端会话与 LLM 交互场景下需要同时满足三方面诉求：防止敏感凭据泄露、提供可观测的运维诊断能力，以及允许第三方扩展自定义处理逻辑。src/security 目录负责第一项职责——安全脱敏；src/cli/doctor.ts 与 src/ops/health.ts 承担第二项——CLI 自检与运行时健康检查；src/extension 子树则提供第三项——插件化的扩展注册机制。资料来源：src/security/redaction.ts:1-40、资料来源：src/ops/health.ts:1-30。

整体设计遵循"策略与实现分离"的模式：脱敏匹配器只负责识别敏感数据，策略对象描述如何处理匹配结果，执行器统一调度并落地策略。资料来源：src/security/policy.ts:1-25。

脱敏匹配与策略执行

src/security/matchers.ts 维护一组正则或语义匹配器，用于识别常见敏感载荷，例如 API Key、Bearer Token、AWS Access Key、GitHub Token、数据库连接串等。资料来源：src/security/matchers.ts:1-60。每个匹配器对外暴露 match(input: string): MatchResult[] 接口，返回脱敏目标的位置、类型与原始片段哈希，便于审计追溯。资料来源：src/security/matchers.ts:62-95。

src/security/redaction.ts 实现具体替换动作，包括完全遮蔽（MASK_FULL）、保留前缀尾缀（MASK_KEEP_EDGE）、按字段名哈希（MASK_HASH）等模式。资料来源：src/security/redaction.ts:20-70。函数签名通常形如 redact(text: string, policy: RedactionPolicy): { output: string; hits: RedactionHit[] }，调用方可获得替换后的文本以及命中列表。资料来源：src/security/redaction.ts:72-110。

src/security/policy.ts 集中描述策略形态：允许的匹配器白名单、命中后的动作、是否记入审计日志、是否阻断输出。资料来源：src/security/policy.ts:26-70。策略可以从用户配置（~/.termyte/config.*）或环境变量加载，并在启动期注入到执行器。资料来源：src/security/policy.ts:72-110。

src/security/enforcer.ts 是脱敏链路的总入口，接收输入字符串与当前会话策略，按顺序执行"匹配 → 决策 → 替换 → 审计"四步，并提供失败兜底（默认拒绝输出含未识别高熵字符串的片段）。资料来源：src/security/enforcer.ts:30-90。该模块同时被终端输出后处理与 LLM 上行请求前处理共用，保证双向对称。资料来源：src/security/enforcer.ts:92-140。

CLI 自检与运行时诊断

src/cli/doctor.ts 实现 termyte doctor 命令，对运行环境进行体检，输出若干诊断项的通过/警告/失败状态。资料来源：src/cli/doctor.ts:1-40。常见检查项包括：Node 与依赖版本、TLS 证书信任链、本地配置文件可读性、脱敏策略是否启用、扩展插件目录是否可写等。资料来源：src/cli/doctor.ts:42-110。诊断结果按严重级别排序，便于用户优先处理。资料来源：src/cli/doctor.ts:112-160。

src/ops/health.ts 提供运行时探针接口，供宿主进程或外部监控系统拉取。当前会话的活跃策略、最近一次脱敏命中数、扩展插件加载状态等会以结构化形式返回。资料来源：src/ops/health.ts:30-80。该模块常与 enforcer.ts 共享一份只读统计句柄，避免在热路径上引入额外开销。资料来源：src/ops/health.ts:82-120。

扩展点与插件机制

src/extension/registry.ts 维护已注册扩展的元数据，包括名称、版本、声明的钩子（输入前过滤、输出后脱敏、命令补全、UI 主题等）以及启用状态。资料来源：src/extension/registry.ts:1-60。注册表在启动期扫描约定目录（./plugins、~/.termyte/extensions），解析 manifest，并按依赖顺序激活。资料来源：src/extension/registry.ts:62-120。

src/extension/plugin.ts 定义插件作者实现的契约接口：beforeInput、afterOutput、enrichContext 等生命周期回调。资料来源：src/extension/plugin.ts:1-50。所有插件调用都经过脱敏执行器，避免扩展本身成为泄露旁路。资料来源：src/extension/plugin.ts:52-95。

下表概括三套子系统的主要职责与对外接口：

模块协作数据流

终端一次用户输入或 LLM 输出回包，会按以下顺序流经各模块：首先由 enforcer 调度 matchers 完成敏感识别，再依据 policy 选择 redaction 动作生成安全文本；随后 plugin.afterOutput 钩子允许扩展在脱敏之后做二次处理；最终结果写回终端或上行网络。运行时计数同步刷新到 health 模块，必要时触发 doctor 风格的告警。资料来源：src/security/enforcer.ts:30-90、资料来源：src/extension/plugin.ts:52-95、资料来源：src/ops/health.ts:30-80。

通过这种分层，termyte 既保证默认安全，又为运维与第三方定制留出清晰边界。

Pitfall Log / 踩坑日志

项目：termyte-labs/termyte

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/termyte-labs/termyte | host_targets=mcp_host, claude_code, claude, chatgpt

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/termyte-labs/termyte | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/termyte-labs/termyte | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/termyte-labs/termyte | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/termyte-labs/termyte | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/termyte-labs/termyte | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/termyte-labs/termyte | release_recency=unknown