定位元数据

定位元数据用于处理“某个路径下有哪些模型”“找某个字段在哪个模型里”“查页面或报表引用了哪个模型”“根据业务词找资源文件”“判断 /项目/... 路径下有什么”等任务。

定位原则

1. 用户给出 /项目名/... 形式的路径时，默认这是 SuccApp 服务器元数据路径，不是本地绝对文件路径。
2. 用户给出 SuccApp 页面 URL 时，可以从 URL 路径识别 /项目名/...，也可以从 :open 等参数中的资源 ID 反查服务器路径。
3. 回答业务问题、排查模型、查字段、查依赖、判断当前项目内容时，优先查当前工作区中已克隆的项目，其次查当前活跃服务器。
4. 用户要求修改页面、模型等元数据资源时，如果当前已经在 SuccApp 工作区，但目标项目尚未克隆，应询问用户是否先把项目克隆到当前工作区，再继续修改。
5. 示例只用于参考和学习。除非用户明确要求查询示例、DEMO 示例或参考写法，.agents/skills/succapp-docs/metadata-examples/ 一般不是用户想找的目标。
6. 除非用户明确要求，不要向上级目录、相邻目录或其它 SuccApp 工作区搜索同名项目来回答当前项目问题。
7. 如果当前工作区和当前活跃服务器都找不到，或 CLI 不可用、未登录、无权限、服务器不可达，应明确说明无法确认真实元数据，并询问用户补充目标服务器、工作区、项目或更详细路径。

默认查询流程

1. 确认当前工作区和活跃服务器，例如执行：

   succapp workspace status --json

2. 从 /项目名/... 路径中识别项目名和相对资源路径，例如 /DEMO/data/tables/行业/企业法人 对应项目 DEMO。

3. 如果用户给的是浏览器 URL，例如 http://localhost:8180/DEMO/data?:open=O20vb6tsc4BF2i7PKKZFPB&:tblview=modelFields，先尝试从 URL 路径得到 /DEMO/data，再用 :open 中的资源 ID 定位实际资源路径：

   succapp server file locate http://localhost:8180 O20vb6tsc4BF2i7PKKZFPB --json

4. 如果当前工作区已克隆该项目，并且项目目录包含 .meta，优先在本地项目目录中查找同名目录、资源文件和目录级 .meta。

5. 如果当前工作区没有该项目或路径，不要到父目录、兄弟目录或其它工作区查找同名项目；使用 SuccApp CLI 的只读命令查询当前活跃服务器，例如：

   succapp server file list /DEMO/data/tables/行业/企业法人 --json
   succapp server file search 企业法人 --project=DEMO --type=tbl --limit=20 --json
   succapp model list --project DEMO --contains=企业法人 --json

6. 找到候选 .tbl 模型后，再按任务需要查看模型摘要、字段或索引：

   succapp model show /DEMO/data/tables/行业/企业法人/示例模型.tbl --json
   succapp model fields /DEMO/data/tables/行业/企业法人/示例模型.tbl --json
   succapp model indexes /DEMO/data/tables/行业/企业法人/示例模型.tbl --json

7. 如果用户要求修改已定位到的页面、模型、报表或脚本等元数据资源，而当前工作区尚未克隆目标项目，应先询问是否执行类似下面的命令克隆项目，不要直接改相邻工作区或绕过工作区直接写服务器：

   succapp workspace project clone DEMO

8. 如果当前工作区和当前活跃服务器都找不到，或 CLI 不可用、未登录、无权限、未配置活跃服务器或服务器不可达，应明确说明无法确认真实元数据，并询问用户补充目标服务器、工作区、项目或更详细路径。

实际命令参数以当前 succapp --help、succapp server file --help 和 succapp model --help 输出为准。查询真实业务项目时优先使用只读命令，避免修改、删除、推送或导出大量数据。

查找方向

任务	优先方法
判断某个路径下有什么	本地查项目目录和 .meta；本地没有时用 succapp server file list 查询服务器目录。
根据浏览器 URL 找资源	从 URL 路径提取 /项目/...；如果 URL 带 :open 资源 ID，用 succapp server file locate 反查路径。
修改未克隆项目中的资源	先询问用户是否把目标项目克隆到当前工作区，再在本地修改和检查 diff。
找某个资源文件	先按路径精确定位；路径不完整时用文件名、标题、业务词执行本地搜索或 succapp server file search。
找模型文件	本地搜索 .tbl；服务器查询用 succapp model list 或 succapp server file search。
找字段在哪个模型里	先筛选候选 .tbl，再用 succapp model fields 查看字段清单。
查页面、报表或仪表板依赖	先定位页面、报表、仪表板文件，再查看其中引用的模型、查询、脚本或组件路径。
根据业务词找资源	同时搜索资源路径、文件内容、模型标题、字段标题和 .meta 信息，并说明匹配依据。

输出要求

AI 回答时应说明：

1. 信息来源：当前工作区、服务器 CLI，还是用户明确要求的示例或其它工作区。
2. 已检查的项目、目录、命令或文件路径。
3. 候选文件、模型、字段或依赖，以及每个候选的判断依据。
4. 哪些内容可以确认，哪些内容因为未登录、无权限、CLI 不可用或服务器不可达而无法确认。

如果没有访问到当前工作区中的真实项目或当前活跃服务器，只能说“无法确认真实元数据”，不能把 metadata-examples 中的示例 DEMO 或相邻工作区里的同名项目当成当前服务器事实。