From 4ac86729d72d134e108dd2450b6067221c30be0c Mon Sep 17 00:00:00 2001 From: csh Date: Mon, 18 May 2026 09:58:13 +0800 Subject: [PATCH] :memo: docs: simplify README + platform-agnostic tools + auto-create local rules - Simplify docs/ section to grouped summary with pointer to docs/index.md - Remove outdated performance metrics table - Use cross-platform path examples throughout - Make AGENT_RULES tool usage section platform-agnostic - Auto-create AGENT_RULES.local.md on sync_rules (empty template) Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 50 ++++++++----------------------- scripts/playbook.py | 17 +++++++++++ templates/AGENT_RULES.template.md | 2 +- 3 files changed, 30 insertions(+), 39 deletions(-) diff --git a/README.md b/README.md index 06e9ba5a..e266a5d5 100644 --- a/README.md +++ b/README.md @@ -24,36 +24,17 @@ Playbook：工程规范与代理规则合集，当前覆盖： `docs/` 目录是给开发者阅读的工程规范，约束代码写法、命名与提交信息。 -- `docs/index.md`：文档导航（跨语言 common / TSL / C++ / Python / TypeScript / Markdown）。 -- `docs/common/commit_message.md`：提交信息与版本号规范（type/scope/subject/body/footer、可选 Emoji 图例、SemVer）。 -- `docs/tsl/index.md`：TSL canonical 入口（语法 / 金融 / 模块 / 函数检索四层）。 -- `docs/tsl/code_style.md`：TSL 代码结构、格式、`begin/end` - 代码块、注释与通用最佳实践。 -- `docs/tsl/naming.md`：TSL 命名规范（顶层声明、文件同名规则、变量/成员/property、常量、集合命名等）。 -- `docs/tsl/syntax/index.md`：TSL 语法手册。 -- `docs/tsl/finance/index.md`：TSL 金融业务层入口（指标、选股、回测与业务流程问题）。 -- `docs/tsl/modules/index.md`：TSL 模块层入口（pyTSL、微信消息、Python 互操作、回测框架）。 -- `docs/tsl/reference/index.md`：TSL 函数检索入口（模块目录位于 `docs/tsl/reference/catalog/`）。 -- `docs/tsl/toolchain.md`：TSL 工具链与验证命令模板。 -- `docs/cpp/code_style.md`：C++ 代码风格（C++23/Modules）。 -- `docs/cpp/naming.md`：C++ 命名规范（Google 基线）。 -- `docs/cpp/toolchain.md`：C++ 工具链与验证命令模板。 -- `docs/cpp/dependencies_conan.md`：C++ Conan 依赖管理建议。 -- `docs/cpp/clangd.md`：clangd 补全配置建议（`.clangd`）。 -- `docs/python/style_guide.md`：Python 代码风格（Google 基线）。 -- `docs/python/tooling.md`：Python 工具链（black/isort/flake8/pylint/mypy/pytest/pre-commit）。 -- `docs/python/configuration.md`：Python 配置清单（落地时从 `templates/python/` - 复制到项目根目录）。 -- `docs/markdown/index.md`：Markdown 代码块与行内代码格式（仅代码格式化）。 -- `docs/typescript/code_style.md`：TypeScript 代码风格（Google 基线）。 -- `docs/typescript/naming.md`：TypeScript 命名规范。 -- `docs/typescript/toolchain.md`：TypeScript 工具链（typescript/prettier/eslint/vitest）。 -- `docs/typescript/configuration.md`：TypeScript 配置清单（tsconfig/eslint/prettier）。 -- `templates/cpp/`：C++ 落地模板（`.clang-format`、`conanfile.txt`、`CMakeUserPresets.json`、`CMakeLists.txt`）。 -- `templates/python/`：Python 落地模板（`pyproject.toml` - 工具配置、`.flake8`、`.pylintrc`、`.pre-commit-config.yaml`、`.editorconfig`、`.vscode/settings.json`）。 -- `templates/ci/`：目标项目 CI 示例模板（如 Gitea - Actions），用于自动化校验部分规范。 +- `docs/index.md`：文档导航入口 +- `docs/common/`：跨语言规范（提交信息、版本号） +- `docs/tsl/`：TSL 规范（语法手册、金融业务、模块、函数检索、代码风格、命名、工具链） +- `docs/cpp/`：C++ 规范（C++23/Modules、Google 基线、Conan、clangd） +- `docs/python/`：Python 规范（Google 基线、black/isort/flake8/pylint/mypy/pytest） +- `docs/typescript/`：TypeScript 规范（Google 基线、prettier/eslint/vitest） +- `docs/markdown/`：Markdown 规范（仅代码格式化） + +落地模板：`templates/cpp/`、`templates/python/`、`templates/ci/`。 + +详见 `docs/index.md`。 ## templates/（项目架构模板） @@ -144,13 +125,6 @@ Layer 3: docs/ (权威静态文档) 更多说明：`rulesets/index.md` -### 性能指标 - -| 指标 | 优化前 | 优化后 | 改善 | -| ------------- | ------- | ------ | ---- | -| .agents 规模 | ~500 行 | 167 行 | -67% | -| 持久化 tokens | ~12,500 | ~4,200 | -66% | - ### 维护原则 **.agents/（Layer 1）修改规则**： @@ -199,7 +173,7 @@ TSL 相关问题直接查阅 `rulesets/tsl/index.md` 与 `docs/tsl/`。 - `project_root`：目标项目根目录。 - `deploy_root`：相对于 `project_root` 的项目内目标目录。 -- 外部 clone 出来的 Playbook 路径（如 `/opt/playbook` 或 `C:/tools/playbook`）：只是执行部署脚本的位置，不是部署目标。 +- 外部 clone 出来的 Playbook 路径（如 `/opt/playbook`）：只是执行部署脚本的位置，不是部署目标。 以 TSL 为例，Playbook 在项目内的默认部署根是 `docs/standards/playbook`；如果你把 `deploy_root` 改成 `custom/playbook`，则部署结果会落到 `/custom/playbook`，文档和脚本入口也会跟着变成 `custom/playbook/docs/...`、`custom/playbook/scripts/...`。 diff --git a/scripts/playbook.py b/scripts/playbook.py index 7df5727a..c6b406a0 100644 --- a/scripts/playbook.py +++ b/scripts/playbook.py @@ -833,6 +833,23 @@ def sync_rules_action(config: dict, context: dict) -> int: text = replace_placeholders(text, project_name, date_value, playbook_scripts) rules_dst.write_text(text.rstrip("\n") + "\n", encoding="utf-8") log("Synced: AGENT_RULES.md") + + local_rules = project_root / "AGENT_RULES.local.md" + if not local_rules.exists(): + local_rules.write_text( + "# AGENT_RULES.local\n" + "\n" + "项目私有规则（优先级高于 AGENT_RULES.md）。\n" + "\n" + "在此记录：\n" + "\n" + "- 项目特有的注意事项与常见陷阱\n" + "- 同一错误发生 2 次以上时的修正规则\n" + "- 团队约定的额外约束\n", + encoding="utf-8", + ) + log("Created: AGENT_RULES.local.md") + return 0 diff --git a/templates/AGENT_RULES.template.md b/templates/AGENT_RULES.template.md index 2bededc9..02f40208 100644 --- a/templates/AGENT_RULES.template.md +++ b/templates/AGENT_RULES.template.md @@ -192,7 +192,7 @@ - **并行执行**：独立的工具调用尽可能并行执行 - **遵循 schema**：严格遵循工具参数定义 - **避免循环**：避免重复调用同一工具获取相同信息 -- **优先专用工具**：文件操作用 Read/Edit/Write，搜索用 Grep/Glob +- **优先专用工具**：文件操作用专用文件工具（非 cat/sed），搜索用专用搜索工具（非 grep/find） ## Context 管理