maestro-flow 0.5.31 → 0.5.33

package/.agents/skills/scholar-thesis-docx/README.md

@@ -0,0 +1,111 @@
+# thesis-docx.skill
+
+[![License](https://img.shields.io/badge/license-MIT-16a34a)](./LICENSE)
+[![Word](https://img.shields.io/badge/Microsoft_Word-Recommended-185ABD)](#运行前提)
+[![Mermaid](https://img.shields.io/badge/Mermaid-Supported-0ea5e9)](#功能)
+
+**语言 / Language**：**中文** | [English](./README_EN.md)
+
+`thesis-docx` 是一个面向毕业论文 / 学位论文场景的 skill。
+
+它的重点不是“批量改 Word”，而是让 AI 在论文文档上按更稳的顺序工作：
+
+1. 先检查 Word 自动化环境  
+2. 先审计，再决定怎么改  
+3. 学校明确规定的格式严格执行  
+4. 学校没规定的格式默认保留现状  
+5. 最后导出 PDF 逐页复核
+
+## 功能
+
+- 修订 thesis / dissertation Word 文档
+- 统一正文、标题、图题注、表题注、参考文献等样式
+- 修复目录、页码、分节、交叉引用、图表编号
+- 生成基于真实材料的 Mermaid 图
+- 生成适合论文使用的代码片段或伪代码，LaTeX排版
+- 审计 OOXML 隐藏问题，例如：
+  - `styleId`
+  - `firstLineChars`
+  - `titlePg`
+  - REF 域显示值
+  - section 级页眉页脚引用
+
+## 运行前提
+
+- Windows 下建议安装桌面版 Microsoft Word
+- Python 脚本建议环境具备：
+  - `python-docx`
+  - `lxml`
+- Mermaid 渲染建议具备：
+  - Node.js
+  - `mmdc` 或可用的 `npx`
+
+## 快速开始
+
+```powershell
+# 1) 检查 Word COM/DOM 是否可用
+powershell -ExecutionPolicy Bypass -File scripts/check_word_com.ps1 -Json
+
+# 2) 先做 OOXML 审计
+python scripts/audit_docx_ooxml.py .\draft.docx --output_json .\draft.audit.json --output_txt .\draft.audit.txt
+
+# 3) 如有需要，先 dry-run 审计样式归一化
+powershell -ExecutionPolicy Bypass -File scripts/normalize_word_styles.ps1 -InputPath .\draft.docx -AuditOnly
+
+# 4) 真正修完后导出 PDF，逐页复核
+powershell -ExecutionPolicy Bypass -File scripts/export_word_pdf.ps1 -DocPath .\draft.docx -PdfPath .\draft.audit.pdf
+```
+
+## 使用原则
+
+- 先审计，再修复
+- 先修学校明确要求，再处理用户自定义要求
+- 不对未规定区域做“全局统一美化”
+- 图、代码、架构、流程都必须基于真实材料
+- 没做 PDF 逐页复核时，不应直接说“格式已全部完成”
+
+## 仓库结构
+
+```text
+.
+├── agents/
+├── SKILL.md
+├── scripts/
+├── references/
+├── examples/
+├── README.md
+├── README_EN.md
+└── LICENSE
+```
+
+## 关键文件
+
+- `SKILL.md`：主说明
+- `agents/openai.yaml`：界面集成元数据
+- `scripts/check_word_com.ps1`：检查 Word COM/DOM
+- `scripts/audit_docx_ooxml.py`：审计 DOCX / OOXML 隐藏问题
+- `scripts/normalize_word_styles.ps1`：批量样式归一化
+- `scripts/export_word_pdf.ps1`：导出 PDF 做逐页审计
+- `scripts/render_mermaid_figure.ps1`：渲染 Mermaid 图
+- `references/paper-format-workflow.md`：论文格式工作流
+- `references/failure-patterns-and-quality-gates.md`：高风险坑与质量门槛
+- `references/script-usage.md`：脚本使用说明
+
+## 安装
+
+```powershell
+git clone https://github.com/the-shy123456/thesis-docx.git
+```
+
+保持仓库目录完整即可，不需要拆文件。
+
+## Star 趋势
+
+[![Star History Chart](https://api.star-history.com/svg?repos=the-shy123456/thesis-docx&type=Date)](https://www.star-history.com/#the-shy123456/thesis-docx&Date)
+
+## License
+
+MIT
+## 社区
+
+- [LINUX DO 社区](https://linux.do)

package/.agents/skills/scholar-thesis-docx/README_EN.md

@@ -0,0 +1,108 @@
+# thesis-docx
+
+[![License](https://img.shields.io/badge/license-MIT-16a34a)](./LICENSE)
+[![Word](https://img.shields.io/badge/Microsoft_Word-Recommended-185ABD)](#runtime-requirements)
+[![Mermaid](https://img.shields.io/badge/Mermaid-Supported-0ea5e9)](#features)
+
+**Language**: [中文](./README.md) | **English**
+
+`thesis-docx` is a skill for thesis and dissertation Word workflows.
+
+Its purpose is not merely bulk formatting. The intended workflow is:
+
+1. check Word automation first  
+2. audit before editing  
+3. strictly enforce school-defined rules  
+4. preserve formatting that the school guide does not define  
+5. export to PDF and review page by page
+
+## Features
+
+- revise thesis / dissertation Word documents
+- normalize body text, headings, figure captions, table captions, and references
+- fix TOC, page numbers, sections, cross-references, and caption numbering
+- generate Mermaid figures from real source material
+- prepare thesis-friendly code excerpts or pseudocode
+- audit hidden OOXML issues such as:
+  - `styleId`
+  - `firstLineChars`
+  - `titlePg`
+  - REF field display text
+  - section-level header/footer references
+
+## Runtime Requirements
+
+- desktop Microsoft Word is strongly recommended on Windows
+- Python scripts typically expect:
+  - `python-docx`
+  - `lxml`
+- Mermaid rendering typically expects:
+  - Node.js
+  - `mmdc` or a usable `npx`
+
+## Quick Start
+
+```powershell
+# 1) Check Word COM/DOM availability
+powershell -ExecutionPolicy Bypass -File scripts/check_word_com.ps1 -Json
+
+# 2) Audit DOCX / OOXML first
+python scripts/audit_docx_ooxml.py .\draft.docx --output_json .\draft.audit.json --output_txt .\draft.audit.txt
+
+# 3) Dry-run style normalization first
+powershell -ExecutionPolicy Bypass -File scripts/normalize_word_styles.ps1 -InputPath .\draft.docx -AuditOnly
+
+# 4) Export to PDF for page-by-page review
+powershell -ExecutionPolicy Bypass -File scripts/export_word_pdf.ps1 -DocPath .\draft.docx -PdfPath .\draft.audit.pdf
+```
+
+## Working Rules
+
+- audit first, fix second
+- prioritize school rules over local preferences
+- do not globally normalize unspecified formatting
+- keep figures, architecture, and code grounded in real materials
+- do not claim completion before PDF-level review
+
+## Repository Layout
+
+```text
+.
+├── agents/
+├── SKILL.md
+├── scripts/
+├── references/
+├── examples/
+├── README.md
+├── README_EN.md
+└── LICENSE
+```
+
+## Key Files
+
+- `SKILL.md`: main instructions
+- `agents/openai.yaml`: UI-facing metadata
+- `scripts/check_word_com.ps1`: check Word COM/DOM availability
+- `scripts/audit_docx_ooxml.py`: audit hidden DOCX / OOXML issues
+- `scripts/normalize_word_styles.ps1`: batch style normalization
+- `scripts/export_word_pdf.ps1`: export PDF for page review
+- `scripts/render_mermaid_figure.ps1`: render Mermaid figures
+- `references/paper-format-workflow.md`: thesis formatting workflow
+- `references/failure-patterns-and-quality-gates.md`: common failure modes and quality gates
+- `references/script-usage.md`: script examples and usage notes
+
+## Installation
+
+```powershell
+git clone https://github.com/the-shy123456/thesis-docx.git
+```
+
+Keep the repository structure intact.
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=the-shy123456/thesis-docx&type=Date)](https://www.star-history.com/#the-shy123456/thesis-docx&Date)
+
+## License
+
+MIT

package/.agents/skills/scholar-thesis-docx/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: thesis-docx
+description: Create, revise, and format thesis or dissertation Word documents with strict academic formatting control. Use when an AI agent needs to generate or revise thesis content, normalize Word styles, follow a school template, fix captions or page numbers or section levels, or produce evidence-based Mermaid figures and LaTeX-formatted code listings for a thesis document.
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+
+# Thesis DOCX
+
+## Overview
+
+Use this skill for thesis-oriented `.docx` work where content quality and
+format fidelity both matter. Prefer Microsoft Word desktop automation over
+WPS-like alternatives whenever the task involves batch formatting, styles,
+captions, pagination, tables of contents, or cross-references.
+
+This skill is designed to avoid the most common thesis-editing failure mode:
+the agent makes broad formatting changes too early, introduces new layout
+problems, and then forces the user to catch them one by one. The default
+behavior should therefore be:
+
+1. audit first,
+2. separate explicit school requirements from unspecified formatting,
+3. fix only what is justified,
+4. re-check page by page before claiming completion.
+
+## Pre-load (before execution)
+
+1. **Codebase docs**: If `.workflow/codebase/ARCHITECTURE.md` exists, read for project context
+2. **Specs**: `maestro spec load --category coding` — load coding conventions
+3. **Wiki knowledge**: `maestro search "thesis academic writing docx formatting" --json` — top 5 entries as prior context
+4. All optional — proceed without if unavailable
+
+## Workflow
+
+1. Check Microsoft Word and COM/DOM automation first.
+   - On Windows, run:
+   ```powershell
+   powershell -ExecutionPolicy Bypass -File scripts/check_word_com.ps1 -Json
+   ```
+   - If Word is missing, COM is unavailable, or DOM access fails:
+     - Stop the automation-heavy plan.
+     - Tell the user to install desktop Microsoft Word.
+     - Explain briefly that WPS or similar tools are likely to degrade layout
+       fidelity for thesis formatting.
+2. Read the user's real constraints before editing.
+   - Collect the thesis template, school formatting guide, screenshots,
+     existing document, sample pages, and any explicit chapter rules.
+   - If the user gave formal requirements, follow them strictly.
+   - If the user did not give requirements, do not invent school-specific
+     standards. Use conservative academic defaults and say that they are
+     defaults.
+   - Explicitly classify requirements into two buckets before editing:
+     - `must enforce`: school guide, template, user-confirmed style rules
+     - `preserve current state`: anything the school guide does not define
+3. Audit the DOCX / OOXML before risky bulk edits.
+   - Prefer `scripts/audit_docx_ooxml.py` before large-scale formatting.
+   - Use it to detect hidden indentation, section drift, stale REF display
+     text, and style-ID mismatches before deciding on a repair strategy.
+4. Standardize with styles, not scattered direct formatting.
+   - Reuse and repair existing styles whenever possible.
+   - Create missing styles only when no matching style exists.
+   - Keep body text, headings, figure captions, table captions, references,
+     abstract, and appendix styles separate and consistent.
+   - Before changing any style globally, inspect whether the document contains
+     direct paragraph formatting or OOXML overrides that will survive the style
+     change.
+5. Edit content only from user-provided facts.
+   - Expand, polish, or reorganize thesis text only within the user's topic,
+     evidence, codebase, notes, or source material.
+   - Do not invent experimental data, system structure, entities, or results.
+6. Generate figures only when the source material is sufficient.
+   - Use Mermaid for architecture diagrams, E-R diagrams, flow charts, state
+     diagrams, and similar thesis figures.
+   - Base every node, field, relation, and dependency on real materials from
+     the user, such as code, SQL schema, API docs, project docs, or the thesis
+     draft itself.
+   - If the materials are insufficient, refuse to fabricate the figure and ask
+     for the missing source information.
+7. Typeset code with LaTeX conventions when thesis code excerpts are needed.
+   - Keep only the code relevant to the argument.
+   - Preserve real identifiers from the user's code or design.
+   - Avoid synthetic filler code written only to look complete.
+8. Audit before you claim completion.
+   - Run a structure audit first: styles, sections, captions, references,
+     page number scheme, cross-references, hidden paragraph overrides.
+   - Then export the document to PDF from Word and review page by page.
+   - Only say the task is complete after the PDF-level audit passes or after
+     you clearly state the remaining manual visual checks.
+
+## Style Strategy
+
+- Treat styles as the single source of truth for formatting.
+- Prefer these logical style buckets:
+  - `Body Text`
+  - `Heading 1` / `Heading 2` / `Heading 3`
+  - `Figure Caption`
+  - `Table Caption`
+  - `References`
+  - `Abstract`
+  - `Keywords`
+  - `Appendix Title`
+- If the document already has equivalent styles, map to them and normalize
+  their font, spacing, indentation, and numbering behavior.
+- If direct formatting conflicts with styles, reduce the direct formatting and
+  bring the document back under style control.
+- Do not globally normalize sections that the school guide does not specify.
+  Examples of high-risk overreach:
+  - page header/footer redesign when the user only asked for headings
+  - changing code box appearance when the task is only about references
+  - normalizing table internals when the school guide does not regulate them
+- When a visual issue remains after style normalization, inspect hidden OOXML
+  state such as `firstLineChars`, numbering indentation, `titlePg`,
+  `differentFirstPageHeaderFooter`, REF field display text, and direct run
+  formatting.
+
+## Audit-First Discipline
+
+Before bulk editing, produce and internally follow a checklist like this:
+
+1. Which parts are explicitly regulated by the school guide?
+2. Which parts are user-defined house rules?
+3. Which parts are currently acceptable and must be preserved?
+4. Which problems are structural vs. visual-only?
+5. Which fixes can be done safely through styles?
+6. Which fixes require Word COM or OOXML-level patching?
+
+Do not say "finished" merely because a structural audit looks good. For thesis
+work, pagination and page-level rendering are part of correctness.
+
+## High-Risk Pitfalls
+
+Read `references/failure-patterns-and-quality-gates.md` before large-scale
+formatting work. In particular, guard against:
+
+- style names that look correct but map to the wrong style IDs
+- paragraph-level direct formatting that overrides the intended style
+- `firstLineChars` or numbering indentation creating invisible extra indents
+- TOC fields or cross-reference fields showing stale display text
+- section-level first-page settings causing missing headers or page numbers
+- Word vs. WPS differences for table row height, vertical alignment, and code
+  box title clipping
+- punctuation normalization that accidentally rewrites DOI, URLs, code, or
+  English references
+
+## Visual Review Rule
+
+For school-format-sensitive thesis work, final verification should prefer this
+order:
+
+1. Word COM/DOM structural checks
+2. Word export to PDF
+3. page-by-page PDF review
+4. only then final delivery language
+
+If page rendering cannot be verified, say so explicitly instead of implying the
+ formatting is fully validated.
+
+## Figure Rules
+
+- Use Mermaid when a thesis figure is needed and the structure can be traced to
+  real source material.
+- Keep the diagram academically neutral and concise.
+- Avoid decorative labels, chatty callouts, and speculative entities.
+- Match the user's terminology unless it conflicts with the real materials.
+- Read `references/figure-and-code-rules.md` before generating diagrams.
+
+## Code Listing Rules
+
+- Prefer LaTeX-oriented code presentation when the thesis includes code
+  listings.
+- Keep the listing faithful to the actual code.
+- Trim non-essential boilerplate when it does not support the thesis argument.
+- If the user requests a specific LaTeX package or listing style, follow it.
+
+## Resource Guide
+
+- `scripts/check_word_com.ps1`
+  - Detect whether Microsoft Word desktop and COM/DOM automation are available.
+- `scripts/audit_docx_ooxml.py`
+  - Audit DOCX styles, direct indentation, section settings, numbering, and REF
+    field behavior before making risky formatting changes.
+- `scripts/normalize_word_styles.ps1`
+  - Batch-normalize thesis body text, Heading 1-3, figure captions, and table
+    captions through Word COM automation.
+- `scripts/export_word_pdf.ps1`
+  - Export the current thesis document to PDF through Word COM for page-level
+    review.
+- `scripts/render_mermaid_figure.ps1`
+  - Render Mermaid source into thesis-ready SVG, PNG, or PDF figure assets.
+- `references/paper-format-workflow.md`
+  - Read for the standard Word thesis formatting workflow.
+- `references/figure-and-code-rules.md`
+  - Read before generating Mermaid figures or LaTeX code listings.
+- `references/failure-patterns-and-quality-gates.md`
+  - Read before large-scale formatting or before claiming the thesis is fully
+    checked.
+- `references/script-usage.md`
+  - Read for command examples and config file conventions.
+
+## Final Checks
+
+- Confirm the document is still style-driven after edits.
+- Confirm captions, numbering, page breaks, and table of contents are coherent.
+- Confirm cross-references display the current target labels, not stale field
+  text.
+- Confirm section settings do not silently remove page headers or page numbers
+  from first pages.
+- Confirm references are formatted according to the school rules and that
+  punctuation normalization did not damage DOI or English references.
+- Confirm every diagram and code block is grounded in user-provided material.
+- Export to PDF and inspect every page before saying the format is complete.
+- If Word automation or PDF verification was unavailable, explicitly warn that
+  layout fidelity was not guaranteed.

package/.agents/skills/scholar-thesis-docx/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Thesis DOCX"
+  short_description: "Audit and revise thesis Word documents"
+  default_prompt: "Use $thesis-docx to audit, revise, and format a thesis Word document with school-specific rules."

package/.agents/skills/scholar-thesis-docx/examples/architecture.sample.mmd

@@ -0,0 +1,5 @@
+flowchart TD
+    Client[User] --> Web[Web Layer]
+    Web --> Service[Service Layer]
+    Service --> Repo[Repository Layer]
+    Repo --> DB[(Database)]

package/.agents/skills/scholar-thesis-docx/examples/final-audit-checklist.sample.md

@@ -0,0 +1,46 @@
+# Thesis Final Audit Checklist (Sample)
+
+Use this as a pre-delivery checklist before saying the thesis formatting is
+complete.
+
+## Requirement Boundary
+
+- School formatting guide loaded and understood
+- User-specific style rules separated from school rules
+- Unspecified formatting intentionally preserved
+
+## Structure Audit
+
+- Cover page
+- Abstract / keywords
+- English abstract / keywords
+- TOC title and TOC levels
+- Heading hierarchy
+- Figure captions
+- Table captions
+- References
+- Acknowledgements
+- Section/page-number scheme
+
+## Hidden OOXML Audit
+
+- Style IDs verified for heading levels
+- `firstLine` checked where indentation looks suspicious
+- `firstLineChars` checked where indentation looks suspicious
+- numbering indentation checked
+- `titlePg` and first-page section settings checked
+- REF field display text checked
+
+## Word PDF Review
+
+- Exported from Word to PDF
+- Every page reviewed
+- Dense figure/table pages reviewed carefully
+- First page of each chapter reviewed
+- Reference pages reviewed
+- Final acknowledgement page reviewed
+
+## Delivery Gate
+
+- No unresolved format regressions remain
+- If any page was not reviewed, that limitation is stated explicitly

package/.agents/skills/scholar-thesis-docx/examples/word-style-config.sample.json

@@ -0,0 +1,35 @@
+{
+  "styles": {
+    "Body": {
+      "TargetStyleName": "正文",
+      "FontName": "Times New Roman",
+      "EastAsiaFontName": "宋体",
+      "Size": 12,
+      "LineSpacingMultiple": 1.5
+    },
+    "Heading1": {
+      "TargetStyleName": "标题 1",
+      "EastAsiaFontName": "黑体",
+      "Size": 16,
+      "Alignment": "Center"
+    },
+    "Heading2": {
+      "TargetStyleName": "标题 2",
+      "EastAsiaFontName": "黑体"
+    },
+    "Heading3": {
+      "TargetStyleName": "标题 3",
+      "EastAsiaFontName": "黑体"
+    },
+    "FigureCaption": {
+      "TargetStyleName": "图标注",
+      "EastAsiaFontName": "宋体",
+      "Size": 10.5
+    },
+    "TableCaption": {
+      "TargetStyleName": "表标注",
+      "EastAsiaFontName": "宋体",
+      "Size": 10.5
+    }
+  }
+}