企业官网建设流程全解析

LifeOS 收入数据建模实战：从 INCOME.md 模板到 Pulse Finance 收入看板

【免费下载链接】LifeOS⛰️ The Life Operating System — an intent engineering platform that moves you from your current state to your ideal state, in life and work.项目地址: https://gitcode.com/GitHub_Trending/pe/LifeOS

导读

LifeOS 将个人财务语境以结构化 Markdown 文件的形式存放在USER/FINANCES/目录中，而INCOME.md正是其中专门负责"收入侧"数据的核心文件。本文以该文件为骨架，逐字段拆解四种收入来源的模板结构，讲解如何通过/interview finances会话或直接编辑完成数据填充，并结合schema.yaml的字段枚举约束与 Pulse Observability 模块中finances页面的真实消费链路，说明这些数据最终如何演变为月度收入汇总、MRR 指标、桑基图与收支趋势图。读完本文，你将掌握在 LifeOS 中建模、校验并可视化个人收入全貌的完整方法。

一、INCOME.md 在 LifeOS 财务数据层中的定位

LifeOS 的私有用户数据树（USER/）中，FINANCES 目录 是个人财务语境的唯一事实来源。LifeOS 会读取这些文件来驱动 Pulse 的 Finance 看板、在日常简报（daily brief）中浮现待缴义务，并基于真实（私有）数据回答关于你资金状况的问题。该目录内部分工明确：

其中 INCOME.md 的定义非常清晰："Every source of money coming in."（一切流入资金的来源）。Pulse 基于它完成三件核心工作：

1. 计算月度收入（compute monthly income）——把各来源按频率折算成月度口径；
2. 识别缺口（identify gaps）——对比预期收入与账单、支出，暴露现金流风险；
3. 与账单流水对账（reconcile against deposits seen in account statements）——把ACCOUNTS.md与银行对账单中出现的入账与收入来源进行匹配验证。

文件的 frontmatter 标注了provenance: template，顶部注释也明确说明这是一个 SAMPLE TEMPLATE：真实数据需通过/interview会话或手动编辑替换占位符后，Pulse Finance 看板才会开始填充真实数值。

二、Active Sources：四种收入来源模板逐字段拆解

INCOME.md的核心章节是## Active Sources（活跃收入来源），模板内置了四个代表性样本，覆盖了从工薪、合同到产品订阅、投资分红的完整场景。值得注意的是，这些字段不是自由文本，schema.yaml对它们有严格的类型与枚举约束——保持字段名不变是 Pulse 正确读取的前提。

2.1 Sample Source 1 — 工资（W-2 雇佣）

- **Type:** W-2 employment (sample) - **Payer:** Sample Employer Inc. - **Frequency:** semi-monthly (sample) - **Gross per period:** $X,XXX - **Net per period:** $X,XXX - **Annual gross (expected):** $X,XXX - **Deposit account:** Sample Bank Checking (...XXXX) - **Started:** YYYY-MM-DD (sample) - **Notes:** Sample notes about this income source.

对应 schema.yaml 中income_source对象（required: [name, type, payer, frequency]）。其中type的合法枚举值为w2 / 1099 / subscription / dividend / interest / royalty / rental / other，frequency的合法枚举值为weekly / biweekly / semi-monthly / monthly / quarterly / annual / project-based / irregular。工资场景下gross_per_period（每期税前）与net_per_period（每期税后）的差值即代扣税额，annual_gross用于全年预期校验。

2.2 Sample Source 2 — 咨询 / 1099 合同

- **Type:** 1099 contract (sample) - **Payer:** Sample Client LLC - **Frequency:** project-based (sample) - **Per-engagement amount:** $X,XXX - **YTD received:** $X,XXX - **Deposit account:** Sample Bank Business Checking (...XXXX) - **Notes:** Sample notes — e.g., quarterly estimated tax implications.

1099 收入的特点是按项目结算、金额不固定，因此模板提供了Per-engagement amount（单次合作金额）与YTD received（年初至今累计到账）两个口径，并在 Notes 中提示季度预估税（quarterly estimated tax）影响——这与其姐妹文件 TAXES.md 的quarterly_estimates结构相呼应。

2.3 Sample Source 3 — 订阅制产品收入（SaaS / 自有产品）

- **Type:** SaaS / product income (sample) - **Source:** Sample Platform (e.g., your own product) - **Frequency:** monthly (sample) - **Current MRR:** $X,XXX - **Trend (last 90 days):** sample direction - **Deposit account:** Sample Payment Processor → Sample Bank Business Checking - **Notes:** Sample notes.

这是模板中唯一带有MRR（月度经常性收入）字段的来源类型，且Deposit account使用Sample Payment Processor → Sample Bank Business Checking的流向链写法，体现了"收款工具 → 最终入账账户"的资金链路。订阅/分红类收入直接对接到看板上的 MRR 指标（见第四节）。

2.4 Sample Source 4 — 投资 / 分红收入

- **Type:** dividend / interest (sample) - **Source:** Sample Brokerage holdings - **Frequency:** quarterly (sample) - **Average per period:** $X - **Notes:** Sample notes — taxable vs. tax-advantaged.

分红/利息收入按季度发生，模板用Average per period（每期平均额）平滑波动，Notes 提示区分应税（taxable）与税收优惠（tax-advantaged）账户——后者对应schema.yaml中investment_account.account_type的taxable / roth_ira / 401k / hsa / 529等枚举。

2.5 Expected Monthly Total 与 Inactive / Past Sources

## Expected Monthly Total - **Expected monthly income (all sources):** $X,XXX - **Variability:** sample description (e.g., "stable ±X%") ## Inactive / Past Sources - Sample past employer — ended YYYY-MM-DD - Sample past client — ended YYYY-MM-DD

Expected Monthly Total是收入侧的关键汇总值：它把所有来源按频率折算为月度口径后求和，Variability则描述收入的稳定性（如 "stable ±X%"），为预算与支出侧提供置信度。Inactive / Past Sources记录已结束的来源（对应schema.yaml中ended日期字段），避免历史收入被误计入当前现金流，同时保留审计追溯能力。

三、两条数据填充路径与占位符规范

FINANCES 目录的 README 明确给出两条等价的填充路径：

1. 运行财务访谈：/interview finances会以对话形式逐文件引导你填写，并把结果写回USER/FINANCES/目录；
2. 直接编辑文件：打开每个文件，把$X、Sample Bank、Sample Vendor等占位符替换为真实值，保持整体结构不变，因为 "Pulse depends on the field names"（Pulse 依赖字段名）。

模板占位符遵循统一约定，便于机器识别与校验：

schema.yaml底部的validation规则进一步收紧了写入边界，这五条规则同样适用于INCOME.md的所有字段：

• 所有金额字段必须是字符串（而非数字），以便 onboarding 阶段允许$X,XXX这类占位符存在；
• last_4字段必须恰好 4 个字符（数字或X占位符）；
• 日期必须为 ISO 8601（YYYY-MM-DD）；
• category与枚举字段必须与允许值精确匹配；
• 任何地方不得出现完整账号，只能使用末四位。

四、隐私边界：为什么收入数据只存在于本地 USER 树

FINANCES 目录属于 LifeOS 的私有 USER 树，永远不会被打包进公开的 LifeOS 发布版。README 的提醒非常直白："Treat it like your password manager"（像对待密码管理器一样对待它）——真实数字写在这里，但它只停留在你的机器上。这也解释了为什么仓库中随附的 INCOME.md 全是占位符：模板必须安全地随仓库发布，真实数据由用户在本机填充。

在 Pulse 看板侧，同样的隐私原则通过前端渲染体现：finances页面中所有金额元素都带data-sensitive标记，页面顶部明确标注 "Private. Toggle Observer mode to blur."（私有数据，可切换观察者模式模糊显示），金额数字在 Observer 模式下会被遮蔽，防止共享屏幕时泄露财务信息。

五、数据如何驱动 Pulse Finance 收入看板：源码级消费链路

INCOME.md的数据并不是静态文本，而是通过 Pulse 的 Observability 模块进入可视化层。以 finances 页面 的实现为例，前端通过fetch("/api/life/finances")拉取 v2 信封数据，其中与收入直接相关的结构为：

income?: { streams: Stream[]; // 收入流列表（label + annual 年化） annual: number; // 年度总收入 monthly: number; // 月度总收入 mrr_monthly: number; // 月度经常性收入 mrr_annual: number; // MRR 年化 };

这份数据在IncomeTab中被渲染为两大区块：

1. IncomeHero 收入总览卡：大字号展示Total Annual Income（年度总收入）与monthly（月度），下方四个 KPI 图块分别为Monthly Recurring（月经常性收入）、MRR Annualized（MRR 年化）、Streams（收入流数量，非敏感数据不脱敏）与Monthly Income。可见INCOME.md中订阅类来源的Current MRR与Trend字段，正是 MRR 两个指标的数据来源。
2. Income Streams 收入流列表：StreamCard逐条渲染每个收入来源，展示年化金额与折算后的annual / 12月度值，并按标签自动匹配图标（consulting → Briefcase、product → Globe、course → BookOpen 等）。

此外，FinancesSankey组件把income.streams作为桑基图左侧节点，汇聚为 "Gross Income" 池后分流到 Expenses 与 Net，直观呈现"收入 → 支出 → 净结余"的资金流向；TrendChart则绘制Income vs Expenses — 12 Month Trend折线图（income 为绿色系var(--money)），页面同时提示 "Flat baseline until Phase 2 collectors accumulate historical monthly data"——即历史月度数据需要 Phase 2 收集器逐步积累后，趋势线才会丰满起来。

从observability.ts的路由清单（文件头部注释）可以看到，该模块不创建独立 HTTP 服务，而是由父进程pulse.ts调用handleObservabilityRequest()分发/api/*路由，/api/life/finances即由 Pulse 守护进程在本地提供，保证了财务数据不经过任何外部服务。

六、与其他财务文件的协同：收入侧到支出侧的整体闭环

INCOME.md不是孤立的：LifeOS 的财务建模以"现金流闭环"为设计目标。顶层概览 FINANCES.md 的Monthly Cash Flow区块正是收入与支出的交汇点——它列出Income (monthly)、Fixed expenses、Variable expenses、Net与Savings rate，其中的收入数字来自INCOME.md的Expected Monthly Total。FINANCES.md的Linked Files一节完整列出了这一协同关系：Income detail →INCOME.md，Expense detail →EXPENSES.md，Recurring bills →obligations.yaml。

而在对账层面，obligations.yaml（周期性账单）与INCOME.md构成"流入 vs 流出"的对照：看板的 Outbound 侧把vendors、obligations、other三组支出年化汇总，Overall标签页计算net_pre_tax与net_post_tax，effective_tax_rate则依赖TAXES.md的税率信息。当预期月度收入低于月度义务总和时，"identify gaps" 的能力就体现出来——这也是模板要求填写Variability（收入稳定性）的原因：缺口评估需要知道收入端本身的置信区间。

七、实操清单：让 INCOME.md 从模板变为真实数据

综合模板结构、schema 约束与看板消费逻辑，一份"合格"的INCOME.md应当满足以下清单：

1. 覆盖全部活跃来源：每个来源至少填写type、payer、frequency三个必填字段（schema 的required列表），金额按占位符约定替换为字符串；
2. 频率口径统一：frequency严格使用枚举值（weekly / biweekly / semi-monthly / monthly / quarterly / annual / project-based / irregular），因为月度折算依赖它；
3. 金额字段完整：工资类补全gross_per_period+net_per_period+annual_gross，1099 类补per-engagement与YTD，订阅类补MRR，投资类补average_per_period；
4. 日期合规：started、ended一律使用YYYY-MM-DD格式；
5. 账户只留末四位：deposit_account写成Sample Bank Checking (...XXXX)形态，杜绝完整账号；
6. 更新Expected Monthly Total：汇总所有来源的月度折算值，并如实描述Variability；
7. 迁移历史来源：已结束的收入移入Inactive / Past Sources，并保留ended日期；
8. 同步相关文件：更新FINANCES.md的月度现金流、TAXES.md的预估季度税、ACCOUNTS.md的入账账户，保证跨文件一致性。

完成填充后重启或刷新 Pulse，/api/life/finances返回的income.streams即从空列表变为真实收入流——Income 标签页的年度/月度总收入、MRR 与桑基图将随之被真实数据点亮。若页面显示isFreshInstall引导卡片（incomeAnnual === 0 && incomeStreams.length === 0），则说明INCOME.md尚未被正确填充或字段名与 schema 不一致，需回头按校验规则核查。

【免费下载链接】LifeOS⛰️ The Life Operating System — an intent engineering platform that moves you from your current state to your ideal state, in life and work.项目地址: https://gitcode.com/GitHub_Trending/pe/LifeOS