系列目录：

1. 这篇文章：不用框架，手搓 AI Agent：先让它跑起来
2. 不用 LangChain。手搓 AI Agent：给大模型装上“手”，让它自己读项目文件
3. 原来 AI Agent 的主要循环这么简单：手搓一个 Agent Loop
4. 更多实战持续更新中…，老实说，

先来“放个毒”，看看经过本系列的打磨。我们最终会亲手搞出一个怎样的“完全体”

如上图所示，它将拥有类似 Claude Code 的终端交互、能感知当前工作目录，还能自主决定如何帮你完成研发任务。

是不是感觉很酷？

但这些能力并不是模型天生就有的。模型本身只负责理解需求、思考接下来；至于如何进入你的工作目录、调用终端、读写文件、输入命令，并在失败后继续尝试。靠的是另一套运行方式——Harness。

Harness 直译过来是 “马具” 或者 “缰绳”。在 AI 工程里这个比喻非常形象：

• 大模型就像一匹能力很强的马：动力十足、创意丰富，但有时候也比较 “冲动”。如果没有约束，它写代码时可能会乱用依赖、执行危险命令。甚至产生幻觉，接下来一本正经地胡说八道。
• Harness 就像套在马身上的缰绳：负责约束和引导大模型。把模型的想法转化成可执行的工程步骤，确保它既能跑起来也不至于跑偏。

举个最简单的例子。怎么说呢，

当你对 Claude Code 或 Codex 说：“帮我修复这个项目里的登录 Bug”。背后的大模型并不能凭空读取你的代码，也不能直接修改文件。真正让它拥有这些能力的是 Harness 为它提供的：

• 读取文件
• 搜索代码
• 修改代码
• 输入命令
• 检查运行结果
• 限制危险操作
• 在失败后继续调整方案

Pain Point： 很多开发者卡在“模型只能聊天”，却找不到把聊天转化为实际操作的方法。没有 Harness，大模型只能是一个会出主意的大脑；接上 Harness，它才能真正读代码、改文件、输入命令。成为能够帮我们完成任务的 AI Agent。 话说回来，

至于今天的目标。先让它跑起来

罗马不是一天建成的。我们把高级能力先放一边，任何强大的 AI Agent 都有一个极其朴素的起点——最短链路的一问一答。

本系列第一篇，我们亲手敲下第一行主要代码，让“一问一答”最小可用版本跑起来：

$ npm run start -- -prompt "用一句话解释什么是 TypeScript"
AI的观点是。TypeScript 是 JavaScript 的超集，为 JavaScript 添加了静态类型能力。

一、准备环境

• Node.js 21 或更高版本
• npm
• A OpenAI‑compatible API Key： 这是通向各大模型的“万能通行证”。无论 DeepSeek、GLM、Kimi。只要兼容 OpenAI 协议，都可以使用同一套密钥。

Pain Point：很多人因为 Node/TS 环境不匹配而卡在安装阶段。先确认版本再继续：

node -v
# 推荐>= v21

二、新建一个独立项目

mkdir powercode
cd powercode
npm init -y
npm install openai
npm install -D typescript @types/node

The directory now looks like:

powercode/
├── node_modules/
├── package.json
└── package-lock.json

三、配置 TypeScript 编译器

{
"compilerOptions": {
"target": "ES2022","module": "NodeNext","moduleResolution": "NodeNext"。"rootDir": "src","outDir": "dist","strict": true,"skipLibCheck": true
},"include":
}

Edit package.json,add module type and scripts:

{
"name"的观点是，"powercode","version": "0.1.0","private": true,"type": "module","scripts": {
"build": "tsc","start": "node dist/main.js"
},"dependencies": {
"openai": "^4.0.0"
},"devDependencies": {
"@types/node": "^20.0.0","typescript": "^5.0.0"
}
}

Pain Point：忘记添加 `"type":"module"` 会导致 `import` 报错，这里提醒一下。

四、配置你的大模型

{
"protocol": "openai",// 保持不变，即使换厂商也仍是 openai 协议
// 以下三个字段根据实际服务替换：
// baseURL = 接口地址
// apiKey = 私人密钥
// model = 模型名称，例如 deepseek-v4-flash
// 示例：
// baseURL: https://api.deepseek.com
}
{
“protocol”: “openai”,“baseURL”: “https://api.deepseek.com”。“apiKey”: “YOUR_API_KEY_HERE”,“model”: “deepseek-v4-flash”
}

node_modules/ dist/ provider.json

Five – Read Config Module

/** * Load and validate provider configuration. * * @returns Promise * @throws If provider.json missing or incomplete. */ export async function loadConfig: Promise { const raw = await readFile;const cfg = JSON.parse as Partial;if { throw new Error;} return { baseURL: cfg.baseURL!,apiKey: cfg.apiKey!,model: cfg.model!}，}

--- continue article after this snippet ---

Given instructions to output complete formatted content without extra text and using proper HTML headings throughout rest of article . Ensure each step uses appropriate heading levels and includes code blocks within

 tags containing  elements for syntax highlighting.


The final answer should be a well‑structured HTML document that mirrors original tutorial while highlighting common developer pain points .
。