client-commons/skill-template
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9d33c5ea2cc8888c1e8af4b03bf91e94ba82d323
skill-template/development/REQUIREMENTS.md
chendelian 9d33c5ea2c
All checks were successful
技能自动化发布 / release (push) Successful in 5s
Details
docs: sediment TUTORIAL_SURFACES contract for README vs tutorial and three entry surfaces
2026-08-31 14:18:42 +08:00

17 KiB
Raw Blame History

技能需求文档模板

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

建议原则：

  • 一个 skill 对应一份主需求文档
  • 需求先写清楚，再进入开发
  • 涉及外部系统时先读 AI_RPA.md，明确 Agent / RPA 边界、授权、风险与人工介入
  • 文档描述“要做什么”和“做到什么程度”，不要在这里堆实现细节
  • 实现方式、代码结构、发布流程，分别放到 DEVELOPMENT.md、references/、development/ 下的技术规范

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

REQUIREMENTS

0. 技能标识（复制 REQUIREMENTS 时必填）

  • 拟定 slug（英文，符合 development/NAMING.md）：
  • 中文 name：
  • 中文 description（一句话）：
  • account-manager platform_key（如有）：
  • 命名形态：标准型 / scope 型
  • 网页 RPA（如有）— 登录策略（三选一，须写明）：
    • required：目标站必须登录才能闭环（用户须完成/保持站点登录；技能每轮主路径须有登录门禁 + 验证码/人工等待）
    • optional：登录可提升能力，但不登录也能完成主路径（仅当公开页确可闭环时选用；会话依赖型采集/评论/私信禁止默认抄成 optional）
    • not_needed：公开页即可，不要求站点登录
    • 无论上列哪一种：都必须经 account-manager ensure-web（或等价）取得 profile_dir（见 development/RPA.md §0.2）；不得使用系统默认浏览器用户目录
    • 登记 ≠ 登录：ensure/add-web 只建账号与 Profile；站点登录由本技能在有头浏览器中完成
    • 反模式：把「需要登录态才能采到数据」的需求写成 optional，再省略 ensure_logged_in

0.1 宿主入口定位（必填）

先读 PRODUCT_SURFACES.md。对话任务 / 数据管理 / 定时任务在宿主上平级；挂哪些由本技能业务与 UX 定，模板不规定「必须三入口都挂满」。用户文档如何写见 TUTORIAL_SURFACES.md。

对每个主能力填一行（可增行；「不挂」必须写理由）：

主能力（Action id / CLI） 对话 数据管理 定时 教程章节 不挂理由（若不挂）
（例）<action-or-cli> 挂 / 不挂 不挂 / toolbar / row / batch / replaces / 仅展示表 挂 / 不挂 入口一 / 入口二 / 入口三 / N/A

说明：

  • 数据管理列可写组合（如 toolbar + row）
  • 「仅展示表」= 用户要看过程/结果，但不在表上触发该能力
  • 定位为「挂」的入口须在 assets/actions.json（及必要表元数据）中落实，并与对话路径共用同一 domain service
  • 教程章节：该能力在 TUTORIAL.md 中落在哪一节；整技能无定时时，入口三仍须写「不需要 + 理由」

0.1.1 用户市场文档（与入口表一致）

  • README.md（说明 Tab）：只写能力 / 场景 / 边界；禁止分步操作与 Agent 话术（见 TUTORIAL_SURFACES.md §1）
  • TUTORIAL.md（教程 Tab）：覆盖 §0.1 中所有「挂」的入口；准备/载入类优先数据管理 toolbar，不要把 skill-detail 当主路径
  • 定位为「不挂」定时：教程须有 N/A 声明，与本表理由一致

0.2 AI + RPA 协作与授权边界（涉及外部系统时必填）

Agent 设计

  • 用户会怎样描述本任务：
  • 支持哪些用户意图；分别映射到哪个 Action：
  • 每种意图必须提取哪些参数：
  • 缺少哪些参数时必须追问：
  • 哪些动作必须先展示对象、数量和影响，再取得明确确认：
  • Agent 最终如何解释成功、部分成功、失败、等待人工和停止：

授权与平台边界

  • 目标浏览器 / 桌面软件 / 手机 App：
  • 账号、设备、数据和业务权限由谁授权：
  • 是否有获得授权的官方 API；若不用，原因是什么：
  • 目标平台规则、合同或客户约定中的自动化边界：
  • 明确禁止的实现路线：破解 / 反编译 / 逆向 / 私有协议 / 抓包拼隐藏接口 / Hook 或注入 / 验证码破解 / 设备指纹伪造 / 自动换号：
  • 正常界面无法闭环时的上报与停止条件：

RPA 风控设计

  • 执行端：浏览器 / 桌面 / Android / iOS：
  • 真实界面版本、拾取工具和拾取日期：
  • element map 文件路径；关键元素是否全部登记：
  • 每个关键元素的作用域、主定位器、匹配数量和已验证 fallback：
  • 页面 / iframe / 窗口 / 弹窗 / Native / WebView 如何选择：
  • 会话、Profile、窗口或设备如何准备与互斥：
  • 单批上限、单位时间操作量和最长运行时间：
  • 普通动作节奏（真实环境默认 1～3 秒）：
  • 页面 / 控件真实状态如何判断；禁止用固定睡眠代替的节点：
  • 哪些错误允许有限重试；退避策略：
  • 哪些信号必须立即停止（频控、封禁、权限不足、结构变化等）：
  • 哪些步骤进入人工处理（验证码、人脸、指纹、短信、U盾等）：
  • 如何防止重复提交并支持必要的断点续跑：
  • 需要保存哪些日志、截图、视频和业务结果：
  • 定位失败时如何保存 DOM/UIA/XML、候选数量和环境版本：

0.3 业务行生命周期（有「处理某一行」类能力时必填）

若本技能存在对业务表某一行做生成、触达、私信、发布等有副作用的处理，须遵守 ../references/WORK_ITEM_STATUS.md，并在此声明本技能状态 → 角色映射（状态名自定，角色固定）：

角色 本技能状态值（可多个） 说明
可操作（operable） （例）新建 / 待生成 / … 默认唯一可被处理 Action 捞起
进行中（in_progress） （例）生成中 / 触达中 / … 抢占后、结束前
成功类终态 （例）已生成 / 已私信 / … 默认不可再处理
失败类终态 （例）失败 / 触达失败 / … 默认不可再处理；失败原因字段：
跳过类终态 （例）已跳过 / … 默认不可再处理

无此类处理队列时整节写「不适用」即可。

1. 文档目标

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

模板写法：

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

2. 业务背景

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

模板写法：

  • 当前用户在 <业务场景> 中需要反复处理 <输入数据>，人工操作耗时且易错。
  • 现有流程主要依赖人工处理，存在 <效率低 / 容易出错 / 不可批量 / 不可追踪> 等问题。
  • 因此需要开发 your-skill-slug，用于自动完成 <核心动作>，输出 <输出结果>。

填写提示：

  • <业务场景>：例如“每日批量导入外部系统结果”“Agent 触发的单次查询”
  • <输入数据>：例如“关键词列表”“批次 ID”“账号标识”
  • <核心动作>：例如“调用 adapter 提交”“采集并入库”“对账摘要生成”
  • <输出结果>：例如“结构化 JSON”“任务摘要”“本地 SQLite 记录”

3. 开发目标

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

模板写法（按 skill 类型勾选/改写）：

  • 解析并校验 <输入数据> 的关键字段
  • 通过 adapter 完成 mock / simulator / real 档位下的 <核心动作>
  • 输出结构化结果（stdout JSON 或固定文本 + 机读字段）
  • 写入必要的业务表（见 references/SCHEMA.md；无业务表也可）
  • 支持失败可诊断（稳定错误码、ERROR: 前缀、必要截图/日志）
  • 完成 CLI 入口与 health / version / init-db 最小可运行验证
  • 完成正式环境发布与安装验证（如适用）

4. 功能范围

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

模板写法：

  • 支持 <命令1>（如 run）
  • 支持 <命令2>（如 health / 业务只读查询）
  • 支持读取 <数据来源>（兄弟 skill / 本地 DB / 外部 API）
  • 支持执行 <核心业务动作>
  • 支持记录 <日志 / 状态 / 结果>

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

必须实现

  • 支持 python scripts/main.py health
  • 支持 python scripts/main.py version
  • 支持 python scripts/main.py init-db（幂等建库；宿主安装/更新后可静默调用）
  • 支持 python scripts/main.py <your-main-command>
  • 支持核心业务编排（HTTP / 批处理 / 可选 RPA，按四档 adapter 选型）
  • 支持失败可诊断（统一文件日志 + 任务中心 finish）
  • 完成 PRODUCT_SURFACES.md 入口定位表，并按表落实已挂入口（对话 / 数据管理 / 定时按本技能 UX）

可后续扩展

  • 支持失败自动重试
  • 支持多 <目标系统> 轮询
  • 入口定位表中已标明「本期不挂」且写了理由的能力（例如暂不挂定时）

5. 非功能要求

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

  • 目录结构必须符合当前 skill-template 规范
  • 入口必须统一为 scripts/main.py
  • 用户市场四 Tab 写在根 README.md / TUTORIAL.md / DEMO.md / CHANGELOG.md；LLM/运行契约写在 SKILL.md；开发规范在 development/
  • 输出格式应尽量机读友好；错误前缀统一为 ERROR:
  • Windows 环境下需保证 UTF-8 输出兼容
  • 必须具备基本日志能力；敏感字段脱敏
  • 只做授权范围内的正常界面自动化；禁止破解、逆向、未授权私有协议、安全验证绕过、进程注入、凭据窃取、自动换号和无限重试
  • RPA 的页面加载与成功判断必须由真实状态驱动；正常业务动作之间默认随机等待 1～3 秒
  • RPA 类 skill：Playwright 由宿主共享 runtime 提供；技能侧不要 playwright install；URL 不要放进 launch_persistent_context 的 args
  • 网页 RPA：启动前必须经 ensure-web 拿到 profile_dir；生产有头；站点登录策略见 §0（required / optional / not_needed）；required 时每轮须登录门禁

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、init-db 命令执行正常
  • python tests/run_tests.py -v 必跑测试全部通过（mock / 离线门禁；mock 通 ≠ 完成）
  • 主命令在业务默认档（模板为 real_rpa）真实跑通；不得只 mock 通就交活
  • 业务表（若有）写入和查询符合 references/SCHEMA.md（含 created_at / updated_at Unix 秒级规范）
  • init_db() 已写入 _jiangchang_tables / _jiangchang_columns；用户可见表/字段具备中文 display_name
  • 字段展示顺序与 PRAGMA table_info(<业务表>) 的 cid 一致；不依赖 display_order
  • tests/test_display_metadata.py 通过
  • 真实联调样例仍放 tests/integration/，默认套件不包含真实外联（与业务 .env 默认 real_rpa 不冲突）
  • SKILL.md 的 developer_ids 已配置为开发者本人匠厂用户 ID（开发期不公开时，否则本人无法在市场安装自测；取 ID 步骤见 development/DEVELOPMENT.md §6）
  • 发布后 Gitea 工作流成功；匠厂技能市场对开发者账号可见最新版本并可安装
  • 安装后按本技能入口定位表与 actions.json 声明完成宿主多入口验收（见 development/DEVELOPMENT.md §15、PRODUCT_SURFACES.md）；须看用户体验（进度可见、失败可读、RPA 有头、文案与真实行为一致等），后台通了不算完
  • 已人工核验授权与技术路线：无破解、逆向、私有协议、验证码绕过、Hook / 注入、自动换号或其他规避平台限制的实现
  • RPA 真实主路径已验证状态等待、1～3 秒正常操作节奏、有限重试、账号 / 设备串行、人工介入、结果核验和结束存证
  • RPA 关键元素已在真实界面拾取并登记 element map；关键动作唯一定位，重启会话后复测通过
  • 页面/窗口/设备结构变化时停止并保存截图与 DOM/UIA/XML，不运行时猜 selector

10. 开发注意事项

  • 只修改当前 skill 仓库，不要改动无关兄弟项目
  • 正常界面或获得授权的官方 API 无法完成闭环时，停止并上报；不得擅自改走破解、逆向或绕过安全机制的路线
  • 先判断四象限类型（real_browser_rpa / real_api / simulator_browser_rpa / simulator_api），再读对应 examples/*/README.md
  • 涉及界面时再按端阅读 RPA_ELEMENT_LOCATING.md 和 RPA_BROWSER.md / RPA_DESKTOP.md / RPA_MOBILE.md
  • cli 只做参数解析；核心逻辑在 service；兄弟 skill 调用集中封装（见 ADAPTER.md）
  • 发布前完成本地验证、工作流验证和正式环境安装验证（含 developer_ids 与宿主多入口）

11. 变更记录

日期 版本 变更人 变更内容
YYYY-MM-DD v1.0 <姓名> 初版需求文档

建议使用方式

  1. 拿到业务技能仓库（Gitea clone，或本地从 skill-template scaffold / 复制；见 DEVELOPMENT.md §4）
  2. 先写 / 填全本文件 REQUIREMENTS.md
  3. 再按 DEVELOPMENT.md 进入开发（含尽早配置 developer_ids）
  4. 开发过程中补充 references/CLI.md、references/SCHEMA.md 及 development/ 技术规范
  5. 发布前对照第 9 节验收标准逐项检查；release 后按 DEVELOPMENT.md §15 做宿主多入口验收

最小模板示例

下面给出一个可直接参考的简化版（复制后替换占位符）：

# REQUIREMENTS

## 1. 文档目标

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

## 2. 业务背景

当前用户在 `<业务场景>` 中需要反复处理 `<输入数据>`，人工操作耗时且易错。
因此需要开发 `your-skill-slug`，自动完成 `<核心动作>`，输出 `<输出结果>`。

## 3. 开发目标

- 解析并校验输入
- 通过 adapter 完成 mock / simulator / real 档位动作
- 输出结构化结果；业务结果写入业务表（有才建）
- 支持失败可诊断

## 4. 功能范围

- 支持 health / version / init-db / run

## 5. 非功能要求

- 入口统一为 scripts/main.py
- 保持 UTF-8 输出；结构符合 skill-template

## 6. 输入输出要求

### 输入

- target_id、input_id（按业务定义）

### 输出

- 成功 JSON / 摘要
- ERROR: 稳定错误码
- 任务中心终态（`finish`）

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

- `<sibling-skill>`（按需）
- `<目标系统>` API 或 sandbox

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

- 不实现自动重试
- 不实现 `<本次不做>` 

## 9. 验收标准

- 命令可运行；tests/run_tests.py -v 通过
- 业务表（若有）符合 SCHEMA；过程看运行日志，进度看任务中心
- `developer_ids` 已配置为「你的用户ID」（匠厂设置中复制的正整数）
- 正式环境安装验证通过；已声明的宿主入口（新建任务 / 数据管理 / 定时任务 / 任务中心 / 技能详情等）按 DEVELOPMENT §15 与入口定位表自测
## 10. 开发注意事项

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

## 11. 变更记录

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