# 数据魔方skill

**Repository Path**: wyerp/data-magic-skill

## Basic Information

- **Project Name**: 数据魔方skill
- **Description**: 数据魔方skill
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-08-09
- **Last Updated**: 2026-08-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 数据魔方 Skill 与 MCP

这个仓库现在回归为 **skill 和 MCP 分开维护** 的本地开发项目，不再按 Codex 插件 marketplace 方式打包发布。

- `skills/data-magic-skill/`：沉淀数据魔方 / 预测 / 预策的平台规则，让 Codex 知道如何写 SQL、ETL、自定义图表、文本组件、分析流程文档，以及如何处理字段类型、画布排版和知识库沉淀。
- `mcp-server/`：本地 MCP 服务源码，把数据魔方平台接口封装成工具，用于读取或操作分析画布、节点、字段、SQL 节点、ETL、数据源和仪表盘组件。
- `业务知识库/`：保存当前项目/当前组织的业务口径、指标解释、分析经验和历史排查结论。
- `数据源知识库/`：保存当前项目/当前组织的数据源字段、数据源用途、维表关系和字段匹配方式。

`skill` 负责规则和判断，`MCP` 负责可执行的平台操作。两者可以一起使用，但不再打成一个插件包。

## 目录分工

```text
skills/data-magic-skill/             # 通用 skill 源码，长期维护
mcp-server/                          # MCP 服务源码，长期维护
业务知识库/                          # 本地业务知识，不写进通用 skill
数据源知识库/                        # 本地数据源知识，不写进通用 skill
template/                            # 自定义图表 / 文本组件教学模板
sql/                                 # 平台 SQL 教学样例
数据魔方接口请求示例/                # 接口样例和历史抓取资料
exports/、输出/、analysis-results/   # 临时导出和分析产物
```

旧插件发布目录和 marketplace 入口已经废弃。后续不要再维护 `plugins/data-magic/`、`.agents/plugins/marketplace.json` 或 `.codex-plugin/`。

## 使用 Skill

当前项目内的 skill 源码在：

```text
skills/data-magic-skill/
```

如果要让 Codex 全局使用最新版，可以把该目录同步到用户级 skill 目录：

```powershell
robocopy .\skills\data-magic-skill "$env:USERPROFILE\.codex\skills\data-magic-skill" /MIR
```

更新 skill 时，优先修改当前项目的 `skills/data-magic-skill/`。如果希望后续会话立即使用最新版，再同步到全局 skill 目录。

## 使用 MCP

MCP 独立使用，不依赖插件。开发和调试时进入 MCP 目录：

```powershell
Set-Location .\mcp-server
npm install
npm start
```

在 Codex 配置里单独添加 MCP 服务即可，路径按本机项目位置填写：

```toml
[mcp_servers.data-magic]
type = "stdio"
command = "node"
args = ['<repo-path>\mcp-server\index.js']
```

如果在本仓库直接使用，可以参考根目录 `.mcp.json` 的本地配置：

```json
{
  "mcpServers": {
    "data-magic": {
      "type": "stdio",
      "command": "node",
      "args": [
        "mcp-server/index.js"
      ]
    }
  }
}
```

### AI Agent 固定调用入口

所有 AI Agent（Codex、Claude Code、OpenCode 或其他工具）在本项目里给某个分析写流程文档时，应优先直接调用 MCP：

```text
get_analysis_document_context(projectId)
```

该工具是只读聚合入口，只传分析 ID 即可返回分析概览、结果候选、结果链、Mermaid 流程图、节点字段摘要、操作详情摘要、计算列公式摘要和 `markdownDraft` 自动草稿。不要先拉 `get_project_graphs`、字段列表、节点详情等 raw 回包再创建临时文件离线拼接；只有需要完整 SQL、解析失败或人工核验原始响应时，才补传 `sqlMode=full`、`includeRaw=true` 或继续调用细粒度工具。

## 设置登录 Cookie

MCP 不包含任何人的登录态。第一次调用数据魔方接口前，需要使用 MCP 的 `set_cookies` 工具写入自己的登录 cookie；可选传入 URL 中的 `token` 参数。

cookie 默认保存到：

```text
%APPDATA%\data-magic-mcp\.data-magic-cookies.json
```

也可以通过环境变量 `DATA_MAGIC_MCP_HOME` 指定保存目录。该文件包含登录信息，不能提交到 Git。

## 持续维护

- 新的平台规则、踩坑经验、SQL 约定、组件模板写法：写入 `skills/data-magic-skill/SKILL.md` 或 `skills/data-magic-skill/references/`。
- 新的可复用平台操作：写入 `mcp-server/`，优先做成 MCP 工具，而不是保留一次性脚本。
- AI Agent 使用 MCP 时遇到的工具不好用、缺能力、超时、返回难解析或 temp 绕路问题：记录到 `mcp-server/MCP_ISSUES.md`，并区分 `codex_desktop`、`codex_cli`、`claude_code`、`opencode` 等运行入口；高频问题优先改 MCP。
- 当前项目的业务口径、数据源字段和匹配关系：分别写入 `业务知识库/` 和 `数据源知识库/`，不要污染通用 skill 或 MCP。
- 临时参数、导出结果、历史排查文件：尽量放到临时目录或本地资料目录，不要混入长期维护入口。

## 已废弃内容

以下内容属于旧的插件化方案，后续不再维护：

- Codex marketplace 插件入口：`.agents/plugins/marketplace.json`
- 插件 manifest：`.codex-plugin/plugin.json`
- 插件发布副本：`plugins/data-magic/`
- MCP bundle 发布产物：`plugins/data-magic/mcp-server/index.mjs`

如果未来重新评估插件方案，应单独开新方案说明，不要把旧发布流程直接恢复。