企业官网建设流程全解析

使用 awesome-codex-skills 的 Harvest Automation 技能，在终端用自然语言完成工时记录与项目自动化管理

【免费下载链接】awesome-codex-skillsA curated list of practical Codex skills for automating workflows across the Codex CLI and API.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-codex-skills

<output_article>

Codex 技能实战：使用 awesome-codex-skills 的 Harvest Automation 实现工时记录与项目自动化管理

本指南以 composio-skills/harvest-automation/SKILL.md 为绝对核心，讲解如何在 Codex CLI 中通过 Rube MCP 与 Composio 工具网关，用自然语言完成 Harvest 的工时记录（time tracking）、项目 / 客户 / 任务管理与报表查询。读完本文，你将掌握该技能的安装配置流程、11 个HARVEST_*工具的完整参数语义、六个核心工作流，以及五个高频踩坑点的规避方法，可以直接在终端里落地一套"说一句话即可记账工时"的自动化工作流。

一、技能定位：一份可被 Codex 自动触发的 Harvest 操作手册

Harvest Automation 是 awesome-codex-skills 仓库中 composio-skills 目录下的一个 Codex Skill。所谓 Skill，按照仓库 README.md 的说明，是一组模块化的指令包：每个技能独立成文件夹，内含一个SKILL.md，通过 YAML frontmatter 声明name和description元数据，正文则是分步执行指引。Codex 读取元数据判断何时触发该技能，只有在命中后才加载正文，从而保持上下文精简。

该技能的 SKILL.md 头部声明如下：

--- name: Harvest Automation description: "Automate time tracking, project management, and invoicing workflows in Harvest -- log hours, manage projects, clients, and tasks through natural language commands." requires: mcp: - rube ---

从中可以看出三个关键信息：

• name：Harvest Automation，技能的唯一标识；
• description：这是 Codex 判断"何时触发"的匹配依据——当用户的请求涉及在 Harvest 中记录工时、管理项目/客户/任务等场景时，该技能会被自动唤起；
• requires.mcp：声明该技能依赖名为rube的 MCP 服务器，这是所有操作得以执行的基础设施。

技能的目标很明确：把"在 Harvest 里记一笔工时、建一个项目、拉一份报表"这类原本要在网页或客户端里完成的重复操作，变成在终端里用自然语言一句话搞定，全程无需离开命令行。

二、工作原理：Rube MCP 与 Composio 工具网关如何把"一句话"变成"一次 API 调用"

Harvest Automation 本身不直接封装 Harvest API，而是依赖 Rube MCP（https://rube.app/mcp）提供的工具网关。这一点可以在同仓库的 composio-skills/composio-automation/SKILL.md 中得到印证，该技能详细描述了 Rube MCP 的标准工作流，Harvest 技能正是这套通用机制下的一个具体业务场景：

1. 发现工具（RUBE_SEARCH_TOOLS）：先用自然语言描述目标任务，返回可用的工具 slug、输入 schema、推荐的执行计划和已知坑。composio-automation 技能特别强调"工具 schema 会变化，永远不要硬编码工具 slug 或参数，先搜索再执行"；
2. 检查连接（RUBE_MANAGE_CONNECTIONS）：确认 Harvest 的 OAuth 连接状态为ACTIVE，若未激活则跟随返回的认证链接完成授权；
3. 执行工具（RUBE_MULTI_EXECUTE_TOOL）：用搜索到的工具 slug 与符合 schema 的参数发起调用，注意即使无额外参数也要携带memory（可为空{}）。

因此，Harvest Automation 的完整调用链可以概括为：

自然语言请求 → Codex 依据 description 触发 Harvest Automation 技能 → RUBE_SEARCH_TOOLS 确认工具 schema → RUBE_MANAGE_CONNECTIONS 校验 Harvest 连接 → RUBE_MULTI_EXECUTE_TOOL 执行 HARVEST_* 工具 → 结果以 JSON 返回终端

这套设计的好处是解耦：技能只负责"教会模型怎么用工具"，真实的鉴权、限流、连接管理全部由 Rube/Composio 网关承担，技能文件本身可以保持轻量。

三、安装与配置：三步启用 Harvest 自动化

按照 SKILL.md 的 Setup 章节，启用过程分为三步：

1. 添加 Rube MCP 服务器：在 Codex 配置中加入 MCP 服务器，URL 为https://rube.app/mcp；
2. 认证 Harvest 账户：根据提示通过返回的连接链接完成 Harvest 账户的 OAuth 授权；
3. 开始用自然语言操作：认证完成后，即可在会话中直接描述工时记录、项目管理等需求。

如果尚未安装技能本身，可以参考仓库 README.md 的 Quickstart 章节完成安装：

• 推荐方式（skill-installer）：克隆仓库后执行python skill-installer/scripts/install-skill-from-github.py --repo ComposioHQ/awesome-codex-skills --path harvest-automation，安装器会把技能放入$CODEX_HOME/skills/<skill-name>（默认~/.codex/skills）；
• 手动方式：将composio-skills/harvest-automation/目录复制到$CODEX_HOME/skills/下，重启 Codex 使其加载元数据。

注意：安装或更新技能后需要重启 Codex 才能被识别；可通过ls ~/.codex/skills与head ~/.codex/skills/<skill>/SKILL.md验证安装结果。以上均为仓库 README.md 明确记载的通用安装流程，对包括 Harvest Automation 在内的所有技能适用。

四、核心工作流一：工时条目的创建与查询

4.1 创建工时条目（HARVEST_CREATE_TIME_ENTRY）

技能文档给出的示例指令是：

Log 3.5 hours of development work on project 12345, task 67890 for today

对应工具为HARVEST_CREATE_TIME_ENTRY，其关键参数语义如下：

从源码层面看，project_id与task_id的绑定关系是本工具最容易出错的地方，详见后文"已知坑"第一节。

4.2 查询工时条目（HARVEST_LIST_TIME_ENTRIES）

配套的HARVEST_GET_TIME_ENTRY则通过工时条目 ID 精确获取单条记录，用于核对或作为更新操作的输入。

五、核心工作流二：项目、客户与任务的建模

5.1 创建与查询项目

技能文档给出的示例指令是：

Create a billable project called "Website Redesign" for client 456 with Tasks billing and project budget

HARVEST_CREATE_PROJECT的参数约束非常严格，五个字段全部必填，缺一即触发校验错误：

• name、client_id、is_billable、bill_by、budget_by（均必填）；
• bill_by可选值："Project"、"Tasks"、"People"、"none"；
• budget_by可选值："project"、"project_cost"、"task"、"task_fees"、"person"、"none"；
• 可选参数：budget（预算金额）、hourly_rate（小时费率）、starts_on/ends_on（起止日期）、is_fixed_fee（是否固定费用）。

查询侧由HARVEST_LIST_PROJECTS（支持按客户过滤）与HARVEST_GET_PROJECT（按 ID 精确获取）承担。

5.2 客户管理

List all active clients in our Harvest account

• HARVEST_CREATE_CLIENT：name必填，可选address、currency、is_active；
• HARVEST_LIST_CLIENTS：支持is_active过滤与分页，per_page上限2000。

客户是项目的组织层级——项目挂在客户之下，因此在创建项目前往往需要先确认目标client_id。

5.3 任务管理

Create a new billable task called "Code Review" with a default rate of $150/hr

• HARVEST_CREATE_TASK：name必填，可选billable_by_default（默认是否可计费）、default_hourly_rate（默认小时费率）、is_active、is_default；
• HARVEST_LIST_TASKS：支持is_active、is_default过滤与分页，per_page上限100；
• 任务名称必须在全部任务（含已归档）中全局唯一。

值得强调的是，任务（task）与项目是"多对多"的分配关系：HARVEST_LIST_TASKS返回的是全局任务库，而一条工时条目真正合法关联的是"已分配到该项目下的任务"。建模顺序通常为：先有客户 → 再建项目 → 把任务分配到项目 → 最后才允许创建指向该项目+任务的工时条目。

六、核心工作流三：时间报表与工时修正

6.1 报表拉取

Show me all unbilled time entries for project 789 from January 2026

报表场景复用HARVEST_LIST_TIME_ENTRIES与HARVEST_GET_TIME_ENTRY，技能文档给出的组合策略：

• 用from_date和to划定时间窗口；
• 用is_billed: false筛选未开票工时（开票/账单核算的前置步骤）；
• 组合project_id、user_id、client_id实现跨维度统计（例如"某客户下某员工在某区间的全部工时"）；
• 用page/per_page分页拉全整个数据集。

6.2 修正既有工时条目

Update time entry 123456 to change the hours to 4.0 and add the note "Completed API integration"

HARVEST_UPDATE_TIME_ENTRY的约束：

• 必填time_entry_id；
• 支持部分更新（partial update）——只传需要改的字段即可，其余保持不变；
• 可更新字段：hours、notes、project_id、task_id、spent_date、started_time、ended_time。

这一能力让"记错工时、改错项目、补备注"等日常纠错操作都能以自然语言完成，不需要回到 Harvest 网页端手动编辑。

七、已知坑与规避策略（Known Pitfalls）

技能文档专门用一节总结了五个高频坑，这直接决定了自动化脚本能否稳定运行：

1. 任务分配关系必须核验：创建工时条目时，task_id必须对应"已经分配到project_id所指项目"的任务。校验时应使用项目任务分配（project task assignments）接口，而不是只依赖HARVEST_LIST_TASKS——后者返回的是全局任务库，包含未分配到该项目的任务。从技能文档的原话看，这是文档作者实测得出的关键经验；
2. 计费模式二选一：Harvest 账户要么是"按时长（duration-based）"要么是"按时间戳（timestamp-based）"计费。在按时长账户上，started_time/ended_time会被忽略；在按时间戳账户上，hours会被忽略。创建工时前需先确认账户类型，避免参数"写了但没生效"；
3. 分页上限不一致：HARVEST_LIST_TIME_ENTRIES和HARVEST_LIST_CLIENTS单页最多2000条，而HARVEST_LIST_PROJECTS和HARVEST_LIST_TASKS单页上限只有100条。写分页循环时必须按工具分别取上限，否则会得到分页截断的数据；
4. 日期格式必须统一：所有日期参数一律使用YYYY-MM-DD；updated_since类的增量过滤则使用带时区的 ISO 8601 格式。混用格式会直接导致解析失败；
5. 项目创建字段不可缺省：HARVEST_CREATE_PROJECT的五个必填字段（name、client_id、is_billable、bill_by、budget_by）任何一个缺失都会返回校验错误，因此这条工具命令应始终按"五字段齐全"来构造。

八、快速参考：11 个 HARVEST_* 工具一览

以下为技能文档 Quick Reference 章节的完整工具清单，可在日常会话中作为速查表：

从结构上可以归纳出技能的设计模式：每个实体（time entry / project / client / task）都配备"创建 + 列表"两个基础工具，工时与项目还额外提供"按 ID 获取"和"更新"工具。这种工具组合足以覆盖"录入—查询—修正—报表"的完整闭环。

九、同系列技能与进一步探索

Harvest Automation 并非孤例，awesome-codex-skills 的 composio-skills 目录下存在大量同构技能。最具对照价值的是 composio-skills/toggl-automation/SKILL.md（同为时间追踪领域）：它的 frontmatter 同样声明requires.mcp: [rube]，核心工具则替换为TOGGL_CREATE_TIME_ENTRY、TOGGL_GET_USER_WORKSPACES等。两个技能放在一起对比，可以清晰看出"Rube MCP 网关 + 业务工具 slug + 参数语义 + 已知坑"这一模板化的技能编写思路：工具命名遵循{APP}_{VERB}_{ENTITY}的大写下划线约定（如HARVEST_CREATE_TIME_ENTRY），参数表与 pitfalls 节则承载了每个应用最核心的领域知识。

如果想要更深入理解 Rube MCP 的底层调用协议（工具搜索、连接管理、批量执行），可以阅读 composio-skills/composio-automation/SKILL.md；如果想了解 Codex 技能的通用安装、编写与触发机制，可查看仓库 README.md 的 "Using Skills in Codex" 与 "Creating Skills" 章节。

结语

Harvest Automation 展示了 Codex Skill 的一种成熟落地形态：用轻量的指令文件教会模型一套业务工具的使用方式，把高频、重复、易错的 Harvest 操作收敛为一句自然语言。它的价值不止于"省去手动点击"，更在于将工时数据、项目结构与计费逻辑沉淀为可脚本化、可审计的工作流——无论是日常记工时，还是月末拉取未开票工时汇总，都可以在终端内完成。本文所覆盖的 11 个工具、6 个工作流与 5 个已知坑，构成了使用该技能的完整知识基线；在实际使用中，建议始终以技能文档和RUBE_SEARCH_TOOLS返回的最新 schema 为准。 </output_article>

【免费下载链接】awesome-codex-skillsA curated list of practical Codex skills for automating workflows across the Codex CLI and API.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-codex-skills