From 3cde0d9ce2a22a1caed548d2b5cd7e840f8fb8da Mon Sep 17 00:00:00 2001 From: yumoqing Date: Mon, 24 Aug 2026 16:33:54 +0800 Subject: [PATCH] =?UTF-8?q?feat(skills):=20=E6=9C=BA=E6=9E=84=E5=B7=A5?= =?UTF-8?q?=E4=BD=9C=E7=A9=BA=E9=97=B4=E7=9B=AE=E5=BD=95=E9=87=8D=E6=9E=84?= =?UTF-8?q?=E2=80=94=E2=80=94projects/apps/modules=20=E4=B8=89=E7=9B=AE?= =?UTF-8?q?=E5=BD=95=20+=20=E9=A1=B9=E7=9B=AE=E5=8E=BB=20repos/references?= =?UTF-8?q?=20=E6=94=B9=20app=20spec.json(=E5=BC=95=E7=94=A8/=E7=94=9F?= =?UTF-8?q?=E6=88=90=E6=A8=A1=E5=9D=97)=20+=20=E5=BA=94=E7=94=A8/=E6=A8=A1?= =?UTF-8?q?=E5=9D=97=E8=90=BD=E7=82=B9=E6=94=B9=E6=9C=BA=E6=9E=84=20apps/m?= =?UTF-8?q?odules=20+=20=E9=83=A8=E7=BD=B2=E5=89=8D=E8=AE=BE=E7=BD=AE?= =?UTF-8?q?=E8=BF=9C=E7=A8=8B=E4=BB=93=E5=BA=93?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../all/module-development-spec/SKILL.md | 6 + .../all/project-directory-spec/SKILL.md | 181 ++++++++---------- .../all/web-application-spec/SKILL.md | 6 + 3 files changed, 91 insertions(+), 102 deletions(-) diff --git a/skills_library/all/module-development-spec/SKILL.md b/skills_library/all/module-development-spec/SKILL.md index 78a4b17..37adccc 100644 --- a/skills_library/all/module-development-spec/SKILL.md +++ b/skills_library/all/module-development-spec/SKILL.md @@ -23,6 +23,12 @@ This skill defines the complete workflow for standardized modules: ahserver ecos - **A module is NOT an independently deployable unit.** It has NO standalone `app.py` entry point, NO own port, NO own Dockerfile/service, NO own deploy script. It only runs because a host application calls `load_{module}()`. A module that carries its own `app.py` / port / deploy script is wrongly built — fix the module, don't deploy it separately. - **Interaction-layer modules** (e.g. pipeline-task) have NO data tables — pure thin wrappers calling other modules' functions via ServerEnv; they provide .dspy + .ui only. +## 模块本地仓库位置 + +在 pipeline 产线机构工作空间中，模块本地仓库在机构 `modules/{模块名}/`（见 project-directory-spec）。模块是应用内的功能模块（Python 包），不是独立部署单元。 + +**部署测试前必须给模块仓库设置远程仓库**（`git remote add origin <远程地址>`），否则部署时无法 git pull 拉取最新代码。 + ## Directory Structure ``` diff --git a/skills_library/all/project-directory-spec/SKILL.md b/skills_library/all/project-directory-spec/SKILL.md index d826216..a5ad5e9 100644 --- a/skills_library/all/project-directory-spec/SKILL.md +++ b/skills_library/all/project-directory-spec/SKILL.md @@ -1,6 +1,6 @@ --- name: project-directory-spec -description: 所有 SDLC 角色产出/检查交付件落点前必读——工作空间目录结构（README.md + env/ + repos/）、repos/ 下按 项目工程文档(_pc)/应用(_app)/独立模块 三类仓库组织、env/ 部署信息单一事实源。不加载会把文件落到错误路径（工作空间根 vs repos/ 下）。 +description: 所有 SDLC 角色产出/检查交付件落点前必读——机构工作空间 projects/apps/modules 三目录 + 项目目录(README+docs/+env/+{应用名}_spec.json)。应用代码落机构 apps/、模块代码落机构 modules/，项目只维护 app spec.json 描述引用/生成模块，无 repos/ 无 references/。不加载会把应用/模块代码落到项目目录下（应落机构 apps/modules）。 essential: true --- @@ -8,7 +8,7 @@ essential: true ## 一、定位与客制化 -本技能是**全局（global）基础规范**，规定项目工作空间的目录结构与各目录作用。 +本技能是**全局（global）基础规范**，规定机构工作空间与项目目录结构、各目录作用。 所有角色（requirement / design / develop / deploy_test / test / deploy_prod / pm / qc）在产出或检查交付件前，都必须先读本技能，确认文件应落在哪个目录、应从哪个目录检查。 @@ -23,129 +23,106 @@ global（全局基础）→ org（客户）→ pipeline（产线）→ project - **产线（pipeline）版**：某条产线（如开发产线）的目录细化，覆盖客户/全局。 - **项目（project）版**：单个项目的特殊目录，覆盖以上所有。 -## 二、顶层目录结构 +## 二、机构工作空间（顶层） -每个项目工作空间（workspace）的标准结构： +机构工作空间根下只有三个子目录： ``` -{workspace}/ +{机构工作空间}/ +├── projects/ # 项目目录 +├── apps/ # 应用本地仓库目录 +└── modules/ # 模块本地仓库目录 +``` + +- **三个子目录下都可以创建子目录**。 +- **子目录命名规则**：英文字母 + 下划线 + 数字组合（`[a-zA-Z0-9_]+`），禁用中文、空格、连字符、其它符号。 +- `apps/{应用名}/`：应用本地仓库，按 **web-application-spec** 创建文件和目录。 +- `modules/{模块名}/`：模块本地仓库，按 **module-development-spec** 创建和生成文件和子目录。 +- `projects/{项目名}/`：一个项目，按本规范创建和生成子目录。 + +## 三、项目目录结构 + +``` +projects/{项目名}/ ├── README.md # 项目说明 -├── env/ # 部署环境信息（集中保存，部署时读，改配置只改这里） -│ ├── test.json # 测试环境（主机/SSH/端口/DB/路径） -│ └── prod.json # 生产环境 -└── repos/ # 项目仓库目录，每个子目录都是一个独立 git 仓库 - ├── {项目名}_pc/ # 项目工程文档仓库（一个项目一个） - ├── {应用名}_app/ # 应用仓库（一个应用一个，可多个） - └── {模块名}/ # 独立模块仓库（一个模块一个，可多个） +├── docs/ # 项目过程文档 +│ ├── 00-requirement/ # 需求文档 +│ ├── 01-design/ # 设计文档 +│ ├── 02-develop/ # 开发说明 +│ ├── 03-test/ # 测试文档 +│ ├── 04-deploy/ # 部署文档 +│ └── 05-pm/ # 项目管理 + QC 审计文档 +├── env/ # 部署环境信息（集中保存） +│ ├── test.json +│ └── prod.json +└── {应用名}_spec.json # 每个 app 一个 spec.json（描述引用/生成模块） ``` -工作空间根下只有 `README.md`、`env/`、`repos/` 三个顶层项，其余所有内容都进 `repos/` 下的对应仓库。**部署环境信息统一放 `env/`，不散落到需求/设计/代码各处**。 +- **项目目录下没有 repos/ 也没有 references/ 目录**。 +- 有几个 app，就写几个 `{应用名}_spec.json`，后面只维护这些 spec.json 文件。 +- 应用/模块的实际代码在机构 `apps/`、`modules/` 下，不在项目目录下。 -## 三、目录作用 +## 四、{应用名}_spec.json 内容 -### README.md —— 项目说明 -- 每个项目一个，放在工作空间根。 -- 内容：项目定位、功能概述、技术栈、目录导航、快速上手。 +每个 app 一个 spec.json，描述该应用引用了哪些模块、需要生成哪些模块： -### env/ —— 部署环境信息（集中管理，部署时读） -- 每个项目一个，放在工作空间根，与 repos/ 平级。 -- 集中保存项目所有部署环境信息（测试/生产的主机、SSH 账号、部署目录、端口、数据库连接、域名）。 -- **单一事实源**：改端口等配置只改这里一个文件，不散落到需求/设计/代码各处。 -- requirement 阶段生成（用户给了环境信息就填，没给标注待明确 + 冒泡问）；design/develop 读端口；deploy_test/deploy_prod 读对应环境执行部署。 - -文件格式（JSON）： ```json -// env/test.json { - "environment": "test", - "host": "hrstest.opencomputing.cn", - "ssh": { "user": "hrs", "port": 22 }, - "deploy_dir": "~/hrs_app", - "app_port": 9280, - "access_url": "http://hrstest.opencomputing.cn:9280", - "database": { "host": "localhost", "port": 3306, "user": "test", "password": "test123", "name": "hrs" }, - "runtime": { "python": "3.10", "docker": false } + "app": "hrs6", + "referenced_modules": ["apppublic", "sqlor", "ahserver", "rbac"], + "generated_modules": ["organization", "payroll", "recruitment"] } ``` -### repos/ —— 项目仓库目录 -- 项目的仓库根目录，**每个子目录都是一个独立 git 仓库**（独立 `.git`、独立提交、独立版本管理）。 -- 临时文件、非仓库文件**不进 repos/**。 +- `app`：应用名（对应机构 `apps/{应用名}/`）。 +- `referenced_modules`：**引用的模块**——机构 `modules/` 下已有的模块（基础模块 apppublic/sqlor/ahserver/rbac/appbase/accounting 等），直接引用，不重新开发。 +- `generated_modules`：**需要生成的模块**——本项目要开发的业务模块，develop 产出到机构 `modules/{模块名}/`。 -### {项目名}_pc —— 项目工程文档仓库 -- 存放项目级的所有过程文档（需求 / 设计 / 开发 / 测试 / 部署 / 项目管理）。 -- 一个项目一个，命名 `{项目名}_pc`。 -- 本地 git 仓库（无远程），各阶段文档的 commit 记录是 QC/PM 审核依据。 -- 内部结构： - ``` - {项目名}_pc/ - ├── README.md - ├── docs/ - │ ├── 00-requirement/ # 需求文档 - │ ├── 01-design/ # 设计文档 - │ ├── 02-develop/ # 开发说明 - │ ├── 03-test/ # 测试文档 - │ ├── 04-deploy/ # 部署文档 - │ └── 05-pm/ # 项目管理 + QC 审计文档 - ├── modules/ # 模块清单 + 模块级设计 - ├── apps/ # 应用说明（一个应用一个文件） - ├── config/ # 部署配置 - └── .gitignore - ``` +## 五、命名规范 -### {应用名}_app —— 应用仓库 -- 存放一个应用的代码（可运行、可部署的应用单元）。 -- 一个应用一个仓库，命名 `{应用名}_app`，一个项目可有多个应用。 -- 有远程 git 仓库。 -- **应用是唯一部署单元**：一个应用 = 一个入口（`app/{应用名}.py`）= 一个端口。业务模块通过 `load_{module}()` 挂到应用这个唯一入口下，模块不独立部署、不独立占端口。 +| 目录 | 命名 | 示例 | +|------|------|------| +| 项目 | `{项目名}`（`[a-zA-Z0-9_]+`） | `hrs6`、`personnel_system` | +| 应用 | `{应用名}`（`[a-zA-Z0-9_]+`） | `hrs6_app` | +| 模块 | `{模块名}`（`[a-zA-Z0-9_]+`） | `organization`、`payroll` | -### {模块名} —— 独立模块仓库 -- 存放一个独立模块的代码（可复用单元，含自己的数据 / CRUD / 处理逻辑 / skills）。 -- 一个模块一个仓库，命名 `{模块名}`（无后缀），由 design 阶段划分。 -- 有远程 git 仓库。 -- **模块不是独立部署单元**：模块是应用内的功能模块（Python 包），无独立 app.py / 端口，必须通过 `load_{module}()` 挂到应用才能运行。 -- 内部结构以 `module-development-spec` 技能为准（Python 包目录=模块名 + wwwroot/models/json/init/scripts/skill/pyproject.toml），本规范不重复定义。 +- 所有目录名用英文字母 + 下划线 + 数字，禁用中文、连字符、空格。 +- 模块名用能表达模块职责的英文名，不用序号或占位名。 -## 四、命名规范 - -| 仓库类型 | 命名 | 示例 | -|---------|------|------| -| 项目工程文档 | `{项目名}_pc` | `hrs_pc` | -| 应用 | `{应用名}_app` | `hrs_app` | -| 独立模块 | `{模块名}`（无后缀） | `organization`、`payroll`、`recruitment` | - -- 占位符 `{项目名}` / `{应用名}` / `{模块名}` 用实际名称替换。 -- 模块名用能表达模块职责的英文名（organization / payroll / recruitment 等），不用序号或占位名。 - -## 五、各角色产出落点 - -> 以下路径都是相对工作空间根的完整路径（从 `repos/` 写起）。角色 agent 用 `write_file` 写文件时按此路径落盘。 +## 六、各角色产出落点 | 角色 | 产出 | 落点 | |------|------|------| -| requirement | 需求规格说明书 | `repos/{项目名}_pc/docs/00-requirement/requirement-spec.md` | -| requirement | 应用部署单元定义 | `repos/{项目名}_pc/apps/{应用名}.md` | -| requirement | 部署环境信息 | `env/test.json` + `env/prod.json`（集中保存，改配置只改这里） | -| design | 系统架构 / UI 设计 | `repos/{项目名}_pc/docs/01-design/architecture.md`、`ui-design.md` | -| design | 模块清单 + 模块级设计 | `repos/{项目名}_pc/modules/{模块名}.md` + `repos/{项目名}_pc/modules/{模块名}/design.md` + `repos/{项目名}_pc/modules/{模块名}/skill/SKILL.md`（模块技能文档，develop 参考） | -| develop | 模块源码 | `repos/{模块名}/`（内部结构以 module-development-spec 为准） | -| develop | 开发说明 | `repos/{项目名}_pc/docs/02-develop/dev-notes.md` | -| test | 测试计划 / 用例 / 报告 | `repos/{项目名}_pc/docs/03-test/` | -| deploy_test | 测试环境部署 | `repos/{项目名}_pc/docs/04-deploy/deploy-test-env.md` | -| deploy_prod | 生产部署 + 发布说明 | `repos/{项目名}_pc/docs/04-deploy/` | -| pm | 项目计划 / 任务分配 / 验收记录 | `repos/{项目名}_pc/docs/05-pm/` | +| requirement | 需求规格说明书 | `projects/{项目名}/docs/00-requirement/requirement-spec.md` | +| requirement | 应用 spec.json | `projects/{项目名}/{应用名}_spec.json`（有几个 app 写几个） | +| requirement | 部署环境信息 | `projects/{项目名}/env/test.json` + `prod.json` | +| design | 系统架构 / UI 设计 | `projects/{项目名}/docs/01-design/architecture.md`、`ui-design.md` | +| design | 模块级设计 | `projects/{项目名}/docs/01-design/modules/{模块名}.md` | +| develop | 应用源码 | 机构 `apps/{应用名}/`（按 web-application-spec） | +| develop | 模块源码 | 机构 `modules/{模块名}/`（按 module-development-spec） | +| develop | 开发说明 | `projects/{项目名}/docs/02-develop/dev-notes.md` | +| test | 测试文档 | `projects/{项目名}/docs/03-test/` | +| deploy_test | 测试环境部署 | `projects/{项目名}/docs/04-deploy/deploy-test-env.md` | +| deploy_prod | 生产部署 | `projects/{项目名}/docs/04-deploy/` | +| pm | 项目文档 | `projects/{项目名}/docs/05-pm/` | -## 六、各角色检查落点（QC / PM 必读） - -QC/PM 检查交付件时，用 `read_file` / `list_files` 的路径是相对工作空间根的，必须从 `repos/` 写起： +## 七、各角色检查落点（QC / PM 必读） | 检查对象 | 完整路径 | |---------|---------| -| 需求文档 | `repos/{项目名}_pc/docs/00-requirement/requirement-spec.md` | -| 应用定义 | `repos/{项目名}_pc/apps/{应用名}.md` | -| 设计文档 | `repos/{项目名}_pc/docs/01-design/` + `repos/{项目名}_pc/modules/` | -| 模块代码 | `repos/{模块名}/`（内部结构以 module-development-spec 为准） | -| 测试文档 | `repos/{项目名}_pc/docs/03-test/` | -| 部署文档 | `repos/{项目名}_pc/docs/04-deploy/` | +| 需求文档 | `projects/{项目名}/docs/00-requirement/` | +| app spec | `projects/{项目名}/{应用名}_spec.json` | +| 设计文档 | `projects/{项目名}/docs/01-design/` | +| 应用代码 | 机构 `apps/{应用名}/`（按 web-application-spec） | +| 模块代码 | 机构 `modules/{模块名}/`（按 module-development-spec） | +| 测试文档 | `projects/{项目名}/docs/03-test/` | +| 部署文档 | `projects/{项目名}/docs/04-deploy/` | -⚠️ 工作空间根下只有 `README.md`、`env/`、`repos/` 三个顶层项，**所有交付文件都在 `repos/` 下**（部署环境信息在 `env/`）。检查时路径必须从 `repos/` 写起，不要在工作空间根下找 `docs/`、`apps/` 等目录——它们不存在。 +⚠️ 应用/模块代码在机构 `apps/`、`modules/` 下，**不在项目目录下**。检查应用/模块代码时，路径是机构工作空间的 `apps/{应用名}/`、`modules/{模块名}/`，不是 `projects/{项目}/...`。 + +## 八、部署前设置远程仓库 + +应用部署测试前，机构 `apps/` 和 `modules/` 下应用使用到的仓库**都要设置远程仓库**（`git remote add origin <远程地址>`），否则部署时无法 git pull 拉取最新代码。 + +- 应用仓库：`apps/{应用名}/` 设置远程仓库。 +- 模块仓库：`modules/{模块名}/` 中，被应用 referenced_modules / generated_modules 引用的都要设置远程仓库。 diff --git a/skills_library/all/web-application-spec/SKILL.md b/skills_library/all/web-application-spec/SKILL.md index 5b14519..e7c2d82 100644 --- a/skills_library/all/web-application-spec/SKILL.md +++ b/skills_library/all/web-application-spec/SKILL.md @@ -40,6 +40,12 @@ pip install git+https://git.opencomputing.cn/yumoqing/appbase pip install git+https://git.opencomputing.cn/yumoqing/rbac ``` +## 应用本地仓库位置 + +应用本地仓库在机构工作空间 `apps/{应用名}/`（见 project-directory-spec）。应用是唯一部署单元——一个应用一个仓库、一个入口（`app/{应用名}.py`）、一个端口，业务模块通过 `load_{模块}()` 挂到应用这个唯一入口下。 + +**部署测试前必须给应用仓库设置远程仓库**（`git remote add origin <远程地址>`），否则部署时无法 git pull 拉取最新代码。 + ## Application Directory Structure ``` ${appname}/