cann-gitcode-mcp 0.1.0__tar.gz → 0.3.0__tar.gz

cann_gitcode_mcp-0.3.0/AGENTS.md

@@ -0,0 +1,179 @@
+# AGENTS.md — cann-gitcode-mcp
+
+## Project Overview
+
+`cann-gitcode-mcp` is an MCP server that exposes GitCode REST API (v5, base `https://gitcode.com/api/v5`) as MCP tools for CANN developers. Package: `cann-gitcode-mcp`; module: `cann_gitcode_mcp`.
+
+## Quick Reference
+
+```bash
+uv pip install -e ".[dev]"   # Install (or: pip install -e ".[dev]")
+pytest -v                     # Run tests
+python -m cann_gitcode_mcp    # Start MCP server (stdio)
+```
+
+| Env Variable | Required | Description |
+|---|---|---|
+| `GITCODE_API_TOKEN` | Yes | Personal access token from GitCode |
+| `GITCODE_API_BASE_URL` | No | Override API base (default: `https://gitcode.com/api/v5`) |
+
+## Architecture
+
+```
+src/cann_gitcode_mcp/
+├── __init__.py          # Package metadata
+├── __main__.py          # python -m entry → server.main()
+├── server.py            # FastMCP instance; wires all tool modules
+├── client.py            # GitCodeClient (async httpx wrapper)
+└── tools/
+    ├── __init__.py
+    ├── pull_request.py  # 7 PR tools
+    └── pipeline.py      # 2 pipeline tools (trigger + summary)
+```
+
+- **`server.py`** — creates `FastMCP("gitcode")`, calls every `register_*_tools(mcp)`. Single wiring point.
+- **`client.py`** — `GitCodeClient` reads `GITCODE_API_TOKEN` from env, provides async `get/post/patch/put/delete`. Raises `ValueError` if token unset, `RuntimeError` on non-2xx.
+- **`tools/`** — each file owns one domain. Tools registered via `@mcp.tool()` inside `register_*_tools(mcp)`.
+
+## Code Rules
+
+1. **Python 3.11+** — `from __future__ import annotations` at top of every file.
+2. **Async** — all tool functions must be `async def`.
+3. **Type hints** — all parameters and return types annotated.
+4. **Return `str`** — `json.dumps(data, ensure_ascii=False)`, no `indent`.
+5. **Docstrings** — first line = MCP tool description; `Args:` for params.
+6. **Registration** — tools via `@mcp.tool()` inside `register_*_tools(mcp)`, never at module import time.
+7. **No bare exceptions** — let errors propagate; MCP framework surfaces them.
+8. **No global state beyond `_client`** — the singleton is reset between tests via `patch`.
+
+## Adding a New Tool
+
+### 1. Create `src/cann_gitcode_mcp/tools/<domain>.py`
+
+```python
+from __future__ import annotations
+import json
+from mcp.server.fastmcp import FastMCP
+from cann_gitcode_mcp.client import GitCodeClient
+
+_client: GitCodeClient | None = None
+
+def _get_client() -> GitCodeClient:
+    global _client
+    if _client is None:
+        _client = GitCodeClient()
+    return _client
+
+def register_<domain>_tools(mcp: FastMCP) -> None:
+
+    @mcp.tool()
+    async def get_thing(owner: str, repo: str, number: int) -> str:
+        """One-line description for MCP.
+
+        Args:
+            owner: Repository namespace
+            repo: Repository name
+            number: Item number
+        """
+        client = _get_client()
+        result = await client.get(f"/repos/{owner}/{repo}/things/{number}")
+        return json.dumps(result, ensure_ascii=False)
+```
+
+### 2. Register in `server.py`
+
+```python
+from cann_gitcode_mcp.tools.<domain> import register_<domain>_tools
+register_<domain>_tools(mcp)
+```
+
+### 3. Add tests in `tests/test_<domain>.py`
+
+```python
+import pytest
+from unittest.mock import AsyncMock, patch
+from mcp.server.fastmcp import FastMCP
+
+@pytest.fixture
+def mcp_server():
+    server = FastMCP("test")
+    with patch("cann_gitcode_mcp.tools.<domain>._client", None), \
+         patch.dict("os.environ", {"GITCODE_API_TOKEN": "test-token"}):
+        register_<domain>_tools(server)
+        yield server
+
+async def test_get_thing(mcp_server):
+    tool_fn = mcp_server._tool_manager._tools["get_thing"].fn
+    with patch("cann_gitcode_mcp.tools.<domain>.GitCodeClient.get",
+               new_callable=AsyncMock, return_value={"id": 1}):
+        result = await tool_fn(owner="org", repo="repo", number=1)
+    assert '"id": 1' in result
+```
+
+### 4. Verify
+
+```bash
+pytest tests/ -v  # All tests must pass before committing
+```
+
+## Token Budget Rules
+
+MCP tool tokens directly squeeze LLM context. Rules split into **input side** (tool definitions, fixed cost per turn) and **output side** (tool responses, variable cost per call).
+
+### Input Side — Tool Definitions (Fixed Cost)
+
+| # | Rule | Practice | Anti-pattern |
+|---|---|---|---|
+| I1 | 合并同域工具 | 相关操作合并为一个工具 + `action` 参数路由 | 一个 API endpoint = 一个 tool |
+| I2 | 描述只写决策信息 | 一行说"做什么"，`Args:` 只写参数含义 | 写示例、教程、实现细节、重复 schema 约束 |
+| I3 | enum 优先于 oneOf | `Literal["a","b"]` 生成 `enum` | `oneOf` 每个值一个 object，2-4x 膨胀 |
+| I4 | 预算守护 | `test_tool_definition_budget.py` 断言工具 ≤ 4、定义 ≤ 1300 tokens | 加工具不跑预算测试 |
+| I5 | 描述中不重复 schema | type/default/min/max 已在 JSON Schema，不再重复 | `"page: Page number (integer, minimum 1, default 1)"` |
+
+### Output Side — Tool Responses (Variable Cost)
+
+| # | Rule | Practice | Anti-pattern |
+|---|---|---|---|
+| O1 | 字段裁剪 | 只返回决策字段，用 `_slim_*`。丢弃 `_links`, `permissions`, `avatar_url` | 透传原始 API 响应（70-90% 冗余） |
+| O2 | 紧凑 JSON | `json.dumps(data, ensure_ascii=False)` 不加缩进 | `indent=2` 增加 30-40% token |
+| O3 | 摘要/详情分级 | `detail="summary"\|"full"` 参数；列表默认 key fields | 列表接口返回完整 body |
+| O4 | 大内容截断 | diff/日志设上限 `_MAX_DIFF_LINES`，超出截断 | 无限制返回大 diff/日志 |
+| O5 | 失败详细 / 成功折叠 | 失败项保留名称+状态+日志链接；成功项折叠为计数 | 成功失败全量输出 |
+| O6 | 写操作返回确认 | create/merge/comment 只返回 id + url | 返回完整创建对象 |
+| O7 | 公共前缀提取 | 多 URL 共享前缀时提取 `base_url` + 相对路径 | 每条记录完整 URL |
+| O8 | structuredContent 不双送 | `content` 和 `structuredContent` 只送一份 | 两者相同但都发送 |
+
+### Test Guards
+
+| Test | Responsibility |
+|---|---|
+| `test_tool_definition_budget.py` | 工具数量和定义 token 总量不超预算 |
+| `test_token_budget.py` | 每个工具响应 token ≤ 预算 |
+| `TestTokenReductionReport` | raw vs slim token 对比（信息性） |
+
+Token approximation: `len(text) // 4` (conservative for mixed CJK/English).
+
+### Current Baseline (2026-03-31)
+
+| Metric | Value |
+|---|---|
+| Tool count | 4 (2 PR + 2 pipeline) |
+| Definition tokens | ~1263 (budget: 1300) |
+| Max response budget | 600 tokens (`get_pr_pipeline_summary`) |
+| Response trimming | 87-95% vs raw API |
+
+### Scaling (When Tools > 8)
+
+Not needed at 4 tools, but plan ahead:
+
+- **Toolset filtering**: `--toolsets` flag, users enable only needed groups
+- **Lazy loading**: expose name + one-line summary, load full schema on demand (91% input savings)
+- **JSON `$ref`**: shared params defined once via `$ref`
+- **Code Mode**: sandbox replaces N tools (98%+ savings, per Anthropic/Cloudflare)
+
+## GitCode API Reference
+
+- Base URL: `https://gitcode.com/api/v5`
+- Auth: `Authorization: Bearer <token>`
+- PR endpoints: `/repos/{owner}/{repo}/pulls[/{number}[/merge|comments|files]]`
+- Pipeline data: extracted from cann-robot PR comments (no dedicated API); see `docs/pipeline-tools-research.md`

cann_gitcode_mcp-0.3.0/CLAUDE.md

@@ -0,0 +1,5 @@
+# CLAUDE.md
+
+<!-- 本项目开发指南统一维护在 AGENTS.md，避免重复 -->
+
+See [AGENTS.md](AGENTS.md) for all project guidelines.

cann_gitcode_mcp-0.3.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: cann-gitcode-mcp
+Version: 0.3.0
+Summary: CANN GitCode MCP Server - GitCode platform tools for CANN developers
+Project-URL: Homepage, https://gitcode.com/shengnan666/cann-gitcode-mcp
+Project-URL: Repository, https://gitcode.com/shengnan666/cann-gitcode-mcp
+Project-URL: Issues, https://gitcode.com/shengnan666/cann-gitcode-mcp/issues
+Author-email: shengnan <shengnan1126@yeah.net>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: cann,gitcode,mcp,model-context-protocol
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: twine>=6.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# cann-gitcode-mcp
+
+[![PyPI version](https://img.shields.io/pypi/v/cann-gitcode-mcp)](https://pypi.org/project/cann-gitcode-mcp/)
+[![Python](https://img.shields.io/pypi/pyversions/cann-gitcode-mcp)](https://pypi.org/project/cann-gitcode-mcp/)
+[![License](https://img.shields.io/pypi/l/cann-gitcode-mcp)](https://github.com/shengnan666/cann-gitcode-mcp/blob/main/LICENSE)
+
+CANN 社区的代码托管在 [GitCode](https://gitcode.com/) 平台。`cann-gitcode-mcp` 将 GitCode API 封装为 [MCP](https://modelcontextprotocol.io/) 工具，让 CANN 开发者在 Claude Code 等 AI 助手中直接操作仓库的 Pull Request、Issue、流水线等，无需离开对话界面。
+
+## 快速开始
+
+### 1. 安装
+
+```bash
+pip install cann-gitcode-mcp
+```
+
+### 2. 配置 Claude Code
+
+先在 [GitCode 用户设置](https://gitcode.com/setting/token-classic) 中生成个人访问令牌，然后按需选择配置范围：
+
+**方式一：当前用户范围（对本用户的所有项目生效）**
+
+编辑 `~/.claude.json`，在顶层添加 `mcpServers` 字段：
+
+```json
+{
+  "mcpServers": {
+    "cann-gitcode": {
+      "command": "cann-gitcode-mcp",
+      "env": {
+        "GITCODE_API_TOKEN": "your_token_here"
+      }
+    }
+  }
+}
+```
+
+**方式二：仅当前工程生效（可提交到版本库，团队共享）**
+
+在项目根目录创建或编辑 `.mcp.json`：
+
+```json
+{
+  "mcpServers": {
+    "cann-gitcode": {
+      "command": "cann-gitcode-mcp",
+      "env": {
+        "GITCODE_API_TOKEN": "your_token_here"
+      }
+    }
+  }
+}
+```
+
+> **注意**：`.mcp.json` 若提交到版本库，其他协作者也会加载该 MCP 配置，但每人需在自己机器上安装 `cann-gitcode-mcp` 并填写自己的 Token。如果 Token 因人而异，可将 `.mcp.json` 加入 `.gitignore`，或仅配置不含 Token 的部分，通过其他方式注入环境变量。
+
+重启 Claude Code 即可使用。
+
+> **环境变量说明**：Token 通过 MCP 配置的 `env` 字段传入即可，无需手动 `export`。如需覆盖 API 地址，可额外设置 `GITCODE_API_BASE_URL`（默认 `https://gitcode.com/api/v5`）。
+
+## 可用工具
+
+### Pull Request
+
+| 工具名 | 说明 |
+|--------|------|
+| `create_pull_request` | 创建 Pull Request |
+| `list_pull_requests` | 列出仓库的 Pull Request（支持状态、排序等过滤） |
+| `get_pull_request` | 获取指定 PR 的详细信息 |
+| `merge_pull_request` | 合并 Pull Request |
+| `comment_pull_request` | 在 PR 上发表评论 |
+| `get_pull_request_files` | 获取 PR 的变更文件列表 |
+| `list_pull_request_comments` | 获取 PR 的所有评论 |
+
+### Pipeline（流水线）
+
+| 工具名 | 说明 |
+|--------|------|
+| `trigger_pr_pipeline` | 向 PR 发送 `compile` 评论以触发 CI/CD 流水线 |
+| `get_pr_pipeline_summary` | 获取 PR 的 CI/CD 流水线摘要（解析 cann-robot 评论） |
+
+`trigger_pr_pipeline` 通过在 PR 下发表 `compile` 评论来触发 cann-robot 启动流水线。**注意**：重复触发会中止当前运行的流水线并重新启动，请勿多次调用。
+
+`get_pr_pipeline_summary` 从 PR 评论中解析 cann-robot 发布的流水线结果，返回每个任务的名称、状态（SUCCESS/FAILED/ABORTED）、日志链接、构建产物下载链接，以及整体 CI 结论。无需 openLiBing token，仅使用 GitCode API。
+
+## 路线图
+
+当前处于早期开发阶段（`0.x`），已实现 PR 工具集和流水线摘要。后续将按 CANN 社区实际研发流程的优先级逐步扩展：
+
+1. **Issue 工具** — Issue 增删改查、评论管理（CANN 社区日常协作最频繁的场景）
+2. **仓库工具** — 分支管理、文件读取、提交历史
+3. **流水线详情（Level 2）** — 通过 openLiBing API 获取 stage/job/step 级别的详细信息和错误消息
+
+欢迎在 [Issue](https://gitcode.com/shengnan666/cann-gitcode-mcp/issues) 中提出需求或反馈。
+
+## 开发
+
+```bash
+# 安装开发依赖
+pip install -e ".[dev]"
+
+# 运行测试
+pytest
+
+# 构建与发布
+python -m build
+twine upload dist/*
+```
+
+## 许可证
+
+[Apache License 2.0](LICENSE)

cann_gitcode_mcp-0.3.0/README.md

@@ -0,0 +1,112 @@
+# cann-gitcode-mcp
+
+[![PyPI version](https://img.shields.io/pypi/v/cann-gitcode-mcp)](https://pypi.org/project/cann-gitcode-mcp/)
+[![Python](https://img.shields.io/pypi/pyversions/cann-gitcode-mcp)](https://pypi.org/project/cann-gitcode-mcp/)
+[![License](https://img.shields.io/pypi/l/cann-gitcode-mcp)](https://github.com/shengnan666/cann-gitcode-mcp/blob/main/LICENSE)
+
+CANN 社区的代码托管在 [GitCode](https://gitcode.com/) 平台。`cann-gitcode-mcp` 将 GitCode API 封装为 [MCP](https://modelcontextprotocol.io/) 工具，让 CANN 开发者在 Claude Code 等 AI 助手中直接操作仓库的 Pull Request、Issue、流水线等，无需离开对话界面。
+
+## 快速开始
+
+### 1. 安装
+
+```bash
+pip install cann-gitcode-mcp
+```
+
+### 2. 配置 Claude Code
+
+先在 [GitCode 用户设置](https://gitcode.com/setting/token-classic) 中生成个人访问令牌，然后按需选择配置范围：
+
+**方式一：当前用户范围（对本用户的所有项目生效）**
+
+编辑 `~/.claude.json`，在顶层添加 `mcpServers` 字段：
+
+```json
+{
+  "mcpServers": {
+    "cann-gitcode": {
+      "command": "cann-gitcode-mcp",
+      "env": {
+        "GITCODE_API_TOKEN": "your_token_here"
+      }
+    }
+  }
+}
+```
+
+**方式二：仅当前工程生效（可提交到版本库，团队共享）**
+
+在项目根目录创建或编辑 `.mcp.json`：
+
+```json
+{
+  "mcpServers": {
+    "cann-gitcode": {
+      "command": "cann-gitcode-mcp",
+      "env": {
+        "GITCODE_API_TOKEN": "your_token_here"
+      }
+    }
+  }
+}
+```
+
+> **注意**：`.mcp.json` 若提交到版本库，其他协作者也会加载该 MCP 配置，但每人需在自己机器上安装 `cann-gitcode-mcp` 并填写自己的 Token。如果 Token 因人而异，可将 `.mcp.json` 加入 `.gitignore`，或仅配置不含 Token 的部分，通过其他方式注入环境变量。
+
+重启 Claude Code 即可使用。
+
+> **环境变量说明**：Token 通过 MCP 配置的 `env` 字段传入即可，无需手动 `export`。如需覆盖 API 地址，可额外设置 `GITCODE_API_BASE_URL`（默认 `https://gitcode.com/api/v5`）。
+
+## 可用工具
+
+### Pull Request
+
+| 工具名 | 说明 |
+|--------|------|
+| `create_pull_request` | 创建 Pull Request |
+| `list_pull_requests` | 列出仓库的 Pull Request（支持状态、排序等过滤） |
+| `get_pull_request` | 获取指定 PR 的详细信息 |
+| `merge_pull_request` | 合并 Pull Request |
+| `comment_pull_request` | 在 PR 上发表评论 |
+| `get_pull_request_files` | 获取 PR 的变更文件列表 |
+| `list_pull_request_comments` | 获取 PR 的所有评论 |
+
+### Pipeline（流水线）
+
+| 工具名 | 说明 |
+|--------|------|
+| `trigger_pr_pipeline` | 向 PR 发送 `compile` 评论以触发 CI/CD 流水线 |
+| `get_pr_pipeline_summary` | 获取 PR 的 CI/CD 流水线摘要（解析 cann-robot 评论） |
+
+`trigger_pr_pipeline` 通过在 PR 下发表 `compile` 评论来触发 cann-robot 启动流水线。**注意**：重复触发会中止当前运行的流水线并重新启动，请勿多次调用。
+
+`get_pr_pipeline_summary` 从 PR 评论中解析 cann-robot 发布的流水线结果，返回每个任务的名称、状态（SUCCESS/FAILED/ABORTED）、日志链接、构建产物下载链接，以及整体 CI 结论。无需 openLiBing token，仅使用 GitCode API。
+
+## 路线图
+
+当前处于早期开发阶段（`0.x`），已实现 PR 工具集和流水线摘要。后续将按 CANN 社区实际研发流程的优先级逐步扩展：
+
+1. **Issue 工具** — Issue 增删改查、评论管理（CANN 社区日常协作最频繁的场景）
+2. **仓库工具** — 分支管理、文件读取、提交历史
+3. **流水线详情（Level 2）** — 通过 openLiBing API 获取 stage/job/step 级别的详细信息和错误消息
+
+欢迎在 [Issue](https://gitcode.com/shengnan666/cann-gitcode-mcp/issues) 中提出需求或反馈。
+
+## 开发
+
+```bash
+# 安装开发依赖
+pip install -e ".[dev]"
+
+# 运行测试
+pytest
+
+# 构建与发布
+python -m build
+twine upload dist/*
+```
+
+## 许可证
+
+[Apache License 2.0](LICENSE)

cann_gitcode_mcp-0.3.0/docs/pipeline-tools-research.md

@@ -0,0 +1,210 @@
+# Pipeline Tools 前期调研与架构设计
+
+> 调研日期: 2026-03-29
+
+## 1. 背景
+
+CANN 的 CI/CD 流水线托管在 openLiBing (www.openlibing.com)。需要通过 MCP 工具查看流水线结果（编译结果、用例执行结果等）。
+
+## 2. openLiBing 平台调研
+
+### 2.1 平台概况
+
+- **URL**: https://www.openlibing.com
+- **性质**: MaJun 平台上的 CI/CD 服务，用于华为开源生态
+- **登录方式**: 通过 GitCode 账号 OAuth 授权登录
+- **公开 API**: 无。无公开文档、无 SDK、无 CLI
+- **内部接口**: 有，Web UI 背后通过 JSON 接口获取数据
+
+### 2.2 已确认的内部接口
+
+**Pipeline Run Detail（流水线运行详情）**
+
+```
+GET /gateway/openlibing-cicd/project/pipeline/pipeline-run/detail
+    ?projectId={projectId}
+    &pipelineId={pipelineId}
+    &pipelineRunId={pipelineRunId}
+```
+
+- Host: `www.openlibing.com`
+- 认证方式: JWT Token，通过 Cookie 和 Header 双重传递
+  - Cookie: `token={jwt}; csrf-token-open-li-bing={jwt}`
+  - Header: `Csrf-Token-Open-Li-Bing: {jwt}`
+- Token 有效期: 30 分钟（`Max-Age=1800`），响应 Set-Cookie 自动续期
+- JWT Payload 含: accountId, accountLogin, accountPlatform("gitcode"), exp 等
+
+### 2.3 流水线数据没有列表接口
+
+用户确认：openLiBing 没有通过 pipelineId 查询运行列表的接口。每次流水线的入口是从 GitCode PR 上 bot 评论中的链接点进去的。
+
+## 3. GitCode PR Bot 评论分析
+
+### 3.1 Bot 信息
+
+- **Bot 用户**: `cann-robot` (login: `cann-robot`)
+- **评论 API**: `GET /api/v5/repos/{owner}/{repo}/pulls/{number}/comments`
+- **认证**: `Authorization: Bearer {GITCODE_API_TOKEN}`（注意是 Bearer 不是 token 前缀）
+
+### 3.2 Bot 评论结构
+
+Bot 发两条评论：
+
+**评论 1**: PR 审批状态（CLA签名、lgtm/approve 进度）
+
+**评论 2**: 流水线结果（关键），包含：
+
+1. **触发信息**: "流水线任务触发成功"
+2. **openLiBing 链接**:
+   ```
+   https://www.openlibing.com/apps/pipelineDetail
+     ?pipelineId={pipelineId}
+     &pipelineRunId={pipelineRunId}
+     &projectName=CANN
+   ```
+3. **HTML 表格**，每行一个任务：
+   - 任务名称: `Check_Pr`, `Compile_X86_compiler`, `UT_Test_dflow` 等
+   - 状态: `SUCCESS` / `FAILED` / `ABORTED`
+   - 日志链接: openLiBing 详情页链接
+   - 下载链接: `ascend-ci.obs.cn-north-4.myhuaweicloud.com` 上的构建产物
+4. **结论**: `CI执行失败` 或 `CI执行成功`
+
+### 3.3 Bot 评论示例（关键部分）
+
+```html
+流水线任务触发成功
+任务链接 [<a href='https://www.openlibing.com/apps/pipelineDetail?pipelineId=xxx&pipelineRunId=yyy&projectName=CANN'>yyy</a>]
+<table>
+  <tr><th>任务名称</th><th>状态</th><th>日志</th><th>下载链接</th></tr>
+  <tr>
+    <td><strong>Compile_X86_compiler</strong></td>
+    <td>❌ FAILED</td>
+    <td><a href=https://www.openlibing.com/apps/pipelineDetail?...>>>>>></a></td>
+    <td><a href=></a></td>
+  </tr>
+  <tr>
+    <td><strong>Compile_X86_executor</strong></td>
+    <td>✅ SUCCESS</td>
+    <td><a href=...>>>>>></a></td>
+    <td><a href=https://ascend-ci.obs.cn-north-4.myhuaweicloud.com/ge/package/1601/cann-ge-executor_linux-x86_64.run>>>>>></a></td>
+  </tr>
+  ...
+</table>
+[2026-03-28 16:45:30] CI执行失败
+```
+
+## 4. openLiBing Pipeline Run Detail 数据结构
+
+从实际抓包获得的 JSON 结构（以 cann_ge pipeline #7071 为例）：
+
+```
+Pipeline Run
+├── id, pipeline_id, name("cann_ge"), status("FAILED")
+├── executor_name, trigger_type("Note"), run_number(7071)
+├── start_time, end_time (epoch ms)
+├── sources[] — 代码来源信息
+│   └── git_type("gitcode"), repo_name("ge"), build_params(MR信息)
+├── artifacts[] — 构建产物列表
+│   └── name, packageType, version
+└── stages[] — 流水线阶段列表
+    ├── 阶段_1 (sequence:0) — 解析CI分支, COMPLETED
+    ├── Image (sequence:1) — 解析镜像版本, COMPLETED
+    ├── 编译构建 (sequence:2) — 14个并行Job, FAILED
+    │   └── jobs[]
+    │       ├── name, identifier, status, condition
+    │       ├── message (失败时有错误信息)
+    │       └── steps[]
+    │           ├── name, task, business_type, status, message
+    │           └── inputs[] (key/value配置)
+    ├── LLT (sequence:3) — UT/ST测试 + codecheck等, 23个Job, INIT(未执行)
+    ├── lcov (sequence:4) — 覆盖率报告, INIT
+    └── 后处理阶段 (sequence:5) — last_comment + Resource Clean, FAILED
+```
+
+### 4.1 Stage 依赖关系
+
+```
+阶段_1 → Image → 编译构建 → LLT → lcov
+                                └→ 后处理阶段 (run_always:true)
+```
+
+### 4.2 Job 状态枚举
+
+- `COMPLETED` — 成功
+- `FAILED` — 失败（message 字段含错误信息）
+- `INIT` — 未执行（因前置阶段失败）
+- `ABORTED` — 被中止
+
+### 4.3 典型错误信息
+
+```json
+{"errorMessage":" 构建任务执行失败!","errorCode":"DEV-CODECI-35002"}
+```
+
+## 5. 架构设计方案
+
+### 5.1 分层设计（已与用户达成共识）
+
+**Level 1: PR 评论解析 + 触发（纯 GitCode API）** ✅ 已实现
+- 不依赖 openLiBing，只用 GITCODE_API_TOKEN
+- 工具 1: `get_pr_pipeline_summary(owner, repo, pr_number)` — 解析 cann-robot 评论提取任务状态表，通过 PR labels 判断流水线状态（running/passed/failed），支持分页获取所有评论确保取到最后一次 pipeline 结果
+- 工具 2: `trigger_pr_pipeline(owner, repo, pr_number)` — 在 PR 中发 `compile` 评论触发流水线
+
+**Level 2: openLiBing 详情（需 openLiBing JWT）**
+- 获取 stage/job/step 级别的详细信息和错误消息
+- 工具: `get_pipeline_run_detail(pipeline_id, pipeline_run_id)`
+- 需要解决 JWT 获取和续期问题
+- **后续实现**，用于获取失败的详细信息
+
+### 5.2 流水线状态判断
+
+通过 PR labels 判断流水线状态（比解析评论更准确）：
+
+| PR Label | pipeline_status |
+|----------|----------------|
+| `ci-pipeline-running` | `running` |
+| `ci-pipeline-passed` | `passed` |
+| `ci-pipeline-failed` | `failed` |
+| 都没有 | `unknown` |
+
+### 5.3 职责划分
+
+| 职责 | 归属 | 原因 |
+|------|------|------|
+| 发 `compile` 评论触发流水线 | MCP 工具 | 原子操作 |
+| 查询最新 pipeline 结果 | MCP 工具 | 原子操作 |
+| 等待流水线完成（轮询） | 调用方（Claude Code / 用户） | 等待时间分钟~几十分钟级 |
+| 判断是否需要重新触发 | 调用方 | 业务决策 |
+
+### 5.4 代码结构
+
+```
+src/cann_gitcode_mcp/
+├── client.py              # 现有 GitCodeClient (Bearer token auth)
+├── openlibing_client.py   # 待实现: OpenLiBingClient (JWT + CSRF auth, auto-refresh)
+└── tools/
+    ├── pull_request.py    # 7 个 PR 工具（含 list_pull_request_comments）
+    └── pipeline.py        # 2 个 pipeline 工具（trigger + summary）
+```
+
+### 5.5 环境变量
+
+| 变量 | 用途 | Level |
+|------|------|-------|
+| `GITCODE_API_TOKEN` | GitCode API 认证 | Level 1 |
+| `OPENLIBING_TOKEN` | openLiBing JWT token | Level 2 |
+
+## 6. 待确认/待探索
+
+- [ ] openLiBing 是否有获取单个 Job 日志的接口（需要用户在 Web UI 上抓包）
+- [ ] openLiBing JWT 的自动获取方案（OAuth flow 还是手动提供）
+- [ ] 是否有其他 openLiBing 接口（如项目列表、流水线列表等）
+
+## 7. 参考
+
+- GitCode PR 评论 API: `GET /api/v5/repos/{owner}/{repo}/pulls/{number}/comments`
+- openLiBing Pipeline Detail: `GET /gateway/openlibing-cicd/project/pipeline/pipeline-run/detail`
+- 示例 PR: https://gitcode.com/cann/ge/pull/1601
+- 示例 Pipeline Run ID: `aaa5c9122dbb44b0bbdd2890218a92f2`
+- 示例 Pipeline ID: `8033cdebd5e5420e9165181589392a80`
+- Project ID: `300033`, Project Name: `CANN`