@fieldwangai/agentflow 0.1.162 → 0.1.163

package/skills/agentflow-flow-dsl/SKILL.md

@@ -82,7 +82,7 @@ Draft → 试运行 → 动态修改 → 明确确认 → 发布/定时流程；
 ## 图结构：workspace.flow.js
 
 ```js
-import { agent, control, display, file, flow, provide, tool } from "agentflow/flow";
+import { agent, context, control, display, file, flow, provide, tool } from "agentflow/flow";
 import collectMetrics from "./nodes/collect-metrics";      // 代码节点
 
 const dateStr = provide.str("查询日期", { value: "2026-08-06" });
@@ -104,6 +104,46 @@ export const run = flow("Run", collect, analyse, chart);
 
 `provide.*` 只是数据源，没有 prev/next 槽，**不要放进 `flow(...)` 链**——被谁引用就跟谁跑。
 
+## Context 资源
+
+知识库、Skills 和可写代码仓属于执行上下文，不是业务数据，也不是控制步骤。使用一等
+`context.*` 资源声明它们，再通过一个强类型 Bundle 连接 Agent：
+
+```js
+const productKnowledge = context.knowledge("Likee 产品知识", {
+  workspaceIds: ["current"], // 内置 ID；其它值必须原样取自 GET /api/workspaces
+});
+
+const developmentSkills = context.skills("研发技能", {
+  skills: ["prd-flow", "agentflow-flow-dsl"],
+});
+
+const codeWorkspace = context.workspace("执行代码仓", {
+  workspaceId: "current",
+  access: "read-write",
+});
+
+const prdContext = context.bundle("PRD 研发上下文", {
+  knowledge: productKnowledge,
+  skills: developmentSkills,
+  workspace: codeWorkspace,
+});
+
+const analyse = agent.subAgent("分析需求", { context: prdContext }, `读取 Context 后分析需求。`);
+export const runWithContext = flow("Run", analyse);
+```
+
+- `context.knowledge / skills / workspace / bundle` 都没有 `prev/next`，不要写进 `flow(...)`。
+  它们通过数据依赖在消费者之前加载。
+- `workspaceIds` 和 `workspaceId` 必须来自当前用户 `GET /api/workspaces` 返回的真实 `id`。不要猜测
+  `knowledge://` URI，也不要把 `path/repoUrl/token` 写入 DSL；路径、仓库与凭证由运行环境按用户解析。
+- Skill key 必须来自 `GET /api/skills`。Flow 只保存 Workspace ID 与 Skill key 这些稳定引用。
+- `agent.subAgent` 优先只接一个 `context:context` 引脚。旧的 `knowledgeContext / skillsContext /
+  workspaceContext / mcpContext` 文本引脚继续兼容，但新流程不要重复连接两套。
+- Bundle 组合的是执行上下文；普通业务字段仍使用单独的数据引脚，不能塞进 Context。
+- 画布手动创建时，从 Provide/Context 分类添加资源节点，把 Knowledge、Skills、Workspace 分别接入
+  Context Bundle，再把 Bundle 的紫色 `context` 输出接到 Agent、Subflow Call 或 While。
+
 ## 四条铁律
 
 1. 节点全部声明在**模块顶层**，不要写进函数
@@ -167,6 +207,8 @@ export const run = flow("Run", read, advance, show);
 - `flow.call(label, subflow, pins)` 是父流程里的真实控制节点，动态引脚由契约生成。
 - 禁止父流程和内部节点直接跨边界连线；所有值必须经过 `flow.call`。
 - 禁止递归调用。当前第一版也不允许子流程内部 `wait/deferred`；调用帧恢复能力补齐前会明确失败。
+- Context 需要跨边界时，显式声明 `const contextIn = flow.input("context", "context")`，加入子流程
+  inputs，并由父图 `flow.call(..., { context: prdContext })` 传入；禁止直接从父图连接内部 Agent。
 
 **`flow.fork` 不是并行。** 它是「一个 `next` 接多个下游」的写法——`flow(a, b, c)` 是线性的，
 没法在链里写出扇出，所以有了它。编译出来就是两条边，图里不存在 fork 这个东西：
@@ -190,6 +232,7 @@ build.next → testB.prev
 
 ```js
 const advance = control.while("推进到人工边界", {
+  context: prdContext,
   state: initial.value,
   maxIterations: "20",
   timeout: "30m",
@@ -200,6 +243,8 @@ export const run4 = flow("Run", advance, report); // done 才继续；wait 会
 - Condition 固定输出 `decision`，Body 固定输出下一版 `state`；两者都可选输出 `summary`。
 - `state` 是用户可见的业务状态载体。`iteration`、`idempotencyKey` 由运行时注入，保留在 DSL
   契约中，但不要要求普通用户在画布上配置或连接。
+- `context` 与 `state` 分离：While 启动时捕获一次 Context，Condition/Body 只有显式声明
+  `flow.input("context", "context")` 才会收到它；Context 不进入 state、history 或 checkpoint。
 - `maxIterations` 和 `timeout` 必须显式设置。新流程不要使用旧的脚本式 While，除非用户要求兼容。
 - Condition/Body 的完整声明、状态迁移、固定输出和手动画布编辑方式都在专项规范中；不要凭记忆简写。
 
@@ -276,7 +321,8 @@ const doc  = display.html("使用说明", { content: file("docs/guide.html") });
 | 一行 shell 就能搞定 | `tool.nodejs("名字", {}, \`node -e "..."\`)` |
 | 给用户看结果 | `display.markdown` / `.code` / `.html` / `.chart` / `.table` |
 | 加载 skills 给下游 agent | `control.loadSkills` → `skillsContext` |
-| 加载知识库 / 代码仓 | `control.cdWorkspace` → `knowledgeContext` |
+| 新流程声明知识库 | `context.knowledge({ workspaceIds })` → Context Bundle |
+| 兼容旧流程加载知识库 / 代码仓 | `control.cdWorkspace` → `knowledgeContext` |
 | 固定文本 / JSON / 密钥 | `provide.str` / `provide.json` / `provide.password` |
 | 文本显式解析为 JSON | `control.parseJson` |
 | 文本转 bool 做分支 | `control.agentToBool` → `prediction` |

package/skills/agentflow-flow-dsl/references/node-calls.md

@@ -7,14 +7,18 @@
 
 | 调用 | 输入引脚 | 输出引脚 |
 |------|----------|----------|
-| `agent.subAgent` | workspaceContext:text, skillsContext:text, mcpContext:text, knowledgeContext:text | result:text |
+| `agent.subAgent` | context:context, workspaceContext:text, skillsContext:text, mcpContext:text, knowledgeContext:text | result:text |
+| `context.bundle` | knowledgeContext:text, skillsContext:text, workspaceContext:text, mcpContext:text | context:context |
+| `context.knowledge` | workspaceIds:json | knowledgeContext:text |
+| `context.skills` | skills:json | skillsContext:text |
+| `context.workspace` | workspaceId:text, access:text | workspaceContext:text |
 | `control.cdWorkspace` | path:text, label:text, knowledgeContext:text, workspaceContext:text | knowledgeContext:text, workspaceContext:text, cwd:file |
 | `control.if` | prediction:bool | — |
 | `control.loadMcp` | serverNames:text | mcpContext:text |
 | `control.loadSkills` | skillKeys:text | skillsContext:text |
 | `control.parseJson` | value:text | result:json |
 | `control.userWorkspace` | — | workspaceContext:text, cwd:file |
-| `control.while` | state:json, maxIterations:text, timeout:text | result:json, state:json, decision:text, iterations:text, summary:text, history:json, checkpointFingerprint:text |
+| `control.while` | context:context, state:json, maxIterations:text, timeout:text | result:json, state:json, decision:text, iterations:text, summary:text, history:json, checkpointFingerprint:text |
 | `display.ascii` | content:text | content:text |
 | `display.chart` | content:text, filePath:file, workspaceContext:text | content:text |
 | `display.code` | content:text, language:text, fileName:text, wrap:bool | content:text |

package/skills/agentflow-flow-dsl/references/subflow-authoring.md

@@ -63,6 +63,25 @@ export const run = flow("Run", callInspect, showSummary);
 - 一个内部节点只能属于一个子流程。禁止直接跨边界连线、跨子流程连线和递归调用。
 - 当前子流程内部不接受 `wait/deferred`。需要暂停 While 时，由 Condition 返回 `wait`。
 
+执行上下文跨子流程时使用强类型契约，不要拆回四根文本线，也不要跨边界直连：
+
+```js
+const contextIn = flow.input("context", "context");
+const inspect = agent.subAgent("分析", { context: contextIn.value }, `使用已授权上下文分析。`);
+
+export const inspectWithContext = flow.subflow(
+  "带上下文的分析",
+  { context: contextIn },
+  flow(inspect),
+  { result: inspect.result },
+);
+
+const callInspect = flow.call("调用分析", inspectWithContext, { context: prdContext });
+```
+
+`context` 只承载知识、Skills、Workspace、MCP 等执行资源；业务参数仍逐项声明。运行时传递已解析
+Bundle，但凭证始终由环境持有，不写入 DSL 或子流程输出。
+
 普通子流程的输出契约可以变化。画布编辑器中把某个内部数据输出拖到 Return 的 `add output`，再命名
 输出；重命名或删除后，所有父图 `SUBFLOW CALL` 的同名输出及相关连线必须同步迁移或移除。
 
@@ -103,33 +122,35 @@ export const run = flow("Run", callInspect, showSummary);
 
 ```js
 const conditionState = flow.input("state", "json");
+const conditionContext = flow.input("context", "context");
 const conditionIteration = flow.input("iteration", "text");
 const check = agent.subAgent(
   "判断是否继续",
-  { state: conditionState.value },
+  { context: conditionContext.value, state: conditionState.value },
   `检查 state。只返回 continue、wait、done 或 fail 之一。`,
 );
 
 export const shouldContinue = flow.subflow(
   "是否继续",
-  { state: conditionState, iteration: conditionIteration },
+  { context: conditionContext, state: conditionState, iteration: conditionIteration },
   flow(check),
   { decision: check.result },
 );
 
 const bodyState = flow.input("state", "json");
+const bodyContext = flow.input("context", "context");
 const bodyIteration = flow.input("iteration", "text");
 const bodyKey = flow.input("idempotencyKey", "text");
 const step = tool.nodejs(
   "推进一轮",
-  { state: bodyState.value, idempotencyKey: bodyKey.value },
+  { context: bodyContext.value, state: bodyState.value, idempotencyKey: bodyKey.value },
   `node ${flowDir}/scripts/advance-one.mjs`,
 );
 const nextState = control.parseJson("校验下一版状态", { value: step.result });
 
 export const advanceOne = flow.subflow(
   "执行一轮",
-  { state: bodyState, iteration: bodyIteration, idempotencyKey: bodyKey },
+  { context: bodyContext, state: bodyState, iteration: bodyIteration, idempotencyKey: bodyKey },
   flow(step, nextState),
   { state: nextState.result },
 );
@@ -138,6 +159,7 @@ const initial = provide.json("初始状态", {
   value: "{\"cursor\":0,\"records\":[],\"valid\":[],\"invalid\":[]}",
 });
 const loop = control.while("逐条处理", {
+  context: prdContext,
   state: initial.value,
   maxIterations: "20",
   timeout: "30m",
@@ -152,8 +174,11 @@ export const run = flow("Run", loop, summarize, report);
 
 | 子流程 | DSL 输入 | DSL 输出 | 产品画布中用户需要理解的部分 |
 |--------|----------|----------|--------------------------------|
-| Condition | `state:json`, `iteration:text` | 必需 `decision:text`；可选 `summary:text` | `state → decision` |
-| Body | `state:json`, `iteration:text`, `idempotencyKey:text` | 必需 `state:json`；可选 `summary:text` | `stateₙ → stateₙ₊₁` |
+| Condition | `state:json`, `iteration:text`；可选 `context:context` | 必需 `decision:text`；可选 `summary:text` | `state → decision` |
+| Body | `state:json`, `iteration:text`, `idempotencyKey:text`；可选 `context:context` | 必需 `state:json`；可选 `summary:text` | `stateₙ → stateₙ₊₁` |
+
+`context:context` 是 Condition/Body 的可选显式输入。While 顶层连接 Context 后，运行时在循环开始时
+捕获一次，并只转发给声明了该输入的子流程。它不属于业务状态，不进入 Return、history 或 checkpoint。
 
 While Return 是固定契约：Condition 只能返回 `decision/summary`，Body 只能返回 `state/summary`。
 不要在 While Return 添加任意顶层变量。普通 Subflow Return 才支持动态输出。
@@ -201,7 +226,9 @@ React 组件名、CSS 类名和像素尺寸属于实现细节，不写入 DSL。
 4. 点击 Body 卡片进入编辑器，连接 Start `state` 到单轮处理节点，最后把完整下一版 JSON 状态连到
    Return `state`；文本结果先经过 `control.parseJson`。
 5. 需要摘要时连接可选 `summary`。不要寻找或手工连接 `iteration/idempotencyKey` 产品引脚。
-6. 返回父图，确认 Condition/Body 卡片、状态流说明和两条调用虚线仍存在。
+6. 需要知识库、Skills 或代码仓时，把 Context Bundle 接到 While 的紫色 `context` 引脚；在需要它的
+   Condition/Body 子图 Start 契约中声明 `context`，再接到内部 Agent。不要把 Context 放进 state。
+7. 返回父图，确认 Condition/Body 卡片、状态流说明和两条调用虚线仍存在。
 
 创建普通子流程时，Start/Return 的控制线和数据线方式相同；区别是 Return 输出可以通过 `add output`
 扩展，父图 SUBFLOW CALL 会同步出现同名输出。

package/skills/agentflow-node-reference/references/builtin-nodes.md

@@ -16,9 +16,9 @@
 ### agent_subAgent
 
 - Display: 子 Agent
-- Description: 利用子 Agent 执行任务；可接收 knowledgeContext 读取知识库，可接收 workspaceContext 切换执行工作区，并接收 skillsContext / mcpContext 注入已加载 skills 与 MCP 工具清单。
+- Description: 利用子 Agent 执行任务；新流程优先接收一个强类型 context Bundle。knowledgeContext、workspaceContext、skillsContext、mcpContext 保留为旧流程兼容引脚。
 - Runtime: agent/runner
-- Inputs: 0. `prev`:node; 1. `workspaceContext`:text; 2. `skillsContext`:text; 3. `mcpContext`:text; 4. `knowledgeContext`:text
+- Inputs: 0. `prev`:node; 1. `context`:context; 2. `workspaceContext`:text; 3. `skillsContext`:text; 4. `mcpContext`:text; 5. `knowledgeContext`:text
 - Outputs: 0. `next`:node; 1. `result`:text
 
 ### workspace_one_click_task
@@ -82,9 +82,9 @@
 ### control_while
 
 - Display: While
-- Description: Repeatedly execute either an explicit Condition/Body subflow pair or one legacy deterministic step command (`script` or `scriptRef`) without adding a cycle to the Workspace graph. A Run restarted after `wait` resumes from the saved output state. Preferred DSL form: `control.while("Advance", { state, maxIterations, timeout }, conditionFlow, bodyFlow)`. Condition must accept `state` and `iteration`, and return `decision` plus optional `summary`. Only `continue` invokes Body. Body must accept `state`, `iteration`, and `idempotencyKey`, and return the next `state` plus optional `summary`. `wait`, `done`, and `fail` skip Body. In legacy script mode, the command runs once per iteration and stdout must be exactly one JSON object: `{"decision":"continue|wait|done|fail","state":{},"summary":"..."}`. `continue` starts another iteration, `wait` pauses this Run before downstream nodes, `done` continues downstream, and `fail` fails the node. A missing `state` keeps the previous state. Each step receives `AGENTFLOW_WHILE_STATE` (JSON), the absolute `AGENTFLOW_WHILE_ITERATION`, `AGENTFLOW_WHILE_MAX_ITERATIONS`, `AGENTFLOW_WHILE_TIMEOUT_MS`, and a stable per-iteration `AGENTFLOW_WHILE_IDEMPOTENCY_KEY`. Pass the idempotency key to external write APIs when they support one. Write progress logs to stderr because stdout is reserved for the decision object. The command also supports the same runtime placeholders as `tool.nodejs`, including `${flowDir}` and `${workspaceRoot}`. A waiting checkpoint retains state, history, elapsed active time, and the next absolute iteration. `maxIterations` and `timeout` are cumulative across resumes. A changed input resets the checkpoint; a matching but malformed checkpoint fails closed. Step output is schema-strict and bounded: unknown fields are rejected, state/stdout are limited to 1 MiB, stderr to 256 KiB, and summary to 4000 characters.
+- Description: Repeatedly execute either an explicit Condition/Body subflow pair or one legacy deterministic step command (`script` or `scriptRef`) without adding a cycle to the Workspace graph. A Run restarted after `wait` resumes from the saved output state. Preferred DSL form: `control.while("Advance", { state, maxIterations, timeout }, conditionFlow, bodyFlow)`. An optional typed `context` input is captured once before iteration and forwarded only to Condition/Body subflows that explicitly declare `flow.input("context", "context")`. Context is never copied into business state, history, or checkpoints. Condition must accept `state` and `iteration`, and return `decision` plus optional `summary`. Only `continue` invokes Body. Body must accept `state`, `iteration`, and `idempotencyKey`, and return the next `state` plus optional `summary`. `wait`, `done`, and `fail` skip Body. In legacy script mode, the command runs once per iteration and stdout must be exactly one JSON object: `{"decision":"continue|wait|done|fail","state":{},"summary":"..."}`. `continue` starts another iteration, `wait` pauses this Run before downstream nodes, `done` continues downstream, and `fail` fails the node. A missing `state` keeps the previous state. Each step receives `AGENTFLOW_WHILE_STATE` (JSON), the absolute `AGENTFLOW_WHILE_ITERATION`, `AGENTFLOW_WHILE_MAX_ITERATIONS`, `AGENTFLOW_WHILE_TIMEOUT_MS`, and a stable per-iteration `AGENTFLOW_WHILE_IDEMPOTENCY_KEY`. Pass the idempotency key to external write APIs when they support one. Write progress logs to stderr because stdout is reserved for the decision object. The command also supports the same runtime placeholders as `tool.nodejs`, including `${flowDir}` and `${workspaceRoot}`. A waiting checkpoint retains state, history, elapsed active time, and the next absolute iteration. `maxIterations` and `timeout` are cumulative across resumes. A changed input resets the checkpoint; a matching but malformed checkpoint fails closed. Step output is schema-strict and bounded: unknown fields are rejected, state/stdout are limited to 1 MiB, stderr to 256 KiB, and summary to 4000 characters.
 - Runtime: bounded Condition/Body state machine
-- Inputs: 0. `prev`:node; 1. `state`:json = null; 2. `maxIterations`:text = 20; 3. `timeout`:text = 30m
+- Inputs: 0. `prev`:node; 1. `context`:context; 2. `state`:json = null; 3. `maxIterations`:text = 20; 4. `timeout`:text = 30m
 - Outputs: 0. `next`:node; 1. `result`:json; 2. `state`:json = null; 3. `decision`:text; 4. `iterations`:text = 0; 5. `summary`:text; 6. `history`:json = []; 7. `checkpointFingerprint`:text
 
 ### workspace_run
@@ -124,7 +124,7 @@
 ### tool_git_worktree_load
 
 - Display: Load Worktree
-- Description: Create or reuse a Git worktree and expose it as the downstream workspace context. - `repoPath` is required unless `gitContext.repoPath` is connected. - `workspaceContext` is required so the node can preserve the previous execution context. - `branch` is optional. When empty, AgentFlow creates a detached worktree at the current HEAD. - `worktreePath` is optional. When empty, AgentFlow creates a temporary worktree under the current run temp directory. - A worktree created by this node during the current Workspace run is removed when the run finishes or is stopped, even when `worktreePath` is explicitly set. - Existing registered worktrees under the current flow workspace are also removed after the run, covering leftovers from previous interrupted runs. - Existing registered worktrees outside the current flow workspace are reused and not removed automatically unless this run created them. - Existing worktree paths are reused only when they are registered by `git worktree list` for the given repo. - `pruneMissing` defaults to true. When Git has a registered worktree whose directory is missing, AgentFlow runs `git worktree prune` before adding it again. - `force` defaults to false. When true, AgentFlow passes `--force` to `git worktree add`.
+- Description: Create or reuse a Git worktree and expose it as the downstream workspace context. - `repoPath` is required unless `gitContext.repoPath` is connected. - `workspaceContext` is required so the node can preserve the previous execution context. - `branch` is optional. When empty, AgentFlow creates a detached worktree at the current HEAD. - `worktreePath` is optional. When empty, AgentFlow creates a managed execution worktree under `.workspace/agentflow/run-workspaces/`, separate from node temp files and durable `outputs/` artifacts. - A `wait` checkpoint retains the execution worktree. The next run reuses the retained output path so loop state and code changes remain available while resuming. - On terminal completion or stop, AgentFlow removes clean managed worktrees. Dirty worktrees are preserved with a warning instead of being force-deleted. - Existing registered worktrees under the current flow workspace are managed by the same lifecycle policy. - Existing registered worktrees outside the current flow workspace are reused and not removed automatically unless this run created them. - Existing worktree paths are reused only when they are registered by `git worktree list` for the given repo. - `pruneMissing` defaults to true. When Git has a registered worktree whose directory is missing, AgentFlow runs `git worktree prune` before adding it again. - `force` defaults to false. When true, AgentFlow passes `--force` to `git worktree add`.
 - Runtime: local-only
 - Inputs: 0. `prev`:node; 1. `repoPath`:file; 2. `branch`:text; 3. `worktreePath`:file; 4. `pruneMissing`:bool = true; 5. `force`:bool = false; 6. `gitContext`:text; 7. `workspaceContext`:text
 - Outputs: 0. `next`:node; 1. `worktreePath`:file; 2. `branch`:text; 3. `commit`:text; 4. `workspaceContext`:text; 5. `gitContext`:text
@@ -261,6 +261,38 @@
 
 ## provide
 
+### context_bundle
+
+- Display: Context Bundle
+- Description: Compose knowledge, skills, workspace, and MCP resources into one strongly typed Context value that can cross Agent, Subflow, and While boundaries.
+- Runtime: local-only
+- Inputs: 0. `knowledgeContext`:text; 1. `skillsContext`:text; 2. `workspaceContext`:text; 3. `mcpContext`:text
+- Outputs: 0. `context`:context
+
+### context_knowledge
+
+- Display: Knowledge Context
+- Description: Select one or more read-only knowledge sources by their authenticated Workspace catalog IDs. The runtime resolves IDs from the same catalog as GET /api/workspaces; paths and credentials are not stored in Flow DSL.
+- Runtime: local-only
+- Inputs: 0. `workspaceIds`:json = []
+- Outputs: 0. `knowledgeContext`:text
+
+### context_skills
+
+- Display: Skills Context
+- Description: Declare versioned skills as a reusable Context resource. This is a data resource and does not participate in the prev/next control chain.
+- Runtime: local-only
+- Inputs: 0. `skills`:json = []
+- Outputs: 0. `skillsContext`:text
+
+### context_workspace
+
+- Display: Workspace Context
+- Description: Bind one authenticated Workspace catalog entry as execution context. The Flow stores only workspaceId; paths and credentials remain runtime-owned.
+- Runtime: local-only
+- Inputs: 0. `workspaceId`:text = current; 1. `access`:text = read-write
+- Outputs: 0. `workspaceContext`:text
+
 ### provide_bool
 
 - Display: Boolean