---

官网：https://statespace.com

文档：https://docs.statespace.com

---

AI并不了解你的数据，但它熟悉Unix和文件系统。Statespace可以帮助你将文件和CLI工具转化为可共享的数据应用，任何智能体都能发现并使用它们。你可以构建数据库浏览器、分享业务规则，或记录遗留API。一旦创建了应用，就可以通过我们的云平台进行部署和监控。

安装

$ curl -fsSL https://statespace.com/install.sh | bash

快速入门

1. 创建应用

在当前目录下运行 statespace init：

$ statespace init

2. 构建应用

将受约束的CLI工具添加到 README.md 或其他Markdown文件中：

---
tools:
  - [grep]
  - [python, scripts/summarize.py]
  - [sqlite3, data/app.db, { regex: "^(SELECT|EXPLAIN)\\b.*" }]
---

# 使用说明
- 只能对数据库执行只读查询
- 使用 `summarize.py` 进行聚合和报告生成
- 使用 `grep` 在本地文件和日志中搜索

或者，让你的编程智能体为你完成构建：

$ claude "请记录我的数据库模式，并添加用于查询的工具"

3. 运行应用

在本地运行你的应用：

$ statespace run --port 8000

现在，智能体和HTTP客户端可以读取页面并执行工具：

# 读取页面
$ curl http://localhost:8000/README.md

# 执行CLI工具
$ curl -X POST http://localhost:8000/README.md \
  -H "Content-Type: application/json" \
  -d '{"command": ["grep", "-r", "revenue", "."]}'

4. 部署应用

将你的应用部署到云端：

$ statespace deploy --name demo

你的应用现在已上线，并可通过公共URL访问：

$ curl https://demo.statespace.app/README.md

5. 分享应用

直接将URL提供给任何智能体：

$ claude "请使用 https://demo.statespace.app 上的API，按地区分解收入"

或者将其配置为MCP服务器：

"mcpServers": {
  "statespace": {
    "command": "npx",
    "args": ["-y", "statespace-mcp", "https://demo.statespace.app"]
  }
}

特性

• 🔌 任意CLI工具 — psql、sqlite3、grep、python — 只要在Shell中运行即可
• 🔒 默认安全 — 通过正则表达式约束，确保智能体只能执行你明确允许的操作
• 🧠 自描述 — Markdown页面既是文档，也是界面
• 📖 可组合 — 内容分散在不同页面上，智能体只需加载所需部分，从而节省资源
• 🚀 可共享 — 可部署到URL、配置为MCP服务器，或与团队成员共享

社区与贡献

• Discord：加入我们的社区服务器，获取实时帮助和讨论
• X：关注我们@statespace_tech，了解最新动态和资讯
• 问题：在GitHub Issues中提交Bug或功能请求

许可证

本项目采用MIT许可证授权。

Statespace 快速上手指南

Statespace 是一个将本地文件和 CLI 工具转换为 AI Agent 可发现、可执行的共享数据应用的平台。它让 AI 通过标准的 Unix 文件系统接口安全地访问你的数据。

环境准备

• 操作系统：支持 Linux、macOS 或 Windows (WSL)。
• 前置依赖：
  • 确保已安装常用的 Shell 工具（如 bash, curl）。
  • 若需使用特定数据库或脚本功能，请预先安装对应工具（如 sqlite3, python, psql 等）。
• 网络要求：需要能够访问 statespace.com 以下载安装脚本和部署应用。

安装步骤

运行以下命令一键安装 Statespace CLI 工具：

curl -fsSL https://statespace.com/install.sh | bash

安装完成后，在终端输入 statespace --version 验证安装是否成功。

基本使用

1. 初始化项目

在项目根目录下运行初始化命令，生成基础配置文件：

statespace init

2. 配置工具与规则

编辑生成的 README.md（或任意 Markdown 文件），在文件顶部的 Frontmatter 区域定义允许 AI 使用的 CLI 工具及安全约束。

示例配置如下：

---
tools:
  - [grep]
  - [python, scripts/summarize.py]
  - [sqlite3, data/app.db, { regex: "^(SELECT|EXPLAIN)\\b.*" }]
---

# Instructions
- Only run read-only queries against the database
- Use `summarize.py` for aggregations and report generation
- Use `grep` to search across local files and logs

说明：上述配置允许 AI 使用 grep 搜索文件，运行指定的 Python 脚本，并仅允许对 SQLite 数据库执行以 SELECT 或 EXPLAIN 开头的只读查询。

3. 本地运行

启动本地服务器，默认端口为 8000：

statespace run --port 8000

此时，AI Agent 或 HTTP 客户端即可通过该端口读取文档或执行受控命令：

# 读取页面内容
curl http://localhost:8000/README.md

# 执行 CLI 工具（例如搜索包含 "revenue" 的内容）
curl -X POST http://localhost:8000/README.md \
  -H "Content-Type: application/json" \
  -d '{"command": ["grep", "-r", "revenue", "."]}'

4. 部署与分享

将应用部署到云端，生成公共访问 URL：

statespace deploy --name demo

部署成功后，你可以直接将生成的 URL（如 https://demo.statespace.app）提供给任何 AI Agent 使用，或将其配置为 MCP 服务器：

"mcpServers": {
  "statespace": {
    "command": "npx",
    "args": ["-y", "statespace-mcp", "https://demo.statespace.app"]
  }
}