word-to-schema

一个面向 RPA 需求工程的多 IDE 工具链，但它的核心价值不是单个 skill，而是 完整工作流：把 Word 需求文档逐步沉淀为可执行协议、任务列表与受控执行过程。

如果只用一句话概括这个项目，可以理解为：

这是一个围绕 word-to-schema-pipeline 与 bug-diagnosis-workflow 构建的安装与执行工具，用来把“原始需求”稳定推进到“可执行开发任务”，并在出问题时进入标准化排查流程。

工作流优先理解

建议先理解工作流，再去看具体 skill。

这个项目当前有两条主线：

1. 主开发工作流

Word / DOCX
-> Markdown
-> Requirement Audit
-> Final Spec
-> Protocol JSON
-> Tasks JSON
-> Controlled Execution

对应主工作流：

• word-to-schema-pipeline

2. Bug 排查工作流

Problem Definition
-> Hypothesis Ranking
-> Reproduction / Tests
-> Diagnosis Summary
-> Fix / Regression

对应问题排查工作流：

• bug-diagnosis-workflow

也就是说，这个项目的重点不是“提供一堆离散 skill”，而是：

1. 先把需求转成结构化输入
2. 再把歧义收敛
3. 再生成协议
4. 再把协议拆成任务
5. 再按顺序执行
6. 如果执行或联调出问题，再进入标准化 bug 排查闭环

快速开始

在你的项目根目录执行：

npx word-to-schema install --ide cursor

安装完成后，会自动：

• 写入当前 IDE 可识别的 workflow / skill 结构
• 创建 docs/md、docs/design、scripts 目录
• 拷贝 scripts/word-to-md.js
• 默认安装宿主项目依赖：mammoth、turndown、fs-extra

如果你不希望自动安装依赖：

npx word-to-schema install --ide cursor --no-deps

推荐工作流

Stage 0：文档导入

先把 Word 文档转成 Markdown：

node scripts/word-to-md.js ./your-requirement.docx

输出结果：

• Markdown：docs/md/[编号或文件名]/[原文件名].md
• 图片：docs/md/[编号或文件名]/images/*

这是整个工作流的输入准备阶段。

Stage 1：需求审计

工作流首先进入“找茬式审计”。

目标不是马上生成协议，而是先把需求里不能落地的地方找出来，例如：

• 字段不清
• 流程不闭环
• 交互反馈缺失
• 旧逻辑与新增逻辑冲突

这个阶段未达到 clear 之前，不进入下一步。

Stage 2：技术定稿

当审计问题得到确认后，工作流会把原始需求与确认结果整合成一份唯一技术定稿。

这份定稿的作用是：

• 成为后续协议生成的唯一真理来源
• 明确新增内容与存量内容的边界
• 减少开发阶段二次解释

Stage 3：协议编译

技术定稿继续进入协议编译阶段，产出结构化的协议 JSON。

这个 JSON 会承载：

• 数据模型
• 状态定义
• 动作定义
• 接口契约
• Mermaid 流程表达
• 工程约束

后续任务拆分和执行，都必须以这个协议为准。

Stage 4：任务编排

协议 JSON 会继续被拆成 tasks.json。

这个阶段的重点不是“列待办事项”，而是：

• 给每个任务绑定协议引用
• 建立依赖关系
• 检查步骤顺序是否正确
• 输出 ordering_check

也就是说，任务不仅要被拆出来，还必须是“可执行顺序正确”的。

Stage 5：受控执行

工作流最后进入执行阶段。

执行不是一次性把所有任务跑完，而是：

• 一次只执行一个任务
• 先检查排序是否正确
• 再检查当前依赖是否满足
• 如果有模糊替换或实现歧义，必须先提问
• 修改后要输出修改总结与影响范围

这个阶段的目标是：

• 防止机械执行
• 防止超范围修改
• 防止在不清晰条件下直接落代码

Stage 6：问题诊断与回归

如果执行、联调或回归阶段出现问题，建议切换到专门的 bug 工作流，而不是只使用单个诊断 skill。

推荐工作流：

bug-problem-definer
-> bug-hypothesis-ranker
-> bug-repro-test-builder
-> issue-diagnosis
-> execution-runner / 修复执行

这个阶段的重点是：

• 先确认问题定义是否准确
• 再排序问题可能性
• 再设计最小复现与测试锚点
• 最后再进入修复与回归验证

这样比单一的“诊断 skill”更稳定，也更适合真实工程排查。

工作流在不同 IDE 下的安装方式

原生双目录模式

这些环境会保留 skills/ 和 workflows/：

• cursor -> .cursor/skills + .cursor/workflows
• gemini -> .agent/skills + .agent/workflows
• antigravity -> .agent/skills + .agent/workflows

其中：

• cursor 当前已内置本地调试脚本
• antigravity 当前已内置本地调试脚本
• gemini 在安装逻辑上已支持，但当前 README 对应的本地调试脚本尚未内置到 package.json

指令兼容模式

这些环境不会单独暴露 workflows/，但仍然支持工作流；workflow 会被转换为 instruction-compatible package：

• codex -> .codex/skills + .codex/instructions
• kiro -> .kiro/skills + .kiro/instructions
• qoder -> .qoder/skills + .qoder/instructions

重点不是目录名，而是：

• 工作流语义仍然存在
• 只是不同 IDE 的落地载体不同

最常用的使用方式

如果你只想快速体验完整流程，通常只需要先做两件事：

1. 安装到当前项目

npx word-to-schema install --ide cursor

2. 准备第一份输入文档

node scripts/word-to-md.js ./your-requirement.docx

之后就让工作流从 Markdown 需求开始推进。

本地调试工作流安装

如果你正在本仓库里开发，想直接在某个编辑器环境中验证工作流安装结果，可以先安装依赖：

npm install

然后直接运行本地调试命令，例如：

npm run debug:install:cursor

已内置以下本地调试命令：

npm run debug:install:cursor
npm run debug:install:antigravity
npm run debug:install:codex
npm run debug:install:kiro
npm run debug:install:qoder

说明：当前 package.json 中已经内置以上脚本；如需补充 gemini 的本地调试脚本，可继续按同样方式扩展。

如果你只想验证 workflow / skill 目录生成，不想自动安装宿主依赖：

npm run debug:install:cursor:no-deps

这些命令适合快速验证：

• workflow 是否被安装到正确位置
• 不同 IDE 下的目录结构是否符合预期
• scripts/word-to-md.js 是否拷贝成功
• 安装提示是否符合当前 IDE 模式

发布与版本升级

当前内置了发布命令和版本升级脚本。

预演发布

npm run publish:npm:dry

直接发布

npm run publish:npm

升级版本并发布

npm run publish:npm:patch
npm run publish:npm:minor
npm run publish:npm:major

这些脚本会调用本地 CLI 的 publish 命令；其中 patch / minor / major 会先更新 package.json 版本号，再执行发布。

组件说明（简版）

下面这些组件是工作流中的阶段能力，建议作为辅助理解，而不是 README 的主阅读路径：

• word-to-md：负责把 .docx 转成 Markdown
• requirement-auditor：负责审计需求歧义
• logic-consolidator：负责形成技术定稿
• requirement-to-schema：负责编译协议 JSON
• task-orchestrator：负责拆任务并校验顺序
• execution-runner：负责受控执行、遇歧义先提问、执行后总结影响范围
• bug-problem-definer：负责先确认“到底是什么问题”
• bug-hypothesis-ranker：负责排序问题可能性
• bug-repro-test-builder：负责最小复现与测试锚定
• issue-diagnosis：负责汇总诊断信息并形成综合排查结论
• word-to-schema-pipeline：负责串联主开发流程
• bug-diagnosis-workflow：负责串联问题排查流程

为什么 README 要以工作流为中心

因为这个项目的真正价值不在于：

• 单独有多少个 skill
• 每个 skill 各自能做什么

而在于：

• 它定义了一条从需求到执行的稳定路径
• 它把“审计 -> 定稿 -> 协议 -> 任务 -> 执行”串成主开发闭环
• 它又把“问题定义 -> 原因排序 -> 复现测试 -> 综合诊断 -> 修复回归”串成 bug 排查闭环
• 它能在不同 IDE 里用接近一致的方式落地这两条工作流

本地开发

npm install
npm link
word-to-schema install --ide cursor

发布前建议

• 检查 package.json 与 CLI 版本是否一致
• 检查模板目录中是否存在重复嵌套目录
• 验证至少一个原生双目录模式 IDE，例如 cursor
• 验证至少一个指令兼容模式 IDE，例如 codex
• 验证 node scripts/word-to-md.js <file.docx> 能正常输出结果
• 验证 npm run publish:npm:dry 能正常预演发包