@huicai/cli 2026.804.0 → 2026.1019.0

package/skills/report-craft/references/feasibility.md

@@ -0,0 +1,118 @@
+# 可研报告逐章要点
+
+**默认用本单位归档体例**（科技计划项目十一节，下面逐章写）：`create_doc` 带 `template:"可行性研究报告"` 时
+就按这十一节审章节，换别的骨架会收到一串「缺必备章节」再返工。只有用户明确要**投资建设类**可研（基建、
+设备采购）时才用通用体例，对应关系见文末。体例不同，**内容硬指标相同**：比选、测算、进度、风险一样都不能少。
+章节标题照抄下面十一节的原文（可加「一、」「二、」编号），别改写成同义词。
+
+每章按「评审在看什么 → 必须有 → 配什么图表 → 常见翻车」写。
+
+---
+
+## 一、立项的背景与意义
+
+- **评审在看**：为什么非做不可。不是技术多先进，是不做会怎样。
+- **必须有**：政策依据（文件全称 + 文号 + 原文关键句，不同义改写）；行业现状用数字说（带来源）；
+  本单位的具体痛点并量化（耗时、成本、差错率、投诉量）；不做的后果；意义分经济 / 技术 / 社会，每层落到具体对象。
+- **图表**：痛点与对策对照（render_diagram `compare`）；有可靠来源时画行业规模趋势（render_chart `line`/`bar`，`note` 写来源）。
+- **翻车**：堆政策口号；以「随着……的快速发展」开头；整章没有一个数字。
+
+## 二、国内外研究现状与发展趋势
+
+- **评审在看**：你懂不懂这个领域、差距在哪、本项目站在什么位置。
+- **必须有**：国外、国内各 2~3 个代表（产品 / 开源项目 / 论文）；按**同一组维度**对比（能力、架构、开放性、
+  成本、国产化适配）；趋势 2~3 条且有依据；本项目的定位与差异点。
+- **图表**：同类方案对比表（表题如「同类方案核心能力对比」）；可选技术演进时间线（render_diagram `timeline`）。
+- **翻车**：维度挑着对自己有利的比；把竞品写成「功能单一」而说不出单一在哪；没有引用来源。
+
+## 三、项目实施主要内容、技术关键与创新点、预期目标
+
+- **必须有**：建设内容按模块逐项写，与功能模块图一一对应；关键技术每项写「难点 — 方案 — 成熟度
+  （自研 / 引进 / 已验证）」；创新点写与现有技术的**区别**（可对应已申请的专利）；预期目标量化：
+  技术指标表（指标 / 现状值 / 目标值 / 测试方法与环境）+ 成果形式（软件著作权、专利、标准的数量）。
+- **图表**：总体架构图（`layered`）、功能模块图（`tree`，用 project_facts 给的模块树，按报告口径改名）、
+  关键技术原理图（`flow` / `sequence`）。
+- **翻车**：创新点写成功能清单；目标写「达到国内领先水平」却没有一个可测指标。
+
+## 四、现有工作基础、条件和优势
+
+- 代码库里已有东西的项目，**这一节最有说服力**：project_facts 的数字放在这里——已建成的模块与服务、
+  接口数、测试用例数、代码规模、提交历史的起止时间、已有文档。有试点用户与运行数据才写，没有不编。
+- **必须有**：团队规模与结构（不编人名）、已有知识产权、软硬件与算力条件、合作单位。
+- **图表**：现有基础一览表（事实 / 数值 / 来源）；可选已建成系统的截图。
+- **时态**：这一节写「已完成」，进度安排写「将要做」。同一件事不能两边都出现。
+
+## 五、项目实施方案、组织方式与课题分解
+
+- **必须有**：技术路线（分阶段）；**方案比选**（2~3 个可比方案，维度：技术成熟度 / 投资 / 工期 / 风险 /
+  可扩展性 / 国产化，给评分或结论与理由）；部署方案；组织方式（决策 / 技术 / 质量 / 实施各由谁负责）；
+  课题分解（子课题 — 负责单位 — 交付物 — 考核指标）。
+- **图表**：技术路线图（`flow`）、部署架构图（`layered`）、组织结构图（`tree`）、课题分解（`tree` 或表）、方案比选表。
+- **翻车**：只写选定方案没有比选（「论证」变「介绍」）；课题分解与第三章建设内容对不上。
+
+## 六、进度安排与年度计划内容
+
+- **必须有**：阶段（需求 / 设计 / 开发 / 测试 / 试点 / 验收）的起止与交付物；里程碑与判定标准；
+  关键路径与依赖；年度计划（每年做什么、花多少、考核什么）。
+- **图表**：实施进度甘特图（render_chart `gantt`，`today` 填编制日期，里程碑用 `milestones`）；里程碑表。
+- **红线**：所有计划节点在编制日期之后；与经费的分年度计划、人员投入月数对得上。
+
+## 七、承担单位和主要研究人员简况
+
+- **必须有**：单位简介（性质、规模、资质、相关业绩）；人员表（姓名 / 职称 / 专业 / 项目分工 / 投入月数）。
+- **不编造**：拿不到的写「［待补：项目负责人姓名、职称］」，交付时列进待补清单。
+
+## 八、经费预算来源、使用计划及还款能力分析
+
+- **必须有**：投资估算表（科目 / 金额 / 占比 / 测算依据 = 单价 × 数量）；分年度使用计划；
+  资金来源（自筹 / 财政 / 贷款，比例合计 100%）；还款能力（没有贷款就写「不涉及」，不要空着）。
+- **工具**：fin_model 的投资估算表；投资构成图（`pie` 或 `waterfall`）。
+- **翻车**：测算依据空着；各处总投资不一致；人工费与人员投入对不上（人数 × 月数 × 月均人工成本应当约等于人工费）。
+
+## 九、应用或产业化前景与市场需求分析
+
+- **必须有**：目标客户与场景；市场规模（给口径与来源）；竞争格局；推广计划（分年度客户数、收入）；商业模式与定价。
+- **图表**：推广计划或市场规模图（`bar` / `line`，注明来源）。
+- **红线**：推广计划里的客户数和单价，就是 fin_model 收入假设里的 `volume` 和 `price`——两处必须是同一组数。
+
+## 十、经济、社会效益分析
+
+- **必须有**：测算口径说明（fin_model 的 notes 原样用）；项目投资现金流量表；财务评价指标表（NPV / IRR /
+  静态与动态回收期 / 总投资收益率）；情景分析；敏感性分析（表 + 龙卷风图 + 临界点）；
+  结论句（fin_model 的 conclusion）；社会效益量化（受益对象、规模、可观测指标）。
+- **图表**：累计现金流量图（`line`，零线交点即回收期）、敏感性龙卷风图（`tornado`）。
+- **翻车**：只有「经济效益显著」；回收期心算（没扣成本）；节约额大于被节约的支出；悲观情景转负却写「完全可行」。
+
+## 十一、项目的风险分析与对策
+
+- **必须有**：技术、市场、进度、资金、人员、合规（数据安全、等保）六类；每条写描述、可能性（1~5）、
+  影响（1~5）、等级、应对措施、责任人、触发条件或预警信号。
+- **图表**：风险矩阵（render_chart `matrix`）+ 风险登记表。敏感性分析里的最敏感因素，要在这里有对应的风险条目。
+- **翻车**：写成套话；没有责任人；「风险总体可控」却没有依据。
+
+---
+
+## 通用投资类可研体例（对照）
+
+| 通用体例章节 | 对应上面哪几章的内容 |
+|---|---|
+| 总论（概况、依据、主要结论） | 一 + 各章结论汇总（总论要能脱离正文独立成立） |
+| 需求分析与建设规模 | 一、九 |
+| 技术方案（三方案比选） | 三、五 |
+| 建设条件 | 四 |
+| 节能环保与安全 | 十一（合规）+ 等保定级、数据合规、能耗 |
+| 组织机构与人力资源 | 五、七 |
+| 实施进度计划 | 六 |
+| 投资估算与资金筹措 | 八 |
+| 财务与效益评价 | 十 |
+| 风险分析与对策 | 十一 |
+| 研究结论与建议 | 明确「可行 / 有条件可行 / 不可行」，有条件的写清条件 |
+
+## 已有代码库的项目：时态怎么分
+
+项目往往是「边做边补可研」。这时最容易把已完成的开发写成计划。处理办法：
+
+1. 用 project_facts 与提交历史确定**已完成**的范围，写进「现有工作基础」（第四章）；
+2. 可研论证的是**后续投入**：还要建什么（新模块、商业化、推广、运维体系、合规认证），
+   投资估算只算后续投入（已发生的投入作为「前期投入」单列说明，不混进后续预算）；
+3. 进度计划从编制日期之后排；甘特图的 `today` 设为编制日期，图上一眼看出「从现在起」。

package/skills/report-craft/references/review-checklist.md

@@ -0,0 +1,51 @@
+# 交付前自审清单
+
+先机检，后人检。机检是 `docx_inspect`：必修必须清零；建议逐条过，保留的要能说出理由。
+人检是下面这张表——机器查不出「论证站不站得住」，只能自己像评审一样读一遍。
+
+## 一、机检（docx_inspect 会报的）
+
+- 必修：进度计划整体早于编制时间、题注断号、引用了不存在的图表、表格或图片超版心、错别字……
+- 建议：同一对象数量前后不一致（「七个维度 / 五个维度」）、可研缺评审常看的图表、财务评价缺 NPV / IRR / 敏感性、
+  术语多种写法、AI 味套话……
+- 提示：文中的「［待补：……］」清单——交付说明里要逐条列出。
+
+create_doc 返回的警告同样要看：「引用了不存在的图表标签」「插图不存在」「缺少模板必备章节」。
+
+## 二、人检（像评审一样读）
+
+**结论与论证**
+1. 总结论（可行 / 有条件可行 / 不可行）写在哪？条件写清了吗？与悲观情景的测算一致吗？
+2. 「为什么非做不可」有没有数据？政策依据写了文件全称和文号吗？
+3. 方案比选有没有至少两个真能比的方案？选择理由是比选表里的维度推出来的吗？
+
+**数字**
+4. 总投资、工期、人数、模块数在全文每一处都一样吗？（`grep` 一遍）
+5. 财务数字是不是全部来自 fin_model 的同一次结果？改过假设之后正文、表、图都重新同步了吗？
+6. 人工费 ≈ 人数 × 月数 × 月均人工成本吗？分年度投资加起来等于总投资吗？
+7. 推广计划的客户数、单价与收入假设一致吗？
+
+**时态与事实**
+8. 已完成的写在「现有工作基础」，计划的都在编制日期之后吗？
+9. 每个规模数字都能指出来源吗（代码库统计 / 文档 / 调研 / 测算）？
+10. 有没有编造的人名、客户、合同、市场数据？拿不到的是否都标了「待补」？
+
+**图表**
+11. 每张图、每张表都被正文引用了吗？引用处说出了它证明什么吗？
+12. 图里的名称与正文、表里一致吗（模块名、阶段名、风险编号）？
+13. 结构图里「已建成」和「本期新建」分开了吗？
+13a. 结构图插进 A4 后最小的字 ≥5.5 磅吗（create_doc 会报「打印看不清」）？图里没有和题注重复的标题块吗（header:false）？
+
+**风险**
+14. 敏感性分析里最敏感的因素，在风险表里有对应条目和应对措施吗？
+15. 每条风险有责任人和触发条件吗？
+
+## 三、交付说明模板
+
+```
+已完成《……可行性研究报告》：docs/……docx（约 N 页）。
+- 图表：结构图 N 张（总体架构、功能模块、部署、业务流程……）、数据图 N 张（进度甘特、累计现金流、敏感性、风险矩阵）、表 N 张。
+- 测算：总投资 …… 万元，所得税后 NPV …… 万元，IRR ……%，静态回收期 …… 年；最敏感因素：……（临界点 ……%）。
+- 待补（需要您提供）：项目负责人与团队成员信息、单位资质、……。
+- 体检：必修 0 项；建议 N 项，其中「……」有意保留，原因是……。
+```

package/skills/report-craft/references/visuals.md

@@ -0,0 +1,114 @@
+# 报告配图：现成写法
+
+两条通用约定：
+
+- **插进文档的结构图加 `"header": false`**：图名交给文档题注（图 3-1 …），图里不再画一遍标题块。
+  `title` 照写，它用来命名文件和 SVG 的 `<title>`。
+- **路径**：结构图 `docs/figures/<名>.svg`（引擎同时出 PNG），数据图 `docs/charts/<名>.png`。
+  Markdown 里引 PNG：`![系统总体架构](docs/figures/总体架构.png){#fig:arch}`，正文写「如@fig:arch 所示」。
+
+- **为纸面画图**：A4 纵向版心 14.66cm 只相当于屏幕上 550px 宽。一层并排 8 个节点、每个都带说明和标签的架构图，
+  缩进版心后字只剩 2~3 磅，打印出来一片蚂蚁。`render_diagram` 会报「插进 A4 后最小的字约 X 磅」，低于 5.5 磅就要改：
+  每层压到 4~5 个节点（同类合并，明细放正文或第二张图）、tags 只留一两个；功能树分支超过 5 个用 `"direction":"LR"`；
+  实在要整张放就横排插入：`![图题](图){#fig:arch .landscape}`（单独一个横向页，版心 23.4cm）。
+
+下面的例子用一个中性的「智能运维平台」演示字段，换成自己项目的内容即可。
+
+## 一、结构图（render_diagram）
+
+### 总体架构（layered）
+
+```json
+{"type":"layered","title":"智能运维平台总体架构","header":false,"flow":"down",
+ "layers":[
+  {"name":"接入层","desc":"多端统一接入与鉴权","nodes":[
+     {"name":"Web 控制台","desc":"Vue 3"},{"name":"桌面客户端","desc":"Electron"},{"name":"开放 API","desc":"REST / SSE"}]},
+  {"name":"业务服务层","desc":"按业务域拆分的微服务","nodes":["告警与工单","用户与权限","计费结算"]},
+  {"name":"能力层","desc":"模型与数据能力","nodes":[{"name":"模型分发网关","emphasis":true},"知识库检索","规则引擎"]},
+  {"name":"数据层","nodes":[{"name":"PostgreSQL","tags":["分库分表"]},"Redis","对象存储"]}]}
+```
+
+这张每层 3 个节点、不带侧栏，纵向插入后最小的字约 6 磅，打印能读。层写职责（`desc`），节点写组件。
+要画「一层 4 个以上节点 + 安全/运维侧栏」的完整总体架构（`"sidebars":[{"name":"安全保障","side":"right","nodes":[…]}]`），
+就**横排插入**（`{#fig:arch .landscape}`），并把同类服务合并到每层 ≤5 个；服务明细另画一张或放进表格。规划中（还没建）的节点加 `"style":"dashed"`，
+并在 `legend` 里说明「虚线为本期新建」——可研里「现状」和「计划」在图上也要分得开。
+
+### 部署架构（layered，按网络区域分层）
+
+```json
+{"type":"layered","title":"部署架构","header":false,
+ "layers":[
+  {"name":"互联网区","nodes":["用户浏览器","客户端"]},
+  {"name":"DMZ 区","nodes":[{"name":"负载均衡","tags":["双机热备"]},{"name":"API 网关","tags":["2 节点"]}]},
+  {"name":"应用区","groups":[{"name":"K8s 集群（3 主 6 工作节点）","nodes":["业务微服务 ×11","模型分发 ×3"]}]},
+  {"name":"数据区","nodes":[{"name":"PostgreSQL","tags":["一主两从"]},{"name":"Redis","tags":["哨兵"]},"对象存储"]}],
+ "notes":["生产与测试环境物理隔离；数据区仅允许应用区访问"]}
+```
+
+### 功能模块（tree）
+
+`project_facts` 返回的模块树 spec 可直接用，但要改成**功能口径**（评审看「系统能干什么」，不看 Maven 模块名）。
+进文档的功能树用 `"direction":"LR"`（自左向右）：四个分支的树从上往下画有 1700px 宽，插进 A4 字只剩 3 磅；
+自左向右只有 500 多 px 宽，字有 10 磅：
+
+```json
+{"type":"tree","title":"系统功能结构","header":false,"direction":"LR",
+ "root":{"name":"智能运维平台","children":[
+   {"name":"监控告警","children":[{"name":"指标采集"},{"name":"告警收敛"},{"name":"根因分析"}]},
+   {"name":"运维工单","children":[{"name":"工单流转"},{"name":"知识推荐"},{"name":"满意度回访"}]},
+   {"name":"智能助手","children":[{"name":"自然语言查询"},{"name":"脚本生成"},{"name":"变更评审"}]},
+   {"name":"平台管理","children":[{"name":"用户权限"},{"name":"计费结算"},{"name":"审计日志"}]}]}}
+```
+
+### 业务流程（flow）与组织结构（tree）
+
+流程图用 `flow`（判断节点 `"shape":"diamond"`，存储 `"cylinder"`，跨角色用 `lanes` 画泳道）；
+组织结构用 `tree`，节点 `desc` 写职责与人数（「技术组 · 6 人 · 架构与核心研发」）。
+
+## 二、数据图（render_chart）
+
+### 实施进度甘特图
+
+```json
+{"type":"gantt","title":"实施进度计划","today":"2026-09-23",
+ "tasks":[
+  {"name":"需求调研与方案设计","start":"2026-10","end":"2026-11","group":"第一阶段"},
+  {"name":"核心模块开发","start":"2026-12","end":"2027-04","group":"第二阶段"},
+  {"name":"集成测试与安全测评","start":"2027-04","end":"2027-06","group":"第二阶段"},
+  {"name":"试点运行","start":"2027-06","end":"2027-08","group":"第三阶段"},
+  {"name":"推广与验收","start":"2027-08","end":"2027-09","group":"第三阶段"}],
+ "milestones":[{"name":"方案评审","date":"2026-11-30"},{"name":"试点上线","date":"2027-06-30"},
+               {"name":"项目验收","date":"2027-09-30"}]}
+```
+
+`today` 填编制日期：图上的竖线让读者一眼看出计划从现在起。计划整体在竖线左边，就是时态写错了。
+
+### 风险矩阵
+
+```json
+{"type":"matrix","title":"风险矩阵","items":[
+  {"id":"R1","name":"上游模型接口变更","p":4,"i":3},
+  {"id":"R2","name":"核心人员流失","p":2,"i":4},
+  {"id":"R3","name":"收入不及预期","p":3,"i":5},
+  {"id":"R4","name":"等保测评不通过","p":2,"i":5}]}
+```
+
+编号与风险登记表一致；登记表里写应对措施与责任人，图只负责「哪些最该盯」。
+
+### 财务图（直接用 fin_model 返回的 spec）
+
+`fin_model` 的「可直接出图的 spec」里有：`cumulative_cashflow`（累计现金流量，零线交点即回收期）、
+`sensitivity_tornado`（敏感性）、`investment_composition`（投资构成环形图）、`investment_waterfall`、
+`revenue_vs_cost` / `revenue_by_line`。可研一般取前三张。拿到后原样交给 `render_chart`，
+**不要改里面的数**——改假设就重跑 fin_model。
+
+### 其他常用
+
+- 对比几个量：`bar`（类别名长或超过 8 个用 `hbar`）；只想强调其中一个系列：`"highlight":"本项目"`，其余自动退为灰色；
+- 构成：`pie`（≤6 块）或 `stacked`（多个整体的构成）；
+- 趋势：`line`；两个量纲不同的量**不要**画进一张图（引擎会拒绝双纵轴），拆成两张或换算成指数。
+
+## 三、配多少图
+
+可研报告 15~30 页，结构图 5~7 张、数据图 3~5 张、表 10 张以上是常见密度。
+图多不等于好：每张图都要有正文句子引出、说明它证明了什么；说不出来的图就删掉。

package/skills/report-craft/references/writing.md

@@ -0,0 +1,80 @@
+# 写得像行家：报告文字的做法
+
+评审读报告的方式是**跳读**：每节看第一句、看图表、看数字，觉得可疑才往下读。
+所以文字的首要任务是让跳读的人拿到结论，其次才是让细读的人找到依据。
+
+## 一、每节第一句就是结论
+
+✗ 「随着工业互联网的快速发展，智能运维在各行各业得到了广泛应用。企业在运维管理过程中……」
+✓ 「设备运维的主要损失不在故障本身，而在发现晚、定位慢：试点工厂 70% 的停机时间花在找原因上。本项目要缩短的正是这一段。」
+
+第一句写不出来，说明这一节还没想清楚要证明什么——先想清楚再写。
+
+## 二、段落按「主张 — 依据 — 含义」走
+
+> **主张**：告警噪声是一线运维最先遇到的问题。
+> **依据**：据试点单位统计，日均告警 1.8 万条，其中 83% 是重复或衍生告警，值班人员每条平均处理 40 秒。
+> **含义**：统一的告警收敛能把有效告警压到每日 3000 条以内，这是本项目第一项建设内容的依据。
+
+没有依据的主张删掉；没有含义的依据（数字摆出来却不说明什么）也删掉。
+
+## 三、数字比形容词有力，来源比数字有力
+
+| ✗ | ✓ |
+|---|---|
+| 显著提升运维效率 | 平均故障定位时间从 42 分钟降到 7.6 分钟（2026 年 6 月试点 30 天统计） |
+| 具有广阔的市场前景 | 目标客群为年营收 5 亿元以上的制造企业，约 1.2 万家（来源：……）；首年签约目标 30 家 |
+| 系统规模较大、功能完善 | 后端 9 个模块、7 个可独立部署的服务，对外接口约 260 个（据代码库统计） |
+| 经济效益良好 | 所得税后 NPV 355.40 万元（i=8%），IRR 27.12%，静态回收期 4.28 年（含建设期 1 年） |
+
+**来源的写法**：「据 backend/pom.xml」「经 fin_model 测算（口径见 10.1 节）」「据《……》（文号）」
+「据 2026 年 7 月用户调研（有效样本 126 份）」。拿不到来源的数不写，或者明确写成假设：
+「按每家门店年订阅 1.2 万元估算（参照同类产品公开报价）」。
+
+## 四、不编造
+
+人名、职称、单位资质、客户名单、合同额、市场规模、试点数据——**拿不到就留空，不要编**：
+
+```
+项目负责人：［待补：姓名、职称、近三年主持的相关项目］
+```
+
+`docx_inspect` 会把这些待补项列出来，交付时逐条告诉用户。编一个像样的数比留空危险得多：
+评审只要追问一次来源，整份报告的可信度就没了。
+
+## 五、时态要对
+
+| 事情的状态 | 放在哪 | 怎么写 |
+|---|---|---|
+| 已经完成 | 现有工作基础 / 项目进展 | 「已完成……，已上线……，累计……」 |
+| 正在做 | 现有工作基础（注明进度） | 「正在开展……，预计 2026 年 11 月完成」 |
+| 计划做 | 实施内容 / 进度安排 | 「计划于 2027 年 3 月前完成……」 |
+
+判断标准只有一个：**编制日期**。编制日期之前的事不能写进计划。
+
+## 六、术语与格式
+
+- 同一事物全文一个叫法（「智能体」就不要再出现「Agent」「代理」混用）；缩略语首次出现写全称
+  （「大语言模型（LLM）」），并收进附录缩略语表。
+- 金额统一单位（万元，保留两位小数），百分比保留一到两位小数；表内数字右对齐由引擎处理。
+- 层级编号：一、（一）1.（1）；不要在一个层级里混用。
+- 图表都要被正文引用，用交叉引用写：「如@fig:arch 所示」「详见@tbl:invest」，编号由引擎生成。
+
+## 七、不写空话
+
+这些词单独出现时几乎不携带信息，出现一次就要问自己「具体是什么」：
+赋能、助力、打造、全方位、多维度、深度融合、有效提升、显著增强、极大地、进一步、
+为……奠定坚实基础、具有重要意义、开创……新局面。
+
+✗ 「平台将全面赋能企业数字化转型，助力企业实现降本增效。」
+✓ 「平台上线后，试点工厂的设备故障平均定位时间从 42 分钟降到 8 分钟，月度停机损失减少约 30 万元。」
+
+## 八、一段范例（财务评价开头）
+
+> 按基准假设，项目总投资 453.00 万元，所得税后财务净现值 355.40 万元（基准收益率 8%），
+> 财务内部收益率 27.12%，静态投资回收期 4.28 年（含建设期 1 年），财务上可行。
+> 营业收入是最敏感的因素：收入下降 35.6% 时 NPV 降为零；在「悲观」情景（收入 -30%、经营成本 +10%）下
+> NPV 为 -3.84 万元，接近盈亏平衡，因此把「首年签约不少于 20 家」列为项目推进的前置条件（见@tbl:risk 中 R3）。
+> 测算口径与逐年现金流见@tbl:cashflow，敏感性见@fig:tornado。
+
+这段话的每个数字都来自 fin_model 的同一次结果，结论（可行）、条件（签约数）和风险（R3）互相印证。