🔧 chore(playbook): align repo with latest workflow

sync playbook-managed rules and prompts. migrate memory-bank to the new structure and move plans to docs/superpowers/plans. keep product README files untouched.
2026-05-24 13:34:07 +08:00
parent 696920df73
commit 7838f3ec3d
27 changed files with 1063 additions and 901 deletions
@@ -1,104 +1,87 @@
 # AGENT_RULES.local

-目的：记录 tsl-devkit 项目私有规则，优先级高于 `AGENT_RULES.md`。
+目的：记录 tsl-devkit 项目私有约束，只补充 `AGENT_RULES.md`
+与 `.agents/` 没有覆盖的仓库事实。

-## 架构参考
+## 进入任务前

-理解项目结构前，必须阅读 `memory-bank/architecture.md`，重点关注：
+- 先读 `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` 不在本任务范围内

- Core / Manager / Provider / Language / Bridge 分层边界
- LSP 请求从 `Dispatcher` 到 Provider 的调用链
- Tree-sitter + AST + Semantic 的分析链路
- C++23 Modules 与构建约束
+## 架构边界

-涉及协议与能力面时，还需同步阅读：
+- LSP 对外兼容性优先：`method` 字符串、JSON 字段名、响应结构
+  不得无依据改动
+- `core/` 负责协议入口、生命周期与路由；
+  具体能力实现放在 `provider/`
+- `provider/` 负责把 LSP 请求编排到项目能力，
+  共享状态统一通过 `manager/` 获取
+- `language/` 承载 AST、语义、符号分析；
+  `bridge/` 只封装第三方库，不放业务规则
+- 新增能力优先沿现有分层扩展，不跨层直接耦合

- `memory-bank/project-brief.md`
- `memory-bank/tech-stack.md`
+## Tree-sitter / AST 同步规则

-## 代码/架构约束
+新增或修改语法、解析、AST 链路时：

- 禁止无需求变更 LSP 协议对外行为：`method` 字符串、协议字段命名、响应结构保持兼容
- 禁止破坏现有分层：Provider 不直接承载 Manager/Language 的底层实现细节
- 换行符必须遵循 `.gitattributes` 规则，以该文件中的配置为准
- 禁止提交构建产物和临时文件：`lsp-server/build/**`、运行日志、临时脚本输出
- `docs/standards/playbook/` 为 vendored 快照；更新优先使用 subtree + 同步脚本，不做无依据手改
+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 层 / 语义层

-## Tree-sitter / AST 变更规则
+## 构建与验证

-新增或修改语法/解析链路时：
+默认 Linux 构建目录：`lsp-server/build/clang-linux/Release`

-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
 ```

-常用目标编译：
+- 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`

-```bash
-cmake --build lsp-server/build/clang-linux/Release --target tsl-server
-cmake --build lsp-server/build/clang-linux/Release --target test_ast
-```
+## Playbook 对齐规则

-## Git 提交规则
+- `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 细节写入产品介绍文档

- 提交首行必须使用 `: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列表>` 规范记录并继续主循环
+- 该仓库常位于 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-03-05
+**最后更新**：2026-05-24