feat(slidev): update 3 4
This commit is contained in:
smart
+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.
|
||||
|
||||
+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.
|
||||
Reference in New Issue
Block a user