zhenyun-pangu-mcp

架构定位：盘古「实时接口」

在四层架构中，本 MCP 是 Knowledge / Skill / Template 之外的唯一"实时事实"来源：

层	回答什么	载体
Skill	这个任务应该怎么做	custom-skills/ 的 SKILL.md（编排流程）
Knowledge	业务/系统/字段是什么	本 MCP 的 knowledge_base/（稳定事实，沉淀于 knowledge_docs）
Template	以前类似问题怎么解决	本 MCP 的 knowledge_base/（SQL 模板，沉淀于 sql_templates）
zhenyun-pangu-mcp	现在生产环境真实是什么/发生了什么	本 MCP（日志 / 数据 / 猪齿鱼 / 代码）

边界原则：

• 所有可能变化的实时事实（当前日志、当前数据、当前 Schema、当前状态、当前服务状态）一律走本 MCP。

• 静态知识（Skill Markdown / Knowledge / Template）只负责帮助 Agent 理解这些实时数据意味着什么，不替代实时查询。

• 旧的独立 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

• 业务系统能力：choerodon_* 系列（猪齿鱼协作，以只读查询为主，choerodon_add_comment 为需确认的写操作）

• 代码与脚本能力：search_repo（本地跨仓搜索）+ *_adapter_script*（数据库脚本发现、服务端解码、搜索与局部读取）+ 已知路径的 gitlab_list_branches/list_tree/get_file 精确读取。当前 GitLab 项目/代码搜索默认禁用。

只读/写边界（安全）：日志查询、Schema/数据查询、猪齿鱼查询类（choerodon_*_issue / choerodon_list_* / choerodon_search_* / choerodon_get_* / choerodon_download_*）、代码检索为只读，Agent 可自主调用。archery_query 的用户 SQL 只允许单条基础 SELECT、EXPLAIN SELECT 或 SHOW CREATE TABLE，不支持其它 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 会真实写入猪齿鱼评论，必须先确认内容；评论必须传规范 Markdown，禁止纯文本和原始 HTML，工具会负责 Markdown 渲染。

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

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

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

能力总览

工具按前缀/能力分组（默认共 48 个；GitLab 搜索开启后增加 2 个）：

知识库工具使用指南

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

认知层与实时事实的边界：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}}。

• 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")：仅在实际复用模板/使用表后记录统计， 不要为了提高排序而虚增计数。

推荐的最小工作流：

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

日志平台区分（重要）

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

• 国内公有云（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"|"" )：trace_id 走「ERROR/WARN + 全链路」两阶段查询；keyword 传 SLS 查询子句（会与 _namespace_ 过滤组合）。

• 时间：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。

安装与运行

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

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

uv sync --dev
uv run pytest -q

以 stdio 运行：

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 的行，支持断点续跑）：

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-pangu-toolkit。 修改任意 skill 或 MCP 源码后，在本目录执行：

./scripts/update_codex_plugin.sh

脚本会同步源文件、更新 Codex cachebuster，并重新安装个人 marketplace 中的插件； 完成后新建 Codex task 以加载最新版本。同步过程不会复制 .env、.venv 或本地 token 缓存。

MCP 客户端配置

{
  "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）

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

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

成功返回：各工具返回 JSON 字符串，尽量包含 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。

• 脚本查询：元信息查询不读取正文；源码 Tool 只返回解码后的 JavaScript，并附 DB/decode/cache/结果准备耗时。定位具体字段或函数时优先搜索正文和局部读取。

失败返回：工具异常一律返回 {"error": "<原因>"} 的 JSON 字符串，不抛 500。常见原因：

• 参数错误：site/instance/db/query 取值非法（如未知 region）。

• 权限错误：Archery/Grafana/SLS 凭据缺失、过期或无权。

• 连接错误 / 查询超时：网络或时间窗过宽（缩小时间范围重试）。

• 数据不存在：查询无结果。

Agent 应根据 error 字段判断失败原因并调整参数后重试，不要用相同参数原样重调。