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...

Security Scan

The skill largely matches its stated purpose (multi-agent report generation) but contains several inconsistencies and implementation gaps (example hardcoded paths, claimed Feishu RAG integration not implemented, mismatched helper names in prompts) that warrant caution before use.

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.

What to consider before installing

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.

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

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

更新日志（v4.0）

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

核心能力

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

---

文件结构

skill_dir/
├── SKILL.md                    # 本文件
├── README.md                   # 项目说明（开源版）
├── LICENSE                    # MIT License
├── requirements.txt           # Python 依赖
├── integrate_report.py         # facade（兼容旧接口）+ CLI 入口
├── parallel_tracker.py         # 并行进度追踪
├── notify.py                  # 可配置通知渠道
├── src/
│   ├── __init__.py            # 公共 API 导出
│   ├── config.py              # 路径配置 + 文件 I/O
│   ├── engine.py               # 核心业务逻辑
│   └── cli.py                 # CLI 入口
└── references/                # 子流程参考文档
    ├── phase0_guide.md         # Phase 0 需求确认流程
    ├── phase1_guide.md         # 规划师 prompt 模板
    ├── phase2_guide.md         # 子Agent prompt 模板
    ├── table_format_guide.md   # Markdown表格格式规范
    └── bug_fix_guide.md        # Bug排查与强制重建

首次使用前：工作目录为 ~/.config/lobsterai-report-agent/（自动创建），可通过 LOBAI_CHAPTERS_DIR 环境变量覆盖。

---

Pipeline 路由

用户任务
├─ 首次提出撰写需求（"我要写xxx"/"帮我写可研报告"）
│   → Phase 0 需求确认 → Phase 1 规划师
│
├─ 已有大纲，要求开始撰写
│   → Phase 2 分批并行子Agent
│
├─ 某章节需修改
│   → 小改动：直接编辑 F:/agent/chapters/0X-xxx.txt
│   → 大改动：重新生成该章节
│
├─ 所有章节已完成，要求生成 docx
│   → Phase 2.5 审查 → Phase 3 整合师汇总
│
├─ 独立小方案（2~5章，无现有chapters依赖）
│   → 直接写作 Markdown → make_docx.py 生成精美 docx
│   → 参考：references/bug_fix_guide.md "make_docx.py 模式"
│
└─ 只需查看进度/术语表/参考资料
    → 直接 CLI 命令

---

Phase 0：需求确认

依次确认4项，全部确认后进入 Phase 1：

1. 写作主题：文档类型/读者/风格/特殊约束
2. 背景信息：项目背景/建设目标/行业背景
3. 参考资料（最重要）：
   • A. 本地文件路径或直接粘贴
   • B. 飞书文档（RAG检索）
   • C. 直接粘贴内容
   • D. 暂不提供
4. 大纲确认：规划师输出大纲后，用户选择 A.开始 / B.调整 / C.取消

参考资料越充分，内容与业务越贴合。详见 references/phase0_guide.md

---

Phase 1：规划师

输入：Phase 0 的主题/背景/参考资料

执行：

python integrate_report.py glossary

自动生成 plan.json + plan_outline_snapshot.md

详细 prompt 模板见 references/phase1_guide.md

完成后通知（通过 notify.py，渠道由 config.json 的 notification_channel 字段决定）：

# 在 Agent 指令中使用 notify 模块
from notify import notify
notify(f"""📋 报告大纲已生成

📌 《[报告主题]》
📊 章节数：[X]章
🔍 行业：[行业领域]

✅ 大纲确认后请回复"开始撰写"，系统将启动并行创作！""")

默认渠道为 log（打印到控制台）。开源用户可配置为 feishu 或 openclaw-weixin。

---

Phase 2：分批并行子Agent

执行流程（全自动，无需人工确认）：

1. 展示大纲/当前批次状态（仅展示，不等待确认）
2. python parallel_tracker.py clear 清空上批次状态
3. 最多5并发启动子Agent（sessions_spawn），自动执行全部批次
4. python parallel_tracker.py wait 后台监控，直至本批全部完成
5. 完成后自动执行 python integrate_report.py convert-batch

子Agent prompt 模板：见 references/phase2_guide.md

每批次完成后通知：

from notify import notify
notify(f"""✅ 第[X]批章节撰写完成！

📖 已完成：[已完成数]/[总章节数] 章
📝 本批完成：[章节列表]

⏳ 下一批：[下一批章节列表]
（自动进入下一批，无需人工确认）""")

📖 已完成：[已完成数]/[总章节数] 章 📝 本批完成： • [章节1标题] • [章节2标题] • [章节3标题]（如有）

⏳ 下一批：[下一批章节列表] （自动进入下一批，无需人工确认）

- 小改动：直接编辑 `F:/agent/chapters/0X-xxx.txt`，保存后重新生成
- 大改动：重新触发子Agent重写，替换原文件

---

## Phase 2.5：跨章一致性审查

```bash
python integrate_report.py check

审查数量指标一致性与术语统一性（对照 glossary.json）

审查完成后通知：

from notify import notify
notify(f"""🔍 一致性审查完成

✅ 术语统一性：正常
✅ 数量指标：一致
✅ 跨章引用：无冲突

📄 即将进入最终整合阶段...

---

Phase 3：整合师汇总

python integrate_report.py

自动完成：解析章节（错误隔离）→ 更新术语表 → 一致性审查 → 生成精美 docx

最终完成后通知：

from notify import notify
notify(f"""🎉🎉🎉 报告撰写完成！🎉🎉🎉

📄 《[报告主题]》
📊 规模：[X]章 / 约[Y]万字
🎨 封面风格：[风格名称]

✅ 精美版报告已生成！
📁 文件位置：F:/agent/chapters/output/

文心，全文已就绪，可进行后续审阅~

---

文档美化功能（自动应用）

生成报告自动包含以下排版效果（通过 plan.json 中 cover_style 字段选择）：

1. 6种封面风格 — 修改 plan.json → cover_style 字段（整数 1～6）
2. 执行摘要 — 深蓝标题条（#1F4E79）背景 + 白字 + 正文缩进
3. 表格式目录 — 深蓝标题条 + 三列条目（序号/章节/页码）
4. 彩色章节标题：
   • H1：整行深藏蓝底色 #1F4E79 + 白字微软雅黑
   • H2：中蓝底色 #2E75B6 + 白字
   • H3：淡蓝背景 #D6E4F0 + 深蓝字 + ▌ 左边条
5. 重点标注盒 — 自动识别【关键】【注意】【优势】【风险】【数据】标签，渲染为彩色卡片（背景/白字/边框）
6. 美化表格 — 表头深藏蓝背景 #1F4E79 + 白字 + 奇偶行交替底色（#DEEAF6 / #FFFFFF）

---

封面样式（6种风格）

封面风格通过 plan.json 中的 cover_style 字段指定（整数，1～6）：

编号	风格名称	特点	推荐场景
1	经典政务风格	深藏蓝顶条 + 金色点缀	政府/国企审批
2	现代简约风格	左侧蓝色重色块 + 右侧信息	科技/商务汇报
3	商务典雅风格	酒红配色 + 居中递进	咨询/投行报告
4	科技数字风格	深海蓝铺满 + 大字白字标题	互联网/数字化
5	中式传统风格	故宫红 + 宣纸米色背景	传统文化/国企
6	全屏沉浸风格	深海蓝铺满 + 大字白字标题	数字化/科技项目

注意：cover_style 值为整数（如 4），代码会自动转换为字符串比较。

---

CLI 命令速查

命令	作用
python integrate_report.py	生成整合报告（全量）
python integrate_report.py convert-batch	批量生成 docx
python integrate_report.py convert-one <in> <out>	单章转 docx
python integrate_report.py check	一致性审查
python integrate_report.py glossary	术语表生成/更新
python integrate_report.py ref show	查看参考资料
python integrate_report.py ref clear	清空参考资料
python integrate_report.py preview [章节前缀]	预览章节摘要
python integrate_report.py feishu-search <query>	搜索飞书知识库
python parallel_tracker.py show	查看撰写进度
python parallel_tracker.py wait	阻塞监控（Ctrl+C停止）
python parallel_tracker.py clear	清空追踪状态

封面风格切换：修改 F:/agent/chapters/plan.json 中的 cover_style 字段（整数 1～6），然后重新生成。 修改代码后需删除 __pycache__ 下的 .pyc 文件 + content_hashes.json 强制重建。

---

状态文件

工作目录默认：~/.config/lobsterai-report-agent/chapters/（可通过 LOBAI_CHAPTERS_DIR 环境变量覆盖）

文件	作用
<CHAPTERS_DIR>/plan.json	章节元数据
<CHAPTERS_DIR>/glossary.json	术语表
<CHAPTERS_DIR>/reference_material.txt	参考资料原文
<CHAPTERS_DIR>/plan_outline_snapshot.md	大纲快照
<CHAPTERS_DIR>/content_hashes.json	增量缓存（删后强制重建）
<CHAPTERS_DIR>/writing_tracker.json	并行进度追踪
<CHAPTERS_DIR>/config.json	项目配置（封面风格、通知渠道等）

---

Critical Rules

Markdown 表格格式（子Agent必须遵守）

详见 references/table_format_guide.md

核心要点：

• 分隔行必须是 |---|---|---|（首尾 | 不可省略）
• 各行列数必须与表头一致
• 单元格内容避免包含 |（用 ～ 或 - 表示范围）

强制重建（修改代码后必须两步都做）

修改 src/engine.py 或 src/config.py 后，必须同时删除以下两个文件才能让新代码生效：

# 1. 删除 .pyc 缓存（修改代码后必须）
# Linux/macOS
find . -type d -name __pycache__ -exec rm -rf {} +
# Windows
Get-ChildItem . -Recurse -Directory __pycache__ | Remove-Item -Recurse -Force

# 2. 删除增量 hash（否则增量模式跳过重写）
# 默认路径
del "%USERPROFILE%\.config\lobsterai-report-agent\chapters\content_hashes.json"

# 3. 重新生成
python integrate_report.py

已知 Bug 已修复（记录备查）

详见 references/bug_fix_guide.md，包括：

• _flush_table 未调用 _parse_md_table 导致表格逐字拆列（v3 早期版本）
• ensure_mermaid_deps() 在 import 时执行 subprocess（现已改为惰性）
• .pyc 缓存导致修改后的代码不生效
• RGBColor 用索引而非 .red/.green/.blue 属性
• add_cover() 设置 section.margin=0 导致正文无边距

---

References

文件	内容
references/phase0_guide.md	Phase 0 需求确认完整流程与话术
references/phase1_guide.md	规划师完整 prompt 模板与 plan.json 格式
references/phase2_guide.md	子Agent完整 prompt 模板（含表格格式警告）
references/table_format_guide.md	Markdown表格格式规范、常见错误与示例
references/bug_fix_guide.md	Bug排查与强制重建操作步骤