--- name: project-docs-diagram description: Create source-backed technical diagrams from a repository, or validate and export native Mermaid, PlantUML, draw.io, and Archify diagrams; not for endpoint API documentation. --- # Project Docs Diagram Produce auditable diagrams from repository evidence. A short request such as “根据代码生成架构图” is sufficient; infer scope, view, engine, and export without requiring a reference image or a detailed prompt. The agent interprets architecture and business meaning; scripts validate source anchors and supported diagram semantics. Keep generated files outside the analyzed repository unless the user asks to commit them. Read [the diagram standard](../../docs/DIAGRAM_STANDARD.md) when selecting a profile. The draw.io landscape theme and GitHub template decision are documented in [the template research](../../docs/ARCHITECTURE_TEMPLATE_RESEARCH.md). Archify `explainer` 是独立的一页文档模式；用户要求项目说明页面时读取 [project-docs-overview](../project-docs-overview/SKILL.md)，不将它作为 typed JSON 图型传入本 Skill 的原生脚本。 ## Workflow 1. Resolve this skill's real directory. The CLI is `../../scripts/generate_architecture.py` relative to that directory. Run `python3 context --source --output /context.json`. For a relevant symbol discovered in the first pass, repeat `--focus ` to include its CodeGraph callees. Do not create a CodeGraph index on the user's behalf. 2. Inspect the complete context. `files`, `symbols`, `routes`, `configKeys`, and `tables` are never capped; scans are candidates to verify. When `codeGraph` is present, start from its structured classes, routes, and focused calls; use `codegraph explore`/`node` to follow relevant paths. A freshness warning means graph data is only a lead: verify against current source. If `knowledgeGraph` or `domainGraph` exists, use its IDs/flows as navigation and semantic draft, with the same freshness caveat. Graph calls are code facts, not automatically architecture relationships. For a large context, inspect by module without silently discarding modules. 3. Choose a semantic profile before an engine. A short “项目／模块架构图” request defaults to `architecture-landscape`; C4, BPMN, UML sequence, and ERD follow their own notation. Write typed IR v2 using [the view contract](references/diagram-view-ir.md), cite source for every element and relation, and reserve `EXTRACTED` for labels literal on cited lines. Do not infer infrastructure or future components from examples. 4. For a new landscape overview, run `python3 inventory --source --output /candidates.json` (use `--scope-prefix` only for an explicit module scope). Review every generated candidate and its `members` against current source and CodeGraph, add source-backed `manualCandidates` for important relationships the scanner missed, and give each candidate one `overview`, `detail`, or reasoned `excluded` decision. A mapped element or relation must cite every member line of that candidate. Usage candidates require a relation and detail decisions require nearby detail IRs. See [the coverage schema](references/diagram-view-ir.md). Do not exclude an in-scope dependency merely to reduce density. 5. For a new landscape, run `python3 validate --source --ir /architecture-ir.json --strict-coverage`, then `python3 deliver --source --ir /architecture-ir.json --output /bundle --format drawio --export-for drawio:png`. `deliver` renders every declared detail before publishing the bundle. `coverageCheck: pass` is required; `declared_only` and `not_declared` are legacy compatibility states. For other profiles use `render` and the selected official engine. Supported exports remain Mermaid/PlantUML `svg|png|pdf`, draw.io `svg|png|jpg|pdf`, and Archify `svg|png|jpg|webp|webm|pdf`. Unsupported combinations fail rather than silently changing notation. If the selected official renderer is missing, run `python3 /scripts/install_renderers.py --auto --engine ` once and retry. This uses the shared Codex/Claude Code renderer setup. An explicit `install.sh --no-engines` disables this automatic step; report that choice or an installation error instead of silently switching engines or export formats. 6. Open every exported image and inspect scope, arrow direction, labels, overlap, and unexplained IDs. `geometryCheck: pass` checks card bounds and overlap in editable draw.io XML; it cannot prove edge routing or visual quality. The landscape limit is 12 elements and 12 relations per view, so split dense diagrams into focused views with traceable candidate decisions. Report actual visual review separately from official `rendererChecks`. ## Official native diagrams outside IR v2 Read [the renderer capability audit](../../docs/RENDERER_CAPABILITY_AUDIT.md) and [the native authoring contract](references/native-diagrams.md) when the user requests another diagram type supported by Mermaid, PlantUML, draw.io, or Archify. For an existing native `.mmd`, `.puml`, `.drawio`, or Archify `.json`, run `python3 ../../scripts/render_native_diagram.py --engine --input --output --export png` (repeat `--export` for desired formats). The command runs the actual official engine; Archify 3.2.0 accepts all ten official typed modes: architecture, workflow, sequence, dataflow, lifecycle, erd, tree, class, timeline, and waterfall. Follow the native authoring contract for material-item pointers and timing evidence. For a **new** diagram outside IR v2, choose the notation, verify source, author official native syntax, and attach a [version 2 evidence manifest](references/native-diagrams.md) when it makes repository claims. Local PlantUML includes are inventoried and packaged. Standard-library or remote includes report `claimCoverage: partial`; disclose that limitation or use a self-contained source before claiming complete coverage. Review inferred claims and the exported image. `claimSemantics: not_proven` remains even when anchors and item coverage pass. The source-line check proves that a cited snippet exists at that location. It does not prove a business interpretation, runtime route, or relationship. Review `INFERRED` and `AMBIGUOUS` claims against multiple code paths before presenting them as conclusions.