AI Agent集成黄历技能包：传统农历查询的现代化技术实现

1. 项目概述：一个面向AI Agent的统一黄历技能包

最近在折腾各种AI Agent和代码助手，发现一个挺有意思的需求：如何让这些智能工具也能“掐指一算”，查询咱们传统的黄历信息？无论是Claude Code、Cursor还是OpenClaw，它们处理代码和逻辑问题很在行，但涉及到像“2025年5月1日适不适合搬家”、“哪天是黄道吉日”这类传统文化查询，就显得有点“知识盲区”了。这正是huangli-agent-skills这个项目要解决的问题。它不是一个简单的日历API，而是一个专门为AI Agent、命令行工具（CLI）以及各类技能客户端设计的、标准化的黄历查询技能包。

简单来说，这个项目把复杂的中国农历、干支纪年、每日宜忌、神煞方位这些传统黄历数据，封装成了一个统一的、可编程的接口。开发者或者普通用户，可以把它像插件一样安装到自己的AI工作流里。之后，无论是通过代码调用，还是直接跟你的AI助手对话（比如“帮我查一下下周五的吉凶”），都能获得结构化的黄历信息。它解决了AI工具在传统文化领域数据缺失的问题，让技术也能服务于传统习俗的查询需求，适合开发者、对AI自动化感兴趣的爱好者，以及任何需要在程序或智能对话中集成黄历功能的用户。

2. 核心设计思路：为什么是“技能包”而非“API”？

初次接触这个项目，你可能会想：这不就是一个提供黄历数据的后台服务吗？为什么非要强调“Agent Skill”和“技能包”的概念？这恰恰是理解其价值的关键。传统的API服务，调用者需要关心网络请求、认证、错误处理、数据解析等一系列底层细节。而一个设计良好的“技能”（Skill），其目标是封装复杂性，提供开箱即用的功能单元。

2.1 统一接口与多客户端适配

huangli-agent-skills的核心是一个名为huangli-toolkit的源码目录，它发布时的标识（slug）是zhongguo-nongli-huangli-jixiong。这个工具包内部定义了三种最常用的查询模式，覆盖了绝大部分使用场景：

1. 按日期查询：给定一个具体的公历日期（如2025-05-01），返回那一天的完整黄历信息。
2. 批量范围查询：给定一个起始和结束日期，返回这个时间段内所有的黄历数据。更强大的是，它支持--filter参数，可以只筛选出包含特定关键词（如“搬家”、“开业”）的日子，这对于规划日程非常实用。
3. 关键词跨年检索：这是非常“智能”的一个功能。比如你想知道“2025年哪天是甲子日”，不需要自己翻日历计算，直接使用search命令，它就能在指定年份范围内，找出所有符合条件的天干地支组合日期。

这种设计抽象了数据获取的复杂性，用户和AI Agent都只需要关注“我想查什么”，而不是“我怎么去查”。工具包本身处理了与后端服务的认证、通信、数据格式化等所有脏活累活。

2.2 双模式授权：兼顾灵活与安全

项目提供了网页和CLI两种授权模式，这不是简单的重复，而是针对不同用户习惯和安全性考虑的精巧设计。

• 网页模式：它的核心价值在于可控性与可视化。对于不熟悉命令行的用户，或者希望先直观了解配额、管理设备的用户，网页控制台是最佳入口。你可以在浏览器里完成所有账户操作，并手动复制Token。这种方式将敏感操作（如注册、登录、查看Token）集中在安全的HTTPS网页中完成，符合大多数用户对“账户管理”的心理预期。
• CLI模式：它的核心价值在于自动化与集成。通过一个auth.py login命令，配合OAuth式的流程（CLI生成临时码，用户在浏览器确认），自动完成本地环境变量的配置。这极大地简化了在自动化脚本、CI/CD流程或AI Agent中集成该技能的步骤。AI Agent可以像调用一个本地命令一样，直接触发授权流程，而无需用户手动介入复制粘贴Token。

实操心得：在实际集成中，我强烈推荐先使用网页模式熟悉整个流程，并测试Token的有效性。一旦确认服务可用，再在需要自动化的环境中部署CLI模式。CLI模式写入的~/.huangli_token.json和~/.huangli.env文件是纯文本，请注意其存放位置的安全性，避免误提交至公开的代码仓库。

3. 详细安装与配置指南

虽然项目文档提供了安装命令，但在不同环境和客户端下，实际安装过程可能会遇到一些“坑”。这里我结合自己的实操经验，为你拆解每一步，并补充那些文档里没写的细节。

3.1 环境准备与依赖检查

无论采用哪种安装方式，一个干净的Python环境是基础。我建议使用venv或conda创建独立的虚拟环境，避免与系统或其他项目的包发生冲突。

# 创建并激活虚拟环境 (以 venv 为例) python3 -m venv huangli-env source huangli-env/bin/activate # Linux/macOS # huangli-env\Scripts\activate # Windows # 激活后，更新pip至最新版本，确保安装过程顺畅 pip install --upgrade pip

接下来，你需要根据自己使用的“客户端”来选择安装路径。这里的“客户端”指的是你主要使用的AI编程工具或技能框架。

3.2 针对不同客户端的安装详解

A. ClawHub 客户端用户如果你使用的是ClawHub这个集成的技能管理客户端，安装是最简单的。确保你已登录ClawHub账户。

clawhub login # 执行安装命令，clawhub会自动处理依赖和路径 clawhub install zhongguo-nongli-huangli-jixiong

安装成功后，技能包通常会被放置在ClawHub管理的统一技能目录下，你无需关心具体路径，直接使用clawhub run或相应的调用方式即可。

B. Cursor / Claude Code / OpenClaw 等编辑器/工具用户对于这类工具，项目推荐使用GitHub命令进行“稀疏克隆”，只下载必要的huangli-toolkit目录，然后手动放置到你的本地技能目录。这是为了保持技能目录的整洁，避免下载整个项目仓库的其他文档。

1. 确定本地技能目录：首先，你需要知道你的AI工具从哪里加载技能。例如，某些工具可能约定技能存放在~/skills/或~/.cursor/skills/下。请查阅你所用工具的文档。假设你的技能根目录是~/my-agent-skills/。
2. 执行稀疏克隆与复制：打开终端，执行以下命令序列。这里以技能最终路径为~/my-agent-skills/zhongguo-nongli-huangli-jixiong为例。

# 1. 创建一个临时目录并进入 mkdir -p /tmp/huangli-install && cd /tmp/huangli-install # 2. 初始化git仓库，并开启稀疏克隆功能 git init git remote add origin https://github.com/Leocdchina/huangli-agent-skills.git git config core.sparseCheckout true # 3. 指定只克隆 `huangli-toolkit/` 这个子目录 echo "huangli-toolkit/*" >> .git/info/sparse-checkout # 4. 拉取代码 git pull origin main # 5. 将克隆的目录复制到你的技能目录，并重命名为规定的slug名称 cp -r huangli-toolkit ~/my-agent-skills/zhongguo-nongli-huangli-jixiong # 6. 清理临时目录 cd ~ rm -rf /tmp/huangli-install

3. 验证安装：进入技能目录，检查核心文件是否存在。

   cd ~/my-agent-skills/zhongguo-nongli-huangli-jixiong ls -la toolkit.py auth.py

   你应该能看到这两个Python脚本文件。

注意事项：稀疏克隆的步骤稍显复杂，但这是管理大量技能时的最佳实践。如果工具支持，你也可以尝试直接将整个仓库克隆到技能目录下的一个子文件夹，但这样会包含README.md,LICENSE等文件，不够纯净。另外，确保你的技能目录路径被你的AI工具正确识别和加载，有时需要在工具的设置中配置技能路径。

3.3 授权配置：网页模式 vs CLI模式

安装完成只是第一步，要让技能工作，必须完成服务授权，即获取并配置访问令牌。

网页模式（手动配置）

1. 访问官网https://nongli.skill.4glz.com，完成注册/登录。
2. 进入控制台https://nongli.skill.4glz.com/dashboard，找到你的API Token。
3. 在终端中，手动设置环境变量。这里有一个关键细节：环境变量的设置是会话级的。如果你关闭了当前终端窗口，设置就会失效。

   export HUANGLI_TOKEN="你的真实Token字符串" export HUANGLI_BASE="https://api.nongli.skill.4glz.com"

   为了让环境变量永久生效，你需要将这两行export命令添加到你的shell配置文件中（如~/.bashrc,~/.zshrc），然后执行source ~/.zshrc。

CLI模式（自动配置）

1. 确保你在技能包目录下，并且虚拟环境已激活。
2. 运行python3 auth.py login。命令行会打印出一个授权链接，并尝试自动打开你的默认浏览器。如果自动打开失败，你需要手动复制链接到浏览器访问。
3. 在浏览器页面完成登录（或注册）并确认授权。
4. 授权成功后，CLI会自动在用户家目录生成~/.huangli_token.json（存储令牌信息）和~/.huangli.env（包含设置环境变量的命令）两个文件。
5. 执行source ~/.huangli.env来加载环境变量到当前会话。

重要技巧：auth.py脚本提供了--print-shell参数，这是一个非常安全且有用的选项。当你运行python3 auth.py login --print-shell时，它完成授权后，不会自动写入任何文件，而是直接将需要设置的export命令打印在终端上。你可以复制这些输出，然后手动决定如何处理（比如临时粘贴执行，或添加到配置文件）。这完全避免了脚本修改你的系统文件，适合在受限环境或希望完全掌控的情况下使用。

4. 核心功能使用与参数解析

配置好环境后，就可以开始使用toolkit.py这个强大的命令行工具了。下面我们深入每一个命令，看看它们在实际场景中如何应用。

4.1by-date: 查询特定日子的黄历

这是最基础也是最常用的功能。命令格式非常简单：

python3 toolkit.py by-date <日期>

日期格式必须是YYYY-MM-DD。

执行示例与输出解读：

python3 toolkit.py by-date 2025-05-01

假设执行成功，你会得到一个结构化的JSON输出。一个典型的响应可能包含以下核心字段：

{ "date": "2025-05-01", "lunar_date": "农历四月初四", "ganzhi_year": "乙巳", "ganzhi_month": "庚辰", "ganzhi_day": "庚午", "solar_term": "谷雨", "star_auspicious": "天德合", "star_inauspicious": "月破, 大耗", "pengzu_baiji": "丁不剃头 午不苫盖", "chong_shengxiao": "冲鼠", "chong_ganzhi": "冲甲子", "yi": ["祭祀", "祈福", "开光", "求嗣", "解除"], "ji": ["嫁娶", "开市", "入宅", "出行", "安葬"], "wuxing": "路旁土", "star": "昴日鸡", "god_direction": { "cai": "正东", "xi": "西南", "fu": "西南", "yanggui": "正西", "yinhui": "正东" } }

• 关键字段说明：
  • yi（宜）和ji（忌）：这是黄历的核心，列出了当日适宜与忌讳的事项。
  • chong_shengxiao（冲生肖）：如果当天“冲鼠”，那么属鼠的人可能需谨慎安排重要事宜。
  • god_direction（神煞方位）：包含了财神、喜神、福神等方位，在传统习俗中用于选择方位。
  • pengzu_baiji（彭祖百忌）：以天干地支为引，列出当日禁忌，如“丁不剃头”指丁日不理发。

4.2batch: 批量查询与智能筛选

当你需要规划一个时间段内的活动时，比如想找出五月份所有适合“搬家”的日子，这个命令就派上用场了。

python3 toolkit.py batch <开始日期> <结束日期> [--filter 关键词]

执行示例：

# 查询2025年5月整个月的黄历 python3 toolkit.py batch 2025-05-01 2025-05-31 # 只查询2025年5月适合“搬家”的日子 python3 toolkit.py batch 2025-05-01 2025-05-31 --filter 搬家

使用--filter参数后，输出将只包含yi（宜）列表中带有“搬家”二字的日期条目。这极大地提升了信息筛选的效率。

实操心得：批量查询会消耗配额。免费额度是每天10个唯一日期。这意味着，batch 2025-05-01 2025-05-31一次查询31天，就会消耗31个配额额度，很可能直接触发超额（返回429错误）。因此，在免费额度内，合理使用--filter缩小查询范围，或者分多次进行小范围查询，是更明智的做法。例如，可以先查上半月适合“开业”的日子，再查下半月适合“搬家”的日子。

4.3search: 跨日期检索特定干支或关键词

这个功能用于解决更模糊的查询需求。例如，你想知道2025年有哪些日子是“甲子日”，或者想找出所有“天德合”吉星高照的日子。

python3 toolkit.py search <关键词> --year <年份>

执行示例：

# 查找2025年所有的“甲子日” python3 toolkit.py search 甲子日 --year 2025 # 查找2025年所有带有“天德”吉星的日子 python3 toolkit.py search 天德 --year 2025

search命令会在指定年份的每一天数据中进行全文检索，匹配ganzhi_day（日干支）、star_auspicious（吉神）等字段，返回所有包含关键词的日期列表。这对于研究传统历法或寻找特定属性的日期非常有用。

5. 集成到AI Agent与自动化工作流

技能包的最终价值在于被调用。下面我将展示如何将huangli-agent-skills集成到不同的自动化场景中。

5.1 在Python脚本中调用

你可以将toolkit.py当作一个模块来调用，或者直接使用subprocess执行命令。这里推荐模块化调用，更优雅。

#!/usr/bin/env python3 import sys import os import json # 假设技能包路径已添加到sys.path，或者使用绝对路径 sys.path.insert(0, '/path/to/your/skills/zhongguo-nongli-huangli-jixiong') from toolkit import main as toolkit_main def get_huangli_by_date(target_date): """查询指定日期的黄历""" # 模拟命令行参数 sys.argv = ['toolkit.py', 'by-date', target_date] try: # 调用主函数，它会将结果打印到stdout。我们需要捕获它。 # 注意：原toolkit.py设计为命令行工具，直接调用main会打印到控制台。 # 更稳妥的方式是使用subprocess捕获输出。 import subprocess result = subprocess.run( [sys.executable, '/path/to/your/skills/zhongguo-nongli-huangli-jixiong/toolkit.py', 'by-date', target_date], capture_output=True, text=True, check=True ) huangli_data = json.loads(result.stdout) return huangli_data except subprocess.CalledProcessError as e: print(f"查询失败: {e.stderr}") return None except json.JSONDecodeError: print("解析结果失败") return None if __name__ == '__main__': # 确保环境变量已设置 if not os.getenv('HUANGLI_TOKEN'): print("请先设置 HUANGLI_TOKEN 环境变量") sys.exit(1) data = get_huangli_by_date('2025-05-10') if data: print(f"日期: {data['date']}") print(f"宜: {', '.join(data.get('yi', []))}") print(f"忌: {', '.join(data.get('ji', []))}") # ... 处理其他数据

5.2 在Shell脚本或CI/CD中调用

在自动化脚本中，直接调用命令行是最直接的方式。

#!/bin/bash # 确保环境变量已source source ~/.huangli.env 2>/dev/null || { echo "未找到huangli环境变量"; exit 1; } TODAY=$(date +%Y-%m-%d) RESULT=$(python3 /path/to/skills/zhongguo-nongli-huangli-jixiong/toolkit.py by-date "$TODAY" 2>&1) if echo "$RESULT" | grep -q "error\|429\|401"; then echo "黄历查询失败: $RESULT" # 可以发送通知到钉钉、Slack等 # curl -X POST ... else # 解析JSON，可以使用jq工具 YI_ITEMS=$(echo "$RESULT" | python3 -c "import sys, json; print(','.join(json.load(sys.stdin).get('yi', [])))") echo "今日($TODAY)宜: $YI_ITEMS" # 可以将结果写入日报、或作为工作流的一个输入 fi

5.3 与Cursor/Claude Code等AI编辑器结合

在这些智能编辑器中，你可以通过自定义指令（Custom Instructions）或技能（Skills）配置，让AI助手在编写代码或规划时，具备查询黄历的能力。

例如，在Cursor的Commands配置中，你可以添加一个命令：

• Name:查询黄历
• Command:python3 /path/to/your/skills/zhongguo-nongli-huangli-jixiong/toolkit.py by-date $(date +%Y-%m-%d)

这样，在编辑器里直接触发这个命令，就能在侧边栏看到今天的黄历信息。更进一步，你可以编写一个更复杂的脚本，让AI在生成“项目启动计划”等文本时，自动插入对启动日期的黄历建议。

6. 常见问题、错误排查与优化建议

在实际使用和集成过程中，你肯定会遇到一些问题。下面是我踩过的一些坑以及解决方案。

6.1 配额不足 (HTTP 429 Error)

这是最常见的问题。免费额度每天只有10个唯一日期。

• 现象：执行命令后返回错误信息，包含429状态码和“quota exceeded”等字样。
• 排查：
  1. 运行python3 auth.py status检查当前Token状态和配额使用情况（如果API提供此端点）。
  2. 回忆或检查脚本是否在短时间内进行了大量batch查询。
• 解决：
  1. 登录网页控制台：访问https://nongli.skill.4glz.com/dashboard，通常这里会有一个“重置配额”或类似按钮。免费用户可以不限次数手动重置。
  2. 优化查询：
     • 避免无节制的batch查询。先用search或小范围batch配合--filter锁定目标日期。
     • 在脚本中加入缓存机制。对于已经查询过的日期，将结果保存在本地文件或数据库中，下次直接读取，避免重复消耗配额。
     • 考虑错峰查询，如果不是需要实时数据，可以将查询安排在配额重置后的时间点。

6.2 认证失败 (HTTP 401/403 Error)

• 现象：提示Invalid token或Unauthorized。
• 排查：
  1. 检查环境变量HUANGLI_TOKEN是否设置正确：echo $HUANGLI_TOKEN。
  2. Token是否已过期或被撤销。可以通过网页控制台查看Token状态或生成新的Token。
  3. 如果是CLI模式生成的Token，检查~/.huangli_token.json文件是否存在且内容完整。
• 解决：
  1. 网页模式用户：重新从控制台复制Token，并更新环境变量。
  2. CLI模式用户：运行python3 auth.py logout（如果支持）或直接删除~/.huangli_token.json和~/.huangli.env文件，然后重新执行python3 auth.py login。
  3. 确保网络环境可以正常访问https://api.nongli.skill.4glz.com。

6.3 命令未找到或Python路径问题

• 现象：python3: can‘t open file ‘toolkit.py‘或ModuleNotFoundError。
• 排查：
  1. 当前工作目录是否正确？你是否在技能包目录zhongguo-nongli-huangli-jixiong下执行命令？
  2. 使用的Python解释器是否正确？特别是使用了虚拟环境的情况下，确保终端会话已激活 (source venv/bin/activate)。
  3. 技能包路径是否正确？尤其是在AI编辑器中调用时，需要填写绝对路径。
• 解决：
  1. 使用绝对路径调用脚本：python3 /full/path/to/toolkit.py ...。
  2. 在脚本开头显式添加Python路径。
  3. 在AI编辑器的命令配置中，使用绝对路径。

6.4 网络超时或连接错误

• 现象：长时间无响应，或提示连接被拒绝/超时。
• 排查：检查本地网络，尝试用curl或浏览器直接访问https://api.nongli.skill.4glz.com看是否通顺。
• 解决：
  1. 如果是临时网络问题，等待后重试。
  2. 在脚本中增加重试逻辑和超时设置。
  3. 确认是否有代理设置干扰。如果使用代理，可能需要配置HTTP_PROXY/HTTPS_PROXY环境变量，或者在代码中为请求设置代理。

6.5 数据解析或格式错误

• 现象：脚本能运行，但解析返回的JSON时出错，或者输出格式不符合预期。
• 排查：
  1. 首先手动运行命令，查看原始输出是否是有效的JSON。可能是API返回了错误信息（如HTML页面）。
  2. 检查Python的json模块是否能正常解析。
• 解决：
  1. 在代码中加强错误处理，捕获JSONDecodeError。
  2. 打印出原始的响应文本，以便调试。
  3. 确认你使用的技能包版本与API服务是否兼容。关注项目的Release更新。

6.6 安全与隐私建议

1. Token管理：HUANGLI_TOKEN是访问凭证，切勿泄露。不要将其提交到公开的Git仓库。.huangli.env和.huangli_token.json文件也应放在安全位置。在CI/CD环境中，使用 Secrets 或环境变量来配置Token。
2. 文件权限：确保生成的本地配置文件 (~/.huangli_*) 权限设置合理（如600），防止其他用户读取。
3. 依赖安全：定期关注项目更新，以获取安全补丁和功能改进。

这个项目为AI工具生态增添了一个非常独特的传统文化维度。从我自己的使用体验来看，它的价值不仅在于提供了一个可查询的黄历接口，更在于其“技能化”的设计理念，使得集成变得异常简单。无论是用于个人日程规划的自动化脚本，还是嵌入到更复杂的AI智能体决策流程中，它都能作为一个可靠的传统文化数据源。最大的挑战可能来自于免费配额的限制，这就要求我们在使用策略上要更聪明，比如做好本地缓存、精细化查询。