@aipt/idp-deploy 0.1.2 → 0.1.4

package/README.md

@@ -1,5 +1,7 @@
 # IDP Deploy
 
+业务项目不复制本仓部署长文档。Dyyto Bootstrap 锁定本包版本和 `local-deployment` 文档 ID；`dyyto docs show --id local-deployment` 提供面向 Agent 的精简入口。
+
 `idp-deploy` 是企业内部开发者平台的轻量部署与运维控制面。它把 PostgreSQL、私有 npm Registry、Tech、Flow、Portal、SmartGo 和 Caddy 组合为可独立启停的服务片段；Dyyto、Bench、Forge 仍是按需运行的 CLI/MCP 工具，不被强制常驻。SmartGo 是显式选择的业务 Profile，不进入默认 IDP Core。
 
 Kubernetes/GitOps 已进入当前 CLI：应用通过 ComponentContract、Bench EnvironmentBinding 和 ReleaseCandidate 生成不可变 DeploymentPlan，再由同一 Kernel 完成确定性 Render、Repository Apply、Git commit、Preimage/CAS 保护和 Repository Verify。它保留历史 `kubernetes-config` 的中央期望状态与 Argo 收敛能力，但不复制跨仓 `sed`、可变 tag、明文 Secret 或宽权限。完整合同与所有权见 [`docs/features/kubernetes-gitops-deployment-backend/DESIGN.md`](docs/features/kubernetes-gitops-deployment-backend/DESIGN.md)。
@@ -72,31 +74,29 @@ Bench 原有部署资产已按能力而非目录整体接收：受控运维语
 export IDP_DEPLOY_ROOT=/Users/dyyto/Desktop/works/sources/spaces/idp-deploy
 export APPLICATION_ROOT=/absolute/path/to/new-project
 export IDP_CONFIG_DIR=/Users/Shared/company/idp/config
+export APP_CONFIG_DIR=/Users/Shared/company/app/config
 
 # 1. 根据Dyyto ApplicationConfigContract创建应用.env、secrets/和certs/；重入不覆盖已有值。
 node "$IDP_DEPLOY_ROOT/bin/idpctl.mjs" app config-init \
   --project "$APPLICATION_ROOT" \
-  --config-dir "$IDP_CONFIG_DIR"
+  --environment local
 
 # 2. 填写命令不能代替外部系统签发的required Secret；不要把值写入项目。
-chmod 600 "$IDP_CONFIG_DIR/applications/<application-id>/secrets/"*
+chmod 600 "$APP_CONFIG_DIR/<application-id>/local/secrets/"*
 
 # 3. 生成不可变Local DeploymentPlan；本步只执行docker compose config和安全检查。
 node "$IDP_DEPLOY_ROOT/bin/idpctl.mjs" local app plan \
   --project "$APPLICATION_ROOT" \
   --compose-file "$APPLICATION_ROOT/deploy/compose.local.yaml" \
-  --output "$IDP_CONFIG_DIR/plans/local-applications/<application-id>-local.json" \
-  --config-dir "$IDP_CONFIG_DIR"
+  --output "$APP_CONFIG_DIR/<application-id>/local/plans/local-applications/<application-id>-local.json"
 
 # 4. 审查Plan中的项目、输入摘要、Compose摘要和promotable:false后执行。
 node "$IDP_DEPLOY_ROOT/bin/idpctl.mjs" local app apply \
-  --plan "$IDP_CONFIG_DIR/plans/local-applications/<application-id>-local.json" \
-  --config-dir "$IDP_CONFIG_DIR"
+  --plan "$APP_CONFIG_DIR/<application-id>/local/plans/local-applications/<application-id>-local.json"
 
 # 5. 随时重新核验精确Plan与容器健康状态。
 node "$IDP_DEPLOY_ROOT/bin/idpctl.mjs" local app verify \
-  --plan "$IDP_CONFIG_DIR/plans/local-applications/<application-id>-local.json" \
-  --config-dir "$IDP_CONFIG_DIR"
+  --plan "$APP_CONFIG_DIR/<application-id>/local/plans/local-applications/<application-id>-local.json"
 ```
 
 代码、Dockerfile、Compose、`.env` 或任一 `*_FILE` 发生变化后，旧 Plan 会 fail-closed；删除旧 Plan 文件并用新的输出文件名重新 `plan`、审查和 `apply`。停止保留容器，移除不删除 Volume：
@@ -363,6 +363,7 @@ node bin/idpctl.mjs sources import bench \
 
 ```bash
 export IDP_CONFIG_DIR=/Users/Shared/company/idp/config
+export APP_CONFIG_DIR=/Users/Shared/company/app/config
 node bin/idpctl.mjs workbench projects init
 ```
 
@@ -376,21 +377,15 @@ node bin/idpctl.mjs workbench projects init
       "id": "apex",
       "hostPath": "/Users/dyyto/Desktop/works/sources/spaces/apex",
       "configBindings": [
-        {
-          "relativePath": "apps/client",
-          "applicationConfigDir": "/Users/Shared/company/apps/apex-client/local"
-        },
-        {
-          "relativePath": "apps/server",
-          "applicationConfigDir": "/Users/Shared/company/apps/apex-server/local"
-        }
+        { "relativePath": "apps/client" },
+        { "relativePath": "apps/server" }
       ]
     }
   ]
 }
 ```
 
-各 Config Dir 应先由 `app config-init` 创建并由操作者填写 `.env`、`secrets/` 和 `certs/`。随后生成不可变 Plan、应用并验证：
+`APP_CONFIG_DIR` 是业务配置总根；上例自动派生 `apex/apps/client/local` 和 `apex/apps/server/local`。各 Config Dir 应先由 `app config-init --workspace-root <apex-root>` 创建并由操作者填写 `.env`、`secrets/` 和 `certs/`。随后生成不可变 Plan、应用并验证：
 
 ```bash
 node bin/idpctl.mjs workbench projects plan \

package/docs/config-dir-security.md

@@ -0,0 +1,3 @@
+# Config Dir 安全边界
+
+平台配置与业务配置分离：`IDP_CONFIG_DIR` 保存工程基座配置，`APP_CONFIG_DIR` 是业务 Workspace 和应用配置总根。Secret、证书与 `*_FILE` 目标位于仓库外，权限不超过 0600；项目内禁止保存真实敏感值。

package/docs/local-deployment.md

@@ -0,0 +1,3 @@
+# 业务应用本地 Docker 部署
+
+设置仓库外 `IDP_CONFIG_DIR` 与 `APP_CONFIG_DIR`，先运行 `idpctl app config-init`，再运行 `idpctl local app plan`、`apply`、`verify`。本地模式直接使用 Compose 构建，不推送远程 OCI；生产交付仍要求不可变多架构镜像摘要。

package/docs/vibe-delivery.md

@@ -0,0 +1,3 @@
+# Vibe Coding 交付接口
+
+编码 Agent 从 Dyyto Context 获得交付意图，不直接修改运行环境。部署写入必须来自精确批准的 idpctl Plan；输入、Compose、配置或源码变化后旧 Plan 自动失效。

package/documentation-manifest.json

@@ -0,0 +1,10 @@
+{
+  "schemaVersion": 1,
+  "package": "@aipt/idp-deploy",
+  "version": "0.1.4",
+  "documents": [
+    { "id": "config-dir-security", "path": "docs/config-dir-security.md", "digest": "sha256:057b3f07104255812d2f26f59842c42f995305c64c5494889fee59772041e324" },
+    { "id": "local-deployment", "path": "docs/local-deployment.md", "digest": "sha256:4d86d7e7ed8619fa750430989afefe71e033673adedb924bb60b4272d7d2e3f6" },
+    { "id": "vibe-delivery", "path": "docs/vibe-delivery.md", "digest": "sha256:3e6dee64c85417c1402ad3d9433e24c223acef584bc2f71cec0711085e5438e6" }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aipt/idp-deploy",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "IDP 私有化部署、外部配置、备份恢复与交付编排 CLI。",
   "type": "module",
   "bin": {
@@ -13,7 +13,11 @@
     "contracts",
     "release",
     "governance",
+    "docs/config-dir-security.md",
+    "docs/local-deployment.md",
+    "docs/vibe-delivery.md",
     "docs/restore-runbook.md",
+    "documentation-manifest.json",
     "README.md",
     "deploy.sh"
   ],

package/src/application-config-location.mjs

@@ -0,0 +1,50 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { invariant } from './errors.mjs';
+import { assertOutsideRepositories, secureDirectoryRoot } from './security.mjs';
+
+const ID = /^[a-z0-9][a-z0-9._-]{0,127}$/u;
+const UNIT = /^(?:apps|packages)\/[a-z0-9][a-z0-9._-]*$/u;
+
+function manifest(root) {
+  try { return JSON.parse(fs.readFileSync(path.join(root, 'project-capabilities.json'), 'utf8')); }
+  catch { return null; }
+}
+
+export function discoverWorkspace(projectRoot, explicitWorkspaceRoot) {
+  const project = fs.realpathSync.native(projectRoot);
+  if (explicitWorkspaceRoot) {
+    invariant(path.isAbsolute(explicitWorkspaceRoot), 'IDP_WORKSPACE_ROOT_NOT_ABSOLUTE', '--workspace-root必须是绝对路径');
+    const root = fs.realpathSync.native(explicitWorkspaceRoot), relative = path.relative(root, project);
+    invariant((relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative))) && manifest(root)?.profile?.id === 'workspace-root', 'IDP_WORKSPACE_ROOT_INVALID', '--workspace-root必须是包含项目的Dyyto Workspace Root');
+    return relative === '' ? null : { root, id: path.basename(root), unitPath: relative.split(path.sep).join('/') };
+  }
+  let cursor = path.dirname(project);
+  while (cursor !== path.dirname(cursor)) {
+    if (manifest(cursor)?.profile?.id === 'workspace-root') {
+      const unitPath = path.relative(cursor, project).split(path.sep).join('/');
+      return { root: cursor, id: path.basename(cursor), unitPath };
+    }
+    cursor = path.dirname(cursor);
+  }
+  return null;
+}
+
+export function resolveApplicationConfigDirectory({ projectRoot, applicationId, appConfigRoot, applicationConfigRoot, workspaceRoot, environment = 'local', create = false }) {
+  invariant(ID.test(applicationId ?? ''), 'IDP_APPLICATION_CONFIG_IDENTITY_INVALID', 'Application identity无效');
+  invariant(ID.test(environment), 'IDP_APPLICATION_ENVIRONMENT_INVALID', '应用环境名称无效');
+  if (applicationConfigRoot) {
+    const app = secureDirectoryRoot(applicationConfigRoot, '应用最终Config Dir', { create }); assertOutsideRepositories(app, '应用最终Config Dir');
+    return { root: app, app, environment, workspace: null, relativeDirectory: '.' };
+  }
+  invariant(path.isAbsolute(appConfigRoot ?? ''), 'APP_CONFIG_DIR_REQUIRED', '请设置绝对APP_CONFIG_DIR或传入--application-config-dir');
+  const root = secureDirectoryRoot(appConfigRoot, 'APP_CONFIG_DIR', { create }); assertOutsideRepositories(root, 'APP_CONFIG_DIR');
+  const workspace = discoverWorkspace(projectRoot, workspaceRoot);
+  if (workspace) invariant(UNIT.test(workspace.unitPath), 'IDP_WORKSPACE_UNIT_INVALID', 'Workspace应用必须位于apps/<name>或packages/<name>');
+  const relativeDirectory = workspace ? `${workspace.id}/${workspace.unitPath}/${environment}` : `${applicationId}/${environment}`;
+  const app = path.resolve(root, ...relativeDirectory.split('/'));
+  invariant(app.startsWith(`${root}${path.sep}`), 'APP_CONFIG_DIRECTORY_ESCAPE', '应用Config Dir逃逸APP_CONFIG_DIR');
+  if (create) secureDirectoryRoot(app, '应用Config Dir', { create: true });
+  else secureDirectoryRoot(app, '应用Config Dir');
+  return { root: app, app, environment, workspace, relativeDirectory };
+}

package/src/cli.mjs

@@ -30,6 +30,18 @@ export function configRootFrom(args, { environment = process.env } = {}) {
   return path.resolve(value);
 }
 
+export function appConfigRootFrom(args, { environment = process.env, required = false } = {}) {
+  const index = args.indexOf('--app-config-dir');
+  if (index >= 0 && (!args[index + 1] || args[index + 1].startsWith('--'))) throw new IdpError('APP_CONFIG_ARGUMENT_MISSING', '--app-config-dir后必须提供绝对路径');
+  const value = index >= 0 ? args[index + 1] : environment.APP_CONFIG_DIR;
+  if (!value) {
+    if (required) throw new IdpError('APP_CONFIG_DIR_REQUIRED', '请设置APP_CONFIG_DIR或传入--app-config-dir');
+    return undefined;
+  }
+  if (!path.isAbsolute(value)) throw new IdpError('APP_CONFIG_DIR_NOT_ABSOLUTE', 'APP_CONFIG_DIR必须是绝对路径');
+  return path.resolve(value);
+}
+
 export function readSourceImportFile(configRoot, rawCandidate) {
   if (!path.isAbsolute(rawCandidate ?? '')) throw new IdpError('IDP_SOURCE_FILE_NOT_ABSOLUTE', '--file必须是原始绝对路径');
   const { root } = doctorConfig(configRoot, { requireConfigured: false, profile: 'registry' });
@@ -72,7 +84,7 @@ function print(value) {
 export async function main(args) {
   const [command, subcommand] = args;
   if (!command || ['help', '--help', '-h'].includes(command)) {
-    process.stdout.write('本地项目命令：\n  app config-init --project <绝对项目目录>\n  local app plan --project <绝对目录> --compose-file <绝对文件> --output <IDP_CONFIG_DIR/plans/local-applications/...>\n  local app apply|verify|stop --plan <绝对文件>\n  local app remove --plan <绝对文件> --confirm <application-id>\n\n');
+    process.stdout.write('本地项目命令：\n  app config-init --project <绝对项目目录> [--workspace-root <绝对目录>] [--environment local]\n  local app plan --project <绝对目录> [--workspace-root <绝对目录>] --compose-file <绝对文件> --output <应用Config Dir/plans/local-applications/...>\n  local app apply|verify|stop --plan <绝对文件>\n  local app remove --plan <绝对文件> --confirm <application-id>\n\nAPP_CONFIG_DIR是全部业务工作区/应用配置总根；显式--application-config-dir仅兼容覆盖最终应用目录。\n\n');
     process.stdout.write('Docker工作台项目命令：\n  workbench projects init\n  workbench projects plan --dyyto-root <绝对目录> --file <candidate> --output <Plan>\n  workbench projects apply --plan <Plan>\n  workbench projects verify\n\n');
     print(`idpctl：私有IDP部署与运维工具\n\n命令：\n  config init\n  config generate-secrets\n  config snapshot\n  release deploy [profile] [--version <semver>] [--oci-repository-root <host/namespace/repository>]\n  gitops app plan-create|plan-update|plan-remove --component-contract <绝对路径> --environment-binding <绝对路径> --release-candidate <绝对路径> --gitops-root <绝对路径> --output <IDP_CONFIG_DIR/plans/...>\n  gitops app apply --plan <绝对路径>\n  gitops app verify --application <名称> --environment <名称> --gitops-root <绝对路径>\n  foundation doctor|verify [--context <kube-context>]\n  foundation directory sync [--argo-url <URL>] [--rollouts-url <URL>] [--registry-url <URL>]\n  sources import dyyto|bench --stdin\n  sources import dyyto|bench --file <IDP_CONFIG_DIR/imports/...>\n  images lock\n  doctor [profile] [--require-configured]\n  compose <profile>\n  pull <profile>\n  up <profile>\n  switch <profile>\n  down <profile>\n  verify <profile>\n  bindings sync <active-profile>\n  accept mac-m4 <profile> --confirm-restart <IDP_INSTANCE_ID>\n  backup create [profile]\n  backup verify <generation-id>\n  restore test <generation-id>\n  restore apply <generation-id>\n  restore verify <candidate-id>\n  restore promote <candidate-id> --confirm <candidate-id>\n  contracts verify config-release|release-candidate|deployment-evidence --file <绝对JSON路径>\n\nProfile：registry、tech-only、foundation、flow、portal、core、full、business-smartgo、core-smartgo；release deploy默认foundation。SmartGo不会进入默认core/full，需显式选择business-smartgo或core-smartgo。\n所有命令只通过IDP_CONFIG_DIR读取仓库外配置；Secret不会打印到终端。GitOps写入必须来自不可变Plan，Apply复验输入、HEAD与Preimage并在外部配置根保存恢复证据。release deploy在同一实例Lease内完成自研镜像的amd64/arm64构建与digest绑定、已有部署备份和隔离恢复演练、镜像锁、Compose、Verifier与Binding事务。bindings sync只从已启用且verify通过的当前运行事实生成Bench ServiceBinding，并保护用户修改与历史Preimage。跨Profile必须使用switch，它会显式清理旧Profile Orphan。restore apply先生成隔离候选；promote保留物理或逻辑Preimage并在失败时自动回滚。`);
     process.stdout.write('无集群开发者命令：\n  app inspect --component-contract <绝对路径> [--environment-binding <绝对路径>]\n  workflow generate|verify --file <绝对路径>\n  build plan --component-contract <绝对路径> --repository <Git URL> --commit <40位SHA> --image-repository <OCI仓库> --output <绝对路径>\n  build trigger --plan <绝对路径> --provider manual --output <绝对路径>\n  build status --trigger <绝对路径>\n附加只读命令：\n  lifecycle check\n  contracts verify ...\n');
@@ -131,19 +143,20 @@ export async function main(args) {
     return;
   }
   const configRoot = configRootFrom(args);
+  const appConfigRoot = appConfigRootFrom(args);
   if (command === 'app' && subcommand === 'config-init') {
-    const values = namedArguments(args.slice(2), ['--project', '--config-dir', '--application-config-dir']);
+    const values = namedArguments(args.slice(2), ['--project', '--config-dir', '--app-config-dir', '--application-config-dir', '--workspace-root', '--environment']);
     invariantNamed(values, '--project', 'app config-init');
-    print(initializeApplicationConfig({ configRoot, projectRoot: values['--project'], applicationConfigRoot: values['--application-config-dir'] }));
+    print(initializeApplicationConfig({ configRoot, appConfigRoot, projectRoot: values['--project'], applicationConfigRoot: values['--application-config-dir'], workspaceRoot: values['--workspace-root'], environment: values['--environment'] ?? 'local' }));
     return;
   }
   if (command === 'workbench' && subcommand === 'projects') {
     const action = args[2];
-    const values = namedArguments(args.slice(3), ['--dyyto-root', '--file', '--output', '--plan', '--config-dir']);
+    const values = namedArguments(args.slice(3), ['--dyyto-root', '--file', '--output', '--plan', '--config-dir', '--app-config-dir']);
     if (action === 'init') print(initializeWorkbenchProjects({ configRoot }));
     else if (action === 'plan') {
       for (const key of ['--dyyto-root', '--file', '--output']) invariantNamed(values, key, 'workbench projects plan');
-      print(createWorkbenchProjectsPlan({ configRoot, dyytoRoot: values['--dyyto-root'], candidateFile: values['--file'], output: values['--output'] }));
+      print(createWorkbenchProjectsPlan({ configRoot, appConfigRoot, dyytoRoot: values['--dyyto-root'], candidateFile: values['--file'], output: values['--output'] }));
     } else if (action === 'apply') { invariantNamed(values, '--plan', 'workbench projects apply'); print(applyWorkbenchProjectsPlan({ configRoot, planFile: values['--plan'] })); }
     else if (action === 'verify') print(verifyWorkbenchProjects({ configRoot }));
     else throw new IdpError('IDP_WORKBENCH_ACTION_UNKNOWN', `未知工作台项目动作：${action ?? ''}`);
@@ -151,17 +164,17 @@ export async function main(args) {
   }
   if (command === 'local' && subcommand === 'app') {
     const action = args[2];
-    const values = namedArguments(args.slice(3), ['--project', '--compose-file', '--output', '--plan', '--confirm', '--config-dir', '--application-config-dir']);
+    const values = namedArguments(args.slice(3), ['--project', '--workspace-root', '--environment', '--compose-file', '--output', '--plan', '--confirm', '--config-dir', '--app-config-dir', '--application-config-dir']);
     if (action === 'plan') {
       for (const key of ['--project', '--compose-file', '--output']) invariantNamed(values, key, 'local app plan');
-      print(createLocalSourcePlan({ configRoot, applicationConfigRoot: values['--application-config-dir'], projectRoot: values['--project'], composeFile: values['--compose-file'], output: values['--output'] }));
+      print(createLocalSourcePlan({ configRoot, appConfigRoot, applicationConfigRoot: values['--application-config-dir'], projectRoot: values['--project'], workspaceRoot: values['--workspace-root'], environment: values['--environment'] ?? 'local', composeFile: values['--compose-file'], output: values['--output'] }));
       return;
     }
     invariantNamed(values, '--plan', `local app ${action ?? ''}`);
-    if (action === 'apply') print(applyLocalSourceDeployment({ configRoot, applicationConfigRoot: values['--application-config-dir'], planFile: values['--plan'] }));
-    else if (action === 'verify') print(verifyLocalSourceDeployment({ configRoot, applicationConfigRoot: values['--application-config-dir'], planFile: values['--plan'] }));
-    else if (action === 'stop') print(stopLocalSourceDeployment({ configRoot, applicationConfigRoot: values['--application-config-dir'], planFile: values['--plan'] }));
-    else if (action === 'remove') print(removeLocalSourceDeployment({ configRoot, applicationConfigRoot: values['--application-config-dir'], planFile: values['--plan'], confirmation: values['--confirm'] }));
+    if (action === 'apply') print(applyLocalSourceDeployment({ configRoot, appConfigRoot, applicationConfigRoot: values['--application-config-dir'], planFile: values['--plan'] }));
+    else if (action === 'verify') print(verifyLocalSourceDeployment({ configRoot, appConfigRoot, applicationConfigRoot: values['--application-config-dir'], planFile: values['--plan'] }));
+    else if (action === 'stop') print(stopLocalSourceDeployment({ configRoot, appConfigRoot, applicationConfigRoot: values['--application-config-dir'], planFile: values['--plan'] }));
+    else if (action === 'remove') print(removeLocalSourceDeployment({ configRoot, appConfigRoot, applicationConfigRoot: values['--application-config-dir'], planFile: values['--plan'], confirmation: values['--confirm'] }));
     else throw new IdpError('IDP_LOCAL_ACTION_UNKNOWN', `未知本地应用动作：${action ?? ''}`);
     return;
   }

package/src/local-source.mjs

@@ -4,6 +4,7 @@ import { IdpError, invariant } from './errors.mjs';
 import { hashFile, sha256, stableJson } from './hash.mjs';
 import { run } from './process.mjs';
 import { assertOutsideRepositories, assertSafeRegularFile, atomicWrite, canonicalPlannedDirectory, parseEnv, resolveContained, secureDirectoryRoot } from './security.mjs';
+import { resolveApplicationConfigDirectory } from './application-config-location.mjs';
 
 const APPLICATION_ID = /^[a-z0-9][a-z0-9._-]{0,127}$/u;
 const ENV_NAME = /^[A-Z][A-Z0-9_]{0,127}$/u;
@@ -72,12 +73,8 @@ function validateApplicationConfigContract(contract, manifest) {
   return contract;
 }
 
-function applicationDirectory(configRoot, id, { create = false, applicationConfigRoot } = {}) {
-  if (applicationConfigRoot) {
-    const app = secureDirectoryRoot(applicationConfigRoot, 'APP_CONFIG_DIR', { create });
-    assertOutsideRepositories(app, 'APP_CONFIG_DIR');
-    return { root: app, app };
-  }
+function applicationDirectory(configRoot, id, { create = false, applicationConfigRoot, appConfigRoot, projectRoot, workspaceRoot, environment = 'local' } = {}) {
+  if (applicationConfigRoot || appConfigRoot) return resolveApplicationConfigDirectory({ projectRoot, applicationId: id, appConfigRoot, applicationConfigRoot, workspaceRoot, environment, create });
   const root = secureDirectoryRoot(configRoot, 'IDP_CONFIG_DIR', { create });
   assertOutsideRepositories(root, 'IDP_CONFIG_DIR');
   const applications = resolveContained(root, 'applications', '应用配置目录');
@@ -96,9 +93,9 @@ function savePreimage(root, id, name, bytes) {
   return { path: candidate, digest };
 }
 
-export function initializeApplicationConfig({ configRoot, projectRoot, applicationConfigRoot }) {
+export function initializeApplicationConfig({ configRoot, appConfigRoot, projectRoot, applicationConfigRoot, workspaceRoot, environment = 'local' }) {
   const project = readProject(projectRoot);
-  const { root, app } = applicationDirectory(configRoot, project.contract.application.id, { create: true, applicationConfigRoot });
+  const { root, app, relativeDirectory, workspace } = applicationDirectory(configRoot, project.contract.application.id, { create: true, applicationConfigRoot, appConfigRoot, projectRoot: project.root, workspaceRoot, environment });
   for (const name of ['secrets', 'certs']) secureDirectoryRoot(path.join(app, name), `应用${name}目录`, { create: true });
   const envFile = path.join(app, '.env');
   const before = fs.existsSync(envFile) ? fs.readFileSync(envFile) : Buffer.from('');
@@ -121,11 +118,11 @@ export function initializeApplicationConfig({ configRoot, projectRoot, applicati
     preimage = savePreimage(root, project.contract.application.id, 'env', before);
     atomicWrite(envFile, `${before.toString('utf8').trimEnd()}\n# 由app config-init补齐；已有值未覆盖。\n${additions.join('\n')}\n`, 0o600);
   }
-  return { schemaVersion: 'idp.application-config-materialization/v1', status: 'ready', application: project.contract.application.id, directory: app, environmentFile: envFile, createdFiles, additions: additions.map((line) => line.slice(0, line.indexOf('='))), ...(preimage ? { preimage } : {}) };
+  return { schemaVersion: 'idp.application-config-materialization/v1', status: 'ready', application: project.contract.application.id, environment, directory: app, relativeDirectory, workspace: workspace ? { id: workspace.id, root: workspace.root, unitPath: workspace.unitPath } : null, environmentFile: envFile, createdFiles, additions: additions.map((line) => line.slice(0, line.indexOf('='))), ...(preimage ? { preimage } : {}) };
 }
 
-function inspectApplicationConfig(configRoot, contract, applicationConfigRoot) {
-  const { app } = applicationDirectory(configRoot, contract.application.id, { applicationConfigRoot });
+function inspectApplicationConfig(configRoot, contract, { applicationConfigRoot, appConfigRoot, projectRoot, workspaceRoot, environment = 'local' }) {
+  const { app } = applicationDirectory(configRoot, contract.application.id, { applicationConfigRoot, appConfigRoot, projectRoot, workspaceRoot, environment });
   const envFile = path.join(app, '.env');
   assertSafeRegularFile(envFile, 0o600, { allowEmpty: contract.bindings.length === 0, role: '应用.env' });
   const env = parseEnv(fs.readFileSync(envFile, 'utf8'), envFile);
@@ -152,16 +149,16 @@ function executeCompose(runner, args, cwd, capture = true) {
   return runner('docker', args, { cwd, capture, maxBuffer: 16 * 1024 * 1024 });
 }
 
-function normalizedCompose({ projectRoot, composeFile, envFile, composeProject, runner }) {
-  const result = executeCompose(runner, ['compose', '--project-name', composeProject, '--env-file', envFile, '--file', composeFile, 'config', '--format', 'json'], projectRoot, true);
+function normalizedCompose({ projectRoot, sourceRoot, composeFile, envFile, composeProject, runner }) {
+  const result = executeCompose(runner, ['compose', '--project-name', composeProject, '--env-file', envFile, '--file', composeFile, 'config', '--format', 'json'], sourceRoot, true);
   let document;
   try { document = JSON.parse(result.stdout); }
   catch (error) { throw new IdpError('IDP_LOCAL_COMPOSE_JSON_INVALID', 'docker compose未返回有效JSON', { cause: error.message }); }
-  validateCompose(document, projectRoot);
+  validateCompose(document, projectRoot, sourceRoot);
   return { document, bytes: `${stableJson(document)}\n` };
 }
 
-function validateCompose(document, projectRoot) {
+function validateCompose(document, projectRoot, sourceRoot) {
   const services = document?.services;
   invariant(services && typeof services === 'object' && Object.keys(services).length > 0, 'IDP_LOCAL_COMPOSE_INVALID', 'Compose必须至少声明一个服务');
   let healthchecks = 0;
@@ -173,9 +170,9 @@ function validateCompose(document, projectRoot) {
     if (service.build) {
       const context = typeof service.build === 'string' ? service.build : service.build.context;
       invariant(typeof context === 'string', 'IDP_LOCAL_COMPOSE_BUILD_INVALID', `服务${name}构建上下文无效`);
-      const absoluteContext = path.resolve(projectRoot, context);
-      const contextRelative = path.relative(projectRoot, absoluteContext);
-      invariant(contextRelative === '' || (!contextRelative.startsWith('..') && !path.isAbsolute(contextRelative)), 'IDP_LOCAL_COMPOSE_BUILD_OUTSIDE_PROJECT', `服务${name}构建上下文必须位于项目内`);
+      const absoluteContext = path.isAbsolute(context) ? context : path.resolve(projectRoot, context);
+      const contextRelative = path.relative(sourceRoot, absoluteContext);
+      invariant(contextRelative === '' || (!contextRelative.startsWith('..') && !path.isAbsolute(contextRelative)), 'IDP_LOCAL_COMPOSE_BUILD_OUTSIDE_WORKSPACE', `服务${name}构建上下文必须位于Workspace源码边界内`);
     }
     if (service.healthcheck && !service.healthcheck.disable) healthchecks += 1;
     for (const [key, value] of Object.entries(service.environment ?? {})) {
@@ -199,24 +196,27 @@ function validateCompose(document, projectRoot) {
 
 function planIdentity(core) { return sha256(stableJson(core)); }
 
-export function createLocalSourcePlan({ configRoot, applicationConfigRoot, projectRoot, composeFile, output, runner = run, now = new Date().toISOString() }) {
+export function createLocalSourcePlan({ configRoot, appConfigRoot, applicationConfigRoot, projectRoot, workspaceRoot, environment = 'local', composeFile, output, runner = run, now = new Date().toISOString() }) {
   const project = readProject(projectRoot);
+  const sourceRoot = workspaceRoot ? fs.realpathSync.native(workspaceRoot) : project.root;
+  const sourceRelative = path.relative(sourceRoot, project.root);
+  invariant(sourceRelative === '' || (!sourceRelative.startsWith('..') && !path.isAbsolute(sourceRelative)), 'IDP_LOCAL_PROJECT_OUTSIDE_WORKSPACE', '项目必须位于--workspace-root内');
   invariant(path.isAbsolute(composeFile ?? ''), 'IDP_LOCAL_COMPOSE_NOT_ABSOLUTE', '--compose-file必须是绝对路径');
   const composePath = fs.realpathSync.native(composeFile);
   const relativeCompose = path.relative(project.root, composePath);
   invariant(relativeCompose && !relativeCompose.startsWith('..') && !path.isAbsolute(relativeCompose), 'IDP_LOCAL_COMPOSE_OUTSIDE_PROJECT', 'Compose文件必须位于项目内');
   assertSafeRegularFile(composePath, 0o644, { allowEmpty: false, role: '本地Compose文件' });
-  const config = inspectApplicationConfig(configRoot, project.contract, applicationConfigRoot);
-  const composeProject = `idp-${project.contract.application.id}-local`.replace(/[^a-z0-9_-]/gu, '-').slice(0, 63);
-  const normalized = normalizedCompose({ projectRoot: project.root, composeFile: composePath, envFile: config.envFile, composeProject, runner });
+  const config = inspectApplicationConfig(configRoot, project.contract, { applicationConfigRoot, appConfigRoot, projectRoot: project.root, workspaceRoot, environment });
+  const composeProject = `idp-${project.contract.application.id}-${environment}`.replace(/[^a-z0-9_-]/gu, '-').slice(0, 63);
+  const normalized = normalizedCompose({ projectRoot: project.root, sourceRoot, composeFile: composePath, envFile: config.envFile, composeProject, runner });
   const core = {
     schemaVersion: PLAN_SCHEMA, mode: 'local-source', promotable: false, application: project.contract.application.id,
-    project: { root: project.root, sourceDigest: projectSourceDigest(project.root), manifest: { path: project.manifestFile, digest: hashFile(project.manifestFile) }, applicationConfigContract: { path: project.contractFile, digest: hashFile(project.contractFile) } },
+    project: { root: project.root, workspaceRoot: sourceRoot, unitPath: sourceRelative.split(path.sep).join('/') || '.', sourceDigest: projectSourceDigest(sourceRoot), manifest: { path: project.manifestFile, digest: hashFile(project.manifestFile) }, applicationConfigContract: { path: project.contractFile, digest: hashFile(project.contractFile) } },
     config: { directory: config.app, environmentFile: config.envFile, environmentDigest: config.envDigest, fileBindings: config.fileBindings },
     compose: { path: composePath, sourceDigest: hashFile(composePath), normalizedDigest: sha256(normalized.bytes) }, composeProject, createdAt: now,
   };
   const plan = { ...core, planId: planIdentity(core) };
-  const { root } = applicationDirectory(configRoot, project.contract.application.id, { applicationConfigRoot });
+  const { root } = applicationDirectory(configRoot, project.contract.application.id, { applicationConfigRoot, appConfigRoot, projectRoot: project.root, workspaceRoot, environment });
   invariant(path.isAbsolute(output ?? ''), 'IDP_LOCAL_PLAN_OUTPUT_NOT_ABSOLUTE', '--output必须是绝对路径');
   const plans = resolveContained(root, 'plans/local-applications', '本地应用Plan目录');
   secureDirectoryRoot(plans, '本地应用Plan目录', { create: true });
@@ -228,27 +228,28 @@ export function createLocalSourcePlan({ configRoot, applicationConfigRoot, proje
   return plan;
 }
 
-function readPlan(configRoot, planFile, applicationConfigRoot) {
+function readPlan(configRoot, planFile, applicationConfigRoot, appConfigRoot) {
   invariant(path.isAbsolute(planFile ?? ''), 'IDP_LOCAL_PLAN_NOT_ABSOLUTE', '--plan必须是绝对路径');
-  const { root } = applicationDirectory(configRoot, 'placeholder', { applicationConfigRoot });
-  const plans = resolveContained(root, 'plans/local-applications', '本地应用Plan目录');
   const candidate = fs.realpathSync.native(planFile);
-  const relative = path.relative(plans, candidate);
-  invariant(relative && !relative.startsWith('..') && !path.isAbsolute(relative), 'IDP_LOCAL_PLAN_OUTSIDE_CONFIG', 'Plan必须位于IDP_CONFIG_DIR/plans/local-applications');
   assertSafeRegularFile(candidate, 0o600, { allowEmpty: false, role: 'Local DeploymentPlan' });
   const plan = readJson(candidate, 'Local DeploymentPlan');
   invariant(plan.schemaVersion === PLAN_SCHEMA && plan.mode === 'local-source' && plan.promotable === false, 'IDP_LOCAL_PLAN_INVALID', 'Local DeploymentPlan版本无效');
   const { planId, ...core } = plan;
   invariant(planIdentity(core) === planId, 'IDP_LOCAL_PLAN_DIGEST_INVALID', 'Local DeploymentPlan摘要无效');
-  return { plan, candidate, root };
+  const root = applicationConfigRoot ? secureDirectoryRoot(applicationConfigRoot, '应用最终Config Dir') : appConfigRoot ? secureDirectoryRoot(appConfigRoot, 'APP_CONFIG_DIR') : secureDirectoryRoot(configRoot, 'IDP_CONFIG_DIR');
+  const plans = appConfigRoot && !applicationConfigRoot ? path.join(plan.config.directory, 'plans/local-applications') : resolveContained(root, 'plans/local-applications', '本地应用Plan目录');
+  const relative = path.relative(plans, candidate);
+  invariant(relative && !relative.startsWith('..') && !path.isAbsolute(relative), 'IDP_LOCAL_PLAN_OUTSIDE_CONFIG', 'Plan必须位于应用Config Dir的plans/local-applications');
+  const runtimeRoot = appConfigRoot && !applicationConfigRoot ? plan.config.directory : root;
+  return { plan, candidate, root: runtimeRoot };
 }
 
 function revalidate(plan, runner) {
-  invariant(projectSourceDigest(plan.project.root) === plan.project.sourceDigest, 'IDP_LOCAL_SOURCE_CHANGED', '项目构建源已变化，请重新生成Plan');
+  invariant(projectSourceDigest(plan.project.workspaceRoot ?? plan.project.root) === plan.project.sourceDigest, 'IDP_LOCAL_SOURCE_CHANGED', 'Workspace构建源已变化，请重新生成Plan');
   invariant(hashFile(plan.project.manifest.path) === plan.project.manifest.digest && hashFile(plan.project.applicationConfigContract.path) === plan.project.applicationConfigContract.digest && hashFile(plan.compose.path) === plan.compose.sourceDigest, 'IDP_LOCAL_INPUT_CHANGED', '项目Manifest、配置合同或Compose已变化，请重新生成Plan');
   invariant(hashFile(plan.config.environmentFile) === plan.config.environmentDigest, 'IDP_LOCAL_CONFIG_CHANGED', '应用.env已变化，请重新生成Plan');
   for (const binding of plan.config.fileBindings) invariant(hashFile(path.join(plan.config.directory, binding.path)) === binding.digest, 'IDP_LOCAL_CONFIG_CHANGED', `${binding.name}已变化，请重新生成Plan`);
-  const normalized = normalizedCompose({ projectRoot: plan.project.root, composeFile: plan.compose.path, envFile: plan.config.environmentFile, composeProject: plan.composeProject, runner });
+  const normalized = normalizedCompose({ projectRoot: plan.project.root, sourceRoot: plan.project.workspaceRoot ?? plan.project.root, composeFile: plan.compose.path, envFile: plan.config.environmentFile, composeProject: plan.composeProject, runner });
   invariant(sha256(normalized.bytes) === plan.compose.normalizedDigest, 'IDP_LOCAL_COMPOSE_RENDER_CHANGED', 'Compose规范化结果已变化，请重新生成Plan');
   return normalized;
 }
@@ -289,11 +290,11 @@ function activeState(root, plan, { required = true } = {}) {
   return { candidate, bytes, state };
 }
 
-export function verifyLocalSourceDeployment({ configRoot, applicationConfigRoot, planFile, runner = run, requireActiveState = true }) {
-  const { plan, root } = readPlan(configRoot, planFile, applicationConfigRoot);
+export function verifyLocalSourceDeployment({ configRoot, appConfigRoot, applicationConfigRoot, planFile, runner = run, requireActiveState = true }) {
+  const { plan, root } = readPlan(configRoot, planFile, applicationConfigRoot, appConfigRoot);
   revalidate(plan, runner);
   activeState(root, plan, { required: requireActiveState });
-  const ps = parsePs(executeCompose(runner, composeArgs(plan, ['ps', '--format', 'json']), plan.project.root, true).stdout);
+  const ps = parsePs(executeCompose(runner, composeArgs(plan, ['ps', '--format', 'json']), plan.project.workspaceRoot ?? plan.project.root, true).stdout);
   invariant(ps.length > 0, 'IDP_LOCAL_DEPLOYMENT_NOT_RUNNING', '本地应用没有运行中的Compose服务');
   for (const service of ps) {
     const state = String(service.State ?? service.state ?? '').toLowerCase();
@@ -304,8 +305,8 @@ export function verifyLocalSourceDeployment({ configRoot, applicationConfigRoot,
   return evidence(root, plan, 'verify', 'verified', { services: ps.map((item) => item.Service ?? item.Name).filter(Boolean) });
 }
 
-export function applyLocalSourceDeployment({ configRoot, applicationConfigRoot, planFile, runner = run }) {
-  const { plan, root, candidate: canonicalPlanFile } = readPlan(configRoot, planFile, applicationConfigRoot);
+export function applyLocalSourceDeployment({ configRoot, appConfigRoot, applicationConfigRoot, planFile, runner = run }) {
+  const { plan, root, candidate: canonicalPlanFile } = readPlan(configRoot, planFile, applicationConfigRoot, appConfigRoot);
   revalidate(plan, runner);
   const current = activeState(root, plan, { required: false });
   const stateFile = current.candidate;
@@ -313,41 +314,41 @@ export function applyLocalSourceDeployment({ configRoot, applicationConfigRoot,
   const preimageFile = path.join(path.dirname(stateFile), `.${plan.application}.${plan.planId.slice(7, 19)}.preimage.json`);
   if (before) atomicWrite(preimageFile, before, 0o600);
   try {
-    executeCompose(runner, composeArgs(plan, ['build']), plan.project.root, false);
-    executeCompose(runner, composeArgs(plan, ['up', '-d', '--wait', '--remove-orphans']), plan.project.root, false);
+    executeCompose(runner, composeArgs(plan, ['build']), plan.project.workspaceRoot ?? plan.project.root, false);
+    executeCompose(runner, composeArgs(plan, ['up', '-d', '--wait', '--remove-orphans']), plan.project.workspaceRoot ?? plan.project.root, false);
     const afterCommands = fs.existsSync(stateFile) ? fs.readFileSync(stateFile) : null;
     invariant((before === null && afterCommands === null) || (before !== null && afterCommands !== null && before.equals(afterCommands)), 'IDP_LOCAL_RUNTIME_STATE_CHANGED', '执行期间运行态被并发修改，拒绝提交Receipt');
-    const receipt = verifyLocalSourceDeployment({ configRoot, applicationConfigRoot, planFile, runner, requireActiveState: false });
+    const receipt = verifyLocalSourceDeployment({ configRoot, appConfigRoot, applicationConfigRoot, planFile, runner, requireActiveState: false });
     atomicWrite(stateFile, `${JSON.stringify({ schemaVersion: 'idp.local-source-runtime/v1', application: plan.application, planId: plan.planId, composeProject: plan.composeProject, composeFile: plan.compose.path, planFile: canonicalPlanFile, receiptId: receipt.receiptId }, null, 2)}\n`, 0o600);
     return evidence(root, plan, 'apply', 'verified', { verifyReceiptId: receipt.receiptId });
   } catch (error) {
     try {
       if (before && current.state?.planFile) {
-        const previous = readPlan(configRoot, current.state.planFile, applicationConfigRoot).plan;
+        const previous = readPlan(configRoot, current.state.planFile, applicationConfigRoot, appConfigRoot).plan;
         revalidate(previous, runner);
-        executeCompose(runner, composeArgs(previous, ['up', '-d', '--wait', '--remove-orphans']), previous.project.root, false);
+        executeCompose(runner, composeArgs(previous, ['up', '-d', '--wait', '--remove-orphans']), previous.project.workspaceRoot ?? previous.project.root, false);
       }
-      else executeCompose(runner, composeArgs(plan, ['down', '--remove-orphans']), plan.project.root, false);
+      else executeCompose(runner, composeArgs(plan, ['down', '--remove-orphans']), plan.project.workspaceRoot ?? plan.project.root, false);
     } catch {}
     evidence(root, plan, 'apply', 'failed', { code: error.code ?? 'IDP_PROCESS_FAILED' });
     throw error;
   }
 }
 
-export function stopLocalSourceDeployment({ configRoot, applicationConfigRoot, planFile, runner = run }) {
-  const { plan, root } = readPlan(configRoot, planFile, applicationConfigRoot);
+export function stopLocalSourceDeployment({ configRoot, appConfigRoot, applicationConfigRoot, planFile, runner = run }) {
+  const { plan, root } = readPlan(configRoot, planFile, applicationConfigRoot, appConfigRoot);
   revalidate(plan, runner);
   activeState(root, plan);
-  executeCompose(runner, composeArgs(plan, ['stop']), plan.project.root, false);
+  executeCompose(runner, composeArgs(plan, ['stop']), plan.project.workspaceRoot ?? plan.project.root, false);
   return evidence(root, plan, 'stop', 'stopped');
 }
 
-export function removeLocalSourceDeployment({ configRoot, applicationConfigRoot, planFile, confirmation, runner = run }) {
-  const { plan, root } = readPlan(configRoot, planFile, applicationConfigRoot);
+export function removeLocalSourceDeployment({ configRoot, appConfigRoot, applicationConfigRoot, planFile, confirmation, runner = run }) {
+  const { plan, root } = readPlan(configRoot, planFile, applicationConfigRoot, appConfigRoot);
   invariant(confirmation === plan.application, 'IDP_LOCAL_REMOVE_CONFIRMATION_REQUIRED', `remove必须通过--confirm ${plan.application}精确确认`);
   revalidate(plan, runner);
   activeState(root, plan);
-  executeCompose(runner, composeArgs(plan, ['down', '--remove-orphans']), plan.project.root, false);
+  executeCompose(runner, composeArgs(plan, ['down', '--remove-orphans']), plan.project.workspaceRoot ?? plan.project.root, false);
   const candidate = statePath(root, plan.application);
   if (fs.existsSync(candidate)) fs.unlinkSync(candidate);
   return evidence(root, plan, 'remove', 'removed', { volumesRemoved: false });

package/src/workbench-projects.mjs

@@ -25,7 +25,7 @@ export function initializeWorkbenchProjects({ configRoot: input }) {
   return { schemaVersion: 'idp.workbench-project-candidate/v1', status: 'ready', candidate };
 }
 
-function readCandidate(root, file) {
+function readCandidate(root, file, appConfigRoot) {
   invariant(path.isAbsolute(file ?? ''), 'IDP_WORKBENCH_CANDIDATE_NOT_ABSOLUTE', '--file必须是绝对路径');
   const workbench = resolveContained(root, 'workbench', '工作台配置目录'); const candidate = fs.realpathSync.native(file);
   const relative = path.relative(workbench, candidate); invariant(relative && !relative.startsWith('..') && !path.isAbsolute(relative), 'IDP_WORKBENCH_CANDIDATE_OUTSIDE_CONFIG', 'candidate必须位于IDP_CONFIG_DIR/workbench');
@@ -46,7 +46,8 @@ function readCandidate(root, file) {
       const applicationRoot = fs.realpathSync.native(path.resolve(hostPath, relativePath));
       invariant(applicationRoot === hostPath || applicationRoot.startsWith(`${hostPath}${path.sep}`), 'IDP_WORKBENCH_PROJECT_RELATIVE_PATH_ESCAPE', `项目${item.id}的应用路径逃逸项目目录`);
       invariant(fs.existsSync(path.join(applicationRoot, 'project-capabilities.json')), 'IDP_WORKBENCH_APPLICATION_INVALID', `项目${item.id}的${relativePath}缺少project-capabilities.json`);
-      const applicationConfigDir = safeDirectory(binding.applicationConfigDir, `项目${item.id}/${relativePath} Config Dir`); assertOutsideRepositories(applicationConfigDir, `项目${item.id}/${relativePath} Config Dir`);
+      const derived = appConfigRoot ? path.join(appConfigRoot, item.id, ...(relativePath === '.' ? [] : relativePath.split('/')), 'local') : undefined;
+      const applicationConfigDir = safeDirectory(binding.applicationConfigDir ?? derived, `项目${item.id}/${relativePath} Config Dir`); assertOutsideRepositories(applicationConfigDir, `项目${item.id}/${relativePath} Config Dir`);
       return { relativePath, applicationConfigDir, containerPath: relativePath === '.' ? `/workspaces/${item.id}` : `/workspaces/${item.id}/${relativePath}`, configDirectory: `/config/applications/${item.id}-${index}/local` };
     });
     return { id: item.id, hostPath, containerPath: `/workspaces/${item.id}`, configBindings };
@@ -54,10 +55,12 @@ function readCandidate(root, file) {
   return { candidate, projects };
 }
 
-export function createWorkbenchProjectsPlan({ configRoot: input, dyytoRoot, candidateFile, output, now = new Date().toISOString() }) {
+export function createWorkbenchProjectsPlan({ configRoot: input, appConfigRoot, dyytoRoot, candidateFile, output, now = new Date().toISOString() }) {
   const root = configRoot(input), dyyto = safeDirectory(dyytoRoot, 'Dyyto仓库');
   invariant(fs.existsSync(path.join(dyyto, 'compose.yaml')), 'IDP_WORKBENCH_DYYTO_INVALID', 'Dyyto仓库缺少compose.yaml');
-  const candidate = readCandidate(root, candidateFile);
+  const applications = appConfigRoot ? safeDirectory(appConfigRoot, 'APP_CONFIG_DIR') : undefined;
+  if (applications) assertOutsideRepositories(applications, 'APP_CONFIG_DIR');
+  const candidate = readCandidate(root, candidateFile, applications);
   const core = { schemaVersion: 'idp.workbench-project-plan/v1', dyytoRoot: dyyto, dyytoComposeDigest: hashFile(path.join(dyyto, 'compose.yaml')), candidate: { path: candidate.candidate, digest: hashFile(candidate.candidate) }, projects: candidate.projects, createdAt: now };
   const plan = { ...core, planId: sha256(stableJson(core)) };
   const plans = resolveContained(root, 'plans/workbench-projects', '工作台Plan目录'); secureDirectoryRoot(plans, '工作台Plan目录', { create: true });