admin/my-pi
1
0
Fork 0
mirror of https://bitbucket.org/siakitem/my-pi.git synced 2026-10-26 10:45:22 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
a6d8416c7633b3e4eedcee3e127b7976b3f139bc
my-pi/AGENTS.md
T
云服务部-叶林立andDevin <158243242+devin-ai-integration[bot]@users.noreply.github.com> a6d8416c76 refactor(pi-compaction): 改为压力触发的观察遮蔽与空闲阈值整段摘要 
原实现对所有工具结果（含 read）在下一次请求即替换为约 4K 的首尾存根，
不看上下文压力，导致模型看不到大文件中段；后台逐条语义摘要又反复改写
历史、打碎 prompt 缓存。参照 Anthropic 上下文编辑、Manus 与 JetBrains
观察遮蔽研究重构为：
- L2：上下文达到阈值时在 turn_end 批量提交 Pi 原生 context_edit，把最近
  keepRecentTurns 轮之外的旧 toolResult 换成确定性占位符；trigger/target
  回差与 minClearTokens 保证少触发、一次清够；原始条目保留，可经
  context_tree_query 取回
- L3：空闲 agent_settled 且超过绝对阈值时调用一次 ctx.compact
- 阈值按绝对 token 计并受窗口比例约束，默认针对 1M 窗口（DeepSeek V4.1
  Flash）：遮蔽 200K→100K、整段摘要 400K
- 删除逐条存根、语义 worker、soft/hard/target 比例与自行取消 Pi 压缩的门控；
  Pi 原生阈值压缩保留为最终安全网

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
2026-10-21 19:51:36 -07:00

10 KiB
Raw Blame History

仓库说明

本仓库维护可通过一次 pi install 部署的个人 Pi 扩展组合包。根 package.json 是唯一的组合包安装入口；install.sh / update.sh / uninstall.sh 只是 pi install / pi update / pi remove 的便捷包装，不形成第二套部署机制。仓库 config/ 是组合包唯一配置来源，扩展运行时直接读取已安装组合包内的文件，不复制、不播种、不迁移；仅外部 npm 扩展固定读取 agent 目录路径时（当前 hashline.json、lsp.json）才允许加载时从 config/ 覆盖写入。每个自维护扩展使用独立顶层目录；各扩展的维护约定见各自目录的 AGENTS.md（extensions/ 下 wrapper 见 extensions/AGENTS.md），上游来源记录见各自 UPSTREAM.md（中文维护）。

扩展清单

目录 / 文件 职责
pi-rtk-optimizer/ 默认只压缩非搜索工具输出；RTK 命令改写为可选能力
pi-ssh/ 纯 ssh2 持久远程连接、远端工作区、SFTP 与有界自适应搜索
pi-permission-system/ 工具/路径/MCP/Skill/子代理转发权限基线，内置 AutoReview 与人工 defer 兜底
pi-subagents/ Claude Code 风格隔离子 Agent：后台执行、steering、resume、嵌套与自定义 Agent
pi-web-search/ 统一 web_search / web_fetch，内部路由 Tavily/Exa/Keenable，对模型隐藏厂商
pi-chrome/ 显式授权接入已登录 Chrome Profile，授权后提供 21 个 chrome_* 工具
pi-tool-search/ 校验过的工具目录 + 固定工具 + 有界动态组 LRU，按需加载原始 schema
pi-ask-user/ ask_user_question：模型主动发起的单题/多题/选择/文本提问（TUI + RPC）
pi-worktree/ /wt（/worktree）git worktree 斜杠命令，不注册模型工具
pi-hermes-memory/ Hermes 风格持久记忆：policy-only 注入、六记忆工具、skill_manage
pi-minimal-footer/ 紧凑 footer：上下文仪表、订阅用量条、扩展状态
pi-notify/ Kitty OSC 99 完成与权限确认通知，精确聚焦来源窗口
pi-compaction/ 压力触发的观察遮蔽（Pi context_edit）、阈值整段摘要、effective token、native compaction
extensions/fff-override.ts FFF override 模式接管 find/grep/multi_grep 与 @ 补全
extensions/codegraph.ts 原生 codegraph_explore，自有 stdio JSON-RPC 直连 codegraph serve（codegraph-client.ts）
extensions/context-mode.ts 经 prompt-guard.ts 加载 context-mode adapter 与 skills（context-mode-filter.ts 过滤冲突锚点）
extensions/hashline.ts 部署 config/pi-hashline-edit.json 后加载 pi-hashline-edit 覆盖 read/edit（hashline-config.ts）
extensions/permission-system.ts 直接加载仓库内 pi-permission-system/src/index.ts
extensions/lsp.ts 物化包内 typescript-language-server、部署 LSP 配置并加载 pi-lsp（lsp-config.ts）
extensions/prompt-guard.ts 第三方扩展代理 API：丢弃 systemPrompt 返回、应用 tools.jsonc description 覆盖、context 过滤器
extensions/subagents.ts pi-subagents 加载 wrapper，注入权威 permission-system.ts 为 mandatory extension
extensions/context-view.ts 只读 /context observer，消费 pi-compaction projection metrics
extensions/system-prompt.ts 唯一系统提示词出口（system-prompt-config.ts 为纯 helper），排在最后
configure.sh + scripts/ 交互式写入搜索 key（auth.json）与 SSH 主机导入
install.sh / update.sh / uninstall.sh pi install/update/remove 包装 + 逐项询问的机器级依赖与终端配置

全局硬规则

  • 系统提示词单一所有权：extensions/system-prompt.ts 排在 pi.extensions 最后，是唯一允许在 before_agent_start 返回 systemPrompt 的扩展；其他扩展只能经 systemPromptOptions.sections.<name> 贡献分区，第三方扩展必须经 extensions/ wrapper + prompt-guard.ts 加载，新增工具必须在 config/prompt/tools.jsonc 登记。宿主传入 customPrompt（子 Agent / SYSTEM.md）时不覆盖其开场白；子 Agent 有独立提示词画像 config/prompt/subagent/（preamble + 内置 Agent），判定规则与路由 scope/subagentExclude 细则见 extensions/AGENTS.md。
  • 加载顺序：permission-system → subagents → pi-ssh → pi-chrome → pi-tool-search → system-prompt（最后）；pi-hermes-memory 必须排在 pi-compaction 之前（session_before_compact 取消语义），pi-compaction 在 pi-minimal-footer 与 context-view 之前。
  • 依赖：外部依赖在根 package.json 用精确版本，自维护扩展一律 file: 本地依赖并更新锁文件；Pi 核心包只作 optional host peer，根 runtime deps 不含 Pi runtime，任何目录不得再装一套 Pi runtime；各子包用于测试的 @earendil-works/* devDependencies 一律写 "latest"，经 scripts/update-pi-devdeps.sh 统一刷新；原生构建依赖只按锁定版本进根 allowScripts（当前仅 better-sqlite3@12.11.1；pi-hermes-memory 的 better-sqlite3@13 用包内 N-API 预编译，不新增放行）。不要用仓库级 .pi/settings.json 代替组合包依赖。根 files 对子包按运行时子路径白名单列出（源码、package.json、README/LICENSE/CHANGELOG/UPSTREAM），不得整目录列入，以免打入嵌套 node_modules、dist 和测试；由 tests/package-files.test.ts 守护。
  • 配置：config/ 下全部文件是权威源、必须提交；不得读写 settings.json 自定义段、agent 目录独立配置文件或以环境变量作持久默认值；config/ 只放机器无关值，路径类默认值在代码中运行时计算。<agentDir>/my-pi/ 只放可丢弃运行时状态（日志、缓存），连同旧 extensions/pi-permission-system/ 残留、构建产物与依赖目录都不提交；用户数据（记忆、会话、auth.json 等）不属于组合包配置，也不得放入该目录。
  • 组合包不加载任何 MCP adapter/SDK：Exa 与 CodeGraph 均用自有直连客户端。
  • 导入/同步上游：只从官方 Git 仓库的明确 tag/commit 取源码快照，禁止 npm tarball/缓存/node_modules/dist/ 等预编译产物作导入源；保留上游 LICENSE、作者、测试与来源说明，移除嵌套 .git、.pi 状态、node_modules 与构建产物；同步前先核对本地改动再按明确范围移植，不得整体覆盖。各目录的维护约定见 AGENTS.md，每个自维护目录必须有中文 UPSTREAM.md 记录来源，上游原文文件不翻译不改写。
  • 脚本：install.sh、update.sh、uninstall.sh、configure.sh 与 scripts/lib.sh 保持 POSIX sh 兼容并留在 files 中，行为变化同步 README；安装默认来源 git:git@bitbucket.org:siakitem/my-pi.git，可由 PI_PACKAGE_SOURCE 覆盖（update/uninstall 同规则）；组合包安装失败立即停止，机器级依赖失败继续检查其余项并最终返回非零。
  • 安装/升级纪律：机器级依赖与终端配置逐项询问、默认拒绝；update.sh 只升级已安装项、缺失项跳过，组件升级先比较本地与远端版本、一致不重装，成功升级后把 git 来源的受管 checkout git reset --hard 还原到已发布版本（本地路径来源不 reset、不 git clean）；pi update 失败 fail-fast——Pi 1.3.0 会据 .pi-update-incomplete 标记在下次 update 自愈，不做预清理或人工恢复。pi update 只在有新版本时整体覆盖已安装副本（含 config/），不逐字段迁移本机改动；需长期保留的自定义必须改仓库 config/ 源文件。.zshrc 只改 # >>> my-pi:<id> >>> 受管块并先建时间戳备份，不覆盖用户 ~/.p10k.zsh；卸载不得删除用户记忆数据（.pi/agent/pi-hermes-memory/、projects-memory/、.hippo/）或共享机器级工具。
  • 未经明确要求不执行发布、提交、推送、运行安装/卸载脚本、安装到用户 Pi 目录等外部写操作；凭据不进入命令参数、日志、会话或仓库（auth.json 权限 600、不提交）。
  • 优先在目标扩展目录内完成改动；保留原项目 LICENSE 与版权；不让一个扩展依赖另一个扩展的未公开内部实现。

验证

  • 组合包依赖或加载入口变化：验证根 npm install 幂等、锁文件有效、全部扩展可在隔离临时 Pi agent 目录加载（见 tests/extension-load.test.ts）；权限配置变化用包内固定 schema 校验，并确认运行时 config/ 路径确实位于组合包内。
  • 脚本变化：sh -n 每个脚本 + ShellCheck，并确认可执行权限、files 包含与 README 一致；搜索/SSH 配置测试只用虚拟凭据、隔离 HOME 与 mock transport，不连真实服务器。
  • 真实 pi install/update/remove、Homebrew、远程安装器、Git 克隆、真实 SSH、真实终端配置的端到端验证属外部写操作，未经要求不执行；用隔离 HOME + mock 验证分支行为。
  • 根目录测试：node --test 'tests/*.test.ts'、git diff --check；各扩展目录的验证命令见其 AGENTS.md。未能运行的验证交付时明确说明，不以静态检查代替运行结果。

项目记忆（pi-hermes-memory）

持久记忆由 pi-hermes-memory 提供，默认 policy-only 模式：system prompt 只注入 <memory-policy> 指令，不注入记忆正文。

  • 任务开始时若可能依赖历史上下文，先调用 memory_search；需要历史对话原话时用 session_search。
  • 发现值得持久化的事实、偏好、约定、纠正或失败教训时，主动用 memory_add 保存，不必等用户开口；更新或删除用 memory_replace / memory_remove。
  • 完成需要反复试错、或用户教了具体流程的任务后，用 skill_manage 把可复用流程沉淀为 skill（scope: "global" 跨项目，scope: "project" 本项目）。
  • 记忆与 skill 数据位于 ~/.pi/agent/pi-hermes-memory/ 与 ~/.pi/agent/projects-memory/，属于用户数据，不得提交、自动迁移或删除。
Reference in New Issue View Git Blame Copy Permalink