249 lines
8.5 KiB
Markdown
249 lines
8.5 KiB
Markdown
# 技能需求文档模板
|
||
|
||
这份文档用于给技术人员、产品人员和实施人员统一描述某个 skill 的研发需求。
|
||
|
||
建议原则：
|
||
|
||
- 一个 skill 对应一份主需求文档
|
||
- 需求先写清楚，再进入开发
|
||
- 文档描述“要做什么”和“做到什么程度”，不要在这里堆实现细节
|
||
- 实现方式、代码结构、发布流程，分别放到 `DEVELOPMENT.md`、`references/`、`development/` 下的技术规范
|
||
|
||
如果你是从 `skill-template` 复制新技能，请复制本文件后，把下面所有占位内容替换成你的真实项目内容。
|
||
|
||
---
|
||
|
||
# REQUIREMENTS
|
||
|
||
## 1. 文档目标
|
||
|
||
说明这份需求文档的作用，以及它解决什么问题。
|
||
|
||
模板写法：
|
||
|
||
- 本文档用于明确 `your-skill-slug` 的研发范围、交付标准、依赖关系和验收要求。
|
||
- 技术人员应以本文件作为开发范围依据，以避免实现偏差、范围蔓延或理解不一致。
|
||
|
||
## 2. 业务背景
|
||
|
||
说明为什么要做这个 skill，它服务什么业务场景，解决什么实际问题。
|
||
|
||
模板写法：
|
||
|
||
- 当前用户在 `<业务场景>` 中需要反复处理 `<输入数据>`，人工操作耗时且易错。
|
||
- 现有流程主要依赖人工处理，存在 `<效率低 / 容易出错 / 不可批量 / 不可追踪>` 等问题。
|
||
- 因此需要开发 `your-skill-slug`，用于自动完成 `<核心动作>`，输出 `<输出结果>`，并写入 `task_logs` 便于追踪。
|
||
|
||
填写提示：
|
||
|
||
- `<业务场景>`：例如“每日批量导入外部系统结果”“Agent 触发的单次查询”
|
||
- `<输入数据>`：例如“关键词列表”“批次 ID”“账号标识”
|
||
- `<核心动作>`：例如“调用 adapter 提交”“采集并入库”“对账摘要生成”
|
||
- `<输出结果>`：例如“结构化 JSON”“任务摘要”“本地 SQLite 记录”
|
||
|
||
## 3. 开发目标
|
||
|
||
说明本次开发希望最终交付什么结果。
|
||
|
||
模板写法（按 skill 类型勾选/改写）：
|
||
|
||
- 解析并校验 `<输入数据>` 的关键字段
|
||
- 通过 adapter 完成 mock / simulator / real 档位下的 `<核心动作>`
|
||
- 输出结构化结果（stdout JSON 或固定文本 + 机读字段）
|
||
- 写入 `task_logs`（及必要的业务表，见 `references/SCHEMA.md`）
|
||
- 支持失败可诊断（稳定错误码、`ERROR:` 前缀、必要截图/日志）
|
||
- 完成 CLI 入口与 `health` / `version` 最小可运行验证
|
||
- 完成正式环境发布与安装验证（如适用）
|
||
|
||
## 4. 功能范围
|
||
|
||
说明这次开发明确要实现哪些功能。
|
||
|
||
模板写法：
|
||
|
||
- 支持 `<命令1>`（如 `run`）
|
||
- 支持 `<命令2>`（如 `logs` / `log-get`）
|
||
- 支持读取 `<数据来源>`（兄弟 skill / 本地 DB / 外部 API）
|
||
- 支持执行 `<核心业务动作>`
|
||
- 支持记录 `<日志 / 状态 / 结果>`
|
||
|
||
建议将功能拆成“必须实现”和“可后续扩展”。
|
||
|
||
### 必须实现
|
||
|
||
- 支持 `python scripts/main.py health`
|
||
- 支持 `python scripts/main.py version`
|
||
- 支持 `python scripts/main.py <your-main-command>`
|
||
- 支持核心业务编排（HTTP / 批处理 / 可选 RPA，按四档 adapter 选型）
|
||
- 支持写入任务日志（`task_logs`）
|
||
|
||
### 可后续扩展
|
||
|
||
- 支持定时批跑
|
||
- 支持失败自动重试
|
||
- 支持多 `<目标系统>` 轮询
|
||
|
||
## 5. 非功能要求
|
||
|
||
说明除功能外，对稳定性、可维护性、目录规范、日志、编码等方面的要求。
|
||
|
||
- 目录结构必须符合当前 `skill-template` 规范
|
||
- 入口必须统一为 `scripts/main.py`
|
||
- 用户说明写在根 `README.md`；LLM/运行契约写在 `SKILL.md`；开发规范在 `development/`
|
||
- 输出格式应尽量机读友好；错误前缀统一为 `ERROR:`
|
||
- Windows 环境下需保证 UTF-8 输出兼容
|
||
- 必须具备基本日志能力；敏感字段脱敏
|
||
- RPA 类 skill：Playwright 由宿主共享 runtime 提供；技能侧不要 `playwright install`；URL 不要放进 `launch_persistent_context` 的 `args`
|
||
|
||
## 6. 输入输出要求
|
||
|
||
### 输入
|
||
|
||
填写本 skill 实际接受的参数与数据来源：
|
||
|
||
- `<参数名>`：含义、是否必填、默认值
|
||
- `<依赖系统>` 返回的结构化数据（如有）
|
||
- 环境变量 / `.env` 中的关键配置（引用 `CONFIG.md`）
|
||
|
||
### 输出
|
||
|
||
- 成功结果（stdout / JSON 字段说明）
|
||
- 错误输出（`ERROR:` 稳定码 + 中文 message）
|
||
- 数据库记录（表名、关键字段，见 `references/SCHEMA.md`）
|
||
- 可选：RPA 截图/视频路径（artifacts）
|
||
|
||
## 7. 依赖的兄弟技能或外部系统
|
||
|
||
### 兄弟技能依赖
|
||
|
||
- `<sibling-skill-slug>`：`<用途>`（例如 account-manager 提供 profile_dir / 租约）
|
||
|
||
### 外部系统依赖
|
||
|
||
- `<目标系统>`：`<用途>`（HTTP API / 仿真 sandbox / 真实网页）
|
||
- 浏览器（如适用）：系统 Chrome/Edge，非 Playwright 内置 Chromium
|
||
- Gitea / 匠厂客户端：发布与正式环境验证
|
||
|
||
### Python 包依赖（requirements.txt）
|
||
|
||
- 本技能若需**特有** Python 三方包，写入根目录 `requirements.txt`。
|
||
- `jiangchang-platform-kit`、`playwright` 等公共能力由宿主共享 runtime 提供，**不要**写入技能 requirements。
|
||
- `SKILL.md` 的 `platform_kit_min_version` 是运行契约/兼容性声明，**不是** pip 依赖声明。
|
||
- 版本须尽量收窄（如 `requests>=2.31.0,<3`），避免共享 venv 冲突。
|
||
- **不要**把系统运行时组件写进 requirements.txt；在 `health` / preflight 中检测并提示。
|
||
|
||
## 8. 不在本次范围内的内容
|
||
|
||
明确本次“不做什么”，避免范围蔓延：
|
||
|
||
- 本次不实现 `<功能A>`
|
||
- 本次不处理 `<平台B>` / `<档位>`
|
||
- 本次不做 `<高级能力>`
|
||
- 本次不兼容旧模板历史结构（`docs/`、`optional/`、`skill_main.py` 等）
|
||
|
||
## 9. 验收标准
|
||
|
||
什么情况下才算开发完成：
|
||
|
||
- 代码结构符合模板规范；`SKILL.md` slug 与 `constants.SKILL_SLUG` 一致
|
||
- `health`、`version` 命令执行正常
|
||
- 主命令（如 `run`）在 mock / simulator 档位可重复验证
|
||
- `python tests/run_tests.py -v` 必跑测试全部通过
|
||
- `task_logs` 写入和查询符合 `references/SCHEMA.md`
|
||
- 真实联调（如有）放在 `tests/integration/`，且默认套件不包含真实外联
|
||
- 发布后 Gitea 工作流成功；匠厂技能市场可见最新版本；安装后可在“新建任务”中调用
|
||
|
||
## 10. 开发注意事项
|
||
|
||
- 只修改当前 skill 仓库，不要改动无关兄弟项目
|
||
- 先判断四象限类型（`real_browser_rpa` / `real_api` / `simulator_browser_rpa` / `simulator_api`），再读对应 `examples/*/README.md`
|
||
- `cli` 只做参数解析；核心逻辑在 `service`；兄弟 skill 调用集中封装（见 `ADAPTER.md`）
|
||
- 发布前完成本地验证、工作流验证和正式环境安装验证
|
||
|
||
## 11. 变更记录
|
||
|
||
| 日期 | 版本 | 变更人 | 变更内容 |
|
||
|------|------|--------|----------|
|
||
| YYYY-MM-DD | v1.0 | `<姓名>` | 初版需求文档 |
|
||
|
||
---
|
||
|
||
## 建议使用方式
|
||
|
||
1. 先写 `REQUIREMENTS.md`
|
||
2. 再按 `DEVELOPMENT.md` 进入开发
|
||
3. 开发过程中补充 `references/CLI.md`、`references/SCHEMA.md` 及 `development/` 技术规范
|
||
4. 发布前对照第 9 节验收标准逐项检查
|
||
|
||
## 最小模板示例
|
||
|
||
下面给出一个可直接参考的简化版（复制后替换占位符）：
|
||
|
||
```md
|
||
# REQUIREMENTS
|
||
|
||
## 1. 文档目标
|
||
|
||
本文档用于明确 `your-skill-slug` 的研发需求、范围和验收标准，作为开发与测试的统一依据。
|
||
|
||
## 2. 业务背景
|
||
|
||
当前用户在 `<业务场景>` 中需要反复处理 `<输入数据>`，人工操作耗时且易错。
|
||
因此需要开发 `your-skill-slug`，自动完成 `<核心动作>`，输出 `<输出结果>`，并写入 task_logs。
|
||
|
||
## 3. 开发目标
|
||
|
||
- 解析并校验输入
|
||
- 通过 adapter 完成 mock / simulator / real 档位动作
|
||
- 输出结构化结果并写入 task_logs
|
||
- 支持失败可诊断
|
||
|
||
## 4. 功能范围
|
||
|
||
- 支持 health / version / run
|
||
- 支持 logs / log-get
|
||
|
||
## 5. 非功能要求
|
||
|
||
- 入口统一为 scripts/main.py
|
||
- 保持 UTF-8 输出；结构符合 skill-template
|
||
|
||
## 6. 输入输出要求
|
||
|
||
### 输入
|
||
|
||
- target_id、input_id（按业务定义）
|
||
|
||
### 输出
|
||
|
||
- 成功 JSON / 摘要
|
||
- ERROR: 稳定错误码
|
||
- task_logs 记录
|
||
|
||
## 7. 依赖的兄弟技能或外部系统
|
||
|
||
- `<sibling-skill>`（按需）
|
||
- `<目标系统>` API 或 sandbox
|
||
|
||
## 8. 不在本次范围内的内容
|
||
|
||
- 不实现自动重试
|
||
- 不实现 `<本次不做>`
|
||
|
||
## 9. 验收标准
|
||
|
||
- 命令可运行；tests/run_tests.py -v 通过
|
||
- task_logs 符合 SCHEMA
|
||
- 正式环境安装验证通过
|
||
|
||
## 10. 开发注意事项
|
||
|
||
- 不修改无关项目；不引入旧模板结构
|
||
|
||
## 11. 变更记录
|
||
|
||
| 日期 | 版本 | 变更人 | 变更内容 |
|
||
|------|------|--------|----------|
|
||
| YYYY-MM-DD | v1.0 | 张三 | 初版 |
|
||
```
|