@zihanw/pi-forge 0.3.0 → 0.3.2

package/README.md

@@ -50,7 +50,7 @@ Prefer clicking over typing JSON? pi-forge has a built-in web editor:
 /preset ui
 ```
 
-Drag, drop, edit, validate, inspect full previews and captured payloads, manage variables/context/regex rules in tabs, switch dark mode, recover through raw stack JSON, import, export, fork, and delete stacks — all in your browser. Stack metadata is collapsible so the active editor stays in view.
+Drag, drop, create, edit, validate, inspect full previews and captured payloads, manage variables/context/regex rules in tabs, switch dark mode, recover through raw stack JSON, import, export, fork, and delete stacks — all in your browser. New stacks start from the default Pi prompt mirror layout. Stack metadata is collapsible so the active editor stays in view. The policy tab shows registered tools and loaded skills with selected-pattern chips and filtering, so allow/deny rules can be built from exact names while still supporting wildcards.
 
 Import accepts native pi-forge stack JSON and SillyTavern preset JSON. SillyTavern presets are converted to prompt stacks automatically; if a preset contains multiple `character_id` configs, the editor asks which one to use.
 
@@ -192,7 +192,7 @@ Items are arranged in order. When the stack is active, pi-forge:
 | `skills` | Loaded Pi skills |
 | `project-context` | Project instructions and context files |
 | `variables` | Static/session/turn template variables |
-| `date` / `cwd` / `date-cwd` | Current date and working directory |
+| `date` / `cwd` / `date-cwd` | Current date, optional current time, and working directory |
 | `active-model` | Which model is being used |
 | `append-system-prompt` | User's appended system prompt text |
 | `pi-docs` | Pi documentation guidance |
@@ -257,6 +257,79 @@ Use these in block content to insert dynamic values:
 {{clearsessionvar::name}}     clear a session variable
 ```
 
+### Filter and conditional macros
+
+Nested macros are supported, and `::` separators are parsed only at the current macro depth.
+
+| Macro | Expands to |
+|-------|-----------|
+| `{{trim::value}}` | `value` with leading/trailing whitespace removed |
+| `{{upper::value}}` | Uppercase `value` |
+| `{{lower::value}}` | Lowercase `value` |
+| `{{json::value}}` | JSON string literal for `value` |
+| `{{xml::value}}` | XML-escaped `value` |
+| `{{ifvar::name::then::else}}` | `then` when a variable exists, otherwise `else` |
+| `{{ifeq::name::expected::then::else}}` | `then` when a variable equals `expected`, otherwise `else` |
+| `{{iftools::tool::then::else}}` | `then` when the selected tool list includes `tool`, otherwise `else` |
+| `{{ifslot::slot::then::else}}` | `then` when the enabled stack items include `slot`, otherwise `else` |
+
+Conditional branches are lazy: only the selected branch is expanded, so skipped branches cannot set or clear variables. The final `else` argument is optional and defaults to empty text.
+
+### Trusted custom macros and slots
+
+Custom macros and slots are registered by trusted extension code, not embedded in prompt-stack JSON. For project-local customization, put registration modules in `.pi/forge/extensions/`. For machine-wide personal customization, put them in `~/.pi/forge/extensions/`. pi-forge loads global modules first, then project-local modules, after project trust and before stack validation. Both locations reload on `/preset reload`.
+
+These modules receive the registration API from pi-forge, so they do not need to import `@zihanw/pi-forge` or know where pi-forge is installed.
+
+```ts
+// .pi/forge/extensions/ticket-context.ts
+export default function register(api) {
+  api.registerMacro({
+    name: "ticketId",
+    description: "Current ticket id from session variables.",
+    render: (ctx) => ctx.variables.toMacroText(ctx.variables.get("ticket.id")),
+  });
+
+  api.registerSlot({
+    name: "ticket-context",
+    description: "Render ticket context for the current task.",
+    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"),
+  });
+}
+```
+
+The stack remains declarative:
+
+```json
+{
+  "kind": "slot",
+  "id": "ticket-context",
+  "enabled": true,
+  "role": "system",
+  "slot": "ticket-context",
+  "options": {
+    "heading": "Current ticket"
+  }
+}
+```
+
+Supported module files are `.ts`, `.js`, `.mjs`, `.cjs`, and `index.*` inside a subdirectory. TypeScript modules should stick to syntax Node can strip at runtime, or you can use `.js` / `.mjs` instead. A module can export either `default function register(api)` or `export function register(api)`. Registered macro and slot names must be unique across built-ins, global extensions, and project extensions; duplicate names show as extension load warnings.
+
+The API includes `cwd`, `forgeDir`, `extensionPath`, `helpers`, `registerMacro`, `registerSlot`, `getRegisteredMacros`, and `getRegisteredSlots`. For global modules, `forgeDir` is `~/.pi/forge`; for project modules, it is `<project>/.pi/forge`.
+
+Missing custom slots are validation warnings until the registering module is loaded. Built-in macros and slots use the same registry internally, so `getRegisteredMacros()` and `getRegisteredSlots()` can be used as implementation references. `/preset diagnostics` shows loaded pi-forge extension files and load failures.
+
+For a complete copyable extension and stack, see [examples/custom-system-status-extension](examples/custom-system-status-extension). It registers a `{{cpuLoad}}` macro and a `machine-status` slot from `.pi/forge/extensions/system-status.ts`.
+
+Reusable Pi packages can still import `registerMacro` and `registerSlot` from `@zihanw/pi-forge`. The `.pi/forge/extensions` and `~/.pi/forge/extensions` loaders are intended for small trusted customizations without package boilerplate.
+
 ## Stack reference
 
 ### Full item types
@@ -312,6 +385,10 @@ Set `stripAssistantThinking` to `true` to remove prior assistant thinking blocks
 
 Use `includeSummaries: false` to omit Pi branch/compaction summary messages, `roles` to keep only specific message roles, `toolMode: "drop"` to remove prior tool-call/tool-result history, and `maxMessages` / `maxChars` to keep only recent history. When filters or limits can break tool-call pairs, pi-forge removes dangling tool calls/results instead of sending inconsistent tool history.
 
+### Date slot options
+
+Set `"includeTime": true` on a `date` or `date-cwd` slot to include the current time in `HH:MM:SS` after the current date.
+
 ### Structured slot format options
 
 Structured runtime slots default to XML-style wrappers. Add `"format": "plain"` to `tools`, `tool-guidelines`, `skills`, `project-context`, or `variables` slots for compact newline-separated output.
@@ -434,6 +511,8 @@ SillyTavern imports convert deterministic prompt-only `{{match}}` / `$0` full-ma
 ```bash
 git clone <repo>
 cd pi-forge
+npm install
+npm run build
 # .pi/settings.json already points at the package root
 pi    # start Pi, trust the project, /reload if needed
 ```
@@ -450,6 +529,12 @@ Typecheck:
 npm run typecheck
 ```
 
+Build package output:
+
+```bash
+npm run build
+```
+
 ## License
 
 MIT

package/README.zh-CN.md

@@ -50,7 +50,7 @@ $EDITOR .pi/forge/prompt-stacks/default.json
 /preset ui
 ```
 
-拖拽、编辑、校验、查看完整预览和捕获的 payload、用 tabs 管理变量/context/regex 规则、切换深色模式、通过原始 stack JSON 修复高级字段、导入、导出、fork、删除栈 —— 全在浏览器里完成。Stack metadata 可以折叠，方便把当前编辑区留在屏幕内。
+拖拽、新建、编辑、校验、查看完整预览和捕获的 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` 配置，编辑器会询问要使用哪一个。
 
@@ -190,7 +190,7 @@ pi-forge 会把预设转换为 prompt stack，并生成迁移报告，标明哪
 | `skills` | 已加载的 Pi 技能 |
 | `project-context` | 项目指令和上下文文件 |
 | `variables` | 静态/会话/轮次模板变量 |
-| `date` / `cwd` / `date-cwd` | 当前日期和工作目录 |
+| `date` / `cwd` / `date-cwd` | 当前日期、可选当前时间和工作目录 |
 | `active-model` | 当前使用的模型 |
 | `append-system-prompt` | 用户追加的系统提示词 |
 | `pi-docs` | Pi 文档指导 |
@@ -255,6 +255,64 @@ pi-forge 会把预设转换为 prompt stack，并生成迁移报告，标明哪
 {{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。
+
+API 包含 `cwd`、`forgeDir`、`extensionPath`、`helpers`、`registerMacro`、`registerSlot`、`getRegisteredMacros`、`getRegisteredSlots`。对全局模块来说，`forgeDir` 是 `~/.pi/forge`；对项目模块来说，它是 `<project>/.pi/forge`。
+
+缺失的自定义 slot 会产生校验 warning，直到对应注册模块加载。内置宏和 slot 也使用同一个 registry，可用 `getRegisteredMacros()` 和 `getRegisteredSlots()` 作为实现参考。`/preset diagnostics` 会显示已加载的 pi-forge extension 文件和加载失败信息。
+
+完整可复制的扩展和 stack 示例见 [examples/custom-system-status-extension](examples/custom-system-status-extension)。它通过 `.pi/forge/extensions/system-status.ts` 注册 `{{cpuLoad}}` 宏和 `machine-status` slot。
+
+可复用的 Pi package 仍然可以从 `@zihanw/pi-forge` import `registerMacro` 和 `registerSlot`。`.pi/forge/extensions` 和 `~/.pi/forge/extensions` loader 主要用于不需要 package 样板的小型可信自定义逻辑。
+
 ## Stack 参考
 
 ### 完整条目类型
@@ -310,6 +368,10 @@ pi-forge 会把预设转换为 prompt stack，并生成迁移报告，标明哪
 
 使用 `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 选项
+
+在 `date` 或 `date-cwd` slot 上设置 `"includeTime": true`，会在当前日期后加入 `HH:MM:SS` 格式的当前时间。
+
 ### 结构化 slot 格式选项
 
 结构化运行时 slot 默认使用 XML 风格包装。给 `tools`、`tool-guidelines`、`skills`、`project-context` 或 `variables` slot 添加 `"format": "plain"`，可输出更紧凑的换行分隔文本。
@@ -432,6 +494,8 @@ SillyTavern 导入会把确定性的 prompt-only `{{match}}` / `$0` full-match r
 ```bash
 git clone <repo>
 cd pi-forge
+npm install
+npm run build
 # .pi/settings.json 已指向包根目录
 pi    # 启动 Pi，信任项目，必要时 /reload
 ```
@@ -448,6 +512,12 @@ npm test
 npm run typecheck
 ```
 
+构建 package 输出：
+
+```bash
+npm run build
+```
+
 ## License
 
 MIT

package/dist/compiler.d.ts

@@ -0,0 +1,10 @@
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { CompileMessagesResult, CompileSystemPromptResult, PromptRuntime, PromptStack, PromptVariableValue, PromptVariableStore } from "./types.ts";
+export declare function createPromptVariableStore(sessionVariables?: Record<string, PromptVariableValue>): PromptVariableStore;
+export declare function resetTurnVariables(store: PromptVariableStore): void;
+export declare function markSessionVariablesClean(store: PromptVariableStore): void;
+export declare function compileSystemPrompt(stack: PromptStack, runtime: PromptRuntime, baseSystemPrompt: string): CompileSystemPromptResult;
+export declare function compileMessages(stack: PromptStack, runtime: PromptRuntime, originalMessages: AgentMessage[]): CompileMessagesResult;
+export declare function getLatestUserMessage(messages: AgentMessage[]): string | undefined;
+export declare function agentMessageToPreviewText(message: AgentMessage): string;
+//# sourceMappingURL=compiler.d.ts.map

package/dist/compiler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compiler.d.ts","sourceRoot":"","sources":["../src/compiler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,KAAK,EAEX,qBAAqB,EACrB,yBAAyB,EACzB,aAAa,EACb,WAAW,EAKX,mBAAmB,EACnB,mBAAmB,EACnB,MAAM,YAAY,CAAC;AAgBpB,wBAAgB,yBAAyB,CAAC,gBAAgB,GAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAM,GAAG,mBAAmB,CAEzH;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,mBAAmB,GAAG,IAAI,CAGnE;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,mBAAmB,GAAG,IAAI,CAE1E;AAED,wBAAgB,mBAAmB,CAClC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,aAAa,EACtB,gBAAgB,EAAE,MAAM,GACtB,yBAAyB,CAuC3B;AAED,wBAAgB,eAAe,CAC9B,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,aAAa,EACtB,gBAAgB,EAAE,YAAY,EAAE,GAC9B,qBAAqB,CA2CvB;AAED,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG,MAAM,GAAG,SAAS,CASjF;AAED,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CAWvE"}