Takumi：为 AI 编程 Agent 注入工程判断力

dev.to · AI#AI编程#开发者工具#工程实践

Editor brief · 编辑速览

Takumi 在 AI 编程工具之上新增「工程决策层」，将优化目标从「Prompt → 代码」升级为「决策 → 推理 → 实现 → 反思 → 能力增长」，帮助开发者获得对系统的深层理解而非表面产出。

文章思维导图

Knowledge map

拖拽缩放

Full translation

完整中文译文

大多数编程 Agent 都追求从 prompt 到可用软件的短路径。这很有用，但最终会让开发者对系统的理解变得脆弱。缺失的抽象层不是又一个模型，也不是又一个聊天窗口——而是工程决策。

Takumi 改变了优化目标：

Prompt → model → code

Decision → developer reasoning → guided implementation → reflection → capability growth

编程 harness 仍然负责文件、工具、模型路由和会话。Takumi 掌控的是开发者判断力周围的这一层。

为什么 Pi 是宿主，而非产品

Pi 暴露了生命周期钩子、TUI 交互、工具调用拦截、会话持久化和 SDK。Takumi 利用这些接缝，而不是维护整个编程 harness 的分支。这使得 Pi 能够跟进模型/提供商/工具的演进，同时让 Takumi 的护城河保持在工程学习层面。

Takumi 用一个保守的目录来检测关键上下文。提到认证的请求会成为安全检查点；提到持久化的请求会成为数据模型检查点。琐碎的实现细节则直接通过。

const checkpoint = detectDecision("Add authentication to the API");

// checkpoint.question:
// "Which security model fits the threat model and user experience?"
// checkpoint.options:
// ["Session-based auth", "JWT tokens", "OAuth/OIDC", ...]

开发者选择一个选项并解释原因。这段推理被存储为 EngineeringDecision，而不是混在对话记忆中。

工程画像是多维的。一个开发者可以具有高架构能力、低测试能力和低并发信心。用一个初学者/中级/高级的单一标签会丢失这些信息。

export interface EngineeringProfile {
  skills: SkillMap;
  confidence: SkillMap;
  testingDiscipline: number;
  architectureMaturity: number;
  recurringMistakes: string[];
  repeatedStrengths: string[];
  commonTradeOffs: string[];
}

辅导同时利用能力和信心。高能力+低信心需要鼓励和一个有边界的挑战；低能力+高信心需要证据、权衡和一个更小的检查点。

对抗架构漂移的治理

每个初始化的项目都会收到两个文件：

ARCHITECTURE.md 定义模块边界和请求流。

VISION_GUARDRAILS.md 定义 Takumi 必须优化的目标以及必须拒绝的内容。

在会话开始时，扩展会读取这两个文件。对于实现请求，开发者陈述提议的边界和愿景一致性；Pi 必须在允许实现工具之前解释其一致性。这将架构意图转化为可执行的开发约束。

持久化和隐私

Takumi 是本地优先的：

.takumi/
├── engineering-profile.json
├── decision-timeline.json
├── telemetry.json
└── latest-debrief.json

JSON 是默认格式，因为它可检查且可移植。当项目需要事务性本地存储时，Node 的内置 SQLite 后端可用。导出和删除是显式的 CLI 操作；本地状态被 Git 忽略。

模式和复盘

Agent settle 之后，模式引擎寻找保守的纵向信号：薄弱的测试纪律、重复的决策类别、反复出现的错误，或者没有可执行证明的架构思考。复盘引擎将这些观察转化为 staff-engineer 风格的反馈：

最强和最弱的时刻；

学到的概念和仍然薄弱的概念；

推荐的下一个练习。

它有意不是一张计分卡。目标是每次一个有用的观察。

Takumi 保持依赖反转的显式性：

export interface AgentAdapter {
  initialize(): Promise<void>;
  startSession(): Promise<Session>;
  injectPrompt(prompt: string): Promise<void>;
  receiveResponse(): Promise<HarnessResponse>;
  // files, commands, pause/resume, and cancellation omitted here
}

export interface CoachingStrategy {
  readonly name: StrategyName;
  applies(context: CoachingContext): boolean;
  createPlan(context: CoachingContext): CoachingPlan;
}

export interface Storage {
  read<T>(key: string): Promise<T | undefined>;
  write<T>(key: string, value: T): Promise<void>;
}

新的 harness 实现一个适配器。新的干预实现一个策略插件。新的持久化系统实现 Storage。Coaching Engine 永不导入 harness。

测试架构

项目使用 Node 的测试运行器进行快速的行为测试和严格的 TypeScript 检查：

npm run typecheck
npm test

测试覆盖适配器生命周期、决策检测、辅导选择、画像更新、治理加载、复盘生成、SQLite 持久化和 CLI 启动器参数。

最有价值的未来工作不是更多自动化，而是更好的证据：结果验证、更丰富的测试/调试信号、原生决策时间线 UI，以及 OpenCode 工具治理。IDE 集成、团队分析、云同步和 MCP 应保持为可选的表面，围绕同一个本地优先核心。

当开发者完成一个任务，能够解释系统为什么工作、做了哪些权衡，以及下一步会怎么做而不需要 agent 接管时，Takumi 就成功了。