@fieldwangai/agentflow 0.1.149 → 0.1.154

package/skills/agentflow-flow-edit-node-fields/SKILL.md

@@ -1,79 +1,10 @@
 ---
 name: agentflow-flow-edit-node-fields
-description: >-
-  仅修改 AgentFlow flow.yaml 中已有实例的允许字段（label、body、role、
-  input/output 的 value 等）；禁止改 definitionId、instanceId、IO 结构与顺序、
-  不增删边与实例。用于改文案、占位符、角色标签而不破坏图拓扑与 handle。
+description: Legacy Pipeline field editing is retired. Use the Workspace Graph skill for node field changes.
 ---
 
-# AgentFlow：仅修改已有节点（白名单字段）
+# Legacy Flow Node Field Editing（已下线）
 
-在 **不增加/删除节点与边、不改编译拓扑** 的前提下，修改一个或多个 **已有** `instances` 条目时使用本技能。
+此 skill 原用于修改 `flow.yaml` 的实例字段。当前新建和操作统一发生在 Workspace 图中，节点字段应修改 `workspace.flow.js` 的节点调用（见 **agentflow-workspace-graph**），并通过 Workspace 保存/预览链路同步。
 
-**路径说明**：`npx skills add` 后本文件不在 AgentFlow 仓库内；`reference/` 相对 **AgentFlow 仓库根目录**。
-
-**权威参考**：`reference/flow-control-capabilities.md`（内置 description 语义）、`reference/flow-prompt-handler-check.md`（改 `body` 后与图一致）。
-
----
-
-## 允许修改的字段（白名单）
-
-对每个已存在的 **`<instanceId>`** 块，**仅**可改下列内容：
-
-| 字段 | 说明 |
-|------|------|
-| **`label`** | 画布显示名 |
-| **`role`** | 角色分类字符串 |
-| **`body`** | 节点用户区正文（agent 任务描述等）；改后核对与边的数据流是否仍一致 |
-| **`script`** | **仅限 `definitionId: tool_nodejs`**——实际执行的 shell/node 命令（`body` 有 script 时不执行）。必须写完整可执行命令，禁止写自然语言 |
-| **`input[].value`** | 各输入槽的默认值 / 占位路径 / 字面量（**不改** 该项的 `type`、`name`） |
-| **`output[].value`** | 各输出槽默认值（**不改** `type`、`name`） |
-
-### tool_nodejs 特殊规则（关键）
-
-`definitionId: tool_nodejs` 的节点**核心是 `script` 字段**，不是 `body`：
-- **`script`**：流水线直接执行的命令代码，stdout 作为 result，exit code 决定成败
-- **`body`**：有 `script` 时仅作为人类可读的注释说明，**不会被执行**
-- **禁止** `tool_nodejs` 只有 `body` 没有 `script`——自然语言描述不会被执行，节点必定失败
-- 如果无法写出完整可执行的 `script`，必须把 `definitionId` 改为 `agent_subAgent`（此变更不在本技能范围，需用 `agentflow-flow-add-instances` 技能）
-
-**`instances.*.description`** 已废弃：不要在 flow.yaml 中写入；agent 系统说明以 **`definitionId` 对应节点定义 `.md`** 的 frontmatter **`description`** 为准。需要补充说明性文字时用 **`body`** 或 **`label`**。
-
----
-
-## 禁止修改（黑名单）
-
-- **`definitionId`**：换类型会错 handle，须走「新增实例 + 删旧实例 + 改边」流程，**不在**本技能范围。  
-- **`instanceId` 键名**：改名必须同步改 **所有 `edges` 的 source/target** 与 **`ui.nodePositions` 键**，否则图断裂；**不在**本技能范围。  
-- **`input` / `output` 数组**：不得 **增删条目**、**改顺序**、**改 `name` / `type`**（会导致 `input-0` / `output-1` 与边不对应）。  
-- **`edges`**：不得增删改（含 `sourceHandle` / `targetHandle`）。  
-- **新增或删除整个 instance 块**：使用技能 **`agentflow-flow-add-instances`** 或其它流程。  
-- **`ui.nodePositions`**：本技能默认 **不** 改；仅当用户明确要求「只动坐标」时可单独改对应 instance 的 `x` / `y`，且 **不** 改其它字段。
-
----
-
-## 操作建议
-
-1. 用搜索定位目标 **`instanceId`**，只改上表白名单字段。  
-2. 修改 **`body`** 或 **`value`** 后，若涉及「读哪些文件 / 写哪些结果」，对照 **`reference/flow-prompt-handler-check.md`**，确保仍与当前 **edges** 上的 handler 一致（本技能不改边，但若文案宣称的读写与图不符，应提示用户需另改图）。  
-3. 批量改多个节点时，对每个实例重复上述约束，**不要**顺带重构 YAML 结构。
-
----
-
-## 保存后同步 Web UI
-
-将 `flow.yaml` 写入磁盘后，在 **Web UI + Composer** 场景下应通知浏览器刷新画布，见 `skills/agentflow-flow-sync-ui/SKILL.md`。
-
----
-
-## 安装（vercel-labs [skills](https://github.com/vercel-labs/skills)）
-
-在 AgentFlow 仓库根目录：
-
-```bash
-npx skills add ./skills --agent cursor --skill agentflow-flow-edit-node-fields -y
-# 或安装本包全部技能：
-npx skills add ./skills --agent cursor -y
-```
-
-项目内默认 **`.agents/skills/`**；全局加 **`-g`**。
+不要修改 `flow.yaml`、`control_start/control_end` 或调用旧 Pipeline 执行接口来完成新需求。请改用 `agentflow-workspace-graph`。

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

@@ -1,24 +1,13 @@
 ---
 name: agentflow-flow-recipes
-description: >-
-  AgentFlow 常见流程模板。用于新建 Git 项目分析、加载项目 skills、打印结果、
-  以及组合 Git Checkout → CD Workspace → Load Skills → Agent → Print 的标准流水线。
+description: Workspace Graph recipes for AgentFlow canvas tasks (git analysis, display, branching).
 ---
 
-# AgentFlow Flow Recipes
+# Workspace Graph Recipes
 
-使用本技能处理这些问题：
+组合 Git Checkout、CD Workspace、Load Skills、Agent、Display 等节点时，先读
+[recipes.md](references/recipes.md)，在 `workspace.flow.js` 中以 `flow(...)` 为入口组织节点，
+再用 `agentflow-workspace-graph` 校验槽位和连线。
 
-- 用户要求“新建流水线拉仓库、cd 进去、让 agent 分析、print 结果”。
-- 需要把 Git 项目作为工作区分析，并可加载项目自身 skills。
-- 需要避免临场猜 slot/handle，按标准 recipe 搭图。
-
-## 必读规则
-
-- 读 [recipes.md](references/recipes.md)。
-- Git 项目分析的标准链路是：`Start → Git Checkout → CD Workspace → Load Skills → Agent → Print → End`。
-- `tool_print.content` 应接 agent 输出内容；没有接 content 时才 fallback 打印上游 result。
-
-## Reference
-
-- [Flow recipes](references/recipes.md)
+旧的 `Start → … → End` 流水线 recipe 已下线；不得生成 `control_start` / `control_end`
+或其它已退役的节点类型（recipes.md 末尾列出了完整清单）。

package/skills/agentflow-flow-recipes/references/recipes.md

@@ -1,63 +1,117 @@
-# AgentFlow Flow Recipes
+# AgentFlow Workspace Graph Recipes
+
+These recipes are written in `workspace.flow.js` form — the authoritative representation of a
+Workspace graph. Syntax reference: **agentflow-flow-dsl**. The old
+`control_start → … → control_end` pipeline recipes are retired; see the note at the end.
+
+Every pin name below comes from `builtin/nodes/*.md`; the full call table is
+[node-calls.md](../../agentflow-flow-dsl/references/node-calls.md). Run
+`agentflow flow dsl lint <flowDir>` after editing — a wrong pin name is an error, not a warning.
 
 ## Git Project Analysis
 
-Use when the user asks to clone/pull a repository, enter it, ask an agent what it does, and print the result.
+Clone/pull a repository, enter it, ask an agent what it does, show the result.
+
+```js
+import { agent, control, display, flow, tool } from "agentflow/flow";
+
+const checkout = tool.gitCheckout("拉取仓库", {
+  repoUrl: "https://example.com/team/repo.git",
+  pullIfExists: "true",
+});
+
+const cd = control.cdWorkspace("进入仓库", {
+  path: ".",
+  workspaceContext: checkout.workspaceContext,
+});
 
-Recommended graph:
+const skills = control.loadSkills("加载 Skills", {
+  skillKeys: `["global-codex:code-reading"]`,
+});
 
-```text
-control_start
-  -> tool_git_checkout
-  -> control_cd_workspace
-  -> control_load_skills
-  -> agent_subAgent
-  -> tool_print
-  -> control_end
+const analyse = agent.subAgent("解读仓库", {
+  workspaceContext: cd.workspaceContext,
+  skillsContext: skills.skillsContext,
+}, `读 README、构建文件、源码目录和入口，说明这个仓库是做什么的、怎么跑起来。`);
+
+const report = display.markdown("分析结果", { content: analyse.result });
+
+export const run = flow("Run", checkout, cd, skills, analyse, report);
 ```
 
-Minimum required values:
+What the data edges do:
 
-- `tool_git_checkout.repoUrl`: repository URL.
-- `tool_git_checkout.pullIfExists`: `true`.
-- `tool_git_checkout.includeSubmodules`: `true` only when the user asks to pull submodules.
-- `control_cd_workspace.target`: `.`.
-- `control_load_skills.source`: `all` or `current-workspace`.
-- `agent_subAgent.body`: ask the agent to inspect README, package/build files, source directories, and entry points.
-- `tool_print.content`: connect from the agent output content.
+- `checkout.workspaceContext → cd.workspaceContext` — hands the checked-out path to CD
+- `cd.workspaceContext → analyse.workspaceContext` — tells the agent which directory it is in
+- `skills.skillsContext → analyse.skillsContext` — injects the selected skills
 
-Required context edges:
+Watch out:
 
-- Git Checkout `next` -> CD Workspace `prev`
-- Git Checkout `workspaceContext` -> CD Workspace `workspaceContext`
-- CD Workspace `next` -> Load Skills `prev`
-- CD Workspace `workspaceContext` -> Load Skills `workspaceContext`
-- Load Skills `next` -> Agent `prev`
-- CD Workspace `workspaceContext` -> Agent `workspaceContext`
-- Load Skills `skillsContext` -> Agent `skillsContext`
-- Agent content output -> Print `content`
-- Print `next` -> End `prev`
+- `control.cdWorkspace` takes `path`, not `target`; `control.loadSkills` takes `skillKeys`
+  (a JSON array of `collection:skill`), not `source`
+- `control.loadSkills` has no `workspaceContext` input — do not try to chain context through
+  it; feed the agent from `cd` directly
+- Do not wire `checkout.repoPath` (a `file`) into `cd.path` (a `text`)
+- Private repositories need working local credentials
 
-Notes:
+## Show A Result
 
-- Do not connect `repoPath:file` to CD `target:text`.
-- If the agent node has no custom file output slot, use its result body and let Print fallback, or add a text/file output slot intentionally.
-- For private/internal Git repositories, local credentials must already work.
+Feed the producing pin into a `display.*` node:
+
+```js
+const shown = display.markdown("结论", { content: analyse.result });
+```
 
-## Edit Current Flow
+Pick the type that matches the payload: `display.markdown`, `.html`, `.table`, `.chart`,
+`.mermaid`, `.ascii`, `.image`, `.reactApp`.
 
-Use existing flow editing skills:
+An agent with an extra output pin must be declared by destructuring, and its prompt must emit
+the output envelope:
 
-- New nodes/edges: `agentflow-flow-add-instances`
-- Existing node text/value edits only: `agentflow-flow-edit-node-fields`
-- After saving in UI Composer: `agentflow-flow-sync-ui`
+```js
+const { storyId } = breakdown;
+const notify = tool.wecomSendAppMarkdown("通知", { markdown: breakdown.result, toUser: storyId });
+```
 
-## Print Result
+## Branching
 
-Prefer explicit content:
+`control.if` is the branch primitive. Its `prediction` input is a `bool`:
 
-```text
-agent.output.summary -> tool_print.input.content
+```js
+const passed = provide.bool("是否发布", { value: "true" });
+const gate = control.if("是否发布", { prediction: passed.value },
+  flow(publish, notifySuccess),
+  flow(rollback, notifyFail),
+);
+export const run = flow("Run", passed, gate);
 ```
 
-Fallback behavior exists, but explicit content keeps the graph self-documenting.
+The taken branch runs and the other is skipped. **Branches cannot rejoin** — fan-in is
+forbidden and `control_anyOne` has no runtime implementation. Let each branch finish on its own.
+
+`control.agentToBool` also produces a `prediction`, but it is `runtime: degraded`: nothing
+constrains the model's answer and `parse-bool` accepts only exactly `true` / `1` / `yes` / `on`.
+If you use it, the prompt must say "只回 true 或 false，多一个字都会被判成 false".
+
+## No Loops
+
+The run planner rejects cyclic graphs (`Workspace run graph contains a cycle`). Express
+"check → fix → re-check" as forward steps, or put the retry loop **inside** one node — the
+agent's body, a `tool.nodejs` script, or a code node under `nodes/<name>/index.mjs`. Never
+draw an edge from a downstream node back to an upstream one.
+
+## Edit The Graph
+
+- Structure, nodes, edges: **agentflow-workspace-graph**
+- Full syntax and the node call table: **agentflow-flow-dsl**
+- Node implementations in code: `nodes/<name>/index.mjs`, see **agentflow-flow-dsl**
+
+Saving is handled by the Workspace API; there is no separate canvas-sync step.
+
+## Retired
+
+`control_start`, `control_end`, `control_anyOne`, `control_toBool`, `control_interval_loop`,
+`control_delay`, `control_wait_until`, `control_cancelled`, `tool_user_check`, `tool_user_ask`,
+`tool_print`, `tool_load_key`, `tool_save_key`, `tool_get_env` and `tool_jenkins_build` only
+ever ran under the retired Start/End runtime. They are not in the node palette and lint
+rejects them — do not generate them.

package/skills/agentflow-flow-sync-ui/SKILL.md

@@ -1,59 +1,8 @@
 ---
 name: agentflow-flow-sync-ui
-description: >-
-  在 AgentFlow Web UI + Composer 场景下，将 flow.yaml 保存到磁盘后通知本地 UI 刷新画布；
-  使用 POST /api/flow-editor-sync（端口以 Composer 系统提示中的 URL 为准）。
+description: Legacy flow.yaml canvas sync is retired. Workspace Graph saves are synchronized through the Workspace API automatically.
 ---
 
-# AgentFlow：保存 flow.yaml 后同步 Web 画布
+# Legacy Flow Canvas Sync（已下线）
 
-在 **已通过 Composer 编辑当前流水线**（系统提示里已注入 `flowId`、`flowSource`、UI 端口）且 **本机正在运行 `agentflow ui`** 时使用。
-
-## 何时执行
-
-每次对当前流水线的 **`flow.yaml` 做完增删改并已写入磁盘** 后执行 **一次**（含多次保存中的最后一次完成后）。
-
-## 做什么
-
-向本地 Web UI 发通知，让已打开该流水线的浏览器通过 SSE 重拉 `GET /api/flow`（与手动切换流水线效果一致，但保留 Composer 对话区）。
-
-在终端执行（**必须与系统提示中的 `flowId`、`flowSource`、`端口` 一致**；以下占位符在 Composer 上下文中会给出**可复制的一行命令**）：
-
-```bash
-curl -sS -X POST http://127.0.0.1:<PORT>/api/flow-editor-sync \
-  -H 'Content-Type: application/json' \
-  -d '{"flowId":"<flowId>","flowSource":"user"}'
-```
-
-`flowSource` 取值：
-
-- `user`：用户目录 `~/agentflow/pipelines`（或 `AGENTFLOW_HOME`）下的该流水线
-- `workspace`：当前项目下 `.workspace/agentflow/pipelines` 下的该流水线（仍会读取旧路径 `.cursor/agentflow/pipelines`）。同项目内 **nodes** 以 `.workspace/agentflow/nodes` 为主（可读 `.cursor/agentflow/nodes`）；**models.json** 以 `.workspace/agentflow/models.json` 为主（可读 `.cursor` 下旧文件）。
-- `builtin`：包内 `builtin/pipelines` 模板（只读；若实际写入的是工作区副本，须用 `workspace` 触发刷新）
-
-## 等价的 Node one-liner（无 curl 时）
-
-```bash
-node -e "fetch('http://127.0.0.1:<PORT>/api/flow-editor-sync',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({flowId:'<flowId>',flowSource:'user'})}).then(r=>r.text()).then(console.log)"
-```
-
-（将 `<PORT>`、`<flowId>`、`flowSource` 换成实际值。）
-
-## 注意
-
-- 仅 **127.0.0.1** 本地 UI；未启动 UI 时请求会失败，可忽略（Composer 正常结束时前端仍会兜底重拉图一次）。
-- 本操作**不**写入 YAML，只触发刷新；请勿用其代替保存文件。
-
----
-
-## 安装（vercel-labs [skills](https://github.com/vercel-labs/skills)）
-
-在 AgentFlow 仓库根目录：
-
-```bash
-npx skills add ./skills --agent cursor --skill agentflow-flow-sync-ui -y
-# 或安装本包全部技能：
-npx skills add ./skills --agent cursor -y
-```
-
-项目内默认 **`.agents/skills/`**；全局加 **`-g`** → **`~/.cursor/skills/`**。
+旧的 `flow.yaml` + `/api/flow-editor-sync` 刷新链路不再用于新功能。Workspace 图请直接编辑 `workspace.flow.js`（见 **agentflow-workspace-graph**），或使用 Workspace Graph 页面/API 的保存机制；需要所见即所得预览时使用 `agentflow-cli workspace-preview --file <flowDir>`。

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

@@ -0,0 +1,212 @@
+---
+name: agentflow-node-dsl
+description: >-
+  使用 AgentFlow Node DSL 编写代码节点包（节点目录中的 index.mjs），在流程里用起来，并发布到
+  marketplace 供其它流程复用。用户要求「加一个自定义节点」「把这段逻辑做成可复用节点」
+  「把节点发布出去」时使用。跨端搜索、上传、安装和 Flow 拉取/发布需配合
+  agentflow-cli skill。
+---
+
+# AgentFlow Node DSL
+
+**一个目录 = 一个节点 = 一个可发布的包。** `index.mjs` 同时是声明和实现。
+
+```
+<flowDir>/nodes/<name>/index.mjs
+```
+
+行为完全由输入决定、不需要 AI 推理的，就该是代码节点。需要理解和判断的用
+`agent.subAgent`。
+
+## CLI 前置条件
+
+同时安装并读取 `agentflow-cli` skill。把其 `SKILL.md` 所在目录记为
+`<agentflow-cli-skill-dir>`；不要假设当前项目包含 `skills/agentflow-cli`。先执行：
+
+```bash
+node <agentflow-cli-skill-dir>/scripts/agentflow-cli.mjs config
+```
+
+跨端节点操作要求 `localRuntime.available: true` 和有效 token；缺少 companion skill 或本地
+AgentFlow runtime 时先停止并按 `agentflow-cli` 的安装说明修复。
+
+写新包之前，先搜索服务端目录，避免重复造已有节点：
+
+```bash
+node <agentflow-cli-skill-dir>/scripts/agentflow-cli.mjs node-package-search --query "需要的能力"
+```
+
+结果包含固定版本 `specifier` 和输入/输出槽。满足需求时先 `node-package-install`，然后直接
+import 返回的 `marketplace:<id>@<version>`；只有没有合适结果时才创建 `nodes/<name>/`。
+
+## 最小完整例子
+
+```js
+import fs from "node:fs/promises";
+
+export default {
+  id: "count_lines",              // 必填，构成 marketplace:count_lines@1.0.0
+  version: "1.0.0",               // 必填，完整 semver
+  name: "统计行数",
+  description: "读一个文本文件，统计行数",
+  inputs: {
+    filePath: { type: "text", description: "文件路径", required: true },
+  },
+  outputs: {
+    total: { type: "text" },
+  },
+};
+
+export async function run(inputs, outputs, dirs) {
+  const text = await fs.readFile(inputs.filePath, "utf-8");
+  const total = text.split("\n").length;
+  await fs.writeFile(outputs.total, String(total), "utf-8");
+  console.log(`共 ${total} 行`);   // 进度而已
+}
+```
+
+在图里就是一条 import：
+
+```js
+import countLines from "./nodes/count-lines";
+
+const count = countLines("统计行数", { filePath: pick.result });
+const show  = display.markdown("结果", { content: count.total });
+```
+
+## 三条硬约束
+
+**① 声明必须是纯字面量。** `export default` 由 acorn **静态解析**——列节点面板、渲染画布、
+校验槽位、算运行缓存指纹，全程不执行包里的代码。目录扫描期执行第三方代码既慢又不安全。
+
+```js
+const T = "text";
+export default { inputs: { day: { type: T } } };        // ✗ 变量引用
+export default { ...base, id: "x" };                     // ✗ 展开
+export default { version: pkg.version };                 // ✗ 成员访问
+```
+
+违反时带位置报错（`export default.id: 只允许字面量，不允许 Identifier`），不会静默变成空
+清单让节点从面板上消失。
+
+**② `outputs.<name>` 是要写入的绝对路径，不是值。** 最容易搞错的一点。
+
+```js
+await fs.writeFile(outputs.total, String(total));   // ✓
+outputs.total = String(total);                      // ✗ 什么都没发生
+```
+
+每个声明过的输出槽各自一个文件。**第一个非控制输出槽**承载节点的结果正文。stdout 只在你
+**没有**为结果槽写文件时才当结果——所以 `console.log` 打进度不会盖掉你写进去的值。
+
+`file` 类型的输出槽同理，把**文件内容本身**写到 `outputs.<name>` 上：
+
+```js
+await fs.writeFile(outputs.deduped, csvText, "utf-8");            // ✓
+const p = path.join(dirs.outputsDir, "deduped.csv");
+await fs.writeFile(p, csvText); await fs.writeFile(outputs.deduped, p);   // ✗
+```
+
+第二种在测试里看着能过（下游确实拿到一个存在的路径），但槽文件才是被当成产物管理的东西，
+你自选的那个路径在真实运行时位于会被清理的临时目录里。
+
+**③ 槽位顺序 = 画布 handle 顺序。** `inputs` / `outputs` 是有序映射，控制槽 `prev` / `next`
+自动前置。改声明顺序等于改已有流程的接线，加槽位请往后加。
+
+可用类型：`text` `file` `bool` `node` `image` `json`。未知类型直接报错。
+
+## `run(inputs, outputs, dirs)`
+
+| 参数 | 内容 |
+|------|------|
+| `inputs` | 槽位名 → 上游传来的值。`file` 槽拿到的是路径 |
+| `outputs` | 槽位名 → **要写入的绝对路径** |
+| `dirs` | `workspaceRoot` / `nodeRunDir` / `nodeTmpDir` / `outputsDir` |
+
+失败 = 抛异常或非零退出。不要用 JSON 包裹 stdout，也不要自己造结果文件。
+
+`index.mjs` 是**普通 Node 模块**，会被真执行：`for` / `if` / `await` 都可以写。复杂实现可拆到
+包内 `scripts/`，模板和资源可放 `templates/`、`assets/` 并用相对路径加载。不要提交
+`node_modules`；跨端包当前只应依赖 Node 内置模块或包内自带源码。
+和 `workspace.flow.js` 那种「禁一切控制流」的结构文件完全两套规则。
+
+## 验证
+
+```bash
+agentflow flow dsl lint <flowDir>     # 声明能不能静态解析、接线对不对
+```
+
+然后在画布上跑一次。节点会以 `marketplace:<id>@<version>` 出现在面板里。
+
+## 发布给别的流程用
+
+流程自带的 `nodes/<name>/` 只有那个流程能用。要复用就发布：
+
+```bash
+agentflow marketplace publish-node <flowDir>/nodes/<name>
+agentflow marketplace list
+```
+
+包会被复制到 `.workspace/agentflow/marketplace/packages/nodes/<id>/<version>`。
+
+要发给另一台机器或另一个 Agent workspace，上传和安装**整个包目录**：
+
+```bash
+node <agentflow-cli-skill-dir>/scripts/agentflow-cli.mjs node-package-publish --file <flowDir>/nodes/<name>
+node <agentflow-cli-skill-dir>/scripts/agentflow-cli.mjs node-package-install \
+  --node <id>@<version> --workspace-root <targetWorkspace>
+```
+
+流程和本地 `nodes/` 已经一起完成时，优先一键发布，避免漏传包或只传 `index.mjs`：
+
+```bash
+node <agentflow-cli-skill-dir>/scripts/agentflow-cli.mjs publish-flow \
+  --flow-id <flow-id> --file <flowDir> --target-space personal --with-dependencies
+```
+
+命令上传所有包目录，并只在远端发布产物中把 `./nodes/<name>` 改为固定版本 import；本地
+`workspace.flow.js` 保持不变。同版本不同内容会整批在上传前拒绝，必须先提升版本号。
+
+如果已经有 `workspace.flow.js`，直接同步它声明的全部包：
+
+```bash
+node <agentflow-cli-skill-dir>/scripts/agentflow-cli.mjs node-package-sync \
+  --flow <flowDir> --workspace-root <targetWorkspace>
+```
+
+如果流程本身还没落到本地，直接 pull；它会先同步包，再生成本地 DSL：
+
+```bash
+node <agentflow-cli-skill-dir>/scripts/agentflow-cli.mjs pull-flow \
+  --flow-id <flow-id> --flow-source user --workspace-root <targetWorkspace>
+```
+
+传输格式是 ZIP，`scripts/`、`templates/`、`assets/` 都会随包传输；同一个 `id@version` 内容
+不同会被拒绝，修改后必须提升版本号。
+
+解析 `marketplace:<id>@<version>` 的顺序是**流程本地 → 已发布 → 集合**：流程自己的实现永远
+不会被同名的已发布包顶掉。
+
+已安装的包直接在 `workspace.flow.js` 里写版本化 import：
+
+```js
+import myNode from "marketplace:<id>@<version>";
+```
+
+存储层会把它投影成「基础类型 + `marketplaceRef`」，保存后仍保留这条 import。
+
+## 别做的事
+
+- **不要写 `node.yaml`。** 它只是已发布老包的回退清单，新包一律用 `index.mjs`。
+- **不要写 `runtime.entry` / `scripts/run.mjs`。** 那是老 manifest 的字段，现在实现就在
+  `index.mjs` 的 `run` 里。
+- **不要找旧的 `agentflow marketplace install-node`。** 它写的是 `flow.yaml` 依赖钉。跨端安装
+  使用 token-backed CLI 的 `node-package-install`；DSL 用 `marketplace:<id>@<version>` import。
+- **不要用 `agentflow run` / `apply`。** Start/End Pipeline 执行栈已退休，运行走 Workspace。
+- **不要把本机绝对路径或密钥写进包。**
+
+## 相关
+
+- `agentflow-flow-dsl`：图怎么写，import 代码节点的语法
+- `agentflow-node-reference`：内置节点类型的槽位表
+- `docs/wiki/code-node-packages.zh-CN.md`：更完整的说明

package/skills/agentflow-node-dsl/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "AgentFlow Node DSL"
+  short_description: "Create, test, and distribute reusable AgentFlow nodes"
+  default_prompt: "Use $agentflow-node-dsl to create and validate a reusable AgentFlow code node package."

package/skills/agentflow-node-reference/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agentflow-node-reference
 description: >-
-  AgentFlow 内置节点参考。用于选择节点类型、确认 builtin node 的 input/output 槽位、
+  AgentFlow Workspace 节点参考。用于选择节点类型、确认 builtin node 的 input/output 槽位、
   判断 local-only/script/agent 执行方式，以及避免 handle 类型和顺序接错。
 ---
 
@@ -9,13 +9,14 @@ description: >-
 
 使用本技能处理这些问题：
 
-- 选择 `agent_subAgent`、`tool_nodejs`、`tool_git_checkout`、`control_cd_workspace`、`tool_print` 等节点。
-- 创建或修改 flow 时需要确认 input/output 名称、类型、顺序和 handle 索引。
+- 选择 `agent_subAgent`、`tool_nodejs`、`tool_git_checkout`、`control_cd_workspace`、`display_markdown` 等节点。
+- 创建或修改 Workspace Graph 时需要确认 input/output 名称、类型、顺序和 handle 索引。
 - 判断节点是否 local-only，是否会调用 agent，是否需要 `script`。
 
 ## 必读规则
 
-- 先读 [builtin-nodes.md](references/builtin-nodes.md)，再改 `flow.yaml` 的 `definitionId`、`input`、`output` 或 `edges`。
+- 先读 [builtin-nodes.md](references/builtin-nodes.md)，再改 `workspace.flow.js` 的节点调用、引脚和连线；DSL 里的调用名见 **agentflow-flow-dsl** 的 node-calls.md。
+- 新图入口使用 `workspace_run` / `workspace_scheduled_run`，不要新增 `control_start` / `control_end`。
 - `input-N` / `output-N` 必须与节点定义中的槽位顺序一致。
 - `tool_nodejs` 只有写了完整 `script` 才会确定性执行；自然语言任务用 `agent_subAgent`。
 - local-only 节点由 AgentFlow runtime 执行，不会调用 agent。