word-to-schema

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

围绕 word-to-schema-pipeline、bug-diagnosis-workflow 与 yapi-interface-doc-workflow 构建的安装与执行工具，用来把"原始需求"稳定推进到"可执行开发任务"，并在出问题时进入标准化排查流程，同时支持从 YApi 获取接口文档。

目录

• 快速开始
• 日常使用指南
• 三条工作流
• 推荐执行流程
• IDE 支持与安装模式
• 组件清单
• CLI 命令参考
• 项目结构
• 本地开发
• 发布
• 约束与限制

快速开始

# 安装到当前项目（以 cursor 为例）
npx word-to-schema install --ide cursor

# 转换 Word 文档为 Markdown
node ./.cursor/skills/word-to-md/word-to-md.js ./your-requirement.docx

安装完成后会自动：

• 写入当前 IDE 可识别的 workflow / skill 结构
• 创建 docs/md、docs/design 目录
• 安装宿主项目依赖（mammoth、turndown、fs-extra）

不需要自动安装依赖时加 --no-deps：

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

日常使用指南

核心理解：Skill 是给 AI Agent 用的

安装完成后，大部分 skill（如 requirement-auditor、logic-consolidator、execution-runner）不是你手动执行的脚本，而是 AI Agent 的行为指令。它们通过 SKILL.md 告诉 Agent 在特定阶段应该怎么思考、怎么提问、怎么输出。

你需要手动执行的只有两类脚本：

• word-to-md.js — 转换 Word 文档
• yapi-doc-fetcher.js — YApi 接口抓取

其余 skill 由 Agent 在对话中自动调用。

你的日常操作方式

场景 1：拿到一份新需求文档

# 1. 手动：转换 Word 为 Markdown
node ./<ide>/skills/word-to-md/word-to-md.js ./新需求.docx

然后在 AI 对话中说：

"请基于 docs/md/xxx/xxx.md 开始需求审计"

Agent 会自动按 word-to-schema-pipeline 工作流推进：审计 → 定稿 → 协议 → 任务 → 执行。

场景 2：首次获取 YApi 接口文档

# 1. 手动：初始化配置
node ./<ide>/skills/yapi-doc-fetcher/yapi-doc-fetcher.js init \
  --base-url http://your-yapi-server:3000 \
  --projects "1076:your_token"

# 2. 手动：发现接口
node ./<ide>/skills/yapi-doc-fetcher/yapi-doc-fetcher.js discover

# 3. 手动：抓取接口
node ./<ide>/skills/yapi-doc-fetcher/yapi-doc-fetcher.js fetch

然后在 AI 对话中说：

"请基于 docs/yapi/yapi-interfaces.md 整理接口报告"

Agent 会执行 yapi-interface-consolidator：分析结构 → 向你确认 → 生成最终报告。

场景 3：后续补充新接口（不需要重新初始化）

# 追加新项目
node ./<ide>/skills/yapi-doc-fetcher/yapi-doc-fetcher.js add --projects "1077:new_token"

# 重新发现
node ./<ide>/skills/yapi-doc-fetcher/yapi-doc-fetcher.js discover

# 只抓新增的
node ./<ide>/skills/yapi-doc-fetcher/yapi-doc-fetcher.js fetch --append

或者只抓特定接口：

node ./<ide>/skills/yapi-doc-fetcher/yapi-doc-fetcher.js fetch --only 51800,51801

场景 4：开发过程中遇到 Bug

在 AI 对话中说：

"我遇到了一个问题：xxx 功能在 xxx 条件下报错 xxx"

Agent 会自动按 bug-diagnosis-workflow 推进：先确认问题定义 → 排序可能性 → 设计复现 → 综合诊断。

场景 5：继续上次未完成的任务

在 AI 对话中说：

"请继续执行 tasks.json 中的下一个任务"

Agent 会读取 tasks.json，找到下一个未完成的任务继续执行。

什么时候用命令行，什么时候跟 Agent 对话

| 操作 | 方式 | 说明 | |------|------|------| | Word 转 Markdown | 命令行 | word-to-md.js | | YApi 配置/发现/抓取 | 命令行 | yapi-doc-fetcher.js | | 需求审计 | 对话 | Agent 自动执行 | | 技术定稿 | 对话 | Agent 自动执行 | | 协议编译 | 对话 | Agent 自动执行 | | 任务拆解 | 对话 | Agent 自动执行 | | 受控执行 | 对话 | Agent 自动执行 | | 接口报告整理 | 对话 | Agent 分析后向你确认 | | Bug 排查 | 对话 | Agent 自动执行 |

三条工作流

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

1. 主开发工作流 (word-to-schema-pipeline)

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

把需求从非结构化文档推进到可执行的开发任务。

2. Bug 排查工作流 (bug-diagnosis-workflow)

Problem Definition → Hypothesis Ranking → Reproduction / Tests → Diagnosis Summary → Fix / Regression

结构化排查，防止跳过定义直接修复。

3. YApi 接口文档工作流 (yapi-interface-doc-workflow)

YApi Config → ID Discovery → Interface Fetching → Interface Report

从 YApi 获取接口文档，整理为可引用的接口资产报告。

推荐执行流程

Stage 0：文档导入

node ./<ide-folder>/skills/word-to-md/word-to-md.js ./your-requirement.docx

输出：

• Markdown：<ide-root>/docs/md/[编号]/[原文件名].md
• 图片：<ide-root>/docs/md/[编号]/images/*

Stage 1：需求审计

"找茬式审计"，识别字段不清、流程不闭环、交互反馈缺失、新旧逻辑冲突等问题。未达到 clear 状态前不进入下一步。

Stage 2：技术定稿

将原始需求与审计确认结果整合为唯一技术定稿，明确新增与存量边界。

Stage 3：协议编译

技术定稿编译为结构化协议 JSON，承载数据模型、状态定义、动作定义、接口契约、Mermaid 流程图和工程约束。

Stage 4：任务编排

协议 JSON 拆解为 tasks.json，每个任务绑定协议引用、建立依赖关系、校验执行顺序。

Stage 5：受控执行

一次只执行一个任务，先检查排序和依赖，遇歧义先提问，修改后输出变更总结与影响范围。

Stage 6：问题诊断

执行或联调出问题时，切换到 bug 排查工作流：

bug-problem-definer → bug-hypothesis-ranker → bug-repro-test-builder → issue-diagnosis → execution-runner

IDE 支持与安装模式

原生双目录模式

保留 skills/ 和 workflows/ 两个独立目录：

| IDE | 目标目录 | |-----|---------| | cursor | .cursor/skills + .cursor/workflows | | antigravity | .agent/skills + .agent/workflows | | gemini | .agent/skills + .agent/workflows |

指令兼容模式

Workflow 转换为 instruction-compatible skill packages：

| IDE | 目标目录 | |-----|---------| | codex | .codex/skills + .codex/instructions | | kiro | .kiro/skills + .kiro/instructions | | qoder | .qoder/skills + .qoder/instructions |

组件清单

主开发流水线

| 组件 | 职责 | |------|------| | word-to-md | 将 .docx 转为 Markdown，自动提取图片 | | requirement-auditor | 审计需求歧义，输出 JSON 审计报告 | | logic-consolidator | 整合反馈形成技术定稿，区分新增与存量 | | requirement-to-schema | 编译协议 JSON（支持 New / Iterative 模式） | | task-orchestrator | 拆解任务并校验依赖顺序 | | execution-runner | 受控执行，遇歧义先提问，执行后总结影响范围 |

Bug 排查流水线

| 组件 | 职责 | |------|------| | bug-problem-definer | 确认问题定义，消除模糊描述 | | bug-hypothesis-ranker | 按证据排序问题可能性 | | bug-repro-test-builder | 设计最小复现，补自动化测试 | | issue-diagnosis | 汇总诊断信息，形成综合排查结论 |

YApi 接口文档流水线

| 组件 | 职责 | |------|------| | yapi-config-manager | 收集并校验 YApi 连接配置 | | yapi-id-collector | 发现项目/分类/接口 ID | | yapi-doc-fetcher | 抓取接口详情，保留原始数据 | | yapi-interface-consolidator | 整理为结构化接口报告 |

CLI 命令参考

install

agent-rpa install --ide <type> [--no-deps]

| 参数 | 说明 | |------|------| | --ide <type> | 必填。目标 IDE 类型：cursor、antigravity、gemini、codex、kiro、qoder | | --no-deps | 可选。跳过自动安装宿主项目依赖 |

publish

agent-rpa publish [--bump <type>] [--tag <tag>] [--access <level>] [--dry-run]

| 参数 | 说明 | |------|------| | --bump <type> | 发布前升级版本：patch、minor、major 或具体版本号 | | --tag <tag> | 发布标签，如 latest、beta | | --access <level> | 包访问级别，默认 public | | --dry-run | 仅预演，不真正发布 |

项目结构

word-to-schema/
├── bin/
│   └── cli.js                  # CLI 入口（install / publish）
├── templates/
│   ├── skills/                 # 所有 skill 模板
│   │   ├── word-to-md/         # Word 转 Markdown（含 JS 脚本）
│   │   ├── requirement-auditor/
│   │   ├── logic-consolidator/
│   │   ├── requirement-to-schema/
│   │   ├── task-orchestrator/
│   │   ├── execution-runner/
│   │   ├── bug-problem-definer/
│   │   ├── bug-hypothesis-ranker/
│   │   ├── bug-repro-test-builder/
│   │   ├── issue-diagnosis/
│   │   ├── yapi-config-manager/
│   │   ├── yapi-id-collector/
│   │   ├── yapi-doc-fetcher/   # YApi 抓取脚本（含 JS 脚本）
│   │   └── yapi-interface-consolidator/
│   └── workflows/              # 工作流编排文档
│       ├── word-to-schema-pipeline.md
│       ├── bug-diagnosis-workflow.md
│       └── yapi-interface-doc-workflow.md
├── docs/                       # 示例/生成文档
├── package.json
└── README.md

本地开发

# 安装依赖
npm install

# 本地调试安装（不同 IDE）
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

# 不安装宿主依赖的调试模式
npm run debug:install:cursor:no-deps

# 全局链接（开发时使用）
npm link
word-to-schema install --ide cursor

发布

# 预演发布
npm run publish:npm:dry

# 直接发布
npm run publish:npm

# 升级版本并发布
npm run publish:npm:patch   # 补丁版本
npm run publish:npm:minor   # 次版本
npm run publish:npm:major   # 主版本

约束与限制

通用约束

• 仅支持 .docx：word-to-md 不支持 .doc、PDF 或其他格式
• Node.js 环境：需要 Node.js 运行时，依赖 mammoth、turndown、fs-extra
• 非实时工具：所有 skill 是 prompt 模板 + 脚本，不是持续运行的服务
• IDE 目录约定：安装路径依赖 IDE 目录约定（.cursor、.kiro 等），不支持自定义路径

工作流约束

• 审计硬闸门：需求审计未达到 clear 状态前，严禁进入协议生成阶段
• 协议至上：所有编码动作必须显式引用 protocol_references
• 任务原子化：严禁合并 Feature，一个任务只解决一个协议动作或实体模型
• 顺序执行：Execution Runner 必须按任务顺序推进，不能跨任务跳跃
• 串行提问：遇到歧义时一次只提一个最关键的问题
• 排序异常拦截：如果任务依赖关系存在循环或歧义，必须暂停并上报

YApi 工作流约束

• 配置先行：没有 baseUrl 与 token 不能进入抓取阶段
• ID 可追溯：所有 ID 必须来自用户输入或 YApi 响应，不能编造
• 原始数据保留：整理报告前必须先保存 yapi.raw.json
• 不泄露 token：任何最终 Markdown 报告都不得包含 token
• 缺失即标记：YApi 未提供的信息必须标记为 missing，不能自动脑补

Bug 排查约束

• 先定义后分析：问题定义未确认前，严禁开始原因分析
• 证据驱动：每个假设必须绑定证据，不能无序罗列
• 复现优先：优先先复现再修复，优先最小范围测试
• 无伪确定性：证据不足时只能给出高/中/低可能性

发布前检查清单

• [ ] package.json 版本号正确
• [ ] 模板目录无重复嵌套
• [ ] 至少验证一个原生双目录模式 IDE（如 cursor）
• [ ] 至少验证一个指令兼容模式 IDE（如 codex）
• [ ] word-to-md.js 能正常转换 .docx 文件
• [ ] npm run publish:npm:dry 预演通过

License

ISC