105 lines
4.3 KiB
Markdown
105 lines
4.3 KiB
Markdown
# AGENT_RULES.local
|
||
|
||
目的：记录 tsl-devkit 项目私有规则，优先级高于 `AGENT_RULES.md`。
|
||
|
||
## 架构参考
|
||
|
||
理解项目结构前，必须阅读 `memory-bank/architecture.md`，重点关注：
|
||
|
||
- Core / Manager / Provider / Language / Bridge 分层边界
|
||
- LSP 请求从 `Dispatcher` 到 Provider 的调用链
|
||
- Tree-sitter + AST + Semantic 的分析链路
|
||
- C++23 Modules 与构建约束
|
||
|
||
涉及协议与能力面时，还需同步阅读：
|
||
|
||
- `memory-bank/project-brief.md`
|
||
- `memory-bank/tech-stack.md`
|
||
|
||
## 代码/架构约束
|
||
|
||
- 禁止无需求变更 LSP 协议对外行为：`method` 字符串、协议字段命名、响应结构保持兼容
|
||
- 禁止破坏现有分层：Provider 不直接承载 Manager/Language 的底层实现细节
|
||
- 换行符必须遵循 `.gitattributes` 规则，以该文件中的配置为准
|
||
- 禁止提交构建产物和临时文件：`lsp-server/build/**`、运行日志、临时脚本输出
|
||
- `docs/standards/playbook/` 为 vendored 快照；更新优先使用 subtree + 同步脚本，不做无依据手改
|
||
|
||
## Tree-sitter / AST 变更规则
|
||
|
||
新增或修改语法/解析链路时：
|
||
|
||
1. 优先修改语法源和解析逻辑（如 `grammar.js`、AST 反序列化逻辑）
|
||
2. `lsp-server/src/tree-sitter/` 与 `lsp-server/test/test_tree_sitter/src/` 下同名 parser/scanner 文件必须保持一致
|
||
3. 修改 AST 节点结构时，同步更新 `types/deserializer/debug_printer/test` 路径
|
||
4. 对行为变更补最小复现测试（优先 `test_ast --self-test` 或对应目录单测）
|
||
5. 汇报中必须写清“语法层问题 / AST 层问题 / 语义层问题”归因
|
||
|
||
## 项目特有提示词
|
||
|
||
执行以下任务时必须先读取对应提示词：
|
||
|
||
| 任务类型 | 提示词路径 |
|
||
| --- | --- |
|
||
| 需求澄清 | `docs/prompts/coding/clarify.md` |
|
||
| 代码复盘/评审总结 | `docs/prompts/coding/review.md` |
|
||
| 代理行为/工作模式 | `docs/prompts/system/agent-behavior.md` |
|
||
| 生成新提示词 | `docs/prompts/meta/prompt-generator.md` |
|
||
|
||
## 测试与验证规则
|
||
|
||
- 执行测试前，若构建目录不可用，先按“标准构建命令”完成依赖安装与编译
|
||
- AST/解析改动至少执行：
|
||
- `ctest --test-dir lsp-server/build/clang-linux/Release -R test_ast_unit --output-on-failure`
|
||
- `ctest --test-dir lsp-server/build/clang-linux/Release -R test_ast_script --output-on-failure`
|
||
- Provider/协议改动至少执行：
|
||
- `ctest --test-dir lsp-server/build/clang-linux/Release -R test_provider --output-on-failure`
|
||
- `ctest --test-dir lsp-server/build/clang-linux/Release -R test_lsp_json --output-on-failure`
|
||
- 语义/符号改动至少执行：
|
||
- `ctest --test-dir lsp-server/build/clang-linux/Release -R test_semantic --output-on-failure`
|
||
- `ctest --test-dir lsp-server/build/clang-linux/Release -R test_symbol --output-on-failure`
|
||
- 若存在已知失败项，必须在汇报中标注失败文件、最小复现结果、是否与本次改动相关
|
||
|
||
## 标准构建命令（Linux / Clang）
|
||
|
||
默认构建目录：`lsp-server/build/clang-linux/Release`
|
||
|
||
```bash
|
||
# 1) 安装依赖（Conan）
|
||
CONAN_HOME=/tmp/conan-home conan install lsp-server \
|
||
-pr:h=lsp-server/conan/profiles/linux-x86_64-clang \
|
||
-pr:b=lsp-server/conan/profiles/linux-x86_64-clang \
|
||
-of lsp-server/build/clang-linux/Release \
|
||
--build=missing
|
||
|
||
# 2) 配置（CMake + Ninja）
|
||
cmake -S lsp-server -B lsp-server/build/clang-linux/Release -G Ninja \
|
||
-DCMAKE_TOOLCHAIN_FILE=$PWD/lsp-server/build/clang-linux/Release/generators/conan_toolchain.cmake \
|
||
-DBUILD_TESTS=ON
|
||
|
||
# 3) 编译
|
||
cmake --build lsp-server/build/clang-linux/Release
|
||
```
|
||
|
||
常用目标编译：
|
||
|
||
```bash
|
||
cmake --build lsp-server/build/clang-linux/Release --target tsl-server
|
||
cmake --build lsp-server/build/clang-linux/Release --target test_ast
|
||
```
|
||
|
||
## Git 提交规则
|
||
|
||
- 提交首行必须使用 `:emoji: type(scope): subject` 格式
|
||
- `emoji` 与 `type` 映射以 `docs/standards/playbook/docs/common/commit_message.md` 为准
|
||
- `subject` 使用英文（建议现在时/祈使句，不加句号）
|
||
- 不允许中文提交标题；中文说明放在 commit body
|
||
|
||
## 紧急处理
|
||
|
||
- 构建/测试环境异常（例如 Conan 缓存、CMake 缓存、路径映射问题）优先记录可复现命令与原始报错
|
||
- 若遇到跨环境阻塞，按 `AGENT_RULES.md` 的 `blocked: env:<环境>:<Task列表>` 规范记录并继续主循环
|
||
|
||
---
|
||
|
||
**最后更新**：2026-03-05
|