Shinobi

Shinobi

面向 AI 编码 Agent 的任务主干。Shinobi 保存能跨会话延续的决策，在 Agent 编写代码之前，主动以语义方式搜索你过去走过的死胡同，并将审批请求发送到你的手机。一个大脑，适用于每台设备：笔记本、云端会话和移动设备都连接到同一个存储。

适用于 Claude Code、Cursor、Cline、Continue.dev、Zed，以及任何兼容 MCP 的客户端。

状态： v0.3 — 自主 Agent。可将其作为托管的 HTTP /mcp 大脑运行（默认部署方式），也可自托管本地实例。在远程 MCP 基础上，新增移动推送、无头调度循环、通过 git worktree 并行协作，以及审计→子任务导入。提供 39 个 MCP 工具、Web 仪表板、移动审批、插件系统和可选语义回忆。

功能

大多数工具都试图作为附加组件提供记忆功能。Shinobi 是 Agent 工作所依托的任务主干——它是工作、决策和已知错误路径的持久骨干，能跨越单个会话，并伴随你使用每台设备。

• 任务主干 — 项目及其子任务由 Agent 认领、完成或调整方向；这是跨会话工作的持久骨架
• 能延续的决策 — 记录架构选择及其理由，让下一次会话（无论在哪台设备上）无需重新讨论
• 构建前搜索死胡同 — 记录每种失败的方案，并在 Agent 计划采用类似方案时立即进行语义匹配，避免它再次花一个会话撞上同一堵墙。没有其他工具能做到这一点。
• 手机审批 — request_approval 会将决策推送到你的口袋；无论你身在何处，Agent 都会阻塞等待你点击“是”或“否”
• 一个大脑，适用于每台设备 — 笔记本编辑器、Claude Code 云端会话和移动聊天都通过远程 MCP 访问同一个存储；无需同步，也不会出现设备间数据偏差
• 计划 — 带版本的计划快照，可在任务进行中检索
• 上下文 — 每个项目的约定、“请勿修改”规则、测试模式、部署说明和文件注释
• 回忆 — 默认使用全文检索（FTS5）；配置嵌入提供方后可使用语义检索
• 笔记 — 自由格式的注释和语音笔记（audio_path 字段）
• 活动时间线 — 每条写入路径都会记录到时间线，方便回放发生过的事
• Git 关联 — link_commit 通过 [SHI-N] 标签或 target_path 归属关系，将提交关联到子任务
• Web 仪表板 — 由 Hono 提供服务的看板，包含决策、死胡同、笔记、计划、上下文、时间线和分析
• 插件系统 — 将 .js 文件放入 ~/.shinobi/plugins/，或安装 @shinobi/plugin-* npm 包并注册自定义 plugin_* 工具

选择托管还是自托管，由你决定。 默认部署方式是在 HTTP /mcp 端点后运行一个远程大脑（我们运行在 shinobi.shinobi-apps.com）；如果你更愿意将所有内容留在自己的设备上，同一个二进制文件也能作为完全本地的单机实例运行。只有在需要语义回忆时，才需要自带嵌入提供方。

🚀 刚来？请按照入门指南操作，十分钟内即可启动可用的大脑。要在多台设备间使用？请查看远程模式和每月 0 美元的云端部署。

安装

要求：

• PATH 中需有 Node.js 18+
• 用于 better-sqlite3 原生构建的 C++ 构建工具链（大多数系统都有预构建二进制文件；Windows 可能需要将 Visual Studio Build Tools 作为备用方案）

从 npm 安装（推荐）

npm install -g @shinobiapps/shinobi

二进制文件名为 shinobi（例如，shinobi serve、shinobi dashboard）。

从 GitHub 安装（最新的未发布版本）

npm install -g github:numbererikson/shinobi

从 main 拉取代码。适合尝试尚未发布的修复。在 Windows 上，可能需要先将 Node 目录添加到系统 PATH，否则此操作可能无法成功，因为 prepare 构建脚本会在子 shell 中运行，而子 shell 并不总是会继承每个会话的 PATH（Laragon、便携式安装）。如果安装失败并提示 'node' is not recognized，请优先使用上面的 npm 安装方式。

从克隆的源代码文件夹安装（用于开发 / 贡献）

git clone https://github.com/numbererikson/shinobi.git
cd shinobi
npm install            # triggers `prepare` → builds dist/
npm install -g .

然后进行初始化

在你希望 Shinobi 能供 MCP 客户端使用的任意项目根目录中：

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 客户端设置部分。

然后打开：

http://127.0.0.1:8765

在 Windows PowerShell 中，如果脚本执行策略阻止运行 shinobi，请使用 .cmd 启动器：

shinobi.cmd dashboard

如果升级了 Node 或复制了旧的 node_modules，请重新构建原生依赖：

npm rebuild better-sqlite3

重要：代码位于 Shinobi 文件夹中，但本地记忆数据库位于：

~/.shinobi/shinobi.db

若只需迁移工具，请复制/克隆 Shinobi 文件夹并运行上面的安装命令。若还要迁移现有项目、任务、决策、笔记和上下文，可以复制 ~/.shinobi/，或使用 shinobi sync。

MCP 客户端设置

下面的每个片段都使用相同的 JSON 结构——command 是运行 Shinobi 的 Node 二进制文件路径，args 是 [<absolute path to dist/cli.js>, "mcp"]。运行以下命令以获取适用于你设备的准确值：

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 使用的是数组，而不是其他客户端使用的对象）：

{
  "mcpServers": [
    {
      "name": "shinobi",
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/dist/cli.js", "mcp"]
    }
  ]
}

command 和 args 请使用项目 .mcp.json 中的值。

Zed

编辑 ~/.config/zed/settings.json。Zed 将 MCP 服务嵌套在 context_servers 中：

{
  "context_servers": {
    "shinobi": {
      "command": {
        "path": "/absolute/path/to/node",
        "args": ["/absolute/path/to/dist/cli.js", "mcp"]
      }
    }
  }
}

重启 Zed。

通用 / 其他客户端

任何支持标准 { command, args } 服务规范的 MCP 客户端都应该可以使用。请使用 .mcp.json 中的相同值：

• command：运行 Shinobi 的 Node 二进制文件的绝对路径
• args：[<absolute path to dist/cli.js>, "mcp"]

避免在 MCP 配置中使用不带路径的 shinobi 命令——许多客户端会通过 shell: false 启动服务，从而跳过操作系统的 PATH 解析，而该解析机制正是 shinobi 能在终端中运行的原因。

远程模式（默认部署方式）

在服务器上托管一个 Shinobi 大脑，并让所有设备连接到它——你的 桌面编辑器、Claude Code 网页版／移动端会话，以及任何支持远程 MCP 的 客户端。shinobi serve 会在 /mcp 暴露 MCP 端点（可流式传输的 HTTP、 无状态、Bearer 令牌身份验证），并同时提供仪表板：

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。

命令行

shinobi <command> [options]

Commands:
  init                            Bootstrap ~/.shinobi/ and drop .mcp.json in the current directory
  mcp                             Run the MCP server over stdio (invoked by the MCP client)
  migrate                         Apply pending SQL migrations
  dashboard                       Start the web dashboard on localhost (default port 8765)
  serve [--host H] [--port P]     Dashboard + MCP HTTP endpoint (/mcp) in one process — see docs/remote-mcp.md
  sync init <path> [branch]       Configure a local git repo as the cross-machine sync target
  sync push                       Snapshot the DB and commit it to the sync repo
  sync pull                       Restore the DB from the sync repo's snapshot
  sync status                     Show last push/pull timestamps and git status
  dispatch [--once|--drain]       Autonomous loop: pull next_task → run worker → complete/unblock → repeat
           [--project N] [--interval S] [--max-failures N]   Worker via SHINOBI_WORKER_CMD (e.g. 'claude -p "$SHINOBI_TASK_PROMPT"'); unset → dry-run
  swarm --agents N                N dispatch loops in parallel, each in its own git worktree/branch, one shared
        [--project N] [--drain]   brain. Atomic claim → no two agents take the same task. --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
存储	通过 better-sqlite3 使用 SQLite（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。

仪表板身份验证

仪表板在环回地址绑定（127.0.0.1、localhost、::1）时无需身份验证，在任何非环回地址绑定时均受令牌保护。令牌从 SHINOBI_DASHBOARD_TOKEN 读取；如果没有设置，则从 ~/.shinobi/dashboard-token 加载；若该文件也不存在，则会自动生成令牌并保存到该文件。/health 始终开放，供探测使用。

浏览器流程——使用令牌打开一次仪表板，之后 Cookie 会一直保留：

http://192.168.1.10:8765/?token=YOUR_TOKEN

Curl／脚本——以下任一种方式均可：

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。

跨机器同步

Shinobi 通过私有 Git 仓库同步本地 SQLite 数据库。每台机器只需设置一次：

# Once: clone a private GitHub repo to act as the sync repo
git clone [email protected]:USER/shinobi-sync.git ~/shinobi-sync

# Once per machine: tell shinobi about it
shinobi sync init ~/shinobi-sync main

# Push from the writer machine:
shinobi sync push

# Pull on the reader machine:
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。

插件

在 ~/.shinobi/plugins/ 中编写一个 .js 文件：

// ~/.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。

路线图

• v0.2 — 远程 MCP 基础：无状态 HTTP /mcp 端点、 Docker + GCP Always Free 部署、Cloudflare Tunnel，以及由环境变量驱动的 .mcp.json 云会话配置。一套大脑，跨笔记本电脑、云端和移动设备使用。
• v0.3（当前） — 自主 Agent：推送通知（任务已完成 / Agent 已阻塞）→ 分发循环（无头 Agent 拉取 next_task，并在你休息时执行任务）→ Shinobi Swarm（N 个并行 Agent、工作树隔离、 共享失败记录），以及从 v0.4 提前纳入的 ingest_findings（审计 → 子任务图 → 群集）。
• v0.4 — 对 tools/* 进行单元测试覆盖；在 ingest_findings 基础上提供更丰富的修复模板 和发现源适配器。
• v1.0 — 稳定性、安全审计、性能优化；仅在有需求信号时提供可选的团队模式 / 托管式 SaaS。

更新日志

发布说明请参见 CHANGELOG.md。

贡献

请参见 CONTRIBUTING.md。欢迎提交问题和 PR。

参与即表示你同意我们的行为准则。

安全

漏洞报告请参见 SECURITY.md——安全问题请不要通过公开问题提交。

许可证

MIT——参见 LICENSE。