rojim666/sztucode/brief-compose

python3 <plugin_root>/scripts/wb/local/resolve_output_docx_path.py \
  --workspace <workspace> \
  [--user-path "<路径>"] [--filename "<主题>.docx"]

 
---
 
## HTML → docx 转换约束（仅引擎硬限制）
 
以下规则来自 `html-to-docx` 转换器能力边界；**违反会导致 docx 排版错乱或信息丢失**，其余 HTML/CSS 写法不受限。
 
### 1. 禁止 Grid / 定义列表
 
- **禁** `display:grid` / `grid-template-*` → 多列对齐改用 `<table>`
- **禁** `<dl>/<dt>/<dd>` → 键值对改用两列 `<table>`
 
### 2. 块级 CSS 不继承
 
转换器**不做**块级样式继承。父元素上的 `text-align` / `font-family` / `color` / `font-size` **不会**下发到子 `<p>` / `<h1>` 等；需要生效的样式请写在各块级元素自身上。
 
### 3. `<hr>` 装饰线
 
`<hr>` 在 docx 中只能变成**满版下边框**，无法保留居中短线/定宽装饰线；不要用 `<hr>` 做标题区装饰分隔。
 
### 4. 左边框段落
 
带 `border-left` 的块，文字开头加 `&nbsp;&nbsp;`（Word 左边框无可靠间距）。
 
### 5. 多段落底纹块
 
整块底纹 + 多段落富文本 → 用裸单列 `<table><tr><td>…</td></tr></table>`，不要用多个 `<div>` 拼底纹。
 
### 6. 分节 / 页眉页脚（仅需要时）
 
- 需要分页结构：顶层 `<section role="...">`（无 section 则单节）
- 需要页码/页眉：`<style>` 内 `@page` 子集（`counter(page)` / `counter(pages)` / `string-set` + `STYLEREF`）
- **不支持** `@page :first`、`@page { size }` 等扩展语法（忽略 + warning）
- 需要封面时用户须明确要求；配合 `@page cover { … content: none }` + `section[role="cover"] { page: cover; }`
 
### 7. 可选扩展标签（用了才需遵守其契约）
 
| 标签 / 属性 | 说明 |
|-------------|------|
| `<div data-component="callout\|divider\|section-marker\|data-card">` | 装饰组件 |
| `<span data-docx-field="..." data-placeholder="...">` | 转 docx 书签；同 HTML 内唯一，匹配 `^[A-Za-z][A-Za-z0-9_-]{0,63}$` |
| `<meta name="docx-page-size" content="A4">` | 声明页面尺寸（默认 A4） |
 
---
 
## html-to-docx 转换
 

 
- `<plugin_root>` = 本 plugin 根目录（`tencent-docx/`）
- **禁止**使用系统 `python` / `python3`；依赖在托管 venv 内
- 成功 stdout：`{"success": true, "docx_path": "...", "warnings": []}`
- 失败 stderr：含 `error` 与可选 `markdown_fallback`
 
| CLI 参数 | 默认 | 说明 |
|----------|------|------|
| `--page-size` | `A4` | `A4` / `Letter` / `A3` |
| `--orientation` | `portrait` | `portrait` / `landscape` |
| `--margin-top/bottom/left/right` | 2.54 / 2.54 / 3.17 / 3.17 cm | 页边距 |
 
私有化 / 无外网环境、脚本首跑失败 → 见 `<plugin_root>/skills/html-to-docx/SKILL.md` 镜像配置；否则提示用户手动另存。
 
---
 
## 强制流程
 

 
未 `present_files` 即结束 = 工作流未完成。
 
---
 
## 异常处理
 
| 场景 | 处理 |
|------|------|
| HTML 无 `<body>` | 终止，提示用户 |
| 用户明确要求新建空白文档且 body 无可渲染正文 | 允许转换 |
| 其他创作请求且 body 无可渲染正文 | 重新生成 HTML，禁止交付空 docx |
| html-to-docx 失败 | 返回源 HTML 路径 + `markdown_fallback`（若有），提示手动另存 |
| 用户事后要改内容/样式 | 属**下一轮请求**，转 `tencent-docs-routing` |
| 用户事后要全文重新美化 | 未命中本 skill，回到 `tdoc-orchestrator` SKILL.md 走 `beautify_only` |