Python 智能体骨架ChenYu1991ppak/Pydsh

pydsh

一个用 Python 实现的最小 DeepSeek Harness。 插件循环、钩子、权限、目标/计划——一条命令，零配置。从零开始，忠实复刻 dsh 工程骨架的教育性实现。

DeepSeek Harness（dsh）是一个 AI agent 框架。这是它的 Python 双胞胎——相同的架构，最小化裁剪，开箱即用。deepseek-harness-anatomy 是配套教程，讲解了每一个机制。

pydsh 架构

适合谁使用

- 你想要一个今天就能用的 Python agent harness——克隆、配置 API key、运行 make tui，你就拥有了一个日常可用的编码 agent，具备工具、技能、子 agent 和压缩能力
- 你正在研究 agent 架构——每一个机制都与官方 dsh 源码对齐（↔ packages/*/src），教学性简化之处均有明确标注
- 你正在构建自己的 agent 框架——把它 fork 作为模板；Cordis 插件容器、seam 三重角色模式、事件流持久化都可复用
- 你读过配套教程 deepseek-harness-anatomy，想看看 Python 中的真实实现

项目描述

pydsh 是官方 DeepSeek Harness（dsh）的 Python 教育性复刻。官方 dsh 是一个 TypeScript 通用 AI agent 框架：由 Cordis 插件容器驱动，它将每一项 agent 能力——会话、模型调用、工具执行、技能、子 agent、上下文压缩、token 计量、审批、web 检索——都实现为可插拔插件，通过 bundle 和 profile 以声明式方式组装。

pydsh 忠实复现了这一架构：

- 内核：自研的 cordis/ 插件容器（Context / Fiber / Service / 事件分发 / 四形态归一化），约 400 行同步单线程内核，等价于官方 @deepseek-ai/cordis
- 能力三重角色：每项能力拆分为三层——定义（纯契约）/ 提供者（构造时自注册）/ 消费者（写入工具注册表）——使 seam 可替换
- 会话事件流：仅追加的事件日志（20+ 类型白名单）；每一个可观察行为都记录为事件，TUI、持久化、压缩和 token 计量都是只读观察者
- Agent 循环：react 风格的循环驱动器——流式 LLM → 工具调用 → 结果回填 → 重新思考 → 直到文本落定
- LLM 软映射层：四类模型家族（DeepSeek / Kimi / Qwen / GPT）的推理强度、温度和推理历史在纯函数中收敛
- pi-tui 终端前端：TypeScript + @earendil-works/pi-tui，独立的 Node.js 进程，通过 ACP JSON-RPC stdio 协议通信，与官方 dsh-tui 对齐
- 真实 token 用量：由 provider 返回的用量（而非估算值）通过 tokenMeter 锚点流向 前端显示

与官方版本（TypeScript + 40 多个包）相比，pydsh 是最小化裁剪的：单仓库单包布局、同步内核，以及一个教学用的事件表面，同时保留所有核心机制形态。每一处偏离都标记为 [教学简化]（teaching simplification），每一处对齐都标记为 ↔ official source location。

当前功能

- 内核：Cordis 插件容器（Context / Fiber / Service / 事件 / 四形态归一化）
- 会话：仅追加事件日志 + 恢复 + 投影 + JSONL / SQLite 持久化
- Agent 循环：react 循环（流式 LLM → 工具 → 回填 → 结算）+ 轮次边界事件
- LLM：OpenAI 兼容流式 + 五档推理强度 + 软映射层（四个模型家族收敛）+ 真实 token 用量（由 provider 返回）
- 工具：注册表 + 三阶段防护流水线 + bash / read_file + 审批（ask / never + answerer）+ 技能加载 + 子代理委派
- 检索：网络搜索 / 抓取（SSRF 防护 + HTML→文本）+ LSP 四项操作
- 压缩：上下文压缩（阈值触发，prune / summarize）
- 前端：pi-tui 终端 + ACP JSON-RPC 服务器，可通过 --profile 切换
- 装配：bundle / profile 叠加链 + pydsh plugin 管理

完整列表：docs/FEATURE.md。

项目结构

pydsh/
├── Makefile                          # 任务自动化
├── scripts/
│   └── setup.sh                      # 一键安装脚本
├── pydsh/                          # Python 包
│   ├── __init__.py
│   ├── cordis/                       # 插件容器内核
│   ├── infrastructure/               # 启动、配置、bundle、profile、打包、tui
│   │   ├── boot/                     # CLI 入口 + 项目加载器
│   │   ├── bundle/                   # Bundle 清单加载
│   │   ├── config/                   # 配置 / models.json / settings.json
│   │   ├── packaging/                # 插件发现（entry-points）
│   │   ├── profile/                  # Profile 叠加链
│   │   └── tui/                      # pi-tui 启动器 + Node.js 前端
│   │       ├── app_pi_tui.py         # App 插件：启动 pi-tui 子进程
│   │       └── pi-tui/               # Node.js 前端（ACP 客户端）
│   ├── packages/
│   │   ├── core/                     # 共享库原语
│   │   ├── services/                 # 能力服务（20+ 项能力）
│   │   └── tools/                    # 消费端工具（bash、read_file、web、lsp）
│   └── bundles/                      # 内置激活清单
├── tests/                            # 测试套件（pytest）
├── docs/                             # 设计文档与原则
└── pyproject.toml                    # 包元数据与 entry-points

快速开始

前置条件

- Python >= 3.11
- Node.js >= 18（在 Linux/macOS 上由安装脚本自动安装）

1. 安装

git clone https://github.com/ChenYu1991ppak/Pydsh.git
cd Pydsh
make install

这会安装 Python 依赖（pip install -e .）、Node.js 依赖，并编译 pi-tui 前端。

2. 配置你的模型

创建带有 API 密钥的 ~/.pydsh/models.json：

mkdir -p ~/.pydsh

models.json 示例：

{
"currentModel": "deepseek",
"availableModels": [
{
"id": "deepseek",
"baseUrl": "https://api.deepseek.com",
"apiKey": "sk-your-api-key-here",
"model": "deepseek-chat"
}
]
}

格式参考：docs/PRINCIPLES.md §8。

3. 启动 TUI

make tui                          # 启动 pi-tui TUI

或直接运行：

pydsh --profile tui [./project] # pi-tui 前端

开发

make test       # 运行所有测试（python -m pytest）
make clean      # 清理构建产物和缓存

不使用 Node.js 运行

如果你不需要 TUI 前端，可以直接使用 ACP 服务器：

pydsh --profile acp              # ACP JSON-RPC 服务器（需要 API 密钥）

自定义配置文件

--profile  会启动自定义配置文件或内置 bundle。详情请参阅 docs/PRINCIPLES.md §7。

~/.pydsh/profiles/my.yaml
bundles: [tui]          # 在 base 之上叠加 tui 前端
plugins:                # 追加 / 覆盖插件
- my-extra-plugin
remove: [pydsh.llm-openai]  # 移除插件

pydsh --profile my [./project]

未来工作（按实现顺序）

1. session-title — LLM 自动生成的会话标题（目前是确定性的回退方案）
2. fs-search + str-replace-editor — 文件搜索和编辑工具（grep / glob + 编辑器）
3. plan + todo — 任务规划和待办面板
4. full commands registry — 命令 ScopedLayers（按代理隔离）
5. ask-user — 用户提问工具
6. terminal — PTY 终端工具
7. workflow + mcp — 多代理编排 + MCP 协议

架构对比

pydsh vs 官方 dsh（DeepSeek Harness）

| 维度 | pydsh | 官方 dsh |
|---|---|---|
| 语言 | Python | TypeScript |
| 代码库规模 | 约 400 行内核，单一包 | 40+ 个包 |
| 内核 | 同步、单线程 | 异步、多线程 |
| 插件系统 | Cordis 容器（Context/Fiber/Service/events） | @deepseek-ai/cordis |
| 代理循环 | React 风格（stream → tools → backfill → settle） | 相同 |
| 会话持久化 | JSONL + SQLite，仅追加事件日志 | 相同 |
| LLM 支持 | DeepSeek、Kimi、Qwen、GPT（软映射层） | DeepSeek + 可扩展 |
| 工具 | bash、read_file、web 搜索/抓取、LSP | 完整工具套件 |
| 前端 | pi-tui（Node.js、ACP JSON-RPC） | dsh-tui |
| 复杂度 | 极简、教学用途 | 生产级、功能齐全 |
| 最适合 | 学习、原型设计、Python 原生项目 | 生产使用、TypeScript 生态 |

pydsh 与其他 Agent 框架对比

| 维度 | pydsh | LangChain | CrewAI |
|---|---|---|---|
| 理念 | 一切皆插件 | 链式组合 | 基于角色的 Agent |
| 插件系统 | Cordis 容器（接缝三角色） | LangChain 插件 | 有限 |
| Agent 循环 | 内置 react 循环 | 自定义链 | 内置 |
| Token 计量 | 真实提供商返回的用量 | 估算 | 估算 |
| 上下文压缩 | 内置（剪枝/摘要） | 外部 | 外部 |
| 学习曲线 | 低（极简、教学式） | 高（大量抽象） | 中 |
| 体积 | 约 400 行内核 | 10 万+ 行 | 1 万+ 行 |

许可证

MIT