theseus-kit: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

theseus-kit 是一个 MCP 服务器，用于安全地检查、编辑、模板化和发布 TFRobot 配置。它通过标准 MCP 协议运行，同时暴露可选的 A2C-SMCP 兼容的 window:// 和 skill:// 资源。

当前状态：0.1.1，已实现 11 个 MCP 工具、3 个配置窗口和 12 类技能。默认 stdio 入口使用用户 PAT；无 PAT 的 stdio OAuth 外部回调登录尚未实现。

开发命令

需要 Python 3.11+ 和 uv。

uv sync --locked --all-groups   # 安装全部依赖
uv run theseus-kit              # 启动 MCP 服务器（stdio 传输）

所有质量检查通过 Poe 任务运行：

uv run poe check       # 顺序执行 format-check → lint → typecheck
uv run poe ci          # CI 完整流程：lock-check → check → test-cov
uv run poe format      # ruff 格式化
uv run poe lint        # ruff 代码检查
uv run poe typecheck   # mypy 严格模式类型检查
uv run poe test        # 运行测试（pytest，asyncio 模式 auto）
uv run poe test-cov    # 测试覆盖率（需要 ≥80%）
uv run poe build       # 构建 wheel + sdist
uv run poe package-check  # twine 检查构建产物

任务列表可通过 uv run poe --help 查看。

运行单个测试

uv run pytest tests/test_auth_routing.py -v
uv run pytest tests/test_auth_routing.py::test_exchange_wire_user_pat -v

E2E 测试（需要真实机器人）

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

发布流程见 docs/releasing.md：版本号由 bump-my-version 管理，通过 GitHub Release + OIDC Trusted Publishing 发布到 PyPI/TestPyPI。

架构

分层设计

1. MCP 表面层（server.py）— FastMCP 实例，工具/资源声明
2. 应用服务层（services/）— 读取、创建、编辑、删除、校验、保存模板、发布用例
3. TFRobot 客户端（transport.py、routing.py、tokens.py、credentials.py）— 认证 HTTP 适配器，对接 /v1/factory/** 和 /llms.txt
4. 资源投影层 — window:// 实时快照（resources.py，三个窗口 summary/recent/topology + 订阅能力 subscriptions.py）与 skill:// 技能指南（skills/，12 个类别，三层结构）：theseus 总纲调度 → 阶段技能 persona-interview / persona-optimize / plan-config / apply-config-plan → 原子技能 analyze-config / manage-topology / tune-config / save-template / publish-config / write-tfonto，外加反馈闭环技能 enhance。阶段交接物在机器人工作区 ~/.theseus/workspaces/<slug>/（画像 <slug>.md + configs/ + plans/）