@istuen/pt 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 istuen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,219 @@
+# Pt
+
+Pt 把领域知识做成可配置的智能体上下文。通过切换配置，Agent 具备不同 Session Context（每轮注入），推理时可通过 Turn Context（按需触发）查阅手册。
+
+---
+
+## 用 Pt 做什么
+
+- **复用 Prompt，不必每次重写**：把重复的 prompt 写成 Pt Domain，配一份 Profile，每次会话切换立即获取领域知识——换项目、换场景，不用重写。
+- **拆分固定与按需，控制上下文成本**：领域知识拆成 Session Context（每轮注入的固定知识 + 参考索引）和 Turn Context（按索引触发的详细手册）——背景每轮都在，详细内容推理时按需查阅。
+- **沉淀对话与经验为可迭代资产**：把对话里的决策、经验、知识用文档显化，入 git 可追溯、可迭代——知识更新改一处，所有会话生效。
+- **连接外部系统与数据源**：领域知识不限于项目内——外部数据源的查询方式、外部系统的操作指引，都可写成 Domain 注入 Agent。
+
+---
+
+## 安装
+
+Pt 是 Pi 扩展，两种安装方式任选其一。
+
+### 方式一：Pi 插件安装（推荐）
+
+```bash
+pi install npm:@istuen/pt
+```
+
+Pi 自动加载 Pt。项目级安装（团队共享，写入 `.pi/settings.json`）加 `-l`：
+
+```bash
+pi install -l npm:@istuen/pt
+```
+
+### 方式二：npm 安装 + 手动配置
+
+```bash
+npm install @istuen/pt
+```
+
+然后在 `.pi/settings.json` 或 `~/.pi/agent/settings.json` 配置扩展入口：
+
+```json
+{
+  "pi": {
+    "extensions": ["./node_modules/@istuen/pt/dist/index.js"]
+  }
+}
+```
+
+## 快速开始
+
+### 1. 激活内建 Profile
+
+进入 pi 后用 `/pt-profile` 选择 `guide`，或直接 `/pt-profile guide`：
+
+```
+/pt-profile guide
+```
+
+也可以启动时用 flag 激活：
+
+```bash
+pi --pt-profile guide
+```
+
+内建 `guide` Profile 用 dev-knowledge Blueprint + 五个内建 Domain（`user-info` / `agent-info` / `project-analysis` / `authoring` / `usage`）——Agent 立刻有“用户身份 + Agent 身份 + 怎么写 Pt 资产 / 怎么分析项目 / 怎么用 Pt”的知识。
+
+### 2. 加自己的知识
+
+用自然语言告诉 Agent 你的项目情况——`guide` Profile 会分析当前项目，帮你创建合适的 Domain 和 Profile，或直接告诉你该怎么创建。
+
+---
+
+## 命令速查
+
+| 命令 | 作用 |
+|---|---|
+| `/pt-profile` | 列出所有可用 Profile |
+| `/pt-profile <name>` | 切换 Profile（下一轮生效） |
+| `/pt` | 查看当前编译状态 |
+| `/pt flows` | 列出可触发手册 |
+| `/manual:<domain>` | 注入该 Domain 的手册段到 Turn Inject |
+| `/<flow> <args>` | 触发 Domain 的 FlowTemplate |
+| `--pt-profile <name>` | Pi 启动时激活 Profile（CLI 优先级最高） |
+
+LLM 工具（Agent 可调用）：`pt_status` / `pt_flows` / `pt_manual` / `pt_verify` / `pt_check_refs`。
+
+---
+
+## Pt 的机制：四个概念
+
+Pt 用四个概念组织——写领域知识，定转换结构，组装身份配置，编译出上下文：
+
+```
+Pt Domain ──→ Blueprint ──→ Pt Profile ──→ Agent Context
+ 领域知识      转换结构       身份配置      编译后上下文
+```
+
+### Pt Domain — 领域知识
+
+领域知识，一个 `.md` 文件。用 MD 语法组成：**H2 做 Module**（内容段，如 `## Scene`、`## Flows`）、**H3 做语义**（项名，如 `### 角色分工`）、**列表项做描述**（`- desc: ...`）。可写业务领域的设计语义、工作流说明、外部系统操作指导。Module 允许自定义，通过 Profile 引用即可。放 `.pt/assets/domains/`。
+
+例子：
+```markdown
+---
+name: user-info
+---
+# user-info
+
+## User
+### who-am-i
+- desc: 我是这个项目的开发者
+
+### preferences
+- desc: 偏好类型安全、模块化设计
+```
+
+### Blueprint — 转换结构
+
+转换结构，一个 `.blueprint.yaml` 文件。定义 Profile 可以把哪些 Domain 注入到 Agent——声明有哪些聚合组（`groups`），每个组聚合哪些 Module，注入到哪（`inject: session` 会话级 / `inject: turn` 轮次级）。跨项目复用。放 `.pt/assets/blueprints/`。
+
+```yaml
+name: dev-knowledge
+groups:
+  - name: 会话背景
+    inject: session
+    modules: [Scene, Participant]
+  - name: 触发索引
+    inject: session
+    modules: [Trigger]
+  - name: 参考手册
+    inject: turn
+    modules: [Rules, Flows, Checklists]
+```
+
+### Pt Profile — 身份配置
+
+Profile 是 Pt 最核心的功能，承接用户与 Agent 之间的会话配置。切换 Profile 会影响：会话背景、主题、用户与 Agent 的身份信息、参考信息等——让 Agent 专注当前推理范围。一个 `.profile.md` 文件，选一个 Blueprint + 列要用的 Domain。项目级，不跨项目复用。放 `.pt/assets/profiles/`。
+
+例子：
+```markdown
+---
+name: my-dev
+blueprint: dev-knowledge
+domains: [user-info, authoring, usage]
+---
+```
+
+### Agent Context — 编译后上下文
+
+Profile 编译后的产物，分两面——**Session Context**（每轮注入：会话背景、身份信息、触发索引）和 **Turn Context**（按需触发：推理时查阅的参考手册）。带 hash 缓存（`.pt/cache/agent-contexts/`），资产变了自动重编译。
+
+**一句话串起来**：写 Domain → 用 Blueprint 定转换结构 → 用 Profile 组装身份 → 编译出 Agent Context 两面注入。
+
+---
+
+## Pt 资产包（Pack）
+
+v15.x 起，Pt 资产按 **Pack** 组织——一个 Pack 是一个目录（含 `domains/` + `blueprints/` + `profiles/` 子目录 + 可选 `pt-asset-pack.yaml` manifest）。Pt 加载 4 类 Pack，优先级从高到低：
+
+| Pack | 来源 | 寻址名 | 说明 |
+|---|---|---|---|
+| **project** | `<cwd>/.pt/assets/`（或 `pt.project-pack-dir` 配置） | `@prj` | 项目专属资产，永远最高优先 |
+| **settings** | `.pi/settings.json` 的 `pt.asset-packs[]` | `@<manifest-name>` | 团队共享 / 第三方 Pack，按声明顺序后者赢 |
+| **global** | `~/.pt/assets/` | `@gbl` | 用户跨项目共用资产 |
+| **builtin** | `src/builtin/assets/`（随 npm 包） | `@pt` | 内建 fallback（guide / dev-knowledge 等） |
+
+### 跨 Pack 引用
+
+Profile / Domain / Blueprint 引用可限定 Pack：`@pack-name/asset-name`。不限定时按优先级自动解析（project > settings > global > builtin）。
+
+```yaml
+# profile.md frontmatter
+blueprint: @pt-internal/dev-knowledge    # 限定到 pt-internal pack
+domains: [@gbl/team-stdlib, workflow]    # @gbl 限定 + 无前缀自动解析
+```
+
+### settings 声明 Pack
+
+在 `.pi/settings.json` 加载第三方 / 团队 Pack（只声明 path，name 从 manifest 读）：
+
+```json
+{
+  "pt": {
+    "asset-packs": [
+      { "path": "~/projects/pt-team-stdlib/assets" },
+      { "path": "../shared-pt-assets" }
+    ],
+    "project-pack-dir": ".pt/assets"
+  }
+}
+```
+
+`project-pack-dir` 可指向项目外路径（`~` / 绝对 / 相对 cwd 都支持）。
+
+### Profile `use` 单继承
+
+Profile 可 `use` 另一 Profile 作为基础，增量覆盖：
+
+```yaml
+---
+name: my-dev
+use: @pt-internal/pt-dev          # 继承 pt-dev 作为基础
+blueprint: @team-stdlib/minimal   # 覆盖 use 的 blueprint
+domains: [my-domain]              # 追加到 use 的 domains
+---
+```
+
+合并规则：`name` 强制（不继承）/ `blueprint` 覆盖 / `tagline` 覆盖 / `domains` 追加去重 / `groups` 同名替换。不写 `use` = 完全独立 Profile（back-compat）。
+
+---
+
+## 开发
+
+技术栈：TypeScript + tsup + Vitest + Biome。零运行时依赖（除 yaml 库用于 Blueprint 解析）。
+
+---
+
+## License
+
+MIT

package/dist/agent/api-bridge.d.ts

@@ -0,0 +1,8 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { AgentAPI, AgentUI } from "../schema.js";
+/** AgentAPI 的 ui 字段类型（NonNullable<AgentAPI["ui"]>）。 */
+type AgentUIContext = AgentUI;
+export declare function toAgentAPI(pi: ExtensionAPI, ctx: {
+    ui: AgentUIContext;
+}): AgentAPI;
+export {};

package/dist/agent/api-bridge.js

@@ -0,0 +1,83 @@
+// src/agent/api-bridge.ts — Pi ExtensionAPI ↔ AgentAPI 桥接（P1.3 抽出）
+//
+// 把 Pi ExtensionAPI 转换成 AgentAPI（结构类型子集）供 AgentAdapter 使用。
+// 同一个 Pi runtime 复用同一个 AgentAPI wrapper——否则 PiAdapter 每次 registerInject
+// 都会得到不同的对象身份，导致 system prompt handler 被重复注册。
+//
+// v12.x（issue pt-session-singleton-pi-web-pollution 修复）：
+//   - 原设计 `api.log` getter / `onInjected` 直接读写 module-level `session` 单例
+//     → tab B 的 wrapper.onInjected 写 tab B 的 lastBuiltPrompt 但走的是 module 单例
+//     → tab A 跑 turn 时 `lastBuiltPrompt` 也是 tab B 的（被覆盖）
+//   - 改造为 per-pi wrapper 内部维护 `currentSessionId` 闭包变量：
+//     - wrapper 的 `api.on` 包装函数在每个 handler 触发前自动从 `args[1]?.sessionManager`
+//       拿 sessionId 写入 `currentSessionId`
+//     - `api.log` getter / `onInjected` 通过 `currentSessionId` 走 `getSessionById(...)`
+//       取 per-session state
+//   - TUI 模式下只有一个 pi 实例，行为等同 module-level 单例（同一 sessionId 始终）
+import { getSessionById } from "../session.js";
+/** 将 Pi ExtensionAPI 转换为 AgentAPI（结构类型子集，运行时透明）。
+ *  Pi ExtensionAPI 是 AgentAPI 的超集，多余方法（registerCommand/registerFlag 等）不暴露给 Adapter。
+ *  v9.1：提供 ui 能力，adapter 可走 ui.notify 报错 / ui.setStatus 设状态（不需 console）。
+ *  v10.x：提供 log 能力，adapter 的 try/catch 异常走 session.logger（不再 swallow）。
+ *  ctx 用 Pi 扩展的 ctx（ExtensionContext/ExtensionCommandContext 都含 ui）——子集够用。
+ *
+ *  同一个 Pi runtime 复用同一个 AgentAPI wrapper，否则 PiAdapter 每次 registerInject
+ *  都会得到不同的对象身份，导致系统 prompt handler 被重复注册。 */
+const agentApiCache = new WeakMap();
+export function toAgentAPI(pi, ctx) {
+    let holder = agentApiCache.get(pi);
+    if (!holder) {
+        let currentCtx = ctx;
+        // v12.x：closure 捕获 currentSessionId，供 api.log/onInjected 拿 per-session state
+        const stateRef = { currentSessionId: undefined };
+        // v12.x：on 包装——handler 触发前自动从 args[1] ctx 拿 sessionId 注入 stateRef
+        const onWrapped = (event, handler) => {
+            pi.on(event, ((event, extCtx) => {
+                // 提取 sessionId：extCtx 是 ExtensionContext
+                const c = extCtx;
+                stateRef.currentSessionId = c?.sessionManager?.getSessionId?.();
+                return handler(event, extCtx);
+            }));
+        };
+        const api = {
+            on: onWrapped,
+            registerCommand: (name, spec) => pi.registerCommand(name, spec),
+            registerFlag: (name, spec) => pi.registerFlag(name, spec),
+            getFlag: (name) => pi.getFlag(name),
+            ui: {
+                notify: (msg, level) => currentCtx.ui.notify(msg, level),
+                setStatus: (name, text) => currentCtx.ui.setStatus(name, text),
+            },
+            // v12.x：api.log 走 per-session logger（避免 tab A 写到 tab B 的日志文件）
+            get log() {
+                const sid = stateRef.currentSessionId;
+                return sid ? getSessionById(sid).logger?.toWriter() : undefined;
+            },
+            // v12.x：onInjected 写 per-session lastBuiltPrompt
+            onInjected: (systemPrompt) => {
+                const sid = stateRef.currentSessionId;
+                if (sid)
+                    getSessionById(sid).lastBuiltPrompt = systemPrompt;
+            },
+        };
+        holder = {
+            api,
+            setContext: (nextCtx) => {
+                currentCtx = nextCtx;
+            },
+            currentSessionId: undefined,
+        };
+        // 把 stateRef 同步到 holder（保持单一来源）
+        Object.defineProperty(holder, "currentSessionId", {
+            get: () => stateRef.currentSessionId,
+            set: (v) => {
+                stateRef.currentSessionId = v;
+            },
+        });
+        agentApiCache.set(pi, holder);
+    }
+    else {
+        holder.setContext(ctx);
+    }
+    return holder.api;
+}

package/dist/agent/index.d.ts

@@ -0,0 +1,2 @@
+export { PiAdapter } from "./pi-adapter.js";
+export { getAgentAdapter } from "./registry.js";

package/dist/agent/index.js

@@ -0,0 +1,3 @@
+// src/agent/index.ts — Agent 适配器入口
+export { PiAdapter } from "./pi-adapter.js";
+export { getAgentAdapter } from "./registry.js";

package/dist/agent/pi-adapter.d.ts

@@ -0,0 +1,35 @@
+import { type AgentAdapter, type AgentAPI, type AgentContext, type Blueprint, type Domain, type Profile } from "../schema.js";
+/** PiAdapter：封装 Pi Agent 的注入机制。 */
+export declare class PiAdapter implements AgentAdapter {
+    name: string;
+    /** Phase term-P4.3：保留 Pi API 名 system_prompt/context_message——
+     *  这是 AgentAdapter 映射边界声明（Pi 支持哪些 Agent Runtime 层注入位置）。
+     *  Blueprint 用 session/turn 语义值（聚合组 inject 字段），Adapter 内部映射到此字段声明的 Pi API 名。 */
+    supportedTargets: string[];
+    private ctx;
+    private blueprint;
+    private domains;
+    private segment;
+    /** 与当前 Pi runtime 的 AgentAPI 绑定；同一 runtime 不重复注册 handler。
+     *  v12.x：per-pi 实例字段——`registry.ts` 给每个 pi 一个新 PiAdapter，所以 `injectedApi`
+     *  不会被其他 session 覆盖。 */
+    private injectedApi;
+    /** v13.x（issue pt-turn-inject-not-profile-scoped）：当前 Profile——turn 路径 scope 过滤用。 */
+    private profile;
+    /** 设置编译产物（transpile 后调）。v12.x：per-pi 实例字段——本 session 的 segment
+     *  不会被其他 session 覆盖。
+     *  v13.x（issue pt-turn-inject-not-profile-scoped）：加 profile 参数——turn 路径 scope 过滤用。 */
+    setAgentContext(ctx: AgentContext, blueprint: Blueprint, domains: Domain[], profile: Profile): void;
+    /** 清除当前 session 的 context；保留当前 runtime 的 handler 绑定。
+     *  v12.x：per-pi 实例字段——只清本 session 的状态。 */
+    resetInjection(): void;
+    /** 启动时注册：把 AgentContext 注入到 Agent。 */
+    registerInject(api: AgentAPI, ctx: AgentContext, blueprint: Blueprint, domains?: Domain[], profile?: Profile | null): void;
+    /** 查询可用手册（/pt flows 用）。
+     *  v9：遍历 Blueprint 的 inject=turn 聚合组 → 引用 Domain → 找 FlowTemplate + Rules 段的 Rule。 */
+    listManuals(_ctx: AgentContext, blueprint: Blueprint, domains: Domain[]): Array<{
+        name: string;
+        hint?: string;
+        domain: string;
+    }>;
+}

package/dist/agent/pi-adapter.js

@@ -0,0 +1,251 @@
+// src/agent/pi-adapter.ts — PiAdapter：封装 Pi Agent 注入机制
+//
+// Phase 9.6：v9 新增 — AgentAdapter 的 Pi 实现。
+//   - system_prompt 注入：api.on("before_agent_start") 每轮追加 segment
+//   - context_message 触发：api.on("input") 拦截 /manual:xxx 和 /<flow-name>
+//   - 这些是 Agent Runtime 层（Pi API），本 Adapter 在该层做 session→system_prompt、turn→context_message 映射
+//
+// Pt 核心只调 AgentAdapter 接口，不直接调 Pi API。加新 Agent 只加 Adapter。
+//
+// Tech Debt T6: 全用 type guard 收窄，不用 as 断言（pt-quality #1）
+// Tech Debt T2: 用 constants 模块名常量（pt-quality #5）
+//
+// v12.x（issue pt-session-singleton-pi-web-pollution 修复）：
+//   - handler 内部读 `args[1]?.sessionManager?.getSessionId()` 拿 per-session sessionId
+//   - 通过 `getSessionById(sessionId)` 拿 per-session SessionState，**不再读 module-level 单例**
+//   - 配合 `src/agent/registry.ts` 的 per-pi WeakMap 改造，
+//     `this.ctx / this.blueprint / this.domains / this.segment / this.injectedApi` 五个实例字段
+//     现在是 per-pi 隔离——其他 session 的 setContext 不会覆盖本 session 的 segment
+import { AGENT_PI, MOD_FLOWS, MOD_RULES } from "../constants.js";
+import { isFlowTemplateArray, isRuleArray } from "../compile/type-guards.js";
+import { renderInjectionFooter } from "../injection-status.js";
+import { getSessionById } from "../session.js";
+import { filterDomainsByProfile, } from "../schema.js";
+import { renderTurnInject } from "../render/turn-inject.js";
+import { renderSessionInject } from "../render/session-inject.js";
+/** v12.x：从 handler 的 args[1] ctx 提取 sessionId。
+ *  pi 的 `pi.on(event, handler)` 触发时传 `(event, ctx)` 两个参数；通过 AgentAPI 包装后
+ *  handler 拿到 `(...args)`，args[0] = event, args[1] = ctx (ExtensionContext)。 */
+function sessionIdFromArgs(args) {
+    const ctx = args[1];
+    return ctx?.sessionManager?.getSessionId?.();
+}
+/** PiAdapter：封装 Pi Agent 的注入机制。 */
+export class PiAdapter {
+    name = AGENT_PI;
+    /** Phase term-P4.3：保留 Pi API 名 system_prompt/context_message——
+     *  这是 AgentAdapter 映射边界声明（Pi 支持哪些 Agent Runtime 层注入位置）。
+     *  Blueprint 用 session/turn 语义值（聚合组 inject 字段），Adapter 内部映射到此字段声明的 Pi API 名。 */
+    supportedTargets = ["system_prompt", "context_message"];
+    ctx = null;
+    blueprint = null;
+    domains = [];
+    segment = null;
+    /** 与当前 Pi runtime 的 AgentAPI 绑定；同一 runtime 不重复注册 handler。
+     *  v12.x：per-pi 实例字段——`registry.ts` 给每个 pi 一个新 PiAdapter，所以 `injectedApi`
+     *  不会被其他 session 覆盖。 */
+    injectedApi = null;
+    /** v13.x（issue pt-turn-inject-not-profile-scoped）：当前 Profile——turn 路径 scope 过滤用。 */
+    profile = null;
+    /** 设置编译产物（transpile 后调）。v12.x：per-pi 实例字段——本 session 的 segment
+     *  不会被其他 session 覆盖。
+     *  v13.x（issue pt-turn-inject-not-profile-scoped）：加 profile 参数——turn 路径 scope 过滤用。 */
+    setAgentContext(ctx, blueprint, domains, profile) {
+        this.ctx = ctx;
+        this.blueprint = blueprint;
+        this.domains = domains;
+        this.profile = profile;
+        this.segment = renderSessionInject(ctx, blueprint);
+    }
+    /** 清除当前 session 的 context；保留当前 runtime 的 handler 绑定。
+     *  v12.x：per-pi 实例字段——只清本 session 的状态。 */
+    resetInjection() {
+        this.ctx = null;
+        this.blueprint = null;
+        this.domains = [];
+        this.profile = null;
+        this.segment = null;
+    }
+    /** 启动时注册：把 AgentContext 注入到 Agent。 */
+    registerInject(api, ctx, blueprint, domains = this.domains, profile = this.profile) {
+        // 先更新状态；同一 runtime 的后续 Profile 切换不能重新注册 handler，
+        // 但 handler 会在事件发生时读取最新的 this.segment / this.ctx。
+        this.ctx = ctx;
+        this.blueprint = blueprint;
+        this.domains = domains;
+        this.profile = profile;
+        this.segment = renderSessionInject(ctx, blueprint);
+        if (this.injectedApi === api) {
+            api.log?.debug("agent:registerInject skipped (already injected)");
+            return;
+        }
+        this.injectedApi = api;
+        // session 注入（inject=session → Pi system_prompt 事件）：每轮追加 segment
+        // v10.x：包 try/catch，运行时异常走 api.log.error + ui.notify，不再 swallow
+        // v11.x（issue pt-injection-status-manual-track）：三分支写 session.injectionState +
+        //   调 api.ui?.setStatus，让 footer 三态文字真实反映注入结果（自报，不检测 Pi）
+        // v12.x：从 args[1] ctx 拿 per-session sessionId，写 per-session SessionState
+        api.on("before_agent_start", async (...args) => {
+            const t0 = Date.now();
+            try {
+                const sessionId = sessionIdFromArgs(args);
+                const sessionState = sessionId ? getSessionById(sessionId) : null;
+                const currentSegment = this.segment;
+                // v14.x（issue pt-asset-migration-visibility Layer 2）：footer 末尾追加 ⚠ N issues。
+                //   从 sessionState.assetHealthIssues 读计数——session_start 已批量体检过。
+                const healthCount = sessionState?.assetHealthIssues?.length ?? 0;
+                // v14.x（tagline）：footer 拼 `: <tagline>`。从 sessionState.cachedProfile 读——transpile 时已存。
+                const tagline = sessionState?.cachedProfile?.tagline ?? null;
+                if (!currentSegment) {
+                    // 无 segment（未加载 Profile / 已被 reset）→ idle
+                    if (sessionState) {
+                        sessionState.injectionState = "idle";
+                        sessionState.injectionError = null;
+                        api.ui?.setStatus("pt", renderInjectionFooter("idle", sessionState.activeProfile, null, healthCount, "auto", tagline));
+                    }
+                    return undefined;
+                }
+                const event = args[0];
+                if (!isSystemPromptEvent(event)) {
+                    // 事件形状异常：归类为 idle（不视为失败——Pi 可能改了事件签名）
+                    if (sessionState) {
+                        sessionState.injectionState = "idle";
+                        sessionState.injectionError = null;
+                        api.ui?.setStatus("pt", renderInjectionFooter("idle", sessionState.activeProfile, null, healthCount, "auto", tagline));
+                    }
+                    return undefined;
+                }
+                const final = `${event.systemPrompt}\n\n## 当前任务上下文\n\n${currentSegment}`;
+                api.log?.debug("agent:before_agent_start ok", {
+                    originalLen: event.systemPrompt.length,
+                    injectedLen: final.length,
+                    deltaLen: final.length - event.systemPrompt.length,
+                    durationMs: Date.now() - t0,
+                });
+                if (sessionState) {
+                    api.onInjected?.(final);
+                    // 成功注入 → injected
+                    sessionState.injectionState = "injected";
+                    sessionState.injectionError = null;
+                    api.ui?.setStatus("pt", renderInjectionFooter("injected", sessionState.activeProfile, null, healthCount, "auto", tagline));
+                }
+                else {
+                    api.onInjected?.(final);
+                }
+                return { systemPrompt: final };
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                api.log?.error("agent:before_agent_start failed", {
+                    err: msg,
+                    durationMs: Date.now() - t0,
+                });
+                api.ui?.notify(`[pt] before_agent_start failed: ${msg}`, "error");
+                // 异常 → failed + 错误消息（footer 追加）
+                const sessionId = sessionIdFromArgs(args);
+                const sessionState = sessionId ? getSessionById(sessionId) : null;
+                // v14.x：catch 路径同样透传 healthCount + tagline（避免修复丢告警 / tagline）
+                const healthCount = sessionState?.assetHealthIssues?.length ?? 0;
+                const tagline = sessionState?.cachedProfile?.tagline ?? null;
+                if (sessionState) {
+                    sessionState.injectionState = "failed";
+                    sessionState.injectionError = msg;
+                    api.ui?.setStatus("pt", renderInjectionFooter("failed", sessionState.activeProfile, msg, healthCount, "auto", tagline));
+                }
+                return undefined; // 失败降级, 不影响主流程
+            }
+        });
+        // context_message 触发：/manual:xxx + /<flow-name>
+        // v10.x：包 try/catch，renderTurnInject 抛错不再 swallow
+        api.on("input", async (...args) => {
+            const t0 = Date.now();
+            try {
+                if (!this.ctx || !this.blueprint)
+                    return { action: "continue" };
+                const event = args[0];
+                if (!isInputEvent(event))
+                    return { action: "continue" };
+                // Phase term-P4.3：renderContextMessage → renderTurnInject
+                // v13.x（issue pt-turn-inject-not-profile-scoped）：按 Profile scope 过滤 domains + 传 profile
+                //   让 /manual:<domain> 在未引用该 domain 的 Profile 下返 null（与 /pt flows 列表一致）
+                const scoped = filterDomainsByProfile(this.domains, this.profile);
+                const result = renderTurnInject(this.ctx, this.blueprint, scoped, this.profile, event.text);
+                const durationMs = Date.now() - t0;
+                if (result === null) {
+                    api.log?.debug("agent:input passthrough", {
+                        inputPreview: event.text.slice(0, 80),
+                        durationMs,
+                    });
+                    return { action: "continue" };
+                }
+                api.log?.info("agent:input transformed", {
+                    inputPreview: event.text.slice(0, 80),
+                    outputLen: result.length,
+                    durationMs,
+                });
+                return { action: "transform", text: result };
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                api.log?.error("agent:input render failed", {
+                    err: msg,
+                    input: args[0],
+                    durationMs: Date.now() - t0,
+                });
+                api.ui?.notify(`[pt] input render failed: ${msg}`, "error");
+                return { action: "continue" }; // 失败降级: 不拦截 input, 让原文本过 LLM
+            }
+        });
+    }
+    /** 查询可用手册（/pt flows 用）。
+     *  v9：遍历 Blueprint 的 inject=turn 聚合组 → 引用 Domain → 找 FlowTemplate + Rules 段的 Rule。 */
+    listManuals(_ctx, blueprint, domains) {
+        const flows = [];
+        for (const group of blueprint.groups) {
+            // Phase term-P4.3：inject 语义值 context_message → turn
+            // Phase term-naming：字段名 target → inject
+            if (group.inject !== "turn")
+                continue;
+            // v13.x（issue pt-turn-inject-not-profile-scoped）：按 Profile scope 过滤 domains——
+            // adapter 内部统一过滤，调用方（commands.ts flowsText）无需预过滤。
+            const scoped = filterDomainsByProfile(domains, this.profile);
+            for (const d of scoped) {
+                // Phase term-P9.2：FlowTemplate 在 ## Flows 段；Rule[] 在 ## Rules 段；Checklist[] 在 ## Checklists 段。
+                const flowsContent = d.modules[MOD_FLOWS];
+                if (isFlowTemplateArray(flowsContent)) {
+                    for (const t of flowsContent) {
+                        flows.push({ name: t.name, hint: t.argumentHint, domain: d.name });
+                    }
+                }
+                const rulesContent = d.modules[MOD_RULES];
+                if (isRuleArray(rulesContent) && rulesContent.length > 0) {
+                    // term-Domain 的 Rule[] 作为 /manual:<domain> 暴露
+                    flows.push({
+                        name: `/manual:${d.name}`,
+                        hint: `${rulesContent.length} 条规范`,
+                        domain: d.name,
+                    });
+                }
+                // Checklist[] 暂不单独暴露——/manual:<domain> 命令会统一处理（renderDomainManual）
+            }
+        }
+        // 去重（按 name）
+        const seen = new Set();
+        return flows.filter((f) => {
+            const key = `${f.domain}/${f.name}`;
+            if (seen.has(key))
+                return false;
+            seen.add(key);
+            return true;
+        });
+    }
+}
+// ==================== Pi ExtensionAPI 事件 type guards ====================
+function isSystemPromptEvent(x) {
+    return (!!x &&
+        typeof x === "object" &&
+        typeof x.systemPrompt === "string");
+}
+function isInputEvent(x) {
+    return !!x && typeof x === "object" && typeof x.text === "string";
+}

package/dist/agent/registry.d.ts

@@ -0,0 +1,4 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { AgentAdapter } from "../schema.js";
+/** 取指定 pi + name 的 AgentAdapter。未找到返 pi 的 per-pi 实例（fallback）。 */
+export declare function getAgentAdapter(pi: ExtensionAPI, name: string): AgentAdapter;