codebase-research

代码库研究

只读调查 Datex Studio 分支，以回答有关代码当前状态的问题，包括组件、流源代码、类型定义、数据源和配置，且不做任何更改。

这是一项实用工具技能。它会生成有依据的答案，供其他技能使用。它不会创建、修改、验证或部署任何内容。

适用场景

当任务需要先了解当前代码库的实际情况才能继续时，请调用此技能。常见的调用方包括：

• impact-analysis — 需要了解某项配置的作用，然后反向追踪调用方。
• requirements-gathering — 需要检查现有报告／流／数据源，以提取有效需求。
• report-creator — 需要在编写报告前确认字段结构、数据源输出或现有报告模式。
• 任何需要基于权威来源进行检查且不改变状态的未来技能。

当用户直接提出以下问题时，也请调用此技能：

• “研究一下代码库，告诉我 X 是如何工作的。”
• “调查一下 Y 定义在哪里。”
• “找出所有引用 Z 的位置。”
• “xxx_flow 函数实际上做什么？”
• “OrderStatus 接受哪些枚举值？”

不适用场景

• 不用于查询 OData 架构 — 请交给 schema-explorer。不要将原始 OData 元数据加载到父级上下文中。
• 不用于修改文件 — 此技能严格只读。如果答案需要进行更改，请转交给合适的创建／编辑技能。
• 不用于对实时数据运行查询 — 此类任务请使用 odata-execution 或 db-query。
• 不用于对整个分支进行深入架构评审 — 此类任务请使用 branch-code-reviewer。此技能只回答具体问题。

模式

这是一项只读研究任务。不要编辑、创建或修改任何文件。不要运行会改变分支状态的命令（不运行 upsert、validate --fix，也不进行任何写入）。通过 dxs CLI 读取的分支是权威来源；切勿假定本地的 src/ 检出内容具有权威性。只能使用只读命令，例如 dxs source explore config <ref> --branch <id>（完整配置）、dxs source explore configs（列表）、dxs source explore summary／trace／graph、dxs schema describe／search，以及针对只读端点运行的 dxs odata execute。如果需要原始 JSON，可运行 dxs configuration get <type> <id> -b <id> -O envelope.json，然后运行 jq .json envelope.json — 将文件写入临时目录，绝不能保留一份持久的权威来源副本。

可用来源

按以下大致优先顺序检查这些来源：

• 分支上的组件配置 — 操作（*-footprintFlow）、函数（*-flow）及所有其他类型。每个配置都是包含内嵌 TypeScript 的 JSON。使用 dxs source explore config <referenceName> --branch <id> 获取（或使用 dxs configuration get <type> <id> -b <id> -O envelope.json → jq .json）。分支是权威来源；不要读取本地检出内容。
• 类型定义 — customtype 配置（*-customType）。接口和枚举定义都在这里。请从分支获取，并优先于摘要信息。
• OData 架构 — 将实体、属性、键和导航相关查询交给 schema-explorer 技能。不要将原始架构文档加载到父级上下文中。
• 平台文档 — datex-studio-shared、datex-studio-conventions、datex-studio-runtime 技能包含编写规范、约定和运行时语义。当问题涉及事物应该如何工作，而非当前存在什么时，请查阅这些文档。
• 项目／功能上下文 — 项目中的所有 CLAUDE.md 文件。包含领域知识和项目专属约定。内容可能已过时；请将其视为提示，而非权威来源。

Datex Studio 专属模式

以下模式使此技能有别于通用技能。每次使用时都要遵循。

1. 流程代码位于 JSON 内部，而非顶层

读取操作、函数或任何基于流程的组件时，可执行的 TypeScript 并不位于顶层 JSON 中。实际代码是嵌入在以下位置的字符串：

nodes[0].stepConfig.executeCodeConfig.code

要分析 TypeScript，请先提取该字符串，然后将其作为 TypeScript 读取和分析。如果只读取外围 JSON，而不深入此路径，你得到的只有元数据，而非实现。

检查多步骤流程时，遍历 nodes[*].stepConfig.executeCodeConfig.code——每个步骤都有自己的代码主体。

2. 将 OData 架构查询委托给 schema-explorer

如果问题涉及实体、属性、键、导航或任何 OData 元数据：

• 应当使用聚焦的查询调用 schema-explorer 技能。
• 不要将原始架构文档载入父级上下文。该文档体量庞大、内容繁杂，会占用上下文窗口。
• schema-explorer 会返回简洁的结构化答案（实体结构、属性列表、导航链），并处理连接解析和 FootPrintApi 特例。

如果因某种原因无法使用 schema-explorer，则直接使用 dxs schema describe / dxs schema search；但仍不得将完整架构转储读入父级上下文。

3. 枚举值位于 customType 配置中

如果问题是“枚举 X 接受哪些值？”或“字段 Y 可能有哪些值？”：

• 只需要成员名称时最快的方法：dxs configuration nomenclature -b <id>（可选 --search <name> 或 --package <Pkg> --kind enum）会在一次简洁调用中返回每个 <Package>.<Type> 及其 constantValues 中的枚举成员（无需逐个获取类型）。参见 ../datex-studio-shared/context-navigation.md#discovering-custom-types-and-enum-members。
• 需要完整定义时（描述、值映射、接口字段结构）：从分支获取 *-customType 配置——使用 dxs source explore config <enum_referenceName> --branch <id>（或使用 dxs source explore configs --type customtype --search <name> 列出候选项）。
• 在该处查找枚举定义——它是事实依据。
• 不要仅依赖 CLAUDE.md 或技能引用中的摘要——这些内容可能已过时。
• 如果某个类型被流程参数引用，请沿引用追溯到其 customType 配置（dxs source explore trace <flow_ref> --branch <id> 会显示类型引用）。

4. Answer / Sources / Caveats 响应格式

始终按以下三部分结构作答（参见下文“响应格式”）。这种结构便于审查答案，也能明确说明歧义；对于使用此技能输出的下游技能而言，这一点至关重要。

工作流

1. 重述问题，用一行说明，以便使用者确认意图。
2. 选择来源——针对每项所需事实，确定可用来源中哪些能够回答。优先使用代码而非文档、类型而非摘要，以及 schema-explorer 而非原始架构。
3. 检查——通过 dxs source explore 从分支获取配置（或调用 schema-explorer 查询 OData 架构）。应用以上四种 Datex Studio 专属模式。将检查范围控制在必要范围内——不要遍历整个分支。
4. 交叉引用，适用于问题涉及代码与架构，或代码与类型的情况。如果来源之间存在分歧，请指出分歧；不要默默择一。
5. 按 Answer / Sources / Caveats 格式撰写答案。

指南

• 具体明确。 引用你找到的行、属性或值。如果引用足够简短，就不要概述。
• 注明来源。 每项说法都应能追溯到其来源配置（dxs source explore 命令和 referenceName），或生成该结果的 schema-explorer 查询。
• 指出歧义。 如果两个来源相互矛盾、CLAUDE.md 摘要与代码矛盾，或无法根据现有来源完整回答问题，请在注意事项中说明。
• 聚焦问题。 研究请求不代表可以浏览无关文件。回答问题后就停止。
• 不做推测。 如果找不到答案，请说明“在 中未找到”，不要猜测。
• 遵守只读原则。 如果检查时发现错误或可改进之处，请在注意事项中提及，但不要修复。由使用者决定如何处理该发现。

回复格式

直接、简洁地回答问题。使用以下三部分结构：

## Answer

<the direct response — concrete, quoted from sources where possible>

## Sources

- `<file path or skill call>` — <what this source contributed>
- `<file path or skill call>` — <what this source contributed>
- ...

## Caveats

- <any ambiguity, conflicting information, assumption, or "not found" note>
- <if none, write: "None.">

示例

## Answer

`update_shipment_status_flow` updates a shipment's `Status` field via the
Footprint API. It accepts `shipmentId: string` and `newStatus: ShipmentStatus`
and returns `{ success: boolean, message: string }`. The function calls
`PATCH /api/Shipments({shipmentId})` with `{ Status: newStatus }`.

## Sources

- `dxs source explore config update_shipment_status_flow --branch <id>` —
  extracted code from `nodes[0].stepConfig.executeCodeConfig.code`; parameter
  list and return shape on the top-level JSON.
- `dxs source explore config shipment-customType --branch <id>` —
  `ShipmentStatus` enum values: `Open`, `InProgress`, `Closed`, `Cancelled`.
- `schema-explorer` (entity `Shipments`) — confirmed `Status` is an
  enum-backed string property, not a navigation.

## Caveats

- The flow's JSDoc says it returns `void`, but the actual code returns
  `{ success, message }`. The JSDoc appears stale.
- `CLAUDE.md` lists a fifth status `Voided`; not present in
  `shipment-customType.json`. Type file wins.

输出约定

单条回复，包含上述三个部分。不得写入文件、修改状态，也不得代表使用者运行后续命令。

使用该技能的使用者负责决定如何处理答案。该技能的唯一职责是让当前代码库状态清晰易懂。