把第一张表，
接进你的工作流。

01 快速上手

需要 Go 1.25 或更高版本。先在项目源码根目录构建 CLI；服务端需另行运行。CLI 本身不连接数据库。

CGO_ENABLED=0 go build -o bin/agent-sheet ./cmd/agent-sheet
./bin/agent-sheet --url https://sheet.sparse-agent.com auth login

打开命令返回的验证地址，用 Chat 登录。核对短码、客户端提供的主机名与目标工作空间，再批准。CLI 会等待并安全保存授权。中断后用 auth finish 继续。

{
  "name": "notes",
  "columns": [
    {"name": "title", "type": "text", "nullable": false},
    {"name": "done", "type": "boolean", "nullable": false}
  ]
}

{"values": {"title": "整理客户需求", "done": false}}

{
  "columns": ["_id", "title", "done"],
  "filters": [{"column": "done", "op": "eq", "value": false}],
  "order_by": [{"column": "title", "direction": "asc"}],
  "limit": 100,
  "offset": 0
}

./bin/agent-sheet --url https://sheet.sparse-agent.com table create --file schema.json
./bin/agent-sheet --url https://sheet.sparse-agent.com row add --table notes --file row.json
./bin/agent-sheet --url https://sheet.sparse-agent.com query --table notes --file query.json

加行成功后会返回稳定 _id。后续更新同一行时使用这个 ID。

02 CLI 命令

以下用 agent-sheet 表示已安装到 PATH 的可执行文件；本地构建时可用 ./bin/agent-sheet。全局参数 --url、--auth-dir 必须放在子命令前。下文所有命令都使用你登录时的同一个服务地址：

agent-sheet --url https://sheet.sparse-agent.com auth finish --wait 10m
agent-sheet --url https://sheet.sparse-agent.com auth status
agent-sheet --url https://sheet.sparse-agent.com table list
agent-sheet --url https://sheet.sparse-agent.com row update --table notes --id ROW_ID --file row.json
agent-sheet --url https://sheet.sparse-agent.com import export.csv --table customers
agent-sheet --url https://sheet.sparse-agent.com import workbook.xlsx --all-sheets --table migration
agent-sheet --url https://sheet.sparse-agent.com auth logout
agent-sheet --help
agent-sheet --skill

将 ROW_ID 替换为服务端返回的 _id，并修改 row.json 中需要更新的值。--file - 可读取 stdin。标准输出为 JSON，错误 JSON 写入 stderr；帮助与手册可离线查看。

设备凭据默认 24 小时到期，到期后重新登录。auth logout 撤销当前设备凭据。授权中断时使用 auth finish，无需反复申请新短码。

03 HTTP API

API 根地址是 https://sheet.sparse-agent.com。表格端点使用设备授权签发的工作空间 Bearer 凭据。凭据应由私有存储注入 Authorization 请求头；不要放在 URL、命令行参数、聊天记录或日志里。

表格 API 错误结构为 {"error":{"code":"…","message":"…"}}。常见状态：400 输入错误、401 凭据失效、403 无权限、404 表或行不存在、409 冲突、429 写队列已满、503 暂不可用。

04 MCP 接入

本地 stdio

先用 CLI 完成设备登录，再让 MCP 客户端启动同一个 CLI。凭据从 CLI 的私密存储读取，不要把 token 放入启动参数。

{
  "mcpServers": {
    "agent-sheet": {
      "command": "/absolute/path/to/agent-sheet",
      "args": ["--url", "https://sheet.sparse-agent.com", "mcp", "--transport", "stdio"]
    }
  }
}

将 command 改为 CLI 的实际绝对路径。若登录时设置了 --auth-dir，在 mcp 之前添加相同参数。具体配置文件位置由你的 MCP 客户端决定。

Streamable HTTP

端点为 https://sheet.sparse-agent.com/mcp。支持自定义 Bearer 凭据的 MCP 客户端可连接；用安全凭据存储注入授权头。当前没有 MCP 专用自动 OAuth 注册流程。

create_table

参数 name、columns。创建一张有明确字段类型的表。

insert_row

参数 table、values。写入一行，返回稳定 ID。

update_row

参数 table、id、values。更新指定行。

query_rows

参数 table、columns、filters、order_by、limit、offset。

import

CSV / XLSX 原子导入。参数 filename，content_base64 或公共 HTTPS url 二选一；支持 table、sheet、all_sheets、header、append、column_mapping。失败整批回滚，默认最多 8 MiB / 10,000 行。

{
  "table": "notes",
  "columns": ["_id", "title", "done"],
  "filters": [{"column": "done", "op": "eq", "value": false}],
  "limit": 100,
  "offset": 0
}

05 字段与查询

表名与字段名：小写字母开头，其后为小写字母、数字或下划线，最多 63 个字符。_id 为系统保留字段。

过滤条件按 AND 组合，支持 eq / ne / gt / gte / lt / lte / is_null / is_not_null。每页默认 100 行，最多 1000 行；用 limit 与 offset 分页。分页期间有写入时，后续页可能变化。

06 权限与安全

一个 Agent 工作空间对应一个租户。一个账号可以拥有多个工作空间，一份设备凭据只授权其中一个。表格请求和 MCP 工具均不接收租户覆盖参数或任意 SQL。

Chat 只提供个人身份登录。Agent 获得的是 Agent Sheet 表格凭据，不包含 Chat API 权限。服务端仅保存凭据哈希；CLI 使用私密文件存储。你可以在工作空间页面撤销自己的设备授权。

网页退出只结束当前 Agent Sheet 网页会话；不会退出 Chat，也不会自动撤销设备凭据。需要停止某台设备访问时，请单独撤销它。

07 常见问题