357 lines
10 KiB
Markdown
357 lines
10 KiB
Markdown
# 技能需求文档模板
|
||
|
||
这份文档用于给技术人员、产品人员和实施人员统一描述某个 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 / 第三方服务】`：作用是 `【用途】`
|
||
|
||
### Python 包依赖（requirements.txt）
|
||
|
||
- 本技能若需**特有** Python 三方包，写入根目录 `requirements.txt`。
|
||
- `jiangchang-platform-kit`、`playwright` 等公共能力由宿主共享 runtime 提供，**不要**写入技能 requirements。
|
||
- `SKILL.md` 的 `platform_kit_min_version` 是运行契约/兼容性声明，供宿主校验，**不是** pip 依赖声明。
|
||
- 匠厂宿主安装/更新技能后，会将技能 requirements 安装到 `{JIANGCHANG_DATA_ROOT}/python-runtime/.venv`。
|
||
- 版本须尽量收窄（如 `requests>=2.31.0,<3`），避免共享 venv 冲突。
|
||
- **不要**把系统运行时组件（如 Microsoft Visual C++ Redistributable）写进 requirements.txt。
|
||
|
||
### 系统运行时前置条件（preflight / health）
|
||
|
||
- 若依赖 Windows 原生 DLL、本机浏览器 channel 等**系统级**能力，在 `health` / preflight 中检测并提示用户自行安装。
|
||
- 此类依赖**不**通过 pip / requirements.txt 由宿主自动安装。
|
||
|
||
示例：
|
||
|
||
### 兄弟技能依赖
|
||
|
||
- `some-sibling-skill`：提供主数据或凭证索引（按业务填写）
|
||
|
||
### 外部系统依赖
|
||
|
||
- 银行 / 政务 HTTP API（示例）：核心外部接口
|
||
- Chromium / Chrome / Edge（可选）：用于浏览器自动化
|
||
- Gitea：用于代码托管和发布工作流
|
||
- 匠厂客户端：用于正式环境安装与验证
|
||
|
||
## 8. 不在本次范围内的内容
|
||
|
||
这一节非常重要，用来明确本次“不做什么”，避免研发越做越散。
|
||
|
||
模板写法：
|
||
|
||
- 本次不实现 `【功能A】`
|
||
- 本次不处理 `【平台B】`
|
||
- 本次不做 `【高级能力】`
|
||
- 本次不兼容 `【旧结构 / 旧逻辑】`
|
||
|
||
示例：
|
||
|
||
- 本次不实现多租户隔离之外的附加报表
|
||
- 本次不实现实时流式处理
|
||
- 本次不实现自动重试机制
|
||
- 本次不兼容旧模板中的历史目录结构
|
||
|
||
## 9. 验收标准
|
||
|
||
说明什么情况下才算真正开发完成。
|
||
|
||
模板写法：
|
||
|
||
- 代码结构符合模板规范
|
||
- 最小命令可运行
|
||
- 核心命令可运行
|
||
- 正式环境可安装
|
||
- 匠厂中可看到最新版本
|
||
- 可以在新建任务中实际使用
|
||
|
||
示例：
|
||
|
||
- `health`、`version` 命令执行正常
|
||
- `run` 主流程可运行
|
||
- 发布后 Gitea 工作流成功
|
||
- 匠厂技能市场能看到最新版本
|
||
- skill 可以正常安装
|
||
- 安装后可在“新建任务”中调用
|
||
|
||
**测试与日志相关验收（所有新 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` 对照验收标准逐项检查
|
||
|
||
## 最小模板示例
|
||
|
||
下面给出一个可直接参考的简化版示例：
|
||
|
||
```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 | 张三 | 初版 |
|
||
```
|