Graph Engineering · 工作流图工程

让 AI 把复杂工作梳理成一张可以检查、分工、恢复和验收的工作流图：每一步由谁负责、读什么、写什么、把哪些结果交给下一步，以及什么时候可以宣布完成。

这里的“图”描述工作如何执行。知识图谱、数据库关系或研究对象本身是另一层数据，不要混在一起。核心规则见 SKILL.md。

本仓库收录完整 skill：主规则、AI 工具显示配置、参考规范、校验脚本、示例与测试。它是一套供 AI 使用的工作规则和 Python 校验工具；仓库没有通用任务执行器，节点中的命令需要由执行者或项目自己的运行器调用。

它帮助解决什么

• 多步骤任务中，明确依赖关系、责任和交接内容。
• 检查潜在并行步骤是否会写入同一位置。
• 为分支、跳过、阻塞和失败保留明确状态。
• 给反馈循环设置触发条件与次数上限。
• 区分“命令跑完了”和“产物通过了领域验收”。
• 将新方法或失败经验转化为有证据、可检查、可回退的规则修改。

一步就能完成的任务通常不需要工作流图。角色名称也不等于独立审查；需要独立判断时，仍要确认实际执行者和证据来源彼此独立。

使用方法

克隆完整仓库：

git clone https://github.com/bydtesla1609/graph-engineering.git

将 graph-engineering 文件夹放入所用 AI 工具支持的技能目录，保持 SKILL.md 位于该文件夹根目录，同时保留配套子目录。也可以直接把 SKILL.md 的路径交给能读取本地文件的 AI。

支持技能调用的工具中，可以这样使用：

用 $graph-engineering 梳理这个项目的数据处理流程。先画出现有流程，再指出依赖、读写冲突、失败恢复和最终验收条件。

用 $graph-engineering 检查这份 workflow JSON，说明哪些步骤可以并行，哪些必须先后执行。

用 $graph-engineering 评估这次失败能否形成通用规则。保留适用条件、反例、验证方法与回退方式。

工作过程

1. 调查现状：找到实际入口、权威输入、产物、校验命令和恢复点。
2. 定义工作图：给节点声明责任和读写范围，给边声明依赖与允许交接的字段。
3. 检查结构：检查循环、不可达节点、写入冲突和最终验收节点。
4. 按图执行：只安排依赖已满足且运行条件安全的步骤；失败时保留可恢复记录。
5. 领域验收：由项目自己的判据判断产物是否合格，根控制器汇总证据并决定是否完成。
6. 有据改进：新规则先经过证据与适用范围检查，再修改实现并复验。

通用层负责工作如何组织；具体项目负责什么算正确。例如数学项目仍需数学证据，软件项目仍需自己的测试。

文件导航

本地校验

脚本使用 Python 标准库，无需安装第三方包。在仓库根目录运行：

python -m unittest discover -s tests -v
python scripts/validate_workflow_graph.py examples/conditional-routing-v2.json --run examples/conditional-routing-v2-run-fast.json
python scripts/validate_graph_change.py examples/conditional-routing-v2-change-set.json
python scripts/validate_graph_change.py examples/skillalchemy-change-set.json

这些检查验证图结构、分支记录和修改提案的约束。它们不会运行图中声明的业务命令，也不证明外部来源真实、业务产物正确或多名独立执行者确实参与了审查。示例运行记录用于演示格式，不代表仓库发布时执行了该业务流程。

来源与保留说明

首次发布保留已有 skill 的全部 13 个源文件，新增本说明和 Git 文件管理配置。后续以本仓库提交记录标识版本。

规则演进参考了 SkillAlchemy 的对照与准入思路，固定来源版本和边界保留在 evolution.md 中；本仓库不包含或自动执行它的上游运行器。

条件分支修改提案 中保留了旧版交接快照的 git:... 来源标识和哈希。它们用于记录历史依据，对应历史快照未包含在本仓库中，公开读者不能仅凭本仓库复核这些快照内容。测试中的 C:\Users\someone\private\evidence.md 是用于验证拒绝本机绝对路径的虚构输入。

English

Graph Engineering is an AI skill for designing and auditing typed work graphs with explicit roles, bounded handoff packets, write-conflict checks, conditional routing, validation gates, and bounded feedback loops. It includes the full skill, reference contracts, standard-library Python validators, examples, and tests. Execution and domain acceptance remain the responsibility of the host project; the validators do not run node commands or establish semantic correctness.