Skip to content
dsh marketplace

dsh-deep-flow

Verified

@jkxie/dsh-deep-flow · v0.3.4 · MIT

Terminal-UI surface for dsh: an interactive Ink REPL bundle riding over dsh-base

Install

dsh plugin add @jkxie/dsh-deep-flow

Confirm the layer applied with dsh --profile default --dump-config — see the install guide.

Source

Creators

Readme

deep-flow

DeepSeek Harness 的终端界面（TUI）：一个交互式 Ink REPL，以仓库外（out-of-tree）dsh bundle 的形式骑在 dsh-base 之上。没有 Host、HTTP 服务或浏览器——一切都在进程内直接对组合好的 Cordis 树运行。

已发布到 npm：@jkxie/dsh-deep-flow。English version: README.md。

░████  ░█████ ░█████ ░████     ░█████ ░█     ░████ ░█   █
░█   █ ░█     ░█     ░█   █    ░█     ░█     ░█  █ ░█   █
░█   █ ░███   ░███   ░████     ░███   ░█     ░█  █ ░█   █
░█   █ ░█     ░█     ░█        ░█     ░█     ░█  █ ░█ █ █
░████  ░█████ ░█████ ░█        ░█     ░█████ ░████  ░█ █

特性

  • 默认新会话 —— 启动直接进入全新对话；/sessions 打开会话选择器。
  • 会话管理 —— /sessions 打开 Gemini 风格的可搜索会话选择器（新建 / 恢复 / 切换）；当前会话标题显示在输入框上方，可用 /rename 固定重命名。
  • 流式对话 —— 助手输出实时流入，以 Markdown 渲染，代码块用 lowlight（highlight.js）高亮，并在可滚动、自动跟随的 transcript 中显示。
  • 丰富的工具卡片 —— 文件编辑显示为内联 diff，读取显示行号 + 高亮，另有终端输出、搜索结果、网页来源，全部由工具 render-intent 契约驱动。
  • 内联人工协作 —— 斜杠命令（本地 /new /rename /init /sessions /models /keys /help /exit 加上 harness 自带命令）、权限提示（y/n）和提问问答，都在聚焦的对话框层内完成。
  • 输入体验 —— / 命令补全与 @path 补全 + 内联 ghost text（Tab 接受），以及 ↑/↓ 输入历史。
  • 模型切换 —— /models 打开基于 ctx.llm 的 provider/model 目录的选择器，并通过 default-model 设置持久化。
  • Gemini 风格主题 —— 语义颜色 token、渐变 logo + spinner、> 提示符，以及集中、文档化的快捷键。
  • 状态可观测 —— 一条由 dsh-working-activity 插件驱动的工作状态行（live working line），下面是分段上下文进度条（system / prompt / assistant / thinking / tools / free）、TPS 仪表 + sparkline，状态行还展示单次运行统计——缓存命中率、reasoning effort、输入 → 输出 token。
  • Git 分支徽标 —— 当工作目录是 git 仓库时，状态行显示当前分支徽标 ⎇ <branch>（启动时读取，每次模型回复完成后刷新）。
  • 会话指标命令 —— /status（模型、effort、会话 id、cwd、tokens、上下文占用率、TPS）、/cost（input / output / cache read / cache write）、/tokens（输入 → 输出）直接在 transcript 中输出报告。
  • Goals / Todos 面板 —— /goal、/todo 打开面板，把 goal/change、todo/write 会话事件投影为实时的 goal + todo 列表。
  • 轨迹时间线 —— /trace 打开可过滤的会话时间线（turn / tool / reasoning / token 分类），↑/↓ 切换过滤器。
  • 导出为 Markdown —— /export 将当前会话（user / assistant / tool 段）以 Markdown 写入当前工作目录（cwd）。
  • Agent 预设 —— /preset 打开基于 harness agent-preset 清单的选择器；在空白会话上选中即可切换 agent 的 preset（已有历史的会话会提示预设切换需要空会话）。
  • 会话模式 —— Shift+Tab 循环切换 默认 / 计划 / 完全访问 模式：每种模式都是可选 DSH plane 开关的命名组合——plan 模式（dsh-plan-mode /plan）、沙箱策略、审批策略。
  • 侧问 —— /btw <问题> 用当前模型选择发起一次独立的 llm.stream 调用，结果显示在面板中，绝不阻塞或打断主回合。
  • Rewind 回退 —— 空输入时双击 Esc 打开历史用户消息选择器；选中后把会话 fork 回该点（通过 sessions.fork + agents.create 换新 agent），并把该消息预填进输入框。
  • 启动提示 —— 空会话时在 logo/version 下方显示三条随机使用提示（命令名高亮、描述灰显，中英双语按系统 locale 自动选择；提示内容维护在 src/tips.txt，改提示无需动代码）。

环境要求

  • Node ^22.19.0 或 >= 24（更老的 22.x 缺少 node:zlib.createZstdDecompress）。
  • pnpm >= 11 —— dsh plugin add 会调用系统 pnpm；pnpm 10.x 会触发 ERR_PNPM_ADDING_TO_ROOT。
  • DEEPSEEK_API_KEY —— 仅发送真实模型请求时需要；启动和界面不需要。

安装与启动

# 前置：全局安装官方 harness CLI
npm install -g @deepseek-ai/dsh

# 全局安装 deep-flow（首次会自动初始化 profile）
npm install -g @jkxie/dsh-deep-flow

# 一键启动
deep-flow

deep-flow 启动器会自动让 profile 与已安装的包保持同步：

  • 首次运行 —— 检测到 profile 未初始化，自动执行 dsh plugin --profile deep-flow add @jkxie/dsh-deep-flow@<版本> 并启动。
  • 版本漂移 —— 若 profile 内安装的版本与全局启动器版本不一致，会自动把 profile 重新固定到启动器版本再启动。因此升级只需 npm install -g @jkxie/dsh-deep-flow@<新版本> 后执行 deep-flow，profile 会在 下次启动时自动更新。
  • 版本一致 —— 直接启动。

手工 / 高级方式（等价）：

dsh plugin --profile deep-flow add @jkxie/dsh-deep-flow@latest
dsh --profile deep-flow

安装指定版本：

dsh plugin --profile deep-flow add @jkxie/[email protected]

更新到最新版：

dsh plugin --profile deep-flow add @jkxie/dsh-deep-flow@latest

@deepseek-ai/* 包通过 dsh 安装目录的 flat profile fallback 解析（源码启动时走 tsx paths），因此不是本包的 npm 依赖——你无需自行安装它们。

快捷键

界面 按键 作用
对话 ↑ / ↓ 召回之前的输入
← / → 移动光标
PgUp / PgDn / 鼠标滚轮 滚动 transcript
Tab 接受 / 命令或 @path 补全
Shift+Tab 循环切换会话模式（默认 / 计划 / 完全访问）
Enter 发送消息
Ctrl-C 清空输入 → 取消本轮 → 退出
/new 新建会话
/rename 重命名当前会话
/init 分析当前目录生成 AGENTS.md
/sessions 选择会话
/models 选择模型
/keys 管理 API 密钥
/help 列出斜杠命令
/status 显示会话信息
/cost 显示 token 用量
/tokens 显示 token 明细
/goal 显示 goal 面板
/todo 显示 todo 面板
/export 将会话导出为 Markdown
/trace 显示会话轨迹时间线
Esc Esc 空输入时回退到某条历史消息
/preset 切换 agent preset
/btw 提出侧问（不阻塞主回合）
/exit 退出
API 密钥 ↑ / k · ↓ / j 移动选择
Enter 编辑选中的密钥（打码）
Esc 回到会话列表
q / Ctrl-C 退出
提示 y / n 允许 / 拒绝权限请求
1-9 选择问题选项
c 输入自定义答案
Enter 确认 / 跳过问题
Esc 取消（撤销请求 / 问题）

工作原理

deep-flow 是一个 Cordis bundle（dsh.bundle.patch → cordis.patch.yml），它禁用了共享的模块热重载 hmr 行，并插入 deep-flow-runner 插件。runner 注入核心服务（agents、sessions、agentDefaultModel、tools、commands、userQuestions、approval），等待 loader 就绪后渲染一棵 Ink 树，它会：

  • 通过 session/event 读取持久会话日志，并经由 Channel（src/store/channel.ts）投影成 React 层用 useSyncExternalStore 订阅的不可变快照；TPS / 上下文进度条 / token 指标源自该 session/event 投影（assistant/message 的 usage、request/header、request/context、user/message、tool/call），而 dsh-working-activity 的实时 activity/status 帧仅驱动工作状态行，
  • 通过 agent.followup() 提交用户输入，
  • 通过 agent.cancel() 取消进行中的回合，
  • 通过 ctx.agents.create() / ctx.agents.resume() 创建 / 恢复 agent——恢复前会先跑 src/compat/sessionLog.ts 就地修复持久化日志，把临时的 activity/status 帧标记为 ignorable，让 seed 校验接受该会话，
  • 通过 ctx.commands、approval/request 瀑布和 ctx.userQuestions 应答交互入口。
概念 机制
事件流 session/event
提示 agent agent.followup()
中断 agent.cancel()
创建 / 恢复会话 ctx.agents.create() / ctx.agents.resume()
权限 / 命令 / 问答 ctx.approval / ctx.commands / ctx.userQuestions
模型目录 / 选择 ctx.llm / ctx.agentDefaultModel
状态可观测 activity/status（dsh-working-activity）→ 仅工作状态行；TPS / 上下文进度条指标来自 session/event 投影

工作状态行来自 dsh-working-activity 插件，它通过 src/working-activity.ts 以本包自己的 @jkxie/dsh-deep-flow/working-activity 子路径再导出，这样 dsh loader 总能从 profile 的直接依赖里解析到它（pnpm 的隔离 node_modules 不会把传递依赖链进 profile 根目录）。

目录结构

src/
  index.tsx            入口 — 仅从 plugin.tsx 再导出 name/inject/apply
  plugin.tsx           runner 插件边界（服务、控制器、boot、render）
  app.tsx              App 界面（视图状态、单一 useInput 分发器、对话框接线）
  commands.ts          本地斜杠命令 + 解析器（/status /cost /tokens /goal /todo /export /trace，纯逻辑）
  controller.ts        Controller / HomeSession / CommandOutcome / StatusSnapshot 类型
  prompt.ts            桥接 boot ↔ React 的提示队列
  working-activity.ts  dsh-working-activity 再导出（loader 可解析的子路径）
  store/
    channel.ts         Channel — session/event → transcript 行 + 实时指标快照
    metrics.ts         上下文进度条、TPS 仪表 + sparkline、token 格式化（纯逻辑）
    goal-todo.ts       goal/change + todo/write 事件归约器（纯逻辑，切换会话可重放）
    rewind.ts          rewind 候选 + fork 边界计算（纯逻辑，可重放）
    session-modes.ts   可配置会话模式（plan/沙箱/审批 组合，纯逻辑）
    trace.ts           有界、可过滤的轨迹时间线投影（纯逻辑）
  screens/
    chat.tsx           ChatScreen — transcript + composer + 状态行
    status-line.tsx    状态行 + 分段上下文进度条 footer
  components/
    goal-panel.tsx     goal 面板（/goal）—— 来自 goal/change 事件的实时 goal
    todo-panel.tsx     todo 面板（/todo）—— 整表 todo/write 快照
    trace-view.tsx     /trace 可过滤时间线视图
    btw-panel.tsx      /btw 侧问面板（独立的 llm.stream 调用）
    preset-picker.tsx  /preset agent 预设选择器
    rewind-picker.tsx  双击 Esc 回退选择器（历史用户消息）
    session-picker.tsx /sessions Gemini 风格会话选择器
  hooks/
    useStore.ts        轻量 useSyncExternalStore 封装
  compat/
    sessionLog.ts      恢复前会话日志修复（第三方事件类型）
  transcript-view.tsx  ToolLine / LineView
  header.tsx           渐变 logo + 版本横幅 + 启动提示（transcript 顶部）
  tips.ts              解析 tips.txt、抽取随机提示子集、locale 检测（纯逻辑）
  tips.txt             中英双语启动提示数据（每行一组 cmd|desc|cmd|desc，可随意编辑）
  composer.tsx         边框输入盒 + spinner/footer
  file-completion.ts   @ 路径补全（纯逻辑）
  git-branch.ts        读取 cwd 的 git 分支（纯逻辑）
  init-prompt.ts        /init 分析 prompt（纯逻辑）
  spinner.tsx          渐变颜色循环 spinner
  useTerminalSize.ts   终端尺寸 hook
  markdown.tsx         markdown-it → Ink 渲染器（流式感知）
  highlight.ts         lowlight/highlight.js 语法高亮器（→ Ink token 颜色）
  tool-cards.tsx       read / terminal / search / web 结果卡片
  diff.tsx             内联文件 diff 视图
  dialogs.tsx          approval / question / model-picker / help 对话框
  keys.tsx             API 密钥管理视图（基于 ctx.credentials 的掩码编辑器）
  theme.ts             颜色主题（单套暗色，解耦）
  keymap.ts            集中式快捷键 + 帮助文本
  logo.tsx             启动 ASCII 艺术字（渐变；换品牌时改这里）
cordis.patch.yml      bundle 补丁（禁用 hmr、插入 deep-flow-runner）

开发

构建（产出 lib/index.js，ESM）：

pnpm run build

从 deepseek-harness checkout 本地运行（需要先 pnpm install 并至少 pnpm run build:lib:host）：

pnpm dsh plugin --profile deep-flow add ../deep-flow
pnpm dsh --profile deep-flow

本项目没有 test / lint / typecheck 脚本——pnpm run build 是主要验证命令，另有 pnpm run verify:metrics / verify:goal-todo / verify:trace / verify:rewind / verify:session-mode 验证纯逻辑（指标、goal/todo 归约器、trace 投影、rewind 候选/边界、会话模式折叠）。渲染通过在假 stdin/stdout 上以 interactive: false 挂载组件离线验证；交互行为需真实终端。里程碑计划（M0–M5，全部完成）及沿途记录的教训见 PLAN.md。

发布

npm version patch    # 或 minor / major —— npm 禁止重复发布同一版本号
npm publish --access public --registry https://registry.npmjs.org/

prepublishOnly 会自动执行 pnpm run build。发布预发布版本而不动 latest 标签时加 --tag beta。

License

MIT