极简编码代理 zhymjh/nano-dsh

nano-dsh

一个基于 Cordis 插件框架 构建的极简交互式 CLI 编码代理。

nano-dsh 是从零开始、大幅精简的重新实现，其理念源自 DeepSeek Harness。它保留了 Cordis 的 Context / ctx.plugin() / ctx.on() 插件架构，但将 harness 中约 60 个相互耦合的包替换为几个小巧、对称的包，以及一个直接的 child_process / fs 工具层。

布局

每个能力都是一个包，在 nano-core 中有一个 XxxService 接口，并在自己的包中有一个实现插件——“一切皆插件”。

packages/
nano-core/ # 纯核心：能力接口（service/）、共享类型（types/）、boot() 组装器、agent 句柄 + 注册表、profile nano-llm/ # LLM 领域：LlmAdapter 抽象、ctx.llms 注册表、LlmPlugin、内置适配器（deepseek/ollama） nano-session/ # 会话能力：MemorySessionStore（ctx.sessions）、JSONL/SQLite 持久化后端、SessionPlugin nano-loop/ # agent 循环驱动器：DefaultLoop（继承 LoopService）、LoopPlugin nano-prompt/ # 系统提示渲染器服务：DefaultPrompt（继承 PromptService）、PromptPlugin nano-tools/ # 工具注册表后端 + 内置工具（bash/fs/search）：ToolRegistry、ToolPlugin nano-app/ # 部署层：createAgent()、CLI（REPL）、Web（SSE 服务器）、环境加载 nano-mcp/ # [保留] MCP 集成 nano-sandbox/ # [保留] 沙箱/进程隔离 nano-plan/ # [保留] 规划能力 nano-skill/ # [保留] 技能能力 nano-subagent/ # [保留] 子代理能力

依赖方向是无环的：

nano-core ← nano-llm / nano-session / nano-loop / nano-prompt / nano-tools ← nano-app

nano-core 仅依赖 cordis。boot() 位于 core 中，并通过依赖注入（BootDeps）组装各能力插件，因此 core 从不导入任何能力实现包。

设计亮点

- 事件溯源会话 —— 会话是一个仅追加的 SessionEvent 日志（user-message / assistant-message / tool-result / system-message）。
模型历史通过 deriveMessages() 从日志中派生而来，因此日志是唯一的事实来源（可重放、可持久化、可调试）。
- 带事件的 Agent 对象 —— createAgent() 返回一个 Agent，具有
run() / cancel() / whenIdle() / clear() / inject() / steer() 以及
一个类型安全的 on()，用于订阅 agent/ 事件瀑布流（agent/chunk、agent/tool-call、agent/error……）。
- 回调与事件共存 —— agent.run(text, { onChunk, onToolCall })
保留了熟悉的每次调用回调；agent.on('agent/...', handler)
为插件和可观测性提供订阅。两者都由同一个循环连接。
- 工具管道钩子 —— 可选的 before/after 钩子在每次
- 工具调用 — 让插件审计、重写、门控或计时工具执行，而无需触及工具实现。
- 声明式组装 — Profile + boot(profile, deps) 将完整的智能体组合（插件、LLM 路由、会话存储）描述为数据；替换 profile 即替换产品。deps 注入能力插件，使核心不依赖具体实现。
- 一切皆插件 — 每个能力都是一个 Cordis 插件（LlmPlugin、SessionPlugin、LoopPlugin、PromptPlugin、ToolPlugin）。通过提供不同的插件来替换任何默认能力 — “一切皆插件，可从配置中替换。”
- 对称的能力键 — 每个能力都挂载一个众所周知的 ctx. 键：ctx.llms / ctx.sessions / ctx.loop / ctx.prompt / ctx.tools / ctx.agents。持久化挂载在可选的 ctx.sessionPersistence 下。没有 provider 词汇 — route（一个命名端点）、adapter（一个后端实现）、model（聊天模型）。
- 可插拔持久化 — ctx.sessions 始终是内存中的唯一事实来源。持久化后端（ctx.sessionPersistence，可选）订阅 session/event / session/flush，并将事件日志增量写入磁盘。memory 运行时无持久化；jsonl / sqlite 持久化会话并在启动时恢复它们。

前置条件

- Node.js >= 22.5（SQLite 后端使用内置的 node:sqlite）
- pnpm

安装

pnpm install

选择一个适配器（默认 deepseek）：

cp .env.example .env
编辑 .env，设置 DEEPSEEK_API_KEY=...（用于 DeepSeek）和/或 NANO_ADAPTER

运行

pnpm nano # DeepSeek（默认）
pnpm nano --adapter ollama # 本地 Ollama，无需 API 密钥
pnpm nano --cwd /path/to/project # 设置工作目录

你也可以在 .env 中设置 NANO_ADAPTER=ollama，而无需使用标志。Ollama 默认使用 http://localhost:11434 和模型 llama3.1；可通过 OLLAMA_BASE_URL / OLLAMA_MODEL 覆盖。运行 pnpm nano --help 查看所有选项，运行 pnpm nano --version 查看版本。

这会打开一个交互式会话。每一行都会变成一次智能体回合；模型可以调用 bash、read、write、edit、grep 和 glob，并循环直到稳定下来。

交互式命令

- /help — 列出可用命令
- /clear — 清除对话历史
- /exit（或 /quit）— 退出会话
- Ctrl+C — 取消正在进行的回合（按两次强制退出）
- 其他任何内容都会发送给模型

Web UI

pnpm web # 启动 Web 服务器并打开浏览器
pnpm web --port 4000 # 选择一个端口
pnpm web --no-open # 启动时不打开浏览器
pnpm web --adapter ollama # 使用特定适配器

在 http://127.0.0.1:3080（默认）提供一个零构建的单页聊天界面，并且通过 SSE 流式传输 agent 回复。它复用与 CLI 相同的 agent 组装（@nano-dsh/app）。

会话持久化

默认情况下，会话仅存在于内存中，退出时即丢失。要持久化它们，请在 Profile 中选择一个后端（或通过 createAgent()）：

// JSONL — 每个会话在 ./.nano-sessions 中对应一个 .jsonl 文件 const profile: Profile = { name: 'my-agent', llm: 'deepseek', session: 'jsonl' }

// SQLite — 事件表位于 ./.nano-sessions/sessions.sqlite const profile: Profile = { name: 'my-agent', llm: 'deepseek', session: 'sqlite' }

每个持久化后端在启动时都会恢复已保存的会话，因此对话可以跨重启继续。sessionDataDir 会覆盖默认的 ./.nano-sessions 数据目录。

构建与类型检查

pnpm build
pnpm typecheck

clean 使用 tsc -b --clean，因此 rebuild（clean + build）始终会生成全新的完整构建——包括跟踪增量状态的 .tsbuildinfo 文件。
在删除或重命名大量符号的重构之后，运行 pnpm rebuild，以便下游包解析重建后的核心的新类型：

pnpm rebuild

包参考

@nano-dsh/core

最小化、无依赖的核心。提供能力接口（位于 service/）、共享数据类型（位于 types/）、boot() 组装器、 agent 句柄 + 注册表，以及 profile 类型。

关键导出：
- boot() / BootDeps — 从 Profile 组装一个 Cordis 上下文
- AgentCore — 挂载 agent 注册表（所有其他能力来自各自的包）
- AgentRegistry — ctx.agents 能力主体（工厂：setFactory + create）
- Agent — 具有 run() / cancel() / whenIdle() / clear() / inject() / steer() / on() 的句柄
- AgentEventMap — agent waterfall 的事件词汇表
- XxxService 能力主体 — LlmService / SessionService / LoopService / PromptService / ToolService / SessionPersistence（位于 service/）；AgentRegistry（位于 agent/）
- Session / SessionEvent / deriveMessages() — 事件溯源会话模型（位于 types/）
- SystemPromptConfiguration — prompt 组装配置（位于 service/）
- ToolDefinition / ToolHooks — 工具契约与管道钩子
- Profile — 声明式 agent 组合（位于 profile/）

深层导入：@nano-dsh/core/types、@nano-dsh/core/service、@nano-dsh/core/agent、@nano-dsh/core/profile 等。

@nano-dsh/llm

LLM 领域包：适配器抽象、路由注册表，以及内置适配器。

关键导出：
- LlmPlugin — 挂载 ctx.llms 注册表，注册内置适配器工厂，并根据 profile 的 llm 配置创建 + 选择活动适配器
- LlmAdapter — 模型后端的抽象基类
- LlmService — ctx.llms 能力主体（适配器注册表 + 默认模型便捷入口）
- DeepSeekAdapter / OllamaAdapter — 内置适配器

@nano-dsh/session

会话存储后端及其组装插件。

关键导出：
- SessionPlugin — 挂载 ctx.sessions 能力（MemorySessionStore），并且当 store 为 jsonl/sqlite 时，挂载一个持久化后端
- MemorySessionStore — 继承 SessionService，即内存中的 ctx.sessions 能力主体
- SessionPersistenceService（来自 @nano-dsh/core/service）— 挂载在 ctx.sessionPersistence 的持久化接缝
- JsonlSessionPersistence — JSONL 后端（每个会话一个 .jsonl 文件，增量事件追加）
- SqliteSessionPersistence — SQLite 后端（node:sqlite，事件表，增量插入）
- JsonlSessionPersistenceConsumer / SqliteSessionPersistenceConsumer — 挂载相应后端的 Consumer 插件

@nano-dsh/loop

智能体循环驱动器。

主要导出：
- LoopPlugin — 挂载 ctx.loop 能力（默认 DefaultLoop）
- DefaultLoop — 继承 LoopService（单例 ctx.loop），委托给 runTurn

@nano-dsh/prompt

系统提示词渲染器服务。

主要导出：
- PromptPlugin — 挂载 ctx.prompt 能力（默认 DefaultPrompt）
- DefaultPrompt — 继承 PromptService（单例 ctx.prompt），委托给 renderSystemPrompt
- renderSystemPrompt — 纯提示词组装函数（人设 + 工具目录）

@nano-dsh/tools

工具注册表后端以及部署的内置工具。

主要导出：
- ToolPlugin — 挂载 ctx.tools
- ToolRegistry — ctx.tools 注册表后端（实现 ToolService）
- registerBuiltinTools() — 在上下文上挂载 bash/fs/search（以及额外工具）

@nano-dsh/app

部署层。结合了 CLI、Web 前端以及一键式智能体组装。内置工具位于 @nano-dsh/tools。

主要导出：
- createAgent() — 单次调用便捷方法：boot(profile, deps) + 注册内置工具 + 创建会话 + 返回 Agent
- main() — 启动交互式 CLI 循环
- startWebServer() — 启动 HTTP + SSE 服务器
- loadEnvFile() / configureProxy() — 环境加载与代理支持

许可证

MIT