插件化编码代理pmorgan3/deep-tui

Deep TUI

Deep TUI 是一个以插件优先的编码代理框架，构建于
Cordis 之上。提供方、工具、提示词、
权限、存储、主题、命令、渲染器以及代理循环都是可替换的插件。CLI 只负责发现配置、
加载插件和分发命令。

Deep TUI 处于 pre-alpha 阶段。其契约和配置可能会发生变化。

快速开始

要求：Node.js 22 或更高版本。

npm install --global @deep-tui/cli
cd path/to/your/project
deep-tui init
export DEEPSEEK_API_KEY=your-key
deep-tui

deep-tui init 会在 deep-tui.config.json 中创建默认组合，而
deep-tui 会打开 TUI。输入提示词并按 Enter。输入 / 可浏览
命令。若要在所有项目中使用同一个默认组合，请运行
deep-tui config init --scope user 而不是 deep-tui init；当项目
配置存在时，项目配置优先。

不使用 TUI 运行：

deep-tui run --model flash "Summarize this repository"
deep-tui run --model pro --new-session "Implement the next task"
deep-tui sessions list
deep-tui config validate

之后可使用 npm install --global @deep-tui/cli@latest 升级。只有在开发 Deep TUI
本身时才需要 pnpm。

开发

pnpm install        # install workspace dependencies
pnpm build          # build every package
pnpm test           # run Vitest
pnpm typecheck      # type-check without emitting
pnpm check          # build, test, and type-check
pnpm pack:check     # verify publishable package contents

在迭代过程中运行单个包或测试：

pnpm --filter @deep-tui/plugin-ui-tui run typecheck
pnpm exec vitest run packages/plugin-ui-tui/tests/tui.spec.ts

除非是定位、加载或修复插件所必需的功能，否则请将行为添加为插件。
公共契约应放在 @deep-tui/sdk 中；实现应放在
packages/plugin- 中。

仓库布局

| 路径 | 用途 |
| --- | --- |
| packages/cli | 配置加载器、引导命令和可执行文件 |
| packages/sdk | 公共契约和服务注册表 |
| packages/runtime | 默认服务实现 |
| packages/plugin- | 可独立加载的功能 |
| examples | 小型本地插件示例 |
| schemas | 配置 schema |
| docs | 架构、打包、路线图和设计计划 |

组合

当前生效的产品是 deep-tui.config.json 中的插件列表：

{
"$schema": "./schemas/config.schema.json",
"version": 2,
"plugins": [
{ "use": "@deep-tui/runtime" },
{
"use": "@deep-tui/plugin-agent",
"config": { "provider": "deepseek", "model": "flash" }
},
{ "use": "@deep-tui/plugin-provider-deepseek" },
{ "use": "@deep-tui/plugin-tool-workspace" },
{ "use": "@deep-tui/plugin-ui-tui" }
]
}

这个简略示例展示的是结构，而不是完整的默认组合。
可运行的配置请参见 deep-tui.config.json。
插件通过 inject 声明所需的服务。Cordis 会在这些服务存在时挂载它，并在卸载时释放其注册项。插件数组的顺序并不决定依赖关系；特定贡献项的 priority 和 order 字段控制选择与呈现。

配置可以叠加用户、扩展、项目和显式文件。在启动 UI 之前，先检查解析后的结果：

deep-tui config paths
deep-tui config show
deep-tui config explain @deep-tui/plugin-agent
deep-tui config validate

当某条命令只应加载所选文件时，使用 --isolated-config。

创建插件

搭建并激活一个本地插件：

deep-tui plugin create concise-prompt
deep-tui plugin create my-command --template slash

本地插件创建在 .deep-tui/plugins/ 下，并添加到当前激活的组合中。一个最小插件如下所示：

export const name = 'concise-prompt'
export const inject = ['prompts']

export function apply(ctx) {
ctx.prompts.register({
id: 'example.concise',
order: 50,
render: () => 'Be concise and concrete.',
})
}

注册项是 Cordis 的 effect，因此卸载插件会移除它们。同样的生命周期适用于工具、提供方、命令、TUI 组件、键位绑定、渲染器、主题和权限处理器。

插件可以从 npm、本地路径或固定的 GitHub URL 加载：

deep-tui plugin add ./examples/slash-greeting.mjs
deep-tui plugin add https://github.com/example/deep-tui-plugin#v1.0.0 --scope user
deep-tui plugin sync --scope user

插件以与 Deep TUI 相同的操作系统权限执行。只安装你信任的代码。模型工具权限不会对插件代码进行沙箱隔离。GitHub 插件必须提交可运行的 ESM 入口；安装期间会禁用依赖的生命周期脚本。

内置能力

默认组合提供：

- 通过可复用的 OpenAI 兼容传输层提供 DeepSeek Flash 和 Pro；
- 工作区读取、搜索、补丁、进程和只读 Git 工具；
- 单根和虚拟 @alias/path 多根工作区；
- 流式 Markdown、语法高亮、结构化工具输出和差异；
- 可组合的全屏 TUI 和无头终端界面；
- 持久会话、压缩、预算、用量和成本报告；
- 记忆的权限、仅会话自动批准和只读计划模式；
- 可移植的 Agent Skills 发现，以及显式精选的来源市场；
- 带脱敏和哈希校验的文件系统审计历史。

大多数功能在 packages/ 下都有包 README，其中包含其配置和公开扩展点。

TUI 参考

| 输入 | 操作 |
| --- | --- |
| Ctrl+P | 切换模型 |
| Ctrl+T | 切换最新推理块 |
| Ctrl+B | 显示或隐藏侧边栏 |
| Tab | 补全命令或将焦点移至侧边栏 |
| Page Up / Page Down | 滚动对话记录 |
| Home / End | 跳转到开头或恢复跟随输出 |
| Ctrl+C | 取消当前活动；再次按下退出 |
| Ctrl+L | 清空对话记录视图 |

有用的命令组包括会话（/new、/resume、/fork）、模型和主题（/model、/theme）、策略（/plan、/auto、/permissions）、上下文管理（/compact、/autocompact、/budget）以及项目工具（/folders、/plugins、/audit）。使用 /help 查看当前组合。

状态与安全

项目状态存储在 .deep-tui/ 下：

- .deep-tui/sessions/ 包含仅追加的对话记录；
- .deep-tui/audit/ 包含经过脱敏的审计事件；
- .deep-tui/permissions.json 包含已记住的项目授权；
- .deep-tui/folders.json 包含额外的工作区根目录；
- .deep-tui/theme.json 包含所选的项目主题。

工作区读取默认允许。写入和进程需通过权限服务。/auto 仅对当前会话生效，/plan 在激活期间拒绝写入、执行和网络访问。这些控制约束的是模型工具调用，而非已安装的插件代码。

文档

- 架构：宿主边界与公共服务
- SDK：插件契约与服务注册表
- CLI：可执行文件与引导行为
- 打包：npm 和 GitHub 分发要求
- 路线图：计划工作与预发布状态
- 设计方案：已实现的验收决策
- 贡献：开发与评审期望

MIT 许可。参见 LICENSE。