321 lines
15 KiB
Markdown
321 lines
15 KiB
Markdown
# SDLC 概念 → 能力 + skill 全景映射
|
||
|
||
> 本文档回答一个问题：开发产线里每一个软件工程概念，如何用「能力（固化工具）+ skill（规范）」覆盖。
|
||
> 元模式来自已固化的「任务 / 问题」两个概念，其余概念照此扩展，避免每个概念一套野路子。
|
||
|
||
---
|
||
|
||
## 一、元模式（六条铁律，所有概念统一遵守）
|
||
|
||
任务（task_capability.py + task skill）和问题（communication.py + team-communication skill）
|
||
已经固化出下面的不变量，新概念一律照抄，不得发明新范式：
|
||
|
||
1. **状态存表，规则存 skill，迁移靠 LLM 决策 + 工具 CAS 原子校验**
|
||
- 工具只做 `UPDATE ... WHERE state=from AND <scope>=...` 的 CAS，**不校验合法性**；
|
||
- 合法性（能走哪条边、谁能操作）由 LLM 读 skill 判断。
|
||
2. **归属用显式列，不靠 status 反推**（问题用 `current_handler_role` + `current_handler_agentid`）。
|
||
3. **流转路径/规则是 skill 知识，不存快照**——改 skill 后历史数据不残留旧路径。
|
||
4. **每次迁移写审计**：`record_audit(tenant_id, entity, entity_id, action, from_state, to_state, who, agent_id, detail, sor)`，append-only，微秒时间戳。
|
||
5. **角色规范名**：agent 角色 `agent.{role}`（无点自动补前缀），人角色 `{orgtype}.{role}`（如 `owner.superuser`）。
|
||
6. **skill frontmatter 带 `capability` + `tools` 字段**，声明配套能力模块与工具清单；项目可用同名 skill 覆盖（六级 scope：global→org→pipeline(common)→role→project→user）。
|
||
|
||
### 能力模块统一骨架（照抄 task_capability.py）
|
||
|
||
```python
|
||
"""<概念>能力 — <表> 的状态机语义化迁移（通用、产线无关）。
|
||
|
||
定位：storage/CRUD 是数据层；本模块是状态机语义化操作层，每个迁移 CAS 原子 + 租户隔离 + 审计。
|
||
状态机/流转规则在 <concept> skill 里（LLM 读 skill 判断合法性）；本模块只固化操作原语。
|
||
"""
|
||
import logging
|
||
from sqlor.dbpools import DBPools
|
||
from appPublic.uniqueID import getID
|
||
from .audit import record_audit
|
||
|
||
DBNAME = "pipeline"
|
||
|
||
S_XXX = "..." # 状态常量
|
||
|
||
def _get_db():
|
||
db = DBPools()
|
||
if not db.databases:
|
||
from appPublic.jsonConfig import getConfig
|
||
config = getConfig()
|
||
if config.databases:
|
||
db.databases = config.databases
|
||
return db, DBNAME
|
||
|
||
def _normalize_role(role):
|
||
role = (role or "").strip()
|
||
if not role:
|
||
return ""
|
||
if "." in role:
|
||
return role
|
||
return f"agent.{role}"
|
||
|
||
async def _transition(entity_id, scope_col, scope_val, from_state, to_state, action,
|
||
table, who=None, agent_id=None, detail=None):
|
||
"""CAS 状态迁移 + 审计。返回 (ok, message)。"""
|
||
...
|
||
# UPDATE {table} SET status={to}, updated_at=NOW() WHERE id={id} AND {scope_col}={scope_val} AND status={from}
|
||
# 校验落库后实际状态 == to，否则 "状态迁移失败(CAS)"
|
||
# await record_audit(scope_val, table, entity_id, action, from_state, to_state, who, agent_id, detail, sor)
|
||
```
|
||
|
||
### skill 统一模板（照抄 task/SKILL.md）
|
||
|
||
```yaml
|
||
---
|
||
name: <concept>
|
||
description: SDLC 产线默认 <概念> 状态机规范——定义状态、合法流转、角色→操作权限、门禁、人拍板点。项目可同名覆盖。触发：<何时加载>。
|
||
capability: <concept>_capability
|
||
tools: [<工具1>, <工具2>, ...]
|
||
---
|
||
# <概念> 状态机规范（SDLC 产线默认）
|
||
|
||
## 一、核心模型（状态存表，规则在本 skill，工具只 CAS，每次迁移写审计）
|
||
## 二、状态枚举表
|
||
## 三、合法流转图
|
||
## 四、角色 → 操作权限（业务级 RBAC）
|
||
## 五、门禁
|
||
## 六、人拍板点（human gate，走问题冒泡到 owner.superuser）
|
||
## 七、配套能力工具清单
|
||
## 八、分层覆盖（项目同名 skill 覆盖）
|
||
```
|
||
|
||
---
|
||
|
||
## 二、概念全景抽取（三类）
|
||
|
||
### A. 状态机概念（有生命周期 → 能力 + skill，共 10 个）
|
||
|
||
| # | 概念 | skill 名 | 表 | 状态字段 | 状态枚举（真实 appcodes） | 现状 |
|
||
|---|------|---------|----|---------|---------------------------|------|
|
||
| 1 | 项目 | project | sd_projects | status | draft / active / completed / archived | ✅ 已固化 |
|
||
| 2 | 迭代 | iteration | sd_iterations | status | planning / in_progress / completed / cancelled | ✅ 已固化 |
|
||
| 3 | 功能/需求 | feature | sd_features | status | proposed / approved / in_progress / delivered / verified / rejected | ✅ 已固化 |
|
||
| 4 | 任务 | task | pipeline_tasks | state | submitted / running / review / approved / completed / waiting / failed | ✅ 已固化 |
|
||
| 5 | 交付件 | deliverable | pipeline_deliverables | review_status | pending / approved / rejected | ✅ 已固化 |
|
||
| 6 | 测试计划 | test-plan | sd_test_plans | status | draft / approved / executing / completed | ✅ 已固化 |
|
||
| 7 | 测试用例 | test-case | sd_test_cases | status | pending / pass / fail / blocked / skipped | ✅ 已固化 |
|
||
| 8 | Bug | bug | sd_bugs | status | open / confirmed / fixing / fixed / verified / closed / rejected | ✅ 已固化 |
|
||
| 9 | 问题 | problem | pipeline_agent_questions | status | pending / answered | ✅ 已固化 |
|
||
| 10 | 部署环境 | deploy-env | sd_deploy_envs | status | configured / verified / failed | ✅ 已固化 |
|
||
|
||
### B. 资源/配置概念（纯 CRUD，无生命周期 → CRUD + 简单工具，不做状态机 skill）
|
||
|
||
| 概念 | 表 | 说明 |
|
||
|------|----|------|
|
||
| 仓库 repository | sd_project_repos | 无状态字段。add_repo / list_repos / clone_repo 已存在 ✅ |
|
||
|
||
### C. 横切/基础设施概念（已实现或无需业务 skill）
|
||
|
||
| 概念 | 实现 | 说明 |
|
||
|------|------|------|
|
||
| 会话 conversation | sd_conversations | append-only 记录，历史注入 |
|
||
| 记忆 memory | pipeline_user_memory + MemoryStore | 分域（global/pipeline/project/user） |
|
||
| 审计 audit | audit_log + audit.py | 通用原语 record_audit |
|
||
| 技能提议 skill-proposal | skill_proposals | pending→testing→approved→published |
|
||
| 角色 role | RoleSpec + SDL_ROLES | 规范在 team-communication + 各角色 system_prompt |
|
||
|
||
---
|
||
|
||
## 三、逐概念映射（A 类，含工具签名草稿）
|
||
|
||
> scope 约定：pipeline_tasks / pipeline_agent_questions 用 `tenant_id=project_id`（引擎层）；
|
||
> sd_* 业务表用各自的归属列（project_id / iteration_id / plan_id）做 CAS 范围校验。
|
||
|
||
### 1. 项目 project
|
||
|
||
```
|
||
能力 pipeline_service/project_capability.py（表 sd_projects，scope=org_id + id）
|
||
工具 create_project(name, project_type, description) → draft
|
||
start_project(project_id) draft → active
|
||
complete_project(project_id) active → completed
|
||
archive_project(project_id) completed → archived
|
||
reopen_project(project_id) archived → active
|
||
list_projects(org_id)
|
||
skill project — 项目生命周期、归档/完成门禁、项目→迭代→功能的包含关系、pipeline_id 绑定规则
|
||
```
|
||
|
||
### 2. 迭代 iteration
|
||
|
||
```
|
||
能力 pipeline_service/iteration_capability.py（表 sd_iterations，scope=project_id）
|
||
工具 create_iteration(project_id, iteration_name, iteration_type) → planning
|
||
start_iteration(iteration_id, project_id) planning → in_progress
|
||
complete_iteration(iteration_id, project_id) in_progress → completed
|
||
cancel_iteration(iteration_id, project_id) planning/in_progress → cancelled
|
||
list_iterations(project_id)
|
||
skill iteration — 迭代准入/准出条件（测试计划 exit_criteria、Bug 清零门禁）
|
||
```
|
||
|
||
### 3. 功能 feature（✅ 已实现）
|
||
|
||
```
|
||
表 sd_features（待建，字段见下）
|
||
状态 proposed / approved / in_progress / delivered / verified / rejected
|
||
能力 pipeline_service/feature_capability.py（scope=project_id）
|
||
工具 propose_feature(project_id, feature_name, description, iteration_id?) → proposed
|
||
approve_feature(feature_id, project_id) proposed → approved
|
||
reject_feature(feature_id, project_id, comment) proposed/approved → rejected
|
||
start_feature(feature_id, project_id) approved → in_progress
|
||
deliver_feature(feature_id, project_id) in_progress → delivered
|
||
verify_feature(feature_id, project_id) delivered → verified
|
||
reopen_feature(feature_id, project_id) rejected/verified → proposed
|
||
list_features(project_id, status?)
|
||
skill feature — 功能从需求拆解到验收闭环；迭代 scope 与用例/Bug 都挂 feature_id
|
||
```
|
||
|
||
### 4. 任务 task（✅ 已固化，基准参考）
|
||
|
||
```
|
||
能力 pipeline_service/task_capability.py
|
||
工具 claim_task / submit_task / approve_task / reject_task / complete_task
|
||
mark_failed / retry_task / suspend_task / revive_task / set_task_state
|
||
skill task
|
||
```
|
||
|
||
### 5. 交付件 deliverable
|
||
|
||
```
|
||
能力 pipeline_service/deliverable_capability.py（表 pipeline_deliverables，scope=project_id）
|
||
工具 submit_deliverable(...) → review_status=pending
|
||
approve_deliverable(deliverable_id, project_id) pending → approved
|
||
reject_deliverable(deliverable_id, project_id, comment) pending → rejected
|
||
list_deliverables(project_id, task_id?)
|
||
skill deliverable — 交付件类型(code/doc/config)、评审标准、与任务/仓库的关联规则
|
||
说明 现状 review_status 由 PM review_complete 顺带改，散在 agent_loop 里，应收敛到本能力
|
||
```
|
||
|
||
### 6. 测试计划 test-plan
|
||
|
||
```
|
||
能力 pipeline_service/test_plan_capability.py（表 sd_test_plans，scope=iteration_id）
|
||
工具 create_test_plan(iteration_id, plan_name, plan_type) → draft
|
||
approve_plan(plan_id) draft → approved
|
||
start_plan(plan_id) approved → executing
|
||
complete_plan(plan_id) executing → completed
|
||
list_plans(iteration_id)
|
||
skill test-plan — 准入/准出条件（entry_criteria/exit_criteria）如何 gate 迭代完成
|
||
```
|
||
|
||
### 7. 测试用例 test-case
|
||
|
||
```
|
||
能力 pipeline_service/test_case_capability.py（表 sd_test_cases，scope=plan_id）
|
||
工具 create_case(plan_id, case_name, case_type) → pending
|
||
pass_case(case_id) pending/fail → pass
|
||
fail_case(case_id) pending/pass → fail（触发联动建 Bug 的规范在 skill）
|
||
skip_case(case_id) pending → skipped
|
||
block_case(case_id) pending → blocked
|
||
list_cases(plan_id)
|
||
skill test-case — 用例执行规范、失败用例如何联动建 Bug（case_id 关联 sd_bugs.case_id）
|
||
```
|
||
|
||
### 8. Bug
|
||
|
||
```
|
||
能力 pipeline_service/bug_capability.py（表 sd_bugs，scope=iteration_id）
|
||
工具 report_bug(...) → open
|
||
confirm_bug(bug_id) open → confirmed
|
||
start_fix(bug_id) confirmed → fixing
|
||
fix_bug(bug_id, fix_description, fix_commit) fixing → fixed
|
||
verify_bug(bug_id) fixed → verified
|
||
close_bug(bug_id) verified → closed
|
||
reject_bug(bug_id) open/confirmed → rejected
|
||
reopen_bug(bug_id) closed/rejected → open
|
||
list_bugs(iteration_id)
|
||
skill bug — 严重度/优先级规则、关闭前「迭代 Bug 清零」门禁、reporter_type(human/agent) 语义
|
||
说明 现状只有 sdlc_ability 里的 add_bug，其余流转靠 CRUD 手改，应收敛
|
||
```
|
||
|
||
### 9. 问题 problem（✅ 已固化）
|
||
|
||
```
|
||
能力 pipeline_service/communication.py
|
||
工具 raise_problem / resolve_problem / escalate_problem / list_problems_for
|
||
skill team-communication
|
||
```
|
||
|
||
### 10. 部署环境 deploy-env
|
||
|
||
```
|
||
能力 pipeline_service/deploy_capability.py（表 sd_deploy_envs，scope=project_id）
|
||
工具 configure_env(project_id, env_type, host, ...) → configured
|
||
verify_env(env_id) configured → verified / failed
|
||
list_envs(project_id)
|
||
skill deploy — 环境类型(test/staging/production)、验证标准、发布门禁、回滚路径
|
||
说明 发布本体（部署动作）复用 task 状态机（deploy 角色）；本能力管「环境」这个可追踪实体
|
||
```
|
||
|
||
---
|
||
|
||
## 四、GAP 结论与实施顺序
|
||
|
||
```
|
||
✅ 已固化能力+skill（10 个状态机概念全齐）：任务、问题、功能、项目、迭代、交付件、测试计划、测试用例、Bug、部署环境
|
||
✅ 已有工具但无状态机 skill（资源概念）：仓库(add_repo/list_repos/clone_repo)
|
||
✅ 横切已实现：记忆、审计、技能提议、角色
|
||
```
|
||
|
||
实施顺序（由「被依赖最多」往下，避免返工）：
|
||
|
||
```
|
||
1. feature（新建 sd_features 表）—— 需求/功能的可追踪根，迭代 scope、用例、Bug 都要挂它
|
||
2. project + iteration —— 规划层容器，feature/task/bug 都挂 project_id/iteration_id
|
||
3. deliverable —— 任务产出物，评审收敛
|
||
4. bug + test-case + test-plan —— 质量闭环（用例失败→建 Bug→修复→回归）
|
||
5. deploy —— 收尾，复用 task 状态机
|
||
```
|
||
|
||
---
|
||
|
||
## 五、附录：feature 概念详细设计（第一批实现）
|
||
|
||
### sd_features 表（models/sd_features.json 草稿）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | str 32, PK | 主键 |
|
||
| project_id | str 32, not null | 所属项目 |
|
||
| iteration_id | str 32 | 所属迭代（规划阶段可空） |
|
||
| feature_name | str 200, not null | 功能名称 |
|
||
| description | text | 功能描述 |
|
||
| feature_type | str 20, default 'new_feature' | 功能类型（new_feature/enhancement/bugfix） |
|
||
| priority | str 10, default 'P2' | 优先级（P0/P1/P2/P3） |
|
||
| status | str 20, not null, default 'proposed' | 功能状态 |
|
||
| acceptance_criteria | text | 验收标准 |
|
||
| task_id | str 32 | 关联 pipeline 任务ID |
|
||
| created_by | str 32 | 创建人 |
|
||
| created_at / updated_at | timestamp | 时间戳 |
|
||
|
||
索引：idx_sd_features_project(project_id)、idx_sd_features_iteration(iteration_id)、idx_sd_features_status(status)
|
||
|
||
### sd_feature_status appcodes（需新增）
|
||
|
||
```
|
||
proposed 已提出 / approved 已批准 / in_progress 开发中 / delivered 已交付 / verified 已验证 / rejected 已驳回
|
||
```
|
||
|
||
### feature 状态机流转图
|
||
|
||
```
|
||
proposed ──approve──▶ approved ──start──▶ in_progress ──deliver──▶ delivered ──verify──▶ verified
|
||
│ │ ▲
|
||
│ reject │ reject │
|
||
▼ ▼ │
|
||
rejected ◀───────────────┴────────── reopen ───────────────────────────────┘
|
||
```
|
||
|
||
### feature skill frontmatter
|
||
|
||
```yaml
|
||
---
|
||
name: feature
|
||
description: SDLC 产线默认功能/需求状态机规范——定义功能状态、合法流转、角色→操作权限、门禁、验收标准。项目可同名覆盖。触发：提出/审批/开发/交付/验证功能，或用户提到新功能、需求拆解。
|
||
capability: feature_capability
|
||
tools: [propose_feature, approve_feature, reject_feature, start_feature, deliver_feature, verify_feature, reopen_feature, list_features]
|
||
---
|
||
```
|