smart/TARE-Learn
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 更新TRA编程培训课程材料、课件与AI技能交付包

Browse Source 
- 新增全套考试卷、评估卷、参考答案与考试培训包模板
- 修正slidev培训课件：调整模块标题、链路图缩放，替换工单示例为通用业务对象
- 修正课堂红线表述为证据红线，将小组作业调整为个人作业要求
- 新增权限、状态流转、审计日志、看板指标四类可复用业务规则块
- 整理AI工程技能交付包，迁移旧资产至客户专属交付包并统一术语
- 新增考试输出模板与TRAE使用记录文档
This commit is contained in:
smart
2026-08-08 11:00:36 +08:00
parent e7d6db93c3
commit 67837df8d0
169 changed files with 6618 additions and 2887 deletions
Download Patch File Download Diff File Expand all files Collapse all files
deliverables/客户AI工程Skill交付包/skills/project-knowledge-builder/references/compatibility.md
+65
View File
@@ -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.
deliverables/客户AI工程Skill交付包/skills/project-knowledge-builder/references/compatibility_zh.md
+64
View File
@@ -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`，或增加忽略目录。
deliverables/客户AI工程Skill交付包/skills/project-knowledge-builder/references/output-contract.md
+142
View File
@@ -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.
deliverables/客户AI工程Skill交付包/skills/project-knowledge-builder/references/output-contract_zh.md
+135
View File
@@ -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 营销文案复制成架构文档。
- 没有来源路径就声称某接口、表、权限或运行模式存在。
- 隐藏未知问题，而不是列出来。