From 8101b5ac019c40458564dc51e5a3520355ce8df1 Mon Sep 17 00:00:00 2001 From: chendelian <116870791@qq.com> Date: Mon, 20 Jul 2026 10:30:36 +0800 Subject: [PATCH] docs: add extensible SHARED_REPOS catalog for public commons --- CHANGELOG.md | 5 ++ SKILL.md | 2 +- development/DEVELOPMENT.md | 2 + development/README.md | 25 +++---- development/RPA.md | 2 + development/RUNTIME.md | 2 + development/SHARED_REPOS.md | 128 ++++++++++++++++++++++++++++++++++++ scripts/util/constants.py | 2 +- tools/README.md | 2 +- 9 files changed, 156 insertions(+), 14 deletions(-) create mode 100644 development/SHARED_REPOS.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 1ad608b..f5564e1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,11 @@ - 小节正文写用户能看懂的变化（新能力、修复、注意事项），避免堆砌内部实现细节 - 打 tag 前**必须**为即将发布的版本新增一节；找不到匹配小节时，本次发布不会更新 changelog 字段 +## 1.0.54 + +- 新增 `development/SHARED_REPOS.md`：可扩展的公开公共仓目录（skill-template / account-manager / jiangchang-platform-kit），含类型、Gitea 地址、clone 与红线 +- 开发入口与 RUNTIME / RPA / tools 文档挂接该目录，便于技术人员与 AI 定位公共依赖 + ## 1.0.53 - 宿主入口对齐：`row` / `batch` 升格为正式 placements；支持 `bind.inputMapping` 与 `readOnly`；已声明入口均须自测（含技能详情直调） diff --git a/SKILL.md b/SKILL.md index a0adad0..e4dead2 100644 --- a/SKILL.md +++ b/SKILL.md @@ -1,7 +1,7 @@ --- name: 技能开发模板（通用业务版） description: "OpenClaw 通用业务技能开发模板，供复制后定制新业务 skill。定制步骤见 development/DEVELOPMENT.md。" -version: 1.0.53 +version: 1.0.54 author: 深圳匠厂科技有限公司 metadata: openclaw: diff --git a/development/DEVELOPMENT.md b/development/DEVELOPMENT.md index f34cacc..2b9db17 100644 --- a/development/DEVELOPMENT.md +++ b/development/DEVELOPMENT.md @@ -24,6 +24,8 @@ 官方下载与文档以各产品站点为准；技能开发步骤以本文与同目录规范为准，不依赖某一家工具的专有流程。 +开发中常用的**公开公共仓**（skill-template / account-manager / jiangchang-platform-kit 等，可 `git clone` 学习，目录可扩展）见 [`SHARED_REPOS.md`](SHARED_REPOS.md)。 + ## 1. 先理解模板的定位 `skill-template` 不是业务 skill，它只是一个**新 skill 仓库模板**。 diff --git a/development/README.md b/development/README.md index 5ee5640..ecbaf48 100644 --- a/development/README.md +++ b/development/README.md @@ -17,21 +17,24 @@ 脚手架与 Git 防串库：[`../tools/README.md`](../tools/README.md)（`scaffold_skill.ps1`）。业务仓也可直接从自建 Gitea clone，见 [`DEVELOPMENT.md`](DEVELOPMENT.md) §4 来源 A。 +**公开公共仓（可 clone 学习，可扩展登记）：** [`SHARED_REPOS.md`](SHARED_REPOS.md) — 当前含 skill-template、account-manager、jiangchang-platform-kit。 + ## 深度规范阅读顺序 开始定制 skill 前，建议按以下顺序阅读： -1. [`REQUIREMENTS.md`](REQUIREMENTS.md) — 需求文档模板与验收标准 -2. [`NAMING.md`](NAMING.md) — slug / 仓库名命名规范（复制模板前必读） -3. [`DEVELOPMENT.md`](DEVELOPMENT.md) — 完整开发步骤与目录规范 -4. [`TESTING.md`](TESTING.md) — 测试分层、隔离数据根与档位开关 -5. [`LOGGING.md`](LOGGING.md) — 日志分层、必打节点、敏感信息红线（**涉及长任务、RPA、外部系统时必读**） -6. [`ADAPTER.md`](ADAPTER.md) — 涉及外部系统对接时 -7. [`RPA.md`](RPA.md) — 涉及浏览器 / 桌面 / 手机自动化时 -8. [`CONFIG.md`](CONFIG.md) — `.env` 规范与 bootstrap 机制 -9. [`DATA_PATHS.md`](DATA_PATHS.md) — 下载/导入/导出等本地文件路径标准（涉及文件读写时必读） -10. [`SKILL_ACTION_RUNTIME.md`](SKILL_ACTION_RUNTIME.md) — Skill Action sync/async、任务中心、Agent 禁令、队列 pick（涉及 RPA / 长任务 / 数据管理按钮 / Cron / Agent 时必读） -11. [`RUNTIME.md`](RUNTIME.md) — 共享 runtime、数据路径、发布打包与编码约定 +1. [`SHARED_REPOS.md`](SHARED_REPOS.md) — **公共仓库目录**（模板 / 账号管理 / platform-kit 等，可扩展） +2. [`REQUIREMENTS.md`](REQUIREMENTS.md) — 需求文档模板与验收标准 +3. [`NAMING.md`](NAMING.md) — slug / 仓库名命名规范（复制模板前必读） +4. [`DEVELOPMENT.md`](DEVELOPMENT.md) — 完整开发步骤与目录规范 +5. [`TESTING.md`](TESTING.md) — 测试分层、隔离数据根与档位开关 +6. [`LOGGING.md`](LOGGING.md) — 日志分层、必打节点、敏感信息红线（**涉及长任务、RPA、外部系统时必读**） +7. [`ADAPTER.md`](ADAPTER.md) — 涉及外部系统对接时 +8. [`RPA.md`](RPA.md) — 涉及浏览器 / 桌面 / 手机自动化时 +9. [`CONFIG.md`](CONFIG.md) — `.env` 规范与 bootstrap 机制 +10. [`DATA_PATHS.md`](DATA_PATHS.md) — 下载/导入/导出等本地文件路径标准（涉及文件读写时必读） +11. [`SKILL_ACTION_RUNTIME.md`](SKILL_ACTION_RUNTIME.md) — Skill Action sync/async、任务中心、Agent 禁令、队列 pick（涉及 RPA / 长任务 / 数据管理按钮 / Cron / Agent 时必读） +12. [`RUNTIME.md`](RUNTIME.md) — 共享 runtime、数据路径、发布打包与编码约定 Agent 调用契约见 [`../references/CLI.md`](../references/CLI.md)、[`../references/SCHEMA.md`](../references/SCHEMA.md)、[`../references/ACTIONS.md`](../references/ACTIONS.md)。 用户市场四 Tab 见根目录 [`README.md`](../README.md) / [`TUTORIAL.md`](../TUTORIAL.md) / [`DEMO.md`](../DEMO.md) / [`CHANGELOG.md`](../CHANGELOG.md)，不要写进本目录。 diff --git a/development/RPA.md b/development/RPA.md index c38dec6..395c999 100644 --- a/development/RPA.md +++ b/development/RPA.md @@ -2,6 +2,8 @@ > 本文是团队 RPA 开发的**统一标准**。任何需要"自动操作软件界面"的 skill，都应先读这份文档，按这里的选型和范式落地，不要每个项目重新踩坑。 +网页账号 / Profile 依赖公开兄弟技能 **account-manager**；浏览器 RPA 原语来自 **jiangchang-platform-kit**。二者 Gitea 地址、clone 方式与红线见 [`SHARED_REPOS.md`](SHARED_REPOS.md)。 + 我们开发的各类 skill，本质上都是在替人操作三类界面：**浏览器、桌面软件、手机软件**。三类的底层技术不同，但**工程范式相同**：可控会话（Profile）、有头运行、拟人操作、失败存证、人工兜底。 --- diff --git a/development/RUNTIME.md b/development/RUNTIME.md index 84ecff9..72a6b73 100644 --- a/development/RUNTIME.md +++ b/development/RUNTIME.md @@ -6,6 +6,8 @@ 技能根目录 `requirements.txt` **只声明技能特有依赖**；**不要**重复声明 `jiangchang-platform-kit` 或 `playwright`。`SKILL.md` 的 `platform_kit_min_version` 是运行契约，**不是** pip 依赖声明。 +kit **源码仓**（可 clone 学习，勿 vendor）与其它公开公共仓登记见 [`SHARED_REPOS.md`](SHARED_REPOS.md)。 + ### 何时上调 `platform_kit_min_version` | 情况 | 做法 | diff --git a/development/SHARED_REPOS.md b/development/SHARED_REPOS.md new file mode 100644 index 0000000..d0fd6bc --- /dev/null +++ b/development/SHARED_REPOS.md @@ -0,0 +1,128 @@ +# 公共仓库目录（可扩展） + +本页是技能开发用到的**公开公共仓唯一登记处**，面向技术人员与 AI 编程代理。 + +- 仓均在公司**自建 Gitea**：[https://git.jc2009.com/](https://git.jc2009.com/)（基于开源 Gitea 自建，**不是** Gitea 官网）。 +- 技术人员一般**可直接访问、随时 `git clone` 到本地**，用于研究、学习、对照与跟进更新。 +- **当前登记 3 项**；以后新增公开公共仓时，**只在本页按类型加行**，不必改散落长文。 + +深度规范仍在 [`RPA.md`](RPA.md)、[`RUNTIME.md`](RUNTIME.md)、[`ADAPTER.md`](ADAPTER.md)、[`DEVELOPMENT.md`](DEVELOPMENT.md)；本页只做**指路 + 边界**。 + +--- + +## 1. 类型（可扩展） + +| 类型 id | 含义 | 典型消费方式 | +|---------|------|--------------| +| `skill-template` | 业务技能作者脚手架与规范源 | clone 学习；`scaffold` / 复制出新业务仓；**不要**在模板仓写业务 | +| `sibling-skill` | 与业务技能并列安装的公开基础设施技能 | clone 学契约；运行时经 **CLI / 封装客户端** 调用 | +| `python-sdk` | 共享 Python 库（源码仓 + 宿主共享 venv 安装） | clone 读实现 / 贡献；运行时 **`import`**，**禁止 vendor** 进技能仓 | +| `asset-bundle` | （预留）共享媒体/资源包等 | 按该仓说明拉取或由 kit/宿主解析 | +| `tooling` | （预留）发布脚本、脚手架、CI 辅助等 | clone 使用或引用其 workflow | + +新增类型时：先在本表加一行类型说明，再在 §2 登记表增加实例。 + +--- + +## 2. 当前登记表 + +| 短名 | 类型 | Gitea（唯一入口） | 一句话职责 | +|------|------|-------------------|------------| +| **skill-template** | `skill-template` | [https://git.jc2009.com/client-commons/skill-template](https://git.jc2009.com/client-commons/skill-template) | 新业务技能的开发模板、目录规范与发布约定 | +| **account-manager** | `sibling-skill` | [https://git.jc2009.com/client-commons/account-manager](https://git.jc2009.com/client-commons/account-manager) | 账号 / 凭据 / 浏览器 Profile / 租约的统一入口 | +| **jiangchang-platform-kit** | `python-sdk` | [https://git.jc2009.com/client-jiangchang/jiangchang-platform-kit](https://git.jc2009.com/client-jiangchang/jiangchang-platform-kit) | 共享 SDK（`jiangchang_skill_core` 等）；技能发布可复用 CI 也在此仓 | + +本地常见路径（仅作对照，以你机器为准）： + +- `D:\OpenClaw\client-commons\skill-template` +- `D:\OpenClaw\client-commons\account-manager` +- `D:\OpenClaw\client-jiangchang\jiangchang-platform-kit` + +### 2.1 skill-template + +| 项 | 说明 | +|----|------| +| **Clone 为了什么** | 读 `development/`、跟模板版本、用 `tools/scaffold_skill` 开新技能 | +| **怎么用** | 来源 B：scaffold；或学完后在业务仓开发。规范以本仓为准 | +| **红线** | 不要在模板仓写业务；业务仓 `origin` 不得指向本仓；不得保留 `.openclaw-skill-template` | +| **深入** | 本目录 [`README.md`](README.md)、[`DEVELOPMENT.md`](DEVELOPMENT.md) | + +```powershell +git clone https://git.jc2009.com/client-commons/skill-template.git +``` + +### 2.2 account-manager + +| 项 | 说明 | +|----|------| +| **Clone 为了什么** | 读 CLI / `references/INTEGRATION.md`、平台表、租约与错误码；排 `NO_ACCOUNT` / `LEASE_CONFLICT` 等 | +| **怎么用（业务技能）** | 经 `scripts/service/account_client.py`（或等价）**subprocess 调 CLI**；网页 RPA 须先拿到 `profile_dir`（`ensure-web` / `pick-web`） | +| **红线** | **禁止**业务技能 `import` 其内部 `rpa_helpers` / 散落存密码（见 `POLICY-RPA-001`）；对方文档若写「同进程 rpa_helpers」，**以本模板约束为准** | +| **深入** | 对方仓 `references/INTEGRATION.md`、`CLI.md`；本模板 [`RPA.md`](RPA.md) §0.2、[`ADAPTER.md`](ADAPTER.md) | + +```powershell +git clone https://git.jc2009.com/client-commons/account-manager.git +``` + +### 2.3 jiangchang-platform-kit + +| 项 | 说明 | +|----|------| +| **Clone 为了什么** | 读 `jiangchang_skill_core`（config / logging / activity·SRCP / rpa / sibling_bridge 等）、跟版本、贡献共享 API | +| **怎么用（业务技能）** | 运行时由**宿主共享 venv** 提供；技能内 `import jiangchang_skill_core...`。`SKILL.md` 的 `platform_kit_min_version` 是兼容声明 | +| **红线** | **不要**把 `jiangchang-platform-kit` / `playwright` 写入技能 `requirements.txt`；**不要**在技能仓 vendor `jiangchang_skill_core/`（`POLICY-RUNTIME-002`） | +| **深入** | 对方仓 `README.md`；本模板 [`RUNTIME.md`](RUNTIME.md)、[`LOGGING.md`](LOGGING.md) | + +```powershell +git clone https://git.jc2009.com/client-jiangchang/jiangchang-platform-kit.git +``` + +私有 PyPI 索引（维护/排障用，日常技能开发通常不必手装）： +`https://git.jc2009.com/api/packages/client-jiangchang/pypi/simple/` + +--- + +## 3. 三者关系（别当成三个无关收藏夹） + +```text +规范 / 脚手架 ──────────► skill-template（本仓） + │ +业务技能 scripts/ ──import──► 宿主共享 venv 中的 platform-kit + │ + └──CLI──► account-manager（兄弟技能，要先拿到 profile_dir 等） +``` + +- **写规范、开新仓** → 打开 **skill-template** +- **少写公共 Python、进度/RPA 原语** → 用 **kit**（运行靠宿主；源码可 clone） +- **账号与浏览器 Profile** → 用 **account-manager**（运行靠 CLI；源码可 clone） + +--- + +## 4. 何时该打开哪个仓 + +| 场景 | 优先打开 | +|------|----------| +| 不知道新技能目录/发布/developer_ids 怎么做 | **skill-template** `development/` | +| 定 `platform_key`、ensure-web、租约、凭证存储 | **account-manager** + 本模板 RPA/ADAPTER | +| 看 `emit` / `finish` / `@rpa_step` / `launch_persistent_browser` 实现 | **jiangchang-platform-kit** | +| 技能发布 CI / reusable workflow 从哪来 | **jiangchang-platform-kit** `.github/workflows/` | +| 「公共东西到底在哪」 | **本页登记表** | + +--- + +## 5. 以后如何新增一条公共仓（维护约定） + +1. 确认公开可访问，URL 使用 `https://git.jc2009.com/...`（勿写 Gitea 官网）。 +2. 选定或新增 §1 **类型**。 +3. 在 §2 **登记表**加一行；必要时增加 `§2.x` 短节（消费方式 + 红线 + clone 示例）。 +4. 若改变业务技能硬约束，同步 [`POLICY_MATRIX.md`](POLICY_MATRIX.md) / 相关深度文档。 +5. **不要**只在某个业务技能 README 里私藏链接而不登记本页。 + +--- + +## 6. 相关链接 + +- 开发入口：[`README.md`](README.md) +- 运行时：[`RUNTIME.md`](RUNTIME.md) +- 网页 RPA / 账号：[`RPA.md`](RPA.md)、[`ADAPTER.md`](ADAPTER.md) +- 脚手架：[`../tools/README.md`](../tools/README.md) diff --git a/scripts/util/constants.py b/scripts/util/constants.py index 7df6e3b..f738230 100644 --- a/scripts/util/constants.py +++ b/scripts/util/constants.py @@ -1,6 +1,6 @@ """技能标识、版本与平台公共库约束（复制后请修改 slug/version/logger）。""" SKILL_SLUG = "your-skill-slug" -SKILL_VERSION = "1.0.53" +SKILL_VERSION = "1.0.54" LOG_LOGGER_NAME = "openclaw.skill.your_skill_slug" PLATFORM_KIT_MIN_VERSION = "1.2.2" diff --git a/tools/README.md b/tools/README.md index 006ce88..7bd6a66 100644 --- a/tools/README.md +++ b/tools/README.md @@ -8,7 +8,7 @@ git clone https://git.jc2009.com//.git ``` -完整说明见 [`../development/DEVELOPMENT.md`](../development/DEVELOPMENT.md) §4「来源 A」。下面脚手架用于**本地已有 skill-template、要新建尚未灌仓目录**的场景（来源 B）。 +完整说明见 [`../development/DEVELOPMENT.md`](../development/DEVELOPMENT.md) §4「来源 A」。公开公共仓（含本模板、account-manager、platform-kit）登记见 [`../development/SHARED_REPOS.md`](../development/SHARED_REPOS.md)。下面脚手架用于**本地已有 skill-template、要新建尚未灌仓目录**的场景（来源 B）。 ## 推荐：脚手架创建新技能