常用概念词典

这份词典用于阅读时快速查阅。定义优先解释它在 DeepSeek Harness 中的具体含义，不追求覆盖同名术语在整个软件行业里的所有用法。

A

ACP（Agent Client Protocol）

一种让外部客户端通过协议创建、驱动和取消 Agent Session 的接口。仓库中的 ACP 入口面向自动化客户端，处理 JSON-RPC/stdio、权限回答、状态和生命周期；它不是 AgentLoop 本身。

Adapter

把外部 Provider 的 API 转换成 Harness 统一接口的实现。LLM Adapter 把统一 GenerateOptions 转换成厂商请求，再把厂商流式事件转换成 StreamChunk。

Agent

一个可接收输入、运行 Turn、取消、等待 idle 并拥有 Session 的活动对象。外部消费者依赖公开 Agent 接口，而不是 AgentLoop 的内部具体类。

AgentHandle

程序化创建 Agent 后返回的所有权 handle。持有者通过它访问 Agent，并负责 dispose；dispose 需要等待 Agent 资源与进行中的工作安全收敛。

AgentLoop

默认的具体 Agent 驱动。它领取 Inbox、建立 Turn/Step、组装模型请求、调用 LLM、执行工具并写 SessionEvent。新产品功能通常挂扩展点，而不是直接修改循环。

Append-only

只在末尾追加新记录，不原地修改旧记录。Session 使用 append-only event log；当前显示状态可以通过 replacement 或最新 snapshot 派生，但旧事实仍保留。

AsyncIterable

可以异步逐项产生值的对象。LLM 流式响应常以它表达，调用方使用 for await 消费 chunk。

AbortSignal

协作式取消信号。它通知异步操作应停止，但不能强制终止任意同进程代码。消费者必须观察或转发 signal，并在取消后释放资源。

B

Branded ID

在 TypeScript 中给字符串等基础类型加领域品牌，例如 SessionId、MessageId、CallId。运行时值可能相同，但编译器阻止不同 id 类型混用。

Bundle

可安装的 Cordis 配置与代码组合层。Profile 叠加一个或多个 Bundle，再应用本地 patch，形成实际部署。

C

Capability

一项可被其他组件使用的能力，例如 LLM、Shell、FS、Persistence、Subagent 或 Web。能力不一定面向模型，也可以供内部插件、入口或协议使用。

Capability Seam

可替换能力的完整分层，包括 Service Definition、Service Provider 和 Consumer。它还需要明确配置、取消、失败和测试，而不只是声明一个接口。

CallId

一次 Tool Call 的标识符。tool/call 与 tool/result 通过同一 CallId 配对。

Canonical Output

Tool 执行返回的规范 JSON 值。它先通过输出 schema 校验，再渲染成模型 ContentBlock 和 UI metadata。规范值用于保证成功结果可验证、可持久化。

Compaction

把一段当前模型 surface 替换为摘要节点，从而缩短后续模型上下文。它通过追加 replacement 表达，不删除原事件，并保持 Tool Call/Result 配对边界。

Consumer

使用某项 Service 的组件。模型 Tool 常是 Consumer，但命令、协议入口、UI 或内部插件也可以是 Consumer。

ContentBlock

模型消息内容的结构化块，例如文本、推理、图片、Tool Call 或 Tool Result。统一 ContentBlock 让不同 LLM Provider 使用相同上层协议。

Context（Cordis Context）

插件访问 Service、注册事件/effect、挂载子插件并携带作用域与生命周期所有权的对象。它不只是普通全局变量容器。

Context Window

模型一次请求能容纳的总上下文容量。历史、系统提示词、工具 schema 和预留输出都消耗容量；Compaction 和 pruning 用来控制增长。

D

Declaration Merging

TypeScript 允许多个模块声明合并到同一接口。Harness 用它扩展 Cordis Context、Events 和 SessionEventMap。它只改变类型，不会自动完成运行时注册。

Discriminated Union

通过共同标签字段区分分支的联合类型，例如 { kind: 'deny' } 与 { kind: 'allow' }。switch 标签后，TypeScript 能缩小具体字段。

Disposer

撤销注册或释放资源的函数。工具、Provider、事件监听器和提示词贡献都应有 disposer，并绑定插件生命周期。

Durability

数据在进程退出或崩溃后仍可恢复的性质。内存 Session append 不自动等于持久化完成，flush 是明确的 durability 观察点。

E

Effect

由 Cordis 生命周期拥有的注册或资源。ctx.effect() 把建立与释放配对，插件卸载或 HMR 时自动撤销。

ESM

JavaScript 的标准模块系统，使用 import/export。仓库全面采用 ESM，源文件相对导入带 .ts，发布产物通过 package exports 运行。

Event Sourcing

用按顺序记录的事实事件作为状态来源，再从事件派生当前状态。Session 是事件溯源模型：模型历史、UI 和恢复从 SessionEvent log 派生。

F

Fiber

Cordis 中承载插件实例及其生命周期状态的运行单元。父插件挂载子插件形成 fiber tree；dispose fiber 会释放它拥有的 effect 和子节点。

Flush

要求持久化层把此前待写事件写到后端并等待收敛的操作。它不是普通 append，也不等同于 Agent idle。

Followup

把用户角色消息放入 Agent 的 next-turn 队列并唤醒它，通常用于开始下一项工作。

Fork

从源 Session 某个边界复制事件前缀，创建具有新 SessionId 和 parent lineage 的子 Session。

G

Goal

同一 Session 内可持久化的目标领域状态。Goal Tool 和 Round Driver 通过公开扩展点读写状态并安排后续轮次。

Guard

在 Tool Registry 中表达不能被后续策略放宽的单调约束。普通 pre-execute waterfall 适合可组合决策，guard 适合最终安全拒绝。

H

HMR（Hot Module Replacement）

运行中卸载旧插件并挂载新插件。正确的 effect/disposer 让旧注册、计时器和资源不会残留。

Headless

没有 Web UI 的一次性 Agent 入口。它接收一项任务、运行 Agent、输出最终结果并退出，也用于真实模型和快照组合。

I

Inbox

Agent 的统一待处理输入结构，包含 next-turn 和 next-step 两个目标。followup、steer 和 inject 是不同预设。

Inject

把上下文消息放入 next-step Inbox，但不单独唤醒 Agent。适合技能内容、文件变化和运行时上下文，在下一次已有请求中进入模型。

inject（Cordis 插件字段）

插件声明的运行时 Service 依赖。与 Agent.inject 同名但含义不同；它让 Cordis 在依赖可用时激活插件。

Invariant

对拥有关系、事件关系或可重建性进行运行时验证的规则。Invariant 应检查权威数据关系，不靠“某个方法存在”之类弱信号。

J

Job

有 owner、状态、输出、取消与清理的后台工作。Job Registry 不要求任务一定是子 Agent，也不理解模型语义。

JSONL

每行一个 JSON record 的逻辑格式。Session Persistence 的 JSONL 后端为每个 Session 保存独立 artifact，物理编码可以压缩或保留原始行。

K

KV Cache

模型 Provider 对相同请求 token 前缀的计算复用。系统提示词、工具 schema 或早期历史改变时，变化点之后的缓存通常需要重算。

L

LLM

大语言模型能力。Harness 的 LLM Service 统一消息、内容块、调用配置、流式 chunk、模型发现与 Adapter 注册。

Loader

读取 Cordis 配置并挂载插件树的组件。它处理 config、disabled、include、依赖激活和 HMR 等组合行为。

M

Message

发送给 LLM 的角色消息，通常是 user、assistant 或 tool result。Message 是 Session surface 的派生结果，不是完整 Session 日志。

MessageId

一条用户或助手消息的品牌标识符，用于 Inbox、来源和协议关联。它不能与 CallId 或 SessionId 混用。

Model-visible

模型请求能够看到的内容。仓库要求模型可见输入可以从 Session log 与 request header 重建。

O

Overlay / Patch

在 Bundle 默认配置之上替换或插入 Cordis 配置行的层。后层按稳定 id 指向目标，常用于部署选择和本地覆盖。

Owner

负责资源生命周期的组件或 handle。Owner 必须决定何时释放、取消和等待 quiescence，不能只把资源放进全局 Map。

P

Persistence

把 SessionEvent 与 Header 写入耐久后端，并提供 locate、append、flush、prepare、load、inspect、list 等能力的 Service Definition 与 Provider。

Plan Mode

记录 Agent 与用户处于计划协作阶段的状态及交互插件。它影响提示词和策略，但不替代独立权限与沙箱限制。

Plugin

由 Cordis 挂载、拥有 Context 和生命周期的功能单元。插件可提供 Service、注册事件、贡献 Tool/Prompt 或挂载子插件。

Profile

一次部署的命名组合，列出要叠加的 Bundle，并拥有本地 patch。Web 与 Headless 可以使用不同 Profile。

Prompt Section

注册到 System Prompt 的有序文本贡献。不同插件可以贡献 identity、persona、工具说明等 section。

Provider

实现一项 Service Definition 或向注册表注册具体后端的插件。例如 bash-local 是 Shell Provider，llm-deepseek 是 LLM Adapter Provider。

Q

Quiescence

资源不再有进行中的自有工作、回调或未完成清理的稳定状态。Dispose 和取消通常需要等待 quiescence，不能只发信号就返回。

R

Replay

用已记录的事件重建 Session 与输出。测试中 Replay Adapter 可以根据录制输入产生确定模型流，不调用真实 API。

Request Header

记录模型调用 config、Adapter 默认来源、系统提示词和 Tool Schema 的 Session snapshot。它不直接成为聊天 Message，却是请求可重建性的一部分。

Resume

从持久存储加载同一 SessionId，并继续其历史与编号。不同于 Fork，Resume 不创建新的 child identity。

Runtime Context

当前运行环境等会变化的模型可见信息。它通过动态 context snapshot 持久进入 Session，避免 Resume 时依赖已丢失的临时变量。

S

Sandbox

在操作系统或执行 Provider 层限制进程能访问的资源。它不等同于 Permission；允许的命令仍可在受限环境中运行。

Schema

运行时验证配置、Tool 参数、Tool 输出或持久数据的规则。TypeScript 类型编译后消失，跨 JSON、模型、文件和进程的值需要 schema 校验。

Scope

贡献的可见范围。每个 Agent 可以拥有 scoped Context，使同名 Prompt、Tool 或模型选择覆盖或补充全局注册。

Service

通过稳定 ctx key 暴露的运行时 API。消费者依赖 Service，而不是具体 Provider 实现。

Session

一个 Agent 交互的 append-only typed event log 及 metadata。它是模型历史、回放、UI 和持久化的共同事实来源。

SessionEvent

Session 日志中的不可变事件，带 type、seq、time 和类型对应的 data。部分 surface 事件还带来源与替换 metadata。

Skill

可发现、按需加载的模型指导包。Skill Registry 聚合 Provider，Skill Tool 让模型查看和加载内容，加载内容进入可重建的 Agent 输入。

Step

一次模型请求，加上该次模型回复要求的 Tool 执行。一个 Turn 可以包含多个 Step。

Steer

把消息放入 next-step Inbox 并唤醒 Agent，适合在当前工作中追加下一步指令。

StreamChunk

LLM Adapter 产生的统一流式输出单元，包括文本增量、推理增量、Tool Call block 和结束信息等。

Surface

从完整 Session 日志中选出的当前模型可见节点序列。Compaction replacement 可以改变当前 surface，而不删除旧事件。

System Prompt

在每个模型 Step 组装的系统指令。它由有序 section、变量、动态 context 和 Tool Schema Provider 共同构造，不是单一硬编码常量。

T

Tool

模型可以调用的 Host 能力描述。ToolDefinition 包含模型 schema、canonical output、执行函数、调度 metadata 和 UI presentation。

Tool Call

模型输出的工具调用请求，包含 CallId、name 和 arguments。系统必须为每个 Call 形成对应 Result，包括解析失败、拒绝和取消。

Tool Result

工具调用的模型可见最终结果。它作为 Session surface 节点进入后续模型请求，并可携带 JSON meta 用于 UI replay。

Turn

从一次工作被接纳开始，到系统不再欠 Tool、next-step 或继续动作结束的生命周期。可以包含零个或多个 Step。

Typert

仓库的类型图生成、加载和运行时注册体系，用于 Host API 与 Client Remote projection。初学主线可以先跳过，学习 Web/API 层时再深入。

W

Waterfall

Cordis 的 around-middleware 事件模式。监听器调用 next 继续下游，也可以返回结果短路；请求、策略和工具执行管线大量使用。

Workflow

运行动态结构化流程或代码的能力。Worker Provider 提供执行环境，Tool Consumer 把它暴露给模型；最终结果仍通过普通 Tool Result 回到父 Step。

快速辨析

Turn 与 Step

Turn 是一项工作生命周期；Step 是一次模型请求及其工具执行。

Session 与 Message History

Session 是完整事件日志；Message History 是从当前 surface 派生的模型协议消息。

Permission 与 Sandbox

Permission 决定是否允许调用；Sandbox 限制被允许的执行能访问什么。

Resume 与 Fork

Resume 继续同一 SessionId；Fork 从历史前缀创建新 SessionId。

Plugin 与 Service

Plugin 是有生命周期的贡献单元；Service 是插件通过 Context 暴露给消费者的稳定 API。

Provider 与 Consumer

Provider 实现能力；Consumer 使用能力。Tool 经常是 Consumer，但不是唯一 Consumer。

Agent.inject 与插件 inject

Agent.inject 向 next-step Inbox 添加模型上下文；插件 inject 声明运行时 Service 依赖。