Potato AI

面向代码 Agent 的可移植项目记忆与 Agent Skills 系统。

English | 简体中文

Potato AI 在项目中安装一套由 Codex、Claude Code、Cursor、Hermes 和 OpenClaw 共享的 .ai 记忆协议。Agent 入口只是钥匙；稳定事实、当前状态、 设计决策和交接信息统一存放在 .ai/。

快速开始

需要 Node.js 20 或更高版本。不需要全局安装、Python、Shell 安装器或 postinstall。

npx @potato-forge/pai init
# 或
pnpm dlx @potato-forge/pai init

指定目录或 Agent：

npx @potato-forge/pai init ./my-project
npx @potato-forge/pai init . --agents codex claude cursor hermes openclaw

如果目标已经是 Potato AI 0.1/0.2，init 会自动升级；也可以显式执行：

npx @potato-forge/pai upgrade .

只安装 Skill

根目录采用标准 Agent Skills 布局，可以不安装完整 .ai 系统而单独安装：

npx skills add https://cnb.cool/potatoforge/potato-ai.git --skill pai-init
npx skills add https://cnb.cool/potatoforge/potato-ai.git --skill pai-sitrap

CLI

pai init [target]
pai upgrade [target]
pai sync [agents...]
pai status [target]
pai doctor [target]
pai changes [target] [--json]
pai checkpoint [target] [--allow-dirty]

初始化会把自包含运行时复制为 scripts/pai.mjs。安装后的 skill 通过 node scripts/pai.mjs 工作，不再依赖 npm 包、网络或 Python。

changes 会同时读取 checkpoint 之后的 commit，以及 staged、unstaged、 untracked 变化，因此用户手写或由其他 IDE/Agent 产生的代码也会进入记忆对齐流程。

安装结构

.ai/
├── vendor/       # 版本化协议与行为规则
├── core/         # 项目拥有的稳定事实与决策
├── state/        # 项目拥有的当前状态与交接
├── logs/         # 脱敏事件记录
├── skills/       # 安装后的 canonical skills
├── commands/     # 可移植指令别名
└── private/      # 本地 checkpoint 与私有笔记（忽略）

scripts/pai.mjs   # 自包含本地 CLI
.agents/skills/   # Codex/Cursor 投影
.claude/skills/   # Claude 投影
.hermes/skills/   # Hermes 投影
skills/           # OpenClaw 投影

升级保证

协议 0.3.0 使用 schema 3。升级保留 .ai/core、.ai/state、.ai/logs 和 .ai/private；被修改的管理文件会先备份到 .ai/archive/migrations/。 旧 scripts/ai-memory.py 会在备份后移除，手写 Agent 入口默认保留，只有 显式 --force 才替换。

旧项目没有有效 checkpoint 时继续要求全量 reconciliation；新协议拒绝被 旧版 CLI 降级。

开发与发布

pnpm install
pnpm check

pnpm check 包含类型检查、skill 校验、测试、生产构建、版本一致性和 tarball 安装烟测。只有 v<semver> CNB tag 会发布 npm；main push 和 PR 只做检查。

首次发布前，在 potatoforge/secrets/main/npm.yml 中只保存 NPM_TOKEN，并授权 本仓库的 tag_push 流水线引用。token 使用具备 @potato-forge 读写权限、明确 过期时间和发布 2FA bypass 的 granular token。不需要 CNB API token。CNB 当前 不属于 npm Trusted Publishing 支持的 CI，因此流水线暂不启用 provenance。

License

MIT