日照模拟与面积算量:功能取舍里藏着的产品判断
日照模拟与面积算量:功能取舍里藏着的产品判断
社区里关于「户型图工具」的测评,最近反复出现两个功能点:一个是能在浏览器里拖动的日照模拟,一个是按墙内净尺寸加 5% 损耗系数算出的地面材料费用。它们看起来一个偏感觉、一个偏算术,却常常被放进同一句推荐语里。原因不难理解——买房和装修这两个决策时刻,用户真正缺的不是一张更漂亮的图,而是「我能不能提前知道住进去会怎样」和「这份报价我能不能自己验一遍」。
这篇文章想做的不是功能清单复述,而是把这两个功能拆到成本、可信度和边界三个层面,看看它们各自买到了什么、放弃了什么。为了把「取舍」讲实,我同时对照了当前工作目录里这个同名仓库 floorplan 的源码:它不做 3D、不做日照、不做算量,但它在自己的领域里做出了一组高度同构的判断,恰好可以作为参照系。
先校准一个同名误会
必须先把事实说清楚,否则后面的推论都会悬空。
社区测评里说的 floorplan-3d,是一个纯前端单文件工具:整个应用就是一个 index.html,2D 平面图上摆家具、拆墙、量尺寸,按一下切换进 Three.js 的 3D 场景,带日照模拟、第一人称漫游和墙体剖切。而本仓库的 floorplan 是另一个东西:它是 Claude Code / Codex 的插件,扫描代码库,把子系统、文件、HTTP 路由画成一张可交互的架构地图,产物是 floorplan/index.html。前者面向居住空间,后者面向代码空间。
两者唯一的共同点是名字,以及「把不可见的结构画出来」这个动作。但这不影响比较,因为产品判断的判据并不依赖行业:一个功能值不值得做,取决于它的实现成本、被感知价值,以及出错时由谁承担后果。这三条在住宅和代码库里是通用的。
需要提醒的是,本仓库里没有任何日照或算量相关的实现——package.json 只有一行 test 脚本,skills/floorplan/ 下的脚本全部围绕扫描、路由匹配、健康检查和图层渲染。所以下面关于日照与算量的技术细节,来自社区测评披露的实现;关于取舍逻辑的对照,来自本仓库可验证的源码。
日照模拟:十几行三角函数,买的是「预入住」的解释权
测评文章给出的交互参数很具体:顶栏的日照滑块范围 7:00 到 18:00,步进 0.25 小时,也就是每 15 分钟一档,拖动时画面实时响应。核心光照逻辑集中在一个 applyLight() 函数里:
const t = (opt.hour - 6) / 12,
az = Math.PI * (.15 + t * .7),
el = Math.sin(Math.PI * t) * 1.05 + .15,
warm = 1 - Math.sin(Math.PI * t);
sun.position.set(Math.cos(az) * 18, Math.sin(el) * 20 + 3, -Math.sin(az) * 10 + 8);
sun.color.setHSL(.09, .5 + warm * .4, .92 - warm * .12);
sun.intensity = opt.night ? .05 : 1.4 + Math.sin(Math.PI * t) * 1.6;
这段代码值得逐项读。t 把 6:00–18:00 归一化到 0–1,滑块从 7:00 起步,所以 t 的起点是 1/12 而不是日出时刻;az 在 0.15π 到 0.85π 之间线性扫掠,这是一个「从东侧转到西侧」的抽象角度,并不对应以正北为 0 的真实方位角定义;el 用正弦包络给出高度角,正午最高、两端贴地。代进数值看:7:00 时 el ≈ 0.42 rad(约 24°),太阳已经挂在中低空;18:00 时 el = 0.15 rad(约 8.6°),是一颗压得很低的落日。warm 则把色温与时段绑定,早晚偏橙、正午偏白,同时驱动 intensity 在 1.4 到 3.0 之间起伏。
也就是说,它模拟的是一天之中光线的叙事节奏,而不是某个纬度、某个日期、某栋楼的真实日照。没有纬度参数,没有节气,没有邻楼遮挡体,也没有「日照时数」这种可以拿去和规范对照的指标。如果按建筑日照分析的标准去衡量,它是不合格的;但按「让购房者在五分钟内对西晒产生体感」这个目标去衡量,它几乎是性价比最高的做法。
成本结构也很清楚:一个平行光、一个开关阴影的渲染管线,外加一个滑块。真正花钱的地方不在公式,而在阴影质量——测评提到阴影贴图最高 4096,平板设备自动降到 2048 保帧率。同一批社区文章在讨论 Web 3D 性能时,把坑归纳为四类:模型面数失控、渲染循环里全量重建、引擎与资源未按需加载、移动端像素比与阴影贴图未做适配。换句话说,日照模拟的公式是一次性成本,渲染管线的维护是长期成本。它之所以在轻量工具里成立,是因为只有一束方向光,而不是一屋子灯具加实时全局光照。
这里已经能看出第一个产品判断:当「感觉」比「精度」更能驱动决策时,选择做一个可被感知的近似,而不是一个可被审计的模型。近似不是偷懒,它需要产品方明确知道自己在简化什么——简化掉纬度与遮挡,换来的是用户敢拖、敢看、敢下结论。
面积算量:5% 损耗系数,卖的不是面积是口径
另一个功能看起来更「硬」:按墙内净尺寸计算各房间地面面积,叠加材料单价与 5% 的行业常规损耗系数,实时生成材料费用明细。
先拆「墙内净尺寸」这个口径。装修报价里最容易吵架的三件事,恰好是面积口径、损耗率和材料混搭。建筑面积含公摊与墙体,套内面积含内墙,墙内净尺寸才是真正要铺地板的那块;三者能差出几个百分点,而报价单通常只写一个总数。工具把口径固定成「墙内净」,等于把争议从「你按什么算的」提前挪到了「我们是否同意这个口径」。
再拆 5%。损耗系数不是测量结果,它是施工参数:铺法(工字、人字、斜铺)、房型异形程度、板幅尺寸、切割余料都会让它上下浮动。行业里给一个默认值,本质是给双方一个可引用的锚。工具把 5% 显式写进明细,价值不在于这个数字多准,而在于它把「不可见的余量」变成了「可讨论的参数」:用户可以直接问「我家斜铺,5% 够吗」,而不是对着一个总价猜。
但也正是这里藏着风险:系数可调,结论就可调。一个把损耗率藏在总价里的报价单,和一个把损耗率摆在明面上的工具,区别不是谁更准,而是谁更难含糊。所以这类功能的产品判断重点不在算法,而在是否愿意把假设暴露给用户。暴露假设会削弱「权威感」,却换来了可验算性——对一次性、金额敏感、信息不对称极强的装修场景,这笔交换通常是划算的。
把两个功能放在一起看,分野就出来了:日照模拟是感知型仿真,交付的是一张能让人产生体感的图;面积算量是计算型对账,交付的是一张能被逐项质疑的表。前者靠渲染说服人,后者靠口径说服人。它们的共同点只有一个——都拒绝给出「精确但无法解释」的答案。
同一套判断,在这个代码仓库里的镜像
现在回到本仓库。它没有日照和算量,但它在几个地方做出了结构完全相同的取舍,而且这些取舍被写进了代码和测试,可以被逐行核对。
精度优先于召回:Health 的自我约束
skills/floorplan/scripts/lib/health.mjs 开头第三行写着一句很少见的自我约束:
// Precision beats recall: a false alarm costs this audience more than a missed one.
这句话决定了后面所有阈值的方向。为了压误报,它做了三层降噪:测试与示例文件单独归类(TEST_FILE、EXAMPLE_FILE 两个正则),占位符与示例值单独排除(PLACEHOLDER),密钥值只保留掩码提示而不是原文:
const mask = (v, password) => password || v.length < 12 ? `${v.length} characters` : `starts “${v.slice(0, 4)}…”, ${v.length} characters`;
它甚至限制了「一次能报多少」:MAX_SECRET_ISSUES = 8,整份报告 issues.slice(0, 40)。未使用文件的检测还加了一层安全网——如果某个模块里大多数文件都「看起来没人用」,它倾向于认为这是自己看不见的加载方式,直接不报;文件名的词干只要在别的源码里出现过,也跳过。
大文件的阈值同样是这个逻辑:loc > 1000 才计入,超过 2000 行才把严重度从 low 提到 medium:
const big = graph.files.filter((f) => f.loc > 1000 && USED_LANGS.has(f.l) && ...).sort((a, b) => b.loc - a.loc);
const huge = big.filter((f) => f.loc >= 2000);
这和 5% 损耗系数是同一种诚实:把「我用的假设」和「我覆盖不到的地方」明确写出来。超过读取上限的文件不会从地图上消失,它仍然带着行数出现,并在说明里注明「连接关系和密钥未被检查」——tests/large-files.test.mjs 就是在锁这条行为,甚至断言了 1,500 lines: too big for Floorplan to read 这句提示的存在。0.3.1 版本把可读单文件上限从 512 KB 提到 2 MB,也是同一个动作:先承认边界,再调整边界。
默认值就是产品态度:导出不默认带 Health
skills/floorplan/assets/ui/60-export.js 里定义导出的可选项时,默认值是这样的:
{ id: 'flows', label: 'Flows and the tour', hint: 'The guided walkthroughs, including ones you requested.', on: true, ... },
{ id: 'notes', label: 'Notes pinned to files', hint: 'The notes shown on file cards.', on: true, ... },
{ id: 'recent', label: 'Recent work', hint: 'What was just changed, and why.', on: false, ... },
{ id: 'health', label: 'Health check', hint: 'Lists the endpoints anyone can use and where secrets sit in the code (never their values). Only include it for people you trust.', on: false, warn: true, ... },
流程图和注释默认勾选,因为它们是「解释系统怎么运转」的部分;健康检查默认不勾,因为它是一张攻击面清单,只该给可信的人。这就是把「这个功能会不会造成二次风险」写成了布尔值,而不是写在文档里靠用户自觉。同一份导出物还会隐去 Ask 栏、编辑器链接、本机路径和 git remote——减少信息,而不是堆叠信息。
规划态与代码态必须分叉:Blueprint 的权限枚举
skills/floorplan/scripts/lib/blueprint.mjs 里有一个很小的枚举,但它决定了整套规划语义:
export const ACCESS = ['public', 'signed-in', 'team', 'webhook', 'internal'];
team 与 signed-in 的区分是刻意的:前者指「运营这个服务的人」,后者指「这个应用的用户」,混用它们会让权限设计从第一步就错。校验时还会专门纠正一个常见误用——如果规划里写了 staff,报错会提示改用 team,或者用 signed-in 加 who 说明是哪类用户。
更关键的是调用关系的匹配策略:matchCalls(...) 之后还要再过滤一次,注释写得很直白——calls only reach the exact planned endpoint (method and path), never a near miss。宁可漏掉一条连线,也不画一条「大概通向这里」的线。这与 Health 的 precision-over-recall 是同一个决策在不同模块里的重复,而不是两套标准。
蓝图模式还会把 Health 换成 design review:代码态检查的是「密码是否写死在代码里」,规划态检查的是「这个接口有没有决定谁能调用」。同一个面板,在不同产物阶段回答不同的问题,这也是一种取舍——不为了复用 UI 而扭曲语义。
把边界写进测试,而不是写进承诺
README.md 里有一句容易被当成营销话术的话:零依赖、可离线、只监听本机。区别在于,这个仓库把它变成了断言。tests/supply-chain.test.mjs 逐条校验:
package.json里不允许出现任何dependencies字段,也不允许有 lockfile;- 整个插件只允许一个网络模块导入(
assets/serve.mjs的node:http),并且必须server.listen(port, '127.0.0.1'); - 所有
fetch调用中,只有一处可以指向外部(可选的 waitlist),其余必须是本地相对路径; - 启动外部程序只允许
spawn与execFileSync,禁止shell: true,且被启动的程序名必须命中白名单; - 禁止
eval,new Function只允许出现在serve.mjs读取自己query.mjs的那一处; - 内置的 ELK 布局引擎要与 npm 上
elkjs@0.9.3的文件逐字节一致(sha256写死在测试里)。
这套测试的意义不在「安全」,而在它让「不做某事」变成可执行的约束。文档会过期,评审会遗忘,但一条断言不会。对照日照模拟里的 4096/2048 阴影贴图分级,你会发现是同一种工程直觉:用确定性换体积,或者用体积换确定性,但代价必须显式。
两类功能背后的用户画像差异
功能取舍之所以不能照抄,是因为同一个功能落到不同人手里,价值密度完全不同。把社区情报里出现的几类人群和本仓库的目标用户放在一起,差异一目了然。
| 维度 | 购房者(日照模拟) | 装修业主(面积算量) | 智能家居用户 | 空间数据/机器人训练 | 本仓库用户(AI 建站者/团队) |
|---|---|---|---|---|---|
| 使用频次 | 一次性、集中在决策窗口 | 一次性,持续数周 | 长期、日常 | 批量、离线 | 高频,随每次改动 |
| 单次决策金额 | 极高 | 中高 | 低 | 项目级 | 低(时间成本为主) |
| 最怕的错误 | 采光被挡却看不出来 | 面积口径与损耗被含糊 | 状态不同步 | 数据不规范、不可序列化 | 误报导致不信任、漏报导致事故 |
| 需要的产物 | 可感知的图 | 可逐项核对的表 | 与真实设备联动的视图 | 带尺寸与语义的结构化导出 | 可点击、可追问、可执行的图与提示 |
| 对精度的容忍 | 低精度、高体感可接受 | 参数必须可见 | 精度要求中等、实时性优先 | 精度要求高、可验证 | 宁可少报,不可乱报 |
这张表解释了一个常被忽略的现象:floorplan-3d 与 Home Assistant 那套基于 Sweet Home 3D 的方案经常被拿来比较,但两者根本不构成替代关系——一个服务装修决策阶段,一个服务智能运维阶段。同理,本地这个 floorplan 也不该被拿去和 3D 户型工具比功能多少,因为它们回答的是不同人在不同时刻的恐惧。
更值得注意的是「户型图作为数据资产」这条线。社区里有文章把它和具身智能训练挂在一起:真实、带尺寸、结构化的户型数据,是机器人理解居住空间的先验。这个视角会把功能优先级彻底改写——对训练数据来说,日照滑块再顺滑也没有意义,重要的是毫米级尺寸、房间拓扑、可序列化的 JSON 导出,以及语义标注是否一致。同一份能力,服务对象一换,该做的功能就换了一批。
三个可以复用的判据
如果把上面的分析压缩成可操作的东西,大概是这样三条。
第一,结论是否可被用户复核。 面积算量把 5% 摆在明面上,用户可以拿铺法去质疑;Health 把文件路径、行号、掩码后的片段摆出来,用户可以点「Show on map」自己看。凡是给出结论却不给复核入口的功能,都在消耗信任。
第二,错了由谁承担,以及误报和漏报哪个更贵。 购房场景里,日照误判的代价由用户承担,所以工具要尽量把体感做足;代码健康检查里,误报的代价是用户从此不再打开这个面板,所以宁可漏报。Precision beats recall 不是通用真理,它是针对特定人群的成本计算。
第三,边界是否写进了机器。 写了,就是产品;只写在文档里,就是意愿。ACCESS 枚举、MAX_SECRET_ISSUES、1000 行阈值、127.0.0.1、shell: true 禁令——这些都是「我们知道自己会在哪里停手」的证据。
flowchart TD
A[想做的一个功能] --> B{结论能被用户复核吗}
B -- 不能 --> C[先补口径/行号/参数,再谈体验]
B -- 能 --> D{误报和漏报哪个更贵}
D -- 误报更贵 --> E[提高阈值,承认覆盖不到的地方]
D -- 漏报更贵 --> F[放宽阈值,但把不确定性显式标出]
E --> G{边界能写成断言吗}
F --> G
G -- 能 --> H[写进测试、默认值与枚举]
G -- 不能 --> I[缩小功能范围,直到能]
写在最后
功能清单能证明一个团队会做什么,删掉的功能才证明它想清楚了什么。日照模拟用十几行三角函数换来「预入住」的体感,面积算量用一个 5% 的系数换来可议价的口径,本仓库则用一句 Precision beats recall、一个默认不勾选的导出项、一条 127.0.0.1 的断言,换来「这个工具说的话可以信」。
它们的共同点不是技术栈,而是同一种克制:知道自己简化了什么,并且愿意把简化写出来。docs/how-it-works.md 里对连接匹配的描述也是这个语气——「It's pattern matching, not a compiler, so it catches most connections but not all」;Health 面板自己也承认「It's a quick automatic check, not a security audit」。
一个产品最难的部分,往往不是把功能做出来,而是在功能旁边写下它的边界。日照滑块和 5% 损耗系数之所以值得讨论,不是因为它们多先进,而是因为它们把「不确定」摆到了用户能碰到的地方。
