Code Documentation & Navigation Guide
This skill provides a Codebase Knowledge Graph to help you navigate complex projects without reading thousands of files. It uses a local SQLite database to store file relationships, dependency layers, and symbol definitions.
⚠️ CRITICAL: BLOCKING REQUIREMENTS (触发条件)
STOP! READ THIS BEFORE PROCEEDING.
You MUST invoke this skill (code-doc-guid) as a BLOCKING STEP before performing any of the following actions. Failure to do so is a violation of protocol.
🔴 Mandatory Pre-Action Check (Recon Phase)
Trigger: You are about to:
- * Modify any code file (
Write, SearchReplace). - Rename or move files (
RunCommand: mv/ren). - Delete files (
DeleteFile). - Refactor a class, function, or variable.
Action: You MUST run python ... codebase_manager.py inspect/search FIRST.
Reason: You cannot safely modify code without knowing who depends on it. "Guessing" is strictly prohibited.
🟢 Mandatory Post-Action Sync (Archive Phase)
Trigger: You have just finished a set of file modifications.
Action: You MUST run
python ... codebase_manager.py update.
Reason: The knowledge graph must remain consistent with the disk state for the next turn.
Workflow & Commands
All commands are run via python scripts/codebase_manager.py <command> [args].
(Note: If running manually, adjust the path to where you saved the script)
1. search - Find Symbols & Concepts
Use this to locate code by name or intent (docstring).
- Command: INLINECODE9
- Example: INLINECODE10
- Output: JSONL format containing file paths, symbol names, and docstrings.
- Action: Use this to find the exact file path* before reading it.
2. inspect - Analyze Dependencies & Risk
Use this to understand the impact of a change.
- * Command: INLINECODE12
- Example: INLINECODE13
- Output (JSON):
*
risk_score:
HIGH /
MEDIUM /
LOW.
*
doc_file: Path to the detailed report (e.g.,
.trae/codeguiddoc.md).
1.
Read the JSON summary first.
2.
IF RISK IS HIGH:
*
STOP. Do not modify code yet.
*
READ the generated markdown file (
doc_file). It contains a
Mermaid Graph and full dependency list.
*
SHOW the Mermaid graph to the user (if possible) or summarize the impact: "This change affects 25 files, including core modules A and B."
*
ASK for confirmation.
3. update - Refresh Index
Use this after
ANY file modification.
- * Command: INLINECODE19
- Output: "Processing X changed files..."
- Note: It is incremental and very fast (<1s usually). Always run this before finishing your turn.
4. graph - Export Visuals (Optional)
Use this only when the user explicitly asks for an architecture overview.
- * Command: INLINECODE21
- Output: Generates
.trae/architecture_layers.md (Human readable) and .trae/dependency_graph.json (Machine readable).
Token Economy Strategy
To save tokens and time:
- 1. Don't read whole files to find one function. Use
search -> Read(limit=20, offset=N). - Don't guess dependencies. Use
inspect to see the exact relationship graph. - Trust the Layering. If you are modifying a Layer 0 file, be extremely careful—it breaks everything. If modifying Layer 5, it's likely safe.
代码文档与导航指南
本技能提供一个代码库知识图谱，帮助你在不阅读数千个文件的情况下导航复杂项目。它使用本地SQLite数据库存储文件关系、依赖层级和符号定义。
⚠️ 关键：阻塞性要求（触发条件）
停下！在继续之前请阅读此内容。
在执行以下任何操作之前，你必须将本技能（code-doc-guid）作为阻塞步骤调用。未执行此操作即违反协议。
🔴 强制性操作前检查（侦察阶段）
触发条件：你即将：
- * 修改任何代码文件（Write、SearchReplace）。
- 重命名或移动文件（RunCommand: mv/ren）。
- 删除文件（DeleteFile）。
- 重构类、函数或变量。
操作：你必须首先运行 python ... codebase_manager.py inspect/search。
原因：在不了解依赖关系的情况下修改代码是不安全的。严格禁止猜测。
🟢 强制性操作后同步（归档阶段）
触发条件：你刚刚完成了一组文件修改。
操作：你
必须运行 python ... codebase_manager.py update。
原因：知识图谱必须与磁盘状态保持一致，以便进行下一步操作。
工作流程与命令
所有命令通过 python scripts/codebase_manager.py [args] 运行。
（注意：如果手动运行，请调整为你保存脚本的路径）
1. search - 查找符号与概念
用于按名称或意图（文档字符串）定位代码。
- 命令：search
- 示例：search UserAuth
- 输出：JSONL格式，包含文件路径、符号名称和文档字符串。
- 操作：在读取文件之前，使用此命令找到确切的文件路径*。
2. inspect - 分析依赖与风险
用于了解变更的影响范围。
- * 命令：inspect fragment>
- 示例：inspect authservice
- 输出（JSON）：
* risk_score：
高 /
中 /
低。
* doc_file：详细报告的路径（例如 .trae/codeguiddoc.md）。
1. 首先
读取JSON摘要。
2.
如果风险为高：
*
停止。暂时不要修改代码。
*
读取生成的markdown文件（doc_file）。其中包含
Mermaid图和完整的依赖列表。
*
展示Mermaid图给用户（如果可能）或总结影响：此变更影响25个文件，包括核心模块A和B。
*
请求确认。
3. update - 刷新索引
在
任何文件修改后使用。
- * 命令：update
- 输出：正在处理X个变更的文件...
- 注意：此操作是增量式的，速度非常快（通常<1秒）。在结束当前操作前务必运行此命令。
4. graph - 导出可视化（可选）
仅在用户明确要求架构概览时使用。
- * 命令：graph
- 输出：生成 .trae/architecturelayers.md（人类可读）和 .trae/dependencygraph.json（机器可读）。
Token经济策略
为节省Token和时间：
- 1. 不要为了查找一个函数而读取整个文件。使用 search -> Read(limit=20, offset=N)。
- 不要猜测依赖关系。使用 inspect 查看精确的关系图。
- 信任层级结构。如果你正在修改第0层文件，务必极其小心——它会破坏一切。如果修改第5层，则相对安全。
