From 01caaf806213cd0cf5cc214c73d07706eef3a934 Mon Sep 17 00:00:00 2001 From: csh Date: Mon, 2 Feb 2026 13:02:42 +0800 Subject: [PATCH] :package: deps(playbook): sync rules, prompts, memory-bank --- .agents/cpp/auth.md | 33 ---- .agents/cpp/code_quality.md | 37 ----- .agents/cpp/index.md | 68 ++++---- .agents/cpp/performance.md | 31 ---- .agents/cpp/testing.md | 26 --- .agents/tsl/index.md | 44 +++++ AGENTS.md | 29 ++++ AGENT_RULES.md | 221 ++++++++++++++++++++++++++ docs/prompts/README.md | 48 ++++++ docs/prompts/coding/clarify.md | 52 ++++++ docs/prompts/coding/review.md | 66 ++++++++ docs/prompts/meta/prompt-generator.md | 126 +++++++++++++++ docs/prompts/system/agent-behavior.md | 62 ++++++++ memory-bank/architecture.md | 44 +++++ memory-bank/decisions.md | 33 ++++ memory-bank/progress.md | 4 + memory-bank/project-brief.md | 48 ++++++ memory-bank/tech-stack.md | 64 ++++++++ playbook.toml | 17 ++ 19 files changed, 892 insertions(+), 161 deletions(-) delete mode 100644 .agents/cpp/auth.md delete mode 100644 .agents/cpp/code_quality.md delete mode 100644 .agents/cpp/performance.md delete mode 100644 .agents/cpp/testing.md create mode 100644 .agents/tsl/index.md create mode 100644 AGENT_RULES.md create mode 100644 docs/prompts/README.md create mode 100644 docs/prompts/coding/clarify.md create mode 100644 docs/prompts/coding/review.md create mode 100644 docs/prompts/meta/prompt-generator.md create mode 100644 docs/prompts/system/agent-behavior.md create mode 100644 memory-bank/architecture.md create mode 100644 memory-bank/decisions.md create mode 100644 memory-bank/progress.md create mode 100644 memory-bank/project-brief.md create mode 100644 memory-bank/tech-stack.md create mode 100644 playbook.toml diff --git a/.agents/cpp/auth.md b/.agents/cpp/auth.md deleted file mode 100644 index 5adf24f..0000000 --- a/.agents/cpp/auth.md +++ /dev/null @@ -1,33 +0,0 @@ -# 安全与鉴权（Auth） - -本文件定义代理在处理鉴权、安全、敏感数据相关任务时的边界与要求。 - -## 1. 基本原则 - -- **最小权限**：只使用完成任务所需的最低权限与最少数据。 -- **默认保守**：不确定是否敏感时按敏感处理。 -- **不扩散秘密**：任何 secret 只在必要范围内出现。 - -## 2. 凭证与敏感信息 - -- 不要在代码、日志、注释或文档中写入明文密钥、Token、密码。 -- 如需示例，使用占位符：``、``。 -- 避免把敏感信息打印到标准输出或错误日志。 - -## 3. 鉴权逻辑修改 - -- 修改鉴权/权限控制时必须说明： - - 变更动机 - - 风险评估 - - 兼容性/回滚方案 -- 默认保持旧行为兼容，除非明确要求破坏性变更。 - -## 4. 依赖与第三方 - -- 禁止无理由新增依赖，尤其是网络、加密、认证相关依赖。 -- 若必须新增，需在 PR 说明理由、替代方案与安全影响。 - -## 5. 审计与合规 - -- 任何涉及用户数据/权限边界的改动需可审计：代码清晰、注释说明“为什么”。 -- 发现潜在安全漏洞时，优先修复或明确标注 `FIXME(name): security risk ...`。 diff --git a/.agents/cpp/code_quality.md b/.agents/cpp/code_quality.md deleted file mode 100644 index 1695a3f..0000000 --- a/.agents/cpp/code_quality.md +++ /dev/null @@ -1,37 +0,0 @@ -# 代码质量（Code Quality） - -本文件定义代理对代码质量的最低要求与审查清单（C++）。 - -## 1. 总体要求 - -- C++ 代码遵守 `docs/cpp/code_style.md` 与 - `docs/cpp/naming.md`（在目标项目中通常 vendoring 到标准快照路径）。 -- 统一使用 - `clang-format`（Google 基线）保持格式一致；不要手工“对齐排版”制造 diff 噪音。 -- 改动聚焦目标；避免“顺手重构”。 -- API 变更要显式说明影响与迁移方式。 -- 涉及三方依赖（例如 Conan）的改动必须说明动机、替代方案与影响面；默认不“顺手升级依赖”。 -- 涉及 C++ Modules 的改动（`.cppm` 或 `export module` - 变更）必须同步更新构建系统的模块清单与相关 target 配置。 - -## 2. 可读性 - -- 复杂逻辑拆分为具名函数/类型；避免深层嵌套与重复代码。 -- 必要注释解释“为什么”而不是“做什么”。 - -## 3. 错误处理与资源管理 - -- 默认使用 RAII；避免裸 `new/delete`。 -- 失败路径必须可观测（返回值/异常/日志其一或按项目约定）。 - -## 4. 复杂度与规模 - -- 单函数尽量 ≤ 80 行；超过应说明原因或拆分（可按项目调整）。 -- 单次 PR 尽量小步提交，便于 review。 - -## 5. Review 清单 - -- 是否有无关改动？ -- 是否保持模块内风格一致？ -- 是否引入不必要的复杂度/依赖？ -- 是否有最小验证（构建/冒烟）步骤？ diff --git a/.agents/cpp/index.md b/.agents/cpp/index.md index 4fe80b4..17336e7 100644 --- a/.agents/cpp/index.md +++ b/.agents/cpp/index.md @@ -1,47 +1,47 @@ -# C++ 代理规则集（.agents/cpp） +# C++ 代理规则集 -本规则集用于存放 **AI/自动化代理在仓库内工作时必须遵守的规则**（C++ 语言专属）。 +本规则集定义 AI/自动化代理在处理 C++ 代码时必须遵守的核心约束。 ## 范围与优先级 -- 作为仓库级基线规则集使用；更靠近代码目录的规则应更具体并可覆盖基线。 -- 当代理规则与 `docs` 发生冲突时： - 1. 安全/合规优先 - 2. 其次保持仓库现有一致性 +- 作为仓库级基线规则集使用；更靠近代码目录的规则更具体并可覆盖基线。 +- 当代理规则与 docs 冲突：安全/合规优先，其次保持仓库一致性。 -## 代理工作原则 +## 代理工作原则（铁律） -- 先理解目标与上下文，再动手改代码。 -- 修改要小而清晰；避免无关重构。 -- 不要引入新依赖或工具，除非明确要求。 +1. 先理解目标与上下文，再动手改代码 +2. 修改要小而清晰；避免无关重构 +3. 发现安全问题（内存安全/鉴权漏洞）立即标注或修复 +4. 不引入新依赖或工具，除非明确要求 -## 子文档 +## C++ 核心约定（不可违反） -- 安全与鉴权：`auth.md` -- 性能：`performance.md` -- 代码质量：`code_quality.md` -- 测试：`testing.md` +- 语言标准：C++23；优先使用 Modules；避免裸指针、`new/delete`、C 风格字符串 +- 代码风格：Google C++ Style Guide；使用项目 `.clang-format`；头文件保护用 `#pragma once` +- 命名规范：文件 `lower_with_under.cpp/.h/.cppm`；类型 `CapWords`；函数/变量 `lower_with_under`；常量 `kCapWords`；成员 `lower_with_under_`；命名空间 `lower_with_under` +- Modules 工程：模块名点分层 `lower_snake_case`；接口文件 `.cppm`；修改 `export module` 必须更新 CMake module file-set +- 构建与依赖：Conan 需提供 `conan-release`/`conan-debug`；`conan install` + `cmake --preset ...`；Windows 通过 Linux + Clang 交叉编译验证 -## C++ 必要约定（必须遵守） +## 安全红线（不可触碰） -- 语言标准：C++23（含 Modules）。 -- 格式化：统一使用 - `clang-format`（Google 基线）；避免手工排版对齐造成 diff 噪音。 -- 文件与命名：遵守 `docs/cpp/` 下的规范（或目标项目 vendoring 的标准快照路径）。 -- Modules：module 名建议使用点分层级；每段用 `lower_snake_case`；module - interface unit 推荐 `.cppm`。 -- Modules 工程：新增/删除/重命名 `.cppm` 或修改 `export module` - 时，必须更新 CMake target 的模块 file-set/清单（否则构建容易漂移）。 -- Windows：不支持原生 Windows 开发环境；Windows 产物通过 Linux + - Clang 交叉编译 profile 验证（profile 的 `[settings] os=Windows`）。 -- 依赖管理（如使用 Conan）：必须提供统一 preset（`conan-release`/`conan-debug`）；优先通过 - `conan install` + `cmake --preset ...` - 验证；如遇 Conan 家目录权限问题可临时设置 `CONAN_HOME=/tmp/conan-home`。 +- 不得在代码/日志/注释中写入明文密钥、密码、Token、API Key +- 避免内存不安全操作：悬垂指针、双重释放、越界访问 +- 禁用不安全函数（`strcpy`, `sprintf`, `gets` 等） +- 修改鉴权/权限逻辑必须说明动机与风险 + +## 权威来源 + +- 代码风格：`docs/standards/playbook/docs/cpp/code_style.md` +- 命名规范：`docs/standards/playbook/docs/cpp/naming.md` +- 工具链：`docs/standards/playbook/docs/cpp/toolchain.md` +- 依赖管理：`docs/standards/playbook/docs/cpp/dependencies_conan.md` +- clangd 配置：`docs/standards/playbook/docs/cpp/clangd.md` + +## Skills（按需加载） + +- `$commit-message` ## 与开发规范的关系 -- 在本仓库内：`docs/cpp/` 与 `docs/common/`。 -- 在目标项目内（若按 README 推荐的 subtree prefix `docs/standards/playbook`）： - - 代码风格：`docs/standards/playbook/docs/cpp/code_style.md` - - 命名规范：`docs/standards/playbook/docs/cpp/naming.md` - - 提交信息：`docs/standards/playbook/docs/common/commit_message.md` +- 本仓库内：`docs/standards/playbook/docs/cpp/` 与 `docs/standards/playbook/docs/common/` +- 目标项目 subtree：`docs/standards/playbook/docs/cpp/` 与 `docs/standards/playbook/docs/common/` diff --git a/.agents/cpp/performance.md b/.agents/cpp/performance.md deleted file mode 100644 index b76f73c..0000000 --- a/.agents/cpp/performance.md +++ /dev/null @@ -1,31 +0,0 @@ -# 性能（Performance） - -本文件定义代理在做性能相关改动时的准则与检查项。 - -## 1. 目标与度量 - -- 明确性能目标：延迟、吞吐、内存、CPU、I/O 等。 -- 没有指标时不要盲目优化；先补充测量或基准。 - -## 2. 处理流程 - -1. 先定位瓶颈（profile/trace/log）。 -2. 再提出最小化改动方案。 -3. 最后用数据验证收益与副作用。 - -## 3. 优化准则 - -- 优先消除算法/结构性问题，再考虑微优化。 -- 避免引入复杂度换取小收益。 -- 性能优化不应牺牲可读性；必要时加注释说明权衡。 - -## 4. 常见风险 - -- 避免重复计算、无界缓存、隐式复制。 -- 注意热路径中的分配与 I/O。 -- 并发优化要考虑正确性与可测试性。 - -## 5. 验证 - -- 提供优化前后可复现的对比数据（基准、采样结果或压测报告）。 -- 若无测试体系，至少提供最小可运行的复现脚本/步骤。 diff --git a/.agents/cpp/testing.md b/.agents/cpp/testing.md deleted file mode 100644 index dfb912a..0000000 --- a/.agents/cpp/testing.md +++ /dev/null @@ -1,26 +0,0 @@ -# 测试（Testing） - -本文件定义代理在改动代码时的测试策略与要求。 - -## 1. 测试层级 - -- **单元测试**：验证函数/模块的独立行为。 -- **集成测试**：验证模块间交互与关键流程。 -- **回归测试**：防止已修复问题复发。 - -## 2. 何时补测试 - -- 新功能必须新增对应测试（若项目有测试体系）。 -- 修复 bug 必须先写/补回归用例（若项目有测试体系）。 -- 仅当改动纯文档/注释/格式时可不加测试。 - -## 3. 测试可维护性 - -- 一个用例只验证一个行为点。 -- 测试命名清晰，能从名字看出期望。 -- 避免依赖外部不稳定资源；必要时 mock/stub。 - -## 4. 运行与失败处理 - -- 若项目提供构建/冒烟命令（CMake），优先保证最小构建可通过。 -- 失败时优先定位改动相关原因，不修无关失败。 diff --git a/.agents/tsl/index.md b/.agents/tsl/index.md new file mode 100644 index 0000000..4f9c648 --- /dev/null +++ b/.agents/tsl/index.md @@ -0,0 +1,44 @@ +# TSL 代理规则集 + +本规则集定义 AI/自动化代理在处理 TSL 代码时必须遵守的核心约束。 + +## 范围与优先级 + +- 作为仓库级基线规则集使用；更靠近代码目录的规则更具体并可覆盖基线。 +- 当代理规则与 docs 冲突：安全/合规优先，其次保持仓库一致性。 + +## 代理工作原则（铁律） + +1. 先理解目标与上下文，再动手改代码 +2. 修改要小而清晰；避免无关重构 +3. 发现安全问题（明文密钥/鉴权漏洞）立即标注或修复 +4. 不引入新依赖或工具，除非明确要求 + +## TSL 核心约定（不可违反） + +- 文件结构：一文件一顶层声明；文件名 = 声明名；`.tsl` 仅 `function`，`.tsf` 可 `function/class/unit` +- 格式：4 空格缩进；关键字小写；多语句用 `begin/end` +- 命名：类型/函数/property `PascalCase`；变量/参数 `snake_case`；私有 `snake_case_`；常量 `kPascalCase` + +## 安全红线（不可触碰） + +- 不得在代码/日志/注释中写入明文密钥、密码、Token、API Key +- 修改鉴权/权限逻辑必须说明动机与风险 +- 不确定是否敏感时按敏感信息处理 + +## 权威来源 + +- 语法手册：`docs/standards/playbook/docs/tsl/syntax_book/index.md` +- 函数库：`docs/standards/playbook/docs/tsl/syntax_book/function/`（按需检索，禁止整份加载） +- 代码风格：`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/` diff --git a/AGENTS.md b/AGENTS.md index 91e675c..880a56d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,3 +17,32 @@ When working on C++ code, follow the generated ruleset entry: Human-facing standards snapshot (vendored): - `docs/standards/playbook/docs/` + + + +### 核心规则 + +- [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/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) - 工作模式参考 + + + + +请以 `.agents/` 下的规则为准： + +- 入口：`.agents/index.md` +- 语言规则：`.agents/cpp/index.md`、`.agents/tsl/index.md` + diff --git a/AGENT_RULES.md b/AGENT_RULES.md new file mode 100644 index 0000000..8bf9449 --- /dev/null +++ b/AGENT_RULES.md @@ -0,0 +1,221 @@ +# AGENT_RULES + +目的：为本仓库提供稳定的执行流程与行为规范。 + +## 优先级 + +1. 系统/开发者指令与安全约束 +2. 项目私有规则：`AGENT_RULES.local.md`（如存在） +3. 仓库规则：`.agents/` 与 `AGENTS.md` +4. 本文件 + +## 安全红线 + +- 不得在代码/日志/注释中写入明文密钥、密码、Token +- 修改鉴权/权限逻辑必须说明动机与风险 +- 不确定是否敏感时按敏感信息处理 +- 执行修改文件系统的命令前，必须解释目的和潜在影响 + +## 行为准则 + +### 项目适应 + +- **模仿项目风格**：优先分析周围代码和配置，遵循现有约定 +- **不假设可用性**：不假设库或框架可用，先验证再使用 +- **完整完成请求**：不遗漏用户要求的任何部分 + +### 技术态度 + +- **准确性优先**：技术准确性优先于迎合用户 +- **诚实纠正**：发现用户理解有误时，礼貌纠正 +- **先查后答**：不确定时先调查再回答 + +### 避免过度工程 + +- **只做要求的**：不主动添加未要求的功能或重构 +- **不过度抽象**：不为一次性操作创建工具函数 +- **不为未来设计**：不为假设的未来需求设计 + +## 沟通原则 + +- **简洁直接**：专业、直接、简洁，避免对话填充词 +- **拒绝时提供替代**：无法满足请求时，简洁说明并提供替代方案 +- **不给时间估算**：专注任务本身，让用户自己判断时间 +- **代码块标注语言**：输出代码时标注语言类型 +- **不使用 emoji**：除非用户明确要求 + +## 上下文加载（每次会话开始） + +**必读文档**（按顺序）： + +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 快速理解项目全貌，避免重复解释。 + +## 规划与执行分工 + +| 阶段 | 工具 | 产出 | 留痕 | +| ------------ | ---------------------- | ----------------- | -------------------- | +| 头脑风暴 | `$brainstorming` skill | 设计思路 | 无 | +| 生成计划 | `$writing-plans` skill | `docs/plans/*.md` | 无 | +| **执行计划** | **主循环** | 代码/配置变更 | **plan_progress.py** | + +> **重要**：第三方 skills 不记录操作状态，执行必须通过主循环完成。 + +## 主循环 + +**触发词**： + +| 触发词 | 模式 | 说明 | +| --------------------------------------- | ---------- | ---------------------- | +| `执行主循环`、`继续执行`、`下一个 Plan` | 常规模式 | 遇确认场景可询问用户 | +| `自动执行所有 Plan` | 无交互模式 | 不询问，按规则自动处理 | + +**Plan 状态**： + +| 状态 | 含义 | +| ----------- | ------------------------- | +| pending | 待执行 | +| in-progress | 执行中（崩溃恢复用） | +| done | 已完成 | +| blocked | 阻塞（需人工介入） | +| skipped | 跳过（Plan 不再需要执行） | + +> 说明：`skipped` 仅用于永久不再执行；如需恢复执行，需手动改回 `pending`。 + +**环境阻塞格式**：`blocked: env:<环境>:` + +- 示例：`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. **结束**：主循环终止 + +## 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 必须包含验证步骤 + +## 执行约束 + +### 代码修改 + +- **必须先读文件再修改**：不读文件就提议修改是禁止的 +- **必须运行测试验证**：相关测试必须通过 +- **遵循换行规则**：遵循 `.gitattributes` 规则 +- **命名一致性**：遵循项目现有的命名风格 +- **最小改动原则**：只修改必要的部分，不顺手重构 + +### 决策记录 + +- **重要决策**：记录到 `memory-bank/decisions.md`（ADR 格式） +- **待确认事项**：在回复中列出并等待确认 +- **进度留痕**：通过 `docs/standards/playbook/scripts/plan_progress.py` 维护 `memory-bank/progress.md` 的 Plan 状态块（唯一权威） + +### Git 操作 + +- **不使用 --amend**：除非用户明确要求，总是创建新提交 +- **不使用 --force**：特别是推送到 main/master，如用户要求必须警告风险 +- **不跳过 hooks**：不使用 `--no-verify` + +## 工具使用 + +- **并行执行**：独立的工具调用尽可能并行执行 +- **遵循 schema**：严格遵循工具参数定义 +- **避免循环**：避免重复调用同一工具获取相同信息 +- **优先专用工具**：文件操作用 Read/Edit/Write，搜索用 Grep/Glob + +## 需要确认的场景 + +**常规模式**（可交互）： + +- 需求不明确或存在多种可行方案 +- 需要行为/兼容性取舍 +- 风险或约束冲突 +- **架构变更**：影响多个模块的修改 +- **性能权衡**：需要在性能和可维护性之间选择 +- **兼容性问题**：可能破坏现有用户代码 + +**无交互模式**（自动处理）： + +| 场景 | 处理方式 | +| -------------------------- | ---------------------------------- | +| 安全红线 | 立即停止，不继续后续 Plan | +| 架构变更/兼容性/破坏性修改 | 标记 blocked，跳到下一个 Plan | +| 多种可行方案 | 选择最保守方案，记录选择理由到报告 | +| 歧义/风险/决策点 | 记录到报告，继续执行 | + +**可以不确认**（两种模式通用）： + +- 明显的 bug 修复 +- 符合现有模式的小改动 +- 测试用例补充 + +## 验证清单 + +每个 Plan 完成后，必须验证： + +- [ ] 代码修改符合 `.agents/` 下的规则（如有） +- [ ] 相关测试通过（如有测试且未被豁免） +- [ ] 换行符正确 +- [ ] 无语法错误 +- [ ] 已通过 `plan_progress.py` 记录 Plan 状态 + +--- + +**最后更新**：2026-02-02 + diff --git a/docs/prompts/README.md b/docs/prompts/README.md new file mode 100644 index 0000000..1342a63 --- /dev/null +++ b/docs/prompts/README.md @@ -0,0 +1,48 @@ +# 提示词库 + +本目录包含 AI 代理的工作流程参考模板。 + +## 目录结构 + +```text +prompts/ +├── README.md # 本文件 +├── system/ +│ └── agent-behavior.md # 工作模式参考 +├── coding/ +│ ├── clarify.md # 需求澄清模板 +│ └── review.md # 复盘总结模板 +└── meta/ + └── prompt-generator.md # 元提示词生成器 +``` + +## 使用方式 + +| 模板 | 触发场景 | +| ----------------------- | ------------------------------ | +| **agent-behavior.md** | 切换工作模式（探索/开发/调试） | +| **clarify.md** | 需求不明确时澄清 | +| **review.md** | Plan 完成后复盘总结 | +| **prompt-generator.md** | 创建新的专用提示词 | + +## 工作流程 + +``` +需求不清 → clarify.md + ↓ +头脑风暴 → $brainstorming skill + ↓ +生成计划 → $writing-plans skill → docs/plans/*.md + ↓ +执行计划 → AGENT_RULES 主循环（留痕） + ↓ +完成复盘 → review.md + ↓ +沉淀提示词 → prompt-generator.md（可选） +``` + +> **核心规则在 `AGENT_RULES.md`**，第三方 skills 负责规划，主循环负责执行和留痕。 + +--- + +**最后更新**：2026-02-02 diff --git a/docs/prompts/coding/clarify.md b/docs/prompts/coding/clarify.md new file mode 100644 index 0000000..7e35ee0 --- /dev/null +++ b/docs/prompts/coding/clarify.md @@ -0,0 +1,52 @@ +# 需求澄清模板 + + + +## 何时使用 + +- 需求描述不明确 +- 存在多种理解方式 +- 缺少关键信息 + +--- + +## 澄清步骤 + +### 1. 复述需求 + +```text +我理解你的需求是：[用自己的话复述] +``` + +### 2. 识别歧义 + +- 歧义 1：[描述不明确的地方] +- 歧义 2：[可能有多种理解的地方] + +### 3. 提出问题 + +> 只问阻塞问题，最多 1–2 个；优先给出选项让用户选择。 + +- 这个功能是否包括 [场景 A]？ +- 当 [条件 X] 时，应该 [行为 Y] 还是 [行为 Z]？ + +### 4. 提供选项 + +**选项 A**：[方案描述] + +- 优点：... +- 缺点：... + +**选项 B**：[方案描述] + +- 优点：... +- 缺点：... + +**推荐**：[推荐哪个，为什么] + +--- + +**最后更新**：2026-02-02 diff --git a/docs/prompts/coding/review.md b/docs/prompts/coding/review.md new file mode 100644 index 0000000..d48cb31 --- /dev/null +++ b/docs/prompts/coding/review.md @@ -0,0 +1,66 @@ +# 复盘模板 + + + +## 何时使用 + +- 一批 Plan 执行完毕后 +- 阶段性工作告一段落 +- 遇到重大阻塞需要总结 + +--- + +## 复盘格式 + +```markdown +# 复盘: [日期/阶段名称] + +## 完成情况 + +### 已完成 +- [x] Plan 1: 简述 +- [x] Plan 2: 简述 + +### 阻塞 +- [ ] Plan 3: 阻塞原因 + +### 跳过 +- [ ] Plan 4: 跳过原因 + +## 关键发现 + +### 做得好的 +- 发现1 +- 发现2 + +### 待改进 +- 问题1 → 建议改进方式 +- 问题2 → 建议改进方式 + +## 决策记录 + +| 决策 | 理由 | 影响 | +|------|------|------| +| 决策1 | 为什么 | 影响范围 | + +## 下一步 + +- [ ] 待处理事项1 +- [ ] 待处理事项2 +``` + +--- + +## 复盘原则 + +- **客观记录**：如实记录完成/阻塞/跳过 +- **提取经验**：总结做得好的和待改进的 +- **决策留痕**：重要决策记录到 decisions.md +- **明确下一步**：列出后续待处理事项 + +--- + +**最后更新**：2026-02-02 diff --git a/docs/prompts/meta/prompt-generator.md b/docs/prompts/meta/prompt-generator.md new file mode 100644 index 0000000..5470fd0 --- /dev/null +++ b/docs/prompts/meta/prompt-generator.md @@ -0,0 +1,126 @@ +# 提示词生成器（元提示词） + + + +## 何时使用 + +- 需要为新场景创建专用提示词 +- 现有提示词不满足特定需求 +- 需要批量生成同类提示词 + +--- + +## 生成流程（α循环） + +### 1. 分析场景 + +```markdown +**场景名称**：[名称] +**目标用户**：[AI/人类/两者] +**触发条件**：[何时使用这个提示词] +**预期输出**：[使用后应该产出什么] +``` + +### 2. 提取约束 + +```markdown +**必须做**： +- 约束1 +- 约束2 + +**禁止做**： +- 禁止1 +- 禁止2 + +**边界条件**： +- 边界1 +- 边界2 +``` + +### 3. 生成草稿 + +```markdown +# [提示词标题] + + + +## 何时使用 + +- 场景1 +- 场景2 + +## [核心内容] + +[根据场景填充] + +## [约束/原则] + +- 约束1 +- 约束2 + +--- + +**最后更新**：2026-02-02 +``` + +--- + +## 优化流程（Ω循环） + +### 1. 评估维度 + +| 维度 | 问题 | +| ---------- | ---------------------- | +| **清晰度** | 指令是否明确无歧义？ | +| **完整度** | 是否覆盖所有必要场景？ | +| **简洁度** | 是否有冗余内容可删除？ | +| **可操作** | AI 能否直接执行？ | + +### 2. 迭代优化 + +``` +草稿 → 评估 → 修改 → 再评估 → ... → 定稿 +``` + +### 3. 验证测试 + +- 用实际场景测试提示词效果 +- 收集反馈，持续迭代 + +--- + +## 提示词模板库 + +### 标准结构 + +```markdown +# [标题] + + + +## 何时使用 +## [核心内容] +## [约束/原则] + +--- + +**最后更新**：2026-02-02 +``` + +### 命名规范 + +- 文件名：`[动词]-[对象].template.md` +- 示例：`clarify-requirement.template.md` + +--- + +**最后更新**：2026-02-02 diff --git a/docs/prompts/system/agent-behavior.md b/docs/prompts/system/agent-behavior.md new file mode 100644 index 0000000..8ef0c84 --- /dev/null +++ b/docs/prompts/system/agent-behavior.md @@ -0,0 +1,62 @@ +# 工作模式参考 + + + +## 模式 1: 探索模式（Explore） + +**目的**：理解代码库、分析问题、收集信息 + +**行为**： + +- 使用搜索工具探索代码 +- 输出分析报告和发现 +- 不修改任何代码 + +**适用场景**： + +- 理解某个模块的实现 +- 分析 bug 的根本原因 +- 评估功能实现的可行性 + +--- + +## 模式 2: 开发模式（Develop） + +**目的**：实现功能、修复 bug、重构代码 + +**行为**： + +- 先读取相关文件，理解现有逻辑 +- 进行精确修改 +- 修改后运行测试验证 + +**适用场景**： + +- 实现新功能 +- 修复已知 bug +- 优化性能 + +--- + +## 模式 3: 调试模式（Debug） + +**目的**：诊断问题、对比差异、验证行为 + +**行为**： + +- 收集相关日志和输出 +- 分析差异原因 +- 修复后重新验证 + +**适用场景**： + +- 测试失败 +- 输出不符合预期 +- 性能问题诊断 + +--- + +**最后更新**：2026-02-02 diff --git a/memory-bank/architecture.md b/memory-bank/architecture.md new file mode 100644 index 0000000..c65e2f5 --- /dev/null +++ b/memory-bank/architecture.md @@ -0,0 +1,44 @@ +# 架构设计 + + + +## 整体架构 + + + +```txt +{{ARCHITECTURE_DIAGRAM}} +``` + +## 核心模块 + + + +### {{MODULE_1}} + +**职责**：{{MODULE_1_DESC}} + +## 关键约束 + + + +- {{CONSTRAINT_1}} + +## 扩展点 + + + +### {{EXTENSION_1}} + +**步骤**： + +1. {{STEP_1}} + +--- + +**最后更新**：2026-02-02 diff --git a/memory-bank/decisions.md b/memory-bank/decisions.md new file mode 100644 index 0000000..598101e --- /dev/null +++ b/memory-bank/decisions.md @@ -0,0 +1,33 @@ +# 架构决策记录 + + + +## ADR 模板 + +```markdown +## ADR-XXX: 决策标题 + +**日期**: YYYY-MM-DD +**状态**: 已采纳 / 已废弃 / 待讨论 + +### 决策 + +简要描述决策内容 + +### 理由 + +为什么做出这个决策 + +### 影响 + +对项目的影响 +``` + +--- + +**最后更新**：2026-02-02 diff --git a/memory-bank/progress.md b/memory-bank/progress.md new file mode 100644 index 0000000..559d39b --- /dev/null +++ b/memory-bank/progress.md @@ -0,0 +1,4 @@ +# Plan 状态 + + + diff --git a/memory-bank/project-brief.md b/memory-bank/project-brief.md new file mode 100644 index 0000000..edf39c6 --- /dev/null +++ b/memory-bank/project-brief.md @@ -0,0 +1,48 @@ +# tsl-devkit 项目简介 + + + +## 项目定位 + + + +**核心目标**：{{PROJECT_GOAL}} + +**一句话描述**：{{PROJECT_DESCRIPTION}} + +## 项目边界 + + + +### 做什么 + +- {{DO_1}} + +### 不做什么 + + + +- {{DONT_1}} + +### 约束条件 + + + +- {{CONSTRAINT_1}} + +## 核心概念 + + + +## 参考资料 + + + +--- + +**最后更新**：2026-02-02 diff --git a/memory-bank/tech-stack.md b/memory-bank/tech-stack.md new file mode 100644 index 0000000..9e90979 --- /dev/null +++ b/memory-bank/tech-stack.md @@ -0,0 +1,64 @@ +# 技术栈与工具链 + + + +## 核心技术 + + + +**主语言**：cpp + +**文件类型**：{{FILE_TYPES}} + +## 项目结构 + + + +```text +tsl-devkit/ +├── {{DIR_1}}/ # {{DIR_1_DESC}} +└── memory-bank/ # 项目上下文 +``` + +## 开发环境 + + + +**必需工具**： + +- {{TOOL_1}} + +**运行测试**： + +```bash +{{TEST_CMD}} +``` + +## 依赖管理 + + + +**外部依赖**： + +- {{EXTERNAL_DEP_1}} + +## 测试策略 + + + +**测试类型**： + +- {{TEST_TYPE_1}} + +**验证标准**： + +- {{PASS_CONDITION_1}} + +--- + +**最后更新**：2026-02-02 diff --git a/playbook.toml b/playbook.toml new file mode 100644 index 0000000..8e91d7a --- /dev/null +++ b/playbook.toml @@ -0,0 +1,17 @@ +[playbook] +project_root = "." + +[sync_rules] +force = true + +[sync_memory_bank] +project_name = "tsl-devkit" +force = false + +[sync_prompts] +force = true + +[sync_standards] +langs = ["cpp", "tsl"] +gitattr_mode = "append" +no_backup = true