#Loom 设计原则

Loom 把一类工作的目标、判断、操作、人工决策和正式结果组织成可以重复执行的流程。设计良好的 Loom 既能推进本轮工作，也能留下后续工作可以理解和使用的事实。

本文面向 Loom 开发者，说明职责划分与设计方法。具体接口以 @intloom/loom-sdk 为准；某个业务 Loom 的阶段和数据规则由它自己的契约定义。Intent 的四阶段流程是一种应用，不是所有 Loom 必须遵循的模板。

#先定义业务契约，再组织执行步骤

开始编写 Agent、Skill 或 Stage YAML 前，先为每个阶段回答下面的问题。涉及用户目标、业务边界和正式结果的选择，应当先与需求方确认。

“Agent 已回答”不等于“阶段已完成”。完成应对应可检查的业务条件和必要的提交结果。

Loom 从 SDK 支持的 prompt、files、dirs、urls 中声明所需输入。业务偏好和约束属于输入及后续业务产物；模型、连接和执行环境由宿主管理。

#将职责放到合适的位置

Agent 指令可以简洁，但实际 Agent Step 还需要绑定模型用途、Tools、Skills 和输出契约。业务角色与模型用途分别定义：角色描述工作，thinking、working、coding 表达优先使用的通用模型用途。

Skill 应保留具体的方法。例如，需求澄清 Skill 可以教开发者如何区分事实、假设和未回答问题；验收 Skill 可以说明什么证据足以支持结论。业务概念可以出现在 Skill 中，内部 Artifact 序列化结构、Record ID 和提交事务不应成为它的主要内容。

调用者必须知道的约束放在 Tool 描述或 Schema 字段说明中。将版本、哈希、统计、来源记录等可确定计算的信息交给 Code；业务引用和变更理由仍应由理解任务的一方明确提供。

#用显式流程组织需要判断的工作

当下一项工作需要不同的上下文、权限、产出或用户决定时，再拆分 Step。不要为每个字段、工具调用或思考动作都增加一次模型调用，也不要求所有阶段具有相同的 Step 数量。

常见组合是：准备上下文 → Agent 形成业务提案 → Code 核验 → 必要的人工确认 → 提交。澄清、修正和失败通过明确分支表达；不需要模型判断的任务可以完全由 Code 完成。

按任务赋予能力。例如，评估交付的 Step 通常只需要读取和评估工具，修改产品的 Step 才需要写入能力。角色提示词中的“禁止修改”不能替代能力配置。

提案修正应有明确反馈、次数边界和停止条件。区分可修正的提案错误、真实业务失败和执行故障，不能通过不断重试或放松检查来制造完成。

#分开设计提案、运行状态和正式结果

Agent 面向业务提交提案，Code 负责将它转成可信的正式数据。Tool 的编辑接口可以只暴露可编辑字段，不必直接复用完整的持久化结构；已知的上下文与返回值应有明确 Schema。

• State 保存本阶段的临时工作，包括草稿、固定基线、反馈和等待状态。
• Record 保存一次业务执行产生的正式事实。已有内容不应被后续运行改写。
• Artifact 保存当前正式业务结果或累计视图，并能说明其依据。

根据业务选择需要哪些产出，不要求每个阶段同时产生 Artifact 和 Record。跨阶段交接使用明确的正式结果及其身份、版本，避免依赖另一个阶段的临时 State。

人工答案、确认、命令结果和文件事实由实际交互及操作产生。模型的声明不能替代它们。用户确认应绑定具体候选及其依据；候选发生实质变化后，需要重新检查并确认。

#累计结果必须说明历史与有效性

需要维护长期状态时，可以保存本轮 Record，并由有明确顺序的 Record 累计生成 Artifact。合并规则由业务 Loom 定义，不能简单拼接报告，也不能隐含地用最新一轮覆盖全部历史。

设计时明确：

• 对象如何保持身份，新结果如何更新同一对象。
• 未被本轮覆盖的对象如何保留历史结论。
• 依据变化后，哪些结论需要重新验证；无法判断影响时如何保守处理。
• 问题如何关闭，删除或退役的对象如何保留可理解的历史。
• 哪些结论属于本轮，哪些来自过去，汇总统计覆盖什么范围。

例如，某功能上一轮通过验收，本轮没有检查它，只能保留其历史结论。相关实现改变时，还需要判断该结论是否继续适用。新报告没有提到某个问题，也不意味着问题已经解决。

如果 Artifact 由 Record 派生，应保留从完整记录序列重建它的能力。Record 与对应 Artifact 更新应在同一 Storage 事务内提交，并处理重复提交和版本冲突。这个事务不包含项目文件修改和外部副作用；应另行定义这些操作的失败与恢复边界。

#完成需要与任务匹配的证据

结构校验、工程检查、业务目标满足和整体质量是不同判断。Schema 合法不能证明需求合理；命令通过不能证明全部验收条件满足。

评估类阶段可以成功完成一份结论为失败、部分完成或证据不足的报告。应分别表达“评估工作完成”和“被评估对象通过”。执行中断而没有形成有效业务结果时，保留运行诊断，不能伪造正式结论。

证据应能定位到实际对象、操作或结果，并说明适用版本和覆盖范围。无法取得证据时，明确保留不确定性。

#让代码组织反映职责

Loom 定义放在 package.json 的 loom 字段；阶段资源放在各自目录。只有确实跨阶段复用、职责稳定的逻辑才上提到根级 src/。

package.json                 # loom 元数据、输入与阶段拓扑
src/                         # 跨阶段共享逻辑与契约
stages/
  <stage>/
    stage.yaml               # Step 编排与能力配置
    agents/                  # 角色指令
    skills/                  # 可复用方法及参考资料
    tools/                   # Agent 可调用的业务操作
    schema/                  # 本阶段上下文、提案、状态与产出契约
    codes/                   # 可执行 Code Steps
    src/                     # 本阶段业务规则与辅助逻辑

目录按实际需要创建。开发者使用 intloom build [path] 构建包，省略路径时使用当前目录；用户通过 intloom loom 管理构建后的包。构建、安装与执行分别承担不同职责。

扩展优先发生在具体 Loom 内。只有多个实际用例需要相同能力时，才考虑将其纳入 SDK；不要把某个 Loom 的业务模型变成所有 Loom 的共同负担。

#定义参考

这些是 IntLoom 的设计原则，参考了 OpenAI Agent 定义、OpenAI Skills、OpenAI 工具契约、Anthropic Skills 和 Anthropic 对 Workflow 与 Agent 的架构区分。正式提交、累计视图与阶段交接的具体规则由各 Loom 自己定义。