附录 A · 术语表
读蓝皮书或官方文档时遇到的术语，按类别整理在这里。每个术语给一句话解释，不展开，需要深入的翻对应章节。
架构类
| 术语 | 一句话解释 |
|---|---|
| Cordis | dsh 底层的插件框架，提供服务注册、类型化事件、可逆副作用三大原语。dsh 的一切能力都跑在它上面 |
| Plugin（插件） | dsh 的最小能力单元，一个导出 apply(ctx) 函数的模块。启动时被加载，通过 ctx 注册工具、监听事件、提供服务 |
| Bundle（组合包） | 插件的发布格式，一个 npm 包，声明自己往运行时贡献哪些插件和配置。装插件本质是装 bundle |
| Profile（配置档） | 一组插件的组合配方，决定"这棵插件树长什么样"。web、headless 都是 profile，存在 $DSH_HOME/profiles/ 下 |
| Context（ctx） | 插件加载时拿到的上下文对象，无所不能——注册工具、调用服务、监听事件、读写配置，全靠它 |
| Service（服务） | 插件通过 ctx 提供的可复用能力，其他插件可以调用。比如会话服务、工具注册服务 |
| Event（事件） | 插件之间通信的方式，发布/订阅模式。比如工具执行前发 tools/pre-execute 事件，其他插件可以订阅拦截 |
| Effect（副作用） | 插件对运行时的修改（注册工具、添加配置等）。卸载插件时按相反顺序撤销，保证干净还原 |
| Seam（接缝） | 插件与插件之间的接口约定，一个插件声明"我需要什么能力"，另一个提供"我有这个能力"，系统自动匹配 |
运行类
| 术语 | 一句话解释 |
|---|---|
| Agent Loop（Agent 循环） | "思考→调工具→看结果→再思考"的迭代循环，直到任务完成或达到终止条件。Agent 和聊天机器人的本质区别就在这 |
| Turn（轮次） | 用户发一条消息到 Agent 给出最终回复，算一轮。一轮内部可能包含多次工具调用 |
| Step（步骤） | Agent 循环里的一次迭代，可能是一次模型调用或一次工具调用。一轮 = 多个 step |
| Session（会话） | 一次完整的对话上下文，绑定工作区，持久化存储。关掉 dsh 再打开还能继续 |
| Trajectory（轨迹） | 会话的完整执行记录——系统提示、模型请求、工具调用、子代理调度，全部按时间线记下来 |
| Headless（无头模式） | 不需要界面的运行方式，一条命令跑完一个任务就退出。适合自动化、CI/CD、定时任务 |
| Web UI | 浏览器界面，交互式对话。dsh web 启动，默认地址 http://127.0.0.1:3080 |
| Fork（分叉） | 在会话的某个历史节点开一条新路，原会话保留。适合"试试另一种做法" |
| Compaction（压缩） | 把早期对话总结成一段摘要，替换原始历史，释放上下文空间。/compact 命令手动触发 |
工具与能力类
| 术语 | 一句话解释 |
|---|---|
| Tool（工具） | Agent 能调用的函数，比如读文件、执行命令、搜索网页。每个工具有 Schema（参数定义） |
| Tool Schema | 工具的参数定义，告诉模型这个工具接受什么参数、什么类型。模型按 Schema 构造调用 |
| MCP（Model Context Protocol） | 模型上下文协议，一套标准接口，让 Agent 能接入外部工具服务器。dsh 通过 dsh-mcp-client 插件支持 |
| MCP Server（MCP 服务器） | 提供一组工具的外部服务，比如 Firecrawl（抓网页）、GitHub（操作仓库）。dsh 接进来后 Agent 就能用这些工具 |
| Skill（技能） | 一段写给模型的指令，告诉它"遇到这类任务按这套步骤来"。存在工作区或用户目录，模型按需加载 |
| Subagent（子代理） | 主代理派出去干子任务的独立 Agent，干完把结果交回来。有两种模式：subagent（不带历史）和 subagent_fork（带历史） |
| Workflow（工作流） | 多步骤的编排，把多个任务按顺序或分支串起来。单步固定套路用 Skill，多步串联用 Workflow |
| Provider（模型提供商） | 提供模型 API 的服务方，比如 DeepSeek、OpenAI、Anthropic。dsh 通过 Model Adapter 接不同 provider |
安全类
| 术语 | 一句话解释 |
|---|---|
| Sandbox（沙箱） | 限制 Agent 能访问哪些文件和资源的隔离机制。OS 内核级，不是 JS 判断，模型绕不过去 |
| Permission（权限） | 三档：read-only（只读）、workspace-write（默认，只能写工作区）、danger-full-access（不限制） |
| Approval（审批） | Agent 想做超出权限的操作时，弹窗问你同不同意。允许一次就是一次，不是永久放行 |
| Write-only（只写） | API Key 的存储方式——保存后界面不回显明文，只显示脱敏描述符。明文只在本地 .credentials.yaml |
模型类
| 术语 | 一句话解释 |
|---|---|
| Model Adapter（模型适配器） | 把不同模型提供商的 API 统一成 dsh 内部标准接口的插件。换模型 = 换适配器，不用改其他代码 |
| LLM（大语言模型） | Large Language Model，负责思考和生成文本的核心。dsh 本身不包含模型，只负责调度 |
| KV Cache（键值缓存） | 模型推理时缓存已计算的前缀，后续请求前缀相同时直接复用，不用重新计算。命中部分按远低于正常价格计费 |
| Context Window（上下文窗口） | 模型一次能处理的最大 token 数。超出部分不会发给模型，等于"遗忘" |
| Token | 模型处理文本的基本单位，中文约 1 字 = 1.5 token，英文约 4 字符 = 1 token。计费和上下文限制都按 token 算 |