client-commons/skill-template
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6b64aad138bce982c2e7c597c8522ad6b2c770c8
skill-template/development/REQUIREMENTS.md
chendelian 6b64aad138
All checks were successful
技能自动化发布 / release (push) Successful in 4s
Details
feat: add standard init-db CLI for host install schema ensure
2026-07-14 17:26:24 +08:00

9.2 KiB
Raw Blame History

技能需求文档模板

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

建议原则：

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

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

REQUIREMENTS

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

  • 拟定 slug（英文，符合 development/NAMING.md）：
  • 中文 name：
  • 中文 description（一句话）：
  • account-manager platform_key（如有）：
  • 命名形态：标准型 / scope 型

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 / init-db 最小可运行验证
  • 完成正式环境发布与安装验证（如适用）

4. 功能范围

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

模板写法：

  • 支持 <命令1>（如 run）
  • 支持 <命令2>（如 logs / log-get）
  • 支持读取 <数据来源>（兄弟 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 选型）
  • 支持写入任务日志（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、init-db 命令执行正常
  • 主命令（如 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 节验收标准逐项检查

最小模板示例

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

# REQUIREMENTS

## 1. 文档目标

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

## 2. 业务背景

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

## 3. 开发目标

- 解析并校验输入
- 通过 adapter 完成 mock / simulator / real 档位动作
- 输出结构化结果并写入 task_logs
- 支持失败可诊断

## 4. 功能范围

- 支持 health / version / init-db / 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 | 张三 | 初版 |
Reference in New Issue View Git Blame Copy Permalink