mirror of
https://bitbucket.org/siakitem/my-pi.git
synced 2026-10-26 10:45:22 +00:00
云服务部-叶林立andDevin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
2682bd7fa7
- 组合包拥有、可随时重建的配置、日志与缓存统一放在 <agentDir>/my-pi/：permission-system/（policy.jsonc、hard-guards.jsonc、 logs/）、rtk-optimizer/config.json、tool-search/（config.json、 catalog-v1.json）与 system-prompt-cover.md。hashline.json、lsp.json 由外部扩展读取固定路径，是唯一例外。 - 新增 config/bundle-manifest.json 与 scripts/rebuild-bundle-config.mjs： 先校验全部来源与目标，在临时目录构建完整树，再整体删除旧 my-pi/ （符号链接只删链接）并原子替换，不备份。install.sh / update.sh 每次 运行都调用它；扩展自身不再播种或迁移配置。 - update.sh 删除 pi update 失败后的 git clean 恢复逻辑：Pi 1.3.0 会在 下一次 pi update 时依据中断标记自行恢复。同时删除 Tool Search settings.json 快照迁移与封面部署脚本。 - Tool Search 改为读取 my-pi/tool-search/config.json（源为 config/tool-search.json，须与 BUNDLE_TOOL_SEARCH_DEFAULTS 一致）， 不再读写 settings.json 的 toolSearch 段，移除 bundleDefaultsVersion。 - 默认权限策略开启 debugLog。 - 旧位置的残留文件不迁移、不清理；AGENTS.md / README 同步新约束。 Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
60 lines
4.7 KiB
Markdown
60 lines
4.7 KiB
Markdown
# Troubleshooting
|
|
|
|
## Common Issues
|
|
|
|
| Problem | Cause | Solution |
|
|
| ----------------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| Config not applied (everything asks) | File not found or parse error | Verify the global policy at `~/.pi/agent/my-pi/permission-system/policy.jsonc` (respects `PI_CODING_AGENT_DIR`); 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 | Use a registered `mcp` tool for server tools: `{ "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. |
|
|
|
|
## 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": "/…/.pi/agent/my-pi/permission-system/policy.jsonc",
|
|
"globalConfigExists": true,
|
|
"projectConfigPath": "/…/my-project/.pi/extensions/pi-permission-system/policy.jsonc",
|
|
"projectConfigExists": false,
|
|
"agentsDir": "/…/.pi/agent/agents",
|
|
"agentsDirExists": true,
|
|
"projectAgentsDir": "/…/my-project/.pi/agents",
|
|
"projectAgentsDirExists": false,
|
|
"legacyGlobalPolicyDetected": false,
|
|
"legacyProjectPolicyDetected": false,
|
|
"legacyExtensionConfigDetected": 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
|