@zeyue0329/xiaoma-cli 1.12.0 → 1.15.0

package/src/xpm-skills/xiaoma-patent-mining/steps/step-01-project-analysis.md

@@ -0,0 +1,65 @@
+# Step 1: Project Understanding and Material Collection
+
+## MANDATORY EXECUTION RULES (READ FIRST)
+
+- 🛑 Do NOT start mining patent candidates yet. The goal of this step is global understanding only.
+- ✅ Read documents and code; do not skim filenames alone.
+- 📋 Output of this step is a project cognition memo — keep it private (in working memory or scratch file), do not append to the final disclosure yet.
+- 🚫 Forbidden to advance to step-02 until the project memo has been produced and verified with the user.
+
+## YOUR TASK
+
+Establish a complete mental model of the target software project so that step-02 can recognize what is genuinely novel and what is generic. The target project root is `context_file` if provided, otherwise the current working directory.
+
+## EXECUTION SEQUENCE
+
+### 1.1 Scan project structure
+
+Pick the right scanning tools by stack:
+
+- Source files: `Glob` patterns like `**/*.java`, `**/*.py`, `**/*.ts`, `**/*.go`, `**/*.rs`
+- Build manifests: `pom.xml`, `build.gradle*`, `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`
+- Infra: `Dockerfile`, `docker-compose*.yml`, `**/*.tf`, k8s manifests
+- DB schema: `**/migrations/**`, `**/*.sql`, ORM model files
+
+### 1.2 Read documentation in priority order
+
+1. README and top-level project notes
+2. Architecture / high-level design docs (`docs/architecture*`, `docs/design*`)
+3. Requirements / PRDs
+4. Database design docs (DDL, ER description)
+5. API / interface docs
+
+### 1.3 Analyze core code
+
+Focus on the layers most likely to contain inventions:
+
+- Core business logic (Service / Domain)
+- Custom algorithms and strategy implementations
+- Middleware integration and self-built components
+- Distributed coordination, caching strategy, message handling
+- Complex DB logic (stored procedures, non-trivial SQL)
+- Exception handling and fault tolerance
+
+### 1.4 Optional prior-art lookup
+
+If `WebSearch` or `Tavily` MCP is available, run a quick scan for public patents and well-known designs in the same problem space. Use this to **rule out** candidates that obviously already exist, not to copy from.
+
+### 1.5 Produce the project cognition memo
+
+Summarize:
+
+- Technical domain (e.g., "supply-chain finance", "industrial IoT gateway")
+- Overall architecture pattern (monolith / microservices / event-driven / batch pipeline)
+- Tech stack inventory
+- Core business flows (3–7 bullets)
+- External integrations
+- Anything that looks unusual, custom, or non-standard — these are the **leads** for step-02
+
+## OUTPUT
+
+A short memo (in chat, or written to a scratch file under `{patent_output_folder}/.cache/project-memo-{date}.md` if available) covering the five bullets above.
+
+## NEXT STEP
+
+After confirming the memo with the user, load `./step-02-patent-mining.md`.

package/src/xpm-skills/xiaoma-patent-mining/steps/step-02-patent-mining.md

@@ -0,0 +1,87 @@
+# Step 2: Patent Point Mining (Three-Element Test)
+
+## MANDATORY EXECUTION RULES (READ FIRST)
+
+- 📖 **You MUST read `references/mining-principles.md` in full before proposing candidates.** It is the authoritative source for the three-element test, negative/positive examples, and common pitfalls. When this file conflicts with anything in this step, the reference wins.
+- 🛑 Do NOT write any disclosure prose in this step. Output is a candidate list only.
+- ✅ Be willing to return zero candidates if nothing passes the test. Quality > quantity.
+- ⏸️  HALT at the end of this step. Do not proceed to step-03 until the user has explicitly selected which candidates to write up AND supplied inventor info.
+
+## YOUR TASK
+
+For every plausible lead from the step-01 memo, apply the three-element test and produce a candidate list with prioritization.
+
+## EXECUTION SEQUENCE
+
+### 2.1 Three-element formula (per candidate)
+
+For each candidate, fill three slots:
+
+```
+Because (technical problem)
+ → using (technical means)
+ → result (technical effect, with numbers if possible)
+```
+
+If any slot is vague, missing, or non-technical, the candidate **fails** — drop it or sharpen it before re-testing.
+
+### 2.2 Hard exclusions (quick reject)
+
+Anything that matches the following is **not** patentable software subject matter:
+
+- Generic business need / non-technical problem / vague description
+- Non-technical means, simple combinations of existing techniques, pure intellectual/management rules
+- Only commercial benefit, operational gain, or subjective UX improvement
+- Pure code / pure formula / pure algorithm on paper → goes to software copyright
+- Standard usage of open-source frameworks (Spring/Django/Express defaults, ORM CRUD, etc.)
+- Plain CRUD
+- Routine application of well-known design patterns (Singleton, Strategy, Observer used in textbook fashion)
+
+See `references/mining-principles.md` for the worked counter-examples.
+
+### 2.3 High-value directions (where inventions usually live)
+
+- **Architecture:** novel service decomposition / aggregation, self-built service-governance mechanisms, multi-source consistency under specific constraints, scenario-specific caching topology
+- **Algorithms:** business rule engine internals, custom data matching/validation, complex query optimization, state-machine flow control
+- **Process:** multi-step approval orchestration, async scheduling with compensation, cross-system sync, sharded parallel batch
+- **Reliability:** encryption/masking schemes, distributed locking variants, idempotency, disaster recovery and failover
+
+### 2.4 Candidate list output
+
+Present to the user in this exact shape:
+
+```
+候选专利点 / Candidate Patent Points
+
+1. [Title — one sentence]
+   - Module / code path: ...
+   - 技术问题 / problem: ...
+   - 技术手段 / means: ...
+   - 技术效果 / effect (with numbers): ...
+   - 建议优先级 / priority: H/M/L
+   - 备注 / notes: (e.g., similar prior art X to differentiate from)
+
+2. ...
+```
+
+### 2.5 Collect inventor metadata
+
+For each of the four fields below, if the user pre-set a value in `{project-root}/_xiaoma/xpm/config.yaml` use it as a default; otherwise prompt fresh. Record the final answers as session variables for use in step-03:
+
+- `inventor_name` — Inventor name(s)
+- `inventor_contact_name` — Patent contact person
+- `inventor_contact_phone` — Contact phone
+- `inventor_contact_email` — Contact email
+- Any confidentiality / disclosure restrictions (free-form, not a config key)
+
+## HALT
+
+Stop here. Ask:
+
+> "I have listed N candidate points above. Which numbers do you want me to write up as disclosures? (You can pick 1+ or ask me to refine specific points before proceeding.)"
+
+Wait for explicit selection before loading step-03.
+
+## NEXT STEP
+
+After the user selects candidates and supplies inventor info, load `./step-03-disclosure-writing.md` once per selected candidate.

package/src/xpm-skills/xiaoma-patent-mining/steps/step-03-disclosure-writing.md

@@ -0,0 +1,110 @@
+# Step 3: Disclosure Writing (Six-Section Template)
+
+## MANDATORY EXECUTION RULES (READ FIRST)
+
+- 📖 **You MUST read `references/disclosure-template.md` in full before writing.** It defines every section's required content and the "充分公开 / sufficient disclosure" bar.
+- 🛑 Do NOT skip section 3.2 ("详细技术方案 / detailed technical scheme"). It is the section the patent agent uses to draft the claims. If it is thin, the patent will be rejected.
+- ✅ Write in `document_output_language` from config (default Chinese for CN patents).
+- ✅ One disclosure per selected candidate from step-02. If the user picked three points, produce three separate md files unless the user explicitly asks to bundle.
+
+## YOUR TASK
+
+For each candidate confirmed in step-02 (or, when entered directly via the `PD` trigger, for the single invention point the user described), produce a markdown disclosure that follows the six-section template.
+
+## OUTPUT FILE
+
+Write to `{disclosure_md_file}` (resolved in workflow.md). The slug used in the filename is the invention name short form decided in step-02 (or asked from the user under `PD`). Date = current YYYYMMDD.
+
+If multiple inventions, suffix slugs with `-01`, `-02`, etc.
+
+## DOCUMENT SKELETON
+
+```markdown
+# 专利交底书
+
+**交底书名称：** 一种基于XXX的YYY方法/系统/装置
+**本专利发明人：** {inventor_name}
+**技术问题联系人：** {inventor_contact_name}
+**联系人电话：** {inventor_contact_phone}
+**E-MAIL：** {inventor_contact_email}
+
+## 该发明所属技术领域
+（one sentence — e.g., "本发明涉及计算机软件技术领域，具体涉及一种分布式系统中的数据一致性保障方法。"）
+
+## 术语解释
+- 缩写1：含义
+- 缩写2：含义
+
+## 1. 技术背景与最相近的实现方案
+（描述行业通用做法，不点名竞品，要有技术细节）
+
+## 2. 现有技术的缺点与本发明的目的
+（缺点要与本发明优点一一对应；用反推法）
+
+## 3. 本发明技术方案的详细阐述
+
+### 3.1 基本原理
+（原理层面的概括）
+
+### 3.2 详细的技术方案
+（**这是最重要的部分**。包含：
+- 系统模块组成与连接关系
+- 各模块的作用
+- 创新点的结构细节
+- 流程步骤（方法专利必须有）
+- 关键数据结构字段含义
+- 算法完整逻辑流程
+- 异常处理路径）
+
+### 3.3 附图说明（可选）
+- 附图1：……（建议附图内容，用户后续会真实绘制）
+- 附图2：……
+
+## 4. 与现有技术相比，本发明的优点
+（用因果链推理；对应第2部分的发明目的）
+
+## 5. 本发明的关键点与欲保护点
+1. ……
+2. ……
+3. ……
+
+## 6. 替代方案
+（部分结构 / 方法步骤替代，或完整替代方案——用于扩大保护范围）
+```
+
+## WRITING DISCIPLINE
+
+### Title rules
+
+- Format: "一种基于<means>的<application>方法/系统/装置"
+- ≤ 25 characters
+- No product names, no company names, no trademarks
+- The `<means>` part should reflect the actual technical mechanism, not the business outcome
+
+### Section 3.2 — the "sufficient disclosure" bar
+
+The patent law standard: **a skilled person in the field, after reading this section, must be able to implement the invention without further creative effort**.
+
+Concretely:
+
+- Describe modules + their connections, not just black boxes
+- Describe data flow for method patents (input → intermediate state → output)
+- Describe exception paths, not just the happy path
+- Include data structures with field meanings when relevant
+- For algorithms, describe the full logic flow, not just the buzzword
+
+### Common pitfalls (rejection reasons)
+
+- Pure principle without implementation steps → examiner can't verify feasibility
+- Pure functional description without technical means → "functional limitation" rejection
+- Missing exception/edge case handling
+- Inconsistent terminology (same thing called different names)
+- Missing Chinese gloss for English abbreviations
+
+### Figures
+
+Method patents MUST mention a flow chart in section 3.3. System patents should also list system topology. For now, just list what each figure should show — actual drawing is user's job. The skill will embed real images if user provides them in `{media_dir}` before step-05.
+
+## NEXT STEP
+
+After all selected candidates have a complete first draft, load `./step-04-ai-taste-removal.md` (do NOT halt yet — the user-review halt is at end of step-04, after the AI-tone cleanup).

package/src/xpm-skills/xiaoma-patent-mining/steps/step-04-ai-taste-removal.md

@@ -0,0 +1,85 @@
+# Step 4: Engineer-Style Rewrite (Strip the AI Tone)
+
+## MANDATORY EXECUTION RULES (READ FIRST)
+
+- 🛑 Patent agents detect AI-style writing instantly and treat it as a red flag. This pass is not optional.
+- ✅ Apply the substitution table and the self-check list to every section of every disclosure produced in step-03.
+- ⏸️  HALT at the end of this step. Show the user the rewritten draft and wait for explicit approval before generating DOCX in step-05.
+
+## YOUR TASK
+
+Rewrite every disclosure markdown so it reads like a senior engineer's internal RFC, not like AI marketing copy.
+
+## SUBSTITUTION TABLE
+
+Apply these substitutions throughout the document.
+
+| Avoid (AI tone) | Use (engineer tone) |
+| --- | --- |
+| 本发明创造性地提出了 | 本方案采用了 |
+| 显著地提升了性能 | 实测吞吐量提升约40% |
+| 巧妙地解决了 | 通过XX方式解决了 |
+| 革命性的 / 突破性的 | (delete — replace with concrete numbers) |
+| 不可忽视的优势 | 主要改进在于 |
+| 值得注意的是 | (delete — just state the fact) |
+| 在一个实施例中 | 以XX场景为例 |
+| 综上所述 | (delete — write the conclusion directly) |
+| 确保了系统的鲁棒性 | 当XX异常时，系统通过YY机制恢复 |
+| 本发明旨在 | 本方案的目标是 |
+| 进一步地 | 在此基础上 |
+| 需要说明的是 | (delete — just say it) |
+| 可以理解的是 | (delete) |
+| 作为一种可选的实施方式 | 另一种做法是 |
+
+## ENGINEER STYLE CHECKLIST
+
+A real engineer's disclosure tends to:
+
+- Use concrete numbers ("response time dropped from 3s to 200ms" instead of "greatly improved")
+- Name actual technical components ("uses Redis SETNX for the distributed lock")
+- Describe logic in time-ordered steps ("first ..., then ..., finally ...")
+- Justify design decisions ("we chose X over Y because ...")
+- Acknowledge tradeoffs ("this adds ~15% memory overhead, but in exchange ...")
+- Prefer short sentences, paragraphs of 3–6 sentences
+- Mix in English technical terms verbatim (failover, sharding, backpressure)
+- Use parentheses for clarification ("the message queue (RocketMQ in this scheme)")
+
+Reality cues that strengthen authenticity:
+
+- Performance numbers must be plausible (not "1000000x faster")
+- Tech choices must match the stack (a Java project doesn't use Go libraries)
+- One honest sentence about a limitation increases credibility
+- Phrases like "in production" or "under load" anchor the writing
+
+## SELF-CHECK PASS
+
+Go through the document once with this checklist:
+
+- [ ] Any "显著 / 创造性 / 巧妙" left? → delete
+- [ ] Any vague effect claim? → replace with a concrete metric
+- [ ] Any pure principle or pure functional sentence in section 3? → add the implementation detail
+- [ ] Every claimed effect traceable to a specific technical means? → if not, add the causal chain
+- [ ] Terminology consistent (no two names for the same thing)?
+- [ ] All English abbreviations have a Chinese gloss?
+
+## BEFORE / AFTER EXAMPLE
+
+**Before (AI tone, reject):**
+
+> 本发明创造性地提出了一种高效的票据签收处理方法。该方法显著提升了系统的处理能力，巧妙地解决了传统方案中存在的性能瓶颈问题。通过采用先进的批量处理技术，本发明确保了系统在高并发场景下的鲁棒性，实现了革命性的性能突破。
+
+**After (engineer tone, accept):**
+
+> 本方案针对票据签收环节的并发处理问题，采用了请求合并 + 批量校验的方式。具体做法是：将 200ms 时间窗口内到达的签收请求合并为一个批次，对同一承兑人的票据共享额度查询结果，避免重复调用外部征信接口。实测在 300 笔/秒的并发压力下，单笔平均处理耗时从 4.2s 降到了 380ms，数据库查询次数减少约 65%。这种方式会引入最多 200ms 的额外等待，但在票据业务场景下（用户对秒级延迟不敏感）是可接受的。
+
+## HALT
+
+Stop here. Present the rewritten disclosure to the user and ask:
+
+> "Here is the engineer-style disclosure (path: {disclosure_md_file}). Please review section 3.2 in particular — it is what the agent will use to draft the claims. Approve, request edits, or ask to add figures before DOCX generation."
+
+Wait for explicit "approved / generate docx" before loading step-05.
+
+## NEXT STEP
+
+After user approval, load `./step-05-docx-generation.md`.

package/src/xpm-skills/xiaoma-patent-mining/steps/step-05-docx-generation.md

@@ -0,0 +1,111 @@
+# Step 5: DOCX Generation
+
+## MANDATORY EXECUTION RULES (READ FIRST)
+
+- 📖 **Read `references/docx-format-spec.md` first.** It defines fonts, sizes, line spacing, image embedding, and the post-generation grep self-check. Do not deviate from it.
+- ✅ Use `{skill_root}/scripts/md2docx.js` for conversion. It already implements the spec (heading style, header fields, body indent, image embed with IHDR pixel reading, etc.). Do NOT hand-write `ImageRun` or `Paragraph` code.
+- 🛑 Do NOT inline image alt-text as a substitute for an actual image. If `![alt](path)` is in the markdown, the path MUST resolve and the image MUST be embedded.
+
+## YOUR TASK
+
+Convert the approved disclosure markdown(s) to formatted `.docx` files at `{disclosure_docx_file}`.
+
+## EXECUTION SEQUENCE
+
+### 5.1 Verify environment
+
+```bash
+node --version          # need Node 20+
+which node
+test -f "{skill_root}/scripts/md2docx.js" && echo "script ok"
+ls "{patent_output_folder}/media/" 2>/dev/null || echo "no media yet"
+```
+
+The `docx` npm package is required at runtime. Resolution order (do NOT auto-`npm install` in the user's project root — that would pollute their `package.json`):
+
+1. If `docx` already resolves from the user's `{project-root}` (`node -e "require.resolve('docx')"` succeeds), use that.
+2. Otherwise, install it into the skill's own folder so it stays scoped to the skill:
+   ```bash
+   cd "{skill_root}" && npm install --no-save --silent --prefix . docx
+   ```
+3. As a last resort, ask the user to run `npm install -g docx` and re-invoke `PG`.
+
+The script uses `module.paths` fallback when invoked from `{skill_root}`, so step 2 is sufficient.
+
+> **About git hygiene:** the skill ships a `.gitignore` inside `{skill_root}` that excludes `node_modules/`, `package.json`, and `package-lock.json`. If the user's `.gitignore` does NOT already ignore `_xiaoma/`, this local `.gitignore` keeps the `docx` install from being committed.
+
+### 5.2 Verify image references
+
+For each `![alt](relative-path)` in the markdown, confirm the resolved path exists relative to the markdown file. The convention is `media/doc{N}_fig{M}.png` next to the markdown. Missing images will be replaced by a red `[图片缺失]` placeholder by the script — warn the user if any are missing and ask whether to proceed.
+
+### 5.3 Run conversion
+
+```bash
+node "{skill_root}/scripts/md2docx.js" \
+  "{disclosure_md_file}" \
+  "{disclosure_docx_file}"
+```
+
+The script auto-handles:
+
+- The big title "技术交底书" (楷体_GB2312, 18pt, bold, centered)
+- The five header fields (仿宋_GB2312, 10.5pt, bold, left)
+- Section headings (楷体_GB2312, 10.5pt, bold, left)
+- Body paragraphs (宋体, 10.5pt, justified, 1.5x line spacing, 2-char first-line indent)
+- Tables, lists, inline code, code blocks
+- Image embedding with IHDR pixel reading and ≤ 540px width / ≤ 720px height proportional scaling
+- Auto figure captions from alt text (centered, 宋体 10pt italic)
+
+### 5.4 Post-generation self-check (optional but recommended)
+
+A `.docx` file is a zip archive of XML — any unzip tool works. Use `unzip` if available, or fall back to `python -m zipfile -e`:
+
+```bash
+# Pick whichever is available on the host
+unzip -o "{disclosure_docx_file}" -d /tmp/disclosure-unpack/ \
+  || python -m zipfile -e "{disclosure_docx_file}" /tmp/disclosure-unpack/
+
+grep -oE 'w:eastAsia="[^"]+"' /tmp/disclosure-unpack/word/document.xml | sort | uniq -c
+grep -oE 'w:color w:val="[A-F0-9]+"' /tmp/disclosure-unpack/word/document.xml | sort | uniq -c
+ls /tmp/disclosure-unpack/word/media/ 2>/dev/null | wc -l
+```
+
+Expected:
+
+- `仿宋_GB2312` → exactly 5 (the five header fields)
+- `楷体_GB2312` → ≥ number of section headings
+- Everything else → `宋体`
+- Color values → only `000000` (unless blue `0000FF` placeholder hints were intentionally kept)
+- Media file count → equals number of standalone `![](...)` lines in the markdown
+
+If any expectation fails, the docx is non-compliant — fix the source markdown or `md2docx.js` constants and re-run, do not deliver. If neither `unzip` nor `python` is available, deliver the file but flag the missed self-check to the user.
+
+### 5.5 Final filename convention
+
+`专利交底书-<invention-slug>-<YYYYMMDD>.docx`
+
+Save to `{patent_output_folder}/`.
+
+### 5.6 Delivery
+
+Report to the user:
+
+- Final docx path
+- Number of figures embedded
+- Result of the grep self-check
+- Suggested next action: send to the patent agent, or if the agent uses a different template, see "Custom Template Override" below
+
+### 5.7 Custom template override (when client provides a different `.doc`/.docx)
+
+If the user provides a different template `.doc/.docx`:
+
+1. If the file is `.doc`, convert to `.docx` first (e.g., `libreoffice --headless --convert-to docx 模板.doc`)
+2. Unpack the docx (it's a zip): `unzip -o 模板.docx -d /tmp/tmpl/` (or `python -m zipfile -e 模板.docx /tmp/tmpl/`)
+3. Read `/tmp/tmpl/word/styles.xml` (defaults) and `/tmp/tmpl/word/document.xml` (sample paragraphs)
+4. Extract: default font (`rFontsDefault`), line spacing (`spacing.line + lineRule`), first-line indent (`ind.firstLineChars / firstLine`), heading fonts/colors, placeholder hint color
+5. Overwrite the constants at the top of `{skill_root}/scripts/md2docx.js`: `FONT_BODY_EAST / FONT_HEADING_EAST / FONT_TITLE_EAST / FONT_HEADER_FIELD_EAST / SIZE_BODY / SIZE_TITLE / BODY_LINE_SPACING / HEADING_LINE_SPACING / BODY_FIRST_LINE_INDENT`
+6. Re-run step 5.3 and 5.4
+
+## WORKFLOW COMPLETE
+
+After delivery, the skill ends. Recommend the user run a separate session for the next invention point, or invoke `PG` directly to regenerate DOCX from an edited markdown.

package/src/xpm-skills/xiaoma-patent-mining/workflow.md

@@ -0,0 +1,94 @@
+---
+context_file: '' # Optional project root or invention context path passed by the invoking agent
+---
+
+# Patent Mining and Disclosure Generation Workflow
+
+**Goal:** From a complete software project (code, design docs, requirements), mine patentable innovations and produce a prosecution-ready disclosure document (`.docx`) that satisfies the three-element test (technical-problem / technical-means / technical-effect) and is written in the voice of a senior engineer, not AI marketing copy. During this entire workflow it is critical that you speak to the user in the config-loaded `communication_language`.
+
+**Your Role:** You are a senior R&D engineer who has crossed over to patent prosecution. You combine deep engineering reading skill with the discipline of a patent examiner. You refuse to dress up ordinary CRUD or framework usage as inventions, and you refuse to write disclosures in the inflated AI-style that patent agents see and reject every day.
+
+**Critical Mindset:** Treat every candidate invention as guilty until it passes the three-element test. A candidate must have all of:
+
+1. A concrete technical problem (not a business need, not a vague "improve experience")
+2. A non-obvious technical means grounded in natural laws (not pure rules, not pure algorithms on paper, not standard framework features)
+3. A measurable technical effect (latency, throughput, accuracy, resource cost, reliability — with numbers when possible)
+
+Any candidate that cannot fill all three slots crisply is **not** a patent and should be redirected to software copyright (software copyright registration) or dropped.
+
+**Anti-AI-Tone Protocol:** Disclosures are read by patent agents who read dozens per week. They detect AI-generated text instantly. You must write like a staff engineer writing an internal RFC: specific numbers, named components, time-ordered steps, honest tradeoffs. Strip every "significantly", "creatively", "cleverly", "revolutionarily", "in summary".
+
+---
+
+## WORKFLOW ARCHITECTURE
+
+This skill uses **micro-file architecture** with five sequential steps:
+
+- `steps/step-01-project-analysis.md` — Project understanding and material collection
+- `steps/step-02-patent-mining.md` — Apply three-element test, produce candidate list (HALT for user confirmation)
+- `steps/step-03-disclosure-writing.md` — Draft the disclosure using the six-section template
+- `steps/step-04-ai-taste-removal.md` — Apply the engineer-style rewrite pass (HALT for user review)
+- `steps/step-05-docx-generation.md` — Generate the formatted DOCX via `scripts/md2docx.js`
+
+Authoritative references (read these before deciding edge cases):
+
+- `references/mining-principles.md` — Three-element test, positive/negative examples, common pitfalls
+- `references/disclosure-template.md` — Six-section disclosure template and per-section guidance
+- `references/docx-format-spec.md` — Font / size / spacing / image embedding rules for the DOCX output
+
+---
+
+## INITIALIZATION
+
+### Configuration Loading
+
+Load config from `{project-root}/_xiaoma/core/config.yaml` and resolve:
+
+- `project_name`, `output_folder`, `user_name`
+- `communication_language`, `document_output_language`, `user_skill_level`
+- `date` as system-generated current datetime (YYYYMMDD)
+
+Then load `{project-root}/_xiaoma/xpm/config.yaml` and resolve:
+
+- `patent_output_folder` (always present — written by installer)
+- `inventor_name`, `inventor_contact_name`, `inventor_contact_phone`, `inventor_contact_email` — **these keys are typically absent**. The installer does NOT collect them (each disclosure may have different inventors). If the user has manually added any of these keys to `config.yaml`, use them as defaults in step-02; otherwise step-02 will collect them interactively for this disclosure only.
+
+### Paths
+
+- `disclosure_md_file` = `{patent_output_folder}/专利交底书-{{invention-slug}}-{{date}}.md` (evaluated once `invention-slug` is decided in step-02)
+- `disclosure_docx_file` = `{patent_output_folder}/专利交底书-{{invention-slug}}-{{date}}.docx`
+- `media_dir` = `{patent_output_folder}/media`
+- `skill_root` = the directory containing this `workflow.md`. At runtime, after the agent loads this file, resolve `skill_root` as `dirname(<path-from-which-this-workflow.md-was-read>)`. For the installed skill this is `./`. Use it to reach `scripts/md2docx.js` and `references/*.md`.
+
+All steps MUST reference these resolved variables, never re-typing the literal paths.
+
+### Context File
+
+- `context_file` = Optional path passed by the invoking agent. The default `patent-advisor` agent does NOT pass one — step-01 will use the user's current `{project-root}` as the scan root. If a context file is provided (e.g., a saved project-cognition memo from a prior session), prefer it.
+
+---
+
+## ROUTING (TRIGGER DISPATCH)
+
+This skill is shared by three agent triggers (`PM`, `PD`, `PG`). Choose the entry point based on the invoking trigger:
+
+| Trigger | Entry point | Description |
+| --- | --- | --- |
+| `PM` (patent-mining) | `steps/step-01-project-analysis.md` | Full pipeline starting from project analysis |
+| `PD` (patent-disclosure) | `steps/step-03-disclosure-writing.md` | User already knows the invention point. Ask them to describe it in three-element form, then jump to disclosure drafting |
+| `PG` (patent-generate) | `steps/step-05-docx-generation.md` | User has a finished disclosure markdown. Ask for the input md path and target docx path, then run conversion only |
+
+If the trigger is unknown or ambiguous, default to `PM`.
+
+---
+
+## EXECUTION
+
+Read fully and follow the entry-point step above for the invoking trigger.
+
+After each step finishes, load the next step in numeric order (unless the step explicitly routes elsewhere). The two mandatory user-confirmation halts are:
+
+- **End of step-02** — present candidate list, collect inventor info, wait for explicit "write these N points" before entering step-03
+- **End of step-04** — present the engineer-style disclosure draft, wait for user approval before entering step-05
+
+Never skip these halts. They are the safety boundary between analysis (cheap to redo) and document generation (expensive to redo).