🔧 chore(playbook): align repo with latest workflow
lsp-server ci / build-and-test (push) Failing after 0s
Details
lsp-server ci / build-and-test (push) Failing after 0s
Details
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.
This commit is contained in:
parent
696920df73
commit
7838f3ec3d
|
|
@ -43,5 +43,4 @@
|
||||||
|
|
||||||
## 与开发规范的关系
|
## 与开发规范的关系
|
||||||
|
|
||||||
- 本仓库内：`docs/standards/playbook/docs/cpp/` 与 `docs/standards/playbook/docs/common/`
|
- 规范文档：`docs/standards/playbook/docs/cpp/` 与 `docs/standards/playbook/docs/common/`
|
||||||
- 目标项目 subtree：`docs/standards/playbook/docs/cpp/` 与 `docs/standards/playbook/docs/common/`
|
|
||||||
|
|
|
||||||
|
|
@ -4,14 +4,18 @@
|
||||||
|
|
||||||
建议约定：
|
建议约定：
|
||||||
|
|
||||||
- `.agents/tsl/`：TSL 相关规则集（由 `sync_standards.*` 同步；适用于 `.tsl`/`.tsf`）
|
- `.agents/cpp/`：C++ 相关规则集（由 playbook 同步；适用于 C++23/Modules）
|
||||||
- `.agents/cpp/`：C++ 相关规则集（由 `sync_standards.*` 同步；适用于 C++23/Modules）
|
- `.agents/tsl/`：TSL 相关规则集（由 playbook 同步；适用于 `.tsl`/`.tsf`）
|
||||||
- `.agents/python/` 等：其他语言的规则集（按需增加）
|
- `.agents/markdown/`：Markdown 相关规则集（仅代码格式化）
|
||||||
|
|
||||||
规则发生冲突时，建议以“更靠近代码的目录规则更具体”为准。
|
规则发生冲突时，建议以“更靠近代码的目录规则更具体”为准。
|
||||||
|
|
||||||
入口建议从：
|
入口建议从：
|
||||||
|
|
||||||
- `.agents/tsl/index.md`（TSL 规则集入口）
|
- `.agents/cpp/index.md`
|
||||||
- `.agents/cpp/index.md`（C++ 规则集入口）
|
- `.agents/tsl/index.md`
|
||||||
- `docs/standards/playbook/docs/`（人类开发规范快照：`tsl/`、`cpp/`、`python/`、`common/`）
|
- `.agents/markdown/index.md`
|
||||||
|
|
||||||
|
标准快照文档入口：
|
||||||
|
|
||||||
|
- docs/standards/playbook/docs
|
||||||
|
|
|
||||||
|
|
@ -20,6 +20,7 @@
|
||||||
|
|
||||||
- 优先使用 Prettier（仓库已固定配置/脚本）
|
- 优先使用 Prettier（仓库已固定配置/脚本）
|
||||||
- 不引入新的 Markdown 格式化依赖
|
- 不引入新的 Markdown 格式化依赖
|
||||||
|
- `markdownlint` 如需启用，由目标项目自行增加；不属于本规则集默认部署内容
|
||||||
|
|
||||||
### 行内代码
|
### 行内代码
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -28,17 +28,18 @@
|
||||||
|
|
||||||
## 权威来源
|
## 权威来源
|
||||||
|
|
||||||
- 语法手册：`docs/standards/playbook/docs/tsl/syntax_book/index.md`
|
- TSL 总入口：`docs/standards/playbook/docs/tsl/index.md`
|
||||||
- 函数库：`docs/standards/playbook/docs/tsl/syntax_book/function/`（按需检索，禁止整份加载）
|
- 语法手册：`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/code_style.md`
|
||||||
- 命名规范：`docs/standards/playbook/docs/tsl/naming.md`
|
- 命名规范：`docs/standards/playbook/docs/tsl/naming.md`
|
||||||
|
|
||||||
## Skills（按需加载）
|
## Skills（按需加载）
|
||||||
|
|
||||||
- `$tsl-guide`
|
|
||||||
- `$commit-message`
|
- `$commit-message`
|
||||||
|
|
||||||
## 与开发规范的关系
|
## 与开发规范的关系
|
||||||
|
|
||||||
- 本仓库内：`docs/standards/playbook/docs/tsl/` 与 `docs/standards/playbook/docs/common/`
|
- 规范文档：`docs/standards/playbook/docs/tsl/` 与 `docs/standards/playbook/docs/common/`
|
||||||
- 目标项目 subtree：`docs/standards/playbook/docs/tsl/` 与 `docs/standards/playbook/docs/common/`
|
|
||||||
|
|
|
||||||
12
AGENTS.md
12
AGENTS.md
|
|
@ -24,19 +24,15 @@ Human-facing standards snapshot (vendored):
|
||||||
|
|
||||||
- [AGENT_RULES.md](./AGENT_RULES.md) - 执行流程与优先级
|
- [AGENT_RULES.md](./AGENT_RULES.md) - 执行流程与优先级
|
||||||
|
|
||||||
### 项目上下文
|
### 项目状态
|
||||||
|
|
||||||
- [memory-bank/project-brief.md](memory-bank/project-brief.md) - 项目定位
|
- [memory-bank/project-brief.md](memory-bank/project-brief.md) - 项目定位
|
||||||
- [memory-bank/tech-stack.md](memory-bank/tech-stack.md) - 技术栈
|
- [memory-bank/active-context.md](memory-bank/active-context.md) - 当前上下文
|
||||||
- [memory-bank/architecture.md](memory-bank/architecture.md) - 架构设计
|
|
||||||
- [memory-bank/progress.md](memory-bank/progress.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/README.md](docs/prompts/README.md) - 提示词与流程入口
|
||||||
- [docs/prompts/coding/review.md](docs/prompts/coding/review.md) - 复盘总结
|
|
||||||
- [docs/prompts/system/agent-behavior.md](docs/prompts/system/agent-behavior.md) - 工作模式参考
|
|
||||||
<!-- playbook:templates:end -->
|
<!-- playbook:templates:end -->
|
||||||
|
|
||||||
<!-- playbook:agents:start -->
|
<!-- playbook:agents:start -->
|
||||||
|
|
|
||||||
|
|
@ -1,104 +1,87 @@
|
||||||
# AGENT_RULES.local
|
# 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`
|
## Tree-sitter / AST 同步规则
|
||||||
- `memory-bank/tech-stack.md`
|
|
||||||
|
|
||||||
## 代码/架构约束
|
新增或修改语法、解析、AST 链路时：
|
||||||
|
|
||||||
- 禁止无需求变更 LSP 协议对外行为：`method` 字符串、协议字段命名、响应结构保持兼容
|
1. 先更新语法源、生成物和解析入口，再补 AST / semantic 适配
|
||||||
- 禁止破坏现有分层：Provider 不直接承载 Manager/Language 的底层实现细节
|
2. `lsp-server/src/tree-sitter/` 与
|
||||||
- 换行符必须遵循 `.gitattributes` 规则，以该文件中的配置为准
|
`lsp-server/test/test_tree_sitter/src/`
|
||||||
- 禁止提交构建产物和临时文件：`lsp-server/build/**`、运行日志、临时脚本输出
|
下同名 parser / scanner 文件必须同步
|
||||||
- `docs/standards/playbook/` 为 vendored 快照；更新优先使用 subtree + 同步脚本，不做无依据手改
|
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
|
```bash
|
||||||
# 1) 安装依赖（Conan）
|
|
||||||
CONAN_HOME=/tmp/conan-home conan install lsp-server \
|
CONAN_HOME=/tmp/conan-home conan install lsp-server \
|
||||||
-pr:h=lsp-server/conan/profiles/linux-x86_64-clang \
|
-pr:h=lsp-server/conan/profiles/linux-x86_64-clang \
|
||||||
-pr:b=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 \
|
-of lsp-server/build/clang-linux/Release \
|
||||||
--build=missing
|
--build=missing
|
||||||
|
|
||||||
# 2) 配置（CMake + Ninja）
|
|
||||||
cmake -S lsp-server -B lsp-server/build/clang-linux/Release -G 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 \
|
-DCMAKE_TOOLCHAIN_FILE=$PWD/lsp-server/build/clang-linux/Release/generators/conan_toolchain.cmake \
|
||||||
-DBUILD_TESTS=ON
|
-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
|
## Playbook 对齐规则
|
||||||
cmake --build lsp-server/build/clang-linux/Release --target tsl-server
|
|
||||||
cmake --build lsp-server/build/clang-linux/Release --target test_ast
|
|
||||||
```
|
|
||||||
|
|
||||||
## 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
|
|
||||||
|
|
||||||
## 紧急处理
|
- 该仓库常位于 CIFS 共享目录，`git status`、
|
||||||
|
`git diff-index` 可能出现假脏或卡住
|
||||||
- 构建/测试环境异常（例如 Conan 缓存、CMake 缓存、路径映射问题）优先记录可复现命令与原始报错
|
- 遇到索引异常时，优先使用：
|
||||||
- 若遇到跨环境阻塞，按 `AGENT_RULES.md` 的 `blocked: env:<环境>:<Task列表>` 规范记录并继续主循环
|
`git -c core.trustctime=false -c core.checkStat=minimal ...`
|
||||||
|
- 必要时执行 `git update-index --refresh`，
|
||||||
|
或先给受影响目录补 `u+w` 权限后再做 subtree / stash / clean
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
**最后更新**：2026-03-05
|
**最后更新**：2026-05-24
|
||||||
|
|
|
||||||
385
AGENT_RULES.md
385
AGENT_RULES.md
|
|
@ -9,214 +9,291 @@
|
||||||
3. 仓库规则：`.agents/` 与 `AGENTS.md`
|
3. 仓库规则：`.agents/` 与 `AGENTS.md`
|
||||||
4. 本文件
|
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=<path>`
|
||||||
|
- `writing-plans` 写出 plan 后，立即用 `playbook.py -record-plan`
|
||||||
|
记录 `plan=<path>`、`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 要求
|
||||||
|
|
||||||
| 阶段 | 工具 | 产出 | 留痕 |
|
- `Plan Meta` 必填，位于 Plan 头部 `---` 之后、Task 1 之前
|
||||||
| ------------ | ---------------------- | ----------------- | -------------------- |
|
- `Plan Meta` 至少包含：
|
||||||
| 头脑风暴 | `$brainstorming` skill | 设计思路 | 无 |
|
- `Plan Group`
|
||||||
| 生成计划 | `$writing-plans` skill | `docs/plans/*.md` | 无 |
|
- `Parent Plan`
|
||||||
| **执行计划** | **主循环** | 代码/配置变更 | **plan_progress.py** |
|
- `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`：永久跳过，不再执行
|
||||||
|
|
||||||
| 状态 | 含义 |
|
`skipped` 如需恢复，必须手动改回 `pending`。
|
||||||
| ----------- | ------------------------- |
|
|
||||||
| pending | 待执行 |
|
|
||||||
| in-progress | 执行中（崩溃恢复用） |
|
|
||||||
| done | 已完成 |
|
|
||||||
| blocked | 阻塞（需人工介入） |
|
|
||||||
| skipped | 跳过（Plan 不再需要执行） |
|
|
||||||
|
|
||||||
> 说明：`skipped` 仅用于永久不再执行；如需恢复执行，需手动改回 `pending`。
|
### 环境阻塞格式
|
||||||
|
|
||||||
**环境阻塞格式**：`blocked: env:<环境>:<Task列表>`
|
- 格式：`env:<环境>:<Task列表>`
|
||||||
|
- 示例：`env:windows:Task2,Task4`
|
||||||
|
- `Task` 列表必须使用英文逗号分隔，且不要包含空格
|
||||||
|
|
||||||
- 示例：`blocked: env:windows:Task2,Task4`
|
### 领取与写回
|
||||||
- 含义：需要在指定环境执行列出的 Task
|
|
||||||
- 约束：`Task` 列表使用英文逗号分隔，不要包含空格，便于解析
|
|
||||||
|
|
||||||
**流程**：
|
领取命令：
|
||||||
|
|
||||||
1. 检测环境：
|
```bash
|
||||||
- 由 `plan_progress.py` 自动识别当前环境（`windows` / `linux` / `darwin`）
|
python docs/standards/playbook/scripts/main_loop.py claim \
|
||||||
2. 选择 Plan：
|
-plans docs/superpowers/plans \
|
||||||
- 运行 `python docs/standards/playbook/scripts/plan_progress.py select -plans docs/plans -progress memory-bank/progress.md`
|
-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 <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:<所需环境>:<Task列表>"`
|
|
||||||
- 其他阻塞：`... -status blocked ... -note "<原因>"`
|
|
||||||
- 跳过整个 Plan：`... -status skipped ... -note "<原因>"`
|
|
||||||
- 回到步骤 2 继续下一个 Plan
|
|
||||||
7. 汇总报告（所有 Plan 处理完毕后）：
|
|
||||||
- 已完成的 Plan
|
|
||||||
- 阻塞/跳过的 Plan 及原因
|
|
||||||
- 需要在其他环境执行的 Plan（`blocked: env:...`）
|
|
||||||
- 待确认的歧义/风险/决策点
|
|
||||||
- 如需记录重要决策，写入 `memory-bank/decisions.md`
|
|
||||||
8. **结束**：主循环终止
|
|
||||||
|
|
||||||
## Plan 规则
|
该命令会在锁保护下串行完成三件事：
|
||||||
|
|
||||||
- **Plan Meta 必填**：Plan 头部 `---` 之后、Task 1 之前插入 `## Plan Meta`，包含：
|
- 自动识别当前环境：`windows`、`linux`、`darwin`
|
||||||
- `Plan Group`（归类任务）
|
- 按顺序选择可执行 Plan：
|
||||||
- `Parent Plan`（上层/集成计划链接）
|
`in-progress` > `pending` > `blocked: env:<当前环境>:...`
|
||||||
- `Verification Scope`（local 或 integration）
|
- 将选中的 Plan 写成 `in-progress`
|
||||||
- `Verification Gate`（must-pass）
|
|
||||||
- **不允许中断任务**：Plan 中不应包含必然失败或依赖未确认的信息；未确认项必须在 `$brainstorming` 阶段解决后再产出 Plan
|
|
||||||
- **验证必须可通过**：Plan 内验证应为当前阶段可通过的局部验证；需要集成验证的内容放入上层/集成 Plan
|
|
||||||
- 不因等待确认而中断可执行步骤；待确认事项在回复中列出
|
|
||||||
- 每轮只处理一个 Plan
|
|
||||||
- **小步快跑**：每个 Plan 应该可快速完成
|
|
||||||
- **可验证**：每个 Plan 必须包含验证步骤
|
|
||||||
|
|
||||||
## 执行约束
|
这里的锁保护的是 `progress.md` 状态块更新，避免多个 session
|
||||||
|
同时读写时发生覆盖。
|
||||||
|
|
||||||
### 代码修改
|
stdout 必须包含：
|
||||||
|
|
||||||
- **必须先读文件再修改**：不读文件就提议修改是禁止的
|
- `PLAN=<path>`
|
||||||
- **必须运行测试验证**：相关测试必须通过
|
- 如为环境恢复，还会附带 `NOTE=env:<环境>:<Task列表>`
|
||||||
- **遵循换行规则**：遵循 `.gitattributes` 规则
|
|
||||||
- **命名一致性**：遵循项目现有的命名风格
|
|
||||||
- **最小改动原则**：只修改必要的部分，不顺手重构
|
|
||||||
|
|
||||||
### 决策记录
|
规划与执行留痕示例：
|
||||||
|
|
||||||
- **重要决策**：记录到 `memory-bank/decisions.md`（ADR 格式）
|
```bash
|
||||||
- **待确认事项**：在回复中列出并等待确认
|
# brainstorming 完成后
|
||||||
- **进度留痕**：通过 `docs/standards/playbook/scripts/plan_progress.py` 维护 `memory-bank/progress.md` 的 Plan 状态块（唯一权威）
|
python docs/standards/playbook/scripts/playbook.py \
|
||||||
|
-record-spec docs/superpowers/specs/<topic>-design.md \
|
||||||
|
-progress memory-bank/progress.md
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# writing-plans 完成后
|
||||||
|
python docs/standards/playbook/scripts/playbook.py \
|
||||||
|
-record-plan docs/superpowers/plans/<topic>.md \
|
||||||
|
-progress memory-bank/progress.md
|
||||||
|
```
|
||||||
|
|
||||||
|
写回命令示例：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python docs/standards/playbook/scripts/main_loop.py finish \
|
||||||
|
-plan <plan> \
|
||||||
|
-status done \
|
||||||
|
-progress memory-bank/progress.md
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python docs/standards/playbook/scripts/main_loop.py finish \
|
||||||
|
-plan <plan> \
|
||||||
|
-status blocked \
|
||||||
|
-progress memory-bank/progress.md \
|
||||||
|
-note "env:<所需环境>:<Task列表>"
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python docs/standards/playbook/scripts/main_loop.py finish \
|
||||||
|
-plan <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 操作
|
### Git 操作
|
||||||
|
|
||||||
- **不使用 --amend**：除非用户明确要求，总是创建新提交
|
- 不使用 `--amend`，除非用户明确要求
|
||||||
- **不使用 --force**：特别是推送到 main/master，如用户要求必须警告风险
|
- 不使用 `--force`；如用户坚持，必须先说明风险
|
||||||
- **不跳过 hooks**：不使用 `--no-verify`
|
- 不使用 `--no-verify` 跳过 hooks
|
||||||
|
|
||||||
## 工具使用
|
### 工具使用
|
||||||
|
|
||||||
- **并行执行**：独立的工具调用尽可能并行执行
|
- 独立步骤尽可能并行执行
|
||||||
- **遵循 schema**：严格遵循工具参数定义
|
- 严格遵循工具参数定义与 schema
|
||||||
- **避免循环**：避免重复调用同一工具获取相同信息
|
- 优先使用专用工具，不重复探测同一信息
|
||||||
- **优先专用工具**：文件操作用 Read/Edit/Write，搜索用 Grep/Glob
|
- 文本搜索优先使用 `rg`
|
||||||
|
|
||||||
## 需要确认的场景
|
## 需要确认的场景
|
||||||
|
|
||||||
**常规模式**（可交互）：
|
### 常规模式
|
||||||
|
|
||||||
- 需求不明确或存在多种可行方案
|
- 需求不明确，或存在多种可行方案
|
||||||
- 需要行为/兼容性取舍
|
- 需要行为、兼容性或性能取舍
|
||||||
- 风险或约束冲突
|
- 涉及架构变更、破坏性修改或约束冲突
|
||||||
- **架构变更**：影响多个模块的修改
|
- 风险较高，且继续执行可能放大返工成本
|
||||||
- **性能权衡**：需要在性能和可维护性之间选择
|
|
||||||
- **兼容性问题**：可能破坏现有用户代码
|
|
||||||
|
|
||||||
**无交互模式**（自动处理）：
|
### 无交互模式
|
||||||
|
|
||||||
| 场景 | 处理方式 |
|
- 安全红线：立即停止，不继续后续 Plan
|
||||||
| -------------------------- | ---------------------------------- |
|
- 架构变更、兼容性问题、破坏性修改：写回 `blocked`
|
||||||
| 安全红线 | 立即停止，不继续后续 Plan |
|
- 多种可行方案：选择最保守方案，并在报告中说明理由
|
||||||
| 架构变更/兼容性/破坏性修改 | 标记 blocked，跳到下一个 Plan |
|
- 一般歧义、风险或决策点：记录到报告，继续执行安全部分
|
||||||
| 多种可行方案 | 选择最保守方案，记录选择理由到报告 |
|
|
||||||
| 歧义/风险/决策点 | 记录到报告，继续执行 |
|
|
||||||
|
|
||||||
**可以不确认**（两种模式通用）：
|
### 可以直接执行
|
||||||
|
|
||||||
- 明显的 bug 修复
|
- 明显的 bug 修复
|
||||||
- 符合现有模式的小改动
|
- 符合现有模式的小改动
|
||||||
- 测试用例补充
|
- 测试用例补充或局部验证补齐
|
||||||
|
|
||||||
|
## Session 收尾
|
||||||
|
|
||||||
|
- 汇总已完成、阻塞、跳过的 Plan 及原因
|
||||||
|
- 标出需要其他环境处理的事项：`env:<环境>:<Task列表>`
|
||||||
|
- 必要时将重要结论写入 `memory-bank/decisions.md`
|
||||||
|
- 出现以下情况时，建议开启新 Session：
|
||||||
|
- 当前方向明显跑偏
|
||||||
|
- 讨论阶段产出多个候选方案，准备进入执行
|
||||||
|
- Session 过长，开始重复犯同类错误
|
||||||
|
|
||||||
## 验证清单
|
## 验证清单
|
||||||
|
|
||||||
每个 Plan 完成后，必须验证：
|
每个 Plan 完成后，至少确认：
|
||||||
|
|
||||||
- [ ] 代码修改符合 `.agents/` 下的规则（如有）
|
- [ ] 代码修改符合 `.agents/` 下的规则（如有）
|
||||||
- [ ] 相关测试通过（如有测试且未被豁免）
|
- [ ] 相关验证已执行，且测试在未豁免时通过
|
||||||
- [ ] 换行符正确
|
- [ ] 换行符与文件格式正确
|
||||||
- [ ] 无语法错误
|
- [ ] 无语法错误或明显运行时错误
|
||||||
- [ ] 已通过 `plan_progress.py` 记录 Plan 状态
|
- [ ] 已通过 `main_loop.py finish` 写回 Plan 状态
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
**最后更新**：2026-02-03
|
**最后更新**：2026-05-24
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,6 @@
|
||||||
|
<!-- playbook:claude:start -->
|
||||||
|
|
||||||
|
@AGENTS.md
|
||||||
|
@AGENT_RULES.md
|
||||||
|
|
||||||
|
<!-- playbook:claude:end -->
|
||||||
|
|
@ -1,6 +1,6 @@
|
||||||
# 提示词库
|
# 提示词入口
|
||||||
|
|
||||||
本目录包含 AI 代理的工作流程参考模板。
|
本目录包含 AI 代理的工作流入口模板，用于把任务路由到合适的执行路径。
|
||||||
|
|
||||||
## 目录结构
|
## 目录结构
|
||||||
|
|
||||||
|
|
@ -8,41 +8,68 @@
|
||||||
prompts/
|
prompts/
|
||||||
├── README.md # 本文件
|
├── README.md # 本文件
|
||||||
├── system/
|
├── system/
|
||||||
│ └── agent-behavior.md # 工作模式参考
|
│ └── agent-behavior.md # 工作流入口
|
||||||
├── coding/
|
├── coding/
|
||||||
│ ├── clarify.md # 需求澄清模板
|
│ ├── clarify.md # 需求澄清模板
|
||||||
│ └── review.md # 复盘总结模板
|
│ ├── verify-change.md # 变更验证模板
|
||||||
└── meta/
|
│ ├── close-task.md # 本轮收尾模板
|
||||||
└── prompt-generator.md # 元提示词生成器
|
│ ├── update-memory.md # 回写记忆模板
|
||||||
|
│ └── code-review.md # MR/PR 代码评审流程
|
||||||
|
└── custom/ # 可选：项目私有提示词
|
||||||
```
|
```
|
||||||
|
|
||||||
## 使用方式
|
## 使用方式
|
||||||
|
|
||||||
| 模板 | 触发场景 |
|
| 模板 | 触发场景 |
|
||||||
| ----------------------- | ------------------------------ |
|
| --------------------- | -------------------- |
|
||||||
| **agent-behavior.md** | 切换工作模式（探索/开发/调试） |
|
| **agent-behavior.md** | 选择工作流入口 |
|
||||||
| **clarify.md** | 需求不明确时澄清 |
|
| **clarify.md** | 需求不明确时澄清 |
|
||||||
| **review.md** | Plan 完成后复盘总结 |
|
| **verify-change.md** | 声称完成前做验证 |
|
||||||
| **prompt-generator.md** | 创建新的专用提示词 |
|
| **close-task.md** | 本轮工作收尾 |
|
||||||
|
| **update-memory.md** | 上下文变化后回写记忆 |
|
||||||
|
| **code-review.md** | 执行 MR/PR 代码评审 |
|
||||||
|
| **custom/*.md** | 项目私有补充流程 |
|
||||||
|
|
||||||
## 工作流程
|
## 工作流程
|
||||||
|
|
||||||
```
|
```text
|
||||||
需求不清 → clarify.md
|
需求不清 → 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 <path> -progress memory-bank/progress.md`
|
||||||
↓
|
↓
|
||||||
完成复盘 → review.md
|
生成计划 → $writing-plans skill → docs/superpowers/plans/*.md
|
||||||
↓
|
↓
|
||||||
沉淀提示词 → prompt-generator.md（可选）
|
plan 完成后 → `playbook.py -record-plan <path> -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
|
||||||
|
|
|
||||||
|
|
@ -49,4 +49,4 @@ Vibe-coding 场景下可跳过，直接开始实现。
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
**最后更新**：2026-02-03
|
**最后更新**：2026-05-24
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,60 @@
|
||||||
|
# 收尾模板
|
||||||
|
|
||||||
|
<!--
|
||||||
|
用途：一轮实现或一个 Plan 结束后做收尾
|
||||||
|
触发：准备结束当前任务、切换上下文、交付结果前
|
||||||
|
-->
|
||||||
|
|
||||||
|
## 目标
|
||||||
|
|
||||||
|
确认当前任务已经形成可交付结果，并把后续工作所需的信息留痕。
|
||||||
|
|
||||||
|
## 执行步骤
|
||||||
|
|
||||||
|
### 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
|
||||||
|
|
@ -0,0 +1,81 @@
|
||||||
|
# Code Review 流程
|
||||||
|
|
||||||
|
## 触发场景
|
||||||
|
|
||||||
|
收到 MR/PR 需要评审时。
|
||||||
|
|
||||||
|
## 准备
|
||||||
|
|
||||||
|
切换到对应分支并获取变更内容：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# GitLab
|
||||||
|
glab mr checkout <MR_ID>
|
||||||
|
glab mr view <MR_ID> | cat
|
||||||
|
glab mr diff <MR_ID> | cat
|
||||||
|
|
||||||
|
# GitHub
|
||||||
|
gh pr checkout <PR_NUMBER>
|
||||||
|
gh pr view <PR_NUMBER>
|
||||||
|
gh pr diff <PR_NUMBER>
|
||||||
|
```
|
||||||
|
|
||||||
|
## 评审流程
|
||||||
|
|
||||||
|
逐步执行以下维度。改动简单时可跳过某些步骤。
|
||||||
|
|
||||||
|
### 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，需结合代码库整体上下文做评估。
|
||||||
|
|
@ -1,66 +0,0 @@
|
||||||
# 复盘模板
|
|
||||||
|
|
||||||
<!--
|
|
||||||
用途：Plan 或阶段完成后的回顾总结
|
|
||||||
触发：主循环汇总报告时、阶段性工作完成时
|
|
||||||
-->
|
|
||||||
|
|
||||||
## 何时使用
|
|
||||||
|
|
||||||
- 一批 Plan 执行完毕后
|
|
||||||
- 阶段性工作告一段落
|
|
||||||
- 遇到重大阻塞需要总结
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 复盘格式
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
# 复盘: [日期/阶段名称]
|
|
||||||
|
|
||||||
## 完成情况
|
|
||||||
|
|
||||||
### 已完成
|
|
||||||
- [x] Plan 1: 简述
|
|
||||||
- [x] Plan 2: 简述
|
|
||||||
|
|
||||||
### 阻塞
|
|
||||||
- [ ] Plan 3: 阻塞原因
|
|
||||||
|
|
||||||
### 跳过
|
|
||||||
- [ ] Plan 4: 跳过原因
|
|
||||||
|
|
||||||
## 关键发现
|
|
||||||
|
|
||||||
### 做得好的
|
|
||||||
- 发现1
|
|
||||||
- 发现2
|
|
||||||
|
|
||||||
### 待改进
|
|
||||||
- 问题1 → 建议改进方式
|
|
||||||
- 问题2 → 建议改进方式
|
|
||||||
|
|
||||||
## 决策记录
|
|
||||||
|
|
||||||
| 决策 | 理由 | 影响 |
|
|
||||||
|------|------|------|
|
|
||||||
| 决策1 | 为什么 | 影响范围 |
|
|
||||||
|
|
||||||
## 下一步
|
|
||||||
|
|
||||||
- [ ] 待处理事项1
|
|
||||||
- [ ] 待处理事项2
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 复盘原则
|
|
||||||
|
|
||||||
- **客观记录**：如实记录完成/阻塞/跳过
|
|
||||||
- **提取经验**：总结做得好的和待改进的
|
|
||||||
- **决策留痕**：重要决策记录到 decisions.md
|
|
||||||
- **明确下一步**：列出后续待处理事项
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**最后更新**：2026-02-03
|
|
||||||
|
|
@ -0,0 +1,79 @@
|
||||||
|
# 回写记忆模板
|
||||||
|
|
||||||
|
<!--
|
||||||
|
用途：在任务完成、方向切换或发现新规律后更新 memory-bank
|
||||||
|
触发：完成一轮实现、形成新决策、当前焦点变化时
|
||||||
|
-->
|
||||||
|
|
||||||
|
## 什么时候需要回写
|
||||||
|
|
||||||
|
- 当前目标已经变化
|
||||||
|
- 最近改动会影响下一轮判断
|
||||||
|
- 发现新的系统模式或约束
|
||||||
|
- 做出了值得保留的决策
|
||||||
|
|
||||||
|
## 回写路径
|
||||||
|
|
||||||
|
### `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`：仍未解决的阻塞、环境约束、待确认事项
|
||||||
|
|
||||||
|
禁止：
|
||||||
|
|
||||||
|
- 手工改写 `<!-- workflow-state:start/end -->`
|
||||||
|
- 手工改写 `<!-- plan-status:start/end -->`
|
||||||
|
- 把临时聊天内容、未验证猜测写进摘要
|
||||||
|
|
||||||
|
### `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
|
||||||
|
|
@ -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
|
||||||
|
|
@ -1,126 +0,0 @@
|
||||||
# 提示词生成器（元提示词）
|
|
||||||
|
|
||||||
<!--
|
|
||||||
用途：根据场景自动生成专用提示词
|
|
||||||
原理：α-prompts（生成）+ Ω-prompts（优化）递归循环
|
|
||||||
-->
|
|
||||||
|
|
||||||
## 何时使用
|
|
||||||
|
|
||||||
- 需要为新场景创建专用提示词
|
|
||||||
- 现有提示词不满足特定需求
|
|
||||||
- 需要批量生成同类提示词
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 生成流程（α循环）
|
|
||||||
|
|
||||||
### 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
|
|
||||||
|
|
@ -1,62 +1,50 @@
|
||||||
# 工作模式参考
|
# 工作流入口
|
||||||
|
|
||||||
<!--
|
<!--
|
||||||
本文件定义三种工作模式，供 AI 根据任务类型选择。
|
本文件不重复定义核心规则；它只负责把任务路由到合适的工作流入口。
|
||||||
核心规则（安全红线、验证清单等）见 AGENT_RULES.md。
|
安全红线、验证要求、主循环规则见 AGENT_RULES.md。
|
||||||
-->
|
-->
|
||||||
|
|
||||||
## 模式 1: 探索模式（Explore）
|
## 路由原则
|
||||||
|
|
||||||
**目的**：理解代码库、分析问题、收集信息
|
- 需求不明确：先看 `docs/prompts/coding/clarify.md`
|
||||||
|
- 需要设计或拆解方案：走
|
||||||
|
`using-superpowers` → `$brainstorming` → `$writing-plans`
|
||||||
|
- `brainstorming` 结束后：立即
|
||||||
|
`playbook.py -record-spec <path> -progress memory-bank/progress.md`
|
||||||
|
- `writing-plans` 结束后：立即
|
||||||
|
`playbook.py -record-plan <path> -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
|
||||||
|
```
|
||||||
|
|
||||||
**适用场景**：
|
## 说明
|
||||||
|
|
||||||
- 理解某个模块的实现
|
- `prompts/` 是入口，不是规则权威
|
||||||
- 分析 bug 的根本原因
|
- 稳定约束写入 `memory-bank/` 或 `AGENT_RULES.local.md`
|
||||||
- 评估功能实现的可行性
|
- 执行留痕以 `memory-bank/progress.md` 的
|
||||||
|
`workflow-state` 与 `plan-status` 为准
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 模式 2: 开发模式（Develop）
|
**最后更新**：2026-05-24
|
||||||
|
|
||||||
**目的**：实现功能、修复 bug、重构代码
|
|
||||||
|
|
||||||
**行为**：
|
|
||||||
|
|
||||||
- 先读取相关文件，理解现有逻辑
|
|
||||||
- 进行精确修改
|
|
||||||
- 修改后运行测试验证
|
|
||||||
|
|
||||||
**适用场景**：
|
|
||||||
|
|
||||||
- 实现新功能
|
|
||||||
- 修复已知 bug
|
|
||||||
- 优化性能
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 模式 3: 调试模式（Debug）
|
|
||||||
|
|
||||||
**目的**：诊断问题、对比差异、验证行为
|
|
||||||
|
|
||||||
**行为**：
|
|
||||||
|
|
||||||
- 收集相关日志和输出
|
|
||||||
- 分析差异原因
|
|
||||||
- 修复后重新验证
|
|
||||||
|
|
||||||
**适用场景**：
|
|
||||||
|
|
||||||
- 测试失败
|
|
||||||
- 输出不符合预期
|
|
||||||
- 性能问题诊断
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**最后更新**：2026-02-03
|
|
||||||
|
|
|
||||||
|
|
@ -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
|
||||||
|
|
@ -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
|
||||||
|
|
@ -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<T>` / `Deserialize<T>` 统一入口
|
|
||||||
- `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
|
|
||||||
|
|
@ -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
|
||||||
|
|
|
||||||
|
|
@ -1,65 +1,42 @@
|
||||||
# 项目进度
|
# 当前进展
|
||||||
|
|
||||||
## 已完成功能
|
## Current Focus
|
||||||
|
|
||||||
### LSP 服务器核心
|
- 已完成 playbook 强对齐；后续开发统一使用新 `memory-bank/` 结构、
|
||||||
|
`docs/superpowers/plans/` 和 `main_loop.py` 状态流转
|
||||||
|
|
||||||
- [x] JSON-RPC 通信框架 (stdio)
|
## Recent Changes
|
||||||
- [x] 请求分发器 (Dispatcher)
|
|
||||||
- [x] 异步任务执行器 (AsyncExecutor)
|
|
||||||
- [x] 文档管理器 (DocumentManager)
|
|
||||||
- [x] 解析管理器 (ParserManager)
|
|
||||||
- [x] 符号管理器 (SymbolManager)
|
|
||||||
- [x] 事件总线 (EventBus)
|
|
||||||
|
|
||||||
### 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`
|
## Next Steps
|
||||||
- [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` - 工作区符号搜索
|
|
||||||
|
|
||||||
### VSCode 扩展
|
1. 新任务先写到 `docs/superpowers/plans/` 再执行
|
||||||
|
2. 进入执行阶段前用 `main_loop.py claim` 领取 Plan
|
||||||
|
3. Playbook 升级保持 subtree + sync 的固定顺序
|
||||||
|
|
||||||
- [x] 语法高亮 (TextMate)
|
## Open Risks
|
||||||
- [x] 代码片段 (Snippets)
|
|
||||||
- [x] LSP 客户端集成
|
|
||||||
- [x] 扩展打包 (`.vsix`)
|
|
||||||
|
|
||||||
### 构建与部署
|
- CIFS 共享目录上的 git 索引状态可能误报脏工作区，
|
||||||
|
影响 subtree、status 和 stash 类命令
|
||||||
|
|
||||||
- [x] CMake 构建系统
|
## Workflow State
|
||||||
- [x] Conan 依赖管理
|
|
||||||
- [x] Linux (Clang) 构建
|
|
||||||
- [x] Windows 交叉编译
|
|
||||||
- [x] Gitea CI/CD 流水线
|
|
||||||
|
|
||||||
## 进行中
|
<!-- workflow-state:start -->
|
||||||
|
phase: done
|
||||||
|
plan: docs/superpowers/plans/2026-05-24-playbook-strong-alignment.md
|
||||||
|
executor: executing-plans
|
||||||
|
constraints: karpathy-guidelines,.agents,AGENT_RULES
|
||||||
|
<!-- workflow-state:end -->
|
||||||
|
|
||||||
- [ ] 语义高亮 (`textDocument/semanticTokens`)
|
## Plan Status
|
||||||
- [ ] 重命名 (`textDocument/rename`)
|
|
||||||
- [ ] 格式化 (`textDocument/formatting`)
|
|
||||||
|
|
||||||
## 待规划
|
|
||||||
|
|
||||||
- [ ] 诊断 (`textDocument/publishDiagnostics`)
|
|
||||||
- [ ] 签名帮助 (`textDocument/signatureHelp`)
|
|
||||||
- [ ] 折叠范围 (`textDocument/foldingRange`)
|
|
||||||
- [ ] 选择范围 (`textDocument/selectionRange`)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
# Plan 状态
|
|
||||||
|
|
||||||
<!-- plan-status:start -->
|
<!-- plan-status:start -->
|
||||||
|
- [x] `2026-05-24-playbook-strong-alignment.md` done
|
||||||
<!-- plan-status:end -->
|
<!-- plan-status:end -->
|
||||||
|
|
|
||||||
|
|
@ -2,47 +2,49 @@
|
||||||
|
|
||||||
## 项目定位
|
## 项目定位
|
||||||
|
|
||||||
**核心目标**：为 TSL (TinySoft Language) 提供完整的 IDE 开发体验
|
**核心目标**：为 TSL 提供稳定、可扩展的语言服务与编辑器集成能力。
|
||||||
|
|
||||||
**一句话描述**：基于 LSP 标准的 TSL 语言服务器及编辑器扩展套件
|
**一句话描述**：以 C++23 LSP 服务器为核心，配套 VSCode 与 Vim 支持的
|
||||||
|
TSL 开发套件。
|
||||||
|
|
||||||
## 项目边界
|
## 项目边界
|
||||||
|
|
||||||
### 做什么
|
### 做什么
|
||||||
|
|
||||||
- 实现 LSP (Language Server Protocol) 服务器，提供标准语言服务
|
- 实现 TSL 的 LSP 服务器，提供补全、跳转、引用、符号等语言能力
|
||||||
- 提供 VSCode 扩展，集成语法高亮、代码补全、诊断等功能
|
- 维护 Tree-sitter 解析、AST、语义与符号链路，保障编辑时反馈质量
|
||||||
- 提供 Vim 语法支持
|
- 提供 VSCode 扩展与 Vim 语法支持，覆盖主要编辑器接入场景
|
||||||
- 支持跨平台运行 (Linux / Windows)
|
- 维护 Linux / Windows 的构建、测试与发布路径
|
||||||
|
|
||||||
### 不做什么
|
### 不做什么
|
||||||
|
|
||||||
- 不实现 TSL 语言的编译器/解释器
|
- 不实现 TSL 编译器、解释器或运行时
|
||||||
- 不实现 TSL 语言的运行时环境
|
- 不实现调试器或独立 IDE 产品
|
||||||
- 不提供 TSL 语言的调试功能 (Debugger)
|
- 不把 playbook 同步内容扩展到产品 README 范围
|
||||||
|
|
||||||
### 约束条件
|
### 约束条件
|
||||||
|
|
||||||
- 必须遵循 LSP 3.17+ 协议标准
|
- 对外行为必须保持 LSP 3.17+ 兼容
|
||||||
- LSP 服务器必须支持增量解析以保证响应性能
|
- 解析链路必须支持增量更新，避免编辑场景响应退化
|
||||||
- 必须同时支持 Linux 和 Windows 平台
|
- C++ 服务器代码以 C++23 Modules 组织，依赖现代编译器工具链
|
||||||
|
- `docs/standards/playbook/` 作为 vendored 快照维护，更新流程固定
|
||||||
|
|
||||||
## 核心概念
|
## 核心概念
|
||||||
|
|
||||||
| 术语 | 说明 |
|
| 术语 | 说明 |
|
||||||
| --------------- | ------------------------------------------------ |
|
| --- | --- |
|
||||||
| **TSL** | TinySoft Language，天软公司的领域特定脚本语言 |
|
| **TSL** | TinySoft Language，天软公司的领域脚本语言 |
|
||||||
| **LSP** | Language Server Protocol，微软定义的语言服务协议 |
|
| **LSP** | Language Server Protocol，编辑器与语言服务的标准协议 |
|
||||||
| **Tree-sitter** | 增量解析框架，用于构建语法树 |
|
| **Tree-sitter** | 增量解析器，用于语法树构建和局部更新 |
|
||||||
| **Provider** | LSP 功能提供者，处理特定类型的请求 |
|
| **Provider** | 处理具体 LSP 请求的能力模块 |
|
||||||
| **Manager** | 管理器，负责文档、符号、解析等核心状态管理 |
|
| **Manager** | 管理文档、解析结果、符号等共享状态的核心组件 |
|
||||||
|
|
||||||
## 参考资料
|
## 参考资料
|
||||||
|
|
||||||
- [LSP 规范](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/)
|
- [LSP 规范](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/)
|
||||||
- [Tree-sitter 文档](https://tree-sitter.github.io/tree-sitter/)
|
- [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
|
||||||
|
|
|
||||||
|
|
@ -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
|
||||||
|
|
@ -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 <cpp-files>
|
||||||
|
npx --prefix vscode prettier -w <ts-or-json-files>
|
||||||
|
```
|
||||||
|
|
||||||
|
## 环境与平台差异
|
||||||
|
|
||||||
|
- 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
|
||||||
|
|
@ -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
|
|
||||||
|
|
@ -1,6 +1,7 @@
|
||||||
[playbook]
|
[playbook]
|
||||||
project_root = "."
|
project_root = "."
|
||||||
deploy_root = "docs/standards/playbook"
|
deploy_root = "docs/standards/playbook"
|
||||||
|
claude_md = "CLAUDE.md"
|
||||||
|
|
||||||
[sync_rules]
|
[sync_rules]
|
||||||
force = true
|
force = true
|
||||||
|
|
@ -19,9 +20,3 @@ no_backup = true
|
||||||
langs = ["cpp", "tsl", "markdown"]
|
langs = ["cpp", "tsl", "markdown"]
|
||||||
gitattr_mode = "append"
|
gitattr_mode = "append"
|
||||||
no_backup = true
|
no_backup = true
|
||||||
|
|
||||||
[install_skills]
|
|
||||||
mode = "all"
|
|
||||||
agents_home = "~/.agents"
|
|
||||||
skill_link = "~/.claude"
|
|
||||||
no_backup = true
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue