# docx-ai-flow

**Repository Path**: emanonhero/docx-ai-flow

## Basic Information

- **Project Name**: docx-ai-flow
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-27
- **Last Updated**: 2026-03-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Vibe Docx

> **用自然语言"说"出你想要的文档** - 就像有个 Word 专家坐在旁边听你指挥

就像 Vibe Coding 让程序员用自然语言写代码，Vibe Docx 让你用自然语言做 Word 文档。

## 产品定位

**Vibe Docx = Copilot 的文档专业 Skill**

不是替代 Copilot，是让 Copilot 变成"文档专家"。

## 核心架构

```
┌──────────────────────────────────────────────────────────���───┐
│                     Vibe Docx 架构                           │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│   用户: "帮我把这个乱七八糟的文档变成专业报告"               │
│                         ↓                                    │
│   ┌─────────────────────────────────────────────────────┐   │
│   │              AGENT (大脑/入职培训)                   │   │
│   │                                                     │   │
│   │  • 意图识别 - 理解用户想做什么                      │   │
│   │  • 策略规划 - 制定多方案解决策略                    │   │
│   │  • 用户交互 - 展示方案、获取选择                    │   │
│   │  • 执行调度 - 协调 Builder 和 Validator             │   │
│   └─────────────────────────────────────────────────────┘   │
│                         ↓                                    │
│   ┌──────────────────┐        ┌──────────────────┐          │
│   │   VALIDATOR      │   ←→   │    BUILDER       │          │
│   │    (眼睛)         │        │     (手脚)       │          │
│   │                  │        │                  │          │
│   │ • 文档体检       │        │ • 文本操作       │          │
│   │ • 结构解析       │        │ • 段落格式       │          │
│   │ • 问题发现       │        │ • 表格处理       │          │
│   │ • 风险预警       │        │ • 图片操作       │          │
│   │ • 最佳实践       │        │ • 批量处理       │          │
│   └──────────────────┘        └──────────────────┘          │
│                                                              │
└──────────────────────────────────────────────────────────────┘
```

## 安装

```bash
# 完整安装
python install.py

# 只安装 builder 和 validator
python install.py --modules builder,validator

# 安装到指定目录
python install.py --target ./my-project

# 检查安装状态
python install.py --check
```

## Quick Start

### 1. 基础用法 - DocxWorkspace

```python
from docx_builder import DocxWorkspace

with DocxWorkspace('report.docx') as doc:
    # 检查文档结构
    info = doc.inspect()
    print(f"段落数: {info['total_paragraphs']}")
    print(f"表格数: {info['total_tables']}")
    print(f"图片数: {info['total_images']}")
    
    # 读取章节
    content = doc.read_section('第三章')
    print(content['text'])
    
    # 替换章节（支持 Markdown）
    doc.splice('第三章', '# 新标题\n\n新内容', format='markdown')
    
    # 操作表格
    tables = doc.table_list()
    doc.table_update(0, [{'row': 0, 'col': 0, 'text': '新值'}])
```

### 2. 智能分析 - EnhancedValidator

```python
from docx_builder.core.enhanced_validator import analyze_document, generate_summary_report

# 分析文档
report = analyze_document('report.docx')

# 生成摘要
summary = generate_summary_report(report)
print(summary)

# 获取问题
format_issues = report.get_issues_by_category('format')
auto_fixable = report.get_auto_fixable_issues()

print(f"发现 {len(report.issues)} 个问题")
print(f"其中 {len(auto_fixable)} 个可自动修复")
```

### 3. 智能交互 - VibeDocxAgent

```python
from docx_builder.agent import VibeDocxAgent

agent = VibeDocxAgent()

# 处理用户请求
response = agent.process_request(
    "这个文档格式乱了，帮我修",
    'report.docx'
)
print(response)

# 选择方案
plan = agent.select_plan('B')

# 执行方案（需要 DocxWorkspace）
with DocxWorkspace('report.docx', output_path='output.docx') as doc:
    result = agent.execute_plan(plan, doc)
    print(result.message)
```

### 4. 格式修复 - FormatFixer

```python
from docx_builder.operations import fix_markdown_syntax, FormatFixer

# 修复 Markdown 语法
doc_xml = "..."  # 你的文档 XML
new_xml, result = fix_markdown_syntax(doc_xml)

print(f"修复了 {result.fixed_count} 处问题")
for change in result.changes:
    print(f"  • {change}")
```

### 5. 表格整理 - TableOrganizer

```python
from docx_builder.operations import TableOrganizer

organizer = TableOrganizer(doc_xml)

# 添加边框
new_xml, result = organizer.add_borders(border_style='single')

# 统一样式
new_xml, result = organizer.unify_style()
```

### 6. 章节操作 - SectionOperator

```python
from docx_builder.operations import SectionOperator

operator = SectionOperator(doc_xml)

# 提取章节
original, extracted, result = operator.extract_section("第三章")
```

## 用户故事

| ID | 故事 | 状态 |
|----|------|------|
| US-001 | 格式修复 - "这个文档格式乱了，帮我修" | ✅ |
| US-002 | 风格转换 - "帮我变成专业报告风格" | ✅ |
| US-003 | 表格整理 - "这个表格帮我统一样式" | ✅ |
| US-004 | 章节操作 - "把第三章拆成独立文档" | ✅ |
| US-005 | 模板应用 - "按公司模板重新格式化" | 📝 |
| US-006 | 批量处理 - "这10个文档帮我合并成一个" | 📝 |

## API 参考

### DocxWorkspace

| 方法 | 说明 |
|-----|------|
| `inspect()` | 文档结构概览 |
| `read_section(title)` | 读取章节内容 |
| `splice(title, content)` | 替换章节（支持 Markdown） |
| `table_list()` | 列出所有表格 |
| `table_read(index)` | 读取表格内容 |
| `table_update(index, cells)` | 更新单元格 |
| `table_create(rows, cols, data)` | 创建表格 |
| `image_list()` | 列出图片 |
| `image_insert(path, position)` | 插入图片 |
| `image_replace(rid, path)` | 替换图片 |
| `checkpoint(name)` | 创建检查点 |
| `rollback(name)` | 回滚到检查点 |

### EnhancedValidator

| 方法 | 说明 |
|-----|------|
| `analyze()` | 完整分析文档 |
| `get_issues_by_severity(severity)` | 按严重程度获取问题 |
| `get_issues_by_category(category)` | 按分类获取问题 |
| `get_auto_fixable_issues()` | 获取可自动修复的问题 |

### VibeDocxAgent

| 方法 | 说明 |
|-----|------|
| `process_request(input, doc_path)` | 处理用户自然语言请求 |
| `select_plan(id)` | 选择执行方案 |
| `execute_plan(plan, builder)` | 执行方案 |

## 与竞品差异

| | Vibe Docx | Copilot | Notion AI |
|---|-----------|---------|-----------|
| **格式能力** | ⭐⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐ |
| **结构理解** | ⭐⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐ |
| **复杂操作** | ⭐⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐ |
| **验证闭环** | ✅ | ❌ | ❌ |
| **多方案推荐** | ✅ | ❌ | ❌ |

## 开源协议

MIT License - 代码完全开放，欢迎贡献！

## 相关资源

- PRD: `_bmad-output/planning-artifacts/prd.md`
- Brainstorming: `_bmad-output/brainstorming/brainstorming-session-2026-02-27.md`
- 测试: `_bmad-output/tests/`