word-to-schema

一个面向 RPA 需求工程的多 IDE 工具链，用来把 Word 需求文档逐步转成可执行的开发协议与任务流。

它更适合这样的使用路径：

1. 安装到当前项目的 IDE 目录
2. 把 .docx 转成 Markdown
3. 审计需求中的模糊点
4. 生成技术定稿文档
5. 编译成协议 JSON
6. 拆成任务列表
7. 按任务顺序受控执行

快速开始

在你的项目根目录执行：

npx word-to-schema install --ide cursor

安装完成后，会自动：

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

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

npx @ywy_user/word-to-schema install --ide cursor --no-deps

支持的 IDE

原生双目录模式

这些环境会保留 skills/ 和 workflows/ 两类目录：

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

指令兼容模式

这些环境同样支持，但不会单独生成 workflows/ 目录；workflow 会被转换为 instruction-compatible package：

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

怎么使用

第一步：安装工具链

示例：

npx @ywy_user/word-to-schema install --ide cursor

安装后，你会在项目里看到类似目录：

.cursor/
docs/
scripts/

或者在兼容模式 IDE 下看到：

.codex/
docs/
scripts/

第二步：把 Word 文档转成 Markdown

运行：

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

输出结果：

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

说明：

• 仅支持 .docx
• 如果文件名以数字开头，会优先用数字作为目录名
• 图片会按顺序导出到 images/ 目录

第三步：执行需求审计

使用 requirement-auditor 对 Markdown 需求做“找茬式”审计。

作用：

• 识别字段不清、逻辑不闭环、交互缺失等问题
• 遇到歧义时只提一个最关键的问题
• 在需求未澄清前，不进入下一步

建议输入：

• docs/md/.../*.md

建议产出：

• Audit_Report
• 用户确认后的补充说明

第四步：生成技术定稿

使用 logic-consolidator。

作用：

• 合并原始需求与审计问答
• 补足缺失状态与异常处理
• 输出唯一技术定稿文档，作为后续开发真理来源

建议产出：

• .spec.md 或等价定稿文档

第五步：编译协议 JSON

使用 requirement-to-schema。

作用：

• 将技术定稿文档编译为结构化协议 JSON
• 区分 New / Iterative 模式
• 生成数据模型、状态、动作、接口契约与 Mermaid 流程图

建议输出目录：

docs/design/

例如：

docs/design/merchant_registration_rpa.json

第六步：生成任务列表

使用 task-orchestrator。

作用：

• 基于协议 JSON 拆解成原子任务
• 给每个任务绑定 protocol_references
• 定义 acceptance_signals
• 校验执行顺序是否合理
• 补充依赖关系，如 depends_on
• 输出 ordering_check，判断整个任务排序是否可执行

这一步非常关键，因为后续执行必须依赖正确排序的 tasks.json。

第七步：按任务受控执行

使用 execution-runner。

作用：

• 按 tasks.json 顺序执行
• 执行前检查 ordering_check
• 检查当前任务依赖是否满足
• 遇到模糊替换、映射歧义、协议缺口时先提问
• 不允许在不明确的情况下机械执行
• 每次只执行一个任务
• 执行后输出验收结果、修改总结、影响范围与阻塞原因

也就是说，真正负责“限制执行范围”和“执行中遇到歧义先提问”的，就是 execution-runner。

第八步：排查执行或联调问题

使用 issue-diagnosis。

作用：

• 先把问题现象整理成明确的问题定义
• 定位可疑模块、可疑文件和最近相关改动
• 输出按优先级排序的问题可能性
• 在证据不足时先提一个最关键的问题
• 在可自动化的情况下补对应测试脚本或最小复现脚本
• 给出下一步排查建议或修复验证路径

这个 skill 更适合在以下场景使用：

• 功能没有按协议运行
• 联调时报错但根因不清楚
• 执行后结果异常，需要快速缩小范围
• 修复前想先补回归测试

推荐完整链路

推荐按下面顺序使用：

word-to-md
-> requirement-auditor
-> logic-consolidator
-> requirement-to-schema
-> task-orchestrator
-> execution-runner

如果在执行、联调或回归阶段遇到问题，可以插入：

issue-diagnosis

也就是：

... -> execution-runner -> issue-diagnosis -> 修复 / 回归验证

各组件职责简表

| 组件 | 作用 | | --- | --- | | word-to-md | 把 .docx 转成 Markdown 并提取图片 | | requirement-auditor | 审计需求歧义，串行提问 | | logic-consolidator | 形成唯一技术定稿 | | requirement-to-schema | 编译协议 JSON | | task-orchestrator | 生成带依赖和顺序校验的任务列表 | | execution-runner | 按任务顺序受控执行，遇歧义先提问 | | issue-diagnosis | 排查问题、给出可能性排序，并在可行时补自动化测试脚本 | | word-to-schema-pipeline | 串联整个流程 |

skills、workflows 与 instructions 的区别

• skills：单点能力模块
• workflows：把多个 skill 串起来的流程编排
• instructions：某些 IDE 下对 workflow 的兼容包装形式

所以如果你在 codex、kiro、qoder 下没有看到 workflows/，并不代表不支持 workflow，而是 workflow 被转换成了 instruction-compatible package。

本地开发

npm install
npm link
agent-rpa install --ide cursor

发布前建议

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