diff --git a/.agents/cpp/index.md b/.agents/cpp/index.md index 17336e7..fbe0cec 100644 --- a/.agents/cpp/index.md +++ b/.agents/cpp/index.md @@ -43,5 +43,4 @@ ## 与开发规范的关系 -- 本仓库内：`docs/standards/playbook/docs/cpp/` 与 `docs/standards/playbook/docs/common/` -- 目标项目 subtree：`docs/standards/playbook/docs/cpp/` 与 `docs/standards/playbook/docs/common/` +- 规范文档：`docs/standards/playbook/docs/cpp/` 与 `docs/standards/playbook/docs/common/` diff --git a/.agents/index.md b/.agents/index.md index 189dbe6..4a9fc88 100644 --- a/.agents/index.md +++ b/.agents/index.md @@ -4,14 +4,18 @@ 建议约定： -- `.agents/tsl/`：TSL 相关规则集（由 `sync_standards.*` 同步；适用于 `.tsl`/`.tsf`） -- `.agents/cpp/`：C++ 相关规则集（由 `sync_standards.*` 同步；适用于 C++23/Modules） -- `.agents/python/` 等：其他语言的规则集（按需增加） +- `.agents/cpp/`：C++ 相关规则集（由 playbook 同步；适用于 C++23/Modules） +- `.agents/tsl/`：TSL 相关规则集（由 playbook 同步；适用于 `.tsl`/`.tsf`） +- `.agents/markdown/`：Markdown 相关规则集（仅代码格式化） 规则发生冲突时，建议以“更靠近代码的目录规则更具体”为准。 入口建议从： -- `.agents/tsl/index.md`（TSL 规则集入口） -- `.agents/cpp/index.md`（C++ 规则集入口） -- `docs/standards/playbook/docs/`（人类开发规范快照：`tsl/`、`cpp/`、`python/`、`common/`） +- `.agents/cpp/index.md` +- `.agents/tsl/index.md` +- `.agents/markdown/index.md` + +标准快照文档入口： + +- docs/standards/playbook/docs diff --git a/.agents/markdown/index.md b/.agents/markdown/index.md index 9603d60..fbe7ae0 100644 --- a/.agents/markdown/index.md +++ b/.agents/markdown/index.md @@ -20,6 +20,7 @@ - 优先使用 Prettier（仓库已固定配置/脚本） - 不引入新的 Markdown 格式化依赖 +- `markdownlint` 如需启用，由目标项目自行增加；不属于本规则集默认部署内容 ### 行内代码 diff --git a/.agents/tsl/index.md b/.agents/tsl/index.md index 4f9c648..ba91faa 100644 --- a/.agents/tsl/index.md +++ b/.agents/tsl/index.md @@ -28,17 +28,18 @@ ## 权威来源 -- 语法手册：`docs/standards/playbook/docs/tsl/syntax_book/index.md` -- 函数库：`docs/standards/playbook/docs/tsl/syntax_book/function/`（按需检索，禁止整份加载） +- TSL 总入口：`docs/standards/playbook/docs/tsl/index.md` +- 语法手册：`docs/standards/playbook/docs/tsl/syntax/index.md` +- 金融业务入口：`docs/standards/playbook/docs/tsl/finance/index.md` +- 模块与集成入口：`docs/standards/playbook/docs/tsl/modules/index.md` +- 函数检索入口：`docs/standards/playbook/docs/tsl/reference/index.md` - 代码风格：`docs/standards/playbook/docs/tsl/code_style.md` - 命名规范：`docs/standards/playbook/docs/tsl/naming.md` ## Skills（按需加载） -- `$tsl-guide` - `$commit-message` ## 与开发规范的关系 -- 本仓库内：`docs/standards/playbook/docs/tsl/` 与 `docs/standards/playbook/docs/common/` -- 目标项目 subtree：`docs/standards/playbook/docs/tsl/` 与 `docs/standards/playbook/docs/common/` +- 规范文档：`docs/standards/playbook/docs/tsl/` 与 `docs/standards/playbook/docs/common/` diff --git a/AGENTS.md b/AGENTS.md index 2bf42f3..26539d6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -24,19 +24,15 @@ Human-facing standards snapshot (vendored): - [AGENT_RULES.md](./AGENT_RULES.md) - 执行流程与优先级 -### 项目上下文 +### 项目状态 - [memory-bank/project-brief.md](memory-bank/project-brief.md) - 项目定位 -- [memory-bank/tech-stack.md](memory-bank/tech-stack.md) - 技术栈 -- [memory-bank/architecture.md](memory-bank/architecture.md) - 架构设计 +- [memory-bank/active-context.md](memory-bank/active-context.md) - 当前上下文 - [memory-bank/progress.md](memory-bank/progress.md) - 进度追踪 -- [memory-bank/decisions.md](memory-bank/decisions.md) - 架构决策 -### 工作流程 +### 工作流入口 -- [docs/prompts/coding/clarify.md](docs/prompts/coding/clarify.md) - 需求澄清 -- [docs/prompts/coding/review.md](docs/prompts/coding/review.md) - 复盘总结 -- [docs/prompts/system/agent-behavior.md](docs/prompts/system/agent-behavior.md) - 工作模式参考 +- [docs/prompts/README.md](docs/prompts/README.md) - 提示词与流程入口 diff --git a/AGENT_RULES.local.md b/AGENT_RULES.local.md index 2456676..faf246e 100644 --- a/AGENT_RULES.local.md +++ b/AGENT_RULES.local.md @@ -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:<环境>:` 规范记录并继续主循环 +- 该仓库常位于 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 diff --git a/AGENT_RULES.md b/AGENT_RULES.md index 4baa7c7..3f8bc6f 100644 --- a/AGENT_RULES.md +++ b/AGENT_RULES.md @@ -9,214 +9,291 @@ 3. 仓库规则：`.agents/` 与 `AGENTS.md` 4. 本文件 -## 安全红线 +## 安全与沟通 -- 不得在代码/日志/注释中写入明文密钥、密码、Token -- 修改鉴权/权限逻辑必须说明动机与风险 -- 不确定是否敏感时按敏感信息处理 -- 执行修改文件系统的命令前，必须解释目的和潜在影响 +### 安全红线 -## 行为准则 +- 不得在代码、日志或注释中写入明文密钥、密码、Token +- 修改鉴权、权限或敏感数据流时，必须说明动机与风险 +- 不确定是否敏感时，一律按敏感信息处理 +- 执行会修改文件系统的命令前，必须说明目的与潜在影响 -### 项目适应 +### 沟通原则 -- **模仿项目风格**：优先分析周围代码和配置，遵循现有约定 -- **不假设可用性**：不假设库或框架可用，先验证再使用 -- **完整完成请求**：不遗漏用户要求的任何部分 +- 统一使用简体中文 +- 专业、直接、简洁，避免对话填充词 +- 发现用户理解有误时，礼貌纠正 +- 无法满足请求时，简洁说明原因并提供替代方案 +- 不给时间估算，专注事实、风险与下一步 +- 代码块必须标注语言类型 +- 不使用 emoji，除非用户明确要求 -### 技术态度 +## 工作原则 -- **准确性优先**：技术准确性优先于迎合用户 -- **诚实纠正**：发现用户理解有误时，礼貌纠正 -- **先查后答**：不确定时先调查再回答 +- 模仿项目现有风格，先看周围代码、配置和测试再动手 +- 不假设库、框架或命令可用，先验证再使用 +- 完整覆盖用户请求，不遗漏边界条件和收尾工作 +- 技术准确性优先于迎合；不确定时先调查再回答 +- 只做当前任务需要的改动，不顺手加功能、不顺手重构 +- 不为一次性操作增加抽象，不为假设的未来需求设计 -### 避免过度工程 +## 会话启动 -- **只做要求的**：不主动添加未要求的功能或重构 -- **不过度抽象**：不为一次性操作创建工具函数 -- **不为未来设计**：不为假设的未来需求设计 +每次新会话开始时，按顺序加载以下上下文： -## 沟通原则 +1. `AGENT_RULES.local.md`：项目私有规则（如存在） +2. `.agents/index.md`：语言规则与工具入口（如存在） +3. `memory-bank/project-brief.md`：项目定位、边界、约束 +4. `memory-bank/tech-context.md`：技术上下文、工具链、验证命令 +5. `memory-bank/system-patterns.md`：系统模式、边界与不变量 +6. `memory-bank/active-context.md`：当前目标、最近变更、下一步 +7. `memory-bank/decisions.md`：重要决策记录（如存在） +8. `memory-bank/progress.md`：执行进度与 Plan 状态（如存在） +9. `docs/superpowers/specs/`：最新设计稿（如存在） +10. `docs/superpowers/plans/`：相关实施计划（如存在） -- **统一简体中文**：所有回复均使用简体中文 -- **简洁直接**：专业、直接、简洁，避免对话填充词 -- **拒绝时提供替代**：无法满足请求时，简洁说明并提供替代方案 -- **不给时间估算**：专注任务本身，让用户自己判断时间 -- **代码块标注语言**：输出代码时标注语言类型 -- **不使用 emoji**：除非用户明确要求 +目的：快速建立项目全貌，避免重复解释和重复试错。 -## 上下文加载（每次会话开始） +## 规划与执行模型 -**必读文档**（按顺序）： +- 头脑风暴使用 `$brainstorming`，产出 + `docs/superpowers/specs/*-design.md` +- 实施计划使用 `$writing-plans`，产出 + `docs/superpowers/plans/*.md` +- Plan 生命周期由 `main_loop.py` 协调，并通过 + `memory-bank/progress.md` 留痕 +- 默认执行器是 `$executing-plans` +- 代码类执行必须同时遵循： + `karpathy-guidelines`、`.agents/`、`AGENT_RULES.md` -1. `AGENT_RULES.local.md` - 项目私有规则（如存在，优先级高于本文件） -2. `.agents/index.md` - 语言规则入口（如存在） -3. `memory-bank/project-brief.md` - 项目定位、边界、约束 -4. `memory-bank/tech-stack.md` - 技术栈、工具链 -5. `memory-bank/architecture.md` - 架构设计、模块职责 -6. `memory-bank/decisions.md` - 重要决策记录（如存在） -7. `memory-bank/progress.md` - 执行进度与状态（如存在） -8. `docs/plans/` - 最新实施计划（如存在） +重要约束： -**目的**：让 AI 快速理解项目全貌，避免重复解释。 +- 规划阶段必须走 `using-superpowers -> brainstorming -> writing-plans` +- `brainstorming` 写出 spec 后，立即用 `playbook.py -record-spec` + 记录 `phase=planning` 与 `spec=` +- `writing-plans` 写出 plan 后，立即用 `playbook.py -record-plan` + 记录 `plan=`、`executor=executing-plans`、 + `constraints=karpathy-guidelines,.agents,AGENT_RULES` +- 未领取 Plan 前，不得直接进入 `$executing-plans` +- 已领取 Plan 后，默认执行使用 `$executing-plans` +- `$subagent-driven-development` 仅在 Plan 或平台明确要求时使用， + 不是默认执行器 +- 执行完成后，必须先运行 `main_loop.py finish` 写回状态， + 再更新 `progress.md` 上半部分摘要 -## 规划与执行分工 +### Plan 要求 -| 阶段 | 工具 | 产出 | 留痕 | -| ------------ | ---------------------- | ----------------- | -------------------- | -| 头脑风暴 | `$brainstorming` skill | 设计思路 | 无 | -| 生成计划 | `$writing-plans` skill | `docs/plans/*.md` | 无 | -| **执行计划** | **主循环** | 代码/配置变更 | **plan_progress.py** | +- `Plan Meta` 必填，位于 Plan 头部 `---` 之后、Task 1 之前 +- `Plan Meta` 至少包含： + - `Plan Group` + - `Parent Plan` + - `Verification Scope` + - `Verification Gate` +- Plan 中不得包含必然失败或依赖未确认的信息 +- 未确认项必须在 `$brainstorming` 阶段解决后，才能产出 Plan +- Plan 内验证必须是当前阶段可通过的局部验证 +- 需要集成验证的内容，放入上层或集成 Plan +- Plan 生成完成后，执行入口只能是主循环 +- 代码类 Plan 应显式声明执行约束： + `karpathy-guidelines`、`.agents/`、`AGENT_RULES.md` +- 不因等待确认而中断可执行步骤；待确认事项写入回复 +- 每个 Plan 应小步、可验证、可快速完成 -> **重要**：第三方 skills 不记录操作状态，执行必须通过主循环完成。 +## 主循环执行契约 -## 主循环 +### 触发方式 -**触发词**： +- 常规模式：`执行主循环`、`继续执行`、`下一个 Plan` +- 无交互模式：`自动执行所有 Plan` -| 触发词 | 模式 | 说明 | -| --------------------------------------- | ---------- | ---------------------- | -| `执行主循环`、`继续执行`、`下一个 Plan` | 常规模式 | 遇确认场景可询问用户 | -| `自动执行所有 Plan` | 无交互模式 | 不询问，按规则自动处理 | +### Plan 状态 -**Plan 状态**： +- `pending`：待执行 +- `in-progress`：执行中，用于恢复中断任务 +- `done`：已完成 +- `blocked`：阻塞，需人工介入或切换环境 +- `skipped`：永久跳过，不再执行 -| 状态 | 含义 | -| ----------- | ------------------------- | -| pending | 待执行 | -| in-progress | 执行中（崩溃恢复用） | -| done | 已完成 | -| blocked | 阻塞（需人工介入） | -| skipped | 跳过（Plan 不再需要执行） | +`skipped` 如需恢复，必须手动改回 `pending`。 -> 说明：`skipped` 仅用于永久不再执行；如需恢复执行，需手动改回 `pending`。 +### 环境阻塞格式 -**环境阻塞格式**：`blocked: env:<环境>:` +- 格式：`env:<环境>:` +- 示例：`env:windows:Task2,Task4` +- `Task` 列表必须使用英文逗号分隔，且不要包含空格 -- 示例：`blocked: env:windows:Task2,Task4` -- 含义：需要在指定环境执行列出的 Task -- 约束：`Task` 列表使用英文逗号分隔，不要包含空格，便于解析 +### 领取与写回 -**流程**： +领取命令： -1. 检测环境： - - 由 `plan_progress.py` 自动识别当前环境（`windows` / `linux` / `darwin`） -2. 选择 Plan： - - 运行 `python docs/standards/playbook/scripts/plan_progress.py select -plans docs/plans -progress memory-bank/progress.md` - - 返回第一个可执行的 Plan： - - `pending` 或 `in-progress` 的 Plan - - `blocked: env:<当前环境>:...` 的 Plan（环境匹配时恢复执行） - - 如无可执行 Plan，跳到步骤 7 - - **注意**：每次 select 会重新扫描 `docs/plans/` 目录，支持动态添加 Plan -3. 标记开始： - - 运行 `python docs/standards/playbook/scripts/plan_progress.py record -plan -status in-progress -progress memory-bank/progress.md` -4. 阅读 Plan： - - 理解目标、子任务与验证标准 - - 如果是从 `blocked: env:...` 恢复，只执行列出的 Task -5. 逐步执行： - - 按顺序执行 Task - - 每个 Task 完成后进行必要验证（测试/日志/diff） - - **Task 失败处理**： - - 环境不匹配（`command not found`、路径不存在）→ 记录该 Task 及所需环境，**继续下一个 Task** - - 其他阻塞 → 记录原因，跳到步骤 6 标记 Plan blocked - - **安全红线**（明文密钥等）→ 立即停止，不继续后续 Plan - - 遇到歧义/风险/决策点： - - 常规模式：记录到回复中，可询问用户 - - 无交互模式：按「需要确认的场景」规则自动处理 -6. 记录结果： - - 全部完成：`... -status done ...` - - 有 Task 因环境跳过：`... -status blocked ... -note "env:<所需环境>:"` - - 其他阻塞：`... -status blocked ... -note "<原因>"` - - 跳过整个 Plan：`... -status skipped ... -note "<原因>"` - - 回到步骤 2 继续下一个 Plan -7. 汇总报告（所有 Plan 处理完毕后）： - - 已完成的 Plan - - 阻塞/跳过的 Plan 及原因 - - 需要在其他环境执行的 Plan（`blocked: env:...`） - - 待确认的歧义/风险/决策点 - - 如需记录重要决策，写入 `memory-bank/decisions.md` -8. **结束**：主循环终止 +```bash +python docs/standards/playbook/scripts/main_loop.py claim \ + -plans docs/superpowers/plans \ + -progress memory-bank/progress.md +``` -## Plan 规则 +该命令会在锁保护下串行完成三件事： -- **Plan Meta 必填**：Plan 头部 `---` 之后、Task 1 之前插入 `## Plan Meta`，包含： - - `Plan Group`（归类任务） - - `Parent Plan`（上层/集成计划链接） - - `Verification Scope`（local 或 integration） - - `Verification Gate`（must-pass） -- **不允许中断任务**：Plan 中不应包含必然失败或依赖未确认的信息；未确认项必须在 `$brainstorming` 阶段解决后再产出 Plan -- **验证必须可通过**：Plan 内验证应为当前阶段可通过的局部验证；需要集成验证的内容放入上层/集成 Plan -- 不因等待确认而中断可执行步骤；待确认事项在回复中列出 -- 每轮只处理一个 Plan -- **小步快跑**：每个 Plan 应该可快速完成 -- **可验证**：每个 Plan 必须包含验证步骤 +- 自动识别当前环境：`windows`、`linux`、`darwin` +- 按顺序选择可执行 Plan： + `in-progress` > `pending` > `blocked: env:<当前环境>:...` +- 将选中的 Plan 写成 `in-progress` -## 执行约束 +这里的锁保护的是 `progress.md` 状态块更新，避免多个 session +同时读写时发生覆盖。 -### 代码修改 +stdout 必须包含： -- **必须先读文件再修改**：不读文件就提议修改是禁止的 -- **必须运行测试验证**：相关测试必须通过 -- **遵循换行规则**：遵循 `.gitattributes` 规则 -- **命名一致性**：遵循项目现有的命名风格 -- **最小改动原则**：只修改必要的部分，不顺手重构 +- `PLAN=` +- 如为环境恢复，还会附带 `NOTE=env:<环境>:` -### 决策记录 +规划与执行留痕示例： -- **重要决策**：记录到 `memory-bank/decisions.md`（ADR 格式） -- **待确认事项**：在回复中列出并等待确认 -- **进度留痕**：通过 `docs/standards/playbook/scripts/plan_progress.py` 维护 `memory-bank/progress.md` 的 Plan 状态块（唯一权威） +```bash +# brainstorming 完成后 +python docs/standards/playbook/scripts/playbook.py \ + -record-spec docs/superpowers/specs/-design.md \ + -progress memory-bank/progress.md +``` + +```bash +# writing-plans 完成后 +python docs/standards/playbook/scripts/playbook.py \ + -record-plan docs/superpowers/plans/.md \ + -progress memory-bank/progress.md +``` + +写回命令示例： + +```bash +python docs/standards/playbook/scripts/main_loop.py finish \ + -plan \ + -status done \ + -progress memory-bank/progress.md +``` + +```bash +python docs/standards/playbook/scripts/main_loop.py finish \ + -plan \ + -status blocked \ + -progress memory-bank/progress.md \ + -note "env:<所需环境>:" +``` + +```bash +python docs/standards/playbook/scripts/main_loop.py finish \ + -plan \ + -status blocked|skipped \ + -progress memory-bank/progress.md \ + -note "<原因>" +``` + +### Plan 场景下的分支与隔离策略 + +- 本节仅适用于通过主循环领取并执行 Plan 的场景 +- 默认允许在当前分支直接执行 Plan，包括 `main` / `master` +- 不强制为 Plan 执行创建隔离工作区、临时分支或 `git worktree` +- 仅在以下场景使用隔离工作区： + - 用户明确要求隔离执行 + - Plan 文本自身明确要求隔离执行 + - 当前任务需要并行隔离以避免相互影响 +- 如外部技能、工具或默认流程要求先隔离，再执行 Plan，以本文件和用户当前指令为准 + +### 执行规则 + +1. 先 `claim`，拿到 `PLAN=` 后再读取 Plan 内容 +2. 如返回 `NOTE=env:...`，本轮只执行列出的 Task +3. 默认执行器是 `$executing-plans`；代码类任务在执行前必须显式 + 加载 `karpathy-guidelines` +4. 执行时同时遵循 `.agents/`、`AGENT_RULES.md` 和 Plan 本身； + 如发生冲突，以优先级更高的规则为准 +5. 按顺序执行 Task，并完成 Plan 约定的验证 +6. 环境不匹配时，记录所需环境和 Task，继续处理本 Plan + 其余可执行 Task +7. 其他阻塞写回 `blocked`；永久放弃写回 `skipped` +8. 触碰安全红线时立即停止，不继续后续 Plan +9. 常规模式下可对高风险事项向用户确认；无交互模式按本文件 + 的“需要确认的场景”自动处理 +10. 每次 `claim` 只领取一个 Plan；写回后再领取下一个 +11. 全部 Plan 处理完后，统一汇总完成项、阻塞项、跳过项、 + 环境需求与待确认事项 + +## 通用执行约束 + +### 代码与配置修改 + +- 必须先读文件再修改 +- 遵循 `.agents/`、项目代码风格和现有命名约定 +- 只改必要部分，不顺手重构无关内容 +- 执行与改动相称的验证；如有相关测试且未被豁免，必须通过 +- 遵循 `.gitattributes` 等换行与文件格式规则 + +### 决策与留痕 + +- 重要决策记录到 `memory-bank/decisions.md` +- 待确认事项在回复中显式列出 +- `workflow-state` 和 `plan-status` 只能通过 + `docs/standards/playbook/scripts/main_loop.py` 维护 +- `progress.md` 上半部分的人类摘要在阶段变化或执行结束后同步更新 +- 同一错误重复两次以上时，立即更新 + `AGENT_RULES.local.md` 或 `memory-bank/decisions.md` +- 发现项目特有规律时，沉淀到 `AGENT_RULES.local.md` ### Git 操作 -- **不使用 --amend**：除非用户明确要求，总是创建新提交 -- **不使用 --force**：特别是推送到 main/master，如用户要求必须警告风险 -- **不跳过 hooks**：不使用 `--no-verify` +- 不使用 `--amend`，除非用户明确要求 +- 不使用 `--force`；如用户坚持，必须先说明风险 +- 不使用 `--no-verify` 跳过 hooks -## 工具使用 +### 工具使用 -- **并行执行**：独立的工具调用尽可能并行执行 -- **遵循 schema**：严格遵循工具参数定义 -- **避免循环**：避免重复调用同一工具获取相同信息 -- **优先专用工具**：文件操作用 Read/Edit/Write，搜索用 Grep/Glob +- 独立步骤尽可能并行执行 +- 严格遵循工具参数定义与 schema +- 优先使用专用工具，不重复探测同一信息 +- 文本搜索优先使用 `rg` ## 需要确认的场景 -**常规模式**（可交互）： +### 常规模式 -- 需求不明确或存在多种可行方案 -- 需要行为/兼容性取舍 -- 风险或约束冲突 -- **架构变更**：影响多个模块的修改 -- **性能权衡**：需要在性能和可维护性之间选择 -- **兼容性问题**：可能破坏现有用户代码 +- 需求不明确，或存在多种可行方案 +- 需要行为、兼容性或性能取舍 +- 涉及架构变更、破坏性修改或约束冲突 +- 风险较高，且继续执行可能放大返工成本 -**无交互模式**（自动处理）： +### 无交互模式 -| 场景 | 处理方式 | -| -------------------------- | ---------------------------------- | -| 安全红线 | 立即停止，不继续后续 Plan | -| 架构变更/兼容性/破坏性修改 | 标记 blocked，跳到下一个 Plan | -| 多种可行方案 | 选择最保守方案，记录选择理由到报告 | -| 歧义/风险/决策点 | 记录到报告，继续执行 | +- 安全红线：立即停止，不继续后续 Plan +- 架构变更、兼容性问题、破坏性修改：写回 `blocked` +- 多种可行方案：选择最保守方案，并在报告中说明理由 +- 一般歧义、风险或决策点：记录到报告，继续执行安全部分 -**可以不确认**（两种模式通用）： +### 可以直接执行 - 明显的 bug 修复 - 符合现有模式的小改动 -- 测试用例补充 +- 测试用例补充或局部验证补齐 + +## Session 收尾 + +- 汇总已完成、阻塞、跳过的 Plan 及原因 +- 标出需要其他环境处理的事项：`env:<环境>:` +- 必要时将重要结论写入 `memory-bank/decisions.md` +- 出现以下情况时，建议开启新 Session： + - 当前方向明显跑偏 + - 讨论阶段产出多个候选方案，准备进入执行 + - Session 过长，开始重复犯同类错误 ## 验证清单 -每个 Plan 完成后，必须验证： +每个 Plan 完成后，至少确认： - [ ] 代码修改符合 `.agents/` 下的规则（如有） -- [ ] 相关测试通过（如有测试且未被豁免） -- [ ] 换行符正确 -- [ ] 无语法错误 -- [ ] 已通过 `plan_progress.py` 记录 Plan 状态 +- [ ] 相关验证已执行，且测试在未豁免时通过 +- [ ] 换行符与文件格式正确 +- [ ] 无语法错误或明显运行时错误 +- [ ] 已通过 `main_loop.py finish` 写回 Plan 状态 --- -**最后更新**：2026-02-03 - +**最后更新**：2026-05-24 diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..d871696 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,6 @@ + + +@AGENTS.md +@AGENT_RULES.md + + diff --git a/docs/prompts/README.md b/docs/prompts/README.md index 4375d26..efaacff 100644 --- a/docs/prompts/README.md +++ b/docs/prompts/README.md @@ -1,6 +1,6 @@ -# 提示词库 +# 提示词入口 -本目录包含 AI 代理的工作流程参考模板。 +本目录包含 AI 代理的工作流入口模板，用于把任务路由到合适的执行路径。 ## 目录结构 @@ -8,41 +8,68 @@ prompts/ ├── README.md # 本文件 ├── system/ -│ └── agent-behavior.md # 工作模式参考 +│ └── agent-behavior.md # 工作流入口 ├── coding/ │ ├── clarify.md # 需求澄清模板 -│ └── review.md # 复盘总结模板 -└── meta/ - └── prompt-generator.md # 元提示词生成器 +│ ├── verify-change.md # 变更验证模板 +│ ├── close-task.md # 本轮收尾模板 +│ ├── update-memory.md # 回写记忆模板 +│ └── code-review.md # MR/PR 代码评审流程 +└── custom/ # 可选：项目私有提示词 ``` ## 使用方式 -| 模板 | 触发场景 | -| ----------------------- | ------------------------------ | -| **agent-behavior.md** | 切换工作模式（探索/开发/调试） | -| **clarify.md** | 需求不明确时澄清 | -| **review.md** | Plan 完成后复盘总结 | -| **prompt-generator.md** | 创建新的专用提示词 | +| 模板 | 触发场景 | +| --------------------- | -------------------- | +| **agent-behavior.md** | 选择工作流入口 | +| **clarify.md** | 需求不明确时澄清 | +| **verify-change.md** | 声称完成前做验证 | +| **close-task.md** | 本轮工作收尾 | +| **update-memory.md** | 上下文变化后回写记忆 | +| **code-review.md** | 执行 MR/PR 代码评审 | +| **custom/*.md** | 项目私有补充流程 | ## 工作流程 -``` +```text 需求不清 → clarify.md ↓ -头脑风暴 → $brainstorming skill +入口约束 → using-superpowers ↓ -生成计划 → $writing-plans skill → docs/plans/*.md +头脑风暴 → $brainstorming skill → docs/superpowers/specs/*-design.md ↓ -执行计划 → AGENT_RULES 主循环（留痕） +spec 完成后 → `playbook.py -record-spec -progress memory-bank/progress.md` ↓ -完成复盘 → review.md +生成计划 → $writing-plans skill → docs/superpowers/plans/*.md ↓ -沉淀提示词 → prompt-generator.md（可选） +plan 完成后 → `playbook.py -record-plan -progress memory-bank/progress.md` + ↓ +领取计划 → `main_loop.py claim` + ↓ +执行计划 → `$executing-plans` + ↓ +代码类任务 → `karpathy-guidelines` + `.agents/` + `AGENT_RULES.md` + ↓ +写回状态 → `main_loop.py finish` + ↓ +更新摘要 → update-memory.md + ↓ +验证改动 → verify-change.md + ↓ +本轮收尾 → close-task.md + ↓ +代码评审（有 MR/PR 时）→ code-review.md ``` -> **核心规则在 `AGENT_RULES.md`**，第三方 skills 负责规划，主循环负责执行和留痕。 +> `coding/` 下是可被框架覆盖更新的标准模板； +> 项目私有流程应沉淀到 `custom/`。 +> +> `prompts/` 是入口层；核心规则在 `AGENT_RULES.md`， +> 长期记忆在 `memory-bank/`，状态留痕必须走 +> `playbook.py -record-spec/-record-plan` 与 +> `main_loop.py claim/finish`。 --- -**最后更新**：2026-02-03 +**最后更新**：2026-05-24 diff --git a/docs/prompts/coding/clarify.md b/docs/prompts/coding/clarify.md index d298ef7..40fd88e 100644 --- a/docs/prompts/coding/clarify.md +++ b/docs/prompts/coding/clarify.md @@ -49,4 +49,4 @@ Vibe-coding 场景下可跳过，直接开始实现。 --- -**最后更新**：2026-02-03 +**最后更新**：2026-05-24 diff --git a/docs/prompts/coding/close-task.md b/docs/prompts/coding/close-task.md new file mode 100644 index 0000000..148694c --- /dev/null +++ b/docs/prompts/coding/close-task.md @@ -0,0 +1,60 @@ +# 收尾模板 + + + +## 目标 + +确认当前任务已经形成可交付结果，并把后续工作所需的信息留痕。 + +## 执行步骤 + +### 1. 核对结果 + +- 已完成哪些改动？ +- 哪些内容仍未完成？ +- 是否存在阻塞、风险或待确认事项？ + +### 2. 核对验证 + +- 已运行哪些验证？ +- 哪些验证未运行，原因是什么？ +- 当前结果是否满足本轮交付标准？ + +### 3. 核对状态留痕 + +- `main_loop.py finish` 是否已经写回 `plan-status` +- `workflow-state.phase` 是否与当前结果一致 +- 如为代码类执行，`workflow-state` 中是否保留了 + `executor=executing-plans` 与既定 `constraints` + +### 4. 回写上下文 + +- 需要写入 `memory-bank/active-context.md` 的信息 +- 需要写入 `memory-bank/progress.md` 上半部分摘要 +- 需要写入 `memory-bank/decisions.md` 的关键决策 + +### 5. 输出收尾摘要 + +```markdown +## 本轮结果 + +- 已完成：... +- 未完成：... +- 验证：... +- 风险 / 待确认：... +- 下一步：... +``` + +## 原则 + +- 只写对下一轮仍然重要的信息 +- 未验证的内容必须显式说明 +- 如果任务状态变更，优先通过 `main_loop.py finish` 留痕 +- 不手工改写 `workflow-state` 或 `plan-status` 状态块 + +--- + +**最后更新**：2026-05-24 diff --git a/docs/prompts/coding/code-review.md b/docs/prompts/coding/code-review.md new file mode 100644 index 0000000..a4c547d --- /dev/null +++ b/docs/prompts/coding/code-review.md @@ -0,0 +1,81 @@ +# Code Review 流程 + +## 触发场景 + +收到 MR/PR 需要评审时。 + +## 准备 + +切换到对应分支并获取变更内容： + +```bash +# GitLab +glab mr checkout +glab mr view | cat +glab mr diff | cat + +# GitHub +gh pr checkout +gh pr view +gh pr diff +``` + +## 评审流程 + +逐步执行以下维度。改动简单时可跳过某些步骤。 + +### 1. 理解业务目标 + +- 能否理解本次改动的业务目标？ +- 如果目标不明确，先确认再评审。 + +### 2. High-level Review + +- 改动是否放在了合适的位置？ +- 是否尽可能复用已有实现？ +- 是否有破坏现有设计与逻辑的可能？ + +### 3. Bug 检查 + +- 是否隐含业务错误、逻辑纰漏或安全问题？ +- **未修改**的相关联代码是否有遗漏？ + +### 4. 代码清晰度 + +- 逻辑是否简洁易懂？ +- 命名是否清晰合理？ +- 一年后再读，是否能轻松理解？ + +### 5. KISS 原则 + +- 是否有不必要的复杂度？ +- 是否有未使用的定义、过多参数？ +- 是否重复造轮子？ + +### 6. 单一职责 + +- 每个函数/类是否只做一件事？ +- 文件/类/方法行数是否合理？ + +### 7. 测试覆盖 + +- 复杂业务逻辑（含 if/else/for）是否有测试？ +- 测试是否有效（非空实现）？ +- 不应过度测试无控制逻辑的代码。 + +## 输出 + +评审完成后，总结发现的**重点问题**，按严重性排列。 + +## AI 与人工的分工 + +| 维度 | 负责方 | 说明 | +| -------------------------- | ------------- | ------------------------------------- | +| Bug、逻辑漏洞、安全问题 | **AI + 人工** | AI 负责初筛与证据收集，结论需人工复核 | +| 代码清晰度、KISS、单一职责 | **AI + 人工** | AI 提供候选问题，人工决定是否采纳 | +| 架构合理性、业务对齐 | **人工** | AI 反馈少且准确率低，需人工把关 | +| 兼容性、历史债务、战略取舍 | **人工** | 依赖背景知识，AI 难以判断 | + +> 规则：AI 结论必须附文件路径、行号或可复现依据；缺少证据时按待确认假设处理。 +> +> 注意：评审不只看 diff，需结合代码库整体上下文做评估。 diff --git a/docs/prompts/coding/review.md b/docs/prompts/coding/review.md deleted file mode 100644 index 45554e9..0000000 --- a/docs/prompts/coding/review.md +++ /dev/null @@ -1,66 +0,0 @@ -# 复盘模板 - - - -## 何时使用 - -- 一批 Plan 执行完毕后 -- 阶段性工作告一段落 -- 遇到重大阻塞需要总结 - ---- - -## 复盘格式 - -```markdown -# 复盘: [日期/阶段名称] - -## 完成情况 - -### 已完成 -- [x] Plan 1: 简述 -- [x] Plan 2: 简述 - -### 阻塞 -- [ ] Plan 3: 阻塞原因 - -### 跳过 -- [ ] Plan 4: 跳过原因 - -## 关键发现 - -### 做得好的 -- 发现1 -- 发现2 - -### 待改进 -- 问题1 → 建议改进方式 -- 问题2 → 建议改进方式 - -## 决策记录 - -| 决策 | 理由 | 影响 | -|------|------|------| -| 决策1 | 为什么 | 影响范围 | - -## 下一步 - -- [ ] 待处理事项1 -- [ ] 待处理事项2 -``` - ---- - -## 复盘原则 - -- **客观记录**：如实记录完成/阻塞/跳过 -- **提取经验**：总结做得好的和待改进的 -- **决策留痕**：重要决策记录到 decisions.md -- **明确下一步**：列出后续待处理事项 - ---- - -**最后更新**：2026-02-03 diff --git a/docs/prompts/coding/update-memory.md b/docs/prompts/coding/update-memory.md new file mode 100644 index 0000000..46c2047 --- /dev/null +++ b/docs/prompts/coding/update-memory.md @@ -0,0 +1,79 @@ +# 回写记忆模板 + + + +## 什么时候需要回写 + +- 当前目标已经变化 +- 最近改动会影响下一轮判断 +- 发现新的系统模式或约束 +- 做出了值得保留的决策 + +## 回写路径 + +### `memory-bank/active-context.md` + +更新： + +- 当前目标 +- 最近变更 +- touched files +- 下一步 + +### `memory-bank/progress.md` + +更新： + +- 先读取 `workflow-state`：当前阶段、spec、plan、executor、constraints +- 再读取 `plan-status`：当前 Plan 的机器状态 +- Current Focus +- Recent Changes +- Next Steps +- Open Risks + +只更新上半部分的人类摘要，不修改状态块。 + +推荐写法： + +- `Current Focus`：当前阶段结束后，项目现在最重要的工作 +- `Recent Changes`：本轮实际完成的变更、写回的状态、关键验证结果 +- `Next Steps`：下一轮最自然的 1-3 个动作 +- `Open Risks`：仍未解决的阻塞、环境约束、待确认事项 + +禁止： + +- 手工改写 `` +- 手工改写 `` +- 把临时聊天内容、未验证猜测写进摘要 + +### `memory-bank/decisions.md` + +仅在出现重要决策时记录 ADR： + +- 为什么这样做 +- 备选方案是什么 +- 影响范围是什么 + +### `memory-bank/system-patterns.md` + +仅在发现稳定模式时更新： + +- 模块边界 +- 不变量 +- 扩展路径 +- 禁止破坏的约束 + +## 原则 + +- 只回写长期有价值的信息 +- 临时聊天内容不要写进去 +- 高变化信息放 `active-context`，稳定约束放 `system-patterns` +- `progress.md` 的状态块只由 `main_loop.py` 维护 +- 摘要应与 `workflow-state` / `plan-status` 保持一致 + +--- + +**最后更新**：2026-05-24 diff --git a/docs/prompts/coding/verify-change.md b/docs/prompts/coding/verify-change.md new file mode 100644 index 0000000..51dafd8 --- /dev/null +++ b/docs/prompts/coding/verify-change.md @@ -0,0 +1,69 @@ +# 变更验证模板 + + + +## 验证目标 + +- 这次改动要证明什么？ +- 哪些行为必须通过？ +- 哪些验证本轮不做？ + +## 验证步骤 + +### 1. 语法 / 结构检查 + +- 确认修改文件可读、可解析、无明显结构错误 + +### 2. 定向验证 + +- 只跑与本次改动直接相关的验证命令 +- 记录命令、结果和关键输出 +- 如仓库存在项目私有验证提示词（例如 `docs/prompts/custom/verify.md`），先读取并执行其中的附加约束 + +```bash +{{VERIFY_CMD}} +``` + +### 3. 差异复核 + +- 核对 diff 是否只包含预期修改 +- 确认没有误删、误改、命名漂移或路径漂移 + +### 4. 状态留痕复核 + +- `workflow-state.phase` 是否与当前声明一致 +- `plan-status` 是否已经通过 `main_loop.py finish` 写回 +- 如为代码类任务，`workflow-state` 中是否保留： + `executor=executing-plans` + `constraints=karpathy-guidelines,.agents,AGENT_RULES` + +### 5. 剩余风险 + +- 本轮未覆盖的验证 +- 环境限制 +- 需要人工确认的点 + +## 输出格式 + +```markdown +## 验证结果 + +- 已验证：... +- 证据：... +- 未验证：... +- 风险：... +``` + +## 原则 + +- 没有证据，不宣称完成 +- 局部修改优先局部验证 +- 不能运行的验证要明确写原因 +- 不手工改写 `workflow-state` 或 `plan-status` 状态块 + +--- + +**最后更新**：2026-05-24 diff --git a/docs/prompts/meta/prompt-generator.md b/docs/prompts/meta/prompt-generator.md deleted file mode 100644 index 3e8a250..0000000 --- a/docs/prompts/meta/prompt-generator.md +++ /dev/null @@ -1,126 +0,0 @@ -# 提示词生成器（元提示词） - - - -## 何时使用 - -- 需要为新场景创建专用提示词 -- 现有提示词不满足特定需求 -- 需要批量生成同类提示词 - ---- - -## 生成流程（α循环） - -### 1. 分析场景 - -```markdown -**场景名称**：[名称] -**目标用户**：[AI/人类/两者] -**触发条件**：[何时使用这个提示词] -**预期输出**：[使用后应该产出什么] -``` - -### 2. 提取约束 - -```markdown -**必须做**： -- 约束1 -- 约束2 - -**禁止做**： -- 禁止1 -- 禁止2 - -**边界条件**： -- 边界1 -- 边界2 -``` - -### 3. 生成草稿 - -```markdown -# [提示词标题] - - - -## 何时使用 - -- 场景1 -- 场景2 - -## [核心内容] - -[根据场景填充] - -## [约束/原则] - -- 约束1 -- 约束2 - ---- - -**最后更新**：2026-02-03 -``` - ---- - -## 优化流程（Ω循环） - -### 1. 评估维度 - -| 维度 | 问题 | -| ---------- | ---------------------- | -| **清晰度** | 指令是否明确无歧义？ | -| **完整度** | 是否覆盖所有必要场景？ | -| **简洁度** | 是否有冗余内容可删除？ | -| **可操作** | AI 能否直接执行？ | - -### 2. 迭代优化 - -``` -草稿 → 评估 → 修改 → 再评估 → ... → 定稿 -``` - -### 3. 验证测试 - -- 用实际场景测试提示词效果 -- 收集反馈，持续迭代 - ---- - -## 提示词模板库 - -### 标准结构 - -```markdown -# [标题] - - - -## 何时使用 -## [核心内容] -## [约束/原则] - ---- - -**最后更新**：2026-02-03 -``` - -### 命名规范 - -- 文件名：`[动词]-[对象].template.md` -- 示例：`clarify-requirement.template.md` - ---- - -**最后更新**：2026-02-03 diff --git a/docs/prompts/system/agent-behavior.md b/docs/prompts/system/agent-behavior.md index c193dd3..9721a4a 100644 --- a/docs/prompts/system/agent-behavior.md +++ b/docs/prompts/system/agent-behavior.md @@ -1,62 +1,50 @@ -# 工作模式参考 +# 工作流入口 -## 模式 1: 探索模式（Explore） +## 路由原则 -**目的**：理解代码库、分析问题、收集信息 +- 需求不明确：先看 `docs/prompts/coding/clarify.md` +- 需要设计或拆解方案：走 + `using-superpowers` → `$brainstorming` → `$writing-plans` +- `brainstorming` 结束后：立即 + `playbook.py -record-spec -progress memory-bank/progress.md` +- `writing-plans` 结束后：立即 + `playbook.py -record-plan -progress memory-bank/progress.md` +- 需要执行已有 Plan：先 `main_loop.py claim`，再走 + `$executing-plans` +- 如为代码类执行：在 `$executing-plans` 前强制叠加 + `karpathy-guidelines`，并同时遵循 `.agents/` 与 `AGENT_RULES.md` +- 需要确认改动是否站得住：看 `docs/prompts/coding/verify-change.md` +- 一轮工作收尾：看 `docs/prompts/coding/close-task.md` +- 需要更新上下文：看 `docs/prompts/coding/update-memory.md` +- 需要评审 MR/PR：看 `docs/prompts/coding/code-review.md` -**行为**： +## 最小工作流 -- 使用搜索工具探索代码 -- 输出分析报告和发现 -- 不修改任何代码 +```text +需求不清 -> clarify +需求明确 -> using-superpowers / brainstorming / writing-plans +brainstorming 完成 -> record planning/spec +writing-plans 完成 -> record plan/executor/constraints +进入执行 -> claim -> executing-plans +代码执行 -> + karpathy-guidelines + .agents + AGENT_RULES +执行结束 -> finish -> update-memory +准备交付 -> verify-change +本轮结束 -> close-task +上下文变化 -> update-memory +``` -**适用场景**： +## 说明 -- 理解某个模块的实现 -- 分析 bug 的根本原因 -- 评估功能实现的可行性 +- `prompts/` 是入口，不是规则权威 +- 稳定约束写入 `memory-bank/` 或 `AGENT_RULES.local.md` +- 执行留痕以 `memory-bank/progress.md` 的 + `workflow-state` 与 `plan-status` 为准 --- -## 模式 2: 开发模式（Develop） - -**目的**：实现功能、修复 bug、重构代码 - -**行为**： - -- 先读取相关文件，理解现有逻辑 -- 进行精确修改 -- 修改后运行测试验证 - -**适用场景**： - -- 实现新功能 -- 修复已知 bug -- 优化性能 - ---- - -## 模式 3: 调试模式（Debug） - -**目的**：诊断问题、对比差异、验证行为 - -**行为**： - -- 收集相关日志和输出 -- 分析差异原因 -- 修复后重新验证 - -**适用场景**： - -- 测试失败 -- 输出不符合预期 -- 性能问题诊断 - ---- - -**最后更新**：2026-02-03 +**最后更新**：2026-05-24 diff --git a/docs/superpowers/plans/2026-05-24-playbook-strong-alignment.md b/docs/superpowers/plans/2026-05-24-playbook-strong-alignment.md new file mode 100644 index 0000000..2329eae --- /dev/null +++ b/docs/superpowers/plans/2026-05-24-playbook-strong-alignment.md @@ -0,0 +1,92 @@ +# Playbook Strong Alignment Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans or +> equivalent plan executor. Keep verification local and update +> `memory-bank/progress.md` through playbook main-loop commands. + +**Goal:** Update the vendored playbook snapshot, align `playbook.toml`, +and migrate repo-owned agent docs to the latest playbook architecture +without touching product README files. + +**Architecture:** Treat `docs/standards/playbook/` as a pure vendored subtree, +regenerate playbook-managed files from the synced snapshot, then rewrite only the +project-owned context files so they match the new `memory-bank/` and +`docs/superpowers/` structure. + +**Tech Stack:** Git subtree, Python playbook scripts, Markdown, +repo-local `.agents/` rules + +--- + +## Plan Meta + +- **Plan Group:** playbook-alignment +- **Parent Plan:** none +- **Verification Scope:** local +- **Verification Gate:** must-pass + +### Task 1: Update vendored playbook and resync managed files + +**Files:** + +- Modify: `docs/standards/playbook/**` +- Modify: `playbook.toml` +- Modify: `AGENTS.md` +- Modify: `AGENT_RULES.md` +- Modify: `docs/prompts/**` +- Modify: `.agents/**` + +- [x] Pull the latest upstream `playbook` into + `docs/standards/playbook/` with `git subtree --squash` +- [x] Align `playbook.toml` to the new config shape and add `claude_md = "CLAUDE.md"` +- [x] Run + `python docs/standards/playbook/scripts/playbook.py -config playbook.toml` + to resync managed files + +### Task 2: Migrate project-owned context to the new architecture + +**Files:** + +- Modify: `AGENT_RULES.local.md` +- Modify: `memory-bank/project-brief.md` +- Modify: `memory-bank/tech-context.md` +- Modify: `memory-bank/system-patterns.md` +- Modify: `memory-bank/active-context.md` +- Modify: `memory-bank/progress.md` +- Modify: `memory-bank/decisions.md` + +- [x] Rewrite `AGENT_RULES.local.md` so it keeps only tsl-devkit-specific rules +- [x] Migrate `memory-bank` to + `project-brief / tech-context / system-patterns / active-context / progress / decisions` +- [x] Preserve repo-specific facts such as layer boundaries, + Tree-sitter synchronization and CIFS/git caveats + +### Task 3: Remove old architecture remnants and move the plan entry point + +**Files:** + +- Delete: `memory-bank/architecture.md` +- Delete: `memory-bank/tech-stack.md` +- Delete: `docs/prompts/coding/review.md` +- Delete: `docs/prompts/meta/prompt-generator.md` +- Deprecate: `docs/plans/2026-05-24-playbook-strong-alignment.md` +- Create: `docs/superpowers/plans/2026-05-24-playbook-strong-alignment.md` + +- [x] Create the new plan entry point under `docs/superpowers/plans/` +- [x] Delete prompt and memory-bank files that are no longer part of the latest playbook layout +- [x] Keep product README files out of scope for this migration +- [x] Replace the old `docs/plans/` file with a deprecation stub because the + current CIFS mount rejected path migration + +### Task 4: Re-record workflow state, verify, and create the final commit + +**Files:** + +- Modify: `memory-bank/progress.md` +- Commit: aligned playbook snapshot, rules, prompts, memory-bank and plan files + +- [x] Re-record the plan with + `python docs/standards/playbook/scripts/playbook.py -record-plan ...` +- [x] Use `main_loop.py claim / finish` to update authoritative workflow blocks +- [x] Re-run sync and diff checks to verify idempotence and whitespace cleanliness +- [x] Commit with repository commit-message convention diff --git a/memory-bank/active-context.md b/memory-bank/active-context.md new file mode 100644 index 0000000..409c482 --- /dev/null +++ b/memory-bank/active-context.md @@ -0,0 +1,41 @@ +# 当前上下文 + +## Current Goal + +- 完成 playbook 强对齐后的收口：沿用新文档架构、主循环和计划路径， + 后续开发不再使用旧 `memory-bank/architecture.md` / + `tech-stack.md` / `docs/plans/` + +## Recent Changes + +- `docs/standards/playbook/` 已通过 subtree 更新到上游最新快照 +- `playbook.toml` 已对齐新配置形态，并启用了 `CLAUDE.md` 同步 +- playbook 管理的规则、提示词和 `.agents/` 已重新同步 + +## Touched Files + +- `AGENT_RULES.local.md` - 收敛项目私有约束并补充 CIFS/git 注意事项 +- `memory-bank/` - 迁移到 `project-brief / tech-context / system-patterns / active-context / progress / decisions` +- `docs/superpowers/plans/2026-05-24-playbook-strong-alignment.md` - + 作为新的计划入口 + +## Open Questions + +- 暂无功能性阻塞；后续若再次在 CIFS 工作区执行 subtree， + 继续使用轻量 git stat 配置 + +## Next Steps + +1. 后续新增实施计划统一写到 `docs/superpowers/plans/` +2. 执行 Plan 时使用 `main_loop.py claim / finish` 回写 `progress.md` +3. 下次升级 playbook 仍按 subtree -> playbook sync 的顺序处理 + +## Session Notes + +- 产品 README 不属于本轮 playbook 对齐范围，保持不动 +- 旧 `docs/prompts/coding/review.md` 与 + `docs/prompts/meta/prompt-generator.md` 已由新架构替代 + +--- + +**最后更新**：2026-05-24 diff --git a/memory-bank/architecture.md b/memory-bank/architecture.md deleted file mode 100644 index 95442fd..0000000 --- a/memory-bank/architecture.md +++ /dev/null @@ -1,189 +0,0 @@ -# 架构设计 - -## 整体架构 - -```mermaid -graph TB - Client["fa:fa-desktop 客户端 (VSCode / Vim / ...)"] - - Client -->|"LSP stdio"| Core - - subgraph Server["LSP Server (C++23)"] - - subgraph Core["Core"] - direction LR - S["Server"] ~~~ D["Dispatcher"] - end - - subgraph Scheduler["Scheduler"] - direction LR - A["AsyncExecutor"] - end - - subgraph Codec["Codec"] - direction LR - C1["Facade"] ~~~ C2["Transformer"] - end - - subgraph Provider["Provider"] - direction LR - P1["Completion"] ~~~ P2["Definition"] ~~~ P3["CodeAction"] ~~~ P4["..."] - end - - subgraph Manager["Manager"] - direction LR - M1["Document"] ~~~ M2["Parser"] ~~~ M3["Symbol"] ~~~ M4["EventBus"] - end - - subgraph Language["Language"] - direction LR - L1["AST"] ~~~ L2["Semantic"] ~~~ L3["Symbol"] - end - - subgraph Bridge["Bridge"] - direction LR - B1["Glaze"] ~~~ B2["Tree-sitter"] ~~~ B3["Taskflow"] ~~~ B4["spdlog"] - end - - Core --> Provider & Manager & Scheduler - Core --> Codec - Provider --> Manager & Language - Manager --> Language & Bridge - Language --> Bridge - Scheduler --> Bridge - Codec --> Bridge - end -``` - -## 核心模块 - -### Core - 核心服务 - -**职责**：处理 LSP 协议通信，分发请求，管理服务器生命周期 - -**关键文件**： - -- `src/core/server.cppm` - 服务器主循环，stdio 读写 -- `src/core/dispatcher.cppm` - 请求分发器，路由到对应 Provider -- `src/core/bootstrap.cppm` - 服务器启动初始化 - -### Scheduler - 异步调度 - -**职责**：管理异步任务的执行、取消和生命周期 - -**关键文件**： - -- `src/scheduler/async_executor.cppm` - 异步任务执行器，基于 Taskflow 实现 - -### Codec - 编解码 - -**职责**：封装 JSON 序列化/反序列化，提供统一的 LSP 消息编解码接口 - -**关键文件**： - -- `src/codec/facade.cppm` - 序列化门面，`Serialize` / `Deserialize` 统一入口 -- `src/codec/transformer.cppm` - LSPAny 类型转换 -- `src/codec/common.cppm` - 公共类型 - -### Manager - 状态管理 - -**职责**：管理文档、符号、解析结果等核心状态 - -**关键文件**： - -- `src/manager/document.cppm` - 文档管理，维护打开的文件内容 -- `src/manager/parser.cppm` - 解析管理，维护语法树缓存 -- `src/manager/symbol.cppm` - 符号管理，维护符号索引 -- `src/manager/event_bus.cppm` - 事件总线，模块间解耦通信 -- `src/manager/events.cppm` - 事件类型定义 -- `src/manager/manager_hub.cppm` - 管理器集线器，统一访问入口 - -### Provider - LSP 功能提供者 - -**职责**：实现具体的 LSP 功能（补全、跳转、悬停等） - -**关键目录**： - -- `src/provider/completion_item/` - 代码补全 -- `src/provider/code_action/` - 代码操作 -- `src/provider/code_lens/` - 代码透镜 -- `src/provider/text_document/` - 文档相关 (悬停、跳转定义、引用等) -- `src/provider/inlay_hint/` - 内联提示 -- `src/provider/document_link/` - 文档链接 -- `src/provider/call_hierarchy/` - 调用层次 -- `src/provider/type_hierarchy/` - 类型层次 -- `src/provider/workspace_symbol/` - 工作区符号搜索 -- `src/provider/initialize/`, `src/provider/initialized/`, `src/provider/shutdown/`, `src/provider/exit/` - 生命周期管理 -- `src/provider/cancel_request/` - 请求取消 -- `src/provider/workspace/`, `src/provider/window/`, `src/provider/client/` - 协议通道管理 -- `src/provider/trace/`, `src/provider/telemetry/` - 追踪与遥测 - -### Language - 语言分析 - -**职责**：TSL 语言的语法和语义分析 - -**关键目录**： - -- `src/language/ast/` - 抽象语法树访问和遍历 -- `src/language/semantic/` - 语义分析 -- `src/language/symbol/` - 符号定义和类型 -- `src/language/keyword/` - 关键字定义 - -### Bridge - 第三方库桥接 - -**职责**：封装第三方库，提供 C++ Module 接口 - -**关键文件**： - -- `src/bridge/glaze.cppm` - JSON 序列化 -- `src/bridge/spdlog.cppm` - 日志 -- `src/bridge/taskflow.cppm` - 并行任务 -- `src/bridge/tree_sitter.cppm` - 语法解析 -- `src/bridge/win32_stdio.cppm` - Windows stdio 支持 - -### Protocol - LSP 协议 - -**职责**：定义 LSP 协议的类型和序列化 - -**关键文件**： - -- `src/protocol/types.cppm` - 基础类型定义 -- `src/protocol/protocol.cppm` - 协议聚合模块 - -## 关键约束 - -- **C++ Modules**：使用 `.cppm` 文件，需要 Clang 20+ 或 GCC 15+ -- **异步处理**：所有耗时操作必须通过 `AsyncExecutor` 异步执行 -- **增量解析**：使用 Tree-sitter 保证编辑时的响应性能 -- **JSON 序列化**：使用 Glaze 库实现零拷贝 JSON 解析 - -## 扩展点 - -### 添加新的 LSP Provider - -**步骤**： - -1. 在 `src/provider/` 下创建新目录 -2. 继承 `ProviderBase` 基类 -3. 实现 `handle()` 方法处理请求 -4. 在 `Dispatcher` 中注册路由 - -### 添加新的语义分析 - -**步骤**： - -1. 在 `src/language/semantic/` 添加分析模块 -2. 定义访问 AST 的逻辑 -3. 在 `SymbolManager` 中集成 - -### 添加新的代码补全类型 - -**步骤**： - -1. 在 `src/provider/completion_item/` 添加新的补全源 -2. 实现补全逻辑，返回 `CompletionItem` 列表 -3. 在主 completion provider 中注册 - ---- - -**最后更新**：2026-03-04 diff --git a/memory-bank/decisions.md b/memory-bank/decisions.md index 1c2afbd..3a01c88 100644 --- a/memory-bank/decisions.md +++ b/memory-bank/decisions.md @@ -141,4 +141,35 @@ VSCode 扩展作为纯客户端，通过 stdio 与独立的 LSP 服务器进程 --- -**最后更新**：2026-02-02 +## ADR-007: 使用 vendored playbook 与主循环维护代理文档 + +**日期**: 2026-05-24 +**状态**: 已采纳 + +### 决策 + +将 `docs/standards/playbook/` 作为 vendored 快照，通过 +`git subtree` 升级；仓库内规则、提示词和 `.agents/` 通过 +`python docs/standards/playbook/scripts/playbook.py -config playbook.toml` +同步；后续实施计划统一放到 `docs/superpowers/plans/`， +并使用 `main_loop.py claim / finish` 维护 `memory-bank/progress.md` +状态块。 + +### 理由 + +- 需要与 playbook 上游架构保持强对齐，减少手工漂移 +- 需要把框架管理文件与项目自维护文件分清边界 +- 需要统一 Plan 留痕和状态流转，避免旧 `docs/plans/` + 与旧 `plan-status` 机制继续分叉 + +### 影响 + +- 升级 playbook 时必须先做 subtree，再执行同步脚本 +- `AGENT_RULES.local.md` 与 `memory-bank/*.md` 仍由项目自行维护 +- 产品 README 不再承载 playbook 对齐信息 +- 后续会话应优先读取 `docs/superpowers/plans/` 与新的 + `workflow-state` / `plan-status` 状态块 + +--- + +**最后更新**：2026-05-24 diff --git a/memory-bank/progress.md b/memory-bank/progress.md index 1374270..1017790 100644 --- a/memory-bank/progress.md +++ b/memory-bank/progress.md @@ -1,65 +1,42 @@ -# 项目进度 +# 当前进展 -## 已完成功能 +## Current Focus -### LSP 服务器核心 +- 已完成 playbook 强对齐；后续开发统一使用新 `memory-bank/` 结构、 + `docs/superpowers/plans/` 和 `main_loop.py` 状态流转 -- [x] JSON-RPC 通信框架 (stdio) -- [x] 请求分发器 (Dispatcher) -- [x] 异步任务执行器 (AsyncExecutor) -- [x] 文档管理器 (DocumentManager) -- [x] 解析管理器 (ParserManager) -- [x] 符号管理器 (SymbolManager) -- [x] 事件总线 (EventBus) +## Recent Changes -### LSP 功能 (Provider) +- vendored `playbook` 快照已通过 subtree 更新并重新同步托管文件 +- `memory-bank` 已迁移到 `tech-context` / `system-patterns` / + `active-context` 新结构 +- 旧 `docs/prompts/coding/review.md`、 + `docs/prompts/meta/prompt-generator.md`、 + `memory-bank/architecture.md`、 + `memory-bank/tech-stack.md` 已移除 -- [x] `initialize` / `shutdown` / `exit` -- [x] `textDocument/didOpen` / `didChange` / `didClose` -- [x] `textDocument/completion` - 代码补全 -- [x] `textDocument/hover` - 悬停信息 -- [x] `textDocument/definition` - 跳转定义 -- [x] `textDocument/references` - 查找引用 -- [x] `textDocument/documentSymbol` - 文档符号 -- [x] `textDocument/codeAction` - 代码操作 -- [x] `textDocument/codeLens` - 代码透镜 -- [x] `textDocument/inlayHint` - 内联提示 -- [x] `textDocument/documentLink` - 文档链接 -- [x] `callHierarchy/incomingCalls` / `outgoingCalls` -- [x] `typeHierarchy/supertypes` / `subtypes` -- [x] `workspace/symbol` - 工作区符号搜索 +## Next Steps -### VSCode 扩展 +1. 新任务先写到 `docs/superpowers/plans/` 再执行 +2. 进入执行阶段前用 `main_loop.py claim` 领取 Plan +3. Playbook 升级保持 subtree + sync 的固定顺序 -- [x] 语法高亮 (TextMate) -- [x] 代码片段 (Snippets) -- [x] LSP 客户端集成 -- [x] 扩展打包 (`.vsix`) +## Open Risks -### 构建与部署 +- CIFS 共享目录上的 git 索引状态可能误报脏工作区， + 影响 subtree、status 和 stash 类命令 -- [x] CMake 构建系统 -- [x] Conan 依赖管理 -- [x] Linux (Clang) 构建 -- [x] Windows 交叉编译 -- [x] Gitea CI/CD 流水线 +## Workflow State -## 进行中 + +phase: done +plan: docs/superpowers/plans/2026-05-24-playbook-strong-alignment.md +executor: executing-plans +constraints: karpathy-guidelines,.agents,AGENT_RULES + -- [ ] 语义高亮 (`textDocument/semanticTokens`) -- [ ] 重命名 (`textDocument/rename`) -- [ ] 格式化 (`textDocument/formatting`) - -## 待规划 - -- [ ] 诊断 (`textDocument/publishDiagnostics`) -- [ ] 签名帮助 (`textDocument/signatureHelp`) -- [ ] 折叠范围 (`textDocument/foldingRange`) -- [ ] 选择范围 (`textDocument/selectionRange`) - ---- - -# Plan 状态 +## Plan Status +- [x] `2026-05-24-playbook-strong-alignment.md` done diff --git a/memory-bank/project-brief.md b/memory-bank/project-brief.md index d1623d6..d4c2d60 100644 --- a/memory-bank/project-brief.md +++ b/memory-bank/project-brief.md @@ -2,47 +2,49 @@ ## 项目定位 -**核心目标**：为 TSL (TinySoft Language) 提供完整的 IDE 开发体验 +**核心目标**：为 TSL 提供稳定、可扩展的语言服务与编辑器集成能力。 -**一句话描述**：基于 LSP 标准的 TSL 语言服务器及编辑器扩展套件 +**一句话描述**：以 C++23 LSP 服务器为核心，配套 VSCode 与 Vim 支持的 +TSL 开发套件。 ## 项目边界 ### 做什么 -- 实现 LSP (Language Server Protocol) 服务器，提供标准语言服务 -- 提供 VSCode 扩展，集成语法高亮、代码补全、诊断等功能 -- 提供 Vim 语法支持 -- 支持跨平台运行 (Linux / Windows) +- 实现 TSL 的 LSP 服务器，提供补全、跳转、引用、符号等语言能力 +- 维护 Tree-sitter 解析、AST、语义与符号链路，保障编辑时反馈质量 +- 提供 VSCode 扩展与 Vim 语法支持，覆盖主要编辑器接入场景 +- 维护 Linux / Windows 的构建、测试与发布路径 ### 不做什么 -- 不实现 TSL 语言的编译器/解释器 -- 不实现 TSL 语言的运行时环境 -- 不提供 TSL 语言的调试功能 (Debugger) +- 不实现 TSL 编译器、解释器或运行时 +- 不实现调试器或独立 IDE 产品 +- 不把 playbook 同步内容扩展到产品 README 范围 ### 约束条件 -- 必须遵循 LSP 3.17+ 协议标准 -- LSP 服务器必须支持增量解析以保证响应性能 -- 必须同时支持 Linux 和 Windows 平台 +- 对外行为必须保持 LSP 3.17+ 兼容 +- 解析链路必须支持增量更新，避免编辑场景响应退化 +- C++ 服务器代码以 C++23 Modules 组织，依赖现代编译器工具链 +- `docs/standards/playbook/` 作为 vendored 快照维护，更新流程固定 ## 核心概念 -| 术语 | 说明 | -| --------------- | ------------------------------------------------ | -| **TSL** | TinySoft Language，天软公司的领域特定脚本语言 | -| **LSP** | Language Server Protocol，微软定义的语言服务协议 | -| **Tree-sitter** | 增量解析框架，用于构建语法树 | -| **Provider** | LSP 功能提供者，处理特定类型的请求 | -| **Manager** | 管理器，负责文档、符号、解析等核心状态管理 | +| 术语 | 说明 | +| --- | --- | +| **TSL** | TinySoft Language，天软公司的领域脚本语言 | +| **LSP** | Language Server Protocol，编辑器与语言服务的标准协议 | +| **Tree-sitter** | 增量解析器，用于语法树构建和局部更新 | +| **Provider** | 处理具体 LSP 请求的能力模块 | +| **Manager** | 管理文档、解析结果、符号等共享状态的核心组件 | ## 参考资料 - [LSP 规范](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/) - [Tree-sitter 文档](https://tree-sitter.github.io/tree-sitter/) -- [VSCode 扩展 API](https://code.visualstudio.com/api) +- [VSCode Extension API](https://code.visualstudio.com/api) --- -**最后更新**：2026-02-02 +**最后更新**：2026-05-24 diff --git a/memory-bank/system-patterns.md b/memory-bank/system-patterns.md new file mode 100644 index 0000000..0594a6f --- /dev/null +++ b/memory-bank/system-patterns.md @@ -0,0 +1,77 @@ +# 系统模式与约束 + +## 模块边界 + +### Core / Protocol + +- **职责**：处理 stdio 生命周期、LSP 消息路由、协议类型定义与序列化入口 +- **输入**：编辑器发来的原始 LSP 请求、通知、初始化参数 +- **输出**：分发后的 provider 调用、协议响应和服务端事件 +- **不应负责**：语义分析、符号计算、解析缓存管理 + +### Provider / Manager + +- **职责**：Provider 负责 capability 级编排； + Manager 负责文档、解析结果、符号等共享状态 +- **输入**：已解析的协议请求、文档状态、语言分析结果 +- **输出**：LSP 返回值、workspace edit、内部状态更新 +- **不应负责**：跨层直接操作第三方库细节，或绕过 manager 持久化共享状态 + +### Language / Bridge + +- **职责**：Language 负责 AST、语义、符号逻辑； + Bridge 负责 Tree-sitter、Glaze、Taskflow、spdlog 等第三方封装 +- **输入**：语法树、节点访问请求、共享分析上下文 +- **输出**：AST 结构、语义结论、符号信息、桥接后的库接口 +- **不应负责**：LSP 协议路由、编辑器生命周期管理 + +## 关键数据流 + +1. 编辑器请求进入 `core/server.cppm`，由 `dispatcher.cppm` + 解析 method 并路由到对应 provider +2. Provider 通过 `manager/` 获取文档、语法树和符号状态， + 需要深入分析时再调用 `language/` 能力 +3. 结果经 `protocol/` 与 `codec/` 序列化后返回客户端； + 异步任务由 `scheduler/async_executor.cppm` 承载 + +## 核心不变量 + +- LSP 线协议必须稳定，能力扩展优先新增 provider 而不是改现有报文结构 +- 文档和解析缓存由 manager 统一持有，其他层不各自维护第二份真相 +- Tree-sitter 生成物、AST 访问逻辑和测试夹具必须同步演进 +- Bridge 模块只做库封装，不夹带 TSL 业务分支 + +## 常见实现模式 + +### 新增 LSP 能力 + +- **适用场景**：新增 `textDocument/*`、`workspace/*`、 + `callHierarchy/*` 等协议能力 +- **推荐做法**：先补 protocol 类型，再在 `src/provider/` + 新增或扩展对应 provider，最后在 dispatcher 注册并补测试 +- **避免事项**：把协议分发、共享状态和语义逻辑揉进一个模块里 + +### 调整语法或 AST + +- **适用场景**：关键字、表达式、声明、节点结构发生变化 +- **推荐做法**：先改 Tree-sitter 与 parser/scanner，同步 AST / + semantic / symbol 访问点，再补 `test_tree_sitter`、 + `test_ast`、相关 provider 测试 +- **避免事项**：只改生成物不改测试，或只改 AST 不回溯语法源 + +## 扩展路径 + +1. 协议功能扩展优先从 `src/protocol/`、`src/provider/`、 + `src/core/dispatcher.cppm` 这一条链路进入 +2. 语言分析扩展优先从 `src/language/` 进入， + 需要共享缓存时再通过 `src/manager/` 暴露给 provider + +## 禁止破坏的约束 + +- 不破坏现有分层边界，不跨层绕过 manager 直接操作底层解析状态 +- 不引入与现有 C++23 Modules 组织方式冲突的头文件式拼装 +- 不在 playbook 对齐任务里修改产品 README 或业务实现 + +--- + +**最后更新**：2026-05-24 diff --git a/memory-bank/tech-context.md b/memory-bank/tech-context.md new file mode 100644 index 0000000..d44f62a --- /dev/null +++ b/memory-bank/tech-context.md @@ -0,0 +1,80 @@ +# 技术上下文与工具链 + +## 核心技术 + +- C++23 Modules、CMake、Conan、Ninja：`lsp-server/` 主体工具链 +- Tree-sitter：TSL 增量解析与语法树生成 +- Glaze、Taskflow、spdlog：JSON、异步调度与日志基础设施 +- TypeScript + VSCode API：`vscode/` 扩展 +- Python 3：playbook 同步、Plan 流程与辅助脚本 + +## 项目结构 + +```text +tsl-devkit/ +├── lsp-server/ # C++23 LSP 服务器、解析器与测试 +├── vscode/ # VSCode 扩展 +├── vim/ # Vim 语法与运行时支持 +├── docs/standards/playbook/ # vendored playbook 快照 +├── docs/prompts/ # playbook 管理的提示词入口 +├── docs/superpowers/plans/ # 实施计划 +└── memory-bank/ # 项目上下文 +``` + +## 关键入口 + +- `lsp-server/src/core/server.cppm` - LSP stdio 主循环 +- `lsp-server/src/core/dispatcher.cppm` - 请求分发入口 +- `lsp-server/src/provider/` - 各类 LSP capability 实现 +- `lsp-server/src/manager/` - 文档、解析、符号等共享状态 +- `lsp-server/src/language/` - AST、语义、符号分析 +- `docs/standards/playbook/scripts/playbook.py` - 同步 playbook 管理文件 +- `docs/standards/playbook/scripts/main_loop.py` - Plan 领取与写回 + +## 开发环境 + +**必需工具**： + +- Python 3 +- CMake 4.2+ +- Conan 2.x +- Ninja +- Clang 20+ 或 GCC 15+ +- Node.js 18+ + +**运行测试**： + +```bash +ctest --test-dir lsp-server/build/clang-linux/Release --output-on-failure +npm --prefix vscode run compile +``` + +**格式化 / Lint**： + +```bash +clang-format -i +npx --prefix vscode prettier -w +``` + +## 环境与平台差异 + +- Linux 是主开发环境；Windows 构建通过 Conan profile + CMake 交叉编译支持 +- 仓库位于 CIFS 共享目录时，git 索引状态可能不稳定，需要用轻量 stat 配置 + +## 依赖与限制 + +- Conan 安装和部分构建步骤依赖外网或内网制品源 +- `docs/standards/playbook/` 不做手工业务改造，只通过 subtree 更新 +- `vscode/package.json` 目前没有独立 lint 脚本，TS 侧最基本验证是 `npm run compile` + +## 验证约定 + +- 文档 / playbook 变更至少要重新运行 + `python docs/standards/playbook/scripts/playbook.py -config playbook.toml` +- 代码改动的验证范围要与影响面匹配，至少覆盖对应模块的构建或测试 +- 在 CIFS 工作区里，git 校验命令优先加 + `-c core.trustctime=false -c core.checkStat=minimal` + +--- + +**最后更新**：2026-05-24 diff --git a/memory-bank/tech-stack.md b/memory-bank/tech-stack.md deleted file mode 100644 index 08b71c4..0000000 --- a/memory-bank/tech-stack.md +++ /dev/null @@ -1,123 +0,0 @@ -# 技术栈与工具链 - -## 核心技术 - -**主语言**：C++23 (LSP 服务器) + TypeScript (VSCode 扩展) - -**文件类型**：`.cppm` (C++ Module), `.cc`, `.ts`, `.json` - -## 项目结构 - -```text -tsl-devkit/ -├── lsp-server/ # LSP 服务器 (C++23) -│ ├── src/ # 源代码 -│ │ ├── bridge/ # 第三方库桥接 -│ │ ├── cli/ # 命令行接口 -│ │ ├── codec/ # 编解码器 -│ │ ├── core/ # 核心服务 -│ │ ├── language/ # 语言分析 -│ │ ├── manager/ # 状态管理器 -│ │ ├── protocol/ # LSP 协议定义 -│ │ ├── provider/ # LSP 功能提供者 -│ │ ├── scheduler/ # 异步调度 -│ │ ├── tree-sitter/ # 解析器绑定 -│ │ └── utils/ # 工具函数 -│ ├── test/ # 单元测试 -│ └── conan/ # Conan 配置 -├── vscode/ # VSCode 扩展 -│ ├── src/ # TypeScript 源码 -│ ├── syntaxes/ # TextMate 语法 -│ └── snippets/ # 代码片段 -├── vim/ # Vim 支持 -├── test/ # 集成测试用例 -├── docs/ # 文档 -│ ├── prompts/ # AI 编码提示 -│ └── standards/ # 代码标准 -└── memory-bank/ # 项目上下文 -``` - -## 开发环境 - -**必需工具**： - -- CMake 4.2+ -- Clang 20+ (推荐) 或 GCC 15+ -- Conan 2.x (包管理) -- Node.js 18+ (VSCode 扩展开发) -- ninja (构建) - -**构建 LSP 服务器 (Linux)**： - -```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 --build=missing - -# 配置 -cmake -S lsp-server -B lsp-server/build/clang-linux/Release \ - -DCMAKE_TOOLCHAIN_FILE=$PWD/lsp-server/build/clang-linux/Release/generators/conan_toolchain.cmake \ - -DBUILD_TESTS=ON - -# 构建 -cmake --build lsp-server/build/clang-linux/Release --target tsl-server -``` - -**构建 LSP 服务器 (Windows 交叉编译)**： - -```bash -CONAN_HOME=/tmp/conan-home conan install lsp-server \ - -pr:b=lsp-server/conan/profiles/linux-x86_64-clang \ - -pr:h=lsp-server/conan/profiles/windows-x86_64-clang-cross \ - -of lsp-server/build/clang-cross --build=missing - -cmake -S lsp-server -B lsp-server/build/clang-cross \ - -DCMAKE_TOOLCHAIN_FILE=$PWD/lsp-server/build/clang-cross/Release/generators/conan_toolchain.cmake \ - -DBUILD_TESTS=OFF - -cmake --build lsp-server/build/clang-cross --target tsl-server -``` - -**运行测试**： - -```bash -# C++ 单元测试 -ctest --test-dir lsp-server/build/clang-linux/Release --output-on-failure - -# VSCode 扩展 -cd vscode && npm test -``` - -## 依赖管理 - -**C++ 依赖 (Conan)**： - -| 包 | 版本 | 用途 | -| ----------- | ------ | ------------------ | -| glaze | 6.4.0 | 高性能 JSON 序列化 | -| spdlog | 1.17.0 | 日志库 | -| fmt | 12.1.0 | 格式化库 | -| taskflow | 3.10.0 | 并行任务执行 | -| tree-sitter | 0.25.9 | 增量语法解析 | - -**VSCode 扩展依赖 (npm)**： - -| 包 | 用途 | -| --------------------- | ---------- | -| vscode-languageclient | LSP 客户端 | - -## 测试策略 - -**测试类型**： - -- LSP JSON 测试：Python 脚本驱动的协议交互测试 (`run_lsp_json_tests.py`) - -**验证标准**： - -- 所有 LSP JSON 测试通过 - ---- - -**最后更新**：2026-02-02 diff --git a/playbook.toml b/playbook.toml index c40ad9a..3871261 100644 --- a/playbook.toml +++ b/playbook.toml @@ -1,6 +1,7 @@ [playbook] project_root = "." deploy_root = "docs/standards/playbook" +claude_md = "CLAUDE.md" [sync_rules] force = true @@ -19,9 +20,3 @@ no_backup = true langs = ["cpp", "tsl", "markdown"] gitattr_mode = "append" no_backup = true - -[install_skills] -mode = "all" -agents_home = "~/.agents" -skill_link = "~/.claude" -no_backup = true