spec-wave 2.1.1

package/assets/ci/samples/pytest.yml.example

@@ -0,0 +1,49 @@
+# Harness Verify · 后端 pytest 样例（Python · FastAPI 等）
+#
+# 用途：复制为 .github/workflows/pytest.yml 并按仓裁剪。
+# 金样 POINTER（Ink）：Cyning12/ai-ink-brain-api-python · .github/workflows/pytest.yml
+# 本地路径（工作区对照）：ai-ink-brain-api-python/.github/workflows/pytest.yml
+#
+# 合并前必绿：pytest tests -m "not intent_eval and not intent_benchmark"（按仓调整 marker）
+
+name: pytest
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+      # - production   # 按需启用
+
+jobs:
+  pytest:
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    env:
+      # CI dummy 环境变量 — 替换为你的 .env.example 文档化变量名
+      # 禁止在 workflow 中写入真实密钥
+      EXAMPLE_API_KEY: "dummy-ci-key"
+      DATABASE_URL: "postgresql://u:p@localhost:5432/test"
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"      # 改为你的版本
+          cache: "pip"
+          cache-dependency-path: requirements.txt
+
+      - name: Install dependencies
+        run: pip install -r requirements.txt
+
+      - name: Run pytest
+        run: pytest tests -q --tb=short
+        # 有 slow/intent marker 时示例：
+        # run: pytest tests -m "not intent_eval and not intent_benchmark" -q --tb=short
+
+      # --- 可选：Ruff / mypy（L2 落地后启用）---
+      # - name: Ruff
+      #   run: ruff check .

package/assets/ci/samples/quality.yml.example

@@ -0,0 +1,56 @@
+# Harness Verify · 前端 quality 样例（Node/TS · Next 等）
+#
+# 用途：复制为 .github/workflows/quality.yml 并按仓裁剪。
+# 金样 POINTER（Ink）：Cyning12/ai-ink-brain · .github/workflows/quality.yml
+# 本地路径（工作区对照）：ai-ink-brain/.github/workflows/quality.yml
+#
+# 合并前三门禁：pnpm install --frozen-lockfile → pnpm lint → pnpm test → pnpm build
+# npm/yarn 用户：替换 install/lint/test/build 命令与 cache 配置。
+
+name: quality
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+      # - production   # 按需启用
+
+jobs:
+  lint-and-build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      # 版本以 package.json 的 packageManager 为真源（pnpm）
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v5
+
+      - name: Setup Node
+        uses: actions/setup-node@v5
+        with:
+          node-version: "24"          # 改为你的 LTS
+          cache: "pnpm"
+          cache-dependency-path: pnpm-lock.yaml
+
+      - name: Install
+        run: pnpm install --frozen-lockfile
+
+      # --- 可选：图谱 / 契约检查（有 docs/_tech_graph/ 时启用）---
+      # - name: Setup Python
+      #   uses: actions/setup-python@v5
+      #   with:
+      #     python-version: "3.11"
+      # - name: Tech graph check
+      #   run: python3 tools/tech_graph_check.py --input docs/_tech_graph
+
+      - name: Lint
+        run: pnpm lint
+
+      - name: Test
+        run: pnpm test
+
+      - name: Build
+        run: pnpm build

package/assets/ci/samples/skills-validate.yml.example

@@ -0,0 +1,38 @@
+# Optional · Agent Skills 校验（skills check + skills-ref validate · v2.23+）
+#
+# 用途：复制为 .github/workflows/skills-validate.yml（或并入既有 workflow 的一步）。
+# 真闸：包内 `npm test` 含 test/skills.test.js（drift/隔离/链接重写）；本样例面向
+#       接入仓或本包仓库的 GitHub Actions，提供官方规范校验器兜底。
+# 锁版本：skills-ref 的分发形态（npm 包名/版本）以官方仓库为准 · 接线时核实替换下方示例：
+#         github.com/agentskills/agentskills/tree/main/skills-ref
+
+name: skills-validate
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  skills:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      # npx-only：关闭 setup-node 默认 packageManager 缓存
+      - name: Setup Node
+        uses: actions/setup-node@v5
+        with:
+          node-version: "24"
+          package-manager-cache: false
+
+      - name: skills check（drift + frontmatter 约束）
+        run: npx --yes spec-wave skills check
+
+      # 官方规范校验器兜底（包名/版本为占位 · 接线时按官方仓库实际分发替换并锁版本）
+      - name: skills-ref validate（官方规范校验）
+        run: npx --yes @agentskills/skills-ref@<pin-version> validate ./skills

package/assets/ci/samples/tech-graph.yml.example

@@ -0,0 +1,55 @@
+# Harness Verify · tech-graph 样例（docs/_tech_graph + graph-compile）
+#
+# 用途：复制为 .github/workflows/tech-graph.yml 并按仓裁剪。
+# 适用：已接入 docs/_tech_graph/，且业务仓自备 scripts/graph-compile.sh。
+#
+# 摩擦（必读）：
+#   本 job 只用 npm/npx 跑 harness（或不装包管理器、只跑 compile 脚本）。
+#   若 package.json 声明 packageManager=pnpm，切勿开启 setup-node 的
+#   packageManager 自动缓存，否则会报：
+#     Unable to locate executable file: pnpm
+#   → 必须设 package-manager-cache: false
+#   对照：quality.yml.example 先 pnpm/action-setup，再 cache: pnpm。
+#
+# 业务仓须自备 ./scripts/graph-compile.sh（本产品仓不随包提供该业务脚本）。
+# 递归分层仓：compile 产物写 shared/graph.json（或仓内约定路径）。
+
+name: tech-graph
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+      # - production   # 按仓裁剪
+
+jobs:
+  compile:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      # npx-only / 无 pnpm 安装：关闭 setup-node@v5 默认 packageManager 缓存
+      - name: Setup Node
+        uses: actions/setup-node@v5
+        with:
+          node-version: "24"
+          package-manager-cache: false
+
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - name: Install graph compile deps
+        run: pip install pyyaml
+
+      # 可选：npx harness 辅助步骤（仍须 package-manager-cache: false）
+      # - name: harness graph check（示例）
+      #   run: npx --yes spec-wave graph --help
+
+      - name: Graph compile
+        run: ./scripts/graph-compile.sh
+        # 业务仓须自备该脚本；递归分层仓写 shared/graph.json

package/assets/coding_wiki/templates/README.md

@@ -0,0 +1,115 @@
+# coding_wiki · LLM 读序与目录约定
+
+复制本目录到用户仓 **`docs/coding_wiki/`**（含 `topics/`）。
+
+> **纪律级别**：`recommended`（人读 / Agent 读序建议）。**不是** `task close` / `wiki_delta` 硬闸——漏目录仍可关账（字段闸见 USER_GUIDE §6.0 / §6.0b）。
+
+---
+
+## 默认两层（起步）
+
+业务仓目标形态：
+
+```text
+docs/coding_wiki/
+  README.md           # 读序 + 本约定 + 加深指引
+  _index.md           # 可选主题索引
+  stable.md           # 稳定度三件套留根（仅此类 + 读序）
+  context.md
+  volatile.md
+  topics/             # 第 2 层：一主题一薄页，指针 docs/** 真值
+    *.md
+```
+
+| 路径 | 层 | 说明 |
+|------|-----|------|
+| [`README.md`](README.md) | 读序 | 本文件 · 目录约定真值 |
+| [`_index.md`](_index.md) | 索引 | 可选 · 主题→页指针 |
+| [`stable.md`](stable.md) | stable | 短摘要 · 规范十二条 · IDE 规则指针 |
+| [`context.md`](context.md) | context | L2、PROJECT_CONFIG 类指针 |
+| [`volatile.md`](volatile.md) | volatile | 本 task 必读（由 task 引用） |
+| [`topics/`](topics/) | 主题 | **一主题一薄页** · 勿在根堆长文 |
+
+invoke §3 应 **pointer** 到本目录，勿重复贴长文。
+
+---
+
+## 原则
+
+1. **根禁止堆主题长文**；主题进 `topics/`（根只留读序 + 稳定度三件套 + 可选 `_index`）。
+2. **勿按日期 / PR / task_slug 建目录**（人扫会炸；时间线放 task/invoke，不放 wiki 树）。
+3. **`wiki export` 不依赖目录深度**；关系图仍靠双括号 wikilink / 相对 `.md` 链（见下「目录 vs 图」）。
+4. 本约定为 **recommended**：整理目录可写在 `wiki_delta=path`，但 **缺两层 / 未加深 ≠ close BLOCK**。
+
+---
+
+## 目录 vs 关系图
+
+| | 文件夹树 | `wiki export` 图 |
+|--|----------|------------------|
+| 服务对象 | **人**扫目录、控爆炸 | Agent / Web / Obsidian **边** |
+| 靠什么 | 两层起步 + 加深阈值 | 双括号 wikilink + md 相对链 |
+| 加深后 | `git mv` 到 `topics/<子域>/` | **边不断**（修好链即可） |
+
+详述与关账字段：见薄指针页 [`POINTER_USER_GUIDE.md`](../../docs/POINTER_USER_GUIDE.md)（原文不随包发布）「Wiki 目录 vs 关系图」· `wiki_delta` 决策树见原文 **§6.0b**（本文不重复）。
+
+> **防踩坑（v2.19+）**：叙述里勿写裸双括号字面当作「格式说明」（会被 `wiki export` 当边解析）；请写「双括号 wikilink」，互链只指向真实页。
+
+---
+
+## 加深阈值（第 3 层）
+
+出现任一信号 → 考虑在 `topics/` 下加**子域**（例：`topics/obs/`、`topics/harness/`），仍保持薄页：
+
+| 信号 | 动作 |
+|------|------|
+| 某目录（含 `topics/`）`.md` **≥ 15**，或人已难扫 | 按子域拆第 3 层 |
+| 单页过长（**>~80 行**）或多主题混写 | **先拆页**，再考虑子域 |
+| **连续 3 个 task** 打同一主题前缀 | 可**提前**建子域，不必等满 15 |
+
+未达阈值时：**不要**为「好看」提前深套目录。
+
+---
+
+## 加深操作清单
+
+1. `git mv` 页到 `topics/<子域>/`（或拆新薄页）
+2. 修双括号 wikilink / 相对 md 链（含 README、`_index`、stable/context）
+3. 更新 [`_index.md`](_index.md) / 本 README 指针
+4. `npx spec-wave wiki export --json --target <仓根>` 校验边仍在（旧包 `--root` 旗标本包未接线，以 `--target` 指定目标根）
+5. 本 task 元信息 **`wiki_delta`** = 改动 path（字段闸不变；目录形状本身不闸）
+
+---
+
+## 样例互链（v2.18.1+）与 topics 演示（v2.18.2+）
+
+根三件套含样例互链；`topics/` 下示例薄页演示**两层**（非业务真值）：
+
+- [[topics/wiki_layout]] · [[topics/wikilinks_export]]
+
+拷贝到业务仓后：
+
+```bash
+npx spec-wave wiki export --json --target .
+# 业务仓：--target <仓根>（旧包 `--root coding_wiki/templates` 旗标本包未接线）
+```
+
+---
+
+## 关账与晋升（v2.18+）
+
+1. task 元信息填 **`wiki_delta`**：改了哪份 wiki / `none`+理由 / `n/a`（未启用 WikiTrack）。  
+2. **`experience_capture=required` 且 `wiki_delta=path`**：经验节须含晋升指针（`Wiki:` / `wiki_promoted:` / `coding_wiki` 路径）。  
+3. volatile：关账后归档要点或清空，避免 stale；可复用条目上移 **context** / **stable**。  
+4. 导出关系图（供 Web/Obsidian 对照，本包不渲染）：见上命令。
+
+---
+
+## 修订记录
+
+| 日期 | 说明 |
+|------|------|
+| 2026-07-28 | 关账晋升 + wiki export 指针 |
+| 2026-07-28 | v2.18.1 · stable/context/volatile 样例互链 |
+| 2026-07-28 | v2.18.2 · 两层目录约定 · 加深阈值/清单 · topics 示例 |
+| 2026-07-28 | v2.19.0 · 叙述防踩坑（勿裸双括号字面） |

package/assets/coding_wiki/templates/_index.md

@@ -0,0 +1,19 @@
+# coding_wiki · 主题索引（可选）
+
+> 拷贝到业务仓后按需维护。根下主题长文应迁入 [[topics/wiki_layout]] 一类薄页，勿在此堆正文。
+
+## 模板样例（v2.18.2+）
+
+| 主题 | 页 |
+|------|-----|
+| 目录两层 / 加深 | [[topics/wiki_layout]] |
+| 链接与 export | [[topics/wikilinks_export]] |
+
+## 业务仓填写
+
+| 主题 | 页 | 真值指针 |
+|------|-----|----------|
+| （例）观测 | `topics/obs/…` | `docs/**` |
+| （例）Harness | `topics/harness/…` | `docs/harness/**` |
+
+读序与约定：[[README]]

package/assets/coding_wiki/templates/context.md

@@ -0,0 +1,18 @@
+# coding_wiki · context
+
+> **层**：context · 项目级指针（变更频率低于 volatile）
+
+## 相关页（样例互链 · v2.18.1+）
+
+- 稳定摘要：[[stable]]
+- 本 task：[[volatile]]
+- 目录说明：[[README]]
+- 主题索引：[[_index]] · [[topics/wikilinks_export]]
+
+## 待填写
+
+- `docs/standards/CODING_*_L2_*.md`  
+- `docs/meta/PROJECT_CONFIG_*.md`（若有）  
+- `docs/_tech_graph/00_main.md` 读序  
+
+由安装向导或人工在接入业务仓时补全链接。

package/assets/coding_wiki/templates/stable.md

@@ -0,0 +1,26 @@
+# coding_wiki · stable
+
+> **层**：stable · 每次会话可注入的短摘要（≤15 行正文建议）
+
+## 相关页（样例互链 · v2.18.1+）
+
+- 读序总览：[[README]]
+- 项目指针：[[context]]
+- 本 task 易变上下文：[[volatile]]
+- 主题样例（两层）：[[topics/wiki_layout]]
+
+## 编码底线（L1 摘要占位）
+
+1. 最小改动 · 不扩 scope  
+2. 类型严格 · 禁 `any`（TS）  
+3. 错误结构化返回  
+4. 测试策略见 task `test_strategy`  
+5. 图谱优先于纯文本臆造  
+
+完整 L1：用户仓 `docs/standards/CODING_BASELINE_L1_*.md`（由 `standards/` 模板生成）。
+
+## IDE 入口
+
+- Cursor：`.cursor/rules/*`  
+- Claude Code：`CLAUDE.md`  
+- 通用：`AGENTS.md`

package/assets/coding_wiki/templates/topics/wiki_layout.md

@@ -0,0 +1,13 @@
+# 主题 · Wiki 目录两层（模板样例）
+
+> **薄页**：约定真值在 [[README]]；本页仅演示 `topics/` 第 2 层。业务仓请改写为本仓主题并指针 `docs/**`。
+
+## 要点
+
+- 根：读序 + stable/context/volatile + 可选 `_index`
+- 主题长文 → `topics/`；勿按日期/PR/task_slug 建目录
+- ≥15 页或难扫 → 子域第 3 层（见 README 加深阈值）
+
+## 相关
+
+- [[README]] · [[_index]] · [[topics/wikilinks_export]]

package/assets/coding_wiki/templates/topics/wikilinks_export.md

@@ -0,0 +1,13 @@
+# 主题 · wikilink 与 wiki export（模板样例）
+
+> **薄页**：图靠链接，不靠文件夹深度。CLI：`wiki export --json`（schema `harness.wiki_graph.v1`）。
+
+## 要点
+
+- 双括号 wikilink + 相对 `.md` 链 → nodes/edges
+- 加深 `git mv` 后须修链，再 export 校验
+- 字段闸（`wiki_delta`）≠ 目录形状闸（recommended）
+
+## 相关
+
+- [[README]] · [[topics/wiki_layout]] · [[stable]]

package/assets/coding_wiki/templates/volatile.md

@@ -0,0 +1,25 @@
+# coding_wiki · volatile
+
+> **层**：volatile · **本 task 专属**；由 task「给执行帽必读」或 invoke §3 引用
+
+## 相关页（样例互链 · v2.18.1+）
+
+- 稳定层：[[stable]]
+- 项目层：[[context]]
+
+## 用法
+
+1. 每个 active task 在正文或 invoke 中 pointer 到本文件或 task 内小节  
+2. Epic 子 task 可共用 Epic 级 volatile 片段  
+3. 关账后归档或清空，避免 stale 上下文  
+
+## 本 task（占位）
+
+- task_slug：`<填写>`  
+- 必读图谱：`docs/_tech_graph/<flow>.md`  
+- `code_quality_bar`：`<strict | recommended | not_applicable>`  
+
+## 关账后
+
+- 可复用条目 → 晋升 [[context]] / [[stable]]  
+- 本文件清空或归档，避免下一 task 读到 stale volatile  

package/assets/docs/POINTER_ONBOARDING.md

@@ -0,0 +1,9 @@
+# 薄指针 · ONBOARDING
+
+> 原引用目标 `docs/ONBOARDING.md`（cyning-harness 仓新人/新仓接入指南）。
+
+- **用途**：Harness 接入档位（S0～S3）、五轨检查清单与嵌入步骤的总入口文档。
+- **本文档不随 dsh-coding-kit 发布**（包内无 docs/ 正文体）。
+- **真值去向**：私仓 `cyning-harness/docs/ONBOARDING.md`（内部文档，未公开）。
+- kit 自仓 dogfood 见源码 `docs/_tech_graph/`（**不随 npm 包发布**；原文 ONBOARDING 仍在私仓）。
+- 历史先例：旧 npm 包 @cyning/harness@1.0.2 曾随包发布 docs/（旧包已弃用，现行为 dsh-coding-kit）。

package/assets/docs/POINTER_RUNBOOK_wiki_delta.md

@@ -0,0 +1,18 @@
+# 薄指针 · RUNBOOK_upgrade_wiki_delta
+
+> 原引用目标 `docs/RUNBOOK_upgrade_wiki_delta_v1_zh.md`（lint-wiki-delta 升级运维手册）。
+
+- **用途**：无 monorepo checkout 时经 `npm pack` / GitHub raw 升级 wiki-delta 样例的运维步骤（原文 §5.1）。
+- **本文档不随 dsh-coding-kit 发布**（包内无 docs/ 正文体）。
+- **真值去向**：私仓 `cyning-harness/docs/RUNBOOK_upgrade_wiki_delta_v1_zh.md`（内部文档，未公开）。
+- 历史先例：旧 npm 包 @cyning/harness@1.0.2 曾随包发布 docs/（旧包已弃用，现行为 dsh-coding-kit）。
+
+## 诊断码表（lint-wiki-delta / task lint E8 · 本仓真值）
+
+| code | 档位 | 触发 | 处置 |
+|------|------|------|------|
+| `wiki_delta_missing` | 默认档（exit 2） | `## Harness 元信息` 表内无任何 `wiki_delta` 行 | 在 `## Harness 元信息` 表格补 `| **wiki_delta** | \`path|none|n/a\` |` 行 |
+| `wiki_delta_wrong_section` | 默认档（exit 2 · 替代 missing 不双报） | `wiki_delta` 行写在 `## Harness 元信息` 之外的节（如 `## Harness`） | detail 含所在节名 + 行号；把该行移入 `## Harness 元信息` 表格内（诊断非兼容：解析器仍只认权威节名） |
+| `wiki_delta_invalid` | `--strict` 追加（exit 2） | 值非 path 形态亦非 none/n/a | 改为 path（含 `/` 或 `.`）或 none/n/a |
+| `wiki_delta_path_missing` | `--strict` 追加（exit 2） | path 形态值相对仓根不存在 | 建文件或改指向 |
+| task lint `E8` | `task lint --file`（error · 无 draft 豁免） | `## Harness 元信息` 节在但缺 `wiki_delta` 行（仅查存在性） | 补行即过；错节场景文案指向正确节名并带行号（与 `close_wiki_delta` 对齐） |

package/assets/docs/POINTER_SDD_HAT_FLOW.md

@@ -0,0 +1,8 @@
+# 薄指针 · SDD_HAT_FLOW
+
+> 原引用目标 `docs/methodology/product/SDD_HAT_FLOW_v2_zh.md`（SDD 帽链流程方法论）。
+
+- **用途**：10-spec → 20-audit → 30/40/50 帽链流程、图谱分期（路径 D）与 Extended 帽（00/50/handoff）说明。
+- **本文档不随 dsh-coding-kit 发布**（包内无 docs/ 正文体）。
+- **真值去向**：私仓 `cyning-harness/docs/methodology/product/SDD_HAT_FLOW_v2_zh.md`（内部文档，未公开）。
+- 历史先例：旧 npm 包 @cyning/harness@1.0.2 曾随包发布 docs/（旧包已弃用，现行为 dsh-coding-kit）。

package/assets/docs/POINTER_USER_GUIDE.md

@@ -0,0 +1,8 @@
+# 薄指针 · USER_GUIDE
+
+> 原引用目标 `docs/USER_GUIDE_v1.0_zh.md`（coding_wiki 用户指南）。
+
+- **用途**：Wiki 目录 vs 关系图、`wiki_delta` 决策树（原文 §6.0b）等使用说明。
+- **本文档不随 dsh-coding-kit 发布**（包内无 docs/ 正文体）。
+- **真值去向**：私仓 `cyning-harness/docs/USER_GUIDE_v1.0_zh.md`（内部文档，未公开）。
+- 历史先例：旧 npm 包 @cyning/harness@1.0.2 曾随包发布 docs/（旧包已弃用，现行为 dsh-coding-kit）。

package/assets/graph/stubs/README.md

@@ -0,0 +1,6 @@
+# graph/stubs
+
+产品包 **不内置** 某上游 OSS 的预填图谱。
+
+- 默认 bootstrap：仅用 [`../templates/`](../templates/)（通用占位）+ 删除 `10_flow_MAIN*`。
+- 项目专用快照：本包 **不提供**；stub 加载机制 **未实现**（声明路径 · 决策见 DEF-007 / DEC-BATCH-1.3.0）。

package/assets/graph/templates/00_main.graph.yaml

@@ -0,0 +1,72 @@
+graph_id: "00_main"
+title: "顶层流程总图"
+description: "模板包主入口分发与典型子流程路由"
+version: "2026-06-30"
+
+nodes:
+  - id: "Q"
+    label: "用户 / 客户端请求"
+  - id: "E"
+    label: "应用入口"
+  - id: "M1"
+    label: "核心业务处理"
+  - id: "M2"
+    label: "次要路径"
+  - id: "ADM"
+    label: "Admin / Job"
+  - id: "FLOW_MAIN"
+    label: "主路径子流程"
+  - id: "FLOW_DOC"
+    label: ">10_flow_MAIN.md"
+  - id: "DB"
+    label: "持久化"
+  - id: "STRUCT_DOC"
+    label: ">01_struct.md"
+
+edges:
+  - from: "Q"
+    to: "E"
+    label: "->"
+    anchors:
+      - path: "src/main.py"
+        line: 1
+      - path: "app/router/index.ts"
+        line: 1
+  - from: "E"
+    to: "M1"
+    label: "主路径 A"
+    anchors:
+      - path: "handlers/resource.py"
+        symbol: "handle_create"
+  - from: "E"
+    to: "M2"
+    label: "主路径 B"
+    anchors:
+      - path: "handlers/health.py"
+        symbol: "health_check"
+  - from: "E"
+    to: "ADM"
+    label: "管理/批处理"
+    anchors:
+      - path: "jobs/ingest.py"
+        symbol: "run_sync"
+  - from: "M1"
+    to: "FLOW_MAIN"
+    mark: "::triggers"
+    type: "triggers"
+  - from: "FLOW_MAIN"
+    to: "FLOW_DOC"
+    label: "加载"
+  - from: "M1"
+    to: "DB"
+    label: "->"
+    anchors:
+      - path: "db/repository.py"
+  - from: "ADM"
+    to: "DB"
+    label: "->"
+    anchors:
+      - path: "db/repository.py"
+  - from: "E"
+    to: "STRUCT_DOC"
+    label: "加载"

package/assets/graph/templates/00_main.md

@@ -0,0 +1,85 @@
+---
+graph_id: 00_main
+version: 2026-06-30
+generated_at: sha256-8d90cf7f068bb199
+source: 00_main.graph.yaml
+---
+
+# 顶层流程总图
+
+模板包主入口分发与典型子流程路由
+
+## Mermaid
+
+```mermaid
+flowchart TD
+    Q[["用户 / 客户端请求"]]
+    E[["应用入口"]]
+    M1["核心业务处理"]
+    M2["次要路径"]
+    ADM["Admin / Job"]
+    FLOW_MAIN[["主路径子流程"]]
+    FLOW_DOC[">10_flow_MAIN.md"]
+    DB["持久化"]
+    STRUCT_DOC[">01_struct.md"]
+
+    Q --> E
+    %% → src/main.py#L1
+    %% → app/router/index.ts#L1
+    E -->|"主路径 A"| M1
+    %% → handlers/resource.py::handle_create
+    E -->|"主路径 B"| M2
+    %% → handlers/health.py::health_check
+    E -->|"管理/批处理"| ADM
+    %% → jobs/ingest.py::run_sync
+    M1 -->|"::triggers"| FLOW_MAIN
+    FLOW_MAIN -->|"加载"| FLOW_DOC
+    M1 --> DB
+    %% → db/repository.py
+    ADM --> DB
+    %% → db/repository.py
+    E -->|"加载"| STRUCT_DOC
+
+    classDef phase fill:#e1f5fe,stroke:#01579b,stroke-width:2px
+    classDef doc fill:#fff8e1,stroke:#ff6f00,stroke-width:1px
+    classDef infra fill:#e8f5e9,stroke:#2e7d32,stroke-width:1px
+    class Q,E phase
+    class FLOW_DOC,STRUCT_DOC doc
+```
+
+## Structured Data
+
+### Nodes
+
+| ID | Label | Kind |
+|----|-------|------|
+| Q | 用户 / 客户端请求 |  |
+| E | 应用入口 |  |
+| M1 | 核心业务处理 |  |
+| M2 | 次要路径 |  |
+| ADM | Admin / Job |  |
+| FLOW_MAIN | 主路径子流程 |  |
+| FLOW_DOC | >10_flow_MAIN.md |  |
+| DB | 持久化 |  |
+| STRUCT_DOC | >01_struct.md |  |
+
+### Edges
+
+| From | To | Mark | Type | Label | Anchors |
+|------|----|------|------|-------|---------|
+| Q | E | -> | depends_on | -> | 2 anchor(s) |
+| E | M1 | -> | depends_on | 主路径 A | 1 anchor(s) |
+| E | M2 | -> | depends_on | 主路径 B | 1 anchor(s) |
+| E | ADM | -> | depends_on | 管理/批处理 | 1 anchor(s) |
+| M1 | FLOW_MAIN | ::triggers | triggers |  |  |
+| FLOW_MAIN | FLOW_DOC | -> | depends_on | 加载 |  |
+| M1 | DB | -> | depends_on | -> | 1 anchor(s) |
+| ADM | DB | -> | depends_on | -> | 1 anchor(s) |
+| E | STRUCT_DOC | -> | depends_on | 加载 |  |
+
+## Sub-graph Links
+
+- `Struct`: [`01_struct.md`](01_struct.md)（手写 · 无 `.graph.yaml`）
+- `Version`: [`02_version.md`](02_version.md)（手写 · 无 `.graph.yaml`）
+- 子图编辑源见 `docs/_tech_graph/*.graph.yaml`
+