z-cli: Skill for Claude Code

项目信息

• 项目根目录：/Users/philip/Documents/code/zspace-cli
• 开发运行：./dev <command> <args>（热更新，改代码直接生效）
• API 模块：src/zspace/api/
• CLI 模块：src/zspace/commands/
• MCP 模块：src/zspace/mcp/tools/

工作流程

收到 curl 命令后，按以下步骤执行：

第一步：解析 curl

从 curl 命令中提取关键信息：

1. URL 路径 — 去掉协议/域名/端口，只保留路径部分。 例如 http://127.0.0.1:13579/v2/file/newdir → /v2/file/newdir 去掉 URL 中 rnd 和 webagent 等反缓存查询参数。

2. HTTP 方法 — 从 -X 参数获取。如果没有 -X 但有 --data-raw，默认为 POST。

3. 请求体参数 — 从 --data-raw 中解析。urllib.parse.urlencode(data) 会自动处理编码， 所以在代码中直接传原始字符串（不要手动 URL 编码）。

4. Referer 路径 — 从 -H 'Referer: ...' 中提取 path= 查询参数的值， 用于 build_headers() 的 path 参数。

5. 响应字段 — 如果响应包含缩写字段（如 n、di、s、mt 等），需要创建字段映射。

第二步：确认无重复

检查以下目录现有文件，确认没有重复实现：

• src/zspace/api/ — API 函数
• src/zspace/commands/ — CLI 命令
• src/zspace/mcp/tools/ — MCP 工具

新增代码前看一两个现有实现，确保风格一致。

第三步：实现 API 函数

根据 curl 在 src/zspace/api/ 下创建或修改 API 函数。

模板：

"""模块描述。"""

import urllib.parse

import httpx

from ..auth import build_headers, get_base_url
from . import _resp_or_json


def your_function(param1: str, param2: str = "default", raw: bool = False) -> str | httpx.Response:
    """函数描述。"""
    data = {
        "param1": param1,
        "param2": param2,
    }
    resp = httpx.request(
        "POST",
        f"{get_base_url()}/api/path",
        headers=build_headers(),
        content=urllib.parse.urlencode(data),
    )
    return _resp_or_json(resp, raw)

规则：

• 必须通过 _resp_or_json() 返回结果
• build_headers() 的 path 参数：有文件路径参数时传入该值，否则传空字符串
• 请求体用 urllib.parse.urlencode(data) 编码
• 跳过 URL 中的 rnd、webagent 等反缓存参数
• 参数名使用可读英文命名
• 需要 raw 参数支持原始响应

关于字段映射

如果 API 返回列表数据（数组）且包含缩写字段名，在 src/zspace/api/fields.py 中添加映射， 并在 API 函数中格式化。

from .fields import YOUR_API_FIELDS

def _format_your_api(data: list) -> str:
    out = []
    for item in data:
        readable = {}
        for short, val in item.items():
            long_name = YOUR_API_FIELDS.get(short, short)
            if long_name in ("modified_at", "created_at") and isinstance(val, (int, float)) and val:
                readable[long_name] = time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(val))
            else:
                readable[long_name] = val
        out.append(readable)
    return json.dumps(out, indent=2, ensure_ascii=False)