文章目录
- 一、为什么要用"问句"来测文档
- 二、测量口径
- 三、十个问题，逐一验
- Q1 不接摄像头，屏为什么全黑？板子到底起没起来 —— **D**
- Q2 怎么把画面拉出来看？RTSP 拉不到视频 —— **B**
- Q3 画面很糊，是不是镜头没对上焦 —— **D**
- Q4 怎么换成我自己的检测模型 —— **D（docs 域），真答案在第三棵树**
- Q5 不用那个 UI，怎么直接拿到检测结果 —— **D**
- Q6 板子的 IP 是多少？为什么每次开机都变 —— **D**
- Q7 编译环境怎么搭？ATC 在哪下载 —— **B（拆成 7a / 7b）**
- Q8 能不能接第二个摄像头？双摄怎么搞 —— **B**
- Q9 怎么改推流的分辨率 / 帧率 —— **B**
- Q10 板子上的喇叭能不能响 —— **C**
- 四、汇总：0 个 A 级
- 五、三个结构性发现
- 5.1 FAQ 是唯一按问题组织的位置，但它选错了问题
- 5.2 同一个能力写了四份，放在四个地方，互相不通
- 5.3 文档把本地已有的东西指向了在线仓库
- 六、一个必须说清的方法学陷阱
- 七、如果我是厂商，我会改这五处
- 八、如果我是老师，我这样自救
- 九、复现方法
这是一次"按问句测文档"的实验。我不看目录结构、不按模块翻阅，只准备 10 个学生真正会问的问题，然后去官方资料里找答案，记录：找到没有、藏在第几层、要不要跨目录树、读完之后能不能照做。
结论有点刺眼：10 个问题里，独立可解的是 0 个。
但这不是"文档写得差"——恰恰相反，有几处写得好得可以直接当范文。问题出在组织方式：这套文档是按软件分层组织的，不是按任务组织的。
一、为什么要用"问句"来测文档
官方文档有 83 篇 markdown、约 5.1 GB 的 SDK、28 个 AI skill。打开目录，你会看到get-started/software-guide/api-reference/hardware-guide/tools/FAQ—— 全部按软件分层命名。
这个结构对"我要查ss_mpi_venc_set_chn_attr的参数"是高效的。但学生不会这样问。
学生问的是：
- “屏怎么不亮？”
- “画面好糊，是不是坏了？”
- “怎么换成我自己训练的模型？”
- “板子的 IP 是多少？为什么每次都不一样？”
这些问句里没有一个 API 名字，也没有一个模块名。用自然语言问句去找一套按模块命名的文档，命中率会骗人，解决率才是真相。
所以这次测量分两步：
- 机器部分（可复现）：脚本按三组递进关键词搜索，记录首命中轮次、命中文件、路径深度、机器耗时。脚本在文末给出。
- 人工部分（不可替代）：打开排名最高的页面读完，判断"照这篇做，能不能解决问题"，然后定级。
第 2 步是关键。第 1 步的结果会严重高估——这点后面有数据。
二、测量口径
| 项 | 定义 |
|---|---|
| 搜索域 | DOCS=docs/zh-CN/**（83 篇 md）；CODE=apps/components/vendor/（1460 个文本文件）；SKILL=.agents/（28 个官方 AI skill，319 个文本文件） |
| 关键词轮次 | round1 = 学生最自然的说法（产品功能名）；round2 = 换个说法；round3 = 想到模块名/代码符号 |
| 路径深度 | 命中文件相对所在域根的路径段数（DOCS 根 =docs/zh-CN） |
| 定级 | A= 有专页，照做即通；B= 有片段但需拼接、或需离开 docs 树；C= 只有接口参考，没有任务路径；D= 文档里没有答案 |
资料规模基线：
| 域 | 内容 | 规模 |
|---|---|---|
docs/zh-CN | 官方文档正文 | 83 篇 md（含图约 58 MB） |
.agents/skills | 官方 AI skills（第三棵树） | 28 个 skill，319 个文本文件 |
appscomponentsvendor | 各工程 README 与源码 | 1460 个文本文件 |
三、十个问题，逐一验
Q1 不接摄像头，屏为什么全黑？板子到底起没起来 ——D
- docs 里搜
未接 | 未检测 | 摄像头失败：0 条相关。命中的是 I2C “未接设备”、SD 卡"未检测"、人脸录入失败。 - 唯一沾边的是
get-started/first-project/README.md的「四、验证结果」表，5 项判据（烧写成功 / 串口进~ #//root/hello存在 / 手动执行有输出 / 重启后不自动执行）。它能判"板子活着"，不能解释"屏为什么黑"。
而真实的因果链是：
不接 sensor → hi_fw_media_vi_init 失败 → goto cleanup → 进程退出 → ui_module_init 从未执行 → 屏全黑ui_module_init()在main()里排在倒数第二位，VI 一失败就直接goto cleanup_eventhub。串口只有两行：
[mpp] hi_fw_media_vi_init failed [main] Bye.但学生不一定想到去插那根线。他看到的只有一块黑屏，而黑屏同时意味着：没接摄像头 / 排线没插紧 / sensor 型号不符 / 板子坏了。四种原因，一个现象。
Q2 怎么把画面拉出来看？RTSP 拉不到视频 ——B
software-guide/api-reference/framework/api_liveserver.md写得相当好：默认端口 554、播放地址格式rtsp://:554/livestream/、直连与 IPC 两种模式、事件回调模型，一应俱全。
但没有一句"PC 端用什么命令拉"，也没有"拉到了只有声音没有画面怎么办"。
实测中必须加-rtsp_transport tcp：
ffplay-rtsp_transporttcp-x1280-y720rtsp://192.168.1.142:554/livestream/0不加的话，窗口全黑，状态行长这样：
35.30 A-V: nan fd= 0 aq= 32KB vq= 0KB sq= 0B这一行的信息量其实很大：音频时钟走了 35 秒（音频通）、A-V: nan（视频时钟没建立）、vq=0KB（视频包没到）、aq=32KB（网络与 RTSP 会话正常）。结论是UDP 下 2560×1440 的大包被丢，小包音频能过。
定级 B：地址能查到，故障排除查不到。
Q3 画面很糊，是不是镜头没对上焦 ——D
全 docs 树里对焦 | 调焦 | 焦距只命中1 处：hardware-guide/periph-standards/sensor/sensor-image-test-items.md:21，原文是"完成对焦后查看…画面是否有左右或上下清晰度不一样"。
这是一条测试项，不是"怎么调"。
而实测事实是：
- 模组是定焦 + 可螺纹手动调焦，出厂焦点不对着你的使用距离；
- 官方建议检测距离约1 米，景深只有几十厘米；
- 镜头外面还有一层保护膜，没撕的话怎么调都糊。
这三条，文档里一处都没有。学生的结论必然是"镜头是坏的"——而实际上转两圈镜头就好了。
Q4 怎么换成我自己的检测模型 ——D（docs 域），真答案在第三棵树
先看关键词：ATC | 模型转换 | 模型量化 | svp_acl在 docs 里 14 处命中，过滤掉SVAC3之后剩 0 处。
为什么？因为 14 处全是HI_MAPI_VENC_SVAC3_NALU_..._PATCH里的 “Audio/Transport/Channel” 之类的撞词。这是本次测量最大的坑：关键词命中数会骗人。
api_aidetect.md只有接口签名（*_create/*_process/*_listen），没有一句"模型从哪来、怎么转换、放哪、有没有容量限制"。
真答案在一个你想不到的地方：.agents/skills/hi-aiot-cv610-ai-algorithm-apply/。它的SKILL.md里写着 aidetect 的完整流程、错误码0xa05f8007、MMZ leak处置、ss_mpi_aidetect_process的常见报错。
这是给人看的文档，但它只服务于 AI 编码助手。docs 里没有任何一处指向它。
Q5 不用那个 UI，怎么直接拿到检测结果 ——D
这个问题对应fw_cli。数据很干脆：
| 位置 | 出现次数 |
|---|---|
docs/zh-CN（83 篇） | 0 |
.agents/skills（28 个） | 0 |
apps/cv610_ev_board/references/factory_demo/ws73_lcd/ | 唯一出现处 |
相对apps深度5 层，而且目录名叫ws73_lcd（Wi-Fi + 屏的出厂 demo），与"命令行工具"没有任何语义关联。
也就是说：实测中最适合教学的 NPU 入口，文档零提及。这是全篇最刺眼的一条，第 6 节会给改法。
Q6 板子的 IP 是多少？为什么每次开机都变 ——D
4 处命中全部错位：
scenario-1/3：讲的是"把Windows 有线网卡设成静态 IP"（WSL 镜像网络），不是板子；scenario-4：setenv ethaddr 12:34:56:78:9A:BC，u-boot 里临时设 MAC，不是板子固件行为；openharmony-support.md:141：ifconfig eth0 192.168.1.16，OpenHarmony 侧的临时配置。
没有"怎么查板子 IP"、没有"MAC 为什么每次变"、没有静态绑定方案。
而实测确认：
/sys/class/net/eth0/addr_assign_type = 1 # NET_ADDR_RANDOM，内核自己标了"这是随机地址"同一块板四次启动，IP 依次是.138 → .141 → .142 → .143，严格递增、旧租约不回收。内核已经把答案写在一个文件里了，只是没人告诉用户去看这个文件。
Q7 编译环境怎么搭？ATC 在哪下载 ——B（拆成 7a / 7b）
7a 环境搭建：A。
software-guide/environment-setup/四个场景（WSL / Ubuntu Server / WSL+Docker / Ubuntu+Docker），每个都带独立的「常见问题」锚点；FAQ/compilation另有 3 条实打实的报错处置（交叉编译器不在 PATH、AI 非交互 SSH 下 PATH 不加载、切案例前要distclean）。这是整套文档里最完整的一块，照着做能成。它也是 11 个子项里唯一拿到 A 的。
7b ATC：D。0 命中。工具包既无下载入口也无章节，环境搭建章节到"能编应用"就结束了。
Q8 能不能接第二个摄像头？双摄怎么搞 ——B
硬件层写得很清楚：板级文档明确"场景二 / 场景三均支持双摄像头"，并用一张表列出了两种场景下板载开关的对应状态。这一点做得好，接口复用与场景的对应关系一目了然。
断点在操作层：samples/cv610_dev_board/README.md里 sensor 那一行给了一个[双摄像头](https://gitcode.com/HiSpark/...)在线链接——而对应的 README 其实就在本地apps/cv610_ev_board/samples/sensor/dual/。
Q9 怎么改推流的分辨率 / 帧率 ——B
docs 里没有操作页，只有api_vpss.md/api_venc.md的接口参考。
答案在本地工程 README：apps/cv610_ev_board/samples/sensor/single/README.md有 Sensor / 分辨率 / fps / MIPI Lane / RAW 的对照表，并指出改分辨率走sample_single_sensor.h的编译宏。
顺带得到一个重要结论：改分辨率要重编译（应用级全量 11.5 秒），这直接是"二次开发门槛"的数据。
Q10 板子上的喇叭能不能响 ——C
7 篇提到"喇叭 / 扬声器 / 放音"，全部是硬件描述（板子上有什么）或api_ao.md接口参考。
没有一条验证路径。
而实测背景更有意思：/proc/umap/ao只有表头没有数据行，说明 AO 设备从未被 enable；fw_cli也没有音频命令。但/root/.ash_history开头 13 条是产线测试命令，里面明明有：
OTT audio_play_start inner OTT audio_play_start external厂商验证过放音，但OTT这个工具不在镜像里。用户无法复现厂商的验证。这一条对课堂尤其要命——老师需要一个"30 秒确认硬件是好的"手段。
四、汇总：0 个 A 级
| # | 问题 | 定级 | 答案实际位置 | 深度 |
|---|---|---|---|---|
| Q1 | 不接摄像头屏全黑 | D | — | — |
| Q2 | RTSP 拉不到视频 | B | software-guide/api-reference/framework/api_liveserver.md | L4 |
| Q3 | 画面糊 / 对焦 | D | —（仅 1 处测试项） | — |
| Q4 | 换成自己的模型 | D | .agents/skills/hi-aiot-cv610-ai-algorithm-apply/ | 域外 |
| Q5 | 不用 UI 拿检测结果 | D | apps/.../references/factory_demo/ws73_lcd/ | 5 层 |
| Q6 | 板子 IP / 每次变 | D | — | — |
| Q7a | 编译环境 | A | software-guide/environment-setup/×4 | L3 |
| Q7b | ATC 在哪下 | D | — | — |
| Q8 | 双摄怎么搞 | B | 板级文档（硬件）+ 本地samples/sensor/dual | L4 / 域外 |
| Q9 | 改分辨率 / 帧率 | B | apps/.../samples/sensor/single/README.md | 域外 |
| Q10 | 喇叭能不能响 | C | api_ao.md（仅接口） | L5 |
| 口径 | 数值 |
|---|---|
| 独立可解（A） | 0 / 10 |
| 需拼接或跨目录树（B） | 4 / 10 |
| 仅有接口参考（C） | 1 / 10 |
| 文档中无答案（D） | 5 / 10 |
五、三个结构性发现
5.1 FAQ 是唯一按问题组织的位置，但它选错了问题
FAQ/合计 7 条：
| 位置 | 条目 |
|---|---|
FAQ/compilation | 交叉编译器未找到 · AI 执行时找不到编译命令 · 切换案例编译不干净 |
FAQ/develop | 产出文件系统镜像 · 应用开机自启 · 文件传输 · 增量编译烧写 |
FAQ/environment | 无独立条目，跳转到 4 个 scenario 的「常见问题」锚点 |
7 条 100% 落在"编译 / 烧录 / 环境 / 文件传输"域，对上面 10 问的覆盖是 0/10。
不是写得不好，是选错了问题：这 7 条全是"程序跑不起来"的问题，而学生卡住的地方是"跑起来了，但看不到、看不懂、改不动"。
5.2 同一个能力写了四份，放在四个地方，互相不通
以 NPU 检测为例：
| 版本 | 位置 | 写给谁 | 有没有"换模型" |
|---|---|---|---|
| 接口参考 | docs/zh-CN/software-guide/api-reference/framework/api_aidetect.md | 查函数签名的人 | ✗ |
| AI 向导 | .agents/skills/hi-aiot-cv610-ai-algorithm-apply/（4 个 references） | AI 编码助手 | ✓（含错误码表） |
| 可跑样例 | apps/cv610_ev_board/samples/ai_component/README.md | 想跑通的人 | 部分 |
| 出厂 demo | apps/cv610_ev_board/references/factory_demo/ws73_lcd/README.md | 想看真实产品的人 | ✓（fw_cli） |
从任意一份出发都走不到另外三份：docs 不引用.agents/，samples 页链到在线仓，出厂 demo 的 README 埋在references/factory_demo/ws73_lcd/第 5 层。
这条比"文档缺失"更准确：能力是完整的、甚至写了四个版本，问题只在入口没有连起来。
5.3 文档把本地已有的东西指向了在线仓库
docs/zh-CN/samples/cv610_dev_board/README.md列了一整张案例表，24 个跳转链接全部是https://gitcode.com/HiSpark/hi_aiot_solution_cv610_ev_board/...的绝对 URL。
而对应的 README 就在本地：apps/cv610_ev_board/samples/sensor/single/README.md、.../dual/、.../ai_component/全都在，内容还更详细（有 Sensor/分辨率/fps 表、目录树、mermaid 数据流图）。
后果：离线环境、内网、GitCode 访问慢的时候，学生的"下一步"直接断掉。
六、一个必须说清的方法学陷阱
关键词命中率与解决率严重脱节。
10 个问题在 docs 树里共命中136 处文件，真正能回答问题的约8 处，噪声率约94%。
几个典型：
| 问句 | 撞到哪 | 为什么撞上 |
|---|---|---|
| 屏为什么黑 | tools/BurnTool.md | 因为里面写了"上电" |
| ATC 在哪下 | HI_MAPI_VENC_SVAC3_NALU_..._PATCH | 因为它含 “ATC” 三个字母 |
| 板子 IP | scenario-1/3 | 因为里面确实有"静态 IP"，但讲的是 Windows 网卡 |
所以：
- "第几轮搜到"不能当指标：10 问里有 9 问在第一轮就"命中"了。
- 机器耗时（平均 124 ms）也不能当指标：那是 grep 的速度。学生的瓶颈不是搜索快，是"不知道往哪棵树找"。
- 唯一有效的指标是"读完最高排名页面之后，还有没有答案"——这正是 A/B/C/D 定级做的事。
这段建议原样保留在报告里，因为它恰好说明：问句找不到答案，不是学生不会搜。
七、如果我是厂商，我会改这五处
| 优先级 | 改法 | 成本 | 收益 |
|---|---|---|---|
| P0 | FAQ 增补五问：摄像头 / 屏 / 模型 / IP / 音频。每问三段：现象、怎么判断、怎么解决 | 一天 | FAQ 是唯一按问题组织的位置，改造成本最低、收益最高 |
| P0 | fw_cli进 README 首屏：加一节"不做 UI 也能验证的 5 条命令" | 半小时 | 把"有 NPU"从宣传语变成学生 30 秒能验证的事实 |
| P1 | 补一页"光学准备"：定焦、工作距离 1 m、螺纹可调、保护膜 | 半天 | 消掉最高频的"镜头是坏的"误判 |
| P2 | samples 页的 24 个绝对 URL 改相对路径 | 十分钟 | 断网/内网环境下"下一步"不断 |
| P2 | 从 skills 抽 1 页给人看（如ai-algorithm-apply的错误码表） | 半天 | 已经写好的高质量内容不该只对 AI 可见 |
八、如果我是老师，我这样自救
- 每台配一根串口线。屏黑时它是唯一能看见真相的通道，能省掉 80% 的"板子坏了"。
- 把这三个问题的答案印在工位卡上：摄像头必须先接、拉流要加
-rtsp_transport tcp、板子自带 Type-C 调试口。 - 课前查好 IP 并贴标签。MAC 每次启动随机，重启就变。
- 第一节课别讲编译。出厂镜像开箱即跑，15 分钟能出图；把编译放到第二次课，且由老师预先搭好环境。
fw_cli值得你花十分钟找出来。它在apps/cv610_ev_board/references/factory_demo/ws73_lcd/，是这块板上最好的教学入口（用法见我另一篇）。
九、复现方法
脚本只回答"能不能搜到、要试几次、藏在哪里"；"搜到的是不是真答案"必须人工读页面后定级。
# 在装了 SDK 的 Linux / WSL 里python3 doc_survey.py>survey.txt2>&1python3 doc_survey.py--json>survey.json脚本做了三件事：三个搜索域、10 组问题（每组三档关键词）、记录首命中轮次 / 路径深度 / 耗时。原始输出已归档，结论可逐条核对。
一句话总结：这套文档不缺内容，缺的是从问题到入口的那条路。10 个问题里 5 个在 83 篇文档里彻底没有答案，4 个要靠翻工程目录去拼，1 个只有接口没有路径——而唯一一个 A 级（环境搭建）说明：只要按任务组织，他们是写得好的。
