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

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

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 提供 `session_run` / `session_capture_output`，避免长命令超时。
- **自动总结与裁剪**：主会话和子代理会在过长时将历史裁剪为「系统 prompt + 最新总结 + 当前轮用户消息」。
- **插件信息英文化**：所有插件 manifest 描述已改为英文。

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

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

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

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

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

备注（从 GitHub 下载的 macOS 安装包）：未签名/未公证的 App 可能会被 Gatekeeper 拦截并提示“已损坏”。本仓库的 Release 工作流会在推送 tag 时对 macOS `dmg/zip` 做签名 + 公证，需要配置这些 GitHub Secrets：
- `DEV_ID_APP_CERT_P12_BASE64`, `DEV_ID_APP_CERT_PASSWORD`（Developer ID Application 证书导出的 `.p12`）
- `ASC_APPLE_ID`, `ASC_APP_SPECIFIC_PASSWORD`, `APPLE_TEAM_ID`（公证）

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

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

备用方式（不安装命令，直接跑）：
- macOS：`ELECTRON_RUN_AS_NODE=1 "<App>/Contents/MacOS/aideui" "<App>/Contents/Resources/app.asar/src/cli.js" chat`
- Windows：`set ELECTRON_RUN_AS_NODE=1 && "<App>\\aideui.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_project_files_*`、`mcp_subagent_router_*`、`mcp_task_manager_*`（默认不允许 shell；其它 MCP 默认仅子代理可用）。
- 子代理：继承全部已注册工具（文件、shell、sessions、task_manager、subagent_router 等）。

## MCP 服务配置
- 配置文件：`~/.deepseek_cli/auth/mcp.config.json`
- 聊天内管理：`/mcp`（查看）、`/mcp_set`（编辑）、`/mcp_tools`（为当前模型启用工具）
- 内置：`chrome_devtools`（默认禁用、仅子代理可用）。如需浏览器自动化/调试，请在 UI（Admin → MCP Server 管理）里启用。
- 端点格式：
  - Stdio（本地拉起）：`cmd://node /abs/path/server.js ...` 或直接填命令行 `npx -y <pkg> ...`
  - HTTP：`http(s)://host/path`（Streamable HTTP；旧版 SSE 服务会自动回退）
  - WebSocket：`ws(s)://host/path`

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

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

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

## 自定义系统 Prompt
- 主程序 prompts：
  - `~/.deepseek_cli/auth/system-prompt.yaml`（`internal_main`，内置只读）
  - `~/.deepseek_cli/auth/system-default-prompt.yaml`（`default`，内置只读）
  - `~/.deepseek_cli/auth/system-user-prompt.yaml`（`user_prompt`，可编辑）
- 子代理 prompts：
  - `~/.deepseek_cli/auth/subagent-system-prompt.yaml`（`internal_subagent`，内置只读）
  - `~/.deepseek_cli/auth/subagent-user-prompt.yaml`（`subagent_user_prompt`，可编辑）

## 环境与调试
- 推荐：在桌面 App 管理台 → `API Keys` 配置 `DEEPSEEK_API_KEY`（写入 `~/.deepseek_cli/admin.db.sqlite`，CLI 启动时自动注入进程环境）。
- 也可继续用系统环境变量方式设置（subagent_router 继承父进程 env）；若系统已设置同名 env，默认优先用系统值，可在 `API Keys` 里启用“覆盖系统 env”强制使用 UI 中保存的 key。
- 请求日志：`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 分钟，仍提前被取消可提升上述环境变量。
- **长命令超时**：改用 `session_run` + `session_capture_output`。
- **历史过长**：依靠自动裁剪，或 `/reset` 重开会话。
- **Windows 终端中文乱码**：通常是终端代码页不是 UTF-8（65001）。可先执行 `chcp 65001` 再运行；CLI 也会尝试在启动时临时切到 UTF-8（如需关闭可设 `MODEL_CLI_DISABLE_WIN_UTF8=1`）。

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