100行代码演练企业级5层标准Harness架构项目（附调通源码）

iLearnAI
iLearnAI LV1
316阅读
本文摘要本期介绍不聊复杂的理论，用手写一个 图书馆管理系统，带大家搞懂 Harness 架构的核心 （五层架构），尤其是大家之前问过的 Spec 和 Skill 到底是什么、为什么需要它们。本文用最精简的代码完整实现Harness AI Agent 工程框架核心能力，严格遵循 Harness 典型模块设计。本文技能要求：最好有（0 基础也可以）基本的项目架构设计能力对当前热门的 Harness 工程有一定...

本期介绍

不聊复杂的理论，用手写一个 图书馆管理系统，带大家搞懂 Harness 架构的核心 （五层架构），尤其是大家之前问过的 Spec 和 Skill 到底是什么、为什么需要它们。

本文用最精简的代码完整实现Harness AI Agent 工程框架核心能力，严格遵循 Harness 典型模块设计。

本文技能要求：

最好有（0 基础也可以）基本的项目架构设计能力

对当前热门的 Harness 工程有一定的概念理解

1. 本演练项目介绍

本项目是一个基于 Harness 规范 构建的图书管理系统。其核心理念是通过“契约驱动开发”（Contract-Driven Development），确保文档、数据定义与业务逻辑在三个维度上的高度一致性。

本项目选题 容易理解的 一个 图书馆管理系统（library\_management），包括基本的功能：

  1. 查看 50 本图书
  2. 搜索图书
  3. 借阅图书
  4. 归还图书

如下是 OpenCode 对项目的分析：

33fba4e29ff7ab7f79a4311932947589.png

2. 项目架构定义

在定义项目架构之前，导入一些基本识认：

Agent = Model + Harness

Model（模型）= 智能 / 推理 / 决策（本项目省略大模型，只保留 “框架骨架”）

Harness（驾驭框架）= 模型之外的全部工程体系：

1）数据怎么存、状态怎么管

2）能力怎么封装成工具

3）任务怎么调度、流程怎么控制

4）边界怎么防护、错误怎么处理

Harness 的本质：给 “聪明但失控” 的模型，装一套底盘、缰绳、刹车、轨道，让它稳定、可复用、可运维地干活。

本项目就是：把一个普通图书馆系统，强行按照 Harness 标准分层，每一层只干一件事，把 “工程化” 的骨架暴露出来。

本项目包含：

  • 标准 5 层 Harness 架构（DataStore → Spec → Skill → Registry → Agent）
  • 完整企业级目录结构
  • 自动生成 spec.md + skill.md
  • 前后台、50 条数据、完整功能

废话少说，如下是本演练企业级的标准 5 层Harness 架构项目的代码包：

library_maanagement_harness/
├── main.py                    # 项目唯一入口
├── core/                      # Harness 核心框架层
│   ├── __init__.py
│   ├── datastore.py           # 数据状态层（唯一数据源）
│   ├── spec.py                # Spec 契约层（给 LLM/Agent 用）
│   ├── skill.py               # Skill 技能层（标准化能力）
│   └── agent.py               # Agent 调度层（大脑）
├── data/
│   ├── __init__.py
│   └── init_data.py           # 50 条图书数据初始化
├── docs/                      # 企业级文档（你要的 spec.md + skill.md）
│   ├── spec.md                # 契约文档（人读）
│   └── skill.md               # 技能文档（人读）
└── README.md                  # 项目说明

2.1. 项目严格遵循以下三个核心原则：

  • Spec (契约层)
  • 定义输入参数的类型、范围和约束（core/spec.py）。
  • Skill (执行层)
  • 实现原子化的业务逻辑，通过 execute 方法进行交互（core/skill.py）。
  • Doc (文档层)
  • 维护标准化的技能清单与契约说明（docs/）。

2.2. 本项目定义的 数据流向 (Data Flow)：

UserInput->SpecValidation->Skill.execute()->DatastoreInteraction->Standardized Output

技能清单与契约设计 (Skill Inventory)

技能 ID功能描述输入参数 (Spec)预期输出/行为
ShowBooksSkill展示所有图书及其状态无返回包含书名、作者、借阅状态的列表
SearchBookSkill基于关键词检索图书keyword: str返回匹配到的图书列表摘要
BorrowBookSkill执行图书借阅流程book_id: int,user_name: str更新数据库状态，返回操作结果
ReturnBookSkill归还已借出的图书book_id: int重置图书状态为可借阅

2.3. 开发与扩展规范

1）技能流程

定义 Spec: 在 core/spec.py 中新增对应的 @dataclass。

实现 Skill: 在 core/skill.py 中继承 BaseSkill 并实现 execute。

更新文档: 同步更新 docs/spec.md 和 docs/skill.md。

2）约束检查

原子性: 每个 Skill 只负责一个单一的、可观测的任务。

一致性: 严禁在代码中修改 Spec 定义而不同步更新文档。

类型安全: 所有输入必须通过 Spec 对象进行结构化映射。

3. 项目代码详解

详细的代码说明，参见每行注释！不作过多重复说明。

3.1 core/datastore.py（数据层）

# ==================================================
# Harness 数据状态层 DataStore
# 作用：唯一数据源、统一管理数据、提供原子化CRUD操作
# 所有状态变更必须通过这一层，保证数据一致性
# ==================================================
class LibraryDataStore:
    # 构造函数：初始化数据存储容器
    def __init__(self):
        self.books = []       # 存储所有图书列表
        self.borrowed = {}    # 存储借阅状态：{图书ID: 借阅人}
    # 添加一本图书到数据存储
    def add_book(self, book_data):
        self.books.append(book_data)
    # 获取全部图书列表
    def get_all_books(self):
        return self.books
    # 根据关键词搜索图书（书名/作者）
    def search_book(self, keyword):
        return [b for b in self.books if keyword in b['name'] or keyword in b['author']]
    # 借阅图书：校验状态 + 修改借阅记录
    def borrow_book(self, book_id, user_name):
        # 如果图书ID超出范围，返回失败
        if book_id >= len(self.books):
            return False, "图书ID不存在"
        # 如果图书已被借阅，返回失败
        if book_id in self.borrowed:
            return False, "图书已被借阅"
        # 执行借阅：记录借阅人和图书ID
        self.borrowed[book_id] = user_name
        return True, "借阅成功"
    # 归还图书：从借阅记录中删除
    def return_book(self, book_id):
        # 如果图书未被借阅，不能归还
        if book_id not in self.borrowed:
            return False, "图书未被借阅"
        # 删除借阅记录
        del self.borrowed[book_id]
        return True, "归还成功"

3.2 core/spec.py （契约层）

# ==================================================
# Harness 契约层 Spec
# 作用：定义每个技能的参数、描述、约束
# 给 LLM/Agent 自动解析使用
# ==================================================
from dataclasses import dataclass  # 导入数据类，用于定义结构化契约
# 展示所有图书的契约
@dataclass
class ShowBooksSpec:
    desc: str = "展示所有图书列表与借阅状态"
# 搜索图书的契约：需要 keyword 参数
@dataclass
class SearchBookSpec:
    keyword: str = ""            # 搜索关键词
    desc: str = "根据书名/作者搜索图书"
# 借阅图书的契约：需要 book_id、user_name
@dataclass
class BorrowBookSpec:
    book_id: int = 0            # 图书ID
    user_name: str = ""         # 借阅人姓名
    desc: str = "借阅图书，绑定用户"
# 归还图书的契约：需要 book_id
@dataclass
class ReturnBookSpec:
    book_id: int = 0            # 图书ID
    desc: str = "归还图书，重置借阅状态"

3.3 core/skill.py （技能层）

# ==================================================
# Harness 技能层 Skill
# 作用：将业务功能封装为标准化、可插拔的技能
# 每个技能绑定一个 Spec，提供统一 execute 接口
# ==================================================
from core.spec import ShowBooksSpec, SearchBookSpec, BorrowBookSpec, ReturnBookSpec
# 所有技能的基类
class BaseSkill:
    spec = None  # 每个子类必须绑定对应的 Spec
    # 构造函数：注入数据存储（依赖注入，解耦）
    def __init__(self, datastore):
        self.datastore = datastore
    # 统一执行入口：子类必须实现
    def execute(self, **kwargs):
        raise NotImplementedError("技能必须实现 execute 方法")
# ------------------------------
# 技能1：展示所有图书
# ------------------------------
class ShowBooksSkill(BaseSkill):
    spec = ShowBooksSpec()  # 绑定契约
    def execute(self, **kwargs):
        books = self.datastore.get_all_books()
        print("\n===== 图书列表 =====")
        # 遍历图书并打印状态
        for idx, book in enumerate(books):
            status = "已借阅" if idx in self.datastore.borrowed else "可借阅"
            print(f"ID:{idx} | 《{book['name']}》 | {book['author']} | {status}")
        return "展示完成"
# ------------------------------
# 技能2：搜索图书
# ------------------------------
class SearchBookSkill(BaseSkill):
    spec = SearchBookSpec()
    def execute(self, **kwargs):
        keyword = kwargs.get("keyword", "")  # 从参数获取关键词
        res = self.datastore.search_book(keyword)
        if not res:
            return "未找到图书"
        return f"找到 {len(res)} 本：{[b['name'] for b in res]}"
# ------------------------------
# 技能3：借阅图书
# ------------------------------
class BorrowBookSkill(BaseSkill):
    spec = BorrowBookSpec()
    def execute(self, **kwargs):
        book_id = int(kwargs.get("book_id", 0))
        user_name = kwargs.get("user_name", "")
        return self.datastore.borrow_book(book_id, user_name)
# ------------------------------
# 技能4：归还图书
# ------------------------------
class ReturnBookSkill(BaseSkill):
    spec = ReturnBookSpec()
    def execute(self, **kwargs):
        book_id = int(kwargs.get("book_id", 0))
        return self.datastore.return_book(book_id)

3.4 core/agent.py （调度层）

# ==================================================
# Harness 调度层 Agent（大脑）
# 作用：统一任务入口、技能路由、执行调度
# ==================================================
from core.skill import ShowBooksSkill, SearchBookSkill, BorrowBookSkill, ReturnBookSkill
class LibraryAgent:
    # 构造函数：接收 datastore，并注册所有技能
    def __init__(self, datastore):
        self.datastore = datastore
        # 技能注册中心：Harness 标准能力发现机制
        self.skill_registry = {
            "show": ShowBooksSkill(datastore),
            "search": SearchBookSkill(datastore),
            "borrow": BorrowBookSkill(datastore),
            "return": ReturnBookSkill(datastore)
        }
    # 统一任务执行入口
    def run(self, task_type, **params):
        # 根据任务类型找到对应技能
        skill = self.skill_registry.get(task_type)
        if not skill:
            return False, "未知技能"
        # 执行技能并返回结果
        return skill.execute(**params)

3.5 data/init\_data.py （数据初始化）

# ==================================================
# 数据初始化模块
# 作用：批量生成 50 条图书数据，用于演示
# ==================================================
def init_50_books(datastore):
    # 基础图书模板
    base_books = [
        {"name": "Python编程", "author": "埃里克", "type": "计算机"},
        {"name": "深度学习", "author": "伊恩", "type": "计算机"},
        {"name": "三体", "author": "刘慈欣", "type": "文学"},
        {"name": "红楼梦", "author": "曹雪芹", "type": "文学"},
        {"name": "史记", "author": "司马迁", "type": "历史"},
    ]
    idx = 0
    # 循环生成直到 50 本
    while len(datastore.books) < 50:
        book = base_books[idx % len(base_books)]
        # 生成带编号的新书
        new_book = {
            "name": f"{book['name']}-{idx+1}",
            "author": book['author'],
            "type": book['type']
        }
        # 添加到数据存储
        datastore.add_book(new_book)
        idx += 1
    print(f"✅ 初始化完成：共 {len(datastore.books)} 本图书")

3.6 main.py （项目入口）

# ==================================================
# 项目主入口文件
# 作用：初始化 Harness 全链路 + 提供前台 UI
# ==================================================
from core.datastore import LibraryDataStore
from core.agent import LibraryAgent
from data.init_data import init_50_books
# --------------------------
# 1. 初始化底层数据存储
# --------------------------
datastore = LibraryDataStore()
# --------------------------
# 2. 加载 50 条演示数据
# --------------------------
init_50_books(datastore)
# --------------------------
# 3. 初始化 Agent（大脑）
# --------------------------
agent = LibraryAgent(datastore)
# --------------------------
# 前台 UI：用户交互界面
# --------------------------
def ui():
    print("=" * 50)
    print("📚 企业级 Harness 图书馆管理系统")
    print("=" * 50)
    # 循环菜单
    while True:
        print("\n1.查看图书 | 2.搜索 | 3.借阅 | 4.归还 | 0.退出")
        c = input("请输入：")
        if c == "1":
            agent.run("show")  # 调用展示技能
        elif c == "2":
            kw = input("关键词：")
            print(agent.run("search", keyword=kw))  # 调用搜索技能
        elif c == "3":
            bid = input("图书ID：")
            user = input("姓名：")
            print(agent.run("borrow", book_id=bid, user_name=user))  # 借阅
        elif c == "4":
            bid = input("图书ID：")
            print(agent.run("return", book_id=bid))  # 归还
        elif c == "0":
            print("👋 退出系统")
            break
# 程序启动
if __name__ == "__main__":
    ui()

3.7 docs/spec.md

# Harness Spec 契约文档
本文件为人工阅读文档，不参与程序运行。
## ShowBooksSpec
- 功能：展示所有图书
- 输入：无
## SearchBookSpec
- 功能：搜索图书
- 输入：keyword
## BorrowBookSpec
- 功能：借阅图书
- 输入：book_id, user_name
## ReturnBookSpec
- 功能：归还图书
- 输入：book_id

3.8 docs/skill.md

# Harness Skill 技能手册
人工阅读文档，不参与代码执行。
## ShowBooksSkill
展示全部图书列表及状态
## SearchBookSkill
根据书名/作者检索图书
## BorrowBookSkill
执行图书借阅逻辑
## ReturnBookSkill
执行图书归还逻辑

4. 附：项目 github

项目源码获取：

https://github.com/hechunji/library\_management\_byenterprise-harness

image.png

觉得内容不错？我要

打赏杯咖啡或蜜雪冰城吧
微信扫一扫
微信赞赏码
支付宝扫一扫
支付宝赞赏码
版权声明
本文作者：iLearnAI
本文链接：https://www.ilearnai.online/archives/55/
转载需注明文章出处，若本文内容有侵犯到您合法权益，请联系站长删除
推荐阅读
不讲技术一匹马弄懂当前最热的Harness
不讲技术一匹马弄懂当前最热的Harness
如何用FDE搞垮一个团队：FDE是新风口，还是换个名字的高级外包？
如何用FDE搞垮一个团队：FDE是新风口，还是换个名字的高级外包？
为什么AI Coding编码效率跃迁后，测试环节的反差感在领导/团队眼里最大？
为什么AI Coding编码效率跃迁后，测试环节的反差感在领导/团队眼里最大？
AI Coding带来的假象与认知落差，掩盖了「真实企业复杂软件工程的全链路失速、质量失稳、债务失控与组织失衡」
AI Coding带来的假象与认知落差，掩盖了「真实企业复杂软件工程的全链路失速、质量失稳、债务失控与组织失衡」
SDD，AI时代的软件工程范式革命，从 Vibe Coding 到规范驱动的全场景落地指南（10w字长文）
SDD，AI时代的软件工程范式革命，从 Vibe Coding 到规范驱动的全场景落地指南（10w字长文）
AI 时代，测试才是稀罕物
AI 时代，测试才是稀罕物
评论 共1条
请登录后参与评论
QQuser01
QQuser01 LV1
广东 东莞

一步一步操作，真成功了😻

回复