@wubaoqi/guancopilot 0.0.0-stage → 0.2.0

package/skills-bundle/guanmetric/references/metric-hierarchy-api-contracts.md

@@ -0,0 +1,193 @@
+# 指标主题与指标目录 CRUD API 契约
+
+本文供 Agent 创建和维护指标体系的组织骨架。真实脱敏样例见
+`metric-hierarchy-api-contract-examples.json`，机器可读约束见
+`metric-hierarchy-api-contract.schema.json`。
+
+## 证据与边界
+
+- 2026-09-21 在 test71 使用隔离临时主题和目录完成 create、edit、detail/list/tree、delete 全链路实测。
+- test71 实测使用 `robot@guandata.com` 的账号密码登录态。按本次范围不再创建 PAT；PAT 对照尚未验证，发布或 MR 的 `Domain and Contract` 不能将 PAT 兼容性标记为已通过。
+- 临时目录和主题均在采集完成后删除，没有保留测试资源。
+- 样例保留真实字段、空值和响应形态，ID、Domain 和名称已脱敏，不能直接用于真实调用。
+- 后端响应可能增加字段，Schema 的响应对象允许 `additionalProperties: true`。
+- 本契约只覆盖 `METRIC_PLATFORM` 指标目录，不可拿去修改 `METRIC_TREE`、`BUSINESS_METRIC` 等其他目录类型。
+- 不包含指标 move 和指标 owner 转移；这是本轮明确排除的范围。
+
+## 命令速查
+
+```bash
+# 主题
+guanmetric project list
+guanmetric project get <project_id>
+guanmetric project create 经营指标 --dry-run
+guanmetric project create 经营指标
+guanmetric project edit <project_id> --name 经营分析指标 --dry-run
+guanmetric project edit <project_id> --name 经营分析指标
+guanmetric project delete <project_id>
+guanmetric project delete <project_id> --confirm
+
+# 指标目录
+guanmetric directory tree <project_id>
+guanmetric directory get <project_id> <dir_id>
+guanmetric directory create 销售分析 --project-id <project_id> --dry-run
+guanmetric directory create 销售分析 --project-id <project_id>
+guanmetric directory edit <project_id> <dir_id> --name 销售经营分析 --dry-run
+guanmetric directory edit <project_id> <dir_id> --name 销售经营分析
+guanmetric directory delete <project_id> <dir_id>
+guanmetric directory delete <project_id> <dir_id> --confirm
+```
+
+旧命令 `project-create` 和 `dir-create` 为兼容保留。新流程优先使用分组命令，便于发现完整 CRUD。
+
+## 接口矩阵
+
+| 资源 | 操作 | 客户端方法与路径 | 权限 |
+| --- | --- | --- | --- |
+| Project | create | `POST /api/metric-platform/projects` | `METRIC_PLATFORM.CREATE` |
+| Project | update | `POST /api/metric-platform/projects/{id}` | `METRIC_PLATFORM.UPDATE` |
+| Project | detail | `GET /api/metric-platform/projects/{id}` | `METRIC_PLATFORM.READ` |
+| Project | list | `GET /api/metric-platform/projects` | `METRIC_PLATFORM.READ` |
+| Project | delete | `POST /api/metric-platform/projects/delete/{id}` | `METRIC_PLATFORM.DELETE` |
+| Directory | create | `POST /api/metric-platform/directory/create` | `METRIC_PLATFORM.CREATE` |
+| Directory | update | `POST /api/metric-platform/directory/{id}/update` | `METRIC_PLATFORM.UPDATE` |
+| Directory | tree/read | `GET /api/directory/METRIC_PLATFORM/unauthorized-tree?projectId={id}` | `BASE.READ` |
+| Directory | delete | `POST /api/metric-platform/directory/{id}/delete` | `METRIC_PLATFORM.DELETE` |
+
+以上是客户端真实路径；后端 Spring 路由是去掉 `/api` 后的同路径。新增写调用需要在正式交付前完成同一用户、同一 Domain 下账号密码与 PAT 对照验证。本次按用户选择只使用账号密码，因此 PAT 仍是明确的待验证门禁，不能由单元测试或账密实测替代。
+
+## Project 写模型
+
+创建和更新使用同一完整写模型：
+
+```json
+{
+  "name": "经营分析指标",
+  "icon": "binoculars_subject",
+  "iconColor": "#799BFF"
+}
+```
+
+更新不是自由 patch。`guanmetric project edit` 先读取详情，只从详情白名单提取
+`name/icon/iconColor`，再合并命令行修改；`id/domId/dirId/canManage/canUse` 是读模型字段，不能原样提交。
+
+创建和更新成功响应相同：
+
+```json
+{"result":"ok","response":{"id":"project_example"}}
+```
+
+只收到 HTTP 2xx 但 `result` 不为 `ok`，或 `response.id` 为空，不能认为成功。CLI 会在创建/编辑后回读详情，校验 `name/icon/iconColor` 与请求一致。
+
+## Project 详情与列表
+
+详情的真实结构：
+
+```json
+{
+  "result": "ok",
+  "response": {
+    "id": "project_example",
+    "domId": "example_domain",
+    "name": "经营分析指标",
+    "icon": "binoculars_subject",
+    "iconColor": "#799BFF",
+    "dirId": "dir_project_root",
+    "canManage": true,
+    "canUse": true
+  }
+}
+```
+
+列表的 `response` 是上述对象数组。`dirId` 是该主题对应的根目录 ID，创建一级指标目录时应把它作为 `parentDirId`。不要把主题 `id` 当目录 ID。
+
+删除成功响应是字符串：
+
+```json
+{"result":"ok","response":"delete success."}
+```
+
+主题删除没有独立影响预检接口。CLI 默认只回读并展示目标；只有 `--confirm` 才提交，资源依赖和最终可删性由后端裁决。
+
+## Directory 写模型
+
+创建和更新都使用完整 `DirectoryAPI` 子集：
+
+```json
+{
+  "name": "销售经营分析",
+  "parentDirId": "dir_project_root",
+  "dirType": "METRIC_PLATFORM"
+}
+```
+
+三个字段均不可省略。更新目录时，即使只改名称，也必须保留当前 `parentDirId` 和固定的
+`dirType=METRIC_PLATFORM`。`guanmetric directory edit` 会先读取目录树并显式构造写模型，禁止把树节点详情直接提交。
+
+创建/更新响应不是只有 ID，而是目录路径对象：
+
+```json
+{
+  "result": "ok",
+  "response": {
+    "dirId": "dir_sales",
+    "dirName": "销售经营分析",
+    "dirType": "METRIC_PLATFORM",
+    "parentDirId": "dir_project_root",
+    "parentDirName": "经营分析指标",
+    "dirPath": [
+      {"dirId":"dir_global_root","dirName":"根目录"},
+      {"dirId":"dir_project_root","dirName":"经营分析指标"},
+      {"dirId":"dir_sales","dirName":"销售经营分析"}
+    ]
+  }
+}
+```
+
+CLI 在创建/编辑前校验父目录属于指定 Project 的 `METRIC_PLATFORM` 树，并在写后重新读取目录树，确认名称和父目录均与请求一致。不能把目录移动到自身或自己的子目录。
+
+## Directory 的“详情”来自目录树
+
+后端没有指标目录单条详情接口。权威读取接口返回整个 Project 的目录树：
+
+```http
+GET /api/directory/METRIC_PLATFORM/unauthorized-tree?projectId={projectId}
+```
+
+树节点结构如下：
+
+```json
+{
+  "id": "dir_sales",
+  "parentDirId": "dir_project_root",
+  "name": "销售经营分析",
+  "type": "DIRECTORY",
+  "contents": [],
+  "canManage": true,
+  "canUse": true,
+  "ctime": "2026-09-21T10:15:32.00Z",
+  "utime": "2026-09-21T10:15:48.00Z",
+  "metricCnt": 0,
+  "allMetricCnt": 0
+}
+```
+
+`guanmetric directory get <project_id> <dir_id>` 是客户端从这棵树按 ID 提取节点，不对应新的后端 API。`contents` 递归包含子目录；`metricCnt` 是当前目录指标数，`allMetricCnt` 是包含后代的指标总数。
+
+删除成功响应：
+
+```json
+{"result":"ok","response":"Directory deleted"}
+```
+
+CLI 禁止通过 directory 命令删除 Project 根目录；删除整个主题必须用 `project delete`。普通目录删除默认只展示节点及其子树/指标计数，追加 `--confirm` 才提交；依赖由后端最终校验。
+
+## Agent 使用约束
+
+1. 先创建 Project，再从 Project 详情/列表取得真实根目录 `dirId`。
+2. 创建目录时固定 `dirType=METRIC_PLATFORM`，并校验 `parentDirId` 在该 Project 目录树内。
+3. 编辑只能原地更新，不能删除重建。
+4. Project 更新只提交 `name/icon/iconColor`；Directory 更新只提交 `name/parentDirId/dirType`。
+5. 所有创建和编辑都必须写后回读；HTTP 成功不等于最终状态正确。
+6. 删除必须先展示精确目标，并要求 `--confirm`；不能自行扩展为批量删除。
+7. 本契约不授权指标 move、指标 owner 转移或其他目录类型管理。

package/skills-bundle/guanmetric/references/metric-mutation.md

@@ -0,0 +1,155 @@
+# 指标新建 / 编辑 / 删除指引
+
+本文是指标写操作的入口索引，用于指导 AI 选择应加载的细分文档，避免一次性读取所有指标类型的长配置。当前覆盖原子指标、复合指标、衍生指标的创建/编辑预检查；删除的完整交互流程后续补充。
+
+创建、编辑、详情和列表接口的真实脱敏响应、JSON Schema 及读写模型映射见
+`metric-api-contracts.md`。Agent 构造写请求前应先按该契约选择指标类型和具体变体。
+
+## 读取顺序
+
+处理指标写操作时按需读取：
+
+1. 先读本文，判断指标类型和整体保存流程。
+2. 如果用户提供 Excel/CSV 批量创建指标，先读取 `metric-excel-template.md`，执行标准化并返回标准 Excel 给用户确认；用户确认前停止在转换阶段。
+3. 始终读取 `metric-common-fields.md`，获取当前环境、通用字段、业务属性 `bizAttrs`、发布/校验规则。
+4. 只读取目标类型文档：
+   - 原子指标：`metric-atomic-mutation.md`
+   - 复合指标：`metric-composite-mutation.md`
+   - 衍生指标：`metric-derived-mutation.md`
+   - 删除指标：`metric-delete-mutation.md`
+5. 如果用户意图不明确，先按“类型判断”问清楚，再加载对应类型文档。
+
+## 类型判断
+
+| 用户意图 | 指标类型 | 读取文档 |
+| --- | --- | --- |
+| 基于一个数据集字段求和、计数、平均、最大、最小、去重计数，或用数据集字段公式生成指标 | 原子指标 `ATOMIC` | `metric-atomic-mutation.md` |
+| 用已有指标做公式，例如销售额 / 订单数、A + B、多个指标组合计算 | 复合指标 `COMPOSITE` | `metric-composite-mutation.md` |
+| 同比、环比、最近 N 天/周/月、累计、期末值、业务限定、组合衍生 | 衍生指标 `DERIVED` | `metric-derived-mutation.md` |
+| 删除、移除某个指标 | 通用删除流程 | `metric-delete-mutation.md` |
+
+常见含混说法：
+
+- “新建一个指标，基于某数据集/某字段”：通常是原子指标。
+- “客单价 = 销售额 / 订单数”：通常是复合指标。
+- “用数据集字段计算一个表达式指标”：先按下方“表达式建模确认”询问用户是否改为复合指标。
+- “给销售额做月环比/最近 7 天/本月累计/华东限定”：通常是衍生指标。
+
+## 表达式建模确认
+
+只要用户要创建的是计算表达式指标，不要直接替用户决定用原子表达式还是复合指标。先向用户确认：
+
+```text
+这个指标需要计算表达式。是否希望我先创建/复用表达式中的基础原子指标，再创建一个复合指标？
+如果选择否，我会按数据集字段表达式创建原子指标。
+```
+
+用户选择“是”时：
+
+1. 拆出表达式中的基础度量。
+2. 先搜索是否已有对应基础原子指标；已有则复用。
+3. 缺失基础指标时，先按 `metric-atomic-mutation.md` 创建基础原子指标。
+4. 再按 `metric-composite-mutation.md` 创建复合指标，公式使用 `[metricId]`，不要使用 `[fdId]`。
+
+用户选择“否”或明确要求数据集字段表达式时，才走原子指标 `formulaField.fdFormula`。
+
+## 总体流程
+
+1. 使用当前已登录环境，不主动询问 profile；写操作前可执行 `guancli auth status`。
+2. 若输入是客户 Excel/CSV，先执行：
+
+```bash
+guanmetric template normalize <input.xlsx> --check-only --output json-v1
+guanmetric template normalize <input.xlsx> --out <standard.xlsx> --report <report.json>
+```
+
+   check-only 不写文件也不执行指标写操作；先按 diagnostics 的 Sheet/行/列和稳定错误码修正。通过后把普通 normalize 生成的标准 Excel 返回给用户确认，并摘要列映射、剔除列、自动填充字段、ID 自动解析结果、可创建/待确认/错误行数。标准化阶段不自动创建主题、目录或指标；找不到或多候选的主题/目录写入 `问题说明`。用户确认标准 Excel 前，不生成最终创建 payload，不执行 dry-run/precheck，不真实提交。若用户修改标准 Excel 后再次传回，重复执行标准化流程，直到所有行都是 `可创建`。
+3. 信息不全时先查 ID，不凭空猜：
+   - 指标主题：`guancli metric project [keyword] -f json`
+   - 指标目录：`guancli metric tree -f json`
+   - 新建指标主题：`guanmetric project create <name> --dry-run`，确认后去掉 `--dry-run`
+   - 新建指标目录：`guanmetric directory create <name> --project-id <metric_topic_id> --dry-run`，确认后去掉 `--dry-run`。创建子目录可传 `--parent-dir-id`
+   - 指标详情：`guancli metric search <keyword> -f json`、`guancli metric get <metric_id> --brief`
+   - 数据集字段：`guancli ds search <keyword>`、`guancli ds get <dsId> --brief`
+4. 如果输入来自标准模板，按 `metric-excel-template.md` 的“创建阶段读取规则”生成 payload：
+   - `指标主题ID/名称`、`指标目录ID/路径`、`数据集ID/名称` 都按 ID 优先、名称或路径兜底解析；不要因为 ID 列为空就直接失败。
+   - 原子指标如果填写 `字段表达式`，生成 `formulaField.fdFormula`，且不要同时传 `fdId/aggrType`。
+   - 原子指标如果填写 `来源字段` + `聚合方式`，解析为 `fdId` + `aggrType`。
+   - 复合指标必须把 `复合公式` 结合 `公式引用指标` 或前置创建结果改写成 `[metricId]` 形式。
+   - 复合指标的每个引用必须解析并核对为 `ATOMIC`/`COMPOSITE`；发现 `DERIVED`/快捷引用指标时停止计划，按业务语义改建为组合衍生或“先复合、后衍生”。
+   - `适用维度`、`时间维度`、业务属性列都需要解析成接口字段，不要把中文名原样提交给后端。
+5. 读取启用的指标业务属性配置，补齐必填 `bizAttrs`。
+6. 基于标准模板输出“指标创建计划”摘要，让用户 review；用户确认计划前，不生成最终提交 JSON，不执行真实创建。
+7. 用户确认标准 Excel 后，执行 `guanmetric flow generate --file <standard.xlsx> --out <metric_flow.json>` 自动生成 `schemaVersion=1.0` 计划并完成只读 plan 校验；不要由 Agent 手写 Flow JSON。单个、不经过标准模板的原子指标仍可使用 `create --dry-run`。
+8. 用户确认环境、目录、口径、计算配置、业务属性、保存方式和 Flow 执行顺序后，使用 `flow apply --state ... --confirm`；旧的单指标命令继续按各类型文档执行。
+9. Flow 会执行前端有而后端缺失的字段规则、原子 save-precheck、逐项创建和逐项验收；后端已有的引用状态、权限和指标定义规则由创建接口裁决，不在 Flow 重复查询。口径冲突、审批中或上游不可用时停止下游创建并保存状态。
+10. `acceptance.mode=usable` 只有在 `PUBLISHED`、`canUse=true` 且 `metric query` 冒烟成功后才算完成；`draft` 模式只验证草稿定义回读。旧命令写入成功后仍至少用 `metric get` 回读，不能把它描述为已完成 Flow 的可用性验收。
+
+不要把“dry-run 成功”“precheck 通过”或“影响校验无阻塞”描述成指标已经创建/编辑成功。
+
+## 指标创建计划
+
+创建指标前必须先输出一个计划供用户 review，尤其是一个需求会创建多个基础原子指标和复合指标时。计划确认前不得提交真实创建请求。
+
+计划至少包含：
+
+- 当前环境和目标主题。
+- 目标目录路径和目录 ID。
+- 将创建的指标清单，按依赖顺序排序；每个指标标明临时序号、名称、类型、保存方式。
+- 每个指标的核心口径：原子指标写数据集、字段、聚合方式或表达式；复合指标写中文公式和 `[metricId]` 公式草案；衍生指标写基础指标和衍生配置。
+- 复合指标依赖核对结果：逐个列出引用指标的 ID、名称和 `subType`，只允许原子/复合指标。若原口径依赖衍生指标，必须展示替代建模及语义差异，确认前不生成提交 payload。
+- 衍生指标的 `衍生自` 解析结果：必须先检查标准模板中是否已有同名原子/复合指标行，再查询现有指标。若该 `衍生自` 是本批也要创建的指标，标准模板阶段就必须已经列出对应基础指标行；创建计划阶段只负责核对、排序和暴露缺失信息，不临时新增模板外指标。
+- 适用维度和时间维度；如果存在时间字段但时间维度为空，计划必须标记为待确认，不能进入提交步骤。
+- 数据格式、业务负责人、必填业务属性。
+- 将复用的已有指标和将新建的基础指标。
+- 后续会执行的校验：dry-run、save-precheck、validate-update-impact 或本地引用检查。
+
+衍生指标依赖核对顺序：
+
+1. 建立标准模板内将创建的指标索引，至少包含原子指标和复合指标名称，也包含会先创建的普通衍生指标名称。
+2. 处理每个普通衍生指标的 `衍生自指标ID / 衍生自`：有 ID 时读取并校验；无 ID 时先在标准模板索引中按名称唯一匹配。
+3. 如果标准模板没有匹配，再用 `guancli metric search <名称> -f json` 在现有指标中查找，并用 `guancli metric get <metric_id> --brief` 核对类型、状态、适用维度、时间维度。
+4. 如果标准模板和现有指标都没有匹配，说明标准模板缺少基础指标行；不要直接生成提交 payload。必须回到标准模板补充对应原子/复合指标行，或在相关行 `问题说明` 中列出缺失的数据集、字段、聚合方式、公式、适用维度或时间维度，让用户补齐后重新标准化。
+5. 依赖顺序必须保证基础原子/复合指标先创建并取得 ID，再创建衍生指标；计划里使用临时引用名，真实提交前替换为返回的 `metricId`。
+
+计划示例：
+
+```markdown
+### 指标创建计划
+
+环境：demo-guandata
+主题：跨境电商指标体系 (ida4...)
+目录：广告分析 / 投放效果 (dir_xxx)
+
+| 步骤 | 动作 | 指标名称 | 类型 | 核心口径 | 时间维度 | 保存方式 |
+| --- | --- | --- | --- | --- | --- | --- |
+| 1 | 复用 | 归因销售额 | 原子指标 | SUM(attributed_sales) | updated_at | 在线 |
+| 2 | 复用 | 广告花费 | 原子指标 | SUM(spend_amount) | updated_at | 在线 |
+| 3 | 新建 | ROAS | 复合指标 | [归因销售额] / [广告花费] | updated_at | 草稿 |
+
+确认后我会生成 JSON、执行 dry-run/必要校验，再提交创建。
+```
+
+## 校验入口速查
+
+| 操作 | 校验规则 |
+| --- | --- |
+| 原子创建，`publish=true` | 先 `POST /api/metric-platform/metrics/atomic-metrics/save-precheck` |
+| 原子创建，`publish=false` | Web 跳过 save-precheck，可在用户确认后创建草稿 |
+| 原子编辑，`publish=true` | 先 atomic `save-precheck`，请求体带 `metricId`；再跑 `validate-update-impact` |
+| 原子编辑，`publish=false` | 跑 `validate-update-impact` |
+| 复合创建 | Web 创建无 save-precheck；提交前做人工摘要和本地 JSON/引用检查 |
+| 复合编辑 | 修改 `formula` 或 `filter` 时跑 `validate-update-impact` |
+| 衍生创建 | Web 创建无 save-precheck；提交前做人工摘要和本地 JSON/引用检查 |
+| 衍生编辑 | 修改 `baseMetricId`、`deriveSetting` 或 `filter` 时跑 `validate-update-impact` |
+| 删除指标 | 先 `GET /api/metric-platform/metrics/{id}/validate-delete-impact`；有下游资源时阻断删除 |
+| 批量上线 | 逐项读取草稿；原子执行 save-precheck；全部类型执行 validate-update-impact；冲突/影响需 `--confirm` |
+| 批量下线 | 逐项调用 `POST /api/metric-platform/metrics/{id}/offline`；部分失败不回滚 |
+
+## 命令能力边界
+
+- `guanmetric create` 和 `guanmetric edit` 是原子指标专用命令。
+- 复合指标使用 `guanmetric composite create|edit`，衍生指标使用 `guanmetric derived create|edit`。专用编辑命令负责详情读模型到 Update DTO 白名单的转换、影响校验和写后回读；不要再用裸 `fetch` 回写指标详情。
+- 对话式批量创建或包含依赖的原子/复合/衍生指标统一使用 `guanmetric flow generate|plan|apply|verify`；Flow 是新增入口，不改变上述旧命令。
+- 指标删除使用 `guanmetric delete <metric_id>`；默认只做影响校验，追加 `--confirm` 才会在无下游依赖时提交删除。
+- 指标批量上下线使用 `guanmetric batch online|offline`；详细输入、输出和失败语义见 `metric-batch-status.md`。

package/skills-bundle/guanmetric/references/metric-public-dimension-api-contract-examples.json

@@ -0,0 +1,62 @@
+{
+  "schemaVersion": "1.0",
+  "source": {
+    "environment": "test153",
+    "capturedAt": "2026-09-21",
+    "authentication": "account-password",
+    "note": "由隔离临时公共维度真实 CRUD 请求采集后脱敏；PAT 未验证，示例 ID 不可用于调用。"
+  },
+  "createRequest": {
+    "name": "区域",
+    "businessOwner": "user_example",
+    "relatedFields": [{"dsId": "dataset_example", "fdId": "field_region"}]
+  },
+  "createResponse": {"result": "ok", "response": {"id": "public_dim_example"}},
+  "updateRequest": {
+    "name": "经营区域",
+    "businessOwner": "user_example",
+    "relatedFields": [{"dsId": "dataset_example", "fdId": "field_region"}]
+  },
+  "updateResponse": {"result": "ok", "response": {"id": "public_dim_example"}},
+  "detailResponse": {
+    "result": "ok",
+    "response": {
+      "id": "public_dim_example",
+      "domId": "example_domain",
+      "name": "经营区域",
+      "businessOwner": {"uId": "user_example", "name": "示例用户", "email": "user@example.com", "avatar": "", "isDel": false},
+      "relatedFields": [{
+        "dsInfo": {"dsId": "dataset_example", "name": "销售明细"},
+        "fdInfo": {"dsId": "dataset_example", "fdId": "field_region", "name": "省份", "metaType": "DIM", "fdType": "STRING"}
+      }],
+      "creator": {"uId": "user_example", "name": "示例用户", "email": "user@example.com", "avatar": "", "isDel": false},
+      "ctime": "2026-09-21 14:05:05",
+      "utime": "2026-09-21 14:05:15"
+    }
+  },
+  "listResponse": {
+    "result": "ok",
+    "response": {
+      "contents": [{
+        "id": "public_dim_example",
+        "domId": "example_domain",
+        "name": "经营区域",
+        "businessOwner": {"uId": "user_example", "name": "示例用户", "email": "user@example.com", "avatar": "", "isDel": false},
+        "relatedFieldsDisplay": "省份(销售明细)",
+        "fdType": "STRING",
+        "creator": {"uId": "user_example", "name": "示例用户", "email": "user@example.com", "avatar": "", "isDel": false},
+        "ctime": "2026-09-21 14:05:05",
+        "utime": "2026-09-21 14:05:15"
+      }],
+      "count": 1,
+      "limit": 20,
+      "offset": 0
+    }
+  },
+  "fieldMapResponse": {
+    "result": "ok",
+    "response": {"field_region": {"id": "public_dim_example", "name": "经营区域"}}
+  },
+  "dependCheckResponse": {"result": "ok", "response": {"isDepended": false}},
+  "deleteResponse": {"result": "ok", "response": "delete success."}
+}

package/skills-bundle/guanmetric/references/metric-public-dimension-api-contract.schema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://guandata.example/schemas/metric-public-dimension-api-contract.schema.json",
+  "title": "GuanData metric public dimension API contracts",
+  "$defs": {
+    "nonEmptyString": {"type": "string", "minLength": 1},
+    "user": {
+      "type": "object",
+      "required": ["uId", "name", "isDel"],
+      "properties": {"uId": {"$ref": "#/$defs/nonEmptyString"}, "name": {"type": "string"}, "email": {"type": "string"}, "avatar": {"type": "string"}, "isDel": {"type": "boolean"}},
+      "additionalProperties": true
+    },
+    "relatedFieldWrite": {
+      "type": "object",
+      "required": ["dsId", "fdId"],
+      "properties": {"dsId": {"$ref": "#/$defs/nonEmptyString"}, "fdId": {"$ref": "#/$defs/nonEmptyString"}},
+      "additionalProperties": false
+    },
+    "writeRequest": {
+      "type": "object",
+      "required": ["name", "businessOwner", "relatedFields"],
+      "properties": {"name": {"$ref": "#/$defs/nonEmptyString"}, "businessOwner": {"$ref": "#/$defs/nonEmptyString"}, "relatedFields": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/relatedFieldWrite"}}},
+      "additionalProperties": false
+    },
+    "mutationResponse": {
+      "type": "object",
+      "required": ["result", "response"],
+      "properties": {"result": {"const": "ok"}, "response": {"type": "object", "required": ["id"], "properties": {"id": {"$ref": "#/$defs/nonEmptyString"}}, "additionalProperties": true}},
+      "additionalProperties": true
+    },
+    "detailResponse": {
+      "type": "object",
+      "required": ["result", "response"],
+      "properties": {"result": {"const": "ok"}, "response": {"type": "object", "required": ["id", "domId", "name", "businessOwner", "relatedFields", "creator", "ctime", "utime"], "properties": {"id": {"type": "string"}, "domId": {"type": "string"}, "name": {"type": "string"}, "businessOwner": {"$ref": "#/$defs/user"}, "relatedFields": {"type": "array"}, "creator": {"$ref": "#/$defs/user"}, "ctime": {"type": "string"}, "utime": {"type": "string"}}, "additionalProperties": true}},
+      "additionalProperties": true
+    },
+    "listResponse": {
+      "type": "object",
+      "required": ["result", "response"],
+      "properties": {"result": {"const": "ok"}, "response": {"type": "object", "required": ["contents", "count", "limit", "offset"], "properties": {"contents": {"type": "array"}, "count": {"type": "number"}, "limit": {"type": "number"}, "offset": {"type": "number"}}, "additionalProperties": true}},
+      "additionalProperties": true
+    },
+    "fieldMapResponse": {"type": "object", "required": ["result", "response"], "properties": {"result": {"const": "ok"}, "response": {"type": "object"}}, "additionalProperties": true},
+    "dependCheckResponse": {"type": "object", "required": ["result", "response"], "properties": {"result": {"const": "ok"}, "response": {"type": "object", "required": ["isDepended"], "properties": {"isDepended": {"type": "boolean"}}, "additionalProperties": true}}, "additionalProperties": true},
+    "deleteResponse": {"type": "object", "required": ["result", "response"], "properties": {"result": {"const": "ok"}, "response": {"type": "string"}}, "additionalProperties": true}
+  }
+}

package/skills-bundle/guanmetric/references/metric-public-dimension.md

@@ -0,0 +1,155 @@
+# 公共维度查询与写入
+
+公共维度用于把多个数据集中的同一业务维度字段关联起来，让跨指标、跨数据集的适用维度能够按同一逻辑维度对齐。
+
+构造或解析请求和响应前先读取 `metric-public-dimension-api-contract-examples.json` 与 `metric-public-dimension-api-contract.schema.json`。样例于 2026-09-21 在 test153 使用隔离临时公共维度和账号密码认证完成 create、detail/list、edit、depend-check、delete 后脱敏；PAT 尚未验证。仓库测试会按 Schema 校验这些真实快照的必需字段和类型，后端新增可选字段不会误报，但刷新快照时若 CLI 依赖字段缺失或变型会失败。
+
+## 命令入口
+
+```bash
+guanmetric public-dim list [keyword]
+guanmetric public-dim get <public_dim_id>
+guanmetric public-dim fd-map <ds_id>
+guanmetric public-dim create --file /tmp/public_dim.json --dry-run
+guanmetric public-dim edit <public_dim_id> --file /tmp/public_dim_patch.json
+guanmetric public-dim owner <public_dim_id> --business-owner <user_id>
+guanmetric public-dim delete <public_dim_id>
+guanmetric public-dim delete <public_dim_id> --confirm
+```
+
+`public-dim` 也可写成 `public-dimension` 或 `pubdim`。
+
+## 通用原则
+
+- 默认使用当前已登录环境，不询问 profile；只有用户明确指定其它环境时才追加 `--profile <profile>`。
+- 用户只给公共维度名称时，先用 `guanmetric public-dim list <keyword>` 搜索候选。
+- 用户只给数据集/字段中文名时，先用 `guancli ds search`、`guancli ds get <dsId> --brief` 查询 `dsId` 和 `fdId`。
+- 新建/编辑前先生成 JSON，并用 `--dry-run` 或人工摘要让用户确认。
+- 公共维度删除是不可恢复操作，必须先做依赖检查，再让用户确认。
+
+## 查询
+
+列表：
+
+```bash
+guanmetric public-dim list 日期 --limit 50 --offset 0 --order-by utimeDesc
+```
+
+详情：
+
+```bash
+guanmetric public-dim get <public_dim_id>
+```
+
+查询某个数据集字段是否已被公共维度占用：
+
+```bash
+guanmetric public-dim fd-map <ds_id>
+```
+
+`fd-map` 返回 `fdId -> { id, name }`，用于新建/编辑公共维度时避免选择已被其它公共维度使用的字段。
+
+真实返回的外层统一为 `{ "result": "ok", "response": ... }`：列表 `response` 包含 `contents/count/limit/offset`；详情中的 `businessOwner/creator` 是用户对象，`relatedFields` 是 `{dsInfo,fdInfo}` 数组；创建和编辑成功的 `response` 包含 `id`；依赖检查使用 `response.isDepended`；删除成功的 `response` 是 `"delete success."`。详情是读模型，不能把 `dsInfo/fdInfo`、用户对象、`domId/creator/ctime/utime` 原样回写。
+
+## 新建/编辑入参
+
+| 字段 | 中文 | 说明 |
+| --- | --- | --- |
+| `name` | 公共维度名称 | 必填；最长 50；仅支持中文、字母、数字、下划线 |
+| `businessOwner` | 责任人 ID | 必填；公共维度业务侧解释对象 |
+| `relatedFields` | 关联的数据集字段 | 必填，至少一个；元素为 `{ "dsId": "...", "fdId": "..." }` |
+
+`relatedFields` 规则：
+
+- 每个元素都必须同时有 `dsId` 和 `fdId`。
+- 同一个公共维度里的字段类型必须兼容/相同；后端会校验，不同类型会失败。
+- Web 会禁用已被其它公共维度使用的字段；CLI 创建前应对每个涉及的数据集调用 `fd-map`，发现字段已归属其它公共维度时先向用户说明并重新选择。
+- 同一个公共维度内不要重复选择同一数据集的同一字段。
+
+## JSON 模板
+
+```json
+{
+  "name": "日期",
+  "businessOwner": "<user_id>",
+  "relatedFields": [
+    { "dsId": "<ds_id_1>", "fdId": "<date_fd_id_1>" },
+    { "dsId": "<ds_id_2>", "fdId": "<date_fd_id_2>" }
+  ]
+}
+```
+
+## 新建流程
+
+1. 收集公共维度名称、责任人、要关联的数据集字段。
+2. 对每个数据集运行 `guancli ds get <dsId> --brief` 核对字段存在和字段类型。
+3. 对每个数据集运行 `guanmetric public-dim fd-map <dsId>`，确认字段未被其它公共维度使用。
+4. 生成 JSON 文件并 dry-run：
+
+```bash
+guanmetric public-dim create --file /tmp/public_dim.json --dry-run
+```
+
+5. 向用户摘要名称、责任人、关联字段、字段类型；用户确认后提交：
+
+```bash
+guanmetric public-dim create --file /tmp/public_dim.json
+```
+
+## 编辑流程
+
+1. 先获取详情：
+
+```bash
+guanmetric public-dim get <public_dim_id>
+```
+
+2. 基于现有详情生成 patch 或完整 JSON。默认 `edit` 会把详情转换成提交 payload 后合并 patch。
+3. 如果修改关联字段，重新检查字段类型和 `fd-map` 占用。
+4. dry-run：
+
+```bash
+guanmetric public-dim edit <public_dim_id> --file /tmp/public_dim_patch.json --dry-run
+```
+
+5. 用户确认后提交：
+
+```bash
+guanmetric public-dim edit <public_dim_id> --file /tmp/public_dim_patch.json
+```
+
+只转移责任人时可用：
+
+```bash
+guanmetric public-dim owner <public_dim_id> --business-owner <user_id>
+```
+
+## 删除流程
+
+删除前先执行依赖检查：
+
+```bash
+guanmetric public-dim delete <public_dim_id>
+```
+
+该命令会调用：
+
+```text
+GET /api/metric-platform/public-dimensions/depend-check/<public_dim_id>
+```
+
+如果返回 `isDepended=true`，说明已有指标在使用该公共维度。Web 的行为是提示“删除后将影响有公共维度的指标计算准确性”，用户确认后仍允许删除。
+
+用户明确确认后执行：
+
+```bash
+guanmetric public-dim delete <public_dim_id> --confirm
+```
+
+提交删除接口：
+
+```text
+POST /api/metric-platform/public-dimensions/delete/<public_dim_id>
+```
+
+不要把“依赖检查通过/已提示风险”描述成已经删除成功；只有 delete 接口成功返回后才算删除完成。