@metagptx/deepflow-suite-cli 0.2.10 → 0.3.0

package/README.md

@@ -1,72 +1,66 @@
 # `@metagptx/deepflow-suite-cli`
 
-`deepflow-suite` is the published DeepFlow distribution CLI. It is intentionally
-separate from the legacy `@metagptx/deepflow-cli` package, which owns the
-`deepflow` command.
+DeepFlow ships one portable Node package containing `deepflow-suite`, five service
+CLIs and seven Skills. Node.js 22.13+ is required. Users do not need Go, Make, a
+workspace checkout, optional dependencies or an OS-specific runtime package.
 
-## Install
+## Install and check
 
 ```bash
 npm install -g @metagptx/deepflow-suite-cli
-deepflow-suite --help
-deepflow-suite install --source package
-deepflow-suite doctor --source package --json
+deepflow-suite install
+deepflow-suite doctor --json
 ```
 
-The public package includes the `deepflow-suite` entrypoint, the five service
-CLI launchers (`df-workbench`, `df-task`, `df-taskdriver`, `df-agentctrl`, and
-`df-agentrt`), and seven bundled Skills. npm automatically selects the matching
-runtime package for `darwin-arm64`, `darwin-x64`, `linux-arm64`, `linux-x64`, or
-`win32-x64`; the user does not need a DeepFlow checkout, Go, or Make.
-
-`install --source package` copies the seven Skills into `$CODEX_HOME/skills`
-(or `~/.codex/skills`) and verifies all six command launchers plus the selected
-runtime package. `doctor --source package --json` reports the same complete
-distribution check. Use `--target` to choose another Skill directory and
-`--force` only when replacing an existing installation is intentional.
-
-If npm is run with `--omit=optional`, package installation fails before changing
-the Skill directory and reports the missing platform runtime package. Reinstall
-without `--omit=optional` to obtain the four Go-backed CLIs.
-
-## Environment selection
-
-The service Skills cover `local`, `dev`, and domestic production `prod-cn`.
-Select the environment explicitly, then configure the service URL described in
-its Skill; installing the package does not select an environment or log in.
-The package release does not update deployed Runtime images, existing Session
-Skill snapshots, or Agent Control definitions.
+npm registers `deepflow-suite`, `df-workbench`, `df-task`, `df-taskdriver`,
+`df-agentctrl` and `df-agentrt` through `package.json#bin`. The installer copies
+bundled Skills to `$CODEX_HOME/skills` (or `~/.codex/skills`); `--target` chooses
+another Skill directory. Existing regular Skill directories require `--force`.
+Skills contain instructions and references; they rely on Suite-provided commands
+and do not carry CLI implementations. `--source package` remains supported and
+is the default. npm installation does not modify the user's Skill directories.
+
+`doctor` checks the installed Skill contents, all six entrypoints, their Suite
+version, and the command actually selected by PATH. It reports stale commands
+from previous installations without overwriting them. Each service CLI supports
+`--cli-version --json`, separate from Agent definition `--version` arguments.
+`npm install --ignore-scripts --omit=optional` is supported.
+
+Select local/dev/prod explicitly before service calls, then configure the URL
+and identity documented by the relevant Skill. Installation performs no login
+or service calls. CLI releases do not update services, Agent definitions or
+existing Session snapshots.
 
 ## Workspace development
 
-From the DeepFlow workspace, install relative Skill links and build the five
-service CLIs:
+CLI source belongs to each service's `cli/` directory. Suite bundles those
+sources without maintaining another client implementation. Development links
+point directly to Node entries and do not compile services:
 
 ```bash
-deepflow-suite install --source workspace --bin-dir "$HOME/.local/bin"
-deepflow-suite doctor --source workspace --json
+node tools/deepflow-cli/bin/deepflow-suite.js install --source workspace
+node tools/deepflow-cli/bin/deepflow-suite.js doctor --source workspace --json
 ```
 
-The workspace distribution contains `deepflow-suite`, `df-workbench`,
-`df-task`, `df-taskdriver`, `df-agentctrl`, `df-agentrt`, and `df-agentrt-repo`.
-The four Runtime variant Skills (`df-agentrt-full`, `df-agentrt-git`,
-`df-agentrt-ci`, and `df-agentrt-preview`) are selected by Agent definitions
-and are not part of the ordinary distribution.
+Use `--bin-dir` to choose a command directory. Replacing a different existing
+command requires `--force`. The normal Skill set is `deepflow-suite`,
+`df-workbench`, `df-task`, `df-taskdriver`, `df-agentctrl`, `df-agentrt` and
+`df-agentrt-repo`; Runtime-specific variant Skills remain separate.
 
-## Publishing
+## Build and release
 
-The package is prepared for public scoped publication like Console CLI:
+Run service CLI contract tests and Node tests, then:
 
 ```bash
-npm run test
-npm run build:runtime
-npm run check:runtime
-npm run pack:dry-run
+npm test
+npm pack
 npm publish
 ```
 
-Publish the five platform runtime packages before publishing the main package;
-all six entrypoints and platform packages must use the same version. `prepack`
-materializes the seven Skill bundle, the Workbench Node entrypoint, and the
-runtime release metadata. The published installer never overwrites an existing
-Skill or CLI file without `--force`.
+`prepack` gathers the five Node clients and seven Skills and generates release
+metadata from the npm package version. The package has no native build or
+runtime download step. Cross-platform install tests use the same npm tarball.
+Old platform packages remain available for pinned 0.2.x releases; mark them
+deprecated after the portable release is available, rather than unpublishing
+packages still referenced by older versions. The legacy `@metagptx/deepflow-cli`
+package and its `deepflow` command are a separate product entrypoint.

package/bin/deepflow-suite.js

@@ -14,7 +14,7 @@ function parseArgs(argv) {
   const [first, ...rest] = argv;
   const command = first?.startsWith("-") ? undefined : first;
   const argumentsToParse = command ? rest : argv;
-  const options = { source: "workspace", workspaceRoot: process.cwd() };
+  const options = { source: "package", workspaceRoot: process.cwd() };
   for (let index = 0; index < argumentsToParse.length; index += 1) {
     const argument = argumentsToParse[index];
     if (argument === "--source") options.source = argumentsToParse[++index];
@@ -27,14 +27,14 @@ function parseArgs(argv) {
     else if (argument === "--skip-cli") options.skipCli = true;
     else if (argument === "--json") options.json = true;
     else if (argument === "--help" || argument === "-h") options.help = true;
-    else if (argument === "--version" || argument === "-v") options.version = true;
+    else if (argument === "--version" || argument === "--cli-version" || argument === "-v") options.version = true;
     else throw new Error(`unknown option: ${argument}`);
   }
   return { command, options };
 }
 
 function printHelp() {
-  console.log(`${CLI_NAME} — DeepFlow distribution installer\n\nCommands:\n  install --source workspace [--root <path>] [--bin-dir <path>] [--skip-cli]\n  install --source package [--target <path>] [--force]\n  install --source bundle --bundle <path> [--target <path>] [--force]\n  doctor [--root <path>] [--bin-dir <path>]\n  bundle --root <path> --output <path>\n\nUse ${CLI_NAME} --help for this message.`);
+  console.log(`${CLI_NAME} — DeepFlow distribution installer\n\nCommands:\n  install [--target <path>] [--force]  Install bundled Skills; npm provides all five CLIs\n  doctor [--json]                    Check Skills, CLI versions and PATH\n  install --source workspace [--root <path>] [--bin-dir <path>] [--skip-cli]\n  doctor --source workspace [--root <path>] [--bin-dir <path>]\n  bundle --root <path> --output <path>\n\nThe default source is package.`);
 }
 
 function output(value, json) {
@@ -47,7 +47,7 @@ const manifestPath = path.join(packageRoot, "manifest.json");
 
 if (options.version) {
   const packageJson = JSON.parse(await readFile(path.join(packageRoot, "package.json"), "utf8"));
-  console.log(packageJson.version);
+  console.log(options.json ? JSON.stringify({ name: CLI_NAME, version: packageJson.version, entry: fileURLToPath(import.meta.url) }) : packageJson.version);
   process.exit(0);
 }
 

package/bundle/deepflow-release.json

@@ -2,13 +2,13 @@
   "schemaVersion": 1,
   "distribution": "deepflow-suite",
   "package": "@metagptx/deepflow-suite-cli",
-  "version": "0.2.10",
+  "version": "0.3.0",
   "platform": "any",
   "arch": "any",
   "cli": {
     "name": "deepflow-suite",
     "package": "@metagptx/deepflow-suite-cli",
-    "version": "0.2.10",
+    "version": "0.3.0",
     "command": "deepflow-suite"
   },
   "skills": [
@@ -16,15 +16,10 @@
       "name": "deepflow-suite",
       "source": "tools/deepflow-cli/skills/deepflow-suite",
       "files": [
-        {
-          "path": "manifest.yaml",
-          "size": 362,
-          "sha256": "03089402b9a59b0605c582e968226f7868928043daea37d5944468d1f4b41b92"
-        },
         {
           "path": "SKILL.md",
-          "size": 3524,
-          "sha256": "8be45b44925906998ec838dcd46a74e164b8e75572523b4facc7cc5e0e1a3118"
+          "size": 4018,
+          "sha256": "ebd8b217b9ce1ca5dc50024838db41ad8afae08a2bc6d2b2cebd6cd5f46fd0b1"
         }
       ]
     },
@@ -32,15 +27,10 @@
       "name": "df-workbench",
       "source": "deepflow-workbench/skills/df-workbench",
       "files": [
-        {
-          "path": "manifest.yaml",
-          "size": 84,
-          "sha256": "e7e7697d875a49b5d3d4dd4d38fb8479d8a1fb175ab65ab6a2c79addbb171457"
-        },
         {
           "path": "SKILL.md",
-          "size": 5782,
-          "sha256": "a7df787038aa0f47a81da0c6ff28239d793e621c262c5254661009d16c9177fd"
+          "size": 5558,
+          "sha256": "54a13bb845b859f855b94facbb5cd1c6d7721be6dd2ec86dee6e8e7feb2be998"
         }
       ]
     },
@@ -83,35 +73,15 @@
           "size": 4538,
           "sha256": "7b3b288ed60b2222fce168c0d61939a00b9579c523ca7027cc69844a9035553f"
         },
-        {
-          "path": "references/environment.md",
-          "size": 3654,
-          "sha256": "efd881f367692dbfcc15393b9b80a0011f98e50b67b778e8619606f3191b6ce4"
-        },
         {
           "path": "references/fact-types.md",
           "size": 3974,
           "sha256": "5dd10c73e652d018ce20617ec8a5e1becb55fb935f15a366831050063a8989fc"
         },
-        {
-          "path": "references/query-scope.md",
-          "size": 1941,
-          "sha256": "5f8fe18b67b9db77cd64cbf7450fa8fa4d6bf3c1cbb06d1b697029476c516d81"
-        },
-        {
-          "path": "references/reading.md",
-          "size": 1953,
-          "sha256": "94bc4eb79b3f560b5bf0eb1cc728a1b2594dc698de02917f0ea53aea3d9c59f2"
-        },
-        {
-          "path": "skill_test.go",
-          "size": 9146,
-          "sha256": "88dfe1f8104812ff1c9c8dd2c869e116a0774e0972fde7e2bd3329f0b2cd332e"
-        },
         {
           "path": "SKILL.md",
-          "size": 13099,
-          "sha256": "c83eef5901c10a4669d98ee7cf3d210a310bfef021e6aff5a3f1ec0913318ee1"
+          "size": 15851,
+          "sha256": "cf87273902c71c1a66511818397d603cd5e820fb01d211c65be6f818b65ba1f5"
         }
       ]
     },
@@ -121,8 +91,8 @@
       "files": [
         {
           "path": "SKILL.md",
-          "size": 13261,
-          "sha256": "108ad742c99f5299a520954f994c1d969212b945881542a83a6e13d8b4def33d"
+          "size": 13372,
+          "sha256": "8a17db4c0f15a64ed18d05abaf1dcc43688cc58f03e96c1f8dd91d11a862f09f"
         }
       ]
     },
@@ -135,21 +105,11 @@
           "size": 251,
           "sha256": "6c2ab44fe6dc9ea7aa769965d92c71d7367d785a04fd4579e1629452dc4a68ef"
         },
-        {
-          "path": "references/environment.md",
-          "size": 2944,
-          "sha256": "f39554b21c5bd945f60c228002c6cc19067dc2e3472f8095ba68401449ccad10"
-        },
         {
           "path": "references/maintenance.md",
           "size": 5170,
           "sha256": "e303df1eb9849bfe6611e2e6fad37079b5d5934068a66173b8f11efc92343f2a"
         },
-        {
-          "path": "references/query-scope.md",
-          "size": 1739,
-          "sha256": "c9044a12bb9f5b703f25d6b3b4d283e2b5626a6378a86d825b1ed3c02843c5f1"
-        },
         {
           "path": "scripts/to_snapshot.py",
           "size": 833,
@@ -157,8 +117,8 @@
         },
         {
           "path": "SKILL.md",
-          "size": 5120,
-          "sha256": "3d4733fecf8feed798c4870356ae403b97a24214ed3c67fe8a89710640f0373e"
+          "size": 8774,
+          "sha256": "6e23208944de6bb1247a31c4f634a9a5ee6c67e2593cc3149d1075742ec4c077"
         }
       ]
     },
@@ -166,30 +126,10 @@
       "name": "df-agentrt",
       "source": "deepflow-agent-runtime/skills/df-agentrt",
       "files": [
-        {
-          "path": "references/environment.md",
-          "size": 2156,
-          "sha256": "71598b8ba22d69e92eec71fd0f8f00ead49681d3b9466b665696203d303bc5e8"
-        },
-        {
-          "path": "references/invocation-result.md",
-          "size": 1949,
-          "sha256": "5fa8680a74a78fac3a7c67bf1184e2a4b230fd3243a8bab1a0105155d3b8173d"
-        },
-        {
-          "path": "references/query-scope.md",
-          "size": 1484,
-          "sha256": "6ba469d71a3fc0be2905491479644cd5cc8064170c853b703358ec8fb19da760"
-        },
-        {
-          "path": "references/session-create.md",
-          "size": 668,
-          "sha256": "6d31dc9858b72fafd5431ace1073dad8115d9f525bf7aad59bb86705faf1a779"
-        },
         {
           "path": "SKILL.md",
-          "size": 10787,
-          "sha256": "a80b106dd9f2661c794eec40da955a267f20119ec9db89b112982c4d6b3f034e"
+          "size": 12458,
+          "sha256": "aaa0811be96749e3dbf2b640291bedc3251a64a406cee6ac7f6e5f77d9b66307"
         }
       ]
     },
@@ -199,8 +139,8 @@
       "files": [
         {
           "path": "SKILL.md",
-          "size": 3198,
-          "sha256": "1f2e9b3c3631eefc8d0bbf1a3727a0aaf64ea31647da26f22dc025ba0aae996d"
+          "size": 3492,
+          "sha256": "f04a22e7967727217003071b7ad7c9268fde9058af4e1f8d3de22e28e18ac718"
         }
       ]
     }
@@ -209,37 +149,27 @@
     {
       "name": "df-workbench",
       "project": "deepflow-workbench",
-      "install": "project",
-      "package": "@metagptx/deepflow-suite-cli",
-      "mode": "node"
+      "entry": "cli/df-workbench.mjs"
     },
     {
       "name": "df-task",
       "project": "deepflow-task",
-      "install": "make install-cli",
-      "package": "platform-runtime",
-      "mode": "binary"
+      "entry": "cli/df-task.mjs"
     },
     {
       "name": "df-taskdriver",
       "project": "deepflow-task-driver",
-      "install": "make install-cli",
-      "package": "platform-runtime",
-      "mode": "binary"
+      "entry": "cli/df-taskdriver.mjs"
     },
     {
       "name": "df-agentctrl",
       "project": "deepflow-agent-ctrl",
-      "install": "make install-cli",
-      "package": "platform-runtime",
-      "mode": "binary"
+      "entry": "cli/df-agentctrl.mjs"
     },
     {
       "name": "df-agentrt",
       "project": "deepflow-agent-runtime",
-      "install": "make build",
-      "package": "platform-runtime",
-      "mode": "binary"
+      "entry": "cli/df-agentrt.mjs"
     }
   ]
 }

package/bundle/skills/deepflow-suite/SKILL.md

@@ -5,6 +5,10 @@ description: DeepFlow 统一入口。常规任务默认使用 df-workbench；只
 
 # DeepFlow Suite
 
+## CLI 依赖
+
+CLI 由 `@metagptx/deepflow-suite-cli` 统一安装，本 Skill 不携带 CLI 实现。使用前应已完成 Suite 安装；缺少命令或版本不匹配时，用 `deepflow-suite doctor --json` 核对。Run 内缺少工具属于执行环境异常，不临时安装或编译。
+
 这是 DeepFlow 的统一用户和开发者入口。它开放完整的 DeepFlow 能力，但不默认调用整条链路：普通任务先走 `df-workbench`，只有确实需要解释推进、Agent 或 Runtime 问题时才升级到其他项目 CLI。
 
 ## 依赖
@@ -22,7 +26,9 @@ description: DeepFlow 统一入口。常规任务默认使用 df-workbench；只
 
 ## 环境门禁
 
-用户没有明确说 `local`、本地、`dev`、开发环境或 `prod`、生产环境时，先询问：
+以下门禁适用于连接环境内服务。纯离线证据分析、源码审查或能力编写无需选择环境；不能借离线分析自动连接材料里引用的服务。
+
+需要连接服务、用户尚未明确说 `local`、本地、`dev`、开发环境或 `prod`、生产环境时，先询问：
 
 ```text
 请指定目标环境：local（本地）、dev（开发环境）还是 prod（生产环境）？

package/bundle/skills/df-agentctrl/SKILL.md

@@ -5,32 +5,114 @@ description: 使用df-agentctrl CLI查询DeepFlow Agent控制面的可用智能
 
 # DeepFlow Agent Control
 
-通过`df-agentctrl`操作Agent定义和版本。运行命令前确认CLI已在PATH中；服务地址由`DF_AGENTCTRL_BASE_URL`或`--base-url`提供，默认`http://127.0.0.1:8080`。本Skill不安装二进制，也不自动启动服务。
+## CLI 依赖
 
-## 环境与可用性
+CLI 由 `@metagptx/deepflow-suite-cli` 统一安装，本 Skill 不携带 CLI 实现。使用前应已完成 Suite 安装；缺少命令或版本不匹配时，用 `deepflow-suite doctor --json` 核对。Run 内缺少工具属于执行环境异常，不临时安装或编译。
 
-托管 Run 沿用注入的 `DF_AGENTCTRL_BASE_URL` 与当前流程环境，不重新询问、不根据业务项目目标环境切换控制面，缺失/冲突先报告。外部调用先确认 local/dev/prod，再按[环境与地址](references/environment.md)显式选址；未明确先询问，失败不切换，跨服务保持同一环境。先验证 `/healthz`，生产写操作限已有授权。
+通过`df-agentctrl`操作Agent定义和版本。运行命令前确认CLI已在PATH中；服务地址由`DF_AGENTCTRL_BASE_URL`或`--base-url`提供，默认`http://127.0.0.1:8080`。本 Skill 不安装 CLI，也不自动启动服务。
 
-入口为 `df-agentctrl help`。工具缺失属于部署缺口；托管 Run 不安装、编译或猜 Runtime 地址，本地维护安装方法见项目 README。
+## 目标环境门禁与地址
 
-## 查询范围
+每次调用控制面前，必须先确认用户要操作的目标环境。在推进器拉起的 Run 里按下文「Run 内的目标环境」确定，不询问。其他情况下，用户没有明确说 `local`、本地、`dev`、开发环境或 `prod`、生产环境时，先询问：
 
-有业务上下文时使用 `list/get --metadata-source <source> --metadata-query-key <key> --json`，只按已确认的具体来源和 key 过滤；metadata 是软范围，不是权限。需要创建 metadata、共享范围或解释范围内不存在时读[范围说明](references/query-scope.md)。
+```text
+请指定目标环境：local（本地）、dev（开发环境）还是 prod（生产环境）？
+```
+
+环境一旦选定，本轮所有服务调用都必须保持在同一环境；不能因为连接失败就切换到另一环境，也不能把当前机器所在位置当成目标环境。
+
+| 目标环境 | 本地执行时的地址 | 在 dev-k8s 内执行时的地址 |
+| --- | --- | --- |
+| `local` | `http://127.0.0.1:8080` | 不适用 |
+| `dev` | `https://deepflowagentctrl.dev.deepwisdomai.com` | `http://deepflowagentctrl.deepflow.svc.cluster.local:8080` |
+| `prod` | 尚未配置 | 尚未配置 |
+
+地址列描述的是同一目标环境的两种访问方式：本地 CLI 使用 dev Ingress，集群内 Agent 使用 dev Service DNS。确认环境后，可以用用户明确提供的 `--base-url` 覆盖该环境的默认地址，但该地址必须属于已选环境；如果地址与环境冲突，先停止并澄清，不能用它绕过环境门禁。`prod` 目前没有地址，任何 prod 操作都必须停止并说明尚未接入。
+
+本地操作 dev 时示例：
+
+```bash
+df-agentctrl --base-url https://deepflowagentctrl.dev.deepwisdomai.com list --json
+```
+
+### Run 内的目标环境
+
+`DF_TASK_ID`、`DF_RUN_ID`、`DF_TASK_ACTOR_KIND` 都非空时，你运行在推进器拉起的 Run 里，没有用户可以询问。此时目标环境由部署决定：用注入的 `DF_AGENTCTRL_BASE_URL` 对照上表反查所属环境，例如 `http://deepflowagentctrl.deepflow.svc.cluster.local:8080` 即 `dev`。每一轮、每个 Run 都按同一规则确定，不需要也不应该等待任何人确认。
+
+反查不到任何环境、地址属于 `prod`，或指令要求操作的环境与反查结果不一致时，停止，不调用服务、不改用其他地址，在最终回复里说明注入地址和冲突原因。
+
+先请求选定地址的 `GET /healthz`，确认控制面可用后再执行创建、保存、启停或回退。健康检查失败时报告该环境不可达，不得静默改用 localhost 或其他环境。
+
+```bash
+df-agentctrl help
+df-agentctrl list --json
+```
+
+若命令不存在，说明缺少 Suite CLI 安装；向调用方说明需要安装 `@metagptx/deepflow-suite-cli` 并提供控制面地址。不要因为这个Skill是在runtime里加载的，就把runtime地址当作控制面地址。
+
+## 业务 metadata 与软范围查询
+
+Agent 定义可以在创建时携带业务方自定义的 JSON metadata。基础服务只约定顶层的
+`source`、`query_keys` 和 `data`：`source` 与 `query_keys` 用于可选的软范围查询，`data`
+由业务方自行组织，服务不会解释其中字段。
+
+创建时把 metadata 放在快照文件的顶层：
+
+```json
+{
+  "name": "代码评审Agent",
+  "description": "阅读代码变更并给出可操作的评审意见",
+  "instructions": "根据任务提供的代码和上下文完成评审。",
+  "skills": [],
+  "mcp_config": {},
+  "metadata": {
+    "source": "workbench",
+    "query_keys": ["account:u123"],
+    "data": {"project": "orders"}
+  },
+  "change_note": "初始版本"
+}
+```
+
+```bash
+df-agentctrl create --file agent.json --json
+```
+
+有业务上下文时，优先限定目录和读取范围：
+
+```bash
+df-agentctrl list \
+  --metadata-source workbench \
+  --metadata-query-key account:u123 \
+  --json
+df-agentctrl get <agent-id> \
+  --metadata-source workbench \
+  --metadata-query-key account:u123 \
+  --json
+```
+
+查询规则：`query_keys` 可以包含多个标识；`"*"` 表示显式共享，匹配任意来源和查询标识；
+不提供过滤参数仍然查询全部启用Agent（`list`）或按 ID 读取（`get`）。metadata 是查询范围，
+不是权限控制。若按范围 `get` 返回不存在，应同时考虑 Agent 不属于该范围的情况。
+
+metadata 归属于 Agent 定义本身，而不是某个版本。当前 CLI 只有 `create --file` 能在创建时
+写入 metadata；`save` 是版本快照写入，不要把 metadata 加进保存文件，也没有单独修改 metadata
+的命令。保存已有 Agent 时沿用维护说明中的快照格式。
 
 ## 发现与读取
 
 目录的 `description` 应让调度器理解职责、所需输入、产出、完成条件和同一责任的续办范围；这些是定义内容，不是新增控制面字段。维护定义时将角色流程写在执行定义中，不要求调度器硬编码角色名称。选新能力前应先根据 Task 事实确认是否已有承担该目标/产物的 Run；目录描述本身不记录某个 Task 的所有权或 Session 状态。
 
-1. 需要发现新能力时查询 `list --json`（有业务范围则加过滤）。以 `id`、`default_version` 和 `description` 判断输入、输出、职责及完成条件；name 可以重复。目录契约已足够时，不逐个读取 instructions、skills 和 MCP。已有执行的续办依据来自 Task 事实及其固定快照，不是重新发现目录。
-2. 契约不足、约束有歧义或需要审查/维护定义时，再读取选中项的明确版本：
+1. 有业务上下文时使用上面的 metadata 过滤；没有上下文时使用`list --json`保持历史全量行为。根据任务和Agent的`description`选择合适定义；`name`允许重复，身份以`id`为准。
+2. 从选中目录项取`id`和`default_version`，按明确版本读取完整定义：
 
 ```bash
 df-agentctrl get <agent-id> --version <default_version> --json
 ```
 
-3. 执行准备方创建 Session 时仍须读取该固定版本的完整定义，不能拿目录摘要代替 instructions/skills/MCP。默认版本可能并发变化，固定目录版本保证本次选择一致；同一轮已读的固定版本无需重复获取。
+3. 读取响应中的`agent`元数据与`version`定义。定义包含`description`、`instructions`、`skills`、`mcp_config`，以及版本号、时间等元数据。
 
-没有合适 Agent 时如实说明，不为一次查询自动创建或改写定义。检查停用 Agent 用 `list --include-disabled --json`；停用不删除历史。
+需要稳定内容时固定目录返回的具体版本，避免两次请求之间默认版本变化。没有合适Agent时如实说明，不为了完成一次查询就自动新建或改写Agent。需要检查停用Agent时使用`list --include-disabled --json`；停用不删除历史。
 
 ## 职责边界