内容
# gcontext
gcontext 存储 AI 代理的状态（指令、服务连接、机密、知识、正在进行的工作），并通过本地 HTTP 服务器上的 MCP 提供服务。MCP 客户端，如 Claude Code、Codex、Cursor 或 Claude Desktop，连接到该服务器并针对共享状态工作。
重点：运行时在会话之间会忘记所有内容。如果状态存储在文件夹中，则它将持续存在，您可以使用 git 对其进行版本控制，并且可以在不丢失任何内容的情况下切换运行时。gcontext 仅管理该状态。它没有聊天循环，没有 LLM 客户端，也没有编排；您附加的运行时会执行实际工作。
## 安装
```bash
uv tool install gcontext-ai
```
## 快速入门
```bash
gcontext init my-agent # 创建状态文件夹
gcontext up my-agent # 在 http://127.0.0.1:4242/mcp 上提供服务
```
然后连接客户端（一次，从任意目录）：
```bash
claude mcp add --transport http my-agent http://127.0.0.1:4242/mcp
```
`gcontext connect claude|desktop|codex|cursor` 打印每个客户端的确切步骤。服务器在客户端连接时记录每个客户端。停止服务器（Ctrl+C）会断开所有连接；无需其他清理。
## 文件夹
```
my-agent/
gcontext.yaml # 名称、描述、端口（可选）
instructions.md # 附加的运行时的持久指令
secrets.env # 机密值，被 gitignore
connections/ # 代理可使用的服务
stripe/
connection.yaml # 机密名称 + Python 依赖项
index.md # API 说明，用例模式
modules/ # 累积的知识
flows/ # 多步骤工作，作为文件跟踪（见下文）
archive/ # 排除扫描，但仍然可读
```
Markdown 保留上下文，YAML 保留配置。使用文本编辑器编辑任意文件；服务器按需读取文件，因此更改立即生效。
连接的客户端获得六种工具：`overview`、`read_context`、`write_context`、`run_script`、`list_connections`、`flows`。
## 上下文账本
`gcontext context` 列出上下文到达代理的每个通道，标记为 `loaded`（启动时推送）、`on demand`（代理通过可见的工具调用拉取）、`skipped`（由启动标志关闭）或 `uncontrolled`（运行时拥有，超出 gcontext 的视图）。gcontext 仅通过该列表上的通道插入上下文。如果您想知道代理看到的内容，这就是答案。
## 机密
`connection.yaml` 声明机密名称；`secrets.env` 保留值。当代理调用 `run_script` 时，值作为环境变量注入，并从脚本输出中清除。代理可以知道 `STRIPE_API_KEY` 存在并在脚本中使用，但绝不会读取值。`secrets.env` 被 `init` 和 `write_context` 工具 gitignore。
`run_script` 在每个项目的虚拟环境中执行 Python，并为每个连接的声明依赖项预安装（通过 uv）。
## 工作流
工作流是描述多步骤工作的 YAML 文件，作为文件依赖项：
```yaml
steps:
- id: draft
needs: [flows/brief/brief.md]
produces: [flows/brief/draft.md]
instructions: 阅读简介，撰写草稿。
```
步骤状态源自文件系统，如 make 目标：
- `blocked`：所需文件不存在
- `ready`：需求存在，产品不存在
- `stale`：所需文件在生成的文件后被修改
- `done`：所有文件存在且是最新的
没有引擎和存储的运行状态。通过编写声明的文件完成一个步骤，无论是由附加的运行时、脚本还是编辑器完成。如果上游文件更改，下游步骤在下一次读取时变得过时。`gcontext flows` 打印工作流板；连接的客户端通过 `flows()` 工具获取相同的信息，该工具仅为当前可操作步骤包含步骤指令。
## 存档
当旧模块或连接开始混乱上下文时，请移动它们：
```bash
mv my-agent/modules/old-onboarding my-agent/archive/modules/
```
`archive/` 下的任何内容在扫描时都被跳过，但通过路径仍然可读，摘要提及已存档的内容，以免它们无声无息地消失。gcontext 永远不会自行移动、存档或删除任何内容。
## 命令
| 命令 | 描述 |
|---|---|
| `gcontext init <dir>` | 搭建新的状态文件夹 |
| `gcontext up [dir]` | 通过 MCP 提供文件夹服务 |
| `gcontext status [dir]` | 服务器状态、连接的客户端、状态概览 |
| `gcontext connect [client]` | 连接 claude、desktop、codex、cursor 的步骤 |
| `gcontext context [dir]` | 打印上下文账本 |
| `gcontext flows [dir]` | 打印工作流板 |
| `gcontext chat [dir]` | 启动针对文件夹的专用 claude 会话 |
## 范围
仅限本地使用。服务器绑定 `127.0.0.1` 且无身份验证，因此无法从您的机器外部访问，并且应该保持这样。远程变体（相同的模型、URL 加令牌）正在计划中，但不是此版本的组成部分。
## 许可证
MIT
MCP 市场