《狂人日记NO.11》— 给 AI 装一本"项目说明书"：我把"自己"蒸馏成了一个编码知识库Skill

本文档在 AI 辅助下完成：先由人工构思大纲与核心观点，再由 AI 根据大纲扩展，最后人工审校定稿。

---

零. 前言

思维链：

最近用 AI 写代码越来越多，有个感受越来越强烈：AI 每次接手项目，都像个刚入职、对项目一无所情的新同事------你不说，它就不懂；你说了，下次又忘了。

尤其是我们这种项目：自研的组件库、三维地球 SDK、卫星轨道计算库一大堆，还有一堆历史沉淀的编码约定。每次让 AI 写点东西，它要么把现成的组件重新造一遍，要么风格飘得妈都不认识，最要命的是三维库------它动不动就 new Cesium.Viewer(...) 绕过我们的统一封装，直接给你整出一堆跑不通的代码。

我就想：能不能把"项目该怎么写"这件事，像写文档一样蒸馏成一份给 AI 看的"说明书"，再封装成一个 Skill？这样 AI 一进来就自动懂我们的库、懂我们的约定，优先复用、不造轮子、不风格漂移。

说干就干。我先后把我维护的 fetm（组件 / 逻辑 / 工具三件套）、sat-earth（卫星态势三维地球）、kbe3d（三维地球 SDK + 卫星轨道库）这几个组件 / SDK 库，以及部分业务项目源码，逐库读了一遍、把隐含的约定显式化，最终产出了这个知识库 Skill：ai-coding-kb。

这就是它的由来。下面从 What / Why / How 三个角度，聊聊这个 Skill 是什么、为什么值得做、以及怎么用。

---

壹. 这个 Skill 是什么（What）

1.1 一句话定义

ai-coding-kb 是一个AI 编码知识库技能，提供两套能力：

1. 初始化蒸馏：在新项目 / 新会话启动时，读取当前项目真实源码与配置，把隐含的编码约定显式化，生成 / 更新 knowledge 文档，让 AI 适配当前项目。
2. 编码期复用 ：写代码时优先查阅自带的 fetm / sat-earth / kbe3d / vue 知识库，复用现有能力、遵守编码风格、不误用全局对象。

本质上，它就是给 AI 装了一本"项目说明书"------而且这本说明书是可执行的：不是给人看的散文，而是给 AI 在写代码前查的 API 索引 + 约定清单。

1.2 它解决什么痛点

AI 接手一个陌生项目时，通常会犯三类错：

痛点	表现	后果
重复造轮子	不知道有现成组件 / hook / 工具，自己又写一遍	代码冗余、行为不一致、维护双倍
风格漂移	不知道项目约定，分号、引号、注释规范各写各的	代码 review 全是在改格式
误用全局对象	不知道 Cesium / window.earth 是免 import 的全局变量，或者绕过统一封装直接 new 底层对象	编译报错、运行时崩溃、三维场景起不来

第三类最致命。三维项目里，AI 一旦自作主张 new Cesium.Viewer 或 new 自己的地球实例，往往就是一堆跑不通的代码------因为它根本不知道你们团队对三维能力的那层统一封装（@/utils/map / dczUtil）。

1.3 它到底装了什么

整个技能目前由 1 个 SKILL.md + 1 个总入口 README.md + 4 套子库 组成，蒸馏出的知识文档共 30+ 篇：

组成	作用
SKILL.md	技能总入口：定义两套流程（初始化蒸馏 / 编码期复用）与触发规则
references/README.md	知识库总入口：四库关系、AI 使用流程、全局对象约定、维护约定
references/vue/	业务应用工程化 + 编码风格（10 篇）
references/fetm/	组件 / 逻辑 / 工具三件套（5 篇）
references/sat-earth/	卫星态势三维地球（7 篇）
references/kbe3d/	三维地球 SDK + 卫星轨道库（8 篇）

不是一份泛泛而谈的"规范文档"，而是按库、按能力拆分的可检索知识 ：写业务页查 vue/；要用现成 UI 组件查 fetm/；写三维地球或卫星轨道查 sat-earth/ 和 kbe3d/。

1.4 四套子库的关系

四库相互独立，但存在清晰的调用层级：

子库	定位	被谁用
vue	业务应用层------工程配置、路由/状态/接口范式、编码风格、态势页标准结构	直接写业务代码
fetm	业务组件与通用逻辑库（UI 组件、组合式函数、工具函数）	业务应用直接 import 复用
sat-earth	卫星态势三维地球组件库（mars3d / Cesium 封装）	业务层经 @/utils/map 间接用
kbe3d	三维地球 SDK（KBCore.Earth 封装）+ 卫星轨道计算	业务层经 @/utils/map 间接用

一句话：vue 是门面，fetm 是零件，三维能力（sat-earth / kbe3d）则统一收敛到 @/utils/map 与 dczUtil 这两层封装之后，业务代码不直接碰底层对象。这个分层，正是知识库要帮 AI 守住的边界。

1.5 知识库长什么样

知识库不是随便写的笔记，它有一套蒸馏规则，保证"显式化出来的约定"是可信、可维护的。

蒸馏流程（五步）：

1. 读工程化配置 ：package.json、vite.config.ts、tsconfig.json、uno.config.ts、eslint.config.js、*.env（只记 key，脱敏）。
2. 读全局类型 ：types/*.d.ts，重点是 global.d.ts 里那些免 import 的全局对象。
3. 读运行时配置 ：public/config/vars.js 及全局变量注入方式。
4. 读核心源码 ：入口 main.ts、API 层 @/api、状态层 @/store、工具层 @/utils、hooks、布局/根组件、views/ 代表页面。
5. 对比历史 knowledge：把读到的事实与已有文档逐条比对，按冲突原则修正 / 补充。

冲突处理四原则（最高优先级）：

• ✅ 以当前项目真实代码为准：知识库与源码冲突，改知识库，不改源码（除非源码确为 bug）。
• ✅ 保留历史经验：当前项目没用到的内容（别的项目的库 / 模式）保留不删，标注「本仓库未采用，保留为历史经验」。
• ❌ 禁止凭空捏造 ：所有写入必须来自真实源码；存疑就搜证，搜不到标「待确认」，绝不复述一个 import xxx from 'yyy'。
• ❌ 脱敏 ：不写项目名、业务名、VITE_APP_* 具体业务值；业务目录用「业务态势页」等泛称。

这四条是知识库可信的根。下面 Why 部分会展开为什么说它是命门。

---

贰. 为什么做这个 Skill（Why）

2.1 痛点还原：AI 每次都"失忆"

传统用 AI 写代码的模式是：你每次新开对话，都要把项目背景、有哪些库、有什么约定重新讲一遍。讲少了它不懂，讲多了你累。

更现实的问题是------你根本讲不全。像我们这种项目，自研库几十个组件、十几个 hook、几十个工具函数，还有 SGP4 轨道传播、Cesium 封装、全局变量注入......你不可能每次都背一遍。一旦没说到的地方，AI 就按自己的"训练默认"来写，于是：

• 明明有 fetm-utils 的 MyWebSocket，它偏要手写一个 new WebSocket(...)；
• 明明要 isSuccess(res) 判成功，它偏写 res.msg === 'SUCCESS'；
• 明明三维要走 @/utils/map，它偏 import Cesium from 'cesium' 然后自己 new Viewer。

这些不是 AI 笨，是它没有项目的"认知基础设施"。Rule 能管一部分行为，但管不了"你有哪些现成能力可以复用"这种量级的信息。

2.2 用前 vs 用后

把"有没有知识库"放到几个高频场景里对比（定性描述）：

场景	没有知识库	有 ai-coding-kb
写个带 WebSocket 的组件	手写 new WebSocket，心跳要自己写	直接 new MyWebSocket(...)，心跳内置
调一个后端接口	写 res.msg === 'SUCCESS' 被判成功（实际约定不是这个）	isSuccess(res) + res.data.data，一次写对
加一个卫星图层	import Cesium 自己 new Viewer / new Entity，绕封装	走 SatMap / KBCore.Earth + satMap.layer.addLayers(...)
算卫星轨道	自己找 sgp4 库、拼 TLE 解析	KBSatellite.sgp4Orbit(...)，CPU/GPU 双模式开箱即用
整体编码风格	分号引号注释各写各的，review 改格式	无分号、单引号、TypeDoc 注释，自动对齐

效果不只是"少写几行"，而是把 AI 从"会写代码但不懂项目"的新人，变成"懂你库、守你约定"的老员工。

2.3 为什么是"知识库"而不是单纯 Rule

很多人第一反应是：这用 Rule 不就完了？

不是一回事。差别在"量级"和"性质"：

维度	Rule（规则）	知识库（Skill）
性质	行为约束（软）："不许编造""用 TypeDoc 注释"	能力索引（硬）：有哪些组件 / hook / 工具、API 怎么调
量级	几条到十几条原则	30+ 篇文档、上百个 API、几十个约定
AI 拿到后能做啥	知道"边界"，但不知道"你有什么"	知道"你有什么"，写代码前能检索复用

Rule 回答的是"怎么写才不犯错 "；知识库回答的是"你有哪些现成东西可以先拿来用"。两者是互补关系，不是替代关系。知识库这套体量，显然已经超出 Rule 能承载的范围，所以它值得被做成一个独立 Skill。

2.4 边际成本递减

这点和我之前做其他 Skill 的体会一样：第一次贵，后面便宜。

• 首次蒸馏：要把几个库逐篇读一遍、显式化约定，确实要花时间（相当于一次性把"项目认知"从你脑子里抽出来）。
• 之后复用：每个新项目 / 新会话，触发一句话（或自动）就能加载，AI 立刻"懂行"。
• 持续沉淀 ：通用约定写回 references/ 子库，跨项目复用；项目特有差异写进当前项目的 .codebuddy/knowledge/，随项目走、团队共享。

一次投入，反复受益，而且越用越厚。

💡 关键心得：真正值得沉淀的，不是某段代码，而是"项目认知"本身------哪些库能用、怎么用、有哪些坑。把它从人脑和零散的对话里抽出来，变成可复用、可共享、可继承的资产，这才是 AI 时代团队最值钱的"护城河"之一。

---

叁. 怎么用（How）

3.1 初始化蒸馏（新项目 / 新会话）

当你说"初始化知识库 / 蒸馏项目 / 适配当前项目"时，Skill 按五步流程跑：

1. 判定项目形态 ：业务应用（含 src/、vite.config.ts）、组件库 / monorepo 子包（shared/、packages/、fetm-*、sat-earth、kbe3d-*），还是混合项目。
2. 按蒸馏规则读源码：工程化配置 → 全局类型 → 运行时配置 → 核心源码 → 对比历史 knowledge。
3. 写出 / 更新 knowledge ：
   • 项目特有差异 → 写进当前项目的 .codebuddy/knowledge/（随项目走、团队共享）。
   • 通用、可跨项目复用的约定 → 同时写回 references/ 对应子库（知识库持续沉淀）。
4. 自检：按「冲突处理四原则」与「写作规范」逐条核对，确认索引同步。

用户已确认"两者都写"：项目差异进 .codebuddy/knowledge/，通用约定回写 references/。

3.2 编码期复用（日常写代码）

每次动手写代码前，Skill 引导 AI 走这套：

1. 判断任务属于哪一层 ，定位对应子库：
   • 改业务页面 / 接口 / store / hooks / 组件样式 → vue/knowledge/
   • 用现成 UI 组件或工具函数 → fetm/knowledge/
   • 写三维地球、图层、特效、卫星轨道（SGP4 / TLE）→ sat-earth/knowledge/ / kbe3d/knowledge/
2. 读对应子库 README → 按「文档索引」找到具体细分文档。
3. 优先复用知识库里的组件、hook、工具、约定与范例代码；不自行实现库里已有的能力。
4. 遵守编码风格 ：无分号、单引号、<script setup lang="ts">、TypeDoc 注释等。
5. 冲突时以真实代码为准：知识库只是约定记录，不替代实际源码。

3.3 几条硬约定（脱敏代码片段）

这些是知识库里最容易被 AI 踩坑、也最该被"焊死"的约定。

① 全局对象免 import，直接用

Cesium / turf / XTDCZ 是 <script> 标签加载的全局变量；window.viewer / window.earth / window.xv 是运行时注入的实例；Vue API（ref / computed / onMounted ...）、useRoute / useRouter、defineStore 由 auto-import 自动注入。一律不写 import。

// ❌ 错误：把全局对象当模块 import
import Cesium from 'cesium'
import { useRoute } from 'vue-router'

// ✅ 正确：全局对象直接用，Vue API 免 import
const viewer = window.viewer
const route = useRoute()

② 接口响应用 isSuccess(res) + res.data.data

拦截器不解包 axios 响应，所以判成功用 isSuccess(res)（code ∈ [0, 200, 20000]），业务数据取 res.data.data。不要 写 res.msg === 'SUCCESS'。

import { API } from '@/api'
import { isSuccess } from '@/api/axios'

const res = await API.getCaseTreeData()
if (isSuccess(res)) {
  this.caseTreeData = res.data.data ?? []
}

③ 三维能力统一走 @/utils/map / dczUtil，业务不直接 new 底层

业务代码不直接 new Cesium.Viewer、不直接 new 自研地球实例，统一走封装层。

// ✅ 业务层通过封装后的地图工具与 hook 操作三维
import { fromIso8601, toIso8601 } from '@/utils/map/mapUtil'
import { useMapScene } from '@/hooks/useMapScene'

const julianDate = fromIso8601('2026-01-01T00:00:00Z')

④ 编码风格：无分号、单引号、<script setup lang="ts">、TypeDoc 注释

组件 <script setup> 有固定结构顺序，公共方法一律补 TypeDoc 注释（@param xxx - 说明 / @returns / @example）：

<script setup lang="ts">
// 1. import（外部包 → 空行 → @/ 内部 → 空行 → 相对路径）
import { MyWebSocket } from 'fetm-utils'

import WidgetContainer from '@/components/Container/WidgetContainer.vue'
import { useMapScene } from '@/hooks/useMapScene'
import { useBusinessStore } from '@/store/modules/business'

import EventProcessPanel from './components/bottom-panel/EventProcessPanel.vue'

// 2. defineOptions（组件名）
defineOptions({ name: 'Simulation' })

// 3. 响应式状态 / store / 组合式函数
const businessStore = useBusinessStore()
const { mapRef } = await useMapScene() // 顶层 await（Vue 3.5 支持）
const isMounted = ref(false)

// 4. computed
const disableTimeline = computed(() => { /* ... */ })

// 5. 方法（function 声明）
function handleSubmit() { /* ... */ }

// 6. 生命周期
onMounted(() => { /* ... */ })
</script>

3.4 可信命门：脱敏 + 禁止捏造

知识库最大的风险不是"写得少"，而是"写错"------尤其 AI 容易一本正经地捏造一个不存在的 API 或 import 路径。所以这个 Skill 把两条当铁律：

• 禁止凭空捏造 ：所有写入必须来自真实读到的源码 / 配置。未确认的（某个 npm 包名、某个全局变量来源）不许猜，去代码里搜证；搜不到就写「待确认」或直接不写，绝不编一个 import xxx from 'yyy'。
• 脱敏业务信息 ：知识库只沉淀技术约定与编码风格，不写项目名、应用标题、业务模块名、VITE_APP_* 具体业务值。目录结构可保留，但中文业务注释用「业务态势页」「<business>-situation/」等泛称替代。

这两条保证了：AI 查到的每一条，都对应真实代码里确实存在的能力，而不是幻觉。

3.5 知识库怎么维护

• 文档索引同步 ：每篇以 README.md 为索引，细分文档登记在索引表；新增 / 删除需同步更新。
• 随项目走 ：项目特有差异在 .codebuddy/knowledge/，团队共享、进版本库。
• 跨项目复用 ：通用约定沉淀在 references/ 子库，新项目复制 knowledge/ 后按蒸馏流程重跑即可。
• 历史经验保留不删：当前项目没用到的库 / 模式，标注「本仓库未采用」继续保留，方便跨项目复用。

---

肆. 它到底装了什么（内容速览 + 真实示例）

光说框架太空，这一节贴几段脱敏后的真实知识，让你直观感受它"装"了什么级别的细节。

4.1 fetm：组件 / 逻辑 / 工具三件套

fetm 是自研组件库（monorepo 的 shared/ 包），分三个子包：

包名	定位	规模
fetm-components	组件库（多为 element-plus 封装）	30+ 业务组件
fetm-hooks	逻辑库	14 个 Vue 组合式函数
fetm-utils	工具库	30 个纯函数 / 工具类模块

核心约定：能复用绝不重写；统一从包名导入，不深入子路径。

// ✅ 统一从包名导入
import { MyWebSocket } from 'fetm-utils'
import { SomeWidget } from 'fetm-components'

// ❌ 不要深入子路径 import
// import MyWebSocket from 'fetm-utils/websocket/index'

图标优先用 unocss 预设（打包为 base64，离线可用），只有动态图标才用 Icon 组件。

4.2 sat-earth：卫星态势三维地球

sat-earth 是基于 mars3d（封装 Cesium）的卫星态势三维地球组件库，核心是一个 SatMap 类 + 13 个 Vue 组件 + Pinia 状态 + 工具函数。主入口是 SatMap 类：

import { SatMap } from 'sat-earth'

const satMap = new SatMap('satGlobe', 'mapContainer', {
  map3d: {
    scene: { center: { lat: 39, lng: 116, alt: 100000 } },
    terrain: { url: '...', show: true },
    basemaps: [{ name: '底图', type: 'xyz', url: '...' }],
    control: { compass: false, locationBar: false },
    custom: {
      layoutTheme: { isDark: true },
      toolbar: { mapSplit: true, keyboardRoam: true },
    },
  },
})

await satMap.inited()
satMap.layer.addLayers([/* ... */])        // 添加图层
satMap.measure.measureLength()             // 距离测量
satMap.spatialAnalysis.viewshed.startDraw() // 视域分析
satMap.plot.startDraw({ /* ... */ })        // 标绘
satMap.downLoadScreenShot({ fileName: '态势图' })

可以看到：业务层只跟 SatMap 打交道，图层、测量、分析、标绘、截图全部挂在 satMap 实例上------这正是知识库要 AI 守住的"统一封装"边界。

4.3 kbe3d：三维地球 SDK + 卫星轨道库

kbe3d 分两个包：kbe3d-core（KBCore，三维地球基础库，封装 Cesium）与 kbe3d-satellite（KBSatellite，卫星态势感知，整合 satellite.js / tle.js / sgp4.gl）。

主入口是 Earth 类，命名空间导入：

import * as KBCore from 'kbe3d-core'
const earth = new KBCore.Earth(container, viewerOptions, earthOptions)

卫星轨道计算是它最有价值的部分------TLE/OMM 解析、开普勒根数转换、SGP4 轨道传播（CPU / GPU 双模式）：

import * as KBSatellite from 'kbe3d-satellite'

// 1. 一次性轨迹外推
const track = await KBSatellite.sgp4Orbit(
  {
    startTime: '2026-03-18T00:00:00Z',
    stopTime: '2026-03-18T02:00:00Z',
    step: 60,
    kepler: [tleLine1, tleLine2], // 或 KeplerElements 六根数
  },
  { isGetDetails: true },
)

// 2. 实时批量（多星高频更新）
const ctrl = await KBSatellite.sgp4OrbitLive(
  [{ id: 'sat1', kepler: [l1, l2] }, { id: 'sat2', kepler: keplerObj }],
  { isUseGPU: true },
)
setInterval(async () => {
  const positions = await ctrl.update(Date.now()) // Map<id, OrbitPropagatorResult>
}, 1000)

⚠️ 一个很容易被踩的坑，知识库专门标了：GPU 仅支持 f32，安全时间阈值约 1.0e5 分钟（约 69 天），超出会抛 Time values require f64 precision，此时应改用 CPU 模式。这类"隐性约束"正是人工 Review 才挖得出、AI 自己写代码极易忽略的------把它写进知识库，AI 下次就不会再踩。

4.4 vue：业务应用工程化与编码风格

vue/ 是业务应用层的总纲，覆盖工程化配置（vite / tsconfig / uno / eslint / env / router / pinia / axios）、各库集成方式、通用编码风格、态势页标准结构、主题切换等，共 10 篇。

它把第三节约的硬约定（全局对象免 import、接口 isSuccess + res.data.data、三维走 @/utils/map、无分号单引号 <script setup lang="ts">、TypeDoc 注释）全部落到"完整可运行的最小片段"上，作为 AI 写新代码的对齐基准。换句话说，vue/ 是其他三库在业务项目里"怎么被正确组合"的范本。

---

伍. 结语

做这个 Skill 的过程中，我最大的一个体会是：我们平时写代码，真正稀缺的从来不是"能不能写出来"，而是"项目里已经有哪些东西、该怎么用、有哪些坑"------这些认知，原本只存在我自己的脑子里，散在无数次对话和 review 里。

ai-coding-kb 做的事，说大不大：把这套认知从人脑里抽出来，蒸馏成一份 AI 能直接查、直接复用的"项目说明书"。但说小也不小------它第一次让我感觉，我和 AI 之间的协作，从"每次重新解释项目"变成了"一次沉淀、长期受益"。

收尾我想讲几点自己的看法：

1. 复用 > 重写，对人如此，对 AI 也如此。 这个 Skill 的第一原则就是"优先复用既有能力，不重复造轮子"。当你把"有哪些现成组件 / hook / 工具"清清楚楚摆在 AI 面前，它就不再是一个会自作主张重写一遍的"新人"，而是一个知道仓库里有什么的"老员工"。
2. 你的经验，应该变成可继承的资产，而不是随对话消散的上下文。 每次 review 时你纠正 AI 的那句话、每个三维库的封装边界、每个接口的成功判定约定......这些如果只活在当下那次对话里，就太可惜了。把它们写进知识库，它们会站在每一次新对话的肩膀上。
3. 越用越厚，回报是指数级的。 首次蒸馏要花时间，但通用约定写回 references/ 后能跨项目复用，项目差异留在 .codebuddy/knowledge/ 随仓库走。知识库不是一次性文档，而是会随项目成长、越攒越值钱的活资产。
4. AI 的输出要验证，不要盲信。 尤其三维库、轨道计算、全局对象这类容易踩坑的地方，用 git diff 看改动、跑一跑、review 逻辑------这些习惯在 AI 时代比以往更重要。知识库能大幅降低 AI 犯低级错的概率，但替你做最终判断的，依然是你自己。

真正拉开差距的，从来不是"会不会用 AI"，而是"有没有把自己的项目认知，沉淀成 AI 能直接复用的资产"。把"自己"蒸馏成一个 Skill，这件事本身，就是我对 AI 时代"如何与工具共处"的一个回答。

附：SKILL 提取链接

笔记名称 ：ai-coding-kb.skill

提取链接 ：share.note.youdao.com/s/KOtFu83r

有效期：长期有效

---

注：本文档在 AI 辅助下完成：先由人工构思大纲和核心观点，再由 AI 根据大纲扩展详细内容，最后人工审校定稿。知识库内容均蒸馏自真实源码与配置，脱敏处理，未杜撰 API。