docs: 更新TRA编程培训课程材料、课件与AI技能交付包
- 新增全套考试卷、评估卷、参考答案与考试培训包模板 - 修正slidev培训课件：调整模块标题、链路图缩放，替换工单示例为通用业务对象 - 修正课堂红线表述为证据红线，将小组作业调整为个人作业要求 - 新增权限、状态流转、审计日志、看板指标四类可复用业务规则块 - 整理AI工程技能交付包，迁移旧资产至客户专属交付包并统一术语 - 新增考试输出模板与TRAE使用记录文档
This commit is contained in:
smart
@@ -1,8 +1,8 @@
|
||||
# 客户 AI 工程 Skill 交付包
|
||||
# 客户 AI 工程资产交付包
|
||||
|
||||
本交付包提供 4 个可复用 AI 工程 Skill，覆盖真实项目中从项目约束生成、复杂业务设计、交付 Review 到修复闭环的完整流程。
|
||||
本包是第五、六天课程配套的正式资产交付物，用于把 AI 编程中的项目理解、约束提取、复杂业务设计、交付 Review 和修复闭环沉淀为可维护的团队资产。
|
||||
|
||||
这些 Skill 不是单次 Prompt，而是可安装、可复制、可随项目持续维护的团队资产。
|
||||
它不包含客户代码、服务地址、账号、令牌、真实业务数据或未经验证的项目结论。所有业务字段、权限码、接口和状态均以占位符表达，使用时必须从目标项目重新取证。
|
||||
|
||||
## 交付内容
|
||||
|
||||
@@ -10,37 +10,46 @@
|
||||
客户AI工程Skill交付包/
|
||||
├── README.md
|
||||
├── 安装说明.md
|
||||
├── 交付清单.md
|
||||
├── skills/
|
||||
│ ├── generate-project-constraints/
|
||||
│ ├── design-complex-business-module/
|
||||
│ ├── review-business-delivery/
|
||||
│ └── track-review-fix-loop/
|
||||
│ ├── generate-project-constraints/ # 提取项目规则与约束
|
||||
│ ├── project-knowledge-builder/ # 建立源码依据的项目知识库
|
||||
│ ├── design-complex-business-module/ # 设计权限、状态、审计、异常态和指标
|
||||
│ ├── review-business-delivery/ # 审查业务交付与变更风险
|
||||
│ └── track-review-fix-loop/ # 跟踪 Review 修复与验证闭环
|
||||
├── mcp-assets/
|
||||
│ ├── MCP能力契约.template.md
|
||||
│ └── MCP工具权限与验收清单.md
|
||||
└── examples/
|
||||
└── jeecgboot-work-order/
|
||||
└── jeecgboot-official-vehicle/
|
||||
└── 公务用车取消派车案例.md
|
||||
```
|
||||
|
||||
## Skill 列表
|
||||
|
||||
| Skill | 用途 | 典型产物 |
|
||||
| -------------------------------- | ------------------------------------------------ | --------------------------------------------- |
|
||||
| `generate-project-constraints` | 从项目源码、配置、CI、文档中提取项目约束 | rules、约束提取表、验收清单 |
|
||||
| `design-complex-business-module` | 设计复杂业务模块的权限、状态、审计、异常态和看板 | RBAC 矩阵、状态流转表、审计 SOP、看板指标字典 |
|
||||
| `review-business-delivery` | 审查复杂业务交付物或 PR 的业务风险 | 阶段 Review 报告、风险清单、验收建议 |
|
||||
| `track-review-fix-loop` | 跟踪 Review 问题修复、验证和资产沉淀 | 修复记录、未闭环清单、资产更新建议 |
|
||||
| Skill | 解决的问题 | 典型产物 |
|
||||
|---|---|---|
|
||||
| `generate-project-constraints` | 从源码、配置、测试和 CI 中提取项目约束 | Rule、约束提取表、验收清单 |
|
||||
| `project-knowledge-builder` | 建立可追溯、可持续更新的项目知识库 | 项目地图、接口与权限索引、维护指南 |
|
||||
| `design-complex-business-module` | 设计高风险业务模块的工程边界 | 权限矩阵、状态流转表、审计 SOP、指标字典 |
|
||||
| `review-business-delivery` | 审查设计、代码或 PR 的业务风险 | Review 报告、风险清单、验收建议 |
|
||||
| `track-review-fix-loop` | 跟踪问题修复、验证和资产更新 | 修复记录、未闭环清单、资产更新建议 |
|
||||
|
||||
## 推荐使用顺序
|
||||
## MCP 资产
|
||||
|
||||
1. 使用 `generate-project-constraints` 为项目生成项目规则。
|
||||
2. 使用 `design-complex-business-module` 生成复杂业务设计资产。
|
||||
3. 使用 `review-business-delivery` 审查设计、代码或阶段交付物。
|
||||
4. 使用 `track-review-fix-loop` 跟踪修复、验证结果和资产沉淀。
|
||||
`mcp-assets/` 只提供能力契约和验收清单，不预置任何 MCP 服务地址、工具配置或凭据。接入外部能力前，必须明确输入输出、数据范围、权限、副作用、失败降级和验证夹具；写入、删除、发布和外发能力不应作为通用 Agent 的默认权限。
|
||||
|
||||
## 适用项目
|
||||
## 公务用车案例
|
||||
|
||||
适用于后台管理系统、低代码平台二开、CRM、工单、审批、运营系统、数据看板等企业业务项目。
|
||||
`examples/jeecgboot-official-vehicle/` 是基于现有 JeecgBoot 公务用车模块的单人训练案例。它展示如何把“取消派车时取消原因不能为空”的训练改造，转成源码依据、最小改动边界、验证证据和待确认项。
|
||||
|
||||
这些 Skill 不要求项目必须有 `CLAUDE.md`、`AGENTS.md` 或 `README.md`。如果项目没有显式说明文档，Skill 会从配置、源码模式、测试和 CI 中提取约束，并把无法证明的内容标记为待确认。
|
||||
该案例只说明已读取到的项目事实与已执行验证，不代表客户已提出相同业务需求，也不能直接替代目标项目的重新取证。
|
||||
|
||||
## 示例说明
|
||||
## 使用边界
|
||||
|
||||
`examples/jeecgboot-work-order/` 提供 JeecgBoot 工单案例参考，帮助理解这些 Skill 在真实后台项目中的使用方式。该示例不是通用 Skill 安装项。
|
||||
- Skill 保存可复用的判断流程，不保存某个项目的路径、字段、接口或权限码。
|
||||
- Rule、任务上下文契约、检查单、模板、Skill、Agent 和 MCP 职责不同，应保持单一权威位置。
|
||||
- 任何没有源码、日志、测试或明确规范支持的结论，都要标记为待确认。
|
||||
- 资产变更应检查行为变化、引用完整性、兼容性、迁移与回退，并使用完整、缺失、冲突和越界输入夹具复核。
|
||||
|
||||
安装与团队使用方式见 [安装说明.md](./安装说明.md)，本次正式交付范围见 [交付清单.md](./交付清单.md)。
|
||||
|
||||
@@ -0,0 +1,48 @@
|
||||
# 公务用车取消派车：影响分析与验证案例
|
||||
|
||||
## 案例边界
|
||||
|
||||
本案例来自当前 JeecgBoot 已接入的公务用车模块，用于单人练习“先取证、再限制改动范围、最后如实记录验证”的工作方式。
|
||||
|
||||
训练改造目标：取消已派车任务时，后端必须拒绝空值和全空白的取消原因。前端表单必填只用于减少误操作，不能替代 Service 入口的业务保护。
|
||||
|
||||
本案例不代表客户已提出相同需求；其他项目必须重新读取自身源码、配置和测试材料。
|
||||
|
||||
## 已确认的项目事实
|
||||
|
||||
| 维度 | 已读取依据 | 结论 |
|
||||
|---|---|---|
|
||||
| 前端入口 | `jeecgboot-vue3/src/views/official/vehicle/dispatch/DispatchList.vue`、`DispatchModal.vue`、`dispatch.data.ts` | 仅在有取消权限且派车状态为 `DISPATCHED` 时显示取消操作；弹窗已配置取消原因必填。 |
|
||||
| 前端 API | `jeecgboot-vue3/src/api/official/vehicle/dispatch.ts` | 页面外仍可直接调用取消接口，因此前端必填不是最终保护。 |
|
||||
| 后端入口 | `OfficialVehicleDispatchController.java`、`OfficialVehicleDispatchServiceImpl.java` | Controller 负责权限与请求转交；Service 负责状态写入和车辆状态释放。 |
|
||||
| 取消参数 | `OfficialVehicleCancelDispatchVo.java` | 请求体包含派车 ID 与取消原因，原有参数对象未限制空白文本。 |
|
||||
| 测试基座 | `OfficialVehicleDispatchControllerTest.java`、模块 `pom.xml` | 模块具备 JUnit 测试基础，原用例未覆盖空白取消原因。 |
|
||||
|
||||
## 可直接复用的任务上下文契约
|
||||
|
||||
```text
|
||||
请基于当前打开的项目，且只基于实际读取到的源码，完成一次变更影响分析；不要修改代码，不要猜测项目外逻辑。
|
||||
|
||||
训练目标：取消已派车任务时，取消原因必须为非空文本；前端必填不能替代后端业务保护。
|
||||
|
||||
请读取前端页面、前端 API、后端 Controller、Service、参数对象、实体、现有测试、模块构建配置和必要数据库脚本。
|
||||
|
||||
请输出：已读取源码；已确认事实及文件依据；必须检查的模块；接口、数据、权限、状态、配置和测试影响；明确不改动项；不超过四步的最小改动计划；人工待确认项。
|
||||
|
||||
要求：事实与推测分开；没有源码或验证证据时标记待确认；不编造测试结果；不直接实施修改。
|
||||
```
|
||||
|
||||
## 实际改动与证据
|
||||
|
||||
| 项目 | 记录 |
|
||||
|---|---|
|
||||
| 最小改动 | 在 `OfficialVehicleDispatchServiceImpl.cancel` 的状态写入前加入取消原因非空校验。 |
|
||||
| 对应测试 | 新增 Service 定向测试，传入全空白取消原因并断言请求被拒绝。 |
|
||||
| 已执行验证 | Maven 定向测试已执行成功，定向 Service 测试通过。 |
|
||||
| 保持不变 | 前端必填、既有取消权限、审计注解、车辆状态释放逻辑和数据库表结构未修改。 |
|
||||
|
||||
## 结论边界
|
||||
|
||||
下列事项没有被本案例写成“已通过”：实际数据库中非空取消原因的正常取消回归、HTTP 响应映射、浏览器提示、审计记录和车辆状态的集成环境验证。
|
||||
|
||||
这正是本案例的核心要求：已有证据支持多大的结论，就只形成多大的结论。
|
||||
@@ -1,44 +0,0 @@
|
||||
# JeecgBoot 工单模块开发审查 Skill
|
||||
|
||||
## 触发场景
|
||||
|
||||
涉及工单列表、详情、评论、状态、指派、看板、权限字符、数据权限、操作日志的需求拆解、代码生成或代码修改。
|
||||
|
||||
## 输入材料
|
||||
|
||||
- PR diff 或相关文件。
|
||||
- 工单需求说明。
|
||||
- 数据模型与接口契约。
|
||||
- 当前 rules。
|
||||
- 前端页面文件。
|
||||
- API 模块文件。
|
||||
- 后端 Controller / Service。
|
||||
- 权限矩阵。
|
||||
- 状态流转表。
|
||||
- 审计日志 SOP。
|
||||
|
||||
## 执行步骤
|
||||
|
||||
1. 识别需求范围和非目标范围。
|
||||
2. 检查字段、接口契约和页面状态是否完整。
|
||||
3. 审查 JeecgBoot 生成代码的字段、查询、分页、字典和异常态。
|
||||
4. 检查新增、编辑、删除、指派、状态变更的前端按钮与后端权限。
|
||||
5. 检查操作日志、数据权限和测试缺口。
|
||||
6. 检查看板指标口径和接口验收记录。
|
||||
7. 输出风险、不确定点和验收建议。
|
||||
|
||||
## 输出格式
|
||||
|
||||
- 需求范围确认。
|
||||
- 接口契约问题表。
|
||||
- 代码生成 Review 清单。
|
||||
- 权限风险表。
|
||||
- 状态流转风险表。
|
||||
- 审计日志风险表。
|
||||
- 测试缺口清单。
|
||||
- 不确定点清单。
|
||||
|
||||
## 验收标准
|
||||
|
||||
每个关键结论必须标注文件、函数、注解、配置或调用链依据。每条建议必须有验收方式。
|
||||
|
||||
@@ -0,0 +1,33 @@
|
||||
# MCP 工具权限与验收清单
|
||||
|
||||
## 接入前
|
||||
|
||||
- [ ] 已确认该能力确实需要 MCP，而非 CLI、Rule、任务上下文契约 或 Skill。
|
||||
- [ ] 每个工具都有用途、输入、输出、副作用和错误语义说明。
|
||||
- [ ] 已确认数据范围、鉴权、审计和脱敏要求。
|
||||
- [ ] 未将密钥、Token、账号、完整个人信息或内部地址写入配置、示例或日志。
|
||||
- [ ] 已明确只读、可逆写入和不可逆操作，未根据工具名称猜测性质。
|
||||
|
||||
## Agent 授权
|
||||
|
||||
- [ ] 每个自定义 Agent 只绑定完成职责所需的 MCP 工具。
|
||||
- [ ] 读取受限信息时，调用身份和数据范围可被 MCP 服务校验。
|
||||
- [ ] 写入、删除、发布和外发操作不属于通用 Agent 默认权限。
|
||||
- [ ] 有副作用操作具备二次确认、幂等或明确的重复调用处理。
|
||||
- [ ] Agent 在 MCP 失败时输出“外部事实未取得”，不编造结果。
|
||||
|
||||
## 验收夹具
|
||||
|
||||
- [ ] 合法完整请求：返回结构、来源时间和范围符合契约。
|
||||
- [ ] 缺少必填参数：拒绝并指出缺口。
|
||||
- [ ] 越权请求：拒绝或触发确认，不泄露超范围数据。
|
||||
- [ ] 鉴权失败、限流、超时和服务错误：错误类型可区分。
|
||||
- [ ] 返回空结果：与工具故障明确区分。
|
||||
- [ ] 敏感字段：按契约脱敏，审计日志不暴露秘密信息。
|
||||
- [ ] 重复调用：符合幂等设计或被安全阻止。
|
||||
|
||||
## 结论
|
||||
|
||||
- [ ] 可接入：契约、权限、审计、失败处理和验收夹具完整。
|
||||
- [ ] 待确认：记录缺失的外部规范或验证材料。
|
||||
- [ ] 不接入：说明改用 CLI、Skill 或人工流程的原因。
|
||||
@@ -0,0 +1,34 @@
|
||||
# MCP 能力契约
|
||||
|
||||
## 基本信息
|
||||
|
||||
| 字段 | 内容 |
|
||||
|---|---|
|
||||
| 服务名称 | `<名称>` |
|
||||
| 接入目的 | `<要解决的外部事实或操作>` |
|
||||
| 适用场景 | `<何时允许使用>` |
|
||||
| 不适用场景 | `<何时不得使用>` |
|
||||
| 来源依据 | `<接口文档、系统规范或已验证记录>` |
|
||||
|
||||
## 工具清单
|
||||
|
||||
| 工具 | 用途 | 输入契约 | 输出契约 | 副作用 | 权限与确认 | 错误语义 | 审计与脱敏 |
|
||||
|---|---|---|---|---|---|---|---|
|
||||
| `<tool>` | `<用途>` | `<必填、格式、范围>` | `<字段、时效、空值>` | `只读 / 可逆写入 / 不可逆` | `<调用资格与确认>` | `<鉴权、限流、超时等>` | `<留痕字段与脱敏规则>` |
|
||||
|
||||
## Agent 绑定边界
|
||||
|
||||
- 允许调用的自定义 Agent：`<名称或角色>`。
|
||||
- 不允许调用的 Agent：`<名称或角色>`。
|
||||
- Agent 调用前必须具备的运行时事实：`<数据范围、目标对象、确认信息>`。
|
||||
- Agent 调用后必须输出：`<来源、时间、结果、失败或待确认>`。
|
||||
|
||||
## 停止与降级
|
||||
|
||||
| 情况 | MCP 或 Agent 的行为 |
|
||||
|---|---|
|
||||
| 缺少关键输入 | 拒绝调用并列出字段缺口 |
|
||||
| 鉴权或数据范围不满足 | 拒绝调用，不尝试扩大权限 |
|
||||
| 限流、超时或服务不可用 | 区分故障类型，标记外部事实未取得 |
|
||||
| 有副作用但未确认 | 停止并请求确认 |
|
||||
| 返回敏感信息 | 按规则脱敏，避免写入任务记录或日志 |
|
||||
@@ -0,0 +1,29 @@
|
||||
# MCP 能力资产包
|
||||
|
||||
本目录用于沉淀可被 Agent 调用的外部能力边界，不保存任何服务地址、访问令牌、账号、内部域名或业务数据。
|
||||
|
||||
## 何时使用
|
||||
|
||||
- 需要跨系统读取经授权的事实、日志或文档。
|
||||
- 需要调用具有结构化输入输出的外部工具。
|
||||
- 需要将浏览器、数据库、内部平台或其他服务能力提供给 Agent。
|
||||
|
||||
## 不适用场景
|
||||
|
||||
- 已有稳定命令且不需要交互式工具调用的任务，优先使用 CLI。
|
||||
- 只有知识、流程、模板或检查清单的任务，优先沉淀为 Rule、任务上下文契约或 Skill。
|
||||
- 未确认数据范围、鉴权方式、审计要求或副作用的外部服务。
|
||||
|
||||
## 使用顺序
|
||||
|
||||
1. 使用 `MCP能力契约.template.md` 描述每个拟接入的服务与工具。
|
||||
2. 使用 `MCP工具权限与验收清单.md` 审查权限、敏感数据、错误和副作用。
|
||||
3. 为完整请求、缺参、越权、故障和脱敏结果准备验证夹具。
|
||||
4. 只有契约与验收都满足时，才将对应工具分配给自定义 Agent 或 Skill。
|
||||
|
||||
## 基本原则
|
||||
|
||||
- 不根据工具名称推断只读或安全性。
|
||||
- 外部工具失败时，结论必须标记为“外部事实未取得”。
|
||||
- 写入、删除、发布和外发能力不应作为通用 Agent 的默认权限。
|
||||
- 日志、示例和夹具不得包含密钥、Token、账号、完整个人信息或内部地址。
|
||||
+13
-13
@@ -1,16 +1,16 @@
|
||||
# 工单 RBAC 权限矩阵
|
||||
# 业务对象 RBAC 权限矩阵
|
||||
|
||||
| 功能点 | 管理员 | 工单负责人 | 研发处理人 | 测试验证人 | 只读观察者 | 权限字符建议 | 备注 |
|
||||
| 功能点 | 管理员 | 业务对象负责人 | 研发处理人 | 测试验证人 | 只读观察者 | 权限字符建议 | 备注 |
|
||||
| --- | --- | --- | --- | --- | --- | --- | --- |
|
||||
| 查看列表 | 允许 | 条件允许 | 条件允许 | 条件允许 | 条件允许 | work:order:list | 按数据范围 |
|
||||
| 查看详情 | 允许 | 条件允许 | 条件允许 | 条件允许 | 条件允许 | work:order:query | 仅可见范围 |
|
||||
| 新建工单 | 允许 | 允许 | 允许 | 允许 | 拒绝 | work:order:add | |
|
||||
| 编辑工单 | 允许 | 条件允许 | 条件允许 | 拒绝 | 拒绝 | work:order:edit | 状态限制 |
|
||||
| 指派负责人 | 允许 | 条件允许 | 拒绝 | 拒绝 | 拒绝 | work:order:assign | |
|
||||
| 状态流转 | 允许 | 条件允许 | 条件允许 | 条件允许 | 拒绝 | work:order:transition | 按状态 |
|
||||
| 关闭工单 | 允许 | 条件允许 | 拒绝 | 条件允许 | 拒绝 | work:order:close | 测试验证后 |
|
||||
| 删除工单 | 允许 | 拒绝 | 拒绝 | 拒绝 | 拒绝 | work:order:delete | 高危操作 |
|
||||
| 查看审计日志 | 允许 | 条件允许 | 条件允许 | 条件允许 | 拒绝 | work:order:audit | |
|
||||
| 查看看板 | 允许 | 允许 | 条件允许 | 条件允许 | 条件允许 | work:order:dashboard | 按数据范围 |
|
||||
| 导出数据 | 允许 | 条件允许 | 拒绝 | 拒绝 | 拒绝 | work:order:export | |
|
||||
| 查看列表 | 允许 | 条件允许 | 条件允许 | 条件允许 | 条件允许 | <module>:list | 按数据范围 |
|
||||
| 查看详情 | 允许 | 条件允许 | 条件允许 | 条件允许 | 条件允许 | <module>:query | 仅可见范围 |
|
||||
| 新建业务对象 | 允许 | 允许 | 允许 | 允许 | 拒绝 | <module>:add | |
|
||||
| 编辑业务对象 | 允许 | 条件允许 | 条件允许 | 拒绝 | 拒绝 | <module>:edit | 状态限制 |
|
||||
| 指派负责人 | 允许 | 条件允许 | 拒绝 | 拒绝 | 拒绝 | <module>:assign | |
|
||||
| 状态流转 | 允许 | 条件允许 | 条件允许 | 条件允许 | 拒绝 | <module>:transition | 按状态 |
|
||||
| 关闭业务对象 | 允许 | 条件允许 | 拒绝 | 条件允许 | 拒绝 | <module>:close | 测试验证后 |
|
||||
| 删除业务对象 | 允许 | 拒绝 | 拒绝 | 拒绝 | 拒绝 | <module>:delete | 高危操作 |
|
||||
| 查看审计日志 | 允许 | 条件允许 | 条件允许 | 条件允许 | 拒绝 | <module>:audit | |
|
||||
| 查看看板 | 允许 | 允许 | 条件允许 | 条件允许 | 条件允许 | <module>:dashboard | 按数据范围 |
|
||||
| 导出数据 | 允许 | 条件允许 | 拒绝 | 拒绝 | 拒绝 | <module>:export | |
|
||||
|
||||
|
||||
+4
-4
@@ -1,11 +1,11 @@
|
||||
# RBAC 权限矩阵生成 Prompt
|
||||
# RBAC 权限矩阵生成 任务上下文契约
|
||||
|
||||
```text
|
||||
请基于 JeecgBoot 工单模块设计 RBAC 权限矩阵。
|
||||
请基于 目标业务模块设计 RBAC 权限矩阵。
|
||||
|
||||
输入材料：
|
||||
- 工单模块需求：<粘贴需求>
|
||||
- 角色列表：管理员、工单负责人、研发处理人、测试验证人、只读观察者
|
||||
- 业务模块需求：<粘贴需求>
|
||||
- 角色列表：管理员、业务对象负责人、研发处理人、测试验证人、只读观察者
|
||||
- 功能点：查看列表、查看详情、新建、编辑、指派、状态流转、关闭、删除、查看审计、查看看板、导出
|
||||
- 项目依据：<粘贴权限、路由、菜单相关路径>
|
||||
|
||||
|
||||
+5
-5
@@ -1,14 +1,14 @@
|
||||
# 工单审计日志 SOP
|
||||
# 业务对象审计日志 SOP
|
||||
|
||||
## 记录原则
|
||||
|
||||
所有会改变工单关键业务状态、负责人、可见性或结论的动作都必须记录审计日志。
|
||||
所有会改变业务对象关键业务状态、负责人、可见性或结论的动作都必须记录审计日志。
|
||||
|
||||
## 审计字段
|
||||
|
||||
| 字段 | 含义 | 示例 |
|
||||
| --- | --- | --- |
|
||||
| ticket_id | 工单 ID | WO-001 |
|
||||
| <business_id> | 业务对象 ID | <业务编号> |
|
||||
| actor_id | 操作人 ID | 1001 |
|
||||
| actor_name | 操作人名称 | zhangsan |
|
||||
| action | 操作类型 | ASSIGN |
|
||||
@@ -23,12 +23,12 @@
|
||||
|
||||
| 动作 | 写入时机 | oldValue | newValue | 验收 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 创建工单 | 创建成功后 | 空 | 工单摘要 | 审计列表可见 |
|
||||
| 创建业务对象 | 创建成功后 | 空 | 业务对象摘要 | 审计列表可见 |
|
||||
| 编辑字段 | 保存成功后 | 修改前字段 | 修改后字段 | 字段前后值正确 |
|
||||
| 指派负责人 | 指派成功后 | 原负责人 | 新负责人 | 审计记录负责人变化 |
|
||||
| 状态流转 | 状态变更成功后 | 原状态 | 新状态 | 审计记录状态变化 |
|
||||
| 评论新增 | 评论保存后 | 空 | 评论摘要 | 审计记录评论动作 |
|
||||
| 关闭工单 | 关闭成功后 | 原状态 | 已关闭 | 审计记录关闭时间 |
|
||||
| 关闭业务对象 | 关闭成功后 | 原状态 | 已关闭 | 审计记录关闭时间 |
|
||||
|
||||
## 验收方式
|
||||
|
||||
|
||||
+1
-1
@@ -2,7 +2,7 @@
|
||||
|
||||
| 检查项 | 通过标准 | 结果 |
|
||||
| --- | --- | --- |
|
||||
| 创建记录 | 创建工单后能查询审计记录 | |
|
||||
| 创建记录 | 创建业务对象后能查询审计记录 | |
|
||||
| 字段变更 | 编辑关键字段记录 oldValue/newValue | |
|
||||
| 指派记录 | 指派负责人记录原负责人和新负责人 | |
|
||||
| 状态记录 | 状态流转记录原状态和新状态 | |
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
| 异常态 | 必须验证 | 结果 |
|
||||
| --- | --- | --- |
|
||||
| 空列表 | 页面显示空状态，不报错 | |
|
||||
| 详情不存在 | 提示工单不存在，页面不崩溃 | |
|
||||
| 详情不存在 | 提示业务对象不存在，页面不崩溃 | |
|
||||
| 权限不足 | 前端提示或隐藏，后端拒绝 | |
|
||||
| 非法状态 | 返回非法流转，状态不变 | |
|
||||
| 重复提交 | 只成功一次，只写一条有效审计 | |
|
||||
|
||||
+2
-2
@@ -1,9 +1,9 @@
|
||||
# 工单异常态清单
|
||||
# 业务对象异常态清单
|
||||
|
||||
| 场景 | 触发条件 | 前端表现 | 后端响应 | 验收 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 权限不足 | 无权限操作 | 按钮不可见或提示无权限 | 403 或业务拒绝 | 不完成操作 |
|
||||
| 工单不存在 | 传入错误 ID | 显示不存在 | 404 或业务错误 | 页面不崩溃 |
|
||||
| 业务对象不存在 | 传入错误 ID | 显示不存在 | 404 或业务错误 | 页面不崩溃 |
|
||||
| 非法状态流转 | closed -> processing | 提示非法流转 | 状态不变 | 数据状态不变 |
|
||||
| 重复提交 | 连续点击提交 | 按钮 loading/禁用 | 只处理一次 | 只生成一条有效审计 |
|
||||
| 参数缺失 | 驳回缺少原因 | 表单校验提示 | 参数错误 | 不改变状态 |
|
||||
|
||||
+3
-3
@@ -1,14 +1,14 @@
|
||||
# 异常态补齐 Prompt
|
||||
# 异常态补齐 任务上下文契约
|
||||
|
||||
```text
|
||||
请基于 JeecgBoot 工单模块，列出状态流转、指派、删除、查询详情、审计日志、看板相关的异常态和防御性逻辑。
|
||||
请基于 目标业务模块，列出状态流转、指派、删除、查询详情、审计日志、看板相关的异常态和防御性逻辑。
|
||||
|
||||
输出表格：
|
||||
场景 | 触发条件 | 前端表现 | 后端响应 | 用户提示 | 测试点 | 验收
|
||||
|
||||
必须覆盖：
|
||||
- 权限不足
|
||||
- 工单不存在
|
||||
- 业务对象不存在
|
||||
- 非法状态流转
|
||||
- 重复提交
|
||||
- 参数缺失
|
||||
|
||||
+2
-2
@@ -2,10 +2,10 @@
|
||||
|
||||
| 检查项 | 通过标准 | 结果 |
|
||||
| --- | --- | --- |
|
||||
| 菜单权限 | 工单菜单只对授权角色可见 | |
|
||||
| 菜单权限 | 业务对象菜单只对授权角色可见 | |
|
||||
| 按钮权限 | 新增、编辑、删除、指派、状态按钮按权限显示 | |
|
||||
| 接口权限 | 无权限账号直接请求敏感接口失败 | |
|
||||
| 数据权限 | 普通用户只能看到授权范围内工单 | |
|
||||
| 数据权限 | 普通用户只能看到授权范围内业务对象 | |
|
||||
| 权限字符 | 前端按钮、菜单配置、后端接口命名一致 | |
|
||||
| 审计 | 权限敏感操作成功后有审计记录 | |
|
||||
| 反例验证 | 无权限账号不能绕过前端执行删除/指派 | |
|
||||
|
||||
+8
-8
@@ -1,12 +1,12 @@
|
||||
# 工单权限控制方案
|
||||
# 业务对象权限控制方案
|
||||
|
||||
| 操作 | 前端入口 | 权限字符 | 后端接口 | 后端校验 | 数据权限 | 验收 |
|
||||
| --- | --- | --- | --- | --- | --- | --- |
|
||||
| 新增工单 | 新增按钮 | work:order:add | /workOrder/add | 权限注解 | 无 | 无权限账号看不到按钮且直接请求失败 |
|
||||
| 编辑工单 | 编辑按钮 | work:order:edit | /workOrder/edit | 权限注解 + 状态校验 | 负责人/创建人范围 | 越权账号返回 403 或业务拒绝 |
|
||||
| 指派负责人 | 指派按钮 | work:order:assign | /workOrder/assign | 权限注解 | 管理员/负责人范围 | 普通研发无法指派他人 |
|
||||
| 状态流转 | 状态按钮 | work:order:transition | /workOrder/transition | 权限注解 + 状态机校验 | 相关工单范围 | 非法流转失败 |
|
||||
| 删除工单 | 删除按钮 | work:order:delete | /workOrder/delete | 权限注解 | 管理员范围 | 非管理员返回 403 |
|
||||
| 查看审计 | 审计页签 | work:order:audit | /workOrder/audit/list | 权限注解 | 相关工单范围 | 无权限不可见且接口拒绝 |
|
||||
| 看板 | 看板菜单 | work:order:dashboard | /workOrder/dashboard | 权限注解 | 数据范围过滤 | 不同角色数据范围不同 |
|
||||
| 新增业务对象 | 新增按钮 | <module>:add | /<module>/add | 权限注解 | 无 | 无权限账号看不到按钮且直接请求失败 |
|
||||
| 编辑业务对象 | 编辑按钮 | <module>:edit | /<module>/edit | 权限注解 + 状态校验 | 负责人/创建人范围 | 越权账号返回 403 或业务拒绝 |
|
||||
| 指派负责人 | 指派按钮 | <module>:assign | /<module>/assign | 权限注解 | 管理员/负责人范围 | 普通研发无法指派他人 |
|
||||
| 状态流转 | 状态按钮 | <module>:transition | /<module>/transition | 权限注解 + 状态机校验 | 相关业务对象范围 | 非法流转失败 |
|
||||
| 删除业务对象 | 删除按钮 | <module>:delete | /<module>/delete | 权限注解 | 管理员范围 | 非管理员返回 403 |
|
||||
| 查看审计 | 审计页签 | <module>:audit | /<module>/audit/list | 权限注解 | 相关业务对象范围 | 无权限不可见且接口拒绝 |
|
||||
| 看板 | 看板菜单 | <module>:dashboard | /<module>/dashboard | 权限注解 | 数据范围过滤 | 不同角色数据范围不同 |
|
||||
|
||||
|
||||
+2
-2
@@ -1,7 +1,7 @@
|
||||
# 权限控制方案生成 Prompt
|
||||
# 权限控制方案生成 任务上下文契约
|
||||
|
||||
```text
|
||||
请基于工单模块 RBAC 权限矩阵，生成 JeecgBoot 权限控制方案。
|
||||
请基于业务模块 RBAC 权限矩阵，生成 JeecgBoot 权限控制方案。
|
||||
|
||||
输入材料：
|
||||
- RBAC 权限矩阵：<粘贴>
|
||||
|
||||
+2
-2
@@ -1,8 +1,8 @@
|
||||
# 工单状态流转表
|
||||
# 业务对象状态流转表
|
||||
|
||||
| 当前状态 | 动作 | 目标状态 | 允许角色 | 前置条件 | 后置动作 | 验收 |
|
||||
| --- | --- | --- | --- | --- | --- | --- |
|
||||
| 新建 | 指派 | 新建 | 管理员/负责人 | 工单未关闭 | 写审计日志 | 指派人变化且状态不变 |
|
||||
| 新建 | 指派 | 新建 | 管理员/负责人 | 业务对象未关闭 | 写审计日志 | 指派人变化且状态不变 |
|
||||
| 新建 | 开始处理 | 处理中 | 研发处理人/负责人 | 已指派处理人 | 写审计日志 | 状态变为处理中 |
|
||||
| 处理中 | 提交验证 | 待验证 | 研发处理人/负责人 | 处理说明不为空 | 写审计日志 | 状态变为待验证 |
|
||||
| 待验证 | 验证通过 | 已关闭 | 测试验证人/负责人 | 验证结果通过 | 写审计日志和关闭时间 | 状态变为已关闭 |
|
||||
|
||||
+2
-2
@@ -1,7 +1,7 @@
|
||||
# 状态流转设计 Prompt
|
||||
# 状态流转设计 任务上下文契约
|
||||
|
||||
```text
|
||||
请为 JeecgBoot 工单模块设计状态流转规则。
|
||||
请为 目标业务模块设计状态流转规则。
|
||||
|
||||
状态候选：
|
||||
- 新建
|
||||
|
||||
+9
-9
@@ -1,13 +1,13 @@
|
||||
# 工单看板指标字典
|
||||
# 业务对象看板指标字典
|
||||
|
||||
| 指标 | 含义 | 口径 | 数据来源 | 展示方式 | 权限 | 验收 |
|
||||
| --- | --- | --- | --- | --- | --- | --- |
|
||||
| 工单总数 | 当前筛选范围内工单数量 | count(ticket_id) | 工单表 | 指标卡 | 看板权限 | 与列表同条件数量一致 |
|
||||
| 未关闭工单数 | 状态不是已关闭的数量 | status != closed | 工单表 | 指标卡 | 看板权限 | 过滤状态验证 |
|
||||
| 平均关闭周期 | 从创建到关闭平均耗时 | avg(close_time - create_time) | 工单表 | 指标卡/趋势 | 看板权限 | 抽样计算一致 |
|
||||
| 按优先级分布 | 高中低优先级数量 | group by priority | 工单表/字典 | 饼图/柱状图 | 看板权限 | 分组总和等于总数 |
|
||||
| 按类型分布 | 缺陷/需求/支持数量 | group by type | 工单表/字典 | 柱状图 | 看板权限 | 分组总和等于总数 |
|
||||
| 缺陷趋势 | 按日期统计缺陷工单 | type=bug group by date | 工单表 | 折线图 | 看板权限 | 日期范围正确 |
|
||||
| 逾期工单数 | 超过 SLA 未关闭数量 | due_time < now and status != closed | 工单表 | 指标卡 | 看板权限 | SLA 口径明确 |
|
||||
| 人员处理负载 | 按负责人统计未关闭数量 | group by assignee | 工单表 | 排行榜 | 管理员/负责人 | 数据范围正确 |
|
||||
| 业务对象总数 | 当前筛选范围内业务对象数量 | count(<business_id>) | 业务对象表 | 指标卡 | 看板权限 | 与列表同条件数量一致 |
|
||||
| 未关闭业务对象数 | 状态不是已关闭的数量 | status != closed | 业务对象表 | 指标卡 | 看板权限 | 过滤状态验证 |
|
||||
| 平均关闭周期 | 从创建到关闭平均耗时 | avg(close_time - create_time) | 业务对象表 | 指标卡/趋势 | 看板权限 | 抽样计算一致 |
|
||||
| 按优先级分布 | 高中低优先级数量 | group by priority | 业务对象表/字典 | 饼图/柱状图 | 看板权限 | 分组总和等于总数 |
|
||||
| 按类型分布 | 缺陷/需求/支持数量 | group by type | 业务对象表/字典 | 柱状图 | 看板权限 | 分组总和等于总数 |
|
||||
| 缺陷趋势 | 按日期统计缺陷业务对象 | type=bug group by date | 业务对象表 | 折线图 | 看板权限 | 日期范围正确 |
|
||||
| 逾期业务对象数 | 超过 SLA 未关闭数量 | due_time < now and status != closed | 业务对象表 | 指标卡 | 看板权限 | SLA 口径明确 |
|
||||
| 人员处理负载 | 按负责人统计未关闭数量 | group by assignee | 业务对象表 | 排行榜 | 管理员/负责人 | 数据范围正确 |
|
||||
|
||||
|
||||
+5
-5
@@ -1,16 +1,16 @@
|
||||
# 看板指标设计 Prompt
|
||||
# 看板指标设计 任务上下文契约
|
||||
|
||||
```text
|
||||
请为 JeecgBoot 工单模块设计研发效能看板指标。
|
||||
请为 目标业务模块设计研发效能看板指标。
|
||||
|
||||
指标方向：
|
||||
- 工单总数
|
||||
- 未关闭工单数
|
||||
- 业务对象总数
|
||||
- 未关闭业务对象数
|
||||
- 平均关闭周期
|
||||
- 按优先级分布
|
||||
- 按类型分布
|
||||
- 缺陷趋势
|
||||
- 逾期工单数
|
||||
- 逾期业务对象数
|
||||
- 人员处理负载
|
||||
|
||||
输出要求：
|
||||
|
||||
+2
-2
@@ -1,7 +1,7 @@
|
||||
# 看板接口验收 Prompt
|
||||
# 看板接口验收 任务上下文契约
|
||||
|
||||
```text
|
||||
请为 JeecgBoot 工单看板统计接口生成验收记录。
|
||||
请为 目标业务看板统计接口生成验收记录。
|
||||
|
||||
输入材料：
|
||||
- 看板指标字典：<粘贴>
|
||||
|
||||
+1
-1
@@ -4,7 +4,7 @@
|
||||
| --- | --- | --- | --- |
|
||||
| 默认查询 | 管理员默认条件 | 返回完整指标 | |
|
||||
| 时间过滤 | 指定 start/end | 只统计时间范围内数据 | |
|
||||
| 类型过滤 | 指定工单类型 | 只统计对应类型 | |
|
||||
| 类型过滤 | 指定业务对象类型 | 只统计对应类型 | |
|
||||
| 空数据 | 无匹配条件 | 返回 0 或空集合 | |
|
||||
| 无权限 | 未授权账号 | 返回 403 或业务拒绝 | |
|
||||
| 数据范围 | 普通角色 | 只返回授权范围 | |
|
||||
|
||||
+2
-2
@@ -1,8 +1,8 @@
|
||||
# 工单看板接口验收记录
|
||||
# 业务对象看板接口验收记录
|
||||
|
||||
| 验收项 | 账号/条件 | 请求参数 | 预期 | 实际 | 证据 | 结论 |
|
||||
| --- | --- | --- | --- | --- | --- | --- |
|
||||
| 工单总数 | 管理员 | 默认筛选 | 返回总数 | | | |
|
||||
| 业务对象总数 | 管理员 | 默认筛选 | 返回总数 | | | |
|
||||
| 空数据 | 管理员 + 无匹配条件 | 不存在的日期范围 | 返回空集合或 0 | | | |
|
||||
| 无权限 | 只读外角色 | 默认筛选 | 返回 403 或业务拒绝 | | | |
|
||||
| 时间过滤 | 管理员 | start/end | 只统计范围内数据 | | | |
|
||||
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
# 项目约束生成 Prompt
|
||||
# 项目约束生成 任务上下文契约
|
||||
|
||||
请为下面项目生成可复用的 AI 开发约束资产。
|
||||
|
||||
|
||||
@@ -0,0 +1,133 @@
|
||||
---
|
||||
name: project-knowledge-builder
|
||||
description: Use when a user asks “项目知识库”, “看项目”, “整理项目”, or otherwise wants to inspect a software project deeply, build/refresh a project knowledge base, create onboarding docs, architecture maps, domain glossaries, ADRs, generated API/config/database indexes, or RAG-ready repository documentation.
|
||||
---
|
||||
|
||||
# Project Knowledge Builder
|
||||
|
||||
## Overview
|
||||
|
||||
Build a source-grounded project knowledge base that helps humans and AI agents understand, extend, troubleshoot, and index a codebase. Treat the knowledge base as a maintained system artifact, not a README rewrite.
|
||||
|
||||
## Quick Use
|
||||
|
||||
Users should not need to remember commands, script paths, or `$project-knowledge-builder`.
|
||||
|
||||
The shortest trigger is enough:
|
||||
|
||||
- `项目知识库`
|
||||
|
||||
Treat the current repository as the target and `docs/project-knowledge/` as the output path unless the user says otherwise. Run the bundled inventory script yourself and write the docs. Only show manual commands when the user explicitly asks for command-line usage.
|
||||
|
||||
## Language And Audience Defaults
|
||||
|
||||
If the user writes in Chinese or asks for Chinese, write human-facing narrative docs in Chinese by default: README, context, architecture, runtime, backend, frontend, data, auth/permissions, extension, troubleshooting, RAG guidance and ADRs. Keep source paths, class names, commands, API paths, config keys, table names, permission codes and metadata enum values unchanged.
|
||||
|
||||
Treat beginners as a primary audience. A useful knowledge base should let a new maintainer answer four questions without extra coaching:
|
||||
|
||||
1. What is this project and where are the main modules?
|
||||
2. How do I run it locally or identify the active runtime mode?
|
||||
3. How do I find the backend endpoint, frontend page, database table and permission code for a feature?
|
||||
4. What must change when adding a normal feature, especially menu/button permissions?
|
||||
|
||||
Do not make generated indexes overly friendly at the cost of precision. Keep generated files machine-refreshable; make narrative docs readable.
|
||||
|
||||
## Core Rule
|
||||
|
||||
Every claim must be traceable to the repository or to an explicitly marked inference. Prefer source paths, commands, generated inventories, and unresolved-question lists over confident prose.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. **Set scope.** Confirm or assume the output location. Default to `docs/project-knowledge/`. If the user mentions RAG, Feishu/Lark, Dify, Notion, onboarding, architecture review, or API docs, tailor the output contract.
|
||||
2. **Read local instructions first.** Check root docs plus `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.codex/`, `.agents/`, package manifests, build files, env examples, Docker files, and module READMEs.
|
||||
3. **Generate an inventory.** Run `scripts/project_inventory.py` from this skill against the repo. Use its output as a factual base, then inspect important files manually.
|
||||
4. **Map contexts.** Identify bounded contexts, runtime modes, major modules, owners implied by paths, external systems, and data stores. Use `CONTEXT.md` and `CONTEXT-MAP.md` style docs.
|
||||
5. **Extract generated indexes.** Produce machine-refreshable docs where possible: endpoints, frontend routes/views, config keys, env variables, database tables, permission codes, scheduled jobs, queues, and extension points.
|
||||
6. **Write human guides.** Produce onboarding, architecture, local run/deploy, data model, auth/permission, extension, troubleshooting, and glossary docs. Match the user's language for narrative docs; for Chinese users, use Chinese section titles such as `已观察来源`, `核心事实`, `操作影响`, and `未知与风险`.
|
||||
7. **Create ADRs for real decisions.** Record important architecture decisions already embodied in the code. Do not invent future decisions unless marked as proposed.
|
||||
8. **Add RAG metadata guidance.** Include chunking, source-path metadata, stale-data policy, and exclusion rules.
|
||||
9. **Verify.** Re-run the inventory, scan docs for placeholders, broken relative links, stale paths, and unsupported claims. Report what was verified and what remains uncertain.
|
||||
|
||||
## Output Contract
|
||||
|
||||
Read `references/output-contract.md` when creating or upgrading a full knowledge base.
|
||||
|
||||
Minimum useful set:
|
||||
|
||||
```text
|
||||
docs/project-knowledge/
|
||||
├── README.md
|
||||
├── CONTEXT.md
|
||||
├── CONTEXT-MAP.md
|
||||
├── 01-architecture.md
|
||||
├── 02-runtime.md
|
||||
├── 03-backend.md
|
||||
├── 04-frontend.md
|
||||
├── 05-data-and-migrations.md
|
||||
├── 06-auth-permissions.md
|
||||
├── 07-extension-guide.md
|
||||
├── 08-troubleshooting.md
|
||||
├── 09-rag-indexing.md
|
||||
├── adr/
|
||||
│ └── 0001-current-runtime-architecture.md
|
||||
└── generated/
|
||||
├── project-inventory.md
|
||||
├── backend-endpoints.md
|
||||
├── frontend-routes.md
|
||||
├── config-reference.md
|
||||
├── database-dictionary.md
|
||||
└── permission-codes.md
|
||||
```
|
||||
|
||||
Scale down only if the repo is small or the user requests a lighter artifact.
|
||||
|
||||
## Source-Grounding Standards
|
||||
|
||||
- Cite source paths inline for non-obvious claims.
|
||||
- Distinguish **Observed** from **Inferred** and **Unknown**.
|
||||
- Do not summarize generated code, dependencies, or configs from memory. Read them.
|
||||
- If external docs are needed for unstable facts, browse primary sources and link them.
|
||||
- Preserve project-specific conventions. If a repo requires trace comments, ADR format, or issue IDs, document and follow that.
|
||||
|
||||
## Cross-Platform Compatibility
|
||||
|
||||
Read `references/compatibility.md` when the user asks about macOS, Windows, Linux, CI, portability, or installing/running the skill across machines. The bundled inventory script is intended to run on Python 3.9+ with only the standard library.
|
||||
|
||||
## Inventory Script
|
||||
|
||||
Use this only for manual refreshes or when the user asks for the command. Run from the target repo:
|
||||
|
||||
macOS/Linux:
|
||||
|
||||
```sh
|
||||
python3 /path/to/skill/scripts/project_inventory.py --root . --out docs/project-knowledge/generated
|
||||
```
|
||||
|
||||
Windows PowerShell:
|
||||
|
||||
```powershell
|
||||
py -3 C:\path\to\skill\scripts\project_inventory.py --root . --out docs\project-knowledge\generated
|
||||
```
|
||||
|
||||
Useful options:
|
||||
|
||||
```sh
|
||||
python3 /path/to/skill/scripts/project_inventory.py --root . --out ./kb-inventory --json
|
||||
python3 /path/to/skill/scripts/project_inventory.py --root . --out docs/project-knowledge/generated --max-files 20000
|
||||
```
|
||||
|
||||
The script is a starting point, not a replacement for reading core files. Inspect representative files before writing narrative docs.
|
||||
|
||||
## Quality Gates
|
||||
|
||||
Before final response:
|
||||
|
||||
- List generated docs with a platform-appropriate command, such as `find docs/project-knowledge -type f | sort` on macOS/Linux or `Get-ChildItem docs/project-knowledge -Recurse -File` on PowerShell.
|
||||
- `rg -n "TODO|TBD|待补|unknown|your/path|foo|bar" docs/project-knowledge`
|
||||
- Re-run the inventory script after edits.
|
||||
- Check that top-level README links resolve.
|
||||
- If the user is Chinese, scan narrative docs for English-only structural headings such as `Observed Sources`, `Core Facts`, `Operational Implications`, `Unknowns/Risks`, `Architecture`, `Runtime`, `Backend`, `Frontend`, `Troubleshooting`, and translate them unless they are code, metadata, or generated output.
|
||||
- Check newcomer usefulness: README gives a reading order; runtime doc names local/Docker/cloud modes; auth doc explains menu/button permission flow; extension doc explains backend CRUD, frontend page and permission changes.
|
||||
- `git status --short` to report changed files.
|
||||
|
||||
If the user asked for “deep” or “落地”, do not stop at a single overview. Deliver generated indexes plus human guides.
|
||||
@@ -0,0 +1,133 @@
|
||||
---
|
||||
name: project-knowledge-builder
|
||||
description: 当用户要求“项目知识库”“看项目”“整理项目”，或需要深度检查软件项目、构建/刷新项目知识库、创建入门文档、架构图、领域词汇表、ADR、API/配置/数据库生成索引或 RAG 友好仓库文档时使用。
|
||||
---
|
||||
|
||||
# 项目知识库构建
|
||||
|
||||
## 概览
|
||||
|
||||
构建一个有源码依据的项目知识库，帮助人和 AI 理解、扩展、排障和索引代码库。把知识库视为持续维护的系统资产，而不是 README 改写。
|
||||
|
||||
## 快速使用
|
||||
|
||||
用户不需要记住命令、脚本路径或 `$project-knowledge-builder`。
|
||||
|
||||
最短触发语即可：
|
||||
|
||||
- `项目知识库`
|
||||
|
||||
除非用户另有说明，将当前仓库作为目标，输出到 `docs/project-knowledge/`。由你运行 bundled inventory 脚本并写文档。只有用户明确要求命令行用法时，才展示手工命令。
|
||||
|
||||
## 语言和受众默认值
|
||||
|
||||
如果用户使用中文或要求中文，人类阅读的叙述文档默认使用中文：README、上下文、架构、运行、后端、前端、数据、认证/权限、扩展、排障、RAG 指南和 ADR。源码路径、类名、命令、API 路径、配置键、表名、权限码、元数据枚举值保持原样。
|
||||
|
||||
把新维护者作为主要受众。一个有用的知识库应该让新人无需额外辅导就能回答四个问题：
|
||||
|
||||
1. 这个项目是什么，主要模块在哪里？
|
||||
2. 如何本地运行，或如何识别当前运行模式？
|
||||
3. 如何找到某个功能对应的后端接口、前端页面、数据库表和权限码？
|
||||
4. 新增普通功能时通常需要修改什么，尤其是菜单/按钮权限？
|
||||
|
||||
生成索引不要为了友好而牺牲精确性。生成文件要便于机器刷新；叙述文档要便于人阅读。
|
||||
|
||||
## 核心规则
|
||||
|
||||
每个结论都必须能追溯到仓库，或明确标记为推断。优先使用源码路径、命令、生成索引和未解决问题清单，而不是自信散文。
|
||||
|
||||
## 工作流
|
||||
|
||||
1. **设定范围。** 确认或默认输出位置为 `docs/project-knowledge/`。如果用户提到 RAG、飞书/Lark、Dify、Notion、入门、架构 Review 或 API 文档，调整输出契约。
|
||||
2. **优先读取本地说明。** 检查根文档，以及 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md`、`.codex/`、`.agents/`、包管理文件、构建文件、env 示例、Docker 文件和模块 README。
|
||||
3. **生成 inventory。** 对目标仓库运行本 Skill 的 `scripts/project_inventory.py`。用输出作为事实基础，再人工检查关键文件。
|
||||
4. **映射上下文。** 识别限界上下文、运行模式、主要模块、路径暗示的 owner、外部系统和数据存储。使用 `CONTEXT.md` 和 `CONTEXT-MAP.md` 风格文档。
|
||||
5. **提取生成索引。** 尽可能产出可机器刷新的文档：接口、前端路由/视图、配置键、环境变量、数据库表、权限码、定时任务、队列、扩展点。
|
||||
6. **编写人类指南。** 产出入门、架构、本地运行/部署、数据模型、认证/权限、扩展、排障和术语表文档。按用户语言书写；中文用户使用 `已观察来源`、`核心事实`、`操作影响`、`未知与风险` 等标题。
|
||||
7. **为真实决策创建 ADR。** 记录当前代码已经体现的重要架构决策。不要发明未来决策，除非标为 proposed。
|
||||
8. **添加 RAG 元数据指南。** 包括切块、source-path metadata、过期策略和排除规则。
|
||||
9. **验证。** 重新运行 inventory，扫描占位符、坏链接、过期路径和无依据结论。报告已验证内容和仍不确定内容。
|
||||
|
||||
## 输出契约
|
||||
|
||||
创建或升级完整知识库时读取 `references/output-contract_zh.md`。
|
||||
|
||||
最小有用集合：
|
||||
|
||||
```text
|
||||
docs/project-knowledge/
|
||||
├── README.md
|
||||
├── CONTEXT.md
|
||||
├── CONTEXT-MAP.md
|
||||
├── 01-architecture.md
|
||||
├── 02-runtime.md
|
||||
├── 03-backend.md
|
||||
├── 04-frontend.md
|
||||
├── 05-data-and-migrations.md
|
||||
├── 06-auth-permissions.md
|
||||
├── 07-extension-guide.md
|
||||
├── 08-troubleshooting.md
|
||||
├── 09-rag-indexing.md
|
||||
├── adr/
|
||||
│ └── 0001-current-runtime-architecture.md
|
||||
└── generated/
|
||||
├── project-inventory.md
|
||||
├── backend-endpoints.md
|
||||
├── frontend-routes.md
|
||||
├── config-reference.md
|
||||
├── database-dictionary.md
|
||||
└── permission-codes.md
|
||||
```
|
||||
|
||||
只有仓库较小或用户要求轻量产物时，才缩小范围。
|
||||
|
||||
## 来源依据标准
|
||||
|
||||
- 非显然结论必须内联引用来源路径。
|
||||
- 区分 **已观察**、**推断** 和 **未知**。
|
||||
- 不要凭记忆总结生成代码、依赖或配置，必须读取。
|
||||
- 如果不稳定事实需要外部文档，浏览一手来源并附链接。
|
||||
- 保留项目专用约定。如果仓库要求追踪注释、ADR 格式或 issue ID，记录并遵守。
|
||||
|
||||
## 跨平台兼容
|
||||
|
||||
当用户询问 macOS、Windows、Linux、CI、可移植性或跨机器安装/运行时，读取 `references/compatibility_zh.md`。bundled inventory 脚本面向 Python 3.9+，只使用标准库。
|
||||
|
||||
## Inventory 脚本
|
||||
|
||||
仅在手工刷新或用户询问命令时展示。请在目标仓库运行：
|
||||
|
||||
macOS/Linux：
|
||||
|
||||
```sh
|
||||
python3 /path/to/skill/scripts/project_inventory.py --root . --out docs/project-knowledge/generated
|
||||
```
|
||||
|
||||
Windows PowerShell：
|
||||
|
||||
```powershell
|
||||
py -3 C:\path\to\skill\scripts\project_inventory.py --root . --out docs\project-knowledge\generated
|
||||
```
|
||||
|
||||
常用选项：
|
||||
|
||||
```sh
|
||||
python3 /path/to/skill/scripts/project_inventory.py --root . --out ./kb-inventory --json
|
||||
python3 /path/to/skill/scripts/project_inventory.py --root . --out docs/project-knowledge/generated --max-files 20000
|
||||
```
|
||||
|
||||
脚本只是起点，不能替代阅读核心文件。编写叙述文档前，必须检查代表性文件。
|
||||
|
||||
## 质量门禁
|
||||
|
||||
最终回复前：
|
||||
|
||||
- 用适合平台的命令列出生成文档，例如 macOS/Linux 使用 `find docs/project-knowledge -type f | sort`，PowerShell 使用 `Get-ChildItem docs/project-knowledge -Recurse -File`。
|
||||
- 执行 `rg -n "TODO|TBD|待补|unknown|your/path|foo|bar" docs/project-knowledge`。
|
||||
- 编辑后重新运行 inventory 脚本。
|
||||
- 检查顶层 README 链接是否可解析。
|
||||
- 如果用户是中文用户，扫描叙述文档中是否仍有英文结构标题，例如 `Observed Sources`、`Core Facts`、`Operational Implications`、`Unknowns/Risks`、`Architecture`、`Runtime`、`Backend`、`Frontend`、`Troubleshooting`，除代码、元数据或生成输出外应翻译。
|
||||
- 检查新人可用性：README 给出阅读顺序；运行文档说明本地/Docker/云端模式；权限文档说明菜单/按钮权限流；扩展文档说明后端 CRUD、前端页面和权限变更。
|
||||
- 使用 `git status --short` 报告变更文件。
|
||||
|
||||
如果用户要求“深度”或“落地”，不要停在单页概览。必须交付生成索引和人类指南。
|
||||
@@ -0,0 +1,4 @@
|
||||
interface:
|
||||
display_name: "项目知识库"
|
||||
short_description: "深度整理代码仓库知识库"
|
||||
default_prompt: "Use $project-knowledge-builder 为当前项目生成 docs/project-knowledge 项目知识库。"
|
||||
+65
@@ -0,0 +1,65 @@
|
||||
# Cross-Platform Compatibility
|
||||
|
||||
Use this reference when running or installing the skill on macOS, Windows, Linux, or CI.
|
||||
|
||||
## Compatibility Summary
|
||||
|
||||
| Area | macOS | Linux | Windows |
|
||||
| --- | --- | --- | --- |
|
||||
| `SKILL.md` workflow | Supported | Supported | Supported |
|
||||
| `project_inventory.py` | Supported with Python 3.9+ | Supported with Python 3.9+ | Supported with Python 3.9+ |
|
||||
| Python dependencies | Standard library only | Standard library only | Standard library only |
|
||||
| Path handling | `pathlib` | `pathlib` | `pathlib` |
|
||||
| Shell dependency | None in script | None in script | None in script |
|
||||
| Generated Markdown paths | POSIX-style relative paths | POSIX-style relative paths | POSIX-style relative paths |
|
||||
|
||||
The script intentionally emits repository-relative paths with `/` separators so generated Markdown is stable across platforms and friendlier for URLs, GitHub, and RAG metadata.
|
||||
|
||||
## Python Invocation
|
||||
|
||||
macOS and Linux usually have one of these:
|
||||
|
||||
```sh
|
||||
python3 skills/project-knowledge-builder/scripts/project_inventory.py --root . --out docs/project-knowledge/generated
|
||||
python skills/project-knowledge-builder/scripts/project_inventory.py --root . --out docs/project-knowledge/generated
|
||||
```
|
||||
|
||||
Windows PowerShell usually uses:
|
||||
|
||||
```powershell
|
||||
py -3 skills\project-knowledge-builder\scripts\project_inventory.py --root . --out docs\project-knowledge\generated
|
||||
python skills\project-knowledge-builder\scripts\project_inventory.py --root . --out docs\project-knowledge\generated
|
||||
```
|
||||
|
||||
CI should prefer an explicit Python:
|
||||
|
||||
```sh
|
||||
python -m py_compile skills/project-knowledge-builder/scripts/project_inventory.py
|
||||
python skills/project-knowledge-builder/scripts/project_inventory.py --root . --out docs/project-knowledge/generated --json
|
||||
```
|
||||
|
||||
## Command Substitutions
|
||||
|
||||
| Task | macOS/Linux | Windows PowerShell |
|
||||
| --- | --- | --- |
|
||||
| List docs | `find docs/project-knowledge -type f \| sort` | `Get-ChildItem docs/project-knowledge -Recurse -File \| Sort-Object FullName` |
|
||||
| Search placeholders | `rg -n "TODO|TBD" docs/project-knowledge` | `rg -n "TODO|TBD" docs/project-knowledge` |
|
||||
| Show git status | `git status --short` | `git status --short` |
|
||||
| Remove temp output | `rm -rf ./kb-inventory` | `Remove-Item .\kb-inventory -Recurse -Force` |
|
||||
|
||||
`rg` is preferred where available. If `rg` is not installed, use the platform search available in the environment.
|
||||
|
||||
## Avoid In Skill Examples
|
||||
|
||||
- Hard-coded `/tmp` paths when the command should work on Windows.
|
||||
- POSIX-only command chains such as `cmd1 && cmd2` in user-facing instructions when a PowerShell equivalent is needed.
|
||||
- Shell glob assumptions that behave differently between zsh, bash, PowerShell, and cmd.
|
||||
- Python code that depends on executable shebang behavior; Windows users should call `py -3 script.py`.
|
||||
|
||||
## Known Limits
|
||||
|
||||
- Java endpoint extraction is regex-based and intentionally conservative. It does not fully resolve constants, composed annotations, or inherited controller mappings.
|
||||
- SQL table extraction looks for `CREATE TABLE`; tables created dynamically or through migrations in another DSL need manual documentation.
|
||||
- Frontend route extraction scans route-like literals and view files; runtime-generated route data from APIs still requires backend menu/permission data or database export.
|
||||
- Very large repositories may need `--max-files` tuning or additional ignore directories.
|
||||
|
||||
+64
@@ -0,0 +1,64 @@
|
||||
# 跨平台兼容
|
||||
|
||||
在 macOS、Windows、Linux 或 CI 上运行或安装本 Skill 时使用本参考。
|
||||
|
||||
## 兼容性摘要
|
||||
|
||||
| 项目 | macOS | Linux | Windows |
|
||||
| --- | --- | --- | --- |
|
||||
| `SKILL.md` 工作流 | 支持 | 支持 | 支持 |
|
||||
| `project_inventory.py` | Python 3.9+ 支持 | Python 3.9+ 支持 | Python 3.9+ 支持 |
|
||||
| Python 依赖 | 仅标准库 | 仅标准库 | 仅标准库 |
|
||||
| 路径处理 | `pathlib` | `pathlib` | `pathlib` |
|
||||
| shell 依赖 | 脚本无依赖 | 脚本无依赖 | 脚本无依赖 |
|
||||
| 生成 Markdown 路径 | POSIX 风格相对路径 | POSIX 风格相对路径 | POSIX 风格相对路径 |
|
||||
|
||||
脚本故意使用带 `/` 分隔符的仓库相对路径，使生成 Markdown 在跨平台、GitHub URL 和 RAG metadata 中更稳定。
|
||||
|
||||
## Python 调用
|
||||
|
||||
macOS 和 Linux 通常使用：
|
||||
|
||||
```sh
|
||||
python3 skills/project-knowledge-builder/scripts/project_inventory.py --root . --out docs/project-knowledge/generated
|
||||
python skills/project-knowledge-builder/scripts/project_inventory.py --root . --out docs/project-knowledge/generated
|
||||
```
|
||||
|
||||
Windows PowerShell 通常使用：
|
||||
|
||||
```powershell
|
||||
py -3 skills\project-knowledge-builder\scripts\project_inventory.py --root . --out docs\project-knowledge\generated
|
||||
python skills\project-knowledge-builder\scripts\project_inventory.py --root . --out docs\project-knowledge\generated
|
||||
```
|
||||
|
||||
CI 应优先使用明确的 Python：
|
||||
|
||||
```sh
|
||||
python -m py_compile skills/project-knowledge-builder/scripts/project_inventory.py
|
||||
python skills/project-knowledge-builder/scripts/project_inventory.py --root . --out docs/project-knowledge/generated --json
|
||||
```
|
||||
|
||||
## 命令替换
|
||||
|
||||
| 任务 | macOS/Linux | Windows PowerShell |
|
||||
| --- | --- | --- |
|
||||
| 列出文档 | `find docs/project-knowledge -type f \| sort` | `Get-ChildItem docs/project-knowledge -Recurse -File \| Sort-Object FullName` |
|
||||
| 搜索占位符 | `rg -n "TODO|TBD" docs/project-knowledge` | `rg -n "TODO|TBD" docs/project-knowledge` |
|
||||
| 查看 git 状态 | `git status --short` | `git status --short` |
|
||||
| 删除临时输出 | `rm -rf ./kb-inventory` | `Remove-Item .\kb-inventory -Recurse -Force` |
|
||||
|
||||
优先使用 `rg`。如果环境中没有 `rg`，使用该平台可用的搜索工具。
|
||||
|
||||
## Skill 示例中应避免
|
||||
|
||||
- 在应支持 Windows 的命令中写死 `/tmp` 路径。
|
||||
- 在面向用户的说明中只给 POSIX 命令链，例如 `cmd1 && cmd2`，而不给 PowerShell 等价方式。
|
||||
- 假设 shell glob 在 zsh、bash、PowerShell、cmd 中行为一致。
|
||||
- 依赖 shebang 可执行行为的 Python 用法；Windows 用户应调用 `py -3 script.py`。
|
||||
|
||||
## 已知限制
|
||||
|
||||
- Java endpoint 提取基于正则，故意保持保守。它不会完整解析常量、组合注解或继承的 controller mapping。
|
||||
- SQL 表提取查找 `CREATE TABLE`；动态创建的表或其他迁移 DSL 需要人工文档化。
|
||||
- 前端路由提取会扫描 route-like 字面量和 view 文件；运行时由 API 生成的路由仍需要后端菜单/权限数据或数据库导出。
|
||||
- 超大仓库可能需要调整 `--max-files`，或增加忽略目录。
|
||||
+142
@@ -0,0 +1,142 @@
|
||||
# Project Knowledge Builder Output Contract
|
||||
|
||||
Use this reference when producing a full codebase knowledge base.
|
||||
|
||||
## Language Policy
|
||||
|
||||
Match the user's language for human-facing narrative docs. If the user writes in Chinese or asks for Chinese, write README, context, architecture, runtime, backend, frontend, data, auth/permissions, extension, troubleshooting, RAG guidance and ADRs in Chinese.
|
||||
|
||||
Keep technical anchors unchanged: source paths, commands, class names, method names, API paths, config keys, table names, permission codes, JSON keys and metadata enum values.
|
||||
|
||||
Generated indexes may remain technical and source-like. Do not hand-translate generated values if it reduces refreshability.
|
||||
|
||||
## Document Roles
|
||||
|
||||
| File | Purpose |
|
||||
| --- | --- |
|
||||
| `README.md` | Entry point, reading order, high-value links, freshness note. For Chinese output, title and usage guidance should be Chinese. |
|
||||
| `CONTEXT.md` | Domain language, business capabilities, user roles, core nouns, invariants. |
|
||||
| `CONTEXT-MAP.md` | Bounded contexts, module ownership, upstream/downstream dependencies, runtime boundaries. |
|
||||
| `01-architecture.md` | System shape, module graph, request/data/control flows, extension seams. |
|
||||
| `02-runtime.md` | Local run, build, env vars, Docker, deployment modes, process topology. Must identify local, Docker standalone and cloud modes when present. |
|
||||
| `03-backend.md` | Backend modules, entrypoints, API conventions, service/mapper/entity patterns. |
|
||||
| `04-frontend.md` | Frontend bootstrap, routing, state, API client, component/page conventions. |
|
||||
| `05-data-and-migrations.md` | Databases, migrations, schema sources, seed data, table families. |
|
||||
| `06-auth-permissions.md` | Authentication, authorization, token/session flow, permission-code lifecycle. Must explain menu/button permission flow when the repo has backend-driven menus. |
|
||||
| `07-extension-guide.md` | How to add a feature end-to-end, with source-grounded examples. Must cover backend CRUD, frontend page and permission/menu data changes when applicable. |
|
||||
| `08-troubleshooting.md` | Symptom-driven runbook with commands, files, and likely causes. |
|
||||
| `09-rag-indexing.md` | Chunking, metadata, exclusions, refresh cadence, stale-data policy. |
|
||||
| `adr/*.md` | Architecture decisions observed in the current code. |
|
||||
| `generated/*.md` | Data-derived indexes that can be regenerated. |
|
||||
|
||||
## Required Sections
|
||||
|
||||
Each narrative doc should include:
|
||||
|
||||
- **Observed Sources:** concrete files or commands used.
|
||||
- **Core Facts:** concise source-backed statements.
|
||||
- **Operational Implications:** what developers must do differently because of those facts.
|
||||
- **Unknowns/Risks:** gaps that need runtime access, DB export, product owner input, or external docs.
|
||||
|
||||
For Chinese output, use equivalent section labels:
|
||||
|
||||
- **已观察来源**
|
||||
- **核心事实**
|
||||
- **操作影响**
|
||||
- **未知与风险**
|
||||
|
||||
## Newcomer Usefulness Gate
|
||||
|
||||
Before considering the knowledge base useful for handoff, verify that a new maintainer can answer:
|
||||
|
||||
1. What is the product/project, and which directories matter first?
|
||||
2. How do I start or identify the active runtime mode?
|
||||
3. Where are backend endpoints, frontend routes/pages, config, tables and permission codes indexed?
|
||||
4. How do menu, button and backend permission checks connect?
|
||||
5. When adding a normal feature, which backend, frontend, database and permission artifacts usually change?
|
||||
|
||||
If the answer is not obvious from README plus the narrative docs, add or revise human-facing guidance before finishing. Do not solve this by making generated indexes longer.
|
||||
|
||||
## Generated Indexes
|
||||
|
||||
### `project-inventory.md`
|
||||
|
||||
Include:
|
||||
|
||||
- repository roots
|
||||
- build/package manifests
|
||||
- primary languages
|
||||
- major directories
|
||||
- scripts
|
||||
- Docker/compose files
|
||||
- env files
|
||||
- test files
|
||||
|
||||
### `backend-endpoints.md`
|
||||
|
||||
Include route method, path, class/file, approximate line, auth annotations, and notes. Do not invent full route paths when class-level and method-level mappings require Java expression resolution; show observed fragments and mark composition limitations.
|
||||
|
||||
### `frontend-routes.md`
|
||||
|
||||
Include static router files, dynamic route loaders, `src/views` index, route guard files, and external route package loaders.
|
||||
|
||||
### `config-reference.md`
|
||||
|
||||
Include env files, YAML/properties files, relevant keys, default values, and risk notes. Redact secrets.
|
||||
|
||||
### `database-dictionary.md`
|
||||
|
||||
Include SQL files, migration files, table names, table families, and whether the table is initialized, migrated, or inferred. Avoid loading huge SQL into prose; summarize and link.
|
||||
|
||||
### `permission-codes.md`
|
||||
|
||||
Include backend annotations, frontend permission helpers/usages, menu/permission SQL occurrences, and auth lifecycle notes.
|
||||
|
||||
## ADR Template
|
||||
|
||||
```markdown
|
||||
# ADR NNNN: Title
|
||||
|
||||
Date: YYYY-MM-DD
|
||||
Status: Observed
|
||||
|
||||
## Context
|
||||
|
||||
Source-backed facts that show the decision exists.
|
||||
|
||||
## Decision
|
||||
|
||||
The architecture decision embodied by the current code.
|
||||
|
||||
## Consequences
|
||||
|
||||
Benefits, tradeoffs, operational constraints, and migration risks.
|
||||
|
||||
## Sources
|
||||
|
||||
- `path/to/file`
|
||||
```
|
||||
|
||||
## RAG Metadata
|
||||
|
||||
Recommended metadata per chunk:
|
||||
|
||||
```json
|
||||
{
|
||||
"project": "name",
|
||||
"snapshot_date": "YYYY-MM-DD",
|
||||
"source_path": "path",
|
||||
"doc_type": "architecture|runtime|generated|adr|runbook",
|
||||
"domain": "backend|frontend|data|auth|deploy",
|
||||
"freshness": "manual|generated",
|
||||
"confidence": "observed|inferred|unknown"
|
||||
}
|
||||
```
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- A long essay without generated indexes.
|
||||
- “Best practice” advice unrelated to the repo.
|
||||
- Copying README marketing text as architecture documentation.
|
||||
- Claiming an endpoint, table, permission, or runtime mode exists without a source path.
|
||||
- Hiding unknowns instead of listing them.
|
||||
+135
@@ -0,0 +1,135 @@
|
||||
# 项目知识库输出契约
|
||||
|
||||
生成完整代码库知识库时使用本参考。
|
||||
|
||||
## 语言策略
|
||||
|
||||
人类阅读的叙述文档应匹配用户语言。如果用户使用中文或要求中文，README、上下文、架构、运行、后端、前端、数据、认证/权限、扩展、排障、RAG 指南和 ADR 都应使用中文。
|
||||
|
||||
技术锚点保持原样：源码路径、命令、类名、方法名、API 路径、配置键、表名、权限码、JSON key 和元数据枚举值。
|
||||
|
||||
生成索引可以保持技术化和接近源码。不要为了翻译而破坏可刷新性。
|
||||
|
||||
## 文档职责
|
||||
|
||||
| 文件 | 用途 |
|
||||
| --- | --- |
|
||||
| `README.md` | 入口、阅读顺序、高价值链接、新鲜度说明。中文输出时标题和使用说明应为中文。 |
|
||||
| `CONTEXT.md` | 领域语言、业务能力、用户角色、核心名词、不变量。 |
|
||||
| `CONTEXT-MAP.md` | 限界上下文、模块归属、上下游依赖、运行边界。 |
|
||||
| `01-architecture.md` | 系统形态、模块图、请求/数据/控制流、扩展点。 |
|
||||
| `02-runtime.md` | 本地运行、构建、环境变量、Docker、部署模式、进程拓扑。存在时必须识别本地、Docker standalone 和云端模式。 |
|
||||
| `03-backend.md` | 后端模块、入口点、API 约定、service/mapper/entity 模式。 |
|
||||
| `04-frontend.md` | 前端启动、路由、状态、API client、组件/页面约定。 |
|
||||
| `05-data-and-migrations.md` | 数据库、迁移、schema 来源、种子数据、表族。 |
|
||||
| `06-auth-permissions.md` | 认证、授权、token/session 流、权限码生命周期。仓库存在后端驱动菜单时，必须解释菜单/按钮权限流。 |
|
||||
| `07-extension-guide.md` | 如何端到端新增功能，并给出有来源依据的示例。适用时必须覆盖后端 CRUD、前端页面和权限/菜单数据变更。 |
|
||||
| `08-troubleshooting.md` | 面向症状的排障手册，包含命令、文件和可能原因。 |
|
||||
| `09-rag-indexing.md` | 切块、元数据、排除规则、刷新频率、过期数据策略。 |
|
||||
| `adr/*.md` | 当前代码已经体现的架构决策。 |
|
||||
| `generated/*.md` | 可重新生成的数据索引。 |
|
||||
|
||||
## 必要章节
|
||||
|
||||
每份叙述文档应包含：
|
||||
|
||||
- **已观察来源**：使用过的具体文件或命令。
|
||||
- **核心事实**：简洁、有来源依据的陈述。
|
||||
- **操作影响**：开发者因这些事实需要采取的不同做法。
|
||||
- **未知与风险**：需要运行权限、数据库导出、产品负责人输入或外部文档才能确认的缺口。
|
||||
|
||||
## 新人可用性门禁
|
||||
|
||||
认为知识库可交接前，确认新维护者能回答：
|
||||
|
||||
1. 这个产品/项目是什么，哪些目录最重要？
|
||||
2. 如何启动，或如何识别当前运行模式？
|
||||
3. 后端接口、前端路由/页面、配置、数据表、权限码在哪里索引？
|
||||
4. 菜单、按钮和后端权限校验如何连接？
|
||||
5. 新增普通功能时，通常会改哪些后端、前端、数据库和权限产物？
|
||||
|
||||
如果 README 加叙述文档无法明显回答这些问题，先补充或修改人类阅读指南。不要通过加长生成索引来解决。
|
||||
|
||||
## 生成索引
|
||||
|
||||
### `project-inventory.md`
|
||||
|
||||
包含：
|
||||
|
||||
- 仓库根路径
|
||||
- 构建/包管理清单
|
||||
- 主要语言
|
||||
- 主要目录
|
||||
- scripts
|
||||
- Docker/compose 文件
|
||||
- env 文件
|
||||
- 测试文件
|
||||
|
||||
### `backend-endpoints.md`
|
||||
|
||||
包含路由方法、路径、类/文件、近似行号、认证注解和备注。不要在 class-level 与 method-level mapping 需要 Java 表达式解析时编造完整路径；展示已观察片段，并标记组合限制。
|
||||
|
||||
### `frontend-routes.md`
|
||||
|
||||
包含静态路由文件、动态路由加载器、`src/views` 索引、路由守卫文件和外部路由包加载器。
|
||||
|
||||
### `config-reference.md`
|
||||
|
||||
包含 env 文件、YAML/properties 文件、相关 key、默认值和风险说明。敏感信息必须脱敏。
|
||||
|
||||
### `database-dictionary.md`
|
||||
|
||||
包含 SQL 文件、迁移文件、表名、表族，以及表是初始化、迁移还是推断得出。不要把巨大 SQL 写进正文；摘要并链接来源。
|
||||
|
||||
### `permission-codes.md`
|
||||
|
||||
包含后端注解、前端权限 helper/usage、菜单/权限 SQL 命中和认证生命周期说明。
|
||||
|
||||
## ADR 模板
|
||||
|
||||
```markdown
|
||||
# ADR NNNN: 标题
|
||||
|
||||
Date: YYYY-MM-DD
|
||||
Status: Observed
|
||||
|
||||
## Context
|
||||
|
||||
说明该决策已经存在的来源事实。
|
||||
|
||||
## Decision
|
||||
|
||||
当前代码体现的架构决策。
|
||||
|
||||
## Consequences
|
||||
|
||||
收益、取舍、操作约束和迁移风险。
|
||||
|
||||
## Sources
|
||||
|
||||
- `path/to/file`
|
||||
```
|
||||
|
||||
## RAG 元数据
|
||||
|
||||
推荐每个 chunk 使用：
|
||||
|
||||
```json
|
||||
{
|
||||
"project": "name",
|
||||
"snapshot_date": "YYYY-MM-DD",
|
||||
"source_path": "path",
|
||||
"doc_type": "architecture|runtime|generated|adr|runbook",
|
||||
"domain": "backend|frontend|data|auth|deploy",
|
||||
"freshness": "manual|generated",
|
||||
"confidence": "observed|inferred|unknown"
|
||||
}
|
||||
```
|
||||
|
||||
## 反模式
|
||||
|
||||
- 只有长篇说明，没有生成索引。
|
||||
- 写与仓库无关的“最佳实践”建议。
|
||||
- 把 README 营销文案复制成架构文档。
|
||||
- 没有来源路径就声称某接口、表、权限或运行模式存在。
|
||||
- 隐藏未知问题，而不是列出来。
|
||||
+313
@@ -0,0 +1,313 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Generate a source-grounded project inventory for knowledge-base work."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import os
|
||||
import re
|
||||
from collections import Counter, defaultdict
|
||||
from pathlib import Path
|
||||
from typing import Iterable
|
||||
|
||||
IGNORE_DIRS = {
|
||||
".git",
|
||||
".idea",
|
||||
".vscode",
|
||||
"node_modules",
|
||||
"dist",
|
||||
"build",
|
||||
"target",
|
||||
".gradle",
|
||||
".mvn/wrapper",
|
||||
"coverage",
|
||||
".next",
|
||||
".nuxt",
|
||||
"__pycache__",
|
||||
}
|
||||
|
||||
MANIFEST_NAMES = {
|
||||
"package.json",
|
||||
"pnpm-lock.yaml",
|
||||
"yarn.lock",
|
||||
"package-lock.json",
|
||||
"pom.xml",
|
||||
"build.gradle",
|
||||
"settings.gradle",
|
||||
"Cargo.toml",
|
||||
"pyproject.toml",
|
||||
"requirements.txt",
|
||||
"go.mod",
|
||||
"composer.json",
|
||||
"Gemfile",
|
||||
}
|
||||
|
||||
CONFIG_PATTERNS = (
|
||||
re.compile(r".*\.env(\..*)?$"),
|
||||
re.compile(r".*application[-\w]*\.(yml|yaml|properties)$"),
|
||||
re.compile(r".*\.(ya?ml|toml|ini|properties|conf)$"),
|
||||
)
|
||||
|
||||
HTTP_MAPPING_RE = re.compile(
|
||||
r"@(RequestMapping|GetMapping|PostMapping|PutMapping|DeleteMapping|PatchMapping)\s*(?:\((.*?)\))?"
|
||||
)
|
||||
PERMISSION_RE = re.compile(r"@(?:RequiresPermissions|RequiresRoles)\s*\((.*?)\)")
|
||||
TABLE_NAME_RE = re.compile(
|
||||
r"\bCREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?`?([A-Za-z0-9_.$-]+)`?",
|
||||
re.IGNORECASE,
|
||||
)
|
||||
VUE_ROUTE_RE = re.compile(r"\b(path|name|component)\s*:\s*['\"]([^'\"]+)['\"]")
|
||||
|
||||
|
||||
def is_ignored(path: Path, root: Path) -> bool:
|
||||
rel_parts = path.relative_to(root).parts
|
||||
for i in range(len(rel_parts)):
|
||||
joined = "/".join(rel_parts[: i + 1])
|
||||
if joined in IGNORE_DIRS or rel_parts[i] in IGNORE_DIRS:
|
||||
return True
|
||||
return False
|
||||
|
||||
|
||||
def iter_files(root: Path, max_files: int) -> Iterable[Path]:
|
||||
count = 0
|
||||
for dirpath, dirnames, filenames in os.walk(root):
|
||||
current = Path(dirpath)
|
||||
dirnames[:] = [d for d in dirnames if not is_ignored(current / d, root)]
|
||||
for name in filenames:
|
||||
path = current / name
|
||||
if is_ignored(path, root):
|
||||
continue
|
||||
count += 1
|
||||
if count > max_files:
|
||||
return
|
||||
yield path
|
||||
|
||||
|
||||
def rel(path: Path, root: Path) -> str:
|
||||
return path.relative_to(root).as_posix()
|
||||
|
||||
|
||||
def read_text(path: Path, limit: int = 400_000) -> str:
|
||||
try:
|
||||
data = path.read_bytes()
|
||||
except OSError:
|
||||
return ""
|
||||
if len(data) > limit:
|
||||
data = data[:limit]
|
||||
try:
|
||||
return data.decode("utf-8")
|
||||
except UnicodeDecodeError:
|
||||
try:
|
||||
return data.decode("utf-8", errors="ignore")
|
||||
except Exception:
|
||||
return ""
|
||||
|
||||
|
||||
def detect_config(path: Path) -> bool:
|
||||
name = path.name
|
||||
return any(pattern.fullmatch(name) for pattern in CONFIG_PATTERNS)
|
||||
|
||||
|
||||
def extract_mapping_value(raw: str | None) -> str:
|
||||
if not raw:
|
||||
return ""
|
||||
value_match = re.search(r"['\"]([^'\"]+)['\"]", raw)
|
||||
if value_match:
|
||||
return value_match.group(1)
|
||||
return raw.strip().replace("\n", " ")[:120]
|
||||
|
||||
|
||||
def scan(root: Path, max_files: int) -> dict:
|
||||
files = list(iter_files(root, max_files))
|
||||
ext_counts = Counter(path.suffix.lower() or "[none]" for path in files)
|
||||
manifests = []
|
||||
configs = []
|
||||
docker = []
|
||||
tests = []
|
||||
java_endpoints = []
|
||||
permission_codes = []
|
||||
vue_routes = []
|
||||
views = []
|
||||
sql_tables = []
|
||||
major_dirs = defaultdict(int)
|
||||
|
||||
for path in files:
|
||||
r = rel(path, root)
|
||||
parts = Path(r).parts
|
||||
if parts:
|
||||
major_dirs[parts[0]] += 1
|
||||
if path.name in MANIFEST_NAMES:
|
||||
manifests.append(r)
|
||||
lower = path.name.lower()
|
||||
if lower.startswith("dockerfile") or "docker-compose" in lower:
|
||||
docker.append(r)
|
||||
if detect_config(path):
|
||||
configs.append(r)
|
||||
if re.search(r"(^|/)(test|tests|__tests__)(/|$)", r) or re.search(r"\.(test|spec)\.[A-Za-z0-9]+$", r):
|
||||
tests.append(r)
|
||||
if "/src/views/" in r and path.suffix.lower() in {".vue", ".tsx", ".ts"}:
|
||||
views.append(r)
|
||||
|
||||
suffix = path.suffix.lower()
|
||||
if suffix not in {".java", ".ts", ".tsx", ".vue", ".js", ".jsx", ".sql", ".yml", ".yaml", ".properties"}:
|
||||
continue
|
||||
text = read_text(path)
|
||||
if not text:
|
||||
continue
|
||||
|
||||
if suffix == ".java":
|
||||
lines = text.splitlines()
|
||||
class_mapping = ""
|
||||
class_name = ""
|
||||
pending_annotations: list[tuple[int, str, str]] = []
|
||||
for idx, line in enumerate(lines, start=1):
|
||||
class_match = re.search(r"\bclass\s+([A-Za-z0-9_]+)", line)
|
||||
if class_match:
|
||||
class_name = class_match.group(1)
|
||||
for match in HTTP_MAPPING_RE.finditer(line):
|
||||
value = extract_mapping_value(match.group(2))
|
||||
annotation = match.group(1)
|
||||
pending_annotations.append((idx, annotation, value))
|
||||
if annotation == "RequestMapping" and not class_mapping and ("class " not in line):
|
||||
class_mapping = value
|
||||
if re.search(r"\b(public|private|protected)\b.*\(", line) and pending_annotations:
|
||||
method = line.strip()[:160]
|
||||
for ann_line, annotation, value in pending_annotations:
|
||||
java_endpoints.append(
|
||||
{
|
||||
"file": r,
|
||||
"line": ann_line,
|
||||
"class": class_name,
|
||||
"annotation": annotation,
|
||||
"class_mapping": class_mapping,
|
||||
"mapping": value,
|
||||
"method_signature": method,
|
||||
}
|
||||
)
|
||||
pending_annotations = []
|
||||
for perm in PERMISSION_RE.finditer(line):
|
||||
permission_codes.append({"file": r, "line": idx, "value": perm.group(1).strip()})
|
||||
|
||||
if suffix in {".ts", ".tsx", ".vue", ".js", ".jsx"}:
|
||||
for idx, line in enumerate(text.splitlines(), start=1):
|
||||
if "path:" in line or "component:" in line or "name:" in line:
|
||||
for match in VUE_ROUTE_RE.finditer(line):
|
||||
vue_routes.append({"file": r, "line": idx, "key": match.group(1), "value": match.group(2)})
|
||||
|
||||
if suffix == ".sql":
|
||||
for match in TABLE_NAME_RE.finditer(text):
|
||||
sql_tables.append({"file": r, "table": match.group(1)})
|
||||
|
||||
return {
|
||||
"root": str(root),
|
||||
"file_count": len(files),
|
||||
"extensions": dict(ext_counts.most_common(40)),
|
||||
"major_dirs": dict(sorted(major_dirs.items(), key=lambda item: (-item[1], item[0]))),
|
||||
"manifests": sorted(manifests),
|
||||
"configs": sorted(configs),
|
||||
"docker": sorted(docker),
|
||||
"tests": sorted(tests),
|
||||
"views": sorted(views),
|
||||
"java_endpoints": java_endpoints,
|
||||
"permission_codes": permission_codes,
|
||||
"vue_routes": vue_routes,
|
||||
"sql_tables": sql_tables,
|
||||
}
|
||||
|
||||
|
||||
def write_md(data: dict, out_dir: Path) -> None:
|
||||
out_dir.mkdir(parents=True, exist_ok=True)
|
||||
|
||||
def bullet(items: list[str], limit: int | None = None) -> str:
|
||||
selected = items if limit is None else items[:limit]
|
||||
if not selected:
|
||||
return "- None found\n"
|
||||
body = "".join(f"- `{item}`\n" for item in selected)
|
||||
if limit is not None and len(items) > limit:
|
||||
body += f"- ... {len(items) - limit} more\n"
|
||||
return body
|
||||
|
||||
inventory = [
|
||||
"# Project Inventory\n\n",
|
||||
f"Root: `{data['root']}`\n\n",
|
||||
f"Files scanned: {data['file_count']}\n\n",
|
||||
"## Major Directories\n\n",
|
||||
]
|
||||
inventory.extend(f"- `{name}`: {count} files\n" for name, count in data["major_dirs"].items())
|
||||
inventory.extend(["\n## Extensions\n\n"])
|
||||
inventory.extend(f"- `{name}`: {count}\n" for name, count in data["extensions"].items())
|
||||
inventory.extend(["\n## Manifests\n\n", bullet(data["manifests"])])
|
||||
inventory.extend(["\n## Config Files\n\n", bullet(data["configs"], 200)])
|
||||
inventory.extend(["\n## Docker Files\n\n", bullet(data["docker"])])
|
||||
inventory.extend(["\n## Test Files\n\n", bullet(data["tests"], 200)])
|
||||
(out_dir / "project-inventory.md").write_text("".join(inventory), encoding="utf-8")
|
||||
|
||||
endpoints = ["# Backend Endpoints\n\n"]
|
||||
if data["java_endpoints"]:
|
||||
endpoints.append("| File | Line | Class | Annotation | Class Mapping | Mapping | Method |\n")
|
||||
endpoints.append("| --- | ---: | --- | --- | --- | --- | --- |\n")
|
||||
for item in data["java_endpoints"]:
|
||||
method_signature = item["method_signature"].replace("|", "\\|")
|
||||
endpoints.append(
|
||||
f"| `{item['file']}` | {item['line']} | `{item['class']}` | `{item['annotation']}` | "
|
||||
f"`{item['class_mapping']}` | `{item['mapping']}` | `{method_signature}` |\n"
|
||||
)
|
||||
else:
|
||||
endpoints.append("No Java endpoint annotations found.\n")
|
||||
(out_dir / "backend-endpoints.md").write_text("".join(endpoints), encoding="utf-8")
|
||||
|
||||
routes = ["# Frontend Routes And Views\n\n", "## Views\n\n", bullet(data["views"], 400), "\n## Route-like Literals\n\n"]
|
||||
if data["vue_routes"]:
|
||||
routes.append("| File | Line | Key | Value |\n| --- | ---: | --- | --- |\n")
|
||||
for item in data["vue_routes"][:1000]:
|
||||
routes.append(f"| `{item['file']}` | {item['line']} | `{item['key']}` | `{item['value']}` |\n")
|
||||
if len(data["vue_routes"]) > 1000:
|
||||
routes.append(f"\nTruncated: {len(data['vue_routes']) - 1000} more route-like literals.\n")
|
||||
else:
|
||||
routes.append("No route-like literals found.\n")
|
||||
(out_dir / "frontend-routes.md").write_text("".join(routes), encoding="utf-8")
|
||||
|
||||
configs = ["# Config Reference\n\n", bullet(data["configs"], 500)]
|
||||
(out_dir / "config-reference.md").write_text("".join(configs), encoding="utf-8")
|
||||
|
||||
tables = ["# Database Dictionary\n\n"]
|
||||
if data["sql_tables"]:
|
||||
tables.append("| Table | Source |\n| --- | --- |\n")
|
||||
for item in sorted(data["sql_tables"], key=lambda x: (x["table"], x["file"])):
|
||||
tables.append(f"| `{item['table']}` | `{item['file']}` |\n")
|
||||
else:
|
||||
tables.append("No SQL CREATE TABLE statements found in scanned files.\n")
|
||||
(out_dir / "database-dictionary.md").write_text("".join(tables), encoding="utf-8")
|
||||
|
||||
perms = ["# Permission Codes\n\n"]
|
||||
if data["permission_codes"]:
|
||||
perms.append("| File | Line | Value |\n| --- | ---: | --- |\n")
|
||||
for item in data["permission_codes"]:
|
||||
permission_value = item["value"].replace("|", "\\|")
|
||||
perms.append(f"| `{item['file']}` | {item['line']} | `{permission_value}` |\n")
|
||||
else:
|
||||
perms.append("No permission annotations found.\n")
|
||||
(out_dir / "permission-codes.md").write_text("".join(perms), encoding="utf-8")
|
||||
|
||||
|
||||
def main() -> int:
|
||||
parser = argparse.ArgumentParser(description=__doc__)
|
||||
parser.add_argument("--root", default=".", help="Repository root to scan")
|
||||
parser.add_argument("--out", required=True, help="Output directory for generated Markdown")
|
||||
parser.add_argument("--json", action="store_true", help="Also write inventory.json")
|
||||
parser.add_argument("--max-files", type=int, default=30000, help="Maximum files to scan")
|
||||
args = parser.parse_args()
|
||||
|
||||
root = Path(args.root).resolve()
|
||||
out_dir = Path(args.out).resolve()
|
||||
data = scan(root, args.max_files)
|
||||
write_md(data, out_dir)
|
||||
if args.json:
|
||||
(out_dir / "inventory.json").write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")
|
||||
print(f"Wrote project inventory to {out_dir}")
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
| 检查项 | 通过标准 | 结果 |
|
||||
| --- | --- | --- |
|
||||
| 创建记录 | 创建工单后能查询审计记录 | |
|
||||
| 创建记录 | 创建业务对象后能查询审计记录 | |
|
||||
| 字段变更 | 编辑关键字段记录 oldValue/newValue | |
|
||||
| 指派记录 | 指派负责人记录原负责人和新负责人 | |
|
||||
| 状态记录 | 状态流转记录原状态和新状态 | |
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
| 异常态 | 必须验证 | 结果 |
|
||||
| --- | --- | --- |
|
||||
| 空列表 | 页面显示空状态，不报错 | |
|
||||
| 详情不存在 | 提示工单不存在，页面不崩溃 | |
|
||||
| 详情不存在 | 提示业务对象不存在，页面不崩溃 | |
|
||||
| 权限不足 | 前端提示或隐藏，后端拒绝 | |
|
||||
| 非法状态 | 返回非法流转，状态不变 | |
|
||||
| 重复提交 | 只成功一次，只写一条有效审计 | |
|
||||
|
||||
@@ -2,10 +2,10 @@
|
||||
|
||||
| 检查项 | 通过标准 | 结果 |
|
||||
| --- | --- | --- |
|
||||
| 菜单权限 | 工单菜单只对授权角色可见 | |
|
||||
| 菜单权限 | 业务对象菜单只对授权角色可见 | |
|
||||
| 按钮权限 | 新增、编辑、删除、指派、状态按钮按权限显示 | |
|
||||
| 接口权限 | 无权限账号直接请求敏感接口失败 | |
|
||||
| 数据权限 | 普通用户只能看到授权范围内工单 | |
|
||||
| 数据权限 | 普通用户只能看到授权范围内业务对象 | |
|
||||
| 权限字符 | 前端按钮、菜单配置、后端接口命名一致 | |
|
||||
| 审计 | 权限敏感操作成功后有审计记录 | |
|
||||
| 反例验证 | 无权限账号不能绕过前端执行删除/指派 | |
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
| --- | --- | --- | --- |
|
||||
| 默认查询 | 管理员默认条件 | 返回完整指标 | |
|
||||
| 时间过滤 | 指定 start/end | 只统计时间范围内数据 | |
|
||||
| 类型过滤 | 指定工单类型 | 只统计对应类型 | |
|
||||
| 类型过滤 | 指定业务对象类型 | 只统计对应类型 | |
|
||||
| 空数据 | 无匹配条件 | 返回 0 或空集合 | |
|
||||
| 无权限 | 未授权账号 | 返回 403 或业务拒绝 | |
|
||||
| 数据范围 | 普通角色 | 只返回授权范围 | |
|
||||
|
||||
+2
-2
@@ -1,7 +1,7 @@
|
||||
# 阶段 Review Prompt
|
||||
# 阶段 Review 任务上下文契约
|
||||
|
||||
```text
|
||||
请对 JeecgBoot 工单模块阶段交付物做 Review。
|
||||
请对 目标业务模块阶段交付物做 Review。
|
||||
|
||||
输入材料：
|
||||
- RBAC 权限矩阵
|
||||
|
||||
+1
-1
@@ -15,7 +15,7 @@
|
||||
|
||||
| 等级 | 模块 | 问题 | 触发规则 | 风险 | 修复建议 | 验收 |
|
||||
| --- | --- | --- | --- | --- | --- | --- |
|
||||
| P1 | 权限 | 删除接口只隐藏按钮，后端缺少权限校验 | 前端按钮不是安全边界 | 可绕过前端删除工单 | 后端补权限校验 | 无权限账号请求返回 403 |
|
||||
| P1 | 权限 | 删除接口只隐藏按钮，后端缺少权限校验 | 前端按钮不是安全边界 | 可绕过前端删除业务对象 | 后端补权限校验 | 无权限账号请求返回 403 |
|
||||
|
||||
## 不确定点
|
||||
|
||||
|
||||
@@ -1,71 +1,35 @@
|
||||
# 验收清单
|
||||
# 业务交付验收清单
|
||||
|
||||
本清单用于判断学员是否真正掌握 JeecgBoot 工单案例，而不是只复制了 TRAE 输出。建议讲师在小组展示时逐项打分。
|
||||
本清单用于审查一个业务模块的设计、代码或 PR 是否具备可交付证据。它不替代目标项目的实际规则、接口规范或测试要求。
|
||||
|
||||
## 项目理解
|
||||
|
||||
| 检查项 | 通过标准 | 结果 |
|
||||
| --- | --- | --- |
|
||||
| 能说明 JeecgBoot 前后端目录 | 至少指出 `jeecg-boot`、`jeecgboot-vue3`、`docs/project-knowledge` 的用途 | |
|
||||
| 能定位后端入口 | 能指出 `JeecgSystemApplication.java` 和后端启动模块 | |
|
||||
| 能定位前端入口 | 能指出 `src/main.ts`、路由、Pinia 和 API 请求层 | |
|
||||
| 能区分事实和推断 | 对没有源码依据的业务规则标注为推断或待确认 | |
|
||||
| 能记录不确定点 | 不确定内容没有被包装成确定事实 | |
|
||||
|---|---|---|
|
||||
| 模块边界明确 | 已定位前后端入口、接口、数据模型和必要配置 | |
|
||||
| 事实与推断分开 | 每个非显然结论能够回到源码、日志、配置或规范 | |
|
||||
| 待确认项明确 | 无证据内容没有被包装成确定事实 | |
|
||||
|
||||
## 需求与接口
|
||||
## 改动边界
|
||||
|
||||
| 检查项 | 通过标准 | 结果 |
|
||||
| --- | --- | --- |
|
||||
| 用户故事完整 | 覆盖管理员、负责人、研发、测试、只读用户 | |
|
||||
| 非目标范围明确 | 明确课堂不做完整编码、生产部署、真实数据迁移 | |
|
||||
| 接口契约完整 | 覆盖列表、详情、新增、编辑、指派、状态、审计、看板 | |
|
||||
| 失败场景明确 | 每个关键接口至少有权限、参数、状态或数据不存在失败场景 | |
|
||||
| 验收方式明确 | 每个关键需求都有可执行检查方法 | |
|
||||
|---|---|---|
|
||||
| 目标与非目标明确 | 说明本次解决的问题及明确不修改的相邻范围 | |
|
||||
| 关键风险已识别 | 权限、状态、审计、异常、数据范围和兼容性按需核对 | |
|
||||
| 最小改动可解释 | 关键规则有权威入口，未引入无关重构 | |
|
||||
|
||||
## 权限与状态
|
||||
## 验证与交付
|
||||
|
||||
| 检查项 | 通过标准 | 结果 |
|
||||
| --- | --- | --- |
|
||||
| 权限矩阵完整 | 覆盖页面级、按钮级、接口级和数据范围 | |
|
||||
| 权限字符合理 | 命名统一，并标注为建议而非源码事实 | |
|
||||
| 后端权限未缺失 | 没有用前端按钮隐藏替代后端接口控制 | |
|
||||
| 状态流转表完整 | 覆盖新建、处理中、待验证、已关闭、已驳回 | |
|
||||
| 非法流转明确 | 至少列出 5 条非法流转和拒绝原因 | |
|
||||
|---|---|---|
|
||||
| 验证覆盖匹配风险 | 正常、异常、权限、状态与边界场景按实际风险设计 | |
|
||||
| 执行结果如实记录 | 已执行命令、CI、日志或人工观察可复核；未执行项明确列出 | |
|
||||
| PR 或变更说明完整 | 包含目标、实现范围、验证证据和已知边界 | |
|
||||
| 资产沉淀有依据 | 仅将可复用且已验证的判断沉淀为 Rule、任务上下文契约、检查单、Skill 或 MCP 契约 | |
|
||||
|
||||
## 审计、异常态与看板
|
||||
|
||||
| 检查项 | 通过标准 | 结果 |
|
||||
| --- | --- | --- |
|
||||
| 审计操作覆盖关键动作 | 创建、编辑、指派、状态流转、关闭、评论至少覆盖 5 类 | |
|
||||
| 审计字段可追溯 | 包含 actor、action、targetId、oldValue、newValue、source | |
|
||||
| 敏感信息处理 | oldValue/newValue 有脱敏说明 | |
|
||||
| 异常态可测试 | 权限不足、重复提交、非法状态、数据不存在、并发修改均覆盖 | |
|
||||
| 看板指标可计算 | 每个指标有口径、维度、过滤条件和数据来源建议 | |
|
||||
|
||||
## Review 与交付
|
||||
|
||||
| 检查项 | 通过标准 | 结果 |
|
||||
| --- | --- | --- |
|
||||
| Review 有证据 | 问题能回到路径、表格或业务规则 | |
|
||||
| 风险按严重程度排序 | 高风险问题优先展示 | |
|
||||
| 建议可行动 | 每条建议有修复方向和验收方式 | |
|
||||
| 交付物齐全 | [worksheets.md](./worksheets.md) 中最终交付记录完整 | |
|
||||
| 能沉淀资产 | 能说明哪些内容进入 [assets-index.md](./assets-index.md) 的资产库 | |
|
||||
|
||||
## 评分建议
|
||||
|
||||
| 等级 | 分数 | 描述 |
|
||||
| --- | ---: | --- |
|
||||
| A | 90-100 | 依据充分，设计完整，风险清楚，验收可执行 |
|
||||
| B | 75-89 | 主链路完整，少量不确定点或验收细节不足 |
|
||||
| C | 60-74 | 有基本产出，但权限、状态、审计或异常态明显薄弱 |
|
||||
| D | 0-59 | 泛泛总结项目，缺少源码依据或无法验收 |
|
||||
|
||||
## 讲师判定原则
|
||||
|
||||
- 优先看证据，不优先看文字是否漂亮。
|
||||
- 优先看权限、状态、审计、异常态，不只看 CRUD。
|
||||
- 优先看不确定点是否被诚实标出。
|
||||
- 优先看能否复用到团队资产库。
|
||||
- 对没有依据的自信结论扣分。
|
||||
## 判定原则
|
||||
|
||||
- 优先审查证据与边界，不以篇幅或术语数量判断质量。
|
||||
- 前端隐藏或必填不能替代后端权限和业务状态保护。
|
||||
- 局部测试、CI 通过和源码阅读分别只支撑相应范围的结论。
|
||||
- 发生资产变更时，补充行为、引用、兼容性和夹具验证证据。
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# 修复记录生成 Prompt
|
||||
# 修复记录生成 任务上下文契约
|
||||
|
||||
```text
|
||||
请根据阶段 Review 报告生成修复记录。
|
||||
|
||||
@@ -2,13 +2,13 @@
|
||||
|
||||
## 场景
|
||||
|
||||
工单指派负责人成功，但没有记录审计日志。
|
||||
业务对象指派负责人成功，但没有记录审计日志。
|
||||
|
||||
## 问题表现
|
||||
|
||||
| 操作 | 结果 |
|
||||
| --- | --- |
|
||||
| 张三将工单指派给李四 | 工单负责人变更成功 |
|
||||
| 张三将业务对象指派给李四 | 业务对象负责人变更成功 |
|
||||
| 查询审计日志 | 没有负责人变更记录 |
|
||||
|
||||
## 风险
|
||||
@@ -28,5 +28,5 @@
|
||||
| --- | --- |
|
||||
| 指派成功 | 审计列表出现 ASSIGN 记录 |
|
||||
| 指派失败 | 不出现成功审计 |
|
||||
| 查询详情 | 审计记录可在工单详情查看 |
|
||||
| 查询详情 | 审计记录可在业务对象详情查看 |
|
||||
|
||||
|
||||
@@ -2,19 +2,19 @@
|
||||
|
||||
## 场景
|
||||
|
||||
工单删除按钮在前端按权限隐藏，但后端删除接口没有权限校验。
|
||||
业务对象删除按钮在前端按权限隐藏，但后端删除接口没有权限校验。
|
||||
|
||||
## 问题代码表现
|
||||
|
||||
| 层级 | 表现 |
|
||||
| --- | --- |
|
||||
| 前端 | 普通研发账号看不到删除按钮 |
|
||||
| 后端 | 直接请求 `/workOrder/delete` 仍可删除 |
|
||||
| 后端 | 直接请求 `/<module>/delete` 仍可删除 |
|
||||
| 审计 | 删除记录可能缺失 |
|
||||
|
||||
## 风险
|
||||
|
||||
攻击者或误操作用户可以绕过前端直接调用接口删除工单。
|
||||
攻击者或误操作用户可以绕过前端直接调用接口删除业务对象。
|
||||
|
||||
## 修复要求
|
||||
|
||||
@@ -27,7 +27,7 @@
|
||||
|
||||
| 账号 | 操作 | 预期 |
|
||||
| --- | --- | --- |
|
||||
| 管理员 | 删除允许删除的工单 | 成功并写审计 |
|
||||
| 管理员 | 删除允许删除的业务对象 | 成功并写审计 |
|
||||
| 普通研发 | 直接请求删除接口 | 失败 |
|
||||
| 只读用户 | 前端访问删除按钮 | 不可见 |
|
||||
|
||||
|
||||
@@ -8,7 +8,7 @@
|
||||
|
||||
| 指标 | 当前说明 |
|
||||
| --- | --- |
|
||||
| 平均关闭周期 | 最近工单平均处理时间 |
|
||||
| 平均关闭周期 | 最近业务对象平均处理时间 |
|
||||
|
||||
## 风险
|
||||
|
||||
@@ -17,7 +17,7 @@
|
||||
## 修复要求
|
||||
|
||||
1. 明确定义为 `close_time - create_time` 或其他确定口径。
|
||||
2. 明确是否排除未关闭工单。
|
||||
2. 明确是否排除未关闭业务对象。
|
||||
3. 明确时间范围过滤字段。
|
||||
4. 用样例数据手工校验。
|
||||
|
||||
@@ -25,7 +25,7 @@
|
||||
|
||||
| 样例 | 预期 |
|
||||
| --- | --- |
|
||||
| 工单 A 创建 1 日、关闭 3 日 | 周期 2 天 |
|
||||
| 未关闭工单 | 不计入平均关闭周期 |
|
||||
| 业务对象 A 创建 1 日、关闭 3 日 | 周期 2 天 |
|
||||
| 未关闭业务对象 | 不计入平均关闭周期 |
|
||||
| 过滤 7 月 | 只统计 7 月范围内符合口径的数据 |
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
## 场景
|
||||
|
||||
已关闭工单可以直接被改回处理中。
|
||||
已关闭业务对象可以直接被改回处理中。
|
||||
|
||||
## 问题表现
|
||||
|
||||
@@ -12,12 +12,12 @@
|
||||
|
||||
## 风险
|
||||
|
||||
已关闭工单被重新打开但没有重开原因、没有审计、没有负责人确认，导致统计和责任链失真。
|
||||
已关闭业务对象被重新打开但没有重开原因、没有审计、没有负责人确认，导致统计和责任链失真。
|
||||
|
||||
## 修复要求
|
||||
|
||||
1. Service 层集中校验状态流转。
|
||||
2. 已关闭工单只能通过“重新打开”动作变为新建。
|
||||
2. 已关闭业务对象只能通过“重新打开”动作变为新建。
|
||||
3. 重新打开必须填写原因。
|
||||
4. 所有成功流转写审计日志。
|
||||
|
||||
|
||||
@@ -0,0 +1,42 @@
|
||||
# 正式交付清单
|
||||
|
||||
## 版本信息
|
||||
|
||||
- 交付名称：客户 AI 工程资产交付包
|
||||
- 版本：V1.0
|
||||
- 整理日期：2026-08-06
|
||||
- 正式载体：本目录与同级 `客户AI工程Skill交付包.zip`
|
||||
|
||||
目录与 ZIP 内容一致；对外发送时任选一种载体即可，不应混用历史压缩包或旧目录。
|
||||
|
||||
## 正式交付范围
|
||||
|
||||
| 类别 | 内容 | 用途 |
|
||||
|---|---|---|
|
||||
| 项目约束 | `generate-project-constraints` | 从目标项目提取可验证的开发约束 |
|
||||
| 项目知识 | `project-knowledge-builder` | 建立源码依据的项目知识库与索引 |
|
||||
| 复杂业务设计 | `design-complex-business-module` | 设计权限、状态、审计、异常态和指标 |
|
||||
| 交付审查 | `review-business-delivery` | 审查设计、代码或 PR 的风险与验证缺口 |
|
||||
| 修复闭环 | `track-review-fix-loop` | 跟踪 Review 问题、修复、验证与资产更新 |
|
||||
| MCP 资产 | `mcp-assets/` | 描述外部能力、权限、副作用、失败降级和验收夹具 |
|
||||
| 实战案例 | `examples/jeecgboot-official-vehicle/` | 基于现有公务用车模块的单人影响分析与验证案例 |
|
||||
|
||||
## 使用边界
|
||||
|
||||
- 五个 Skill 与 MCP 资产均为通用工程资产；业务对象、路径、接口、权限码、状态和测试命令必须从目标项目重新取得。
|
||||
- 公务用车案例只保留已经读取和验证的事实，用于说明方法，不构成任何客户业务要求。
|
||||
- MCP 目录不包含服务地址、凭据、内部域名或真实数据。接入时必须先完成能力契约、权限审查和验证夹具。
|
||||
- 本包不包含客户源码、训练分支、构建产物、在线考试题或讲师逐字稿；这些材料按其使用场景独立管理。
|
||||
|
||||
## 交付前核验项
|
||||
|
||||
- [x] 五个 Skill 目录均包含 `SKILL.md`，并保留各自的 assets、references、scripts 或 agents 文件。
|
||||
- [x] `mcp-assets/` 包含能力契约模板、权限与验收清单及使用说明。
|
||||
- [x] 扫描确认未携带历史案例、多人协作要求、默认账号或系统元数据文件。
|
||||
- [x] 压缩包可完整解压，且内容与本目录一致。
|
||||
|
||||
## 交付后的首次动作
|
||||
|
||||
1. 阅读 `README.md` 与 `安装说明.md`，确认目标 AI 编程工具的 Skill 加载方式。
|
||||
2. 在目标项目先运行项目约束提取与项目知识构建，再选择复杂业务设计或 Review 类 Skill。
|
||||
3. MCP 接入前填写能力契约，未完成权限和夹具验证时不得给 Agent 授权高风险工具。
|
||||
@@ -1,63 +1,56 @@
|
||||
# 安装说明
|
||||
|
||||
## 方式一：安装到 TRAE Skills 目录
|
||||
## 使用前确认
|
||||
|
||||
把 `skills/` 下的 4 个 Skill 文件夹复制到本机 Skills 目录：
|
||||
本包不携带外部系统地址、账号、令牌或客户数据。请先在目标项目中确认 AI 工具的 Skill 加载方式、项目规则位置和访问权限，再决定安装范围。
|
||||
|
||||
```text
|
||||
~/.trae/skills/
|
||||
```
|
||||
## 方式一：作为本地 Skill 目录使用
|
||||
|
||||
安装后目录应类似：
|
||||
将 `skills/` 下需要启用的完整文件夹复制到当前 AI 编程工具配置的本地 Skill 目录。不同版本和不同工具的目录规则可能不同，应以当前客户端实际配置为准。
|
||||
|
||||
```text
|
||||
~/.trae/skills/
|
||||
├── generate-project-constraints/
|
||||
├── design-complex-business-module/
|
||||
├── review-business-delivery/
|
||||
└── track-review-fix-loop/
|
||||
```
|
||||
|
||||
每个 Skill 文件夹必须保留完整结构：
|
||||
每个 Skill 必须保留原始目录结构：
|
||||
|
||||
```text
|
||||
skill-name/
|
||||
├── SKILL.md
|
||||
├── agents/
|
||||
│ └── openai.yaml
|
||||
└── assets/
|
||||
├── assets/ # 部分 Skill 提供
|
||||
├── references/ # 部分 Skill 提供
|
||||
└── scripts/ # 部分 Skill 提供
|
||||
```
|
||||
|
||||
## 调用方式
|
||||
推荐启用顺序：
|
||||
|
||||
在支持 Skill 的 AI 编程工具中，可以这样调用：
|
||||
|
||||
```text
|
||||
Use $generate-project-constraints 为当前项目生成 AI 开发约束。
|
||||
Use $design-complex-business-module 设计这个业务模块的权限、状态、审计、异常态和看板。
|
||||
Use $review-business-delivery Review 这批阶段交付物。
|
||||
Use $track-review-fix-loop 根据 Review 报告生成修复闭环记录。
|
||||
```
|
||||
1. `generate-project-constraints`：先获取项目约束。
|
||||
2. `project-knowledge-builder`：建立项目地图和可检索知识。
|
||||
3. `design-complex-business-module`：设计权限、状态、审计等高风险边界。
|
||||
4. `review-business-delivery`：审查设计、代码或 PR。
|
||||
5. `track-review-fix-loop`：跟踪修复、验证与资产更新。
|
||||
|
||||
## 方式二：作为团队资产库使用
|
||||
|
||||
如果当前 AI 工具暂不支持原生 Skill 机制，可以把本包作为团队资产库使用：
|
||||
如果当前工具不支持原生 Skill 发现，可将本包纳入团队资产库。保留目录结构，并让任务上下文契约或 Agent 明确引用对应文件。
|
||||
|
||||
```text
|
||||
ai-engineering-assets/
|
||||
├── skills/
|
||||
├── rules/
|
||||
├── prompts/
|
||||
├── templates/
|
||||
├── checklists/
|
||||
├── mcp-assets/
|
||||
└── examples/
|
||||
```
|
||||
|
||||
此时 `SKILL.md` 作为标准工作流说明，`assets/` 作为可复制模板、Prompt、检查清单和反例库。
|
||||
其中 `SKILL.md` 负责输入、工作流、输出契约和停止条件；`assets/` 存放模板、任务上下文契约、检查单和反例；`mcp-assets/` 负责外部能力的契约、权限与验收边界。
|
||||
|
||||
## 维护建议
|
||||
## MCP 资产的使用
|
||||
|
||||
- 每次项目规则变化后，重新运行 `generate-project-constraints`。
|
||||
- 每次复杂业务模块交付后，把高频问题沉淀到 `review-business-delivery` 或 `track-review-fix-loop` 的 assets。
|
||||
- 不要把某个项目的专用规则直接复制成通用规则。
|
||||
- 对无法从源码或配置证明的内容，统一标记为待确认。
|
||||
1. 使用 `mcp-assets/MCP能力契约.template.md` 描述每项待接入能力。
|
||||
2. 使用 `mcp-assets/MCP工具权限与验收清单.md` 审查数据范围、权限、副作用和故障降级。
|
||||
3. 为完整请求、缺参、越权、超时和敏感字段准备验证夹具。
|
||||
4. 只有契约与验证完整后，才把工具授权给对应 Agent。
|
||||
|
||||
## 维护要求
|
||||
|
||||
- 项目规则、框架、接口、权限或测试基座变化后，重新取证并更新相关资产。
|
||||
- 不要将示例中的业务对象、路径、字段、接口、状态或验证结论复制到其他项目。
|
||||
- 资产变更需要说明行为变化、兼容边界、迁移方式、回退条件和验证证据。
|
||||
- 对无法证明的内容保留为待确认，不以经验或模型建议替代事实。
|
||||
|
||||
Reference in New Issue
Block a user