mirror of
https://bitbucket.org/siakitem/my-pi.git
synced 2026-10-26 18:55:22 +00:00
云服务部-叶林立andDevin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
2aa1be0b54
配置统一：权限策略、硬防御、Tool Search、提示词封面以及新迁入的 RTK、pi-compaction、pi-worktree、pi-hermes-memory 配置全部由扩展 直接读取已安装组合包内的 config/，pi install / pi update 即完成部署； 删除 rebuild-bundle-config.mjs 与 bundle-manifest.json，my-pi/ 只保留 日志与缓存。update.sh 成功升级后将默认 git 来源的已安装副本 reset 回发布版本。AGENTS.md 新增「组合包配置原则」。 脚本整合：search_config.sh / ssh_config.sh 合并为 configure.sh search|ssh；install.sh / update.sh 共享函数抽到 scripts/lib.sh，远程 安装器改为先下载到临时文件再执行，下载失败可被检测。 权限：hard-guards 新增 protectedWrites，写入 Pi 凭据/设置、已安装 组合包与扩展目录、pi-ssh 凭据库时一律人工确认（跳过 AutoReview、 yolo 与 Session grant，无 UI 时拒绝）；放行 ls、LSP 查询、ctx 只读、 web_search、Chrome 只读与 git 只读命令，skill_manage 改为 ask。 Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
57 lines
5.0 KiB
Markdown
57 lines
5.0 KiB
Markdown
# Troubleshooting
|
|
|
|
## Common Issues
|
|
|
|
| Problem | Cause | Solution |
|
|
| ----------------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| Config not applied (everything asks) | File not found or parse error | Verify the global policy at `config/pi-permission-policy.jsonc` inside the installed bundle; check JSONC syntax |
|
|
| Per-agent override not applied | Frontmatter parsing issue | Ensure `---` delimiters at file top; keep YAML simple; restart session |
|
|
| Tool blocked as unregistered | Unknown tool name | Server tools arrive as `mcp__<server>__<tool>` under Pi's built-in MCP (check `/mcp`); a unified `mcp` proxy tool uses `{ "tool": "server:tool" }` |
|
|
| `/skill:<name>` blocked | Deny policy or confirmation unavailable | Check merged `skill` policy (global/project/agent layers). `ask` still requires UI or forwarded confirmation. |
|
|
| External file path blocked | `external_directory` is `ask` without UI or `deny` | Allow/ask the permission or keep file tools inside the active working directory. |
|
|
| Spurious external-path prompt for `cd <subdir> && grep … ../path` | Relative path was resolved against cwd instead of the `cd` target | Fixed in current version — paths after a leading `cd <subdir> &&` are resolved against the cd target, matching actual shell behavior. |
|
|
| Permission prompt is too verbose | Generic extension tool input is large | Built-in file tools are summarized automatically; third-party tools are capped to a bounded one-line JSON preview. |
|
|
| A file write keeps prompting despite a session grant or yolo | The target is in `protectedWrites` | Working as designed — protected writes are human-only and never take a session grant. Remove the entry from `protectedWrites` in `config/pi-permission-hard-guards.jsonc` to lift it. |
|
|
| A file write is denied without any prompt | `protectedWrites` target, no confirmation UI (headless or subagent relay) | Working as designed — a human-only ask cannot be answered without a local UI. Run the write from an interactive session instead. |
|
|
|
|
## Diagnostic Logging
|
|
|
|
Enable `"debugLog": true` in your config to write verbose diagnostics to `logs/pi-permission-system-debug.jsonl`.
|
|
|
|
On every session start, the extension emits a `config.resolved` entry to both logs listing the resolved config paths and whether each exists.
|
|
This makes it easy to verify which files the extension actually loaded:
|
|
|
|
```jsonc
|
|
{
|
|
"event": "config.resolved",
|
|
"globalConfigPath": "/…/bundle/config/pi-permission-policy.jsonc",
|
|
"globalConfigExists": true,
|
|
"agentsDir": "/…/.pi/agent/agents",
|
|
"agentsDirExists": true,
|
|
"projectAgentsDir": "/…/my-project/.pi/agents",
|
|
"projectAgentsDirExists": false
|
|
}
|
|
```
|
|
|
|
## Threat Model
|
|
|
|
**Goal:** Enforce policy at the host level, not the model level.
|
|
|
|
**What this stops:**
|
|
|
|
- Agent calling tools it shouldn't use (e.g., `write`, dangerous `bash`)
|
|
- Tool switching attempts (calling non-existent tool names)
|
|
- Accidental escalation via skill loading
|
|
- Unapproved path-bearing tool access outside the active working directory when `external_directory` is `ask` or `deny`
|
|
|
|
**Limitations:**
|
|
|
|
- If a dangerous action is possible via an allowed tool, policy must explicitly restrict it
|
|
- This is a permission decision layer, not a sandbox — for true isolation see [Agent Sandboxes](https://engine.build/lab/agent-sandboxes)
|
|
- The review log records bash command strings unredacted.
|
|
Log files are created owner-only (`0600`), and values bound to a sensitive key name (`authorization`, `token`, `password`, …) are masked — but a secret embedded in a command string is not.
|
|
Review-log values are shortened at `reviewLogFieldMaxWidth` (1000 characters by default), which bounds the file's growth but is a length cap, not redaction.
|
|
See [Log file sensitivity](configuration.md#log-file-sensitivity) and [ADR 0010].
|
|
|
|
[ADR 0010]: https://github.com/gotgenes/pi-packages/blob/main/packages/pi-permission-system/docs/decisions/0010-permission-log-secret-exposure.md
|