Appearance
5.3 术语表
本章概览：DSH 领域词汇的规范定义（基于官方
docs/glossary.md整理并扩展本站用语）。"一个概念一个规范术语"，避免歧义。
官方出处：
docs/glossary.md（deepseek-harness-src/docs/glossary.md）
能力缝（capability-seam）
| 术语 | 定义 |
|---|---|
| seam（能力缝） | 一项可替换能力，含三个角色：Service Definition（拥有 ctx.<key> 与词汇表的 Cordis Service）、一个或多个 Service Provider、一个或多个 Consumer（注入该服务的消费方）。packages/shell 是规范示例：dsh-shell（定义）、dsh-bash-local/dsh-bash-sandbox（提供方）、dsh-tool-bash（消费方）。seam 是完整能力，绝不只是单个角色 |
| Service Definition | 声明接口的角色；依赖纪律：只依赖 cordis（+ 必要基础类型） |
| Service Provider | 实现接口、可替换的角色 |
| Consumer | 消费接口的角色，通常是面向模型的工具 |
Agent 作用域（agent-scope）
| 术语 | 定义 |
|---|---|
| scope（作用域） | 按 agent 注册的单元：一个贡献（工具、提示片段、变量、限制、监听器）要么 global（对所有 agent 可见），要么 scoped（只属于一个 scope key）。两层、扁平：scoped 注册不向下继承给子代理 |
| scope key | 作用域的不透明身份，按对象同一性比较；惯例：活 agent 是自己作用域的 key |
agent context（agent.ctx） | agent 的作用域上下文；经它的注册既作用域可见又作用域生命周期（一个事实驱动两者） |
| scoped dispatch | 规则：关于某 agent 活动的事件以该 agent 的载体派发；关于注册表自身的事件（如添加了工具）不设过滤 |
| shadowing（遮蔽） | 最近者胜的名称解析：scoped 工具/片段/变量对该作用域替换同名 global 孪生 |
| restriction（限制） | tools.restrict 对一个作用域过滤 global 工具集（交集组合）；被过滤掉的工具在提示词中缺席且拒绝执行，与不存在无异 |
| setup window（设置窗口） | 创建槽位：CreateAgentOptions.setup 在 agent 对象存在但未发布前组合 scoped 世界；setup 只注册，不驱动 agent |
| lineage（血统） | 作为数据携带的父子事实（parentSession、持久 delegationDepth、运行时 subagentDepth）；绝不影响可见性 |
目标（goal）
| 术语 | 定义 |
|---|---|
| goal（目标） | 附加在既有会话上的一个持久完成目标，带 revision 化的 active/paused/blocked/complete 阶段与轮次上限；blocked 保留策略码与说明。目标是状态，不是调度器或独立对话；会话日志是其真相源 |
| goal round（目标轮次） | 为当前目标准入的一次续跑周期；同会话驱动器把它物化为一个 goal 源头的 turn（可含 0..n 个 step）；无关的人类轮次不消耗目标轮次上限 |
| goal activation（目标激活） | 让续跑消费者准入下一目标轮次的进程本地许可；激活是 armed/disarmed，刻意不持久化——恢复/续跑需要后来的显式人类授权 |
人类命令（human command）
| 术语 | 定义 |
|---|---|
| human command（人类命令） | 斜杠前缀指令，由人类面向的适配器经 ctx.commands 解释执行，不成为模型消息；区别于模型侧工具与 shell 命令执行 |
| command plane（命令平面） | 由 UI 适配器与命令插件拥有的发现、解析、派发、取消与结果渲染；命令输出是 UI 状态（除非 handler 另行变更持久领域） |
| goal command | dsh-command-goal 贡献的 /goal 人类命令，直接观察或变更当前目标 |
循环层级（loop hierarchy）
| 术语 | 定义 |
|---|---|
| turn（轮次） | 会话中一次已准入输入的排空，在模型与工具停止或终止策略介入后结束 |
| step（步骤） | 一次模型请求 + 其响应引起的工具执行；一个轮次含 0..n 个步骤 |
| round（轮） | 含一个 turn 的外层策略迭代，如 goal round 或一次 fresh-agent Ralph 尝试；轮计数器属于该策略，不数会话中每个 turn |
Ralph
| 术语 | 定义 |
|---|---|
| Ralph loop | 一次前台 fresh-agent 工作流向不可变目标；是由 workflow 与 subagent 原语组合成的模型侧工具策略——不是同会话 goal、agent-loop 模式、调度器或通用 workflow 脚本功能 |
| Ralph round | Ralph loop 中的一次新子会话；孩子不接收父或先前孩子的对话种子；共享工作区与一个有界 Ralph 交接物承载跨轮状态 |
| Ralph handoff（交接物） | 从一轮传到下一轮的有界结构化报告：状态、摘要、证据、下一步、阻塞文本；补充而非取代共享工作区 |
本站补充术语（对应本站章节）
| 术语 | 定义 | 本站章节 |
|---|---|---|
| profile | Harness home 中的具名组装：组合包列表 + 树外插件 + 用户 patch 层 | 0.3 |
| bundle（组合包） | Cordis 配置项及其挂载代码的分发格式（dsh.bundle.patch） | 1.3 |
| patch 层 | 按 id 整体替换条目 config 或插入条目的配置覆盖层 | 1.3 |
| agent preset | 存放 agent.cordis.yml 的目录；standing scope 挂载一次、会话共享 | 4.3 |
| continuable subagent | 可接收 follow-up 的持久化子代理（vs one-shot 一次性委派） | 3.4 |
| projection（投影） | 从会话日志派生的状态读模型（ctx.sessionProjections） | 2.5 |
参考资料
- docs/glossary.md — 官方术语表（权威）（
deepseek-harness-src/docs/glossary.md） - docs/glossary.zh.md — 官方中文术语表（
deepseek-harness-src/docs/glossary.zh.md）