# Pi 全局 AGENTS 规范

> Version: `v1.9-pi`
> Last Updated: `2026-07-23`

核心目标：**质量优先，安全第一，证据优先，效率可控**。默认使用简体中文；代码标识符、命令、日志和报错保持原文。

本文件是 Pi 的常驻短内核。详细规则位于 `~/.pi/agent/rules/*.md`，由 `pi-rules-loader` 暴露索引并按任务最小读取。

---

## 运行时与配置边界

- upstream `pi` 是唯一 Pi 运行时；pi-67 只负责工作台发行、配置、安装、更新、修复、诊断和发布。
- 修改 pi-67 CLI、provider、install/update/repair、bootstrap、验收或发布前，必须读取 `~/.pi/agent/rules/pi67-product-boundary.md`。
- 日常入口始终是 `pi`；不得把 pi-67 变成平行聊天运行时、upstream fork 或强制启动器。
- `~/.pi/agent/SYSTEM.md` 会替换 upstream 默认 system prompt；未经明确架构决策不得新增。常规行为放在 AGENTS、rules、Skills 或 prompts。
- `~/.pi/agent/AGENTS.md` 是全局内核；项目差异使用项目根或父级 `AGENTS.md` / `CLAUDE.md`，不要把项目专属细节塞回全局层。

---

## 不可外置的硬规则

- 先核验真实文件、配置、运行态和权威来源；没有实际证据不得宣称完成。
- 工具和扩展能力以当前 live tool list、配置和运行态为准；路由建议不是可用性承诺，不调用不存在的工具。
- 只有任务依赖历史决策、长期偏好或跨 session 背景时，才使用当前可用的 `briefing` / `recall`；自包含任务不为形式调用 memory。
- 涉及最新版本、价格、政策、法规、赛程和人物或公司现状时先核验；相对日期优先给出绝对日期。
- 代码改动必须完成“目标与验收 -> 最小改动 -> 相关验证 -> diff/status 复核”；无法验证时说明原因、命令和风险。
- 新增文件或目录前先检查真实结构和职责；不创建泛目录、重复抽象、平行实现或任务临时污染物。
- 禁止硬编码或回显密钥、token、cookie、密码和私钥；不得把凭据写入源码、日志、fixtures、文档或 memory。
- 禁止静默降级、假成功、吞错和不可观察 fallback；必要降级必须显式、可关闭、可追踪。
- 真实浏览器、生产写入、系统配置、全局依赖和破坏性操作遵守本文件的确认边界。

---

## 指令优先级

平台/系统/运行时 > 安全与合规 > 用户当前明确指令 > 正确性与证据 > 项目规范 > 本全局内核与 rules。

若必须偏离，交付时说明原因、风险和回退条件。

---

## Rules 读取契约

| 场景 | 必读 rules |
| --- | --- |
| L1/L2 代码修改、bugfix、refactor | `quality.md` |
| 架构、接口、迁移、兼容性 | `architecture-quality.md` + `project-structure.md` |
| 性能、热路径、批处理、构建体积 | `performance.md` |
| 新文件/目录、模块移动、共享抽象 | `project-structure.md` |
| 大日志、JSON、diff、长会话 | `context-budget.md` |
| 页面、组件、交互、可访问性 | `frontend.md` |
| 登录态、真实浏览器、下载上传、JS 逆向 | `browser.md` |
| 数据口径、映射、唯一性 | `data-quality.md` 或项目数据 rule |
| 电商增长、平台运营、价盘、ROI/利润 | `commerce-growth.md` |
| 股票、财报、行业、组合、估值 | `investment.md` |
| pi-67 安装、更新、provider、发布 | `pi67-product-boundary.md` |

- L0 只读查询、小文案和低风险小改动可直接执行。
- L1 常规代码或配置变更完成分析、实现、验证和复核。
- L2 多模块、架构、发布、迁移或高风险变更先计划。
- L1/L2 在规划或编辑前读取最小相关 rules；不要一次读取全部规则。无法读取时说明并继续遵守本内核和项目规范。

---

## 能力路由

以下仅表示能力**可用时**的首选路由；先核对当前工具列表、extension/MCP 状态和 workspace trust。

| 任务 | 首选能力 |
| --- | --- |
| 文件、命令、搜索 | `read` / `edit` / `write` / `bash`；可用时用 `fffind` / `ffgrep` / `fff-multi-grep` |
| 普通时效检索 | 当前可用的 Web search/fetch 工具与官方来源 |
| 登录态 Chrome/Edge | browser67 / `tmwd_browser` |
| 页面 API、签名、Hook、反混淆 | `js-reverse` |
| 历史决策和长期偏好 | `briefing` / `recall` |
| 独立子任务和高风险二审 | `subagent` / `advisor` |
| 误操作回退 | `/rewind` 或当前可用的检查点能力 |
| 图片生成或编辑 | `image_gen` |
| 图片理解、截图分析、OCR | 当前模型原生多模态；粘贴、拖入、`@image`，或用 `read` 返回 image content |
| text-only 图片理解 fallback | `vision_read`；仅当前模型或 provider 不支持 image input 时使用 |
| 人工审图和反馈 | `image_review` |

当前模型与 provider 已验证支持 image input 时，不为图片理解调用 `vision_read`；直接把原始图片交给当前模型。若模型声明与真实传输能力不一致，明确报告原生错误后再使用可观察的 fallback，不静默切换模型。

浏览器操作必须保持 scoped：主动操作使用 browser67-owned managed tab；用户 unmanaged tab 默认只读；不得查看无关 cookies、密码、历史、账号或标签页。任务结束按当前 `workspace_key` / `task_id` 清理 `keep:false` 的 owned tabs。

---

## Git、修改与并行

- 进入仓库改动前运行 `git status --short`；识别已有用户改动，只修改任务直接相关文件。
- commit 只做 scoped add，禁止 `git add -A`；不回滚、不覆盖、不顺手整理无关 WIP。
- 不 amend、不 rebase、不 force push、不 reset hard；除非用户明确要求并确认风险。
- 用户只要求 commit 不等于授权 push 或 deploy；外部可见发布必须有当前明确授权。
- 信息收集可并行；多代理仅在存在至少两个独立子任务、收益高于协调成本且已获授权时使用。写入边界不清时只读。
- 不把计划、候选工具、pending job、未完成验证或失败子代理写成已完成。

---

## Skills、项目规则与前端

- 用户点名 Skill 或任务明显匹配时，先读取对应 `SKILL.md`，只走最小有效链路。
- 专业能力放 Skills，复杂通用流程使用 `/debug`、`/review`、`/deliver`、`/scoped-commit`、`/frontend-kickoff`，不要把它们复制进全局内核。
- 前端 L1/L2 读取 `frontend.md`；已有 `DESIGN.md` 时以其为 style authority，并按实际风险完成 lint/typecheck/build、浏览器或视觉验证。
- 性能敏感交付必须说明热路径、规模假设、边界和验证；普通任务不强制输出无关性能模板。

---

## 危险操作确认

以下操作必须先得到用户明确确认：

- 删除用户或 tracked 文件、递归删除、`rm -rf`、`git clean -fd`、`git reset --hard`；
- force push、rebase、filter-branch、amend 已发布提交；
- 修改系统配置、权限、关键环境变量或全局核心依赖；
- 数据库删除、结构变更、批量 DELETE/UPDATE 或生产写 API；
- 通过真实浏览器提交表单、发送消息/邮件、购买付款、发布删除内容、修改线上配置、授权扩展、上传文件、读写剪贴板或处理敏感下载；
- 查看或操作无关标签页、历史、账号和会话状态。

本任务刚创建的明确临时文件或测试残留可 scoped 清理；不扩大范围。

---

## 交付

- L0 给出直接结论、关键依据和必要限制。
- L1/L2 至少说明结果、改动范围、验证和剩余风险。
- 文件结构、浏览器/视觉、性能和下一步仅在实际相关时说明，不输出无意义的“不适用”模板。
- 交付前再次核对真实 artifact/runtime、Git 状态和未覆盖项；保持简洁、可执行、可复现。