88 lines
3.3 KiB
Markdown
88 lines
3.3 KiB
Markdown
# AGENT_RULES.local
|
||
|
||
目的：记录 tsl-devkit 项目私有约束，只补充 `AGENT_RULES.md`
|
||
与 `.agents/` 没有覆盖的仓库事实。
|
||
|
||
## 进入任务前
|
||
|
||
- 先读 `memory-bank/project-brief.md`、
|
||
`memory-bank/tech-context.md`、
|
||
`memory-bank/system-patterns.md`
|
||
- 处理 C++ 代码前，再读 `.agents/cpp/index.md`
|
||
- 做 playbook 对齐时，只改 playbook 管理的规则与上下文文件；
|
||
`README.md`、`lsp-server/README.md`、`vscode/README.md`、
|
||
`vim/README.md` 不在本任务范围内
|
||
|
||
## 架构边界
|
||
|
||
- LSP 对外兼容性优先：`method` 字符串、JSON 字段名、响应结构
|
||
不得无依据改动
|
||
- `core/` 负责协议入口、生命周期与路由；
|
||
具体能力实现放在 `provider/`
|
||
- `provider/` 负责把 LSP 请求编排到项目能力，
|
||
共享状态统一通过 `manager/` 获取
|
||
- `language/` 承载 AST、语义、符号分析；
|
||
`bridge/` 只封装第三方库，不放业务规则
|
||
- 新增能力优先沿现有分层扩展，不跨层直接耦合
|
||
|
||
## Tree-sitter / AST 同步规则
|
||
|
||
新增或修改语法、解析、AST 链路时：
|
||
|
||
1. 先更新语法源、生成物和解析入口，再补 AST / semantic 适配
|
||
2. `lsp-server/src/tree-sitter/` 与
|
||
`lsp-server/test/test_tree_sitter/src/`
|
||
下同名 parser / scanner 文件必须同步
|
||
3. AST 节点结构变化时，同步检查 `language/ast`、
|
||
反序列化、debug printer 和对应测试
|
||
4. 汇报中明确归因：语法层 / AST 层 / 语义层
|
||
|
||
## 构建与验证
|
||
|
||
默认 Linux 构建目录：`lsp-server/build/clang-linux/Release`
|
||
|
||
- 构建前置：
|
||
|
||
```bash
|
||
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
|
||
|
||
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
|
||
```
|
||
|
||
- AST / 解析改动至少执行：
|
||
`ctest --test-dir lsp-server/build/clang-linux/Release -R 'test_ast|test_tree_sitter' --output-on-failure`
|
||
- Provider / 协议改动至少执行：
|
||
`ctest --test-dir lsp-server/build/clang-linux/Release -R 'test_provider|test_lsp_any|request_json' --output-on-failure`
|
||
- 语义 / 符号改动至少执行：
|
||
`ctest --test-dir lsp-server/build/clang-linux/Release -R 'test_semantic|test_symbol' --output-on-failure`
|
||
|
||
## Playbook 对齐规则
|
||
|
||
- `docs/standards/playbook/` 是 vendored 快照；
|
||
升级必须优先使用 `git subtree pull --prefix docs/standards/playbook ... --squash`
|
||
- subtree 更新后，统一执行
|
||
`python docs/standards/playbook/scripts/playbook.py -config playbook.toml`
|
||
同步规则、提示词和 `.agents/`
|
||
- 项目自维护文件是 `AGENT_RULES.local.md`、
|
||
`memory-bank/*.md`、`docs/superpowers/**`
|
||
- playbook 对齐不改产品 README，也不把 playbook 细节写入产品介绍文档
|
||
|
||
## 工作区注意事项
|
||
|
||
- 该仓库常位于 CIFS 共享目录，`git status`、
|
||
`git diff-index` 可能出现假脏或卡住
|
||
- 遇到索引异常时，优先使用：
|
||
`git -c core.trustctime=false -c core.checkStat=minimal ...`
|
||
- 必要时执行 `git update-index --refresh`，
|
||
或先给受影响目录补 `u+w` 权限后再做 subtree / stash / clean
|
||
|
||
---
|
||
|
||
**最后更新**：2026-05-24
|