@metagptx/deepflow-suite-cli 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,49 @@
-# Temporary Holding Version
+# `@metagptx/deepflow-suite-cli`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`deepflow-suite` is the published DeepFlow distribution CLI. It is intentionally
+separate from the legacy `@metagptx/deepflow-cli` package, which owns the
+`deepflow` command.
+
+## Install
+
+```bash
+npm install -g @metagptx/deepflow-suite-cli
+deepflow-suite --help
+deepflow-suite install --source package
+deepflow-suite doctor --source package --json
+```
+
+The package installation mode copies the seven bundled Skills into
+`$CODEX_HOME/skills` (or `~/.codex/skills`). Use `--target` to choose another
+Skill directory and `--force` only when replacing an existing installation is
+intentional.
+
+## Workspace development
+
+From the DeepFlow workspace, install relative Skill links and build the five
+service CLIs:
+
+```bash
+deepflow-suite install --source workspace --bin-dir "$HOME/.local/bin"
+deepflow-suite 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 three Runtime variant Skills (`df-agentrt-full`, `df-agentrt-git`, and
+`df-agentrt-preview`) remain service-local and are not part of the ordinary
+distribution.
+
+## Publishing
+
+The package is prepared for public scoped publication like Console CLI:
+
+```bash
+npm run test
+npm run pack:dry-run
+npm publish
+```
+
+`prepack` materializes the seven Skill bundle and its release manifest. The
+published `deepflow-suite` command never overwrites an existing Skill or CLI
+file without `--force`.

package/bin/deepflow-suite.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { readFile } from "node:fs/promises";
+
+import { assembleBundle } from "../src/bundle.mjs";
+import { installBundleSkills } from "../src/bundle-installer.mjs";
+import { CLI_NAME, defaultCodexSkillsDir } from "../src/constants.mjs";
+import { doctor } from "../src/commands/doctor.mjs";
+import { install } from "../src/commands/install.mjs";
+
+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() };
+  for (let index = 0; index < argumentsToParse.length; index += 1) {
+    const argument = argumentsToParse[index];
+    if (argument === "--source") options.source = argumentsToParse[++index];
+    else if (argument === "--root") options.workspaceRoot = path.resolve(argumentsToParse[++index]);
+    else if (argument === "--output") options.outputDir = path.resolve(argumentsToParse[++index]);
+    else if (argument === "--bundle") options.bundleDir = path.resolve(argumentsToParse[++index]);
+    else if (argument === "--target") options.targetDir = path.resolve(argumentsToParse[++index]);
+    else if (argument === "--bin-dir") options.binDir = path.resolve(argumentsToParse[++index]);
+    else if (argument === "--force") options.force = true;
+    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 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.`);
+}
+
+function output(value, json) {
+  console.log(json ? JSON.stringify(value, null, 2) : JSON.stringify(value));
+}
+
+const { command, options } = parseArgs(process.argv.slice(2));
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+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);
+  process.exit(0);
+}
+
+if (!command || options.help) {
+  printHelp();
+  process.exit(0);
+}
+
+try {
+  const result = command === "install" && options.source === "bundle"
+    ? await installBundleSkills({
+      ...options,
+      targetDir: options.targetDir ?? defaultCodexSkillsDir(),
+    })
+    : command === "install"
+      ? await install({ ...options, manifestPath })
+      : command === "doctor"
+        ? await doctor({ ...options, manifestPath })
+        : command === "bundle"
+          ? await assembleBundle({ ...options, manifestPath })
+          : (() => { throw new Error(`unknown command: ${command}`); })();
+  output(result, options.json);
+  if (command === "doctor" && !result.ok) process.exitCode = 1;
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 1;
+}

package/bundle/deepflow-release.json

@@ -0,0 +1,185 @@
+{
+  "schemaVersion": 1,
+  "distribution": "deepflow-suite",
+  "package": "@metagptx/deepflow-suite-cli",
+  "version": "0.1.1",
+  "platform": "darwin",
+  "arch": "arm64",
+  "cli": {
+    "name": "deepflow-suite",
+    "package": "@metagptx/deepflow-suite-cli",
+    "version": "0.1.1",
+    "command": "deepflow-suite"
+  },
+  "skills": [
+    {
+      "name": "deepflow-suite",
+      "source": "tools/deepflow-cli/skills/deepflow-suite",
+      "files": [
+        {
+          "path": "manifest.yaml",
+          "size": 362,
+          "sha256": "35e52b807171fa954b465853732740faaa37ab2f4a798f5e10f6f3dc101ae167"
+        },
+        {
+          "path": "SKILL.md",
+          "size": 3054,
+          "sha256": "39fd13809264aa2fa83b535c604c3a83511748f51be6a8b2fb52be3682f31481"
+        }
+      ]
+    },
+    {
+      "name": "df-workbench",
+      "source": "deepflow-workbench/skills/df-workbench",
+      "files": [
+        {
+          "path": "manifest.yaml",
+          "size": 84,
+          "sha256": "e7e7697d875a49b5d3d4dd4d38fb8479d8a1fb175ab65ab6a2c79addbb171457"
+        },
+        {
+          "path": "SKILL.md",
+          "size": 2758,
+          "sha256": "c86ee01f8b130669f87efc223ffdeff96841a89037c39738eaf8730bdd58091b"
+        }
+      ]
+    },
+    {
+      "name": "df-task",
+      "source": "deepflow-task/skills/df-task",
+      "files": [
+        {
+          "path": "assets/payload-examples/adjudication.json",
+          "size": 142,
+          "sha256": "fec652168ca886b43ac2ba635343c0d98d316f40cb1f5e4c9d1d8582cebe141f"
+        },
+        {
+          "path": "assets/payload-examples/artifact_published.json",
+          "size": 159,
+          "sha256": "1e766567855af8a89f424c9248b0dada83ca0773a9d4006f7b44a7771a153cd5"
+        },
+        {
+          "path": "assets/payload-examples/help_requested.json",
+          "size": 164,
+          "sha256": "cd4e79ae2e4698d7e46ceadb006e0518139ed85e768cd160ea75d64cb0fc53f0"
+        },
+        {
+          "path": "assets/payload-examples/run_outcome.json",
+          "size": 167,
+          "sha256": "43c4de8531d455af3bc908e70b287218f0bc464417f29f5213da2477c2485086"
+        },
+        {
+          "path": "assets/payload-examples/run_terminated.json",
+          "size": 88,
+          "sha256": "df880d0c9dcce614af6869d684c038592720246b45484d4274572d59ff842a99"
+        },
+        {
+          "path": "assets/payload-examples/summary.json",
+          "size": 198,
+          "sha256": "c8954184c2b3454a7b11d1089555374068ac44fb50d4f476ddf498d188ab988c"
+        },
+        {
+          "path": "references/fact-types.md",
+          "size": 3353,
+          "sha256": "37c13c13822734744d9f4a73710e1206009eeb037102620ccdb77af78e1dcb39"
+        },
+        {
+          "path": "skill_test.go",
+          "size": 9132,
+          "sha256": "fc4f7b01d9641e74d26093f552be28c16b99f132ef77cc9f79a48efbca85a3c3"
+        },
+        {
+          "path": "SKILL.md",
+          "size": 12155,
+          "sha256": "aec1bb832519f6503b9e17cbe34bf4ff39bac451f57912d5cd42de1a3e2e77e2"
+        }
+      ]
+    },
+    {
+      "name": "df-taskdriver",
+      "source": "deepflow-task-driver/skills/df-taskdriver",
+      "files": [
+        {
+          "path": "SKILL.md",
+          "size": 13110,
+          "sha256": "8e547dca84792272cdfbad841a162dce6f98d6e13e440f6db60763a559d4d823"
+        }
+      ]
+    },
+    {
+      "name": "df-agentctrl",
+      "source": "deepflow-agent-ctrl/skills/df-agentctrl",
+      "files": [
+        {
+          "path": "assets/agent.json",
+          "size": 251,
+          "sha256": "6c2ab44fe6dc9ea7aa769965d92c71d7367d785a04fd4579e1629452dc4a68ef"
+        },
+        {
+          "path": "references/maintenance.md",
+          "size": 3388,
+          "sha256": "ba0bfb12eba04bb6be090b43180a3dc672584e9ec63142fd3671755b57e27375"
+        },
+        {
+          "path": "scripts/to_snapshot.py",
+          "size": 833,
+          "sha256": "d532da019f9e2112e86b5f68ac6f8ad4b3351d806b924750ac1299dce76c6988"
+        },
+        {
+          "path": "SKILL.md",
+          "size": 8078,
+          "sha256": "72f692d4daed01c78a360bc7cd4e541a66d1f23e7b3b43df4836c02eae9d5efd"
+        }
+      ]
+    },
+    {
+      "name": "df-agentrt",
+      "source": "deepflow-agent-runtime/skills/df-agentrt",
+      "files": [
+        {
+          "path": "SKILL.md",
+          "size": 10079,
+          "sha256": "f1d8abb45c3bd7010b01a89393a16c143ed5718b092af9804f2fd849a2274f68"
+        }
+      ]
+    },
+    {
+      "name": "df-agentrt-repo",
+      "source": "deepflow-agent-runtime/skills/df-agentrt-repo",
+      "files": [
+        {
+          "path": "SKILL.md",
+          "size": 3198,
+          "sha256": "1f2e9b3c3631eefc8d0bbf1a3727a0aaf64ea31647da26f22dc025ba0aae996d"
+        }
+      ]
+    }
+  ],
+  "clis": [
+    {
+      "name": "df-workbench",
+      "project": "deepflow-workbench",
+      "install": "project"
+    },
+    {
+      "name": "df-task",
+      "project": "deepflow-task",
+      "install": "make install-cli"
+    },
+    {
+      "name": "df-taskdriver",
+      "project": "deepflow-task-driver",
+      "install": "make install-cli"
+    },
+    {
+      "name": "df-agentctrl",
+      "project": "deepflow-agent-ctrl",
+      "install": "make install-cli"
+    },
+    {
+      "name": "df-agentrt",
+      "project": "deepflow-agent-runtime",
+      "install": "make build"
+    }
+  ]
+}

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

@@ -0,0 +1,79 @@
+---
+name: deepflow-suite
+description: DeepFlow 统一入口。常规任务默认使用 df-workbench；只有用户明确要求或 Workbench 事实无法解释阻塞时，才按顺序检查 Task、Task Driver、Agent Control 和 Agent Runtime。
+---
+
+# DeepFlow Suite
+
+这是 DeepFlow 的统一用户和开发者入口。它开放完整的 DeepFlow 能力，但不默认调用整条链路：普通任务先走 `df-workbench`，只有确实需要解释推进、Agent 或 Runtime 问题时才升级到其他项目 CLI。
+
+## 依赖
+
+本 Skill 依赖以下项目级 Skill 和 CLI：
+
+- `df-workbench`：用户身份、工作区、Workbench 配置和任务事实；
+- `df-task`：Task 原始事实和事实落库核对；
+- `df-taskdriver`：任务推进和唤起兑现诊断；
+- `df-agentctrl`：Agent 定义、版本和可分配目录；
+- `df-agentrt`：Session、Invocation、transcript 和运行现场。
+- `df-agentrt-repo`：在 Runtime 会话中发现和追加代码仓库。
+
+这些依赖由 `deepflow-suite` 安装器统一安装。不要因为某个依赖缺失就自行复制 Skill、克隆仓库或切换安装源。
+
+## 环境门禁
+
+用户没有明确说 `local`、本地、`dev`、开发环境或 `prod`、生产环境时，先询问：
+
+```text
+请指定目标环境：local（本地）、dev（开发环境）还是 prod（生产环境）？
+```
+
+环境一旦选定，本轮所有 Workbench、Task、Driver、Agent Control 和 Runtime 请求保持在同一环境。连接失败不能静默切换环境。
+
+## 默认路由
+
+### 普通任务
+
+创建任务、继续对话、查看任务和读取可见进度，只调用 `df-workbench`：
+
+```bash
+df-workbench me --json
+df-workbench config --json
+df-workbench task create --message '<用户原始请求>' --json
+df-workbench task send <task-id> --message '<补充内容>' --json
+df-workbench task get <task-id> --json
+df-workbench task facts <task-id> --json
+```
+
+不要在普通用户入口直接调用 `df-task` 写接口，不要伪造 `DF_TASK_ACTOR_*`，不要自行创建 Run 或选择执行 Agent。
+
+### 深度排障
+
+用户询问“任务为什么卡住”“为什么没有执行”“查看 Session/Invocation”“检查 Driver/Agent/Runtime”时，按以下顺序只读检查：
+
+```text
+df-workbench
+  → df-task
+  → df-taskdriver
+  → df-agentctrl
+  → df-agentrt
+```
+
+前一步事实不足以解释问题时，才进入下一步。不要把某个服务可达描述成整条链路成功，也不要把未知状态描述成完成或失败。
+
+## 写操作安全
+
+- 普通排障优先只读；
+- 取消、释放 Session、修复孤儿执行、启停或回退 Agent 前必须获得明确确认；
+- 不直接修改 Task 事实；
+- 不因诊断失败而重建 Session、Invocation 或切换环境；
+- 所有服务请求保持在用户选定的环境。
+
+## 输出边界
+
+回复时区分：
+
+1. 已由事实确认的结果；
+2. Driver、Agent Control 或 Runtime 返回的诊断；
+3. 仍无法确认的未知状态；
+4. 需要用户或服务维护者采取的下一步。

package/bundle/skills/deepflow-suite/manifest.yaml

@@ -0,0 +1,20 @@
+id: deepflow-suite
+version: 0.1.1
+kind: composite-skill
+requires:
+  skills:
+    - df-workbench
+    - df-task
+    - df-taskdriver
+    - df-agentctrl
+    - df-agentrt
+    - df-agentrt-repo
+  cli:
+    - df-workbench
+    - df-task
+    - df-taskdriver
+    - df-agentctrl
+    - df-agentrt
+resolution:
+  managed_by: deepflow-suite
+  install_missing_dependencies: false

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

@@ -0,0 +1,143 @@
+---
+name: df-agentctrl
+description: 使用df-agentctrl CLI查询DeepFlow Agent控制面的可用智能体目录、读取指定版本定义，或按用户要求创建和维护Agent、比较版本、启停和回退。适用于调度前发现Agent以及管理员维护Agent定义，不负责runtime执行或任务编排。
+---
+
+# DeepFlow Agent Control
+
+通过`df-agentctrl`操作Agent定义和版本。运行命令前确认CLI已在PATH中；服务地址由`DF_AGENTCTRL_BASE_URL`或`--base-url`提供，默认`http://127.0.0.1:8080`。本Skill不安装二进制，也不自动启动服务。
+
+## 目标环境门禁与地址
+
+每次调用控制面前，必须先确认用户要操作的目标环境。在推进器拉起的 Run 里按下文「Run 内的目标环境」确定，不询问。其他情况下，用户没有明确说 `local`、本地、`dev`、开发环境或 `prod`、生产环境时，先询问：
+
+```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
+```
+
+若命令不存在，说明缺少CLI部署：本项目源码可用时运行`make install-cli`，否则向调用方说明需要安装`df-agentctrl`及提供控制面地址。不要因为这个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 时沿用维护说明中的快照格式。
+
+## 发现与读取
+
+1. 有业务上下文时使用上面的 metadata 过滤；没有上下文时使用`list --json`保持历史全量行为。根据任务和Agent的`description`选择合适定义；`name`允许重复，身份以`id`为准。
+2. 从选中目录项取`id`和`default_version`，按明确版本读取完整定义：
+
+```bash
+df-agentctrl get <agent-id> --version <default_version> --json
+```
+
+3. 读取响应中的`agent`元数据与`version`定义。定义包含`description`、`instructions`、`skills`、`mcp_config`，以及版本号、时间等元数据。
+
+需要稳定内容时固定目录返回的具体版本，避免两次请求之间默认版本变化。没有合适Agent时如实说明，不为了完成一次查询就自动新建或改写Agent。需要检查停用Agent时使用`list --include-disabled --json`；停用不删除历史。
+
+## 职责边界
+
+- 控制面提供定义；聚合平台读取定义后组装`AgentData`并注入runtime。runtime不依赖控制面的API。
+- 调度智能体如何选择Agent、创建worker记录和执行任务，由既定调度流程及其playbook/skill负责。查询到Agent不代表已经分配或执行任务。
+- `provider`、`model`、`thinking level`、任务上下文与执行提示词覆盖不属于本控制面字段。
+- Skills只保留名称和固定版本或`follow_latest`，执行准备方负责解析和获取Skill内容。MCP只保存配置，不在这里做连通性检查或服务部署。
+
+## 维护Agent
+
+仅在任务要求创建、修改、启停或回退定义时使用写命令；沿用用户已经给出的授权范围。详细快照格式和操作示例见[维护说明](references/maintenance.md)。
+
+```text
+df-agentctrl create --file agent.json --json
+df-agentctrl save <agent-id> --file agent.json [--change-note <text>] --json
+df-agentctrl versions <agent-id> --json
+df-agentctrl diff <agent-id> --from <n> --to <n> [--json]
+df-agentctrl enable <agent-id> --json
+df-agentctrl disable <agent-id> --json
+df-agentctrl rollback <agent-id> --version <n> [--change-note <text>] --json
+```
+
+`save`提交完整快照，不是Patch；每次成功保存都会创建新版本并立即成为默认版本。回退也是创建新版本，当前名称和启停状态不变。所有命令支持`--base-url`，全局选项可放在命令前后；子命令帮助用`help <command>`。
+
+## 输出与错误
+
+自动处理响应使用`--json`：stdout只包含成功JSON，stderr是错误。默认Diff输出是文件统计和unified patch。
+
+- 退出0：成功。
+- 退出2：参数、UUID、版本号或输入文件无效；请求尚未发送，修正后再执行。
+- 退出1：网络或服务端失败，读取stderr。400/422按字段修正；404核对ID和版本。
+- `create/save/rollback`超时后，先用`list/get/versions`判断写入是否已发生。这些命令没有请求幂等键，不能盲目重试。
+
+完成维护后报告Agent ID、实际产生的版本和操作结果；只做目录查询时报告选中的ID和版本，不声称runtime已启动。

package/bundle/skills/df-agentctrl/assets/agent.json

@@ -0,0 +1,8 @@
+{
+  "name": "代码评审Agent",
+  "description": "阅读代码变更并给出可操作的评审意见",
+  "instructions": "根据任务提供的代码和上下文完成评审。",
+  "skills": [],
+  "mcp_config": {},
+  "change_note": "初始版本"
+}

package/bundle/skills/df-agentctrl/references/maintenance.md

@@ -0,0 +1,68 @@
+# Agent定义维护
+
+## 快照格式
+
+新建时可复制本Skill的[示例](../assets/agent.json)，然后按任务填写：
+
+```json
+{
+  "name": "代码评审Agent",
+  "description": "阅读代码变更并给出可操作的评审意见",
+  "instructions": "根据任务提供的代码和上下文完成评审。",
+  "skills": [],
+  "mcp_config": {},
+  "change_note": "初始版本"
+}
+```
+
+如果需要按业务范围发现Agent，可在创建快照的顶层增加可选 metadata。`source` 和 `query_keys`
+供控制面做软范围查询，`data` 由业务方自行组织：
+
+```json
+"metadata": {
+  "source": "workbench",
+  "query_keys": ["account:u123"],
+  "data": {"project": "orders"}
+}
+```
+
+metadata 只在 `create` 时写入 Agent 记录；`save` 提交的是版本定义快照，不接受 metadata 字段。
+
+名称必填、允许重复；长度上限为200字符，职责说明2000、Instructions 200000、修改说明2000。`name`属于Agent元数据，历史版本不保留过去的名称。
+
+Skill引用的`name`使用Marketplace slug；例如固定`{"name":"code-review","version":"1.0.0"}`或跟随`{"name":"code-review","follow_latest":true}`，两种策略二选一。不要把Marketplace数据库ID或Skill文件内容写进定义。控制面保存时不访问Marketplace验证该引用。
+
+MCP空配置用`{}`，非空用`{"mcpServers":{...}}`；不加入模型、运行会话或调度业务字段。保存会完整覆盖版本内容，遗漏字段不意味着保留旧值。
+
+## 编辑已有Agent
+
+先读取完整定义，转换为可写快照，再修改需要调整的字段：
+
+```bash
+df-agentctrl get <agent-id> --json > current.json
+python3 <skill-dir>/scripts/to_snapshot.py < current.json > agent.json
+# 按任务修改agent.json，保留未修改的Instructions、Skills和MCP。
+df-agentctrl save <agent-id> --file agent.json --change-note '调整评审指令' --json
+```
+
+`<skill-dir>`使用当前Skill所在目录的实际路径。转换脚本保留名称和四项定义字段，清空修改说明，不携带`id`、时间、版本号等服务端元数据。不要直接把`get`响应作为`save`请求提交。
+
+`--change-note`覆盖文件里的说明，`--change-note=`可显式清空。保存成功返回`{"agent": {...}, "version": {...}}`，从响应取实际版本号，不假设仍是读取版本加一（其他管理员可能同时保存）。
+
+## 版本与回退
+
+```bash
+df-agentctrl versions <agent-id> --json
+df-agentctrl diff <agent-id> --from 1 --to 2
+df-agentctrl rollback <agent-id> --version 1 --change-note '恢复版本1内容' --json
+```
+
+Diff比较同一个Agent的两个已有版本，返回`description.md`、`instructions.md`、`skills.json`和`mcp-config.json`中实际变化的文件。`--json`返回结构化`files`及每个文件的`patch`。
+
+若当前为v2，回退v1会创建v3，不把默认指针直接拨回v1。回退返回新版本对象，名称与启停状态保持当前值。
+
+## 启停与失败恢复
+
+启停是幂等操作：`enable`恢复默认目录可见性，`disable`隐藏目录项；两者均保留历史，不取消已开始的执行。
+
+写请求超时可能发生在事务已经提交之后。先检查返回的ID（若有）、目录、当前版本和版本历史；无法确认是否提交时报告不确定性，不重复创建版本。控制面没有删除Agent、删除历史或补丁更新命令。

package/bundle/skills/df-agentctrl/scripts/to_snapshot.py

@@ -0,0 +1,26 @@
+#!/usr/bin/env python3
+"""Read a df-agentctrl get --json response on stdin and emit a writable snapshot."""
+import argparse
+import json
+import sys
+
+
+def main():
+    argparse.ArgumentParser(description=__doc__).parse_args()
+    try:
+        detail = json.load(sys.stdin)
+        agent, version = detail["agent"], detail["version"]
+        snapshot = {"name": agent["name"]}
+        for key in ("description", "instructions", "skills", "mcp_config"):
+            snapshot[key] = version[key]
+        snapshot["change_note"] = ""
+    except (ValueError, TypeError, KeyError) as exc:
+        print(f"Expected a complete df-agentctrl get --json response: {exc}", file=sys.stderr)
+        return 2
+    json.dump(snapshot, sys.stdout, ensure_ascii=False, indent=2)
+    print()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())