企业官网建设流程全解析

这次我们来看一个面向开发者的智能体（Agent）定制化实战项目。核心围绕Pi Agent和Harness Agent这两个概念展开，重点不是空谈理论，而是如何从零开始，构建一个能实际运行、具备特定技能的智能体。如果你关心如何将大型语言模型（LLM）的能力封装成可复用的、可编排的智能体，并集成到自己的开发流程或产品中，这篇文章会提供一套清晰的实践路径。

简单来说，Pi Agent可以被理解为一个基于特定框架或平台（如 Claude Code、Cursor 等）的智能体实例或开发范式，而Harness则代表了对智能体进行“驾驭”和工程化管理的工具或方法论。本文的目标是拆解从 Prompt 工程到企业级 Agent 工程的完整演进过程，通过实战演示如何定义技能（Skills）、管理扩展（Extensions），并最终打造一个稳定可靠的定制化智能体。

对于开发者而言，最值得关注的几个点是：第一，整个过程严重依赖TypeScript/JavaScript生态，这是现代 AI 应用开发的主流选择；第二，智能体的能力通过Skills和Extensions来模块化扩展，类似于给一个基础模型安装“插件”；第三，整个流程可以本地运行，对硬件几乎没有特殊门槛，重点在于代码组织和工程实践。本文将带你完成环境搭建、Skill 开发、Harness 配置、测试验证到集成部署的全流程，并提供常见问题的排查思路。

1. 核心能力速览

在深入细节之前，我们先通过一个表格快速了解本实战项目涉及的核心要素、技术栈和资源要求，让你对整体有个把握。

2. 适用场景与使用边界

在投入时间进行定制开发前，明确它能做什么、不能做什么至关重要。

这个工具最适合谁？

• 全栈或前端开发者：熟悉 TypeScript/Node.js 生态，希望深度定制 AI 编程助手。
• 技术团队负责人：需要为团队构建标准化、可复用的 AI 能力模块，提升开发效率。
• AI 应用开发者：不满足于简单的聊天交互，希望构建具备复杂工作流和持久状态的智能体。

它能解决什么问题？

1. 提示词工程固化：将那些需要反复调试、多轮交互的复杂 Prompt，封装成开箱即用的 Skill，降低使用门槛。
2. 能力模块化与复用：将代码审查、文档生成、数据库查询等能力拆分为独立的 Skills，可以在不同智能体间组合使用。
3. 与企业流程集成：通过 Harness 配置智能体的权限、知识库和工具集，让其符合企业内部规范和安全要求。
4. 提升开发体验：通过 IDE 扩展，将智能体深度集成到编码环境中，实现上下文感知的代码建议和自动化操作。

不适合什么场景？

• 追求零代码/可视化配置：本实践涉及代码开发，需要一定的编程基础。
• 需要极高并发或低延迟：基于 LLM API 的智能体受网络和 API 速率限制影响，不适合实时性要求极高的场景。
• 替代基础模型训练：这是应用层开发，不涉及模型微调或训练。

安全与合规边界

• 代码与数据安全：智能体可能访问项目代码、文件系统甚至外部 API。必须严格配置其可访问范围，避免敏感信息泄露。
• API 密钥管理：LLM API 密钥是核心资产，严禁硬编码在代码中。必须使用环境变量或安全的密钥管理服务。
• 生成内容审核：对于自动生成的代码、文档等内容，应建立人工复核机制，尤其是用于生产环境时。
• 版权与许可：确保智能体生成代码时使用的依赖、库的许可证符合项目要求。

3. 环境准备与前置条件

开始实战之前，请确保你的本地开发环境满足以下要求。这是一个标准的 Node.js 全栈开发环境配置。

操作系统

• 推荐: macOS, Linux (Ubuntu/Debian), 或 Windows 10/11 (建议使用 WSL2 以获得最佳体验)。
• 本教程的命令以 Unix-like 系统（macOS/Linux/WSL）为例，Windows PowerShell 可能有细微差别。

核心运行时与工具

1. Node.js: 版本18.x或20.xLTS。这是运行 TypeScript 代码和各类工具链的基础。

   node --version # 检查版本

2. npm或yarn或pnpm: 包管理器。推荐使用pnpm或npm。

   npm --version # 或 pnpm --version

3. TypeScript: 通常作为项目依赖安装，但也可全局安装以便使用tsc命令。

   npm install -g typescript tsc --version

4. Git: 用于版本控制和克隆示例项目。

IDE 与扩展 (可选但推荐)

• Visual Studio Code: 首选 IDE。
• 推荐 VSCode 扩展:
  • TypeScript和JavaScript语言支持（内置）。
  • ESLint(代码检查)。
  • Prettier(代码格式化)。
  • 如果开发 VSCode 扩展，需要安装@vscode/vsce(Visual Studio Code Extension Manager)。

LLM API 访问权限

• 你需要一个可用的 LLM API 服务账号和密钥，例如：
  • OpenAI API(GPT-4, GPT-3.5-Turbo)
  • Anthropic Claude API
  • 其他兼容 OpenAI API 格式的服务(如本地部署的模型服务)
• 将 API Key 设置为环境变量，切勿提交到代码仓库。

  # 在 shell 配置文件 (.bashrc, .zshrc) 中设置 export OPENAI_API_KEY='your-api-key-here' # 或 export ANTHROPIC_API_KEY='your-api-key-here'

项目目录结构准备建议创建一个清晰的项目目录，用于管理代码、配置和测试文件。

mkdir pi-agent-harness-demo && cd pi-agent-harness-demo mkdir -p src/skills src/tools config tests

4. 安装部署与启动方式

由于“Pi Agent”和“Harness Agent”可能指代不同的具体实现，这里我们以一个概念性的、基于 TypeScript 和常见 AI SDK 的智能体项目结构为例，展示通用的安装和启动模式。你可以将此结构适配到具体的框架（如 LangChain、LlamaIndex、或自定义框架）。

步骤 1：初始化项目并安装核心依赖

# 初始化 package.json npm init -y # 安装 TypeScript 和类型定义 npm install -D typescript @types/node ts-node nodemon # 初始化 tsconfig.json npx tsc --init # 根据提示调整配置，通常需要设置 "target": "ES2020", "module": "commonjs", "outDir": "./dist" # 安装 AI SDK 和工具库 (以 OpenAI SDK 和 LangChain 为例) npm install openai langchain @langchain/core # 如果使用 Anthropic # npm install @anthropic-ai/sdk # 安装辅助工具库 npm install dotenv axios commander

步骤 2：创建基础项目结构

pi-agent-harness-demo/ ├── package.json ├── tsconfig.json ├── .env # 环境变量文件 (需加入 .gitignore) ├── .gitignore ├── src/ │ ├── index.ts # 主入口文件 │ ├── agent/ │ │ ├── harness.ts # Harness 配置与逻辑 │ │ └── pi-agent.ts # Pi Agent 核心类 │ ├── skills/ # 技能模块目录 │ │ ├── index.ts # 技能注册出口 │ │ ├── fileSkill.ts # 示例：文件操作技能 │ │ └── codeSkill.ts # 示例：代码分析技能 │ └── tools/ # 工具函数目录 ├── config/ │ └── default.json # 配置文件 ├── tests/ # 测试文件 └── scripts/ # 启动脚本

步骤 3：编写智能体核心与 Harness 逻辑src/agent/pi-agent.ts(简化示例):

import { OpenAI } from 'openai'; import { BaseSkill } from '../skills/index'; export class PiAgent { private openai: OpenAI; private skills: Map<string, BaseSkill> = new Map(); private context: any = {}; constructor(apiKey: string) { this.openai = new OpenAI({ apiKey }); } registerSkill(skill: BaseSkill) { this.skills.set(skill.name, skill); } async process(input: string): Promise<string> { // 1. 意图识别：判断用户输入需要哪个Skill处理 const intent = await this.detectIntent(input); // 2. 如果有匹配的Skill，则执行 if (this.skills.has(intent)) { const skill = this.skills.get(intent)!; return await skill.execute(input, this.context); } // 3. 否则，交给通用LLM处理 return await this.callLLM(input); } private async detectIntent(input: string): Promise<string> { // 简化版意图识别，实际可使用更复杂的NLU逻辑 const prompt = `分析用户输入"${input}"，判断其意图。可选意图：read_file, write_file, analyze_code, general_query。只返回意图名称。`; const response = await this.openai.chat.completions.create({ model: 'gpt-3.5-turbo', messages: [{ role: 'user', content: prompt }], temperature: 0.1, }); return response.choices[0]?.message?.content?.trim() || 'general_query'; } private async callLLM(input: string): Promise<string> { const response = await this.openai.chat.completions.create({ model: 'gpt-4', messages: [{ role: 'user', content: input }], }); return response.choices[0]?.message?.content || ''; } }

src/agent/harness.ts(Harness 配置示例):

import { PiAgent } from './pi-agent'; import * as skills from '../skills/index'; export class AgentHarness { private agent: PiAgent; constructor(apiKey: string) { this.agent = new PiAgent(apiKey); this.setupSkills(); this.applyConstraints(); } private setupSkills() { // 注册所有技能 this.agent.registerSkill(new skills.FileReadSkill()); this.agent.registerSkill(new skills.CodeAnalysisSkill()); // ... 注册更多技能 } private applyConstraints() { // 应用安全约束和行为规则 // 例如：限制文件系统访问路径、设置最大Token数、过滤敏感词等 console.log('[Harness] 安全与行为约束已加载。'); } getAgent(): PiAgent { return this.agent; } // 可以添加监控、日志、限流等中间件功能 async runWithMonitoring(input: string): Promise<string> { console.log(`[Harness] 处理请求: ${input.substring(0, 50)}...`); const startTime = Date.now(); try { const result = await this.agent.process(input); const duration = Date.now() - startTime; console.log(`[Harness] 请求处理成功，耗时 ${duration}ms`); return result; } catch (error) { console.error(`[Harness] 请求处理失败:`, error); return '抱歉，处理您的请求时出现了问题。'; } } }

步骤 4：创建并启动主服务src/index.ts:

import 'dotenv/config'; import { AgentHarness } from './agent/harness'; import * as readline from 'readline'; async function main() { const apiKey = process.env.OPENAI_API_KEY; if (!apiKey) { console.error('错误：请设置 OPENAI_API_KEY 环境变量。'); process.exit(1); } const harness = new AgentHarness(apiKey); console.log('Pi Agent with Harness 已启动。输入文本进行交互，输入 `exit` 退出。'); const rl = readline.createInterface({ input: process.stdin, output: process.stdout, }); rl.on('line', async (input) => { if (input.toLowerCase() === 'exit') { rl.close(); return; } const response = await harness.runWithMonitoring(input); console.log('\nAgent:', response, '\n'); }); } main().catch(console.error);

步骤 5：配置启动脚本在package.json中添加：

{ "scripts": { "start": "ts-node src/index.ts", "dev": "nodemon --exec ts-node src/index.ts", "build": "tsc", "serve": "node dist/index.js" } }

步骤 6：启动智能体交互服务

# 确保已设置 API Key export OPENAI_API_KEY='your-key' # 开发模式启动（使用 ts-node，支持热更新） npm run dev # 或者构建后运行 npm run build npm run serve

启动后，你将在命令行中看到一个交互式界面，可以直接输入自然语言指令与你的定制智能体进行交互。

5. 功能测试与效果验证

智能体搭建好后，需要通过一系列测试来验证其核心功能是否按预期工作。我们从 Skill 单元测试到集成测试逐步进行。

5.1 Skill 单元测试：验证原子化能力

首先，为每个 Skill 编写独立的测试。以FileReadSkill为例：tests/skills/fileSkill.test.ts:

import { FileReadSkill } from '../../src/skills/fileSkill'; import fs from 'fs/promises'; import path from 'path'; describe('FileReadSkill', () => { const skill = new FileReadSkill(); const testDir = path.join(__dirname, 'test-data'); const testFile = path.join(testDir, 'hello.txt'); beforeAll(async () => { await fs.mkdir(testDir, { recursive: true }); await fs.writeFile(testFile, 'Hello, World!', 'utf-8'); }); afterAll(async () => { await fs.rm(testDir, { recursive: true, force: true }); }); it('应该能正确识别读取文件的意图', async () => { const canHandle = await skill.canHandle('请读取 /tmp/test.txt 文件的内容'); expect(canHandle).toBe(true); }); it('应该能执行文件读取并返回内容', async () => { const result = await skill.execute(`读取文件 ${testFile}`, {}); expect(result).toContain('Hello, World!'); }); it('对于不存在的文件应返回友好错误', async () => { const result = await skill.execute('读取文件 /nonexistent/path.txt', {}); expect(result).toContain('无法读取'); expect(result).toContain('不存在'); }); });

运行测试：

# 假设使用 Jest npx jest tests/skills/fileSkill.test.ts

5.2 意图识别测试：验证路由准确性

测试 Harness 和 Agent 能否正确将用户输入路由到对应的 Skill。tests/agent/intent.test.ts:

import { PiAgent } from '../../src/agent/pi-agent'; import { FileReadSkill } from '../../src/skills/fileSkill'; describe('Intent Detection', () => { let agent: PiAgent; beforeEach(() => { // 使用模拟的 API Key，实际测试中可能使用 Mock agent = new PiAgent('test-key'); agent.registerSkill(new FileReadSkill()); }); it('应将文件读取请求路由到 FileReadSkill', async () => { // 这里需要模拟或拦截 agent.detectIntent 方法，使其返回 'read_file' // 然后验证 agent.process 最终调用了 skill.execute // 具体实现依赖你的测试框架和 Mock 策略 }); });

5.3 端到端集成测试：模拟真实用户场景

创建一个简单的测试脚本，模拟用户与智能体的完整对话。tests/integration/cli-test.js(可以用更简单的 JS 快速验证):

// 这是一个使用构建后产物的简单集成测试 const { exec } = require('child_process'); const path = require('path'); const agentScript = path.join(__dirname, '../../dist/index.js'); // 注意：这是一个概念性示例，实际需要更复杂的进程通信来测试 CLI console.log('启动集成测试...'); // 可以通过 spawn 子进程，向其 stdin 写入指令，并从 stdout 读取结果来验证

5.4 效果验证清单

完成开发和测试后，对照以下清单验证你的智能体：

• [ ]基础对话：输入普通问题，智能体能调用 LLM 返回合理回答。
• [ ]Skill 触发：输入 Skill 相关的指令（如“读取 src/index.ts 文件”），智能体能正确识别并执行对应 Skill。
• [ ]错误处理：输入非法指令或访问不存在的路径，智能体能返回友好的错误信息，而不是崩溃或暴露内部堆栈。
• [ ]上下文管理：在多轮对话中，智能体能否保持上下文连贯（例如，上一轮说“查看项目结构”，下一轮说“打开第一个文件”）。
• [ ]资源清理：Skill 执行后，是否妥善关闭了文件句柄、数据库连接等资源。
• [ ]性能基线：记录典型请求的响应时间，建立性能基线，用于后续优化对比。

6. 接口 API 与批量任务

将智能体封装成 API 服务，是将其能力提供给其他应用的关键。同时，很多场景需要处理批量任务。

6.1 封装为 HTTP API 服务

使用 Express.js 快速创建一个 API 服务器。src/api/server.ts:

import express from 'express'; import { AgentHarness } from '../agent/harness'; import 'dotenv/config'; const app = express(); const port = process.env.PORT || 3000; app.use(express.json()); // 初始化 Harness (单例，避免重复初始化) let harness: AgentHarness | null = null; function getHarness(): AgentHarness { if (!harness) { const apiKey = process.env.OPENAI_API_KEY; if (!apiKey) throw new Error('API Key not configured'); harness = new AgentHarness(apiKey); } return harness; } // 健康检查端点 app.get('/health', (req, res) => { res.json({ status: 'ok', service: 'pi-agent-api' }); }); // 核心处理端点 app.post('/v1/process', async (req, res) => { try { const { message, session_id: sessionId, options } = req.body; if (!message || typeof message !== 'string') { return res.status(400).json({ error: 'Invalid request: `message` field is required and must be a string.' }); } const agentHarness = getHarness(); // 这里可以将会话ID用于上下文管理 const response = await agentHarness.runWithMonitoring(message); res.json({ response, session_id: sessionId, timestamp: new Date().toISOString(), }); } catch (error) { console.error('API Error:', error); res.status(500).json({ error: 'Internal server error processing your request.' }); } }); // 启动服务器 app.listen(port, () => { console.log(`Pi Agent API server listening on port ${port}`); });

在package.json中添加脚本：

{ "scripts": { "api": "ts-node src/api/server.ts" } }

启动 API 服务：

npm run api # 服务将在 http://localhost:3000 启动

使用curl进行测试：

curl -X POST http://localhost:3000/v1/process \ -H "Content-Type: application/json" \ -d '{"message": "请总结当前目录下所有 .ts 文件的数量", "session_id": "test-123"}'

6.2 批量任务处理

对于需要处理大量独立任务的场景（如批量代码审查、文档生成），可以设计一个任务队列。

简单文件批处理示例scripts/batch-process.js:

const fs = require('fs').promises; const path = require('path'); const { AgentHarness } = require('../dist/agent/harness'); // 假设已构建 async function processFileBatch(inputDir, outputDir) { const harness = new AgentHarness(process.env.OPENAI_API_KEY); const files = await fs.readdir(inputDir); const txtFiles = files.filter(f => f.endsWith('.txt')); const results = []; for (const file of txtFiles) { const inputPath = path.join(inputDir, file); const content = await fs.readFile(inputPath, 'utf-8'); // 构建一个处理请求，例如“总结以下内容” const prompt = `请用一句话总结以下文本的核心内容：\n\n${content}`; try { console.log(`处理文件: ${file}`); const summary = await harness.runWithMonitoring(prompt); const outputPath = path.join(outputDir, `${path.basename(file, '.txt')}_summary.txt`); await fs.writeFile(outputPath, summary, 'utf-8'); results.push({ file, status: 'success', outputPath }); } catch (error) { console.error(`处理文件 ${file} 失败:`, error.message); results.push({ file, status: 'failed', error: error.message }); } // 避免速率限制，简单延迟 await new Promise(resolve => setTimeout(resolve, 500)); } // 保存处理报告 const reportPath = path.join(outputDir, `batch_report_${Date.now()}.json`); await fs.writeFile(reportPath, JSON.stringify(results, null, 2), 'utf-8'); console.log(`批量处理完成。报告已保存至: ${reportPath}`); } // 使用示例 if (require.main === module) { const inputDir = process.argv[2] || './input'; const outputDir = process.argv[3] || './output'; processFileBatch(inputDir, outputDir).catch(console.error); }

运行批量任务：

node scripts/batch-process.js ./data/inputs ./data/outputs

关键设计考虑：

1. 错误处理与重试：批量任务中个别失败不应导致整体中断。需要记录失败项并可能实现重试逻辑。
2. 速率限制：调用外部 LLM API 时，必须遵守其速率限制。可以在循环中添加延迟或使用令牌桶算法。
3. 进度与状态持久化：对于长时间运行的批量任务，应将进度保存到文件或数据库，以便中断后可以恢复。
4. 资源管理：避免同时发起过多请求，导致内存或网络连接耗尽。

7. 资源占用与性能观察

虽然基于 API 的智能体对本地硬件要求不高，但其性能和资源使用模式仍有观察价值，尤其是在处理批量任务或作为常驻服务时。

观察维度与方法：

1. 内存占用：

   • 使用process.memoryUsage()在关键节点打印内存信息。
   • 对于长时间运行的服务，监控其内存增长趋势，防止内存泄漏。

   setInterval(() => { const usage = process.memoryUsage(); console.log(`内存使用: RSS=${Math.round(usage.rss / 1024 / 1024)}MB, HeapTotal=${Math.round(usage.heapTotal / 1024 / 1024)}MB, HeapUsed=${Math.round(usage.heapUsed / 1024 / 1024)}MB`); }, 60000); // 每分钟记录一次

2. API 调用延迟与成本：

   • 记录每个请求从发起到收到响应的耗时。
   • 估算 Token 使用量，关联 API 调用成本。OpenAI 等 SDK 的响应中通常包含usage字段。

   const start = Date.now(); const completion = await openai.chat.completions.create({...}); const end = Date.now(); console.log(`请求耗时: ${end - start}ms, Token 消耗: prompt=${completion.usage?.prompt_tokens}, completion=${completion.usage?.completion_tokens}`);

3. 并发处理能力：

   • 测试 API 服务在并发请求下的表现。可以使用autocannon或artillery进行压力测试。
   • 注意：如果后端 LLM API 有严格的 RPM（每分钟请求数）限制，本地并发测试需谨慎。

   # 使用 autocannon 进行简单压测 npx autocannon -c 10 -d 30 http://localhost:3000/v1/process

4. Skill 执行效率：

   • 为每个 Skill 的execute方法添加性能计时，识别性能瓶颈是在 LLM 调用还是在本地操作（如文件 I/O、数据库查询）。

性能优化建议：

• 缓存：对频繁查询且结果稳定的内容（如项目结构解析、文档摘要）进行缓存。
• 异步与非阻塞：确保所有 I/O 操作（文件、网络）使用异步模式，避免阻塞事件循环。
• 连接池与复用：对于数据库或外部服务连接，使用连接池。
• 流式响应：对于生成长文本的场景，如果 LLM API 支持，考虑使用流式响应（Server-Sent Events）来提升用户体验。

8. 常见问题与排查方法

在开发和运行过程中，你可能会遇到以下问题。这里提供排查思路和解决方案。

9. 最佳实践与使用建议

基于上述实战，总结出以下最佳实践，帮助你构建更稳健、可维护的智能体系统。

1. Skill 设计原则

   • 单一职责：每个 Skill 只做一件事，并把它做好。例如，一个 Skill 负责读文件，另一个负责写文件。
   • 明确接口：定义清晰的 Skill 接口（如canHandle(input): boolean和execute(input, context): Promise<string>），便于统一管理和扩展。
   • 依赖注入：Skill 所需的工具（如文件系统操作、数据库客户端）应通过构造函数注入，而不是在内部硬编码，这有利于测试和替换。

2. Harness 作为控制层

   • 集中配置：将所有智能体的行为配置（如允许访问的路径、最大 Token 数、可用工具列表）放在 Harness 中管理。
   • 中间件管道：在 Harness 中实现中间件（Middleware）管道，用于处理日志、监控、权限检查、速率限制等横切关注点。
   • 上下文管理：由 Harness 统一管理对话上下文，实现上下文窗口的滑动、总结或持久化。

3. 配置与密钥管理

   • 环境变量：所有敏感信息（API Keys、数据库连接串）必须通过环境变量传入。
   • 配置文件：将非敏感的配置（如默认模型、超时时间、技能开关）放在 JSON 或 YAML 配置文件中。
   • 配置验证：启动时验证关键配置是否存在且有效，避免运行时才报错。

4. 测试策略

   • 单元测试：为每个 Skill 和工具函数编写单元测试，确保其逻辑正确。
   • 集成测试：测试多个 Skill 与 Harness、Agent 的协同工作。
   • 端到端测试：模拟真实用户场景，测试从 API 入口到最终输出的完整流程。
   • Mock LLM 调用：在测试中，使用jest.mock或类似工具模拟 LLM API 调用，保证测试的稳定性和速度。

5. 部署与运维

   • 进程管理：对于长期运行的服务，使用pm2、systemd或 Docker 容器来管理进程，实现自动重启和日志轮转。
   • 健康检查：API 服务必须提供/health等健康检查端点，便于容器编排平台（如 Kubernetes）进行探活。
   • 日志结构化：使用winston或pino等日志库，输出结构化的 JSON 日志，便于使用 ELK 或 Loki 等工具进行收集和分析。

6. 安全与合规

   • 输入验证与清理：对所有用户输入进行验证和清理，防止注入攻击。
   • 输出过滤：对 LLM 生成的内容进行必要的过滤和审核，避免输出不当内容。
   • 访问控制：如果 API 对外公开，必须实施身份验证和授权机制（如 API Key、JWT）。
   • 数据隐私：明确告知用户数据如何被使用，避免在 Prompt 中泄露用户隐私信息。对于企业数据，考虑使用本地化模型或具有数据保护协议的 API 服务。

遵循这些实践，你的 Pi Agent 项目将从一个实验性脚本，演进为一个可维护、可扩展、安全可靠的企业级智能体工程应用。