# 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