Project Docs Overview

Turn code and project materials into source-backed project overviews, feature explanations, architecture documentation, and developer onboarding guides. On request, create interactive Archify explainers or beginner-friendly HTML illustrations adapted to the reader and purpose.

中文文档 / Chinese documentation

若当前 Skill 目录下存在 .bundle 且其 ../../ 不是本集合的 Git 检出，先读取 .bundle/skills/project-docs-overview/GUIDE.md 并以该目录为 Skill 真实目录；其中的共享脚本、资料和其他 Skill 均来自同一快照。通过 npx skills update <已安装的本集合 Skill 名称> 更新此类安装，按实际作用域加 -g 或 -p；不运行快照内依赖 Git 检出的更新命令。

生成或修订前按读者与用途约定确定需要解释的部分；说明页面也可面向领域专家，不默认使用 ELI5。读者适配保留已选模板、来源与事实口径。

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

一页说明与交互 HTML

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

用户要求“零基础图解”或面向新手的图解页面时，使用同一规范的 ELI5 写作方式：按读者已有知识及解释目标，选择概念关系、业务流程、规则判断、技术机制、问题因果、方案取舍、变更影响、角色培训或客户说明的组织方式，不套用统一流程图。ELI5 不限技术主题，也不表示把成人当儿童。只说“ELI5 解释”“通俗解释”“给业务人员看”是在指定表达方式，默认在当前回答或已选文档中解释；明确要求图解成品或 HTML 时才生成页面。仅有业务材料、没有目标仓库时按该规范的材料取证方式处理，不要求先建仓库或扫描代码。不改变仅画图、产品交互原型及正式文档的既有分工。

取证

先解析本 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 路径，并简述覆盖范围、验证结果与待确认事项。