spine

<p align="center"> <img src="assets/spine-banner.png" alt="Spine — 受控、基于来源的自主交付" width="820"> </p> # Spine **受控、基于来源的自主交付** — 将需求转化为已审查、已测试的拉取请求，人工全程可控。 > **命名。** *Spine* 是产品。它作为 **`synaptixs-spine`** 包分发，其命令为 **`orchestrator`** — 这些名称在整个文档中将保留在安装行和命令中。 Spine 读取需求（来自 Confluence、Notion 或 Markdown 文件），理解目标仓库，生成基于该仓库自身约定（惯例）的代码，编写和运行测试，并为您打开 **拉取请求以供审查**。在开始和合并之前，它会暂停以等待您的批准。在您确认之前，不会向您的跟踪器推送、合并或写入任何内容。 它适用于希望拥有 **可检查、可重现且安全** 的代理的团队，这些代理可以 **在真实代码上运行**，而不仅仅是演示。 ```bash pip install synaptixs-spine orchestrator init && orchestrator doctor # 搭建 .env，检查准备情况 orchestrator sdlc feature --source file://./spec.md --safe # 本地构建 — 无推送，无 PR ``` --- ## 文档 | 指南 | 阅读它来了解 | |---|---| | **[设置与安装](SETUP.md)** | 安装 CLI、.env 和建立完整的栈（Temporal + Postgres）以用于自主管道。 | | **[用户指南](USER_GUIDE.md)** | 分步指南：从您的第一个本地构建到实际的 PR、本地模型、网页仪表盘以及连接工具（MCP）。 | | **[从 Codex 使用 Spine](CODEX_GUIDE.md)** | 从 **Codex 应用** 驱动 Spine — 安装（插件或 MCP 服务器）、凭证、工具参考以及端到端的新建和既有项目演练。 | | **[功能与能力](FEATURES.md)** | 能力目录 — Spine 今日可做的所有事情、其状态、使用的命令/标志以及每个深入研究的链接。 | | **[知识图谱（PKG）](KNOWLEDGE_GRAPH.md)** | Spine 如何理解您的代码库 — 代码原生图谱、其模型、CLI 以及它如何支持既有和新建工作。 | | **[运维与开发者指南](OPERATIONS.md)** | 如何操作：部署模式、完整的环境变量参考以及建立每个高级功能 — 包括语义 spine（ontomesh × infodrift）。 | | **[社区简介](COMMUNITY.md)** | 一页概览 — 它做什么、生命周期覆盖范围、如何尝试以及我们正在寻找的反馈。 | 新来者？**安装 → [用户指南](USER_GUIDE.md) 步骤 1–4.** 这是整个日常工作流程，约十分钟。 --- ## 功能与能力 **需求 → 已审查的 PR。** 将其指向需求来源和代码仓库。它提取意图的积压，编写规格，生成实现和测试，使其通过审查并为您打开拉取请求 — 带有 **两个人工关卡**（在构建之前，在合并之前）。安全模式完全在本地构建（分支 + 差异，无外部写入），以便您可以首先检查所有内容。 **基于代码的理解。** 在生成之前，它会构建您的仓库的 **产品知识图谱** — 模块、类型、函数、调用站点、影响范围 — 并基于已存在的内容生成新代码，因此输出内容读起来像您的团队编写的内容一样。适用于 **Python、Java、TypeScript、C#、C 和 C++**。`orchestrator understand` 编写一个提交的、代码真实的 `memory-bank/`，您的整个团队（和任何 AI 工具）都可以阅读。 **受控的自主性。** 工作流程本身就是一个类型化的、已验证的工件。规划器分解目标，运行时执行它，而 **每边验证器** 检查每一步骤与模式、证据和策略。失败触发重新规划、人工批准或干净的停止。每个工具调用、批准和决策都记录在 **追加审计日志** 中，每个运行都有支出预算。 **跨运行学习。** 跨运行的语义记忆使代理能够回忆惯例、缺陷和过去运行的决策 — 每个记忆都引用它来自的运行。 **您可以查看其内部。** 实时 **OpenTelemetry** 跟踪涵盖每个 LLM 调用、循环步骤和工具调用，与审计日志连接 — 因此您可以调试运行，而不仅仅是读取其结果。 **按您的意愿使用。** **CLI** 用于脚本编写和 CI，**网页仪表盘**（委托运行、实时查看、内联批准门户），**终端 UI**，以及 **MCP** 双向 — 使用外部 MCP 工具，或将整个管道 **作为 MCP 服务器** 暴露给 Claude Code、Codex 或您的 IDE。 **自带模型。** 通过 LiteLLM（Anthropic、OpenAI、Bedrock）支持多供应商，或在本地模型（Ollama）上完全离线运行。按阶段混合模型。 **持久。** 长期运行的管道被检查点（Temporal + Postgres）— 它们在重启后存活，并在人工批准暂停后恢复。 --- ## 工作原理 ``` 需求（Confluence / Notion / Markdown） │ ▼ 计划 ──► 验证 ──► 生成代码 ──► 运行测试 ──► 审查 ──► 打开 PR │ （基于您的仓库的知识图谱） │ └──────────── 每边验证器 + 审计 ────────────────┘ 人工关卡 1 ▲ ▲ 人工关卡 2 （在构建之前） （在合并之前） ``` | 概念 | 它是什么 | |---|---| | **规划器 → GraphIR** | 将目标转化为类型化的、已验证的执行图（节点、边、预算、批准点）。 | | **注册表** | 版本化的代理模板 + 工具合约，规划器从中组装。 | | **运行时** | 基于 LangGraph 的执行器，带有 Postgres 检查点和类型状态。 | | **验证器链** | 每边模式 / 置信度 / 证据 / 策略检查，控制每次交接。 | | **批准门户** | 一流节点，暂停以供人工审查，并在您的决定下恢复。 | | **审计日志** | 追加记录每个工具调用、批准和策略决策。 | --- ## 常见问题 **它会自己合并代码吗？** 否。它打开一个 PR；人工审查和合并。在构建和合并之前有两个批准门户 — 安全模式根本不会进行外部写入。 **我的代码/数据会去哪里？** 到您配置的 LLM 提供商 — 或者如果您运行本地模型（Ollama），则根本不会去任何地方。生成的代码将保留在本地分支中，直到您选择 `--live`。 **我需要 Docker 或数据库吗？** 对于日常路径，不需要（`sdlc feature --safe` 在本地构建一个需求）。自主的多功能管道 + 网页仪表盘需要 Temporal + Postgres — 请参阅 [设置指南](SETUP.md)。 **哪些语言和模型？** 代码生成和理解涵盖 **Python、Java、TypeScript、C#、C 和 C++**（C# 还提取 ASP.NET Core 端点和 EF Core 实体；C 构建 `#include` 图谱并合并头声明及其源定义；C++ 是 C 前端的超集，添加类、命名空间、继承、成员函数和模板，并共享 C 的 CMake/Meson + `ctest` 代码生成）。任何 LiteLLM 支持的提供商（Anthropic、OpenAI、Bedrock）或本地 Ollama 模型；您可以为每个阶段设置不同的模型。 **为什么它可以安全地在真实的仓库上运行？** 生成的代码上的写入保护、允许的 + 写入门控的外部工具、每个运行的支出预算、追加的审计轨迹，以及在推送或合并之前的人工批准。 **CLI 还是网页 UI？** 两者皆可 — 它们驱动同一个引擎和同一个 API。使用 CLI 进行脚本编写/CI，使用网页 UI（或终端 UI）实时查看运行并手动批准门户。 **其他工具可以调用它吗？** 是的。它通过 MCP 双方进行通信：它可以使用外部 MCP 服务器，并且它可以 **作为 MCP 服务器** 运行，以便 Claude Code / Codex / 您的 IDE 可以调用管道（带有相同的门户）。 --- ## 贡献与反馈 我们非常欢迎您的意见。请选择合适的渠道： - 🐛 **错误？** 打开一个 [错误报告](https://github.com/synaptixs/spine/issues/new?template=bug_report.md)。 - 💡 **功能想法/增强？** 打开一个 [功能请求](https://github.com/synaptixs/spine/issues/new?template=feature_request.md)。 - 💬 **问题、反馈或讨论想法？** 开始一个 [讨论](https://github.com/synaptixs/spine/discussions)。 - 🔒 **安全问题？** 请遵循 [SECURITY.md](SECURITY.md) — 不要公开一个问题。 参见 [CONTRIBUTING.md](CONTRIBUTING.md) 和 [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) 以了解贡献如何被审查。 ## 许可证 MIT 许可证。参见 [LICENSE](LICENSE)。