@zihanw/pi-forge 0.4.0-beta.1 → 0.4.1

package/docs/reference/subagent-adapter.md

@@ -0,0 +1,204 @@
+# Subagent adapter contract
+
+Status: experimental exported pure contract and host-preparation utilities for 0.4. This is a narrow one-shot delegation boundary, not a background orchestration runner or an OS sandbox.
+
+> **Migration note (0.4):** execution ownership — backend registration, preflight binding, plan sealing, conversation/execution fingerprint issuance, lifecycle arbitration, and both fresh-process backends (`pi-subprocess-readonly`, `pi-rpc-readonly`) — lives in [`@zihanw/pi-subagent-runtime`](https://github.com/MacroSony/pi-subagent-runtime). Forge keeps the host surface described here (profiles, compilation, approval, plan/response product types) and consumes the runtime through its public API. The former in-package `SubagentBackendRegistry`, `PiSubprocessBackend`, and `PiSdkIsolatedBackend` exports no longer ship. Sections 8-9 below describe the superseded in-package design and remain as historical context.
+
+## Public Surface
+
+New integrations should import this experimental 0.4 surface from `@zihanw/pi-forge/subagent`. The package root re-exports the same names through 0.4 for compatibility. Stability classifications and compatibility-path policy are recorded in the [public API policy](public-api.md).
+
+The package root exports:
+
+- `AgentRequest`, `AgentProfileSnapshot`, `BackendPreflightResult`, `AgentExecutionPlan`, and `AgentResponse`.
+- Granular access, limit, tool, media, context, artifact, trace, usage, and diagnostic types.
+- Host resolution through `resolveSubagentHostProfile()`.
+- Tool negotiation through `negotiateSubagentTools()`.
+- Deterministic context preparation through `budgetSubagentContext()`, `renderSubagentSelectedContext()`, and `prepareSubagentInitialMessages()`.
+- Protected Pi-message helpers.
+- Plan construction through `createAgentExecutionPlan()`.
+- Pure request, snapshot, preflight, plan, response, artifact, and trace validators. Portable leaf validators (access, limits, prompt runtime, descriptors, enforcement) are re-exported from the runtime core so one implementation serves both packages.
+- Canonical `sha256:v1` profile, stack, and prompt-runtime fingerprints.
+- Host preparation through `prepareSubagentHostPlan()`.
+
+The existing `agentProfileFingerprint()` remains unchanged. It is still the legacy JSON provenance value used for branch drift. Portable fingerprints use separately named functions and semantics.
+
+Conversation and execution fingerprints are **not** host-computed: they are issued by `@zihanw/pi-subagent-runtime` when it seals a prepared plan and are passed into `createAgentExecutionPlan()` as required inputs. The host validates their shape and propagates them; substitution detection is the runtime's sealed-plan binding.
+
+## Required Flow
+
+```text
+AgentRequest
+    -> resolveSubagentHostProfile
+    -> ExecutionRuntime.prepare (explicit backendId; backend preflight;
+       backend-assisted host compilation through the compile callback)
+    -> runtime sealing (conversation + execution fingerprints)
+    -> createAgentExecutionPlan (host plan carrying the sealed fingerprints)
+    -> host approval bound to the sealed fingerprints
+    -> ExecutionRuntime.execute
+    -> validateAgentResponse
+```
+
+No stage may substitute parent-runtime model objects, credentials, source file paths, or raw session history for the portable artifacts.
+
+### 1. Request validation
+
+`validateAgentRequest()` checks:
+
+- Schema, IDs, task text/media references, and media digests.
+- Explicit selected-context byte budgets and provenance.
+- Delegation depth.
+- Access-level/workspace/working-directory/network/process combinations.
+- Required versus best-effort hard limits.
+- Result-projection bounds and remote-egress consent.
+
+Media references are opaque host resources with content digests. The contract does not place local absolute paths or media bytes in the portable request.
+
+### 2. Host resolution
+
+`resolveSubagentHostProfile()` performs only backend-independent work:
+
+- Validates the loaded profile and exact prompt-stack reference.
+- Accepts null, default/replace, append, and prepend stack modes.
+- Scans prompt-stack items for custom macro and slot dependencies.
+- Requires those registrations to be loaded before final resolution.
+- Produces a path-free immutable profile snapshot and portable fingerprints.
+
+It deliberately does not inspect a model registry, authentication, backend tools, mounts, or limits. Parent `/profile use` resolution remains separate.
+
+Unknown macro commands and custom slots are treated as missing subagent dependencies. Static stack variables and built-in macros/slots are excluded. Custom registrations without a `source` still resolve but produce a warning because their dependency identity is anonymous.
+
+### 3. Backend preflight
+
+An accepted `BackendPreflightResult` must identify the exact model/thinking level, dynamic tool catalog, granular capabilities, effective access receipt, and accepted limit receipt.
+
+`validateBackendPreflight()` enforces:
+
+- Exact profile model and thinking-level agreement.
+- Explicit consent for remote provider transport.
+- Requested media MIME support.
+- No missing, extra, upgraded, or mode-mismatched mounts.
+- Working-directory containment through backend mount IDs.
+- Read/write, symlink, process, and denied-network enforcement claims.
+- Every required limit uses `backend-hard` enforcement.
+- Best-effort limits are reported honestly, such as Pi SDK host-abort timeouts.
+- Rejected preflight results contain at least one error diagnostic.
+
+Prompt tool filtering is not accepted as an access receipt.
+
+### 4. Tool negotiation
+
+Each backend tool declares a stable backend ID, policy-facing name, and effects:
+
+- `filesystem-read`
+- `filesystem-write`
+- `process`
+- `network`
+
+`negotiateSubagentTools()` applies prompt-stack policy to names, then removes tools whose declared effects exceed request access. Effect-free tools may remain under filesystem access `none`; network and process are independently controlled. Unmatched allow patterns remain warnings.
+
+Adapters must classify tool effects conservatively. A tool with undeclared effects invalidates the backend's enforcement claim even if name filtering succeeds.
+
+### 5. Context and exact preparation
+
+`budgetSubagentContext()` measures the exact UTF-8 bytes of the rendered selected-context envelope. Required items are retained first. Optional items are considered newest-to-oldest without partial item truncation, and returned in original order. Required overflow fails preparation.
+
+`prepareSubagentInitialMessages()` creates:
+
+1. One quoted selected-context message when the budget retains context.
+2. Host-prepared prompt-stack messages.
+3. The complete protected task/media message as the final user message.
+
+Prompt-stack messages cannot claim reserved selected-context or delegated-task markers.
+
+Backends such as Pi SDK may expose exact base-prompt runtime inputs only in a pre-provider hook. They may call the host preparer there, but provider transport must remain blocked until `createAgentExecutionPlan()` succeeds. A `partial` prompt-runtime preflight cannot produce an execution plan.
+
+### 6. Plan and fingerprints
+
+`createAgentExecutionPlan()` revalidates the request, snapshot, preflight, deterministic context receipt, tool negotiation, runtime fidelity, and protected final task. It carries the runtime-issued conversation and execution fingerprints as required inputs; the host never computes either value.
+
+The runtime's conversation fingerprint binds the exact sealed system prompt and ordered messages, so equivalent conversations on different backends compare equal. Its execution fingerprint additionally binds the accepted backend, preflight, effective tools, access and limit receipts, and runtime inputs, so the same conversation on different backends produces different execution fingerprints. Approval displays both values and execution accepts only the runtime-bound prepared handle.
+
+Canonical serialization sorts object keys, omits undefined object fields, rejects cycles/non-finite numbers/non-JSON values, preserves array order, and normalizes negative zero.
+
+### 7. Response validation
+
+`validateAgentResponse()` enforces the terminal status matrix:
+
+| Status | Required terminal field | Output rule |
+|---|---|---|
+| `completed` | none | absent or `partial: false` |
+| `failed` | structured `error` | absent or `partial: true` |
+| `cancelled` | `reason` | absent or `partial: true` |
+| `timed-out` | `reason`, `enforcedTimeoutMs` | absent or `partial: true` |
+| `limit-reached` | `reachedLimit` | absent or `partial: true` |
+
+It also validates request/run/backend correlation, model and fingerprints, effective backend tool IDs, backend-produced enforcement receipts, duration, token/cost units, artifact namespaces, relative paths, cleanup ownership, and authorized trace handles. Cost requires an ISO 4217 currency code.
+
+### 8. Optional backend registry
+
+`SubagentBackendRegistry` starts empty and never installs a default backend. It:
+
+- Validates backend descriptors and rejects duplicate identities.
+- Binds accepted preflight IDs to the exact backend, request, and profile fingerprint used during discovery.
+- Routes exact-preflight preparation directly to the host preparer and requires backend-assisted adapters to invoke the same host boundary.
+- Binds the exact runtime fingerprint, compiled system/messages, effective tools, and context receipt returned by host preparation; recomputing an execution fingerprint cannot substitute a different plan.
+- Routes dry-plan discard through the owning backend before forgetting the preflight binding.
+- Rejects malformed, tampered, foreign, or unbound execution plans before transport.
+- Arbitrates backend completion, explicit user cancellation, external abort signals, and declared host-abort timeouts through one terminal result.
+- Discards prepared backend state without invoking execution when cancellation wins before backend dispatch.
+- Normalizes thrown provider failures and malformed backend responses into contract-valid failed responses.
+- Replaces backend-reported duration with host-observed duration.
+- Keeps opaque backend trace IDs behind host-generated handles and enforces authorization scope, backend routing, expiry, and explicit forgetting during inspection.
+- Refuses backend unregistration while an execution remains active or is draining after cancellation.
+
+The registry validates receipts but does not manufacture filesystem, process, network, token, turn, or output isolation. Those remain adapter responsibilities.
+
+Access receipts may explicitly declare `executionBoundary: "shared-user"`. This boundary means the subprocess retains the invoking user's operating-system permissions and its effective access is constrained only by the tools exposed to the model. A shared-user receipt cannot claim mount, symlink, process, or network isolation. Omitting the field preserves the legacy `isolated` interpretation.
+
+### 9. Experimental foreground subprocess and approval path
+
+`PiSubprocessBackend` is the extension's deliberately narrow default adapter:
+
+- It resolves the exact profile model through Pi's existing `ModelRegistry`, reuses the host Pi `ModelRuntime` so preparation sees the same authentication, and prepares the exact prompt inside an in-process Pi session held behind a provider gate. Required host capabilities are checked and fail closed before provider transport.
+- After approval, it disposes the preparation session and launches a fresh foreground Pi subprocess with the approved model, thinking level, system prompt, messages, and tool IDs. Pi's ordinary text stdout is drained separately from a dedicated newline-delimited report channel.
+- Its bridge preserves the exact prepared messages and rejects tools outside the approved allowlist. Candidate tools are limited to `read`, `grep`, `find`, and `ls`, then intersected with prompt-stack policy.
+- It loads no write/edit/shell tools, skills, prompt templates, context files, themes, or third-party Pi extensions and writes no child session file.
+- It accepts text-only, one-shot, sequential `read-only` requests rooted at the project working directory, with no process tool and optional host-abort timeout. It advertises no artifact retention or contract trace inspection.
+- It records a bounded foreground execution report containing sanitized transcript events, tool calls/results, usage, stderr, status, and execution identity. Inline images remain available to the child model but cross the report boundary only as MIME/encoded-size metadata. Base64-like text is redacted, individual strings are capped, and retained messages form a 512 KiB rolling tail so large tool histories cannot make the parent TUI/session retain unbounded data. Temporary bridge inputs are mode `0600` and removed during cleanup.
+- Retained textual tool results are ordinary parent-session tool details. `/tree` can move the active branch away from them but does not erase abandoned entries from Pi's on-disk session JSONL; callers handling sensitive files must treat session-data deletion as a separate operation.
+
+This backend declares `executionBoundary: "shared-user"`. It does not create allowed-root mount containment, symlink-safe path containment, process isolation, or agent-network isolation. The subprocess retains the invoking user's OS permissions; `read-only` describes the tools exposed to the model, not a security sandbox. Network is therefore honestly recorded as allowed even though no dedicated network or shell tool is exposed.
+
+The model-callable `forge_subagent_profiles` tool reads the already-loaded host profile catalog without preparing a prompt or contacting a provider, then filters it through explicit trusted-project `subagents.profiles.<id>.enabled` policy. Global config supplies only general backend/timeout defaults; global profile entries warn and are ignored because the loaded profile and stack catalog is project-local. The tool exposes only delegation-enabled IDs, names, descriptions, declared model/thinking/stack metadata, effective backend/timeout and sources, ready/unavailable resolution diagnostics, and whether parent policy currently exposes the invocation tool. Disabled and unlisted profiles remain usable through ordinary profile workflows but cannot be delegated. A restrictive parent stack must allow both `forge_subagent_profiles` and `forge_subagent` for discovery followed by delegation.
+
+The model-callable `forge_subagent` tool and `/forge-agent run` use the same runtime path. Both reject profiles that are not explicitly enabled, resolve global/project general defaults plus trusted-project per-profile backend/timeout policy, and prepare an exact immutable plan while provider transport remains closed. `/forge-agent run` always shows a compact approval summary, allows inspection of the complete prompt, and requires interactive approval bound to the execution fingerprint. The tool does the same by default, but a trusted project may set `subagents.allowAgentInvocationWithoutApproval: true` in `.pi/forge/config.json`; this permits non-UI model invocation pinned to the effective configured profile backend and records `trusted-project-config` in the result receipt without weakening eligibility, preflight, or plan binding. Missing, malformed, and untrusted-project settings fail closed. The tool returns bounded content to the parent model and expandable execution details to the human. `/forge-agent plan` still prepares and discards without provider transport; `/forge-agent backends` shows capabilities and effective enabled-profile settings. Fresh-process backend registration, binding, lifecycle, and execution are provided by `@zihanw/pi-subagent-runtime`.
+
+## Adapter-Enforced Responsibilities
+
+The exported validators cannot create isolation. Every adapter remains responsible for:
+
+- Credential and model availability in its own runtime.
+- Backend-side mount materialization and path canonicalization immediately before access.
+- Symlink-race-safe containment.
+- Process and agent-network isolation.
+- Accurate tool effects and stable tool mappings.
+- Required hard timeout, turn, token, and output limits.
+- Cancellation settlement and cleanup.
+- Media transport and remote-egress behavior.
+- Artifact authorization, retention, and cleanup.
+- Trace storage, authorization, redaction, pagination, and expiry.
+- Returning actual enforcement receipts rather than echoing request fields.
+
+An adapter must reject preflight when it cannot enforce a required field. Both shipped process adapters accept shared-user read-only access and network allow, and use best-effort host abort rather than a backend-hard timeout. Provider transport is always a separate, explicitly approved egress path.
+
+## Deliberately Not Included
+
+- Filesystem writes, process/shell tools, media input, or background runs in the shipped path.
+- OS-level filesystem, process, or network sandboxing for the shared-user subprocess.
+- Automatic parent-history/context selection; the delegated task is explicit and starts a clean conversation.
+- Session resume, retries, queues, chains, or pipelines.
+- Artifact/trace storage implementations.
+- Automatic provider or backend fallback.
+
+Those belong to later iterations and cannot be inferred from these pure types alone.

package/docs/zh-CN/README.md

@@ -0,0 +1,37 @@
+# pi-forge 中文文档
+
+[项目首页](../../README.zh-CN.md) · [English docs](../README.md)
+
+## 从这里开始
+
+- [快速上手](getting-started.md)：安装、创建 stack、打开编辑器并保存 profile。
+- [Prompt stack](concepts/prompt-stacks.md)：prompt 组合、历史布局和策略模型。
+- [Agent profile](concepts/agent-profiles.md)：一次性模型/思考等级/stack 预设。
+
+## 指南
+
+- [Web 编辑器](guides/web-editor.md)
+- [实验性前台 delegation](guides/delegation.md)：启用前请先阅读安全边界。
+- [Prompt stack 使用场景（英文）](../guides/use-cases.md)
+
+SillyTavern 导入、自定义 macros/slots 和调试的完整说明目前以英文版为准：
+
+- [SillyTavern import](../guides/sillytavern-import.md)
+- [Custom macros and slots](../guides/custom-macros-and-slots.md)
+- [Prompt and payload debugging](../guides/debugging.md)
+
+## 参考
+
+- [命令参考](reference/commands.md)
+- [Stack schema 与策略（英文）](../reference/stack-schema.md)
+- [Macros 与 slots（英文）](../reference/macros-and-slots.md)
+- [配置（英文）](../reference/configuration.md)
+- [Public API（英文）](../reference/public-api.md)
+- [实验性 subagent adapter（英文）](../reference/subagent-adapter.md)
+
+## 开发与设计
+
+- [开发设置与兼容性（英文）](../development/setup.md)
+- [Release 流程（英文）](../development/release.md)
+- [Roadmap（英文）](../development/roadmap.md)
+- [历史设计档案（英文）](../design/README.md)

package/docs/zh-CN/concepts/agent-profiles.md

@@ -0,0 +1,46 @@
+# Agent profile
+
+[中文文档](../README.md) · [English](../../concepts/agent-profiles.md)
+
+Agent profile 是项目级或用户全局、带 schema version 的预设，只引用一个精确模型、思考等级和 prompt stack。项目 profile 位于 `.pi/forge/agent-profiles/`，全局 profile 位于 `~/.pi/forge/agent-profiles/`。命令接受 `reviewer`、`project:reviewer` 和 `global:reviewer`；未限定 ID 优先解析项目 profile，项目 profile 会遮蔽同 ID 全局 profile。
+
+```json
+{
+  "schemaVersion": 1,
+  "type": "pi-forge.agent-profile",
+  "id": "reviewer",
+  "name": "Reviewer",
+  "description": "只审查代码，不做修改。",
+  "autoActivate": true,
+  "model": {
+    "provider": "provider-id",
+    "id": "model-id"
+  },
+  "thinkingLevel": "high",
+  "promptStack": "reviewer"
+}
+```
+
+`promptStack` 可以是 `null`。Profile v1 不保存生成参数、工具、skills、backend 或 runner policy；不支持字段会直接报错。工具/skill 策略只属于引用的 stack。
+
+`promptStack` 引用相对 profile 自身 scope 解析：项目 profile 用裸 ID 引用项目 stack，也可用 `global:<id>` 显式引用全局 stack；全局 profile 只能引用全局 stack，`project:<id>` 会被拒绝。
+
+## 应用
+
+```text
+/profile save reviewer
+/profile preview reviewer
+/profile use reviewer
+```
+
+保存不会包含 secrets、history、tools 或 provenance。应用前会完整检查 profile、模型、认证、思考等级、stack 和工具策略；失败时不会部分应用，运行中失败会尝试 rollback。
+
+成功应用后，后续手动修改会被保留。Profile 不是持续的 runtime owner。
+
+## Auto-activation 与 drift
+
+最多一个 profile 可以设置 `autoActivate: true`。它只在全新 session 中应用一次，并优先于独立 stack autoload；恢复的 branch 状态优先。无效或冲突的自动启用会 fail closed。
+
+`/profile status` 会把 profile 源定义变化和当前模型/思考等级/stack drift 分开显示。Provenance 只用于 branch 状态报告；reload、resume、tree navigation 和 compaction 不会重新应用 profile。
+
+普通 profile 默认不能委派。Delegation 授权跟随 profile scope：可信项目 `.pi/forge/config.json` 的 `subagents.profiles.<id>` 只授权 `project:<id>`，用户全局 `~/.pi/forge/config.json` 的 `subagents.profiles.<id>` 只授权 `global:<id>`；同 ID 的全局和项目 profile 永不互相继承授权。删除 profile 会清除同 scope 的授权，防止以后同 ID profile 继承权限。启用前见[前台 delegation](../guides/delegation.md)。

package/docs/zh-CN/concepts/prompt-stacks.md

@@ -0,0 +1,42 @@
+# Prompt stack
+
+[中文文档](../README.md) · [English](../../concepts/prompt-stacks.md)
+
+Prompt stack 是一份有序、声明式的 prompt 与策略描述，由固定 **block** 和动态 **slot** 组成。Stack 可以放在项目 `.pi/forge/prompt-stacks/`，也可以放在用户全局 `~/.pi/forge/prompt-stacks/`。命令接受 `reviewer`、`project:reviewer` 和 `global:reviewer`；未限定 ID 优先解析项目 stack，项目 stack 会遮蔽同 ID 全局 stack。重复 ID 只在同一 scope 内算错误。
+
+## 编译模型
+
+每个用户轮次开始时，pi-forge 会：
+
+1. 按 JSON 顺序排列启用的 block/slot。
+2. 构建 system 内容，并使用 `replace`、`append` 或 `prepend` 模式。
+3. 在可移动 `chat-history` 周围插入 user/assistant 消息。
+4. 展开内置、变量和可信自定义宏。
+5. 对 Pi 执行工具策略，并过滤 pi-forge 渲染的 skills。
+6. 应用 history/compiled outgoing regex。
+7. 可选地在消息完成后应用破坏性的 finalize regex。
+
+## 常用历史布局
+
+1. 长期 system 规则。
+2. 工具和项目上下文。
+3. `includeLastUserMessage: false` 的 `chat-history`。
+4. 包含 `{{lastUserMessage}}` 的最终 user block。
+
+这样既保留旧上下文，又只在最后明确出现一次当前请求。History 还可以过滤 summary/role、去掉旧工具消息、移除 assistant thinking，并限制消息数或字符数。
+
+## 策略边界
+
+工具 `allow`/`deny` 会修改 Pi active tools，并在 tool call 时再次检查。Skill policy 只过滤 pi-forge 渲染给模型的列表；它不能阻止明确调用，也不是安全边界。若必须控制模型可见 skill 列表，请使用 `replace`，因为 Pi 的基础 prompt 可能已经在 `append`/`prepend` 内容之前列出 skills。
+
+## Scope 与自动启用
+
+- 只有显式设置 `"autoActivate": true` 的 stack 参与自动启用；文件名（包括 `default.json`）没有特殊作用。
+- 项目 stack 优先于全局 stack；项目 scope 存在候选时，即使项目候选无效或冲突也会 fail closed，不会回退到全局 stack。
+- 同 ID 项目 stack 会遮蔽全局 stack，包括无效 shadow 或显式 opt-out。
+- `/preset use none` 会记录 session branch 的 opt-out。
+- Active stack 和 session variables 会跟随 Pi session tree branch。
+- 恢复的 branch 状态优先于新 session 自动启用。
+- 自动启用的 agent profile 优先于独立 stack autoload。
+
+完整字段见英文 [stack schema](../../reference/stack-schema.md)，macro/slot 见[参考](../../reference/macros-and-slots.md)。

package/docs/zh-CN/getting-started.md

@@ -0,0 +1,81 @@
+# 快速上手
+
+[中文文档](README.md) · [English](../getting-started.md)
+
+## 安装
+
+pi-forge 需要 Node.js 22.19 或更高版本，并作为 Pi extension 运行：
+
+```bash
+pi install npm:@zihanw/pi-forge
+```
+
+安装或更新后请重启 Pi。Pi host 会提供运行时 SDK；精确 package 版本只用于可复现的开发测试。用户全局 stack/profile 始终可以浏览；项目 stack、profile 和 config 只在 Pi 信任项目后加载和写入。
+
+## 第一个 stack
+
+Prompt stack 保存在 `.pi/forge/prompt-stacks/*.json`。推荐从 [默认 Pi mirror](../../examples/default-prompt-stack.json) 开始：
+
+```bash
+mkdir -p .pi/forge/prompt-stacks
+cp examples/default-prompt-stack.json .pi/forge/prompt-stacks/default.json
+```
+
+如果不是在仓库 clone 中，可以打开 `/preset ui` 新建 stack；编辑器使用同样的默认布局。
+
+```text
+/preset reload
+/preset use default
+```
+
+示例中的 `default.json` 带 `"autoActivate": true`，因此没有恢复的 session 选择或明确 opt-out 时会自动启用。设置 `"autoActivate": false` 可以关闭此行为；文件名本身没有特殊作用。
+
+## 编辑和检查
+
+```text
+/preset ui
+```
+
+编辑器运行在带 token 的本地 `127.0.0.1` URL，支持结构化/原始 JSON 编辑、排序、校验、完整预览、策略、regex、导入导出、fork 和 profile 管理。工具栏的 scope 下拉（默认 `project`）决定新建、fork 和导入 stack 写入项目 `.pi/forge/prompt-stacks` 还是用户全局 `~/.pi/forge/prompt-stacks`。
+
+命令行也可以检查：
+
+```text
+/preset validate default
+/preset preview default
+/preset diagnostics
+```
+
+## 创建 profile
+
+先选择模型、思考等级和 stack，然后执行：
+
+```text
+/profile save reviewer
+/profile preview reviewer
+/profile use reviewer
+```
+
+Profile 默认保存在 `.pi/forge/agent-profiles/*.json`。`/profile save global:reviewer` 会写入用户全局 `~/.pi/forge/agent-profiles`。应用是经过 preflight 的一次性操作；之后的手动设置不会被自动覆盖。
+
+## 存储与迁移
+
+| 路径 | 用途 |
+|---|---|
+| `.pi/forge/prompt-stacks/` | 项目 prompt stacks |
+| `.pi/forge/agent-profiles/` | 项目 agent profiles |
+| `.pi/forge/config.json` | 项目配置和 `project:<id>` delegation 授权 |
+| `.pi/forge/extensions/` | 可信项目 macro/slot 代码 |
+| `~/.pi/forge/prompt-stacks/` | 用户全局 prompt stacks |
+| `~/.pi/forge/agent-profiles/` | 用户全局 agent profiles |
+| `~/.pi/forge/config.json` | 用户默认配置和 `global:<id>` delegation 授权 |
+| `~/.pi/forge/extensions/` | 可信用户 macro/slot 代码 |
+
+旧的 `.pi/prompt-stacks/*.json` 仍可读取；命令创建的 stack 会写到 `.pi/forge/prompt-stacks`，使用 Web 编辑器的 `global` scope 下拉可创建到用户全局 `~/.pi/forge/prompt-stacks`。安全迁移方式：
+
+```text
+/preset migrate-stacks --dry-run
+/preset migrate-stacks
+```
+
+确认复制结果后再考虑 `--overwrite` 或 `--delete-legacy`。

package/docs/zh-CN/guides/delegation.md

@@ -0,0 +1,66 @@
+# 实验性前台 delegation
+
+[中文文档](../README.md) · [English](../../guides/delegation.md)
+
+> **实验性：** 此 API 和 backend 可能独立于稳定的 prompt stack/profile 功能发生变化。
+
+pi-forge 可以把明确授权的 agent profile 作为独立、干净、一次性的 Pi 进程执行。它在前台运行，并向父对话返回有界报告。
+
+## 启用 profile
+
+Profile 默认不能委派。请在可信项目的 `.pi/forge/config.json` 中逐个启用项目 profile，在用户全局 `~/.pi/forge/config.json` 中逐个启用全局 profile；也可以使用 `/preset ui` 的 delegation 卡片：
+
+```json
+{
+  "subagents": {
+    "backend": "pi-subprocess-readonly",
+    "timeoutMs": 60000,
+    "profiles": {
+      "reviewer": {
+        "enabled": true,
+        "timeoutMs": 300000
+      }
+    }
+  }
+}
+```
+
+授权跟随 profile scope：项目 config 的 `subagents.profiles.<id>` 只授权 `project:<id>`，全局 config 的 `subagents.profiles.<id>` 只授权 `global:<id>`。同 ID 的全局和项目 profile 不会互相继承 enable/backend/timeout。未启用或未列出的 ID 不会被 discovery 返回，即使猜中 ID 也会被拒绝。
+
+## Plan 与运行
+
+```text
+/forge-agent backends
+/forge-agent plan reviewer 检查这个 API 设计。
+/forge-agent run reviewer 检查这个 API 设计。
+```
+
+`plan` 会解析 profile/stack、编译并校验不可变的实际 provider-bound 计划，然后在不联系 provider 的情况下丢弃。Profile selector 在所有入口使用同一语法：`reviewer`（项目优先）、`project:reviewer` 或 `global:reviewer`。同 ID 冲突时，项目 profile 保持简写 selector，全局 profile 仍通过 `global:<id>` 调用。
+
+父模型使用无数据外发的 `forge_subagent_profiles` 做 discovery，再用 `forge_subagent` 执行。限制严格的父 stack 必须允许这两个工具名。
+
+当前有两个 fresh-process backend：默认 `pi-subprocess-readonly` 使用 text/print，`pi-rpc-readonly` 使用 RPC。两者执行同一密封 prompt 和 shared-user 只读策略。所选 backend 不可用时会 fail closed，不会自动 fallback。
+
+## 审批
+
+默认情况下，provider transport 前会显示与执行 fingerprint 绑定的计划，包括任务、profile/stack、provider/model、thinking、工具、cwd、安全边界和 payload 大小。可以选择 **View full prompt** 检查完整 system prompt 和消息。
+
+可信项目可以明确允许模型无需逐次审批：
+
+```json
+{
+  "subagents": {
+    "allowAgentInvocationWithoutApproval": true
+  }
+}
+```
+
+它只影响 `forge_subagent`；`/forge-agent run` 仍需要交互审批。格式错误或不可信项目会 fail closed。请把此 config 当作授权文件：除非所有可调用父 agent 都可以无需再次询问就把编译 prompt 和可读文件发给 provider，否则不要启用或提交此设置。
+
+## Child 边界
+
+Child 从干净对话开始，不会自动继承父 history。候选工具只有 `read`、`grep`、`find`、`ls`，并继续受到 stack policy 限制。它不会加载 write/edit/shell、skills、prompt templates、context files 或第三方 extensions。
+
+> **当前 backend 是 shared-user，不是操作系统沙箱。** “只读”只是模型工具策略，进程仍拥有启动用户的 OS 权限。该用户可读的绝对路径可能被读取并发送给 provider；文本可能保留在父 tool-result 和 Pi session JSONL。Timeout/取消仅为 best effort。`/tree` 不能撤销 provider 请求、计费或外部影响，也不保证删除磁盘上的 abandoned entry。
+
+不要给此 shared-user 设计添加 write/edit/shell。操作系统隔离和需要第二次审批的 staged write 属于未来工作。

package/docs/zh-CN/guides/web-editor.md

@@ -0,0 +1,45 @@
+# Web 编辑器
+
+[中文文档](../README.md) · [English](../../guides/web-editor.md)
+
+在可信 Pi 项目中执行：
+
+```text
+/preset ui
+```
+
+`/preset ui restart` 会替换 server，`/preset ui stop` 会关闭它。
+
+编辑器绑定在带 session token 的可用 `127.0.0.1` 端口；多个项目可以同时运行。读取、预览和 payload 检查在合适范围内可用；写入要求 Pi 信任项目，并且文件被限制在 pi-forge 的 stack/profile 存储内。可以在 `.pi/forge/config.json` 中设置偏好端口：
+
+```json
+{
+  "webEditor": { "port": 41738 }
+}
+```
+
+端口被占用时会自动选择其他端口。请不要把带 token 的编辑器 URL 暴露或代理到不可信网络。写入操作要求项目已被 Pi 信任。
+
+## Prompt stack 工作区
+
+支持：
+
+- 从默认 Pi mirror 新建 stack；
+- 结构化和原始 JSON 编辑；
+- 拖拽排序、启用/禁用、校验和完整编译预览；
+- 工具/skill 搜索、精确名称 chips 和通配符策略；
+- variables、context 和 regex 规则；
+- 原生 pi-forge 与 SillyTavern JSON 导入；
+- 导出、fork、删除和 payload 捕获。
+
+已有 ID 在编辑时不可修改；需要新 ID 时使用 **Fork**，避免破坏 profile 引用和当前选择。工具栏的 scope 下拉（默认 `project`）决定新建、导入和 fork 的写入位置：选择 `global` 写入用户全局 `~/.pi/forge/prompt-stacks`，选择 `project` 写入项目 `.pi/forge/prompt-stacks`。列表会为全局 stack 显示 `global` badge；保存和删除通过 `global:<id>` 路由精确作用于全局文件。保存、导入、fork 和删除后会重新加载当前 Pi session。
+
+## Agent profile 工作区
+
+列表显示 profile ID、名称、模型、思考等级、stack、校验状态、auto-activation、last-applied provenance 和 delegation 状态。每个 profile 都带 `project` / `global` scope badge；同 ID 的 shadow 对会显示 `shadows global:<id>` 或 `shadowed by project:<id>`。
+
+可信项目通过 **New profile** 旁的 scope 下拉（默认 `project`）选择目标 scope：选择 `global` 写入用户全局 `~/.pi/forge/agent-profiles`，选择 `project` 写入项目 `.pi/forge/agent-profiles`。全局 profile 可通过显式 `global:<id>` 路由编辑、校验、保存、一次性应用和删除；未限定路由始终只作用于项目资源。编辑全局 profile 时，stack 下拉只显示全局 stack。Model 选项来自 Pi registry，thinking 选项反映模型支持，stack 选项来自同一个 repository。编辑器会拒绝同 scope 内第二个 auto-activation profile。
+
+Delegation 卡片按 profile 的 scope 修改 `subagents.profiles.<id>` 的 enable/backend/timeout：项目 profile 写入项目 config，全局 profile 写入用户全局 config。切换 profile、刷新、删除或离开页面时，未保存的 delegation 字段会得到保护。通用默认值和 `allowAgentInvocationWithoutApproval` 只能在 config 文件中设置。
+
+启用前请阅读[前台 delegation](delegation.md)。

package/docs/zh-CN/reference/commands.md

@@ -0,0 +1,60 @@
+# 命令参考
+
+[中文文档](../README.md) · [English](../../reference/commands.md)
+
+方括号参数可选。写项目文件的命令要求项目已被信任。未限定的 `<id>` 使用项目优先的有效查找；需要精确选择时使用 `project:<id>` 或 `global:<id>`。
+
+## Prompt stack
+
+| 命令 | 行为 |
+|---|---|
+| `/preset list` | 列出 stack 和状态 |
+| `/preset status` | 显示当前 stack 和诊断摘要 |
+| `/preset use <id>` | 校验并选择 stack |
+| `/preset use none` | 在当前 session branch 禁用 stack |
+| `/preset preview [id]` | 编译但不发送 provider 请求 |
+| `/preset validate [id]` | 校验一个或全部 stack |
+| `/preset diagnostics` | 显示 loader、runtime、policy、regex 和 extension 诊断 |
+| `/preset reload` | 重新加载 stack 和可信 macro/slot registration |
+| `/preset ui [stop\|restart]` | 打开或管理 Web 编辑器 |
+
+## 迁移与导入
+
+| 命令 | 行为 |
+|---|---|
+| `/preset migrate-stacks [--dry-run] [--overwrite] [--delete-legacy]` | 把旧 stack 复制到 `.pi/forge/prompt-stacks` |
+| `/preset import-silly <path> [character_id] [--dry-run] [--overwrite]` | 转换 SillyTavern preset 并生成报告 |
+
+覆盖或删除之前请先使用 `--dry-run`。
+
+## Agent profile
+
+| 命令 | 行为 |
+|---|---|
+| `/profile list` | 列出 profile 和解析诊断 |
+| `/profile use <id>` | preflight 并一次性应用 |
+| `/profile save <id\|global:id> [--overwrite]` | 捕获当前模型、thinking 和 stack；`global:<id>` 写入用户全局目录 |
+| `/profile status` | 比较当前 runtime 和 last-applied provenance |
+| `/profile preview <id>` | 不应用地解析模型/auth/thinking/stack/tools |
+| `/profile validate [id]` | 校验一个或全部 profile |
+| `/profile reload` | 重新加载定义，但不应用 |
+| `/profile forget` | 删除 provenance，不改变 runtime |
+
+## 实验性 delegation
+
+| 命令 | 行为 |
+|---|---|
+| `/forge-agent backends` | 列出 backend、capabilities 和默认值 |
+| `/forge-agent plan <profile> [--backend <id>] <task>` | 准备、显示并丢弃计划，不联系 provider |
+| `/forge-agent run <profile> [--backend <id>] <task>` | 审批并执行前台只读任务 |
+
+只接受匹配 scope 明确授权的 profile：项目 config 授权 `project:<id>`，全局 config 授权 `global:<id>`。模型工具为 `forge_subagent_profiles` 和 `forge_subagent`。见[安全说明](../guides/delegation.md)。
+
+## Payload
+
+| 命令 | 行为 |
+|---|---|
+| `/intercept` | 显示下一个脱敏 provider payload |
+| `/payload next [save=<path>]` | 显示并可选保存 payload，同时提供给 Web 编辑器 |
+
+即使 credentials 字段被脱敏，保存的 payload 仍可能包含 prompt 和对话内容，请按敏感数据处理。