文档 构建 应用

应用

应用是 Aitroop 中可重复工作的基本单元，把一次性的好对话变成可定时运行的工作流。本页讲创建、运行、编辑、版本管理和分享。

心智模型。一个应用 = 一个表单 + 一组有序的阶段 + 一份输出声明。表单让它具备参数化；阶段让它支持多步骤；输出声明让它可链接、可分享。少了任意一项，它就不再算是一个完整的应用；三项都没有，那就只是聊天而已。

创建应用:四阶段流程

你通过与智能体对话来创建应用。内置的 aitroop-app-create 技能（即应用构建器）每次都会按照结构化的四阶段流程进行。理解这些阶段有助于你引导对话，并预期接下来会发生什么。

阶段 0:理解意图

当你的消息中包含触发词时，应用构建器会激活，并提出 1 到 5 个澄清性问题：

  1. 应用应该做什么？一句话目标。
  2. 它需要哪些输入？自由文本、文件、日期、选项？
  3. 它应该产出什么？报告、代码文件、电子表格、结构化数据？
  4. 有多少步骤 / 阶段？单次智能体调用，还是多阶段流水线？
  5. 需要哪些特定工具或集成？网页搜索、文件处理、OAuth？
把话说具体一点就能跳过提问。如果你的第一条消息已经回答了全部五个问题，应用构建器会直接进入阶段 1。大多数熟练用户会写一段话，一次性覆盖任务 + 输入 + 输出 + 工具。

阶段 1:设计应用

应用构建器会构造完整的 AppDef JSON。它会选定：

  • 名称:根据应用的功能确定，采用标题大小写。
  • 图标:一个匹配使用场景的 emoji。
  • 标签:可搜索的关键词。
  • 输入:为每个变量挑选合适的类型：text 用于短标识符，textarea 用于长内容，select 用于固定选项，daterange 用于时间区间，file 用于上传。
  • 阶段:默认单阶段。仅在工作天然存在可分离步骤时才会拆分为多阶段。
  • 产物:markdown 用于散文，csv 用于表格，json 用于结构化数据，html 用于可渲染页面，image 用于视觉素材，code 用于源文件。
  • 资源:添加应用所需的技能和连接。
  • 超时:默认 3 分钟，重度研究类应用会提到 5-10 分钟。

阶段 2:校验

在保存之前，应用构建器会执行内部检查：

  • 输入、阶段、产物中的每个 id 都唯一。
  • 阶段目标里每一个 {{field_id}} 引用都对应一个真实的输入。
  • 阶段之间的引用（阶段 2 读取阶段 1 的产物）连接正确。
  • 如果应用应该有可见输出，那么至少要有一个阶段产出产物。
  • required: true 只用在真正会阻塞运行的输入上。
  • 目标足够具体：含糊的目标会被改写。

如果校验失败，应用构建器会自行修复问题，而不是反过来问你。只有当校验通过后，你才会看到阶段 3。

阶段 3:通过 API 创建或更新

应用构建器会调用平台的 REST API：

# New App
POST https://app.aitroop.net/api/apps
Authorization: Bearer <AT_USER_TOKEN>
Content-Type: application/json

# Existing App
PUT https://app.aitroop.net/api/apps/<appId>
Authorization: Bearer <AT_USER_TOKEN>
Content-Type: application/json

请求体就是完整的 AppDef JSON。平台会持久化它，分配一个版本号，并返回应用 ID。整个过程你看不到，它在幕后完成。

阶段 4:向用户呈现

应用构建器会反馈以下信息：

  • 应用名称和功能说明。
  • 输入列表及其类型。
  • 阶段列表及其描述。
  • 会产出哪些产物。
  • 应用 ID:便于你后续查找。
  • 提供进一步打磨的选项。

此刻应用就已经上线、可运行，并存在于你的应用库中。

示例：三种复杂度的三个应用

简单:单输入、单阶段

You: Create an app that explains a technical term
in plain English for a non-technical audience. Input is
the term. Output is a 200-word explanation.

Agent: <designs the App, no clarifying questions
needed since you gave inputs+output+length up front>

 App: Plain English Explainer 📖
 Input:  term (text, required)
 Stage:  Explain {{term}} in ~200 words for a
       non-technical audience...
 Output: explanation.md (markdown)

中等:多输入、单阶段，需要一个连接

You: Create an app that summarizes my unread Gmail
from the last N days into a priority-ranked list.

Agent: Two questions:
 1. Default for N (number of days)?
 2. How many emails should the summary cover?

You: Default N=3. Top 20 emails.

Agent: <designs the App>

 App: Email Triage 📧
 Inputs:
   days_back (number, default 3)
   max_emails (number, default 20)
 Stage: Read the last {{days_back}} days of unread Gmail.
       Rank top {{max_emails}} by urgency...
 Output: triage.md (markdown)
 Resources: skills=[], connects=[google]

注意 connects 中的 google。首次运行这个应用时，你会被提示授权 Gmail 访问权限。之后再运行就不会再提示了。

复杂:多阶段并带有人工审核步骤

You: Create an outreach pipeline. Stage 1: find
companies matching an ICP description. Stage 2: enrich
each with public info. Stage 3: I review and remove
rows. Stage 4: draft personalized emails for survivors.

Agent: <asks 3 questions, you answer>

 App: Outreach Pipeline 🎯
 Inputs:
   icp (textarea, required)
   target_count (number, default 30)
 Stages:
   1. find (agent) → leads.csv
   2. enrich (agent) → enriched.csv
   3. review (human, paused until you approve)
   4. draft (agent) → drafts.md
 Resources: skills=[web-search], connects=[]

运行这个应用时，平台会自动执行阶段 1 和阶段 2。阶段 3 会暂停，并在审核面板中展示 enriched.csv。你删除不需要的行后，点击Approve and continue。阶段 4 会以审核后的子集继续运行。

运行应用

从应用库运行

  1. 点击侧边栏的 Apps。
  2. 点击你想运行的应用。
  3. 应用页面会打开，左边是表单，右边是输出占位。
  4. 填写必填字段（带红色星号标记的）。
  5. 可选字段会显示占位提示或预填的默认值。
  6. 点击 Run（位于表单底部的大号按钮）。

运行期间你会看到什么

页面会分屏，右侧面板会填入：

  • 顶部的阶段指示器:"Stage 1 of 3: research_and_write"。
  • 推理轨迹:智能体的计划、工具调用（网页搜索、技能调用）、部分输出。
  • 产物实时预览:智能体在写入产物的同时，你能实时看到它出现。
  • 运行控制:运行过程中，可以使用 Cancel 按钮取消。

运行结束后会发生什么

产物会保存到运行历史。在产物预览面板，你可以：

  • Download:选择一种格式（产物的原生格式，或针对可渲染内容的 PDF/DOCX）。
  • Copy:把原始内容复制到剪贴板。
  • Edit in chat:打开一个针对此产物的新对话，便于快速调整。
  • Share:生成一个指向产物的链接（可见性取决于应用设置）。

未更改的输入

下次再进入应用页面时，表单会自动预填上一次使用的输入。点击字段旁的重置图标（🔄）可以将它清回默认值。

用相同输入重新运行

在任意一次历史运行上，点击 Re-run，即可用相同输入复制一次运行。适用于：刷新时效性数据（例如"最新资讯"类应用）、验证一致性、在不同版本之间做提示词的 A/B 对比。

编辑应用

对话式编辑（推荐用于非琐碎的改动）

  1. 在应用页面，点击 Edit in chat（有时显示为"Chat with this App"）。
  2. 会打开一段对话，并把应用的设计作为上下文加载进来。
  3. 用自然语言告诉智能体你想改什么。例如：
    • "加一个 select 类型的输入用于输出语言，选项为 English / Chinese / Spanish。"
    • "把这一个阶段拆成 'research' 和 'write'，把研究笔记作为上下文传给写作阶段。"
    • "把超时改成 10 分钟。"
    • "删掉 company_url 这个输入。"
  4. 智能体会给你一份差异说明：什么改了、什么没改。
  5. 批准后，智能体会调用 PUT /api/apps/{id}。新版本就此保存。

直接字段编辑（用于快速改动）

  1. 在应用页面，点击 Edit。
  2. 编辑器会打开，所有字段一览无余：名称、图标、标签、输入、阶段、产物、资源。
  3. 直接修改任意字段：
    • 点击某个输入的类型下拉框，把 text 切换为 textarea。
    • 点击某个选项进行重命名。
    • 在目标字段中输入，编辑给智能体的指令。
    • 拖动输入项以重新排序。
  4. 点击 Save。新版本保存。

编辑目标:常见模式

阶段目标承载了应用大部分的行为逻辑。常见的编辑方式：

  • 添加结构:"输出格式：A 部分（一段话） / B 部分（项目符号列表）……"
  • 添加约束:"最多 500 字。""只使用最近 12 个月的来源。"
  • 添加个性化挂钩:"匹配 {{tone}} 中描述的受众语气。"
  • 提升具体性:把模糊动词（"review"）替换为具体动词（"给出 1-10 分并附理由"）。

版本管理

每次保存都会创建一个新版本。版本按 v1、v2、v3…… 编号。应用页面上有一个 Versions 标签页，列出所有版本。

在 Versions 标签页中你可以

  • 查看历史:每个版本的保存时间、保存人、变更摘要。
  • 查看某个版本的完整 AppDef:点击任意版本，查看其完整配置。
  • 对比两个版本:选择两个版本，并排查看差异。
  • 回滚:一键将任意旧版本提升为"当前版本"。当前行为会随之回退；你回滚之前的那个版本仍会保留在历史里。

定时任务与版本管理

定时任务默认使用应用的当前版本。所以如果你周日修复了一个 bug，周一的定时运行就会用上修复后的版本。

若需要稳定性（例如面向客户的报告，不应突然变化），可以把定时任务固定到某个具体版本。被固定的定时任务会忽略后续的应用编辑。

分享与访问

每个应用有三种可见性：

  • Private:只有你能看到和运行。默认。
  • Team:工作区内所有人都能看见。最适合团队共享的内部应用。
  • Public link:任何有链接的人都能运行（具体取决于套餐）。即便如此，每次运行的输入和输出依然各自沙箱化。

团队应用下的按用户连接

当一位团队成员运行一个团队应用时，运行会使用他们自己的连接，而不是你的。一个共享的"每日邮件分诊"应用，由你运行时读取你的 Gmail，由同事运行时读取同事的 Gmail。每个用户都会授权自己的连接。

Fork（复刻）

任何对团队应用有查看权限的人，都可以对它执行 fork:创建一份属于自己的私有副本，并拥有独立的版本历史。适用于"我想要这个应用，但要做点自己的修改"，又不希望影响共享版本的场景。

多阶段应用详解

什么时候该使用多阶段

满足以下任一情形时，可以考虑多阶段：

  • 工作天然可拆分为"先做 X，然后基于 X 的结果做 Y"。
  • 你希望只重跑最后一步，而不必重跑之前那些昂贵的步骤。
  • 中间需要一个人工审批检查点。
  • 某一步需要确定性的转换（在两个 agent 阶段之间插入一个 script 阶段）。

阶段之间如何共享数据

每个阶段的产物都会自动对下一个阶段可用。在下一个阶段的目标中用模板语法引用即可：

# Stage 2 goal referencing Stage 1's artifact
Take the CSV produced by Stage 1 ({{ stages.find.leads }})
and enrich each row with the company's funding history.
Output the same CSV with three new columns:
total_funding, last_round, last_round_date.

三种阶段类型的实际用法

agent:默认类型

智能体读取输入（以及任意先前的产物），使用已安装的技能和已授权的连接，产出声明的产物。最适合：推理、摘要、起草、研究。

script:确定性转换

一个 Python 或 Node 脚本，在沙箱内运行，不调用语言模型。最适合：过滤 CSV、去重、格式转换、精确算术。速度快、可预测。

human:暂停以待审核

运行会暂停。平台向用户展示目标文本和先前的产物。用户可以修改、批准或拒绝。下一个阶段使用人工产出的内容继续运行。最适合：审批检查点、"挑出最好的 N 项"、"发送前修复任何看起来不对的地方"。

实战示例:只重跑最后一个阶段

假设你的三阶段应用顺利跑完了，但最后一个阶段的草稿不理想。为了避免重做阶段 1 和阶段 2：

  1. 从应用的 Runs 标签页中打开该次运行。
  2. 点击 Re-run from stage…
  3. 选择 Stage 3。
  4. 阶段 1 和阶段 2 的产物会被复用，阶段 3 会带着你修过的内容再跑一遍。

从 API 角度看，同样的操作如下：

POST /api/apps/<appId>/run
Content-Type: application/json

{
  "input": { ...same form values as the prior run... },
  "start_from_stage_index": 2,
  "prior_execution_id": "exec_8f4c2e1b"
}

关于完整的执行生命周期、取消、门控和 SSE 流式输出，请参见 执行记录。

通过 API 调用应用

在界面中能做的一切，也都通过 REST 提供。当你想从 webhook、CI 任务、另一个智能体或同事的脚本中触发应用时，这非常有用。

认证

在 Settings → API Tokens → Create 处获取一个 token。把它当作密码:范围最小化、定期轮换、绝不入仓。所有接口都要求：

Authorization: Bearer $AT_USER_TOKEN

核心接口

方法与路径作用
GET /api/apps列出你的所有应用。
POST /api/apps创建一个应用。请求体为完整的 AppDef JSON。
GET /api/apps/:appId获取某个应用的当前定义。
PUT /api/apps/:appId更新（会保存一个新版本）。
DELETE /api/apps/:appId归档应用（30 天内可恢复）。
POST /api/apps/:appId/run触发一次执行。请求体包含 input，以及可选的 is_test、start_from_stage_index、prior_execution_id。
GET /api/app-executions/:execId轮询状态 / 产物。
GET /api/app-executions/:execId/stream实时事件的 SSE 流。
POST /api/app-executions/:execId/cancel停止一次正在运行的执行。

端到端示例：触发应用、等待完成、下载产物

# 1. Trigger the run
EXEC=$(curl -s -X POST \
  https://app.aitroop.net/api/apps/app_8f4c2e1b/run \
  -H "Authorization: Bearer $AT_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "input": { "company_name": "Stripe" } }' \
  | jq -r .id)

# 2. Wait until done (poll, or use SSE)
while true; do
  STATUS=$(curl -s \
    -H "Authorization: Bearer $AT_USER_TOKEN" \
    https://app.aitroop.net/api/app-executions/$EXEC \
    | jq -r .status)
  echo "status: $STATUS"
  [[ "$STATUS" == "completed" || "$STATUS" == "failed" ]] && break
  sleep 5
done

# 3. Download the artifact
ART=$(curl -s -H "Authorization: Bearer $AT_USER_TOKEN" \
  https://app.aitroop.net/api/app-executions/$EXEC/artifacts \
  | jq -r '.[0].id')
curl -s -H "Authorization: Bearer $AT_USER_TOKEN" \
  https://app.aitroop.net/api/artifacts/$ART/download \
  -o brief.md

当应用失败时

常见的失败模式及其诊断方式：

现象可能原因解决办法
超时阶段超过了 timeout_ms调高超时，或拆成两个阶段
"Connect not authorized"所需的连接被撤销在 Settings → Connects 中重新授权
"Required input missing"表单在某个必填字段为空时被提交谨慎设置必填，或修正表单
输出含糊或泛泛目标不够具体编辑目标:添加结构、约束、示例
格式错乱阶段目标要求了一种格式，但声明的是另一种对齐目标与 artifact_defs.format

"Debug in chat" 工作流

  1. 打开失败的运行。
  2. 点击 Debug in chat。
  3. 会打开一段新对话，并带上该次运行的完整上下文：输入、部分产物、智能体的推理轨迹、错误。
  4. 与智能体交流："为什么失败了？我应该改什么？"
  5. 智能体会进行诊断、给出修复建议，并且通常会直接编辑应用以应用修复。
  6. 重新运行。

需要避免的常见错误

  • 目标含糊。"Do research" 太模糊了。要写明来源、深度、输出结构。
  • 缺少产物。一个没有 artifact_defs 的阶段不会产出任何可见内容。
  • 必填项过多。能给默认值的就给。冗长的表单容易被放弃。
  • 超时过短。重度研究需要 5-10 分钟（timeout_ms: 600000）。
  • 输入类型错误。长文本用 textarea，不要用 text。固定选项用 select。
  • 过度拆分。如果在一次对话中它就是一个完整的想法，一个阶段就够了。不要预先拆。
  • 目标过短。两行的目标通常不如一份带结构和约束的 10 行目标好用。

常见问题与排错

我的应用每次运行输出都不一致，怎么收紧？

按以下顺序使用两个杠杆：

  1. 收紧目标。添加带编号的输出结构、字数指标，以及可接受输出的示例。当规范越精确，智能体匹配得就越接近。
  2. 降低模型的自由度。在目标里加上："如果对任何部分不确定，请说 'insufficient data'，而不要猜测。"当被允许时，智能体更愿意给出保守的答复，而不是自信地猜。

对于真正确定性的转换（解析、过滤、格式化），请用 script 阶段替换智能体阶段。

某个阶段可以根据输入跳过自身吗？

可以。在控制它的输入上使用 show_if（例如 "show_if": "include_competitors == true"），并且在目标中使用条件块： {{#if include_competitors}} ... {{/if}}。智能体读取的是未渲染的目标，因此真正告诉它是否要做这项工作的，是这个条件块。

如何把一个应用的输出传给另一个应用？

两种模式：

  • 定时任务 + webhook。让应用 A 的定时任务 POST 到应用 B 的 /run 接口。把产物 URL 作为输入传过去。
  • 通过 script 阶段串联。阶段 1 通过 API 调用应用 A 并读取产物。阶段 2 及之后在同一个应用中继续。

原生的"应用组合"功能已在路线图上。

两个人可以同时编辑同一个应用吗？

勉强可以。每次保存都是一个新版本，所以两人并行编辑不会互相覆盖。但"当前版本"指针归最后保存者所有。对于正在积极开发的团队应用，建议商定一位负责人，或使用对话式编辑（它会通过智能体被串行化）。

如何导出应用的定义？

curl https://app.aitroop.net/api/apps/<appId> \
  -H "Authorization: Bearer $AT_USER_TOKEN" \
  -o my-app.json

把 JSON 保存到 git、分享给同事，或通过 POST /api/apps 粘贴到一个新工作区。

能导入别人导出的应用吗？

可以。打开 Apps → New → Import JSON，粘贴 AppDef，点击保存。平台会校验并在你的工作区中创建应用。所需的技能和连接会被列出来；首次运行时会提示你授权连接。

我的应用目标引用了一个用户尚未授权的连接，会怎样？

平台会在启动沙箱之前就检测到这一点。运行会转为 failed，并附带 connect_unauthorized，指明缺失的提供商。系统会在界面中提示用户授权，之后即可重试。对于定时运行，会提醒该定时任务的所有者。

能否限制谁可以运行应用？

有三种控制方式：

  • 可见性:private / team / public link。
  • 按角色限制运行:按组织角色限制（仅管理员、仅成员）。在 Apps → Settings 下配置。
  • 按用户的连接:即便同事能运行你的应用，运行使用的也是他们自己的 token，而不是你的。
下一篇 技能:智能体可以调用的能力