@zihanw/pi-forge 0.5.9 → 0.5.10

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

@@ -6,7 +6,7 @@ Pi-forge 引入了能力（Capabilities）：会话级动态提示词指令与
 
 ## 环境要求与安装
 
-- **宿主版本：** 最低支持 Pi 0.87.0。已发布的 Forge 0.5.7 声明 peer 范围为 `>=0.87.0 <0.88.0`；Forge 0.5.8 支持 `>=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.1.0`；Forge 0.5.9 支持联合范围 `>=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.4.0`（开发 SDK 更新至 1.3.0，`typebox@1.3.27`；最低 SDK 0.87 保持不变；不声称对 0.86 的双重运行时支持）。能力功能需要 Forge 0.5.5。详见 [Pi 1.0 兼容指南](../guides/pi-1-compatibility.md)。
+- **宿主版本：** 最低支持 Pi 0.87.0。已发布的 Forge 0.5.7 声明 peer 范围为 `>=0.87.0 <0.88.0`；Forge 0.5.8 支持 `>=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.1.0`；Forge 0.5.10 支持联合范围 `>=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.5.0`（开发 SDK 更新至 1.4.0，`typebox@1.3.27`；最低 SDK 0.87 保持不变；不声称对 0.86 的双重运行时支持）。能力功能需要 Forge 0.5.5。详见 [Pi 1.0 兼容指南](../guides/pi-1-compatibility.md)。
 - **项目信任：** 激活能力、预设绑定或添加手动指令需要项目处于受信任状态（`isProjectTrusted()`）。
 - **兼容性限制：** 包含 `tools.initial` 的配置需要新版 Forge 支持；旧版 Forge 会忽略 `initial`，因而配置不具备向下降级兼容性。
 
@@ -48,6 +48,35 @@ Pi-forge 引入了能力（Capabilities）：会话级动态提示词指令与
 - **授权撤销行为：** 在 Preset 中撤销授权（将 `modelCallable` 设为 `false`）或删除绑定项，不会追溯抹除已激活的快照；用户通过 CLI（`/capability disable` 或 `/capability reset`）或 Web 面板停用是标准恢复路径。
 - **用户与 Agent 所有权及去重：** 激活项记录归属主体（`user` 或 `agent`）。重复 `enable` 已激活的能力具备幂等性，绝不自动在用户与 Agent 之间转移所有权（takeover）。接管必须通过显式关闭后再重新启用。
 
+## 执行授权（Forge 0.5.10）
+
+活跃 Preset 含有限制性的工具策略时，**所有工具调用（包括 codemode 嵌套调用）都必须获得 Forge 授权**。有效集以配置的 `tools.initial` 为起点，否则采用按策略计算的基线，再在 allow/deny 约束下应用已启用 Capability 的添加与移除。关闭 Capability 会立即撤销不再获授权工具的执行权限；默认集或其他 Capability 仍可能授权该工具。不会中断正在执行的工具。Forge 依据这个有效集，而不是 Pi 的 active 工具列表；仅列入 allow 不会启用有效集之外的工具。对当前未启用工具的调用，若可由 Capability 提供权限，拦截提示会指向 `forge_capability`。
+
+有效集中的工具 `P` 还授权**同一注册来源**的已注册 `P__*` 子工具。例如，启用 `mcp` 或 `mcp__hitch` 后，pi-mcp-adapter 6+/7 以 `mcp__hitch__<tool>` 名义发出的同来源调用可以执行，无需把每个子工具写入 `allow`。注册来源不同或缺失时不授予此权限。Preset deny 与活动 Capability remove 仍可阻止子工具；可用精确 deny 项排除单个子工具。Capability `remove` 使用精确名称，不支持通配符。
+
+同步会保留已 active 且由有效集或同来源命名空间规则授权的工具，以及注册 exposure 为 `deferred` 或 `codemode` 的工具，但 Preset deny 或 Capability remove 排除的工具仍会撤掉。保留不授予执行权限：未授权的已发现工具保留在可调用表中，让门禁返回可操作的拦截提示，而非误导性的 “not found”。其他外部激活的 `direct` 工具仍会撤掉；旧 Pi 缺失 exposure 时按 `direct` 处理。关闭 Capability 仍会撤掉其不再获授权的 direct 添加项。`tools.initial` 保持权威；无 `initial` 的仅 deny 预设和混合 wildcard allow（例如 `allow: ["*", "read"]`）保持既有的外部新增吸收进基线语义，可因此授权这些工具。纯选择性 allow（不含 `*`）不会仅因外部激活而获得执行授权。保留减少不必要的撤销，但不能消除所有 OpenAI 缓存回退。
+
+无活跃 Preset 或无限制性工具策略时，执行行为不变。仅 `tools.initial` 或仅 `allow: ["*"]` 不会启用新门禁；allow 列表含有非 `*` 项，或 deny 列表非空时才启用。已有的显式 Capability 移除仍生效。
+
+以下 **Preset 工具策略片段**使用 deny（不同时使用 allow，两种策略互斥），允许启用 `mcp__hitch`，但即使父工具已启用，也禁止其中一个子工具：
+
+```json
+{
+  "tools": {
+    "deny": ["mcp__hitch__delete"],
+    "initial": ["forge_capability"]
+  }
+}
+```
+
+Capability 可配置 `"tools": { "add": ["mcp__hitch"], "remove": [] }`。启用后，除 `mcp__hitch__delete` 外的同来源子工具均获授权。关闭后撤销该命名空间权限，除非仍有其他有效父工具授权它。请使用会话中实际注册的名称。
+
+### 已知限制
+
+- **发现：** codemode `ALL_TOOLS` / `searchTools()` 与 `tool_search` 仍可能显示未授权工具名。Forge 只阻断执行，不过滤发现。
+- **模型 API：** codemode `models.generateImages()`（Pi 1.0 新增）与 `models.classify()`（0.99 已有）不经过 `tool_call`，Forge 无法拦截。关闭生图 Capability **不能**禁用这些 API。只有通过 SDK 编程式装配 `createCodemodeExtension({ models: false })` 才能关闭这类 codemode 模型访问；Pi settings 没有对应开关。
+- **前缀缓存：** 在 OpenAI Responses/Completions 系列传输上，任何工具移除（包括关闭 Capability 导致的工具移除）都会使该会话后续请求发送当前完整工具表。移除检测会扫描转录历史，因此只要该历史仍保留，重新启用工具也不能恢复增量投递。这会破坏前缀缓存。Anthropic 原生 `tool_removal` 路径不受这种回退影响。Forge 旨在尽量保留可缓存前缀，不承诺缓存命中。
+
 ## Preset 授权的 Agent 控制
 
 Preset 的 `capabilities` 绑定支持智能体自主选择与启用能力：
@@ -230,7 +259,7 @@ Forge 在每次发起模型请求时通过两阶段拼装动态投影能力增
 
 ## 兼容性与安全边界
 
-- **要求上游 Pi 最低版本：** 必须使用上游 Pi 0.87.0 或更高版本（Forge 0.5.9 支持 `>=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.4.0`；Forge 0.5.8 支持 `>=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.1.0`；已发布 0.5.7 的 peer 元数据保持 `>=0.87.0 <0.88.0` 不变）。不提供对 0.86 的双重运行时支持。之前在 `context` hook 中操作或读取完整 System 消息的第三方扩展必须迁移到 `context_with_system` 完整 hook。详见 [Pi 1.0 兼容指南](../guides/pi-1-compatibility.md)。
+- **要求上游 Pi 最低版本：** 必须使用上游 Pi 0.87.0 或更高版本（Forge 0.5.10 支持 `>=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.5.0`；Forge 0.5.8 支持 `>=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.1.0`；已发布 0.5.7 的 peer 元数据保持 `>=0.87.0 <0.88.0` 不变）。不提供对 0.86 的双重运行时支持。之前在 `context` hook 中操作或读取完整 System 消息的第三方扩展必须迁移到 `context_with_system` 完整 hook。详见 [Pi 1.0 兼容指南](../guides/pi-1-compatibility.md)。
 - **`before_agent_start` 注入时机：** `before_agent_start` 阶段强制注入的 System 提示词在 Pi 执行流中仍然晚于 `context_with_system` 生效。
 - **前置扩展上下文改写：** Pi 允许 hook 改写消息。当可见元数据锚点或未锚定事件需要定位时，Forge 要求输入与规范会话投影有唯一的有序对应，否则中止而非猜测（fail-closed）。Pi 可能先保存排队的 custom 消息、但暂不放入工具续跑上下文：Forge 仅容许位置能唯一确定的 custom 消息缺省，忽略其重新生成的外层时间戳；保留传入对象，不擅自把缺省对话补回请求。前置改写因而可能与该定位方式冲突；简单后移不保证组合安全。通用插件、warming、自动 overflow 兼容性仍未全面验收。
 - **上游缺陷与协议限制：** 上游 Pi 元数据分块及语义截断缺陷（semantic-cut defect）未被修复，压缩检查点位置保持不变。旧会话和旧投递载体保持原样，不支持继续恢复能力状态；Forge 不会迁移旧 JSONL 或改写历史摘要。不支持也不承诺 OMP（Oh My Pi）。

package/docs/zh-CN/reference/provider-support.md

@@ -24,7 +24,7 @@ Pi 和 Forge 在每次请求时都读取当前模型的 `compat` 标记：
 | API | 指令正文 | 工具变化 |
 |---|---|---|
 | `anthropic-messages` | 有标记时为 `role: "system"` 消息。Pi 会把它留到下一条 assistant 消息之前再发，因此不会插在 `tool_use` 和对应的 `tool_result` 之间；记录在用户消息之前的更新，实际会发在该用户消息之后。 | 需要 `supportsMidConvoToolChanges` 且至少一个初始工具。**Pi 1.0.1 起：** 请求级工具列表固定不变（初始工具加一个保留的 deferred 占位工具）；之后的工具直接以完整定义写在 `tool_addition` 块里（同名重定义会替换旧定义），用 `tool_removal` 撤下。**Pi 1.0.0 及更早：** 之后的工具带 `defer_loading` 追加到请求级列表，列表只增不减，同名重定义会退回发送完整列表。其他情况（包括会话开始时没有任何活动工具，例如 `tools.initial: []`）在请求级别发送当前列表。 |
-| `openai-responses`、`openai-codex-responses`、`azure-openai-responses` | 有标记时，在原位置发送 `developer` 消息（支持 developer 角色的推理模型）或 `system` 消息。 | 保留的历史中只有新增时，新工具在原位置加载；历史中任何位置出现过移除或同名重声明，这次请求就改为在请求级别发送完整的当前列表。 |
+| `openai-responses`、`openai-codex-responses`、`azure-openai-responses` | 有标记时，在原位置发送 `developer` 消息（支持 developer 角色的推理模型）或 `system` 消息。 | 保留的历史中只有新增时，新工具在原位置加载；历史中任何位置出现过移除或同名重声明，这次及后续请求就改为在请求级别发送完整的当前列表，直到不再保留该历史。 |
 | `openai-completions` | 有标记时，在原位置发送 `developer` 或 `system` 消息。 | 有 `supportsMidConvoToolAdditions` 时新增在原位置加载；移除和重声明改为发送完整的当前列表。 |
 | `mistral-conversations` | 有标记时，在原位置发送 `system` 消息。 | 始终在请求级别发送完整的当前列表。 |
 | Google Generative AI / Vertex | 始终折入 `systemInstruction`，没有会话中路径。 | 完整的当前列表。 |
@@ -58,7 +58,7 @@ Pi 和 Forge 在每次请求时都读取当前模型的 `compat` 标记：
 - **`anthropic/claude-sonnet-5`，fallback 路径：** 工具变化后的那次请求没有读到任何缓存，因为 Pi 改写了首条 system 提示词和工具列表。模型还对带标记的用户更新产生了怀疑，确认后才使用新工具。
 - **OpenAI Responses / Codex：** 之前的测试中，一次移除就改为发送完整工具列表，缓存读取降为 0；只有新增的请求保住了前缀。
 
-想让缓存稳定，优先选用带原生工具变化标记的模型；在 Responses 系列模型上，如果在意缓存复用，尽量不要在同一会话中移除工具。
+为尽量保留可缓存前缀，优先选用带原生工具变化标记的模型；不承诺缓存命中。在 OpenAI Responses/Completions 系列传输上，任何移除（包括关闭 Capability 导致的工具移除）都会因移除检测扫描转录历史，使该会话后续请求发送当前完整工具表。只要该历史仍保留，重新启用工具也不能恢复增量投递。Anthropic 原生 `tool_removal` 路径不受这种回退影响。
 
 ## 检查自己的环境
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zihanw/pi-forge",
-	"version": "0.5.9",
+	"version": "0.5.10",
 	"description": "Pi extension for editable context presets, one-shot agent profiles, tool policy, and request debugging.",
 	"repository": {
 		"type": "git",
@@ -45,10 +45,10 @@
 		]
 	},
 	"peerDependencies": {
-		"@earendil-works/pi-agent-core": ">=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.4.0",
-		"@earendil-works/pi-ai": ">=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.4.0",
-		"@earendil-works/pi-coding-agent": ">=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.4.0",
-		"@earendil-works/pi-tui": ">=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.4.0",
+		"@earendil-works/pi-agent-core": ">=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.5.0",
+		"@earendil-works/pi-ai": ">=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.5.0",
+		"@earendil-works/pi-coding-agent": ">=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.5.0",
+		"@earendil-works/pi-tui": ">=0.87.0 <0.88.0 || 0.99.0 || 0.99.1 || 0.99.2 || >=1.0.0 <1.5.0",
 		"typebox": "*"
 	},
 	"peerDependenciesMeta": {
@@ -69,10 +69,10 @@
 		}
 	},
 	"devDependencies": {
-		"@earendil-works/pi-agent-core": "1.3.0",
-		"@earendil-works/pi-ai": "1.3.0",
-		"@earendil-works/pi-coding-agent": "1.3.0",
-		"@earendil-works/pi-tui": "1.3.0",
+		"@earendil-works/pi-agent-core": "1.4.0",
+		"@earendil-works/pi-ai": "1.4.0",
+		"@earendil-works/pi-coding-agent": "1.4.0",
+		"@earendil-works/pi-tui": "1.4.0",
 		"@types/node": "22.20.1",
 		"@vitejs/plugin-vue": "6.0.8",
 		"playwright-core": "1.61.1",