# 🧠 你很需要的教训/经验自提取工具

> 你有没有过这种时刻——上周刚踩过的坑，今天换个项目又踩了一遍？我有。而且不止一次。

所以我做了一个东西，叫 **agent-kb**。

📦 **仓库链接**：`https://cnb.cool/apigogo/agent-kb`

它不是什么高大上的论文数据库，就是一个很朴素的想法：**一事实一文件，跨项目可复用的教训才值得留**。我把每次做项目踩的坑——不管是工具链的、流程的、还是那些根本找不到为什么的静默失败——都写成标准化的 md 文件，按三个分类归档。现在有 **85 条** 了。

## 📊 先来看看我都踩了些什么

```txt
📁 agent-kb/
├── tools/       13 条  ← 环境与工具链经验（装软件、配 PATH、CLI 奇葩行为）
├── workflow/    18 条  ← 流程与协作方法（改代码、验收标准、跨平台链路）
└── pitfalls/    56 条  ← 失败教训与反模式（踩过的坑、静默失败、假阳性）
```

56 条教训反模式，是 tools + workflow 加起来两倍还多。这说明什么？**说明我是真的踩了很多坑** 😅

## 🔥 几个我最"印象深刻"的坑

说几个让你有画面感的——

### 坑 1：CNB NPC 派单连续崩 3 次，根因是 payload 少传了一个变量

这是我这辈子最短的"学习曲线"。

我用 CNB 的云原生 NPC（CodeBuddy）来跑自动派单。派单的 body 长这样：

```json
// ❌ 我第一次写的（崩了）
{
  "event": "api_trigger_npc",
  "branch": "main",
  "title": "...",
  "npc": {"name": "CodeBuddy", "workMode": true},
  "env": {"userPrompt": "完整任务书塞这里..."}   // 只传了任务书
}
```

结果每次都是 **秒崩**（<2 秒 error），runner log 里明确写着：

```txt
npc:go requires "userPrompt" parameter for non-NPC events
```

我：？？env 里明明有 userPrompt 啊？

折腾了 3 次，最后去读仓库的 `.cnb.yml` 才发现——NPC 的 `npc:go` stage 引用的**不只是** `$userPrompt`，还有 `$systemPrompt`。两个变量都从 env 取值，少一个就崩一个：

```yaml
npc:go:
  image: codebuddy/codebuddy
  options:
    systemPrompt: $systemPrompt   # ← 我漏传了这个！
    userPrompt: $userPrompt
```

正解是 env 里**同时传两个**：

```json
// ✅ 第四次才对
{
  "npc": {"name": "CodeBuddy", "workMode": true},
  "env": {
    "systemPrompt": "你是工程化 NPC...（简短人设）",
    "userPrompt": "完整任务书..."
  }
}
```

现在这条经验写在 KB 里了，标题叫 `cnb-npc-dispatch-essentials.md`。下次任何项目要派 CNB NPC 单，直接查这条，省得再踩一遍。

### 坑 2：Git credential.helper 空值让 fetch 永远挂起

`git config --global credential.helper ""` 看起来是"禁用 credential 缓存"对吧？

**错**。Git 的 credential helper 链是**顺序执行所有匹配的 helper**。空字符串那个 helper 被调用后——它不报错、不返回凭据、也不告诉 git"我没有凭据"——git 就**永远等下去**，fetch 直接挂起，没有超时。

更糟的是，我 `gh auth setup-git` 又追加了两条 gh helper，第一条空值先命中，后面的全没机会执行。

教训写在 `pitfalls/credential-helper-empty-value-blocks-git-fetch.md`。

### 坑 3：Windows symlink 让 macOS 测试全挂

做跨平台项目时踩的。macOS 的 `/var` 是 symlink 到 `/private/var`，`/tmp` 到 `/private/tmp`。我的路径比较逻辑里，workspace 被 `realpath` 解析成了 `/private/var/...`，但目标路径保留了调用者的 lexical 拼写 `/var/...`。

结果：**所有 in-workspace 目标都被判定为 out-of-workspace**（因为 `commonpath` 对不上）。Linux 和 Windows runner 因为 temp 路径是 canonical 的所以全绿——我在 Windows 本机跑也绿，CI 上 macOS runner 全红。

根因是混了 lexical spell 和 physical root。修法是两边都走同一个 `_physical()` helper。类似的 symlink / realpath 坑在 KB 的 `pitfalls/` 目录下也有一条。

## 🏗 agent-kb 的设计哲学

三个简单的规则：

| 规则 | 说人话 |
|---|---|
| **一事实一文件** | 每个坑一个 md，标题就是坑名，别写长文散文 |
| **跨项目可复用才进 KB** | 项目专属的记忆留在各项目 memory 里，只有换个项目也用得上的才晋升 |
| **钩子自动扫视** | 每次新会话开始，系统自动读 INDEX.md，命中相关条目就拉全文——不用我手动查 |

条目模板很朴素：

```markdown
---
title: "坑的简短标题"
date: 2026-09-20
tags: [git, credential, windows]
severity: high
---

## 症状
（发生了什么）

## 根因
（为什么会这样）

## 解法
（怎么做才对）

## 教训
（下次遇到类似的记住什么）
```

## ☁️ 云原生构建？有的

agent-kb 本身就是在 CNB 上云原生维护的。每次沉淀新条目、更新 INDEX、跑一遍一致性检查，都是 CNB Build 自动流水线。

有一次我忘了给新增条目加 INDEX 行，Build 直接红了——流水线里有个检查步骤会遍历所有 md 文件，验证 INDEX 里都有对应链接。想蒙混过关？不存在的 😄

## 🤔 想问大家的

最后提两个问题，社区里有没有同学有类似经验：

1. **CNB NPC / CodeBuddy 派单**——有没有同学在自己的项目里也踩过 payload 格式的坑？你们的 `.cnb.yml` 里 `npc:go` 段引用了哪些 env 变量？我看到有的项目还加了 `model`, `temperature`, `max_tokens` 这些，是不是都要传？

2. **跨平台路径问题**——Windows / macOS / Linux 的路径比较、symlink 处理、`normpath` vs `realpath`，我感觉这个坑是"永恒"的。大家有没有什么通用解法？比如统一用 POSIX 路径字符串、或者永远不依赖 `commonpath`？

欢迎交流～

---

🔗 **agent-kb 仓库**：`https://cnb.cool/apigogo/agent-kb`

你有没有过这种时刻——上周刚踩过的坑，今天换个项目又踩了一遍？我有。而且不止一次。

你很需要的教训/经验/知识自提取工具——Agent-kb

agent-kb ：在 CNB 平台云原生维护的 AI Agent 跨平台经验知识库。以「一事实一文件」为核心原则，将工具链踩坑教训、流程协作方法、失败反模式分别归档为标准化 Markdown 条目。钩子机制自动扫视 INDEX 并在相关场景触发时拉取全文，无需手动检索。每次沉淀新条目、更新索引、一致性校验均由 CNB Build 云原生流水线自动完成，确保知识库内容与规则的一致性。

开发工具

职业发展

人工智能

agent-kb：跨项目可复用的踩坑经验库，85条标准化Markdown记录按工具、流程、反模式三类归档。收录CNB NPC派单payload缺失、Git credential空值挂起、macOS symlink路径等实战教训，云原生构建自动校验，新会话自动匹配相关条目，避免重复踩坑。开源仓库地址：https://cnb.cool/apigogo/agent-kb

2026上云采购 | AI焕新·智启新局

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

agent-kb：跨项目可复用的踩坑经验库，85条标准化Markdown记录按工具、流程、反模式三类归档。收录CNB NPC派单payload缺失、Git credential空值挂起、macOS symlink路径等实战教训，云原生构建自动校验，新会话自动匹配相关条目，避免重复踩坑。开源仓库地址：https://cn...

你很需要的教训/经验/知识自提取工具——Agent-kb-腾讯云开发者社区-腾讯云

你很需要的教训/经验/知识自提取工具——Agent-kb

你很需要的教训/经验/知识自提取工具——Agent-kb

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐