client-commons/skill-template
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5c18d308bbc2d22b54472fa9f9bba16df84b0388
skill-template/references/REQUIREMENTS.md

9.2 KiB
Raw Blame History

技能需求文档模板

这份文档用于给技术人员、产品人员和实施人员统一描述某个 skill 的研发需求。

建议原则：

  • 一个 skill 对应一份主需求文档
  • 需求先写清楚，再进入开发
  • 文档描述“要做什么”和“做到什么程度”，不要在这里堆实现细节
  • 实现方式、代码结构、发布流程，分别放到 DEVELOPMENT.md、CLI.md、SCHEMA.md、RUNTIME.md

如果你是从 skill-template 复制新技能，请复制本文件后，把下面所有占位内容替换成你的真实项目内容。

REQUIREMENTS

1. 文档目标

说明这份需求文档的作用，以及它解决什么问题。

模板写法：

  • 本文档用于明确 【技能名称】 的研发范围、交付标准、依赖关系和验收要求。
  • 技术人员应以本文件作为开发范围依据，以避免实现偏差、范围蔓延或理解不一致。

示例：

  • 本文档用于明确 your-skill-slug（示例：disburse-payroll-icbc）的研发范围、交付标准、依赖关系和验收要求。

2. 业务背景

说明为什么要做这个 skill，它服务什么业务场景，解决什么实际问题。

模板写法：

  • 当前业务场景中，用户需要在 【目标平台】 完成 【业务动作】。
  • 现有流程主要依赖人工处理，存在 【效率低 / 容易出错 / 不可批量 / 不可追踪】 等问题。
  • 因此需要开发 【技能名称】，将该流程标准化、自动化，并接入匠厂技能体系中。

示例：

  • 当前财务团队需要将工资代发批次与银行接口对账，人工导出表格、核对差异耗时且易错。
  • 因此需要开发 disburse-payroll-icbc，用于自动拉取代发结果、写入任务日志 task_logs 并输出对账摘要，支持审计追踪。

3. 开发目标

说明本次开发希望最终交付什么结果。

模板写法：

  • 完成 【技能名称】 的标准目录结构搭建
  • 完成 CLI 入口与基础命令
  • 完成核心业务流程
  • 完成与兄弟技能或外部系统的必要集成
  • 完成正式环境发布验证

示例：

  • 完成 your-skill-slug 的标准 skill 结构建设
  • 提供 health、version、run、logs、log-get 等命令
  • 支持对接银行 / 薪酬系统 API（示例），并记录任务执行结果
  • 支持写入任务日志 task_logs，并可在正式环境中安装验证

4. 功能范围

说明这次开发明确要实现哪些功能。

模板写法：

  • 支持 【命令1】
  • 支持 【命令2】
  • 支持读取 【数据来源】
  • 支持执行 【核心业务动作】
  • 支持记录 【日志 / 状态 / 结果】

建议将功能拆成“必须实现”和“可后续扩展”。

示例：

必须实现

  • 支持 python scripts/main.py health
  • 支持 python scripts/main.py version
  • 支持 python scripts/main.py run
  • 支持从 some-sibling-skill 读取批次元数据（如需要）
  • 支持执行核心业务编排（HTTP / 批处理 / 可选 RPA）
  • 支持写入任务日志（task_logs）

可后续扩展

  • 支持定时批跑
  • 支持失败自动重试
  • 支持多目标轮询

5. 非功能要求

说明除功能外，对稳定性、可维护性、目录规范、日志、编码等方面的要求。

模板写法：

  • 目录结构必须符合当前 skill 模板规范
  • 入口必须统一为 scripts/main.py
  • 输出格式应尽量机读友好
  • 错误前缀统一为 ERROR:
  • Windows 环境下需保证 UTF-8 输出兼容
  • 必须具备基本日志能力

示例：

  • 项目结构必须对齐 skill-template
  • CLI 入口统一使用 scripts/main.py
  • 关键执行结果应可通过 JSON 或固定文本结构返回
  • 任务日志必须可追踪（task_logs）
  • 不允许重新引入旧模板中的 docs/、optional/ 或 scripts/skill_main.py

6. 输入输出要求

说明这个 skill 接收什么输入，产出什么输出。

模板写法：

输入

  • 【输入参数1】
  • 【输入参数2】
  • 【依赖系统返回的数据】

输出

  • 【标准输出】
  • 【错误输出】
  • 【数据库记录】
  • 【日志文件】

示例：

输入

  • target_id：可选，指定任务目标（账号 / 客户 / 平台）
  • input_id：可选，指定输入批次或记录
  • 兄弟技能返回的结构化数据（如有）

输出

  • 成功结果（stdout / JSON）
  • 错误输出（ERROR: / FAIL:）
  • 在本地数据库写入 task_logs
  • 在日志目录中写入执行日志

7. 依赖的兄弟技能或外部系统

说明开发该 skill 时依赖哪些内部技能或外部平台。

模板写法：

兄弟技能依赖

  • 【skill-a】：作用是 【用途】
  • 【skill-b】：作用是 【用途】

外部系统依赖

  • 【平台名】：作用是 【用途】
  • 【浏览器 / API / 第三方服务】：作用是 【用途】

示例：

兄弟技能依赖

  • some-sibling-skill：提供主数据或凭证索引（按业务填写）

外部系统依赖

  • 银行 / 政务 HTTP API（示例）：核心外部接口
  • Chromium / Chrome / Edge（可选）：用于浏览器自动化
  • Gitea：用于代码托管和发布工作流
  • 匠厂客户端：用于正式环境安装与验证

8. 不在本次范围内的内容

这一节非常重要，用来明确本次“不做什么”，避免研发越做越散。

模板写法：

  • 本次不实现 【功能A】
  • 本次不处理 【平台B】
  • 本次不做 【高级能力】
  • 本次不兼容 【旧结构 / 旧逻辑】

示例：

  • 本次不实现多租户隔离之外的附加报表
  • 本次不实现实时流式处理
  • 本次不实现自动重试机制
  • 本次不兼容旧模板中的历史目录结构

9. 验收标准

说明什么情况下才算真正开发完成。

模板写法：

  • 代码结构符合模板规范
  • 最小命令可运行
  • 核心命令可运行
  • 正式环境可安装
  • 匠厂中可看到最新版本
  • 可以在新建任务中实际使用

示例：

  • health、version 命令执行正常

  • run 主流程可运行

  • 发布后 Gitea 工作流成功

  • 匠厂技能市场能看到最新版本

  • skill 可以正常安装

  • 安装后可在“新建任务”中调用

  • python tests/run_tests.py -v 必跑测试全部通过

  • 任务日志（task_logs）写入和查询符合预期

  • 真实联调（如有）已在 tests/integration/ 中验证，且默认套件不包含真实外联

10. 开发注意事项

说明研发过程中必须特别注意的事项。

模板写法：

  • 不要修改无关 skill
  • 不要破坏现有模板规范
  • 优先遵守目录和分层约定
  • 不要在 CLI 层堆业务逻辑
  • 发布前必须先做本地最小验证

示例：

  • 只允许修改当前 skill 仓库，不要改动其他兄弟项目
  • 如使用浏览器自动化，优先复用已验证过的定位器和流程
  • cli 只做参数解析，核心逻辑统一放到 service
  • 发布前必须完成本地验证、工作流验证和正式环境安装验证

11. 变更记录

这一节用于记录需求文档本身的变化，不是 git 提交记录的替代，而是给技术人员看“需求范围怎么变了”。

模板写法：

日期 版本 变更人 变更内容
2026-04-13 v1.0 张三 初版需求文档
2026-04-14 v1.1 李四 增加正式环境验收要求

建议使用方式

建议每个新 skill 开发时，按下面顺序使用文档：

  1. 先写 references/REQUIREMENTS.md
  2. 再按 references/DEVELOPMENT.md 进入开发
  3. 开发过程中补充 CLI.md、SCHEMA.md、RUNTIME.md、TESTING.md
  4. 发布前回到 REQUIREMENTS.md 对照验收标准逐项检查

最小模板示例

下面给出一个可直接参考的简化版示例：

# REQUIREMENTS

## 1. 文档目标

本文档用于明确 `your-skill-slug` 的研发需求、范围和验收标准，作为开发与测试的统一依据。

## 2. 业务背景

采购审计需要将政府采购公告结构化归档；人工复制粘贴效率低，需要可追溯的任务日志。

## 3. 开发目标

- 完成 `your-skill-slug` 的标准 skill 结构
- 支持核心业务批处理 / HTTP 对接主流程
- 支持任务日志记录（task_logs）

## 4. 功能范围

- 支持 `health`
- 支持 `version`
- 支持 `run`
- 支持查询任务日志（logs / log-get）

## 5. 非功能要求

- 入口统一为 `scripts/main.py`
- 保持 UTF-8 输出
- 结构符合 skill 模板规范

## 6. 输入输出要求

### 输入

- `target_id`
- `input_id`

### 输出

- 成功结果
- 错误信息
- task_logs 记录

## 7. 依赖的兄弟技能或外部系统

- （按需填写兄弟 skill）
- 政务公告站点 HTTP API（示例）

## 8. 不在本次范围内的内容

- 不实现浏览器可视化回放（如需另行立项）
- 不实现自动重试

## 9. 验收标准

- 命令可运行
- `python tests/run_tests.py -v` 全部通过
- task_logs 写入符合 SCHEMA 约定
- 能完成正式环境安装验证
- 能在新建任务中使用

## 10. 开发注意事项

- 不修改无关项目
- 不引入旧模板结构

## 11. 变更记录

| 日期 | 版本 | 变更人 | 变更内容 |
|------|------|--------|----------|
| 2026-04-13 | v1.0 | 张三 | 初版 |
Reference in New Issue View Git Blame Copy Permalink