CodeT：一种 Pi-native 的智能体实践方案

发表于 分类于

项目概述

CodeT 是一个基于 Pi CodingAgent构建的、**文本驱动、插件化、渐进演进**的软件工程智能体。

目标不是"更聪明的 AI"，而是"更可控的工程环境"。

CodeT 不是一个项目，也不是一个单体智能体。它是

  • 一套工程哲学（Text as Truth / Evolve by Practice）
  • 一套 Pi 插件命名与使用约定（codet-*）
  • 一组可独立演进的 Skills + Extensions

核心哲学

一切皆文本（Text as Truth）

  • *规范*： AGENTS.md{.verbatim}, RULES.md{.verbatim},
    TODO.md{.verbatim}, PLAN.md{.verbatim}
  • *代码*：源码本身就是文本
  • *记忆*：不依赖 SQLite / 向量库，只用 Markdown + JSONL
  • *通信*：多实例之间通过文件（而非 RPC / 内存）协作
  • *版本化*：所有"智能体产物"都可 git diff{.verbatim}

插件化（Pi Extension First）

  • 每个能力 = 一个 Pi Extension + Skill
  • 不修改 Pi 内核
  • 有现成开源插件 → 直接用
  • 没有 → 自己写 Skill（Markdown）+ Extension（TypeScript）,
    skill是内核, TypeScript内部直接调用
    pi.sendUserMessage("/skill:pi-init")
  • 插件可独立版本、独立维护

渐进式智能体（Evolve by Practice）

  • 不做"大而全"的智能体
  • 从 /init{.verbatim} 开始
  • 在实际项目中用 → 踩坑 → 提炼规则 → 固化到插件
  • 用 /omfg{.verbatim} 式机制把 Bad Case 变成规则

AI 参与开发（AI-Assisted Construction）

  • CodeT 本身由 Pi 编写
  • 每个新命令、Skill、工具，都由 Pi 生成初稿
  • 人工 review → 修正 → 提交
  • 变更同步写入 =AGENTS.md=，形成闭环

调度边界（非常重要）

CodeT 严格遵守以下边界：

  • Pi 负责：
    • 命令解析
    • Skill / Extension 路由
    • 工具调用决策
    • 上下文管理
    • 多轮对话编排
  • CodeT 负责：
    • 定义命令语义
    • 提供 Skill（提示词）
    • 提供 Extension（工具封装）
    • 维护 AGENTS.md / RULES.md

CodeT 永远不会：

  • 实现命令间调用链
  • 管理会话状态
  • 编排子 Agent
  • 接管 Pi 的调度权

失败边界

CodeT 遵循”显式失败”原则：

  • 任何命令失败时：
    • 不重试
    • 不自动回滚
    • 不隐藏错误
  • 错误信息直接写入：
    • 终端输出
    • 或 STATUS.md
  • 修复策略由人、或后续 Pi 会话决定

核心能力组成

Context Loader（上下文加载）

职责

  • 从 cwd 向上递归查找：
    • AGENTS.md{.verbatim}
    • RULES.md{.verbatim}
    • SYSTEM.md{.verbatim} （可选）
  • 按优先级合并
  • 在会话开始时自动注入系统提示

设计约束

  • 不缓存解析结果（每次启动重新扫描）
  • 不引入数据库
  • 支持全局（ ~/.pi/agent/{.verbatim} ）+ 项目级（ ./{.verbatim} ）

Slash Commands（命令系统）

所有命令均以 /xxx{.verbatim} 形式存在，由 Pi 负责解析与调度，本质是
*Prompt Template + 工具调用*。

以/init为例

命令 作用 形式

/init{.verbatim} 初始化陌生项目，生成 AGENTS.md Skill（MD） + Extension（TS）

/init{.verbatim} 已落地为
Skill（=skills/pi-init/SKILL.md=，见=codet-pi-init= 包），由模型用
bash/read/write 工具扫描项目并写 AGENTS.md{.verbatim} ——完全
Pi-native，逻辑活在文本资产里。另外保留一个**薄 Extension
桥接**，让在 Pi 中可用 /init{.verbatim} 入口（内部
pi.sendUserMessage("/skill:pi-init ...")=），因为 Pi 的 Skill 命令固定为 =/skill:<name>{.verbatim}
前缀；薄桥接仅为命名友好，不做扫描/生成。离线兜底：=/init –template
[<path>]= 用模板占位符（==
等）确定性生成。模板可自由改文本，不需要改代码。

Skill System（提示词资产）

  • 每个 Skill = 一个目录 + SKILL.md{.verbatim}
  • Skill 可被 Pi 自动发现
  • Skill 内容：
    • 角色设定
    • 约束条件
    • 输出契约
    • 探索维度（模型自主决定顺序）

示例目录

1
2
3
skills/
└── pi-init/
    └── SKILL.md

Multi-Instance Collaboration via tmux（多实例协作）

CodeT 不使用”子 Agent”概念，每个 pi{.verbatim}
实例都是平等的、独立的主 Agent。

  • 用 tmux pane 启动多个 pi{.verbatim}
  • 通过共享文件协作：
    • PLAN.md{.verbatim}
    • TODO.md{.verbatim}
    • STATUS.md{.verbatim}
  • 每个实例职责明确（backend / frontend / scripts）

约定优于机制

  • 不写编排引擎
  • 只在 AGENTS.md{.verbatim} 中写明协作约定

技术选型

运行时

  • Pi Coding Agent（宿主）
  • Node.js >= 20（Extension 运行环境）
  • TypeScript（Extension 开发语言）
  • tmux（多实例编排）

文本格式

  • Markdown（规范、计划、待办、规则）
  • Org-mode（本设计文档及后续架构文档）
  • JSONL（会话日志，可选）

版本控制

  • Git（所有文本产物的版本化）
  • 分支策略：feature/* → develop → main

反模式清单（Anti-Patterns）

以下做法*明确禁止*，因为它们破坏"一切皆文本"的初心：

  • 引入 SQLite / 向量数据库存储记忆或规则
  • 用 TS 运行时状态保存会话上下文（应使用文件）
  • 内置子 Agent 线程调度（应使用 tmux + 文件约定）
  • 用 bitmap / 二进制格式做上下文压缩（应生成文本摘要）
  • 用 hashline / 二进制 patch 做编辑校验（应 git diff{.verbatim} +
    lint{.verbatim} ）
  • 把规范藏进数据库而非 AGENTS.md{.verbatim}