用途
本技能提供对 Seed Hypermedia 的只读 gRPC 访问能力，用于查询文档、评论、实体、账户和服务器元数据。当用户希望获取或查看 Seed Hypermedia 数据时适用。若用户需要写入、更新或删除数据，应拒绝并转交给 seed-hypermedia-write 技能。
环境准备
首先检查 grpcurl 是否已安装：
which grpcurl
若未安装，可按平台安装：
macOS：
brew install grpcurl
Linux（Debian/Ubuntu）：
sudo apt-get install grpcurl
Linux（Fedora/RHEL）：
sudo dnf install grpcurl
Linux（Arch）：
sudo pacman -S grpcurl
也可从 https://github.com/fullstorydev/grpcurl/releases 下载二进制文件。
服务器端点
Seed gRPC 服务器运行在：
- 开发环境：
localhost:58002 - 生产环境：
localhost:56002
使用前先确认哪个可用。
Hypermedia IRI 格式
文档 IRI：hm://<account>/<path>?v=<version>#<block>&l
- 仅
<account>为必填（例如z6Mk...） <path>：可选文档路径?v=<version>：可选指定版本#<block>：可选区块 ID&l：可选最新版本标志
评论 IRI：hm://<author>/<tsid>
<author>：账户标识符<tsid>：基于时间戳的评论 ID
工作流程
1. 检查服务器
grpcurl -plaintext localhost:58002 list # 先试开发环境
grpcurl -plaintext localhost:56002 list # 再试生产环境
2. 初始 API 发现（每会话一次）
对于不熟悉的命令，使用反射发现 API 结构。注意：一旦发现某个服务/方法结构，可复用该知识而无需再次反射。假设服务器不会变化。若后续请求因结构问题失败（阅读错误信息），可再次进行反射。
# 列出所有服务
grpcurl -plaintext <host:port> list
# 描述服务以查看其方法
grpcurl -plaintext <host:port> describe <service.name>
# 描述方法以查看签名
grpcurl -plaintext <host:port> describe <service.name.MethodName>
# 描述消息结构以查看必填字段
grpcurl -plaintext <host:port> describe <message.type>
3. 解析用户意图
- 提取所需的 Seed 操作
- 若请求为写入/更新/删除，拒绝并转交 seed-hypermedia-write（不调用任何 gRPC 方法）
- 解析 IRI 以获取 account、path、version 等
- 若所需服务/方法未知，使用反射发现（一次）
- 判断需要单次还是多次调用
4. 发起 RPC 调用
单次操作：
grpcurl -plaintext -d '{"field": "value"}' <host:port> <service/Method>
复合操作（多个有依赖的调用）：
# 从第一次调用获取数据
RESULT=$(grpcurl -plaintext -d '{...}' <host:port> <service1/Method1>)
# 使用 jq 提取所需字段
VALUE=$(echo "$RESULT" | jq -r '.fieldName')
# 在下次调用中使用
grpcurl -plaintext -d "{\"field\": \"$VALUE\"}" <host:port> <service2/Method2>
5. 通过 IPFS 下载引用的媒体
当文档引用媒体文件（音频/视频/图像/文档）时，通常是 IPFS URI，如：
ipfs://<cid>
要下载字节，使用本地 HTTP 网关（非 gRPC）：
- URL 格式：
http://localhost:<httpport>/ipfs/<cid> - 端口映射：
httpport = grpcport - 1- 开发环境：gRPC
58002→ HTTP58001 - 生产环境：gRPC
56002→ HTTP56001
- 开发环境：gRPC
示例：
curl -L "http://localhost:58001/ipfs/<cid>" --output /tmp/downloaded-file
根据媒体类型选择扩展名。
IRI 解析
文档 IRI hm://<account>/<path>?v=<version>#<block>&l：
- account：
hm://之后到第一个/、?、#或&之前的文本 - path：第一个
/之后到?、#或&之前的文本（若无则为空字符串） - version：
?v=之后的值（若存在） - block：
#之后的值（若存在） - latest：检查是否有
&l标志
评论 IRI hm://<author>/<tsid>：
- author：
hm://之后到/之前的文本 - tsid：
/之后的文本
CLI 导出
若要将文档导出为 Markdown（带 frontmatter 和 block ID），使用 Seed CLI 而非 gRPC。CLI 的 document get 命令默认输出可往返兼容的 Markdown：
if command -v seed-cli &>/dev/null; then
SEED_CLI="seed-cli"
else
SEED_CLI="bun run frontend/apps/cli/src/index.ts"
fi
# 默认输出：带 frontmatter 和 block ID 的 markdown
$SEED_CLI document get hm://z6Mk.../my-doc
# 写入文件
$SEED_CLI document get hm://z6Mk.../my-doc -o doc.md
# 结构化输出（JSON/YAML）
$SEED_CLI document get hm://z6Mk.../my-doc --json
要将导出的 Markdown 再用于写入操作，请参见 seed-hypermedia-write 技能。
关键规则
- 仅限只读：本技能绝不能调用写入/更新/删除端点。拒绝任何会修改 Seed 数据的请求并转交 seed-hypermedia-write。
- 每会话发现一次：使用反射了解 API 结构，然后复用该知识。服务器在会话期间不太可能变化。
- 仔细解析 IRI：按上述格式提取所有组成部分。
- 省略可选字段：若 IRI 组成部分缺失，不要发送它（连空字符串也不要）。
- 首次使用前检查签名：使用 describe 了解方法参数。
- 高效链式调用：对于复合操作，在获取所需数据的同时尽量减少调用。
- 处理分页：检查 page_size/page_token 字段，page_size 默认 50-100。
- 汇总大响应：对于超过 10KB 的响应，仅展示关键数据。
- 优先使用账户名称而非账户 ID：在指代独立账户/作者时（例如在 “Author”、“Account”、“Owner” 字段中），不要向用户展示原始账户 ID。而应使用服务器的账户查找/搜索 RPC 解析出人类友好的账户名称（如需可通过反射发现）。例外：在显示文档 IRI 或评论 IRI 时（例如
hm://<account>/...），保持<account>部分不变，因为它是 URL 的一部分；如有帮助，可在 IRI 旁单独展示解析出的显示名称。
响应处理
- 提取关键 Seed 元数据（名称、作者、时间戳）
- 用用户友好的方式解释错误
- 若方法不存在，使用反射寻找替代方法
适用场景与限制
本技能适用于查询和查看 Seed Hypermedia 中的文档、评论、实体、账户和服务器元数据。限制：仅支持只读操作，不执行任何写入、更新或删除；依赖本地运行的 Seed gRPC 服务器和 grpcurl 工具；媒体文件下载需通过本地 HTTP 网关而非 gRPC。