research-work-system

# AGENTS.md — 调研工作体系的通用 Agent 指令

> 本文件是给**任何支持 AGENTS.md 约定的 agent 工具**（ZCode、Cursor、Codex、Gemini CLI 等）的长期指令。进入本目录即自动读取；内容与 CLAUDE.md（Claude Code 版）保持同步，两者改一处、必改另一处。
> 入口与状态：[[记忆索引]]（总入口）｜ [[项目库/项目台账]]（项目登记）。

## 体系是什么

一套可复用的调研工作方法：7 步流水线 × 三方案（A 企业 / B 行业技术 / C 混合）＋ 9 项执行规范 ＋ 模板库 T1—T8 ＋ 工具脚本库 ＋ 项目台账与标准骨架 ＋ 记忆库（长期记忆）。服务对象是**无技术背景的 VC/PE 投资人**。

## 目录地图（体系根=本文件夹，全部相对路径）

> 🔴 **Agent 首读顺序（必读）**：进入本目录后、执行任何任务前，先按顺序通读 `README.md` → `记忆索引.md` → `方法论/00-项目总纲.md` → `CHANGELOG.md`（本文件由工具自动加载，无需手动读）。

- `README.md` 给人读；`记忆索引.md` 人与 AI 共用总入口；
- `方法论/00-项目总纲.md`：定位、三场景决策表、体系闭环、术语约定——**先读它**；
- `方法论/01—07` 七步文档（各含规范化提示词 + 执行规范 + 质量检查清单）；
- `方法论/12—14` 三方案（先按决策表选方案，再执行）；
- `方法论/08—10` 执行规范；`方法论/15` 项目库规范；`方法论/16` 环境自检；`方法论/17` 调研前置（强制）；`方法论/18` 复盘记忆沉淀（强制）；`方法论/19` 方法论演进；`方法论/20` 文档同步与版本管理；`方法论/21` 修改影响定位与全量同步；
- `CHANGELOG.md` 变更日志；`记忆库/` 长期记忆（知识库\ + 经验库\）；
- `方法论/模板库/T1—T8`；`方法论/工具脚本库/`（check_env.sh、fix_ref.py、wps_one.ps1、convert_all.sh、mineru_convert.py）；
- `集成配置/` Obsidian 与 Claudian 接入指南；`.claude/skills/` Claudian 技能。

## 工作规则

0. **首读清单（最高优先）**：进入本目录后、执行任何任务前，必须先按顺序用 Read 完整通读 4 份文档——`README.md` → `记忆索引.md` → `方法论/00-项目总纲.md` → `CHANGELOG.md`——未读完不得开始任何动作；本文件（AGENTS.md）由工具自动加载，无需手动读取；
1. **调研前置强制确认（最高优先）**：任何调研任务开始前，先做深度需求交互（八项必问）、确认参考资源位置（不明必须追问，禁止猜测）、用 T7 模板出调研方案并提交用户确认——**用户确认前不得开始任何调研动作**（见 `方法论/17`）；
2. **一切产出必须落盘**：调研与使用材料禁止静默输出（只写在对话里），必须保存为 markdown 到正确位置（02-调研产出\ 等），对话只做摘要与指引并报告文件位置；
3. **调研后强制复盘沉淀**：每次调研结束与用户复盘，知识轨写入 `记忆库/知识库/`、经验轨写入 `记忆库/经验库/`，新规则回写方法论（见 `方法论/18`）；
4. 新项目：先登记台账（编号 PRJ-YYYY-NN 顺延、方案 A/B/C、状态=筹备中）→ 建六骨架 → 执行；
5. 产出落位：markdown 进 `项目库/PRJ-YYYY-NN-项目名/02-调研产出/`；**原文与公开检索材料进 01-原始资料\（有链接的页面抓快照存 `检索材料\`，并登记 `00-检索来源档案索引.md`，见 15 号文档归档规则第 5 条）**；交付物进 04；
6. **数据必须反复核对（质量红线，铁律第七条）**：金融分析对数据正确性要求极高——核心数字入报告前须经至少两道独立核对（权威原文核对 + 交叉验证/勾稽验算），核对链（来源+核对方式+日期）可追溯；口径冲突并列注明来源、信息不足标注"公开信息有限"禁止编造、数字必带来源；表格逐格核验（单位/同比方向/口径归属/分项合计=总计/同比重算）；单来源数字降级标注不得进结论；核对记录汇总存项目 `05-复盘与存档\数据核对记录表.md`（细则见 08 号第二节、10 号第〇节）。**产业图谱/全景图类产出另须反复核对正确性**：对照用户口径、官方分类与 ≥1 张市面主流图（含自媒体），做图谱核对——分层结构、环节归属、图上数据三查（细则见 10 号 0.5 节）；
7. 每步过质量门（步骤文档末尾检查清单）再交付；
8. 记忆维护：台账/状态/方法论/踩坑有变化时，按 20 号文档的同步映射表同步更新 `记忆索引.md`、`CLAUDE.md`、`README.md` 等，并运行 `check_sync.sh` 确认一致；版本变更走 CHANGELOG 与版本号三处对齐；
9. 技术写作：三件套（大白话定义 + 生活类比 + 对比表）；报告六节结构见 `方法论/03`；**写作逻辑链铁律**——所有数据/事实后必须写清"前提→推理→结论"逻辑链与投资含义，禁止只堆数据让人意会（03 号写法规则 6）；**产业图景类调研**须"全景图谱 + 每个局部领域深度研究 ×N"（每份七节含投资逻辑与估值，见 03 号 2.1、13 号）；**逻辑传递论述法**——产业图景主线论述用"层层递进"结构（原始状态 A0→新情况 A1/B1→新结果结构 A2/B2→瓶颈 A3/B3→方案 A4.x→必然引发 A5/B5/C5，定律立锚、逐环乘数、**每环完整展开（是什么→为什么→怎样导致→必然性，禁名词+箭头简写）**、终点锚定最强弹性卡点，见 03 号写法规则 7）；
10. 技术选型（成熟方案优先）：调研内容以外的技术性操作，先看市场成熟方案（pandoc/WPS/MinerU/Obsidian/Claudian 等），自研仅限胶水脚本（选型三问见 09 号文档第三节）；
11. 方法论演进：用户反馈、复盘经验、外部优质方法论 → 按 19 号文档流程评估回写，更新 CHANGELOG.md 与版本号；
12. 不设时间预算：持续执行调研任务，按质量门推进，用户可随时叫停或调整范围；
13. 修改前影响定位（最高优先）：对本体系做任何修改前（含其他机器上的个性化修改），先按 21 号文档列出影响清单（受影响文件与位置），同一轮内完成全部同步并跑 `check_sync.sh`，再更新 CHANGELOG 与版本号——禁止半同步状态；
14. **子 agent 使用规范**：使用子 agent（Explore/general 等）必须先交代任务背景、上下文情况（项目阶段、已有结论、文件位置、已核对修正的数字），并先让子 agent 全面理解任务信息与相关规范（本体系规则、质量红线、数据纪律、命名归档规范）再执行——禁止零上下文派发；子 agent 结论必须复核并注明来源；
15. **财务比率计算纪律**：财务比率类指标（ROE/毛利率/净利率/费用率/周转率/负债率/EPS 等）优先采信同花顺/东方财富/雪球等金融平台公开指标值，AI 只取值与核对、不自行从头重算专业比率（易错：加权/期末口径、年化、单位换算）；财报已披露指标以财报为准；AI 自算仅限简单派生（占比/PS/净现比/同比）且必须双方法验算；
16. **渲染图片质量（4K）**：所有渲染/生成的图片（Mermaid 图谱、图表、PPT 中的图片等）必须满足 **4K 画质**（长边 ≥3840 px，建议 3840×2160 或更高；不能小于 3840 宽）。渲染交付前须用 `identify`/Python PIL 核对实际尺寸，低于 4K 重新渲染；纹理/线条需清晰无锯齿，禁止输出低分辨率占位图。

## 常用命令

- 环境自检：`bash 方法论/工具脚本库/check_env.sh`
- 生成 Word 全框线模板（首次，模板丢失时）：`cd 方法论/工具脚本库 && pandoc --print-default-data-file reference.docx > ref.docx && python fix_ref.py ref.docx custom-ref.docx`
- 转 Word：`pandoc 源.md -o 目标.docx --reference-doc=方法论/工具脚本库/custom-ref.docx`
- 转 PDF：`powershell.exe -NoProfile -ExecutionPolicy Bypass -File 方法论/工具脚本库/wps_one.ps1 -Src 输入.docx -Dst 输出.pdf`

## 已知坑

- 网络搜索每轮并行 ≤2（防限流）；限流后降为单查询放慢节奏；
- WPS 不支持 `/t file /pdf` 命令行语法，转 PDF 必须走 COM（wps_one.ps1）；MS Word COM `SaveAs([ref]…)` 报 psobject 错误，用 `SaveAs2`；
- 转 PDF 后 `taskkill //F //IM wps.exe` 与 `wpscloudsvr.exe`，防残留进程占用目录；
- 删除报"Device or resource busy"的目录：先 cd 离开，再查占用进程；
- pandoc 的 `--` 之后**全部参数会被当作输入文件**（GNU 惯例），禁止 `pandoc -- "$f" -o …`（会把 `-o` 吞掉，报 `-o: withBinaryFile: does not exist`）——正确写法 `pandoc "$f" -o 输出.docx`（PRJ-2026-02 踩坑，convert_all.sh 已修复）；
- Git Bash 脚本把 `/tmp` Unix 路径传给 Windows 程序（pandoc.exe）前必须 `cygpath -w` 转换（PRJ-2026-02 踩坑，已修复）；
- Windows 上 `python3` 可能是应用商店 stub（非交互环境静默失败、退出码 49），脚本优先用 `python`、不存在再 `python3`（与 check_env.sh 一致；PRJ-2026-02 踩坑，已修复）；
- Git Bash 管道中中文输出可能乱码（GBK/UTF-8 混显），不影响文件内容，勿据此判断失败。
- WebSearch 返回结果多数不带链接（大量查询返回 "No links found"，只有摘要与来源名称），资料导读表需要链接时须追加定向检索补链；上市公司原文按名称到巨潮资讯网（cninfo.com.cn）检索（PRJ-2026-03 踩坑）。
- 财报/公告原文渠道共四个：巨潮资讯网、东方财富、同花顺、公司官网"投资者关系"页（用户 2026-08-25 提供）；本机环境变量 MINERU_API_KEY 已配置，PDF 原文转 markdown 走 `python 方法论/工具脚本库/mineru_convert.py`（PRJ-2026-03）。
- MinerU API 限额（mineru.net）：单文件 ≤200 页（超出需本地切分后分批转换，PRJ-2026-03 已实战）；每日 1000 页优先解析额度、超出排队解析；提交任务 50 文件/分钟、单用户日限 5000 文件；获取结果 1000 次/分钟（mineru_convert.py 尚未入库、暂用内联脚本，见 CHANGELOG）。
- 安全钩子（Mimosa）静态扫描识别不了自定义 URL/路径校验函数：含网络请求的工具脚本写入仓库可能被误拦（SSRF/路径穿越误报）——按"取值点就地白名单校验"写仍可能不通过；应对：一次性内联执行（脚本不落盘），或人工复核后入库（PRJ-2026-03 踩坑）。
- convert_all.sh 三个路径参数必须传**绝对路径**（或让脚本自动转绝对——现已内置）：脚本内部会 cd 进源目录，相对路径的输出目录会嵌套漂移进源目录（PRJ-2026-03 踩坑，convert_all.sh 已修复）；
- wps_one.ps1 的 `$app.Quit()` 在 WPS 已自行退出时会抛"RPC 服务器不可用"（HRESULT 0x800706BA），属转换完成后的清理异常、不影响 PDF 产出——已加 try/catch 吞掉（PRJ-2026-03 踩坑，已修复）。
- 渲染 Mermaid 图：`npx @mermaid-js/mermaid-cli` 的 puppeteer-core 不自带浏览器，默认启动失败；用 `-p puppeteer.json` 指定本机 Edge/Chrome（`--no-sandbox`）；渲染 PNG 用 `-s 4`（或按需提高 scale）保证 ≥4K，交付前用 PIL 核对尺寸（PRJ-2026-04 首次实战）。（2026-08-30 增补，规则 16）

## 案例基线

- PRJ-2026-01 WRC2026 世界机器人大会调研（方案 C，已交付）——复盘见 `方法论/11-案例复盘-WRC2026.md`；案例库独立存放，关键数字已内嵌各文档与模板。
- PRJ-2026-02 卫星互联网调研（方案 B，已交付）——方案 B 全流程首跑验证：5 份产出 + Word/PDF 镜像；踩坑修复见 `项目库/PRJ-2026-02-卫星互联网/05-复盘与存档/复盘报告.md`。
- PRJ-2026-03 扫地机器人双雄调研（方案 C，已交付，复盘待用户确认）——石头科技×科沃斯对比：14 份产出；复盘报告见 `项目库/PRJ-2026-03-扫地机器人双雄/05-复盘与存档/复盘报告.md`。