@zihanw/pi-forge 0.5.1 → 0.5.3

package/docs/guides/web-editor.md

@@ -14,7 +14,7 @@ Use `/preset ui restart` to replace its server or `/preset ui stop` to close it.
 
 The editor binds to an available `127.0.0.1` port and uses a session token. Multiple Pi projects can run editors simultaneously. Lifecycle reinitialization reuses the existing editor URL for the same project when possible.
 
-Reads, preview, resources, and payload inspection remain available as appropriate, but writes require Pi to trust the project. Files are constrained to pi-forge's stack/profile storage. Never expose or proxy the editor URL to an untrusted network.
+Reads, preview, resources, and payload inspection remain available as appropriate, but writes require Pi to trust the project. Files are constrained to Pi Forge's Preset/Profile storage. Never expose or proxy the editor URL to an untrusted network.
 
 Choose a preferred port in `.pi/forge/config.json`:
 
@@ -28,12 +28,17 @@ Choose a preferred port in `.pi/forge/config.json`:
 
 If that port is unavailable, pi-forge selects another and shows the actual URL.
 
-## Prompt-stack workspace
+## Interface language
 
-The stack workspace provides:
+The editor interface is available in English and Chinese. Use the language selector in the top bar (Auto / English / 中文); the choice is written to `webEditor.locale` in the project config. `Auto` (the default) follows the browser language, and the initial page render also honors the browser's `Accept-Language` header. Interface chrome, built-in Preset/Profile surfaces, and the preview/diff dock are localized; compiler diagnostics, provider-contributed settings pages, and authored Preset content stay in their authored language.
+
+## Preset workspace
+
+The Preset workspace provides:
 
 - creation from the default Pi-mirror layout;
-- structured metadata, item, policy, variables, context, and regex editing;
+- an ordered **Stack** tab for Block/Slot composition;
+- structured metadata, policy, parameters, context, and Regex editing;
 - drag-and-drop item order and enable/disable controls;
 - validation and a full compiled preview;
 - registered-tool and loaded-skill search with exact-name chips and wildcard patterns;
@@ -43,15 +48,15 @@ The stack workspace provides:
 - payload arming and redacted captured-payload inspection;
 - light and dark themes.
 
-Existing IDs are immutable during edit. Use **More → Fork** to create a different ID without breaking profile references or the active selection. The compact selector attached to **New stack** (default `Project`) chooses where new stacks, imports, and forks are written: `Global` targets the user-global `~/.pi/forge/prompt-stacks`, `Project` targets `.pi/forge/prompt-stacks`. Less-used capture, fork, import, export, and delete actions live under **More** so the stack and Preview/Diff panes keep the available viewport. Stack rows show a `global` badge, and save/delete routes use `global:<id>` for exact global mutations. Legacy stacks remain editable in place.
+Existing IDs are immutable during edit. Use **More → Fork** to create a different ID without breaking Profile references or the active selection. The compact selector attached to **New preset** (default `Project`) chooses where new Presets, imports, and forks are written: `Global` targets the user-global `~/.pi/forge/prompt-stacks`, `Project` targets `.pi/forge/prompt-stacks`. Those paths keep their pre-0.5.3 names for compatibility. Less-used capture, fork, import, export, and delete actions live under **More** so the Stack and Preview/Diff panes keep the available viewport. Preset rows show a `global` badge, and save/delete routes use `global:<id>` for exact global mutations. Legacy resources remain editable in place.
 
-Saves, imports, forks, and deletes reload stack state into the current Pi session. When another surface changes a referenced stack, returning to profiles refreshes profile resolution.
+Saves, imports, forks, and deletes reload Preset state into the current Pi session. When another surface changes a referenced Preset, returning to Profiles refreshes Profile resolution.
 
 ## Agent-profile workspace
 
-The profile list shows each profile's ID, display metadata, model, thinking level, stack, resolution state, auto-activation, last-applied provenance, and a `project`/`global` scope badge. Same-ID shadow pairs are marked `shadows global:<id>` or `shadowed by project:<id>`.
+The Profile list shows each Profile's ID, display metadata, model, thinking level, Preset, resolution state, auto-activation, last-applied provenance, and a `project`/`global` scope badge. Same-ID shadow pairs are marked `shadows global:<id>` or `shadowed by project:<id>`.
 
-Trusted projects can create profiles in either scope: the scope selector beside **New profile** (default `project`) chooses whether to write the user-global `~/.pi/forge/agent-profiles` or the project `.pi/forge/agent-profiles`. Global profiles can be edited, validated, saved, applied once, and deleted through explicit `global:<id>` routes; unqualified routes stay project-only. When editing a global profile, the prompt-stack dropdown offers only global stacks. Model choices come from Pi's model registry, thinking choices reflect model support, and stack choices come from the shared repository. The editor rejects a second auto-activation profile within the same scope.
+Trusted projects can create Profiles in either scope: the scope selector beside **New profile** (default `project`) chooses whether to write the user-global `~/.pi/forge/agent-profiles` or the project `.pi/forge/agent-profiles`. Global Profiles can be edited, validated, saved, applied once, and deleted through explicit `global:<id>` routes; unqualified routes stay project-only. When editing a global Profile, the Preset dropdown offers only global Presets. Model choices come from Pi's model registry, thinking choices reflect model support, and Preset choices come from the shared repository. The editor rejects a second auto-activation Profile within the same scope.
 
 The runtime/provenance card separates current runtime state, last-applied snapshot, source-definition changes, and field-level runtime drift.
 

package/docs/reference/configuration.md

@@ -9,13 +9,16 @@ Project configuration lives in `.pi/forge/config.json` and is loaded only for a
 ```json
 {
   "webEditor": {
-    "port": 41738
+    "port": 41738,
+    "locale": "auto"
   }
 }
 ```
 
 The port is preferred, not guaranteed. The editor binds only to `127.0.0.1` and chooses another available port when necessary.
 
+`webEditor.locale` selects the editor's interface language: `"en"`, `"zh-CN"`, or `"auto"` (default). `"auto"` follows the browser language. The language selector in the editor's top bar writes this setting; `"auto"` removes the key.
+
 ## Experimental subagents
 
 Subagent configuration is owned by the optional `@zihanw/pi-forge-subagents` package. Dedicated files are `.pi/forge/subagents.json` for a trusted project and `~/.pi/forge/subagents.json` for user defaults. Legacy `.pi/forge/config.json` / `~/.pi/forge/config.json` `subagents` sections are read-only fallback material and emit a warning.

package/docs/reference/features.md

@@ -72,12 +72,16 @@ This file tracks the currently implemented feature surface for agent profiles, t
 - Chat history can filter summaries/roles, drop prior tool history, and cap recent history by message count or approximate characters with dangling tool calls/results repaired after filtering.
 - Duplicate chat-history warning unless explicitly allowed.
 - Synthetic `user`, `assistant`, and hidden `custom` messages.
+- Optional consecutive-role merge (`context.mergeConsecutiveRoles`/`mergeSeparator`): runs of consecutive stack-authored `user`/`assistant` items compile into a single message; chat-history output and custom-role items are hard boundaries, and merging runs after compiled-stage regex.
+- Validation warning when an enabled `system` item appears after non-system items (cross-channel item position has no effect on compilation).
 - Context rewrite limited to the first provider request of each user-submitted turn.
 - Tool policy filters Pi's active tool list while the stack is active and restores the previous active tools when the stack no longer applies.
 - Tool policy restores its pre-policy baseline during extension shutdown so Pi reload/session replacement cannot carry a restricted built-in tool set into the replacement runtime.
 - Startup tool enforcement waits until extension `session_start` configuration is complete, reasserts before user input and turns, and blocks disallowed model tool calls at execution time.
 - Skill policy filters skills rendered by pi-forge `skills` slots.
 - Outgoing regex transforms can run after `chat-history` insertion and after final prompt compilation.
+- Per-rule `frequency: "request"` re-runs an outgoing message rule on every tool-result follow-up request over Pi's full natural context; the default `"turn"` keeps first-request-only behavior.
+- `finalize` rules whose `roles` explicitly include `"toolResult"` also rewrite stored tool-result messages at completion time (destructive, documented); rules without `roles` stay assistant-only.
 - Finalize regex transforms can rewrite completed assistant messages at `message_end`.
 
 ## Regex Transforms
@@ -197,6 +201,7 @@ This file tracks the currently implemented feature surface for agent profiles, t
 - Collapsible prompt-stack sidebar.
 - Collapsible stack metadata panel and main-area tabs for Items, Regex, Policy, and Stack JSON/context/variables work.
 - Light/dark theme toggle, button icons, and tooltips for common actions.
+- English/中文 interface switch (`webEditor.locale`: `"en"`, `"zh-CN"`, or `"auto"` following the browser language); contributed settings tabs remain provider-authored and are not translated.
 - Unsaved-change badge in the top bar.
 - Create a new prompt stack from the browser, including when no stack files exist yet; new stacks start from the default Pi prompt mirror layout.
 - View immutable stack ID and edit name, mode, `autoActivate`, description, and existing stack file content; use Fork to create a new ID.

package/docs/reference/stack-schema.md

@@ -25,7 +25,7 @@ Block:
 }
 ```
 
-Valid roles are `system`, `user`, `assistant`, and `custom`. Custom-role content participates in compilation but does not produce a provider message directly.
+Valid roles are `system`, `user`, `assistant`, and `custom`. Custom-role content participates in compilation and reaches the provider as a `user` message: Pi converts `custom` messages to `user` when it builds the wire request, so the wire carries no distinct custom role. Custom-role items never merge with other items (see [Context options](#context-options)).
 
 Slot:
 
@@ -45,12 +45,30 @@ Slot:
 
 Item IDs must be unique. Unsupported slots and missing required custom registrations produce diagnostics. Multiple chat-history slots warn unless explicitly permitted.
 
+Item position only matters within each channel: all `system` items join the system prompt in their relative order, and all non-system items become messages in their relative order. A `system` item placed after non-system items therefore has no effect on placement and produces a validation warning; roles are never silently converted. Use a `user` item for in-conversation injection.
+
 ## Modes
 
 - `replace` replaces Pi's base system prompt; empty output falls back to the base.
 - `append` places stack system text after Pi's base.
 - `prepend` places stack system text before Pi's base.
 
+## Context options
+
+```json
+{
+  "context": {
+    "allowDuplicateChatHistory": false,
+    "mergeConsecutiveRoles": true,
+    "mergeSeparator": "\n\n"
+  }
+}
+```
+
+- `allowDuplicateChatHistory` permits multiple enabled chat-history slots; otherwise only the first expands.
+- `mergeConsecutiveRoles` (default `false`) merges runs of consecutive stack items that share the same declared role into a single message, joined by `mergeSeparator` (default a blank line). Only stack-authored `user`/`assistant` items merge: chat-history output (including the implicit history tail) and `custom` items are hard boundaries, and merging runs after compiled-stage regex so regex semantics are unchanged. The web editor preview reflects the merged layout.
+- `mergeSeparator` is inserted verbatim between merged texts and may be an empty string.
+
 ## Chat-history options
 
 ```json
@@ -151,6 +169,43 @@ Regex rules are ordered, deterministic JavaScript `RegExp` replacements. There i
 
 Message rules may filter by `roles`, `maxMessages`, `maxChars`, `minDepth`, and `maxDepth` (depth 0 is latest). `trimStrings` removes literal strings from expanded matches/captures. Supported flags are `g`, `i`, `m`, `s`, and `u`. Replacements use JavaScript `$&`/`$1`; `$0` is accepted as a full-match alias and `$$` yields a literal dollar sign.
 
+### Frequency
+
+Outgoing rules default to `"frequency": "turn"`: they run during the full compilation on the first provider request of each user turn. Tool-result follow-up requests receive Pi's natural context, so a turn-scoped rule never sees tool output until the next user turn.
+
+Set `"frequency": "request"` to also run an outgoing message rule on every tool-result follow-up request, applied to Pi's full natural context:
+
+```json
+{
+  "id": "redact-api-keys",
+  "stage": "history",
+  "effect": "outgoing",
+  "frequency": "request",
+  "pattern": "\\b(sk-[A-Za-z0-9_-]{12,})\\b",
+  "flags": "g",
+  "replace": "[REDACTED]"
+}
+```
+
+Each provider request is rebuilt from the stored transcript, so re-applying a rule to older messages is wire-consistent and never doubles. History-stage rules and compiled-stage rules with a `messages` target both participate; on follow-ups there is no stack layout rewrite, so both stages collapse onto the natural context (history-stage rules run first). `frequency` has no effect on `finalize` rules or system-only targets, and validation says so. It is wire-only scrubbing: the stored transcript keeps the original text.
+
+Regex rules only cover the text targets and patterns you declare. They cannot recognize every credential format and do not scan system text, tool definitions, or arbitrary request metadata unless those targets are explicitly supported and selected. Treat them as deterministic text transforms, not as a security boundary.
+
+To scrub the same recognized shapes from stored assistant/tool-result text, pair a request-frequency outgoing rule with a `finalize` rule:
+
+```json
+{
+  "id": "redact-api-keys-finalize",
+  "stage": "compiled",
+  "effect": "finalize",
+  "targets": ["messages"],
+  "roles": ["assistant", "toolResult"],
+  "pattern": "\\b(sk-[A-Za-z0-9_-]{12,})\\b",
+  "flags": "g",
+  "replace": "[REDACTED]"
+}
+```
+
 Outgoing rules change future model input. To destructively change a completed assistant transcript message:
 
 ```json
@@ -170,3 +225,5 @@ Outgoing rules change future model input. To destructively change a completed as
 > `finalize` runs at `message_end`, after raw output may have streamed. It replaces the stored assistant message, so the original output is not preserved.
 
 `effect: "outgoing"` and `"finalize"` are the only valid effects; `"display"` and `"both"` are rejected during validation. Runtime diagnostics report match and changed-segment counts.
+
+`finalize` applies to assistant messages by default, and additionally to stored tool-result messages when a rule's `roles` explicitly includes `"toolResult"` — useful for scrubbing secrets out of stored tool output before the follow-up request replays it. Rules without `roles` keep assistant-only behavior, user messages are never finalized, and unsupported roles warn.

package/docs/zh-CN/README.md

@@ -4,16 +4,16 @@
 
 ## 从这里开始
 
-- [快速上手](getting-started.md)：安装、创建 stack、打开编辑器并保存 profile。
-- [Prompt stack](concepts/prompt-stacks.md)：prompt 组合、历史布局和策略模型。
-- [Agent profile](concepts/agent-profiles.md)：一次性模型/思考等级/stack 预设。
+- [快速上手](getting-started.md)：安装、创建预设、打开编辑器并保存 Profile。
+- [预设与堆栈](concepts/prompt-stacks.md)：完整预设及其有序 Block/Slot 编排。
+- [Agent Profile](concepts/agent-profiles.md)：一次性模型/思考等级/预设组合。
 
 ## 指南
 
 - [Web 编辑器](guides/web-editor.md)
 - [迁移到 0.5](guides/migrating-to-0.5.md)
 - [实验性前台 delegation](guides/delegation.md)：启用前请先阅读安全边界。
-- [Prompt stack 使用场景（英文）](../guides/use-cases.md)
+- [预设使用场景（英文）](../guides/use-cases.md)
 
 自定义 macros/slots 和调试的完整说明目前以英文版为准：
 

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

@@ -1,8 +1,12 @@
-# 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 内算错误。
+**Preset（预设）**是 Pi Forge 应用的完整声明式资源；其中由固定 **Block** 和动态 **Slot** 组成的有序 prompt 编排叫 **Stack（堆栈）**。同一份预设还会携带策略、Regex、参数和扩展引用。
+
+> **0.5.3 兼容说明。** UI 使用“预设 → 堆栈”术语。这个补丁版本仍保留文件路径、JSON type、Profile 字段、API 路由和内部类型中的 `prompt-stack` / `promptStack` 拼写。
+
+预设当前放在兼容路径 `.pi/forge/prompt-stacks/` 或用户全局 `~/.pi/forge/prompt-stacks/`。命令接受 `reviewer`、`project:reviewer` 和 `global:reviewer`；未限定 ID 优先解析项目预设，项目预设会遮蔽同 ID 全局预设。重复 ID 只在同一 scope 内算错误。
 
 ## 编译模型
 
@@ -13,8 +17,8 @@ Prompt stack 是一份有序、声明式的 prompt 与策略描述，由固定 *
 3. 在可移动 `chat-history` 周围插入 user/assistant 消息。
 4. 用 forge-v1 编译 `runtime.*` / `parameters.*` / `extensions.*` 模板。
 5. 对 Pi 执行工具策略，并过滤 pi-forge 渲染的 skills。
-6. 应用 history/compiled outgoing regex。
-7. 可选地在消息完成后应用破坏性的 finalize regex。
+6. 应用 history/compiled outgoing regex。`frequency: "request"` 的 outgoing 消息规则还会在 tool 结果后续请求上对 Pi 的完整自然上下文再次运行；默认 `"turn"` 保持仅在每轮首次请求运行。
+7. 可选地在消息完成后应用破坏性的 finalize regex；`roles` 显式包含 `"toolResult"` 的 finalize 规则还会改写存储的 tool 结果消息。
 
 ## 常用历史布局
 
@@ -25,18 +29,20 @@ Prompt stack 是一份有序、声明式的 prompt 与策略描述，由固定 *
 
 这样既保留旧上下文，又只在最后明确出现一次当前请求。History 还可以过滤 summary/role、去掉旧工具消息、移除 assistant thinking，并限制消息数或字符数。
 
+堆栈还可以通过 `context.mergeConsecutiveRoles`（及可选的 `context.mergeSeparator`）把连续的同角色条目合并成一条消息；chat-history 输出和 custom 角色条目永远不会被合并。详见英文 [Preset schema](../../reference/stack-schema.md#context-options)。
+
 ## 策略边界
 
-工具 `allow`/`deny` 会修改 Pi active tools，并在 tool call 时再次检查。具体的 `allow` 列表会从 Pi 的完整已注册工具目录中选择，因此可以启用 stack 激活前处于 inactive 状态的工具；`deny` 只从原 active baseline 中移除工具，`allow: ["*"]` 仍表示不限制且不会启用全部工具。Skill policy 只过滤 pi-forge 渲染给模型的列表；它不能阻止明确调用，也不是安全边界。若必须控制模型可见 skill 列表，请使用 `replace`，因为 Pi 的基础 prompt 可能已经在 `append`/`prepend` 内容之前列出 skills。
+工具 `allow`/`deny` 会修改 Pi active tools，并在 tool call 时再次检查。具体的 `allow` 列表会从 Pi 的完整已注册工具目录中选择，因此可以启用预设激活前处于 inactive 状态的工具；`deny` 只从原 active baseline 中移除工具，`allow: ["*"]` 仍表示不限制且不会启用全部工具。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。
+- 只有显式设置 `"autoActivate": true` 的预设参与自动启用；文件名（包括 `default.json`）没有特殊作用。
+- 项目预设优先于全局预设；项目 scope 存在候选时，即使项目候选无效或冲突也会 fail closed，不会回退到全局预设。
+- 同 ID 项目预设会遮蔽全局预设，包括无效 shadow 或显式 opt-out。
 - `/preset use none` 会记录 session branch 的 opt-out。
-- Active stack 选择会跟随 Pi session tree branch。
+- Active Preset 选择会跟随 Pi session tree branch。
 - 恢复的 branch 状态优先于新 session 自动启用。
-- 自动启用的 agent profile 优先于独立 stack autoload。
+- 自动启用的 Agent Profile 优先于独立预设 autoload。
 
 完整字段见英文 [stack schema](../../reference/stack-schema.md)（schema v2 使用 `parameters`），模板语法见[参考](../../reference/macros-and-slots.md)。

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

@@ -10,7 +10,7 @@
 
 `/preset ui restart` 会替换 server，`/preset ui stop` 会关闭它。
 
-编辑器绑定在带 session token 的可用 `127.0.0.1` 端口；多个项目可以同时运行。读取、预览和 payload 检查在合适范围内可用；写入要求 Pi 信任项目，并且文件被限制在 pi-forge 的 stack/profile 存储内。可以在 `.pi/forge/config.json` 中设置偏好端口：
+编辑器绑定在带 session token 的可用 `127.0.0.1` 端口；多个项目可以同时运行。读取、预览和 payload 检查在合适范围内可用；写入要求 Pi 信任项目，并且文件被限制在 Pi Forge 的预设/Profile 存储内。可以在 `.pi/forge/config.json` 中设置偏好端口：
 
 ```json
 {
@@ -20,11 +20,16 @@
 
 端口被占用时会自动选择其他端口。请不要把带 token 的编辑器 URL 暴露或代理到不可信网络。写入操作要求项目已被 Pi 信任。
 
-## Prompt stack 工作区
+## 界面语言
+
+编辑器界面提供英文和中文。使用顶栏的语言选择器（Auto / English / 中文）；选择会写入项目配置中的 `webEditor.locale`。默认为 `Auto`，跟随浏览器语言，首次页面渲染也会参考浏览器的 `Accept-Language` 请求头。界面框架、内置预设/Profile 界面以及预览/差异停靠栏均已本地化；编译器诊断信息、插件提供的设置页面以及预设中自行编写的内容保持其原始语言。
+
+## 预设工作区
 
 支持：
 
-- 从默认 Pi mirror 新建 stack；
+- 从默认 Pi mirror 新建预设；
+- 在 **堆栈** tab 中编排有序的 Block/Slot；
 - 结构化和原始 JSON 编辑；
 - 拖拽排序、启用/禁用、校验和完整编译预览；
 - 工具/skill 搜索、精确名称 chips 和通配符策略；
@@ -32,13 +37,13 @@
 - 原生 pi-forge 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。
+已有 ID 在编辑时不可修改；需要新 ID 时使用 **Fork**，避免破坏 Profile 引用和当前选择。工具栏的 scope 下拉（默认 `project`）决定新建、导入和 fork 的写入位置：选择 `global` 写入用户全局 `~/.pi/forge/prompt-stacks`，选择 `project` 写入项目 `.pi/forge/prompt-stacks`；这些目录名在 0.5.3 中为兼容性暂时保留。列表会为全局预设显示 `global` badge；保存和删除通过 `global:<id>` 路由精确作用于全局文件。保存、导入、fork 和删除后会重新加载当前 Pi session。
 
 ## Agent profile 工作区
 
-列表显示 profile ID、名称、模型、思考等级、stack、校验状态、auto-activation 和 last-applied provenance。每个 profile 都带 `project` / `global` scope badge；同 ID 的 shadow 对会显示 `shadows global:<id>` 或 `shadowed by project:<id>`。
+列表显示 Profile ID、名称、模型、思考等级、预设、校验状态、auto-activation 和 last-applied provenance。每个 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。
+可信项目通过 **New profile** 旁的 scope 下拉（默认 `project`）选择目标 scope：选择 `global` 写入用户全局 `~/.pi/forge/agent-profiles`，选择 `project` 写入项目 `.pi/forge/agent-profiles`。全局 Profile 可通过显式 `global:<id>` 路由编辑、校验、保存、一次性应用和删除；未限定路由始终只作用于项目资源。编辑全局 Profile 时，预设下拉只显示全局预设。Model 选项来自 Pi registry，thinking 选项反映模型支持，预设选项来自同一个 repository。编辑器会拒绝同 scope 内第二个 auto-activation Profile。
 
 ## Delegation
 

package/examples/custom-system-status-extension/README.md

@@ -2,12 +2,12 @@
 
 This example shows how trusted pi-forge extension modules can register a custom macro and custom slot without importing `@zihanw/pi-forge` from a loose Pi extension file.
 
-It registers:
+It registers two renderers that sample the machine when the prompt is compiled:
 
-- `{{ extensions.cpuLoad }}` macro: one-line CPU load summary.
-- `machine-status` slot: CPU load, OS load average, memory, and uptime snapshot.
+- `{{ extensions.cpuLoad }}` macro: one-line CPU load summary sampled when that macro is rendered.
+- `machine-status` slot: CPU load, OS load average, memory, and uptime sampled when that slot is rendered.
 
-The renderers are synchronous, so this example uses Node's OS load average and memory APIs. It is a rough machine-load signal, not an async sampled CPU-utilization profiler.
+This is compile-time telemetry, not a continuous sampler: no background timer runs and nothing streams while the model is generating. pi-forge performs the full Stack compilation for the first provider request of each user turn (and for explicit Preview/Diff compilation); tool-result follow-up requests do not rerun the full Stack. The macro and slot render independently, so their snapshots may differ slightly.
 
 ## Try It
 
@@ -26,7 +26,7 @@ Start Pi, trust the project if prompted, then run:
 /preset use custom-system-status
 ```
 
-Use `/preset diagnostics` to confirm the extension file is listed under loaded pi-forge extensions.
+Use `/preset diagnostics` to confirm the extension file is listed under loaded pi-forge extensions. Start another user turn or recompile Preview to sample again. `/preset reload` is only needed after changing the extension or stack files.
 
 ## Where To Put The Extension
 
@@ -54,7 +54,7 @@ Each module exports a default function or named `register` function:
 ```ts
 export default function register(api) {
   api.registerMacro({ name: "cpuLoad", dependencies: [], render: ({ env, helpers }) => "..." });
-  api.registerSlot({ name: "machine-status", render: () => "..." });
+  api.registerSlot({ name: "machine-status", dependencies: [], render: ({ options, helpers }) => "..." });
 }
 ```
 

package/examples/custom-system-status-extension/index.ts

@@ -12,10 +12,10 @@ interface ForgeRegistrationApi {
 		name: string;
 		source?: string;
 		description?: string;
+		dependencies?: string[];
 		options?: Record<string, unknown>;
 		render: (ctx: {
 			options: Record<string, unknown>;
-			format: () => "xml" | "plain" | "json";
 			helpers: {
 				escapeXml(value: string): string;
 				plainBullet(label: string, value: string): string;
@@ -24,7 +24,7 @@ interface ForgeRegistrationApi {
 	}): () => void;
 }
 
-interface SystemStatusSnapshot {
+export interface SystemStatusSnapshot {
 	logicalCores: number;
 	cpuModel: string;
 	load1: number;
@@ -37,18 +37,24 @@ interface SystemStatusSnapshot {
 	uptimeSeconds: number;
 }
 
-export default function registerSystemStatus(api: ForgeRegistrationApi): void {
+export default function registerSystemStatus(
+	api: ForgeRegistrationApi,
+	sampleSystemStatus: () => SystemStatusSnapshot = readSystemStatus,
+): void {
 	api.registerMacro({
 		name: "cpuLoad",
 		source: "pi-forge-example-system-status",
-		description: "Current machine CPU load as normalized 1-minute OS load average.",
-		render: () => formatCpuLoad(readSystemStatus()),
+		description: "Machine CPU load sampled when the prompt is compiled.",
+		dependencies: [],
+		// Renderers run during prompt compilation. Read a fresh snapshot for each render.
+		render: () => formatCpuLoad(Object.freeze(sampleSystemStatus())),
 	});
 
 	api.registerSlot({
 		name: "machine-status",
 		source: "pi-forge-example-system-status",
-		description: "Current machine CPU, memory, and uptime snapshot.",
+		description: "Machine CPU, memory, and uptime sampled when the prompt is compiled.",
+		dependencies: [],
 		options: {
 			format: { type: "enum", values: ["plain", "xml"], default: "plain" },
 			heading: { type: "string", default: "Machine status" },
@@ -56,14 +62,15 @@ export default function registerSystemStatus(api: ForgeRegistrationApi): void {
 			includeUptime: { type: "boolean", default: true },
 		},
 		render: (ctx) => {
-			const snapshot = readSystemStatus();
+			// Do not capture this at registration time: sample when the slot is rendered.
+			const snapshot = Object.freeze(sampleSystemStatus());
 			const includeMemory = ctx.options.includeMemory !== false;
 			const includeUptime = ctx.options.includeUptime !== false;
 			const heading = typeof ctx.options.heading === "string" && ctx.options.heading.trim()
 				? ctx.options.heading.trim()
 				: "Machine status";
 
-			if (ctx.format() === "xml") {
+			if (ctx.options.format === "xml") {
 				const lines = [
 					"<machine_status>",
 					`  <cpu logical_cores=\"${snapshot.logicalCores}\" normalized_load_1m=\"${snapshot.normalizedLoad1.toFixed(3)}\" model=\"${ctx.helpers.escapeXml(snapshot.cpuModel)}\">${ctx.helpers.escapeXml(formatCpuLoad(snapshot))}</cpu>`,

package/examples/fake-assistant-direct-output-prompt-stack.json

@@ -0,0 +1,48 @@
+{
+  "schemaVersion": 2,
+  "type": "pi-forge.prompt-stack",
+  "id": "fake-assistant-direct-output",
+  "name": "Fake Assistant: Direct Output",
+  "description": "Model-specific experiment: append an ordinary assistant text message after chat history to suggest that tagged reasoning has already finished. Compatibility varies by model, provider, and endpoint; verify with an A/B run before use.",
+  "autoActivate": false,
+  "mode": "replace",
+  "defaults": {
+    "syntheticMessagesVisible": false,
+    "unresolvedMacroPolicy": "warn"
+  },
+  "context": {
+    "allowDuplicateChatHistory": false,
+    "mergeConsecutiveRoles": false
+  },
+  "tools": {
+    "deny": [
+      "*"
+    ]
+  },
+  "items": [
+    {
+      "kind": "block",
+      "id": "direct-answer-role",
+      "name": "Direct Answer Role",
+      "enabled": true,
+      "role": "system",
+      "content": "You are a concise assistant. Answer the user's latest request directly and include only the requested result."
+    },
+    {
+      "kind": "slot",
+      "id": "chat-history",
+      "name": "Chat History",
+      "enabled": true,
+      "slot": "chat-history"
+    },
+    {
+      "kind": "block",
+      "id": "fake-completed-thinking",
+      "name": "Fake Completed Thinking",
+      "enabled": true,
+      "role": "assistant",
+      "content": "<think>思考已完成，直接输出结果。</think>"
+    }
+  ],
+  "parameters": {}
+}

package/examples/hack-prompt-stack.json

@@ -0,0 +1,118 @@
+{
+  "schemaVersion": 2,
+  "type": "pi-forge.prompt-stack",
+  "id": "regex-hack",
+  "name": "Regex Hack Pack",
+  "description": "Default layout plus outgoing-history regex rules: ANSI escapes are removed and illustrative sk-/ghp_ token shapes are redacted. This is a non-exhaustive demo, not a general secret scanner.",
+  "autoActivate": false,
+  "mode": "replace",
+  "defaults": {
+    "syntheticMessagesVisible": false,
+    "unresolvedMacroPolicy": "warn"
+  },
+  "context": {
+    "allowDuplicateChatHistory": false
+  },
+  "tools": {
+    "allow": [
+      "*"
+    ]
+  },
+  "items": [
+    {
+      "kind": "block",
+      "id": "main-role",
+      "name": "Pi Default Role",
+      "enabled": true,
+      "role": "system",
+      "content": "You are an expert coding assistant operating inside pi, a coding agent harness. You help users by reading files, executing commands, editing code, and writing new files."
+    },
+    {
+      "kind": "slot",
+      "id": "tools",
+      "name": "Available Tools",
+      "enabled": true,
+      "role": "system",
+      "slot": "tools",
+      "options": {
+        "format": "plain",
+        "onlyWithSnippets": true
+      }
+    },
+    {
+      "kind": "slot",
+      "id": "project-context",
+      "name": "Project Context",
+      "enabled": true,
+      "role": "system",
+      "slot": "project-context"
+    },
+    {
+      "kind": "slot",
+      "id": "date-cwd",
+      "name": "Date and Working Directory",
+      "enabled": true,
+      "role": "system",
+      "slot": "date-cwd"
+    },
+    {
+      "kind": "slot",
+      "id": "chat-history",
+      "name": "Chat History",
+      "enabled": true,
+      "slot": "chat-history",
+      "options": {
+        "stripAssistantThinking": false
+      }
+    }
+  ],
+  "regex": {
+    "schemaVersion": 1,
+    "rules": [
+      {
+        "id": "strip-ansi-escapes",
+        "name": "ANSI terminal escape codes removed from outgoing history",
+        "enabled": true,
+        "stage": "history",
+        "targets": [
+          "messages"
+        ],
+        "pattern": "\\x1B\\[[0-?]*[ -/]*[@-~]",
+        "flags": "g",
+        "replace": ""
+      },
+      {
+        "id": "redact-api-keys-outgoing",
+        "name": "Illustrative sk-/ghp_ token shapes redacted on every provider request",
+        "enabled": true,
+        "stage": "history",
+        "effect": "outgoing",
+        "frequency": "request",
+        "targets": [
+          "messages"
+        ],
+        "pattern": "\\b(sk-[A-Za-z0-9_-]{12,}|ghp_[A-Za-z0-9]{20,})\\b",
+        "flags": "g",
+        "replace": "[REDACTED]"
+      },
+      {
+        "id": "redact-api-keys-finalize",
+        "name": "Illustrative sk-/ghp_ token shapes scrubbed from the stored transcript",
+        "enabled": true,
+        "stage": "compiled",
+        "effect": "finalize",
+        "targets": [
+          "messages"
+        ],
+        "roles": [
+          "assistant",
+          "toolResult"
+        ],
+        "pattern": "\\b(sk-[A-Za-z0-9_-]{12,}|ghp_[A-Za-z0-9]{20,})\\b",
+        "flags": "g",
+        "replace": "[REDACTED]"
+      }
+    ]
+  },
+  "parameters": {}
+}

package/examples/minimal-prompt-stack.json

@@ -0,0 +1,40 @@
+{
+  "schemaVersion": 2,
+  "type": "pi-forge.prompt-stack",
+  "id": "minimal",
+  "name": "Minimal Worker",
+  "description": "Minimal Pi approximation of the DeepSeek Harness Minimal shape: the exact one-line persona, chat history, and only Pi's stock bash plus edit. It does not replicate DSH's persistent shell, editor tool, PTY, sandbox, or deployment semantics.",
+  "autoActivate": false,
+  "mode": "replace",
+  "defaults": {
+    "syntheticMessagesVisible": false,
+    "unresolvedMacroPolicy": "warn"
+  },
+  "tools": {
+    "allow": [
+      "bash",
+      "edit"
+    ]
+  },
+  "items": [
+    {
+      "kind": "block",
+      "id": "worker-role",
+      "name": "Worker Role",
+      "enabled": true,
+      "role": "system",
+      "content": "You are a helpful software engineer assistant."
+    },
+    {
+      "kind": "slot",
+      "id": "chat-history",
+      "name": "Chat History",
+      "enabled": true,
+      "slot": "chat-history",
+      "options": {
+        "includeSummaries": false
+      }
+    }
+  ],
+  "parameters": {}
+}

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@zihanw/pi-forge",
-	"version": "0.5.1",
-	"description": "Pi extension for prompt stacks, one-shot agent profiles, policy, import, and debugging.",
+	"version": "0.5.3",
+	"description": "Pi extension for editable context presets, one-shot agent profiles, tool policy, and request debugging.",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/MacroSony/pi-forge.git"