Martty

<h1 align="center">Martty</h1>

DSH-first Agent TUI，使用与 DSH 同款的 Cordis 插件能力，也可连接其他兼容 ACP agent。

<a href="README.md">中文</a> · <a href="README.en.md">English</a>

快速开始

全局安装后直接启动：

npm install --global martty
martty

不想安装到全局，可以直接运行：

npx --yes martty

Martty 内置 ACP 连接层，默认启动并连接 DSH。已有 DSH 环境时，也可以把 Martty 安装到独立 profile，交给 DSH 管理插件和升级：

npm install --global @deepseek-ai/dsh
dsh plugin --profile martty add martty@latest
dsh --profile martty

只想看界面，可以运行：

martty --demo
martty --demo-skin

Agent UI

Martty 在终端中呈现完整的 agent 工作过程，包括流式回复、推理、工具调用、 subagent、Plan、token 用量和持久化会话。图片可以从文件或剪贴板加入 prompt； 工具输出、Markdown、代码块和图片预览都使用终端原生交互。

回合运行时可以继续排队消息，也可以立即 steer 当前 agent。会话通过 /new、 /resume 和 --session-id 管理，workspace、模型、权限和界面选择会随会话恢复。

<img src="assets/screenshots/agent-turn.png" width="720" alt="Martty 中的 Markdown 回复、工具调用和运行状态" />

常用操作：

按键 / 命令	行为
enter	发送消息；回合运行时排队 follow-up
ctrl+x	立即 steer 当前 agent
esc	中断当前回合并保留草稿
/	打开命令与参数候选
/model · /agent	选择模型和 Agent Preset
/permission · shift+tab	选择或轮换权限模式
/image <path> · /clip	添加本地图片或剪贴板图片
!cmd	在 workspace 的会话级本地 shell 中执行命令
/help · /keys	查看命令与快捷键

插件系统

Martty 的界面不是一组写死的开关。UI、主题、Slot、命令、Overlay 和 Session 视图 都由 Cordis Plugin 组合，并随 Plugin 生命周期一起加载和卸载。这套插件系统也是 Martty 的自进化路径：Agent 可以读取当前能力，创建新的界面 Plugin，并在运行中继续 观察和修改。

一个 Cordis Plugin Package 可以包含两个部分：

Cordis Plugin Package
├── code.host       # 可选，运行在 Host Cordis tree
└── code.client     # 可选，运行在 Martty Client Cordis tree

只包含 code.host 是 Host-only，只包含 code.client 是 Client-only，两者都有就是 双向 Plugin。双向 Plugin 仍是一个 Plugin run；Client half 可以通过 host.call(method, args) 调用同一 run 的 Host half。

四个 Plugin 视图

视图	显示什么
/ui	UI Plugin 列表，例如 Martty 与 DeepSeek；选择后切换整套 UI 组合
/theme	Theme Plugin 列表；选择后切换配色及该 Plugin 的其他能力
/plugins	当前已经加载的静态 Plugin，只读
/cordis-plugins	Cordis 模式刚创建的临时 Plugin；可随 run 停止、替换或回收

/ui 和 /theme 是视图，不是 Plugin 类型。列表中的 Plugin 可以是 Client-only， 也可以是同时带有 Host half 与 Client half 的双向 Plugin。

Theme Plugin 与明暗模式彼此独立。使用 /theme 选择 Theme Plugin，使用 /theme toggle 或 ctrl+t 切换当前 Theme Plugin 的 dark/light 变体。输入 /theme 时，上拉候选会把 toggle 与 Theme Plugin 分区显示。

五个 Slot

带有 Client half 的 Plugin 可以通过 tuiSlots.register 向五个位置提供界面内容：

Slot	类型	位置与用途
welcome.hero	single · root	欢迎页品牌区
welcome.info	single · root	欢迎页版本、模型、workspace 与 session 信息
chrome.right	list · root	主界面右栏，适合监控面板和持续状态
conversation.input.dock	list · session	输入框上方，适合 Plan、任务和 Goal 摘要
conversation.composer.dock	list · session	输入框下方，适合 token、耗时等紧凑统计

节点类型、更新和卸载生命周期见 Plugin API：tuiSlots， 字段定义见 tui-node.v0.schema.json。

创建 Plugin

Creator 可以检查当前 Host 与 Client 暴露的 Service、Slot 和 Schema，再生成 code.host、code.client 或双向 Package。Client-only Artifact 可以保存到 $MARTTY_HOME/plugins/<artifact-id>/plugin.json；包含 code.host 的 Package 由当前 Harness 管理。

自进化过程是一个可观察的闭环：

inspect → generate → run → observe → update / rollback → save

Creator 先读取真实 API，再运行生成的 Plugin。装载错误、Schema 错误和绘制结果都能 反馈到下一次修改；满意后再保存，不满意可以更新、停止或回滚。Plugin 只能使用公开的 Service 和语义节点，不能直接操作 TTY、raw mode 或终端坐标。

从临时 Plugin 升级为常驻 Plugin

Cordis 模式里的 Plugin 默认只属于当前进程。验证完成后，可以把它升级为重启后仍会 加载的常驻 Plugin：

临时 Plugin → 验证当前 Package → 保存或打包 → 启动时加载

…