企业官网建设流程全解析

LifeOS Arbol Actions 深度解析：可复用原子动作模块的设计、实现与最佳实践

【免费下载链接】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 的云端执行层 Arbol 将一切云端工作收敛为三种可组合原语——Actions、Pipelines 与 Flows。其中Actions 是最底层的原子单元：每个动作只做一件事，输入 JSON、输出 JSON，不依赖共享状态、不留副作用通道，是所有流水线与流程得以组合复用的基石。本文以 ACTIONS 目录说明 为主体骨架，结合 ArbolSystem.md 的系统级文档，完整讲解动作模块的目录规范、action.json清单与action.ts实现、管道（pipe）模型与透传（passthrough）模式、能力声明、命名规范、本地与云端运行方式，以及"何时该新建动作、如何新建动作"的实战准则。读完本文，你将掌握在 LifeOS 中设计与编写一个生产级可复用 Action 的完整方法。

一、Actions 是什么：LifeOS 云端执行层的原子单元

在 LifeOS 的架构中，Arbol 是"在你入睡时仍在运行的 LifeOS"——调度流（scheduled flows）持续监听数据源、转化信号、从边缘侧推动状态变更，即使没有会话打开，系统对"当前状态"的认知也在不断刷新（参见 LifeosSystemArchitecture.md）。

Arbol 通过三种自下而上组合的原语组织所有云端工作：

Action ---> Pipeline ---> Flow (unit) (chain) (scheduled system)

ACTIONS 目录说明 给出的定义是全文的锚点：

Purpose:Reusable action modules — atomic units of work that LifeOS pipelines and flows compose into larger workflows.

Actions 是可复用的动作模块——LifeOS 管道与流程组合成更大工作流的原子工作单元。它遵循 UNIX 哲学：一件事做到极致，通过标准接口组合：

JSON Input → Action Logic → JSON Output

关键的纪律约束有三条，缺一不可：

• 无副作用通道（no side channels）：动作不能偷偷读写共享状态；
• 无共享状态（no shared state）：动作之间不共享内存或全局变量，数据只通过输入输出流动；
• 小而可组合（small and composable）：保持动作小、专注、可复用，这正是整个设计的目的所在（"Keeping them small and composable is the entire point"）。

典型真实动作示例（来自 ArbolSystem.md）：

二、目录结构：一个动作 = 一个自包含子目录

按 ACTIONS 目录说明 的约定，"这里存放什么"很明确：

Each action is a self-contained subdir (typicallyA_<NAME>/or grouped under category folders likeextract/,format/,transform/) holding anaction.jsonmanifest and anaction.tsimplementation.

即每个动作是一个自包含子目录，典型命名为A_<NAME>/，也可以按类别归入extract/、format/、transform/等分类文件夹。目录内只有两个文件（详见 ArbolSystem.md）：

A_LABEL_AND_RATE/ ├── action.json # 清单：名称、描述、输入/输出 schema、requires 依赖 └── action.ts # 实现：execute(input, ctx) → output

这两个文件构成动作的完整契约：

• action.json—— 动作的"身份证"，描述动作是什么、能吃进什么、产出什么、需要哪些运行时能力；
• action.ts—— 动作的"引擎"，实现execute(input, ctx)函数完成从输入到输出的单次转换。

在 LifeOS 的个人用户树中，动作的存放位置是LifeOS/install/USER/CUSTOMIZATIONS/ARBOL/ACTIONS/。新装系统的示例状态为空——目录中只有这份 README，真实内容会随着你使用 LifeOS 而逐步沉淀（"Sample state for fresh installs: Empty / Just this README"）。

三、动作清单（action.json）与实现（action.ts）

3.1 action.json：声明式的输入/输出契约

动作清单负责声明四类元信息：name、description、input/output的字段级 schema，以及requires依赖列表（见 ArbolSystem.md）：

{ "name": "A_LABEL_AND_RATE", "description": "Label and rate content using Fabric's label_and_rate pattern.", "input": { "content": { "type": "string", "required": true }, "title": { "type": "string" } }, "output": { "one_sentence_summary": { "type": "string" }, "labels": { "type": "array" }, "rating": { "type": "string" }, "quality_score": { "type": "integer" } }, "requires": ["llm", "readFile"] }

要点解读：

• input中的每个字段可用required标记是否必填，type声明字段类型；运行时校验器据此对入参做快速失败（fail fast）检查；
• output声明动作产出的字段，既是文档契约，也是下游动作输入的依据；
• requires是显式能力声明——不要假设能力天然存在（"Don't assume capabilities exist"），用到的能力必须全部列出。

3.2 action.ts：execute(input, ctx) 模式

实现文件以默认导出对象的形式暴露execute方法，接收输入与运行时上下文（ActionContext），返回输出（见 ArbolSystem.md）：

import type { ActionContext } from "../lib/types.v2"; export default { async execute(input: Input, ctx: ActionContext): Promise<Output> { const { content, ...upstream } = input; // ... 使用 ctx.capabilities 完成工作 ... return { ...upstream, ...results }; }, };

注意这里的核心套路：先用结构剩余语法把本次消费的字段（如content）从输入中取出，其余字段作为upstream保留，返回时通过展开运算符把...upstream与本次结果合并。这正是下一节要展开的透传模式。

四、管道模型与透传（Passthrough）模式

4.1 Unix 式管道：N 动作的输出是 N+1 动作的输入

Arbol 管道采用 Unix 风格管道模型：前一个动作的输出，直接成为后一个动作的输入（见 ArbolSystem.md）：

Source --> Action 1 --> Action 2 --> Action 3 --> Destination | | | transform enrich format

4.2 透传模式：让上下文在管道中持续累积

ArbolSystem.md 强调：动作必须使用透传模式（...upstream）来保留前序动作产生的元数据，同时叠加自身输出。这样数据在管道中流动时上下文不断累积，而不是每一步被丢弃：

// 动作接收上游数据，加入自身输出，把一切继续向后传递 const { content, ...upstream } = input; return { ...upstream, // 保留此前所有动作的输出 myField: result, // 叠加本动作的贡献 };

这意味着管道中最后一个动作能够访问此前所有动作产生的每个字段，而不只是紧邻的上一个动作——这是动作可自由组合、管道可任意编排的关键保障。

4.3 字段级数据流示例

以下来自 ArbolSystem.md 的示例展示了两个动作之间的字段级流动：

A_EXTRACT_TRANSCRIPT A_LABEL_AND_RATE ┌─────────────────┐ ┌──────────────────┐ │ Input: │ │ Input: │ │ url │ ─────> │ content │ (原为 "transcript") │ │ │ video_id │ (透传) │ Output: │ │ title │ (透传) │ content ────┤ │ │ │ video_id ────┤ │ Output: │ │ title ────┤ │ one_sentence_ │ │ source ────┤ │ summary │ └─────────────────┘ │ labels │ │ rating │ │ quality_score │ └──────────────────┘

A_EXTRACT_TRANSCRIPT消费url，产出content、video_id、title、source；A_LABEL_AND_RATE消费content，同时通过透传获得video_id、title等上游字段，最终产出摘要、标签、评分与质量分。每个动作只声明自己新增的字段，其余一律透传。

五、动作类别与能力（Capabilities）体系

5.1 三种运行时类别

根据运行环境不同，动作分为三类（见 ArbolSystem.md）：

5.2 能力注入：requires 与 ctx.capabilities

动作在action.json的requires中声明依赖，由运行器注入对应实现（见 ArbolSystem.md）：

双环境注入策略：本地运行器注入真实实现；云端 Worker 工厂提供 Cloudflare 兼容版本。也就是说，同一份动作代码在本地与云端运行时能力来源不同，但动作本身无需改动——这正是"同一套动作、管道、流程在两种模式下无需改码即可运行"（Execution Modes，见 ArbolSystem.md）的基础。

5.3 命名规范

动作命名有严格约定（见 ArbolSystem.md）：

• 前缀：A_（动作专属前缀）；
• 大小写：UPPER_SNAKE_CASE；
• 长度与词序：2~4 个词，动词开头（WRITE、EXTRACT、LABEL、SEND）；
• Worker 名：arbol-a-{kebab-case-name}。

六、运行动作：本地 Runner 与云端 Worker

6.1 本地运行

Arbol 的本地运行器为bun脚本runner.v2.ts，可用run与list两个子命令（见 ArbolSystem.md）：

cd ~/.claude/LIFEOS/ARBOL/Actions bun lib/runner.v2.ts run A_LABEL_AND_RATE --input '{"content": "Your text here"}' bun lib/runner.v2.ts list

6.2 云端运行

云端动作以 Cloudflare Worker 形式部署，通过 HTTP 调用（见 ArbolSystem.md）：

curl -X POST https://arbol-a-your-action.YOUR-SUBDOMAIN.workers.dev/ \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{"content": "Your text here"}'

响应格式（见 ArbolSystem.md）统一包裹为：

{ "success": true, "action": "A_YOUR_ACTION", "duration_ms": 1234, "output": { "result": "...", "upstream_field": "preserved from input" } }

output内既包含动作自身的产出字段，也包含从输入透传过来的upstream_field——这与透传模式一一对应，便于调用方追踪数据血缘。

注意（公开版边界）：Arbol 属于 LifeOS 的私有基础设施，LIFEOS/ARBOL/本地运行器目录（Actions/、Flows/、Pipelines/）被 rsync 排除在公开发布包之外（见 ArbolSystem.md）。公开版提供的是 Arbol 的模型（三大原语、管道模型、云端 Worker 架构），以上本地命令路径仅存在于维护者私有部署中，可作为自建蓝本。

七、创建新动作：从目录到部署的五步流程

ArbolSystem.md 给出了新建动作的完整流程，结合 ACTIONS 目录说明 的存放约定，标准做法如下：

1. 创建目录：在个人定制目录下创建A_<NAME>子目录：

   mkdir ~/.claude/LIFEOS/USER/CUSTOMIZATIONS/ARBOL/ACTIONS/A_YOUR_ACTION

2. 定义清单：编写action.json，声明 name、description、input/output schema、requires；
3. 实现逻辑：编写action.ts，使用execute(input, ctx)模式完成单次转换；
4. 本地测试：

   bun lib/runner.v2.ts run A_YOUR_ACTION --input '{"content": "test"}'

5. 云端部署（可选）：在~/.claude/LIFEOS/USER/CUSTOMIZATIONS/ARBOL/Workers/a-your-action/下添加 Worker，然后执行：

   bash deploy.sh a-your-action

个人优先的解析顺序

ACTIONS 目录说明 指出动作目录"由用户显式填充"，而 CUSTOMIZATIONS 契约 进一步明确了覆盖规则：

Resolution order is always personal-first:CUSTOMIZATIONS/ARBOL/ACTIONS/<name>overridesLIFEOS/ARBOL/Actions/<name>; same forPIPELINES/andFLOWS/. The user copy wins.

即解析顺序永远是个人优先：放在CUSTOMIZATIONS/ARBOL/ACTIONS/<name>下的动作会覆盖系统级LIFEOS/ARBOL/Actions/<name>中的同名动作。这意味着：

• 想覆盖系统自带动作 → 在CUSTOMIZATIONS/ARBOL/ACTIONS/<name>放你的版本即可，运行时优先选你的；
• 想新增仅对你有意义的动作 → 同样放在CUSTOMIZATIONS/ARBOL/ACTIONS/下，没有"个人版 vs 系统版"之分，凡是你的就放这里。

同时 CUSTOMIZATIONS 契约 也划清了边界：纯读取的参考数据（身份、项目、联系人、观点、TELOS）应放在CUSTOMIZATIONS/的兄弟目录而非子目录——定制化关乎行为，而非事实；一次性实验则先用MEMORY/WORK/{slug}/，证明价值后再晋升到CUSTOMIZATIONS/。

八、动作最佳实践

ArbolSystem.md 总结了五条铁律，与 ACTIONS 目录说明 的"小而可组合"哲学互为表里：

1. 单一职责（Single Responsibility）：每个动作只做一件事。如果它做了两件事，拆成两个。
2. 透传模式（Passthrough Pattern）：永远写const { content, ...upstream } = input; return { ...upstream, ...myFields };，保证上下文向下游累积。
3. 显式能力声明（Explicit Capabilities）：把一切依赖写进requires。不要假设能力天然存在。
4. 快速失败（Fail Fast）：立即校验输入，抛出错因明确的异常。
5. 尽可能幂等（Idempotent Where Possible）：相同输入应产生相同输出（LLM 动作建议温度设为 0）。

九、什么时候该新建动作

ACTIONS 目录说明 对"如何被填充"给出了明确判据：

You build actions when you need a piece of logic that two or more flows or pipelines will reuse, or when you want one well-tested unit instead of inline code repeated across skills.

翻译成决策标准就是——满足以下任一条件时，就该把逻辑抽成 Action：

• 跨流程复用：同一段逻辑要被两个或以上的 Flow / Pipeline 复用；
• 追求可测试单元：你希望得到一个经过充分测试的独立单元，而不是在多个 skill 之间重复粘贴内联代码。

反之，如果一段逻辑只在一处使用、不会复用，先不要急于抽象——保持内联，直到"两次及以上复用"的信号出现。

十、Actions 与 Pipeline、Flow 的边界

Actions 是组合体系的最底层，理解它与上层原语的边界，才能正确设计动作（见 ArbolSystem.md 与 FLOWS 说明、PIPELINES 说明）：

三个关键规则（来自 ArbolSystem.md 的 Loop Gate 章节）：

• Pipeline 不循环：一条管道只按顺序跑完动作链一次并返回输出；
• Flow 控制迭代：for 循环与退出条件写在 Flow Worker 中；
• 必须设置maxIterations：没有上限，失败的退出条件会造成死循环。

一个典型的"晨间博客摘要邮件"案例可以说明三者如何组合（见 ArbolSystem.md）：A_EXTRACT抓取文章正文、A_SUMMARIZE压缩为一段、A_RATE打分——三个彼此无知的原子动作组成管道A_EXTRACT → A_SUMMARIZE → A_RATE；Flow 再把管道接到博客 RSS 源与邮箱目标上，用 cron0 8 * * *定时触发。整条链路跑在边缘节点而非笔记本上，系统对"博客有什么新内容"的认知无需打开会话也能自动刷新。

十一、小结

Actions 是 LifeOS Arbol 执行层最基础也最关键的抽象：一个自包含目录（A_<NAME>/+action.json+action.ts）、一次输入到输出的单次转换、零共享状态、强透传契约，决定了上层 Pipeline 与 Flow 能否自由组合。理解并遵守"单一职责、透传模式、显式能力、快速失败、幂等优先"这五条准则，就能持续沉淀出高质量的可复用动作库——让 LifeOS 的执行层像树一样：一根共享原语的主干，不断生长出边缘侧的调度枝桠。

想进一步深入，建议依次阅读仓库内的三份文档：ACTIONS 目录说明（本主题的权威入口）、CUSTOMIZATIONS 契约（个人优先覆盖规则与存放边界）、ArbolSystem.md（含 Pipelines、Flows、部署、认证、调优的完整系统文档），以及 PIPELINES 说明 与 FLOWS 说明 了解相邻层级的约定。

【免费下载链接】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