feat(managed-agent): integrate directory resource scaffolds and safe builds

Author: chenanran555

packages/commands/src/commands/managed-agent/_engine/config-loader.ts

@@ -30,6 +30,7 @@ export const BAILIAN_PROVIDER = "bailian";
 
 interface AgentConfigOptions {
   resolveEnv?: boolean;
+  environment?: Record<string, string>;
   projectName?: string;
   statePath?: string;
   credentials?: CredentialScope;

packages/commands/src/commands/managed-agent/project.ts

@@ -46,6 +46,14 @@ export const managedAgentProjectInit = defineCommand({
   usageArgs: "[--project <directory>]",
   flags: PROJECT_FLAG,
   exampleArgs: ["", "--project ./my-agent"],
+  notes: [
+    {
+      "en-US":
+        "New projects include Skill, File, Vault, and Environment examples under each resource directory's _examples/. They are not referenced by agent.json and are excluded from Build/Publish. Copy an example outside _examples/ to enable it, then configure its Agent reference.",
+      "zh-CN":
+        "新项目在四类资源目录的 _examples/ 下生成配置示例，不写入 agent.json 引用，也不参与 Build/Publish。需要使用时，将示例复制到 _examples/ 外，再配置 Agent 引用。",
+    },
+  ],
   async run(ctx) {
     if (ctx.settings.dryRun) {
       emitResult(
@@ -95,8 +103,9 @@ export const managedAgentProjectBuild = defineCommand({
     level: "high",
     message: {
       "en-US":
-        "This organizes the directory project source and writes the previewed immutable Build.",
-      "zh-CN": "该操作会整理目录项目源文件，并写入已预览的不可变 Build。",
+        "This organizes project source, moves literal Vault secrets into the local .env, and writes the previewed immutable Build.",
+      "zh-CN":
+        "该操作会整理项目源文件，将 Vault 明文密钥移入本地 .env，并写入已预览的不可变 Build。",
     },
   },
   usageArgs: "[--project <directory>]",
@@ -161,8 +170,9 @@ export const managedAgentProjectPublish = defineCommand({
   async run(ctx) {
     installSdkTransport(ctx);
     const root = ctx.flags.project ?? ".";
-    const resolveBuild: ProjectBuildResolver = async (buildPath) =>
+    const resolveBuild: ProjectBuildResolver = async (buildPath, options) =>
       (await resolveAgentProjectConfig(ctx, buildPath, {
+        environment: options?.environment,
         overrideBailianBaseUrl: true,
       })) as unknown as Awaited<ReturnType<ProjectBuildResolver>>;
     const planned = await withAgentErrors(() =>

packages/commands/tests/e2e/managed-agent.e2e.test.ts

@@ -290,6 +290,32 @@ describe("e2e: managed-agent", () => {
     expect(await stat(join(projectRoot, ".env")).catch(() => null)).toBeNull();
     expect(await stat(join(projectRoot, ".gitignore")).catch(() => null)).toBeNull();
 
+    expect(
+      JSON.parse(await readFile(join(projectRoot, "agents/assistant/agent.json"), "utf8")),
+    ).toEqual({ name: "Assistant", model: "qwen3.7-max" });
+    for (const relativePath of [
+      "skills/_examples/example-skill/skill.json",
+      "skills/_examples/example-skill/SKILL.md",
+      "files/_examples/example-file/file.json",
+      "files/_examples/example-file/example.md",
+      "vaults/_examples/example-vault/vault.json",
+      "environments/_examples/example-env/environment.json",
+    ]) {
+      expect((await stat(join(projectRoot, "agents/assistant", relativePath))).isFile()).toBe(true);
+      expect(
+        await readFile(join(projectRoot, "agents/assistant", relativePath, "../README.md"), "utf8"),
+      ).toContain("_examples/");
+    }
+
+    const skillDirectory = join(projectRoot, "agents/assistant/skills/writer");
+    const filesDirectory = join(projectRoot, "agents/assistant/files");
+    const nestedFileDirectory = join(filesDirectory, "mount");
+    await mkdir(skillDirectory, { recursive: true });
+    await mkdir(nestedFileDirectory, { recursive: true });
+    await writeFile(join(skillDirectory, "SKILL.md"), "# Writer\n", "utf8");
+    await writeFile(join(filesDirectory, "brief.txt"), "Build this brief.\n", "utf8");
+    await writeFile(join(nestedFileDirectory, "mount.md"), "Mount this file.\n", "utf8");
+
     const validated = await runCommandE2e(MANAGED_AGENT_ROUTES, [
       "managed-agent",
       "project",
@@ -304,6 +330,38 @@ describe("e2e: managed-agent", () => {
       parseStdoutJson<{ diagnostics?: Array<{ severity?: string }> }>(validated.stdout).diagnostics,
     ).not.toContainEqual(expect.objectContaining({ severity: "error" }));
 
+    const vaultDirectory = join(projectRoot, "agents/assistant/vaults/secrets");
+    await mkdir(vaultDirectory, { recursive: true });
+    await writeFile(
+      join(vaultDirectory, "vault.json"),
+      JSON.stringify({
+        id: "secrets",
+        display_name: "Secrets",
+        credentials: [
+          {
+            name: "service",
+            type: "environment_variable",
+            secret_name: "SERVICE_TOKEN",
+            secret_value: "e2e-vault-private-value",
+          },
+        ],
+      }),
+    );
+    const dryBuild = await runCommandE2e(MANAGED_AGENT_ROUTES, [
+      "managed-agent",
+      "project",
+      "build",
+      "--project",
+      projectRoot,
+      "--dry-run",
+      "--output",
+      "json",
+    ]);
+    expect(dryBuild.exitCode, dryBuild.stderr).toBe(0);
+    expect(dryBuild.stdout + dryBuild.stderr).not.toContain("e2e-vault-private-value");
+    expect(dryBuild.stdout).toContain("AGENTS_VAULT_");
+    expect(await stat(join(projectRoot, ".env")).catch(() => null)).toBeNull();
+
     const built = await runCommandE2e(MANAGED_AGENT_ROUTES, [
       "managed-agent",
       "project",
@@ -315,12 +373,50 @@ describe("e2e: managed-agent", () => {
       "json",
     ]);
     expect(built.exitCode, built.stderr).toBe(0);
+    const generatedYaml = await readFile(
+      join(projectRoot, ".openagentpack/build/agents.yaml"),
+      "utf8",
+    );
+    expect(generatedYaml).not.toContain("example-");
+    expect(generatedYaml).not.toContain("_examples");
+    expect(generatedYaml).not.toContain("$" + "{SERVICE_TOKEN}");
+    expect(built.stdout + built.stderr).not.toContain("e2e-vault-private-value");
+    expect(await readFile(join(projectRoot, ".env"), "utf8")).toContain("e2e-vault-private-value");
+    expect(await readFile(join(vaultDirectory, "vault.json"), "utf8")).not.toContain(
+      "e2e-vault-private-value",
+    );
+    expect(
+      await readFile(join(projectRoot, ".openagentpack/build/agents.yaml"), "utf8"),
+    ).not.toContain("e2e-vault-private-value");
     expect(await readFile(join(projectRoot, ".openagentpack/build/agents.yaml"), "utf8")).toContain(
       "assistant",
     );
     expect(await readFile(join(projectRoot, ".openagentpack/build/agents.yaml"), "utf8")).toContain(
       "provider: bailian",
     );
+    expect(JSON.parse(await readFile(join(skillDirectory, "skill.json"), "utf8"))).toEqual({
+      id: "writer",
+    });
+    expect(JSON.parse(await readFile(join(filesDirectory, "brief/file.json"), "utf8"))).toEqual({
+      id: "brief",
+      name: "brief.txt",
+      source: "./brief.txt",
+    });
+    expect(JSON.parse(await readFile(join(nestedFileDirectory, "file.json"), "utf8"))).toEqual({
+      id: "mount",
+      name: "mount.md",
+      source: "./mount.md",
+    });
+    const builtAgent = JSON.parse(
+      await readFile(join(projectRoot, "agents/assistant/agent.json"), "utf8"),
+    );
+    expect(builtAgent.skills).toEqual(["writer"]);
+    expect(builtAgent.files).toEqual(
+      expect.arrayContaining([
+        { file: "brief", mount_path: "/mnt/brief.txt" },
+        { file: "mount", mount_path: "/mnt/mount.md" },
+      ]),
+    );
 
     const status = await runCommandE2e(MANAGED_AGENT_ROUTES, [
       "managed-agent",

skills/bailian-managed-agent/SKILL.md

@@ -63,9 +63,12 @@ for explicit confirmation before re-running with `--yes`.
 
 - Bailian CLI and Workbench use the same `.openagentpack/versions/project` store and enable switch. Git is not required.
 - Directory projects always use Bailian. `project.json` does not declare a Provider; Build supplies the Bailian Provider configuration automatically.
+- Fresh `project init` includes complete Skill/File/Vault/Environment examples with bilingual README files under `agents/assistant/<resource-type>/_examples/`. They are not linked in `agent.json` and are excluded from Build discovery, Workbench declarations, and remote Publish. Copy a resource outside `_examples/` and configure its Agent reference to use it. Examples remain local versioned source; never put real secrets into them. / 新项目的四类资源示例默认不启用、不发布；请按 README 复制到 `_examples/` 外再配置引用，不要向示例写入真实密钥。
 - `project init`, `validate`, `build`, and version commands are local-only. Publish and Workbench resolve credentials from Bailian CLI flags, shell environment, or the active Profile; project initialization does not write credentials into the project directory.
 - Build is local-only. Publish never runs Build implicitly and consumes only a current `.openagentpack/build/agents.yaml` plus manifest.
-- Agent-owned Files live under `agents/<agent>/files/<id>/`. Add `{ "file": "<id>", "mount_path": "/mnt/<name>" }` to `agent.json.files`; Publish uploads the File and every later Session mounts it automatically. A File referenced by multiple Agents is promoted to `resources/files/<id>/` during Build.
+- Build moves literal Vault `secret_value` / `access_token` values from Agent-local or shared `vault.json` into project-root `.env`, replacing them with generated environment references. Existing references and `.env` entries are preserved; conflicts receive suffixed variable names. Preview/dry-run never write or print secrets. Publish and Workbench read the selected project's root `.env` as a fallback to inherited environment variables, even when invoked elsewhere. `.env` is private plaintext storage, excluded from local versions but not automatically ignored by Git; keep it backed up securely.
+- Build 会将 Agent 本地或共享 `vault.json` 中的明文密钥移入项目根目录 `.env`，再写回环境变量引用；保留已有引用和变量，重名时生成后缀。预览不写文件或输出密钥。`.env` 不进入版本快照，也不加密；请自行备份并加入 Git 忽略规则。
+- Agent-local File and Skill content supports Build-time association. A File may be copied directly into `agents/<agent>/files/`, or placed in `agents/<agent>/files/<id>/` when that directory contains exactly one content file; Build generates `file.json` and a `/mnt/<filename>` entry in `agent.json.files`. A directory under `agents/<agent>/skills/<id>/` containing `SKILL.md` generates `skill.json` and its `agent.json.skills` entry. Explicit JSON always wins; shared root resources remain explicit. Resources referenced by multiple Agents are promoted to the corresponding root shared directory during Build.
 - A successful Publish versions the canonical YAML and the complete project source tree, including Skill scripts/assets and binary files. Remote State is never versioned or restored.
 - `project version restore` restores source files to the working directory, invalidates Build, and does not move version history or remote State.
 - `managed-agent playground` remains the standalone `agents.yaml` Session Preview path; directory Workbench is only under `managed-agent project workbench`.

skills/bailian-managed-agent/reference/managed-agent.md

@@ -1181,14 +1181,14 @@ bl managed-agent playground --file agents.yaml --no-open
 
 ### `bl managed-agent project build`
 
-| Field              | Value                                                                                 |
-| ------------------ | ------------------------------------------------------------------------------------- |
-| **Name**           | `managed-agent project build`                                                         |
-| **Description**    | Organize directory source and generate the immutable Publish Build                    |
-| **Authentication** | No Auth                                                                               |
-| **Usage**          | `bl managed-agent project build [--project <directory>]`                              |
-| **Risk**           | `high`                                                                                |
-| **Risk message**   | This organizes the directory project source and writes the previewed immutable Build. |
+| Field              | Value                                                                                                                     |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------- |
+| **Name**           | `managed-agent project build`                                                                                             |
+| **Description**    | Organize directory source and generate the immutable Publish Build                                                        |
+| **Authentication** | No Auth                                                                                                                   |
+| **Usage**          | `bl managed-agent project build [--project <directory>]`                                                                  |
+| **Risk**           | `high`                                                                                                                    |
+| **Risk message**   | This organizes project source, moves literal Vault secrets into the local .env, and writes the previewed immutable Build. |
 
 > **Agent safety:** Never add `--yes` automatically. On `type="requires_confirmation"`, stop and ask for explicit user confirmation of the same action and scope.
 
@@ -1230,6 +1230,10 @@ bl managed-agent project build --project ./my-agent --yes
 | ----------------------- | ------ | -------- | --------------------------------------------------- |
 | `--project <directory>` | string | no       | Directory project root (default: current directory) |
 
+#### Notes
+
+- New projects include Skill, File, Vault, and Environment examples under each resource directory's \_examples/. They are not referenced by agent.json and are excluded from Build/Publish. Copy an example outside \_examples/ to enable it, then configure its Agent reference.
+
 #### Examples
 
 ```bash