Huly Vibe Sync

Vibesync服务

项目注册、Beads发布工作流程指导以及Oculair项目工作区的PM代理协调服务。

当前范围

• 用于发现和管理工作区项目的项目注册表API。
• 适用于轻量级移动客户端的Android友好项目摘要端点。
• 由存储库状态数据库支持的通用工作项API曲面。
• 珠子(bd)作为本地问题跟踪的真相来源。
• Letta PM代理元数据和报告集成。
• 带有健康检查和可选Temporal workers的Docker化运行时。

快速开始

使用Bun的主机运行时：

cd /opt/stacks/vibesync
bun install --frozen-lockfile
bun run type-check:all
bun run start

构建一个主机可运行的二进制文件：

bun run build:binary
./dist/vibesync

二进制文件捆绑了Bun服务入口点。shell的运行时集成 out-to-host工具、Python助手、Beads、Dolt、Git或挂载的工作区路径 仍然需要主机上可用的工具/文件。

Docker仍然适用于当前的部署拓扑：

cd /opt/stacks/vibesync
cp .env.example .env
docker-compose up -d
docker-compose logs -f

对于需要DoltHub配置令牌的生产重启，请使用 Vaultwarder支持编写包装，而不是将令牌存储在 .env:

./scripts/vibesync-compose-vaultwarden.sh pull vibesync
./scripts/vibesync-compose-vaultwarden.sh up -d vibesync

包装器读取 DoltHub API Token 运行时来自Vaultwarden的项目 出口 DOLTHUB_API_TOKEN 只是为了这个 docker compose 调用。

配置

看 .env.example 对于支持的设置。核心设置包括：

VIBE_MCP_URL=http://192.168.50.90:9717/mcp
SYNC_INTERVAL=10000
PARALLEL_SYNC=true
MAX_WORKERS=5
DRY_RUN=false

API项目注册处

列出项目

GET /api/projects

返回适用于移动优先绘制的轻量级项目摘要，包括仓库元数据、PM代理元数据、跟踪器功能、活动时间戳和版本/etag字段。

项目详情

GET /api/projects/:id

返回一个紧凑的项目详细信息摘要。大型集合通过单独的分页子资源公开。 如果跟踪器/工作项水合失败，项目详细信息仍会返回 200 仅使用正常的项目字段和标记 project.tracker.data_freshness.status 作为 "error"。新鲜度元数据中的错误消息经过净化后用于UI显示，并且永远不会暴露原始堆栈跟踪或低级异常文本。

项目子资源

• GET /api/projects/:id/agents
• GET /api/projects/:id/conversations
• GET /api/projects/:id/work-items
• GET /api/projects/:id/activity
• GET /api/projects/:id/issues
• GET /api/projects/:id/ready-work

子资源使用光标样式的分页信封 page.next_cursor, page.has_more，以及 page.total_known. 如果子资源无法水合，端点通常会返回项目范围的信封，其中该子资源的集合为空，并且 data_freshness.status = "error" data_freshness.error value是一个经过净化的、用户安全的摘要。

项目 etag 仅当项目摘要/详细信息字段更改时，值才会更改。跟踪器的新鲜度和子资源的可用性不会改变项目 etag；每个子资源响应都公开自己的 etag 和 data_freshness.last_sync_at 用于缓存无效和过时/错误UI状态。

Android问题/工作合同

GET /api/projects/:id/ready-work Android相当于 bd ready：它返回开放、可操作、畅通无阻的工作，而不需要客户端从原始问题列表中重建准备状态。

GET /api/projects/:id/issues 返回紧凑的分页问题摘要。它支持Android友好的过滤器，包括 status, priority, assignee, type, ready=true|false，文本查询通过 q，并通过以下方式进行增量刷新 updatedSince / updated_since.排序目前支持 priority, updated，以及 created.

GET /api/issues/:id 通过稳定的不透明问题ID返回完整的问题详细信息，包括描述、接受标准、标签、规范化状态、阻断器引用、子引用、时间戳和验证警告。

突变终点是一流的，并且具有冲突意识。发送 If-Match 标题或 if_match 身体领域与问题 etag；陈旧突变复发 409 具有结构化 conflict 对象。发送 Idempotency-Key 或 idempotency_key 用于离线安全重试。

• POST /api/issues/:id/claim
• POST /api/issues/:id/unclaim
• PATCH /api/issues/:id/status
• POST /api/issues/:id/notes
• POST /api/issues/:id/close
• POST /api/issues/:id/reopen

突变请求示例：

POST /api/issues/letta-mobile-qmbg/claim
If-Match: letta-mobile-qmbg:1778416496000
Idempotency-Key: android-queue-42
Content-Type: application/json

{
  "assignee": "emmanuel"
}

冲突响应：

{
  "error": "Issue conflict",
  "statusCode": 409,
  "conflict": {
    "reason": "etag_mismatch",
    "expected": "letta-mobile-qmbg:stale",
    "current": "letta-mobile-qmbg:1778416496000",
    "issueId": "letta-mobile-qmbg"
  }
}

问题有效载荷是确定性的，并且模式版本化：

{
  "id": "letta-mobile-qmbg",
  "projectId": "letta-mobile",
  "provider": "beads",
  "title": "Define Android Beads data contract for project workspaces",
  "type": "task",
  "priority": "high",
  "status": "open",
  "statusLabel": "todo",
  "ready": true,
  "assignee": null,
  "blockedBy": [],
  "blocks": [],
  "isBlocked": false,
  "updatedAt": "2026-05-10T12:34:56.000Z",
  "summary": "Short list-safe summary",
  "acceptanceCriteria": ["Criterion one"],
  "labels": ["android", "project-workspace"],
  "validationWarnings": [],
  "etag": "letta-mobile-qmbg:1778416496000"
}

标准化的机器可读状态是 open, in_progress, blocked, deferred，以及 closed；原始跟踪器状态仍然可用 statusLabel 用于显示/调试。

注册项目

POST /api/registry/projects

{
  "filesystem_path": "/opt/stacks/letta-mobile",
  "name": "Letta Mobile",
  "git_url": "https://github.com/oculairmedia/letta-mobile.git"
}

• filesystem_path 是必需的，并且必须是绝对路径。
• name 和 git_url 是可选的。
• 路径必须存在并且是git存储库。

更新项目

PATCH /api/registry/projects/:id

{
  "filesystem_path": "/opt/stacks/letta-mobile",
  "git_url": "https://github.com/oculairmedia/letta-mobile.git"
}

Beads/DoltHub远程配置

POST /api/projects/:id/beads-remote/provision

默认情况下，创建或重用项目范围的DoltHub数据库，配置项目的Beads远程，并推送本地Beads数据库。数据库名称根据项目文件夹名称进行规范化，例如 /opt/stacks/letta-mobile 成为DoltHub遥控器 https://doltremoteapi.dolthub.com/oulair/letta_mobile.

{
  "push": true
}

配置是幂等的：已存在的DoltHub数据库被视为成功，现有的本地或不匹配的Beads远程将被配置的DoltHub远程替换。使用 GET /api/projects/:id/beads-remote 以检查存储的配置元数据。

DoltHub API令牌仅用于创建专用数据库。常规 bd dolt push/pull 操作使用服务器的 dolt login 凭据来自 ~/.dolt/creds，因此请单独提供这些凭据。

CLI帮助程序：

npm run vibesync -- project-beads-remote HVSYN
npm run vibesync -- project-provision-beads-remote HVSYN
npm run vibesync -- project-provision-beads-remote HVSYN --no-push

珠子工作流程

在此存储库中使用Beads进行问题跟踪：

bd ready
bd show 
bd update  --claim
bd close 

不要通过外部问题工具路由项目问题操作。