DSH
1.apps 是面向最终用户的可运行应用入口，如 Web UI 和 headless 模式
2.packages/preset/agent-presets/presets
packages/preset/agent-presets/presets/minimal/agent.cordis.yml
packages/preset/agent-presets/presets/minimal/preset.yml
极简模式就是通过这棵树，装配了 persona、persistent-shell、filesystem 等核心组件。
3.preset+基础
基础 ：boot bundle core
packages/boot/app-boot/ 包，它负责解析 Profile 并启动整个应用
packages/boot/cmdline/src
packages/bundle/base/cordis.patch.yml
@module @deepseek-ai/dsh-base
dsh-base 是所有 Profile 的基础层 会话、工具、模型等最核心服务的初始化逻辑
packages/core/README.zh.md
dsh-agent-loop 创建 agent——全新创建或从持久化历史恢复——并运行轮次与步骤生命周期
：领取提示词、组装请求、流式接收模型响应、分发工具调用，并把每个结果追加回会话日志
packages/core/session
session scope system-prompt
Tool： 工具注册表 支持权限审批、沙箱隔离、文件系统守卫、结果改写等多种安全策略
工具执行流水线（tool execution pipeline）
tool/call、tool/result
主要：llm message event session extensions
「事件溯源」（event sourcing）架构
@deepseek-ai/dsh-core: 提供 tools、llm、session 等核心服务，是 agent-loop 运行的基础
功能和性能以及其他 ：
框架可观测、可调试 Agent 行为可编排
会话状态可持久化、可恢复
Cordis 提供了服务注册、类型化事件、可逆副作用三大原语，
dsh 在此之上构建了会话（session）、工具（tools）、LLM 适配（llm）、Agent 循环（agent-loop）等核心子系统
基本骨架： agentLoop / Context / Tool
对接： LLM session message/event
agent loop
01.轮次与步骤 turn and step lifecycle
dsh-agent-loop是 ctx.agents 背后的驱动器
agent-loop 都会执行一套标准的资源回收（Teardown）流程，
停止并排空 (stop and drain) → 展开作用域 (unwind scope) → 分离 Agent (detach agent) → 分离会话 (detach session)。
turn一条用户消息的完整过程
turn-start end
step-start end (模型调用前 模型调用中 模型调用后 调用工具前 调用工具中 调用工具后)
交互式编程助手—
具体：
模型调用：模型看到什么以及不给模型看什么 以及怎么给模型看，什么时候给模型看
createScope(ctx, key) 在 ctx 的 fiber 下创建作用域：其 ctx 携带作用域标签
dsh-agent-default-model 提供部署的默认模型选择——提供方、模型与可选的推理（reasoning）强度——agent 入口在全新会话没有自己的选择时应用它
01. Session
Event 是日志的基本单位，而 Message 是从这些 Event 中“投影”出来的视图
Session-SessionEvent
Message ：通过 deriveMessages() 函数，从 Session 日志中的特定事件（即 SurfaceEvent）“实时派生”出来
'user/message' 'assistant/message' 'tool/result'
Surface ： 日志中所有能产生 Message 的事件（即 SurfaceEvent）的序列号列表，使得 deriveMessages() 可以高效地生成消息历史
核心生命周期事件 (Session/Turn/Step) 模型交互事件 (User/Assistant/Tool) 系统与审计事件
02. 模型调用
ctx.systemPrompt ： assemble() dsh-system-prompt 组装模型在每个步骤之前收到的系统提示词与工具 schema
固定开场白、runtime 上下文、部署 persona 与工具顺序
工具调用
三个 waterfall 事件组成：tools/pre-execute、tools/execute、tools/post-execute
安全团队-性能团队-产品团队
tools/pre-execute waterfall 最先运行，承载钩子、权限、沙箱策略
tools/execute waterfall 包裹实际派发，承载超时、重试、指标采集
tools/post-execute waterfall 最后 运行，可以接受、阻止、替换或添加上下文
turn：
正常结束、被干预结束和异常结束三大类
正常结束 ： 没有请求调用任何工具 (tool_calls)
被干预结束： 用户取消 (User Cancellation) 钩子阻断 (Hook Blocking)
异常结束 (Error & Limit) : 最大步数/轮数 (Max Steps/Rounds) Token 上限 (Token Budget) 总执行时间超时 (Timeout)
capability-seams：
agent 拥有公共契约（Agent 接口、事件词汇），agent-loop 是其默认实现
对比Pi agent： Trace、Turn
Trace（一次完整运行）
一个 Turn 的定义非常精确：一次模型调用 + 这次调用触发的所有工具执行。 turn_start 和 turn_end 事件包裹
一个 Turn = 一次 turn_start → 一次模型调用 → 工具执行 → 一次 turn_end。
主干
1.LLM
01.模型现状
消息格式 流式传输 思考模式 缓存控制
02.ctx.llm 的本质是一个“能力接缝”（Seam）
Definition： ctx.llm 本身，它声明了 stream、prepareCall 等标准
Provider ： llm-deepseek (DeepSeek官方)、llm-pi-ai (兼容OpenAI接口)
Consumer ： agent-loop（Agent主循环），它只调用 ctx.llm 的接口，不关心具体实现
具体：
适配器注册机制：ctx.llm 提供了 registerAdapter 等核心 API 来管理适配器
registerConfigurableProviders 声明可通过配置激活的提供者，实现“声明-激活”分离
定义了一套 与供应商无关的标准词汇表（StreamChunk）标准词汇表涵盖了流式输出的所有可能
开发者不仅可以通过 ctx.llm.registerAdapter 注册新适配器，还能通过 Cordis 插件机制整体替换 ctx.llm 服务本身
一个类并继承自 LlmAdapter，然后实现其核心方法 stream
DSH 中接入新模型，本质上是编写一个符合 LlmAdapter 接口的 Cordis 插件。
核心工作就是实现 stream 方法，做好DSH标准 (StreamChunk) 与供应商API之间的“翻译”工作
对比pi agent ：定义了一套事件协议（12 种事件）和一个函数签名
“统一枚举 + 映射表”策略
（stream）→ 标准报告协议（12 种事件）→ 4 个 Provider）
把所有翻译器注册进了一个”通讯录”（查表）
模型回复的内容分三类（文字、思考、工具调用），每类都有”开始→逐字增量→结束”三步，再加上流开始和流结束两个信号。
开发： Provider registerApiProvider Config
怎么标记不变内容”这件事，思路完全不同
2.Tool 工具 -Capability Seam
@deepseek-ai/dsh-tools 本身是一个工具注册表与执行流水线，它定义了一套标准框架，
而具体的工具功能则由其他独立的插件包提供
它通过定义清晰的“服务定义”（ctx.tools），
让各种具体的“工具插件”（Service Providers）和“Agent循环”（Consumer）能够以一种标准化、可插拔、独立演进的
3.Agent 的决策、记忆和任务管理
schedule/ 会话调度
goal/ 目标持久化
subagent/ 子代理：
workflow/ 工作流引擎：提供工作流接缝(seam
4. 持久性约定
会话日志是“真理之源” session
通用存储：枢纽 (Hub)：ctx.storage
ctx.settings 设置管理。管理插件和系统的配置设置
四种模式的差异
Minimal 模式 (极简模式)
Standard 模式 (标准模式)
核心工具包 高级功能包 其他组件
Code 模式 (PTC 模式)
基础能力：继承了 Standard 模式的全部能力包。核心差异：额外引入了 dsh-code-runtime 包，用于提供代码执行环境
Creator 模式 (创造模式)
继承了 Standard 模式的全部能力包。核心差异：额外引入了 dsh-tool-cordis 包
Pi agent
视角一：作为编码 Agent —— 一个好用的日常工具
作为学习素材 —— Agent 设计的教科书
作为 SDK —— 构建你自己的 Agent
Pi 的扩展是事件总线 + TS 模块，本质是"往上加"
pi agent的原子 Message、Model、Tool——就是整个 Pi 系统的原子
AgentMessage 是 Message 的超集 Message 是只有三种标准消息（User/Assistant/ToolResult）
Agent （循环、状态、事件、压缩）
Trace、Turn
Loop 循环是 Pi 的基石 调用链
ReAct 循环模式 prompts context config steering 消息注入 terminate 机制
AgentTool 继承了 Tool
Pi 分三层：pi-ai（管模型）→ pi-agent-core（管循环）→ pi-coding-agent（管业务）
依赖方向 “依赖漏斗”分层法
pi-ai 怎么调用已有模型，和怎么接入一个新模型？
没有设计 BaseProvider 抽象类让所有翻译器继承，而是定义了一套事件协议（12 种事件）和一个函数签名
agent-loop
内核上叠加了 steering（紧急插队）、followUp（任务追加）、prepareNextTurn（动态切模型）、shouldStopAfterTurn（安全阀）
coding :工具到底是怎么定义的？怎么把工具的信息告诉模型？beforeToolCall——前置钩子 afterToolCall——后置钩子
并行 vs 串行？
管道来解决这些问题：参数预处理 → Schema 验证 → 权限拦截 → 工具执行 → 结果后处理
消息-事件
监听机制——session.subscribe（只读观察，Agent 不等你）和扩展系统的 pi.on（能拦截、能改写，Agent 会等你）
DSH ： plugin Profile 与组合包 (Bundle)
Event ：
SessionEvent 仅追加（Append-Only）的事件日志（Event Log）
plugin：
LLM seam Model 在 DeepSeek Harness 中同样是一个可替换的插件
插件组合
Core Packages -
agent loop插件：Transaction 轮次（Turn） 和 步骤（Step）
基于事件溯源，历史消息从 SessionEvent 日志中实时派生(Derived)
过 LLM seam (LLM 接缝) 调用
工具注册表 (Tool Registry) 分发和执行
浙公网安备 33010602011771号