Lockstep Core

锁步链协议

基于链的项目跟踪，用于人类+人工智能协作。MCP服务器为您的AI编码助手提供跨会话的持久内存——链将工作链接在一起，票跟踪需要做什么，切换保留上下文，这样对话之间就不会丢失任何东西。

这是给谁的？

任何使用人工智能编码助手（Claude等）的人都厌倦了每次会话都重新解释上下文。Lockstep在以下情况下特别有用：

• 在连续性很重要的多届项目上开展工作
• 想要结构化的会话类型（发现、规划、构建、审查），而不需要严格的执行
• 神经分化，并受益于执行功能的外部支架
• 希望您的人工智能合作伙伴能够随着时间的推移跟踪增长和容量

特性

• 37个工具+5个命令 用于完整的项目生命周期管理
• 基于链的跟踪 --会话作为一个工作链连接在一起
• YAML定义的链类型 --完整的漏斗、增强、重构、开箱即用的bug修复，或创建自己的
• 渐进式披露 --早期阶段显示减少认知负荷的领域较少；信息在变得相关时浮出水面
• 门票促销 --独立门票在增长时可以推广成连锁店；自动发现相关票证
• 会话类型 --发现、研究、规划、架构、构建、审查
• 结构化交接 --决策、文件更改、打开的线程和下一个会话建议在对话之间传输
• 容量跟踪 --成长阶段（训练轮→ 合伙→ 安全网）与事件记录
• 咨询，而非强制执行 --协议标记并解释，从不阻止
• 完全本地化 --所有数据都以YAML文件的形式存储在您的计算机上，没有网络访问权限
• 跨平台 --在macOS、Windows 11和Linux（x64和ARM）上进行了测试
• 人类可读数据 --直接检查、编辑或版本控制项目数据

安装

来自《人物目录》（克劳德桌面版）

1. 在Anthropic目录中查找“Lockstep Core”
2. 单击安装
3. 出现提示时，选择一个数据目录（默认： ~/.lockstep/data)

MCPB捆绑包（手动）

1. 下载 lockstep-core.mcpb 从 最新版本
2. 使用Claude Desktop打开它（双击或拖动）
3. 出现提示时，选择一个数据目录（默认： ~/.lockstep/data)

手动设置

需要 紫外线 Python 3.11+。适用于macOS、Windows和Linux。

git clone https://github.com/dandelionrosegroup/lockstep-core.git
cd lockstep-core

添加到您的Claude Desktop配置中：

macOS/Linux：

{
  "mcpServers": {
    "lockstep": {
      "command": "uv",
      "args": ["run", "--python", "3.11", "--with", "mcp>=1.0.0", "--with", "pydantic>=2.0.0", "--with", "PyYAML>=6.0", "src/server.py"],
      "cwd": "/path/to/lockstep-core",
      "env": {
        "LOCKSTEP_DATA_DIR": "/path/to/your/data",
        "PATH": "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/homebrew/bin:~/.local/bin"
      }
    }
  }
}

重要提示： Claude Desktop是一个GUI应用程序，不继承shell的PATH。这 PATH 上面的条目确保 uv （通常安装在 ~/.local/bin/uv)是可发现的。如果你通过Homebrew安装了uv， /opt/homebrew/bin 覆盖了这条路。

窗户：

{
  "mcpServers": {
    "lockstep": {
      "command": "uv",
      "args": ["run", "--python", "3.11", "--with", "mcp>=1.0.0", "--with", "pydantic>=2.0.0", "--with", "PyYAML>=6.0", "src/server.py"],
      "cwd": "C:\\Users\\you\\Projects\\lockstep-core",
      "env": {
        "LOCKSTEP_DATA_DIR": "C:\\Users\\you\\.lockstep\\data"
      }
    }
  }
}

注： 在Windows上，使用双反斜杠(\\)或正斜杠(/)JSON路径中。

故障排除

“uv：找不到命令”或服务器无法启动： Claude Desktop不继承终端的PATH。确保 uv 可以找到：

• macOS/Linux： 添加 PATH env-var，如上面的配置示例所示，或者使用uv的完整路径（例如。， "command": "/Users/you/.local/bin/uv")
• 窗户： uv安装程序通常会将自己添加到系统PATH中。如果不是。， "command": "C:\\Users\\you\\.local\\bin\\uv.exe")

服务器启动但立即断开连接：

• 验证Python 3.11+是否可用： uv python list （如果需要，uv将自动下载，这要归功于 --python 3.11 旗帜）
• 检查Claude Desktop的MCP日志： ~/Library/Logs/Claude/mcp*.log （macOS）或 %APPDATA%\Claude\logs\ （Windows）

配置

Lockstep需要一个设置：a 数据目录 它存储链、票和容量数据。

• 违约： ~/.lockstep/data
• 自定义： 集 LOCKSTEP_DATA_DIR MCPB安装期间的环境变量或配置
• Lockstep自动创建子目录(chains/, tickets/, capacity/, declarations/, handoffs/, catches/, archive/)

使用示例

启动一项新举措

在一个命令中创建票证、链和第一个会话。

用户提示：

“创建一个名为‘构建用户身份验证’的新计划，其愿景是‘用户可以注册、登录和管理他们的帐户’。”

工具调用： cmd_new_initiative

{
  "title": "Build user authentication",
  "vision": "Users can sign up, log in, and manage their accounts."
}

答复：

{
  "ticket_id": "TICKET-001",
  "chain_id": "build-user-authentication",
  "chain_type": "full-funnel",
  "first_session": "discovery",
  "link_number": 1,
  "message": "Initiative created. Discovery session is active. Record your session declaration."
}

将门票推广到连锁店

当独立工单的范围扩大时，将其升级为自动发现相关工作的链式跟踪。

用户提示：

“将TICKET-005推广到链中。完成愿景是‘OAuth完全集成和测试’。”

工具调用： promote_ticket

{
  "ticket_id": "TICKET-005",
  "completion_vision": "OAuth fully integrated and tested"
}

答复：

{
  "promoted": true,
  "ticket_id": "TICKET-005",
  "chain_id": "add-oauth-support",
  "chain_type": "enhancement",
  "first_session": "planning",
  "nesting_candidates": [
    {
      "ticket_id": "TICKET-008",
      "title": "Review Auth Flows",
      "shared_tags": ["auth"]
    }
  ],
  "candidate_message": "Found 1 related ticket(s) that could be nested.",
  "message": "Ticket promoted to chain 'add-oauth-support'. Planning session is active."
}

记录切换

捕获会话上下文，以便下一次对话可以无缝衔接。

用户提示：

“记录一次切换——我们决定使用JWT令牌和bcrypt作为密码。文件已更改：auth.py（已创建），models.py（已修改）。下一个会话应该是规划。”

工具调用： record_handoff

{
  "chain_id": "build-user-authentication",
  "session_type": "discovery",
  "status": "complete",
  "decisions_made": ["JWT tokens for auth", "bcrypt for password hashing"],
  "files_changed": [
    {"path": "auth.py", "action": "created"},
    {"path": "models.py", "action": "modified"}
  ],
  "recommended_next_type": "planning",
  "quick_start": "Define API routes, data models, and auth middleware based on JWT+bcrypt decisions."
}

工具参考

链生命周期（15个工具）

票证生命周期（7个工具）

容量跟踪（5个工具）

查询工具（6个工具）

会话支持（4个工具）

命令（5个快捷键）

创建自定义链类型

链类型定义为YAML文件 templates/。删除一个新文件以创建新的链类型——不需要更改代码。

模板格式

# templates/your-type.yaml
chain_type: your-type
display_name: Your Type
phases: [planning, build, review]
autonomous_eligible: false
required_fields:
  - completion_vision
optional_fields:
  - capacity_role
  - parent_chain
progressive_disclosure:
  planning:
    show: [completion_vision, entity, tags]
    prompt: "What are we building and why?"
  build:
    show: [all]
    prompt: null
  review:
    show: [all]
    prompt: "Does this meet the completion vision?"

领域

渐进式披露

每个阶段都可以定义：

• show：此阶段可见的链字段列表。使用 [all] 展示一切。
• prompt：在此阶段，向AI合作伙伴提供了可选的指导文本。

可用字段 show: completion_vision, entity, tags, capacity_role, parent_chain, child_chains, child_tickets, spawn_reason, expected_sequence, gate_skips, all.

核心结构领域(chain_id, title, status, links等等）总是可见的而不管披露规则如何。

内置链类型

从v0.1.0迁移

如果您有现有的v0.1.0数据，请运行迁移脚本：

python scripts/migrate_v1_to_v2.py ~/.lockstep/data

这将创建备份，重命名 template 到 chain_type，并对模式版本进行升级。服务器还会自动迁移读取时遇到的任何v1文件，因此迁移是可选的，但建议用于干净的数据。

设计原则

1. 咨询，而非强制执行。 协议会标记并解释——它从不阻塞。如果你想直接从发现跳转到构建，它会记录跳转并继续。
2. 让潜意识有意识。 会话切换、捕获事件和容量跟踪会随着时间的推移阐明模式，而不会强制改变行为。
3. 支架成长，尊重自主。 成长阶段（训练轮→ 合伙→ 安全网）使阻力最小的道路成为富有成效的道路，但它们从来不是唯一的道路。
4. 协议服务于伙伴关系。 如果结构抵抗工作，结构就会弯曲。

数据存储

所有数据都以YAML文件的形式存储在您配置的数据目录中：

~/.lockstep/data/
├── chains/          # CHAIN-[kebab-title].yaml
├── tickets/         # TICKET-[number].yaml
├── capacity/        # [role-name].yaml
├── declarations/    # Session declaration records
├── handoffs/        # Session handoff records
├── catches/         # Catch event records
└── archive/         # Completed chains and tickets
    ├── chains/
    └── tickets/

YAML文件是人类可读和版本可控的。不需要数据库。

隐私政策

Lockstep是一个完全本地的MCP服务器。它不收集数据，不发出网络请求，也不包括遥测。您的项目数据保留在您的计算机上。

完整政策： 隐私.md

支持

• 问题：
• 讨论：

贡献

Lockstep是GPL v3许可的。欢迎捐款。在macOS、Windows 11和Linux上进行了测试。

# Set up development environment
git clone https://github.com/dandelionrosegroup/lockstep-core.git
cd lockstep-core

# Run tests (uv handles dependencies automatically)
uv run --python 3.11 --with mcp --with pydantic --with PyYAML python tests/test_integration.py
uv run --python 3.11 --with mcp --with pydantic --with PyYAML python tests/test_phase2_promotion.py
uv run --python 3.11 --with mcp --with pydantic --with PyYAML python tests/test_phase3_disclosure.py

# Or run all tests with pytest (requires pytest + pytest-asyncio)
uv run --python 3.11 --with mcp --with pydantic --with PyYAML --with pytest --with pytest-asyncio \
  python -m pytest tests/ -v

检查 问题 好地方开始。

许可证

GNU通用公共许可证v3.0 --版权所有（C）2025-2026杰克·丹尼尔·威廉姆斯/蒲公英玫瑰集团有限责任公司

作为…的一部分建造 蒲公英玫瑰集团的使命是证明神经发散思维与人工智能合作是独一无二的。