======================================================================
opencode-graphgen —— 插件介绍文档
======================================================================
版本 0.4.2
许可 MIT（Copyright (c) 2026 江小东（研道人））
仓库 https://github.com/jiang216/--opencode-graphgen
形态 opencode MCP 服务端（主）+ 可选文件监听插件 + 命令行安装器
依赖 Node.js >= 20；Python 3.9+（引擎与校验脚本）
----------------------------------------------------------------------
一、它是什么
----------------------------------------------------------------------
opencode-graphgen 是一套「文档不出轨」的工具箱，装一次、全项目可用：
· 把项目的 Markdown 文档扫成一张图（谁引用谁、哪条需求对应哪段文档、
哪次提交动了哪个条目），并自动生成可提交的 graph.json / GRAPH.md /
graph.mmd。
· 用机械规则比对「文档里写的东西」和「代码里真实存在的东西」，
文档写错了（路由删了、菜单少了、章节编号跳了、清单没同步）直接报错，
而不是靠人肉 review。
· 顺带管代码仓库：有没有库、该不该建、这次部署对应哪个提交、
提交信息里带的需求条目能不能对上。
对使用者的感受是：在 opencode 里说一句「看下项目缺什么」，它会自己把
引擎、技能、AGENTS 约定、提交钩子铺好；之后每次改文档、每次提交，
图谱与校验自动跟上。
----------------------------------------------------------------------
二、解决什么问题
----------------------------------------------------------------------
1. 文档与代码脱节
接口加了、路由删了、菜单改了，文档还停在三个月前。doclint 用
R1~R8 八组规则做机械比对，不一致就报错，并在提交时拦截。
2. 文档之间的引用没人维护
graphgen 把文档、条目、提交编成节点与边，反链/正链随改随查，
再也不用全局搜索「谁引用了这一节」。
3. 新项目接入成本高
MCP 全局装一次，任意项目首次调用即自动部署（冲突预检 → 补齐引擎 →
写 AGENTS 片段 → 建库/快照），不污染已有文件。
4. 需求/文档/代码三条线对不上
提交信息带条目 ID（如 DG-009），repo 层自动建「条目 ↔ 提交」索引，
查一个需求就能看到它落在哪些提交里。
----------------------------------------------------------------------
三、组成
----------------------------------------------------------------------
组件 路径 作用
---------------- -------------------------- ----------------------
图谱引擎 tools/graphgen.py 扫 Markdown 生成
docs/graph.json、
docs/GRAPH.md、
docs/graph.mmd，
--check 只做 lint
防漂移校验 tools/doclint.py 文档 vs 事实源比对
（R1 章节编号 / R2 菜单 /
R3 清单 / R4 路由 /
R5 白名单 / R6 凭据 /
R7 条目文件 / R8 快照 /
markers 生成块）
仓库适配 tools/repo.py git/hg/svn 统一：
detect / status / init /
snapshot / links / guard
生成块写回 tools/gen_doc_slice.py 把事实源的生成结果写回
<!-- gen:name --> 块
MCP 服务端 mcp/ 全局一份，工具名 gcgl_*，
自带自动部署与提交约定
注入
opencode 插件 src/index.ts 可选（--plugin 安装）：
文件事件自动重生成 +
graphgen_query /
repo_query
技能 skills/graphgen/SKILL.md 教智能体查反链、跑生成器
安装器 install.py 一键幂等装进目标项目
（--hooks 附提交硬闸）
模板 templates/ doclint 配置示例、
pre-commit / commit-msg、
AGENTS 片段
----------------------------------------------------------------------
四、安装
----------------------------------------------------------------------
A. MCP（推荐，全局一次）
node mcp\install.mjs --install-dir D:\tools\graphgen-mcp
node mcp\install.mjs --install-dir D:\tools\graphgen-mcp --doctor
然后重启 opencode。之后在任意项目里直接对话：
gcgl_status 看项目缺什么、下一步做什么
gcgl_deploy {confirm:true} 铺引擎/技能/AGENTS/钩子
gcgl_query action=generate 生成或重生成图谱
gcgl_verify 一次跑完检查 + 仓库体检
B. 传统安装（不用 MCP / 需要保存即重生成）
python install.py --target <目标项目> [--hooks] [--plugin]
装完在目标项目验证：
python tools/graphgen.py --check
python tools/doclint.py
C. 全局引导器（可选）
bootstrap/ 装到 ~/.config/opencode/ 一次，之后任意项目把发行包
拷进去即自动安装。
----------------------------------------------------------------------
五、五个 MCP 工具
----------------------------------------------------------------------
gcgl_status 只读体检：引擎是否已装、是否过期、配置/技能/AGENTS/
仓库/快照状态、git 身份是否就绪。
gcgl_deploy 部署。默认只出计划；confirm=true 才写盘；有冲突文件
需 force=true。拒绝部署到引擎目录自身。
gcgl_query 文档图谱三合一：
action=query 按节点 ID 查正反链
（BUG:XX-001 / G-004 / DOC:xxx）
action=generate 重生成 graph.json / GRAPH.md / .mmd
action=check graphgen --check
action=doclint 文档漂移机械校验
gcgl_repo 代码仓库管理：
detect / status / init / snapshot / links / guard
除 init 外均只读；guard 不执行 add/commit/push。
gcgl_verify 聚合检查（graphgen --check + doclint + repo status），
提交前/改完文档后跑一次即可。
----------------------------------------------------------------------
六、日常流程
----------------------------------------------------------------------
新项目第一次
1. gcgl_status 看建议动作
2. gcgl_deploy confirm=true
3. 按提示补 docs/CHANGELOG.md 条目（缺省会自动写种子条目 DG-001）
改文档
1. 改完调用 gcgl_query action=generate
2. gcgl_verify 0 错 0 警再提交
改代码
1. 提交信息带条目 ID：fix(DG-009): ...
2. 提交后 gcgl_query node=DG-009 可看到关联提交
发版
node scripts\release.mjs --bump patch
版本号 → 自检 → 打包 dist zip → 打 tag → push → 建 GitHub Release
----------------------------------------------------------------------
七、配置
----------------------------------------------------------------------
引擎根目录 ~/.config/opencode/graphgen-mcp（安装时可用
--install-dir 改）
MCP 名称 gcgl（旧名 graphgen 会被识别为遗留项）
自动部署 autoDeploy:on，首次调用 query/repo/verify 时先做冲突预检
项目差异 一律写进该项目的 tools/doclint.config.json 与
tools/graphgen.config.json，脚本本身不硬编码任何项目路径
提交约定 改完由智能体自己提交；不 push、不 amend 他人提交、
不改全局 git 配置；身份只记 name/email，不存 token
----------------------------------------------------------------------
八、产物
----------------------------------------------------------------------
dist\opencode-graphgen-<版本>.zip 发行包（源码 + 工具 + 文档）
dist\opencode-graphgen-<版本>.zip.sha256 对应校验值
dist\social-preview.png 1280×640 社交预览图
dist\icons\ 图标全套（见下）
图标清单
favicon.ico 16/24/32/48/64/128/256 多尺寸
icon.svg 矢量主图
icon-small.svg 16~32px 简化变体（去细线、加粗节点）
icon-maskable.svg PWA maskable 矢量
icon-16 … icon-1024.png 11 个位图尺寸
apple-touch-icon.png 180×180（iOS 主屏）
icon-maskable-192/512 安卓自适应图标
网页接入
<link rel="icon" href="/favicon.ico" sizes="any">
<link rel="icon" type="image/svg+xml" href="/icons/icon.svg">
<link rel="apple-touch-icon" href="/icons/apple-touch-icon.png">
<meta property="og:image" content="/social-preview.png">
----------------------------------------------------------------------
九、目录
----------------------------------------------------------------------
mcp\ MCP 服务端、安装器、自检
src\ 旧 opencode 插件（可选）
tools\ 引擎 / doclint / 仓库 / 生成块
skills\ graphgen 技能
templates\ doclint 配置、提交钩子、AGENTS 片段
bootstrap\ 旧全局引导器
scripts\ 发布脚本
dist\ 发行产物（不入库）
README.md 总览与快速开始
INSTALL.md 详细安装方式
graphgen-config.md 图谱引擎配置字段
mcp\README.md MCP 服务端说明
----------------------------------------------------------------------
十、许可
----------------------------------------------------------------------
MIT License
Copyright (c) 2026 江小东（研道人）
可自由使用、修改、分发、商用，保留版权声明即可；
本软件按现状提供，不附带任何担保。
完整条款见仓库根目录 LICENSE 文件或 Release 中的 LICENSE。
======================================================================
渝公网安备50023002020384号 本站由:3daoshan.com 开发维护 