pi-extending

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Pi — Extending & Embedding

Pi — 扩展与嵌入

Four ways to build on top of Pi:

Concern	Section
Authoring TypeScript extensions (tools, commands, hooks, providers)	Extension authoring
Distributing extensions/skills via npm or git	Package authoring
Embedding pi or speaking the JSON-RPC protocol	RPC + SDK
Working inside the pi_agent_rust repo	pi_agent_rust internals

基于Pi进行构建的四种方式：

关注点	章节
编写TypeScript扩展（工具、命令、钩子、提供者）	扩展编写
通过npm或git分发扩展/技能	包编写
嵌入Pi或使用JSON-RPC协议	RPC + SDK
在pi_agent_rust仓库内开发	pi_agent_rust 内部实现

Extension Authoring

扩展编写

Pi extension authoring

Pi扩展编写

Ground every answer in

pi-mono/

files below.

所有回答均基于以下

pi-mono/

文件。

Grounding

参考依据

pi-mono/packages/coding-agent/docs/extensions.md

— capabilities, lifecycle, patterns.

pi-mono/packages/coding-agent/examples/extensions/README.md

— runnable examples index.

```
pi-mono/packages/coding-agent/src/core/resource-loader.ts
```
—
```
extendResources()
```
appends paths via
```
mergePaths
```
after existing
```
lastSkillPaths
```
(late paths lose name collisions to earlier ones unless names differ).
```
pi-mono/packages/coding-agent/src/core/agent-session.ts
```
— extension commands vs queued prompts; skill expansion hooks.
```
pi-mono/packages/coding-agent/docs/tui.md
```
— extension TUI component integration with
```
@mariozechner/pi-tui
```
:
```
Component
```
rendering contract, overlay patterns, input handling in extension context.

pi-mono/packages/coding-agent/docs/custom-provider.md

—

registerProvider()

for proxies, OAuth/SSO, custom APIs, and custom model definitions.

pi-mono/packages/coding-agent/docs/extensions.md

— 功能、生命周期、模式。

pi-mono/packages/coding-agent/examples/extensions/README.md

— 可运行示例索引。

```
pi-mono/packages/coding-agent/src/core/resource-loader.ts
```
—
```
extendResources()
```
通过
```
mergePaths
```
在现有
```
lastSkillPaths
```
后追加路径（路径名称冲突时，晚加载的路径会被早加载的覆盖，除非名称不同）。

pi-mono/packages/coding-agent/src/core/agent-session.ts

— 扩展命令与排队提示；技能扩展钩子。

```
pi-mono/packages/coding-agent/docs/tui.md
```
— 扩展TUI组件与
```
@mariozechner/pi-tui
```
的集成：
```
Component
```
渲染约定、覆盖层模式、扩展上下文内的输入处理。
```
pi-mono/packages/coding-agent/docs/custom-provider.md
```
— 使用
```
registerProvider()
```
实现代理、OAuth/SSO、自定义API和自定义模型定义。

Invariants

固定规则

Extensions can register tools, commands, themes, prompts, and extra skill paths; exact API surface is defined in docs and example modules — start from
```
docs/extensions.md
```
, not memory.
Dynamic resource discovery patterns live under
```
pi-mono/packages/coding-agent/examples/extensions/
```
(e.g.
```
dynamic-resources/
```
listing in examples README).

扩展可注册工具、命令、主题、提示和额外技能路径；具体API范围由文档和示例模块定义——从
```
docs/extensions.md
```
开始，而非凭记忆。
动态资源发现模式位于
```
pi-mono/packages/coding-agent/examples/extensions/
```
下（例如示例README中的
```
dynamic-resources/
```
列表）。

Workflows

工作流程

New extension: Read
```
docs/extensions.md
```
, clone the closest
```
examples/extensions/
```
template, then align with project
```
AGENTS.md
```
if working inside
```
pi-mono
```
.
Skills from extensions: Trace
```
extendResources
```
+
```
mergePaths
```
in
```
resource-loader.ts
```
to explain ordering with user/project/package skills.
Extension TUI: Read
```
docs/tui.md
```
for the
```
Component
```
rendering contract in extension context; combine with
```
pi-tui
```
skill for library-level APIs.

Custom providers via extension: See

pi-mono/packages/coding-agent/docs/custom-provider.md

for

registerProvider()

OAuth flows and proxy patterns (grounded in

pi-cli-workspace

新建扩展：阅读
```
docs/extensions.md
```
，克隆最接近的
```
examples/extensions/
```
模板，若在
```
pi-mono
```
内开发则需与项目
```
AGENTS.md
```
保持一致。
扩展中的技能：追踪
```
resource-loader.ts
```
中的
```
extendResources
```
+
```
mergePaths
```
，解释与用户/项目/包技能的加载顺序。
扩展TUI：阅读
```
docs/tui.md
```
了解扩展上下文内的
```
Component
```
渲染约定；结合
```
pi-tui
```
技能使用库级API。
通过扩展实现自定义提供者：查看
```
pi-mono/packages/coding-agent/docs/custom-provider.md
```
了解
```
registerProvider()
```
的OAuth流程和代理模式（基于
```
pi-cli-workspace
```
）。

Anti-patterns

反模式

Do not assert MCP support in core; optional via extension (see coding-agent README philosophy).

不要断言核心支持MCP；需通过扩展提供可选支持（参见coding-agent README中的设计理念）。

Package Authoring

包编写

Pi package authoring

Pi包编写

Grounding

参考依据

pi-mono/packages/coding-agent/docs/packages.md

— manifest, install commands, layout.

pi-mono/packages/coding-agent/README.md

— Pi Packages section (

pi install

package.json

pi

key, keywords).

pi-mono/packages/coding-agent/src/core/package-manager.ts

—

resourcePrecedenceRank

(package-origin resources sort after user/project).

pi-mono/packages/coding-agent/docs/packages.md

— 清单、安装命令、布局。

pi-mono/packages/coding-agent/README.md

— Pi包章节（

pi install

、

package.json

中的

pi

字段、关键词）。

pi-mono/packages/coding-agent/src/core/package-manager.ts

—

resourcePrecedenceRank

（包来源的资源排序在用户/项目资源之后）。

Invariants

固定规则

Packages integrate through the same resource resolution pipeline as local dirs; package-origin metadata ranks after user/project auto paths — see
```
resourcePrecedenceRank
```
in
```
pi-mono/packages/coding-agent/src/core/package-manager.ts
```
.
Third-party packages execute code; skills can instruct arbitrary actions — security notes are first-party in
```
docs/packages.md
```
and coding-agent README.

包通过与本地目录相同的资源解析管道集成；包来源元数据的优先级低于用户/项目自动路径——参见
```
pi-mono/packages/coding-agent/src/core/package-manager.ts
```
中的
```
resourcePrecedenceRank
```
。
第三方包会执行代码；技能可指示任意操作——安全说明在
```
docs/packages.md
```
和coding-agent README中由官方提供。

Workflows

工作流程

Define a package: Mirror the
```
package.json
```
example from
```
docs/packages.md
```
/ README; verify conventional dirs (
```
skills/
```
,
```
extensions/
```
, etc.) against those docs.
Predict overrides: Combine package-manager precedence with
```
loadSkills
```
“first name wins” (
```
pi-mono/packages/coding-agent/src/core/skills.ts
```
).

定义包：参照
```
docs/packages.md
```
/ README中的
```
package.json
```
示例；对照文档验证常规目录（
```
skills/
```
、
```
extensions/
```
等）。
预测覆盖规则：结合包管理器优先级与
```
loadSkills
```
的“同名优先”规则（
```
pi-mono/packages/coding-agent/src/core/skills.ts
```
）。

Anti-patterns

反模式

Do not invent CLI flags not documented in
```
docs/packages.md
```
/ README.

不要发明
```
docs/packages.md
```
/ README中未记录的CLI标志。

RPC + SDK

Pi RPC and SDK integration

Pi RPC与SDK集成

Grounding

参考依据

```
pi-mono/packages/coding-agent/docs/rpc.md
```
— Framing section (LF-only record delimiter;
```
readline
```
incompatibility with U+2028/U+2029).

pi-mono/packages/coding-agent/docs/sdk.md

— programmatic session patterns plus

createAgentSession

AgentSession

createAgentSessionRuntime

ModelRegistry.create()

AuthStorage.create()

, and

SessionManager.inMemory()

pi-mono/packages/coding-agent/docs/json.md

—

--mode json

event stream: session header,

agent_*

turn_*

message_*

tool_execution_*

events,

jq

filtering examples.

```
pi-mono/packages/coding-agent/src/modes/rpc/rpc-client.ts
```
— reference TypeScript client mentioned from
```
rpc.md
```
intro when applicable.
```
pi-mono/packages/coding-agent/src/core/agent-session.ts
```
— API surface for in-process embedding (per
```
rpc.md
```
note to TypeScript users).

```
pi-mono/packages/coding-agent/docs/rpc.md
```
— 帧格式章节（仅LF作为记录分隔符；
```
readline
```
与U+2028/U+2029不兼容）。

pi-mono/packages/coding-agent/docs/sdk.md

— 程序化会话模式以及

createAgentSession

、

AgentSession

、

createAgentSessionRuntime

、

ModelRegistry.create()

、

AuthStorage.create()

和

SessionManager.inMemory()

。

pi-mono/packages/coding-agent/docs/json.md

—

--mode json

事件流：会话头、

agent_*

turn_*

message_*

tool_execution_*

事件、

jq

过滤示例。

```
pi-mono/packages/coding-agent/src/modes/rpc/rpc-client.ts
```
—
```
rpc.md
```
介绍中提到的参考TypeScript客户端（适用时）。
```
pi-mono/packages/coding-agent/src/core/agent-session.ts
```
— 进程内嵌入的API范围（根据
```
rpc.md
```
给TypeScript用户的说明）。

Invariants

固定规则

Framing rules are normative text in
```
pi-mono/packages/coding-agent/docs/rpc.md
```
; quote or paraphrase strictly from that file when advising client implementers.
Skill commands and prompt templates are expanded for RPC prompts per
```
rpc.md
```
Input expansion bullet under
```
prompt
```
command.
```
--mode json
```
is read-only observation (stdout events);
```
--mode rpc
```
is bidirectional control (stdin commands + stdout responses). Different use cases, same framing caveats for U+2028/U+2029.

For TypeScript/Node embedding,

createAgentSession()

is the primary factory; it requires

sessionManager

authStorage

, and

modelRegistry

. For advanced multi-session hosting, use

createAgentSessionRuntime()

which returns

AgentSessionRuntime

with lower-level access to

agent

sessionManager

settingsManager

modelRegistry

extensions

bashExecutor

resourceLoader

—

pi-mono/packages/coding-agent/docs/sdk.md

帧格式规则是
```
pi-mono/packages/coding-agent/docs/rpc.md
```
中的标准文本；为客户端实现者提供建议时，严格引用或转述该文件内容。
技能命令和提示模板会针对RPC提示进行扩展，参见
```
rpc.md
```
中
```
prompt
```
命令下的输入扩展要点。
```
--mode json
```
是只读观测模式（标准输出事件）；
```
--mode rpc
```
是双向控制模式（标准输入命令 + 标准输出响应）。两者用途不同，但都存在U+2028/U+2029的帧格式限制。

对于TypeScript/Node嵌入，

createAgentSession()

是主要工厂方法；它需要

sessionManager

、

authStorage

和

modelRegistry

。对于高级多会话托管，使用

createAgentSessionRuntime()

，它返回

AgentSessionRuntime

，提供对

agent

、

sessionManager

、

settingsManager

、

modelRegistry

、

extensions

、

bashExecutor

、

resourceLoader

的底层访问——参见

pi-mono/packages/coding-agent/docs/sdk.md

。

Workflows

工作流程

Choose integration: If user is on Node/TS, point to
```
rpc.md
```
recommendation to prefer
```
AgentSession
```
vs subprocess; cite the file’s opening Note for Node.js/TypeScript users.
Debug framing: Re-read Framing section; do not suggest generic line readers as compliant.
JSON event stream: For read-only observation of agent activity, point to
```
json.md
```
(
```
--mode json
```
); for bidirectional control, point to
```
rpc.md
```
(
```
--mode rpc
```
).

In-process embedding: For TypeScript/Node users who don't need subprocess isolation, prefer

createAgentSession()

over

--mode rpc

. Import from

@mariozechner/pi-coding-agent

. See

pi-mono/packages/coding-agent/docs/sdk.md

and

pi-mono/packages/coding-agent/examples/sdk/

选择集成方式：如果用户使用Node/TS，指向
```
rpc.md
```
中优先使用
```
AgentSession
```
而非子进程的建议；引用文件开头的Node.js/TypeScript用户注意事项。
调试帧格式：重新阅读帧格式章节；不要建议使用通用行读取器作为兼容方案。
JSON事件流：如需只读观测Agent活动，指向
```
json.md
```
（
```
--mode json
```
）；如需双向控制，指向
```
rpc.md
```
（
```
--mode rpc
```
）。

进程内嵌入：对于不需要子进程隔离的TypeScript/Node用户，优先使用

createAgentSession()

而非

--mode rpc

。从

@mariozechner/pi-coding-agent

导入。参见

pi-mono/packages/coding-agent/docs/sdk.md

和

pi-mono/packages/coding-agent/examples/sdk/

。

Anti-patterns

反模式

Do not describe delimiter behavior contradicting
```
rpc.md
```
(only
```
\n
```
as record delimiter; optional
```
\r
```
strip on input).

不要描述与
```
rpc.md
```
矛盾的分隔符行为（仅
```
\n
```
作为记录分隔符；输入时可选择性去除
```
\r
```
）。

pi_agent_rust internals

pi_agent_rust 内部实现

Pi Agent Rust

Use This Skill When

适用场景

You are working inside
```
pi_agent_rust
```
and need the fastest path to safe, verified edits.
You are touching provider/tool/session/extension behavior and need targeted triage.
You are changing installer/uninstaller/skill install behavior and need deterministic safety checks.
You need symptom-first debugging playbooks instead of ad-hoc command hunting.

你正在
```
pi_agent_rust
```
内开发，需要最快的安全验证编辑路径。
你正在修改提供者/工具/会话/扩展行为，需要针对性问题排查。
你正在修改安装器/卸载器/技能安装行为，需要确定性安全检查。
你需要基于症状的调试指南，而非临时命令查找。

60-Second Bootstrap

60秒快速启动

bash

export CARGO_TARGET_DIR="/data/tmp/pi_agent_rust/${USER:-agent}"
export TMPDIR="/data/tmp/pi_agent_rust/${USER:-agent}/tmp"
mkdir -p "$TMPDIR"

rch exec -- cargo check --all-targets
rch exec -- cargo clippy --all-targets -- -D warnings
cargo fmt --check
bash tests/installer_regression.sh

bash

export CARGO_TARGET_DIR="/data/tmp/pi_agent_rust/${USER:-agent}"
export TMPDIR="/data/tmp/pi_agent_rust/${USER:-agent}/tmp"
mkdir -p "$TMPDIR"

rch exec -- cargo check --all-targets
rch exec -- cargo clippy --all-targets -- -D warnings
cargo fmt --check
bash tests/installer_regression.sh

Symptom Router

症状排查指引

Symptom	First 3 Commands
Provider stream/tool-call regression	`cargo test provider_streaming -- --nocapture` ; `rg -n "stream
Session replay/index drift	`cargo test session -- --nocapture` ; `rg -n "Session
Extension policy/runtime failure	`cargo test extension -- --nocapture` ; `rg -n "policy
Installer/uninstaller/skill issue	`bash tests/installer_regression.sh` ; `rg -n "AGENT_SKILL_STATUS
Interactive vs RPC divergence	`cargo test e2e_rpc -- --nocapture` ; `rg -n "interactive

For deeper diagnosis, use

references/DEBUGGING-PLAYBOOKS.md

症状	前3个排查命令
提供者流/工具调用回归	`cargo test provider_streaming -- --nocapture` ; `rg -n "stream
会话重放/索引漂移	`cargo test session -- --nocapture` ; `rg -n "Session
扩展策略/运行时失败	`cargo test extension -- --nocapture` ; `rg -n "policy
安装器/卸载器/技能问题	`bash tests/installer_regression.sh` ; `rg -n "AGENT_SKILL_STATUS
交互式与RPC模式差异	`cargo test e2e_rpc -- --nocapture` ; `rg -n "interactive

如需深入诊断，使用

references/DEBUGGING-PLAYBOOKS.md

。

Non-Negotiables

不可协商规则

Read
```
AGENTS.md
```
first, then follow it exactly.
Do not delete files or run destructive git/filesystem commands.
Keep edits in-place; avoid creating variant files for the same purpose.
Use
```
main
```
semantics in docs/scripts; do not introduce
```
master
```
.
Prefer
```
rg
```
for fast text recon and
```
ast-grep
```
for structural matching/refactors.
Prefer
```
rch exec -- <cargo ...>
```
for heavy compile/test workloads.
After substantive edits, run compile/lint/format gates and the smallest relevant regression slice.

先阅读
```
AGENTS.md
```
，然后严格遵循其要求。
不要删除文件或运行破坏性git/文件系统命令。
保持编辑在原文件内；避免为同一目的创建变体文件。
在文档/脚本中使用
```
main
```
语义；不要引入
```
master
```
。
优先使用
```
rg
```
进行快速文本检索，使用
```
ast-grep
```
进行结构匹配/重构。
对于繁重的编译/测试工作负载，优先使用
```
rch exec -- <cargo ...>
```
。
完成实质性编辑后，运行编译/ lint/格式检查，以及最小相关回归测试。

Core Workflow

核心工作流程

Recon: identify exact change surface and invariants.
Implement: minimal, behavior-focused patch with explicit failure semantics.
Validate: targeted tests first, broaden only as needed.
Verify UX: error/status output is explicit, stable, and non-ambiguous.
Sync docs: update
```
README.md
```
when flags/behavior/user guidance changed.

调研：确定确切的修改范围和固定规则。
实现：最小化、聚焦行为的补丁，明确失败语义。
验证：先进行针对性测试，仅在需要时扩大范围。
验证UX：错误/状态输出明确、稳定且无歧义。
同步文档：当标志/行为/用户指引变更时，更新
```
README.md
```
。

Changed Files -> Required Tests

修改文件 -> 必选测试

Changed Files (examples)	Minimum Required Tests
`install.sh` , `uninstall.sh` , `.claude/skills/pi-agent-rust/**`	`bash -n install.sh uninstall.sh tests/installer_regression.sh` ; `shellcheck -x install.sh uninstall.sh tests/installer_regression.sh` ; `bash tests/installer_regression.sh` ; `bash scripts/skill-smoke.sh`
`src/providers/**` , `src/provider.rs` , `src/sse.rs`	`cargo test provider_streaming` ; `cargo test conformance`
`src/session.rs` , `src/session_index.rs` , `src/session_test.rs`	`cargo test session` ; `cargo test conformance`
`src/extensions.rs` , `src/extensions_js.rs`	`cargo test extension` ; `cargo test conformance`
`src/tools.rs`	`cargo test tools` ; `cargo test conformance`
`src/interactive.rs` , `src/rpc.rs` , `src/main.rs`	`cargo test e2e_rpc` ; `cargo test conformance`

修改文件示例	最低必选测试
`install.sh` , `uninstall.sh` , `.claude/skills/pi-agent-rust/**`	`bash -n install.sh uninstall.sh tests/installer_regression.sh` ; `shellcheck -x install.sh uninstall.sh tests/installer_regression.sh` ; `bash tests/installer_regression.sh` ; `bash scripts/skill-smoke.sh`
`src/providers/**` , `src/provider.rs` , `src/sse.rs`	`cargo test provider_streaming` ; `cargo test conformance`
`src/session.rs` , `src/session_index.rs` , `src/session_test.rs`	`cargo test session` ; `cargo test conformance`
`src/extensions.rs` , `src/extensions_js.rs`	`cargo test extension` ; `cargo test conformance`
`src/tools.rs`	`cargo test tools` ; `cargo test conformance`
`src/interactive.rs` , `src/rpc.rs` , `src/main.rs`	`cargo test e2e_rpc` ; `cargo test conformance`

Do Not Run Yet

暂不运行

Run these only after targeted repro + focused slice indicates need:

Broad
```
cargo test
```
across entire workspace when a narrower slice already reproduces.
Heavy multi-surface runs before confirming changed-file impact.
Repeated full conformance loops while the core failing slice is still unstable.

仅在针对性复现 + 聚焦测试表明需要时，才运行以下命令：

当较窄范围的测试已能复现问题时，在整个工作区运行宽泛的
```
cargo test
```
。
在确认修改文件的影响前，运行大量多范围测试。
在核心失败测试仍不稳定时，重复执行完整的一致性测试循环。

High-Value Commands

高价值命令

bash

undefined

bash

undefined

Fast recon

快速调研

Installer + skill safety gates

安装器 + 技能安全检查

bash -n install.sh uninstall.sh tests/installer_regression.sh shellcheck -x install.sh uninstall.sh tests/installer_regression.sh bash tests/installer_regression.sh bash scripts/skill-smoke.sh

Rust gates

Rust检查

rch exec -- cargo check --all-targets rch exec -- cargo clippy --all-targets -- -D warnings cargo fmt --check


For an expanded command cookbook, see `references/COMMANDS.md`.
For deep incident triage, see `references/DEBUGGING-PLAYBOOKS.md`.

rch exec -- cargo check --all-targets rch exec -- cargo clippy --all-targets -- -D warnings cargo fmt --check


如需扩展命令手册，参见`references/COMMANDS.md`。
如需深度事件排查，参见`references/DEBUGGING-PLAYBOOKS.md`。

Critical Files

关键文件

```
src/main.rs
```
: CLI entry and mode dispatch.
```
src/agent.rs
```
: agent loop and tool iteration behavior.
```
src/provider.rs
```
: provider trait contract.
```
src/providers/
```
: provider implementations and factory wiring.
```
src/tools.rs
```
: built-in tools (
```
read
```
,
```
write
```
,
```
edit
```
,
```
bash
```
,
```
grep
```
,
```
find
```
,
```
ls
```
).
```
src/session.rs
```
: JSONL session persistence.
```
src/session_index.rs
```
: session index and metadata cache.
```
src/extensions.rs
```
+
```
src/extensions_js.rs
```
: extension policy and QuickJS bridge.
```
src/interactive.rs
```
+
```
src/rpc.rs
```
: TUI and RPC/stdin surfaces.
```
install.sh
```
+
```
uninstall.sh
```
: install lifecycle, migration, and skill management.
```
tests/installer_regression.sh
```
: installer regression harness.
```
scripts/skill-smoke.sh
```
: skill integrity + inline-sync validation.

```
src/main.rs
```
：CLI入口和模式调度。
```
src/agent.rs
```
：Agent循环和工具迭代行为。
```
src/provider.rs
```
：提供者 trait 约定。
```
src/providers/
```
：提供者实现和工厂 wiring。
```
src/tools.rs
```
：内置工具（
```
read
```
、
```
write
```
、
```
edit
```
、
```
bash
```
、
```
grep
```
、
```
find
```
、
```
ls
```
）。
```
src/session.rs
```
：JSONL会话持久化。
```
src/session_index.rs
```
：会话索引和元数据缓存。
```
src/extensions.rs
```
+
```
src/extensions_js.rs
```
：扩展策略和QuickJS桥接。
```
src/interactive.rs
```
+
```
src/rpc.rs
```
：TUI和RPC/标准输入界面。
```
install.sh
```
+
```
uninstall.sh
```
：安装生命周期、迁移和技能管理。
```
tests/installer_regression.sh
```
：安装器回归测试工具。
```
scripts/skill-smoke.sh
```
：技能完整性 + 内联同步验证。

Known Footguns

已知陷阱

Custom artifact install paths without compatible release context can fall back incorrectly if not explicitly guarded.
Skill status can become misleading on mixed outcomes unless partial/failure branches are explicit.
Uninstall logic must enforce both marker checks and expected destination path shape.
Installer progress/status text should stay on stderr when stdout is used for data plumbing.
Bundled skill and inline fallback can silently drift unless explicitly checked.

自定义制品安装路径如果没有兼容的发布上下文，若未明确保护，可能会错误回退。
除非明确处理部分/失败分支，否则混合结果下的技能状态可能会产生误导。
卸载逻辑必须同时执行标记检查和预期目标路径形状验证。
当标准输出用于数据管道时，安装器进度/状态文本应输出到标准错误。
捆绑技能和内联回退可能会在未明确检查的情况下悄然偏离。

Patch Patterns

补丁模式

Pattern 1: Mixed Outcome Status Clarity

模式1：混合结果状态明确化

bash

undefined

bash

undefined

BEFORE: everything collapsed into "skipped custom"

之前：所有情况合并为"skipped custom"

if [ "$skipped_custom" -ge 1 ]; then AGENT_SKILL_STATUS="skipped (existing custom skill)" fi

AFTER: distinguish custom-skip from write failure

之后：区分自定义跳过与写入失败

if [ "$skipped_custom" -ge 1 ] && [ "$failed_writes" -ge 1 ]; then AGENT_SKILL_STATUS="partial (custom skill kept; other install failed)" elif [ "$skipped_custom" -ge 1 ]; then AGENT_SKILL_STATUS="skipped (existing custom skill)" fi

undefined

undefined

Pattern 2: Safe Skill Replacement

模式2：安全技能替换

bash

undefined

bash

undefined

BEFORE: remove destination before validating copy result

之前：在验证复制结果前删除目标路径

rm -rf "$destination" cp "$source" "$destination/SKILL.md"

AFTER: stage then atomically move into place

之后：先暂存再原子性移动到目标位置

staged="$(mktemp -d ...)" cp "$source" "$staged/SKILL.md" mv "$staged" "$destination"

undefined

staged="$(mktemp -d ...)" cp "$source" "$staged/SKILL.md" mv "$staged" "$destination"

undefined

Failure Triage

故障排查

Installer summary/status mismatch: trace

AGENT_SKILL_STATUS

CHECKSUM_STATUS

, and

COMPLETIONS_STATUS

install.sh

Install/uninstall safety concern: verify marker checks and expected destination guards in both scripts.
Provider/session/extension regressions: use symptom router, then follow
```
references/DEBUGGING-PLAYBOOKS.md
```
.
Docs drift: ensure
```
README.md
```
flags/examples match current installer behavior.

安装器摘要/状态不匹配：追踪

install.sh

中的

AGENT_SKILL_STATUS

、

CHECKSUM_STATUS

和

COMPLETIONS_STATUS

。

安装/卸载安全问题：验证两个脚本中的标记检查和预期目标路径保护。
提供者/会话/扩展回归：使用症状排查指引，然后遵循
```
references/DEBUGGING-PLAYBOOKS.md
```
。
文档偏离：确保
```
README.md
```
中的标志/示例与当前安装器行为一致。

Done Criteria

完成标准

Changed-file matrix minimum tests passed.
Compile/lint/format checks passed for touched surfaces.

Installer/skill changes pass

tests/installer_regression.sh

and

scripts/skill-smoke.sh

Behavior is explicit on failure paths; no silent fallback surprises.
Skill docs and inline fallback remain aligned and current.

修改文件对应的最低测试已通过。
涉及部分的编译/lint/格式检查已通过。

安装器/技能修改通过

tests/installer_regression.sh

和

scripts/skill-smoke.sh

。

失败路径的行为明确；无意外的静默回退。
技能文档和内联回退保持一致且最新。

另请参阅（相关技能 — Pi系列）

If your issue relates to:

using Pi: workspace, sessions, /commands, providers, themes, keybindings — check
```
pi-using
```
if appropriate.

如果你的问题涉及：

使用Pi：工作区、会话、/commands、提供者、主题、按键绑定 — 适当时查看
```
pi-using
```
。