feat(skill): 分层导入机制——Skill 支持 references/scripts/templates 子文件加载 + 新建 project-directory-spec 项目目录规范 + sdlc-repo-standard 改为引用新规范
This commit is contained in:
parent
93079c1a54
commit
905e01f581
@ -131,6 +131,37 @@ class Skill:
|
||||
{cap_line}{body}
|
||||
"""
|
||||
|
||||
_LINKED_DIRS = ('references', 'scripts', 'templates', 'assets')
|
||||
|
||||
def list_linked_files(self) -> List[str]:
|
||||
"""列出 skill 目录下 references/scripts/templates/assets 内的子文件（相对路径）。"""
|
||||
base = os.path.dirname(self.path)
|
||||
result = []
|
||||
for sub in self._LINKED_DIRS:
|
||||
d = os.path.join(base, sub)
|
||||
if os.path.isdir(d):
|
||||
for root, _, files in os.walk(d):
|
||||
for f in files:
|
||||
result.append(os.path.relpath(os.path.join(root, f), base))
|
||||
return sorted(result)
|
||||
|
||||
def read_linked_file(self, rel_path: str) -> str:
|
||||
"""读取 skill 目录下 references/scripts/templates/assets 内的子文件（相对路径）。"""
|
||||
base = os.path.realpath(os.path.dirname(self.path))
|
||||
full = os.path.realpath(os.path.join(base, rel_path or ''))
|
||||
rel = os.path.relpath(full, base)
|
||||
if rel == os.pardir or rel.startswith(os.pardir + os.sep) or os.path.isabs(rel):
|
||||
return 'FAIL: 路径越界'
|
||||
if not any(rel == sub or rel.startswith(sub + os.sep) for sub in self._LINKED_DIRS):
|
||||
return f'FAIL: 只允许加载 references/scripts/templates/assets 下的文件（收到 {rel}）'
|
||||
if not os.path.isfile(full):
|
||||
return f'FAIL: 文件不存在 {rel_path}'
|
||||
try:
|
||||
with open(full, 'r', encoding='utf-8') as f:
|
||||
return f.read()
|
||||
except Exception as e:
|
||||
return f'ERROR: {str(e)[:300]}'
|
||||
|
||||
|
||||
def _parse_frontmatter(content: str) -> Optional[dict]:
|
||||
if not content.startswith("---"):
|
||||
|
||||
131
skills_library/all/project-directory-spec/SKILL.md
Normal file
131
skills_library/all/project-directory-spec/SKILL.md
Normal file
@ -0,0 +1,131 @@
|
||||
---
|
||||
name: project-directory-spec
|
||||
description: 项目目录规范——项目工作空间目录结构与各目录作用（README.md 项目说明 + repos/ 下按 项目工程文档(_pc)/应用(_app)/独立模块 三类独立仓库组织）。所有 SDLC 角色产出与检查前必读，路径以此为准。
|
||||
---
|
||||
|
||||
# 项目目录规范
|
||||
|
||||
## 一、定位与客制化
|
||||
|
||||
本技能是**全局（global）基础规范**，规定项目工作空间的目录结构与各目录作用。
|
||||
|
||||
所有角色（requirement / design / develop / deploy_test / test / deploy_prod / pm / qc）在产出或检查交付件前，都必须先读本技能，确认文件应落在哪个目录、应从哪个目录检查。
|
||||
|
||||
同名技能按 scope 逐级覆盖实现客制化，优先级（低→高）：
|
||||
|
||||
```
|
||||
global（全局基础）→ org（客户）→ pipeline（产线）→ project（项目）
|
||||
```
|
||||
|
||||
- **全局版**：最通用的目录约定（即本文件）。
|
||||
- **客户（org）版**：客户组织自己的目录要求，覆盖全局。
|
||||
- **产线（pipeline）版**：某条产线（如开发产线）的目录细化，覆盖客户/全局。
|
||||
- **项目（project）版**：单个项目的特殊目录，覆盖以上所有。
|
||||
|
||||
## 二、顶层目录结构
|
||||
|
||||
每个项目工作空间（workspace）的标准结构：
|
||||
|
||||
```
|
||||
{workspace}/
|
||||
├── README.md # 项目说明
|
||||
└── repos/ # 项目仓库目录，每个子目录都是一个独立 git 仓库
|
||||
├── {项目名}_pc/ # 项目工程文档仓库（一个项目一个）
|
||||
├── {应用名}_app/ # 应用仓库（一个应用一个，可多个）
|
||||
└── {模块名}/ # 独立模块仓库（一个模块一个，可多个）
|
||||
```
|
||||
|
||||
工作空间根下只有 `README.md` 和 `repos/` 两个顶层项，其余所有内容都进 `repos/` 下的对应仓库。
|
||||
|
||||
## 三、目录作用
|
||||
|
||||
### README.md —— 项目说明
|
||||
- 每个项目一个，放在工作空间根。
|
||||
- 内容：项目定位、功能概述、技术栈、目录导航、快速上手。
|
||||
|
||||
### repos/ —— 项目仓库目录
|
||||
- 项目的仓库根目录，**每个子目录都是一个独立 git 仓库**（独立 `.git`、独立提交、独立版本管理）。
|
||||
- 临时文件、非仓库文件**不进 repos/**。
|
||||
|
||||
### {项目名}_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 仓库。
|
||||
|
||||
### {模块名} —— 独立模块仓库
|
||||
- 存放一个独立模块的代码（可复用单元，含自己的数据 / CRUD / 处理逻辑 / skills）。
|
||||
- 一个模块一个仓库，命名 `{模块名}`（无后缀），由 design 阶段划分。
|
||||
- 有远程 git 仓库。
|
||||
- 内部结构（参考）：
|
||||
```
|
||||
{模块名}/
|
||||
├── README.md
|
||||
├── src/ # 源码
|
||||
├── ddl/ # 表结构 DDL
|
||||
├── init/ # 初始化数据
|
||||
└── selftest.py # 自测
|
||||
```
|
||||
|
||||
## 四、命名规范
|
||||
|
||||
| 仓库类型 | 命名 | 示例 |
|
||||
|---------|------|------|
|
||||
| 项目工程文档 | `{项目名}_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` |
|
||||
| design | 系统架构 / UI 设计 | `repos/{项目名}_pc/docs/01-design/architecture.md`、`ui-design.md` |
|
||||
| design | 模块清单 + 模块级设计 | `repos/{项目名}_pc/modules/{模块名}.md` + `repos/{项目名}_pc/modules/{模块名}/design.md` |
|
||||
| develop | 模块源码 + DDL | `repos/{模块名}/src/`、`repos/{模块名}/ddl/` |
|
||||
| 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/` |
|
||||
|
||||
## 六、各角色检查落点（QC / PM 必读）
|
||||
|
||||
QC/PM 检查交付件时，用 `read_file` / `list_files` 的路径是相对工作空间根的，必须从 `repos/` 写起：
|
||||
|
||||
| 检查对象 | 完整路径 |
|
||||
|---------|---------|
|
||||
| 需求文档 | `repos/{项目名}_pc/docs/00-requirement/requirement-spec.md` |
|
||||
| 应用定义 | `repos/{项目名}_pc/apps/{应用名}.md` |
|
||||
| 设计文档 | `repos/{项目名}_pc/docs/01-design/` + `repos/{项目名}_pc/modules/` |
|
||||
| 模块代码 | `repos/{模块名}/src/`、`repos/{模块名}/ddl/` |
|
||||
| 测试文档 | `repos/{项目名}_pc/docs/03-test/` |
|
||||
| 部署文档 | `repos/{项目名}_pc/docs/04-deploy/` |
|
||||
|
||||
⚠️ 工作空间根下只有 `README.md` 和 `repos/` 两个顶层项，**所有交付文件都在 `repos/` 下**。检查时路径必须从 `repos/` 写起，不要在工作空间根下找 `docs/`、`apps/` 等目录——它们不存在。
|
||||
@ -1,60 +1,13 @@
|
||||
---
|
||||
name: sdlc-repo-standard
|
||||
description: SDLC project repo layout and deliverable specs.
|
||||
description: SDLC 交付件规格——模块说明/模块级设计/应用说明的文件格式 + 各角色产出内容与行为准则。目录结构与落点路径以 project-directory-spec 为准。
|
||||
---
|
||||
|
||||
# SDLC 项目仓库标准
|
||||
# SDLC 交付件规格
|
||||
|
||||
项目工作空间 `workspace/repos/` 下建三类仓库，其他临时文件/其他用途文件**不进仓库**：
|
||||
> ⚠️ 项目目录结构（README.md + repos/ 下 {项目名}_pc / {应用名}_app / {模块} 三类仓库、各角色落点路径）以 **project-directory-spec** 技能为唯一权威，本技能不再定义目录结构，只定义 SDLC 交付件的**内容格式**与角色产出行为准则。
|
||||
|
||||
1. **项目过程仓库**（`repos/project/`）：阶段文档、QC 审计文档、项目管理文档都放这里
|
||||
2. **应用仓库**（至少一个）：应用代码
|
||||
3. **模块仓库**（每个模块一个）：模块代码
|
||||
|
||||
## 目录结构
|
||||
|
||||
```
|
||||
workspace/
|
||||
├── repos/
|
||||
│ ├── project/ # 项目过程仓库（git，本地仓库，无远程）
|
||||
│ │ ├── README.md
|
||||
│ │ ├── docs/ # 阶段文档
|
||||
│ │ │ ├── 00-requirement/
|
||||
│ │ │ │ └── requirement-spec.md
|
||||
│ │ │ ├── 01-design/
|
||||
│ │ │ │ ├── architecture.md # 系统架构、模块划分、模块间依赖、开发顺序
|
||||
│ │ │ │ └── ui-design.md # 视觉风格/主页面/用户交互模式/弹窗规范
|
||||
│ │ │ ├── 02-develop/
|
||||
│ │ │ │ └── dev-notes.md
|
||||
│ │ │ ├── 03-test/
|
||||
│ │ │ │ ├── test-plan.md
|
||||
│ │ │ │ ├── test-cases.md
|
||||
│ │ │ │ └── test-report.md
|
||||
│ │ │ ├── 04-deploy/
|
||||
│ │ │ │ ├── deploy-guide.md
|
||||
│ │ │ │ └── release-notes.md
|
||||
│ │ │ └── 05-pm/ # 项目管理文档 + QC 审计文档
|
||||
│ │ │ └── reviews/
|
||||
│ │ ├── modules/ # 模块说明 + 模块级设计（自包含单元）
|
||||
│ │ │ ├── <模块名>.md # 模块清单：功能/仓库/依赖/开发顺序
|
||||
│ │ │ └── <模块名>/
|
||||
│ │ │ ├── design.md # 数据设计(表DDL) + CRUD + 处理逻辑(接口)
|
||||
│ │ │ └── skill/SKILL.md
|
||||
│ │ ├── apps/ # 应用说明（每个应用一个文件）
|
||||
│ │ │ └── <应用名>.md
|
||||
│ │ ├── config/ # 部署配置
|
||||
│ │ └── .gitignore
|
||||
│ ├── <应用仓库>/ # 应用代码仓库（至少一个）
|
||||
│ └── <模块仓库>/ # 每个模块一个代码仓库
|
||||
└── （其他临时文件不进仓库）
|
||||
```
|
||||
|
||||
**说明**：
|
||||
- 项目过程仓库是**本地 git 仓库**（无远程），只 commit 不 push。
|
||||
- 应用仓库、模块仓库是**代码仓库**（有远程），develop 阶段 clone 到 `repos/` 下。
|
||||
- **git 提交时机**：不在 agent 每次产出时提交，而是 **PM 审核通过后系统统一提交**（项目过程仓库 + 应用/模块仓库），减少 git 并发锁与远端 push 频率。
|
||||
|
||||
## 模块说明文件 `modules/<模块名>.md`
|
||||
## 模块说明文件 `{项目名}_pc/modules/{模块名}.md`
|
||||
|
||||
```markdown
|
||||
# <模块名>
|
||||
@ -68,23 +21,21 @@ workspace/
|
||||
- **关联应用**: <属于哪个应用>
|
||||
```
|
||||
|
||||
## 模块级设计 `modules/<模块名>/`
|
||||
## 模块级设计 `{项目名}_pc/modules/{模块名}/`
|
||||
|
||||
每个模块是自包含、可复用的单元，数据设计放模块内而非应用级：
|
||||
|
||||
```
|
||||
modules/<模块名>/
|
||||
{项目名}_pc/modules/{模块名}/
|
||||
├── design.md # 数据设计(表结构DDL) + CRUD 定义 + 处理逻辑(接口)
|
||||
└── skill/SKILL.md # 模块技能文档（develop agent 参考）
|
||||
```
|
||||
|
||||
**原则**: 数据、CRUD、处理逻辑、skills 都属于模块本身，不放在应用级 design 里，这样模块可整体复用（换个应用直接带着自己的数据/逻辑/skills 一起加载）。
|
||||
**原则**: 数据、CRUD、处理逻辑、skills 都属于模块本身，不放在应用级 design 里，这样模块可整体复用。
|
||||
|
||||
**模板**: 设计产出用统一模板，保证 develop 读到的每个模块设计结构一致——
|
||||
- `design.md` 模板 → `templates/module-design.md`（模块元信息 / 数据设计→models / CRUD→json / 处理逻辑→dspy / 入口菜单）
|
||||
- `skill/SKILL.md` 模板 → `templates/module-skill.md`（frontmatter / 概述 / 数据模型 / 关键接口 / 陷阱 / 依赖）
|
||||
**模板**: design.md 用 `templates/module-design.md`（模块元信息 / 数据设计→models / CRUD→json / 处理逻辑→dspy / 入口菜单）；skill/SKILL.md 用 `templates/module-skill.md`（frontmatter / 概述 / 数据模型 / 关键接口 / 陷阱 / 依赖）。
|
||||
|
||||
## 应用说明文件 `apps/<应用名>.md`
|
||||
## 应用说明文件 `{项目名}_pc/apps/{应用名}.md`
|
||||
|
||||
```markdown
|
||||
# <应用名>
|
||||
@ -97,42 +48,38 @@ modules/<模块名>/
|
||||
- **状态**: <规划中/开发中/已上线>
|
||||
```
|
||||
|
||||
## 各角色产出规范
|
||||
|
||||
> 所有阶段文档都产出到项目过程仓库 `repos/project/` 下，完成后 `deliver` 交付即可；**git 提交由 PM 审核通过后系统统一执行**，agent 无需自己 `git_commit_push`。
|
||||
## 各角色产出内容（落点路径见 project-directory-spec）
|
||||
|
||||
### requirement（需求分析师）
|
||||
- **产出**: `repos/project/docs/00-requirement/requirement-spec.md`
|
||||
- **同时创建**: `repos/project/apps/` 下至少一个应用说明文件（应用 = 部署单元，含端口/环境）
|
||||
- **不划分模块**: 模块划分是架构决策，由 design 阶段设计师完成
|
||||
- **内容**: 项目概述、用户角色及权限、功能列表（含验收标准）、非功能需求、业务流程
|
||||
- **同时创建**: `{项目名}_pc/apps/` 下至少一个应用说明文件（应用 = 部署单元，含端口/环境）
|
||||
- **不划分模块**: 模块划分是架构决策，由 design 阶段设计师完成
|
||||
|
||||
### design（系统设计师）
|
||||
- **应用级产出**: `repos/project/docs/01-design/architecture.md`（系统架构、模块划分、模块间依赖、开发顺序）, `ui-design.md`（视觉风格/主页面/用户交互模式/弹窗规范）
|
||||
- **模块级设计**: 每个模块在 `repos/project/modules/<模块名>/` 下产出自己的设计——数据设计(表结构DDL)、CRUD 定义、处理逻辑(接口)、skills(技能文档)。数据/CRUD/逻辑/skills 属于模块本身，不放在应用级，保证模块可整体复用
|
||||
- **更新**: `repos/project/modules/` 下各模块的技术栈、依赖关系、开发顺序
|
||||
- **内容**: 架构图及技术选型、模块清单与依赖图、视觉风格与交互规范
|
||||
- **应用级**: `architecture.md`（系统架构、模块划分、模块间依赖、开发顺序）+ `ui-design.md`（视觉风格/主页面/交互模式/弹窗规范）
|
||||
- **模块级**: 每个模块在 `{项目名}_pc/modules/{模块名}/` 下产出 design.md（数据设计/CRUD/处理逻辑）+ skill/SKILL.md
|
||||
- **更新**: `{项目名}_pc/modules/` 下各模块的技术栈、依赖关系、开发顺序
|
||||
|
||||
### develop（开发工程师）
|
||||
- **产出**: `repos/project/docs/02-develop/dev-notes.md`（开发说明，记录了哪些模块仓库、开发了什么功能）
|
||||
- **源码**: 写入对应模块的独立仓库 `repos/<模块名>/`（通过 `modules/` 中的 repo URL 确定），**不在项目过程仓库中**
|
||||
- **更新**: `repos/project/modules/` 下对应模块的状态为开发中/已完成
|
||||
- **源码**: 写入模块仓库 `repos/{模块名}/`，不在项目工程文档仓库
|
||||
- **开发说明**: `{项目名}_pc/docs/02-develop/dev-notes.md`
|
||||
- **行为准则**:
|
||||
1. 先读 `repos/project/modules/` 确认模块仓库 URL
|
||||
2. `git_clone` 模块仓库到 `repos/` 下
|
||||
3. `write_file` 写代码到模块仓库
|
||||
4. `run_shell` 编译验证
|
||||
5. `write_file` 更新 `repos/project/modules/<模块名>.md` 状态
|
||||
6. `deliver` 交付（git 提交由 PM 审核通过后系统统一执行）
|
||||
1. 读 `{项目名}_pc/modules/` 确认模块仓库
|
||||
2. clone 模块仓库到 `repos/` 下
|
||||
3. write_file 写代码到模块仓库
|
||||
4. run_shell 编译验证
|
||||
5. git_commit_push 提交模块仓库
|
||||
6. 更新 `{项目名}_pc/modules/{模块名}.md` 状态
|
||||
7. deliver 交付
|
||||
|
||||
### test（测试工程师）
|
||||
- **产出**: `repos/project/docs/03-test/test-plan.md`, `test-cases.md`, `test-report.md`
|
||||
- **内容**: test-plan.md、test-cases.md、test-report.md
|
||||
|
||||
### deploy（部署工程师）
|
||||
- **产出**: `repos/project/docs/04-deploy/deploy-guide.md`, `release-notes.md`, `repos/project/config/` 下部署配置
|
||||
- **内容**: deploy-guide.md、release-notes.md、`{项目名}_pc/config/` 下部署配置
|
||||
|
||||
### PM（项目经理）
|
||||
- **审核要点**:
|
||||
- 每个阶段检查交付件实际产出（list_files/read_file 检查文件），审核通过后系统统一 git 提交
|
||||
- develop: 必须检查对应模块仓库代码文件实际产出，`modules/` 状态已更新
|
||||
- 每个阶段检查 `modules/` 和 `apps/` 文件是否随进度更新
|
||||
- 每个阶段检查项目工程文档仓库有 git commit、交付件已受控提交
|
||||
- develop: 必须检查对应模块仓库有 git commit、modules/ 状态已更新
|
||||
- 每个阶段检查 modules/ 和 apps/ 文件是否随进度更新
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user