# zhenyun-pangu-mcp

> ## 架构定位：盘古「实时接口」
>
> 在四层架构中，本 MCP 是日志、数据库、猪齿鱼和代码的**实时事实来源**；脚本平台当前源码、
> 版本、Fixture 和启用状态由独立的 `zhenyun-script-platform-mcp` 提供：
>
> | 层 | 回答什么 | 载体 |
> |---|---|---|
> | **Skill** | 这个任务应该怎么做 | `custom-skills/` 的 SKILL.md（编排流程） |
> | **Knowledge** | 业务/系统/字段**是什么** | 本 MCP 的 `knowledge_base/`（稳定事实，沉淀于 knowledge_docs） |
> | **Template** | 以前类似问题**怎么解决** | 本 MCP 的 `knowledge_base/`（SQL 模板，沉淀于 sql_templates） |
> | **zhenyun-pangu-mcp** | **现在**业务环境真实**是什么/发生了什么** | 本 MCP（日志 / 数据 / 猪齿鱼 / 代码 / 脚本身份发现） |
> | **zhenyun-script-platform-mcp** | 平台当前脚本是什么、如何真实调试与安全保存 | Script Platform API / DEV GraalJS Runtime |
>
> **边界原则**：
> - 所有**可能变化**的实时事实（当前日志、当前数据、当前 Schema、当前状态、当前服务状态）一律走本 MCP。
> - 静态知识（Skill Markdown / Knowledge / Template）只负责帮助 Agent 理解这些实时数据意味着什么，**不替代实时查询**。
> - Pangu 的脚本搜索只负责发现精确身份；当前源码、版本、Fixture、Debug、Save、Deploy 必须使用 `zhenyun-script-platform-mcp`。
> - 旧的独立 `log-ops` / `sql-ops` / `gitlab-code` MCP 已被本 MCP 整合取代，不再是正式概念，请勿引用。
>
> **能力分类**（供 Agent 理解"何时用哪类工具"）：
> - **认知层（知识/模板/表）**：`search_knowledge` / `get_knowledge` / `search_sql_templates` / `get_sql_template` / `search_tables` / `get_table` / `get_table_relations` / `search_pangu`（统一搜索）/ `diagnose_context`（组合诊断）
> - **日志能力**：`obs_sls_query` / `obs_sls_targets`（国内公有云盘古 prod/dev/test，阿里云 SLS）/ `obs_log_query` / `obs_log_trace` / `obs_log_datasources`（AWS 海外，Loki）
> - **数据能力**：`archery_query` / `archery_describe_table` / `archery_list_columns` / `archery_query_tenant` / `archery_list_databases` / `archery_list_instances`
> - **ES 只读能力**：`es_search` / `es_count` / `es_get`（prod/dev/test，未配置时返回明确降级提示）
> - **业务系统能力**：`choerodon_*` 系列（猪齿鱼协作，以只读查询为主，评论新增、编辑和删除为需授权的写操作）
> - **代码与脚本能力**：`search_repo`（本地跨仓搜索）+ `search_adapter_scripts` / `search_standalone_scripts`（只发现脚本身份）+ 已知路径的 `gitlab_list_branches/list_tree/get_file` 精确读取。当前脚本正文统一由 Script Platform MCP 获取；GitLab 项目/代码搜索默认禁用。
>
> **只读/写边界（安全）**：日志查询、Schema/数据查询、猪齿鱼查询类（`choerodon_*_issue` / `choerodon_list_*` / `choerodon_search_*` / `choerodon_get_*` / `choerodon_download_*`）、代码检索为**只读**，Agent 可自主调用。`archery_query` 的用户 SQL 允许单条 `SELECT`、`EXPLAIN SELECT`、`SHOW CREATE TABLE`；SELECT 支持 `CASE WHEN` 表达式、`IN (...)` / `NOT IN (...)` 值列表，以及 `COUNT`、`SUM`、`AVG`、`MIN`、`MAX`、`IFNULL`、`NULLIF`、`CONCAT`、`CONCAT_WS`、`CAST`。不支持其它 `SHOW/DESC`、`WITH`、子查询、多语句、注释、窗口函数、集合运算或任何写入语法；实例/库/表结构由专用工具提供。任何生产 INSERT/UPDATE/DELETE **不在本 MCP 提供**，统一由 Skill 生成 SQL 后交用户人工确认执行。认知层的 `search_*` / `get_*` / `diagnose_context` / `list_sql_templates` 为只读；`save_*`、`update_*`、`delete_*`、`add_table_relation`、`upsert_table_knowledge` 和使用统计工具会写入 knowledge_docs / sql_templates / table_catalog / table_relations 元数据，不影响业务数据，调用前应确认沉淀内容。`choerodon_add_comment`、`choerodon_update_comment` 和 `choerodon_delete_comment` 会真实修改猪齿鱼评论，须先确认完整最终正文或删除目标；新增/编辑正文传规范 Markdown，由工具渲染为 HTML。

甄云盘古通用工具 MCP，供任意 MCP 客户端（Claude Desktop / Cursor / 各类 agent）复用。

跨 agent 接入、通用导出命令和本轮协作优化见 [WORKFLOW_OPTIMIZATION.md](WORKFLOW_OPTIMIZATION.md)。

猪齿鱼评论格式说明：`choerodon_add_comment` / `choerodon_update_comment` 接收规范 Markdown，但接口写入的
`commentText` 是统一渲染后的 HTML 富文本。Markdown 表格会转换为 `<table>`，代码块
会转换为 `<pre><code class="language-xxx">`；因此从评论区复制代码时不会带回 Markdown
的 ``` 围栏，这是浏览器复制 HTML 内容的正常表现。不要在同一条评论中手工拼接 HTML 和
Markdown，否则编辑器二次解析时可能出现表格或代码块样式互相覆盖。

**完全自包含**：不依赖任何外部项目目录，仅需在 `.env` 配置真实凭据即可使用。

## 能力总览

工具按前缀/能力分组（旧脚本正文工具默认隐藏；实时清单可用 `get_workflow_guide(topic="capabilities")` 查看）：

| 前缀 | 工具 | 说明 |
|------|------|------|
| 协作协议 | `get_workflow_guide` | 需求/排障/修复/知识/证据交接的按需指引；本地读取，零业务调用，适用于未加载技能的 MCP 客户端 |
| `knowledge`（认知层） | `search_knowledge` / `get_knowledge` | 业务知识/排查经验：混合检索（语义+关键词）+ 详情（沉淀于 knowledge_docs） |
| `template`（行动层） | `search_sql_templates` / `get_sql_template` / `list_sql_templates` | 可复用 SQL/修复模板：混合检索 + 详情 + 总览（沉淀于 sql_templates） |
| `table`（事实层） | `search_tables` / `get_table` / `get_table_relations` | 表目录 + 关联关系（沉淀于 table_catalog / table_relations） |
| `search_pangu` | `search_pangu` | 统一搜索：一次检索 知识 + 模板 + 表 + 关系 |
| `diagnose_context` | `diagnose_context` | 组合诊断：自动汇集 认知 → 模板 → 表 → 关系 的诊断上下文 |
| 知识库维护写操作 | `save_knowledge` / `update_knowledge` / `delete_knowledge` / `save_sql_template` / `list_sql_templates` / `update_sql_template` / `delete_sql_template` / `record_template_usage` / `add_table_relation` / `record_table_usage` / `upsert_table_knowledge` | 沉淀、维护知识/模板/表目录/关联关系；仅写认知层元数据，不修改业务库 |
| `obs_*` | `obs_sls_query` / `obs_sls_targets` / `obs_log_query` / `obs_log_trace` / `obs_log_datasources` | 日志能力：阿里云 SLS（国内公有云盘古 prod + 非生产 dev/test 全覆盖）+ Loki（仅 AWS 海外全环境） |
| `archery_*` | `archery_query` / `archery_describe_table` / `archery_list_columns` / `archery_query_tenant` / `archery_list_databases` / `archery_list_instances` | 数据能力（Archery 双站点 cn/aws + 盘古专属租户/库/实例能力）；`archery_query_tenant` 必须传 tenant，不支持空参列举 |
| `es_*` | `es_search` / `es_count` / `es_get` | 工作台 ES 的 prod/dev/test 只读查询；禁止写入，单次最多返回 `ES_MAX_SIZE` 条 |
| 脚本身份发现 | `search_adapter_scripts` / `search_standalone_scripts` | 只按租户、服务、编码或描述发现候选；命中后使用 `zhenyun-script-platform-mcp` 的 `adapter_get` / `independent_script_get` 读取权威当前态 |
| `choerodon_*` | `choerodon_list_projects` / `choerodon_query_issue` / `choerodon_list_issue` / `choerodon_search_users` / `choerodon_get_status_map` / `choerodon_search_tasks_by_person` / `choerodon_list_attachments` / `choerodon_download_attachment` / `choerodon_list_comments` / `choerodon_preview_comment` / `choerodon_add_comment` / `choerodon_update_comment` / `choerodon_delete_comment` | 业务系统能力：猪齿鱼协作；评论预览为离线只读，新增、按版本编辑和删除是写操作，需明确授权并预览完整内容 |
| `gitlab_*` | `gitlab_get_file` / `gitlab_list_tree` / `gitlab_list_branches` | 仅对已知 project/ref/path 做精确读取；`gitlab_search_projects/code` 默认不注册，避免失败后回退 |
| `search_repo` | `search_repo` | 普通代码检索的默认入口：跨本地代码仓库搜索（内容 / 文件名 / 模块结构） |

旧 `get/search_*_script_source` Python 实现暂时保留作紧急回滚，但默认不注册为 MCP 工具，避免
与 Script Platform MCP 形成两个正文来源。只有显式设置
`PANGU_EXPOSE_LEGACY_SCRIPT_READ_TOOLS=true` 才临时暴露；常规 Agent/Skill 不得依赖该开关。

## 知识库工具使用指南

认知层存放的是可复用的稳定知识和目录元数据，不是生产实时事实。调用顺序按问题类型选择：

| 你要解决的问题 | 首选工具 | 下一步 |
|---|---|---|
| 不知道某个业务规则、状态、机制是否已有结论 | `search_knowledge` | 用结果 `id` 调 `get_knowledge`；没有命中且结论已确认时再 `save_knowledge` |
| 处理排障或复杂 SQL，尚不清楚要查什么 | `diagnose_context` | 按返回的知识/模板/表/关系，分别调用专项工具和实时日志/Archery |
| 不知道真实表名或业务描述对应哪些表 | `search_tables` | 用表名调 `get_table`/`get_table_relations`，字段存在性再调 Archery |
| 想复用以前的查询/修复方案 | `search_sql_templates` | 用模板 `id` 调 `get_sql_template`；实际复用后调 `record_template_usage` |
| 只知道一句跨域关键词，想快速发现线索 | `search_pangu` | 这是关键词发现，不替代专项检索和实时数据查询 |

认知层与实时事实的边界：`search_knowledge`/`get_knowledge` 回答“业务和机制是什么”；
`search_sql_templates`/`get_sql_template` 回答“以前怎么处理”；`search_tables`/`get_table`/
`get_table_relations` 提供目录注释和已沉淀关系。当前日志、数据、DDL、字段存在性必须分别使用
`obs_*`、`archery_query`、`archery_describe_table`/`archery_list_columns`，不能仅凭知识库内容下结论。

知识库写工具会修改 Supabase 认知层元数据，不会执行模板 SQL，也不会修改业务数据库；除统计工具外，
调用前应先向用户确认要写入的内容：

- `save_knowledge(title, content_md, ...)`：沉淀已确认的规则、机制、排查结论或数据模型说明。
  `content_md` 使用规范 Markdown；`core_tables`、`tags`、`related_template_ids` 为逗号分隔字符串；
  默认 `status=draft`，核验后再标 `verified`。
- `update_knowledge(doc_id, ...)`：只修改明确传入的字段，适合修正正文/标题/归类、把核验过的
  知识标为 verified（`verified_at` 自动写入）或将过时知识标 `deprecated/archived`；修改正文等
  影响语义检索的字段时会自动重新生成 embedding。过时但仍有参考价值的知识优先置
  `deprecated/archived`，避免直接删除丢失上下文。
- `delete_knowledge(doc_id)`：破坏性维护操作，仅清理错误、重复或彻底作废的知识，必须明确确认；
  删除前先 `get_knowledge` 核对 id。
- `save_sql_template(title, category, scenario, sql_text, ...)`：沉淀复杂查询或供人工确认的修复方案。
  `sql_text` 只写入模板库，不会被 MCP 执行；`parameters` 必须是 JSON 对象字符串，例如
  `{"tenant_id":{"type":"bigint","required":true}}`。数据修复模板可保存 `execution_flow`
  和脱敏 `example_case`；排障模板可保存 `problem_description`、`symptom`、`root_cause`、
  `preconditions`、`diagnosis_steps`、`verify_sql`、`rollback_sql`。
- `list_sql_templates(...)`：只读总览；`update_sql_template(id, ...)`：只修改明确传入的字段，
  适合纠正模板或补充验证标记；`delete_sql_template(id)` 是破坏性维护操作，必须明确确认。
- `add_table_relation(...)`：仅在 Archery/SELECT 验证 join 后沉淀关系，`join_on` 例如
  `a.order_id = b.order_id`，`confidence` 为 0~1；`upsert_table_knowledge(...)`：在 Archery
  确认表真实存在后补录/修正目录描述和标签。两者都不创建外键、不改业务表。
- `record_template_usage(id)` 和 `record_table_usage("a,b")`：仅在实际复用模板/使用表后记录统计，
  不要为了提高排序而虚增计数。

推荐的最小工作流：

```text
问题/排障 → diagnose_context 或 search_knowledge
          → get_knowledge / search_sql_templates / search_tables
          → Archery / 日志工具确认当前事实
          → 输出结果；确认后才 save_knowledge/save_sql_template
          → 实际复用后 record_template_usage/record_table_usage
```

## 日志平台区分（重要）

盘古日志分布在两个平台，查询前需先确认目标环境落在哪个平台：

| 能力 | 环境 | 平台 | 数据源 / project | 标签体系 |
|------|------|------|------------------|----------|
| `obs_sls_query` | **cn 国内盘古 `prod`** | 阿里云 SLS | `pangu-cn-saas-3-prod-shared-sls-project-0` / `sls-store-0-pangu-prod` | `_namespace_` = `saas-prod` |
| `obs_sls_query` | **cn 国内盘古 `dev` / `test`（非生产）** | 阿里云 SLS | `pangu-cn-saas-3-nonprod-shared-sls-project-0` / `sls-store-0-pangu-nonprod` | `_namespace_` = `saas-dev-new` / `saas-test-new` |
| `obs_log_query` | AWS 海外（全部环境） | Grafana/Loki | `Jp-saas-1-prod` / `Jp-saas-1-noneprod` / `ops` | `job` / `app` |

- **国内公有云（cn）盘古全部环境（`prod` / `dev` / `test`）都是阿里云 SLS**，一律用 `obs_sls_query(environment=...)`；`system`/`environment` 到 project/logstore/namespace 的映射由 MCP 完成，调用方不接触 AccessKey。
- **AWS 海外（jp-saas-1，无论 prod/非生产）**用 `obs_log_query(region="aws")`。
- ⚠️ 路由铁律：**国内盘古（含非生产）走 SLS，只有 AWS 海外走 Loki**。`obs_log_*` 已不接受 `region="cn"`（会返回「请改用 obs_sls_query」的提示）；盘古非生产不要调 `obs_log_query`。
- 变迁记录：盘古非生产曾短暂迁移到 Loki（`logs.going-link.net`），现已迁回阿里云 SLS，相关 `LOKI_API_BASE_CN` / `CN_LOG_*` / `CN_LOG_DS_*` 配置已移除。

**常用参数提示**：

- `obs_sls_query(environment="prod"|"dev"|"test", trace_id=..., keyword=..., level="ERROR"|"", container_name=...)`：`trace_id` 走「ERROR/WARN + 全链路」两阶段查询；`keyword` 传 SLS 查询子句（会与 `_namespace_` 过滤组合）；二开排障传 `container_name="srm-script-container"`，把 traceId 或关键字检索限制在脚本容器。
- 时间：`time_range` 支持 `最近30分钟` / `最近2小时` / `最近3天` / `今天` / `昨天` / `本周` / `上月`，或 `30m` / `2h` / `1d`，或 `YYYY-MM-DD HH:mm~HH:mm`（北京时间）。
- `auto_expand`（默认 true）：未显式指定时间窗且 0 命中时，自动扩到最近 24h、72h 各重试一次，实际窗口见 `meta.attempted_windows`。
- 不确定支持哪些环境时，用 `obs_sls_targets()` 列出真实映射；AWS 侧用 `obs_log_datasources(region="aws")` 列出真实数据源名。

> 两个平台的凭据（SLS AccessKey / Grafana 账号密码）均在 `.env` 独立配置，详见 `.env.example`。

## 安装与运行

```bash
cd zhenyun-pangu-mcp
uv sync
cp .env.example .env   # 填写真实凭据
```

运行测试（统一通过 uv 管理解释器和依赖）：

```bash
uv sync --dev
uv run pytest -q
```

以 stdio 运行：

```bash
uv run zhenyun-pangu-mcp
# 或
uv run python -m zhenyun_pangu_mcp
```

## 语义向量（Cloudflare Workers AI）

语义检索统一使用 Cloudflare Workers AI 的 `@cf/qwen/qwen3-embedding-0.6b`（1024 维），
向量写入单列 `embedding`（`vector(1024)`）。免费层每天 10,000 Neurons，对本知识库规模足够。

历史说明：早期支持 NVIDIA / Voyage 双 provider 并预留 `embedding_voyage` 双列做 A/B 对比。
`nvidia/nv-embed-v1` 已被官方下线（410），Voyage 免费额度限速（3 RPM / 10K TPM）不适合批量回填，
故整体切换到 Cloudflare Workers AI；双列设计与 `*_voyage` 检索 RPC 均已废弃，向量列维度由 2048 改为 1024。

回填 / 重建向量（默认只处理 `embedding IS NULL` 的行，支持断点续跑）：

```bash
uv run python scripts/rebuild_embeddings.py --table all --batch-size 50
uv run python scripts/rebuild_embeddings.py --table knowledge_docs --limit 20
```

换模型或需要全量覆盖重算时加 `--force`（会覆盖该表全部已有向量）。
未配置 `CF_API_TOKEN` / `CF_ACCOUNT_ID` 时，检索自动降级为关键词检索（不报错，但召回率下降）。

## 打包为 Codex 插件

工作区中的 `custom-skills/`、本 MCP 与独立的 `zhenyun-script-platform-mcp` 已打包为个人插件
`zhenyun-pangu-toolkit`。
修改任意 skill 或 MCP 源码后，在本目录执行：

```bash
./scripts/update_codex_plugin.sh
```

脚本会先校验全部 Skill、运行 MCP 全量测试和 Skill↔MCP 合同检查，再同步源文件、
更新 Codex cachebuster，并重新安装个人 marketplace 中的插件；
完成后新建 Codex task 以加载最新版本。同步过程不会复制 `.env`、`.venv` 或本地 token 缓存。

## MCP 客户端配置

```json
{
  "mcpServers": {
    "zhenyun-pangu-mcp": {
      "command": "uvx",
      "args": ["--from", "/path/to/zhenyun-pangu-mcp", "zhenyun-pangu-mcp"],
      "env": {
        "MCP_ENV_DIR": "/path/to/zhenyun-pangu-mcp"
      }
    }
  }
}
```

## 配置项（`.env`）

| 分组 | 环境变量 | 说明 |
|------|----------|------|
| Archery | `ARCHERY_USERNAME` / `ARCHERY_PASSWORD` / `ARCHERY_AWS_USERNAME` / `ARCHERY_AWS_PASSWORD` | 数据库网关 cn/aws 凭据 |
| | `ARCHERY_DB_CN` / `ARCHERY_DB_AWS` / `ARCHERY_DB_DEV` / `ARCHERY_DB_TEST` | 实例别名 → 真实实例名 |
| Loki | `AWS_LOG_USERNAME` / `AWS_LOG_PASSWORD` | Grafana 登录凭据（仅 AWS 海外） |
| | `AWS_LOG_DS_*` | 环境 → 数据源名映射（AWS 海外） |
| Choerodon | `CHOERODON_BASE_URL` / `CHOERODON_USERNAME` / `CHOERODON_PASSWORD` | 猪齿鱼网关与登录凭据 |
| SLS | `SLS_PANGU_PROD_ACCESS_KEY_ID` / `SLS_PANGU_PROD_ACCESS_KEY_SECRET` | 盘古 prod 阿里云日志凭据 |
| | `SLS_PANGU_NONPROD_ACCESS_KEY_ID` / `SLS_PANGU_NONPROD_ACCESS_KEY_SECRET` | 盘古非生产（dev/test）阿里云日志凭据 |
| GitLab | `GITLAB_BASE_URL` / `GITLAB_TOKEN`（或 `GITLAB_USERNAME`/`GITLAB_PASSWORD`） | GitLab 仓库地址与凭据 |
| | `GITLAB_SEARCH_ENABLED` | 默认 `false`，不注册不可用的 GitLab 项目/代码搜索；仅平台能力恢复后显式开启 |
| | `GITLAB_SEARCH_ROOT_ID` / `GITLAB_SEARCH_ROOT_GROUP` | 代码搜索根目录（限定 group/project，避免全站噪声） |
| 脚本发现/兼容 | `PANGU_EXPOSE_LEGACY_SCRIPT_READ_TOOLS` | 默认 `false`，只暴露两项身份发现工具；仅紧急回滚时临时开启旧正文工具 |
| | `ADAPTER_SCRIPT_CACHE_*` / `ADAPTER_SCRIPT_*_LINES` / `ADAPTER_SCRIPT_MAX_RANGE_CHARS` | 仅旧正文工具启用时使用的解码缓存与返回范围配置 |
| Embedding | `CF_API_TOKEN` / `CF_ACCOUNT_ID` / `CF_EMBED_MODEL` / `CF_EMBEDDING_DIMENSION` | Cloudflare Workers AI 凭据（默认 `@cf/qwen/qwen3-embedding-0.6b` / 1024 维），向量写单列 `embedding`；未配置时语义检索降级为关键词 |
| 其他 | `PG_ROOT` | 本地跨仓搜索根目录（默认本仓库根） |

> 凭据请勿提交 git；`.env` 已由 `.gitignore` 排除，仅 `.env.example`（占位符版）入库。

## 输出与错误规范（Agent 可据此判断）

**成功返回**：结构化工具返回 JSON 字符串，认知层工具按设计返回可读 Markdown。结构化结果尽量包含 `summary / total / results` 等摘要 + 关键结果，避免一次性返回数千行吃 Agent Context：
- 日志查询：`obs_log_query` / `obs_log_trace` 返回 `total`（命中总数）+ 截断后的 `results`（按 `limit`），`obs_log_trace` 附 `meta.error_count / warn_count`，可用 `level=error` 省 token。
- 数据查询：`archery_query` 返回行集与数量；查询大结果集建议缩小 `limit` 或用更精准 WHERE。
- 脚本查询：Pangu 只返回 Adapter/Independent Script 候选身份；命中后用 Script Platform MCP 的
  `adapter_get` / `independent_script_get` 获取当前正文、版本和 Fixture。

**失败返回**：结构化工具返回 `{"ok": false, "error": {"code": "...", "message": "...", "retryable": true|false}}`；认知层工具按设计返回可读 Markdown。Archery/SLS 的参数错误和缺失配置返回 `retryable=false`，需要先修正输入或配置；网络等临时后端错误可能为 `true`。空结果是成功响应，不代表工具失败。

Archery 工具的 `site` Schema 限定为 `cn` / `aws`，默认 `cn`；省略 `instance` 使用该站点的默认实例。`archery_query_tenant` 的 `tenant` 是必填参数。ES 环境和 `search_repo.mode` 也通过 Schema 暴露为有限选项，客户端可在调用前校验常见拼写错误。