@zihanw/pi-forge 0.3.0 → 0.3.1

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,72 @@ 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. A stack can reference the registered name and pass declarative options; the executable `render` body lives in a Pi extension or another explicitly installed package.
+
+```ts
+import { registerMacro, registerSlot } from "@zihanw/pi-forge";
+
+registerMacro({
+  name: "ticketId",
+  description: "Current ticket id from session variables.",
+  render: (ctx) => ctx.variables.toMacroText(ctx.variables.get("ticket.id")),
+});
+
+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"
+  }
+}
+```
+
+Missing custom slots are validation warnings until the registering extension is installed and loaded. Built-in macros and slots use the same registry internally, so `getRegisteredMacros()` and `getRegisteredSlots()` can be used as implementation references.
+
+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 a trusted Pi extension file.
+
+When pi-forge is installed as a package, custom extensions can import `@zihanw/pi-forge`. When developing from a local checkout loaded through Pi settings, set an explicit local path as shown in the example README, such as `PI_FORGE_MODULE=/path/to/pi-forge/src/index.ts`. pi-forge keeps the macro/slot registry process-global so compatible local module copies share registrations.
+
 ## Stack reference
 
 ### Full item types
@@ -312,6 +378,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 +504,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 +522,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,57 @@ 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。Stack 只引用已注册名称并传入声明式 options；真正的 `render` 逻辑放在 Pi 扩展或明确安装的包里。
+
+```ts
+import { registerMacro, registerSlot } from "@zihanw/pi-forge";
+
+registerMacro({
+  name: "ticketId",
+  description: "从会话变量读取当前 ticket id。",
+  render: (ctx) => ctx.variables.toMacroText(ctx.variables.get("ticket.id")),
+});
+
+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"),
+});
+```
+
+缺失的自定义 slot 会产生校验 warning，直到对应注册扩展安装并加载。内置宏和 slot 也使用同一个 registry，可用 `getRegisteredMacros()` 和 `getRegisteredSlots()` 作为实现参考。
+
+完整可复制的扩展和 stack 示例见 [examples/custom-system-status-extension](examples/custom-system-status-extension)。它在可信 Pi 扩展文件中注册 `{{cpuLoad}}` 宏和 `machine-status` slot。
+
+如果 pi-forge 是作为 package 安装的，自定义扩展可以 import `@zihanw/pi-forge`。如果你是通过 Pi settings 加载本地 checkout，请按示例 README 设置显式路径，例如 `PI_FORGE_MODULE=/path/to/pi-forge/src/index.ts`。pi-forge 会把 macro/slot registry 放在当前进程的 global registry 中，因此兼容的本地模块副本可以共享注册结果。
+
 ## Stack 参考
 
 ### 完整条目类型
@@ -310,6 +361,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 +487,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 +505,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"}