Insitu

面向智能体的情境化身份。你在这里是谁。

Insitu 存储可复用的 段落（即常驻指导的章节），并将它们组合成你当前所在项目的协议。materialize 将该协议写入宿主在会话启动时已经注入的文件中。你通过 list_stanzas 和大小摘要进行编写。智能体使用 resolve_protocol 来检查并拉取 available 段落。

它不模拟仓库、组件或系统事实。那是开发上下文工具（参考配置中的 ContextForge）的职责。两者旨在并行运行。

状态

设计锁定于 2026-08-17（DESIGN.md v0.5）。读取路径、角色（§6.1）、validate / where_used 和 materialize 已实现。变更工具要等到首次内部试用之后。当前下一步：STATUS.md。

安装

需要 Python 3.11+ 和 uv。

cd insitu
uv sync
uv run pytest
uv run insitu

uv run insitu 在 stdio 上启动 MCP 服务器。

保险库根目录

每个进程一个保险库，顺序如下：

1. INSITU_HOME

2. --vault /path/to/vault

3. ~/.insitu

一个新的保险库只是磁盘上的文件夹（stanzas/、projects/、可选的 config/surfaces.yaml）。本仓库中的 examples/vault/ 是一个虚构的示例，你可以指向它：

uv run insitu --vault examples/vault

不要将个人保险库复制到本公共仓库中。

将 MCP 服务器添加到宿主

有关 Cursor、Claude Code 和 Grok 的片段，请参阅 install/mcp.json.examples.md。典型形式如下：

{
  "mcpServers": {
    "insitu": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/insitu", "insitu"],
      "env": { "INSITU_HOME": "/path/to/your/vault" }
    }
  }
}

复制三个路由器（一次性，用户全局）

路由器告诉宿主 Insitu 的存在。它们不是项目协议。

可选：将 install/AGENTS.md 手动粘贴到宪法文件中。materialize 从不写入 AGENTS.md、CLAUDE.md 或 CLAUDE.local.md。

使用 config/surfaces.yaml（grok、claude、cursor）在保险库中启用宿主适配器。然后在项目检出目录中调用 materialize。它将写入 PROTOCOL.md 以及 .grok/rules/、.claude/rules/ 和 .cursor/rules/ 下的适配器文件。

预期用途

# you, after a vault or map change
materialize               # PROTOCOL.md + host adapters (.grok/.claude/.cursor rules)

# agent, live / on demand
resolve_protocol          # inspect weight, refresh, compare to the materialized header
get_stanza ...            # pull an available stanza

# you, registering a new project
list_stanzas              # what exists, and how heavy each piece is
link_stanza ...           # after the write path exists
get_project               # how heavy is this project's protocol?

开发

uv sync
uv run pytest
uv run insitu

Python 3.11+，FastMCP。如果你是正在本仓库工作的智能体，请参阅 AGENTS.md。

许可证

MIT。参见 LICENSE。