企业官网建设流程全解析

1. 先搞清楚这个项目到底在做什么

一个人，九个月，20万行代码，每个月消耗40亿以上的token，最终交付的是一款基于Harness架构的应用。这组数字放在任何一个技术社区里都足够炸裂，但真正值得拆解的不是数字本身，而是这些数字背后隐藏的工程决策链条。我第一次看到这个项目描述的时候，脑子里冒出来的第一个问题是：为什么要用Harness架构？第二个问题是：40亿token到底花在了什么地方？第三个问题是：一个人怎么扛住20万行代码的维护复杂度？

先把概念理清楚。Harness在这里指的是一种以Agent编排为核心的工程架构范式，它的核心思想是把大模型的能力封装成可调度、可组合、可观测的执行单元，然后通过一层编排引擎把这些单元串联成完整的业务流程。你可以把它理解成一个“AI能力总线”——每个Agent是一个独立的功能模块，Harness负责决定什么时候调用哪个Agent、传什么参数、拿到结果之后怎么处理。这和传统的微服务架构有相似之处，但区别在于Harness架构中的“服务”本身具有不确定性和自主决策能力，这就让编排层的设计变得极其关键。

这个项目选择Harness架构而不是简单的Prompt链或者单Agent方案，背后的逻辑其实很直接：当你的应用需要处理多种类型的任务（比如文档解析、代码生成、知识检索、格式转换），单Agent方案会迅速遇到上下文窗口瓶颈和能力冲突问题。一个Agent既要懂Markdown语法又要会调Claude Code的API还要能操作Obsidian的库文件，这种“全栈Agent”在实际运行中会变得极其不稳定。Harness架构通过拆分职责解决了这个问题，每个Agent只负责一个垂直领域，编排层负责路由和状态管理。

适合关注这个项目的人其实很广：如果你正在做AI Agent开发，这里面的架构决策和踩坑经验可以直接复用；如果你在用Claude Code或者DeepSeek Harness做日常开发，可以了解怎么把这些工具串联成自动化流水线；如果你只是对“一个人怎么用AI工具完成大规模项目”感兴趣，这里面的工作流设计思路同样有参考价值。不管你是刚接触Agent开发的新手，还是已经在做多Agent编排的老手，这个项目里都有值得挖的东西。

2. 架构选型的底层逻辑与关键取舍

2.1 为什么是Harness而不是其他方案

市面上做Agent编排的方案大致分三类：第一类是以LangChain为代表的重框架路线，第二类是以Claude Code为代表的CLI工具路线，第三类就是Harness这种轻编排层路线。这三者的核心区别在于控制粒度和调试友好度。

LangChain的问题在于抽象层太厚。你写一个简单的文档处理流程，可能要经过Chain、Agent、Tool、Memory四层抽象，每一层都有自己的配置和生命周期。好处是功能全，坏处是出了问题你根本不知道是哪一层的锅。我在实际项目里用过LangChain做知识库问答，调试一个检索失败的问题花了整整两天，最后发现是Memory模块的默认配置把上下文截断了。

Claude Code这类CLI工具的优势是开箱即用，你不需要自己搭编排层，直接写Prompt就能跑。但它的局限也很明显：你很难把多个CLI工具的调用串联成一个自动化流程，而且每次调用都是独立的会话，状态管理基本靠手动传递。对于这个项目来说，20万行代码的规模意味着每天可能有上百次Agent调用，纯靠CLI工具手动操作根本不现实。

Harness架构的定位正好在两者之间。它不像LangChain那么重，核心就是一个编排引擎加一组Agent注册接口；也不像CLI工具那么轻，它提供了状态管理、错误重试、日志追踪这些生产级功能。用一句话概括：Harness让你用最小的抽象成本获得最大的编排灵活性。

2.2 40亿token到底花在哪了

很多人看到“每月40亿token”第一反应是“这也太烧钱了”，但如果你拆开来看，这个数字其实很合理。假设每天有200次Agent调用，每次调用平均消耗6万token（包括输入上下文和输出结果），那一天就是1200万token，一个月30天就是3.6亿。再加上一些批量处理任务（比如对整个代码库做静态分析、生成文档），很容易就冲到40亿。

关键不在于花了多少token，而在于这些token的投入产出比。我算过一笔账：如果用传统方式写20万行代码，一个高级工程师大概需要18到24个月，按市场价算人力成本至少在百万级别。而40亿token按当前主流模型的定价，成本大概在几万到十几万之间。这个账算下来，token消耗反而是整个项目里最便宜的部分。

真正贵的是时间。一个人九个月完成20万行代码，意味着平均每天要产出700多行有效代码。这个速度靠手写是不可能的，必须依赖Agent自动化生成加人工审核的流水线。所以40亿token的本质是“用机器时间换人类时间”，这个交易在大多数场景下都是划算的。

2.3 单Agent、多Agent和Harness的边界在哪

这里有一个很容易踩的坑：很多人一上来就搞多Agent，结果发现协调成本比收益还大。我的经验是，判断标准很简单——如果你的任务可以用一个Prompt加几个工具函数解决，就别上多Agent；如果任务涉及三个以上不同领域的知识，且这些知识之间有明确的先后依赖关系，那才考虑Harness架构。

具体到这个项目，它至少涉及四个垂直领域：Markdown文档处理、代码生成与审查、知识库管理（Obsidian）、以及Agent编排本身。这四个领域的知识几乎没有重叠，一个Agent不可能同时精通。所以拆成四个独立Agent，由Harness统一调度，是合理的架构决策。

但拆分的粒度也很讲究。拆得太细，Agent之间的通信开销会吃掉大部分性能；拆得太粗，又回到了单Agent的老问题。这个项目最终选择了“按领域拆分、按流程编排”的策略，每个Agent内部可以有自己的子流程，但对外只暴露一个统一的调用接口。这种设计在保持灵活性的同时控制了复杂度。

3. 核心模块的实操细节与避坑指南

3.1 Markdown处理管线的搭建要点

Markdown在这个项目里扮演的是“中间表示层”的角色。Agent生成的代码、文档、配置，全部先转成Markdown格式，然后再由下游模块消费。这样做的好处是Markdown的解析和生成都有成熟的库支持，而且人类可读，方便调试。

但Markdown处理有几个经典的坑。第一个是换行问题。不同平台对Markdown换行的处理不一致，有的把单个换行当空格，有的当新段落。在Agent生成内容时，如果不显式控制换行符，很容易出现格式错乱。我的做法是在Agent的输出模板里强制使用双换行表示段落分隔，单换行只在列表项内部使用。

第二个是表格转换。项目里经常需要把Markdown表格转成Excel或者从Excel转回来。这里推荐用Python的tabulate库做Markdown表格的解析，用openpyxl做Excel的读写。注意Markdown表格不支持合并单元格，如果你的数据有合并需求，要么在转换前拍平，要么在Excel侧做后处理。

第三个是数学公式。Markdown本身不支持数学公式，需要依赖LaTeX扩展。在Agent生成包含公式的内容时，要确保公式被$...$或$$...$$包裹，并且下游的渲染器支持MathJax或KaTeX。我踩过的坑是Agent有时候会把公式写成普通文本，导致渲染出来是一堆乱码。解决办法是在Agent的System Prompt里明确要求“所有数学表达式必须用LaTeX语法包裹”。

import re from tabulate import tabulate def markdown_table_to_list(md_text): """将Markdown表格转换为二维列表""" lines = [l for l in md_text.split('\n') if l.strip().startswith('|')] if len(lines) < 2: return [] # 跳过分隔行 data_lines = [lines[0]] + lines[2:] rows = [] for line in data_lines: cells = [c.strip() for c in line.strip('|').split('|')] rows.append(cells) return rows def list_to_markdown_table(data, headers=None): """将二维列表转换为Markdown表格""" return tabulate(data, headers=headers, tablefmt='pipe')

3.2 Agent编排引擎的设计与实现

编排引擎是整个Harness架构的心脏。它的核心职责有三个：任务路由、状态管理、错误处理。任务路由决定了一个请求应该发给哪个Agent；状态管理确保多轮对话中的上下文不丢失；错误处理保证单个Agent失败不会导致整个流程崩溃。

任务路由最简单的实现是基于规则的if-else，但这种方式在Agent数量超过五个之后会变得难以维护。更好的做法是用一个轻量级的分类器，可以是一个小模型，也可以是一组关键词匹配规则。这个项目用的是“关键词匹配加置信度打分”的方案：每个Agent注册自己的触发关键词和优先级，编排引擎根据输入内容计算每个Agent的匹配分数，选分数最高的执行。

状态管理是另一个容易出问题的地方。Agent之间的状态传递如果设计不好，会出现“上下文爆炸”——每个Agent都往上下文里塞东西，最后token全花在传递历史记录上了。我的建议是采用“最小必要状态”原则：每个Agent只接收完成当前任务所需的最小上下文，执行完毕后只返回结果，不返回中间过程。中间过程写到日志里，需要的时候再查。

错误处理方面，重试机制是必须的，但重试策略要分情况。对于网络超时这类瞬时错误，直接重试三次；对于参数错误这类逻辑错误，重试没有意义，应该直接返回错误信息让上游处理；对于模型输出格式错误，可以尝试用修正Prompt重新调用一次。

class HarnessEngine: def __init__(self): self.agents = {} self.state_store = {} def register_agent(self, name, agent, keywords, priority=0): self.agents[name] = { 'instance': agent, 'keywords': keywords, 'priority': priority } def route(self, user_input): scores = {} for name, config in self.agents.items(): score = sum(1 for kw in config['keywords'] if kw in user_input) score += config['priority'] if score > 0: scores[name] = score if not scores: return None return max(scores, key=scores.get) def execute(self, user_input, session_id): agent_name = self.route(user_input) if not agent_name: return {'error': 'No matching agent found'} agent = self.agents[agent_name]['instance'] context = self.state_store.get(session_id, {}) try: result = agent.run(user_input, context) self.state_store[session_id] = result.get('new_state', context) return result except Exception as e: return {'error': str(e), 'agent': agent_name}

3.3 Claude Code与DeepSeek Harness的协同使用

这个项目里同时用到了Claude Code和DeepSeek Harness，两者的定位不同。Claude Code主要负责代码生成和重构，它的优势在于对代码上下文的理解深度；DeepSeek Harness主要负责批量任务处理和流程编排，它的优势在于成本控制和并发能力。

协同使用的关键接口是文件系统。Claude Code生成的代码写到指定目录，DeepSeek Harness从目录里读取文件做后续处理。这种“文件系统作为消息队列”的模式看起来简陋，但实际用起来非常稳定，而且天然支持断点续传——如果某个环节失败了，重新跑的时候只需要处理未完成的文件。

配置Claude Code的时候有几个注意点。第一是工作目录要设置正确，否则它会在错误的位置生成文件。第二是权限控制，建议用只读模式挂载不需要修改的目录，避免Agent误操作。第三是超时设置，代码生成任务有时候会跑很久，默认超时时间可能不够，需要根据任务复杂度调整。

DeepSeek Harness这边，安装和配置相对简单，但要注意插件加载的顺序。如果插件之间有依赖关系，加载顺序错了会导致初始化失败。我遇到过一次harness failed to load plugins的错误，排查了半天发现是一个插件依赖的环境变量在另一个插件之后才设置。解决办法是在配置文件里显式声明插件依赖关系，让Harness按拓扑排序加载。

3.4 Obsidian作为知识库的集成方案

Obsidian在这个项目里承担的是“项目记忆”的角色。所有Agent产生的文档、决策记录、代码片段，最终都归档到Obsidian的Vault里。这样做的好处是知识可以累积，下次遇到类似问题时Agent可以直接检索历史记录，不需要重新推理。

集成Obsidian的核心是文件格式。Obsidian使用Markdown作为原生格式，这和项目的中间表示层天然兼容。但Obsidian有一些自己的扩展语法，比如[[双链]]、![[嵌入]]、> [!note]标注块等。在Agent生成内容时，需要决定是否使用这些扩展语法。我的建议是：内部知识库可以用扩展语法增强可读性，但对外输出的内容要用标准Markdown，避免兼容性问题。

从Zotero导入笔记到Obsidian是一个常见需求。Zotero导出的笔记通常是HTML或者Markdown格式，但格式和Obsidian的规范有差异。我写了一个转换脚本，核心逻辑是解析Zotero的导出文件，提取标题、作者、年份、标签等元数据，然后按照Obsidian的模板重新组织。注意Zotero的标签系统和Obsidian的标签系统不完全兼容，需要做映射。

import re from pathlib import Path def zotero_note_to_obsidian(zotero_md_path, output_dir): """将Zotero导出的Markdown笔记转换为Obsidian格式""" content = Path(zotero_md_path).read_text(encoding='utf-8') # 提取元数据 title_match = re.search(r'^# (.+)$', content, re.MULTILINE) title = title_match.group(1) if title_match else 'Untitled' # 提取标签 tags = re.findall(r'#(\w+)', content) tag_line = ' '.join(f'#{t}' for t in set(tags)) # 重组内容 body = re.sub(r'^# .+$', '', content, count=1, flags=re.MULTILINE) obsidian_content = f"""--- title: {title} tags: {tag_line} --- # {title} {body.strip()} """ output_path = Path(output_dir) / f"{title}.md" output_path.write_text(obsidian_content, encoding='utf-8') return str(output_path)

4. 大规模Agent项目的工程化管理

4.1 20万行代码怎么组织才不会失控

一个人维护20万行代码，听起来像是天方夜谭，但如果这20万行里有80%是Agent生成的，事情就变得可行了。关键在于建立一套“生成-审查-归档”的流水线，让人类只做决策和审核，不做重复劳动。

代码组织上，我强烈建议按功能域划分目录，而不是按技术分层。比如agents/目录下放所有Agent的实现，pipelines/目录下放编排流程，knowledge/目录下放知识库相关代码。每个目录内部再按具体功能分子目录。这种组织方式的好处是当你需要修改某个功能时，所有相关代码都在一个地方，不需要在多个层级之间跳转。

版本控制方面，Git是必须的，但提交策略要调整。Agent生成的代码建议单独提交，提交信息里标注是哪个Agent生成的、用了什么Prompt。这样出问题的时候可以快速定位是Prompt的问题还是Agent实现的问题。人工修改的代码单独提交，和Agent生成的代码区分开。

代码审查环节，我的做法是设置三道关卡：第一道是自动化检查，包括语法检查、类型检查、单元测试；第二道是Agent互审，用一个专门的审查Agent去检查生成代码的质量；第三道是人工抽查，每天随机抽取10%的生成代码做人工审核。这三道关卡下来，代码质量基本可控。

4.2 Token消耗的监控与优化

40亿token听起来很多，但如果不做监控，很容易在不知不觉中翻倍。我建议从第一天就建立Token消耗的监控体系，按Agent、按任务类型、按时间段三个维度统计消耗。

监控数据出来之后，优化方向就很清晰了。常见的优化手段包括：压缩Prompt长度（去掉冗余的示例和说明）、缓存重复的查询结果、用更小的模型处理简单任务、批量合并相似请求。这个项目里我印象最深的一个优化是：把Agent的System Prompt从2000token压缩到800token，整体消耗直接降了15%。

还有一个容易被忽视的优化点是输出格式。如果Agent的输出是给另一个Agent消费的，用JSON比用自然语言能省不少token。JSON的结构化特性让下游Agent不需要做复杂的解析，而且同样的信息量JSON通常比自然语言短。

4.3 并发处理与性能调优

Agent项目的并发处理和传统Web服务不太一样。传统服务的瓶颈通常在数据库或者网络IO，Agent项目的瓶颈在模型API的速率限制和上下文窗口大小。这两个瓶颈决定了你的并发策略。

速率限制方面，主流模型API都有RPM（每分钟请求数）和TPM（每分钟token数）的限制。做并发设计的时候，不能简单地开一堆线程去调API，那样只会触发限流。正确的做法是实现一个令牌桶或者漏桶算法，控制请求的发送速率。同时要做好退避重试，遇到429错误的时候指数级增加等待时间。

上下文窗口方面，每个Agent调用都有窗口大小限制。如果你的任务需要处理很长的文档，要么分段处理，要么用RAG（检索增强生成）的方式只取相关片段。这个项目里处理长文档的策略是“分块加摘要”：先把文档切成固定大小的块，每块生成摘要，最后把所有摘要合并成全局摘要。这样既控制了单次调用的token量，又保留了文档的整体信息。

import time import threading from collections import deque class RateLimiter: def __init__(self, max_requests_per_minute): self.max_rpm = max_requests_per_minute self.requests = deque() self.lock = threading.Lock() def acquire(self): with self.lock: now = time.time() # 清理一分钟前的记录 while self.requests and self.requests[0] < now - 60: self.requests.popleft() if len(self.requests) >= self.max_rpm: wait_time = 60 - (now - self.requests[0]) if wait_time > 0: time.sleep(wait_time) self.requests.append(time.time())

4.4 错误恢复与断点续传

大规模Agent项目最怕的就是跑到一半挂了，然后要从头开始。断点续传机制是必须的，核心思路是把每个任务的执行状态持久化到磁盘或者数据库，重启的时候从上次中断的地方继续。

实现断点续传的关键是任务ID的设计。每个任务要有唯一的ID，这个ID要能标识任务的输入、配置和版本。任务执行过程中，每完成一个步骤就把状态写到一个checkpoint文件里。重启的时候先读checkpoint，跳过已完成的步骤。

错误恢复策略要分级别。对于可重试的错误（网络超时、限流），自动重试；对于需要人工干预的错误（参数错误、逻辑错误），记录到错误队列，等人工处理后再重新入队；对于不可恢复的错误（数据损坏、依赖缺失），直接标记任务失败，通知相关人员。

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

5.1 Agent输出格式不稳定的处理

这是Agent开发中最常见的问题。同一个Prompt，有时候输出JSON，有时候输出Markdown，有时候还夹杂着解释性文字。解决这个问题有三个层次的手段。

第一层是在Prompt里明确格式要求，并且给出示例。示例要尽可能具体，包括字段名、数据类型、嵌套结构。第二层是在Agent输出之后加一个格式校验和修正的步骤，用正则表达式或者JSON解析器去提取有效内容。第三层是在编排引擎里做容错，如果Agent输出无法解析，就触发一次“格式修正”调用，让模型重新输出。

我的经验是三层都要做，但重点放在第一层。一个好的Prompt能减少80%的格式问题。另外，用JSON Schema来约束输出格式比用自然语言描述更有效，因为模型对结构化约束的遵循度更高。

5.2 上下文丢失与状态管理故障

多轮对话中上下文丢失是另一个高频问题。表现是Agent在第二轮对话中忘记了第一轮的信息，或者把不同会话的状态搞混了。根因通常是状态存储的键设计有问题，或者状态更新时没有做并发控制。

排查这类问题的第一步是检查session_id的生成逻辑。session_id必须全局唯一，且在整个会话期间保持不变。如果session_id是基于时间戳生成的，要确保精度足够，不会出现碰撞。第二步是检查状态存储的读写是否原子化。多个Agent同时读写同一个session的状态时，如果没有加锁，会出现覆盖写的问题。

我的做法是用Redis做状态存储，利用它的原子操作和过期机制。每个session的状态设置一个合理的TTL（比如24小时），避免状态无限累积。同时用Redis的WATCH/MULTI命令做乐观锁，确保状态更新的原子性。

5.3 插件加载失败与依赖冲突

harness failed to load plugins这个错误在Harness架构的项目里很常见。根因通常是插件之间的依赖关系没有正确声明，或者某个插件依赖的环境变量没有设置。

排查步骤是这样的：先看错误日志，确定是哪个插件加载失败；然后检查这个插件的依赖列表，逐个确认依赖是否满足；最后检查环境变量和配置文件，确保所有必需的配置项都有值。如果依赖关系复杂，建议画一张依赖图，用拓扑排序确定加载顺序。

预防措施是在项目初期就建立插件的依赖管理规范。每个插件都要有一个manifest文件，声明自己的名称、版本、依赖列表、配置项。Harness启动时先读取所有manifest，构建依赖图，按拓扑排序加载。这样即使插件数量增加，也不会出现加载顺序问题。

5.4 模型API调用超时与限流

API超时和限流是生产环境中最常见的两类错误。超时通常是网络问题或者模型负载高，限流则是触发了API的速率限制。

对于超时，首先要区分是连接超时还是读取超时。连接超时通常是网络问题，检查网络配置和DNS解析；读取超时是模型处理时间过长，可以尝试减小输入长度或者换用更快的模型。重试策略上，连接超时可以直接重试，读取超时建议先减小输入再重试。

对于限流，关键是做好请求队列和退避。不要一遇到429就立即重试，那样只会加剧限流。正确的做法是实现指数退避，第一次等1秒，第二次等2秒，第三次等4秒，以此类推。同时要在客户端做请求合并，把多个小请求合并成一个大请求，减少请求数量。

5.5 代码生成质量波动的应对

Agent生成的代码质量不稳定是另一个让人头疼的问题。同一个需求，有时候生成的代码可以直接用，有时候需要大改。影响代码质量的因素很多：Prompt的清晰度、模型的版本、上下文的长度、甚至调用的时间。

我的应对策略是建立一套“生成-评估-筛选”的流水线。每个代码生成任务跑三次，用不同的温度参数（比如0.2、0.5、0.8），然后用一个评估Agent给三份代码打分，选分数最高的。这样虽然增加了token消耗，但代码可用率能提升不少。

另外，给Agent提供更多的上下文也能提升代码质量。比如在生成某个函数的代码时，把相关的类型定义、接口文档、调用示例都放到Prompt里。上下文越丰富，模型生成的代码越贴合项目规范。

6. 从项目里提炼的可复用经验

6.1 一个人做大项目的节奏控制

九个月20万行代码，平均每天700多行。这个节奏不是靠加班堆出来的，而是靠合理的任务拆分和自动化流水线。我的经验是把大目标拆成周目标，周目标拆成日目标，日目标拆成具体的Agent调用任务。每天早上花半小时规划当天的任务，然后让Agent去执行，自己只做审核和决策。

节奏控制的关键是“留缓冲”。不要把所有时间排满，每天留出两小时处理意外情况。Agent项目的不确定性很高，今天可能一切顺利，明天可能遇到一个诡异的问题卡一整天。有缓冲时间，心态就不会崩。

6.2 工具链的选型原则

这个项目里用到的工具很多：Claude Code、DeepSeek Harness、Obsidian、Typora、VS Code等等。选型的原则是“成熟优先、接口开放、社区活跃”。不要为了尝鲜去用刚发布的工具，除非你有能力自己修bug。

具体来说，Markdown编辑器选Typora是因为它的渲染效果最接近最终输出；知识库选Obsidian是因为它的文件格式开放，不会被锁定；代码编辑器选VS Code是因为它的插件生态最丰富。每个工具都要有替代方案，万一某个工具出问题了可以快速切换。

6.3 知识管理的长期价值

项目过程中产生的文档、决策记录、代码片段，如果不好好管理，项目结束后就变成了一堆垃圾。Obsidian的价值在于它把这些零散的信息组织成了可检索、可关联的知识网络。

我的做法是每完成一个模块就写一篇总结笔记，记录这个模块的设计思路、遇到的问题、解决方案。笔记之间用双链关联，形成知识图谱。项目结束后，这些笔记就是最好的技术资产，下次做类似项目的时候可以直接复用。

6.4 成本控制的实战技巧

40亿token听起来很多，但通过合理的优化，实际成本可以控制在很低的水平。除了前面提到的Prompt压缩、结果缓存、模型降级之外，还有一个技巧是“错峰调用”。很多模型API在凌晨时段的费率更低，把批量处理任务安排在凌晨跑，能省不少钱。

另一个技巧是“分级处理”。不是所有任务都需要用最强的模型，简单的分类、提取任务用便宜的小模型就够了。只有复杂的推理、生成任务才用大模型。这个项目里大概70%的调用用的是小模型，只有30%用大模型，整体成本降了一半以上。

6.5 后续扩展的方向

这个项目的架构设计留了不少扩展空间。比如可以增加更多的Agent来覆盖新的领域，可以接入更多的模型来提升效果，可以把编排引擎做成分布式的来提升吞吐量。但扩展的前提是核心架构足够稳定，不要为了扩展而扩展。

我个人觉得最有价值的扩展方向是“Agent的自我进化”。让Agent根据历史执行记录自动调整Prompt和参数，逐步提升执行效果。这个方向目前还在探索阶段，但已经有一些初步的实践案例，效果还不错。