# flowix

> DSH Shared Foundation Package: Injects all basic plugin entries including model adapters, tools, persistence, permissions, and telemetry in the form of cordis.patch.yml, serving as the first layer patch for each profile.

## Metadata

- Author: [@text2future](https://github.com/text2future)
- Repo: <https://github.com/text2future/flowix.git>
- GitHub: [text2future/flowix](https://github.com/text2future/flowix)
- Stars: 331
- Language: TypeScript
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Homepage: <https://www.flowix-memo.com/>
- Topics: `agent-memory`, `claude-code`, `codex-cli`, `desktop`, `dsh`, `dsh-plugin`, `dsh-plugin-desktop`, `hermes-agent`, `markdown-editor`, `memory-system`, `note-taking`, `open-code`
- Forks: 42
- Open Issues: 23
- Last push: 2026-08-19T17:44:52.000Z
- Added: 2026-08-20T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:text2future/flowix/app/flowix-dsh-host/vendor/deepseek-harness/packages/bundle/base
```

## Wiki

## 一句话定位
DSH 的共享底座组合包 `@deepseek-ai/dsh-base`，把模型适配器、工具、持久化、权限、设置/凭证、遥测等所有基础插件行一次性插入 profile 根，作为任何 profile（headless / web-app / 用户自定义）的第一层 patch 注入。

## 核心能力
- 提供模型适配层：默认 DeepSeek 官方 provider + `deepseek-v4-flash`，并挂载 pi-ai 多 provider 适配（无配置时不增加可用模型）
- 注册基础工具集：bash/pwsh、文件系统读写与搜索、jobs、子代理委派、str_replace_editor、web 搜索、todo、goal、workflow、Ralph 迭代等
- 配置会话持久化：JSONL 会话日志 + 检查点策略、附件字节、内容寻址存储
- 配置权限边界：默认 `workspace-write` 文件效果策略 + 用户审批服务，三档预设（只读 / 工作区写入 / 完全访问）
- 加载设置与凭证：用户设置文档与本地凭证存储，支持热重载
- 挂载但默认禁用遥测：需通过 `DSH_TELEMETRY_MODE` 环境变量显式开启

## 技术实现
- **语言**: YAML（patch 清单）+ TypeScript（仅 invariant 伴生插件）
- **关键依赖**: `@deepseek-ai/cordis`（peer）+ 80 余个 dsh 内部包（`@deepseek-ai/dsh-agent`、`@deepseek-ai/dsh-session`、`@deepseek-ai/dsh-llm`、`@deepseek-ai/dsh-tools` 等）
- **架构模式**: 静态 patch 清单载体（`cordis.patch.yml`），通过 `package.json#dsh.bundle.patch` manifest 字段被 profile 组合器解析，无运行时代码；patch 行后续由更高层 patch 按 id 覆盖
- **入口文件**: `cordis.patch.yml`（实际入口）+ `src/index.ts`（仅 export {}）+ `src/invariant.ts`（空操作 invariant 安装器）

## 适用场景
所有 DSH profile 都需要它作为底座：如果要自定义一个 headless 或 web 端 DSH agent 运行时，先把这个组合包放进 `dsh.profile.bundles` 第一位，再叠加模式层与用户层 patch。它面向需要构建或扩展 DSH agent 运行时的开发者，普通用户通常不会直接接触。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DSH | >=0.1.0-rc.5 | `package.json` 自身版本号；作为 profile 底座被所有 DSH profile 引用 |
| Node.js | >=22.19 | 工作区 `engines` 统一要求 `^22.19.0 || >=24`，本包未单独声明 |
| 平台 | macOS / Windows / Linux | bash 栈在 POSIX，pwsh 栈在 win32，权限面在两套栈上保持一致 |
| 原生模块 | 无 | 纯 YAML/JS 配置驱动，无 node-gyp 依赖 |

## 安装方式
```bash
dsh plugin --profile web add github:text2future/flowix/app/flowix-dsh-host/vendor/deepseek-harness/packages/bundle/base
```

## 配置项
| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| `DSH_PERMISSION_MODE` | 环境变量 | 切换权限预设：`read-only` / `workspace-write` / `danger-full-access` | `workspace-write` |
| `DSH_TELEMETRY_MODE` | 环境变量 | 开启会话遥测（OTLP/HTTP 上报）；未设置则默认禁用 | 未设置（DISABLED） |
| `DSH_TELEMETRY_OTLP_URL` | 环境变量 | 覆盖遥测上报端点 | `https://harness-telemetry.deepseeksvc.com/v1/logs` |
| `DEEPSEEK_API_KEY` | 环境变量 | DeepSeek 官方 provider 与 web 搜索的凭证引用 | 无（未设置则相关 adapter 不可用） |
| `DSH_HOME` | 环境变量 | 设置文件、凭证、会话日志与附件的根目录位置 | 由宿主运行时决定 |

## 常见问题

**Q: 这个插件是做什么用的？我直接装就能用吗？**

A: 它是 DSH profile 的"地基组合包"，把模型适配器、工具、持久化、权限等所有基础插件行一次性注入；普通用户装上后还必须叠加模式层（如 headless / web-app）和用户层的 patch 才能组成完整 profile。

**Q: 它的运行时代码在哪里？为什么 src/index.ts 是空的？**

A: 该包的实际内容是 `cordis.patch.yml`——一份 Cordis 组合器识别的静态 patch 清单；`src/index.ts` 只导出空对象，`src/invariant.ts` 提供一个空操作的不变量伴生插件（因为它没有自身状态需要校验）。

**Q: 全文本会话搜索默认能用吗？侧栏搜不到正文怎么办？**

A: 默认不能用。`session-query-sqlite` 的 `openAt` 被设为 `never`，SQLite 数据库不会被创建，搜索调用会返回 `SESSION_QUERY_SEARCH_DISABLED`；侧栏搜索此时只能匹配标题和工作区名。如需正文检索，在后续 patch 层（profile `cordis.patch.yml` 或 `--patch` overlay）覆盖 `openAt` 为 `first-search` 或 `startup`。

**Q: 默认会上传我的会话内容吗？**

A: 不会。遥测默认 `DISABLED`，需显式设置 `DSH_TELEMETRY_MODE=FULL` 或 `FEEDBACK_ONLY` 才会向 OTLP 端点上报；任何非空 `DSH_TELEMETRY_DISABLED` 也会关闭上报。

**Q: Windows 下能装吗？bash 工具会冲突吗？**

A: 能装。patch 用对称的 `!!js` 表达式门控：`bash-sandbox`/`tool-bash` 在 win32 禁用，`pwsh-sandbox`/`tool-pwsh` 在非 win32 禁用，每个宿主恰好挂载一套 shell 栈，权限面在 POSIX 与 win32 一致（win32 走 Windows ACL 受限令牌）。

**Q: 我能用 patch 局部覆盖某个配置吗？**

A: 不能。patch 替换整行 `config` 而不是深合并，因此覆盖时必须把该行所有想保留的字段都重述一次，否则缺省字段会被丢弃。

**Q: 卸载它会怎样？**

A: 它没有运行时代码，卸载等同于移除 profile 第一层 patch，所有依赖 base 注入的 session、tool、provider 都会消失；通常只在重建 profile 时才会移除，不建议在已部署的 profile 上移除。

## 上手难度
进阶 — patch 本身可读，但要让其真正生效需要理解 DSH 的 profile 组合机制、Cordis 加载顺序、`!!js` 表达式求值上下文以及后续 patch 层的覆盖语义，对 Cordis/DSH 不熟的开发者需要先阅读官方 `docs/architecture.md` 与 `docs/cordis-primer.md`。

## 已知问题与限制
- patch 替换整行 `config`，没有深合并层；profile 覆盖必须逐字段重述该行需要保留的全部配置（来源：`README.md:20`）
- Claude SDK 平台 CLI 仍在 Profile 安装闭包中：base 组合包依赖 Claude provider，其生产路径解析宿主 `claude`，移除 SDK 中未使用的可选载荷被推迟到产品安装闭包后续项（来源：`README.md:21-22`）
- Windows 的临时目录授权是按会话的私有子目录：`workspace-write` 写入限制在工作区与会话自己的 temp 子目录（`<temp>\dsh-<hash>`），`read-only` 不授予任何临时目录写入权限（来源：`README.md:23`）
- 默认 `agent-default-model` 写死为 `deepseek-official` + `deepseek-v4-flash`，若用户 settings 文档未覆盖，将只走 DeepSeek 官方 provider（来源：`cordis.patch.yml:62-67`）
- `session-query-sqlite` 默认 `openAt: never`：侧栏搜索只能命中标题与工作区名，全文检索需用户主动在后续 patch 层启用（来源：`cordis.patch.yml:117-121`）

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [flowix](https://deepseek-plugin.org/plugins/text2future/flowix/app/flowix-dsh-host/vendor/deepseek-harness/packages/bundle/base)
Wiki generated by AI (model: `MiniMax-M3`)