SKILL.md 全文

Frontmatter

name	nav-review-identify
description	|

---
name: nav-review-identify
description: 'NAV 复核第一阶段：识别基金特征与文件夹结构。读取 TB / FS Pack / IPA，判断基金类型、TB 频率（月度 vs 季度）、报告体系、银行账户、是否含 MMF、上期文件夹位置等关键属性，输出结构化 profile.json 供后续阶段消费。触发场景：被 nav-review 主调度 skill 调用，或用户单独要求"识别基金结构"、"分析 NAV 文件夹"、"profile 这个基金"。'
---

NAV Review Stage 1 — 基金特征识别


When to Use

由 nav-review 主调度 skill 在 Stage 1 自动调用

用户单独说"识别基金结构"、"分析 NAV 文件夹"、"profile 这个基金"

用户给定一个基金某月份/某季度文件夹，要求先弄清楚里面有什么


本 skill 只做识别和元数据收集，不读取业务数据，不生成截图，不出报告。

---

输入

target_dir：基金某期间文件夹的绝对路径（必须）

月度示例：.../FundA/2026-04/

季度示例：.../FundB/2025 Q4/


输出


固定产出一份 JSON 文件至 <target_dir>/.cortex/nav_profile.json，并在终端打印同样内容。下游 collect / report skill 读取该文件作为单一可信来源。

profile.json 字段定义


| 字段 | 类型 | 必填 | 来源步骤 |
|------|------|------|----------|
| fund_name | string | ✅ | Step 1（从文件夹名或 TB 提取） |
| period_type | "monthly" \| "quarterly" | ✅ | Step 1 |
| period_label | string | ✅ | Step 1 |
| period_end_date | string (YYYY-MM-DD) | ✅ | Step 1 |
| months_in_scope | string[] | ✅ | Step 1 |
| subsequent_months | string[] | ✅ | Step 1 |
| report_system | "Maples-FSPack" \| "IGOWIN-Report" | ✅ | Step 1 |
| fund_types | string[] | ✅ | Step 2 |
| has_mmf | boolean | ✅ | Step 2 |
| has_partnership | boolean | ✅ | Step 2 |
| has_hedge_fund | boolean | ✅ | Step 2 |
| has_nominee | boolean | ✅ | Step 2 |
| nominee_platforms | string[] | ✅ | Step 2 |
| bank_accounts | object[] | ✅ | Step 2 |
| investments | object[] | ✅ | Step 2 |
| key_files | object | ✅ | Step 1 |
| prior_period_dir | string \| null | ✅ | Step 3 |
| prior_period_files | object | ✅ | Step 3 |
| folders | object | ✅ | Step 1 |

嵌套对象结构（字段名与层级保持不变）：
bank_accounts[]：{ "tb_code": string, "name": string, "type": "main"|"nominee"|"other" }

investments[]：{ "name": string, "type": string, "tb_code": string }

key_files：{ "fs_pack", "tb_csv", "cash_appraisal", "ipa", "investment_movement", "payment_log", "summary_log", "nav_workbook" } — 值为相对路径或 null

prior_period_files：{ "fs_pack": string|null, "ipa": string|null }

folders：{ "bank_statements": string[], "investment": string[], "capital_call_reports": string|null, "payments": string|null }


---

参考表


5 张参考表已外置至 [references/report_system_reference.md](references/report_system_reference.md)，执行时按需查阅：

1. 两种报告体系特征对照
2. Maples 文本科目 ↔ 业务含义映射
3. N 系列报告用途速查
4. period_type 对下游影响速查
5. Reporting Period 格式速查

---

执行步骤


Step 1：扫描文件夹 + period_type 判断 + 报告体系判断 + 关键文件定位


1a. 扫描文件夹结构

powershell Get-ChildItem -Path "<target_dir>" -Force | Select-Object Name, PSIsContainer

遍历常见子目录：Report/、Bank statements/、Cash/、Investment/、Capital call reports/、Payments/，填充 folders 字段。

1b. 判断报告体系

| 信号 | 报告体系 |
|------|---------|
| 根目录存在 FS pack.xlsx | Maples-FSPack |
| 存在 Report/Trial Balance_.csv 与 Report/Investment Position Appraisal. | IGOWIN-Report |

如同时存在，优先 Maples-FSPack（FS Pack 信息更全），但保留两套关键文件路径。

两种体系详细特征对照见参考表 1。


1c. 判断 period_type 与 months_in_scope

1. 优先从文件夹名称识别：
含 Q1/Q2/Q3/Q4 → quarterly

形如 YYYY-MM 或 YYYY年M月 → monthly

2. 用 TB 数据复核（见下方合并脚本）：
Maples-FSPack：读 FS pack TB sheet 的 "Reporting Period" 字段

IGOWIN-Report：读 Report/Trial Balance_*.csv 文件名中的日期

3. 二者矛盾时以 TB 为准，并在 stdout 输出 warning。
4. 派生 months_in_scope / subsequent_months / period_end_date / period_label。

Reporting Period 格式 → period_type 映射见参考表 5。  

period_type 对下游核对的影响见参考表 4。


1d. 定位关键文件

| key | glob | 说明 |
|-----|------|------|
| fs_pack | FS pack.xlsx | Maples 体系 |
| tb_csv | Report/Trial Balance_*.csv | IGOWIN 体系 |
| cash_appraisal | Report/Cash Appraisal.pdf | IGOWIN 体系 |
| ipa | Report/Investment Position Appraisal.* | IGOWIN 体系 |
| investment_movement | Investment movement summary.xlsx | Maples 体系 |
| payment_log | Payment log_.xlsx 或上一级 ../Payment log_.xlsx | 跨期共享 |
| summary_log | Summary log.xlsx 或 Summary Log.xlsx | |
| nav_workbook |  NAV workbook.xlsx | IGOWIN 体系 |

找不到则填 null。

1e. 合并 openpyxl 脚本（TB 频率识别 + SOFI 读取，一次加载多 sheet）

仅 Maples-FSPack 体系需要执行：

powershell python -c " import openpyxl, glob, os os.chdir('<target_dir>') fs = glob.glob('FS pack.xlsx') if not fs: print('NO_FS_PACK'); exit(0) wb = openpyxl.load_workbook(fs[0], data_only=True)

--- TB sheet: Reporting Period ---

ws_tb = wb['TB'] for row in ws_tb.iter_rows(min_row=1, max_row=15, values_only=True): print('TB\t' + '\t'.join(str(c)[:80] if c else '' for c in row))

--- SOFI sheet: 持仓与类型 ---

if 'SOFI' in wb.sheetnames: ws_sofi = wb['SOFI'] for row in ws_sofi.iter_rows(min_row=1, max_row=ws_sofi.max_row, values_only=True): cols = [str(c) if c is not None else '' for c in row] if any(cols): print('SOFI\t' + '\t'.join(cols)) "

输出行以 TB\t 或 SOFI\t 前缀区分来源，Agent 据此分别解析。

---

Step 2：基金类型识别 + 银行账户 + Nominee


2a. 基金类型与持仓
Maples-FSPack：从 Step 1e 的 SOFI 输出按行分类

IGOWIN-Report：读 Report/Investment Position Appraisal.csv


分类规则：
含 Money Market / MMF / Liquid → MMF

含 Partnership / LP → Partnership Interest

含 Hedge / 单位结构（NAV per unit + Units） → Hedge Fund


填充 fund_types[]、investments[]、has_mmf、has_partnership、has_hedge_fund。

2b. 银行账户与 Nominee

从 TB 中提取以 Cash 开头或 TB Code 落在现金科目段的行：
TB Code 末位 0000 → type: "main"

TB Code 末位 0001+ 且 Description 含 Nominee / Ark / Noah → type: "nominee"

其他 → type: "other"


如果文件夹下存在 Bank statements/Ark/ 或 Cash/Ark/，标记 has_nominee=true 并加入 nominee_platforms[]。

Maples 文本科目与数字科目映射见参考表 2。


---

Step 3：定位上期文件夹


从父目录列出兄弟目录，按字典/日期顺序找上一期：
monthly：上一个月（YYYY-MM）

quarterly：上一个季度（含跨年）


将相对路径写入 prior_period_dir。如果上期目录存在，进入扫描 prior_period_files.fs_pack / .ipa；不存在则 prior_period_dir 为 null 并在 stdout 警告。

---

Step 4：组装并写入 profile.json


将 Step 1–3 收集的所有字段组装为完整 profile 对象，写入 <target_dir>/.cortex/nav_profile.json 并在终端打印。

关键文件不存在的字段统一为 null，不可为空字符串。

---

完成检查表

[ ] nav_profile.json 已写入 <target_dir>/.cortex/

[ ] period_type ∈ {monthly, quarterly}，且 months_in_scope 长度一致（1 / 3）

[ ] prior_period_dir 指向存在的目录或为 null（null 时 stdout 有警告）


---

关键注意事项


1. 本 skill 不读取流水、不算金额、不下结论。任何金额/差异计算均由后续 collect/report skill 完成。
2. 不要硬编码"季度"或"月度"：必须由 TB Reporting Period 或文件夹名共同决定，二者矛盾时以 TB 为准并在 stdout 输出 warning。
3. 路径全部用相对于 target_dir 的路径写入 profile，方便 report 阶段嵌入或在 iGowin 上传时引用。
4. Maples-FSPack 与 IGOWIN-Report 不冲突：两套字段并存，下游按 report_system 选择主路径。
5. Subagent 容错：本 skill 多用 run_in_terminal + openpyxl/csv 直接读，避免依赖 subagent。

`