SASP-共享代理状态协议

v0.1.0 - _面向需要学习共享的AI代理的vibe编码MCP服务器_

“太多的程序员，一个代码库”-永恒的斗争，现在人工智能增加了100%

一个MCP（模型上下文协议）服务器，为使用Yjs的编码代理提供编辑感知和意图协调。用共鸣建造，为共鸣，由共鸣。

这是怎么回事？

看，我们明白了。克劳德在这里试图重构 UserService.authenticate()，Claude的堂兄同时将OAuth添加到同一功能中。混乱随之而来。合并冲突从天而降。你的git历史看起来像犯罪现场。

特殊空勤团 是来教这些人工智能代理一些礼仪的。把它看作是你代码中一个真正被动攻击性的“占领”标志，但有更多的CRDT和更少的浴室幽默。

概述

SASP使多个AI编码代理能够通过以下方式实时协调其编辑：

📢 广播意识状态 -“嘿，大家好，我在编辑UserService.authenticate，不要@me”
🎫 声明编辑意图 -把你的瞄准镜像沙滩巾一样放在酒店椅子上
🚨 检测重叠 -“对不起，我在那个功能上叫了dibs”
📝 录制摘要 -为子孙后代记录你的混乱
🎸 保持Git真实 -因为归根结底，Git仍然是真理的源泉

特性

实时感知：代理广播他们当前的活动、文件、选择和理由
意图管理：使用基于TTL的租约保留编辑范围
重叠检测：自动检测冲突编辑（符号>范围优先）
编辑摘要：跟踪发生了什么变化、运行了哪些测试以及结果
MCP集成：完全支持MCP工具、资源和提示
Yjs支持：利用Yjs实现基于CRDT的状态同步

建筑

┌─────────────────────────────────────────────────────────┐
│                    MCP Server (stdio)                    │
├─────────────────────────────────────────────────────────┤
│  Tools:                                                  │
│   - awareness.set_local                                  │
│   - intent.start / update / end                          │
│   - edits.append_summary                                 │
│   - git.commit (stub)                                    │
├─────────────────────────────────────────────────────────┤
│  Resources:                                              │
│   - resources.awareness.doc (snapshot)                   │
├─────────────────────────────────────────────────────────┤
│  Prompts:                                                │
│   - plan-change                                          │
│   - apply-diff                                           │
│   - negotiate-overlap                                    │
├─────────────────────────────────────────────────────────┤
│  Core Components:                                        │
│   - Yjs Document (intents, summaries, awareness)        │
│   - Overlap Detector (symbol > range precedence)        │
│   - TTL Manager (intent expiration)                     │
│   - Auth Validator (bearer token + session)             │
└─────────────────────────────────────────────────────────┘

安装

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Run demo
npm run demo

快速开始

1.启动MCP服务器

# Via npm
npm start

# Or directly with node
node dist/index.js

服务器在stdio上运行，可以与任何兼容MCP的主机集成。

2.配置

设置环境变量以配置服务器：

# Authentication token (required)
export SASP_AUTH_TOKEN="your-secret-token"

# Room ID for Yjs sync (optional)
export SASP_ROOM_ID="my-team-room"

# Log level (optional)
export SASP_LOG_LEVEL="info"  # debug | info | warn | error

3.向MCP主机注册

VS Code

添加到您的VS代码设置中：

{
  "mcp.servers": {
    "sasp": {
      "command": "node",
      "args": ["/path/to/sasp/dist/index.js"],
      "env": {
        "SASP_AUTH_TOKEN": "your-secret-token"
      }
    }
  }
}

克劳德桌面

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "sasp": {
      "command": "node",
      "args": ["/path/to/sasp/dist/index.js"],
      "env": {
        "SASP_AUTH_TOKEN": "your-secret-token"
      }
    }
  }
}

用法

意识管理

设置代理的意识状态以广播您正在做的事情：

// Tool: awareness.set_local
{
  "agent_id": "agent-alpha",
  "session_id": "session-001",
  "token": "your-secret-token",
  "state": {
    "agent_id": "agent-alpha",
    "session_id": "session-001",
    "activity": "editing",  // planning | editing | testing | idle
    "file": "src/UserService.ts",
    "selection": { "symbol": "UserService.authenticate" },
    "rationale": "Adding OAuth support",
    "task_id": "TASK-123"
  }
}

意图管理

开始一个意图

编辑前保留一个范围：

// Tool: intent.start
{
  "agent_id": "agent-alpha",
  "session_id": "session-001",
  "token": "your-secret-token",
  "file": "src/UserService.ts",
  "scope": {
    "symbol": "UserService.authenticate"  // or "range": { startLine: 10, endLine: 20 }
  },
  "reason": "Adding OAuth support",
  "planned_delta_hash": "sha256-abc123",
  "ttl_ms": 300000  // 5 minutes (optional)
}

// Response:
{
  "ok": true,
  "lease_id": "uuid-lease-id"
}

// Or if overlap detected:
{
  "ok": false,
  "error": "Intent overlaps with existing active intent",
  "conflict": {
    "conflicting_lease_id": "other-lease-id",
    "reason": "Symbol 'UserService.authenticate' is already being edited by agent-beta"
  }
}

更新意图

修改范围、原因或扩展TTL：

// Tool: intent.update
{
  "agent_id": "agent-alpha",
  "session_id": "session-001",
  "token": "your-secret-token",
  "lease_id": "uuid-lease-id",
  "fields": {
    "scope": { "symbol": "UserService.authenticateWithOAuth" },
    "reason": "Expanded to include new OAuth method",
    "ttl_ms": 600000  // Extend to 10 minutes
  }
}

结束一个意图

完成后释放范围：

// Tool: intent.end
{
  "agent_id": "agent-alpha",
  "session_id": "session-001",
  "token": "your-secret-token",
  "lease_id": "uuid-lease-id",
  "status": "ended"  // or "expired"
}

编辑摘要

记录您更改的内容：

// Tool: edits.append_summary
{
  "agent_id": "agent-alpha",
  "session_id": "session-001",
  "token": "your-secret-token",
  "file": "src/UserService.ts",
  "summary": {
    "outline": "Added OAuth 2.0 authentication flow",
    "affected_symbols": ["UserService.authenticate", "OAuthProvider"],
    "delta_hash": "sha256-abc123",
    "tests_run": ["test/auth.test.ts"],
    "result": "pass"  // or "fail"
  }
}

获取快照

读取当前状态：

// Resource: resources.awareness.doc
{
  "uri": "sasp://awareness/doc"
}

// Response:
{
  "awareness_states": {
    "12345": {
      "agent_id": "agent-alpha",
      "activity": "editing",
      "file": "src/UserService.ts",
      // ...
    }
  },
  "intents": {
    "lease-uuid": {
      "lease_id": "lease-uuid",
      "agent_id": "agent-alpha",
      "file": "src/UserService.ts",
      "status": "active",
      // ...
    }
  },
  "summaries_index": {
    "src/UserService.ts": [
      {
        "agent_id": "agent-alpha",
        "outline": "Added OAuth support",
        // ...
      }
    ]
  }
}

提示词

SASP包括三个提示来指导代理：

1.计划变更

指导代理商：

订阅意识
读取当前快照
检测重叠
宣布意图或谈判

# List prompts
curl -X POST http://localhost:3000/prompts/list

# Get prompt
curl -X POST http://localhost:3000/prompts/get -d '{"name": "plan-change"}'

2.应用差异

指导代理商通过：

编辑时监控意识
更新对“编辑”的认识
运行测试
录制摘要
结束意图

3.协商重叠

解决冲突的策略：

推迟并等待
重新确定变更范围
通过意识进行协调
分工

重叠规则

SASP执行这些重叠检测规则：

相同符号：总是冲突
符号与范围：符号声明取代范围声明
范围vs范围：如果范围相交（包括相邻线），则会发生冲突
不同的文件：从不冲突
状态：只有“活动”意图块；“已结束”和“已过期”不要

例子

// CONFLICT: Same symbol
Agent A: { symbol: "MyFunction" }
Agent B: { symbol: "MyFunction" }  ❌

// CONFLICT: Symbol supersedes range
Agent A: { range: { startLine: 10, endLine: 20 } }
Agent B: { symbol: "MyFunction" }  ❌ (if MyFunction is in that range)

// CONFLICT: Overlapping ranges
Agent A: { range: { startLine: 10, endLine: 20 } }
Agent B: { range: { startLine: 15, endLine: 25 } }  ❌

// OK: Different symbols
Agent A: { symbol: "FunctionA" }
Agent B: { symbol: "FunctionB" }  ✓

// OK: Non-overlapping ranges (requires at least one-line gap)
Agent A: { range: { startLine: 10, endLine: 20 } }
Agent B: { range: { startLine: 21, endLine: 30 } }  ✓
// Note: Adjacent or touching ranges (e.g., endLine matching another intent's startLine) are considered overlapping.

// OK: Different files
Agent A: { file: "A.ts", symbol: "MyFunction" }
Agent B: { file: "B.ts", symbol: "MyFunction" }  ✓

演示

运行附带的演示，查看两个代理的协调：

# Build first
npm run build

# Run demo
npm run demo

演示显示：

代理A开始意图 UserService.authenticate()
代理B尝试使用相同的符号→ 拒绝（重叠）
代理B通过感知等待
代理A完成并结束意图
代理B成功启动意图
代理B完成编辑

测试

# Run all tests
npm test

# Run specific test suite
npm test unit_overlap
npm test unit_ttl
npm test integ_two_agents

# Watch mode
npm run test:watch

测试包括：

✅ 重叠检测（符号、范围、优先级）
✅ TTL到期和定时器管理
✅ 两个代理协调流程
✅ 宣传意识
✅ 意图更新和验证

项目结构

sasp/
├── server/
│   └── src/
│       ├── index.ts              # MCP server entrypoint
│       ├── config.ts             # Configuration
│       ├── types.ts              # TypeScript types
│       ├── core/
│       │   ├── auth.ts           # Authentication
│       │   ├── overlap.ts        # Overlap detection
│       │   └── ttl.ts            # TTL management
│       ├── yjs/
│       │   └── doc.ts            # Yjs document layer
│       ├── mcp/
│       │   └── tools/
│       │       ├── awareness.ts  # Awareness tools
│       │       ├── intent.ts     # Intent tools
│       │       └── edits.ts      # Edit & git tools
│       ├── resources/
│       │   └── awareness_doc.ts  # Snapshot resource
│       └── prompts/
│           ├── catalog.json
│           ├── plan-change.md
│           ├── apply-diff.md
│           └── negotiate-overlap.md
├── client-demo/
│   └── cli.ts                    # Demo client
├── tests/
│   ├── unit_overlap.test.ts
│   ├── unit_ttl.test.ts
│   └── integ_two_agents.test.ts
├── package.json
├── tsconfig.json
└── README.md

安全

承载令牌：所有工具都需要有效的身份验证令牌
会话验证：必须注册agent_id和session_id
所有权：代理只能更新/结束自己的意图
TTL强制：过期意图自动过期

演出

意识延迟：端到端约50-200ms用于更新
意图验证：重叠检查为O（n），其中n=活动意图
YJS同步：具有可选WebSocket复制的内存中CRDT

振动检查

这是 v0.1.0 -由AI代理构建的氛围编码MVP，适用于AI代理。这是开玩笑的，这是实验性的，而且可能有虫子。但它是有效的，它解决了一个真正的问题：协调多个AI编码代理，而不会把你的代码库变成垃圾箱。

适用于各地的氛围编码人员：这证明，即使你只是在摸索，你也可以发布一些有用的东西。没有花哨的规划，没有企业架构图，只是纯粹的“让我们现在就解决这个问题”的能量。如果你正在使用人工智能代理构建，并需要它们停止踩到对方的脚趾，那就试试吧。

限制（MVP-我们对此很诚实）

git.commit 是一个存根（还没有实际的git集成-我们将其保存为0.2）
没有用于符号索引的LSP集成（您必须知道您的符号名称）
默认情况下未启用WebSocket提供程序（仅限单个实例）
没有持久存储（重启时状态丢失-这都是震动，没有承诺）

路线图

\[\]与commit挂钩的真正git集成
\[\]基于LSP的符号解析
\[\]通过y-websocket进行多服务器同步
\[\]带有Yjs快照的持久存储
\[\]每个分支室隔离
\[\]已签名的意图和审计日志
\[\]GitHub集成（PR评论、检查）

贡献

欢迎Vibe程序员！这个项目是本着“运送它，看看会发生什么”的精神建造的，所以不要害羞：

分叉存储库（或者不分叉，只发送震动）
创建一个功能分支（如果你觉得辣，可以直接在main上工作）
为新功能添加测试（令人惊讶的是，我们确实相信测试）
确保所有测试通过(npm test)
仅提交具有良好氛围的拉取请求

众议院规则：保持真实，保持有趣，记住合并冲突是通过沟通而不是战斗来解决的。

许可证

MIT许可证-有关详细信息，请参阅许可证文件

支持

问题：https://github.com/yourusername/sasp/issues
文档：https://github.com/yourusername/sasp/wiki

致谢

内置 MCP-SDK
状态同步通过 YJS
受到作战转型和CRDT研究的启发

sasp MCP

快速接入

详细介绍