# SakuraBot Hub

面向 DSH 与 MCP 客户端的本地工具箱。一个母插件统一管理九个子插件；每个子插件可分别安装、启用、停用和卸载。管理界面提供配置、检查、操作表单与结果。

## 授权与商业化

当前 0.2.0 版本仍为 MIT，可免费商用。后续新增代码与模块计划采用“非商用免费、商用付费”；企业内部业务使用属于商用。适用范围以届时各组件的完整许可为准，见[授权政策与版本边界](docs/LICENSING.md)。

## 当前能力

| 子插件 | 已提供操作 | 运行前置条件 |
|---|---|---|
| 项目记忆 | 按项目新增、编辑、搜索、删除和导出记录 | 本地独立数据目录 |
| 技能中心 | 阅读三篇原创通用技能、记录主动使用 | 不导入私人技能或记忆 |
| 联网研究 | 公开网页读取、百科检索、DSH 搜索接口 | 网络；DSH 搜索需宿主已配置提供方 |
| 浏览器与电脑 | 独立浏览器读页、截图；代理宿主观察/点击 | Chromium 路径、允许站点；桌面模式另需宿主电脑工具与活跃 Agent |
| 文件与文档 | 文件清单、UTF-8 文本读取/搜索、生成 Markdown/JSON/TXT | 显式授权目录；输出新文件，不覆盖原文件 |
| 图像工作室 | 图片信息、等比缩放、PNG/JPEG/WebP 转换 | 显式授权目录；sharp 随依赖安装 |
| 视频与音频 | 媒体信息、抽帧、剪片、WAV 导出 | 本机 FFmpeg 与 FFprobe |
| A2S 协作 | 生成交接任务、代理 DSH 启动/查询/补充/停止子代理 | 执行代理需活跃 DSH Agent 与宿主模型配置 |
| 开发辅助 | 项目概况、Git 状态/差异、源码搜索 | 授权项目目录；Git 操作需本机 Git |

安装启用只代表允许调用；外部依赖和配置会在实际执行时检查。图片处理不含生图模型，媒体工具不含视频生成模型，文件工具当前不解析 PDF/Office。A2S“准备任务”不会假报模型已经执行。跨 IDE 采用 MCP 协议适配，不宣称所有 IDE 原生页面均已测试。

## 独立管理界面

需要 Node.js 22.19.0 或更新版本。克隆后在项目目录运行：

```sh
npm ci --ignore-scripts
npm run build
```

PowerShell：

```powershell
$env:SAKURA_HUB_DATA = Join-Path $PWD '.local/demo-data'
npm run preview
```

macOS / Linux：

```sh
SAKURA_HUB_DATA="$PWD/.local/demo-data" npm run preview
```

打开进程输出的本机地址。默认仅监听 `127.0.0.1`，由操作系统分配端口。安装并启用需要的子插件，进入“管理”，保存配置并检查，然后运行操作。文件、图像、媒体和开发工具只访问你填写的专用目录；新文件写到该目录的 `.sakura-output/`。

状态保存在指定数据目录的 `hub-state.json`。卸载保留数据与配置。一个数据目录只允许一个进程使用；DSH、独立管理页和 MCP 同时运行时请分别配置数据目录。

## DSH 插件

已适配 DSH 0.2.1-rc.2。执行 `npm pack --ignore-scripts` 可生成本地包，通过 DSH 官方插件安装流程选择该包。宿主提供 DSH 工具服务与 React；它们是可选 peer 依赖，独立预览不会安装另一份 DSH 内核。

插件使用官方连接 RPC 和工具注册入口。子代理、电脑工具的代理调用沿用 DSH 原生策略、审批与 Agent 身份；管理页不会根据一个会话 ID 伪造 Agent。缺少宿主服务会显示具体错误，不会自动读取其他配置或私人账号。

本仓库不包含正式 Desktop 安装或自动重启脚本。安装前保存工作，按宿主提示操作。

## IDE / Agent 接入

参见 [MCP 接入说明](docs/MCP.md)。入口：

```sh
node scripts/mcp.mjs --data-dir /absolute/dedicated/data --config /absolute/sakura-mcp.json
```

MCP 只暴露启用的工具和只读状态。目录、可执行程序与插件启用集合通过用户启动配置指定，模型不能通过 MCP 修改这些权限。

## 开发与验证

```sh
npm test
npm run build
npm pack --ignore-scripts
```

测试包含核心持久化、配置/取消/生命周期、真实文件与 Git、真实 sharp、真实 FFmpeg、官方 MCP SDK Client 的真实 stdio 往返以及模拟宿主代理。没有 FFmpeg 时媒体测试会明确跳过；完整媒体验收需要安装 FFmpeg 后重跑。宿主模拟测试不等同于真实模型或桌面点击已经完成。

结构：`packages/hub` 为核心与 UI，`packages/capabilities` 为七类能力，原有两个子插件独立存放；`index.mjs` 是 DSH 适配器，`scripts/mcp.mjs` 是 MCP 适配器。新增可信打包子插件遵循 definition/probe/invoke 接口，无需复制母插件。

## 数据与边界

这是个人本地工具，不是多租户服务或操作系统沙箱。请仅授权自己控制的专用目录，不要允许不可信进程同时改写目录/符号链接。工具拒绝越界与常见敏感路径；这不能替代操作系统权限。联网资料作为外部数据处理，不作为指令。独立浏览器使用新会话，不复用私人登录资料；允许站点需要显式配置。取消会尽力终止在途操作，已经输出的文件会保留。

本项目由 Micker / Ghoscro 创建。公开版本不包含私人记忆、用户数据、账号凭据、内部部署详情或私有完整自动化流程；示例使用合成数据。来源见 [PROVENANCE.md](PROVENANCE.md)。采用 [MIT 许可证](LICENSE)，允许商用、修改与再分发，须保留版权及许可声明。

## 发布验证状态（0.2.0）

本插件采用用户自配模型方式发布，不附带模型账号、密钥或推理服务。A2S 真实模型委派回合尚未验证；准备任务和宿主工具转发已实现，但不能据此推断模型执行成功。

本次发布通过 71 项自动化测试（无跳过）和 21 项官方 DSH 隔离宿主检查。文件、Git、图片、媒体处理、独立浏览器与 MCP stdio 已做实际调用。原生电脑点击尚未实机验证；Wikipedia 检索在验证环境中超时；各 IDE 的原生界面尚未逐一测试。上述外部能力需要用户配置相应服务后验证。