diff --git a/AGENTS.md b/AGENTS.md index 8a5aff3..cc9fd35 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -60,7 +60,7 @@ Do not load the whole directory. Load only the needed fragments. ### Scenario 1: write a simple TSL function -``` +```text 1. Auto read .agents/tsl/index.md (47 lines) 2. Trigger $tsl-guide, load SKILL.md (192 lines) 3. Generate code @@ -70,7 +70,7 @@ Token cost: ~6,000 tokens ### Scenario 2: write a TSL class -``` +```text 1. Auto read .agents/tsl/index.md (47 lines) 2. Trigger $tsl-guide, load SKILL.md + references/advanced.md 3. Generate code @@ -80,7 +80,7 @@ Token cost: ~10,000 tokens ### Scenario 3: find a TSL function library entry -``` +```text 1. Auto read .agents/tsl/index.md (47 lines) 2. Trigger $tsl-guide, load references/functions_index.md 3. Use rg to locate the function fragment @@ -93,11 +93,11 @@ Token cost: ~8,000 tokens ## Performance metrics -| Metric | Before | Now | Improvement | -| ----------------- | -------- | ------- | ----------- | -| .agents size | ~500 lines | 168 lines | -66% | -| Persistent tokens | ~12,500 | ~4,200 | -66% | -| Avg scenario tokens | ~12,500 | ~10,500 | -16% | +| Metric | Before | Now | Improvement | +| ------------------- | ---------- | --------- | ----------- | +| .agents size | ~500 lines | 168 lines | -66% | +| Persistent tokens | ~12,500 | ~4,200 | -66% | +| Avg scenario tokens | ~12,500 | ~10,500 | -16% | --- @@ -131,14 +131,14 @@ Do: Q: Why is .agents/ so small? A: Because it is loaded every conversation. Keeping it under 50 lines saves - about 71% of persistent token usage. +about 71% of persistent token usage. Q: Why does TSL need a dedicated tsl-guide skill? A: TSL is not pre-trained. The agent needs from-scratch teaching. Q: What if my project has custom conventions? A: Fork playbook into the project (git subtree) and modify the project's - `.agents/`. +`.agents/`. --- diff --git a/README.md b/README.md index 43d830e..c921ca0 100644 --- a/README.md +++ b/README.md @@ -41,6 +41,39 @@ Playbook:TSL(`.tsl`/`.tsf`)+ C++ + Python + Markdown(代码格式化) - `templates/ci/`:目标项目 CI 示例模板(如 Gitea Actions),用于自动化校验部分规范。 +## templates/(项目架构模板) + +`templates/` 目录除了语言配置模板外,还包含 AI 代理工作环境的项目架构模板: + +- `templates/memory-bank/`:项目上下文文档模板(project-brief、tech-stack、architecture、progress、decisions、implementation-plan) +- `templates/prompts/`:工作流程模板(agent-behavior、clarify、verify) +- `templates/AGENTS.template.md`:路由中心模板(项目主入口) +- `templates/AGENT_RULES.template.md`:执行流程模板 + +### 快速部署 + +使用 `sync_templates` 脚本一键部署项目架构: + +```bash +# Linux/macOS +sh scripts/sync_templates.sh /path/to/project + +# PowerShell +.\scripts\sync_templates.ps1 -ProjectRoot C:\path\to\project + +# Windows CMD +scripts\sync_templates.bat C:\path\to\project +``` + +**部署行为**: + +- **新项目**:创建完整的 `AGENTS.md`、`AGENT_RULES.md`、`memory-bank/`、`docs/prompts/`、`TODO.md`、`CONFIRM.md` +- **已有 AGENTS.md**:追加路由链接(使用 `` 标记) +- **--full 参数**:追加完整框架(规则优先级 + 新会话开始时)到已有 AGENTS.md +- **其他文件**:如果已存在则跳过(使用 `--force` 覆盖) + +详见:`templates/README.md` + ## rulesets/(规则集模板库 - 三层架构) > **重要说明**:playbook 仓库中的 `rulesets/` 是**规则集模板库**,不是 playbook 项目自身的代理规则。 @@ -187,6 +220,7 @@ git commit -m ":package: deps(playbook): add tsl standards" > 会自动生成最小版;已存在则不会覆盖。 3. **验收**(任意满足其一即可): + - 目录存在:`.agents/tsl/` - 规则入口可读:`.agents/tsl/index.md` - (可选)C++ 规则入口可读:`.agents/cpp/index.md` diff --git a/SKILLS.md b/SKILLS.md index 40200ce..2b3e83b 100644 --- a/SKILLS.md +++ b/SKILLS.md @@ -156,6 +156,7 @@ sh docs/standards/playbook/scripts/install_codex_skills.sh ### 通用工作流 Skills - **`testing-workflow`**:跨语言测试策略 + - 适用:TSL / Python / C++ - 覆盖:单元测试 / 集成测试 / 回归测试 - 108 行 diff --git a/codex/skills/bulk-refactor-workflow/SKILL.md b/codex/skills/bulk-refactor-workflow/SKILL.md index fc47f9b..0f20c64 100644 --- a/codex/skills/bulk-refactor-workflow/SKILL.md +++ b/codex/skills/bulk-refactor-workflow/SKILL.md @@ -24,19 +24,23 @@ description: ## Procedure(default) 1. **Baseline** + - 确保工作区干净:`git status --porcelain` - 跑一个基线验证(至少 build 或核心测试子集),避免“本来就坏” 2. **Enumerate** + - 先搜索再改:用 `rg`/`git grep` 列出全部命中 - 分类命中:真实调用 vs 注释/文档/样例;避免误改 3. **Apply Mechanical Change** + - 优先使用确定性的机械变换(脚本/结构化编辑)而非手工逐个改 - 每轮改动后立即做小验证(编译/单测子集) - 复杂迁移优先“两阶段”:先兼容旧接口(deprecated),再清理旧接口 4. **Format & Lint(按项目约定)** + - 仅在确认“会破坏 diff 可读性”前提下分批格式化(避免把重构和格式揉在一起) 5. **Verify & Report** diff --git a/codex/skills/code-review-workflow/SKILL.md b/codex/skills/code-review-workflow/SKILL.md index 88f9cd4..0c0a67e 100644 --- a/codex/skills/code-review-workflow/SKILL.md +++ b/codex/skills/code-review-workflow/SKILL.md @@ -23,22 +23,27 @@ description: ## Procedure 1. **Triage** + - Identify touched areas, public APIs, behavior changes, data/auth paths - Classify risk (blast radius, rollback difficulty) 2. **Correctness** + - Invariants, edge cases, error handling, null/empty, concurrency - Backward compatibility (inputs/outputs, wire formats, config) 3. **Security** + - AuthZ/AuthN boundaries, least privilege - Input validation, injection surfaces, secrets/log redaction 4. **Maintainability** + - Naming/structure/style aligned with Playbook docs - Complexity hotspots, duplication, clarity of intent 5. **Performance** + - Hot paths, algorithmic complexity, allocations/IO, N+1 patterns 6. **Tests & Verification** diff --git a/codex/skills/commit-message/SKILL.md b/codex/skills/commit-message/SKILL.md index 149b050..ceb9a28 100644 --- a/codex/skills/commit-message/SKILL.md +++ b/codex/skills/commit-message/SKILL.md @@ -25,22 +25,27 @@ diff)生成 1–3 条提交信息建议:`:emoji: type(scope): subject`(可 ## Procedure(default) 1. **收集 staged 概览(尽量小上下文)** + - `git diff --cached --name-status` - `git diff --cached --stat` - 必要时只看关键文件:`git diff --cached -- ` 2. **读取并遵循权威规范** + - 优先读取就近的 `commit_message.md`(见上方路径),以其中的 type/emoji/格式为准。 3. **生成 1 条主建议 + 2 条备选** + - 格式固定:`:emoji: type(scope): subject`(scope 可省略)。 - subject 用一句话描述“做了什么”,避免含糊词;尽量 ≤ 72 字符,不加句号。 4. **判断是否建议拆分提交** + - 当 staged 同时包含多个不相关模块/目的时:建议拆分,并给出拆分方式(按目录/功能点/风险)。 5. **可选:补充 body/footer(如需要)** + - body:说明 why/impact/verify(按规范建议换行)。 - footer:任务号或 `BREAKING CHANGE:`(若有)。 diff --git a/codex/skills/create-plan/SKILL.md b/codex/skills/create-plan/SKILL.md index 2a22d3d..435fcb1 100644 --- a/codex/skills/create-plan/SKILL.md +++ b/codex/skills/create-plan/SKILL.md @@ -20,6 +20,7 @@ Throughout the entire workflow, operate in read-only mode. Do not write or update files. 1. **Scan context quickly** + - Read `README.md` and any obvious docs (`docs/`, `CONTRIBUTING.md`, `ARCHITECTURE.md`). - Skim relevant files (the ones most likely touched). @@ -27,12 +28,14 @@ update files. shape). 2. **Ask follow-ups only if blocking** + - Ask **at most 1–2 questions**. - Only ask if you cannot responsibly plan without the answer; prefer multiple-choice. - If unsure but not blocked, make a reasonable assumption and proceed. 3. **Create a plan using the template below** + - Start with **1 short paragraph** describing the intent and approach. - Clearly call out what is **in scope** and what is **not in scope** in short. diff --git a/codex/skills/style-cleanup/SKILL.md b/codex/skills/style-cleanup/SKILL.md index 727c948..64b0a8c 100644 --- a/codex/skills/style-cleanup/SKILL.md +++ b/codex/skills/style-cleanup/SKILL.md @@ -23,6 +23,7 @@ description: ## Procedure(default) 1. **Baseline** + - 记录当前状态:`git status --porcelain` - 明确范围(默认只处理变更文件): - staged:`git diff --name-only --cached` @@ -30,6 +31,7 @@ description: - untracked:`git ls-files -o --exclude-standard` 2. **Detect Toolchain(prefer repo truth)** + - 优先用仓库既有入口脚本 / 配置: - JS/TS:`package.json` scripts(`format`/`lint`/`lint:fix`)、prettier/biome/eslint 配置 @@ -41,6 +43,7 @@ description: - 禁止默认“引入新 formatter/linter 配置”;缺配置时只做最小手工调整,并先确认是否允许落地配置文件。 3. **Apply(format first, then lint)** + - 先 formatter(会改文件),再 lint(检查),再 lint --fix(如有),最后再跑一次 check 确认干净。 - 默认只处理目标文件集合;避免全仓库 reformat(除非用户明确要求)。 @@ -52,6 +55,7 @@ description: `npx prettier -w `(以项目脚本为准) 4. **Guardrails** + - 只做风格与格式:不改变行为、不改 public API、不做重构。 - 如格式化导致 diff 暴涨(文件数/行数过大):先停下,给出原因与两种方案让用户选: 1. 仅格式化本次改动文件(推荐默认) diff --git a/codex/skills/tsl-guide/references/functions_index.md b/codex/skills/tsl-guide/references/functions_index.md index 9ec0275..1573ed1 100644 --- a/codex/skills/tsl-guide/references/functions_index.md +++ b/codex/skills/tsl-guide/references/functions_index.md @@ -1,8 +1,7 @@ # TSL 函数库分类索引 > **说明**:本文档是 `$tsl-guide` 的子文档,仅提供分类索引与检索策略。 -> **权威入口**:`docs/tsl/syntax_book/function/tsl/index.md` -> **注意**:函数库已拆分为 `docs/tsl/syntax_book/function/` 多文件,禁止整目录加载。 +> **权威入口**:`docs/tsl/syntax_book/function/tsl/index.md` > **注意**:函数库已拆分为 `docs/tsl/syntax_book/function/` 多文件,禁止整目录加载。 ## 使用方法 diff --git a/docs/tsl/syntax_book/function/financial/index.md b/docs/tsl/syntax_book/function/financial/index.md index 41a5f08..28d0b02 100644 --- a/docs/tsl/syntax_book/function/financial/index.md +++ b/docs/tsl/syntax_book/function/financial/index.md @@ -31,10 +31,12 @@ ### 财务与基本面 - **[财务分析](./financial_analysis.md)** (46,778行) ⚠️ **最大文件** + - 资产负债表、利润表、现金流量表 - 财务比率、财务指标、财务预测 - **[基本面](./fundamentals.md)** (6,139行) + - 公司基本信息、行业分类、股东结构 - 分红、配股、增发等公司行为 @@ -49,10 +51,12 @@ ### 量化分析 - **[金融工程](./financial_engineering.md)** (6,564行) + - 风险模型、因子模型、组合优化 - 回测框架、绩效归因 - **[组合评价](./portfolio_evaluation.md)** (3,656行) + - 夏普比率、最大回撤、收益波动 - 组合绩效评估、风险调整收益 diff --git a/docs/tsl/syntax_book/function/tsl/index.md b/docs/tsl/syntax_book/function/tsl/index.md index a17bc4d..b220abf 100644 --- a/docs/tsl/syntax_book/function/tsl/index.md +++ b/docs/tsl/syntax_book/function/tsl/index.md @@ -16,10 +16,12 @@ TSL函数包含数学、系统、基础、图形等通用函数,适用于各 ### 系统与平台 - **[系统相关函数](./system.md)** (1,647行) + - 系统信息、环境变量、进程控制 - 内存管理、性能监控 - **[平台函数](./platform.md)** (553行) + - 平台特定功能、系统调用 - **[客户端函数](./client.md)** (409行) @@ -28,6 +30,7 @@ TSL函数包含数学、系统、基础、图形等通用函数,适用于各 ### 基础功能 - **[基础函数](./base.md)** (10,660行) + - 字符串处理、数组操作、日期时间 - 类型转换、条件判断、数据结构 - 文件操作、流程控制 @@ -38,6 +41,7 @@ TSL函数包含数学、系统、基础、图形等通用函数,适用于各 ### 资源与交互 - **[资源访问函数](./resource.md)** (4,897行) + - 文件读写、数据库访问、网络通信 - 配置文件、资源管理 @@ -47,6 +51,7 @@ TSL函数包含数学、系统、基础、图形等通用函数,适用于各 ### 工具函数 - **[压缩和解压函数](./compression.md)** (108行) + - 数据压缩、解压缩、归档 - **[信息摘要及编码](./digest_encoding.md)** (172行)