modelstudioai · chenanran555 · Aug 15, 2026 · Aug 18, 2026 · Aug 24, 2026 · Aug 24, 2026
diff --git a/.changeset/config.json b/.changeset/config.json
@@ -2,7 +2,15 @@
 	"$schema": "https://unpkg.com/@changesets/config@3.1.1/schema.json",
 	"changelog": "@changesets/cli/changelog",
 	"commit": false,
-	"fixed": [["@openagentpack/sdk", "@openagentpack/playground", "@openagentpack/cli"]],
+	"fixed": [
+		[
+			"@openagentpack/sdk",
+			"@openagentpack/project-versions",
+			"@openagentpack/project-workspace",
+			"@openagentpack/playground",
+			"@openagentpack/cli"
+		]
+	],
 	"linked": [],
 	"access": "public",
 	"baseBranch": "main",

diff --git a/.changeset/project-playground-debugger.md b/.changeset/project-playground-debugger.md
@@ -0,0 +1,9 @@
+---
+"@openagentpack/sdk": minor
+"@openagentpack/playground": minor
+"@openagentpack/cli": minor
+---
+
+Replace the fixed Playbook showcase with project-aware debugging. `agents playground` remains a read-only `agents.yaml` Session Preview, while `agents project workbench` watches and edits a directory project, performs fingerprint-protected Build/Plan/Publish operations, streams operation and Session events, and manages explicit temporary attachment cleanup.
+
+Add SDK source-path tracking, runtime-scoped Agent planning, full-project planning, stable plan fingerprints, and stale-plan enforcement. Preview stays at `agents playground -f/--file [--agent <id>]`; the project console moves under `agents project workbench --project <directory>`.
diff --git a/.changeset/project-versions-package.md b/.changeset/project-versions-package.md
@@ -0,0 +1,13 @@
+---
+"@openagentpack/sdk": minor
+"@openagentpack/project-versions": minor
+"@openagentpack/project-workspace": minor
+"@openagentpack/playground": minor
+"@openagentpack/cli": minor
+---
+
+Publish a directory workspace service for deterministic Build/Publish and a
+Git-independent full source-tree snapshot engine. CLI and Workbench share one
+versioning switch, content-addressed text/binary blobs, forward restore, and a
+cross-process mutation lock while remote State remains excluded. Project Build
+previews now show full directory source changes against the current version HEAD.
diff --git a/.changeset/workbench-resource-editing.md b/.changeset/workbench-resource-editing.md
@@ -0,0 +1,5 @@
+---
+"@openagentpack/playground": minor
+---
+
+Add Workbench editing and removal for resources already present in a directory project. Agent JSON, instructions Markdown, Skill metadata/content, and project resources use server-side redacted previews, revision conflicts, reference protection, explicit Build, full-project Plan, and separately confirmed Publish.
diff --git a/.dependency-cruiser.cjs b/.dependency-cruiser.cjs
@@ -4,14 +4,14 @@ module.exports = {
 		{
 			name: "no-cli-to-server",
 			severity: "error",
-			comment: "The CLI host must consume shared behavior through @openagentpack/sdk, not by importing the API server.",
+			comment: "The CLI host must consume shared behavior through published engine packages, not the API server.",
 			from: { path: "^packages/cli/" },
 			to: { path: "^apps/server/" },
 		},
 		{
 			name: "no-server-to-cli",
 			severity: "error",
-			comment: "The API server must consume shared behavior through @openagentpack/sdk, not by importing CLI code.",
+			comment: "The API server must consume shared behavior through published engine packages, not CLI code.",
 			from: { path: "^apps/server/" },
 			to: { path: "^packages/cli/" },
 		},
@@ -22,6 +22,21 @@ module.exports = {
 			from: { path: "^packages/sdk/" },
 			to: { path: "^(packages/cli|apps/server|apps/webui)/" },
 		},
+		{
+			name: "no-project-versions-to-hosts-or-apps",
+			severity: "error",
+			comment:
+				"@openagentpack/project-versions is a shared Node engine and must not depend on host packages or applications.",
+			from: { path: "^packages/project-versions/" },
+			to: { path: "^(packages/cli|packages/playground|apps/server|apps/webui)/" },
+		},
+		{
+			name: "no-project-workspace-to-hosts-or-apps",
+			severity: "error",
+			comment: "@openagentpack/project-workspace is a shared Node engine and must not depend on hosts or applications.",
+			from: { path: "^packages/project-workspace/" },
+			to: { path: "^(packages/cli|packages/playground|apps/server|apps/webui)/" },
+		},
 		{
 			name: "no-sdk-deep-imports",
 			severity: "error",
@@ -42,6 +57,20 @@ module.exports = {
 			from: { path: "^apps/webui/src/" },
 			to: { path: "^packages/sdk/" },
 		},
+		{
+			name: "no-webui-project-versions-runtime-import",
+			severity: "error",
+			comment: "Browser-facing code must use Workbench APIs instead of importing the Node-only version engine.",
+			from: { path: "^apps/webui/src/" },
+			to: { path: "^packages/project-versions/" },
+		},
+		{
+			name: "no-webui-project-workspace-runtime-import",
+			severity: "error",
+			comment: "Browser-facing code must use Workbench APIs instead of importing the Node-only workspace engine.",
+			from: { path: "^apps/webui/src/" },
+			to: { path: "^packages/project-workspace/" },
+		},
 	],
 	options: {
 		doNotFollow: {

@@ -58,7 +58,7 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          # Full consumer smoke (sdk + playground + cli) on the repo baseline.
+          # Full consumer smoke (sdk + local-git + playground + cli) on the repo baseline.
           - node: 22
             scope: all
           - node: 24

diff --git a/README.md b/README.md
@@ -77,14 +77,19 @@ The mechanics are a single `agents.yaml`, a `validate → plan → apply` workfl
 ## Quick start
 
 ```bash
-agents init            # interactive wizard writes a starter agents.yaml
-agents validate        # offline YAML check, no API calls
-agents plan            # preview create / update / delete
-agents apply -y        # apply changes
-agents destroy         # tear down managed resources
+agents project init             # create a directory project (or convert agents.yaml)
+agents project validate         # validate JSON, Markdown, skills, and local files
+agents project build --dry-run  # preview organization and generated YAML
+agents project build -y         # freeze the current source into a Build
+agents project publish -y       # publish exactly that Build and record a version
+agents project workbench        # edit and debug the same directory project
 ```
 
-Run `agents playground` to launch the local WebUI, and use `--provider` to target `bailian`, `qoder`, `ark`, or `claude`. You can switch providers on the same declaration, run real sessions, and observe tool calls and artifacts.
+Directory projects keep global settings in `project.json`, each Agent under `agents/<id>/`, Agent instructions in `instructions.md`, and local Skill source either beside its Agent or under the shared `skills/` directory. Build promotes a Skill to the shared directory when multiple Agents reference it and deterministically writes `.openagentpack/build/agents.yaml`. Publish never runs Build implicitly.
+
+Workbench and CLI share `agents project version status|enable|disable|list|preview|restore`. Versions are Git-independent full source-tree snapshots: immutable manifests point to content-addressed text and binary blobs, while `.openagentpack/state.json` is always excluded. Restore writes a historical tree forward into the working directory without moving version history or remote State. Deployment and Channel declarations remain read-only in Workbench but participate in full project Publish.
+
+The original YAML workflow remains available through `agents init`, `validate`, `plan`, `apply`, and `destroy`. `agents playground -f agents.yaml` continues to open a YAML Agent Session Preview, but YAML Apply no longer creates project versions and cannot be used inside a directory-project root.
 
 ▶ [Watch the full Playground demo](https://github.com/user-attachments/assets/bf51b8d8-f2ed-464b-bca9-0709fefcc44d)
 
@@ -172,28 +177,31 @@ The [`examples/`](./examples) directory has runnable configs for every provider,
 
 ## Using the SDK
 
-Everything the CLI does is available programmatically from `@openagentpack/sdk`:
+Cloud runtime capabilities are available from `@openagentpack/sdk`. Directory compilation, Build/Publish, and full-tree versions are exposed by `@openagentpack/project-workspace`, backed by the storage primitives in `@openagentpack/project-versions`:
 
 ```ts
-import { resolveProjectConfig, planProjectContext } from "@openagentpack/sdk";
-
-const config = await resolveProjectConfig({ configPath: "agents.yaml" });
-const plan = await planProjectContext(config);
-console.log(plan);
+import { previewProjectBuild, commitProjectBuild } from "@openagentpack/project-workspace";
+
+const preview = await previewProjectBuild("./my-agent");
+const build = await commitProjectBuild({
+  projectRoot: preview.project_root,
+  baseRevision: preview.project_revision,
+});
+console.log(build.manifest);
 ```
 
 See the [SDK reference](./docs/reference/sdk.md) for the public API surface.
 
 ## WebUI
 
-`apps/webui` is a Vite single-page app for browsing playbooks and driving agent sessions; `apps/server` exposes the SDK over an OpenAPI surface. Run both from the repo root:
+`apps/webui` is a Vite directory-project Workbench; `apps/server` exposes directory editing, Build/Publish, versions, and Session debugging over an OpenAPI surface. Run both from the repo root with `AGENTS_PROJECT_ROOT` pointing at a project:
 
 ```bash
 bun install
 bun run dev        # server + webui together
 ```
 
-Or launch a packaged local UI with `agents playground --provider <bailian|qoder|ark|claude>`.
+Launch the packaged project console with `agents project workbench --project <directory>`. Use `agents playground -f <path/to/agents.yaml>` only for the legacy YAML Session Preview. Workbench edits directory source, requires an explicit Build, and publishes the reviewed Build; it never edits Provider ownership or pushes Git state.
 
 ## Contributing
 

diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -81,10 +81,13 @@ agents init            # 交互式向导生成 agents.yaml
 agents validate        # 离线校验，不发起 API 调用
 agents plan            # 预览 create / update / delete
 agents apply -y        # 执行变更
+agents version enable  # 可选：成功 Apply 后版本化 YAML
 agents destroy         # 销毁托管资源
 ```
 
-运行 `agents playground` 可启动本地 WebUI，并通过 `--provider` 指定 `bailian`、`qoder`、`ark` 或 `claude`。你可以在同一份声明上切换 Provider、运行真实 Session，并观察工具调用和 Artifact。
+运行 `agents playground -f agents.yaml` 会直接打开 Agent Preview：单 Agent 项目自动选择，多 Agent 项目可传 `--agent <id>`，未指定时进入 Workbench 选择。使用 `agents workbench -f agents.yaml` 可直接打开项目控制台且不创建 Session。Playground 从 YAML 读取全部 Agent 和 Provider，并监听本地依赖文件。Workbench 的 Resources 页面可以通过服务端生成的 YAML Diff 编辑或移除已有声明；保存更新 `agents.yaml` 并自动刷新项目 Plan。本地版本默认不存在，只有用户在 Versions 页面或通过 `agents version enable` 显式启用后才会创建基线；开关启用时，成功 Apply 后自动版本化有变化的 YAML。Versions 页面与 CLI 共用开关，并浏览和恢复历史。
+
+CLI 也提供 `agents version status|enable|disable|list|preview|restore`。Workbench 与 CLI 按当前 `agents.yaml` 共用一个本地开关：`agents version enable` 会在需要时创建基线并开启两边的成功 Apply 自动版本，`version disable` 会同时关闭两边。`store.json` 只保存开关和 head，`entries/` 保存不可变链式元数据，完整 YAML 保存在内容寻址的 `blobs/` 中，因此不依赖 Git。Restore 只把历史 YAML 写回工作区，不移动版本历史；`agents.state.json` 和外部引用文件始终不进入版本。Deployment 和 Channel 声明继续只读，且不进入 Workbench 项目 Apply。配置缺失或非法时进入诊断 Workbench。
 
 ▶ [观看 Playground 完整演示](https://github.com/user-attachments/assets/bf51b8d8-f2ed-464b-bca9-0709fefcc44d)
 
@@ -172,10 +175,11 @@ Beta 用户可以安装 `@openagentpack/cli@beta`；固定版本及切回稳定
 
 ## 使用 SDK
 
-CLI 的全部能力都可通过 `@openagentpack/sdk` 以编程方式调用：
+云端项目运行能力可通过 `@openagentpack/sdk` 以编程方式调用；仅限 Node.js 的本地项目版本能力由独立包 `@openagentpack/project-versions` 提供：
 
 ```ts
 import { resolveProjectConfig, planProjectContext } from "@openagentpack/sdk";
+import { createProjectVersionService } from "@openagentpack/project-versions";
 
 const config = await resolveProjectConfig({ configPath: "agents.yaml" });
 const plan = await planProjectContext(config);
@@ -186,14 +190,14 @@ console.log(plan);
 
 ## WebUI
 
-`apps/webui` 是一个 Vite 单页应用，用于浏览 playbook 和驱动 Agent Session；`apps/server` 通过 OpenAPI 暴露 SDK。从仓库根目录同时启动两者：
+`apps/webui` 是一个 Vite 单页项目工作台，用于检查和调试 `agents.yaml` 中声明的 Agent；`apps/server` 通过 OpenAPI 暴露 SDK。从仓库根目录同时启动两者：
 
 ```bash
 bun install
 bun run dev        # 同时启动 server + webui
 ```
 
-或用 `agents playground --provider <bailian|qoder|ark|claude>` 启动打包的本地 UI。
+也可以用 `agents playground -f <path/to/agents.yaml>` 打开打包后的 Preview，或用 `agents workbench -f <path/to/agents.yaml>` 打开项目控制台。Provider、模型、工具、memory、skills 和资源全部来自 YAML，UI 不提供覆盖；Deployment 声明仅只读展示。
 
 ## 参与贡献