Description

Multi-Agent system for writing ultra-long feasibility study reports. Phase 0 Requirement Confirmation - Phase 1 Planner outputs outline - Phase 2 Batch paral...

README (SKILL.md)

\r \r Phase 2.5 跨章一致性审查 → Phase 3 整合师汇总输出精美 docx。\r 核心文件：src/engine.py（核心逻辑）、src/config.py（配置）、integrate_report.py（兼容 facade）。\r ---\r \r

超长可研报告多Agent协作撰写 v3.3\r

Name: lobsterai-report-agent
Author: jinqiu193

\r

更新日志（v4.0）\r

\r

✅ 重构拆分：src/config.py（配置+I/O） + src/engine.py（核心逻辑） + src/cli.py（CLI入口）\r
✅ integrate_report.py 保留为 facade，100% 向后兼容旧接口\r
✅ Mermaid CLI 惰性加载（import 时不执行 subprocess）\r
✅ 路径全部可配置（环境变量 LOBAI_CHAPTERS_DIR / LOBAI_OUTPUT_DIR）\r
✅ 通知渠道可配置（notify.py：log / feishu / openclaw-weixin）\r
✅ 新增 README.md + LICENSE\r \r

核心能力\r

\r

多Agent并行：最多5个子Agent并发撰写，效率翻倍\r
增量更新：内容未变化的章节跳过重写，速度提升\r
精美排版：自动生成封面、表格式目录、彩色章节标题、重点标注盒、美化表格\r
飞书RAG：自动检索飞书知识库补充参考资料\r
6种封面风格：随意切换，适合不同场景\r \r ---\r \r

文件结构\r

\r

skill_dir/\r
├── SKILL.md                    # 本文件\r
├── README.md                   # 项目说明（开源版）\r
├── LICENSE                    # MIT License\r
├── requirements.txt           # Python 依赖\r
├── integrate_report.py         # facade（兼容旧接口）+ CLI 入口\r
├── parallel_tracker.py         # 并行进度追踪\r
├── notify.py                  # 可配置通知渠道\r
├── src/\r
│   ├── __init__.py            # 公共 API 导出\r
│   ├── config.py              # 路径配置 + 文件 I/O\r
│   ├── engine.py               # 核心业务逻辑\r
│   └── cli.py                 # CLI 入口\r
└── references/                # 子流程参考文档\r
    ├── phase0_guide.md         # Phase 0 需求确认流程\r
    ├── phase1_guide.md         # 规划师 prompt 模板\r
    ├── phase2_guide.md         # 子Agent prompt 模板\r
    ├── table_format_guide.md   # Markdown表格格式规范\r
    └── bug_fix_guide.md        # Bug排查与强制重建\r
```\r
\r
> **首次使用前**：工作目录为 `~/.config/lobsterai-report-agent/`（自动创建），可通过 `LOBAI_CHAPTERS_DIR` 环境变量覆盖。\r
\r
---\r
\r
## Pipeline 路由\r
\r
```\r
用户任务\r
├─ 首次提出撰写需求（"我要写xxx"/"帮我写可研报告"）\r
│   → Phase 0 需求确认 → Phase 1 规划师\r
│\r
├─ 已有大纲，要求开始撰写\r
│   → Phase 2 分批并行子Agent\r
│\r
├─ 某章节需修改\r
│   → 小改动：直接编辑 F:/agent/chapters/0X-xxx.txt\r
│   → 大改动：重新生成该章节\r
│\r
├─ 所有章节已完成，要求生成 docx\r
│   → Phase 2.5 审查 → Phase 3 整合师汇总\r
│\r
├─ 独立小方案（2~5章，无现有chapters依赖）\r
│   → 直接写作 Markdown → make_docx.py 生成精美 docx\r
│   → 参考：references/bug_fix_guide.md "make_docx.py 模式"\r
│\r
└─ 只需查看进度/术语表/参考资料\r
    → 直接 CLI 命令\r
```\r
\r
---\r
\r
## Phase 0：需求确认\r
\r
依次确认4项，全部确认后进入 Phase 1：\r
\r
1. **写作主题**：文档类型/读者/风格/特殊约束\r
2. **背景信息**：项目背景/建设目标/行业背景\r
3. **参考资料**（最重要）：\r
   - A. 本地文件路径或直接粘贴\r
   - B. 飞书文档（RAG检索）\r
   - C. 直接粘贴内容\r
   - D. 暂不提供\r
4. **大纲确认**：规划师输出大纲后，用户选择 A.开始 / B.调整 / C.取消\r
\r
> 参考资料越充分，内容与业务越贴合。详见 `references/phase0_guide.md`\r
\r
---\r
\r
## Phase 1：规划师\r
\r
**输入**：Phase 0 的主题/背景/参考资料\r
\r
**执行**：\r
```bash\r
python integrate_report.py glossary\r
```\r
自动生成 `plan.json` + `plan_outline_snapshot.md`\r
\r
> 详细 prompt 模板见 `references/phase1_guide.md`\r
\r
**完成后通知**（通过 `notify.py`，渠道由 `config.json` 的 `notification_channel` 字段决定）：\r
\r
```python\r
# 在 Agent 指令中使用 notify 模块\r
from notify import notify\r
notify(f"""📋 报告大纲已生成\r
\r
📌 《[报告主题]》\r
📊 章节数：[X]章\r
🔍 行业：[行业领域]\r
\r
✅ 大纲确认后请回复"开始撰写"，系统将启动并行创作！""")\r
```\r
\r
默认渠道为 `log`（打印到控制台）。开源用户可配置为 `feishu` 或 `openclaw-weixin`。\r
\r
---\r
\r
## Phase 2：分批并行子Agent\r
\r
**执行流程**（全自动，无需人工确认）：\r
1. 展示大纲/当前批次状态（仅展示，不等待确认）\r
2. `python parallel_tracker.py clear` 清空上批次状态\r
3. 最多5并发启动子Agent（`sessions_spawn`），自动执行全部批次\r
4. `python parallel_tracker.py wait` 后台监控，直至本批全部完成\r
5. 完成后自动执行 `python integrate_report.py convert-batch`\r
\r
**子Agent prompt 模板**：见 `references/phase2_guide.md`\r
\r
**每批次完成后通知**：\r
\r
```python\r
from notify import notify\r
notify(f"""✅ 第[X]批章节撰写完成！\r
\r
📖 已完成：[已完成数]/[总章节数] 章\r
📝 本批完成：[章节列表]\r
\r
⏳ 下一批：[下一批章节列表]\r
（自动进入下一批，无需人工确认）""")\r
```\r
\r
📖 已完成：[已完成数]/[总章节数] 章\r
📝 本批完成：\r
   • [章节1标题]\r
   • [章节2标题]\r
   • [章节3标题]（如有）\r
\r
⏳ 下一批：[下一批章节列表]\r
（自动进入下一批，无需人工确认）\r
```\r
- 小改动：直接编辑 `F:/agent/chapters/0X-xxx.txt`，保存后重新生成\r
- 大改动：重新触发子Agent重写，替换原文件\r
\r
---\r
\r
## Phase 2.5：跨章一致性审查\r
\r
```bash\r
python integrate_report.py check\r
```\r
审查数量指标一致性与术语统一性（对照 glossary.json）\r
\r
**审查完成后通知**：\r
\r
```python\r
from notify import notify\r
notify(f"""🔍 一致性审查完成\r
\r
✅ 术语统一性：正常\r
✅ 数量指标：一致\r
✅ 跨章引用：无冲突\r
\r
📄 即将进入最终整合阶段...\r
```\r
\r
---\r
\r
## Phase 3：整合师汇总\r
\r
```bash\r
python integrate_report.py\r
```\r
\r
自动完成：解析章节（错误隔离）→ 更新术语表 → 一致性审查 → 生成精美 docx\r
\r
**最终完成后通知**：\r
\r
```python\r
from notify import notify\r
notify(f"""🎉🎉🎉 报告撰写完成！🎉🎉🎉\r
\r
📄 《[报告主题]》\r
📊 规模：[X]章 / 约[Y]万字\r
🎨 封面风格：[风格名称]\r
\r
✅ 精美版报告已生成！\r
📁 文件位置：F:/agent/chapters/output/\r
\r
文心，全文已就绪，可进行后续审阅~\r
```\r
\r
---\r
\r
## 文档美化功能（自动应用）\r
\r
生成报告自动包含以下排版效果（通过 `plan.json` 中 `cover_style` 字段选择）：\r
\r
1. **6种封面风格** — 修改 `plan.json` → `cover_style` 字段（整数 1～6）\r
2. **执行摘要** — 深蓝标题条（`#1F4E79`）背景 + 白字 + 正文缩进\r
3. **表格式目录** — 深蓝标题条 + 三列条目（序号/章节/页码）\r
4. **彩色章节标题**：\r
   - H1：整行深藏蓝底色 `#1F4E79` + 白字微软雅黑\r
   - H2：中蓝底色 `#2E75B6` + 白字\r
   - H3：淡蓝背景 `#D6E4F0` + 深蓝字 + `▌` 左边条\r
5. **重点标注盒** — 自动识别【关键】【注意】【优势】【风险】【数据】标签，渲染为彩色卡片（背景/白字/边框）\r
6. **美化表格** — 表头深藏蓝背景 `#1F4E79` + 白字 + 奇偶行交替底色（`#DEEAF6` / `#FFFFFF`）\r
\r
---\r
\r
## 封面样式（6种风格）\r
\r
封面风格通过 `plan.json` 中的 `cover_style` 字段指定（整数，1～6）：\r
\r
| 编号 | 风格名称 | 特点 | 推荐场景 |\r
|------|----------|------|----------|\r
| 1 | 经典政务风格 | 深藏蓝顶条 + 金色点缀 | 政府/国企审批 |\r
| 2 | 现代简约风格 | 左侧蓝色重色块 + 右侧信息 | 科技/商务汇报 |\r
| 3 | 商务典雅风格 | 酒红配色 + 居中递进 | 咨询/投行报告 |\r
| 4 | 科技数字风格 | 深海蓝铺满 + 大字白字标题 | 互联网/数字化 |\r
| 5 | 中式传统风格 | 故宫红 + 宣纸米色背景 | 传统文化/国企 |\r
| 6 | 全屏沉浸风格 | 深海蓝铺满 + 大字白字标题 | 数字化/科技项目 |\r
\r
> **注意**：`cover_style` 值为整数（如 `4`），代码会自动转换为字符串比较。\r
\r
---\r
\r
## CLI 命令速查\r
\r
| 命令 | 作用 |\r
|------|------|\r
| `python integrate_report.py` | 生成整合报告（全量） |\r
| `python integrate_report.py convert-batch` | 批量生成 docx |\r
| `python integrate_report.py convert-one \x3Cin> \x3Cout>` | 单章转 docx |\r
| `python integrate_report.py check` | 一致性审查 |\r
| `python integrate_report.py glossary` | 术语表生成/更新 |\r
| `python integrate_report.py ref show` | 查看参考资料 |\r
| `python integrate_report.py ref clear` | 清空参考资料 |\r
| `python integrate_report.py preview [章节前缀]` | 预览章节摘要 |\r
| `python integrate_report.py feishu-search \x3Cquery>` | 搜索飞书知识库 |\r
| `python parallel_tracker.py show` | 查看撰写进度 |\r
| `python parallel_tracker.py wait` | 阻塞监控（Ctrl+C停止） |\r
| `python parallel_tracker.py clear` | 清空追踪状态 |\r
\r
> **封面风格切换**：修改 `F:/agent/chapters/plan.json` 中的 `cover_style` 字段（整数 1～6），然后重新生成。\r
> 修改代码后需删除 `__pycache__` 下的 `.pyc` 文件 + `content_hashes.json` 强制重建。\r
\r
---\r
\r
## 状态文件\r
\r
> 工作目录默认：`~/.config/lobsterai-report-agent/chapters/`（可通过 `LOBAI_CHAPTERS_DIR` 环境变量覆盖）\r
\r
| 文件 | 作用 |\r
|------|------|\r
| `\x3CCHAPTERS_DIR>/plan.json` | 章节元数据 |\r
| `\x3CCHAPTERS_DIR>/glossary.json` | 术语表 |\r
| `\x3CCHAPTERS_DIR>/reference_material.txt` | 参考资料原文 |\r
| `\x3CCHAPTERS_DIR>/plan_outline_snapshot.md` | 大纲快照 |\r
| `\x3CCHAPTERS_DIR>/content_hashes.json` | 增量缓存（删后强制重建） |\r
| `\x3CCHAPTERS_DIR>/writing_tracker.json` | 并行进度追踪 |\r
| `\x3CCHAPTERS_DIR>/config.json` | 项目配置（封面风格、通知渠道等） |\r
\r
---\r
\r
## Critical Rules\r
\r
### Markdown 表格格式（子Agent必须遵守）\r
\r
详见 `references/table_format_guide.md`\r
\r
核心要点：\r
- 分隔行必须是 `|---|---|---|`（首尾 `|` 不可省略）\r
- 各行列数必须与表头一致\r
- 单元格内容避免包含 `|`（用 `～` 或 `-` 表示范围）\r
\r
### 强制重建（修改代码后必须两步都做）\r
\r
修改 `src/engine.py` 或 `src/config.py` 后，必须同时删除以下两个文件才能让新代码生效：\r
\r
```bash\r
# 1. 删除 .pyc 缓存（修改代码后必须）\r
# Linux/macOS\r
find . -type d -name __pycache__ -exec rm -rf {} +\r
# Windows\r
Get-ChildItem . -Recurse -Directory __pycache__ | Remove-Item -Recurse -Force\r
\r
# 2. 删除增量 hash（否则增量模式跳过重写）\r
# 默认路径\r
del "%USERPROFILE%\.config\lobsterai-report-agent\chapters\content_hashes.json"\r
\r
# 3. 重新生成\r
python integrate_report.py\r
```\r
\r
### 已知 Bug 已修复（记录备查）\r
\r
详见 `references/bug_fix_guide.md`，包括：\r
- `_flush_table` 未调用 `_parse_md_table` 导致表格逐字拆列（v3 早期版本）\r
- `ensure_mermaid_deps()` 在 import 时执行 subprocess（现已改为惰性）\r
- `.pyc` 缓存导致修改后的代码不生效\r
- `RGBColor` 用索引而非 `.red/.green/.blue` 属性\r
- `add_cover()` 设置 `section.margin=0` 导致正文无边距\r
\r
---\r
\r
## References\r
\r
| 文件 | 内容 |\r
|------|------|\r
| `references/phase0_guide.md` | Phase 0 需求确认完整流程与话术 |\r
| `references/phase1_guide.md` | 规划师完整 prompt 模板与 plan.json 格式 |\r
| `references/phase2_guide.md` | 子Agent完整 prompt 模板（含表格格式警告） |\r
| `references/table_format_guide.md` | Markdown表格格式规范、常见错误与示例 |\r
| `references/bug_fix_guide.md` | Bug排查与强制重建操作步骤 |\r

Usage Guidance

This skill is generally coherent with its purpose (local multi-agent report generation) but has a few notable inconsistencies you should review before installing or running it: - It reads/writes files under a user directory (default: ~/.config/lobsterai-report-agent/) and will create plan.json, chapter txt files, snapshots, and docx outputs. Make sure you are comfortable with the skill creating and modifying files there and set LOBAI_CHAPTERS_DIR / LOBAI_OUTPUT_DIR if you prefer a different location. - SKILL.md promises "飞书RAG" retrieval, but the code does not implement Feishu API calls or require Feishu credentials. If you expect automatic Feishu RAG, verify or implement that integration yourself. Notifications can attempt to use openclaw_runtime if available; that depends on your OpenClaw runtime and its configuration. - Some prompt templates and examples contain hardcoded Windows paths (F:/agent/..., AppData paths) and sys.path insertions. Do NOT blindly execute those example paths in environments where they don't apply; they may cause subagents to import code from unexpected locations. - There are minor API mismatches between templates and modules (e.g., template calls to chapter_register vs. module's Tracker.register). If you or child agents follow the templates verbatim, they may error. Review/adjust the prompts to match actual module APIs. - The skill may use subprocess to call Mermaid CLI (mmdc/node) if you enable mermaid rendering. Ensure you trust any binaries you install for that (npm-installed mmdc or node) and be aware that rendering will execute subprocesses. - The workflow includes autonomous spawning of subagents (sessions_spawn). Only enable or run the skill in an environment where you trust the agent to spawn and run subagents that will read/write the configured directories. Actionable checklist before use: 1. Inspect/backup the target chapters directory and any existing files in the default path. 2. Set LOBAI_CHAPTERS_DIR and LOBAI_OUTPUT_DIR explicitly to directories you control. 3. Review notify.py and confirm notification channel behavior; do not expect Feishu RAG to work without additional integration. 4. Review and (if needed) correct the prompt templates in references/ to match the actual Python API (Tracker.register/update/mark_done vs. template helper names). 5. Install python-docx and optionally mermaid-cli only from trusted sources if you need mermaid rendering. Given the inconsistencies and mismatch between claimed features and implementation, proceed with caution and review the code and prompts before running the skill in production.

Capability Analysis

Type: OpenClaw Skill Name: lobsterai-report-agent Version: 1.0.1 The lobsterai-report-agent bundle is a legitimate multi-agent system designed to orchestrate the generation of complex feasibility study reports in .docx format. The code utilizes standard libraries like python-docx and integrates with the Mermaid CLI for diagram rendering via subprocess.run. While it employs potentially risky functions such as os.system for console management and subprocess for external tool execution, these are used strictly for their stated purposes (clearing the screen and rendering charts). The instructions in SKILL.md and the reference guides are task-oriented and do not contain malicious prompt injections or instructions to exfiltrate sensitive data. The notification system (notify.py) correctly leverages the OpenClaw runtime for status updates.

Capability Assessment

ℹ Purpose & Capability

Name/description and most code files align with a local multi-agent report generator that reads/writes chapter files, produces docx, and renders mermaid diagrams. However, SKILL.md claims features ("飞书RAG" automatic retrieval) that are not implemented in the codebase; many example/reference files use hardcoded Windows paths (F:/agent/..., AppData paths) while config.py defaults to ~/.config, which is inconsistent.

ℹ Instruction Scope

Runtime instructions and prompt templates direct the agent to read and write local files (chapters, plan.json, reference_material.txt) and to spawn subagents (sessions_spawn) that will also read/write the same filesystem. That behavior is coherent for a multi-agent writer. Concerns: prompt templates show calls/imports and function names (e.g., chapter_register, chapter_update, chapter_done) that don't exactly match the module API (parallel_tracker provides Tracker.register/update/mark_done), and templates include hardcoded example sys.path insertions pointing at a SKILL install location — this could lead to unexpected imports if followed verbatim.

✓ Install Mechanism

No install spec is provided (instruction-only plus shipped source files). The repository relies on python-docx and optionally the mermaid CLI (mmdc/node). No remote downloads, no URL-based installers, and no extract-from-URL steps are present in the provided files.

ℹ Credentials

The skill declares no required environment variables or credentials. The code references optional env vars (LOBAI_CHAPTERS_DIR, LOBAI_OUTPUT_DIR, LOBAI_NOTIFY_CHANNEL) which are reasonable for configuring file locations and notification channel. There are no requests for unrelated secrets or cloud credentials. The SKILL.md does mention Feishu RAG and OpenClaw notification channels, but the code does not implement Feishu API calls nor request Feishu credentials — notification functions attempt to call openclaw_runtime if present, which depends on the runtime environment.

✓ Persistence & Privilege

always:false and user-invocable:true. The skill writes files under a user-scoped directory (defaults to ~/.config/lobsterai-report-agent/), and does not request system-wide configuration edits or other skills' credentials. It will spawn child agent sessions as part of its workflow (sessions_spawn described in SKILL.md), which is expected for a multi-agent workflow but increases runtime activity — this is an expected capability, not an unexplained privilege.

Version History

v1.0.1

lobsterai-report-agent 1.0.1 - No file or code changes detected in this release. - All features and behavior remain identical to the previous version.

v1.0.0

lobsterai-report-agent v4.0.0 — Major refactor and enhancement update - Core codebase refactored into src/config.py (I/O & config), src/engine.py (core logic), src/cli.py (CLI entry). - integrate_report.py retained as a backward-compatible facade for existing interfaces. - Configurable file paths and output directories via environment variables (LOBAI_CHAPTERS_DIR / LOBAI_OUTPUT_DIR). - Notification channels now configurable (log, feishu, or openclaw-weixin). - Mermaid CLI is now lazily loaded for improved performance. - README.md and LICENSE files added for open-source use. - Enhanced multi-Agent parallel writing, incremental updates, and polished DOCX export with multiple cover styles. - See SKILL.md for updated CLI commands, configuration, and pipeline details.

Metadata

Slug lobsterai-report-agent

Version 1.0.1

License MIT-0

All-time Installs 0

Active Installs 0

Total Versions 2

Frequently Asked Questions

What is lobsterai-report-agent?

Multi-Agent system for writing ultra-long feasibility study reports. Phase 0 Requirement Confirmation - Phase 1 Planner outputs outline - Phase 2 Batch paral... It is an AI Agent Skill for Claude Code / OpenClaw, with 90 downloads so far.

How do I install lobsterai-report-agent?

Run "/install lobsterai-report-agent" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.

Is lobsterai-report-agent free?

Yes, lobsterai-report-agent is completely free, licensed under MIT-0. You can download, install and use it at no cost.

Which platforms does lobsterai-report-agent support?

lobsterai-report-agent is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).

Who created lobsterai-report-agent?

It is built and maintained by jinqiu193 (@jinqiu193); the current version is v1.0.1.

More Skills

lobsterai-report-agent