企业官网建设流程全解析

很长一段时间里，我把AI当成一个“对话工具”——打开窗口，输入问题，拿走答案。但用久了发现一个特别难受的点：它记不住我的背景。我写过不少技术笔记：某个老系统的坑、某个业务的边界、某个第三方库的兼容性结论。这些信息散落在Obsidian库里，是我花好几年攒下来的“个人脑外记忆”，可是AI打开对话的那一刻，全都用不上，我只能一次次把相同背景重新描述。后来我把思路倒了过来：既然Codex这种AI智能体能自己读文件，那我就把整个Obsidian个人知识库作为它的工作目录，让AI“接着我的积累干活”。这篇教程就是这套做法的完整复盘，包括库结构怎么设计、Codex怎么配置、提示词怎么写，以及好几条踩过才懂的经验。适合三类人：长期记技术笔记的开发者、想用AI管理研究资料的学者，以及所有希望“AI不是从零开始，而是站在你肩膀上”的知识工作者。

1. 为什么是Codex加Obsidian：从提示词工程走向知识工程

1.1 你缺的可能不是更好的提示词，而是让AI能读到的积累

现在的AI教程一抓一大把，翻来覆去讲“提示词”“结构化提问”“角色扮演”。不可否认，这些技巧有效，但它们解决的是“同一份上下文里怎么榨干AI”的问题。而更常见的瓶颈是：AI根本没有足够的背景信息。你让一个刚来的实习生直接改核心模块，他只会在曾经的聊天记录里抓瞎；你让AI替你重构老项目，它也不知道这个项目经历过多少轮需求变更、有哪些隐藏的业务规则。

Obsidian里存的恰恰是这些东西——你曾经解决过的问题、记录过的决策、整理过的代码片段。把个人知识库给AI读，相当于给实习生一份交接文档，而这份文档不是临时写的，是你积累了很久的真实沉淀。我特别喜欢一个类比：AI每次会话像一张白纸，你的笔记像一沓旧图纸。没有图纸，AI只能凭常识瞎猜；有图纸，AI才能按你的思路干活。所以无论你用哪款AI工具，第一步都应该是回头审视自己的知识库，而不是继续寻找更玄妙的提问话术。

1.2 Codex的工作方式：会自己翻资料的智能体

需要先澄清一下，Codex并不是又一个大模型聊天框。它是OpenAI推出的命令行AI智能体，以编码任务为核心，工作方式很接近一名真正在你电脑前操作的工程师：它会在当前目录里列文件、查看内容、搜索关键代码、运行命令，然后给出修改建议甚至直接把代码改了。这种“会自己翻资料”的特性，让它和Obsidian的配合变成一件很自然的事。

我最初试用Codex时，把电脑里一个写了好几年的笔记库当作工作目录，直接跑了一次codex。它自己就开始浏览目录结构、读我写的MOC文件、翻最近的项目笔记，整个过程几乎不需要我指引。那种感觉挺奇妙的——AI第一次不是在“猜我的意思”，而是在“读我的积累”。当然，这并不是说它天生认识Obsidian的语法，关键还是后端知识库本身要够规范，这正是第二章要解决的问题。

1.3 这套方案适合谁，以及它的边界

先说适合的人。第一种是“笔记已经攒了不少”的开发者，Obsidian里有技术踩坑、架构设计、代码模式；第二种是研究者或内容创作者，需要把大量文献、素材、观点交给AI去整理输出；第三种是会把工作文档做成Markdown的知识工作者，比如产品经理、咨询顾问，知识库记录了项目脉络，让AI基于这些脉络做分析。

不太适合谁呢？如果你的Obsidian库几乎是空的，或者只是随手丢些网址收藏，那这套方案见效很慢。因为它的核心逻辑是“用积累换效率”，没有积累，AI能读的东西就少，最后又回到普通对话模式。另外它也不是万能工程助手：Codex强在编码和检索，不要指望它帮你凭空生成一个完整产品，更多是“基于你已有的东西做得更好”。打个比方，它像是你的老搭档，不是你的全新外包队伍。这个边界感要提前建立，才不会用两天就失望。

2. 知识库设计：让AI读得懂的Obsidian结构

2.1 别一上来就让AI读整个库：三层设计避免上下文爆炸

笔记库用久了，动辄上千篇文档，全量丢给AI只有两个结果：要么上下文超限，要么AI抓不住重点。我最后沉淀下来的经验可以归纳成三层结构：入口层（地图），索引层（摘要），细节层（正文）。入口层通常是几个MOC文件，告诉AI“这个知识库里有哪些主题空间”；索引层是每个主题下的一篇摘要笔记或Frontmatter里的summary字段；细节层才是各自独立的详细笔记。AI读到哪、读多少，由Prompt控制，它先看入口，再查摘要，最后才深入细节。

这个设计思路和给新同事发资料的逻辑一样：你不会把五年聊天记录全部丢过去，而是先给一份Wiki首页，再给项目概览，最后按需找详细文档。Obsidian的默认形态是大量双链笔记互相关联，但对AI而言，过多网状结构反而不利于检索，所以我倾向于在重要节点上做“收敛”——画出一条从MOC到摘要再到正文的主干路径，信息反而更清晰。坚持这样做，半年之后你的库不会变成蜘蛛网，反而会像一本有目录、有索引、有正文的出版物。

注意：这里有一个很容易忽略的前提，AI读取的是纯文本Markdown，它不会像人一样在Obsidian界面里点击跳转。所以“导航路径”这件事，必须由你在笔记结构里主动铺好。

2.2 Frontmatter规范：给每一篇笔记配上结构化的“身份卡”

Obsidian支持在每篇Markdown文件顶部写YAML格式的Frontmatter，用三个短横线包裹。对AI来说，这是它读过最舒服的部分之一：结构化字段比散文更容易被解析。我常用的模板是这样：

--- title: 登录模块权限设计 tags: [架构/后端, 认证授权] type: design-doc status: 已采纳 summary: 登录模块采用RBAC加细粒度资源权限，主要决策集中在角色维度，2025年起不再兼容旧Token。 related: [auth-login-重构记录, 用户中心业务边界] ---

几个字段的用途分别是：title是标题；tags是检索标签，我强制只用层级标签，例如“架构/后端”“故障/数据库”，不用“重要”“笔记”这种模糊标签；type标记文档类型，可以是design-doc、bug-trace、tutorial、meeting-note等；status记录这条经验是已采纳还是草稿；summary是整个Frontmatter里对AI最关键的字段，一句话说清这篇笔记解决什么问题；related用来指定关联笔记的相对路径，比套用Obsidian的[[双链]]更适合程序读取。

这套规范对老笔记不需要强行追溯。我当时的处理方式是：从最近写的30篇补起，把Frontmatter补全，再往后坚持新笔记必写完整。一个知识库真正能被AI高效使用，靠的不是几百篇全部达标，而是核心路径上的几十篇足够标准。

2.3 MOC设计：给AI一张“知识地图”，而不是一堆散装笔记

MOC是Obsidian社区很流行的概念，本质就是一篇汇总笔记，里面用列表或表格把某个主题下所有重要笔记串起来。我每建立一个主题空间时，都会先写MOC，而且给它加一段背景说明。AI不用去读几十篇碎片笔记，一篇背景说明就让它快速理解这个主题的边界。

下面是我常用的MOC结构示例：

# 前端架构 · MOC > 项目背景：前端采用Vue3+TypeScript，老登录模块在2024年重构过，主要决策依赖《登录权限设计》和《用户中心业务边界》两篇笔记。 > 使用说明：AI在处理前端架构相关任务时，先阅读本文件，再根据任务定位到具体笔记。 ## 核心文档 - [登录权限设计](notes/auth-login.md) - [用户中心业务边界](notes/user-center-boundary.md) - [前端发布流程](notes/frontend-deploy.md) ## 最近进展 - 2025.03：Token刷新机制升级，细节见《会话管理改造》 - 2025.02：路由守卫新增白名单策略，见《路由权限清单》 ## 待办与计划 - [ ] 登录高峰期限流方案评审

这里有几个细节值得注意。首先，链接我全部写成Markdown相对路径格式，而不是Obsidian默认的[[双链]]，原因后面第四章会细说；其次，每篇MOC都有一句“AI使用说明”，相当于主动给智能体指路；第三，我保留了“最近进展”和“待办”两个块，这样AI在处理问题时，不只看到静态知识，还能看到项目当前状态。这套结构让MOC从一个“链接集合”升级成“AI依据文件”，是我整张方案里性价比最高的投资。

3. 实操：从安装配置到让AI真正干活

3.1 Codex安装与仓库初始化：以Obsidian库为工作区

先从工具链讲起。Codex的官方安装方式很简单，需要电脑上已经装好Node.js，然后在终端执行：

npm install -g @openai/codex

装完之后，先用codex init初始化配置文件。这条命令会生成一个~/.codex/config.toml，Codex的很多行为都是在这里定义的，包括模型选择、审批策略、对话历史保留等等。如果你不太确定配置项的含义，可以直接看文件顶部注释，或者保持默认。官方也提供了codex --help可以随时查看。

接下来是关键一步：把Obsidian库目录设为Codex的工作区。如果你用终端进入Vault文件夹，比如：

cd ~/Documents/MyVault codex

这样启动之后，Codex的当前工作区就是这个Vault。它的好处是：AI可以任意读取库里的Markdown文件，可以直接把你指定的笔记内容作为分析依据，还可以把修改后的方案写回库里。我还会把一些高频使用的动作存成Shell外挂命令，比如一键把目录列表压缩成上下文摘要，这些细节操作下面会讲到。需要说明的是，Codex是个会持续执行多步任务的智能体，它不会只回答一句就结束，而会列计划、读文件、执行操作，所以给它一个边界清晰的工作区非常重要，不建议直接在家目录运行。

关于config.toml，我实际常用的配置就三行：

model = "gpt-5-codex" approval_policy = "on-request"

approval_policy = "on-request"的意思是，Codex每次要执行比较敏感的操作（比如改文件、运行命令）前，会先问我一句，得到确认后才动手。新手阶段建议都开这个，不然它可能会在你还没看懂计划的时候就改了文件，回头排查起来很痛苦。

3.2 写一份真正管用的AGENTS.md：让AI一进来就懂你的规矩

Codex会自动读取工作区里的AGENTS.md文件，把它当作项目行为准则。这是整条链路里最能提效的部分，因为写好这一个文件，就等于把所有“如何配合”的常识灌进了AI的初始上下文。我自己的AGENTS.md长这样：

# AGENTS.md ## 项目简介 本目录是一个 Obsidian 个人知识库，存放技术笔记、项目文档和长期积累的工作经验。 目标是通过 AI 智能体协助检索、分析、整理和重构这些知识。 ## 笔记组织方式 - 每个主题空间都有一篇 MOC，AI 处理某类任务前必须先读对应 MOC。 - 笔记顶部有 YAML Frontmatter，summary 字段是核心摘要。 - 重要链接一律使用相对路径 Markdown 格式，不使用 [[双链]]。 ## 任务执行规范 1. 开始任务前，先列出你准备读取哪些文件。 2. 所有结论必须标注引用来源，不确定的地方明确说“笔记中未找到”。 3. 如果要修改现有笔记，先展示 diff，确认后再写入。 4. 任务结束后，把结果记录在“决议日志”中，格式为：日期/做了什么/下一步建议。

这份文件对AI的约束非常明显：第一步强制它列读取计划，避免盲目乱翻整库；第二步要求从成果反推证据，减少无中生有；第三步是操作权限把关，防止AI一顿操作把笔记改得面目全非；第四步则是让整个工作流闭环，下次AI再来时知道上次停在哪。

有个小经验：不要一开始就把AGENTS.md写得很长。我第一版写了七八条规则，结果AI每轮都被那些规则牵制思路。后来精简到上面这份，核心约束不超过五个，执行效果反而好很多。规则在精不在多。

3.3 实测：让AI基于笔记改代码的五步法

理论知识说完，给你一条能直接照做的完整流程。我把它称作“五步法”，每一步都有具体操作。

第一步，让AI只读地图不读全库。假设今天要重构登录模块，我会这么写Prompt：

先读取前端架构的MOC文件（00-MOC/frontend-arch.md），了解当前项目背景和核心文档分布，不要展开阅读其它无关笔记。

这一步的目的是把AI的上下文窗口用在刀刃上。第二步，按需深入指定笔记。等它读完MOC后，我会继续指定参考文件：

接下来精读这两篇笔记：notes/auth-login.md 和 notes/user-center-boundary.md，重点关注登录流程和权限边界。准备一份重构方案，方案里必须注明每个结论来自哪篇笔记。

第三步，让AI列出计划但先别动手。我会要求它输出“准备执行的操作清单”，例如要改哪些文件、涉及哪些函数、会跑什么测试。如果计划里出现了笔记里没有的东西，我会立刻打断纠正。第四步，批准执行并验证。确认计划没问题后，让Codex直接改代码或在库里生成新的Markdown方案，改完我会要求它跑相关测试，再把执行结果和新产生的结论回填到原笔记。第五步，收敛归档。任务完成后，让AI在决议日志里追加一条记录，然后更新MOC的“最近进展”区块。

这套五步法最核心的思想是：让AI做“检索-分析-执行”中的一环，但每一步都要有人的判断在场。我最高效的一次，是把一篇困扰了我三天的老项目模块改造，压缩到十五分钟完事。因为在之前几个月里，笔记库已经把来龙去脉写清楚了，AI只是把这些脉络重新串起来。

3.4 一次完整的“知识库驱动”任务演示

为了让你更好理解，我贴一段实际跑过的任务记录。当时我想让AI基于旧笔记输出一个新的登录模块设计，整个过程大致如下：

我：先读《前端架构MOC》和《登录模块权限设计》两篇笔记，我要在这基础上扩展一个“多端登录”方案。 AI：已读取两份文件。根据笔记记录，当前登录模块使用RBAC，且旧Token机制将在2025年停用。我准备输出一份扩展方案，包括多端会话隔离、刷新Token策略和权限校验顺序。这三项均可在现有笔记中找到依据。 我：可以，但第三项“权限校验顺序”在笔记里没有明确描述，请把它标为缺口。 AI：好的，我会在方案中单独标注“待补充”。已经生成方案草稿，需要我现在写入候选笔记目录吗？ 我：写入吧，然后在决议日志里记一条。

整个过程没有一句废话。AI知道去哪找资料、知道哪些内容有据可查、哪些内容只是推测，写出来的方案也不会凭空创新。这种体验和我过去“问一句答一句”的模式完全不一样。而能把对话压缩到这么高效的原因，恰恰是知识库三层的结构设计在前，AGENTS.md的规则约束在中，最后才是那句Prompt。

4. 常见问题与排查技巧实录

4.1 Obsidian双链让AI摸不着头脑

踩过的第一个坑，就是Obsidian最引以为傲的双链。普通人类看[[登录权限设计]]一眼就知道这指向某篇笔记，但Codex在读取时会把它当成一个奇怪的文本标记，没法直接跳转。如果是我们人在操作界面点击没问题，但AI在终端里只能处理纯文本。

我的解决方案很简单：凡是AI需要读取的“主路径”文件，链接全部改写成相对路径格式[登录权限设计](notes/auth-login.md)。这样不仅Codex能解析，Obsidian本身也支持Markdown格式链接。至于双链，可以用在人类自己浏览的栏目里，但AI主导的MOC和索引文件，一定用相对路径。如果你已经写了一堆双链文件，不用全改，只要把MOC和核心入口改好就行，AI靠这些入口就能指路到正文，其余双链基本不受影响。

4.2 上下文还是太长？用摘要优先和索引文件

即使有MOC和摘要，随着笔记越来越详细，AI读一篇长文也可能撑爆上下文窗口。我后来会在每个主题空间里维护一个INDEX.md，它是MOC的进一步抽象：一篇文章只用一行，格式是“标题——一句话摘要——相对路径”。AI面对这类任务时，我可以直接命令它先读INDEX.md，从中挑出两到三个文件名，再进入正文。等于给AI装了一个图书目录，它不用一本本翻过去才知道哪本书有用。

分享一个具体的Prompt写法：

先读 notes/INDEX.md，根据里面的摘要判断哪些笔记和“登录模块会话管理”相关，只返回你选中的文件路径和判断理由。

实际效果非常明显，AI读完索引再深入指定文档，常常能把一次任务的上下文占用减少一半以上。所以知识库不是越大越好，而是“AI走得进去、出得来”才好。

4.3 Frontmatter解析失败、标签混乱、主题插件安装失败

先说Frontmatter。我见过最多的错误是YAML格式问题：比如字段值里包含英文冒号，写了未加引号的字符串，或者缩进不对，导致解析直接失败。Obsidian墙上的提示可能不明显，但AI读取时会发现字段乱掉。补个实用经验：每个Frontmatter尽量只写简单键值对，复杂内容放到正文里，不要硬塞给YAML。另外标签我统一用/做层级分隔符，比如架构/前端，避免中文空格导致AI识别出多个标签。

至于主题安装报错也遇到过。社区主题Anuppuccin在Obsidian里一键安装提示无法下载时，可以直接去GitHub仓库下载主题文件夹，手动放到Vault目录下的.obsidian/themes/里，再在“外观”设置里切换。这属于老生常谈，但每次都能救急。顺带一提，如果对Obsidian插件安装机制不熟，遇到任何安装失败，第一反应都是从“手动放到对应目录”的角度排查，十有八九能解决。

4.4 两条血泪教训：别让AI“自由发挥”，要它“引用来源”

在使用这套流程的过程中，我踩过最深的坑是两个。第一个是过度信任AI给出的方案，它信誓旦旦说某段代码是笔记里藏着的，结果我翻了半天根本没找到。后来我设置了硬约束：所有结论必须带来源，笔记里没有的就说没有。这个约束真的救了好几次，AI开始自己说“笔记中没有找到该信息”，而不是顺着我的问题编答案。

第二个教训是别把AI当“从零到一的生产工具”。我一度试图让Codex从一个老的业务笔记里“续写”整个新方案，结果它把笔记里没提过的未来功能都写进去了，看起来有理有据，实际全是幻觉。解决办法是在AGENTS.md里明确“只能基于笔记现有内容工作，未覆盖的需求要标记为缺口”。很多幻觉问题的根源不是AI变笨了，而是你给了它一个允许发挥的空间。想把幻觉挡在外面，就要主动收窄这个空间。

用这套方法跑了快半年，我最大的感受是：AI终于不是“每次从零开始的外包”，而变成了一个了解我积累的助理。每天开工前我会花十分钟更新MOC和决议日志，Codex跑完任务后，也会顺手在决议日志里记一行“今天做了什么、下一步建议是什么”，下次我只需要让它看日志，就能无缝接着跑。这种“积累—沉淀—复用”的节奏，才是知识库最有价值的地方。

最后再分享一个小技巧：在Obsidian里单独建一篇笔记叫《AI协作手册》，专门记录你和Codex之间好用和不好用的协作模式。比如某一类Prompt特别高效、某类任务会导致它陷入幻觉，都记下来。半年下来，这本手册比任何AI教程都管用，因为它是你和你自己的智能体磨合出来的专属说明书。希望这篇教程能让你也体验到“让AI接着你的积累干活”的痛快。