shinobi

# Shinobi [](https://shinobi-apps.com/shinobi) [](https://github.com/numbererikson/shinobi/actions/workflows/test.yml) [](https://opensource.org/licenses/MIT) [](https://nodejs.org) AI 编程代理的任务主干。Shinobi 持有跨会话的决策，**主动搜索过去的死胡同——在代理编写代码之前进行语义搜索**，并将审批路由到您的手机。一个大脑，每个设备：笔记本电脑、云会话和移动设备都连接到同一个存储库。 与 Claude Code、Cursor、Cline、Continue.dev、Zed 兼容 — 任何支持 MCP 的客户端。 > **状态：** v0.3 — 自主代理。将其作为托管的 HTTP `/mcp` 大脑（默认部署）或自托管的本地实例运行。移动推送、头部调度循环、git 工作树上的并行集群和基于远程 MCP 基础的审计→子任务摄取。39 个 MCP 工具、网页仪表盘、移动审批、插件系统、可选的语义回忆。 ## 功能 大多数工具试图成为内存的附加组件。Shinobi 是您的代理工作的**任务主干** — 持久的工作骨架、决策和已知的错误路径，它们的生命周期超出任何单个会话，并跨所有设备。 - **任务主干** — 项目 + 子任务，代理声称、完成或转移；多会话工作的持久骨架 - **决策的存活** — 记录架构选择及其理由，以便下一个会话（在任何设备上）不会重新协商 - **死胡同，在您构建前搜索** — 每个失败的方法都被记录下来，并在代理计划类似方法时**语义匹配**，因此它永远不会在同一个墙上烧毁第二个会话。没有其他工具执行此操作。 - **手机上的审批** — `request_approval` 将决策推送到您的口袋；代理会阻塞，直到您点击确定/取消，无论您在哪里 - **一个大脑，每个设备** — 笔记本电脑编辑器、Claude Code 云会话和移动聊天都通过远程 MCP 访问同一个存储库；无需同步步骤，无需设备间漂移 - **计划** — 版本控制的计划快照，可在任务中途检索 - **上下文** — 每个项目的约定、“不要碰”规则、测试模式、部署说明、文件注释 - **回忆** — 默认情况下使用全文索引（FTS5），当配置了嵌入提供程序时使用语义索引（基于嵌入） - **笔记** — 自由格式的注释和语音笔记（audio_path 字段） - **活动时间线** — 每个写入路径都记录在时间线中，以便您可以重放发生的事情 - **git 链接** — `link_commit` 通过 `[SHI-N]` 标签或 `target_path` 属性将提交与子任务绑定 - **网页仪表盘** — Hono 服务的 Kanban + 决策 + 死胡同 + 笔记 + 计划 + 上下文 + 时间线 + 分析 - **插件系统** — 在 `~/.shinobi/plugins/` 中放置一个 `.js` 文件，或安装一个 `@shinobi/plugin-*` npm 包，并注册自定义 `plugin_*` 工具 **托管或自托管，随您选择。** 默认部署是一个远程大脑，位于 HTTP `/mcp` 端点后面（我们在 `shinobi.shinobi-apps.com` 上运行）；同一个二进制文件仍然可以在您希望将所有内容保留在自己的机器上时，作为完全本地的单机实例运行。仅当您想要语义回忆时，才需要自带嵌入式提供程序。 > 🚀 新来者？请遵循 [快速入门](docs/getting-started.md) — 十分钟内从零到一个正常运行的大脑。正在进行多设备操作？[远程模式](docs/remote-mcp.md) + [$0/月云部署](docs/deploy-gcp-free.md)。 ## 安装 要求： - `PATH` 中有 Node.js 18+ - 用于 `better-sqlite3` 原生构建的 C++ 构建工具链（大多数系统都有预编译的二进制文件；Windows 可能需要 [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) 作为备用方案） ### 从 npm（推荐） ```bash npm install -g @shinobiapps/shinobi ``` 二进制文件是 `shinobi`（例如 `shinobi serve`、`shinobi dashboard`）。 ### 从 GitHub（最新，未发布） ```bash npm install -g github:numbererikson/shinobi ``` 从 `main` 拉取。有助于尝试未发布的修复。在 Windows 上，您可能需要将 Node 目录添加到系统 `PATH` 中，然后此操作才有效，因为 `prepare` 构建脚本在子shell中运行，该子shell不总是继承会话 `PATH`（Laragon， 便携式安装）。如果安装失败并显示 `'node' 未识别`，请优先使用上面的 npm 安装。 ### 从克隆的源文件夹（用于开发/贡献） ```bash git clone https://github.com/numbererikson/shinobi.git cd shinobi npm install # 触发 `prepare` → 构建 dist/ npm install -g . ``` ### 然后初始化 在您希望 Shinobi 可用于您的 MCP 客户端的任何项目根目录中： ```bash shinobi init shinobi dashboard ``` `init` 将： 1. 创建 `~/.shinobi/`，包含 `config.json`、`.env` 模板和 `shinobi.db`（应用迁移） 2. 为当前项目添加 `.mcp.json` 代码段 3. 打印下一步骤 `shinobi init` 为两个客户端写入配置，并带有工作区本地的 MCP 约定： - **Claude Code** — `<workspace>/.mcp.json` - **Cursor** — `<workspace>/.cursor/mcp.json` 重启客户端后，`mcp__shinobi__*` 工具变得可用。 对于其他 MCP 客户端（Cline、Continue.dev、Zed），请参见下面的 [MCP 客户端设置](#mcp-client-setup) 部分。 然后打开： ```text http://127.0.0.1:8765 ``` 在 Windows PowerShell 上，如果脚本执行阻止了 `shinobi`，请使用 `.cmd` 辅助程序： ```powershell shinobi.cmd dashboard ``` 如果您升级了 Node 或复制了一个旧的 `node_modules`，请重建原生依赖项： ```bash npm rebuild better-sqlite3 ``` 重要：代码位于 Shinobi 文件夹中，但本地内存数据库位于： ```text ~/.shinobi/shinobi.db ``` 要移动工具，只需复制/克隆 Shinobi 文件夹并运行上述安装命令。要移动现有的项目、任务、决策、笔记和上下文，还可以复制 `~/.shinobi/` 或使用 `shinobi sync`。 ## MCP 客户端设置 以下每个代码段都使用**相同的 JSON 结构** — `command` 是运行 Shinobi 的 Node 二进制文件的路径，`args` 是 `[<绝对路径到 dist/cli.js>, "mcp"]`。打印您机器上的确切值： ```bash shinobi init --print-config ``` （或从您已经运行 `shinobi init` 的任何项目中读取 `.mcp.json` — 值是相同的。） ### Claude Code 自动添加 — `shinobi init` 编写 `<workspace>/.mcp.json`。重启 Claude Code 以获取服务器。 ### Cursor 自动添加 — `shinobi init` 编写 `<workspace>/.cursor/mcp.json`。适用于 Cursor 0.43+。重启 Cursor 或重新加载工作区。 对于**全局** Cursor 配置（每个项目都看到 Shinobi），请将相同的代码段粘贴到 `~/.cursor/mcp.json`（或使用 Cursor 设置 → MCP）。 ### Cline（VS Code 扩展） 打开 Cline 的设置文件： - Windows： `%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json` - macOS： `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` - Linux： `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` 将您项目的 `.mcp.json` 内容合并到文件的 `mcpServers` 对象中。重启 VS Code。 ### Continue.dev 编辑 `~/.continue/config.json`。将 Shinobi 添加到 `mcpServers` 数组（注意：Continue 使用 **数组**，而不是像其他客户端一样的对象）： ```json { "mcpServers": [ { "name": "shinobi", "command": "/绝对路径/到/node", "args": ["/绝对路径/到/dist/cli.js", "mcp"] } ] } ``` 使用您的 `.mcp.json` 中的值作为 `command` 和 `args`。 ### Zed 编辑 `~/.config/zed/settings.json`。Zed 在 `context_servers` 下嵌套 MCP 服务器： ```json { "context_servers": { "shinobi": { "command": { "path": "/绝对路径/到/node", "args": ["/绝对路径/到/dist/cli.js", "mcp"] } } } } ``` 重启 Zed。 ### 通用/其他客户端 任何支持标准 `{ command, args }` 服务器规范的 MCP 客户端都应该有效。使用您的 `.mcp.json` 中的值： - `command`：运行 Shinobi 的 Node 二进制文件的绝对路径 - `args`： `[<绝对路径到 dist/cli.js>, "mcp"]` 避免在 MCP 配置中使用裸 `shinobi` 命令 — 许多客户端使用 `shell: false` 启动服务器，这会跳过 OS PATH 解析，使得 `shinobi` 在终端中有效。 ### 远程模式（默认部署） 在服务器上托管一个 Shinobi 大脑，并将所有设备连接到它 — 您的桌面编辑器、Claude Code 网络/移动会话、任何支持远程 MCP 的客户端。 `shinobi serve` 在 `/mcp` 处公开 MCP 端点（可流式传输的 HTTP，**无状态**，带有身份验证令牌）以及仪表板： ```bash claude mcp add --transport http shinobi https://your-host/mcp \ --header "Authorization: Bearer YOUR_TOKEN" ``` 这是运行 Shinobi 的推荐方式 — 一个大脑，从所有设备都可以访问。相同的二进制文件仍然可以在您希望在自己的机器上托管所有内容时，作为本地单机实例运行。完整的部署指南（Docker、Cloudflare Tunnel、GCP Always Free、客户端配置）： [docs/remote-mcp.md](docs/remote-mcp.md). ## 命令行界面 ``` shinobi <命令> [选项] 命令： init 引导 ~/.shinobi/ 并在当前目录中添加 .mcp.json mcp 通过 stdio 运行 MCP 服务器（由 MCP 客户端调用） migrate 应用待处理的 SQL 迁移 dashboard 在 localhost 上启动网页仪表板（默认端口 8765） serve [--host H] [--port P] 仪表板 + MCP HTTP 端点（/mcp）合二为一 — 参见 docs/remote-mcp.md sync init <path> [branch] 将本地 git 仓库配置为跨机器同步目标 sync push 快照数据库并将其提交到同步仓库 sync pull 从同步仓库的快照中恢复数据库 sync status 显示最后的推送/拉取时间戳和 git 状态 dispatch [--once|--drain] 自主循环：拉取 next_task → 运行 worker → 完成/取消阻塞 → 重复 [--project N] [--interval S] [--max-failures N] 通过 SHINOBI_WORKER_CMD（例如 'claude -p "$SHINOBI_TASK_PROMPT"'）运行 worker；未设置 → 干运行 swarm --agents N N 个调度循环并行运行，每个循环在自己的 git 工作树/分支中，一个共享 [--project N] [--drain] 大脑。原子声明 → 没有两个代理会获得相同的任务。--no-worktree / --keep-worktrees ``` ## MCP 工具（39） | 组 | 工具 | |---|---| | 项目 | list_projects, get_project, create_project, update_project, archive_project, unarchive_project, delete_project | | 子任务 | list_tasks, get_task, create_task, bulk_create_tasks, update_subtask, delete_subtask, claim_task, complete_task, next_task | | 决策 | log_decision, decisions_for_file, update_decision_status | | 死胡同 | log_dead_end, check_dead_ends | | 笔记 | add_note, list_notes | | 计划 | save_plan, get_plan | | 上下文 | get_context, update_context | | 回忆 | recall (FTS5 或语义) | | 时间线 | history, link_commit | | 工作流 | agent_bootstrap, session_closeout, file_context | | 提取 | extract_decisions, compress_session_summary | | 审批 | request_approval | | 通知 | notify | | 发现 | ingest_findings | | 插件 | plugin_hello | ## 架构 | 层 | 技术 | |---|---| | 语言 | TypeScript（严格模式，ES2022，NodeNext） | | 运行时 | Node 18+ | | MCP | `@modelcontextprotocol/sdk` 1.x | | 存储 | SQLite via `better-sqlite3`（WAL 模式） | | 仪表板 | Hono + `@hono/node-server`（同一进程，localhost:8765） | | 嵌入（可选） | OpenAI text-embedding-3-small / Voyage voyage-3-lite / Ollama nomic-embed-text | | 迁移 | 前向迁移，sha256 校验和，`schema_migrations` 表 | 参见 [docs/architecture.md](docs/architecture.md) 以了解请求生命周期和模块布局。 ## 仪表板身份验证 仪表板在环回绑定（`127.0.0.1`、`localhost`、`::1`）上开放，并使用令牌保护非环回绑定。令牌从 `SHINOBI_DASHBOARD_TOKEN` 读取，否则加载到 `~/.shinobi/dashboard-token`，否则自动生成并保存在那里。 `/health` 始终开放用于探测。 浏览器流程 — 使用令牌打开仪表板一次，cookie 就会生效： ```text http://192.168.1.10:8765/?token=YOUR_TOKEN ``` Curl / 脚本 — 以下任何一种方法都有效： ```bash curl -H "Authorization: Bearer $SHINOBI_DASHBOARD_TOKEN" http://192.168.1.10:8765/api/projects/1/snapshot curl -H "X-Shinobi-Token: $SHINOBI_DASHBOARD_TOKEN" http://192.168.1.10:8765/api/projects/1/snapshot curl --cookie "shinobi_token=$SHINOBI_DASHBOARD_TOKEN" http://192.168.1.10:8765/api/projects/1/snapshot ``` 参见 [docs/configuration.md](docs/configuration.md#dashboard) 以获取完整的环境变量参考。 ## 跨机器同步 Shinobi 通过私有 git 仓库同步您的本地 SQLite 数据库。每个机器只需设置一次： ```bash # 一次：克隆私有 GitHub 仓库作为同步仓库 git clone git@github.com:USER/shinobi-sync.git ~/shinobi-sync # 每个机器一次：告诉 shinobi 关于它 shinobi sync init ~/shinobi-sync main # 从写入机器推送： shinobi sync push # 在读取机器上拉取： shinobi sync pull ``` 数据库文件作为二进制文件位于 `main` 分支上；预先存在的本地数据库备份到 `<path>.bak-<timestamp>` 之前恢复。 ## 配置 编辑 `~/.shinobi/.env` 或在运行 `shinobi mcp` 之前设置环境变量： | 变量 | 默认值 | 目的 | |---|---|---| | `SHINOBI_DB_PATH` | `~/.shinobi/shinobi.db` | SQLite 位置 | | `SHINOBI_CONFIG_DIR` | `~/.shinobi` | 配置 + 插件目录 | | `SHINOBI_PLUGINS_DIR` | `${configdir}/plugins` | 插件发现目录 | | `SHINOBI_DASHBOARD_PORT` | `8765` | 仪表板端口 | | `SHINOBI_DASHBOARD_HOST` | `127.0.0.1` | 仪表板绑定主机。环回跳过身份验证；非环回自动启用令牌身份验证。 | | `SHINOBI_DASHBOARD_TOKEN` | _(自动)_ | 覆盖仪表板令牌；需要时自动生成到 `~/.shinobi/dashboard-token`。 | | `SHINOBI_EMBED_PROVIDER` | `none` | `openai` / `voyage` / `ollama` / `none` | | `SHINOBI_EMBED_API_KEY` | — | OpenAI / Voyage 认证信息（否则回落到 `OPENAI_API_KEY` / `VOYAGE_API_KEY`） | | `SHINOBI_EMBED_MODEL` | 提供者默认值 | 覆盖模型 ID | | `SHINOBI_EMBED_DIMS` | 提供者默认值 | 覆盖维度 | | `SHINOBI_OLLAMA_URL` | `http://localhost:11434` | Ollama 端点 | | `SHINOBI_MIGRATIONS_DIR` | `<package>/migrations` | 覆盖迁移源 | 完整参考： [docs/configuration.md](docs/configuration.md). ## 插件 在 `~/.shinobi/plugins/` 中编写单个 `.js` 文件： ```javascript // ~/.shinobi/plugins/my-plugin.js export default function register(registry, api) { registry.registerTool({ name: 'plugin_count_open', description: 'Count open decisions across all projects', inputSchema: { type: 'object', properties: {}, additionalProperties: false }, handler: (_args, api) => { const projects = api.listProjects(); let total = 0; for (const p of projects) { total += api.listDecisions({ projectId: p.id, status: 'open' }).length; } return { open_decisions: total }; }, }); } ``` 重启 MCP 客户端后，`mcp__shinobi__plugin_count_open` 即可使用。参见 [docs/plugin-development.md](docs/plugin-development.md). ## 路线图 - **v0.2** — 远程 MCP 基础：无状态 HTTP `/mcp` 端点，Docker + GCP Always Free 部署，Cloudflare Tunnel，环境变量驱动的 `.mcp.json` 实现云会话。一个大脑连接笔记本电脑、云和移动设备。 - **v0.3（当前）** — 自主代理：推送通知（任务完成/代理阻塞）→ 调度循环（无头代理拉取 `next_task` 并工作，同时您睡觉）→ Shinobi Swarm（N 个并行代理，工作树隔离，共享死胡同），以及 `ingest_findings`（审计→子任务图→集群），从 v0.4 提前。 - **v0.4** — 单元测试覆盖率通过 `tools/*`；在 `ingest_findings` 基础上更丰富的补救模板和查找源适配器。 - **v1.0** — 稳定性、安全审计、性能通过；可选团队模式/托管 SaaS 仅在有需求信号时提供。 ## 更新日志 参见 [CHANGELOG.md](CHANGELOG.md) 获取发行说明。 ## 贡献 参见 [CONTRIBUTING.md](CONTRIBUTING.md). 欢迎提出问题和 PR。 您参与贡献即表示同意我们的 [行为准则](CODE_OF_CONDUCT.md). ## 安全 有关漏洞报告，请参见 [SECURITY.md](SECURITY.md) — 请勿公开安全问题。 ## 许可 MIT — 参见 [LICENSE](LICENSE).