Turritopsis

面向长期项目的共享交接层。

1 个人类 + 4 个代理。71 天。50 万行活跃代码。

代理来来去去。项目不应遗忘。

你的编码代理能读取代码。Turritopsis 告诉它：

• 现在什么是真的；

• 项目为何最终变成这样；

• 当前工作停在哪里；

• 哪些已经失败；

• 哪些边界不可打破；

• 以及从哪里继续。

list_stages()
search_stages("why is release frozen?")
get_stage("project.handoff")

Turritopsis 不是私有代理记忆、代码索引、会话延续、项目维基或分块 RAG。它是一个小巧、对 Git 友好的项目知识地址空间，用于存放代码和 Git 无法可靠重建的知识。

一个 MCP，多个代理：经过实战检验的工作流

Turritopsis 源于一个人使用四个不同代理在聊天、编码、本地和 VPS 工作区中运行一个真实的长期系统。它们不共享私有记忆或连续会话。它们通过一个 MCP 共享一个项目地图。

聊天窗口用于思考。 ChatGPT 和 Claude 可以在对话表面进行长上下文头脑风暴、产品决策和困难的设计讨论。它们的上下文和 token 预算花在推理上，而不是反复重建仓库。

编码窗口用于执行。 一个干净的编码代理可以到达，调用 list_stages、search_stages 和 get_stage，并在几秒内接管。它不需要自己的代理记忆系统、重放旧对话或新写的交接文档。干净的窗口保持干净，而不丢失工程进展。

更便宜的模型处理日常维护。 它可以检查最近的差异和陈旧的验证日期，刷新基于证据的知识，并让不确定的事实保持未解决。昂贵的模型保留给值得它们的决策。

人类编辑方向，而不是记账。 Web 界面提供项目地图、Stage 编辑器、实时 Markdown 预览、修订冲突、提案和历史。人类纠正优先级、边界和项目意义，而代理从可追溯的证据维护实现细节。

实际结果是连续性，而不强迫每个代理成为记忆系统。代理可以消失，会话可以结束，新的编码窗口仍然可以找到当前真相并继续工作。

Related MCP server: handoff-mcp

安装和启动

python -m pip install -e .
turritopsis init --yes --name "My Project" --description "What this project does"
turritopsis init --yes --name "My Project" --modules "API, Worker, Web"
turritopsis add anatomy anatomy.components "Current components"
turritopsis serve --stdio

HTTP 使用流式 MCP，默认只监听回环地址：

turritopsis serve                 # 127.0.0.1:3013
turritopsis serve --port 4013
turritopsis serve --data /project/.turritopsis/stages.json

打开 http://127.0.0.1:3013/ 获取人类 Project Map。同一进程提供：

• / — Project Map、搜索、Stage 阅读器/编辑器、交接、Authority、提案和历史；

• /mcp — 四个 MCP 工具；

• /api/... — 本地 UI API，由同一个 Turritopsis、Store、搜索和更新实现支持。

turritopsis ui 是仅需要人类界面时的显式别名。安装后不需要 Node 运行时、前端构建、LLM 或 API 密钥。

远程暴露是显式的（--host 0.0.0.0），应放在认证层后面。

代理入职技能

仓库包含一个兼容 Codex 的技能，位于 skills/turritopsis-onboarding/。将该目录复制到你的 Codex 技能文件夹，然后在代理初始化、加入或恢复项目时调用 $turritopsis-onboarding。该技能教会已安装的代理如何选择通用的 Stage 职责和项目特定的套件，而不是复制一个项目的 Current 名称。

知识模型

一个 Current 路由一个持久的项目问题家族。Current 名称是项目特定的；anatomy、flow、bounds、manual 和 genesis 对某些长期运行的 Agent 系统有用，但不是每个 SDK、数据库、移动客户端、ML 管道或设备的通用默认值。

一个 Stage 是一个完整的、命名的知识区域——不是任意的文本块。Stage Markdown 可以包含英文或中文元数据：

# Current work and handoff

Type: handoff
Purpose: Tell a new contributor where work currently stands.
Search hints: handoff blocker next step release current work
Summary: Release is frozen pending hardware regression.
Verified: 2026-08-24 by agent
Status: current
Authority: current work, next action
Freshness: volatile

## Update triggers

- The blocker or next action changes.

将当前真相、历史解释和确定性生成的事实放在单独的 Stage 中。Status: historical 永远不会静默地呈现为当前权威。生成的 Stage 应说明手动编辑将被覆盖。

四个 MCP 工具

• list_stages(current?) 映射 currents 或紧凑的 Stage 元数据，从不映射正文。

• search_stages(...) 提供可解释的加权路由或精确的行/上下文匹配。

• get_stage(stage_id) 返回一个完整的 Stage 及其正文哈希修订。

• update_stage(...) 支持替换/追加、可选的 expected_revision、actor 日志、滚动备份和冲突响应。

搜索权重保持经过验证的实时路由顺序：Stage id、搜索提示、标题、权威、摘要、目的、状态/验证、Current，然后是标题/正文。semantic 是一个可解释的结构化字段路由器；它不声称嵌入。

所有读取重新加载 stages.json。写入获取文件锁，仅比较目标 Stage 修订，通过临时文件写入并 fsync，原子替换规范文件，追加 changelog.jsonl，并保留滚动备份。

结构和维护

.turritopsis/
├── stages.json
├── config.json
├── scan-evidence.json
├── scan-anomalies.json
├── scan-run.json
├── changelog.jsonl
├── maintenance.jsonl
├── backups/
└── proposals/

普通的 turritopsis init 询问主要模块并创建初始 Current/Stage 地址。--modules 以非交互方式提供相同的答案。

冷启动特意分为本地确定性扫描和已安装代理分类：

turritopsis scan
# The current Codex/Claude Agent reads scan-run.json and scan-evidence.json,
# chooses Stage types and a project suite, then writes skeleton.json.
turritopsis apply-skeleton skeleton.json

turritopsis init --scan 是第一个命令的兼容别名。它读取有界的项目树、README 文件、清单、CI/配置文档和其他非敏感文本材料，然后写入 scan-evidence.json、scan-anomalies.json 和 scan-run.json。它不使用模型、网络、提供商或 API 密钥。重新运行 scan 从保存的证据恢复，除非显式使用 --refresh，因此中断的代理永远不必再次支付扫描成本。

已安装的代理——而不是第二个外部 LLM——分类该证据。apply-skeleton 在原子创建 stages.json 之前验证模式、来源、Current 和 Stage id、证据路径、Stage 类型/新鲜度、空职责、重复 Authority、垃圾抽屉和碎片化。它从不覆盖现有的知识库；后续写入必须使用修订保护的 update_stage。规范知识仍然以显式占位符开始，必须从验证的证据填充。

可选的 LLM 支持的维护使用 .turritopsis/config.json；扫描和骨架应用从不读取它：

{
  "llm": {
    "provider": "openai",
    "model": "gpt-4.1-mini",
    "api_key_env": "OPENAI_API_KEY"
  }
}

支持的提供商是 openai、anthropic 和 openai-compatible。兼容提供商需要 base_url。设置可以用 TURRITOPSIS_LLM_PROVIDER、TURRITOPSIS_LLM_MODEL、TURRITOPSIS_LLM_API_KEY_ENV、TURRITOPSIS_LLM_BASE_URL、TURRITOPSIS_LLM_TIMEOUT 和 TURRITOPSIS_LLM_MAX_TOKENS 覆盖。API 密钥值仅从配置的环境变量读取，从不写入项目文件。

turritopsis maintain 检查最近的 Git 更改、缺失的引用路径和验证年龄。对于每个受影响的策展 Stage，它将当前正文和有界的项目证据发送到配置的 LLM，验证返回的 JSON 和引用的证据 id，更新 Verified，然后通过正常的 Stage 修订、锁、备份、原子替换和变更日志路径写入。如果证据不足，模型必须返回 no_change。

turritopsis maintain
turritopsis maintain --model CHEAP_MODEL
turritopsis maintain --proposal-only
turritopsis maintain --schedule "0 3 * * *" --model CHEAP_MODEL
turritopsis maintain --show-schedule
turritopsis maintain --unschedule
turritopsis survey
turritopsis anomalies
turritopsis brief
turritopsis export --format md
turritopsis export --format json --output project-knowledge.json

--proposal-only 在需要时保留审查优先的漂移报告；--apply 仍然应用显式审查的提案。它们是可选工作流，不是对正常证据支持维护的限制。

--schedule 在当前 POSIX 用户的 crontab 中安装或替换一个路径范围的条目。上面的示例每天在 cron 主机的本地时区 03:00 运行，将输出写入 .turritopsis/maintenance-cron.log，并且重复时是幂等的。它从不将 API 密钥写入 crontab：config.json 中命名的 api_key_env 必须已经可用于 cron 环境。--show-schedule 和 --unschedule 仅检查或删除此项目的 Turritopsis 标记块。在没有 crontab 的主机上，从 CI 或本机调度器调用相同的 turritopsis maintain --model CHEAP_MODEL 命令。

唯一的自动写入例外是显式生成的 Stage，带有确定性生成器配置：

{
  "id": "anatomy.revision",
  "title": "Current Git revision",
  "status": "generated",
  "generator": {"type": "git_revision"},
  "body": ""
}

内置确定性类型是 git_revision、file_hash 和 path_exists。它们的输出明显标记为自动生成，不使用 LLM。

核心列表/搜索/获取/更新、Web UI、MCP 服务、扫描和骨架应用不需要 LLM 和 API 密钥。只有可选的自动策展维护需要。

许可证

Turritopsis 是根据标准 MIT 许可证 发布的开源软件。商业使用、修改、分发、再许可和私人使用均允许，但须遵守许可证通知要求。

开发

python -m pip install -e ".[test]"
pytest