内容
<div align="center">
<img src="frontend/public/favicon.svg" width="72" alt="Black Box logo">
<h1>Black Box</h1>
<p><strong>本地优先的内存和编码代理协调。</strong></p>
<p>
保留决策。原子化认领工作。留下类型化的交接。<br>
让下一个代理从上下文开始，而不是考古。
</p>
<p>
<a href="https://github.com/nathanmauro/black-box/actions/workflows/ci.yml"><img src="https://github.com/nathanmauro/black-box/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
<a href="https://openjdk.org/projects/jdk/21/"><img src="https://img.shields.io/badge/Java-21-ED8B00?logo=openjdk&logoColor=white" alt="Java 21"></a>
<a href="http://localhost:8766/mcp"><img src="https://img.shields.io/badge/MCP-Streamable_HTTP-7C6CF2" alt="MCP Streamable HTTP"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-2EA44F.svg" alt="MIT License"></a>
</p>
</div>
Black Box 是一个可写的内存总线和协调账本，适用于 Codex、Claude Code 和其他 MCP 客户端。代理提交值得保留的推理，通过 SQLite 支持的任务队列进行协调，并在后续会话中回忆确切的决策或完成交接。
Black Box 服务器故意不作为代理运行器。它记录意图，仲裁所有权，并公开状态；您的代理和编排器仍然执行工作。
| 记住 | 协调 | 观察 | 保持本地优先 |
| --- | --- | --- | --- |
| 类型决策、交接、观察、替代方案、置信度和开放环 | 冻结规范、精确车道队列、原子化认领、生命周期规则和完成交接 | 活动、逻辑项目、项目感知板、结构化回忆、搜索、SSE 更新和统计 | SQLite 是权威的；Elasticsearch 和模型支持的功能是可选的 |
## 循环
```mermaid
flowchart LR
P[规划器] -->|创建规范| S[冻结规范]
S -->|加入任务| Q[车道队列]
Q -->|原子化认领| W[工作器]
W -->|阻塞或完成| T[任务生命周期]
T -->|完成任务| H[可回忆的交接]
H -->|回忆上下文| N[下一个代理]
```
1. 规划器冻结工作定义并将特定于车道的任务加入队列。
2. 工作器原子化认领其精确车道中优先级最高、时间最老的任务。
3. 每个过渡都经过验证和记录；停滞工作可以被阻塞并显式重置。
4. 完成创建正常的 Black Box 交接并将其链接到任务。
5. 后续代理直接回忆结果，而不是从记录中重建。
任务路径从未启动工作器、执行命令或改变检查点。SSE 帧是唤醒提示；`claimNextTask` 和 `listTasks` 仍然是权威的。
## 查看
### 跟随整个项目故事线
<img src="docs/assets/projects.png" alt="Black Box Projects workspace showing one logical project, its verified worktree scope, recent sessions, saved synthesis, and newest storyline evidence." width="100%">
在单个逻辑身份下分组验证的工作树，检查最新的高信号证据，并跳转到活动、精确范围的面板或回忆，而无需重写记录的历史。
| 协调面板 | 结构化回忆 |
| --- | --- |
| <img src="docs/assets/board.png" alt="Black Box Coordination Board with Open, In Progress, Blocked, and Done lanes." width="100%"> | <img src="docs/assets/recall.png" alt="Black Box Recall workspace showing a typed Handoff and Decision." width="100%"> |
| 检查冻结的意图、所有权、阻塞因素、优先级和链接的完成交接。 | 按仓库或主题查询决策和交接，无需阅读原始记录。 |
## 60 秒开始
要求：Java 21+、Maven 3.9+、`curl` 和 `jq`。
```bash
git clone https://github.com/nathanmauro/black-box.git
cd black-box
./scripts/quickstart.sh
```
快速启动会构建 jar，启动隔离的演示数据库，植入跨代理故事，证明回忆，并打开 UI 访问 [localhost:8766](http://localhost:8766)。
已经构建？
```bash
./scripts/demo.sh
```
想要完整的协调循环，而不影响您的实时数据库？
```bash
./scripts/demo-agent-loop.sh --dry-run
./scripts/demo-agent-loop.sh --run-isolated
```
直接运行应用程序：
```bash
mvn spring-boot:run
curl -fsS http://localhost:8766/api/status | jq
```
## 连接代理
Black Box 通过 `http://localhost:8766/mcp` 上的 Streamable HTTP 公开 MCP。
Codex:
```bash
codex mcp add sba-agentic --url http://localhost:8766/mcp
codex mcp list
```
Claude Code:
```bash
claude mcp add --transport http --scope user sba-agentic http://localhost:8766/mcp
claude mcp list
```
如果工具未显示，请重启客户端。服务器保留历史 MCP ID `sba-agentic`；产品名称为 Black Box。
### 内存工具
| 工具 | 目的 |
| --- | --- |
| `captureDecision` | 保留选择、理由、拒绝的替代方案、置信度和开放环 |
| `captureHandoff` | 留下上下文、开放环和下一个动作给另一个代理 |
| `captureObservation` | 记录简洁的事实或笔记 |
| `recallContext` | 按仓库、主题或事件 ID 回忆结构化决策和交接 |
| `searchSessions` | 搜索捕获的事件和会话 |
| `recentSessions` | 列出最近的代理会话 |
| `localModelStatus` | 检查可选的本地模型后端 |
### 协调工具
| 工具 | 目的 |
| --- | --- |
| `createSpec` | 在目录的规范项目范围或路径下冻结工作定义 |
| `enqueueTask` | 将开放任务添加到精确车道 |
| `claimNextTask` | 原子化认领优先级最高、最老的合格任务 |
| `updateTaskStatus` | 通过允许的生命周期阻塞、重置或取消 |
| `completeTask` | 完成拥有工作并原子化链接可回忆的交接 |
| `listTasks` | 按项目、车道或状态查询完整的任务/规范快照 |
| `getSpec` | 检索冻结的规范主体和出处 |
REST 镜像完全匹配七个协调操作。成功的 REST 和 MCP 结果共享字段名称和 ISO-8601 时间戳；失败使用稳定的类型错误信封。参见 [架构](docs/architecture.md) 以获取完整合同和事务边界。
## 最小代理交接
以下语法是说明性的；MCP 客户端以不同的方式渲染工具调用。
```text
createSpec({
"projectKey": "/workspace/example-app",
"title": "添加健康探测",
"body": "实现 GET /healthz 并证明 200 响应。",
"actor": "规划器"
})
enqueueTask({
"specId": "<returned-spec-id>",
"title": "实现和验证健康探测",
"lane": "codex",
"priority": 10,
"actor": "规划器"
})
claimNextTask({"lane": "codex", "agent": "worker-1"})
completeTask({
"taskId": "<returned-task-id>",
"actor": "worker-1",
"source": "codex",
"clientSessionId": "health-probe-run",
"summary": "实现了并验证了 GET /healthz。",
"openLoops": [],
"nextAction": "运行发布门控。"
})
recallContext({
"repoOrTopic": "<returned-resultHandoffId>",
"withinHours": 24,
"kinds": ["handoff"]
})
```
## 产品界面
- **活动** — 全局事件流、会话浏览器、面部查找工作区和可选的询问界面。
- **项目** — 一个可搜索的逻辑项目工作区，包含验证的工作树范围，无需重写记录的路径。检查组成范围、最近的会话、混合故事线证据和保存的综合信息，或显式合并和撤销模糊的目录范围。
- **面板** — 可搜索的目录项目和车道过滤器，显示明确排队的开放、进行中、阻塞和完成任务，并带有冻结的规范和链接的交接详细信息。选择项目不会从活动、会话或外部系统推断任务；使用其规范范围或路径作为 `createSpec.projectKey` 在排队工作时。
- **回忆** — 按仓库或主题聚焦的决策、交接和观察检索。
- **搜索** — 带有可选 Elasticsearch 结果的本地 SQLite 搜索。
直接打开：
- [活动](http://localhost:8766/)
- [项目](http://localhost:8766/projects)
- [面板](http://localhost:8766/board)
- [回忆](http://localhost:8766/recall)
- [搜索](http://localhost:8766/search)
## 信任和数据边界
SQLite 是会话、事件、结构化内存、规范、任务和生命周期事件的真实来源。服务器默认绑定到 `127.0.0.1`，没有内置身份验证。除非您接受该信任模型，否则不要在网络上公开它。
逻辑项目别名仅影响目录、会话、故事线和保存的合并读取。Black Box 在项目分组时从不重写历史会话/事件路径或任务/规范项目范围。
自动编辑在持久化之前启用，用于私钥块、AWS 凭证、承载令牌或 API 令牌和密码/令牌赋值。仅当您故意想要未编辑的本地存储时，请设置 `SBA_REDACT_ENABLED=false`。
核心捕获、协调和回忆不需要模型和 Elasticsearch。会话摘要是例外：默认的 `external` 后端调用捆绑的 Codex 包装器，并可以通过该供应商路径发送记录文本。设置 `SBA_SUMMARY_BACKEND=local` 以使用 LM Studio 或另一个本地 OpenAI 兼容服务器。
## 板块驱动的运行器模式（可选，配置控制）
Black Box 还附带一个可选的外部运行器进程：`java -jar sba-agentic.jar runner`，一个 CLI 子命令，与 `doctor`、`ingest`、`sessions` 和其他维护命令并列。故事通过面板的新故事表单或通过 `createSpec` 加 `enqueueTask` 在车道 `gate` 中记录，以 `full_auto` 或 `sdlc` 记录在其冻结的规范中，并开始相同的确定性就绪检查。两种模式都使用隔离的工作树、配置的引擎、验证、提交、实时面板更新和工作器会话上下文的线索。 `fake` 引擎可用于测试。
### FULL_AUTO
故事就绪是唯一的人类关口。 通过的关口会排队一个 `auto` 任务，其工作器会构建、验证并提交更改；然后运行器拥有发货。 推送、拉取请求创建和合并仅在存储库配置允许它们且现有的关闭门控通过时发生。
### SDLC
SDLC 在规划和审查后添加审批注释：`gate → plan → approval → build → review → approval → ship`。计划和审查工作器接收只读、无提交合同，并在完成其阶段后用 `plan` 或 `review` 注释完成。计划审批会将构建排队到 `auto` 车道。构建使用相同的执行路径，通过验证的提交，但延迟发货，记录其保留的分支和工作树，并排队 `sdlc:review`。审查针对相同的工作树运行并发布建议的发现；审查审批调用与 FULL_AUTO 相同的发货路径。
在没有匹配的审批的情况下，运行器不会取得任何进展。拒绝记录反馈为已经完成的阶段任务的 `progress` 标记，并排队或发货为零。审批永远不会绕过存储库允许列表、危险设置、推送和自动合并配置、凭证或绿色检查要求。
- 运行器需要通过 `SBA_RUNNER_CONFIG` 或默认 `~/.blackbox/runner.json` 进行显式机器本地配置。它从未提交；从 [`docs/runner-config.example.json`](docs/runner-config.example.json) 开始。配置允许列出存储库并控制推送、自动合并和危险设置。
- 下游行为在两种模式下都关闭：未知的存储库、危险标志、红色检查、缺少审批或缺少凭证会产生仅限本地、等待或阻止的工作，而不会有风险的操作。
- Black Box 服务器仍然从不启动工作器或执行任务命令。运行器是一个单独的进程和一个普通的 REST 客户端，就像任何其他代理或编排器一样。
参见 [FULL_AUTO 架构](docs/architecture.md#optional-full_auto-runner)、[SDLC 架构](docs/architecture.md#optional-sdlc-runner-mode)、[`FULL_AUTO 板块驱动运行器`](docs/superpowers/specs/2026-07-15-full-auto-board-runner.md)和 [`SDLC 模式`](docs/superpowers/specs/2026-07-16-sdlc-mode.md) 以获取完整的管道和防护栏。
## 以服务形式运行
macOS launchd:
```bash
./scripts/deploy-local.sh
```
脚本构建前端和 jar，重启 `com.nathan.sba-agentic`，并等待健康的状况响应。使用 `scripts/black-box.plist.template` 进行首次 LaunchAgent 安装。
macOS 板块运行器 launchd：
`scripts/deploy-runner-local.sh` 将已构建的 jar 部署为 `com.nathan.blackbox-runner` launchd 服务。它不会构建 jar；运行 `scripts/deploy-local.sh` 首先。使用 `scripts/blackbox-runner.plist.template` 进行首次运行器 LaunchAgent 安装。
以手动运行脚本启动或重启运行器。这不是被动服务：启动它会根据 `~/.blackbox/runner.json` 启动自主编排。运行器认领 `gate` 和 `auto` 任务用于 FULL_AUTO 故事，并认领 `gate`、`sdlc:plan`、`auto` 和 `sdlc:review` 任务用于 SDLC 故事；它还会对 SDLC 审批注释做出反应。两种模式都使用配置的引擎、存储库、推送和自动合并设置。查看 [板块驱动的运行器模式](#板块驱动的运行器模式-可选-配置控制) 以获取完整的行为并查看 [`docs/runner-config.example.json`](docs/runner-config.example.json) 以获取配置形状。
Linux systemd:
```bash
cp scripts/black-box.service ~/.config/systemd/user/black-box.service
$EDITOR ~/.config/systemd/user/black-box.service
systemctl --user daemon-reload
systemctl --user enable --now black-box
```
本地开发的 Docker:
```bash
mvn clean -DskipTests package
docker build -t black-box .
docker run --rm -p 127.0.0.1:8766:8766 -v black-box-data:/data black-box
```
## 配置
默认值位于 `src/main/resources/application.yml`。
| 变量 | 默认值 | 目的 |
| --- | --- | --- |
| `SBA_PORT` | `8766` | HTTP 端口 |
| `SBA_BIND_ADDRESS` | `127.0.0.1` | 绑定地址；网络暴露没有内置身份验证 |
| `SBA_DATASOURCE_URL` | `jdbc:sqlite:sba-agentic.db` | SQLite 数据库位置 |
| `SBA_REDACT_ENABLED` | `true` | 持久化前编辑类似秘密的文本 |
| `SBA_SUMMARY_BACKEND` | `external` | 摘要后端；设置为 `local` 以使用兼容 OpenAI 的本地模型 |
| `SBA_SUMMARY_EXTERNAL_COMMAND` | `scripts/summarize-with-codex.sh` | 外部摘要命令 |
| `SBA_LOCAL_AI_BASE_URL` | `http://localhost:1234` | 兼容 OpenAI 的本地模型 |
| `SBA_ELASTICSEARCH_ENABLED` | `false` | 启用可选的二级搜索索引 |
| `SBA_ELASTICSEARCH_URL` | `http://localhost:9200` | 可选的 Elasticsearch 端点 |
| `SBA_EXPORT_OBSIDIAN_DIR` | 未设置 | 启用内置的 Obsidian 摘要导出目标 |
钩子桥接另外读取 `SBA_AGENTIC_URL`、`SBA_AGENT_SOURCE`、`SBA_RECALL_WITHIN_HOURS`、`SBA_RECALL_LIMIT` 和 `SBA_RECALL_MAX_CHARS`。参见 [本地写入和 Elasticsearch](docs/local-writes-and-elasticsearch.md) 以获取完整的运营参考。
## 可选的捕获和回忆钩子
Black Box 在您选择加入之前不会捕获代理会话。
- `scripts/hooks/sba-agent-hook.sh` 标准化支持的 Claude Code 或 Codex 钩子有效载体，并将它们发布到 `/api/events`。提示、最终响应和工具钩子收到语义 `user`、`assistant` 和 `tool` 角色，以便 Browse 可以重建记录的对话。
- `scripts/hooks/sba-recall-hook.sh` 为 Claude Code 的 `SessionStart` 回忆最近的决策和交接，并打印有界上下文块。
Codex 会话应通过 MCP 在相关工作附近调用 `recallContext`。 `AGENTS.md` 中的简短指令效果很好。
钩子烟雾测试：
```bash
scripts/test-agent-hook.sh
printf '{"hook_event_name":"UserPromptSubmit","session_id":"hook-test","prompt":"hello","cwd":"%s"}' "$PWD" |
SBA_AGENT_SOURCE=manual scripts/hooks/sba-agent-hook.sh`
printf '{"hook_event_name":"UserPromptSubmit","session_id":"hook-test","prompt":"hello","cwd":"%s"}' "$PWD" |
SBA_AGENT_SOURCE=manual scripts/hooks/sba-agent-hook.sh
```
## 终端证明
下面的演示是从真正的隔离决策 → 交接 → 回忆流程生成的。
<!-- 由 ./scripts/record-demo.sh 生成，用于记录 ./scripts/demo.sh。 -->
使用以下命令重新生成：
```bash
SBA_DEMO_PORT=8797 ./scripts/record-demo.sh
```
## 开发
```bash
mvn test
cd frontend && npm test
cd frontend && npm run build
cd frontend && npm run e2e
```
E2E 套件在一个隔离的临时 SQLite 数据库上启动一个打包的 jar，如果路径或所有权标记不安全，则关闭路径或所有权标记。它不会附加到端口 `8766` 或生产数据库。
有关更深入的实现细节：
- [架构](docs/architecture.md)
- [代理任务队列设计](docs/superpowers/specs/2026-06-28-agent-task-queue-design.md)
- [本地写入和 Elasticsearch](docs/local-writes-and-elasticsearch.md)
## 许可
[MIT](LICENSE) © 2026 Nathan Mauro
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器