Project Research

---
name: project-research
description: "用于读取已有代码项目，结合真实代码、文档、local 材料和 git 记录，产出项目功能能力地图：项目定位、一级能力域、二级功能组或模块、三级功能点、证据路径、当前状态、下一步，以及可选的完全汉化 XLSX 阅读版。默认不做工作分解、产品结构拆解、成熟度评估、卡点长分析、任务计划、排期或资源估算。"
---

# 项目功能能力地图

## 目标

读取一个已有代码项目、配置、文档、`local/` 材料和 git 记录，整理出一份轻量的项目功能能力地图，帮助后续做进展管理、项目汇报、绩效材料和需求范围判断。

核心产物是一张证据表：

```text
项目目标
-> 一级能力域
-> 二级功能组或模块
-> 三级功能点
-> 证据路径
-> 当前状态
-> 下一步
```

保留 `project-research` 这个 skill 名只是为了兼容已有运行入口；默认工作方式已经改成“项目功能能力地图”，不是完整项目研究包。

能力地图要同时覆盖两类内容：

- 当前已经在代码、配置、测试、脚本、文档或运行结果中形成的能力。
- 从 `local/` 材料、roadmap、forward plan、PRD、issue/commit 历史和 git 演进线中能谨慎推断出的后续 L1 / L2 / L3 能力。

后续能力不能写成已完成；只能按证据强度标为 `已规划`、`待验证` 或带 `[推断]` 的条目。

## 边界

这个 skill 只回答：

- 这个项目是做什么的。
- 项目有哪些主要能力域。
- 每个能力域下面有哪些功能组或模块。
- 每个功能组或模块下面有哪些可观察的功能点。
- 每个功能点有哪些代码、文档、配置、测试或命令证据。
- 每个功能点当前处于什么简单状态。
- 每个二级模块下一步最该补什么。
- 从 git 记录和 local 材料看，后续还应该补哪些 L1 / L2 / L3。

默认不输出：

- 产品结构拆解。
- 工作分解。
- 跟踪矩阵。
- 长篇卡点清单。
- 交付成熟度或成熟度等级。
- 详细功能规格卡。
- 部署和运维检查报告。
- 目标变化日志。
- 增量快照。
- 大量表格文件；但用户明确要求 Excel / XLSX / 表格阅读版时，可以额外输出一个 `项目能力表.xlsx`。
- 完成率、权重、评分、排期、负责人、资源估算、成本估算或绩效判断。

如果用户要拆研发任务，转交 `delivery-task-planning`。如果用户要正式功能规格，转交 `functional-spec`。如果用户要打分、写汇报话术或做绩效评价，应在能力地图完成后另起下游步骤。

## 安全

- 默认只读扫描。
- 只运行不会破坏项目的命令，例如列文件、读文档、查配置、看入口、跑明确安全的 smoke/test 命令。
- 不删除文件、不改配置、不跑迁移、不重置 Git、不清数据库、不部署，除非用户在这个 skill 之外明确要求。
- 不把原始 token、密钥、密码、私有 URL 或个人数据写进产物；只记录变量名和脱敏示例。
- 如果为了证明证据运行了命令，在相关备注里简短记录命令和结果。

## 输出语言

- 默认产物使用简体中文，包括文件标题、章节名、说明文字、表格列名、状态、备注和下一步。
- 默认新建输出目录，优先使用 `./local/项目能力地图-YYYYMMDD/`；如果目录已存在，追加短后缀，避免覆盖旧结果，除非用户明确要求覆盖。
- 默认生成中文文件名：
  - `项目能力摘要.md`
  - `项目功能能力地图.md`
  - `项目能力表.csv`
- 当用户明确提到 `XLSX`、`Excel`、`工作簿`、`表格阅读版`、`方便阅读的 Excel 版`、`完全汉化 XLSX` 或类似要求时，额外生成：
  - `项目能力表.xlsx`
- CSV 默认使用中文表头，便于直接给人阅读和导入表格工具。
- XLSX 默认使用完全中文工作表名、中文表头、中文说明和中文状态；代码路径、命令、API、配置键等真实标识保留原文。
- 代码路径、命令、包名、API 名、配置键、代码标识符、skill 名和文件扩展名保持原文，不强行翻译。
- 需要给自动化脚本消费时，用户可以另行要求英文文件名或英文表头；默认不要主动输出英文版。

## 状态标签

每个三级功能点只选一个主状态：

| 状态 | 含义 |
|---|---|
| `已规划` | 有目标或计划，但没有找到具体设计或代码证据。 |
| `已设计` | 已有结构、接口、数据模型、模板、路由或方案，但没有看到完整实现。 |
| `已开发` | 已有对应代码或配置。 |
| `可运行` | 能启动、执行或产出可观察结果。 |
| `待验证` | 看起来已经实现，但还需要联调、测试、稳定性或真实使用确认。 |
| `已废弃/重构` | 证据显示该功能点已经废弃、替换或不再按原路径推进。 |
| `未发现证据` | 资料中提到或按项目目标应有，但没有找到支撑证据。 |

不要使用成熟度等级、百分比或“完成了多少”的表达。

## 工作流程

1. 确认目标项目根目录，默认使用当前目录。
2. 确认输出目录，默认新建 `./local/项目能力地图-YYYYMMDD/`。
3. 只扫描足够支撑能力地图的证据：README、文档、依赖清单、入口文件、路由、接口、模型、服务、页面组件、提示词、工作流、配置、测试、示例、部署文件和近期生成物。
4. 读取 `local/` 下与项目事实、PRD、forward plan、phase gate、roadmap、handoff、status 或验收报告相关的材料；`local/` 常被 `.gitignore` 忽略，不能只看 `git status`。
5. 查看近期和关键 git 记录，例如 `git log --oneline --decorate --max-count 50`、与业务能力相关的 merge/commit 标题，以及必要时的 `git show --stat`；只把能解释能力演进的提交写进证据。
6. 写一句项目目标。优先使用仓库里明确写出的目标；如果是推断，标记 `[推断]` 并说明来源。
7. 按业务能力识别一级能力域，不要机械照搬 `frontend`、`backend`、`scripts` 这类目录名。一般控制在 3-8 个。
8. 在每个一级能力域下识别二级功能组或模块。一般每个一级能力域控制在 3-8 个。
9. 在每个二级功能组或模块下识别三级功能点。一般每个二级模块控制在 2-8 个。三级功能点必须是可观察功能，不要写抽象概念。
10. 把当前能力和后续能力放进同一张表，但必须用状态区分：
   - 代码、测试、配置或可运行命令已经支撑的功能点，按证据选择 `已开发` 或 `可运行`。
   - 设计文档、接口契约、DDL、模板、roadmap 已经定义但未见完整实现的功能点，标为 `已设计` 或 `已规划`。
   - 已有 adapter、smoke 脚本或配置入口，但缺真实联调、live provider、真实数据库或稳定使用证据的功能点，标为 `待验证`。
   - 仅根据 git 演进线、目录结构或相邻材料推断的后续项，在证据或备注中标记 `[推断]`。
11. 为每个三级功能点附证据：
   - 尽量使用具体路径，必要时带行号。
   - 只有推断没有直接证据时，标记 `[推断]` 并写明推断来源。
   - 找不到证据时，标记 `[未知]` 或状态 `未发现证据`。
12. 为每个三级功能点选择一个主状态。
13. 为每个二级模块写一句下一步建议。平铺 CSV 时，同一个二级模块的下一步可以在多行重复。
14. 默认只写这 3 个产物：
    - `项目能力摘要.md`
    - `项目功能能力地图.md`
    - `项目能力表.csv`
15. 如果用户要求 XLSX / Excel / 工作簿 / 表格阅读版，用同一份 CSV 数据额外生成 `项目能力表.xlsx`，不要让 XLSX 与 CSV 内容漂移。
16. 最后输出简短交付摘要：产物路径、一级/二级/三级数量、主要证据缺口、3 句可用于汇报的中文表达；如果生成 XLSX，也说明工作簿的工作表结构。

## 默认产物

- `项目能力摘要.md`：项目目标、核心能力域、当前已形成能力、从 git / local 看出的后续能力方向、主要缺口和一句汇报表达。
- `项目功能能力地图.md`：可读的一级/二级/三级能力地图表、按一级能力域汇总说明、后续 L2 / L3 方向、缺口摘要和 3 句汇报表达。
- `项目能力表.csv`：可导入表格工具的平铺能力表，默认表头：

```csv
一级能力域,二级功能组或模块,三级功能点,功能说明,证据路径,当前状态,下一步,备注
```

默认不要创建很多 CSV 文件。

## 可选 XLSX 阅读版

当用户明确要求 XLSX / Excel / 工作簿 / 表格阅读版时，额外输出 `项目能力表.xlsx`。XLSX 是 CSV 的阅读层，不是独立事实源。

默认工作表：

- `阅读说明`：项目名、文件用途、证据来源、后续项标记规则、验证命令和注意事项。
- `状态汇总`：L3 总数、L1 数、L2 数、各状态数量，以及状态标签说明。
- `能力表`：与 `项目能力表.csv` 同内容、同表头、同顺序。
- `L1-L2索引`：按 L1 / L2 聚合 L3 数量和 L2 下一步，便于快速浏览。

格式要求：

- 完全汉化：工作表名、标题、表头、说明、状态说明和备注都用简体中文。
- 首行冻结、开启筛选、自动换行、列宽适合长路径阅读。
- 状态列使用稳定色块，但不要增加评分、完成率、权重或排期字段。
- 如果工作簿使用公式，必须按 spreadsheet / xlsx skill 规则重新计算并确认没有公式错误；如果只是静态表，至少用 `openpyxl` 重新打开检查工作表、行数和表头。
- 默认新建文件，不直接覆盖旧 XLSX，除非用户明确要求。

## 参考文件 / 何时读取

- `references/methodology.md`：当用户问为什么这么设计，或需要检查产物是否又变重时读取。
- `references/project-summary-template.md`：写 `项目能力摘要.md` 时读取。
- `references/capability-map-template.md`：写 `项目功能能力地图.md` 时读取。
- `references/csv-output-schema.md`：写 `项目能力表.csv` 时读取。
- `references/xlsx-output-schema.md`：用户要求 XLSX / Excel / 工作簿 / 表格阅读版时读取。

## 验收标准

- 产物默认使用简体中文。
- 输出包含项目目标，以及一级/二级/三级能力行。
- 一级是能力域，二级是功能组或模块，三级是可观察功能点。
- 三级功能点尽量引用具体证据路径。
- 没有直接证据的内容必须标记 `[推断]` 或 `[未知]`，不能当事实写。
- 后续 L1 / L2 / L3 必须来自 `local/`、roadmap、forward plan、PRD、git 记录或明确推断来源，不能凭空补齐。
- 每个三级功能点只使用允许的中文状态标签。
- 默认产物仅限 `项目能力摘要.md`、`项目功能能力地图.md`、`项目能力表.csv`；用户要求 XLSX 时可额外生成 `项目能力表.xlsx`。
- 如果输出 XLSX，`能力表` 工作表必须与 CSV 行列一致，且工作簿必须能被重新打开。
- 不默认输出工作分解、产品结构拆解、跟踪矩阵、成熟度模型、卡点长分析、规格卡、快照、任务卡或大量表格。
- 不输出完成率、评分、权重、排期、成本、资源估算、负责人分配或绩效判断。
- 密钥和个人数据必须脱敏。