pi-agent-rust

Pi Agent Rust

60 秒快速启动

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

症状路由

症状	首选的 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。

不容妥协的要求

• 首先阅读 AGENTS.md，然后严格遵循其中的要求。
• 不要删除文件，也不要运行具有破坏性的 git／文件系统命令。
• 在原处进行编辑；避免为同一用途创建变体文件。
• 在文档／脚本中采用 main 语义；不要引入 master。
• 快速检索文本时优先使用 rg，进行结构匹配／重构时优先使用 ast-grep。
• 对于繁重的编译／测试任务，优先使用 rch exec -- <cargo ...>。
• 进行实质性编辑后，运行编译／lint／格式检查，并执行范围最小的相关回归测试。

核心工作流

• 勘察：确定确切的修改范围和不变量。
• 实现：采用以行为为重点的最小补丁，明确失败语义。
• 验证：先运行定向测试，必要时再扩大范围。
• 验证用户体验：错误／状态输出应明确、稳定且无歧义。
• 同步文档：当标志／行为／用户指南发生变化时，更新 README.md。

已更改文件 -> 必需测试

已更改文件（示例）	最低限度的必需测试
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

暂勿运行

只有在定向复现和聚焦测试表明有此必要后，才运行以下测试：

• 如果较窄的测试范围已能复现问题，就不要在整个工作区运行大范围的 cargo test。
• 在确认已更改文件的影响之前，不要运行涉及多个模块的重型测试。
• 在核心失败测试范围仍不稳定时，不要反复运行完整的一致性测试。

高价值命令

# Fast recon
git status --short
rg -n "install|uninstall|skill|checksum|sigstore|completion|provider|session|extension" \
  install.sh uninstall.sh README.md tests/installer_regression.sh src/

# 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
rch exec -- cargo check --all-targets
rch exec -- cargo clippy --all-targets -- -D warnings
cargo fmt --check

如需更详尽的命令手册，请参阅 references/COMMANDS.md。 如需深入进行事件分诊，请参阅 references/DEBUGGING-PLAYBOOKS.md。

关键文件

• src/main.rs：CLI 入口和模式分发。
• src/agent.rs：Agent 循环和工具迭代行为。
• src/provider.rs：提供程序 trait 契约。
• src/providers/：提供程序实现和工厂接线。
• 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/stdin 接口。
• install.sh + uninstall.sh：安装生命周期、迁移和技能管理。
• tests/installer_regression.sh：安装程序回归测试套件。
• scripts/skill-smoke.sh：技能完整性和内联同步验证。

已知陷阱

• 如果未明确防护，在缺少兼容发布上下文时，自定义构件安装路径可能会错误地回退。
• 如果未明确处理部分成功和失败分支，混合结果可能导致技能状态具有误导性。
• 卸载逻辑必须同时验证标记和预期目标路径的格式。
• 当 stdout 用于数据传输时，安装程序的进度/状态文本应输出到 stderr。
• 如果未明确检查，捆绑技能和内联回退可能会悄然产生偏差。

补丁模式

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

# BEFORE: everything collapsed into "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

模式 2：安全替换技能

# 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"

故障排查

• 安装程序摘要/状态不匹配： 在 install.sh 中追踪 AGENT_SKILL_STATUS、CHECKSUM_STATUS 和 COMPLETIONS_STATUS。
• 安装/卸载安全问题： 验证两个脚本中的标记检查和预期目标路径防护。
• 提供程序/会话/扩展回归： 使用症状路由器，然后参考 references/DEBUGGING-PLAYBOOKS.md。
• 文档偏差： 确保 README.md 中的标记/示例与当前安装程序行为一致。

完成标准

• 已通过变更文件矩阵规定的最低测试要求。
• 已通过所涉及部分的编译/静态检查/格式检查。
• 安装程序/技能变更已通过 tests/installer_regression.sh 和 scripts/skill-smoke.sh。
• 失败路径上的行为明确；不会出现意外的静默回退。
• 技能文档和内联回退保持一致且为最新状态。