npm package: @leeoohoo/deepseek-cli
Description: Terminal chat client for multiple AI models (Node.js implementation).
Latest version: 0.1.1

# Deepseek CLI 子代理增强版（中文指南）

English version: `README.en.md`

## 本分支的增强点
- **子代理市场**：`subagents/marketplace.json` 可安装插件，内置 Python / Spring Boot / React 三套插件（代理 + 技能）。
- **主代理只做编排**：主代理仅能用委派/任务工具；子代理获得全部 MCP 工具（文件、Shell、任务、子代理路由等）。
- **任务追踪**：`invoke_sub_agent` 每次都会在子代理系统提示中注入任务规则，要求先用 `mcp_task_manager_add_task` 记录任务，进展用 `update_task`，完成时必须用 `complete_task` 携带“完成明细”备注。
- **配置/会话报告**：启动自动生成 `config-report.html`（模型、MCP、Prompt、子代理）和 `session-report.html`（消息、任务、工具历史，左右抽屉 + 全宽聊天，支持 Markdown）。
- **UI 交互询问**：新增 `ui_prompter` MCP，可在 Electron UI 浮动岛弹出表单/选择项（`mcp_ui_prompter_prompt_key_values` / `mcp_ui_prompter_prompt_choices`），收集用户输入并返回给 AI。
- **长跑命令**：Shell MCP 提供 `tmux_run` / `tmux_capture_output`，避免长命令超时。
- **自动总结与裁剪**：主会话和子代理会在过长时将历史裁剪为「系统 prompt + 最新总结 + 当前轮用户消息」。
- **插件信息英文化**：所有插件 manifest 描述已改为英文。

## 安装
```bash
npm install
```

## 运行
```bash
node src/cli.js chat
# 或 npx --yes -p @leeoohoo/deepseek-cli deepseekc chat（需确保 ~/.npm 权限正常）
```

启动会打印：
- `Config snapshot written to: .../config-report.html`
- `Session report will update at: .../session-report.html`

## 桌面应用打包（macOS/Windows）
本项目包含 Electron UI（`deepseekui`），可用 `electron-builder` 打包成独立桌面应用（macOS Intel/Apple Silicon + Windows x64）：

```bash
npm run desktop:dist
# 产物输出到 dist_desktop/
```

## 桌面 App 安装后在终端使用 CLI（无需 Node）
桌面 App 自带 Electron/Node 运行时；安装桌面 App 后，即使系统没装 Node，也可以在终端运行 CLI。

推荐方式（最省事）：
- 打开桌面 App → `管理台` → `设置` → `终端命令（无需 Node）` → 点击“安装/更新 deepseekc”
- 重新打开一个终端窗口，然后直接运行：`deepseekc chat`

备用方式（不安装命令，直接跑）：
- macOS：`ELECTRON_RUN_AS_NODE=1 "<App>/Contents/MacOS/deepseekui" "<App>/Contents/Resources/app.asar/src/cli.js" chat`
- Windows：`set ELECTRON_RUN_AS_NODE=1 && "<App>\\deepseekui.exe" "<App>\\resources\\app.asar\\src\\cli.js" chat`

CI 构建：`.github/workflows/desktop-build.yml`（支持 `workflow_dispatch`；推送 `v*` tag 会构建并创建 GitHub Release 附件）。

## 聊天内常用指令
- `/sub marketplace` 查看插件
- `/sub install <id>` 安装插件
- `/sub agents` 查看已装代理 + 技能
- `/sub run <agent_id> <任务> [--skills skill1,skill2]` 手动运行子代理
- `/prompt` 查看/覆盖系统 prompt
- `/tool [id]` 查看最近工具输出

## MCP 工具（主 vs 子）
- 主代理白名单：`invoke_sub_agent`、`get_current_time`、`mcp_subagent_router_*`、`mcp_task_manager_*`。不允许 shell。
- 子代理：继承全部已注册工具（文件、shell、tmux、task_manager、subagent_router 等）。

### Shell MCP 长命令
- `mcp_shell_tasks_run_shell_command` 适合短时命令。
- `mcp_shell_tasks_tmux_run` 启动/复用 tmux 会话跑长流程。
- `mcp_shell_tasks_tmux_capture_output` 查看 tmux 输出。

## 总结与裁剪
- 阈值（粗估 token）：默认 60000，可用 `MODEL_CLI_SUMMARY_TOKENS` 调整。
- 触发后历史被裁剪为：系统 prompt + 最新总结 + 当前轮用户消息。
- 子代理也使用同样模式裁剪。

## 目录结构
```
src/                  # CLI 主体、聊天循环、prompt、MCP runtime
subagents/            # 子代理管理、marketplace、插件（python / spring-boot / frontend-react）
mcp_servers/          # Shell（含 tmux 工具）等 MCP 服务器
README.en.md / README.zh.md
```

## 自定义系统 Prompt
- 路径：`~/.deepseek_cli/auth/system-prompt.yaml`（自动生成）
- `internal`：始终前置。
- `default`：主代理编排行为。

## 环境与调试
- 设置 `DEEPSEEK_API_KEY` 供需要的模型使用（subagent_router 继承父进程 env）。
- 请求日志：`MODEL_CLI_LOG_REQUEST=1`
- 模型重试：`MODEL_CLI_RETRY=<n>`
- MCP 超时可调：`MODEL_CLI_MCP_TIMEOUT_MS`（默认 600000）/ `MODEL_CLI_MCP_MAX_TIMEOUT_MS`（默认 1200000，最大 30 分钟）

## 常见问题
- **报告写入权限**：修复 `~/.deepseek_cli` 权限（如 `chown -R $(whoami) ~/.deepseek_cli`）或在可写环境运行。
- **工具未注册**：主代理仅允许任务/子代理工具，shell 工具需在子代理内使用。
- **`mcp_*` 请求超时**：长耗时 MCP 工具（子代理、shell）现默认 10 分钟，仍提前被取消可提升上述环境变量。
- **长命令超时**：改用 `tmux_run` + `tmux_capture_output`。
- **历史过长**：依靠自动裁剪，或 `/reset` 重开会话。

## License
MIT（同上游）。见 `LICENSE`。