📝 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) <noreply@anthropic.com>
This commit is contained in:
@@ -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`,则部署结果会落到 `<project_root>/custom/playbook`,文档和脚本入口也会跟着变成 `custom/playbook/docs/...`、`custom/playbook/scripts/...`。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user