@zihanw/pi-forge 0.3.2 → 0.4.0

package/README.zh-CN.md

@@ -1,523 +1,150 @@
 # pi-forge
 
-[English](README.md) | [简体中文](README.zh-CN.md)
+[English](README.md) | [简体中文](README.zh-CN.md) · [中文文档](docs/zh-CN/README.md)
 
 ![pi-forge header](https://raw.githubusercontent.com/MacroSony/pi-forge/main/assets/pi-forge-header-concept-1.png)
 
-**pi-forge** 让你自定义 Pi 的思考方式和行为。它提供 prompt stack（提示栈）：这些 JSON 文件可以替换、追加到或插入到 Pi 的默认系统提示词之前，并控制 AI 的性格、可见工具、对话历史布局、模板变量和 prompt 转换。
+**pi-forge** 让你自定义 [Pi](https://github.com/badlogic/pi-mono) 的思考方式和行为。Prompt stack（提示栈）负责 prompt 组合和工具策略；agent profile（agent 配置预设）可以一次性应用模型、思考等级和提示栈。
 
-可以把它理解为 AI agent 的角色卡。
+可以把它理解为 AI agent 的角色卡和工作台。
 
-## 能做什么
+## 主要能力
 
-- **赋予 Pi 个性** — 把它变成创意写手、角色扮演搭档、严格的代码审查员，或任何你想要的风格。
-- **一键切换模式** — 在"写代码"、"写小说"、"做翻译"之间用一条命令切换。
-- **控制 AI 看到什么** — 选择每个 prompt 中出现哪些工具、技能和项目上下文。
-- **按栈限制工具和技能** — 为专注模式启用工具策略，并过滤技能可见性。
-- **使用模板变量** — 定义 `{{char}}` / `{{user}}` 这样的静态值，并在 prompt 文本里使用 ST 风格的轮次/会话变量宏。
-- **转换发出和最终消息文本** — 对选中的历史、最终编译 prompt 或已结束的 assistant 消息执行确定性 regex 替换。
-- **导入 SillyTavern 预设** — 一条命令把 ST 角色预设迁移到 Pi。
-- **调试 prompt** — 拦截并查看实际发给模型的内容。
+- 把 system prompt、聊天历史、工具、skills、项目上下文和运行时数据组合成可排序的 block 和 slot。
+- 用一条命令切换编程、审查、写作、角色扮演和翻译模式。
+- 保存并应用完整的模型/思考等级/提示栈预设。
+- 按栈严格限制工具，并过滤模型可见的 skills。
+- 使用静态、轮次和会话变量，以及支持嵌套的模板宏。
+- 对发给模型的 prompt 或最终 assistant 消息执行确定性 regex 转换。
+- 导入 SillyTavern 预设并检查迁移报告。
+- 在本地 Web 编辑器中管理 stack/profile，并检查实际 provider payload。
+- 用明确启用的 profile 运行实验性、需要审批的前台 subagent。
 
-## 快速上手
+## 安装
 
-### 安装
+pi-forge 需要 Node.js 22.19 或更高版本。
 
 ```bash
 pi install npm:@zihanw/pi-forge
 ```
 
-### 第一个 prompt stack
+安装或更新后请重启 Pi。运行中的 Pi host 会向 extension 提供 SDK package；pi-forge 只在开发和测试中固定精确版本，以保证结果可复现，不会用 peer dependency 锁死 Pi 频繁发布的版本。兼容策略见[开发与兼容性](docs/development/setup.md#pi-compatibility)（英文）。
 
-从 [examples/default-prompt-stack.json](examples/default-prompt-stack.json) 创建 `.pi/forge/prompt-stacks/default.json`。
+## 五分钟上手
 
-默认示例参考了 `@earendil-works/pi-coding-agent/dist/core/system-prompt.js` 中 Pi 自己的 prompt builder，但把它拆成可移动的 pi-forge slot：角色、工具、guidelines、Pi 文档提示、append-system-prompt、项目上下文、技能、日期/cwd 和对话历史。
+### 1. 创建 prompt stack
+
+从 [默认 Pi mirror](examples/default-prompt-stack.json) 创建 `.pi/forge/prompt-stacks/default.json`：
 
 ```bash
 mkdir -p .pi/forge/prompt-stacks
-$EDITOR .pi/forge/prompt-stacks/default.json
+cp examples/default-prompt-stack.json .pi/forge/prompt-stacks/default.json
 ```
 
-把示例 JSON 粘贴进去。如果你就在这个仓库里开发，也可以直接执行 `cp examples/default-prompt-stack.json .pi/forge/prompt-stacks/default.json`。
-
-搞定。重启 Pi 或执行 `/preset reload`。如果当前没有选中其他栈，`default.json` 会自动启用；如果你之前执行过 `/preset use none` 或选择了别的栈，请执行 `/preset use default`。
+如果你通过 npm 安装而不是 clone 仓库，请直接打开 `/preset ui` 新建 stack；编辑器使用相同的 Pi mirror 布局。
 
-### 可视化编辑器
-
-不想手写 JSON？pi-forge 内置了 Web 编辑器：
+重启 Pi，或执行：
 
+```text
+/preset reload
+/preset use default
 ```
-/preset ui
-```
-
-拖拽、新建、编辑、校验、查看完整预览和捕获的 payload、用 tabs 管理变量/context/regex 规则、切换深色模式、通过原始 stack JSON 修复高级字段、导入、导出、fork、删除栈 —— 全在浏览器里完成。新栈会从默认 Pi prompt mirror 布局开始。Stack metadata 可以折叠，方便把当前编辑区留在屏幕内。Policy tab 会显示已注册工具和已加载 skills，并提供已选 pattern chips 和过滤输入，方便用精确名称编写 allow/deny 规则，同时保留通配符写法。
-
-导入支持原生 pi-forge stack JSON，也支持 SillyTavern 预设 JSON。SillyTavern 预设会自动转换成 prompt stack；如果一个预设里有多个 `character_id` 配置，编辑器会询问要使用哪一个。
-
-编辑器默认运行在一个可用的 `127.0.0.1` 端口，并带有会话 token，所以多个 Pi 实例可以同时打开各自的编辑器。如果 Pi 在 session navigation 或新会话后重新初始化扩展，同一项目中的 `/preset ui` 会复用已有编辑器 URL，不会遗留旧 server 后再开一个新端口。写入需要项目被信任，且只会写入 prompt-stack 存储目录。新建的栈会写入 `.pi/forge/prompt-stacks`；旧的 `.pi/prompt-stacks` 栈仍然可读取和编辑。保存、导入、fork、删除成功后会重新加载到当前 Pi 会话。需要时可以用 `/preset ui restart` 或 `/preset ui stop`。
-
-要把旧栈复制到新位置，执行 `/preset migrate-stacks`。加 `--dry-run` 可先预览，加 `--overwrite` 可覆盖目标文件，加 `--delete-legacy` 会在复制成功后删除旧文件。
-
-如果想优先使用某个端口，可以创建 `.pi/forge/config.json`。如果该端口被占用，pi-forge 会回退到其他可用端口，并显示实际 URL：
-
-```json
-{
-  "webEditor": {
-    "port": 41738
-  }
-}
-```
-
-## 使用场景
 
-### 🎭 角色扮演 & 创意写作
+没有其他 stack 或已恢复 session 选择优先时，`default.json` 会自动启用。
 
-让 Pi 扮演一个角色。在系统提示词中定义性格，用 user message 注入写作风格规则，用 `{{lastUserMessage}}` 在对话历史之后重新插入用户输入。
+### 2. 打开可视化编辑器
 
-常用模式：
-- 把长期角色规则放在 `system` block。
-- 把 Pi 运行时上下文（工具、技能、项目）放在 `user` slot。
-- 把 `chat-history` slot 设为跳过最新用户消息。
-- 在最后加一个带 `{{lastUserMessage}}` 的 `user` block。
-
-这样最新请求会更清晰，也不会重复出现。
-
-如果想先从一个基线栈 fork 再改成角色，可以从 [examples/default-prompt-stack.json](examples/default-prompt-stack.json) 开始。
-
-### 🧑‍💻 专注代码审查
-
-创建一个 `reviewer.json` 栈，加入严格的审查规则，例如“优先检查正确性、回归风险、安全问题和缺失测试”。保留 `tools`、`project-context`、`variables` 和 `chat-history` slot，这样 Pi 仍然能检查仓库并看到你暴露的模板变量。
-
-如果你想保留 Pi 原本的编程行为，只额外加上更严格的审查视角，可以使用 `mode: "append"`。
-
-### 🌐 翻译模式
-
-创建一个小型 `translator.json` 栈，用一个 system block 指定语气和目标语言，再保留 `chat-history` 和 `{{lastUserMessage}}` 的布局。这样可以在双语润色、直译、产品本地化审查之间快速切换，而不影响默认助手。
-
-### 🔀 多模式切换
-
-为不同任务创建独立的栈：
-
-```
-.pi/forge/prompt-stacks/
-  coder.json       # 严格编程助手
-  writer.json      # 创意写作搭档
-  translator.json  # 双语翻译
-```
-
-用 `/preset use coder`、`/preset use writer` 等命令切换。
-
-### 🧪 展示 pi-forge 特性的预设
-
-- **Pi mirror** — 从 [examples/default-prompt-stack.json](examples/default-prompt-stack.json) 开始。它保留 Pi 的默认行为，同时把每个运行时区块变成可移动、可检查的 slot。
-- **Focused reviewer** — 见 [examples/reviewer-prompt-stack.json](examples/reviewer-prompt-stack.json)。它禁用写文件工具，把旧聊天历史包裹成背景上下文，从 history 中移除最新用户消息，再用 `{{lastUserMessage}}` 作为明确的 review target 插入。
-- **SillyTavern DM writer** — 见 [examples/sillytavern-dm-writer-prompt-stack.json](examples/sillytavern-dm-writer-prompt-stack.json)。它用 `{{char}}` / `{{user}}` 定义 Dungeon Master 角色，包裹旧冒险历史，把 `{{lastUserMessage}}` 作为当前玩家行动重新插入，并用 regex 清理 OOC 注释、暗骰标记、骰子写法和 `Player:` 前缀。
-
-### 🔧 模板变量
-
-定义稳定的 prompt 常量：
-
-```json
-"variables": {
-  "char": "Konata",
-  "user": "User"
-}
-```
-
-在 prompt 文本里用 ST 风格宏做局部变量读写：
-
-```
-{{setvar::mood::focused}}
-{{getvar::mood}}
-{{setsessionvar::topic::compiler cleanup}}
-```
-
-需要长期保存的项目记忆请写入仓库文件，而不是 pi-forge prompt 变量。
-
-### 📦 SillyTavern 迁移
-
-把 ST 预设导入 Pi：
-
-```
-/preset import-silly ~/SillyTavern/presets/my-preset.json
+```text
+/preset ui
 ```
 
-pi-forge 会把预设转换为 prompt stack，并生成迁移报告，标明哪些已处理、哪些需要手动调整。
-
-可安全表示的 SillyTavern `promptOnly` regex 脚本会作为 history 阶段规则转换成 pi-forge `regex.rules`，包括 full-match token 转换、trim strings、depth 字段和明确的 user/assistant placement。Display-only、prompt/display 混合、DOM/browser、CSS/HTML 美化、JavaScript、不支持的 placement 和无效 regex 脚本会保留为报告项，供手动检查。
+本地编辑器可以新建、fork、校验、预览、导入、导出和删除 prompt stack。切换到 **Agent profiles** 可以管理一次性模型/思考等级/stack 预设，以及实验性 delegation 配置。写入操作要求项目已被信任。
 
-### 🔍 Prompt 调试
+### 3. 保存 profile
 
-查看实际发给模型的内容：
+先正常配置 Pi，然后捕获当前设置：
 
-```
-/payload next save=.pi/forge/payloads/last.json
-```
-
-或者打开 `/preset ui`，点击 **Arm payload**，发送下一条 Pi prompt，然后在浏览器里查看脱敏后的 provider payload。
-
-或者不发送只预览编译结果：
-
-```
-/preset preview
+```text
+/profile save reviewer
+/profile use reviewer
 ```
 
-## 工作原理
+Profile 只应用一次。之后手动修改模型或思考等级会被保留，直到再次应用 profile；当前 prompt stack 的工具策略则会在启用期间持续执行。
 
-一个 prompt stack 是一个 JSON 文件，包含两种条目：
+## 基本概念
 
-| 类型 | 作用 |
-|------|------|
-| **Block** | 在指定位置插入的静态文本（系统提示词、用户消息、助手消息） |
-| **Slot** | 来自 Pi 运行时的动态内容 —— 工具、技能、对话历史、日期、项目上下文等 |
+Prompt stack 是一个有序 JSON 文档，包含：
 
-条目按顺序排列。当栈激活时，pi-forge 会：
+| 类型 | 用途 |
+|---|---|
+| **Block** | 固定的 `system`、`user`、`assistant` 或隐藏 `custom` 文本 |
+| **Slot** | 工具、skills、项目上下文、变量、日期/cwd、聊天历史等运行时内容 |
 
-1. 用你的 `system` 角色 block 和 slot 生成系统提示词，然后按照栈的 `mode` 应用。
-2. 在对话历史周围插入 `user`/`assistant` 角色的 block 和 slot。
-3. 展开 `{{宏}}`，如 `{{lastUserMessage}}`、`{{date}}` 和自定义变量。
-4. 将 stack 的工具策略应用到 Pi 当前 active tools，并过滤 pi-forge 渲染的 tool/skill slot。
-5. 应用已启用的 `history` 和 `compiled` 阶段 outgoing regex 规则。
-6. 可选地在 assistant 消息结束时应用破坏性的 `finalize` regex 规则。
+Stack 可以 `replace`、`append` 或 `prepend` Pi 的基础 system prompt。编译时，pi-forge 会展开宏、插入对话、执行工具策略、过滤自己渲染的 skill 列表，并应用已启用的 regex 规则。
 
-### Slot 一览
+Agent profile 是项目级预设，引用精确 provider/model、思考等级和 prompt stack。它不会重复保存工具或 skill 策略；被引用的 stack 始终是唯一来源。
 
-| Slot | 插入的内容 |
-|------|-----------|
-| `chat-history` | 当前对话 |
-| `tools` | 可用工具及其描述 |
-| `tool-guidelines` | 工具使用指导 |
-| `skills` | 已加载的 Pi 技能 |
-| `project-context` | 项目指令和上下文文件 |
-| `variables` | 静态/会话/轮次模板变量 |
-| `date` / `cwd` / `date-cwd` | 当前日期、可选当前时间和工作目录 |
-| `active-model` | 当前使用的模型 |
-| `append-system-prompt` | 用户追加的系统提示词 |
-| `pi-docs` | Pi 文档指导 |
+推荐从这些示例开始：
 
-### 模式
-
-- **replace**（默认）— 你的栈完全替换 Pi 的系统提示词。
-- **append** — 你的栈追加在 Pi 默认系统提示词之后。
-- **prepend** — 你的栈插入在 Pi 默认系统提示词之前。
+- [默认 Pi mirror](examples/default-prompt-stack.json)：保留 Pi 默认行为，同时让所有区域都可移动。
+- [专注代码审查](examples/reviewer-prompt-stack.json)：只读工具策略、背景历史和明确的最新用户目标。
+- [SillyTavern DM writer](examples/sillytavern-dm-writer-prompt-stack.json)：角色、变量、历史布局和 regex 清理。
+- [自定义 system-status extension](examples/custom-system-status-extension/README.md)：注册可信 macro 和 slot。
 
 ## 常用命令
 
-### 管理 prompt stack
-
-| 命令 | 作用 |
-|------|------|
-| `/preset list` | 显示所有可用栈 |
-| `/preset use <id>` | 激活一个栈 |
-| `/preset use none` | 在当前会话中禁用 prompt stack |
-| `/preset preview [id]` | 查看编译后的 prompt |
-| `/preset validate [id]` | 检查栈是否有问题 |
-| `/preset status` | 显示当前激活栈和诊断摘要 |
-| `/preset diagnostics` | 显示运行时诊断 |
-| `/preset reload` | 从磁盘重新加载栈 |
-| `/preset migrate-stacks [--dry-run] [--overwrite] [--delete-legacy]` | 将旧 `.pi/prompt-stacks` 文件复制到 `.pi/forge/prompt-stacks` |
-| `/preset ui [stop\|restart]` | 打开、停止或重启 Web 编辑器 |
-
-### 导入 & 调试
-
-| 命令 | 作用 |
-|------|------|
-| `/preset import-silly <path>` | 导入 SillyTavern 预设 |
-| `/intercept` | 显示下一条 provider payload |
-| `/payload next [save=<path>]` | 显示并可保存下一条 payload |
-
-## 常用宏
-
-在 block 内容中使用这些宏来插入动态值：
-
-| 宏 | 展开为 |
-|----|--------|
-| `{{lastUserMessage}}` | 用户最新消息 |
-| `{{date}}` | 当前日期 (YYYY-MM-DD) |
-| `{{time}}` | 当前时间 (HH:MM:SS) |
-| `{{cwd}}` | 当前工作目录 |
-| `{{tools}}` | 逗号分隔的工具名 |
-| `{{selectedTools}}` | 所选工具名的别名 |
-| `{{activeModel}}` | 当前模型 (provider/id) |
-| `{{char}}` / `{{user}}` | 栈中定义的自定义变量 |
-
-### 变量宏
-
-```
-{{setvar::name::value}}        设置轮次变量（每条消息清空）
-{{setsessionvar::name::value}} 设置会话变量（持久化）
-{{setvar::session::name::value}} 也可设置会话变量
-{{getvar::name}}               读取变量（轮次 → 会话 → 静态）
-{{getturnvar::name}}           只读取轮次变量
-{{getsessionvar::name}}        只读取会话变量
-{{clearvar::name}}             清除变量
-{{clearturnvar::name}}         清除轮次变量
-{{clearsessionvar::name}}      清除会话变量
-```
-
-### 过滤和条件宏
-
-宏支持嵌套，`::` 分隔符只会在当前宏深度拆分。
-
-| 宏 | 展开为 |
-|----|--------|
-| `{{trim::value}}` | 去掉首尾空白后的 `value` |
-| `{{upper::value}}` | 大写 `value` |
-| `{{lower::value}}` | 小写 `value` |
-| `{{json::value}}` | `value` 的 JSON 字符串字面量 |
-| `{{xml::value}}` | XML 转义后的 `value` |
-| `{{ifvar::name::then::else}}` | 变量存在时输出 `then`，否则输出 `else` |
-| `{{ifeq::name::expected::then::else}}` | 变量等于 `expected` 时输出 `then`，否则输出 `else` |
-| `{{iftools::tool::then::else}}` | 当前工具列表包含 `tool` 时输出 `then`，否则输出 `else` |
-| `{{ifslot::slot::then::else}}` | 启用的 stack 条目包含 `slot` 时输出 `then`，否则输出 `else` |
-
-条件宏是 lazy 的：只有选中的分支会展开，所以被跳过的分支不会设置或清除变量。最后的 `else` 参数可省略，默认输出空文本。
-
-### 可信自定义宏和 slot
-
-自定义宏和 slot 由可信扩展代码注册，不把可执行代码写进 prompt-stack JSON。项目本地自定义代码放在 `.pi/forge/extensions/`。机器级个人自定义代码放在 `~/.pi/forge/extensions/`。pi-forge 会在项目受信任后、stack 校验前先加载全局模块，再加载项目本地模块；两个位置都会在 `/preset reload` 时重新加载。
-
-这些模块会从 pi-forge 接收注册 API，所以不需要 import `@zihanw/pi-forge`，也不需要知道 pi-forge 安装在哪里。
-
-```ts
-// .pi/forge/extensions/ticket-context.ts
-export default function register(api) {
-  api.registerMacro({
-    name: "ticketId",
-    description: "从会话变量读取当前 ticket id。",
-    render: (ctx) => ctx.variables.toMacroText(ctx.variables.get("ticket.id")),
-  });
-
-  api.registerSlot({
-    name: "ticket-context",
-    description: "渲染当前任务的 ticket 上下文。",
-    options: {
-      heading: { type: "string", default: "Ticket context" },
-    },
-    render: (ctx) => [
-      String(ctx.options.heading ?? "Ticket context") + ":",
-      "- Ticket: " + ctx.variables.toMacroText(ctx.variables.get("ticket.id")),
-      "- Project: " + ctx.helpers.normalizePath(ctx.runtime.options.cwd),
-    ].join("\n"),
-  });
-}
-```
-
-支持 `.ts`、`.js`、`.mjs`、`.cjs` 文件，也支持子目录里的 `index.*`。TypeScript 模块应使用 Node 运行时可直接 strip 的语法；如果需要更复杂的构建，使用 `.js` / `.mjs`。模块可以导出 `default function register(api)`，也可以导出具名 `register(api)`。注册的宏和 slot 名称必须在内置项、全局扩展、项目扩展之间唯一；重复名称会显示为扩展加载 warning。
+| 命令 | 用途 |
+|---|---|
+| `/preset ui [stop\|restart]` | 打开或管理 Web 编辑器 |
+| `/preset list` | 列出 prompt stack |
+| `/preset use <id\|none>` | 选择或禁用 stack |
+| `/preset preview [id]` | 编译 stack，但不发送请求 |
+| `/preset validate [id]` | 校验一个或全部 stack |
+| `/preset diagnostics` | 查看运行时和 extension 诊断 |
+| `/profile list` | 列出并 preflight profile |
+| `/profile save <id> [--overwrite]` | 把当前运行时保存为 profile |
+| `/profile use <id>` | preflight 后一次性应用 profile |
+| `/profile status` | 查看上次应用 provenance 和当前 drift |
+| `/payload next [save=<path>]` | 检查下一个经过脱敏的 provider payload |
 
-API 包含 `cwd`、`forgeDir`、`extensionPath`、`helpers`、`registerMacro`、`registerSlot`、`getRegisteredMacros`、`getRegisteredSlots`。对全局模块来说，`forgeDir` 是 `~/.pi/forge`；对项目模块来说，它是 `<project>/.pi/forge`。
+完整列表见[命令参考](docs/zh-CN/reference/commands.md)。
 
-缺失的自定义 slot 会产生校验 warning，直到对应注册模块加载。内置宏和 slot 也使用同一个 registry，可用 `getRegisteredMacros()` 和 `getRegisteredSlots()` 作为实现参考。`/preset diagnostics` 会显示已加载的 pi-forge extension 文件和加载失败信息。
+## 实验性前台 delegation
 
-完整可复制的扩展和 stack 示例见 [examples/custom-system-status-extension](examples/custom-system-status-extension)。它通过 `.pi/forge/extensions/system-status.ts` 注册 `{{cpuLoad}}` 宏和 `machine-status` slot。
+pi-forge 可以把明确授权的 profile 作为干净、前台运行的 Pi 子进程。模型通过 `forge_subagent_profiles` 发现可用 profile，再用 `forge_subagent` 调用；用户可以使用 `/forge-agent plan` 和 `/forge-agent run`。
 
-可复用的 Pi package 仍然可以从 `@zihanw/pi-forge` import `registerMacro` 和 `registerSlot`。`.pi/forge/extensions` 和 `~/.pi/forge/extensions` loader 主要用于不需要 package 样板的小型可信自定义逻辑。
+此功能仍是**实验性功能**，profile 默认不能委派。请在受信任项目的 `.pi/forge/config.json` 或 Web 编辑器 delegation 卡片中逐个启用。除非项目明确授权无人值守的模型调用，否则执行前会显示与不可变计划绑定的审批界面。
 
-## Stack 参考
+> **安全边界：** 当前 backend 是 shared-user 进程，不是操作系统沙箱。“只读”只描述模型可见工具策略。Child 仍有启动用户的 OS 读取权限；可读内容可能发送给所选 provider，并保留在 Pi session 数据中。Timeout 和取消仅为 best effort，`/tree` 不能撤销 provider 请求、计费或外部影响。
 
-### 完整条目类型
+启用前必须阅读[前台 delegation 与安全模型](docs/zh-CN/guides/delegation.md)。
 
-**Block：**
-
-```json
-{
-  "kind": "block",
-  "id": "unique-id",
-  "name": "可读标签",
-  "enabled": true,
-  "role": "system",
-  "content": "你的文本。用 {{宏}} 插入动态内容。"
-}
-```
-
-有效角色：`system`、`user`、`assistant`、`custom`。
-
-**Slot：**
-
-```json
-{
-  "kind": "slot",
-  "id": "unique-id",
-  "name": "对话历史",
-  "enabled": true,
-  "role": "user",
-  "slot": "chat-history",
-  "options": {
-    "includeLastUserMessage": false
-  }
-}
-```
-
-### Chat history 选项
-
-```json
-"options": {
-  "includeLastUserMessage": false,
-  "stripAssistantThinking": true,
-  "includeSummaries": true,
-  "toolMode": "keep",
-  "roles": ["user", "assistant"],
-  "maxMessages": 40,
-  "maxChars": 20000
-}
-```
+## 文档导航
 
-当你在 history 之后使用 `{{lastUserMessage}}` 时设为 `false`，避免用户消息出现两次。
+### 学习
 
-把 `stripAssistantThinking` 设为 `true` 可以从插入的历史中移除之前 assistant 的 thinking block。可见 assistant 文本、tool call 和 tool result 消息会保留。它只影响这个 slot 插入到模型输入里的 history，不会修改当前 agent loop 或已存储 transcript。
+- [快速上手](docs/zh-CN/getting-started.md)
+- [Prompt stack 概念](docs/zh-CN/concepts/prompt-stacks.md)
+- [Agent profile 概念](docs/zh-CN/concepts/agent-profiles.md)
+- [Web 编辑器](docs/zh-CN/guides/web-editor.md)
+- [前台 delegation](docs/zh-CN/guides/delegation.md)
 
-使用 `includeSummaries: false` 可以排除 Pi 的 branch/compaction summary 消息；`roles` 可以只保留指定消息角色；`toolMode: "drop"` 可以移除之前的 tool call/tool result history；`maxMessages` / `maxChars` 可以只保留最近 history。当过滤或截断可能拆散 tool-call pair 时，pi-forge 会移除悬空的 tool call/result，避免发送不一致的 tool history。
+### 参考
 
-### Date slot 选项
+- [命令](docs/zh-CN/reference/commands.md)
+- [英文 stack schema](docs/reference/stack-schema.md)
+- [英文 macros 与 slots](docs/reference/macros-and-slots.md)
+- [英文配置参考](docs/reference/configuration.md)
 
-在 `date` 或 `date-cwd` slot 上设置 `"includeTime": true`，会在当前日期后加入 `HH:MM:SS` 格式的当前时间。
+完整英文文档从 [docs/README.md](docs/README.md) 开始。
 
-### 结构化 slot 格式选项
+## 兼容性原则
 
-结构化运行时 slot 默认使用 XML 风格包装。给 `tools`、`tool-guidelines`、`skills`、`project-context` 或 `variables` slot 添加 `"format": "plain"`，可输出更紧凑的换行分隔文本。
-
-```json
-{
-  "kind": "slot",
-  "id": "tools",
-  "enabled": true,
-  "role": "system",
-  "slot": "tools",
-  "options": {
-    "format": "plain"
-  }
-}
-```
-
-默认 Pi mirror 示例还会用到几个额外 slot 选项：
-
-```json
-{
-  "slot": "tools",
-  "options": {
-    "format": "plain",
-    "onlyWithSnippets": true
-  }
-}
-```
-
-`tools.onlyWithSnippets` 会像 Pi 默认 prompt 一样，只显示带 prompt snippet 的工具。`tool-guidelines.heading`、`tool-guidelines.includePiDefaultGuidelines` 和 `tool-guidelines.piStyle` 用来匹配 Pi 默认的 guidelines 标题和条目。`skills.requireReadTool` 会在 read 工具未启用时隐藏 skills，和 Pi 默认行为一致。
-
-### 工具和技能策略
-
-Prompt stack 可以用栈级 `allow` 或 `deny` 列表限制工具和技能。模式默认精确匹配，也支持 `*` 通配符。
-
-```json
-{
-  "tools": {
-    "allow": ["read", "bash"]
-  },
-  "skills": {
-    "deny": ["browser-danger"]
-  }
-}
-```
-
-使用 `allow` 时，只有匹配的工具或技能保持启用。使用 `deny` 时，除匹配项以外的工具或技能保持启用。同一个资源策略不能同时包含非空 `allow` 和 `deny` 列表；混用会产生 validation error。
-
-工具策略会在栈激活期间通过 Pi 的 active tool list 强制执行。pi-forge 会记住之前的 active tools，并在禁用 prompt stack 或切换到没有工具策略的 stack 时恢复。
-
-技能策略会过滤 pi-forge `skills` slot 渲染出的技能。如果 stack 使用 `mode: "append"` 或 `"prepend"`，Pi base prompt 里可能已经包含未过滤的技能；需要控制技能可见性时请使用 `mode: "replace"`。
-
-### Regex 转换
-
-Prompt stack 可以对发给模型的 prompt 文本执行确定性的 regex 替换，也可以选择清理已结束的 assistant 消息。Outgoing 规则支持 `history` 和 `compiled` 阶段。破坏性的最终消息清理使用 `stage: "compiled"`、`effect: "finalize"` 和 `messages` target。真正的 display-only streaming 转换和 provider-payload 重写还不会生效。
-
-```json
-"regex": {
-  "schemaVersion": 1,
-  "rules": [
-    {
-      "id": "trim-ooc",
-      "enabled": true,
-      "stage": "history",
-      "effect": "outgoing",
-      "pattern": "\\(OOC:[^)]+\\)",
-      "flags": "gi",
-      "replace": "",
-      "roles": ["assistant"],
-      "maxMessages": 20
-    }
-  ]
-}
-```
-
-使用 `stage: "history"` 可以转换 `chat-history` slot 插入的消息。使用 `stage: "compiled"` 并可选配置 `targets: ["system"]`、`["messages"]` 或两者，可以转换最终编译后的 prompt。消息规则可以用 `roles`、`maxMessages`、`maxChars`、`minDepth` 和 `maxDepth` 限制范围，其中 depth `0` 是最新消息。Replacement 使用 JavaScript 语法（`$&` 表示完整匹配，`$1` 表示捕获组；`$0` 也作为完整匹配的别名，`$$` 转义字面 `$`）。`trimStrings` 会从展开后的 replacement match/capture 中移除字面量字符串，对应 SillyTavern 的 Trim Out 行为。支持的 regex flags 是 `g`、`i`、`m`、`s` 和 `u`。
-
-要在 streaming 结束后清理一条 assistant 消息，使用 `effect: "finalize"`：
-
-```json
-{
-  "id": "finalize-ooc",
-  "enabled": true,
-  "stage": "compiled",
-  "effect": "finalize",
-  "targets": ["messages"],
-  "roles": ["assistant"],
-  "pattern": "\\s*\\(OOC:[^)]+\\)",
-  "flags": "gi",
-  "replace": ""
-}
-```
-
-警告：`finalize` 在 `message_end` 运行，TUI 可能已经显示过原始 streaming 输出。它会把清理后的 replacement message 交回 Pi，因此 transcript 中不会保留模型原始输出。
-
-`effect: "outgoing"` 改变发给模型的输入。`effect: "finalize"` 改变已结束的 assistant transcript 内容。`effect: "display"` 和 `"both"` 会通过校验并产生 warning，但在真正的 display transforms 实现前运行时会忽略。
-
-SillyTavern 导入会把确定性的 prompt-only `{{match}}` / `$0` full-match replacement 转成 JavaScript `$&`（`$0` 和 `$&` 在 pi-forge 中都可以用），在 `source.sillytavern` 中保留原始 regex 元数据，并作为 history 阶段规则运行以保持 depth 相对 chat。display-only、browser、unsupported-placement 脚本保留为 report-only。Web 编辑器提供结构化 Regex 对话框来编辑这些规则字段，并会保留需要通过 raw JSON 编辑的高级未知字段。
-
-### Variables slot 选项
-
-```json
-{
-  "kind": "slot",
-  "id": "variables",
-  "enabled": true,
-  "role": "user",
-  "slot": "variables",
-  "options": {
-    "includeStatic": true,
-    "includeSession": true,
-    "includeTurn": false,
-    "format": "xml"
-  }
-}
-```
-
-## 开发环境搭建
-
-```bash
-git clone <repo>
-cd pi-forge
-npm install
-npm run build
-# .pi/settings.json 已指向包根目录
-pi    # 启动 Pi，信任项目，必要时 /reload
-```
-
-运行测试：
-
-```bash
-npm test
-```
-
-类型检查：
-
-```bash
-npm run typecheck
-```
-
-构建 package 输出：
-
-```bash
-npm run build
-```
+- npm 安装不会要求用户跟随某个精确 Pi patch 版本。
+- Release 会分别记录实际测试过的 Pi 最低版本和当前版本。
+- 如果实验性 subagent 依赖的 host capability 不存在，它应在 provider transport 前明确报错并 fail closed。
+- 普通 prompt stack 和 profile 使用不应因为可选 delegation backend 不兼容而失效。
 
 ## License
 
-MIT
+[MIT](LICENSE)

package/SUBAGENT_ADAPTER_CONTRACT.md

@@ -0,0 +1,5 @@
+# Subagent adapter contract
+
+The authoritative experimental contract moved to [`docs/reference/subagent-adapter.md`](docs/reference/subagent-adapter.md).
+
+This compatibility pointer remains at the published root path so existing links continue to work.