[Docs]: server 模式 quickstart/basic usage 应明确区分 user_key 与 root_key + account/user

[qin-ctx]

问题概述

这个 issue 需要处理的是教程 / 文档表达不清，不是服务端认证逻辑本身的 bug。

当前服务端行为是符合设计的：

• 常规租户数据访问，应该优先使用某个租户下的 user_key
• 如果使用 root_key 去访问 tenant-scoped API，那么必须额外提供 account 和 user
• Python SDK 已经支持通过 SyncHTTPClient(..., account=..., user=...) 自动带上对应请求头

问题在于，用户最先接触到的 quickstart / basic usage 示例没有把这层区别讲清楚，导致很多人会自然把 root_key 理解成“全能 key”，然后直接拿它去调用 add_resource、find、ls 之类的数据 API，最后在运行时收到报错。

报错背景信息

这个 issue 虽然不是要修服务端 bug，但必须保留用户实际踩坑时的报错背景，否则后来者看不出文档到底误导了什么。

典型踩坑路径是：

1. 按 server 模式部署 OpenViking，并开启认证
2. 参考 quickstart 或 basic demo，看到“启用认证后传 api_key 即可”
3. 误把 root_key 当成常规 SDK 调用用的 key
4. 直接调用 add_resource()、find()、ls() 等 tenant-scoped API
5. 收到服务端拒绝请求的异常

典型报错如下：

openviking_cli.exceptions.InvalidArgumentError: ROOT requests to tenant-scoped APIs must include X-OpenViking-Account and X-OpenViking-User headers. Use a user key for regular data access.

也就是说，问题不是接口坏了，而是教程没有明确告诉用户：root_key 不能像 user_key 一样直接用于常规租户数据访问。

正确用法

常规数据访问：推荐使用 user_key

对于大多数 quickstart / 教程场景，应该直接使用某个租户下的 user_key：

import openviking as ov

client = ov.SyncHTTPClient(
    url="http://localhost:1933",
    api_key="your-user-key",
)
client.initialize()

client.add_resource(path="/tmp/test.md")
results = client.find("search query")

使用 root_key 时：必须同时传 account 和 user

如果确实要用 root_key 访问 tenant-scoped API，就必须显式指定目标租户身份：

import openviking as ov

client = ov.SyncHTTPClient(
    url="http://localhost:1933",
    api_key="your-root-key",
    account="acme",
    user="alice",
)
client.initialize()

client.add_resource(path="/tmp/test.md")
results = client.find("search query")

否则服务端会按设计拒绝请求。

为什么当前教程容易误导

目前相关信息其实已经部分存在，但分布不均，用户先看到的内容更容易形成错误认知：

• docs/zh/guides/04-authentication.md 已经说明：root_key 访问 tenant-scoped API 时必须显式提供 account / user
• docs/zh/getting-started/03-quickstart-server.md 目前只写了“启用认证时传 api_key”，没有区分 user_key 和 root_key
• examples/basic-usage/README_CN.md 的 HTTP client 示例没有补充 server 多租户认证差异

因此，用户很容易把 root_key 理解成“给了就能直接跑所有 SDK 示例”的 key。

建议修改内容

1. 在 docs/zh/getting-started/03-quickstart-server.md 中明确区分两类用法：
   • 常规教程流：使用 user_key
   • root_key 流：必须同时传 account / user
2. 在 examples/basic-usage/README_CN.md 的 HTTP 模式示例附近补一段说明，直接提示 server 模式下的多租户认证差异
3. 增加两个最小可运行示例：
   • user_key 的常规资源导入 / 检索示例
   • root_key + account/user 的显式租户访问示例
4. 如有必要，同步补充英文 quickstart / example，避免中英文文档认知不一致

验收标准

• 用户阅读 server quickstart / basic usage 后，能明确知道常规场景应该使用 user_key
• 用户能在同一处文档里看到 root_key + account/user 的完整示例
• 文档不再暗示“只要有 root_key 就能直接调用常规 tenant-scoped SDK API”
• 用户看到报错时，能从文档直接定位到原因，而不是误以为服务端实现异常

相关代码与文档位置

• openviking/server/auth.py:129-141
• openviking_cli/client/http.py:191-194
• docs/zh/guides/04-authentication.md:94-129
• docs/zh/getting-started/03-quickstart-server.md:46-52
• examples/basic-usage/README_CN.md:87-115