在终端里跑 Claude 操作表格

星汉AI表格内置了一个普通的 PTY 终端面板（右侧栏的 Terminal 图标），它就是一个 zsh / pwsh 终端，能跑 ls / git / mongosh，也能跑 claude、codex 这类 AI CLI。

配合官方提供的 MCP server（xhe-mcp-stdio），Claude 能列项目、读表、查行、改单元格、加字段、建表。本页讲一遍端到端怎么配。

你能让 Claude 干什么

举几个真实可用的 prompt：

“列出这个项目里所有的表” → list_tables
“客户表里状态=流失的客户有几个？把价值大于 10k 的列出来” → describe_table + query_rows
“把所有跟进时间在 30 天前的客户的状态改成流失” → query_rows + 多次 update_cell，会先报告匹配数量再确认
“给客户表加一列 “下次联系日期”，日期类型” → add_field
“基于客户表的列结构，帮我新建一张表叫 “线索”，字段类似但加上来源、评分” → add_table
“把 CSV 文件 ~/Downloads/leads.csv 里的 50 行导进线索表” → claude 用本地 bash 解析 CSV，循环调 add_row

跨工具组合也行 —— 让 Claude 一边读数据、一边写文件、一边问你确认、一边改表。

准备：一次性配置

编译 MCP server 二进制
Terminal window
```
cd /path/to/xinghan-editor/client/go
go build -o ~/bin/xhe-mcp-stdio ./cmd/mcp-stdio
```
产物是一个 stdio 协议的 MCP server，启动时连本机 sqlite / mongo 引擎（跟编辑器主进程同一份配置）。
告诉 Claude 这个 MCP server

推荐用 claude mcp add（官方文档）：
Terminal window
```
claude mcp add xinghan ~/bin/xhe-mcp-stdio
```
或手动编辑 ~/.claude.json，找到 mcpServers，加：
```
{
  "mcpServers": {
    "xinghan": {
      "command": "/Users/<you>/bin/xhe-mcp-stdio",
      "args": [],
      "env": {}
    }
  }
}
```
MCP server 会读跟编辑器主进程相同的 sqlite / mongo 配置（~/xinghan/ 下）。所以打开任意 .xhdb 项目之前先在编辑器里至少打开过一次，让数据目录被初始化。
重启 claude CLI session

如果 claude 已经开着，需要 /exit 退出再重进，让它重新加载 mcp 列表。

在编辑器里用起来

打开编辑器，加载你要操作的 .xhdb 项目

这一步让数据引擎认识当前项目。
点右侧栏 Terminal 图标

右侧抽屉会出来一个终端面板，已经在 $HOME 下开了一个 zsh session。Tab 栏可以 + 新建多个 session，× 关闭，切来切去状态保留。
运行 claude
Terminal window
```
claude
```
第一次跑会提示登录（官方说明）。
验证 MCP 连上了

在 claude 里输入：
```
/mcp
```
应该看到 xinghan server 状态为 connected，并列出 list_projects、list_tables 等 9 个 tool。
开干

先让它列项目拿到 projectId（MCP tools 都需要这个参数）：
```
> list my xinghan projects
```
然后正常对话即可：
```
> 在项目 prj_abc123 里，把 客户 表里所有 阶段=流失 的行的 价值 字段清零
```
写操作（update_cell / add_row / delete / add_field / add_table）Claude 会先报告影响范围，等你 y 才动手。这是 system prompt 里强制的礼貌。

配合 skill 让 Claude 更靠谱

如果发现 Claude 在某类任务上经常出错（比如批量改单元格忘了先 describe_table、bulk import CSV 时一次循环太多触发 rate limit），可以写一个 skill 放到 ~/.claude/skills/<name>/SKILL.md，描述步骤 + tool 调用顺序。Claude 会在匹配的对话里自动加载这段提示。

例如 ~/.claude/skills/xinghan-bulk-update/SKILL.md：

---
name: xinghan-bulk-update
description: Bulk-update many cells in a xinghan table based on a filter
---

When the user asks for bulk updates to a xinghan table:

1. Call `list_tables` to find the target table by name
2. Call `describe_table` to get the field schema (need fieldId for filter + update columns)
3. Call `query_rows` to enumerate matching rows (warn if count > 20)
4. Confirm count + sample with the user before issuing writes
5. For each row, call `update_cell(projectId, tableId, fieldId, recordId, newValue)`
6. Summarize the result at the end

这部分内置一套（5-6 个常用 skill）是 Phase 2 的事，会作为 ~/.claude/skills/xinghan-* 一键安装到用户目录。

已知限制

终端 cwd 默认在 $HOME，不是项目目录 —— 因为星汉项目是单个 .xhdb 文件（在桌面/Downloads/任意位置），没有”项目工作目录”概念。需要在某个项目目录工作的话自己 cd。
抽屉折叠重开后 xterm scrollback 丢，最近 ~64KB 输出能从 server backlog buffer 回放。PTY session 本身在服务端持续活着 30 分钟（无 attach 后空闲回收），所以重开还能继续之前的对话。
不是项目作用域：MCP server 一次能看到所有项目（list_projects 返回全部），让 Claude 操作之前要明确指定 projectId。Phase 2 计划让终端 spawn 时通过 env 注入当前项目，省掉手动传。
Windows 暂未测：终端 PTY 基于 node-pty ConPTY，理论上跨平台，但目前只在 macOS / Linux 验证过。

故障排查

症状	检查
`claude` 启动后 `/mcp` 看不到 xinghan	检查 `~/.claude.json` 是否正确；`xhe-mcp-stdio` 是否可执行（`ls -la`）
MCP 工具调用返回”project not found”	重新打开 `.xhdb` 项目让引擎挂载；确认 projectId 来自 `list_projects` 输出
终端面板第一次打开没显示主题色	已修；如果还出现请 `Cmd+R` 刷新一次。MutationObserver 监听 `<html>` class 变化重 apply xterm theme
改窗口大小后输入框出现 `{"type":"resize",...}`	已修；WS text 帧解析；如果还出现请重启编辑器（plugin server 没 reload）
终端 session 切来切去丢了	已修；iframe 重 mount 会 `GET /api/sessions` 恢复 tab 列表