# 安装
uv sync --locked --all-groups

# 启动 MCP 服务器（stdio 传输）
uv run theseus-kit

# 机器人路由信息
export THESEUS_ROBOT__ROBOT_ID="my-robot"
export THESEUS_ROBOT__NAMESPACE="default"
export THESEUS_ROBOT__ROBOT_TYPE="tfrobot"
export THESEUS_ROBOT__API_BASE_URL="https://api.example.com"
export THESEUS_ROBOT__MANAGER_BASE_URL="https://manager.example.com"

# 凭证（二选一）
# 方式 1：用户个人令牌（推荐——theseus-kit 是人管配置的工具，非 A2A）
export THESEUS_CREDENTIAL__KIND="user_pat"
export THESEUS_CREDENTIAL__PAT="tfp_xxx"
export THESEUS_CREDENTIAL__ROBOT_PUBLIC_ID="myorg:000042"
# 可选：显式缩窄短 Token；不设置时默认申请以下三个配置 scope
export THESEUS_CREDENTIAL__SCOPES="config:read config:write config:publish"

# 方式 2：OAuth 2.0（MCP Client 驱动授权）
export THESEUS_CREDENTIAL__KIND="oauth"
export THESEUS_CREDENTIAL__AUTHORIZATION_SERVER="https://manager.example.com"
export THESEUS_CREDENTIAL__SCOPES="config:read config:write"

get_config_summary        ← 入口：发现有哪些配置
    ↓
list_config_nodes         ← 导航：探索配置树
    ↓
get_config_detail         ← 读取：获取具体内容（含 content_hash）
    ↓
get_llms_doc              ← Schema：了解字段/校验规则
    ↓
update_draft              ← 修改：带冲突保护的写入
    ↓
validate_draft            ← 校验：发布前预检
    ↓
publish_config            ← 发布：显式确认 + root_hash 校验

配置的凭证 → Manager 换发端点 → 短 JWT（aud=robot:{public_id}）
→ 注入 X-TF-* 路由头 → 调用 TFRobotServer

MCP Client → TFRSManager AS（Authorization Code + PKCE）
→ OAuth AS token（aud={issuer}/robots/<id>, typ=at+jwt）
→ theseus-kit 校验（tfrs-auth RS256 + JWKS + scope）
→ 直传 TFRobotServer（无需换发）

{
  "mcpServers": {
    "theseus-kit": {
      "command": "uv",
      "args": ["run", "theseus-kit"],
      "env": {
        "THESEUS_ROBOT__ROBOT_ID": "my-robot",
        "THESEUS_ROBOT__NAMESPACE": "default",
        "THESEUS_ROBOT__ROBOT_TYPE": "tfrobot",
        "THESEUS_ROBOT__API_BASE_URL": "https://api.example.com",
        "THESEUS_ROBOT__MANAGER_BASE_URL": "https://manager.example.com",
        "THESEUS_CREDENTIAL__KIND": "user_pat",
        "THESEUS_CREDENTIAL__PAT": "tfp_xxx",
        "THESEUS_CREDENTIAL__ROBOT_PUBLIC_ID": "myorg:000042",
        "THESEUS_CREDENTIAL__SCOPES": "config:read config:write config:publish"
      }
    }
  }
}

{
  "mcpServers": {
    "theseus-kit": {
      "command": "uv",
      "args": ["run", "theseus-kit"],
      "env": {
        "THESEUS_ROBOT__ROBOT_ID": "my-robot",
        "THESEUS_ROBOT__NAMESPACE": "default",
        "THESEUS_ROBOT__ROBOT_TYPE": "tfrobot",
        "THESEUS_ROBOT__API_BASE_URL": "https://api.example.com",
        "THESEUS_ROBOT__MANAGER_BASE_URL": "https://manager.example.com",
        "THESEUS_CREDENTIAL__KIND": "oauth",
        "THESEUS_CREDENTIAL__AUTHORIZATION_SERVER": "https://manager.example.com",
        "THESEUS_CREDENTIAL__SCOPES": "config:read config:write"
      }
    }
  }
}

┌──────────────────────────────────────────┐
│  MCP 表面层（server.py）                  │
│  FastMCP · 11 工具 · 3 window:// 资源     │
│  3 skill:// 资源 · OAuth PRM 路由         │
├──────────────────────────────────────────┤
│  应用服务层（services/）                   │
│  ConfigReader · DraftEditor · Publisher   │
│  DraftValidator · TemplateSaver           │
│  LlmsDocReader                            │
├──────────────────────────────────────────┤
│  资源投影层（resources/ · skills/）        │
│  window:// 实时快照 · skill:// 中文指南    │
├──────────────────────────────────────────┤
│  TFRobot 客户端（transport.py）            │
│  RobotClient · RobotAuth · 令牌源双路径   │
├──────────────────────────────────────────┤
│  认证层（oauth.py · tokens.py ·           │
│         credentials.py）                  │
│  JwtVerifier 适配 · 令牌换发 · AS 发现    │
├──────────────────────────────────────────┤
│  模型层（models.py · config.py ·          │
│         routing.py · errors.py）          │
│  TFSResponse · 渐进披露模型 · 路由上下文  │
└──────────────────────────────────────────┘

UserPatConfig
  → build_credential()           # 构造 tfrs-auth PatCredential
  → AsyncCachingTokenSource      # token-exchange + 缓存 + single-flight + 临期刷新 + 退避
  → RobotAuth                    # 注入 Authorization: Bearer <jwt> + X-TF-*
  → TFRobotServer

OAuthConfig
  → TheseusTokenVerifier         # tfrs-auth JwtVerifier → MCP SDK TokenVerifier
  → RFC 8414 AS 发现             # fetch_as_metadata() → jwks_uri + issuer
  → 校验: RS256 + scope + exp    # JwtVerifier.verify(required_scope=)
  → StaticTokenSource            # 静态持有已验 token，不换发
  → RobotAuth                    # 注入 Authorization: Bearer + X-TF-*
  → TFRobotServer                # 原生接受 aud={issuer}/robots/<id> + typ=at+jwt

1. MCP Client 调用 get_config_detail(locator="...")

2. server.py 工具处理函数
   → ConfigReader(robot_id=...).get_detail(client, locator, depth, max_bytes)

3. RobotClient.from_settings(settings)
   → RobotAuth(token_source, context).async_auth_flow()
     → token_source.token() 获取 Bearer（换发或静态）
     → context.routing_headers() 获取 X-TF-Namespace / X-TF-RobotId / X-TF-RobotType
   → httpx.AsyncClient 发送 GET 请求到 TFRobotServer

4. TFRobotServer 响应的 JSON 被反序列化为 TFSResponse[ConfigDetail]
   → code / message / data 信封解包
   → ConfigDetail 包含 content_hash / bytes_returned / truncated / redacted[] 等元数据

5. 结果返回给 MCP Client
   → 同时更新 window:// 资源的 last_locator（用于 recent 快照）

uv sync --locked --all-groups   # 安装全部依赖
uv run poe check                # 顺序执行 format-check → lint → typecheck
uv run poe ci                   # CI 完整流程：lock-check → check → test-cov
uv run poe test                 # 运行测试（pytest，asyncio 模式 auto）
uv run poe test-cov             # 测试覆盖率（需要 ≥80%）

THESEUS_E2E=1 \
THESEUS_ROBOT__ROBOT_ID=<rid> \
THESEUS_ROBOT__NAMESPACE=<ns> \
THESEUS_ROBOT__ROBOT_TYPE=tfrobot \
THESEUS_ROBOT__API_BASE_URL=https://api.<clusterDomain> \
THESEUS_ROBOT__MANAGER_BASE_URL=https://<manager-host> \
THESEUS_CREDENTIAL__KIND=user_pat \
THESEUS_CREDENTIAL__PAT=<tfp_...> \
THESEUS_CREDENTIAL__ROBOT_PUBLIC_ID=<orgSlug>:<employeeNo> \
uv run pytest tests/test_e2e_robot.py -v -m e2e

uv run poe ci && uv run poe build && uv run poe package-check