git:20261027.aaa6c55 to git:20261103.159a85e

---

name: project-docs-overview

---

# Project Docs Overview

写给需要理解项目或功能的人，而不是把类名和接口列表改写成段落。介绍业务目标与功能时使用 [项目总览模板](assets/project-overview.md)；介绍某项功能或改造时使用 [功能说明模板](assets/feature-description.md)；评估系统当前架构时使用 [架构总览模板](assets/architecture-overview.md)；为新开发者提供安装、运行、测试和排障说明时使用 [开发者上手手册模板](assets/developer-guide.md)。保留所选模板中全部二级章节及顺序，章节内可增加三级标题。资料不足时写明「待确认」或「暂无已知项」，删除空表格和模板提示。用户明确指定其他结构时按其要求。默认交付一份 Markdown；只有用户要求时才发布到飞书或修改目标项目的文档。明确要求按 PDLC 阶段产出时，使用对应 PDLC Skill 及其模板和状态流程。

## 一页说明与交互 HTML

用户明确要求“一页说明”“做成页面”“explainer”或交互 HTML 时，读取 [explainer 写作与交付规范](references/explainer.md)，按 Archify 3.2.0 的独立 Markdown 契约交付草稿、交互 HTML 与官方回执。继续遵循下方取证和业务核对要求；此模式使用结论与问题面板，不套用固定 Markdown 模板，也不运行 `validate_project_doc.py`。仅画图仍交由 `project-docs-diagram`。未指定页面交付时沿用默认 Markdown。

## 取证

先解析本 Skill 目录的真实路径，下文 `../../scripts/` 均相对该目录；安装为软链接时也使用解析后的路径。

1. 先读用户给的需求资料，以及目标仓库已有的 README、需求／设计文档和测试，确认项目要解决的问题与已有口径。用户提供的示例若只是版式参考，只借鉴结构，不复用其中的业务事实。若根目录有 `.codegraph/`，先用 CodeGraph 定位入口、调用链和影响面；没有索引就直接查源码，不替用户建索引。

2. 找到相关文件或符号后，用 `python3 ../../scripts/project_doc_context.py --source <目标仓库> --focus <文件/符号/路由/业务词> --output <工作目录>/focus.json` 提取该主题的文件、路由、配置、表候选及**新鲜**的 understand-anything 图谱节点。`--focus` 可重复；项目总览和架构总览先列主要模块，将已知主题合并到同一命令，例如 `--focus Order --focus Refund`，一次扫描取回各模块事实，再按模块核对和写作。同一任务复用这次取证结果，不按章节重复全仓扫描；逐个核对主题，任何主题无命中时 `needsBroaderSearch` 和 `warnings` 会提示补充取证，不能用其他主题命中代替；新增主题缺资料或源码已变化时再补充取证。不因一次无命中就认定能力不存在，改用入口或目录扩大搜索。需要完整清单时才用 `generate_architecture.py context`；不要把整个 JSON 一次灌入写作上下文。图谱过期或版本未知时聚焦工具会排除图谱内容并警告；重新从当前源码取证。新鲜的 domain flow 可作为业务流程线索，仍须核对入口、分支和结果。

3. 沿用户可见的主流程核对入口、业务处理、持久化／外部调用、异常去向和测试。项目总览按主要能力取样，不逐个复述接口；功能说明要核对相关分支、边界条件和反例。图谱或上下文提示与当前源码冲突时，以当前源码为准。

开发者上手手册还要核对实际存在的安装脚本、配置示例、运行与测试命令、项目规范和文档路径；不能把示例命令当作已验证的操作。

架构总览还要核对服务或模块清单、依赖方向、数据归属、配置与部署资料，以及已有 feature 设计记录。日志、指标、告警、容量与备份等运行状态需要运行或运维证据；只看到代码或配置时写明能证明的范围。

4. 分清**需求口径**、**代码现状**、**拟议改动**和**推断**。业务规则优先引用用户提供的需求资料；源码只能证明实现行为，不能替产品作决定。重要结论附近附可打开的来源链接或相对目标仓库的 `路径#L行号`。文首写 `> 源代码版本：<git HEAD 的完整 40 位哈希>`；非 Git 仓库写 `> 源代码版本：非Git仓库`。工作区有未提交源码时注明这一点及核对范围；没有依据的产品口径、工期和上线状态标为「待确认」，不要补造。

## 更新已有文档

已有文档时先运行 `python3 ../../scripts/project_doc_impact.py --source <目标仓库> --file <已有.md>`。它根据文档记录的版本、当前 Git 变更和 `路径#L行号` 给出直接受影响章节；`--changed <路径>` 可补充变更的本地 PRD。逐个复核受影响章节，并检查 `unmappedChangedFiles` 是否引入新能力或跨章节影响；图谱的单跳依赖只能当导航提示。保留人工写作和无关章节，更新过期来源、状态、图及文首版本后再验证。没有 Git 基线或只有外部 PRD 时，手工比较资料及全文，不把空影响清单当作无需更新。

## 写作

- 开头用几句话说清服务对象、解决的问题和主要结果，再展开模块与技术名词。每个主要功能写清触发者／条件、关键规则、用户或系统得到的结果；有金额、权限、状态等组合判据时用决策表，覆盖正常、边界与异常情况。

- **项目总览**按模板固定呈现目标与边界、功能地图、端到端主链路、模块职责与依赖、关键业务规则、运行与运维入口、已知限制。

- **架构总览**按模板固定呈现系统全景、核心流程、服务与模块边界、通信机制、数据架构、可观测性、可扩展性、架构评估、问题与改进。系统全景至少有一张标出边界、主要组件和关键依赖的架构图；核心流程至少有一张标出触发、处理、结果与重要分支的流程图。跨系统关系复杂时另补系统上下文图；有部署资料时说明运行节点与部署关系，有架构决策记录时写明取舍和影响。没有足够依据绘制时说明缺少的证据，并将文档标为未完成，不用想象中的组件或流程填图。单体项目按实际模块描述，不假设微服务、消息队列或网关。区分已确认问题、推测风险和待核实运行情况。五维评分只在每一维都有可引用的依据时给出 1–5 分；1 表示有严重阻塞，3 表示基本可用但有明确缺口，5 表示针对当前需求有充分验证证据，其余分值按风险和证据落点解释。优先用可观察的质量场景（触发、预期结果、验证方式）说明评分；缺少证据写「待评估」和所需资料，不为填满表格给分。

- **功能说明／改造方案**按模板固定呈现需求与口径、现状及缺口、端到端链路、核心方案与取舍、改动点、验证场景、风险及依赖。仅在已有计划资料支持时用三级标题补里程碑和工期。区分「已实现」「计划中」「待确认」，旧方案被订正时明确标出当前有效结论。

- **开发者上手手册**按模板固定呈现项目总览、环境准备、安装与启动、常用操作、开发约定、测试与验证、推荐阅读路线、文档索引、常见问题与排障。阅读路线从实际入口沿一条主流程到关键规则和复杂模块；可参考新鲜图谱的 `tour`、层级和复杂度，但模板摘要须回看源码。没有图谱时也能从入口与调用链写出路线。命令要写运行目录、前置条件和成功信号；只把实际执行过的检查写成「已验证」。

- 其他文档在图能帮助理解跨模块链路或规则分叉时加入：业务流程按参与者和步骤画，状态变迁标出条件，跨模块调用用时序或组件图。架构总览的全景图与核心流程图使用 `project-docs-diagram` 选图、取证、渲染和审图；将 Markdown、本地 PNG/SVG、可编辑图源和图的证据清单放在同一交付目录及其子目录内，用相对路径嵌入图片并在所在章节链接图源。原生图源旁保留 `project-docs-diagram` 的 `diagram.evidence.json`（v2），IR `deliver` 图则保留完整 bundle 及 `manifest.json`；严格校验据此核对源码锚点或交付回执。若交付环境原生支持 Mermaid，也可嵌入已渲染检查的 Mermaid 源码。记录官方引擎的验证结果，并逐张检查导出图片与图源、节点、箭头方向和分支是否一致；渲染成功并不证明架构含义正确。每张图在正文解释。接口细节可链接 `project-docs-api` 产物，正文只保留理解业务所需的字段。

- 按用户指定语言写作；未指定时沿用对话语言。把来源放在相关结论附近，保留已有资料的核心口径。交付前逐项核对业务名称、方向、状态、边界场景和来源；删除没有证据的肯定句。明确列出尚待业务方确认的问题，不能把它们写成已定方案。

将成品写到用户指定位置；未指定时放在目标仓库之外的工作目录。用户要求维护仓库的架构现状时，更新现有 `docs/ARCHITECTURE.md`，保留人工内容并用 Git 历史追溯；没有该文件时创建。写完后重新读取实际文件，运行 `python3 <本仓库>/scripts/validate_project_doc.py --kind project|feature|guide|architecture --file <成品.md> --source <目标仓库>` 检查框架、版本、每章来源及本地来源行号；架构总览再加 `--check-diagrams`，检查两类必备图、图片真实格式、交付目录内的相对资源、可编辑图源的官方引擎渲染、v2 图形证据覆盖及五维评分。修复失败项后再交付。该命令不证明引用与业务解释之间的语义关系，也不能证明已导出的图片与图源语义一致；须人工核对业务与架构判断及每张图的含义。用户明确指定其他结构时，遵从该结构并在交付时说明未运行固定模板检查。交付 Markdown 路径，并简述覆盖范围、验证结果与待确认事项。