yumoqing/pipeline_core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(skills): 机构工作空间目录重构——projects/apps/modules 三目录 + 项目去 repos/references 改 app spec.json(引用/生成模块) + 应用/模块落点改机构 apps/modules + 部署前设置远程仓库

Browse Source
This commit is contained in:
yumoqing 2026-08-24 16:33:54 +08:00
parent 8164444ab3
commit 3cde0d9ce2
3 changed files with 91 additions and 102 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
skills_library/all/module-development-spec/SKILL.md
View File

@ -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
```

181
skills_library/all/project-directory-spec/SKILL.md
View File

@ -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 引用的都要设置远程仓库。

6
skills_library/all/web-application-spec/SKILL.md
View File

@ -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}/