Bailian Managed Agent

Bailian managed agent IaC (bl managed-agent)

CRITICAL — Before executing, MUST read the shared protocol in [`../bailian-protocol/SKILL.md`](../bailian-protocol/SKILL.md): High-risk operation confirmation, Version & updates (pre-flight checklist), and CLI errors: report an issue. Command details are authoritative in [`reference/managed-agent.md`](reference/managed-agent.md) and `bl managed-agent --help` — do not guess flags. If that protocol file is missing, stop and run `bl skill init`; do not guess auth/consent.

Safety guardrail (the most important rule)

apply / destroy and single-resource create --yes mutate persistent remote resources:

1. For agents.yaml resource changes, always run bl managed-agent plan first and show the diff to the user.
2. A single-resource create command previews its scoped plan when --yes is absent; show that preview before retrying it with --yes.
3. Only after explicit user confirmation, retry apply / destroy / single-resource create with --yes.
4. Never add --yes on your own initiative before the user has confirmed.

API-oriented commands do not replace IaC. Agent / Environment / Skill / Vault / Deployment 的 create 命令仍通过 agents.yaml → scoped plan → scoped apply 管理；查询命令和 Session、Event、File、Deployment 运行时动作直接调用 API。 session archive|delete、file delete、deployment run|pause|unpause 也需要先 --dry-run，确认后才传 --yes。

state rm, session archive|delete, file delete, deployment run|pause|unpause, and future risk: high commands follow the shared protocol: show the risk message and exact scope, then wait for explicit confirmation before re-running with --yes.

IaC lifecycle

1. Init      bl managed-agent init          # scaffold agents.yaml
2. Validate  bl managed-agent validate      # offline, no network calls
3. Preview   bl managed-agent plan          # show the pending change diff
4. Confirm   show the plan and ask the user # no automatic --yes
5. Apply     bl managed-agent apply --yes   # only after explicit confirmation
6. Destroy   bl managed-agent destroy --yes # separate explicit confirmation

Directory projects, Workbench, and local versions

• 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.
• 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.

Scoped single-resource create

以下命令都先构造 agents.yaml 声明，再通过 SDK 的定向 Plan/Apply 创建远端资源，不绕过 State：

• 用户只提供资源 name；CLI 自动生成稳定的 YAML 逻辑 key，同名资源用递增后缀并存。Credential 追加到指定 Vault，不单独生成 key。
• agent create --skill <id> 直接绑定已存在的远端 Skill，不要求顶层 skills 声明；默认写为 type: custom，平台 Skill 显式增加 --type official。同一次命令中的全部 --skill 共用该类型。
• agent create --skill-dir <path> 接收可重复的本地 Skill 目录或 ZIP：CLI 从其中的 SKILL.md 读取 name，自动生成顶层 skills.<key> 声明，并把该 key 写入 Agent 的 skills 列表；定向 Apply 会先上传 custom Skill，再创建 Agent。--type 只作用于 --skill <id>，不改变本地 Skill 的 custom 类型。
• Environment 和 Vault 属于 Session/Deployment 运行时绑定，不是 Agent 创建参数；在 session create|run 或 deployment create 中传入。
• 默认只预览自动 key 和定向计划；--dry-run 完全离线，只有显式 --yes 才写 YAML 并创建远端资源。
• 定向流程只刷新目标资源及其传递依赖；无关资源不检测 Drift、不产生 action，也不阻塞。
• 目标资源必须是 create，相关依赖必须已经处于 no-op；项目级 Drift 和删除仍由全量 plan/apply 处理。
• 远端创建失败时保留 YAML 声明；修复相关依赖或 Provider 错误后，重复相同命令会复用待创建 key。
• skill create 接受本地目录、ZIP 或单个 SKILL.md；远程 URL 仍需手工声明到 YAML，再执行全量 Apply。

Credential secret input

vault credential create --secret-env <ENV_NAME> 中的参数是变量名，不是 Secret 明文。Secret 可来自 Shell export、CI Secret 注入或可选的 .env；CLI 会从当前目录向上自动加载最近的 .env，用户不必创建该文件。