client-commons/skill-template
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: auto release commit (2026-07-03 12:09:55)
All checks were successful
技能自动化发布 / release (push) Successful in 5s
Details

Browse Source
This commit is contained in:
chendelian
2026-07-03 12:09:55 +08:00
parent 7136689efe
commit 4a0be93b4a
22 changed files with 1613 additions and 575 deletions
Download Patch File Download Diff File Expand all files Collapse all files

391
development/REQUIREMENTS.md
View File

@@ -1,259 +1,200 @@
# 技能需求文档模板
这份文档用于给技术人员、产品人员和实施人员统一描述某个 skill 的研发需求。
建议原则：
- 一个 skill 对应一份主需求文档
- 需求先写清楚，再进入开发
- 文档描述“要做什么”和“做到什么程度”，不要在这里堆实现细节
- 实现方式、代码结构、发布流程，分别放到 `DEVELOPMENT.md`、`references/`、`development/` 下的技术规范
如果你是从 `skill-template` 复制新技能，请复制本文件后，把下面所有占位内容替换成你的真实项目内容。
---
# REQUIREMENTS
## 0. 技能标识（复制 REQUIREMENTS 时必填）
- 拟定 slug（英文，符合 `development/NAMING.md`）：
- 中文 name：
- 中文 description（一句话）：
- account-manager platform_key（如有）：
- 命名形态：标准型 / scope 型
| 项 | 值 |
|----|-----|
| slug | `download-settlement-report-amazon` |
| 中文 name | Amazon 结算报表自动下载 |
| 中文 description | 在 Amazon 卖家中心自动请求并下载结算报表（Settlement） |
| account-manager platform_key | `amazon_sim`（若尚未注册，见 README / 本文 §7） |
| 命名形态 | 标准型（verb-noun-platform） |
## 1. 文档目标
说明这份需求文档的作用，以及它解决什么问题。
模板写法：
- 本文档用于明确 `your-skill-slug` 的研发范围、交付标准、依赖关系和验收要求。
- 本文档用于明确 `download-settlement-report-amazon` 的研发范围、交付标准、依赖关系和验收要求。
- 技术人员应以本文件作为开发范围依据，以避免实现偏差、范围蔓延或理解不一致。
- 本文档同时作为**老师/实训样板**：学员可复制本技能结构开发同类 Amazon / 跨境报表技能。
## 2. 业务背景
说明为什么要做这个 skill，它服务什么业务场景，解决什么实际问题。
模板写法：
- 当前用户在 `<业务场景>` 中需要反复处理 `<输入数据>`，人工操作耗时且易错。
- 现有流程主要依赖人工处理，存在 `<效率低 / 容易出错 / 不可批量 / 不可追踪>` 等问题。
- 因此需要开发 `your-skill-slug`，用于自动完成 `<核心动作>`，输出 `<输出结果>`，并写入 `task_logs` 便于追踪。
填写提示：
- `<业务场景>`：例如“每日批量导入外部系统结果”“Agent 触发的单次查询”
- `<输入数据>`：例如“关键词列表”“批次 ID”“账号标识”
- `<核心动作>`：例如“调用 adapter 提交”“采集并入库”“对账摘要生成”
- `<输出结果>`：例如“结构化 JSON”“任务摘要”“本地 SQLite 记录”
- 跨境财务实训需定期从 Amazon 下载**结算报表（Settlement）**，用于对账、利润分析与凭证附件。
- 人工操作路径：登录卖家中心 → Reports → **Payments** 分类 → 选择 Settlement → 填写日期 → 请求 → 等待生成 → 下载 xlsx。
- 本技能用 **Playwright RPA** 在仿真环境 `https://sandbox.jc2009.com/industries/ecommerce/amazon` 自动完成上述流程，产出 xlsx 并写入 `task_logs`（`task_type=download_settlement`）。
- **禁止**调用 `GET/POST /api/ecommerce/amazon/reports` 等 REST API 下载；必须走浏览器页面操作。
## 3. 开发目标
说明本次开发希望最终交付什么结果。
模板写法（按 skill 类型勾选/改写）：
- 解析并校验 `<输入数据>` 的关键字段
- 通过 adapter 完成 mock / simulator / real 档位下的 `<核心动作>`
- 输出结构化结果（stdout JSON 或固定文本 + 机读字段）
- 写入 `task_logs`（及必要的业务表，见 `references/SCHEMA.md`）
- 支持失败可诊断（稳定错误码、`ERROR:` 前缀、必要截图/日志）
- 完成 CLI 入口与 `health` / `version` 最小可运行验证
- 完成正式环境发布与安装验证（如适用）
- 提供标准 CLI：`health`、`version`、`run`、`logs`、`log-get`
- 实现四档 adapter 中的 **mock**（CI 默认）与 **simulator_rpa**（联调）
- 集成 **account-manager**：`pick-web --platform amazon_sim --lease` 获取 `profile_dir` 与租约
- 登录：`launch_browser_with_profile` + `ensure_logged_in`（account-manager `rpa_helpers`）
- 下载文件保存至 `{skill_data_dir}/downloads/`；失败截图至 `{skill_data_dir}/rpa-artifacts/{batch_id}/`
- 可选 `RpaVideoSession` 录屏（中文步骤标题）
## 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`）
- `python scripts/main.py health`
- `python scripts/main.py version`
- `python scripts/main.py run --date-from YYYY-MM-DD --date-to YYYY-MM-DD [--seller-code CODE]`
- Playwright RPA（`OPENCLAW_TEST_TARGET=simulator_rpa`）
- mock adapter（CI 默认，`OPENCLAW_TEST_TARGET=mock`）
- 写入 `task_logs`（`task_type=download_settlement`）
- 下载文件保存到 `{skill_data_dir}/downloads/`
- 失败截图到 `rpa-artifacts/`
### 可后续扩展
### 第一版不做
- 支持定时批跑
- 支持失败自动重试
- 支持多 `<目标系统>` 轮询
- 解析 xlsx 内容
- 多店铺批量下载
- 直接调 `/api/ecommerce/amazon/reports` API
- `real_rpa` 真实 Amazon 生产站点
## 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`
- 目录结构符合 `skill-template` 规范；入口 `scripts/main.py`
- Playwright 由宿主共享 runtime 提供；技能侧不要 `playwright install`
- URL **不要**放进 `launch_persistent_context(args=[...])`；Reports 页通过 `page.goto(REPORTS_URL)` 打开
- 元素定位优先 `data-testid`（F12 原则）
- 步骤间 `random_delay`；禁止 `el.value=`、JS 跳转
- Windows UTF-8 输出；错误前缀 `ERROR:`
## 6. 输入输出要求
### 输入
填写本 skill 实际接受的参数与数据来源：
| 参数 | 必填 | 默认 | 说明 |
|------|------|------|------|
| `--date-from` | 是* | `2025-12-01` | 报表起始日期 |
| `--date-to` | 是* | `2025-12-31` | 报表结束日期 |
| `--seller-code` | 否 | 页面第一个 seller | 店铺代码，如 `AMA1OF6T` |
- `<参数名>`：含义、是否必填、默认值
- `<依赖系统>` 返回的结构化数据（如有）
- 环境变量 / `.env` 中的关键配置（引用 `CONFIG.md`）
\* CLI 提供默认值，业务上仍须为合法 `YYYY-MM-DD`。
### 输出
环境变量见 `.env.example`：`AMAZON_SIM_BASE_URL`、`AMAZON_SIM_REPORTS_URL`、`OPENCLAW_TEST_TARGET` 等。
- 成功结果（stdout / JSON 字段说明）
- 错误输出（`ERROR:` 稳定码 + 中文 message）
- 数据库记录（表名、关键字段，见 `references/SCHEMA.md`）
- 可选：RPA 截图/视频路径（artifacts）
### 成功输出（stdout JSON）
## 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`（含 `created_at` / `updated_at` Unix 秒级规范）
- `init_db()` 已写入 `_jiangchang_tables` / `_jiangchang_columns`；用户可见表/字段具备中文 `display_name`
- 字段展示顺序与 `PRAGMA table_info(task_logs)` 的 cid 一致；不依赖 `display_order`
- `tests/test_display_metadata.py` 通过
- 真实联调（如有）放在 `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 | 张三 | 初版 |
```json
{
"ok": true,
"job_id": "...",
"file_path": "...",
"filename": "settlement_....xlsx",
"date_from": "2025-12-01",
"date_to": "2025-12-31"
}
```
### 失败输出
- 退出码非 0
- stdout JSON 中 `ok: false` 或前置 `ERROR:` 行（如 `ERROR:INVALID_ARGS`）
- `task_logs.status=failed`，`error_msg` 含原因
- 可选：`rpa-artifacts/` 下 PNG 截图
## 7. 依赖的兄弟技能或外部系统
### 兄弟技能
- **account-manager**：`platform_key=amazon_sim`；提供 `profile_dir`、租约、`get-credential --reveal`
- 若 `amazon_sim` 平台不存在，需运维在 account-manager 注册后再添加账号
添加账号示例：
```bash
python D:\OpenClaw\client-commons\account-manager\scripts\main.py account add-web \
--platform amazon_sim \
--login-id <邮箱> \
--url https://sandbox.jc2009.com/industries/ecommerce/amazon/login \
--environment simulator \
--auth-strategy password_auto
```
`extra_json` 建议：`{"logged_in_url_pattern": "/seller"}`
Amazon 仿真登录：登录页为**邮箱 + Continue**，无复杂验证码。
### 外部系统
| 页面 | URL |
|------|-----|
| 卖家首页 | `https://sandbox.jc2009.com/industries/ecommerce/amazon/seller` |
| 登录页 | `https://sandbox.jc2009.com/industries/ecommerce/amazon/login` |
| Reports | `https://sandbox.jc2009.com/industries/ecommerce/amazon/seller/reports` |
**禁止**使用 `localhost:5173`。
## 8. 不在本次范围内的内容
- 不解析 xlsx、不入账 Kingdee / 星航
- 不实现多店铺批跑
- 不修改 `client-sandbox` 源码
- 不修改 `skill-template` 源仓库
- 不实现 `real_api` / 生产 Amazon `real_rpa`
## 9. 验收标准与 RPA 步骤
### RPA 步骤（与 sandbox 联调文档一致）
参考：`client-sandbox/sandbox-docs/migration/from-monolith-docs/skill-integration-guide.md`
1. `account-manager pick-web --platform amazon_sim --lease` → `profile_dir`、`url`、`lease_token`
2. `launch_browser_with_profile` + `ensure_logged_in`
3. `page.goto(REPORTS_URL)`（URL 不进 launch args）
4. 等待 `[data-testid="reports-page-root"]`
5. 切换到 **Payments** 分类（Settlement 在该 Tab；默认 Tab 为 Fulfillment）
- 优先 `[data-testid="reports-tab-payments"]`
- 若无 testid，用 `get_by_role("button", name="Payments")`
6. 点击 `[data-testid="reports-type-item-settlement"]`
7. 填写 `[data-testid="reports-form-date-from"]` / `reports-form-date-to`
8. 可选：`[data-testid="reports-form-seller-select"]`
9. 点击 `[data-testid="reports-form-submit"]`
10. 轮询 `[data-testid^="reports-jobs-status-"][data-status="DONE"]`（超时 60s，间隔 2s）
11. 点击 `[data-testid^="reports-jobs-download-"]`，`expect_download` 保存 xlsx
12. `lease release`
13. 写 `task_logs` + 返回 JSON
### 仿真环境已知依赖（Payments Tab）
截至开发时，`sim-ecommerce-amazon/frontend/pages/ReportsPage.jsx` 中：
- 已定义 `REPORT_TABS`（含 Payments），且 `settlement` 类型挂载在 `payments` Tab 下
- **但页面未渲染 Tab 切换按钮**（无 `reports-tab-payments` DOM），默认 `activeTab=fulfillment`，页面上仅显示 Orders 类型
因此 **线上仿真** 联调时，RPA 可能在步骤 5 失败（Payments Tab 不可见）。处理方式：
- **mock 测试**必须全部通过（CI 不依赖 Tab UI）
- **simulator_rpa** 代码已实现 Tab 切换逻辑，待 sandbox 前端补充 Tab UI 后即可联调
- 联调前可请 sandbox 团队在 Reports 页渲染 Tab 并添加 `data-testid="reports-tab-payments"`
### 命令验收
- `python tests/run_tests.py -v` 全部通过
- `python scripts/main.py health` 退出码 0
- `OPENCLAW_TEST_TARGET=mock python scripts/main.py run --date-from 2025-12-01 --date-to 2025-12-31` 退出码 0 且产出 mock xlsx
### 联调验收（有账号时）
```powershell
$env:OPENCLAW_TEST_TARGET="simulator_rpa"
$env:JIANGCHANG_DATA_ROOT="D:\claw-data"
$env:JIANGCHANG_USER_ID="10032"
python scripts/main.py run --date-from 2025-12-01 --date-to 2025-12-31
```
成功：产出 xlsx + `task_logs` 有 `download_settlement` 记录 + 退出码 0。
## 10. 开发注意事项
- 只修改本 skill 仓库；不改动其他 61 个空目录
- adapter 目录：`scripts/service/amazon_report_adapter/`
- 真实浏览器联调样例：`tests/integration/test_simulator_rpa_contract.py.sample`（不进默认套件）
## 11. 变更记录
| 日期 | 版本 | 变更人 | 变更内容 |
|------|------|--------|----------|
| 2026-07-03 | v1.0.0 | 样板实现 | 初版：mock + simulator_rpa + REQUIREMENTS 填实 |